harnery 0.42.0 → 0.43.0

package/dist/core/hooks/shell-waiter.js

@@ -1,83 +1,10 @@
+import { basename, shellCommandFromTool, tokenize } from "./shell-tokens.js";
 /** Recognize inline waiters; this is not a proof of arbitrary shell termination. */
 const REASON = "Inline shell waiter blocked: polling loops and delayed log-only checks can outlive the job " +
     "and accumulate as background tasks. Read the existing task output now, or wait on its " +
     "existing task handle. If polling is necessary, use a reviewed script with a hard deadline, " +
     "nonzero timeout exit, and producer-exit/failure detection. Do not create another waiter " +
     "to check progress or infer completion from a broad pgrep -f pattern.";
-/** Keep quoted arguments opaque, including examples and heredoc bodies. */
-function tokenize(source) {
-    const out = [];
-    const heredocs = [];
-    for (let i = 0; i < source.length;) {
-        const ch = source[i];
-        if (ch === "\\" && source[i + 1] === "\n") {
-            i += 2;
-            continue;
-        }
-        if (ch === "\n") {
-            out.push({ value: ";", quoted: false, operator: true });
-            i++;
-            for (const doc of heredocs.splice(0)) {
-                while (i < source.length) {
-                    const end = source.indexOf("\n", i);
-                    const stop = end === -1 ? source.length : end;
-                    const line = source.slice(i, stop);
-                    i = end === -1 ? source.length : end + 1;
-                    if ((doc.tabs ? line.replace(/^\t+/, "") : line) === doc.end)
-                        break;
-                }
-            }
-            continue;
-        }
-        if (/\s/.test(ch)) {
-            i++;
-            continue;
-        }
-        if (ch === "#") {
-            const end = source.indexOf("\n", i);
-            i = end === -1 ? source.length : end;
-            continue;
-        }
-        if (";|&(){}<>".includes(ch)) {
-            const op = source.slice(i).match(/^(?:<<-?|>>|&&|\|\||[;|&(){}<>])/)[0];
-            out.push({ value: op, quoted: false, operator: true });
-            i += op.length;
-            continue;
-        }
-        let value = "";
-        let quoted = false;
-        while (i < source.length && !/[\s;|&(){}<>]/.test(source[i])) {
-            const next = source[i++];
-            if (next === "'" || next === '"' || next === "`") {
-                quoted = true;
-                while (i < source.length && source[i] !== next) {
-                    if (source[i] === "\\" && next !== "'" && i + 1 < source.length)
-                        i++;
-                    value += source[i++];
-                }
-                if (source[i] === next)
-                    i++;
-            }
-            else if (next === "\\" && i < source.length) {
-                const escaped = source[i++];
-                if (escaped !== "\n")
-                    value += escaped;
-            }
-            else {
-                value += next;
-            }
-        }
-        const previous = out.at(-1)?.value;
-        if (previous === "<<" || previous === "<<-") {
-            heredocs.push({ end: value, tabs: previous === "<<-" });
-        }
-        out.push({ value, quoted });
-    }
-    return out;
-}
-function basename(value) {
-    return value.split(/[\\/]/).at(-1) ?? value;
-}
 function isWaiter(source, depth = 0) {
     if (depth > 8)
         return false;
@@ -151,23 +78,6 @@ function isWaiter(source, depth = 0) {
         commands.every((name) => harmless.has(name)));
 }
 export function shellWaiterReason(toolName, toolInput) {
-    if (typeof toolName !== "string")
-        return null;
-    const name = toolName.toLowerCase().replace(/^functions\./, "");
-    if (!["bash", "shell", "shell_command", "exec_command"].includes(name))
-        return null;
-    let input = toolInput;
-    if (typeof input === "string") {
-        try {
-            input = JSON.parse(input);
-        }
-        catch {
-            return null;
-        }
-    }
-    if (!input || typeof input !== "object")
-        return null;
-    const args = input;
-    const command = args.command ?? args.cmd;
-    return typeof command === "string" && isWaiter(command) ? REASON : null;
+    const command = shellCommandFromTool(toolName, toolInput);
+    return command !== null && isWaiter(command) ? REASON : null;
 }

package/dist/core/semantic/contract.d.ts

@@ -152,7 +152,7 @@ export declare const SemanticUsageReceiptV1Schema: import("@sinclair/typebox").T
     scope: import("@sinclair/typebox").TLiteral<"unreported">;
 }>]>;
 export declare const SemanticEvidenceObservationV1Schema: import("@sinclair/typebox").TObject<{
-    kind: import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"error" | "recovery" | "artifact" | "operation" | "action" | "terminal" | "progress" | "task" | "intent" | "wait" | "lifecycle" | "claim-conflict">[]>;
+    kind: import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"recovery" | "artifact" | "error" | "operation" | "action" | "terminal" | "task" | "progress" | "intent" | "wait" | "lifecycle" | "claim-conflict">[]>;
     event_id: import("@sinclair/typebox").TString;
     observed_at: import("@sinclair/typebox").TString;
     label: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -193,7 +193,7 @@ export declare const SemanticEvidenceV1Schema: import("@sinclair/typebox").TObje
         started_at: import("@sinclair/typebox").TString;
     }>>;
     recent: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
-        kind: import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"error" | "recovery" | "artifact" | "operation" | "action" | "terminal" | "progress" | "task" | "intent" | "wait" | "lifecycle" | "claim-conflict">[]>;
+        kind: import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"recovery" | "artifact" | "error" | "operation" | "action" | "terminal" | "task" | "progress" | "intent" | "wait" | "lifecycle" | "claim-conflict">[]>;
         event_id: import("@sinclair/typebox").TString;
         observed_at: import("@sinclair/typebox").TString;
         label: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -201,7 +201,7 @@ export declare const SemanticEvidenceV1Schema: import("@sinclair/typebox").TObje
         error_class: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     }>>;
     attention: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
-        kind: import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"error" | "recovery" | "artifact" | "operation" | "action" | "terminal" | "progress" | "task" | "intent" | "wait" | "lifecycle" | "claim-conflict">[]>;
+        kind: import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"recovery" | "artifact" | "error" | "operation" | "action" | "terminal" | "task" | "progress" | "intent" | "wait" | "lifecycle" | "claim-conflict">[]>;
         event_id: import("@sinclair/typebox").TString;
         observed_at: import("@sinclair/typebox").TString;
         label: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -628,7 +628,7 @@ export declare const SemanticInvalidReadModelV2Schema: import("@sinclair/typebox
     }>;
     receipt: import("@sinclair/typebox").TObject<{
         reason_code: import("@sinclair/typebox").TLiteral<"invalid_output">;
-        validation_issue_codes: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"unknown" | "schema" | "privacy" | "confidence" | "identity" | "basis" | "citation" | "unsupported_claim">[]>>;
+        validation_issue_codes: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"unknown" | "confidence" | "schema" | "privacy" | "identity" | "basis" | "citation" | "unsupported_claim">[]>>;
         usage: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
             schema_version: import("@sinclair/typebox").TLiteral<1>;
             source: import("@sinclair/typebox").TLiteral<"native">;
@@ -954,7 +954,7 @@ export declare const SemanticAgentReadModelV2Schema: import("@sinclair/typebox")
     }>;
     receipt: import("@sinclair/typebox").TObject<{
         reason_code: import("@sinclair/typebox").TLiteral<"invalid_output">;
-        validation_issue_codes: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"unknown" | "schema" | "privacy" | "confidence" | "identity" | "basis" | "citation" | "unsupported_claim">[]>>;
+        validation_issue_codes: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"unknown" | "confidence" | "schema" | "privacy" | "identity" | "basis" | "citation" | "unsupported_claim">[]>>;
         usage: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
             schema_version: import("@sinclair/typebox").TLiteral<1>;
             source: import("@sinclair/typebox").TLiteral<"native">;

package/dist/core/storage/process-log.d.ts

@@ -20,6 +20,16 @@ export interface RotatingProcessOptions {
     env?: Readonly<Record<string, string | undefined>>;
     max_bytes?: number;
     backups?: number;
+    /**
+     * How to start the log wrapper, as an argv prefix that takes the JSON
+     * specification as its final argument and ends in `runProcessLogWorker`. The
+     * default runs this module's own file, which does not exist inside a
+     * single-file host bundle; such a host supplies a hidden task of its own.
+     */
+    worker?: {
+        command: string;
+        arguments: string[];
+    };
 }
 /** Resolve one catalog-owned partition path, with an explicit legacy rollback. */
 export declare function processLogDestination(options: ProcessLogDestinationOptions): string;
@@ -35,4 +45,6 @@ export declare class RotatingTextSink {
 export declare function spawnRotatingProcess(options: RotatingProcessOptions): ChildProcess;
 /** Run a short process synchronously while keeping its captured output bounded. */
 export declare function runRotatingProcessSync(options: RotatingProcessOptions): number | null;
+/** The wrapper's body: run the specified command and rotate its output into the log. */
+export declare function runProcessLogWorker(raw: string | undefined): Promise<void>;
 //# sourceMappingURL=process-log.d.ts.map

package/dist/core/storage/process-log.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-log.d.ts","sourceRoot":"","sources":["../../../src/core/storage/process-log.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAoB,MAAM,oBAAoB,CAAC;AAiBzE,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,4BAA4B;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAKD,kFAAkF;AAClF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CAcnF;AAED,qBAAa,gBAAgB;;gBAIf,OAAO,EAAE,uBAAuB;IAa5C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAuB1B,eAAe,IAAI,IAAI;IAKvB,KAAK,IAAI,IAAI;IACb,KAAK,IAAI,IAAI;CAWd;AAED,6FAA6F;AAC7F,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,sBAAsB,GAAG,YAAY,CAqBlF;AAED,mFAAmF;AACnF,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,GAAG,IAAI,CAgBrF"}
+{"version":3,"file":"process-log.d.ts","sourceRoot":"","sources":["../../../src/core/storage/process-log.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAoB,MAAM,oBAAoB,CAAC;AAiBzE,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,4BAA4B;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CACnD;AAKD,kFAAkF;AAClF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CAcnF;AAED,qBAAa,gBAAgB;;gBAIf,OAAO,EAAE,uBAAuB;IAa5C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAuB1B,eAAe,IAAI,IAAI;IAKvB,KAAK,IAAI,IAAI;IACb,KAAK,IAAI,IAAI;CAWd;AAED,6FAA6F;AAC7F,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,sBAAsB,GAAG,YAAY,CA4BlF;AAED,mFAAmF;AACnF,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,GAAG,IAAI,CAgBrF;AAED,wFAAwF;AACxF,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BhF"}

package/dist/core/storage/process-log.js

@@ -98,7 +98,14 @@ export function spawnRotatingProcess(options) {
         command: options.command,
         arguments: options.arguments ?? [],
     });
-    return spawn("bun", [fileURLToPath(import.meta.url), "--run", specification], {
+    // Run the wrapper with the Bun that is running this code: a host may carry a
+    // managed Bun that is not on PATH.
+    const bun = typeof process.versions.bun === "string" ? process.execPath : "bun";
+    const launcher = options.worker ?? {
+        command: bun,
+        arguments: [fileURLToPath(import.meta.url), "--run"],
+    };
+    return spawn(launcher.command, [...launcher.arguments, specification], {
         detached: true,
         stdio: "ignore",
         env: { ...(options.env ?? process.env) },
@@ -125,7 +132,8 @@ export function runRotatingProcessSync(options) {
     sink.close();
     return result.status;
 }
-async function runProcessLogWorker(raw) {
+/** The wrapper's body: run the specified command and rotate its output into the log. */
+export async function runProcessLogWorker(raw) {
     const parsed = JSON.parse(raw ?? "null");
     if (!parsed || typeof parsed.command !== "string" || !Array.isArray(parsed.arguments)) {
         throw new Error("invalid process log worker specification");

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,
+    };
+}