@idp.global/sdk 19.3.0 → 19.5.0

package/readme.md

@@ -13,6 +13,7 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 | Runtime | Import | What it does |
 | --- | --- | --- |
 | Browser | `@idp.global/sdk/browser` | SSO client, JWT and refresh-token storage, login redirects, logout, transfer-token exchange, and typed request shortcuts for user, organization, billing, OIDC, and admin flows. |
+| Browser, relying-party sign-in only | `@idp.global/sdk/browser/bearer` | `RelyingPartyBearerClient` and the bearer contract types, without the rest of the browser client; for applications whose server runs `@idp.global/sdk/relyingparty` in bearer mode. |
 | Server | `@idp.global/sdk/server` | NoSQL-backed account store, scrypt password hashing, local/idp.global account authentication, a server-side typed-socket client for idp.global password login, and confidential OIDC introspection. |
 | Relying party | `@idp.global/sdk/relyingparty` | The OIDC relying-party session layer: authorization code flow with PKCE on `openid-client`, login attempts and HttpOnly cookie sessions with CSRF tokens on NoSQL, sealed provider tokens rotated under a cross-replica lock, live organization authority, HTTP login routes, a TypedRouter actor scope and TypedSocket session binding. |
 
@@ -151,6 +152,7 @@ await idp.logout();
 | `getTransferTokenAndSwitchToLocation()` | Request a transfer token and navigate to the same configured target with `transfertoken` attached. |
 | `processTransferToken()` | Consume a `transfertoken` from the current URL and refresh local auth state. |
 | `logout()` | Revoke and clear the current login flow. |
+| `RelyingPartyBearerClient` | The bearer hand-off client of a relying party's own `web` and `popup` logins: PKCE start URL, the redirect and popup receivers, claim, refresh single-flight across tabs through Web Locks, and logout, with the token pair in an application storage adapter (`IRelyingPartyBearerTokenStorage`). `createPkce()` and `claimCode(pkce, code)` claim a code delivered another way, such as a device pairing, without a window. See [Bearer Hand-off](#bearer-hand-off). |
 
 ### Typed Request Shortcuts
 
@@ -381,6 +383,43 @@ in that application only once the reused answer expires — up to the configured
 TTL — while ending the login session in the application drops its reused answers
 at once. A failure to observe is never reused.
 
+idp.global answers an introspection inactive for a login that ended as well as
+for a membership that is gone. Only a refresh tells them apart: idp.global
+refuses the refresh of an ended login (`invalid_grant`), and also when the user
+can no longer sign in or an organization of the login is no longer active, but
+rotates the token of a member who was removed from one organization. So an
+inactive answer is not yet a refusal. `AuthorityObserver` first rotates the
+session's provider token (`liveProviderToken(sessionId, principalId,
+{ rejectedAccessToken })`) and introspects again with the new token:
+
+- A refused rotation is the ended login. It ends the session
+  (`refresh_token_refused`, through `onSessionEnded`) and throws
+  `AuthorityTokenError` `authority_login_required`. No membership is refused.
+- Only an inactive answer on a token from a rotation that started after the
+  observation's own inactive answer throws `AuthorityRefusedError`
+  `idp_membership_absent`. The source marks such a token
+  `rotatedAfterRejection`, and the observer orders inactive answers and
+  rotation starts by one sequence; it compares no tokens.
+- Every other inactive answer throws `authority_unavailable` and keeps nothing:
+  when the rotation started before the answer, when another replica holds the
+  session's rotation, when a rotation was already running, and when the session
+  has no refresh token.
+- An observer rotates a session's token for an inactive answer at most once per
+  `AUTHORITY_FORCED_REFRESH_INTERVAL_MS` (60 s). An inactive answer within that
+  time of the rotation is `authority_unavailable`, as is every one while a
+  rotation that failed stands. After it the next inactive answer rotates and
+  decides.
+- A deactivated application is not a refusal either. idp.global answers its
+  refresh with `invalid_client`, which reads as `authority_unavailable`.
+- idp.global counts refused token requests per client: after 10 in 10 minutes
+  without a successful one in between, it blocks the client's token requests
+  for 15 minutes. A rotation only refuses earlier what the session's next
+  refresh would refuse, once per session.
+- A token source of an application's own (`IAuthorityTokenSource`) must rotate
+  when it is given `rejectedAccessToken` and mark the token. One that never
+  rotates or marks, as a 19.3.0 source does, can never refuse: its inactive
+  answers are `authority_unavailable`.
+
 ### Server-held OIDC UserInfo
 
 Use `OidcUserInfoClient` to obtain current profile and organization picker data
@@ -562,7 +601,9 @@ What it does:
   idpOrganizationId })` introspects the organization with the session's live
   token and projects the role keys through the application's table. It answers
   a grant or throws `AuthorityRefusedError` (with `firstRefusal` once per
-  transition, for an audit trail) or `AuthorityTokenError`.
+  transition, for an audit trail) or `AuthorityTokenError`. An inactive answer
+  rotates the token before it refuses, and a login that ended at idp.global ends
+  the session (`authority_login_required`); see the authority contract above.
 - **Transports**: `createActorScope()` gives a TypedRouter request scope
   (`addRequestScope`) that runs every dispatch as the actor its trusted local
   data names. `RelyingPartySocketBinding` registers a TypedSocket connection
@@ -573,6 +614,13 @@ What it does:
 Nothing runs on a timer, and no token, cookie or sealed value ever reaches a
 log line or an error message.
 
+`onSessionEnded` names the session, the reason and whether this call revoked
+it (`revokedHere`); when it did, it also names the session's principal
+(`principalId`), and when the session was over already it does not.
+`onProviderSessionOpened` receives the session and, for a bearer login, its
+`delivery`: the client kind, the return target and the client's `state`. A
+cookie login has no `delivery`.
+
 Application hooks never stand in the way of that cleanup. A throwing (or
 rejecting) `onSessionEnded` or `onEvent` is reported as a `hook_failed` event —
 `onEvent`'s own failure on `console.error` — and the provider tokens go back
@@ -583,8 +631,9 @@ an https `publicOrigin`; on http the constructor refuses them, because browsers
 would silently drop those cookies.
 
 **Adopting existing session data.** The persisted fields and index declarations
-are those nevermind.finance has stored since mainapp 0b693cb. An application
-that already holds such collections binds the models to them and passes its own
+are those nevermind.finance has stored since mainapp 0b693cb, and the session
+model adds an `expiresAt` index, built on first use. An application that
+already holds such collections binds the models to them and passes its own
 cookie names and CSRF label, so live sessions and sealed tokens keep working:
 
 ```ts
@@ -604,6 +653,49 @@ A deployment without a provider (`provider` omitted) keeps the same session
 store for sessions it opens itself with `openSession({ principalId })`, for
 example after a local password check.
 
+Nothing runs on a timer. A login start first removes up to 100 login attempts
+and up to 100 sessions that ended more than an hour ago, and a bearer login
+start also its bearer hand-offs and token generations; `openBearerHandoff`
+removes the bearer state and the sessions, `openSession` the sessions only.
+Removing an ended session fires no end hook and calls no provider.
+
+**Deleting an account.** The sweeps above run only when a session is created,
+so an ended session can stay stored for long on a quiet service.
+`eraseSessionsOfPrincipal(principalId)` removes everything of one principal at
+once: an application calls it when it deletes the account, after its own
+erasers and before its user record, so a failure can be retried.
+
+```ts
+await accountData.eraseAll(userId); // the application's own records
+const erasure = await sessions.eraseSessionsOfPrincipal(userId);
+await users.delete(userId);
+```
+
+- It ends every session of the principal that is not revoked yet, an expired
+  one too, as `endSession` does: its tokens stop working at once,
+  `onSessionEnded` fires (reason `logout`, with `principalId`), and its
+  provider tokens go back to idp.global, which a deleted row could no longer
+  do.
+- Then it deletes every session row of the principal, live or ended, and with
+  each the login attempt a provider session came out of and, in bearer mode,
+  its hand-offs (claimed or not) and its token generations. The session row
+  goes last: it is the only link from the principal to the others, so an
+  erase that fails half way leaves a retry everything it needs.
+- It answers what it removed (`IRelyingPartySessionsErasure`: `endedSessions`,
+  `deletedSessions`, `deletedLoginAttempts`, `deletedBearerHandoffs`,
+  `deletedBearerTokens`); a second call finds nothing.
+- A session opened by a login already past `admit` when the erase runs is not
+  covered. It keeps the principal id until it expires and a later sweep
+  removes it. A second `eraseSessionsOfPrincipal(principalId)`, run after the
+  user record is deleted, removes it. A token generation issued by a refresh
+  already under way is not covered either; it outlives its session row as
+  described below.
+- A token generation, and for at most a minute a hand-off, outlives the row
+  of its session when that session was revoked and swept before its expiry.
+  It holds only hashes, the session id and times, the bearer sweep removes it
+  an hour after the session would have expired, and the erase cannot
+  attribute it to the principal any more.
+
 **Building before the database connects.** `db` may be a function that answers
 the database once it exists. It is called on every use of a model, the way
 `@Collection(() => db)` resolves it, and never while the models,
@@ -795,14 +887,17 @@ Tokens and their ends:
   bearer login sweeps it (`handoff_unclaimed`). Each answers 400
   `invalid_bearer_handoff`; reuse is also reported as a
   `bearer_credential_reused` event.
-- A bearer session is a provider login like a cookie session: `onSessionEnded`,
-  `endSessionsOfPrincipal` and `AuthorityObserver` apply as they are. A refresh
+- A bearer login is a provider login like a cookie session: `onSessionEnded`,
+  `endSessionsOfPrincipal` and `AuthorityObserver` apply as they are. (A
+  session opened by pairing a device has no provider login of its own; see
+  "Pairing a device" below.) A refresh
   rotates the provider token when it is due and ends the session when
   idp.global has ended the login (`invalid_bearer_grant`); an unreachable
   provider answers 503 `authority_unavailable` and spends nothing. Until then
   an access token works for its remaining lifetime. An application that must
   see an idp.global logout sooner observes authority per request
-  (`authority.observe({ loginSessionId: live.session.id, … })`).
+  (`authority.observe({ loginSessionId: live.session.id, … })`), which ends the
+  session as soon as idp.global has ended the login.
 
 The four API routes answer CORS, including the preflight, for the popup
 origins exactly and never allow credentials; every other origin gets no CORS
@@ -815,23 +910,266 @@ The client side:
   `Referrer-Policy: no-referrer`.
 - A popup client opens the login with `window.open` (without `noopener`) and
   accepts only the message of the popup it opened, from the relying party's
-  public origin, with its own `state`:
+  public origin, with its own `state`. The opener page must keep its opener
+  link to the popup: `Cross-Origin-Opener-Policy: same-origin` severs it, while
+  `same-origin-allow-popups` keeps it.
+- Every client claims a code once and never retries a claim or a refresh. Its
+  refreshes run one at a time across everything that shares the pair, and a
+  rotated pair is stored, all of it at once, before its access token is first
+  used: a pair that is lost after the relying party rotated it cannot be
+  recovered, and its spent refresh token coming back ends the session. Native
+  clients implement this side themselves.
+
+The HTTP answers are exported as types (`IRelyingPartyBearerTokenAnswer`,
+`IRelyingPartyBearerSessionAnswer`, `IRelyingPartyBearerLogoutAnswer`,
+`IRelyingPartyBearerErrorAnswer` with `TRelyingPartyBearerErrorCode`, and the
+popup's `IRelyingPartyBearerMessage`), and so are the requests:
+`IRelyingPartyBearerLoginQuery` (the `bearer/login` query by its parameter
+names), `IRelyingPartyBearerClaimRequest` (`{ code, codeVerifier }`),
+`IRelyingPartyBearerRefreshRequest` (`{ refreshToken }`) and
+`IRelyingPartyBearerLogoutRequest` (`{ refreshToken? }`). They come from a
+module that imports nothing, so `@idp.global/sdk/browser` and
+`@idp.global/sdk/browser/bearer` share them with the server.
+
+**The browser client.** `RelyingPartyBearerClient` from `@idp.global/sdk/browser`
+is that client side for `web` and `popup` logins. The application owns where the
+token pair lives: it passes a storage adapter, typically over IndexedDB, and the
+client keeps nothing of its own across reloads.
+
+```ts
+import { RelyingPartyBearerClient, type IRelyingPartyBearerTokenStorage } from '@idp.global/sdk/browser';
+
+const storage: IRelyingPartyBearerTokenStorage = {
+  get: () => tokenStore.get('bearer'), // the stored pair, or null
+  set: (tokens, { signal }) => tokenStore.put('bearer', tokens, { signal }), // resolves once durable, writes nothing once aborted
+  clear: ({ signal }) => tokenStore.delete('bearer', { signal }), // resolves once durable, removes nothing once aborted
+};
+const client = new RelyingPartyBearerClient({ origin: 'https://app.example', storage });
+
+// web: start, and receive on the return target page
+const login = await client.createLogin({ clientKind: 'web', returnTarget: '/signed-in' });
+sessionStorage.setItem('bearer-login', JSON.stringify(login));
+location.assign(login.url);
+// … on /signed-in
+const result = await client.completeRedirectLogin(JSON.parse(sessionStorage.getItem('bearer-login') ?? 'null'));
+// result.tokens is the stored pair; result.previousSession says what became of the one it replaced
+
+// popup: make the login first, open it in the click handler itself
+const popupLogin = await client.createLogin({ clientKind: 'popup', returnTarget: 'https://workspace.example' });
+button.onclick = () => client.openPopupLogin(popupLogin).then(showWorkspace, showSignInError);
+
+// every call
+const accessToken = await client.accessToken(); // null without a session
+// after the relying party refused one
+await client.refresh(rejectedAccessToken);
+await client.logout();
+```
+
+- `createLogin` makes the verifier, its S256 challenge and the state from 32
+  random bytes each and answers them with the start URL. The pending login is
+  the application's to keep until it comes back; it holds the verifier.
+- `completeRedirectLogin(login)` answers `null` on a page without a delivery.
+  It removes `code`, `error` and `state` from the address first, then refuses a
+  state that is not the login's (`state_mismatch`, nothing claimed) and claims
+  the code once (`already_received` after that).
+- A received login (`IRelyingPartyBearerLoginResult`) replaces the stored pair.
+  After the claim, under the lock, the client stores the new pair and then
+  ends the session of the pair it replaced through `bearer/logout`, with that
+  pair held in memory. `previousSession` is `no_previous_session`,
+  `same_session` (nothing to end), `previous_session_ended`, or
+  `previous_session_not_revoked` with `previousSessionError`. In the last case
+  that session lives on at the relying party until it expires. A failed claim
+  leaves the stored pair and its session as they were.
+- `createPkce()` makes a verifier and its S256 challenge from 32 random bytes,
+  and `claimCode(pkce, code)` claims a code bound to that challenge which
+  reached the client another way than its own login, such as a device pairing
+  ("Pairing a device" below). It is received like a login: one
+  claim, never retried, under `requestTimeoutMs`, and the pair replaces the
+  stored one under the lock (`IRelyingPartyBearerLoginResult`). A pair is
+  claimed with once: a second call with it, after a failed claim as well, is
+  `already_received` and sends nothing. A pair that is not one (a malformed
+  verifier, a challenge that is not its S256) or a code that is not text
+  throws before anything is sent. Neither needs a window.
+- `openPopupLogin(login, { timeoutMs?, signal?, windowFeatures? })` calls
+  `window.open` before it returns, so a browser lets it through within the
+  click. It takes only a message from the relying party's exact origin, from
+  this popup, of `RELYING_PARTY_BEARER_MESSAGE_TYPE` and with the login's
+  state; it ignores every other. It ends with `popup_blocked`, `popup_closed`,
+  `popup_timeout` (10 minutes by default) or the signal's reason.
+- `accessToken()` answers the stored access token while it is fresh, and
+  otherwise rotates it first. `refreshSkewMs` (one minute by default, at most
+  half the lifetime) is the margin. `refresh(rejectedAccessToken?)` rotates now.
+  Both answer `null`, and clear the storage, once the session is over
+  (`invalid_bearer_grant`).
+- Every refresh, logout and store of a claimed pair holds one Web Lock
+  (`lockName`; by default per origin), so the tabs of an origin rotate one at a
+  time. Inside the lock the pair is read from the storage again. A pair another
+  tab rotated is used as it is, so concurrent refreshes make one request. A
+  rotated pair is stored before the lock is released and before its access
+  token is answered; when `storage.set` fails, the new pair is never used and
+  the session is lost.
+- `requestTimeoutMs` (30 seconds by default, more than 0 and at most two
+  minutes; any other value throws) is the deadline of each operation: the
+  claim of a login's code, a refresh with the write of its pair, the store of a
+  claimed pair with the revoke of the one it replaced, and a logout. When it
+  fires, the request is aborted, the signal a storage write got aborts, an
+  answer that still arrives is dropped unstored, the lock is released for the other
+  tabs and the call fails with `request_failed`; a login whose pair is stored
+  by then stands, with `previous_session_not_revoked`. A claim or refresh the
+  relying party carried out before the deadline is lost with its answer. A
+  timed-out claim fails the login, and the user signs in again; after a lost
+  refresh, the next refresh ends the session (`refresh_token_reused`) and the
+  user signs in again. Strict rotation costs that.
+- `storage.set(tokens, { signal })` and `storage.clear({ signal })` either
+  honour the signal, so a write it aborted is not made and the call rejects,
+  or complete synchronously, as an adapter over `localStorage` does. The lock
+  is never held past the deadline, so an adapter that ignores the signal can
+  finish a write after another tab took the lock. A late `set` overwrites what
+  that tab stored or cleared, and the session can then end
+  (`refresh_token_reused`); a late `clear` removes the pair that tab stored.
+  Either way the user signs in again.
+- `logout()` clears the storage and then ends the session at the relying party
+  with the pair it held. When that request fails, is refused or reaches the
+  deadline, it throws `session_not_revoked` with the request's error as its
+  `cause`: the device is signed out, the session may live on at the relying
+  party until it expires, and the application can tell the user they are
+  signed out on this device only. A deadline that fires before the storage is
+  cleared throws `request_failed` and leaves the pair.
+- Failures are `RelyingPartyBearerClientError`s with a `code`. A refusal of the
+  relying party is `request_refused` with its `status` and `answerError`; an
+  unreachable one is `request_failed`, which leaves the stored pair as it was,
+  except in `logout()` (`session_not_revoked`).
+- The client needs the Web Locks API and Web Crypto, which a browser offers
+  only in a secure context, and has no fallback for either. Every request is
+  sent without credentials, cache or redirects.
+- It runs in a Manifest V3 extension's service worker. That was checked in
+  Chromium 149: a module service worker imported `@idp.global/sdk/browser/bearer`
+  and ran `createPkce`, `claimCode` against the bearer routes and a rotation
+  through `accessToken()`, with the lock held at each write. Other browsers'
+  extension workers were not checked. The extension needs a host permission
+  for the relying party's origin: the routes answer CORS for popup origins
+  only, so without one the browser's preflight is refused and the claim fails
+  with `request_failed` before it is sent.
+
+**Pairing a device.** A person who is signed in can sign a second device of
+theirs in without a login on it, such as a TV or a browser extension. The
+device makes a PKCE pair and shows the application its challenge, for example
+together with a short code that the person confirms in a session where they
+are signed in. The application's server then opens the device's session from
+the session that confirmed:
+
+```ts
+// the device polls; the person has confirmed the pairing in one of their sessions
+const { code, expiresAt } = await sessions.openBearerHandoff({
+  openerSessionId: pairing.confirmedInSessionId, // written by the confirm handler, never taken from the device
+  codeChallenge: pairing.codeChallenge, // the device's S256 challenge
+  maxAgeSeconds: 8 * 60 * 60, // optional: 1 to sessionMaxAgeSeconds, which is the default
+});
+// answer the poll with `code`; the device claims it at POST /auth/bearer/claim with its verifier
+```
+
+```ts
+// the device, with the browser client (a native client claims at bearer/claim itself)
+const pkce = await client.createPkce();
+await showPairingRequest(pkce.codeChallenge);
+const result = await client.claimCode(pkce, await pollForCode());
+```
+
+- **The opener.** `openerSessionId` must name a live provider login: not ended
+  and not expired, with an active principal and a provider login of its own
+  (`idpSubject`). A session from `openSession` or from `openBearerHandoff`
+  does not qualify, so a paired device cannot pair another one. Any other
+  opener throws `RelyingPartyError('invalid_handoff_opener')` (400). A
+  challenge that is not one throws `invalid_bearer_request`, and a
+  `maxAgeSeconds` outside 1 to `sessionMaxAgeSeconds` throws a `RangeError`.
+  Nothing is stored for any of these. Without `bearer` the call throws
+  `login_method_unavailable`; in bearer-only mode it works, with a bearer login
+  as the opener. The check reads this relying party's state of the opener;
+  observe authority with the opener first to ask idp.global itself.
+- **The pairing record.** It keeps the id of the session that confirmed,
+  written by the confirm handler and never taken from the device. That opener
+  must still be live when the poll delivers the code. Open one hand-off per
+  confirmed pairing, in the poll that delivers it; then the code is never
+  stored, and only the public challenge sits in the record. Only server code
+  opens a hand-off, and no route does. Guard the confirmation against a code
+  the person did not start themselves (RFC 8628 §5.4).
+- **The code** is a bearer login's code: one claim within
+  `BEARER_HANDOFF_MAX_AGE_SECONDS` (60) and never past the session, bound to
+  the challenge, stored only as a hash. A claimed code that comes back, a wrong
+  verifier or a code nobody claims ends the session.
+- **The session** acts as the opener's principal and has no `idpSubject` or
+  `loginAttemptId`. It lives `maxAgeSeconds` from the opening, the same rule as
+  every session, and no refresh extends it. It refreshes without asking the
+  provider. Its expiry, `endSession`, `endSessionsOfPrincipal`, the device's
+  `bearer/logout` and the reuse of its code or refresh token end it; an
+  inactive principal resolves it to nothing.
+- **What does not reach it.** It holds no provider token, so an idp.global
+  logout or a change of the person's memberships never reaches it, and
+  `AuthorityObserver.observe` refuses it (`authority_login_required`) without
+  ending it. So the application:
+  - grants a paired session (`session.idpSubject` absent) no idp.global
+    organization authority and does not observe it. An application that ends
+    sessions on `authority_login_required` must not observe paired sessions at
+    all;
+  - sees idp.global end a login only as `onSessionEnded` with the reason
+    `refresh_token_refused` for one of the person's provider sessions. It may
+    answer that by ending the person's paired sessions: `endSession` for those
+    `sessionsOfPrincipal` lists without `idpSubject`, or
+    `endSessionsOfPrincipal` to end every session of the person. The hook
+    names the principal of a session it revoked (`principalId`), so the
+    application needs no table of sessions and principals of its own;
+  - ends paired sessions itself when the person signs out everywhere, and
+    erases them with every other session when the account goes
+    (`eraseSessionsOfPrincipal`, see "Deleting an account");
+  - chooses `sessionMaxAgeSeconds`, or `maxAgeSeconds` per pairing, knowing
+    that a paired device lives that long without a check at idp.global.
+
+**Bearer-only mode.** An application whose every client is a bearer client turns
+the cookie login off with `cookieSessions: false`. No route then reads or sets a
+cookie, and that includes the intent cookie a cookie-mode callback clears. It
+takes no `csrfKey`, and it refuses `csrfKey`, `csrfLabel` and `cookieNames`,
+because nothing would use them; `bearer` and `provider` are required.
 
 ```ts
-const popup = window.open(loginUrl, 'idp-login', 'popup,width=480,height=640');
-window.addEventListener('message', async (event) => {
-  if (event.origin !== 'https://app.example' || event.source !== popup) return;
-  const message = event.data;
-  if (message?.type !== 'idp.global/relyingparty:bearer-handoff' || message.state !== state) return;
-  if (message.error) return showSignInError(message.error);
-  const tokens = await fetch('https://app.example/auth/bearer/claim', {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ code: message.code, codeVerifier: verifier }),
-  }).then((response) => response.json());
+const sessions = new RelyingPartySessions({
+  cookieSessions: false,
+  models,
+  provider,
+  publicOrigin: 'https://app.example',
+  sessionEncryptionKey: decodeSecretKey(process.env.SESSION_ENCRYPTION_KEY!, 'SESSION_ENCRYPTION_KEY'),
+  principals,
+  bearer: { returnTargets: { web: ['/signed-in'], popup: ['https://workspace.example'] } },
 });
 ```
 
+`/auth/login`, `/auth/finalize`, `/auth/session` and `/auth/logout` answer
+`null`, like every path the routes do not serve. `startLogin`,
+`completeLogin`, `abandonLogin`, `finalizeLogin`, `openSession`,
+`clearSessionCookie` and `clearIntentCookie` throw `login_method_unavailable`,
+and `resolveCookieSession` answers `null`. `openBearerHandoff` works, with a
+bearer login as the opener. A callback that belongs to no bearer
+login redirects to `failureLocation` when the provider sent an `error`, and
+otherwise answers 400 `authentication_failed`. `RelyingPartySocketBinding`
+registers a browser by its cookie session, so it binds no connection in this
+mode; an application with sockets authenticates them itself, for example with
+`resolveBearerSession`.
+
+**Listing a principal's sessions.** `sessionsOfPrincipal(principalId, { limit?,
+cursor? })` answers one page of the principal's live sessions, newest first,
+cookie and bearer alike: `{ sessions, nextCursor? }`. `limit` is 1 to 1,000
+(100 by default). `nextCursor` is there while more may follow. A session live
+throughout the walk appears on exactly one page; one opened during the walk is
+newer than every cursor and appears in the next walk. The cursor is opaque; a malformed one
+throws `invalid_sessions_cursor` (400). An inactive principal has no live
+session.
+
+```ts
+let page = await sessions.sessionsOfPrincipal(principalId, { limit: 50 });
+while (page.nextCursor) {
+  page = await sessions.sessionsOfPrincipal(principalId, { limit: 50, cursor: page.nextCursor });
+}
+```
+
 ### Testing an Application
 
 `@idp.global/sdk/relyingparty/testing` exports `RelyingPartyProviderDouble`, an
@@ -893,13 +1231,17 @@ const delivery = await readBearerDelivery(await fetch(callback, { redirect: 'man
 | --- | --- |
 | `IdpOidcProvider` | Discovery, PKCE authorization URL, code exchange with UserInfo, refresh, revocation and organization introspection for idp.global. Implements `IOidcProvider`. `trustedCaPem` or `fetch` for an issuer under a private CA. |
 | `createRelyingPartyModels()` | Binds the session, login-attempt, bearer hand-off and bearer token models to one `SmartdataDb`, or to a function asked for it on every use, optionally under existing collection names. |
-| `RelyingPartySessions<TPrincipal>` | Login start (with an application intent and a prompt)/complete/abandon/finalize, `openSession` (with a shorter lifetime), `resolveCookieSession`, `revalidateSession`, `revalidateLiveSession`, `isSessionLive`, `validateCsrf`, `logout`/`endSession`, `endSessionsOfPrincipal`, `liveProviderToken`. Principals give `isActive` or `resolve` (`IRelyingPartyPrincipals`, `IRelyingPartyPrincipalResolver<TPrincipal>`); with `resolve`, live sessions carry `principal`. With `bearer`: `startBearerLogin`, `bearerDeliveryOf`, `completeBearerLogin`, `abandonBearerLogin`, `claimBearerHandoff`, `refreshBearerTokens`, `resolveBearerAccessToken`, `resolveBearerSession`, `endBearerSession`. |
-| `AuthorityObserver` | Live organization authority with opt-in positive and negative reuse. |
-| `RelyingPartyRoutes` | `handle(ctx)` for `/auth/login`, `/auth/callback`, `/auth/finalize`, `/auth/session` and `/auth/logout`; `null` for anything else. Takes a typedserver route context. `onLogout` is awaited after a CSRF-checked logout ended the session. In bearer mode also `/auth/bearer/login`, `/auth/bearer/claim`, `/auth/bearer/refresh`, `/auth/bearer/session` and `/auth/bearer/logout`, with CORS for the popup origins only. |
+| `RelyingPartySessions<TPrincipal>` | Login start (with an application intent and a prompt)/complete/abandon/finalize, `openSession` (with a shorter lifetime), `resolveCookieSession`, `revalidateSession`, `revalidateLiveSession`, `isSessionLive`, `validateCsrf`, `logout`/`endSession`, `endSessionsOfPrincipal`, `eraseSessionsOfPrincipal` (deleting an account), `sessionsOfPrincipal` (paged), `liveProviderToken` (with `rejectedAccessToken`). Principals give `isActive` or `resolve` (`IRelyingPartyPrincipals`, `IRelyingPartyPrincipalResolver<TPrincipal>`); with `resolve`, live sessions carry `principal`. With `bearer`: `startBearerLogin`, `bearerDeliveryOf`, `completeBearerLogin`, `abandonBearerLogin`, `openBearerHandoff` (pairing a device from a live provider login), `claimBearerHandoff`, `refreshBearerTokens`, `resolveBearerAccessToken`, `resolveBearerSession`, `endBearerSession`; `cookieSessions: false` (`IRelyingPartyBearerOnlySessionsOptions`) runs bearer hand-off alone, without cookies or a CSRF key. |
+| `AuthorityObserver`, `AUTHORITY_FORCED_REFRESH_INTERVAL_MS` | Live organization authority with opt-in positive and negative reuse. An inactive answer rotates the session's token, at most once per interval, before it refuses. |
+| `RelyingPartyRoutes` | `handle(ctx)` for `/auth/login`, `/auth/callback`, `/auth/finalize`, `/auth/session` and `/auth/logout`; `null` for anything else. Takes a typedserver route context. `onLogout` is awaited after a CSRF-checked logout ended the session. In bearer mode also `/auth/bearer/login`, `/auth/bearer/claim`, `/auth/bearer/refresh`, `/auth/bearer/session` and `/auth/bearer/logout`, with CORS for the popup origins only; in bearer-only mode `/auth/login`, `/auth/finalize`, `/auth/session` and `/auth/logout` answer `null`. |
 | `createActorScope()` | AsyncLocalStorage actor context with a TypedRouter request scope. |
 | `RelyingPartySocketBinding` | TypedSocket browser registration, per-request re-validation and session tags; takes a connection wrapper or its peer. |
 | `SecretBox`, `deriveCsrfToken()`, `decodeSecretKey()`, `parseCookies()`, `serializeCookie()`, `sanitizeReturnPath()` | The primitives underneath. |
 | `pkceChallengeOf()`, `verifyPkceChallenge()`, `parseBearerAuthorization()`, `isBearerReturnTargetAllowed()`, `RELYING_PARTY_BEARER_MESSAGE_TYPE`, `BEARER_HANDOFF_MAX_AGE_SECONDS` | The bearer primitives: S256, the `Authorization` header, the return-target match and the popup message type. |
+| `IRelyingPartyBearerTokenAnswer`, `IRelyingPartyBearerSessionAnswer`, `IRelyingPartyBearerLogoutAnswer`, `IRelyingPartyBearerErrorAnswer`, `TRelyingPartyBearerErrorCode`, `IRelyingPartyBearerMessage` | The HTTP answers of the bearer routes and the popup message, shared with `@idp.global/sdk/browser`. |
+| `IRelyingPartyBearerLoginQuery`, `IRelyingPartyBearerClaimRequest`, `IRelyingPartyBearerRefreshRequest`, `IRelyingPartyBearerLogoutRequest` | The requests of the bearer routes: the `bearer/login` query and the JSON bodies, shared with `@idp.global/sdk/browser`. |
+| `IRelyingPartyBearerHandoffOpening` | What `openBearerHandoff` answers: the paired session, its code and when the code expires. |
+| `IRelyingPartySessionsErasure` | What `eraseSessionsOfPrincipal` answers: how many sessions it ended, and how many sessions, login attempts, bearer hand-offs and token generations it deleted. |
 | `RelyingPartyError`, `RelyingPartyRefusal`, `LoginCallbackError`, `AuthorityTokenError`, `AuthorityRefusedError`, `RelyingPartyDatabaseUnavailableError` | Errors with stable codes; none carries token material. A `RelyingPartyRefusal` may name the application's `location` for the browser. |
 | `RelyingPartyProviderDouble` (`/relyingparty/testing`) | An in-process idp.global for an application's tests: personas, live organization roles, single-use codes, rotating and reuse-detecting refresh tokens, recorded calls and injectable failures. `createBearerPkcePair()` and `readBearerDelivery()` for bearer clients. |
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@idp.global/sdk',
-  version: '19.3.0',
+  version: '19.5.0',
   description: 'Reusable browser and server SDK for idp.global authentication.'
 }