@idp.global/sdk 19.3.0 → 19.5.0

package/ts_relyingparty/classes.rpmodels.ts

@@ -3,10 +3,11 @@ import { RelyingPartyDatabaseUnavailableError } from './classes.errors.js';
 import type { TRelyingPartyBearerClientKind } from './interfaces.js';
 
 /**
- * One browser session of a relying party. The persisted field names, their
- * types and the index declarations are the ones nevermind.finance has stored
- * under `SessionDoc` since before this module existed, so its collection is
- * read and written unchanged.
+ * One browser session of a relying party. The persisted field names and their
+ * types are the ones nevermind.finance has stored under `SessionDoc` since
+ * before this module existed, so its collection is read and written
+ * unchanged; its indexes are those and the `expiresAt` index the sweep of
+ * ended sessions reads.
  */
 export class RelyingPartySessionDoc extends plugins.nosqldb.SmartDataDbDoc<RelyingPartySessionDoc, RelyingPartySessionDoc> {
   @plugins.nosqldb.unI()
@@ -27,7 +28,9 @@ export class RelyingPartySessionDoc extends plugins.nosqldb.SmartDataDbDoc<Relyi
   @plugins.nosqldb.svDb()
   public lastSeenAt: number = 0;
 
+  /** a revocation lowers it to `revokedAt` when that is earlier, so the sweep finds every ended session by it */
   @plugins.nosqldb.svDb()
+  @plugins.nosqldb.index()
   public expiresAt: number = 0;
 
   /** absent while the session is valid */

package/ts_relyingparty/contract.bearer.ts

@@ -0,0 +1,145 @@
+/**
+ * The wire contract of the bearer hand-off routes: what a bearer client sends
+ * and what it is answered. This module imports nothing, so the browser client
+ * (`@idp.global/sdk/browser`) shares it with the routes without reaching any
+ * server code; keep it that way.
+ */
+
+/** The `type` of every message a popup delivery posts. */
+export const RELYING_PARTY_BEARER_MESSAGE_TYPE = 'idp.global/relyingparty:bearer-handoff';
+
+/**
+ * How a bearer client receives the outcome of its login:
+ *
+ * - `web`: a redirect to a same-origin path of the application
+ * - `loopback`: a redirect to `http://127.0.0.1:<port>/…` or `http://[::1]:<port>/…`, any port (RFC 8252)
+ * - `custom_scheme`: a redirect to a registered private-use URI scheme such as `com.example.app:/signed-in` (RFC 8252)
+ * - `popup`: a page that posts the outcome to `window.opener` at exactly one registered origin
+ */
+export type TRelyingPartyBearerClientKind = 'web' | 'loopback' | 'custom_scheme' | 'popup';
+
+/**
+ * What the popup page of a `popup` delivery posts to `window.opener`. The
+ * receiver accepts it only when `event.origin` is the relying party's public
+ * origin, `event.source` is the popup it opened, `type` is
+ * `RELYING_PARTY_BEARER_MESSAGE_TYPE` and `state` is its own.
+ */
+export interface IRelyingPartyBearerMessage {
+  type: string;
+  /** the hand-off code; absent when the login failed */
+  code?: string;
+  /** why the login failed (`TRelyingPartyBearerDeliveryError`); absent when it succeeded */
+  error?: string;
+  state?: string;
+}
+
+/**
+ * Why a bearer login delivered no code, as the `error` of its redirect or
+ * popup message: `access_denied` when the provider came back without one,
+ * `authentication_failed` when the login could not be completed, or the code
+ * of the application's own refusal (`RelyingPartyRefusal.code`).
+ */
+export type TRelyingPartyBearerDeliveryError = 'access_denied' | 'authentication_failed' | (string & {});
+
+/** RFC 7636 §4.1: a code verifier is 43 to 128 characters of `A-Z a-z 0-9 . _ ~ -`. */
+const PKCE_VERIFIER = /^[A-Za-z0-9._~-]{43,128}$/u;
+
+/** Whether a value is a well-formed PKCE code verifier (RFC 7636 §4.1). */
+export const isPkceVerifier = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string' && PKCE_VERIFIER.test(valueArg);
+
+/**
+ * The query of `GET <prefix>bearer/login`, by its parameter names on the
+ * wire. The routes check every parameter as untrusted input.
+ */
+export interface IRelyingPartyBearerLoginQuery {
+  client_kind: TRelyingPartyBearerClientKind;
+  /** one of the configured return targets of the kind, exactly; a loopback target with the client's port */
+  return_target: string;
+  /** BASE64URL(SHA-256(code verifier)), 43 characters */
+  code_challenge: string;
+  /** only `S256` is accepted */
+  code_challenge_method: 'S256';
+  /** the client's own correlation value, 1 to 256 characters of `A-Z a-z 0-9 . _ ~ -`, handed back with the outcome */
+  state?: string;
+}
+
+/** The JSON body of `POST <prefix>bearer/claim`. */
+export interface IRelyingPartyBearerClaimRequest {
+  /** the hand-off code, claimed once */
+  code: string;
+  /** the verifier of the challenge the code is bound to (`isPkceVerifier`) */
+  codeVerifier: string;
+}
+
+/** The JSON body of `POST <prefix>bearer/refresh`. */
+export interface IRelyingPartyBearerRefreshRequest {
+  /** the current refresh token; this call spends it */
+  refreshToken: string;
+}
+
+/**
+ * The JSON body of `POST <prefix>bearer/logout`. The session is named by
+ * `Authorization: Bearer <accessToken>`, or by `refreshToken` once that access
+ * token has expired.
+ */
+export interface IRelyingPartyBearerLogoutRequest {
+  refreshToken?: string;
+}
+
+/** The session a bearer answer names. */
+export interface IRelyingPartyBearerSessionInfo {
+  sessionId: string;
+  principalId: string;
+  /** epoch milliseconds: the end of the session, which no refresh extends */
+  expiresAt: number;
+}
+
+/** What `POST <prefix>bearer/claim` and `POST <prefix>bearer/refresh` answer with status 200. */
+export interface IRelyingPartyBearerTokenAnswer {
+  tokenType: 'Bearer';
+  accessToken: string;
+  /** epoch milliseconds on the relying party's clock */
+  accessTokenExpiresAt: number;
+  /** seconds the access token lives from the answer, for a client whose clock differs */
+  expiresIn: number;
+  /** spent by the next refresh; it never comes back after that */
+  refreshToken: string;
+  /** epoch milliseconds: the end of the session */
+  refreshTokenExpiresAt: number;
+  session: IRelyingPartyBearerSessionInfo;
+}
+
+/** What `GET <prefix>bearer/session` answers with status 200; `null` for any token that is not live. */
+export interface IRelyingPartyBearerSessionAnswer {
+  session: IRelyingPartyBearerSessionInfo | null;
+}
+
+/** What `POST <prefix>bearer/logout` answers with status 200; `true` only when this call ended a live session. */
+export interface IRelyingPartyBearerLogoutAnswer {
+  endedLiveSession: boolean;
+}
+
+/**
+ * The `error` of a failed bearer route, answered as `{ error }`:
+ *
+ * - `invalid_bearer_request` (400): a login start or claim with a missing or malformed parameter
+ * - `return_target_not_allowed` (400): a login start naming a return target not configured for its kind
+ * - `invalid_bearer_handoff` (400): a claim with a code that is unknown, expired, already claimed or of the wrong verifier
+ * - `invalid_bearer_grant` (400): a refresh token that is unknown, spent, expired or of a session that is over
+ * - `authority_unavailable` (503): a refresh that could not reach the provider; nothing was spent, retry it
+ * - `authentication_unavailable` (503): any other failure on the relying party's side
+ * - `forbidden` (403): a CORS preflight from an origin that is no popup return target
+ */
+export type TRelyingPartyBearerErrorCode =
+  | 'invalid_bearer_request'
+  | 'return_target_not_allowed'
+  | 'invalid_bearer_handoff'
+  | 'invalid_bearer_grant'
+  | 'authority_unavailable'
+  | 'authentication_unavailable'
+  | 'forbidden';
+
+export interface IRelyingPartyBearerErrorAnswer {
+  error: TRelyingPartyBearerErrorCode;
+}

package/ts_relyingparty/helpers.bearer.ts

@@ -1,11 +1,15 @@
+import {
+  isPkceVerifier,
+  RELYING_PARTY_BEARER_MESSAGE_TYPE,
+  type IRelyingPartyBearerMessage,
+  type TRelyingPartyBearerClientKind,
+} from './contract.bearer.js';
 import { sha256, timingSafeEqualString } from './helpers.crypto.js';
 import { sanitizeReturnPath } from './helpers.returnpath.js';
-import type {
-  IRelyingPartyBearerDelivery,
-  IRelyingPartyBearerMessage,
-  IRelyingPartyBearerReturnTargets,
-  TRelyingPartyBearerClientKind,
-} from './interfaces.js';
+import type { IRelyingPartyBearerDelivery, IRelyingPartyBearerReturnTargets } from './interfaces.js';
+
+// the verifier check lives in the import-free contract, which the browser client shares
+export { isPkceVerifier, RELYING_PARTY_BEARER_MESSAGE_TYPE };
 
 export const RELYING_PARTY_BEARER_CLIENT_KINDS: readonly TRelyingPartyBearerClientKind[] = Object.freeze([
   'web',
@@ -14,15 +18,10 @@ export const RELYING_PARTY_BEARER_CLIENT_KINDS: readonly TRelyingPartyBearerClie
   'popup',
 ]);
 
-/** The `type` of every message a popup delivery posts. */
-export const RELYING_PARTY_BEARER_MESSAGE_TYPE = 'idp.global/relyingparty:bearer-handoff';
-
 /** A return target is a location the application configured, not a place to park data. */
 const MAX_RETURN_TARGET_LENGTH = 2_048;
 /** BASE64URL of a SHA-256 digest, without padding (RFC 7636 §4.2). */
 const PKCE_CHALLENGE = /^[A-Za-z0-9_-]{43}$/u;
-/** RFC 7636 §4.1: 43 to 128 unreserved characters. */
-const PKCE_VERIFIER = /^[A-Za-z0-9._~-]{43,128}$/u;
 const CLIENT_STATE = /^[A-Za-z0-9._~-]{1,256}$/u;
 const LOOPBACK_HOSTS: readonly string[] = ['127.0.0.1', '[::1]'];
 /** A private-use scheme is a reverse domain name: it has a dot, and no web scheme has one (RFC 8252 §7.1). */
@@ -34,9 +33,6 @@ export const isBearerClientKind = (valueArg: unknown): valueArg is TRelyingParty
 export const isPkceChallenge = (valueArg: unknown): valueArg is string =>
   typeof valueArg === 'string' && PKCE_CHALLENGE.test(valueArg);
 
-export const isPkceVerifier = (valueArg: unknown): valueArg is string =>
-  typeof valueArg === 'string' && PKCE_VERIFIER.test(valueArg);
-
 export const isBearerClientState = (valueArg: unknown): valueArg is string =>
   typeof valueArg === 'string' && CLIENT_STATE.test(valueArg);
 

package/ts_relyingparty/interfaces.ts

@@ -1,4 +1,21 @@
 import type { IOidcCompletion, TOidcCompletionFailureStage, TOidcPrompt, TOidcTokenHint } from './classes.idpoidcprovider.js';
+import type { TRelyingPartyBearerClientKind } from './contract.bearer.js';
+
+export type {
+  IRelyingPartyBearerClaimRequest,
+  IRelyingPartyBearerErrorAnswer,
+  IRelyingPartyBearerLoginQuery,
+  IRelyingPartyBearerLogoutAnswer,
+  IRelyingPartyBearerLogoutRequest,
+  IRelyingPartyBearerMessage,
+  IRelyingPartyBearerRefreshRequest,
+  IRelyingPartyBearerSessionAnswer,
+  IRelyingPartyBearerSessionInfo,
+  IRelyingPartyBearerTokenAnswer,
+  TRelyingPartyBearerClientKind,
+  TRelyingPartyBearerDeliveryError,
+  TRelyingPartyBearerErrorCode,
+} from './contract.bearer.js';
 
 /** A session as the application reads it; no token and no sealed value is part of it. */
 export interface IRelyingPartySession {
@@ -35,6 +52,21 @@ export interface IRelyingPartySessionOpening {
   sessionCookie: string;
 }
 
+/** What `sessionsOfPrincipal` reads: how many sessions, and after which page. */
+export interface IRelyingPartySessionsPageOptions {
+  /** 1 to `RELYING_PARTY_MAX_SESSIONS_PAGE_LIMIT`; `RELYING_PARTY_DEFAULT_SESSIONS_PAGE_LIMIT` when absent */
+  limit?: number;
+  /** the `nextCursor` of the page before; absent for the first page */
+  cursor?: string;
+}
+
+/** One page of a principal's live sessions, newest first. */
+export interface IRelyingPartySessionsPage {
+  sessions: IRelyingPartySession[];
+  /** opaque; reads the next page as `cursor`. Absent on the last page. */
+  nextCursor?: string;
+}
+
 /**
  * What `startLogin` carries besides the return path. `intent` is the
  * application's own text — the invitation a login accepts, the account it
@@ -62,16 +94,6 @@ export interface IRelyingPartyLoginStart {
   intentCookie: string;
 }
 
-/**
- * How a bearer client receives the outcome of its login:
- *
- * - `web`: a redirect to a same-origin path of the application
- * - `loopback`: a redirect to `http://127.0.0.1:<port>/…` or `http://[::1]:<port>/…`, any port (RFC 8252)
- * - `custom_scheme`: a redirect to a registered private-use URI scheme such as `com.example.app:/signed-in` (RFC 8252)
- * - `popup`: a page that posts the outcome to `window.opener` at exactly one registered origin
- */
-export type TRelyingPartyBearerClientKind = 'web' | 'loopback' | 'custom_scheme' | 'popup';
-
 /**
  * The exact return targets a bearer client may name, per client kind. A kind
  * without targets is not offered. Matching is by equality, never by prefix
@@ -138,6 +160,37 @@ export interface IRelyingPartyBearerHandoff {
   expiresAt: number;
 }
 
+/**
+ * A bearer session the application opened for a device it paired
+ * (`openBearerHandoff`): the session, which has no provider login of its own
+ * (`idpSubject` and `loginAttemptId` are absent), and the single-use code the
+ * device claims at `bearer/claim` with the verifier of its challenge. The
+ * code is no token; only its hash is stored.
+ */
+export interface IRelyingPartyBearerHandoffOpening {
+  session: IRelyingPartySession;
+  code: string;
+  /** epoch milliseconds, at most `BEARER_HANDOFF_MAX_AGE_SECONDS` after the opening and never past the session */
+  expiresAt: number;
+}
+
+/**
+ * What `eraseSessionsOfPrincipal` removed of one principal: the sessions it
+ * ended first, and the rows it deleted.
+ */
+export interface IRelyingPartySessionsErasure {
+  /** sessions not revoked yet (an expired one too) that it ended, each with `onSessionEnded` and its provider tokens handed back */
+  endedSessions: number;
+  /** session rows, live or ended */
+  deletedSessions: number;
+  /** the sign-in transactions the provider sessions came out of */
+  deletedLoginAttempts: number;
+  /** bearer hand-offs, claimed or not */
+  deletedBearerHandoffs: number;
+  /** bearer token generations, current or rotated */
+  deletedBearerTokens: number;
+}
+
 /**
  * The relying party's own tokens of a bearer session. The refresh token
  * rotates on every use; a rotated one coming back ends the session.
@@ -154,27 +207,17 @@ export interface IRelyingPartyBearerTokens {
   refreshTokenExpiresAt: number;
 }
 
-/**
- * What the popup page of a `popup` delivery posts to `window.opener`. The
- * receiver accepts it only when `event.origin` is the relying party's public
- * origin, `event.source` is the popup it opened, `type` is
- * `RELYING_PARTY_BEARER_MESSAGE_TYPE` and `state` is its own.
- */
-export interface IRelyingPartyBearerMessage {
-  type: string;
-  /** the hand-off code; absent when the login failed */
-  code?: string;
-  /** why the login failed; absent when it succeeded */
-  error?: string;
-  state?: string;
-}
-
 /** A provider access token usable right now, with the subject it belongs to. */
 export interface IProviderToken {
   accessToken: string;
   subject: string;
   /** epoch milliseconds; `0` when the provider named no lifetime */
   expiresAt: number;
+  /**
+   * `true` only on the answer to `rejectedAccessToken`, and only when a
+   * rotation that this call started issued the token.
+   */
+  rotatedAfterRejection?: boolean;
 }
 
 /** What an authority observer needs from the session owner. `RelyingPartySessions` implements it. */
@@ -182,8 +225,21 @@ export interface IAuthorityTokenSource {
   /**
    * The access token of a login session, rotated first when it is due. The
    * session must belong to `expectedPrincipalIdArg`. Throws `AuthorityTokenError`.
+   *
+   * `rejectedAccessToken` is a token idp.global answered inactive for. The
+   * source must rotate the session's token then, whatever is stored, and set
+   * `rotatedAfterRejection` only when a rotation that this call started issued
+   * the token. A refused refresh ends the session and throws
+   * `authority_login_required`. A rotation that started before the call, one
+   * another replica holds, or a session without a refresh token marks
+   * nothing. A source that never rotates or never marks its answer can never
+   * refuse: the observer answers `authority_unavailable` (fail-closed).
    */
-  liveProviderToken(sessionIdArg: string, expectedPrincipalIdArg: string): Promise<IProviderToken>;
+  liveProviderToken(
+    sessionIdArg: string,
+    expectedPrincipalIdArg: string,
+    optionsArg?: { rejectedAccessToken?: string },
+  ): Promise<IProviderToken>;
 }
 
 /**
@@ -250,6 +306,8 @@ export type TRelyingPartyEventName =
   | 'login_attempt_sweep_failed'
   /** expired bearer hand-offs and token generations could not be swept */
   | 'bearer_sweep_failed'
+  /** sessions an hour past their end could not be swept */
+  | 'session_sweep_failed'
   /** a bearer hand-off code or refresh token came back after its use; `reason` names which, the session ended */
   | 'bearer_credential_reused'
   /** an application hook threw; the step it belonged to ran on regardless */
@@ -275,20 +333,22 @@ export interface IRelyingPartyHooks {
    * A provider login opened a session, linked to its attempt. Runs before the
    * login answers; a throw fails the login: the session is revoked, the
    * provider tokens are handed back and the original error is rethrown.
+   * `delivery` is where a bearer login's outcome goes (its client kind, return
+   * target and the client's `state`); a cookie login has none.
    */
-  onProviderSessionOpened?(eventArg: { session: IRelyingPartySession }): Promise<void>;
+  onProviderSessionOpened?(eventArg: { session: IRelyingPartySession; delivery?: IRelyingPartyBearerDelivery }): Promise<void>;
   /**
    * A session ended, or a caller tried to end one that was already over
    * (`revokedHere: false`). Close its live connections when `revokedHere`,
    * drop cached authority either way. Must not wait. A throw (or a rejected
    * promise) is reported as a `hook_failed` event and never stops the end:
-   * the provider tokens go back regardless.
+   * the provider tokens go back regardless. An end that revoked the session
+   * here names its principal (`principalId`); one that found it over already
+   * does not.
    */
-  onSessionEnded?(eventArg: {
-    sessionId: string;
-    reason: TRelyingPartySessionEndReason;
-    revokedHere: boolean;
-  }): void;
+  onSessionEnded?(eventArg:
+    | { sessionId: string; reason: TRelyingPartySessionEndReason; revokedHere: true; principalId: string }
+    | { sessionId: string; reason: TRelyingPartySessionEndReason; revokedHere: false }): void;
   /**
    * Structured diagnostics; the default writes one JSON line to
    * `console.error`. A throwing sink never interrupts the step that reported: