docs: make CipherBox the identity-token issuer in the blueprint

[FSM1]

Records ADR 0008 (FSM1/cipher-box-next#64) in the blueprint. Documentation only, no code surface.

Draft until FSM1/cipher-box-next#64 is accepted — the decision corpus is normative and this repo carries the as-built statement of it, so this should not land ahead of the decision.

What changed and why

The blueprint conflated two authentications:

1. Unlocking the Core Kit — an identity provider vouches for the person; the Core Kit returns the TSS key.
2. Authenticating to the API — the engine signs a challenge with the derived identity key.

FSM1/cipher-box-next#28 D5 decided (2), correctly. (1) was never decided, and v2 built it as Web3Auth's hosted OAuth in the client wiring. That is what makes a wallet unable to start a session and leaves passwordless email delegated.

The account model is untouched, and that is the point: the Core Kit yields the same secp256k1 key whichever provider vouched, so api.md's "Account = the Web3Auth-derived identity key" holds either way.

blueprint/api.md

CipherBox becomes the identity-token issuer over its own JWKS. The method set is stated explicitly, with passwordless email as the API's own and wallet as a first-class first login on web only. The "SIWE stays a secondary auth method" clause goes — that is the clause ADR 0008 amends. Adds the note that Google's OAuth client ID is the provider's and is not the Web3Auth project client ID.

blueprint/web-client.md

Names the two authentications as distinct. States the shared-orchestration package and that credential collection is injected per host, with the boundary at credential collection rather than at the bearer token — v1 drew it at the token and its two hosts drifted. States that wallet is a first login here.

blueprint/desktop.md

States that the shell imports the same login package but not packages/client, whose worker, leadership and Service Worker machinery has no place there. Records that Google collection is genuinely native: GIS does not run in that webview, and a packaged Tauri origin cannot satisfy the redirect_uri the fallback flow needs, so the callback comes from a loopback listener. States that the wallet method is absent rather than offered and unable to complete.

Checks

markdownlint-cli2 and prettier --check both clean on all three files.

Note

Document CipherBox as the identity-token issuer in the authentication blueprint

• Updates api.md to reflect ADR 0008: CipherBox issues the identity JWT consumed by Core Kit, with each verified method (Google, passwordless email, wallet) minting the same CipherBox JWT rather than treating SIWE as secondary.
• Updates web-client.md to describe shared login orchestration via a host-agnostic package, and declares wallet (via wagmi) as a first-class login method on web.
• Updates desktop.md to document that Google OAuth uses a native loopback listener instead of an in-webview flow, and explicitly excludes wallet as a login method on desktop due to platform constraints.

^{Macroscope summarized 2de3c3a.}

Summary by CodeRabbit

• Documentation
  • Clarified authentication flows across web and desktop experiences.
  • Documented Google, passwordless email, and wallet sign-in behavior.
  • Wallet sign-in is now described as a supported web login option using SIWE.
  • Desktop authentication uses native Google OAuth handling and does not include wallet login.
  • Clarified that passwordless email codes are issued, verified, and delivered by the API.
  • Documented shared login orchestration while preserving host-specific credential collection.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 70689ba3-a4c9-4e51-bea4-0a00957f2f8b

📥 Commits

Reviewing files that changed from the base of the PR and between 892ca99 and 2de3c3a.

📒 Files selected for processing (3)

• blueprint/api.md
• blueprint/desktop.md
• blueprint/web-client.md

---

Walkthrough

The blueprints document CipherBox-issued identity JWTs, JWKS verification, shared login orchestration, web wallet authentication, and desktop-specific Google OAuth handling.

Changes

Authentication architecture

Layer / File(s)	Summary
API authentication contract blueprint/api.md	The API issues identity JWTs for Google, passwordless email, and web-only SIWE wallet login. Core Kit verifies the JWT through the API’s JWKS.
Web authentication orchestration blueprint/web-client.md	The web client shares login orchestration across hosts. Wagmi collects wallet signatures, while the API mints the identity token. The engine retains refresh-cookie handling through the Http seam.
Desktop authentication integration blueprint/desktop.md	The desktop shell uses shared login orchestration with a desktop credential collector. Google OAuth uses a native loopback callback, and wallet login is omitted.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related issues

• identity: implement ADR 0008 — CipherBox issues the Core Kit identity token #1253: Covers the same CipherBox-issued JWT, web wallet login, and shared authentication orchestration changes.
• api: issue the identity token the Core Kit consumes #1257: Covers the same API-issued JWT and JWKS authentication flow.
• web: make wallet a first-class first login #1260: Covers the same first-class web wallet login behavior.
• web: rebuild the web shell with login and the vault browser #642: Relates to wagmi-based SIWE signing and Core Kit login orchestration.

Possibly related PRs

• FSM1/cipher-box#660: Introduced the Tauri shell extended by the documented desktop authentication flow.
• FSM1/cipher-box#911: Implements the Core Kit, Google/email, and SIWE authentication flows described by the blueprints.
• FSM1/cipher-box#1035: Relates to the web and desktop authentication configuration and shared engine orchestration.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/blueprint-identity-token-issuer

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}