@cotal-ai/cli 0.26.0 → 0.28.0-hack-20260823202734

package/dist/lib/join-target.d.ts

@@ -28,18 +28,22 @@
  * overlay is actually up on this machine; the same literal with the overlay down is just a CGNAT
  * address.
  *
- * WHERE THIS GOES NEXT, so the next editor does not relax it for the wrong reason. Measured on
- * this stack: the `tls` connect option verifies the certificate CHAIN AND THE HOSTNAME (Node
- * defaults, `rejectUnauthorized: true`, servername from the URL), so a redirected name cannot
- * complete the handshake and hostnames become safe — but only once something REQUIRES TLS. The
- * relaxation is therefore a function of recorded strictness, not of time passing, and the agreed
- * eventual shape is `classifyJoinTarget(url, { tlsRequired })` rather than a third verdict: one
- * place keeps answering "may this machine send credentials to that address", with strictness as
- * an input it cannot otherwise see. Two counterintuitive consequences worth keeping in view:
- * the overlay ranges are the AWKWARD case under TLS (CGNAT space, no public CA will issue for it,
- * verifying a literal needs an IP SAN, so it implies a private CA on every joiner), while the
- * `<host>.ts.net` names refused below are the EASY case (publicly resolvable, publicly-trusted
- * certs). Do not pre-relax: with nothing requiring TLS today, literals-only is the correct rule.
+ * WHERE THIS WENT, so the next editor knows the relaxation below is the authorized one. The
+ * previous header said, measured on this stack: the `tls` connect option verifies the certificate
+ * CHAIN AND THE HOSTNAME (Node defaults, `rejectUnauthorized: true`, servername from the URL), so
+ * a redirected name cannot complete the handshake and hostnames become safe — but only once
+ * something REQUIRES TLS. The relaxation is a function of recorded strictness, not of time
+ * passing, and the agreed shape is `classifyJoinTarget(url, { tlsRequired })` rather than a third
+ * verdict: one place keeps answering "may this machine send credentials to that address", with
+ * strictness as an input it cannot otherwise see. THAT PRECONDITION HAS NOW LANDED: the broker
+ * can serve TLS and the mesh record carries `tlsRequired`, so with `tlsRequired: true` a hostname
+ * or a public literal classifies as {@link JoinReach} `"public-tls"`. Two counterintuitive
+ * consequences remain in force: the overlay ranges are the AWKWARD case under TLS (CGNAT space,
+ * no public CA will issue for it, verifying a literal needs an IP SAN, so it implies a private CA
+ * on every joiner), while the `<host>.ts.net` names are the EASY case (publicly resolvable,
+ * publicly-trusted certs). With `tlsRequired: false` nothing is relaxed: literals-only stays the
+ * rule, verbatim. And ordinary private ranges are refused in BOTH modes — no public CA issues for
+ * them, so required TLS cannot make them verifiable, and a cafe LAN is private too.
  */
 /** The address class a permitted target belongs to. This is a REACHABILITY allowlist: it says the
  *  address is one we are willing to consider, never that the connection is protected. What
@@ -51,7 +55,11 @@ export type JoinReach =
 /** A private-overlay literal. Permitted TODAY without required TLS, carrying a
  *  {@link JoinTarget.residual} that says so; it becomes conditional on TLS in step two. The
  *  address alone is not a guarantee - see {@link DialPolicy.tlsRequired}. */
- | "overlay";
+ | "overlay"
+/** A hostname or public literal dialed with REQUIRED TLS ({@link DialPolicy.tlsRequired}):
+ *  the certificate chain + hostname check is the authority, so the resolver no longer picks
+ *  the peer. Never produced with `tlsRequired: false`. */
+ | "public-tls";
 export interface JoinTarget {
     /** The normalized dial URL, port defaulted. */
     server: string;
@@ -80,11 +88,11 @@ export interface DialPolicy {
      * DHCP or routing can answer a dial to it. So the address class establishes only that we are
      * willing to consider the target; requiring TLS is what makes it safe.
      *
-     * There is no field on the mesh record to source this from yet — it arrives with the work that
-     * teaches the broker to serve TLS — so callers pass `false` today, and with it false an overlay
-     * literal is refused unless {@link DialPolicy.allowUnencryptedOverlay} says the operator
-     * accepted the tunnel dependency. When this can be `true` the acceptance stops being needed:
-     * the transport is then proven rather than promised, and the flag can go.
+     * The mesh record now carries this intent (`MeshEntry.tlsRequired`), so callers pass the
+     * record's real strictness. With it `false` an overlay literal is refused unless
+     * {@link DialPolicy.allowUnencryptedOverlay} says the operator accepted the tunnel dependency.
+     * With it `true` the acceptance stops being needed — the transport is proven rather than
+     * promised — and a hostname or public literal becomes registrable as `"public-tls"`.
      */
     tlsRequired: boolean;
     /**
@@ -102,6 +110,59 @@ export interface DialPolicy {
      */
     allowUnencryptedOverlay: boolean;
 }
+/**
+ * WHICH fence refused, as a closed set rather than as prose.
+ *
+ * The union is exhaustive on purpose: a new refusal arm must name itself here or it will not
+ * compile, so an unlabelled refusal is a type error rather than a cell that passes for the wrong
+ * reason.
+ */
+export declare const JOIN_REFUSAL_CODES: readonly ["not-a-url", "bad-scheme", "no-host", "overlay-unacked", "private-range", "unprotected-target"];
+/**
+ * The type is DERIVED from the runtime array above, so there is exactly ONE universe of codes.
+ *
+ * A suite that restated this list would carry a second copy of the thing it measures, and copies
+ * drift in the direction that hurts: an arm added here but not there makes the emitted-code check
+ * either falsely red or, if loosened to compensate, permanently green. Exporting the array and
+ * deriving the type means a new arm is visible to the suite by construction, with the union no
+ * less closed than a hand-written one.
+ */
+export type JoinRefusalCode = (typeof JOIN_REFUSAL_CODES)[number];
+/**
+ * A refusal from THIS classifier, identified structurally.
+ *
+ * The suite used to decide "was this a refusal?" by matching the rendered message, which is a
+ * string shape standing in for a decision — the exact defect the address fences in this file exist
+ * to correct, reproduced in the harness that proves them. Measured: a fault firing before the
+ * privacy check that emitted the privacy refusal's text VERBATIM was accepted as a genuine
+ * private-range refusal. A tag the classifier sets deliberately cannot be produced by an unrelated
+ * fault, so a cell can require not merely "something refused" but "the fence I am testing refused".
+ *
+ * BOUNDARY, stated so "typed" is not read as "unspoofable": this class is EXPORTED so the suite can
+ * assert `instanceof`, and that same export hands the constructor to every importer — so a refusal
+ * is NOT unforgeable from outside. What holds is narrower, and is the property that matters:
+ * unforgeable BY ACCIDENT — constructible only by deliberate code that imports the class, wherever
+ * it lives; and `classifyJoinTarget` throws its own. The reachable threat was never a malicious
+ * importer manufacturing one; it was a non-privacy fault inside this module reporting as a privacy
+ * refusal, and a deliberate tag plus a per-cell code closes that.
+ */
+export declare class JoinRefusal extends Error {
+    readonly code: JoinRefusalCode;
+    constructor(code: JoinRefusalCode, message: string);
+}
+/**
+ * Is this host the loopback machine, whatever spelling it arrived in?
+ *
+ * THE ANSWER COMES FROM PARSING AN ADDRESS, NEVER FROM HOW THE TEXT BEGINS. A prefix test like
+ * `/^127\./` matches `127.evil.com`, `127.0.0.1.nip.io` and `127.com` — all registrable by anyone
+ * — and misses real loopback spellings such as `0177.0.0.1` or `[::ffff:127.0.0.1]`. It is wrong
+ * in both directions, which is what a string standing in for an address decision usually is.
+ *
+ * Exported so every caller that needs "is this loopback" shares ONE authority, canonicalization
+ * included, rather than growing a second opinion. Brackets are tolerated so a caller may pass a
+ * URL hostname straight in.
+ */
+export declare function isLoopbackHost(host: string): boolean;
 /**
  * Classify a registration target, or throw the reason it is refused.
  *

package/dist/lib/join-target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"join-target.d.ts","sourceRoot":"","sources":["../../src/lib/join-target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH;;;0BAG0B;AAC1B,MAAM,MAAM,SAAS;AACnB,6DAA6D;AAC3D,UAAU;AACZ;;6EAE6E;GAC3E,SAAS,CAAC;AAEd,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,SAAS,CAAC;IACjB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,2FAA2F;AAC3F,MAAM,WAAW,UAAU;IACzB;;;;;;;;;;;;;;OAcG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB;;;;;;;;;;;;OAYG;IACH,uBAAuB,EAAE,OAAO,CAAC;CAClC;AAuCD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,UAAU,CA8C9E"}
+{"version":3,"file":"join-target.d.ts","sourceRoot":"","sources":["../../src/lib/join-target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH;;;0BAG0B;AAC1B,MAAM,MAAM,SAAS;AACnB,6DAA6D;AAC3D,UAAU;AACZ;;6EAE6E;GAC3E,SAAS;AACX;;0DAE0D;GACxD,YAAY,CAAC;AAEjB,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,SAAS,CAAC;IACjB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,2FAA2F;AAC3F,MAAM,WAAW,UAAU;IACzB;;;;;;;;;;;;;;OAcG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB;;;;;;;;;;;;OAYG;IACH,uBAAuB,EAAE,OAAO,CAAC;CAClC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,2GAarB,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;gBACnB,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM;CAKnD;AAKD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGpD;AA8ID;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,UAAU,CAqE9E"}

package/dist/lib/join-target.js

@@ -28,21 +28,88 @@
  * overlay is actually up on this machine; the same literal with the overlay down is just a CGNAT
  * address.
  *
- * WHERE THIS GOES NEXT, so the next editor does not relax it for the wrong reason. Measured on
- * this stack: the `tls` connect option verifies the certificate CHAIN AND THE HOSTNAME (Node
- * defaults, `rejectUnauthorized: true`, servername from the URL), so a redirected name cannot
- * complete the handshake and hostnames become safe — but only once something REQUIRES TLS. The
- * relaxation is therefore a function of recorded strictness, not of time passing, and the agreed
- * eventual shape is `classifyJoinTarget(url, { tlsRequired })` rather than a third verdict: one
- * place keeps answering "may this machine send credentials to that address", with strictness as
- * an input it cannot otherwise see. Two counterintuitive consequences worth keeping in view:
- * the overlay ranges are the AWKWARD case under TLS (CGNAT space, no public CA will issue for it,
- * verifying a literal needs an IP SAN, so it implies a private CA on every joiner), while the
- * `<host>.ts.net` names refused below are the EASY case (publicly resolvable, publicly-trusted
- * certs). Do not pre-relax: with nothing requiring TLS today, literals-only is the correct rule.
+ * WHERE THIS WENT, so the next editor knows the relaxation below is the authorized one. The
+ * previous header said, measured on this stack: the `tls` connect option verifies the certificate
+ * CHAIN AND THE HOSTNAME (Node defaults, `rejectUnauthorized: true`, servername from the URL), so
+ * a redirected name cannot complete the handshake and hostnames become safe — but only once
+ * something REQUIRES TLS. The relaxation is a function of recorded strictness, not of time
+ * passing, and the agreed shape is `classifyJoinTarget(url, { tlsRequired })` rather than a third
+ * verdict: one place keeps answering "may this machine send credentials to that address", with
+ * strictness as an input it cannot otherwise see. THAT PRECONDITION HAS NOW LANDED: the broker
+ * can serve TLS and the mesh record carries `tlsRequired`, so with `tlsRequired: true` a hostname
+ * or a public literal classifies as {@link JoinReach} `"public-tls"`. Two counterintuitive
+ * consequences remain in force: the overlay ranges are the AWKWARD case under TLS (CGNAT space,
+ * no public CA will issue for it, verifying a literal needs an IP SAN, so it implies a private CA
+ * on every joiner), while the `<host>.ts.net` names are the EASY case (publicly resolvable,
+ * publicly-trusted certs). With `tlsRequired: false` nothing is relaxed: literals-only stays the
+ * rule, verbatim. And ordinary private ranges are refused in BOTH modes — no public CA issues for
+ * them, so required TLS cannot make them verifiable, and a cafe LAN is private too.
  */
+/**
+ * WHICH fence refused, as a closed set rather than as prose.
+ *
+ * The union is exhaustive on purpose: a new refusal arm must name itself here or it will not
+ * compile, so an unlabelled refusal is a type error rather than a cell that passes for the wrong
+ * reason.
+ */
+export const JOIN_REFUSAL_CODES = [
+    /** The string is not a URL at all. */
+    "not-a-url",
+    /** Parsed, but not a broker scheme this policy classifies. */
+    "bad-scheme",
+    /** Parsed, but carries no host to classify. */
+    "no-host",
+    /** An overlay literal without required TLS and without recorded acceptance. */
+    "overlay-unacked",
+    /** A private range, which required TLS cannot make verifiable. */
+    "private-range",
+    /** A hostname or public literal with no TLS requirement to protect it. */
+    "unprotected-target",
+];
+/**
+ * A refusal from THIS classifier, identified structurally.
+ *
+ * The suite used to decide "was this a refusal?" by matching the rendered message, which is a
+ * string shape standing in for a decision — the exact defect the address fences in this file exist
+ * to correct, reproduced in the harness that proves them. Measured: a fault firing before the
+ * privacy check that emitted the privacy refusal's text VERBATIM was accepted as a genuine
+ * private-range refusal. A tag the classifier sets deliberately cannot be produced by an unrelated
+ * fault, so a cell can require not merely "something refused" but "the fence I am testing refused".
+ *
+ * BOUNDARY, stated so "typed" is not read as "unspoofable": this class is EXPORTED so the suite can
+ * assert `instanceof`, and that same export hands the constructor to every importer — so a refusal
+ * is NOT unforgeable from outside. What holds is narrower, and is the property that matters:
+ * unforgeable BY ACCIDENT — constructible only by deliberate code that imports the class, wherever
+ * it lives; and `classifyJoinTarget` throws its own. The reachable threat was never a malicious
+ * importer manufacturing one; it was a non-privacy fault inside this module reporting as a privacy
+ * refusal, and a deliberate tag plus a per-cell code closes that.
+ */
+export class JoinRefusal extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "JoinRefusal";
+        this.code = code;
+    }
+}
 /** The NATS default client port, used when the join URL omits one. */
 const DEFAULT_PORT = 4222;
+/**
+ * Is this host the loopback machine, whatever spelling it arrived in?
+ *
+ * THE ANSWER COMES FROM PARSING AN ADDRESS, NEVER FROM HOW THE TEXT BEGINS. A prefix test like
+ * `/^127\./` matches `127.evil.com`, `127.0.0.1.nip.io` and `127.com` — all registrable by anyone
+ * — and misses real loopback spellings such as `0177.0.0.1` or `[::ffff:127.0.0.1]`. It is wrong
+ * in both directions, which is what a string standing in for an address decision usually is.
+ *
+ * Exported so every caller that needs "is this loopback" shares ONE authority, canonicalization
+ * included, rather than growing a second opinion. Brackets are tolerated so a caller may pass a
+ * URL hostname straight in.
+ */
+export function isLoopbackHost(host) {
+    const bare = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+    return isLoopbackLiteral(normalizeLegacyV4(normalizeMappedV4(bare)));
+}
 /** Loopback: `127.0.0.0/8` and `::1`. LITERALS ONLY, never `localhost`, because the whole point is
  *  a verdict that does not depend on a resolver an attacker could influence (a hosts-file entry or
  *  a poisoned lookup would otherwise turn "loopback" into any address at all). */
@@ -72,12 +139,132 @@ function isOverlayLiteral(host) {
     }
     return /^fd7a:115c:a1e0:/i.test(host);
 }
+/** Ordinary private ranges: RFC1918, link-local, and the non-overlay ULA/link-local v6 space.
+ *  Refused in BOTH modes — a cafe LAN is private too, and no public CA issues certificates for
+ *  these ranges, so required TLS cannot make an address here verifiable. */
+function isPrivateLiteral(host) {
+    const v4 = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (v4) {
+        const p = v4.slice(1).map(Number);
+        if (p.some((n) => n > 255))
+            return false; // not an IP literal at all; treated as a hostname
+        if (p[0] === 10)
+            return true; // 10.0.0.0/8
+        if (p[0] === 172 && p[1] >= 16 && p[1] <= 31)
+            return true; // 172.16.0.0/12
+        if (p[0] === 192 && p[1] === 168)
+            return true; // 192.168.0.0/16
+        if (p[0] === 169 && p[1] === 254)
+            return true; // 169.254.0.0/16 link-local
+        return false;
+    }
+    // ULA fc00::/7 and link-local fe80::/10; the overlay's fd7a:115c:a1e0::/48 is classified first.
+    return /^(f[cd][0-9a-f]{2}:|fe[89ab][0-9a-f]{0,2}:)/i.test(host);
+}
 /** A URL's hostname with an IPv6 literal's brackets removed (`[::1]` -> `::1`). */
 function bareHost(url) {
     return url.hostname.startsWith("[") && url.hostname.endsWith("]")
         ? url.hostname.slice(1, -1)
         : url.hostname;
 }
+/**
+ * Collapse ANY legacy IPv4 spelling to canonical dotted-quad, so that one address has ONE
+ * verdict however it is written.
+ *
+ * `inet_aton` — which the C library, Node's resolver and every OS dialer accept — does not
+ * require four decimal octets. It takes 1, 2, 3 or 4 parts, each of which may be decimal, octal
+ * (leading `0`) or hex (leading `0x`), and a short form's final part absorbs the remaining bytes.
+ * All of these are 192.168.1.10, verified against `dns.lookup` on this machine:
+ *
+ *     3232235786        (decimal dword)      -> 192.168.1.10
+ *     0300.0250.01.012  (octal dotted)       -> 192.168.1.10
+ *     0xC0A8010A        (hex dword)          -> 192.168.1.10
+ *     0177.0.0.1        (octal, loopback)    -> 127.0.0.1
+ *     192.168.257       (3-part shorthand)   -> 192.168.1.1
+ *
+ * A classifier that only matched four decimal octets treated each of these as a HOSTNAME, so it
+ * fell through the private-range fence and registered as a public address, while the dotted form
+ * of the very same host was refused. Canonicalize first; classify once.
+ *
+ * Returns the dotted form, or the input unchanged when it is not an IPv4 literal in any spelling
+ * (a real hostname, or a v6 literal handled below).
+ */
+function normalizeLegacyV4(host) {
+    if (!/^[0-9a-fx.]+$/i.test(host) || host.endsWith("."))
+        return host;
+    const parts = host.split(".");
+    if (parts.length > 4)
+        return host;
+    const nums = [];
+    for (const part of parts) {
+        if (part === "")
+            return host;
+        let n;
+        if (/^0[xX][0-9a-fA-F]+$/.test(part))
+            n = parseInt(part.slice(2), 16);
+        else if (/^0[0-7]+$/.test(part))
+            n = parseInt(part.slice(1), 8);
+        else if (/^(0|[1-9][0-9]*)$/.test(part))
+            n = Number(part);
+        else
+            return host; // e.g. 09 or 0xZ: not a number in any base, so not an IPv4 literal
+        if (!Number.isSafeInteger(n) || n < 0)
+            return host;
+        nums.push(n);
+    }
+    // The last part absorbs the bytes the earlier parts did not name (inet_aton's short forms).
+    const leading = nums.slice(0, -1);
+    const last = nums[nums.length - 1];
+    if (leading.some((n) => n > 255))
+        return host;
+    const width = 4 - leading.length;
+    if (last > (width === 4 ? 0xffffffff : Math.pow(256, width) - 1))
+        return host;
+    const bytes = [...leading];
+    for (let i = width - 1; i >= 0; i--)
+        bytes.push((last >>> (8 * i)) & 0xff);
+    return bytes.join(".");
+}
+/**
+ * Collapse an IPv4-MAPPED IPv6 literal to its dotted IPv4 form, so that one address has ONE
+ * verdict however it is spelled.
+ *
+ * `::ffff:192.168.1.10` and `::ffff:c0a8:010a` are the same 192.168.1.10, and the kernel dials
+ * them to the same host. RFC 4291 mapped form is exactly `::ffff:a.b.c.d` (equivalently
+ * `::ffff:xxxx:xxxx`) and NOTHING ELSE: `::ffff:0:127.0.0.1` looks similar but is a different
+ * address, which a socket proves — it dials ENETUNREACH where `::ffff:127.0.0.1` connects to
+ * loopback. Collapsing it would be this fence's own bug in mirror image, granting a loopback,
+ * overlay or public verdict to an address that is none of those. Classifying the v6 spelling separately meant the private-range check ran
+ * a v4 regex that could not match, the address fell through to "not private", and
+ * `--tls` registered a LAN broker that the dotted form correctly refuses. Every classifier below
+ * therefore sees the normalized form, which keeps loopback/overlay/private answers identical
+ * across spellings rather than fixing only the range that was reported.
+ *
+ * Anything that is not a v4-mapped literal is returned unchanged.
+ */
+function normalizeMappedV4(host) {
+    const m = host.match(/^::ffff:([0-9a-f.:]+)$/i);
+    if (!m)
+        return host;
+    const tail = m[1];
+    const dotted = tail.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (dotted) {
+        const p = dotted.slice(1).map(Number);
+        return p.some((n) => n > 255) ? host : p.join(".");
+    }
+    // Only the two RFC 4291 tails are mapped. A legacy-spelled tail (`::ffff:3232235786`) is not
+    // handled here and does not need to be: `new URL()` rejects it as an invalid IPv6 literal
+    // before this function is ever called, so the target is refused as "not a URL" — a stricter
+    // answer than any collapse. Adding a branch for it would be unreachable code that no test
+    // could kill, and the address does not resolve anyway (a socket reports ENOTFOUND).
+    const hex = tail.match(/^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i);
+    if (hex) {
+        const hi = parseInt(hex[1], 16);
+        const lo = parseInt(hex[2], 16);
+        return [hi >> 8, hi & 0xff, lo >> 8, lo & 0xff].join(".");
+    }
+    return host;
+}
 /**
  * Classify a registration target, or throw the reason it is refused.
  *
@@ -90,15 +277,23 @@ export function classifyJoinTarget(raw, policy) {
         url = new URL(raw);
     }
     catch {
-        throw new Error(`${JSON.stringify(raw)} is not a URL - pass a broker address like nats://100.64.0.1:4222`);
+        throw new JoinRefusal("not-a-url", `${JSON.stringify(raw)} is not a URL - pass a broker address like nats://100.64.0.1:4222`);
     }
-    if (url.protocol !== "nats:" && url.protocol !== "tls:")
-        throw new Error(`${JSON.stringify(raw)} must be a nats:// or tls:// URL, not ${url.protocol}//`);
-    const host = bareHost(url);
+    if (url.protocol !== "nats:" && url.protocol !== "tls:" && url.protocol !== "ws:" && url.protocol !== "wss:")
+        throw new JoinRefusal("bad-scheme", `${JSON.stringify(raw)} must be a nats://, tls://, ws:// or wss:// URL, not ${url.protocol}//`);
+    // ONE address, ONE verdict: every legacy IPv4 spelling (decimal dword, octal, hex, short form)
+    // and every v4-mapped v6 literal is collapsed to canonical dotted form BEFORE any classifier
+    // runs, so an alternate spelling cannot walk past the private-range fence.
+    const host = normalizeLegacyV4(normalizeMappedV4(bareHost(url)));
     if (!host)
-        throw new Error(`${JSON.stringify(raw)} has no host`);
-    const port = url.port || String(DEFAULT_PORT);
-    const server = `${url.protocol}//${url.hostname}:${port}`;
+        throw new JoinRefusal("no-host", `${JSON.stringify(raw)} has no host`);
+    // A websocket broker rides the web's ports and may live under a PATH (`wss://host/mesh-ws`
+    // behind an HTTPS edge) - the path is part of the address and must survive into the record,
+    // where a plain NATS URL has no path to keep.
+    const ws = url.protocol === "ws:" || url.protocol === "wss:";
+    const port = url.port || String(ws ? (url.protocol === "wss:" ? 443 : 80) : DEFAULT_PORT);
+    const path = ws && url.pathname !== "/" ? url.pathname : "";
+    const server = `${url.protocol}//${url.hostname}:${port}${path}`;
     // Loopback is the one class that needs no transport guarantee: nothing leaves the machine, so
     // there is nothing on a wire for anyone to sit on.
     if (isLoopbackLiteral(host))
@@ -107,7 +302,7 @@ export function classifyJoinTarget(raw, policy) {
         if (policy.tlsRequired)
             return { server, reach: "overlay" };
         if (!policy.allowUnencryptedOverlay)
-            throw new Error(`${JSON.stringify(raw)} refused: ${host} is a private-overlay address, and this build cannot require TLS on the connection.\n` +
+            throw new JoinRefusal("overlay-unacked", `${JSON.stringify(raw)} refused: ${host} is a private-overlay address, and this build cannot require TLS on the connection.\n` +
                 `  That is safe while the overlay tunnel is up, and NOT safe if it is down: the range is then ordinary carrier-grade\n` +
                 `  NAT, and whoever answers the dial receives the credentials this machine sends.\n` +
                 `  Only you can know whether the tunnel is up, so accept it explicitly with --allow-unencrypted-overlay, which records\n` +
@@ -122,7 +317,17 @@ export function classifyJoinTarget(raw, policy) {
                 `  become a refusal once the broker can be served over TLS and the record can say TLS is required.`,
         };
     }
-    throw new Error(`${JSON.stringify(raw)} refused: this build cannot protect a connection to ${host}, and a machine that registers a mesh sends its agent credentials to that broker.\n` +
+    // Recorded strictness relaxes the fence, exactly as the header pre-authorized: with TLS
+    // REQUIRED, the `tls` connect option verifies the certificate chain and the hostname, so a
+    // hostname or a public literal is safe — the resolver stops choosing the peer. Private ranges
+    // stay refused: no public CA issues for them, and a cafe LAN is private too.
+    if (policy.tlsRequired) {
+        if (!isPrivateLiteral(host))
+            return { server, reach: "public-tls" };
+        throw new JoinRefusal("private-range", `${JSON.stringify(raw)} refused: ${host} is a private-range address, and requiring TLS does not make it verifiable - no public CA issues certificates for RFC1918 or link-local space, and a cafe LAN is private, not yours.\n` +
+            `  Register the broker by its public name or address, or run it on this machine and use a loopback literal.`);
+    }
+    throw new JoinRefusal("unprotected-target", `${JSON.stringify(raw)} refused: this build cannot protect a connection to ${host}, and a machine that registers a mesh sends its agent credentials to that broker.\n` +
         `  Only a loopback literal (127.0.0.0/8, ::1) or a private-overlay literal (100.64.0.0/10, fd7a:115c:a1e0::/48) may be registered. An overlay literal additionally needs --allow-unencrypted-overlay, which records that you accepted its tunnel dependency.\n` +
         `  Ordinary private ranges are refused too: a cafe network is private, and private is not the same as yours.\n` +
         `  A hostname is refused even when it resolves somewhere permitted - otherwise whoever answers the lookup chooses which machine receives the credentials. Pass the address itself.`);

package/dist/lib/join-target.js.map

@@ -1 +1 @@
-{"version":3,"file":"join-target.js","sourceRoot":"","sources":["../../src/lib/join-target.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"join-target.js","sourceRoot":"","sources":["../../src/lib/join-target.ts"],"names":[],"mappings":"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"}

package/dist/seed/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/seed/store.ts"],"names":[],"mappings":"AAqBA;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,CAWzG;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,cAAc,EAAE,MAAM,EAAE,eAAe,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAS5F"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/seed/store.ts"],"names":[],"mappings":"AAsBA;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,CAyBzG;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,cAAc,EAAE,MAAM,EAAE,eAAe,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAe5F"}

package/dist/seed/store.js

@@ -1,5 +1,6 @@
 import { cpSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";
+import { provenance } from "@cotal-ai/workspace";
 import { seedStoreDir, seedStorePath, shippedSourceDir } from "./paths.js";
 /**
  * The durable seed store: a stable, per-generation copy of each shipped connector payload that
@@ -34,6 +35,20 @@ export function stageSeedPayload(generation, name, opts = {}) {
     mkdirSync(dirname(dest), { recursive: true });
     cpSync(src, staging, { recursive: true, filter: (from) => payloadFilter(src, from) });
     renameSync(staging, dest); // atomic within the store: the final path only ever holds a complete payload
+    // Announce the write on the provenance channel. This store is operator-global (a sibling of the
+    // shared `extensions/` prefix, moved only by `XDG_CONFIG_HOME`), so re-seeding it from a non-released
+    // checkout silently makes those bytes the machine-wide payload for that generation key; naming the
+    // path here lets the line read as the machine-wide action it is. Only on a real materialization: the
+    // idempotent early return above (an intact prior copy) writes nothing and stays silent.
+    //
+    // THE BOUND, stated where the claim is made: this announce is AFTER the commit and rides the
+    // provenance channel, which is a plain stderr write with no failure policy. If stderr is closed or
+    // erroring, the payload is still written and the line is lost, so the guarantee is "a materialization
+    // that reaches a working stderr is named", not "no materialization is ever unannounced". Announcing
+    // BEFORE the rename would trade that for a worse lie (a named write that then failed), and throwing
+    // on a lost line would fail a seed for a disclosure fault. The channel-wide fix belongs to the
+    // provenance layer rather than to this call site.
+    provenance.wrote(`operator-global seed store payload (${name})`, dest);
     return dest;
 }
 /**
@@ -51,8 +66,14 @@ export function gcSeedStore(keepGeneration, referencedSpecs) {
             continue;
         const genDir = join(root, gen);
         const referenced = referencedSpecs.some((spec) => spec === genDir || spec.startsWith(genDir + sep));
-        if (!referenced)
-            rmSync(genDir, { recursive: true, force: true });
+        if (referenced)
+            continue;
+        rmSync(genDir, { recursive: true, force: true });
+        // Announce the DELETE for the same reason the write above is announced: this store is
+        // operator-global, so dropping a generation from it is a machine-wide act performed by a command
+        // the operator ran for a local reason. It is announced AFTER the removal, so the line reports
+        // what happened rather than what was intended.
+        provenance.removed(`operator-global seed store generation (${gen})`, genDir);
     }
 }
 //# sourceMappingURL=store.js.map

package/dist/seed/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/seed/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACzF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE3E;;;;;;GAMG;AAEH;;;kGAGkG;AAClG,SAAS,aAAa,CAAC,IAAY,EAAE,IAAY;IAC/C,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAkB,EAAE,IAAY,EAAE,OAA4B,EAAE;IAC/F,MAAM,IAAI,GAAG,aAAa,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IAC7C,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACvE,MAAM,GAAG,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,GAAG,IAAI,UAAU,CAAC;IAClC,MAAM,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/C,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;IACtF,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,6EAA6E;IACxG,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,cAAsB,EAAE,eAAkC;IACpF,MAAM,IAAI,GAAG,YAAY,EAAE,CAAC;IAC5B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO;IAC9B,KAAK,MAAM,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,IAAI,GAAG,KAAK,cAAc;YAAE,SAAS;QACrC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC/B,MAAM,UAAU,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC;QACpG,IAAI,CAAC,UAAU;YAAE,MAAM,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACpE,CAAC;AACH,CAAC"}
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/seed/store.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cotal-ai/cli",
   "description": "Cotal mesh CLI: up, join, watch, console, spawn, mint, channels, history, ext.",
-  "version": "0.26.0",
+  "version": "0.28.0-hack-20260823202734",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -28,8 +28,8 @@
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
     "ws": "^8.21.0",
-    "@cotal-ai/workspace": "0.26.0",
-    "@cotal-ai/core": "0.26.0"
+    "@cotal-ai/core": "0.28.0-hack-20260823202734",
+    "@cotal-ai/workspace": "0.28.0-hack-20260823202734"
   },
   "optionalDependencies": {
     "@eplightning/nats-server-darwin-arm64": "^2.14.0",