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]>

docs/development/testing.md

@@ -14,7 +14,9 @@ module migration discovery, identity schema drift detection, formatting, linting
 Migration-runner unit tests use a narrow database/session port to prove deterministic planning,
 approval, transaction orchestration, cleanup, and sanitized errors. They do not claim to prove
 PostgreSQL behavior. Identity unit tests cover branded opaque-ID contracts, principal shapes,
-configuration validation (secret, base URL, and trusted-origin rules), bounded/validated
+configuration validation (secret rules, canonical-origin-only base URL and trusted origins, and the
+full loopback/unspecified classifier production rejects — `.localhost`, all of `127.0.0.0/8`,
+`0.0.0.0`, `::1` compressed and expanded, `::`, and IPv4-mapped forms), bounded/validated
 connection and operation (`query_timeout`/`statement_timeout`) database timeouts, the Core identity
 runtime (explicit construction, exact schema mapping, only email/password and rate limiting
 enabled, an explicit `advanced.disableCSRFCheck`/`disableOriginCheck: false` pair, an explicit
@@ -22,9 +24,12 @@ error-only sanitized logger that strips Better Auth's own message and arguments
 they contain, pinned 8–128 password-length bounds, sanitized failures, exact whole-name
 session-cookie detection that never fires on a prefixed, suffixed, or differently-cased lookalike,
 and that a broken session store during principal resolution is never silently reported as anonymous
-while an unrelated cookie performs no identity database work at all), and Core migration discovery
-(deterministic ordering, the reserved `core` identity, and collision rejection) — all without a
-live database. `apps/api`'s own unit tests cover its pure Hono app factory (route shapes, module
+while an unrelated cookie performs no identity database work at all), the PostgreSQL transport
+policy (`core/tests/database-transport.test.ts`: mode validation including every loose or aliased
+spelling, production's plaintext refusal with no loopback exception, connection-string
+TLS-parameter rejection, and that no configuration path yields `rejectUnauthorized: false` or leaks
+CA material into an error), and Core migration discovery (deterministic ordering, the reserved
+`core` identity, and collision rejection) — all without a live database. `apps/api`'s own unit tests cover its pure Hono app factory (route shapes, module
 route mounting/enforcement/CORS/response sanitization, CORS allow/deny/preflight, deterministic 404
 and sanitized error responses), its runtime configuration, its idempotent shutdown lifecycle
 (concurrent callers share one server-close-then-module-runtime-stop-then-pool-close promise; a
@@ -125,6 +130,20 @@ completes and is independently verifiable, through the harness's own administrat
 never the API's own pool — before that pool closes. See
 [ADR 0016](../architecture/decisions/0016-module-database-access.md).
 
+A fourth dedicated suite (`core/tests/database-tls.integration.ts`, included in the same
+`pnpm test:migrations:integration` run) proves the production PostgreSQL transport policy against a
+real TLS-enabled PostgreSQL rather than against the shape of an options object: a trusted
+certificate whose identity matches the host connects and is confirmed encrypted through
+`pg_stat_ssl`; a certificate that does not chain to the configured CA is refused
+(`UNABLE_TO_VERIFY_LEAF_SIGNATURE`); the same server reached through an address its certificate does
+not cover is refused (`ERR_TLS_CERT_ALTNAME_INVALID`); the identical connection *without* the
+policy's pinned `checkServerIdentity` succeeds, which is the concrete gap the policy closes; and
+`verify-full` cannot be satisfied by a plaintext-only endpoint. Every CA, certificate, and private
+key is generated at test runtime into a temporary directory and deleted afterwards — **no private
+key material is ever committed to this repository** — and the disposable container is removed in
+`afterAll` even when an assertion fails. See
+[ADR 0018](../architecture/decisions/0018-identity-session-resolution-and-database-transport.md).
+
 CI runs the same command in the dedicated `migration-smoke` job. After this change is merged, add
 the following pull-request status context to `main` branch protection: