@humwick/server 0.130.0 → 0.130.2

package/node_modules/@humwick/kernel/effects.ts

@@ -1,493 +0,0 @@
-import { lookup as lookupHost } from "node:dns/promises";
-import { request as httpRequest } from "node:http";
-import { request as httpsRequest } from "node:https";
-import { Readable } from "node:stream";
-import type { Clock, Disposable, Logger, Rng, Transport } from "./contract";
-
-function assertDelay(value: number, name: string, allowZero: boolean): void {
-  if (!Number.isFinite(value) || value < 0 || (!allowZero && value === 0)) {
-    const qualifier = allowZero ? "a non-negative" : "a positive";
-    throw new RangeError(`${name} must be ${qualifier} finite number`);
-  }
-}
-
-/** A logger that discards every record. Useful as the default ModuleCtx.log in tests. */
-export function createSilentLogger(): Logger {
-  const noop = (): void => {};
-  return { debug: noop, info: noop, warn: noop, error: noop };
-}
-
-/** A logger that forwards to the host console, tagging each record with its level. */
-export function createConsoleLogger(): Logger {
-  const write = (level: "debug" | "info" | "warn" | "error") =>
-    (message: string, fields?: Readonly<Record<string, unknown>>): void => {
-      if (fields) console[level](message, fields);
-      else console[level](message);
-    };
-  return { debug: write("debug"), info: write("info"), warn: write("warn"), error: write("error") };
-}
-
-/** Production wall-clock provider. Ambient time and timers stop at this kernel boundary. */
-export function createRealClock(): Clock {
-  return {
-    now: () => Date.now(),
-    sleep(ms) {
-      assertDelay(ms, "sleep delay", true);
-      return new Promise((resolve) => setTimeout(resolve, ms));
-    },
-    every(ms, fn) {
-      assertDelay(ms, "interval", false);
-      const timer = setInterval(fn, ms);
-      let disposed = false;
-      return {
-        dispose() {
-          if (disposed) return;
-          disposed = true;
-          clearInterval(timer);
-        },
-      };
-    },
-  };
-}
-
-interface ScheduledAction {
-  readonly id: number;
-  due: number;
-  readonly interval?: number;
-  readonly run: () => void;
-}
-
-export interface ControllableClock extends Clock {
-  /** Advance virtual time, firing due actions in stable registration order. */
-  advanceBy(ms: number): void;
-  /** Advance to an absolute virtual timestamp. Time cannot move backwards. */
-  advanceTo(timestamp: number): void;
-}
-
-/**
- * A clock for deterministic tests and replay. It never consults or waits for wall time.
- * Scheduled work only runs when the caller advances the clock.
- */
-export function createControllableClock(initialNow = 0): ControllableClock {
-  if (!Number.isFinite(initialNow)) throw new RangeError("initial time must be a finite number");
-
-  let now = initialNow;
-  let nextId = 1;
-  const scheduled = new Map<number, ScheduledAction>();
-
-  function schedule(delay: number, run: () => void, interval?: number): Disposable {
-    const action: ScheduledAction = { id: nextId++, due: now + delay, interval, run };
-    scheduled.set(action.id, action);
-    return { dispose: () => scheduled.delete(action.id) };
-  }
-
-  function nextDueAtOrBefore(timestamp: number): ScheduledAction | undefined {
-    let next: ScheduledAction | undefined;
-    for (const action of scheduled.values()) {
-      if (action.due > timestamp) continue;
-      if (!next || action.due < next.due || (action.due === next.due && action.id < next.id)) next = action;
-    }
-    return next;
-  }
-
-  const clock: ControllableClock = {
-    now: () => now,
-    sleep(ms) {
-      assertDelay(ms, "sleep delay", true);
-      return new Promise((resolve) => {
-        schedule(ms, resolve);
-      });
-    },
-    every(ms, fn) {
-      assertDelay(ms, "interval", false);
-      return schedule(ms, fn, ms);
-    },
-    advanceBy(ms) {
-      assertDelay(ms, "advance", true);
-      clock.advanceTo(now + ms);
-    },
-    advanceTo(timestamp) {
-      if (!Number.isFinite(timestamp)) throw new RangeError("target time must be a finite number");
-      if (timestamp < now) throw new RangeError("controllable clock cannot move backwards");
-
-      let action = nextDueAtOrBefore(timestamp);
-      while (action) {
-        now = action.due;
-        if (action.interval === undefined) {
-          scheduled.delete(action.id);
-        } else {
-          // Reschedule first so dispose() from inside the callback cancels the next firing.
-          action.due += action.interval;
-        }
-        action.run();
-        action = nextDueAtOrBefore(timestamp);
-      }
-      now = timestamp;
-    },
-  };
-
-  return clock;
-}
-
-function assertJitterArgs(baseMs: number, spread: number): void {
-  assertDelay(baseMs, "jitter base", true);
-  assertDelay(spread, "jitter spread", true);
-}
-
-function jitter(random: () => number, baseMs: number, spread: number): number {
-  assertJitterArgs(baseMs, spread);
-  // spread is a ratio: 0.2 produces a value within baseMs +/- 20%.
-  const factor = 1 + (random() * 2 - 1) * spread;
-  return Math.max(0, Math.round(baseMs * factor));
-}
-
-/** Production cryptographic RNG provider. It never delegates to Math.random(). */
-export function createSystemRng(): Rng {
-  const random = (): number => {
-    const value = new Uint32Array(1);
-    crypto.getRandomValues(value);
-    return value[0]! / 0x1_0000_0000;
-  };
-
-  return {
-    uuid: () => crypto.randomUUID(),
-    random,
-    jitter: (baseMs, spread) => jitter(random, baseMs, spread),
-  };
-}
-
-function hashSeed(seed: string): number {
-  // FNV-1a provides a small, stable conversion from string seeds to 32-bit state.
-  let hash = 0x811c9dc5;
-  for (let i = 0; i < seed.length; i++) {
-    hash ^= seed.charCodeAt(i);
-    hash = Math.imul(hash, 0x01000193);
-  }
-  return hash >>> 0;
-}
-
-/** Stable seeded RNG (Mulberry32) for deterministic tests and workflow replay. */
-export function createSeededRng(seed: number | string): Rng {
-  if (typeof seed === "number" && !Number.isFinite(seed)) throw new RangeError("RNG seed must be finite");
-  let state = typeof seed === "string" ? hashSeed(seed) : Math.trunc(seed) >>> 0;
-
-  const nextUint32 = (): number => {
-    state = (state + 0x6d2b79f5) >>> 0;
-    let value = state;
-    value = Math.imul(value ^ (value >>> 15), value | 1);
-    value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
-    return (value ^ (value >>> 14)) >>> 0;
-  };
-  const random = (): number => nextUint32() / 0x1_0000_0000;
-
-  const uuid = (): string => {
-    const bytes = new Uint8Array(16);
-    for (let offset = 0; offset < bytes.length; offset += 4) {
-      const value = nextUint32();
-      bytes[offset] = value >>> 24;
-      bytes[offset + 1] = value >>> 16;
-      bytes[offset + 2] = value >>> 8;
-      bytes[offset + 3] = value;
-    }
-    bytes[6] = (bytes[6]! & 0x0f) | 0x40;
-    bytes[8] = (bytes[8]! & 0x3f) | 0x80;
-    const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
-    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
-  };
-
-  return {
-    uuid,
-    random,
-    jitter: (baseMs, spread) => jitter(random, baseMs, spread),
-  };
-}
-
-/**
- * Baseline protection for destinations modules should never need to reach directly.
- * Caller-provided rules extend this list by default.
- */
-export const DEFAULT_NET_DENY_LIST = Object.freeze([
-  "localhost",
-  "metadata.google.internal",
-  "metadata.google",
-  "0.0.0.0/8",
-  "10.0.0.0/8",
-  "100.64.0.0/10",
-  "127.0.0.0/8",
-  "169.254.0.0/16",
-  "172.16.0.0/12",
-  "192.0.0.0/24",
-  "192.168.0.0/16",
-  "198.18.0.0/15",
-  "224.0.0.0/4",
-  "240.0.0.0/4",
-  "::/128",
-  "::1/128",
-  "::/96",
-  "::ffff:0:0/96",
-  "64:ff9b::/96",
-  "64:ff9b:1::/48",
-  "2001:db8::/32",
-  "fc00::/7",
-  "fe80::/10",
-  "ff00::/8",
-] as const);
-
-export interface NetResolvedAddress {
-  readonly address: string;
-  readonly family: 4 | 6;
-}
-
-export interface NetConnectionPin extends NetResolvedAddress {
-  readonly hostname: string;
-}
-
-type ResolverCapability = (hostname: string) => Promise<readonly NetResolvedAddress[]>;
-type FetchCapability = (url: string, init: RequestInit | undefined, pin: NetConnectionPin) => Promise<Response>;
-
-export interface NetTransportOptions {
-  /** Hostname or IPv4/IPv6 CIDR rules. Hostname rules include all subdomains. */
-  denyList?: readonly string[];
-  /** Defaults stay active unless this explicit escape hatch is disabled. */
-  includeDefaultDenyList?: boolean;
-  /** Trusted injected host capability; production uses a socket pinned to the vetted address. */
-  fetch?: FetchCapability;
-  /** Injected hostname resolver; production defaults to the operating-system resolver. */
-  resolve?: ResolverCapability;
-}
-
-type ParsedRule =
-  | { readonly source: string; readonly kind: "hostname"; readonly hostname: string }
-  | { readonly source: string; readonly kind: "cidr"; readonly bits: 32 | 128; readonly network: bigint; readonly prefix: number };
-
-function parseIpv4(value: string): bigint | undefined {
-  const parts = value.split(".");
-  if (parts.length !== 4) return undefined;
-  let result = 0n;
-  for (const part of parts) {
-    if (!/^\d+$/.test(part)) return undefined;
-    if (part.length > 1 && part.startsWith("0")) return undefined;
-    const octet = Number(part);
-    if (octet > 255) return undefined;
-    result = (result << 8n) | BigInt(octet);
-  }
-  return result;
-}
-
-function parseIpv6(value: string): bigint | undefined {
-  let address = value.toLowerCase();
-  if (address.startsWith("[") && address.endsWith("]")) address = address.slice(1, -1);
-  if (address.includes("%")) return undefined;
-
-  const doubleColon = address.indexOf("::");
-  if (doubleColon !== -1 && doubleColon !== address.lastIndexOf("::")) return undefined;
-  const left = (doubleColon === -1 ? address : address.slice(0, doubleColon)).split(":").filter(Boolean);
-  const right = (doubleColon === -1 ? "" : address.slice(doubleColon + 2)).split(":").filter(Boolean);
-
-  function expandIpv4Tail(parts: string[]): boolean {
-    const tail = parts.at(-1);
-    if (!tail?.includes(".")) return true;
-    const ipv4 = parseIpv4(tail);
-    if (ipv4 === undefined) return false;
-    parts.splice(parts.length - 1, 1, ((ipv4 >> 16n) & 0xffffn).toString(16), (ipv4 & 0xffffn).toString(16));
-    return true;
-  }
-
-  if (!expandIpv4Tail(left) || !expandIpv4Tail(right)) return undefined;
-  const missing = 8 - left.length - right.length;
-  if ((doubleColon === -1 && missing !== 0) || (doubleColon !== -1 && missing < 1)) return undefined;
-  const groups = [...left, ...Array.from({ length: missing }, () => "0"), ...right];
-  if (groups.length !== 8) return undefined;
-
-  let result = 0n;
-  for (const group of groups) {
-    if (!/^[0-9a-f]{1,4}$/.test(group)) return undefined;
-    result = (result << 16n) | BigInt(`0x${group}`);
-  }
-  return result;
-}
-
-function mask(bits: 32 | 128, prefix: number): bigint {
-  if (prefix === 0) return 0n;
-  return ((1n << BigInt(prefix)) - 1n) << BigInt(bits - prefix);
-}
-
-function parseRule(source: string): ParsedRule {
-  const value = source.trim();
-  if (!value) throw new TypeError("net deny-list rules must not be empty");
-
-  const slash = value.lastIndexOf("/");
-  if (slash !== -1) {
-    const address = value.slice(0, slash);
-    const parsedPrefix = Number(value.slice(slash + 1));
-    const ipv4 = parseIpv4(address);
-    const ipv6 = ipv4 === undefined ? parseIpv6(address) : undefined;
-    const bits = ipv4 !== undefined ? 32 : ipv6 !== undefined ? 128 : undefined;
-    if (!bits || !Number.isInteger(parsedPrefix) || parsedPrefix < 0 || parsedPrefix > bits) {
-      throw new TypeError(`invalid net deny-list CIDR rule '${source}'`);
-    }
-    const addressValue = ipv4 ?? ipv6!;
-    const prefixMask = mask(bits, parsedPrefix);
-    return { source, kind: "cidr", bits, network: addressValue & prefixMask, prefix: parsedPrefix };
-  }
-
-  let hostname = value.startsWith(".") ? value.slice(1) : value;
-  try {
-    hostname = new URL(`http://${hostname}/`).hostname;
-  } catch {
-    throw new TypeError(`invalid net deny-list hostname rule '${source}'`);
-  }
-  hostname = hostname.toLowerCase().replace(/\.+$/, "");
-  if (!hostname) throw new TypeError(`invalid net deny-list hostname rule '${source}'`);
-  return { source, kind: "hostname", hostname };
-}
-
-function normalizeHostname(hostname: string): string {
-  return hostname.toLowerCase().replace(/\.+$/, "");
-}
-
-function matchingRule(hostname: string, rules: readonly ParsedRule[]): ParsedRule | undefined {
-  const normalized = normalizeHostname(hostname);
-  const unbracketed = normalized.startsWith("[") && normalized.endsWith("]") ? normalized.slice(1, -1) : normalized;
-  const ipv4 = parseIpv4(unbracketed);
-  const ipv6 = ipv4 === undefined ? parseIpv6(unbracketed) : undefined;
-
-  return rules.find((rule) => {
-    if (rule.kind === "hostname") return normalized === rule.hostname || normalized.endsWith(`.${rule.hostname}`);
-    const address = rule.bits === 32 ? ipv4 : ipv6;
-    return address !== undefined && (address & mask(rule.bits, rule.prefix)) === rule.network;
-  });
-}
-
-export class NetEgressDeniedError extends Error {
-  constructor(
-    readonly hostname: string,
-    readonly rule: string,
-  ) {
-    super(`outbound HTTP to host '${hostname}' was refused by net deny-list rule '${rule}'`);
-    this.name = "NetEgressDeniedError";
-  }
-}
-
-export class NetRedirectRefusedError extends Error {
-  constructor(readonly hostname: string) {
-    super(`outbound HTTP redirect from host '${hostname}' was refused; follow it explicitly through ctx.net`);
-    this.name = "NetRedirectRefusedError";
-  }
-}
-
-export class NetEgressResolutionError extends Error {
-  constructor(readonly hostname: string, options?: ErrorOptions) {
-    super(`outbound HTTP to host '${hostname}' was refused because its address could not be resolved safely`, options);
-    this.name = "NetEgressResolutionError";
-  }
-}
-
-const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
-
-async function defaultResolver(hostname: string): Promise<readonly NetResolvedAddress[]> {
-  const addresses = await lookupHost(hostname, { all: true, verbatim: true });
-  return addresses.map(({ address, family }) => {
-    if (family !== 4 && family !== 6) throw new TypeError(`resolver returned an unsupported address family`);
-    return { address, family };
-  });
-}
-
-async function pinnedFetch(url: string, init: RequestInit | undefined, pin: NetConnectionPin): Promise<Response> {
-  const request = new Request(url, init);
-  const body = request.body ? Buffer.from(await request.arrayBuffer()) : undefined;
-  const requestCapability = request.url.startsWith("https:") ? httpsRequest : httpRequest;
-  const requestHeaders: Record<string, string> = {};
-  request.headers.forEach((value, name) => {
-    requestHeaders[name] = value;
-  });
-
-  return await new Promise<Response>((resolve, reject) => {
-    const outgoing = requestCapability(request.url, {
-      method: request.method,
-      headers: requestHeaders,
-      family: pin.family,
-      signal: request.signal,
-      // Supplying the exact vetted address here is the security boundary: the socket
-      // cannot perform a second DNS lookup and therefore cannot be DNS-rebound.
-      lookup: (_hostname, options, callback) => {
-        if (options.all) callback(null, [{ address: pin.address, family: pin.family }]);
-        else callback(null, pin.address, pin.family);
-      },
-    }, (incoming) => {
-      const headers = new Headers();
-      for (let index = 0; index < incoming.rawHeaders.length; index += 2) {
-        headers.append(incoming.rawHeaders[index]!, incoming.rawHeaders[index + 1]!);
-      }
-      resolve(new Response(Readable.toWeb(incoming) as unknown as ReadableStream, {
-        status: incoming.statusCode,
-        statusText: incoming.statusMessage,
-        headers,
-      }));
-    });
-    outgoing.on("error", reject);
-    outgoing.end(body);
-  });
-}
-
-/** Create the outbound HTTP provider used as ModuleCtx.net. */
-export function createNetTransport(options: NetTransportOptions = {}): Transport {
-  const sources = [
-    ...(options.includeDefaultDenyList === false ? [] : DEFAULT_NET_DENY_LIST),
-    ...(options.denyList ?? []),
-  ];
-  const rules = sources.map(parseRule);
-  const fetchCapability = options.fetch ?? pinnedFetch;
-  const resolver = options.resolve ?? defaultResolver;
-
-  return {
-    async fetch(input, init) {
-      let url: URL;
-      try {
-        url = new URL(input);
-      } catch {
-        throw new TypeError(`ctx.net.fetch requires an absolute HTTP(S) URL`);
-      }
-      if (url.protocol !== "http:" && url.protocol !== "https:") {
-        throw new TypeError(`ctx.net.fetch refuses non-HTTP protocol '${url.protocol}'`);
-      }
-
-      const hostname = normalizeHostname(url.hostname);
-      url.hostname = hostname;
-      const denied = matchingRule(hostname, rules);
-      if (denied) throw new NetEgressDeniedError(url.hostname, denied.source);
-
-      const unbracketed = hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
-      const literalIpv4 = parseIpv4(unbracketed);
-      const literalIpv6 = literalIpv4 === undefined ? parseIpv6(unbracketed) : undefined;
-      let addresses: readonly NetResolvedAddress[];
-      if (literalIpv4 !== undefined || literalIpv6 !== undefined) {
-        addresses = [{ address: unbracketed, family: literalIpv4 !== undefined ? 4 : 6 }];
-      } else {
-        try {
-          addresses = await resolver(hostname);
-        } catch (cause) {
-          throw new NetEgressResolutionError(hostname, { cause });
-        }
-      }
-
-      if (addresses.length === 0) throw new NetEgressResolutionError(hostname);
-      for (const address of addresses) {
-        const valid = address.family === 4 ? parseIpv4(address.address) : address.family === 6 ? parseIpv6(address.address) : undefined;
-        if (valid === undefined) throw new NetEgressResolutionError(hostname);
-        const addressDenied = matchingRule(address.address, rules);
-        if (addressDenied) throw new NetEgressDeniedError(hostname, addressDenied.source);
-      }
-      const selected = addresses[0]!;
-      const pin: NetConnectionPin = { hostname, address: selected.address, family: selected.family };
-
-      // Manual redirect handling is a security invariant: an allowed URL must not make
-      // the host fetch a second, denied URL behind this gate.
-      const response = await fetchCapability(url.href, { ...init, redirect: "manual" }, pin);
-      if (REDIRECT_STATUSES.has(response.status) && init?.redirect !== "manual") {
-        throw new NetRedirectRefusedError(url.hostname);
-      }
-      return response;
-    },
-  };
-}