@idp.global/sdk 19.3.0 → 19.4.0

package/ts_relyingparty/contract.bearer.ts

@@ -0,0 +1,99 @@
+/**
+ * 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 & {});
+
+/** 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,13 @@
+import {
+  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';
+
+export { RELYING_PARTY_BEARER_MESSAGE_TYPE };
 
 export const RELYING_PARTY_BEARER_CLIENT_KINDS: readonly TRelyingPartyBearerClientKind[] = Object.freeze([
   'web',
@@ -14,9 +16,6 @@ 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). */

package/ts_relyingparty/interfaces.ts

@@ -1,4 +1,17 @@
 import type { IOidcCompletion, TOidcCompletionFailureStage, TOidcPrompt, TOidcTokenHint } from './classes.idpoidcprovider.js';
+import type { TRelyingPartyBearerClientKind } from './contract.bearer.js';
+
+export type {
+  IRelyingPartyBearerErrorAnswer,
+  IRelyingPartyBearerLogoutAnswer,
+  IRelyingPartyBearerMessage,
+  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 +48,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 +90,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
@@ -154,27 +172,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 +190,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 +271,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 */