@idp.global/sdk 19.2.0 → 19.3.0

package/ts_relyingparty/classes.rpmodels.ts

@@ -1,5 +1,6 @@
 import * as plugins from './plugins.js';
 import { RelyingPartyDatabaseUnavailableError } from './classes.errors.js';
+import type { TRelyingPartyBearerClientKind } from './interfaces.js';
 
 /**
  * One browser session of a relying party. The persisted field names, their
@@ -62,7 +63,8 @@ export class RelyingPartySessionDoc extends plugins.nosqldb.SmartDataDbDoc<Relyi
  * against, the binding to the browser that started it, the sealed PKCE
  * verifier and the return path. Consumed exactly once by a conditional update.
  * Field names and indexes are the ones nevermind.finance stores under
- * `LoginAttemptDoc`.
+ * `LoginAttemptDoc`; the `bearer…` fields exist only on the attempt of a
+ * bearer login, whose binding token is never issued.
  */
 export class RelyingPartyLoginAttemptDoc extends plugins.nosqldb.SmartDataDbDoc<RelyingPartyLoginAttemptDoc, RelyingPartyLoginAttemptDoc> {
   @plugins.nosqldb.unI()
@@ -103,11 +105,98 @@ export class RelyingPartyLoginAttemptDoc extends plugins.nosqldb.SmartDataDbDoc<
   /** the session the callback created; finalize releases the return path against it */
   @plugins.nosqldb.svDb()
   public createdSessionId?: string | null;
+
+  /** how the bearer client of this login receives its outcome; absent on a cookie login */
+  @plugins.nosqldb.svDb()
+  public bearerClientKind?: TRelyingPartyBearerClientKind;
+
+  /** the return target the bearer client named, exactly */
+  @plugins.nosqldb.svDb()
+  public bearerReturnTarget?: string;
+
+  /** the bearer client's S256 code challenge; its hand-off is claimed with the matching verifier */
+  @plugins.nosqldb.svDb()
+  public bearerCodeChallenge?: string;
+
+  /** the bearer client's own `state`, handed back with the outcome */
+  @plugins.nosqldb.svDb()
+  public bearerClientState?: string;
+}
+
+/**
+ * The single-use code a bearer login hands its client. Only the hash of the
+ * code is stored; the code is bound to the client's S256 challenge, lives at
+ * most a minute and is consumed by one conditional update.
+ */
+export class RelyingPartyBearerHandoffDoc extends plugins.nosqldb.SmartDataDbDoc<RelyingPartyBearerHandoffDoc, RelyingPartyBearerHandoffDoc> {
+  @plugins.nosqldb.unI()
+  public id: string = '';
+
+  /** sha256 of the code */
+  @plugins.nosqldb.unI()
+  public codeHash: string = '';
+
+  /** the session the login opened; the code is its only way out */
+  @plugins.nosqldb.svDb()
+  public sessionId: string = '';
+
+  @plugins.nosqldb.svDb()
+  public codeChallenge: string = '';
+
+  @plugins.nosqldb.svDb()
+  public createdAt: number = 0;
+
+  /** at most a minute after the callback; the sweep ends the session of a code nobody claimed by then */
+  @plugins.nosqldb.svDb()
+  @plugins.nosqldb.index()
+  public expiresAt: number = 0;
+
+  /** `null` until a claim consumes the code */
+  @plugins.nosqldb.svDb()
+  public consumedAt: number | null = null;
+}
+
+/**
+ * One generation of a bearer session's tokens: an access token and the
+ * refresh token that replaces both. Only hashes are stored. Exactly one
+ * generation of a session is current (`rotatedAt` `null`); a rotated one is
+ * kept until the session expires, so its refresh token coming back is
+ * recognized as reuse.
+ */
+export class RelyingPartyBearerTokenDoc extends plugins.nosqldb.SmartDataDbDoc<RelyingPartyBearerTokenDoc, RelyingPartyBearerTokenDoc> {
+  @plugins.nosqldb.unI()
+  public id: string = '';
+
+  @plugins.nosqldb.unI()
+  public accessTokenHash: string = '';
+
+  @plugins.nosqldb.unI()
+  public refreshTokenHash: string = '';
+
+  @plugins.nosqldb.svDb()
+  public sessionId: string = '';
+
+  @plugins.nosqldb.svDb()
+  public createdAt: number = 0;
+
+  @plugins.nosqldb.svDb()
+  public accessTokenExpiresAt: number = 0;
+
+  /** the session's end; the refresh token never outlives it, and the sweep removes the generation after it */
+  @plugins.nosqldb.svDb()
+  @plugins.nosqldb.index()
+  public expiresAt: number = 0;
+
+  /** `null` while this generation is current; when its refresh token was spent otherwise */
+  @plugins.nosqldb.svDb()
+  public rotatedAt: number | null = null;
 }
 
 export const RELYING_PARTY_DEFAULT_COLLECTION_NAMES = {
   sessions: 'IdpRelyingPartySession',
   loginAttempts: 'IdpRelyingPartyLoginAttempt',
+  bearerHandoffs: 'IdpRelyingPartyBearerHandoff',
+  bearerTokens: 'IdpRelyingPartyBearerToken',
 } as const;
 
 export interface IRelyingPartyModelsOptions {
@@ -125,22 +214,37 @@ export interface IRelyingPartyModelsOptions {
   collectionNames?: {
     sessions?: string;
     loginAttempts?: string;
+    bearerHandoffs?: string;
+    bearerTokens?: string;
   };
 }
 
-export interface IRelyingPartyModels {
+/** The models bearer hand-off mode stores its codes and tokens in. */
+export interface IRelyingPartyBearerModels {
+  readonly BearerHandoff: typeof RelyingPartyBearerHandoffDoc;
+  readonly BearerToken: typeof RelyingPartyBearerTokenDoc;
+}
+
+/**
+ * The models of the session layer. The bearer models are needed only when
+ * `RelyingPartySessions` runs with `bearer`; `createRelyingPartyModels`
+ * always binds them.
+ */
+export interface IRelyingPartyModels extends Partial<IRelyingPartyBearerModels> {
   readonly Session: typeof RelyingPartySessionDoc;
   readonly LoginAttempt: typeof RelyingPartyLoginAttemptDoc;
 }
 
 /**
- * Binds the two relying-party models to one database. Each call declares its
+ * Binds the relying-party models to one database. Each call declares its
  * own model classes, so several databases — and several applications in one
  * process — never share a binding. A deferred `db` is resolved on every use,
  * the way `@Collection(() => db)` resolves it; a use before it answers a
  * `SmartdataDb` throws `RelyingPartyDatabaseUnavailableError`.
  */
-export const createRelyingPartyModels = (optionsArg: IRelyingPartyModelsOptions): IRelyingPartyModels => {
+export const createRelyingPartyModels = (
+  optionsArg: IRelyingPartyModelsOptions,
+): IRelyingPartyModels & IRelyingPartyBearerModels => {
   const dbOption = optionsArg.db;
   if (!(dbOption instanceof plugins.nosqldb.SmartdataDb) && typeof dbOption !== 'function') {
     throw new Error('createRelyingPartyModels needs a SmartdataDb of @lossless.org/client/nosqldb or a function answering one');
@@ -163,6 +267,10 @@ export const createRelyingPartyModels = (optionsArg: IRelyingPartyModelsOptions)
   const sessions = optionsArg.collectionNames?.sessions ?? RELYING_PARTY_DEFAULT_COLLECTION_NAMES.sessions;
   const loginAttempts = optionsArg.collectionNames?.loginAttempts
     ?? RELYING_PARTY_DEFAULT_COLLECTION_NAMES.loginAttempts;
+  const bearerHandoffs = optionsArg.collectionNames?.bearerHandoffs
+    ?? RELYING_PARTY_DEFAULT_COLLECTION_NAMES.bearerHandoffs;
+  const bearerTokens = optionsArg.collectionNames?.bearerTokens
+    ?? RELYING_PARTY_DEFAULT_COLLECTION_NAMES.bearerTokens;
 
   @plugins.nosqldb.Collection(resolveDb, { collectionName: sessions })
   class BoundSessionDoc extends RelyingPartySessionDoc {}
@@ -170,5 +278,16 @@ export const createRelyingPartyModels = (optionsArg: IRelyingPartyModelsOptions)
   @plugins.nosqldb.Collection(resolveDb, { collectionName: loginAttempts })
   class BoundLoginAttemptDoc extends RelyingPartyLoginAttemptDoc {}
 
-  return { Session: BoundSessionDoc, LoginAttempt: BoundLoginAttemptDoc };
+  @plugins.nosqldb.Collection(resolveDb, { collectionName: bearerHandoffs })
+  class BoundBearerHandoffDoc extends RelyingPartyBearerHandoffDoc {}
+
+  @plugins.nosqldb.Collection(resolveDb, { collectionName: bearerTokens })
+  class BoundBearerTokenDoc extends RelyingPartyBearerTokenDoc {}
+
+  return {
+    Session: BoundSessionDoc,
+    LoginAttempt: BoundLoginAttemptDoc,
+    BearerHandoff: BoundBearerHandoffDoc,
+    BearerToken: BoundBearerTokenDoc,
+  };
 };

package/ts_relyingparty/helpers.bearer.ts

@@ -0,0 +1,260 @@
+import { sha256, timingSafeEqualString } from './helpers.crypto.js';
+import { sanitizeReturnPath } from './helpers.returnpath.js';
+import type {
+  IRelyingPartyBearerDelivery,
+  IRelyingPartyBearerMessage,
+  IRelyingPartyBearerReturnTargets,
+  TRelyingPartyBearerClientKind,
+} from './interfaces.js';
+
+export const RELYING_PARTY_BEARER_CLIENT_KINDS: readonly TRelyingPartyBearerClientKind[] = Object.freeze([
+  'web',
+  'loopback',
+  'custom_scheme',
+  '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). */
+const CUSTOM_SCHEME = /^[a-z][a-z0-9+-]*(\.[a-z0-9+-]+)+:$/u;
+
+export const isBearerClientKind = (valueArg: unknown): valueArg is TRelyingPartyBearerClientKind =>
+  typeof valueArg === 'string' && (RELYING_PARTY_BEARER_CLIENT_KINDS as readonly string[]).includes(valueArg);
+
+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);
+
+/** The S256 challenge of a verifier: BASE64URL(SHA-256(ASCII(verifier))). */
+export const pkceChallengeOf = (verifierArg: string): string => sha256(verifierArg);
+
+/** Whether a verifier answers a challenge under S256, compared in constant time. */
+export const verifyPkceChallenge = (verifierArg: unknown, challengeArg: string): boolean =>
+  isPkceVerifier(verifierArg) && challengeArg.length > 0 && timingSafeEqualString(pkceChallengeOf(verifierArg), challengeArg);
+
+const parseUrl = (valueArg: string): URL | null => {
+  try {
+    return new URL(valueArg);
+  } catch {
+    return null;
+  }
+};
+
+/** A URL as given, in its canonical form, with nothing that a delivery would have to merge into. */
+const plainUrl = (valueArg: unknown): URL | null => {
+  if (typeof valueArg !== 'string' || valueArg.length === 0 || valueArg.length > MAX_RETURN_TARGET_LENGTH) {
+    return null;
+  }
+  const parsed = parseUrl(valueArg);
+  if (
+    !parsed
+    || parsed.href !== valueArg
+    || parsed.username !== ''
+    || parsed.password !== ''
+    || parsed.search !== ''
+    || parsed.hash !== ''
+  ) {
+    return null;
+  }
+  return parsed;
+};
+
+const configuredTarget = (
+  kindArg: TRelyingPartyBearerClientKind,
+  entryArg: unknown,
+  publicOriginArg: string,
+  loginPathPrefixArg: string,
+): boolean => {
+  // targets are compared exactly; an entry that reads like a wildcard is a mistake, said at once
+  if (typeof entryArg === 'string' && entryArg.includes('*')) {
+    return false;
+  }
+  if (kindArg === 'web') {
+    return typeof entryArg === 'string'
+      && !entryArg.includes('?')
+      && !entryArg.includes('#')
+      && sanitizeReturnPath(entryArg, publicOriginArg, loginPathPrefixArg) === entryArg;
+  }
+  if (kindArg === 'popup') {
+    const parsed = typeof entryArg === 'string' ? parseUrl(entryArg) : null;
+    return parsed !== null
+      && (parsed.protocol === 'https:' || parsed.protocol === 'http:')
+      && parsed.origin === entryArg;
+  }
+  const parsed = plainUrl(entryArg);
+  if (!parsed) {
+    return false;
+  }
+  if (kindArg === 'loopback') {
+    return parsed.protocol === 'http:' && LOOPBACK_HOSTS.includes(parsed.hostname) && parsed.port === '';
+  }
+  return CUSTOM_SCHEME.test(parsed.protocol);
+};
+
+/**
+ * The return targets of a deployment, checked once: every entry has to be
+ * the exact canonical form a client can name, or the configuration is
+ * refused. A target with a query or a fragment is refused too, because the
+ * delivery adds its own query, and so is one with a `*`: nothing is a wildcard.
+ */
+export const normalizeBearerReturnTargets = (
+  targetsArg: IRelyingPartyBearerReturnTargets,
+  publicOriginArg: string,
+  loginPathPrefixArg: string,
+): Readonly<Required<IRelyingPartyBearerReturnTargets>> => {
+  if (!targetsArg || typeof targetsArg !== 'object') {
+    throw new Error('bearer.returnTargets must name the return targets per client kind');
+  }
+  for (const key of Object.keys(targetsArg)) {
+    if (!isBearerClientKind(key)) {
+      throw new Error(`bearer.returnTargets.${key} is no client kind; the kinds are ${RELYING_PARTY_BEARER_CLIENT_KINDS.join(', ')}`);
+    }
+  }
+  const normalized = {} as Record<TRelyingPartyBearerClientKind, readonly string[]>;
+  let any = false;
+  for (const kind of RELYING_PARTY_BEARER_CLIENT_KINDS) {
+    const entries: unknown = targetsArg[kind] ?? [];
+    if (!Array.isArray(entries)) {
+      throw new Error(`bearer.returnTargets.${kind} must be a list`);
+    }
+    for (const entry of entries) {
+      if (!configuredTarget(kind, entry, publicOriginArg, loginPathPrefixArg)) {
+        throw new Error(`bearer.returnTargets.${kind} has an entry that is not an exact ${kind} target: ${JSON.stringify(entry)}`);
+      }
+    }
+    normalized[kind] = Object.freeze([...entries] as string[]);
+    any ||= entries.length > 0;
+  }
+  if (!any) {
+    throw new Error('bearer.returnTargets names no return target');
+  }
+  return Object.freeze(normalized);
+};
+
+/**
+ * Whether a client may name this return target: an entry of its kind,
+ * exactly. A loopback target names its own port, which is the only part
+ * that is not compared; it has to be given in canonical form.
+ */
+export const isBearerReturnTargetAllowed = (
+  targetsArg: Readonly<Required<IRelyingPartyBearerReturnTargets>>,
+  kindArg: TRelyingPartyBearerClientKind,
+  candidateArg: unknown,
+): boolean => {
+  if (typeof candidateArg !== 'string' || candidateArg.length === 0 || candidateArg.length > MAX_RETURN_TARGET_LENGTH) {
+    return false;
+  }
+  const entries = targetsArg[kindArg];
+  if (kindArg !== 'loopback') {
+    return entries.includes(candidateArg);
+  }
+  const parsed = plainUrl(candidateArg);
+  if (!parsed || parsed.protocol !== 'http:' || !LOOPBACK_HOSTS.includes(parsed.hostname) || parsed.port === '') {
+    return false;
+  }
+  return entries.includes(`http://${parsed.hostname}${parsed.pathname}`);
+};
+
+/** RFC 6750 §2.1: the scheme is matched case-insensitively, the token is a b64token. */
+const AUTHORIZATION_BEARER = /^bearer +([A-Za-z0-9._~+/-]+=*)$/iu;
+
+/** The token of an `Authorization: Bearer <token>` header, or `null`. */
+export const parseBearerAuthorization = (headerArg: string | null | undefined): string | null => {
+  if (typeof headerArg !== 'string' || headerArg.length > MAX_RETURN_TARGET_LENGTH) {
+    return null;
+  }
+  return AUTHORIZATION_BEARER.exec(headerArg.trim())?.[1] ?? null;
+};
+
+/** What a delivery hands the client: the code, or why there is none. */
+export type TRelyingPartyBearerOutcome = { code: string } | { error: string };
+
+/** The location a redirect delivery sends the client to, with the outcome and its `state` in the query. */
+export const bearerDeliveryLocation = (
+  deliveryArg: IRelyingPartyBearerDelivery,
+  outcomeArg: TRelyingPartyBearerOutcome,
+  publicOriginArg: string,
+): string => {
+  const location = deliveryArg.clientKind === 'web'
+    ? new URL(deliveryArg.returnTarget, publicOriginArg)
+    : new URL(deliveryArg.returnTarget);
+  if ('code' in outcomeArg) {
+    location.searchParams.set('code', outcomeArg.code);
+  } else {
+    location.searchParams.set('error', outcomeArg.error);
+  }
+  if (deliveryArg.state !== undefined) {
+    location.searchParams.set('state', deliveryArg.state);
+  }
+  return location.href;
+};
+
+/** The message a popup delivery posts. */
+export const bearerDeliveryMessage = (
+  deliveryArg: IRelyingPartyBearerDelivery,
+  outcomeArg: TRelyingPartyBearerOutcome,
+): IRelyingPartyBearerMessage => ({
+  type: RELYING_PARTY_BEARER_MESSAGE_TYPE,
+  ...outcomeArg,
+  ...(deliveryArg.state !== undefined ? { state: deliveryArg.state } : {}),
+});
+
+/** JSON that stays inert inside an HTML element, whatever the strings in it hold. */
+const inertJson = (valueArg: unknown): string =>
+  JSON.stringify(valueArg)
+    .replace(/</gu, '\\u003c')
+    .replace(/>/gu, '\\u003e')
+    .replace(/&/gu, '\\u0026')
+    .replace(/\u2028/gu, '\\u2028')
+    .replace(/\u2029/gu, '\\u2029');
+
+/** The id of the element a popup page keeps its delivery in. */
+export const RELYING_PARTY_BEARER_POPUP_DATA_ID = 'idp-rp-bearer-delivery';
+
+/**
+ * The page of a popup delivery. Its one script, allowed by nonce alone,
+ * posts the message to `window.opener` with the registered origin as the
+ * target origin — never `*` — so a browser hands it to nobody else, and
+ * closes the window. The delivery is data in a JSON block, never script.
+ */
+export const bearerPopupPage = (
+  deliveryArg: IRelyingPartyBearerDelivery,
+  outcomeArg: TRelyingPartyBearerOutcome,
+  nonceArg: string,
+): string => {
+  const data = inertJson({ targetOrigin: deliveryArg.returnTarget, message: bearerDeliveryMessage(deliveryArg, outcomeArg) });
+  const script = [
+    `var delivery = JSON.parse(document.getElementById('${RELYING_PARTY_BEARER_POPUP_DATA_ID}').textContent);`,
+    'if (window.opener) {',
+    '  window.opener.postMessage(delivery.message, delivery.targetOrigin);',
+    '  window.close();',
+    '}',
+  ].join('\n');
+  return [
+    '<!doctype html>',
+    '<html lang="en"><head><meta charset="utf-8"><title>Sign-in</title></head><body>',
+    `<script type="application/json" id="${RELYING_PARTY_BEARER_POPUP_DATA_ID}">${data}</script>`,
+    `<script nonce="${nonceArg}">\n${script}\n</script>`,
+    '<p>The sign-in is complete. You can close this window.</p>',
+    '</body></html>',
+  ].join('\n');
+};
+
+/** The policy of a popup page: its nonce script and nothing else. */
+export const bearerPopupContentSecurityPolicy = (nonceArg: string): string =>
+  `default-src 'none'; script-src 'nonce-${nonceArg}'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'`;

package/ts_relyingparty/index.ts

@@ -3,6 +3,7 @@ export * from './classes.errors.js';
 export * from './helpers.cookies.js';
 export * from './helpers.crypto.js';
 export * from './helpers.returnpath.js';
+export * from './helpers.bearer.js';
 export * from './classes.secretbox.js';
 export * from './classes.idpoidcprovider.js';
 export * from './classes.rpmodels.js';

package/ts_relyingparty/interfaces.ts

@@ -62,6 +62,113 @@ 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
+ * 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;
+}
+
+/**
+ * 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;
@@ -123,7 +230,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 +248,10 @@ 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'
+  /** 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 } : {}),
+  };
+};