@stigmer/server 3.14.0-dev.20260910084630

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

@@ -0,0 +1,139 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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";
+
+/**
+ * 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>;
+}
+
+/**
+ * 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";
+  }
+}
+
+/** Skill artifacts are zip archives; the driver stores the honest type. */
+const SKILL_ARTIFACT_CONTENT_TYPE = "application/zip";
+
+/**
+ * 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).
+ */
+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)
+  );
+}

package/src/domain/skill/storage/frontmatter.ts

@@ -0,0 +1,181 @@
+/**
+ * SKILL.md frontmatter parsing — ports pkg/domain/skill/storage/
+ * frontmatter.go. The backend is the single source of truth for parsing
+ * SKILL.md: name (required, kebab-case with optional dot-scoped
+ * namespaces) and description come from the YAML frontmatter between ---
+ * markers at the start of the file. Every error string is wire-visible
+ * teaching copy, byte-pinned from Go (multi-line "expected format" blocks
+ * included).
+ *
+ * Proven by __tests__/frontmatter.test.ts and the skill conformance
+ * suite's push-validation negatives.
+ */
+import yaml from "js-yaml";
+
+// goTrimSpace: Go's exact TrimSpace set — a .trim()-based delimiter check
+// would accept BOM'd "---" lines Go rejects (found by the #8 parity review
+// panel; promoted to gocompat when search criteria became the second
+// consumer, #14).
+import { goTrimSpace } from "../../../gocompat/trim.js";
+
+/** Parsed SKILL.md frontmatter (Go SkillFrontmatter). */
+export interface SkillFrontmatter {
+  /** Canonical skill identifier (required; kebab-case, optionally dot-scoped). */
+  readonly name: string;
+  /** Human-readable summary (optional but recommended). */
+  readonly description: string;
+  /** Informational only — hash-based versioning is used instead. */
+  readonly version: string;
+}
+
+/**
+ * Kebab-case skill names, optionally scoped with dot-separated namespaces:
+ * lowercase letters, numbers, hyphens (words), and dots (namespace
+ * segments). Every segment between separators must be alphanumeric, so a
+ * name cannot start or end with a separator, nor contain consecutive
+ * separators. The derived slug renders dots as hyphens (generateSlug).
+ */
+const SKILL_NAME_PATTERN = /^[a-z0-9]+([.-][a-z0-9]+)*$/;
+
+/**
+ * bufio.Scanner's default token cap (Go bufio.MaxScanTokenSize): lines
+ * longer than this fail Go's scan loop, so the port enforces the same
+ * ceiling — measured in BYTES, as the scanner buffers bytes. Two distinct
+ * arms, faithful to Go's checking order: a too-long FIRST line makes the
+ * initial Scan() return false before Err() is consulted (reported as
+ * "SKILL.md is empty"), while a too-long line inside the frontmatter
+ * surfaces the scanner error.
+ */
+const MAX_SCAN_TOKEN_SIZE = 64 * 1024;
+
+function lineTooLong(line: string): boolean {
+  return Buffer.byteLength(line, "utf8") > MAX_SCAN_TOKEN_SIZE;
+}
+
+/**
+ * Extracts and parses YAML frontmatter from SKILL.md content (Go
+ * ParseFrontmatter). Throws plain Errors — the push pipeline wraps them
+ * into the InvalidArgument "failed to extract SKILL.md: ..." arm.
+ */
+export function parseFrontmatter(content: string): SkillFrontmatter {
+  const frontmatterYaml = extractFrontmatterYaml(content);
+
+  let parsed: unknown;
+  try {
+    parsed = yaml.load(frontmatterYaml);
+  } catch (error) {
+    throw new Error(
+      `failed to parse YAML frontmatter: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  const record =
+    typeof parsed === "object" && parsed !== null
+      ? (parsed as Record<string, unknown>)
+      : {};
+  const frontmatter: SkillFrontmatter = {
+    name: typeof record["name"] === "string" ? record["name"] : "",
+    description:
+      typeof record["description"] === "string" ? record["description"] : "",
+    version: typeof record["version"] === "string" ? record["version"] : "",
+  };
+
+  validateFrontmatter(frontmatter);
+  return frontmatter;
+}
+
+/**
+ * Extracts the raw YAML between --- delimiters: the frontmatter must
+ * start on the FIRST line with --- and end with --- on its own line
+ * (whitespace-trimmed comparison on both, as Go's scanner loop does).
+ */
+function extractFrontmatterYaml(content: string): string {
+  if (content === "") {
+    throw new Error("SKILL.md is empty");
+  }
+
+  const lines = content.split(/\r?\n/);
+  // Go's initial Scan() returns false for a first line over the scanner
+  // cap — and its !Scan() arm reports "SKILL.md is empty" without ever
+  // consulting Err(). Bug-for-bug: the misleading copy IS the contract.
+  if (lineTooLong(lines[0]!)) {
+    throw new Error("SKILL.md is empty");
+  }
+  const firstLine = goTrimSpace(lines[0]!);
+  if (firstLine !== "---") {
+    throw new Error(
+      "SKILL.md must start with YAML frontmatter (---)\n\n" +
+        "Expected format:\n" +
+        "---\n" +
+        "name: my-skill-name\n" +
+        "description: A brief description of what this skill does\n" +
+        "---\n" +
+        "# Skill Title\n" +
+        "...",
+    );
+  }
+
+  const frontmatterLines: string[] = [];
+  let foundClosing = false;
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (lineTooLong(line)) {
+      // Go: the scan loop stops, and Err() is checked BEFORE the
+      // closing-delimiter check — so an over-cap line inside the
+      // frontmatter wins over "not closed". Message text is the %w-chain
+      // rendering of bufio.ErrTooLong.
+      throw new Error(
+        "error reading SKILL.md content: bufio.Scanner: token too long",
+      );
+    }
+    if (goTrimSpace(line) === "---") {
+      foundClosing = true;
+      break;
+    }
+    frontmatterLines.push(line);
+  }
+
+  if (!foundClosing) {
+    throw new Error("SKILL.md frontmatter is not closed (missing closing ---)");
+  }
+
+  if (frontmatterLines.length === 0) {
+    throw new Error(
+      "SKILL.md has empty frontmatter\n\n" +
+        "The frontmatter must contain at least a 'name' field:\n" +
+        "---\n" +
+        "name: my-skill-name\n" +
+        "---",
+    );
+  }
+
+  return frontmatterLines.join("\n");
+}
+
+/** Required-field and format validation (Go validateFrontmatter). */
+function validateFrontmatter(frontmatter: SkillFrontmatter): void {
+  if (frontmatter.name === "") {
+    throw new Error(
+      "SKILL.md is missing required 'name' field in YAML frontmatter\n\n" +
+        "Expected format:\n" +
+        "---\n" +
+        "name: my-skill-name\n" +
+        "---\n\n" +
+        "The name must be kebab-case (lowercase letters, numbers, and hyphens), " +
+        "optionally scoped with dots (e.g. 'platform.my-skill')",
+    );
+  }
+
+  if (!SKILL_NAME_PATTERN.test(frontmatter.name)) {
+    throw new Error(
+      `invalid skill name '${frontmatter.name}' in SKILL.md\n\n` +
+        "Skill names must be kebab-case, optionally scoped with dot-separated namespaces:\n" +
+        "- Lowercase letters (a-z)\n" +
+        "- Numbers (0-9)\n" +
+        "- Hyphens (-) to separate words\n" +
+        "- Dots (.) to separate namespace segments\n\n" +
+        "Every segment must be alphanumeric: no leading, trailing, or consecutive separators.\n\n" +
+        "Examples: 'calculator', 'web-scraper', 'math-utils', 'platform.planton-architecture'",
+    );
+  }
+}

package/src/domain/skill/storage/prefilter.ts

@@ -0,0 +1,200 @@
+/**
+ * safearchive-parity entry pre-filter — ports the OBSERVABLE half of
+ * github.com/google/safearchive's zip.MaximumSecurityMode (applyMagic,
+ * zip.go:158, at the go.mod-pinned v0.0.0-20241025131057) plus its
+ * sanitizer package. Go's push gate opens ZIPs through safearchive, which
+ * rewrites the entry list BEFORE zip_extractor.go's validation loop sees
+ * it — so the gate's accept/reject behavior includes this filter, and
+ * local parity requires reproducing it (sub-project DD-001, Option A,
+ * owner-ratified 2026-08-24). The cloud edition applies none of this; the
+ * parity target is the Go server.
+ *
+ * The four observable behaviors, in safearchive's exact order per entry:
+ *   1. SanitizeFilenames — names become unrooted, ..-free, /-separated.
+ *      Consequence: "../SKILL.md" IS a root SKILL.md to the gate.
+ *   2. SkipWindowsShortFilenames — entries with an 8.3-style path
+ *      component (`~N`) are dropped.
+ *   3. PreventSymlinkTraversal (+ case-insensitive) — entries whose path
+ *      passes through an earlier symlink entry are dropped; symlink
+ *      entries themselves stay (and register as shadows).
+ *   4. SkipSpecialFiles — device/pipe/socket/char-device entries are
+ *      dropped.
+ * (safearchive's fifth measure, SanitizeFileMode, strips permission bits
+ * the gate never exposes — not observable, not ported.)
+ *
+ * Entry file types are decoded from the central directory's raw
+ * creator/attribute fields exactly as Go archive/zip's FileHeader.Mode()
+ * does: Unix/macOS creators carry a POSIX mode in the attribute high 16
+ * bits; FAT/NTFS/VFAT creators carry MSDOS bits that can never encode a
+ * symlink or special file; unknown creators decode to a regular file.
+ *
+ * Proven by __tests__/prefilter.test.ts (byte-crafted fixtures per DD-001).
+ */
+import type { ZipStructuralEntry } from "@stigmer/zip-structure";
+
+// ─── sanitizer.SanitizePath ──────────────────────────────────────────────
+
+/**
+ * safearchive sanitizer.SanitizePath (nix variant): backslashes normalize
+ * to slashes, then TrimPrefix(Clean("/"+path), "/") — always unrooted with
+ * no ".." elements; a trailing separator on the input is preserved when
+ * the sanitized result is non-empty.
+ *
+ * The nix variant is deliberate: Go compiles the _win variant only on
+ * Windows hosts, where sanitized names carry backslashes. The TS gate
+ * normalizes to slashes everywhere — a Windows-host-only cosmetic
+ * divergence in ERROR TEXT for pathological names, disclosed in the PR.
+ */
+export function sanitizePath(input: string): string {
+  const sanitized = sanitizeCore(input);
+  if (
+    input.length > 0 &&
+    (input.endsWith("/") || input.endsWith("\\")) &&
+    sanitized.length > 0
+  ) {
+    return `${sanitized}/`;
+  }
+  return sanitized;
+}
+
+function sanitizeCore(input: string): string {
+  const normalizedSeparators = input.replaceAll("\\", "/");
+  // Go filepath.Clean("/"+in): resolve "." and ".." lexically against a
+  // rooted path (leading ".." cannot climb above the root), collapse
+  // duplicate separators, and drop any trailing separator.
+  const segments = `/${normalizedSeparators}`.split("/");
+  const resolved: string[] = [];
+  for (const segment of segments) {
+    if (segment === "" || segment === ".") {
+      continue;
+    }
+    if (segment === "..") {
+      resolved.pop();
+      continue;
+    }
+    resolved.push(segment);
+  }
+  return resolved.join("/");
+}
+
+// ─── sanitizer.HasWindowsShortFilenames ──────────────────────────────────
+
+/** Matches a Windows 8.3 short-name marker (`~1`, `~23.`) in a component. */
+const WINDOWS_SHORT_FILENAME_PATTERN = /~\d+\.?/;
+
+/** safearchive sanitizer.HasWindowsShortFilenames, verbatim semantics. */
+export function hasWindowsShortFilenames(input: string): boolean {
+  return input
+    .replaceAll("\\", "/")
+    .split("/")
+    .some((part) => WINDOWS_SHORT_FILENAME_PATTERN.test(part));
+}
+
+// ─── archive/zip FileHeader.Mode() — the type bits the filter tests ──────
+
+// CreatorVersion high bytes (Go archive/zip creator* constants).
+const CREATOR_UNIX = 3;
+const CREATOR_MACOSX = 19;
+
+// POSIX file-type field masks (syscall.S_IF*).
+const S_IFMT = 0o170000;
+const S_IFBLK = 0o060000;
+const S_IFCHR = 0o020000;
+const S_IFIFO = 0o010000;
+const S_IFLNK = 0o120000;
+const S_IFSOCK = 0o140000;
+
+interface EntryTypeBits {
+  readonly isSymlink: boolean;
+  /** Device, char device, named pipe, or socket (safearchive isSpecialFile). */
+  readonly isSpecial: boolean;
+}
+
+/**
+ * Decodes the entry's file-type bits the way Go's zip.FileHeader.Mode()
+ * does. Only Unix/macOS creators can express symlinks or special files;
+ * every other creator (FAT, NTFS, VFAT, unknown) decodes to a regular
+ * file for the two bits this filter tests.
+ */
+export function entryTypeBits(entry: ZipStructuralEntry): EntryTypeBits {
+  const creator = entry.versionMadeBy >> 8;
+  if (creator !== CREATOR_UNIX && creator !== CREATOR_MACOSX) {
+    return { isSymlink: false, isSpecial: false };
+  }
+  const unixMode = (entry.externalAttributes >>> 16) & 0xffff;
+  const fileType = unixMode & S_IFMT;
+  return {
+    isSymlink: fileType === S_IFLNK,
+    isSpecial:
+      fileType === S_IFBLK ||
+      fileType === S_IFCHR ||
+      fileType === S_IFIFO ||
+      fileType === S_IFSOCK,
+  };
+}
+
+// ─── applyMagic ──────────────────────────────────────────────────────────
+
+/**
+ * A structural entry after the pre-filter: same record, sanitized name.
+ * The original entry rides along for payload access.
+ */
+export interface PrefilteredEntry {
+  /** The sanitized name — what every downstream check sees (Go f.Name). */
+  readonly name: string;
+  readonly entry: ZipStructuralEntry;
+}
+
+/**
+ * safearchive applyMagic under MaximumSecurityMode, step-for-step in its
+ * per-entry order: sanitize the name; drop 8.3-named entries; drop entries
+ * shadowed by an earlier symlink (case-insensitive path-prefix match,
+ * registering symlink entries as shadows); drop special files.
+ */
+export function applyEntryPrefilter(
+  entries: readonly ZipStructuralEntry[],
+): PrefilteredEntry[] {
+  const symlinks = new Set<string>();
+  const result: PrefilteredEntry[] = [];
+
+  for (const entry of entries) {
+    const name = sanitizePath(entry.name);
+
+    if (hasWindowsShortFilenames(name)) {
+      continue;
+    }
+
+    // PreventSymlinkTraversal + PreventCaseInsensitiveSymlinkTraversal:
+    // re-sanitize (idempotent — safearchive does the same), strip the
+    // trailing separator, lowercase, and test every path prefix against
+    // the symlinks seen so far.
+    const shadowKey = trimTrailingSlash(sanitizePath(name)).toLowerCase();
+    const parts = shadowKey.split("/");
+    let traversal = false;
+    for (let i = 1; i <= parts.length; i++) {
+      if (symlinks.has(parts.slice(0, i).join("/"))) {
+        traversal = true;
+        break;
+      }
+    }
+    if (traversal) {
+      continue;
+    }
+
+    const typeBits = entryTypeBits(entry);
+    if (typeBits.isSymlink) {
+      symlinks.add(shadowKey);
+    }
+    if (typeBits.isSpecial) {
+      continue;
+    }
+
+    result.push({ name, entry });
+  }
+
+  return result;
+}
+
+function trimTrailingSlash(path: string): string {
+  return path.endsWith("/") ? path.slice(0, -1) : path;
+}