@reticulum/dacar 1.0.0

package/src/operation.js

@@ -0,0 +1,256 @@
+/**
+ * Signed authorization Operations / Deltas (Dacar spec §5.2, §5.3).
+ *
+ * An Operation is a cryptographically signed instruction to Grant (Add) or
+ * Revoke (Remove) a Tuple. Ed25519 signing/verification is delegated to the
+ * `Identity` from `@reticulum/core` (Web Crypto), and transport serialization
+ * uses its MessagePack implementation.
+ *
+ * Single-identity issuers carry exactly one signature; Threshold Group issuers
+ * carry exactly `N` signatures from distinct members (§5.2).
+ */
+
+import { Identity, MsgPack, toHex } from "@reticulum/core";
+import { MAX_HLC } from "./hlc.js";
+import { Tuple } from "./tuple.js";
+
+/** Ed25519 signatures are always 64 bytes. */
+export const SIGNATURE_SIZE = 64;
+/** HLC timestamps travel as 64-bit big-endian unsigned integers. */
+export const HLC_BYTES = 8;
+
+/**
+ * The effect of an Operation on the CRDT.
+ * @readonly
+ * @enum {number}
+ */
+export const Action = {
+  REVOKE: 0x00,
+  GRANT: 0x01,
+};
+
+/**
+ * @typedef {Object} OperationInit
+ * @property {Tuple} tuple
+ * @property {number} action One of {@link Action}.
+ * @property {bigint} hlc
+ * @property {Uint8Array[]} [signatures] 64-byte signatures (empty if unsigned).
+ */
+
+export class Operation {
+  /** @param {OperationInit} init */
+  constructor({ tuple, action, hlc, signatures = [] }) {
+    if (action !== Action.GRANT && action !== Action.REVOKE) {
+      throw new TypeError("action must be Action.GRANT or Action.REVOKE");
+    }
+    if (typeof hlc !== "bigint" || hlc < 0n || hlc > MAX_HLC) {
+      throw new RangeError("hlc must be a bigint in [0, 2^64)");
+    }
+    if (!Array.isArray(signatures)) {
+      throw new TypeError("signatures must be an array");
+    }
+    for (const sig of signatures) {
+      if (!(sig instanceof Uint8Array) || sig.length !== SIGNATURE_SIZE) {
+        throw new RangeError(`each signature must be ${SIGNATURE_SIZE} bytes`);
+      }
+    }
+    this.tuple = tuple;
+    this.action = action;
+    this.hlc = hlc;
+    /** @type {Uint8Array[]} */
+    this.signatures = Object.freeze([...signatures]);
+  }
+
+  get issuer() {
+    return this.tuple.issuer;
+  }
+  get grantee() {
+    return this.tuple.grantee;
+  }
+  get relationHash() {
+    return this.tuple.relationHash;
+  }
+  get objectHashes() {
+    return this.tuple.objectHashes;
+  }
+  get wildcard() {
+    return this.tuple.wildcard;
+  }
+
+  /** §5.2 signature pre-image. @returns {Uint8Array} */
+  get preimage() {
+    let len = 16 + 16 + 1 + HLC_BYTES + 16 + 1 + 1;
+    for (const h of this.tuple.objectHashes) len += h.length;
+    const out = new Uint8Array(len);
+    let o = 0;
+    out.set(this.tuple.issuer, o); o += 16;
+    out.set(this.tuple.grantee, o); o += 16;
+    out[o++] = this.action;
+    new DataView(out.buffer).setBigUint64(o, this.hlc, false); // big-endian
+    o += HLC_BYTES;
+    out.set(this.tuple.relationHash, o); o += 16;
+    out[o++] = this.tuple.wildcard ? 0x01 : 0x00;
+    out[o++] = this.tuple.objectHashes.length;
+    for (const h of this.tuple.objectHashes) {
+      out.set(h, o);
+      o += h.length;
+    }
+    return out;
+  }
+
+  /**
+   * Return a copy signed with one or more `@reticulum/core` Identities holding
+   * private keys. Each identity produces one signature, in argument order.
+   * Pass one identity for a single-identity issuer, or `N` member identities for
+   * a Threshold Group issuer (§5.2).
+   * @param {...Identity} identities
+   * @returns {Promise<Operation>}
+   */
+  async sign(...identities) {
+    if (identities.length === 0) throw new Error("at least one signing identity is required");
+    const preimage = this.preimage;
+    const signatures = await Promise.all(identities.map((id) => id.sign(preimage)));
+    return new Operation({ tuple: this.tuple, action: this.action, hlc: this.hlc, signatures });
+  }
+
+  /**
+   * Coerce a public-key-like value into an `@reticulum/core` Identity.
+   * @param {Identity | Uint8Array} value
+   * @returns {Promise<Identity>}
+   */
+  static async _asIdentity(value) {
+    return value instanceof Identity ? value : await Identity.fromPublicKey(value);
+  }
+
+  /**
+   * Verify a single-identity Operation against one public key (§5.2).
+   * @param {Identity | Uint8Array} identityOrPublicKey
+   * @returns {Promise<boolean>}
+   */
+  async verify(identityOrPublicKey) {
+    if (this.signatures.length !== 1) return false;
+    return this.verifyThreshold([identityOrPublicKey], 1);
+  }
+
+  /**
+   * Verify a Threshold Group Operation (§5.2, §4.1). Requires exactly
+   * `threshold` signatures, each valid against a *distinct* member public key.
+   * Duplicate signatures, or signatures verifying against the same public key
+   * more than once, are rejected.
+   * @param {(Identity | Uint8Array)[]} memberPublicKeys
+   * @param {number} threshold
+   * @returns {Promise<boolean>}
+   */
+  async verifyThreshold(memberPublicKeys, threshold) {
+    if (!(Number.isInteger(threshold) && threshold >= 1) || this.signatures.length !== threshold) {
+      return false;
+    }
+    if (memberPublicKeys.length < threshold) return false;
+    const preimage = this.preimage;
+    /** @type {{ id: Identity, key: Uint8Array }[]} */
+    const members = [];
+    for (const v of memberPublicKeys) {
+      const id = await Operation._asIdentity(v);
+      members.push({ id, key: await id.getPublicKey() });
+    }
+    const used = new Set(); // hex of used public keys
+    for (const sig of this.signatures) {
+      if (sig.length !== SIGNATURE_SIZE) return false;
+      let matched = null;
+      for (const m of members) {
+        const hex = toHex(m.key);
+        if (used.has(hex)) continue;
+        if (await m.id.validate(sig, preimage)) {
+          matched = hex;
+          break;
+        }
+      }
+      if (matched === null) return false;
+      used.add(matched);
+    }
+    return used.size === threshold;
+  }
+
+  /**
+   * Verify against a resolved `IssuerKeyset` (§11.2.4 bridge). A resolver maps
+   * the Operation's 16-byte Issuer hash to a keyset; this confirms the
+   * threshold signature against it.
+   * @param {import("./verifier.js").IssuerKeyset} keyset
+   * @returns {Promise<boolean>}
+   */
+  async verifyKeyset(keyset) {
+    return this.verifyThreshold(keyset.memberPublicKeys, keyset.threshold);
+  }
+
+  /** §5.3 transport payload (the Operation must be signed first). @returns {Uint8Array} */
+  toPayload() {
+    if (this.signatures.length === 0) {
+      throw new Error("Operation must be signed before payload serialization");
+    }
+    return MsgPack.encode([
+      this.tuple.issuer,
+      this.tuple.grantee,
+      this.action,
+      this.hlc,
+      this.tuple.relationHash,
+      [...this.tuple.objectHashes],
+      this.tuple.wildcard,
+      [...this.signatures],
+    ]);
+  }
+
+  /**
+   * Deserialize a §5.3 transport payload.
+   * @param {Uint8Array} data
+   * @returns {Operation}
+   */
+  static fromPayload(data) {
+    const decoded = MsgPack.decode(data);
+    if (!Array.isArray(decoded) || decoded.length !== 8) {
+      throw new Error("payload must be an 8-element MessagePack array");
+    }
+    const [issuer, grantee, action, hlc, relationHash, objectHashes, wildcard, signatures] = decoded;
+    if (action !== Action.GRANT && action !== Action.REVOKE) {
+      throw new Error(`unknown action byte ${action}`);
+    }
+    if (!Array.isArray(signatures) || signatures.length === 0) {
+      throw new Error("signatures must be a non-empty array of 64-byte blobs");
+    }
+    return new Operation({
+      tuple: new Tuple({
+        relationHash: expectBytes(relationHash, 16, "relation_hash"),
+        objectHashes: objectHashes.map((h) => expectBytes(h, 16, "object_hash")),
+        wildcard: expectBool(wildcard, "wildcard"),
+        grantee: expectBytes(grantee, 16, "grantee"),
+        issuer: expectBytes(issuer, 16, "issuer"),
+      }),
+      action,
+      hlc: BigInt(hlc),
+      signatures: signatures.map((s) => expectBytes(s, SIGNATURE_SIZE, "signature")),
+    });
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @param {number} len
+ * @param {string} name
+ * @returns {Uint8Array}
+ */
+function expectBytes(value, len, name) {
+  if (!(value instanceof Uint8Array) || value.length !== len) {
+    throw new Error(`${name} must be a ${len}-byte Uint8Array`);
+  }
+  return value;
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} name
+ * @returns {boolean}
+ */
+function expectBool(value, name) {
+  if (typeof value !== "boolean") throw new Error(`${name} must be a boolean`);
+  return value;
+}
+

package/src/threshold.js

@@ -0,0 +1,110 @@
+/**
+ * Threshold Trust Anchors: N-of-M identity groups (Dacar spec §4.1).
+ *
+ * A Threshold Group is a composite authority requiring consensus: an Operation
+ * issued *by* the group MUST carry exactly `N` valid signatures from `N`
+ * distinct members of the `M`-member set (§5.2).
+ *
+ * The **Group ID** is the SHA-256 hash of the alphabetically sorted member
+ * hashes concatenated with the threshold `N`, truncated to the first 16 bytes
+ * (§4.1). The Group ID is itself a 16-byte value usable wherever an Issuer hash
+ * is expected.
+ *
+ * > Scope (§4.1): in v1.0, Threshold Groups MAY ONLY act as Issuers.
+ *
+ * SHA-256 uses Web Crypto, so `groupId()` is asynchronous. Compute it once and
+ * cache the result (`group.id` after the first `await group.groupId()`).
+ */
+
+import { HASH_SIZE } from "./namespace.js";
+
+const encoder = new TextEncoder();
+
+/** The threshold `N` is folded into the Group ID as an 8-byte big-endian int. */
+const THRESHOLD_BYTES = 8;
+
+/** Compare two 16-byte member hashes for ascending sort (byte-wise === hex). */
+function compareHashes(a, b) {
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return a[i] - b[i];
+  }
+  return 0;
+}
+
+/** Synchronously validate member hashes and threshold (shared by all paths). */
+function validateMembers(members, threshold) {
+  if (!(Number.isInteger(threshold) && threshold >= 1 && threshold <= members.length)) {
+    throw new Error(
+      `threshold must satisfy 1 <= N <= M (got N=${threshold}, M=${members.length})`,
+    );
+  }
+  for (const m of members) {
+    if (!(m instanceof Uint8Array) || m.length !== HASH_SIZE) {
+      throw new RangeError(`member hash must be ${HASH_SIZE} bytes`);
+    }
+  }
+  if (members.length < 2) {
+    throw new Error("a threshold group needs at least 2 members (M)");
+  }
+}
+
+/**
+ * Compute the 16-byte Group ID for a member set and threshold (§4.1).
+ *
+ * Members are 16-byte identity hashes, sorted ascending by raw byte value
+ * (equivalent to hex-alphabetical order). The threshold `N` is appended as an
+ * 8-byte big-endian unsigned integer, then SHA-256 of the whole blob is
+ * truncated to 16 bytes.
+ * @param {Uint8Array[]} members
+ * @param {number} threshold
+ * @returns {Promise<Uint8Array>}
+ */
+export async function groupId(members, threshold) {
+  const normalized = [...members].sort(compareHashes);
+  validateMembers(normalized, threshold);
+  const nBytes = new Uint8Array(THRESHOLD_BYTES);
+  new DataView(nBytes.buffer).setBigUint64(0, BigInt(threshold), false); // big-endian
+  const total = normalized.length * HASH_SIZE + THRESHOLD_BYTES;
+  const blob = new Uint8Array(total);
+  let o = 0;
+  for (const m of normalized) {
+    blob.set(m, o);
+    o += HASH_SIZE;
+  }
+  blob.set(nBytes, o);
+  const digest = await crypto.subtle.digest("SHA-256", blob);
+  return new Uint8Array(digest).slice(0, HASH_SIZE);
+}
+
+export class ThresholdGroup {
+  /**
+   * @param {Uint8Array[]} members M member identity hashes (16 bytes each).
+   * @param {number} threshold The consensus threshold N.
+   */
+  constructor(members, threshold) {
+    validateMembers([...members], threshold);
+    /** @readonly @type {Uint8Array[]} sorted ascending. */
+    this.members = [...members].sort(compareHashes);
+    /** @readonly */ this.threshold = threshold;
+    /** Cached Group ID once computed. @type {Uint8Array | null} */
+    this._id = null;
+    this._idPromise = null;
+  }
+
+  /** The number of members `M`. @returns {number} */
+  get size() {
+    return this.members.length;
+  }
+
+  /** The 16-byte Group ID (cached after the first call). @returns {Promise<Uint8Array>} */
+  groupId() {
+    if (this._id) return Promise.resolve(this._id);
+    if (!this._idPromise) {
+      this._idPromise = groupId(this.members, this.threshold).then((id) => {
+        this._id = id;
+        return id;
+      });
+    }
+    return this._idPromise;
+  }
+}

package/src/transport/index.js

@@ -0,0 +1,37 @@
+/**
+ * Optional RNS/RFed/LXMF-dependent transport adapters for Dacar (spec §8, §11).
+ *
+ * These wire the pure, transport-agnostic core — the §8 `Challenge`/
+ * `AuthoritativeServer`/`ChallengeClient` and the §11 `DeltaReceiver` — to the
+ * concrete Reticulum transports from `@reticulum/core`:
+ *
+ *   - {@link RnsIdentityResolver}      §3.1, §11.2.4  recall → verify key
+ *   - {@link RnsChallengeServer} &c.   §8             Challenge over an RNS Link
+ *   - {@link LxmfDeltaDelivery}        §11.2/§11.3    targeted LXMF + Paper Messages
+ *   - {@link RfedDeltaSync}            §11.1          RFed many-to-many convergence
+ *
+ * Importing the pure core (`@reticulum/dacar`) does **not** import this
+ * subpath: it is opt-in via `@reticulum/dacar/transport`. Every adapter depends
+ * only on `@reticulum/core`, which the core already depends on, so the
+ * transport layer adds no new dependency.
+ */
+
+export { RnsIdentityResolver } from "./rnsIdentity.js";
+
+export {
+  CHALLENGE_REQUEST_PATH,
+  DEFAULT_CHALLENGE_TIMEOUT_MS,
+  DEFAULT_ESTABLISH_TIMEOUT_MS,
+  challengeRequestHandler,
+  RnsChallengeServer,
+  RnsLinkTransport,
+  establishLink,
+} from "./rnsChallenge.js";
+
+export {
+  LxmfDeltaDelivery,
+  messageTitle,
+  messageContent,
+} from "./lxmfSync.js";
+
+export { RfedDeltaSync } from "./rfedSync.js";

package/src/transport/lxmfSync.js

@@ -0,0 +1,221 @@
+/**
+ * §11.2 targeted Delta delivery + §11.3 Paper Messages over LXMF.
+ *
+ * LXMF gives Dacar forward-secret, store-and-forward, point-to-point delivery
+ * of Deltas to (possibly offline) nodes, alongside the public RFed broadcast
+ * (§11.1, served by `./rfedSync.js`). A Delta (the §5.3 MessagePack payload)
+ * is embedded as the *content* of an LXMF message whose title is the fixed
+ * discriminator `dacar/sync/delta`; on receipt, only messages with that title
+ * are fed to the shared {@link import("../delta.js").DeltaReceiver
+ * DeltaReceiver} (verify-on-ingest, §11.2.4).
+ *
+ * §11.3 reuses the very same LXMF messages in LXMF's Paper Message encoding
+ * (the `lxm://` URI, high-density QR), giving a fully air-gapped, optical
+ * channel: export produces the encrypted URI; import feeds it straight back
+ * through the router.
+ *
+ * This module is part of the optional transport layer: importing the pure core
+ * never pulls it in. It depends only on `@reticulum/core`, which the core
+ * already depends on, so no new dependency is added.
+ *
+ * Typical use (receiver, wired to a {@link import("@reticulum/core").LXMRouter
+ * LXMRouter}):
+ *
+ * ```js
+ * router.addEventListener("message", async (event) => {
+ *   await delivery.handleMessage(event.detail.message);
+ * });
+ * ```
+ *
+ * Typical use (sender, to a known recipient `lxmf.delivery` hash):
+ *
+ * ```js
+ * await delivery.deliver(deltaPayload, recipientDeliveryHash);
+ * ```
+ *
+ * @example Receiver with a DeltaReceiver wired in
+ * // event.detail.message is the LXMF message the router just decrypted.
+ * await delivery.handleMessage(event.detail.message);
+ */
+
+import { LXMessage as LXMFMessage } from "@reticulum/core";
+import { LXMF_DELIVERY_TITLE } from "../naming.js";
+
+/**
+ * Best-effort title of an LXMF message as text.
+ *
+ * Tolerates the title being a `Uint8Array` (some code paths leave it binary),
+ * decoding it leniently. Used to filter on the fixed `dacar/sync/delta`
+ * discriminator without ever touching the payload.
+ * @param {{ title?: string | Uint8Array } | null} message
+ * @returns {string}
+ */
+export function messageTitle(message) {
+  const t = message ? message.title : undefined;
+  if (typeof t === "string") return t;
+  if (t instanceof Uint8Array) return new TextDecoder().decode(t);
+  return "";
+}
+
+/**
+ * Best-effort content of an LXMF message as raw bytes (the §5.3 Delta payload).
+ *
+ * `@reticulum/core`'s `Message.deserialize()` UTF-8-decodes the content element
+ * into `message.content`, which corrupts arbitrary binary Deltas. The raw bytes
+ * are preserved on `_decodedPayload[2]` (the same field the library uses
+ * internally for §5.6 signature re-verification), so this helper recovers the
+ * exact bytes a Python peer sent with `content=<delta bytes>`. For an
+ * in-process-constructed message whose `content` is already a `Uint8Array`, it
+ * returns that directly.
+ * @param {{ content?: string | Uint8Array, _decodedPayload?: any[] } | null} message
+ * @returns {Uint8Array}
+ */
+export function messageContent(message) {
+  // Deserialized message: the raw content bytes survive on the decoded payload.
+  const raw = message ? message._decodedPayload : undefined;
+  if (Array.isArray(raw) && raw[2] instanceof Uint8Array) {
+    return new Uint8Array(raw[2]);
+  }
+  const c = message ? message.content : undefined;
+  if (c instanceof Uint8Array) return new Uint8Array(c);
+  if (typeof c === "string") return new TextEncoder().encode(c);
+  return new Uint8Array(0);
+}
+
+/**
+ * §11.2 targeted Delta delivery over LXMF; §11.3 Paper Message channel.
+ *
+ * The send paths (`deliver`, `makePaperUri`) are thin wrappers over a bound
+ * `LXMRouter` / outbound `Destination`; the receive path (`handleMessage`) is
+ * the title filter + verify-on-ingest seam and is fully testable without a
+ * live network (the LXMF codec is pure).
+ */
+export class LxmfDeltaDelivery {
+  /** Fixed title discriminator (spec §11.2). Aliases `LXMF_DELIVERY_TITLE`. */
+  static TITLE = LXMF_DELIVERY_TITLE;
+
+  /**
+   * @param {Object} [opts]
+   * @param {import("../delta.js").DeltaReceiver | null} [opts.receiver]
+   *   The shared DeltaReceiver (state + key resolver). May be omitted on a
+   *   send-only node (then `handleMessage` throws if called).
+   * @param {import("@reticulum/core").LXMRouter | null} [opts.router]
+   *   Optional bound `LXMRouter` for `deliver` / `ingestPaperUri`.
+   */
+  constructor({ receiver = null, router = null } = {}) {
+    /** @type {import("../delta.js").DeltaReceiver | null} */
+    this._receiver = receiver;
+    /** @type {import("@reticulum/core").LXMRouter | null} */
+    this._router = router;
+  }
+
+  // -- §11.2 send --------------------------------------------------------
+
+  /**
+   * Builds an LXMF message wrapping one §5.3 Delta payload (§11.2.2).
+   *
+   * The content is the raw Delta bytes (encoded `bin` on the wire, matching the
+   * Python reference's `content=<delta bytes>`), under the fixed
+   * `dacar/sync/delta` title. The returned message is *not yet sent*; pass it
+   * to `router.send()` (or call {@link deliver}) to queue it for the network.
+   * @param {Uint8Array} deltaPayload
+   * @param {Uint8Array} destinationHash The recipient `lxmf.delivery` hash.
+   * @param {Uint8Array} sourceHash The sender's `lxmf.delivery` hash.
+   * @returns {import("@reticulum/core").LXMessage}
+   */
+  makeMessage(deltaPayload, destinationHash, sourceHash) {
+    if (!(deltaPayload instanceof Uint8Array)) {
+      throw new TypeError("deltaPayload must be a Uint8Array");
+    }
+    return new LXMFMessage({
+      destinationHash,
+      sourceHash,
+      // bin on the wire — round-trips byte-identical with the Python reference.
+      content: new Uint8Array(deltaPayload),
+      title: LxmfDeltaDelivery.TITLE,
+    });
+  }
+
+  /**
+   * Builds and queues a Delta for LXMF delivery via the bound router (§11.2).
+   *
+   * Uses the router's identity as the LXMF sender (and source hash). Delivery
+   * method is chosen by the router (DIRECT link, falling back to opportunistic).
+   * @param {Uint8Array} deltaPayload
+   * @param {Uint8Array} destinationHash The recipient `lxmf.delivery` hash.
+   * @param {Object} [opts]
+   * @param {Uint8Array | null} [opts.linkId] Reuse an existing DIRECT link id.
+   * @returns {Promise<import("@reticulum/core").LXMessage>}
+   */
+  async deliver(deltaPayload, destinationHash, { linkId = null } = {}) {
+    if (!this._router) {
+      throw new Error("LxmfDeltaDelivery.deliver requires a router");
+    }
+    const sourceHash = this._router.identity.identityHash;
+    const message = this.makeMessage(deltaPayload, destinationHash, sourceHash);
+    await this._router.send(message, this._router.identity, linkId);
+    return message;
+  }
+
+  // -- §11.2 receive -----------------------------------------------------
+
+  /**
+   * LXMF `message` event handler: filter by title, then apply the Delta
+   * (§11.2.4).
+   *
+   * Returns `true` iff a Dacar Delta was applied to the CRDT, `false`
+   * otherwise (wrong title, or a malformed/forged payload — which
+   * `DeltaReceiver.applyPayload()` swallows so a bad message can never crash
+   * the transport). Non-Dacar messages are passed through untouched.
+   * @param {{ title?: string | Uint8Array, content?: string | Uint8Array, _decodedPayload?: any[] } | null} message
+   * @returns {Promise<boolean>}
+   */
+  async handleMessage(message) {
+    if (messageTitle(message) !== LxmfDeltaDelivery.TITLE) return false;
+    if (!this._receiver) {
+      throw new Error("LxmfDeltaDelivery.handleMessage requires a receiver");
+    }
+    return this._receiver.applyPayload(messageContent(message));
+  }
+
+  // -- §11.3 Paper Messages (air-gapped / optical) ----------------------
+
+  /**
+   * Builds a §11.3 Paper Message (`lxm://` URI, QR-encodable) wrapping one
+   * Delta.
+   *
+   * Same wrapping as {@link makeMessage} but encrypted to the recipient via
+   * the outbound `lxmf.delivery` destination (which holds the recipient public
+   * key), so the returned URI carries no plaintext Delta. `sourceIdentity`
+   * signs the message; `outboundDestination` is the recipient's OUT
+   * `lxmf.delivery` destination.
+   * @param {Uint8Array} deltaPayload
+   * @param {Uint8Array} destinationHash The recipient `lxmf.delivery` hash.
+   * @param {Object} opts
+   * @param {import("@reticulum/core").Identity} opts.sourceIdentity
+   * @param {import("@reticulum/core").Destination} opts.outboundDestination
+   * @returns {Promise<string>} The `lxm://` paper URI.
+   */
+  async makePaperUri(deltaPayload, destinationHash, { sourceIdentity, outboundDestination }) {
+    const message = this.makeMessage(deltaPayload, destinationHash, sourceIdentity.identityHash);
+    return message.toPaperUri(sourceIdentity, outboundDestination);
+  }
+
+  /**
+   * Feeds a scanned Paper Message URI back through the bound router (§11.3).
+   *
+   * The router decrypts it (it must own the delivery Identity) and dispatches
+   * the recovered LXMF message as a `message` event, which
+   * {@link handleMessage} then filters and applies. Returns the router's
+   * ingest result (the reconstructed message, or `null` if it was not for this
+   * node / already ingested).
+   * @param {string} uri
+   * @returns {Promise<import("@reticulum/core").LXMessage | null>}
+   */
+  async ingestPaperUri(uri) {
+    if (!this._router) {
+      throw new Error("LxmfDeltaDelivery.ingestPaperUri requires a router");
+    }
+    return this._router.ingestUri(uri);
+  }
+}