permdock 0.7.0 → 0.9.0

package/dist/{permdock-BfWEeMqk.js → permdock-BvjivVb9.js}

@@ -1,33 +1,36 @@
 import { n as isReadonlyArray, r as isRecord, t as compact } from "./compact-CAf557ZB.js";
-import { n as freezeDeep, t as freezeCopy } from "./freeze-CrU8nQeX.js";
-import { n as PermDockValidationError } from "./validation-error-ZfUHbKvf.js";
-import { a as deniedMessage, i as approvalMessage, n as PermDockDeniedError, t as PermDockApprovalRequiredError } from "./errors-BKy0EfhN.js";
-import { t as attachInternals } from "./internals-Dk8A8fX3.js";
-import { _ as keyToScope, a as getResource, c as listPermissions, g as formerScopes } from "./permission-registry-DpPtSKNZ.js";
-import { n as isThenable } from "./thenable-yD7SabqG.js";
-import { i as readAppData } from "./app-data-MuyzVqX8.js";
-import { f as scopeList, h as tenantOf, o as normalizeMemberships } from "./scopes-BHsc-wp-.js";
-import { o as pickVisible, s as sanitizeContext } from "./validity-CZ7-y0Cj.js";
-import { c as nowSeconds, d as resolveActiveTenant, m as tenantsOf, p as scopeField, t as heldRoleNamesIn, u as relatesTo } from "./tenancy-CmeBQ6Nv.js";
-import { u as policyX } from "./policy-DaJy4nK4.js";
-import { t as byCodePoint } from "./compare-pfyVnBjE.js";
-import { D as emptyListeners, E as emitSafe, N as contactMemberships, O as finish, P as isContact, i as customRolesFor, o as roleSourceFor, r as assignableNamesFor, s as sourceName, t as evaluate, u as customGrantsFor, w as unknownLevelsFor } from "./evaluate-B_oqFbWC.js";
-import { a as whereGrant, c as applyRoleKinds, i as collectSnapshotGrants, l as audiencesOf, o as heldRoleNames, p as asMembershipSource, r as assignableIn, s as roleLeaf, t as snapshotOf } from "./instance-snapshot-CjcwnEiV.js";
-import { r as relationReader, t as pendingRelations } from "./relations-BnCWnJGI.js";
-import { r as snapshotGrant } from "./snapshot-CbGmYiJx.js";
-import { a as decideForTarget, i as permittedIds, o as deniedFor, r as mayUse, s as signSnapshot, t as whereFromGrants } from "./where-scope-wq2coopv.js";
-import { i as decideAllWith, n as canAllWith } from "./checks-BC_0mPIq.js";
+import { n as freezeDeep, t as freezeCopy } from "./freeze-jjan0lCv.js";
+import { n as PermDockValidationError } from "./validation-error-CYg2kJEw.js";
+import { a as deniedMessage, i as approvalMessage, n as PermDockDeniedError, t as PermDockApprovalRequiredError } from "./errors-B6R_lg2a.js";
+import { t as attachInternals } from "./internals-B3IgHrvo.js";
+import { _ as keyToScope, a as getResource, c as listPermissions, g as formerScopes } from "./permission-registry-B8tYxPIt.js";
+import { n as isThenable } from "./thenable-BNSM1U2R.js";
+import { i as readAppData } from "./app-data-UNNm07jV.js";
+import { f as scopeList, h as tenantOf, o as normalizeMemberships } from "./scopes-0Up_UA2t.js";
+import { o as pickVisible, s as sanitizeContext } from "./validity-Buc7w8E9.js";
+import { t as byCodePoint } from "./compare-DTfyUunF.js";
+import { c as nowSeconds, d as resolveActiveTenant, m as tenantsOf, p as scopeField, t as heldRoleNamesIn, u as relatesTo } from "./tenancy-5d1zVBvK.js";
+import { d as policyX } from "./policy-CLQ8__GF.js";
+import { D as emptyListeners, E as emitSafe, N as contactMemberships, O as finish, P as isContact, i as customRolesFor, o as roleSourceFor, r as assignableNamesFor, s as sourceName, t as evaluate, u as customGrantsFor, w as unknownLevelsFor } from "./evaluate-BAmf_AQd.js";
+import { c as heldRoleNames, d as audiencesOf, g as asMembershipSource, i as assignableIn, l as roleLeaf, o as collectSnapshotGrants, s as whereGrant, t as snapshotOf, u as applyRoleKinds } from "./instance-snapshot-DuWf1cT3.js";
+import { r as relationReader, t as pendingRelations } from "./relations-BxvRvDHK.js";
+import { i as snapshotGrant } from "./snapshot-CXlzi69u.js";
+import { a as decideForTarget, i as permittedIds, o as deniedFor, r as mayUse, s as signSnapshot, t as whereFromGrants } from "./where-scope-DlCdCM_8.js";
+import { i as decideAllWith, n as canAllWith } from "./checks-CGkP3Z7A.js";
 import { r as isSubject, t as anonymousSubject } from "./subject-BGoM5o8B.js";
 //#region src/core/app.ts
 const APP = Symbol.for("permdock.app");
-/** The app definition bound to `policy` by `defineApp`, or `undefined` for a plain policy. */
+/**
+* The app definition bound to `policy` by `defineApp`, or `undefined` for a
+* plain policy.
+*/
 function appOf(policy) {
 	const value = Reflect.get(policy, APP);
 	return value === void 0 ? void 0 : value;
 }
 /**
-* `options` with the app's values under it, key by key, for an adapter
-* factory to call first: `options = withApp(policy, options)`.
+* `options` with the app's values under it, key by key, for an adapter factory
+* to call first: `options = withApp(policy, options)`.
 */
 function withApp(policy, options) {
 	const app = appOf(policy);
@@ -39,7 +42,10 @@ function withApp(policy, options) {
 }
 //#endregion
 //#region src/core/assert-decision.ts
-/** `assert`'s outcome: the granted decision, or the error a refusal throws after `onDenied` runs. */
+/**
+* `assert`'s outcome: the granted decision, or the error a refusal throws after
+* `onDenied` runs.
+*/
 function assertDecision(policy, subject, permission, data, decision, onDenied) {
 	if (decision.outcome === "granted") return decision;
 	if (onDenied !== void 0) onDenied(decision);
@@ -72,7 +78,10 @@ function assertDecision(policy, subject, permission, data, decision, onDenied) {
 }
 //#endregion
 //#region src/core/instance-env.ts
-/** The environment `derive(options)` builds on: `base` with the sources `options` replaces loaded again. */
+/**
+* The environment `derive(options)` builds on: `base` with the sources
+* `options` replaces loaded again.
+*/
 function deriveEnv(policy, subject, base, relationCache, options) {
 	const scopes = scopeList(policy.scopes);
 	const tenants = tenantsOf(subject.principal, scopes);
@@ -140,7 +149,10 @@ function simulateEvent(policy, subject, env, evaluated) {
 }
 //#endregion
 //#region src/core/instance.ts
-/** Each round reads one more layer: link hops, then the chain, then nested groups. */
+/**
+* Each round reads one more layer: link hops, then the chain, then nested
+* groups.
+*/
 const LOAD_ROUNDS = 48;
 function buildInstance(policy, subject, envBase, team) {
 	const listeners = emptyListeners();
@@ -500,6 +512,96 @@ function buildInstance(policy, subject, envBase, team) {
 	return Object.freeze(instance);
 }
 //#endregion
+//#region src/core/freshness.ts
+function versionQuery(principal, issuedAt) {
+	return compact({
+		id: principal.id,
+		roles: principal.roles,
+		memberships: principal.memberships,
+		authzVersion: principal.authzVersion,
+		issuedAt
+	});
+}
+function threw(source, auth) {
+	auth.push({
+		reason: "source-threw",
+		source: "memberships",
+		...sourceName(source)
+	});
+}
+/**
+* `onStale: 'reread'`: a token behind the source's version has its memberships
+* (and global roles, with `readRoles`) read live; a version that cannot be read
+* keeps the claims and marks the subject stale.
+*/
+function rereadStale(source, principal, issuedAt, context, read, auth, readRoles) {
+	const claims = principal.memberships ?? [];
+	const claimed = principal.authzVersion;
+	const judge = (current) => typeof claimed === "number" && current !== void 0 && claimed >= current ? "fresh" : "reread";
+	const unknown = () => {
+		threw(source, auth);
+		return "unknown";
+	};
+	let freshness;
+	try {
+		const current = source.version?.(versionQuery(principal, issuedAt), context);
+		freshness = isThenable(current) ? Promise.resolve(current).then(judge, unknown) : judge(current);
+	} catch {
+		freshness = unknown();
+	}
+	const failed = () => {
+		threw(source, auth);
+		return [];
+	};
+	const rolesOf = (found) => {
+		if (found !== "reread" || readRoles === void 0) return;
+		try {
+			const roles = readRoles();
+			return isThenable(roles) ? Promise.resolve(roles).catch(failed) : roles;
+		} catch {
+			return failed();
+		}
+	};
+	if (isThenable(freshness)) {
+		const settled = freshness.then((found) => ({
+			found,
+			roles: rolesOf(found)
+		}));
+		return {
+			memberships: settled.then(({ found }) => found === "reread" ? read() : claims),
+			stale: settled.then(({ found }) => found === "unknown"),
+			roles: settled.then(({ roles }) => roles)
+		};
+	}
+	return compact({
+		memberships: freshness === "reread" ? read() : claims,
+		stale: freshness === "unknown",
+		roles: rolesOf(freshness)
+	});
+}
+/**
+* Whether the token's memberships are behind the source for `fresh`
+* permissions. Live memberships are never stale; token memberships are stale
+* unless a source reports a version the token's `authzVersion` has reached.
+*/
+function staleness(policy, principal, source, given, auth) {
+	if ((policy.fresh ?? []).length === 0 || principal === null || given.live) return false;
+	if (given.stale !== void 0) return given.stale;
+	const claimed = principal.authzVersion;
+	if (source?.version === void 0 || typeof claimed !== "number") return true;
+	const compare = (current) => current === void 0 || claimed < current;
+	try {
+		const current = source.version(versionQuery(principal, given.issuedAt), given.context);
+		return isThenable(current) ? Promise.resolve(current).then(compare, () => {
+			threw(source, auth);
+			return true;
+		}) : compare(current);
+	} catch {
+		threw(source, auth);
+		return true;
+	}
+}
+//#endregion
 //#region src/core/oauth-scopes.ts
 /**
 * Every OAuth scope a token may carry to the permission keys it reaches: each
@@ -542,11 +644,17 @@ function expandOAuthScopes(policy, delegation) {
 		scopes: [...out]
 	};
 }
-/** The coarse scopes the policy declares that cover `permission`, in declaration order. */
+/**
+* The coarse scopes the policy declares that cover `permission`, in declaration
+* order.
+*/
 function coarseScopesFor(policy, permission) {
 	return (policy.oauthScopes ?? []).filter((entry) => entry.permissions.includes(permission.key)).map((entry) => entry.scope);
 }
-/** Every token scope that reaches `permission`: its own, any it was renamed from, and the coarse scopes covering it. */
+/**
+* Every token scope that reaches `permission`: its own, any it was renamed
+* from, and the coarse scopes covering it.
+*/
 function scopesReaching(policy, permission) {
 	return [
 		permission.scope,
@@ -555,9 +663,9 @@ function scopesReaching(policy, permission) {
 	];
 }
 /**
-* The scope an `insufficient_scope` challenge names for `permission`: the
-* first coarse scope that covers it, which the authorization server issues,
-* else the permission's own scope.
+* The scope an `insufficient_scope` challenge names for `permission`: the first
+* coarse scope that covers it, which the authorization server issues, else the
+* permission's own scope.
 */
 function challengeScope(policy, permission) {
 	return coarseScopesFor(policy, permission)[0] ?? permission.scope;
@@ -567,10 +675,25 @@ function hasScope(granted, scopes) {
 	return scopes.some((scope) => granted?.includes(scope) === true);
 }
 //#endregion
+//#region src/core/source-memo.ts
+/**
+* One memo per `getPermDock` call. A read that throws is not kept, so the next
+* caller tries again.
+*/
+function sourceMemo() {
+	const answers = /* @__PURE__ */ new Map();
+	return (key, read) => {
+		if (answers.has(key)) return answers.get(key);
+		const answer = read();
+		answers.set(key, answer);
+		return answer;
+	};
+}
+//#endregion
 //#region src/core/resolve-subject.ts
 /**
-* The tenant a user API key holds its owner to (`Credential.tenant`): only
-* the memberships inside it count, and no global role.
+* The tenant a user API key holds its owner to (`Credential.tenant`): only the
+* memberships inside it count, and no global role.
 */
 function heldTenantOf(principal) {
 	const credential = principal["credential"];
@@ -581,13 +704,14 @@ function heldTenantOf(principal) {
 function outsideHeld(held, options) {
 	return held !== void 0 && options.tenant !== void 0 && options.tenant !== held;
 }
-function assemblePrincipal(policy, user, options, auth) {
+function assemblePrincipal(policy, user, options, auth, memo) {
 	let principal;
 	let context = {};
 	let actor = options.actor;
 	let delegation = options.delegation;
 	let session = options.session;
 	let expiresAt = options.expiresAt;
+	let issuedAt;
 	let liveSession;
 	try {
 		if (user === null || user === void 0) principal = policy.subject(user);
@@ -598,6 +722,7 @@ function assemblePrincipal(policy, user, options, auth) {
 			delegation = user.delegation ?? delegation;
 			session = user.session ?? session;
 			expiresAt = user.expiresAt ?? expiresAt;
+			issuedAt = typeof user.issuedAt === "number" && Number.isFinite(user.issuedAt) ? user.issuedAt : void 0;
 			liveSession = user.liveSession === true ? true : void 0;
 		} else principal = policy.subject(user);
 	} catch {
@@ -613,7 +738,10 @@ function assemblePrincipal(policy, user, options, auth) {
 			return from.membershipsFor(compact({
 				id: of.id,
 				kind: of.kind
-			}), compact({ tenant: options.tenant }));
+			}), compact({
+				tenant: options.tenant,
+				memo
+			}));
 		} catch {
 			auth.push({
 				reason: "source-threw",
@@ -629,10 +757,13 @@ function assemblePrincipal(policy, user, options, auth) {
 		live = true;
 		memberships = read(source, principal);
 	} else if (principal?.memberships !== void 0 && fromClaims && source.onStale === "reread" && source.version !== void 0) {
-		const reread = rereadStale(source, principal, principal.memberships, () => read(source, principal), auth, source.globalRolesFor === void 0 ? void 0 : () => source.globalRolesFor?.(compact({
+		const reread = rereadStale(source, principal, issuedAt, {
+			memo,
+			intent: options.intent ?? "write"
+		}, () => read(source, principal), auth, source.globalRolesFor === void 0 ? void 0 : () => source.globalRolesFor?.(compact({
 			id: principal.id,
 			kind: principal.kind
-		})) ?? []);
+		}), { memo }) ?? []);
 		memberships = reread.memberships;
 		stale = reread.stale;
 		roles = reread.roles;
@@ -645,78 +776,21 @@ function assemblePrincipal(policy, user, options, auth) {
 		delegation: expandOAuthScopes(policy, delegation),
 		session,
 		expiresAt,
+		issuedAt,
 		memberships,
 		live,
 		stale,
 		liveSession: principal === null ? void 0 : liveSession
 	});
 }
-function versionQuery(principal) {
-	return compact({
-		id: principal.id,
-		roles: principal.roles,
-		memberships: principal.memberships
-	});
-}
-function rereadStale(source, principal, claims, read, auth, readRoles) {
-	const claimed = principal.authzVersion;
-	const judge = (current) => typeof claimed === "number" && current !== void 0 && claimed >= current ? "fresh" : "reread";
-	const unknown = () => {
-		auth.push({
-			reason: "source-threw",
-			source: "memberships",
-			...sourceName(source)
-		});
-		return "unknown";
-	};
-	let freshness;
-	try {
-		const current = source.version?.(versionQuery(principal));
-		freshness = isThenable(current) ? Promise.resolve(current).then(judge, unknown) : judge(current);
-	} catch {
-		freshness = unknown();
-	}
-	const failed = () => {
-		auth.push({
-			reason: "source-threw",
-			source: "memberships",
-			...sourceName(source)
-		});
-		return [];
-	};
-	const rolesOf = (found) => {
-		if (found !== "reread" || readRoles === void 0) return;
-		try {
-			const roles = readRoles();
-			return isThenable(roles) ? Promise.resolve(roles).catch(failed) : roles;
-		} catch {
-			return failed();
-		}
-	};
-	if (isThenable(freshness)) {
-		const settled = freshness.then((found) => ({
-			found,
-			roles: rolesOf(found)
-		}));
-		return {
-			memberships: settled.then(({ found }) => found === "reread" ? read() : claims),
-			stale: settled.then(({ found }) => found === "unknown"),
-			roles: settled.then(({ roles }) => roles)
-		};
-	}
-	return compact({
-		memberships: freshness === "reread" ? read() : claims,
-		stale: freshness === "unknown",
-		roles: rolesOf(freshness)
-	});
-}
 function finishSubject(policy, assembled, context, input, options, extra) {
 	if (assembled.principal === null) return freezeCopy(compact({
 		...anonymousSubject(context),
 		actor: assembled.actor,
 		delegation: assembled.delegation,
 		session: assembled.session,
-		expiresAt: assembled.expiresAt
+		expiresAt: assembled.expiresAt,
+		issuedAt: assembled.issuedAt
 	}));
 	const scopes = scopeList(policy.scopes);
 	const held = heldTenantOf(assembled.principal);
@@ -742,11 +816,15 @@ function finishSubject(policy, assembled, context, input, options, extra) {
 		context: freezeCopy(context),
 		session: assembled.session,
 		expiresAt: assembled.expiresAt,
+		issuedAt: assembled.issuedAt,
 		stale: extra.stale ? true : void 0,
 		liveSession: assembled.liveSession
 	}));
 }
-/** Runs the policy's membership schema over each `x`; an invalid one is dropped and reported, never the membership. */
+/**
+* Runs the policy's membership schema over each `x`; an invalid one is dropped
+* and reported, never the membership.
+*/
 function checkMembershipX(memberships, schema, auth) {
 	if (schema === void 0) return memberships;
 	let dropped = false;
@@ -786,37 +864,6 @@ function settle(value, fallback, onError) {
 	});
 	return value;
 }
-/**
-* Whether the token's memberships are behind the source for `fresh`
-* permissions. Live memberships are never stale; token memberships are stale
-* unless a source reports a version the token's `authzVersion` has reached.
-*/
-function staleness(policy, assembled, options, auth) {
-	const principal = assembled.principal;
-	if ((policy.fresh ?? []).length === 0 || principal === null || assembled.live) return false;
-	if (assembled.stale !== void 0) return assembled.stale;
-	const source = options.memberships === void 0 ? void 0 : asMembershipSource(options.memberships);
-	const claimed = principal.authzVersion;
-	if (source?.version === void 0 || typeof claimed !== "number") return true;
-	const compare = (current) => current === void 0 || claimed < current;
-	try {
-		const current = source.version(versionQuery(principal));
-		return isThenable(current) ? settle(Promise.resolve(current).then(compare), true, () => {
-			auth.push({
-				reason: "source-threw",
-				source: "memberships",
-				...sourceName(source)
-			});
-		}) : compare(current);
-	} catch {
-		auth.push({
-			reason: "source-threw",
-			source: "memberships",
-			...sourceName(source)
-		});
-		return true;
-	}
-}
 function cleanNames(list) {
 	return Array.isArray(list) ? list.filter((item) => typeof item === "string" && item !== "") : [];
 }
@@ -870,25 +917,33 @@ function withRequestContext(request, resolved) {
 		...resolved
 	};
 }
-function resolveSubject(policy, user, options, auth) {
-	const first = assemblePrincipal(policy, user, options, auth);
+function resolveSubject(policy, user, options, auth, memo = sourceMemo()) {
+	const first = assemblePrincipal(policy, user, options, auth, memo);
 	const apply = (roles) => resolveAssembled(policy, roles === void 0 || first.principal === null ? first : {
 		...first,
 		principal: {
 			...first.principal,
 			roles
 		}
-	}, options, auth);
+	}, options, auth, memo);
 	return isThenable(first.roles) ? Promise.resolve(first.roles).then(apply) : apply(first.roles);
 }
-function resolveAssembled(policy, assembled, options, auth) {
+function resolveAssembled(policy, assembled, options, auth, memo) {
 	const memberships = settle(assembled.memberships, [], () => {
 		auth.push({
 			reason: "source-threw",
 			source: "memberships"
 		});
 	});
-	const stale = staleness(policy, assembled, options, auth);
+	const stale = staleness(policy, assembled.principal, options.memberships === void 0 ? void 0 : asMembershipSource(options.memberships), {
+		live: assembled.live,
+		stale: assembled.stale,
+		issuedAt: assembled.issuedAt,
+		context: {
+			memo,
+			intent: options.intent ?? "write"
+		}
+	}, auth);
 	const withPlans = (resolved) => entitlementsOf(assembled, activeTenantOf(policy, assembled, applyRoleKinds(policy, assembled.principal?.roles, normalizeMemberships(resolved, scopeList(policy.scopes))).memberships, options), options, auth);
 	if (isThenable(assembled.context) || isThenable(memberships) || isThenable(stale)) return Promise.all([
 		Promise.resolve(assembled.context),
@@ -913,7 +968,7 @@ function resolveAssembled(policy, assembled, options, auth) {
 }
 //#endregion
 //#region src/core/permdock.ts
-function instantiate(codePolicy, subject, options, auth) {
+function instantiate(codePolicy, subject, options, auth, memo) {
 	const { policy, errors } = options.policies?.apply(codePolicy) ?? {
 		policy: codePolicy,
 		errors: []
@@ -921,7 +976,7 @@ function instantiate(codePolicy, subject, options, auth) {
 	const scopes = scopeList(policy.scopes);
 	const tenants = tenantsOf(subject.principal, scopes);
 	const roleSource = roleSourceFor(options.customRoles, subject, auth);
-	const customRoles = customRolesFor(roleSource, tenants, auth, subject.principal === null ? void 0 : subject.principal.roles ?? [], (tenant) => heldRoleNamesIn(subject.principal, scopes, tenant));
+	const customRoles = customRolesFor(roleSource, tenants, auth, subject.principal === null ? void 0 : subject.principal.roles ?? [], (tenant) => heldRoleNamesIn(subject.principal, scopes, tenant), memo);
 	const assignable = assignableNamesFor(roleSource, tenants, auth);
 	const approvals = options.approvalPolicies?.load(policy, tenants, auth);
 	const build = (roles, names, approvalPolicies) => {
@@ -950,6 +1005,7 @@ function instantiate(codePolicy, subject, options, auth) {
 				context: {}
 			}, compact({
 				tenant,
+				intent: options.intent,
 				memberships: options.memberships,
 				customRoles: options.customRoles,
 				entitlements: options.entitlements,
@@ -970,15 +1026,16 @@ function instantiate(codePolicy, subject, options, auth) {
 function create(policy, user, given) {
 	const options = withApp(policy, given);
 	const auth = [];
-	const subject = resolveSubject(policy, user, options, auth);
-	if (isThenable(subject)) return subject.then((resolved) => instantiate(policy, resolved, options, auth));
-	return instantiate(policy, subject, options, auth);
+	const memo = sourceMemo();
+	const subject = resolveSubject(policy, user, options, auth, memo);
+	if (isThenable(subject)) return subject.then((resolved) => instantiate(policy, resolved, options, auth, memo));
+	return instantiate(policy, subject, options, auth, memo);
 }
 /**
 * The instance for `user`, built synchronously. Every input must answer
 * synchronously: the subject mapper, `memberships`, `customRoles`,
-* `entitlements`, `approvalPolicies` and the freshness check. One that
-* answers with a Promise throws here; use `getPermDock` for those.
+* `entitlements`, `approvalPolicies` and the freshness check. One that answers
+* with a Promise throws here; use `getPermDock` for those.
 */
 function getPermDockSync(policy, user, options = {}) {
 	const created = create(policy, user, options);
@@ -988,7 +1045,10 @@ function getPermDockSync(policy, user, options = {}) {
 	}
 	return created;
 }
-/** The instance for `user`: waits for every source, then builds it. `getPermDockSync` is the synchronous twin. */
+/**
+* The instance for `user`: waits for every source, then builds it.
+* `getPermDockSync` is the synchronous twin.
+*/
 function getPermDock(policy, user, options = {}) {
 	return Promise.resolve().then(() => create(policy, user, options));
 }