permdock 0.0.0 → 0.1.0

package/dist/connection-JvqwHODC.js

@@ -0,0 +1,194 @@
+import { t as compact } from "./compact-y6vfu2_f.js";
+import { r as PermDockRevokedError } from "./errors-Iy71s7Oj.js";
+//#region src/server/connection.ts
+/** `setTimeout` stores delays in a signed 32-bit integer. */
+const MAX_DELAY = 2147483647;
+const REVOKED = Object.freeze({
+	outcome: "denied",
+	denials: Object.freeze([Object.freeze({
+		role: null,
+		reason: "no-grant",
+		detail: "connection-revoked"
+	})]),
+	alternatives: Object.freeze([])
+});
+function principalId(permdock) {
+	return permdock.subject.principal?.id;
+}
+function nextMembershipExpiry(permdock, now) {
+	let next;
+	for (const membership of permdock.memberships()) {
+		const at = membership.expiresAt;
+		if (at !== void 0 && at > now && (next === void 0 || at < next)) next = at;
+	}
+	return next;
+}
+async function loadData(data) {
+	if (data === void 0) return {
+		ok: true,
+		value: void 0
+	};
+	if (typeof data !== "function") return {
+		ok: true,
+		value: data
+	};
+	const loaded = await data();
+	return loaded === null || loaded === void 0 ? {
+		ok: false,
+		value: void 0
+	} : {
+		ok: true,
+		value: loaded
+	};
+}
+function matches(event, permdock, tenant) {
+	if (event.principal !== principalId(permdock)) return false;
+	const session = permdock.subject.session;
+	if (event.session !== void 0 && session !== void 0 && event.session !== session) return false;
+	return !(event.kind === "changed" && event.tenant !== void 0 && tenant !== void 0 && event.tenant !== tenant);
+}
+/** Opens a long-lived connection. Never throws; a failure aborts. */
+async function openConnection(input) {
+	const controller = new AbortController();
+	const timers = /* @__PURE__ */ new Set();
+	const decideOptions = compact({
+		source: "adapter",
+		adapter: input.adapter
+	});
+	let unsubscribe;
+	let closed = false;
+	let current;
+	let chain = Promise.resolve();
+	const clear = () => {
+		for (const timer of timers) clearTimeout(timer);
+		timers.clear();
+		unsubscribe?.();
+		unsubscribe = void 0;
+	};
+	const abort = (code, decision) => {
+		if (controller.signal.aborted) return;
+		clear();
+		controller.abort(new PermDockRevokedError(compact({
+			code,
+			permission: input.options.permission?.key,
+			decision
+		})));
+	};
+	const after = (ms, run) => {
+		const timer = setTimeout(() => {
+			timers.delete(timer);
+			run();
+		}, Math.max(0, Math.min(ms, MAX_DELAY)));
+		timers.add(timer);
+	};
+	/** `true` when `permdock` still holds the opening permission. */
+	const admits = async (permdock) => {
+		const { permission } = input.options;
+		if (permission === void 0) return true;
+		const loaded = await loadData(input.options.data);
+		if (!loaded.ok) {
+			abort("denied");
+			return false;
+		}
+		const decision = permdock.decide(permission, loaded.value, decideOptions);
+		if (decision.outcome !== "granted") {
+			abort("denied", decision);
+			return false;
+		}
+		return true;
+	};
+	let schedule;
+	const revalidate = () => {
+		chain = chain.then(async () => {
+			if (controller.signal.aborted || closed) return;
+			let next;
+			try {
+				next = await input.rebuild();
+			} catch {
+				abort("subject-changed");
+				return;
+			}
+			const id = principalId(next);
+			if (id === void 0 || current === void 0 || id !== principalId(current)) {
+				abort("subject-changed");
+				return;
+			}
+			if (!await admits(next)) return;
+			current = next;
+			for (const timer of timers) clearTimeout(timer);
+			timers.clear();
+			schedule?.(next);
+		}).catch(() => {
+			abort("subject-changed");
+		});
+	};
+	schedule = (permdock) => {
+		const now = Date.now() / 1e3;
+		const expiresAt = permdock.subject.expiresAt;
+		if (expiresAt !== void 0) {
+			if (expiresAt <= now) {
+				abort("expired");
+				return;
+			}
+			const wait = (expiresAt - now) * 1e3;
+			after(wait, () => {
+				if (wait > MAX_DELAY) {
+					schedule?.(current ?? permdock);
+					return;
+				}
+				abort("expired");
+			});
+		}
+		const membership = nextMembershipExpiry(permdock, now);
+		if (membership !== void 0) after((membership - now) * 1e3, revalidate);
+		const every = input.options.revalidate;
+		if (every !== void 0 && Number.isFinite(every) && every > 0) after(every, revalidate);
+	};
+	try {
+		current = await input.open();
+	} catch {
+		abort("denied");
+	}
+	if (current !== void 0 && !controller.signal.aborted && await admits(current)) {
+		schedule(current);
+		if (input.feed !== void 0 && !controller.signal.aborted) try {
+			unsubscribe = input.feed.subscribe((event) => {
+				if (current === void 0 || !matches(event, current, input.tenant)) return;
+				if (event.kind === "session-revoked") abort("session-revoked");
+				else revalidate();
+			});
+		} catch {
+			abort("expired");
+		}
+	}
+	const live = () => controller.signal.aborted || closed ? void 0 : current;
+	return Object.freeze({
+		get permdock() {
+			if (current === void 0) throw new PermDockRevokedError({ code: "denied" });
+			return current;
+		},
+		signal: controller.signal,
+		check(permission, data, checkOptions) {
+			const permdock = live();
+			if (permdock === void 0) return REVOKED;
+			return permdock.decide(permission, data, checkOptions?.trusted === true ? {
+				...decideOptions,
+				trusted: true
+			} : {
+				...decideOptions,
+				trusted: false,
+				boundary: "manual"
+			});
+		},
+		filter(permission, items) {
+			const permdock = live();
+			return permdock === void 0 ? [] : permdock.filter(permission, items, decideOptions);
+		},
+		close() {
+			closed = true;
+			clear();
+		}
+	});
+}
+//#endregion
+export { openConnection };

package/dist/context-CKEAabd7.js

@@ -0,0 +1,73 @@
+import { t as compact } from "./compact-y6vfu2_f.js";
+import { t as emptySnapshot } from "./from-snapshot-BMGnhmgv.js";
+import { t as createClientStore } from "./store-C6hFW6ta.js";
+import { t as isPromiseLike } from "./source-DoBBYJi2.js";
+import { getContext, onDestroy, setContext } from "svelte";
+import { toStore } from "svelte/store";
+//#region src/svelte/context.ts
+const permDockKey = Symbol("permdock");
+function isReadable(value) {
+	return typeof value === "object" && value !== null && "subscribe" in value && typeof value.subscribe === "function";
+}
+function reactiveSource(source) {
+	if (typeof source === "function") return toStore(source);
+	return isReadable(source) ? source : void 0;
+}
+/**
+* Builds the store; the returned `stop` ends the subscription to a reactive
+* snapshot source.
+*/
+function connectSvelteStore(options) {
+	const source = options.snapshot;
+	const promised = isPromiseLike(source);
+	const reactive = promised ? void 0 : reactiveSource(source);
+	let initial = emptySnapshot();
+	if (reactive !== void 0) reactive.subscribe((value) => {
+		initial = value;
+	})();
+	else if (!promised) initial = source;
+	const store = createClientStore(compact({
+		snapshot: initial,
+		endpoint: options.endpoint,
+		approvals: options.approvals,
+		tenant: options.tenant,
+		fetch: options.fetch,
+		headers: options.headers,
+		maxAge: options.maxAge,
+		verifier: options.verifier
+	}));
+	if (promised) {
+		store.follow(source);
+		return {
+			store,
+			stop: () => void 0
+		};
+	}
+	if (reactive === void 0) return {
+		store,
+		stop: () => void 0
+	};
+	let current = initial;
+	return {
+		store,
+		stop: reactive.subscribe((value) => {
+			if (value !== current) {
+				current = value;
+				store.replace(value);
+			}
+		})
+	};
+}
+function providePermDock(options) {
+	const { store, stop } = connectSvelteStore(options);
+	onDestroy(stop);
+	setContext(permDockKey, store);
+	return store;
+}
+function getStore() {
+	const store = getContext(permDockKey);
+	if (store === void 0) throw new Error("PermDock: stores require setPermDock.");
+	return store;
+}
+//#endregion
+export { providePermDock as n, getStore as t };

package/dist/context-gtAwAILx.js

@@ -0,0 +1,6 @@
+import { createContext } from "react";
+//#region src/react/context.ts
+const PermDockStoreContext = createContext(null);
+const PermDockSnapshotPromiseContext = createContext(null);
+//#endregion
+export { PermDockStoreContext as n, PermDockSnapshotPromiseContext as t };

package/dist/convex/index.d.ts

@@ -0,0 +1,40 @@
+import { C as Policy, E as PolicyVocabulary, Zt as PermDock, mr as Principal } from "../policy-CInmNGkM.js";
+import { d as Permission } from "../permissions-B4apnahQ.js";
+import { o as ProblemDetails, r as PermDockDeniedError } from "../errors-DbZ1YOnb.js";
+//#region src/convex/types.d.ts
+type ConvexCtxLike = {
+  readonly auth?: {
+    readonly getUserIdentity?: () => Promise<unknown>;
+  };
+  readonly db?: unknown;
+};
+type ConvexPermDockCtx<TCtx, V extends PolicyVocabulary = PolicyVocabulary> = TCtx & {
+  readonly permdock: PermDock<V>;
+};
+type ConvexSubject<TCtx, TUser = unknown> = (ctx: TCtx) => TUser | Promise<TUser>;
+type ConvexQueryBuilder = (definition: {
+  readonly args: Record<string, never>;
+  readonly handler: (ctx: ConvexCtxLike, args: Record<string, never>) => unknown;
+}) => unknown;
+type ConvexPermDockOptions<TCtx, TUser = unknown> = {
+  readonly subject: ConvexSubject<TCtx, TUser>;
+  readonly query?: ConvexQueryBuilder;
+};
+type ConvexHandler<TCtx, TArgs, TResult, V extends PolicyVocabulary = PolicyVocabulary> = (ctx: ConvexPermDockCtx<TCtx, V>, args: TArgs) => TResult | Promise<TResult>;
+type ConvexErrorData = ProblemDetails;
+type ConvexPermDock<TCtx, V extends PolicyVocabulary = PolicyVocabulary> = {
+  readonly withPermDock: <TArgs, TResult>(handler: ConvexHandler<TCtx, TArgs, TResult, V>) => (ctx: TCtx, args: TArgs) => Promise<TResult>;
+  readonly snapshotQuery: (options?: {
+    readonly include?: readonly Permission[];
+  }) => unknown;
+};
+//#endregion
+//#region src/convex/create.d.ts
+export declare class ConvexError extends Error {
+  override readonly name = "ConvexError";
+  readonly data: ReturnType<PermDockDeniedError["toProblemDetails"]>;
+  constructor(data: ReturnType<PermDockDeniedError["toProblemDetails"]>);
+}
+export declare function createPermDock<TCtx, TUser, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, options: ConvexPermDockOptions<TCtx, TUser>): ConvexPermDock<TCtx, V>;
+//#endregion
+export type { ConvexCtxLike, ConvexErrorData, ConvexHandler, ConvexPermDock, ConvexPermDockCtx, ConvexPermDockOptions, ConvexQueryBuilder, ConvexSubject };

package/dist/convex/index.js

@@ -0,0 +1,55 @@
+import { t as compact } from "../compact-y6vfu2_f.js";
+import { n as PermDockDeniedError, t as PermDockApprovalRequiredError } from "../errors-Iy71s7Oj.js";
+import { t as createPermDock$1 } from "../permdock-yoZ7EjxX.js";
+//#region src/convex/create.ts
+var ConvexError = class extends Error {
+	name = "ConvexError";
+	data;
+	constructor(data) {
+		super(data.detail);
+		this.data = data;
+	}
+};
+function toConvexError(error) {
+	if (error instanceof PermDockDeniedError || error instanceof PermDockApprovalRequiredError) return new ConvexError(error.toProblemDetails());
+	return error;
+}
+function createPermDock(policy, options) {
+	const withPermDock = (handler) => {
+		return async (ctx, args) => {
+			let user = null;
+			try {
+				user = await options.subject(ctx);
+			} catch {
+				user = null;
+			}
+			const permdock = await createPermDock$1(policy, user);
+			const next = {
+				...ctx,
+				permdock
+			};
+			try {
+				return await handler(next, args);
+			} catch (error) {
+				throw toConvexError(error);
+			}
+		};
+	};
+	const snapshotQuery = (snapshotOptions) => {
+		const handler = withPermDock((ctx, args) => {
+			return Promise.resolve(ctx.permdock.snapshot(compact({ include: snapshotOptions?.include })));
+		});
+		const definition = {
+			args: {},
+			handler: (ctx, args) => handler(ctx, args)
+		};
+		if (options.query !== void 0) return options.query(definition);
+		return definition;
+	};
+	return {
+		withPermDock,
+		snapshotQuery
+	};
+}
+//#endregion
+export { ConvexError, createPermDock };

package/dist/create-BKF3dgFk.d.ts

@@ -0,0 +1,162 @@
+import { $ as DecisionSink, C as Policy, E as PolicyVocabulary, Mn as Decision, Zt as PermDock, at as LimitStore, ct as MembershipSource, fr as JsonWebKeyLike, ft as RelationSource, hr as Subject, ir as Actor, mr as Principal, pt as RoleSource, sn as PolicySource, tt as EntitlementSource, xt as SnapshotSource } from "./policy-CInmNGkM.js";
+import { d as Permission } from "./permissions-B4apnahQ.js";
+import { f as ApprovalStore } from "./types-B8w5PFtS.js";
+import { t as ApprovalHint } from "./errors-DbZ1YOnb.js";
+import { n as RevocationFeed } from "./revocations-Cy06JNx2.js";
+import { r as PdpFactory } from "./types-BvBk1wgn.js";
+//#region src/server/connection.d.ts
+type ConnectionData<T> = T | (() => T | null | undefined | Promise<T | null | undefined>);
+type ConnectionOptions<T = unknown> = {
+  /** The permission the stream or socket is opened for; re-checked after every revalidation. */
+  readonly permission?: Permission;
+  /** The row for `permission`, or a loader re-run on every revalidation. */
+  readonly data?: ConnectionData<T>;
+  /** Milliseconds between periodic revalidations; off by default. */
+  readonly revalidate?: number;
+};
+type Connection = {
+  /** The current instance; replaced, never mutated, after a revalidation. */
+  readonly permdock: PermDock;
+  /** Aborts with a `PermDockRevokedError` when the connection must end. */
+  readonly signal: AbortSignal;
+  /**
+   * Per-message decision. Data is validated against the resource schema
+   * first unless `{ trusted: true }` marks it as a row the server loaded.
+   */
+  readonly check: (permission: Permission, data?: unknown, options?: {
+    readonly trusted?: boolean;
+  }) => Decision;
+  readonly filter: <T>(permission: Permission<string, T, "instance">, items: readonly T[]) => T[];
+  /** Stops timers and the feed subscription. Call it when the transport closes. */
+  readonly close: () => void;
+};
+//#endregion
+//#region src/server/web-bot-auth.d.ts
+type WebBotAuthJwk = JsonWebKeyLike & {
+  readonly kid?: string;
+  readonly crv?: string;
+};
+type WebBotAuthKeyLookup = (input: {
+  readonly request: Request;
+  readonly keyid: string;
+  readonly agent: string | undefined;
+}) => WebBotAuthJwk | undefined | Promise<WebBotAuthJwk | undefined>;
+type WebBotAuthKeys = {
+  readonly lookup: WebBotAuthKeyLookup;
+};
+type WebBotAuthOptions = {
+  readonly verify?: boolean;
+  readonly keys: WebBotAuthKeys | WebBotAuthKeyLookup;
+  readonly required?: boolean;
+  readonly maxAge?: number;
+  /** Unix seconds; defaults to the system clock. */
+  readonly now?: () => number;
+};
+/**
+ * An adapter's `webBotAuth` option: `(request) => verifyWebBotAuth(request, options)`,
+ * so an app without it does not bundle RFC 9421 verification.
+ */
+type WebBotAuthVerifier = (request: Request) => Promise<Actor | undefined>;
+type DiscoverViaSignatureAgentOptions = {
+  readonly allow: readonly string[];
+  readonly fetch?: typeof fetch;
+};
+declare class InvalidSignatureError extends Error {
+  override readonly name: "InvalidSignatureError";
+  readonly response: Response;
+  constructor(response: Response);
+}
+declare function invalidSignatureResponse(error: unknown): Response | undefined;
+declare function invalidSignatureProblem(detail: string): Response;
+declare function discoverViaSignatureAgent(options: DiscoverViaSignatureAgentOptions): WebBotAuthKeys;
+declare function verifyWebBotAuth(request: Request, options: WebBotAuthOptions | undefined): Promise<Actor | undefined>;
+//#endregion
+//#region src/server/evaluations.d.ts
+declare function createEvaluationsHandler(options: {
+  readonly policy: Policy;
+  readonly resolve?: (request: Request) => Promise<PermDock>;
+  readonly getPermDock?: (query?: {
+    readonly tenant?: string;
+  }) => Promise<PermDock>;
+  readonly store?: ApprovalStore;
+  readonly adapter?: string;
+  /** The most evaluations one POST may carry; a larger batch is a 413 before any instance is resolved. */
+  readonly maxEvaluations?: number;
+}): {
+  readonly POST: (request: Request) => Promise<Response>;
+  readonly GET: (request: Request) => Promise<Response>;
+};
+//#endregion
+//#region src/server/create.d.ts
+type ServerPermDockOptions<TUser = unknown> = {
+  /** The user, or a full `Subject` (core then skips `policy.subject`); `null` is anonymous. */
+  readonly subject: (request: Request) => TUser | Subject | null | Promise<TUser | Subject | null>;
+  readonly actor?: (request: Request) => unknown;
+  /** `(request) => verifyWebBotAuth(request, options)`; a verified bot becomes the actor. */
+  readonly webBotAuth?: WebBotAuthVerifier;
+  readonly tenant?: string | ((request: Request) => string | undefined | Promise<string | undefined>);
+  readonly memberships?: MembershipSource | readonly MembershipSource[];
+  /** The object graph for relation grants that walk a parent chain; without it they deny. */
+  readonly relations?: RelationSource;
+  readonly entitlements?: EntitlementSource;
+  readonly customRoles?: RoleSource;
+  /** Hosted grants, read once per instance; see `PolicySource`. */
+  readonly policies?: PolicySource;
+  readonly store?: ApprovalStore;
+  readonly sink?: DecisionSink;
+  readonly limits?: LimitStore;
+  /** Ends or revalidates open connections; never a decision input. */
+  readonly revocations?: RevocationFeed;
+  /**
+   * `createPermDock` from `permdock/pdp`: `protect` then decides delegated
+   * permissions through the remote PDP. The instance handlers receive stays
+   * synchronous and keeps denying delegated permissions (`pdp-unavailable`).
+   */
+  readonly pdp?: PdpFactory;
+  /** Accepted for adapter parity; HTTP adapters do not read it. */
+  readonly snapshots?: SnapshotSource;
+  /** Added as `approval` to every `approval-required` problem. */
+  readonly approval?: ApprovalHint;
+};
+type Guard<T = unknown, V extends PolicyVocabulary = PolicyVocabulary> = {
+  readonly ok: true;
+  readonly permdock: PermDock<V>;
+  readonly decision: Extract<Decision, {
+    readonly outcome: "granted";
+  }>;
+  readonly data: T;
+} | {
+  readonly ok: false;
+  readonly response: Response;
+};
+type OpenApiHooks = {
+  readonly security: (permission: Permission) => {
+    readonly security: readonly Record<string, readonly string[]>[];
+    readonly "x-permdock-permissions": readonly string[];
+  };
+  readonly securitySchemes: () => Readonly<Record<string, unknown>>;
+};
+type ProtectOptions = {
+  /**
+   * `true` when `loadData` returns a row the server loaded itself, to skip
+   * schema validation. Anything else is validated against the resource
+   * schema before the check.
+   */
+  readonly trusted?: boolean;
+};
+type TenantOption<TContext> = string | ((context: TContext) => string | undefined | Promise<string | undefined>);
+type ServerPermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
+  readonly permdock: (request: Request) => Promise<PermDock<V>>;
+  readonly protect: <T = unknown>(permission: Permission, loadData?: (request: Request) => T | null | undefined | Promise<T | null | undefined>, protectOptions?: ProtectOptions) => (request: Request) => Promise<Guard<T, V>>;
+  /** A long-lived connection for a stream or socket opened by `request`. */
+  readonly connection: <T = unknown>(request: Request, options?: ConnectionOptions<T>) => Promise<Connection>;
+  readonly problem: (decision: Decision, init?: {
+    readonly permission?: Permission;
+    readonly instance?: string;
+  }) => Response;
+  readonly openapi: OpenApiHooks;
+  readonly permdockHandler: () => ReturnType<typeof createEvaluationsHandler>;
+};
+declare function createPermDock<TUser, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, options: ServerPermDockOptions<TUser>): ServerPermDock<V>;
+//#endregion
+export { ConnectionOptions as S, invalidSignatureProblem as _, ServerPermDockOptions as a, Connection as b, createEvaluationsHandler as c, WebBotAuthJwk as d, WebBotAuthKeyLookup as f, discoverViaSignatureAgent as g, WebBotAuthVerifier as h, ServerPermDock as i, DiscoverViaSignatureAgentOptions as l, WebBotAuthOptions as m, OpenApiHooks as n, TenantOption as o, WebBotAuthKeys as p, ProtectOptions as r, createPermDock as s, Guard as t, InvalidSignatureError as u, invalidSignatureResponse as v, ConnectionData as x, verifyWebBotAuth as y };