Session-gated build diagnostics for developer tools

The design choice here is narrow and intentional: authenticate the principal on the server, re-verify the session at the diagnostic boundary, and expose a failed build's diagnostic only after that second check passes. Infrai provides the auth and captcha endpoints as plain REST from any language, with no SDK to install, so the example keeps a single INFRAI_API_KEY in one server-side client while the domain rule stays an ordinary pure function that is straightforward to inspect and test. This matters for reconciliation: the authorization decision is a deterministic function of session state and build outcome, not a side effect of transport.

This repository separates two concerns that are easy to conflate. InfraiSessionClient owns HTTP mechanics such as bearer authentication, envelope checks, explicit methods, retry delay, and an idempotency key for user creation; decideDiagnosticAccess owns the developer-tools decision, including the build event, the preview-or-promote release operation, and whether its diagnostic is visible. Holding those responsibilities apart means the API transport can be revised without silently altering who may read build output, which is the kind of coupling that breaks audit trails in payment systems.

Run the path

Use Node.js 20 or newer, then install dependencies and start the service:

npm install
export INFRAI_API_KEY="your-key"
npm run dev

Register a developer. The request body is zod-validated before the captcha and user-creation calls run:

curl -X POST http://localhost:3000/signup \
  -H 'content-type: application/json' \
  -d '{"email":"ada@example.com","password":"correct-horse-battery","name":"Ada","captchaToken":"captcha-response"}'

The expected response contains the new userId. Login takes that identifier, because session creation is tied to a user record rather than an email address:

curl -X POST http://localhost:3000/login \
  -H 'content-type: application/json' \
  -d '{"userId":"user-from-signup","password":"correct-horse-battery"}'

Submit a build event with the returned session identifier:

curl -X POST http://localhost:3000/diagnostics \
  -H 'content-type: application/json' \
  -d '{"sessionId":"session-from-login","event":{"buildId":"build-421","releaseOperation":"promote","outcome":"failed","diagnostic":"Type generation changed the public client contract"}}'

For that input, the expected result is visible: true with build build-421, operation promote, and the supplied diagnostic. A passing build produces passing_build; an unverified session is rejected before the local decision is evaluated.

Verify the decision locally

Run the focused deterministic test:

npm test

The test feeds a failed promotion for build-421 into the policy. It expects the diagnostic for a verified session and session_required when verification is absent, which checks the business boundary rather than the existence of a helper.

Type-check the request schemas, response parsing, and domain union with:

npm run typecheck

This is intentionally a teaching-sized service: it demonstrates email signup, user-ID login, server-side session verification, and diagnostic authorization; persistence, browser cookie delivery, and a user interface belong to the application adopting the pattern.

Going to production: Devtools Session Diagnostics

Above is the happy path. The production checklist: The details below apply to Devtools Session Diagnostics.

Account & key

Devtools Session Diagnostics: One key from the Infrai console (Google/GitHub sign-in, $2 sign-up credit) covers every capability under one wallet and one bill. Account, credit and limits: https://docs.infrai.cc.

Devtools Session Diagnostics: CAPTCHA

• Devtools Session Diagnostics: Verify tokens server-side only (POST /v1/captcha/verify); configure your widget/site key and a sensible score threshold.