@spacefast/common 0.0.5 → 0.0.6

package/dist/utils/access-match.js

@@ -0,0 +1,296 @@
+// The ONE TS implementation of the runtime's grant-satisfaction kernel
+// (internal-docs/access-plan.html X-9): glob-aware `grants ∩ requiredGrants`
+// intersection plus signing-key grant-namespace filtering. The PHP evaluator
+// (runtime/engine/runtime/access-rules.php `_stattic_unified_grants_intersect`
+// / `_stattic_unified_filter_grants_by_namespace`) is the enforcer of record;
+// this matcher exists so the cloud's authorize pre-flight (and, later,
+// `access simulate`) never mints a token the runtime would reject.
+//
+// Parity is pinned by a shared JSON corpus (`access-match.fixtures.json`),
+// asserted against this module in packages/common and against the PHP in the
+// control plane's php-policy-parity test — the one sanctioned
+// generated↔source drift-guard pattern. Do not change semantics here without
+// extending the corpus.
+// Drops every grant not prefixed by one of the signing key's namespaces. This
+// bounds a leaked external key's blast radius to exactly the grant namespaces
+// the owner pointed it at (and bounds the runtime-local pw: key to `pw:`).
+export function filterGrantsByNamespace(grants, namespaces) {
+    const kept = [];
+    for (const grant of grants) {
+        if (typeof grant !== "string" || grant === "") {
+            continue;
+        }
+        for (const namespace of namespaces) {
+            if (typeof namespace === "string" && namespace !== "" && grant.startsWith(namespace)) {
+                kept.push(grant);
+                break;
+            }
+        }
+    }
+    return kept;
+}
+// `*` in a requiredGrant matches any run of characters (grants have no path
+// structure to anchor on, unlike paths). Exact match when no `*` present.
+export function grantGlobMatches(pattern, grant) {
+    if (!pattern.includes("*")) {
+        return pattern === grant;
+    }
+    const regex = pattern
+        .split("*")
+        .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+        .join(".*");
+    return new RegExp(`^${regex}$`).test(grant);
+}
+// Glob-aware intersection: a visitor passes when ANY verified concrete grant
+// matches ANY requiredGrant. requiredGrants may carry `*` wildcards (e.g.
+// "email:*@acme.com"); verified grants are concrete.
+export function grantsIntersect(grants, requiredGrants) {
+    for (const required of requiredGrants) {
+        if (typeof required !== "string" || required === "") {
+            continue;
+        }
+        for (const grant of grants) {
+            if (typeof grant !== "string" || grant === "") {
+                continue;
+            }
+            if (grantGlobMatches(required, grant)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+// The composed satisfaction test the authorize pre-flight runs: namespace-drop
+// the visitor's grants by the signing key, then intersect with the rule's
+// requiredGrants — exactly what the runtime does after verifying a signature.
+export function grantsSatisfyRule(input) {
+    return grantsIntersect(filterGrantsByNamespace(input.grants, input.grantNamespaces), input.requiredGrants);
+}
+// ---------------------------------------------------------------------------
+// Rule-match evaluation (the `match` half of the kernel)
+// ---------------------------------------------------------------------------
+//
+// TS mirror of the PHP `_stattic_unified_rule_matches` /
+// `_stattic_unified_path_glob_matches` / `_stattic_unified_ip_in_cidr` family
+// (runtime/engine/runtime/access-rules.php). Powers `access simulate` and the
+// authorize pre-flight's path scoping. Parity is pinned by the same shared
+// corpus (`access-match.fixtures.json`, sections `pathGlob` + `cidr`) asserted
+// against the PHP in php-policy-parity.test.ts.
+// Mirrors `_spacefast_canonicalize_host`.
+export function canonicalizeHost(host) {
+    return host.trim().toLowerCase().replace(/\.+$/, "");
+}
+export function hostGlobMatches(pattern, host) {
+    const regex = pattern
+        .split("*")
+        .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+        .join(".*");
+    return new RegExp(`^${regex}$`, "i").test(canonicalizeHost(host));
+}
+export function hostTemplateMatches(template, host) {
+    let regex = "";
+    let index = 0;
+    while (index < template.length) {
+        const char = template[index];
+        if (char === "*") {
+            regex += ".*";
+            index += 1;
+            continue;
+        }
+        if (char === ":") {
+            const name = template.slice(index + 1).match(/^[A-Za-z][A-Za-z0-9_]*/)?.[0] ?? "";
+            if (!name) {
+                return false;
+            }
+            regex += "[^.]+";
+            index += name.length + 1;
+            continue;
+        }
+        regex += char.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        index += 1;
+    }
+    return new RegExp(`^${regex}$`, "i").test(canonicalizeHost(host));
+}
+// Glob path matcher: "/docs/**" (any depth), "/docs/*" (one segment), exact
+// otherwise. Empty pattern matches everything.
+export function pathGlobMatches(pattern, path) {
+    if (pattern === "") {
+        return true;
+    }
+    if (!pattern.includes("*")) {
+        return pattern === path;
+    }
+    let regex = "";
+    let i = 0;
+    while (i < pattern.length) {
+        const char = pattern[i];
+        if (char === "*") {
+            if (pattern[i + 1] === "*") {
+                regex += ".*";
+                i += 2;
+                continue;
+            }
+            regex += "[^/]*";
+            i += 1;
+            continue;
+        }
+        regex += char.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        i += 1;
+    }
+    return new RegExp(`^${regex}$`).test(path);
+}
+// Case-insensitive substring match on the user agent; empty needle matches.
+export function agentMatches(needle, agent) {
+    if (needle === "") {
+        return true;
+    }
+    return agent.toLowerCase().includes(needle.toLowerCase());
+}
+// inet_pton equivalent: dotted-quad IPv4 or RFC 4291 IPv6 (including "::"
+// compression and an embedded IPv4 tail) → bytes, or null when unparseable.
+function ipToBytes(ip) {
+    if (/^\d{1,3}(\.\d{1,3}){3}$/.test(ip)) {
+        const parts = ip.split(".").map(Number);
+        if (parts.some((part) => part > 255)) {
+            return null;
+        }
+        return Uint8Array.from(parts);
+    }
+    if (!ip.includes(":")) {
+        return null;
+    }
+    let head = ip;
+    let v4Tail = null;
+    const lastColon = ip.lastIndexOf(":");
+    const tail = ip.slice(lastColon + 1);
+    if (tail.includes(".")) {
+        const tailBytes = ipToBytes(tail);
+        if (!tailBytes || tailBytes.length !== 4) {
+            return null;
+        }
+        v4Tail = [...tailBytes];
+        head = ip.slice(0, lastColon + 1) + "0:0"; // placeholder groups, replaced below
+    }
+    const doubleColonSplits = head.split("::");
+    if (doubleColonSplits.length > 2) {
+        return null;
+    }
+    const parseGroups = (raw) => {
+        if (raw === "") {
+            return [];
+        }
+        const groups = [];
+        for (const part of raw.split(":")) {
+            if (!/^[0-9a-fA-F]{1,4}$/.test(part)) {
+                return null;
+            }
+            groups.push(Number.parseInt(part, 16));
+        }
+        return groups;
+    };
+    let groups;
+    if (doubleColonSplits.length === 2) {
+        const left = parseGroups(doubleColonSplits[0] ?? "");
+        const right = parseGroups(doubleColonSplits[1] ?? "");
+        if (left === null || right === null || left.length + right.length > 8) {
+            return null;
+        }
+        groups = [...left, ...Array(8 - left.length - right.length).fill(0), ...right];
+    }
+    else {
+        groups = parseGroups(head);
+        if (groups === null || groups.length !== 8) {
+            return null;
+        }
+    }
+    const bytes = new Uint8Array(16);
+    groups.forEach((group, index) => {
+        bytes[index * 2] = group >> 8;
+        bytes[index * 2 + 1] = group & 0xff;
+    });
+    if (v4Tail) {
+        bytes[12] = v4Tail[0];
+        bytes[13] = v4Tail[1];
+        bytes[14] = v4Tail[2];
+        bytes[15] = v4Tail[3];
+    }
+    return bytes;
+}
+// Mirrors `_stattic_unified_ip_in_cidr`: a bare address (no "/") is an exact
+// string compare; mixed families never match; malformed input never matches.
+export function ipInCidr(ip, cidr) {
+    if (cidr === "") {
+        return false;
+    }
+    if (!cidr.includes("/")) {
+        return ip === cidr;
+    }
+    const [subnet = "", bitsRaw = ""] = cidr.split("/", 2);
+    const ipBytes = ipToBytes(ip);
+    const subnetBytes = ipToBytes(subnet);
+    if (!ipBytes || !subnetBytes || ipBytes.length !== subnetBytes.length) {
+        return false;
+    }
+    if (!/^\d+$/.test(bitsRaw)) {
+        return false;
+    }
+    const bits = Number.parseInt(bitsRaw, 10);
+    const maxBits = ipBytes.length * 8;
+    if (bits < 0 || bits > maxBits) {
+        return false;
+    }
+    const fullBytes = Math.floor(bits / 8);
+    for (let index = 0; index < fullBytes; index += 1) {
+        if (ipBytes[index] !== subnetBytes[index]) {
+            return false;
+        }
+    }
+    const remainder = bits % 8;
+    if (remainder === 0) {
+        return true;
+    }
+    const mask = (0xff << (8 - remainder)) & 0xff;
+    return (ipBytes[fullBytes] & mask) === (subnetBytes[fullBytes] & mask);
+}
+export function ipInAnyCidr(ip, cidrs) {
+    if (ip === "") {
+        return false;
+    }
+    return cidrs.some((cidr) => typeof cidr === "string" && ipInCidr(ip, cidr));
+}
+// AND-combined match — mirrors `_stattic_unified_rule_matches` exactly. An
+// empty match matches everything in scope.
+export function ruleMatchApplies(match, context) {
+    if (match.host !== undefined && canonicalizeHost(match.host) !== canonicalizeHost(context.host)) {
+        return false;
+    }
+    if (match.hostPattern !== undefined && !hostGlobMatches(match.hostPattern, context.host)) {
+        return false;
+    }
+    if (match.hostTemplate !== undefined && !hostTemplateMatches(match.hostTemplate, context.host)) {
+        return false;
+    }
+    if (match.pathPattern !== undefined && !pathGlobMatches(match.pathPattern, context.path)) {
+        return false;
+    }
+    if (match.channel !== undefined && match.channel !== (context.channel ?? "")) {
+        return false;
+    }
+    if (match.ipCidrs !== undefined && !ipInAnyCidr(context.ip ?? "", match.ipCidrs)) {
+        return false;
+    }
+    if (match.agent !== undefined && !agentMatches(match.agent, context.agent ?? "")) {
+        return false;
+    }
+    if (match.country !== undefined && match.country.toUpperCase() !== (context.country ?? "")) {
+        return false;
+    }
+    if (match.header !== undefined) {
+        const name = match.header.name.toLowerCase();
+        const actual = Object.entries(context.headers ?? {}).find(([key]) => key.toLowerCase() === name)?.[1];
+        if (match.header.name === "" || (actual ?? "") !== match.header.value) {
+            return false;
+        }
+    }
+    return true;
+}

package/dist/utils/auth-redirect.d.ts

@@ -1 +1,3 @@
-export declare function sanitizeDashboardReturnTo(returnTo: string | null | undefined): string | undefined;
+export declare function sanitizeDashboardReturnTo(returnTo: string | null | undefined, options?: {
+    apiOrigin?: string | null;
+}): string | undefined;

package/dist/utils/auth-redirect.js

@@ -17,9 +17,29 @@ function hasUnsafeReturnToChars(value) {
     }
     return false;
 }
-export function sanitizeDashboardReturnTo(returnTo) {
+// The ONE absolute-URL exception to the same-origin returnTo policy
+// (access-plan X-41): the api-origin GET /v1/access/authorize URL exactly —
+// the sign-in leg of the visitor redirect chain. Everything else absolute is
+// an open-redirect surface and stays rejected.
+const API_AUTHORIZE_PATH = "/v1/access/authorize";
+export function sanitizeDashboardReturnTo(returnTo, options) {
     const normalized = returnTo?.trim();
     const decoded = normalized ? decodedReturnTo(normalized) : null;
+    if (normalized && decoded && options?.apiOrigin) {
+        try {
+            const candidate = new URL(normalized);
+            const apiOrigin = new URL(options.apiOrigin).origin;
+            if (candidate.origin === apiOrigin &&
+                candidate.pathname === API_AUTHORIZE_PATH &&
+                !hasUnsafeReturnToChars(normalized) &&
+                !hasUnsafeReturnToChars(decoded)) {
+                return candidate.toString();
+            }
+        }
+        catch {
+            // Not an absolute URL — fall through to the same-origin path rules.
+        }
+    }
     if (!normalized ||
         !decoded ||
         !normalized.startsWith("/") ||

package/dist/utils/build-settings.d.ts

@@ -46,4 +46,10 @@ export type PlatformConfig = {
 export declare function stringField(value: Record<string, unknown> | null, key: string): string | null;
 export declare function numberField(value: Record<string, unknown> | null, key: string): number | null;
 export declare function detectPlatformConfigs(input: Omit<BuildSettingsInput, "fileNames" | "packageJson">): PlatformConfig[];
+export type PlatformRoutingConversion = {
+    redirectLines: string[];
+    headerBlocks: string[];
+    notes: string[];
+};
+export declare function convertPlatformRouting(configs: PlatformConfig[]): PlatformRoutingConversion;
 export declare function detectBuildSettings(input: BuildSettingsInput): DetectedBuildSettings;