@idp.global/sdk 19.2.1 → 19.4.0

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,12 +90,99 @@ export interface IRelyingPartyLoginStart {
   intentCookie: string;
 }
 
+/**
+ * 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
+ * or pattern; a loopback target matches on any port.
+ */
+export interface IRelyingPartyBearerReturnTargets {
+  /** same-origin paths such as `/signed-in`, without query or fragment */
+  web?: readonly string[];
+  /** `http://127.0.0.1/<path>` or `http://[::1]/<path>` without a port; the client names its own port */
+  loopback?: readonly string[];
+  /** whole URIs of a private-use scheme with a dot in it, such as `com.example.app:/signed-in`, without query or fragment */
+  custom_scheme?: readonly string[];
+  /** bare origins such as `https://workspace.example`; the popup posts to exactly the one its client named */
+  popup?: readonly string[];
+}
+
+/**
+ * Bearer hand-off mode: the application's own clients sign in through this
+ * relying party and receive its own access and refresh tokens instead of a
+ * cookie.
+ */
+export interface IRelyingPartyBearerOptions {
+  returnTargets: IRelyingPartyBearerReturnTargets;
+  /** how long an access token lives, in seconds; 900 by default, never past its session */
+  accessTokenMaxAgeSeconds?: number;
+}
+
+/** What a bearer client sends to start its login. Every field is checked as untrusted input. */
+export interface IRelyingPartyBearerLoginRequest {
+  clientKind: TRelyingPartyBearerClientKind;
+  /** one of the configured return targets of the kind, exactly; a loopback target with the client's port */
+  returnTarget: string;
+  /** BASE64URL(SHA-256(code verifier)), 43 characters */
+  codeChallenge: string;
+  /** only `S256` is accepted */
+  codeChallengeMethod: '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 redirect that starts a bearer login. It sets no cookie. */
+export interface IRelyingPartyBearerLoginStart {
+  authorizationUrl: URL;
+}
+
+/** Where the outcome of a bearer login goes, as its client named it at the start. */
+export interface IRelyingPartyBearerDelivery {
+  clientKind: TRelyingPartyBearerClientKind;
+  returnTarget: string;
+  /** the client's `state`, when it gave one */
+  state?: string;
+}
+
+/**
+ * A bearer login that came back from the provider: its session is open, and
+ * its single-use code is what the client claims the tokens with. The code is
+ * no token; only its hash is stored.
+ */
+export interface IRelyingPartyBearerHandoff {
+  session: IRelyingPartySession;
+  delivery: IRelyingPartyBearerDelivery;
+  code: string;
+  /** epoch milliseconds, at most `BEARER_HANDOFF_MAX_AGE_SECONDS` after the callback */
+  expiresAt: 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.
+ */
+export interface IRelyingPartyBearerTokens {
+  session: IRelyingPartySession;
+  /** epoch milliseconds on the relying party's clock; a client with another clock counts from it */
+  issuedAt: number;
+  accessToken: string;
+  /** epoch milliseconds */
+  accessTokenExpiresAt: number;
+  refreshToken: string;
+  /** epoch milliseconds: the end of the session, which no refresh extends */
+  refreshTokenExpiresAt: number;
+}
+
 /** 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. */
@@ -75,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>;
 }
 
 /**
@@ -123,7 +251,15 @@ export type TRelyingPartySessionEndReason =
   /** its access token is dead and there is nothing to rotate it with */
   | 'access_token_unusable'
   /** a rotation found it revoked by someone else */
-  | 'revoked_elsewhere';
+  | 'revoked_elsewhere'
+  /** its bearer hand-off code expired before a client claimed it */
+  | 'handoff_unclaimed'
+  /** its bearer hand-off code was claimed with a verifier that does not match its challenge */
+  | 'handoff_verifier_mismatch'
+  /** its bearer hand-off code came back after it was claimed */
+  | 'handoff_code_reused'
+  /** a bearer refresh token that was already rotated came back: the whole family ends */
+  | 'refresh_token_reused';
 
 export type TRelyingPartyEventName =
   | 'idp_token_refresh_failed'
@@ -133,6 +269,12 @@ export type TRelyingPartyEventName =
   | 'oidc_token_revocation_failed'
   | 'oidc_token_revocation_timed_out'
   | '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 */
   | 'hook_failed'
   /** a session whose opening failed could not be revoked; its provider tokens went back anyway */

package/ts_relyingparty/testing.ts

@@ -12,6 +12,8 @@ import {
   type IOidcRefreshedTokens,
   type TOidcTokenHint,
 } from './classes.idpoidcprovider.js';
+import { pkceChallengeOf, RELYING_PARTY_BEARER_POPUP_DATA_ID } from './helpers.bearer.js';
+import type { IRelyingPartyBearerMessage } from './interfaces.js';
 
 /**
  * `@idp.global/sdk/relyingparty/testing`: an in-process idp.global for the
@@ -350,3 +352,61 @@ export class RelyingPartyProviderDouble implements IOidcProvider {
     return !tokenArg.revoked && (tokenArg.expiresAt === 0 || tokenArg.expiresAt > this.#now());
   }
 }
+
+// ---- bearer clients ----
+
+/** A PKCE pair as a bearer client makes one: the verifier it keeps and the S256 challenge it sends. */
+export const createBearerPkcePair = (): { verifier: string; challenge: string } => {
+  const verifier = plugins.crypto.randomBytes(32).toString('base64url');
+  return { verifier, challenge: pkceChallengeOf(verifier) };
+};
+
+/** What a bearer delivery handed its client. */
+export interface IBearerDeliveryRead {
+  /** a redirect: its location without the query; a popup page: the origin it posts to */
+  target: string;
+  /** the popup page's message as it would be posted; absent for a redirect */
+  message?: IRelyingPartyBearerMessage;
+  code?: string;
+  error?: string;
+  state?: string;
+}
+
+const POPUP_DATA = new RegExp(
+  `<script type="application/json" id="${RELYING_PARTY_BEARER_POPUP_DATA_ID}">([^<]*)</script>`,
+  'u',
+);
+
+/**
+ * Reads the answer of a bearer login's callback the way its client would:
+ * the `code`, `error` and `state` of a redirect's location, or the message
+ * and target origin of a popup page. Anything else throws.
+ */
+export const readBearerDelivery = async (responseArg: Response): Promise<IBearerDeliveryRead> => {
+  const location = responseArg.headers.get('location');
+  if (responseArg.status === 302 && location) {
+    const url = new URL(location);
+    const read: IBearerDeliveryRead = { target: '' };
+    for (const name of ['code', 'error', 'state'] as const) {
+      const value = url.searchParams.get(name);
+      if (value !== null) {
+        read[name] = value;
+      }
+    }
+    url.search = '';
+    read.target = url.href;
+    return read;
+  }
+  const data = responseArg.status === 200 ? POPUP_DATA.exec(await responseArg.text())?.[1] : undefined;
+  if (data === undefined) {
+    throw new Error(`readBearerDelivery: a response with status ${responseArg.status} is no bearer delivery`);
+  }
+  const delivery = JSON.parse(data) as { targetOrigin: string; message: IRelyingPartyBearerMessage };
+  return {
+    target: delivery.targetOrigin,
+    message: delivery.message,
+    ...(delivery.message.code !== undefined ? { code: delivery.message.code } : {}),
+    ...(delivery.message.error !== undefined ? { error: delivery.message.error } : {}),
+    ...(delivery.message.state !== undefined ? { state: delivery.message.state } : {}),
+  };
+};