permdock 0.7.0 → 0.9.0

package/dist/ssf/index.js

@@ -1,11 +1,11 @@
 import { r as isRecord, t as compact } from "../compact-CAf557ZB.js";
-import { o as statusProblem } from "../problem-details-cn5X30gZ.js";
-import { o as epochSeconds } from "../time-DkWjdL98.js";
-import { n as readBodyText } from "../body-text-QcXok_SI.js";
-import { a as methodNotAllowed, c as problemResponse, d as validationProblem, o as notFoundProblem } from "../problem-CTviyH5L.js";
-import { t as cancelApprovals } from "../helpers-DY3vXuGs.js";
-import { i as issuerFromDiscovery, t as joseTokenVerifier } from "../verifier-DHuh-okk.js";
-import { t as memoryReplayStore } from "../replay-Du1tJjG7.js";
+import { o as statusProblem } from "../problem-details-CLDgX1KV.js";
+import { o as epochSeconds } from "../time-nR1JesoH.js";
+import { n as readBodyText } from "../body-text-DQhcmqdY.js";
+import { f as validationProblem, l as problemResponse, o as methodNotAllowed, s as notFoundProblem } from "../problem-BVLHFK33.js";
+import { t as cancelApprovals } from "../helpers-DJicaG6f.js";
+import { i as issuerFromDiscovery, t as joseTokenVerifier } from "../verifier-DUV6pLqZ.js";
+import { t as memoryReplayStore } from "../replay-BU09ad4L.js";
 import { t as timeoutSignal } from "../timeout-D51niuQP.js";
 //#region src/ssf/claims.ts
 function asSubject(mapped, session, issuer) {
@@ -162,8 +162,8 @@ const PUSH_TIMEOUT_MS = 3e4;
 const MAX_ERROR_BYTES = 16384;
 /**
 * Signs one event as an RFC 8417 Security Event Token (`typ: secevent+jwt`):
-* `sub_id` is the event's subject and `events` holds exactly one entry, as
-* SSF 1.0 requires. `iss` is the signer's own.
+* `sub_id` is the event's subject and `events` holds exactly one entry, as SSF
+* 1.0 requires. `iss` is the signer's own.
 */
 function signSet(event, signer, options) {
 	return signer.sign(compact({
@@ -200,10 +200,10 @@ async function errorBody(response) {
 	}
 }
 /**
-* Pushes one SET to a receiver (RFC 8935). A `2xx` is delivery; a `400`
-* maps the receiver's `err` to a cause; `401` and `403` are
-* `authentication-failed` and `access-denied`; a network failure, a timeout,
-* a `429` or a `5xx` is `unavailable` with `retry: true`. Never throws.
+* Pushes one SET to a receiver (RFC 8935). A `2xx` is delivery; a `400` maps
+* the receiver's `err` to a cause; `401` and `403` are `authentication-failed`
+* and `access-denied`; a network failure, a timeout, a `429` or a `5xx` is
+* `unavailable` with `retry: true`. Never throws.
 */
 async function pushSet(set, options) {
 	const fetchFn = options.fetch ?? globalThis.fetch;
@@ -295,7 +295,10 @@ function risc(name, subject, payload) {
 		payload: Object.freeze(payload)
 	});
 }
-/** RISC 1.0 event builders for the events PermDock's receiver treats as revoking every session. */
+/**
+* RISC 1.0 event builders for the events PermDock's receiver treats as revoking
+* every session.
+*/
 const riscEvents = Object.freeze({
 	accountDisabled: (input) => risc("account-disabled", input.subject, compact({ reason: input.reason })),
 	accountPurged: (input) => risc("account-purged", input.subject, {}),
@@ -437,8 +440,8 @@ const CHANGED_EVENTS = /* @__PURE__ */ new Set([
 ]);
 /**
 * When the replay record of a SET may be dropped: its `exp`, or for a SET
-* without one (RFC 8417 section 2.2) the end of its acceptance window, so
-* the same `jti` cannot pass verification again once the record is gone.
+* without one (RFC 8417 section 2.2) the end of its acceptance window, so the
+* same `jti` cannot pass verification again once the record is gone.
 */
 function replayExpiresAt(claims, clockTolerance = 0, maxTokenAge = DEFAULT_SET_MAX_AGE) {
 	if (typeof claims["exp"] === "number") return claims["exp"] + clockTolerance;
@@ -875,13 +878,16 @@ function createPermDock(policy, options) {
 }
 //#endregion
 //#region src/ssf/set-queue.ts
-/** The largest poll request body read: acknowledgements and errors for many SETs. */
+/**
+* The largest poll request body read: acknowledgements and errors for many
+* SETs.
+*/
 const MAX_POLL_BYTES = 262144;
 const DEFAULT_MAX_EVENTS = 100;
 /**
 * An in-process `SetQueue`: pending SETs per stream in insertion order. A
-* process restart loses them; a deployment with more than one instance needs
-* a shared queue.
+* process restart loses them; a deployment with more than one instance needs a
+* shared queue.
 */
 function memorySetQueue() {
 	const streams = /* @__PURE__ */ new Map();
@@ -943,10 +949,10 @@ function parsePollRequest(text) {
 	};
 }
 /**
-* The RFC 8936 poll endpoint over a `SetQueue`. It applies the request's
-* `acks` and `setErrs`, then answers `{ sets, moreAvailable }` with up to
-* `maxEvents` pending SETs. It answers at once whatever `returnImmediately`
-* says, which RFC 8936 section 2.4 allows.
+* The RFC 8936 poll endpoint over a `SetQueue`. It applies the request's `acks`
+* and `setErrs`, then answers `{ sets, moreAvailable }` with up to `maxEvents`
+* pending SETs. It answers at once whatever `returnImmediately` says, which RFC
+* 8936 section 2.4 allows.
 */
 function setPollHandler(options) {
 	const cap = options.maxEvents ?? DEFAULT_MAX_EVENTS;
@@ -1066,9 +1072,9 @@ function readDelivery(value) {
 	});
 }
 /**
-* The receiver-supplied properties of a stream request (SSF 1.0 section
-* 8.1.1). `previous` keeps the properties a PATCH leaves out; without it an
-* absent property takes its default. Transmitter-supplied properties are ignored.
+* The receiver-supplied properties of a stream request (SSF 1.0 section 8.1.1).
+* `previous` keeps the properties a PATCH leaves out; without it an absent
+* property takes its default. Transmitter-supplied properties are ignored.
 */
 function readProperties(body, previous) {
 	let delivery = previous?.delivery ?? { method: "urn:ietf:rfc:8936" };
@@ -1110,7 +1116,10 @@ async function owned(streams, id, owner) {
 	const stream = await streams.get(id);
 	return stream?.owner === owner ? stream : notFoundProblem();
 }
-/** Acknowledges every pending SET of `stream`; a queue that never empties is read at most until it repeats. */
+/**
+* Acknowledges every pending SET of `stream`; a queue that never empties is
+* read at most until it repeats.
+*/
 async function drain(queue, stream) {
 	let previous;
 	for (;;) {
@@ -1121,7 +1130,10 @@ async function drain(queue, stream) {
 		await Promise.all(pending.map(({ jti }) => Promise.resolve(queue.ack(stream, jti))));
 	}
 }
-/** Pushes the SETs a paused push stream held, oldest first, until one may be retried. */
+/**
+* Pushes the SETs a paused push stream held, oldest first, until one may be
+* retried.
+*/
 async function flush(queue, configuration, fetchFn) {
 	const { stream_id: stream, delivery } = configuration;
 	if (delivery.endpoint_url === void 0) return;
@@ -1170,9 +1182,9 @@ async function deliver(stream, status, jti, set, options) {
 }
 /**
 * Signs `event` once per distinct stream audience and delivers it to every
-* stream that is not disabled and has the event in `events_delivered`: a
-* push stream through `pushSet`, a poll stream or a paused stream into the
-* queue. Answers one row per stream that took the event.
+* stream that is not disabled and has the event in `events_delivered`: a push
+* stream through `pushSet`, a poll stream or a paused stream into the queue.
+* Answers one row per stream that took the event.
 */
 async function fanOutSet(event, options) {
 	const groups = /* @__PURE__ */ new Map();
@@ -1203,10 +1215,10 @@ async function fanOutSet(event, options) {
 }
 /**
 * An SSF 1.0 transmitter as one Fetch handler, routed by path suffix:
-* `/.well-known/ssf-configuration` (section 7.1), `/stream` (8.1.1),
-* `/status` (8.1.2), `/verify` (8.1.4) and `/poll` (RFC 8936). Each receiver
-* sees only the streams it created. Disabling or deleting a stream drops its
-* pending SETs; a paused stream holds them until it is enabled again.
+* `/.well-known/ssf-configuration` (section 7.1), `/stream` (8.1.1), `/status`
+* (8.1.2), `/verify` (8.1.4) and `/poll` (RFC 8936). Each receiver sees only
+* the streams it created. Disabling or deleting a stream drops its pending
+* SETs; a paused stream holds them until it is enabled again.
 */
 function ssfTransmitter(options) {
 	const base = (options.endpoint ?? options.issuer).replace(/\/+$/u, "");

package/dist/{standard-webhooks-DgFFD-Ga.js → standard-webhooks-D67a3nzk.js}

@@ -1,5 +1,5 @@
-import { m as rfc3339, p as nowSeconds } from "./time-DkWjdL98.js";
-import { n as readBodyText } from "./body-text-QcXok_SI.js";
+import { m as rfc3339, p as nowSeconds } from "./time-nR1JesoH.js";
+import { n as readBodyText } from "./body-text-DQhcmqdY.js";
 //#region src/server/standard-webhooks.ts
 const DEFAULT_TOLERANCE = 300;
 const JWKS_TTL_SECONDS = 300;
@@ -41,9 +41,9 @@ function validId(id) {
 	return id.length > 0 && id.length <= 256 && !/\s/u.test(id);
 }
 /**
-* Signs Standard Webhooks deliveries: `v1` HMAC-SHA256 with a `whsec_`
-* secret, `v1a` Ed25519 with a private JWK. Throws on an invalid key or id,
-* because both come from the sender's own configuration.
+* Signs Standard Webhooks deliveries: `v1` HMAC-SHA256 with a `whsec_` secret,
+* `v1a` Ed25519 with a private JWK. Throws on an invalid key or id, because
+* both come from the sender's own configuration.
 */
 function webhookSigner(options) {
 	if (options.keys.length === 0) throw new TypeError("PermDock: webhookSigner() needs at least one key");

package/dist/{standard-webhooks-B_qRg0ws.d.ts → standard-webhooks-DOYEuOLx.d.ts}

@@ -1,5 +1,5 @@
-import { Rt as Instant, ar as JsonWebKeyLike } from "./policy-types-B-F-qAZk.js";
-import { l as ReplayStore } from "./types-cTos-H7p.js";
+import { Wt as Instant, dr as JsonWebKeyLike } from "./policy-types-DGIO_gxq.js";
+import { l as ReplayStore } from "./types-DsHGPtkR.js";
 //#region src/server/standard-webhooks.d.ts
 /** The three Standard Webhooks headers a delivery carries. */
 type WebhookHeaders = {
@@ -34,7 +34,7 @@ type WebhookMessage = {
   readonly now?: Instant;
 };
 type WebhookSigner = {
-  sign(message: WebhookMessage): Promise<WebhookHeaders>;
+  sign: (message: WebhookMessage) => Promise<WebhookHeaders>;
 };
 /** An Ed25519 public JWK set for `v1a`, or the URL that serves one. */
 type WebhookJwks = {
@@ -70,12 +70,12 @@ type VerifiedWebhookMessage = {
 };
 type WebhookVerifier = {
   /** Never throws; claims the `webhook-id` only after a signature verifies. */
-  verify(input: WebhookInput): Promise<VerifiedWebhookMessage>;
+  verify: (input: WebhookInput) => Promise<VerifiedWebhookMessage>;
 };
 /**
- * Signs Standard Webhooks deliveries: `v1` HMAC-SHA256 with a `whsec_`
- * secret, `v1a` Ed25519 with a private JWK. Throws on an invalid key or id,
- * because both come from the sender's own configuration.
+ * Signs Standard Webhooks deliveries: `v1` HMAC-SHA256 with a `whsec_` secret,
+ * `v1a` Ed25519 with a private JWK. Throws on an invalid key or id, because
+ * both come from the sender's own configuration.
  */
 declare function webhookSigner(options: WebhookSignerOptions): WebhookSigner;
 /**

package/dist/{store-DSP9oGvh.js → store-RNFvaJJv.js}

@@ -1,10 +1,10 @@
 import { t as compact } from "./compact-CAf557ZB.js";
-import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
-import { i as flattenApprovers } from "./approvers-CqPOLD-o.js";
-import { a as durationOf, i as dateAt } from "./time-DkWjdL98.js";
-import { c as rootMembershipId } from "./scopes-BHsc-wp-.js";
-import { n as matchGrantee } from "./grantee-match-0RtHWQDx.js";
-import { a as escalationOpenAt, i as approverRelationKey, o as stageEscalationOpenAt, r as approvalQuorum, s as ApprovalError } from "./types-DqzsnlSA.js";
+import { n as freezeDeep } from "./freeze-jjan0lCv.js";
+import { i as flattenApprovers } from "./approvers-B4r0N_Uz.js";
+import { a as durationOf, i as dateAt } from "./time-nR1JesoH.js";
+import { c as rootMembershipId } from "./scopes-0Up_UA2t.js";
+import { n as matchGrantee } from "./grantee-match-7RZZvoT_.js";
+import { a as escalationOpenAt, i as approverRelationKey, o as stageEscalationOpenAt, r as approvalQuorum, s as ApprovalError } from "./types-CcUXciSj.js";
 //#region src/approvals/page.ts
 const DEFAULT_PAGE_SIZE = 50;
 const MAX_PAGE_SIZE = 200;
@@ -26,7 +26,10 @@ function compare(a, b) {
 function encodeApprovalCursor(request) {
 	return JSON.stringify(positionOf(request));
 }
-/** The `(createdAt, token)` position a `next` cursor names, or `null` for one that does not parse. */
+/**
+* The `(createdAt, token)` position a `next` cursor names, or `null` for one
+* that does not parse.
+*/
 function decodeApprovalCursor(cursor) {
 	try {
 		const parsed = JSON.parse(cursor);
@@ -38,8 +41,8 @@ function decodeApprovalCursor(cursor) {
 /**
 * Pages already-filtered requests in `(createdAt, token)` order, as the
 * built-in stores do: `limit` within 1 to 200 (50 when absent), `cursor` from
-* the previous page's `next`, and no items for a cursor that does not parse.
-* A custom `ApprovalStore` that filters in memory returns it from `list`.
+* the previous page's `next`, and no items for a cursor that does not parse. A
+* custom `ApprovalStore` that filters in memory returns it from `list`.
 */
 function pageApprovals(matching, query) {
 	const after = query.cursor === void 0 ? void 0 : decodeApprovalCursor(query.cursor);
@@ -53,7 +56,10 @@ function pageApprovals(matching, query) {
 		next: encodeApprovalCursor(last)
 	} : { items };
 }
-/** Every matching request of `store`, following `next` until the last page (at most 1000 pages of 200). */
+/**
+* Every matching request of `store`, following `next` until the last page (at
+* most 1000 pages of 200).
+*/
 function listAllApprovals(store, filter) {
 	const collect = async (cursor, pages, items) => {
 		const page = await store.list(cursor === void 0 ? {
@@ -74,8 +80,8 @@ function listAllApprovals(store, filter) {
 /**
 * The tenants a subject acts in for approvals: `principal.tenant` and the
 * instance of every membership at the first scope. A membership at a nested
-* scope (a team, or one with `within`) names no tenant, even when its parent
-* is the request's tenant.
+* scope (a team, or one with `within`) names no tenant, even when its parent is
+* the request's tenant.
 */
 function membershipTenants(subject) {
 	const principal = subject.principal;
@@ -172,14 +178,14 @@ function vouchedRule(verdict) {
 	return typeof verdict.vouched === "string" && verdict.vouched !== "" ? verdict.vouched : void 0;
 }
 /**
-* Refuses `by` as an approver of `request`, or returns the index of the
-* stage the approval counts for (`undefined` without `stages`). Eligibility
-* is `approvers.by` or, under `stages`, the first incomplete stage
-* (`sequential`) or any incomplete stage (`all`); `approvers.escalation.to`
-* is eligible too once the request has waited `escalation.after`. A
-* principal who already approved is refused, so one person never completes
-* two stages. `relations` are the relation approvers `by` holds on the
-* request's resource (see `ApprovalVerdict.relations`).
+* Refuses `by` as an approver of `request`, or returns the index of the stage
+* the approval counts for (`undefined` without `stages`). Eligibility is
+* `approvers.by` or, under `stages`, the first incomplete stage (`sequential`)
+* or any incomplete stage (`all`); `approvers.escalation.to` is eligible too
+* once the request has waited `escalation.after`. A principal who already
+* approved is refused, so one person never completes two stages. `relations`
+* are the relation approvers `by` holds on the request's resource (see
+* `ApprovalVerdict.relations`).
 */
 function assertApprover(request, by, requireDistinctApprover, at, relations = [], permissions = []) {
 	const now = dateAt(at);
@@ -219,12 +225,12 @@ function isSystemSubject(by) {
 	return by.actor?.kind === "system";
 }
 /**
-* The request after `verdict`, for a store to persist: a rejection resolves
-* it; an approval is appended to `approvals` and resolves it once there are
-* `approvers.quorum` (default 1). Throws an `ApprovalError` when the request
-* is not pending, has expired or `verdict.by` may not approve it. Stores
-* should write the result only when the stored row is still pending with the
-* same number of approvals, so two approvers racing both count.
+* The request after `verdict`, for a store to persist: a rejection resolves it;
+* an approval is appended to `approvals` and resolves it once there are
+* `approvers.quorum` (default 1). Throws an `ApprovalError` when the request is
+* not pending, has expired or `verdict.by` may not approve it. Stores should
+* write the result only when the stored row is still pending with the same
+* number of approvals, so two approvers racing both count.
 */
 function applyApprovalVerdict(request, verdict, at) {
 	const now = dateAt(at);

package/dist/{store-options-B_poyYvg.js → store-options-Dil3lraY.js}

@@ -1,11 +1,11 @@
 import { t as compact } from "./compact-CAf557ZB.js";
-import { g as secondsOf } from "./time-DkWjdL98.js";
-import { c as rowIdOf } from "./delegation-C5rOdTp5.js";
-import { c as nowSeconds } from "./tenancy-CmeBQ6Nv.js";
-import { n as payloadDigest } from "./token-2qYDvXz2.js";
-import { n as parseSnapshot } from "./snapshot-CbGmYiJx.js";
-import { c as snapshotClaim } from "./where-scope-wq2coopv.js";
-import { n as fromSnapshot, t as emptySnapshot } from "./from-snapshot-Bz469dIh.js";
+import { g as secondsOf } from "./time-nR1JesoH.js";
+import { c as rowIdOf } from "./delegation-CDB6_keF.js";
+import { c as nowSeconds } from "./tenancy-5d1zVBvK.js";
+import { n as payloadDigest } from "./token-DC9EQiet.js";
+import { n as parseSnapshot } from "./snapshot-CXlzi69u.js";
+import { c as snapshotClaim } from "./where-scope-DlCdCM_8.js";
+import { n as fromSnapshot, t as emptySnapshot } from "./from-snapshot-DCakWRsr.js";
 import { t as timeoutSignal } from "./timeout-D51niuQP.js";
 //#region src/client/source.ts
 /** A compact JWS: three non-empty dot-separated parts. */
@@ -131,7 +131,10 @@ const NO_ENDPOINT = {
 	}],
 	alternatives: []
 };
-/** The row's id under the snapshot's id field, or `undefined` for a row without one. */
+/**
+* The row's id under the snapshot's id field, or `undefined` for a row without
+* one.
+*/
 function rowId(snapshot, permission, data) {
 	const id = rowIdOf(data, snapshot.ids?.[permission.resource]);
 	return id === "*" ? void 0 : id;
@@ -140,7 +143,10 @@ function cacheKey(snapshot, permission, data) {
 	if (data === void 0) return `${permission.key}:*`;
 	return `${permission.key}:${rowId(snapshot, permission, data) ?? `#${payloadDigest(data)}`}`;
 }
-/** Collects the checks the snapshot cannot answer and posts them as one AuthZEN batch per microtask. */
+/**
+* Collects the checks the snapshot cannot answer and posts them as one AuthZEN
+* batch per microtask.
+*/
 function createBatch(options) {
 	const { answers, endpoint } = options;
 	let queued = [];
@@ -230,8 +236,75 @@ function createBatch(options) {
 	};
 }
 //#endregion
+//#region src/client/refresh-on.ts
+const DEFAULT_TYPES = ["com.permdock.membership.*", "com.permdock.catalog.*"];
+const REFRESH_DELAY = 250;
+function matches(type, patterns) {
+	return patterns.some((pattern) => pattern.endsWith("*") ? type.startsWith(pattern.slice(0, -1)) : type === pattern);
+}
+function eventType(data) {
+	if (typeof data !== "string") return;
+	try {
+		const parsed = JSON.parse(data);
+		if (typeof parsed === "object" && parsed !== null && "type" in parsed && typeof parsed.type === "string") return parsed.type;
+	} catch {
+		return;
+	}
+}
+/**
+* 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.
+*/
+function eventSourceRefresh(url, options = {}) {
+	const types = options.types ?? DEFAULT_TYPES;
+	return (refresh) => {
+		if (typeof globalThis.EventSource !== "function") return () => void 0;
+		const source = new globalThis.EventSource(url, { withCredentials: options.withCredentials === true });
+		source.addEventListener("message", (event) => {
+			const type = eventType(event.data);
+			if (type !== void 0 && matches(type, types)) refresh();
+		});
+		return () => {
+			source.close();
+		};
+	};
+}
+/**
+* Runs `triggers` while `start()` holds, folding calls within 250 ms into one
+* `refresh`. `skip()` answering `true` drops a call: after `clear()` or
+* `dispose()` nothing refetches.
+*/
+function refreshTriggers(triggers, refresh, skip) {
+	let offs = [];
+	let timer;
+	const fire = () => {
+		if (skip() || timer !== void 0) return;
+		timer = setTimeout(() => {
+			timer = void 0;
+			if (!skip()) refresh();
+		}, REFRESH_DELAY);
+	};
+	return {
+		start() {
+			if (offs.length === 0) offs = triggers.map((trigger) => trigger(fire));
+		},
+		stop() {
+			for (const off of offs) off();
+			offs = [];
+			if (timer !== void 0) {
+				clearTimeout(timer);
+				timer = void 0;
+			}
+		}
+	};
+}
+//#endregion
 //#region src/client/request.ts
-/** Milliseconds a decision, refresh or approval request may take; a slower one is an error like a failed request. */
+/**
+* Milliseconds a decision, refresh or approval request may take; a slower one
+* is an error like a failed request.
+*/
 const STORE_TIMEOUT_MS = 1e4;
 function storeRequest(fetchImpl, headers) {
 	return (url, body) => fetchImpl(url, {
@@ -313,6 +386,7 @@ function createClientStore(options) {
 	let generation = 0;
 	let disposed = false;
 	let staleNext = options.stale === true;
+	let cleared = false;
 	let rawJws;
 	const request = storeRequest(fetchImpl, () => typeof options.headers === "function" ? options.headers() : options.headers);
 	const emit = () => {
@@ -364,6 +438,7 @@ function createClientStore(options) {
 		reset();
 		if ((snapshot.subject.principal?.id ?? null) !== (next.subject.principal?.id ?? null)) approvals.forget();
 		snapshot = next;
+		cleared = false;
 		instance = fromSnapshot(snapshot, compact({ tenant }));
 		base = "ready";
 		if (staleNext && next.subject.principal !== null) {
@@ -511,12 +586,21 @@ function createClientStore(options) {
 			decision
 		};
 	};
+	const triggers = refreshTriggers(server ? [] : options.refreshOn ?? [], () => {
+		cached.refresh().catch(() => void 0);
+	}, () => disposed || cleared);
 	const subscribe = (listener) => {
 		listeners.add(listener);
-		if (listeners.size === 1) approvals.resume();
+		if (listeners.size === 1) {
+			approvals.resume();
+			triggers.start();
+		}
 		return () => {
 			listeners.delete(listener);
-			if (listeners.size === 0) approvals.stop();
+			if (listeners.size === 0) {
+				approvals.stop();
+				triggers.stop();
+			}
 		};
 	};
 	const wrap = (permdock) => {
@@ -596,6 +680,7 @@ function createClientStore(options) {
 				reset();
 				tenant = options.tenant;
 				snapshot = emptySnapshot();
+				cleared = true;
 				instance = fromSnapshot(snapshot, compact({ tenant }));
 				base = "server-only";
 				approvals.forget();
@@ -679,6 +764,7 @@ function createClientStore(options) {
 			generation += 1;
 			batch.clear();
 			approvals.forget();
+			triggers.stop();
 			listeners.clear();
 		},
 		requestApproval: approvals.request
@@ -688,7 +774,10 @@ function createClientStore(options) {
 }
 //#endregion
 //#region src/client/store-options.ts
-/** One hint per store: the first check `endpoint: false` turns into a `server-only` denial. */
+/**
+* One hint per store: the first check `endpoint: false` turns into a
+* `server-only` denial.
+*/
 function hintOnce() {
 	let shown = false;
 	return (permission) => {
@@ -723,8 +812,9 @@ function adapterStore(options, snapshot, native) {
 		stale: native?.stale,
 		onSnapshot: both(native?.onSnapshot, options.onSnapshot),
 		onClear: both(native?.onClear, options.onClear),
-		approvalInterval: options.approvalInterval
+		approvalInterval: options.approvalInterval,
+		refreshOn: options.refreshOn
 	}));
 }
 //#endregion
-export { isPromiseLike as i, storeOf as n, isJws as r, adapterStore as t };
+export { isPromiseLike as a, isJws as i, storeOf as n, eventSourceRefresh as r, adapterStore as t };

package/dist/stores-DZJvxFIZ.d.ts

@@ -0,0 +1,59 @@
+import { Un as Decision, fr as Membership, j as PolicyVocabulary } from "./policy-types-DGIO_gxq.js";
+import { u as Permission } from "./permission-types-CAY-GU7e.js";
+import { r as Role } from "./vocabulary-DEJ5j4mR.js";
+import { d as UncheckedData, s as RowData } from "./permdock-CprAPN3w.js";
+import { r as DescribeOptions, t as DecisionDescription } from "./describe-BbFPBSms.js";
+import { n as ProtectedAction } from "./action-result-BcudBQOF.js";
+import { a as FilterResult, c as PermissionSet, h as TenantView, l as PermissionState, m as SubjectView, o as GateMode, p as RolesOptions, r as ClientPermDock, s as GateView, t as ApprovalHandle } from "./types-tQB2CEnY.js";
+import { n as ProtectedActionReadable, r as SveltePermDockOptions } from "./types-CEinc15V.js";
+import { Readable } from "svelte/store";
+//#region src/svelte/stores.d.ts
+declare function setPermDock(options: SveltePermDockOptions): ClientPermDock;
+declare function getPermDock<V extends PolicyVocabulary = PolicyVocabulary>(): ClientPermDock<V>;
+/**
+ * `describe` with the provider's `messages`; a call's own `messages` win. Call
+ * it during component init.
+ */
+declare function getDescribe(): (decision: Decision, options?: DescribeOptions) => DecisionDescription;
+declare function permission<D>(reference: Permission, data?: () => UncheckedData<D>): Readable<PermissionState>;
+declare function permission<P extends Permission>(reference: P, data?: () => RowData<P>): Readable<PermissionState>;
+/**
+ * What a permission-gated control renders, as `useGate` in React: `hidden`,
+ * `disabled`, `needsApproval`, `upgrade` and a `reason` in the provider's
+ * `messages`. Call it during component initialisation.
+ */
+declare function gate<D>(reference: Permission, data?: () => UncheckedData<D>, options?: {
+  readonly mode?: GateMode;
+}): Readable<GateView>;
+declare function gate<P extends Permission>(reference: P, data?: () => RowData<P>, options?: {
+  readonly mode?: GateMode;
+}): Readable<GateView>;
+declare function permissions(references: () => readonly Permission[], data?: () => unknown): Readable<PermissionSet>;
+declare function filtered<T>(reference: Permission<string, NoInfer<T>, "instance">, rows: () => readonly T[]): Readable<FilterResult<T>>;
+declare function tenant(): Readable<TenantView>;
+declare function memberships(): Readable<readonly Membership[]>;
+declare function roles(options?: () => RolesOptions): Readable<{
+  readonly roles: readonly Role[];
+}>;
+declare function assignable(): Readable<readonly Role[]>;
+type AssignableOptions = {
+  readonly tenant?: string;
+} | (() => {
+  readonly tenant?: string;
+});
+declare function assignablePermissions(options?: AssignableOptions): Readable<readonly Permission[]>;
+declare function subject(): Readable<SubjectView>;
+declare function approval(decision: () => Decision): Readable<ApprovalHandle>;
+/**
+ * A `protectAction` server action wired to a control, as `useProtectedAction`
+ * in React: a readable store of `gate`, `result`, `pending` and `approval`,
+ * with `run` and `retry`. Call it during component initialisation.
+ */
+declare function protectedAction<T, D>(action: ProtectedAction<T>, reference: Permission, data?: () => UncheckedData<D>, options?: {
+  readonly mode?: GateMode;
+}): ProtectedActionReadable<T>;
+declare function protectedAction<T, P extends Permission>(action: ProtectedAction<T>, reference: P, data?: () => RowData<P>, options?: {
+  readonly mode?: GateMode;
+}): ProtectedActionReadable<T>;
+//#endregion
+export { gate as a, memberships as c, protectedAction as d, roles as f, tenant as h, filtered as i, permission as l, subject as m, assignable as n, getDescribe as o, setPermDock as p, assignablePermissions as r, getPermDock as s, approval as t, permissions as u };

package/dist/{stores-BqEuHC05.js → stores-DxZWDXCs.js}

@@ -1,6 +1,7 @@
-import { a as livePermDock, c as rolesView, d as subjectView, f as tenantView, n as describeWith, o as permissionSet, r as filterResult, t as approvalHandle } from "./views-BB8E9dTP.js";
-import { n as getUi, r as providePermDock, t as getStore } from "./context--uM9V3Ui.js";
-import { readable, toStore } from "svelte/store";
+import { n as actionRunner, t as actionApproval } from "./protected-action-DUYqb-Ma.js";
+import { a as livePermDock, c as rolesView, d as subjectView, f as tenantView, i as gateView, n as describeWith, o as permissionSet, r as filterResult, t as approvalHandle } from "./views-CD8wuL4Z.js";
+import { n as getUi, r as providePermDock, t as getStore } from "./context-BnIzxTNE.js";
+import { derived, readable, toStore, writable } from "svelte/store";
 //#region src/svelte/stores.ts
 function fromStore(store, compute) {
 	return readable(compute(), (set) => {
@@ -23,7 +24,10 @@ function setPermDock(options) {
 function getPermDock() {
 	return sveltePermDock(getStore());
 }
-/** `describe` with the provider's `messages`; a call's own `messages` win. Call it during component init. */
+/**
+* `describe` with the provider's `messages`; a call's own `messages` win. Call
+* it during component init.
+*/
 function getDescribe() {
 	return describeWith(getUi().messages);
 }
@@ -33,6 +37,16 @@ function permission(reference, data) {
 function permissionFor(store, reference, data) {
 	return fromStore(store, () => store.permissionState(reference, data?.()));
 }
+function gate(reference, data, options = {}) {
+	return gateFor(getStore(), reference, data, {
+		...options,
+		describe: getDescribe()
+	});
+}
+function gateFor(store, reference, data, options = {}) {
+	const describeDecision = options.describe ?? describeWith(void 0);
+	return fromStore(store, () => gateView(store.permissionState(reference, data?.()), (decision) => describeDecision(decision, { permission: reference }), options.mode));
+}
 function permissions(references, data) {
 	return permissionsFor(getStore(), references, data);
 }
@@ -87,5 +101,28 @@ function approval(decision) {
 function approvalFor(store, decision) {
 	return fromStore(store, () => approvalHandle(store, decision()));
 }
+function protectedAction(action, reference, data, options = {}) {
+	return protectedActionFor(getStore(), action, reference, data, {
+		...options,
+		describe: getDescribe()
+	});
+}
+function protectedActionFor(store, action, reference, data, options = {}) {
+	const state = writable({
+		result: void 0,
+		pending: false
+	});
+	const runner = actionRunner(() => action, state.set);
+	return {
+		subscribe: derived([gateFor(store, reference, data, options), state], ([gated, current]) => ({
+			gate: gated,
+			result: current.result,
+			pending: current.pending,
+			approval: actionApproval(store, current.result)
+		})).subscribe,
+		run: runner.run,
+		retry: runner.retry
+	};
+}
 //#endregion
-export { getDescribe as a, permission as c, setPermDock as d, subject as f, filtered as i, permissions as l, assignable as n, getPermDock as o, tenant as p, assignablePermissions as r, memberships as s, approval as t, roles as u };
+export { gate as a, memberships as c, protectedAction as d, roles as f, tenant as h, filtered as i, permission as l, subject as m, assignable as n, getDescribe as o, setPermDock as p, assignablePermissions as r, getPermDock as s, approval as t, permissions as u };