@idp.global/sdk 19.2.1 → 19.4.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`). 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
@@ -583,8 +624,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 +646,12 @@ 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; `openSession` removes
+the sessions only. Removing an ended session fires no end hook and calls no
+provider.
+
 **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,
@@ -700,6 +748,285 @@ for (const connection of await binding.connectionsOfSession(sessionId)) {
 }
 ```
 
+### Bearer Hand-off
+
+Cookies serve the application's own pages. Clients of its own that hold no
+cookie of this origin — a desktop app, a native app, a page framed on another
+origin — sign in through the same idp.global login and receive the relying
+party's own access and refresh tokens instead. The `bearer` option turns this
+on beside the cookie login; no bearer route reads or sets a cookie.
+
+```ts
+const models = createRelyingPartyModels({ db: smartdataDb });
+await models.Session.ensureInitialized();
+await models.LoginAttempt.ensureInitialized();
+await models.BearerHandoff.ensureInitialized();
+await models.BearerToken.ensureInitialized();
+
+const sessions = new RelyingPartySessions({
+  models,
+  provider,
+  // … publicOrigin, keys, principals and hooks as above
+  bearer: {
+    returnTargets: {
+      web: ['/signed-in'],
+      loopback: ['http://127.0.0.1/callback', 'http://[::1]/callback'],
+      custom_scheme: ['com.example.app:/oauth/callback'],
+      popup: ['https://workspace.example'],
+    },
+    accessTokenMaxAgeSeconds: 900, // the default
+  },
+});
+```
+
+The flow, with the routes under the default `/auth/` prefix:
+
+1. The client makes a PKCE verifier and its S256 challenge (RFC 7636) and
+   opens `GET /auth/bearer/login?client_kind=<kind>&return_target=<target>&code_challenge=<challenge>&code_challenge_method=S256&state=<state>`.
+   `state` is optional: the client's own value of 1 to 256 characters of
+   `A-Z a-z 0-9 . _ ~ -`, handed back with the outcome. A malformed request
+   answers 400 `invalid_bearer_request`, a target that is not configured for
+   the kind 400 `return_target_not_allowed`; neither stores anything.
+2. The relying party runs the idp.global login (authorization code with PKCE,
+   as for cookies). Its `GET /auth/callback` opens the session and delivers a
+   hand-off code to the return target. The code is no token: it is valid for
+   one claim within `BEARER_HANDOFF_MAX_AGE_SECONDS` (60), bound to the
+   challenge, and only its hash is stored. `web`, `loopback` and
+   `custom_scheme` get a redirect with `code` and `state` in the query.
+   `popup` gets a page whose one nonce script posts
+   `{ type: RELYING_PARTY_BEARER_MESSAGE_TYPE, code, state }` to
+   `window.opener` with the registered origin as the target origin — never
+   `'*'` — and closes the window. A login that fails delivers `error` instead
+   of `code`: `access_denied` when the provider came back without a code, the
+   code of a `RelyingPartyRefusal` (its `location` is not followed), or
+   `authentication_failed`.
+3. The client claims with `POST /auth/bearer/claim` `{ code, codeVerifier }`.
+   The answer, as for `POST /auth/bearer/refresh` `{ refreshToken }`, is
+   `{ tokenType: 'Bearer', accessToken, accessTokenExpiresAt, expiresIn, refreshToken, refreshTokenExpiresAt, session: { sessionId, principalId, expiresAt } }`
+   (`expiresIn` in seconds, counted on the relying party's clock).
+4. `Authorization: Bearer <accessToken>` authenticates the client:
+   `GET /auth/bearer/session` answers `{ session }` (`null` without a live
+   one), and the application's own routes call
+   `sessions.resolveBearerSession(authorizationHeader)` for the live session.
+   `POST /auth/bearer/logout` ends the session of that access token, or of the
+   body's `{ refreshToken }` once the access token has expired, and answers
+   `{ endedLiveSession }`.
+
+Return targets are an exact allow-list per kind, compared by equality:
+
+- `web`: paths on the public origin outside the login routes.
+- `loopback`: `http://127.0.0.1/<path>` or `http://[::1]/<path>`, configured
+  without a port. The client names its ephemeral port, and any port matches
+  (RFC 8252 §7.3); `localhost` is not accepted.
+- `custom_scheme`: whole URIs of a private-use scheme with a dot in it (RFC
+  8252 §7.1).
+- `popup`: bare origins.
+
+The constructor refuses an entry that is not in its canonical form, carries a
+query or a fragment, or contains a `*`: nothing is a prefix and nothing is a
+wildcard.
+
+Tokens and their ends:
+
+- An access token lives `accessTokenMaxAgeSeconds` and never past its
+  session; the refresh token lives until the session ends, and no refresh
+  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`.
+- 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
+  expired unclaimed ends its session when it comes back or when the next
+  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
+  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, … })`), 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
+header.
+
+The client side:
+
+- A web client reads `code` and `state` from its return path, removes them with
+  `history.replaceState` and claims at once. Every delivery is sent with
+  `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`. 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`). They come from a module that imports
+nothing, so `@idp.global/sdk/browser` shares 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.
+- `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.
+
+**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 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`. 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
@@ -739,20 +1066,38 @@ discovery. Once one has succeeded, discovery stays done, as with
 `IdpOidcProvider`; `discoveries` counts the calls. The claims of a login are
 those of its sign-in; introspection reads the persona as it is now.
 
+For bearer clients, `createBearerPkcePair()` makes a verifier and its S256
+challenge, and `readBearerDelivery(response)` reads a callback answer the way
+its client would: the `code`, `error` and `state` of a redirect's location
+(`target` is the location without its query), or a popup page's posted
+`message` and its target origin.
+
+```ts
+import { createBearerPkcePair, readBearerDelivery } from '@idp.global/sdk/relyingparty/testing';
+
+const pkce = createBearerPkcePair();
+const start = await fetch(`${appOrigin}/auth/bearer/login?client_kind=web&return_target=/signed-in&code_challenge=${pkce.challenge}&code_challenge_method=S256`, { redirect: 'manual' });
+const callback = idp.callbackUrlFor(new URL(start.headers.get('location')!), new URL('/auth/callback', appOrigin));
+const delivery = await readBearerDelivery(await fetch(callback, { redirect: 'manual' }));
+// delivery.code is claimed with pkce.verifier at /auth/bearer/claim
+```
+
 ### Relying-Party API Surface
 
 | 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. |
-| `createRelyingPartyModels()` | Binds the session and login-attempt 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`. |
-| `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. |
+| `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. |
+| `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`. |
 | `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. |
+| `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.2.1',
+  version: '19.4.0',
   description: 'Reusable browser and server SDK for idp.global authentication.'
 }