diff --git a/README.md b/README.md index b86dbdc..f0e0a0e 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ The point is painfully simple: ## Front Door -- **Value:** one shared auth authority: provider OAuth (Discord, Patreon, GitHub, Twitch, YouTube, Spotify), linked identities, grants, entitlements and session issuance, with Ed25519-signed claims that app backends verify locally. +- **Value:** one shared auth authority: provider OAuth (Discord, Patreon, GitHub, Twitch, YouTube, Spotify, Google OIDC for linking), linked identities, grants, entitlements and session issuance, with Ed25519-signed claims that app backends verify locally. - **Problem:** every GameCult app was rebuilding Discord/Patreon login glue. Heimdall centralizes identity authority and keeps app-domain data in the apps. - **Entry points:** - `src/index.ts` and `src/app.ts`: the Fastify service. `src/signing.ts` and `src/claims.ts` issue JWTs and serve `/.well-known/jwks.json`; `src/oauth.ts` and `src/providers.ts` own provider flows. diff --git a/deployment/idunn/recipe.toml b/deployment/idunn/recipe.toml index f520258..8179280 100644 --- a/deployment/idunn/recipe.toml +++ b/deployment/idunn/recipe.toml @@ -138,11 +138,16 @@ route_required = true optional_environment = [ "CULTMESH_URI_ODIN_RUDP", "GC_ACCESS_APP_BIFROST_BACKEND_CALLBACK_URLS", + "GC_ACCESS_APP_BIFROST_RUNTIME_IDS", "GC_ACCESS_APP_BIFROST_SHARED_SECRET_FILE", "GC_ACCESS_APP_GHOSTLIGHT_BACKEND_CALLBACK_URLS", "GC_ACCESS_APP_GHOSTLIGHT_RUNTIME_IDS", "GC_ACCESS_APP_GHOSTLIGHT_SHARED_SECRET_FILE", + "GC_ACCESS_APP_REPIXELIZER_BACKEND_CALLBACK_URLS", + "GC_ACCESS_APP_REPIXELIZER_RUNTIME_IDS", "GC_ACCESS_APP_REPIXELIZER_SHARED_SECRET_FILE", + "GC_ACCESS_APP_STREAMPIXELS_BACKEND_CALLBACK_URLS", + "GC_ACCESS_APP_STREAMPIXELS_RUNTIME_IDS", "GC_ACCESS_APP_STREAMPIXELS_SHARED_SECRET_FILE", "GC_ACCESS_APPLY_SCHEMA_ON_STARTUP", "GC_ACCESS_BIFROST_PATRON_SUPPORT_ENDPOINT", @@ -156,16 +161,21 @@ optional_environment = [ "GC_ACCESS_PRIVATE_COMMAND_PORT", "GC_ACCESS_PROVIDER_DISCORD_CLIENT_ID", "GC_ACCESS_PROVIDER_DISCORD_CLIENT_SECRET_FILE", + "GC_ACCESS_PROVIDER_GITHUB_CLIENT_ID", "GC_ACCESS_PROVIDER_GITHUB_CLIENT_SECRET_FILE", + "GC_ACCESS_PROVIDER_GOOGLE_CLIENT_ID", + "GC_ACCESS_PROVIDER_GOOGLE_CLIENT_SECRET_FILE", "GC_ACCESS_PROVIDER_JOYSTICK_CLIENT_ID", "GC_ACCESS_PROVIDER_JOYSTICK_CLIENT_SECRET_FILE", "GC_ACCESS_PROVIDER_PATREON_CLIENT_ID", "GC_ACCESS_PROVIDER_PATREON_CLIENT_SECRET_FILE", + "GC_ACCESS_PROVIDER_SPOTIFY_CLIENT_ID", "GC_ACCESS_PROVIDER_SPOTIFY_CLIENT_SECRET_FILE", "GC_ACCESS_PROVIDER_TWITCH_CLIENT_ID", "GC_ACCESS_PROVIDER_TWITCH_CLIENT_SECRET_FILE", "GC_ACCESS_PROVIDER_YOUTUBE_CLIENT_ID", "GC_ACCESS_PROVIDER_YOUTUBE_CLIENT_SECRET_FILE", + "GC_ACCESS_REFRESH_TTL_SECONDS", "GC_ACCESS_SESSION_TTL_SECONDS", "GC_ACCESS_SIGNING_KEY_ID", "GC_ACCESS_SIGNING_PRIVATE_KEY_BOOTSTRAP", @@ -190,7 +200,7 @@ schema_generation = "heimdall-v1" [[state.slots]] id = "service" -relative_path = "heimdall.service.cc" +relative_path = "cultcache/heimdall.service.cc" kind = "cultcache-file" schema = "heimdall.service_state.v1" writer = "process-bound-single-writer" diff --git a/docs/answer-collector-consent.md b/docs/answer-collector-consent.md new file mode 100644 index 0000000..ca8175e --- /dev/null +++ b/docs/answer-collector-consent.md @@ -0,0 +1,265 @@ +# Answer Collector: Record and Consent + +Status: specification. Nothing here is implemented. It fixes what an answer +record is and what a respondent has agreed to, so that a collector, a tally and +a training export can be built against one definition. Field names and types +below are the contract for the typed CultCache records. + +Scope: free-text and choice answers that members give to a sample put to them +by an experiment. Not identity proof (see `architecture.md`). Personal details +(names, contact data, account identifiers, anything that identifies a person) are +out of scope: the collector does not ask for them and a sample must not solicit +them. The only identifier it keeps is `member_id`, and that stays on the reward +path. + +## Notice + +Consent is declared once per room, not per reply. Each experiment room carries +one notice that names the scope the room's answers may be used for and the way +out. A notice has a `notice_version`; any change to its wording or scope is a new +version. + +### Where the notice lives + +A room's notice is a Matrix room state event: type `org.gamecult.notice`, empty +`state_key`, content `{version, scope}`. + +- `version` follows the version rule under Representation. +- `scope` is `show`, `study` or `train`. +- The event is set under the room's power levels. A pinned message is not + accepted as a notice: anyone who can pin could forge it. +- Absent or malformed (a missing or unknown field, a `version` the version rule + does not accept, an unknown `scope`) means no `train` + line and the narrowest scope, `show`. Malformed content is never repaired. + +The wording shown to respondents is the room's own business; the collector reads +only `version` and `scope`. A change to either is a new state event and so a +new `version`. + +| scope | what the notice allows | +|---|---| +| `show` | display back inside the experiment (to the respondent, and in aggregate to participants). Nothing else. | +| `study` | `show`, plus analysis by the experiment's researchers. Quoted in findings only unattributed. | +| `train` | `study`, plus use as training or evaluation data for models. | + +`train` is a declared scope: it is used only when the notice for that room says +`train` in terms. It is never inferred, never a default, and never raised by a +reply. + +The first reply a member posts in the room is their acceptance of the notice +version then in force. No separate click, command or form. A later notice version +needs a new acceptance: the member's first reply under it. + +### Notice acceptance record + +| field | type | rule | +|---|---|---| +| `member_id` | Heimdall member id | the accepting member. | +| `experiment_id` | string | the room. | +| `notice_version` | integer | the `version` of the room's notice state event when the reply was received. | +| `scope` | `show` \| `study` \| `train` | the scope that version declared. | +| `accepted_at` | UTC timestamp | `origin_server_ts` of the first reply. | +| `event_id` | Matrix event id | that reply, as proof. | + +Key: `(experiment_id, member_id, notice_version)`. Written once, never updated. + +## Terms (newcomers only) + +Joining Heimdall is gated by terms. Acceptance is the terms version recorded by +the Matrix `m.login.terms` stage at registration: member field `terms_version` +(string) and `terms_accepted_at` (UTC timestamp). These fields belong to the +Heimdall member record. A typed `MemberTerms` record keyed by `member_id` is the +shape of that pair in a typed library; it is not a second store, and the +collector does not hold it. This applies to newcomers +only. Members who joined before the terms stage existed, and Minds, are not +re-asked and have no `terms_version`; the collector does not read it and does not +gate on it. The notice above is the only consent the collector itself checks. + +Open gap: the registration checkbox records no version. Void is raising this; +nothing here rules it. + +## Answer record + +One record per answer. Fields: + +| field | type | rule | +|---|---|---| +| `sample_id` | string `@` | names the thing answered about; `` follows the version rule under Representation. A changed sample is a new version. | +| `experiment_id` | string | the experiment that asked. | +| `member_id` | Heimdall member id | the respondent. Never a Matrix id, never a display name. | +| `notice_version` | integer | the notice version in force when the answer was received; matches an acceptance record by the key above. | +| `scope` | `show` \| `study` \| `train` | copied from that notice version at answer time. Never edited afterwards. | +| `text` | string, or absent | the answer as given. Non-empty while the answer is live; absent once exited. | +| `exited` | boolean, default false | one-way: set by redaction, never cleared. A new answer is a new record. | +| `text_hash` | 32 bytes, or absent | the tombstone hash of `text` (see "Tombstone"). Present only once exited, and only when the collector held `text` before the redaction. | +| `received_at` | UTC timestamp | assigned by the collector when it receives the reply. Not copied from the reply. | +| `event_id` | Matrix event id | the reply; the receipt. | + +Key: `(experiment_id, sample_id, member_id)`. A member's later answer to the +same key replaces the earlier one (latest `received_at` wins); the earlier text +is not retained. Two replies to one key with equal `received_at` tie-break on +`event_id` compared bytewise: the greater `event_id` wins as the later reply. + +Empty text: a live (non-exited) answer must have non-empty `text`, and the +collector rejects a reply whose text is empty. Empty text is valid only on an +exited answer, where redaction clears `text` and leaves the hash-only tombstone. + +A reply whose `notice_version` or `scope` is missing, unparseable or has no +matching acceptance record is stored, with those fields absent. It is excluded +from every use: no tally, no display, and from training in particular. It +writes no acceptance record. The reply is kept so the member can still exit it +and the collector can show what it refused, but no scope was declared, so none +is inferred. The notice version of a reply is the one the room's notice state +event held at the reply's `origin_server_ts`; if the collector cannot establish +what it held then, the reply has no notice version. + +### Representation + +- Timestamps are Unix milliseconds in UTC, stored as a signed 64-bit integer, + the unit of Matrix `origin_server_ts`. Every "UTC timestamp" above means this. +- `member_id`, `experiment_id` and `event_id` are non-empty strings; + `member_id` is opaque and `event_id` is the Matrix event id verbatim. +- Version rule. Every version field in the consent system is a positive integer + written in decimal with no leading zeros and at most 4294967295 (u32 max): + the `` of `sample_id` (`s@`), `notice_version`, the + `version` of the room notice `org.gamecult.notice`, and the notice acceptance + and terms records (`terms_version`, carried as that decimal string). Anything + else (zero, a sign, whitespace, a non-digit, a leading zero such as `s@01`, a + value above the maximum) is refused, not normalised: `s@1` is the only + spelling of version 1, so one version has exactly one key. A room notice + whose `version` fails the rule is malformed: no `train` line, narrowest scope + `show`. Nothing is silently rewritten to fit. +- Two encodings of the one version rule. In the `org.gamecult.notice` room state + event, `version` is a JSON number; a string (including `"01"`) is malformed. + In the answer key (`s@`, and the composite keys), the version stays + its encoded decimal text, held to the leading-zero refusal. The rule is the + same in both: a positive integer, no leading zeros, at most 4294967295. +- A composite key is its parts joined with U+001F. A part that is empty or + contains U+001F is refused, not escaped. + +## Versions + +Answers never tally across `sample_id` versions. A tally is computed for one +full `sample_id` including version; there is no "all versions" aggregate and no +API that takes a sample without a version. A version bump starts an empty tally. +Replies to an old version are dropped when the tally is for a newer one. + +## Training rule + +A record is training or evaluation data only if all hold: + +1. `scope = train`, copied from a notice version that declared `train`; +2. an acceptance record exists for `(experiment_id, member_id, notice_version)` + of the answer, its own `scope` is `train` and equals the answer's `scope`, + and `accepted_at <= received_at`, i.e. the author had accepted that notice + version when they answered; +3. `exited = false` at export time. + +Open gap: `accepted_at` is the homeserver's `origin_server_ts` and `received_at` is the collector's own clock, so +condition 2 compares two clocks. If the collector's clock is behind the homeserver's, a member's first answer (which is +also their acceptance) can fail `accepted_at <= received_at` and is excluded. That fails closed, never opens `train` +wrongly. The remedy is to compare on one clock (keep the reply's `origin_server_ts` on the answer); this revision does +not rule it. + +No recorded scope, or no recorded acceptance, means excluded. Records wider than +`show` are kept apart from `show` records: one store per scope (`show`, `study`, +`train`) plus a store for scopeless replies that no read path serves. A record +lives in the store its `scope` names, so a read for one level cannot return +another. A typed-record library need not model the partition; the collector's +store layout owns it. + +## Tombstone + +- Function: HMAC-SHA-256 (RFC 2104 with SHA-256, FIPS 180-4), output the raw 32 + bytes stored in `text_hash`. No truncation. +- Message: the ASCII string `heimdall.tombstone.v1`, U+001F, `event_id` + (UTF-8), U+001F, `text` (UTF-8, as received, no normalisation). The `event_id` + makes the hash specific to the reply, so equal texts hash differently. +- Key (the salt): 32 bytes from a cryptographically secure random source, + generated once per member by the member-side service, which is the service that + already maps Matrix sender to `member_id`. It is held there, beside the member + record, and is never given to the collector, a researcher, an export or a log. + The collector cannot compute or check a tombstone hash on its own. +- Redaction: when the collector sees a redaction of a reply whose text it holds, + it sends `event_id` and `text` to the member-side service, which returns the + hash; the collector writes `text_hash`, sets `exited`, and erases `text`. If the + service does not answer, `text` is kept, the record is not yet exited, and the + run retries. A reply the collector never collected has no text and gets no + tombstone. +- Verification: only the member-side service can check a claimed text against a + tombstone. If a member's salt is destroyed, their tombstones can no longer be + tied to any text, and that is the member's erasure. + +## Identity: count once, reward without exposure + +The Matrix sender is mapped to a Heimdall member id by Heimdall's linked +identity, at collection time. The collector stores `member_id` only; the Matrix +sender is discarded after mapping. A sender with no linked member is dropped, +not stored under a placeholder. + +- Count once: the key above makes one member one answer per sample version, + however many Matrix accounts or bridges they use. +- Reward without exposure: a reward is issued against `member_id` by the + rewarding service. Researchers and displays see counts and text under their + scope, never `member_id`. The mapping from a record to a person is available + to the reward path only. + +## Eureka's shape (Matrix) + +- One room per experiment. The room is `experiment_id`. +- The sample is posted as a message; the room's notice is its `org.gamecult.notice` state event. An answer + is a thread reply to the sample, the answer text being the body. There is no + per-reply scope syntax. +- The reply event is the receipt: its event id and timestamp are the proof the + answer was received. `received_at` is the collector's own clock at receipt, + not the reply's `origin_server_ts`. +- Redaction is exit (see below): redacting the reply event sets `exited`. +- The collector is on demand (it reads the room when run, it is not a standing + listener). It drops: + - redacted replies (recorded as exited); + - replies from unlinked senders; + - replies to an old sample version when the tally is for a newer one. + +## What Matrix cannot guarantee + +- **Receipt outliving a deleted reply.** Redaction removes content, and + homeserver retention varies. If the collector holds a receipt for a reply that + later disappears, it keeps a tombstone: `event_id`, `sample_id`, `received_at`, + and a salted hash of `text`. Hash only, never text, and no `member_id` + beyond what the record's key already holds. The count and the exit are + provable without the content. The record is marked `exited`; `text` is erased. + The tombstone is the exited `Answer` record itself, with `text_hash` set; it is + not a separate record. +- **Edits.** An edit is a new event, not the receipt. Only the original event + counts; edits are ignored, so what was accepted is what was received. To + change an answer, redact and reply again. +- **Bridge spoofing.** A bridge can post as any ghost user. Only senders whose + Matrix id resolves through Heimdall's linked identity to a member count; + bridged ghost ids are not linked identities. A bridge cannot raise scope: scope + comes only from the room's notice state event. +- **Bridged origin.** Events that arrive through a bridge are dropped by origin, + not by judging their text. + +## What the respondent sees + +Posted with the sample, in the room: + +- the notice: its scope in one line, that the first reply accepts it, and how to + exit; +- the notice version. + +After answering, the respondent sees their receipt: the thread reply itself, +plus the collector's acknowledgement that names the notice version and scope it +recorded. + +The consent and vote controls make no reward sound, animation or other +reinforcement. A reward is issued later, by the rewarding service, never as +feedback to the act of consenting or voting. + +## How to exit + +Redact your reply. That is all. The next collection run sets `exited`, erases +`text`, and excludes the record from every later tally and from training. It +cannot undo past use: tallies already shown and anything already exported +cannot be recalled by Matrix or by the collector. The experiment's page states +the export cadence so the window is known. diff --git a/docs/app-profiles/bifrost.md b/docs/app-profiles/bifrost.md index 976452f..9a7926c 100644 --- a/docs/app-profiles/bifrost.md +++ b/docs/app-profiles/bifrost.md @@ -77,3 +77,37 @@ patron points locally. This route is a bridge from auth-owned Patreon evidence to Bifrost-owned governance meaning. Heimdall still does not own points, votes, tiers, ledger history, or payout policy. + +## App-asserted step-up + +Bifrost's profile carries `stepUpAssertion: { methods: ["bifrost-passkey", +"bifrost-email-code"] }`, the only such grant. With its secret and a member's +live Heimdall bearer, Bifrost calls `POST /v1/apps/bifrost/step-up` with +`{method, nonce}` after it has checked the factor itself, and receives an access +token for the same session whose `step_up_at` and `step_up_method` satisfy +Heimdall's unlink check. Bifrost must send a fresh nonce per assertion, keep +the returned token only for the action it is for, and never send a method it did +not verify: Heimdall cannot tell. Contract, codes, limits and what it does not +prove are in `docs/service-contract.md`. + +Precondition and limit: Bifrost can call this only while it holds the member's +Heimdall bearer, which it deliberately does not today. Holding it in a cookie +ticket would turn cookie theft into bearer theft and, with a passkey or email +code, into unlink power. And unlink accepts any method: a `bifrost-email-code` +proof can unlink an identity a Google re-authentication would have guarded. +Requiring a method per route is the later hardening (identity moves). + +## Identity moves + +Bifrost's profile carries `identityMoves: { accountProofMethods: +["bifrost-passkey"] }`, the only such grant (its methods are a subset of +`stepUpAssertion.methods`). With its secret, `POST /v1/apps/bifrost/identity-moves` +moves logins from one Heimdall account to another when it presents fresh proofs +of both: Bifrost's merge saga owns survivor choice, preview and undo timing; +Heimdall moves what the proofs cover. A proof through one login moves only that +login; an asserted `bifrost-passkey` proof covers the whole source account; +`bifrost-email-code` proves an inbox and does not. A multi-login source without a +passkey therefore needs one fresh sign-in per login. Until the Google client is +live, a member's strong proof is the asserted passkey only; Discord and Patreon +give weak (300 s) proofs. Contract, refusal order and idempotency are in +`docs/service-contract.md`. diff --git a/docs/architecture.md b/docs/architecture.md index 8ae5c19..956b1db 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -154,7 +154,11 @@ The important split: - Heimdall owns provider OAuth, identity linking, entitlement refresh, signed sessions, claims, grants, audit surfaces, and managed provider credential - custody + custody. It authenticates; it does not issue GameCult identity. Bifrost is + the identity provider, and the account id Heimdall mints is an authenticator + handle. Remaining scar: Heimdall still creates that account id on first + login (`store.createAccount`, `src/app.ts`), which the chat work does not + need moved - the host experiment owns its workload, queue, editor, render path, viewer profile model, creator model, or other product-specific machinery - the host experiment also owns which local entity a connection attaches to, @@ -332,6 +336,49 @@ access token (`revoked`) or no refresh is due (`current`; due means a known expiry within 5 minutes, a stored refresh token, and a runtime that refreshes). It never decides that a refresh happens. +### One writer for `linked_identities` moves + +An identity belongs to the account that holds it. `upsertLinkedIdentity` writes +the holder's own row (`ON CONFLICT (provider, provider_user_id) DO UPDATE ... +WHERE linked_identities.account_id = EXCLUDED.account_id`; it never sets +`account_id`) and throws `IdentityHeldElsewhereError` when another account holds +the identity. `unlinkLinkedIdentity` is the only delete: one transaction locks +the account row, refuses the account's last identity, and deletes the row only +for the account that holds it. The store role therefore holds DELETE on +`linked_identities`, checked at startup. The HTTP side (`/v1/me/identities`) is +in `service-contract.md`; an unlink needs a step-up proof inside 600 seconds. + +`moveIdentities` is the only statement that sets `linked_identities.account_id` +to another account, reached only through `POST /v1/apps/{app}/identity-moves`. +One transaction locks both accounts in id order (opposite moves queue, they do +not deadlock), answers a repeated `moveId` from its `identity_moves` row, +re-checks the proof sessions, applies `decideMove` (one pure function both stores +call, so memory and Postgres cannot disagree), moves the rows with credentials +stripped, revokes the source's sessions, expires its pending links and unredeemed +completions, and appends the row. `identity_moves` is append-only (SELECT and +INSERT only, checked at startup). An alias (an account with no login and an +unreversed move from it) is derived inside the transaction to refuse moves into +or out of it, never stored; nothing resolves an alias to its destination, because +no consumer needs it and a chain of moves would make one hop wrong. + +### Step-up proof has two sources + +An access token's `step_up_at` is set in exactly two places: the `sign_in` +step-up callback (Heimdall asked the provider to re-authenticate; label +`provider:`) and `assertStepUp`, the app-asserted route (the app says it +checked a factor; label from the profile's `stepUpAssertion.methods`). Both +feed the one reader, `proofTier` in `claims.ts` (unlink and identity moves both +read it: `strong` is a step-up inside 600 s, `weak` a sign-in inside 300 s via +`auth_at`), and a refresh sets neither. `proofCovers` says what a proof speaks +for: only a strong proof whose method the profile lists as an account proof +covers the whole account; any other proof covers the one login in +`auth_identity_id`. The +asserted route trusts the calling app and is bounded by the app secret, a live +bearer for that app, the method allowlist, a nonce claimed once per session +through `claimOAuthStateUse` (phase `step_up_assert`, no new table or grant; +retained to the session expiry as of the claim, which a refresh may slide past), +and in-process fixed-window limits (`src/fixed-window.ts`). + ### Three nested guards 1. **Single flight, per process.** `refreshesInFlight` is keyed by store, then @@ -443,13 +490,12 @@ builder was not used. process, so N Heimdall processes can present one token N times after a transient failure. Needs a failed-attempt marker on the row, read under the lock. Must land before or with Idunn onboarding. -- `joystick:follow_up:connect-start-needs-app-auth`: connect starts are - unauthenticated, so anyone can name `{creator, targetId}`; the callback - re-check proves a binding exists, not that the caller owns it. It also owns - the whitespace-only `targetId` that passes both gates and the callback's - fail-open `''` fallback for a vanished profile (finding - `joystick:finding:cut-h1.s4.whitespace-targetid-passes-custody-gate`). Must - land before the public Joystick bot or a second creator. +- `joystick:follow_up:connect-start-needs-app-auth` (Heimdall side done): a + connect start that names a connection target needs the app's own secret for + every managed provider, and a blank target is refused at start and at the + callback mint. What StreamPixels must do on its side is in + `notes/streampixels-connect-redeem.md`; its redeem must refuse a creator + connect whose target it did not start. - `joystick:follow_up:heimdall-idunn-onboarding` (gamecult-ops): live Heimdall is a hand-copied release under `heimdall.service`, not an Idunn-admitted generation; the recipe's Joystick lines are declared but unproven by a @@ -613,8 +659,9 @@ Only the browser-driven OAuth flow: | Path | Why it must be public | |---|---| -| `/v1/oauth/{provider}/start` | the user's browser goes here | -| `/v1/oauth/{provider}/callback` | the provider redirects here; one-shot and not retryable | +| `/v1/oauth/{provider}/start` | the app's server calls it, with its app secret where the profile requires one | +| `/v1/oauth/{provider}/launch` | the user's browser goes here first; it sets the binding cookie and redirects to the provider, once per state | +| `/v1/oauth/{provider}/callback` | the provider redirects here; one-shot: it needs the binding cookie and consumes the state | | `/.well-known/jwks.json` | *nothing external consumes it today* — see below | Everything else is internal by the design already written down: diff --git a/docs/joystick-consent-flow.md b/docs/joystick-consent-flow.md new file mode 100644 index 0000000..3fafec6 --- /dev/null +++ b/docs/joystick-consent-flow.md @@ -0,0 +1,237 @@ +# Joystick sign-in and consent: what was missing, and the flow that fills it + +Status: built (sections 3-6 describe the code on this branch); sections 1-2 are +the state of `fefd2dd` (main) that motivated it. Follow-up +`heimdall-body:follow_up:chat-s3124-3129`, built under +`heimdall-body:follow_up:chat-mind-20261108T131253147Z-t1`. The steward's rulings +on the five open questions are in section 4. + +## 1. What a viewer sees today + +**Joystick viewer sign-in does not exist.** `streampixelsProfile` +(`src/app-profiles.ts:109-117`) lists Joystick only in +`managedConnectionProviders`. `admitsProviderForMode` (`:243`) admits `sign_in` +and `link` only for `identityProviders`, so +`POST /v1/oauth/joystick/start` with `mode: sign_in` returns +`400 provider_not_supported_for_app` as JSON before any redirect +(`startOAuthFlow`, `src/app.ts:598-603`). The viewer sees whatever the app does +with a failed start; Heimdall shows them nothing. The architecture doc records +this as deliberate until the public bot is registered +(`docs/architecture.md:461`, `joystick:follow_up:joystick-viewer-signin-public-bot`). + +**The only live Joystick path is a creator `connect`.** Walking it as the +person in the browser: + +1. The app backend starts the flow (authenticated by app secret, `connection` + `{kind: creator, targetId}`). The person's browser is sent to + `/v1/oauth/joystick/launch?state=...`. +2. `launch` (`src/app.ts:1130-1194`) claims the state, sets the binding cookie + and answers `302` straight to `joystick.tv/api/oauth/authorize`. **Heimdall + renders no page of its own.** Nothing says who is asking, for what, or what + will be kept. +3. The only ask the person sees is Joystick's own screen, listing the scopes in + `providerCatalog.joystick.defaultScopes` (`src/providers.ts:162`): + `identity:read stream:read chat:read followers:read subscribers:read`. + Joystick words that screen, not us. +4. The callback (`:1196`) exchanges the code, stores the credential encrypted + (rotating refresh token, managed custody), and returns the generic handoff + page (`src/browser-handoff.ts`): title "Authentication Complete", body "You + can return to the app now." It does not name the app, the provider, the + scopes granted, or that a long-lived refresh token is now held by Heimdall. +5. Refusal: if the person clicks Deny at Joystick, the callback gets + `error=access_denied`, and the page says "Authentication Failed ... Return to + the app to continue." The provider's own text is relayed only in + `errorDescription` in the fallback URL fragment / postMessage payload, not + shown on the page. Refusing *at Heimdall's step* is impossible: there is no + Heimdall step. +6. After: the audit rows `oauth_callback_succeeded`, `auth_completion_created`, + `managed_credential_revoked` etc. (`createAuditEvent` call sites, e.g. + `app.ts:1582`) are written for operators. There is **no route a viewer can + call to read them**, and no route a viewer can call to revoke a credential. + Revocation exists only inside the app backend plane (`managed-credential.ts:172`). + +## 2. What consent is missing + +| Gap | Today | Why it matters | +| --- | --- | --- | +| Visible ask | None from Heimdall; provider screen only | The person cannot tell Heimdall custody (refresh token kept, rotated, used for stream/chat/follower reads) from a one-off login. | +| Who is asking | Not shown | Two parties act: the app (StreamPixels) and Heimdall as custodian. Neither is named. | +| Scope truth | Provider screen lists scopes; Heimdall's `requestedScopes` / `defaultScopes` are not shown or compared with what was granted | Granted scopes can differ from requested; the stored `scopes` (`app.ts:1406`) are never shown. | +| Typed refusal | A deny is an untyped `provider_error` | The app and the audit log cannot tell "viewer said no" from "provider broke". | +| Receipt | Operator audit rows only | The viewer cannot audit what was agreed, when, or revoke it. | +| Viewer vs creator | The `connect` binding proves a binding exists, not that the browser's owner is the creator (`joystick:follow_up:connect-start-needs-app-auth`) | Consent from the wrong person is not consent. | + +## 3. The consent flow + +Applies to every completion `callbackMint` calls `custody_only`: a managed +creator connection (Joystick today; Twitch and YouTube on StreamPixels when +they are connected rather than signed in). Viewer sign-in through an identity +provider is unchanged. + +### 3.1 The ask + +`GET /v1/oauth/:provider/launch` renders a Heimdall page (`src/consent.ts`) +instead of answering `302`, after the state verifies and before any use is +claimed. The page names the app and the origin the person returns to, the +provider and the exact scopes Heimdall will send (`authorizationScopes`, the +same function that builds the authorization URL), what Heimdall keeps (an +encrypted refresh token and access token, until the person takes it back or the +provider ends it), what the app receives, and how to take it back. It carries +two POST forms to `/v1/oauth/:provider/consent`, **Continue to Joystick** and +**No, return to the app**, and runs no script. It sets the ask's own +cookie (`__Host-heimdall-ask-`), which carries the exact text shown and is +accepted only by Continue and No; an answer without it is `state_not_bound` and +spends nothing. Viewing the ask claims nothing and binds nothing: the launch +binding cookie, which decides who may complete the state, is set only when +Continue claims the launch, and it carries the text shown on to the callback. +(An earlier cut set the binding on the ask, so anyone holding the launch URL +could become the state's owner; review of 2026-11-08 found it.) + +What the app receives, stated as the code does it: not a claim. The app +backend can call `managed-credentials/resolve` and receive the current access +token; it never receives the refresh token. The earlier draft said the app +receives "no token"; that was wrong and the page does not say it. + +### 3.2 Typed refusal + +A decline, and a provider `error=access_denied` on any provider, produce the +result `consent_refused` with `by: "viewer" | "provider"`: an audit event +`consent_refused` (provider, mode, by; no account, no person), the browser +attempt denied with `denialCode consent_refused`, both uses of the state spent, +a `backend_callback` app told with the same payload, a "Not Connected" page in +the browser, and `400 {error: "consent_refused", by}` as JSON. No credential is +stored and no receipt is written. Every other provider error stays +`provider_error`. This changes the `access_denied` answer for every provider, +including Bifrost's and Repixelizer's sign-in; see the PR for the contract note. + +### 3.3 Receipt + +On a granted `custody_only` completion Heimdall writes one `consent_receipts` +row of kind `grant`: id (random), account, app, provider, scopes asked, scopes +granted (as the provider returned them), `consentText` (the lines and +button labels shown, taken from the ask and never rebuilt, so a deploy between +ask and callback cannot change what the receipt says), `consentPageDigest` +(sha-256 of that text), `createdAt`. A custody callback with no shown text +exchanges no code and stores no credential. The id +reaches the app (`consentReceiptId` in the completion and backend payloads) and +the person (the handoff page). + +Receipts are append-only: the store role has `SELECT` and `INSERT` on the table +and nothing else. A revocation is a second row of kind `revocation` naming the +grant it takes back, unique per grant (a partial unique index); a grant is live +exactly when no revocation names it, and a concurrent second revoke reports +nothing and writes nothing. The +draft's `revokedAt` slot is gone for that reason. + +### 3.4 My grants + +Signed in means a live Heimdall access token for any app (`Authorization: +Bearer`), or a page link minted from one. + +- `GET /v1/me/grants`: every grant and receipt of the account. `Accept: + text/html` gets the page, one **Take this back** form per live grant; anything + else gets `{grants, receipts}`. +- `POST /v1/me/grants/link` (bearer): `{url}` to the page, valid ten minutes. + The token is signed, purpose-bound (`heimdall_grants_page`), stateless, and + opens only this page and its revoke forms. The forms on a page opened by a link + carry the link's own expiry, so using a link never renews it. This is how a browser that holds no + session gets in; Heimdall sets no new cookie and stores nothing for it. +- `POST /v1/me/grants/:id/revoke` (bearer, or the page token in the form): + strips the stored tokens from the credential, then writes a revocation row + for every live grant on that credential. The credential is one row per account + and provider, whichever app asked, so taking it back ends every grant resting + on it. The next `managed-credentials/resolve` answers `410 + managed_credential_revoked`; nothing else needs to learn of it. Revoking a + revoked grant changes nothing. Another account's grant id is `404`. + +Heimdall can delete its copy; it cannot withdraw the permission at the +provider, and the page says so. + +## 4. The steward's rulings + +Each ruling picks the answer that gives the person the most agency and leaves +the least stored. + +1. **Who gets the ask: managed custody only.** Where Heimdall holds a credential + the person cannot see and an app can use, the person is asked and given a + receipt. A login is already asked by the provider's own screen, and a receipt + per login would store a row per sign-in for no agency the provider's screen + does not give. The line is `callbackMint === "custody_only"`, so it needs no + second list to keep in step with the profiles. +2. **The receipt is a new typed table, `consent_receipts`.** The audit table is + operator-shaped and has no read path for the person; a viewer-readable + record in it would make every audit row a potential disclosure. The table + holds ids, scopes and a digest: no IP address, no user agent, no page text. A revocation names a + receipt of its own account: a composite foreign key `(revokes_receipt_id, + account_id)` to `(id, account_id)`, which is why `(id, account_id)` is also a + unique key (`checkSchema` counts it). The in-memory store refuses the same. The table is created + whole and first-created: no deployed database had an earlier shape, so there + is no `ALTER` step. + Refusals leave no receipt, only the anonymous audit row. +3. **Viewer identity: sign-in, not the cookie.** The binding cookie dies with + the state and proves only that a browser launched a flow; it is not an + account. The receipt page and revoke require a live access token or a + ten-minute link minted from one. The cost is that a first-time creator must + hold the session the completion returned to the app; the app mints the link. + The alternative, a new long-lived Heimdall cookie, would store a session for + every person who merely looked. +4. **`consent_refused` reaches a backend callback app.** An app that started the + attempt and is waiting must be told, or it polls to expiry and cannot tell + a person's no from a fault. The person's no is also not held against them: + Heimdall stores nothing and sets no cooldown; whether and when to ask again + is the app's rule. +5. **Wording: derived, not authored.** The text is generated from facts the code + holds and states nothing the code does not do; it is a constant in + `src/consent.ts` and its digest rides every receipt. Legal review of the + wording (the CultCoin legal thread) may only narrow it, and any change moves + the digest. Until that review lands the copy is Heimdall's, signed by the + steward. +6. **Bounds on what rides the cookies.** The wording is read from a cookie + only up to 16 KB inflated, so a compressed bomb is refused, not expanded. An + app may request at most 32 scopes of 512 characters (`requested_scopes_too_large` + at the ask). A custody callback whose binding carries no wording is refused + with `consent_text_missing` before the state is claimed, so nothing is burned. + +### Refusal return contract (for app authors) + +A person's No at the ask, or a provider `access_denied`, is `consent_refused`. +No completion code is minted and the state is spent. What each side gets: + +- **Browser.** A 200 HTML page titled "Not Connected" (a non-HTML caller gets a 400 + JSON `{error, by, provider, returnTo}`). The page does not redirect: by ruling + it never navigates on its own. It posts the payload to `window.opener` + (target origin = the origin of `returnTo`), tries `window.close()` after 50 ms, + and offers a "Return to the app" link. In a plain tab the person clicks it. +- **The link** is `returnTo` with a fragment (read `location.hash`; it never + reaches a server): `heimdall_status=error`, `heimdall_error=consent_refused`, + `heimdall_refused_by=viewer|provider`, `heimdall_provider`, + `heimdall_handoff_kind`, `heimdall_app_slug`, `heimdall_mode`, and + `heimdall_attempt_id` when the flow carries an attempt. There is no + `heimdall_completion_code`; a page with none, and `heimdall_error`, is a refusal. + A fault is a different `heimdall_error` (`provider_error` and others). +- **postMessage** carries `{source: "heimdall", kind: "oauth_result", + status: "error", error: "consent_refused", by, provider, appSlug, mode, + returnTo, handoffKind, attemptId?}`. +- **Backend callback apps** get the same result POSTed to their callback URL + (`status: "error"`, `error: "consent_refused"`, `by`, `attemptId`). An auth + attempt is marked `denied` with `denialCode: "consent_refused"`, which + `completeAuth` returns as `denied`. + +`tests/joystick-consent.test.ts` ("the refusal return contract") pins the +fragment for both refusals and the attempt id. + +## 5. Out of scope + +Enabling Joystick in `identityProviders`; fixing +`joystick:follow_up:connect-start-needs-app-auth`; revoking at the provider +(Joystick offers no revocation call Heimdall uses); retention or deletion of +consent receipts and of the audit rows; consent for the creator's audience. + +## 6. Tests + +`tests/joystick-consent.test.ts` holds one behaviour per rule above. Rules were +checked by mutation, each mutant run on its own with a 300 s limit under an 8 GB +address-space cap (the PR lists them). The Postgres statements for +`consent_receipts` are exercised by `tests/store.test.ts` against the fake pool +and, when `HEIMDALL_TEST_PG_ADMIN_URL` is set, against a live database +(`scripts/test-live-pg.sh`); the live run was not possible where this was built. diff --git a/docs/service-contract.md b/docs/service-contract.md index 1567ae5..6b77caa 100644 --- a/docs/service-contract.md +++ b/docs/service-contract.md @@ -119,6 +119,7 @@ Supported providers in the skeleton: - `youtube` - `spotify` - `joystick` +- `google` Request body: @@ -149,12 +150,29 @@ Response: "appSlug": "repixelizer", "mode": "sign_in", "callbackUrl": "https://heimdall.gamecult.org/v1/oauth/discord/callback", - "authorizationUrl": "https://discord.com/oauth2/authorize?...", - "stateToken": "", + "authorizationUrl": "https://heimdall.gamecult.org/v1/oauth/discord/launch?state=", "stateExpiresAt": "2026-04-26T12:10:00.000Z" } ``` +Send the user's browser to `authorizationUrl` unchanged. It is Heimdall's launch +hop, not the provider's URL. + +### `GET /v1/oauth/{provider}/launch?state=` + +The first thing the user's browser does with a state. Heimdall verifies the +state (signature, issuer, provider, `nbf`/`exp` with 30 s of skew), claims the +state's single launch, sets the binding cookie +`__Host-heimdall-oauth-` (`Path=/`, `Secure`, `HttpOnly`, `SameSite=Lax`, +`Max-Age` until the state expires; the value is a Heimdall-signed binding for +that state) and answers `302` to the provider's authorize URL, with +`Cache-Control: no-store` and `Referrer-Policy: no-referrer`. A second launch of +the same state is `400 state_already_launched` and sets no cookie. The state is +refused with `400 invalid_state`, `state_provider_mismatch` or `state_expired`. + +The binding cookie needs an `https` public base URL (or `localhost`). A browser +must finish the flow in the browser that launched it. + Failure modes: - `503 provider_not_configured` when the provider client id is missing @@ -168,7 +186,46 @@ Failure modes: - `401 app_auth_required` when the request body carries `entitlementPolicy` and the caller did not authenticate as that app via `x-heimdall-app-secret` (`resolveAppCaller`, `src/app-caller.ts`) -- this applies regardless of - `handoff.kind` or app slug; a caller with no policy to attach needs no secret + `handoff.kind` or app slug; a caller with no policy to attach needs no secret, + unless the app's profile sets `startRequiresAppCaller` (Bifrost only): then + every start for that app, with or without a policy, needs that app's secret. + Bifrost binds browser completion to a nonce that rides readable in the signed + state's `return_to`, so only Bifrost may mint a Bifrost state; apps whose + browser starts are public by design leave the flag unset +- `401 app_auth_required` also when `mode` is `connect` and the body carries a + `connection` (a creator or account target): a connection target is app-backend + authority, so only the authenticated app named by `appSlug` may start it. No + secret, or another app's, is refused before any state is signed. `sign_in` + starts carrying a `connection` are `400 connection_not_allowed_in_sign_in` + +Step-up (`stepUp: true`, sign_in only, off by default): + +- Asks the provider for a real re-authentication on the authorize URL, so a + provider session already open in the browser is not enough to complete the + sign-in. The start request field is `stepUp`; the signed state carries it as + `step_up`, and the launch hop builds the provider URL from the state alone. + Nothing on the callback or redeem side can set or clear it (a `stepUp` in a + redeem body is ignored), and a completion reports it as `stepUpRequested: true` + when the start asked. +- It is the authenticated app's request, like a connection target: no secret or + another app's is `401 app_auth_required`; a `link` or `connect` start carrying + it is `400 step_up_only_in_sign_in`; `stepUp: false` is the same as absent. +- Provider parameters (`stepUpAuthorizationParams`, `src/providers.ts`): Twitch + `force_verify=true`, YouTube `prompt=login consent` (consent is kept; the + provider always asks it), Google `prompt=login`. **The strengths differ.** + Google `prompt=login` forces the person to re-authenticate. Twitch + `force_verify` re-shows the authorize page: it proves a person at that browser + chose to continue, not that they entered credentials. A consumer that needs + credentials re-entered must not rely on Twitch step-up. +- A provider with no such parameter (Discord, Patreon, GitHub, Spotify, + Joystick) is `400 step_up_not_supported`, with the provider named, before any + state is signed. The URL builder throws rather than omit the step. +- A `backend_callback` handoff delivery does not carry `stepUpRequested`; only the redeemed completion does. +- A state signed by a build with step-up and launched by an older build loses the step + silently (the older parser ignores `step_up`): deploy every Heimdall instance on one + release, with no mixed window. +- Heimdall requests the step; it cannot observe that the provider honoured it. + `stepUpRequested` says "asked", not "verified". Launch note: @@ -179,6 +236,45 @@ Launch note: implemented yet - Repixelizer launch can configure Discord and Patreon on its provider buttons +### Google (OpenID Connect, link-only) + +`google` is an identity provider that never mints an account. It is a second +door into a person who already has one. + +- Callback redirect URI (register exactly this in the Google Cloud OAuth + client): `{GC_ACCESS_BASE_URL}/v1/oauth/google/callback`, which is + `https://heimdall.gamecult.org/v1/oauth/google/callback` in production. +- Scopes `openid email profile`. The authorization request carries `state` + (signed, Heimdall's), a `nonce`, and a PKCE `S256` challenge, all built at the + launch hop, which is where the browser first meets the provider URL. The verifier + and the nonce are derived from the state's `jti` and Heimdall's signing key, + so nothing is stored between start and callback. +- The callback verifies the `id_token` (RS256 against Google's published + keys; `iss` is Google, `aud` is this client, `exp`, `iat`, `nonce`) and + requires a `sub` and a verified email. The account key is `sub`; the email + is a display and contact field and never a lookup key. +- `mode: "link"` needs `Authorization: Bearer ` for the + same app; the identity attaches to that token's account and to no other. + `mode: "sign_in"` signs in an account the `sub` is already linked to. +- A `sub` no account holds, arriving with `sign_in`, is refused and mints + nothing. A `sub` linked to another account is refused and never moved. + Both audit as `oauth_callback_failed` with error class `LinkRefusal` + and the code `identity_not_linked` or `link_initiator_mismatch`. +- Link is two-phase. The callback verifies the identity and records a pending + link (TTL `completionTtlSeconds`), answering `status: "link_pending"` with a + `pendingLinkId` and no session; it writes no linked identity. The app calls + `POST /v1/apps/:appSlug/links/confirm` with `{ pendingLinkId }` and the + Heimdall access token of the account that began the link; only that call + attaches the identity. A different account, an expired, used or unknown id + answers 410; a `sub` another account holds by then answers 409. A refused + confirm does not consume the link. +- A sign-in callback evaluates every linked identity of the account with the + start-time entitlement policy, so a member returning through Google keeps + what Discord or Patreon grant. +- Configure with `GC_ACCESS_PROVIDER_GOOGLE_CLIENT_ID` and + `GC_ACCESS_PROVIDER_GOOGLE_CLIENT_SECRET_FILE`. Admitted to the `bifrost` + app profile only. + ### `GET /v1/oauth/{provider}/callback` Purpose: @@ -189,7 +285,11 @@ Purpose: Current status: -- validates signed `state` +- validates signed `state` (signature, issuer, provider, expiry), requires the + binding cookie the launch hop set, and consumes the state: a second callback + is `400 state_already_used`, a missing or foreign cookie `400 state_not_bound`, + an expired state `400 state_expired`; the binding is checked before the claim, + so a browser without the cookie cannot burn the launching browser's state - returns provider errors cleanly - for Discord, exchanges the authorization code, resolves the provider identity, persists the local account/link/session/audit records, evaluates @@ -334,6 +434,11 @@ Request body: } ``` +Binding rules: + +- A completion minted for a connection target (`connection.targetId` in the signed state) is redeemed only with `targetId` equal to it; absent or different answers `403 completion_target_mismatch` and leaves the code unconsumed. +- A `link` completion is redeemed only by the authenticated app backend (`x-heimdall-app-secret`); otherwise `401 app_auth_required`, code unconsumed. `link` start itself needs that authentication and `initiatingAccountId`; the callback refuses with `403 link_initiator_mismatch` when the provider identity belongs to a different account, and attaches an unlinked identity to the initiator. + Response: ```json @@ -443,6 +548,256 @@ Important behavior: - the endpoint is not a provider OAuth start path and should not produce a provider authorization URL +### `GET /v1/me/identities` + +The identities the signed-in account holds, for a member's own view. + +Authentication: a live Heimdall access token for any app as +`Authorization: Bearer` (the same check as `/v1/me/grants`). `401 +sign_in_required` otherwise. The answer is `Cache-Control: no-store`. + +```json +{ + "accountId": "uuid", + "identities": [ + { + "id": "uuid", + "provider": "twitch", + "providerUserId": "12345", + "username": "name", + "displayName": "Name", + "linkedAt": "2026-11-13T12:00:00.000Z", + "scopes": ["user:read:email"] + } + ] +} +``` + +`username` and `displayName` are present when the provider gave them. The +answer never carries a token column, the stored provider profile or the +account's email. + +### `POST /v1/me/identities/{identityId}/unlink` + +Takes one identity off the signed-in account. It is the only way a linked +identity is deleted, and it never takes the account's last one. + +Authentication: a live Heimdall access token for any app, and fresh proof. The +body is empty or `null`. + +- `401 sign_in_required`: no live bearer. +- `403 step_up_required`: the access token carries no `step_up_at` claim, or it + is in the future, or it is older than 600 seconds + (`STEP_UP_PROOF_TTL_SECONDS`, `src/claims.ts`). The remedy is a `sign_in` + start with `stepUp: true` (see step-up above) through an identity on the + account whose provider has re-authentication parameters, today twitch, + youtube and google, then the access token that sign-in returns. +- `404 identity_not_found`: no such identity, or one that belongs to another + account. The two are not distinguishable. +- `409 last_identity`: the account holds no other identity. +- `200`: `{"unlinked": {"id", "provider", "providerUserId"}, "identities": [...]}` + with the remaining list in the shape above. + +`step_up_at` (epoch seconds) is set on the access claim only when the callback's +signed state has `step_up` true and mode `sign_in`, or by an app's `POST +/v1/apps/{appSlug}/step-up` assertion (below). A refresh never carries it: +tokens a refresh issues cannot unlink, so proof is renewed only by a new step-up +sign-in. The unlink writes the audit event `identity_unlinked` (provider and +identity id only). When the account then holds no identity of that provider, the +revocation receipts for its live grants of that provider are written, as the +grants revoke route writes them. + +A Twitch step-up proof is weaker than YouTube's or Google's: `force_verify` does +not force credential re-entry (see the step-up note under the OAuth start +section, "The strengths differ"). + +Limits that stay: + +- Access tokens issued before the unlink keep the unlinked identity in their + `identities` claim and its facts until they expire (`sessionTtlSeconds`). +- Discord and Patreon identities cannot give proof (no re-authentication + parameter); an account holding only those cannot unlink. +- A stolen access token minted by a step-up sign-in can unlink more than one + identity during its 600 second window. +- A sign-in through a provider whose identity is no longer linked mints a new + account. + +A link no longer moves an identity: `upsertLinkedIdentity` refuses an identity +another account holds (`links/confirm` answers `409 identity_linked_elsewhere`, +the callback `link_initiator_mismatch`). An unlinked identity belongs to no +account and can be linked by any account through the normal link flow. + +### `POST /v1/apps/{appSlug}/step-up` + +An app asserts that a member just passed a factor the app itself checked (for +Bifrost: a passkey assertion or an emailed code), and receives an access token +that carries that proof. The unlink route's step-up check then passes unchanged. + +Authentication: both, always. + +- the app's secret in `x-heimdall-app-secret`, as for every app route; and +- the member's live Heimdall access token for the same app as + `Authorization: Bearer`. + +Body (`additionalProperties` are dropped as on the sibling routes): + +```json +{ "method": "bifrost-passkey", "nonce": "16 to 128 characters, fresh per assertion" } +``` + +Nonce: 16 to 128 characters of the base64url alphabet (`A-Za-z0-9_-`), so a +random token fits and spaces, controls and lone surrogates are a 400 schema +refusal. `method` is 1 to 64 characters and then must be in the profile's set. + +Schema validation (body shape, `method` length, the nonce pattern and length, +the app slug) runs before the secret is checked and answers `400` with +Fastify's fixed schema error, the same for every caller whatever the secret and +never audited. Then the order of refusals, each a closed `error` code: + +- `401 app_auth_required`: missing, wrong or another app's secret. The first + check of the handler; nothing is written. +- `403 step_up_assertion_not_permitted`: the app's profile has no + `stepUpAssertion` grant. Only `bifrost` has one; every other app is refused + with its own secret. This branch has its own small budget (5 per 60 s per + app); past it the answer is 429. +- `429 step_up_rate_limited` (`retryAfterSeconds`): the per-app budget (120 per + 60 s, spent by every attempt that passed the secret and the grant, including + ones whose bearer then fails) is spent. In-process fixed windows: they reset + when the process restarts and are not shared between instances. +- `401 sign_in_required`: the bearer is missing, malformed, expired, signed by + another key, a refresh token, or rests on a session that is not live (no row, + wrong account, revoked or expired, revision moved). One answer for all of + them; it does not say whether an account exists. +- `403 bearer_app_mismatch`: a live bearer issued to another app. An app cannot + assert for a token issued to another app. It tells only a holder of the + secret and a valid bearer that the bearer is live and for another app, which + that holder already knows. +- `429 step_up_rate_limited`: the per-account budget (10 per 600 s) is spent. + It is checked after the bearer and its audience, before method and nonce. +- `400 unknown_step_up_method`: `method` is not in the profile's closed set + (`methods` in the answer lists it). Bifrost: `bifrost-passkey`, + `bifrost-email-code`. Provider labels (`provider:*`) cannot be asserted. +- `409 step_up_nonce_replayed`: that nonce was already spent for this session. + The claim is the store's `oauth_state_uses` single-use primitive with phase + `step_up_assert` and the key a SHA-256 of session id and nonce, so it holds + across restarts and instances. **Retention is the session's expiry as of the + claim plus 10.5 minutes (the 10 minute prune margin and 30 s clock skew), and + pruning is lazy: each successful claim deletes at most 50 expired rows.** A refresh slides the session's expiry + without bound, so a nonce can be pruned while its session is still live and + then be accepted again. Replaying it still needs the secret and a live + bearer, which is the power to assert with a fresh nonce; the nonce guards a + captured request, not a compromised app. A refused method or a rate-limited + attempt does not spend the nonce. +- `201`: `{"accessToken", "claimSet", "stepUp": {"at", "method", "validForSeconds"}}`, + `Cache-Control: no-store`. + +What the minted token is: a copy of the bearer's claims with a new `jti`, +`iat` and `nbf`, `step_up_at` = now and `step_up_method` = the asserted method. +It keeps the bearer's `exp`, same `sid` and account. Facts, capabilities and +identities are the bearer's and are not recomputed, so the route adds proof and +no capability. It mints no refresh token and writes no session row: it cannot +extend a lifetime or a session. A later refresh carries neither claim. The proof +is good for the usual 600 seconds (`STEP_UP_PROOF_TTL_SECONDS`) and only until +the token's own `exp`. + +Receipts: each assertion writes the audit event `step_up_asserted`, and each +refusal after the secret verified writes `step_up_assertion_refused`, except +that two kinds are not recorded row by row: a rate-limited refusal is recorded +once per window per budget (its first; the row's `budget` names `app`, +`account` or `notPermitted`), and an app without the grant once per window. +Every other refusal under budget still writes a row each, up to about 121 a +minute for a holder of the secret, and `audit_events` has no retention: that is +an open follow-up. Rows carry the +app, the account and session when the bearer resolved, `method` (null when it +was not in the allowlist), `outcome`, `code`, `budget` (rate-limit rows) and `nonceDigest`. Never the +secret, the bearer, the minted token or the nonce. A request without the secret, +or failing schema validation, writes nothing. + +Precondition: the route is usable only once the app holds the member's Heimdall +bearer. Bifrost deliberately does not hold it today. Putting the bearer in a +cookie ticket would turn cookie theft into bearer theft and, with +`bifrost-passkey` or `bifrost-email-code`, into unlink power; whether and how +Bifrost keeps the bearer is its own decision and is not made here. + +Unlink accepts any method today. A `bifrost-email-code` proof unlinks an +identity a Google re-authentication would have guarded. Identity moves +(below) are the first route to require a method for whole-account coverage; +unlink is unchanged. + +What this does not prove: Heimdall cannot see the passkey or the code. It trusts +the calling app's word, exactly as it trusts `stepUpRequested` (asked, not +verified). The word is bounded by the app secret, a live member bearer for that +app, the profile's method allowlist, a single-use nonce, the proof window and +the rate limits. A compromised Bifrost can assert proofs only for members whose +live bearer it holds. `identity_unlinked` records the proof's `stepUpMethod` +(`provider:`, an app label, or null), and unlink does not yet require any +particular method. + +### `POST /v1/apps/{appSlug}/identity-moves` + +The one sanctioned way a login changes account (`moveIdentities` is the only +writer of `linked_identities.account_id`). Bifrost owns the merge: survivor +choice, preview, grace and undo timing. Heimdall receives the choice as which +proofs fill which side, renders no preview and picks nothing. Only a profile with +`identityMoves` may call it (today bifrost). + +Credential: the app's secret. Body (closed; unknown properties are ignored, and +no account is ever named by the body): + +- `moveId` (`^[A-Za-z0-9_-]{16,64}$`): the caller's idempotency key. +- `fromProofs`: 1 to 8 live Heimdall access tokens for this app, all of the + source account. +- Forward move: `toProof` (a live token of the destination) and optionally + `identityIds` (1 to 32; default every login the source holds). +- Reversal: `reversesMoveId` instead of `toProof`/`identityIds`. It moves back + exactly the logins the forward move carried, once; `fromProofs` must be of the + forward move's destination. A reversal is not itself reversible. + +Each proof must be fresh: a step-up inside 600 s (`strong`) or a sign-in inside +300 s (`weak`), by `proofTier`, the same freshness rule the unlink route reads. +A token with neither claim (a refresh, a link) is stale. + +Coverage: a proof through login X (`auth_identity_id`) moves X and nothing else +from that account. Only a strong proof asserted with a method in the profile's +`identityMoves.accountProofMethods` (`bifrost-passkey`; not `bifrost-email-code`, +which proves an inbox) speaks for the whole account. Moving several logins takes +one proof per login, or the passkey. + +Order of refusals, each a fixed code: `401 app_auth_required`; `403 +not_allowed_for_app`; a replayed `moveId` is answered next (below); `409 +not_reversible` (reversal names a missing, foreign or reversal move); `403 +proof_invalid` `{proof: "from"|"to"}` (not a live bearer of this app, or +`fromProofs` naming two accounts); `409 same_account`; `403 proof_stale` +`{proof}`; `403 identity_not_proved`; then the store: `403 proof_invalid` (a +proof session lapsed under the lock), `409 already_moved` (either side is an +alias), `409 provider_conflict` `{provider}`, `409 not_reversible`, `409 +move_id_conflict`, `404 identity_not_found`, `403 identity_not_proved`. A refusal +body is `{error, detail?, proof?, provider?}` and never names an account id, an +identity the caller did not send, an email or a name. + +On success, in one transaction: the logins move to the destination with their +stored credentials stripped; every live session of the source is revoked and its +pending links and unredeemed completions expire; one append-only `identity_moves` +row is written. Afterwards, for each moved provider the source no longer holds, +its live grants get revocation receipts under the source, and `identity_moved` +is audited. Answer `200`, `Cache-Control: no-store`: +`{moveId, accountId: , movedIdentityIds, proof: {from, to}, reversesMoveId?}`, +with `proof.from` `strong` if any from-proof was strong and `to` null on a +reversal. + +Idempotency: the same `moveId` with the same app, accounts and `reversesMoveId` +answers the stored receipt byte for byte, even though the first success revoked +the source's sessions: the proofs are then checked for a valid Heimdall +signature, issuer, type and audience, and account, not for liveness. The replay +re-runs the revocation receipts, so a crash between commit and receipts heals on +the caller's retry. Anything else under a used `moveId` is `409 move_id_conflict`. + +What a move leaves: an account holding no login with an unreversed move from it +is an alias: derived at move time, never stored, and no route resolves it. A +move into or out of an alias is `already_moved`. Bearers of +the destination keep their old identity list until they refresh. A sign-in +through a moved login lands on the destination because the row moved. + ### `POST /v1/apps/{appSlug}/managed-credentials/resolve` Purpose: @@ -491,12 +846,34 @@ Important behavior: identity (`SELECT ... FOR UPDATE`), so a given refresh token is presented to the provider once across concurrent requests and across two Heimdall processes sharing one database. Within one process, concurrent refreshes of - one identity share a single attempt and its outcome (success or failure), so - nobody re-presents a token behind a failed holder in that burst. Residual - risk, tracked as follow-up `joystick:follow_up:cross-process-failed-refresh-marker`: - the guard is one presentation per process per burst, so N - Heimdall processes can present one token N times after a transient failure. - The provider call is bounded at 10 seconds + one identity share a single attempt and its outcome (success or failure). A + failed or timed-out attempt is recorded on the identity row + (`refresh_failed_at`, written in the same transaction as the lock), and no + process presents that row's refresh token again for 60 seconds: a process + that takes the lock inside the backoff answers the same + `managed_credential_refresh_failed` without calling the provider. A stamp + more than 60 seconds in the future (a writer whose clock runs ahead) is skew, + not a fresh failure, so the wait is capped at twice the backoff. A rotation, + a revocation or a re-link clears the marker. + The marker is a best-effort write on a second connection, made after the + lock's transaction rolled back; it is not part of that transaction. When the + rotation or the revocation the provider's answer called for cannot be + committed, the fallback write leaves the marker and blanks the refresh token + only when that token is spent: on a revoke (a rotating provider answered + without a refresh token, or the grant was rejected), or when the provider + rotates refresh tokens (Joystick) and so consumed it. A provider that keeps + its refresh token valid (Twitch) keeps it, so a transient database failure + does not strand the link: the next caller after the backoff presents it again. + Residual risk: the provider may consume the refresh token as soon as the + request is sent. If a Heimdall process dies after that and before the commit + of the marker, the rotation or the revocation, or if the blanking fallback + write fails too, nothing is recorded, and the + next caller can present the refresh token the provider already consumed; for + a provider that rotates (Joystick) that reads as token theft. The Heimdall + steward ruled (#minds, 2026-11-08) that an intent log, written on its own + connection before the provider call, replaces this marker; it is tracked in + `joystick:follow_up:write-ahead-refresh-attempt-record`. + The provider call is bounded at 10 seconds. - a provider whose refresh tokens rotate (Joystick) fails closed: a refresh response without a new refresh token revokes the credential instead of keeping the old token @@ -556,6 +933,10 @@ Current claim payload fields: - `typ` - `account_id` - `access_revision` +- `step_up_at` optional: epoch seconds of the proof; set only by a `sign_in` step-up callback or `POST /v1/apps/{appSlug}/step-up`, never by a refresh +- `step_up_method` optional: present exactly when `step_up_at` is; `provider:` for a provider step-up sign-in, otherwise the method label the app asserted +- `auth_at` optional: epoch seconds of the sign-in this token was minted by; set only by a `sign_in` callback (never link, connect or refresh), always with `auth_identity_id` +- `auth_identity_id` optional: the `linked_identities.id` that sign-in came through; the only record of which login proved the session. An asserted step-up spreads the bearer's claims, so these pass through unchanged - `display_name` optional - `app.slug` - `app.profile_version` diff --git a/docs/verse-service-contract.md b/docs/verse-service-contract.md index fcfa4ac..f3c98e9 100644 --- a/docs/verse-service-contract.md +++ b/docs/verse-service-contract.md @@ -11,7 +11,8 @@ evidence only. ## Owner Map -- Owner: Heimdall owns provider identity/linking, OAuth attempts, signed session and claim +- Owner: Heimdall owns provider identity/linking (an authenticator handle, not + GameCult identity, which is Bifrost's), OAuth attempts, signed session and claim issuance, entitlement refresh, managed provider token custody, grants, auth-completion handoffs, refresh sessions, and audit events. - Inputs: provider OAuth callbacks, app profile requests, caller-supplied diff --git a/notes/streampixels-connect-redeem.md b/notes/streampixels-connect-redeem.md new file mode 100644 index 0000000..83f57a7 --- /dev/null +++ b/notes/streampixels-connect-redeem.md @@ -0,0 +1,35 @@ +# For Kiko: what StreamPixels must do for a creator connect + +Heimdall's side is done (this PR). A connect start that carries a `connection` +target is accepted only with StreamPixels' own `x-heimdall-app-secret`, so only +the StreamPixels backend can mint a state naming `{kind: "creator", targetId}`. +Heimdall cannot see StreamPixels' session; the secret proves the caller is the +backend, and the backend must have proved the creator-manage session itself +before it starts the connect. + +What StreamPixels has to change (not done here; this repo does not touch it): + +1. **Start the connect only after the creator-manage check.** The route that + calls `POST /v1/oauth/:provider/start` with `mode: "connect"` must have + verified, for the signed-in StreamPixels user, that they may manage creator + `targetId`. Never take `targetId` from the browser unchecked. +2. **Remember what you started.** Store, server-side and bound to the attempt + (the `attemptId` or browser session), the `targetId` StreamPixels asked + Heimdall to bind. +3. **Redeem with that stored target, never one read back from the request or + the completion.** `POST /v1/apps/streampixels/auth/redeem` takes `targetId`; + Heimdall answers `403 completion_target_mismatch` (code left unconsumed) when + it differs from the signed state's. That only protects you if the value you + send is the one you stored at step 2. A redeem with no stored target for this + attempt must be refused by StreamPixels before it calls Heimdall. +4. **Refuse a creator connect you did not start.** If a connect completion + arrives for a `targetId` with no matching started attempt, do not rebind that + creator's connector, whatever Heimdall's completion says. +5. **A connect completion with no creator target is not a creator connect and + not a sign-in.** Joystick is managed-connection only: a non-creator Joystick + completion is an error. (Twitch/YouTube `connect` without a `connection` is + Heimdall's viewer-session path; treat it as that, never as a connector rebind.) +6. Blank targets (`" "`, zero-width characters) are refused by Heimdall at + start with `400 invalid_connection_target`; send real ids only. + +Tracked as `joystick:follow_up:connect-start-needs-app-auth`. diff --git a/package.json b/package.json index 36394ef..626ab8a 100644 --- a/package.json +++ b/package.json @@ -17,6 +17,7 @@ "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node24 --outfile=dist/heimdall --external:pg-native --banner:js=\"#!/usr/bin/env node\nimport{createRequire}from'node:module';const require=createRequire(import.meta.url);\"" }, "dependencies": { + "@fastify/cookie": "^11.1.3", "@fastify/cors": "^11.2.0", "@msgpack/msgpack": "^3.1.3", "@gamecult/cultcache-ts": "file:vendor/CultLib/packages/cultcache-ts", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 855ad01..c84f4d2 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -12,6 +12,9 @@ importers: .: dependencies: + '@fastify/cookie': + specifier: ^11.1.3 + version: 11.1.5 '@fastify/cors': specifier: ^11.2.0 version: 11.2.0 @@ -229,6 +232,9 @@ packages: '@fastify/ajv-compiler@4.0.5': resolution: {integrity: sha512-KoWKW+MhvfTRWL4qrhUwAAZoaChluo0m0vbiJlGMt2GXvL4LVPQEjt8kSpHI3IBq5Rez8fg+XeH3cneztq+C7A==} + '@fastify/cookie@11.1.5': + resolution: {integrity: sha512-hs7e0otf7n/lJMpt63EFdQb5/u8kO6DeexEtLPVTybSdItC6SwJ1O0vtTyWvKNR70LZcHLlsUr/y3jFpqtyWRA==} + '@fastify/cors@11.2.0': resolution: {integrity: sha512-LbLHBuSAdGdSFZYTLVA3+Ch2t+sA6nq3Ejc6XLAKiQ6ViS2qFnvicpj0htsx03FyYeLs04HfRNBsz/a8SvbcUw==} @@ -469,6 +475,10 @@ packages: resolution: {integrity: sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==} engines: {node: '>=18'} + cookie@2.0.1: + resolution: {integrity: sha512-yuToqVvRrj6pfDXREyQAAv8SkAEk/8GS3jQRTiUMm66TVtBYmqQeoEjL2Lmq8Rpo6271vH76InTChTitEAm65w==} + engines: {node: '>=22'} + cultmesh-ts@file:vendor/CultLib/packages/cultmesh-ts: resolution: {directory: vendor/CultLib/packages/cultmesh-ts, type: directory} engines: {node: '>=18'} @@ -547,6 +557,9 @@ packages: fastify-plugin@5.1.0: resolution: {integrity: sha512-FAIDA8eovSt5qcDgcBvDuX/v0Cjz0ohGhENZ/wpc3y+oZCY2afZ9Baqql3g/lC+OHRnciQol4ww7tuthOb9idw==} + fastify-plugin@6.0.1: + resolution: {integrity: sha512-4wW4RxSmvPXLrh5mgQEiu43qU3bw44N2ss4FTkTkQIbprUhE+/s43QX0j/ttcztdWK7PEkHqVthdc5GdEGDvjA==} + fastify@5.12.7: resolution: {integrity: sha512-v4pEPsTRPuqlDIYiQFB+BHjVN4SdHX9u0ABk0ZDUKbbdY1vsNryUd1j4Z+jQEZajvYIVk047Kimva9/AJ79GYw==} @@ -1186,6 +1199,11 @@ snapshots: ajv-formats: 3.0.1(ajv@8.20.0) fast-uri: 3.1.0 + '@fastify/cookie@11.1.5': + dependencies: + cookie: 2.0.1 + fastify-plugin: 6.0.1 + '@fastify/cors@11.2.0': dependencies: fastify-plugin: 5.1.0 @@ -1393,6 +1411,8 @@ snapshots: cookie@1.1.1: {} + cookie@2.0.1: {} + cultmesh-ts@file:vendor/CultLib/packages/cultmesh-ts: dependencies: '@gamecult/cultcache-ts': file:vendor/CultLib/packages/cultcache-ts @@ -1500,6 +1520,8 @@ snapshots: fastify-plugin@5.1.0: {} + fastify-plugin@6.0.1: {} + fastify@5.12.7: dependencies: '@fastify/ajv-compiler': 4.0.5 diff --git a/scripts/test-live-pg.sh b/scripts/test-live-pg.sh new file mode 100755 index 0000000..e028caa --- /dev/null +++ b/scripts/test-live-pg.sh @@ -0,0 +1,28 @@ +#!/usr/bin/env bash +# Runs the whole vitest suite with the live-Postgres files enabled, against a +# throwaway local cluster that this script starts and removes. Needs the +# Postgres server binaries (initdb, pg_ctl) on PATH or in PG_BIN. +# SOUL_PG_URL's test drops and recreates schema public, so it only ever sees +# this disposable cluster. +set -euo pipefail +# Prerequisites, done here when missing (each step is skipped once it holds): +# 1. the vendor/CultLib submodule checked out, +# 2. its npm dependencies installed (the vendor packages build with its tsc), +# 3. dist/ built for cultcache-ts, cultnet-ts and cultmesh-ts (package.json +# points main at dist/index.js), +# 4. this repo's pnpm install (npm install if pnpm fails with EACCES). +cd "$(dirname "$0")/.." +[ -f vendor/CultLib/package.json ] || git submodule update --init vendor/CultLib +[ -d vendor/CultLib/node_modules/typescript ] || (cd vendor/CultLib && npm ci) +for pkg in cultcache-ts cultnet-ts cultmesh-ts; do + [ -f "vendor/CultLib/packages/$pkg/dist/index.js" ] || (cd "vendor/CultLib/packages/$pkg" && npm run build) +done +[ -d node_modules/vitest ] || pnpm install --frozen-lockfile || npm install # pnpm can fail with EACCES on its store; npm does not need it +export PATH="${PG_BIN:-/usr/lib/postgresql/16/bin}:$PATH" +dir="$(mktemp -d)" +port="${PG_PORT:-54329}" +trap 'pg_ctl -D "$dir" -m immediate stop >/dev/null 2>&1 || true; rm -rf "$dir"' EXIT +initdb -D "$dir" -U pgadmin --auth=trust >/dev/null +pg_ctl -D "$dir" -o "-p $port -k $dir -c listen_addresses=127.0.0.1" -l "$dir/log" -w start >/dev/null +url="postgres://pgadmin@127.0.0.1:$port/postgres" +HEIMDALL_TEST_PG_ADMIN_URL="$url" SOUL_PG_URL="$url" npx vitest run --config vitest.config.ts "$@" diff --git a/src/app-profiles.ts b/src/app-profiles.ts index 3489a48..a77f76a 100644 --- a/src/app-profiles.ts +++ b/src/app-profiles.ts @@ -45,6 +45,33 @@ export interface AppProfile { * plane; absent for apps with no such requirement. */ requiredEntitlementPolicyKind?: OAuthEntitlementPolicy["kind"]; + /** + * The app binds browser completion to its own pending attempt, and the + * binding is the secrecy of the attempt nonce, which rides readable in the + * signed (not encrypted) state's return_to. If anyone could start a flow for + * this app, whoever learned a victim's nonce could mint a completion bound + * to it and sign the victim's browser in as themselves (login CSRF, finding + * known-nonce-login-csrf). So a start for this app is refused unless the + * caller is this app's authenticated caller: only the app can mint its own + * state. Absent for apps whose browser starts are public by design. + */ + startRequiresAppCaller?: boolean; + /** + * The app may assert, with its secret and a member's live bearer, that the + * member just passed a factor the app itself checked (POST + * /v1/apps/{app}/step-up). Heimdall cannot see that factor and trusts the + * app, so the grant is explicit per app and closed per method: only these + * labels may be asserted, and they end up in the claim's step_up_method. + * Absent for every app that may not assert. + */ + stepUpAssertion?: { methods: readonly string[] }; + /** + * The app may move linked identities between two accounts it holds proofs + * for (POST /v1/apps/{app}/identity-moves). `accountProofMethods` are the + * asserted step_up_method labels that prove a whole account rather than one + * login; each must be one of stepUpAssertion.methods. Absent: the app may not move. + */ + identityMoves?: { accountProofMethods: readonly string[] }; } /** The membership signal shared by every app that gates on GameCult membership. */ @@ -137,11 +164,15 @@ const streampixelsProfile: AppProfile = { const bifrostProfile: AppProfile = { slug: "bifrost", displayName: "Bifrost", - profileVersion: "2026-06-08", - identityProviders: ["discord", "patreon"], + profileVersion: "2026-11-04", + identityProviders: ["discord", "patreon", "google"], entitlementSources: ["discord", "patreon"], managedConnectionProviders: [], allowedReturnOrigins: ["https://bifrost.gamecult.org"], + startRequiresAppCaller: true, + stepUpAssertion: { methods: ["bifrost-passkey", "bifrost-email-code"] }, + // A passkey proves the account; an email code proves an inbox, which is one login's worth at most. + identityMoves: { accountProofMethods: ["bifrost-passkey"] }, capabilities: [ { key: "member_access", @@ -251,6 +282,17 @@ export function isAllowedReturnOrigin(profile: AppProfile, returnTo: string): bo } } +/** + * A connection target names something: at least one letter or number that is + * not a default-ignorable code point (the Hangul and Khmer fillers are letters + * that render as nothing). An allowlist, so marks, private-use, unassigned and + * surrogate code points and symbols cannot stand in for a name. The one + * definition the start gate and the callback mint both use. + */ +export function isUsableConnectionTarget(targetId: string): boolean { + return /(?![\p{Default_Ignorable_Code_Point}])[\p{L}\p{N}]/u.test(targetId); +} + /** * What a completed OAuth callback may mint, decided at the callback from the * signed state's mode and the provider's role in the profile (the start gate @@ -277,7 +319,7 @@ export function callbackMint( return mode === "connect" && profile.managedConnectionProviders.includes(provider) && connection?.kind === "creator" && - connection.targetId !== "" + isUsableConnectionTarget(connection.targetId) ? "custody_only" : "refused"; } diff --git a/src/app.ts b/src/app.ts index 40ceb20..b3c7755 100644 --- a/src/app.ts +++ b/src/app.ts @@ -1,6 +1,8 @@ -import { createHmac, randomUUID } from "node:crypto"; +import { createHash, createHmac, randomUUID } from "node:crypto"; +import { deflateRawSync, inflateRawSync } from "node:zlib"; +import cookie from "@fastify/cookie"; import cors from "@fastify/cors"; -import Fastify, { type FastifyError, type FastifyInstance } from "fastify"; +import Fastify, { type FastifyError, type FastifyInstance, type FastifyReply, type FastifyRequest } from "fastify"; import { type AppCaller, isAppCaller, resolveAppCaller } from "./app-caller.js"; import { deliverBackendHandoff, type BackendHandoffPayload } from "./backend-handoff.js"; import { @@ -22,12 +24,15 @@ import { type OAuthStartRequest, type Provider, } from "./contracts.js"; -import { issueAccessClaim, type IssueAccessClaimInput } from "./claims.js"; -import { builtInAppProfiles, getAppProfile, isAllowedReturnOrigin, serializeAppProfile, admitsProviderForMode, callbackMint } from "./app-profiles.js"; +import { issueAccessClaim, proofCovers, proofTier, signAssertedStepUpClaim, STEP_UP_PROOF_TTL_SECONDS, type IssueAccessClaimInput } from "./claims.js"; +import { FixedWindowBudget, type FixedWindowLimit } from "./fixed-window.js"; +import { builtInAppProfiles, getAppProfile, isAllowedReturnOrigin, serializeAppProfile, admitsProviderForMode, callbackMint, isUsableConnectionTarget } from "./app-profiles.js"; import { renderBrowserHandoffPage } from "./browser-handoff.js"; +import { consentText, digestOfText, grantViews, GRANTS_PATH, renderConsentPage, renderGrantsPage, type ConsentAsk } from "./consent.js"; import { type HeimdallConfig, loadConfig } from "./config.js"; import { createTokenCustody, type TokenCustody } from "./custody.js"; import { grantFact } from "./facts.js"; +import { deriveOidcSecrets } from "./google-oidc.js"; import { createOAuthRuntimeRegistry, fetchPatreonIdentity, @@ -35,12 +40,14 @@ import { type OAuthRuntimeRegistry, } from "./oauth.js"; import { ManagedCredentialRefreshFailed, refreshManagedCredential } from "./managed-credential.js"; -import { buildAuthorizationUrl, providerCatalog, providerExpectedEnv } from "./providers.js"; +import { authorizationScopes, buildAuthorizationUrl, providerCatalog, providerExpectedEnv } from "./providers.js"; import { createRuntimeKeyMaterial, signJwt, verifyJwt } from "./signing.js"; -import { createStore, type HeimdallStore } from "./store/index.js"; +import { createStore, IdentityHeldElsewhereError, type HeimdallStore } from "./store/index.js"; import { + OAUTH_STATE_SKEW_MS, type CreateAccountInput, type StoredCapabilityGrant, + type StoredIdentityMove, type StoredLinkedIdentity, type UpsertLinkedIdentityInput, } from "./store/types.js"; @@ -91,10 +98,13 @@ function buildOAuthStateToken(options: { mode: OAuthMode; returnTo: string; connection: OAuthConnectionBinding | undefined; + initiatorAccountId: string | undefined; handoff: OAuthHandoff; entitlementPolicy: OAuthEntitlementPolicy | undefined; + requestedScopes: string[] | undefined; + stepUp: boolean | undefined; keys: ReturnType; -}): { token: string; expiresAt: string } { +}): { token: string; jti: string; expiresAt: string } { const issuedAt = nowEpochSeconds(); const expiresAtEpoch = issuedAt + options.config.stateTtlSeconds; const payload: OAuthStatePayload = { @@ -111,13 +121,17 @@ function buildOAuthStateToken(options: { mode: options.mode, return_to: options.returnTo, connection: options.connection ?? null, + initiator_account_id: options.initiatorAccountId ?? null, handoff: options.handoff, entitlement_policy: options.entitlementPolicy ?? null, + requested_scopes: options.requestedScopes ?? null, + step_up: options.stepUp ? true : null, }; const token = signJwt(payload as unknown as Record, options.keys); return { token, + jti: payload.jti, expiresAt: new Date(expiresAtEpoch * 1000).toISOString(), }; } @@ -151,6 +165,11 @@ function parseOAuthStatePayload(payload: Record): OAuthStatePay entitlementPolicy !== null && (entitlementPolicy as Record).kind === "patreon_membership_access" && typeof (entitlementPolicy as Record).requiredTierTitle === "string")); + const requestedScopes = payload.requested_scopes; + const requestedScopesAreValid = + requestedScopes === null || + requestedScopes === undefined || + (Array.isArray(requestedScopes) && requestedScopes.every((scope) => typeof scope === "string")); if ( payload.typ !== "heimdall_oauth_state" || typeof payload.provider !== "string" || @@ -168,7 +187,10 @@ function parseOAuthStatePayload(payload: Record): OAuthStatePay typeof payload.nbf !== "number" || typeof payload.exp !== "number" || !handoffIsValid || - !entitlementPolicyIsValid + !entitlementPolicyIsValid || + !(payload.initiator_account_id === undefined || payload.initiator_account_id === null || typeof payload.initiator_account_id === "string") || + !requestedScopesAreValid || + !(payload.step_up === undefined || payload.step_up === null || payload.step_up === true) ) { return null; } @@ -177,13 +199,176 @@ function parseOAuthStatePayload(payload: Record): OAuthStatePay if (!normalizedPayload.handoff) { normalizedPayload.handoff = { kind: "browser_completion" }; } + if (!normalizedPayload.initiator_account_id) { + normalizedPayload.initiator_account_id = null; + } if (!normalizedPayload.entitlement_policy) { normalizedPayload.entitlement_policy = null; } + if (!normalizedPayload.requested_scopes) { + normalizedPayload.requested_scopes = null; + } + if (!normalizedPayload.step_up) { + normalizedPayload.step_up = null; + } return normalizedPayload; } +type OAuthStateVerdict = + | { ok: true; payload: OAuthStatePayload } + | { ok: false; error: "invalid_state" | "state_provider_mismatch" | "state_expired" }; + +/** + * The one place a signed OAuth state becomes trusted: signature, shape, issuer, + * audience and provider, and the time window with OAUTH_STATE_SKEW_MS of skew + * (30 s, as refresh tokens use). Every route that turns a state into navigation or a completion + * runs this first; the refusals are fixed codes and never echo the token. + */ +function verifyOAuthState( + config: HeimdallConfig, + keys: ReturnType, + token: string, + provider: Provider +): OAuthStateVerdict { + const verification = verifyJwt(token, keys.publicKey); + if (!verification.valid) { + return { ok: false, error: "invalid_state" }; + } + + const payload = parseOAuthStatePayload(verification.payload); + if (!payload || payload.iss !== config.issuer) { + return { ok: false, error: "invalid_state" }; + } + if (payload.aud !== payload.provider || payload.provider !== provider) { + return { ok: false, error: "state_provider_mismatch" }; + } + + const now = nowEpochSeconds(); + if (payload.nbf > now + OAUTH_STATE_SKEW_MS / 1000 || payload.exp <= now - OAUTH_STATE_SKEW_MS / 1000) { + return { ok: false, error: "state_expired" }; + } + + return { ok: true, payload }; +} + +const oauthBindingType = "heimdall_oauth_binding"; + +function oauthBindingCookieName(jti: string): string { + return `__Host-heimdall-oauth-${jti}`; +} + +/** The signed claim that this browser launched this state: it is the cookie's value, and needs no store read to check. */ +function signOAuthBinding( + config: HeimdallConfig, + keys: ReturnType, + state: OAuthStatePayload, + shownText?: string +): string { + return signJwt( + { + typ: oauthBindingType, + iss: config.issuer, + jti: state.jti, + iat: nowEpochSeconds(), + exp: state.exp, + // The wording the person agreed to, carried from the ask to the receipt. + ...(shownText === undefined ? {} : { ct: deflateRawSync(shownText).toString("base64url") }), + }, + keys + ); +} + +const consentAskType = "heimdall_consent_ask"; + +/** The most wording a cookie may carry, before and after compression. The ask refuses what exceeds it; the readers never inflate past it. */ +const maxConsentTextBytes = 16 * 1024; +/** Browsers drop a cookie above 4096 bytes; the ask refuses one it could not keep. */ +const maxConsentCookieChars = 3800; +/** What an app may request: more is not a scope list a person can read. */ +const maxRequestedScopes = 32; +const maxRequestedScopeChars = 512; + +function consentAskCookieName(jti: string): string { + return `__Host-heimdall-ask-${jti}`; +} + +/** + * The ask's own cookie. It proves a browser was shown the ask and carries the + * exact text shown; only Continue and No accept it. It is not the launch + * binding: that is set when Continue claims the launch, so that merely opening + * the launch URL never makes a browser the state's owner. + */ +function signConsentAsk(config: HeimdallConfig, keys: ReturnType, state: OAuthStatePayload, shownText: string): string { + return signJwt( + { typ: consentAskType, iss: config.issuer, jti: state.jti, iat: nowEpochSeconds(), exp: state.exp, ct: deflateRawSync(shownText).toString("base64url") }, + keys + ); +} + +/** The text a held cookie of the given type carries, or null when the cookie is absent, foreign, expired or carries none. */ +function cookieConsentText( + config: HeimdallConfig, + keys: ReturnType, + token: string | undefined, + type: string, + state: OAuthStatePayload +): string | null { + if (!token) return null; + const verification = verifyJwt(token, keys.publicKey); + if (!verification.valid) return null; + const { typ, iss, jti, exp, ct } = verification.payload; + if (typ !== type || iss !== config.issuer || jti !== state.jti || typeof exp !== "number" || exp <= nowEpochSeconds() || typeof ct !== "string") { + return null; + } + try { + return inflateRawSync(Buffer.from(ct, "base64url"), { maxOutputLength: maxConsentTextBytes }).toString("utf8"); + } catch { + return null; + } +} + +function setConsentAskCookie(reply: FastifyReply, state: OAuthStatePayload, value: string, maxAgeSeconds: number): void { + reply.setCookie(consentAskCookieName(state.jti), value, { + path: "/", + secure: true, + httpOnly: true, + sameSite: "lax", + maxAge: Math.max(0, maxAgeSeconds), + }); +} + +function oauthBindingHolds( + config: HeimdallConfig, + keys: ReturnType, + token: string | undefined, + state: OAuthStatePayload +): boolean { + if (!token) { + return false; + } + const verification = verifyJwt(token, keys.publicKey); + if (!verification.valid) { + return false; + } + const { typ, iss, jti, exp } = verification.payload; + return typ === oauthBindingType && iss === config.issuer && jti === state.jti && typeof exp === "number" && exp > nowEpochSeconds(); +} + +function setOAuthBindingCookie(reply: FastifyReply, state: OAuthStatePayload, value: string, maxAgeSeconds: number): void { + reply.setCookie(oauthBindingCookieName(state.jti), value, { + path: "/", + secure: true, + httpOnly: true, + sameSite: "lax", + maxAge: Math.max(0, maxAgeSeconds), + }); +} + +function oauthCallbackUrl(config: HeimdallConfig, provider: Provider): string { + return `${config.publicBaseUrl}/v1/oauth/${provider}/callback`; +} + function buildGrantFacts(grants: StoredCapabilityGrant[]): string[] { return grants.map((grant) => grantFact(grant.capability)); } @@ -248,11 +433,17 @@ function relayedProviderText(value: string | undefined, bound: number): string | return printable ? printable : undefined; } -/** - * What may be recorded or answered about a caught error: its class and its - * code, each only when it is a short identifier. Never its message, which - * carries whatever the thrower quoted (a host, a database, a provider's body). - */ +/** A link callback the signed state's initiator does not license. Its message is static and safe to relay. */ +export class LinkRefusal extends Error { + constructor( + readonly code: "link_initiator_missing" | "link_initiator_mismatch" | "link_initiator_unknown" | "identity_not_linked", + message: string + ) { + super(message); + this.name = "LinkRefusal"; + } +} + export function errorIdentity(error: unknown): { errorClass: string; errorCode: string | null } { const code = (error as { code?: unknown } | null)?.code; return { @@ -392,6 +583,8 @@ async function evaluateStoredEntitlements(options: { appSlug: AppSlug; accountId: string; entitlementPolicies: OAuthEntitlementPolicy[]; + /** A provider the caller has already evaluated with fresh tokens. */ + skipProvider?: Provider; }): Promise { const profile = getAppProfile(options.appSlug); if (!profile) { @@ -401,7 +594,7 @@ async function evaluateStoredEntitlements(options: { const facts: string[] = []; for (const storedIdentity of linkedIdentities) { - if (!profile.entitlementSources.includes(storedIdentity.provider)) { + if (!profile.entitlementSources.includes(storedIdentity.provider) || storedIdentity.provider === options.skipProvider) { continue; } @@ -486,6 +679,13 @@ export async function startOAuthFlow( * which one reaches the signed state token. */ trustedBrowserAttemptId?: string; + /** + * The account an explicit link binds to. Like `trustedBrowserAttemptId` + * it is a function argument, never a value parsed out of the request: + * the HTTP route sets it only from a verified Heimdall access token for + * this app (`resolveLinkAccount`), so a caller cannot name an account. + */ + linkAccountId?: string; } ): Promise { const { config, keys } = ctx; @@ -501,16 +701,85 @@ export async function startOAuthFlow( }; } - if (callbackMint(profile, provider, input.mode, input.connection) === "refused") { + // A connection target is app-backend authority: it rides only on connect + // starts that carry the app's own secret (gated below), and never on a + // sign_in start, which is open to any browser. + if (input.mode === "sign_in" && input.connection !== undefined) { return { statusCode: 400, + body: { error: "connection_not_allowed_in_sign_in", detail: "sign_in start must not carry a connection target." }, + }; + } + + if (input.stepUp && input.mode !== "sign_in") { + return { statusCode: 400, body: { error: "step_up_only_in_sign_in", detail: "stepUp applies to sign_in starts only." } }; + } + + const descriptor = providerCatalog[provider]; + // A provider that never mints an account attaches an identity only through + // a bound link: the user's own access token, since the app's word does not + // name this person to Google. A link start without a verified Heimdall session would end + // in a refusal at the callback, so it is refused before the redirect. + // `sign_in` stays open: it signs in an identity already linked, and the + // callback refuses one that is not. + if (descriptor.firstLogin === "requires_link" && input.mode === "link" && !options?.linkAccountId) { + return { + statusCode: 401, body: { - error: "creator_connection_required", - detail: `${provider} on ${profile.slug} is a managed creator connection: connect needs connection.kind creator and a targetId.`, + error: "link_session_required", + detail: `Linking ${descriptor.displayName} needs a Heimdall access token for ${profile.slug}: send it as a Bearer token.`, }, }; } + // Link mode binds an identity to an existing account, so the account must + // be named by someone Heimdall can believe: the authenticated app backend. + // The name rides in the signed state and the callback holds the provider's + // identity to it. No other mode carries an initiator. + if (input.mode === "link") { + if (options?.linkAccountId) { + // The user's own access token for this app names the account. + if (input.initiatingAccountId !== undefined && input.initiatingAccountId !== options.linkAccountId) { + return { statusCode: 400, body: { error: "link_initiator_conflict", detail: "initiatingAccountId differs from the bearer's account." } }; + } + } else { + if (!isAppCaller(caller) || caller.appSlug !== profile.slug) { + return { statusCode: 401, body: { error: "app_auth_required" } }; + } + if (!input.initiatingAccountId) { + return { statusCode: 400, body: { error: "link_initiator_required", detail: "link mode needs initiatingAccountId." } }; + } + if (!(await ctx.store.findAccountById(input.initiatingAccountId))) { + return { statusCode: 400, body: { error: "link_initiator_unknown", detail: "initiatingAccountId names no account." } }; + } + } + } else if (input.initiatingAccountId !== undefined) { + return { statusCode: 400, body: { error: "initiator_only_in_link_mode" } }; + } + + // A step-up is app-backend authority, like a connection target: it is + // asked for by the authenticated app, never by a browser, and only on + // sign_in. A provider with no re-authentication parameter is refused here, + // at start, so no step-up ever reaches the person without its step. + if (input.stepUp) { + if (!isAppCaller(caller) || caller.appSlug !== profile.slug) { + return { statusCode: 401, body: { error: "app_auth_required" } }; + } + if (!providerCatalog[provider].stepUpAuthorizationParams) { + return { statusCode: 400, body: { error: "step_up_not_supported", provider, detail: `${providerCatalog[provider].displayName} has no re-authentication parameter.` } }; + } + } + + if ( + input.requestedScopes !== undefined && + (input.requestedScopes.length > maxRequestedScopes || input.requestedScopes.some((scope) => scope.length > maxRequestedScopeChars)) + ) { + return { + statusCode: 400, + body: { error: "requested_scopes_too_large", detail: `At most ${maxRequestedScopes} scopes of ${maxRequestedScopeChars} characters each.` }, + }; + } + if (!isAllowedReturnOrigin(profile, input.returnTo)) { return { statusCode: 400, @@ -554,10 +823,28 @@ export async function startOAuthFlow( if (options?.trustedBrowserAttemptId && handoff.kind === "browser_completion") { handoff = { kind: "browser_completion", attemptId: options.trustedBrowserAttemptId }; } - if (entitlementPolicy && (!isAppCaller(caller) || caller.appSlug !== profile.slug)) { + if ((entitlementPolicy || profile.startRequiresAppCaller || (input.mode === "connect" && input.connection !== undefined)) && (!isAppCaller(caller) || caller.appSlug !== profile.slug)) { return { statusCode: 401, body: { error: "app_auth_required" } }; } + // After the app-secret gate, so a caller without the secret learns nothing about what a target must look like. + if (input.connection !== undefined && !isUsableConnectionTarget(input.connection.targetId)) { + return { + statusCode: 400, + body: { error: "invalid_connection_target", detail: "connection.targetId must name a target." }, + }; + } + + if (callbackMint(profile, provider, input.mode, input.connection) === "refused") { + return { + statusCode: 400, + body: { + error: "creator_connection_required", + detail: `${provider} on ${profile.slug} is a managed creator connection: connect needs connection.kind creator and a targetId.`, + }, + }; + } + const providerConfig = config.providers[provider]; if (!providerConfig.clientId) { return { @@ -566,7 +853,6 @@ export async function startOAuthFlow( }; } - const callbackUrl = `${config.publicBaseUrl}/v1/oauth/${provider}/callback`; const state = buildOAuthStateToken({ config, provider, @@ -574,32 +860,426 @@ export async function startOAuthFlow( mode: input.mode, returnTo: input.returnTo, connection: input.connection, + initiatorAccountId: options?.linkAccountId ?? input.initiatingAccountId, handoff, entitlementPolicy, + requestedScopes: input.requestedScopes, + stepUp: input.stepUp, keys, }); - return { statusCode: 201, body: { provider, appSlug: profile.slug, mode: input.mode, - callbackUrl, - authorizationUrl: buildAuthorizationUrl({ - provider, - clientId: providerConfig.clientId, - redirectUri: callbackUrl, - state: state.token, - requestedScopes: input.requestedScopes, - }), + callbackUrl: oauthCallbackUrl(config, provider), + authorizationUrl: `${config.publicBaseUrl}/v1/oauth/${provider}/launch?state=${encodeURIComponent(state.token)}`, handoff, - stateToken: state.token, stateExpiresAt: state.expiresAt, }, }; } +/** What a live bearer proves: the account its session belongs to, and the claims it was signed with. */ +interface ResolvedBearer { + accountId: string; + claims: Record; + /** When the session row the bearer rests on expires (the refresh horizon, not the access token's `exp`). */ + sessionExpiresAt: string; +} + +/** + * The one verifier of a Heimdall access token. The token must verify under + * Heimdall's own key, be an access token for `appSlug` (or, when none is + * named, for any app), be inside its validity window, and belong to a session + * the store still holds for that account at that revision. A bearer that fails + * any of these proves nothing. + */ +async function resolveBearer( + ctx: Pick, + authorization: string | undefined, + appSlug?: AppSlug +): Promise { + const token = /^Bearer\s+(\S+)$/i.exec(authorization ?? "")?.[1]; + if (!token) return null; + const verification = verifyJwt(token, ctx.keys.publicKey); + if (!verification.valid) return null; + const claims = verification.payload; + const audience = appSlug ?? claims.aud; + if (!isAppSlug(audience)) return null; + const now = nowEpochSeconds(); + if ( + claims.typ !== "heimdall_access" || + claims.iss !== ctx.config.issuer || + claims.aud !== audience || + typeof claims.account_id !== "string" || + typeof claims.sid !== "string" || + typeof claims.access_revision !== "number" || + typeof claims.exp !== "number" || + claims.exp <= now || + (typeof claims.nbf === "number" && claims.nbf > now) + ) { + return null; + } + const session = await ctx.store.findSession(audience, claims.sid); + if ( + !session || + session.accountId !== claims.account_id || + session.accessRevision !== claims.access_revision || + Date.parse(session.expiresAt) <= Date.now() + ) { + return null; + } + return { accountId: claims.account_id, claims, sessionExpiresAt: session.expiresAt }; +} + +/** The account a link start binds to: the one a live Heimdall access token for this app names. A link is explicit or it does not happen. */ +async function resolveLinkAccount( + ctx: Pick, + appSlug: AppSlug, + authorization: string | undefined +): Promise { + return (await resolveBearer(ctx, authorization, appSlug))?.accountId ?? null; +} + +/** The account a Heimdall access token for any app names, when the token and its session are live. */ +async function resolveAccessAccount( + ctx: Pick, + authorization: string | undefined +): Promise { + return (await resolveBearer(ctx, authorization))?.accountId ?? null; +} + +/** What an app may spend asserting step-up proofs: per member account, and per calling app. */ +export const STEP_UP_ASSERT_LIMITS: { account: FixedWindowLimit; app: FixedWindowLimit; notPermitted: FixedWindowLimit } = { + account: { max: 10, windowMs: 600_000 }, + app: { max: 120, windowMs: 60_000 }, + // An app whose profile has no grant, holding its own secret: a handful of refusals per window, no more. + notPermitted: { max: 5, windowMs: 60_000 }, +}; + +export interface StepUpAssertBudgets { + account: FixedWindowBudget; + app: FixedWindowBudget; + notPermitted: FixedWindowBudget; +} + +export function createStepUpAssertBudgets(now: () => number = () => Date.now()): StepUpAssertBudgets { + return { + account: new FixedWindowBudget(STEP_UP_ASSERT_LIMITS.account, now), + app: new FixedWindowBudget(STEP_UP_ASSERT_LIMITS.app, now), + notPermitted: new FixedWindowBudget(STEP_UP_ASSERT_LIMITS.notPermitted, now), + }; +} + +/** + * POST /v1/apps/{app}/step-up. The app says its member just passed a factor + * the app checked; Heimdall cannot see the factor, so the word is bounded by + * what the route demands: the app's secret AND the member's live bearer for + * that same app, the profile's explicit grant and method allowlist, a nonce + * spent once per session, and a rate per account and per app. Every + * refusal after the secret verified is recorded, except that a flood is not: + * a rate-limited refusal is recorded once per window per budget (its first), + * and an app without the grant is recorded once per window; a request without + * the secret writes nothing, since anyone can send one. The audit rows carry a digest of + * the nonce, never the nonce, the bearer or the secret. + */ +export async function assertStepUp( + ctx: Pick, + budgets: StepUpAssertBudgets, + appSlug: AppSlug, + headers: Record, + input: { method: string; nonce: string } +): Promise { + const { config, keys, store } = ctx; + if (!resolveAppCaller(config, appSlug, headers)) { + return { statusCode: 401, body: { error: "app_auth_required" } }; + } + const permitted = getAppProfile(appSlug)?.stepUpAssertion; + let known: { accountId: string; sessionId: string } | undefined; + let nonceDigest: string | undefined; + let tripped: string | undefined; + const refuse = async (statusCode: number, error: string, extra: Record = {}, record = true): Promise => { + if (!record) return { statusCode, body: { error, ...extra } }; + await store.createAuditEvent({ + ...(known ? { accountId: known.accountId, sessionId: known.sessionId } : {}), + appSlug, + eventType: "step_up_assertion_refused", + eventPayloadJson: { outcome: "refused", code: error, budget: tripped ?? null, method: permitted?.methods.includes(input.method) ? input.method : null, nonceDigest: nonceDigest ?? null }, + createdAt: new Date().toISOString(), + }); + return { statusCode, body: { error, ...extra } }; + }; + // Audit only the first denial of a window: the rows record that a budget tripped, not every request behind it. + const limited = (budget: string, spent: { n: number; retryAfterSeconds: number }, max: number) => { + tripped = budget; + return refuse(429, "step_up_rate_limited", { retryAfterSeconds: spent.retryAfterSeconds }, spent.n === max + 1); + }; + + if (!permitted) { + const spent = budgets.notPermitted.spend(appSlug); + if (spent.retryAfterSeconds) return limited("notPermitted", spent, STEP_UP_ASSERT_LIMITS.notPermitted.max); + return refuse(403, "step_up_assertion_not_permitted", { detail: `${appSlug} may not assert step-up proofs.` }, spent.n === 1); + } + const appSpent = budgets.app.spend(appSlug); + if (appSpent.retryAfterSeconds) return limited("app", appSpent, STEP_UP_ASSERT_LIMITS.app.max); + + const bearer = await resolveBearer(ctx, headers.authorization as string | undefined); + if (!bearer) { + return refuse(401, "sign_in_required", { detail: "Send the member's live Heimdall access token as a Bearer token." }); + } + const sessionId = bearer.claims.sid as string; + known = { accountId: bearer.accountId, sessionId }; + if (bearer.claims.aud !== appSlug) { + return refuse(403, "bearer_app_mismatch", { detail: `The access token was not issued to ${appSlug}.` }); + } + const accountSpent = budgets.account.spend(bearer.accountId); + if (accountSpent.retryAfterSeconds) return limited("account", accountSpent, STEP_UP_ASSERT_LIMITS.account.max); + + nonceDigest = createHash("sha256").update(`heimdall-step-up-nonce\0${sessionId}\0${input.nonce}`).digest("hex"); + if (!permitted.methods.includes(input.method)) { + return refuse(400, "unknown_step_up_method", { methods: permitted.methods }); + } + const at = new Date().toISOString(); + if (!(await store.claimOAuthStateUse({ jti: nonceDigest, phase: "step_up_assert", appSlug, usedAt: at, expiresAt: bearer.sessionExpiresAt }))) { + return refuse(409, "step_up_nonce_replayed", { detail: "A nonce is good once per session; send a fresh one." }); + } + + const minted = signAssertedStepUpClaim({ keys, bearerClaims: bearer.claims, method: input.method }); + await store.createAuditEvent({ + accountId: bearer.accountId, + sessionId, + appSlug, + eventType: "step_up_asserted", + eventPayloadJson: { outcome: "asserted", code: null, method: input.method, nonceDigest, stepUpAt: minted.stepUpAt }, + createdAt: at, + }); + return { + statusCode: 201, + body: { + accessToken: minted.accessToken, + claimSet: minted.claimSet, + stepUp: { at: minted.stepUpAt, method: input.method, validForSeconds: STEP_UP_PROOF_TTL_SECONDS }, + }, + }; +} + +export const MOVE_ID_PATTERN = "^[A-Za-z0-9_-]{16,64}$"; + +export interface MoveIdentitiesBody { + moveId: string; + fromProofs: string[]; + toProof?: string; + identityIds?: string[]; + reversesMoveId?: string; +} + +/** The answer a move gives, derived from its stored row so a replay is byte-identical to the first answer. */ +function moveReceipt(move: StoredIdentityMove) { + const tier = (proofs: { tier: "strong" | "weak" }[]) => (proofs.some((proof) => proof.tier === "strong") ? "strong" : "weak"); + return { + moveId: move.id, + accountId: move.toAccountId, + movedIdentityIds: move.moved.map((moved) => moved.id), + proof: { from: tier(move.proof.from), to: move.proof.to ? move.proof.to.tier : null }, + ...(move.reversesMoveId !== undefined ? { reversesMoveId: move.reversesMoveId } : {}), + }; +} + +/** + * POST /v1/apps/{app}/identity-moves: the one sanctioned way a login changes + * account. The caller's secret and its profile's identityMoves grant open the + * route; the accounts come only from the proofs (live bearers of this app, + * fresh by proofTier), never from the body, an email or a name. A proof + * through login X moves X; only an asserted account proof (the profile's + * accountProofMethods) speaks for the whole account. The store decides and + * commits; this route verifies, maps refusals to fixed codes, then writes the + * revocation receipts the move owes (revokeLiveGrants stays their one writer) + * and the audit row. A replayed moveId is answered before the proofs are + * verified, because the first success revoked the source's sessions. + */ +export async function moveIdentitiesRoute( + ctx: Pick, + revokeLiveGrants: (accountId: string, provider: Provider, receipts: Parameters[0], at: string) => Promise, + appSlug: AppSlug, + headers: Record, + body: MoveIdentitiesBody +): Promise { + const { config, keys, store } = ctx; + const refuse = (statusCode: number, error: string, extra: Record = {}): HandlerResult => ({ statusCode, body: { error, ...extra } }); + if (!resolveAppCaller(config, appSlug, headers)) return refuse(401, "app_auth_required"); + const grant = getAppProfile(appSlug)?.identityMoves; + if (!grant) return refuse(403, "not_allowed_for_app"); + + // The providers a move carried away from its source that the source no longer holds: their grants are taken back under the source. + const settleGrants = async (move: StoredIdentityMove) => { + const held = new Set((await store.listStoredLinkedIdentitiesForAccount(move.fromAccountId)).map((identity) => identity.provider)); + const at = new Date().toISOString(); + for (const provider of new Set(move.moved.map((moved) => moved.provider))) { + if (!held.has(provider)) await revokeLiveGrants(move.fromAccountId, provider, await store.listConsentReceipts(move.fromAccountId), at); + } + }; + + const existing = await store.findIdentityMove(body.moveId); + if (existing) { + const signedFor = (token: string | undefined, accountId: string) => { + const verification = token ? verifyJwt(token, keys.publicKey) : null; + return ( + verification?.valid === true && + verification.payload.typ === "heimdall_access" && + verification.payload.iss === config.issuer && + verification.payload.aud === appSlug && + verification.payload.account_id === accountId + ); + }; + const same = + existing.appSlug === appSlug && + existing.reversesMoveId === body.reversesMoveId && + body.fromProofs.every((token) => signedFor(token, existing.fromAccountId)) && + (existing.reversesMoveId !== undefined ? body.toProof === undefined : signedFor(body.toProof, existing.toAccountId)); + if (!same) return refuse(409, "move_id_conflict"); + await settleGrants(existing); + return { statusCode: 200, body: moveReceipt(existing) }; + } + + let forward: StoredIdentityMove | null = null; + if (body.reversesMoveId !== undefined) { + forward = await store.findIdentityMove(body.reversesMoveId); + if (!forward || forward.appSlug !== appSlug || forward.reversesMoveId !== undefined) return refuse(409, "not_reversible"); + } + + const nowS = nowEpochSeconds(); + const resolve = (token: string) => resolveBearer(ctx, `Bearer ${token}`, appSlug); + const fromBearers = []; + for (const token of body.fromProofs) { + const bearer = await resolve(token); + if (!bearer) return refuse(403, "proof_invalid", { proof: "from" }); + fromBearers.push(bearer); + } + const fromAccountId = fromBearers[0]!.accountId; + if (fromBearers.some((bearer) => bearer.accountId !== fromAccountId)) return refuse(403, "proof_invalid", { proof: "from" }); + let toBearer: ResolvedBearer | null = null; + if (forward === null) { + toBearer = await resolve(body.toProof!); + if (!toBearer) return refuse(403, "proof_invalid", { proof: "to" }); + } else if (fromAccountId !== forward.toAccountId) { + return refuse(409, "not_reversible"); + } + const toAccountId = toBearer?.accountId ?? forward!.fromAccountId; + if (fromAccountId === toAccountId) return refuse(409, "same_account"); + + const proofOf = (bearer: ResolvedBearer, tier: "strong" | "weak") => ({ + tier, + method: tier === "strong" && typeof bearer.claims.step_up_method === "string" ? bearer.claims.step_up_method : null, + identityId: typeof bearer.claims.auth_identity_id === "string" ? bearer.claims.auth_identity_id : null, + }); + const fromProof = []; + for (const bearer of fromBearers) { + const tier = proofTier(bearer.claims, nowS); + if (!tier) return refuse(403, "proof_stale", { proof: "from" }); + fromProof.push(proofOf(bearer, tier)); + } + const toTier = toBearer ? proofTier(toBearer.claims, nowS) : null; + if (toBearer && !toTier) return refuse(403, "proof_stale", { proof: "to" }); + + const coverage = fromBearers.map((bearer) => proofCovers(bearer.claims, grant.accountProofMethods, nowS)); + if (coverage.every((covered) => covered === null)) return refuse(403, "identity_not_proved"); + const covers = coverage.includes("account") ? "account" : coverage.filter((covered): covered is string => covered !== null); + + const at = new Date().toISOString(); + const result = await store.moveIdentities({ + moveId: body.moveId, + appSlug, + fromAccountId, + toAccountId, + identityIds: forward ? forward.moved.map((moved) => moved.id) : (body.identityIds ?? "all"), + covers, + proofSessions: [...fromBearers, ...(toBearer ? [toBearer] : [])].map((bearer) => ({ + appSlug, + sessionId: bearer.claims.sid as string, + accountId: bearer.accountId, + accessRevision: bearer.claims.access_revision as number, + })), + ...(body.reversesMoveId !== undefined ? { reversesMoveId: body.reversesMoveId } : {}), + proof: { from: fromProof, to: toBearer && toTier ? proofOf(toBearer, toTier) : null }, + at, + }); + switch (result.kind) { + case "proof_lapsed": + return refuse(403, "proof_invalid"); + case "already_moved": + case "not_reversible": + case "move_id_conflict": + return refuse(409, result.kind); + case "provider_conflict": + return refuse(409, "provider_conflict", { provider: result.provider }); + case "identity_not_found": + return refuse(404, "identity_not_found"); + case "identity_not_proved": + return refuse(403, "identity_not_proved"); + case "replayed": + await settleGrants(result.move); + return { statusCode: 200, body: moveReceipt(result.move) }; + case "moved": { + const { move } = result; + await settleGrants(move); + await store.createAuditEvent({ + accountId: move.fromAccountId, + appSlug, + eventType: "identity_moved", + eventPayloadJson: { + moveId: move.id, + toAccountId: move.toAccountId, + movedIdentityIds: move.moved.map((moved) => moved.id), + providers: move.moved.map((moved) => moved.provider), + tiers: { from: moveReceipt(move).proof.from, to: moveReceipt(move).proof.to }, + reversesMoveId: move.reversesMoveId ?? null, + }, + createdAt: at, + }); + return { statusCode: 200, body: moveReceipt(move) }; + } + } +} + +const grantsPageTokenType = "heimdall_grants_page"; +const grantsPageTokenTtlSeconds = 600; + +/** A short, purpose-bound proof of a signed-in account, so the grants page can be opened and its forms posted by a browser that holds no session. */ +function signGrantsPageToken( + config: HeimdallConfig, + keys: ReturnType, + accountId: string, + exp: number = nowEpochSeconds() + grantsPageTokenTtlSeconds +): string { + return signJwt({ typ: grantsPageTokenType, iss: config.issuer, account_id: accountId, iat: nowEpochSeconds(), exp }, keys); +} + +/** The account and expiry a page token proves. A page's own forms are signed to this same expiry, so a link is never renewed by being used. */ +function grantsPageTokenAccount( + config: HeimdallConfig, + keys: ReturnType, + token: unknown +): { accountId: string; exp: number } | null { + if (typeof token !== "string") return null; + const verification = verifyJwt(token, keys.publicKey); + if (!verification.valid) return null; + const { typ, iss, account_id: accountId, exp } = verification.payload; + return typ === grantsPageTokenType && iss === config.issuer && typeof accountId === "string" && typeof exp === "number" && exp > nowEpochSeconds() + ? { accountId, exp } + : null; +} + +function consentAskFor(state: OAuthStatePayload): ConsentAsk { + return { + appSlug: state.app_slug, + provider: state.provider, + scopes: authorizationScopes(state.provider, state.requested_scopes ?? undefined), + returnOrigin: new URL(state.return_to).origin, + }; +} + /** * Session refresh, extracted for the same reason as startOAuthFlow: the HTTP * route and the plane's `refreshAuth` (which owns Ghostlight identity) call @@ -738,6 +1418,11 @@ export async function buildApp(options: BuildAppOptions = {}): Promise { + done(null, Object.fromEntries(new URLSearchParams(body as string))); + }); app.get("/healthz", async () => ({ ok: true, @@ -822,6 +1507,8 @@ export async function buildApp(options: BuildAppOptions = {}): Promise { const caller = resolveAppCaller(config, request.body.appSlug, request.headers); - const result = await startOAuthFlow({ config, keys, store }, request.params.provider, caller, request.body); + let linkAccountId: string | undefined; + if (request.body.mode === "link") { + const bound = await resolveLinkAccount({ config, keys, store }, request.body.appSlug, request.headers.authorization); + if (bound === null && request.headers.authorization !== undefined) { + reply.code(401); + return { error: "invalid_link_session", detail: "The bearer is not a live Heimdall access token for this app." }; + } + linkAccountId = bound ?? undefined; + } + const result = await startOAuthFlow({ config, keys, store }, request.params.provider, caller, request.body, { + ...(linkAccountId !== undefined ? { linkAccountId } : {}), + }); reply.code(result.statusCode); return result.body; } ); + /** + * A refusal of a verified state. A browser (Accept: text/html) gets the + * handoff page linking back to the state's return_to, so the person is not + * left on a bare JSON body; the origin is re-checked against the app's + * allowlist here rather than trusting the signed value. Anything else gets + * the fixed JSON code. + */ + const refuseVerifiedState = ( + request: FastifyRequest, + reply: FastifyReply, + state: OAuthStatePayload, + error: "state_not_bound" | "state_already_launched" | "state_already_used" | "consent_text_missing" + ) => { + reply.code(400); + const profile = getAppProfile(state.app_slug); + if (prefersHtml(request.headers.accept) && profile && isAllowedReturnOrigin(profile, state.return_to)) { + reply.type("text/html; charset=utf-8"); + return reply.send( + renderBrowserHandoffPage({ + handoffKind: (state.handoff ?? { kind: "browser_completion" }).kind, + status: "error", + provider: state.provider, + appSlug: state.app_slug, + mode: state.mode, + returnTo: state.return_to, + error, + }) + ); + } + return { error }; + }; + + const denyAttempt = async (state: OAuthStatePayload, denialCode: string): Promise => { + const handoff = state.handoff ?? { kind: "browser_completion" }; + if (handoff.kind !== "browser_completion" || !handoff.attemptId) return; + await store.updateAuthAttempt(state.app_slug, handoff.attemptId, { + status: "denied", + at: new Date().toISOString(), + denialCode, + }); + }; + + /** + * The person said no, at Heimdall's ask (`viewer`) or at the provider + * (`provider`, a returned access_denied). It is its own result, never a + * provider_error: the app and the audit log can tell a refusal from a fault. + * Nothing is stored beyond an audit row that names no one. + */ + const refuseConsent = async (request: FastifyRequest, reply: FastifyReply, state: OAuthStatePayload, by: "viewer" | "provider") => { + const handoff = state.handoff ?? { kind: "browser_completion" }; + await denyAttempt(state, "consent_refused"); + await store.createAuditEvent({ + appSlug: state.app_slug, + eventType: "consent_refused", + eventPayloadJson: { provider: state.provider, mode: state.mode, by }, + createdAt: new Date().toISOString(), + }); + if (handoff.kind === "backend_callback") { + await maybeDeliverBackendHandoff(handoff, { + source: "heimdall", + kind: "oauth_result", + handoffKind: "backend_callback", + attemptId: handoff.attemptId, + status: "error", + provider: state.provider, + appSlug: state.app_slug, + mode: state.mode, + returnTo: state.return_to, + connection: state.connection, + error: "consent_refused", + by, + }); + } + if (prefersHtml(request.headers.accept)) { + reply.type("text/html; charset=utf-8"); + return reply.send( + renderBrowserHandoffPage({ + handoffKind: handoff.kind, + status: "error", + provider: state.provider, + appSlug: state.app_slug, + mode: state.mode, + returnTo: state.return_to, + ...(handoff.attemptId ? { attemptId: handoff.attemptId } : {}), + error: "consent_refused", + by, + }) + ); + } + reply.code(400); + return { error: "consent_refused", by, provider: state.provider, returnTo: state.return_to }; + }; + + const providerNotConfigured = (reply: FastifyReply, state: OAuthStatePayload) => { + reply.code(503); + return { error: "provider_not_configured", provider: state.provider, expectedEnv: providerExpectedEnv(state.provider) }; + }; + + /** Claim the launch use, bind the browser, and send it to the provider. */ + const beginProviderRedirect = async (request: FastifyRequest, reply: FastifyReply, state: OAuthStatePayload, rawState: string, shownText?: string) => { + const clientId = config.providers[state.provider].clientId; + if (!clientId) { + return providerNotConfigured(reply, state); + } + const oidc = providerCatalog[state.provider].oidc ? deriveOidcSecrets(state.jti, keys.privateKey) : undefined; + // Built before the state is claimed: a state that cannot be honoured (a step-up for a provider with no + // re-authentication parameter) fails here without burning its launch use or setting the binding cookie. + const authorizationUrl = buildAuthorizationUrl({ + provider: state.provider, + clientId, + redirectUri: oauthCallbackUrl(config, state.provider), + state: rawState, + requestedScopes: state.requested_scopes ?? undefined, + ...(state.step_up ? { stepUp: true } : {}), + ...(oidc ? { oidc: { nonce: oidc.nonce, codeChallenge: oidc.codeChallenge } } : {}), + }); + const first = await store.claimOAuthStateUse({ + jti: state.jti, + phase: "launch", + appSlug: state.app_slug, + usedAt: new Date().toISOString(), + expiresAt: new Date(state.exp * 1000).toISOString(), + }); + if (!first) { + return refuseVerifiedState(request, reply, state, "state_already_launched"); + } + + setOAuthBindingCookie(reply, state, signOAuthBinding(config, keys, state, shownText), state.exp - nowEpochSeconds()); + reply.header("Cache-Control", "no-store"); + reply.header("Referrer-Policy", "no-referrer"); + return reply.redirect(authorizationUrl, 302); + }; + + app.get<{ + Params: { provider: Provider }; + Querystring: { state: string }; + }>( + "/v1/oauth/:provider/launch", + { + schema: { + params: { + type: "object", + required: ["provider"], + additionalProperties: false, + properties: { + provider: { type: "string", enum: [...providers] }, + }, + }, + querystring: { + type: "object", + required: ["state"], + additionalProperties: false, + properties: { + state: { type: "string", minLength: 1 }, + }, + }, + }, + }, + async (request, reply) => { + const verified = verifyOAuthState(config, keys, request.query.state, request.params.provider); + if (!verified.ok) { + reply.code(400); + return { error: verified.error }; + } + const state = verified.payload; + const askProfile = getAppProfile(state.app_slug); + if (askProfile && callbackMint(askProfile, state.provider, state.mode, state.connection) === "custody_only") { + if (!config.providers[state.provider].clientId) { + return providerNotConfigured(reply, state); + } + // Heimdall is about to hold a credential for the app: ask first. Viewing + // the ask claims nothing and binds nothing; only Continue spends the + // launch use and sets the launch binding. The ask's own cookie rides on + // the page so that the form's answer can only come from the browser + // that was shown it, and carries the text it was shown. + const ask = consentAskFor(state); + const shown = consentText(ask); + const askCookie = signConsentAsk(config, keys, state, shown); + // An ask the cookies cannot carry is refused, not shown: the person + // could press Continue and nothing would bind. + if (Buffer.byteLength(shown, "utf8") > maxConsentTextBytes || askCookie.length > maxConsentCookieChars) { + reply.code(400); + return { error: "consent_ask_too_large" }; + } + setConsentAskCookie(reply, state, askCookie, state.exp - nowEpochSeconds()); + reply.header("Cache-Control", "no-store"); + reply.header("Referrer-Policy", "no-referrer"); + reply.header("X-Frame-Options", "DENY"); + reply.header( + "Content-Security-Policy", + `default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'; base-uri 'none'; form-action 'self' ${new URL(providerCatalog[state.provider].authorizationEndpoint).origin}` + ); + reply.type("text/html; charset=utf-8"); + return reply.send(renderConsentPage(ask, request.query.state)); + } + return beginProviderRedirect(request, reply, state, request.query.state); + } + ); + + app.post<{ + Params: { provider: Provider }; + Body: { state: string; decision: "continue" | "decline" }; + }>( + "/v1/oauth/:provider/consent", + { + schema: { + params: { + type: "object", + required: ["provider"], + additionalProperties: false, + properties: { provider: { type: "string", enum: [...providers] } }, + }, + body: { + type: "object", + required: ["state", "decision"], + additionalProperties: false, + properties: { + state: { type: "string", minLength: 1 }, + decision: { type: "string", enum: ["continue", "decline"] }, + }, + }, + }, + }, + async (request, reply) => { + const verified = verifyOAuthState(config, keys, request.body.state, request.params.provider); + if (!verified.ok) { + reply.code(400); + return { error: verified.error }; + } + const state = verified.payload; + const profile = getAppProfile(state.app_slug); + if (!profile || callbackMint(profile, state.provider, state.mode, state.connection) !== "custody_only") { + reply.code(400); + return { error: "consent_not_required" }; + } + // Either answer must come from the browser the ask was shown to. + const shownText = cookieConsentText(config, keys, request.cookies[consentAskCookieName(state.jti)], consentAskType, state); + if (shownText === null) { + return refuseVerifiedState(request, reply, state, "state_not_bound"); + } + setConsentAskCookie(reply, state, "", 0); + if (request.body.decision === "continue") { + return beginProviderRedirect(request, reply, state, request.body.state, shownText); + } + // A decline spends both uses of the state: it can neither launch nor complete afterwards. + const usedAt = new Date().toISOString(); + const expiresAt = new Date(state.exp * 1000).toISOString(); + if (!(await store.claimOAuthStateUse({ jti: state.jti, phase: "launch", appSlug: state.app_slug, usedAt, expiresAt }))) { + return refuseVerifiedState(request, reply, state, "state_already_launched"); + } + await store.claimOAuthStateUse({ jti: state.jti, phase: "callback", appSlug: state.app_slug, usedAt, expiresAt }); + setOAuthBindingCookie(reply, state, "", 0); + return refuseConsent(request, reply, state, "viewer"); + } + ); + app.get<{ Params: { provider: Provider }; Querystring: { code?: string; state?: string; error?: string; error_description?: string }; @@ -905,27 +1859,49 @@ export async function buildApp(options: BuildAppOptions = {}): Promise => { - if (handoff.kind !== "browser_completion" || !handoff.attemptId) return; - await store.updateAuthAttempt(statePayload.app_slug, handoff.attemptId, { - status: "denied", - at: new Date().toISOString(), - denialCode, - }); - }; + const denyBrowserAttempt = (denialCode: string): Promise => denyAttempt(statePayload, denialCode); + // The cookie is checked before the claim: a stranger without it must not be + // able to burn the state that the browser that launched it still needs. + // The attempt is denied, though: a launcher whose cookie lapsed can never + // complete this state, and its page polls an attempt that would otherwise + // sit pending until it expires. + if (!oauthBindingHolds(config, keys, request.cookies[oauthBindingCookieName(statePayload.jti)], statePayload)) { + await denyBrowserAttempt("state_not_bound"); + return refuseVerifiedState(request, reply, statePayload, "state_not_bound"); + } + // A custody flow carries the wording its person was shown in the launch + // binding. A binding without it did not pass through the ask (a launch + // from before it existed): refuse here, before the state is spent and + // before any code is exchanged, so nothing is kept and nothing is burned. + const shownText = cookieConsentText(config, keys, request.cookies[oauthBindingCookieName(statePayload.jti)], oauthBindingType, statePayload); + const callbackProfile = getAppProfile(statePayload.app_slug); + const mint = callbackProfile ? callbackMint(callbackProfile, request.params.provider, statePayload.mode, statePayload.connection) : "refused"; + if (mint === "custody_only" && shownText === null) { + await denyBrowserAttempt("consent_text_missing"); + return refuseVerifiedState(request, reply, statePayload, "consent_text_missing"); + } + setOAuthBindingCookie(reply, statePayload, "", 0); + const firstCallback = await store.claimOAuthStateUse({ + jti: statePayload.jti, + phase: "callback", + appSlug: statePayload.app_slug, + usedAt: new Date().toISOString(), + expiresAt: new Date(statePayload.exp * 1000).toISOString(), + }); + if (!firstCallback) { + return refuseVerifiedState(request, reply, statePayload, "state_already_used"); + } + if (request.query.error === "access_denied") { + return refuseConsent(request, reply, statePayload, "provider"); + } if (request.query.error) { const providerError = relayedProviderText(request.query.error, 64); const providerErrorDescription = relayedProviderText(request.query.error_description, 256); @@ -1018,50 +1994,51 @@ export async function buildApp(options: BuildAppOptions = {}): Promise { const linkedIdentityInput: UpsertLinkedIdentityInput = { - accountId: account.id, + accountId, provider: identity.provider, providerUserId: identity.providerUserId, scopes: tokenSet.scope, @@ -1085,7 +2062,128 @@ export async function buildApp(options: BuildAppOptions = {}): Promise, @@ -1284,6 +2405,7 @@ export async function buildApp(options: BuildAppOptions = {}): Promise( + "/v1/apps/:appSlug/links/confirm", + { + schema: { + params: { + type: "object", + required: ["appSlug"], + additionalProperties: false, + properties: { appSlug: { type: "string", enum: [...appSlugs] } }, + }, + body: { + type: "object", + required: ["pendingLinkId"], + additionalProperties: false, + properties: { pendingLinkId: { type: "string", minLength: 1 } }, + }, + }, + }, + async (request, reply) => { + const accountId = await resolveLinkAccount({ config, keys, store }, request.params.appSlug, request.headers.authorization); + if (!accountId) { + reply.code(401); + return { error: "invalid_link_session", detail: "The bearer is not a live Heimdall access token for this app." }; + } + const nowIso = new Date().toISOString(); + const pending = await store.consumePendingLink(request.params.appSlug, request.body.pendingLinkId, accountId, nowIso); + if (!pending) { + reply.code(410); + return { error: "invalid_or_expired_pending_link" }; + } + const holder = await store.findAccountByLinkedIdentity(pending.provider, pending.providerUserId); + if (holder && holder.id !== accountId) { + reply.code(409); + return { error: "identity_linked_elsewhere" }; + } + try { + await store.upsertLinkedIdentity({ ...pending.identity, accountId, updatedAt: nowIso }); + } catch (error) { + // The holder check above is the fast path; a second account may win the race to the identity. + if (!(error instanceof IdentityHeldElsewhereError)) throw error; + reply.code(409); + return { error: "identity_linked_elsewhere" }; + } + await store.createAuditEvent({ + accountId, + appSlug: pending.appSlug, + eventType: "link_confirmed", + eventPayloadJson: { provider: pending.provider }, + createdAt: nowIso, + }); + reply.code(201); + return { status: "linked", provider: pending.provider, accountId, returnTo: pending.returnTo }; + } + ); + app.post<{ Params: { appSlug: AppSlug }; Body: RedeemAuthCompletionRequest }>( "/v1/apps/:appSlug/auth-completions/redeem", { @@ -1388,12 +2573,38 @@ export async function buildApp(options: BuildAppOptions = {}): Promise { const nowIso = new Date().toISOString(); + // Sign-in and connect completions are redeemed by the browser flow, so + // the route stays open to it. A link completion was minted for an + // initiator the authenticated app named at start; only that app's + // backend redeems it. Redeem is also where the connection target is + // held to what the signed state named, both ways: a target the state never named is refused too. Both refusals read the row + // without consuming it, so a wrong caller or target cannot burn the code. + const pending = await store.findAuthCompletion(request.params.appSlug, request.body.completionCode); + if (pending && !pending.consumedAt && pending.expiresAt > nowIso) { + if (pending.mode === "link" && !resolveAppCaller(config, request.params.appSlug, request.headers)) { + reply.code(401); + return { error: "app_auth_required" }; + } + if (pending.targetId !== request.body.targetId) { + await store.createAuditEvent({ + accountId: pending.accountId, + sessionId: pending.sessionId, + appSlug: pending.appSlug, + eventType: "auth_completion_target_refused", + eventPayloadJson: { provider: pending.provider, mode: pending.mode }, + createdAt: nowIso, + }); + reply.code(403); + return { error: "completion_target_mismatch" }; + } + } const completion = await store.consumeAuthCompletion(request.params.appSlug, request.body.completionCode, nowIso); if (!completion) { @@ -1523,6 +2734,37 @@ export async function buildApp(options: BuildAppOptions = {}): Promise( + "/v1/apps/:appSlug/step-up", + { + schema: { + params: { + type: "object", + required: ["appSlug"], + additionalProperties: false, + properties: { appSlug: { type: "string", enum: [...appSlugs] } }, + }, + body: { + type: "object", + required: ["method", "nonce"], + additionalProperties: false, + properties: { + method: { type: "string", minLength: 1, maxLength: 64 }, + // base64url alphabet: what a random token looks like, and no spaces, controls or lone surrogates. + nonce: { type: "string", pattern: "^[A-Za-z0-9_-]{16,128}$" }, + }, + }, + }, + }, + async (request, reply) => { + const result = await assertStepUp({ config, keys, store }, stepUpBudgets, request.params.appSlug, request.headers, request.body); + reply.code(result.statusCode).header("cache-control", "no-store"); + return result.body; + } + ); + app.post<{ Params: { appSlug: AppSlug }; Body: { @@ -1767,5 +3009,236 @@ export async function buildApp(options: BuildAppOptions = {}): Promise => { + const bearerAccount = await resolveAccessAccount({ config, keys, store }, request.headers.authorization); + if (bearerAccount) return { accountId: bearerAccount, exp: nowEpochSeconds() + grantsPageTokenTtlSeconds }; + return grantsPageTokenAccount(config, keys, pageToken); + }; + + const grantsReply = (reply: FastifyReply) => { + reply.header("Cache-Control", "no-store"); + reply.header("Referrer-Policy", "no-referrer"); + reply.header("X-Frame-Options", "DENY"); + reply.header("Content-Security-Policy", "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'"); + }; + + const signInRequired = (reply: FastifyReply) => { + reply.code(401); + return { error: "sign_in_required", detail: "Send a Heimdall access token as a Bearer token, or open a link from POST /v1/me/grants/link." }; + }; + + /** + * Writes a revocation receipt for each live grant the account holds on + * `provider` (whichever app asked: the credential is one row per account and + * provider), and the audit event naming them. The credential is gone or + * stripped first, so a failure here leaves a receipt that still reads active + * over a credential that is gone, never the reverse. Returns the grants this + * call revoked. + */ + const revokeLiveGrants = async (accountId: string, provider: Provider, receipts: Parameters[0], at: string): Promise => { + const revoked: string[] = []; + for (const live of grantViews(receipts).filter((view) => view.provider === provider && view.status === "active")) { + const { created } = await store.createConsentReceipt({ + kind: "revocation", + accountId, + appSlug: live.appSlug, + provider: live.provider, + createdAt: at, + revokesReceiptId: live.id, + }); + // A concurrent revoke may have written it first; only the writer reports it. + if (created) revoked.push(live.id); + } + if (revoked.length) { + await store.createAuditEvent({ accountId, eventType: "consent_revoked", eventPayloadJson: { provider, grantIds: revoked }, createdAt: at }); + } + return revoked; + }; + + const identityViews = async (accountId: string) => + (await store.listStoredLinkedIdentitiesForAccount(accountId)).map((identity) => ({ + id: identity.id, + provider: identity.provider, + providerUserId: identity.providerUserId, + ...(identity.username !== undefined ? { username: identity.username } : {}), + ...(identity.displayName !== undefined ? { displayName: identity.displayName } : {}), + linkedAt: identity.createdAt, + scopes: identity.scopes, + })); + + // The identities an account holds: ids and public profile facts, never a + // credential, a stored profile or an email. + app.get("/v1/me/identities", async (request, reply) => { + const bearer = await resolveBearer({ config, keys, store }, request.headers.authorization); + if (!bearer) return signInRequired(reply); + grantsReply(reply); + return { accountId: bearer.accountId, identities: await identityViews(bearer.accountId) }; + }); + + // Taking an identity off the account. The bearer alone is not enough: the + // access token must come from a step-up sign-in inside the proof window, and + // a refresh never carries that proof forward. + app.post<{ Params: { identityId: string }; Body?: null }>( + "/v1/me/identities/:identityId/unlink", + { + schema: { + params: { type: "object", required: ["identityId"], additionalProperties: false, properties: { identityId: { type: "string", minLength: 1 } } }, + body: { type: ["object", "null"], additionalProperties: false, properties: {} }, + }, + }, + async (request, reply) => { + const bearer = await resolveBearer({ config, keys, store }, request.headers.authorization); + if (!bearer) return signInRequired(reply); + grantsReply(reply); + const { accountId, claims } = bearer; + const nowS = nowEpochSeconds(); + if (proofTier(claims, nowS) !== "strong") { + reply.code(403); + return { + error: "step_up_required", + detail: `Unlinking needs a sign-in with stepUp completed within the last ${STEP_UP_PROOF_TTL_SECONDS} seconds: POST /v1/oauth/{provider}/start with mode sign_in and stepUp true through an identity on this account whose provider has re-authentication parameters (today twitch, youtube and google; discord and patreon cannot prove), then use the access token that sign-in returns.`, + }; + } + const result = await store.unlinkLinkedIdentity(accountId, request.params.identityId); + if (result.kind === "not_found") { + reply.code(404); + return { error: "identity_not_found" }; + } + if (result.kind === "last_identity") { + reply.code(409); + return { error: "last_identity", detail: "This is the account's only identity; unlinking it would leave the account unreachable." }; + } + const { identity } = result; + const at = new Date().toISOString(); + await store.createAuditEvent({ + accountId, + eventType: "identity_unlinked", + eventPayloadJson: { provider: identity.provider, identityId: identity.id, stepUpMethod: typeof claims.step_up_method === "string" ? claims.step_up_method : null }, + createdAt: at, + }); + // The credential went with the row. When no identity of that provider + // is left, the grants that rested on it are taken back in the record too. + const remaining = await store.listStoredLinkedIdentitiesForAccount(accountId); + if (!remaining.some((other) => other.provider === identity.provider)) { + await revokeLiveGrants(accountId, identity.provider, await store.listConsentReceipts(accountId), at); + } + return { + unlinked: { id: identity.id, provider: identity.provider, providerUserId: identity.providerUserId }, + identities: await identityViews(accountId), + }; + } + ); + + // The sanctioned mover of logins between accounts: see moveIdentitiesRoute. Registered here because it + // needs revokeLiveGrants, which belongs to this scope. + app.post<{ Params: { appSlug: AppSlug }; Body: MoveIdentitiesBody }>( + "/v1/apps/:appSlug/identity-moves", + { + schema: { + params: { + type: "object", + required: ["appSlug"], + additionalProperties: false, + properties: { appSlug: { type: "string", enum: [...appSlugs] } }, + }, + body: { + type: "object", + required: ["moveId", "fromProofs"], + additionalProperties: false, + properties: { + moveId: { type: "string", pattern: MOVE_ID_PATTERN }, + fromProofs: { type: "array", minItems: 1, maxItems: 8, items: { type: "string", minLength: 1, maxLength: 8192 } }, + toProof: { type: "string", minLength: 1, maxLength: 8192 }, + identityIds: { type: "array", minItems: 1, maxItems: 32, uniqueItems: true, items: { type: "string", minLength: 1 } }, + reversesMoveId: { type: "string", pattern: MOVE_ID_PATTERN }, + }, + // A forward move names its destination proof; a reversal names the move and nothing else about who or what. + oneOf: [ + { required: ["toProof"], not: { anyOf: [{ required: ["reversesMoveId"] }] } }, + { required: ["reversesMoveId"], not: { anyOf: [{ required: ["toProof"] }, { required: ["identityIds"] }] } }, + ], + }, + }, + }, + async (request, reply) => { + const result = await moveIdentitiesRoute({ config, keys, store }, revokeLiveGrants, request.params.appSlug, request.headers, request.body); + reply.code(result.statusCode).header("cache-control", "no-store"); + return result.body; + } + ); + + // The signed-in surface for consent: every grant and receipt the account + // holds, and the one-click way to take each back. + app.get<{ Querystring: { t?: string } }>( + GRANTS_PATH, + { schema: { querystring: { type: "object", additionalProperties: false, properties: { t: { type: "string" } } } } }, + async (request, reply) => { + const caller = await grantsAccount(request, request.query.t); + if (!caller) return signInRequired(reply); + const { accountId } = caller; + grantsReply(reply); + const receipts = await store.listConsentReceipts(accountId); + if (prefersHtml(request.headers.accept)) { + reply.type("text/html; charset=utf-8"); + return reply.send(renderGrantsPage(grantViews(receipts), signGrantsPageToken(config, keys, accountId, caller.exp))); + } + return { grants: grantViews(receipts), receipts }; + } + ); + + // A link a browser can open: short-lived, opens the grants page and nothing else. + app.post(`${GRANTS_PATH}/link`, async (request, reply) => { + const accountId = await resolveAccessAccount({ config, keys, store }, request.headers.authorization); + if (!accountId) return signInRequired(reply); + grantsReply(reply); + reply.code(201); + return { + url: `${config.publicBaseUrl}${GRANTS_PATH}?t=${encodeURIComponent(signGrantsPageToken(config, keys, accountId))}`, + expiresInSeconds: grantsPageTokenTtlSeconds, + }; + }); + + app.post<{ Params: { grantId: string }; Body?: { t?: string } }>( + `${GRANTS_PATH}/:grantId/revoke`, + { + schema: { + params: { type: "object", required: ["grantId"], additionalProperties: false, properties: { grantId: { type: "string", minLength: 1 } } }, + body: { type: ["object", "null"], additionalProperties: false, properties: { t: { type: "string" } } }, + }, + }, + async (request, reply) => { + const caller = await grantsAccount(request, request.body?.t); + if (!caller) return signInRequired(reply); + const { accountId } = caller; + grantsReply(reply); + const receipts = await store.listConsentReceipts(accountId); + const grant = grantViews(receipts).find((view) => view.id === request.params.grantId); + if (!grant) { + reply.code(404); + return { error: "grant_not_found" }; + } + const revoked: string[] = []; + if (grant.status === "active") { + // The credential is one row per account and provider, whichever app + // asked, so taking it back ends every live grant that rests on it. + // It is stripped first: a failure after that leaves a receipt that + // still reads active over a credential that is gone, never the reverse. + const identity = await store.findStoredLinkedIdentityForAccount(accountId, grant.provider); + const at = new Date().toISOString(); + if (identity) { + await store.updateLinkedIdentityCredential(identity.id, async () => ({ kind: "revoke", updatedAt: at })); + } + revoked.push(...(await revokeLiveGrants(accountId, grant.provider, receipts, at))); + } + if (prefersHtml(request.headers.accept) || request.headers["content-type"]?.startsWith("application/x-www-form-urlencoded")) { + reply.type("text/html; charset=utf-8"); + const views = grantViews(await store.listConsentReceipts(accountId)); + return reply.send(renderGrantsPage(views, signGrantsPageToken(config, keys, accountId, caller.exp), revoked.length ? "Taken back." : "Already taken back.")); + } + return { revoked, grants: grantViews(await store.listConsentReceipts(accountId)) }; + } + ); + return app; } diff --git a/src/backend-handoff.ts b/src/backend-handoff.ts index 204c570..b26a59f 100644 --- a/src/backend-handoff.ts +++ b/src/backend-handoff.ts @@ -30,6 +30,8 @@ export interface BackendHandoffSuccessPayload mode: OAuthMode; account: AccountSummary; entitlements: EntitlementEvaluation; + /** The receipt of the consent a managed connection rests on. */ + consentReceiptId?: string; } export interface BackendHandoffErrorPayload extends BackendHandoffBase { @@ -37,9 +39,20 @@ export interface BackendHandoffErrorPayload extends BackendHandoffBase { mode?: OAuthMode; error: string; errorDescription?: string; + /** Who said no, when `error` is consent_refused. */ + by?: "viewer" | "provider"; } -export type BackendHandoffPayload = BackendHandoffSuccessPayload | BackendHandoffErrorPayload; +/** A verified link that waits for the initiating account's confirm: no session, no tokens. */ +export interface BackendHandoffLinkPendingPayload extends BackendHandoffBase { + status: "link_pending"; + mode: OAuthMode; + pendingLinkId: string; + expiresAt: string; + confirmEndpoint: string; +} + +export type BackendHandoffPayload = BackendHandoffSuccessPayload | BackendHandoffErrorPayload | BackendHandoffLinkPendingPayload; export async function deliverBackendHandoff(callbackUrl: string, payload: BackendHandoffPayload): Promise { const response = await fetch(callbackUrl, { diff --git a/src/browser-handoff.ts b/src/browser-handoff.ts index e23601e..b8da567 100644 --- a/src/browser-handoff.ts +++ b/src/browser-handoff.ts @@ -12,7 +12,11 @@ export interface BrowserHandoffSuccess extends BrowserHandoffBase { status: "success"; mode: OAuthMode; completionCode?: string; + /** A verified link waiting for its initiator's confirm; carries no session. */ + pendingLinkId?: string; attemptId?: string; + /** The receipt of the consent a managed connection rests on. */ + consentReceiptId?: string; } export interface BrowserHandoffError extends BrowserHandoffBase { @@ -20,6 +24,8 @@ export interface BrowserHandoffError extends BrowserHandoffBase { error: string; errorDescription?: string; attemptId?: string; + /** Who said no, when `error` is consent_refused. */ + by?: "viewer" | "provider"; } export type BrowserHandoffPayload = BrowserHandoffSuccess | BrowserHandoffError; @@ -45,11 +51,19 @@ function buildBrowserFallbackUrl(payload: BrowserHandoffPayload): string { fragment.set("heimdall_attempt_id", payload.attemptId); } + if (payload.status === "success" && payload.consentReceiptId) { + fragment.set("heimdall_consent_receipt_id", payload.consentReceiptId); + } if (payload.status === "success" && payload.completionCode) { fragment.set("heimdall_completion_code", payload.completionCode); + } else if (payload.status === "success" && payload.pendingLinkId) { + fragment.set("heimdall_pending_link_id", payload.pendingLinkId); } else { if (payload.status === "error") { fragment.set("heimdall_error", payload.error); + if (payload.by) { + fragment.set("heimdall_refused_by", payload.by); + } if (payload.errorDescription) { fragment.set("heimdall_error_description", payload.errorDescription); } @@ -73,14 +87,19 @@ export function renderBrowserHandoffPage(payload: BrowserHandoffPayload): string }); const scriptOrigin = serializeForScript(targetOrigin); const scriptFallbackUrl = serializeForScript(fallbackUrl); - const scriptTitle = serializeForScript( - payload.status === "success" ? "Authentication Complete" : "Authentication Failed" - ); + const refused = payload.status === "error" && payload.error === "consent_refused"; + const pageTitle = refused ? "Not Connected" : payload.status === "success" ? "Authentication Complete" : "Authentication Failed"; + const scriptTitle = serializeForScript(pageTitle); const scriptBody = serializeForScript( - payload.status === "success" - ? payload.handoffKind === "backend_callback" - ? "The app backend has the auth result already. You can return to the app now." - : "You can return to the app now." + refused + ? "Nothing was connected and nothing was kept. You can return to the app." + : payload.status === "success" + ? (payload.handoffKind === "backend_callback" + ? "The app backend has the auth result already. You can return to the app now." + : "You can return to the app now.") + + (payload.consentReceiptId + ? ` Your consent is recorded as receipt ${payload.consentReceiptId}; you can review it and take it back from your Heimdall connections page.` + : "") : "The authentication flow failed. Return to the app to continue." ); @@ -89,7 +108,7 @@ export function renderBrowserHandoffPage(payload: BrowserHandoffPayload): string - ${payload.status === "success" ? "Authentication Complete" : "Authentication Failed"} + ${pageTitle} + + +
+${body} +
+ +`; +} + +/** The ask. Two POST forms carry the signed state; the page runs no script. */ +export function renderConsentPage(ask: ConsentAsk, state: string): string { + const lines = consentLines(ask); + const provider = providerCatalog[ask.provider].displayName; + const [headline, ...rest] = lines; + const form = (decision: "continue" | "decline", label: string) => + ``; + return page( + `${appName(ask.appSlug)} wants to connect ${provider}`, + `

${escapeHtml(headline!)}

+
    +${rest.map((line) => `
  • ${escapeHtml(line)}
  • `).join("\n")} +
+
+ + ${form("continue", consentButtons(ask).go)} + ${form("decline", consentButtons(ask).no)} +
` + ); +} + +export interface GrantView { + consentText: string; + id: string; + appSlug: AppSlug; + provider: Provider; + scopesAsked: string[]; + scopesGranted: string[]; + grantedAt: string; + consentPageDigest: string; + status: "active" | "revoked"; + revokedAt?: string; + revocationReceiptId?: string; +} + +/** Every grant the receipts hold, each live unless a revocation names it. */ +export function grantViews(receipts: readonly StoredConsentReceipt[]): GrantView[] { + const revocations = new Map(); + for (const receipt of receipts) { + if (receipt.kind === "revocation") revocations.set(receipt.revokesReceiptId, receipt); + } + const views: GrantView[] = []; + for (const receipt of receipts) { + if (receipt.kind !== "grant") continue; + const revocation = revocations.get(receipt.id); + views.push({ + id: receipt.id, + appSlug: receipt.appSlug, + provider: receipt.provider, + scopesAsked: receipt.scopesAsked, + scopesGranted: receipt.scopesGranted, + grantedAt: receipt.createdAt, + consentPageDigest: receipt.consentPageDigest, + consentText: receipt.consentText, + status: revocation ? "revoked" : "active", + ...(revocation ? { revokedAt: revocation.createdAt, revocationReceiptId: revocation.id } : {}), + }); + } + return views; +} + +/** The signed-in page: every grant with its receipt, one button each to take it back. */ +export function renderGrantsPage(grants: readonly GrantView[], pageToken: string, notice?: string): string { + const cards = grants.length + ? grants + .map((grant) => { + const provider = providerCatalog[grant.provider].displayName; + const header = `${escapeHtml(appName(grant.appSlug))} → ${escapeHtml(provider)}`; + const detail = `granted ${escapeHtml(grant.grantedAt)}; permissions ${escapeHtml(grant.scopesGranted.join(", ") || "none returned")}; receipt ${escapeHtml(grant.id)}; wording ${escapeHtml(grant.consentPageDigest.slice(0, 12))}`; + if (grant.status === "revoked") { + return `
${header} taken back ${escapeHtml(grant.revokedAt ?? "")}; receipt ${escapeHtml(grant.revocationReceiptId ?? "")}
${detail}
`; + } + return `
${header} active
${detail} +
+ + +
`; + }) + .join("\n") + : `

You have not connected anything through Heimdall.

`; + return page( + "Your connections", + `

Your connections

+${notice ? `

${escapeHtml(notice)}

\n` : ""}${cards} +

Taking a connection back deletes Heimdall's copy of the tokens. The app's next request for a token is refused. The permission stays with the provider until you remove it in the provider's settings.

` + ); +} diff --git a/src/contracts.ts b/src/contracts.ts index d6cab2a..78a3a60 100644 --- a/src/contracts.ts +++ b/src/contracts.ts @@ -1,4 +1,4 @@ -export const providers = ["discord", "patreon", "github", "twitch", "youtube", "spotify", "joystick"] as const; +export const providers = ["discord", "patreon", "github", "twitch", "youtube", "spotify", "joystick", "google"] as const; export type Provider = (typeof providers)[number]; @@ -73,9 +73,13 @@ export interface OAuthStartRequest { mode: OAuthMode; returnTo: string; connection?: OAuthConnectionBinding; + /** Link mode only: the account the authenticated app says is linking. Carried in the signed state. */ + initiatingAccountId?: string; handoff?: OAuthHandoff; requestedScopes?: string[]; entitlementPolicy?: OAuthEntitlementPolicy; + /** Sign_in only, app-authenticated: ask the provider for a real re-authentication. Off when absent. */ + stepUp?: boolean; } export interface OAuthStatePayload { @@ -92,8 +96,13 @@ export interface OAuthStatePayload { mode: OAuthMode; return_to: string; connection: OAuthConnectionBinding | null; + initiator_account_id: string | null; handoff: OAuthHandoff | null; entitlement_policy: OAuthEntitlementPolicy | null; + /** The start's requestedScopes, carried so the launch hop can build the provider URL from the signed state alone. */ + requested_scopes: string[] | null; + /** The start's step-up request. Signed, so the launch hop reads it here and nowhere else; null when not asked. */ + step_up: true | null; } export interface LinkedIdentityInput { @@ -105,6 +114,8 @@ export interface LinkedIdentityInput { export interface RedeemAuthCompletionRequest { completionCode: string; + /** Required when the completion was minted for a connection target; must equal it. */ + targetId?: string; } export type HeimdallAuthAttemptStatus = "pending" | "completed" | "denied" | "consumed" | "expired"; @@ -142,6 +153,19 @@ export interface AccessClaimPayload { typ: "heimdall_access"; account_id: string; access_revision: number; + /** Epoch seconds of the step-up sign-in this access token was minted by; absent on every other token, and never carried by a refresh. */ + step_up_at?: number; + /** + * How the proof in step_up_at was made: `provider:` for a step-up + * sign-in Heimdall ran, or one of the calling app's allowlisted method + * labels when the app asserted it (POST /v1/apps/{app}/step-up). Present + * exactly when step_up_at is; never carried by a refresh. + */ + step_up_method?: string; + /** Epoch seconds of the sign-in this access token was minted by, with auth_identity_id; absent unless a sign_in callback minted it, and never carried by a refresh. */ + auth_at?: number; + /** The linked_identities.id the sign-in came through; present exactly when auth_at is. It is the only record of which login proved the session, and it describes the sign-in, not an asserted factor. */ + auth_identity_id?: string; display_name?: string; app: { slug: AppSlug; diff --git a/src/fixed-window.ts b/src/fixed-window.ts new file mode 100644 index 0000000..cfb7f00 --- /dev/null +++ b/src/fixed-window.ts @@ -0,0 +1,49 @@ +// A fixed-window attempt budget per key, held in memory by the process that +// serves the route. It bounds a credentialed caller's rate; it is not a +// security boundary on its own and resets on restart. The clock is injected +// so tests can move it. + +export interface FixedWindowLimit { + max: number; + windowMs: number; +} + +export class FixedWindowBudget { + private readonly windows = new Map(); + + constructor( + private readonly limit: FixedWindowLimit, + private readonly now: () => number = Date.now, + private readonly maxKeys = 4096, + ) {} + + /** + * Spend one attempt for `key`. `n` counts attempts in the window, denied ones + * included, so a caller can act on the first denial (`n === max + 1`) and not + * on the flood behind it. `retryAfterSeconds` is 0 when allowed. + */ + spend(key: string): { n: number; retryAfterSeconds: number } { + const at = this.now(); + let current = this.windows.get(key); + if (!current || at - current.startedAt >= this.limit.windowMs) { + this.sweep(at); + current = { startedAt: at, used: 0 }; + this.windows.set(key, current); + } + current.used += 1; + if (current.used <= this.limit.max) return { n: current.used, retryAfterSeconds: 0 }; + return { n: current.used, retryAfterSeconds: Math.max(1, Math.ceil((current.startedAt + this.limit.windowMs - at) / 1000)) }; + } + + /** Drop turned-over windows once the table is full; if it is still full, the oldest key goes. */ + private sweep(at: number): void { + if (this.windows.size < this.maxKeys) return; + for (const [key, window] of this.windows) { + if (at - window.startedAt >= this.limit.windowMs) this.windows.delete(key); + } + if (this.windows.size >= this.maxKeys) { + const oldest = this.windows.keys().next().value; + if (oldest !== undefined) this.windows.delete(oldest); + } + } +} diff --git a/src/google-oidc.ts b/src/google-oidc.ts new file mode 100644 index 0000000..b368e45 --- /dev/null +++ b/src/google-oidc.ts @@ -0,0 +1,228 @@ +import { createHash, createPublicKey, sign, verify, type KeyObject } from "node:crypto"; + +/** + * Google sign-in as OpenID Connect: the id_token is the identity, and this + * file is the one place that decides whether to believe it. The subject + * (`sub`) is the account key; the email is a claim about the subject, never + * its key. + */ + +export const GOOGLE_ISSUERS = ["https://accounts.google.com", "accounts.google.com"] as const; +export const GOOGLE_JWKS_URI = "https://www.googleapis.com/oauth2/v3/certs"; + +const CLOCK_LEEWAY_SECONDS = 60; +const DEFAULT_JWKS_TTL_SECONDS = 3600; +const MAX_JWKS_TTL_SECONDS = 24 * 3600; +/** An unknown `kid` refetches the key set at most this often. */ +const MIN_JWKS_REFETCH_MS = 60_000; + +export type GoogleIdTokenFailure = + | "malformed" + | "unsupported_algorithm" + | "unknown_key" + | "bad_signature" + | "bad_issuer" + | "bad_audience" + | "expired" + | "not_yet_valid" + | "bad_nonce" + | "missing_subject" + | "email_missing" + | "email_not_verified" + | "jwks_unavailable"; + +/** A refusal that names the rule that failed and quotes nothing from the token. */ +export class GoogleIdTokenError extends Error { + readonly code: GoogleIdTokenFailure; + + constructor(code: GoogleIdTokenFailure) { + super(`Google id_token refused (${code}).`); + this.name = "GoogleIdTokenError"; + this.code = code; + } +} + +export interface GoogleIdentityClaims { + sub: string; + email: string; + name?: string; + picture?: string; + hd?: string; +} + +interface Jwk { + kid?: string; + kty?: string; + alg?: string; + n?: string; + e?: string; +} + +let cachedKeys: { keys: Map; expiresAt: number; fetchedAt: number } | null = null; + +export function resetGoogleJwksCache(): void { + cachedKeys = null; +} + +async function fetchGoogleKeys(now: number): Promise<{ keys: Map; expiresAt: number; fetchedAt: number }> { + let response: Response; + try { + response = await fetch(GOOGLE_JWKS_URI, { headers: { Accept: "application/json" } }); + } catch { + throw new GoogleIdTokenError("jwks_unavailable"); + } + if (!response.ok) { + throw new GoogleIdTokenError("jwks_unavailable"); + } + let body: { keys?: Jwk[] }; + try { + body = (await response.json()) as { keys?: Jwk[] }; + } catch { + throw new GoogleIdTokenError("jwks_unavailable"); + } + const keys = new Map(); + for (const jwk of body.keys ?? []) { + if (jwk.kty !== "RSA" || !jwk.kid || (jwk.alg !== undefined && jwk.alg !== "RS256")) continue; + try { + keys.set(jwk.kid, createPublicKey({ key: jwk as never, format: "jwk" })); + } catch { + // A key Node cannot read verifies nothing; the others stand. + } + } + const maxAge = /max-age=(\d+)/.exec(response.headers.get("cache-control") ?? ""); + const ttl = Math.min(maxAge ? Number(maxAge[1]) : DEFAULT_JWKS_TTL_SECONDS, MAX_JWKS_TTL_SECONDS); + return { keys, expiresAt: now + ttl * 1000, fetchedAt: now }; +} + +async function keyForKid(kid: string, now: number): Promise { + if (cachedKeys && cachedKeys.expiresAt > now) { + const hit = cachedKeys.keys.get(kid); + if (hit) return hit; + // Unknown kid in a live cache: Google may have rotated. Refetch, but not on every bad token. + if (now - cachedKeys.fetchedAt < MIN_JWKS_REFETCH_MS) { + throw new GoogleIdTokenError("unknown_key"); + } + } + cachedKeys = await fetchGoogleKeys(now); + const key = cachedKeys.keys.get(kid); + if (!key) throw new GoogleIdTokenError("unknown_key"); + return key; +} + +function decodeSegment(segment: string): Record { + try { + const value = JSON.parse(Buffer.from(segment, "base64url").toString("utf8")) as unknown; + if (typeof value === "object" && value !== null && !Array.isArray(value)) { + return value as Record; + } + } catch { + // fallthrough + } + throw new GoogleIdTokenError("malformed"); +} + +/** + * Verifies a Google id_token for this client. Order is signature first, then + * claims, so no claim of an unauthenticated token decides anything. Refuses + * on: algorithm other than RS256, unknown key, bad signature, `iss` not + * Google, `aud` not this client (an array `aud` also needs `azp` to be this + * client), `exp` passed, `iat` or `nbf` in the future, `nonce` not the one + * this authorization request carried, no `sub`, no `email`, and an email + * Google has not verified. + */ +export async function verifyGoogleIdToken( + idToken: string, + expected: { clientId: string; nonce: string }, + nowMs: number = Date.now() +): Promise { + const parts = idToken.split("."); + if (parts.length !== 3 || parts.some((part) => part === "")) { + throw new GoogleIdTokenError("malformed"); + } + const [encodedHeader, encodedPayload, encodedSignature] = parts as [string, string, string]; + const header = decodeSegment(encodedHeader); + if (header.alg !== "RS256") { + throw new GoogleIdTokenError("unsupported_algorithm"); + } + if (typeof header.kid !== "string" || header.kid === "") { + throw new GoogleIdTokenError("unknown_key"); + } + + const key = await keyForKid(header.kid, nowMs); + const signatureValid = verify( + "RSA-SHA256", + Buffer.from(`${encodedHeader}.${encodedPayload}`, "utf8"), + key, + Buffer.from(encodedSignature, "base64url") + ); + if (!signatureValid) { + throw new GoogleIdTokenError("bad_signature"); + } + + const claims = decodeSegment(encodedPayload); + const nowSeconds = Math.floor(nowMs / 1000); + + if (typeof claims.iss !== "string" || !(GOOGLE_ISSUERS as readonly string[]).includes(claims.iss)) { + throw new GoogleIdTokenError("bad_issuer"); + } + const aud = claims.aud; + const audienceOk = + typeof aud === "string" + ? aud === expected.clientId + : Array.isArray(aud) && aud.includes(expected.clientId) && claims.azp === expected.clientId; + if (!audienceOk) { + throw new GoogleIdTokenError("bad_audience"); + } + if (typeof claims.exp !== "number" || claims.exp + CLOCK_LEEWAY_SECONDS <= nowSeconds) { + throw new GoogleIdTokenError("expired"); + } + if (typeof claims.iat !== "number" || claims.iat - CLOCK_LEEWAY_SECONDS > nowSeconds) { + throw new GoogleIdTokenError("not_yet_valid"); + } + if (claims.nbf !== undefined && (typeof claims.nbf !== "number" || claims.nbf - CLOCK_LEEWAY_SECONDS > nowSeconds)) { + throw new GoogleIdTokenError("not_yet_valid"); + } + if (typeof claims.nonce !== "string" || claims.nonce !== expected.nonce) { + throw new GoogleIdTokenError("bad_nonce"); + } + if (typeof claims.sub !== "string" || claims.sub === "" || claims.sub.length > 255) { + throw new GoogleIdTokenError("missing_subject"); + } + if (typeof claims.email !== "string" || claims.email === "") { + throw new GoogleIdTokenError("email_missing"); + } + if (claims.email_verified !== true && claims.email_verified !== "true") { + throw new GoogleIdTokenError("email_not_verified"); + } + + const identity: GoogleIdentityClaims = { sub: claims.sub, email: claims.email }; + if (typeof claims.name === "string" && claims.name !== "") identity.name = claims.name; + if (typeof claims.picture === "string" && claims.picture !== "") identity.picture = claims.picture; + if (typeof claims.hd === "string" && claims.hd !== "") identity.hd = claims.hd; + return identity; +} + +/** + * The PKCE verifier and the nonce of one authorization request, derived from + * the request's state `jti` and Heimdall's signing key instead of stored. The + * state token travels through the browser and carries the `jti`, so whoever + * can read the redirect can read the `jti`; they cannot compute an Ed25519 + * signature over it. The signature is deterministic, so start and callback + * derive the same pair, and nothing is persisted between them. + */ +export function deriveOidcSecrets(stateJti: string, signingKey: KeyObject): { + codeVerifier: string; + codeChallenge: string; + nonce: string; +} { + const derive = (label: string): string => + createHash("sha256") + .update(sign(null, Buffer.from(`heimdall:oidc:${label}:${stateJti}`, "utf8"), signingKey)) + .digest("base64url"); + const codeVerifier = derive("pkce-verifier"); + return { + codeVerifier, + codeChallenge: createHash("sha256").update(codeVerifier, "ascii").digest("base64url"), + nonce: derive("nonce"), + }; +} diff --git a/src/index.ts b/src/index.ts index 8ee966b..0bc13c3 100644 --- a/src/index.ts +++ b/src/index.ts @@ -6,14 +6,16 @@ import { publishHeimdallOdinState } from "./odin-publication.js"; import { startHeimdallPrivateCommandPlane } from "./private-command-plane.js"; import type { CultNetOperationServer } from "cultnet-ts"; import { createHeimdallRuntimePulse, buildHeimdallHealthDetail, publishHeimdallVerseState } from "./verse-state.js"; -import { - buildPresenceStatement, - PublisherSequence, - readRuntimeBundleFacts, - type RuntimeBundleFacts, -} from "./runtime-presence.js"; +import { openPresenceAuthority } from "./runtime-presence.js"; const config = loadConfig(); +// Under Idunn the launch's presence keys, bundle facts and publisher sequence +// open here, before anything listens. A launch-contract fault throws, uncaught, +// and the process exits non-zero with no listener: Idunn fails Warming in +// seconds rather than waiting on a candidate that can never sign. +const presenceAuthority = config.idunnRuntimeBundlePath + ? await openPresenceAuthority(config) + : undefined; const app = await buildApp({ config }); const versePulseIntervalMs = 60_000; const healthPulseIntervalMs = 10_000; @@ -69,14 +71,6 @@ async function publishVerseState(): Promise { await publishHeimdallOdinState(config, pulse); } -/** - * Read once and keep: the bundle is Idunn's immutable record of this launch and - * cannot change while the process lives, so re-reading it every pulse would be - * work that can only ever return the same answer or fail. - */ -let runtimeBundleFacts: RuntimeBundleFacts | undefined; -const presenceSequence = new PublisherSequence(); - async function publishHealthState(): Promise { const pulse = createHeimdallRuntimePulse(config); @@ -94,30 +88,17 @@ async function publishHealthState(): Promise { ? buildHeimdallHealthDetail(config, pulse) : `Heimdall candidate warming; ${lease.reason}`; - if (!config.idunnRuntimeBundlePath) { + if (!presenceAuthority) { // Outside Idunn there is no launch to attest and nothing that admits the // statement; publishing is simply not part of that world. return; } - runtimeBundleFacts ??= await readRuntimeBundleFacts(config.idunnRuntimeBundlePath); - - const observedAtUnixMillis = Date.parse(pulse.updatedAt); - const presence = await buildPresenceStatement({ - bundle: runtimeBundleFacts, - state: lease.mayWrite ? "active" : "warming", - detail, - boundEndpoint: `http://${config.host}:${config.port}`, - // A warming candidate holds no lease and must not claim one; the contract - // refuses the pair, and Idunn needs the warming statement to promote it. - writeLeaseSha256: null, - observedAtUnixMillis, - publisherSequence: presenceSequence.next(observedAtUnixMillis), - providerHealthIdentityPath: config.providerHealthIdentityPath, - }); + const state = lease.mayWrite ? "active" : "warming"; + const presence = presenceAuthority.sign(state, detail, Date.parse(pulse.updatedAt)); await publishIdunnRudpHealth(config, { daemonId: config.daemonId, - state: lease.mayWrite ? "active" : "warming", + state, detail, observedAt: pulse.updatedAt, presence, diff --git a/src/managed-credential.ts b/src/managed-credential.ts index 32e9f51..fe60fc6 100644 --- a/src/managed-credential.ts +++ b/src/managed-credential.ts @@ -1,7 +1,7 @@ import { type HeimdallConfig } from "./config.js"; import { type Provider } from "./contracts.js"; import { type TokenCustody } from "./custody.js"; -import { type OAuthProviderRuntime, type OAuthRuntimeRegistry, ProviderResponseError } from "./oauth.js"; +import { type ExpiringTokenSet, type OAuthProviderRuntime, type OAuthRuntimeRegistry, ProviderResponseError } from "./oauth.js"; import { providerCatalog } from "./providers.js"; import { type HeimdallStore } from "./store/index.js"; import { type CredentialDecision, type StoredLinkedIdentity } from "./store/types.js"; @@ -16,6 +16,14 @@ export const MANAGED_CREDENTIAL_REFRESH_SKEW_MS = 5 * 60 * 1000; */ export const MANAGED_CREDENTIAL_REFRESH_TIMEOUT_MS = 10_000; +/** + * After a refresh attempt fails or times out, no process presents the row's + * refresh token again until this long has passed (the failure is recorded on + * the row, read under the lock). A provider that rotates may have consumed the + * token before the attempt was aborted, and presenting it again reads as theft. + */ +export const MANAGED_CREDENTIAL_REFRESH_BACKOFF_MS = 60 * 1000; + export interface ManagedCredentialContext { config: HeimdallConfig; store: HeimdallStore; @@ -55,6 +63,17 @@ function dueForRefresh(identity: StoredLinkedIdentity, runtime: OAuthProviderRun return Date.parse(identity.tokenExpiresAt) - now <= MANAGED_CREDENTIAL_REFRESH_SKEW_MS; } +/** + * Whether a failure stamped `failedAt` still holds this clock off. A stamp from + * a writer whose clock runs ahead reads as the future; one this far ahead or + * more is skew, not a fresh failure, so the wait stays bounded at twice the + * backoff. + */ +function withinBackoff(failedAt: string, now: number): boolean { + const elapsed = now - Date.parse(failedAt); + return elapsed > -MANAGED_CREDENTIAL_REFRESH_BACKOFF_MS && elapsed < MANAGED_CREDENTIAL_REFRESH_BACKOFF_MS; +} + function withoutTokens(identity: StoredLinkedIdentity): StoredLinkedIdentity { const { accessTokenEncrypted: _a, refreshTokenEncrypted: _r, tokenExpiresAt: _e, ...rest } = identity; return rest; @@ -68,10 +87,8 @@ function withoutTokens(identity: StoredLinkedIdentity): StoredLinkedIdentity { * attempt is in flight join it and receive its outcome, success or failure. * The entry lives exactly as long as the attempt: a later request retries. * - * Known residual risk (docs/service-contract.md): one presentation per - * process per burst, so N processes may present one token N times. The - * cross-process failed-refresh marker that would close it is - * joystick:follow_up:cross-process-failed-refresh-marker. + * Across processes the row owns it: a failed attempt leaves a marker on the + * row, and a process that takes the lock inside the backoff presents nothing. */ const refreshesInFlight = new WeakMap>>(); @@ -120,28 +137,8 @@ async function refreshUnderLock( const runtime = ctx.oauthRuntimes[provider]; let revocation: ManagedCredentialRevocationReason | undefined; - const decide = async (locked: StoredLinkedIdentity): Promise => { - if (!locked.accessTokenEncrypted || !dueForRefresh(locked, runtime, clock())) { - return { kind: "keep" }; - } - const updatedAt = new Date(clock()).toISOString(); - const refreshToken = ctx.tokenCustody.decrypt(locked.refreshTokenEncrypted!); - - let refreshed; - try { - refreshed = await runtime.refreshAccessToken!({ - config: ctx.config, - refreshToken, - signal: AbortSignal.timeout(ctx.timeoutMs ?? MANAGED_CREDENTIAL_REFRESH_TIMEOUT_MS), - }); - } catch (error) { - if (error instanceof ProviderResponseError && error.oauthError === "invalid_grant") { - revocation = "provider_revoked"; - return { kind: "revoke", updatedAt }; - } - throw new ManagedCredentialRefreshFailed(provider); - } - + let failed = false; + const rotation = (locked: StoredLinkedIdentity, refreshed: ExpiringTokenSet, updatedAt: string): CredentialDecision => { let refreshTokenEncrypted: string; if (refreshed.refreshToken) { refreshTokenEncrypted = ctx.tokenCustody.encrypt(refreshed.refreshToken); @@ -162,9 +159,47 @@ async function refreshUnderLock( tokenExpiresAt: refreshed.expiresAt, scopes: refreshed.scope.length ? refreshed.scope : locked.scopes, updatedAt, + consumedRefreshToken: providerCatalog[provider].rotatesRefreshTokens, }; }; + const decide = async (locked: StoredLinkedIdentity): Promise => { + if (!locked.accessTokenEncrypted || !dueForRefresh(locked, runtime, clock())) { + return { kind: "keep" }; + } + if (locked.refreshFailedAt && withinBackoff(locked.refreshFailedAt, clock())) { + failed = true; + return { kind: "keep" }; + } + const refreshToken = ctx.tokenCustody.decrypt(locked.refreshTokenEncrypted!); + + let refreshed; + try { + refreshed = await runtime.refreshAccessToken!({ + config: ctx.config, + refreshToken, + signal: AbortSignal.timeout(ctx.timeoutMs ?? MANAGED_CREDENTIAL_REFRESH_TIMEOUT_MS), + }); + } catch (error) { + if (error instanceof ProviderResponseError && error.oauthError === "invalid_grant") { + revocation = "provider_revoked"; + return { kind: "revoke", updatedAt: new Date(clock()).toISOString() }; + } + failed = true; + return { kind: "failed", failedAt: new Date(clock()).toISOString() }; + } + + // The provider has answered, and may have consumed the token: from here a throw must still leave the marker, which + // a rolled-back transaction would not (the store writes it on its own for a rotation it could not commit). + const answeredAt = new Date(clock()).toISOString(); + try { + return rotation(locked, refreshed, answeredAt); + } catch { + failed = true; + return { kind: "failed", failedAt: new Date(clock()).toISOString() }; + } + }; + const committed = await ctx.store.updateLinkedIdentityCredential(snapshot.id, decide); if (revocation) { await ctx.store.createAuditEvent({ @@ -174,6 +209,9 @@ async function refreshUnderLock( createdAt: new Date(clock()).toISOString(), }); } + if (failed) { + throw new ManagedCredentialRefreshFailed(provider); + } if (!committed) { return { kind: "revoked", identity: withoutTokens(snapshot) }; } diff --git a/src/oauth.ts b/src/oauth.ts index b6658e8..346726d 100644 --- a/src/oauth.ts +++ b/src/oauth.ts @@ -7,6 +7,7 @@ import { } from "./contracts.js"; import { type HeimdallConfig } from "./config.js"; import { entitlementFacts } from "./facts.js"; +import { verifyGoogleIdToken } from "./google-oidc.js"; import { providerCatalog } from "./providers.js"; import { type CreateEntitlementSnapshotInput } from "./store/types.js"; @@ -49,13 +50,22 @@ export interface OAuthProviderRuntime { config: HeimdallConfig; code: string; redirectUri: string; + /** PKCE verifier of an OIDC provider's request (RFC 7636). */ + codeVerifier?: string; }): Promise; refreshAccessToken?(options: { config: HeimdallConfig; refreshToken: string; signal?: AbortSignal; }): Promise; - resolveIdentity(options: { config: HeimdallConfig; accessToken: string }): Promise; + resolveIdentity(options: { + config: HeimdallConfig; + accessToken: string; + /** The exchange's answer: an OIDC provider's identity is its id_token, not a lookup with the access token. */ + tokenSet?: OAuthTokenSet; + /** The nonce this authorization request carried; an OIDC provider's id_token must echo it. */ + oidcNonce?: string; + }): Promise; evaluateEntitlements(options: { config: HeimdallConfig; callback: OAuthCallbackContext; @@ -144,7 +154,7 @@ function normalizeScopes(scope: string | string[] | undefined): string[] { } export type TokenGrant = - | { grant_type: "authorization_code"; code: string; redirect_uri: string } + | { grant_type: "authorization_code"; code: string; redirect_uri: string; code_verifier?: string } | { grant_type: "refresh_token"; refresh_token: string }; /** @@ -249,6 +259,7 @@ function sharedRuntimeExchange(provider: Provider): OAuthProviderRuntime["exchan grant_type: "authorization_code", code: options.code, redirect_uri: options.redirectUri, + ...(options.codeVerifier !== undefined ? { code_verifier: options.codeVerifier } : {}), }); // A rotating provider's refresh token is the only way back to the // credential: a grant that arrives without one would be stored as a row @@ -527,6 +538,31 @@ async function resolveYouTubeIdentity(options: { accessToken: string }): Promise return identity; } +async function resolveGoogleIdentity(options: { + config: HeimdallConfig; + tokenSet?: OAuthTokenSet; + oidcNonce?: string; +}): Promise { + const clientId = options.config.providers.google.clientId; + const idToken = options.tokenSet?.raw.id_token; + if (!clientId || typeof idToken !== "string" || !options.oidcNonce) { + throw new Error("Google sign-in needs a client id, an id_token and the request's nonce."); + } + const claims = await verifyGoogleIdToken(idToken, { clientId, nonce: options.oidcNonce }); + const identity: ResolvedIdentity = { + provider: "google", + providerUserId: claims.sub, + username: claims.email, + displayName: claims.name ?? claims.email, + primaryEmail: claims.email, + profile: { sub: claims.sub, email: claims.email, email_verified: true, name: claims.name, picture: claims.picture, hd: claims.hd }, + }; + if (claims.picture) { + identity.avatarUrl = claims.picture; + } + return identity; +} + async function resolveSpotifyIdentity(options: { accessToken: string }): Promise { const profile = await fetchJson<{ id?: string; @@ -945,6 +981,15 @@ const youtubeRuntime: OAuthProviderRuntime = { }, }; +const googleRuntime: OAuthProviderRuntime = { + exchangeAuthorizationCode: sharedRuntimeExchange("google"), + refreshAccessToken: sharedRuntimeRefresh("google"), + resolveIdentity: resolveGoogleIdentity, + async evaluateEntitlements() { + return { facts: [], snapshots: [] }; + }, +}; + const spotifyRuntime: OAuthProviderRuntime = { exchangeAuthorizationCode: sharedRuntimeExchange("spotify"), refreshAccessToken: sharedRuntimeRefresh("spotify"), @@ -986,5 +1031,6 @@ export function createOAuthRuntimeRegistry(): OAuthRuntimeRegistry { youtube: youtubeRuntime, spotify: spotifyRuntime, joystick: joystickRuntime, + google: googleRuntime, }; } diff --git a/src/private-command-plane.ts b/src/private-command-plane.ts index 6d3025b..8e9fb8d 100644 --- a/src/private-command-plane.ts +++ b/src/private-command-plane.ts @@ -305,7 +305,6 @@ async function beginAuth( throw new Error(String(startPayload.detail ?? startPayload.error ?? "OAuth start was denied.")); } const authorizationUrl = String(startPayload.authorizationUrl ?? ""); - const authorizationOrigin = new URL(authorizationUrl).origin; return { status: "accepted", payloadSchema: "heimdall.auth_begin_receipt.v1", @@ -316,7 +315,7 @@ async function beginAuth( expiresAt: attempt.expiresAt, navigation: { url: authorizationUrl, - allowedOrigins: [authorizationOrigin, new URL(config.publicBaseUrl).origin], + allowedOrigins: [new URL(config.publicBaseUrl).origin], }, }, }; diff --git a/src/provider-health-identity.ts b/src/provider-health-identity.ts index ad4903f..ca89f2c 100644 --- a/src/provider-health-identity.ts +++ b/src/provider-health-identity.ts @@ -7,7 +7,7 @@ import { sign, type KeyObject, } from "node:crypto"; -import { readFileSync } from "node:fs"; +import { closeSync, fstatSync, readSync } from "node:fs"; import { chmod, readFile } from "node:fs/promises"; import { SingleFileMessagePackBackingStore, type CultCacheEnvelope } from "@gamecult/cultcache-ts"; import { readPrivateStoreRecord } from "./idunn-store.js"; @@ -71,7 +71,7 @@ export async function openOrEnrollProviderHealthIdentity(path: string): Promise< if (existing.length !== 1) { throw new Error("Provider-health identity store must contain exactly one record."); } - return decodePrivateIdentity(existing[0]!.payload, await readMachineId()); + return decodePrivateIdentity(existing[0]!.payload, await readMachineId(), "bin"); } const PRESENCE_IDENTITY_FD_NAME = "gamecult-runtime-presence-identity"; @@ -124,7 +124,8 @@ export function passedDescriptor( */ export async function openProviderHealthIdentity( path: string, - env: NodeJS.ProcessEnv = process.env + env: NodeJS.ProcessEnv = process.env, + machineId: () => Promise = readMachineId ): Promise { const descriptor = passedDescriptor(PRESENCE_IDENTITY_FD_NAME, env); if (descriptor === undefined) { @@ -140,11 +141,33 @@ export async function openProviderHealthIdentity( } const payload = readPrivateStoreRecord( - readFileSync(descriptor), + readPassedDescriptor(descriptor), "Idunn runtime presence identity" ); - return decodePrivateIdentity(payload, await readMachineId()); + // The descriptor's writer is the Rust owner, whose key fields are integer arrays. + return decodePrivateIdentity(payload, await machineId(), "int-array"); +} + +/** + * Read a passed descriptor whole, from offset 0, and close it. A descriptor is + * a one-shot input: reading it again starts at the offset the last read left, + * which is the end, so the owner reads once at open and keeps what it decoded. + */ +export function readPassedDescriptor(descriptor: number): Buffer { + try { + const size = fstatSync(descriptor).size; + const bytes = Buffer.alloc(size); + let read = 0; + while (read < size) { + const count = readSync(descriptor, bytes, read, size - read, read); + if (count === 0) break; + read += count; + } + return bytes.subarray(0, read); + } finally { + closeSync(descriptor); + } } export function signProviderHealthPayload(identity: PrivateIdentity, payload: Uint8Array): Uint8Array { @@ -176,23 +199,58 @@ export function providerHealthPublicIdentity(identity: PrivateIdentity): { return { identityId: identity.identityId, publicKeyHex: Buffer.from(identity.publicKey).toString("hex") }; } -function decodePrivateIdentity(payload: Uint8Array, machineId: string): PrivateIdentity { +/** + * Which writer produced the record. The self-enrolling store this process + * writes keeps key fields as MessagePack bin; the Rust owner (cultnet-rs + * service_identity.rs) serialises a Vec without serde_bytes, so its key + * fields are arrays of integers. Each source is read in its own shape and the + * other is refused. + */ +type KeyShape = "bin" | "int-array"; + +function keyBytes(value: unknown, shape: KeyShape, field: string): Uint8Array { + const bytes = + shape === "bin" + ? value instanceof Uint8Array + ? value + : undefined + : Array.isArray(value) && + value.every((byte) => typeof byte === "number" && Number.isInteger(byte) && byte >= 0 && byte <= 255) + ? Uint8Array.from(value as number[]) + : undefined; + if (bytes === undefined || bytes.length !== 32) { + throw new Error( + `Provider-health identity key shape check failed: ${field} is not a 32-byte ${shape === "bin" ? "binary" : "integer-array"} key field.` + ); + } + return bytes; +} + +function decodePrivateIdentity(payload: Uint8Array, machineId: string, shape: KeyShape): PrivateIdentity { const value = decode(payload); if (!Array.isArray(value) || value.length !== 10) { - throw new Error("Provider-health identity payload is malformed."); + throw new Error("Provider-health identity schema check failed: payload is not a 10-field record."); } - const [schema, identityId, publicKey, protectedSeed, protector, binding, version] = value; - if ( - schema !== PRIVATE_SCHEMA || - typeof identityId !== "string" || - !(publicKey instanceof Uint8Array) || publicKey.length !== 32 || - !(protectedSeed instanceof Uint8Array) || protectedSeed.length !== 32 || - protector !== "linux_file_mode_machine_id_binding" || - binding !== protectorBinding(machineId) || - version !== "v1" || - identityId !== deriveIdentityId(publicKey) - ) { - throw new Error("Provider-health identity does not belong to this host or profile."); + const [schema, identityId, publicKeyField, protectedSeedField, protector, binding, version] = value; + if (schema !== PRIVATE_SCHEMA) { + throw new Error("Provider-health identity schema check failed: unexpected schema id."); + } + if (typeof identityId !== "string") { + throw new Error("Provider-health identity id check failed: id is not a string."); + } + const publicKey = keyBytes(publicKeyField, shape, "public key"); + const protectedSeed = keyBytes(protectedSeedField, shape, "protected seed"); + if (protector !== "linux_file_mode_machine_id_binding") { + throw new Error("Provider-health identity protector check failed: unexpected protector."); + } + if (binding !== protectorBinding(machineId)) { + throw new Error("Provider-health identity binding check failed: not bound to this host's machine id."); + } + if (version !== "v1") { + throw new Error("Provider-health identity version check failed: unexpected version."); + } + if (identityId !== deriveIdentityId(publicKey)) { + throw new Error("Provider-health identity id check failed: id does not derive from the public key."); } const seed = xorSeed(protectedSeed, binding); const privateKey = privateKeyFromSeed(seed); diff --git a/src/providers.ts b/src/providers.ts index 77eebf4..d66bd16 100644 --- a/src/providers.ts +++ b/src/providers.ts @@ -22,6 +22,24 @@ export interface ProviderDescriptor { clientIdEnv: string; clientSecretEnv: string; additionalAuthorizationParams?: Record; + /** + * The authorize parameters that make this provider ask the person again + * (a sign_in step-up). Absent means the provider has no such parameter, and + * a step-up start for it is refused rather than passed without the step. + */ + stepUpAuthorizationParams?: Record; + /** + * What a callback does with a (provider, subject) no account holds yet. + * `mints_account` is every provider's behaviour before Google: the first + * login makes an account. `requires_link` never mints: the identity + * attaches only to the account a verified link start bound + * (`initiator_account_id`), otherwise the callback refuses. Google is a second + * door into a person who already has an account, so a first Google login + * must not make a stranger of them. + */ + firstLogin: "mints_account" | "requires_link"; + /** OpenID Connect: the callback verifies an id_token and uses PKCE (S256) and a nonce. */ + oidc?: true; } export const providerCatalog: Record = { @@ -35,6 +53,7 @@ export const providerCatalog: Record = { defaultAccessTokenLifetimeSeconds: 3600, defaultScopes: ["identify", "guilds.members.read"], roles: ["identity", "entitlement"], + firstLogin: "mints_account", clientIdEnv: "GC_ACCESS_PROVIDER_DISCORD_CLIENT_ID", clientSecretEnv: "GC_ACCESS_PROVIDER_DISCORD_CLIENT_SECRET_FILE", }, @@ -48,6 +67,7 @@ export const providerCatalog: Record = { defaultAccessTokenLifetimeSeconds: 3600, defaultScopes: ["identity", "identity[email]"], roles: ["identity", "entitlement"], + firstLogin: "mints_account", clientIdEnv: "GC_ACCESS_PROVIDER_PATREON_CLIENT_ID", clientSecretEnv: "GC_ACCESS_PROVIDER_PATREON_CLIENT_SECRET_FILE", }, @@ -61,6 +81,7 @@ export const providerCatalog: Record = { defaultAccessTokenLifetimeSeconds: 3600, defaultScopes: ["read:user", "user:email"], roles: ["identity", "managed_credential"], + firstLogin: "mints_account", clientIdEnv: "GC_ACCESS_PROVIDER_GITHUB_CLIENT_ID", clientSecretEnv: "GC_ACCESS_PROVIDER_GITHUB_CLIENT_SECRET_FILE", }, @@ -74,8 +95,11 @@ export const providerCatalog: Record = { defaultAccessTokenLifetimeSeconds: 3600, defaultScopes: ["user:read:email"], roles: ["identity", "managed_credential"], + firstLogin: "mints_account", clientIdEnv: "GC_ACCESS_PROVIDER_TWITCH_CLIENT_ID", clientSecretEnv: "GC_ACCESS_PROVIDER_TWITCH_CLIENT_SECRET_FILE", + // Twitch force_verify re-shows the authorize page; it is not a password prompt. + stepUpAuthorizationParams: { force_verify: "true" }, }, youtube: { key: "youtube", @@ -92,6 +116,7 @@ export const providerCatalog: Record = { "https://www.googleapis.com/auth/youtube.readonly", ], roles: ["identity", "managed_credential"], + firstLogin: "mints_account", clientIdEnv: "GC_ACCESS_PROVIDER_YOUTUBE_CLIENT_ID", clientSecretEnv: "GC_ACCESS_PROVIDER_YOUTUBE_CLIENT_SECRET_FILE", additionalAuthorizationParams: { @@ -99,6 +124,8 @@ export const providerCatalog: Record = { include_granted_scopes: "true", prompt: "consent", }, + // login forces re-authentication; consent is kept because this provider always asks for it. + stepUpAuthorizationParams: { prompt: "login consent" }, }, spotify: { key: "spotify", @@ -114,9 +141,27 @@ export const providerCatalog: Record = { "user-modify-playback-state", ], roles: ["identity", "managed_credential"], + firstLogin: "mints_account", clientIdEnv: "GC_ACCESS_PROVIDER_SPOTIFY_CLIENT_ID", clientSecretEnv: "GC_ACCESS_PROVIDER_SPOTIFY_CLIENT_SECRET_FILE", }, + google: { + key: "google", + displayName: "Google", + authorizationEndpoint: "https://accounts.google.com/o/oauth2/v2/auth", + tokenEndpoint: "https://oauth2.googleapis.com/token", + tokenEndpointAuthMethod: "client_secret_post", + rotatesRefreshTokens: false, + defaultAccessTokenLifetimeSeconds: 3600, + defaultScopes: ["openid", "email", "profile"], + roles: ["identity"], + firstLogin: "requires_link", + oidc: true, + clientIdEnv: "GC_ACCESS_PROVIDER_GOOGLE_CLIENT_ID", + clientSecretEnv: "GC_ACCESS_PROVIDER_GOOGLE_CLIENT_SECRET_FILE", + additionalAuthorizationParams: { prompt: "select_account" }, + stepUpAuthorizationParams: { prompt: "login" }, + }, joystick: { key: "joystick", displayName: "Joystick", @@ -127,32 +172,59 @@ export const providerCatalog: Record = { defaultAccessTokenLifetimeSeconds: 3600, defaultScopes: ["identity:read", "stream:read", "chat:read", "followers:read", "subscribers:read"], roles: ["identity", "managed_credential"], + firstLogin: "mints_account", clientIdEnv: "GC_ACCESS_PROVIDER_JOYSTICK_CLIENT_ID", clientSecretEnv: "GC_ACCESS_PROVIDER_JOYSTICK_CLIENT_SECRET_FILE", }, }; +/** The scopes an authorization request carries: the caller's, or the provider's defaults. */ +export function authorizationScopes(provider: Provider, requested: readonly string[] | undefined): string[] { + return requested?.length ? [...requested] : [...providerCatalog[provider].defaultScopes]; +} + export function buildAuthorizationUrl(options: { provider: Provider; clientId: string; redirectUri: string; state: string; requestedScopes: string[] | undefined; + /** For an OIDC provider: the nonce, and the S256 challenge of the PKCE verifier. */ + oidc?: { nonce: string; codeChallenge: string }; + /** Ask the provider for a real re-authentication. Throws for a provider with no such parameter: never a silent pass. */ + stepUp?: boolean; }): string { const descriptor = providerCatalog[options.provider]; const url = new URL(descriptor.authorizationEndpoint); - const scopes = options.requestedScopes?.length ? options.requestedScopes : descriptor.defaultScopes; + const scopes = authorizationScopes(options.provider, options.requestedScopes); url.searchParams.set("client_id", options.clientId); url.searchParams.set("redirect_uri", options.redirectUri); url.searchParams.set("response_type", "code"); url.searchParams.set("scope", scopes.join(" ")); url.searchParams.set("state", options.state); + if (descriptor.oidc) { + if (!options.oidc) { + throw new Error(`${descriptor.displayName} is an OIDC provider: its authorization URL needs a nonce and a PKCE challenge.`); + } + url.searchParams.set("nonce", options.oidc.nonce); + url.searchParams.set("code_challenge", options.oidc.codeChallenge); + url.searchParams.set("code_challenge_method", "S256"); + } for (const [key, value] of Object.entries(descriptor.additionalAuthorizationParams ?? {})) { url.searchParams.set(key, value); } + if (options.stepUp) { + if (!descriptor.stepUpAuthorizationParams) { + throw new Error(`${descriptor.displayName} has no re-authentication parameter: a step-up cannot be honoured.`); + } + for (const [key, value] of Object.entries(descriptor.stepUpAuthorizationParams)) { + url.searchParams.set(key, value); + } + } + return url.toString(); } diff --git a/src/runtime-presence.ts b/src/runtime-presence.ts index e3ed0b1..3c1054b 100644 --- a/src/runtime-presence.ts +++ b/src/runtime-presence.ts @@ -19,7 +19,6 @@ import path from "node:path"; import { createHash, createPrivateKey, type KeyObject } from "node:crypto"; -import { readFileSync } from "node:fs"; import { decode } from "@msgpack/msgpack"; import { @@ -33,11 +32,14 @@ import { type RuntimePresenceState, } from "cultnet-ts"; +import type { HeimdallConfig } from "./config.js"; import { readIdunnStoreRecord } from "./idunn-store.js"; import { openProviderHealthIdentity, passedDescriptor, + readPassedDescriptor, signWithIdentity, + type PrivateIdentity, } from "./provider-health-identity.js"; const PKCS8_ED25519_SEED_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex"); @@ -176,29 +178,6 @@ export async function readRuntimeBundleFacts(bundlePath: string): Promise { - const env = inputs.env ?? process.env; - const activationKey = openActivationSigner(env); - if (activationKey === undefined) { - throw new Error( - "Idunn passed no runtime activation credential, so this process cannot prove it is the " + - "incarnation Idunn started", - ); - } - const identity = await openProviderHealthIdentity(inputs.providerHealthIdentityPath, env); +export function buildPresenceStatement(inputs: PresenceStatementInputs): PresenceStatement { + const { identity } = inputs; const presence: RuntimePresenceHealth = { target: inputs.bundle.target, @@ -284,7 +253,7 @@ export async function buildPresenceStatement( const proof = runtimePresenceProofPayload(presence); const signature = signWithIdentity(identity, runtimePresenceProviderSigningMessage(proof)); const activationSignature = signWithIdentity( - { ...identity, privateKey: activationKey }, + { ...identity, privateKey: inputs.activationKey }, runtimePresenceActivationSigningMessage(proof), ); @@ -293,3 +262,72 @@ export async function buildPresenceStatement( payload: encodeRuntimePresenceHealth(presence, signature, activationSignature), }; } + +export interface PresenceAuthority { + sign( + state: RuntimePresenceState, + detail: string, + observedAtUnixMillis: number, + ): PresenceStatement; +} + +/** + * Open everything this launch's presence statements stand on, once, before the + * process listens: Idunn's bundle facts, the activation seed and the presence + * identity (each descriptor is read whole and closed), and the one publisher + * sequence. It owns them for the life of the process; a pulse supplies only its + * state, detail and observation time. + * + * A launch-contract fault (a missing or malformed bundle, descriptor or + * identity) throws here, so the process exits before it accepts a request and + * Idunn fails Warming at once, instead of a listener that can never sign. + */ +export async function openPresenceAuthority( + config: Pick, + env: NodeJS.ProcessEnv = process.env, + machineId?: () => Promise, +): Promise { + if (!config.idunnRuntimeBundlePath) { + throw new Error("no Idunn runtime bundle path: presence has no launch to attest"); + } + const bundle = await readRuntimeBundleFacts(config.idunnRuntimeBundlePath); + + const activationDescriptor = passedDescriptor(IDUNN_RUNTIME_ACTIVATION_CREDENTIAL_NAME, env); + if (activationDescriptor === undefined) { + throw new Error( + "Idunn passed no runtime activation credential, so this process cannot prove it is the " + + "incarnation Idunn started", + ); + } + const seed = readPassedDescriptor(activationDescriptor); + if (seed.length !== 32) { + throw new Error("Idunn runtime activation credential is not a 32-byte seed"); + } + const activationKey = createPrivateKey({ + key: Buffer.concat([PKCS8_ED25519_SEED_PREFIX, seed]), + format: "der", + type: "pkcs8", + }); + + const identity = await openProviderHealthIdentity(config.providerHealthIdentityPath, env, machineId); + const boundEndpoint = `http://${config.host}:${config.port}`; + const sequence = new PublisherSequence(); + + return { + sign: (state, detail, observedAtUnixMillis) => + buildPresenceStatement({ + bundle, + identity, + activationKey, + state, + detail, + boundEndpoint, + // A warming candidate holds no lease and must not claim one; the + // contract refuses the pair, and Idunn needs the warming statement to + // promote it. + writeLeaseSha256: null, + observedAtUnixMillis, + publisherSequence: sequence.next(observedAtUnixMillis), + }), + }; +} diff --git a/src/store/identity-move.ts b/src/store/identity-move.ts new file mode 100644 index 0000000..7b80d43 --- /dev/null +++ b/src/store/identity-move.ts @@ -0,0 +1,88 @@ +import { type Provider } from "../contracts.js"; +import { type MoveIdentitiesInput, type StoredIdentityMove, type StoredLinkedIdentity } from "./types.js"; + +/** Everything a store read under its locks that the move rules decide on. */ +export interface MoveFacts { + /** The identity_moves row already holding input.moveId. */ + existing: StoredIdentityMove | null; + /** The move input.reversesMoveId names, and whether a reversal of it already exists. */ + forward: { move: StoredIdentityMove; reversed: boolean } | null; + /** Every proof session still carries its sid, app, account and access revision and has not expired. */ + proofSessionsLive: boolean; + sourceIdentities: readonly StoredLinkedIdentity[]; + destinationProviders: ReadonlySet; + /** An account with no identity and an unreversed move from it. */ + sourceIsAlias: boolean; + destinationIsAlias: boolean; +} + +export type MoveDecision = + | { kind: "replayed"; move: StoredIdentityMove } + | { kind: "refused"; result: { kind: "move_id_conflict" | "proof_lapsed" | "already_moved" | "identity_not_found" | "identity_not_proved" | "not_reversible" } | { kind: "provider_conflict"; provider: Provider } } + | { kind: "move"; identities: StoredLinkedIdentity[] }; + +/** + * The one statement of the move rules, in the order they are decided. Both + * stores gather MoveFacts under their locks and apply the answer, so memory + * and Postgres cannot disagree about what a move refuses. + */ +export function decideMove(input: MoveIdentitiesInput, facts: MoveFacts): MoveDecision { + const refuse = (kind: "move_id_conflict" | "proof_lapsed" | "already_moved" | "identity_not_found" | "identity_not_proved" | "not_reversible"): MoveDecision => ({ kind: "refused", result: { kind } }); + + const { existing } = facts; + if (existing) { + return existing.appSlug === input.appSlug && + existing.fromAccountId === input.fromAccountId && + existing.toAccountId === input.toAccountId && + existing.reversesMoveId === input.reversesMoveId + ? { kind: "replayed", move: existing } + : refuse("move_id_conflict"); + } + if (!facts.proofSessionsLive) return refuse("proof_lapsed"); + + const held = new Set(facts.sourceIdentities.map((identity) => identity.id)); + if (input.reversesMoveId !== undefined) { + const forward = facts.forward; + if ( + !forward || + forward.reversed || + forward.move.appSlug !== input.appSlug || + forward.move.reversesMoveId !== undefined || + forward.move.toAccountId !== input.fromAccountId || + forward.move.fromAccountId !== input.toAccountId || + !forward.move.moved.every((moved) => held.has(moved.id)) + ) { + return refuse("not_reversible"); + } + } else if (facts.sourceIsAlias || facts.destinationIsAlias) { + return refuse("already_moved"); + } + + let chosen: StoredLinkedIdentity[]; + if (input.identityIds === "all") { + chosen = [...facts.sourceIdentities]; + } else { + if (!input.identityIds.every((id) => held.has(id))) return refuse("identity_not_found"); + const wanted = new Set(input.identityIds); + chosen = facts.sourceIdentities.filter((identity) => wanted.has(identity.id)); + } + if (chosen.length === 0) return refuse("identity_not_found"); + + if (input.covers !== "account") { + const covered = new Set(input.covers); + if (!chosen.every((identity) => covered.has(identity.id))) return refuse("identity_not_proved"); + } + const clash = chosen.find((identity) => facts.destinationProviders.has(identity.provider)); + if (clash) return { kind: "refused", result: { kind: "provider_conflict", provider: clash.provider } }; + return { kind: "move", identities: chosen }; +} + +/** The history a move writes about what it carried. */ +export function movedRecord(identities: readonly StoredLinkedIdentity[]): StoredIdentityMove["moved"] { + return identities.map((identity) => ({ + id: identity.id, + provider: identity.provider, + providerUserId: identity.providerUserId, + credentialStripped: identity.accessTokenEncrypted !== undefined || identity.refreshTokenEncrypted !== undefined, + })); +} diff --git a/src/store/in-memory.ts b/src/store/in-memory.ts index 6a53dad..f12661d 100644 --- a/src/store/in-memory.ts +++ b/src/store/in-memory.ts @@ -3,7 +3,14 @@ import { type AppSlug, type LinkedIdentityInput, type Provider } from "../contra import { type CreateAccountInput, type CreateAuthAttemptInput, + type ClaimOAuthStateUseInput, + OAUTH_STATE_PRUNE_BATCH, + oauthStatePruneCutoffMs, type CreateAuthCompletionInput, + type CreateConsentReceiptInput, + type CreatePendingLinkInput, + type StoredConsentReceipt, + type StoredPendingLink, type CreateAuditEventInput, type CreateCapabilityGrantInput, type CredentialDecision, @@ -11,6 +18,7 @@ import { type CreateSessionInput, type CreatePrivateCommandReceiptInput, type HeimdallStore, + IdentityHeldElsewhereError, type StoredAccount, type StoredAuthAttempt, type StoredAuthCompletion, @@ -18,8 +26,13 @@ import { type StoredLinkedIdentity, type StoredSession, type StoredPrivateCommandReceipt, + type MoveIdentitiesInput, + type MoveResult, + type StoredIdentityMove, + type UnlinkResult, type UpsertLinkedIdentityInput, } from "./types.js"; +import { decideMove, movedRecord } from "./identity-move.js"; function clone(value: T): T { return JSON.parse(JSON.stringify(value)) as T; @@ -47,9 +60,14 @@ export class InMemoryStore implements HeimdallStore { private readonly authAttempts = new Map(); private readonly privateCommandReceipts = new Map(); private readonly authCompletions = new Map(); + private readonly pendingLinks = new Map(); private readonly authCompletionsByAttempt = new Map(); + /** `${jti}:${phase}` -> the state's expiresAt. */ + private readonly oauthStateUses = new Map(); private readonly entitlementSnapshots = new Map(); private readonly auditEvents = new Map(); + private readonly consentReceipts: StoredConsentReceipt[] = []; + private readonly identityMoves = new Map(); async ensureSchema(): Promise { return; @@ -137,6 +155,9 @@ export class InMemoryStore implements HeimdallStore { const existing = [...this.linkedIdentities.values()].find( (identity) => identity.provider === input.provider && identity.providerUserId === input.providerUserId ); + if (existing && existing.accountId !== input.accountId) { + throw new IdentityHeldElsewhereError(); + } const id = existing?.id ?? input.id ?? randomUUID(); const linkedIdentity: StoredLinkedIdentity = { id, @@ -177,6 +198,87 @@ export class InMemoryStore implements HeimdallStore { return clone(linkedIdentity); } + async unlinkLinkedIdentity(accountId: string, identityId: string): Promise { + const target = this.linkedIdentities.get(identityId); + if (!target || target.accountId !== accountId) return { kind: "not_found" }; + const held = [...this.linkedIdentities.values()].filter((identity) => identity.accountId === accountId).length; + if (held <= 1) return { kind: "last_identity" }; + this.linkedIdentities.delete(identityId); + return { kind: "unlinked", identity: clone(target) }; + } + + /** No await between the reads and the writes: the event loop is the lock. */ + async moveIdentities(input: MoveIdentitiesInput): Promise { + const at = Date.parse(input.at); + const forwardMove = input.reversesMoveId !== undefined ? this.identityMoves.get(input.reversesMoveId) : undefined; + const sourceIdentities = [...this.linkedIdentities.values()].filter((identity) => identity.accountId === input.fromAccountId); + const destinationIdentities = [...this.linkedIdentities.values()].filter((identity) => identity.accountId === input.toAccountId); + const decision = decideMove(input, { + existing: this.identityMoves.get(input.moveId) ?? null, + forward: forwardMove ? { move: forwardMove, reversed: this.isReversed(forwardMove.id) } : null, + proofSessionsLive: input.proofSessions.every((proof) => { + const session = this.sessions.get(proof.sessionId); + return ( + session !== undefined && + session.appSlug === proof.appSlug && + session.accountId === proof.accountId && + session.accessRevision === proof.accessRevision && + Date.parse(session.expiresAt) > at + ); + }), + sourceIdentities: clone(sourceIdentities), + destinationProviders: new Set(destinationIdentities.map((identity) => identity.provider)), + sourceIsAlias: sourceIdentities.length === 0 && this.hasUnreversedMoveFrom(input.fromAccountId), + destinationIsAlias: destinationIdentities.length === 0 && this.hasUnreversedMoveFrom(input.toAccountId), + }); + if (decision.kind === "replayed") return { kind: "replayed", move: clone(decision.move) }; + if (decision.kind === "refused") return decision.result; + + for (const identity of decision.identities) { + const row = this.linkedIdentities.get(identity.id)!; + row.accountId = input.toAccountId; + row.updatedAt = input.at; + delete row.accessTokenEncrypted; + delete row.refreshTokenEncrypted; + delete row.tokenExpiresAt; + delete row.refreshFailedAt; + } + for (const session of this.sessions.values()) { + if (session.accountId === input.fromAccountId && Date.parse(session.expiresAt) > at) { + session.expiresAt = input.at; + session.lastSeenAt = input.at; + session.accessRevision += 1; + } + } + for (const row of [...this.pendingLinks.values(), ...this.authCompletions.values()]) { + if (row.accountId === input.fromAccountId && !row.consumedAt && Date.parse(row.expiresAt) > at) row.expiresAt = input.at; + } + const move: StoredIdentityMove = { + id: input.moveId, + appSlug: input.appSlug, + fromAccountId: input.fromAccountId, + toAccountId: input.toAccountId, + ...(input.reversesMoveId !== undefined ? { reversesMoveId: input.reversesMoveId } : {}), + moved: movedRecord(decision.identities), + proof: clone(input.proof), + createdAt: input.at, + }; + this.identityMoves.set(move.id, clone(move)); + return { kind: "moved", move }; + } + + async findIdentityMove(moveId: string): Promise { + return clone(this.identityMoves.get(moveId) ?? null); + } + + private isReversed(moveId: string): boolean { + return [...this.identityMoves.values()].some((move) => move.reversesMoveId === moveId); + } + + private hasUnreversedMoveFrom(accountId: string): boolean { + return [...this.identityMoves.values()].some((move) => move.fromAccountId === accountId && !this.isReversed(move.id)); + } + async updateLinkedIdentityCredential( id: string, decide: (locked: StoredLinkedIdentity) => Promise, @@ -191,7 +293,13 @@ export class InMemoryStore implements HeimdallStore { if (decision.kind === "keep") { return clone(current); } + if (decision.kind === "failed") { + const marked: StoredLinkedIdentity = { ...current, refreshFailedAt: decision.failedAt }; + this.linkedIdentities.set(id, clone(marked)); + return clone(marked); + } const next: StoredLinkedIdentity = { ...current, updatedAt: decision.updatedAt }; + delete next.refreshFailedAt; delete next.accessTokenEncrypted; delete next.refreshTokenEncrypted; delete next.tokenExpiresAt; @@ -390,6 +498,7 @@ export class InMemoryStore implements HeimdallStore { accountId: input.accountId, sessionId: input.sessionId, returnTo: input.returnTo, + ...(input.targetId ? { targetId: input.targetId } : {}), createdAt: input.createdAt, expiresAt: input.expiresAt, payloadJson: clone(input.payloadJson), @@ -402,6 +511,11 @@ export class InMemoryStore implements HeimdallStore { return clone(completion); } + async findAuthCompletion(appSlug: AppSlug, code: string): Promise { + const completion = this.authCompletions.get(code); + return completion && completion.appSlug === appSlug ? clone(completion) : null; + } + async consumeAuthCompletion(appSlug: AppSlug, code: string, at: string): Promise { const completion = this.authCompletions.get(code); if (!completion) { @@ -424,6 +538,42 @@ export class InMemoryStore implements HeimdallStore { return this.consumeAuthCompletion(appSlug, code, at); } + async createPendingLink(input: CreatePendingLinkInput): Promise { + const link: StoredPendingLink = { id: randomUUID(), ...clone(input) }; + this.pendingLinks.set(link.id, clone(link)); + return clone(link); + } + + async consumePendingLink(appSlug: AppSlug, id: string, accountId: string, at: string): Promise { + const link = this.pendingLinks.get(id); + if (!link || link.appSlug !== appSlug || link.accountId !== accountId || link.expiresAt <= at || link.consumedAt) { + return null; + } + link.consumedAt = at; + return clone(link); + } + + async claimOAuthStateUse(input: ClaimOAuthStateUseInput): Promise { + const key = `${input.jti}:${input.phase}`; + if (this.oauthStateUses.has(key)) { + return false; + } + this.oauthStateUses.set(key, input.expiresAt); + // A state is still accepted until its exp + skew; a record is kept a margin longer, and each + // successful claim removes at most a batch of what is past that (oauthStatePruneCutoffMs), as + // the Postgres store does. + const cutoff = oauthStatePruneCutoffMs(Date.parse(input.usedAt)); + let pruned = 0; + for (const [oldKey, expiresAt] of this.oauthStateUses) { + if (pruned >= OAUTH_STATE_PRUNE_BATCH) break; + if (Date.parse(expiresAt) <= cutoff) { + this.oauthStateUses.delete(oldKey); + pruned += 1; + } + } + return true; + } + async upsertEntitlementSnapshot(input: CreateEntitlementSnapshotInput): Promise { const key = `${input.accountId}:${input.provider}:${input.scope}`; this.entitlementSnapshots.set(key, clone(input)); @@ -436,4 +586,22 @@ export class InMemoryStore implements HeimdallStore { }); this.auditEvents.set(event.id ?? randomUUID(), event); } + + async createConsentReceipt(input: CreateConsentReceiptInput): Promise<{ receipt: StoredConsentReceipt; created: boolean }> { + if (input.kind === "revocation") { + // The table's foreign key: a revocation names a receipt of the same account. + if (!this.consentReceipts.some((r) => r.id === input.revokesReceiptId && r.accountId === input.accountId)) { + throw new Error("A revocation must name a receipt of its own account."); + } + const existing = this.consentReceipts.find((r) => r.kind === "revocation" && r.revokesReceiptId === input.revokesReceiptId); + if (existing) return { receipt: clone(existing), created: false }; + } + const receipt = { id: randomUUID(), ...clone(input) } as StoredConsentReceipt; + this.consentReceipts.push(clone(receipt)); + return { receipt: clone(receipt), created: true }; + } + + async listConsentReceipts(accountId: string): Promise { + return this.consentReceipts.filter((receipt) => receipt.accountId === accountId).map(clone); + } } diff --git a/src/store/postgres.ts b/src/store/postgres.ts index 487f375..f0da059 100644 --- a/src/store/postgres.ts +++ b/src/store/postgres.ts @@ -1,11 +1,17 @@ import { randomUUID } from "node:crypto"; import { Pool, type PoolClient, type QueryResultRow } from "pg"; import { type AppSlug, type HeimdallAuthAttemptStatus, type LinkedIdentityInput, type Provider } from "../contracts.js"; +import { decideMove, movedRecord, type MoveFacts } from "./identity-move.js"; import { CREATE_SCHEMA_SQL, REQUIRED_COLUMNS, REQUIRED_KEYS, REQUIRED_TABLES } from "./schema.js"; import { type CreateAccountInput, type CreateAuthAttemptInput, + type ClaimOAuthStateUseInput, type CreateAuthCompletionInput, + type CreateConsentReceiptInput, + type CreatePendingLinkInput, + type StoredConsentReceipt, + type StoredPendingLink, type CreateAuditEventInput, type CreateCapabilityGrantInput, type CredentialDecision, @@ -13,6 +19,12 @@ import { type CreateSessionInput, type CreatePrivateCommandReceiptInput, type HeimdallStore, + IdentityHeldElsewhereError, + type MoveIdentitiesInput, + type MoveResult, + type StoredIdentityMove, + OAUTH_STATE_PRUNE_BATCH, + oauthStatePruneCutoffMs, type StoredAccount, type StoredAuthAttempt, type StoredAuthCompletion, @@ -20,6 +32,7 @@ import { type StoredLinkedIdentity, type StoredSession, type StoredPrivateCommandReceipt, + type UnlinkResult, type UpsertLinkedIdentityInput, } from "./types.js"; @@ -42,6 +55,7 @@ interface LinkedIdentityRow extends QueryResultRow { access_token_encrypted: string | null; refresh_token_encrypted: string | null; token_expires_at: string | null; + refresh_failed_at: string | null; scopes: string; profile_json: Record; created_at: string; @@ -82,12 +96,26 @@ interface AuthCompletionRow extends QueryResultRow { account_id: string; session_id: string; return_to: string; + target_id: string | null; payload_json: Record; created_at: string | Date; expires_at: string | Date; consumed_at: string | Date | null; } +interface PendingLinkRow extends QueryResultRow { + id: string; + app_slug: AppSlug; + account_id: string; + provider: Provider; + provider_user_id: string; + identity_json: StoredPendingLink["identity"]; + return_to: string; + created_at: string | Date; + expires_at: string | Date; + consumed_at: string | Date | null; +} + interface AuthAttemptRow extends QueryResultRow { handle: string; app_slug: AppSlug; @@ -151,6 +179,42 @@ function mapAccountRow(row: AccountRow): StoredAccount { return account; } +interface IdentityMoveRow extends QueryResultRow { + id: string; + app_slug: AppSlug; + from_account_id: string; + to_account_id: string; + reverses_move_id: string | null; + moved_json: StoredIdentityMove["moved"]; + proof_json: StoredIdentityMove["proof"]; + created_at: string; +} + +async function selectIdentityMove(db: Pick, moveId: string): Promise { + const result = await db.query("SELECT * FROM identity_moves WHERE id = $1", [moveId]); + const row = result.rows[0]; + if (!row) return null; + return { + id: row.id, + appSlug: row.app_slug, + fromAccountId: row.from_account_id, + toAccountId: row.to_account_id, + ...(row.reverses_move_id ? { reversesMoveId: row.reverses_move_id } : {}), + moved: row.moved_json, + proof: row.proof_json, + createdAt: new Date(row.created_at).toISOString(), + }; +} + +/** A move from this account that no reversal names: the account's identities went elsewhere. */ +async function hasUnreversedMoveFrom(db: Pick, accountId: string): Promise { + const result = await db.query( + "SELECT 1 FROM identity_moves m WHERE m.from_account_id = $1 AND NOT EXISTS (SELECT 1 FROM identity_moves r WHERE r.reverses_move_id = m.id) LIMIT 1", + [accountId] + ); + return (result.rowCount ?? 0) > 0; +} + function mapLinkedIdentityRow(row: LinkedIdentityRow): StoredLinkedIdentity { const identity: StoredLinkedIdentity = { id: row.id, @@ -188,6 +252,10 @@ function mapLinkedIdentityRow(row: LinkedIdentityRow): StoredLinkedIdentity { identity.tokenExpiresAt = new Date(row.token_expires_at).toISOString(); } + if (row.refresh_failed_at) { + identity.refreshFailedAt = new Date(row.refresh_failed_at).toISOString(); + } + return identity; } @@ -231,6 +299,59 @@ function mapSessionRow(row: SessionRow): StoredSession { }; } +interface ConsentReceiptRow { + id: string; + kind: "grant" | "revocation"; + account_id: string; + app_slug: AppSlug; + provider: Provider; + created_at: Date | string; + scopes_asked: string | null; + scopes_granted: string | null; + consent_page_digest: string | null; + consent_text: string | null; + revokes_receipt_id: string | null; +} + +function mapConsentReceiptRow(row: ConsentReceiptRow): StoredConsentReceipt { + const base = { + id: row.id, + accountId: row.account_id, + appSlug: row.app_slug, + provider: row.provider, + createdAt: normalizeTimestamp(row.created_at), + }; + if (row.kind === "revocation") { + return { ...base, kind: "revocation", revokesReceiptId: row.revokes_receipt_id ?? "" }; + } + return { + ...base, + kind: "grant", + scopesAsked: parseScopes(row.scopes_asked ?? ""), + scopesGranted: parseScopes(row.scopes_granted ?? ""), + consentPageDigest: row.consent_page_digest ?? "", + consentText: row.consent_text ?? "", + }; +} + +function mapPendingLinkRow(row: PendingLinkRow): StoredPendingLink { + const link: StoredPendingLink = { + id: row.id, + appSlug: row.app_slug, + accountId: row.account_id, + provider: row.provider, + providerUserId: row.provider_user_id, + identity: row.identity_json, + returnTo: row.return_to, + createdAt: normalizeTimestamp(row.created_at), + expiresAt: normalizeTimestamp(row.expires_at), + }; + if (row.consumed_at) { + link.consumedAt = normalizeTimestamp(row.consumed_at); + } + return link; +} + function mapAuthCompletionRow(row: AuthCompletionRow): StoredAuthCompletion { const completion: StoredAuthCompletion = { code: row.code, @@ -249,6 +370,10 @@ function mapAuthCompletionRow(row: AuthCompletionRow): StoredAuthCompletion { completion.attemptId = row.attempt_id; } + if (row.target_id) { + completion.targetId = row.target_id; + } + if (row.consumed_at) { completion.consumedAt = normalizeTimestamp(row.consumed_at); } @@ -368,18 +493,28 @@ export function samePredicate(declared: string, actual: string, keyColumns: stri /** * What the store's statements do to each table, and so the privileges its * database role needs: it reads what it returns or looks up, inserts what it - * creates, updates what it changes or upserts, and deletes nothing. + * creates, updates what it changes or upserts, and deletes two things: + * expired oauth_state_uses rows (which needs SELECT for its WHERE), and the one + * linked_identities row an unlink names (unlinkLinkedIdentity, the only + * delete there; it needs SELECT for its WHERE and for the account's count). + * identity_moves is append-only. moveIdentities is the statement that updates + * linked_identities.account_id (its one writer), sessions, pending_links and + * auth_completions, all of which already hold UPDATE. * audit_events is written and never read back. */ -export const STORE_TABLE_PRIVILEGES: Readonly> = { +export const STORE_TABLE_PRIVILEGES: Readonly> = { accounts: ["SELECT", "INSERT", "UPDATE"], - linked_identities: ["SELECT", "INSERT", "UPDATE"], + linked_identities: ["SELECT", "INSERT", "UPDATE", "DELETE"], sessions: ["SELECT", "INSERT", "UPDATE"], auth_attempts: ["SELECT", "INSERT", "UPDATE"], private_command_receipts: ["SELECT", "INSERT"], auth_completions: ["SELECT", "INSERT", "UPDATE"], + pending_links: ["SELECT", "INSERT", "UPDATE"], + oauth_state_uses: ["SELECT", "INSERT", "DELETE"], capability_grants: ["SELECT", "INSERT"], entitlement_snapshots: ["SELECT", "INSERT", "UPDATE"], + consent_receipts: ["SELECT", "INSERT"], + identity_moves: ["SELECT", "INSERT"], audit_events: ["INSERT"], }; @@ -514,7 +649,9 @@ export async function checkSchemaRequirements(pool: Pick, require SELECT 1 FROM unnest($2::text[], $3::text[]) AS used(table_name, column_name) JOIN pg_attribute a ON a.attrelid = to_regclass(used.table_name) AND a.attname = used.column_name AND NOT a.attisdropped WHERE used.table_name = required.table_name - AND NOT has_column_privilege(a.attrelid, a.attnum, required.privilege) + AND NOT CASE WHEN required.privilege = 'DELETE' + THEN has_table_privilege(a.attrelid, 'DELETE') -- DELETE is a row privilege, never held per column + ELSE has_column_privilege(a.attrelid, a.attnum, required.privilege) END ) `, [ @@ -691,16 +828,17 @@ export class PostgresStore implements HeimdallStore { ) ON CONFLICT (provider, provider_user_id) DO UPDATE SET - account_id = EXCLUDED.account_id, username = EXCLUDED.username, display_name = EXCLUDED.display_name, primary_email = EXCLUDED.primary_email, access_token_encrypted = EXCLUDED.access_token_encrypted, refresh_token_encrypted = EXCLUDED.refresh_token_encrypted, token_expires_at = EXCLUDED.token_expires_at, + refresh_failed_at = NULL, scopes = EXCLUDED.scopes, profile_json = EXCLUDED.profile_json, updated_at = EXCLUDED.updated_at + WHERE linked_identities.account_id = EXCLUDED.account_id RETURNING * `, [ @@ -721,7 +859,144 @@ export class PostgresStore implements HeimdallStore { ] ); - return mapLinkedIdentityRow(expectRow(result.rows[0], "upsertLinkedIdentity")); + // The conflict arm updates only the holder's own row; another account's yields no row. + if (!result.rows[0]) throw new IdentityHeldElsewhereError(); + return mapLinkedIdentityRow(result.rows[0]); + } + + async unlinkLinkedIdentity(accountId: string, identityId: string): Promise { + const client = await this.pool.connect(); + try { + await client.query("BEGIN"); + try { + // The account row serialises its unlinks: two clients racing for the last two identities queue here. + await client.query("SELECT id FROM accounts WHERE id = $1 FOR UPDATE", [accountId]); + const held = await client.query<{ n: string | number }>( + "SELECT count(*) AS n FROM linked_identities WHERE account_id = $1", + [accountId] + ); + let result: UnlinkResult; + if (Number(held.rows[0]?.n ?? 0) <= 1) { + const mine = await client.query("SELECT 1 FROM linked_identities WHERE id = $1 AND account_id = $2", [identityId, accountId]); + result = mine.rowCount ? { kind: "last_identity" } : { kind: "not_found" }; + } else { + const deleted = await client.query( + "DELETE FROM linked_identities WHERE id = $2 AND account_id = $1 RETURNING *", + [accountId, identityId] + ); + result = deleted.rows[0] ? { kind: "unlinked", identity: mapLinkedIdentityRow(deleted.rows[0]) } : { kind: "not_found" }; + } + await client.query("COMMIT"); + return result; + } catch (error) { + await client.query("ROLLBACK"); + throw error; + } + } finally { + client.release(); + } + } + + async moveIdentities(input: MoveIdentitiesInput): Promise { + const client = await this.pool.connect(); + try { + await client.query("BEGIN"); + try { + // Both accounts, one statement each in id order, before anything is read: opposite moves queue here + // instead of deadlocking. The order is the code's own, not whatever order a plan locks a set in. + for (const id of [input.fromAccountId, input.toAccountId].sort()) { + await client.query("SELECT id FROM accounts WHERE id = $1 FOR UPDATE", [id]); + } + const existing = await selectIdentityMove(client, input.moveId); + let forward: MoveFacts["forward"] = null; + if (input.reversesMoveId !== undefined) { + const forwardMove = await selectIdentityMove(client, input.reversesMoveId); + const reversal = forwardMove ? await client.query("SELECT 1 FROM identity_moves WHERE reverses_move_id = $1", [forwardMove.id]) : null; + forward = forwardMove ? { move: forwardMove, reversed: (reversal?.rowCount ?? 0) > 0 } : null; + } + let proofSessionsLive = true; + for (const proof of input.proofSessions) { + const live = await client.query( + "SELECT 1 FROM sessions WHERE id = $1 AND app_slug = $2 AND account_id = $3 AND access_revision = $4 AND expires_at > $5", + [proof.sessionId, proof.appSlug, proof.accountId, proof.accessRevision, input.at] + ); + if (!live.rowCount) proofSessionsLive = false; + } + const source = await client.query( + "SELECT * FROM linked_identities WHERE account_id = $1 ORDER BY created_at ASC, id ASC FOR UPDATE", + [input.fromAccountId] + ); + const destination = await client.query<{ provider: Provider }>("SELECT provider FROM linked_identities WHERE account_id = $1", [input.toAccountId]); + const sourceIdentities = source.rows.map(mapLinkedIdentityRow); + const decision = decideMove(input, { + existing, + forward, + proofSessionsLive, + sourceIdentities, + destinationProviders: new Set(destination.rows.map((row) => row.provider)), + sourceIsAlias: sourceIdentities.length === 0 && (await hasUnreversedMoveFrom(client, input.fromAccountId)), + destinationIsAlias: destination.rowCount === 0 && (await hasUnreversedMoveFrom(client, input.toAccountId)), + }); + if (decision.kind !== "move") { + await client.query("ROLLBACK"); + return decision.kind === "replayed" ? { kind: "replayed", move: decision.move } : decision.result; + } + const ids = decision.identities.map((identity) => identity.id); + await client.query( + `UPDATE linked_identities + SET account_id = $2, access_token_encrypted = NULL, refresh_token_encrypted = NULL, + token_expires_at = NULL, refresh_failed_at = NULL, updated_at = $3 + WHERE id = ANY($1) AND account_id = $4`, + [ids, input.toAccountId, input.at, input.fromAccountId] + ); + await client.query( + "UPDATE sessions SET expires_at = $2, last_seen_at = $2, access_revision = access_revision + 1 WHERE account_id = $1 AND expires_at > $2", + [input.fromAccountId, input.at] + ); + for (const table of ["pending_links", "auth_completions"]) { + await client.query( + `UPDATE ${table} SET expires_at = $2 WHERE account_id = $1 AND consumed_at IS NULL AND expires_at > $2`, + [input.fromAccountId, input.at] + ); + } + const move: StoredIdentityMove = { + id: input.moveId, + appSlug: input.appSlug, + fromAccountId: input.fromAccountId, + toAccountId: input.toAccountId, + ...(input.reversesMoveId !== undefined ? { reversesMoveId: input.reversesMoveId } : {}), + moved: movedRecord(decision.identities), + proof: input.proof, + createdAt: input.at, + }; + try { + await client.query( + `INSERT INTO identity_moves (id, app_slug, from_account_id, to_account_id, reverses_move_id, moved_json, proof_json, created_at) + VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`, + [move.id, move.appSlug, move.fromAccountId, move.toAccountId, nullable(move.reversesMoveId), JSON.stringify(move.moved), JSON.stringify(move.proof), move.createdAt] + ); + } catch (error) { + // The row is the arbiter of a race the locks did not serialise (a reversal of the same move through another pool). + if ((error as { code?: string }).code !== "23505") throw error; + await client.query("ROLLBACK"); + const winner = await this.findIdentityMove(input.moveId); + if (!winner) return { kind: "not_reversible" }; + const again = decideMove(input, { existing: winner, forward: null, proofSessionsLive: true, sourceIdentities: [], destinationProviders: new Set(), sourceIsAlias: false, destinationIsAlias: false }); + return again.kind === "replayed" ? { kind: "replayed", move: again.move } : { kind: "move_id_conflict" }; + } + await client.query("COMMIT"); + return { kind: "moved", move }; + } catch (error) { + await client.query("ROLLBACK").catch(() => undefined); + throw error; + } + } finally { + client.release(); + } + } + + async findIdentityMove(moveId: string): Promise { + return selectIdentityMove(this.pool, moveId); } async updateLinkedIdentityCredential( @@ -731,6 +1006,7 @@ export class PostgresStore implements HeimdallStore { const client = await this.pool.connect(); try { await client.query("BEGIN"); + let decision: CredentialDecision | undefined; try { const locked = await client.query( "SELECT * FROM linked_identities WHERE id = $1 FOR UPDATE", @@ -741,9 +1017,15 @@ export class PostgresStore implements HeimdallStore { return null; } const row = mapLinkedIdentityRow(expectRow(locked.rows[0], "updateLinkedIdentityCredential")); - const decision = await decide(row); + decision = await decide(row); let committed = row; - if (decision.kind !== "keep") { + if (decision.kind === "failed") { + const marked = await client.query( + "UPDATE linked_identities SET refresh_failed_at = $2 WHERE id = $1 RETURNING *", + [id, decision.failedAt] + ); + committed = mapLinkedIdentityRow(expectRow(marked.rows[0], "updateLinkedIdentityCredential")); + } else if (decision.kind !== "keep") { const rotated = decision.kind === "rotate" ? decision : undefined; const written = await client.query( ` @@ -751,6 +1033,7 @@ export class PostgresStore implements HeimdallStore { SET access_token_encrypted = $2, refresh_token_encrypted = $3, token_expires_at = $4, + refresh_failed_at = NULL, scopes = $5, updated_at = $6 WHERE id = $1 @@ -771,6 +1054,21 @@ export class PostgresStore implements HeimdallStore { return committed; } catch (error) { await client.query("ROLLBACK"); + if (decision?.kind === "rotate" || decision?.kind === "revoke") { + // The provider answered, and what its answer called for could not be committed: the rollback took the answer + // with it. In a transaction of its own, leave the marker, so no caller presents the token within the backoff. + // Blank the token only when it is spent: a revoke, or a provider that rotates (Joystick) and consumed it. + // A provider that keeps its refresh token valid (Twitch) keeps it, so a transient write failure does not + // strand the link. Best effort: if this write fails too, the original error is the one that matters, and the + // residual is named in docs/service-contract.md. + const spent = decision.kind === "revoke" || decision.consumedRefreshToken; + await client + .query( + `UPDATE linked_identities SET ${spent ? "refresh_token_encrypted = NULL, " : ""}refresh_failed_at = $2 WHERE id = $1`, + [id, decision.updatedAt] + ) + .catch(() => undefined); + } throw error; } } finally { @@ -1004,9 +1302,9 @@ export class PostgresStore implements HeimdallStore { ` INSERT INTO auth_completions ( code, attempt_id, app_slug, provider, mode, account_id, session_id, - return_to, payload_json, created_at, expires_at + return_to, target_id, payload_json, created_at, expires_at ) - VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11) + VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12) RETURNING * `, [ @@ -1018,6 +1316,7 @@ export class PostgresStore implements HeimdallStore { input.accountId, input.sessionId, input.returnTo, + input.targetId ?? null, JSON.stringify(input.payloadJson), input.createdAt, input.expiresAt, @@ -1027,6 +1326,14 @@ export class PostgresStore implements HeimdallStore { return mapAuthCompletionRow(expectRow(result.rows[0], "createAuthCompletion")); } + async findAuthCompletion(appSlug: AppSlug, code: string): Promise { + const result = await this.pool.query( + "SELECT * FROM auth_completions WHERE code = $1 AND app_slug = $2", + [code, appSlug] + ); + return result.rowCount ? mapAuthCompletionRow(expectRow(result.rows[0], "findAuthCompletion")) : null; + } + async consumeAuthCompletion(appSlug: AppSlug, code: string, at: string): Promise { const result = await this.pool.query( ` @@ -1061,6 +1368,78 @@ export class PostgresStore implements HeimdallStore { return result.rowCount ? mapAuthCompletionRow(expectRow(result.rows[0], "consumeAuthCompletionByAttempt")) : null; } + async createPendingLink(input: CreatePendingLinkInput): Promise { + const result = await this.pool.query( + ` + INSERT INTO pending_links ( + id, app_slug, account_id, provider, provider_user_id, identity_json, + return_to, created_at, expires_at + ) + VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9) + RETURNING * + `, + [ + randomUUID(), + input.appSlug, + input.accountId, + input.provider, + input.providerUserId, + JSON.stringify(input.identity), + input.returnTo, + input.createdAt, + input.expiresAt, + ] + ); + return mapPendingLinkRow(expectRow(result.rows[0], "createPendingLink")); + } + + async consumePendingLink(appSlug: AppSlug, id: string, accountId: string, at: string): Promise { + const result = await this.pool.query( + ` + UPDATE pending_links + SET consumed_at = $4 + WHERE id = $1 + AND app_slug = $2 + AND account_id = $3 + AND consumed_at IS NULL + AND expires_at > $4 + RETURNING * + `, + [id, appSlug, accountId, at] + ); + return result.rowCount ? mapPendingLinkRow(expectRow(result.rows[0], "consumePendingLink")) : null; + } + + async claimOAuthStateUse(input: ClaimOAuthStateUseInput): Promise { + // No conflict target and no RETURNING: ON CONFLICT DO NOTHING alone says whether the row was new. + const result = await this.pool.query( + ` + INSERT INTO oauth_state_uses (jti, phase, app_slug, used_at, expires_at) + VALUES ($1, $2, $3, $4, $5) + ON CONFLICT DO NOTHING + `, + [input.jti, input.phase, input.appSlug, input.usedAt, input.expiresAt] + ); + if (result.rowCount !== 1) return false; + // Retention: one bounded delete of records past the shared cutoff, inline as the memory store does. + // The claim row is already written, so a prune failure must not fail the claim: a throw would make + // the user's retry look like a replay. Unpruned rows are harmless and the next claim prunes them. + try { + await this.pool.query( + ` + DELETE FROM oauth_state_uses + WHERE (jti, phase) IN ( + SELECT jti, phase FROM oauth_state_uses WHERE expires_at <= $1 LIMIT $2 + ) + `, + [new Date(oauthStatePruneCutoffMs(Date.parse(input.usedAt))), OAUTH_STATE_PRUNE_BATCH] + ); + } catch { + // deliberately swallowed, see above + } + return true; + } + async upsertEntitlementSnapshot(input: CreateEntitlementSnapshotInput): Promise { await this.pool.query( ` @@ -1091,6 +1470,52 @@ export class PostgresStore implements HeimdallStore { ); } + async createConsentReceipt(input: CreateConsentReceiptInput): Promise<{ receipt: StoredConsentReceipt; created: boolean }> { + const grant = input.kind === "grant" ? input : null; + // No conflict target and the partial unique index decides: a second + // revocation of one grant inserts nothing and the first is read back. + const result = await this.pool.query( + ` + INSERT INTO consent_receipts ( + id, kind, account_id, app_slug, provider, created_at, + scopes_asked, scopes_granted, consent_page_digest, consent_text, revokes_receipt_id + ) + VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11) + ON CONFLICT DO NOTHING + RETURNING * + `, + [ + randomUUID(), + input.kind, + input.accountId, + input.appSlug, + input.provider, + input.createdAt, + grant ? grant.scopesAsked.join(" ") : null, + grant ? grant.scopesGranted.join(" ") : null, + grant ? grant.consentPageDigest : null, + grant ? grant.consentText : null, + input.kind === "revocation" ? input.revokesReceiptId : null, + ] + ); + if (result.rowCount) { + return { receipt: mapConsentReceiptRow(expectRow(result.rows[0], "createConsentReceipt")), created: true }; + } + const existing = await this.pool.query( + `SELECT * FROM consent_receipts WHERE revokes_receipt_id = $1`, + [input.kind === "revocation" ? input.revokesReceiptId : null] + ); + return { receipt: mapConsentReceiptRow(expectRow(existing.rows[0], "createConsentReceipt")), created: false }; + } + + async listConsentReceipts(accountId: string): Promise { + const result = await this.pool.query( + `SELECT * FROM consent_receipts WHERE account_id = $1 ORDER BY created_at, id`, + [accountId] + ); + return result.rows.map(mapConsentReceiptRow); + } + async createAuditEvent(input: CreateAuditEventInput): Promise { await this.pool.query( ` diff --git a/src/store/schema.ts b/src/store/schema.ts index 420f5e6..ff1fcf2 100644 --- a/src/store/schema.ts +++ b/src/store/schema.ts @@ -82,6 +82,19 @@ CREATE TABLE IF NOT EXISTS private_command_receipts ( CREATE INDEX IF NOT EXISTS private_command_receipts_expiry_idx ON private_command_receipts(expires_at); +CREATE TABLE IF NOT EXISTS pending_links ( + id TEXT PRIMARY KEY, + app_slug TEXT NOT NULL, + account_id TEXT NOT NULL REFERENCES accounts(id) ON DELETE CASCADE, + provider TEXT NOT NULL, + provider_user_id TEXT NOT NULL, + identity_json JSONB NOT NULL, + return_to TEXT NOT NULL, + created_at TIMESTAMPTZ NOT NULL, + expires_at TIMESTAMPTZ NOT NULL, + consumed_at TIMESTAMPTZ +); + CREATE TABLE IF NOT EXISTS auth_completions ( code TEXT PRIMARY KEY, app_slug TEXT NOT NULL, @@ -106,6 +119,15 @@ CREATE INDEX IF NOT EXISTS auth_completions_lookup_idx -- redeem the completion it created without ever needing the code. ALTER TABLE auth_completions ADD COLUMN IF NOT EXISTS attempt_id TEXT; +-- The connection target the signed state named (connection.targetId). Redeem +-- compares it against the target the redeeming app states. +ALTER TABLE auth_completions ADD COLUMN IF NOT EXISTS target_id TEXT; + +-- When a refresh attempt on this row last failed or timed out, read under the row +-- lock so a second Heimdall process does not present the same refresh token +-- right behind it. Cleared by rotation, revocation and re-link. +ALTER TABLE linked_identities ADD COLUMN IF NOT EXISTS refresh_failed_at TIMESTAMPTZ; + -- One attempt handle may bind at most one unconsumed completion (R21.1): a -- second completion for the same handle would let the by-attempt UPDATE in -- consumeAuthCompletionByAttempt match more than one row, silently consuming @@ -119,6 +141,23 @@ CREATE UNIQUE INDEX IF NOT EXISTS auth_completions_attempt_unconsumed_unique_idx ON auth_completions(app_slug, attempt_id) WHERE attempt_id IS NOT NULL AND consumed_at IS NULL; +-- One use per (state jti, phase): a signed OAuth state launches once and +-- completes once. The first INSERT for a pair wins; ON CONFLICT DO NOTHING +-- reports every later claim as no row. A state is accepted until expires_at + 30 s +-- of skew, so a row may be pruned only after that and is never consulted again; +-- each successful claim deletes a bounded batch of rows past expires_at + skew +-- + margin (OAUTH_STATE_* in types.ts), found through the expires_at index. +CREATE TABLE IF NOT EXISTS oauth_state_uses ( + jti TEXT NOT NULL, + phase TEXT NOT NULL, + app_slug TEXT NOT NULL, + used_at TIMESTAMPTZ NOT NULL, + expires_at TIMESTAMPTZ NOT NULL, + PRIMARY KEY (jti, phase) +); + +CREATE INDEX IF NOT EXISTS oauth_state_uses_expires_at_idx ON oauth_state_uses(expires_at); + CREATE TABLE IF NOT EXISTS capability_grants ( id TEXT PRIMARY KEY, account_id TEXT NOT NULL REFERENCES accounts(id) ON DELETE CASCADE, @@ -149,6 +188,57 @@ CREATE TABLE IF NOT EXISTS entitlement_snapshots ( UNIQUE(account_id, provider, scope) ); +-- Consent receipts are append-only (the store role has INSERT and SELECT +-- only): a revocation is a row that names the grant it takes back. +CREATE TABLE IF NOT EXISTS consent_receipts ( + id TEXT PRIMARY KEY, + kind TEXT NOT NULL, + account_id TEXT NOT NULL REFERENCES accounts(id) ON DELETE CASCADE, + app_slug TEXT NOT NULL, + provider TEXT NOT NULL, + created_at TIMESTAMPTZ NOT NULL, + scopes_asked TEXT, + scopes_granted TEXT, + consent_page_digest TEXT, + consent_text TEXT, + revokes_receipt_id TEXT, + UNIQUE(id, account_id), + FOREIGN KEY (revokes_receipt_id, account_id) REFERENCES consent_receipts(id, account_id) +); + +-- A revocation names a receipt of its own account (the composite foreign key; +-- NULL skips it for grants). A grant is taken back once: the second +-- revocation naming it conflicts. +CREATE UNIQUE INDEX IF NOT EXISTS consent_receipts_revokes_unique_idx + ON consent_receipts(revokes_receipt_id) + WHERE revokes_receipt_id IS NOT NULL; + +CREATE INDEX IF NOT EXISTS consent_receipts_account_idx + ON consent_receipts(account_id, created_at); + +-- One row per identity move, append-only: no UPDATE and no DELETE, and no +-- ON DELETE CASCADE, so the record outlives nothing it names. moved_json is +-- [{id, provider, providerUserId, credentialStripped}]; proof_json is +-- {from: [{tier, method, identityId}], to: {...} | null}. Never a token, sid, +-- email or name. A move is reversed once: the second row naming it conflicts. +CREATE TABLE IF NOT EXISTS identity_moves ( + id TEXT PRIMARY KEY, + app_slug TEXT NOT NULL, + from_account_id TEXT NOT NULL REFERENCES accounts(id), + to_account_id TEXT NOT NULL REFERENCES accounts(id), + reverses_move_id TEXT REFERENCES identity_moves(id), + moved_json JSONB NOT NULL, + proof_json JSONB NOT NULL, + created_at TIMESTAMPTZ NOT NULL +); + +CREATE UNIQUE INDEX IF NOT EXISTS identity_moves_reverses_unique_idx + ON identity_moves(reverses_move_id) + WHERE reverses_move_id IS NOT NULL; + +CREATE INDEX IF NOT EXISTS identity_moves_from_idx + ON identity_moves(from_account_id); + CREATE TABLE IF NOT EXISTS audit_events ( id TEXT PRIMARY KEY, account_id TEXT, @@ -210,7 +300,7 @@ export const REQUIRED_TABLES = createdTables.map(({ table }) => table); export const REQUIRED_COLUMNS = [ ...createdTables.flatMap(({ table, lines }) => lines - .filter((line) => !/^(?:PRIMARY KEY|UNIQUE)\b/.test(line)) + .filter((line) => !/^(?:PRIMARY KEY|UNIQUE|FOREIGN KEY)\b/.test(line)) .map((line) => { const [, column, type] = /^(\w+) (\w+)/.exec(line)!; return { table, column: column!, type: type!, nullable: !/\b(?:NOT NULL|PRIMARY KEY)\b/.test(line) }; diff --git a/src/store/types.ts b/src/store/types.ts index 5307e1f..78d12a4 100644 --- a/src/store/types.ts +++ b/src/store/types.ts @@ -33,12 +33,86 @@ export interface StoredLinkedIdentity { accessTokenEncrypted?: string; refreshTokenEncrypted?: string; tokenExpiresAt?: string; + /** When a refresh attempt last failed; cleared by the next rotation, revocation or re-link. */ + refreshFailedAt?: string; scopes: string[]; profileJson: Record; createdAt: string; updatedAt: string; } +/** + * An upsert named an identity another account holds. A provider identity + * belongs to the account that holds it until that account unlinks it; no + * write moves it. + */ +export class IdentityHeldElsewhereError extends Error { + constructor() { + super("This provider identity is held by another account."); + this.name = "IdentityHeldElsewhereError"; + } +} + +/** What unlinkLinkedIdentity decided; `identity` is the row as it was deleted. */ +export type UnlinkResult = + | { kind: "unlinked"; identity: StoredLinkedIdentity } + | { kind: "last_identity" } + | { kind: "not_found" }; + +/** One login a move carried; `credentialStripped` is history written at the move (the row held a token the move dropped). */ +export interface MovedIdentity { + id: string; + provider: Provider; + providerUserId: string; + credentialStripped: boolean; +} + +/** What each side's proofs were, as tiers and methods only: never a token, sid, email or name. */ +export interface IdentityMoveProof { + from: { tier: "strong" | "weak"; method: string | null; identityId: string | null }[]; + to: { tier: "strong" | "weak"; method: string | null; identityId: string | null } | null; +} + +/** The append-only record of one move. */ +export interface StoredIdentityMove { + id: string; + appSlug: AppSlug; + fromAccountId: string; + toAccountId: string; + reversesMoveId?: string; + moved: MovedIdentity[]; + proof: IdentityMoveProof; + createdAt: string; +} + +export interface MoveIdentitiesInput { + moveId: string; + appSlug: AppSlug; + fromAccountId: string; + toAccountId: string; + /** The logins to carry, or every login the source holds. */ + identityIds: readonly string[] | "all"; + /** What the caller's from-proofs cover: the whole account, or exactly these logins. */ + covers: "account" | readonly string[]; + /** Sessions the proofs rested on; each must still be live when the transaction commits. */ + proofSessions: readonly { appSlug: AppSlug; sessionId: string; accountId: string; accessRevision: number }[]; + reversesMoveId?: string; + proof: IdentityMoveProof; + at: string; +} + +/** What moveIdentities decided. Refusals write nothing. */ +export type MoveResult = + | { kind: "moved"; move: StoredIdentityMove } + | { kind: "replayed"; move: StoredIdentityMove } + | { kind: "move_id_conflict" } + | { kind: "proof_lapsed" } + | { kind: "already_moved" } + | { kind: "identity_not_found" } + | { kind: "identity_not_proved" } + | { kind: "provider_conflict"; provider: Provider } + | { kind: "not_reversible" }; + export interface UpsertLinkedIdentityInput { id?: string; accountId: string; @@ -58,8 +132,9 @@ export interface UpsertLinkedIdentityInput { /** * What the owner of a refresh decides after reading the row under its lock. - * `rotate` and `revoke` write token columns, scopes and updated_at only; they - * never touch account, profile or identity fields. + * `rotate` and `revoke` write token columns, scopes, updated_at and clear the + * failed-refresh marker; `failed` writes the marker alone. None touches + * account, profile or identity fields. */ export type CredentialDecision = | { kind: "keep" } @@ -70,8 +145,11 @@ export type CredentialDecision = tokenExpiresAt: string; scopes: string[]; updatedAt: string; + /** The provider rotates refresh tokens, so the one presented is spent whether or not this decision commits. */ + consumedRefreshToken: boolean; } - | { kind: "revoke"; updatedAt: string }; + | { kind: "revoke"; updatedAt: string } + | { kind: "failed"; failedAt: string }; export interface StoredSession { id: string; @@ -159,18 +237,46 @@ export interface StoredAuthCompletion { accountId: string; sessionId: string; returnTo: string; + /** The connection target the signed state named, if any; compared at redeem. */ + targetId?: string; createdAt: string; expiresAt: string; consumedAt?: string; payloadJson: Record; } +/** The skew a signed OAuth state is still accepted for past its exp: verifyOAuthState in app.ts reads this, so the two cannot drift. */ +export const OAUTH_STATE_SKEW_MS = 30_000; +/** Extra time a use record is kept past exp + skew before it may be pruned. */ +export const OAUTH_STATE_PRUNE_MARGIN_MS = 10 * 60_000; +/** The most use records one claim deletes. */ +export const OAUTH_STATE_PRUNE_BATCH = 50; + +/** + * The one retention rule for oauth_state_uses, shared by both stores: a record + * is prunable when expires_at + skew + margin <= now, that is when its + * expires_at is at or before this cutoff. + */ +export function oauthStatePruneCutoffMs(nowMs: number): number { + return nowMs - OAUTH_STATE_SKEW_MS - OAUTH_STATE_PRUNE_MARGIN_MS; +} + +export interface ClaimOAuthStateUseInput { + jti: string; + /** `step_up_assert` is the app-asserted step-up route's one-use nonce claim: jti is a digest of session and nonce. */ + phase: "launch" | "callback" | "step_up_assert"; + appSlug: AppSlug; + usedAt: string; + expiresAt: string; +} + export interface CreateAuthCompletionInput { /** * Correlation handle only (see StoredAuthCompletion.attemptId). The store * always mints `code` itself; a caller cannot choose it. */ attemptId?: string; + targetId?: string; appSlug: AppSlug; provider: Provider; mode: OAuthMode; @@ -182,6 +288,28 @@ export interface CreateAuthCompletionInput { payloadJson: Record; } +/** + * A link the callback has verified but not written. The identity attaches to + * `accountId` (the account whose Heimdall access token began the link) only + * when that same account confirms it; until then no linked-identity row + * exists. `identity` holds the already-encrypted row to write. + */ +export interface StoredPendingLink { + id: string; + appSlug: AppSlug; + accountId: string; + provider: Provider; + providerUserId: string; + identity: UpsertLinkedIdentityInput; + returnTo: string; + createdAt: string; + expiresAt: string; + consumedAt?: string; +} + +/** The store mints `id`; a caller cannot choose it. */ +export type CreatePendingLinkInput = Omit; + export interface StoredAuthAttempt { handle: string; appSlug: AppSlug; @@ -219,6 +347,33 @@ export interface StoredPrivateCommandReceipt { export type CreatePrivateCommandReceiptInput = StoredPrivateCommandReceipt; +/** + * What a person agreed to, or took back. Append-only: a grant row is never + * edited, and a revocation is a second row naming it, so a grant is live + * exactly when no revocation names it. `scopesAsked` is what Heimdall sent the + * provider, `scopesGranted` what the provider returned, `consentPageDigest` + * the hash of the wording the person was shown and `consentText` that wording + * itself. A grant is revoked at most once: a second revocation naming the same + * grant is not written, and the store answers with the first. + */ +export type StoredConsentReceipt = { + id: string; + accountId: string; + appSlug: AppSlug; + provider: Provider; + createdAt: string; +} & ( + | { kind: "grant"; scopesAsked: string[]; scopesGranted: string[]; consentPageDigest: string; consentText: string } + | { kind: "revocation"; revokesReceiptId: string } +); + +/** The store mints `id`; a caller cannot choose it. */ +export type CreateConsentReceiptInput = StoredConsentReceipt extends infer R + ? R extends StoredConsentReceipt + ? Omit + : never + : never; + export interface HeimdallStore { ensureSchema(): Promise; close(): Promise; @@ -229,7 +384,26 @@ export interface HeimdallStore { findStoredLinkedIdentity(provider: Provider, providerUserId: string): Promise; findStoredLinkedIdentityForAccount(accountId: string, provider: Provider): Promise; listStoredLinkedIdentitiesForAccount(accountId: string): Promise; + /** Writes the holder's own row; throws IdentityHeldElsewhereError rather than move another account's identity. */ upsertLinkedIdentity(input: UpsertLinkedIdentityInput): Promise; + /** + * The only delete of a linked identity. One transaction locks the account, + * refuses to take its last identity, and deletes the row only if the + * account holds it (an id that is missing or another account's is the same + * `not_found`). + */ + unlinkLinkedIdentity(accountId: string, identityId: string): Promise; + /** + * The only writer that sets a linked identity's account to another account, + * in one transaction: lock both accounts (in id order), answer a repeated + * moveId from its row, re-check the proof sessions, refuse what the rules + * refuse, move the rows with their credentials stripped, revoke the source's + * sessions and expire its pending links and unredeemed completions, and + * append the identity_moves row. A reversal (`reversesMoveId`) moves back + * exactly what the forward move carried. The destination never loses an identity. + */ + moveIdentities(input: MoveIdentitiesInput): Promise; + findIdentityMove(moveId: string): Promise; /** * Serialise decisions about one row's credential. `decide` receives the row * as read under the lock (never a caller's snapshot) and the decision is @@ -263,6 +437,8 @@ export interface HeimdallStore { createPrivateCommandReceipt(input: CreatePrivateCommandReceiptInput): Promise; findPrivateCommandReceipt(appSlug: AppSlug, idempotencyKey: string): Promise; createAuthCompletion(input: CreateAuthCompletionInput): Promise; + /** Read a completion without consuming it, so redeem can refuse a mismatch without burning the code. */ + findAuthCompletion(appSlug: AppSlug, code: string): Promise; consumeAuthCompletion(appSlug: AppSlug, code: string, at: string): Promise; /** * Consume a completion by its correlated attempt handle instead of its @@ -271,6 +447,27 @@ export interface HeimdallStore { * it created without ever needing to know (or forge) the code. */ consumeAuthCompletionByAttempt(appSlug: AppSlug, attemptId: string, at: string): Promise; + createPendingLink(input: CreatePendingLinkInput): Promise; + /** + * Single-use redemption: returns the link only for the app and the account + * it was begun by, before it expires and once. A mismatch returns null and + * leaves the link unconsumed. + */ + consumePendingLink(appSlug: AppSlug, id: string, accountId: string, at: string): Promise; upsertEntitlementSnapshot(input: CreateEntitlementSnapshotInput): Promise; + /** + * Claim one use of a signed OAuth state: true only for the first claim of + * (jti, phase), false for every later one. Without it a state is a bearer + * token any number of browsers can complete, so an attacker who learns a + * victim's state completes it as themselves and hands the victim a code + * for the attacker's account. `expiresAt` is the state's own expiry; the + * state is refused at that time before any claim, so the record is dead + * after it and a store may drop it. + */ + claimOAuthStateUse(input: ClaimOAuthStateUseInput): Promise; createAuditEvent(input: CreateAuditEventInput): Promise; + /** `created` is false when a revocation for that grant already existed and is what comes back. */ + createConsentReceipt(input: CreateConsentReceiptInput): Promise<{ receipt: StoredConsentReceipt; created: boolean }>; + /** Every receipt the account holds, oldest first. */ + listConsentReceipts(accountId: string): Promise; } diff --git a/state/evidence.jsonl b/state/evidence.jsonl index 5329d5f..279b21e 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -37,3 +37,7 @@ {"ts": "2026-09-08T12:20:12+00:00", "type": "security", "status": "accepted", "note": "epiphany/heimdall-caller-identity, second Hands pass: closed the two Soul-proven holes. (1) auth-completions redeem code is now always store-minted (never handoff.attemptId); attemptId survives only as a separate correlation field on StoredAuthCompletion/CreateAuthCompletionInput, and a new store.consumeAuthCompletionByAttempt(appSlug, attemptId, at) lets the private command plane's completeAuth redeem by the handle it already owns instead of forging an HTTP self-call with completionCode=handle. (2) startOAuthFlow now refuses any returnTo whose origin is not in AppProfile.allowedReturnOrigins (repixelizer/streampixels/bifrost -> .gamecult.org, ghostlight -> yggdrasil.gamecult.org per its docs/app-profiles doc and existing test fixtures; a registered app's allowlist is derived from its stored redirectUris origins). AppCaller is now branded with an unexported Symbol (app-caller.ts); private-command-plane.ts's two { appSlug } literals are gone, replaced by app-caller.ts's callerFromOpenedEnvelope. Deleted: validateAppRegistration, AppRegistrationRequest, RegistrationProblem, AppRegistrationError, HeimdallStore.registerApp (writer). Kept: findRegisteredApp/listRegisteredApps/resolveAppProfile fallback -- AppSlug is a plain string (contracts.ts), registered_apps is a real extension point for a slug Heimdall was never rebuilt for, and isBuiltInApp's only production call site (listAppProfiles) depends on that fallback existing; a row is now provisioned by direct SQL (or InMemoryStore.seedRegisteredApp in tests), not by any app-facing writer. Deleted the two appSlug===\"ghostlight\" branches in private-command-plane.ts; the requirement is now AppProfile.requiredEntitlementPolicyKind, checked generically through resolveAppProfile. tsc --noEmit clean; vitest 94 passed/1 pre-existing-skip, only pre-existing failure is tests/odin-publication.test.ts (Cannot find module 'cultcache-ts', present on main too).", "branch": "epiphany/heimdall-caller-identity"} {"ts": "2026-10-19T15:56:24+00:00", "type": "design", "status": "accepted", "note": "Refresh is now one locked primitive for every provider (replaces unserialized refreshLinkedIdentityCredentialIfNeeded); Joystick is managed-only (Heimdall-held credential, no viewer sign-in until joystick:follow_up:joystick-viewer-signin-public-bot). Merged in PR #1, live at d51fa6b; campaign joystick:campaign:self.", "branch": "eureka/joystick-h1"} {"ts": "2026-10-19T16:03:16+00:00", "type": "verification", "status": "accepted", "note": "Live d51fa6b (H1) verified by a real human sign-in: the operator's StreamPixels Twitch sign-in through Heimdall start/callback, 2026-10-19 ('Twitch auth worked fine'); a streampixels session was created 16:02:33Z, after the 15:51Z switch. Joystick consent round trip still open: joystick:follow_up:h1-joystick-consent-round-trip."} +{"ts": "2026-11-12T23:10:15+00:00", "type": "design", "status": "accepted", "note": "Changelog 2026-11-12: sign_in start accepts stepUp (app-authenticated, sign_in only, off by default); signed state carries step_up; launch adds Twitch force_verify=true, YouTube prompt='login consent', Google prompt=login; any other provider is 400 step_up_not_supported; completion reports stepUpRequested. Not deployed. For joystick:follow_up:chat-s7055-7056 (StreamPixels link hardening, second factor via fresh sign-in)."} +{"ts": "2026-11-13T19:10:00+00:00", "type": "design", "status": "accepted", "note": "Changelog 2026-11-13: GET /v1/me/identities lists an account's identities (no credentials, profile or email); POST /v1/me/identities/:id/unlink deletes one with a step-up proof (access claim step_up_at, 600 s, never carried by refresh), refuses the last identity (409), writes revocation receipts when the provider's last identity goes. upsertLinkedIdentity no longer moves an identity between accounts (IdentityHeldElsewhereError; links/confirm 409 identity_linked_elsewhere, callback link_initiator_mismatch). The store role needs DELETE on linked_identities (startup refuses without it): owner-role GRANT at deploy."} +{"ts": "2026-11-13T20:01:42+00:00", "type": "design", "status": "accepted", "note": "Changelog 2026-11-13: POST /v1/apps/{app}/step-up (profile grant stepUpAssertion, bifrost only; methods bifrost-passkey, bifrost-email-code). App secret plus the member's live bearer for that app; mints a same-session access token with step_up_at now and new claim step_up_method (exp kept, no refresh, no session write); nonce single-use via oauth_state_uses phase step_up_assert (no schema change), retained to the session expiry as of the claim (a refresh may slide the session past it); in-process rate limits 10 per 600 s per account, 120 per 60 s per app; audit step_up_asserted and step_up_assertion_refused with a nonce digest (429s and not-permitted refusals audited once per window; not-permitted has a 5 per 60 s per-app budget); nonce is base64url 16-128. Provider step-up sign-ins now carry step_up_method provider:; identity_unlinked records stepUpMethod. Heimdall cannot verify the factor: it trusts the calling app. Not deployed; no env, secret or migration. For heimdall-body:follow_up:chat-s7419-7419.", "branch": "heimdall/app-asserted-step-up"} +{"ts": "2026-11-14T01:10:00+00:00", "type": "design", "status": "accepted", "note": "Changelog 2026-11-14: POST /v1/apps/{app}/identity-moves (profile grant identityMoves, bifrost only; accountProofMethods bifrost-passkey) and the identity_moves table, the only writer of linked_identities.account_id (moveIdentities, one transaction, accounts locked in id order, shared decideMove on both stores). Access claims gain auth_at and auth_identity_id (sign_in callback only). proofTier is the one freshness rule (unlink reads it; strong 600 s step_up_at, weak 300 s auth_at); proofCovers: only an asserted account-proof method covers a whole account, otherwise the login in auth_identity_id (ruling move-proof-strict-passkey). Moves strip credentials, revoke the source's sessions, expire its pending links and unredeemed completions, write revocation receipts under the source, audit identity_moved; moveId is idempotent (replay answers the stored receipt without proof liveness); a move is reversible once. Not deployed: the owner must apply the identity_moves DDL and GRANT SELECT, INSERT ON identity_moves to the store role before the new build starts (startup refuses SCHEMA_MISSING / SCHEMA_PRIVILEGES otherwise).", "branch": "heimdall/identity-moves"} diff --git a/tests/access-plugin.test.ts b/tests/access-plugin.test.ts index 4789bf8..6da0568 100644 --- a/tests/access-plugin.test.ts +++ b/tests/access-plugin.test.ts @@ -8,6 +8,7 @@ import { entitlementFacts } from "../src/facts.js"; import { startHeimdallPrivateCommandPlane } from "../src/private-command-plane.js"; import { openPrivateEnvelope, sealPrivateEnvelope, type HeimdallPrivateEnvelope } from "../src/private-command-security.js"; import { type OAuthProviderRuntime } from "../src/oauth.js"; +import { launchState } from "./oauth-flow.js"; const secret = "ghostlight-private-command-secret"; const resources: Array<{ close(): Promise }> = []; @@ -107,9 +108,12 @@ describe("Heimdall Eve access plugin", () => { const begin = openPrivateEnvelope(beginWire, secret); expect(begin.schema).toBe("heimdall.auth_begin_receipt.v1"); const handle = String(begin.handle); - const navigation = begin.navigation as { url: string }; + const navigation = begin.navigation as { url: string; allowedOrigins: string[] }; const state = new URL(navigation.url).searchParams.get("state"); expect(state).toBeTruthy(); + // The browser goes to Heimdall's launch hop first, and only Heimdall's origin is allowed. + expect(navigation.url.startsWith("https://heimdall.gamecult.org/v1/oauth/discord/launch?state=")).toBe(true); + expect(navigation.allowedOrigins).toEqual(["https://heimdall.gamecult.org"]); const pendingEnvelope = sealPrivateEnvelope({ appSlug: "ghostlight", @@ -124,9 +128,11 @@ describe("Heimdall Eve access plugin", () => { const pending = openPrivateEnvelope(decodeEnvelope(pendingResponse.payload), secret); expect(pending).toMatchObject({ status: "pending", handle }); + const { cookie } = await launchState(app, state ?? ""); const callback = await app.inject({ method: "GET", url: `/v1/oauth/discord/callback?code=test-code&state=${encodeURIComponent(state ?? "")}`, + headers: { cookie }, }); expect(callback.statusCode, callback.body).toBe(201); // The completion code is always minted by the store now, never the @@ -291,7 +297,7 @@ function testConfig(): HeimdallConfig { storage: { backend: "memory", applySchemaOnStartup: true }, providers: { discord: { clientId: "discord-client", clientSecret: "discord-secret" }, - patreon: {}, github: {}, twitch: {}, youtube: {}, spotify: {}, joystick: {}, + patreon: {}, github: {}, twitch: {}, youtube: {}, spotify: {}, joystick: {}, google: {}, }, }; } diff --git a/tests/app.test.ts b/tests/app.test.ts index 7f4d96d..20a0191 100644 --- a/tests/app.test.ts +++ b/tests/app.test.ts @@ -4,7 +4,8 @@ import { join } from "node:path"; import { inspect } from "node:util"; import { afterEach, describe, expect, it } from "vitest"; import { type FastifyInstance } from "fastify"; -import { buildApp, errorIdentity } from "../src/app.js"; +import { buildApp, errorIdentity, getHeimdallRuntimeContext, startOAuthFlow } from "../src/app.js"; +import { resolveAppCaller } from "../src/app-caller.js"; import { builtInAppProfiles, callbackMint } from "../src/app-profiles.js"; import { deliverBackendHandoff, type BackendHandoffPayload } from "../src/backend-handoff.js"; import { type HeimdallConfig, loadConfig } from "../src/config.js"; @@ -12,96 +13,7 @@ import { entitlementFacts, identityFacts } from "../src/facts.js"; import { createOAuthRuntimeRegistry, ProviderResponseError, type OAuthProviderRuntime } from "../src/oauth.js"; import { createRuntimeKeyMaterial, signJwt, verifyJwt } from "../src/signing.js"; import { InMemoryStore } from "../src/store/index.js"; - -function createTestConfig(): HeimdallConfig { - return { - serviceName: "heimdall", - host: "127.0.0.1", - port: 4100, - workspaceRoot: "E:/Projects/Heimdall", - dataRoot: "E:/Projects/Heimdall/.heimdall-data", - cultCachePath: "E:/Projects/Heimdall/.heimdall-data/cultcache/heimdall.service.cc", - publicBaseUrl: "https://heimdall.gamecult.org", - issuer: "https://heimdall.gamecult.org", - daemonId: "yggdrasil-heimdall", - idunnRudpHealth: undefined, - idunnHealthContract: "heimdall.cultnet-rudp-provider-health", - providerHealthIdentityPath: "E:/Projects/Heimdall/.heimdall-data/provider-health-identity.cc", - sessionTtlSeconds: 3600, - refreshTtlSeconds: 60 * 60 * 24 * 30, - stateTtlSeconds: 600, - completionTtlSeconds: 300, - bootstrapSigningPrivateKeyOnMissing: false, - tokenEncryptionKeyBase64: Buffer.alloc(32, 7).toString("base64"), - appSharedSecrets: { - streampixels: "streampixels-secret", - repixelizer: "repixelizer-secret", - bifrost: "bifrost-secret", - }, - appBackendCallbacks: { - bifrost: ["https://bifrost.gamecult.org/auth/heimdall/callback"], - repixelizer: ["https://repixelizer.gamecult.org/api/auth/heimdall/callback"], - }, - storage: { - backend: "memory", - applySchemaOnStartup: true, - }, - providers: { - discord: { clientId: "discord-client", clientSecret: "discord-secret" }, - patreon: { clientId: "patreon-client", clientSecret: "patreon-secret" }, - github: { clientId: "github-client", clientSecret: "github-secret" }, - twitch: { clientId: "twitch-client", clientSecret: "twitch-secret" }, - youtube: { clientId: "youtube-client", clientSecret: "youtube-secret" }, - spotify: { clientId: "spotify-client", clientSecret: "spotify-secret" }, - joystick: { clientId: "joystick-client", clientSecret: "joystick-secret" }, - }, - }; -} - -function createMockDiscordRuntime(): OAuthProviderRuntime { - return { - async exchangeAuthorizationCode() { - return { - accessToken: "discord-access-token", - refreshToken: "discord-refresh-token", - tokenType: "Bearer", - scope: ["identify", "guilds.members.read"], - expiresAt: "2026-04-26T13:00:00.000Z", - raw: { source: "test" }, - }; - }, - async resolveIdentity() { - return { - provider: "discord", - providerUserId: "discord-user-123", - username: "meta", - displayName: "Meta", - primaryEmail: "meta@gamecult.org", - profile: { id: "discord-user-123", username: "meta" }, - }; - }, - async evaluateEntitlements({ callback }) { - return { - facts: [entitlementFacts.appAccess], - snapshots: [ - { - accountId: callback.accountId, - provider: "discord", - scope: "repixelizer:discord_role_access:gamecult-guild", - evaluatedAt: "2026-04-26T12:00:00.000Z", - isAllowed: true, - reasonCode: "matched_role", - reasonDetail: "Matched Repixelizer access role.", - rawSummaryJson: { - guildId: "gamecult-guild", - matchedRoles: ["role-repixelizer"], - }, - }, - ], - }; - }, - }; -} +import { createMockDiscordRuntime, createTestConfig, launchFlow, providerRedirect, stateOf, type LaunchedFlow } from "./oauth-flow.js"; const apps: Awaited>[] = []; const originalFetch = globalThis.fetch; @@ -134,7 +46,7 @@ function getHeimdallContext(app: FastifyInstance) { }).heimdallContext; } -async function startDiscordSignIn(app: FastifyInstance): Promise { +async function startDiscordSignIn(app: FastifyInstance): Promise { const response = await app.inject({ method: "POST", url: "/v1/oauth/discord/start", @@ -146,7 +58,7 @@ async function startDiscordSignIn(app: FastifyInstance): Promise { }); expect(response.statusCode).toBe(201); - return response.json().stateToken as string; + return launchFlow(app, response.json()); } afterEach(async () => { @@ -207,9 +119,9 @@ describe("Heimdall service", () => { expect(response.statusCode).toBe(201); const payload = response.json(); - expect(payload.authorizationUrl).toContain("discord.com/oauth2/authorize"); + expect((await providerRedirect(app, payload)).href).toContain("discord.com/oauth2/authorize"); - const verified = verifyJwt(payload.stateToken as string, getPublicKey(app)); + const verified = verifyJwt(stateOf(payload), getPublicKey(app)); expect(verified.valid).toBe(true); if (verified.valid) { expect(verified.payload).toEqual( @@ -249,6 +161,170 @@ describe("Heimdall service", () => { expect(response.json()).toEqual(expect.objectContaining({ error: "app_auth_required" })); }); + describe("apps that bind browser completion to their own attempt", () => { + // Bifrost's browser binding is the secrecy of its attempt nonce, which + // travels readable in the signed state. Only Bifrost may mint a Bifrost + // state, so a known nonce cannot carry a stranger's completion + // (finding known-nonce-login-csrf). + const victimAttempt = "VICTIM-ATTEMPT-NONCE"; + const bifrostReturn = `https://bifrost.gamecult.org/auth/heimdall/complete?attempt=${victimAttempt}`; + const bifrostStart = (handoff?: { kind: "browser_completion" }) => ({ + appSlug: "bifrost" as const, + mode: "sign_in" as const, + returnTo: bifrostReturn, + ...(handoff ? { handoff } : {}), + }); + + it("refuses an unauthenticated Bifrost start for browser_completion and for an omitted handoff", async () => { + const app = await buildApp({ config: createTestConfig() }); + apps.push(app); + + for (const payload of [bifrostStart({ kind: "browser_completion" }), bifrostStart()]) { + const response = await app.inject({ method: "POST", url: "/v1/oauth/discord/start", payload }); + expect(response.statusCode).toBe(401); + expect(response.json()).toEqual({ error: "app_auth_required" }); + } + }); + + it("the attack fails: a stranger cannot obtain a Bifrost state carrying a chosen return_to nonce", async () => { + const app = await buildApp({ config: createTestConfig() }); + apps.push(app); + + const response = await app.inject({ + method: "POST", + url: "/v1/oauth/discord/start", + payload: bifrostStart({ kind: "browser_completion" }), + }); + expect(response.statusCode).toBe(401); + expect(response.body).not.toContain(victimAttempt); + expect(response.body).not.toContain("stateToken"); + expect(response.body).not.toContain("authorizationUrl"); + }); + + it("still starts for Bifrost's own app secret, with the requested return_to in the state", async () => { + const app = await buildApp({ config: createTestConfig() }); + apps.push(app); + + const response = await app.inject({ + method: "POST", + url: "/v1/oauth/discord/start", + headers: { "x-heimdall-app-secret": "bifrost-secret" }, + payload: bifrostStart({ kind: "browser_completion" }), + }); + expect(response.statusCode).toBe(201); + const verified = verifyJwt(stateOf(response.json()), getPublicKey(app)); + expect(verified.valid).toBe(true); + if (verified.valid) { + expect(verified.payload).toEqual(expect.objectContaining({ app_slug: "bifrost", return_to: bifrostReturn })); + } + }); + + it("refuses another app's credentials on a Bifrost start", async () => { + const app = await buildApp({ config: createTestConfig() }); + apps.push(app); + + for (const secret of ["streampixels-secret", "repixelizer-secret"]) { + const response = await app.inject({ + method: "POST", + url: "/v1/oauth/discord/start", + headers: { "x-heimdall-app-secret": secret }, + payload: bifrostStart({ kind: "browser_completion" }), + }); + expect(response.statusCode, secret).toBe(401); + expect(response.json()).toEqual({ error: "app_auth_required" }); + } + }); + + it("refuses another app's authenticated caller on a direct Bifrost start, with no policy attached", async () => { + // Over HTTP the caller is resolved against the body's slug, so a foreign + // secret never becomes a caller at all. The command plane and direct + // callers hand startOAuthFlow a caller of their own, so the slug match is + // decided here too. + const config = createTestConfig(); + const app = await buildApp({ config }); + apps.push(app); + const foreign = resolveAppCaller(config, "repixelizer", { "x-heimdall-app-secret": "repixelizer-secret" }); + const own = resolveAppCaller(config, "bifrost", { "x-heimdall-app-secret": "bifrost-secret" }); + + const refused = await startOAuthFlow(getHeimdallRuntimeContext(app), "discord", foreign, bifrostStart({ kind: "browser_completion" })); + expect(refused.statusCode).toBe(401); + const allowed = await startOAuthFlow(getHeimdallRuntimeContext(app), "discord", own, bifrostStart({ kind: "browser_completion" })); + expect(allowed.statusCode).toBe(201); + }); + + it("gates every mode, provider and handoff kind Bifrost admits, not one spelling of them", async () => { + // Hand mutants narrowing the gate to browser_completion or to sign_in + // survived the single-case tests (finding gate-tests-narrow). + const store = new InMemoryStore(); + const now = new Date().toISOString(); + const initiator = await store.createAccount({ createdAt: now, lastSeenAt: now }); + const app = await buildApp({ config: createTestConfig(), store }); + apps.push(app); + const handoffs = [ + undefined, + { kind: "browser_completion" }, + { + kind: "backend_callback", + attemptId: "bifrost-attempt-1", + callbackUrl: "https://bifrost.gamecult.org/auth/heimdall/callback", + }, + ]; + + let cases = 0; + for (const mode of ["sign_in", "link", "connect"] as const) { + for (const provider of ["discord", "patreon"] as const) { + for (const handoff of handoffs) { + const label = `${mode} ${provider} ${handoff?.kind ?? "omitted"}`; + const payload = { + appSlug: "bifrost", + mode, + returnTo: bifrostReturn, + ...(mode === "link" ? { initiatingAccountId: initiator.id } : {}), + ...(handoff ? { handoff } : {}), + }; + const refused = await app.inject({ method: "POST", url: `/v1/oauth/${provider}/start`, payload }); + expect(refused.statusCode, label).toBe(401); + expect(refused.json(), label).toEqual({ error: "app_auth_required" }); + + const allowed = await app.inject({ + method: "POST", + url: `/v1/oauth/${provider}/start`, + headers: { "x-heimdall-app-secret": "bifrost-secret" }, + payload, + }); + expect(allowed.statusCode, label).toBe(201); + expect(allowed.json().authorizationUrl, label).toContain(`/v1/oauth/${provider}/launch?state=`); + cases += 1; + } + } + } + expect(cases).toBe(18); + }); + + it("leaves public-by-design apps unchanged: unauthenticated browser_completion starts still succeed", async () => { + const app = await buildApp({ config: createTestConfig() }); + apps.push(app); + + for (const [appSlug, provider, returnTo] of [ + ["repixelizer", "discord", "https://repixelizer.gamecult.org/app/"], + ["streampixels", "twitch", "https://streampixels.gamecult.org/app/"], + ] as const) { + const response = await app.inject({ + method: "POST", + url: `/v1/oauth/${provider}/start`, + payload: { appSlug, mode: "sign_in", returnTo, handoff: { kind: "browser_completion" } }, + }); + expect(response.statusCode, appSlug).toBe(201); + } + }); + + it("flags only Bifrost's profile", () => { + expect( + Object.values(builtInAppProfiles).filter((profile) => profile.startRequiresAppCaller).map((profile) => profile.slug) + ).toEqual(["bifrost"]); + }); + }); + it("accepts caller-owned entitlement policy for a browser completion handoff when the caller is trusted", async () => { // The other half of the same pin: a caller holding the secret may attach // policy even without a backend_callback handoff, because identity no @@ -302,9 +378,9 @@ describe("Heimdall service", () => { expect(response.statusCode).toBe(201); const payload = response.json(); - expect(payload.authorizationUrl).toContain("discord.com/oauth2/authorize"); + expect((await providerRedirect(app, payload)).href).toContain("discord.com/oauth2/authorize"); - const verified = verifyJwt(payload.stateToken as string, getPublicKey(app)); + const verified = verifyJwt(stateOf(payload), getPublicKey(app)); expect(verified.valid).toBe(true); if (verified.valid) { expect(verified.payload).toEqual( @@ -348,11 +424,11 @@ describe("Heimdall service", () => { expect(response.statusCode).toBe(201); const payload = response.json(); - const authorizationUrl = new URL(payload.authorizationUrl as string); + const authorizationUrl = await providerRedirect(app, payload); expect(`${authorizationUrl.origin}${authorizationUrl.pathname}`).toBe("https://www.patreon.com/oauth2/authorize"); expect(authorizationUrl.searchParams.get("scope")).toBe("identity identity[email]"); - const verified = verifyJwt(payload.stateToken as string, getPublicKey(app)); + const verified = verifyJwt(stateOf(payload), getPublicKey(app)); expect(verified.valid).toBe(true); if (verified.valid) { expect(verified.payload).toEqual( @@ -396,9 +472,9 @@ describe("Heimdall service", () => { expect(response.statusCode).toBe(201); const payload = response.json(); - expect(payload.authorizationUrl).toContain("discord.com/oauth2/authorize"); + expect((await providerRedirect(app, payload)).href).toContain("discord.com/oauth2/authorize"); - const verified = verifyJwt(payload.stateToken as string, getPublicKey(app)); + const verified = verifyJwt(stateOf(payload), getPublicKey(app)); expect(verified.valid).toBe(true); if (verified.valid) { expect(verified.payload).toEqual( @@ -442,10 +518,10 @@ describe("Heimdall service", () => { expect(response.statusCode).toBe(201); const payload = response.json(); - const authorizationUrl = new URL(payload.authorizationUrl as string); + const authorizationUrl = await providerRedirect(app, payload); expect(`${authorizationUrl.origin}${authorizationUrl.pathname}`).toBe("https://www.patreon.com/oauth2/authorize"); - const verified = verifyJwt(payload.stateToken as string, getPublicKey(app)); + const verified = verifyJwt(stateOf(payload), getPublicKey(app)); expect(verified.valid).toBe(true); if (verified.valid) { expect(verified.payload).toEqual( @@ -473,10 +549,11 @@ describe("Heimdall service", () => { }); apps.push(app); - const stateToken = await startDiscordSignIn(app); + const flow = await startDiscordSignIn(app); const response = await app.inject({ method: "GET", - url: `/v1/oauth/discord/callback?code=test-code&state=${encodeURIComponent(stateToken)}`, + url: `/v1/oauth/discord/callback?code=test-code&state=${encodeURIComponent(flow.state)}`, + headers: { cookie: flow.cookie }, }); expect(response.statusCode).toBe(201); @@ -689,10 +766,11 @@ describe("Heimdall service", () => { }); apps.push(app); - const stateToken = await startDiscordSignIn(app); + const flow = await startDiscordSignIn(app); const callbackResponse = await app.inject({ method: "GET", - url: `/v1/oauth/discord/callback?code=test-code&state=${encodeURIComponent(stateToken)}`, + url: `/v1/oauth/discord/callback?code=test-code&state=${encodeURIComponent(flow.state)}`, + headers: { cookie: flow.cookie }, }); const completionCode = callbackResponse.json().completion.code as string; @@ -731,10 +809,11 @@ describe("Heimdall service", () => { const auditEvents = () => [...(store as unknown as { auditEvents: Map }).auditEvents.values()]; - const stateToken = await startDiscordSignIn(app); + const flow = await startDiscordSignIn(app); const callback = await app.inject({ method: "GET", - url: `/v1/oauth/discord/callback?code=test-code&state=${encodeURIComponent(stateToken)}`, + url: `/v1/oauth/discord/callback?code=test-code&state=${encodeURIComponent(flow.state)}`, + headers: { cookie: flow.cookie }, }); const { code, expiresAt } = callback.json().completion as { code: string; expiresAt: string }; const created = auditEvents().filter((event) => event.eventType === "auth_completion_created"); @@ -815,10 +894,11 @@ describe("Heimdall service", () => { }); apps.push(app); - const stateToken = await startDiscordSignIn(app); + const flow = await startDiscordSignIn(app); const callbackResponse = await app.inject({ method: "GET", - url: `/v1/oauth/discord/callback?code=test-code&state=${encodeURIComponent(stateToken)}`, + url: `/v1/oauth/discord/callback?code=test-code&state=${encodeURIComponent(flow.state)}`, + headers: { cookie: flow.cookie }, }); expect(callbackResponse.statusCode).toBe(201); const refreshToken = callbackResponse.json().refreshToken as string; @@ -862,11 +942,12 @@ describe("Heimdall service", () => { }); apps.push(app); - const stateToken = await startDiscordSignIn(app); + const flow = await startDiscordSignIn(app); const response = await app.inject({ method: "GET", - url: `/v1/oauth/discord/callback?code=test-code&state=${encodeURIComponent(stateToken)}`, + url: `/v1/oauth/discord/callback?code=test-code&state=${encodeURIComponent(flow.state)}`, headers: { + cookie: flow.cookie, accept: "text/html", }, }); @@ -912,12 +993,13 @@ describe("Heimdall service", () => { }, }); expect(startResponse.statusCode).toBe(201); - const stateToken = startResponse.json().stateToken as string; + const flow = await launchFlow(app, startResponse.json()); const response = await app.inject({ method: "GET", - url: `/v1/oauth/discord/callback?code=test-code&state=${encodeURIComponent(stateToken)}`, + url: `/v1/oauth/discord/callback?code=test-code&state=${encodeURIComponent(flow.state)}`, headers: { + cookie: flow.cookie, accept: "text/html", }, }); @@ -1123,11 +1205,12 @@ describe("Heimdall service", () => { returnTo: "https://streampixels.gamecult.org/auth/connect", }, }); - const stateToken = startResponse.json().stateToken as string; + const flow = await launchFlow(app, startResponse.json()); const callbackResponse = await app.inject({ method: "GET", - url: `/v1/oauth/twitch/callback?code=test-code&state=${encodeURIComponent(stateToken)}`, + url: `/v1/oauth/twitch/callback?code=test-code&state=${encodeURIComponent(flow.state)}`, + headers: { cookie: flow.cookie }, }); const accountId = callbackResponse.json().account.id as string; @@ -1210,11 +1293,12 @@ describe("Heimdall service", () => { returnTo: "https://streampixels.gamecult.org/auth/connect", }, }); - const stateToken = startResponse.json().stateToken as string; + const flow = await launchFlow(app, startResponse.json()); const callbackResponse = await app.inject({ method: "GET", - url: `/v1/oauth/twitch/callback?code=test-code&state=${encodeURIComponent(stateToken)}`, + url: `/v1/oauth/twitch/callback?code=test-code&state=${encodeURIComponent(flow.state)}`, + headers: { cookie: flow.cookie }, }); const accountId = callbackResponse.json().account.id as string; @@ -1276,10 +1360,11 @@ describe("Heimdall service", () => { }); apps.push(app); - const stateToken = await startDiscordSignIn(app); + const flow = await startDiscordSignIn(app); const callbackResponse = await app.inject({ method: "GET", - url: `/v1/oauth/discord/callback?code=test-code&state=${encodeURIComponent(stateToken)}`, + url: `/v1/oauth/discord/callback?code=test-code&state=${encodeURIComponent(flow.state)}`, + headers: { cookie: flow.cookie }, }); expect(callbackResponse.statusCode).toBe(201); const evaluationsAtSignIn = evaluations; @@ -1355,17 +1440,136 @@ describe("Heimdall service", () => { expect(urls).toEqual([]); }); + // Targets made only of whitespace, format characters, controls and the invisible fillers that render as nothing. + const BLANK_TARGETS = [ + " ", "\t", "\n ", "\u200B", "\u00A0\uFEFF", + "\u2800", "\u3164", "\u115F", "\u1160", "\uFFA0", "\u034F", "\u0000", "\u0007", " \u2800\u3164 ", + // Marks, private-use, unassigned and lone-surrogate code points, and the symbols that read as nothing: none is a letter or a number. + "\u0300", "\uE000", "\u0378", "\uD800", "\u{16FE4}", "\u{1D159}", "\u{F0000}", "\u0300\uE000 ", + ]; + // A target is usable when it holds a letter or a number that is not an invisible filler. + const NAMING_TARGETS = ["creator-1", " creator-1 ", "Framgång", "42", "\u2800a\u3164", "\u3164\u0300x"]; + + describe("a connect start that names a connection target is the app backend's", () => { + // The target is app-backend authority: the StreamPixels backend proves the creator-manage session and states the + // creator it started the connect for. Anyone else naming {creator, X} would have X's connector rebound to their + // own OAuth account at StreamPixels' redeem. + const returnTo = "https://streampixels.gamecult.org/auth/connect"; + const managed = ["twitch", "youtube", "joystick"] as const; + const startFor = (app: FastifyInstance, provider: string, connection: unknown, headers: Record = {}) => + app.inject({ + method: "POST", + url: `/v1/oauth/${provider}/start`, + headers, + payload: { appSlug: "streampixels", mode: "connect", returnTo, connection }, + }); + const own = { "x-heimdall-app-secret": "streampixels-secret" }; + + it.each(managed)("%s: a creator target is refused without the app's own secret and minted for it", async (provider) => { + const config = createTestConfig(); + const app = await buildApp({ config }); + apps.push(app); + const creator = { kind: "creator", targetId: "victim-creator" }; + + for (const headers of [{}, { "x-heimdall-app-secret": "repixelizer-secret" }, { "x-heimdall-app-secret": "wrong" }]) { + const refused = await startFor(app, provider, creator, headers); + expect([refused.statusCode, refused.json()]).toEqual([401, { error: "app_auth_required" }]); + expect(refused.body).not.toContain("authorizationUrl"); + } + const started = await startFor(app, provider, creator, own); + expect(started.statusCode).toBe(201); + const verified = verifyJwt(stateOf(started.json()), getPublicKey(app)); + expect(verified.valid && verified.payload).toEqual(expect.objectContaining({ connection: expect.objectContaining(creator) })); + + // A direct caller (the command plane hands startOAuthFlow its own) is held to the slug too. + const input = { appSlug: "streampixels" as const, mode: "connect" as const, returnTo, connection: { kind: "creator" as const, targetId: "victim-creator" } }; + const foreign = resolveAppCaller(config, "repixelizer", { "x-heimdall-app-secret": "repixelizer-secret" }); + expect((await startOAuthFlow(getHeimdallRuntimeContext(app), provider, foreign, input)).statusCode).toBe(401); + expect((await startOAuthFlow(getHeimdallRuntimeContext(app), provider, null, input)).statusCode).toBe(401); + }); + + it.each(["twitch", "youtube"] as const)("%s: any connection kind needs the app's secret, not only creator", async (provider) => { + const app = await buildApp({ config: createTestConfig() }); + apps.push(app); + const account = { kind: "account", targetId: "victim-account" }; + + const refused = await startFor(app, provider, account); + expect([refused.statusCode, refused.json()]).toEqual([401, { error: "app_auth_required" }]); + expect((await startFor(app, provider, account, own)).statusCode).toBe(201); + }); + + it.each(managed)("%s: a blank target is refused even for the app, whatever the blank is made of", async (provider) => { + const app = await buildApp({ config: createTestConfig() }); + apps.push(app); + + for (const kind of ["creator", "account"]) { + for (const targetId of BLANK_TARGETS) { + const refused = await startFor(app, provider, { kind, targetId }, own); + expect([refused.statusCode, refused.json().error], `${kind} ${JSON.stringify(targetId)}`).toEqual([400, "invalid_connection_target"]); + expect(refused.body).not.toContain("authorizationUrl"); + } + } + for (const targetId of NAMING_TARGETS) { + expect((await startFor(app, provider, { kind: "creator", targetId }, own)).statusCode, JSON.stringify(targetId)).toBe(201); + } + }); + + it.each(managed)("%s: a blank target without the app's secret gets 401, not the 400 that would tell a stranger what the gate checks", async (provider) => { + const app = await buildApp({ config: createTestConfig() }); + apps.push(app); + + for (const headers of [{}, { "x-heimdall-app-secret": "wrong" }]) { + for (const targetId of [" ", "\u2800"]) { + const refused = await startFor(app, provider, { kind: "creator", targetId }, headers); + expect([refused.statusCode, refused.json()], JSON.stringify(targetId)).toEqual([401, { error: "app_auth_required" }]); + } + } + }); + + it("the callback mint holds a blank creator target to the same bar", () => { + const streampixels = builtInAppProfiles.streampixels!; + for (const targetId of BLANK_TARGETS) { + expect(callbackMint(streampixels, "joystick", "connect", { kind: "creator", targetId }), JSON.stringify(targetId)).toBe("refused"); + } + // A visible character among the blanks names a target. + expect(callbackMint(streampixels, "joystick", "connect", { kind: "creator", targetId: "\u2800a\u3164" })).toBe("custody_only"); + for (const targetId of NAMING_TARGETS) { + expect(callbackMint(streampixels, "joystick", "connect", { kind: "creator", targetId }), JSON.stringify(targetId)).toBe("custody_only"); + } + }); + }); + describe("joystick connect", () => { const creator = { kind: "creator", targetId: "creator-1" }; async function connect(app: FastifyInstance, extra: Record = { connection: creator }) { const start = await app.inject({ method: "POST", url: "/v1/oauth/joystick/start", + headers: { "x-heimdall-app-secret": "streampixels-secret" }, payload: { appSlug: "streampixels", mode: "connect", returnTo: "https://streampixels.gamecult.org/auth/connect", ...extra }, }); return start; } + it("gates a connect start that names a creator on the app's own secret: none and a foreign app's are 401, its own is 201", async () => { + const config = createTestConfig(); + const app = await buildApp({ config }); + apps.push(app); + const body = { appSlug: "streampixels", mode: "connect", returnTo: "https://streampixels.gamecult.org/auth/connect", connection: creator }; + const start = (headers: Record) => app.inject({ method: "POST", url: "/v1/oauth/joystick/start", headers, payload: body }); + + for (const headers of [{}, { "x-heimdall-app-secret": "repixelizer-secret" }, { "x-heimdall-app-secret": "wrong" }]) { + const refused = await start(headers); + expect([refused.statusCode, refused.json()]).toEqual([401, { error: "app_auth_required" }]); + } + expect((await start({ "x-heimdall-app-secret": "streampixels-secret" })).statusCode).toBe(201); + + // A direct caller (the command plane hands startOAuthFlow its own) is held to the slug too. + const input = { appSlug: "streampixels" as const, mode: "connect" as const, returnTo: body.returnTo, connection: { kind: "creator" as const, targetId: "creator-1" } }; + const foreign = resolveAppCaller(config, "repixelizer", { "x-heimdall-app-secret": "repixelizer-secret" }); + expect((await startOAuthFlow(getHeimdallRuntimeContext(app), "joystick", foreign, input)).statusCode).toBe(401); + }); + it.each([ ["no connection", {}, "creator_connection_required"], ["an account connection", { connection: { kind: "account", targetId: "victim-1" } }, "creator_connection_required"], @@ -1377,7 +1581,7 @@ describe("Heimdall service", () => { expect(start.statusCode).toBe(400); expect(start.json().error).toBe(error); expect(start.json().authorizationUrl).toBeUndefined(); - expect(start.json().stateToken).toBeUndefined(); + expect(start.json()).not.toHaveProperty("stateToken"); }); it.each([ @@ -1393,14 +1597,15 @@ describe("Heimdall service", () => { apps.push(app); const keys = createRuntimeKeyMaterial({ ...config, bootstrapSigningPrivateKeyOnMissing: false }); const calls = stubJoystick({ channel_id: "chan-forged", username: "deru" }); - const stateToken = (await connect(app)).json().stateToken as string; - const verified = verifyJwt(stateToken, keys.publicKey); + const flow = await launchFlow(app, (await connect(app)).json()); + const verified = verifyJwt(flow.state, keys.publicKey); expect(verified.valid).toBe(true); const forged = signJwt({ ...(verified as { payload: Record }).payload, connection }, keys); const callback = await app.inject({ method: "GET", url: `/v1/oauth/joystick/callback?code=c&state=${encodeURIComponent(forged)}`, + headers: { cookie: flow.cookie }, }); expect(callback.statusCode).toBeGreaterThanOrEqual(400); expect(calls).toEqual([]); @@ -1432,9 +1637,11 @@ describe("Heimdall service", () => { handoff: { kind: "backend_callback", attemptId: "attempt-js-1", callbackUrl }, }); expect(start.statusCode).toBe(201); + const flow = await launchFlow(app, start.json()); const callback = await app.inject({ method: "GET", - url: `/v1/oauth/joystick/callback?code=c&state=${encodeURIComponent(start.json().stateToken as string)}`, + url: `/v1/oauth/joystick/callback?code=c&state=${encodeURIComponent(flow.state)}`, + headers: { cookie: flow.cookie }, }); expect(callback.statusCode).toBeLessThan(300); @@ -1453,7 +1660,7 @@ describe("Heimdall service", () => { apps.push(app); const start = await connect(app); expect(start.statusCode).toBe(201); - const url = new URL(start.json().authorizationUrl as string); + const url = await providerRedirect(app, start.json()); expect(`${url.origin}${url.pathname}`).toBe("https://joystick.tv/api/oauth/authorize"); expect(url.searchParams.get("client_id")).toBe("joystick-client"); expect(url.searchParams.get("scope")).toBe("identity:read stream:read chat:read followers:read subscribers:read"); @@ -1467,10 +1674,11 @@ describe("Heimdall service", () => { const app = await buildApp({ config: createTestConfig(), store }); apps.push(app); stubJoystick({ channel_id: "deru-chan", username: "deru" }); - const stateToken = (await connect(app)).json().stateToken as string; + const flow = await launchFlow(app, (await connect(app)).json()); const connected = await app.inject({ method: "GET", - url: `/v1/oauth/joystick/callback?code=a&state=${encodeURIComponent(stateToken)}`, + url: `/v1/oauth/joystick/callback?code=a&state=${encodeURIComponent(flow.state)}`, + headers: { cookie: flow.cookie }, }); const accountId = connected.json().account.id as string; const before = await store.findStoredLinkedIdentityForAccount(accountId, "joystick"); @@ -1518,14 +1726,15 @@ describe("Heimdall service", () => { apps.push(app); const keys = createRuntimeKeyMaterial({ ...config, bootstrapSigningPrivateKeyOnMissing: false }); const calls = stubJoystick({ channel_id: "chan-forged", username: "deru" }); - const stateToken = (await connect(app)).json().stateToken as string; - const verified = verifyJwt(stateToken, keys.publicKey); + const flow = await launchFlow(app, (await connect(app)).json()); + const verified = verifyJwt(flow.state, keys.publicKey); expect(verified.valid).toBe(true); const forged = signJwt({ ...(verified as { payload: Record }).payload, mode }, keys); const callback = await app.inject({ method: "GET", url: `/v1/oauth/joystick/callback?code=c&state=${encodeURIComponent(forged)}`, + headers: { cookie: flow.cookie }, }); expect(callback.statusCode).toBeGreaterThanOrEqual(400); expect(callback.body).not.toContain("viewer_access"); @@ -1542,11 +1751,12 @@ describe("Heimdall service", () => { const app = await buildApp({ config: createTestConfig(), store }); apps.push(app); const calls = stubJoystick({ channel_id: "chan-9", username: "deru", nickname: "Deru!", photo_url: "https://img/x.png" }); - const stateToken = (await connect(app)).json().stateToken as string; + const flow = await launchFlow(app, (await connect(app)).json()); const callback = await app.inject({ method: "GET", - url: `/v1/oauth/joystick/callback?code=the-code&state=${encodeURIComponent(stateToken)}`, + url: `/v1/oauth/joystick/callback?code=the-code&state=${encodeURIComponent(flow.state)}`, + headers: { cookie: flow.cookie }, }); expect(callback.statusCode).toBeLessThan(300); @@ -1575,10 +1785,11 @@ describe("Heimdall service", () => { const app = await buildApp({ config: createTestConfig(), store }); apps.push(app); stubJoystick({ channel_id: "chan-9", username: "deru" }); - const stateToken = (await connect(app)).json().stateToken as string; + const flow = await launchFlow(app, (await connect(app)).json()); const callback = await app.inject({ method: "GET", - url: `/v1/oauth/joystick/callback?code=c&state=${encodeURIComponent(stateToken)}`, + url: `/v1/oauth/joystick/callback?code=c&state=${encodeURIComponent(flow.state)}`, + headers: { cookie: flow.cookie }, }); const row = await store.findStoredLinkedIdentityForAccount(callback.json().account.id as string, "joystick"); expect(row?.displayName).toBe("deru"); @@ -1589,10 +1800,11 @@ describe("Heimdall service", () => { const app = await buildApp({ config: createTestConfig(), store }); apps.push(app); stubJoystick({ username: "deru" }); - const stateToken = (await connect(app)).json().stateToken as string; + const flow = await launchFlow(app, (await connect(app)).json()); const callback = await app.inject({ method: "GET", - url: `/v1/oauth/joystick/callback?code=c&state=${encodeURIComponent(stateToken)}`, + url: `/v1/oauth/joystick/callback?code=c&state=${encodeURIComponent(flow.state)}`, + headers: { cookie: flow.cookie }, }); expect(callback.statusCode).toBeGreaterThanOrEqual(400); expect(await store.findStoredLinkedIdentity("joystick", "undefined")).toBeNull(); @@ -1787,11 +1999,11 @@ describe("error answers never echo an input", () => { const app = await buildApp({ config: createTestConfig(), oauthRuntimes: { discord: failingDiscordRuntime() } }); apps.push(app); - const stateToken = await startDiscordSignIn(app); + const flow = await startDiscordSignIn(app); const response = await app.inject({ method: "GET", - url: `/v1/oauth/discord/callback?code=test-code&state=${encodeURIComponent(stateToken)}`, - headers: { accept: "text/html" }, + url: `/v1/oauth/discord/callback?code=test-code&state=${encodeURIComponent(flow.state)}`, + headers: { cookie: flow.cookie, accept: "text/html" }, }); expect(response.headers["content-type"]).toContain("text/html"); @@ -1823,9 +2035,11 @@ describe("error answers never echo an input", () => { }, }); expect(start.statusCode).toBe(201); + const flow = await launchFlow(app, start.json()); const response = await app.inject({ method: "GET", - url: `/v1/oauth/discord/callback?code=test-code&state=${encodeURIComponent(start.json().stateToken as string)}`, + url: `/v1/oauth/discord/callback?code=test-code&state=${encodeURIComponent(flow.state)}`, + headers: { cookie: flow.cookie }, }); expect(response.statusCode).toBe(502); @@ -1843,16 +2057,16 @@ describe("the relayed provider error", () => { const injected = `"\\\u0007é${"x".repeat(300)}`; const allowed = /^[\x20-\x21\x23-\x5b\x5d-\x7e]*$/; - function providerErrorUrl(stateToken: string): string { - const query = new URLSearchParams({ state: stateToken, error: `${"e".repeat(100)}\u0000`, error_description: injected }); - return `/v1/oauth/discord/callback?${query.toString()}`; + function providerErrorRequest(flow: LaunchedFlow) { + const query = new URLSearchParams({ state: flow.state, error: `${"e".repeat(100)}\u0000`, error_description: injected }); + return { method: "GET" as const, url: `/v1/oauth/discord/callback?${query.toString()}`, headers: { cookie: flow.cookie } }; } it("is printable and bounded in the JSON answer", async () => { const app = await buildApp({ config: createTestConfig() }); apps.push(app); - const response = await app.inject({ method: "GET", url: providerErrorUrl(await startDiscordSignIn(app)) }); + const response = await app.inject(providerErrorRequest(await startDiscordSignIn(app))); expect(response.statusCode).toBe(400); const { providerError, providerErrorDescription } = response.json() as Record; @@ -1866,11 +2080,8 @@ describe("the relayed provider error", () => { const app = await buildApp({ config: createTestConfig() }); apps.push(app); - const response = await app.inject({ - method: "GET", - url: providerErrorUrl(await startDiscordSignIn(app)), - headers: { accept: "text/html" }, - }); + const request = providerErrorRequest(await startDiscordSignIn(app)); + const response = await app.inject({ ...request, headers: { ...request.headers, accept: "text/html" } }); expect(response.headers["content-type"]).toContain("text/html"); expect(response.body.match(/