Skip to content
rachel/tessera
File

Blob: AGENTS.md

Markdown99 lines

AGENTS.md

Operating Rules

  • Product name: tessera, lowercase in code, comments, docs, and user-facing copy unless grammar requires otherwise.
  • Ask first: "Can we do more with less code?" Prefer the smallest correct change that preserves clarity, performance, and security.
  • If a local fix creates known fragility or a security-sensitive dead end, pay the structural cost now. Optional refactors should be proposed, not made by default.
  • Read before editing. For non-local changes, inspect the target file plus a caller, consumer, sibling module, or focused test.
  • Work from the live source tree. Docs and prior context are secondary when they drift.
  • Keep edits scoped. Multiple agents may be working in parallel, so never overwrite or revert unrelated changes.
  • Assume the dev server may already be running. Do not start npm run dev unless asked, clearly needed, or no relevant server is running.
  • Prefer explicit code over clever code. Reuse existing helpers, route patterns, schemas, UI primitives, and auth utilities before adding new ones.
  • Preserve the src/client/, src/worker/, generated-code, and migration boundaries.
  • Prefer the @/ alias for imports from src.
  • For current Cloudflare behavior, prefer official Cloudflare docs via cloudflare-docs MCP when available. For package signatures, read local .d.ts files first.

Source Of Truth

  • README.md: architecture and local quickstart.
  • OPERATOR.md: deployment, secrets, and production operation.
  • The live source tree is authoritative when docs drift.
  • docs/phase-1-design.md and docs/tessera-phase-1-design.md: historical security-sensitive design context for issuer, callbacks, cookies, signing keys, invites, and sub claims. Confirm endpoint paths, env vars, schema details, and generated output against current source before treating them as current.
  • src/worker/db/schema/: D1 schema source. drizzle/d1/ is generated by npm run db:generate.
  • src/worker/auth/cli-config.ts: Better Auth CLI source. src/worker/db/schema/auth.ts is generated by npm run auth:generate.
  • worker-configuration.d.ts, dist/, and .wrangler/ are generated outputs. Regenerate them; do not hand-edit them.

Project Map

tessera is a Cloudflare Workers OIDC provider with a React frontend.

  • Worker: src/worker/index.ts mounts Hono; auth/ configures Better Auth; api/ owns tessera routes; db/ owns Drizzle; middleware/ owns auth gates, origin checks, security headers, admin allowlisting, and rate limiting; services/ owns crypto, Turnstile, and URL helpers.
  • Client: src/client/app.tsx and main.tsx boot the React app; pages live in pages/, UI in components/, admin-specific components in components/admin/, hooks in hooks/, HTTP/auth/navigation helpers in lib/, and styles in styles/app.css.
  • Tests: worker and client Vitest specs in tests/worker/ and tests/client/, Playwright in tests/e2e/, local OIDC simulators in scripts/test-client/ and scripts/test-consent/.
  • Runtime config and generated output: wrangler.jsonc, drizzle/d1/, worker-configuration.d.ts, dist/, and .wrangler/.

Security And Runtime Invariants

  • tessera is invite-only. Do not introduce open signup.
  • Stable opaque sub claims are core product behavior. Account linking, issuer URLs, callback paths, cookie behavior, signing keys, token claims, and token lifetimes are security-sensitive.
  • D1 is authoritative for users, accounts, sessions, OAuth clients, signing keys, invites, roles, and bans. Better Auth state stays in D1.
  • /api/*, /.well-known/*, and /healthz must run through the Worker before static asset handling. OAuth endpoints live under /api/auth/oauth2/*; JWKS is /api/auth/jwks.
  • OIDC discovery must advertise endpoints and JWKS paths that the Worker actually serves.
  • Turnstile-gated flows fail closed on missing config, missing tokens, and failed verification.
  • Sign-in, social sign-in, invite acceptance, and /api/auth/* remain rate-limited through RL_AUTH / RL_API; public JWKS and auth utility endpoints stay explicitly exempt.
  • Admin routes use requireAdmin; protected user routes use requireUser.
  • Keep OAuth client secret creation, rotation, and revocation fail-closed.
  • Do not log secrets, bearer tokens, OAuth client secrets, session cookies, password material, invite tokens, signing keys, or raw Turnstile responses.

Change Guidance

  • Worker routes belong in src/worker/api/ and are mounted from src/worker/index.ts.
  • Keep reusable worker logic in helpers or middleware rather than route handlers.
  • Reuse src/worker/http.ts for HTTP errors/responses, src/worker/config.ts for base URL and issuer logic, src/worker/services/turnstile.ts for Turnstile, and src/worker/middleware/rate-limit.ts for rate limiting.
  • If request or response shapes change, update the worker route, matching client helper in src/client/lib/, and affected tests together.
  • Frontend changes should reuse src/client/components/ui/ and preserve accessible semantics, keyboard behavior, focus states, labels, and contrast.
  • Treat TurnstileWidget and /api/config as the authoritative client Turnstile path.
  • Update src/worker/db/schema/ before generating D1 migrations. Do not hand-edit drizzle/d1/ unless explicitly asked.
  • Cross-check README.md, OPERATOR.md, current source, and focused tests before shipping security-sensitive auth or OIDC changes. Treat phase design docs as context, not current implementation authority.

Commands

  • npm run dev: start Vite + Cloudflare Worker dev.
  • npm run build: production bundle in dist/.
  • npm run typecheck: generate Worker types and run TypeScript checks.
  • npm test: run Vitest with the Cloudflare worker pool.
  • npm run test:e2e: run Playwright e2e coverage.
  • npm run test:client: run the local OIDC RP simulator.
  • npm run test:consent: run the local consent-flow simulator.
  • npm run db:generate: generate D1 migrations.
  • npm run db:migrate: apply remote D1 migrations.
  • npm run db:migrate:local: apply local D1 migrations.
  • npm run db:seed-initial-user / npm run db:seed-initial-user:local: seed the bootstrap invite.
  • npm run auth:generate: regenerate Better Auth schema.
  • npm run format:check / npm run format: check or apply Prettier formatting.

Validation

  • Run npm run typecheck for most code changes.
  • Prefer focused tests/worker/*.test.ts for worker, auth, invite, OIDC, Turnstile, rate-limit, and service behavior changes.
  • Do not run the full npm test suite by default. It includes Argon2id coverage and is intentionally slow; run it only when broad cross-file worker regression coverage is clearly needed or explicitly requested.
  • Run npm run build when changing route wiring, bundling, static assets, wrangler.jsonc, or runtime registration.
  • Run npm run test:e2e or a focused Playwright spec for browser-visible auth, invite, account, admin, or consent flows.
  • Run npm run test:client after OIDC discovery, authorize/token, PKCE, client registration, or claim-shape changes.
  • Run npm run test:consent after consent-page or consent-route changes.
  • If an appropriate check cannot be run, state why.

Primary References

  • Worker entry: src/worker/index.ts
  • Auth setup: src/worker/auth/index.ts, src/worker/auth/cli-config.ts
  • API handlers: src/worker/api/
  • Auth middleware: src/worker/middleware/auth.ts
  • D1 schema: src/worker/db/schema/
  • Issuer/base URL: src/worker/config.ts
  • Turnstile/rate limits: src/worker/services/turnstile.ts, src/worker/middleware/rate-limit.ts
  • Client app: src/client/app.tsx, src/client/main.tsx
  • Client helpers and UI: src/client/lib/, src/client/components/ui/
  • Tests: tests/worker/, tests/client/, tests/e2e/, scripts/test-client/, scripts/test-consent/