ID-JAG step-up + auth_time freshness

[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 ← you are here
5. Claim anonymous registration via ID-JAG #12

Summary

Gate first-time linking of an ID-JAG to an existing account behind a user-confirmation ceremony, and reject ID-JAGs with stale or missing auth_time so agents have to refresh upstream.

Two distinct failure modes from /agent/identity for ID-JAG flows, both 401, with different error codes so the agent knows where to route:

• interaction_required — service-side step-up. The ID-JAG matched an existing user by verified email/phone but no (iss, sub) delegation yet. Body carries the same RFC 8628-shaped ceremony block as verified-email registration; the agent surfaces user_code + verification_uri to the user. The /claim page renders provider-aware copy ("Acme Provider is asking to link this account…") using the service's trust-list displayName. The matched email becomes the registration's claim_email, so the existing wrong-account check fires.
• login_required — provider-side re-auth required. ID-JAG missing or stale auth_time. The agent's recourse is at its provider (prompt=login or equivalent) — nothing the user does at the service helps. WWW-Authenticate carries max_age so the agent knows the threshold.

Without step-up, any trusted provider could mint an ID-JAG with email_verified: true for a victim's email and silently take over their account at the service. Step-up makes the user's signed-in session at the service the binding signal for linking external identities. The auth_time check stops agents from riding indefinitely-stale upstream sessions.

Service code

• config.idJagMaxAuthAgeSeconds: 3600 — hard-required, not nullable.
• trustedIssuers entries are now { iss, displayName }; trustedIssuerDisplayName(iss) resolves what the /claim page renders. Service-controlled so a malicious provider can't pick its own copy.
• verify.ts requires auth_time on every ID-JAG and rejects ones older than idJagMaxAuthAgeSeconds + clockSkew. Applied universally — including known (iss, sub) delegations — to prevent indefinite session piggy-backing.
• matcher.ts MatchResult is a discriminated union: { kind: "match" | "step_up_required" }. Email/phone matches no longer call upsertDelegation — they return step_up_required and let the route gate the binding.
• store.ts findOrCreateIdJagRegistration unified into one function with a context: { user } | { email } discriminator. Same deterministic (iss, sub, aud) key for clean-match and step-up — step-up is just the not-yet-claimed state of the same registration. completeClaim for id_jag registrations calls upsertDelegation(iss, sub, user.id) on success.
• agent-auth.ts handleIdJagStepUp returns 401 with the ceremony block; handleIdJagVerifyError maps auth_time_* codes to 401 login_required with WWW-Authenticate: AgentAuth error="login_required", max_age="…".
• claim.ts renders per-kind prompt copy. ID-JAG registrations get "Link <Provider> to your account?" wording.

Provider code

• session.ts freshens user.auth_time = new Date() on every login. The seed timestamp would otherwise be permanently stale; ID-JAGs would all read as expired.

Docs

• AUTH.md Step 3 ID-JAG: documents both 401 response shapes and the required auth_time claim.
• agent-providers/README.md: auth_time moves from optional to required; errors table adds interaction_required and login_required; Downstream Verification section names the three resolution paths (existing delegation / JIT / step-up).
• agent-services/README.md: new subsections on auth_time freshness and first-link step-up; user-matching policy updated to step-up on email/phone matches; trust-list guidance includes service-controlled display_name with CIMD as the production roadmap.

Smoke test

End-to-end verified:

1. alice signs up at service via email-verif (creates alice@example.com user)
2. alice signs in at provider, mints ID-JAG, presents to service → 401 interaction_required with registration_type: id-jag-step-up + ceremony block ✓
3. alice signs in at service, lands on /claim page rendered as "Link Agent Provider to your account?" ✓
4. alice submits user_code → 200; agent's next claim-grant poll on /oauth2/token returns access_token + identity_assertion with scope: api.read api.write ✓
5. ID-JAGs now carry auth_time (verified by JWT decode) ✓

[devin-ai-integration]

@greptileai review

[greptile-apps]

Greptile Summary

This PR gates first-time ID-JAG delegation binding behind a user-confirmation ceremony (interaction_required step-up) and universally rejects ID-JAGs with missing or stale auth_time (login_required), closing the account-takeover vector where a trusted provider could silently claim an existing user's account via a forged email_verified assertion.

• MatchResult is now a discriminated union; email/phone matches return step_up_required instead of silently calling upsertDelegation, and completeClaim now calls upsertDelegation for id_jag registrations so the binding is established only after the user confirms.
• verifyIdJag enforces auth_time presence and freshness in both directions (too-old and too-future), with separate 401 shapes carrying OIDC-standard interaction_required and login_required error codes so agents can route correctly.
• trustedIssuers entries carry a service-controlled displayName rendered on the /claim page, preventing a malicious provider from choosing its own confirmation copy.

Confidence Score: 5/5

Safe to merge; the core security invariants (no silent delegation binding, auth_time freshness enforced universally including future timestamps) are correctly implemented and the wrong-account check at the claim page gates step-up completion to the matched user.

The discriminated-union matcher, unified findOrCreateIdJagRegistration, and completeClaim delegation upsert all compose correctly. The race-resolution path in handleIdJagStepUp correctly falls through to emitIdJagSuccess when the ceremony completes concurrently. No sensitive tokens are logged, JWTs are validated with iss/aud checks, and the provider display name is service-controlled.

agent-services/src/routes/agent-auth.ts (escapeHeader CRLF gap) and AUTH.md (step-up user_code refresh path undocumented)

Important Files Changed

Filename	Overview
agent-services/src/verify.ts	Adds auth_time presence and freshness checks (too-old and future); error code auth_time_too_old is reused for the future-auth_time case where a distinct code would be clearer
agent-services/src/matcher.ts	MatchResult refactored to a discriminated union; email/phone matches now return step_up_required instead of silently binding the delegation — correct and well-scoped
agent-services/src/store.ts	findOrCreateIdJagRegistration unified with context discriminator; completeClaim now calls upsertDelegation for id_jag kind to bind the delegation on ceremony completion
agent-services/src/routes/agent-auth.ts	New handleIdJagStepUp and handleIdJagVerifyError handlers added; 409 guard removed to enable step-up; escapeHeader omits CRLF sanitization
agent-services/src/routes/claim.ts	promptCopy added for provider-aware step-up wording; all user-controlled values are properly escaped; wrong-account check runs before code validation
agent-services/src/trust.ts	trustedIssuerDisplayName added; display name is service-controlled and falls back to iss URL
agent-services/src/config.ts	trustedIssuers entries extended to {iss, displayName}; idJagMaxAuthAgeSeconds added as a required constant
agent-providers/src/routes/session.ts	auth_time freshened on every login so ID-JAGs carry a current timestamp rather than a permanently stale seed value
AUTH.md	Documents both 401 shapes and updates error table; step-up user_code refresh path for ID-JAG flows is undocumented

Sequence Diagram

sequenceDiagram
    participant Agent
    participant Service as POST /agent/identity
    participant Claim as /claim (browser)
    participant Token as POST /oauth2/token

    Note over Agent,Token: Happy path — known (iss, sub) delegation
    Agent->>Service: ID-JAG (auth_time fresh)
    Service->>Service: verifyIdJag → auth_time check ✓
    Service->>Service: matchOrProvision → kind: match
    Service->>Agent: 200 identity_assertion

    Note over Agent,Token: login_required — auth_time missing or stale
    Agent->>Service: ID-JAG (auth_time old / missing)
    Service->>Service: verifyIdJag → auth_time_missing or auth_time_too_old
    Service->>Agent: 401 login_required + WWW-Authenticate max_age
    Agent->>Agent: re-auth user at provider

    Note over Agent,Token: Step-up — (iss,sub) unknown, email matches existing user
    Agent->>Service: ID-JAG (auth_time fresh)
    Service->>Service: matchOrProvision → step_up_required
    Service->>Service: findOrCreateIdJagRegistration → ceremony minted
    Service->>Agent: 401 interaction_required + claim block
    Agent->>Token: POST claim_token (poll → authorization_pending)
    Claim->>Claim: user signs in, types user_code → completeClaim
    Claim->>Claim: upsertDelegation(iss, sub, user.id)
    Agent->>Token: POST claim_token (poll → 200 access_token)

Loading

_{Reviews (10): Last reviewed commit: "Replace remaining "ceremony block" refer..." | Re-trigger Greptile}

[m0tzy]

@greptile

[m0tzy]

@greptile