Airlock Pattern B consumer (cross-apex handoff sign-in for a Next.js app)

notes

Field-derived 2026-10-15 from chronicle-cat/app#44. The origin is registered by airlock#105 (merged and deployed
2026-10-12).

  THE PACKAGE IS NOT PUBLISHED. @devarno-cloud/airlock-consumer returned 404 from npm.pkg.github.com. The gh token
  lacked read:packages, so a permissions 404 is not fully ruled out; re-check with a read:packages token. The
  package README lists publishing as a TODO. The precedent is to vendor it, as choco-hq does in
  services/cho-co-web/src/lib/airlock-consumer/VENDORED.md. Copy src/{types,lib/jwt,createCallbackRoute,
  createCrossApexMiddleware}.ts from devarno-cloud/packages/airlock-consumer and record the source SHA in
  VENDORED.md. Rewrite the .js import extensions with
    sed -i -E "s#from '(\./[^']+|\.\./[^']+)\.js'#from '\1'#g"
  Keep the consumer's config outside the vendored directory. Never hand-roll a verifier instead.

  THE CONTRACT LIVES IN devarno-cloud/airlock src/routes/handoff.ts. The request is
  GET /api/auth/handoff?return=<url>, and the return origin must be in handoff_consumers. Token claims: aud is the
  return URL's ORIGIN; iss is https://airlock.devarno.cloud in prod; then sub, email, name, role, an optional org,
  and nonce. TTL is 60 seconds. Failures return ?error=session_invalid or ?error=signing_failed with no token.
  Probe registration with
    curl -o /dev/null -w '%{http_code}' 'https://airlock.devarno.cloud/api/auth/handoff?return=<encoded callback>'
  302 means registered; 400 means not registered.

  AIRLOCK SIGN-OUT WILL NOT RETURN USERS TO YOUR APEX. /auth/sign-out?callbackURL= only honours *.devarno.cloud
  (sanitizeCallbackURL in src/routes/auth-ui.ts). Clear the local cookie first, then redirect; the user ends on
  airlock's page.

  KEEP TOKEN-EXCHANGE APIs OUT OF THE MIDDLEWARE MATCHER. The vendored middleware sends unauthenticated requests to
  airlock with a 3xx, and a fetch() that follows it dies on CORS. Have the API return 401 JSON itself. Prefer a
  narrow matcher (e.g. ['/documents/:path*', '/login']) over the package's catch-all with publicPaths.

  FACTORIES READ ENV WHEN THEY ARE BUILT. Build createCallbackRoute and createCrossApexMiddleware per request, so env
  is read at runtime and tests can vary it. Add your own fail-closed check (503, no cookie) for each extra secret.
  The callback only checks SESSION_SECRET itself.

  AUTH_DISABLED IS NOT GATED TO PRODUCTION. The package README says production ignores it. createCrossApexMiddleware
  never checks NODE_ENV. It is safe only if every token mint independently requires a real session cookie. Assert
  that in a test.

  TESTING. Put `// @vitest-environment node` on route and middleware tests. jose's node build fetches the JWKS over
  node:http, so stubbing fetch does nothing. Serve a real JWKS from http.createServer and point AIRLOCK_URL at it
  (chronicle-cat/app src/__tests__/airlockFixtures.ts). Call handlers with new NextRequest(url, {headers:{cookie}}).
  A passing middleware response carries x-middleware-next: 1. Cover the open-redirect `next`, an aud mismatch, an iss
  mismatch, a missing token, airlock's ?error, and each missing or short secret.

  PREVIEW DEPLOYS BOUNCE TO PROD. The callback resolves `next` against the configured apex URL, not the request
  host. Set the apex env per preview.

  CHECK THE COMMIT IDENTITY. Clones under ~/code/workspace/clones may carry repo-level
  user.email=fleet@devarno.cloud. On a repo whose fleets_allowed is [], decide before committing whether that
  identity is acceptable.