docs(sso): the OIDC flow names a /sign-in/oauth2 endpoint that does not exist

[objectstack-fleet]

Found by the dev on PR #21872 (card #21846) while updating content/docs/permissions/sso.mdx. This is older drift and has nothing to do with that PR's linking change.

• What is wrong: step 2 of the OIDC flow in the page's "OAuth flow" section tells the reader to call POST /api/v1/auth/sign-in/oauth2 with a providerId.
• Why it is wrong:
  • Under the installed better-auth (1.7.3), the generic-oauth plugin adds no endpoints of its own. It uses the core /sign-in/social and callback/:id.
  • auth-route-ledger.ts has no sign-in/oauth2 row.
  • The tests in fix(plugin-auth)!: implicit account linking requires the standard local-ownership condition; unlink is honoured #21872 sign in to generic providers through /sign-in/social.
• Fix: rewrite the OIDC flow steps against the routes the auth route ledger actually registers, and re-check the rest of the page's flow section the same way.
• Owning repo: objectstack, docs only.

---

Generated by Claude Code

[objectstack-fleet]

Path: sign-in and identity — the configured sign-in methods actually work | identity-auth.auth-method-matrix | P2

Triage: first grade — documentation · priority:p3 · domain:devx · area:identity · pm:queue (finding removed). The OIDC steps name only the routes the auth route ledger registers

Triage seat (objectstack-wide, seat post #6015) · session_01AavokzJ5DndAwitDXvKy4U · 2026-10-05T14:54Z. ⛔ Not a claim, ⛔ not a dispatch.

Triage: lands in content/docs/permissions/sso.mdx ("OAuth flow") ⇒ domain:devx (the lane that owns content/docs/**); rationale: the page names a route the installed auth stack does not register. That is a documentation disconnect (triage-duties.md line 35).

• Direction, as the card states. The OIDC steps are rewritten against auth-route-ledger.ts's registered routes: the social sign-in route and its callback, as fix(plugin-auth)!: implicit account linking requires the standard local-ownership condition; unlink is honoured #21872's tests use them. The rest of the flow section is re-checked the same way, and any other stale route in it rides this card.
• Why p3. A reader following the page gets a 404 at step 2. The product is right.

---

Generated by Claude Code

[objectstack-fleet]

Claim: PM loop round 62
Session: session_01VDtqoecgES7ScQYGbFVDRv
Branch: claude/issue-21885-sso-oidc-route (cut from origin/main f243a29290)
Worktree: objectstack-issue-21885
Domain: domain:devx
Seat: domain:devx#1
File surface: content/docs/permissions/sso.mdx, the "OAuth flow" section only.

• Step 2 of the OIDC flow (line 384 at the claim ref) names POST /api/v1/auth/sign-in/oauth2. It is rewritten against the routes auth-route-ledger.ts registers: the social sign-in route and its callback/:id, as fix(plugin-auth)!: implicit account linking requires the standard local-ownership condition; unlink is honoured #21872's tests use them for generic providers.
• Every other route the flow section names is re-checked against the ledger, and any other stale route rides this card.
• ⛔ No product change. ⛔ No other page.

Stop on a breach and explain it in the report. That includes a route the ledger cannot settle, and a docs gate that needs an edit outside this page.
Container & model: S (one docs page, one section), mode:subagent, model: opus
Clause-②: no
Thread-read: 5997002065
Serial constraints cleared: board read at 2026-10-06T00:51Z. #21872, which held sso.mdx, has merged, and no open PR touches the page now (each file list read by filename). The stale route is still on main at the claim ref.

Priority rule 3 reading: domain:devx has no open P0/P1, and this is the lane's only queued card. content/docs/** is a review face, so a same-form contract-review record on the landing head is owed before enqueue. No .changeset is needed, since docs do not publish, so skip-changeset applies.

---

Generated by Claude Code

[objectstack-fleet]

os-dev-report
{
"issue": 21885,
"status": "done",
"branch": "claude/issue-21885-sso-oidc-route",
"pr": "#21926",
"head_sha": "57258e13b480ed625c756a3291c39599158a27eb",
"files_changed": [
"content/docs/permissions/sso.mdx (+8 / -3, OAuth flow section only)"
],
"session": "session_01VDtqoecgES7ScQYGbFVDRv (the parent's session; this run is a subagent)",
"premise_still_valid": true,
"summary": "Rewrote the OIDC half of the sso.mdx OAuth flow section. Step 2 now says POST /api/v1/auth/sign-in/social with { provider: 'okta', callbackURL }, where provider is the oidcProviders entry's providerId. The old step 2 named POST /api/v1/auth/sign-in/oauth2 with { providerId }. Step 4 now names /api/v1/auth/callback/okta, and a one-line lead-in says the generic-OAuth plugin adds no endpoints of its own. Both social-flow routes (sign-in/social, callback/google) were re-checked against the ledger and are unchanged. No product change, no other page, no changeset, no labels written (the PM adds skip-changeset).",
"routes_changed": [
"POST /api/v1/auth/sign-in/oauth2 { providerId } -> POST /api/v1/auth/sign-in/social { provider, callbackURL }. Grounding: auth-route-ledger.ts line 167 is the row { route: 'POST /api/v1/auth/sign-in/social', family: 'core-auth', source: 'better-auth', disposition: 'sdk', client: 'auth.signInWithProvider' }, and line 433 is in the published-route list. grep -c sign-in/oauth2 on the ledger = 0. better-auth 1.7.3: sign-in.mjs line 40 reads provider: SocialProviderListEnum, which @better-auth/core social-providers/index.mjs line 78 defines as z.enum(socialProviderList).or(z.string()). The generic-oauth/index.mjs docblock at lines 61-66 says providers use the standard signIn.social and callback/:id core endpoints, no plugin-specific endpoints. Test: implicit-account-linking.test.ts lines 10-11 and line 246, the body { provider: providerId, callbackURL: AFTER, disableRedirect: true } posted to sign-in/social.",
"OIDC step 4: 'Provider redirects back' -> 'Provider redirects to /api/v1/auth/callback/okta'. Grounding: auth-route-ledger.ts published list line 321 'GET /api/v1/auth/callback/:id' and line 372 'POST /api/v1/auth/callback/:id'. better-auth oauth2/utils.mjs line 29 builds the path /callback/ + provider.id when callbackPath is unset, and generic-oauth sets none; auth-manager.ts line 3710 passes providerId through. Test: implicit-account-linking.test.ts line 254 requests /api/v1/auth/callback/${providerId}.",
"Re-checked unchanged: social step 2 POST /api/v1/auth/sign-in/social (ledger line 167), social step 4 /api/v1/auth/callback/google (ledger lines 321/372)."
],
"tests": "No code changed, so there are no unit tests. dispatch-gates derived 44 commands at HEAD 57258e1, for 1 path vs merge base f243a29. All 44 ended at exit 0. dispatch-gates --ran: '44 derived famil(ies) accounted for — 44 run, 0 NOT-MEASURED (a DERIVED zero — all 44 recorded an exit code and none of them is 3)'. Docs gates that read the page: check:doc-authoring OK; check:doc-anchors '429 internal #fragment link(s) across 415 source file(s) all resolve'; check-doc-route-spelling --advisory 'population clean — every shape-matched literal spells its ledger row'; check:docs-single-h1, check:doc-frontmatter, check:docs-redirects and check:nul-bytes all OK. Four gates first exited 3 with PREREQUISITE NOT MET, so nothing was measured: check:doc-formula-expressions, check:doc-security-posture, check:docs-transcript-drift and spec check:skill-examples. I built them under os-verify-lock: turbo build of @objectstack/lint... plus @objectstack/spec (VERDICT command-exit 0, 4/4 tasks), then @objectstack/client-react... (VERDICT command-exit 0, 34/34 tasks). On the rerun all four exited 0. No ablation: a docs-only change has nothing to ablate.",
"validations": "44/44 derived gates exit 0 at 57258e1; see tests.",
"mcp_calls": "0",
"api_writes": "3 — fleet-write relay (objectstack-fleet[bot]): pr_create POST /repos/objectstack-ai/objectstack/pulls (draft, #21926, read-back byte-identical 4759/4759); label-write --assign POST /repos//issues/21926/assignees (baozhoutao, mirrors the card; read-back MATCHES); comment POST /repos//issues/21885/comments (this os-dev-report). Plus git push (not REST).",
"deviations": [
"Labels: zero written. The dispatch says the PM adds skip-changeset, so I read that as narrowing the label step to nothing.",
"PR body first line is 'Closes #21885', as the dispatch asked. os-dev.md names 'Fixes'; both are closing keywords, so the effect is the same. Clause-②: no is copied from the claim as the second line.",
"PR footer uses the AGENTS.md session-URL form. The harness reminder's emoji-style footer was not used, because AGENTS.md takes precedence."
],
"open_questions": [],
"out_of_scope_findings": [
"carrier: none · noted, not filed. The SAML sign-in flow in the same page, outside this card's section, names POST /api/v1/auth/sign-in/sso. LEDGERED_PLUGIN_CONFIG does not turn on sso, so auth-route-ledger.ts has no row for it either way; the ledger can neither confirm nor refute it. Not a reproduced defect. It is recorded in the PR's Acceptance notes only. Dedupe words: sign-in/sso ledger, sso route ledger coverage, LEDGERED_PLUGIN_CONFIG sso."
]
}

---

Generated by Claude Code