permdock 0.6.0 → 0.8.0

package/dist/types-B_d_g7T3.d.ts

@@ -0,0 +1,262 @@
+import { Gt as Snapshot, Ln as Decision, Zn as Actor, dt as TokenVerifier, j as PolicyVocabulary, rr as Delegation, sr as Principal } from "./policy-types-CCiDRZBH.js";
+import { u as Permission } from "./permission-types-CAY-GU7e.js";
+import { a as PermDock } from "./permdock-B6Sf4T_S.js";
+import { n as DescribeMessages, t as DecisionDescription } from "./describe-ByS9LgHK.js";
+import { t as ActionResult } from "./action-result-CL-QCITA.js";
+//#region src/client/refresh-on.d.ts
+/**
+ * Calls `refresh` when the snapshot may be out of date (a membership event, a
+ * window focus, a realtime message) and returns the unsubscribe. A refresh
+ * re-fetches the signed snapshot; it never grants by itself.
+ */
+type RefreshTrigger = (refresh: () => void) => () => void;
+type EventSourceRefreshOptions = {
+  /**
+   * CloudEvent `type` values that refresh; a trailing `*` matches a prefix.
+   * Defaults to `com.permdock.membership.*` and `com.permdock.catalog.*`.
+   */
+  readonly types?: readonly string[];
+  readonly withCredentials?: boolean;
+};
+/**
+ * A `refreshOn` trigger over Server-Sent Events: each `message` whose data is a
+ * structured CloudEvent with a matching `type` refreshes the snapshot. Without
+ * a global `EventSource` it never fires.
+ */
+declare function eventSourceRefresh(url: string, options?: EventSourceRefreshOptions): RefreshTrigger;
+//#endregion
+//#region src/client/request.d.ts
+type StoreHeaders = Readonly<Record<string, string>>;
+//#endregion
+//#region src/client/store.d.ts
+type ClientStoreOptions = {
+  readonly snapshot: Snapshot | string;
+  readonly endpoint?: string;
+  readonly snapshotUrl?: string;
+  readonly approvals?: string;
+  readonly tenant?: string;
+  readonly fetch?: typeof fetch;
+  /**
+   * Request headers, or a getter read on every request so a rotated token needs
+   * no new store.
+   */
+  readonly headers?: StoreHeaders | (() => StoreHeaders | undefined);
+  readonly maxAge?: number;
+  readonly verifier?: TokenVerifier;
+  /**
+   * `raw` is the compact JWS the snapshot was verified from, so a signed
+   * snapshot can be persisted signed.
+   */
+  readonly onSnapshot?: (snapshot: Snapshot, tenant: string | undefined, raw: string | undefined) => void;
+  readonly onClear?: () => void;
+  /**
+   * Called once per key the snapshot cannot answer when there is no `endpoint`
+   * to ask.
+   */
+  readonly onServerOnly?: (permission: Permission) => void;
+  /**
+   * `true` while rendering on the server: endpoint checks answer `pending`
+   * without a request. Defaults to `typeof window === 'undefined'`.
+   */
+  readonly server?: boolean;
+  /** Milliseconds between approval status polls. Defaults to 2000. */
+  readonly approvalInterval?: number;
+  /** Start `pending`: the snapshot arrives later through `track()`. */
+  readonly awaiting?: boolean;
+  /**
+   * The first snapshot that hydrates with a principal is a persisted copy:
+   * `stale` until a refresh or a `replace()` lands.
+   */
+  readonly stale?: boolean;
+  /**
+   * Reuse decisions for the same row object until the next microtask. Only for
+   * renderers that do not track the fields a check reads (React): Vue, Svelte
+   * and Solid would stop re-running when a reactive row changes in place.
+   */
+  readonly passCache?: boolean;
+  /**
+   * Triggers that refresh the snapshot, started while something subscribes and
+   * never during a server render. Calls within 250 ms fold into one refresh.
+   */
+  readonly refreshOn?: readonly RefreshTrigger[];
+};
+type ClientStore = {
+  get: () => ClientPermDock;
+  subscribe: (listener: () => void) => () => void;
+  permissionState: (permission: Permission, data?: unknown) => PermissionState;
+  requestApproval: (decision: Decision, note?: string) => Promise<void>;
+  /** Hydrate from a pushed snapshot; a compact JWS goes through the verifier. */
+  replace: (value: unknown) => void;
+  /**
+   * Stay `pending` until `value` settles, then hydrate; a rejection fails
+   * closed.
+   */
+  follow: (value: PromiseLike<Snapshot | string>) => void;
+  /**
+   * `follow()` once per `value`, without suspending. A thenable React already
+   * settled (`status: 'fulfilled'`) hydrates at once.
+   */
+  track: (value: PromiseLike<Snapshot | string>) => void;
+  /**
+   * The approval state for a decision. While something subscribes, an
+   * `approval-required` decision is polled at `<approvals>/<token>`.
+   */
+  approvalState: (decision: Decision) => ApprovalState;
+  /**
+   * Hydrate from a resolved `snapshotPromise` during render. Idempotent per
+   * `source`; subscribers are notified in a microtask, never synchronously
+   * inside render.
+   */
+  adopt: (value: Snapshot | string, source: object) => void;
+  snapshot: () => Snapshot;
+  /** The tenant the store currently answers for. */
+  tenant: () => string | undefined;
+  /**
+   * Stops polls, drops in-flight results and persistence; the store keeps
+   * answering from its last snapshot.
+   */
+  dispose: () => void;
+};
+//#endregion
+//#region src/client/protected-action.d.ts
+type ProtectedActionState<T> = {
+  /** The last call's answer; `undefined` before the first call. */
+  readonly result: ActionResult<T> | undefined;
+  /** A call is in flight. */
+  readonly pending: boolean;
+};
+//#endregion
+//#region src/client/types.d.ts
+type ClientStatus = "ready" | "pending" | "stale" | "server-only";
+type PermissionState = {
+  readonly allowed: boolean;
+  readonly status: ClientStatus;
+  readonly decision: Decision;
+};
+type PermissionSet = {
+  readonly granted: readonly Permission[];
+  get: (permission: Permission) => PermissionState | undefined;
+};
+type ClientPermDock<V extends PolicyVocabulary = PolicyVocabulary> = PermDock<V> & {
+  status: (permission?: Permission, data?: unknown) => ClientStatus;
+  invalidate: (ref: Permission | {
+    readonly [key: string]: unknown;
+  }) => void;
+  refresh: (options?: {
+    readonly tenant?: string;
+  }) => Promise<void>;
+  clear: () => void;
+  subscribe: (listener: () => void) => () => void;
+};
+type ApprovalState = "not-needed" | "required" | "pending" | "approved" | "rejected" | "expired";
+type ApprovalHandle = {
+  readonly state: ApprovalState;
+  readonly token: string | undefined;
+  readonly request: (note?: string) => Promise<void>;
+};
+/**
+ * A protected server action wired to a control: the gate for its button, the
+ * last answer, and the approval its `approval-required` problem carries. The
+ * client decides nothing; the action answers.
+ */
+type ProtectedActionView<T> = ProtectedActionState<T> & {
+  readonly gate: GateView;
+  /** On an `approval-required` problem, the handle for its token. */
+  readonly approval: ApprovalHandle | undefined;
+};
+type ProtectedActionHandle<T> = ProtectedActionView<T> & {
+  readonly run: (input: unknown) => Promise<ActionResult<T>>;
+  /** Resends the last input with the approval token; `undefined` without one. */
+  readonly retry: () => Promise<ActionResult<T> | undefined>;
+};
+type SubjectView = {
+  readonly principal: Principal | null;
+  readonly actor: Actor | undefined;
+  readonly delegation: Delegation | undefined;
+  readonly expiresAt: number | undefined;
+  readonly simulated: boolean;
+};
+type TenantView = {
+  readonly tenant: string | null;
+  readonly tenants: readonly string[];
+  readonly switchTo: (id: string) => Promise<void>;
+  readonly status: ClientStatus;
+};
+type FilterResult<T> = readonly T[] & {
+  readonly partial: boolean;
+};
+/**
+ * Which held roles `useRoles` lists: those of a tenant (the active one by
+ * default), or only those on the memberships of one `scope`, and of one
+ * instance `id` of it.
+ */
+type RolesOptions = {
+  readonly tenant?: string;
+  readonly scope?: string;
+  readonly id?: string;
+};
+/**
+ * The provider options Vue, Svelte and Solid share; each adds its own reactive
+ * `snapshot`, `tenant`, `headers`, `verifier` and `defaults`.
+ */
+type ProviderOptionsBase = {
+  /**
+   * 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;
+  /** Read on every request, so a new `fetch` applies without a new store. */
+  readonly fetch?: typeof fetch;
+  readonly maxAge?: number;
+  /** Localised text for the describe helper. */
+  readonly messages?: DescribeMessages;
+  /** Called with each snapshot the store accepts. */
+  readonly onSnapshot?: NonNullable<ClientStoreOptions["onSnapshot"]>;
+  /** Called when the store drops its snapshot. */
+  readonly onClear?: () => void;
+  /** Milliseconds between approval status polls. Defaults to 2000. */
+  readonly approvalInterval?: number;
+  /**
+   * Triggers that refresh the snapshot, such as `eventSourceRefresh(url)`; read
+   * once.
+   */
+  readonly refreshOn?: readonly RefreshTrigger[];
+};
+/**
+ * How a control shows a permission it cannot use: hidden, or disabled with a
+ * reason.
+ */
+type GateMode = "hide" | "disable";
+/**
+ * Everything a permission-gated control renders from, in one value: a button, a
+ * menu item or a link reads these fields and decides nothing itself. The client
+ * is a hint; the server checks again.
+ */
+type GateView = {
+  /** The decision granted the action. */
+  readonly allowed: boolean;
+  /** The snapshot is loading; render the control disabled, not hidden. */
+  readonly pending: boolean;
+  /** `mode: "hide"` and the action is not available: render nothing. */
+  readonly hidden: boolean;
+  /**
+   * The control cannot run the action now (denied, pending or awaiting
+   * approval).
+   */
+  readonly disabled: boolean;
+  /** The decision needs a person's approval first; offer to request it. */
+  readonly needsApproval: boolean;
+  /**
+   * The plans that would grant the action, for an upgrade prompt; empty
+   * otherwise.
+   */
+  readonly upgrade: readonly string[];
+  /** Title and detail for a tooltip or an accessible description. */
+  readonly reason: DecisionDescription;
+  readonly decision: Decision;
+};
+//#endregion
+export { ClientStoreOptions as _, FilterResult as a, eventSourceRefresh as b, PermissionSet as c, ProtectedActionView as d, ProviderOptionsBase as f, ClientStore as g, TenantView as h, ClientStatus as i, PermissionState as l, SubjectView as m, ApprovalState as n, GateMode as o, RolesOptions as p, ClientPermDock as r, GateView as s, ApprovalHandle as t, ProtectedActionHandle as u, EventSourceRefreshOptions as v, RefreshTrigger as y };

package/dist/{types-BdtSDbBO.d.ts → types-B_tiYvk8.d.ts}

@@ -1,5 +1,5 @@
-import { Cn as RelationGrantee, Rt as Instant, ar as Subject, cr as AdapterId, fn as Approver, nr as Membership, o as ApprovalStage, on as WireDelegation, r as ApprovalMode } from "./policy-types-n0uRTsW8.js";
-import { V as AppData } from "./vocabulary-CN8H_9UF.js";
+import { Dn as RelationGrantee, Rt as Instant, fr as AdapterId, gn as Approver, lr as Subject, o as ApprovalStage, or as Membership, r as ApprovalMode, un as WireDelegation } from "./policy-types-CCiDRZBH.js";
+import { M as AppData } from "./permission-types-CAY-GU7e.js";
 //#region src/approvals/types.d.ts
 type ApprovalStatus = "pending" | "approved" | "rejected" | "expired";
 type ApprovalApprovers = {
@@ -12,30 +12,42 @@ type ApprovalApprovers = {
   readonly distinct?: boolean;
   /** Set when the approval no longer applies once the row's `version` changes. */
   readonly staleOn?: "resource-change";
-  /** Distinct approvers of `by` needed before `status` becomes `approved`; absent means 1. */
+  /**
+   * Distinct approvers of `by` needed before `status` becomes `approved`;
+   * absent means 1.
+   */
   readonly quorum?: number;
-  /** Who else may approve once the request has waited `after` seconds since `createdAt`. */
+  /**
+   * Who else may approve once the request has waited `after` seconds since
+   * `createdAt`.
+   */
   readonly escalation?: {
     readonly after: number;
     readonly to: Approver | readonly Approver[];
   };
 };
-/** One recorded approval: who gave it, when, and under `stages` the index of the stage it counts for. */
+/**
+ * One recorded approval: who gave it, when, and under `stages` the index of the
+ * stage it counts for.
+ */
 type ApprovalSignature = {
   readonly by: string;
   readonly at: string;
   readonly stage?: number;
   readonly vouched?: string;
-  /** The principal `by` approved for, when `by` acted under an `ApprovalDelegation`. */
+  /**
+   * The principal `by` approved for, when `by` acted under an
+   * `ApprovalDelegation`.
+   */
   readonly onBehalfOf?: string;
   /** The `ApprovalDelegation` id `onBehalfOf` was read from. */
   readonly delegation?: string;
 };
 /**
- * One out-of-office delegation: `delegate` may approve what `delegator`
- * could approve, from `from` until `until`. Both instants are required, so
- * a delegation cannot be open-ended. `permissions` and `resources` narrow
- * it; absent, it covers every request. `tenant` holds it to one tenant.
+ * One out-of-office delegation: `delegate` may approve what `delegator` could
+ * approve, from `from` until `until`. Both instants are required, so a
+ * delegation cannot be open-ended. `permissions` and `resources` narrow it;
+ * absent, it covers every request. `tenant` holds it to one tenant.
  */
 type ApprovalDelegation = {
   readonly id: string;
@@ -57,12 +69,12 @@ type ApprovalDelegation = {
 type ApprovalDelegationSource = {
   /** Names the implementation in errors and events. */
   readonly name?: string;
-  delegationsFor(query: {
+  delegationsFor: (query: {
     readonly delegate: string;
     readonly tenant?: string;
     /** RFC 3339. The source returns delegations active at this instant. */
     readonly at: string;
-  }): readonly ApprovalDelegation[] | Promise<readonly ApprovalDelegation[]>;
+  }) => readonly ApprovalDelegation[] | Promise<readonly ApprovalDelegation[]>;
 };
 type ApprovalSubjectSummary = {
   readonly principal: {
@@ -97,15 +109,24 @@ type ApprovalRequest = {
   readonly createdAt: string;
   readonly expiresAt: string;
   readonly status: ApprovalStatus;
-  /** Approvals given so far, oldest first; the request is `approved` once there are `approvers.quorum` of them. */
+  /**
+   * Approvals given so far, oldest first; the request is `approved` once there
+   * are `approvers.quorum` of them.
+   */
   readonly approvals?: readonly ApprovalSignature[];
   readonly resolvedAt?: string;
-  /** The approver whose verdict resolved the request (the last of `approvals` on a quorum), or `system:<by>` for a cancellation. */
+  /**
+   * The approver whose verdict resolved the request (the last of `approvals` on
+   * a quorum), or `system:<by>` for a cancellation.
+   */
   readonly resolvedBy?: string;
   readonly vouched?: string;
   readonly note?: string;
   readonly consumedAt?: string;
-  /** The application's own data, set when the request opens; plain JSON, never read by a decision. */
+  /**
+   * The application's own data, set when the request opens; plain JSON, never
+   * read by a decision.
+   */
   readonly x?: AppData;
 };
 type ApprovalVerdict = {
@@ -120,8 +141,8 @@ type ApprovalVerdict = {
    */
   readonly relations?: readonly string[];
   /**
-   * The `holder(permission)` approvers (by permission key) that `by` holds
-   * in the request's tenant, as `approverPermissions` read them from the
+   * The `holder(permission)` approvers (by permission key) that `by` holds in
+   * the request's tenant, as `approverPermissions` read them from the
    * approver's own instance. Server-side input, never from the request body.
    * Absent means none, so permission approvers match nobody.
    */
@@ -130,8 +151,8 @@ type ApprovalVerdict = {
   /**
    * Set when `by` is not an approver and acts for this principal under an
    * `ApprovalDelegation`. Server-side input: the handler resolves the
-   * delegator, and `applyApprovalVerdict` checks them again. `relations`
-   * and `permissions` are that principal's facts, never the delegate's.
+   * delegator, and `applyApprovalVerdict` checks them again. `relations` and
+   * `permissions` are that principal's facts, never the delegate's.
    */
   readonly onBehalfOf?: {
     readonly subject: Subject;
@@ -169,28 +190,28 @@ type ApprovalStore = {
   /** Names the implementation in errors and events. */
   readonly name?: string;
   /**
-   * Seconds a request opened against this store stays open when the
-   * caller sets no `ttl`; absent means `DEFAULT_APPROVAL_TTL`. A grant's
-   * `approval.ttl` still caps it.
+   * Seconds a request opened against this store stays open when the caller sets
+   * no `ttl`; absent means `DEFAULT_APPROVAL_TTL`. A grant's `approval.ttl`
+   * still caps it.
    */
   readonly ttl?: number;
-  create(request: ApprovalRequest): Promise<void> | void;
-  get(token: string): Promise<ApprovalRequest | null> | ApprovalRequest | null;
+  create: (request: ApprovalRequest) => Promise<void> | void;
+  get: (token: string) => Promise<ApprovalRequest | null> | ApprovalRequest | null;
   /**
    * The request with this `id`, for `approvalsHandler`, which routes by id.
    * Without it the handler pages through `list` to find the id.
    */
-  getById?(id: string): Promise<ApprovalRequest | null> | ApprovalRequest | null;
-  resolve(token: string, verdict: ApprovalVerdict): Promise<ApprovalRequest> | ApprovalRequest;
-  list(query: ApprovalListQuery): Promise<ApprovalPage> | ApprovalPage;
-  expire(now?: Instant): Promise<number> | number;
+  getById?: (id: string) => Promise<ApprovalRequest | null> | ApprovalRequest | null;
+  resolve: (token: string, verdict: ApprovalVerdict) => Promise<ApprovalRequest> | ApprovalRequest;
+  list: (query: ApprovalListQuery) => Promise<ApprovalPage> | ApprovalPage;
+  expire: (now?: Instant) => Promise<number> | number;
   /**
    * Marks an approved, unexpired, unconsumed request consumed and returns it;
    * returns `null` otherwise. Must be atomic: two concurrent calls for one
    * token never both return the request.
    */
-  consume(token: string, now?: Instant): Promise<ApprovalRequest | null> | ApprovalRequest | null;
-  cancel?(filter: ApprovalListFilter, meta: ApprovalCancelMeta): Promise<number> | number;
+  consume: (token: string, now?: Instant) => Promise<ApprovalRequest | null> | ApprovalRequest | null;
+  cancel?: (filter: ApprovalListFilter, meta: ApprovalCancelMeta) => Promise<number> | number;
 };
 type ApprovalResumeFailureCause = "approval-not-found" | "approval-pending" | "approval-rejected" | "approval-expired" | "approval-consumed";
 type ApprovalInspectResult = {
@@ -201,9 +222,15 @@ type ApprovalInspectResult = {
   readonly cause: ApprovalResumeFailureCause;
 };
 declare const APPROVAL_HEADER: "PermDock-Approval";
-/** Seconds a request stays open when neither the store nor the call sets a `ttl`. */
+/**
+ * Seconds a request stays open when neither the store nor the call sets a
+ * `ttl`.
+ */
 declare const DEFAULT_APPROVAL_TTL: number;
-/** The approvals a request needs in total: `approvers.quorum` (or 1), or the sum of its stages' quorums. */
+/**
+ * The approvals a request needs in total: `approvers.quorum` (or 1), or the sum
+ * of its stages' quorums.
+ */
 declare function approvalQuorum(request: ApprovalRequest): number;
 /**
  * The instant from which `approvers.escalation.to` may approve, in epoch

package/dist/{types-DqzsnlSA.js → types-CcUXciSj.js}

@@ -1,4 +1,4 @@
-import { a as durationOf } from "./time-DkWjdL98.js";
+import { a as durationOf } from "./time-nR1JesoH.js";
 //#region src/approvals/errors.ts
 var ApprovalError = class extends Error {
 	name = "ApprovalError";
@@ -21,7 +21,10 @@ const CODES = /* @__PURE__ */ new Set([
 function isApprovalErrorCode(value) {
 	return typeof value === "string" && CODES.has(value);
 }
-/** Matches by `name` and `code`, so an error from another copy of the module still maps. */
+/**
+* Matches by `name` and `code`, so an error from another copy of the module
+* still maps.
+*/
 function isApprovalError(value) {
 	if (!(value instanceof Error) || value.name !== "ApprovalError") return false;
 	const code = Reflect.get(value, "code");
@@ -30,9 +33,15 @@ function isApprovalError(value) {
 //#endregion
 //#region src/approvals/types.ts
 const APPROVAL_HEADER = "PermDock-Approval";
-/** Seconds a request stays open when neither the store nor the call sets a `ttl`. */
+/**
+* Seconds a request stays open when neither the store nor the call sets a
+* `ttl`.
+*/
 const DEFAULT_APPROVAL_TTL = 3600;
-/** The approvals a request needs in total: `approvers.quorum` (or 1), or the sum of its stages' quorums. */
+/**
+* The approvals a request needs in total: `approvers.quorum` (or 1), or the sum
+* of its stages' quorums.
+*/
 function approvalQuorum(request) {
 	const stages = request.approvers?.stages;
 	if (stages !== void 0) return stages.reduce((sum, stage) => sum + (stage.quorum ?? 1), 0);
@@ -48,7 +57,10 @@ function escalationOpenAt(request) {
 	if (seconds === void 0) return;
 	return Date.parse(request.createdAt) + seconds * 1e3;
 }
-/** The instant from which a stage's own `escalation.to` may approve it, in epoch milliseconds; `undefined` when it has none or `after` does not parse. */
+/**
+* The instant from which a stage's own `escalation.to` may approve it, in epoch
+* milliseconds; `undefined` when it has none or `after` does not parse.
+*/
 function stageEscalationOpenAt(request, stage) {
 	const seconds = durationOf(stage.escalation?.after);
 	if (seconds === void 0) return;