@idp.global/sdk 19.2.1 → 19.4.0

package/ts_relyingparty/classes.rpmodels.ts

@@ -1,11 +1,13 @@
 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
- * 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()
@@ -26,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 */
@@ -62,7 +66,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 +108,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 +217,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 +270,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 +281,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/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

@@ -0,0 +1,259 @@
+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, IRelyingPartyBearerReturnTargets } from './interfaces.js';
+
+export { RELYING_PARTY_BEARER_MESSAGE_TYPE };
+
+export const RELYING_PARTY_BEARER_CLIENT_KINDS: readonly TRelyingPartyBearerClientKind[] = Object.freeze([
+  'web',
+  'loopback',
+  'custom_scheme',
+  'popup',
+]);
+
+/** 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';