@selvajs/server 0.2.0-beta.3 → 0.2.0-beta.4

package/src/compute/safe-url.ts

@@ -1,186 +0,0 @@
-import { lookup } from 'node:dns/promises';
-import { isIP } from 'node:net';
-
-/**
- * SSRF guard for `loadRemoteDefinition`. Without it an authenticated user could
- * submit `http://169.254.169.254/...` (cloud metadata) or any intranet endpoint
- * and the server would fetch it on their behalf.
- *
- * Two layers:
- *
- *   1. `isSafeRemoteDefinitionUrl` — synchronous literal pre-filter. Rejects
- *      protocol, hostname literals, and every IP *encoding* that maps to a
- *      blocked address (dotted-decimal, integer, octal, hex, short-form,
- *      IPv4-mapped IPv6). Fast and DNS-free; safe to call anywhere.
- *
- *   2. `assertSafeRemoteDefinitionUrl` — resolves the hostname via DNS and
- *      re-checks the *resolved* IP. This is the real defense: it catches a
- *      public name that resolves to a private IP, which the literal filter
- *      can't see. Still not bulletproof against rebinding (the IP can change
- *      between this lookup and fetch's own); for that the caller would have to
- *      connect to the resolved IP directly. Connecting by IP is a larger change
- *      — this closes the practical bypasses (literal encodings + a DNS record
- *      that points inward) which is what an attacker actually reaches for.
- */
-
-/**
- * True when `ip` (a normalized IPv4 or IPv6 literal from `isIP`/`dns.lookup`)
- * is loopback, private, link-local, or otherwise must-not-fetch. IPv4-mapped
- * IPv6 (`::ffff:a.b.c.d`) is unwrapped to its embedded IPv4 first so the v4
- * rules apply.
- */
-function isBlockedIp(ip: string): boolean {
-	let addr = ip.toLowerCase();
-
-	// Unwrap IPv4-mapped IPv6 so the embedded address is judged by the IPv4
-	// rules below. `URL` compresses the dotted form to hex (`::ffff:127.0.0.1`
-	// → `::ffff:7f00:1`), so handle both spellings.
-	const mappedDotted = /^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(addr);
-	if (mappedDotted) {
-		addr = mappedDotted[1];
-	} else {
-		const mappedHex = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(addr);
-		if (mappedHex) {
-			const hi = parseInt(mappedHex[1], 16);
-			const lo = parseInt(mappedHex[2], 16);
-			addr = [(hi >> 8) & 0xff, hi & 0xff, (lo >> 8) & 0xff, lo & 0xff].join('.');
-		}
-	}
-
-	if (isIP(addr) === 4) {
-		const octets = addr.split('.').map(Number);
-		if (octets.length !== 4 || octets.some((o) => o > 255)) return true; // malformed → block
-		const [a, b] = octets;
-		if (a === 0) return true; // 0.0.0.0/8 (incl. 0.0.0.0)
-		if (a === 127) return true; // loopback
-		if (a === 10) return true; // RFC1918
-		if (a === 192 && b === 168) return true; // RFC1918
-		if (a === 172 && b >= 16 && b <= 31) return true; // RFC1918
-		if (a === 169 && b === 254) return true; // link-local + cloud metadata
-		return false;
-	}
-
-	// IPv6 literals.
-	if (addr === '::1' || addr === '::') return true; // loopback / unspecified
-	if (/^(fc|fd)[0-9a-f]{0,2}:/.test(addr)) return true; // unique-local fc00::/7
-	if (/^fe[89ab][0-9a-f]:/.test(addr)) return true; // link-local fe80::/10
-	return false;
-}
-
-/**
- * Parse a bare-IPv4 hostname in any encoding browsers/glibc accept — integer
- * (`2130706433`), octal (`0177.0.0.1`), hex (`0x7f000001`), and short forms
- * (`127.1`) — into a canonical dotted-decimal string. Returns null when the
- * host is not a numeric IPv4 literal (i.e. it's a real name or already-valid
- * dotted-quad, which callers handle separately).
- */
-function canonicalizeNumericIpv4(host: string): string | null {
-	// Already a clean dotted-quad — let isIP handle it directly.
-	if (isIP(host) === 4) return host;
-
-	const rawParts = host.split('.');
-	if (rawParts.length === 0 || rawParts.length > 4) return null;
-
-	const parseUInt = (s: string): number | null => {
-		if (s === '') return null;
-		let n: number;
-		if (/^0x[0-9a-f]+$/i.test(s)) n = parseInt(s, 16);
-		else if (/^0[0-7]+$/.test(s)) n = parseInt(s, 8);
-		else if (/^[0-9]+$/.test(s)) n = parseInt(s, 10);
-		else return null;
-		return Number.isFinite(n) ? n : null;
-	};
-
-	const nums = rawParts.map(parseUInt);
-	if (nums.some((n) => n === null)) return null;
-	const parts = nums as number[];
-
-	// inet_aton semantics: the final part absorbs all remaining low-order bytes.
-	// 1 part  → 32-bit value; 2 → a.(24-bit); 3 → a.b.(16-bit); 4 → a.b.c.d.
-	let value: number;
-	switch (parts.length) {
-		case 1:
-			value = parts[0];
-			break;
-		case 2:
-			if (parts[0] > 0xff || parts[1] > 0xffffff) return null;
-			value = (parts[0] << 24) | parts[1];
-			break;
-		case 3:
-			if (parts[0] > 0xff || parts[1] > 0xff || parts[2] > 0xffff) return null;
-			value = (parts[0] << 24) | (parts[1] << 16) | parts[2];
-			break;
-		default:
-			if (parts.some((p) => p > 0xff)) return null;
-			value = (parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3];
-	}
-	value = value >>> 0; // force unsigned 32-bit
-	if (value > 0xffffffff) return null;
-
-	return [(value >>> 24) & 0xff, (value >>> 16) & 0xff, (value >>> 8) & 0xff, value & 0xff].join(
-		'.'
-	);
-}
-
-/**
- * Synchronous literal pre-filter. Rejects bad schemes, loopback hostnames, and
- * any IP literal (in any encoding) that resolves to a blocked address. Does NOT
- * perform DNS — a public *name* that points at a private IP passes here and is
- * caught by `assertSafeRemoteDefinitionUrl`.
- */
-export function isSafeRemoteDefinitionUrl(raw: string): boolean {
-	let parsed: URL;
-	try {
-		parsed = new URL(raw);
-	} catch {
-		return false;
-	}
-	if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return false;
-
-	let host = parsed.hostname.toLowerCase();
-	if (!host) return false;
-
-	// Hostname literals that never reach DNS.
-	if (host === 'localhost' || host.endsWith('.localhost')) return false;
-
-	// Strip the brackets URL keeps around IPv6 literals.
-	const isBracketed = host.startsWith('[') && host.endsWith(']');
-	if (isBracketed) host = host.slice(1, -1);
-
-	if (isIP(host) === 6) return !isBlockedIp(host);
-
-	// Numeric IPv4 in any encoding → canonicalize, then judge.
-	const canonical = canonicalizeNumericIpv4(host);
-	if (canonical) return !isBlockedIp(canonical);
-
-	// A real hostname — passes the literal filter; DNS resolution is the gate.
-	return true;
-}
-
-/**
- * Full SSRF check: literal pre-filter, then resolve every A/AAAA record and
- * reject if *any* resolved IP is blocked. Returns the original URL on success
- * so callers can `await assertSafeRemoteDefinitionUrl(url)` inline. Throws on
- * any rejection.
- */
-export async function assertSafeRemoteDefinitionUrl(raw: string): Promise<string> {
-	if (!isSafeRemoteDefinitionUrl(raw)) {
-		throw new Error('Remote definition URL is not allowed');
-	}
-
-	const host = new URL(raw).hostname.toLowerCase().replace(/^\[|\]$/g, '');
-
-	// Already an IP literal — isSafeRemoteDefinitionUrl validated it; no DNS.
-	if (isIP(host) !== 0 || canonicalizeNumericIpv4(host)) return raw;
-
-	let resolved: { address: string }[];
-	try {
-		resolved = await lookup(host, { all: true });
-	} catch {
-		throw new Error('Remote definition URL is not allowed');
-	}
-	if (resolved.length === 0 || resolved.some((r) => isBlockedIp(r.address))) {
-		throw new Error('Remote definition URL is not allowed');
-	}
-	return raw;
-}

package/src/compute/solve-cache-envelope.ts

@@ -1,98 +0,0 @@
-/**
- * L2 cache entry format (R6). An entry is the gzipped response body plus a tiny
- * metadata header, so a hit is near-CPU-free: no `JSON.stringify`, no re-solve —
- * gzip clients get the stored bytes verbatim, and the header carries just enough
- * to rebuild the `ok` outcome (error/warning counts for the metric, uncompressed
- * length for the `Content-Length` on a gunzip fallback).
- *
- * Wire layout (opaque to the `ISolveResultCache` backend, which sees only bytes):
- *
- *   [ 4 bytes: header length N, big-endian uint32 ]
- *   [ N bytes: UTF-8 JSON EnvelopeHeader ]
- *   [ rest:    gzipped JSON response body ]
- *
- * The `algo` echo (M3) is already stripped at the source in the package's
- * `runSolve`, so the body never carries the base64 definition — entries stay
- * small without a strip step here.
- */
-
-import { gunzipSync } from 'node:zlib';
-
-/** Metadata stored beside the gzipped body. Small; parsed on every hit. */
-export interface EnvelopeHeader {
-	/** Grasshopper runtime error count, for the solve metric. */
-	errorCount: number;
-	/** Grasshopper runtime warning count, for the solve metric. */
-	warningCount: number;
-	/** Uncompressed JSON body length in bytes (Content-Length for a gunzip fallback). */
-	serializedBytes: number;
-	/**
-	 * SHA-256 hex of the canonical input preimage (H2 defense-in-depth). A hit
-	 * verifies this equals the requesting key's hash before serving — a wide-hash
-	 * collision that produced the same storage key still can't serve the wrong
-	 * geometry.
-	 */
-	inputHash: string;
-}
-
-/**
- * Encode a cache entry from the gzipped body + header. The body MUST already be
- * gzipped (the pipeline gzips before storing so every hit serves compressed
- * bytes; a rare non-gzip client gunzips on read).
- */
-export function encodeSolveCacheEntry(header: EnvelopeHeader, gzippedBody: Uint8Array): Uint8Array {
-	const headerJson = Buffer.from(JSON.stringify(header), 'utf8');
-	const out = Buffer.allocUnsafe(4 + headerJson.byteLength + gzippedBody.byteLength);
-	out.writeUInt32BE(headerJson.byteLength, 0);
-	headerJson.copy(out, 4);
-	Buffer.from(gzippedBody.buffer, gzippedBody.byteOffset, gzippedBody.byteLength).copy(
-		out,
-		4 + headerJson.byteLength
-	);
-	return out;
-}
-
-/** A decoded entry: the parsed header + the still-gzipped body slice. */
-export interface DecodedSolveCacheEntry {
-	header: EnvelopeHeader;
-	gzippedBody: Uint8Array;
-}
-
-/**
- * Decode a cache entry. Returns `null` on any malformed input (truncated, bad
- * length prefix, non-JSON header) — a corrupt entry is treated as a miss, never
- * an error, matching the best-effort cache contract.
- */
-export function decodeSolveCacheEntry(bytes: Uint8Array): DecodedSolveCacheEntry | null {
-	if (bytes.byteLength < 4) return null;
-	const buf = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-	const headerLen = buf.readUInt32BE(0);
-	const headerEnd = 4 + headerLen;
-	if (headerEnd > buf.byteLength) return null;
-	let header: EnvelopeHeader;
-	try {
-		header = JSON.parse(buf.toString('utf8', 4, headerEnd)) as EnvelopeHeader;
-	} catch {
-		return null;
-	}
-	if (
-		typeof header?.errorCount !== 'number' ||
-		typeof header?.warningCount !== 'number' ||
-		typeof header?.serializedBytes !== 'number' ||
-		typeof header?.inputHash !== 'string'
-	) {
-		return null;
-	}
-	// Slice (view, no copy) of the gzipped remainder.
-	const gzippedBody = new Uint8Array(
-		bytes.buffer,
-		bytes.byteOffset + headerEnd,
-		bytes.byteLength - headerEnd
-	);
-	return { header, gzippedBody };
-}
-
-/** Gunzip a stored body back to the JSON string, for a non-gzip client (rare). */
-export function gunzipEntryBody(gzippedBody: Uint8Array): string {
-	return gunzipSync(gzippedBody).toString('utf8');
-}

package/src/compute/solve-cache-key.ts

@@ -1,85 +0,0 @@
-/**
- * Durable L2 cache-key derivation (H2 / R8 / R13).
- *
- * The in-process L1 cache keys on a 32-bit FNV hash — fine for a 20-entry Map,
- * unsafe for a durable, cross-user cache where a collision serves user A's
- * geometry to user B (CONTEXT.md L92–97 records exactly this bug shipping once).
- * So the L2 key is a wide SHA-256 hash, and the entry stores the canonical
- * preimage so a hit can compare it byte-for-byte (defense-in-depth).
- *
- * What goes into the key:
- *   - The **transformed** input tree (R13) — the exact tree handed to the
- *     scheduler, canonicalized with the package's exported `stableStringify` so
- *     the L2 key parity-matches the L1 canonicalization path.
- *   - A **config subset** (R8): everything OTHER than definition+inputs that
- *     changes a solve's result — model units, tolerances, `dataversion`, the
- *     compute contract version, and (when known) the Rhino server identity. A
- *     durable key of `(versionId, inputHash)` alone would collide across
- *     differing server configs or Rhino versions.
- *
- * `versionId`, `definitionId`, and `orgId` are NOT hashed in here — they're
- * separate parts of the {@link SolveCacheKey} tuple so the backend can scope its
- * keyspace (per-definition quota, per-org isolation) without unpacking the hash.
- */
-
-import { createHash } from 'node:crypto';
-import { stableStringify } from '@selvajs/compute';
-import { COMPUTE_CONTRACT_VERSION } from './solve-pipeline.js';
-
-/**
- * Solve-affecting configuration folded into the key alongside the input tree.
- * Every field here is something that, if it changed, would legitimately change
- * the solve output for the SAME definition + inputs. Assemble it from the app's
- * resolved solve config; unset fields are simply absent from the canonical form.
- */
-export interface SolveCacheConfigSubset {
-	/** Rhino model unit system, if the app pins one (else the definition/server default). */
-	modelUnits?: string;
-	/** Absolute tolerance, if pinned. */
-	absoluteTolerance?: number;
-	/** Angle tolerance, if pinned. */
-	angleTolerance?: number;
-	/** Grasshopper `dataversion` / data-tree schema version, if pinned. */
-	dataVersion?: number | string;
-	/**
-	 * Compute-server identity (id or URL). Folds in because two servers can run
-	 * different Rhino/plugin versions that yield different geometry for the same
-	 * inputs. Optional — omit for a single-pool deployment where it's constant.
-	 */
-	computeServerId?: string;
-}
-
-/** The canonical preimage + its SHA-256 digest. Store both in the L2 entry header. */
-export interface SolveCacheInputKey {
-	/** The canonical string that was hashed (for hit-time byte comparison). */
-	canonical: string;
-	/** SHA-256 hex of {@link canonical} — the `inputKey` part of the storage key. */
-	hash: string;
-}
-
-/**
- * Derive the durable `inputKey` from the transformed input tree and the solve
- * config subset. Deterministic and stable across processes/instances: the same
- * tree + config always produce the same hash, which is what lets a shared cache
- * hit across app instances.
- *
- * @param transformedTree the tree AFTER `transformInputParameter`/`TreeBuilder`
- *   (R13) — the exact object handed to `scheduler.solve`.
- * @param config solve-affecting config (R8); `COMPUTE_CONTRACT_VERSION` is folded
- *   in automatically so a wire-contract bump invalidates old entries for free.
- */
-export function deriveSolveCacheInputKey(
-	transformedTree: unknown,
-	config: SolveCacheConfigSubset
-): SolveCacheInputKey {
-	// stableStringify sorts keys deterministically — same content, same string,
-	// regardless of property insertion order. Tag each part so a value can't shift
-	// across the tree/config boundary and collide (e.g. tree "]" meeting config "[").
-	const canonical = stableStringify({
-		v: COMPUTE_CONTRACT_VERSION,
-		tree: transformedTree,
-		config
-	});
-	const hash = createHash('sha256').update(canonical).digest('hex');
-	return { canonical, hash };
-}

package/src/compute/solve-cache-single-flight.ts

@@ -1,59 +0,0 @@
-/**
- * In-process single-flight (R4) — dogpile protection above the L2 cache.
- *
- * N identical live solves arriving while the first is still running would each
- * enqueue and each hit Rhino (the scheduler has no in-flight coalescing, and
- * Rhino's `cachesolve` still costs a round trip per repeat). The classic cold-key
- * stampede: a hot public definition + a deploy = a thundering herd onto compute.
- *
- * This coalesces them: the first caller for a key runs the work; concurrent
- * callers for the SAME key await the same promise and share its result. Once the
- * work settles (resolve OR reject), the key is released so the next request runs
- * fresh — the map never retains a settled entry, so it can't serve a stale
- * result or leak memory.
- *
- * It sits ABOVE the `ISolveResultCache` interface (in-process, per app instance).
- * A cross-instance lease (Redis `SET NX`) is a later backend capability; this is
- * the free first slice that covers the common same-instance burst.
- *
- * Correctness note: the shared promise resolves to ONE value for all waiters, so
- * the wrapped work must return an immutable / independently-serializable result
- * (the solve pipeline returns a fresh envelope object — safe to share by
- * reference here because the app serializes it per response).
- */
-
-export interface SolveCacheSingleFlight {
-	/**
-	 * Run `work` under `key`, coalescing concurrent identical calls. The first
-	 * caller executes; overlapping callers for the same key await the same promise.
-	 * The key is freed as soon as the promise settles (success or failure).
-	 */
-	run<T>(key: string, work: () => Promise<T>): Promise<T>;
-	/** Number of keys currently in flight (observability / tests). */
-	inFlight(): number;
-}
-
-export function createSolveCacheSingleFlight(): SolveCacheSingleFlight {
-	const inflight = new Map<string, Promise<unknown>>();
-
-	return {
-		run<T>(key: string, work: () => Promise<T>): Promise<T> {
-			const existing = inflight.get(key);
-			if (existing) return existing as Promise<T>;
-
-			// `.finally` releases the key on both settle paths. Start the work inside
-			// the promise chain so a synchronous throw in `work` still rejects the
-			// shared promise (and still frees the key) rather than escaping.
-			const p = (async () => work())().finally(() => {
-				// Only delete if it's still OUR promise — a key freed and re-taken by a
-				// later caller must not be clobbered.
-				if (inflight.get(key) === p) inflight.delete(key);
-			});
-			inflight.set(key, p);
-			return p;
-		},
-		inFlight(): number {
-			return inflight.size;
-		}
-	};
-}