@freqhole/haruspex 0.0.0

package/dist/knock/pending-checker.test.js

@@ -0,0 +1,93 @@
+import { IDBFactory, IDBKeyRange } from "fake-indexeddb";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { checkPendingKnocks } from "./pending-checker.js";
+import { sendKnock } from "./requester.js";
+import { createIdbKnockStore } from "./store.js";
+beforeEach(() => {
+    globalThis.indexedDB = new IDBFactory();
+    globalThis.IDBKeyRange = IDBKeyRange;
+});
+function makeStore() {
+    return createIdbKnockStore({ databaseName: "app-db", storeName: "knocks" });
+}
+const ACCEPTED_PEER = "ab".repeat(32);
+const DENIED_PEER = "cd".repeat(32);
+const STILL_PENDING_PEER = "ef".repeat(32);
+const UNREACHABLE_PEER = "12".repeat(32);
+const browseScope = { kind: "browse" };
+describe("checkPendingKnocks", () => {
+    it("fires onAccepted for newly-accepted knocks and leaves others alone", async () => {
+        const store = makeStore();
+        const sendTransport = {
+            sendKnock: vi.fn().mockResolvedValue({ status: "pending" }),
+            checkKnockStatus: vi.fn(),
+        };
+        await sendKnock(store, sendTransport, ACCEPTED_PEER, { scope: browseScope });
+        await sendKnock(store, sendTransport, DENIED_PEER, { scope: browseScope });
+        await sendKnock(store, sendTransport, STILL_PENDING_PEER, { scope: browseScope });
+        await sendKnock(store, sendTransport, UNREACHABLE_PEER, { scope: browseScope });
+        const checkTransport = {
+            sendKnock: vi.fn(),
+            checkKnockStatus: vi.fn().mockImplementation((nodeId) => {
+                if (nodeId === ACCEPTED_PEER) {
+                    return Promise.resolve({ status: "accepted", grantedResourceIds: ["doc-1"] });
+                }
+                if (nodeId === DENIED_PEER)
+                    return Promise.resolve({ status: "denied" });
+                if (nodeId === STILL_PENDING_PEER)
+                    return Promise.resolve({ status: "pending" });
+                return Promise.reject(new Error("peer unreachable"));
+            }),
+        };
+        const onAccepted = vi.fn();
+        const onDenied = vi.fn();
+        await checkPendingKnocks({ store, transport: checkTransport, onAccepted, onDenied });
+        expect(onAccepted).toHaveBeenCalledTimes(1);
+        expect(onAccepted.mock.calls[0][0].nodeId).toBe(ACCEPTED_PEER);
+        expect(onDenied).toHaveBeenCalledTimes(1);
+        expect(onDenied.mock.calls[0][0].nodeId).toBe(DENIED_PEER);
+        const remainingPending = (await store.listPending()).map((r) => r.nodeId).sort();
+        expect(remainingPending.sort()).toEqual([STILL_PENDING_PEER, UNREACHABLE_PEER].sort());
+    });
+    it("ignores inbound pending knocks - only sweeps outbound ones", async () => {
+        const store = makeStore();
+        await store.createKnock({
+            nodeId: ACCEPTED_PEER,
+            direction: "inbound",
+            scope: browseScope,
+        });
+        const transport = {
+            sendKnock: vi.fn(),
+            checkKnockStatus: vi.fn().mockResolvedValue({ status: "accepted" }),
+        };
+        const onAccepted = vi.fn();
+        await checkPendingKnocks({ store, transport, onAccepted });
+        expect(onAccepted).not.toHaveBeenCalled();
+        expect(transport.checkKnockStatus).not.toHaveBeenCalled();
+    });
+    it("does nothing when there are no pending knocks", async () => {
+        const store = makeStore();
+        const transport = {
+            sendKnock: vi.fn(),
+            checkKnockStatus: vi.fn(),
+        };
+        const onAccepted = vi.fn();
+        await checkPendingKnocks({ store, transport, onAccepted });
+        expect(onAccepted).not.toHaveBeenCalled();
+    });
+    it("works without an onDenied callback", async () => {
+        const store = makeStore();
+        const sendTransport = {
+            sendKnock: vi.fn().mockResolvedValue({ status: "pending" }),
+            checkKnockStatus: vi.fn(),
+        };
+        await sendKnock(store, sendTransport, DENIED_PEER, { scope: browseScope });
+        const transport = {
+            sendKnock: vi.fn(),
+            checkKnockStatus: vi.fn().mockResolvedValue({ status: "denied" }),
+        };
+        const onAccepted = vi.fn();
+        await expect(checkPendingKnocks({ store, transport, onAccepted })).resolves.toBeUndefined();
+        expect(onAccepted).not.toHaveBeenCalled();
+    });
+});

package/dist/knock/requester.d.ts

@@ -0,0 +1,26 @@
+import type { KnockRecord, KnockRequest, KnockStore, KnockTransport } from "./types.js";
+export interface CheckKnockStatusOptions {
+    /** additional attempts after the first, each with exponential backoff.
+     *  default 0 (a single attempt, no retry). */
+    retries?: number;
+    /** base backoff in ms; doubles each retry. default 1000. */
+    backoffMs?: number;
+    /** injectable delay, overridable in tests. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * send a fresh knock: creates the outbound record (enforcing the dedup
+ * rule - throws KnockConflictError if one is already pending for this node
+ * id + scope) and calls the transport once. if the transport call itself
+ * fails (peer offline, network error), the record is left pending for a
+ * later checkKnockStatus retry rather than surfacing the network error to
+ * the caller - only the initial dedup conflict is worth failing loudly on.
+ */
+export declare function sendKnock(store: KnockStore, transport: KnockTransport, nodeId: string, request: KnockRequest): Promise<KnockRecord>;
+/**
+ * re-check status for a previously-sent knock. retries with exponential
+ * backoff on transport failure (the peer may be transiently unreachable);
+ * the last error is thrown once retries are exhausted.
+ */
+export declare function checkKnockStatus(store: KnockStore, transport: KnockTransport, knockId: string, options?: CheckKnockStatusOptions): Promise<KnockRecord>;
+//# sourceMappingURL=requester.d.ts.map

package/dist/knock/requester.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requester.d.ts","sourceRoot":"","sources":["../../src/knock/requester.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EAEZ,UAAU,EACV,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,uBAAuB;IACtC;kDAC8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,UAAU,EACjB,SAAS,EAAE,cAAc,EACzB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,WAAW,CAAC,CActB;AAMD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,UAAU,EACjB,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,WAAW,CAAC,CA0BtB"}

package/dist/knock/requester.js

@@ -0,0 +1,72 @@
+// requester-side operations: sending a knock and re-checking its status.
+/**
+ * send a fresh knock: creates the outbound record (enforcing the dedup
+ * rule - throws KnockConflictError if one is already pending for this node
+ * id + scope) and calls the transport once. if the transport call itself
+ * fails (peer offline, network error), the record is left pending for a
+ * later checkKnockStatus retry rather than surfacing the network error to
+ * the caller - only the initial dedup conflict is worth failing loudly on.
+ */
+export async function sendKnock(store, transport, nodeId, request) {
+    const record = await store.createKnock({
+        nodeId,
+        direction: "outbound",
+        scope: request.scope,
+        message: request.message,
+    });
+    try {
+        const reply = await transport.sendKnock(nodeId, request);
+        return await applyStatusReply(store, record, reply);
+    }
+    catch {
+        return record;
+    }
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * re-check status for a previously-sent knock. retries with exponential
+ * backoff on transport failure (the peer may be transiently unreachable);
+ * the last error is thrown once retries are exhausted.
+ */
+export async function checkKnockStatus(store, transport, knockId, options = {}) {
+    const record = await store.getKnock(knockId);
+    if (!record) {
+        throw new Error(`knock ${knockId} not found`);
+    }
+    const retries = options.retries ?? 0;
+    const backoffMs = options.backoffMs ?? 1000;
+    const sleep = options.sleep ?? defaultSleep;
+    let lastError;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            const reply = await transport.checkKnockStatus(record.nodeId, {
+                scope: record.scope,
+                message: record.message,
+            });
+            return await applyStatusReply(store, record, reply);
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt < retries) {
+                await sleep(backoffMs * 2 ** attempt);
+            }
+        }
+    }
+    throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
+/**
+ * persist a status reply against a record, appending a decision only when
+ * the reply actually resolves the knock (accepted/denied) - a "still
+ * pending" reply leaves the record and its audit log untouched.
+ */
+async function applyStatusReply(store, record, reply) {
+    if (reply.status === "pending")
+        return record;
+    return store.recordDecision(record.id, {
+        byNodeId: record.nodeId,
+        outcome: reply.status,
+        at: Date.now(),
+    }, { grantedResourceIds: reply.grantedResourceIds });
+}

package/dist/knock/requester.test.d.ts

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

package/dist/knock/requester.test.d.ts.map

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

package/dist/knock/requester.test.js

@@ -0,0 +1,108 @@
+import { IDBFactory, IDBKeyRange } from "fake-indexeddb";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { checkKnockStatus, sendKnock } from "./requester.js";
+import { createIdbKnockStore } from "./store.js";
+beforeEach(() => {
+    globalThis.indexedDB = new IDBFactory();
+    globalThis.IDBKeyRange = IDBKeyRange;
+});
+function makeStore() {
+    return createIdbKnockStore({ databaseName: "app-db", storeName: "knocks" });
+}
+const NODE_ID = "ab".repeat(32);
+const browseScope = { kind: "browse" };
+function makeTransport(overrides = {}) {
+    return {
+        sendKnock: vi.fn().mockResolvedValue({ status: "pending" }),
+        checkKnockStatus: vi.fn().mockResolvedValue({ status: "pending" }),
+        ...overrides,
+    };
+}
+describe("sendKnock", () => {
+    it("creates an outbound record and applies the transport's reply", async () => {
+        const store = makeStore();
+        const transport = makeTransport({
+            sendKnock: vi.fn().mockResolvedValue({ status: "accepted", grantedResourceIds: ["doc-1"] }),
+        });
+        const record = await sendKnock(store, transport, NODE_ID, {
+            scope: browseScope,
+            message: "hi",
+        });
+        expect(record.direction).toBe("outbound");
+        expect(record.status).toBe("accepted");
+        expect(record.grantedResourceIds).toEqual(["doc-1"]);
+        expect(transport.sendKnock).toHaveBeenCalledWith(NODE_ID, {
+            scope: browseScope,
+            message: "hi",
+        });
+    });
+    it("leaves the record pending when the transport reply is still pending", async () => {
+        const store = makeStore();
+        const transport = makeTransport();
+        const record = await sendKnock(store, transport, NODE_ID, { scope: browseScope });
+        expect(record.status).toBe("pending");
+        expect(record.decisions).toEqual([]);
+    });
+    it("leaves the record pending when the transport call throws", async () => {
+        const store = makeStore();
+        const transport = makeTransport({
+            sendKnock: vi.fn().mockRejectedValue(new Error("peer unreachable")),
+        });
+        const record = await sendKnock(store, transport, NODE_ID, { scope: browseScope });
+        expect(record.status).toBe("pending");
+    });
+    it("propagates the dedup conflict when a pending knock already exists", async () => {
+        const store = makeStore();
+        const transport = makeTransport();
+        await sendKnock(store, transport, NODE_ID, { scope: browseScope });
+        await expect(sendKnock(store, transport, NODE_ID, { scope: browseScope })).rejects.toThrow();
+    });
+});
+describe("checkKnockStatus", () => {
+    it("resolves the record when the transport reports a decision", async () => {
+        const store = makeStore();
+        const transport = makeTransport();
+        const record = await sendKnock(store, transport, NODE_ID, { scope: browseScope });
+        transport.checkKnockStatus = vi.fn().mockResolvedValue({ status: "denied" });
+        const updated = await checkKnockStatus(store, transport, record.id);
+        expect(updated.status).toBe("denied");
+        expect(updated.decisions).toHaveLength(1);
+    });
+    it("throws for an unknown knock id", async () => {
+        const store = makeStore();
+        const transport = makeTransport();
+        await expect(checkKnockStatus(store, transport, "nope")).rejects.toThrow();
+    });
+    it("retries with backoff and succeeds before exhausting retries", async () => {
+        const store = makeStore();
+        const transport = makeTransport();
+        const record = await sendKnock(store, transport, NODE_ID, { scope: browseScope });
+        let calls = 0;
+        transport.checkKnockStatus = vi.fn().mockImplementation(() => {
+            calls += 1;
+            if (calls < 3)
+                return Promise.reject(new Error("unreachable"));
+            return Promise.resolve({ status: "accepted" });
+        });
+        const sleep = vi.fn().mockResolvedValue(undefined);
+        const updated = await checkKnockStatus(store, transport, record.id, {
+            retries: 3,
+            backoffMs: 10,
+            sleep,
+        });
+        expect(updated.status).toBe("accepted");
+        expect(calls).toBe(3);
+        expect(sleep).toHaveBeenCalledTimes(2);
+        expect(sleep).toHaveBeenNthCalledWith(1, 10);
+        expect(sleep).toHaveBeenNthCalledWith(2, 20);
+    });
+    it("throws the last error once retries are exhausted", async () => {
+        const store = makeStore();
+        const transport = makeTransport();
+        const record = await sendKnock(store, transport, NODE_ID, { scope: browseScope });
+        transport.checkKnockStatus = vi.fn().mockRejectedValue(new Error("still unreachable"));
+        const sleep = vi.fn().mockResolvedValue(undefined);
+        await expect(checkKnockStatus(store, transport, record.id, { retries: 2, backoffMs: 5, sleep })).rejects.toThrow("still unreachable");
+        expect(transport.checkKnockStatus).toHaveBeenCalledTimes(3);
+    });
+});

package/dist/knock/responder.d.ts

@@ -0,0 +1,13 @@
+import type { KnockPolicy, KnockRecord, KnockStore } from "./types.js";
+/**
+ * accept an inbound knock: runs the injected policy and records its result
+ * as an accepted decision. `decidedBy` is the responder's own node id,
+ * recorded on the decision's audit entry.
+ */
+export declare function acceptKnock(store: KnockStore, knockId: string, policy: KnockPolicy, decidedBy: string): Promise<KnockRecord>;
+/**
+ * deny an inbound knock. no policy callback - denial has no side effect to
+ * inject.
+ */
+export declare function denyKnock(store: KnockStore, knockId: string, decidedBy: string): Promise<KnockRecord>;
+//# sourceMappingURL=responder.d.ts.map

package/dist/knock/responder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"responder.d.ts","sourceRoot":"","sources":["../../src/knock/responder.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvE;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,WAAW,EACnB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,WAAW,CAAC,CAgBtB;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,WAAW,CAAC,CAUtB"}

package/dist/knock/responder.js

@@ -0,0 +1,40 @@
+// responder-side operations: accepting or denying an inbound knock.
+//
+// the accept side effect (creating a user, granting a role, whatever
+// accepting a knock actually means for the app) is always the injected
+// `KnockPolicy` callback - this module only records the decision and
+// resolves the knock record's status, never performs an app-specific
+// effect itself.
+/**
+ * accept an inbound knock: runs the injected policy and records its result
+ * as an accepted decision. `decidedBy` is the responder's own node id,
+ * recorded on the decision's audit entry.
+ */
+export async function acceptKnock(store, knockId, policy, decidedBy) {
+    const record = await store.getKnock(knockId);
+    if (!record) {
+        throw new Error(`knock ${knockId} not found`);
+    }
+    const result = await policy(record);
+    return store.recordDecision(knockId, {
+        byNodeId: decidedBy,
+        outcome: "accepted",
+        grantedRole: result.grantedRole,
+        at: Date.now(),
+    }, { grantedResourceIds: result.grantedResourceIds });
+}
+/**
+ * deny an inbound knock. no policy callback - denial has no side effect to
+ * inject.
+ */
+export async function denyKnock(store, knockId, decidedBy) {
+    const record = await store.getKnock(knockId);
+    if (!record) {
+        throw new Error(`knock ${knockId} not found`);
+    }
+    return store.recordDecision(knockId, {
+        byNodeId: decidedBy,
+        outcome: "denied",
+        at: Date.now(),
+    });
+}

package/dist/knock/responder.test.d.ts

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

package/dist/knock/responder.test.d.ts.map

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

package/dist/knock/responder.test.js

@@ -0,0 +1,89 @@
+import { IDBFactory, IDBKeyRange } from "fake-indexeddb";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { acceptKnock, denyKnock } from "./responder.js";
+import { createIdbKnockStore } from "./store.js";
+beforeEach(() => {
+    globalThis.indexedDB = new IDBFactory();
+    globalThis.IDBKeyRange = IDBKeyRange;
+});
+function makeStore() {
+    return createIdbKnockStore({ databaseName: "app-db", storeName: "knocks" });
+}
+const REQUESTER_NODE_ID = "ab".repeat(32);
+const RESPONDER_NODE_ID = "cd".repeat(32);
+const browseScope = { kind: "browse" };
+describe("acceptKnock", () => {
+    it("runs the injected policy and records an accepted decision", async () => {
+        const store = makeStore();
+        const record = await store.createKnock({
+            nodeId: REQUESTER_NODE_ID,
+            direction: "inbound",
+            scope: browseScope,
+            message: "let me in",
+        });
+        const policy = vi.fn().mockResolvedValue({
+            grantedRole: "member",
+            grantedResourceIds: ["doc-1"],
+        });
+        const updated = await acceptKnock(store, record.id, policy, RESPONDER_NODE_ID);
+        expect(policy).toHaveBeenCalledWith(record);
+        expect(updated.status).toBe("accepted");
+        expect(updated.processedBy).toBe(RESPONDER_NODE_ID);
+        expect(updated.decisions).toEqual([
+            {
+                byNodeId: RESPONDER_NODE_ID,
+                outcome: "accepted",
+                grantedRole: "member",
+                at: updated.processedAt,
+            },
+        ]);
+        expect(updated.grantedResourceIds).toEqual(["doc-1"]);
+    });
+    it("supports a synchronous policy callback", async () => {
+        const store = makeStore();
+        const record = await store.createKnock({
+            nodeId: REQUESTER_NODE_ID,
+            direction: "inbound",
+            scope: browseScope,
+        });
+        const policy = () => ({ grantedRole: "viewer" });
+        const updated = await acceptKnock(store, record.id, policy, RESPONDER_NODE_ID);
+        expect(updated.status).toBe("accepted");
+        expect(updated.decisions[0].grantedRole).toBe("viewer");
+    });
+    it("throws for an unknown knock id", async () => {
+        const store = makeStore();
+        const policy = () => ({});
+        await expect(acceptKnock(store, "nope", policy, RESPONDER_NODE_ID)).rejects.toThrow();
+    });
+    it("propagates a policy rejection without recording a decision", async () => {
+        const store = makeStore();
+        const record = await store.createKnock({
+            nodeId: REQUESTER_NODE_ID,
+            direction: "inbound",
+            scope: browseScope,
+        });
+        const policy = vi.fn().mockRejectedValue(new Error("policy declined"));
+        await expect(acceptKnock(store, record.id, policy, RESPONDER_NODE_ID)).rejects.toThrow("policy declined");
+        expect((await store.getKnock(record.id))?.status).toBe("pending");
+    });
+});
+describe("denyKnock", () => {
+    it("records a denied decision with no granted role", async () => {
+        const store = makeStore();
+        const record = await store.createKnock({
+            nodeId: REQUESTER_NODE_ID,
+            direction: "inbound",
+            scope: browseScope,
+        });
+        const updated = await denyKnock(store, record.id, RESPONDER_NODE_ID);
+        expect(updated.status).toBe("denied");
+        expect(updated.decisions).toEqual([
+            { byNodeId: RESPONDER_NODE_ID, outcome: "denied", at: updated.processedAt },
+        ]);
+    });
+    it("throws for an unknown knock id", async () => {
+        const store = makeStore();
+        await expect(denyKnock(store, "nope", RESPONDER_NODE_ID)).rejects.toThrow();
+    });
+});

package/dist/knock/store.d.ts

@@ -0,0 +1,11 @@
+import type { KnockStore } from "./types.js";
+export interface KnockStoreOptions {
+    databaseName: string;
+    storeName: string;
+}
+/**
+ * an idb-backed KnockStore. database/store names are parameterized (see
+ * KnockStoreOptions) so an app can point this at its own existing tables.
+ */
+export declare function createIdbKnockStore(options: KnockStoreOptions): KnockStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/knock/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/knock/store.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAKV,UAAU,EACX,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AA4ED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAgJ1E"}