Claim anonymous registration via ID-JAG

[m0tzy]

• I have QA'd the changes

Stack

1. Split credentials into a separate endpoint #8
2. Migrate revocation channel to SET delivery (RFC 8417/8935) #9
3. Invert the claim flow to mirror device auth #10
4. ID-JAG step-up + auth_time freshness #11
5. Claim anonymous registration via ID-JAG #12 ← you are here

Summary

POST /agent/identity/claim gains a second body shape, discriminated on type:

{ "type": "email", "claim_token": "...", "email": "..." }                      → start user_code ceremony (existing)
{ "type": "identity_assertion", "claim_token": "...", "assertion": "<ID-JAG>" } → claim atomically via ID-JAG (new)

The flow this unlocks: an agent starts anonymous, does pre-claim work, later acquires an ID-JAG (user signed in at the agent's provider mid-run) and binds the existing anonymous registration to that user. Keeps registration_id and pre-claim continuity intact instead of throwing it away and re-registering.

Verification chain

/claim with type: identity_assertion runs the same verification chain as /agent/identity. Failures route the same way:

ID-JAG state	Response
Signature / audience / replay bad	400 with the verifier error code
auth_time missing or stale	401 login_required with WWW-Authenticate: AgentAuth error="login_required", max_age="…"
Matcher: existing (iss, sub) delegation OR JIT (no email conflict)	200 + v2 identity_assertion — ID-JAG alone is enough; bound atomically
Matcher: step_up_required (ID-JAG's email matches an existing different user, no delegation yet)	200 + claim_attempt ceremony block — user must confirm at /claim. The ceremony binds the anonymous registration AND the (iss, sub) delegation in one shot.

The step-up branch returns the ceremony block right here rather than redirecting to /agent/identity — /claim is already the user-mediated confirmation surface; there's no reason to bounce the agent across endpoints.

Implementation

• schemas.ts: claimBody becomes a z.discriminatedUnion("type", …).
• store.ts:
  • recordAnonymousClaimAttempt accepts an optional idJag triple. When set, the anonymous registration records id_jag = { iss, sub, aud } so completeClaim upserts the delegation alongside the user binding.
  • completeAnonymousClaimViaIdJag handles the atomic clean-match path (no ceremony): binds user + delegation, records id_jag, revokes pre-claim access_tokens.
  • completeClaim upserts delegation based on registration.id_jag presence (not kind), so both step-up-via-/identity and step-up-via-/claim paths bind delegations on completion.
• agent-auth.ts /claim handler dispatches on parsed.value.type. The new handleAnonymousClaimViaIdJag runs verifyIdJag → matchOrProvision → branches on match.kind.
• Demo: existing anon claim call now sends the type field.
• Docs: AUTH.md Step 4 gets a "4a-alt. Claim via ID-JAG" subsection; agent-services README documents both shapes; README.md gets a new sequence diagram showing the two branches.

Smoke test

Step-up path (ceremony required):

1. Pre-seed alice@example.com at the service via email-verif
2. Anonymous register
3. POST /claim with type: identity_assertion + ID-JAG → 200 with claim_attempt (user_code 428947) ✓
4. User completes ceremony at /claim → 200
5. Agent polls /oauth2/token with claim grant → scope api.read api.write, v2 assertion's email: alice@example.com ✓

Clean-match path (ID-JAG enough):
6. Fresh anonymous register
7. POST /claim with type: identity_assertion + ID-JAG (same (iss, sub), delegation now exists from step 5) → 200 + immediate v2 identity_assertion, no ceremony ✓

[devin-ai-integration]

@greptileai review

[greptile-apps]

Greptile Summary

This PR adds a second body shape to POST /agent/identity/claim, discriminated on type, so an anonymous registration can be bound to a user identity by presenting an ID-JAG directly rather than always requiring a user_code ceremony. When the ID-JAG is enough on its own (existing delegation or no email conflict) the claim completes atomically with a v2 identity_assertion; when the ID-JAG's email matches a different existing account, the endpoint falls back to the familiar claim_attempt ceremony block.

• schemas.ts makes claimBody a z.discriminatedUnion on type (login_hint | identity_assertion); this is a breaking rename for existing callers who must now send \"type\": \"login_hint\".
• store.ts adds completeAnonymousClaimViaIdJag for the atomic clean-match path and extends recordClaimAttempt to carry the id_jag triple, so completeClaim upserts the delegation for both step-up-via-/identity and step-up-via-/claim paths.
• agent-auth.ts adds handleAnonymousClaimViaIdJag that runs verifyIdJag → matchOrProvision → branches on match kind; docs, CHANGELOG, and README sequence diagrams are updated to match.

Confidence Score: 3/5

The clean-match ID-JAG path in store.ts can be permanently blocked after any expired ceremony, and the step_up branch in agent-auth.ts silently overwrites an active in-flight ceremony — both need fixing before the new endpoint behaves as documented.

Two issues affect the new claim path's correctness: completeAnonymousClaimViaIdJag gates on status === pending_claim but that status persists after the user_code expires (since claim.attempt is never cleared), so a delegation-matching ID-JAG is blocked until the entire claim token expires rather than just until the ceremony window closes. Separately, handleAnonymousClaimViaIdJag calls recordClaimAttempt in the step_up branch without first checking whether an active ceremony is already running, so a concurrent or retried call can silently replace a ceremony the user is actively completing.

agent-services/src/store.ts (the pending_claim guard in completeAnonymousClaimViaIdJag) and agent-services/src/routes/agent-auth.ts (the step_up branch in handleAnonymousClaimViaIdJag) need the most attention.

Important Files Changed

Filename	Overview
agent-services/src/routes/agent-auth.ts	Adds handleAnonymousClaimViaIdJag — dispatches on type, verifies ID-JAG, branches on matchOrProvision result; the step_up path can silently overwrite an active ceremony (no pending_claim guard before recordClaimAttempt), and the email-immutability bypass for in-flight ceremonies is unguarded (covered in prior threads).
agent-services/src/store.ts	Adds completeAnonymousClaimViaIdJag and extends recordClaimAttempt/completeClaim; the pending_claim guard in completeAnonymousClaimViaIdJag does not account for expired user_codes, permanently blocking the clean-match path after any initiated ceremony.
agent-services/src/schemas.ts	Refactors claimBody into a z.discriminatedUnion on type with loginHintClaimBody and idJagClaimBody sub-schemas; clean and correct.
agent-services/src/routes/home.ts	Updates anonClaim to use type: login_hint and renames email to login_hint correctly; updateAnonClaimPreview still uses type: email (invalid discriminator) and the old email key (covered in prior thread).
AUTH.md	Adds 4a-alt section documenting both ID-JAG claim shapes with accurate request/response examples; failure table is correctly updated; minor doc inconsistency about interaction_required vs 200 covered in prior thread.
agent-services/README.md	Documents both login_hint and identity_assertion shapes with implementation steps and response examples; step_up description mentions 401 interaction_required which is inconsistent with the actual 200 response (prior thread).
README.md	Adds a sequence diagram for the two ID-JAG claim branches (clean-match and step_up); accurate and matches the implementation.
CHANGELOG.md	Adds v0.7.0 entry documenting both new response shapes and calling out the breaking type discriminator requirement; accurate.
package.json	Version bumped from 0.6.0 to 0.7.0 consistent with the breaking change in claimBody.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[POST /agent/identity/claim] --> B{Parse claimBody\ndiscriminatedUnion on type}
    B -->|invalid| C[400 invalid_request]
    B --> D{Lookup registration\nby claim_token hash}
    D -->|not found| E[401 invalid_claim_token]
    D -->|expired| F[410 claim_expired]
    D -->|claimed| G[409 claimed_or_in_flight]
    D --> H{type?}
    H -->|identity_assertion| I{kind === anonymous?}
    I -->|no| J[409 claimed_or_in_flight]
    I -->|yes| K[verifyIdJag]
    K -->|auth_time error| L[401 login_required]
    K -->|other error| M[400 verifier error]
    K -->|ok| N[matchOrProvision]
    N -->|step_up_required| O[recordClaimAttempt\nwrite id_jag triple]
    O --> P[200 status: initiated\nclaim_attempt block]
    N -->|match| Q[completeAnonymousClaimViaIdJag]
    Q -->|ceremony_in_flight\npending_claim status| R[409 ceremony_in_flight]
    Q -->|ok| S[signServiceIdJag]
    S --> T[200 status: claimed\nidentity_assertion v2]
    H -->|login_hint| U[classifyLoginHint]
    U -->|invalid| V[400 invalid_login_hint]
    U -->|ok| W[recordClaimAttempt]
    W --> X[200 status: initiated\nclaim_attempt block]

Loading

_{Reviews (18): Last reviewed commit: "Bump package.json to 0.7.0 to match CHAN..." | Re-trigger Greptile}

[m0tzy]

@greptile

[m0tzy]

@greptile

[m0tzy]

@greptile

[m0tzy]

@greptile

[m0tzy]

@greptile