@idp.global/sdk 18.1.0 → 18.3.0

package/ts_server/classes.oidc-introspection-client.ts

@@ -1,4 +1,5 @@
 import * as plugins from './plugins.js';
+import type { TOidcFetch } from './helpers.trusted-ca-fetch.js';
 
 export interface IOidcIntrospectionClientOptions {
   issuer: string;
@@ -6,6 +7,12 @@ export interface IOidcIntrospectionClientOptions {
   clientSecret: string;
   timeoutMs?: number;
   maxResponseBytes?: number;
+  /**
+   * The fetch every introspection request goes through, e.g.
+   * `createTrustedCaFetch(caPem)` for an issuer under a private CA. The global
+   * `fetch` when absent.
+   */
+  fetch?: TOidcFetch;
 }
 
 export interface IOidcIntrospectionClientRequest {
@@ -40,6 +47,7 @@ export class OidcIntrospectionClient {
   readonly #authorization: string;
   readonly #timeoutMs: number;
   readonly #maxResponseBytes: number;
+  readonly #fetch?: TOidcFetch;
 
   constructor(optionsArg: IOidcIntrospectionClientOptions) {
     if (!optionsArg || !exactString(optionsArg.issuer, 2048) || !exactString(optionsArg.clientId)
@@ -56,6 +64,8 @@ export class OidcIntrospectionClient {
       || !Number.isSafeInteger(this.#maxResponseBytes) || this.#maxResponseBytes < 1 || this.#maxResponseBytes > 65536) {
       throw new OidcIntrospectionError('invalid_request');
     }
+    if (optionsArg.fetch !== undefined && typeof optionsArg.fetch !== 'function') throw new OidcIntrospectionError('invalid_request');
+    this.#fetch = optionsArg.fetch;
     this.#issuer = canonicalIssuer;
     this.#clientId = optionsArg.clientId;
     // OAuth Basic components are form-encoded separately before joining with ':'.
@@ -76,11 +86,15 @@ export class OidcIntrospectionClient {
     });
     let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
     try {
-      const response = await Promise.race([fetch(`${this.#issuer}/oauth/introspect`, {
-        method: 'POST', redirect: 'error', credentials: 'omit', cache: 'no-store', signal: controller.signal,
+      const url = `${this.#issuer}/oauth/introspect`;
+      const init = {
+        method: 'POST', redirect: 'error' as const, signal: controller.signal,
         headers: { authorization: this.#authorization, 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
         body: new URLSearchParams({ token, subject, organization_id: organizationId, nonce, token_type_hint: 'access_token' }),
-      }), deadline]);
+      };
+      const response = await Promise.race([this.#fetch
+        ? this.#fetch(url, init)
+        : fetch(url, { ...init, credentials: 'omit', cache: 'no-store' }), deadline]);
       if (response.status !== 200) throw new OidcIntrospectionError('unavailable');
       if (response.headers.get('content-type')?.split(';')[0].trim().toLowerCase() !== 'application/json'
         || !response.headers.get('cache-control')?.toLowerCase().split(',').map((partArg) => partArg.trim()).includes('no-store')

package/ts_server/helpers.trusted-ca-fetch.ts

@@ -0,0 +1,204 @@
+import * as plugins from './plugins.js';
+
+/**
+ * What the sdk's OIDC clients pass to their fetch: the subset of `RequestInit`
+ * that `openid-client` and `OidcIntrospectionClient` use. Node's global `fetch`
+ * satisfies it.
+ */
+export interface IOidcFetchInit {
+  method: string;
+  headers: Record<string, string>;
+  body?: ArrayBuffer | ReadableStream | string | Uint8Array | URLSearchParams | null;
+  duplex?: 'half';
+  /** `manual` answers a redirect as it is; `error` rejects it. Neither follows it. */
+  redirect: 'manual' | 'error';
+  signal?: AbortSignal;
+}
+
+/** A fetch for one OIDC client's requests, e.g. one that trusts the issuer's private CA. */
+export type TOidcFetch = (urlArg: string, initArg: IOidcFetchInit) => Promise<Response>;
+
+const pemCertificatePattern = /-----BEGIN CERTIFICATE-----\r?\n[A-Za-z0-9+/=\r\n]+-----END CERTIFICATE-----/g;
+
+/** The statuses a fetch answers with a null body. */
+const nullBodyStatuses: ReadonlySet<number> = new Set([101, 103, 204, 205, 304]);
+
+/** The statuses fetch treats as redirects. */
+const redirectStatuses: ReadonlySet<number> = new Set([301, 302, 303, 307, 308]);
+
+/**
+ * Idle keep-alive sockets close after this delay, or earlier when the server
+ * announces a shorter `Keep-Alive: timeout`, so a pooled socket is not reused
+ * as the server closes it.
+ */
+const idleSocketTimeoutMs = 4_000;
+
+/** A request body as bytes, with the content type fetch would give it. */
+const encodeBody = async (
+  bodyArg: NonNullable<IOidcFetchInit['body']>,
+): Promise<{ bytes: Buffer; contentType?: string }> => {
+  if (typeof bodyArg === 'string') {
+    return { bytes: Buffer.from(bodyArg, 'utf8'), contentType: 'text/plain;charset=UTF-8' };
+  }
+  if (bodyArg instanceof URLSearchParams) {
+    return { bytes: Buffer.from(bodyArg.toString(), 'utf8'), contentType: 'application/x-www-form-urlencoded;charset=UTF-8' };
+  }
+  if (bodyArg instanceof ArrayBuffer) {
+    return { bytes: Buffer.from(new Uint8Array(bodyArg)) };
+  }
+  if (bodyArg instanceof Uint8Array) {
+    return { bytes: Buffer.from(bodyArg) };
+  }
+  const chunks: Uint8Array[] = [];
+  const reader = bodyArg.getReader();
+  while (true) {
+    const part = await reader.read();
+    if (part.done) {
+      break;
+    }
+    if (!(part.value instanceof Uint8Array)) {
+      await reader.cancel();
+      throw new TypeError('A request body stream must yield bytes');
+    }
+    chunks.push(part.value);
+  }
+  return { bytes: Buffer.concat(chunks) };
+};
+
+/**
+ * The response body as a fetch body stream, read as it is pulled. Cancelling
+ * it destroys the response and so its connection.
+ */
+const webStreamOf = (incomingArg: plugins.http.IncomingMessage): ReadableStream<Uint8Array> => {
+  const chunks = incomingArg[Symbol.asyncIterator]();
+  return new ReadableStream<Uint8Array>({
+    async pull(controllerArg) {
+      const part = await chunks.next();
+      if (part.done) {
+        controllerArg.close();
+      } else {
+        controllerArg.enqueue(part.value);
+      }
+    },
+    async cancel() {
+      await chunks.return?.();
+    },
+  });
+};
+
+/**
+ * Every certificate of the given PEM text, each parsed. Anything else in the
+ * text, or no certificate at all, is refused: an unreadable trust anchor must
+ * fail here, not as a TLS error at the first request.
+ */
+const readTrustedCertificates = (trustedCaPemArg: string | readonly string[]): string[] => {
+  const pems = typeof trustedCaPemArg === 'string' ? [trustedCaPemArg] : trustedCaPemArg;
+  if (!Array.isArray(pems) || pems.length === 0) {
+    throw new TypeError('trustedCaPem must name at least one PEM certificate');
+  }
+  const certificates: string[] = [];
+  for (const pem of pems) {
+    if (typeof pem !== 'string') {
+      throw new TypeError('trustedCaPem must be PEM certificate text');
+    }
+    const blocks = pem.match(pemCertificatePattern) ?? [];
+    if (blocks.length === 0 || pem.replace(pemCertificatePattern, '').trim() !== '') {
+      throw new TypeError('trustedCaPem must contain PEM certificates only');
+    }
+    for (const block of blocks) {
+      try {
+        new plugins.crypto.X509Certificate(block);
+      } catch {
+        throw new TypeError('trustedCaPem contains a certificate that cannot be parsed');
+      }
+      certificates.push(block);
+    }
+  }
+  return certificates;
+};
+
+/**
+ * A fetch over `node:https` whose connections trust the given CA certificates
+ * and nothing else. The agent belongs to this fetch alone: the process-wide
+ * trust store, the global `fetch` and its dispatcher stay untouched. Only
+ * `https:` URLs are fetched, redirects are never followed, and bodies are
+ * requested without a content coding. Idle pooled sockets are unreferenced, so
+ * they never keep the process alive.
+ */
+export const createTrustedCaFetch = (trustedCaPemArg: string | readonly string[]): TOidcFetch => {
+  const agent = new plugins.https.Agent({
+    ca: readTrustedCertificates(trustedCaPemArg),
+    keepAlive: true,
+    timeout: idleSocketTimeoutMs,
+  });
+  return async (urlArg, initArg) => {
+    const url = new URL(urlArg);
+    if (url.protocol !== 'https:') {
+      throw new TypeError('A trusted-CA fetch only requests https URLs');
+    }
+    const signal = initArg.signal;
+    signal?.throwIfAborted();
+    const headers = new Headers(initArg.headers);
+    let body: Buffer | undefined;
+    if (initArg.body !== undefined && initArg.body !== null) {
+      const encoded = await encodeBody(initArg.body);
+      body = encoded.bytes;
+      if (encoded.contentType && !headers.has('content-type')) {
+        headers.set('content-type', encoded.contentType);
+      }
+      headers.set('content-length', String(body.byteLength));
+    }
+    headers.set('accept-encoding', 'identity');
+    signal?.throwIfAborted();
+
+    return new Promise<Response>((resolve, reject) => {
+      const request = plugins.https.request(url, {
+        method: initArg.method,
+        headers: Object.fromEntries(headers.entries()),
+        agent,
+      });
+      // Stays attached for the request's lifetime, so a connection failure
+      // while the body is read never becomes an unhandled 'error' event.
+      request.on('error', reject);
+      // Destroyed without an error on purpose: an error would be re-emitted on
+      // the socket, which no longer has a listener once a keep-alive response
+      // completed. The response body errors as its connection goes.
+      const abort = () => {
+        reject(signal?.reason);
+        request.destroy();
+      };
+      signal?.addEventListener('abort', abort, { once: true });
+      request.once('close', () => signal?.removeEventListener('abort', abort));
+      request.on('response', (incoming) => {
+        try {
+          const status = incoming.statusCode ?? 0;
+          if (initArg.redirect === 'error' && redirectStatuses.has(status)) {
+            throw new TypeError('The response is a redirect');
+          }
+          const contentEncoding = incoming.headers['content-encoding'];
+          if (contentEncoding !== undefined && contentEncoding.trim().toLowerCase() !== 'identity') {
+            throw new TypeError('The response has a content coding');
+          }
+          // same combination rules as fetch: repeated fields join with ", "
+          const responseHeaders = new Headers();
+          for (let index = 0; index < incoming.rawHeaders.length; index += 2) {
+            responseHeaders.append(incoming.rawHeaders[index], incoming.rawHeaders[index + 1]);
+          }
+          const withoutBody = nullBodyStatuses.has(status) || initArg.method.toUpperCase() === 'HEAD';
+          if (withoutBody) {
+            incoming.resume();
+          }
+          resolve(new Response(withoutBody ? null : webStreamOf(incoming), {
+            status,
+            statusText: incoming.statusMessage,
+            headers: responseHeaders,
+          }));
+        } catch (error) {
+          reject(error);
+          request.destroy();
+        }
+      });
+      request.end(body);
+    });
+  };
+};

package/ts_server/index.ts

@@ -3,6 +3,7 @@ export * from './classes.account-auth-service.js';
 export * from './classes.account-doc.js';
 export * from './classes.account-store.js';
 export * from './classes.idp-global-server-client.js';
+export * from './helpers.trusted-ca-fetch.js';
 export * from './classes.oidc-introspection-client.js';
 export * from './classes.oidc-userinfo-client.js';
 export * from './classes.password-hasher.js';

package/ts_server/plugins.ts

@@ -1,6 +1,8 @@
 import * as crypto from 'crypto';
+import * as http from 'node:http';
+import * as https from 'node:https';
 
-export { crypto };
+export { crypto, http, https };
 
 import * as idpInterfaces from '@idp.global/interfaces';