@idp.global/sdk 18.0.1 → 18.1.0

package/ts_relyingparty/classes.idpoidcprovider.ts

@@ -0,0 +1,386 @@
+import * as plugins from './plugins.js';
+import {
+  OidcIntrospectionClient,
+  OidcIntrospectionError,
+} from '../ts_server/classes.oidc-introspection-client.js';
+
+export interface IOidcAuthorizationOptions {
+  state: string;
+  nonce: string;
+  pkceVerifier: string;
+}
+
+export interface IOidcCompletionOptions extends IOidcAuthorizationOptions {
+  /** the callback as the application's own public origin saw it */
+  callbackUrl: URL;
+}
+
+/** One organization the provider reports for the subject; display data, not an authorization grant. */
+export interface IOidcOrganizationClaim {
+  id: string;
+  name: string;
+  slug: string;
+  roles: string[];
+}
+
+export interface IOidcCompletion {
+  subject: string;
+  accessToken: string;
+  refreshToken?: string;
+  /** epoch milliseconds; `0` when the token response named no lifetime */
+  accessTokenExpiresAt: number;
+  email?: string;
+  emailVerified: boolean;
+  displayName?: string;
+  organizations: IOidcOrganizationClaim[];
+}
+
+/**
+ * One live observation of a subject's authority in one organization, as
+ * `POST /oauth/introspect` answers it. An inactive answer names no reason:
+ * revoked token, dead login session, removed membership and disconnected app
+ * are deliberately indistinguishable.
+ */
+export interface IOidcOrganizationObservation {
+  active: boolean;
+  /** the sorted membership role keys; empty when inactive */
+  roles: readonly string[];
+  /** the observation's own `exp` in epoch milliseconds; `0` when inactive */
+  expiresAt: number;
+}
+
+export interface IOidcRefreshedTokens {
+  accessToken: string;
+  /** the rotated refresh token; absent when the provider returned none */
+  refreshToken?: string;
+  /** epoch milliseconds; `0` when the token response named no lifetime */
+  accessTokenExpiresAt: number;
+}
+
+/** Why an observation or a refresh could not be made; never why access was refused. */
+export type TOidcAuthorityFailure = 'unavailable' | 'invalid_response';
+
+/** The provider could not be asked, or did not answer in its own contract. The caller fails closed on it. */
+export class OidcAuthorityUnavailableError extends Error {
+  constructor(
+    public readonly reason: TOidcAuthorityFailure,
+    causeArg?: unknown,
+  ) {
+    super('The identity provider could not be observed', { cause: causeArg });
+    this.name = 'OidcAuthorityUnavailableError';
+  }
+}
+
+/** The provider refused the refresh with `invalid_grant`: the refresh family is revoked, expired or was reused. */
+export class OidcRefreshRefusedError extends Error {
+  constructor(causeArg?: unknown) {
+    super('The identity provider refused the refresh', { cause: causeArg });
+    this.name = 'OidcRefreshRefusedError';
+  }
+}
+
+export type TOidcTokenHint = 'access_token' | 'refresh_token';
+
+export type TOidcCompletionFailureStage = 'token_exchange' | 'token_validation' | 'userinfo';
+
+export class OidcCompletionError extends Error {
+  constructor(
+    public readonly stage: TOidcCompletionFailureStage,
+    causeArg: unknown,
+  ) {
+    super('OIDC completion failed', { cause: causeArg });
+    this.name = 'OidcCompletionError';
+  }
+}
+
+/**
+ * What the session layer needs from the provider. `IdpOidcProvider` is the
+ * implementation; tests bind a double to it, so no test opens a socket.
+ */
+export interface IOidcProvider {
+  /**
+   * The deadline of every provider request, in seconds. The refresh lock that
+   * keeps two replicas from spending one refresh token outlives it.
+   */
+  readonly requestTimeoutSeconds: number;
+  init(): Promise<void>;
+  buildAuthorizationUrl(optionsArg: IOidcAuthorizationOptions): Promise<URL>;
+  completeAuthorization(optionsArg: IOidcCompletionOptions): Promise<IOidcCompletion>;
+  revokeToken(tokenArg: string, hintArg: TOidcTokenHint): Promise<void>;
+  /** Throws `OidcAuthorityUnavailableError` rather than guessing an answer. */
+  introspectOrganization(optionsArg: {
+    accessToken: string;
+    subject: string;
+    organizationId: string;
+  }): Promise<IOidcOrganizationObservation>;
+  /** Throws `OidcRefreshRefusedError` on `invalid_grant`, `OidcAuthorityUnavailableError` for everything else. */
+  refreshTokens(refreshTokenArg: string): Promise<IOidcRefreshedTokens>;
+}
+
+/**
+ * The scopes a relying party asks for. `organizations` and `roles` are what
+ * idp.global reports memberships under.
+ */
+export const IDP_OIDC_DEFAULT_SCOPES = 'openid profile email organizations roles';
+
+export const IDP_OIDC_DEFAULT_REQUEST_TIMEOUT_SECONDS = 10;
+
+export interface IIdpOidcProviderOptions {
+  /** the issuer origin, `https://…`; the introspection client refuses anything else */
+  issuer: URL;
+  clientId: string;
+  clientSecret: string;
+  /** the registered callback, on the application's public origin */
+  redirectUri: URL;
+  scopes?: string;
+  /** deadline of discovery, token, UserInfo, refresh and revocation requests */
+  requestTimeoutSeconds?: number;
+  /** deadline of one introspection; the introspection client's default applies when absent */
+  introspectionTimeoutMs?: number;
+}
+
+const optionalString = (valueArg: unknown): string | undefined =>
+  typeof valueArg === 'string' && valueArg.trim().length > 0 ? valueArg.trim() : undefined;
+
+/** When an access token dies, from the `expires_in` of a token response; `0` when it names none. */
+const expiryOf = (expiresInArg: number | undefined): number =>
+  typeof expiresInArg === 'number' && Number.isFinite(expiresInArg) && expiresInArg > 0
+    ? Date.now() + Math.floor(expiresInArg) * 1_000
+    : 0;
+
+/**
+ * Organization claims as idp.global documents them: `id`, `name`, `slug` and
+ * the member's roles. Anything that is not that exact shape is dropped rather
+ * than guessed at.
+ */
+export const readOrganizationClaims = (valueArg: unknown): IOidcOrganizationClaim[] => {
+  if (!Array.isArray(valueArg)) {
+    return [];
+  }
+  const organizations: IOidcOrganizationClaim[] = [];
+  for (const entry of valueArg) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      continue;
+    }
+    const candidate = entry as Record<string, unknown>;
+    const id = optionalString(candidate.id);
+    const name = optionalString(candidate.name);
+    const slug = optionalString(candidate.slug);
+    if (!id || !name || !slug) {
+      continue;
+    }
+    const roles = Array.isArray(candidate.roles)
+      ? candidate.roles.filter((roleArg): roleArg is string => typeof roleArg === 'string')
+      : [];
+    organizations.push({ id, name, slug, roles });
+  }
+  return organizations;
+};
+
+/**
+ * The relying-party side of the authorization code flow with S256 PKCE on
+ * `openid-client`, in the profile idp.global supports: code responses, S256
+ * challenges, RS256 ID tokens and `client_secret_basic` for a confidential
+ * client. Live organization authority is observed with the sdk's
+ * `OidcIntrospectionClient`.
+ */
+export class IdpOidcProvider implements IOidcProvider {
+  public readonly requestTimeoutSeconds: number;
+  readonly #options: IIdpOidcProviderOptions;
+  #configuration?: plugins.openidClient.Configuration;
+  #introspection?: OidcIntrospectionClient;
+
+  constructor(optionsArg: IIdpOidcProviderOptions) {
+    if (!(optionsArg?.issuer instanceof URL) || !(optionsArg.redirectUri instanceof URL)) {
+      throw new Error('IdpOidcProvider needs the issuer and the redirect URI as URLs');
+    }
+    if (!optionalString(optionsArg.clientId) || !optionalString(optionsArg.clientSecret)) {
+      throw new Error('IdpOidcProvider needs a client id and a client secret');
+    }
+    const timeout = optionsArg.requestTimeoutSeconds ?? IDP_OIDC_DEFAULT_REQUEST_TIMEOUT_SECONDS;
+    if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 60) {
+      throw new Error('IdpOidcProvider requestTimeoutSeconds must be an integer from 1 to 60');
+    }
+    this.requestTimeoutSeconds = timeout;
+    this.#options = optionsArg;
+  }
+
+  private get configuration(): plugins.openidClient.Configuration {
+    if (!this.#configuration) {
+      throw new Error('The identity provider is not initialized');
+    }
+    return this.#configuration;
+  }
+
+  public async init(): Promise<void> {
+    if (this.#configuration) {
+      return;
+    }
+    const options = this.#options;
+    // the timeout given to discovery bounds discovery itself and stays on the
+    // resolved configuration for every later request
+    const configuration = await plugins.openidClient.discovery(
+      options.issuer,
+      options.clientId,
+      {
+        client_secret: options.clientSecret,
+        token_endpoint_auth_method: 'client_secret_basic',
+        id_token_signed_response_alg: 'RS256',
+      },
+      plugins.openidClient.ClientSecretBasic(options.clientSecret),
+      { timeout: this.requestTimeoutSeconds },
+    );
+    const metadata = configuration.serverMetadata();
+    if (!metadata.authorization_endpoint || !metadata.token_endpoint || !metadata.jwks_uri) {
+      throw new Error('The identity provider is missing required OIDC endpoints');
+    }
+    if (!metadata.code_challenge_methods_supported?.includes('S256')) {
+      throw new Error('The identity provider must support PKCE S256');
+    }
+    if (
+      metadata.id_token_signing_alg_values_supported
+      && !metadata.id_token_signing_alg_values_supported.includes('RS256')
+    ) {
+      throw new Error('The identity provider must sign ID tokens with RS256');
+    }
+    if (metadata.grant_types_supported && !metadata.grant_types_supported.includes('authorization_code')) {
+      throw new Error('The identity provider must support the authorization_code grant');
+    }
+    if (metadata.grant_types_supported && !metadata.grant_types_supported.includes('refresh_token')) {
+      // without rotation the access token dies long before the session does
+      throw new Error('The identity provider must support the refresh_token grant');
+    }
+    this.#introspection = new OidcIntrospectionClient({
+      issuer: options.issuer.origin,
+      clientId: options.clientId,
+      clientSecret: options.clientSecret,
+      ...(options.introspectionTimeoutMs !== undefined ? { timeoutMs: options.introspectionTimeoutMs } : {}),
+    });
+    this.#configuration = configuration;
+  }
+
+  public async buildAuthorizationUrl(optionsArg: IOidcAuthorizationOptions): Promise<URL> {
+    const codeChallenge = await plugins.openidClient.calculatePKCECodeChallenge(optionsArg.pkceVerifier);
+    return plugins.openidClient.buildAuthorizationUrl(this.configuration, {
+      redirect_uri: this.#options.redirectUri.href,
+      response_type: 'code',
+      scope: this.#options.scopes ?? IDP_OIDC_DEFAULT_SCOPES,
+      code_challenge: codeChallenge,
+      code_challenge_method: 'S256',
+      state: optionsArg.state,
+      nonce: optionsArg.nonce,
+    });
+  }
+
+  public async completeAuthorization(optionsArg: IOidcCompletionOptions): Promise<IOidcCompletion> {
+    let tokens: Awaited<ReturnType<typeof plugins.openidClient.authorizationCodeGrant>>;
+    try {
+      tokens = await plugins.openidClient.authorizationCodeGrant(this.configuration, optionsArg.callbackUrl, {
+        pkceCodeVerifier: optionsArg.pkceVerifier,
+        expectedState: optionsArg.state,
+        expectedNonce: optionsArg.nonce,
+        idTokenExpected: true,
+      });
+    } catch (error) {
+      throw new OidcCompletionError('token_exchange', error);
+    }
+
+    let subject: string;
+    try {
+      const claims = tokens.claims();
+      if (!claims?.sub) {
+        throw new Error('The token response carries no subject');
+      }
+      subject = claims.sub;
+    } catch (error) {
+      throw new OidcCompletionError('token_validation', error);
+    }
+
+    // UserInfo is the current view of profile and organization claims; the ID
+    // token proves the login. Both are read, and the subjects must agree.
+    let userInfo: Awaited<ReturnType<typeof plugins.openidClient.fetchUserInfo>>;
+    try {
+      userInfo = await plugins.openidClient.fetchUserInfo(this.configuration, tokens.access_token, subject);
+    } catch (error) {
+      throw new OidcCompletionError('userinfo', error);
+    }
+    if (userInfo.sub !== subject) {
+      throw new OidcCompletionError('token_validation', new Error('The UserInfo subject does not match the ID token'));
+    }
+
+    return {
+      subject,
+      accessToken: tokens.access_token,
+      ...(tokens.refresh_token ? { refreshToken: tokens.refresh_token } : {}),
+      accessTokenExpiresAt: expiryOf(tokens.expires_in),
+      email: optionalString(userInfo.email),
+      emailVerified: userInfo.email_verified === true,
+      displayName: optionalString(userInfo.name) || optionalString(userInfo.preferred_username),
+      organizations: readOrganizationClaims(Reflect.get(userInfo, 'organizations')),
+    };
+  }
+
+  public async revokeToken(tokenArg: string, hintArg: TOidcTokenHint): Promise<void> {
+    await plugins.openidClient.tokenRevocation(this.configuration, tokenArg, { token_type_hint: hintArg });
+  }
+
+  /**
+   * One `POST /oauth/introspect` through the confidential introspection
+   * client, which validates the whole answer before this code sees it. A
+   * refusal (`active: false`) is an answer; anything else is a failure to
+   * observe.
+   */
+  public async introspectOrganization(optionsArg: {
+    accessToken: string;
+    subject: string;
+    organizationId: string;
+  }): Promise<IOidcOrganizationObservation> {
+    if (!this.#introspection) {
+      throw new Error('The identity provider is not initialized');
+    }
+    let response: Awaited<ReturnType<OidcIntrospectionClient['introspect']>>;
+    try {
+      response = await this.#introspection.introspect({
+        token: optionsArg.accessToken,
+        subject: optionsArg.subject,
+        organizationId: optionsArg.organizationId,
+      });
+    } catch (error) {
+      if (error instanceof OidcIntrospectionError) {
+        if (error.code === 'invalid_request') {
+          // a request the endpoint's own client refuses is a defect of the
+          // caller, never an answer about access
+          throw error;
+        }
+        throw new OidcAuthorityUnavailableError(error.code, error);
+      }
+      throw new OidcAuthorityUnavailableError('unavailable', error);
+    }
+    if (!response.active) {
+      return { active: false, roles: [], expiresAt: 0 };
+    }
+    return {
+      active: true,
+      roles: response.idp_global_authority.roles,
+      expiresAt: response.exp * 1_000,
+    };
+  }
+
+  /** The refresh grant with rotation; a superseded refresh token is never kept by the caller. */
+  public async refreshTokens(refreshTokenArg: string): Promise<IOidcRefreshedTokens> {
+    let tokens: Awaited<ReturnType<typeof plugins.openidClient.refreshTokenGrant>>;
+    try {
+      tokens = await plugins.openidClient.refreshTokenGrant(this.configuration, refreshTokenArg);
+    } catch (error) {
+      if (error instanceof plugins.openidClient.ResponseBodyError && error.error === 'invalid_grant') {
+        throw new OidcRefreshRefusedError(error);
+      }
+      throw new OidcAuthorityUnavailableError('unavailable', error);
+    }
+    return {
+      accessToken: tokens.access_token,
+      ...(tokens.refresh_token ? { refreshToken: tokens.refresh_token } : {}),
+      accessTokenExpiresAt: expiryOf(tokens.expires_in),
+    };
+  }
+}

package/ts_relyingparty/classes.relyingpartyroutes.ts

@@ -0,0 +1,286 @@
+import * as plugins from './plugins.js';
+import { LoginCallbackError, RelyingPartyError, RelyingPartyRefusal } from './classes.errors.js';
+import type { RelyingPartySessions } from './classes.relyingpartysessions.js';
+import type { IResolvedRelyingPartySession } from './interfaces.js';
+
+/**
+ * The part of an HTTP request context the routes read. `IRequestContext` of
+ * `@push.rocks/smartserve` — what a typedserver `IRouteHandler` receives —
+ * satisfies it, so the routes plug into `addRoute()` / `addCustomRoutes()`
+ * without the sdk depending on either package.
+ */
+export interface IRelyingPartyHttpContext {
+  readonly method: string;
+  readonly url: URL;
+  readonly headers: Headers;
+  readonly request: Request;
+}
+
+export interface IRelyingPartyRoutesOptions {
+  sessions: RelyingPartySessions;
+  /** where a sign-in that did not finish sends the browser; no provider text is ever echoed into it */
+  failureLocation: string;
+  /**
+   * Where a refusal of the application (`RelyingPartyRefusal.code`) sends the
+   * browser, so the application can explain it; a refusal not named here is
+   * answered as a failed authentication with its status.
+   */
+  refusalLocations?: Readonly<Record<string, string>>;
+  /**
+   * The body `GET <prefix>session` answers with. Default:
+   * `{ session: { sessionId, principalId, expiresAt, csrfToken } | null }`.
+   */
+  sessionAnswer?(resolvedArg: IResolvedRelyingPartySession | null): Promise<object>;
+  /** the largest logout body read, in bytes; a longer one is cancelled as soon as it passes the limit */
+  maxBodyBytes?: number;
+  /**
+   * diagnostics of a failed start or callback; the default writes one JSON
+   * line to `console.error`. A throwing sink never changes the answer: the
+   * event and its failure go to `console.error` instead.
+   */
+  onRouteEvent?(eventArg: {
+    event: 'auth_login_start_failed' | 'auth_callback_failed' | 'auth_callback_declined' | 'auth_callback_refused';
+    stage?: string;
+    code?: string;
+    correlationId?: string;
+    message?: string;
+  }): void;
+}
+
+const DEFAULT_MAX_BODY_BYTES = 16 * 1024;
+/** What the provider names in a callback it did not issue a code for. */
+const MAX_PROVIDER_ERROR_CODE_LENGTH = 64;
+
+const noStoreHeaders = (headersArg?: Record<string, string>): Headers => {
+  const headers = new Headers(headersArg);
+  headers.set('Cache-Control', 'no-store');
+  headers.set('Pragma', 'no-cache');
+  headers.set('Cross-Origin-Resource-Policy', 'same-origin');
+  return headers;
+};
+
+const jsonResponse = (bodyArg: object, statusArg: number, headersArg?: Record<string, string>): Response => {
+  const headers = noStoreHeaders(headersArg);
+  headers.set('Content-Type', 'application/json; charset=utf-8');
+  return new Response(JSON.stringify(bodyArg), { status: statusArg, headers });
+};
+
+const redirect = (locationArg: string, headersArg?: Record<string, string>): Response =>
+  new Response(null, { status: 302, headers: noStoreHeaders({ Location: locationArg, ...headersArg }) });
+
+/**
+ * The HTTP steps of a relying-party login, all under the sessions' login path
+ * prefix (default `/auth/`):
+ *
+ * - `GET login?return=…` redirects to the provider and sets the intent cookie
+ * - `GET callback` consumes the attempt once and sets the session cookie; a
+ *   provider `error` abandons the attempt
+ * - `GET finalize` releases the return path only to the browser holding the
+ *   session this attempt created
+ * - `GET session` answers the current session
+ * - `POST logout` ends the session; it needs this origin and the CSRF token
+ *
+ * `handle()` answers `null` for every other request, so the application
+ * chains its own routes (a local password login) around it. Cookies are only
+ * ever set here: a `/typedrequest` answer cannot carry `Set-Cookie`.
+ */
+export class RelyingPartyRoutes {
+  readonly #sessions: RelyingPartySessions;
+  readonly #options: IRelyingPartyRoutesOptions;
+  readonly #maxBodyBytes: number;
+
+  constructor(optionsArg: IRelyingPartyRoutesOptions) {
+    this.#sessions = optionsArg.sessions;
+    this.#options = optionsArg;
+    this.#maxBodyBytes = optionsArg.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+  }
+
+  /** The paths the routes answer, for registering them one by one. */
+  public get paths(): { login: string; callback: string; finalize: string; session: string; logout: string } {
+    const prefix = this.#sessions.loginPathPrefix;
+    return {
+      login: prefix + 'login',
+      callback: prefix + 'callback',
+      finalize: prefix + 'finalize',
+      session: prefix + 'session',
+      logout: prefix + 'logout',
+    };
+  }
+
+  public readonly handle = async (contextArg: IRelyingPartyHttpContext): Promise<Response | null> => {
+    const paths = this.paths;
+    const path = contextArg.url.pathname;
+    const method = contextArg.method.toUpperCase();
+    const providerLogin = this.#sessions.providerLoginEnabled;
+
+    if (path === paths.login && method === 'GET' && providerLogin) {
+      return this.login(contextArg);
+    }
+    if (path === paths.callback && method === 'GET' && providerLogin) {
+      return this.callback(contextArg);
+    }
+    if (path === paths.finalize && method === 'GET' && providerLogin) {
+      let location = this.#options.failureLocation;
+      try {
+        location = await this.#sessions.finalizeLogin(contextArg.headers.get('cookie'));
+      } catch {
+        location = this.#options.failureLocation;
+      }
+      return redirect(location, { 'Set-Cookie': this.#sessions.clearIntentCookie() });
+    }
+    if (path === paths.session && method === 'GET') {
+      const resolved = await this.#sessions.resolveCookieSession(contextArg.headers.get('cookie'));
+      return jsonResponse(await this.sessionAnswer(resolved), 200);
+    }
+    if (path === paths.logout && method === 'POST') {
+      return this.logout(contextArg);
+    }
+    return null;
+  };
+
+  private async login(contextArg: IRelyingPartyHttpContext): Promise<Response> {
+    try {
+      const start = await this.#sessions.startLogin(contextArg.url.searchParams.get('return'));
+      return redirect(start.authorizationUrl.href, { 'Set-Cookie': start.intentCookie });
+    } catch (error) {
+      this.emit({ event: 'auth_login_start_failed', message: error instanceof Error ? error.message : String(error) });
+      return jsonResponse({ error: 'authentication_unavailable' }, 503);
+    }
+  }
+
+  private async callback(contextArg: IRelyingPartyHttpContext): Promise<Response> {
+    // the callback is read from the public origin, never from a forwarded host
+    const callbackUrl = new URL(contextArg.url.pathname + contextArg.url.search, this.#sessions.publicOrigin);
+    const cookieHeader = contextArg.headers.get('cookie');
+    const providerError = callbackUrl.searchParams.get('error');
+    if (providerError) {
+      // the user cancelled, or the provider refused: nothing to exchange, and
+      // the attempt is consumed so its state never completes later
+      await this.#sessions.abandonLogin(callbackUrl, cookieHeader);
+      this.emit({ event: 'auth_callback_declined', code: providerError.slice(0, MAX_PROVIDER_ERROR_CODE_LENGTH) });
+      return redirect(this.#options.failureLocation, { 'Set-Cookie': this.#sessions.clearIntentCookie() });
+    }
+    try {
+      const opening = await this.#sessions.completeLogin(callbackUrl, cookieHeader);
+      return redirect(this.paths.finalize, { 'Set-Cookie': opening.sessionCookie });
+    } catch (error) {
+      const clearIntent = { 'Set-Cookie': this.#sessions.clearIntentCookie() };
+      if (error instanceof RelyingPartyRefusal) {
+        this.emit({ event: 'auth_callback_refused', code: error.code });
+        const locations = this.#options.refusalLocations ?? {};
+        if (Object.hasOwn(locations, error.code)) {
+          return redirect(locations[error.code], clearIntent);
+        }
+        return jsonResponse({ error: 'authentication_failed' }, error.status, clearIntent);
+      }
+      const status = error instanceof RelyingPartyError ? error.status : 502;
+      if (status >= 500) {
+        this.emit({
+          event: 'auth_callback_failed',
+          correlationId: plugins.crypto.randomUUID(),
+          stage: error instanceof LoginCallbackError ? error.stage : 'unclassified',
+          message: error instanceof Error ? error.message : String(error),
+        });
+      }
+      return jsonResponse({ error: 'authentication_failed' }, status, clearIntent);
+    }
+  }
+
+  private async logout(contextArg: IRelyingPartyHttpContext): Promise<Response> {
+    if (contextArg.headers.get('origin') !== this.#sessions.publicOrigin) {
+      return jsonResponse({ error: 'forbidden' }, 403);
+    }
+    const clearSession = { 'Set-Cookie': this.#sessions.clearSessionCookie() };
+    const resolved = await this.#sessions.resolveCookieSession(contextArg.headers.get('cookie'));
+    if (!resolved) {
+      return jsonResponse({ endedLiveSession: false }, 200, clearSession);
+    }
+    const body = await this.readJsonBody(contextArg);
+    const csrfToken = body && typeof body === 'object' ? Reflect.get(body, 'csrfToken') : undefined;
+    if (!this.#sessions.validateCsrf(resolved, csrfToken)) {
+      return jsonResponse({ error: 'forbidden' }, 403);
+    }
+    return jsonResponse({ endedLiveSession: await this.#sessions.logout(resolved.session.id) }, 200, clearSession);
+  }
+
+  private async sessionAnswer(resolvedArg: IResolvedRelyingPartySession | null): Promise<object> {
+    if (this.#options.sessionAnswer) {
+      return this.#options.sessionAnswer(resolvedArg);
+    }
+    return {
+      session: resolvedArg
+        ? {
+            sessionId: resolvedArg.session.id,
+            principalId: resolvedArg.session.principalId,
+            expiresAt: resolvedArg.session.expiresAt,
+            csrfToken: resolvedArg.csrfToken,
+          }
+        : null,
+    };
+  }
+
+  /**
+   * A JSON body within `maxBodyBytes`, or `null`. The limit holds while the
+   * body streams, whatever `Content-Length` claims or omits: the read is
+   * cancelled at the first chunk that passes it.
+   */
+  private async readJsonBody(contextArg: IRelyingPartyHttpContext): Promise<unknown> {
+    const declaredLength = Number(contextArg.headers.get('content-length') || 0);
+    if (!Number.isFinite(declaredLength) || declaredLength < 0 || declaredLength > this.#maxBodyBytes) {
+      return null;
+    }
+    const body = contextArg.request.body;
+    if (!body) {
+      return null;
+    }
+    const reader = body.getReader();
+    const chunks: Uint8Array[] = [];
+    let received = 0;
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) {
+          break;
+        }
+        received += value.byteLength;
+        if (received > this.#maxBodyBytes) {
+          await reader.cancel();
+          return null;
+        }
+        chunks.push(value);
+      }
+    } catch {
+      return null;
+    } finally {
+      reader.releaseLock();
+    }
+    try {
+      return JSON.parse(Buffer.concat(chunks, received).toString('utf8')) as unknown;
+    } catch {
+      return null;
+    }
+  }
+
+  private emit(eventArg: Parameters<NonNullable<IRelyingPartyRoutesOptions['onRouteEvent']>>[0]): void {
+    if (!this.#options.onRouteEvent) {
+      console.error(JSON.stringify(eventArg));
+      return;
+    }
+    const reportFailure = (errorArg: unknown) => {
+      console.error(JSON.stringify({
+        event: 'hook_failed',
+        hook: 'onRouteEvent',
+        message: errorArg instanceof Error ? errorArg.message : String(errorArg),
+      }));
+      console.error(JSON.stringify(eventArg));
+    };
+    try {
+      const result: unknown = this.#options.onRouteEvent(eventArg);
+      if (result instanceof Promise) {
+        result.catch(reportFailure);
+      }
+    } catch (error) {
+      reportFailure(error);
+    }
+  }
+}