harnery 0.42.0 → 0.44.0

package/dist/lib/guarded-remove.js

@@ -1,20 +1,43 @@
 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";
+import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
 const protectedNames = new Set([".git", ".harnery", ".credentials", ".ssh", ".gnupg"]);
 const MAX_ENTRIES = 10_000;
+const MAX_OWNED_ARTIFACT_ENTRIES = 100_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 ?? []);
+    if (options.cleanClone) {
+        if (!options.recursive)
+            throw new Error("Clean clone removal requires --recursive");
+        if (options.allowProtected?.length)
+            throw new Error("Clean clone removal cannot be combined with --allow-protected");
+        if (!options.assertOwnedArtifact)
+            throw new Error("Clean clone removal requires one current caller-owned managed artifact");
+        options.assertOwnedArtifact(root);
+    }
+    const entryLimit = options.entryLimit ?? MAX_ENTRIES;
+    if (!Number.isSafeInteger(entryLimit) ||
+        entryLimit < 1 ||
+        entryLimit > MAX_OWNED_ARTIFACT_ENTRIES)
+        throw new Error(`The entry limit must be an integer from 1 to ${MAX_OWNED_ARTIFACT_ENTRIES}`);
+    const assertEntryLimitAuthority = () => {
+        if (entryLimit <= MAX_ENTRIES)
+            return;
+        if (!options.assertOwnedArtifact)
+            throw new Error("An entry limit above 10000 requires one current caller-owned managed artifact");
+        options.assertOwnedArtifact(root);
+    };
+    const allowed = allowedProtected(options.allowProtected ?? [], root, options.liveRoots ?? [], options.assertOwnedArtifact);
     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");
+    assertEntryLimitAuthority();
     if (paths.length === 0 || paths.length > 100)
         throw new Error("Supply 1-100 explicit targets");
     const targets = paths.map((path) => checkedPath(path, allowed));
@@ -22,6 +45,7 @@ export function guardedRemove(paths, options, checkClaims = () => { }) {
     const removedProtected = new Set();
     const links = [];
     const gitDirs = new Set();
+    const cleanClones = new Set();
     let bytes = 0;
     const devices = new Set();
     for (const target of targets) {
@@ -64,6 +88,10 @@ export function guardedRemove(paths, options, checkClaims = () => { }) {
         if (stat.isDirectory() && !options.recursive)
             throw new Error(`Directory removal requires --recursive: ${target}`);
         const device = stat.dev;
+        if (options.cleanClone) {
+            assertCleanClone(target);
+            cleanClones.add(target);
+        }
         devices.add(device);
         const pending = [target];
         while (pending.length) {
@@ -72,6 +100,12 @@ export function guardedRemove(paths, options, checkClaims = () => { }) {
             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 (options.cleanClone && basename(path) === ".git") {
+                    const clone = dirname(path);
+                    assertCleanClone(clone);
+                    cleanClones.add(clone);
+                    allowed.add(path);
+                }
                 if (!allowed.has(path))
                     throw new Error(protectedMessage(path));
                 removedProtected.add(path);
@@ -82,16 +116,16 @@ export function guardedRemove(paths, options, checkClaims = () => { }) {
                 // 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`);
+                if (snapshots.size >= entryLimit)
+                    throw new Error(`Removal exceeds the ${entryLimit}-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`);
+            if (snapshots.size >= entryLimit)
+                throw new Error(`Removal exceeds the ${entryLimit}-entry limit; use the owning cleanup command`);
             snapshots.set(path, fingerprint(info));
             if (info.isFile())
                 bytes += info.size;
@@ -126,6 +160,7 @@ export function guardedRemove(paths, options, checkClaims = () => { }) {
         root,
         targets,
         entries: snapshots.size,
+        entry_limit: entryLimit,
         bytes,
         protected: [...removedProtected].sort(),
         links,
@@ -137,12 +172,19 @@ export function guardedRemove(paths, options, checkClaims = () => { }) {
     if (checkedPath(options.root, new Set(), true) !== root ||
         fingerprint(lstatSync(root)) !== rootFingerprint)
         throw new Error("Allowed root changed during inspection");
+    assertEntryLimitAuthority();
+    if (options.cleanClone)
+        options.assertOwnedArtifact(root);
+    // Ownership may have been released or changed while the contents were inspected.
+    allowedProtected(options.allowProtected ?? [], root, options.liveRoots ?? [], options.assertOwnedArtifact);
     for (const target of targets) {
         checkedPath(target, allowed);
         assertUntracked(target);
     }
     for (const dir of gitDirs)
         assertNoUnpushedHistory(dir);
+    for (const clone of cleanClones)
+        assertCleanClone(clone);
     checkClaims(targets);
     for (const [path, previous] of snapshots) {
         if (fingerprint(lstatSync(path)) !== previous)
@@ -152,6 +194,44 @@ export function guardedRemove(paths, options, checkClaims = () => { }) {
         rmSync(target, { recursive: Boolean(options.recursive), force: false });
     return { ...report, applied: true };
 }
+/** A disposable clone must not be the only copy of work or a registered worktree. */
+function assertCleanClone(clone) {
+    const metadata = join(clone, ".git");
+    const stat = lstatSync(metadata);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error(`Clean clone removal requires a standalone .git directory: ${clone}`);
+    const git = (args) => {
+        const result = spawnSync("git", ["-c", "core.fsmonitor=false", "-C", clone, ...args], {
+            encoding: "utf8",
+            timeout: 10_000,
+            maxBuffer: 4 * 1024 * 1024,
+            env: {
+                ...process.env,
+                LC_ALL: "C",
+                GIT_DIR: undefined,
+                GIT_COMMON_DIR: undefined,
+                GIT_WORK_TREE: undefined,
+                GIT_INDEX_FILE: undefined,
+                GIT_OPTIONAL_LOCKS: "0",
+            },
+        });
+        if (result.error || result.status !== 0)
+            throw new Error(`Cannot verify clean clone ${clone}: git ${args[0]} failed`);
+        return result.stdout;
+    };
+    if (realpathSync(git(["rev-parse", "--show-toplevel"]).trim()) !== clone ||
+        realpathSync(resolve(clone, git(["rev-parse", "--git-common-dir"]).trim())) !== metadata)
+        throw new Error(`Clean clone removal refuses shared repository metadata: ${clone}`);
+    const worktrees = git(["worktree", "list", "--porcelain", "-z"])
+        .split("\0")
+        .filter((entry) => entry.startsWith("worktree "));
+    if (worktrees.length !== 1 || worktrees[0] !== `worktree ${clone}`)
+        throw new Error(`Clean clone removal refuses registered or linked worktrees: ${clone}`);
+    if (git(["status", "--porcelain=v1", "--untracked-files=all"]).trim())
+        throw new Error(`Clean clone has uncommitted or untracked work: ${clone}`);
+    if (git(["rev-list", "--max-count=1", "HEAD", "--all", "--reflog", "--not", "--remotes"]).trim())
+        throw new Error(`Clean clone has HEAD, ref or reflog commits not on any remote: ${clone}`);
+}
 /** The metadata file the artifact commands keep in each artifact workspace. */
 const ARTIFACT_RECORD = ".harnery-artifact.json";
 /**
@@ -188,9 +268,9 @@ function insideAllowed(path, allowed) {
  * 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) {
+function allowedProtected(paths, root, liveRoots, assertOwnedArtifact) {
     const allowed = new Set();
-    const live = liveRoots.map((dir) => resolve(dir));
+    const live = liveRoots.map((dir) => realpathSync(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");
@@ -213,11 +293,25 @@ function allowedProtected(paths, root, liveRoots) {
         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)))
+            if (path === dir || strictlyInside(path, dir))
                 throw new Error(`The live workspace's own state cannot be allowed: ${path}`);
+            for (const name of [".git", ".harnery"]) {
+                const state = resolve(dir, name);
+                if (path !== state && !strictlyInside(state, path))
+                    continue;
+                // Only an explicitly named copied state directory inside one owned
+                // artifact may cross the outer live-state ancestor. Other live roots
+                // (including a checkout inside that artifact) still veto the path.
+                if (name === ".harnery" &&
+                    basename(path) === ".harnery" &&
+                    info.isDirectory() &&
+                    dirname(root) === resolve(state, "artifacts") &&
+                    assertOwnedArtifact) {
+                    assertOwnedArtifact(root);
+                    continue;
+                }
+                throw new Error(`The live workspace's own state cannot be allowed: ${path}`);
+            }
         }
         allowed.add(realpathSync(path));
     }

package/dist/lib/identities/assume.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assume.d.ts","sourceRoot":"","sources":["../../../src/lib/identities/assume.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA0BH,MAAM,MAAM,uBAAuB,GAC/B,eAAe,GACf,iBAAiB,GACjB,sBAAsB,GACtB,oBAAoB,GACpB,kBAAkB,GAClB,oBAAoB,GACpB,aAAa,GACb,mBAAmB,CAAC;AAExB,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,IAAI,EAAE,uBAAuB;gBAA7B,IAAI,EAAE,uBAAuB,EAC7C,OAAO,EAAE,MAAM;CAKlB;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,+DAA+D;IAC/D,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAOD;+EAC+E;AAC/E,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,KAAK,SAAa,EAClB,mBAAmB,GAAE,WAAW,CAAC,MAAM,CAAa,GACnD,gBAAgB,GAAG,IAAI,CA6BzB;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CAyCT;AAuED,gEAAgE;AAChE,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,GACjC,oBAAoB,CAyHtB"}
+{"version":3,"file":"assume.d.ts","sourceRoot":"","sources":["../../../src/lib/identities/assume.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA0BH,MAAM,MAAM,uBAAuB,GAC/B,eAAe,GACf,iBAAiB,GACjB,sBAAsB,GACtB,oBAAoB,GACpB,kBAAkB,GAClB,oBAAoB,GACpB,aAAa,GACb,mBAAmB,CAAC;AAExB,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,IAAI,EAAE,uBAAuB;gBAA7B,IAAI,EAAE,uBAAuB,EAC7C,OAAO,EAAE,MAAM;CAKlB;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,+DAA+D;IAC/D,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAOD;+EAC+E;AAC/E,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,KAAK,SAAa,EAClB,mBAAmB,GAAE,WAAW,CAAC,MAAM,CAAa,GACnD,gBAAgB,GAAG,IAAI,CA6BzB;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CA6CT;AAuED,gEAAgE;AAChE,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,GACjC,oBAAoB,CAyHtB"}

package/dist/lib/identities/assume.js

@@ -85,6 +85,7 @@ export function reclaimAbandonedLocalConflict(coordRoot, conflict) {
     let sessionId = conflict.instance_id;
     let ageSecs;
     const liveRow = readLiveCoordinationRow(coordRoot, conflict.instance_id);
+    let expectedGenerationId = liveRow?.v3_generation_id ?? null;
     if (liveRow) {
         adapter = adapterOf(liveRow.platform);
         sessionId = liveRow.session_id || conflict.instance_id;
@@ -99,8 +100,10 @@ export function reclaimAbandonedLocalConflict(coordRoot, conflict) {
             // It is required to join the exact producer state when recording the sweep.
             adapter = adapterOf(hb.platform);
             sessionId = hb.session_id || conflict.instance_id;
+            expectedGenerationId = hb.v3_generation_id ?? null;
         }
         catch {
+            expectedGenerationId = null;
             /* content unreadable — still reclaim the file */
         }
         try {
@@ -116,6 +119,7 @@ export function reclaimAbandonedLocalConflict(coordRoot, conflict) {
         owner: conflict.instance_id,
         nativeSessionId: sessionId,
         adapter,
+        expectedGenerationId,
         observation: "stale_heartbeat",
         ageMs: Math.max(0, (ageSecs ?? 0) * 1_000),
     });

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"}

package/dist/lib/tunnel/current-address.js

@@ -0,0 +1,123 @@
+// This machine's public addresses as Cloudflare sees them, and the allowlist
+// bookkeeping around them (`tunnel allow add --current`).
+//
+// The tunnel gate admits a visitor by the `CF-Connecting-IP` header, which is
+// the address Cloudflare saw. Asking Cloudflare's own trace endpoint therefore
+// returns the same address the gate will later compare, with no third party and
+// no guess about NAT. The IPv4 and IPv6 probes use address literals, so each
+// travels over the family it is named for and needs no DNS.
+//
+// Entries the refresh adds are recorded in `auto_allowed`. The next refresh
+// replaces exactly those, so a machine that changes network does not pile up
+// stale addresses, and an entry added by hand is never removed.
+import { ipv4Slash32, ipv6Slash64, normalizeAllowEntry } from "./allowlist.js";
+export const TRACE_URL_V4 = "https://1.1.1.1/cdn-cgi/trace";
+export const TRACE_URL_V6 = "https://[2606:4700:4700::1111]/cdn-cgi/trace";
+/** The `ip=` value of a Cloudflare trace body, or null. */
+export function parseTraceIp(body) {
+    const m = body.match(/^ip=(\S+)\s*$/m);
+    return m ? m[1] : null;
+}
+async function probe(url, family, opts) {
+    let last = "no answer";
+    for (let attempt = 0; attempt < opts.attempts; attempt++) {
+        try {
+            const res = await opts.fetch(url, { signal: AbortSignal.timeout(opts.timeoutMs) });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            const ip = parseTraceIp(await res.text());
+            if (!ip)
+                throw new Error("the trace had no ip= line");
+            const entry = family === 4 ? ipv4Slash32(ip) : ipv6Slash64(ip);
+            if (!entry)
+                throw new Error(`expected an IPv${family} address, got ${ip}`);
+            return ip;
+        }
+        catch (error) {
+            last = error instanceof Error ? error.message : String(error);
+        }
+    }
+    throw new Error(last);
+}
+/** Both families in parallel. A family that fails is reported, not thrown. */
+export async function detectPublicAddresses(options = {}) {
+    const opts = {
+        fetch: options.fetch ?? fetch,
+        timeoutMs: options.timeoutMs ?? 4_000,
+        attempts: options.attempts ?? 2,
+    };
+    const [v4, v6] = await Promise.allSettled([
+        probe(TRACE_URL_V4, 4, opts),
+        probe(TRACE_URL_V6, 6, opts),
+    ]);
+    const out = { failures: [] };
+    if (v4.status === "fulfilled")
+        out.v4 = v4.value;
+    else
+        out.failures.push(`IPv4: ${v4.reason.message}`);
+    if (v6.status === "fulfilled")
+        out.v6 = v6.value;
+    else
+        out.failures.push(`IPv6: ${v6.reason.message}`);
+    return out;
+}
+const sameEntry = (a, b) => (normalizeAllowEntry(a) ?? a) === (normalizeAllowEntry(b) ?? b);
+const includesEntry = (list, entry) => list.some((e) => sameEntry(e, entry));
+/**
+ * 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 function planCurrentAddresses(config, detected) {
+    const previousAuto = config.auto_allowed ?? [];
+    const wanted = [];
+    if (detected.v4) {
+        const entry = ipv4Slash32(detected.v4);
+        if (entry)
+            wanted.push(entry);
+    }
+    if (detected.v6) {
+        const entry = ipv6Slash64(detected.v6);
+        if (entry)
+            wanted.push(entry);
+    }
+    if (wanted.length === 0) {
+        return {
+            config,
+            added: [],
+            removed: [],
+            automatic: previousAuto,
+            changed: false,
+            warnings: [
+                `Could not detect this machine's public address (${detected.failures.join("; ") || "no answer"}). ` +
+                    `The allowlist is unchanged${previousAuto.length ? `; the previous automatic entries stay: ${previousAuto.join(", ")}` : ""}.`,
+            ],
+        };
+    }
+    const manual = config.allowed_ips.filter((e) => !includesEntry(previousAuto, e));
+    // An address already listed by hand stays manual, so a later refresh keeps it.
+    const automatic = wanted.filter((e) => !includesEntry(manual, e));
+    const allowed = [...manual, ...automatic];
+    const before = config.allowed_ips;
+    const added = allowed.filter((e) => !includesEntry(before, e));
+    const removed = before.filter((e) => !includesEntry(allowed, e));
+    const warnings = [];
+    const missing = [detected.v4 ? null : "IPv4", detected.v6 ? null : "IPv6"].filter(Boolean);
+    if (missing.length > 0) {
+        warnings.push(`${missing.join(" and ")} was not detected, so this network is treated as having none` +
+            (detected.failures.length ? ` (${detected.failures.join("; ")})` : "") +
+            ".");
+    }
+    return {
+        config: { ...config, allowed_ips: allowed, auto_allowed: automatic },
+        added,
+        removed,
+        automatic,
+        changed: added.length > 0 || removed.length > 0,
+        warnings,
+    };
+}