@reticulum/dacar 1.1.2 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticulum/dacar",
-  "version": "1.1.2",
+  "version": "1.2.1",
   "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,7 +18,7 @@
  *   dacar check <grantee> <relation> <object>
  *   dacar grants
  *   dacar revoke <grantee> <relation> <object> [--publish]
- *   dacar publish <file> [<file>...] | --all   (work doc #8)
+ *   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,
@@ -34,8 +34,8 @@ 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";
@@ -46,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;
 
@@ -79,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 });
 }
 
@@ -103,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;
@@ -156,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),
@@ -221,7 +239,7 @@ async function _issue(args, action) {
 
   // Record plaintext ledger.
   const ledger = await store.loadLedger();
-  ledger.set(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(toHex(payload));
@@ -230,21 +248,34 @@ async function _issue(args, action) {
   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 --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.)
+    // 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 --all` to flush)");
+    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);
@@ -269,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) {
@@ -307,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);
 
@@ -383,19 +479,34 @@ function coercePayload(data, forceBinary) {
   return hexToBytes(trimmed);
 }
 
-export { coercePayload };
+export { coercePayload, recordPublish };
 
 /**
- * `dacar publish` — push signed delta(s) to the rfed channel (§11.1, doc #8).
+ * `dacar publish` — push signed delta(s) to the rfed channel (§11.1, docs #8/#11).
  *
- * Two modes:
+ * Two source families (mutually exclusive):
  *   - `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.
+ *     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).
  *
- * Reuses the `grant --publish` machinery (`publishDelta`: boot RNS, announce,
- * subscribe, publish).
+ * 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);
@@ -403,47 +514,75 @@ async function cmdPublish(args) {
   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 (useAll && files.length) {
-    throw new CliError("publish: use either <file>... or --all, not both");
+  if (files.length && fromStores) {
+    throw new CliError(
+      "publish: use either <file>... or a source flag (--outbox/--sent/--all), not both",
+    );
   }
-  if (!useAll && !files.length) {
-    throw new CliError("publish: provide <file>... (one or more) or --all");
+  // 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[]} */
-  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);
+  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));
     }
   }
 
-  // Pack: a single delta as raw bytes, multiple as a batch payload.
-  const batch = toPublish.length === 1
-    ? toPublish[0]
-    : DeltaReceiver.packPayloads(toPublish);
+  // 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 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}`);
+  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(" + ")})`);
 
-  // Reuse the grant --publish machinery (boot RNS, announce, subscribe, publish).
-  await publishDelta(args, store, identity, batch);
+  const accepted = await publishDelta(args, store, identity, deduped);
+  const nSent = await recordPublish(store, deduped, accepted, { recordToSent });
 
-  if (useAll) {
-    await store.saveOutbox([]);
-    err("  outbox cleared");
+  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;
 }
@@ -466,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);
@@ -486,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;
 }
@@ -537,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;
 }
@@ -559,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(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(
@@ -600,7 +742,7 @@ const SUBCOMMANDS = {
   },
   publish: {
     run: cmdPublish,
-    opts: { all: "boolean", binary: "boolean", node: "string", discover: "boolean", topic: "string", "rns-dir": "string", interface: "string" },
+    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,
   },

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);
+  }
+}