spec: issue-3626 Login code exchange instead of a token in the callback URL

[migmartri]

Summary

At the end of an OIDC login, the control plane sends the user session token to the client in the callback URL (?t=<token>). This spec replaces that with a short-lived, single-use handoff code. The client exchanges the code for the token at a new control plane endpoint. The code is bound to the client that started the login, with a PKCE-style challenge. The control plane also rejects a post-login redirect that is not a relative path.

Old CLIs keep working. The control plane supports both methods first, and clients move to the code exchange next. A login without a challenge keeps the legacy ?t= callback, and the info endpoint tells new clients that the exchange is available. A later release denies the legacy callback by default, with an operator setting to allow it again. The legacy callback is deleted when the oldest supported CLI uses the exchange and legacy use is zero for one release cycle.

Open questions for reviewers

None. The Decision Record (D-001 to D-010) lists the options that were rejected.

We would like two reviewers to approve this spec before it merges.

AI assistance: this spec was drafted with Claude Code and reviewed by the owner.

Refs #3626

🤖 Posted by Maximus bot (Claude Code) on behalf of @migmartri using the eng-autopilot skill

[chainloop-platform]

PR validation — ✅ 3 passing

Status	Policy	Material	Messages
✅ Passed	pr-min-approvals	pr-info	-
✅ Passed	pr-description-required	pr-info	-
✅ Passed	pr-user-story-linked	pr-info	-

_{View attestation ↗}

AI Session Checks — 🟢 92% · ✅ 0 failing

Avg score	Sessions	Failing policies	Attribution	Files	Lines	Total Duration
🟢 92%	1	✅ 0	100% AI / 0% Human	1	+263 / -33	48m8s

🟢 92% — 100% AI — ✅ All policies passing

Oct 15, 2026 16:13 UTC · 48m8s · $8.31 · 234 in / 146.8k out · claude-code 2.1.300 (claude-opus-5-5)

_{View session details ↗}

Change Summary

• Adds a new design spec for login-callback hardening in docs/specs/issue-3626-login-code-exchange.md.
• Opens a public parent issue and a draft spec PR for reviewer discussion.
• Revises the spec after feedback to log exchange-failure reasons and rename the callback parameter to handoff.

AI Session Overall Score

🟢 92% — Clean spec-authoring session; alignment, setup, scope, and user confidence were all strong.

AI Session Analysis Breakdown

🟢 95% · scope-discipline

🟢 Repo edits stayed on the single spec file the task called for. · High Impact

🟢 93% · user-trust-signal

🟢 Final feedback was constructive and explicitly called the points non-blockers. · High Impact

🟢 92% · alignment

🟢 The ask gave explicit public-repo and workflow constraints from the start. · High Impact

🟢 90% · context-and-planning

No notes.

abstained · solution-quality

🟡 Implementation quality was not assessed because this PR only changes a design spec. · Low Severity

abstained · verification

🟡 Runtime verification was not assessed because this PR only changes a design spec. · Low Severity

---

File Attribution

████████████████████ 100% AI / 0% Human

Status	Attribution	File	Lines
modified	ai	docs/specs/issue-3626-login-code-exchange.md	+263 / -33

---

Policies (4)

Status	Policy	Material	Messages
✅ Passed	ai-config-mcp-servers-allowed	ai-coding-session-4bff92	-
✅ Passed	ai-config-ai-agents-allowed	ai-coding-session-4bff92	-
✅ Passed	ai-config-no-dangerous-commands	ai-coding-session-4bff92	-
✅ Passed	ai-config-no-secrets	ai-coding-session-4bff92	-

Security Checks — ✅ 5 passing

✅ secret-scan

Status	Policy	Messages
✅ Passed	secrets-detection	-

✅ sast-scan

Status	Policy	Messages
✅ Passed	owasp-top10-2025	-
✅ Passed	sast	-
✅ Passed	cwe-top25	-
✅ Passed	cwe-top26-40-cusp	-

Scans not applied (3)

Scan	Reason
vulnerability-scan	no manifest/lockfile changed
github-actions-scan	no workflow files changed
iac-scan	no IaC files changed

_{View attestation ↗}

Security context

✅ Nothing this change touches has a recorded security-fix history.

_{View in Chainloop ↗ · How this works ↗}

---

Powered by Chainloop and Chainloop Trace

[matiasinsaurralde]

LGTM