@stigmer/server 3.14.0-dev.20260910084630

package/dist/domain/skill/storage/zip-gate.js

@@ -0,0 +1,186 @@
+/**
+ * Skill artifact ZIP gate — ports pkg/domain/skill/storage/zip_extractor.go
+ * arm-for-arm. Validates an uploaded artifact (size caps, ZIP-bomb
+ * budgets, entry-count and filename rules, root-SKILL.md presence with the
+ * #452 hint), extracts SKILL.md IN MEMORY ONLY (never to disk), and parses
+ * its frontmatter. Structural parsing rides @stigmer/zip-structure
+ * (central-directory-based, issues #450/#567); the safearchive-parity
+ * entry pre-filter runs first (prefilter.ts, sub-project DD-001) exactly
+ * as Go's reader rewrites its entry list before validation.
+ *
+ * Error strings are wire-visible contract (the push pipeline wraps them
+ * into the InvalidArgument "failed to extract SKILL.md: ..." arm), pinned
+ * from Go including the stdlib texts Go's %w wrapping surfaces
+ * ("zip: not a valid zip file", "zip: unsupported compression algorithm",
+ * "zip: checksum error"). Two disclosed nuances versus Go, both stricter
+ * only on pathological archives: a corrupt payload SLICE on any entry
+ * fails structural parsing here while Go only fails when it opens that
+ * entry, and deflate-corruption error text carries zlib's message rather
+ * than Go flate's.
+ *
+ * Proven by __tests__/zip-gate.test.ts and the skill conformance suite's
+ * push-validation negatives (CONFORMANCE_TARGET=local).
+ */
+import { createHash } from "node:crypto";
+import { inflateRawSync } from "node:zlib";
+import { crc32, parseZipStructure } from "@stigmer/zip-structure";
+import { MAX_COMPRESSION_RATIO, MAX_FILES, MAX_SKILL_MD_SIZE, MAX_UNCOMPRESSED_SIZE, MAX_ZIP_SIZE, NESTED_SKILL_MD_HINT, } from "../constants.js";
+import { applyEntryPrefilter } from "./prefilter.js";
+import { parseFrontmatter } from "./frontmatter.js";
+/** ZIP compression methods the gate can open (Go registers the same two). */
+const METHOD_STORED = 0;
+const METHOD_DEFLATED = 8;
+/**
+ * Validates the artifact and extracts SKILL.md + frontmatter (Go
+ * ExtractSkillMd). Throws plain Errors with byte-pinned messages; the
+ * push pipeline owns the gRPC code.
+ */
+export function extractSkillMd(zipData) {
+    if (zipData.length > MAX_ZIP_SIZE) {
+        throw new Error(`ZIP file too large: ${zipData.length} bytes (max: ${MAX_ZIP_SIZE})`);
+    }
+    const hash = calculateHash(zipData);
+    let entries;
+    try {
+        entries = parseZipStructure(zipData);
+    }
+    catch {
+        // Go's zip.NewReader surfaces stdlib ErrFormat here; its text is what
+        // clients see via the %w chain, so it is pinned verbatim.
+        throw new Error("invalid ZIP file: zip: not a valid zip file");
+    }
+    // safearchive MaximumSecurityMode rewrites the entry list before any
+    // validation sees it (DD-001) — sanitized names, shadowed/special/8.3
+    // entries dropped.
+    const filtered = applyEntryPrefilter(entries);
+    validateZipContent(filtered);
+    const content = extractSkillMdContent(filtered);
+    let frontmatter;
+    try {
+        frontmatter = parseFrontmatter(content);
+    }
+    catch (error) {
+        throw new Error(`invalid SKILL.md frontmatter: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return {
+        content,
+        hash,
+        name: frontmatter.name,
+        description: frontmatter.description,
+    };
+}
+/**
+ * Security validation over the (pre-filtered) entry list — Go
+ * validateZipContent, checks in its exact order: empty archive, file-count
+ * cap, then per entry SKILL.md placement tracking, filename
+ * control-character rejection, the running declared-uncompressed budget
+ * (fail-fast), and the per-file compression-ratio cap; finally the
+ * root-SKILL.md presence rule with the #452 nested-only hint.
+ */
+function validateZipContent(entries) {
+    if (entries.length === 0) {
+        throw new Error("ZIP file is empty");
+    }
+    if (entries.length > MAX_FILES) {
+        throw new Error(`too many files in ZIP: ${entries.length} (max: ${MAX_FILES})`);
+    }
+    let totalUncompressedSize = 0;
+    let hasSkillMd = false;
+    let hasNestedSkillMd = false;
+    for (const { name, entry } of entries) {
+        // SKILL.md must be at the archive root. Nested occurrences are tracked
+        // only to make the rejection actionable (below).
+        if (name === "SKILL.md") {
+            hasSkillMd = true;
+        }
+        else if (name.endsWith("/SKILL.md")) {
+            hasNestedSkillMd = true;
+        }
+        // Reject null bytes and control characters in entry names (code
+        // points, not UTF-16 units — Go ranges over runes).
+        for (const ch of name) {
+            const codePoint = ch.codePointAt(0);
+            if (codePoint < 32 || codePoint === 127) {
+                throw new Error(`invalid character in filename: ${name}`);
+            }
+        }
+        // Track the declared uncompressed total (fail fast once exceeded).
+        totalUncompressedSize += entry.uncompressedSize;
+        if (totalUncompressedSize > MAX_UNCOMPRESSED_SIZE) {
+            throw new Error(`total uncompressed size too large: ${totalUncompressedSize} bytes (max: ${MAX_UNCOMPRESSED_SIZE})`);
+        }
+        // Per-file compression ratio (ZIP-bomb guard); integer division as Go.
+        if (entry.compressedSize > 0) {
+            const ratio = Math.floor(entry.uncompressedSize / entry.compressedSize);
+            if (ratio > MAX_COMPRESSION_RATIO) {
+                throw new Error(`suspicious compression ratio in ${name}: ${ratio}:1 (max: ${MAX_COMPRESSION_RATIO}:1)`);
+            }
+        }
+    }
+    if (!hasSkillMd) {
+        if (hasNestedSkillMd) {
+            throw new Error(NESTED_SKILL_MD_HINT);
+        }
+        throw new Error("SKILL.md not found in ZIP archive");
+    }
+}
+/**
+ * Extracts SKILL.md's content in memory (Go extractSkillMdContent): the
+ * first root-named entry, decompressed under the 1MB cap, CRC-verified
+ * (Go's reader checks the checksum on every read), UTF-8 decoded.
+ */
+function extractSkillMdContent(entries) {
+    for (const { name, entry } of entries) {
+        if (name !== "SKILL.md") {
+            continue;
+        }
+        let contentBytes;
+        switch (entry.compressionMethod) {
+            case METHOD_STORED:
+                contentBytes = entry.compressedData;
+                break;
+            case METHOD_DEFLATED:
+                try {
+                    // The cap bounds the ACTUAL inflated output — declared sizes are
+                    // client claims (the ratio check upstream only sees declarations).
+                    contentBytes = new Uint8Array(inflateRawSync(entry.compressedData, {
+                        maxOutputLength: MAX_SKILL_MD_SIZE + 1,
+                    }));
+                }
+                catch (error) {
+                    if (isOutputLengthError(error)) {
+                        throw new Error(`SKILL.md too large (max: ${MAX_SKILL_MD_SIZE} bytes)`);
+                    }
+                    throw new Error(`failed to read SKILL.md: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                break;
+            default:
+                // Go: File.Open returns ErrAlgorithm for methods without a
+                // registered decompressor; the text is pinned via the %w chain.
+                throw new Error("failed to open SKILL.md: zip: unsupported compression algorithm");
+        }
+        if (contentBytes.length > MAX_SKILL_MD_SIZE) {
+            throw new Error(`SKILL.md too large (max: ${MAX_SKILL_MD_SIZE} bytes)`);
+        }
+        if (crc32(contentBytes) !== entry.crc32) {
+            // Go's checksumReader: stdlib ErrChecksum via the read-error arm.
+            throw new Error("failed to read SKILL.md: zip: checksum error");
+        }
+        if (contentBytes.length === 0) {
+            throw new Error("SKILL.md is empty");
+        }
+        return new TextDecoder().decode(contentBytes);
+    }
+    throw new Error("SKILL.md not found in ZIP archive");
+}
+/** node:zlib's maxOutputLength violation (the output-cap arm). */
+function isOutputLengthError(error) {
+    return (error instanceof Error &&
+        (("code" in error && error.code === "ERR_BUFFER_TOO_LARGE") ||
+            error.message.includes("maxOutputLength")));
+}
+/** SHA-256 hex of the artifact bytes (Go CalculateHash). */
+export function calculateHash(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+//# sourceMappingURL=zip-gate.js.map

package/dist/domain/skill/storage/zip-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zip-gate.js","sourceRoot":"","sources":["../../../../src/domain/skill/storage/zip-gate.ts"],"names":[],"mappings":"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"}

package/dist/domain/skill/transfer/handler.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Skill artifact transfer lane — ports pkg/domain/skill/transfer/handler.go:
+ * the HTTP upload/download surface that carries skill artifact bytes
+ * OUTSIDE the gRPC control plane (#675). The gRPC server caps messages at
+ * 10MB while the skill layer permits 100MB artifacts, so inline bytes
+ * physically cannot carry every valid skill.
+ *
+ *   PUT {prefix}/uploads/{ref}  — stage artifact bytes (capability: ref)
+ *   GET {prefix}/{storage_key}  — serve artifact bytes (capability: key)
+ *
+ * Neither route carries bearer auth by design: the URL is the credential,
+ * mirroring cloud's pre-signed R2 URLs. Minting an upload URL requires the
+ * same gRPC authorization as push; download keys are unguessable content
+ * hashes handed out by authorized skill reads.
+ *
+ * The lane slots into the transport's existing skillTransferLane seam
+ * (transport/server.ts lane 3); URL renderers live next to the route
+ * dispatch so the URL shape and its handler cannot drift apart (Go's
+ * stated invariant). Proven by __tests__/skill.test.ts's transfer-lane
+ * block (both protocol stacks) and the conformance suite's transfer-lane
+ * tests.
+ */
+import type { Logger } from "../../../boot/logger.js";
+import type { LaneHandler } from "../../../transport/lanes.js";
+import type { SkillArtifactStorage } from "../storage/artifact-storage.js";
+import type { UploadSlots } from "./slots.js";
+/**
+ * Renders the capability URL for a minted reference against the lane's
+ * externally-reachable base URL.
+ */
+export declare function uploadUrl(baseUrl: string, ref: string): string;
+/** Renders the download URL for an artifact storage key. */
+export declare function downloadUrl(baseUrl: string, storageKey: string): string;
+/** Builds the lane handler (Go NewHandler). */
+export declare function newSkillTransferLane(slots: UploadSlots, artifacts: SkillArtifactStorage, logger: Logger): LaneHandler;
+//# sourceMappingURL=handler.d.ts.map

package/dist/domain/skill/transfer/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../../src/domain/skill/transfer/handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,KAAK,EAAE,WAAW,EAA6B,MAAM,6BAA6B,CAAC;AAG1F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAM3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,4DAA4D;AAC5D,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAEvE;AAMD,+CAA+C;AAC/C,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,oBAAoB,EAC/B,MAAM,EAAE,MAAM,GACb,WAAW,CAsCb"}

package/dist/domain/skill/transfer/handler.js

@@ -0,0 +1,120 @@
+import { SKILL_ARTIFACTS_PATH_PREFIX } from "../../../transport/constants.js";
+import { DOWNLOAD_KEY_PREFIX, UPLOADS_SEGMENT } from "../constants.js";
+import { ArtifactNotFoundError } from "../storage/artifact-storage.js";
+import { SizeMismatchError, SlotConsumedError, SlotUnknownError, } from "./slots.js";
+/**
+ * Renders the capability URL for a minted reference against the lane's
+ * externally-reachable base URL.
+ */
+export function uploadUrl(baseUrl, ref) {
+    return `${trimTrailingSlash(baseUrl)}${SKILL_ARTIFACTS_PATH_PREFIX}${UPLOADS_SEGMENT}${ref}`;
+}
+/** Renders the download URL for an artifact storage key. */
+export function downloadUrl(baseUrl, storageKey) {
+    return `${trimTrailingSlash(baseUrl)}${SKILL_ARTIFACTS_PATH_PREFIX}/${storageKey}`;
+}
+function trimTrailingSlash(url) {
+    return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+/** Builds the lane handler (Go NewHandler). */
+export function newSkillTransferLane(slots, artifacts, logger) {
+    return (request, response) => {
+        const url = request.url ?? "";
+        const pathOnly = url.split("?")[0] ?? "";
+        if (!pathOnly.startsWith(SKILL_ARTIFACTS_PATH_PREFIX)) {
+            // Unreachable through the lane router (it dispatches by this exact
+            // prefix); kept as the honest Go http.NotFound arm for direct use.
+            writeText(response, 404, "404 page not found");
+            return;
+        }
+        const rest = pathOnly.slice(SKILL_ARTIFACTS_PATH_PREFIX.length);
+        // The lane router is synchronous; the async handlers run detached. The
+        // terminal catch is load-bearing: a response-write failure on a
+        // vanished client would otherwise escape as an unhandled rejection —
+        // process-fatal under Node's default policy.
+        const logDetachedFailure = (arm) => (error) => {
+            logger.error(`skill transfer lane ${arm} handler failed`, {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        };
+        if (rest.startsWith(UPLOADS_SEGMENT)) {
+            const ref = rest.slice(UPLOADS_SEGMENT.length);
+            handleUpload(request, response, slots, ref, logger).catch(logDetachedFailure("upload"));
+            return;
+        }
+        handleDownload(request, response, artifacts, rest.replace(/^\//, ""), logger).catch(logDetachedFailure("download"));
+    };
+}
+async function handleUpload(request, response, slots, ref, logger) {
+    if (request.method !== "PUT") {
+        response.setHeader("Allow", "PUT");
+        writeText(response, 405, "method not allowed");
+        return;
+    }
+    try {
+        await slots.receive(ref, request);
+        response.statusCode = 204;
+        response.end();
+    }
+    catch (error) {
+        if (error instanceof SlotUnknownError) {
+            // Deliberately the same shape for "never existed" and "expired":
+            // distinguishing them would let an unauthorized caller probe which
+            // tokens were once valid.
+            writeText(response, 404, "upload reference unknown or expired — request a new upload URL");
+        }
+        else if (error instanceof SlotConsumedError) {
+            writeText(response, 409, "upload reference already used — request a new upload URL");
+        }
+        else if (error instanceof SizeMismatchError) {
+            writeText(response, 400, `${error.message} — the upload must match the size declared to createArtifactUploadUrl`);
+        }
+        else {
+            logger.error("skill artifact upload failed", {
+                ref,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            writeText(response, 500, "failed to stage upload");
+        }
+    }
+}
+async function handleDownload(request, response, artifacts, key, logger) {
+    if (request.method !== "GET") {
+        response.setHeader("Allow", "GET");
+        writeText(response, 405, "method not allowed");
+        return;
+    }
+    if (!key.startsWith(DOWNLOAD_KEY_PREFIX)) {
+        writeText(response, 404, "404 page not found");
+        return;
+    }
+    let data;
+    try {
+        // Full in-memory read matches the store's own interface (get returns
+        // bytes) and the ≤100MB validation ceiling bounds the allocation.
+        data = await artifacts.get(key);
+    }
+    catch (error) {
+        if (error instanceof ArtifactNotFoundError) {
+            writeText(response, 404, "404 page not found");
+            return;
+        }
+        logger.error("skill artifact download failed", {
+            storageKey: key,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        writeText(response, 500, "failed to load artifact");
+        return;
+    }
+    response.setHeader("Content-Type", "application/zip");
+    response.setHeader("Content-Length", String(data.length));
+    response.statusCode = 200;
+    response.end(Buffer.from(data));
+}
+/** Go http.Error's shape: text/plain body with a trailing newline. */
+function writeText(response, status, body) {
+    response.statusCode = status;
+    response.setHeader("Content-Type", "text/plain; charset=utf-8");
+    response.end(`${body}\n`);
+}
+//# sourceMappingURL=handler.js.map

package/dist/domain/skill/transfer/handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../../../../src/domain/skill/transfer/handler.ts"],"names":[],"mappings":"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"}

package/dist/domain/skill/transfer/slots.d.ts

@@ -0,0 +1,79 @@
+import type { Readable } from "node:stream";
+/** Go errSlotUnknown — never existed, expired, or swept. */
+export declare class SlotUnknownError extends Error {
+    constructor();
+}
+/** Go errSlotConsumed — the slot already carries an upload. */
+export declare class SlotConsumedError extends Error {
+    constructor();
+}
+/** Go errSlotEmpty — minted but never (successfully) uploaded to. */
+export declare class SlotEmptyError extends Error {
+    constructor();
+}
+/** Go errSizeMismatch — the body disagreed with the minted declaration. */
+export declare class SizeMismatchError extends Error {
+    constructor(received: number, declared: number);
+}
+export declare class UploadSlots {
+    private readonly slots;
+    private readonly stagingDir;
+    private readonly ttlMs;
+    private readonly maxSize;
+    /** Injectable for expiry tests, mirroring Go's `now` field. */
+    private readonly now;
+    /**
+     * Creates the registry and prepares the staging directory. Any file
+     * already present is an orphan from a previous process (the registry
+     * that knew about it died with that process), so the directory is
+     * emptied — this is also the crash-recovery story for uploads that
+     * never reached their push.
+     */
+    constructor(stagingDir: string, ttlMs: number, maxSize: number, now?: () => number);
+    /**
+     * Reserves an upload slot for an artifact of declaredSize bytes and
+     * returns its single-use reference + TTL. The caller has already
+     * authorized the request and validated declaredSize against the skill
+     * size limit; this guard is the registry's own invariant.
+     */
+    mint(declaredSize: number): {
+        ref: string;
+        ttlMs: number;
+    };
+    /**
+     * Streams an upload's body into the slot's staging file. The body must
+     * match the size declared at mint time exactly: a shorter body means a
+     * truncated transfer, a longer one means the client lied — both reject
+     * rather than staging bytes that would fail (or worse, surprise)
+     * validation later. The staged file only becomes consumable once this
+     * resolves.
+     */
+    receive(ref: string, body: Readable): Promise<void>;
+    /**
+     * Returns the staged bytes for ref and retires the slot — an upload
+     * reference is strictly single-use. Push calls this when it sees
+     * artifact_upload_ref; whatever happens downstream (validation failure
+     * included), the slot is gone and the client must re-mint to retry.
+     */
+    consume(ref: string): Promise<Uint8Array>;
+    /**
+     * Drops expired slots and their staged files. Called from mint, which
+     * bounds the registry: it can hold at most the slots minted within one
+     * TTL window.
+     */
+    private sweep;
+    /**
+     * The staging file name for a reference. Public since O5: the local
+     * driver's presigned-PUT arm maps refs onto driver staging keys
+     * (boot/compose.ts), and that mapping must come from HERE — a
+     * re-declared "<ref>.zip" in the composition would drift from stagePath
+     * with nothing to catch it.
+     */
+    stagedFileName(ref: string): string;
+    /**
+     * Maps a reference to its staging file. refs are server-generated hex
+     * (never client-supplied paths), so simple joining is safe.
+     */
+    private stagePath;
+}
+//# sourceMappingURL=slots.d.ts.map

package/dist/domain/skill/transfer/slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slots.d.ts","sourceRoot":"","sources":["../../../../src/domain/skill/transfer/slots.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAI5C,4DAA4D;AAC5D,qBAAa,gBAAiB,SAAQ,KAAK;;CAK1C;AAED,+DAA+D;AAC/D,qBAAa,iBAAkB,SAAQ,KAAK;;CAK3C;AAED,qEAAqE;AACrE,qBAAa,cAAe,SAAQ,KAAK;;CAKxC;AAED,2EAA2E;AAC3E,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAI/C;AAQD,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAEnC;;;;;;OAMG;gBAED,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAM,MAAiB;IAU9B;;;;;OAKG;IACH,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAc1D;;;;;;;OAOG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IA6CzD;;;;;OAKG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAuB/C;;;;OAIG;IACH,OAAO,CAAC,KAAK;IAUb;;;;;;OAMG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAInC;;;OAGG;IACH,OAAO,CAAC,SAAS;CAGlB"}

package/dist/domain/skill/transfer/slots.js

@@ -0,0 +1,216 @@
+/**
+ * Skill artifact upload slots — ports pkg/domain/skill/transfer/slots.go.
+ * The in-memory registry of single-use upload capabilities plus the
+ * staging directory their bytes land in (#675).
+ *
+ * In-memory is deliberate: the OSS server is single-instance (the same
+ * assumption the in-process router transport and SQLite store already
+ * make), and a slot is worthless across restarts anyway — its bytes live
+ * in the staging directory, which is swept on boot.
+ *
+ * Sentinel error classes replace Go's sentinel error values so the HTTP
+ * handler maps registry failures onto honest status codes without string
+ * matching; their message texts are Go's, verbatim (they ride wire-visible
+ * copy: push's "artifact_upload_ref not usable: %v" and the handler's 400
+ * body).
+ *
+ * Proven by __tests__/slots.test.ts (injected clock for expiry) and the
+ * conformance suite's transfer-lane tests.
+ */
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { pipeline } from "node:stream/promises";
+import { REF_BYTE_LEN, REF_PREFIX } from "../constants.js";
+/** Go errSlotUnknown — never existed, expired, or swept. */
+export class SlotUnknownError extends Error {
+    constructor() {
+        super("upload reference unknown or expired");
+        this.name = "SlotUnknownError";
+    }
+}
+/** Go errSlotConsumed — the slot already carries an upload. */
+export class SlotConsumedError extends Error {
+    constructor() {
+        super("upload reference already carries an upload");
+        this.name = "SlotConsumedError";
+    }
+}
+/** Go errSlotEmpty — minted but never (successfully) uploaded to. */
+export class SlotEmptyError extends Error {
+    constructor() {
+        super("upload reference has no uploaded bytes");
+        this.name = "SlotEmptyError";
+    }
+}
+/** Go errSizeMismatch — the body disagreed with the minted declaration. */
+export class SizeMismatchError extends Error {
+    constructor(received, declared) {
+        super(`upload size mismatch: received ${received} bytes, declared ${declared}`);
+        this.name = "SizeMismatchError";
+    }
+}
+export class UploadSlots {
+    slots = new Map();
+    stagingDir;
+    ttlMs;
+    maxSize;
+    /** Injectable for expiry tests, mirroring Go's `now` field. */
+    now;
+    /**
+     * Creates the registry and prepares the staging directory. Any file
+     * already present is an orphan from a previous process (the registry
+     * that knew about it died with that process), so the directory is
+     * emptied — this is also the crash-recovery story for uploads that
+     * never reached their push.
+     */
+    constructor(stagingDir, ttlMs, maxSize, now = Date.now) {
+        fs.rmSync(stagingDir, { recursive: true, force: true });
+        fs.mkdirSync(stagingDir, { recursive: true, mode: 0o700 });
+        this.stagingDir = stagingDir;
+        this.ttlMs = ttlMs;
+        this.maxSize = maxSize;
+        this.now = now;
+    }
+    /**
+     * Reserves an upload slot for an artifact of declaredSize bytes and
+     * returns its single-use reference + TTL. The caller has already
+     * authorized the request and validated declaredSize against the skill
+     * size limit; this guard is the registry's own invariant.
+     */
+    mint(declaredSize) {
+        if (declaredSize <= 0 || declaredSize > this.maxSize) {
+            throw new Error(`declared size ${declaredSize} outside (0, ${this.maxSize}]`);
+        }
+        const ref = REF_PREFIX + randomBytes(REF_BYTE_LEN).toString("hex");
+        this.sweep();
+        this.slots.set(ref, {
+            declaredSize,
+            expiresAtMs: this.now() + this.ttlMs,
+            uploaded: false,
+        });
+        return { ref, ttlMs: this.ttlMs };
+    }
+    /**
+     * Streams an upload's body into the slot's staging file. The body must
+     * match the size declared at mint time exactly: a shorter body means a
+     * truncated transfer, a longer one means the client lied — both reject
+     * rather than staging bytes that would fail (or worse, surprise)
+     * validation later. The staged file only becomes consumable once this
+     * resolves.
+     */
+    async receive(ref, body) {
+        const slot = this.slots.get(ref);
+        if (slot === undefined || this.now() > slot.expiresAtMs) {
+            throw new SlotUnknownError();
+        }
+        if (slot.uploaded) {
+            throw new SlotConsumedError();
+        }
+        const declared = slot.declaredSize;
+        const filePath = this.stagePath(ref);
+        let written = 0;
+        try {
+            // Consume at most declared+1 bytes: seeing the extra byte proves the
+            // body exceeds the declaration without buffering an unbounded stream
+            // (Go's io.LimitReader(declared+1) + written != declared check).
+            await pipeline(body, limitBytes(declared + 1, (n) => {
+                written += n;
+            }), fs.createWriteStream(filePath, { flags: "w", mode: 0o600 }));
+        }
+        catch (error) {
+            await fs.promises.rm(filePath, { force: true });
+            throw new Error(`failed to receive upload: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (written !== declared) {
+            await fs.promises.rm(filePath, { force: true });
+            throw new SizeMismatchError(written, declared);
+        }
+        // Re-check after the write: the slot may have expired mid-upload
+        // (Go re-checks under the lock for the same reason).
+        const current = this.slots.get(ref);
+        if (current === undefined || this.now() > current.expiresAtMs) {
+            await fs.promises.rm(filePath, { force: true });
+            throw new SlotUnknownError();
+        }
+        current.uploaded = true;
+    }
+    /**
+     * Returns the staged bytes for ref and retires the slot — an upload
+     * reference is strictly single-use. Push calls this when it sees
+     * artifact_upload_ref; whatever happens downstream (validation failure
+     * included), the slot is gone and the client must re-mint to retry.
+     */
+    async consume(ref) {
+        const slot = this.slots.get(ref);
+        if (slot === undefined || this.now() > slot.expiresAtMs) {
+            throw new SlotUnknownError();
+        }
+        if (!slot.uploaded) {
+            throw new SlotEmptyError();
+        }
+        this.slots.delete(ref);
+        const filePath = this.stagePath(ref);
+        try {
+            const data = await fs.promises.readFile(filePath);
+            return data;
+        }
+        catch (error) {
+            throw new Error(`failed to read staged artifact: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            await fs.promises.rm(filePath, { force: true });
+        }
+    }
+    /**
+     * Drops expired slots and their staged files. Called from mint, which
+     * bounds the registry: it can hold at most the slots minted within one
+     * TTL window.
+     */
+    sweep() {
+        const nowMs = this.now();
+        for (const [ref, slot] of this.slots) {
+            if (nowMs > slot.expiresAtMs) {
+                this.slots.delete(ref);
+                fs.rmSync(this.stagePath(ref), { force: true });
+            }
+        }
+    }
+    /**
+     * The staging file name for a reference. Public since O5: the local
+     * driver's presigned-PUT arm maps refs onto driver staging keys
+     * (boot/compose.ts), and that mapping must come from HERE — a
+     * re-declared "<ref>.zip" in the composition would drift from stagePath
+     * with nothing to catch it.
+     */
+    stagedFileName(ref) {
+        return `${ref}.zip`;
+    }
+    /**
+     * Maps a reference to its staging file. refs are server-generated hex
+     * (never client-supplied paths), so simple joining is safe.
+     */
+    stagePath(ref) {
+        return path.join(this.stagingDir, this.stagedFileName(ref));
+    }
+}
+/**
+ * A byte-capped pass-through: forwards up to `limit` bytes (counting via
+ * onBytes) and then stops consuming — the TS analogue of piping through
+ * io.LimitReader.
+ */
+function limitBytes(limit, onBytes) {
+    return async function* (source) {
+        let remaining = limit;
+        for await (const chunk of source) {
+            if (remaining <= 0) {
+                return;
+            }
+            const slice = chunk.length <= remaining ? chunk : chunk.subarray(0, remaining);
+            remaining -= slice.length;
+            onBytes(slice.length);
+            yield slice;
+        }
+    };
+}
+//# sourceMappingURL=slots.js.map