@arnilo/prism-tools 0.0.0-stage → 0.13.1

package/coding/src/security/egress/dns-pin.ts

@@ -0,0 +1,88 @@
+/** DNS pinning and rebinding defense: resolve once, connect to pinned answers, verify the socket. */
+
+import { lookup } from "node:dns/promises";
+import { EgressError } from "./types.js";
+
+/** Normalize IPv6-mapped IPv4 (`::ffff:1.2.3.4` → `1.2.3.4`) for comparison. */
+export function normalizeAddress(address: string): string {
+  const lower = address.toLowerCase();
+  if (lower.startsWith("::ffff:")) return lower.slice("::ffff:".length);
+  return lower;
+}
+
+function ipv4ToInt(address: string): number | undefined {
+  const parts = address.split(".");
+  if (parts.length !== 4) return undefined;
+  let value = 0;
+  for (const part of parts) {
+    const octet = Number(part);
+    if (!Number.isInteger(octet) || octet < 0 || octet > 255) return undefined;
+    value = value * 256 + octet;
+  }
+  return value;
+}
+
+/** Private, loopback, link-local, metadata, multicast, and reserved ranges. */
+export function isPrivateAddress(address: string): boolean {
+  const normalized = normalizeAddress(address);
+  if (normalized.includes(":")) {
+    if (normalized === "::1" || normalized === "::") return true;
+    if (normalized.startsWith("fc") || normalized.startsWith("fd")) return true; // fc00::/7 ULA
+    if (normalized.startsWith("fe8") || normalized.startsWith("fe9") || normalized.startsWith("fea") || normalized.startsWith("feb"))
+      return true; // fe80::/10
+    if (normalized.startsWith("::ffff:")) return isPrivateAddress(normalized.slice("::ffff:".length));
+    if (normalized.startsWith("2001:db8:")) return true; // documentation
+    if (normalized.startsWith("ff")) return true; // multicast
+    return false;
+  }
+  const value = ipv4ToInt(normalized);
+  if (value === undefined) return true; // malformed → treat as non-routable
+  if (value === 0) return true; // 0.0.0.0/8
+  if (value >>> 24 === 10) return true; // 10/8
+  if (value >>> 24 === 127) return true; // 127/8 loopback
+  if (value >>> 16 === 0xa9fe) return true; // 169.254/16 link-local + metadata
+  if (value >>> 20 === 0xac1) return true; // 172.16/12
+  if (value >>> 16 === 0xc0a8) return true; // 192.168/16
+  if (value >>> 22 === 0x191) return true; // 100.64/10 CGNAT
+  if (value >>> 24 === 192 && (value & 0xff) === 0) return true; // 192.0.0.0/24
+  if (value >>> 24 === 192 && (value & 0xff) === 2) return true; // 192.0.2.0/24 TEST-NET
+  if (value >>> 16 === 0xc612) return true; // 198.18/15 benchmarking
+  if (value >>> 24 === 198 && (value & 0xff) === 51) return true; // 198.51.100/24
+  if (value >>> 24 === 203 && (value & 0xff) === 113) return true; // 203.0.113/24
+  if (value >>> 28 === 0xe) return true; // 224/4 multicast
+  if (value >>> 28 === 0xf) return true; // 240/4 reserved
+  return false;
+}
+
+/** 169.254.169.254 and IPv6 link-local metadata endpoints. */
+export function isMetadataAddress(address: string): boolean {
+  const normalized = normalizeAddress(address);
+  if (normalized === "169.254.169.254") return true;
+  if (normalized.startsWith("fe80:")) return true;
+  return false;
+}
+
+export type AddressResolver = (host: string) => Promise<readonly string[]>;
+
+/** Resolve a host to pinned addresses; IP literals resolve to themselves. */
+export async function resolvePinned(host: string, resolve?: AddressResolver): Promise<readonly string[]> {
+  if (resolve) return resolve(host);
+  if (host.includes(":") || /^\d{1,3}(\.\d{1,3}){3}$/.test(host)) return [host];
+  try {
+    const records = await lookup(host, { all: true, verbatim: true });
+    return records.map((record) => record.address);
+  } catch {
+    throw new EgressError("ERR_PRISM_EGRESS_DNS", `DNS resolution failed for ${host}`);
+  }
+}
+
+/** Rebind defense: the connected socket must belong to the pinned answer set. */
+export function assertPinned(host: string, remoteAddress: string | undefined, pinned: readonly string[]): void {
+  if (!remoteAddress) {
+    throw new EgressError("ERR_PRISM_EGRESS_DNS", `no remote address for ${host}`);
+  }
+  const normalized = normalizeAddress(remoteAddress);
+  if (!pinned.some((ip) => normalizeAddress(ip) === normalized)) {
+    throw new EgressError("ERR_PRISM_EGRESS_DNS", `connection address ${remoteAddress} is not a pinned answer for ${host}`);
+  }
+}

package/coding/src/security/egress/index.ts

@@ -0,0 +1,32 @@
+/** Egress module entry point: policy, proxy, DNS pinning, limits, attestation. */
+
+export type { AddressResolver } from "./dns-pin.js";
+export { assertPinned, isMetadataAddress, isPrivateAddress, normalizeAddress, resolvePinned } from "./dns-pin.js";
+export type { EgressLimitOptions, ResolvedEgressLimits } from "./limits.js";
+export {
+  DEFAULT_MAX_EGRESS_CONCURRENT_CONNECTIONS,
+  DEFAULT_MAX_EGRESS_REDIRECT_HOPS,
+  DEFAULT_MAX_EGRESS_REQUEST_BYTES,
+  DEFAULT_MAX_EGRESS_RESPONSE_BYTES,
+  DEFAULT_MAX_EGRESS_RULES,
+  DEFAULT_MAX_EGRESS_TRANSFER_TIME_MS,
+  HARD_MAX_EGRESS_CONCURRENT_CONNECTIONS,
+  HARD_MAX_EGRESS_REDIRECT_HOPS,
+  HARD_MAX_EGRESS_REQUEST_BYTES,
+  HARD_MAX_EGRESS_RESPONSE_BYTES,
+  HARD_MAX_EGRESS_RULES,
+  HARD_MAX_EGRESS_TRANSFER_TIME_MS,
+  resolveEgressLimits,
+} from "./limits.js";
+export type { CreateEgressPolicyOptions, EgressPolicy, EgressPreset, EgressProtocol, EgressRule } from "./policy.js";
+export { createEgressPolicy, EGRESS_PRESETS } from "./policy.js";
+export type {
+  CreateAllowListEgressProxyOptions,
+  EgressAttestation,
+  EgressProxy,
+  EgressProxyEndpoint,
+  EgressProxyStats,
+} from "./proxy.js";
+export { createAllowListEgressProxy } from "./proxy.js";
+export type { EgressAuditRecord, EgressErrorCode } from "./types.js";
+export { EgressError } from "./types.js";

package/coding/src/security/egress/limits.ts

@@ -0,0 +1,57 @@
+/** Frozen finite caps for the allow-list egress proxy. */
+
+export const DEFAULT_MAX_EGRESS_CONCURRENT_CONNECTIONS = 32;
+export const HARD_MAX_EGRESS_CONCURRENT_CONNECTIONS = 256;
+export const DEFAULT_MAX_EGRESS_REQUEST_BYTES = 64 * 1024 ** 2;
+export const HARD_MAX_EGRESS_REQUEST_BYTES = 1024 ** 3;
+export const DEFAULT_MAX_EGRESS_RESPONSE_BYTES = 64 * 1024 ** 2;
+export const HARD_MAX_EGRESS_RESPONSE_BYTES = 1024 ** 3;
+export const DEFAULT_MAX_EGRESS_TRANSFER_TIME_MS = 600_000;
+export const HARD_MAX_EGRESS_TRANSFER_TIME_MS = 3_600_000;
+export const DEFAULT_MAX_EGRESS_RULES = 128;
+export const HARD_MAX_EGRESS_RULES = 1_024;
+export const DEFAULT_MAX_EGRESS_REDIRECT_HOPS = 5;
+export const HARD_MAX_EGRESS_REDIRECT_HOPS = 10;
+
+export interface EgressLimitOptions {
+  readonly concurrentConnections?: number;
+  readonly requestBytes?: number;
+  readonly responseBytes?: number;
+  readonly transferTimeMs?: number;
+  readonly rulesPerPolicy?: number;
+  readonly redirectHops?: number;
+}
+
+export interface ResolvedEgressLimits {
+  readonly concurrentConnections: number;
+  readonly requestBytes: number;
+  readonly responseBytes: number;
+  readonly transferTimeMs: number;
+  readonly rulesPerPolicy: number;
+  readonly redirectHops: number;
+}
+
+const SPECS: Record<keyof ResolvedEgressLimits, readonly [number, number]> = {
+  concurrentConnections: [DEFAULT_MAX_EGRESS_CONCURRENT_CONNECTIONS, HARD_MAX_EGRESS_CONCURRENT_CONNECTIONS],
+  requestBytes: [DEFAULT_MAX_EGRESS_REQUEST_BYTES, HARD_MAX_EGRESS_REQUEST_BYTES],
+  responseBytes: [DEFAULT_MAX_EGRESS_RESPONSE_BYTES, HARD_MAX_EGRESS_RESPONSE_BYTES],
+  transferTimeMs: [DEFAULT_MAX_EGRESS_TRANSFER_TIME_MS, HARD_MAX_EGRESS_TRANSFER_TIME_MS],
+  rulesPerPolicy: [DEFAULT_MAX_EGRESS_RULES, HARD_MAX_EGRESS_RULES],
+  redirectHops: [DEFAULT_MAX_EGRESS_REDIRECT_HOPS, HARD_MAX_EGRESS_REDIRECT_HOPS],
+};
+
+function validateEgressLimit(name: keyof ResolvedEgressLimits, value: number, hardCap: number): number {
+  if (!Number.isSafeInteger(value) || value < 1 || value > hardCap) {
+    throw new RangeError(`${name} must be a positive safe integer at most ${hardCap}`);
+  }
+  return value;
+}
+
+export function resolveEgressLimits(input: EgressLimitOptions = {}): ResolvedEgressLimits {
+  return Object.fromEntries(
+    Object.entries(SPECS).map(([name, [fallback, hardCap]]) => {
+      const value = input[name as keyof EgressLimitOptions] ?? fallback;
+      return [name, validateEgressLimit(name as keyof ResolvedEgressLimits, value as number, hardCap)];
+    }),
+  ) as unknown as ResolvedEgressLimits;
+}

package/coding/src/security/egress/policy.ts

@@ -0,0 +1,137 @@
+/** Allow-list egress policy: deny-all default, exact host/port/protocol rules, frozen presets. */
+
+import { createHash } from "node:crypto";
+import { DEFAULT_MAX_EGRESS_RULES, HARD_MAX_EGRESS_RULES } from "./limits.js";
+import { EgressError } from "./types.js";
+
+export type EgressProtocol = "http" | "https";
+
+export interface EgressRule {
+  readonly host: string;
+  readonly port: number;
+  readonly protocol: EgressProtocol;
+  /** Allow private/link-local/metadata addresses for this rule (default false). */
+  readonly allowPrivate?: boolean;
+}
+
+export type EgressPreset = "npm-registry" | "github";
+
+export interface EgressPolicy {
+  readonly rules: readonly EgressRule[];
+  readonly fingerprint: string;
+  allows(host: string, port: number, protocol: EgressProtocol): boolean;
+  /** Exact rule match (undefined when denied). */
+  match(host: string, port: number, protocol: EgressProtocol): EgressRule | undefined;
+}
+
+/** Frozen preset expansions — explicit rule lists, no wildcards. */
+export const EGRESS_PRESETS: Record<EgressPreset, readonly EgressRule[]> = {
+  "npm-registry": [{ host: "registry.npmjs.org", port: 443, protocol: "https" }],
+  github: [
+    { host: "api.github.com", port: 443, protocol: "https" },
+    { host: "github.com", port: 443, protocol: "https" },
+    { host: "codeload.github.com", port: 443, protocol: "https" },
+    { host: "objects.githubusercontent.com", port: 443, protocol: "https" },
+    { host: "raw.githubusercontent.com", port: 443, protocol: "https" },
+    { host: "uploads.github.com", port: 443, protocol: "https" },
+  ],
+};
+
+const HOSTNAME_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;
+const IPV4_RE = /^(\d{1,3}\.){3}\d{1,3}$/;
+const IPV6_RE = /^[0-9a-f:]+$/;
+
+function validateHost(host: string): string {
+  if (typeof host !== "string" || host.length === 0 || host.length > 253) {
+    throw new EgressError("ERR_PRISM_EGRESS_POLICY", "egress rule host must be a non-empty string at most 253 chars");
+  }
+  if (host.includes("*") || host.includes(" ") || host.includes("\t") || host.includes("/")) {
+    throw new EgressError("ERR_PRISM_EGRESS_POLICY", `egress rule host must not contain wildcards or whitespace: ${host}`);
+  }
+  const lower = host.toLowerCase();
+  if (!HOSTNAME_RE.test(lower) && !IPV4_RE.test(lower) && !IPV6_RE.test(lower)) {
+    throw new EgressError("ERR_PRISM_EGRESS_POLICY", `egress rule host is not a valid hostname or IP literal: ${host}`);
+  }
+  return lower;
+}
+
+function validatePort(port: number): number {
+  if (!Number.isSafeInteger(port) || port < 1 || port > 65_535) {
+    throw new EgressError("ERR_PRISM_EGRESS_POLICY", `egress rule port must be an integer in 1..65535: ${port}`);
+  }
+  return port;
+}
+
+function validateRule(rule: EgressRule): EgressRule {
+  if (!rule || typeof rule !== "object") {
+    throw new EgressError("ERR_PRISM_EGRESS_POLICY", "egress rule must be an object");
+  }
+  if (rule.protocol !== "http" && rule.protocol !== "https") {
+    throw new EgressError("ERR_PRISM_EGRESS_POLICY", `egress rule protocol must be http or https: ${String(rule.protocol)}`);
+  }
+  if (rule.allowPrivate !== undefined && typeof rule.allowPrivate !== "boolean") {
+    throw new EgressError("ERR_PRISM_EGRESS_POLICY", "egress rule allowPrivate must be a boolean when present");
+  }
+  return {
+    host: validateHost(rule.host),
+    port: validatePort(rule.port),
+    protocol: rule.protocol,
+    ...(rule.allowPrivate ? { allowPrivate: true } : {}),
+  };
+}
+
+function fingerprint(rules: readonly EgressRule[]): string {
+  const canonical = rules
+    .map((r) => `${r.protocol}|${r.host}|${r.port}|${r.allowPrivate === true ? 1 : 0}`)
+    .sort()
+    .join("\n");
+  return createHash("sha256").update(canonical).digest("hex");
+}
+
+export interface CreateEgressPolicyOptions {
+  readonly allow?: readonly EgressRule[];
+  readonly presets?: readonly EgressPreset[];
+  /** Rule-count cap (default 128, hard 1024). */
+  readonly maxRules?: number;
+}
+
+export function createEgressPolicy(options: CreateEgressPolicyOptions = {}): EgressPolicy {
+  const maxRules = options.maxRules ?? DEFAULT_MAX_EGRESS_RULES;
+  if (!Number.isSafeInteger(maxRules) || maxRules < 1 || maxRules > HARD_MAX_EGRESS_RULES) {
+    throw new EgressError("ERR_PRISM_EGRESS_POLICY", `maxRules must be a positive safe integer at most ${HARD_MAX_EGRESS_RULES}`);
+  }
+  const seen = new Set<string>();
+  const rules: EgressRule[] = [];
+  const push = (rule: EgressRule): void => {
+    const key = `${rule.protocol}|${rule.host}|${rule.port}|${rule.allowPrivate === true ? 1 : 0}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    rules.push(rule);
+  };
+  for (const preset of options.presets ?? []) {
+    if (preset !== "npm-registry" && preset !== "github") {
+      throw new EgressError("ERR_PRISM_EGRESS_POLICY", `unknown egress preset: ${String(preset)}`);
+    }
+    for (const rule of EGRESS_PRESETS[preset]) push(rule);
+  }
+  for (const rule of options.allow ?? []) push(validateRule(rule));
+  if (rules.length > maxRules) {
+    throw new EgressError("ERR_PRISM_EGRESS_POLICY", `egress policy exceeds maxRules (${maxRules})`);
+  }
+  const frozen = Object.freeze(rules);
+  const policy: EgressPolicy = {
+    rules: frozen,
+    fingerprint: fingerprint(frozen),
+    allows(host, port, protocol) {
+      return policy.match(host, port, protocol) !== undefined;
+    },
+    match(host, port, protocol) {
+      const h = host.toLowerCase();
+      for (const rule of frozen) {
+        if (rule.host === h && rule.port === port && rule.protocol === protocol) return rule;
+      }
+      return undefined;
+    },
+  };
+  return policy;
+}