@spacefast/common 0.0.24 → 0.2.1

package/dist/utils/secure-local-file.js

@@ -236,10 +236,9 @@ async function canonicalPortableWriteRoot(rootInput) {
 async function openPortableChildDirectory(identities, visibleParent, component, create) {
     assertSafeComponent(component);
     const childPath = path.join(visibleParent, component);
-    // A missing directory is the normal "file not found" result for secure
-    // reads. Probe before identity capture so callers can handle ENOENT. If the
-    // directory disappears after this probe, visibleDirectoryIdentity still
-    // fails closed because an observed ancestor binding changed mid-read.
+    // A missing directory is the normal "file not found" for secure reads, so
+    // probe before identity capture. A later disappearance still fails closed in
+    // visibleDirectoryIdentity.
     if (!create) {
         await lstat(childPath);
     }
@@ -273,7 +272,6 @@ function lockName(leaf) {
     const digest = createHash("sha256").update(identity).digest("hex").slice(0, 24);
     return `.spacefast-${digest}.lock`;
 }
-const LEGACY_LEAF_LOCK_STALE_MS = 2 * 60_000;
 function serializeLeafLockOwner(owner) {
     const { phase, ...identity } = owner;
     return `${phase === "active" ? "A" : "R"}${JSON.stringify(identity)}\n`;
@@ -293,6 +291,7 @@ function parseLeafLockOwner(raw) {
             (value.temporaryName === undefined ||
                 (typeof value.temporaryName === "string" &&
                     /^\.spacefast-[0-9a-f-]{36}\.tmp$/.test(value.temporaryName)))) {
+            // SAFETY: The preceding checks establish every required LeafLockOwner field and the optional temporaryName field.
             return { ...value, phase };
         }
     }
@@ -360,14 +359,8 @@ function processIsAlive(pid) {
     }
 }
 async function leafLockRecordIsStale(record) {
-    // The original lock format was an empty exclusive file. It carries no owner
-    // identity, so a short age fence is the only safe compatibility signal: a
-    // fresh legacy writer stays exclusive, while crash wreckage can recover.
-    if (record?.kind === "legacy") {
-        return Date.now() - record.modifiedAtMs > LEGACY_LEAF_LOCK_STALE_MS;
-    }
-    // A malformed non-empty record is not proof that no writer owns it. New lock
-    // records are atomically published, so corruption still needs explicit recovery.
+    // A malformed record is not proof that no writer owns it. New lock records are
+    // atomically published, so corruption still needs explicit recovery.
     if (record?.kind !== "owned")
         return false;
     const { owner } = record;
@@ -399,13 +392,8 @@ async function readLeafLockRecord(filePath) {
             visibleMetadata.ino !== metadata.ino) {
             return { kind: "invalid" };
         }
-        const raw = await file.readFile("utf8");
-        const owner = parseLeafLockOwner(raw);
-        if (owner)
-            return { kind: "owned", owner };
-        return raw.length === 0
-            ? { kind: "legacy", modifiedAtMs: metadata.mtimeMs }
-            : { kind: "invalid" };
+        const owner = parseLeafLockOwner(await file.readFile("utf8"));
+        return owner ? { kind: "owned", owner } : { kind: "invalid" };
     }
     finally {
         await file.close();
@@ -476,8 +464,7 @@ async function unlinkOwnedLeafLockArtifact(lockPath, artifactPath, nonce) {
         return;
     }
     // The pathname changed after its owner was inspected. Restore the exact inode
-    // when the name is still free; if another lock is already visible, keep this
-    // one displaced so contenders detect it instead of deleting a fresh owner.
+    // when the name is free; otherwise keep it displaced so contenders detect it.
     let restored = false;
     try {
         await link(retiredPath, artifactPath);
@@ -555,14 +542,12 @@ async function acquireLeafLock(lockPath, temporaryPath) {
                 if (released)
                     return;
                 released = true;
-                // Move the canonical name into unique cleanup custody while its inode
-                // is still active. Once that atomic rename happens a new owner may
-                // publish, but cleanup only ever unlinks the retired name it inspected.
+                // Move the canonical name into unique custody while its inode is still
+                // active; cleanup only ever unlinks the retired name it inspected.
                 await unlinkOwnedLeafLockArtifact(lockPath, lockPath, owner.nonce).catch(() => undefined);
                 try {
-                    // A delayed stale reclaimer may already hold this inode at a displaced
-                    // name. Mark it complete through the handle so that artifact can be
-                    // reclaimed even though this process remains alive.
+                    // A delayed stale reclaimer may hold this inode at a displaced name.
+                    // Mark it complete through the handle so it can still be reclaimed.
                     const releasedWrite = await acquiredHandle.write(Buffer.from("R"), 0, 1, 0);
                     if (releasedWrite.bytesWritten === 1)
                         await acquiredHandle.sync();
@@ -609,16 +594,15 @@ async function acquireLeafLock(lockPath, temporaryPath) {
         }
         const displaced = await readLeafLockRecord(displacedPath);
         if (!(await leafLockRecordIsStale(displaced))) {
-            // A fresh owner won between our stale read and rename. Put its exact inode
-            // back when possible; every contender also scans displaced names before
-            // entering, so a live writer is never silently unlocked.
+            // A fresh owner won between our stale read and rename. Put its exact
+            // inode back; contenders scan displaced names before entering, so a live
+            // writer is never silently unlocked.
             try {
                 await link(displacedPath, lockPath);
             }
             catch (error) {
                 if (isMissing(error)) {
-                    // Its owner completed cleanup while we inspected the displaced inode.
-                    // Nothing remains to restore; compete again for the now-current name.
+                    // Its owner finished cleanup; compete again for the current name.
                     await delay(LEAF_LOCK_RETRY_DELAY_MS);
                     continue;
                 }
@@ -868,10 +852,9 @@ async function commitPortableStagedFile(input) {
     }
 }
 async function secureWriteFilePortable(options) {
-    // The caller explicitly trusts the root. Canonicalize that boundary once so
-    // supported system aliases such as macOS `/var -> /private/var` do not look
-    // like attacker-controlled children; every path below it is still walked
-    // component-by-component without following symlinks.
+    // Canonicalize the trusted root once so system aliases like macOS
+    // `/var -> /private/var` don't look like attacker-controlled children.
+    // Everything below it is still walked without following symlinks.
     const root = await canonicalPortableWriteRoot(options.root);
     const relativePath = validateRelativePath(options.relativePath, "write");
     const components = relativePath.split(path.sep);
@@ -934,9 +917,9 @@ async function secureWriteFilePortable(options) {
 }
 /**
  * Writes beneath an explicitly trusted root without following output-tree
- * symlinks. Linux uses descriptor-relative operations; other supported
- * platforms use exclusive staging plus before-and-after ancestor identity
- * validation and fail closed if any binding changes.
+ * symlinks. Linux uses descriptor-relative operations; other platforms use
+ * exclusive staging plus before-and-after ancestor identity validation, and
+ * fail closed if any binding changes.
  */
 export async function secureWriteFile(options) {
     if ((options.data === undefined) === (options.write === undefined)) {

package/dist/utils/space-config.d.ts

@@ -3,7 +3,7 @@ import { type SpaceConfig, type SpaceConfigFile } from "../contracts/space-confi
 export type SpaceConfigBlockingIssueCode = "config_file_too_large" | "config_templates_over_limit" | "config_meta_too_long" | "config_name_too_long" | "config_functions_key_removed" | "config_invalid" | "config_runtime_invalid_kind" | "config_runtime_entry_missing" | "inject_snippet_too_large" | "inject_invalid";
 export type SpaceConfigIssue = {
     severity: "info" | "warning" | "error";
-    code: SpaceConfigBlockingIssueCode | "single_html_index" | "files_mode_inferred";
+    code: SpaceConfigBlockingIssueCode | "single_html_index" | "files_mode_inferred" | "listing_shadows_fallback";
     message: string;
     /** JSON-path-lite pointer into the config shape (e.g. `meta.title`). */
     path?: string;
@@ -16,18 +16,15 @@ type SpaceConfigBlockingIssue = SpaceConfigIssue & {
     code: SpaceConfigBlockingIssueCode;
 };
 /**
- * Keys a committed `sf.jsonc` owns outright: they are facts about the content
- * of a version (who may read it, what it is called, what runs it), so they roll
- * forward and back with the version instead of living in the space's mutable
- * overlay. API intake refuses them rather than storing or dropping them.
+ * Keys a committed `sf.jsonc` owns outright. They are facts about a version's
+ * content, so they roll forward and back with it instead of living in the
+ * space's mutable overlay. API intake refuses them.
  */
-export declare const SPACE_CONFIG_FILE_ONLY_KEYS: readonly ["access", "name", "runtime"];
+export declare const SPACE_CONFIG_FILE_ONLY_KEYS: readonly ["access", "name", "runtime", "system"];
 /**
- * Validates a space `config` overlay at API intake (PATCH /spaces, publish
- * `config`): file-only keys, the 16 KB compiled-overlay cap, plus the shared
- * shape caps. Returns the first blocking issue, or null when the overlay is
- * acceptable. Takes the raw request value, because the overlay schema strips
- * file-only keys and this is what has to see them.
+ * Validates a space `config` overlay at API intake, returning the first
+ * blocking issue or null. Takes the RAW request value: the overlay schema
+ * strips file-only keys, and this is what has to see them.
  */
 export declare function spaceConfigOverlayIssue(config: unknown): SpaceConfigBlockingIssue | null;
 export declare function stripJsonComments(raw: string): string;
@@ -37,16 +34,16 @@ export type ResolvedServingConfig = {
         path: string;
         status: 200 | 404;
     } | null;
-    /** W7.1 clean URLs: serve flat `<name>.html` at its extensionless URL. */
+    /** Serve flat `<name>.html` at its extensionless URL. */
     cleanUrls: boolean;
     listing: boolean;
     viewer: boolean;
     meta: NonNullable<SpaceConfig["meta"]> | null;
-    /** Theme tokens for every Spacefast-authored page; null when unset. */
+    /** Theme tokens for every Spacefast-authored page. */
     pageTheme: NonNullable<SpaceConfig["theme"]> | null;
-    /** Hidden experimental build-pipeline flag; false keeps today's behavior. */
+    /** Hidden experimental build-pipeline flag. */
     experimentalGutenberg: boolean;
-    /** Resolved inject snippets; only honored when experimentalGutenberg is true. */
+    /** Only honored when experimentalGutenberg is true. */
     inject: NonNullable<SpaceConfig["inject"]> | null;
 };
 export type SpaceSettingsPatch = {

package/dist/utils/space-config.js

@@ -42,9 +42,7 @@ function capIssues(candidate) {
             details: { count: templates.length, limit: SPACE_CONFIG_CAPS.templates },
         });
     }
-    // inject snippets (hidden feature, honored only with experimental_gutenberg):
-    // shape and byte caps fail with the stable codes here, before zod, so intake
-    // reports inject_invalid / inject_snippet_too_large instead of shape errors.
+    // inject is a hidden feature, honored only with experimental_gutenberg.
     const inject = candidate.inject;
     if (inject !== undefined) {
         if (typeof inject !== "object" || inject === null || Array.isArray(inject)) {
@@ -57,6 +55,7 @@ function capIssues(candidate) {
         }
         else {
             for (const key of ["head", "bodyStart", "bodyEnd", "noscript"]) {
+                // SAFETY: The enclosing branch proves inject is a non-null, non-array object.
                 const snippets = inject[key];
                 if (snippets === undefined) {
                     continue;
@@ -125,18 +124,15 @@ function capIssues(candidate) {
     return issues;
 }
 /**
- * Keys a committed `sf.jsonc` owns outright: they are facts about the content
- * of a version (who may read it, what it is called, what runs it), so they roll
- * forward and back with the version instead of living in the space's mutable
- * overlay. API intake refuses them rather than storing or dropping them.
+ * Keys a committed `sf.jsonc` owns outright. They are facts about a version's
+ * content, so they roll forward and back with it instead of living in the
+ * space's mutable overlay. API intake refuses them.
  */
-export const SPACE_CONFIG_FILE_ONLY_KEYS = ["access", "name", "runtime"];
+export const SPACE_CONFIG_FILE_ONLY_KEYS = ["access", "name", "runtime", "system"];
 /**
- * Validates a space `config` overlay at API intake (PATCH /spaces, publish
- * `config`): file-only keys, the 16 KB compiled-overlay cap, plus the shared
- * shape caps. Returns the first blocking issue, or null when the overlay is
- * acceptable. Takes the raw request value, because the overlay schema strips
- * file-only keys and this is what has to see them.
+ * Validates a space `config` overlay at API intake, returning the first
+ * blocking issue or null. Takes the RAW request value: the overlay schema
+ * strips file-only keys, and this is what has to see them.
  */
 export function spaceConfigOverlayIssue(config) {
     if (config === null || config === undefined || typeof config !== "object") {
@@ -165,15 +161,15 @@ export function spaceConfigOverlayIssue(config) {
     }
     return capIssues(config)[0] ?? null;
 }
-// Strips JSONC comments and trailing commas (string-aware single pass). The
-// config file itself is parsed by the crate; this stays for the OTHER JSONC
-// files the CLI reads (agent configs, exported platform env).
+// The config file itself is parsed by the crate; this stays for the OTHER
+// JSONC files the CLI reads (agent configs, exported platform env).
 export function stripJsonComments(raw) {
     let output = "";
     let inString = false;
     let inLineComment = false;
     let inBlockComment = false;
     for (let i = 0; i < raw.length; i += 1) {
+        // SAFETY: The loop condition proves i addresses a character in raw.
         const char = raw[i];
         const next = raw[i + 1];
         if (inLineComment) {
@@ -220,6 +216,7 @@ export function stripJsonComments(raw) {
             // Trailing comma: skip when the next non-whitespace/non-comment char closes.
             let j = i + 1;
             while (j < raw.length) {
+                // SAFETY: The loop condition proves j addresses a character in raw.
                 const ahead = raw[j];
                 if (/\s/.test(ahead)) {
                     j += 1;

package/dist/utils/static-runtime-policy.d.ts

@@ -1,18 +1,21 @@
+import { INTERNAL_REDIRECT_RESPONSE_HEADERS, PLATFORM_MANAGED_RESPONSE_HEADER_PREFIXES, PLATFORM_MANAGED_RESPONSE_HEADERS } from "./static-runtime-policy.generated.js";
+export { INTERNAL_REDIRECT_RESPONSE_HEADERS, PLATFORM_MANAGED_RESPONSE_HEADER_PREFIXES, PLATFORM_MANAGED_RESPONSE_HEADERS, };
 export declare const PHP_LIKE_EXTENSIONS: string[];
-export declare const INTERNAL_REDIRECT_RESPONSE_HEADERS: string[];
-export declare const PLATFORM_MANAGED_RESPONSE_HEADERS: string[];
-/** Reserved response-header namespaces owned by the platform's own serving signature. */
-export declare const PLATFORM_MANAGED_RESPONSE_HEADER_PREFIXES: string[];
 /** True when user rules may neither set nor remove this response header. */
 export declare function isPlatformManagedResponseHeader(name: string): boolean;
-export declare const NON_IMMUTABLE_EXTENSIONS: string[];
-export declare const GUARANTEED_IMMUTABLE_PREFIXES: string[];
+/**
+ * The token grammar a `_headers` rule accepts for a header NAME. Anything that
+ * GENERATES `_headers` rules must gate on it too, so a generated rule can
+ * never fail the author's publish.
+ */
+export declare const HEADER_RULE_NAME_PATTERN: RegExp;
+/** `content-type` → `Content-Type`: the casing compiled rules and generated `_headers` carry. */
+export declare function canonicalHeaderName(input: string): string;
 /** Lowercased extension without the leading dot, posix semantics. Dotfiles have no extension. */
 export declare function pathExtension(filePath: string): string;
 /** Basename without its extension (the "stem"), posix semantics. */
 export declare function pathStem(filePath: string): string;
 export declare function isPhpLikeStaticPath(filePath: string): boolean;
-export declare function isImmutableAssetPath(filePath: string): boolean;
 /** Forced inert serving policy for a committed static file. PHP-like files are never executable. */
 export declare function runtimeFileSafety(filePath: string): {
     executable: false;

package/dist/utils/static-runtime-policy.fixtures.json

@@ -1,44 +1,33 @@
 {
     "phpLike": [
-        { "path": "index.php", "expected": true },
-        { "path": "nested/app.phtml", "expected": true },
-        { "path": "lib.phar", "expected": true },
-        { "path": "legacy.php5", "expected": true },
-        { "path": "index.html", "expected": false },
-        { "path": "assets/main.js", "expected": false },
-        { "path": ".env", "expected": false }
-    ],
-    "immutable": [
-        { "path": "_next/static/chunks/main-app-4A_iFExJ.js", "expected": true },
-        { "path": "_next/static/chunks/framework-2c1d4f8a.js", "expected": true },
-        { "path": "_next/static/chunks/pages/index-a1b2c3d4e5f6.js", "expected": true },
-        { "path": "_next/static/chunks/oton0Guf.js", "expected": true },
-        { "path": "_next/static/css/app.plainname.css", "expected": true },
-        { "path": "/_next/static/chunks/oton0Guf.js", "expected": true },
-        { "path": "_app/immutable/entry/start.DYyuCeEr.js", "expected": true },
-        { "path": "_nuxt/index.oton0Guf.js", "expected": true },
-        { "path": "_astro/about.DYyuCeEr.css", "expected": true },
-        { "path": "_next/static/index.html", "expected": false },
-        { "path": "_next/static/sitemap.xml", "expected": false },
-        { "path": "_app/immutable/manifest.txt", "expected": false },
-        { "path": "_nextish/chunks/oton0Guf.js", "expected": false },
-        { "path": "nested/_next/static/chunks/oton0Guf.js", "expected": false },
-        { "path": "assets/index-BzeDGMM3.js", "expected": false },
-        { "path": "assets/auth-client-P1Tx-Cyu.js", "expected": false },
-        { "path": "assets/index-DYyuCeEr.js", "expected": false },
-        { "path": "assets/index-9f8e7d6c.js", "expected": false },
-        { "path": "assets/D3GeoMap.js", "expected": false },
-        { "path": "assets/index.js", "expected": false },
-        { "path": "assets/client-widget.js", "expected": false },
-        { "path": "app.1a2b3c4d.css", "expected": false },
-        { "path": "vendor.3f9a2b7e.js", "expected": false },
-        { "path": "static/js/main.d41d8cd98f00b204e9800998.js", "expected": false },
-        { "path": "index.html", "expected": false },
-        { "path": "robots.txt", "expected": false },
-        { "path": "config.xml", "expected": false },
-        { "path": "page.php", "expected": false },
-        { "path": "MyComponent.js", "expected": false },
-        { "path": "image01.png", "expected": false }
+        {
+            "path": "index.php",
+            "expected": true
+        },
+        {
+            "path": "nested/app.phtml",
+            "expected": true
+        },
+        {
+            "path": "lib.phar",
+            "expected": true
+        },
+        {
+            "path": "legacy.php5",
+            "expected": true
+        },
+        {
+            "path": "index.html",
+            "expected": false
+        },
+        {
+            "path": "assets/main.js",
+            "expected": false
+        },
+        {
+            "path": ".env",
+            "expected": false
+        }
     ],
     "safeContentType": [
         {
@@ -46,12 +35,20 @@
             "mime": "application/x-httpd-php",
             "expected": "text/plain; charset=utf-8"
         },
-        { "path": "lib.phar", "mime": "application/zip", "expected": "application/octet-stream" },
+        {
+            "path": "lib.phar",
+            "mime": "application/zip",
+            "expected": "application/octet-stream"
+        },
         {
             "path": "assets/main.js",
             "mime": "text/javascript; charset=utf-8",
             "expected": "text/javascript; charset=utf-8"
         },
-        { "path": "logo.svg", "mime": "image/svg+xml", "expected": "image/svg+xml" }
+        {
+            "path": "logo.svg",
+            "mime": "image/svg+xml",
+            "expected": "image/svg+xml"
+        }
     ]
 }

package/dist/utils/static-runtime-policy.generated.d.ts

@@ -0,0 +1,16 @@
+/** Reserved response-header namespaces carrying the platform's own serving signature. */
+export declare const PLATFORM_MANAGED_RESPONSE_HEADER_PREFIXES: readonly string[];
+/**
+ * The internal-redirect/sendfile family, every vendor spelling: headers that make the web
+ * server produce a different response instead of describing this one. Factored out of the
+ * managed set below so the proxy relay can drop exactly these from an untrusted upstream
+ * while still relaying ordinary response headers the managed set also lists.
+ */
+export declare const INTERNAL_REDIRECT_RESPONSE_HEADERS: readonly string[];
+/**
+ * Rejected/platform-managed response headers: user `_headers` rules can never set or remove
+ * these. The internal-redirect family above is a strict subset — anything the proxy lane
+ * refuses to relay is also refused from `_headers`. Ask isPlatformManagedResponseHeader(),
+ * not this list alone: the reserved prefixes are the other half of the policy.
+ */
+export declare const PLATFORM_MANAGED_RESPONSE_HEADERS: readonly string[];

package/dist/utils/static-runtime-policy.generated.js

@@ -0,0 +1,70 @@
+// @generated by `cargo run -p stattic-runtime-compiler --bin protocol-codegen -- --policy-ts`.
+// `crates/stattic-runtime-policy/src/lib.rs` is the only editable authority.
+/** Reserved response-header namespaces carrying the platform's own serving signature. */
+export const PLATFORM_MANAGED_RESPONSE_HEADER_PREFIXES = [
+    "x-spacefast-",
+    "x-stattic-",
+];
+/**
+ * The internal-redirect/sendfile family, every vendor spelling: headers that make the web
+ * server produce a different response instead of describing this one. Factored out of the
+ * managed set below so the proxy relay can drop exactly these from an untrusted upstream
+ * while still relaying ordinary response headers the managed set also lists.
+ */
+export const INTERNAL_REDIRECT_RESPONSE_HEADERS = [
+    "x-accel-buffering",
+    "x-accel-charset",
+    "x-accel-expires",
+    "x-accel-limit-rate",
+    "x-accel-redirect",
+    "x-lighttpd-send-file",
+    "x-lighttpd-sendfile",
+    "x-lighttpd-sendfile2",
+    "x-reproxy-url",
+    "x-sendfile",
+];
+/**
+ * Rejected/platform-managed response headers: user `_headers` rules can never set or remove
+ * these. The internal-redirect family above is a strict subset — anything the proxy lane
+ * refuses to relay is also refused from `_headers`. Ask isPlatformManagedResponseHeader(),
+ * not this list alone: the reserved prefixes are the other half of the policy.
+ */
+export const PLATFORM_MANAGED_RESPONSE_HEADERS = [
+    "accept-ranges",
+    "age",
+    "allow",
+    "alt-svc",
+    "cdn-cache-control",
+    "cloudflare-cdn-cache-control",
+    "connection",
+    "content-encoding",
+    "content-length",
+    "content-range",
+    "cookie",
+    "date",
+    "host",
+    "keep-alive",
+    "location",
+    "netlify-cdn-cache-control",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "server",
+    "set-cookie",
+    "strict-transport-security",
+    "surrogate-control",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+    "vary",
+    "x-accel-buffering",
+    "x-accel-charset",
+    "x-accel-expires",
+    "x-accel-limit-rate",
+    "x-accel-redirect",
+    "x-lighttpd-send-file",
+    "x-lighttpd-sendfile",
+    "x-lighttpd-sendfile2",
+    "x-reproxy-url",
+    "x-sendfile",
+];