@freqhole/reliquary 0.0.0

package/dist/automerge/acl-filtering.d.ts

@@ -0,0 +1,87 @@
+import { NetworkAdapter, type DocumentId, type Message, type PeerId, type PeerMetadata } from "@automerge/automerge-repo";
+/**
+ * resolves the effective role a peer has on a given document, so the
+ * adapter can decide whether to strip that peer's changes. must be
+ * synchronous - it's called inline while handling an inbound message.
+ */
+export type RoleResolver<TRole> = (documentId: DocumentId, senderId: PeerId) => TRole;
+export interface AclFilteringOptions<TRole> {
+    /** looks up the role a peer has on a document. */
+    resolveRole: RoleResolver<TRole>;
+    /** returns true when a role may not write - its sync/request changes
+     *  get stripped. roles for which this returns false pass through
+     *  unchanged (e.g. members, admins, or any other writable role). */
+    isReadOnly(role: TRole): boolean;
+    /** optional logger hook, called once per message that actually had
+     *  changes stripped. defaults to a no-op. */
+    onStrip?(info: {
+        documentId: DocumentId;
+        senderId: PeerId;
+        changeCount: number;
+    }): void;
+}
+/**
+ * a NetworkAdapter that wraps another NetworkAdapter and strips CRDT
+ * changes out of read-only peers' inbound sync/request messages.
+ *
+ * everything else - connect/send/disconnect, peer-candidate/
+ * peer-disconnected/close events, and any message that isn't a
+ * sync/request carrying changes from a read-only peer - passes through
+ * completely unchanged, so this is a drop-in replacement for the wrapped
+ * adapter from automerge-repo's point of view.
+ */
+export declare class AclFilteringNetworkAdapter<TRole> extends NetworkAdapter {
+    private wrapped;
+    private options;
+    constructor(wrapped: NetworkAdapter, options: AclFilteringOptions<TRole>);
+    isReady(): boolean;
+    whenReady(): Promise<void>;
+    connect(peerId: PeerId, peerMetadata?: PeerMetadata): void;
+    send(message: Message): void;
+    disconnect(): void;
+    /**
+     * inspect an inbound message from the wrapped adapter. sync/request
+     * messages from a read-only peer that carry changes get those changes
+     * stripped (heads/need/have are preserved so the peer's own reads keep
+     * working); everything else is re-emitted untouched.
+     */
+    private handleMessage;
+}
+/**
+ * build an AclFilteringNetworkAdapter wrapping `wrapped`, stripping CRDT
+ * changes from any peer `options.isReadOnly` marks as read-only for the
+ * document a message targets.
+ */
+export declare function createAclFilteringAdapter<TRole>(wrapped: NetworkAdapter, options: AclFilteringOptions<TRole>): AclFilteringNetworkAdapter<TRole>;
+/**
+ * minimal shape this module needs from an automerge-repo `Repo` to build
+ * a handle-cache-backed role resolver, without depending on the `Repo`
+ * class's full type (which would pull automerge-repo's document-loading
+ * machinery into this module's public surface for no reason).
+ */
+export interface HandleLookup {
+    handles: Record<string, {
+        isReady(): boolean;
+        doc(): unknown;
+    } | undefined>;
+}
+/**
+ * build a `RoleResolver` backed by a repo's already-cached document
+ * handles.
+ *
+ * looks up the cached handle for `documentId` via `repo.handles` (a plain
+ * synchronous record the repo already knows about) and hands its current
+ * doc value to the caller-supplied `readRole` function - this
+ * deliberately avoids `repo.find()`, which can trigger a network fetch
+ * and has side effects (creating a new handle, marking it as requested
+ * from peers) that have no place in a message-filtering hot path. if the
+ * repo has never seen this document, or the cached handle isn't ready
+ * yet, there's nothing to check against, so this returns `defaultRole`.
+ *
+ * `readRole` owns all app-specific vocabulary: what shape the doc's acl
+ * data takes, how a raw value is validated, and what the fallback should
+ * be for a missing or invalid entry - this function only owns the
+ * handle-cache lookup mechanics.
+ */
+export declare function createHandleBasedRoleResolver<TRole>(repo: HandleLookup, readRole: (doc: unknown, senderId: PeerId) => TRole, defaultRole: TRole): RoleResolver<TRole>;
+//# sourceMappingURL=acl-filtering.d.ts.map

package/dist/automerge/acl-filtering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acl-filtering.d.ts","sourceRoot":"","sources":["../../src/automerge/acl-filtering.ts"],"names":[],"mappings":"AA8BA,OAAO,EACL,cAAc,EACd,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,MAAM,EACX,KAAK,YAAY,EAClB,MAAM,2BAA2B,CAAC;AAEnC;;;;GAIG;AACH,MAAM,MAAM,YAAY,CAAC,KAAK,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,KAAK,KAAK,CAAC;AAEtF,MAAM,WAAW,mBAAmB,CAAC,KAAK;IACxC,kDAAkD;IAClD,WAAW,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IACjC;;wEAEoE;IACpE,UAAU,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC;IACjC;iDAC6C;IAC7C,OAAO,CAAC,CAAC,IAAI,EAAE;QAAE,UAAU,EAAE,UAAU,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACzF;AAED;;;;;;;;;GASG;AACH,qBAAa,0BAA0B,CAAC,KAAK,CAAE,SAAQ,cAAc;IACnE,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,OAAO,CAA6B;gBAEhC,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,mBAAmB,CAAC,KAAK,CAAC;IAWxE,OAAO,IAAI,OAAO;IAIlB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAI1B,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI;IAM1D,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAI5B,UAAU,IAAI,IAAI;IAIlB;;;;;OAKG;IACH,OAAO,CAAC,aAAa;CAgCtB;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAC7C,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,mBAAmB,CAAC,KAAK,CAAC,GAClC,0BAA0B,CAAC,KAAK,CAAC,CAEnC;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,OAAO,IAAI,OAAO,CAAC;QAAC,GAAG,IAAI,OAAO,CAAA;KAAE,GAAG,SAAS,CAAC,CAAC;CAC7E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EACjD,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,KAAK,EACnD,WAAW,EAAE,KAAK,GACjB,YAAY,CAAC,KAAK,CAAC,CAQrB"}

package/dist/automerge/acl-filtering.js

@@ -0,0 +1,138 @@
+// ---------------------------------------------------------------------------
+// acl-filtering network adapter wrapper for automerge-repo
+//
+// enforces read-only access at the network boundary for peers whose role
+// on a document doesn't permit writes. automerge-repo's DocSynchronizer
+// calls Automerge.receiveSyncMessage() unconditionally for every inbound
+// "sync"/"request" message - there's no hook inside automerge-repo to
+// reject a peer's changes before they're applied to the local doc. this
+// wrapper sits in front of a real NetworkAdapter and strips any CRDT
+// changes carried by a read-only peer's sync/request messages before
+// automerge-repo ever sees them, while still letting "have"/"need"/"heads"
+// through so that peer keeps receiving updates normally.
+//
+// the role model itself (what roles exist, what document a role applies
+// to, how a role is stored) is left entirely to the caller: this module
+// only needs a synchronous function from (documentId, senderId) to some
+// role value, and a predicate over that role value saying whether it may
+// write. this keeps the module free of any particular app's resource/
+// subject/role vocabulary while still giving it the exact seam a
+// consuming app's own role model can implement.
+//
+// usage:
+//   const adapter = createAclFilteringAdapter(realAdapter, {
+//     resolveRole: myRoleResolver,
+//     isReadOnly: (role) => role === "viewer",
+//   });
+//   new Repo({ network: [adapter], ... });
+// ---------------------------------------------------------------------------
+import { decodeSyncMessage, encodeSyncMessage } from "@automerge/automerge";
+import { NetworkAdapter, } from "@automerge/automerge-repo";
+/**
+ * a NetworkAdapter that wraps another NetworkAdapter and strips CRDT
+ * changes out of read-only peers' inbound sync/request messages.
+ *
+ * everything else - connect/send/disconnect, peer-candidate/
+ * peer-disconnected/close events, and any message that isn't a
+ * sync/request carrying changes from a read-only peer - passes through
+ * completely unchanged, so this is a drop-in replacement for the wrapped
+ * adapter from automerge-repo's point of view.
+ */
+export class AclFilteringNetworkAdapter extends NetworkAdapter {
+    wrapped;
+    options;
+    constructor(wrapped, options) {
+        super();
+        this.wrapped = wrapped;
+        this.options = options;
+        this.wrapped.on("peer-candidate", (payload) => this.emit("peer-candidate", payload));
+        this.wrapped.on("peer-disconnected", (payload) => this.emit("peer-disconnected", payload));
+        this.wrapped.on("close", () => this.emit("close"));
+        this.wrapped.on("message", (message) => this.handleMessage(message));
+    }
+    isReady() {
+        return this.wrapped.isReady();
+    }
+    whenReady() {
+        return this.wrapped.whenReady();
+    }
+    connect(peerId, peerMetadata) {
+        this.peerId = peerId;
+        this.peerMetadata = peerMetadata;
+        this.wrapped.connect(peerId, peerMetadata);
+    }
+    send(message) {
+        this.wrapped.send(message);
+    }
+    disconnect() {
+        this.wrapped.disconnect();
+    }
+    /**
+     * inspect an inbound message from the wrapped adapter. sync/request
+     * messages from a read-only peer that carry changes get those changes
+     * stripped (heads/need/have are preserved so the peer's own reads keep
+     * working); everything else is re-emitted untouched.
+     */
+    handleMessage(message) {
+        if (message.type !== "sync" && message.type !== "request") {
+            this.emit("message", message);
+            return;
+        }
+        if (!message.documentId || !message.data) {
+            this.emit("message", message);
+            return;
+        }
+        const role = this.options.resolveRole(message.documentId, message.senderId);
+        if (!this.options.isReadOnly(role)) {
+            this.emit("message", message);
+            return;
+        }
+        const decoded = decodeSyncMessage(message.data);
+        if (decoded.changes.length === 0) {
+            this.emit("message", message);
+            return;
+        }
+        this.options.onStrip?.({
+            documentId: message.documentId,
+            senderId: message.senderId,
+            changeCount: decoded.changes.length,
+        });
+        const filtered = encodeSyncMessage({ ...decoded, changes: [] });
+        this.emit("message", { ...message, data: filtered });
+    }
+}
+/**
+ * build an AclFilteringNetworkAdapter wrapping `wrapped`, stripping CRDT
+ * changes from any peer `options.isReadOnly` marks as read-only for the
+ * document a message targets.
+ */
+export function createAclFilteringAdapter(wrapped, options) {
+    return new AclFilteringNetworkAdapter(wrapped, options);
+}
+/**
+ * build a `RoleResolver` backed by a repo's already-cached document
+ * handles.
+ *
+ * looks up the cached handle for `documentId` via `repo.handles` (a plain
+ * synchronous record the repo already knows about) and hands its current
+ * doc value to the caller-supplied `readRole` function - this
+ * deliberately avoids `repo.find()`, which can trigger a network fetch
+ * and has side effects (creating a new handle, marking it as requested
+ * from peers) that have no place in a message-filtering hot path. if the
+ * repo has never seen this document, or the cached handle isn't ready
+ * yet, there's nothing to check against, so this returns `defaultRole`.
+ *
+ * `readRole` owns all app-specific vocabulary: what shape the doc's acl
+ * data takes, how a raw value is validated, and what the fallback should
+ * be for a missing or invalid entry - this function only owns the
+ * handle-cache lookup mechanics.
+ */
+export function createHandleBasedRoleResolver(repo, readRole, defaultRole) {
+    return (documentId, senderId) => {
+        const handle = repo.handles[documentId];
+        if (!handle || !handle.isReady()) {
+            return defaultRole;
+        }
+        return readRole(handle.doc(), senderId);
+    };
+}

package/dist/automerge/acl-filtering.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=acl-filtering.test.d.ts.map

package/dist/automerge/acl-filtering.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acl-filtering.test.d.ts","sourceRoot":"","sources":["../../src/automerge/acl-filtering.test.ts"],"names":[],"mappings":""}

package/dist/automerge/acl-filtering.test.js

@@ -0,0 +1,302 @@
+// ---------------------------------------------------------------------------
+// unit tests for AclFilteringNetworkAdapter / createAclFilteringAdapter /
+// createHandleBasedRoleResolver
+// ---------------------------------------------------------------------------
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import * as Automerge from "@automerge/automerge";
+import { NetworkAdapter } from "@automerge/automerge-repo";
+import { AclFilteringNetworkAdapter, createAclFilteringAdapter, createHandleBasedRoleResolver, } from "./acl-filtering.js";
+// ---------------------------------------------------------------------------
+// mock: a minimal NetworkAdapter we can drive by hand and spy on.
+// ---------------------------------------------------------------------------
+class MockAdapter extends NetworkAdapter {
+    isReady = vi.fn(() => true);
+    whenReady = vi.fn(async () => { });
+    connect = vi.fn();
+    send = vi.fn();
+    disconnect = vi.fn();
+}
+const isReadOnlyRole = (role) => role === "reader";
+// ---------------------------------------------------------------------------
+// helpers: build real automerge sync messages so decode/encode round-trips
+// through genuine wasm data, not synthetic garbage bytes (which can hang
+// the wasm decoder instead of throwing).
+// ---------------------------------------------------------------------------
+const DOC_ID = "doc-1";
+const READER_ID = "reader-peer";
+const WRITER_ID = "writer-peer";
+const LOCAL_ID = "local-peer";
+/**
+ * run a two-doc sync handshake far enough that the final message from doc1
+ * to doc2 actually carries a change (automerge's first couple of sync
+ * messages are just heads/have/need - the change payload only shows up
+ * once both sides have exchanged state at least once).
+ */
+function buildSyncMessageWithChange() {
+    let doc1 = Automerge.from({ foo: "bar" });
+    let doc2 = Automerge.init();
+    let s1 = Automerge.initSyncState();
+    let s2 = Automerge.initSyncState();
+    const [ns1, msg1] = Automerge.generateSyncMessage(doc1, s1);
+    s1 = ns1;
+    [doc2, s2] = Automerge.receiveSyncMessage(doc2, s2, msg1);
+    const [ns2, msg2] = Automerge.generateSyncMessage(doc2, s2);
+    s2 = ns2;
+    [doc1, s1] = Automerge.receiveSyncMessage(doc1, s1, msg2);
+    const [, msg3] = Automerge.generateSyncMessage(doc1, s1);
+    return msg3;
+}
+function buildSyncMessageWithoutChange() {
+    const doc1 = Automerge.from({ foo: "bar" });
+    const s1 = Automerge.initSyncState();
+    const [, msg1] = Automerge.generateSyncMessage(doc1, s1);
+    return msg1;
+}
+function makeSyncMessage(data, senderId, type = "sync") {
+    return {
+        type,
+        senderId,
+        targetId: LOCAL_ID,
+        documentId: DOC_ID,
+        data,
+    };
+}
+describe("AclFilteringNetworkAdapter", () => {
+    let wrapped;
+    let options;
+    let adapter;
+    beforeEach(() => {
+        wrapped = new MockAdapter();
+        options = {
+            resolveRole: vi.fn(() => "writer"),
+            isReadOnly: isReadOnlyRole,
+        };
+        adapter = new AclFilteringNetworkAdapter(wrapped, options);
+    });
+    // -----------------------------------------------------------------------
+    // lifecycle proxying
+    // -----------------------------------------------------------------------
+    describe("lifecycle proxying", () => {
+        it("proxies connect() to the wrapped adapter", () => {
+            const meta = { isEphemeral: false };
+            adapter.connect(LOCAL_ID, meta);
+            expect(wrapped.connect).toHaveBeenCalledWith(LOCAL_ID, meta);
+            expect(adapter.peerId).toBe(LOCAL_ID);
+            expect(adapter.peerMetadata).toBe(meta);
+        });
+        it("proxies send() to the wrapped adapter unchanged", () => {
+            const message = makeSyncMessage(new Uint8Array([1, 2, 3]), WRITER_ID);
+            adapter.send(message);
+            expect(wrapped.send).toHaveBeenCalledWith(message);
+        });
+        it("proxies disconnect() to the wrapped adapter", () => {
+            adapter.disconnect();
+            expect(wrapped.disconnect).toHaveBeenCalled();
+        });
+        it("proxies isReady() and whenReady() to the wrapped adapter", async () => {
+            wrapped.isReady.mockReturnValue(false);
+            expect(adapter.isReady()).toBe(false);
+            wrapped.isReady.mockReturnValue(true);
+            expect(adapter.isReady()).toBe(true);
+            await adapter.whenReady();
+            expect(wrapped.whenReady).toHaveBeenCalled();
+        });
+    });
+    // -----------------------------------------------------------------------
+    // event re-emission
+    // -----------------------------------------------------------------------
+    describe("event re-emission", () => {
+        it("re-emits peer-candidate from the wrapped adapter unchanged", () => {
+            const listener = vi.fn();
+            adapter.on("peer-candidate", listener);
+            const payload = { peerId: WRITER_ID, peerMetadata: {} };
+            wrapped.emit("peer-candidate", payload);
+            expect(listener).toHaveBeenCalledWith(payload);
+        });
+        it("re-emits peer-disconnected from the wrapped adapter unchanged", () => {
+            const listener = vi.fn();
+            adapter.on("peer-disconnected", listener);
+            const payload = { peerId: WRITER_ID };
+            wrapped.emit("peer-disconnected", payload);
+            expect(listener).toHaveBeenCalledWith(payload);
+        });
+        it("re-emits close from the wrapped adapter", () => {
+            const listener = vi.fn();
+            adapter.on("close", listener);
+            wrapped.emit("close");
+            expect(listener).toHaveBeenCalled();
+        });
+    });
+    // -----------------------------------------------------------------------
+    // message filtering
+    // -----------------------------------------------------------------------
+    describe("message filtering", () => {
+        it("passes non-sync/request message types through completely unchanged", () => {
+            options = { resolveRole: vi.fn(() => "reader"), isReadOnly: isReadOnlyRole };
+            adapter = new AclFilteringNetworkAdapter(wrapped, options);
+            const listener = vi.fn();
+            adapter.on("message", listener);
+            const ephemeralMessage = {
+                type: "ephemeral",
+                senderId: READER_ID,
+                targetId: LOCAL_ID,
+                documentId: DOC_ID,
+                data: new Uint8Array([9, 9, 9]),
+            };
+            wrapped.emit("message", ephemeralMessage);
+            expect(listener).toHaveBeenCalledWith(ephemeralMessage);
+            expect(options.resolveRole).not.toHaveBeenCalled();
+        });
+        it("passes sync messages through unchanged for a writer sender", () => {
+            options = { resolveRole: vi.fn(() => "writer"), isReadOnly: isReadOnlyRole };
+            adapter = new AclFilteringNetworkAdapter(wrapped, options);
+            const listener = vi.fn();
+            adapter.on("message", listener);
+            const message = makeSyncMessage(buildSyncMessageWithChange(), WRITER_ID);
+            wrapped.emit("message", message);
+            expect(listener).toHaveBeenCalledWith(message);
+        });
+        it("passes sync messages through unchanged for an admin sender", () => {
+            options = { resolveRole: vi.fn(() => "admin"), isReadOnly: isReadOnlyRole };
+            adapter = new AclFilteringNetworkAdapter(wrapped, options);
+            const listener = vi.fn();
+            adapter.on("message", listener);
+            const message = makeSyncMessage(buildSyncMessageWithChange(), WRITER_ID);
+            wrapped.emit("message", message);
+            expect(listener).toHaveBeenCalledWith(message);
+        });
+        it("strips changes from a read-only sender's sync message, preserving heads/need/have", () => {
+            options = { resolveRole: vi.fn(() => "reader"), isReadOnly: isReadOnlyRole };
+            adapter = new AclFilteringNetworkAdapter(wrapped, options);
+            const listener = vi.fn();
+            adapter.on("message", listener);
+            const rawData = buildSyncMessageWithChange();
+            const originalDecoded = Automerge.decodeSyncMessage(rawData);
+            expect(originalDecoded.changes.length).toBeGreaterThan(0);
+            const message = makeSyncMessage(rawData, READER_ID);
+            wrapped.emit("message", message);
+            expect(listener).toHaveBeenCalledTimes(1);
+            const emitted = listener.mock.calls[0][0];
+            // not the same object/bytes as the original - it was re-encoded.
+            expect(emitted).not.toBe(message);
+            expect(emitted.data).not.toBe(rawData);
+            const filteredDecoded = Automerge.decodeSyncMessage(emitted.data);
+            expect(filteredDecoded.changes).toHaveLength(0);
+            expect(filteredDecoded.heads).toEqual(originalDecoded.heads);
+            expect(filteredDecoded.need).toEqual(originalDecoded.need);
+            expect(filteredDecoded.have).toEqual(originalDecoded.have);
+        });
+        it("strips changes from a read-only sender's request message the same way as sync", () => {
+            options = { resolveRole: vi.fn(() => "reader"), isReadOnly: isReadOnlyRole };
+            adapter = new AclFilteringNetworkAdapter(wrapped, options);
+            const listener = vi.fn();
+            adapter.on("message", listener);
+            const rawData = buildSyncMessageWithChange();
+            const message = makeSyncMessage(rawData, READER_ID, "request");
+            wrapped.emit("message", message);
+            const emitted = listener.mock.calls[0][0];
+            expect(Automerge.decodeSyncMessage(emitted.data).changes).toHaveLength(0);
+        });
+        it("passes a read-only sender's sync message through unchanged when it carries no changes", () => {
+            options = { resolveRole: vi.fn(() => "reader"), isReadOnly: isReadOnlyRole };
+            adapter = new AclFilteringNetworkAdapter(wrapped, options);
+            const listener = vi.fn();
+            adapter.on("message", listener);
+            const message = makeSyncMessage(buildSyncMessageWithoutChange(), READER_ID);
+            wrapped.emit("message", message);
+            expect(listener).toHaveBeenCalledWith(message);
+        });
+        it("passes messages through unchanged when documentId or data is missing", () => {
+            const listener = vi.fn();
+            adapter.on("message", listener);
+            const message = {
+                type: "sync",
+                senderId: READER_ID,
+                targetId: LOCAL_ID,
+            };
+            wrapped.emit("message", message);
+            expect(listener).toHaveBeenCalledWith(message);
+            expect(options.resolveRole).not.toHaveBeenCalled();
+        });
+        it("calls resolveRole with the message's documentId and senderId", () => {
+            const message = makeSyncMessage(buildSyncMessageWithChange(), WRITER_ID);
+            wrapped.emit("message", message);
+            expect(options.resolveRole).toHaveBeenCalledWith(DOC_ID, WRITER_ID);
+        });
+        it("calls onStrip with change count details when changes are stripped", () => {
+            const onStrip = vi.fn();
+            options = {
+                resolveRole: vi.fn(() => "reader"),
+                isReadOnly: isReadOnlyRole,
+                onStrip,
+            };
+            adapter = new AclFilteringNetworkAdapter(wrapped, options);
+            const message = makeSyncMessage(buildSyncMessageWithChange(), READER_ID);
+            wrapped.emit("message", message);
+            expect(onStrip).toHaveBeenCalledWith({
+                documentId: DOC_ID,
+                senderId: READER_ID,
+                changeCount: expect.any(Number),
+            });
+            expect(onStrip.mock.calls[0][0].changeCount).toBeGreaterThan(0);
+        });
+    });
+    // -----------------------------------------------------------------------
+    // createAclFilteringAdapter factory
+    // -----------------------------------------------------------------------
+    describe("createAclFilteringAdapter", () => {
+        it("builds an AclFilteringNetworkAdapter wrapping the given adapter", () => {
+            const built = createAclFilteringAdapter(wrapped, options);
+            expect(built).toBeInstanceOf(AclFilteringNetworkAdapter);
+            const listener = vi.fn();
+            built.on("message", listener);
+            const message = makeSyncMessage(buildSyncMessageWithChange(), WRITER_ID);
+            wrapped.emit("message", message);
+            expect(listener).toHaveBeenCalledWith(message);
+        });
+    });
+});
+// ---------------------------------------------------------------------------
+// createHandleBasedRoleResolver
+// ---------------------------------------------------------------------------
+describe("createHandleBasedRoleResolver", () => {
+    function makeFakeRepo(handles) {
+        return { handles };
+    }
+    it("defaults to the default role when the repo has no cached handle for the document", () => {
+        const repo = makeFakeRepo({});
+        const readRole = vi.fn(() => "writer");
+        const resolver = createHandleBasedRoleResolver(repo, readRole, "reader");
+        expect(resolver(DOC_ID, WRITER_ID)).toBe("reader");
+        expect(readRole).not.toHaveBeenCalled();
+    });
+    it("defaults to the default role when the cached handle isn't ready yet", () => {
+        const repo = makeFakeRepo({
+            [DOC_ID]: { isReady: () => false, doc: () => ({}) },
+        });
+        const readRole = vi.fn(() => "writer");
+        const resolver = createHandleBasedRoleResolver(repo, readRole, "reader");
+        expect(resolver(DOC_ID, WRITER_ID)).toBe("reader");
+        expect(readRole).not.toHaveBeenCalled();
+    });
+    it("delegates to readRole with the handle's current doc value once ready", () => {
+        const doc = { acl: { [WRITER_ID]: { role: "writer" } } };
+        const repo = makeFakeRepo({
+            [DOC_ID]: { isReady: () => true, doc: () => doc },
+        });
+        const readRole = vi.fn((d, senderId) => (d.acl?.[senderId]?.role ?? "reader"));
+        const resolver = createHandleBasedRoleResolver(repo, readRole, "reader");
+        expect(resolver(DOC_ID, WRITER_ID)).toBe("writer");
+        expect(readRole).toHaveBeenCalledWith(doc, WRITER_ID);
+    });
+    it("leaves all role-shape validation and fallback logic to readRole", () => {
+        const doc = { acl: { [WRITER_ID]: { role: "super-admin" } } };
+        const repo = makeFakeRepo({
+            [DOC_ID]: { isReady: () => true, doc: () => doc },
+        });
+        // readRole itself decides an unrecognized role value falls back to "reader"
+        const readRole = vi.fn(() => "reader");
+        const resolver = createHandleBasedRoleResolver(repo, readRole, "reader");
+        expect(resolver(DOC_ID, WRITER_ID)).toBe("reader");
+    });
+});

package/dist/automerge/index.d.ts

@@ -0,0 +1,5 @@
+export { IrohNetworkAdapter, SYNC_ALPN } from "./iroh-network-adapter.js";
+export type { BiStreamLike, ConnectionSummary, EndpointState, IrohNetworkAdapterOptions, MiddenStreamNode, } from "./types.js";
+export { AclFilteringNetworkAdapter, createAclFilteringAdapter, createHandleBasedRoleResolver, } from "./acl-filtering.js";
+export type { AclFilteringOptions, HandleLookup, RoleResolver } from "./acl-filtering.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/automerge/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/automerge/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC1E,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,yBAAyB,EACzB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,EACzB,6BAA6B,GAC9B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,mBAAmB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/automerge/index.js

@@ -0,0 +1,7 @@
+// entry point for the automerge subpath: iroh-transport NetworkAdapter for
+// automerge-repo plus the acl change-stripping wrapper mechanism. this is
+// one of two subpaths in this package allowed a framework-shaped peer
+// dependency (`@automerge/automerge-repo`); ./blobs, ./transfer, ./worker,
+// and ./utils must never import from here.
+export { IrohNetworkAdapter, SYNC_ALPN } from "./iroh-network-adapter.js";
+export { AclFilteringNetworkAdapter, createAclFilteringAdapter, createHandleBasedRoleResolver, } from "./acl-filtering.js";