Skip to content

feat: one-time agent enrollment codes (#286 P4) - #311

Merged
brianorwhatever merged 2 commits into
mainfrom
feat/agent-enrollment-codes
Nov 18, 2026
Merged

brianorwhatever merged 2 commits into
mainfrom
feat/agent-enrollment-codes

Conversation

@brianorwhatever

@brianorwhatever brianorwhatever commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

PR P4 of the agent-signing plan: plans/002-agent-signing-decisions.md (D14, Track A row P4, on the docs/agent-signing-plan branch). Part of #286.

An owner mints a short-lived, one-time code in Settings and gives it to an agent. P5 will require that code in the agent's access request, so only an agent the owner started can ask for access. That answers the request-spam question left open on #308.

Nothing consumes a code yet, and the feature is off by default.

What's here

  • Table agentEnrollmentCodes: ownerId, codeHash, label, createdAt, expiresAt, redeemedAt. Only the SHA-256 of a code is stored. Indexed by hash, by owner and by expiry.
  • convex/agentEnrollment.ts
    • mintEnrollmentCode({ label? }) returns the plaintext code once.
    • listEnrollmentCodes() returns the owner's unused codes, without the code or its hash.
    • revokeEnrollmentCode({ codeId }) deletes an unredeemed code.
    • internal redeemEnrollmentCode({ code }) checks that the code exists, is unexpired and is unredeemed, marks it redeemed in the same transaction, and returns { ownerId, ownerDid, codeId, label }. Every failure returns null.
  • Limits: 15 minute lifetime (ENROLLMENT_CODE_TTL_MS), 5 unused codes per account, 10 mints an hour per account.
  • Code format: BOOP-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX, 25 characters of Crockford base32 (125 bits). Case, spaces and hyphens are ignored, and I/L/O read as 1/1/0.
  • Settings: an "Agents" section with "Create code", a copy button, a countdown, and Revoke for unused codes.
  • Docs: docs/agent-enrollment-codes.md, including what P5 has to do with the code.

Decisions worth a look

  • Two switches, both off unless true. The repo has no feature-flag convention, so I added src/lib/featureFlags.ts with the build-time VITE_AGENT_ENROLLMENT_CODES. Minting is also gated on the Convex env var AGENT_ENROLLMENT_CODES, so the endpoint does nothing on a deployment that hasn't opted in.
  • Minting is an action. The code comes from the runtime's CSPRNG, not from a mutation's seeded randomness. The action hands the hash to an internal actor mutation, which authenticates again and applies the cap and rate limit in its own transaction.
  • Rate limiting reuses rateLimits. I pulled the body of checkAndIncrementInternal into an exported consumeRateLimit(ctx, key, endpoint) so a mutation can spend a budget in its own transaction, and added an enrollmentCodeMint budget. Behaviour of the existing initiate and verify budgets is unchanged.
  • Session only. An API key is refused on mint, list and revoke, so an agent can't enroll another agent.
  • The owner is stored as the user id. Redemption returns the account's current DID, so a code survives a DID re-mint.
  • Revoke deletes the row. There is no revokedAt.
  • Redemption attempts aren't rate-limited here. redeemEnrollmentCode is internal with no caller. P5's unauthenticated endpoint has to limit attempts per IP.
  • Housekeeping: an hourly cron deletes codes a day past expiry, and account deletion erases the account's codes.
  • convex/_generated/api.d.ts was edited by hand to register the new module, because convex codegen needs a deployment and I didn't connect to one.

Verification

  • tsc -b, the Convex and e2e typechecks, and eslint on the changed files: clean.
  • bun test: 887 pass, 0 fail (main: 866).
  • bun run build: green.
  • New tests: scripts/agent-enrollment-codes.test.mjs (format, mint, hash-only storage, redeem, double redeem, expiry, revoke, cap, rate limit, session-only, server switch, cleanup) and scripts/agent-enrollment-code-ui.test.mjs (build flag, Settings section).
  • Not deployed anywhere. Not exercised against a live Convex deployment or in a browser.

🤖 Generated with Claude Code

Note

Add one-time agent enrollment codes behind feature flag (#286 P4)

  • Adds a full enrollment-code lifecycle in agentEnrollment.ts: session-only mint, list, and revoke handlers plus an internal single-use redeem mutation. Codes are BOOP-prefixed 25-symbol Crockford base32 strings, stored only as SHA-256 hashes, with a 15-minute lifetime and a 5-active-code per-account cap.
  • Adds format, normalization, hashing, constant-time comparison, and label helpers in enrollmentCode.ts, an agentEnrollmentCodes schema table, and a mint rate limit of 10 per hour in rateLimits.ts (with the fixed-window logic extracted into consumeRateLimit).
  • Adds a Settings Agents section in Settings.tsx with a new AgentEnrollmentCode.tsx component for minting, copying, listing, and revoking codes. Visible only when AGENT_ENROLLMENT_CODES_ENABLED is true; the server also requires AGENT_ENROLLMENT_CODES="true" for minting.
  • Runs hourly cleanup of stale codes via crons.ts (200 per batch) and drains enrollment codes in users.deleteUserStep during account deletion. Codes are added but not yet consumed anywhere.
  • Behavioral Change: rateLimits.ts endpoint validators now accept the new enrollmentCodeMint endpoint; account deletion now includes a bounded enrollment-code deletion step before the user row is removed.

Macroscope summarized 2ec6987.

An owner mints a short-lived, one-time code in Settings and gives it to an
agent. P5 will require the code in the agent's access request (plans/002
D14), so only an agent the owner started can ask for access. Nothing
redeems a code yet.

- agentEnrollmentCodes table: only the SHA-256 of a code is stored.
- mint (returns the code once), list and revoke for the signed-in owner;
  internal redeemEnrollmentCode validates and marks redeemed in one
  transaction and returns the owner.
- 15 minute lifetime, 5 unused codes per account, 10 mints an hour through
  the rateLimits budget.
- Settings section behind VITE_AGENT_ENROLLMENT_CODES, and minting behind
  the Convex env var AGENT_ENROLLMENT_CODES. Both are off by default.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@railway-app

railway-app Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

🚅 Deployed to the boop-pr-311 environment in Friends

Service Status Web Updated
boop ✅ Success (View Logs) Web Nov 18, 2026 at 8:34 am UTC

@railway-app
railway-app Bot temporarily deployed to Friends / boop-pr-311 November 15, 2026 20:00 Destroyed
# Conflicts:
#	docs/authenticated-function-inventory.md
@railway-app
railway-app Bot temporarily deployed to Friends / boop-pr-311 November 18, 2026 08:31 Destroyed
@brianorwhatever
brianorwhatever marked this pull request as ready for review November 18, 2026 08:38
@brianorwhatever
brianorwhatever merged commit 8195771 into main Nov 18, 2026
9 checks passed
@pullfrog

pullfrog Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

This run was cancelled before it finished.

Pullfrog  | View workflow run | via Pullfrog

This branch was successfully deployed

No deployments
Friends / boop-pr-311 — 2ec6987d Deployed Nov 18, 2026 by railway-app[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant