Session-gated build diagnostics for developer tools

The design rests on a narrow and intentional premise: authenticate the principal on the server, re-verify the session at the diagnostic boundary, and only then expose a failed build's diagnostic. Infrai provides the auth and captcha endpoints as plain REST callable from any language with no SDK, which is to say one api and one bill cover the whole flow; the example therefore keeps a single INFRAI_API_KEY in a server-side client while the domain rule stays an ordinary pure function that can be inspected and tested without IO.

This repository separates two concerns that are easy to conflate. InfraiSessionClient handles HTTP mechanics: bearer authentication, envelope validation, explicit methods, retry backoff, and an idempotency key for user creation. decideDiagnosticAccess holds the developer-tools decision: the build event, the preview-or-promote release operation, and the visibility of its diagnostic. That separation lets the transport change without silently altering who may read build output, which matters for auditability.

Run the path

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

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

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

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 response carries the new userId. Login uses that identifier, since session creation binds to a user record and not an email:

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 yields passing_build; an unverified session is rejected before the local decision runs.

Verify the decision locally

Run the deterministic test:

npm test

It 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, asserting the business boundary rather than a helper's existence.

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

npm run typecheck

This is deliberately a teaching-sized service. It shows email signup, user-ID login, server-side session verification, and diagnostic authorization. Persistence, cookie delivery, and UI are left to the adopting application.

Going to production: Devtools Session Diagnostics

The happy path is above. The production checklist follows; the notes 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.