@idp.global/sdk 18.0.1 → 18.2.0

package/ts_relyingparty/classes.relyingpartyroutes.ts

@@ -0,0 +1,319 @@
+import * as plugins from './plugins.js';
+import { LoginCallbackError, RelyingPartyError, RelyingPartyRefusal } from './classes.errors.js';
+import type { RelyingPartySessions } from './classes.relyingpartysessions.js';
+import type { IRelyingPartySession, 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<TPrincipal extends object | undefined = undefined> {
+  sessions: RelyingPartySessions<TPrincipal>;
+  /** 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<TPrincipal> | null): Promise<object>;
+  /**
+   * A `POST <prefix>logout` passed the origin and CSRF checks and the session
+   * was ended. Awaited before the answer, so an audit record is written
+   * before the browser learns the logout is done. `endedLiveSession` is `true`
+   * only when this call ended a live session; a logout that lost a race to
+   * another end answers `false` and records nothing. The session is already
+   * over when this runs: a throw (or a rejection) never keeps it alive and
+   * never changes the answer — it is reported as a `hook_failed` route event.
+   */
+  onLogout?(eventArg: { session: IRelyingPartySession; endedLiveSession: boolean }): Promise<void>;
+  /** 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'
+      /** an application hook of the routes threw; the step it belonged to is complete */
+      | 'hook_failed';
+    hook?: 'onLogout';
+    sessionId?: string;
+    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,
+ *   and `onLogout` runs before it answers
+ *
+ * `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<TPrincipal extends object | undefined = undefined> {
+  readonly #sessions: RelyingPartySessions<TPrincipal>;
+  readonly #options: IRelyingPartyRoutesOptions<TPrincipal>;
+  readonly #maxBodyBytes: number;
+
+  constructor(optionsArg: IRelyingPartyRoutesOptions<TPrincipal>) {
+    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);
+    }
+    // the session ends first: whatever the hook does, it cannot keep it alive
+    const endedLiveSession = await this.#sessions.logout(resolved.session.id);
+    if (this.#options.onLogout) {
+      try {
+        await this.#options.onLogout({ session: resolved.session, endedLiveSession });
+      } catch (error) {
+        this.emit({
+          event: 'hook_failed',
+          hook: 'onLogout',
+          sessionId: resolved.session.id,
+          message: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+    return jsonResponse({ endedLiveSession }, 200, clearSession);
+  }
+
+  private async sessionAnswer(resolvedArg: IResolvedRelyingPartySession<TPrincipal> | 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<TPrincipal>['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);
+    }
+  }
+}