@spacefast/common 0.0.11 → 0.0.13

package/dist/utils/dns-instructions.js

@@ -0,0 +1,78 @@
+import { DnsInstructionSchema } from "../contracts/common.js";
+function normalizeDnsName(value) {
+    return value.trim().toLowerCase().replace(/\.$/, "");
+}
+export function addressDnsInstructionsForHostname(input) {
+    const hostname = normalizeDnsName(input.hostname);
+    return input.dnsInstructions.flatMap((candidate) => {
+        const parsed = DnsInstructionSchema.safeParse(candidate);
+        if (!parsed.success) {
+            return [];
+        }
+        const instruction = parsed.data;
+        if ((instruction.type !== "A" && instruction.type !== "AAAA") ||
+            instruction.purpose !== "routing" ||
+            normalizeDnsName(instruction.name) !== hostname) {
+            return [];
+        }
+        return [
+            {
+                type: instruction.type,
+                name: instruction.name,
+                value: instruction.value,
+                purpose: instruction.purpose,
+                ...(instruction.ttl === undefined ? {} : { ttl: instruction.ttl }),
+            },
+        ];
+    });
+}
+function normalizeAddress(value) {
+    const address = value.trim().toLowerCase();
+    if (!address.includes(":")) {
+        return address;
+    }
+    try {
+        return new URL(`http://[${address}]`).hostname.slice(1, -1);
+    }
+    catch {
+        return address;
+    }
+}
+export function isWpCloudInboundIpv4(value) {
+    const match = /^192\.0\.79\.(\d{1,3})$/.exec(value);
+    if (!match) {
+        return false;
+    }
+    const octet = Number(match[1]);
+    return octet >= 128 && octet <= 191;
+}
+function instructionAcceptsObservedAddress(instruction, observedValue) {
+    const expected = normalizeAddress(instruction.value);
+    const observed = normalizeAddress(observedValue);
+    return observed === expected || (instruction.type === "A" && isWpCloudInboundIpv4(observed));
+}
+export function addressDnsInstructionIsObserved(input) {
+    const observed = input.instruction.type === "A" ? input.records.a : input.records.aaaa;
+    return observed.some((value) => instructionAcceptsObservedAddress(input.instruction, value));
+}
+export function unsupportedAddressDnsRecordsForHostname(input) {
+    const instructions = addressDnsInstructionsForHostname(input);
+    if (instructions.length === 0) {
+        return [];
+    }
+    const records = [
+        ...input.records.a.map((value) => ({ type: "A", value })),
+        ...input.records.aaaa.map((value) => ({ type: "AAAA", value })),
+    ].filter((record) => !instructions.some((instruction) => instruction.type === record.type &&
+        instructionAcceptsObservedAddress(instruction, record.value)));
+    const unique = new Set();
+    return records.flatMap((record) => {
+        const value = record.value.trim();
+        const key = `${record.type}:${value}`;
+        if (!value || unique.has(key)) {
+            return [];
+        }
+        unique.add(key);
+        return [{ ...record, name: input.hostname }];
+    });
+}

package/dist/utils/domain-diagnostics.d.ts

@@ -0,0 +1,29 @@
+export type HostnameDiagnosticsForActions = {
+    hostname: string;
+    providerIps: string[];
+    dnsInstructions: unknown[];
+    dns: {
+        pointsToProvider: boolean;
+        txtVerified: boolean | null;
+        expectedTxtValue: string | null;
+        records?: {
+            a: string[];
+            aaaa: string[];
+        };
+    };
+    ssl: {
+        status: string;
+        canRetry: boolean;
+        brokenRecord: {
+            reason: string | null;
+            lastError: string | null;
+        } | null;
+    };
+};
+export type DomainRequiredAction = {
+    code: string;
+    hostname: string;
+    message: string;
+};
+/** Turn hostname diagnostics into the actions a user must take to finish binding. */
+export declare function domainRequiredActions(hostnameDiagnostics: HostnameDiagnosticsForActions[]): DomainRequiredAction[];

package/dist/utils/domain-diagnostics.js

@@ -0,0 +1,63 @@
+import { addressDnsInstructionIsObserved, addressDnsInstructionsForHostname, unsupportedAddressDnsRecordsForHostname, } from "./dns-instructions.js";
+/** Turn hostname diagnostics into the actions a user must take to finish binding. */
+export function domainRequiredActions(hostnameDiagnostics) {
+    const actions = [];
+    for (const entry of hostnameDiagnostics) {
+        const unsupportedRecords = entry.dns.records
+            ? unsupportedAddressDnsRecordsForHostname({ ...entry, records: entry.dns.records })
+            : [];
+        actions.push(...unsupportedRecords.map((record) => ({
+            code: "dns_unaccepted_address",
+            hostname: entry.hostname,
+            message: `Remove the ${record.type} record on ${record.name} with value ${record.value}; it does not match a Spacefast target for this hostname.`,
+        })));
+        if (!entry.dns.pointsToProvider) {
+            const routingInstructions = addressDnsInstructionsForHostname(entry);
+            const observedAddressRecords = entry.dns.records;
+            const missingRoutingInstructions = observedAddressRecords
+                ? routingInstructions.filter((instruction) => !addressDnsInstructionIsObserved({
+                    instruction,
+                    records: observedAddressRecords,
+                }))
+                : routingInstructions;
+            if (missingRoutingInstructions.length > 0) {
+                actions.push(...missingRoutingInstructions.map((instruction) => ({
+                    code: "dns_not_pointing",
+                    hostname: entry.hostname,
+                    message: `Add an ${instruction.type} record on ${instruction.name} with value ${instruction.value}.`,
+                })));
+            }
+            else if (routingInstructions.length === 0) {
+                const targets = entry.providerIps.length > 0 ? entry.providerIps.join(", ") : "Spacefast";
+                actions.push({
+                    code: "dns_not_pointing",
+                    hostname: entry.hostname,
+                    message: `Point ${entry.hostname} at ${targets} using the DNS record type shown by Spacefast.`,
+                });
+            }
+        }
+        if (entry.dns.txtVerified === false && entry.dns.expectedTxtValue) {
+            actions.push({
+                code: "txt_verification_missing",
+                hostname: entry.hostname,
+                message: `Add a TXT record on ${entry.hostname} with value ${entry.dns.expectedTxtValue}.`,
+            });
+        }
+        if (entry.ssl.brokenRecord) {
+            const reason = entry.ssl.brokenRecord.reason ?? entry.ssl.brokenRecord.lastError;
+            actions.push({
+                code: "ssl_blocking_record",
+                hostname: entry.hostname,
+                message: `Fix the DNS record blocking SSL on ${entry.hostname}${reason ? ` (${reason})` : ""}.`,
+            });
+        }
+        else if (entry.ssl.status !== "active" && entry.ssl.canRetry) {
+            actions.push({
+                code: "ssl_retry_available",
+                hostname: entry.hostname,
+                message: `SSL is ${entry.ssl.status} on ${entry.hostname}; retry with \`sf domains check ${entry.hostname}\`.`,
+            });
+        }
+    }
+    return actions;
+}

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

@@ -0,0 +1,51 @@
+{
+    "comment": "Shared egress-policy corpus (spec: one proxy-egress-safety invariant). Exercised by THREE enforcers: apps/control-plane/src/http/egress-guard.ts (control-plane SSRF guard), runtime/engine/shared/egress.php (runtime proxy egress), and crates/stattic-runtime-core (Rust finalizer policy). Every case must produce the same verdict in TypeScript, PHP, and Rust; parity is asserted by apps/control-plane/src/runtime/php-policy-parity.test.ts, src/http/egress-guard.test.ts, and crates/stattic-runtime-core/src/policy.rs::proxy_destinations_match_the_shared_egress_corpus.",
+    "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/grants.d.ts

@@ -0,0 +1,53 @@
+import { type Grant, type GrantCapability, type GrantCheckFailure, type GrantSource } from "../contracts/grants.js";
+export type GrantPrincipal = {
+    teamIds?: readonly string[];
+    personIds?: readonly string[];
+    linkIds?: readonly string[];
+    passwordCredentialIds?: readonly string[];
+    machineIds?: readonly string[];
+    externalIdentities?: readonly {
+        issuer: string;
+        subject: string;
+    }[];
+    verifiedEmail?: boolean;
+    ipAddress?: string;
+    country?: string;
+    userAgent?: string;
+};
+export type GrantEvaluationTarget = {
+    kind: "live";
+} | {
+    kind: "version";
+    versionId: string;
+} | {
+    kind: "branch";
+    branch: string;
+};
+export type GrantEvaluationInput = {
+    grants: readonly Grant[];
+    resource: string;
+    resourceKind?: "route" | "artifact";
+    target: GrantEvaluationTarget;
+    principal?: GrantPrincipal;
+    spaceClaimed: boolean;
+    now?: Date;
+    useCounts?: Readonly<Record<string, number>>;
+    acquiredGrantIds?: readonly string[];
+};
+export type GrantMatch = {
+    grantId: string;
+    capabilities: GrantCapability[];
+    source: GrantSource;
+};
+export type GrantEvaluation = {
+    capabilities: GrantCapability[];
+    matches: GrantMatch[];
+};
+export declare function grantResourcePatternMatches(pattern: string, resource: string, resourceKind?: "route" | "artifact"): boolean;
+export type GrantEvaluationExplanation = {
+    grantId: string;
+    failures: GrantCheckFailure[];
+};
+export declare function explainGrants(input: GrantEvaluationInput): GrantEvaluationExplanation[];
+export declare function evaluateGrants(input: GrantEvaluationInput): GrantEvaluation;
+export declare function grantAllows(input: GrantEvaluationInput, capability: GrantCapability): boolean;

package/dist/utils/grants.js

@@ -0,0 +1,160 @@
+import { normalizeAccessScopePath } from "../contracts/access.js";
+import { GRANT_CAPABILITIES, grantNetworkCidrMatches, normalizeGrantResourcePattern, } from "../contracts/grants.js";
+function audienceMatches(audience, principal) {
+    switch (audience.kind) {
+        case "public":
+            return true;
+        case "team":
+            return principal.teamIds?.includes(audience.teamId) ?? false;
+        case "person":
+            return principal.personIds?.includes(audience.personId) ?? false;
+        case "link":
+            return principal.linkIds?.includes(audience.linkId) ?? false;
+        case "password":
+            return principal.passwordCredentialIds?.includes(audience.credentialId) ?? false;
+        case "machine":
+            return principal.machineIds?.includes(audience.machineId) ?? false;
+        case "external":
+            return (principal.externalIdentities?.some((identity) => identity.issuer === audience.issuer && identity.subject === audience.subject) ?? false);
+    }
+    throw new Error("Unsupported Grant audience.");
+}
+function targetMatches(selector, target) {
+    switch (selector.kind) {
+        case "live":
+            return target.kind === "live";
+        case "version":
+            return target.kind === "version" && target.versionId === selector.versionId;
+        case "branch":
+            return target.kind === "branch" && target.branch === selector.branch;
+        case "all_versions":
+            return target.kind === "version";
+    }
+    throw new Error("Unsupported Grant target.");
+}
+function normalizeGrantEvaluationResource(resource, resourceKind) {
+    if (resourceKind === "route")
+        return normalizeAccessScopePath(resource);
+    if (!resource.startsWith("/")) {
+        throw new TypeError("artifact resource must be an absolute path");
+    }
+    const canonical = normalizeGrantResourcePattern(resource);
+    if (canonical.includes("*")) {
+        throw new TypeError("artifact resource cannot contain wildcards");
+    }
+    return canonical;
+}
+export function grantResourcePatternMatches(pattern, resource, resourceKind = "route") {
+    const canonicalPattern = normalizeGrantResourcePattern(pattern);
+    const canonicalResource = normalizeGrantEvaluationResource(resource, resourceKind);
+    const patternSegments = canonicalPattern === "/" ? [] : canonicalPattern.slice(1).split("/");
+    const resourceSegments = canonicalResource === "/" ? [] : canonicalResource.slice(1).split("/");
+    const matches = (patternIndex, resourceIndex) => {
+        const patternSegment = patternSegments[patternIndex];
+        if (patternSegment === undefined)
+            return resourceIndex === resourceSegments.length;
+        if (patternSegment === "**") {
+            if (patternIndex === patternSegments.length - 1)
+                return true;
+            for (let next = resourceIndex; next <= resourceSegments.length; next++) {
+                if (matches(patternIndex + 1, next))
+                    return true;
+            }
+            return false;
+        }
+        if (resourceIndex >= resourceSegments.length)
+            return false;
+        if (patternSegment !== "*" && patternSegment !== resourceSegments[resourceIndex])
+            return false;
+        return matches(patternIndex + 1, resourceIndex + 1);
+    };
+    return matches(0, 0);
+}
+function grantCheckFailures(grant, input, principal, now) {
+    const failures = [];
+    if (grant.source.kind === "config" && !input.spaceClaimed) {
+        failures.push("space_unclaimed_config");
+    }
+    if (!audienceMatches(grant.audience, principal))
+        failures.push("audience");
+    if (!targetMatches(grant.target, input.target))
+        failures.push("target");
+    const timestamp = now.getTime();
+    if (!Number.isFinite(timestamp)) {
+        failures.push("invalid_time");
+    }
+    else {
+        const notBefore = grant.constraints.notBefore;
+        if (notBefore !== undefined && timestamp < Date.parse(notBefore))
+            failures.push("not_before");
+        const expiresAt = grant.constraints.expiresAt;
+        if (expiresAt !== undefined && timestamp >= Date.parse(expiresAt))
+            failures.push("expired");
+    }
+    const maxUses = grant.constraints.maxUses;
+    if (maxUses !== undefined && !input.acquiredGrantIds?.includes(grant.id)) {
+        const uses = input.useCounts?.[grant.id];
+        if (!Number.isInteger(uses) || (uses ?? 0) < 0 || (uses ?? 0) >= maxUses) {
+            failures.push("max_uses");
+        }
+    }
+    if (grant.constraints.requireVerifiedEmail && principal.verifiedEmail !== true) {
+        failures.push("verified_email");
+    }
+    if (grant.constraints.network &&
+        ((grant.constraints.network.ipCidrs !== undefined &&
+            (!principal.ipAddress ||
+                !grant.constraints.network.ipCidrs.some((cidr) => grantNetworkCidrMatches(cidr, principal.ipAddress ?? "")))) ||
+            (grant.constraints.network.countries !== undefined &&
+                (!principal.country ||
+                    !grant.constraints.network.countries.includes(principal.country.toUpperCase()))) ||
+            (grant.constraints.network.excludedCountries !== undefined &&
+                (!principal.country ||
+                    grant.constraints.network.excludedCountries.includes(principal.country.toUpperCase()))) ||
+            (grant.constraints.network.excludedUserAgentSubstrings !== undefined &&
+                (!principal.userAgent ||
+                    grant.constraints.network.excludedUserAgentSubstrings.some((needle) => principal.userAgent?.toLowerCase().includes(needle.toLowerCase())))))) {
+        failures.push("network");
+    }
+    const included = grant.resources.include.some((pattern) => grantResourcePatternMatches(pattern, input.resource, input.resourceKind));
+    if (!included) {
+        failures.push("resource_not_included");
+    }
+    else if (grant.resources.exclude.some((pattern) => grantResourcePatternMatches(pattern, input.resource, input.resourceKind))) {
+        failures.push("resource_excluded");
+    }
+    return failures;
+}
+export function explainGrants(input) {
+    const principal = input.principal ?? {};
+    const now = input.now ?? new Date();
+    return input.grants.map((grant) => ({
+        grantId: grant.id,
+        failures: grantCheckFailures(grant, input, principal, now),
+    }));
+}
+export function evaluateGrants(input) {
+    const principal = input.principal ?? {};
+    const now = input.now ?? new Date();
+    const matches = [];
+    const capabilities = new Set();
+    for (const grant of input.grants) {
+        if (grantCheckFailures(grant, input, principal, now).length > 0)
+            continue;
+        const matchedCapabilities = [...grant.capabilities];
+        matches.push({
+            grantId: grant.id,
+            capabilities: matchedCapabilities,
+            source: grant.source,
+        });
+        for (const capability of matchedCapabilities)
+            capabilities.add(capability);
+    }
+    return {
+        capabilities: GRANT_CAPABILITIES.filter((capability) => capabilities.has(capability)),
+        matches,
+    };
+}
+export function grantAllows(input, capability) {
+    return evaluateGrants(input).capabilities.includes(capability);
+}

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/local-space-state.js

@@ -131,6 +131,7 @@ export async function findUpward(probe, startDir = process.cwd(), boundary) {
         current = resolvedBoundary;
     }
     for (;;) {
+        // oxlint-disable-next-line no-await-in-loop -- each parent probe depends on the child being absent
         const found = await probe(current);
         if (found)
             return found;

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;