fix: enforce production transport policy
Every PostgreSQL connection this repository opened was plaintext, in every environment: no connection site set `ssl` at all, so credentials, session tokens, and row data crossed the network in the clear and nothing in configuration, startup, or `pnpm doctor` said so. The public identity URL boundary was also looser than it appeared. `core/src/database/transport.ts` is now the one typed policy. It has exactly two modes: `verify-full` (TLS required, certificate chain verified, and server identity verified against the configured host — the production default) and `disable` (the development/test default, refused outright in production). There is deliberately no encryption-only `require` mode, no chain-only `verify-ca`, and no `rejectUnauthorized: false` escape hatch anywhere in the configuration surface; every loose or aliased spelling is rejected in both environments, so a typo never quietly becomes a weaker mode. Production has no plaintext exception at all, not even for a loopback database — a connection string cannot prove the database is process-local. Verification is certificate *and* hostname. The policy supplies an explicit `checkServerIdentity` pinned to the host parsed from DATABASE_URL, because the pinned driver sets TLS `servername` only for non-IP hosts and Node performs no identity check when it is unset — so `rejectUnauthorized: true` alone accepts a certificate from any host the trusted CA ever signed when connecting by IP. Both halves are proven against a real TLS-enabled PostgreSQL, including that the same connection without the pinned callback succeeds. Every CA, certificate, and key is generated at test runtime and deleted afterwards. A DATABASE_URL may no longer carry its own TLS parameters. The pinned driver merges parsed connection-string values over explicitly passed options, so a `?sslmode=disable` in the URL would silently replace the policy's verified `ssl` object; that now fails with a stable code, reported by both `pnpm doctor` and the migration CLIs rather than as "failed unexpectedly". One shared environment reader keeps `process.env` out of Core's reusable constructors, and every executable that opens a connection resolves the policy identically: the API (validated before any pool, Better Auth instance, module runtime, or listener exists), both migration commands, the bootstrap CLI, and Doctor's own connection. Doctor reports it as a blocking failure, never a warning, naming only the effective mode. Separately, the identity base URL and every trusted origin must now be exactly one canonical origin — the WHATWG origin serialization must equal the supplied string — so a path, trailing slash, credentials, explicit default port, or non-canonical case is rejected rather than normalized into something that no longer matches what a browser sends. Production's loopback rejection now classifies the address instead of comparing against three literals, covering `.localhost`, all of 127.0.0.0/8, 0.0.0.0, `::`, expanded and IPv4-mapped forms. This is a configuration-shape guarantee only: it does not resolve DNS or prove reachability, and TLS protects the connection, not the exposure. Co-Authored-By: Claude Opus 5 <[email protected]>
This commit is contained in:
ekklesia
co-authored by
Claude Opus 5
Claude Opus 5
parent
7a0f624fc3
commit
6b6b77c105
@@ -1,5 +1,9 @@
|
||||
import { drizzle, type NodePgDatabase } from "drizzle-orm/node-postgres";
|
||||
import { Pool, type PoolConfig } from "pg";
|
||||
import {
|
||||
type DatabaseTransportPolicy,
|
||||
databaseTlsConnectionOptions,
|
||||
} from "../database/transport.js";
|
||||
import { authorizationSchema } from "./schema.js";
|
||||
|
||||
export type AuthorizationDrizzleDatabase = NodePgDatabase<typeof authorizationSchema>;
|
||||
@@ -27,6 +31,10 @@ export interface AuthorizationDatabaseOptions {
|
||||
* `core/src/identity/database.ts`: `connectionTimeoutMs` alone only bounds establishing a
|
||||
* connection, not a hung query already running on one. */
|
||||
readonly operationTimeoutMs?: number;
|
||||
/** The validated transport policy (`core/src/database/transport.js`). Passed explicitly by
|
||||
* every production executable; omitted by single-domain unit/integration factories that use
|
||||
* the disposable loopback database, which keeps the pre-existing plaintext behavior. */
|
||||
readonly transport?: DatabaseTransportPolicy;
|
||||
}
|
||||
|
||||
export interface AuthorizationDatabaseHandle {
|
||||
@@ -80,8 +88,13 @@ export function createAuthorizationDrizzleDatabase(
|
||||
const validatedConnectionString = validateConnectionString(connectionString);
|
||||
const validatedConnectionTimeoutMs = validateTimeout(options.connectionTimeoutMs);
|
||||
const validatedOperationTimeoutMs = validateTimeout(options.operationTimeoutMs);
|
||||
const ssl =
|
||||
options.transport === undefined
|
||||
? undefined
|
||||
: databaseTlsConnectionOptions(validatedConnectionString, options.transport);
|
||||
const poolConfig: PoolConfig = {
|
||||
connectionString: validatedConnectionString,
|
||||
...(ssl === undefined ? {} : { ssl }),
|
||||
...(validatedConnectionTimeoutMs === undefined
|
||||
? {}
|
||||
: { connectionTimeoutMillis: validatedConnectionTimeoutMs }),
|
||||
|
||||
@@ -1,11 +1,19 @@
|
||||
import { formatMigrationApplyReport } from "./migration-report.js";
|
||||
import { discoverRepositoryMigrations } from "./migration-command-support.js";
|
||||
import { reportMigrationCommandError } from "./migration-command-errors.js";
|
||||
import { resolveExecutableDatabaseTransport } from "./database-transport-environment.js";
|
||||
import { applyModuleMigrations, createPostgresMigrationDatabase } from "../migrations/index.js";
|
||||
|
||||
async function main(): Promise<void> {
|
||||
const aggregate = await discoverRepositoryMigrations();
|
||||
const database = createPostgresMigrationDatabase(process.env.DATABASE_URL);
|
||||
const databaseUrl = process.env.DATABASE_URL;
|
||||
// Resolved and asserted before any client exists: an unsafe production transport fails
|
||||
// here rather than after opening a connection.
|
||||
const transport =
|
||||
typeof databaseUrl === "string" ? resolveExecutableDatabaseTransport(databaseUrl) : undefined;
|
||||
const database = createPostgresMigrationDatabase(databaseUrl, {
|
||||
...(transport === undefined ? {} : { transport }),
|
||||
});
|
||||
const result = await applyModuleMigrations({ aggregate, database });
|
||||
|
||||
for (const line of formatMigrationApplyReport(result)) {
|
||||
|
||||
@@ -6,6 +6,7 @@ import {
|
||||
createAuthorizationDrizzleDatabase,
|
||||
PlatformOwnerBootstrapError,
|
||||
} from "../authorization/index.js";
|
||||
import { resolveExecutableDatabaseTransport } from "./database-transport-environment.js";
|
||||
|
||||
class BootstrapCliError extends Error {
|
||||
constructor(message: string) {
|
||||
@@ -67,9 +68,13 @@ async function main(): Promise<void> {
|
||||
throw new BootstrapCliError("DATABASE_URL is required.");
|
||||
}
|
||||
|
||||
// Asserted before the connection is constructed, so an unsafe production transport never opens
|
||||
// a client at all.
|
||||
const transport = resolveExecutableDatabaseTransport(databaseUrl);
|
||||
const { close, db } = createAuthorizationDrizzleDatabase(databaseUrl, {
|
||||
connectionTimeoutMs: 10_000,
|
||||
operationTimeoutMs: 10_000,
|
||||
transport,
|
||||
});
|
||||
try {
|
||||
await bootstrapPlatformOwner(db, { userId: parsedUserId.data });
|
||||
|
||||
@@ -0,0 +1,46 @@
|
||||
import {
|
||||
assertProductionDatabaseTransport,
|
||||
type DatabaseTransportEnvironment,
|
||||
type DatabaseTransportPolicy,
|
||||
createDatabaseTransportPolicy,
|
||||
} from "../database/transport.js";
|
||||
|
||||
/**
|
||||
* The one place every Core-owned executable reads its database transport policy from the process
|
||||
* environment, so `pnpm doctor`, `pnpm migrations:plan`, `pnpm migrations:apply`, and
|
||||
* `pnpm authorization:bootstrap-owner` cannot drift from each other or from `apps/api`.
|
||||
*
|
||||
* Environment reading lives here, in the executable layer, deliberately: the reusable Core
|
||||
* database/migration constructors keep taking explicit typed inputs and never touch `process.env`.
|
||||
* `NODE_ENV` is interpreted exactly as `apps/api` interprets it — only the literal string
|
||||
* `"development"` relaxes anything, so an unset or misspelled value validates as production.
|
||||
*/
|
||||
export function readDatabaseTransportFromEnvironment(): {
|
||||
readonly environment: DatabaseTransportEnvironment;
|
||||
readonly transport: DatabaseTransportPolicy;
|
||||
} {
|
||||
const environment: DatabaseTransportEnvironment =
|
||||
process.env.NODE_ENV === "development" ? "development" : "production";
|
||||
const transport = createDatabaseTransportPolicy(
|
||||
{
|
||||
...(process.env.EKKLESIA_DATABASE_CA === undefined
|
||||
? {}
|
||||
: { certificateAuthority: process.env.EKKLESIA_DATABASE_CA }),
|
||||
...(process.env.EKKLESIA_DATABASE_TLS_MODE === undefined
|
||||
? {}
|
||||
: { mode: process.env.EKKLESIA_DATABASE_TLS_MODE }),
|
||||
},
|
||||
{ environment },
|
||||
);
|
||||
return { environment, transport };
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolves the policy and asserts it is safe for the given database URL before any client, pool,
|
||||
* or connection is constructed. Throws the sanitized `DatabaseTransportError` otherwise.
|
||||
*/
|
||||
export function resolveExecutableDatabaseTransport(databaseUrl: string): DatabaseTransportPolicy {
|
||||
const { environment, transport } = readDatabaseTransportFromEnvironment();
|
||||
assertProductionDatabaseTransport(databaseUrl, transport, environment);
|
||||
return transport;
|
||||
}
|
||||
@@ -81,8 +81,19 @@ export async function runDoctorCommand(repositoryRoot = process.cwd()): Promise<
|
||||
const rootPackage = rootPackageDocument(rootValue);
|
||||
const moduleSdkPackage = rootPackageDocument(moduleSdkValue);
|
||||
|
||||
const databaseEnvironment =
|
||||
process.env.NODE_ENV === "development" ? ("development" as const) : ("production" as const);
|
||||
const report = await diagnoseEkklesia({
|
||||
clientAddress: readClientAddressFromEnvironment(),
|
||||
databaseEnvironment,
|
||||
databaseTransport: {
|
||||
...(process.env.EKKLESIA_DATABASE_CA === undefined
|
||||
? {}
|
||||
: { certificateAuthority: process.env.EKKLESIA_DATABASE_CA }),
|
||||
...(process.env.EKKLESIA_DATABASE_TLS_MODE === undefined
|
||||
? {}
|
||||
: { mode: process.env.EKKLESIA_DATABASE_TLS_MODE }),
|
||||
},
|
||||
databaseUrl: process.env.DATABASE_URL,
|
||||
identityConfiguration: readIdentityConfigurationFromEnvironment(),
|
||||
moduleDiscovery: {
|
||||
|
||||
@@ -1,7 +1,16 @@
|
||||
import { DatabaseTransportError } from "../database/transport.js";
|
||||
import { MigrationRunnerError, PostgresMigrationDatabaseError } from "../migrations/index.js";
|
||||
import { ModuleDiscoveryError, ModuleMigrationDiscoveryError } from "../modules/index.js";
|
||||
|
||||
export function reportMigrationCommandError(error: unknown): void {
|
||||
if (error instanceof DatabaseTransportError) {
|
||||
// The message is a fixed string chosen by code; it never carries the connection string, host,
|
||||
// port, credentials, CA material, or the offending mode value, so it is safe to print as-is —
|
||||
// and an operator who misconfigured TLS needs to know that, not "failed unexpectedly".
|
||||
console.error(`[${error.code}] ${error.message}`);
|
||||
return;
|
||||
}
|
||||
|
||||
if (error instanceof ModuleDiscoveryError) {
|
||||
console.error(error.message);
|
||||
for (const issue of error.issues) {
|
||||
|
||||
@@ -1,11 +1,19 @@
|
||||
import { formatMigrationPlanReport } from "./migration-report.js";
|
||||
import { discoverRepositoryMigrations } from "./migration-command-support.js";
|
||||
import { reportMigrationCommandError } from "./migration-command-errors.js";
|
||||
import { resolveExecutableDatabaseTransport } from "./database-transport-environment.js";
|
||||
import { createPostgresMigrationDatabase, planModuleMigrations } from "../migrations/index.js";
|
||||
|
||||
async function main(): Promise<void> {
|
||||
const aggregate = await discoverRepositoryMigrations();
|
||||
const database = createPostgresMigrationDatabase(process.env.DATABASE_URL);
|
||||
const databaseUrl = process.env.DATABASE_URL;
|
||||
// Resolved and asserted before any client exists: an unsafe production transport fails
|
||||
// here rather than after opening a connection.
|
||||
const transport =
|
||||
typeof databaseUrl === "string" ? resolveExecutableDatabaseTransport(databaseUrl) : undefined;
|
||||
const database = createPostgresMigrationDatabase(databaseUrl, {
|
||||
...(transport === undefined ? {} : { transport }),
|
||||
});
|
||||
const plan = await planModuleMigrations({ aggregate, database });
|
||||
|
||||
for (const line of formatMigrationPlanReport(plan)) {
|
||||
|
||||
@@ -1 +1,2 @@
|
||||
export * from "./pool.js";
|
||||
export * from "./transport.js";
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import { Pool, type PoolConfig } from "pg";
|
||||
import { type DatabaseTransportPolicy, databaseTlsConnectionOptions } from "./transport.js";
|
||||
|
||||
export type PostgresPoolErrorCode = "POSTGRES_POOL_CONFIGURATION_INVALID";
|
||||
|
||||
@@ -22,6 +23,11 @@ export interface PostgresPoolOptions {
|
||||
/** Bounds both `query_timeout` and `statement_timeout`: `connectionTimeoutMs` alone only bounds
|
||||
* establishing a connection, not a hung query already running on one. */
|
||||
readonly operationTimeoutMs?: number;
|
||||
/** The validated transport policy (`./transport.js`). Omitted only by isolated unit-test and
|
||||
* single-domain factories that connect to a disposable loopback database; every production
|
||||
* executable passes one explicitly. When omitted, no `ssl` option is set and the connection is
|
||||
* plaintext — exactly the pre-existing development behavior. */
|
||||
readonly transport?: DatabaseTransportPolicy;
|
||||
}
|
||||
|
||||
export interface PostgresPoolHandle {
|
||||
@@ -84,8 +90,16 @@ export function createValidatedPostgresPool(
|
||||
const validatedConnectionString = validateConnectionString(connectionString);
|
||||
const validatedConnectionTimeoutMs = validateTimeout(options.connectionTimeoutMs);
|
||||
const validatedOperationTimeoutMs = validateTimeout(options.operationTimeoutMs);
|
||||
// `databaseTlsConnectionOptions` also rejects a URL carrying its own TLS parameters, so the
|
||||
// pinned driver's `Object.assign({}, config, parse(connectionString))` precedence can never
|
||||
// silently replace the policy's `ssl` object with a weaker one.
|
||||
const ssl =
|
||||
options.transport === undefined
|
||||
? undefined
|
||||
: databaseTlsConnectionOptions(validatedConnectionString, options.transport);
|
||||
const poolConfig: PoolConfig = {
|
||||
connectionString: validatedConnectionString,
|
||||
...(ssl === undefined ? {} : { ssl }),
|
||||
...(validatedConnectionTimeoutMs === undefined
|
||||
? {}
|
||||
: { connectionTimeoutMillis: validatedConnectionTimeoutMs }),
|
||||
|
||||
@@ -0,0 +1,252 @@
|
||||
import net from "node:net";
|
||||
import tls from "node:tls";
|
||||
import type { ConnectionOptions } from "node:tls";
|
||||
|
||||
export type DatabaseTransportEnvironment = "development" | "production";
|
||||
|
||||
/**
|
||||
* The two transport modes this release supports, named after the libpq/PostgreSQL vocabulary an
|
||||
* operator already knows:
|
||||
*
|
||||
* - `verify-full` — TLS is required, the server certificate must chain to a trusted CA, **and**
|
||||
* the certificate identity must match the configured database host. This is the production
|
||||
* default, and the only mode a production deployment may use.
|
||||
* - `disable` — no TLS at all. Available only for the disposable loopback PostgreSQL used by local
|
||||
* development and this repository's integration harness.
|
||||
*
|
||||
* There is deliberately no encryption-only mode (`require`/`verify-ca`) and no
|
||||
* `rejectUnauthorized: false` escape hatch: both authenticate nothing, and an unauthenticated
|
||||
* encrypted channel to an attacker-controlled endpoint is not a security property worth offering.
|
||||
*/
|
||||
export type DatabaseTlsMode = "disable" | "verify-full";
|
||||
|
||||
export type DatabaseTransportErrorCode =
|
||||
| "DATABASE_TLS_CONNECTION_STRING_CONFLICT"
|
||||
| "DATABASE_TLS_MODE_INVALID"
|
||||
| "DATABASE_TLS_REQUIRED_IN_PRODUCTION"
|
||||
| "DATABASE_URL_INVALID";
|
||||
|
||||
const errorMessages: Readonly<Record<DatabaseTransportErrorCode, string>> = Object.freeze({
|
||||
DATABASE_TLS_CONNECTION_STRING_CONFLICT:
|
||||
"The database URL must not carry TLS parameters; configure the database TLS mode explicitly.",
|
||||
DATABASE_TLS_MODE_INVALID: 'The database TLS mode must be exactly "verify-full" or "disable".',
|
||||
DATABASE_TLS_REQUIRED_IN_PRODUCTION:
|
||||
"A production database connection must use certificate-verified TLS.",
|
||||
DATABASE_URL_INVALID: "The database URL must be an absolute postgres:// or postgresql:// URL.",
|
||||
});
|
||||
|
||||
/** Never carries the connection string, host, port, database name, credentials, certificate, CA
|
||||
* material, or the offending mode value. */
|
||||
export class DatabaseTransportError extends Error {
|
||||
readonly code: DatabaseTransportErrorCode;
|
||||
|
||||
constructor(code: DatabaseTransportErrorCode) {
|
||||
super(errorMessages[code]);
|
||||
this.name = "DatabaseTransportError";
|
||||
this.code = code;
|
||||
this.stack = `${this.name}: ${this.message}`;
|
||||
Object.freeze(this);
|
||||
}
|
||||
}
|
||||
|
||||
export interface DatabaseTransportPolicy {
|
||||
readonly mode: DatabaseTlsMode;
|
||||
/** PEM trust material for a private PostgreSQL CA. Optional: when omitted, Node's own trusted CA
|
||||
* set is used. Never logged, never echoed in an error. */
|
||||
readonly certificateAuthority?: string;
|
||||
}
|
||||
|
||||
export interface DatabaseTransportPolicyInput {
|
||||
readonly mode?: unknown;
|
||||
readonly certificateAuthority?: unknown;
|
||||
}
|
||||
|
||||
export interface CreateDatabaseTransportPolicyOptions {
|
||||
/** Defaults to production, so an omitted environment never silently relaxes transport security. */
|
||||
readonly environment?: DatabaseTransportEnvironment;
|
||||
}
|
||||
|
||||
/**
|
||||
* Every TLS-related parameter `[email protected]` recognizes in a PostgreSQL URL. These
|
||||
* are rejected outright rather than merged, because the pinned driver resolves them in a way that
|
||||
* silently defeats an explicit policy: `pg`'s own `ConnectionParameters` does
|
||||
* `Object.assign({}, config, parse(config.connectionString))`
|
||||
* (`pg/lib/connection-parameters.js`), so a URL parameter **overwrites** the `ssl` object a caller
|
||||
* passed alongside it. Verified directly against a live TLS PostgreSQL instance: a
|
||||
* `?sslmode=disable` URL combined with an explicit certificate-verifying `ssl` object connects in
|
||||
* plaintext.
|
||||
*
|
||||
* The pinned release additionally aliases `prefer`/`require`/`verify-ca` to full verification while
|
||||
* printing a deprecation warning that they will adopt weaker libpq semantics in `pg@9`, so even
|
||||
* a URL that looks safe today is not a durable guarantee. One typed policy is the whole contract.
|
||||
*/
|
||||
const CONNECTION_STRING_TLS_PARAMETERS = Object.freeze([
|
||||
"ssl",
|
||||
"sslcert",
|
||||
"sslkey",
|
||||
"sslmode",
|
||||
"sslnegotiation",
|
||||
"sslpassword",
|
||||
"sslrootcert",
|
||||
"uselibpqcompat",
|
||||
]);
|
||||
|
||||
function parseDatabaseUrl(databaseUrl: string): URL {
|
||||
let url: URL;
|
||||
try {
|
||||
url = new URL(databaseUrl);
|
||||
} catch {
|
||||
throw new DatabaseTransportError("DATABASE_URL_INVALID");
|
||||
}
|
||||
if (url.protocol !== "postgres:" && url.protocol !== "postgresql:") {
|
||||
throw new DatabaseTransportError("DATABASE_URL_INVALID");
|
||||
}
|
||||
return url;
|
||||
}
|
||||
|
||||
/** The host a certificate's identity must match — the exact host the driver will connect to. */
|
||||
export function databaseHostFromUrl(databaseUrl: string): string {
|
||||
const url = parseDatabaseUrl(databaseUrl);
|
||||
// `URL.hostname` keeps IPv6 literals bracketed; TLS identity checking wants the bare address.
|
||||
const hostname = url.hostname;
|
||||
return hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
|
||||
}
|
||||
|
||||
/** Whether the database endpoint is an unambiguous loopback literal. Used only to decide whether
|
||||
* the development plaintext mode is even permissible; it is never a production allowance. */
|
||||
function isLoopbackDatabaseHost(host: string): boolean {
|
||||
const normalized = host.toLowerCase();
|
||||
if (normalized === "localhost" || normalized.endsWith(".localhost")) {
|
||||
return true;
|
||||
}
|
||||
if (net.isIPv4(normalized)) {
|
||||
return normalized.startsWith("127.");
|
||||
}
|
||||
if (net.isIPv6(normalized)) {
|
||||
return normalized === "::1" || normalized === "::ffff:127.0.0.1";
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Validates the typed transport policy. Parsing is deliberately separate from environment policy,
|
||||
* matching the convention the public-signup gate already established: a malformed mode is reported
|
||||
* as malformed in every environment, never relabeled as a production failure.
|
||||
*/
|
||||
export function createDatabaseTransportPolicy(
|
||||
input: DatabaseTransportPolicyInput = {},
|
||||
options: CreateDatabaseTransportPolicyOptions = {},
|
||||
): DatabaseTransportPolicy {
|
||||
const environment = options.environment ?? "production";
|
||||
|
||||
let mode: DatabaseTlsMode;
|
||||
if (input.mode === undefined) {
|
||||
// Production fails safe to verified TLS; development keeps the plaintext disposable-PostgreSQL
|
||||
// workflow this repository's harness relies on.
|
||||
mode = environment === "production" ? "verify-full" : "disable";
|
||||
} else if (input.mode === "verify-full" || input.mode === "disable") {
|
||||
mode = input.mode;
|
||||
} else {
|
||||
// No coercion of booleans, `1`, `"TRUE"`, `" verify-full "`, or any other loose spelling.
|
||||
throw new DatabaseTransportError("DATABASE_TLS_MODE_INVALID");
|
||||
}
|
||||
|
||||
if (environment === "production" && mode !== "verify-full") {
|
||||
throw new DatabaseTransportError("DATABASE_TLS_REQUIRED_IN_PRODUCTION");
|
||||
}
|
||||
|
||||
if (
|
||||
input.certificateAuthority !== undefined &&
|
||||
(typeof input.certificateAuthority !== "string" ||
|
||||
input.certificateAuthority.trim().length === 0)
|
||||
) {
|
||||
throw new DatabaseTransportError("DATABASE_TLS_MODE_INVALID");
|
||||
}
|
||||
|
||||
return Object.freeze({
|
||||
...(typeof input.certificateAuthority === "string"
|
||||
? { certificateAuthority: input.certificateAuthority }
|
||||
: {}),
|
||||
mode,
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Rejects any database URL carrying its own TLS parameters. Called before a pool or client is ever
|
||||
* constructed, so a URL can never silently downgrade or contradict the validated policy — there is
|
||||
* exactly one place transport security is decided.
|
||||
*/
|
||||
export function assertNoConnectionStringTlsParameters(databaseUrl: string): void {
|
||||
const url = parseDatabaseUrl(databaseUrl);
|
||||
for (const [name] of url.searchParams) {
|
||||
if (CONNECTION_STRING_TLS_PARAMETERS.includes(name.toLowerCase())) {
|
||||
throw new DatabaseTransportError("DATABASE_TLS_CONNECTION_STRING_CONFLICT");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Translates the validated policy into the exact pinned-`pg` options that achieve it, and asserts
|
||||
* the URL cannot override them.
|
||||
*
|
||||
* `verify-full` is **not** simply `ssl: true` or `{ rejectUnauthorized: true }`. Verified directly
|
||||
* against a live TLS PostgreSQL instance: those verify the certificate *chain*, but `pg` only sets
|
||||
* `options.servername` for non-IP hosts (`pg/lib/connection.js`), and Node performs no identity
|
||||
* check at all when `servername` is unset — so a certificate issued for an entirely different name
|
||||
* is accepted when connecting to an IP address. Supplying an explicit `checkServerIdentity` pinned
|
||||
* to the configured host closes that gap for DNS and IP hosts alike (proven: a certificate valid
|
||||
* only for `localhost` is rejected with `ERR_TLS_CERT_ALTNAME_INVALID` when reached via
|
||||
* `127.0.0.1`).
|
||||
*/
|
||||
export function databaseTlsConnectionOptions(
|
||||
databaseUrl: string,
|
||||
policy: DatabaseTransportPolicy,
|
||||
): false | ConnectionOptions {
|
||||
assertNoConnectionStringTlsParameters(databaseUrl);
|
||||
if (policy.mode === "disable") {
|
||||
return false;
|
||||
}
|
||||
const host = databaseHostFromUrl(databaseUrl);
|
||||
return {
|
||||
...(policy.certificateAuthority === undefined ? {} : { ca: policy.certificateAuthority }),
|
||||
// Chain verification. There is no configuration that can set this to `false`.
|
||||
rejectUnauthorized: true,
|
||||
// Identity verification against the host actually being connected to — never the SNI value pg
|
||||
// may or may not have set, and never skipped for an IP endpoint.
|
||||
checkServerIdentity: (_servername: string, certificate: tls.PeerCertificate) =>
|
||||
tls.checkServerIdentity(host, certificate),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* The one production guard every executable database path shares: a production deployment must use
|
||||
* `verify-full`, and its URL must not carry TLS parameters. There is no production plaintext
|
||||
* exception — not for loopback, not for an RFC1918 address, not for a Docker service name. A
|
||||
* production process that genuinely runs beside its database still gets certificate-verified TLS,
|
||||
* which costs nothing and removes an entire class of "it was only internal" misconfiguration.
|
||||
*/
|
||||
export function assertProductionDatabaseTransport(
|
||||
databaseUrl: string,
|
||||
policy: DatabaseTransportPolicy,
|
||||
environment: DatabaseTransportEnvironment,
|
||||
): void {
|
||||
assertNoConnectionStringTlsParameters(databaseUrl);
|
||||
if (environment !== "production") {
|
||||
return;
|
||||
}
|
||||
if (policy.mode !== "verify-full") {
|
||||
throw new DatabaseTransportError("DATABASE_TLS_REQUIRED_IN_PRODUCTION");
|
||||
}
|
||||
}
|
||||
|
||||
/** A fixed, generic description of the effective transport for diagnostics. Never includes the
|
||||
* URL, host, port, database name, credentials, certificate, or CA path. */
|
||||
export function describeDatabaseTransport(policy: DatabaseTransportPolicy): string {
|
||||
return policy.mode === "verify-full"
|
||||
? `TLS required with certificate and hostname verification${
|
||||
policy.certificateAuthority === undefined ? "" : " (explicit private CA supplied)"
|
||||
}.`
|
||||
: "TLS disabled (development/test plaintext).";
|
||||
}
|
||||
|
||||
export { isLoopbackDatabaseHost };
|
||||
@@ -13,7 +13,7 @@ const sections: readonly DoctorSection[] = Object.freeze([
|
||||
section("Platform", ["platform.runtime"]),
|
||||
section("Modules", ["modules.discovery", "modules.dependencies", "modules.permissions"]),
|
||||
section("Data definitions", ["schemas.discovery", "migrations.discovery"]),
|
||||
section("PostgreSQL", ["postgresql.connection", "postgresql.plan"]),
|
||||
section("PostgreSQL", ["database.transport", "postgresql.connection", "postgresql.plan"]),
|
||||
section("Identity", ["identity.configuration", "identity.client-address"]),
|
||||
section("Object storage", ["object-storage.integration"]),
|
||||
]);
|
||||
|
||||
@@ -7,6 +7,14 @@ import {
|
||||
} from "@ekklesia/contracts";
|
||||
import { getTableName } from "drizzle-orm";
|
||||
import { type PermissionRegistry, PermissionRegistryError } from "../authorization/index.js";
|
||||
import {
|
||||
assertProductionDatabaseTransport,
|
||||
type DatabaseTransportEnvironment,
|
||||
type DatabaseTransportPolicyInput,
|
||||
DatabaseTransportError,
|
||||
createDatabaseTransportPolicy,
|
||||
describeDatabaseTransport,
|
||||
} from "../database/transport.js";
|
||||
import {
|
||||
type ClientAddressConfigInput,
|
||||
ClientAddressConfigError,
|
||||
@@ -41,6 +49,7 @@ import {
|
||||
} from "../modules/index.js";
|
||||
|
||||
export type DoctorCheckId =
|
||||
| "database.transport"
|
||||
| "platform.runtime"
|
||||
| "modules.discovery"
|
||||
| "modules.dependencies"
|
||||
@@ -78,6 +87,10 @@ export interface DoctorIdentityConfigurationOptions {
|
||||
|
||||
export interface DoctorOptions {
|
||||
readonly clientAddress?: ClientAddressConfigInput | undefined;
|
||||
/** The environment the executable resolved, used only for transport policy evaluation; identity
|
||||
* configuration keeps its own `identityConfiguration.environment` for the same purpose. */
|
||||
readonly databaseEnvironment?: DatabaseTransportEnvironment | undefined;
|
||||
readonly databaseTransport?: DatabaseTransportPolicyInput | undefined;
|
||||
readonly databaseUrl?: string | undefined;
|
||||
readonly identityConfiguration?: DoctorIdentityConfigurationOptions | undefined;
|
||||
readonly moduleDiscovery: ModuleDiscoveryOptions;
|
||||
@@ -417,6 +430,41 @@ function identityConfigurationCheck(
|
||||
* combination is a `failure`, distinguishing the three states this pass's audit specifically calls
|
||||
* for: safe direct mode, explicitly configured proxy mode, and an invalid configuration.
|
||||
*/
|
||||
/**
|
||||
* Pure configuration validation only: never opens a connection, and never prints the database URL,
|
||||
* host, port, database name, credentials, certificate, or CA material. An unsafe production
|
||||
* transport is a blocking `failure`, not a warning — a production deployment that would reach
|
||||
* PostgreSQL without certificate-verified TLS is not "ready with warnings".
|
||||
*/
|
||||
function databaseTransportCheck(
|
||||
input: DatabaseTransportPolicyInput | undefined,
|
||||
databaseUrl: string | undefined,
|
||||
environment: DatabaseTransportEnvironment | undefined,
|
||||
): DoctorCheck {
|
||||
const effectiveEnvironment = environment ?? "production";
|
||||
try {
|
||||
const policy = createDatabaseTransportPolicy(input, { environment: effectiveEnvironment });
|
||||
if (typeof databaseUrl === "string" && databaseUrl.trim() !== "") {
|
||||
// Also rejects a URL carrying TLS parameters that could override the policy.
|
||||
assertProductionDatabaseTransport(databaseUrl, policy, effectiveEnvironment);
|
||||
}
|
||||
return freezeCheck(
|
||||
"database.transport",
|
||||
"pass",
|
||||
policy.mode === "verify-full"
|
||||
? "Database TLS verified"
|
||||
: "Database TLS disabled (development)",
|
||||
[describeDatabaseTransport(policy)],
|
||||
);
|
||||
} catch (error) {
|
||||
const code =
|
||||
error instanceof DatabaseTransportError ? error.code : "DATABASE_TRANSPORT_INVALID";
|
||||
return freezeCheck("database.transport", "failure", "Database transport unsafe", [
|
||||
`[${code}] The configured database transport is not permitted.`,
|
||||
]);
|
||||
}
|
||||
}
|
||||
|
||||
function clientAddressCheck(input: ClientAddressConfigInput | undefined): DoctorCheck {
|
||||
try {
|
||||
const config = createClientAddressConfig(input, TRUSTED_CLIENT_ADDRESS_HEADER);
|
||||
@@ -580,9 +628,16 @@ export async function diagnoseEkklesia(
|
||||
);
|
||||
} else {
|
||||
try {
|
||||
// Doctor's own read-only connection uses the exact same validated transport policy every
|
||||
// other executable does, so a Doctor "connection established" can never mean something
|
||||
// weaker than what `pnpm api:start` or `pnpm migrations:apply` would use.
|
||||
const doctorTransport = createDatabaseTransportPolicy(options.databaseTransport, {
|
||||
environment: options.databaseEnvironment ?? "production",
|
||||
});
|
||||
const database = dependencies.createMigrationDatabase(databaseUrl, {
|
||||
connectionTimeoutMs: doctorPostgresTimeoutMs,
|
||||
operationTimeoutMs: doctorPostgresTimeoutMs,
|
||||
transport: doctorTransport,
|
||||
});
|
||||
const plan = await dependencies.planMigrations({ aggregate: migrations, database });
|
||||
postgresConnectionCheck = freezeCheck(
|
||||
@@ -598,6 +653,11 @@ export async function diagnoseEkklesia(
|
||||
|
||||
const identityCheck = identityConfigurationCheck(options.identityConfiguration);
|
||||
const clientAddressDoctorCheck = clientAddressCheck(options.clientAddress);
|
||||
const transportCheck = databaseTransportCheck(
|
||||
options.databaseTransport,
|
||||
options.databaseUrl,
|
||||
options.databaseEnvironment,
|
||||
);
|
||||
|
||||
const storageCheck = freezeCheck("object-storage.integration", "skipped", "Check unavailable", [
|
||||
"Core storage integration has not been implemented yet.",
|
||||
@@ -610,6 +670,7 @@ export async function diagnoseEkklesia(
|
||||
permissionsCheck,
|
||||
schemaCheck,
|
||||
migrationCheck,
|
||||
transportCheck,
|
||||
postgresConnectionCheck,
|
||||
postgresPlanCheck,
|
||||
identityCheck,
|
||||
|
||||
+142
-20
@@ -18,12 +18,108 @@ export type IdentityConfigErrorCode =
|
||||
| "TRUSTED_ORIGINS_MISSING";
|
||||
|
||||
const MIN_SECRET_LENGTH = 32;
|
||||
const LOOPBACK_HOSTNAMES: ReadonlySet<string> = new Set([
|
||||
"localhost",
|
||||
"127.0.0.1",
|
||||
"::1",
|
||||
"0.0.0.0",
|
||||
]);
|
||||
|
||||
/**
|
||||
* Hostnames that are never a legitimate public production origin, matched exactly (after WHATWG
|
||||
* URL canonicalization, which already folds `127.1`, `2130706433`, and `0x7f000001` into
|
||||
* `127.0.0.1`, and lowercases every hostname).
|
||||
*
|
||||
* This is a purely *syntactic* classifier. It rejects literal and reserved loopback/unspecified
|
||||
* spellings; it performs no DNS resolution, so it cannot and does not prove that some arbitrary
|
||||
* public name will never resolve to a loopback address later. Network reachability remains the
|
||||
* deployment's own firewall/DNS responsibility.
|
||||
*/
|
||||
const IPV4_LOOPBACK_BLOCK = /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/u;
|
||||
const UNSPECIFIED_HOSTNAMES: ReadonlySet<string> = new Set(["0.0.0.0", "[::]"]);
|
||||
const LITERAL_LOOPBACK_HOSTNAMES: ReadonlySet<string> = new Set(["localhost"]);
|
||||
|
||||
/** Expands a bracketed IPv6 `URL.hostname` into its 8 canonical 16-bit groups, or `undefined` when
|
||||
* the value is not a bracketed IPv6 literal. Handles `::` zero-compression and the mixed
|
||||
* `::ffff:a.b.c.d` notation the WHATWG parser preserves. */
|
||||
function expandIpv6Hostname(hostname: string): readonly number[] | undefined {
|
||||
if (!hostname.startsWith("[") || !hostname.endsWith("]")) {
|
||||
return undefined;
|
||||
}
|
||||
let body = hostname.slice(1, -1);
|
||||
// Mixed notation: translate a trailing dotted-quad into two hex groups.
|
||||
const dotted = /^(.*:)(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/u.exec(body);
|
||||
if (dotted) {
|
||||
const octets = [dotted[2], dotted[3], dotted[4], dotted[5]].map((part) => Number(part));
|
||||
if (octets.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255)) {
|
||||
return undefined;
|
||||
}
|
||||
const high = ((octets[0] as number) << 8) | (octets[1] as number);
|
||||
const low = ((octets[2] as number) << 8) | (octets[3] as number);
|
||||
body = `${dotted[1]}${high.toString(16)}:${low.toString(16)}`;
|
||||
}
|
||||
|
||||
const [head, tail, ...extra] = body.split("::");
|
||||
if (extra.length > 0) {
|
||||
return undefined;
|
||||
}
|
||||
const parseGroups = (value: string | undefined): number[] | undefined => {
|
||||
if (value === undefined || value === "") {
|
||||
return [];
|
||||
}
|
||||
const groups: number[] = [];
|
||||
for (const part of value.split(":")) {
|
||||
if (!/^[0-9a-f]{1,4}$/u.test(part)) {
|
||||
return undefined;
|
||||
}
|
||||
groups.push(Number.parseInt(part, 16));
|
||||
}
|
||||
return groups;
|
||||
};
|
||||
const leading = parseGroups(head);
|
||||
const trailing = tail === undefined ? [] : parseGroups(tail);
|
||||
if (!leading || !trailing) {
|
||||
return undefined;
|
||||
}
|
||||
if (tail === undefined) {
|
||||
return leading.length === 8 ? leading : undefined;
|
||||
}
|
||||
const missing = 8 - leading.length - trailing.length;
|
||||
if (missing < 0) {
|
||||
return undefined;
|
||||
}
|
||||
return [...leading, ...Array.from({ length: missing }, () => 0), ...trailing];
|
||||
}
|
||||
|
||||
/** Whether a canonicalized `URL.hostname` is a loopback or unspecified listen address in any
|
||||
* spelling this repository accepts — literal name, reserved `.localhost` namespace, the full IPv4
|
||||
* `127.0.0.0/8` block, IPv6 `::1` compressed or expanded, IPv6 `::` unspecified, and IPv4-mapped
|
||||
* IPv6 forms of both in mixed (`::ffff:127.0.0.1`) and hexadecimal (`::ffff:7f00:1`) notation. */
|
||||
function isLoopbackOrUnspecifiedHostname(hostname: string): boolean {
|
||||
const normalized = hostname.toLowerCase();
|
||||
if (LITERAL_LOOPBACK_HOSTNAMES.has(normalized) || UNSPECIFIED_HOSTNAMES.has(normalized)) {
|
||||
return true;
|
||||
}
|
||||
// RFC 6761 reserves the entire `.localhost` namespace for loopback.
|
||||
if (normalized.endsWith(".localhost")) {
|
||||
return true;
|
||||
}
|
||||
if (IPV4_LOOPBACK_BLOCK.test(normalized)) {
|
||||
return true;
|
||||
}
|
||||
const groups = expandIpv6Hostname(normalized);
|
||||
if (!groups) {
|
||||
return false;
|
||||
}
|
||||
const isAllZero = groups.every((group) => group === 0);
|
||||
// `::` (unspecified) and `::1` (loopback).
|
||||
if (isAllZero || (groups.slice(0, 7).every((group) => group === 0) && groups[7] === 1)) {
|
||||
return true;
|
||||
}
|
||||
// IPv4-mapped IPv6 (`::ffff:a.b.c.d`): classify the embedded IPv4 address.
|
||||
const isMapped = groups.slice(0, 5).every((group) => group === 0) && groups[5] === 0xffff;
|
||||
if (isMapped) {
|
||||
const high = groups[6] as number;
|
||||
const low = groups[7] as number;
|
||||
const embedded = `${high >> 8}.${high & 0xff}.${low >> 8}.${low & 0xff}`;
|
||||
return IPV4_LOOPBACK_BLOCK.test(embedded) || embedded === "0.0.0.0";
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
const errorMessages: Readonly<Record<IdentityConfigErrorCode, string>> = Object.freeze({
|
||||
BASE_URL_INSECURE_IN_PRODUCTION: "The identity base URL must use https in production.",
|
||||
@@ -90,20 +186,38 @@ export interface CreateIdentityConfigOptions {
|
||||
readonly environment?: IdentityEnvironment;
|
||||
}
|
||||
|
||||
function isLoopbackHostname(hostname: string): boolean {
|
||||
return LOOPBACK_HOSTNAMES.has(hostname.toLowerCase());
|
||||
}
|
||||
|
||||
function parseAbsoluteHttpUrl(value: unknown): URL | undefined {
|
||||
/**
|
||||
* Parses one value that must be exactly a canonical absolute `http:`/`https:` **origin** — the
|
||||
* single representation both the identity base URL and every trusted origin use, so no component
|
||||
* of the platform can reinterpret the same deployment differently.
|
||||
*
|
||||
* Canonical means `URL.origin` must equal the configured string byte-for-byte. That one comparison
|
||||
* structurally rejects every non-origin component at once — credentials, any path (including a
|
||||
* bare trailing `/`, since `URL.origin` is slashless), a query, a fragment, surrounding
|
||||
* whitespace, an uppercase hostname, and a redundant default port — because the WHATWG parser
|
||||
* normalizes or preserves each of those in a way that no longer matches `origin`.
|
||||
*
|
||||
* Structural parsing is deliberately separate from environment policy: a caller distinguishes
|
||||
* "this is not an origin" from "this origin is not allowed in production" and reports the
|
||||
* structural code first, so an already-malformed URL is never mislabeled as a production-loopback
|
||||
* failure.
|
||||
*/
|
||||
function parseCanonicalHttpOrigin(value: unknown): URL | undefined {
|
||||
if (typeof value !== "string" || value.length === 0) {
|
||||
return undefined;
|
||||
}
|
||||
let url: URL;
|
||||
try {
|
||||
const url = new URL(value);
|
||||
return url.protocol === "http:" || url.protocol === "https:" ? url : undefined;
|
||||
url = new URL(value);
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
if (url.protocol !== "http:" && url.protocol !== "https:") {
|
||||
return undefined;
|
||||
}
|
||||
// `URL.origin` carries no credentials, path, query, or fragment, and is already lowercased with
|
||||
// any default port elided — so requiring exact equality is the whole canonical-origin rule.
|
||||
return url.origin === value ? url : undefined;
|
||||
}
|
||||
|
||||
function validateSecret(secret: unknown): string {
|
||||
@@ -126,7 +240,11 @@ function validateBaseUrl(baseUrl: unknown, environment: IdentityEnvironment): st
|
||||
if (typeof baseUrl !== "string" || baseUrl.length === 0) {
|
||||
throw new IdentityConfigError("BASE_URL_MISSING");
|
||||
}
|
||||
const url = parseAbsoluteHttpUrl(baseUrl);
|
||||
// Structural validity first, in every environment: the base URL is the public origin of the
|
||||
// already-fixed `/api/auth` transport, and Ekklesia does not support mounting Better Auth
|
||||
// beneath a configurable URL path. A credentialed, pathed, queried, fragmented, whitespace-
|
||||
// padded, or otherwise non-canonical spelling is structurally invalid, never a policy failure.
|
||||
const url = parseCanonicalHttpOrigin(baseUrl);
|
||||
if (!url) {
|
||||
throw new IdentityConfigError("BASE_URL_INVALID");
|
||||
}
|
||||
@@ -134,11 +252,13 @@ function validateBaseUrl(baseUrl: unknown, environment: IdentityEnvironment): st
|
||||
if (url.protocol !== "https:") {
|
||||
throw new IdentityConfigError("BASE_URL_INSECURE_IN_PRODUCTION");
|
||||
}
|
||||
if (isLoopbackHostname(url.hostname)) {
|
||||
if (isLoopbackOrUnspecifiedHostname(url.hostname)) {
|
||||
throw new IdentityConfigError("BASE_URL_LOOPBACK_IN_PRODUCTION");
|
||||
}
|
||||
}
|
||||
return baseUrl;
|
||||
// Store the canonical origin — identical to what `validateTrustedOrigin` stores — so CORS,
|
||||
// Better Auth's own origin checks, and this base URL can never disagree about the same origin.
|
||||
return url.origin;
|
||||
}
|
||||
|
||||
function validateTrustedOrigin(origin: unknown, environment: IdentityEnvironment): string {
|
||||
@@ -152,19 +272,21 @@ function validateTrustedOrigin(origin: unknown, environment: IdentityEnvironment
|
||||
if (origin.includes("*") || origin.includes("?")) {
|
||||
throw new IdentityConfigError("TRUSTED_ORIGIN_WILDCARD_UNSUPPORTED");
|
||||
}
|
||||
const url = parseAbsoluteHttpUrl(origin);
|
||||
if (!url || url.origin !== origin) {
|
||||
const url = parseCanonicalHttpOrigin(origin);
|
||||
if (!url) {
|
||||
throw new IdentityConfigError("TRUSTED_ORIGIN_INVALID");
|
||||
}
|
||||
if (environment === "production") {
|
||||
if (url.protocol !== "https:") {
|
||||
throw new IdentityConfigError("TRUSTED_ORIGIN_INSECURE_IN_PRODUCTION");
|
||||
}
|
||||
if (isLoopbackHostname(url.hostname)) {
|
||||
// The identical classifier the base URL uses, so the two can never disagree about whether the
|
||||
// same host is a production-legal origin.
|
||||
if (isLoopbackOrUnspecifiedHostname(url.hostname)) {
|
||||
throw new IdentityConfigError("TRUSTED_ORIGIN_LOOPBACK_IN_PRODUCTION");
|
||||
}
|
||||
}
|
||||
return origin;
|
||||
return url.origin;
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
import { drizzle, type NodePgDatabase } from "drizzle-orm/node-postgres";
|
||||
import { Pool, type PoolConfig } from "pg";
|
||||
import {
|
||||
type DatabaseTransportPolicy,
|
||||
databaseTlsConnectionOptions,
|
||||
} from "../database/transport.js";
|
||||
import { identityAdapterSchema } from "./schema.js";
|
||||
|
||||
export type IdentityDrizzleDatabase = NodePgDatabase<typeof identityAdapterSchema>;
|
||||
@@ -28,6 +32,10 @@ export interface IdentityDatabaseOptions {
|
||||
* indefinitely. `connectionTimeoutMs` alone only bounds establishing a connection — it does
|
||||
* nothing once a query is already running on one. */
|
||||
readonly operationTimeoutMs?: number;
|
||||
/** The validated transport policy (`core/src/database/transport.js`). Passed explicitly by
|
||||
* every production executable; omitted by single-domain unit/integration factories that use
|
||||
* the disposable loopback database, which keeps the pre-existing plaintext behavior. */
|
||||
readonly transport?: DatabaseTransportPolicy;
|
||||
}
|
||||
|
||||
export interface IdentityDatabaseHandle {
|
||||
@@ -81,8 +89,13 @@ export function createIdentityDrizzleDatabase(
|
||||
const validatedConnectionString = validateConnectionString(connectionString);
|
||||
const validatedConnectionTimeoutMs = validateTimeout(options.connectionTimeoutMs);
|
||||
const validatedOperationTimeoutMs = validateTimeout(options.operationTimeoutMs);
|
||||
const ssl =
|
||||
options.transport === undefined
|
||||
? undefined
|
||||
: databaseTlsConnectionOptions(validatedConnectionString, options.transport);
|
||||
const poolConfig: PoolConfig = {
|
||||
connectionString: validatedConnectionString,
|
||||
...(ssl === undefined ? {} : { ssl }),
|
||||
...(validatedConnectionTimeoutMs === undefined
|
||||
? {}
|
||||
: { connectionTimeoutMillis: validatedConnectionTimeoutMs }),
|
||||
|
||||
@@ -1,4 +1,8 @@
|
||||
import { Client, type ClientConfig, type QueryResultRow } from "pg";
|
||||
import {
|
||||
type DatabaseTransportPolicy,
|
||||
databaseTlsConnectionOptions,
|
||||
} from "../database/transport.js";
|
||||
import type {
|
||||
AppliedMigrationRecord,
|
||||
MigrationDatabase,
|
||||
@@ -76,6 +80,10 @@ export class PostgresMigrationDatabaseError extends Error {
|
||||
export interface PostgresMigrationDatabaseOptions {
|
||||
readonly connectionTimeoutMs?: number;
|
||||
readonly operationTimeoutMs?: number;
|
||||
/** The validated transport policy (`core/src/database/transport.js`). Every production executable
|
||||
* that plans or applies migrations passes one; omitting it keeps the pre-existing plaintext
|
||||
* behavior used by the disposable loopback PostgreSQL harness. */
|
||||
readonly transport?: DatabaseTransportPolicy;
|
||||
}
|
||||
|
||||
interface HistoryExistenceRow extends QueryResultRow {
|
||||
@@ -178,8 +186,16 @@ function createClientConfig(
|
||||
"The PostgreSQL operation timeout is invalid.",
|
||||
);
|
||||
|
||||
// Also rejects a URL carrying its own TLS parameters, so `pg`'s connection-string precedence
|
||||
// can never silently replace this policy with a weaker one.
|
||||
const ssl =
|
||||
options?.transport === undefined
|
||||
? undefined
|
||||
: databaseTlsConnectionOptions(connectionString, options.transport);
|
||||
|
||||
return {
|
||||
connectionString,
|
||||
...(ssl === undefined ? {} : { ssl }),
|
||||
...(validatedConnectionTimeoutMs === undefined
|
||||
? {}
|
||||
: { connectionTimeoutMillis: validatedConnectionTimeoutMs }),
|
||||
|
||||
@@ -0,0 +1,331 @@
|
||||
import { execFile } from "node:child_process";
|
||||
import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
import { promisify } from "node:util";
|
||||
import { Client } from "pg";
|
||||
import { afterAll, describe, expect, it } from "vitest";
|
||||
import { databaseTlsConnectionOptions } from "../src/database/transport.js";
|
||||
|
||||
const run = promisify(execFile);
|
||||
|
||||
/**
|
||||
* Real TLS proof for the production transport policy, exercised through the pinned `pg` client
|
||||
* against a disposable, TLS-enabled PostgreSQL container.
|
||||
*
|
||||
* Every certificate, key, and CA used here is generated at test runtime into an isolated temporary
|
||||
* directory and deleted in `afterAll` — no private-key material is committed to this repository.
|
||||
* The container, its name, and its published loopback port are likewise disposable and removed in
|
||||
* `afterAll` even when an assertion fails.
|
||||
*/
|
||||
const containerName = `ekklesia-database-tls-${process.pid}`;
|
||||
let certificateDirectory: string | undefined;
|
||||
let containerStarted = false;
|
||||
let boundPort: number | undefined;
|
||||
|
||||
class TlsHarnessError extends Error {
|
||||
constructor(message: string) {
|
||||
super(message);
|
||||
this.name = "TlsHarnessError";
|
||||
this.stack = `${this.name}: ${this.message}`;
|
||||
}
|
||||
}
|
||||
|
||||
async function openssl(args: readonly string[], cwd: string): Promise<void> {
|
||||
try {
|
||||
await run("openssl", [...args], { cwd });
|
||||
} catch {
|
||||
// Never surface openssl's own stderr: it can echo paths from the harness environment.
|
||||
throw new TlsHarnessError("The disposable TLS material could not be generated.");
|
||||
}
|
||||
}
|
||||
|
||||
/** Generates a private CA, a server certificate signed by it whose only SAN is `DNS:localhost`,
|
||||
* and an unrelated second CA. The deliberately narrow SAN is what makes the hostname-mismatch
|
||||
* assertion below meaningful: reaching the very same server through `127.0.0.1` must fail. */
|
||||
async function generateCertificates(directory: string): Promise<void> {
|
||||
await openssl(
|
||||
[
|
||||
"req",
|
||||
"-new",
|
||||
"-x509",
|
||||
"-days",
|
||||
"1",
|
||||
"-nodes",
|
||||
"-out",
|
||||
"ca.crt",
|
||||
"-keyout",
|
||||
"ca.key",
|
||||
"-subj",
|
||||
"/CN=Ekklesia Disposable Test CA",
|
||||
],
|
||||
directory,
|
||||
);
|
||||
await openssl(
|
||||
[
|
||||
"req",
|
||||
"-new",
|
||||
"-nodes",
|
||||
"-out",
|
||||
"server.csr",
|
||||
"-keyout",
|
||||
"server.key",
|
||||
"-subj",
|
||||
"/CN=localhost",
|
||||
],
|
||||
directory,
|
||||
);
|
||||
await writeFile(path.join(directory, "san.cnf"), "subjectAltName=DNS:localhost\n");
|
||||
await openssl(
|
||||
[
|
||||
"x509",
|
||||
"-req",
|
||||
"-in",
|
||||
"server.csr",
|
||||
"-CA",
|
||||
"ca.crt",
|
||||
"-CAkey",
|
||||
"ca.key",
|
||||
"-CAcreateserial",
|
||||
"-out",
|
||||
"server.crt",
|
||||
"-days",
|
||||
"1",
|
||||
"-extfile",
|
||||
"san.cnf",
|
||||
],
|
||||
directory,
|
||||
);
|
||||
await openssl(
|
||||
[
|
||||
"req",
|
||||
"-new",
|
||||
"-x509",
|
||||
"-days",
|
||||
"1",
|
||||
"-nodes",
|
||||
"-out",
|
||||
"other-ca.crt",
|
||||
"-keyout",
|
||||
"other-ca.key",
|
||||
"-subj",
|
||||
"/CN=Unrelated Test CA",
|
||||
],
|
||||
directory,
|
||||
);
|
||||
}
|
||||
|
||||
async function docker(args: readonly string[]): Promise<string> {
|
||||
const { stdout } = await run("docker", [...args]);
|
||||
return stdout.trim();
|
||||
}
|
||||
|
||||
async function startTlsPostgres(directory: string): Promise<number> {
|
||||
// The certificate/key are copied *inside* the container and re-owned before PostgreSQL starts:
|
||||
// PostgreSQL refuses a key file that is not owned by the database user or root, and a bind-
|
||||
// mounted host file keeps the host's ownership.
|
||||
await docker([
|
||||
"run",
|
||||
"-d",
|
||||
"--name",
|
||||
containerName,
|
||||
"-e",
|
||||
"POSTGRES_DB=ekklesia_tls",
|
||||
"-e",
|
||||
"POSTGRES_USER=ekklesia_tls",
|
||||
"-e",
|
||||
"POSTGRES_PASSWORD=ekklesia_tls",
|
||||
"-v",
|
||||
`${directory}:/certs-src:ro`,
|
||||
"-p",
|
||||
"127.0.0.1:0:5432",
|
||||
"--entrypoint",
|
||||
"/bin/sh",
|
||||
"postgres:18.4-alpine3.24",
|
||||
"-c",
|
||||
"mkdir -p /tls && cp /certs-src/server.crt /certs-src/server.key /tls/ && " +
|
||||
"chown postgres:postgres /tls/server.* && chmod 600 /tls/server.key && " +
|
||||
"exec docker-entrypoint.sh postgres -c ssl=on -c ssl_cert_file=/tls/server.crt " +
|
||||
"-c ssl_key_file=/tls/server.key",
|
||||
]);
|
||||
containerStarted = true;
|
||||
|
||||
const published = await docker(["port", containerName, "5432"]);
|
||||
const match = /^127\.0\.0\.1:(\d+)$/u.exec(published.split("\n")[0]?.trim() ?? "");
|
||||
if (!match) {
|
||||
throw new TlsHarnessError(
|
||||
"The disposable TLS PostgreSQL port is not bound safely to loopback.",
|
||||
);
|
||||
}
|
||||
return Number(match[1]);
|
||||
}
|
||||
|
||||
/** Bounded readiness polling — never an arbitrary sleep. Resolves once the server accepts a TLS
|
||||
* connection, or fails after the deadline. */
|
||||
async function waitForTlsReadiness(port: number, ca: string): Promise<void> {
|
||||
const deadline = Date.now() + 60_000;
|
||||
let lastError: unknown;
|
||||
while (Date.now() < deadline) {
|
||||
const client = new Client({
|
||||
connectionTimeoutMillis: 3_000,
|
||||
database: "ekklesia_tls",
|
||||
host: "localhost",
|
||||
password: "ekklesia_tls",
|
||||
port,
|
||||
ssl: { ca, rejectUnauthorized: true },
|
||||
user: "ekklesia_tls",
|
||||
});
|
||||
try {
|
||||
await client.connect();
|
||||
await client.end();
|
||||
return;
|
||||
} catch (error) {
|
||||
lastError = error;
|
||||
try {
|
||||
await client.end();
|
||||
} catch {
|
||||
// The failed client is already unusable; nothing to clean up beyond this.
|
||||
}
|
||||
await new Promise((resolve) => setTimeout(resolve, 250));
|
||||
}
|
||||
}
|
||||
throw new TlsHarnessError(
|
||||
`The disposable TLS PostgreSQL did not become ready: ${String(lastError)}`,
|
||||
);
|
||||
}
|
||||
|
||||
async function connectWith(
|
||||
host: string,
|
||||
port: number,
|
||||
ssl: ReturnType<typeof databaseTlsConnectionOptions>,
|
||||
): Promise<{ encrypted: boolean }> {
|
||||
const client = new Client({
|
||||
connectionTimeoutMillis: 5_000,
|
||||
database: "ekklesia_tls",
|
||||
host,
|
||||
password: "ekklesia_tls",
|
||||
port,
|
||||
...(ssl === false ? {} : { ssl }),
|
||||
user: "ekklesia_tls",
|
||||
});
|
||||
try {
|
||||
await client.connect();
|
||||
const result = await client.query<{ encrypted: boolean }>(
|
||||
"SELECT ssl AS encrypted FROM pg_stat_ssl WHERE pid = pg_backend_pid()",
|
||||
);
|
||||
return { encrypted: result.rows[0]?.encrypted === true };
|
||||
} finally {
|
||||
try {
|
||||
await client.end();
|
||||
} catch {
|
||||
// Closing an already-failed client is not itself a test failure.
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
afterAll(async () => {
|
||||
if (containerStarted) {
|
||||
await docker(["rm", "-f", containerName]).catch(() => undefined);
|
||||
}
|
||||
if (certificateDirectory) {
|
||||
// Removes the generated CA, server certificate, and every private key.
|
||||
await rm(certificateDirectory, { force: true, recursive: true }).catch(() => undefined);
|
||||
}
|
||||
});
|
||||
|
||||
describe.sequential("production PostgreSQL TLS policy against a real TLS endpoint", () => {
|
||||
it("starts a disposable TLS-enabled PostgreSQL with runtime-generated certificates", async () => {
|
||||
certificateDirectory = await mkdtemp(path.join(tmpdir(), "ekklesia-tls-"));
|
||||
await generateCertificates(certificateDirectory);
|
||||
boundPort = await startTlsPostgres(certificateDirectory);
|
||||
const ca = await readFile(path.join(certificateDirectory, "ca.crt"), "utf8");
|
||||
await waitForTlsReadiness(boundPort, ca);
|
||||
expect(boundPort).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
it("connects successfully, and encrypted, when the certificate is trusted and its identity matches the host", async () => {
|
||||
const ca = await readFile(path.join(certificateDirectory as string, "ca.crt"), "utf8");
|
||||
const ssl = databaseTlsConnectionOptions(
|
||||
`postgresql://ekklesia_tls@localhost:${boundPort}/ekklesia_tls`,
|
||||
{ certificateAuthority: ca, mode: "verify-full" },
|
||||
);
|
||||
|
||||
const { encrypted } = await connectWith("localhost", boundPort as number, ssl);
|
||||
expect(encrypted).toBe(true);
|
||||
});
|
||||
|
||||
it("refuses a certificate that does not chain to the configured CA", async () => {
|
||||
const otherCa = await readFile(
|
||||
path.join(certificateDirectory as string, "other-ca.crt"),
|
||||
"utf8",
|
||||
);
|
||||
const ssl = databaseTlsConnectionOptions(
|
||||
`postgresql://ekklesia_tls@localhost:${boundPort}/ekklesia_tls`,
|
||||
{ certificateAuthority: otherCa, mode: "verify-full" },
|
||||
);
|
||||
|
||||
await expect(connectWith("localhost", boundPort as number, ssl)).rejects.toMatchObject({
|
||||
code: "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
|
||||
});
|
||||
});
|
||||
|
||||
it("refuses a trusted certificate whose identity does not match the host being connected to", async () => {
|
||||
// The server certificate's only SAN is `DNS:localhost`, so reaching the identical server via
|
||||
// its IP address is a genuine hostname mismatch. This is the case the pinned driver does *not*
|
||||
// catch on its own: `pg` sets `servername` only for non-IP hosts, and Node performs no identity
|
||||
// check when it is unset, so `rejectUnauthorized: true` alone would accept this connection.
|
||||
const ca = await readFile(path.join(certificateDirectory as string, "ca.crt"), "utf8");
|
||||
const ssl = databaseTlsConnectionOptions(
|
||||
`postgresql://[email protected]:${boundPort}/ekklesia_tls`,
|
||||
{ certificateAuthority: ca, mode: "verify-full" },
|
||||
);
|
||||
|
||||
await expect(connectWith("127.0.0.1", boundPort as number, ssl)).rejects.toMatchObject({
|
||||
code: "ERR_TLS_CERT_ALTNAME_INVALID",
|
||||
});
|
||||
});
|
||||
|
||||
it("proves the gap the policy closes: chain-only verification would accept that same mismatch", async () => {
|
||||
const ca = await readFile(path.join(certificateDirectory as string, "ca.crt"), "utf8");
|
||||
// Exactly what `ssl: { ca, rejectUnauthorized: true }` alone does — no pinned
|
||||
// `checkServerIdentity`. It connects, which is why the policy supplies one.
|
||||
const { encrypted } = await connectWith("127.0.0.1", boundPort as number, {
|
||||
ca,
|
||||
rejectUnauthorized: true,
|
||||
});
|
||||
expect(encrypted).toBe(true);
|
||||
});
|
||||
|
||||
it("cannot satisfy verify-full against a plaintext-only PostgreSQL endpoint", async () => {
|
||||
// The disposable plaintext PostgreSQL the rest of the integration suite uses.
|
||||
const plaintextUrl = process.env.EKKLESIA_MIGRATION_TEST_DATABASE_URL;
|
||||
if (typeof plaintextUrl !== "string" || plaintextUrl.trim() === "") {
|
||||
throw new TlsHarnessError("The plaintext integration database is not configured.");
|
||||
}
|
||||
const parsed = new URL(plaintextUrl);
|
||||
const ca = await readFile(path.join(certificateDirectory as string, "ca.crt"), "utf8");
|
||||
const ssl = databaseTlsConnectionOptions(plaintextUrl, {
|
||||
certificateAuthority: ca,
|
||||
mode: "verify-full",
|
||||
});
|
||||
|
||||
const client = new Client({
|
||||
connectionTimeoutMillis: 5_000,
|
||||
database: parsed.pathname.slice(1),
|
||||
host: parsed.hostname,
|
||||
password: decodeURIComponent(parsed.password),
|
||||
port: Number(parsed.port),
|
||||
...(ssl === false ? {} : { ssl }),
|
||||
user: decodeURIComponent(parsed.username),
|
||||
});
|
||||
try {
|
||||
await expect(client.connect()).rejects.toBeTruthy();
|
||||
} finally {
|
||||
try {
|
||||
await client.end();
|
||||
} catch {
|
||||
// Already unusable.
|
||||
}
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,303 @@
|
||||
import tls from "node:tls";
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
import { reportMigrationCommandError } from "../src/cli/migration-command-errors.js";
|
||||
import {
|
||||
assertNoConnectionStringTlsParameters,
|
||||
assertProductionDatabaseTransport,
|
||||
createDatabaseTransportPolicy,
|
||||
databaseHostFromUrl,
|
||||
DatabaseTransportError,
|
||||
databaseTlsConnectionOptions,
|
||||
describeDatabaseTransport,
|
||||
} from "../src/database/transport.js";
|
||||
|
||||
const productionUrl = "postgresql://ekklesia:[email protected]:5432/ekklesia";
|
||||
|
||||
describe("createDatabaseTransportPolicy", () => {
|
||||
it("defaults to certificate-verified TLS in production and plaintext in development", () => {
|
||||
expect(createDatabaseTransportPolicy()).toEqual({ mode: "verify-full" });
|
||||
expect(createDatabaseTransportPolicy({}, { environment: "production" })).toEqual({
|
||||
mode: "verify-full",
|
||||
});
|
||||
expect(createDatabaseTransportPolicy({}, { environment: "development" })).toEqual({
|
||||
mode: "disable",
|
||||
});
|
||||
});
|
||||
|
||||
it("refuses plaintext in production", () => {
|
||||
let captured: unknown;
|
||||
try {
|
||||
createDatabaseTransportPolicy({ mode: "disable" }, { environment: "production" });
|
||||
} catch (error) {
|
||||
captured = error;
|
||||
}
|
||||
expect(captured).toBeInstanceOf(DatabaseTransportError);
|
||||
expect(captured).toMatchObject({ code: "DATABASE_TLS_REQUIRED_IN_PRODUCTION" });
|
||||
});
|
||||
|
||||
it("rejects every loose, aliased, or coercible mode spelling in both environments", () => {
|
||||
for (const mode of [
|
||||
"VERIFY-FULL",
|
||||
"Verify-Full",
|
||||
" verify-full",
|
||||
"verify-full ",
|
||||
"require", // encryption-only: deliberately unsupported
|
||||
"verify-ca", // no hostname verification: deliberately unsupported
|
||||
"prefer",
|
||||
"no-verify",
|
||||
"allow",
|
||||
"true",
|
||||
true,
|
||||
false,
|
||||
1,
|
||||
0,
|
||||
"",
|
||||
null,
|
||||
]) {
|
||||
for (const environment of ["production", "development"] as const) {
|
||||
let captured: unknown;
|
||||
try {
|
||||
createDatabaseTransportPolicy({ mode }, { environment });
|
||||
} catch (error) {
|
||||
captured = error;
|
||||
}
|
||||
expect(captured, `expected ${JSON.stringify(mode)} to be rejected`).toMatchObject({
|
||||
code: "DATABASE_TLS_MODE_INVALID",
|
||||
});
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
it("accepts an optional private CA and rejects an empty one", () => {
|
||||
expect(
|
||||
createDatabaseTransportPolicy({ certificateAuthority: "-----BEGIN CERTIFICATE-----" })
|
||||
.certificateAuthority,
|
||||
).toBe("-----BEGIN CERTIFICATE-----");
|
||||
for (const certificateAuthority of ["", " ", 42]) {
|
||||
let captured: unknown;
|
||||
try {
|
||||
createDatabaseTransportPolicy({ certificateAuthority });
|
||||
} catch (error) {
|
||||
captured = error;
|
||||
}
|
||||
expect(captured).toBeInstanceOf(DatabaseTransportError);
|
||||
}
|
||||
});
|
||||
|
||||
it("never carries the offending mode or CA material in the thrown error", () => {
|
||||
let captured: unknown;
|
||||
try {
|
||||
createDatabaseTransportPolicy({ certificateAuthority: "SUPER-SECRET-CA", mode: "sslmode=x" });
|
||||
} catch (error) {
|
||||
captured = error;
|
||||
}
|
||||
const publicText = `${String(captured)}\n${
|
||||
captured instanceof Error ? (captured.stack ?? "") : ""
|
||||
}\n${JSON.stringify(captured)}`;
|
||||
expect(publicText).not.toContain("SUPER-SECRET-CA");
|
||||
expect(publicText).not.toContain("sslmode=x");
|
||||
});
|
||||
});
|
||||
|
||||
describe("assertNoConnectionStringTlsParameters", () => {
|
||||
it("rejects every TLS parameter the pinned connection-string parser recognizes", () => {
|
||||
for (const parameter of [
|
||||
"ssl=true",
|
||||
"sslmode=disable",
|
||||
"sslmode=require",
|
||||
"sslmode=verify-full",
|
||||
"sslcert=/tmp/c.crt",
|
||||
"sslkey=/tmp/c.key",
|
||||
"sslrootcert=/tmp/ca.crt",
|
||||
"sslpassword=x",
|
||||
"sslnegotiation=direct",
|
||||
"uselibpqcompat=true",
|
||||
"SSLMODE=disable", // case-insensitive
|
||||
]) {
|
||||
let captured: unknown;
|
||||
try {
|
||||
assertNoConnectionStringTlsParameters(`${productionUrl}?${parameter}`);
|
||||
} catch (error) {
|
||||
captured = error;
|
||||
}
|
||||
expect(captured, `expected ${parameter} to be rejected`).toMatchObject({
|
||||
code: "DATABASE_TLS_CONNECTION_STRING_CONFLICT",
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
it("allows an unrelated parameter", () => {
|
||||
expect(() =>
|
||||
assertNoConnectionStringTlsParameters(`${productionUrl}?application_name=ekklesia`),
|
||||
).not.toThrow();
|
||||
});
|
||||
|
||||
it("rejects a non-PostgreSQL or malformed URL", () => {
|
||||
for (const url of ["", "not-a-url", "mysql://db.example.test/x", "http://db.example.test"]) {
|
||||
let captured: unknown;
|
||||
try {
|
||||
assertNoConnectionStringTlsParameters(url);
|
||||
} catch (error) {
|
||||
captured = error;
|
||||
}
|
||||
expect(captured).toMatchObject({ code: "DATABASE_URL_INVALID" });
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe("databaseTlsConnectionOptions", () => {
|
||||
it("produces no TLS options at all when the policy disables TLS", () => {
|
||||
expect(
|
||||
databaseTlsConnectionOptions("postgresql://127.0.0.1:5432/ekklesia", { mode: "disable" }),
|
||||
).toBe(false);
|
||||
});
|
||||
|
||||
it("enables chain verification and pins hostname verification to the configured host", () => {
|
||||
const options = databaseTlsConnectionOptions(productionUrl, { mode: "verify-full" });
|
||||
expect(options).not.toBe(false);
|
||||
if (options === false) {
|
||||
throw new Error("expected TLS options");
|
||||
}
|
||||
// There is no configuration path that produces `rejectUnauthorized: false`.
|
||||
expect(options.rejectUnauthorized).toBe(true);
|
||||
expect(typeof options.checkServerIdentity).toBe("function");
|
||||
expect(options.ca).toBeUndefined();
|
||||
});
|
||||
|
||||
it("checks the certificate against the configured host, not against whatever SNI the driver set", () => {
|
||||
// The pinned driver sets `servername` only for non-IP hosts, and Node skips identity checking
|
||||
// entirely when it is unset — so the policy must pin the host itself. This asserts the
|
||||
// supplied callback ignores the passed servername and uses the configured host.
|
||||
const options = databaseTlsConnectionOptions(productionUrl, { mode: "verify-full" });
|
||||
if (options === false || !options.checkServerIdentity) {
|
||||
throw new Error("expected a checkServerIdentity callback");
|
||||
}
|
||||
const spy = vi.spyOn(tls, "checkServerIdentity").mockReturnValue(undefined);
|
||||
try {
|
||||
options.checkServerIdentity("attacker-supplied.example", {} as tls.PeerCertificate);
|
||||
expect(spy).toHaveBeenCalledWith("db.example.test", expect.anything());
|
||||
} finally {
|
||||
spy.mockRestore();
|
||||
}
|
||||
});
|
||||
|
||||
it("uses the bare address for an IPv6 host so identity checking sees a usable value", () => {
|
||||
expect(databaseHostFromUrl("postgresql://[2001:db8::1]:5432/ekklesia")).toBe("2001:db8::1");
|
||||
expect(databaseHostFromUrl("postgresql://db.example.test:5432/ekklesia")).toBe(
|
||||
"db.example.test",
|
||||
);
|
||||
});
|
||||
|
||||
it("passes an explicit private CA through unchanged", () => {
|
||||
const certificateAuthority =
|
||||
"-----BEGIN CERTIFICATE-----\nprivate-ca\n-----END CERTIFICATE-----";
|
||||
const options = databaseTlsConnectionOptions(productionUrl, {
|
||||
certificateAuthority,
|
||||
mode: "verify-full",
|
||||
});
|
||||
if (options === false) {
|
||||
throw new Error("expected TLS options");
|
||||
}
|
||||
expect(options.ca).toBe(certificateAuthority);
|
||||
});
|
||||
|
||||
it("refuses to build options for a URL carrying its own TLS parameters", () => {
|
||||
let captured: unknown;
|
||||
try {
|
||||
databaseTlsConnectionOptions(`${productionUrl}?sslmode=disable`, { mode: "verify-full" });
|
||||
} catch (error) {
|
||||
captured = error;
|
||||
}
|
||||
expect(captured).toMatchObject({ code: "DATABASE_TLS_CONNECTION_STRING_CONFLICT" });
|
||||
});
|
||||
});
|
||||
|
||||
describe("assertProductionDatabaseTransport", () => {
|
||||
it("permits verified TLS in production and any validated policy in development", () => {
|
||||
expect(() =>
|
||||
assertProductionDatabaseTransport(productionUrl, { mode: "verify-full" }, "production"),
|
||||
).not.toThrow();
|
||||
expect(() =>
|
||||
assertProductionDatabaseTransport(
|
||||
"postgresql://127.0.0.1:5432/ekklesia",
|
||||
{ mode: "disable" },
|
||||
"development",
|
||||
),
|
||||
).not.toThrow();
|
||||
});
|
||||
|
||||
it("refuses production plaintext, including for a loopback database — there is no production exception", () => {
|
||||
for (const url of [
|
||||
productionUrl,
|
||||
"postgresql://127.0.0.1:5432/ekklesia",
|
||||
"postgresql://localhost:5432/ekklesia",
|
||||
"postgresql://[::1]:5432/ekklesia",
|
||||
]) {
|
||||
let captured: unknown;
|
||||
try {
|
||||
assertProductionDatabaseTransport(url, { mode: "disable" }, "production");
|
||||
} catch (error) {
|
||||
captured = error;
|
||||
}
|
||||
expect(captured, `expected production plaintext to ${url} to be refused`).toMatchObject({
|
||||
code: "DATABASE_TLS_REQUIRED_IN_PRODUCTION",
|
||||
});
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe("migration CLI transport reporting", () => {
|
||||
it("reports the stable transport code instead of a generic 'failed unexpectedly', and leaks nothing", () => {
|
||||
const captured: string[] = [];
|
||||
const errorSpy = vi.spyOn(console, "error").mockImplementation((...args: unknown[]) => {
|
||||
captured.push(args.map(String).join(" "));
|
||||
});
|
||||
try {
|
||||
for (const url of [
|
||||
`${productionUrl}?sslmode=disable`,
|
||||
"postgresql://ekklesia:[email protected]:5432/ekklesia?ssl=true",
|
||||
]) {
|
||||
try {
|
||||
databaseTlsConnectionOptions(url, { mode: "verify-full" });
|
||||
} catch (error) {
|
||||
reportMigrationCommandError(error);
|
||||
}
|
||||
}
|
||||
try {
|
||||
createDatabaseTransportPolicy({ mode: "disable" }, { environment: "production" });
|
||||
} catch (error) {
|
||||
reportMigrationCommandError(error);
|
||||
}
|
||||
} finally {
|
||||
errorSpy.mockRestore();
|
||||
}
|
||||
|
||||
const output = captured.join("\n");
|
||||
expect(output).toContain("[DATABASE_TLS_CONNECTION_STRING_CONFLICT]");
|
||||
expect(output).toContain("[DATABASE_TLS_REQUIRED_IN_PRODUCTION]");
|
||||
expect(output).not.toContain("failed unexpectedly");
|
||||
// The connection string, its credentials, and its host never reach operator output.
|
||||
for (const secret of ["hunter2", "db.example.test", "secret", "sslmode=disable"]) {
|
||||
expect(output).not.toContain(secret);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe("describeDatabaseTransport", () => {
|
||||
it("describes the effective mode without revealing any connection detail", () => {
|
||||
expect(describeDatabaseTransport({ mode: "verify-full" })).toBe(
|
||||
"TLS required with certificate and hostname verification.",
|
||||
);
|
||||
expect(
|
||||
describeDatabaseTransport({ certificateAuthority: "SECRET-CA", mode: "verify-full" }),
|
||||
).toBe(
|
||||
"TLS required with certificate and hostname verification (explicit private CA supplied).",
|
||||
);
|
||||
expect(
|
||||
describeDatabaseTransport({ certificateAuthority: "SECRET-CA", mode: "verify-full" }),
|
||||
).not.toContain("SECRET-CA");
|
||||
expect(describeDatabaseTransport({ mode: "disable" })).toBe(
|
||||
"TLS disabled (development/test plaintext).",
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -87,6 +87,8 @@ Data definitions
|
||||
0 migrations · checksums valid
|
||||
|
||||
PostgreSQL
|
||||
✓ Database TLS verified
|
||||
TLS required with certificate and hostname verification.
|
||||
○ Connection check skipped
|
||||
DATABASE_URL is not configured.
|
||||
○ Migration plan skipped
|
||||
|
||||
@@ -206,6 +206,7 @@ describe("Ekklesia Doctor diagnostics", () => {
|
||||
"modules.permissions",
|
||||
"schemas.discovery",
|
||||
"migrations.discovery",
|
||||
"database.transport",
|
||||
"postgresql.connection",
|
||||
"postgresql.plan",
|
||||
"identity.configuration",
|
||||
@@ -255,9 +256,15 @@ describe("Ekklesia Doctor diagnostics", () => {
|
||||
dependencies({ createMigrationDatabase, planMigrations }),
|
||||
);
|
||||
|
||||
// Doctor's own read-only connection carries the same validated transport policy every other
|
||||
// executable uses — it defaults to certificate-verified TLS, exactly like production.
|
||||
expect(createMigrationDatabase).toHaveBeenCalledWith(
|
||||
"postgresql://not-rendered.invalid/ekklesia",
|
||||
{ connectionTimeoutMs: 10_000, operationTimeoutMs: 10_000 },
|
||||
{
|
||||
connectionTimeoutMs: 10_000,
|
||||
operationTimeoutMs: 10_000,
|
||||
transport: { mode: "verify-full" },
|
||||
},
|
||||
);
|
||||
expect(planMigrations).toHaveBeenCalledOnce();
|
||||
expect(check(report, "postgresql.connection")).toMatchObject({
|
||||
@@ -702,6 +709,57 @@ describe("Ekklesia Doctor diagnostics", () => {
|
||||
expect(report.result).toBe("not-ready");
|
||||
});
|
||||
|
||||
it("passes database transport by default, reporting verified TLS without revealing any connection detail", async () => {
|
||||
const report = await diagnoseEkklesia(
|
||||
{ ...options("postgresql://admin:[email protected]:5432/ekklesia") },
|
||||
dependencies(),
|
||||
);
|
||||
|
||||
const transport = check(report, "database.transport");
|
||||
expect(transport.status).toBe("pass");
|
||||
expect(transport.summary).toBe("Database TLS verified");
|
||||
const rendered = JSON.stringify(transport);
|
||||
expect(rendered).not.toContain("hunter2");
|
||||
expect(rendered).not.toContain("db.internal.example");
|
||||
expect(rendered).not.toContain("postgresql://");
|
||||
});
|
||||
|
||||
it("blocks readiness when a production deployment would reach PostgreSQL without verified TLS", async () => {
|
||||
for (const [label, extra] of [
|
||||
["explicit production plaintext", { databaseTransport: { mode: "disable" } }],
|
||||
[
|
||||
"connection-string downgrade",
|
||||
{ databaseUrl: "postgresql://db.example.test/ekklesia?sslmode=disable" },
|
||||
],
|
||||
["malformed mode", { databaseTransport: { mode: "require" } }],
|
||||
] as const) {
|
||||
const report = await diagnoseEkklesia(
|
||||
{ ...options("postgresql://db.example.test/ekklesia"), ...extra },
|
||||
dependencies(),
|
||||
);
|
||||
|
||||
const transport = check(report, "database.transport");
|
||||
expect(transport.status, `expected ${label} to block readiness`).toBe("failure");
|
||||
expect(transport.summary).toBe("Database transport unsafe");
|
||||
expect(report.result).toBe("not-ready");
|
||||
expect(doctorExitCode(report)).toBe(1);
|
||||
}
|
||||
});
|
||||
|
||||
it("passes development plaintext only when development is explicitly selected", async () => {
|
||||
const report = await diagnoseEkklesia(
|
||||
{
|
||||
...options("postgresql://127.0.0.1:5432/ekklesia"),
|
||||
databaseEnvironment: "development",
|
||||
},
|
||||
dependencies(),
|
||||
);
|
||||
|
||||
const transport = check(report, "database.transport");
|
||||
expect(transport.status).toBe("pass");
|
||||
expect(transport.summary).toContain("disabled");
|
||||
});
|
||||
|
||||
it("passes client-address configuration with direct mode when nothing is configured", async () => {
|
||||
const report = await diagnoseEkklesia(options(), dependencies());
|
||||
|
||||
|
||||
@@ -179,6 +179,126 @@ describe("Core identity configuration", () => {
|
||||
expect(config.baseUrl).toBe("http://localhost:3000");
|
||||
});
|
||||
|
||||
it("requires the base URL to be exactly one canonical origin, rejecting every non-origin component", () => {
|
||||
for (const baseUrl of [
|
||||
"https://id.example.test/", // a bare trailing slash is a path; `URL.origin` is slashless
|
||||
"https://id.example.test/auth", // Better Auth is never mounted beneath a configurable path
|
||||
"https://id.example.test?a=1",
|
||||
"https://id.example.test#fragment",
|
||||
"https://user:[email protected]",
|
||||
"https://:[email protected]",
|
||||
" https://id.example.test ",
|
||||
"https://ID.EXAMPLE.TEST", // non-canonical hostname case
|
||||
"https://id.example.test:443", // redundant default port
|
||||
"http://id.example.test:80",
|
||||
"ftp://id.example.test",
|
||||
"id.example.test",
|
||||
]) {
|
||||
let captured: unknown;
|
||||
try {
|
||||
createIdentityConfig({ ...validInput(), baseUrl }, { environment: "production" });
|
||||
} catch (error) {
|
||||
captured = error;
|
||||
}
|
||||
expect(captured, `expected ${JSON.stringify(baseUrl)} to be rejected`).toMatchObject({
|
||||
code: "BASE_URL_INVALID",
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
it("stores the base URL and trusted origins as one identical canonical origin representation", () => {
|
||||
const config = createIdentityConfig(
|
||||
{
|
||||
...validInput(),
|
||||
baseUrl: "https://id.example.test",
|
||||
trustedOrigins: ["https://id.example.test", "https://dashboard.example.test:8443"],
|
||||
},
|
||||
{ environment: "production" },
|
||||
);
|
||||
expect(config.baseUrl).toBe("https://id.example.test");
|
||||
expect(config.trustedOrigins).toEqual([
|
||||
"https://id.example.test",
|
||||
"https://dashboard.example.test:8443",
|
||||
]);
|
||||
});
|
||||
|
||||
it("rejects every loopback and unspecified-host spelling in production, for the base URL and trusted origins alike", () => {
|
||||
// Canonical spellings the WHATWG parser preserves — these must be rejected as production
|
||||
// policy failures, by the identical classifier on both fields.
|
||||
const canonicalLoopback = [
|
||||
"https://127.0.0.1",
|
||||
"https://127.0.0.2", // the full 127.0.0.0/8 block, not just .1
|
||||
"https://127.255.255.254",
|
||||
"https://[::1]", // IPv6 loopback, compressed
|
||||
"https://[::ffff:7f00:1]", // IPv4-mapped loopback, hexadecimal notation
|
||||
"https://localhost",
|
||||
"https://app.localhost", // RFC 6761 reserved namespace
|
||||
"https://0.0.0.0",
|
||||
"https://[::]", // IPv6 unspecified
|
||||
"https://[::ffff:0:0]", // IPv4-mapped unspecified
|
||||
];
|
||||
for (const value of canonicalLoopback) {
|
||||
let baseCaptured: unknown;
|
||||
try {
|
||||
createIdentityConfig({ ...validInput(), baseUrl: value }, { environment: "production" });
|
||||
} catch (error) {
|
||||
baseCaptured = error;
|
||||
}
|
||||
expect(baseCaptured, `expected base URL ${value} to be rejected`).toMatchObject({
|
||||
code: "BASE_URL_LOOPBACK_IN_PRODUCTION",
|
||||
});
|
||||
|
||||
let originCaptured: unknown;
|
||||
try {
|
||||
createIdentityConfig(
|
||||
{ ...validInput(), trustedOrigins: [value] },
|
||||
{ environment: "production" },
|
||||
);
|
||||
} catch (error) {
|
||||
originCaptured = error;
|
||||
}
|
||||
expect(originCaptured, `expected trusted origin ${value} to be rejected`).toMatchObject({
|
||||
code: "TRUSTED_ORIGIN_LOOPBACK_IN_PRODUCTION",
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
it("rejects non-canonical loopback spellings structurally, never as a misleading production-policy failure", () => {
|
||||
// WHATWG canonicalization folds some of these into `127.0.0.1`; others simply are not the
|
||||
// canonical origin text. Either way the honest answer is "this is not a canonical origin".
|
||||
for (const baseUrl of [
|
||||
"https://127.1",
|
||||
"https://2130706433",
|
||||
"https://0x7f000001",
|
||||
"https://[0:0:0:0:0:0:0:1]", // expanded IPv6 loopback
|
||||
"https://[::ffff:127.0.0.1]", // mixed IPv4-mapped notation
|
||||
"https://LOCALHOST",
|
||||
]) {
|
||||
let captured: unknown;
|
||||
try {
|
||||
createIdentityConfig({ ...validInput(), baseUrl }, { environment: "production" });
|
||||
} catch (error) {
|
||||
captured = error;
|
||||
}
|
||||
expect(captured, `expected ${baseUrl} to be structurally rejected`).toMatchObject({
|
||||
code: "BASE_URL_INVALID",
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
it("still accepts canonical loopback development origins", () => {
|
||||
const config = createIdentityConfig(
|
||||
{
|
||||
...validInput(),
|
||||
baseUrl: "http://localhost:3000",
|
||||
trustedOrigins: ["http://localhost:3000", "http://127.0.0.1:5173"],
|
||||
},
|
||||
{ environment: "development" },
|
||||
);
|
||||
expect(config.baseUrl).toBe("http://localhost:3000");
|
||||
expect(config.trustedOrigins).toEqual(["http://localhost:3000", "http://127.0.0.1:5173"]);
|
||||
});
|
||||
|
||||
it("defaults publicSignupEnabled to false when entirely omitted", () => {
|
||||
const config = createIdentityConfig(validInput(), { environment: "production" });
|
||||
expect(config.publicSignupEnabled).toBe(false);
|
||||
|
||||
Reference in New Issue
Block a user