@spacefast/common 0.0.10 → 0.0.12

package/dist/utils/egress-policy.fixtures.json

@@ -0,0 +1,51 @@
+{
+    "comment": "Shared egress-policy corpus (spec: one proxy-egress-safety invariant). Exercised by BOTH enforcers: apps/control-plane/src/http/egress-guard.ts (control-plane SSRF guard) and runtime/engine/shared/egress.php (runtime proxy egress). Every case must produce the same verdict in TypeScript and PHP; parity is asserted by apps/control-plane/src/runtime/php-policy-parity.test.ts and src/http/egress-guard.test.ts.",
+    "ips": [
+        { "ip": "127.0.0.1", "public": false, "reason": "loopback" },
+        { "ip": "127.8.9.10", "public": false, "reason": "loopback /8" },
+        { "ip": "0.0.0.0", "public": false, "reason": "this-network" },
+        { "ip": "10.0.0.1", "public": false, "reason": "RFC1918" },
+        { "ip": "172.16.0.1", "public": false, "reason": "RFC1918" },
+        { "ip": "172.31.255.255", "public": false, "reason": "RFC1918 upper bound" },
+        { "ip": "172.32.0.1", "public": true, "reason": "outside 172.16/12" },
+        { "ip": "192.168.1.1", "public": false, "reason": "RFC1918" },
+        { "ip": "100.64.0.1", "public": false, "reason": "carrier-grade NAT" },
+        { "ip": "169.254.169.254", "public": false, "reason": "cloud metadata" },
+        { "ip": "169.254.0.1", "public": false, "reason": "link-local" },
+        { "ip": "192.0.0.1", "public": false, "reason": "special-purpose" },
+        { "ip": "192.0.2.1", "public": false, "reason": "TEST-NET-1" },
+        { "ip": "198.18.0.1", "public": false, "reason": "benchmarking" },
+        { "ip": "198.51.100.7", "public": false, "reason": "TEST-NET-2" },
+        { "ip": "203.0.113.9", "public": false, "reason": "TEST-NET-3" },
+        { "ip": "224.0.0.1", "public": false, "reason": "multicast" },
+        { "ip": "255.255.255.255", "public": false, "reason": "broadcast" },
+        { "ip": "8.8.8.8", "public": true, "reason": "public" },
+        { "ip": "1.1.1.1", "public": true, "reason": "public" },
+        { "ip": "93.184.216.34", "public": true, "reason": "public" },
+        { "ip": "::1", "public": false, "reason": "loopback" },
+        { "ip": "::", "public": false, "reason": "unspecified" },
+        { "ip": "fe80::1", "public": false, "reason": "link-local" },
+        { "ip": "fc00::1", "public": false, "reason": "unique-local" },
+        { "ip": "fd00:ec2::254", "public": false, "reason": "ULA cloud metadata" },
+        { "ip": "ff02::1", "public": false, "reason": "multicast" },
+        { "ip": "2001:db8::1", "public": false, "reason": "documentation" },
+        { "ip": "100::1", "public": false, "reason": "discard-only" },
+        { "ip": "64:ff9b::808:808", "public": false, "reason": "NAT64 denied outright" },
+        { "ip": "::ffff:10.0.0.1", "public": false, "reason": "IPv4-mapped private" },
+        { "ip": "::ffff:a00:1", "public": false, "reason": "IPv4-mapped private (hex form)" },
+        {
+            "ip": "::ffff:8.8.8.8",
+            "public": true,
+            "reason": "IPv4-mapped public defers to inner policy"
+        },
+        { "ip": "2606:4700:4700::1111", "public": true, "reason": "public" }
+    ],
+    "hosts": [
+        { "host": "localhost", "allowed": false },
+        { "host": "sub.localhost", "allowed": false },
+        { "host": "169.254.169.254", "allowed": false },
+        { "host": "view.fast", "allowed": false },
+        { "host": "wpc-manage-site-123.view.fast", "allowed": false },
+        { "host": "example.com", "allowed": true }
+    ]
+}

package/dist/utils/id-hints.d.ts

@@ -1,5 +1,6 @@
 export declare const HINT_SCAN_CAP = 200;
 export declare const HINT_MAX_CANDIDATES = 5;
+export declare const HINT_MAX_KEY_LENGTH = 256;
 export declare function levenshtein(a: string, b: string): number;
 export declare function refCloseness(needle: string, candidate: string): number;
 export declare function rankCandidates<T>(ref: string, rows: T[], keysOf: (row: T) => Array<string | null | undefined>, options?: {

package/dist/utils/id-hints.js

@@ -9,19 +9,44 @@
 // returns only the recovery hint (no candidate ids).
 export const HINT_SCAN_CAP = 200;
 export const HINT_MAX_CANDIDATES = 5;
-export function levenshtein(a, b) {
-    const rows = a.length + 1;
-    const cols = b.length + 1;
-    let previous = Array.from({ length: cols }, (_, index) => index);
-    for (let i = 1; i < rows; i++) {
-        const current = [i, ...Array.from({ length: cols - 1 }, () => 0)];
-        for (let j = 1; j < cols; j++) {
+// All supported hint keys (ids, slugs, hostnames, and numeric version refs) fit
+// within this ceiling. Rejecting larger values keeps best-effort 404 recovery
+// from turning attacker-controlled refs or stored labels into quadratic work.
+export const HINT_MAX_KEY_LENGTH = 256;
+function boundedLevenshtein(a, b, maxDistance) {
+    if (Math.abs(a.length - b.length) > maxDistance)
+        return maxDistance + 1;
+    // Keep the rolling rows on the shorter input. The band avoids evaluating
+    // cells that cannot contribute a result within maxDistance.
+    if (b.length > a.length)
+        [a, b] = [b, a];
+    let previous = new Uint16Array(b.length + 1);
+    let current = new Uint16Array(b.length + 1);
+    for (let j = 0; j <= b.length; j++)
+        previous[j] = j;
+    const outsideBand = maxDistance + 1;
+    for (let i = 1; i <= a.length; i++) {
+        current.fill(outsideBand);
+        current[0] = i <= maxDistance ? i : outsideBand;
+        const start = Math.max(1, i - maxDistance);
+        const end = Math.min(b.length, i + maxDistance);
+        let rowMinimum = current[0] ?? outsideBand;
+        for (let j = start; j <= end; j++) {
             const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-            current[j] = Math.min((current[j - 1] ?? 0) + 1, (previous[j] ?? 0) + 1, (previous[j - 1] ?? 0) + cost);
+            current[j] = Math.min((current[j - 1] ?? outsideBand) + 1, (previous[j] ?? outsideBand) + 1, (previous[j - 1] ?? outsideBand) + cost);
+            rowMinimum = Math.min(rowMinimum, current[j] ?? outsideBand);
         }
-        previous = current;
+        if (rowMinimum > maxDistance)
+            return outsideBand;
+        [previous, current] = [current, previous];
+    }
+    return previous[b.length] ?? outsideBand;
+}
+export function levenshtein(a, b) {
+    if (a.length > HINT_MAX_KEY_LENGTH || b.length > HINT_MAX_KEY_LENGTH) {
+        return Number.POSITIVE_INFINITY;
     }
-    return previous[cols - 1] ?? 0;
+    return boundedLevenshtein(a, b, Math.max(a.length, b.length));
 }
 // Returns a small finite score the closer `candidate` is to `needle`, or
 // +Infinity when they are not genuinely close. Exact match = 0; substring
@@ -29,14 +54,17 @@ export function levenshtein(a, b) {
 export function refCloseness(needle, candidate) {
     if (!candidate)
         return Number.POSITIVE_INFINITY;
+    if (needle.length > HINT_MAX_KEY_LENGTH || candidate.length > HINT_MAX_KEY_LENGTH) {
+        return Number.POSITIVE_INFINITY;
+    }
     if (candidate === needle)
         return 0;
     if (candidate.includes(needle) || needle.includes(candidate))
         return 1;
-    const distance = levenshtein(needle, candidate);
     // Only surface genuinely close typos: bound the allowed distance by the shorter
     // string so short refs don't match everything.
     const tolerance = Math.max(2, Math.floor(Math.min(needle.length, candidate.length) / 3));
+    const distance = boundedLevenshtein(needle, candidate, tolerance);
     return distance <= tolerance ? 1 + distance : Number.POSITIVE_INFINITY;
 }
 // Rank `rows` by how close any of their keys are to `ref`, returning at most
@@ -44,14 +72,28 @@ export function refCloseness(needle, candidate) {
 // only genuine near-matches surface. Ties break by the optional comparator
 // (e.g. recency); keys are matched case-insensitively.
 export function rankCandidates(ref, rows, keysOf, options) {
+    if (rows.length > HINT_SCAN_CAP || ref.length > HINT_MAX_KEY_LENGTH)
+        return [];
     const needle = ref.toLowerCase();
+    // Unicode case conversion can expand a string (for example, U+0130). Keep
+    // that normalized representation under the same work ceiling too.
+    if (needle.length > HINT_MAX_KEY_LENGTH)
+        return [];
     const max = options?.max ?? HINT_MAX_CANDIDATES;
     return rows
         .map((row) => {
-        const scores = keysOf(row).map((key) => key ? refCloseness(needle, key.toLowerCase()) : Number.POSITIVE_INFINITY);
+        let score = Number.POSITIVE_INFINITY;
+        for (const key of keysOf(row)) {
+            if (!key || key.length > HINT_MAX_KEY_LENGTH)
+                continue;
+            const candidate = key.toLowerCase();
+            if (candidate.length > HINT_MAX_KEY_LENGTH)
+                continue;
+            score = Math.min(score, refCloseness(needle, candidate));
+        }
         return {
             row,
-            score: scores.length > 0 ? Math.min(...scores) : Number.POSITIVE_INFINITY,
+            score,
         };
     })
         .filter((entry) => entry.score < Number.POSITIVE_INFINITY)

package/dist/utils/page-colors.d.ts

@@ -0,0 +1,50 @@
+import type { SpacePageTheme } from "../contracts/space-config.js";
+/** Default page palette (mirrored into the shared template CSS). */
+export declare const PAGE_COLOR_DEFAULTS: {
+    readonly accent: "#ff4217";
+    readonly bg: "#f9f8f4";
+    readonly fg: "#1a1913";
+    readonly muted: "#6f6b62";
+    readonly card: "#f9f8f4";
+    readonly border: "#ddd9cf";
+    readonly darkBg: "#141313";
+    readonly darkFg: "#e9e7e2";
+    readonly darkMuted: "#8f8b84";
+    readonly darkCard: "#141313";
+    readonly darkBorder: "#2b2a27";
+};
+export type PageSchemeColors = {
+    bg: string;
+    fg: string;
+    muted: string;
+    card: string;
+    border: string;
+    error: string;
+};
+export type DerivedPageColors = {
+    /** `adaptive` keeps the built-in light/dark schemes; otherwise pinned. */
+    scheme: "adaptive" | "light" | "dark";
+    /** The accent exactly as pushed (fills keep the brand color verbatim). */
+    accent: string;
+    /** Label color on accent fills. */
+    onAccent: string;
+    /** Accent-derived link color, readable on the light (or pinned) surface. */
+    link: string;
+    /** Adaptive only: link color readable on the built-in dark surface. */
+    linkDark?: string;
+    /** Full derived scheme when a background pins the page. */
+    pinned?: PageSchemeColors;
+};
+/**
+ * Return `color` unchanged when it already meets `target` on `surface`;
+ * otherwise move its OKLCH lightness (hue/chroma preserved) just far enough
+ * to meet it. Falls back to plain black/white when even full lightness range
+ * cannot reach the target (e.g. a mid-gray surface).
+ */
+export declare function readableOn(color: string, surface: string, target: number): string;
+/** Button-label color for an accent fill: white when it can carry, else ink. */
+export declare function onAccentColor(accent: string): string;
+/** The one entry point: raw theme in, everything the templates paint with out. */
+export declare function derivePageColors(theme: Pick<SpacePageTheme, "accent" | "background">): DerivedPageColors;
+/** Hex form of any schema-accepted color, for color-picker inputs. */
+export declare function pageColorToHex(value: string): string | null;

package/dist/utils/page-colors.js

@@ -0,0 +1,167 @@
+// Readability engine for Spacefast-authored pages.
+//
+// Theme colors are intent, not CSS: users and agents push any accent or
+// background (dashboard, spacefast.jsonc, API) and the platform guarantees
+// every rendered page stays readable. This module derives the full set of
+// colors the templates actually paint with:
+//
+//   - `onAccent`  — button-label color on accent fills (black or white).
+//   - `link`      — the accent, lightness-adjusted until it meets WCAG AA
+//                   against the surface it sits on. Hue and chroma survive,
+//                   so it still reads as the brand color.
+//   - `pinned`    — when a background is set, a complete coherent scheme
+//                   (fg/muted/surface/border) derived from it and pinned for
+//                   every visitor. A chosen background IS the page; the
+//                   visitor's OS dark-mode setting must not repaint half the
+//                   variables into an unreadable hybrid.
+//
+// Everything is pure and deterministic: publish finalize, dashboard previews,
+// and tests all call the same functions and get the same pixels.
+import { formatHex, oklch, parse, wcagContrast } from "culori";
+/** Default page palette (mirrored into the shared template CSS). */
+export const PAGE_COLOR_DEFAULTS = {
+    accent: "#ff4217",
+    bg: "#f9f8f4",
+    fg: "#1a1913",
+    muted: "#6f6b62",
+    card: "#f9f8f4",
+    border: "#ddd9cf",
+    darkBg: "#141313",
+    darkFg: "#e9e7e2",
+    darkMuted: "#8f8b84",
+    darkCard: "#141313",
+    darkBorder: "#2b2a27",
+};
+/** WCAG AA for body-size text. */
+const TEXT_CONTRAST = 4.5;
+/** Body-size button labels on accent fills. */
+const UI_CONTRAST = 4.5;
+/** Essential control boundaries against their painted surface. */
+const CONTROL_CONTRAST = 3;
+/** Primary foreground meets AA even on mid-tone custom backgrounds. */
+const FG_CONTRAST = 4.5;
+function safeParse(value) {
+    if (!value)
+        return undefined;
+    try {
+        return parse(value.trim());
+    }
+    catch {
+        return undefined;
+    }
+}
+function contrast(a, b) {
+    return wcagContrast(a, b);
+}
+function isLightSurface(surface) {
+    return contrast("#000000", surface) >= contrast("#ffffff", surface);
+}
+/**
+ * Return `color` unchanged when it already meets `target` on `surface`;
+ * otherwise move its OKLCH lightness (hue/chroma preserved) just far enough
+ * to meet it. Falls back to plain black/white when even full lightness range
+ * cannot reach the target (e.g. a mid-gray surface).
+ */
+export function readableOn(color, surface, target) {
+    if (contrast(color, surface) >= target)
+        return color;
+    const parsed = safeParse(color);
+    const converted = parsed ? oklch(parsed) : undefined;
+    if (!converted)
+        return isLightSurface(surface) ? "#000000" : "#ffffff";
+    const base = { mode: "oklch", l: converted.l, c: converted.c, h: converted.h ?? 0 };
+    const darken = isLightSurface(surface);
+    const limit = darken ? 0 : 1;
+    const atLimit = formatHex({ ...base, l: limit });
+    if (contrast(atLimit, surface) < target) {
+        return isLightSurface(surface) ? "#000000" : "#ffffff";
+    }
+    // Binary search for the lightness closest to the original that still meets
+    // the target; contrast is monotonic in lightness on a fixed surface side.
+    let searchLimit = limit;
+    let searchStart = base.l;
+    for (let i = 0; i < 24; i += 1) {
+        const mid = (searchStart + searchLimit) / 2;
+        if (contrast(formatHex({ ...base, l: mid }), surface) >= target) {
+            searchLimit = mid;
+        }
+        else {
+            searchStart = mid;
+        }
+    }
+    return formatHex({ ...base, l: searchLimit });
+}
+/** Button-label color for an accent fill: white when it can carry, else ink. */
+export function onAccentColor(accent) {
+    return contrast("#ffffff", accent) >= UI_CONTRAST ? "#ffffff" : "#000000";
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+/** Derive a complete coherent scheme from a pushed background color. */
+function schemeFromBackground(background) {
+    const parsed = safeParse(background);
+    const bg = parsed ? formatHex(parsed) : PAGE_COLOR_DEFAULTS.bg;
+    const base = (parsed ? oklch(parsed) : undefined) ?? {
+        mode: "oklch",
+        l: 0.98,
+        c: 0.004,
+        h: 80,
+    };
+    const hue = base.h ?? 0;
+    const tint = Math.min(base.c ?? 0, 0.02);
+    if (isLightSurface(bg)) {
+        return {
+            polarity: "light",
+            colors: {
+                bg,
+                card: bg,
+                fg: readableOn(PAGE_COLOR_DEFAULTS.fg, bg, FG_CONTRAST),
+                muted: readableOn(formatHex({ mode: "oklch", l: 0.55, c: tint, h: hue }), bg, TEXT_CONTRAST),
+                border: readableOn(formatHex({ mode: "oklch", l: 0.9, c: Math.min(tint, 0.015), h: hue }), bg, CONTROL_CONTRAST),
+                error: readableOn("#a82d1a", bg, TEXT_CONTRAST),
+            },
+        };
+    }
+    const borderL = clamp(base.l + 0.1, 0.28, 0.45);
+    return {
+        polarity: "dark",
+        colors: {
+            bg,
+            card: bg,
+            fg: readableOn(PAGE_COLOR_DEFAULTS.darkFg, bg, FG_CONTRAST),
+            muted: readableOn(formatHex({ mode: "oklch", l: 0.72, c: tint, h: hue }), bg, TEXT_CONTRAST),
+            border: readableOn(formatHex({ mode: "oklch", l: borderL, c: tint, h: hue }), bg, CONTROL_CONTRAST),
+            error: readableOn("#ff8a7a", bg, TEXT_CONTRAST),
+        },
+    };
+}
+/** The one entry point: raw theme in, everything the templates paint with out. */
+export function derivePageColors(theme) {
+    const accentInput = theme.accent?.trim();
+    const accent = safeParse(accentInput) ? accentInput : PAGE_COLOR_DEFAULTS.accent;
+    const onAccent = onAccentColor(accent);
+    const background = theme.background?.trim();
+    if (background && safeParse(background)) {
+        const { polarity, colors } = schemeFromBackground(background);
+        return {
+            scheme: polarity,
+            accent,
+            onAccent,
+            link: readableOn(accent, colors.card, TEXT_CONTRAST),
+            pinned: colors,
+        };
+    }
+    return {
+        scheme: "adaptive",
+        accent,
+        onAccent,
+        link: readableOn(accent, PAGE_COLOR_DEFAULTS.card, TEXT_CONTRAST),
+        linkDark: readableOn(accent, PAGE_COLOR_DEFAULTS.darkCard, TEXT_CONTRAST),
+    };
+}
+/** Hex form of any schema-accepted color, for color-picker inputs. */
+export function pageColorToHex(value) {
+    const parsed = safeParse(value);
+    return parsed ? formatHex(parsed) : null;
+}