permdock 0.3.1 → 0.5.0

package/dist/solid/index.d.ts

@@ -1,41 +1,38 @@
-import { Ft as TokenVerifier, Mr as Membership, Tt as Snapshot, Yn as Decision } from "../policy-IB6yxpC3.js";
-import { f as Permission } from "../permissions-DttnqqxC.js";
-import { r as Role } from "../vocabulary-DA8a8zif.js";
-import { n as requiredPlans } from "../problem-details-DX075l9V.js";
-import { i as describe } from "../describe-DMYiCjJV.js";
+import { Mn as ApprovalRequiredDecision, Nn as Decision, Vt as Snapshot, dt as TokenVerifier, nr as Membership, zn as GrantedDecision } from "../policy-types-DzwivBgR.js";
+import { r as Role, w as Permission } from "../vocabulary-D6lPdb4Z.js";
+import { n as requiredPlans } from "../problem-details-DXlt-vks.js";
+import { i as describe, r as DescribeOptions, t as DecisionDescription } from "../describe-BZUsixiL.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-CKNSyIf_.js";
+import { t as approvalHeaders } from "../headers-CIbDTUTK.js";
+import { a as FilterResult, c as PermissionSet, d as RolesOptions, f as SubjectView, i as ClientStatus, l as PermissionState, n as ApprovalState, p as TenantView, r as ClientPermDock, t as ApprovalHandle, u as ProviderOptionsBase } from "../types-BNORmDM8.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 = {
+type PermDockProviderProps = ProviderOptionsBase & {
   /**
    * 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;
+  /** Read on every request, with `verifier`, so a rotated token applies without a new store. */
   readonly headers?: Readonly<Record<string, string>>;
-  readonly maxAge?: number;
   readonly verifier?: TokenVerifier;
+  /** What every `<Protected>` below renders for a slot it leaves out. */
+  readonly defaults?: PermDockDefaults;
   readonly children: unknown;
 };
+/** Provider-wide content for the `<Protected>` slots a component leaves out. */
+type PermDockDefaults = {
+  readonly pending?: SolidChild;
+  readonly denied?: SolidChild | ((decision: Decision) => SolidChild);
+  readonly approval?: SolidChild | ((decision: ApprovalRequiredDecision) => SolidChild);
+};
 type PermissionBoundaryProps = {
   /** Rendered in place of the children when one throws `PermDockDeniedError`. */
   readonly denied?: SolidChild | ((state: PermissionBoundaryState) => SolidChild);
@@ -48,10 +45,10 @@ type ProtectedProps = {
   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);
+  readonly denied?: SolidChild | ((decision: Decision) => SolidChild);
+  /** Rendered for an approval-required decision; defaults to `denied`. */
+  readonly approval?: SolidChild | ((decision: ApprovalRequiredDecision) => SolidChild);
+  readonly children: SolidChild | ((decision: GrantedDecision) => SolidChild);
 };
 //#endregion
 //#region src/solid/hooks.d.ts
@@ -61,7 +58,7 @@ export declare function usePermissions(permissions: Accessor<readonly Permission
 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<{
+export declare function useRoles(options?: Accessor<RolesOptions>): Accessor<{
   readonly roles: readonly Role[];
 }>;
 export declare function useAssignableRoles(): Accessor<readonly Role[]>;
@@ -72,6 +69,8 @@ export declare function useAssignablePermissions(options?: {
 }>): Accessor<readonly Permission[]>;
 export declare function useSubject(): Accessor<SubjectView>;
 export declare function useApproval(decision: Accessor<Decision>): Accessor<ApprovalHandle>;
+/** `describe` with the provider's `messages`; a call's own `messages` win. */
+export declare function useDescribe(): (decision: Decision, options?: DescribeOptions) => DecisionDescription;
 //#endregion
 //#region src/solid/boundary.d.ts
 /**
@@ -90,4 +89,4 @@ export declare function Protected(props: ProtectedProps): JSX.Element;
 //#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 };
+export { type ApprovalHandle, type ApprovalState, type ClientPermDock, type ClientStatus, type FilterResult, type PermDockDefaults, type PermDockProviderProps, type PermissionBoundaryProps, type PermissionBoundaryState, type PermissionSet, type PermissionState, type ProtectedProps, type RolesOptions, type SolidChild, type SubjectView, type TenantView, approvalHeaders, describe, requiredPlans };

package/dist/solid/index.js

@@ -1,14 +1,15 @@
-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-ByhZq1jV.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 { t as compact } from "../compact-CAf557ZB.js";
+import { r as requiredPlans } from "../problem-details-cn5X30gZ.js";
+import { t as describe } from "../describe-BybMRY7A.js";
 import { n as boundaryFallback, t as boundaryDigest } from "../boundary-BM8a_P6E.js";
-import { n as switchTenant, t as providerStore } from "../provider-store-Cfbvo4DE.js";
+import { t as approvalHeaders } from "../headers-BIjfMaoC.js";
+import { i as isPromiseLike } from "../store-options-BqEakYRa.js";
+import { n as switchTenant, t as providerStore } from "../provider-store-B5Yrkhzr.js";
+import { a as livePermDock, c as rolesView, d as subjectView, f as tenantView, l as scopedTenant, n as describeWith, o as permissionSet, r as filterResult, s as protectedView, t as approvalHandle, u as slotContent } from "../views-DTIIO-oQ.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);
+const PermDockUiContext = createContext({});
 function useStore() {
 	const store = useContext(PermDockContext);
 	if (store === void 0) throw new Error("PermDock: hooks require <PermDockProvider>.");
@@ -85,6 +86,11 @@ function useApproval(decision) {
 		return approvalHandle(store, decision());
 	});
 }
+/** `describe` with the provider's `messages`; a call's own `messages` win. */
+function useDescribe() {
+	const ui = useContext(PermDockUiContext);
+	return (decision, options) => describeWith(ui.messages)(decision, options);
+}
 //#endregion
 //#region src/solid/boundary.ts
 const BoundaryContext = createContext(null);
@@ -124,20 +130,25 @@ function usePermissionBoundary() {
 //#region src/solid/protected.ts
 function Protected(props) {
 	const root = usePermDock();
+	const ui = useContext(PermDockUiContext);
 	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 "pending": return slotContent("pending", props, ui.defaults) ?? null;
+			case "denied": return content(slotContent("denied", props, ui.defaults), current.decision);
+			case "approval": return content(slotContent("approval", props, ui.defaults), current.decision);
 			case "default": return typeof props.children === "function" ? props.children(current.decision) : props.children;
 			default: return current;
 		}
 	};
 	return render;
 }
+function content(slot, decision) {
+	return typeof slot === "function" ? slot(decision) : slot ?? null;
+}
 //#endregion
 //#region src/solid/provider.ts
 function PermDockProvider(props) {
@@ -150,7 +161,10 @@ function PermDockProvider(props) {
 		snapshotUrl: props.snapshotUrl,
 		approvals: props.approvals,
 		tenant: props.tenant,
-		maxAge: props.maxAge
+		maxAge: props.maxAge,
+		onSnapshot: props.onSnapshot,
+		onClear: props.onClear,
+		approvalInterval: props.approvalInterval
 	}), () => ({
 		headers: props.headers,
 		fetch: props.fetch,
@@ -177,12 +191,28 @@ function PermDockProvider(props) {
 			arrive = void 0;
 		}, { defer: initial !== void 0 }));
 	}
+	const ui = {
+		get defaults() {
+			return props.defaults;
+		},
+		get messages() {
+			return props.messages;
+		}
+	};
 	return createComponent(PermDockContext.Provider, {
 		value: store,
+		get children() {
+			return uiProvider(ui, props);
+		}
+	});
+}
+function uiProvider(ui, props) {
+	return createComponent(PermDockUiContext.Provider, {
+		value: ui,
 		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 };
+export { PermDockProvider, PermissionBoundary, Protected, approvalHeaders, describe, requiredPlans, useApproval, useAssignablePermissions, useAssignableRoles, useDescribe, useFilter, useMemberships, usePermDock, usePermission, usePermissionBoundary, usePermissions, useRoles, useSubject, useTenant };

package/dist/solid-start/index.d.ts

@@ -0,0 +1,52 @@
+import { T as Policy, Vt as Snapshot, j as PolicyVocabulary, rr as Principal } from "../policy-types-DzwivBgR.js";
+import { w as Permission } from "../vocabulary-D6lPdb4Z.js";
+import { a as OperationInput, t as Operation } from "../operations-CxybZErY.js";
+import { r as PermDock } from "../permdock-D7eeLJER.js";
+import { D as ConnectionOptions, T as Connection, f as InvalidSignatureError, i as OpenApiHooks, o as ProtectOptions, u as SnapshotQuery, v as discoverViaSignatureAgent, x as webBotAuthVerifier } from "../server-types-BLd4MnBX.js";
+import { a as ProtectTarget, n as FetchAdapterOptions, t as ContextReader } from "../fetch-adapter-qKJBuRqy.js";
+import { APIEvent, FetchEvent } from "@solidjs/start/server";
+//#region src/solid-start/create.d.ts
+/** The h3 event under every SolidStart request; `subject` and `scope` read it. */
+type SolidStartNativeEvent = FetchEvent["nativeEvent"];
+/** An h3 middleware for `createMiddleware([...])` in `src/middleware.ts`. */
+type SolidStartMiddleware = (event: SolidStartNativeEvent, next: () => unknown) => Promise<unknown>;
+type SolidStartPermDockOptions<TUser = unknown> = FetchAdapterOptions<SolidStartNativeEvent, TUser>;
+/** What the adapter sets on `event.locals`. */
+type SolidStartPermDockLocals<TData = unknown, V extends PolicyVocabulary = PolicyVocabulary> = {
+  readonly permdock: PermDock<V>;
+  readonly permdockData: TData;
+};
+/** The event a wrapped API route receives: its own `APIEvent` with typed `locals`. */
+type SolidStartPermDockEvent<TEvent extends FetchEvent = APIEvent, TData = unknown, V extends PolicyVocabulary = PolicyVocabulary> = TEvent & {
+  readonly locals: SolidStartPermDockLocals<TData, V>;
+};
+/** Wraps an API route handler. */
+type SolidStartGuarded<TData, V extends PolicyVocabulary = PolicyVocabulary> = <TEvent extends FetchEvent = APIEvent, R = Response>(handler: (event: SolidStartPermDockEvent<TEvent, TData, V>) => R | Promise<R>) => (event: TEvent) => Promise<R | Response>;
+type SolidStartProtect<V extends PolicyVocabulary = PolicyVocabulary> = {
+  <T = unknown>(permission: Permission | null, data?: ContextReader<APIEvent, T | null | undefined>, protectOptions?: ProtectOptions): SolidStartGuarded<NonNullable<T>, V>;
+  <TOperation extends Operation>(operation: TOperation, input?: ContextReader<APIEvent, OperationInput<TOperation>>, protectOptions?: ProtectOptions): SolidStartGuarded<unknown, V>;
+};
+/** The decision endpoint, one API route handler per method. */
+type SolidStartPermDockHandlers = {
+  readonly GET: (event: FetchEvent) => Promise<Response>;
+  readonly POST: (event: FetchEvent) => Promise<Response>;
+};
+type SolidStartPermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
+  /** Sets `event.context.permdock` on the h3 event; a bad Web Bot Auth signature is a `401`. */
+  readonly middleware: () => SolidStartMiddleware;
+  /** `export const DELETE = protect(permissions.post.delete, loadPost)(handler)`. */
+  readonly protect: SolidStartProtect<V>;
+  /** Types `event.locals.permdock` for an API route and answers a thrown PermDock error with Problem Details. */
+  readonly withPermDock: SolidStartGuarded<unknown, V>;
+  /** The instance for an API route, or a server function through `getRequestEvent()`. */
+  readonly getPermDock: (event: FetchEvent) => Promise<PermDock<V>>;
+  /** The snapshot a route `query` returns for `permdock/solid`. */
+  readonly getSnapshot: (event: FetchEvent, query?: SnapshotQuery) => Promise<Snapshot>;
+  readonly connection: (event: FetchEvent, connectionOptions?: ConnectionOptions) => Promise<Connection>;
+  /** `export const { GET, POST } = permdockHandler()` in `src/routes/api/permdock.ts`. */
+  readonly permdockHandler: () => SolidStartPermDockHandlers;
+  readonly openapi: OpenApiHooks;
+};
+export declare function createPermDock<TUser, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, options: SolidStartPermDockOptions<TUser>): SolidStartPermDock<V>;
+//#endregion
+export { type ContextReader, InvalidSignatureError, type ProtectTarget, type SolidStartGuarded, type SolidStartMiddleware, type SolidStartNativeEvent, type SolidStartPermDock, type SolidStartPermDockEvent, type SolidStartPermDockHandlers, type SolidStartPermDockLocals, type SolidStartPermDockOptions, type SolidStartProtect, discoverViaSignatureAgent, webBotAuthVerifier };

package/dist/solid-start/index.js

@@ -0,0 +1,49 @@
+import { d as discoverViaSignatureAgent, m as webBotAuthVerifier, u as InvalidSignatureError } from "../evaluations-DZ2CbV5k.js";
+import { i as decorate } from "../bind-CZzhx-Vj.js";
+import { n as guardedRoute, t as fetchAdapter } from "../fetch-adapter-g0ypLkID.js";
+//#region src/solid-start/create.ts
+/**
+* `event.locals`. Its type, `App.RequestEventLocals`, is declared by
+* `@solidjs/start/env`, which only an app's own `tsconfig` loads.
+*/
+function localsOf(event) {
+	return Reflect.get(event, "locals");
+}
+const route = {
+	context: (event) => event.nativeEvent,
+	locals: localsOf
+};
+function createPermDock(policy, options) {
+	const adapter = fetchAdapter(policy, options, "solid-start", (event) => event.req);
+	const middleware = () => async (event, next) => {
+		const attached = await adapter.ensure(event.context, event);
+		if (!attached.ok) return attached.response;
+		return adapter.mapErrors(event, next);
+	};
+	const protect = ((target, data, protectOptions) => guardedRoute(adapter, route, target, data, protectOptions));
+	const withPermDock = (handler) => async (event) => {
+		const attached = await adapter.ensure(event.nativeEvent.context, event.nativeEvent);
+		if (!attached.ok) return attached.response;
+		decorate(localsOf(event), attached.permdock);
+		return adapter.mapErrors(event.nativeEvent, () => handler(event));
+	};
+	const handlers = () => {
+		const { GET, POST } = adapter.handlers();
+		return {
+			GET: (event) => GET(event.nativeEvent),
+			POST: (event) => POST(event.nativeEvent)
+		};
+	};
+	return {
+		middleware,
+		protect,
+		withPermDock,
+		getPermDock: (event) => adapter.getPermDock(event.nativeEvent),
+		getSnapshot: (event, query) => adapter.getSnapshot(event.nativeEvent, query),
+		connection: (event, connectionOptions) => adapter.connection(event.nativeEvent, connectionOptions),
+		permdockHandler: handlers,
+		openapi: adapter.kernel.openapi
+	};
+}
+//#endregion
+export { InvalidSignatureError, createPermDock, discoverViaSignatureAgent, webBotAuthVerifier };

package/dist/{sources-BdOYLw9j.d.ts → sources-BV9j0DeZ.d.ts}

@@ -1,6 +1,6 @@
-import { gt as MembershipSource } from "./policy-IB6yxpC3.js";
-import { n as RoleThrough, y as SupabaseSuspension } from "./types-C97IskBw.js";
-import { o as SupabaseManifestMembership } from "./manifest-uDS9y5de.js";
+import { et as MembershipSource } from "./policy-types-DzwivBgR.js";
+import { n as RoleThrough, y as SupabaseSuspension } from "./types-CdlxsYQh.js";
+import { o as SupabaseManifestMembership } from "./manifest-mx5ghSFM.js";
 //#region src/supabase/roles.d.ts
 /** A roles table a role column references, by `schema.table`. */
 type RoleKeys = {
@@ -55,6 +55,8 @@ type MembershipTableOptions = Common & {
     readonly managedBy?: string;
     /** A `text[]` column of seats. */
     readonly seats?: string;
+    /** A `jsonb` column of app data (`Membership.x`); never written into claims. */
+    readonly x?: string;
   };
 };
 type MembershipJunctionOptions = Common & {
@@ -92,6 +94,8 @@ type MembershipJunctionOptions = Common & {
   };
   /** A `text[]` column of seats. */
   readonly seats?: string;
+  /** A `jsonb` column of app data (`Membership.x`); never written into claims. */
+  readonly x?: string;
 };
 /** What `permdock supabase hook generate` compiles; the same SQL the source runs. */
 type MembershipSql = {
@@ -159,26 +163,20 @@ type SqlMembershipSource = MembershipSource & {
 type SupabasePostgres = {
   readonly queryRaw: (text: string, params?: unknown[]) => Promise<readonly Record<string, unknown>[]>;
 };
-/**
- * `ctx.postgres` (from `withPostgresClient`) or `ctx.postgresAdmin` as a
- * `SqlQuery` for `fromTable`, `fromJunction` and `supabaseApprovalStore`.
- * `ctx.postgres` runs as the caller under RLS, so the membership tables must
- * be readable by `authenticated`; `ctx.postgresAdmin` bypasses RLS.
- */
-declare function fromSupabasePostgres(postgres: SupabasePostgres): SqlQuery;
+declare function supabasePostgresQuery(postgres: SupabasePostgres): SqlQuery;
 /**
  * Memberships from one table holding every scope: a row per user, scope,
  * instance and role (`user_id, scope, scope_id, role`), with optional
  * `within`, `via`, expiry, owner and seat columns. Rows of the same instance
  * merge into one membership.
  */
-declare function fromTable(options: MembershipTableOptions): SqlMembershipSource;
+declare function tableMembershipSource(options: MembershipTableOptions): SqlMembershipSource;
 /**
  * Memberships from a table of one scope (`customer_contacts`): every row is a
  * membership of `scope`, with roles from a column or fixed (`['contact']`), a
  * fixed `via`, and ancestor ids from `within` columns.
  */
-declare function fromJunction(options: MembershipJunctionOptions): SqlMembershipSource;
+declare function junctionMembershipSource(options: MembershipJunctionOptions): SqlMembershipSource;
 declare const AUTHZ_VERSION_TABLE = "permdock_authz_version";
 /**
  * Reads the authorization version `permdock supabase hook generate` keeps in
@@ -189,4 +187,4 @@ declare function authzVersion(options: {
   readonly schema?: string;
 }): NonNullable<MembershipSource["version"]>;
 //#endregion
-export { MembershipTableOptions as a, SupabasePostgres as c, fromSupabasePostgres as d, fromTable as f, MembershipSql as i, authzVersion as l, MembershipHolders as n, SqlMembershipSource as o, MembershipJunctionOptions as r, SqlQuery as s, AUTHZ_VERSION_TABLE as t, fromJunction as u };
+export { MembershipTableOptions as a, SupabasePostgres as c, supabasePostgresQuery as d, tableMembershipSource as f, MembershipSql as i, authzVersion as l, MembershipHolders as n, SqlMembershipSource as o, MembershipJunctionOptions as r, SqlQuery as s, AUTHZ_VERSION_TABLE as t, junctionMembershipSource as u };