docs(auth): design the mobile SSO authorization bridge (M9) #23

wtclaude · 2026-07-20T22:08:05Z

wtclaude commented

2026-07-20 22:08:05 +00:00

What & why

Records the design for native Android "Sign in with Google/Discord" via a Mobile SSO Authorization Bridge, written before coding so the contract lives in docs/ first. Companion to the backend implementation in RunicGateway/website#80.

The bridge extends the existing /auth/sso/* redirect flow and terminates in the existing mobile bearer tokens — it is a new consumer of the session service, not a parallel auth path. Custom-scheme callback only for now; App Links deferred with a dedicated note.

website/BACKEND_DESIGN.md — mobile_auth_sessions / mobile_auth_codes schema (§3); the /auth/mobile/sso/{start,exchange} contract, the two PKCE layers, state/CSRF, the exact-match redirect-URI allowlist, TOTP parity, and the documented revocation-latency window (§4). Also corrects the device-sessions surface to /auth/me/sessions (distinct from /auth/me/devices, which is push).
android/PLAN.md — promotes §4.2's "possible later enhancement" to milestone M9 (backend-first, mirroring M7); status note.
android/APP_LINKS.md (new) — architecture note on the per-shard assetlinks.json / pairing multi-tenancy question. App Links deferred; the only server change they need later is more entries in the redirect-URI allowlist.

How it was tested

Docs only — Markdown reviewed for internal consistency with the code in website#80 (endpoints, table columns, env var names, and the /auth/me/sessions path all match the implementation).

Checklist

I have read CONTRIBUTING.md.
The change builds and existing tests/checks pass locally.
I have added or updated tests/docs where it makes sense.
My commits are reasonably scoped with clear messages.

AI-assisted contributions (required)

AI tools were used. Tool(s): Claude Code. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a Co-Authored-By trailer.

License

I agree that my contribution is licensed under this project's license (GNU GPL v3.0 or later), and I have the right to contribute it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr

## What & why Records the design for native Android "Sign in with Google/Discord" via a **Mobile SSO Authorization Bridge**, written before coding so the contract lives in `docs/` first. Companion to the backend implementation in `RunicGateway/website#80`. The bridge **extends** the existing `/auth/sso/*` redirect flow and terminates in the existing mobile bearer tokens — it is a new *consumer* of the session service, not a parallel auth path. Custom-scheme callback only for now; App Links deferred with a dedicated note. - **`website/BACKEND_DESIGN.md`** — `mobile_auth_sessions` / `mobile_auth_codes` schema (§3); the `/auth/mobile/sso/{start,exchange}` contract, the two PKCE layers, state/CSRF, the exact-match redirect-URI allowlist, TOTP parity, and the documented revocation-latency window (§4). Also corrects the device-sessions surface to `/auth/me/sessions` (distinct from `/auth/me/devices`, which is push). - **`android/PLAN.md`** — promotes §4.2's "possible later enhancement" to milestone **M9** (backend-first, mirroring M7); status note. - **`android/APP_LINKS.md`** (new) — architecture note on the per-shard `assetlinks.json` / pairing multi-tenancy question. App Links deferred; the only server change they need later is more entries in the redirect-URI allowlist. ## How it was tested Docs only — Markdown reviewed for internal consistency with the code in `website#80` (endpoints, table columns, env var names, and the `/auth/me/sessions` path all match the implementation). ## Checklist - [x] I have read [CONTRIBUTING.md](CONTRIBUTING.md). - [x] The change builds and existing tests/checks pass locally. - [x] I have added or updated tests/docs where it makes sense. - [x] My commits are reasonably scoped with clear messages. ## AI-assisted contributions (required) - [x] AI tools were used. Tool(s): `Claude Code`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-By` trailer. ## License - [x] I agree that my contribution is licensed under this project's license (**GNU GPL v3.0 or later**), and I have the right to contribute it. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr

wtclaude added 1 commit 2026-07-20 22:08:07 +00:00

docs(auth): design the mobile SSO authorization bridge (M9) 1aba1ff93d

Record the plan before coding: native Android "Sign in with Google/Discord"
via a Mobile SSO Authorization Bridge that extends the existing /auth/sso/*
redirect flow and terminates in the existing mobile bearer tokens.

- BACKEND_DESIGN.md: mobile_auth_sessions / mobile_auth_codes schema, the
  /auth/mobile/sso/{start,exchange} contract, the two PKCE layers, state/CSRF,
  exact-match redirect-URI allowlist, TOTP parity, and the documented
  revocation-latency window.
- android/PLAN.md: promote §4.2's "possible later enhancement" to milestone M9
  (backend-first, mirroring M7); status note.
- android/APP_LINKS.md: new architecture note on the per-shard assetlinks.json
  / pairing multi-tenancy question (App Links deferred; custom scheme only now).

Co-Authored-By: Claude <noreply@anthropic.com>

wtclaude referenced this pull request from RunicGateway/website

2026-07-20 22:08:32 +00:00

feat(auth): native SSO authorization bridge for the Android app (M9 Part 1) #80

whitlocktech approved these changes 2026-07-20 22:09:02 +00:00

whitlocktech merged commit b3fa93e9c4 into main

2026-07-20 22:09:09 +00:00

whitlocktech deleted branch docs/mobile-sso-bridge

2026-07-20 22:09:10 +00:00

whitlocktech referenced this issue from a commit

2026-07-20 22:09:10 +00:00

Merge pull request 'docs(auth): design the mobile SSO authorization bridge (M9)' (#23) from docs/mobile-sso-bridge into main

Sign in to join this conversation.