@idp.global/sdk 19.4.0 → 19.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idp.global/sdk",
-  "version": "19.4.0",
+  "version": "19.6.0",
   "private": false,
   "description": "Reusable browser and server SDK for idp.global authentication.",
   "type": "module",
@@ -36,10 +36,10 @@
   },
   "devDependencies": {
     "@api.global/typedserver": "^11.4.0",
-    "@git.zone/tsrepo": "^1.1.1",
+    "@git.zone/tsrepo": "^2.1.0",
     "@lossless.org/client": "^2.0.0",
     "@lossless.org/nosqldb": "10.5.0",
-    "@types/node": "26.6.5"
+    "@types/node": "26.6.6"
   },
   "files": [
     "ts/**/*",

package/readme.md

@@ -152,7 +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`). See [Bearer Hand-off](#bearer-hand-off). |
+| `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
 
@@ -559,8 +559,10 @@ What it does:
 - **Login**: `GET /auth/login?return=/path` stores one login attempt (state and
   browser binding stored as SHA-256, PKCE verifier sealed) and redirects to the
   provider. `GET /auth/callback` consumes the attempt exactly once, exchanges
-  the code, reads UserInfo with a subject check, calls `principals.admit` and
-  opens a session; a provider `error` abandons the attempt. `GET /auth/finalize`
+  the code, verifies the ID token (its RS256 signature against idp.global's
+  JWKS, its issuer, audience and nonce), reads UserInfo with a subject check,
+  calls `principals.admit` and opens a session; a provider `error` abandons the
+  attempt. `GET /auth/finalize`
   releases the return path only to the browser holding the session that attempt
   created. Return paths stay on the public origin and outside the login routes.
   Expired attempts are swept when the next login starts.
@@ -583,7 +585,8 @@ What it does:
   the routes follow it only when it is a plain path on the public origin
   outside the login routes, exactly as given, and otherwise answer as if it
   named none.
-- **Sessions**: an HttpOnly, `SameSite=Lax` cookie whose token is stored as a
+- **Sessions**: an HttpOnly, `SameSite=Lax` (by default, see "Framed
+  applications" below) cookie whose token is stored as a
   hash, touched at most once a minute, with a CSRF token derived per request as
   an HMAC of the cookie token. `GET /auth/session` answers the session and
   `POST /auth/logout` needs the public origin and the CSRF token; its body is
@@ -596,7 +599,8 @@ What it does:
 - **Provider tokens**: sealed with AES-256-GCM (`SecretBox`) and rotated shortly
   before they expire, once per process and under a lock stored on the session,
   so two replicas never spend one refresh token. A refused refresh ends the
-  session; an unreachable provider fails closed.
+  session; an unreachable provider fails closed, and so does a refresh whose ID
+  token does not verify against the JWKS.
 - **Live authority**: `AuthorityObserver.observe({ loginSessionId, principalId,
   idpOrganizationId })` introspects the organization with the session's live
   token and projects the role keys through the application's table. It answers
@@ -614,6 +618,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
@@ -623,9 +634,46 @@ login's cause. Custom `cookieNames` with a `__Host-` or `__Secure-` prefix need
 an https `publicOrigin`; on http the constructor refuses them, because browsers
 would silently drop those cookies.
 
+**Framed applications.** The session cookie and the login's intent cookie are
+`SameSite=Lax`, so a browser never sends them into a page of the application
+that another site frames. `cookiePolicy` changes that for both cookies, on
+every `Set-Cookie` that sets or clears them:
+
+```ts
+const sessions = new RelyingPartySessions({
+  // …
+  cookiePolicy: { sameSite: 'None', partitioned: true },
+});
+```
+
+- `sameSite: 'None'` sends the cookies with the framed page's requests too.
+  It needs an https `publicOrigin`, since a `SameSite=None` cookie must be
+  `Secure`.
+- `partitioned: true` adds `Partitioned` (CHIPS): the browser keeps the
+  cookies per top-level site, so the application has one jar under each site
+  that frames it, where a browser that blocks third-party cookies would
+  otherwise drop them. It is valid only with `sameSite: 'None'`.
+- The constructor refuses `partitioned` without `sameSite: 'None'`,
+  `sameSite: 'None'` on http, any other `sameSite` value and a `partitioned`
+  that is not a boolean. Bearer-only mode refuses `cookiePolicy` altogether.
+  `sessions.cookiePolicy` answers the resolved policy; the default is
+  `{ sameSite: 'Lax', partitioned: false }`.
+- With `SameSite=None` the browser also sends the session cookie with other
+  sites' requests to the application, so the CSRF token (`validateCsrf`) and
+  the origin check are its only CSRF defence: check them on every request that
+  changes something.
+- A partitioned cookie belongs to the top-level site of the window that
+  received it. A login that leaves the frame, in a popup or a new tab, sets its
+  cookies in the application's own top-level jar, where the frame never reads
+  them, so the whole login, `/auth/login` through `/auth/finalize`, has to run
+  inside the frame. Where the provider's login cannot run framed, the framed
+  application signs in with a bearer `popup` login instead (see "Bearer
+  Hand-off").
+
 **Adopting existing session data.** The persisted fields and index declarations
 are those nevermind.finance has stored since mainapp 0b693cb, and the session
-model adds an `expiresAt` index, built on first use. An application that
+model adds an `expiresAt` index and the bearer hand-off and token models a
+`sessionId` index, each 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:
 
@@ -648,9 +696,81 @@ 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; `openSession` removes
-the sessions only. Removing an ended session fires no end hook and calls no
-provider.
+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. In bearer
+mode a session's hand-offs and token generations go before its row, so none
+outlives the session, and a removal that fails half way is finished by the
+next one. `endSessionsOfPrincipal` ends the principal's live sessions; one that
+expired is over already and is neither ended nor counted.
+
+**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 holds only hashes, the session
+  id and times, and the bearer sweep removes it an hour after the session
+  would have expired.
+
+**Telling provider failures apart.** Every failure of the provider half is an
+`OidcProviderError`, so an application classifies it without importing
+openid-client. `code` (`TOidcProviderErrorCode`) says which case it is, and
+`oauthError` the provider's own OAuth error code when it sent one, such as
+`invalid_grant` (a short token; the provider's description is never kept):
+
+| `code` | When |
+| --- | --- |
+| `token_exchange_refused` | The provider refused the login: an OAuth error in the callback, for the code at the token endpoint (`invalid_grant` for a used or expired code), or for its token at UserInfo. |
+| `login_mismatch` | The callback or its ID token is not this login's: another `state`, or an ID token claim that does not match it (the nonce, and likewise the issuer, the audience or the authorized party). |
+| `invalid_response` | The provider answered outside its contract: an ID token whose signature does not verify against the JWKS or that has expired, no subject, another subject at UserInfo, a body that is no OAuth answer. |
+| `provider_unreachable` | The provider could not be asked: no answer in time, a transport failure, a 5xx, or no discovery yet. |
+| `refresh_refused` | The refresh grant answered `invalid_grant`: the refresh family is revoked, expired or was reused. |
+
+`OidcCompletionError` (with its `stage`), `OidcRefreshRefusedError` and
+`OidcAuthorityUnavailableError` (with its `reason`) are `OidcProviderError`s. A
+failed login callback throws `LoginCallbackError`, whose `cause` is the
+provider's failure when the provider half failed:
+
+```ts
+import { LoginCallbackError, OidcProviderError } from '@idp.global/sdk/relyingparty';
+
+try {
+  await sessions.completeLogin(callbackUrl, cookieHeader);
+} catch (error) {
+  const failure = error instanceof LoginCallbackError ? error.cause : error;
+  if (failure instanceof OidcProviderError) {
+    // `failure.code` and `failure.oauthError` are tokens a log line may carry
+    log({ event: 'login_failed', code: failure.code, oauthError: failure.oauthError });
+    const retryLater = failure.code === 'provider_unreachable' || failure.code === 'invalid_response';
+    // …
+  }
+}
+```
 
 **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
@@ -707,10 +827,11 @@ a deadline of its own; bound a slow audit store inside it.
 
 **Issuers under a private CA.** `IdpOidcProvider` takes `trustedCaPem` — one
 PEM string or several, e.g. `@idp.global/devidp`'s `caCertificatePem` or a LAN
-deployment's root. Discovery, token, UserInfo, refresh, revocation and
-introspection then go through one `node:https` agent of this provider that
-trusts those CAs and nothing else; the global `fetch`, its dispatcher and
-`NODE_EXTRA_CA_CERTS` are not involved, and the issuer must still be `https:`.
+deployment's root. Discovery, token, UserInfo, refresh, revocation,
+introspection and the JWKS the ID tokens are verified with then go through one
+`node:https` agent of this provider that trusts those CAs and nothing else; the
+global `fetch`, its dispatcher and `NODE_EXTRA_CA_CERTS` are not involved, and
+the issuer must still be `https:`.
 An unreadable PEM is refused by the constructor.
 
 ```ts
@@ -775,6 +896,7 @@ const sessions = new RelyingPartySessions({
       popup: ['https://workspace.example'],
     },
     accessTokenMaxAgeSeconds: 900, // the default
+    refreshReuseGraceSeconds: 60, // the default; 0 turns it off, at most 300
   },
 });
 ```
@@ -833,9 +955,26 @@ Tokens and their ends:
   extends it.
 - A refresh spends its refresh token and answers a new pair; the old access
   token stops working at once. A spent refresh token that comes back ends the
-  whole session (`refresh_token_reused`), so a client serializes its refreshes,
-  and a client that lost a refresh answer signs in again. A refused refresh
-  answers 400 `invalid_bearer_grant`.
+  whole session (`refresh_token_reused`), so a client serializes its refreshes.
+  A refused refresh answers 400 `invalid_bearer_grant`.
+- A refresh answer that never reached the client (a reload, a closed tab, a
+  dropped connection) is the one exception. Within `refreshReuseGraceSeconds`
+  of the rotation (60 by default, 0 turns it off, at most 300; the
+  constructor refuses anything else), a spent refresh token whose successor
+  was never presented revokes that successor and answers a new pair, reported
+  as a `bearer_refresh_reissued` event. Presented means its access token
+  authenticated a request (`bearer/session`, `resolveBearerSession`,
+  `resolveBearerAccessToken`) or its refresh token was sent to `bearer/refresh`.
+  Only hashes are stored, so the lost pair is replaced, never repeated, and
+  that pair coming back later is reuse. Once the successor was presented, after
+  the window (counted from the rotation, however often the retry's answer is
+  lost too), and for the second of two retries at once, the spent token is
+  reuse and ends the session as before. `bearer/logout` judges a spent refresh
+  token the same way: a sign-out after a lost answer, within the window, ends
+  the session as a `logout`, not as reuse. A stolen spent token works within the
+  same window while the client has not used its new pair yet: the client's
+  access token then stops working, and its next refresh ends the session.
+  Choose the window by that trade-off.
 - The first claim consumes the code, whatever its verifier. A wrong verifier
   ends the session (`handoff_verifier_mismatch`), a claimed code that comes
   back ends it too (`handoff_code_reused`, RFC 6749 §4.1.2), and a code that
@@ -843,8 +982,10 @@ 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
@@ -870,15 +1011,21 @@ The client side:
 - 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.
+  used. A pair that is lost after the relying party rotated it is recovered
+  only by the next refresh with the stored pair within the grace window; after
+  it, the 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`). They come from a module that imports
-nothing, so `@idp.global/sdk/browser` shares them with the server.
+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
@@ -929,6 +1076,16 @@ await client.logout();
   `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
@@ -945,8 +1102,9 @@ await client.logout();
   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.
+  token is answered; when `storage.set` fails, the new pair is never used, and
+  the session goes on only if the next refresh comes within the relying
+  party's grace window.
 - `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
@@ -956,9 +1114,10 @@ await client.logout();
   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.
+  timed-out claim fails the login, and the user signs in again. After a lost
+  refresh, the next refresh with the stored pair gets a new one when it runs
+  within the relying party's `refreshReuseGraceSeconds`; later it ends the
+  session (`refresh_token_reused`) and the user signs in again.
 - `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
@@ -981,12 +1140,94 @@ await client.logout();
 - 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.
+takes no `csrfKey`, and it refuses `csrfKey`, `csrfLabel`, `cookieNames` and
+`cookiePolicy`, because nothing would use them; `bearer` and `provider` are
+required.
 
 ```ts
 const sessions = new RelyingPartySessions({
@@ -1004,7 +1245,8 @@ const sessions = new RelyingPartySessions({
 `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`. A callback that belongs to no bearer
+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
@@ -1086,17 +1328,21 @@ const delivery = await readBearerDelivery(await fetch(callback, { redirect: 'man
 
 | API | Description |
 | --- | --- |
-| `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. |
+| `IdpOidcProvider` | Discovery, PKCE authorization URL, code exchange with UserInfo, refresh, revocation and organization introspection for idp.global. Implements `IOidcProvider`. Verifies the signature of every ID token against the issuer's JWKS. `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`, `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`, `claimBearerHandoff`, `refreshBearerTokens`, `resolveBearerAccessToken`, `resolveBearerSession`, `endBearerSession`; `cookieSessions: false` (`IRelyingPartyBearerOnlySessionsOptions`) runs bearer hand-off alone, without cookies or a CSRF key. |
+| `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. |
+| `SecretBox`, `deriveCsrfToken()`, `decodeSecretKey()`, `parseCookies()`, `serializeCookie()` (with `partitioned`, which needs `secure`), `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. |
+| `OidcProviderError`, `TOidcProviderErrorCode`, `OIDC_PROVIDER_ERROR_CODES`; `OidcCompletionError`, `OidcRefreshRefusedError`, `OidcAuthorityUnavailableError` | The provider's failures with the sdk's own `code` and the provider's `oauthError`, so no application classifies openid-client errors itself. |
 | `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. |
 
 ## Runtime Notes

package/ts/00_commitinfo_data.ts

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