harnery 0.41.0 → 0.43.0

package/dist/lib/guarded-remove.js

@@ -0,0 +1,310 @@
+import { spawnSync } from "node:child_process";
+import { lstatSync, readdirSync, readlinkSync, realpathSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, parse, relative, resolve, sep } from "node:path";
+const protectedNames = new Set([".git", ".harnery", ".credentials", ".ssh", ".gnupg"]);
+const MAX_ENTRIES = 10_000;
+/** Permanent removal is deliberately limited to inspected, untracked local outputs. */
+export function guardedRemove(paths, options, checkClaims = () => { }) {
+    const cwd = realpathSync(process.cwd());
+    const root = checkedPath(options.root, new Set(), true);
+    const allowed = allowedProtected(options.allowProtected ?? [], root, options.liveRoots ?? []);
+    const rootStat = lstatSync(root);
+    const rootFingerprint = fingerprint(rootStat);
+    if (!rootStat.isDirectory())
+        throw new Error("--root must be a directory");
+    if (root === parse(root).root || root === realpathSync(homedir()))
+        throw new Error("--root cannot be a filesystem root or home directory");
+    if (paths.length === 0 || paths.length > 100)
+        throw new Error("Supply 1-100 explicit targets");
+    const targets = paths.map((path) => checkedPath(path, allowed));
+    const snapshots = new Map();
+    const removedProtected = new Set();
+    const links = [];
+    const gitDirs = new Set();
+    let bytes = 0;
+    const devices = new Set();
+    for (const target of targets) {
+        const home = realpathSync(homedir());
+        if (target === home || strictlyInside(target, home))
+            throw new Error(`Cannot remove the home directory or its ancestor: ${target}`);
+        const systemRoots = process.platform === "win32"
+            ? [
+                process.env.SystemRoot,
+                process.env.ProgramFiles,
+                process.env["ProgramFiles(x86)"],
+            ].filter((value) => Boolean(value))
+            : [
+                "/etc",
+                "/usr",
+                "/boot",
+                "/dev",
+                "/proc",
+                "/sys",
+                "/bin",
+                "/sbin",
+                "/lib",
+                "/lib64",
+                "/run",
+            ];
+        if (systemRoots.some((system) => target === resolve(system) ||
+            strictlyInside(resolve(system), target) ||
+            strictlyInside(target, resolve(system))))
+            throw new Error(`System files are protected: ${target}`);
+        if (!strictlyInside(root, target))
+            throw new Error(`Target must be strictly inside --root: ${target}`);
+        if (target === cwd || strictlyInside(target, cwd))
+            throw new Error(`Cannot remove the working directory or its ancestor: ${target}`);
+        if (targets.some((other) => other !== target && strictlyInside(other, target)) ||
+            targets.filter((other) => other === target).length > 1)
+            throw new Error("Targets must not duplicate or contain one another");
+        const stat = lstatSync(target);
+        if (stat.dev !== rootStat.dev)
+            throw new Error(`Target crosses a mount boundary: ${target}`);
+        if (stat.isDirectory() && !options.recursive)
+            throw new Error(`Directory removal requires --recursive: ${target}`);
+        const device = stat.dev;
+        devices.add(device);
+        const pending = [target];
+        while (pending.length) {
+            const path = pending.pop();
+            const info = lstatSync(path);
+            if (basename(path) === ARTIFACT_RECORD && insideArtifactWorkspace(path, null))
+                throw new Error(`An artifact's record is managed by the artifact commands: ${path}`);
+            if (protectedNames.has(basename(path).toLowerCase())) {
+                if (!allowed.has(path))
+                    throw new Error(protectedMessage(path));
+                removedProtected.add(path);
+            }
+            if (info.isSymbolicLink()) {
+                // A link inside the tree is removed as a link; its target is never
+                // read, followed, or counted. (The target itself and its ancestors
+                // were already refused if they were links, in checkedPath.)
+                if (path === target)
+                    throw new Error(`Path contains a symlink: ${path}`);
+                if (snapshots.size >= MAX_ENTRIES)
+                    throw new Error(`Removal exceeds the ${MAX_ENTRIES}-entry limit; use the owning cleanup command`);
+                snapshots.set(path, fingerprint(info));
+                links.push({ path, target: readlinkSync(path) });
+                continue;
+            }
+            if (info.dev !== device || (!info.isDirectory() && !info.isFile()))
+                throw new Error(`Mount boundary or special file cannot be removed: ${path}`);
+            if (snapshots.size >= MAX_ENTRIES)
+                throw new Error(`Removal exceeds the ${MAX_ENTRIES}-entry limit; use the owning cleanup command`);
+            snapshots.set(path, fingerprint(info));
+            if (info.isFile())
+                bytes += info.size;
+            else {
+                const names = readdirSync(path);
+                if (names.includes("HEAD") &&
+                    names.includes("objects") &&
+                    names.includes("config") &&
+                    !insideAllowed(path, allowed))
+                    throw new Error(`Repository metadata cannot be removed: ${path}. To remove it on purpose, name it with --allow-protected ${path}`);
+                if (allowed.has(path))
+                    removedProtected.add(path);
+                if (isRepositoryMetadata(path))
+                    gitDirs.add(path);
+                for (const name of names)
+                    pending.push(resolve(path, name));
+            }
+        }
+        assertUntracked(target);
+    }
+    if (devices.size > 1)
+        throw new Error("Targets must be on one filesystem");
+    for (const path of allowed)
+        if (!removedProtected.has(path))
+            throw new Error(`--allow-protected names a path no target removes: ${path}`);
+    for (const dir of gitDirs)
+        assertNoUnpushedHistory(dir);
+    checkClaims(targets);
+    const report = {
+        schema: "harnery.removal/v1",
+        applied: false,
+        root,
+        targets,
+        entries: snapshots.size,
+        bytes,
+        protected: [...removedProtected].sort(),
+        links,
+    };
+    if (!options.yes || options.dryRun)
+        return report;
+    // Recheck the entire batch before its first mutation. Filesystem changes after
+    // these checks remain possible; this is a guard, not a transactional filesystem.
+    if (checkedPath(options.root, new Set(), true) !== root ||
+        fingerprint(lstatSync(root)) !== rootFingerprint)
+        throw new Error("Allowed root changed during inspection");
+    for (const target of targets) {
+        checkedPath(target, allowed);
+        assertUntracked(target);
+    }
+    for (const dir of gitDirs)
+        assertNoUnpushedHistory(dir);
+    checkClaims(targets);
+    for (const [path, previous] of snapshots) {
+        if (fingerprint(lstatSync(path)) !== previous)
+            throw new Error(`Target changed during inspection: ${path}`);
+    }
+    for (const target of targets)
+        rmSync(target, { recursive: Boolean(options.recursive), force: false });
+    return { ...report, applied: true };
+}
+/** The metadata file the artifact commands keep in each artifact workspace. */
+const ARTIFACT_RECORD = ".harnery-artifact.json";
+/**
+ * True when `path` lies strictly inside one artifact workspace,
+ * <dir>/.harnery/artifacts/<id>/..., under the `.harnery` component `state`
+ * (any `.harnery` when null). Artifact workspaces hold local outputs, so their
+ * contents may be removed; the workspace itself, its record file, and the rest
+ * of Harnery state stay protected and follow the artifact commands. `orSelf`
+ * accepts the workspace directory itself (used for --root, which is never removed).
+ */
+function insideArtifactWorkspace(path, state, orSelf = false) {
+    const parts = path.split(sep);
+    for (let i = 0; i < parts.length; i++) {
+        if (parts[i].toLowerCase() !== ".harnery")
+            continue;
+        if (state !== null && parts.slice(0, i + 1).join(sep) !== state)
+            continue;
+        // .harnery / artifacts / <id> / <something>
+        return (parts[i + 1] === "artifacts" && Boolean(parts[i + 2]) && parts.length >= i + (orSelf ? 3 : 4));
+    }
+    return false;
+}
+function protectedMessage(path) {
+    return `Protected state cannot be removed: ${path}. To remove it on purpose, name it with --allow-protected ${path}`;
+}
+function insideAllowed(path, allowed) {
+    for (const entry of allowed)
+        if (path === entry || strictlyInside(entry, path))
+            return true;
+    return false;
+}
+/**
+ * Resolves the caller's --allow-protected paths. Each must be one exact
+ * protected path strictly inside the root, reached without symlinks, and
+ * never the Git metadata or Harnery state of a live workspace root.
+ */
+function allowedProtected(paths, root, liveRoots) {
+    const allowed = new Set();
+    const live = liveRoots.map((dir) => resolve(dir));
+    for (const input of paths) {
+        if (!input?.trim() || /[\0\r\n*?[\]$]/.test(input))
+            throw new Error("Use a nonempty explicit --allow-protected path without wildcards");
+        const path = resolve(input);
+        let cursor = dirname(path);
+        while (true) {
+            if (lstatSync(cursor).isSymbolicLink())
+                throw new Error(`--allow-protected path contains a symlink: ${cursor}`);
+            const parent = dirname(cursor);
+            if (parent === cursor)
+                break;
+            cursor = parent;
+        }
+        const info = lstatSync(path);
+        if (info.isSymbolicLink())
+            throw new Error(`--allow-protected path is a symlink: ${path}`);
+        if (!strictlyInside(root, path))
+            throw new Error(`--allow-protected path must be strictly inside --root: ${path}`);
+        const named = protectedNames.has(basename(path).toLowerCase());
+        if (!named && !(info.isDirectory() && isRepositoryMetadata(path)))
+            throw new Error(`--allow-protected must name a protected path itself: ${path}`);
+        for (const dir of live) {
+            const own = [".git", ".harnery"].map((name) => resolve(dir, name));
+            if (path === dir ||
+                strictlyInside(path, dir) ||
+                own.some((state) => path === state || strictlyInside(state, path)))
+                throw new Error(`The live workspace's own state cannot be allowed: ${path}`);
+        }
+        allowed.add(realpathSync(path));
+    }
+    return allowed;
+}
+function isRepositoryMetadata(dir) {
+    const names = readdirSync(dir);
+    return names.includes("HEAD") && names.includes("objects") && names.includes("config");
+}
+/**
+ * Removing a repository's metadata loses any commit that exists nowhere
+ * else. An allowed Git directory must have no branch or tag commit missing
+ * from its remotes; anything that cannot be checked is refused.
+ */
+function assertNoUnpushedHistory(gitDir) {
+    const result = spawnSync("git", [
+        "--git-dir",
+        gitDir,
+        "rev-list",
+        "--max-count=1",
+        "--branches",
+        "--tags",
+        "--not",
+        "--remotes",
+    ], {
+        encoding: "utf8",
+        timeout: 10_000,
+        env: { ...process.env, LC_ALL: "C", GIT_DIR: undefined, GIT_WORK_TREE: undefined },
+    });
+    if (result.error || result.status !== 0)
+        throw new Error(`Cannot confirm ${gitDir} holds no unpushed history`);
+    if (result.stdout.trim())
+        throw new Error(`Repository has commits not on any remote: ${gitDir}`);
+}
+function strictlyInside(parent, child) {
+    const rel = relative(parent, child);
+    return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+function checkedPath(input, allowed = new Set(), isRoot = false) {
+    if (!input?.trim() || /[\0\r\n*?[\]$]/.test(input))
+        throw new Error("Use a nonempty explicit path without wildcards or unresolved variables");
+    const path = resolve(input);
+    let cursor = path;
+    while (true) {
+        if (protectedNames.has(basename(cursor).toLowerCase()) &&
+            !allowed.has(cursor) &&
+            !insideArtifactWorkspace(path, cursor, isRoot))
+            throw new Error(cursor === path ? protectedMessage(path) : `Protected state contains this path: ${cursor}`);
+        const info = lstatSync(cursor);
+        if (info.isSymbolicLink())
+            throw new Error(`Path contains a symlink: ${cursor}`);
+        const parent = dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    return realpathSync(path);
+}
+function fingerprint(stat) {
+    return [stat.dev, stat.ino, stat.mode, stat.size, stat.mtimeMs, stat.ctimeMs].join(":");
+}
+function assertUntracked(target) {
+    const git = (args) => spawnSync("git", ["-C", dirname(target), ...args], {
+        encoding: "utf8",
+        timeout: 10_000,
+        maxBuffer: 4 * 1024 * 1024,
+        env: {
+            ...process.env,
+            LC_ALL: "C",
+            GIT_LITERAL_PATHSPECS: "1",
+            GIT_DIR: undefined,
+            GIT_WORK_TREE: undefined,
+            GIT_INDEX_FILE: undefined,
+        },
+    });
+    const detected = git(["rev-parse", "--show-toplevel"]);
+    if (detected.error)
+        throw new Error(`Cannot check Git ownership: ${detected.error.message}`);
+    if (detected.status !== 0) {
+        if (detected.status === 128 && detected.stderr.startsWith("fatal: not a git repository"))
+            return;
+        throw new Error(`Cannot check Git ownership: ${detected.stderr.trim()}`);
+    }
+    const repo = detected.stdout.trim();
+    const tracked = git(["ls-files", "--cached", "-z", "--full-name", "--", target]);
+    if (tracked.error || tracked.status !== 0)
+        throw new Error(`Cannot inspect Git index in ${repo}`);
+    if (tracked.stdout.length)
+        throw new Error(`Tracked files are protected; use git rm for intentional source removal: ${target}`);
+}

package/dist/lib/instructions/templates.js

@@ -67,8 +67,7 @@ export function renderInstructionsBlock(binName, skills = { decide: true, counci
     return `## harnery coordination
 
 This project runs [harnery](https://harnery.com) for multi-agent coordination.
-You share this checkout with other agents; the surfaces below keep you oriented
-and out of each other's way, and let you dispatch a team of your own when a job
+You share this checkout with other agents; the surfaces below keep you oriented and out of each other's way, and let you dispatch a team of your own when a job
 is bigger than one session. Run \`${b} <command> --help\` for any command's full
 surface. ${deeper}
 
@@ -81,8 +80,7 @@ widely-shared files.
 **Task lifecycle.** Beside the activity peers already see, declare whether your
 objective is still open: \`${b} agents lifecycle blocked --reason "<why>"\` when
 it cannot proceed, \`${b} agents lifecycle done\` when it is complete, and
-\`${b} agents lifecycle active\` to reopen. \`done\` requires a current task and
-a passing Git finalization check (dirty or unpushed work refuses, and nothing is
+\`${b} agents lifecycle active\` to reopen. \`done\` requires a current task and a passing Git finalization check (dirty or unpushed work refuses, and nothing is
 written). Ordinary \`set-task\` calls never change lifecycle, and a transition
 that re-mints the session title tells you the new name to copy. ${endPointer}
 
@@ -107,8 +105,7 @@ It reclaims an abandoned namesake (no live process) and refuses only when anothe
 live process still holds the name; never hand-edit Harnery's history, heartbeat,
 or derived identity cache.
 
-**Declare intent on shell commands.** Every command you run is captured to the
-coordination ledger (\`.harnery/ledgers/v3/\`). Lead a shell command with a
+**Declare intent on shell commands.** Every command you run is captured to the coordination ledger (\`.harnery/ledgers/v3/\`). Lead a shell command with a
 \`# intent: <why>\` comment (or set the tool's description) so the recorded event
 carries a reason instead of \`(no intent)\`; the [tool-intent
 guide](https://harnery.com/guides/tool-intent/) owns the details.
@@ -132,6 +129,10 @@ After review, use \`${b} artifacts discard <id> --reason "<why no longer needed>
 Do not create a repo-root temp directory; \`${b} artifacts clean\` previews
 expired cleanup and requires \`--yes\` to delete anything.
 
+**Removing local outputs.** Use \`${b} rm --root <directory> <paths...>\` instead of shell \`rm\`, which skips resolved-path, Git ownership, and peer-claim checks. Preview
+is the default; \`--yes\` deletes permanently and \`--recursive\` permits directories.
+Use \`git rm\` for tracked source and the artifact commands for managed evidence.
+
 **Local file links.** When the operator should open a local repo file, mint the
 URL with \`${b} files url <repo-relative-path>\` instead of guessing it. HTML opens
 as a real page with working scripts and relative assets; other files open in the
@@ -142,8 +143,7 @@ can't resolve from the repo, file it instead. \`${b} decision file "<question>"\
 records it and lets you proceed on a stated default; \`${b} decision search "<terms>"\`
 surfaces prior decisions, so check for precedent before re-deciding. ${decidePointer}
 
-**Councils.** For a hard or contested decision, convene a council of agents.
-\`${b} council create "<objective>"\` runs structured rounds toward a decision. ${councilPointer}`;
+**Councils.** For a hard or contested decision, convene a council of agents. \`${b} council create "<objective>"\` runs structured rounds toward a decision. ${councilPointer}`;
 }
 function decideBody(b) {
     return `The decision docket is a persistent queue for decisions you would otherwise

package/dist/lib/tunnel/allowlist.d.ts

@@ -0,0 +1,44 @@
+export type IpFamily = 4 | 6;
+export interface ParsedIp {
+    family: IpFamily;
+    value: bigint;
+}
+export interface AllowEntry extends ParsedIp {
+    /** Prefix length in bits (32 or 128 for a single address). */
+    prefix: number;
+}
+/**
+ * Parse one address. Returns null for anything that is not an IP literal. A
+ * zone id (`fe80::1%en0`) is dropped, and an IPv4-mapped IPv6 address is
+ * reported as the IPv4 address it carries.
+ */
+export declare function parseIp(raw: string): ParsedIp | null;
+/**
+ * Parse an allowlist entry: `203.0.113.8`, `203.0.113.0/24`, `2601:db8::1`, or
+ * `2601:db8:1:2::/64`. Host bits below the prefix are cleared, so
+ * `203.0.113.77/24` means the network `203.0.113.0/24`. Returns null when the
+ * entry is not a valid address or its prefix length is out of range.
+ */
+export declare function parseAllowEntry(raw: string): AllowEntry | null;
+/** Canonical text of an address (dotted quad, or compressed lowercase IPv6). */
+export declare function formatIp(ip: ParsedIp): string;
+/** Canonical text of an entry; a single address carries no `/len` suffix. */
+export declare function formatAllowEntry(entry: AllowEntry): string;
+/**
+ * Canonical spelling of an allowlist entry, or null when invalid. Two spellings
+ * of one address or range (`2601:DB8:0:0::1`, `2601:db8::1`) normalize equal.
+ */
+export declare function normalizeAllowEntry(raw: string): string | null;
+export interface Allowlist {
+    entries: AllowEntry[];
+    /** Entries that could not be parsed; they never match anything. */
+    invalid: string[];
+}
+export declare function compileAllowlist(rawEntries: readonly string[]): Allowlist;
+/** True when `ip` lies inside any entry. A missing or malformed address never matches. */
+export declare function allowlistMatches(list: Allowlist, ip: string): boolean;
+/** The IPv6 /64 network prefix of an address, as a canonical `…/64` entry. */
+export declare function ipv6Slash64(address: string): string | null;
+/** A single IPv4 address as a `/32` entry. */
+export declare function ipv4Slash32(address: string): string | null;
+//# sourceMappingURL=allowlist.d.ts.map

package/dist/lib/tunnel/allowlist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowlist.d.ts","sourceRoot":"","sources":["../../../src/lib/tunnel/allowlist.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,CAAC;AAE7B,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,QAAQ,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAW,SAAQ,QAAQ;IAC1C,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;CAChB;AAyCD;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAYpD;AAQD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAmB9D;AAyBD,gFAAgF;AAChF,wBAAgB,QAAQ,CAAC,EAAE,EAAE,QAAQ,GAAG,MAAM,CAO7C;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAG1D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG9D;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,mEAAmE;IACnE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAWzE;AAED,0FAA0F;AAC1F,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CASrE;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI1D;AAED,8CAA8C;AAC9C,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI1D"}

package/dist/lib/tunnel/allowlist.js

@@ -0,0 +1,204 @@
+// Address allowlist for the tunnel gate: exact addresses and CIDR ranges, IPv4
+// and IPv6. Pure functions with no I/O, shared by the gate worker (matching)
+// and the `tunnel allow` commands (validation + canonical spelling).
+//
+// An IPv6 phone and laptop on one Wi-Fi network have different addresses but
+// share a /64 prefix, so a range entry such as `2601:db8:1:2::/64` admits both.
+// An entry without a prefix length is a single address (/32 or /128).
+//
+// IPv4-mapped IPv6 addresses (`::ffff:203.0.113.8`) are IPv4 addresses reached
+// through a dual-stack socket, so they parse and match as IPv4.
+import { isIPv4, isIPv6 } from "node:net";
+const FULL_BITS = { 4: 32, 6: 128 };
+function parseIpv4(text) {
+    if (!isIPv4(text))
+        return null;
+    let value = 0n;
+    for (const part of text.split("."))
+        value = (value << 8n) | BigInt(Number(part));
+    return value;
+}
+function parseIpv6(text) {
+    if (!isIPv6(text))
+        return null;
+    let rest = text;
+    // A trailing dotted quad (`::ffff:1.2.3.4`, `64:ff9b::1.2.3.4`) is two groups.
+    const dotted = rest.match(/^(.*:)(\d+\.\d+\.\d+\.\d+)$/);
+    if (dotted) {
+        const v4 = parseIpv4(dotted[2]);
+        if (v4 === null)
+            return null;
+        rest = `${dotted[1]}${(v4 >> 16n).toString(16)}:${(v4 & 0xffffn).toString(16)}`;
+    }
+    const halves = rest.split("::");
+    if (halves.length > 2)
+        return null;
+    const head = halves[0] ? halves[0].split(":") : [];
+    const tail = halves.length === 2 && halves[1] ? halves[1].split(":") : [];
+    const missing = 8 - head.length - tail.length;
+    if (halves.length === 1 ? missing !== 0 : missing < 1)
+        return null;
+    const groups = [
+        ...head,
+        ...Array.from({ length: halves.length === 2 ? missing : 0 }, () => "0"),
+        ...tail,
+    ];
+    if (groups.length !== 8)
+        return null;
+    let value = 0n;
+    for (const group of groups) {
+        if (!/^[0-9a-f]{1,4}$/i.test(group))
+            return null;
+        value = (value << 16n) | BigInt(Number.parseInt(group, 16));
+    }
+    return value;
+}
+/**
+ * Parse one address. Returns null for anything that is not an IP literal. A
+ * zone id (`fe80::1%en0`) is dropped, and an IPv4-mapped IPv6 address is
+ * reported as the IPv4 address it carries.
+ */
+export function parseIp(raw) {
+    let text = raw.trim();
+    if (text.startsWith("[") && text.endsWith("]"))
+        text = text.slice(1, -1);
+    const zone = text.indexOf("%");
+    if (zone !== -1)
+        text = text.slice(0, zone);
+    if (!text)
+        return null;
+    const v4 = parseIpv4(text);
+    if (v4 !== null)
+        return { family: 4, value: v4 };
+    const v6 = parseIpv6(text);
+    if (v6 === null)
+        return null;
+    if (v6 >> 32n === 0xffffn)
+        return { family: 4, value: v6 & 0xffffffffn };
+    return { family: 6, value: v6 };
+}
+function maskFor(family, prefix) {
+    const bits = BigInt(FULL_BITS[family]);
+    const host = bits - BigInt(prefix);
+    return ((1n << bits) - 1n) ^ ((1n << host) - 1n);
+}
+/**
+ * Parse an allowlist entry: `203.0.113.8`, `203.0.113.0/24`, `2601:db8::1`, or
+ * `2601:db8:1:2::/64`. Host bits below the prefix are cleared, so
+ * `203.0.113.77/24` means the network `203.0.113.0/24`. Returns null when the
+ * entry is not a valid address or its prefix length is out of range.
+ */
+export function parseAllowEntry(raw) {
+    const text = raw.trim();
+    const slash = text.indexOf("/");
+    const address = parseIp(slash === -1 ? text : text.slice(0, slash));
+    if (!address)
+        return null;
+    let prefix = FULL_BITS[address.family];
+    if (slash !== -1) {
+        const lengthText = text.slice(slash + 1);
+        if (!/^\d{1,3}$/.test(lengthText))
+            return null;
+        prefix = Number(lengthText);
+        // A prefix on an IPv4-mapped IPv6 entry counts from the IPv6 start, so
+        // `::ffff:1.2.3.0/120` is the IPv4 /24. Anything shorter is not an IPv4 range.
+        if (address.family === 4 && /:/.test(text.slice(0, slash))) {
+            if (prefix < 96 || prefix > 128)
+                return null;
+            prefix -= 96;
+        }
+        if (prefix > FULL_BITS[address.family])
+            return null;
+    }
+    return { ...address, prefix, value: address.value & maskFor(address.family, prefix) };
+}
+function compress(groups) {
+    // RFC 5952: collapse the longest run of two or more zero groups (first wins).
+    let bestStart = -1;
+    let bestLen = 0;
+    for (let i = 0; i < 8;) {
+        if (groups[i] !== 0) {
+            i++;
+            continue;
+        }
+        let j = i;
+        while (j < 8 && groups[j] === 0)
+            j++;
+        if (j - i > bestLen) {
+            bestStart = i;
+            bestLen = j - i;
+        }
+        i = j;
+    }
+    if (bestLen < 2)
+        return groups.map((g) => g.toString(16)).join(":");
+    const left = groups.slice(0, bestStart).map((g) => g.toString(16));
+    const right = groups.slice(bestStart + bestLen).map((g) => g.toString(16));
+    return `${left.join(":")}::${right.join(":")}`;
+}
+/** Canonical text of an address (dotted quad, or compressed lowercase IPv6). */
+export function formatIp(ip) {
+    if (ip.family === 4) {
+        return [24n, 16n, 8n, 0n].map((shift) => Number((ip.value >> shift) & 0xffn)).join(".");
+    }
+    const groups = [];
+    for (let i = 7; i >= 0; i--)
+        groups.push(Number((ip.value >> BigInt(i * 16)) & 0xffffn));
+    return compress(groups);
+}
+/** Canonical text of an entry; a single address carries no `/len` suffix. */
+export function formatAllowEntry(entry) {
+    const address = formatIp(entry);
+    return entry.prefix === FULL_BITS[entry.family] ? address : `${address}/${entry.prefix}`;
+}
+/**
+ * Canonical spelling of an allowlist entry, or null when invalid. Two spellings
+ * of one address or range (`2601:DB8:0:0::1`, `2601:db8::1`) normalize equal.
+ */
+export function normalizeAllowEntry(raw) {
+    const entry = parseAllowEntry(raw);
+    return entry ? formatAllowEntry(entry) : null;
+}
+export function compileAllowlist(rawEntries) {
+    const entries = [];
+    const invalid = [];
+    for (const raw of rawEntries) {
+        const text = raw.trim();
+        if (!text)
+            continue;
+        const entry = parseAllowEntry(text);
+        if (entry)
+            entries.push(entry);
+        else
+            invalid.push(text);
+    }
+    return { entries, invalid };
+}
+/** True when `ip` lies inside any entry. A missing or malformed address never matches. */
+export function allowlistMatches(list, ip) {
+    const address = parseIp(ip);
+    if (!address)
+        return false;
+    for (const entry of list.entries) {
+        if (entry.family !== address.family)
+            continue;
+        const mask = maskFor(entry.family, entry.prefix);
+        if ((address.value & mask) === entry.value)
+            return true;
+    }
+    return false;
+}
+/** The IPv6 /64 network prefix of an address, as a canonical `…/64` entry. */
+export function ipv6Slash64(address) {
+    const ip = parseIp(address);
+    if (!ip || ip.family !== 6)
+        return null;
+    return formatAllowEntry({ ...ip, prefix: 64, value: ip.value & maskFor(6, 64) });
+}
+/** A single IPv4 address as a `/32` entry. */
+export function ipv4Slash32(address) {
+    const ip = parseIp(address);
+    if (!ip || ip.family !== 4)
+        return null;
+    return `${formatIp(ip)}/32`;
+}

package/dist/lib/tunnel/current-address.d.ts

@@ -0,0 +1,41 @@
+import type { TunnelConfig } from "./state.js";
+export declare const TRACE_URL_V4 = "https://1.1.1.1/cdn-cgi/trace";
+export declare const TRACE_URL_V6 = "https://[2606:4700:4700::1111]/cdn-cgi/trace";
+export interface DetectedAddresses {
+    v4?: string;
+    v6?: string;
+    /** One note per family that could not be read. */
+    failures: string[];
+}
+export interface DetectOptions {
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+    /** Tries per family; a transient failure on a flaky network should not drop an address. */
+    attempts?: number;
+}
+/** The `ip=` value of a Cloudflare trace body, or null. */
+export declare function parseTraceIp(body: string): string | null;
+/** Both families in parallel. A family that fails is reported, not thrown. */
+export declare function detectPublicAddresses(options?: DetectOptions): Promise<DetectedAddresses>;
+export interface CurrentAddressPlan {
+    config: TunnelConfig;
+    /** Entries newly present in the allowlist. */
+    added: string[];
+    /** Automatic entries from an earlier refresh that are now gone. */
+    removed: string[];
+    /** The automatic entries after this refresh (the detected, not already listed by hand). */
+    automatic: string[];
+    changed: boolean;
+    warnings: string[];
+}
+/**
+ * Fold freshly detected addresses into the allowlist.
+ *
+ * When nothing was detected the config comes back untouched with a warning:
+ * a failed lookup must never empty the list. When at least one family was
+ * detected, a family that was not is treated as absent from this network, so
+ * its old automatic entry goes. The entries for the detected families replace
+ * every previous automatic entry; manual entries are kept in place.
+ */
+export declare function planCurrentAddresses(config: TunnelConfig, detected: DetectedAddresses): CurrentAddressPlan;
+//# sourceMappingURL=current-address.d.ts.map

package/dist/lib/tunnel/current-address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"current-address.d.ts","sourceRoot":"","sources":["../../../src/lib/tunnel/current-address.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,eAAO,MAAM,YAAY,kCAAkC,CAAC;AAC5D,eAAO,MAAM,YAAY,iDAAiD,CAAC;AAE3E,MAAM,WAAW,iBAAiB;IAChC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,2DAA2D;AAC3D,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGxD;AAoBD,8EAA8E;AAC9E,wBAAsB,qBAAqB,CACzC,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAgB5B;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,YAAY,CAAC;IACrB,8CAA8C;IAC9C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,mEAAmE;IACnE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,2FAA2F;IAC3F,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAOD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,iBAAiB,GAC1B,kBAAkB,CAkDpB"}