@reticulum/dacar 1.1.0 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticulum/dacar",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "JavaScript implementation of Dacar, a Decentralized Access Control system for Reticulum",
   "type": "module",
   "main": "src/index.js",

package/src/cli/dacar.js

@@ -18,6 +18,7 @@
  *   dacar check <grantee> <relation> <object>
  *   dacar grants
  *   dacar revoke <grantee> <relation> <object> [--publish]
+ *   dacar publish <file> [<file>...] | --all   (work doc #8)
  *   dacar identity remember|forget|list ...
  *
  * Online flags: --node <hash>, --topic <topic>, --interface shared|auto|tcp,
@@ -28,17 +29,14 @@ import { parseArgs } from "node:util";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { pathToFileURL } from "node:url";
 import process from "node:process";
 
-import { Identity, Reticulum, toHex } from "@reticulum/core";
+import { Identity, toHex } from "@reticulum/core";
 import { MemoryStorageAdapter } from "@reticulum/core";
-import {
-  AutoInterface,
-  FileStorageAdapter,
-  LocalClientInterface,
-  TCPClientInterface,
-} from "@reticulum/node";
+import { FileStorageAdapter } from "@reticulum/node";
 import { RFedClient } from "@reticulum/core/src/rfed/client.js";
+import { bootRns } from "./rns_boot.js";
 
 import { Action, Operation, Tuple, Engine } from "../index.js";
 import { DeltaReceiver } from "../delta.js";
@@ -48,7 +46,7 @@ import { NamespaceHasher, DEFAULT_SALT, SALT_SIZE, HASH_SIZE } from "../namespac
 import { Keyring, IssuerKeyset } from "../verifier.js";
 
 import { DacarStore, SELF_ALIAS, AliasRegistry } from "./store.js";
-import { announceIdentity, runPublish, runSync, registerAnnounceHandler } from "./session.js";
+import { announceIdentity, discoverRfedNode, ensureNodeIdentity, runPublish, runSync, registerAnnounceHandler } from "./session.js";
 
 const SHORT_HASH = 7;
 
@@ -131,30 +129,18 @@ async function resolveRnsConfigDir(args) {
   return dir;
 }
 
-/**
- * Boot RNS with an interface. Mirrors `@reticulum/node`'s `rfed` CLI:
- * `--interface shared|auto|tcp` (default `shared`).
- */
-async function bootRns(configDir, iface) {
-  const rns = new Reticulum({ storageAdapter: new FileStorageAdapter(configDir) });
-  if (iface === "auto") {
-    rns.addInterface(new AutoInterface({}));
-  } else if (iface === "tcp") {
-    const host = process.env.RNS_HOST || "127.0.0.1";
-    const port = parseInt(process.env.RNS_PORT || "42424", 10);
-    rns.addInterface(new TCPClientInterface({ host, port }));
-  } else {
-    // shared (default): attach to a running rnsd, else no-op (standalone).
-    rns.addInterface(new LocalClientInterface({}));
-  }
-  return rns;
-}
+// `bootRns` lives in `./rns_boot.js` (Node-only): it constructs, **connects**,
+// and default-attaches the chosen mesh interface, and optionally raises the
+// Reticulum log threshold + logs each announce for `--verbose`. See
+// `src/cli/rns_boot.js` for why `connect()` + `isDefault=true` are
+// non-optional (the `--discover` silent-timeout symptom).
 
-async function resolveRfedNode(args, store, aliases) {
+async function resolveRfedNode(args, store, aliases, rns) {
   if (args.node) return resolveIdentityHash(args.node, aliases);
   const raw = await store.loadConfig();
   if (raw.rfedNode) return raw.rfedNode;
-  throw new CliError("no rfed node configured (use --node <hash> or set [rfed] node in config)");
+  if (args.discover && rns) return discoverRfedNode({ rns, timeout: 30000 });
+  throw new CliError("no rfed node configured (use --node <hash>, --discover, or set [rfed] node in config)");
 }
 
 async function resolveTopic(args, store) {
@@ -235,28 +221,47 @@ async function _issue(args, action) {
 
   // Record plaintext ledger.
   const ledger = await store.loadLedger();
-  ledger.set(toHex(tuple.key), { object: args.object, relation: args.relation, wildcard: args.object.endsWith("*") && args.object !== "*", firstSeen: Number(hlc >> 16n) });
+  ledger.set(tuple.key, { object: args.object, relation: args.relation, wildcard: args.object.endsWith("*") && args.object !== "*", firstSeen: Number(hlc >> 16n) });
   await store.saveLedger(ledger);
 
-  out(payload.hex());
+  out(toHex(payload));
   err(`✔ ${action === Action.GRANT ? "granted" : "revoked"} ${shortHash(grantee, args.fullHashes)}  ${args.relation}  on  ${args.object}`);
   err(`  hlc     : 0x${hlc.toString(16)}`);
   err(`  payload : hex on stdout (${payload.length} bytes)`);
 
   if (args.publish) {
     await publishDelta(args, store, identity, payload);
+  } else {
+    // Outbox (work doc #8): queue locally-issued deltas for `publish --all`.
+    // `--publish` sends immediately and never enqueues. (JS `grant` always
+    // applies locally — there is no `--no-apply` — so every non-publish grant
+    // is a candidate for later batch publish.)
+    const outbox = await store.loadOutbox();
+    outbox.push(payload);
+    await store.saveOutbox(outbox);
+    err("  (queued in outbox: `dacar publish --all` to flush)");
   }
   return 0;
 }
 
 async function publishDelta(args, store, identity, payload) {
   const aliases = await store.loadAliases();
-  const nodeHash = await resolveRfedNode(args, store, aliases);
   const topic = await resolveTopic(args, store);
-
   const configDir = await resolveRnsConfigDir(args);
-  const rns = await bootRns(configDir, args.interface || "shared");
-  await announceIdentity(identity);
+  const rns = await bootRns(configDir, args.interface || "shared", {
+    verbose: !!args.verbose,
+  });
+  // RNS must be booted before resolveRfedNode: --discover listens for peer
+  // announces on the live transport (mirrors Python's _publish_delta).
+  const nodeHash = await resolveRfedNode(args, store, aliases, rns);
+  await announceIdentity(identity, rns);
+  // Proactively fetch the rfed node's identity: when --node is given (or
+  // --discover derived it), the destination's announce may not yet be in
+  // the recall store. Send a path? request and wait for the announce rather
+  // than failing with "wait for its announce" (work doc #6).
+  await ensureNodeIdentity(rns, nodeHash, {
+    onRequest: () => err("  requesting rfed node identity…"),
+  });
 
   // Durable issuer cache (doc #5): seed from observed dacar.node announces.
   const keyring = await store.loadKeyring();
@@ -276,18 +281,27 @@ async function cmdSync(args) {
   const identity = await store.loadIdentity();
   if (!identity) throw new CliError("no signing identity (run `dacar init`)");
 
-  const nodeHash = await resolveRfedNode(args, store, aliases);
-  const topic = await resolveTopic(args, store);
-
+  // RNS must be booted before discover if we're autodiscovering
   const configDir = await resolveRnsConfigDir(args);
-  const rns = await bootRns(configDir, args.interface || "shared");
-  await announceIdentity(identity);
+  const rns = await bootRns(configDir, args.interface || "shared", {
+    verbose: !!args.verbose,
+  });
+  await announceIdentity(identity, rns);
 
   // Durable issuer cache (doc #5): load persisted keyring + announce handler.
   const keyring = await store.loadKeyring();
   keyring.registerSingle(identity.identityHash, await identity.getPublicKey());
   await registerAnnounceHandler({ rns, keyring, onSave: (kr) => store.saveKeyring(kr) });
 
+  const nodeHash = await resolveRfedNode(args, store, aliases, rns);
+  // Proactively fetch the rfed node's identity: when --node is given (or
+  // --discover derived it), the destination's announce may not yet be in
+  // the recall store. Send a path? request and wait for the announce rather
+  // than failing with "wait for its announce" (work doc #6).
+  await ensureNodeIdentity(rns, nodeHash, {
+    onRequest: () => err("  requesting rfed node identity…"),
+  });
+  const topic = await resolveTopic(args, store);
   const state = await store.loadState(config);
   const resolver = new RnsIdentityResolver(keyring);
   const rx = new DeltaReceiver(state, resolver);
@@ -333,6 +347,107 @@ async function cmdApply(args) {
   return 1;
 }
 
+/**
+ * Read a payload file (or stdin) and auto-detect hex (mirrors Python's
+ * `_read_payload_input`): an all-hex, even-length ASCII blob decodes to bytes.
+ * `--binary` forces raw bytes.
+ * @param {string} path
+ * @param {boolean} forceBinary
+ * @returns {Promise<Uint8Array>}
+ */
+async function readPayloadInput(path, forceBinary) {
+  const data = path === "-" ? new Uint8Array(await readStdin()) : await readFile(path);
+  return coercePayload(data, forceBinary);
+}
+
+/**
+ * Auto-detect a hex payload: if *all* bytes are ASCII hex characters (after
+ * trimming surrounding whitespace) and the length is even, decode to bytes;
+ * otherwise return the raw bytes unchanged.
+ * @param {Uint8Array | Buffer} data
+ * @param {boolean} forceBinary
+ * @returns {Uint8Array}
+ */
+function coercePayload(data, forceBinary) {
+  const bytes = new Uint8Array(data);
+  if (forceBinary || !bytes.length) return bytes;
+  let s;
+  try {
+    s = Buffer.from(bytes).toString("ascii");
+  } catch {
+    return bytes; // not ASCII -> raw bytes
+  }
+  const trimmed = s.trim();
+  if (!trimmed || trimmed.length % 2 !== 0) return bytes;
+  if (!/^[0-9a-fA-F]+$/.test(trimmed)) return bytes;
+  return hexToBytes(trimmed);
+}
+
+export { coercePayload };
+
+/**
+ * `dacar publish` — push signed delta(s) to the rfed channel (§11.1, doc #8).
+ *
+ * Two modes:
+ *   - `dacar publish <file> [<file>...]` — publish previously-signed delta
+ *     payload(s) (exact bytes, no re-sign; multiple files → one batch).
+ *   - `dacar publish --all` — pack + publish the outbox of locally-issued
+ *     deltas, then clear it. A no-op (exit 0) on an empty outbox.
+ *
+ * Reuses the `grant --publish` machinery (`publishDelta`: boot RNS, announce,
+ * subscribe, publish).
+ */
+async function cmdPublish(args) {
+  const store = await openStore(args);
+  const identity = await store.loadIdentity();
+  if (!identity) throw new CliError("no signing identity (run `dacar init`)");
+
+  const useAll = !!args.all;
+  const files = args._positionals ?? [];
+
+  if (useAll && files.length) {
+    throw new CliError("publish: use either <file>... or --all, not both");
+  }
+  if (!useAll && !files.length) {
+    throw new CliError("publish: provide <file>... (one or more) or --all");
+  }
+
+  /** @type {Uint8Array[]} */
+  let toPublish;
+  if (useAll) {
+    toPublish = await store.loadOutbox();
+    if (!toPublish.length) {
+      err("outbox empty (nothing to publish)");
+      return 0;
+    }
+  } else {
+    toPublish = [];
+    for (const path of files) {
+      const data = await readPayloadInput(path, !!args.binary);
+      if (!data.length) throw new CliError(`empty payload: ${path}`);
+      toPublish.push(data);
+    }
+  }
+
+  // Pack: a single delta as raw bytes, multiple as a batch payload.
+  const batch = toPublish.length === 1
+    ? toPublish[0]
+    : DeltaReceiver.packPayloads(toPublish);
+
+  const label = useAll ? "outbox" : `${toPublish.length} file(s)`;
+  const kind = toPublish.length > 1 ? "a batch" : "a single delta";
+  err(`  publishing ${toPublish.length} delta(s) (${label}) as ${kind}`);
+
+  // Reuse the grant --publish machinery (boot RNS, announce, subscribe, publish).
+  await publishDelta(args, store, identity, batch);
+
+  if (useAll) {
+    await store.saveOutbox([]);
+    err("  outbox cleared");
+  }
+  return 0;
+}
+
 async function readStdin() {
   const chunks = [];
   for await (const chunk of process.stdin) chunks.push(chunk);
@@ -358,7 +473,9 @@ async function cmdIdentityRemember(args) {
   } else {
     // Boot RNS and try to recall.
     const configDir = await resolveRnsConfigDir(args);
-    const rns = await bootRns(configDir, args.interface || "shared");
+    const rns = await bootRns(configDir, args.interface || "shared", {
+      verbose: !!args.verbose,
+    });
     const { Destination } = await import("@reticulum/core");
     const recalled = await Destination.recall(issuerHash, true);
     if (!recalled) {
@@ -442,7 +559,7 @@ async function cmdGrants(args) {
   err(`${label} (${rows.length})`);
   for (const { entry, active } of rows) {
     const t = entry.tuple;
-    const row = ledger.get(toHex(t.key));
+    const row = ledger.get(t.key);
     const rel = row?.relation || `[${shortHash(t.relationHash, args.fullHashes)}]`;
     const obj = row?.object || "[hash]";
     err(
@@ -466,19 +583,25 @@ const SUBCOMMANDS = {
   },
   grant: {
     run: cmdGrant,
-    opts: { publish: "boolean", node: "string", topic: "string", "rns-dir": "string", interface: "string" },
+    opts: { publish: "boolean", node: "string", discover: "boolean", topic: "string", "rns-dir": "string", interface: "string" },
     positional: ["grantee", "relation", "object"],
     online: true,
   },
   revoke: {
     run: cmdRevoke,
-    opts: { publish: "boolean", node: "string", topic: "string", "rns-dir": "string", interface: "string" },
+    opts: { publish: "boolean", node: "string", discover: "boolean", topic: "string", "rns-dir": "string", interface: "string" },
     positional: ["grantee", "relation", "object"],
     online: true,
   },
   sync: {
     run: cmdSync,
-    opts: { node: "string", topic: "string", "rns-dir": "string", interface: "string" },
+    opts: { node: "string", discover: "boolean", topic: "string", "rns-dir": "string", interface: "string" },
+    online: true,
+  },
+  publish: {
+    run: cmdPublish,
+    opts: { all: "boolean", binary: "boolean", node: "string", discover: "boolean", topic: "string", "rns-dir": "string", interface: "string" },
+    // variable file list (0..N) accessed via args._positionals
     online: true,
   },
   apply: { run: cmdApply, opts: { binary: "boolean" }, positional: ["payload"], online: false },
@@ -503,17 +626,22 @@ function buildOptions(spec) {
   for (const [k, t] of Object.entries(spec.opts || {})) {
     opts[k] = { type: t };
   }
-  if (spec.positional && spec.positional.length) {
-    opts.store = { type: "string" };
-    opts.identity = { type: "string" };
-    opts["full-hashes"] = { type: "boolean" };
-  }
+  // --verbose / -v is global: accepted by every (sub)command so it never
+  // errors out, and threaded into bootRns to raise the Reticulum log
+  // threshold + log interface/announce diagnostics.
+  opts.verbose = { type: "boolean", short: "v" };
+  // --store / --identity / --full-hashes are global on every (sub)command
+  // (they were previously gated on `positional`, which silently dropped them
+  // for commands with no positionals — e.g. `sync`, `config show`, `grants`).
+  opts.store = { type: "string" };
+  opts.identity = { type: "string" };
+  opts["full-hashes"] = { type: "boolean" };
   return opts;
 }
 
 async function main() {
   if (process.argv.includes("--help") || process.argv.includes("-h")) {
-    err(`usage: dacar <command> [options]\n\ncommands: ${Object.keys(SUBCOMMANDS).join(", ")}\n\nGlobal options: --store <path>, --identity <hex|path>, --full-hashes`);
+    err(`usage: dacar <command> [options]\n\ncommands: ${Object.keys(SUBCOMMANDS).join(", ")}\n\nGlobal options: --store <path>, --identity <hex|path>, --full-hashes, -v/--verbose`);
     return 0;
   }
   const argv = process.argv.slice(2);
@@ -559,7 +687,25 @@ async function main() {
   }
 }
 
-main().then((code) => process.exit(code ?? 0)).catch((e) => {
-  err("fatal: " + (e?.stack || e));
-  process.exit(1);
-});
+// Only auto-run when invoked as the entry script (Node/Bun via `pathToFileURL`,
+// Deno via `import.meta.main`), so the module can be imported in tests without
+// triggering the CLI dispatch (mirrors how `./cli/store` + `./cli/session`
+// are unit-tested).
+const isMain = (() => {
+  try {
+    if (import.meta.main === true) return true; // Deno
+  } catch { /* not Deno */ }
+  try {
+    if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+      return true; // Node / Bun
+    }
+  } catch { /* pathToFileURL unavailable */ }
+  return false;
+})();
+
+if (isMain) {
+  main().then((code) => process.exit(code ?? 0)).catch((e) => {
+    err("fatal: " + (e?.stack || e));
+    process.exit(1);
+  });
+}

package/src/cli/rns_boot.js

@@ -0,0 +1,131 @@
+/**
+ * Node-only RNS boot helpers (work doc #6).
+ *
+ * Constructs and **connects** a mesh interface, then attaches it to a booted
+ * `Reticulum` as the **default** interface — mirroring `@reticulum/node`'s
+ * `rfed` CLI `attachInterface`. This is non-optional: without `connect()` the
+ * interface's readable/writable streams are never set up and `_packetWriter`
+ * stays `null`, so `TransportCore.broadcast()` silently skips it
+ * (`if (!iface._packetWriter) continue`) and routed `sendPacket()` throws
+ * `No route to host`. No traffic flows in either direction — the
+ * `dacar sync --discover` "no rfed.node announce received within 30000ms"
+ * timeout symptom, even when an rfed node is announcing on the mesh.
+ *
+ * Node-only (imports `@reticulum/node` interfaces); kept out of the
+ * browser-portable `session.js`/`store.js` (see `test/cli-purity.test.js`).
+ * The Node-only CLI bin (`dacar.js`) composes this with the portable helpers.
+ */
+
+import { Reticulum, setLogLevel, toHex } from "@reticulum/core";
+import {
+  AutoInterface,
+  FileStorageAdapter,
+  LocalClientInterface,
+  TCPClientInterface,
+} from "@reticulum/node";
+
+/**
+ * Boot a `Reticulum` with a connected, default-attached mesh interface.
+ *
+ * `shared` (default) prefers a running rnsd via
+ * `LocalClientInterface.connectToSharedInstance()` (which internally
+ * connects); if no shared instance is reachable it falls back to
+ * `AutoInterface` so the node is still on the mesh — the same fallback the
+ * rfed CLI uses. `auto` and `tcp` connect their respective interfaces
+ * directly.
+ *
+ * @param {string} configDir Reticulum storage directory (identity/paths).
+ * @param {"shared"|"auto"|"tcp"} iface Interface kind to attach.
+ * @param {Object} [opts]
+ * @param {boolean} [opts.verbose=false] Raise the Reticulum log threshold to
+ *   `DEBUG` and log interface status + each validated announce the transport
+ *   sees (dest/name-hash/hops), so a failing `--discover` shows whether any
+ *   announces arrive at all and for which aspects.
+ * @param {() => Promise<import("@reticulum/node").LocalClientInterface | null>} [opts.sharedFactory]
+ *   Injectable shared-instance connector (tests).
+ * @param {() => import("@reticulum/node").AutoInterface} [opts.autoFactory]
+ *   Injectable AutoInterface factory (tests).
+ * @param {(host: string, port: number) => import("@reticulum/node").TCPClientInterface} [opts.tcpFactory]
+ *   Injectable TCPClientInterface factory (tests).
+ * @returns {Promise<import("@reticulum/core").Reticulum>} A booted Reticulum
+ *   with one connected default interface.
+ */
+export async function bootRns(configDir, iface, opts = {}) {
+  if (opts.verbose) setLogLevel("DEBUG");
+  const rns = new Reticulum({
+    storageAdapter: new FileStorageAdapter(configDir),
+  });
+  const label = await attachInterface(rns, iface, opts);
+  if (opts.verbose) {
+    const ifaces = [...rns.transport.interfaces];
+    const online = ifaces.filter((i) => i.online).length;
+    process.stderr.write(
+      `  rns: interface=${label} attached=${ifaces.length} online=${online}\n`,
+    );
+    // Surface every announce the transport validates, so a failed --discover
+    // shows whether *any* announces are arriving (and for which aspects).
+    rns.transport.addEventListener("announce", (event) => {
+      const d = event.detail ?? {};
+      const hops = d.packet?.hops ?? "?";
+      process.stderr.write(
+        `  announce: dest=${toHex(d.destinationHash ?? new Uint8Array())} ` +
+          `name=${toHex(d.nameHash ?? new Uint8Array())} hops=${hops}\n`,
+      );
+    });
+  }
+  return rns;
+}
+
+/**
+ * Construct, **connect**, and default-attach the requested interface kind.
+ *
+ * Connection is awaited before `addInterface(…, true)` so the interface's
+ * streams are live by the time the transport binds it (and so a connection
+ * failure surfaces immediately as a clear error rather than a 30s hang).
+ *
+ * @param {import("@reticulum/core").Reticulum} rns A booted Reticulum.
+ * @param {"shared"|"auto"|"tcp"} iface Interface kind.
+ * @param {Object} [opts] Factory overrides (see {@link bootRns}); `verbose`
+ *   only affects the shared→auto fallback notice.
+ * @returns {Promise<string>} A human-readable label for the attached interface.
+ */
+export async function attachInterface(rns, iface, opts = {}) {
+  const makeAuto =
+    opts.autoFactory ?? (() => new AutoInterface({ name: "auto" }));
+  const makeTcp =
+    opts.tcpFactory ??
+    ((host, port) => new TCPClientInterface({ host, port }));
+  const makeShared =
+    opts.sharedFactory ?? (() => LocalClientInterface.connectToSharedInstance());
+
+  if (iface === "auto") {
+    const auto = makeAuto();
+    await auto.connect();
+    rns.addInterface(auto, true);
+    return "AutoInterface";
+  }
+  if (iface === "tcp") {
+    const host = process.env.RNS_HOST || "127.0.0.1";
+    const port = parseInt(process.env.RNS_PORT || "42424", 10);
+    const tcp = makeTcp(host, port);
+    await tcp.connect();
+    rns.addInterface(tcp, true);
+    return `TCP ${host}:${port}`;
+  }
+  // shared (default): prefer a running rnsd; fall back to AutoInterface so the
+  // node is still on the mesh when no daemon is present (mirrors the rfed CLI).
+  const shared = await makeShared();
+  if (shared) {
+    rns.addInterface(shared, true);
+    return "shared rnsd instance";
+  }
+  if (opts.verbose) {
+    process.stderr.write(
+      "  rns: shared instance unavailable; falling back to AutoInterface\n",
+    );
+  }
+  const auto = makeAuto();
+  await auto.connect();
+  rns.addInterface(auto, true);
+  return "AutoInterface (shared instance unavailable)";
+}

package/src/cli/session.js

@@ -12,7 +12,7 @@
  * core. It mirrors Python's `dacar/cli/rns.py` + `run_publish`/`run_sync`.
  */
 
-import { Destination, Identity } from "@reticulum/core";
+import { Destination, DestType, Identity, toHex } from "@reticulum/core";
 import { APP_NAME } from "../naming.js";
 import { RfedDeltaSync } from "../transport/rfedSync.js";
 
@@ -28,12 +28,79 @@ import { RfedDeltaSync } from "../transport/rfedSync.js";
  * @param {import("@reticulum/core").Identity} identity
  * @returns {Promise<Uint8Array>}
  */
-export async function announceIdentity(identity) {
-  const dest = await Destination.IN(`${APP_NAME}.node`, "single", identity, null);
+export async function announceIdentity(identity, rns = null) {
+  // `Destination.IN` is a static factory (`Destination.IN(name, type, identity,
+  // interfaceLayer)`) — NOT a Direction enum value (unlike Python RNS's
+  // `RNS.Destination.IN` constant). The destination must be bound to `rns` as
+  // its interface layer, or `announce()` throws "Destination not bound to an
+  // RNS instance." Mirrors `@reticulum/core`'s rfed/client.js `listen()`.
+  const dest = await Destination.IN(
+    `${APP_NAME}.node`,
+    DestType.SINGLE,
+    identity,
+    rns,
+  );
   await dest.announce();
   return dest.destinationHash;
 }
 
+/**
+ * How long {@link ensureNodeIdentity} waits for a path-response announce
+ * after sending a `path?` request before giving up, in milliseconds.
+ */
+export const DEFAULT_NODE_DISCOVERY_TIMEOUT = 15_000;
+
+/**
+ * Recall a node's identity, proactively requesting its path if unknown.
+ *
+ * When `--node <hash>` (or `--discover`) resolves to an rfed destination whose
+ * announce isn't in the recall store yet, `RFedClient.subscribe` can't open a
+ * link and fails with `rfed node identity unknown for <hash>; wait for its
+ * announce`. Rather than fail immediately, this sends a `path?` request for
+ * the destination and polls `Destination.recall` until the node's
+ * path-response announce populates it (or `timeout` elapses), then returns
+ * the identity.
+ *
+ * The rfed node announces every `rfed.*` destination under one shared
+ * identity, so a path request for any of them is answered with an announce
+ * that makes that identity recallable by destination hash.
+ *
+ * `onRequest` (if given) is invoked once when the path request is sent, so the
+ * CLI can surface "requesting node identity…" progress to the user. Throws
+ * the same `rfed node identity unknown for …` error the client raises if
+ * still unknown after `timeout` — so callers that skip this helper see no
+ * behavior change.
+ * @param {import("@reticulum/core").Reticulum} rns A booted Reticulum.
+ * @param {Uint8Array} nodeHash An `rfed.*` destination hash of the node.
+ * @param {Object} [opts]
+ * @param {number} [opts.timeout=15000] Max wait in milliseconds.
+ * @param {number} [opts.pollInterval=250] Poll interval in milliseconds.
+ * @param {() => void} [opts.onRequest] Invoked once when the path request fires.
+ * @returns {Promise<import("@reticulum/core").Identity>}
+ */
+export async function ensureNodeIdentity(
+  rns,
+  nodeHash,
+  { timeout = DEFAULT_NODE_DISCOVERY_TIMEOUT, pollInterval = 250, onRequest } = {},
+) {
+  let identity = await Destination.recall(nodeHash);
+  if (identity) return identity;
+  // Not yet known — proactively request the destination's path (§7.1). The
+  // rfed node answers with a path-response announce (§7.2.4) that populates
+  // the recall store; poll until it arrives or the timeout elapses.
+  if (onRequest) onRequest();
+  await rns.transport.requestPath(nodeHash);
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    identity = await Destination.recall(nodeHash);
+    if (identity) return identity;
+    await new Promise((resolve) => setTimeout(resolve, pollInterval));
+  }
+  throw new Error(
+    `rfed node identity unknown for ${toHex(nodeHash)}; wait for its announce`,
+  );
+}
+
 /**
  * Publish a signed Delta to the rfed channel (§11.1, work doc #6).
  *
@@ -138,3 +205,73 @@ async function _dacarNodeHash(identity) {
   const destHashBuffer = await crypto.subtle.digest("SHA-256", combined);
   return new Uint8Array(destHashBuffer.slice(0, 16));
 }
+
+/**
+ * Autodiscover an rfed node from its `rfed.node` announce.
+ *
+ * Listens for a validated `rfed.node` announce on the live transport and
+ * resolves with that announce's `destinationHash` — the rfed node's canonical
+ * identifier (the same hash `--node <hash>` accepts and `RFedClient` recalls
+ * to open a link).
+ *
+ * The rfed daemon is an external process (dacar ships only the client); it
+ * announces `rfed.node` and the `rfed.channel.*` service destinations under
+ * one shared identity. A `dacar.node` announce is a *different* thing — it is
+ * a dacar peer advertising its own signing identity (the announce invariant,
+ * §11.2.4), not an rfed transport node. Discovery therefore filters for
+ * `rfed.node` announces (by `nameHash`), not `dacar.node`, and returns the
+ * announced destination hash directly (no derivation — the announce *is* the
+ * node hash).
+ *
+ * @param {Object} opts
+ * @param {import("@reticulum/core").Reticulum} opts.rns A booted Reticulum.
+ * @param {number} [opts.timeout=30000] Timeout in milliseconds.
+ * @returns {Promise<Uint8Array>} The `rfed.node` destination hash of the
+ *   discovered node.
+ * @throws {CliError} If no `rfed.node` announce is received within the timeout.
+ */
+export async function discoverRfedNode({ rns, timeout = 30000 }) {
+  if (!rns?.transport?.addEventListener) {
+    throw new CliError("RNS transport not available for discovery");
+  }
+  const encoder = new TextEncoder();
+  // nameHash = SHA-256("rfed.node")[:10] — matches `@reticulum/core`'s
+  // Destination._computeHashes. The announce event carries this as
+  // `detail.nameHash`; filtering on it selects only `rfed.node` announces
+  // (the rfed.channel.* services share the identity but have different names).
+  const expectedNameHash = new Uint8Array(
+    (await crypto.subtle.digest("SHA-256", encoder.encode("rfed.node"))).slice(0, 10),
+  );
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+
+    const onAnnounce = (event) => {
+      const detail = event.detail;
+      if (!detail?.nameHash) return;
+      // Only resolve on rfed.node announces.
+      if (toHex(detail.nameHash) !== toHex(expectedNameHash)) return;
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      rns.transport.removeEventListener("announce", onAnnounce);
+      // The announce's destinationHash *is* the rfed node's canonical hash.
+      resolve(detail.destinationHash);
+    };
+
+    rns.transport.addEventListener("announce", onAnnounce);
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      rns.transport.removeEventListener("announce", onAnnounce);
+      reject(
+        new CliError(
+          `no rfed.node announce received within ${timeout}ms ` +
+            "(ensure an rfed node is reachable and announcing)",
+        ),
+      );
+    }, timeout);
+  });
+}
+
+class CliError extends Error {}

package/src/cli/store.js

@@ -16,6 +16,9 @@
  *   - `aliases`     — msgpack `[{ hash, names[], note? }]`
  *   - `ledger`      — msgpack `{ tupleHashHex: { object?, relation?, wildcard?, firstSeen } }`
  *   - `identities`  — msgpack `{ hashHex: pubKeyBytes }` (durable issuer cache, doc #5)
+ *   - `outbox`      — msgpack `[payloadBytes, ...]` of locally-issued,
+ *                    not-yet-published signed Deltas (doc #8); flushed + cleared
+ *                    by `dacar publish --all`
  *
  * Secret material (the node's own identity private key) uses the adapter's
  * dedicated `loadKey`/`saveKey` slot, matching `@reticulum/core`.
@@ -221,7 +224,15 @@ export class DacarStore {
     const horizon = config?.deletionHorizonDays ?? (await this.loadConfig()).horizonDays;
     const bytes = await this._adapter.get(NS, "state");
     if (bytes && bytes.length) {
-      return StateVector.fromPayload(bytes, { deletionHorizonDays: horizon });
+      // `trusted: true` — these are this node's own persisted CRDT snapshot
+      // (written by `saveState()` → `toPayload()`), never network bytes.
+      // Network Operations arrive as signed Deltas through `DeltaReceiver`
+      // (the verify-on-ingest path), not here. Asserting `trusted` silences
+      // the audible `fromPayload` footgun warning during normal CLI use.
+      return StateVector.fromPayload(bytes, {
+        deletionHorizonDays: horizon,
+        trusted: true,
+      });
     }
     return new StateVector({ deletionHorizonDays: horizon });
   }
@@ -317,6 +328,39 @@ export class DacarStore {
     if (own) keyring.registerSingle(own.identityHash, await own.getPublicKey());
     return keyring;
   }
+
+  // -- outbox (work doc #8) -----------------------------------------------
+
+  /**
+   * Load the outbox of locally-issued, not-yet-published signed Delta
+   * payloads, in the order they were issued. Returns an empty array when no
+   * outbox record exists yet.
+   * @returns {Promise<Uint8Array[]>}
+   */
+  async loadOutbox() {
+    const bytes = await this._adapter.get(NS, "outbox");
+    if (!bytes) return [];
+    let obj;
+    try {
+      obj = MsgPack.decode(bytes);
+    } catch {
+      return []; // corrupted -> treat as empty (do not crash the CLI)
+    }
+    if (!Array.isArray(obj)) return [];
+    return obj.filter((p) => p instanceof Uint8Array).map((p) => new Uint8Array(p));
+  }
+
+  /**
+   * Persist the outbox as a MessagePack array of signed Delta payloads.
+   * @param {Uint8Array[]} payloads
+   */
+  async saveOutbox(payloads) {
+    await this._adapter.set(
+      NS,
+      "outbox",
+      MsgPack.encode(payloads.map((p) => new Uint8Array(p))),
+    );
+  }
 }
 
 /**

package/src/crdt.js

@@ -256,14 +256,20 @@ export class StateVector {
    * > `DeltaReceiver.applyPayloads()` (a batch of signed §5.3 Operations)
    * > instead.
    * >
-   * > A one-time `console.warn` is emitted to make this contract audible.
+   * > A one-time `console.warn` is emitted to make this contract audible —
+   * > unless `opts.trusted` is set, which a caller that has already asserted
+   * > it is loading its own persisted snapshot (e.g. `DacarStore.loadState`)
+   * > passes to keep normal CLI output free of developer-footgun noise.
    * @param {Uint8Array} data
    * @param {Object} [opts]
    * @param {number} [opts.deletionHorizonDays]
+   * @param {boolean} [opts.trusted=false] Suppress the audible warning when the
+   *   caller has asserted the bytes are a trusted-local snapshot (its own
+   *   store). The JSDoc contract above still applies regardless.
    * @returns {StateVector}
    */
-  static fromPayload(data, { deletionHorizonDays = DEFAULT_DELETION_HORIZON_DAYS } = {}) {
-    if (!__trustedLocalWarned) {
+  static fromPayload(data, { deletionHorizonDays = DEFAULT_DELETION_HORIZON_DAYS, trusted = false } = {}) {
+    if (!trusted && !__trustedLocalWarned) {
       __trustedLocalWarned = true;
       console.warn(
         "StateVector.fromPayload() is trusted-local-only: it performs no " +