Invert the claim flow to mirror device auth

[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 ← you are here
4. ID-JAG step-up + auth_time freshness #11
5. Claim anonymous registration via ID-JAG #12

Summary

Invert the claim ceremony and consolidate polling onto /oauth2/token.

Before: service emails the user a 6-digit OTP each time, user reads it back to the agent, agent submits. Each ceremony required a fresh email round-trip and gave us no leverage over any existing user session at the service.

After: agent gets the user_code at registration time and surfaces it to the user along with a verification_uri. The user signs in to the service in their browser (which can reuse existing session, SSO, whatever the service normally does) and types the code on a service-owned page. The agent polls /oauth2/token with a profile-specific claim grant for completion.

Re-authentication now uses the service's own browser-based sign-in surface — the channel users already trust, and where the service can apply whatever step-up / SSO / MFA policy it wants — instead of a code emailed out of band each ceremony. Eliminating the email channel also closes the phishing-by-agent vector where a malicious agent could intercept a code the user fetched from their inbox.

The new ceremony block borrows from RFC 8628 device-authorization (user_code, verification_uri, expires_in, interval). Polling happens at the standard token_endpoint with a profile-specific grant URN (urn:workos:agent-auth:grant-type:claim) — not the IANA device_code grant — so it doesn't collide with services that also implement standard RFC 8628 device authorization at the same endpoint. The AS routes by grant_type, with zero risk of a claim_token being looked up in a device-auth store or vice versa.

Agent surface

• Registration responses include a ceremony block — under claim for email-verification (returned with the registration itself) or under claim_attempt for anonymous (returned from /agent/identity/claim). Both carry user_code, verification_uri, expires_in, interval.
• /oauth2/token gains a second grant: urn:workos:agent-auth:grant-type:claim takes the claim_token, returns authorization_pending while waiting, expired_token on closed window, and a standard OAuth token response on completion. Success extends the standard response with identity_assertion + assertion_expires so the agent has a refresh path via the JWT-bearer grant once the access_token expires.
• Discovery's grant_types_supported lists both grants.
• claim_attempt_token (in verification_uri) binds the URL to a specific registration without leaking the user-typed user_code.

New user-facing surface (service-owned)

• New /login route — mock IdP, cookie-bound session.
• New /claim route — cookie-gated form where the user types the user_code.
• POST /agent/identity/claim/complete is the form-action endpoint for /claim — the agent no longer calls it.

Security: binding the ceremony to a specific user

• The email parameter on anonymous POST /agent/identity/claim binds the registration to that user — only that signed-in account can complete the ceremony, preventing third-party interception of the user_code.
• The wrong-account check fires whenever claim_email is set, regardless of registration kind — covers both email-verification (asserted by the agent at registration) and anonymous (provided by the agent at /claim).
• Anonymous: completing the ceremony revokes any pre-claim access_tokens. The canonical credential is the one returned by the claim grant.

Removed

• /agent/identity/claim/attempt/challenge — user_code is minted at ceremony start now, no separate mint step.
• /agent/identity/claim/view — polling moved to /oauth2/token with the claim grant.
• mail.ts, routes/mail.ts, and the .mail/ directory — the agent already has the verification URL + user_code, so an out-of-band email channel adds nothing and is the part most vulnerable to phishing-by-agent.

Internal

• Store: rename otp_* fields on RegistrationClaimAttempt → user_code_*. completeClaim takes signedInUser: User instead of looking up by email.
• New Session type + createSession / findSession / destroySession helpers for the cookie-bound /claim form.
• Docs (AUTH.md, README.md, agent-services/README.md) and the service demo (routes/home.ts) rewritten end to end.

[devin-ai-integration]

@greptileai review

[greptile-apps]

Greptile Summary

This PR inverts the agent-auth claim ceremony from a service-emailed OTP to an RFC 8628-shaped device-authorization flow: the agent now receives user_code + verification_uri at ceremony start, the user signs in on a service-owned browser page and types the code, and the agent polls /oauth2/token with a custom urn:workos:agent-auth:grant-type:claim grant until the ceremony completes.

• New claim ceremony flow: registration responses carry a ceremony block (user_code, verification_uri, expires_in, interval); /oauth2/token gains the claim grant that returns authorization_pending / expired_token / a standard token response with identity_assertion extension.
• New service-owned browser surface: /login (mock IdP, cookie-bound session) and /claim (form-action endpoint); the agent never calls these — it only polls the token endpoint.
• Security hardening: email binding is now immutable after first /agent/identity/claim call, preventing ceremony redirection to a different account on re-initiation; anonymous pre-claim credentials are revoked on successful claim; the email/OTP channel (phishing vector) is removed entirely.

Confidence Score: 5/5

Safe to merge; the core claim ceremony logic, email-immutability guard, and expired user_code check are all correct.

The ceremony inversion is well-structured: the store correctly handles email binding, user_code expiry, and pre-claim credential revocation. The token endpoint correctly returns expired_token when the user_code window closes and authorization_pending while waiting. The only new issue introduced is a hardcoded session-secret fallback in config.ts, which is a demo-only concern explicitly called out in comments.

agent-services/src/config.ts — the hardcoded SESSION_SECRET fallback should be reviewed before any non-demo deployment.

Important Files Changed

Filename	Overview
agent-services/src/routes/token.ts	Adds the claim-grant handler (RFC 8628-shaped polling) alongside the existing JWT-bearer grant; dispatches on grant_type, includes expired user_code check, and extends the success response with identity_assertion + assertion_expires.
agent-services/src/routes/claim.ts	New user-facing claim form (GET + POST); cookie-gated via requireUser, validates claim_attempt_token via view_token_hash, enforces wrong-account check, and delegates to completeClaim in the store.
agent-services/src/routes/login.ts	New mock IdP; sanitises return_to (same-origin only), auto-provisions unknown emails, and sets session.userId via express-session.
agent-services/src/routes/agent-auth.ts	Stripped to registration and claim-initiation endpoints; adds email-immutability guard on re-initiation so the bound account cannot be redirected after first bind.
agent-services/src/store.ts	Renames otp_* fields to user_code_*, changes completeClaim to accept a User directly, and revokes pre-claim credentials for anonymous registrations on successful claim.
agent-services/src/config.ts	Adds session config (secret, TTL, poll interval); hardcoded "demo-secret-do-not-ship" fallback for SESSION_SECRET violates the no-hardcoded-secrets rule.
agent-services/src/index.ts	Wires express-session and urlencoded body parser; session cookie correctly sets httpOnly, secure (conditional on NODE_ENV), and sameSite: lax.
agent-services/src/schemas.ts	Replaces claimCompleteBody/generateOtpBody with claimFormBody + claimGrantBody; renames tokenEndpointBody to jwtBearerGrantBody; validates user_code as exactly 6 digits.
agent-services/src/routes/well-known.ts	Adds urn:workos:agent-auth:grant-type:claim to grant_types_supported in the AS discovery document.

Sequence Diagram

sequenceDiagram
    participant Agent
    participant Service as Service (/agent/identity, /oauth2/token)
    participant Browser as User Browser (/login, /claim)

    Agent->>Service: POST /agent/identity (anonymous or email)
    Service-->>Agent: "registration_id, claim_token, claim + {user_code, verification_uri, expires_in, interval}"

    Note over Agent,Browser: Agent surfaces user_code + verification_uri to user

    Agent->>Service: POST /agent/identity/claim (anonymous only, with email)
    Service-->>Agent: "claim_attempt {user_code, verification_uri, expires_in, interval}"

    loop Poll until complete
        Agent->>Service: "POST /oauth2/token (grant_type=urn:workos:agent-auth:grant-type:claim, claim_token)"
        Service-->>Agent: "{error: authorization_pending} or {error: expired_token}"
    end

    Browser->>Service: "GET /login?return_to=/claim?claim_attempt_token=..."
    Service-->>Browser: Login form
    Browser->>Service: POST /login (email)
    Service-->>Browser: "Redirect to /claim?claim_attempt_token=..."
    Browser->>Service: GET /claim (cookie-gated)
    Service-->>Browser: Claim form (user_code input)
    Browser->>Service: POST /agent/identity/claim/complete (user_code, claim_attempt_token)
    Service-->>Browser: All set confirmation

    Agent->>Service: "POST /oauth2/token (grant_type=claim, claim_token)"
    Service-->>Agent: access_token + identity_assertion (v2) + assertion_expires

Loading

_{Reviews (8): Last reviewed commit: "Swap bespoke session plumbing for expres..." | Re-trigger Greptile}

[m0tzy]

@greptile

[m0tzy]

@greptile

[mthadley]

This was fine as we were prototyping, but for the sake of readability, maybe time to bring in a real template engine?

(Doesn't need to be done here, but maybe in a future refactor).

[m0tzy]

This is worth doing but I'll open another PR for it