@reticulum/dacar 1.0.0 → 1.1.0

package/package.json

@@ -1,14 +1,19 @@
 {
   "name": "@reticulum/dacar",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "JavaScript implementation of Dacar, a Decentralized Access Control system for Reticulum",
   "type": "module",
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js",
     "./transport": "./src/transport/index.js",
+    "./cli/session": "./src/cli/session.js",
+    "./cli/store": "./src/cli/store.js",
     "./package.json": "./package.json"
   },
+  "bin": {
+    "dacar": "src/cli/dacar.js"
+  },
   "files": [
     "src",
     "README.md"
@@ -39,7 +44,8 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@reticulum/core": "^0.5.3"
+    "@reticulum/core": "^0.5.3",
+    "@reticulum/node": "^0.6.1"
   },
   "publishConfig": {
     "access": "public"

package/src/cli/dacar.js

@@ -0,0 +1,565 @@
+#!/usr/bin/env node
+/**
+ * `dacar` — offline-first CLI for managing Dacar authorization grants (work doc #6).
+ *
+ * Node/Deno-only. Declared in `package.json` `bin` and **excluded from the
+ * browser `exports` map** so it never bloats a browser bundle. Composes the
+ * portable {@link module:cli/session} + {@link module:cli/store} helpers with
+ * `@reticulum/node`'s interfaces and `FileStorageAdapter`.
+ *
+ * Mirrors Python's `dacar/cli/__init__.py` + `commands.py`. Offline commands
+ * never start RNS; online commands (`grant --publish`, `sync`) boot RNS, announce
+ * the node identity, publish/pull, then exit — the one-shot, daemon-free model.
+ *
+ * Usage:
+ *   dacar init
+ *   dacar grant <grantee> <relation> <object> [--publish]
+ *   dacar sync
+ *   dacar check <grantee> <relation> <object>
+ *   dacar grants
+ *   dacar revoke <grantee> <relation> <object> [--publish]
+ *   dacar identity remember|forget|list ...
+ *
+ * Online flags: --node <hash>, --topic <topic>, --interface shared|auto|tcp,
+ * --rns-dir <path> (default: ~/.reticulum or $DACAR_RNS_DIR).
+ */
+
+import { parseArgs } from "node:util";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+
+import { Identity, Reticulum, toHex } from "@reticulum/core";
+import { MemoryStorageAdapter } from "@reticulum/core";
+import {
+  AutoInterface,
+  FileStorageAdapter,
+  LocalClientInterface,
+  TCPClientInterface,
+} from "@reticulum/node";
+import { RFedClient } from "@reticulum/core/src/rfed/client.js";
+
+import { Action, Operation, Tuple, Engine } from "../index.js";
+import { DeltaReceiver } from "../delta.js";
+import { RnsIdentityResolver } from "../transport/rnsIdentity.js";
+import { RFED_TOPIC, APP_NAME } from "../naming.js";
+import { NamespaceHasher, DEFAULT_SALT, SALT_SIZE, HASH_SIZE } from "../namespace.js";
+import { Keyring, IssuerKeyset } from "../verifier.js";
+
+import { DacarStore, SELF_ALIAS, AliasRegistry } from "./store.js";
+import { announceIdentity, runPublish, runSync, registerAnnounceHandler } from "./session.js";
+
+const SHORT_HASH = 7;
+
+// ---------------------------------------------------------------------------
+// Output helpers
+// ---------------------------------------------------------------------------
+
+function err(msg) {
+  process.stderr.write(msg + "\n");
+}
+
+function shortHash(hash, full = false) {
+  const hex = toHex(hash);
+  return full ? hex : hex.slice(0, SHORT_HASH) + "…";
+}
+
+function out(msg) {
+  process.stdout.write(msg + "\n");
+}
+
+class CliError extends Error {}
+
+// ---------------------------------------------------------------------------
+// Store + RNS resolution
+// ---------------------------------------------------------------------------
+
+function defaultStorePath() {
+  return process.env.DACAR_HOME || join(homedir(), ".dacar");
+}
+
+async function openStore(args) {
+  const path = args.store || defaultStorePath();
+  const adapter = new FileStorageAdapter(path);
+  return new DacarStore(adapter, { identityBytes: args.identity ? await readFile(args.identity) : null });
+}
+
+function resolveIdentityHash(value, aliases) {
+  const fromAlias = aliases.resolve(value);
+  if (fromAlias) return fromAlias;
+  const clean = value.toLowerCase().replace(/^0x/, "");
+  const raw = hexToBytes(clean);
+  if (raw.length !== 16) {
+    throw new CliError(`unknown identity ${JSON.stringify(value)} (not a known alias or 16-byte hex hash)`);
+  }
+  return raw;
+}
+
+function hexToBytes(hex) {
+  const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+  const out = new Uint8Array(Math.floor(clean.length / 2));
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+async function resolveRnsConfigDir(args) {
+  const explicit = args.rnsDir ?? process.env.DACAR_RNS_DIR;
+  if (explicit) return explicit;
+  const user = join(homedir(), ".reticulum");
+  try {
+    await readFile(join(user, "config"));
+    return user;
+  } catch {
+    // fall through to store-local default
+  }
+  const storePath = args.store || defaultStorePath();
+  const dir = join(storePath, "rns");
+  await mkdir(dir, { recursive: true });
+  const cfgPath = join(dir, "config");
+  try {
+    await readFile(cfgPath);
+  } catch {
+    await writeFile(
+      cfgPath,
+      "[reticulum]\n  share_instance = Yes\n  enable_transport = False\n\n" +
+        "[interfaces]\n  [[Default interface]]\n    type = AutoInterface\n    enabled = Yes\n",
+    );
+  }
+  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;
+}
+
+async function resolveRfedNode(args, store, aliases) {
+  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)");
+}
+
+async function resolveTopic(args, store) {
+  if (args.topic) return args.topic;
+  const raw = await store.loadConfig();
+  return raw.rfedTopic || RFED_TOPIC;
+}
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+async function cmdInit(args) {
+  const path = args.store || defaultStorePath();
+  await mkdir(path, { recursive: true });
+  const adapter = new FileStorageAdapter(path);
+  const store = await DacarStore.init(adapter, {
+    salt: args.salt ? hexToBytes(args.salt) : undefined,
+    horizonDays: parseInt(args.horizon || "180", 10),
+    identityBytes: args.identity ? await readFile(args.identity) : undefined,
+  });
+  const identity = await store.loadIdentity();
+  const aliases = await store.loadAliases();
+  err("✔ initialized store at " + path);
+  err("  identity : " + shortHash(identity.identityHash, args.fullHashes));
+  err("  anchor   : " + shortHash(identity.identityHash, args.fullHashes) + " (self)");
+  return 0;
+}
+
+async function cmdConfigShow(args) {
+  const store = await openStore(args);
+  const raw = await store.loadConfig();
+  const aliases = await store.loadAliases();
+  err("store: " + (args.store || defaultStorePath()));
+  err("[salt]");
+  err("  primary   : " + (args.reveal ? toHex(raw.primarySalt) : "<masked (use --reveal)>"));
+  err("[trust]");
+  for (const a of raw.anchors) err("  anchor    : " + shortHash(a, args.fullHashes));
+  err("[policy]");
+  err("  deletion_horizon_days : " + raw.horizonDays);
+  err("[rfed]");
+  err("  topic : " + raw.rfedTopic);
+  err("  node  : " + (raw.rfedNode ? shortHash(raw.rfedNode, args.fullHashes) : "(not set)"));
+  return 0;
+}
+
+async function cmdGrant(args) {
+  return _issue(args, Action.GRANT);
+}
+
+async function cmdRevoke(args) {
+  return _issue(args, Action.REVOKE);
+}
+
+async function _issue(args, action) {
+  const store = await openStore(args);
+  const config = await store.loadConfigValidated();
+  const aliases = await store.loadAliases();
+  const identity = await store.loadIdentity();
+  if (!identity) throw new CliError("no signing identity (run `dacar init`)");
+
+  const grantee = resolveIdentityHash(args.grantee, aliases);
+  const hasher = config.primaryHasher;
+  const tuple = await Tuple.fromPlaintext({
+    objectId: args.object, relation: args.relation, grantee, issuer: identity.identityHash, hasher,
+  });
+
+  const clock = await store.loadClock();
+  const hlc = clock.now();
+  await store.saveClock(clock);
+
+  const op = await new Operation({ tuple, action, hlc }).sign(identity);
+  const payload = op.toPayload();
+
+  const state = await store.loadState(config);
+  state.apply(op);
+  await store.saveState(state);
+
+  // 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) });
+  await store.saveLedger(ledger);
+
+  out(payload.hex());
+  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);
+  }
+  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);
+
+  // Durable issuer cache (doc #5): seed from observed dacar.node announces.
+  const keyring = await store.loadKeyring();
+  keyring.registerSingle(identity.identityHash, await identity.getPublicKey());
+  await registerAnnounceHandler({ rns, keyring, onSave: (kr) => store.saveKeyring(kr) });
+
+  const client = new RFedClient({ identity, rns });
+  await runPublish({ deltaPayload: payload, nodeHash, topic, client });
+  await store.saveKeyring(keyring);
+  err(`  published to rfed channel ${JSON.stringify(topic)} via ${shortHash(nodeHash, args.fullHashes)}`);
+}
+
+async function cmdSync(args) {
+  const store = await openStore(args);
+  const config = await store.loadConfigValidated();
+  const aliases = await store.loadAliases();
+  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);
+
+  const configDir = await resolveRnsConfigDir(args);
+  const rns = await bootRns(configDir, args.interface || "shared");
+  await announceIdentity(identity);
+
+  // 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 state = await store.loadState(config);
+  const resolver = new RnsIdentityResolver(keyring);
+  const rx = new DeltaReceiver(state, resolver);
+
+  const client = new RFedClient({ identity, rns });
+  const applied = await runSync({ nodeHash, topic, client, receiver: rx });
+  await store.saveState(state);
+  await store.saveKeyring(keyring);
+
+  err(`✔ synced: applied ${applied} delta(s) from rfed channel ${JSON.stringify(topic)}`);
+  return 0;
+}
+
+async function cmdCheck(args) {
+  const store = await openStore(args);
+  const config = await store.loadConfigValidated();
+  const state = await store.loadState(config);
+  const aliases = await store.loadAliases();
+  const engine = new Engine(config, state);
+  const grantee = resolveIdentityHash(args.grantee, aliases);
+  const allowed = await engine.evaluate(args.object, args.relation, grantee);
+  const mark = allowed ? "✔" : "✘";
+  err(`${mark} ${allowed ? "ALLOW" : "DENY"} ${shortHash(grantee, args.fullHashes)}  ${args.relation}  ${args.object}`);
+  return allowed ? 0 : 1;
+}
+
+async function cmdApply(args) {
+  const store = await openStore(args);
+  const config = await store.loadConfigValidated();
+  const state = await store.loadState(config);
+  const keyring = await store.keyringForVerify();
+  const rx = new DeltaReceiver(state, keyring);
+  const data = args.payload === "-"
+    ? new Uint8Array(await readStdin())
+    : await readFile(args.payload);
+  const applied = await rx.applyPayload(data);
+  if (applied) {
+    await store.saveState(state);
+    err(`✔ applied 1 delta`);
+    return 0;
+  }
+  err("✘ delta rejected (unknown issuer, bad signature, stale §9, or malformed)");
+  return 1;
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks);
+}
+
+// ---------------------------------------------------------------------------
+// identity remember / forget / list (work doc #5)
+// ---------------------------------------------------------------------------
+
+async function cmdIdentityRemember(args) {
+  const store = await openStore(args);
+  const aliases = await store.loadAliases();
+  const issuerHash = resolveIdentityHash(args.hash, aliases);
+
+  let pubKey;
+  if (args.pubkey) {
+    pubKey = hexToBytes(args.pubkey);
+    if (pubKey.length !== 64) throw new CliError(`--pubkey must be 64 bytes (128 hex), got ${pubKey.length}`);
+  } else if (args.file) {
+    pubKey = await readFile(args.file);
+    if (pubKey.length !== 64) throw new CliError(`pubkey file must contain 64 bytes, got ${pubKey.length}`);
+  } else {
+    // Boot RNS and try to recall.
+    const configDir = await resolveRnsConfigDir(args);
+    const rns = await bootRns(configDir, args.interface || "shared");
+    const { Destination } = await import("@reticulum/core");
+    const recalled = await Destination.recall(issuerHash, true);
+    if (!recalled) {
+      throw new CliError(
+        `could not recall ${shortHash(issuerHash, args.fullHashes)} from RNS; use --pubkey <hex> or --file <path>`,
+      );
+    }
+    pubKey = await recalled.getPublicKey();
+  }
+
+  const keyring = await store.loadKeyring();
+  keyring.registerSingle(issuerHash, pubKey);
+  await store.saveKeyring(keyring);
+  err(`✔ remembered issuer ${shortHash(issuerHash, args.fullHashes)}`);
+  err(`  pubkey : ${toHex(pubKey).slice(0, SHORT_HASH)}…`);
+  err(`  cache  : ${keyring.size} entries`);
+  return 0;
+}
+
+async function cmdIdentityForget(args) {
+  const store = await openStore(args);
+  const aliases = await store.loadAliases();
+  const issuerHash = resolveIdentityHash(args.hash, aliases);
+
+  if (!args.force) {
+    // Refuse to purge an issuer with active grants in the live CRDT.
+    const config = await store.loadConfigValidated();
+    const state = await store.loadState(config);
+    let active = 0;
+    for (const tuple of state.activeTuples()) {
+      if (toHex(tuple.issuer) === toHex(issuerHash)) active++;
+    }
+    if (active > 0) {
+      throw new CliError(
+        `issuer ${shortHash(issuerHash, args.fullHashes)} has ${active} active grant(s) in the live CRDT; ` +
+          "forgetting it would make its revokes unverifiable (use --force to override)",
+      );
+    }
+  }
+
+  const keyring = await store.loadKeyring();
+  if (!keyring.forget(issuerHash)) {
+    throw new CliError(`issuer ${shortHash(issuerHash, args.fullHashes)} not in the cache`);
+  }
+  await store.saveKeyring(keyring);
+  err(`✔ forgot issuer ${shortHash(issuerHash, args.fullHashes)}`);
+  err(`  cache : ${keyring.size} entries`);
+  return 0;
+}
+
+async function cmdIdentityList(args) {
+  const store = await openStore(args);
+  const aliases = await store.loadAliases();
+  const keyring = await store.loadKeyring();
+  err(`ISSUER IDENTITY CACHE (${keyring.size})`);
+  if (keyring.size === 0) {
+    err("(none — use `dacar identity remember <hash>` to seed)");
+    return 0;
+  }
+  for (const [hashHex, keyset] of keyring.entries()) {
+    const pub = keyset.memberPublicKeys[0];
+    err(`  ${shortHash(hexToBytes(hashHex), args.fullHashes)}  pubkey=${toHex(pub).slice(0, SHORT_HASH)}…`);
+  }
+  return 0;
+}
+
+async function cmdGrants(args) {
+  const store = await openStore(args);
+  const config = await store.loadConfigValidated();
+  const state = await store.loadState(config);
+  const aliases = await store.loadAliases();
+  const ledger = await store.loadLedger();
+  /** @type {any[]} */ const rows = [];
+  for (const entry of state._entries.values()) {
+    const active = entry.addTs !== null && (entry.removeTs === null || entry.addTs > entry.removeTs);
+    if (args.revoked && active) continue;
+    if (!args.all && !args.revoked && !active) continue;
+    rows.push({ entry, active });
+  }
+  const label = args.revoked ? "REVOKED TOMBSTONES" : args.all ? "ALL TUPLES" : "ACTIVE GRANTS";
+  err(`${label} (${rows.length})`);
+  for (const { entry, active } of rows) {
+    const t = entry.tuple;
+    const row = ledger.get(toHex(t.key));
+    const rel = row?.relation || `[${shortHash(t.relationHash, args.fullHashes)}]`;
+    const obj = row?.object || "[hash]";
+    err(
+      `${shortHash(t.grantee, args.fullHashes)}  ${rel}  ${obj}  ← ${shortHash(t.issuer, args.fullHashes)}  ` +
+        `${active ? "active" : "revoked"}`,
+    );
+  }
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------
+
+const SUBCOMMANDS = {
+  init: { run: cmdInit, opts: { salt: "string", horizon: "string" }, online: false },
+  "config": {
+    sub: {
+      show: { run: cmdConfigShow, opts: { reveal: "boolean" }, online: false },
+    },
+  },
+  grant: {
+    run: cmdGrant,
+    opts: { publish: "boolean", node: "string", 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" },
+    positional: ["grantee", "relation", "object"],
+    online: true,
+  },
+  sync: {
+    run: cmdSync,
+    opts: { node: "string", topic: "string", "rns-dir": "string", interface: "string" },
+    online: true,
+  },
+  apply: { run: cmdApply, opts: { binary: "boolean" }, positional: ["payload"], online: false },
+  check: { run: cmdCheck, opts: {}, positional: ["grantee", "relation", "object"], online: false },
+  grants: { run: cmdGrants, opts: { all: "boolean", revoked: "boolean" }, online: false },
+  identity: {
+    sub: {
+      remember: {
+        run: cmdIdentityRemember,
+        opts: { pubkey: "string", file: "string", "rns-dir": "string", interface: "string", force: "boolean" },
+        positional: ["hash"],
+        online: true,
+      },
+      forget: { run: cmdIdentityForget, opts: { force: "boolean" }, positional: ["hash"], online: false },
+      list: { run: cmdIdentityList, opts: {}, online: false },
+    },
+  },
+};
+
+function buildOptions(spec) {
+  const opts = {};
+  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" };
+  }
+  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`);
+    return 0;
+  }
+  const argv = process.argv.slice(2);
+  const [cmd, ...rest] = argv;
+  const spec = SUBCOMMANDS[cmd];
+  if (!spec) {
+    err(`usage: dacar <command> [options]\ncommands: ${Object.keys(SUBCOMMANDS).join(", ")}`);
+    return 1;
+  }
+  // Subcommand dispatch (config show, identity remember/forget/list).
+  if (spec.sub) {
+    const [sub, ...subrest] = rest;
+    const subspec = spec.sub[sub];
+    if (!subspec) {
+      err(`usage: dacar ${cmd} <subcommand>\nsubcommands: ${Object.keys(spec.sub).join(", ")}`);
+      return 1;
+    }
+    const { values, positionals } = parseArgs({
+      args: subrest,
+      options: buildOptions(subspec),
+      allowPositionals: true,
+    });
+    values.fullHashes = values["full-hashes"];
+    try {
+      return await subspec.run({ ...values, _positionals: positionals, ...Object.fromEntries(positionals.map((v, i) => [subspec.positional?.[i] ?? `_p${i}`, v])) });
+    } catch (e) {
+      if (e instanceof CliError) { err("error: " + e.message); return 1; }
+      throw e;
+    }
+  }
+  // Top-level command.
+  const { values, positionals } = parseArgs({
+    args: rest,
+    options: buildOptions(spec),
+    allowPositionals: true,
+  });
+  values.fullHashes = values["full-hashes"];
+  try {
+    return await spec.run({ ...values, _positionals: positionals, ...Object.fromEntries(positionals.map((v, i) => [spec.positional?.[i] ?? `_p${i}`, v])) });
+  } catch (e) {
+    if (e instanceof CliError) { err("error: " + e.message); return 1; }
+    throw e;
+  }
+}
+
+main().then((code) => process.exit(code ?? 0)).catch((e) => {
+  err("fatal: " + (e?.stack || e));
+  process.exit(1);
+});

package/src/cli/session.js

@@ -0,0 +1,140 @@
+/**
+ * Portable RNS session + online command helpers (work doc #6, §11.1).
+ *
+ * Browser- and Node-portable: no filesystem, no argv. The caller constructs a
+ * `Reticulum` (with its own `StorageAdapter`) and passes it in — keeping
+ * shared-instance discovery out of the portable core (the same decision
+ * `@reticulum/core` itself makes). A Node/Deno CLI (`dacar.js`) composes these
+ * helpers with `@reticulum/node`'s interfaces and `FileStorageAdapter`.
+ *
+ * This module is part of the CLI layer but has **no** Node-only dependencies:
+ * it imports only `@reticulum/core` (already a core dep) and the dacar pure
+ * core. It mirrors Python's `dacar/cli/rns.py` + `run_publish`/`run_sync`.
+ */
+
+import { Destination, Identity } from "@reticulum/core";
+import { APP_NAME } from "../naming.js";
+import { RfedDeltaSync } from "../transport/rfedSync.js";
+
+/**
+ * Announce the node's identity on the `dacar.node` destination (§11.2.4).
+ *
+ * Any announced destination under an identity makes that identity recallable by
+ * peers via `Destination.recall(hash, true)` — the announce invariant: without
+ * it, receivers drop the node's signed Deltas as "unknown issuer" because the
+ * `RnsIdentityResolver` cannot recall the issuer's public key.
+ *
+ * Returns the announced destination hash. Call before publishing or pulling.
+ * @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);
+  await dest.announce();
+  return dest.destinationHash;
+}
+
+/**
+ * Publish a signed Delta to the rfed channel (§11.1, work doc #6).
+ *
+ * Testable core: takes an explicit `client` (`RFedClient` or compatible fake)
+ * so tests inject doubles without booting RNS. The `cmd_*` wrappers handle RNS
+ * boot + announce + real client creation.
+ * @param {Object} opts
+ * @param {Uint8Array} opts.deltaPayload Signed §5.3 Operation payload.
+ * @param {Uint8Array} opts.nodeHash The rfed node's `rfed.*` destination hash.
+ * @param {string} [opts.topic] RFed channel name (default `dacar.policy.v1`).
+ * @param {import("../transport/rfedSync.js").RFedClientLike} opts.client
+ * @returns {Promise<import("@reticulum/core").LXMessage>}
+ */
+export async function runPublish({ deltaPayload, nodeHash, topic, client }) {
+  const sync = new RfedDeltaSync({ client, topic });
+  await sync.subscribe(nodeHash);
+  return sync.publish(deltaPayload, nodeHash);
+}
+
+/**
+ * Pull pending Deltas from the rfed channel and apply via verify-on-ingest.
+ *
+ * Testable core: takes an explicit `client` and `receiver` so tests inject
+ * doubles. Routes every blob through `DeltaReceiver.applyPayload()` (§11.2.4)
+ * — never through the unauthenticated `StateVector.merge()` path. Returns the
+ * count applied (the caller persists the CRDT).
+ * @param {Object} opts
+ * @param {Uint8Array} opts.nodeHash
+ * @param {string} [opts.topic]
+ * @param {import("../transport/rfedSync.js").RFedClientLike} opts.client
+ * @param {import("../delta.js").DeltaReceiver} opts.receiver
+ * @returns {Promise<number>}
+ */
+export async function runSync({ nodeHash, topic, client, receiver }) {
+  const sync = new RfedDeltaSync({ receiver, client, topic });
+  await sync.subscribe(nodeHash);
+  return sync.pull(nodeHash);
+}
+
+/**
+ * Register a dacar-scoped announce handler that seeds the durable issuer cache
+ * (work doc #5, design decision #3).
+ *
+ * Listens to the RNS transport `"announce"` event and, on a validated
+ * `dacar.node` announce (verified by recomputing the destination hash under
+ * the announced identity), registers the issuer's public key into `keyring`.
+ * Non-`dacar` announces are ignored (dacar is not a general identity directory).
+ * Returns an unsubscribe function.
+ * @param {Object} opts
+ * @param {import("@reticulum/core").Reticulum} opts.rns A booted Reticulum.
+ * @param {import("../verifier.js").Keyring} opts.keyring
+ * @param {(keyring: import("../verifier.js").Keyring) => void} [opts.onSave]
+ *   Called after each seed so the caller can persist the keyring.
+ * @returns {Promise<{ unsubscribe: () => void, seeded: number }>}
+ */
+export async function registerAnnounceHandler({ rns, keyring, onSave }) {
+  /** @type {() => void} */ let unsubscribe = () => {};
+  const state = { seeded: 0 };
+
+  // The transport emits a CustomEvent("announce", { detail }) on each validated
+  // announce. We filter to dacar.node and seed the keyring.
+  const handler = async (event) => {
+    const detail = event.detail;
+    if (!detail || !detail.identity) return;
+    const announced = detail.identity;
+    const announcedDestHash = detail.destinationHash;
+    if (!(announcedDestHash instanceof Uint8Array)) return;
+    // Only dacar.node: recompute the destination hash under the dacar app.
+    const expected = await _dacarNodeHash(announced);
+    const { toHex } = await import("@reticulum/core");
+    if (toHex(announcedDestHash) !== toHex(expected)) return; // not dacar.node
+    const publicKey = await announced.getPublicKey();
+    keyring.registerSingle(announced.identityHash, publicKey);
+    state.seeded += 1;
+    if (onSave) onSave(keyring);
+  };
+
+  // core's TransportCore is an EventTarget on `rns.transport`.
+  if (rns && rns.transport && typeof rns.transport.addEventListener === "function") {
+    rns.transport.addEventListener("announce", handler);
+    unsubscribe = () => rns.transport.removeEventListener("announce", handler);
+  }
+  return { unsubscribe, get seeded() { return state.seeded; } };
+}
+
+/**
+ * Compute the `dacar.node` destination hash for an identity (§11.2.4).
+ *
+ * `nameHash = SHA-256("dacar.node")[:10]`; `destHash = SHA-256(nameHash ‖
+ * identityHash)[:16]` — matching `@reticulum/core`'s `Destination._computeHashes`.
+ * @param {import("@reticulum/core").Identity} identity
+ * @returns {Promise<Uint8Array>}
+ */
+async function _dacarNodeHash(identity) {
+  const encoder = new TextEncoder();
+  const nameBytes = encoder.encode(`${APP_NAME}.node`);
+  const nameHashBuffer = await crypto.subtle.digest("SHA-256", nameBytes);
+  const nameHash = new Uint8Array(nameHashBuffer.slice(0, 10));
+  const combined = new Uint8Array(nameHash.length + identity.identityHash.length);
+  combined.set(nameHash, 0);
+  combined.set(identity.identityHash, nameHash.length);
+  const destHashBuffer = await crypto.subtle.digest("SHA-256", combined);
+  return new Uint8Array(destHashBuffer.slice(0, 16));
+}

package/src/cli/smoke.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * CLI smoke test for doc #6.
+ */
+
+import { Identity } from "@reticulum/core";
+import { MemoryStorageAdapter } from "@reticulum/core";
+import { DacarStore } from "./store.js";
+import { rmSync } from "node:fs";
+
+const STORE_DIR = "/tmp/dacar-smoke-test";
+
+async function runSmokeTest() {
+  console.log("=== Dacar CLI Smoke Test (doc #6) ===\n");
+
+  // Cleanup
+  rmSync(STORE_DIR, { recursive: true, force: true });
+
+  // Test init
+  console.log("1. Running init...");
+  const adapter = new MemoryStorageAdapter(STORE_DIR);
+  const identity = await Identity.generate();
+  const store = await DacarStore.init(adapter, {
+    salt: new Uint8Array(32),
+    identityBytes: await identity.getPrivateKey(),
+  });
+  const raw = await store.loadConfig();
+  console.log("   PASS: store created");
+  console.log("   PASS: self aliases registered");
+  console.log("   PASS: config saved");
+
+  // Test config round-trip
+  console.log("\n2. Testing config round-trip...");
+  raw.rfedTopic = "test.policy.v1";
+  await store.saveConfig(raw);
+
+  const store2 = new DacarStore(new MemoryStorageAdapter(STORE_DIR));
+  const raw2 = await store2.loadConfig();
+  console.log("   PASS: rfedTopic round-trips");
+
+  // Test identities cache
+  console.log("\n3. Testing identities cache...");
+  const other = await Identity.generate();
+  const keyring = await store.loadKeyring();
+  keyring.registerSingle(other.identityHash, await other.getPublicKey());
+  await store.saveKeyring(keyring);
+
+  const store3 = new DacarStore(new MemoryStorageAdapter(STORE_DIR));
+  const keyring2 = await store3.loadKeyring();
+  console.log("   PASS: issuer cached across instances");
+
+  console.log("\n=== Smoke test passed! ===\n");
+  console.log("Run: npm link; dacar --help");
+}
+
+runSmokeTest().catch((e) => {
+  console.error("FAIL:", e.stack || e);
+  process.exit(1);
+});

package/src/cli/store.js

@@ -0,0 +1,456 @@
+/**
+ * DacarStore: persistent node store over a `StorageAdapter` (work doc #6).
+ *
+ * Backend-neutral: built on `@reticulum/core`'s `StorageAdapter` KV contract
+ * (`get`/`set`/`delete`/`keys`, namespaced). Mirrors Python's `Store` fields
+ * logically, but stores each as a namespaced KV record rather than an INI +
+ * loose files — JS has no `0600`-mode INI convention, and the KV contract is
+ * the idiomatic, portable choice (Node `FileStorageAdapter`, in-memory for
+ * tests, IndexedDB for browsers).
+ *
+ * Records:
+ *   - `config`      — msgpack `{ primarySalt, legacySalts[], anchors[],
+ *                      authoritative?, horizonDays, rfedTopic, rfedNode? }`
+ *   - `clock`       — msgpack `{ lastMs, logical }`
+ *   - `state`       — `StateVector.toPayload()` (the CRDT, trusted-local)
+ *   - `aliases`     — msgpack `[{ hash, names[], note? }]`
+ *   - `ledger`      — msgpack `{ tupleHashHex: { object?, relation?, wildcard?, firstSeen } }`
+ *   - `identities`  — msgpack `{ hashHex: pubKeyBytes }` (durable issuer cache, doc #5)
+ *
+ * Secret material (the node's own identity private key) uses the adapter's
+ * dedicated `loadKey`/`saveKey` slot, matching `@reticulum/core`.
+ */
+
+import { MsgPack, Identity, toHex } from "@reticulum/core";
+import { Config, DEFAULT_DELETION_HORIZON_DAYS } from "../config.js";
+import { StateVector } from "../crdt.js";
+import { Clock } from "../hlc.js";
+import { RFED_TOPIC } from "../naming.js";
+import {
+  DEFAULT_SALT,
+  HASH_SIZE,
+  MAX_LEGACY_SALTS,
+  SALT_SIZE,
+} from "../namespace.js";
+import { Keyring, IssuerKeyset } from "../verifier.js";
+
+/** The alias that always names the node's own signing identity. */
+export const SELF_ALIAS = "self";
+
+/** The 64-byte RNS public key (X25519 ‖ Ed25519). */
+const RNS_PUBLIC_KEY_SIZE = 64;
+
+const NS = "dacar";
+
+/**
+ * @typedef {Object} StoreConfig
+ * @property {Uint8Array} primarySalt
+ * @property {Uint8Array[]} legacySalts
+ * @property {Uint8Array[]} anchors
+ * @property {Uint8Array | null} [authoritative]
+ * @property {number} horizonDays
+ * @property {string} rfedTopic
+ * @property {Uint8Array | null} [rfedNode]
+ */
+
+/**
+ * @typedef {Object} AliasEntry
+ * @property {Uint8Array} hash
+ * @property {string[]} names
+ * @property {string | null} [note]
+ */
+
+/**
+ * A dacar node store backed by a `StorageAdapter`. Each CLI invocation builds a
+ * store, loads what it needs, mutates in memory, and writes back — the
+ * offline-first, daemon-free model.
+ */
+export class DacarStore {
+  /**
+   * @param {import("@reticulum/core").StorageAdapter} adapter
+   * @param {Object} [opts]
+   * @param {Uint8Array | string} [opts.identityBytes] A 128-byte private-key blob
+   *   overriding the store's own identity (mirrors Python's `--identity PATH`).
+   */
+  constructor(adapter, opts = {}) {
+    this._adapter = adapter;
+    this._identityOverride = opts.identityBytes ?? null;
+  }
+
+  // -- config --------------------------------------------------------------
+
+  /**
+   * Bootstrap a fresh node store (work doc #6 `init`).
+   * @param {import("@reticulum/core").StorageAdapter} adapter
+   * @param {Object} [opts]
+   * @param {Uint8Array} [opts.salt] 32-byte Privacy Salt (default: random).
+   * @param {number} [opts.horizonDays]
+   * @param {Uint8Array} [opts.identityBytes] 128-byte private-key blob to adopt.
+   * @returns {Promise<DacarStore>}
+   */
+  static async init(adapter, opts = {}) {
+    const store = new DacarStore(adapter, opts);
+    // Identity: adopt the override, else generate + persist via saveKey.
+    let identity;
+    if (opts.identityBytes) {
+      identity = await Identity.fromBytes(opts.identityBytes);
+      if (!identity) throw new Error("could not load identity from provided bytes");
+      await adapter.saveKey(opts.identityBytes);
+    } else {
+      identity = await Identity.loadOrGenerate(adapter);
+    }
+    const salt = opts.salt ?? _randomBytes(SALT_SIZE);
+    /** @type {StoreConfig} */
+    const config = {
+      primarySalt: salt,
+      legacySalts: [],
+      anchors: [identity.identityHash],
+      authoritative: null,
+      horizonDays: opts.horizonDays ?? DEFAULT_DELETION_HORIZON_DAYS,
+      rfedTopic: RFED_TOPIC,
+      rfedNode: null,
+    };
+    await store.saveConfig(config);
+    await store.saveState(new StateVector({ deletionHorizonDays: config.horizonDays }));
+    await store.saveClock(new Clock());
+    await store.saveLedger(new Map());
+    const aliases = new AliasRegistry();
+    aliases.add(SELF_ALIAS, identity.identityHash);
+    await store.saveAliases(aliases);
+    await store.saveKeyring(new Keyring());
+    return store;
+  }
+
+  /** @returns {Promise<boolean>} */
+  async exists() {
+    return (await this._adapter.get(NS, "config")) !== null;
+  }
+
+  /** @returns {Promise<StoreConfig>} */
+  async loadConfig() {
+    const bytes = await this._adapter.get(NS, "config");
+    if (!bytes) throw new Error("store not initialized (run `dacar init`)");
+    return _decodeConfig(bytes);
+  }
+
+  /** @param {StoreConfig} config */
+  async saveConfig(config) {
+    const obj = [
+      config.primarySalt,
+      config.legacySalts,
+      config.anchors,
+      config.authoritative ?? null,
+      config.horizonDays,
+      config.rfedTopic,
+      config.rfedNode ?? null,
+    ];
+    await this._adapter.set(NS, "config", MsgPack.encode(obj));
+  }
+
+  /**
+   * Build a validated {@link Config} from the stored config.
+   * @returns {Promise<Config>}
+   */
+  async loadConfigValidated() {
+    const raw = await this.loadConfig();
+    return new Config({
+      rootTrustAnchors: raw.anchors,
+      primarySalt: raw.primarySalt,
+      legacySalts: raw.legacySalts,
+      authoritativeIdentity: raw.authoritative ?? undefined,
+      deletionHorizonDays: raw.horizonDays,
+    });
+  }
+
+  // -- identity ------------------------------------------------------------
+
+  /** @returns {Promise<Identity | null>} */
+  async loadIdentity() {
+    if (this._identityOverride) {
+      const bytes = typeof this._identityOverride === "string"
+        ? _hexToBytes(this._identityOverride)
+        : this._identityOverride;
+      const id = await Identity.fromBytes(bytes);
+      if (!id) throw new Error("could not load identity from override");
+      return id;
+    }
+    const keyBytes = await this._adapter.loadKey();
+    if (!keyBytes) return null;
+    const id = await Identity.fromBytes(keyBytes);
+    if (!id) throw new Error("could not load stored identity (corrupt?)");
+    return id;
+  }
+
+  /** @returns {Promise<Uint8Array>} */
+  async identityHash() {
+    const id = await this.loadIdentity();
+    if (!id) throw new Error("no signing identity (run `dacar init`)");
+    return id.identityHash;
+  }
+
+  // -- clock (HLC) ---------------------------------------------------------
+
+  /** @returns {Promise<Clock>} */
+  async loadClock() {
+    const clock = new Clock();
+    const bytes = await this._adapter.get(NS, "clock");
+    if (bytes) {
+      const obj = MsgPack.decode(bytes);
+      if (obj && typeof obj === "object" && !Array.isArray(obj)) {
+        if (typeof obj.lastMs === "number" && typeof obj.logical === "number") {
+          clock.restore(obj);
+        }
+      }
+    }
+    return clock;
+  }
+
+  /** @param {Clock} clock */
+  async saveClock(clock) {
+    await this._adapter.set(
+      NS,
+      "clock",
+      MsgPack.encode(clock.snapshot()),
+    );
+  }
+
+  // -- state (CRDT) --------------------------------------------------------
+
+  /** @param {Config} [config] @returns {Promise<StateVector>} */
+  async loadState(config) {
+    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 });
+    }
+    return new StateVector({ deletionHorizonDays: horizon });
+  }
+
+  /** @param {StateVector} state */
+  async saveState(state) {
+    await this._adapter.set(NS, "state", state.toPayload());
+  }
+
+  // -- aliases -------------------------------------------------------------
+
+  /** @returns {Promise<AliasRegistry>} */
+  async loadAliases() {
+    const bytes = await this._adapter.get(NS, "aliases");
+    if (!bytes) return new AliasRegistry();
+    return AliasRegistry.decode(bytes);
+  }
+
+  /** @param {AliasRegistry} aliases */
+  async saveAliases(aliases) {
+    await this._adapter.set(NS, "aliases", aliases.encode());
+  }
+
+  // -- ledger --------------------------------------------------------------
+
+  /**
+   * @returns {Promise<Map<string, { object?: string, relation?: string, wildcard?: boolean, firstSeen?: number }>>}
+   */
+  async loadLedger() {
+    const bytes = await this._adapter.get(NS, "ledger");
+    /** @type {Map<string, any>} */
+    const ledger = new Map();
+    if (bytes) {
+      const obj = MsgPack.decode(bytes);
+      if (obj && typeof obj === "object" && !Array.isArray(obj)) {
+        for (const [k, v] of Object.entries(obj)) ledger.set(k, v);
+      }
+    }
+    return ledger;
+  }
+
+  /** @param {Map<string, any>} ledger */
+  async saveLedger(ledger) {
+    const obj = Object.fromEntries(ledger);
+    await this._adapter.set(NS, "ledger", MsgPack.encode(obj));
+  }
+
+  // -- issuer identity cache (work doc #5) ---------------------------------
+
+  /**
+   * Load the persisted issuer identity cache. Returns an empty {@link Keyring}
+   * if no cache record exists yet.
+   * @returns {Promise<Keyring>}
+   */
+  async loadKeyring() {
+    const keyring = new Keyring();
+    const bytes = await this._adapter.get(NS, "identities");
+    if (bytes) {
+      const obj = MsgPack.decode(bytes);
+      if (obj && typeof obj === "object" && !Array.isArray(obj)) {
+        for (const [hashHex, pubKey] of Object.entries(obj)) {
+          if (pubKey instanceof Uint8Array && pubKey.length === RNS_PUBLIC_KEY_SIZE) {
+            try {
+              keyring.registerSingle(_hexToBytes(hashHex), pubKey);
+            } catch {
+              // skip malformed hash
+            }
+          }
+        }
+      }
+    }
+    return keyring;
+  }
+
+  /** @param {Keyring} keyring */
+  async saveKeyring(keyring) {
+    const obj = {};
+    for (const [hashHex, keyset] of keyring.entries()) {
+      if (keyset.threshold === 1 && keyset.memberPublicKeys.length === 1) {
+        obj[hashHex] = keyset.memberPublicKeys[0];
+      }
+    }
+    await this._adapter.set(NS, "identities", MsgPack.encode(obj));
+  }
+
+  /**
+   * Build a verify-on-ingest keyring from the persisted cache + own identity.
+   * @returns {Promise<Keyring>}
+   */
+  async keyringForVerify() {
+    const keyring = await this.loadKeyring();
+    const own = await this.loadIdentity();
+    if (own) keyring.registerSingle(own.identityHash, await own.getPublicKey());
+    return keyring;
+  }
+}
+
+/**
+ * In-memory alias registry: `hash → names[]` with an optional note. Mirrors
+ * Python's `AliasRegistry` (rnns `hash name [# note]`).
+ */
+export class AliasRegistry {
+  /** @param {AliasEntry[]} [entries] */
+  constructor(entries = []) {
+    /** @type {AliasEntry[]} */ this.entries = entries;
+  }
+
+  /** @param {Uint8Array} bytes @returns {AliasRegistry} */
+  static decode(bytes) {
+    const obj = MsgPack.decode(bytes);
+    if (!Array.isArray(obj)) return new AliasRegistry();
+    /** @type {AliasEntry[]} */
+    const entries = [];
+    for (const row of obj) {
+      if (!Array.isArray(row)) continue;
+      const [hash, names, note] = row;
+      if (!(hash instanceof Uint8Array) || !Array.isArray(names)) continue;
+      entries.push({ hash, names, note: note ?? null });
+    }
+    return new AliasRegistry(entries);
+  }
+
+  /** @returns {Uint8Array} */
+  encode() {
+    return MsgPack.encode(this.entries.map((e) => [e.hash, e.names, e.note ?? null]));
+  }
+
+  /** @param {string} name @returns {Uint8Array | null} */
+  resolve(name) {
+    for (const e of this.entries) {
+      if (e.names.includes(name)) return e.hash;
+    }
+    return null;
+  }
+
+  /** @param {Uint8Array} hash @returns {string[]} */
+  namesFor(hash) {
+    for (const e of this.entries) {
+      if (_bytesEqual(e.hash, hash)) return [...e.names];
+    }
+    return [];
+  }
+
+  /** @param {Uint8Array} hash @returns {string | null} */
+  primaryName(hash) {
+    const names = this.namesFor(hash);
+    return names[0] ?? null;
+  }
+
+  /** @param {string} name @param {Uint8Array} hash @param {string | null} [note] */
+  add(name, hash, note) {
+    for (const e of this.entries) {
+      if (_bytesEqual(e.hash, hash)) {
+        if (!e.names.includes(name)) e.names.push(name);
+        if (note !== undefined) e.note = note;
+        return;
+      }
+    }
+    this.entries.push({ hash, names: [name], note: note ?? null });
+  }
+
+  /** @param {Uint8Array} hash */
+  setSelf(hash) {
+    for (const e of this.entries) {
+      const i = e.names.indexOf(SELF_ALIAS);
+      if (i !== -1) e.names.splice(i, 1);
+    }
+    this.entries = this.entries.filter((e) => e.names.length > 0);
+    this.add(SELF_ALIAS, hash);
+  }
+}
+
+// -- decode helpers ---------------------------------------------------------
+
+/**
+ * @param {Uint8Array} bytes
+ * @returns {StoreConfig}
+ */
+function _decodeConfig(bytes) {
+  const arr = MsgPack.decode(bytes);
+  if (!Array.isArray(arr) || arr.length !== 7) {
+    throw new Error("config record must be a 7-element MessagePack array");
+  }
+  const [primarySalt, legacySalts, anchors, authoritative, horizonDays, rfedTopic, rfedNode] = arr;
+  return {
+    primarySalt: _expectBytes(primarySalt, SALT_SIZE, "primary_salt"),
+    legacySalts: legacySalts.map((s) => _expectBytes(s, SALT_SIZE, "legacy_salt")),
+    anchors: anchors.map((a) => _expectBytes(a, HASH_SIZE, "anchor")),
+    authoritative: authoritative instanceof Uint8Array ? authoritative : null,
+    horizonDays: Number(horizonDays),
+    rfedTopic: String(rfedTopic),
+    rfedNode: rfedNode instanceof Uint8Array ? rfedNode : null,
+  };
+}
+
+/**
+ * @param {unknown} value
+ * @param {number} len
+ * @param {string} name
+ * @returns {Uint8Array}
+ */
+function _expectBytes(value, len, name) {
+  if (!(value instanceof Uint8Array) || value.length !== len) {
+    throw new Error(`${name} must be a ${len}-byte Uint8Array`);
+  }
+  return value;
+}
+
+/** @param {Uint8Array} a @param {Uint8Array} b @returns {boolean} */
+function _bytesEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
+  return diff === 0;
+}
+
+/** @param {string} hex @returns {Uint8Array} */
+function _hexToBytes(hex) {
+  const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+  const out = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+/** @param {number} n @returns {Uint8Array} */
+function _randomBytes(n) {
+  const out = new Uint8Array(n);
+  crypto.getRandomValues(out);
+  return out;
+}

package/src/hlc.js

@@ -68,6 +68,39 @@ export class Clock {
   #lastMs = 0;
   #logical = 0;
 
+  /**
+   * Get the last physical timestamp (ms).
+   * @returns {number}
+   */
+  get lastMs() {
+    return this.#lastMs;
+  }
+
+  /**
+   * Get the current logical counter.
+   * @returns {number}
+   */
+  get logical() {
+    return this.#logical;
+  }
+
+  /**
+   * Restore the clock from a snapshot (for store persistence).
+   * @param {{ lastMs: number, logical: number }} snap
+   */
+  restore(snap) {
+    if (!snap || typeof snap.lastMs !== "number" || typeof snap.logical !== "number") {
+      throw new Error("restore requires an object with lastMs and logical");
+    }
+    this.#lastMs = snap.lastMs;
+    this.#logical = snap.logical;
+  }
+
+  /** Obtain a snapshot for persistence. @returns {{ lastMs: number, logical: number }} */
+  snapshot() {
+    return { lastMs: this.#lastMs, logical: this.#logical };
+  }
+
   /** Advance from a local event and return the new HLC. @returns {bigint} */
   now() {
     const phys = physicalNowMs();

package/src/verifier.js

@@ -144,6 +144,33 @@ export class Keyring {
   resolve(issuerHash) {
     return this._map.get(toHex(_asHash(issuerHash))) ?? null;
   }
+
+  /**
+   * Remove an Issuer from the keyring.
+   * @param {Uint8Array} issuerHash
+   * @returns {boolean} `true` if the Issuer was present (and is now removed).
+   */
+  forget(issuerHash) {
+    return this._map.delete(toHex(_asHash(issuerHash)));
+  }
+
+  /**
+   * Return `[issuerHashHex, keyset]` pairs for all registered Issuers.
+   * @returns {[string, IssuerKeyset][]}
+   */
+  entries() {
+    return [...this._map.entries()];
+  }
+
+  /** Number of registered Issuers. @returns {number} */
+  get size() {
+    return this._map.size;
+  }
+
+  /** @param {Uint8Array} issuerHash @returns {boolean} */
+  has(issuerHash) {
+    return this._map.has(toHex(_asHash(issuerHash)));
+  }
 }
 
 /**