feat(verify): an adapter conformance suite any server adapter can run

[Bccorb]

Closes #246. Part of fells-code/seamless-auth-api#371.

Why

Server adapters hold the auth API's tokens in cookies, so each one is part of the security surface. Only the Node adapters had parity tests, inside seamless-auth-server. The adapter specs here covered the happy paths and nothing about cookies, refresh, bearer transport or what reaches the API. A Go, Rust or Python adapter had nothing to prove itself against.

What changes

The contract. verify/CONFORMANCE.md states what a reference app on any adapter must serve:

• GET / for health
• the adapter at /auth
• GET /api/me behind the adapter's own guard
• GET /__captured/:recipient, fed by the adapter's external-delivery hook
• one trusted proxy hop

It also gives the configuration, including AUTH_SERVER_ISSUER for an app that reaches the API through a published port, and every behaviour the specs check.

Six new specs in verify/harness/adapter/. They run against the Express and Fastify reference apps on every seamless verify.

Spec	Checks
cookieAttributes	HttpOnly; Secure; SameSite=None; Path=/ and Max-Age equal to the API's lifetimes; clearing on logout; no token or refreshToken in any cookie-transport body
refreshRotation	Sign-in from the refresh cookie alone with both cookies rotating; concurrent requests on one refresh cookie all succeed; a used refresh cookie is refused after the 5 second reuse window; POST /auth/refresh returns no tokens
bearerTransport	Tokens in bodies and no cookies; the access token accepted by /auth/users/me and /api/me; refresh rotation and reuse; logout ends the session
protectedEndpoint	/api/me refuses no session and an altered cookie, and sees the signed-in user
errorPassthrough	A validation 400 keeps its body; no session answers 401 with an error code; an unknown route answers 404
clientForwarding	The auth API records the browser's address and user agent against the user's events, read back through the admin API

seamless verify --adapter-url=<url> starts only Postgres and the auth API, then runs the same specs as a new conformance Playwright project against a reference app the caller started. It skips packing the Node adapters and the browser layer, and exits 1 when the app fails.

Reference apps

• They trust one proxy hop, and each virtual user arrives with its own X-Forwarded-For and User-Agent. That is what makes forwarding checkable, and it gives each user its own rate-limit bucket on the API, which removes the shared per-IP OTP cap that used to constrain these specs.
• Fastify uses a one-hop trust function, because Fastify 5 ignores a numeric trustProxy.
• Both serve /api/me and accept AUTH_SERVER_ISSUER.
• They pin @seamless-auth/express ^0.19.1 and @seamless-auth/fastify ^0.10.1. The old ^0.16.0 and ^0.7.0 pins meant the daily released smoke test was testing adapters several minors old.

Found by the suite

• fix(fastify): requireAuth cannot read the session cookie on routes outside the plugin seamless-auth-server#207: Fastify's requireAuth refused every cookie session on routes outside the plugin. Fixed in fix(fastify): read the session cookie on routes outside the plugin seamless-auth-server#209.
• docs(fastify): an explicit trustProxy hop count no longer forwards the client IP seamless-auth-server#208: Fastify 5 ignores the numeric trustProxy our README recommends, so Fastify adopters forward the proxy's address as the client IP. Docs fix pending.

Before merging

• Conformance CI here runs the specs against seamless-auth-server main. The Fastify /api/me cookie case fails until fix(fastify): read the session cookie on routes outside the plugin seamless-auth-server#209 merges.
• The daily released smoke test will fail on that case and on the token-in-body case until the adapter releases containing test(conformance): cover CLI commands, bearer transport, the dashboard and types PRs #209 and chore: scaffold from seamless-templates v0.15.0 #206 are published. That is accurate: the released adapters have both problems.

Checks

• npm test: 57 files, 1175 passed. That includes 4 new verify tests for --adapter-url: services started, project and environment, no packing with --local, exit 1 on failure, and URL validation.
• npm run build passes.
• Real stack, with the API from main and the adapters built from fix(fastify): read the session cookie on routes outside the plugin seamless-auth-server#209:
  • adapter and adapter-fastify projects: 48 of 48, three runs in a row.
  • conformance project against the Express reference app running on the host through AUTH_SERVER_ISSUER, the setup an external adapter uses: 24 of 24.

Not covered yet: a non-JSON error body from the API, such as a plaintext 429. It needs a fault-injecting proxy between the adapter and the API, and CONFORMANCE.md says so.