Skip to content
rachel/tessera
File

Blob: docs/phase-1-inventory.md

Markdown325 lines

Tessera — Phase 1 Document 1

Per-project migration inventory

This inventory captures how user identity works today in each repo affected by the tessera migration. All findings come from reading code, not READMEs. Paths are repo-relative (e.g. src/worker/auth/passwords.ts:42).

The two cross-cutting reference tables at the end (Turnstile pattern, encryption-at-rest) collect file paths tessera will mirror.

anvil

Identity storage today

Users table — src/worker/db/d1/schema/users.ts (lines 1–14)

  • id (text, primary key)
  • slug, email, displayName, createdAt, disabledAt (nullable)

Password credentials table (separate from users) — src/worker/db/d1/schema/password-credentials.ts (lines 1–13)

  • userId (text, primary key, FK → users.id)
  • algorithm, digest, iterations, salt (Uint8Array), passwordHash (Uint8Array), updatedAt

Hash format: PBKDF2 (not Argon2). Implementation src/worker/auth/passwords.ts:13-34 uses crypto.subtle.deriveBits(PBKDF2, digest, iterations, salt) → 256-bit key. 16-byte random salt; algorithm, digest, and iterations are stored on the row so verify can reproduce.

Session mechanism: KV-backed. src/worker/auth/sessions.ts:

  • KV key shape: sess:{sessionId} with TTL.
  • Record: { userId, issuedAt, expiresAt, version } (ISO8601).
  • Bearer-token auth — sessionId is sent as Authorization: Bearer <id> (parsed in src/worker/auth/middleware.ts:10).

Auth library: none. Custom Hono handlers + @cloudflare/util-en-garde codecs (no Better Auth).

Code reading/writing identity

Operation Location
Sign-in (POST /auth/login) src/worker/api/public/auth.ts:62-106 (handleLogin)
Sign-up via invite (POST /auth/invite/accept) src/worker/api/public/auth.ts:119-217 (handleInviteAccept)
Password hash src/worker/auth/passwords.ts:37 (hashPassword)
Password verify src/worker/auth/passwords.ts:52 (verifyPassword, timing-safe)
Session create src/worker/auth/sessions.ts:19 (createSession)
Session read src/worker/auth/sessions.ts:41 (readSession)
Session refresh src/worker/auth/sessions.ts:66 (maybeRefreshSession)
Session delete src/worker/auth/sessions.ts:100 (deleteSession)
requireAuth middleware src/worker/auth/middleware.ts:23-39 (sets c.set("user", user))
Logout src/worker/api/public/auth.ts:108-117 (handleLogout)
Invite create (auth-gated) src/worker/api/private/invites.ts:11-43

Foreign keys to user identifier

D1 (all reference users.id as text):

Table FK column Schema file
password_credentials userId src/worker/db/d1/schema/password-credentials.ts:6
project_index ownerUserId src/worker/db/d1/schema/projects.ts:8
run_index triggeredByUserId src/worker/db/d1/schema/run-index.ts:9
invites createdByUserId, acceptedByUserId src/worker/db/d1/schema/invites.ts:10, 13

Durable Object storage:

  • project_runs.triggeredByUserId (in ProjectDO) — src/worker/db/durable/schema/project-do.ts:34

DO stub naming is not keyed on user id (uses prj_/run_ prefixes via src/worker/services/id-service.ts:65-68).

What changes to consume tessera as an OIDC IdP

  1. Add OIDC client wiring: env vars TESSERA_OIDC_ISSUER (=https://auth.limic.dev), TESSERA_OIDC_CLIENT_ID, wrangler secret TESSERA_OIDC_CLIENT_SECRET. New /auth/callback route exchanges code at https://auth.limic.dev/token and validates the ID token signature against https://auth.limic.dev/.well-known/jwks.json.
  2. Replace handleLogin: sign-in becomes a redirect to tessera's /authorize (PKCE, state, nonce). The password form on /sign-in is deleted.
  3. Drop password_credentials table once tessera is live for all anvil users (one-shot SQL: DROP TABLE password_credentials;). Remove src/worker/auth/passwords.ts.
  4. Add a tessera_sub TEXT UNIQUE column to users with an index. users.id and every FK column referencing it stay untouched. The OIDC callback finds the local user by tessera_sub; on first sign-in for an email already in users, the callback binds by UPDATE users SET tessera_sub = ?. (See Document 2 § Migration strategy for the design rationale; the actual migration code lives in anvil, not tessera.)
  5. Invite flow: anvil's invites table stays for "invite this tessera-identified user into anvil" semantics; handleInviteAccept becomes "associate the OIDC-authenticated user with this anvil invite" — no password fields.

What stays unchanged

  • users.id column and every FK column referencing it — completely untouched.
  • KV session mechanism — anvil still mints its own bearer-token session at the OIDC callback. The OIDC ID token is consumed once at callback, not on every request.
  • requireAuth middleware (still reads bearer, still calls readSession).
  • All Turnstile gating on non-auth public surfaces.
  • The encryption-at-rest pattern for repo tokens / webhook secrets — orthogonal to this migration.

bland

Identity storage today

Users table — src/worker/db/d1/schema.ts:4-16

  • id (text, primary key)
  • email (text, unique), password_hash (text), name, avatar_url, created_at, updated_at

Hash format: Argon2id PHC string $argon2id$v=19$m=19456,t=2,p=1$<base64-salt>$<base64-hash> — src/worker/lib/auth.ts:78-84. Implementation uses @noble/hashes/argon2.js (pure JS, workerd-compatible — same library tessera will use).

Session mechanism: JWT (no Better Auth). Implementation uses jose. Access token TTL 15 min; refresh token TTL 7 days, stored in bland_refresh httpOnly cookie. No session table.

  • Token mint: src/worker/lib/auth.ts:119-133 (createAccessToken, createRefreshToken).
  • Token verify: src/worker/middleware/auth.ts:36.
  • requireAuth / optionalAuth: src/worker/middleware/auth.ts:53-81.

Auth library: none. Custom JWT impl on jose + @noble/hashes/argon2.js.

Code reading/writing identity

Operation Location
Sign-in (POST /auth/login) src/worker/routes/auth.ts:30-71
Invite-accept user create src/worker/routes/invites.ts:183-201
Password hash (called from invite accept) src/worker/lib/auth.ts (hashPassword)
Password verify src/worker/lib/auth.ts:86-117 (constant-time compare)
Token create src/worker/lib/auth.ts:119-133
requireAuth middleware src/worker/middleware/auth.ts:53-81
Logout (clear cookie) src/worker/routes/auth.ts:113-117
GET /auth/me src/worker/routes/auth.ts:120-123
Client auth state src/client/stores/auth-store.ts

Foreign keys to user identifier

D1 — all reference users.id:

Table FK column Schema file
workspaces owner_id src/worker/db/d1/schema.ts:23-25
memberships user_id src/worker/db/d1/schema.ts:34-36
invites invited_by, accepted_by src/worker/db/d1/schema.ts:56-58, 64
pages created_by src/worker/db/d1/schema.ts:92-94
pageShares grantee_id (when grantee_type='user'), created_by src/worker/db/d1/schema.ts:119, 124-126
uploads uploaded_by src/worker/db/d1/schema.ts:143-145

Durable Objects: none keyed on user id. DocSync and WorkspaceIndexer DOs are keyed on workspace/document.

What changes to consume tessera as an OIDC IdP

  1. Add OIDC client wiring: TESSERA_OIDC_ISSUER, TESSERA_OIDC_CLIENT_ID, secret TESSERA_OIDC_CLIENT_SECRET; new /auth/callback route.
  2. Replace POST /auth/login: redirect to tessera's /authorize. Remove password form on /login UI.
  3. Drop the password column once tessera is live for all bland users: ALTER TABLE users DROP COLUMN password_hash;. Drop hashPassword/verifyPassword from src/worker/lib/auth.ts.
  4. Add a tessera_sub TEXT UNIQUE column to users with an index. users.id and every FK column referencing it stay untouched. OIDC callback finds the local user by tessera_sub; on first sign-in for a known email, the callback binds by UPDATE users SET tessera_sub = ?.
  5. Decide JWT-or-OIDC-token retention: bland currently uses jose-issued JWTs for its own session. Recommendation: keep bland's JWT session (callback validates tessera ID token → mints bland JWT → sets refresh cookie). Minimal change to existing middleware.

What stays unchanged

  • users.id column and every FK column referencing it — completely untouched.
  • jose-based JWT verify in middleware.
  • All workspace / page / share / upload FKs.
  • Turnstile setup (still needed on any unauthenticated public surface; the sign-in form gating goes away with the form).

ccccocc

(Skipping the standard inventory per the Phase 1 instructions — workspace mapping is ephemeral and a separate post-tessera task.)

Cloudflare Access claim usage today

ccccocc reads the sub claim from the verified Cf-Access-Jwt-Assertion header.

  • Header parsed at src/worker/auth.ts:89 inside authenticateAccess().
  • JWT signature verified against the team's Access JWKS (https://{team}.cloudflareaccess.com/cdn-cgi/access/certs):
    • fetchJWKS at src/worker/auth.ts:134
    • verifySignature at src/worker/auth.ts:158
  • Standard JWT validation in the same function: exp (line 106), aud against CF_ACCESS_AUD (line 111), iss (line 118).
  • payload.sub extracted at src/worker/auth.ts:129 and bound as userId.
  • payload.email is also read into the AuthResult but not used for sandbox identification.

The sandbox identifier is derived (no hashing, no slug) at src/worker/auth.ts:49 (deriveSandboxId):

${userId}-${workspace || "default"}

This string keys the Sandbox Durable Object stub at src/worker/index.ts:72, 84, 106, 164, 177, 198 via getSandbox(env.Sandbox, sandboxId).

There is no persistent storage of the sub value — it is re-extracted from each request's JWT and used to address the DO directly.

What tessera must guarantee about the sub claim

  1. Stable — same value across logins and across all linked identity providers (email+password, GitHub, Google) for the same human.
  2. Opaque — never email, never email-derived; tessera issues a UUID v4 and binds linked identities to it.
  3. String-shaped, namespace-safe — usable directly in DO stub names. UUID v4 satisfies this.

When tessera replaces the existing direct-GitHub/Google Cloudflare Access OIDC config, ccccocc must stop treating payload.sub as the tessera subject. Cloudflare Access uses payload.sub for its own user ID and exposes the forwarded tessera subject as payload.custom.tessera_sub when the tessera_sub claim is listed in the Access OIDC Claims configuration.

git-on-cloudflare

System A — git HTTP Basic-auth (machine credentials, STAYS UNCHANGED)

Routes (registered in src/routes/git.ts:219-245):

Route Auth
GET /:owner/:repo/info/refs?service=git-upload-pack none (read advertise)
POST /:owner/:repo/git-upload-pack none (fetch/clone)
POST /:owner/:repo/git-receive-pack Basic-auth required (push)

Auth pipeline:

  • Header parse: src/auth/verify.ts:5-19 (getBasicCredentials).
  • Verify (called from src/routes/git.ts:240): src/auth/verify.ts:21-40. Username must match the :owner URL param; password is the token; verification is delegated to AuthDurableObject.

Token storage (no D1):

  • AuthDurableObject storage: type AuthUsers = Record<string, string[]> keyed by the literal string "users", mapping owner → array of hashed token strings. Schema at src/do/auth/authState.ts:7.
  • Hash: PBKDF2-SHA256, 100k iterations + 16-byte salt, format salt:iterations:hash. src/do/auth/authDO.ts:43-71 (hashTokenWithPBKDF2).
  • Verify: src/do/auth/authDO.ts:80-90 (timing-safe; supports variable iteration counts).

This entire system stays as-is in the tessera era. git push over HTTPS continues to use Basic-auth tokens; tessera does not touch it.

System B — Web admin UI (humans, MOVES behind tessera OIDC)

Routes that should move behind OIDC (currently behind reused git Basic-auth via verifyAuth(env, owner, request, true)):

  • GET /:owner/:repo/admin — admin dashboard
  • POST /:owner/:repo/admin/compact, DELETE /:owner/:repo/admin/compact
  • GET /:owner/admin/registry, POST /:owner/admin/registry/sync
  • GET/PUT /:owner/:repo/admin/refs, GET/PUT /:owner/:repo/admin/head
  • GET /:owner/:repo/admin/debug-*
  • DELETE /:owner/:repo/admin/pack/:packKey, DELETE /:owner/:repo/admin/purge

Routes currently behind a separate AUTH_ADMIN_TOKEN Bearer (also moves behind OIDC):

  • GET /auth/api/users, POST /auth/api/users, DELETE /auth/api/users — list / add / delete machine tokens

Routes that stay public:

  • GET / (home)
  • GET /:owner (repos list)
  • GET /:owner/:repo, /tree, /blob, /commits, /commit/:oid (read-only repo browsing)
  • GET /auth (token management UI page; ops behind it require Bearer)

Handler files:

  • src/routes/ui.ts:10-45 — UI route registrations.
  • src/routes/admin.ts:36-344 — admin JSON API.
  • src/routes/auth.ts:6-117 — auth UI + token mgmt API.
  • src/routes/ui/adminPage.ts:27 — admin page calls verifyAuth(env, owner, request, true).
  • Bearer-admin path: src/routes/auth.ts:30, 50, 84 call getBearerToken(request); verified via stub.adminAuthorizeOrRateLimit() at src/do/auth/authDO.ts:274-323 against env.AUTH_ADMIN_TOKEN.

Current identity state for the web admin

  • No session cookies.
  • No password system.
  • No web-level user identity at all — admin pages reuse the same Basic-auth-token system as git push. The Bearer path (/auth/api/users) uses a separate AUTH_ADMIN_TOKEN wrangler secret.

What changes for tessera

  1. Replace verifyAuth(..., true) for admin UI/API with a new requireOidcSession middleware that validates a tessera-minted session cookie (or bearer JWT) and asserts the sub claim against OPERATOR_SUB.
  2. Replace AUTH_ADMIN_TOKEN Bearer for /auth/api/users with the same OIDC-session check.
  3. Add new env: TESSERA_OIDC_ISSUER, TESSERA_OIDC_CLIENT_ID, secret TESSERA_OIDC_CLIENT_SECRET, plus OPERATOR_SUB (tessera UUID for the limic operator).
  4. Add /auth/callback route to handle the OIDC redirect.
  5. No D1 migration needed — git-on-cloudflare has no users table. Identity has been "the holder of this Basic-auth token" up to now; after the change, identity is "the OIDC sub from tessera." There is no historical row to rewrite.

What stays unchanged

  • All git Basic-auth routes (System A) and the AuthDurableObject storage.
  • All public read routes.
  • Repo metadata SQLite schema (src/do/repo/db/schema.ts:4-31 — only pack catalog, no user data).

flamemail

Confirmation

Persistent identity = the ADMIN_PASSWORD wrangler secret, full stop. Confirmed:

  • No users D1 table. src/worker/db/schema.ts:17-37 declares only inboxes, emails, attachments, domains.
  • Login compares the submitted password against c.env.ADMIN_PASSWORD at src/worker/api/admin.ts:79 using constantTimeEqualStrings (src/worker/security.ts:73-83, wrapping crypto.subtle.timingSafeEqual via Cloudflare's SubtleCrypto).
  • Successful admin login mints a session token at src/worker/api/admin.ts:88-94 via createSessionToken. Token is tok_<nanoid(32)> (38 chars), stored in KV SESSIONS with TTL. Session record: { type: "admin" }. Implementation: src/worker/services/inbox/session-store.ts:33-40.
  • No OAuth, SAML, magic-link, or per-user accounts.

Public inbox tokens are anonymous capability tokens, not identity. Confirmed:

  • The inboxes table has no FK to any user table — columns are id, localPart, domain, fullAddress, isPermanent, createdAt, expiresAt (src/worker/db/schema.ts:17-37).
  • Inbox creation (POST /api/public/inboxes at src/worker/api/inboxes.ts:28-84) returns {address, token, ttlHours, expiresAt}. The token is the same tok_<nanoid(32)> shape, stored in KV SESSIONS as { type: "user", address }.
  • Tokens are presented as Authorization: Bearer, not embedded in URLs. There is no path-based capability URL.

What changes for tessera

The admin login form at /admin/login (currently Turnstile + ADMIN_PASSWORD) becomes an OIDC redirect to tessera's /authorize. The ADMIN_PASSWORD wrangler secret is removed once tessera is live. The KV-backed { type: "admin" } session record can stay; it is minted at the OIDC callback instead of after a password compare.

The public anonymous inbox capability flow stays entirely as-is — those tokens are not identity, they are capability URLs.

What stays unchanged

  • Public inbox creation flow (anonymous capability tokens).
  • Email reception, storage, attachment handling.
  • KV session store mechanism (just minted at OIDC callback instead of after a password compare).
  • Turnstile gating on inbox creation and admin login (tessera will mirror flamemail's fail-closed style on missing env keys → 503).

Turnstile pattern reference table

Tessera will mirror this. All three projects fail closed: missing token, missing secret, or failed siteverify all reject the request.

Concern anvil bland flamemail
Site key env read src/worker/api/public/app-config.ts:10 src/worker/lib/spa-shell.ts:30-32 src/worker/api/config.ts:7
Secret env read src/worker/services/turnstile.ts:60 src/worker/middleware/turnstile.ts:31 src/worker/services/turnstile.ts:53
Client widget component src/client/components/turnstile-widget.tsx src/client/components/auth/turnstile-widget.tsx src/client/components/turnstile-widget.tsx (renders 140-163)
Server siteverify POST src/worker/services/turnstile.ts:101 src/worker/middleware/turnstile.ts:37 src/worker/services/turnstile.ts:94
Fail-closed enforcement src/worker/api/public/auth.ts:35-60 (assertTurnstileVerified) src/worker/middleware/turnstile.ts:26-62 (400/403 returns) src/worker/services/turnstile.ts:49-185 (503 on missing keys / 403 on fail)
Local-dev bypass (none — uses test keys) src/worker/middleware/turnstile.ts:22 (isLocalRequestUrl) (none — uses test keys)

Recommended pattern for tessera:

  • Server side: follow anvil's assertTurnstileVerified helper called from each gated handler. Tessera's gated surface is small (/sign-in and /invite/<token>); middleware-style verification adds indirection without benefit.
  • Client side: copy bland's widget (src/client/components/auth/turnstile-widget.tsx) — most recently iterated, closest to the auth-flow shape tessera needs.
  • Fail-closed return codes: 503 for missing env keys (deploy-config error, per flamemail); 400 for missing token; 403 for failed siteverify or action mismatch.

Encryption-at-rest reference (anvil)

Anvil ports its own AES-GCM helper (src/worker/security/secrets.ts) and writes a three-column shape (*Ciphertext, *KeyVersion, *Nonce) for every encrypted field, keyed off a versioned appEncryptionKeysJson wrangler secret. Tessera deliberately does not mirror this. Better Auth already covers the two columns that matter here:

  • JWKS private bytes — the jwt plugin wraps jwks.privateKey with BETTER_AUTH_SECRET on write and unwraps on sign (gated by !options.jwks.disablePrivateKeyEncryption, which defaults to encrypted). See node_modules/better-auth/dist/plugins/jwt/{sign,utils}.mjs.
  • OAuth provider access/refresh/id tokens — when account.encryptOAuthTokens: true is set on betterAuth({...}), oauth2/utils.mjs wraps account.access_token / refresh_token / id_token with the same secret. Tessera enables this in src/worker/auth/index.ts. The read path checks isLikelyEncrypted(token) first, so flipping the flag is backwards-compatible with any plaintext rows already in D1.

Tessera therefore ships one secret (BETTER_AUTH_SECRET) instead of BETTER_AUTH_SECRET plus a separate appEncryptionKeysJson map, and there is no src/worker/security/secrets.ts in the tree. If a future column genuinely needs at-rest encryption beyond what Better Auth covers, port anvil's helper at that point — don't add it speculatively.