y-reticulum 0.1.3 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-03
+
+### Added
+
+- Optional `linkPolicy` provider option: an application-supplied callback that decides whether a peer link may carry room traffic, evaluated on both the initiator and responder sides once the remote identity is cryptographically proven (via the signed announce on the initiator side, via the signed `LINKIDENTIFY` handshake on the responder side)
+- Optional `identifyTimeoutMs` provider option: how long the responder waits for the initiator's identify handshake before refusing the link (default 10 s)
+- `refused` provider event, fired when a peer link was refused by the link policy, so apps can surface access requests ("peer X wants to join")
+- Browser demo build (`tsdown.config.js`, `demo-src/`)
+
 ## [0.1.3] - 2026-09-21
 
 ## [0.1.2] - 2026-09-21

package/README.md

@@ -90,6 +90,15 @@ new ReticulumProvider(roomName, ydoc[, opts])
   // to the 60s floor from the Reticulum spec (sub-minute intervals trigger
   // ingress rate limiting).
   announceIntervalMs: 60_000,
+  // Optional access control. When set, peer links must prove their identity
+  // (the initiator runs the signed identify handshake over the link) and pass
+  // the policy before any room traffic flows. Refused links are torn down and
+  // reported via the `refused` event. See "Access control" below.
+  linkPolicy: ({ remoteIdentityHash, remoteDestinationHash, initiator }) =>
+    allowed.has(remoteIdentityHash),
+  // How long the responder waits for the initiator's identify handshake
+  // before refusing the link. Only relevant with a `linkPolicy`.
+  identifyTimeoutMs: 10_000,
 }
 ```
 
@@ -100,6 +109,41 @@ The provider extends `ObservableV2` and emits:
 | `status` | `{ connected: boolean }` | the provider (dis)connects from the mesh |
 | `synced` | `{ synced: boolean }` | sync state with the peer mesh changes |
 | `peers` | `{ added: string[], removed: string[] }` | peers are discovered or drop off |
+| `refused` | `{ refusals: Array<{ destinationHash: string \| null, identityHash: string \| null, initiator: boolean }> }` | a peer link was refused by the link policy |
+
+## Access control
+
+Pass a `linkPolicy` to gate which peers may sync with your room. The policy is
+a (possibly async) callback that receives the remote peer's
+`remoteIdentityHash` (hex truncated hash of their long-term Reticulum
+identity), their room `remoteDestinationHash` when known (initiator side;
+`null` on the responder side, where it is only learnt after identify), and
+`initiator` telling which side of the link you are. Return `true` to allow the
+link, `false` to refuse it: refused links are torn down before any room traffic flows, and reported on the `refused` event.
+
+The identity hash is cryptographically bound on both sides: on the initiator
+side it comes from the peer's signed announce, on the responder side from the
+signed identify handshake over the link. Peers that never identify (e.g. older
+versions without ACL support) are refused after `identifyTimeoutMs` and
+reported with a `null` identityHash.
+
+Refusals make natural access requests: collect them and, when a user grants
+access, add the peer's identity hash to your allow-list. The next announce
+cycle connects the peers.
+
+```js
+const granted = new Set([myIdentityHash])
+const provider = new ReticulumProvider("your-room-name", ydoc, {
+  reticulum: rns,
+  identity,
+  linkPolicy: ({ remoteIdentityHash }) => granted.has(remoteIdentityHash),
+})
+provider.on("refused", ({ refusals }) => {
+  for (const { identityHash } of refusals) {
+    console.log("access request from", identityHash) // surface in your UI
+  }
+})
+```
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "y-reticulum",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Reticulum provider for Yjs",
   "keywords": [
     "reticulum",

package/src/provider.js

@@ -37,6 +37,14 @@ import { Room } from "./room.js";
  *   Cadence (ms) at which the room destination is re-announced for discovery.
  *   Forwarded to `Destination.startAnnouncing`, which clamps it to the
  *   §9.7 60 s floor (sub-minute intervals trigger ingress rate limiting).
+ * @property {import("./room.js").LinkPolicy} [linkPolicy]
+ *   When set, peer links must prove their identity (the initiator runs the
+ *   signed identify handshake over the link) and pass the policy before any
+ *   room traffic flows. Refused links are torn down and reported via the
+ *   `refused` event, which apps can use to surface access requests.
+ * @property {number} [identifyTimeoutMs]
+ *   How long the responder waits for the initiator's identify handshake
+ *   before refusing the link.
  */
 
 /**
@@ -50,6 +58,8 @@ import { Room } from "./room.js";
  *   Fired when sync state with the peer mesh changes. (Phase 3.)
  * @property {(event: { added: Array<string>, removed: Array<string> }) => void} peers
  *   Fired when peers are discovered or drop off.
+ * @property {(event: { refusals: Array<{ destinationHash: string | null, identityHash: string | null, initiator: boolean }> }) => void} refused
+ *   Fired when a peer link was refused by the link policy.
  */
 
 /**
@@ -75,6 +85,8 @@ export class ReticulumProvider extends ObservableV2 {
     this.awareness = opts.awareness ?? new awarenessProtocol.Awareness(doc);
     this.maxConns = opts.maxConns ?? 20;
     this.announceIntervalMs = opts.announceIntervalMs ?? 60_000;
+    this.linkPolicy = opts.linkPolicy ?? null;
+    this.identifyTimeoutMs = opts.identifyTimeoutMs ?? 10_000;
 
     /** Resolved with the room destination's identity on connect(). */
     this.identityPromise = opts.identity
@@ -113,6 +125,8 @@ export class ReticulumProvider extends ObservableV2 {
       appName,
       maxConns: this.maxConns,
       announceIntervalMs: this.announceIntervalMs,
+      linkPolicy: this.linkPolicy,
+      identifyTimeoutMs: this.identifyTimeoutMs,
       callbacks: {
         onPeers: (
           /** @type {string[]} */ added,
@@ -120,6 +134,8 @@ export class ReticulumProvider extends ObservableV2 {
         ) => this.emit("peers", [{ added, removed }]),
         onSynced: (/** @type {boolean} */ synced) =>
           this.emit("synced", [{ synced }]),
+        onRefused: (/** @type {any[]} */ refusals) =>
+          this.emit("refused", [{ refusals }]),
       },
     });
     await this.room.connect();

package/src/room.js

@@ -13,7 +13,7 @@
  * lexicographically smaller. The other simply accepts.
  */
 
-import { Destination, DestType, toHex } from "@reticulum/core";
+import { Destination, DestType, Identity, toHex } from "@reticulum/core";
 import * as encoding from "lib0/encoding";
 import * as awarenessProtocol from "y-protocols/awareness";
 import * as syncProtocol from "y-protocols/sync";
@@ -38,12 +38,36 @@ function bytesEqual(/** @type {Uint8Array} */ a, /** @type {Uint8Array} */ b) {
   return diff === 0;
 }
 
+/**
+ * Context handed to a room's {@link LinkPolicy} for every inbound and
+ * outbound peer link.
+ *
+ * @typedef {Object} LinkPolicyContext
+ * @property {string} remoteIdentityHash Hex truncated hash of the remote
+ *   peer's long-term identity. Cryptographically bound: on the initiator
+ *   side it comes from the peer's announce, on the responder side from the
+ *   signed identify handshake over the link.
+ * @property {string|null} remoteDestinationHash Hex destination hash of the
+ *   remote room destination, when known (initiator side).
+ * @property {boolean} initiator Whether this side initiated the link.
+ */
+
+/**
+ * Decides whether a peer link may carry room traffic. Called on both the
+ * initiator and responder sides once the remote identity is proven.
+ *
+ * @typedef {(context: LinkPolicyContext) => boolean | Promise<boolean>} LinkPolicy
+ */
+
 /**
  * @typedef {Object} RoomCallbacks
  * @property {(added: string[], removed: string[]) => void} onPeers
  *   Fired whenever peers are discovered or drop off. Ids are hex link_ids.
  * @property {(synced: boolean) => void} onSynced
  *   Fired when the room's overall sync state changes.
+ * @property {(refusals: Array<{ destinationHash: string | null, identityHash: string | null, initiator: boolean }>) => void} [onRefused]
+ *   Fired when a peer link was refused by the link policy. Apps can use this
+ *   to surface access requests (e.g. "peer X wants to join").
  */
 
 /**
@@ -61,6 +85,11 @@ export class Room {
    * @param {string} options.appName - Deterministic destination app-name for the room.
    * @param {number} options.maxConns
    * @param {number} options.announceIntervalMs
+   * @param {LinkPolicy | null} [options.linkPolicy] When set, peer links must prove
+   *   their identity (initiator runs the identify handshake) and pass the
+   *   policy before any room traffic flows; refused links are torn down.
+   * @param {number} [options.identifyTimeoutMs] How long the responder waits
+   *   for the initiator's identify handshake before refusing.
    * @param {RoomCallbacks} options.callbacks
    */
   constructor({
@@ -71,6 +100,8 @@ export class Room {
     appName,
     maxConns,
     announceIntervalMs,
+    linkPolicy,
+    identifyTimeoutMs = 10_000,
     callbacks,
   }) {
     this.doc = doc;
@@ -80,6 +111,8 @@ export class Room {
     this.appName = appName;
     this.maxConns = maxConns;
     this.announceIntervalMs = announceIntervalMs;
+    this.linkPolicy = linkPolicy ?? null;
+    this.identifyTimeoutMs = identifyTimeoutMs;
     this.callbacks = callbacks;
 
     /** @type {import("@reticulum/core").Destination|null} */
@@ -202,7 +235,34 @@ export class Room {
     // Glare avoidance: only the lexicographically smaller destination initiates.
     if (this.myHex > remoteHex) return;
 
+    // De-bounce before the policy runs: announces repeat, and a slow (e.g.
+    // interactive) policy must not let concurrent announces each open a Link.
     this.pendingInitiates.add(remoteHex);
+
+    // Link policy (initiator side): the announce cryptographically binds the
+    // remote identity, so the policy can run before any link is opened.
+    if (this.linkPolicy) {
+      const initiatorIdentityHash = toHex(
+        await Identity.truncatedHash(detail.identity.publicKey),
+      );
+      const allowed = await this.linkPolicy({
+        remoteIdentityHash: initiatorIdentityHash,
+        remoteDestinationHash: remoteHex,
+        initiator: true,
+      });
+      if (!allowed) {
+        this.pendingInitiates.delete(remoteHex);
+        this.callbacks.onRefused?.([
+          {
+            destinationHash: remoteHex,
+            identityHash: initiatorIdentityHash,
+            initiator: true,
+          },
+        ]);
+        return;
+      }
+    }
+
     try {
       const out = await Destination.OUT(
         this.appName,
@@ -215,6 +275,11 @@ export class Room {
         await link.teardown();
         return;
       }
+      // With a policy, prove our identity to the responder before any room
+      // traffic: their policy cannot evaluate us until we do
+      if (this.linkPolicy) {
+        await link.identify(this.identity);
+      }
       this.linkedDestHexes.add(remoteHex);
       this._registerPeer(link, detail.destinationHash);
     } catch {
@@ -226,7 +291,9 @@ export class Room {
   }
 
   /**
-   * Responder path: a peer is opening a Link to us. Accept it.
+   * Responder path: a peer is opening a Link to us. Accept it. With a link
+   * policy, the peer must prove its identity over the link (signed identify
+   * handshake) before the policy decides and any room traffic flows.
    * @param {Event} event
    */
   async _onLinkRequest(event) {
@@ -239,12 +306,58 @@ export class Room {
         await link.teardown();
         return;
       }
+      if (this.linkPolicy) {
+        const identityHash = await this._awaitIdentify(link);
+        if (!identityHash) {
+          // The peer never proved who they are: refuse without ceremony
+          await link.teardown();
+          this.callbacks.onRefused?.([
+            { destinationHash: null, identityHash: null, initiator: false },
+          ]);
+          return;
+        }
+        const allowed = await this.linkPolicy({
+          remoteIdentityHash: identityHash,
+          remoteDestinationHash: null,
+          initiator: false,
+        });
+        if (!allowed) {
+          await link.teardown();
+          this.callbacks.onRefused?.([
+            { destinationHash: null, identityHash, initiator: false },
+          ]);
+          return;
+        }
+      }
       this._registerPeer(link, null);
     } catch {
       // Handshake failed; nothing to clean up.
     }
   }
 
+  /**
+   * Waits for the initiator's signed identify handshake on this link.
+   *
+   * @param {import("@reticulum/core").Link} link
+   * @returns {Promise<string|null>} Hex remote identity hash, or null when
+   *   the peer did not identify within the timeout.
+   */
+  _awaitIdentify(link) {
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        link.removeEventListener("identify", onIdentify);
+        resolve(null);
+      }, this.identifyTimeoutMs);
+      const onIdentify = (/** @type {Event} */ event) => {
+        clearTimeout(timer);
+        const detail = /** @type {any} */ (event).detail;
+        const identity = detail?.identity;
+        resolve(identity ? toHex(identity.getSalt()) : null);
+      };
+      link.addEventListener("identify", onIdentify, { once: true });
+    });
+  }
+
   /**
    * Registers a newly active peer and kicks off the Yjs sync handshake
    * (syncStep1 + local awareness), mirroring y-webrtc's peer-on-connect path.

package/test/acl.test.js

@@ -0,0 +1,84 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { Identity, toHex } from "@reticulum/core";
+import * as Y from "yjs";
+import { ReticulumProvider } from "../src/index.js";
+import { nudgeAnnounce } from "./loopback.js";
+
+const ROOM = "y-reticulum-acl-smoke";
+
+/** Polls `cond()` every 50ms until true, rejecting after `timeoutMs`. */
+function waitFor(cond, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const deadline = Date.now() + timeoutMs;
+    const tick = () => {
+      if (cond()) return resolve(undefined);
+      if (Date.now() >= deadline) return reject(new Error("waitFor timed out"));
+      setTimeout(tick, 50);
+    };
+    tick();
+  });
+}
+
+test("link policy gates sync: granted peers sync, refused peers do not", {
+  timeout: 30000,
+}, async () => {
+  const { makeLoopback } = await import("./loopback.js");
+  const { rnsA, rnsB, close } = await makeLoopback();
+  const docA = new Y.Doc();
+  const docB = new Y.Doc();
+  const idA = await Identity.generate();
+  const idB = await Identity.generate();
+  const hashA = toHex(await Identity.truncatedHash(await idA.getPublicKey()));
+  const hashB = toHex(await Identity.truncatedHash(await idB.getPublicKey()));
+
+  // A grants itself (owner) and nobody else: B must be refused
+  const granted = new Set([hashA]);
+  /** @type {any[]} */
+  const refusals = [];
+  const providerA = new ReticulumProvider(ROOM, docA, {
+    reticulum: rnsA,
+    identity: idA,
+    linkPolicy: ({ remoteIdentityHash }) => granted.has(remoteIdentityHash),
+  });
+  providerA.on("refused", (/** @type {any} */ e) => {
+    refusals.push(...e.refusals);
+  });
+  const providerB = new ReticulumProvider(ROOM, docB, {
+    reticulum: rnsB,
+    identity: idB,
+    linkPolicy: () => true,
+  });
+
+  await providerA.connect();
+  await providerB.connect();
+  await nudgeAnnounce(providerA, providerB);
+
+  // B's edit must NOT reach A while B is ungranted (either direction of the
+  // link was refused)
+  docB.getMap("doc").set("intruder", "yes");
+  await new Promise((resolve) => setTimeout(resolve, 1500));
+  assert.equal(
+    docA.getMap("doc").get("intruder"),
+    undefined,
+    "ungranted peer's data never arrives",
+  );
+
+  // The owner sees the refusal with B's identity hash: a join request
+  await waitFor(() => refusals.some((r) => r.identityHash === hashB), 10000);
+
+  // Owner grants B; the next announce cycle connects them
+  granted.add(hashB);
+  await nudgeAnnounce(providerA, providerB);
+  await waitFor(() => docA.getMap("doc").get("intruder") === "yes", 15000);
+  assert.equal(
+    docA.getMap("doc").get("intruder"),
+    "yes",
+    "granted peer's data now syncs",
+  );
+
+  await providerA.destroy().catch(() => {});
+  await providerB.destroy().catch(() => {});
+  await close();
+});