permdock 0.0.0 → 0.2.0

package/dist/snapshot-cache-D6jLelln.js

@@ -0,0 +1,44 @@
+import { n as payloadDigest } from "./token-CIWxJOCh.js";
+//#region src/core/snapshot-cache.ts
+/**
+* `{ stale }` in seconds: `max` when the value never expires, otherwise the seconds left, clamped
+* to `[min, max]`. A value with less than `min` seconds left gets its real remainder, so Next.js
+* leaves it out of prefetches and an HTTP cache does not serve it past `expiresAt`.
+*/
+function cacheLifeFor(value, options = {}) {
+	const min = options.min ?? 30;
+	const max = Math.max(options.max ?? 300, min);
+	const expiresAt = value?.expiresAt;
+	if (expiresAt === void 0 || expiresAt === null) return { stale: max };
+	const issuedAt = value?.issuedAt !== void 0 && value.issuedAt > 0 ? value.issuedAt : void 0;
+	const now = options.now ?? issuedAt ?? Math.floor(Date.now() / 1e3);
+	const remaining = Math.floor(expiresAt - now);
+	if (remaining < min) return { stale: Math.max(0, remaining) };
+	return { stale: Math.min(max, remaining) };
+}
+/**
+* The `cacheTag` for one subject's cached snapshots: `permdock:<sub>`, or `permdock:anon`
+* without a subject. Tag the private cache with it and pass it to `updateTag` or
+* `revalidateTag` on every write that changes the subject's snapshot.
+*/
+function snapshotTag(sub) {
+	return `permdock:${sub === void 0 || sub === null || sub === "" ? "anon" : sub}`;
+}
+/**
+* Response headers for a loader or route that returns `snapshot`: `Cache-Control: private` with
+* `max-age` from `cacheLifeFor`, `Vary: Authorization, Cookie`, an `ETag` over everything but
+* `issuedAt`, and `Cache-Tag` with `snapshotTag(sub)` and `tags`.
+*/
+function snapshotHeaders(snapshot, options = {}) {
+	const content = {};
+	for (const [key, value] of Object.entries(snapshot)) if (key !== "issuedAt") content[key] = value;
+	const { tags, ...life } = options;
+	return {
+		"Cache-Control": `private, max-age=${cacheLifeFor(snapshot, life).stale}`,
+		Vary: "Authorization, Cookie",
+		ETag: `"${payloadDigest(content)}"`,
+		"Cache-Tag": [snapshotTag(snapshot.subject.principal?.id), ...tags ?? []].join(",")
+	};
+}
+//#endregion
+export { snapshotHeaders as n, snapshotTag as r, cacheLifeFor as t };

package/dist/snapshot-cache-DwQH8ufx.d.ts

@@ -0,0 +1,45 @@
+import { Tt as Snapshot } from "./policy-CFZAr_Al.js";
+//#region src/core/snapshot-cache.d.ts
+type CacheLifeForOptions = {
+  /** Lower bound in seconds. Next.js includes a private entry in per-link prefetches from 30. */
+  readonly min?: number;
+  /** Upper bound in seconds. Next.js keeps a per-session App Shell entry from 300. */
+  readonly max?: number;
+  /** Seconds since the epoch; defaults to the snapshot's `issuedAt`, then the clock. */
+  readonly now?: number;
+};
+/**
+ * `{ stale }` in seconds: `max` when the value never expires, otherwise the seconds left, clamped
+ * to `[min, max]`. A value with less than `min` seconds left gets its real remainder, so Next.js
+ * leaves it out of prefetches and an HTTP cache does not serve it past `expiresAt`.
+ */
+declare function cacheLifeFor(value: {
+  readonly expiresAt?: number | null;
+  readonly issuedAt?: number;
+} | null, options?: CacheLifeForOptions): {
+  readonly stale: number;
+};
+/**
+ * The `cacheTag` for one subject's cached snapshots: `permdock:<sub>`, or `permdock:anon`
+ * without a subject. Tag the private cache with it and pass it to `updateTag` or
+ * `revalidateTag` on every write that changes the subject's snapshot.
+ */
+declare function snapshotTag(sub?: string | null): string;
+type SnapshotHeadersOptions = CacheLifeForOptions & {
+  /** Sent in `Cache-Tag` after `snapshotTag(sub)`, such as the app's own organisation tag. */
+  readonly tags?: readonly string[];
+};
+type SnapshotHeaders = {
+  readonly "Cache-Control": string;
+  readonly Vary: string;
+  readonly ETag: string;
+  readonly "Cache-Tag": string;
+};
+/**
+ * Response headers for a loader or route that returns `snapshot`: `Cache-Control: private` with
+ * `max-age` from `cacheLifeFor`, `Vary: Authorization, Cookie`, an `ETag` over everything but
+ * `issuedAt`, and `Cache-Tag` with `snapshotTag(sub)` and `tags`.
+ */
+declare function snapshotHeaders(snapshot: Snapshot, options?: SnapshotHeadersOptions): SnapshotHeaders;
+//#endregion
+export { snapshotHeaders as a, cacheLifeFor as i, SnapshotHeaders as n, snapshotTag as o, SnapshotHeadersOptions as r, CacheLifeForOptions as t };

package/dist/solid/index.d.ts

@@ -0,0 +1,93 @@
+import { Ft as TokenVerifier, Mr as Membership, Tt as Snapshot, Yn as Decision } from "../policy-CFZAr_Al.js";
+import { f as Permission } from "../permissions-DttnqqxC.js";
+import { r as Role } from "../vocabulary-DA8a8zif.js";
+import { n as requiredPlans } from "../problem-details-CkL50EEf.js";
+import { i as describe } from "../describe-PdoqESvg.js";
+import { t as PermissionBoundaryState } from "../boundary-BmHxVH1J.js";
+import { t as approvalHeaders } from "../headers-Cf-zWvsO.js";
+import { a as FilterResult, c as SubjectView, i as ClientStatus, l as TenantView, n as ApprovalState, o as PermissionSet, r as ClientPermDock, s as PermissionState, t as ApprovalHandle, u as UseRolesOptions } from "../types-kxznc7cn.js";
+import { Accessor, Accessor as Accessor$1, JSX } from "solid-js";
+//#region src/solid/types.d.ts
+/** Structural `JSX.Element`: text, a DOM node or a list of children. */
+type SolidChild = string | number | boolean | null | undefined | {
+  readonly nodeType: number;
+} | readonly SolidChild[];
+type PermDockProviderProps = {
+  /**
+   * An accessor re-hydrates the store when it changes and keeps it `pending`
+   * while it returns `undefined` (a loading `createResource`); a promise keeps
+   * the store `pending` until it settles.
+   */
+  readonly snapshot: Snapshot | string | Accessor$1<Snapshot | string | undefined> | PromiseLike<Snapshot | string>;
+  /**
+   * The AuthZEN evaluations endpoint for checks the snapshot cannot answer.
+   * `false` never calls one: such a check is denied with reason `server-only`.
+   */
+  readonly endpoint?: string | false;
+  /** Where `refresh()` fetches a fresh snapshot. Defaults to `endpoint`. */
+  readonly snapshotUrl?: string;
+  readonly approvals?: string;
+  /** A change switches the active tenant (`refresh({ tenant })`). */
+  readonly tenant?: string;
+  /** `headers`, `fetch` and `verifier` are read on every request, so a rotated token applies without a new store. */
+  readonly fetch?: typeof fetch;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly maxAge?: number;
+  readonly verifier?: TokenVerifier;
+  readonly children: unknown;
+};
+type PermissionBoundaryProps = {
+  /** Rendered in place of the children when one throws `PermDockDeniedError`. */
+  readonly denied?: SolidChild | ((state: PermissionBoundaryState) => SolidChild);
+  /** Rendered for `PermDockApprovalRequiredError`; defaults to `denied`. */
+  readonly approval?: SolidChild | ((state: PermissionBoundaryState) => SolidChild);
+  readonly children: unknown;
+};
+type ProtectedProps = {
+  readonly permission: Permission;
+  readonly data?: unknown;
+  readonly tenant?: string;
+  readonly pending?: SolidChild;
+  readonly fallback?: SolidChild | ((decision: Decision) => SolidChild);
+  readonly children: SolidChild | ((decision: Extract<Decision, {
+    readonly outcome: "granted";
+  }>) => SolidChild);
+};
+//#endregion
+//#region src/solid/hooks.d.ts
+export declare function usePermDock(): ClientPermDock;
+export declare function usePermission(permission: Permission | Accessor<Permission>, data?: Accessor<unknown>): Accessor<PermissionState>;
+export declare function usePermissions(permissions: Accessor<readonly Permission[]>, data?: Accessor<unknown>): Accessor<PermissionSet>;
+export declare function useFilter<T>(permission: Permission<string, T, "instance">, rows: Accessor<readonly T[]>): Accessor<FilterResult<T>>;
+export declare function useTenant(): Accessor<TenantView>;
+export declare function useMemberships(): Accessor<readonly Membership[]>;
+export declare function useRoles(options?: Accessor<UseRolesOptions>): Accessor<{
+  readonly roles: readonly Role[];
+}>;
+export declare function useAssignableRoles(): Accessor<readonly Role[]>;
+export declare function useAssignablePermissions(options?: {
+  readonly tenant?: string;
+} | Accessor<{
+  readonly tenant?: string;
+}>): Accessor<readonly Permission[]>;
+export declare function useSubject(): Accessor<SubjectView>;
+export declare function useApproval(decision: Accessor<Decision>): Accessor<ApprovalHandle>;
+//#endregion
+//#region src/solid/boundary.d.ts
+/**
+ * Catches `PermDockDeniedError` and `PermDockApprovalRequiredError` thrown
+ * below it and renders `denied`, or `approval` for an approval request
+ * (default `denied`), with the refused permission and `retry()`. Any other
+ * error goes to the next `ErrorBoundary` up.
+ */
+export declare function PermissionBoundary(props: PermissionBoundaryProps): JSX.Element;
+/** Inside a `PermissionBoundary` fallback: what was refused and `retry()`. */
+export declare function usePermissionBoundary(): PermissionBoundaryState | null;
+//#endregion
+//#region src/solid/protected.d.ts
+export declare function Protected(props: ProtectedProps): JSX.Element;
+//#endregion
+//#region src/solid/provider.d.ts
+export declare function PermDockProvider(props: PermDockProviderProps): JSX.Element;
+//#endregion
+export { type ApprovalHandle, type ApprovalState, type ClientPermDock, type ClientStatus, type FilterResult, type PermDockProviderProps, type PermissionBoundaryProps, type PermissionBoundaryState, type PermissionSet, type PermissionState, type ProtectedProps, type SolidChild, type SubjectView, type TenantView, type UseRolesOptions, approvalHeaders, describe, requiredPlans };

package/dist/solid/index.js

@@ -0,0 +1,188 @@
+import { t as compact } from "../compact-y6vfu2_f.js";
+import { r as requiredPlans } from "../problem-details-_AMOYz-w.js";
+import { t as describe } from "../describe-B_gVZEVi.js";
+import { t as approvalHeaders } from "../headers-BZSDieNT.js";
+import { i as isPromiseLike } from "../store-options-yO0V6gRn.js";
+import { a as protectedView, c as subjectView, i as permissionSet, l as tenantView, n as filterResult, o as rolesView, r as livePermDock, s as scopedTenant, t as approvalHandle } from "../views-Soe7bGSC.js";
+import { n as boundaryFallback, t as boundaryDigest } from "../boundary-BM8a_P6E.js";
+import { n as switchTenant, t as providerStore } from "../provider-store-DNyC1y48.js";
+import { ErrorBoundary, createComponent, createComputed, createContext, createMemo, createSignal, getOwner, on, onCleanup, useContext } from "solid-js";
+//#region src/solid/context.ts
+const PermDockContext = createContext(void 0);
+function useStore() {
+	const store = useContext(PermDockContext);
+	if (store === void 0) throw new Error("PermDock: hooks require <PermDockProvider>.");
+	return store;
+}
+//#endregion
+//#region src/solid/hooks.ts
+function useVersion(store) {
+	if (getOwner() === null) throw new Error("PermDock: call hooks inside a component or createRoot, which removes their store subscription.");
+	const [tick, setTick] = createSignal(0);
+	onCleanup(store.subscribe(() => {
+		setTick((current) => current + 1);
+	}));
+	return tick;
+}
+function usePermDock() {
+	const store = useStore();
+	const version = useVersion(store);
+	return livePermDock(() => {
+		version();
+		return store.get();
+	});
+}
+function usePermission(permission, data) {
+	const store = useStore();
+	const version = useVersion(store);
+	return createMemo(() => {
+		version();
+		const current = typeof permission === "function" ? permission() : permission;
+		return store.permissionState(current, data?.());
+	});
+}
+function usePermissions(permissions, data) {
+	const store = useStore();
+	const version = useVersion(store);
+	return createMemo(() => {
+		version();
+		return permissionSet(store, permissions(), data?.());
+	});
+}
+function useFilter(permission, rows) {
+	const permdock = usePermDock();
+	return createMemo(() => filterResult(permdock, permission, rows()));
+}
+function useTenant() {
+	const permdock = usePermDock();
+	return createMemo(() => tenantView(permdock));
+}
+function useMemberships() {
+	const permdock = usePermDock();
+	return createMemo(() => permdock.memberships());
+}
+function useRoles(options = () => ({})) {
+	const permdock = usePermDock();
+	return createMemo(() => rolesView(permdock, options()));
+}
+function useAssignableRoles() {
+	const permdock = usePermDock();
+	return createMemo(() => permdock.assignableRoles());
+}
+function useAssignablePermissions(options = {}) {
+	const permdock = usePermDock();
+	return createMemo(() => permdock.assignablePermissions(typeof options === "function" ? options() : options));
+}
+function useSubject() {
+	const permdock = usePermDock();
+	return createMemo(() => subjectView(permdock));
+}
+function useApproval(decision) {
+	const store = useStore();
+	const version = useVersion(store);
+	return createMemo(() => {
+		version();
+		return approvalHandle(store, decision());
+	});
+}
+//#endregion
+//#region src/solid/boundary.ts
+const BoundaryContext = createContext(null);
+/**
+* Catches `PermDockDeniedError` and `PermDockApprovalRequiredError` thrown
+* below it and renders `denied`, or `approval` for an approval request
+* (default `denied`), with the refused permission and `retry()`. Any other
+* error goes to the next `ErrorBoundary` up.
+*/
+function PermissionBoundary(props) {
+	return createComponent(ErrorBoundary, {
+		fallback: (error, reset) => {
+			const digest = boundaryDigest(error);
+			if (digest === null) throw error;
+			const state = {
+				...digest,
+				retry: reset
+			};
+			return createComponent(BoundaryContext.Provider, {
+				value: state,
+				get children() {
+					const chosen = boundaryFallback(digest, props);
+					return typeof chosen === "function" ? chosen(state) : chosen ?? null;
+				}
+			});
+		},
+		get children() {
+			return props.children;
+		}
+	});
+}
+/** Inside a `PermissionBoundary` fallback: what was refused and `retry()`. */
+function usePermissionBoundary() {
+	return useContext(BoundaryContext);
+}
+//#endregion
+//#region src/solid/protected.ts
+function Protected(props) {
+	const root = usePermDock();
+	const local = usePermission(() => props.permission, () => props.data);
+	const scoped = createMemo(() => scopedTenant(root, props.tenant));
+	const view = createMemo(() => protectedView(local(), root, props.permission, props.data, scoped()));
+	const render = () => {
+		const current = view();
+		switch (current.slot) {
+			case "pending": return props.pending ?? null;
+			case "fallback": return typeof props.fallback === "function" ? props.fallback(current.decision) : props.fallback ?? null;
+			case "default": return typeof props.children === "function" ? props.children(current.decision) : props.children;
+			default: return current;
+		}
+	};
+	return render;
+}
+//#endregion
+//#region src/solid/provider.ts
+function PermDockProvider(props) {
+	const source = props.snapshot;
+	const promised = isPromiseLike(source);
+	const read = typeof source === "function" ? source : void 0;
+	const initial = promised ? void 0 : read === void 0 ? source : read();
+	const store = providerStore(compact({
+		endpoint: props.endpoint,
+		snapshotUrl: props.snapshotUrl,
+		approvals: props.approvals,
+		tenant: props.tenant,
+		maxAge: props.maxAge
+	}), () => ({
+		headers: props.headers,
+		fetch: props.fetch,
+		verifier: props.verifier
+	}), promised ? source : initial);
+	createComputed(on(() => props.tenant, (next) => {
+		switchTenant(store, next);
+	}, { defer: true }));
+	onCleanup(() => {
+		store.dispose();
+	});
+	if (!promised && read !== void 0) {
+		let arrive;
+		if (initial === void 0) store.follow(new Promise((resolve) => {
+			arrive = resolve;
+		}));
+		createComputed(on(read, (next) => {
+			if (next === void 0) return;
+			if (arrive === void 0) {
+				store.replace(next);
+				return;
+			}
+			arrive(next);
+			arrive = void 0;
+		}, { defer: initial !== void 0 }));
+	}
+	return createComponent(PermDockContext.Provider, {
+		value: store,
+		get children() {
+			return props.children;
+		}
+	});
+}
+//#endregion
+export { PermDockProvider, PermissionBoundary, Protected, approvalHeaders, describe, requiredPlans, useApproval, useAssignablePermissions, useAssignableRoles, useFilter, useMemberships, usePermDock, usePermission, usePermissionBoundary, usePermissions, useRoles, useSubject, useTenant };