@spacefast/common 0.0.13 → 0.0.18

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

@@ -1,6 +1,6 @@
 import { type Grant } from "../contracts/grants.js";
 import { type SpaceConfig, type SpaceConfigFile } from "../contracts/space-config.js";
-export type SpaceConfigBlockingIssueCode = "config_file_too_large" | "config_templates_over_limit" | "config_meta_too_long" | "config_invalid" | "inject_snippet_too_large" | "inject_invalid";
+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";
@@ -15,12 +15,21 @@ export declare function compileSpaceConfigPublicGrant(fileConfig: Pick<SpaceConf
 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.
+ */
+export declare const SPACE_CONFIG_FILE_ONLY_KEYS: readonly ["access", "name", "runtime"];
 /**
  * Validates a space `config` overlay at API intake (PATCH /spaces, publish
- * `config`): the 16 KB compiled-overlay cap plus the shared shape caps.
- * Returns the first blocking issue, or null when the overlay is acceptable.
+ * `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.
  */
-export declare function spaceConfigOverlayIssue(config: SpaceConfig | Record<string, unknown>): SpaceConfigBlockingIssue | null;
+export declare function spaceConfigOverlayIssue(config: unknown): SpaceConfigBlockingIssue | null;
 export declare function stripJsonComments(raw: string): string;
 export type ParsedSpaceConfigFile = {
     /** Parsed config (cap- and shape-valid keys only); null when unusable. */

package/dist/utils/space-config.js

@@ -123,19 +123,103 @@ function capIssues(candidate) {
     }
     return issues;
 }
+// File-only keys (`name`, `runtime`) never reach the API overlay, so their
+// checks live beside the shared caps rather than inside them. Both run BEFORE
+// zod so a bad declaration reports its stable code instead of a shape error.
+const RUNTIME_KINDS = new Set(["zero", "functions"]);
+function fileOnlyIssues(candidate) {
+    const issues = [];
+    const name = candidate.name;
+    if (typeof name === "string" && name.trim().length > SPACE_CONFIG_CAPS.nameChars) {
+        issues.push({
+            severity: "error",
+            code: "config_name_too_long",
+            message: `name supports up to ${SPACE_CONFIG_CAPS.nameChars} characters.`,
+            path: "name",
+            details: { length: name.trim().length, limit: SPACE_CONFIG_CAPS.nameChars },
+        });
+    }
+    const runtime = candidate.runtime;
+    if (runtime === undefined) {
+        return issues;
+    }
+    if (typeof runtime !== "object" || runtime === null || Array.isArray(runtime)) {
+        issues.push({
+            severity: "error",
+            code: "config_runtime_invalid_kind",
+            message: 'runtime must be an object declaring a kind of "zero" or "functions".',
+            path: "runtime",
+        });
+        return issues;
+    }
+    const declaration = runtime;
+    const kind = declaration.kind;
+    if (typeof kind !== "string" || !RUNTIME_KINDS.has(kind)) {
+        issues.push({
+            severity: "error",
+            code: "config_runtime_invalid_kind",
+            message: 'runtime.kind must be "zero" or "functions".',
+            path: "runtime.kind",
+            ...(typeof kind === "string" ? { details: { kind } } : {}),
+        });
+        return issues;
+    }
+    if (kind === "zero") {
+        // Zero is never inferred, so a declaration that names neither entry has
+        // nothing to compile — failing here beats publishing static files under a
+        // config that promised a database app.
+        for (const key of ["server", "client"]) {
+            const value = declaration[key];
+            if (typeof value !== "string" || value.trim().length === 0) {
+                issues.push({
+                    severity: "error",
+                    code: "config_runtime_entry_missing",
+                    message: `runtime.${key} is required and must name a module when runtime.kind is "zero".`,
+                    path: `runtime.${key}`,
+                });
+            }
+        }
+        return issues;
+    }
+    const entry = declaration.entry;
+    if (entry !== undefined && (typeof entry !== "string" || entry.trim().length === 0)) {
+        issues.push({
+            severity: "error",
+            code: "config_runtime_entry_missing",
+            message: "runtime.entry must name a module when present; omit it to detect the worker instead.",
+            path: "runtime.entry",
+        });
+    }
+    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.
+ */
+export const SPACE_CONFIG_FILE_ONLY_KEYS = ["access", "name", "runtime"];
 /**
  * Validates a space `config` overlay at API intake (PATCH /spaces, publish
- * `config`): the 16 KB compiled-overlay cap plus the shared shape caps.
- * Returns the first blocking issue, or null when the overlay is acceptable.
+ * `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.
  */
 export function spaceConfigOverlayIssue(config) {
-    if (Object.prototype.hasOwnProperty.call(config, "access")) {
-        return {
-            severity: "error",
-            code: "config_invalid",
-            message: "access is only valid in the committed sf.jsonc file.",
-            path: "access",
-        };
+    if (config === null || config === undefined || typeof config !== "object") {
+        return null;
+    }
+    for (const key of SPACE_CONFIG_FILE_ONLY_KEYS) {
+        if (Object.prototype.hasOwnProperty.call(config, key)) {
+            return {
+                severity: "error",
+                code: "config_invalid",
+                message: `${key} is only valid in the committed ${SPACE_CONFIG_CANONICAL_FILE} file.`,
+                path: key,
+                details: { file: SPACE_CONFIG_CANONICAL_FILE },
+            };
+        }
     }
     const encoded = JSON.stringify(config);
     if (byteLength(encoded) > SPACE_CONFIG_CAPS.overlayBytes) {
@@ -149,9 +233,18 @@ export function spaceConfigOverlayIssue(config) {
     }
     return capIssues(config)[0] ?? null;
 }
-// Routing concerns never live in sf.jsonc (spec: redirects, rewrites,
-// proxies, and headers stay exclusively in `_redirects`/`_headers`).
-const ROUTING_KEYS = new Set(["redirects", "rewrites", "proxies", "proxy", "headers", "routes"]);
+// Other platforms' routing vocabulary. We have one matcher grammar; naming it
+// four more ways would be four more things to keep in sync.
+const ROUTING_KEYS = new Set(["proxies", "proxy", "routes"]);
+// OUR routing vocabulary. These keys are real sf.jsonc keys, owned end to end
+// by the routing compiler (crates/stattic-runtime-core): the strict v1 compiler
+// validates them and the merge folds them in behind `_redirects`/`_headers`.
+// This lane resolves the serving config, so it neither validates nor carries
+// them — it just leaves them alone.
+const ROUTING_RULE_KEYS = new Set(["redirects", "rewrites", "headers"]);
+// Replaced by the `runtime` declaration; never silently ignored like other
+// unknown keys, because it is the one key whose loss changes what gets served.
+const REMOVED_FUNCTIONS_KEY = "functions";
 const KNOWN_FILE_KEYS = new Set(Object.keys(spaceConfigFileSchema.shape));
 // Strips JSONC comments and trailing commas (string-aware single pass).
 export function stripJsonComments(raw) {
@@ -290,7 +383,23 @@ export function parseSpaceConfigFile(raw, options = {}) {
         if (KNOWN_FILE_KEYS.has(key)) {
             continue;
         }
-        if (ROUTING_KEYS.has(key)) {
+        if (ROUTING_RULE_KEYS.has(key)) {
+            delete record[key];
+            continue;
+        }
+        if (key === REMOVED_FUNCTIONS_KEY) {
+            // The runtime declaration replaced this key outright (spec "The old
+            // top-level functions.* key is removed in the same cutover"): warning-and-
+            // strip would publish static files under a config that asked for a
+            // worker, so it blocks with its own code instead.
+            issues.push({
+                severity: "error",
+                code: "config_functions_key_removed",
+                message: `The "${REMOVED_FUNCTIONS_KEY}" key was removed from ${configPath}; declare runtime.kind "functions" instead.`,
+                path: key,
+            });
+        }
+        else if (ROUTING_KEYS.has(key)) {
             issues.push({
                 severity: "error",
                 code: "config_invalid",
@@ -308,8 +417,7 @@ export function parseSpaceConfigFile(raw, options = {}) {
         }
         delete record[key];
     }
-    const caps = capIssues(record);
-    issues.push(...caps);
+    issues.push(...capIssues(record), ...fileOnlyIssues(record));
     if (issues.some((issue) => issue.severity === "error")) {
         return { config: null, issues };
     }

package/dist/utils/storage-policy.d.ts

@@ -0,0 +1,20 @@
+export declare const STORAGE_OBJECT_MAX_FILE_BYTES: number;
+export declare const STORAGE_OBJECT_MAX_OWNER_BYTES: number;
+export declare const STORAGE_CONTENT_SNIFF_BYTES = 512;
+export declare const STORAGE_BLOCKED_CONTENT_TYPES: string[];
+export declare const STORAGE_BLOCKED_CONTENT_TYPE_FRAGMENTS: string[];
+export declare const STORAGE_BLOCKED_MAGIC_HEX: string[];
+export declare const STORAGE_BLOCKED_TEXT_PREFIXES: string[];
+export declare function storageDeclaredTypeBlocked(contentType: string): boolean;
+export declare function storageContentBlocked(contentType: string, input: Uint8Array): boolean;
+export type StorageByteRange = {
+    unsatisfiable: true;
+} | {
+    start: number;
+    end: number;
+    header: string;
+};
+export declare function storageParseSingleRange(rangeHeader: string | null | undefined, size: number): StorageByteRange | null;
+export declare function storageIfNoneMatchMatches(header: string | null | undefined, etag: string): boolean;
+export declare function storageParseHttpDate(value: string): number | null;
+export declare function storageIfRangeMatches(ifRange: string, etag: string, lastModified: string): boolean;

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

@@ -0,0 +1,174 @@
+{
+    "content": [
+        {
+            "name": "declared html",
+            "contentType": "text/html; charset=utf-8",
+            "hex": "706c61696e",
+            "expected": true
+        },
+        {
+            "name": "declared javascript",
+            "contentType": "application/javascript",
+            "hex": "706c61696e",
+            "expected": true
+        },
+        {
+            "name": "windows executable magic",
+            "contentType": "application/octet-stream",
+            "hex": "4d5a0000",
+            "expected": true
+        },
+        {
+            "name": "mach executable magic",
+            "contentType": "application/octet-stream",
+            "hex": "feedfacf0000",
+            "expected": true
+        },
+        {
+            "name": "trimmed active html",
+            "contentType": "text/plain",
+            "hex": "20090a3c7363726970743e",
+            "expected": true
+        },
+        {
+            "name": "svg remains allowed",
+            "contentType": "image/svg+xml",
+            "hex": "3c73766720786d6c6e733d22687474703a2f2f7777772e77332e6f72672f323030302f737667223e",
+            "expected": false
+        },
+        {
+            "name": "plain bytes remain allowed",
+            "contentType": "application/octet-stream",
+            "hex": "68656c6c6f2073746f72616765",
+            "expected": false
+        }
+    ],
+    "ranges": [
+        { "name": "absent", "header": null, "size": 14, "expected": null },
+        {
+            "name": "full tail",
+            "header": "bytes=7-",
+            "size": 14,
+            "expected": { "start": 7, "end": 13, "header": "bytes=7-13" }
+        },
+        {
+            "name": "bounded",
+            "header": "bytes=0-6",
+            "size": 14,
+            "expected": { "start": 0, "end": 6, "header": "bytes=0-6" }
+        },
+        {
+            "name": "suffix",
+            "header": "bytes=-4",
+            "size": 14,
+            "expected": { "start": 10, "end": 13, "header": "bytes=10-13" }
+        },
+        {
+            "name": "clamped",
+            "header": "bytes=10-99",
+            "size": 14,
+            "expected": { "start": 10, "end": 13, "header": "bytes=10-13" }
+        },
+        {
+            "name": "unsatisfiable",
+            "header": "bytes=20-30",
+            "size": 14,
+            "expected": { "unsatisfiable": true }
+        },
+        { "name": "multiple ignored", "header": "bytes=0-1,4-5", "size": 14, "expected": null },
+        { "name": "malformed ignored", "header": "items=0-1", "size": 14, "expected": null }
+    ],
+    "ifNoneMatch": [
+        { "name": "exact", "header": "\"abc\"", "etag": "\"abc\"", "expected": true },
+        { "name": "weak", "header": "W/\"abc\"", "etag": "\"abc\"", "expected": true },
+        { "name": "list", "header": "\"no\", W/\"abc\"", "etag": "\"abc\"", "expected": true },
+        { "name": "wildcard", "header": "*", "etag": "\"abc\"", "expected": true },
+        { "name": "miss", "header": "\"no\"", "etag": "\"abc\"", "expected": false }
+    ],
+    "ifRange": [
+        {
+            "name": "exact etag",
+            "header": "\"abc\"",
+            "etag": "\"abc\"",
+            "lastModified": "Wed, 21 Oct 2015 07:28:00 GMT",
+            "expected": true
+        },
+        {
+            "name": "weak etag rejected",
+            "header": "W/\"abc\"",
+            "etag": "\"abc\"",
+            "lastModified": "Wed, 21 Oct 2015 07:28:00 GMT",
+            "expected": false
+        },
+        {
+            "name": "newer date",
+            "header": "Wed, 21 Oct 2015 07:29:00 GMT",
+            "etag": "\"abc\"",
+            "lastModified": "Wed, 21 Oct 2015 07:28:00 GMT",
+            "expected": true
+        },
+        {
+            "name": "older date",
+            "header": "Wed, 21 Oct 2015 07:27:00 GMT",
+            "etag": "\"abc\"",
+            "lastModified": "Wed, 21 Oct 2015 07:28:00 GMT",
+            "expected": false
+        },
+        {
+            "name": "leap second",
+            "header": "Wed, 21 Oct 2015 07:28:60 GMT",
+            "etag": "\"abc\"",
+            "lastModified": "Wed, 21 Oct 2015 07:28:59 GMT",
+            "expected": true
+        },
+        {
+            "name": "obsolete RFC 850 date",
+            "header": "Sunday, 06-Nov-94 08:49:37 GMT",
+            "etag": "\"abc\"",
+            "lastModified": "Sun, 06 Nov 1994 08:49:37 GMT",
+            "expected": true
+        },
+        {
+            "name": "obsolete asctime date",
+            "header": "Sun Nov  6 08:49:37 1994",
+            "etag": "\"abc\"",
+            "lastModified": "Sun, 06 Nov 1994 08:49:37 GMT",
+            "expected": true
+        },
+        {
+            "name": "relative date rejected",
+            "header": "tomorrow",
+            "etag": "\"abc\"",
+            "lastModified": "Wed, 21 Oct 2015 07:28:00 GMT",
+            "expected": false
+        },
+        {
+            "name": "wrong weekday rejected",
+            "header": "Thu, 21 Oct 2015 07:29:00 GMT",
+            "etag": "\"abc\"",
+            "lastModified": "Wed, 21 Oct 2015 07:28:00 GMT",
+            "expected": false
+        },
+        {
+            "name": "invalid calendar date rejected",
+            "header": "Fri, 31 Feb 2023 07:29:00 GMT",
+            "etag": "\"abc\"",
+            "lastModified": "Wed, 21 Oct 2015 07:28:00 GMT",
+            "expected": false
+        },
+        {
+            "name": "out-of-range time rejected",
+            "header": "Wed, 21 Oct 2015 07:28:61 GMT",
+            "etag": "\"abc\"",
+            "lastModified": "Wed, 21 Oct 2015 07:28:00 GMT",
+            "expected": false
+        },
+        {
+            "name": "trailing garbage rejected",
+            "header": "Wed, 21 Oct 2015 07:29:00 GMT later",
+            "etag": "\"abc\"",
+            "lastModified": "Wed, 21 Oct 2015 07:28:00 GMT",
+            "expected": false
+        }
+    ]
+}

package/dist/utils/storage-policy.js

@@ -0,0 +1,193 @@
+// Single source of truth for storage HTTP and object-intake policy.
+//
+// TypeScript adapters import this module directly. The PHP runtime binding is
+// generated into runtime/engine/shared/storage-policy.generated.php by
+// `bun --filter @spacefast/control-plane runtime:codegen-policy`. Both execute
+// the same storage-policy.fixtures.json corpus.
+export const STORAGE_OBJECT_MAX_FILE_BYTES = 5 * 1024 * 1024;
+export const STORAGE_OBJECT_MAX_OWNER_BYTES = 100 * 1024 * 1024;
+export const STORAGE_CONTENT_SNIFF_BYTES = 512;
+export const STORAGE_BLOCKED_CONTENT_TYPES = [
+    "application/java-archive",
+    "application/java-vm",
+    "application/vnd.microsoft.portable-executable",
+    "application/x-dosexec",
+    "application/x-httpd-php",
+    "application/x-java-archive",
+    "application/x-mach-binary",
+    "application/x-msdownload",
+    "application/xhtml+xml",
+    "text/html",
+];
+export const STORAGE_BLOCKED_CONTENT_TYPE_FRAGMENTS = ["javascript", "ecmascript"];
+export const STORAGE_BLOCKED_MAGIC_HEX = [
+    "4d5a",
+    "7f454c46",
+    "feedface",
+    "cefaedfe",
+    "feedfacf",
+    "cffaedfe",
+    "cafebabe",
+];
+export const STORAGE_BLOCKED_TEXT_PREFIXES = ["#!", "<!doctype html", "<html", "<script", "<?php"];
+const BLOCKED_CONTENT_TYPES = new Set(STORAGE_BLOCKED_CONTENT_TYPES);
+export function storageDeclaredTypeBlocked(contentType) {
+    const declared = contentType.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+    return (BLOCKED_CONTENT_TYPES.has(declared) ||
+        STORAGE_BLOCKED_CONTENT_TYPE_FRAGMENTS.some((fragment) => declared.includes(fragment)));
+}
+function bytesStartWithHex(bytes, hex) {
+    if (bytes.byteLength < hex.length / 2)
+        return false;
+    for (let offset = 0; offset < hex.length; offset += 2) {
+        if (bytes[offset / 2] !== Number.parseInt(hex.slice(offset, offset + 2), 16)) {
+            return false;
+        }
+    }
+    return true;
+}
+export function storageContentBlocked(contentType, input) {
+    if (storageDeclaredTypeBlocked(contentType))
+        return true;
+    const prefix = input.subarray(0, STORAGE_CONTENT_SNIFF_BYTES);
+    if (STORAGE_BLOCKED_MAGIC_HEX.some((magic) => bytesStartWithHex(prefix, magic))) {
+        return true;
+    }
+    const decoded = new TextDecoder().decode(prefix);
+    let contentStart = 0;
+    while (contentStart < decoded.length) {
+        const code = decoded.charCodeAt(contentStart);
+        if (code !== 0 && code !== 9 && code !== 10 && code !== 11 && code !== 13 && code !== 32) {
+            break;
+        }
+        contentStart += 1;
+    }
+    const text = decoded.slice(contentStart).toLowerCase();
+    return STORAGE_BLOCKED_TEXT_PREFIXES.some((blocked) => text.startsWith(blocked));
+}
+export function storageParseSingleRange(rangeHeader, size) {
+    if (!rangeHeader || rangeHeader.trim() === "" || rangeHeader.includes(","))
+        return null;
+    const match = /^bytes=(\d*)-(\d*)$/.exec(rangeHeader.trim());
+    if (!match || (!match[1] && !match[2]))
+        return null;
+    if (!match[1]) {
+        const suffix = Number(match[2]);
+        if (!Number.isSafeInteger(suffix) || suffix <= 0 || size <= 0) {
+            return { unsatisfiable: true };
+        }
+        const start = Math.max(0, size - suffix);
+        const end = size - 1;
+        return { start, end, header: `bytes=${start}-${end}` };
+    }
+    const start = Number(match[1]);
+    const requestedEnd = match[2] ? Number(match[2]) : size - 1;
+    const end = Math.min(requestedEnd, size - 1);
+    if (!Number.isSafeInteger(start) ||
+        !Number.isSafeInteger(requestedEnd) ||
+        start >= size ||
+        start > end ||
+        size < 0) {
+        return { unsatisfiable: true };
+    }
+    return { start, end, header: `bytes=${start}-${end}` };
+}
+function storageEtagOpaqueTag(etag) {
+    const trimmed = etag.trim();
+    return /^W\//i.test(trimmed) ? trimmed.slice(2).trim() : trimmed;
+}
+export function storageIfNoneMatchMatches(header, etag) {
+    const value = header?.trim() ?? "";
+    if (value === "")
+        return false;
+    if (value === "*")
+        return true;
+    const target = storageEtagOpaqueTag(etag);
+    if (target === "")
+        return false;
+    return value
+        .split(",")
+        .map((candidate) => candidate.trim())
+        .filter(Boolean)
+        .some((candidate) => storageEtagOpaqueTag(candidate) === target);
+}
+const HTTP_MONTHS = [
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+];
+const HTTP_WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+const HTTP_WEEKDAYS_LONG = [
+    "Sunday",
+    "Monday",
+    "Tuesday",
+    "Wednesday",
+    "Thursday",
+    "Friday",
+    "Saturday",
+];
+function storageHttpDateTimestamp(weekday, day, month, year, hour, minute, second) {
+    if (hour > 23 || minute > 59 || second > 60)
+        return null;
+    const normalizedSecond = Math.min(second, 59);
+    const date = new Date(0);
+    date.setUTCFullYear(year, month, day);
+    date.setUTCHours(hour, minute, normalizedSecond, 0);
+    if (date.getUTCFullYear() !== year ||
+        date.getUTCMonth() !== month ||
+        date.getUTCDate() !== day ||
+        date.getUTCHours() !== hour ||
+        date.getUTCMinutes() !== minute ||
+        date.getUTCSeconds() !== normalizedSecond ||
+        (weekday !== null && date.getUTCDay() !== weekday)) {
+        return null;
+    }
+    return date.getTime() + (second === 60 ? 1_000 : 0);
+}
+// HTTP-date has exactly three accepted wire forms (RFC 9110 §5.6.7). General
+// date parsers also accept relative/free-form input such as `tomorrow`, so
+// validators must parse the grammar and validate its calendar components.
+export function storageParseHttpDate(value) {
+    const input = value.trim();
+    let match = /^(Sun|Mon|Tue|Wed|Thu|Fri|Sat), (\d{2}) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (\d{4}) (\d{2}):(\d{2}):(\d{2}) GMT$/.exec(input);
+    if (match) {
+        return storageHttpDateTimestamp(HTTP_WEEKDAYS.indexOf(match[1] ?? ""), Number(match[2]), HTTP_MONTHS.indexOf(match[3] ?? ""), Number(match[4]), Number(match[5]), Number(match[6]), Number(match[7]));
+    }
+    match =
+        /^(Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday), (\d{2})-(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)-(\d{2}) (\d{2}):(\d{2}):(\d{2}) GMT$/.exec(input);
+    if (match) {
+        const now = new Date();
+        let year = Math.floor(now.getUTCFullYear() / 100) * 100 + Number(match[4]);
+        const candidate = storageHttpDateTimestamp(null, Number(match[2]), HTTP_MONTHS.indexOf(match[3] ?? ""), year, Number(match[5]), Number(match[6]), Number(match[7]));
+        const fiftyYearsFromNow = new Date(now);
+        fiftyYearsFromNow.setUTCFullYear(now.getUTCFullYear() + 50);
+        if (candidate !== null && candidate > fiftyYearsFromNow.getTime())
+            year -= 100;
+        return storageHttpDateTimestamp(HTTP_WEEKDAYS_LONG.indexOf(match[1] ?? ""), Number(match[2]), HTTP_MONTHS.indexOf(match[3] ?? ""), year, Number(match[5]), Number(match[6]), Number(match[7]));
+    }
+    match =
+        /^(Sun|Mon|Tue|Wed|Thu|Fri|Sat) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (?:([0-9]{2})| ([0-9])) (\d{2}):(\d{2}):(\d{2}) (\d{4})$/.exec(input);
+    if (!match)
+        return null;
+    return storageHttpDateTimestamp(HTTP_WEEKDAYS.indexOf(match[1] ?? ""), Number(match[3] ?? match[4]), HTTP_MONTHS.indexOf(match[2] ?? ""), Number(match[8]), Number(match[5]), Number(match[6]), Number(match[7]));
+}
+export function storageIfRangeMatches(ifRange, etag, lastModified) {
+    const value = ifRange.trim();
+    if (value === "" || /^W\//i.test(value))
+        return false;
+    if (value.startsWith('"')) {
+        return !/^W\//i.test(etag.trim()) && etag.trim() === value;
+    }
+    const requestTime = storageParseHttpDate(value);
+    const modifiedTime = storageParseHttpDate(lastModified);
+    return requestTime !== null && modifiedTime !== null && requestTime >= modifiedTime;
+}

package/dist/utils/upload-session.d.ts

@@ -19,10 +19,21 @@ export type UploadSessionEvent = {
     target: UploadTarget;
     error: unknown;
 };
+/** The RFC 9457 problem document a runtime upload target returns on failure. */
+export type UploadTargetServerError = {
+    code: string;
+    message: string;
+    pointer?: string;
+    type?: string;
+    details?: unknown;
+    suggestions?: readonly string[];
+    requestId?: string;
+};
 export declare class UploadTargetError extends Error {
     readonly target: UploadTarget;
     readonly status: number;
-    constructor(target: UploadTarget, status: number, message: string);
+    readonly serverError?: UploadTargetServerError | undefined;
+    constructor(target: UploadTarget, status: number, message: string, serverError?: UploadTargetServerError | undefined);
 }
 export declare function uploadPageHasRemainder(page: UploadSession): boolean;
 export declare const UPLOAD_STALLED_RESUME_MAX_ATTEMPTS = 3;

package/dist/utils/upload-session.js

@@ -1,13 +1,47 @@
 export class UploadTargetError extends Error {
     target;
     status;
-    constructor(target, status, message) {
+    serverError;
+    constructor(target, status, message, serverError) {
         super(message);
         this.target = target;
         this.status = status;
+        this.serverError = serverError;
         this.name = "UploadTargetError";
     }
 }
+function parseUploadTargetServerError(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (!parsed || typeof parsed !== "object") {
+        return undefined;
+    }
+    const record = parsed;
+    if (typeof record.code !== "string" || typeof record.detail !== "string") {
+        return undefined;
+    }
+    const stringField = (name) => typeof record[name] === "string" ? record[name] : undefined;
+    const suggestions = Array.isArray(record.suggestions)
+        ? record.suggestions.filter((entry) => typeof entry === "string")
+        : [];
+    const pointer = stringField("pointer");
+    const type = stringField("type");
+    const requestId = stringField("requestId");
+    return {
+        code: record.code,
+        message: record.detail,
+        ...(pointer ? { pointer } : {}),
+        ...(type ? { type } : {}),
+        ...(record.details === undefined ? {} : { details: record.details }),
+        ...(suggestions.length > 0 ? { suggestions } : {}),
+        ...(requestId ? { requestId } : {}),
+    };
+}
 // Manifest paging policy — ONE definition, shared by every uploader (the CLI
 // and the control plane's inline uploader).
 //
@@ -78,8 +112,9 @@ export async function executeUploadSession(input) {
             });
             if (!response.ok) {
                 const details = await response.text().catch(() => "");
+                const serverError = parseUploadTargetServerError(details);
                 const suffix = details.trim() ? `: ${details.trim().slice(0, 1_000)}` : "";
-                throw new UploadTargetError(target, response.status, `Upload failed for ${target.path} with ${response.status} ${response.statusText}${suffix}.`);
+                throw new UploadTargetError(target, response.status, `Upload failed for ${target.path} with ${response.status} ${response.statusText}${suffix}.`, serverError);
             }
             input.onEvent?.({ type: "target-done", target });
         }