@cello-protocol/daemon 0.0.227 → 0.0.229

package/dist/registry-poll.js.map

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

package/dist/registry-version-store-db.d.ts

@@ -0,0 +1,22 @@
+/**
+ * DOD-REGISTRY-1 — DB-backed registry version store (anti-rollback).
+ *
+ * Same shape as DbManifestVersionStore — a singleton row in the encrypted daemon DB
+ * holding the last-seen registry version. A registry fetch whose version is <= the
+ * persisted version is refused (monotonicity across restarts prevents rollback attacks
+ * where a compromised directory serves an older registry to un-classify a new type).
+ */
+import type { DaemonDatabase } from "./sqlcipher-db.js";
+import type { Logger } from "./types.js";
+export interface IRegistryVersionStore {
+    getLastSeenVersion(): number | null;
+    persistVersion(version: number): void;
+}
+export declare function ensureRegistrySchema(db: DaemonDatabase): void;
+export declare class DbRegistryVersionStore implements IRegistryVersionStore {
+    #private;
+    constructor(db: DaemonDatabase, logger: Logger);
+    getLastSeenVersion(): number | null;
+    persistVersion(version: number): void;
+}
+//# sourceMappingURL=registry-version-store-db.d.ts.map

package/dist/registry-version-store-db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-version-store-db.d.ts","sourceRoot":"","sources":["../src/registry-version-store-db.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGzC,MAAM,WAAW,qBAAqB;IACpC,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAAC;IACpC,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,cAAc,GAAG,IAAI,CAQ7D;AAED,qBAAa,sBAAuB,YAAW,qBAAqB;;gBAItD,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM;IAM9C,kBAAkB,IAAI,MAAM,GAAG,IAAI;IAOnC,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CAiBtC"}

package/dist/registry-version-store-db.js

@@ -0,0 +1,50 @@
+/**
+ * DOD-REGISTRY-1 — DB-backed registry version store (anti-rollback).
+ *
+ * Same shape as DbManifestVersionStore — a singleton row in the encrypted daemon DB
+ * holding the last-seen registry version. A registry fetch whose version is <= the
+ * persisted version is refused (monotonicity across restarts prevents rollback attacks
+ * where a compromised directory serves an older registry to un-classify a new type).
+ */
+import { extractErrorMessage } from "./error-message.js";
+export function ensureRegistrySchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS registry_state (
+      id                INTEGER PRIMARY KEY CHECK (id = 1),
+      last_seen_version INTEGER,
+      updated_at        INTEGER NOT NULL
+    )
+  `);
+}
+export class DbRegistryVersionStore {
+    #db;
+    #logger;
+    constructor(db, logger) {
+        this.#db = db;
+        this.#logger = logger;
+        ensureRegistrySchema(db);
+    }
+    getLastSeenVersion() {
+        const row = this.#db
+            .prepare("SELECT last_seen_version FROM registry_state WHERE id = 1")
+            .get();
+        return row && row.last_seen_version != null ? Number(row.last_seen_version) : null;
+    }
+    persistVersion(version) {
+        try {
+            this.#db
+                .prepare(`INSERT INTO registry_state (id, last_seen_version, updated_at)
+           VALUES (1, ?, ?)
+           ON CONFLICT(id) DO UPDATE SET last_seen_version = excluded.last_seen_version, updated_at = excluded.updated_at`)
+                .run(version, Date.now());
+        }
+        catch (err) {
+            this.#logger.error("registry.version.persist.failed", { version, error: extractErrorMessage(err) });
+            const e = new Error(`registry_persist_failed: ${extractErrorMessage(err)}`);
+            e.code = "registry_persist_failed";
+            throw e;
+        }
+        this.#logger.info("registry.version.persisted", { version });
+    }
+}
+//# sourceMappingURL=registry-version-store-db.js.map

package/dist/registry-version-store-db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-version-store-db.js","sourceRoot":"","sources":["../src/registry-version-store-db.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAOzD,MAAM,UAAU,oBAAoB,CAAC,EAAkB;IACrD,EAAE,CAAC,IAAI,CAAC;;;;;;GAMP,CAAC,CAAC;AACL,CAAC;AAED,MAAM,OAAO,sBAAsB;IACxB,GAAG,CAAiB;IACpB,OAAO,CAAS;IAEzB,YAAY,EAAkB,EAAE,MAAc;QAC5C,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;QACd,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,oBAAoB,CAAC,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED,kBAAkB;QAChB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG;aACjB,OAAO,CAAC,2DAA2D,CAAC;aACpE,GAAG,EAAsD,CAAC;QAC7D,OAAO,GAAG,IAAI,GAAG,CAAC,iBAAiB,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACrF,CAAC;IAED,cAAc,CAAC,OAAe;QAC5B,IAAI,CAAC;YACH,IAAI,CAAC,GAAG;iBACL,OAAO,CACN;;0HAEgH,CACjH;iBACA,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QAC9B,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,iCAAiC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACpG,MAAM,CAAC,GAAG,IAAI,KAAK,CAAC,4BAA4B,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC3E,CAA+B,CAAC,IAAI,GAAG,yBAAyB,CAAC;YAClE,MAAM,CAAC,CAAC;QACV,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,4BAA4B,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IAC/D,CAAC;CACF"}

package/dist/relay-endpoints.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Where a relay is, decided in ONE place.
+ *
+ * The directory hands this daemon the current relay pool on every signaling connect. Past session
+ * rows also carry relay addresses, frozen at whatever the relay advertised when that session began.
+ * Those two disagree after any fleet change — on 2026-09-15 a saved row still held the pre-TLS
+ * `/ip4/…:4001/ws` address, and the mailbox pull, which read saved rows alone, dialled it 1,904
+ * times while three parked messages waited behind it.
+ *
+ * So the directory's pool comes first, per relay peer id, and saved rows only add relays the
+ * directory did not list. Reservation and mailbox pull both use this, so they cannot disagree.
+ */
+export interface RelayEndpoint {
+    relayPeerId: string;
+    relayAddrs: string[];
+}
+export declare function mergeRelayEndpoints(directoryPool: readonly RelayEndpoint[] | undefined, persisted: readonly RelayEndpoint[]): RelayEndpoint[];
+//# sourceMappingURL=relay-endpoints.d.ts.map

package/dist/relay-endpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-endpoints.d.ts","sourceRoot":"","sources":["../src/relay-endpoints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,SAAS,aAAa,EAAE,GAAG,SAAS,EACnD,SAAS,EAAE,SAAS,aAAa,EAAE,GAClC,aAAa,EAAE,CAMjB"}

package/dist/relay-endpoints.js

@@ -0,0 +1,9 @@
+export function mergeRelayEndpoints(directoryPool, persisted) {
+    const merged = new Map();
+    for (const ep of [...(directoryPool ?? []), ...persisted]) {
+        if (!merged.has(ep.relayPeerId))
+            merged.set(ep.relayPeerId, ep);
+    }
+    return [...merged.values()];
+}
+//# sourceMappingURL=relay-endpoints.js.map

package/dist/relay-endpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-endpoints.js","sourceRoot":"","sources":["../src/relay-endpoints.ts"],"names":[],"mappings":"AAiBA,MAAM,UAAU,mBAAmB,CACjC,aAAmD,EACnD,SAAmC;IAEnC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAyB,CAAC;IAChD,KAAK,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC,EAAE,GAAG,SAAS,CAAC,EAAE,CAAC;QAC1D,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,WAAW,CAAC;YAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;AAC9B,CAAC"}

package/dist/relay-only.d.ts

@@ -0,0 +1,140 @@
+/**
+ * CELLO Daemon — relay-only routing (`DOD-M15-RELAYONLY-1`).
+ *
+ * The feature half of the IP disclosure. A direct session reveals the operator's IP permanently;
+ * relay routing is the mitigation, and until now it was a footnote in an architecture document
+ * rather than something an operator could switch on.
+ *
+ * ─── ⚠️ WHY THIS IS NOT A `transport_mode` SETTING ─────────────────────────────────────────────
+ *
+ * `transport_mode` DOES NOT CONTROL WHETHER A DIRECT CONNECTION HAPPENS, and a setting that wrote it
+ * would be a privacy control that does not protect privacy:
+ *
+ *   - The directory already defaults the label to relay (`requestedTransportMode ?? "relay"`), so in
+ *     the ordinary case the label ALREADY reads "relay".
+ *   - And the client dials directly anyway — the gate is `counterparty_session_addrs.length > 0`,
+ *     *"regardless of the transport_mode LABEL"*, in `initiate-session-handler.ts`'s own words.
+ *
+ * So the IP is exposed today on a path whose label already claims otherwise, and an operator who set
+ * a label-only flag would be told they were protected while they were not.
+ *
+ * ─── The two halves, and why the second is the one that makes it a control ────────────────────
+ *
+ * A direct connection leaks the IP in BOTH directions:
+ *
+ *   1. **We dial only their CIRCUIT** — `dialableAddrs`. Dialling their direct address hands them
+ *      ours; dialling the circuit terminates at the relay and reveals nothing.
+ *   2. **We publish only our own CIRCUIT** — `publishableEndpoint`. The only route they hold points
+ *      at the relay, which protects the operator **even against a counterparty who ignores the flag**.
+ *
+ * The second is load-bearing: *a control that depends on the other side honouring it is not a
+ * control.* The first alone would leave us reachable by anyone who kept our address.
+ *
+ * ⚠️ **AND NEITHER HALF IS SUFFICIENT WHILE libp2p CAN SPEAK FOR US.** These functions filter what
+ * the DIRECTORY is told. `identify` hands a peer our listen addresses on the first relayed
+ * connection, and `dcutr` actively hole-punches a relayed connection into a direct one — the inbound
+ * side starts that upgrade, and a relay-only responder IS the inbound side. Both bypass everything
+ * here, peer-to-peer. `createNode`'s `holePunch: { enabled: false }` closes the second; the announce
+ * filter closes the first. **Without those, this file filters the paperwork and leaves the wire
+ * open** — see `DOD-M15-RELAYONLY-1`.
+ *
+ * `publishableEndpoint` is applied INSIDE `getStandingReceiverInfo` — the single method both publish
+ * paths draw from — rather than at its call sites. Suppressing at call sites would be a hand-kept
+ * list, and a fourth publish path added later would leak while every test stayed green. At the choke
+ * point a new caller inherits the protection instead of having to be told about it.
+ */
+/** The per-agent settings key. Lower-snake, dotted namespace, per `agent-settings-keys.ts`. */
+export declare const RELAY_ONLY_KEY = "transport.relay_only";
+/**
+ * Is relay-only routing ON for this agent?
+ *
+ * ⚠️ THE FAILURE DIRECTION IS CHOSEN, not incidental. **Only the exact string `"true"` is ON.**
+ * Unset reads OFF because the daemon must run correctly on defaults alone; a corrupt or unparseable
+ * value also reads OFF, because reading a value nobody validated as ON would silently break every
+ * ordinary direct session.
+ *
+ * That leaves one hazard — a typo'd value that the operator believes turned the control on — and it
+ * is closed at the WRITE boundary instead: `validateSettingValue` refuses anything but `"true"` and
+ * `"false"`, loudly, so a mistyped value can never be stored to be misread here.
+ */
+export declare function isRelayOnly(getSetting: (key: string) => string | null): boolean;
+/**
+ * The setting's state when the read itself may fail — `"on" | "off" | "unknown"`.
+ *
+ * ⚠️ **"THE DATABASE IS GONE" IS NOT A VALUE, AND TREATING IT AS ONE FAILS TOWARD DISCLOSURE.**
+ * `getSetting` returns `null` both for *unset* and for *no database*, and `isRelayOnly` reads both
+ * as OFF. Unset-means-off is right; **db-gone-means-off is not** — the standing receiver outlives
+ * the database during shutdown, so an offer arriving in that window would publish the operator's
+ * real addresses with relay-only switched on.
+ *
+ * A read that THROWS is also `"unknown"` rather than an escaping exception: this sits on a ceremony
+ * path with no catch, where a throw becomes an unhandled rejection and the offer vanishes with no
+ * local log — the initiator then sees `counterparty_did_not_accept` and blames its own subsystem.
+ *
+ * The caller decides what `"unknown"` costs. For publishing, it must cost a refusal, never a guess.
+ */
+export declare function relayOnlyState(getSetting: (key: string) => string | null, readable: boolean): "on" | "off" | "unknown";
+/** A session-transport endpoint as published to a counterparty. */
+export interface PublishableEndpoint {
+    peerId: string;
+    addrs: string[];
+}
+/**
+ * A relay-CIRCUIT multiaddr — the address that discloses nothing about the operator.
+ *
+ * ⚠️ THIS IS THE DISTINCTION THE WHOLE UNIT TURNS ON, and getting it wrong the first time took the
+ * operator OFF THE NETWORK rather than making them private. A `/p2p-circuit` address names the
+ * **RELAY's** address and our peer id. It terminates at the relay. Publishing one tells a
+ * counterparty how to reach us *through* the relay and tells them nothing about where we are;
+ * dialing one reveals us to the relay we already chose, not to them.
+ *
+ * So relay-only is not "no addresses". It is "circuit addresses only".
+ */
+export declare function isCircuitAddr(addr: string): boolean;
+/**
+ * The endpoint as it may leave this machine.
+ *
+ * ⚠️ **AN EMPTY ADDRESS ARRAY IS NOT A PRIVATE FRAME, IT IS A MALFORMED ONE.** The first build of
+ * this published `addrs: []` and the directory refuses exactly that on both sides — a
+ * `session_request` whose `initiator_session_addrs` is empty is rejected outright, and a
+ * `session_offer_accept` is only folded in `if (counterparty_session_addrs.length > 0)`, **with no
+ * `else`**, so the accept was silently dropped and the offer waiter never resolved. The operator
+ * switched on a privacy control and was told their counterparty was offline.
+ *
+ * So we publish the **circuit-only subset**: enough for the directory to build a real assignment and
+ * for the counterparty to reach us over the relay, and nothing that points at the operator.
+ *
+ * A genuinely empty result is meaningful and is NOT silently published — see `relayOnlyReachable`.
+ * A null endpoint stays null: "no standing receiver" and "a receiver at no address" are different
+ * facts, and collapsing them would let a caller advertise an endpoint that does not exist.
+ */
+export declare function publishableEndpoint<T extends PublishableEndpoint>(endpoint: T | null, relayOnly: boolean): T | PublishableEndpoint | null;
+/**
+ * Can a relay-only agent actually be reached with what it is about to publish?
+ *
+ * FALSE means it holds **no relay reservation**, so the circuit-only subset is empty.
+ *
+ * ⚠️ **"YET" WAS DROPPED FROM THAT SENTENCE ON PURPOSE — 056-SLOTDEAD.** It meant "the login walk
+ * has not got there yet", i.e. wait and it will become true on its own. Since 055-ONDEMAND an idle
+ * agent holds none and never will: the slot is taken at offer time, so this is asked AFTER the
+ * on-demand reserve and a FALSE here means that reserve genuinely failed. Reading it as "not yet"
+ * would argue for retrying rather than refusing, on a call that is waiting for an answer now.
+ *
+ * That must be a LOUD LOCAL REFUSAL rather than an empty publish: an empty publish is refused by the
+ * directory as malformed and surfaces to the operator as "the counterparty is offline", which is a
+ * lie about someone else's state caused by a setting on this machine.
+ */
+export declare function relayOnlyReachable(endpoint: PublishableEndpoint | null, relayOnly: boolean): boolean;
+/**
+ * Which of the counterparty's advertised addresses may we dial?
+ *
+ * ⚠️ Returns the FILTERED LIST, not a boolean, because "relay-only" does not mean "do not connect" —
+ * it means "connect only over the circuit". The first build refused every address including the
+ * `/p2p-circuit` one, which is the relay route this setting exists to force everything onto, so it
+ * dropped every session onto the store-and-forward backstop.
+ *
+ * The counterparty may not be relay-only themselves, so they will still advertise direct addresses:
+ * those are dropped, because dialing one hands them our IP with our own setting switched on.
+ */
+export declare function dialableAddrs(addrs: readonly string[], relayOnly: boolean): string[];
+//# sourceMappingURL=relay-only.d.ts.map

package/dist/relay-only.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-only.d.ts","sourceRoot":"","sources":["../src/relay-only.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAGH,+FAA+F;AAC/F,eAAO,MAAM,cAAc,yBAAyB,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,OAAO,CAE/E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,EAC1C,QAAQ,EAAE,OAAO,GAChB,IAAI,GAAG,KAAK,GAAG,SAAS,CAO1B;AAED,mEAAmE;AACnE,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CA+BnD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,mBAAmB,EAC/D,QAAQ,EAAE,CAAC,GAAG,IAAI,EAClB,SAAS,EAAE,OAAO,GACjB,CAAC,GAAG,mBAAmB,GAAG,IAAI,CAIhC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,EAAE,SAAS,EAAE,OAAO,GAAG,OAAO,CAIpG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,EAAE,CAGpF"}

package/dist/relay-only.js

@@ -0,0 +1,193 @@
+/**
+ * CELLO Daemon — relay-only routing (`DOD-M15-RELAYONLY-1`).
+ *
+ * The feature half of the IP disclosure. A direct session reveals the operator's IP permanently;
+ * relay routing is the mitigation, and until now it was a footnote in an architecture document
+ * rather than something an operator could switch on.
+ *
+ * ─── ⚠️ WHY THIS IS NOT A `transport_mode` SETTING ─────────────────────────────────────────────
+ *
+ * `transport_mode` DOES NOT CONTROL WHETHER A DIRECT CONNECTION HAPPENS, and a setting that wrote it
+ * would be a privacy control that does not protect privacy:
+ *
+ *   - The directory already defaults the label to relay (`requestedTransportMode ?? "relay"`), so in
+ *     the ordinary case the label ALREADY reads "relay".
+ *   - And the client dials directly anyway — the gate is `counterparty_session_addrs.length > 0`,
+ *     *"regardless of the transport_mode LABEL"*, in `initiate-session-handler.ts`'s own words.
+ *
+ * So the IP is exposed today on a path whose label already claims otherwise, and an operator who set
+ * a label-only flag would be told they were protected while they were not.
+ *
+ * ─── The two halves, and why the second is the one that makes it a control ────────────────────
+ *
+ * A direct connection leaks the IP in BOTH directions:
+ *
+ *   1. **We dial only their CIRCUIT** — `dialableAddrs`. Dialling their direct address hands them
+ *      ours; dialling the circuit terminates at the relay and reveals nothing.
+ *   2. **We publish only our own CIRCUIT** — `publishableEndpoint`. The only route they hold points
+ *      at the relay, which protects the operator **even against a counterparty who ignores the flag**.
+ *
+ * The second is load-bearing: *a control that depends on the other side honouring it is not a
+ * control.* The first alone would leave us reachable by anyone who kept our address.
+ *
+ * ⚠️ **AND NEITHER HALF IS SUFFICIENT WHILE libp2p CAN SPEAK FOR US.** These functions filter what
+ * the DIRECTORY is told. `identify` hands a peer our listen addresses on the first relayed
+ * connection, and `dcutr` actively hole-punches a relayed connection into a direct one — the inbound
+ * side starts that upgrade, and a relay-only responder IS the inbound side. Both bypass everything
+ * here, peer-to-peer. `createNode`'s `holePunch: { enabled: false }` closes the second; the announce
+ * filter closes the first. **Without those, this file filters the paperwork and leaves the wire
+ * open** — see `DOD-M15-RELAYONLY-1`.
+ *
+ * `publishableEndpoint` is applied INSIDE `getStandingReceiverInfo` — the single method both publish
+ * paths draw from — rather than at its call sites. Suppressing at call sites would be a hand-kept
+ * list, and a fourth publish path added later would leak while every test stayed green. At the choke
+ * point a new caller inherits the protection instead of having to be told about it.
+ */
+/** The per-agent settings key. Lower-snake, dotted namespace, per `agent-settings-keys.ts`. */
+export const RELAY_ONLY_KEY = "transport.relay_only";
+/**
+ * Is relay-only routing ON for this agent?
+ *
+ * ⚠️ THE FAILURE DIRECTION IS CHOSEN, not incidental. **Only the exact string `"true"` is ON.**
+ * Unset reads OFF because the daemon must run correctly on defaults alone; a corrupt or unparseable
+ * value also reads OFF, because reading a value nobody validated as ON would silently break every
+ * ordinary direct session.
+ *
+ * That leaves one hazard — a typo'd value that the operator believes turned the control on — and it
+ * is closed at the WRITE boundary instead: `validateSettingValue` refuses anything but `"true"` and
+ * `"false"`, loudly, so a mistyped value can never be stored to be misread here.
+ */
+export function isRelayOnly(getSetting) {
+    return getSetting(RELAY_ONLY_KEY) === "true";
+}
+/**
+ * The setting's state when the read itself may fail — `"on" | "off" | "unknown"`.
+ *
+ * ⚠️ **"THE DATABASE IS GONE" IS NOT A VALUE, AND TREATING IT AS ONE FAILS TOWARD DISCLOSURE.**
+ * `getSetting` returns `null` both for *unset* and for *no database*, and `isRelayOnly` reads both
+ * as OFF. Unset-means-off is right; **db-gone-means-off is not** — the standing receiver outlives
+ * the database during shutdown, so an offer arriving in that window would publish the operator's
+ * real addresses with relay-only switched on.
+ *
+ * A read that THROWS is also `"unknown"` rather than an escaping exception: this sits on a ceremony
+ * path with no catch, where a throw becomes an unhandled rejection and the offer vanishes with no
+ * local log — the initiator then sees `counterparty_did_not_accept` and blames its own subsystem.
+ *
+ * The caller decides what `"unknown"` costs. For publishing, it must cost a refusal, never a guess.
+ */
+export function relayOnlyState(getSetting, readable) {
+    if (!readable)
+        return "unknown";
+    try {
+        return getSetting(RELAY_ONLY_KEY) === "true" ? "on" : "off";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * A relay-CIRCUIT multiaddr — the address that discloses nothing about the operator.
+ *
+ * ⚠️ THIS IS THE DISTINCTION THE WHOLE UNIT TURNS ON, and getting it wrong the first time took the
+ * operator OFF THE NETWORK rather than making them private. A `/p2p-circuit` address names the
+ * **RELAY's** address and our peer id. It terminates at the relay. Publishing one tells a
+ * counterparty how to reach us *through* the relay and tells them nothing about where we are;
+ * dialing one reveals us to the relay we already chose, not to them.
+ *
+ * So relay-only is not "no addresses". It is "circuit addresses only".
+ */
+export function isCircuitAddr(addr) {
+    // ⚠️ PARSED, never substring-matched. `addr.includes("/p2p-circuit")` was defeatable by the
+    // COUNTERPARTY, who controls these strings — the directory copies them verbatim and the FROST
+    // signature attests that the quorum agreed on the assignment, NOT that its contents are circuits.
+    //
+    //     /dns4/p2p-circuit.attacker.example/tcp/443/p2p/12D3KooWTheirs
+    //
+    // contains the literal text, resolves through the DNS transport, and would have been dialled
+    // directly — handing over the operator's IP with relay-only switched ON, while the suppression log
+    // reported `suppressed: 0`. A control a peer can defeat by naming a host is precisely what this
+    // line rules out.
+    //
+    // EXACT SEGMENT match on the multiaddr's own `/`-delimited components. `p2p-circuit` is a
+    // standalone protocol with no value, so it appears as a whole segment; a hostname that merely
+    // CONTAINS the text appears as `p2p-circuit.attacker.example`, which is a different segment and is
+    // correctly rejected.
+    //
+    // Deliberately NOT `multiaddr().protoNames()`, which would be the stricter parse: that lives in
+    // `@multiformats/multiaddr`, a dependency `core/daemon` does not have. Reaching for it here would
+    // add a package to the daemon to make one boolean stricter, and this client is installed on
+    // operators' machines where install weight is a user-facing cost. The exact-segment test defeats
+    // the demonstrated bypass with no new dependency.
+    //
+    // ⚠️ RESIDUAL, stated rather than left implied, and TRACKED as `DOD-M15-CIRCUIT-RELAY-BIND-1`:
+    // this proves the address CLAIMS a circuit hop, not that the circuit runs through a relay we
+    // chose. A counterparty can name a relay we hold no reservation with — including one they run —
+    // and `dialableAddrs` will pass it, so the relay they named learns our IP with relay-only on.
+    // The stronger check is binding the embedded relay peer id to our own reservations, and it needs
+    // the reservation set here, which this module does not have. Do not narrow the bound by editing
+    // this sentence; close it at the call site that holds the reservations.
+    return addr.split("/").includes("p2p-circuit");
+}
+/**
+ * The endpoint as it may leave this machine.
+ *
+ * ⚠️ **AN EMPTY ADDRESS ARRAY IS NOT A PRIVATE FRAME, IT IS A MALFORMED ONE.** The first build of
+ * this published `addrs: []` and the directory refuses exactly that on both sides — a
+ * `session_request` whose `initiator_session_addrs` is empty is rejected outright, and a
+ * `session_offer_accept` is only folded in `if (counterparty_session_addrs.length > 0)`, **with no
+ * `else`**, so the accept was silently dropped and the offer waiter never resolved. The operator
+ * switched on a privacy control and was told their counterparty was offline.
+ *
+ * So we publish the **circuit-only subset**: enough for the directory to build a real assignment and
+ * for the counterparty to reach us over the relay, and nothing that points at the operator.
+ *
+ * A genuinely empty result is meaningful and is NOT silently published — see `relayOnlyReachable`.
+ * A null endpoint stays null: "no standing receiver" and "a receiver at no address" are different
+ * facts, and collapsing them would let a caller advertise an endpoint that does not exist.
+ */
+export function publishableEndpoint(endpoint, relayOnly) {
+    if (endpoint === null)
+        return null;
+    if (!relayOnly)
+        return endpoint;
+    return { peerId: endpoint.peerId, addrs: endpoint.addrs.filter(isCircuitAddr) };
+}
+/**
+ * Can a relay-only agent actually be reached with what it is about to publish?
+ *
+ * FALSE means it holds **no relay reservation**, so the circuit-only subset is empty.
+ *
+ * ⚠️ **"YET" WAS DROPPED FROM THAT SENTENCE ON PURPOSE — 056-SLOTDEAD.** It meant "the login walk
+ * has not got there yet", i.e. wait and it will become true on its own. Since 055-ONDEMAND an idle
+ * agent holds none and never will: the slot is taken at offer time, so this is asked AFTER the
+ * on-demand reserve and a FALSE here means that reserve genuinely failed. Reading it as "not yet"
+ * would argue for retrying rather than refusing, on a call that is waiting for an answer now.
+ *
+ * That must be a LOUD LOCAL REFUSAL rather than an empty publish: an empty publish is refused by the
+ * directory as malformed and surfaces to the operator as "the counterparty is offline", which is a
+ * lie about someone else's state caused by a setting on this machine.
+ */
+export function relayOnlyReachable(endpoint, relayOnly) {
+    if (!relayOnly)
+        return true;
+    if (endpoint === null)
+        return false;
+    return endpoint.addrs.some(isCircuitAddr);
+}
+/**
+ * Which of the counterparty's advertised addresses may we dial?
+ *
+ * ⚠️ Returns the FILTERED LIST, not a boolean, because "relay-only" does not mean "do not connect" —
+ * it means "connect only over the circuit". The first build refused every address including the
+ * `/p2p-circuit` one, which is the relay route this setting exists to force everything onto, so it
+ * dropped every session onto the store-and-forward backstop.
+ *
+ * The counterparty may not be relay-only themselves, so they will still advertise direct addresses:
+ * those are dropped, because dialing one hands them our IP with our own setting switched on.
+ */
+export function dialableAddrs(addrs, relayOnly) {
+    if (!relayOnly)
+        return [...addrs];
+    return addrs.filter(isCircuitAddr);
+}
+//# sourceMappingURL=relay-only.js.map

package/dist/relay-only.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-only.js","sourceRoot":"","sources":["../src/relay-only.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAGH,+FAA+F;AAC/F,MAAM,CAAC,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CAAC,UAA0C;IACpE,OAAO,UAAU,CAAC,cAAc,CAAC,KAAK,MAAM,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAC5B,UAA0C,EAC1C,QAAiB;IAEjB,IAAI,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChC,IAAI,CAAC;QACH,OAAO,UAAU,CAAC,cAAc,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;IAC9D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAQD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,4FAA4F;IAC5F,8FAA8F;IAC9F,kGAAkG;IAClG,EAAE;IACF,oEAAoE;IACpE,EAAE;IACF,6FAA6F;IAC7F,mGAAmG;IACnG,gGAAgG;IAChG,kBAAkB;IAClB,EAAE;IACF,0FAA0F;IAC1F,8FAA8F;IAC9F,mGAAmG;IACnG,sBAAsB;IACtB,EAAE;IACF,gGAAgG;IAChG,kGAAkG;IAClG,4FAA4F;IAC5F,iGAAiG;IACjG,kDAAkD;IAClD,EAAE;IACF,+FAA+F;IAC/F,6FAA6F;IAC7F,gGAAgG;IAChG,8FAA8F;IAC9F,iGAAiG;IACjG,gGAAgG;IAChG,wEAAwE;IACxE,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAkB,EAClB,SAAkB;IAElB,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,CAAC,SAAS;QAAE,OAAO,QAAQ,CAAC;IAChC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;AAClF,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAoC,EAAE,SAAkB;IACzF,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAC5B,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACpC,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,KAAwB,EAAE,SAAkB;IACxE,IAAI,CAAC,SAAS;QAAE,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;IAClC,OAAO,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;AACrC,CAAC"}

package/dist/relay-receipt-store.d.ts

@@ -0,0 +1,155 @@
+import type { DaemonDatabase } from "./sqlcipher-db.js";
+import type { Logger } from "./types.js";
+/** A relay's signed ACK for a submitted content hash, stored as an immutable receipt. */
+export interface RelayReceipt {
+    /** Hex of the 32-byte content hash the relay witnessed + sequenced (payload, NOT the unique key). */
+    hashHex: string;
+    /** Hex of the agent (K_local pubkey) this receipt belongs to. */
+    agentPubkeyHex: string;
+    /** Session this hash belonged to (hex) — part of the unique attestation position. */
+    sessionIdHex: string;
+    /** Stable relay identifier (relay-node sets relayId = hex of its ACK-signing pubkey). */
+    relayId: string;
+    /** Hex of the 32-byte Ed25519 pubkey that signed this ACK (= relayId; the directory confirms it at seal). */
+    relayPubkeyHex: string;
+    /** Relay-assigned canonical sequence number — part of the unique attestation position. */
+    sequenceNumber: number;
+    /** Unix ms timestamp embedded in the ACK TBS. */
+    timestamp: number;
+    /**
+     * 069-ORDERPROOF — hex of the 32-byte running root of this session's tree AFTER this leaf was
+     * appended, as the relay signed it. The position alone says where a leaf sits in a COUNTER; the
+     * root says where it sits in a CHAIN, which is what lets a party prove a prefix once the relay is
+     * gone. Optional on the TYPE only so rows written before this order still read; every row this
+     * build writes has one.
+     */
+    runningRootHex?: string;
+    /** Hex of the 64-byte Ed25519 signature over the ACK TBS. */
+    signatureHex: string;
+    /** The relay's committed Structure2 (CBOR) for this leaf (DOD-MSG-4 hash_submit_ack). */
+    structure2Cbor?: Uint8Array;
+    /** The sender-signed Structure1 (CBOR) for this leaf. */
+    structure1Cbor?: Uint8Array;
+    /** Leaf kind: 0x00 message, 0x02 control (SEAL). */
+    leafKind?: number;
+}
+/**
+ * FED-OPTIONB-SEAL-001: a fully-carried leaf for the unilateral-seal offline rebuild — a receipt that has
+ * its Structure2/Structure1 carry bytes. `getSealLeaves` returns these (the chain the directory can rebuild
+ * + verify offline), narrowing the optional carry fields to required.
+ */
+export interface SealLeaf extends RelayReceipt {
+    structure2Cbor: Uint8Array;
+    structure1Cbor: Uint8Array;
+    leafKind: number;
+}
+/**
+ * Verify a relay ordering attestation against a relay pubkey the CALLER supplies — and the caller
+ * must have got it from the directory-signed assignment, never from the frame.
+ *
+ * Returns true iff every field is well-formed and the 64-byte Ed25519 signature verifies over
+ * TBS = SHA-256(DOMAIN ‖ session_id ‖ content_hash ‖ seq_BE4 ‖ running_root ‖ ts_BE8) — the same
+ * statement the relay signs. A forged sequence, a swapped session or a rewritten prefix all change
+ * the TBS, so each fails.
+ *
+ * A wrong-length field returns FALSE rather than throwing: these bytes come off a wire the relay
+ * controls, and a malformed length must refuse this attestation, not take down the frame handler.
+ */
+export declare function verifyRelayAck(sessionId: Uint8Array, contentHash: Uint8Array, sequenceNumber: number, runningRoot: Uint8Array, timestamp: number, signature: Uint8Array, relayPubkey: Uint8Array): boolean;
+/** Why an attestation was refused. For the LOG — the protocol outcome is identical for all of them. */
+export type AckRefusalCause = 
+/** This session has no directory-named relay key recorded, so nothing can anchor the check. */
+"no_anchor"
+/** The frame named a relay other than the one the directory assigned to this session. */
+ | "relay_not_assigned"
+/** `relay_id` was present but is not a 64-hex Ed25519 pubkey. */
+ | "bad_relay_id"
+/** No signature, no timestamp, or no running root — the relay attested nothing. */
+ | "attestation_absent"
+/** The signature does not bind (session, hash, sequence, root, timestamp) under the assigned key. */
+ | "signature_invalid";
+/** The decision for one `hash_submit_ack` — pure + directly unit-testable (the verify-gates-store wiring). */
+export type AckEvaluation = {
+    kind: "store";
+    receipt: RelayReceipt;
+}
+/**
+ * REFUSED. One outcome for missing, malformed and mismatched — the caller must treat all three
+ * identically, and `cause` exists so the LOG can still name which one it was. A caller that
+ * branches on `cause` to soften any of them reintroduces exactly the hole this closes.
+ */
+ | {
+    kind: "refused";
+    cause: AckRefusalCause;
+};
+/**
+ * Read back the leaf we just submitted, so the relay's attestation has something to be checked
+ * against — the step BEFORE `evaluateRelayAck`, and the one that decides whether the check can run
+ * at all.
+ *
+ * ⚠️ "COULD NOT RUN THE CHECK" IS NOT "THE CHECK PASSED" — 069-ORDERPROOF.
+ *
+ * Both failures here used to be waved through by the caller, which settled the send `ok` having
+ * verified nothing: the absent-versus-verified collapse this unit exists to remove, reproduced at
+ * the one point where nothing was left to verify with. These are our OWN just-signed bytes, so a
+ * hostile relay cannot steer into either — unreachable in practice, which is a different claim from
+ * safe to wave through, and the distinction is the one that decays under later edits.
+ *
+ * `"none"` is the honest third answer: no submit was made, so no attestation is owed and none is
+ * missing. It is the only one of the three that does not reject.
+ */
+export declare function readSubmittedLeaf(structure1Cbor: Uint8Array | undefined, seq: number): {
+    kind: "none";
+} | {
+    kind: "unreadable";
+    event: string;
+    reason?: string;
+} | {
+    kind: "ok";
+    contentHash: Uint8Array;
+    sessionId: Uint8Array;
+};
+/**
+ * Evaluate a relay ordering attestation: decide whether it yields a storable, signature-verified
+ * receipt. This is the verify-gates-store decision in isolation, so it is unit-testable without the
+ * relay stream.
+ *
+ * `expectedRelayPubkeyHex` is the anchor and it is REQUIRED in substance: `undefined` refuses. It
+ * must come from `relay_id` on an assignment whose FROST signature has been verified.
+ */
+export declare function evaluateRelayAck(params: {
+    sessionId: Uint8Array;
+    contentHash: Uint8Array;
+    runningRoot: Uint8Array | undefined;
+    sessionIdHex: string;
+    agentPubkeyHex: string;
+    /** The relay the DIRECTORY assigned to this session, hex. Absent ⇒ nothing to anchor to ⇒ refuse. */
+    expectedRelayPubkeyHex: string | undefined;
+    relayId: string | undefined;
+    relaySignature: Uint8Array | undefined;
+    timestamp: number | undefined;
+    sequenceNumber: number;
+}): AckEvaluation;
+export declare class RelayReceiptStore {
+    #private;
+    constructor(db: DaemonDatabase, logger: Logger);
+    /**
+     * Persist a VERIFIED receipt. IMMUTABLE: keyed on the attestation POSITION (agent, session, sequence) —
+     * `INSERT OR IGNORE` keeps the FIRST hash recorded for a position, so a relay cannot rewrite the hash it
+     * already attested at that (session, sequence). Returns true if a new row was written, false if the
+     * position was already recorded (logged distinctly when the existing hash DIFFERS — a relay equivocation).
+     */
+    store(receipt: RelayReceipt, storedAtMs: number): boolean;
+    /** The stored receipt at an attestation position (agent, session, sequence), or undefined. */
+    get(agentPubkeyHex: string, sessionIdHex: string, sequenceNumber: number): RelayReceipt | undefined;
+    /** All receipts for an agent (optionally a single session), in canonical sequence order (ascending). */
+    getAll(agentPubkeyHex: string, sessionIdHex?: string): RelayReceipt[];
+    /**
+     * FED-OPTIONB-SEAL-001: the complete carried leaf chain for a session's UNILATERAL seal — every receipt
+     * that has its Structure2/Structure1 carry bytes, ordered by canonical sequence. The directory rebuilds +
+     * verifies this tree OFFLINE (no directory→relay getSealLeaves dial). Rows without carry bytes
+     * (pre-migration / receipt-only) are omitted: the caller carries only what the directory can rebuild.
+     */
+    getSealLeaves(agentPubkeyHex: string, sessionIdHex: string): SealLeaf[];
+}
+//# sourceMappingURL=relay-receipt-store.d.ts.map

package/dist/relay-receipt-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-receipt-store.d.ts","sourceRoot":"","sources":["../src/relay-receipt-store.ts"],"names":[],"mappings":"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"}