@freqhole/haruspex 0.0.0

package/dist/knock/store.js

@@ -0,0 +1,211 @@
+// idb-backed KnockStore.
+//
+// database + store names are parameterized (see KnockStoreOptions) rather
+// than hardcoded, so an app's existing knock table names can be pointed at
+// this store in place, without a browser-data migration - the same
+// `dbName` option pattern reliquary-ts's ./blobs subpath uses.
+import { KnockConflictError } from "./types.js";
+const NODE_ID_INDEX = "nodeId";
+const DEDUP_INDEX = "dedup";
+/**
+ * canonical rendering of a scope, used as the dedup index key. mirrors
+ * rust's dedup key exactly: it is keyed on the full scope value, so e.g.
+ * two account-scope knocks for different `requestedUsername`s do not dedup
+ * against each other.
+ */
+function scopeKey(scope) {
+    switch (scope.kind) {
+        case "account":
+            return `account:${scope.requestedUsername ?? ""}`;
+        case "browse":
+            return "browse";
+        case "resource":
+            return `resource:${scope.resourceId}:${scope.requestedRole ?? ""}`;
+    }
+}
+function toRow(record) {
+    return { ...record, scopeKey: scopeKey(record.scope) };
+}
+function fromRow(row) {
+    const { scopeKey: _scopeKey, ...record } = row;
+    return record;
+}
+function reqPromise(req) {
+    return new Promise((resolve, reject) => {
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error);
+    });
+}
+/**
+ * open the database, creating the store (and its indexes) on demand if
+ * this is the first time this database/store pair has been opened.
+ */
+function openDb(databaseName, storeName) {
+    return new Promise((resolve, reject) => {
+        const probe = indexedDB.open(databaseName);
+        probe.onsuccess = () => {
+            const db = probe.result;
+            if (db.objectStoreNames.contains(storeName)) {
+                resolve(db);
+                return;
+            }
+            const nextVersion = db.version + 1;
+            db.close();
+            const upgrade = indexedDB.open(databaseName, nextVersion);
+            upgrade.onupgradeneeded = () => {
+                const upgradeDb = upgrade.result;
+                if (!upgradeDb.objectStoreNames.contains(storeName)) {
+                    const store = upgradeDb.createObjectStore(storeName, { keyPath: "id" });
+                    store.createIndex(NODE_ID_INDEX, "nodeId", { unique: false });
+                    store.createIndex(DEDUP_INDEX, ["nodeId", "scopeKey", "status"], {
+                        unique: false,
+                    });
+                }
+            };
+            upgrade.onsuccess = () => resolve(upgrade.result);
+            upgrade.onerror = () => reject(upgrade.error);
+        };
+        probe.onerror = () => reject(probe.error);
+    });
+}
+/**
+ * an idb-backed KnockStore. database/store names are parameterized (see
+ * KnockStoreOptions) so an app can point this at its own existing tables.
+ */
+export function createIdbKnockStore(options) {
+    const { databaseName, storeName } = options;
+    return {
+        async createKnock(input) {
+            const db = await openDb(databaseName, storeName);
+            try {
+                const key = scopeKey(input.scope);
+                return await new Promise((resolve, reject) => {
+                    const tx = db.transaction(storeName, "readwrite");
+                    const store = tx.objectStore(storeName);
+                    const dedupIndex = store.index(DEDUP_INDEX);
+                    const range = IDBKeyRange.only([input.nodeId, key, "pending"]);
+                    const checkReq = dedupIndex.getAllKeys(range);
+                    checkReq.onerror = () => reject(checkReq.error);
+                    checkReq.onsuccess = () => {
+                        if (checkReq.result.length > 0) {
+                            reject(new KnockConflictError(input.nodeId, input.scope));
+                            tx.abort();
+                            return;
+                        }
+                        const record = {
+                            id: crypto.randomUUID(),
+                            nodeId: input.nodeId,
+                            direction: input.direction,
+                            scope: input.scope,
+                            message: input.message ?? "",
+                            status: "pending",
+                            createdAt: input.createdAt ?? Date.now(),
+                            decisions: [],
+                            ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
+                        };
+                        const putReq = store.put(toRow(record));
+                        putReq.onerror = () => reject(putReq.error);
+                        putReq.onsuccess = () => resolve(record);
+                    };
+                });
+            }
+            finally {
+                db.close();
+            }
+        },
+        async getKnock(id) {
+            const db = await openDb(databaseName, storeName);
+            try {
+                const tx = db.transaction(storeName, "readonly");
+                const row = (await reqPromise(tx.objectStore(storeName).get(id)));
+                return row ? fromRow(row) : null;
+            }
+            finally {
+                db.close();
+            }
+        },
+        async listPending() {
+            const db = await openDb(databaseName, storeName);
+            try {
+                const tx = db.transaction(storeName, "readonly");
+                const rows = (await reqPromise(tx.objectStore(storeName).getAll()));
+                return rows
+                    .filter((r) => r.status === "pending")
+                    .map(fromRow)
+                    .sort((a, b) => b.createdAt - a.createdAt);
+            }
+            finally {
+                db.close();
+            }
+        },
+        async listAll() {
+            const db = await openDb(databaseName, storeName);
+            try {
+                const tx = db.transaction(storeName, "readonly");
+                const rows = (await reqPromise(tx.objectStore(storeName).getAll()));
+                return rows.map(fromRow).sort((a, b) => b.createdAt - a.createdAt);
+            }
+            finally {
+                db.close();
+            }
+        },
+        async findByNodeId(nodeId) {
+            const db = await openDb(databaseName, storeName);
+            try {
+                const tx = db.transaction(storeName, "readonly");
+                const rows = (await reqPromise(tx.objectStore(storeName).index(NODE_ID_INDEX).getAll(nodeId)));
+                if (rows.length === 0)
+                    return null;
+                rows.sort((a, b) => b.createdAt - a.createdAt);
+                return fromRow(rows[0]);
+            }
+            finally {
+                db.close();
+            }
+        },
+        async recordDecision(id, decision, patch) {
+            const db = await openDb(databaseName, storeName);
+            try {
+                return await new Promise((resolve, reject) => {
+                    const tx = db.transaction(storeName, "readwrite");
+                    const store = tx.objectStore(storeName);
+                    const getReq = store.get(id);
+                    getReq.onerror = () => reject(getReq.error);
+                    getReq.onsuccess = () => {
+                        const row = getReq.result;
+                        if (!row) {
+                            reject(new Error(`knock ${id} not found`));
+                            tx.abort();
+                            return;
+                        }
+                        const record = fromRow(row);
+                        const updated = {
+                            ...record,
+                            status: decision.outcome,
+                            processedAt: decision.at,
+                            processedBy: decision.byNodeId,
+                            decisions: [...record.decisions, decision],
+                            grantedResourceIds: patch?.grantedResourceIds ?? record.grantedResourceIds,
+                        };
+                        const putReq = store.put(toRow(updated));
+                        putReq.onerror = () => reject(putReq.error);
+                        putReq.onsuccess = () => resolve(updated);
+                    };
+                });
+            }
+            finally {
+                db.close();
+            }
+        },
+        async deleteKnock(id) {
+            const db = await openDb(databaseName, storeName);
+            try {
+                const tx = db.transaction(storeName, "readwrite");
+                await reqPromise(tx.objectStore(storeName).delete(id));
+            }
+            finally {
+                db.close();
+            }
+        },
+    };
+}

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

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

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

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

package/dist/knock/store.test.js

@@ -0,0 +1,195 @@
+import { IDBFactory, IDBKeyRange } from "fake-indexeddb";
+import { beforeEach, describe, expect, it } from "vitest";
+import { createIdbKnockStore } from "./store.js";
+import { KnockConflictError } from "./types.js";
+beforeEach(() => {
+    globalThis.indexedDB = new IDBFactory();
+    globalThis.IDBKeyRange = IDBKeyRange;
+});
+const NODE_ID = "ab".repeat(32);
+const OTHER_NODE_ID = "cd".repeat(32);
+const browseScope = { kind: "browse" };
+describe("createIdbKnockStore", () => {
+    it("creates and round-trips a pending knock", async () => {
+        const store = createIdbKnockStore({ databaseName: "app-db", storeName: "knocks" });
+        const record = await store.createKnock({
+            nodeId: NODE_ID,
+            direction: "outbound",
+            scope: browseScope,
+            message: "let me in",
+        });
+        expect(record.status).toBe("pending");
+        expect(record.decisions).toEqual([]);
+        expect(await store.getKnock(record.id)).toEqual(record);
+    });
+    it("has no metadata field when none is supplied - non-breaking for existing callers", async () => {
+        const store = createIdbKnockStore({ databaseName: "app-db", storeName: "knocks" });
+        const record = await store.createKnock({
+            nodeId: NODE_ID,
+            direction: "outbound",
+            scope: browseScope,
+            message: "let me in",
+        });
+        expect(record.metadata).toBeUndefined();
+        expect(await store.getKnock(record.id)).toEqual(record);
+    });
+    it("round-trips an app-populated metadata bag", async () => {
+        const store = createIdbKnockStore({ databaseName: "app-db", storeName: "knocks" });
+        const metadata = { name: "alice", avatarColor: "#ff00ff" };
+        const record = await store.createKnock({
+            nodeId: NODE_ID,
+            direction: "inbound",
+            scope: browseScope,
+            message: "let me in",
+            metadata,
+        });
+        expect(record.metadata).toEqual(metadata);
+        expect((await store.getKnock(record.id))?.metadata).toEqual(metadata);
+    });
+    it("defaults message to an empty string and createdAt to now", async () => {
+        const store = createIdbKnockStore({ databaseName: "app-db", storeName: "knocks" });
+        const before = Date.now();
+        const record = await store.createKnock({
+            nodeId: NODE_ID,
+            direction: "inbound",
+            scope: browseScope,
+        });
+        expect(record.message).toBe("");
+        expect(record.createdAt).toBeGreaterThanOrEqual(before);
+    });
+    it("rejects a second pending knock for the same node id + scope", async () => {
+        const store = createIdbKnockStore({ databaseName: "app-db", storeName: "knocks" });
+        await store.createKnock({ nodeId: NODE_ID, direction: "outbound", scope: browseScope });
+        await expect(store.createKnock({ nodeId: NODE_ID, direction: "outbound", scope: browseScope })).rejects.toThrow(KnockConflictError);
+    });
+    it("allows a second pending knock for a different scope on the same node id", async () => {
+        const store = createIdbKnockStore({ databaseName: "app-db", storeName: "knocks" });
+        await store.createKnock({ nodeId: NODE_ID, direction: "outbound", scope: browseScope });
+        const resourceKnock = await store.createKnock({
+            nodeId: NODE_ID,
+            direction: "outbound",
+            scope: { kind: "resource", resourceId: "doc-1" },
+        });
+        expect(resourceKnock.status).toBe("pending");
+    });
+    it("allows a new knock once the prior one is no longer pending", async () => {
+        const store = createIdbKnockStore({ databaseName: "app-db", storeName: "knocks" });
+        const first = await store.createKnock({
+            nodeId: NODE_ID,
+            direction: "outbound",
+            scope: browseScope,
+        });
+        await store.recordDecision(first.id, { byNodeId: NODE_ID, outcome: "denied", at: Date.now() });
+        const second = await store.createKnock({
+            nodeId: NODE_ID,
+            direction: "outbound",
+            scope: browseScope,
+        });
+        expect(second.status).toBe("pending");
+        expect(second.id).not.toBe(first.id);
+    });
+    it("allows a new knock once the prior one is deleted", async () => {
+        const store = createIdbKnockStore({ databaseName: "app-db", storeName: "knocks" });
+        const first = await store.createKnock({
+            nodeId: NODE_ID,
+            direction: "outbound",
+            scope: browseScope,
+        });
+        await store.deleteKnock(first.id);
+        const second = await store.createKnock({
+            nodeId: NODE_ID,
+            direction: "outbound",
+            scope: browseScope,
+        });
+        expect(second.status).toBe("pending");
+        expect(await store.getKnock(first.id)).toBeNull();
+    });
+    it("listPending returns only pending records, newest first", async () => {
+        const store = createIdbKnockStore({ databaseName: "app-db", storeName: "knocks" });
+        const a = await store.createKnock({
+            nodeId: NODE_ID,
+            direction: "outbound",
+            scope: browseScope,
+            createdAt: 1000,
+        });
+        const b = await store.createKnock({
+            nodeId: OTHER_NODE_ID,
+            direction: "outbound",
+            scope: browseScope,
+            createdAt: 2000,
+        });
+        await store.recordDecision(a.id, { byNodeId: NODE_ID, outcome: "accepted", at: 3000 });
+        const pending = await store.listPending();
+        expect(pending.map((r) => r.id)).toEqual([b.id]);
+    });
+    it("listAll returns every record, newest first", async () => {
+        const store = createIdbKnockStore({ databaseName: "app-db", storeName: "knocks" });
+        const a = await store.createKnock({
+            nodeId: NODE_ID,
+            direction: "outbound",
+            scope: browseScope,
+            createdAt: 1000,
+        });
+        const b = await store.createKnock({
+            nodeId: OTHER_NODE_ID,
+            direction: "outbound",
+            scope: browseScope,
+            createdAt: 2000,
+        });
+        expect((await store.listAll()).map((r) => r.id)).toEqual([b.id, a.id]);
+    });
+    it("findByNodeId returns the most recent record for that node id", async () => {
+        const store = createIdbKnockStore({ databaseName: "app-db", storeName: "knocks" });
+        const first = await store.createKnock({
+            nodeId: NODE_ID,
+            direction: "outbound",
+            scope: browseScope,
+            createdAt: 1000,
+        });
+        await store.recordDecision(first.id, { byNodeId: NODE_ID, outcome: "denied", at: 1500 });
+        const second = await store.createKnock({
+            nodeId: NODE_ID,
+            direction: "outbound",
+            scope: browseScope,
+            createdAt: 2000,
+        });
+        const found = await store.findByNodeId(NODE_ID);
+        expect(found?.id).toBe(second.id);
+    });
+    it("findByNodeId returns null for an unknown node id", async () => {
+        const store = createIdbKnockStore({ databaseName: "app-db", storeName: "knocks" });
+        expect(await store.findByNodeId(NODE_ID)).toBeNull();
+    });
+    it("recordDecision appends to the audit log and resolves status", async () => {
+        const store = createIdbKnockStore({ databaseName: "app-db", storeName: "knocks" });
+        const record = await store.createKnock({
+            nodeId: NODE_ID,
+            direction: "inbound",
+            scope: browseScope,
+        });
+        const updated = await store.recordDecision(record.id, { byNodeId: OTHER_NODE_ID, outcome: "accepted", grantedRole: "member", at: 5000 }, { grantedResourceIds: ["doc-1", "doc-2"] });
+        expect(updated.status).toBe("accepted");
+        expect(updated.processedAt).toBe(5000);
+        expect(updated.processedBy).toBe(OTHER_NODE_ID);
+        expect(updated.decisions).toEqual([
+            { byNodeId: OTHER_NODE_ID, outcome: "accepted", grantedRole: "member", at: 5000 },
+        ]);
+        expect(updated.grantedResourceIds).toEqual(["doc-1", "doc-2"]);
+    });
+    it("recordDecision throws for an unknown id", async () => {
+        const store = createIdbKnockStore({ databaseName: "app-db", storeName: "knocks" });
+        await expect(store.recordDecision("nope", { byNodeId: NODE_ID, outcome: "denied", at: 0 })).rejects.toThrow();
+    });
+    it("uses parameterized database and store names", async () => {
+        const store = createIdbKnockStore({
+            databaseName: "playlistz-db",
+            storeName: "knocks",
+        });
+        await store.createKnock({ nodeId: NODE_ID, direction: "inbound", scope: browseScope });
+        const otherStore = createIdbKnockStore({
+            databaseName: "different-db",
+            storeName: "knocks",
+        });
+        expect(await otherStore.listAll()).toEqual([]);
+    });
+});

package/dist/knock/types.d.ts

@@ -0,0 +1,144 @@
+/** who initiated the knock: a peer knocking on us, or us knocking on a peer. */
+export type KnockDirection = "inbound" | "outbound";
+/** current resolution of a knock request. */
+export type KnockStatus = "pending" | "accepted" | "denied";
+/**
+ * what access is being requested. mirrors rust's `KnockScope` enum
+ * field-for-field so a knock raised on one side of the wire describes the
+ * same request shape on the other:
+ *   - account: acceptance creates or links a user identity
+ *   - browse: list access, no specific resource named
+ *   - resource: access to one named resource, with an optional requested role
+ */
+export type KnockScope = {
+    kind: "account";
+    requestedUsername?: string;
+} | {
+    kind: "browse";
+} | {
+    kind: "resource";
+    resourceId: string;
+    requestedRole?: string;
+};
+/** one responder decision, appended to a knock's audit log. */
+export interface KnockDecision {
+    /** node id of whoever made this decision (the responder). */
+    byNodeId: string;
+    outcome: Exclude<KnockStatus, "pending">;
+    grantedRole?: string;
+    /** unix epoch millis. */
+    at: number;
+}
+export interface KnockRecord {
+    id: string;
+    nodeId: string;
+    direction: KnockDirection;
+    scope: KnockScope;
+    message: string;
+    status: KnockStatus;
+    /** unix epoch millis. */
+    createdAt: number;
+    /** unix epoch millis of the most recent decision, if any. */
+    processedAt?: number;
+    processedBy?: string;
+    /** full decision audit trail - see KnockDecision. */
+    decisions: KnockDecision[];
+    /**
+     * resource ids granted alongside a decision, for the case where one
+     * knock can cover more than the single `resourceId` named in `scope`
+     * (e.g. a browse-scope knock accepted with access to several resources).
+     * rust's per-decision shape carries a single `grantedRole` and no id
+     * list - this field is a ts-side addition for that many-resource case,
+     * not a wire concept the two sides need to agree on byte-for-byte.
+     * settled: multi-resource grants are never carried on the wire decision
+     * message itself - they're delivered as grant-store writes plus the
+     * protocol's own `acl-change` message. this field is a local read-model
+     * convenience an app can populate from those grant writes, not
+     * something a transport implementation needs to fill in.
+     */
+    grantedResourceIds?: string[];
+    /**
+     * an opaque, app-populated json bag for data the wire message carries
+     * that this record has no dedicated field for (e.g. a sender's display
+     * name alongside their knock message). this package never reads or
+     * interprets its contents - it only persists and returns whatever the
+     * caller supplied at creation time.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * thrown by `KnockStore.createKnock` when an active (pending) knock already
+ * exists for this node id + scope - the dedup rule haruspex's sqlite store
+ * enforces with a partial unique index over (node_id, scope) where
+ * status = 'pending'.
+ */
+export declare class KnockConflictError extends Error {
+    readonly nodeId: string;
+    readonly scope: KnockScope;
+    constructor(nodeId: string, scope: KnockScope);
+}
+export interface CreateKnockInput {
+    nodeId: string;
+    direction: KnockDirection;
+    scope: KnockScope;
+    message?: string;
+    /** unix epoch millis; defaults to Date.now(). */
+    createdAt?: number;
+    /** stored and returned as-is, never interpreted - see KnockRecord.metadata. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * persistence for knock records. an idb-backed implementation is provided
+ * (see store.ts); apps may supply their own to match existing storage.
+ */
+export interface KnockStore {
+    /** enforces the dedup rule: one active (pending) knock per node id +
+     *  scope. throws KnockConflictError if one already exists. */
+    createKnock(input: CreateKnockInput): Promise<KnockRecord>;
+    getKnock(id: string): Promise<KnockRecord | null>;
+    /** all pending knock records, newest first. */
+    listPending(): Promise<KnockRecord[]>;
+    /** all knock records regardless of status, newest first. */
+    listAll(): Promise<KnockRecord[]>;
+    /** the most recent knock record for `nodeId`, regardless of status, or
+     *  null if this node id has never knocked. */
+    findByNodeId(nodeId: string): Promise<KnockRecord | null>;
+    /** appends a decision and resolves the record's status
+     *  (last-decision-wins, matching haruspex's sqlite store). */
+    recordDecision(id: string, decision: KnockDecision, patch?: {
+        grantedResourceIds?: string[];
+    }): Promise<KnockRecord>;
+    /** permanently deletes a knock record, freeing the node id + scope to
+     *  knock again (the dedup rule only covers pending rows). */
+    deleteKnock(id: string): Promise<void>;
+}
+/** what a knock requester sends, and what the responder answers with. */
+export interface KnockRequest {
+    scope: KnockScope;
+    message?: string;
+    requesterName?: string;
+}
+export interface KnockStatusReply {
+    status: KnockStatus;
+    grantedResourceIds?: string[];
+}
+/**
+ * the wire operations `sendKnock`/`checkKnockStatus` need - injected so
+ * this package never owns a transport. one call opens a knock, the other
+ * re-checks a knock already sent (a retry/poll path, never a fresh knock).
+ */
+export interface KnockTransport {
+    sendKnock(nodeId: string, request: KnockRequest): Promise<KnockStatusReply>;
+    checkKnockStatus(nodeId: string, request: KnockRequest): Promise<KnockStatusReply>;
+}
+export interface KnockPolicyResult {
+    grantedRole?: string;
+    grantedResourceIds?: string[];
+}
+/**
+ * app-injected side effect for accepting a knock - creating a user,
+ * granting a role, whatever the accept actually does. this package only
+ * manages the knock record's lifecycle, never these side effects.
+ */
+export type KnockPolicy = (record: KnockRecord) => Promise<KnockPolicyResult> | KnockPolicyResult;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/knock/types.ts"],"names":[],"mappings":"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"}

package/dist/knock/types.js

@@ -0,0 +1,26 @@
+// framework-free knock (access-request) state, mirroring haruspex's rust
+// KnockScope/KnockRecord shapes so both sides of a knock describe the same
+// request.
+//
+// this module owns the record shape and the store/transport contracts;
+// sending or checking a knock over any particular wire is the caller's
+// transport implementation to provide, and the accept side effect
+// (creating a user, granting a role, whatever accepting actually means for
+// the app) is always an injected policy callback - this package only
+// tracks the knock record's lifecycle, never those side effects.
+/**
+ * thrown by `KnockStore.createKnock` when an active (pending) knock already
+ * exists for this node id + scope - the dedup rule haruspex's sqlite store
+ * enforces with a partial unique index over (node_id, scope) where
+ * status = 'pending'.
+ */
+export class KnockConflictError extends Error {
+    nodeId;
+    scope;
+    constructor(nodeId, scope) {
+        super(`an active knock already exists for node ${nodeId} and this scope`);
+        this.nodeId = nodeId;
+        this.scope = scope;
+        this.name = "KnockConflictError";
+    }
+}

package/dist/permissions/access.d.ts

@@ -0,0 +1,54 @@
+import type { RoleHierarchy } from "./role-table.js";
+/**
+ * does `actualRole` have at least the privilege of `requiredRole`? lower
+ * hierarchy numbers are more privileged, so this holds when `actualRole`'s
+ * level is less than or equal to `requiredRole`'s.
+ */
+export declare function hasAtLeastRole<TRole extends string>(hierarchy: RoleHierarchy<TRole>, actualRole: TRole, requiredRole: TRole): boolean;
+/** is `userId` strictly the resource's owner? */
+export declare function isOwner(userId: string, ownerId: string | null): boolean;
+/**
+ * is `userId` the resource's owner, or does `actualRole` have at least
+ * `requiredRole`'s privilege? owner always passes regardless of role.
+ */
+export declare function canAccessOwnerOr<TRole extends string>(hierarchy: RoleHierarchy<TRole>, userId: string, ownerId: string | null, actualRole: TRole, requiredRole: TRole): boolean;
+/**
+ * a route-auth-shaped access rule: public (always allowed), authenticated
+ * (any signed-in caller), role (a minimum role), owner (strictly the
+ * resource's owner), or owner_or (owner, or a minimum role).
+ */
+export type AccessRule<TRole extends string> = {
+    type: "public";
+} | {
+    type: "authenticated";
+} | {
+    type: "role";
+    role: TRole;
+} | {
+    type: "owner";
+} | {
+    type: "owner_or";
+    role: TRole;
+};
+/** the caller context an `AccessRule` is evaluated against. */
+export interface AccessContext<TRole extends string> {
+    userRole: TRole | null;
+    userId: string | null;
+    ownerId: string | null;
+}
+/** evaluate any `AccessRule` against a caller context. */
+export declare function canAccess<TRole extends string>(hierarchy: RoleHierarchy<TRole>, rule: AccessRule<TRole>, ctx: AccessContext<TRole>): boolean;
+/** the bundle of role-hierarchy-bound checks `bindRoleHierarchy` produces. */
+export interface RoleChecks<TRole extends string> {
+    hasAtLeastRole: (actualRole: TRole, requiredRole: TRole) => boolean;
+    canAccessOwnerOr: (userId: string, ownerId: string | null, actualRole: TRole, requiredRole: TRole) => boolean;
+    isOwner: (userId: string, ownerId: string | null) => boolean;
+    canAccess: (rule: AccessRule<TRole>, ctx: AccessContext<TRole>) => boolean;
+}
+/**
+ * bind a role hierarchy once and get back plain functions that no longer
+ * need it threaded through every call - convenient for a caller that only
+ * ever checks against one hierarchy for its whole lifetime.
+ */
+export declare function bindRoleHierarchy<TRole extends string>(hierarchy: RoleHierarchy<TRole>): RoleChecks<TRole>;
+//# sourceMappingURL=access.d.ts.map

package/dist/permissions/access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../../src/permissions/access.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,SAAS,MAAM,EACjD,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,EAC/B,UAAU,EAAE,KAAK,EACjB,YAAY,EAAE,KAAK,GAClB,OAAO,CAET;AAED,iDAAiD;AACjD,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAEvE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,SAAS,MAAM,EACnD,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,EAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,UAAU,EAAE,KAAK,EACjB,YAAY,EAAE,KAAK,GAClB,OAAO,CAGT;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,KAAK,SAAS,MAAM,IACvC;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAEtC,+DAA+D;AAC/D,MAAM,WAAW,aAAa,CAAC,KAAK,SAAS,MAAM;IACjD,QAAQ,EAAE,KAAK,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,0DAA0D;AAC1D,wBAAgB,SAAS,CAAC,KAAK,SAAS,MAAM,EAC5C,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,EAC/B,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,EACvB,GAAG,EAAE,aAAa,CAAC,KAAK,CAAC,GACxB,OAAO,CAiBT;AAED,8EAA8E;AAC9E,MAAM,WAAW,UAAU,CAAC,KAAK,SAAS,MAAM;IAC9C,cAAc,EAAE,CAAC,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,KAAK,OAAO,CAAC;IACpE,gBAAgB,EAAE,CAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,UAAU,EAAE,KAAK,EACjB,YAAY,EAAE,KAAK,KAChB,OAAO,CAAC;IACb,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,KAAK,OAAO,CAAC;IAC7D,SAAS,EAAE,CAAC,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,aAAa,CAAC,KAAK,CAAC,KAAK,OAAO,CAAC;CAC5E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,SAAS,MAAM,EACpD,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,GAC9B,UAAU,CAAC,KAAK,CAAC,CAQnB"}