@spacefast/common 0.0.11 → 0.0.13

package/dist/contracts/publishes.js

@@ -1,162 +0,0 @@
-import { z } from "zod";
-import { registeredIdSchema } from "./ids.js";
-export const publishStates = [
-    "awaiting_upload",
-    "uploaded",
-    "parked",
-    "materializing",
-    "succeeded",
-    "failed",
-    "cancelled",
-    "expired",
-];
-export const publishStateSchema = z.enum(publishStates);
-export const publishIdSchema = registeredIdSchema("pub");
-const spaceIdSchema = registeredIdSchema("spc");
-const versionIdSchema = registeredIdSchema("ver");
-export const publishAdmissionSchema = z.object({
-    id: publishIdSchema,
-    idempotencyKey: z.string().min(1),
-    requestFingerprint: z.string().min(1),
-});
-const cancellableActionSchema = z.object({
-    kind: z.literal("cancel_publish"),
-    publishId: publishIdSchema,
-});
-export const publishSchema = z.discriminatedUnion("state", [
-    z
-        .object({
-        id: publishIdSchema,
-        state: z.literal("awaiting_upload"),
-        target: z
-            .object({
-            spaceId: spaceIdSchema,
-            baseVersionId: versionIdSchema.nullable(),
-        })
-            .optional(),
-        counts: z
-            .object({
-            received: z.number().int().nonnegative(),
-            missing: z.number().int().positive(),
-        })
-            .optional(),
-        expiresAt: z.string().datetime().optional(),
-        upload: z
-            .object({
-            missing: z
-                .array(z.object({
-                path: z.string(),
-                sha256: z
-                    .string()
-                    .regex(/^[0-9a-f]{64}$/)
-                    .nullable(),
-                size: z.number().int().nonnegative(),
-                url: z.string().url(),
-                headers: z.record(z.string(), z.string()),
-                expiresAt: z.string().datetime(),
-            }))
-                .min(1),
-        })
-            .optional(),
-    })
-        .refine((publish) => publish.counts === undefined ||
-        publish.upload === undefined ||
-        publish.counts.missing === publish.upload.missing.length, {
-        message: "Upload instructions must match the missing upload count.",
-        path: ["upload", "missing"],
-    })
-        .refine((publish) => publish.counts !== undefined || publish.upload !== undefined, {
-        message: "An awaiting_upload publish must carry counts or upload instructions.",
-        path: ["counts"],
-    }),
-    z.object({ id: publishIdSchema, state: z.literal("uploaded") }),
-    z
-        .object({
-        id: publishIdSchema,
-        state: z.literal("parked"),
-        reason: z.literal("capacity"),
-        queuePosition: z.number().int().positive().optional(),
-        nextCheckAfterSeconds: z.number().int().positive(),
-        actions: z.tuple([cancellableActionSchema]),
-    })
-        .refine((publish) => publish.actions.every((action) => action.publishId === publish.id), {
-        message: "Cancel actions must reference the enclosing publish.",
-        path: ["actions"],
-    }),
-    z.object({
-        id: publishIdSchema,
-        state: z.literal("materializing"),
-        operation: z.object({
-            id: registeredIdSchema("op"),
-            kind: z.literal("publish.finalize"),
-            status: z.enum(["queued", "running"]),
-        }),
-    }),
-    z.object({
-        id: publishIdSchema,
-        state: z.literal("succeeded"),
-        outcome: z.enum(["created", "updated", "unchanged"]),
-        capturedBaseVersionId: versionIdSchema.nullable().optional(),
-        claim: z
-            .object({
-            token: z.string().min(1),
-            url: z.string().url(),
-            expiresAt: z.string().datetime(),
-        })
-            .optional(),
-        result: z.object({
-            space: z.object({ id: spaceIdSchema, liveUrl: z.string().url() }),
-            version: z.object({ id: versionIdSchema, immutableUrl: z.string().url() }),
-            live: z.object({
-                previousVersionId: versionIdSchema.nullable(),
-                versionId: versionIdSchema,
-            }),
-        }),
-    }),
-    z.object({ id: publishIdSchema, state: z.literal("failed"), errorCode: z.string().min(1) }),
-    z.object({ id: publishIdSchema, state: z.literal("cancelled") }),
-    z.object({ id: publishIdSchema, state: z.literal("expired") }),
-]);
-// Cancellation may win during materialization only before the Version exists;
-// afterwards it is not cancelable and the outcome is unchanged.
-const allowedTransitions = {
-    awaiting_upload: ["uploaded", "cancelled", "expired"],
-    uploaded: ["parked", "materializing", "cancelled", "expired"],
-    parked: ["materializing", "cancelled", "expired"],
-    materializing: ["succeeded", "failed", "cancelled", "expired"],
-    succeeded: [],
-    failed: [],
-    cancelled: [],
-    expired: [],
-};
-export function canTransitionPublish(from, to) {
-    return allowedTransitions[from].some((candidate) => candidate === to);
-}
-export function transitionPublish(publish, next) {
-    if (publish.id !== next.id ||
-        publish.idempotencyKey !== next.idempotencyKey ||
-        publish.requestFingerprint !== next.requestFingerprint) {
-        throw new Error("A publish transition cannot change the durable publish identity.");
-    }
-    if (!canTransitionPublish(publish.state, next.state)) {
-        throw new Error(`Invalid publish transition: ${publish.state} -> ${next.state}`);
-    }
-    // Project through the wire schema so fields from the previous variant (e.g. a
-    // parked `reason` spread into a materializing publish) never leak downstream.
-    return {
-        ...publishSchema.parse(next),
-        idempotencyKey: next.idempotencyKey,
-        requestFingerprint: next.requestFingerprint,
-    };
-}
-export function convergePublishAdmission(existing, attempted) {
-    if (existing === undefined)
-        return { outcome: "created", publish: attempted };
-    if (existing.idempotencyKey !== attempted.idempotencyKey) {
-        throw new Error("Admission convergence requires one idempotency key.");
-    }
-    if (existing.requestFingerprint !== attempted.requestFingerprint) {
-        return { outcome: "conflict", publish: existing };
-    }
-    return { outcome: "replayed", publish: existing };
-}

package/dist/utils/access-match.d.ts

@@ -1,39 +0,0 @@
-export declare function filterGrantsByNamespace(grants: string[], namespaces: string[]): string[];
-export declare function grantGlobMatches(pattern: string, grant: string): boolean;
-export declare function grantsIntersect(grants: string[], requiredGrants: string[]): boolean;
-export declare function grantsSatisfyRule(input: {
-    grants: string[];
-    requiredGrants: string[];
-    grantNamespaces: string[];
-}): boolean;
-export declare function canonicalizeHost(host: string): string;
-export declare function hostGlobMatches(pattern: string, host: string): boolean;
-export declare function hostTemplateMatches(template: string, host: string): boolean;
-export declare function pathGlobMatches(pattern: string, path: string): boolean;
-export declare function agentMatches(needle: string, agent: string): boolean;
-export declare function ipInCidr(ip: string, cidr: string): boolean;
-export declare function ipInAnyCidr(ip: string, cidrs: string[]): boolean;
-export type RuleMatchContext = {
-    host: string;
-    path: string;
-    channel?: string | undefined;
-    ip?: string | undefined;
-    agent?: string | undefined;
-    country?: string | undefined;
-    headers?: Record<string, string> | undefined;
-};
-export type RuleMatchInput = {
-    host?: string | undefined;
-    hostPattern?: string | undefined;
-    hostTemplate?: string | undefined;
-    pathPattern?: string | undefined;
-    channel?: string | undefined;
-    ipCidrs?: string[] | undefined;
-    agent?: string | undefined;
-    country?: string | undefined;
-    header?: {
-        name: string;
-        value: string;
-    } | undefined;
-};
-export declare function ruleMatchApplies(match: RuleMatchInput, context: RuleMatchContext): boolean;

package/dist/utils/access-match.js

@@ -1,296 +0,0 @@
-// 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/sf-config-v1.d.ts

@@ -1,2 +0,0 @@
-import { type CompileSfConfigV1Options, type SfConfigV1CompileResult } from "../contracts/sf-config-v1.js";
-export declare function compileSfConfigV1(source: string, options?: CompileSfConfigV1Options): SfConfigV1CompileResult;