admin: customer notes table + read-only impersonation JWT + RequireWritable middleware

[mastermanas805]

Summary

Two related admin surfaces for the founder's customer-management drawer:

• Notes — free-text per-team admin annotations. Migration 024 +
  three handlers behind RequireAdmin: GET/POST /admin/customers/:team_id/notes
  and DELETE /admin/notes/:note_id. Hard delete (notes are reversible
  by re-typing).
• Impersonation — POST /admin/customers/:team_id/impersonate
  mints a 10-minute JWT carrying read_only=true + impersonated_by=<admin email>.
• RequireWritable middleware — new gate that 403s POST/PATCH/PUT/DELETE
  on every /api/v1/* route, the /deploy group, and every top-level
  mutating provisioning endpoint (/db/new, /cache/new, …, /stacks/*)
  whenever the JWT carries read_only=true. GETs fall through —
  view-as-customer is the whole point.

Every impersonation issuance writes an audit_log row with
kind=admin.impersonation_started. /auth/me surfaces the impersonation
state so the dashboard can render the banner.

Read-only is irrevocable for the session lifetime. The
AgentActionReadOnlySession agent_action sentence satisfies the U3
contract and is exercised by TestAgentActionContract.

Test plan

• make test-unit green
• TestAgentActionContract passes with new AgentActionReadOnlySession
• 7 new tests for admin notes (create/list/delete round-trip,
  newest-first, non-admin 403, empty body, unknown team, unknown
  note id, 8KB cap)
• 10 new tests for impersonation (mints both claims, 10-min exp,
  audit row, non-admin 403, unknown team 404, empty team 409, GET
  works, POST blocked, real session still works, expired token
  rejected by RequireAuth)
• 6 new tests for RequireWritable middleware (no-token passes,
  normal-token passes, GET under impersonation passes, POST/PUT/PATCH/DELETE
  under impersonation blocked, locals populated correctly)

Total: 23 new test functions, all green.

Coverage audit

grep on every POST/PATCH/PUT/DELETE route registration confirms
RequireWritable applies to:

• app.Post("/db/new"), /cache/new, /nosql/new, /queue/new,
  /storage/new, /webhook/new — inline middleware on each
• app.Post("/billing/checkout") (legacy top-level alias) — inline
• app.Post("/stacks/new"), app.Delete("/stacks/:slug"),
  app.Patch("/stacks/:slug/env"), app.Post("/stacks/:slug/redeploy")
  — inline on each
• deployGroup (POST /deploy/new, PATCH /deploy/:id/env,
  DELETE /deploy/:id, POST /deploy/:id/redeploy) — installed on the
  group middleware chain
• api group (every POST/PATCH/PUT/DELETE under /api/v1/* —
  resources, team, billing, deployments, stacks, vault, audit, api-keys,
  experiments, invitations) — installed on the group middleware chain
• adminGroup inherits RequireWritable from its api parent group;
  the impersonation-mint endpoint is the deliberate exemption (the
  admin minting holds a writable session, so the gate never fires
  there anyway).

Routes intentionally NOT gated: POST /claim, POST /webhook/receive/:token,
POST /auth/*, POST /razorpay/webhook, POST /api/v1/invitations/:token/accept
— none of these accept a session JWT, so no read_only flag can be present.

Pushback / open notes

None — the spec is internally consistent. The one tension between
"apply to /api/v1/*" and "test 5 says /db/new must 403" is resolved
by applying RequireWritable broadly (both group and inline), which is
what the test suite asserts.

🤖 Generated with Claude Code