/cross-app-shared-auth

name: cross-app-shared-auth
description: Blueprint for wiring many apps to one shared login plus a central accounts database, so a person has a single account across every app and access to each app accrues per app (opt-in, deny-by-default). Use this whenever onboarding a new app into a shared-auth family, setting up cross-subdomain SSO, building a central entitlement or "app access" database, adding per-app access gating, or when the user mentions one login for many products, shared accounts across apps, subdomain SSO, a central accounts service, app entitlements, or letting people sign up from any app OR a landing page and have it register centrally. Trigger even if the user does not say "shared auth" but describes a portfolio or family of apps that should share identity.

Cross-App Shared Auth

A repeatable blueprint for connecting a family of apps to **one shared identity** plus **one central accounts database**, so:

• a person has **a single account** across every app (sign in once, known everywhere),
• **access to each app is granted per app**, on demand, and accrues over time (not all-or-nothing),
• users can **sign up from any app OR from a central landing page**, and either path registers them centrally.

Use it two ways: to **stand up the platform** the first time, and to **onboard each new app** after that. When onboarding, follow the sequence in `references/onboarding-checklist.md` step by step.

---

The one idea to hold onto

**Identity is shared. Entitlement is per app.** These are two independent layers, and conflating them is the mistake that causes almost every problem in this space.

• **Identity** (who is this person): one shared auth provider issues one stable user id used by every app. Signing in on app A signs you in on app B too (SSO across subdomains). This does **not** grant access to app B.
• **Entitlement** (what may this person use): stored in a central accounts database keyed on that shared user id. Each app checks it. No record for this user and this app means no access (deny-by-default).

So "one login" and "you only get into the apps you have actually turned on" are not in tension. They are the intended combination.

Two slots, chosen independently:

| Slot | Job | Examples | |------|-----|----------| | Identity provider | issue one shared user id, handle sign in / sign up | Clerk, Supabase Auth, Auth0, Firebase Auth | | Central accounts store | hold per-app access records, keyed on the shared user id | Convex, Postgres, MySQL, any DB |

The database vendor is free per app. The only hard rule: apps that share one identity must share **one** identity provider instance, so the user id is common and joins everything.

Read `references/architecture.md` for the full picture with a diagram.

---

Prerequisites (have these before onboarding any app)

1. **One shared identity provider instance** for the whole family (not one per app). It should:

• be rooted at the parent domain so its session cookie is shared across subdomains (for example an instance anchored at the apex so `a.example.com` and `b.example.com` share it),
• expose a token/claim format the central DB can verify (many providers call this a JWT template; give it a known name so backends can request it, and make sure it stamps the audience the central DB expects, see guardrail 3).

2. **A central accounts database and API** (the entitlement store). It needs the schema and functions in `references/examples.md`: an `app_access` table (the whitelist), a `users` table (the identity link), and server-side functions `getAccess`, `activateApp`, `listMyApps`, `ensureUser`, all keyed on the shared user id and all deny-by-default. 3. **The central DB trusts the shared identity provider.** The central store verifies the provider's tokens (configure its auth with the provider's issuer). This is what makes the same user id resolve inside the central DB. 4. **A published, versioned platform contract.** One short document that pins the platform-specific values every app needs: the **template registry** (which backends have a JWT template, one per backend), the central store URL, the exact central function names, and the app-slug registry. Without it each app guesses, and invents mismatched APIs against a store that does not have them. Every app cites it by version, so a contract change signals apps to re-check. This is the source of truth the per-app record block points at.

If any of these is missing, build it first. Everything else assumes they exist.

---

The onboarding sequence (per new app)

This is the heart of the skill. When adding an app to the family, do these in order. The full checklist with commands and gotchas is in `references/onboarding-checklist.md`.

1. **Inspect first.** Determine the app's framework, whether it already uses the shared identity provider, and whether any accounts wiring already exists. Never assume a clean slate. If the app is not yet on the shared identity provider, that is a dependency: resolve it before the accounts wiring, and do not rebuild it. 2. **Confirm shared identity.** The app uses the shared provider's keys (same publishable key + issuer), not its own instance. For a subdomain family, it pins `authorizedParties` to its own origin (see the security note below). 3. **Add a client to the central accounts DB**, separate from the app's own database. Authenticate it by requesting the central store's **token template** (for example `getToken({ template: "<name>" })`), not the bare session token, so the token carries the audience the store checks and the central DB resolves the same user id. Confirm that template, and one for the app's own backend if it differs, exist in the platform's template registry first (guardrail 3); if the app is the first on a new backend, add its template before wiring. Call the central functions by reference, since the app repo does not have the central DB's generated types. 4. **Wire the gate.** Separate the two checks. Un