@reticulum/dacar 1.1.1 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticulum/dacar",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "JavaScript implementation of Dacar, a Decentralized Access Control system for Reticulum",
   "type": "module",
   "main": "src/index.js",
@@ -44,8 +44,9 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@reticulum/core": "^0.5.3",
-    "@reticulum/node": "^0.6.1"
+    "@reticulum/core": "^0.6.5",
+    "@reticulum/node": "^0.6.5",
+    "@types/node": "^26.2.0"
   },
   "publishConfig": {
     "access": "public"

package/src/challenge.js

@@ -61,7 +61,7 @@ async function asIdentity(value) {
   return value instanceof Identity ? value : await Identity.fromPublicKey(value);
 }
 
-/** @param {unknown} value @param {number} len @param {string} name @returns {Uint8Array} */
+/** @param {Uint8Array} 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`);

package/src/cli/dacar.js

@@ -5,7 +5,7 @@
  * 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`.
+ * `@reticulum/node`'s interfaces and `DacarFileAdapter` (Python-parity layout).
  *
  * Mirrors Python's `dacar/cli/__init__.py` + `commands.py`. Offline commands
  * never start RNS; online commands (`grant --publish`, `sync`) boot RNS, announce
@@ -18,6 +18,7 @@
  *   dacar check <grantee> <relation> <object>
  *   dacar grants
  *   dacar revoke <grantee> <relation> <object> [--publish]
+ *   dacar publish <file> [<file>...] | --outbox | --sent | --all   (docs #8/#11)
  *   dacar identity remember|forget|list ...
  *
  * Online flags: --node <hash>, --topic <topic>, --interface shared|auto|tcp,
@@ -28,12 +29,13 @@ 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, toHex } from "@reticulum/core";
 import { MemoryStorageAdapter } from "@reticulum/core";
-import { FileStorageAdapter } from "@reticulum/node";
-import { RFedClient } from "@reticulum/core/src/rfed/client.js";
+import { DacarFileAdapter } from "./fileStore.js";
+import { RFedClient } from "@reticulum/core/src/rfed/index.js";
 import { bootRns } from "./rns_boot.js";
 
 import { Action, Operation, Tuple, Engine } from "../index.js";
@@ -44,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, discoverRfedNode, ensureNodeIdentity, runPublish, runSync, registerAnnounceHandler } from "./session.js";
+import { announceIdentity, discoverRfedNode, ensureNodeIdentity, runPublishMany, runSync, registerAnnounceHandler } from "./session.js";
 
 const SHORT_HASH = 7;
 
@@ -77,7 +79,7 @@ function defaultStorePath() {
 
 async function openStore(args) {
   const path = args.store || defaultStorePath();
-  const adapter = new FileStorageAdapter(path);
+  const adapter = new DacarFileAdapter(path);
   return new DacarStore(adapter, { identityBytes: args.identity ? await readFile(args.identity) : null });
 }
 
@@ -101,6 +103,24 @@ function hexToBytes(hex) {
   return out;
 }
 
+/**
+ * Normalize an issuer public key to the 64-byte RNS form (X25519 ‖ Ed25519)
+ * used by `IssuerKeyset`. Accepts the canonical 32-byte Ed25519 public key
+ * (Python parity) — padding the unused X25519 half with zeros — or a full
+ * 64-byte RNS public key as-is.
+ * @param {Uint8Array} pubKey 32-byte Ed25519 or 64-byte RNS public key.
+ * @returns {Uint8Array}
+ */
+function asRnsPubKey(pubKey) {
+  if (pubKey.length === 32) {
+    const padded = new Uint8Array(64);
+    padded.set(pubKey, 32);
+    return padded;
+  }
+  if (pubKey.length === 64) return pubKey;
+  throw new CliError(`pubkey must be 32 bytes (64 hex, Ed25519) or 64 bytes (128 hex, RNS), got ${pubKey.length}`);
+}
+
 async function resolveRnsConfigDir(args) {
   const explicit = args.rnsDir ?? process.env.DACAR_RNS_DIR;
   if (explicit) return explicit;
@@ -154,7 +174,7 @@ async function resolveTopic(args, store) {
 async function cmdInit(args) {
   const path = args.store || defaultStorePath();
   await mkdir(path, { recursive: true });
-  const adapter = new FileStorageAdapter(path);
+  const adapter = new DacarFileAdapter(path);
   const store = await DacarStore.init(adapter, {
     salt: args.salt ? hexToBytes(args.salt) : undefined,
     horizonDays: parseInt(args.horizon || "180", 10),
@@ -219,21 +239,43 @@ 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(toHex(await tuple.hash()), { 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);
+    // Durability (work doc #11): enqueue the signed payload to the outbox
+    // *before* the risky network send, so it survives a crash or failed
+    // transport and can be retried via `publish --outbox`. On send it moves
+    // outbox → sent box (the durable replay log), so every issued Delta lands
+    // in the durable log and can be re-sent to new peers.
+    const ob = await store.loadOutbox();
+    ob.push(payload);
+    await store.saveOutbox(ob);
+    const accepted = await publishDelta(args, store, identity, [payload]);
+    await recordPublish(store, [payload], accepted, { recordToSent: true });
+    if (accepted[0]) {
+      err("  (published + logged to sent box)");
+    } else {
+      err("  (send failed; retained in outbox for retry)");
+    }
+  } else {
+    // Outbox (work doc #8): queue locally-issued deltas for `publish --outbox`.
+    // (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 --outbox` to flush)");
   }
   return 0;
 }
 
-async function publishDelta(args, store, identity, payload) {
+async function publishDelta(args, store, identity, payloads) {
   const aliases = await store.loadAliases();
   const topic = await resolveTopic(args, store);
   const configDir = await resolveRnsConfigDir(args);
@@ -258,9 +300,74 @@ async function publishDelta(args, store, identity, payload) {
   await registerAnnounceHandler({ rns, keyring, onSave: (kr) => store.saveKeyring(kr) });
 
   const client = new RFedClient({ identity, rns });
-  await runPublish({ deltaPayload: payload, nodeHash, topic, client });
+  // Publish each Delta as its own compact inner-format message (§11.1.1) —
+  // one §5.3 Operation per envelope, never a multi-delta batch (the publish
+  // destination is fire-and-forget and capped by the ~500-byte path MTU).
+  // RNS is a singleton, so boot + subscribe happen once for the whole batch.
+  const accepted = await runPublishMany({
+    deltaPayloads: payloads, nodeHash, topic, client, rns,
+  });
   await store.saveKeyring(keyring);
-  err(`  published to rfed channel ${JSON.stringify(topic)} via ${shortHash(nodeHash, args.fullHashes)}`);
+  const total = payloads.length;
+  const sent = accepted.filter((ok) => ok).length;
+  if (sent < total) {
+    err(`  ⚠ only ${sent}/${total} delta(s) accepted by the transport ` +
+      "(fire-and-forget: node storage is not confirmed)");
+  }
+  err(`  sent ${sent}/${total} delta(s) to rfed channel ${JSON.stringify(topic)} via ${shortHash(nodeHash, args.fullHashes)}`);
+  return accepted;
+}
+
+/**
+ * Update the outbox + sent box after a publish attempt (work doc #11).
+ *
+ * - Remove every transport-accepted payload from the **outbox** (it has been
+ *   sent, so it leaves the unsent queue).
+ * - If `recordToSent`, append transport-accepted payloads to the **sent box**
+ *   (the durable replay log), deduplicating by exact bytes. Re-sends from the
+ *   sent box (`publish --sent`) are already present, so this is a no-op for them.
+ *
+ * Returns the number of accepted deltas. Pure store logic (no RNS) so it runs
+ * even when `publishDelta` is patched in tests.
+ * @param {import("./store.js").DacarStore} store
+ * @param {Uint8Array[]} payloads
+ * @param {boolean[]} accepted Per-delta transport acceptance.
+ * @param {Object} opts
+ * @param {boolean} opts.recordToSent
+ * @returns {Promise<number>}
+ */
+async function recordPublish(store, payloads, accepted, { recordToSent }) {
+  /** @type {Uint8Array[]} */
+  const acceptedBytes = [];
+  for (let i = 0; i < payloads.length; i++) {
+    if (accepted[i]) acceptedBytes.push(new Uint8Array(payloads[i]));
+  }
+  if (!acceptedBytes.length) return 0;
+  // Drain accepted deltas from the outbox (they've been sent).
+  const outbox = await store.loadOutbox();
+  if (outbox.length) {
+    const accSet = new Set(acceptedBytes.map((p) => toHex(p)));
+    const newOutbox = outbox.filter((p) => !accSet.has(toHex(p)));
+    if (newOutbox.length !== outbox.length) {
+      await store.saveOutbox(newOutbox);
+    }
+  }
+  // Append to the sent box (dedup by exact bytes, preserve order).
+  if (recordToSent) {
+    const sent = await store.loadSent();
+    const existing = new Set(sent.map((p) => toHex(p)));
+    let changed = false;
+    for (const p of acceptedBytes) {
+      const h = toHex(p);
+      if (!existing.has(h)) {
+        sent.push(p);
+        existing.add(h);
+        changed = true;
+      }
+    }
+    if (changed) await store.saveSent(sent);
+  }
+  return acceptedBytes.length;
 }
 
 async function cmdSync(args) {
@@ -296,7 +403,7 @@ async function cmdSync(args) {
   const rx = new DeltaReceiver(state, resolver);
 
   const client = new RFedClient({ identity, rns });
-  const applied = await runSync({ nodeHash, topic, client, receiver: rx });
+  const applied = await runSync({ nodeHash, topic, client, receiver: rx, rns });
   await store.saveState(state);
   await store.saveKeyring(keyring);
 
@@ -336,6 +443,150 @@ 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, recordPublish };
+
+/**
+ * `dacar publish` — push signed delta(s) to the rfed channel (§11.1, docs #8/#11).
+ *
+ * Two source families (mutually exclusive):
+ *   - `dacar publish <file> [<file>...]` — publish previously-signed delta
+ *     payload(s) (exact bytes, no re-sign). The **exact signed bytes** are
+ *     published — no re-signing, no new HLC, no local state change — so the
+ *     receiver's verify-on-ingest authenticates the *original* issuer. These
+ *     are external payloads and are **not** added to the sent box (they are
+ *     not this node's issuance).
+ *   - `dacar publish [--outbox] [--sent] [--all]` — publish this node's own
+ *     issuance from its durable stores (work doc #11):
+ *     - `--outbox` flushes the unsent queue; each Delta **moves** to the sent
+ *       box (the durable replay log) once the transport accepts it.
+ *     - `--sent` re-sends every Delta in the sent box (idempotent: CRDT merge
+ *       is a no-op for already-delivered deltas). The sent box is not modified.
+ *     - `--all` is `--outbox` + `--sent` (everything this node has issued).
+ *
+ * With no source flag and no files, `--outbox` is implied (the common "flush
+ * what I've issued" case). Bare `publish` on an empty outbox is a no-op (0).
+ *
+ * Each Delta is published as its **own** rfed message (one §5.3 Operation per
+ * compact inner-format envelope, §11.1.1) — exactly like `grant --publish`.
+ * All sources reuse the `grant --publish` machinery (`publishDelta`: boot RNS,
+ * announce, subscribe, publish), then record accepted deltas via
+ * `recordPublish` (sent box append + outbox drain).
+ */
+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;
+  let useOutbox = !!args.outbox || useAll;
+  let useSent = !!args.sent || useAll;
+  const files = args._positionals ?? [];
+  let fromStores = useOutbox || useSent;
+
+  if (files.length && fromStores) {
+    throw new CliError(
+      "publish: use either <file>... or a source flag (--outbox/--sent/--all), not both",
+    );
+  }
+  // With no files and no source flag, `--outbox` is implied (doc #11): the
+  // common case is "flush what I've issued".
+  if (!files.length && !fromStores) {
+    useOutbox = true;
+    fromStores = true;
+  }
+
+  /** @type {Uint8Array[]} */
+  const toPublish = [];
+  if (useOutbox) toPublish.push(...(await store.loadOutbox()));
+  if (useSent) toPublish.push(...(await store.loadSent()));
+  for (const path of files) {
+    const data = await readPayloadInput(path, !!args.binary);
+    if (!data.length) throw new CliError(`empty payload: ${path}`);
+    toPublish.push(data);
+  }
+
+  if (!toPublish.length) {
+    const which = [
+      ["outbox", useOutbox],
+      ["sent", useSent],
+    ].filter(([, on]) => on).map(([n]) => n).join(" + ") || "outbox";
+    err(`nothing to publish (${which} empty)`);
+    return 0;
+  }
+
+  // Dedup the send list by exact bytes, preserving first-seen order (a delta
+  // could appear in both the outbox and the sent box after a partial-failure
+  // recovery; sending it once is sufficient — CRDT merge is idempotent).
+  const seen = new Set();
+  const deduped = [];
+  for (const payload of toPublish) {
+    const h = toHex(payload);
+    if (!seen.has(h)) {
+      seen.add(h);
+      deduped.push(new Uint8Array(payload));
+    }
+  }
+
+  // External file payloads are not this node's issuance -> not logged to the
+  // sent box. Anything sourced from a store (outbox/sent/--all) is recorded.
+  const recordToSent = files.length === 0;
+
+  const labelParts = [];
+  if (useOutbox) labelParts.push("outbox");
+  if (useSent) labelParts.push("sent");
+  if (files.length) labelParts.push(`${files.length} file(s)`);
+  err(`  publishing ${deduped.length} delta(s) (${labelParts.join(" + ")})`);
+
+  const accepted = await publishDelta(args, store, identity, deduped);
+  const nSent = await recordPublish(store, deduped, accepted, { recordToSent });
+
+  if (useOutbox && !files.length) {
+    err(
+      `  (${nSent} moved outbox → sent box; ` +
+        "`dacar publish --sent` to re-send)",
+    );
+  } else if (useSent && !useOutbox && !files.length) {
+    err("  (sent box re-sent; not modified — idempotent)");
+  }
+  return 0;
+}
+
 async function readStdin() {
   const chunks = [];
   for await (const chunk of process.stdin) chunks.push(chunk);
@@ -354,10 +605,8 @@ async function cmdIdentityRemember(args) {
   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}`);
+    pubKey = new Uint8Array(await readFile(args.file));
   } else {
     // Boot RNS and try to recall.
     const configDir = await resolveRnsConfigDir(args);
@@ -374,11 +623,12 @@ async function cmdIdentityRemember(args) {
     pubKey = await recalled.getPublicKey();
   }
 
+  pubKey = asRnsPubKey(pubKey);
   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(`  pubkey : ${toHex(pubKey.slice(32)).slice(0, SHORT_HASH)}…`);
   err(`  cache  : ${keyring.size} entries`);
   return 0;
 }
@@ -425,7 +675,11 @@ async function cmdIdentityList(args) {
   }
   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)}…`);
+    // On disk only the 32-byte Ed25519 half is stored (Python parity); in
+    // memory it's padded to a 64-byte RNS key (zeros ‖ Ed25519). Show the
+    // meaningful Ed25519 half.
+    const ed25519 = pub.length === 64 ? pub.slice(32) : pub;
+    err(`  ${shortHash(hexToBytes(hashHex), args.fullHashes)}  pubkey=${toHex(ed25519).slice(0, SHORT_HASH)}…`);
   }
   return 0;
 }
@@ -447,7 +701,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(toHex(await t.hash()));
     const rel = row?.relation || `[${shortHash(t.relationHash, args.fullHashes)}]`;
     const obj = row?.object || "[hash]";
     err(
@@ -486,6 +740,12 @@ const SUBCOMMANDS = {
     opts: { node: "string", discover: "boolean", topic: "string", "rns-dir": "string", interface: "string" },
     online: true,
   },
+  publish: {
+    run: cmdPublish,
+    opts: { all: "boolean", outbox: "boolean", sent: "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 },
   check: { run: cmdCheck, opts: {}, positional: ["grantee", "relation", "object"], online: false },
   grants: { run: cmdGrants, opts: { all: "boolean", revoked: "boolean" }, online: false },
@@ -512,11 +772,12 @@ function buildOptions(spec) {
   // errors out, and threaded into bootRns to raise the Reticulum log
   // threshold + log interface/announce diagnostics.
   opts.verbose = { type: "boolean", short: "v" };
-  if (spec.positional && spec.positional.length) {
-    opts.store = { type: "string" };
-    opts.identity = { type: "string" };
-    opts["full-hashes"] = { type: "boolean" };
-  }
+  // --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;
 }
 
@@ -568,7 +829,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/fileStore.js

@@ -0,0 +1,166 @@
+/**
+ * `DacarFileAdapter` — a `StorageAdapter` that writes the **canonical Python
+ * `Store` loose-file layout** for the `dacar` namespace (work doc #9), while
+ * delegating everything else (the node signing identity, RNS ratchets, and any
+ * non-dacar namespace) to `@reticulum/node`'s `FileStorageAdapter`.
+ *
+ * Why a separate adapter? `@reticulum/core`'s `FileStorageAdapter` lays records
+ * out as `<dir>/<namespace>/<key>.bin` (the KV contract the browser/test
+ * `MemoryStorageAdapter` also models). Python's canonical `Store` instead
+ * writes **loose files** at the store root — `config`, `clock.msgpack`,
+ * `state.msgpack`, `aliases`, `ledger.msgpack`, `identities.msgpack`,
+ * `outbox.msgpack` — with per-file modes (0600 secret / 0644 public). For the
+ * JS and Python CLIs to share one store directory byte-for-byte, JS must write
+ * the same filenames at the same paths with the same modes.
+ *
+ * The record *names* (the `key` passed to `get`/`set`) are the exact Python
+ * filenames (set in `src/cli/store.js`); this adapter simply writes them at
+ * `<dir>/<key>` with the matching mode, and lists them back via `keys`.
+ *
+ * The node's own signing **identity private key** stays library-native:
+ * `FileStorageAdapter` writes/reads `<dir>/identity.key` (128-byte priv+pub),
+ * which coexists with — and is distinct from — Python's 64-byte `<dir>/identity`.
+ * A store therefore carries the identity of whichever CLI initialized it.
+ *
+ * Node-only (imports `node:fs` + `@reticulum/node`); the portable record
+ * encode/decode lives in `src/cli/store.js` (browser-safe, no `fs`).
+ */
+
+import { existsSync } from "node:fs";
+import { chmod, mkdir, readdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { FileStorageAdapter } from "@reticulum/node";
+
+/** Namespace the `DacarStore` writes its records under. */
+const DACAR_NS = "dacar";
+
+/** Directory mode (Python `Store._DIR_MODE`). */
+const DIR_MODE = 0o700;
+
+/**
+ * Per-record file modes, mirroring the canonical Python `Store`:
+ *   - secret records (config, state, ledger, identities, outbox): 0600
+ *   - public records (clock, aliases): 0644
+ * Unknown dacar records default to 0600 (fail-closed).
+ */
+const FILE_MODES = {
+  config: 0o600,
+  "clock.msgpack": 0o644,
+  "state.msgpack": 0o600,
+  aliases: 0o644,
+  "ledger.msgpack": 0o600,
+  "identities.msgpack": 0o600,
+  "outbox.msgpack": 0o600,
+  "sent.msgpack": 0o600,
+};
+
+export class DacarFileAdapter {
+  /**
+   * @param {string} directory Absolute store directory (e.g. `~/.dacar`).
+   */
+  constructor(directory) {
+    this.directory = directory;
+    /** @type {import("@reticulum/node").FileStorageAdapter} */
+    this._fallback = new FileStorageAdapter(directory);
+    this._dirReady = false;
+  }
+
+  /**
+   * Ensure the store directory exists with mode 0700 (Python `Store.init`
+   * `os.chmod(path, DIR_MODE)`; umask-independent via explicit chmod).
+   */
+  async _ensureDir() {
+    if (this._dirReady) return;
+    await mkdir(this.directory, { recursive: true });
+    await chmod(this.directory, DIR_MODE);
+    this._dirReady = true;
+  }
+
+  /**
+   * @param {string} namespace
+   * @param {string} key
+   * @returns {Promise<Uint8Array | null>}
+   */
+  async get(namespace, key) {
+    if (namespace === DACAR_NS) {
+      try {
+        const buf = await readFile(join(this.directory, key));
+        return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+      } catch (e) {
+        if (e.code === "ENOENT") return null;
+        throw e;
+      }
+    }
+    return this._fallback.get(namespace, key);
+  }
+
+  /**
+   * @param {string} namespace
+   * @param {string} key
+   * @param {Uint8Array} value
+   */
+  async set(namespace, key, value) {
+    if (namespace === DACAR_NS) {
+      await this._ensureDir();
+      const path = join(this.directory, key);
+      await writeFile(path, value, { mode: 0o600 });
+      // Force the exact mode (umask-independent), matching Python's os.chmod.
+      await chmod(path, FILE_MODES[key] ?? 0o600);
+      return;
+    }
+    return this._fallback.set(namespace, key, value);
+  }
+
+  /**
+   * @param {string} namespace
+   * @param {string} key
+   */
+  async delete(namespace, key) {
+    if (namespace === DACAR_NS) {
+      try {
+        await unlink(join(this.directory, key));
+      } catch (e) {
+        if (e.code === "ENOENT") return;
+        throw e;
+      }
+      return;
+    }
+    return this._fallback.delete(namespace, key);
+  }
+
+  /**
+   * @param {string} namespace
+   * @returns {Promise<string[]>}
+   */
+  async keys(namespace) {
+    if (namespace === DACAR_NS) {
+      if (!existsSync(this.directory)) return [];
+      const entries = await readdir(this.directory);
+      return entries.filter((f) => Object.prototype.hasOwnProperty.call(FILE_MODES, f));
+    }
+    return this._fallback.keys(namespace);
+  }
+
+  // -- identity + ratchets: delegate to FileStorageAdapter (library-native) -
+
+  /** @param {Uint8Array} bytes */
+  async saveKey(bytes) {
+    return this._fallback.saveKey(bytes);
+  }
+
+  /** @returns {Promise<Uint8Array | null>} */
+  async loadKey() {
+    return this._fallback.loadKey();
+  }
+
+  /** @param {Uint8Array} hash @param {Uint8Array} bytes */
+  async saveOwnedRatchets(hash, bytes) {
+    return this._fallback.saveOwnedRatchets(hash, bytes);
+  }
+
+  /** @param {Uint8Array} hash @returns {Promise<Uint8Array | null>} */
+  async loadOwnedRatchets(hash) {
+    return this._fallback.loadOwnedRatchets(hash);
+  }
+}