@stigmer/server 3.15.3-dev.20260914121148 → 3.16.0

package/src/archive/__tests__/archive.test.ts

@@ -0,0 +1,233 @@
+/**
+ * Pins the shared archive plumbing on its own, apart from the skill gate
+ * that composes it: the structural walk's sentences and their order, the
+ * capped inflate's typed outcomes, the writer's determinism (the same
+ * files twice are byte-equal, entry order is irrelevant, the result reads
+ * back through the server's own reader), and the content-addressed
+ * store's key shape and traversal collapse under a second prefix. The
+ * skill gate's zip-gate.test.ts proves the composition keeps its pinned
+ * copy; this file proves the pieces a plugin builds on.
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { parseZipStructure } from "@stigmer/zip-structure";
+import { buildZip } from "@stigmer/zip-structure/testing";
+
+import { LocalArtifactStorage } from "../../artifactstorage/artifact-storage.js";
+import {
+  ArtifactNotFoundError,
+  newContentAddressedArchiveStore,
+} from "../content-store.js";
+import { InflateError, inflateEntry } from "../inflate.js";
+import { PLATFORM_ARCHIVE_LIMITS } from "../limits.js";
+import {
+  calculateHash,
+  openArchive,
+  validateArchiveStructure,
+} from "../open.js";
+import { writeArchive } from "../write.js";
+
+const encoder = new TextEncoder();
+
+describe("openArchive", () => {
+  it("hashes the bytes and pre-filters the entries", () => {
+    const zip = buildZip([{ name: "./a/../plugin.json", content: "{}" }]);
+    const opened = openArchive(zip);
+    expect(opened.hash).toBe(calculateHash(zip));
+    expect(opened.entries.map((e) => e.name)).toEqual(["plugin.json"]);
+  });
+
+  it("refuses an over-limit archive before parsing, naming the limit", () => {
+    expect(() => openArchive(new Uint8Array(11), 10)).toThrow(
+      "ZIP file too large: 11 bytes (max: 10)",
+    );
+  });
+
+  it("refuses bytes that are not a zip with the stdlib text", () => {
+    expect(() => openArchive(encoder.encode("not a zip"))).toThrow(
+      "invalid ZIP file: zip: not a valid zip file",
+    );
+  });
+});
+
+describe("validateArchiveStructure", () => {
+  it("refuses an empty archive first", () => {
+    expect(() => validateArchiveStructure([], PLATFORM_ARCHIVE_LIMITS)).toThrow(
+      "ZIP file is empty",
+    );
+  });
+
+  it("refuses too many files, then a control character, then the budget", () => {
+    const one = openArchive(buildZip([{ name: "a", content: "x" }])).entries;
+    expect(() =>
+      validateArchiveStructure(one, {
+        ...PLATFORM_ARCHIVE_LIMITS,
+        maxFiles: 0,
+      }),
+    ).toThrow("too many files in ZIP: 1 (max: 0)");
+
+    const control = openArchive(
+      buildZip([{ name: "bad\u0001name", content: "x" }]),
+    ).entries;
+    expect(() =>
+      validateArchiveStructure(control, PLATFORM_ARCHIVE_LIMITS),
+    ).toThrow("invalid character in filename: bad\u0001name");
+
+    const big = openArchive(
+      buildZip([{ name: "a", content: "x".repeat(64) }]),
+    ).entries;
+    expect(() =>
+      validateArchiveStructure(big, {
+        ...PLATFORM_ARCHIVE_LIMITS,
+        maxUncompressedSize: 10,
+      }),
+    ).toThrow("total uncompressed size too large: 64 bytes (max: 10)");
+  });
+
+  it("hands every sanitised name to the observer in order", () => {
+    const entries = openArchive(
+      buildZip([
+        { name: "skills/x/SKILL.md", content: "---\nname: x\n---" },
+        { name: "plugin.json", content: "{}" },
+      ]),
+    ).entries;
+    const seen: string[] = [];
+    validateArchiveStructure(entries, PLATFORM_ARCHIVE_LIMITS, (name) =>
+      seen.push(name),
+    );
+    expect(seen).toEqual(["skills/x/SKILL.md", "plugin.json"]);
+  });
+});
+
+describe("inflateEntry", () => {
+  it("returns stored and deflated payloads under the cap", () => {
+    const zip = buildZip([
+      { name: "s", content: "stored" },
+      { name: "d", content: "deflated".repeat(20), method: "deflated" },
+    ]);
+    const [stored, deflated] = parseZipStructure(zip);
+    expect(new TextDecoder().decode(inflateEntry(stored!, 1024))).toBe(
+      "stored",
+    );
+    expect(new TextDecoder().decode(inflateEntry(deflated!, 1024))).toBe(
+      "deflated".repeat(20),
+    );
+  });
+
+  it("refuses output past the cap as too-large, judged on the real bytes", () => {
+    const zip = buildZip([
+      { name: "d", content: "a".repeat(4096), method: "deflated" },
+    ]);
+    const [entry] = parseZipStructure(zip);
+    let failure: InflateError | undefined;
+    try {
+      inflateEntry(entry!, 100);
+    } catch (error) {
+      failure = error instanceof InflateError ? error : undefined;
+    }
+    expect(failure?.kind).toBe("too-large");
+  });
+
+  it("refuses a corrupt payload as a checksum failure", () => {
+    const zip = buildZip([{ name: "s", content: "hello" }]);
+    const [entry] = parseZipStructure(zip);
+    const corrupted = { ...entry!, compressedData: encoder.encode("jello") };
+    let failure: InflateError | undefined;
+    try {
+      inflateEntry(corrupted, 1024);
+    } catch (error) {
+      failure = error instanceof InflateError ? error : undefined;
+    }
+    expect(failure?.kind).toBe("checksum");
+    expect(failure?.detail).toBe("zip: checksum error");
+  });
+
+  it("refuses a compression method the platform does not register", () => {
+    const zip = buildZip([{ name: "s", content: "hello" }]);
+    const [entry] = parseZipStructure(zip);
+    const bzip2 = { ...entry!, compressionMethod: 12 };
+    expect(() => inflateEntry(bzip2, 1024)).toThrow(
+      "unsupported-method: zip: unsupported compression algorithm",
+    );
+  });
+});
+
+describe("writeArchive", () => {
+  const files = [
+    {
+      path: "skills/x/SKILL.md",
+      bytes: encoder.encode("---\nname: x\n---\nbody"),
+    },
+    { path: "plugin.json", bytes: encoder.encode('{"name":"x"}') },
+  ];
+
+  it("is byte-deterministic and independent of entry order", () => {
+    const first = writeArchive(files);
+    const second = writeArchive([...files].reverse());
+    expect(Buffer.from(first).equals(Buffer.from(second))).toBe(true);
+    expect(calculateHash(first)).toBe(calculateHash(second));
+  });
+
+  it("round-trips through the server's own reader", () => {
+    const opened = openArchive(writeArchive(files));
+    expect(opened.entries.map((e) => e.name)).toEqual([
+      "plugin.json",
+      "skills/x/SKILL.md",
+    ]);
+    const skill = opened.entries.find((e) => e.name === "skills/x/SKILL.md")!;
+    expect(new TextDecoder().decode(inflateEntry(skill.entry, 1024))).toBe(
+      "---\nname: x\n---\nbody",
+    );
+  });
+
+  it("refuses a path listed twice", () => {
+    expect(() => writeArchive([files[0]!, files[0]!])).toThrow(
+      "archive path 'skills/x/SKILL.md' listed twice",
+    );
+  });
+});
+
+describe("newContentAddressedArchiveStore", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(path.join(tmpdir(), "archive-store-test-"));
+  });
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("keys under its prefix and round-trips bytes", async () => {
+    const store = newContentAddressedArchiveStore(
+      new LocalArtifactStorage(dir, ""),
+      "plugins/",
+    );
+    const hash = "a".repeat(64);
+    expect(store.getStorageKey(hash)).toBe(`plugins/${hash}.zip`);
+    expect(await store.exists(hash)).toBe(false);
+    const key = await store.store(hash, encoder.encode("zip"));
+    expect(key).toBe(`plugins/${hash}.zip`);
+    expect(await store.exists(hash)).toBe(true);
+    expect(new TextDecoder().decode(await store.get(key))).toBe("zip");
+    expect(await store.size(key)).toBe(3);
+  });
+
+  it("collapses a traversal-shaped key and a missing key to one not-found", async () => {
+    const store = newContentAddressedArchiveStore(
+      new LocalArtifactStorage(dir, ""),
+      "plugins/",
+    );
+    await expect(store.get("../../etc/passwd")).rejects.toBeInstanceOf(
+      ArtifactNotFoundError,
+    );
+    await expect(store.get("plugins/missing.zip")).rejects.toBeInstanceOf(
+      ArtifactNotFoundError,
+    );
+    await expect(store.size("../x")).rejects.toThrow(
+      "artifact not found: ../x",
+    );
+  });
+});

package/src/{domain/skill → archive}/__tests__/prefilter.test.ts

@@ -15,7 +15,7 @@ import {
   entryTypeBits,
   hasWindowsShortFilenames,
   sanitizePath,
-} from "../storage/prefilter.js";
+} from "../prefilter.js";
 
 // versionMadeBy high byte 3 = Unix creator; POSIX mode rides the attribute
 // high 16 bits (how zip writers encode symlinks and special files).

package/src/archive/content-store.ts

@@ -0,0 +1,132 @@
+/**
+ * The content-addressed archive store — a domain port over the one
+ * ArtifactStorage blob driver: keys are `<prefix><sha256>.zip`, writes are
+ * once and never garbage-collected (historical versions stay downloadable
+ * through the keys a version history exposes), and a key that addresses
+ * nothing inside the store collapses to one not-found before the driver
+ * sees it. Skills shipped this shape first
+ * (pkg/domain/skill/storage/artifact_storage.go, then the TS port under
+ * domain/skill/storage); plugins need the identical port under another
+ * prefix, so the implementation lives here and each domain names its
+ * instance (`skills/`, `plugins/`).
+ *
+ * Why the traversal guard is the port's, not the driver's: a
+ * client-supplied storage key that resolves outside the store must read
+ * exactly like a missing file — the driver's own containment refusal is a
+ * distinguishable error, and distinguishing them would tell a probing
+ * caller which escapes exist. Lexical, against a fixed virtual root, so
+ * the judgment is identical on every backend.
+ *
+ * Key shape: a LITERAL forward-slash join, never path.join — the key is a
+ * wire-visible identifier (status.artifact_storage_key, download URLs, the
+ * lane's prefix check) and Windows support arrives only through this server
+ * (#24); path.join would mint backslash keys there.
+ *
+ * Proven by the skill store's __tests__/artifact-storage.test.ts (the
+ * `skills/` instance) and by __tests__/content-store.test.ts.
+ */
+import path from "node:path";
+
+import type { ArtifactStorage } from "../artifactstorage/artifact-storage.js";
+import { ArtifactStorageNotFoundError } from "../artifactstorage/artifact-storage.js";
+
+/**
+ * Storage abstraction for content-addressed archives. The interface exists
+ * for the same reason Go's did: the cloud edition uses R2 behind the
+ * identical surface, and a controller must not know which one it holds.
+ */
+export interface ContentAddressedArchiveStore {
+  /** Saves an archive under its content hash; returns the storage key. */
+  store(hash: string, data: Uint8Array): Promise<string>;
+  /** Loads an archive by storage key; throws ArtifactNotFoundError if absent. */
+  get(storageKey: string): Promise<Uint8Array>;
+  /** Whether an archive with this content hash already exists (dedupe). */
+  exists(hash: string): Promise<boolean>;
+  /** The storage key for a hash, without storing ("<prefix><hash>.zip"). */
+  getStorageKey(hash: string): string;
+  /** The stored archive's byte size via stat — never loads content. */
+  size(storageKey: string): Promise<number>;
+}
+
+/**
+ * A storage key that addresses nothing inside the store — missing file OR
+ * a traversal-shaped key (both render as Go's "artifact not found: %s").
+ */
+export class ArtifactNotFoundError extends Error {
+  constructor(storageKey: string) {
+    super(`artifact not found: ${storageKey}`);
+    this.name = "ArtifactNotFoundError";
+  }
+}
+
+/** Archives are zip files; the driver stores the honest type. */
+const ARCHIVE_CONTENT_TYPE = "application/zip";
+
+/**
+ * The store over a blob driver. Object-literal factory rather than a class:
+ * all state is the captured driver and prefix, and the seam-adapter shape
+ * matches runner-credential-provider.ts (the house style for ports).
+ *
+ * `keyPrefix` ends with a slash (`skills/`); it is also the download lane's
+ * containment prefix, so the two agree by construction.
+ */
+export function newContentAddressedArchiveStore(
+  driver: ArtifactStorage,
+  keyPrefix: string,
+): ContentAddressedArchiveStore {
+  const virtualRoot = path.resolve(path.sep, "archive-store");
+  const keyEscapesStore = (storageKey: string): boolean => {
+    const resolved = path.resolve(virtualRoot, storageKey);
+    return (
+      resolved !== virtualRoot && !resolved.startsWith(virtualRoot + path.sep)
+    );
+  };
+
+  return {
+    getStorageKey(hash: string): string {
+      return `${keyPrefix}${hash}.zip`;
+    },
+
+    async store(hash: string, data: Uint8Array): Promise<string> {
+      const storageKey = this.getStorageKey(hash);
+      await driver.upload(storageKey, data, ARCHIVE_CONTENT_TYPE);
+      return storageKey;
+    },
+
+    async get(storageKey: string): Promise<Uint8Array> {
+      if (keyEscapesStore(storageKey)) {
+        throw new ArtifactNotFoundError(storageKey);
+      }
+      try {
+        return await driver.download(storageKey);
+      } catch (error) {
+        if (error instanceof ArtifactStorageNotFoundError) {
+          throw new ArtifactNotFoundError(storageKey);
+        }
+        throw new Error(
+          `failed to read artifact: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    },
+
+    async exists(hash: string): Promise<boolean> {
+      return driver.exists(this.getStorageKey(hash));
+    },
+
+    async size(storageKey: string): Promise<number> {
+      if (keyEscapesStore(storageKey)) {
+        throw new ArtifactNotFoundError(storageKey);
+      }
+      try {
+        return await driver.size(storageKey);
+      } catch (error) {
+        if (error instanceof ArtifactStorageNotFoundError) {
+          throw new ArtifactNotFoundError(storageKey);
+        }
+        throw new Error(
+          `failed to stat artifact: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    },
+  };
+}

package/src/archive/inflate.ts

@@ -0,0 +1,107 @@
+/**
+ * Reading one archive entry under a real cap. Declared sizes are client
+ * claims, so every gate that opens an entry bounds the ACTUAL inflated
+ * output (`maxOutputLength`), verifies the CRC the way Go's checksumReader
+ * does on every read, and opens only the two methods the platform
+ * registers (stored, deflated). The skill gate did this for SKILL.md alone;
+ * a plugin reads many documents through the same discipline, so the read
+ * lives here and each kind keeps its own sentences: the outcome is a typed
+ * failure, never prose, because the skill's copy is byte-pinned wire
+ * contract and a plugin's names a different document.
+ *
+ * Proven by __tests__/inflate.test.ts and, through composition, by the
+ * skill gate's zip-gate.test.ts.
+ */
+import { inflateRawSync } from "node:zlib";
+
+import { crc32 } from "@stigmer/zip-structure";
+import type { ZipStructuralEntry } from "@stigmer/zip-structure";
+
+/** ZIP compression methods the gate can open (Go registers the same two). */
+const METHOD_STORED = 0;
+const METHOD_DEFLATED = 8;
+
+export type InflateFailureKind =
+  /** The inflated output passed `maxSize`. */
+  | "too-large"
+  /** zlib refused the payload; `detail` carries its message. */
+  | "read-failed"
+  /** A compression method neither Go nor this gate registers. */
+  | "unsupported-method"
+  /** The inflated bytes do not match the entry's CRC. */
+  | "checksum";
+
+/** A typed refusal; the kind that called maps it to its pinned sentence. */
+export class InflateError extends Error {
+  constructor(
+    readonly kind: InflateFailureKind,
+    readonly detail: string,
+  ) {
+    super(`${kind}: ${detail}`);
+    this.name = "InflateError";
+  }
+}
+
+/**
+ * Inflates one entry to at most `maxSize` bytes and verifies its CRC.
+ * The cap bounds the actual output, not the declaration.
+ */
+export function inflateEntry(
+  entry: ZipStructuralEntry,
+  maxSize: number,
+): Uint8Array {
+  let content: Uint8Array;
+  switch (entry.compressionMethod) {
+    case METHOD_STORED:
+      content = entry.compressedData;
+      break;
+    case METHOD_DEFLATED:
+      try {
+        content = new Uint8Array(
+          inflateRawSync(entry.compressedData, {
+            maxOutputLength: maxSize + 1,
+          }),
+        );
+      } catch (error) {
+        if (isOutputLengthError(error)) {
+          throw new InflateError(
+            "too-large",
+            `output exceeds ${maxSize} bytes`,
+          );
+        }
+        throw new InflateError(
+          "read-failed",
+          error instanceof Error ? error.message : String(error),
+        );
+      }
+      break;
+    default:
+      // Go: File.Open returns ErrAlgorithm for methods without a registered
+      // decompressor; each kind pins the text via its own %w-shaped arm.
+      throw new InflateError(
+        "unsupported-method",
+        "zip: unsupported compression algorithm",
+      );
+  }
+
+  if (content.length > maxSize) {
+    throw new InflateError("too-large", `output exceeds ${maxSize} bytes`);
+  }
+
+  if (crc32(content) !== entry.crc32) {
+    // Go's checksumReader: stdlib ErrChecksum via the read-error arm.
+    throw new InflateError("checksum", "zip: checksum error");
+  }
+
+  return content;
+}
+
+/** node:zlib's maxOutputLength violation (the output-cap arm). */
+function isOutputLengthError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    (("code" in error &&
+      (error as { code?: string }).code === "ERR_BUFFER_TOO_LARGE") ||
+      error.message.includes("maxOutputLength"))
+  );
+}

package/src/archive/limits.ts

@@ -0,0 +1,42 @@
+/**
+ * The platform's archive limits — one home for every ZIP-bomb budget the
+ * server applies to a pushed archive, whichever kind it becomes. Skills
+ * carried these alone until plugins arrived (also pushed as a ZIP); the
+ * values stay byte-pinned to the retired Go gate's (pkg/domain/skill/storage/
+ * zip_extractor.go), because every sentence quoting them is wire contract
+ * and the transfer lane refuses over-limit declarations by them before a
+ * byte moves.
+ *
+ * A per-kind cap that is NOT an archive budget (the 1 MB SKILL.md
+ * extraction cap) stays with its kind: it bounds one document, not the
+ * archive.
+ */
+
+/**
+ * The compressed-archive ceiling. The platform's artifact size limit, not
+ * just an extraction guard: createArtifactUploadUrl enforces it before any
+ * bytes move and clients quote it in fail-loud size errors (#675).
+ */
+export const MAX_ZIP_SIZE = 100 * 1024 * 1024;
+
+/** Total declared-uncompressed budget across all entries (ZIP-bomb guard). */
+export const MAX_UNCOMPRESSED_SIZE = 500 * 1024 * 1024;
+
+/** Per-file declared compression ratio ceiling (ZIP-bomb guard). */
+export const MAX_COMPRESSION_RATIO = 100;
+
+/** Entry-count ceiling. */
+export const MAX_FILES = 10_000;
+
+/** The budgets `validateArchiveStructure` applies; the platform's by default. */
+export interface ArchiveLimits {
+  readonly maxFiles: number;
+  readonly maxUncompressedSize: number;
+  readonly maxCompressionRatio: number;
+}
+
+export const PLATFORM_ARCHIVE_LIMITS: ArchiveLimits = {
+  maxFiles: MAX_FILES,
+  maxUncompressedSize: MAX_UNCOMPRESSED_SIZE,
+  maxCompressionRatio: MAX_COMPRESSION_RATIO,
+};

package/src/archive/open.ts

@@ -0,0 +1,131 @@
+/**
+ * Opening a pushed archive — the kind-agnostic half of the ZIP gate every
+ * archive-shaped push runs (skills, plugins). Two steps, both pure over the
+ * bytes: `openArchive` bounds the compressed size, hashes the bytes (the
+ * content-addressed version identity), parses the central directory and
+ * applies the safearchive prefilter; `validateArchiveStructure` walks the
+ * pre-filtered entries in the retired Go gate's exact order (empty
+ * archive, file count, then per entry the filename control-character rule,
+ * the running declared-uncompressed budget and the per-file ratio cap).
+ *
+ * What a KIND requires of the entries (a root SKILL.md, a plugin manifest)
+ * is not here: the walk accepts an `onEntry` observer so a kind tracks what
+ * it needs in the same pass and rules on it afterwards, which keeps the
+ * observable error order the skill gate's tests pin.
+ *
+ * Error text is wire-visible contract: the sentences below are the Go
+ * gate's verbatim, wrapped by each kind's push step into its own
+ * InvalidArgument arm. Only declared sizes are judged here; inflating an
+ * entry under a real cap is `inflate.ts`'s job.
+ *
+ * Proven by the skill gate's __tests__/zip-gate.test.ts (which composes
+ * these) and by __tests__/open.test.ts for the plugin-shaped path.
+ */
+import { createHash } from "node:crypto";
+
+import { parseZipStructure } from "@stigmer/zip-structure";
+import type { ZipStructuralEntry } from "@stigmer/zip-structure";
+
+import type { ArchiveLimits } from "./limits.js";
+import { MAX_ZIP_SIZE } from "./limits.js";
+import { applyEntryPrefilter } from "./prefilter.js";
+import type { PrefilteredEntry } from "./prefilter.js";
+
+/** A parsed, pre-filtered archive with its content-addressed identity. */
+export interface OpenedArchive {
+  /** SHA-256 hex of the archive bytes. */
+  readonly hash: string;
+  /** The entries a kind may read, names sanitised, shadows dropped. */
+  readonly entries: readonly PrefilteredEntry[];
+}
+
+/**
+ * Bounds, hashes, parses and pre-filters. Throws plain Errors with
+ * byte-pinned messages; the caller owns the gRPC code.
+ */
+export function openArchive(
+  bytes: Uint8Array,
+  maxZipSize: number = MAX_ZIP_SIZE,
+): OpenedArchive {
+  if (bytes.length > maxZipSize) {
+    throw new Error(
+      `ZIP file too large: ${bytes.length} bytes (max: ${maxZipSize})`,
+    );
+  }
+
+  const hash = calculateHash(bytes);
+
+  let entries: readonly ZipStructuralEntry[];
+  try {
+    entries = parseZipStructure(bytes);
+  } 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 — sanitized names, shadowed/special/8.3 entries
+  // dropped.
+  return { hash, entries: applyEntryPrefilter(entries) };
+}
+
+/**
+ * The structural walk: empty archive, file-count cap, then per entry the
+ * control-character rule, the running declared-uncompressed budget
+ * (fail-fast) and the per-file compression-ratio cap. `onEntry` sees each
+ * sanitised name in order so a kind can track its own requirements.
+ */
+export function validateArchiveStructure(
+  entries: readonly PrefilteredEntry[],
+  limits: ArchiveLimits,
+  onEntry?: (name: string) => void,
+): void {
+  if (entries.length === 0) {
+    throw new Error("ZIP file is empty");
+  }
+
+  if (entries.length > limits.maxFiles) {
+    throw new Error(
+      `too many files in ZIP: ${entries.length} (max: ${limits.maxFiles})`,
+    );
+  }
+
+  let totalUncompressedSize = 0;
+
+  for (const { name, entry } of entries) {
+    onEntry?.(name);
+
+    // 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 > limits.maxUncompressedSize) {
+      throw new Error(
+        `total uncompressed size too large: ${totalUncompressedSize} bytes (max: ${limits.maxUncompressedSize})`,
+      );
+    }
+
+    // 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 > limits.maxCompressionRatio) {
+        throw new Error(
+          `suspicious compression ratio in ${name}: ${ratio}:1 (max: ${limits.maxCompressionRatio}:1)`,
+        );
+      }
+    }
+  }
+}
+
+/** SHA-256 hex of the archive bytes (Go CalculateHash). */
+export function calculateHash(data: Uint8Array): string {
+  return createHash("sha256").update(data).digest("hex");
+}

package/src/{domain/skill/storage → archive}/prefilter.ts

@@ -28,6 +28,11 @@
  * bits; FAT/NTFS/VFAT creators carry MSDOS bits that can never encode a
  * symlink or special file; unknown creators decode to a regular file.
  *
+ * Shared by every archive gate the server runs (skills, plugins): the
+ * filter describes what an archive IS before any kind reads it, so it
+ * lives with the archive plumbing rather than with the first kind that
+ * needed it.
+ *
  * Proven by __tests__/prefilter.test.ts (byte-crafted fixtures per DD-001).
  */
 import type { ZipStructuralEntry } from "@stigmer/zip-structure";