@stigmer/server 3.15.3-dev.20260914121148 → 3.16.0

package/src/domain/skill/storage/artifact-storage.ts

@@ -1,139 +1,38 @@
 /**
- * Skill artifact store — ports pkg/domain/skill/storage/artifact_storage.go.
- * Content-addressed, write-once, never garbage-collected (OD-5): artifacts
- * live at {storagePath}/skills/{sha256}.zip, byte-identical to Go's paths —
- * at cutover the TS server inherits a Go-written storage directory and must
- * serve its artifacts in place. There is deliberately NO delete method on
- * the interface: historical versions stay downloadable through the storage
- * keys listVersions exposes.
+ * Skill artifact store — the `skills/` instance of the content-addressed
+ * archive store (src/archive/content-store.ts). Artifacts live at
+ * {storagePath}/skills/{sha256}.zip, byte-identical to the retired Go
+ * server's paths: at cutover the TS server inherited a Go-written storage
+ * directory and serves its artifacts in place. Write-once, never
+ * garbage-collected (OD-5): there is deliberately NO delete method, so the
+ * storage keys listVersions exposes stay downloadable.
  *
- * Since O5 (20260827.02, blueprint 03 §6b) this is a DOMAIN PORT layered
- * over the one ArtifactStorage blob driver (the Q2 gate ruling): the
- * driver stores blobs; this module owns the keys, the write-once posture,
- * and the not-found vocabulary. The compose root hands it a PER-DOMAIN
- * driver instance rooted at storagePath (the Q2b ruling) — skill artifacts
- * never silently follow the generic artifact store's backend selection.
+ * Since O5 (20260827.02, blueprint 03 §6b) this is a DOMAIN PORT over the
+ * one ArtifactStorage blob driver (the Q2 gate ruling); the compose root
+ * hands it a PER-DOMAIN driver instance rooted at storagePath (Q2b), so
+ * skill artifacts never silently follow the generic artifact store's
+ * backend selection. The port's implementation moved to src/archive when
+ * plugins needed the identical shape under `plugins/`; the names exported
+ * here are the skill domain's and every consumer keeps them.
  *
  * Proven by __tests__/artifact-storage.test.ts and the skill conformance
  * suite's getArtifact/round-trip tests.
  */
-import path from "node:path";
-
 import type { ArtifactStorage } from "../../../artifactstorage/artifact-storage.js";
-import { ArtifactStorageNotFoundError } from "../../../artifactstorage/artifact-storage.js";
+import type { ContentAddressedArchiveStore } from "../../../archive/content-store.js";
+import { newContentAddressedArchiveStore } from "../../../archive/content-store.js";
 
-/**
- * Storage abstraction for skill artifacts (Go ArtifactStorage). The
- * interface exists for the same reason as Go's: cloud uses R2 behind the
- * identical surface, and the controller must not know which one it holds.
- */
-export interface SkillArtifactStorage {
-  /** Saves an artifact under its content hash; returns the storage key. */
-  store(hash: string, data: Uint8Array): Promise<string>;
-  /** Loads an artifact by storage key; throws ArtifactNotFoundError if absent. */
-  get(storageKey: string): Promise<Uint8Array>;
-  /** Whether an artifact with this content hash already exists (dedupe). */
-  exists(hash: string): Promise<boolean>;
-  /** The storage key for a hash, without storing ("skills/<hash>.zip"). */
-  getStorageKey(hash: string): string;
-  /** The stored artifact's byte size via stat — never loads content. */
-  size(storageKey: string): Promise<number>;
-}
+export { ArtifactNotFoundError } from "../../../archive/content-store.js";
 
-/**
- * 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";
- * distinguishing them would tell a probing caller which escapes exist).
- */
-export class ArtifactNotFoundError extends Error {
-  constructor(storageKey: string) {
-    super(`artifact not found: ${storageKey}`);
-    this.name = "ArtifactNotFoundError";
-  }
-}
+/** Storage abstraction for skill artifacts (Go ArtifactStorage). */
+export type SkillArtifactStorage = ContentAddressedArchiveStore;
 
-/** Skill artifacts are zip archives; the driver stores the honest type. */
-const SKILL_ARTIFACT_CONTENT_TYPE = "application/zip";
+/** The key prefix shared with cloud R2 and the download lane's containment check. */
+export const SKILL_ARTIFACT_KEY_PREFIX = "skills/";
 
-/**
- * The skill store over a blob driver. Object-literal factory rather than a
- * class: all state is the captured driver, and the seam-adapter shape
- * matches runner-credential-provider.ts (the O5 house style for ports).
- */
+/** The skill store over a blob driver: "skills/<hash>.zip". */
 export function newSkillArtifactStorage(
   driver: ArtifactStorage,
 ): SkillArtifactStorage {
-  return {
-    /**
-     * "skills/<hash>.zip" — the relative key format shared with cloud R2.
-     * Deliberately a LITERAL forward-slash join, not path.join: the key is
-     * a wire-visible identifier (status.artifact_storage_key, download
-     * URLs, the lane's "skills/" prefix check), and Windows support
-     * arrives only through this server (#24) — path.join would mint
-     * backslash keys there that the download lane could never serve.
-     */
-    getStorageKey(hash: string): string {
-      return `skills/${hash}.zip`;
-    },
-
-    async store(hash: string, data: Uint8Array): Promise<string> {
-      const storageKey = this.getStorageKey(hash);
-      await driver.upload(storageKey, data, SKILL_ARTIFACT_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)}`,
-        );
-      }
-    },
-  };
-}
-
-/**
- * The domain's own traversal guard (Go resolveWithinRoot, kept HERE per
- * "the domain owns keys"): a client-supplied storage key that resolves
- * outside the store addresses nothing inside it, and must collapse to the
- * same not-found as a missing file BEFORE the driver sees it — 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 rather than an accident of the local driver's directory.
- */
-function keyEscapesStore(storageKey: string): boolean {
-  const virtualRoot = path.resolve(path.sep, "skill-store");
-  const resolved = path.resolve(virtualRoot, storageKey);
-  return (
-    resolved !== virtualRoot && !resolved.startsWith(virtualRoot + path.sep)
-  );
+  return newContentAddressedArchiveStore(driver, SKILL_ARTIFACT_KEY_PREFIX);
 }

package/src/domain/skill/storage/zip-gate.ts

@@ -3,10 +3,15 @@
  * 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.
+ * its frontmatter.
+ *
+ * The kind-agnostic half (open, hash, prefilter, structural walk, capped
+ * inflate with CRC) is src/archive's, shared with the plugin gate since
+ * plugins are pushed as archives too; this module composes it and owns
+ * what is a SKILL's: the root-SKILL.md rule, the 1 MB document cap, the
+ * frontmatter parse, and every sentence below. The observable error order
+ * is the Go gate's exactly: the structural walk tracks SKILL.md placement
+ * in the same pass it validates, and rules on presence last.
  *
  * Error strings are wire-visible contract (the push pipeline wraps them
  * into the InvalidArgument "failed to extract SKILL.md: ..." arm), pinned
@@ -21,24 +26,22 @@
  * 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 type { ZipStructuralEntry } from "@stigmer/zip-structure";
-
+import { InflateError, inflateEntry } from "../../../archive/inflate.js";
+import { PLATFORM_ARCHIVE_LIMITS } from "../../../archive/limits.js";
+import {
+  openArchive,
+  validateArchiveStructure,
+} from "../../../archive/open.js";
+import type { PrefilteredEntry } from "../../../archive/prefilter.js";
 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 type { PrefilteredEntry } from "./prefilter.js";
 import { parseFrontmatter } from "./frontmatter.js";
 
+export { calculateHash } from "../../../archive/open.js";
+
 /** Result of a successful gate pass (Go ExtractSkillMdResult). */
 export interface ExtractSkillMdResult {
   /** Full SKILL.md content, frontmatter included. */
@@ -51,41 +54,35 @@ export interface ExtractSkillMdResult {
   readonly description: string;
 }
 
-/** 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: Uint8Array): ExtractSkillMdResult {
-  if (zipData.length > MAX_ZIP_SIZE) {
-    throw new Error(
-      `ZIP file too large: ${zipData.length} bytes (max: ${MAX_ZIP_SIZE})`,
-    );
-  }
+  const { hash, entries } = openArchive(zipData, MAX_ZIP_SIZE);
 
-  const hash = calculateHash(zipData);
+  // SKILL.md must be at the archive root. Nested occurrences are tracked
+  // only to make the rejection actionable (the #452 hint), in the same
+  // pass the structural checks run so their precedence stays Go's.
+  let hasSkillMd = false;
+  let hasNestedSkillMd = false;
+  validateArchiveStructure(entries, PLATFORM_ARCHIVE_LIMITS, (name) => {
+    if (name === "SKILL.md") {
+      hasSkillMd = true;
+    } else if (name.endsWith("/SKILL.md")) {
+      hasNestedSkillMd = true;
+    }
+  });
 
-  let entries: readonly ZipStructuralEntry[];
-  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");
+  if (!hasSkillMd) {
+    if (hasNestedSkillMd) {
+      throw new Error(NESTED_SKILL_MD_HINT);
+    }
+    throw new Error("SKILL.md not found in ZIP archive");
   }
 
-  // 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);
+  const content = extractSkillMdContent(entries);
 
   let frontmatter;
   try {
@@ -104,76 +101,10 @@ export function extractSkillMd(zipData: Uint8Array): ExtractSkillMdResult {
   };
 }
 
-/**
- * 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: readonly PrefilteredEntry[]): void {
-  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.
+ * first root-named entry, decompressed under the 1MB cap, CRC-verified,
+ * UTF-8 decoded. The typed inflate outcome maps to Go's sentences here.
  */
 function extractSkillMdContent(entries: readonly PrefilteredEntry[]): string {
   for (const { name, entry } of entries) {
@@ -182,41 +113,28 @@ function extractSkillMdContent(entries: readonly PrefilteredEntry[]): string {
     }
 
     let contentBytes: Uint8Array;
-    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)`);
-          }
+    try {
+      contentBytes = inflateEntry(entry, MAX_SKILL_MD_SIZE);
+    } catch (error) {
+      if (!(error instanceof InflateError)) {
+        throw error;
+      }
+      switch (error.kind) {
+        case "too-large":
           throw new Error(
-            `failed to read SKILL.md: ${error instanceof Error ? error.message : String(error)}`,
+            `SKILL.md too large (max: ${MAX_SKILL_MD_SIZE} bytes)`,
           );
+        case "read-failed":
+          throw new Error(`failed to read SKILL.md: ${error.detail}`);
+        case "unsupported-method":
+          throw new Error(`failed to open SKILL.md: ${error.detail}`);
+        case "checksum":
+          throw new Error(`failed to read SKILL.md: ${error.detail}`);
+        default: {
+          const exhaustive: never = error.kind;
+          throw new Error(`unknown inflate failure ${String(exhaustive)}`);
         }
-        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) {
@@ -228,17 +146,3 @@ function extractSkillMdContent(entries: readonly PrefilteredEntry[]): string {
 
   throw new Error("SKILL.md not found in ZIP archive");
 }
-
-/** 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"))
-  );
-}
-
-/** SHA-256 hex of the artifact bytes (Go CalculateHash). */
-export function calculateHash(data: Uint8Array): string {
-  return createHash("sha256").update(data).digest("hex");
-}