@stigmer/runner 3.12.0 → 3.12.1

package/src/shared/__tests__/plan-mode-permissions.test.ts

@@ -0,0 +1,58 @@
+/**
+ * Unit pins for the plan-mode rule builder (issue #528).
+ *
+ * The rule ORDER and SHAPE are the security boundary: deepagents evaluates
+ * first-match-wins with a permissive default, so the workspace read-allow
+ * must precede the read-deny, and the deny patterns must be the match-all
+ * "/**". These tests pin the built value; the boundary's end-to-end
+ * behavior (including matcher semantics for escaped roots and symlinked
+ * platform paths) is pinned against the real deepagents runtime in
+ * execute-deep-agent/__tests__/plan-mode-path-normalization.test.ts.
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  buildPlanModePermissions,
+  escapeGlobLiteral,
+} from "../plan-mode-permissions.js";
+
+describe("buildPlanModePermissions", () => {
+  it("builds the policy in enforcement order: workspace read-allow, then read-deny, then write-deny", () => {
+    expect(buildPlanModePermissions("/ws/session-1/repo")).toEqual([
+      { operations: ["read"], paths: ["/ws/session-1/repo/**"] },
+      { operations: ["read"], paths: ["/**"], mode: "deny" },
+      { operations: ["write"], paths: ["/**"], mode: "deny" },
+    ]);
+  });
+
+  it("canonicalizes the root before building the pattern", () => {
+    // Enforcement canonicalizes incoming paths (no trailing separator,
+    // collapsed slashes) before matching — a pattern built from a raw
+    // trailing-slash root would silently match nothing.
+    const [allow] = buildPlanModePermissions("/ws//session-1/repo/");
+    expect(allow.paths).toEqual(["/ws/session-1/repo/**"]);
+  });
+
+  it("glob-escapes the root so special characters match literally", () => {
+    const [allow] = buildPlanModePermissions("/Users/x/My (work) [v2]");
+    expect(allow.paths).toEqual(["/Users/x/My \\(work\\) \\[v2\\]/**"]);
+  });
+});
+
+describe("escapeGlobLiteral", () => {
+  it("escapes every micromatch metacharacter", () => {
+    expect(escapeGlobLiteral("a*b?c(d)e[f]g{h}i!j+k@l")).toBe(
+      "a\\*b\\?c\\(d\\)e\\[f\\]g\\{h\\}i\\!j\\+k\\@l",
+    );
+  });
+
+  it("escapes backslashes themselves", () => {
+    expect(escapeGlobLiteral("a\\b")).toBe("a\\\\b");
+  });
+
+  it("leaves plain path characters alone", () => {
+    expect(escapeGlobLiteral("/ws/session-1/repo.dir")).toBe(
+      "/ws/session-1/repo.dir",
+    );
+  });
+});

package/src/shared/__tests__/zip-extract.test.ts

@@ -1,89 +1,12 @@
 import { describe, it, expect } from "vitest";
-import { deflateRawSync } from "node:zlib";
 import { extractZipFileEntries } from "../zip-extract.js";
-
-// ─── Helpers ─────────────────────────────────────────────────────────────
-
-/**
- * Build a minimal valid ZIP archive from an array of { name, content } entries.
- * Uses stored (method 0) compression for simplicity. Produces local file
- * headers only (no central directory) — sufficient for our parser.
- */
-function buildStoredZip(files: { name: string; content: string }[]): Uint8Array {
-  const parts: Uint8Array[] = [];
-
-  for (const file of files) {
-    const nameBytes = new TextEncoder().encode(file.name);
-    const contentBytes = new TextEncoder().encode(file.content);
-    const isDir = file.name.endsWith("/");
-
-    // Local file header: 30 bytes
-    const header = new ArrayBuffer(30);
-    const view = new DataView(header);
-    view.setUint32(0, 0x04034b50, true);  // signature
-    view.setUint16(4, 20, true);           // version needed
-    view.setUint16(6, 0, true);            // general purpose flags
-    view.setUint16(8, 0, true);            // compression method (stored)
-    view.setUint16(10, 0, true);           // last mod time
-    view.setUint16(12, 0, true);           // last mod date
-    view.setUint32(14, 0, true);           // crc-32 (unused for our purposes)
-    view.setUint32(18, isDir ? 0 : contentBytes.length, true); // compressed size
-    view.setUint32(22, isDir ? 0 : contentBytes.length, true); // uncompressed size
-    view.setUint16(26, nameBytes.length, true);  // file name length
-    view.setUint16(28, 0, true);           // extra field length
-
-    parts.push(new Uint8Array(header));
-    parts.push(nameBytes);
-    if (!isDir) {
-      parts.push(contentBytes);
-    }
-  }
-
-  const totalLength = parts.reduce((sum, p) => sum + p.length, 0);
-  const result = new Uint8Array(totalLength);
-  let offset = 0;
-  for (const part of parts) {
-    result.set(part, offset);
-    offset += part.length;
-  }
-  return result;
-}
-
-/**
- * Build a ZIP archive with a single deflated (method 8) entry.
- */
-function buildDeflatedZip(name: string, content: string): Uint8Array {
-  const nameBytes = new TextEncoder().encode(name);
-  const contentBytes = new TextEncoder().encode(content);
-  const compressed = deflateRawSync(contentBytes);
-
-  const header = new ArrayBuffer(30);
-  const view = new DataView(header);
-  view.setUint32(0, 0x04034b50, true);
-  view.setUint16(4, 20, true);
-  view.setUint16(6, 0, true);
-  view.setUint16(8, 8, true);            // deflated
-  view.setUint16(10, 0, true);
-  view.setUint16(12, 0, true);
-  view.setUint32(14, 0, true);
-  view.setUint32(18, compressed.length, true);
-  view.setUint32(22, contentBytes.length, true);
-  view.setUint16(26, nameBytes.length, true);
-  view.setUint16(28, 0, true);
-
-  const totalLength = 30 + nameBytes.length + compressed.length;
-  const result = new Uint8Array(totalLength);
-  result.set(new Uint8Array(header), 0);
-  result.set(nameBytes, 30);
-  result.set(new Uint8Array(compressed.buffer, compressed.byteOffset, compressed.length), 30 + nameBytes.length);
-  return result;
-}
+import { buildZip } from "../../__test-utils__/zip-fixtures.js";
 
 // ─── extractZipFileEntries ───────────────────────────────────────────────
 
 describe("extractZipFileEntries", () => {
   it("extracts stored files from a ZIP archive", async () => {
-    const zip = buildStoredZip([
+    const zip = buildZip([
       { name: "SKILL.md", content: "# My Skill" },
       { name: "references/schema.md", content: "# Schema\n\nTable definitions." },
     ]);
@@ -96,7 +19,7 @@ describe("extractZipFileEntries", () => {
 
   it("extracts deflated files", async () => {
     const content = "This content is compressed with deflate.";
-    const zip = buildDeflatedZip("notes.txt", content);
+    const zip = buildZip([{ name: "notes.txt", content, method: "deflated" }]);
 
     const entries = await extractZipFileEntries(zip);
     expect(entries).toHaveLength(1);
@@ -104,7 +27,7 @@ describe("extractZipFileEntries", () => {
   });
 
   it("skips directory entries", async () => {
-    const zip = buildStoredZip([
+    const zip = buildZip([
       { name: "references/", content: "" },
       { name: "references/data.md", content: "data" },
     ]);
@@ -115,7 +38,7 @@ describe("extractZipFileEntries", () => {
   });
 
   it("excludes files by basename", async () => {
-    const zip = buildStoredZip([
+    const zip = buildZip([
       { name: "SKILL.md", content: "# Skill" },
       { name: "references/schema.md", content: "# Schema" },
       { name: "scripts/run.py", content: "print('hi')" },
@@ -127,7 +50,7 @@ describe("extractZipFileEntries", () => {
   });
 
   it("excludes files by full path", async () => {
-    const zip = buildStoredZip([
+    const zip = buildZip([
       { name: "a.md", content: "a" },
       { name: "nested/a.md", content: "nested" },
     ]);
@@ -138,7 +61,7 @@ describe("extractZipFileEntries", () => {
   });
 
   it("excludes entries matching basename even when nested", async () => {
-    const zip = buildStoredZip([
+    const zip = buildZip([
       { name: "SKILL.md", content: "root" },
       { name: "sub/SKILL.md", content: "sub" },
       { name: "data.md", content: "data" },
@@ -166,7 +89,7 @@ describe("extractZipFileEntries", () => {
   });
 
   it("handles multiple files with nested directories", async () => {
-    const zip = buildStoredZip([
+    const zip = buildZip([
       { name: "SKILL.md", content: "# Skill" },
       { name: "references/", content: "" },
       { name: "references/database-schema.md", content: "# Schema" },
@@ -184,7 +107,7 @@ describe("extractZipFileEntries", () => {
   });
 
   it("returns all entries when no exclude option is provided", async () => {
-    const zip = buildStoredZip([
+    const zip = buildZip([
       { name: "a.txt", content: "aaa" },
       { name: "b.txt", content: "bbb" },
     ]);
@@ -194,11 +117,105 @@ describe("extractZipFileEntries", () => {
   });
 
   it("returns all entries when exclude list is empty", async () => {
-    const zip = buildStoredZip([
-      { name: "a.txt", content: "aaa" },
-    ]);
+    const zip = buildZip([{ name: "a.txt", content: "aaa" }]);
 
     const entries = await extractZipFileEntries(zip, { exclude: [] });
     expect(entries).toHaveLength(1);
   });
+
+  // ── Streaming entries (issue #450) ─────────────────────────────────────
+
+  it("extracts Go-default streaming archives (deflated, data descriptors)", async () => {
+    const zip = buildZip([
+      { name: "SKILL.md", content: "# Streamed Skill", method: "deflated", streaming: true },
+      { name: "references/notes.md", content: "streamed notes", method: "deflated", streaming: true },
+    ]);
+
+    const entries = await extractZipFileEntries(zip);
+    expect(entries).toEqual([
+      { path: "SKILL.md", content: "# Streamed Skill" },
+      { path: "references/notes.md", content: "streamed notes" },
+    ]);
+  });
+
+  it("extracts a stored streaming entry whose payload embeds the data-descriptor signature", async () => {
+    // The four bytes of the descriptor signature (0x08074b50, little-endian
+    // "PK\x07\x08") planted mid-content, followed by twelve bytes a
+    // descriptor-scanning parser would misread as CRC and sizes. The old
+    // local-header walk truncated this entry at the planted signature and
+    // desynchronized everything after it — the exact defect of issue #450.
+    const poisoned = "before PK\u0007\u0008AAAABBBBCCCC after — full content survives";
+    const zip = buildZip([
+      { name: "poison.md", content: poisoned, streaming: true },
+      { name: "after.md", content: "the entry after the poisoned one" },
+    ]);
+
+    const entries = await extractZipFileEntries(zip);
+    expect(entries).toEqual([
+      { path: "poison.md", content: poisoned },
+      { path: "after.md", content: "the entry after the poisoned one" },
+    ]);
+  });
+
+  it("uses central-directory sizes when local header sizes are zeroed", async () => {
+    const content = "sizes live only in the central directory";
+    const zip = buildZip([{ name: "cd-sizes.txt", content, streaming: true }]);
+
+    const entries = await extractZipFileEntries(zip);
+    expect(entries).toEqual([{ path: "cd-sizes.txt", content }]);
+  });
+
+  // ── Central directory edge cases ───────────────────────────────────────
+
+  it("locates the EOCD behind a trailing archive comment", async () => {
+    const zip = buildZip([{ name: "a.txt", content: "aaa" }], {
+      comment: "release archive — built by tooling",
+    });
+
+    const entries = await extractZipFileEntries(zip);
+    expect(entries).toEqual([{ path: "a.txt", content: "aaa" }]);
+  });
+
+  it("is not fooled by EOCD signature bytes inside the archive comment", async () => {
+    // "PK\x05\x06" inside the comment is a decoy EOCD; validation must
+    // reject it (its "fields" are comment text) and keep scanning backward
+    // to the real record.
+    const zip = buildZip([{ name: "a.txt", content: "aaa" }], {
+      comment: "decoy: PK\u0005\u0006 not a real record",
+    });
+
+    const entries = await extractZipFileEntries(zip);
+    expect(entries).toEqual([{ path: "a.txt", content: "aaa" }]);
+  });
+
+  it("returns empty array when the central directory is missing", async () => {
+    // Local headers and payloads only — a download truncated before the
+    // archive's index. The parser must not fall back to guessing from
+    // local headers (design record 017).
+    const zip = buildZip(
+      [
+        { name: "a.txt", content: "aaa" },
+        { name: "b.txt", content: "bbb" },
+      ],
+      { omitCentralDirectory: true },
+    );
+
+    const entries = await extractZipFileEntries(zip);
+    expect(entries).toEqual([]);
+  });
+
+  it("returns empty array for an archive with entries but a truncated tail", async () => {
+    const zip = buildZip([{ name: "a.txt", content: "aaa" }]);
+    const truncated = zip.subarray(0, zip.length - 10); // clips into the EOCD
+
+    const entries = await extractZipFileEntries(truncated);
+    expect(entries).toEqual([]);
+  });
+
+  it("extracts an empty archive (EOCD only) as no entries", async () => {
+    const zip = buildZip([]);
+
+    const entries = await extractZipFileEntries(zip);
+    expect(entries).toEqual([]);
+  });
 });

package/src/shared/mcp-enabled-tools.ts

@@ -21,8 +21,12 @@
  * identity space as the sub-agent McpAccess filter and the approval-policy
  * maps. An enabled name the server does not expose is warned and dropped
  * (enforce the intersection): the restriction still holds and the run
- * proceeds with the valid subset; apply-time validation against
- * discovered_capabilities is the server-side follow-up that catches typos.
+ * proceeds with the valid subset. The server-side half (issue #402) rejects
+ * such names at apply time once the referenced server has discovered
+ * capabilities (stigmer-server validateEnabledToolsStep /
+ * validateDefaultEnabledToolsStep); this runtime leniency remains the
+ * safety net for manifests applied before a server's first connect and for
+ * toolsets that changed since the last discovery.
  */
 
 /**

package/src/shared/plan-mode-permissions.ts

@@ -2,12 +2,26 @@
  * The Plan-mode filesystem permission rules — the enforcement twin of
  * `plan-mode-prompt.ts` (which carries the instruction half of the contract).
  *
- * Plan mode is read-only BY CONSTRUCTION on the native harness: these rules
- * deny every filesystem write operation at the tool level so
- * write_file/edit_file cannot mutate the workspace regardless of what the
- * model was told. Rules are first-match-wins with a permissive default, so a
- * single deny-all-writes rule is sufficient. (The Cursor harness has no
- * tool-level lever and enforces plan mode via its prompt prefix instead.)
+ * Plan mode is contained BY CONSTRUCTION on the native harness: these rules
+ * deny every filesystem write everywhere AND scope reads to the session
+ * workspace (issue #528 — owner ruling: the workspace is plan mode's read
+ * boundary on cloud and desktop runners alike). Without the read boundary,
+ * model-provided absolute paths reached anywhere the process account could
+ * read — the pod filesystem (including /proc/self/environ) on cloud runners,
+ * the user's whole home directory on desktop — while plan mode still carries
+ * exfiltration-capable tools (web_fetch, MCP). Rules are first-match-wins
+ * with a permissive default (deepagents' decidePathAccess), so order is
+ * load-bearing: the workspace read-allow must precede the read-deny.
+ *
+ * The workspace-root pattern is matched as a STRING against the raw tool-call
+ * path (micromatch, dot:true), before the backend touches disk. That is
+ * exactly why the legitimate out-of-workspace reads keep working: skills,
+ * attachments, and the approved plan live in the platform dir but are
+ * addressed through the `{workspace}/.stigmer` symlink (see
+ * shared/workspace/stigmer-link.ts), so their path strings are in-root even
+ * though the bytes are not. The same holds for multi-workspace local entries
+ * (`{workspace}/{name}` symlinks). A realpath-based boundary would break
+ * both; do not "harden" this into one.
  *
  * Applied in execute-deep-agent/setup.ts to the parent graph AND threaded
  * into every compiled sub-agent graph: deepagents' parent-permission
@@ -18,9 +32,9 @@
  *
  * Rules travel with a companion: every graph that carries them also installs
  * the path-normalization middleware (middleware/path-normalization.ts,
- * issue #429), because deepagents' rule validation refuses workspace-relative
- * paths outright — without the shim, prompt-compliant relative READS die in
- * validation instead of just working. Both are derived from the same
+ * issues #429/#528), because deepagents' rule validation refuses
+ * workspace-relative paths outright and its `ls`/`glob`/`grep` schema default
+ * of "/" would deny the bare first listing. Both are derived from the same
  * expression at each composition site so they cannot drift apart.
  *
  * Invariant: never combine these rules with a shell-capable (sandbox)
@@ -30,8 +44,41 @@
  * for shell capability on both the parent and sub-agent backends.
  */
 
+import { resolve } from "node:path";
 import type { FilesystemPermission } from "deepagents";
 
-export const PLAN_MODE_PERMISSIONS: FilesystemPermission[] = [
-  { operations: ["write"], paths: ["/**"], mode: "deny" },
-];
+/**
+ * Backslash-escape every character micromatch/picomatch treats as glob
+ * syntax, so the result matches the input literally. micromatch exports no
+ * escape API of its own, and this is correctness, not caution: an unescaped
+ * `(` in a desktop project path would make the workspace read-allow rule
+ * silently never match — bricking every plan-mode read for that workspace.
+ * Semantics are pinned end-to-end through deepagents' own matcher by the
+ * special-character workspace suite in plan-mode-path-normalization.test.ts.
+ */
+export function escapeGlobLiteral(literal: string): string {
+  return literal.replace(/[\\*?()[\]{}!+@]/g, "\\$&");
+}
+
+/**
+ * Build the plan-mode rule set for a graph whose filesystem backend is
+ * rooted at `workspaceRootDir`. The three rules read as the policy:
+ * reads allowed in the workspace, reads denied everywhere else, writes
+ * denied everywhere.
+ *
+ * `{root}/**` matches the root itself as well as its subtree (verified
+ * against the installed micromatch), so one allow pattern suffices. The
+ * root is `path.resolve`d first because enforcement canonicalizes incoming
+ * paths (collapsed slashes, no trailing separator) before matching — a
+ * trailing slash in the pattern would silently match nothing.
+ */
+export function buildPlanModePermissions(
+  workspaceRootDir: string,
+): FilesystemPermission[] {
+  const canonicalRoot = resolve(workspaceRootDir);
+  return [
+    { operations: ["read"], paths: [`${escapeGlobLiteral(canonicalRoot)}/**`] },
+    { operations: ["read"], paths: ["/**"], mode: "deny" },
+    { operations: ["write"], paths: ["/**"], mode: "deny" },
+  ];
+}

package/src/shared/zip-extract.ts

@@ -1,10 +1,24 @@
 /**
- * Minimal, dependency-free ZIP archive parser.
+ * Skill-artifact ZIP extraction: text-decoded entries with non-fatal
+ * structural failure.
  *
- * Handles the local file header format, supporting stored (method 0) and
- * deflated (method 8) entries. Returns parsed entries as path + content
- * pairs — consumers bring their own write mechanism (WorkspaceBackend,
- * node:fs, etc.).
+ * Structural parsing lives in zip-structure.ts (central-directory-based —
+ * see that module's doc for why local-header walks are never acceptable,
+ * issue #450). This module owns the skill-artifact *policy* on top of it:
+ *
+ * Input without a readable central directory is not given a second
+ * chance on purpose: every artifact reaching the runner was validated at
+ * push by a central-directory-based reader on both editions (OSS:
+ * `safearchive/zip` in stigmer-server's skill storage; cloud:
+ * commons-compress `ZipFile` in SkillArtifactExtractor), so a missing
+ * EOCD here can only mean a truncated or corrupted download — and the
+ * honest result for that is the documented empty return, not a guess.
+ * (The attachment injector consumes the same structural layer under the
+ * opposite policy — fail-hard — because its input is untrusted.)
+ *
+ * Handles stored (method 0) and deflated (method 8) entries. Returns
+ * parsed entries as path + content pairs — consumers bring their own
+ * write mechanism (WorkspaceBackend, node:fs, etc.).
  *
  * Extracted from skill-writer.ts so both the deep-agent and Cursor
  * harnesses can share the same ZIP parsing logic without coupling to
@@ -12,6 +26,7 @@
  */
 
 import { createInflateRaw } from "node:zlib";
+import { EOCD_MIN_SIZE, parseZipStructure, type ZipStructuralEntry } from "./zip-structure.js";
 
 // ─── Public API ──────────────────────────────────────────────────────────
 
@@ -29,18 +44,26 @@ export interface ZipFileEntry {
  * entries whose filename (basename or full path) matches any excluded name.
  *
  * Returns an empty array for empty, truncated, or non-ZIP input rather
- * than throwing — callers treat missing artifacts as non-fatal.
+ * than throwing — callers treat missing artifacts as non-fatal. Errors
+ * while *decompressing* a structurally valid entry (corrupt deflate
+ * stream, unsupported compression method) do propagate: at that point
+ * the archive's structure vouched for the entry, and silently dropping
+ * it would be the exact corruption this module exists to prevent.
  */
 export async function extractZipFileEntries(
   zipBytes: Uint8Array,
   options?: { exclude?: readonly string[] },
 ): Promise<ZipFileEntry[]> {
-  if (zipBytes.length < 4) return [];
+  if (zipBytes.length < EOCD_MIN_SIZE) return [];
 
-  let entries: ZipEntry[];
+  let entries: ZipStructuralEntry[];
   try {
-    entries = parseZipEntries(zipBytes);
-  } catch {
+    entries = parseZipStructure(zipBytes);
+  } catch (err) {
+    console.warn(
+      "[zip-extract] archive has no readable central directory " +
+      `(truncated or corrupt download?): ${err instanceof Error ? err.message : String(err)}`,
+    );
     return [];
   }
 
@@ -58,16 +81,6 @@ export async function extractZipFileEntries(
   return results;
 }
 
-// ─── Internals ───────────────────────────────────────────────────────────
-
-interface ZipEntry {
-  name: string;
-  isDirectory: boolean;
-  compressedData: Uint8Array;
-  compressionMethod: number;
-  uncompressedSize: number;
-}
-
 function isExcluded(name: string, excludeSet: ReadonlySet<string>): boolean {
   if (excludeSet.size === 0) return false;
   if (excludeSet.has(name)) return true;
@@ -76,104 +89,9 @@ function isExcluded(name: string, excludeSet: ReadonlySet<string>): boolean {
   return excludeSet.has(basename);
 }
 
-function parseZipEntries(data: Uint8Array): ZipEntry[] {
-  const entries: ZipEntry[] = [];
-  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
-  let offset = 0;
-
-  while (offset < data.length - 4) {
-    const signature = view.getUint32(offset, true);
-    if (signature !== 0x04034b50) break; // Local file header signature
-
-    const generalFlags = view.getUint16(offset + 6, true);
-    const hasDataDescriptor = (generalFlags & 0x08) !== 0;
-    const compressionMethod = view.getUint16(offset + 8, true);
-    let compressedSize = view.getUint32(offset + 18, true);
-    let uncompressedSize = view.getUint32(offset + 22, true);
-    const fileNameLength = view.getUint16(offset + 26, true);
-    const extraFieldLength = view.getUint16(offset + 28, true);
-
-    const fileNameStart = offset + 30;
-    const fileName = new TextDecoder().decode(
-      data.subarray(fileNameStart, fileNameStart + fileNameLength),
-    );
-
-    const dataStart = fileNameStart + fileNameLength + extraFieldLength;
-
-    if (hasDataDescriptor && compressedSize === 0) {
-      const sizes = findDataDescriptor(data, view, dataStart, compressionMethod);
-      compressedSize = sizes.compressedSize;
-      uncompressedSize = sizes.uncompressedSize;
-    }
-
-    const compressedData = data.subarray(dataStart, dataStart + compressedSize);
-
-    entries.push({
-      name: fileName,
-      isDirectory: fileName.endsWith("/"),
-      compressedData,
-      compressionMethod,
-      uncompressedSize,
-    });
-
-    let nextOffset = dataStart + compressedSize;
-    if (hasDataDescriptor) {
-      if (nextOffset + 4 <= data.length && view.getUint32(nextOffset, true) === 0x08074b50) {
-        nextOffset += 16; // signature(4) + crc(4) + compressedSize(4) + uncompressedSize(4)
-      } else {
-        nextOffset += 12; // crc(4) + compressedSize(4) + uncompressedSize(4)
-      }
-    }
-    offset = nextOffset;
-  }
-
-  return entries;
-}
-
-/**
- * Scan forward from dataStart to find the data descriptor that contains
- * the actual compressed and uncompressed sizes. Looks for either the
- * optional signature 0x08074b50 or falls back to scanning the central
- * directory for the matching entry.
- */
-function findDataDescriptor(
-  data: Uint8Array,
-  view: DataView,
-  dataStart: number,
-  _compressionMethod: number,
-): { compressedSize: number; uncompressedSize: number } {
-  for (let pos = dataStart; pos < data.length - 16; pos++) {
-    const sig = view.getUint32(pos, true);
-    if (sig === 0x08074b50) {
-      return {
-        compressedSize: view.getUint32(pos + 8, true),
-        uncompressedSize: view.getUint32(pos + 12, true),
-      };
-    }
-    if (sig === 0x04034b50 || sig === 0x02014b50) {
-      const descStart = pos - 12;
-      if (descStart >= dataStart) {
-        return {
-          compressedSize: view.getUint32(descStart + 4, true),
-          uncompressedSize: view.getUint32(descStart + 8, true),
-        };
-      }
-      break;
-    }
-  }
-  for (let pos = dataStart; pos < data.length - 4; pos++) {
-    const sig = view.getUint32(pos, true);
-    if (sig === 0x04034b50 || sig === 0x02014b50 || sig === 0x08074b50) {
-      const compressedSize = sig === 0x08074b50
-        ? view.getUint32(pos + 8, true)
-        : pos - dataStart;
-      return { compressedSize, uncompressedSize: 0 };
-    }
-  }
-  return { compressedSize: data.length - dataStart, uncompressedSize: 0 };
-}
+// ─── Decompression ───────────────────────────────────────────────────────
 
-async function decompressEntry(entry: ZipEntry): Promise<string> {
+async function decompressEntry(entry: ZipStructuralEntry): Promise<string> {
   if (entry.compressionMethod === 0) {
     return new TextDecoder().decode(entry.compressedData);
   }