harnery 0.42.0 → 0.44.0

package/dist/lib/zip/index.js

@@ -0,0 +1,398 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, constants, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { inflateRawSync } from "node:zlib";
+import { strFromU8, zipSync } from "fflate";
+export const DEFAULT_ZIP_LIMITS = Object.freeze({
+    archiveBytes: 64 * 1024 * 1024,
+    entryBytes: 64 * 1024 * 1024,
+    totalBytes: 256 * 1024 * 1024,
+    entries: 10_000,
+});
+function limitsFor(options) {
+    const limits = { ...DEFAULT_ZIP_LIMITS, ...options.limits };
+    for (const [key, value] of Object.entries(limits))
+        if (!Number.isSafeInteger(value) || value < 1)
+            throw new Error(`Invalid ZIP limit: ${key}`);
+    return limits;
+}
+function readBoundedFile(path, limit, noFollow = false) {
+    const fd = openSync(path, constants.O_RDONLY | (noFollow ? (constants.O_NOFOLLOW ?? 0) : 0));
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.size > limit)
+            throw new Error("ZIP input exceeds byte limit or is not a file");
+        const bytes = Buffer.alloc(stat.size + 1);
+        let count = 0;
+        while (count < bytes.length) {
+            const read = readSync(fd, bytes, count, bytes.length - count, null);
+            if (!read)
+                break;
+            count += read;
+        }
+        if (count !== stat.size)
+            throw new Error("ZIP input changed while reading");
+        return bytes.subarray(0, count);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function bytesOf(source, limits) {
+    const bytes = typeof source === "string" ? readBoundedFile(source, limits.archiveBytes) : source;
+    if (bytes.byteLength > limits.archiveBytes)
+        throw new Error("ZIP archive exceeds compressed byte limit");
+    return bytes;
+}
+function centralEntries(bytes, limits) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let end = bytes.length - 22;
+    for (; end >= Math.max(0, bytes.length - 65_557); end--) {
+        if (view.getUint32(end, true) === 0x06054b50 &&
+            end + 22 + view.getUint16(end + 20, true) === bytes.length)
+            break;
+    }
+    if (end < Math.max(0, bytes.length - 65_557))
+        throw new Error("Missing ZIP end record");
+    const count = view.getUint16(end + 10, true);
+    if (view.getUint16(end + 4, true) !== 0 ||
+        view.getUint16(end + 6, true) !== 0 ||
+        view.getUint16(end + 8, true) !== count ||
+        count === 0xffff)
+        throw new Error("Split or ZIP64 archives are unsupported");
+    if (count > limits.entries)
+        throw new Error("ZIP archive exceeds entry count limit");
+    const central = view.getUint32(end + 16, true);
+    let offset = central;
+    if (offset + view.getUint32(end + 12, true) !== end)
+        throw new Error("Invalid ZIP directory bounds");
+    const entries = [];
+    const names = new Set();
+    let total = 0;
+    for (let index = 0; index < count; index++) {
+        if (offset + 46 > end || view.getUint32(offset, true) !== 0x02014b50)
+            throw new Error("Invalid ZIP directory entry");
+        const flags = view.getUint16(offset + 8, true);
+        const method = view.getUint16(offset + 10, true);
+        if (flags & 1)
+            throw new Error("Encrypted ZIP entries are unsupported");
+        if (method !== 0 && method !== 8)
+            throw new Error("Unsupported ZIP compression method");
+        const nameLength = view.getUint16(offset + 28, true);
+        const next = offset +
+            46 +
+            nameLength +
+            view.getUint16(offset + 30, true) +
+            view.getUint16(offset + 32, true);
+        if (next > end || view.getUint16(offset + 34, true) !== 0)
+            throw new Error("Invalid ZIP directory entry bounds");
+        const rawName = bytes.subarray(offset + 46, offset + 46 + nameLength);
+        const name = strFromU8(rawName, !(flags & 0x800));
+        if (names.has(name))
+            throw new Error(`Duplicate ZIP entry: ${name}`);
+        names.add(name);
+        const size = view.getUint32(offset + 24, true);
+        const compressedSize = view.getUint32(offset + 20, true);
+        const checksum = view.getUint32(offset + 16, true);
+        const header = view.getUint32(offset + 42, true);
+        if (size === 0xffffffff || compressedSize === 0xffffffff || header === 0xffffffff)
+            throw new Error("ZIP64 entries are unsupported");
+        total += size;
+        if (size > limits.entryBytes || total > limits.totalBytes)
+            throw new Error("ZIP archive exceeds entry or total byte limit");
+        if (header + 30 > central || view.getUint32(header, true) !== 0x04034b50)
+            throw new Error("Invalid ZIP local header");
+        const localNameLength = view.getUint16(header + 26, true);
+        const dataOffset = header + 30 + localNameLength + view.getUint16(header + 28, true);
+        if (dataOffset + compressedSize > central ||
+            localNameLength !== nameLength ||
+            view.getUint16(header + 6, true) !== flags ||
+            view.getUint16(header + 8, true) !== method ||
+            !rawName.every((byte, i) => bytes[header + 30 + i] === byte))
+            throw new Error("ZIP local and central header mismatch");
+        if (!(flags & 8) &&
+            (view.getUint32(header + 14, true) !== checksum ||
+                view.getUint32(header + 18, true) !== compressedSize ||
+                view.getUint32(header + 22, true) !== size))
+            throw new Error("ZIP local and central size/checksum mismatch");
+        if (method === 0 && compressedSize !== size)
+            throw new Error("Stored ZIP entry size mismatch");
+        if (name.endsWith("/") && size !== 0)
+            throw new Error("ZIP directory has a payload");
+        entries.push({
+            name,
+            size,
+            compressedSize,
+            directory: name.endsWith("/"),
+            crc32: checksum,
+            method,
+            dataOffset,
+            headerOffset: header,
+        });
+        offset = next;
+    }
+    if (offset !== end)
+        throw new Error("Invalid ZIP directory length");
+    const ordered = [...entries].sort((a, b) => a.headerOffset - b.headerOffset);
+    for (let i = 1; i < ordered.length; i++)
+        if (ordered[i].headerOffset < ordered[i - 1].dataOffset + ordered[i - 1].compressedSize)
+            throw new Error("Overlapping ZIP entry ranges");
+    return entries;
+}
+const CRC_TABLE = Uint32Array.from({ length: 256 }, (_, value) => {
+    for (let bit = 0; bit < 8; bit++)
+        value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+    return value >>> 0;
+});
+function crc32(bytes) {
+    let crc = 0xffffffff;
+    for (const byte of bytes)
+        crc = (crc >>> 8) ^ CRC_TABLE[(crc ^ byte) & 255];
+    return (crc ^ 0xffffffff) >>> 0;
+}
+function inventory(bytes, limits) {
+    try {
+        return centralEntries(bytes, limits);
+    }
+    catch (error) {
+        throw new Error(`Unreadable ZIP archive: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export function listZip(source, options = {}) {
+    const limits = limitsFor(options);
+    return inventory(bytesOf(source, limits), limits).map(({ method, dataOffset, headerOffset, ...entry }) => entry);
+}
+export function readZipEntries(source, keep = () => true, options = {}) {
+    const limits = limitsFor(options);
+    const bytes = bytesOf(source, limits);
+    const selected = inventory(bytes, limits).filter((entry) => !entry.directory && keep(entry.name));
+    const result = new Map();
+    for (const entry of selected) {
+        const compressed = bytes.subarray(entry.dataOffset, entry.dataOffset + entry.compressedSize);
+        // zlib enforces actual output length during decoding, independent of forged headers.
+        const data = entry.method === 0
+            ? compressed.slice()
+            : inflateRawSync(compressed, {
+                maxOutputLength: Math.max(1, Math.min(entry.size, limits.entryBytes)),
+            });
+        if (!(data instanceof Uint8Array) || data.byteLength !== entry.size)
+            throw new Error(`ZIP entry size or decode mismatch: ${entry.name}`);
+        if (crc32(data) !== entry.crc32)
+            throw new Error(`ZIP entry checksum mismatch: ${entry.name}`);
+        result.set(entry.name, data);
+    }
+    return result;
+}
+export function readZipEntry(source, name, options = {}) {
+    return readZipEntries(source, (entry) => entry === name, options).get(name);
+}
+export function readZipText(source, name, options = {}) {
+    const bytes = readZipEntry(source, name, options);
+    return bytes ? new TextDecoder().decode(bytes) : undefined;
+}
+/** Portable names exclude traversal, device names, streams and ambiguous aliases. */
+export function safeEntryPath(root, name) {
+    const normalized = name.replaceAll("\\", "/");
+    const parts = normalized.replace(/\/$/, "").split("/");
+    if (!name ||
+        normalized.startsWith("/") ||
+        isAbsolute(normalized) ||
+        parts.some((part) => !part ||
+            part === "." ||
+            part === ".." ||
+            [...part].some((character) => character.charCodeAt(0) < 32) ||
+            /[:<>"|?*]/.test(part) ||
+            /[. ]$/.test(part) ||
+            /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part))) {
+        throw new Error(`Unsafe ZIP entry path: ${name}`);
+    }
+    const base = resolve(root);
+    const target = resolve(base, ...parts);
+    if (!target.startsWith(base.endsWith(sep) ? base : base + sep))
+        throw new Error(`ZIP entry escapes destination: ${name}`);
+    return target;
+}
+function statIfPresent(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+const outside = (rel) => rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+/**
+ * Canonicalize the directory holding a caller-named path. The caller chose
+ * that location, so links among its ancestors (macOS /tmp and /var, a linked
+ * home directory) are resolved once here. The named path itself and everything
+ * below it stay subject to assertNoLinks, which is where a planted link could
+ * redirect a write. Missing directories are appended unresolved and checked
+ * again once they exist.
+ */
+function anchored(path) {
+    const named = resolve(path);
+    const missing = [basename(named)];
+    let existing = dirname(named);
+    while (!statIfPresent(existing) && dirname(existing) !== existing) {
+        missing.unshift(basename(existing));
+        existing = dirname(existing);
+    }
+    const anchor = realpathSync(existing);
+    return { anchor, path: join(anchor, ...missing) };
+}
+/**
+ * Inspect every existing component from the path up to, not including, its
+ * anchor, including a dangling link at the final path.
+ */
+function assertNoLinks(path, leaf, anchor) {
+    let current = resolve(path);
+    if (outside(relative(anchor, current)))
+        throw new Error(`ZIP path is outside its anchored directory: ${current}`);
+    let first = true;
+    while (current !== anchor) {
+        const stat = statIfPresent(current);
+        if (stat) {
+            if (stat.isSymbolicLink())
+                throw new Error(`Refusing ZIP path through a symbolic link: ${current}`);
+            if ((!first || leaf === "directory") && !stat.isDirectory())
+                throw new Error(`ZIP directory path is not a directory: ${current}`);
+            if (first && leaf === "file" && !stat.isFile())
+                throw new Error(`ZIP output is not a regular file: ${current}`);
+        }
+        current = dirname(current);
+        first = false;
+    }
+}
+function writeAtomic(path, bytes, overwrite, anchor) {
+    assertNoLinks(path, "file", anchor);
+    if (!overwrite && statIfPresent(path))
+        throw new Error(`ZIP output already exists: ${path}`);
+    mkdirSync(dirname(path), { recursive: true });
+    assertNoLinks(dirname(path), "directory", anchor);
+    const temp = join(dirname(path), `.zip-${randomUUID()}.tmp`);
+    let fd;
+    try {
+        fd = openSync(temp, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | (constants.O_NOFOLLOW ?? 0), 0o600);
+        writeFileSync(fd, bytes);
+        closeSync(fd);
+        fd = undefined;
+        assertNoLinks(path, "file", anchor);
+        if (overwrite)
+            renameSync(temp, path);
+        else {
+            linkSync(temp, path);
+            unlinkSync(temp);
+        }
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+        if (statIfPresent(temp))
+            unlinkSync(temp);
+    }
+}
+/** Preflight all selected names, collisions and existing filesystem paths before writing. */
+export function extractZip(source, dest, options = {}) {
+    const limits = limitsFor(options);
+    const bytes = bytesOf(source, limits);
+    const entries = inventory(bytes, limits).filter((entry) => (options.filter ?? (() => true))(entry.name));
+    const { anchor, path: root } = anchored(dest);
+    assertNoLinks(root, "directory", anchor);
+    const targets = new Map();
+    for (const entry of entries) {
+        const target = safeEntryPath(root, entry.name);
+        const key = target.toLowerCase();
+        if (targets.has(key))
+            throw new Error(`Colliding ZIP entry: ${entry.name}`);
+        targets.set(key, entry.directory);
+        assertNoLinks(target, entry.directory ? "directory" : "file", anchor);
+        if (!entry.directory && !options.overwrite && statIfPresent(target))
+            throw new Error(`ZIP output already exists: ${target}`);
+    }
+    for (const target of targets.keys()) {
+        let parent = dirname(target);
+        while (parent !== dirname(parent)) {
+            if (targets.get(parent) === false)
+                throw new Error(`ZIP file/directory collision: ${parent}`);
+            parent = dirname(parent);
+        }
+    }
+    const selected = new Set(entries.filter((entry) => !entry.directory).map((entry) => entry.name));
+    const files = readZipEntries(bytes, (name) => selected.has(name), options);
+    mkdirSync(root, { recursive: true });
+    for (const entry of entries) {
+        if (entry.directory) {
+            const path = safeEntryPath(root, entry.name);
+            assertNoLinks(path, "directory", anchor);
+            mkdirSync(path, { recursive: true });
+        }
+    }
+    for (const [name, data] of files)
+        writeAtomic(safeEntryPath(root, name), data, options.overwrite ?? false, anchor);
+    return [...files.keys()];
+}
+export function buildZip(inputs, options = {}) {
+    const limits = limitsFor(options);
+    // Inputs are matched against the base as the caller spelled it; reads go
+    // through its anchored form.
+    const named = resolve(options.base ?? ".");
+    const { anchor, path: base } = anchored(named);
+    assertNoLinks(base, "directory", anchor);
+    const tree = Object.create(null);
+    const entries = [];
+    const names = new Set();
+    let total = 0;
+    const add = (input) => {
+        const rel = relative(named, resolve(named, input));
+        if (!rel || outside(rel))
+            throw new Error(`ZIP input is outside its base directory: ${input}`);
+        const path = join(base, rel);
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink())
+            throw new Error(`Refusing ZIP input symbolic link: ${input}`);
+        assertNoLinks(path, stat.isDirectory() ? "directory" : "file", anchor);
+        if (stat.isDirectory()) {
+            for (const name of readdirSync(path).sort())
+                add(join(named, rel, name));
+            return;
+        }
+        if (!stat.isFile())
+            throw new Error(`ZIP input is not a regular file: ${input}`);
+        const name = rel.split(sep).join("/");
+        safeEntryPath(base, name);
+        if (Object.hasOwn(tree, name))
+            return;
+        if (names.has(name.toLowerCase()))
+            throw new Error(`Colliding ZIP input: ${name}`);
+        total += stat.size;
+        if (stat.size > limits.entryBytes ||
+            total > limits.totalBytes ||
+            entries.length >= limits.entries)
+            throw new Error("ZIP inputs exceed size or entry count limit");
+        const bytes = readBoundedFile(path, Math.min(stat.size, limits.entryBytes), true);
+        if (bytes.byteLength !== stat.size)
+            throw new Error(`ZIP input changed while reading: ${name}`);
+        names.add(name.toLowerCase());
+        tree[name] = [bytes, { mtime: stat.mtime }];
+        entries.push(name);
+    };
+    for (const input of [...inputs].sort())
+        add(input);
+    if (!entries.length)
+        throw new Error("Nothing to ZIP: inputs contain no files");
+    const bytes = zipSync(tree, { level: options.level ?? 6 });
+    if (bytes.byteLength > limits.archiveBytes)
+        throw new Error("ZIP archive exceeds compressed byte limit");
+    return { bytes, entries };
+}
+export function createZip(archive, inputs, options = {}) {
+    const { anchor, path } = anchored(archive);
+    assertNoLinks(path, "file", anchor);
+    if (!options.overwrite && statIfPresent(path))
+        throw new Error(`ZIP output already exists: ${archive}`);
+    const result = buildZip(inputs, options);
+    writeAtomic(path, result.bytes, options.overwrite ?? false, anchor);
+    return result.entries;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "description": "Multi-agent coordination for AI coding agents - Claude Code, Cursor, and Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",
@@ -182,6 +182,11 @@
       "types": "./dist/lib/format.d.ts",
       "import": "./dist/lib/format.js"
     },
+    "./lib/zip": {
+      "bun": "./src/lib/zip/index.ts",
+      "types": "./dist/lib/zip/index.d.ts",
+      "import": "./dist/lib/zip/index.js"
+    },
     "./lib/headless": {
       "bun": "./src/lib/headless/index.ts",
       "types": "./dist/lib/headless/index.d.ts",
@@ -266,6 +271,7 @@
     "test:web": "cd web && bun install && bun test",
     "test:integration": "bash tests/integration/run.sh",
     "smoke": "node scripts/smoke-test.mjs",
+    "check:local": "node scripts/check-local.mjs",
     "docs:dev": "bun run --cwd docs dev",
     "docs:build": "bun run --cwd docs build",
     "brand:showcase": "node scripts/build-brand-showcase.mjs",
@@ -283,6 +289,7 @@
     "@sinclair/typebox": "^0.34.52",
     "axe-core": "^4.12.1",
     "commander": "^14.0.3",
+    "fflate": "^0.8.2",
     "gpt-tokenizer": "^3.4.0",
     "js-yaml": "^4.3.0",
     "linkedom": "^0.18.0",

package/src/commander.ts

@@ -280,6 +280,38 @@ export async function registerHarneryLogStorageCommands(
   return parent;
 }
 
+export interface HarneryTunnelCommandOptions {
+  emit?: EmitContext;
+  context?: HarneryProgramContext;
+}
+
+/**
+ * Mount `tunnel` under `parent`, for a host whose own program does not come
+ * from `createHarneryProgram` (a host CLI that exposes the tunnel as one of its
+ * command families).
+ */
+export async function registerHarneryTunnelCommand(
+  parent: Command,
+  options: HarneryTunnelCommandOptions = {},
+): Promise<Command> {
+  const { registerTunnelCommand } = await import("./commands/tunnel.ts");
+  registerTunnelCommand(parent, options.emit ?? defaultEmit, options.context);
+  return parent;
+}
+
+export type { RefreshCurrentOptions, RefreshCurrentResult } from "./commands/tunnel.ts";
+
+/**
+ * `tunnel allow add --current` as a function: allow this machine's public
+ * addresses and optionally reload running gates, keeping their URLs.
+ */
+export async function refreshTunnelCurrentAddress(
+  options: import("./commands/tunnel.ts").RefreshCurrentOptions,
+): Promise<import("./commands/tunnel.ts").RefreshCurrentResult> {
+  const { refreshCurrentAddress } = await import("./commands/tunnel.ts");
+  return refreshCurrentAddress(options);
+}
+
 export function createHarneryProgram(opts: HarneryContextOpts = {}): Command {
   const program = new Command();
   const emit = opts.emit ?? defaultEmit;