feat: expose core identity transport

docs/development/testing.md

@@ -13,11 +13,16 @@ These commands exercise package tests, repository boundaries, type checking, off
 module migration discovery, identity schema drift detection, formatting, linting, and builds.
 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 principal/opaque-ID contracts, configuration
-validation (secret, base URL, and trusted-origin rules), the Better Auth construction boundary
-(explicit construction, exact schema mapping, no unexpected provider or plugin, sanitized
-failures), and Core migration discovery (deterministic ordering, the reserved `core` identity, and
-collision rejection) — all without a live database.
+PostgreSQL behavior. Identity unit tests cover branded opaque-ID contracts, principal shapes,
+configuration validation (secret, base URL, and trusted-origin rules), the Core identity runtime
+(explicit construction, exact schema mapping, only email/password and rate limiting enabled,
+sanitized failures, and that a database outage during principal resolution is never silently
+reported as anonymous), 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, CORS allow/deny/preflight, deterministic 404 and sanitized
+error responses), its runtime configuration, and that importing any of its modules — including the
+executable server module without calling its exported `main` — never reads the environment,
+connects to PostgreSQL, or starts a server.
 
 `pnpm verify` is intentionally Docker-free. It never plans or applies migrations against a live
 database.
@@ -52,6 +57,22 @@ staying byte-for-byte unchanged once Core is introduced, and a later module migr
 rolling back cleanly without damaging the already-committed Core identity migration or leaking the
 advisory lock.
 
+A second dedicated suite (`apps/api/tests/api-http.integration.ts`, included in the same
+`pnpm test:migrations:integration` run) starts the real `apps/api` HTTP server against a freshly
+migrated disposable database and exercises it with real HTTP requests: public sign-up (with no
+automatic session, per `autoSignIn: false`), explicit sign-in producing a host-only
+`HttpOnly`/`SameSite=Lax`/secure session cookie, `/api/v1/principal` for both the authenticated and
+anonymous shapes, sign-out actually invalidating the session, a malformed or missing cookie
+resolving as anonymous, duplicate sign-up creating no second identity row, two distinct accounts
+producing identical principal shapes with no elevation and no owner/role/permission data at the
+database level, no plaintext password ever stored, CORS never returning an allow-origin header for
+an untrusted origin, Better Auth's handler being unreachable outside `/api/auth/*`, a database
+outage during principal resolution producing a sanitized `503` rather than a false anonymous `200`,
+starting the API against an unmigrated database creating no tables at all, and a clean listener/pool
+shutdown. See [ADR 0011](../architecture/decisions/0011-identity-http-transport-and-public-enrollment.md)
+for one CSRF/origin guarantee that was verified manually against the real server but could not be
+reproduced reliably inside this test runner, and is documented rather than silently asserted.
+
 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: