@idp.global/sdk 18.0.0 → 18.1.0

package/ts_relyingparty/classes.rpmodels.ts

@@ -0,0 +1,146 @@
+import * as plugins from './plugins.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.
+ */
+export class RelyingPartySessionDoc extends plugins.nosqldb.SmartDataDbDoc<RelyingPartySessionDoc, RelyingPartySessionDoc> {
+  @plugins.nosqldb.unI()
+  public id: string = '';
+
+  /** sha256 of the cookie token; the token itself is never stored */
+  @plugins.nosqldb.unI()
+  public tokenHash: string = '';
+
+  /** the application's principal (user) this session acts as */
+  @plugins.nosqldb.svDb()
+  @plugins.nosqldb.index()
+  public userId: string = '';
+
+  @plugins.nosqldb.svDb()
+  public createdAt: number = 0;
+
+  @plugins.nosqldb.svDb()
+  public lastSeenAt: number = 0;
+
+  @plugins.nosqldb.svDb()
+  public expiresAt: number = 0;
+
+  /** absent while the session is valid */
+  @plugins.nosqldb.svDb()
+  public revokedAt?: number;
+
+  /** the provider subject of a provider login; absent for a session the application opened itself */
+  @plugins.nosqldb.svDb()
+  public idpSubject?: string;
+
+  /** the login attempt this session came out of; finalize matches it */
+  @plugins.nosqldb.svDb()
+  public loginAttemptId?: string;
+
+  /** sealed with the session encryption key; only the server ever sees the tokens */
+  @plugins.nosqldb.svDb()
+  public sealedAccessToken?: string;
+
+  @plugins.nosqldb.svDb()
+  public sealedRefreshToken?: string;
+
+  /** when the sealed access token dies, epoch milliseconds; `0` when the provider named no lifetime */
+  @plugins.nosqldb.svDb()
+  public accessTokenExpiresAt?: number;
+
+  /** until when one replica holds the right to rotate this session's tokens, epoch milliseconds */
+  @plugins.nosqldb.svDb()
+  public refreshLockUntil?: number;
+}
+
+/**
+ * One browser's sign-in transaction: the state hash the callback is matched
+ * 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`.
+ */
+export class RelyingPartyLoginAttemptDoc extends plugins.nosqldb.SmartDataDbDoc<RelyingPartyLoginAttemptDoc, RelyingPartyLoginAttemptDoc> {
+  @plugins.nosqldb.unI()
+  public id: string = '';
+
+  /** sha256 of the `state` parameter; the parameter itself is never stored */
+  @plugins.nosqldb.unI()
+  public stateHash: string = '';
+
+  /** sha256 of the intent cookie value; binds the callback to the browser that started it */
+  @plugins.nosqldb.unI()
+  public bindingTokenHash: string = '';
+
+  @plugins.nosqldb.svDb()
+  public sealedPkceVerifier: string = '';
+
+  @plugins.nosqldb.svDb()
+  public nonce: string = '';
+
+  /** same-origin path the browser returns to */
+  @plugins.nosqldb.svDb()
+  public returnPath: string = '/';
+
+  @plugins.nosqldb.svDb()
+  public createdAt: number = 0;
+
+  @plugins.nosqldb.svDb()
+  public expiresAt: number = 0;
+
+  /** absent until the callback consumes the attempt; `null` matches "not consumed" in a filter */
+  @plugins.nosqldb.svDb()
+  public consumedAt?: number | null;
+
+  /** the session the callback created; finalize releases the return path against it */
+  @plugins.nosqldb.svDb()
+  public createdSessionId?: string | null;
+}
+
+export const RELYING_PARTY_DEFAULT_COLLECTION_NAMES = {
+  sessions: 'IdpRelyingPartySession',
+  loginAttempts: 'IdpRelyingPartyLoginAttempt',
+} as const;
+
+export interface IRelyingPartyModelsOptions {
+  db: plugins.nosqldb.SmartdataDb;
+  /**
+   * The persisted collection names. An application that already stores these
+   * documents names its existing collections here.
+   */
+  collectionNames?: {
+    sessions?: string;
+    loginAttempts?: string;
+  };
+}
+
+export interface IRelyingPartyModels {
+  readonly Session: typeof RelyingPartySessionDoc;
+  readonly LoginAttempt: typeof RelyingPartyLoginAttemptDoc;
+}
+
+/**
+ * Binds the two 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.
+ */
+export const createRelyingPartyModels = (optionsArg: IRelyingPartyModelsOptions): IRelyingPartyModels => {
+  const db = optionsArg.db;
+  if (!(db instanceof plugins.nosqldb.SmartdataDb)) {
+    throw new Error('createRelyingPartyModels needs a SmartdataDb of @lossless.org/client/nosqldb');
+  }
+  const sessions = optionsArg.collectionNames?.sessions ?? RELYING_PARTY_DEFAULT_COLLECTION_NAMES.sessions;
+  const loginAttempts = optionsArg.collectionNames?.loginAttempts
+    ?? RELYING_PARTY_DEFAULT_COLLECTION_NAMES.loginAttempts;
+
+  @plugins.nosqldb.Collection(() => db, { collectionName: sessions })
+  class BoundSessionDoc extends RelyingPartySessionDoc {}
+
+  @plugins.nosqldb.Collection(() => db, { collectionName: loginAttempts })
+  class BoundLoginAttemptDoc extends RelyingPartyLoginAttemptDoc {}
+
+  return { Session: BoundSessionDoc, LoginAttempt: BoundLoginAttemptDoc };
+};

package/ts_relyingparty/classes.secretbox.ts

@@ -0,0 +1,49 @@
+import * as plugins from './plugins.js';
+
+/**
+ * The persisted format tag of a sealed value. It names the stored layout of
+ * values that already exist and is read as it is; it is not an API version.
+ */
+const SEALED_FORMAT = 'v1';
+const ALGORITHM = 'aes-256-gcm';
+const IV_LENGTH = 12;
+const TAG_LENGTH = 16;
+
+/**
+ * Seals small secrets at rest — the PKCE verifier of a login attempt and the
+ * provider tokens of a session — with AES-256-GCM under a 32-byte deployment
+ * key. The sealed form is `v1:<base64url iv>:<base64url tag>:<base64url
+ * ciphertext>`, the form nevermind.finance has stored since before this module
+ * existed, so its sealed values open here unchanged.
+ */
+export class SecretBox {
+  readonly #key: Buffer;
+
+  constructor(keyArg: Buffer) {
+    if (!Buffer.isBuffer(keyArg) || keyArg.length !== 32) {
+      throw new Error('SecretBox needs a 32 byte key');
+    }
+    this.#key = Buffer.from(keyArg);
+  }
+
+  public seal(plainArg: string): string {
+    const iv = plugins.crypto.randomBytes(IV_LENGTH);
+    const cipher = plugins.crypto.createCipheriv(ALGORITHM, this.#key, iv, { authTagLength: TAG_LENGTH });
+    const ciphertext = Buffer.concat([cipher.update(plainArg, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return [SEALED_FORMAT, iv.toString('base64url'), tag.toString('base64url'), ciphertext.toString('base64url')].join(':');
+  }
+
+  /** The plain value, or a throw: another format, another key, or a changed byte. */
+  public open(sealedArg: string): string {
+    const [format, ivText, tagText, cipherText] = sealedArg.split(':');
+    if (format !== SEALED_FORMAT || !ivText || !tagText || cipherText === undefined) {
+      throw new Error('Sealed secret has an unknown format');
+    }
+    const decipher = plugins.crypto.createDecipheriv(ALGORITHM, this.#key, Buffer.from(ivText, 'base64url'), {
+      authTagLength: TAG_LENGTH,
+    });
+    decipher.setAuthTag(Buffer.from(tagText, 'base64url'));
+    return Buffer.concat([decipher.update(Buffer.from(cipherText, 'base64url')), decipher.final()]).toString('utf8');
+  }
+}

package/ts_relyingparty/classes.socketbinding.ts

@@ -0,0 +1,142 @@
+import * as plugins from './plugins.js';
+import type { RelyingPartySessions } from './classes.relyingpartysessions.js';
+import { sha256, timingSafeEqualString } from './helpers.crypto.js';
+import type { IRelyingPartySession } from './interfaces.js';
+
+/** The part of a server `TypedSocket` the binding uses. */
+export type TRelyingPartySocketTransport = Pick<
+  plugins.typedsocket.TypedSocket,
+  'setServerTag' | 'findAllTargetConnectionsByTag'
+>;
+
+export type TRelyingPartySocketConnection = plugins.typedsocket.ISmartServeConnectionWrapper;
+
+/** What a browser connection is pinned to for its whole life; no cookie and no CSRF token is kept. */
+export interface IRelyingPartyPinnedSession {
+  sessionId: string;
+  principalId: string;
+  /** SHA-256 of the CSRF token the registration proved */
+  csrfTokenHash: string;
+}
+
+export interface IRelyingPartySocketRefusal {
+  code: 'invalid_input' | 'forbidden' | 'unauthorized';
+  status: number;
+}
+
+export type TRelyingPartySocketRegistration =
+  | { registered: true; pinned: IRelyingPartyPinnedSession; expiresAt: number }
+  | { registered: false; refusal: IRelyingPartySocketRefusal };
+
+export interface IRelyingPartySocketBindingOptions {
+  sessions: RelyingPartySessions;
+  /** the transport typedserver created; `undefined` before the server runs */
+  transport: () => TRelyingPartySocketTransport | undefined;
+  /** the server-owned tag prefix that finds the connections of a session */
+  tagPrefix?: string;
+}
+
+/**
+ * Binds typed socket connections to relying-party browser sessions. A
+ * connection registers once with the CSRF token of the page; the proof is the
+ * upgrade's own `Origin` and `Cookie` — which only a browser on this origin
+ * sends — plus the token, and the connection is pinned to the session. Every
+ * later request re-validates the session with the same strength as an HTTP
+ * request. Connection limits, rate limits and sweeps belong to the
+ * application's socket gate.
+ */
+export class RelyingPartySocketBinding {
+  readonly #sessions: RelyingPartySessions;
+  readonly #transport: () => TRelyingPartySocketTransport | undefined;
+  public readonly tagPrefix: string;
+
+  constructor(optionsArg: IRelyingPartySocketBindingOptions) {
+    this.#sessions = optionsArg.sessions;
+    this.#transport = optionsArg.transport;
+    this.tagPrefix = optionsArg.tagPrefix ?? 'idp_rp_session:';
+  }
+
+  /** The upgrade headers a connection arrived with. */
+  public upgradeOf(connectionArg: TRelyingPartySocketConnection): { origin: string | null; cookie: string | null } {
+    const headers = connectionArg.peer.context.headers;
+    return { origin: headers.get('origin'), cookie: headers.get('cookie') };
+  }
+
+  /**
+   * What a registration payload `{ csrfToken }` proves, given the upgrade it
+   * came on. No connection state is touched, so the application decides about
+   * its limits between this answer and `tagConnection`.
+   */
+  public async resolveBrowserRegistration(
+    payloadArg: unknown,
+    upgradeArg: { origin: string | null; cookie: string | null },
+  ): Promise<TRelyingPartySocketRegistration> {
+    if (!payloadArg || typeof payloadArg !== 'object' || !Reflect.has(payloadArg, 'csrfToken')) {
+      return { registered: false, refusal: { code: 'invalid_input', status: 400 } };
+    }
+    if (upgradeArg.origin !== this.#sessions.publicOrigin) {
+      return { registered: false, refusal: { code: 'forbidden', status: 403 } };
+    }
+    const resolved = await this.#sessions.resolveCookieSession(upgradeArg.cookie);
+    if (!resolved) {
+      return { registered: false, refusal: { code: 'unauthorized', status: 401 } };
+    }
+    if (!this.#sessions.validateCsrf(resolved, Reflect.get(payloadArg, 'csrfToken'))) {
+      return { registered: false, refusal: { code: 'forbidden', status: 403 } };
+    }
+    return {
+      registered: true,
+      pinned: {
+        sessionId: resolved.session.id,
+        principalId: resolved.session.principalId,
+        csrfTokenHash: sha256(resolved.csrfToken),
+      },
+      expiresAt: resolved.session.expiresAt,
+    };
+  }
+
+  public tagOf(sessionIdArg: string): string {
+    return this.tagPrefix + sessionIdArg;
+  }
+
+  /** Tags a connection with its session; throws when the transport is not running or the connection is gone. */
+  public tagConnection(connectionArg: TRelyingPartySocketConnection, sessionIdArg: string): void {
+    const transport = this.#transport();
+    if (!transport) {
+      throw new Error('The socket transport is not running');
+    }
+    transport.setServerTag(connectionArg, this.tagOf(sessionIdArg));
+  }
+
+  /**
+   * The pinned session as it stands right now: re-read, live, its principal
+   * active and unchanged, touched under the liveness it was read with. The
+   * browser keeps proving itself with its CSRF token, compared against the
+   * hash the registration kept. Nothing of this is cached.
+   */
+  public async revalidate(
+    pinnedArg: IRelyingPartyPinnedSession,
+  ): Promise<{ session: IRelyingPartySession; verifyCsrf(candidateArg: unknown): boolean } | null> {
+    const session = await this.#sessions.revalidateSession(pinnedArg.sessionId);
+    if (!session || session.principalId !== pinnedArg.principalId) {
+      return null;
+    }
+    const expectedHash = pinnedArg.csrfTokenHash;
+    return {
+      session,
+      verifyCsrf: (candidateArg) =>
+        typeof candidateArg === 'string'
+        && expectedHash.length > 0
+        && timingSafeEqualString(expectedHash, sha256(candidateArg)),
+    };
+  }
+
+  /** The live connections of one session, for closing them when it ends. */
+  public async connectionsOfSession(sessionIdArg: string): Promise<readonly TRelyingPartySocketConnection[]> {
+    const transport = this.#transport();
+    if (!transport) {
+      return [];
+    }
+    return transport.findAllTargetConnectionsByTag(this.tagOf(sessionIdArg));
+  }
+}

package/ts_relyingparty/helpers.cookies.ts

@@ -0,0 +1,79 @@
+export interface ICookieOptions {
+  httpOnly?: boolean;
+  maxAgeSeconds?: number;
+  sameSite?: 'Lax' | 'Strict' | 'None';
+  secure?: boolean;
+}
+
+// Control characters, space, DEL and the cookie delimiters are never valid.
+const isInvalidCookieCharacter = (characterArg: string): boolean => {
+  const code = characterArg.charCodeAt(0);
+  return code <= 0x20 || code === 0x7f || characterArg === ';' || characterArg === ',';
+};
+
+const assertCookiePart = (valueArg: string, labelArg: string): void => {
+  if (!valueArg || Array.from(valueArg).some(isInvalidCookieCharacter)) {
+    throw new Error('Invalid cookie ' + labelArg);
+  }
+};
+
+/** The cookies of a `Cookie` header; the first value of a repeated name wins, an undecodable value is skipped. */
+export const parseCookies = (cookieHeaderArg: string | null | undefined): Map<string, string> => {
+  const result = new Map<string, string>();
+  if (!cookieHeaderArg) {
+    return result;
+  }
+  for (const part of cookieHeaderArg.split(';')) {
+    const separatorIndex = part.indexOf('=');
+    if (separatorIndex <= 0) {
+      continue;
+    }
+    const name = part.slice(0, separatorIndex).trim();
+    const encodedValue = part.slice(separatorIndex + 1).trim();
+    if (!name || result.has(name)) {
+      continue;
+    }
+    try {
+      result.set(name, decodeURIComponent(encodedValue));
+    } catch {
+      continue;
+    }
+  }
+  return result;
+};
+
+/** One `Set-Cookie` value, always `Path=/` and never with a `Domain`, so a `__Host-` name stays valid. */
+export const serializeCookie = (
+  nameArg: string,
+  valueArg: string,
+  optionsArg: ICookieOptions = {},
+): string => {
+  assertCookiePart(nameArg, 'name');
+  assertCookiePart(valueArg, 'value');
+  const parts = [nameArg + '=' + encodeURIComponent(valueArg), 'Path=/'];
+  if (optionsArg.httpOnly) {
+    parts.push('HttpOnly');
+  }
+  if (optionsArg.secure) {
+    parts.push('Secure');
+  }
+  if (optionsArg.sameSite) {
+    parts.push('SameSite=' + optionsArg.sameSite);
+  }
+  if (optionsArg.maxAgeSeconds !== undefined) {
+    if (!Number.isSafeInteger(optionsArg.maxAgeSeconds) || optionsArg.maxAgeSeconds < 0) {
+      throw new Error('Invalid cookie max age');
+    }
+    parts.push('Max-Age=' + optionsArg.maxAgeSeconds);
+  }
+  return parts.join('; ');
+};
+
+export const serializeClearedCookie = (
+  nameArg: string,
+  optionsArg: Omit<ICookieOptions, 'maxAgeSeconds'> = {},
+): string =>
+  serializeCookie(nameArg, 'deleted', {
+    ...optionsArg,
+    maxAgeSeconds: 0,
+  }) + '; Expires=Thu, 01 Jan 1970 00:00:00 GMT';

package/ts_relyingparty/helpers.crypto.ts

@@ -0,0 +1,49 @@
+import * as plugins from './plugins.js';
+
+/** A 32-byte key given as base64 or base64url; anything else is refused by `labelArg`, never echoed. */
+export const decodeSecretKey = (valueArg: string, labelArg: string): Buffer => {
+  const normalized = typeof valueArg === 'string' ? valueArg.trim() : '';
+  if (!normalized) {
+    throw new Error(labelArg + ' must not be empty');
+  }
+  const base64Normalized = normalized
+    .replace(/-/gu, '+')
+    .replace(/_/gu, '/')
+    .replace(/=+$/u, '');
+  const decoded = Buffer.from(normalized, 'base64');
+  if (
+    decoded.length !== 32
+    || decoded.toString('base64').replace(/=+$/u, '') !== base64Normalized
+  ) {
+    throw new Error(labelArg + ' must decode to exactly 32 bytes');
+  }
+  return decoded;
+};
+
+export const randomToken = (byteLengthArg: number = 32): string =>
+  plugins.crypto.randomBytes(byteLengthArg).toString('base64url');
+
+/** base64url SHA-256 of a UTF-8 string; how tokens, states and bindings are stored. */
+export const sha256 = (valueArg: string): string =>
+  plugins.crypto.createHash('sha256').update(valueArg, 'utf8').digest('base64url');
+
+export const timingSafeEqualString = (leftArg: string, rightArg: string): boolean => {
+  const left = Buffer.from(leftArg, 'utf8');
+  const right = Buffer.from(rightArg, 'utf8');
+  if (left.length !== right.length) {
+    return false;
+  }
+  return plugins.crypto.timingSafeEqual(left, right);
+};
+
+/**
+ * The CSRF token of a session: an HMAC of the session cookie token under the
+ * deployment's CSRF key, after a label that separates this use of the key from
+ * any other. It is derived again on every request and never stored.
+ */
+export const deriveCsrfToken = (sessionTokenArg: string, csrfKeyArg: Buffer, labelArg: string): string =>
+  plugins.crypto
+    .createHmac('sha256', csrfKeyArg)
+    .update(labelArg, 'utf8')
+    .update(sessionTokenArg, 'utf8')
+    .digest('base64url');

package/ts_relyingparty/helpers.returnpath.ts

@@ -0,0 +1,44 @@
+/** A return path is a location the application produced, not a place to park data. */
+const MAX_RETURN_PATH_LENGTH = 1_024;
+
+/**
+ * The one path a login may return to, judged on the normalized result and
+ * never on the shape of the input: `/.//evil.com` parses on this origin but
+ * normalizes to `//evil.com`, which a browser reads as another host. Everything
+ * that is not a plain same-origin path outside the login routes — a scheme, a
+ * host, a backslash, a control character, an overlong value, a path under
+ * `loginPathPrefixArg` — becomes `/`.
+ */
+export const sanitizeReturnPath = (
+  returnPathArg: unknown,
+  publicOriginArg: string,
+  loginPathPrefixArg: string,
+): string => {
+  const candidate = typeof returnPathArg === 'string' ? returnPathArg.trim() : '';
+  if (
+    !candidate.startsWith('/')
+    || candidate.length > MAX_RETURN_PATH_LENGTH
+    || candidate.includes('\\')
+    // the URL parser drops tabs and newlines silently; such a path is refused instead of mangled
+    || /\p{Cc}/u.test(candidate)
+  ) {
+    return '/';
+  }
+  const loginRoot = loginPathPrefixArg.endsWith('/') ? loginPathPrefixArg.slice(0, -1) : loginPathPrefixArg;
+  try {
+    const parsed = new URL(candidate, publicOriginArg);
+    if (parsed.origin !== publicOriginArg) {
+      return '/';
+    }
+    if (parsed.pathname === loginRoot || parsed.pathname.startsWith(loginRoot + '/')) {
+      return '/';
+    }
+    const normalized = parsed.pathname + parsed.search + parsed.hash;
+    if (!normalized.startsWith('/') || normalized.startsWith('//') || normalized.includes('\\')) {
+      return '/';
+    }
+    return normalized;
+  } catch {
+    return '/';
+  }
+};

package/ts_relyingparty/index.ts

@@ -0,0 +1,13 @@
+export * from './interfaces.js';
+export * from './classes.errors.js';
+export * from './helpers.cookies.js';
+export * from './helpers.crypto.js';
+export * from './helpers.returnpath.js';
+export * from './classes.secretbox.js';
+export * from './classes.idpoidcprovider.js';
+export * from './classes.rpmodels.js';
+export * from './classes.relyingpartysessions.js';
+export * from './classes.authorityobserver.js';
+export * from './classes.relyingpartyroutes.js';
+export * from './classes.actorscope.js';
+export * from './classes.socketbinding.js';

package/ts_relyingparty/interfaces.ts

@@ -0,0 +1,133 @@
+import type { IOidcCompletion, TOidcCompletionFailureStage, TOidcTokenHint } from './classes.idpoidcprovider.js';
+
+/** A session as the application reads it; no token and no sealed value is part of it. */
+export interface IRelyingPartySession {
+  id: string;
+  /** the application's principal (user) the session acts as */
+  principalId: string;
+  createdAt: number;
+  lastSeenAt: number;
+  expiresAt: number;
+  /** the provider subject; absent for a session the application opened itself */
+  idpSubject?: string;
+  loginAttemptId?: string;
+}
+
+/** A live session behind a cookie, with the CSRF token derived for it. */
+export interface IResolvedRelyingPartySession {
+  session: IRelyingPartySession;
+  csrfToken: string;
+}
+
+/** A session just opened: the answer, the CSRF token and the `Set-Cookie` value that carries it. */
+export interface IRelyingPartySessionOpening extends IResolvedRelyingPartySession {
+  sessionCookie: string;
+}
+
+/** The redirect that starts a provider login, and the cookie that binds it to this browser. */
+export interface IRelyingPartyLoginStart {
+  authorizationUrl: URL;
+  intentCookie: 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;
+}
+
+/** What an authority observer needs from the session owner. `RelyingPartySessions` implements it. */
+export interface IAuthorityTokenSource {
+  /**
+   * The access token of a login session, rotated first when it is due. The
+   * session must belong to `expectedPrincipalIdArg`. Throws `AuthorityTokenError`.
+   */
+  liveProviderToken(sessionIdArg: string, expectedPrincipalIdArg: string): Promise<IProviderToken>;
+}
+
+/**
+ * The application's side of a provider login: who the verified subject is
+ * here. `admit` creates or updates the local principal (and whatever the
+ * application projects from the organization claims) and answers its id, or
+ * throws `RelyingPartyRefusal` to refuse the login; the provider tokens are
+ * then handed back and the refusal reaches the caller unchanged.
+ */
+export interface IRelyingPartyPrincipals {
+  admit(completionArg: IOidcCompletion): Promise<{ principalId: string }>;
+  /** Whether a principal may act right now; a session of an inactive principal resolves to nothing. */
+  isActive(principalIdArg: string): Promise<boolean>;
+}
+
+export type TRelyingPartySessionEndReason =
+  /** the application or the user ended it */
+  | 'logout'
+  /** the provider refused to rotate its tokens: the login is over there */
+  | 'refresh_token_refused'
+  /** its refresh token was sealed under a key this deployment no longer has */
+  | 'sealed_refresh_token_unreadable'
+  /** 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';
+
+export type TRelyingPartyEventName =
+  | 'idp_token_refresh_failed'
+  | 'idp_token_store_failed'
+  | 'idp_session_ended'
+  | 'oidc_sealed_token_unreadable'
+  | 'oidc_token_revocation_failed'
+  | 'oidc_token_revocation_timed_out'
+  | 'login_attempt_sweep_failed'
+  /** 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 */
+  | 'session_discard_failed';
+
+/** The application hooks whose failures `hook_failed` names. */
+export type TRelyingPartyHookName = 'onProviderSessionOpened' | 'onSessionEnded' | 'onEvent';
+
+/** One structured diagnostic line. It never carries a token, a cookie or a sealed value. */
+export interface IRelyingPartyEvent {
+  event: TRelyingPartyEventName;
+  sessionId?: string;
+  reason?: string;
+  hint?: TOidcTokenHint;
+  hook?: TRelyingPartyHookName;
+  message?: string;
+}
+
+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.
+   */
+  onProviderSessionOpened?(eventArg: { session: IRelyingPartySession }): 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.
+   */
+  onSessionEnded?(eventArg: {
+    sessionId: string;
+    reason: TRelyingPartySessionEndReason;
+    revokedHere: boolean;
+  }): void;
+  /**
+   * Structured diagnostics; the default writes one JSON line to
+   * `console.error`. A throwing sink never interrupts the step that reported:
+   * the event and a `hook_failed` line go to `console.error` instead.
+   */
+  onEvent?(eventArg: IRelyingPartyEvent): void;
+}
+
+/** Where a failed login callback stopped; for the log, never for the browser. */
+export type TLoginCallbackStage =
+  | TOidcCompletionFailureStage
+  | 'attempt_persistence'
+  | 'principal_admission'
+  | 'session_persistence';

package/ts_relyingparty/plugins.ts

@@ -0,0 +1,17 @@
+import * as asyncHooks from 'node:async_hooks';
+import * as crypto from 'node:crypto';
+
+export { asyncHooks, crypto };
+
+import * as typedrequest from '@api.global/typedrequest';
+import * as typedsocket from '@api.global/typedsocket';
+
+export { typedrequest, typedsocket };
+
+import * as nosqldb from '@lossless.org/client/nosqldb';
+
+export { nosqldb };
+
+import * as openidClient from 'openid-client';
+
+export { openidClient };