@reticulum/dacar 1.0.0

package/src/engine.js

@@ -0,0 +1,198 @@
+/**
+ * The evaluation engine (§7).
+ *
+ * Resolves a plaintext request `(Object, Relation, Grantee)` against the local
+ * CRDT state and the recursive delegation graph, terminating at a Root Trust
+ * Anchor.
+ *
+ * Resolution (§7.3): DENY if any valid active Deny Tuple exists; else ALLOW if
+ * any valid active Allow Tuple exists; else DENY. "Valid" means the granting
+ * Issuer's authority traces back to a Root Trust Anchor (directly, or recursively
+ * via the reserved `admin` relation).
+ *
+ * Namespace Label Privacy (§3.3) means the engine never compares plaintext
+ * labels: it hashes the request with every configured salt (§10.2) and matches
+ * the byte arrays against hashed Tuples. The total-work bound (§7.2) is enforced
+ * *per request across all salt tracks simultaneously* (§10.2).
+ *
+ * Hashing (Web Crypto) is asynchronous, so `evaluate()` is async. To keep the
+ * recursive core fast and synchronous, every per-salt hash needed during
+ * evaluation — including the `admin`/`-admin` relation hashes used by authority
+ * recursion — is precomputed up front into a hypothesis object. The challenge
+ * server (§8) builds the same hypothesis objects straight from the wire and
+ * calls the synchronous `evaluateHashes()`.
+ */
+
+import { toHex } from "@reticulum/core";
+import { covers } from "./namespace.js";
+
+/** Maximum delegation hops in a single evaluation path (§7.2). */
+export const DEFAULT_MAX_DEPTH = 10;
+/** Maximum evaluation steps (visited nodes) per request (§7.2). */
+export const DEFAULT_MAX_VISITED = 50;
+/** The reserved relation that confers the authority to delegate (§3.2). */
+export const ADMIN_RELATION = "admin";
+
+/**
+ * @typedef {Object} Hypothesis
+ * @property {import("./namespace.js").NamespaceHasher} hasher
+ * @property {Uint8Array[]} objectHashes Exact request object hashes for this salt.
+ * @property {Uint8Array} allowRelationHash HMAC of the requested relation.
+ * @property {Uint8Array} denyRelationHash HMAC of "-"+requested relation.
+ * @property {Uint8Array} adminAllowHash HMAC of "admin".
+ * @property {Uint8Array} adminDenyHash HMAC of "-admin".
+ */
+
+/**
+ * @typedef {Object} EngineOptions
+ * @property {number} [maxDepth]
+ * @property {number} [maxVisited]
+ */
+
+export class Engine {
+  /**
+   * @param {import("./config.js").Config} config
+   * @param {import("./crdt.js").StateVector} state
+   * @param {EngineOptions} [options]
+   */
+  constructor(config, state, options = {}) {
+    this.config = config;
+    this.state = state;
+    this.maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+    this.maxVisited = options.maxVisited ?? DEFAULT_MAX_VISITED;
+  }
+
+  /**
+   * Hash the plaintext request with every configured salt (§7.1, §10.2) and
+   * resolve it. Returns true iff (object, relation, grantee) is ALLOWED.
+   * @param {string} objectId
+   * @param {string} relation
+   * @param {Uint8Array} grantee
+   * @returns {Promise<boolean>}
+   */
+  async evaluate(objectId, relation, grantee) {
+    const denyRelation = "-" + relation;
+    const hypotheses = await Promise.all(
+      this.config.hashers.map(async (hasher) => {
+        const [objectHashes, allowRelationHash, denyRelationHash, adminAllowHash, adminDenyHash] =
+          await Promise.all([
+            hasher.hashObject(objectId),
+            hasher.hashRelation(relation),
+            hasher.hashRelation(denyRelation),
+            hasher.hashRelation(ADMIN_RELATION),
+            hasher.hashRelation("-" + ADMIN_RELATION),
+          ]);
+        return {
+          hasher,
+          objectHashes: objectHashes.hashes,
+          allowRelationHash,
+          denyRelationHash,
+          adminAllowHash,
+          adminDenyHash,
+        };
+      }),
+    );
+    return this.evaluateHashes(grantee, hypotheses);
+  }
+
+  /**
+   * Evaluate pre-hashed per-salt hypotheses (§7.3, §10.2). Synchronous: all
+   * required hashes are already present in each hypothesis. The total-work bound
+   * is shared across all hypotheses. Used by the §8 challenge server.
+   * @param {Uint8Array} grantee
+   * @param {Hypothesis[]} hypotheses
+   * @returns {boolean}
+   */
+  evaluateHashes(grantee, hypotheses) {
+    // Index active tuples by grantee hex for this request.
+    /** @type {Map<string, import("./tuple.js").Tuple[]>} */
+    const index = new Map();
+    const granteeHex = toHex(grantee);
+    for (const t of this.state.activeTuples()) {
+      const g = toHex(t.grantee);
+      const arr = index.get(g);
+      if (arr) arr.push(t);
+      else index.set(g, [t]);
+    }
+    /** @type {Map<string, boolean>} memo of positive authority results */
+    const memo = new Map();
+    let counter = 0;
+    const { config, maxDepth, maxVisited } = this;
+    const hyps = [...hypotheses];
+
+    /** @param {Hypothesis[]} hs @returns {string} */
+    const objectKey = (hs) => hs.map((h) => toHex(h.hasher.salt) + "|" + h.objectHashes.map(toHex).join(".")).join(";");
+
+    /**
+     * @param {Uint8Array} issuer
+     * @param {Hypothesis[]} hs
+     * @param {number} depth
+     * @param {Set<string>} visited
+     * @returns {boolean}
+     */
+    function authority(issuer, hs, depth, visited) {
+      if (config.isRootAnchor(issuer)) return true; // §7.2 terminal trust anchor
+      const key = toHex(issuer) + "|" + objectKey(hs);
+      if (memo.has(key)) return /** @type {boolean} */ (memo.get(key));
+      if (depth >= maxDepth) return false; // §7.2 recursion depth bound
+      const issuerHex = toHex(issuer);
+      if (visited.has(issuerHex)) return false; // §7.2 cycle detection
+      const nextVisited = new Set(visited);
+      nextVisited.add(issuerHex);
+      // Build admin hypotheses reusing the same object hashes.
+      const adminHyps = hs.map((h) => ({
+        hasher: h.hasher,
+        objectHashes: h.objectHashes,
+        allowRelationHash: h.adminAllowHash,
+        denyRelationHash: h.adminDenyHash,
+        adminAllowHash: h.adminAllowHash,
+        adminDenyHash: h.adminDenyHash,
+      }));
+      const result = _resolve(adminHyps, issuer, depth + 1, nextVisited) === "allow";
+      if (result) memo.set(key, true);
+      return result;
+    }
+
+    /**
+     * @param {Hypothesis[]} hs
+     * @param {Uint8Array} granteeId
+     * @param {number} depth
+     * @param {Set<string>} visited
+     * @returns {"deny" | "allow" | "none"}
+     */
+    function _resolve(hs, granteeId, depth, visited) {
+      counter += 1;
+      if (counter > maxVisited) return "none"; // §7.2 / §10.2 shared total-work bound
+      const gid = toHex(granteeId);
+      const candidates = index.get(gid) ?? [];
+      let denyValid = false;
+      let allowValid = false;
+      for (const candidate of candidates) {
+        for (const h of hs) {
+          if (bytesEqualHash(candidate.relationHash, h.denyRelationHash)) {
+            if (covers(candidate.objectHashes, candidate.wildcard, h.objectHashes)) {
+              if (authority(candidate.issuer, hs, depth, visited)) denyValid = true;
+            }
+          } else if (bytesEqualHash(candidate.relationHash, h.allowRelationHash)) {
+            if (covers(candidate.objectHashes, candidate.wildcard, h.objectHashes)) {
+              if (authority(candidate.issuer, hs, depth, visited)) allowValid = true;
+            }
+          }
+        }
+      }
+      if (denyValid) return "deny";
+      if (allowValid) return "allow";
+      return "none";
+    }
+
+    return _resolve(hyps, grantee, 0, new Set()) === "allow";
+  }
+}
+
+/** Fast hex-free 16-byte equality for relation hashes. @param {Uint8Array} a @param {Uint8Array} b @returns {boolean} */
+function bytesEqualHash(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;
+}

package/src/hlc.js

@@ -0,0 +1,104 @@
+/**
+ * Hybrid Logical Clocks (Dacar spec §5.1).
+ *
+ * An HLC packs into a single 64-bit unsigned integer, transmitted big-endian:
+ *   high 48 bits: physical time (Unix epoch, milliseconds)
+ *   low 16 bits : logical counter
+ *
+ * Packed HLCs are represented as ECMAScript `bigint`, because
+ * `physical_ms << 16` exceeds `Number.MAX_SAFE_INTEGER` for any realistic
+ * timestamp.
+ */
+
+export const PHYSICAL_BITS = 48n;
+export const LOGICAL_BITS = 16n;
+/** @type {bigint} 0xFFFF */
+export const LOGICAL_MASK = (1n << LOGICAL_BITS) - 1n;
+/** @type {bigint} 2^48 - 1 */
+export const MAX_PHYSICAL = (1n << PHYSICAL_BITS) - 1n;
+/** @type {bigint} 2^16 - 1 */
+export const MAX_LOGICAL = LOGICAL_MASK;
+/** @type {bigint} 2^64 - 1 */
+export const MAX_HLC = (1n << 64n) - 1n;
+
+/**
+ * Pack a physical timestamp (ms) and logical counter into a 64-bit HLC.
+ * @param {number} physicalMs
+ * @param {number} logical
+ * @returns {bigint}
+ */
+export function packHlc(physicalMs, logical) {
+  if (!Number.isInteger(physicalMs) || physicalMs < 0 || BigInt(physicalMs) > MAX_PHYSICAL) {
+    throw new RangeError(`physicalMs must fit in 48 bits, got ${physicalMs}`);
+  }
+  if (!Number.isInteger(logical) || logical < 0 || BigInt(logical) > MAX_LOGICAL) {
+    throw new RangeError(`logical must fit in 16 bits, got ${logical}`);
+  }
+  return (BigInt(physicalMs) << LOGICAL_BITS) | BigInt(logical);
+}
+
+/**
+ * Unpack an HLC into its physical (ms) and logical parts (both safe Numbers).
+ * @param {bigint} hlc
+ * @returns {{ physicalMs: number, logical: number }}
+ */
+export function unpackHlc(hlc) {
+  if (typeof hlc !== "bigint" || hlc < 0n || hlc > MAX_HLC) {
+    throw new RangeError(`hlc must fit in 64 bits, got ${hlc}`);
+  }
+  return {
+    physicalMs: Number(hlc >> LOGICAL_BITS),
+    logical: Number(hlc & LOGICAL_MASK),
+  };
+}
+
+/**
+ * Current wall-clock time in milliseconds since the Unix epoch.
+ * @returns {number}
+ */
+export function physicalNowMs() {
+  return Date.now();
+}
+
+/**
+ * A process-local HLC generator producing monotonically non-decreasing
+ * timestamps, able to absorb remote HLCs observed during sync.
+ */
+export class Clock {
+  #lastMs = 0;
+  #logical = 0;
+
+  /** Advance from a local event and return the new HLC. @returns {bigint} */
+  now() {
+    const phys = physicalNowMs();
+    if (phys > this.#lastMs) {
+      this.#lastMs = phys;
+      this.#logical = 0;
+    } else {
+      this.#logical += 1;
+    }
+    return packHlc(this.#lastMs, this.#logical);
+  }
+
+  /**
+   * Absorb a remote HLC observed during sync and return the new local HLC.
+   * @param {bigint} remoteHlc
+   * @returns {bigint}
+   */
+  observe(remoteHlc) {
+    const { physicalMs: rphys, logical: rlog } = unpackHlc(remoteHlc);
+    const phys = physicalNowMs();
+    if (phys > this.#lastMs && phys > rphys) {
+      this.#lastMs = phys;
+      this.#logical = 0;
+    } else if (rphys > this.#lastMs) {
+      this.#lastMs = rphys;
+      this.#logical = rlog + 1;
+    } else if (this.#lastMs > rphys) {
+      this.#logical += 1;
+    } else {
+      this.#logical = Math.max(this.#logical, rlog) + 1;
+    }
+    return packHlc(this.#lastMs, this.#logical);
+  }
+}

package/src/index.js

@@ -0,0 +1,88 @@
+/**
+ * Dacar: Decentralized Access Control for Reticulum (JavaScript reference impl).
+ *
+ * A tuple-based, offline-first authorization policy plane built on an
+ * LWW-Element-Set CRDT, designed for delay-tolerant mesh networks.
+ *
+ * Object and relation labels are stored only as salted HMAC-SHA256 hashes
+ * (§3.3 Namespace Label Privacy), Threshold Groups may act as N-of-M Issuers
+ * (§4.1), and the state is bounded by Time-Horizon Tombstone Pruning (§9).
+ */
+
+export const __version__ = "1.0.0";
+export const __specVersion__ = "1.0-RC7";
+
+// HLC (§5.1)
+export {
+  PHYSICAL_BITS,
+  LOGICAL_BITS,
+  LOGICAL_MASK,
+  MAX_PHYSICAL,
+  MAX_LOGICAL,
+  MAX_HLC,
+  packHlc,
+  unpackHlc,
+  physicalNowMs,
+  Clock,
+} from "./hlc.js";
+
+// Namespace Label Privacy (§3.3)
+export {
+  DELIMITER,
+  WILDCARD,
+  SALT_SIZE,
+  HASH_SIZE,
+  DEFAULT_SALT,
+  MAX_LEGACY_SALTS,
+  NamespaceHasher,
+  covers,
+  split,
+  parseObject,
+  bytesEqual,
+} from "./namespace.js";
+
+// Tuple (§3.1, §6.1)
+export { MAX_SEGMENTS, Tuple } from "./tuple.js";
+
+// Threshold Groups (§4.1)
+export { ThresholdGroup, groupId } from "./threshold.js";
+
+// Operations (§5.2, §5.3)
+export { SIGNATURE_SIZE, HLC_BYTES, Action, Operation } from "./operation.js";
+
+// Verify-on-ingest (§11.2.4)
+export { IssuerKeyset, Keyring, verifyOperation } from "./verifier.js";
+
+// Transport-agnostic Delta receive boundary (§11)
+export { DeltaReceiver } from "./delta.js";
+
+// RNS naming conventions (§8, §11)
+export {
+  APP_NAME,
+  CHALLENGE_ASPECTS,
+  CHALLENGE_DESTINATION,
+  RFED_TOPIC,
+  LXMF_DELIVERY_TITLE,
+} from "./naming.js";
+
+// Config (§4, §10) + state (§6, §9)
+export { Config, DEFAULT_DELETION_HORIZON_DAYS } from "./config.js";
+export { StateVector } from "./crdt.js";
+
+// Engine (§7)
+export {
+  Engine,
+  ADMIN_RELATION,
+  DEFAULT_MAX_DEPTH,
+  DEFAULT_MAX_VISITED,
+} from "./engine.js";
+
+// Challenge (§8)
+export {
+  NONCE_SIZE,
+  Verdict,
+  Challenge,
+  Receipt,
+  AuthoritativeServer,
+  ChallengeClient,
+} from "./challenge.js";

package/src/namespace.js

@@ -0,0 +1,183 @@
+/**
+ * Namespace Label Privacy (Dacar spec §3.3).
+ *
+ * To prevent label disclosure over public transports, Dacar never transmits or
+ * stores Object or Relation strings in plaintext. Every string label is hashed
+ * with **HMAC-SHA256**, keyed with the node's Privacy Salt, and strictly
+ * truncated to the first 16 bytes.
+ *
+ * Objects are split by `:` into segments, each hashed individually. The
+ * terminal suffix wildcard `*` is stripped *before* hashing and carried as a
+ * boolean flag on the Tuple (§3.3).
+ *
+ * > WARNING (§3.3): an unset Privacy Salt defaults to 32 null bytes, which is
+ * > *fail-open on privacy* — the hashes become trivially dictionary-attackable.
+ *
+ * Hashing uses the Web Crypto `HMAC`/`SHA-256` primitives, so all methods are
+ * asynchronous and runtime-portable (browsers, Node, Deno, Bun).
+ */
+
+export const DELIMITER = ":";
+export const WILDCARD = "*";
+
+/** Privacy Salts are 32 bytes of cryptographically secure random data. */
+export const SALT_SIZE = 32;
+/** All label hashes (and RNS.Identity hashes) are 16 bytes. */
+export const HASH_SIZE = 16;
+/** The fail-open default salt when none is configured (§3.3 WARNING). */
+export const DEFAULT_SALT = new Uint8Array(SALT_SIZE);
+/** Maximum number of concurrently-configured Legacy Salts (§10.2). */
+export const MAX_LEGACY_SALTS = 2;
+
+/** Domain-separation tag used to derive a salt's identifying `id_tag` (§8.3). */
+const SALT_ID_TAG = new TextEncoder().encode("dacar.salt.id");
+
+const encoder = new TextEncoder();
+
+/**
+ * Split an object string into its colon-delimited segments.
+ * @param {string} objectId
+ * @returns {string[]}
+ */
+export function split(objectId) {
+  return objectId.split(DELIMITER);
+}
+
+/**
+ * Return `{ segments, wildcard }` for an object string.
+ *
+ * The terminal `*` is stripped and reported via the wildcard flag:
+ *   - `"*"`          -> `{ segments: [], wildcard: true }`   (root wildcard)
+ *   - `"sensor:*"`   -> `{ segments: ["sensor"], wildcard: true }`
+ *   - `"sensor:wind"`-> `{ segments: ["sensor","wind"], wildcard: false }`
+ *
+ * A non-terminal `*` is treated as a literal segment.
+ * @param {string} objectId
+ * @returns {{ segments: string[], wildcard: boolean }}
+ */
+export function parseObject(objectId) {
+  if (objectId === WILDCARD) return { segments: [], wildcard: true };
+  const segments = split(objectId);
+  let wildcard = false;
+  if (segments.length > 0 && segments[segments.length - 1] === WILDCARD) {
+    wildcard = true;
+    segments.pop();
+  }
+  return { segments, wildcard };
+}
+
+/**
+ * Truncate a 32-byte HMAC-SHA256 digest to the first 16 bytes (§3.3).
+ * @param {Uint8Array} digest
+ * @returns {Uint8Array}
+ */
+function truncate16(digest) {
+  return digest.slice(0, HASH_SIZE);
+}
+
+export class NamespaceHasher {
+  /**
+   * @param {Uint8Array} [salt] 32-byte Privacy Salt (defaults to fail-open nulls).
+   */
+  constructor(salt = DEFAULT_SALT) {
+    if (!(salt instanceof Uint8Array) || salt.length !== SALT_SIZE) {
+      throw new RangeError(`salt must be ${SALT_SIZE} bytes`);
+    }
+    /** @readonly @type {Uint8Array} */
+    this.salt = salt;
+    /** Lazily-imported HMAC CryptoKey, shared across all sign calls. */
+    this._keyPromise = null;
+  }
+
+  /** @returns {Promise<CryptoKey>} */
+  _key() {
+    if (!this._keyPromise) {
+      this._keyPromise = crypto.subtle.importKey(
+        "raw",
+        this.salt,
+        { name: "HMAC", hash: "SHA-256" },
+        false,
+        ["sign"],
+      );
+    }
+    return this._keyPromise;
+  }
+
+  /**
+   * HMAC-SHA256(salt, relation) truncated to 16 bytes (§3.3).
+   * @param {string} relation
+   * @returns {Promise<Uint8Array>}
+   */
+  async hashRelation(relation) {
+    const key = await this._key();
+    const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder.encode(relation)));
+    return truncate16(mac);
+  }
+
+  /**
+   * Return `{ hashes, wildcard }` for an object string (§3.3).
+   * @param {string} objectId
+   * @returns {Promise<{ hashes: Uint8Array[], wildcard: boolean }>}
+   */
+  async hashObject(objectId) {
+    const { segments, wildcard } = parseObject(objectId);
+    const key = await this._key();
+    const hashes = await Promise.all(
+      segments.map(async (seg) => {
+        const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder.encode(seg)));
+        return truncate16(mac);
+      }),
+    );
+    return { hashes, wildcard };
+  }
+
+  /**
+   * A 16-byte tag identifying this salt (§8.3 `salt_id_tag`):
+   * `HMAC-SHA256(salt, b"dacar.salt.id")` truncated to 16 bytes.
+   * @returns {Promise<Uint8Array>}
+   */
+  async idTag() {
+    const key = await this._key();
+    const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, SALT_ID_TAG));
+    return truncate16(mac);
+  }
+}
+
+/**
+ * Does a Tuple's hashed Object cover a request's exact hashed Object? (§3.3)
+ *
+ * A match succeeds if the Tuple is wildcarded and its hashes are a *prefix* of
+ * the request hashes, or if the two hash arrays are identical.
+ * @param {Uint8Array[]} tupleHashes
+ * @param {boolean} wildcard
+ * @param {Uint8Array[]} requestHashes
+ * @returns {boolean}
+ */
+export function covers(tupleHashes, wildcard, requestHashes) {
+  if (wildcard) {
+    if (tupleHashes.length > requestHashes.length) return false;
+    for (let i = 0; i < tupleHashes.length; i++) {
+      if (!bytesEqual(tupleHashes[i], requestHashes[i])) return false;
+    }
+    return true;
+  }
+  if (tupleHashes.length !== requestHashes.length) return false;
+  for (let i = 0; i < tupleHashes.length; i++) {
+    if (!bytesEqual(tupleHashes[i], requestHashes[i])) return false;
+  }
+  return true;
+}
+
+/**
+ * Constant-time-ish byte comparison.
+ * @param {Uint8Array} a
+ * @param {Uint8Array} b
+ * @returns {boolean}
+ */
+export function bytesEqual(a, b) {
+  if (!(a instanceof Uint8Array) || !(b instanceof Uint8Array)) return false;
+  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;
+}

package/src/naming.js

@@ -0,0 +1,39 @@
+/**
+ * RNS naming conventions for the Dacar policy plane (spec §8, §11).
+ *
+ * Pure, dependency-free constants. Two scopes:
+ *
+ *   - `RFED_TOPIC` is a *deployment-overridable default*. RFed is a broadcast
+ *     (many-to-many) medium, so deployments sharing an RNS network SHOULD set a
+ *     deployment-specific topic to isolate their policy feeds (verify-on-ingest
+ *     limits cross-feed damage, but not the bandwidth cost or the risk of
+ *     shared root anchors).
+ *   - `CHALLENGE_DESTINATION` and `LXMF_DELIVERY_TITLE` are *fixed
+ *     discriminators*. The §8 Challenge and §11.2 LXMF delivery are addressed
+ *     point-to-point to a specific Identity, so RNS derives isolation from the
+ *     destination *hash* (which embeds the target Identity), not from this name.
+ *
+ * Both the pure core and the (optional) transport adapters reference these, so
+ * the on-wire naming is defined in one place and stays consistent across
+ * language implementations. Transport adapters accept overrides (e.g.
+ * `topic = RFED_TOPIC`) for deployment-specific values.
+ */
+
+/** The RNS App Name under which all Dacar services live (§8, §11). */
+export const APP_NAME = "dacar";
+
+/** Aspects of the §8 Authoritative Challenge destination (App `dacar`). */
+export const CHALLENGE_ASPECTS = Object.freeze(["auth", "v1"]);
+
+/** The full dotted name of the §8 Authoritative Challenge destination. */
+export const CHALLENGE_DESTINATION = "dacar.auth.v1";
+
+/**
+ * RFed topic for many-to-many CRDT convergence (§11.1). Deployment-overridable
+ * default — RFed is broadcast, so shared-network deployments SHOULD set a
+ * distinct topic to isolate their feeds.
+ */
+export const RFED_TOPIC = "dacar.policy.v1";
+
+/** LXMF message title for targeted Delta delivery (§11.2). */
+export const LXMF_DELIVERY_TITLE = "dacar/sync/delta";