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 — an identity_assertion type that lets an anonymous registration be bound to a user via an ID-JAG, either atomically (clean match) or by falling back to a user_code ceremony (step-up). Schema, store, route handler, docs, and the demo client are all updated consistently.

• schemas.ts converts claimBody to a z.discriminatedUnion on \"type\", requiring existing email-shape callers to add \"type\": \"email\" (breaking change documented in CHANGELOG).
• store.ts adds completeAnonymousClaimViaIdJag for the atomic clean-match path and extends recordClaimAttempt with an optional idJag triple so completeClaim can upsert the delegation when the step-up ceremony is confirmed; the pending_claim guard prevents a competing ceremony from being stomped.
• agent-auth.ts adds handleAnonymousClaimViaIdJag with email-immutability enforcement and correctly branches between the step-up and clean-match paths.

Confidence Score: 5/5

Safe to merge — the core claim path is correctly guarded and the previous review's concerns are addressed.

The email-immutability guard, pending_claim block, and ceremony_in_flight error path all work correctly together. The one data-consistency wrinkle — matchOrProvision creating a JIT user/delegation before the email check or ceremony_in_flight guard can reject the request — doesn't expose wrong data on the registration itself and mirrors the pre-existing behavior of the /agent/identity endpoint. Docs, schema, store, and route handler are all consistent with each other and the PR description.

agent-services/src/routes/agent-auth.ts — specifically the ordering of matchOrProvision relative to the email check in handleAnonymousClaimViaIdJag.

Important Files Changed

Filename	Overview
agent-services/src/routes/agent-auth.ts	Adds handleAnonymousClaimViaIdJag with email-immutability guard and dispatches on the new discriminator. The matchOrProvision call creates JIT side-effects (user + delegation) before the email check or ceremony_in_flight guard can reject the request.
agent-services/src/store.ts	Adds completeAnonymousClaimViaIdJag, extends recordClaimAttempt with optional idJag, and broadens completeClaim's delegation condition from kind === "id_jag" to id_jag presence — all look correct.
agent-services/src/schemas.ts	Converts claimBody from a plain object to a z.discriminatedUnion on "type" with emailClaimBody and idJagClaimBody — schema is correct.
agent-services/src/routes/home.ts	Adds type: "email" to both the preview helper and the actual anonClaim() request body — both now match the updated discriminated union schema.
AUTH.md	Documents the new "4a-alt. Claim via ID-JAG" subsection with both success shapes and failure codes, consistent with the implementation.
agent-services/README.md	Adds the "Claim via ID-JAG" section documenting both terminal shapes and the anonymous-only restriction — matches the implementation.

Sequence Diagram

sequenceDiagram
    actor User
    participant Agent
    participant Service

    Agent->>Service: "POST /agent/identity { type: anonymous }"
    Service-->>Agent: 200 (v1 identity_assertion, claim_token)

    Note over Agent: operates pre-claim

    User-->>Agent: Signs in at provider — ID-JAG obtained

    Agent->>Service: "POST /agent/identity/claim<br/>{ type: identity_assertion, claim_token, assertion }"
    Service->>Service: verifyIdJag → matchOrProvision

    alt Clean match (delegation exists or JIT, no email conflict)
        Service-->>Agent: "200 { status: claimed, identity_assertion v2 }"
        Note over Agent: exchange v2 at /oauth2/token (jwt-bearer)
    else Step-up required (email matches existing different account)
        Service-->>Agent: "200 { status: initiated, claim_attempt: user_code + verification_uri }"
        Agent-->>User: Surface user_code + verification_uri
        User->>Service: GET verification_uri → POST /claim/complete
        Note over Service: bind anonymous reg to user + upsert (iss,sub) delegation
        loop poll until claimed
            Agent->>Service: POST /oauth2/token (claim grant)
            Service-->>Agent: 200 (access_token + v2 identity_assertion)
        end
    end

Loading

_{Reviews (16): Last reviewed commit: "Again with feeling" | Re-trigger Greptile}

[m0tzy]

@greptile

[m0tzy]

@greptile

[m0tzy]

@greptile

[m0tzy]

@greptile

[m0tzy]

@greptile