@idp.global/sdk 19.3.0 → 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,
@@ -802,7 +850,8 @@ Tokens and their ends:
   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 +864,169 @@ 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`). 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 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`. 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 +1088,14 @@ 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`, `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. `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.4.0',
   description: 'Reusable browser and server SDK for idp.global authentication.'
 }