@reticulum/dacar 1.0.0

package/src/transport/rfedSync.js

@@ -0,0 +1,228 @@
+/**
+ * §11.1 eventual consistency via RFed (Reticulum Federation).
+ *
+ * Global convergence of the CRDT is handled by RFed's many-to-many broadcast:
+ * each node publishes its signed Operations (§5.3 Deltas) to a shared channel
+ * (default `dacar.policy.v1`, deployment-overridable), and receives peers'
+ * Deltas via RFed fanout. Because every Delta is individually Ed25519-signed,
+ * RFed need not be trusted: received bytes flow through the *same* verify-on-
+ * ingest seam (`DeltaReceiver.applyPayload()`, §11.2.4) as LXMF and optical
+ * delivery — **never** through the unauthenticated `StateVector.merge()` path.
+ * A forged or stale Delta is simply dropped before it can mutate state.
+ *
+ * `RfedDeltaSync` wraps a `@reticulum/core` `RFedClient`. A Delta is wrapped as
+ * the LXMF *content* of a channel message under the fixed `dacar/sync/delta`
+ * title; on receipt the channel is the feed discriminator (every message on it
+ * is a Dacar Delta), and the content bytes are fed to `DeltaReceiver`.
+ *
+ * §11.3 air-gapped/optical transport is served by `./lxmfSync.js` (Paper
+ * Messages); RFed is the online many-to-many path.
+ *
+ * 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:
+ *
+ * ```js
+ * const client = new RFedClient({ identity, rns });
+ * const sync = new RfedDeltaSync({ receiver: new DeltaReceiver(state, resolver), client });
+ * await sync.subscribe(nodeHash);   // cache the channel's stamp cost
+ * await sync.listen();              // receive live fanout Deltas
+ * await sync.publish(deltaPayload, nodeHash);
+ * ```
+ */
+
+import {
+  LXMessage,
+  deliveryHashFor,
+  deriveChannel,
+  unwrapChannelMessage,
+} from "@reticulum/core";
+import { LXMF_DELIVERY_TITLE, RFED_TOPIC } from "../naming.js";
+import { messageContent } from "./lxmfSync.js";
+
+/**
+ * The shape of the decoded fanout callback argument from `RFedClient.listen`.
+ * Only `message` is consumed here.
+ * @typedef {Object} RfedDecoded
+ * @property {import("@reticulum/core").LXMessage} message
+ * @property {unknown} [senderIdentity]
+ * @property {Uint8Array} [senderPub]
+ * @property {Uint8Array} [sourceHash]
+ * @property {boolean} [signatureValid]
+ * @property {Uint8Array} [channelHash]
+ * @property {string | null} [channelName]
+ */
+
+/**
+ * The minimal `RFedClient` surface this adapter relies on. The real client from
+ * `@reticulum/core` satisfies it; tests inject a fake.
+ * @typedef {Object} RFedClientLike
+ * @property {(nodeHash: Uint8Array, channelName: string) => Promise<unknown>} subscribe
+ * @property {(nodeHash: Uint8Array, channelName: string) => Promise<unknown>} [unsubscribe]
+ * @property {(nodeHash: Uint8Array, channelName: string, lxmMessage: import("@reticulum/core").LXMessage) => Promise<unknown>} publish
+ * @property {(nodeHash: Uint8Array, channelName: string) => Promise<{ items: Array<{ channelHash: Uint8Array, blob: Uint8Array }>, morePending: boolean }>} pull
+ * @property {(onMessage: (decoded: RfedDecoded) => void) => Promise<Uint8Array>} listen
+ */
+
+/**
+ * §11.1 RFed Delta broadcast + receive, routed through verify-on-ingest.
+ */
+export class RfedDeltaSync {
+  /** Default RFed channel (deployment-overridable, spec §11.1). */
+  static DEFAULT_TOPIC = RFED_TOPIC;
+
+  /**
+   * @param {Object} opts
+   * @param {import("../delta.js").DeltaReceiver | null} [opts.receiver]
+   *   The shared DeltaReceiver (state + key resolver). May be omitted on a
+   *   publish-only node (then `listen`/`pull` throw if called).
+   * @param {RFedClientLike} opts.client A `@reticulum/core` `RFedClient`.
+   * @param {string} [opts.topic] RFed channel name (default `dacar.policy.v1`).
+   */
+  constructor({ receiver = null, client, topic = RFED_TOPIC }) {
+    if (!client) throw new TypeError("RfedDeltaSync requires an RFedClient");
+    /** @type {import("../delta.js").DeltaReceiver | null} */
+    this._receiver = receiver;
+    /** @type {RFedClientLike} */
+    this._client = client;
+    /** @type {string} */
+    this._topic = topic;
+  }
+
+  /** @returns {string} The configured RFed channel name. */
+  get topic() {
+    return this._topic;
+  }
+
+  /**
+   * Builds the LXMF channel message wrapping one §5.3 Delta payload.
+   *
+   * The message's `sourceHash`/`destinationHash` are placeholders: the rfed
+   * Phase-0 codec (`wrapChannelMessage`) overwrites them with the channel's
+   * `lxmf.delivery` hashes before serialization, so the classic "source_hash
+   * is the bare identity hash" bug cannot occur.
+   * @param {Uint8Array} deltaPayload
+   * @returns {import("@reticulum/core").LXMessage}
+   */
+  makeMessage(deltaPayload) {
+    if (!(deltaPayload instanceof Uint8Array)) {
+      throw new TypeError("deltaPayload must be a Uint8Array");
+    }
+    return new LXMessage({
+      // Overwritten by the rfed codec before going on the wire.
+      destinationHash: new Uint8Array(16),
+      sourceHash: new Uint8Array(16),
+      content: new Uint8Array(deltaPayload),
+      title: LXMF_DELIVERY_TITLE,
+    });
+  }
+
+  /**
+   * Subscribes to the channel on a node, caching its advertised stamp cost.
+   * Call at least once per session and after any publish seems dropped.
+   * @param {Uint8Array} nodeHash Any `rfed.*` destination hash of the node.
+   * @returns {Promise<unknown>} The client's `{ ok, stampCost }` result.
+   */
+  async subscribe(nodeHash) {
+    return this._client.subscribe(nodeHash, this._topic);
+  }
+
+  /**
+   * Removes the subscription.
+   * @param {Uint8Array} nodeHash
+   * @returns {Promise<unknown>}
+   */
+  async unsubscribe(nodeHash) {
+    if (!this._client.unsubscribe) {
+      throw new Error("RFedClient has no unsubscribe");
+    }
+    return this._client.unsubscribe(nodeHash, this._topic);
+  }
+
+  /**
+   * Publishes a Delta to the channel (fire-and-forget, §11.1).
+   *
+   * Call {@link subscribe} first so the channel's stamp cost is cached; an
+   * unstamped publish may be silently dropped by a cost-enforcing node.
+   * @param {Uint8Array} deltaPayload
+   * @param {Uint8Array} nodeHash
+   * @returns {Promise<import("@reticulum/core").LXMessage>} The published message.
+   */
+  async publish(deltaPayload, nodeHash) {
+    const message = this.makeMessage(deltaPayload);
+    await this._client.publish(nodeHash, this._topic, message);
+    return message;
+  }
+
+  /**
+   * Starts listening for live fanout Deltas and routes each through
+   * verify-on-ingest (§11.1, §11.2.4).
+   *
+   * The channel is the feed discriminator, so every received message is a
+   * Dacar Delta; `DeltaReceiver.applyPayload()` authenticates it by signature
+   * and swallows any malformed/forged payload so a bad message can never crash
+   * the transport or mutate state.
+   * @returns {Promise<Uint8Array>} The local `rfed.delivery` destination hash.
+   */
+  async listen() {
+    if (!this._receiver) {
+      throw new Error("RfedDeltaSync.listen requires a receiver");
+    }
+    const receiver = this._receiver;
+    return this._client.listen((decoded) => {
+      // RFedClient.invoke does not await the callback; run applyPayload without
+      // leaving an unhandled rejection (it swallows malformed payloads itself).
+      Promise.resolve(receiver.applyPayload(messageContent(decoded.message))).catch(
+        () => {},
+      );
+    });
+  }
+
+  /**
+   * Drains the node's deferred queue (offline catch-up) and routes each blob
+   * through verify-on-ingest (§11.1).
+   *
+   * Each blob is EC-decrypted with the derived channel identity and the
+   * recovered LXMF message's content is applied. Foreign/undecryptable blobs
+   * are dropped, not fatal. Repeats until the node reports no more pending
+   * pages. Returns the count of Deltas newly applied to the CRDT.
+   *
+   * > **Assumption:** the node serves each deferred entry's `blob` as the rfed
+   * > `inner_blob` (the EC-encrypted channel message), matching the fanout
+   * > payload's inner half. Verify against a live rfed node on first deploy.
+   *
+   * @param {Uint8Array} nodeHash
+   * @returns {Promise<number>}
+   */
+  async pull(nodeHash) {
+    if (!this._receiver) {
+      throw new Error("RfedDeltaSync.pull requires a receiver");
+    }
+    const { identity: channelIdentity } = await deriveChannel(this._topic);
+    const channelDeliveryHash = await deliveryHashFor(channelIdentity);
+    const receiver = this._receiver;
+    let applied = 0;
+    let morePending = true;
+    while (morePending) {
+      const page = await this._client.pull(nodeHash, this._topic);
+      for (const item of page.items) {
+        try {
+          const decoded = await unwrapChannelMessage({
+            innerBlob: item.blob,
+            channelIdentity,
+            channelDeliveryHash,
+          });
+          if (await receiver.applyPayload(messageContent(decoded.message))) {
+            applied++;
+          }
+        } catch {
+          // a foreign/undecryptable blob is dropped, never fatal
+        }
+      }
+      morePending = page.morePending;
+    }
+    return applied;
+  }
+}

package/src/transport/rnsChallenge.js

@@ -0,0 +1,243 @@
+/**
+ * §8 Strict Consistency Challenge over a real RNS Link.
+ *
+ * Optional transport wiring around the already pure-and-tested §8 logic
+ * (`Challenge`, `AuthoritativeServer`, `Receipt`, `ChallengeClient` from
+ * `../challenge.js`). Three pieces:
+ *
+ *   - `challengeRequestHandler(server)` builds the response_generator a server
+ *     registers on the `dacar.auth.v1` destination: it feeds each incoming
+ *     challenge payload to `AuthoritativeServer.handle()` and returns the
+ *     signed Freshness Receipt bytes (or nothing on a malformed challenge).
+ *   - `RnsChallengeServer` exposes an Authoritative Identity on
+ *     `dacar.auth.v1`, accepts Links, and registers that handler.
+ *   - `RnsLinkTransport` is the client-side
+ *     {@link import("../challenge.js").Transport Transport} callable: it sends
+ *     a challenge payload over an established Link and awaits the signed
+ *     receipt, returning `null` on timeout/partition (which §8 treats as DENY).
+ *   - `establishLink()` opens a Link and awaits ACTIVE.
+ *
+ * The Dacar-specific glue (handler wrapping, partition → DENY) is covered by
+ * injected-fake unit tests; the pure §8 protocol is covered by
+ * `test/challenge.test.js`.
+ *
+ * This module is part of the optional transport layer: importing the pure core
+ * never pulls it in. It depends only on `@reticulum/core` (Destination, Link),
+ * which the core already depends on.
+ */
+
+import { Destination, DestType, Link } from "@reticulum/core";
+import { APP_NAME, CHALLENGE_ASPECTS } from "../naming.js";
+
+/** The RNS request path used for the Challenge exchange (§8). */
+export const CHALLENGE_REQUEST_PATH = "challenge";
+
+/** Default Challenge round-trip timeout in milliseconds. Partition → §8 DENY. */
+export const DEFAULT_CHALLENGE_TIMEOUT_MS = 15_000;
+
+/** Default Link establishment timeout in milliseconds (§8.2). */
+export const DEFAULT_ESTABLISH_TIMEOUT_MS = 15_000;
+
+/**
+ * @typedef {import("../challenge.js").AuthoritativeServer} AuthoritativeServer
+ * @typedef {import("@reticulum/core").Destination} DestinationType
+ * @typedef {import("@reticulum/core").Link} LinkType
+ * @typedef {import("@reticulum/core").Identity} IdentityType
+ * @typedef {import("../challenge.js").Transport} Transport
+ */
+
+/**
+ * @callback ResponseGenerator
+ * @param {string} path
+ * @param {any} data The §8.3 challenge payload (a `Uint8Array`).
+ * @param {Uint8Array} requestId
+ * @param {IdentityType | null} remoteIdentity
+ * @param {number} requestTime
+ * @returns {Promise<Uint8Array | null>}
+ */
+
+/**
+ * Builds the response_generator answering Challenge requests (§8.4).
+ *
+ * The returned callable matches the `@reticulum/core` `responseGenerator`
+ * contract (PROTOCOL-SPEC.md §11.2): it feeds `data` (the §8.3 challenge
+ * payload) to `AuthoritativeServer.handle()` and returns the signed Receipt
+ * payload. Malformed or unprocessable challenges yield `null` (no response),
+ * which the client treats as a partition → DENY (§8).
+ * @param {AuthoritativeServer} server
+ * @returns {ResponseGenerator}
+ */
+export function challengeRequestHandler(server) {
+  return async (_path, data) => {
+    try {
+      return await server.handle(data);
+    } catch {
+      return null; // malformed/unprocessable → no response → partition → DENY (§8)
+    }
+  };
+}
+
+/**
+ * Authoritative endpoint: answers Challenge requests over RNS Links (§8).
+ *
+ * Because destination creation is asynchronous, construct via the static
+ * {@link RnsChallengeServer.create} factory. The server creates the
+ * `dacar.auth.v1` destination for `identity`, accepts Links, registers the
+ * Challenge request handler, and (by default) announces so clients can find
+ * it. A running `Reticulum` instance is assumed.
+ */
+export class RnsChallengeServer {
+  /** The request path Challenge requests are served on (§8). */
+  static REQUEST_PATH = CHALLENGE_REQUEST_PATH;
+
+  /**
+   * @param {Object} opts
+   * @param {IdentityType} opts.identity The Authoritative Identity (signs receipts).
+   * @param {AuthoritativeServer} opts.server The pure §8 authoritative evaluator.
+   * @param {import("@reticulum/core").Reticulum} opts.rns A running Reticulum instance.
+   * @param {string} [opts.appName] Override the `dacar` app name.
+   * @param {readonly string[]} [opts.aspects] Override the `auth.v1` aspects.
+   * @param {boolean} [opts.announce] Whether to announce immediately (default true).
+   * @returns {Promise<RnsChallengeServer>}
+   */
+  static async create({
+    identity,
+    server,
+    rns,
+    appName = APP_NAME,
+    aspects = CHALLENGE_ASPECTS,
+    announce = true,
+  }) {
+    const self = new RnsChallengeServer(server);
+    const name = [appName, ...aspects].join(".");
+
+    // Build the `dacar.auth.v1` IN SINGLE destination and bind it to the
+    // transport so routed packets reach it (mirrors LXMRouter.init).
+    const dest = await Destination.IN(name, DestType.SINGLE, identity, rns);
+    rns.transport.bindLocalDestination(dest);
+    rns.registerDestination(dest);
+
+    // Accept Links so clients can issue Challenge requests over them.
+    dest.addEventListener("link_request", async (/** @type {any} */ event) => {
+      try {
+        await dest.acceptLink(event.detail.packet);
+      } catch {
+        // A failed handshake tears itself down; never fatal to the server.
+      }
+    });
+
+    await dest.registerRequestHandler(RnsChallengeServer.REQUEST_PATH, {
+      responseGenerator: challengeRequestHandler(server),
+    });
+
+    if (announce) await dest.announce();
+    self._destination = dest;
+    return self;
+  }
+
+  /** @param {AuthoritativeServer} server */
+  constructor(server) {
+    /** @type {AuthoritativeServer} */
+    this._server = server;
+    /** @type {DestinationType | null} */
+    this._destination = null;
+  }
+
+  /** @returns {AuthoritativeServer} */
+  get server() {
+    return this._server;
+  }
+
+  /** @returns {DestinationType | null} */
+  get destination() {
+    return this._destination;
+  }
+
+  /** @returns {Uint8Array | null} The 16-byte destination hash. */
+  get destinationHash() {
+    return this._destination ? this._destination.destinationHash : null;
+  }
+
+  /**
+   * (Re)announce the destination so clients can resolve a path to it.
+   * @returns {Promise<void>}
+   */
+  async announce() {
+    if (!this._destination) throw new Error("Server not created");
+    await this._destination.announce();
+  }
+}
+
+/**
+ * Client-side {@link Transport} over an established Link.
+ *
+ * Call it with the §8.3 challenge payload: it issues an RNS request on the
+ * link and resolves with the signed Receipt bytes, or `null` on any failure —
+ * a non-ACTIVE link, a send failure, a timeout, or a partition — which
+ * {@link import("../challenge.js").ChallengeClient ChallengeClient} treats as
+ * a partition → DENY (§8).
+ *
+ * `@reticulum/core`'s `Link.request()` throws when the link is not ACTIVE and
+ * rejects on timeout/failure, so a single try/catch maps every failure mode to
+ * the §8 partition penalty without issuing a request on a link that cannot
+ * carry one.
+ */
+export class RnsLinkTransport {
+  /** The request path Challenge requests are sent on (§8). */
+  static REQUEST_PATH = CHALLENGE_REQUEST_PATH;
+
+  /**
+   * @param {LinkType} link An established (or establishable) RNS Link.
+   * @param {Object} [opts]
+   * @param {string} [opts.requestPath] Override the request path.
+   * @param {number} [opts.timeoutMs] Round-trip timeout in milliseconds.
+   */
+  constructor(link, { requestPath = CHALLENGE_REQUEST_PATH, timeoutMs = DEFAULT_CHALLENGE_TIMEOUT_MS } = {}) {
+    this._link = link;
+    this._path = requestPath;
+    this._timeoutMs = timeoutMs;
+  }
+
+  /**
+   * @param {Uint8Array} challengePayload
+   * @returns {Promise<Uint8Array | null>}
+   */
+  async call(challengePayload) {
+    try {
+      const response = await this._link.request(this._path, challengePayload, {
+        timeout: this._timeoutMs,
+      });
+      if (!(response instanceof Uint8Array)) return null;
+      return response;
+    } catch {
+      return null; // inactive link / send failure / timeout → partition → DENY (§8)
+    }
+  }
+}
+
+/**
+ * Opens an RNS Link to `destination` and awaits ACTIVE (§8.2).
+ *
+ * @param {DestinationType} destination An OUT destination whose identity is the
+ *   authoritative responder.
+ * @param {Object} [opts]
+ * @param {number} [opts.timeoutMs] Establishment timeout in milliseconds.
+ * @returns {Promise<LinkType | null>} The active Link, or `null` if it could
+ *   not be established within `timeoutMs` (partition → §8 DENY).
+ */
+export async function establishLink(destination, { timeoutMs = DEFAULT_ESTABLISH_TIMEOUT_MS } = {}) {
+  let link;
+  try {
+    link = await Link.initiate(destination, destination.interfaceLayer.transport);
+    return await link.whenActive(timeoutMs);
+  } catch {
+    if (link) {
+      try {
+        await link.teardown();
+      } catch {
+        // teardown is best-effort on a failed handshake
+      }
+    }
+    return null;
+  }
+}

package/src/transport/rnsIdentity.js

@@ -0,0 +1,84 @@
+/**
+ * RNS Identity-backed KeyResolver (spec §3.1, §11.2.4).
+ *
+ * By spec a Dacar single-identity Issuer Hash **is** a standard 16-byte
+ * `RNS.Identity` hash — `SHA-256(P)[:16]` where `P` is the 64-byte RNS public
+ * key (`X25519_pub ‖ Ed25519_pub`). This resolver turns such a hash into the
+ * full 64-byte public key needed to verify an Operation's signature, by
+ * querying RNS's Identity *recall* store — the same store a live Reticulum
+ * populates from announce interception.
+ *
+ * Dacar's verify-on-ingest (§11.2.4) therefore works on real network Deltas
+ * with no out-of-band key exchange: an announced Identity is recalled by its
+ * hash, and the Operation it claims to be from is signature-checked against
+ * that Identity's signing key.
+ *
+ * Threshold Groups (§4.1) cannot be resolved this way — their Group ID is a
+ * composite hash, not an RNS identity, so RNS has nothing to recall. They —
+ * and any out-of-band single identities — fall through to an optional
+ * *fallback* resolver (e.g. a {@link Keyring} of pre-registered group
+ * keysets). RNS is consulted first, then the fallback, so announced
+ * identities always win.
+ *
+ * This module is part of the optional transport layer: importing the pure
+ * core (`@reticulum/dacar`) never pulls it in. It depends only on
+ * `@reticulum/core`'s `Destination.recall`, which the core already depends on
+ * for `Identity` / `MsgPack`, so it adds no new dependency.
+ */
+
+import { Destination } from "@reticulum/core";
+import { IssuerKeyset } from "../verifier.js";
+
+/**
+ * Invokes a resolver (`KeyResolver` function or a {@link Keyring}) and awaits
+ * its result, tolerating either shape. Mirrors the dispatch in verifier.js.
+ * @param {import("../verifier.js").KeyResolver | import("../verifier.js").Keyring | null} resolver
+ * @param {Uint8Array} hash
+ * @returns {Promise<import("../verifier.js").IssuerKeyset | null>}
+ */
+async function resolveWith(resolver, hash) {
+  if (typeof resolver === "function") return await resolver(hash);
+  if (resolver && typeof resolver.resolve === "function") {
+    return await resolver.resolve(hash);
+  }
+  return null;
+}
+
+/**
+ * Resolves single-identity Issuer hashes via the RNS Identity recall store.
+ *
+ * Usable directly as a {@link import("../verifier.js").KeyResolver KeyResolver}
+ * — both `resolve()` and the callable form (via `resolve` being the only
+ * method) are accepted by `DeltaReceiver` / `verifyOperation`, which dispatch
+ * on `typeof resolver === "function"`. Pass the resolver itself (or its
+ * `.resolve` method) where a `KeyResolver` function is expected.
+ */
+export class RnsIdentityResolver {
+  /**
+   * @param {import("../verifier.js").KeyResolver | import("../verifier.js").Keyring | null} [fallback]
+   *   Consulted when RNS has no Identity for a hash — e.g. for Threshold Group
+   *   IDs and out-of-band identities. RNS is consulted first, then the fallback.
+   */
+  constructor(fallback = null) {
+    this._fallback = fallback;
+  }
+
+  /**
+   * Resolve a 16-byte Issuer hash to an {@link IssuerKeyset}, or `null` when
+   * the Issuer is unknown to both RNS and the fallback (the Operation is then
+   * rejected as unverifiable).
+   * @param {Uint8Array} issuerHash
+   * @returns {Promise<import("../verifier.js").IssuerKeyset | null>}
+   */
+  async resolve(issuerHash) {
+    // `fromIdentityHash = true` scans the recall store matching by the
+    // identity hash (SHA-256(P)[:16]) rather than by destination hash.
+    const identity = await Destination.recall(issuerHash, true);
+    if (identity) {
+      // IssuerKeyset carries the full 64-byte RNS public key (X25519 ‖ Ed25519).
+      return IssuerKeyset.single(await identity.getPublicKey());
+    }
+    if (this._fallback) return resolveWith(this._fallback, issuerHash);
+    return null;
+  }
+}

package/src/tuple.js

@@ -0,0 +1,120 @@
+/**
+ * The authorization Tuple and its canonical hash (Dacar spec §3.1, §6.1).
+ *
+ * A Tuple asserts that a Grantee holds a Relation over an Object, authorized by
+ * an Issuer: `(Object, Relation, Grantee, Issuer)`.
+ *
+ * For Namespace Label Privacy (§3.3), the Relation and Object are stored *only*
+ * as their 16-byte salted hashes. The **Tuple Hash** (§6.1) is SHA-256 over:
+ *
+ *   [16-byte Issuer] + [16-byte Grantee] + [16-byte Relation Hash]
+ *   + [1-byte Wildcard Flag] + [1-byte Segment Count] + [Object Hashes]
+ *
+ * Action and HLC are deliberately excluded, so a Grant and its Revoke for the
+ * same permission resolve to the *same* Tuple Hash. The pre-image is built
+ * synchronously and uniquely identifies a Tuple, so `toHex(preimage)` doubles as
+ * the CRDT's internal map key; the full async SHA-256 is available via `hash()`.
+ */
+
+import { toHex } from "@reticulum/core";
+import { HASH_SIZE, bytesEqual } from "./namespace.js";
+
+/** Maximum number of Object segments (the Segment Count field is one byte). */
+export const MAX_SEGMENTS = 0xff;
+
+/**
+ * @typedef {Object} HashedTupleInit
+ * @property {Uint8Array} relationHash 16-byte HMAC of the relation string.
+ * @property {Uint8Array[]} objectHashes 16-byte HMAC per non-wildcard segment.
+ * @property {boolean} wildcard True iff the Object ended in the suffix `*`.
+ * @property {Uint8Array} grantee 16-byte holder identity hash.
+ * @property {Uint8Array} issuer 16-byte issuer identity hash or Group ID.
+ */
+
+export class Tuple {
+  /** @param {HashedTupleInit} init */
+  constructor({ relationHash, objectHashes, wildcard, grantee, issuer }) {
+    if (!(relationHash instanceof Uint8Array) || relationHash.length !== HASH_SIZE) {
+      throw new RangeError(`relationHash must be ${HASH_SIZE} bytes`);
+    }
+    if (!(grantee instanceof Uint8Array) || grantee.length !== HASH_SIZE) {
+      throw new RangeError(`grantee must be ${HASH_SIZE} bytes`);
+    }
+    if (!(issuer instanceof Uint8Array) || issuer.length !== HASH_SIZE) {
+      throw new RangeError(`issuer must be ${HASH_SIZE} bytes`);
+    }
+    if (objectHashes.length > MAX_SEGMENTS) {
+      throw new RangeError(`too many object segments (${objectHashes.length} > ${MAX_SEGMENTS})`);
+    }
+    for (const h of objectHashes) {
+      if (!(h instanceof Uint8Array) || h.length !== HASH_SIZE) {
+        throw new RangeError(`object segment hash must be ${HASH_SIZE} bytes`);
+      }
+    }
+    /** @readonly */ this.relationHash = relationHash;
+    /** @readonly */ this.objectHashes = Object.freeze([...objectHashes]);
+    /** @readonly */ this.wildcard = wildcard;
+    /** @readonly */ this.grantee = grantee;
+    /** @readonly */ this.issuer = issuer;
+  }
+
+  /**
+   * Build a Tuple by hashing plaintext labels with `hasher` (§3.3).
+   * @param {Object} opts
+   * @param {string} opts.objectId
+   * @param {string} opts.relation
+   * @param {Uint8Array} opts.grantee
+   * @param {Uint8Array} opts.issuer
+   * @param {import("./namespace.js").NamespaceHasher} opts.hasher
+   * @returns {Promise<Tuple>}
+   */
+  static async fromPlaintext({ objectId, relation, grantee, issuer, hasher }) {
+    const [relationHash, { hashes, wildcard }] = await Promise.all([
+      hasher.hashRelation(relation),
+      hasher.hashObject(objectId),
+    ]);
+    return new Tuple({ relationHash, objectHashes: hashes, wildcard, grantee, issuer });
+  }
+
+  /** §6.1 hash pre-image (excludes Action + HLC). @returns {Uint8Array} */
+  get preimage() {
+    let len = HASH_SIZE * 3 + 2; // issuer + grantee + relationHash + flags
+    for (const h of this.objectHashes) len += h.length;
+    const out = new Uint8Array(len);
+    let o = 0;
+    out.set(this.issuer, o); o += HASH_SIZE;
+    out.set(this.grantee, o); o += HASH_SIZE;
+    out.set(this.relationHash, o); o += HASH_SIZE;
+    out[o++] = this.wildcard ? 0x01 : 0x00;
+    out[o++] = this.objectHashes.length;
+    for (const h of this.objectHashes) {
+      out.set(h, o);
+      o += h.length;
+    }
+    return out;
+  }
+
+  /** Canonical 32-byte SHA-256 Tuple Hash (§6.1). @returns {Promise<Uint8Array>} */
+  async hash() {
+    const digest = await crypto.subtle.digest("SHA-256", this.preimage);
+    return new Uint8Array(digest);
+  }
+
+  /** Stable unique key derived from the §6.1 pre-image (sync). @returns {string} */
+  get key() {
+    return toHex(this.preimage);
+  }
+
+  /** Structural equality with another Tuple. @param {unknown} other @returns {boolean} */
+  equals(other) {
+    if (!(other instanceof Tuple)) return false;
+    return (
+      bytesEqual(this.relationHash, other.relationHash) &&
+      this.objectHashes.length === other.objectHashes.length &&
+      this.objectHashes.every((h, i) => bytesEqual(h, other.objectHashes[i])) &&
+      this.wildcard === other.wildcard &&
+      bytesEqual(this.grantee, other.grantee) &&
+      bytesEqual(this.issuer, other.issuer)
+    );
+  }
+}