@selvajs/server 0.2.0-beta.1

package/dist/compute/remote-definition.js

@@ -0,0 +1,110 @@
+/**
+ * Remote-definition fetch: SSRF-guarded, size-capped, timed, and TTL-cached.
+ *
+ * A solve can reference its `.gh` by remote URL instead of a stored blob. That
+ * URL is attacker-controllable (a share-token caller supplies `definitionUrl`),
+ * so every fetch runs through {@link assertSafeRemoteDefinitionUrl} (literal +
+ * DNS host validation, blocking private/loopback/link-local targets and
+ * literal-encoding bypasses), streams the body with an early size cap, and
+ * bounds the wall time with a deadline.
+ *
+ * The TTL cache is a per-fetcher `Map<url, {data, fetchedAt}>` so repeated
+ * solves of the same remote definition skip the network. It's created by
+ * {@link createRemoteDefinitionFetcher} rather than being module-global, so a
+ * consuming app can hold one fetcher per process (the app binding does) or
+ * several isolated ones (tests) without shared state leaking across them.
+ */
+import { assertSafeRemoteDefinitionUrl } from './safe-url.js';
+/** Once the cache exceeds this many entries, evict the oldest 10 by `fetchedAt`. */
+const CACHE_MAX_ENTRIES = 50;
+const CACHE_EVICT_BATCH = 10;
+/**
+ * Read a response body into memory, aborting (and throwing) as soon as the
+ * running byte total exceeds `maxBytes`. Falls back to `arrayBuffer()` only when
+ * the body isn't a readable stream (older fetch impls). Exported for direct use
+ * and reuse; the fetcher below wraps it with SSRF + TTL.
+ */
+export async function readBodyWithCap(response, maxBytes, controller) {
+    if (!response.body) {
+        const buffer = await response.arrayBuffer();
+        if (buffer.byteLength > maxBytes)
+            throw new Error('Remote definition exceeds size limit');
+        return new Uint8Array(buffer);
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            controller.abort();
+            throw new Error('Remote definition exceeds size limit');
+        }
+        chunks.push(value);
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+/**
+ * Build a remote-definition fetcher owning its own TTL cache. Each fetcher's
+ * cache is independent, so one per process shares warm bytes while test fetchers
+ * stay isolated.
+ */
+export function createRemoteDefinitionFetcher(config) {
+    const cache = new Map();
+    return {
+        async load(url) {
+            // Resolves the host and rejects when any resolved IP is private/loopback/
+            // link-local — covers literal-encoding bypasses (integer/octal/hex/short-form,
+            // IPv4-mapped IPv6) and public names that point inward. Throws on rejection.
+            await assertSafeRemoteDefinitionUrl(url);
+            const now = config.now();
+            const cached = cache.get(url);
+            if (cached && now - cached.fetchedAt < config.cacheTtlMs) {
+                return cached.data;
+            }
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), config.fetchTimeoutMs);
+            let data;
+            try {
+                const response = await fetch(url, {
+                    signal: controller.signal,
+                    redirect: 'error'
+                });
+                if (!response.ok) {
+                    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+                }
+                // Reject early when the server declares an oversized body.
+                const declared = Number(response.headers.get('content-length'));
+                if (Number.isFinite(declared) && declared > config.maxBytes) {
+                    throw new Error('Remote definition exceeds size limit');
+                }
+                // Stream and count rather than `arrayBuffer()` — a missing/lying
+                // content-length must not let an unbounded body buffer into memory
+                // before the cap is checked. Abort the moment we cross the limit.
+                data = await readBodyWithCap(response, config.maxBytes, controller);
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+            cache.set(url, { data, fetchedAt: now });
+            if (cache.size > CACHE_MAX_ENTRIES) {
+                const entries = Array.from(cache.entries());
+                entries.sort((a, b) => a[1].fetchedAt - b[1].fetchedAt);
+                for (let i = 0; i < CACHE_EVICT_BATCH; i++) {
+                    cache.delete(entries[i][0]);
+                }
+            }
+            return data;
+        }
+    };
+}
+//# sourceMappingURL=remote-definition.js.map

package/dist/compute/remote-definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-definition.js","sourceRoot":"","sources":["../../src/compute/remote-definition.ts"],"names":[],"mappings":"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"}

package/dist/compute/safe-url.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 declare function isSafeRemoteDefinitionUrl(raw: string): boolean;
+/**
+ * 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 declare function assertSafeRemoteDefinitionUrl(raw: string): Promise<string>;
+//# sourceMappingURL=safe-url.d.ts.map

package/dist/compute/safe-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-url.d.ts","sourceRoot":"","sources":["../../src/compute/safe-url.ts"],"names":[],"mappings":"AA4HA;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CA2B9D;AAED;;;;;GAKG;AACH,wBAAsB,6BAA6B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAoBhF"}

package/dist/compute/safe-url.js

@@ -0,0 +1,195 @@
+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) {
+    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) {
+    // 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) => {
+        if (s === '')
+            return null;
+        let n;
+        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;
+    // 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;
+    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) {
+    let parsed;
+    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) {
+    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;
+    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;
+}
+//# sourceMappingURL=safe-url.js.map

package/dist/compute/safe-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-url.js","sourceRoot":"","sources":["../../src/compute/safe-url.ts"],"names":[],"mappings":"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"}

package/dist/compute/solve-pipeline.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Transport-agnostic solve pipeline — the callable core lifted out of the app's
+ * `/api/compute` route (embeddable-server-layer plan, K3).
+ *
+ * Given an already-resolved solve context — the `.gh` bytes, the input params +
+ * user values, and a warm `SolveScheduler` (from `createClientCache`) — this
+ * runs the framework-free half of a solve:
+ *
+ *   input tree build → scheduler.solve (with abort/timeout classification) →
+ *   JSON serialize (size-guarded) → optional gzip → Server-Timing envelope.
+ *
+ * It returns a discriminated {@link SolveOutcome}: `ok` carries the ready-to-send
+ * {@link SolveEnvelope} (body + headers + phase metrics), while the error
+ * variants (`timeout`, `client_abort`, `too_large`, `compute_error`) name a
+ * failure the transport maps to its own status code. Nothing here throws for an
+ * expected failure and nothing here touches auth, the database, share tokens,
+ * rate limits, or metric sinks — those stay app policy in the route.
+ *
+ * The Server-Timing string it emits IS the versioned wire contract (audit D5):
+ * see {@link COMPUTE_CONTRACT_VERSION} and {@link COMPUTE_VERSION_HEADER}.
+ */
+import { type GrasshopperComputeResponse } from '@selvajs/compute';
+import type { SchemaInput } from '@selvajs/schemas';
+import type { CachedClient } from './client-cache.js';
+/** Current compute-response contract version. Additive header; bump on shape change. */
+export declare const COMPUTE_CONTRACT_VERSION: 1;
+/** Response header carrying {@link COMPUTE_CONTRACT_VERSION}. */
+export declare const COMPUTE_VERSION_HEADER = "X-Selva-Compute-Version";
+/** A schema input carrying the optional numeric bounds the transform reads. */
+export type PipelineInput = SchemaInput & {
+    minimum?: number;
+    maximum?: number;
+    stepSize?: number;
+};
+export interface SolvePipelineArgs {
+    /** The `.gh` bytes to solve (stored blob or remote fetch — resolved by the caller). */
+    definitionSource: Uint8Array;
+    /** Persisted input params; only those with a `paramType` are sent to the solve. */
+    inputs: PipelineInput[];
+    /** User-chosen values keyed by input id; missing keys fall back to the schema default. */
+    values: Record<string, unknown>;
+    /** Warm client bundle from `createClientCache().getClient(...)`. */
+    client: CachedClient;
+    /** Longest a serialized result may be (bytes) before a 413. */
+    responseMaxBytes: number;
+    /** Solve-deadline millis — used only to phrase the timeout message. */
+    maxSolveDurationMs: number;
+    /** Client's `Accept-Encoding`; gzip is applied only when it advertises `gzip`. */
+    acceptEncoding: string;
+    /**
+     * Request abort signal, forwarded to the scheduler so a client disconnect
+     * cancels the upstream compute call. Its `aborted` flag also disambiguates a
+     * client disconnect from the scheduler's own deadline firing.
+     */
+    signal: AbortSignal;
+    /**
+     * Wall-clock origin (`performance.now()` captured at the top of the request)
+     * so the pipeline's `load`/`total` phase timings line up with the caller's
+     * pre-solve prep. The caller owns everything before this and stamps `defLoadMs`.
+     */
+    loadStartMs: number;
+    /** Pre-solve "load" phase duration the caller already measured (auth + DB + fetch). */
+    defLoadMs: number;
+    /**
+     * Pre-solve prep sub-phase marks (`[label, ms]`), surfaced verbatim as `p_*`
+     * Server-Timing entries. The caller assembles these; the pipeline only echoes.
+     */
+    prepMarks?: [string, number][];
+}
+/** Phase timings the pipeline measured; the caller uses them for debug logging. */
+export interface SolvePhaseMetrics {
+    treeBuildMs: number;
+    solveMs: number;
+    serializeMs: number;
+    gzipMs: number;
+    serverTotalMs: number;
+    /** Uncompressed serialized length in bytes. */
+    serializedBytes: number;
+    /** Gzipped length in bytes, or null when compression was skipped. */
+    compressedBytes: number | null;
+}
+/** A ready-to-send response: body + headers + the solve result + phase metrics. */
+export interface SolveEnvelope {
+    /** The response body — a gzip `Uint8Array` when `encoding === 'gzip'`, else the JSON string. */
+    body: string | Uint8Array;
+    /** `'gzip'` when the body is compressed; absent otherwise. */
+    encoding?: 'gzip';
+    /** Fully-assembled response headers (Content-Type/-Length/-Encoding, Vary, Server-Timing, version). */
+    headers: Record<string, string>;
+    /** The solved definition — the caller reads `errors`/`warnings` for its metric record. */
+    result: GrasshopperComputeResponse;
+    /** Phase timings, for the caller's optional debug breakdown. */
+    metrics: SolvePhaseMetrics;
+}
+/**
+ * Discriminated result. `ok` carries the envelope; every other variant names an
+ * expected failure the transport maps to a status code (the app route maps
+ * timeout→504, client_abort→499, too_large→413; `compute_error` re-surfaces the
+ * original error for the generic 500/503 path). `durationMs` on the error
+ * variants is the solve wall time up to the failure, for the metric record.
+ */
+export type SolveOutcome = {
+    kind: 'ok';
+    envelope: SolveEnvelope;
+    solveMs: number;
+    errorCount: number;
+    warningCount: number;
+} | {
+    kind: 'timeout';
+    durationMs: number;
+    message: string;
+} | {
+    kind: 'client_abort';
+    durationMs: number;
+} | {
+    kind: 'too_large';
+} | {
+    kind: 'compute_error';
+    durationMs: number;
+    error: unknown;
+};
+/**
+ * Run the framework-free half of a solve and produce a typed outcome. See the
+ * module doc for the phase sequence and the app/library boundary.
+ */
+export declare function runSolvePipeline(args: SolvePipelineArgs): Promise<SolveOutcome>;
+//# sourceMappingURL=solve-pipeline.d.ts.map

package/dist/compute/solve-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solve-pipeline.d.ts","sourceRoot":"","sources":["../../src/compute/solve-pipeline.ts"],"names":[],"mappings":"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"}