@reticulum/dacar 1.0.0

package/README.md

@@ -0,0 +1,215 @@
+# `@reticulum/dacar` — JavaScript implementation
+
+A JavaScript implementation of the [Dacar 1.0-RC6](../README.md) specification:
+decentralized, offline-first access control for Reticulum mesh networks.
+
+Dacar is a tuple-based authorization system (inspired by Google Zanzibar) built
+on an LWW-Element-Set CRDT. Each node evaluates permissions locally against a
+replicated, eventually-consistent authorization state, with delegation chains
+that terminate at configured Root Trust Anchors.
+
+This is a modern ES-module package with JSDoc type annotations that runs on
+**browsers, Node.js, Deno, and Bun** with no build step.
+
+## Dependencies
+
+| Need | Choice | Why |
+| ---- | ------ | --- |
+| Ed25519 sign/verify (§5.2) | `@reticulum/core` `Identity` (Web Crypto) | The canonical Reticulum JS stack |
+| HMAC-SHA256 / SHA-256 (§3.3, §6.1) | Web Crypto `crypto.subtle` | Standard, runtime-portable |
+| MessagePack (§5.3) | `@reticulum/core` `MsgPack` | Reuses the canonical stack's encoder |
+
+`@reticulum/core` is the only dependency (for both the core and the optional
+transport adapters — which additionally use its `Destination`, `Link`,
+`LXMRouter`, and `RFedClient`).
+
+> **Note on MessagePack + 64-bit HLCs:** a packed HLC (`physical_ms << 16`)
+> exceeds `Number.MAX_SAFE_INTEGER`, so it is represented as a `bigint`. The HLC
+> is always encoded as a `bigint` (uint64) and normalized with `BigInt()` on
+> decode, so it round-trips losslessly.
+
+## Install
+
+```bash
+cd javascript
+npm install
+```
+
+## Layout
+
+```
+src/
+  hlc.js          §5.1  Hybrid Logical Clocks (bigint, 64-bit packed, big-endian)
+  namespace.js    §3.3  Namespace Label Privacy: salted HMAC-SHA256 hashing,
+                        object segmenting, wildcard flag, hashed-object matching
+  tuple.js        §3.1, §6.1  hashed authorization Tuple + SHA-256 Tuple Hash
+  threshold.js    §4.1  N-of-M Threshold Groups + 16-byte Group ID
+  operation.js    §5.2, §5.3  signed Operation (single + multi-sig), pre-image,
+                        MessagePack transport payload
+  crdt.js         §6, §9  LWW-Element-Set state, merge (Remove wins ties),
+                        Time-Horizon Tombstone Pruning, intake rejection
+  config.js       §4, §10  Root Trust Anchors, Privacy Salts (Primary + Legacy),
+                        Authoritative Identity, deletion horizon
+  engine.js       §7    recursive delegation evaluation, hashed hypotheses,
+                        multi-salt shared work bound
+  challenge.js    §8    Strict Consistency Challenge (hashed, multi-salt) +
+                        signed Freshness Receipts
+  verifier.js     §5.2, §11.2.4  verify-on-ingest: IssuerKeyset, KeyResolver,
+                        Keyring, verifyOperation()
+  delta.js        §11.2.4  DeltaReceiver — transport-agnostic receive boundary
+                        (decode → verify → apply)
+  naming.js       §8, §11  RNS naming constants (fixed discriminators +
+                        configurable RFed topic)
+  index.js              public API
+  transport/      §8, §11.2, §11.3  optional RNS/RFed/LXMF adapters (opt-in):
+    rnsIdentity.js   §3.1, §11.2.4  RnsIdentityResolver (recall → verify key)
+    rnsChallenge.js  §8  Challenge over an RNS Link (server endpoint +
+                        client transport + establishLink)
+    lxmfSync.js      §11.2/§11.3  targeted LXMF Delta delivery + Paper Messages
+    rfedSync.js      §11.1  RFed many-to-many convergence
+    index.js               transport barrel
+test/             node:test smoketests for every module (incl. transport-*)
+scripts/test.sh   cross-runtime runner (node / deno / bun)
+```
+
+## Quick start
+
+```js
+import {
+  Action,
+  Clock,
+  Config,
+  Engine,
+  NamespaceHasher,
+  Operation,
+  StateVector,
+  Tuple,
+} from "@reticulum/dacar";
+import { Identity } from "@reticulum/core";
+
+const anchor = await Identity.generate();          // your Root Trust Anchor
+const ROOT = anchor.identityHash;                   // 16-byte hash
+
+const hasher = new NamespaceHasher(); // default salt is FAIL-OPEN; supply a real 32-byte salt!
+const state = new StateVector();
+const clock = new Clock();
+
+// Bootstrap: the root anchor grants "read" on "sensor:wind".
+const op = await new Operation({
+  tuple: await Tuple.fromPlaintext({
+    objectId: "sensor:wind", relation: "read", grantee: ROOT, issuer: ROOT, hasher,
+  }),
+  action: Action.GRANT,
+  hlc: clock.now(),
+}).sign(anchor);
+state.apply(op);
+
+const engine = new Engine(new Config({ rootTrustAnchors: [ROOT] }), state);
+console.log(await engine.evaluate("sensor:wind", "read", ROOT)); // true
+```
+
+## Transport layer
+
+The pure core has no transport: it is wired to the Reticulum transports by the
+optional `@reticulum/dacar/transport` subpath. Importing the core
+(`@reticulum/dacar`) never pulls it in, and every adapter depends only on
+`@reticulum/core` (already a core dependency), so it adds **no new dependency**.
+
+Every transport funnels received bytes through the same verify-on-ingest seam
+(`DeltaReceiver.applyPayload()`, §11.2.4): a Delta is decoded, authenticated by
+Ed25519 signature, and only then merged — regardless of whether it arrived over
+RFed, LXMF, or a scanned QR code.
+
+For **bulk / full-state convergence** (e.g. RFed catch-up), pack many signed
+Deltas into one message and ingest them as a batch with `DeltaReceiver.applyPayloads()`
+— each element is still independently verified-on-ingest, so a forged element
+is dropped without aborting the rest. This is the secure alternative to
+`StateVector.merge()`, which is trusted-local-only (snapshot/restore of a
+node's own state) and must never be fed network bytes:
+
+```js
+const batch = DeltaReceiver.packPayloads([opA.toPayload(), opB.toPayload()]);
+const applied = await rx.applyPayloads(batch); // → # of Deltas verified + applied
+```
+
+```js
+import {
+  RnsIdentityResolver,
+  LxmfDeltaDelivery,
+  RfedDeltaSync,
+  RnsChallengeServer,
+  RnsLinkTransport,
+  establishLink,
+} from "@reticulum/dacar/transport";
+```
+
+| Adapter | Spec | Role |
+| ------- | ---- | ---- |
+| `RnsIdentityResolver` | §3.1, §11.2.4 | Resolves a single-identity Issuer hash to its 64-byte public key via `Destination.recall` (the announce store); Threshold Groups & out-of-band identities fall through to an optional fallback resolver. Usable directly as a `KeyResolver`. |
+| `LxmfDeltaDelivery` | §11.2, §11.3 | Targeted, forward-secret Delta delivery over LXMF (store-and-forward to offline nodes), plus LXMF Paper Message export/import for air-gapped/optical (QR) transport. |
+| `RfedDeltaSync` | §11.1 | Many-to-many CRDT convergence via RFed (`RFedClient`): publish + receive signed Deltas on a shared, deployment-overridable channel, routed through verify-on-ingest — never the unauthenticated `merge()`. |
+| `RnsChallengeServer` / `RnsLinkTransport` / `establishLink` | §8 | The Strict Consistency Challenge over a real RNS Link: an authoritative endpoint answering `dacar.auth.v1` requests, and the client-side `Transport` callable (+ helper to open a Link) for `ChallengeClient`. |
+
+> **The Issuer Hash must be the canonical RNS identity hash.** RNS defines an
+> identity hash as `SHA-256(P)[:16]` where `P` is the 64-byte public key
+> (`X25519_pub ‖ Ed25519_pub`). `RnsIdentityResolver` recalls exactly that hash;
+> any other value cannot be authenticated and is dropped. (Threshold Group IDs
+> are exempt — they are resolved by explicit keyset registration, not recall.)
+
+### RFed convergence
+
+```js
+import { RFedClient } from "@reticulum/core";
+import { DeltaReceiver, StateVector } from "@reticulum/dacar";
+import { RfedDeltaSync } from "@reticulum/dacar/transport";
+
+const client = new RFedClient({ identity, rns });
+const sync = new RfedDeltaSync({
+  receiver: new DeltaReceiver(state, resolver),
+  client,
+  // topic: "dacar.policy.v1",  // deployment-overridable default
+});
+await sync.subscribe(nodeHash);          // cache the channel's stamp cost
+await sync.listen();                     // receive live fanout Deltas
+await sync.publish(deltaPayload, nodeHash);
+```
+
+### Strict Consistency Challenge
+
+```js
+import { ChallengeClient } from "@reticulum/dacar";
+import { RnsChallengeServer, RnsLinkTransport, establishLink } from "@reticulum/dacar/transport";
+
+// Server side: expose the Authoritative Identity on dacar.auth.v1.
+await RnsChallengeServer.create({ identity: authority, server, rns });
+
+// Client side: open a Link and challenge it (partition → DENY).
+const dest = await Destination.OUT("dacar.auth.v1", DestType.SINGLE, authority, rns);
+const link = await establishLink(dest);
+const client = new ChallengeClient(config, state, authorityPublicKey, new RnsLinkTransport(link));
+await client.authorize("sensor:wind", "calibrate", granteeHash);
+```
+
+## Tests
+
+Tests use [`node:test`](https://nodejs.org/api/test.html) and run under every
+installed runtime (node, deno, bun). The runner fails if **none** is installed:
+
+```bash
+npm test            # runs under each installed runtime
+npm run test:node   # node only
+npm run test:deno   # deno only
+npm run test:bun    # bun only
+```
+
+## Publishing
+
+Published to both registries as **`@reticulum/dacar`**:
+
+```bash
+# JSR
+cd javascript && deno publish
+
+# npm
+cd javascript && npm publish
+```

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@reticulum/dacar",
+  "version": "1.0.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",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "sh scripts/test.sh",
+    "test:node": "node --test --test-force-exit test/*.test.js",
+    "test:deno": "deno test --allow-read=test,src --allow-env --no-check test/",
+    "test:bun": "bun test test/"
+  },
+  "keywords": [
+    "reticulum",
+    "rns",
+    "access-control",
+    "authorization",
+    "crdt",
+    "mesh",
+    "offline"
+  ],
+  "license": "EUPL-1.2",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bergie/dacar.git",
+    "directory": "javascript"
+  },
+  "homepage": "https://github.com/bergie/dacar#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@reticulum/core": "^0.5.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/challenge.js

@@ -0,0 +1,394 @@
+/**
+ * Strict Consistency Challenge / Freshness Receipts (§8).
+ *
+ * For destructive operations eventual consistency is dangerous. The node
+ * performs a local pre-check, then challenges a configured Authoritative
+ * Identity over an RNS link (App Name `dacar`, Aspects `auth`, `v1`) for a
+ * signed verdict evaluated against the server's absolute-latest CRDT state.
+ *
+ * To preserve Namespace Label Privacy (§3.3), the Challenge payload carries
+ * only *hashed* hypotheses — never plaintext. The client hashes the request
+ * across its Primary Salt and all Legacy Salts (§10); the server matches each by
+ * its `salt_id_tag` and evaluates directly in hash space.
+ *
+ * Canonical challenge wire format (§8.3):
+ *
+ *   [ nonce(32),
+ *     [ [ salt_id_tag(16), grantee_hash(16), allow_relation_hash(16),
+ *         deny_relation_hash(16), [object_segment_hashes] ],
+ *       ... ] ]
+ *
+ * Each entry is fully self-contained for one salt and carries *both* the allow
+ * and deny relation hashes so the Authority can apply the deny-beats-allow rule
+ * (§7.3) without recovering plaintext.
+ *
+ * The RNS transport is abstracted behind an async `transport` callable
+ * (`challengePayload -> receiptPayload | null`), so the cryptographic and
+ * verdict logic is testable without a live network. A transport that returns
+ * null or throws is a partition -> immediately DENIED (§8).
+ */
+
+import { Identity, MsgPack, toHex } from "@reticulum/core";
+import { Config } from "./config.js";
+import { Engine } from "./engine.js";
+import { Clock, MAX_HLC } from "./hlc.js";
+import { HASH_SIZE, bytesEqual } from "./namespace.js";
+
+/** Cryptographically secure challenge nonces are 32 bytes. */
+export const NONCE_SIZE = 32;
+/** Ed25519 signatures are 64 bytes. */
+const SIGNATURE_SIZE = 64;
+
+/**
+ * The binary verdict carried by a Freshness Receipt.
+ * @readonly
+ * @enum {number}
+ */
+export const Verdict = {
+  DENY: 0x00,
+  ALLOW: 0x01,
+};
+
+/**
+ * @typedef {Uint8Array | Identity} PublicKeyLike
+ */
+
+/**
+ * @param {PublicKeyLike} value
+ * @returns {Promise<Identity>}
+ */
+async function asIdentity(value) {
+  return value instanceof Identity ? value : await Identity.fromPublicKey(value);
+}
+
+/** @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;
+}
+
+/**
+ * @typedef {Object} DecodedEntry
+ * @property {Uint8Array} saltIdTag
+ * @property {Uint8Array} granteeHash
+ * @property {Uint8Array} allowRelationHash
+ * @property {Uint8Array} denyRelationHash
+ * @property {Uint8Array[]} objectHashes
+ */
+
+/**
+ * @typedef {Object} DecodedChallenge
+ * @property {Uint8Array} nonce
+ * @property {Uint8Array} grantee
+ * @property {DecodedEntry[]} entries
+ */
+
+export class Challenge {
+  /**
+   * @param {Object} init
+   * @param {string} init.object Plaintext (held only on the client).
+   * @param {string} init.relation Plaintext (held only on the client).
+   * @param {Uint8Array} init.grantee 16-byte holder identity hash.
+   * @param {Uint8Array} init.nonce 32-byte nonce.
+   * @param {import("./namespace.js").NamespaceHasher[]} init.hashers Salts to hypothesize over.
+   */
+  constructor({ object, relation, grantee, nonce, hashers }) {
+    if (!(grantee instanceof Uint8Array) || grantee.length !== HASH_SIZE) {
+      throw new TypeError(`grantee must be ${HASH_SIZE} bytes`);
+    }
+    if (!(nonce instanceof Uint8Array) || nonce.length !== NONCE_SIZE) {
+      throw new TypeError(`nonce must be ${NONCE_SIZE} bytes`);
+    }
+    if (!Array.isArray(hashers) || hashers.length === 0) {
+      throw new TypeError("at least one salt hasher is required");
+    }
+    this.object = object;
+    this.relation = relation;
+    this.grantee = grantee;
+    this.nonce = nonce;
+    this.hashers = [...hashers];
+  }
+
+  /**
+   * Build a Challenge with a fresh (or supplied) cryptographically secure nonce.
+   * @param {string} object
+   * @param {string} relation
+   * @param {Uint8Array} grantee
+   * @param {import("./namespace.js").NamespaceHasher[]} hashers
+   * @param {Object} [opts]
+   * @param {Uint8Array} [opts.nonce]
+   * @returns {Challenge}
+   */
+  static generate(object, relation, grantee, hashers, { nonce } = {}) {
+    return new Challenge({
+      object,
+      relation,
+      grantee,
+      nonce: nonce ?? crypto.getRandomValues(new Uint8Array(NONCE_SIZE)),
+      hashers,
+    });
+  }
+
+  /** Serialize the hashed multi-salt challenge (§8.3). @returns {Promise<Uint8Array>} */
+  async toPayload() {
+    const denyRelation = "-" + this.relation;
+    const entries = await Promise.all(
+      this.hashers.map(async (hasher) => {
+        const [saltIdTag, allowRelationHash, denyRelationHash, { hashes }] = await Promise.all([
+          hasher.idTag(),
+          hasher.hashRelation(this.relation),
+          hasher.hashRelation(denyRelation),
+          hasher.hashObject(this.object),
+        ]);
+        return [
+          saltIdTag,
+          this.grantee,
+          allowRelationHash,
+          denyRelationHash,
+          [...hashes],
+        ];
+      }),
+    );
+    return MsgPack.encode([this.nonce, entries]);
+  }
+
+  /**
+   * Decode a challenge payload (§8.4). Plaintext is intentionally unrecoverable.
+   * @param {Uint8Array} data
+   * @returns {DecodedChallenge}
+   */
+  static fromPayload(data) {
+    const decoded = MsgPack.decode(data);
+    if (!Array.isArray(decoded) || decoded.length !== 2) {
+      throw new Error("challenge payload must be a 2-element MessagePack array");
+    }
+    const [nonce, entries] = decoded;
+    const nonceBytes = expectBytes(nonce, NONCE_SIZE, "nonce");
+    if (!Array.isArray(entries)) {
+      throw new Error("challenge entries must be an array");
+    }
+    /** @type {DecodedEntry[]} */
+    const result = [];
+    /** @type {Uint8Array | null} */
+    let grantee = null;
+    for (const entry of entries) {
+      if (!Array.isArray(entry) || entry.length !== 5) {
+        throw new Error("each challenge entry must be a 5-element array");
+      }
+      const [saltIdTag, granteeHash, allowRh, denyRh, objectHashes] = entry;
+      if (!Array.isArray(objectHashes)) throw new Error("object_segment_hashes must be an array");
+      const gh = expectBytes(granteeHash, HASH_SIZE, "grantee_hash");
+      if (grantee === null) grantee = gh;
+      else if (!bytesEqual(grantee, gh)) throw new Error("all challenge entries must share one grantee");
+      result.push({
+        saltIdTag: expectBytes(saltIdTag, HASH_SIZE, "salt_id_tag"),
+        granteeHash: gh,
+        allowRelationHash: expectBytes(allowRh, HASH_SIZE, "allow_relation_hash"),
+        denyRelationHash: expectBytes(denyRh, HASH_SIZE, "deny_relation_hash"),
+        objectHashes: objectHashes.map((h) => expectBytes(h, HASH_SIZE, "object_hash")),
+      });
+    }
+    if (grantee === null) throw new Error("challenge must carry at least one entry");
+    return { nonce: nonceBytes, grantee, entries: result };
+  }
+}
+
+/**
+ * @typedef {Object} ReceiptInit
+ * @property {number} verdict One of {@link Verdict}.
+ * @property {bigint} serverHlc
+ * @property {Uint8Array} nonce
+ * @property {Uint8Array} [signature]
+ */
+
+export class Receipt {
+  /** @param {ReceiptInit} init */
+  constructor({ verdict, serverHlc, nonce, signature = new Uint8Array(0) }) {
+    if (verdict !== Verdict.ALLOW && verdict !== Verdict.DENY) {
+      throw new TypeError("verdict must be Verdict.ALLOW or Verdict.DENY");
+    }
+    if (typeof serverHlc !== "bigint" || serverHlc < 0n || serverHlc > MAX_HLC) {
+      throw new RangeError("serverHlc must be a bigint in [0, 2^64)");
+    }
+    if (!(nonce instanceof Uint8Array) || nonce.length !== NONCE_SIZE) {
+      throw new TypeError(`nonce must be ${NONCE_SIZE} bytes`);
+    }
+    if (!(signature instanceof Uint8Array) || (signature.length !== 0 && signature.length !== SIGNATURE_SIZE)) {
+      throw new RangeError(`signature must be 0 or ${SIGNATURE_SIZE} bytes`);
+    }
+    this.verdict = verdict;
+    this.serverHlc = serverHlc;
+    this.nonce = nonce;
+    this.signature = signature;
+  }
+
+  /** Unpadded concatenation of the fields preceding the signature (41 bytes). @returns {Uint8Array} */
+  get preimage() {
+    const hlcBytes = new Uint8Array(8);
+    new DataView(hlcBytes.buffer).setBigUint64(0, this.serverHlc, false); // big-endian
+    const out = new Uint8Array(1 + 8 + NONCE_SIZE);
+    out[0] = this.verdict;
+    out.set(hlcBytes, 1);
+    out.set(this.nonce, 9);
+    return out;
+  }
+
+  /** @param {Identity} identity @returns {Promise<Receipt>} */
+  async sign(identity) {
+    const signature = await identity.sign(this.preimage);
+    return new Receipt({ verdict: this.verdict, serverHlc: this.serverHlc, nonce: this.nonce, signature });
+  }
+
+  /** @param {PublicKeyLike} identityOrPublicKey @returns {Promise<boolean>} */
+  async verify(identityOrPublicKey) {
+    if (this.signature.length !== SIGNATURE_SIZE) return false;
+    const identity = await asIdentity(identityOrPublicKey);
+    return identity.validate(this.signature, this.preimage);
+  }
+
+  /** @returns {Uint8Array} */
+  toPayload() {
+    if (this.signature.length !== SIGNATURE_SIZE) {
+      throw new Error("Receipt must be signed before payload serialization");
+    }
+    return MsgPack.encode([this.verdict, this.serverHlc, this.nonce, this.signature]);
+  }
+
+  /** @param {Uint8Array} data @returns {Receipt} */
+  static fromPayload(data) {
+    const decoded = MsgPack.decode(data);
+    if (!Array.isArray(decoded) || decoded.length !== 4) {
+      throw new Error("receipt payload must be a 4-element MessagePack array");
+    }
+    const [verdict, serverHlc, nonce, signature] = decoded;
+    if (verdict !== Verdict.ALLOW && verdict !== Verdict.DENY) {
+      throw new Error(`unknown verdict byte ${verdict}`);
+    }
+    return new Receipt({
+      verdict,
+      serverHlc: BigInt(serverHlc),
+      nonce: expectBytes(nonce, NONCE_SIZE, "nonce"),
+      signature: expectBytes(signature, SIGNATURE_SIZE, "signature"),
+    });
+  }
+}
+
+/**
+ * Bind each decoded entry to a configured salt via its salt_id_tag (§8.4) and
+ * build the synchronous hypothesis objects the engine consumes.
+ * @param {import("./config.js").Config} config
+ * @param {DecodedChallenge} decoded
+ * @returns {Promise<import("./engine.js").Hypothesis[]>}
+ */
+async function buildHypotheses(config, decoded) {
+  /** @type {Map<string, import("./namespace.js").NamespaceHasher>} */
+  const byTag = new Map();
+  for (const hasher of config.hashers) {
+    byTag.set(toHex(await hasher.idTag()), hasher);
+  }
+  /** @type {import("./engine.js").Hypothesis[]} */
+  const hyps = [];
+  for (const entry of decoded.entries) {
+    const hasher = byTag.get(toHex(entry.saltIdTag));
+    if (!hasher) continue; // unknown salt -> hypothesis unusable, skip
+    const [adminAllowHash, adminDenyHash] = await Promise.all([
+      hasher.hashRelation("admin"),
+      hasher.hashRelation("-admin"),
+    ]);
+    hyps.push({
+      hasher,
+      objectHashes: entry.objectHashes,
+      allowRelationHash: entry.allowRelationHash,
+      denyRelationHash: entry.denyRelationHash,
+      adminAllowHash,
+      adminDenyHash,
+    });
+  }
+  return hyps;
+}
+
+/** The Authoritative Identity: evaluates requests and signs Freshness Receipts. */
+export class AuthoritativeServer {
+  /**
+   * @param {Config} config
+   * @param {import("./crdt.js").StateVector} state
+   * @param {Identity} privateKey Identity holding the signing key.
+   * @param {Object} [opts]
+   * @param {Clock} [opts.clock]
+   */
+  constructor(config, state, privateKey, { clock } = {}) {
+    this._engine = new Engine(config, state);
+    this._state = state;
+    this._config = config;
+    this._privateKey = privateKey;
+    this._clock = clock ?? new Clock();
+  }
+
+  /** @param {Uint8Array} challengePayload @returns {Promise<Uint8Array>} */
+  async handle(challengePayload) {
+    const decoded = Challenge.fromPayload(challengePayload);
+    const hypotheses = await buildHypotheses(this._config, decoded);
+    const allowed = hypotheses.length > 0 && this._engine.evaluateHashes(decoded.grantee, hypotheses);
+    const verdict = allowed ? Verdict.ALLOW : Verdict.DENY;
+    const receipt = await new Receipt({
+      verdict,
+      serverHlc: this._clock.now(),
+      nonce: decoded.nonce,
+    }).sign(this._privateKey);
+    return receipt.toPayload();
+  }
+}
+
+/**
+ * @callback Transport
+ * @param {Uint8Array} challengePayload
+ * @returns {Promise<Uint8Array | null> | Uint8Array | null}
+ */
+
+/** The requesting node: performs the local pre-check and the challenge exchange. */
+export class ChallengeClient {
+  /**
+   * @param {Config} config
+   * @param {import("./crdt.js").StateVector} state
+   * @param {PublicKeyLike} authoritativePublicKey
+   * @param {Transport} transport
+   */
+  constructor(config, state, authoritativePublicKey, transport) {
+    if (config.authoritativeIdentity === undefined) {
+      throw new Error("Strict Consistency requires an Authoritative Identity (§8)");
+    }
+    this._engine = new Engine(config, state);
+    this._state = state;
+    this._config = config;
+    this._publicKey = authoritativePublicKey;
+    this._transport = transport;
+  }
+
+  /**
+   * Run the full §8 flow. Resolves true only on a verified server ALLOW.
+   * @param {string} objectId
+   * @param {string} relation
+   * @param {Uint8Array} grantee
+   * @returns {Promise<boolean>}
+   */
+  async authorize(objectId, relation, grantee) {
+    // §8.1 Local pre-check.
+    if (!(await this._engine.evaluate(objectId, relation, grantee))) return false;
+    // §8.2/§8.3 Challenge across Primary + Legacy salts.
+    const challenge = Challenge.generate(objectId, relation, grantee, this._config.hashers);
+    let receiptPayload;
+    try {
+      receiptPayload = await Promise.resolve(this._transport(await challenge.toPayload()));
+    } catch {
+      return false; // partition penalty (§8)
+    }
+    if (receiptPayload === null || receiptPayload === undefined) return false; // partition (§8)
+    const receipt = Receipt.fromPayload(receiptPayload);
+    // §8.5 Verify nonce match and signature.
+    if (!bytesEqual(receipt.nonce, challenge.nonce)) return false;
+    if (!(await receipt.verify(this._publicKey))) return false;
+    return receipt.verdict === Verdict.ALLOW;
+  }
+}