@powerhousedao/powerhouse-vetra-packages 6.2.2-dev.37 → 6.2.2-dev.38

package/dist/node/{document-drive-BTZnoCCz.mjs → document-drive-CI0J7nMj.mjs}

@@ -3951,6 +3951,30 @@ var GroupPrincipalNotAllowedError = class extends Error {
 		this.grantId = grantId;
 	}
 };
+/**
+* Thrown when a change would leave a creator-less policy with no grant
+* permitting execute on the auth scope. Without the creator carve-out no
+* subject could ever administer such a policy again.
+*/
+var AuthAdministrationLockoutError = class extends Error {
+	grantId;
+	constructor(grantId) {
+		super(`Change to grant "${grantId}" would leave no reachable grant permitting execute on the auth scope: a policy with no creator must always retain one`);
+		this.name = "AuthAdministrationLockoutError";
+		this.grantId = grantId;
+	}
+};
+/**
+* Thrown when INITIALIZE_AUTH would create a creator-less policy with no grant
+* permitting execute on the auth scope. Such a policy would be born with no
+* subject able to administer it.
+*/
+var AuthAdministrationMissingError = class extends Error {
+	constructor() {
+		super("Initial grants include no reachable grant permitting execute on the auth scope: a policy with no creator must always include one");
+		this.name = "AuthAdministrationMissingError";
+	}
+};
 const GRANT_KEYS = new Set([
 	"id",
 	"description",
@@ -4102,15 +4126,114 @@ function assertValidGrant(grant, documentType) {
 	if (problem !== null) throw new InvalidGrantError(grantId, problem);
 	if (documentType === "@powerhousedao/document-group" && "group" in grant.principal) throw new GroupPrincipalNotAllowedError(grantId);
 }
-/** Validates an initial grant list: the count cap plus every grant. */
-function assertValidInitialGrants(grants, documentType) {
+/**
+* Validates an initial grant list: the count cap, every grant, and — on a
+* creator-less policy — that some grant keeps the auth scope administrable.
+*/
+function assertValidInitialGrants(grants, documentType, creator) {
 	if (grants.length > 100) throw new InvalidGrantError("", `policy exceeds 100 grants`);
 	for (const grant of grants) assertValidGrant(grant, documentType);
+	if (creator === void 0 && !administrationReachable(grants)) throw new AuthAdministrationMissingError();
 }
-/** Validates a grant upsert: the grant itself plus the count cap on append. */
-function assertValidGrantUpsert(grant, existing, documentType) {
+/**
+* Validates a grant upsert: the grant itself, the count cap on append, and
+* administration retention. Retention is checked on an append as well as an
+* in-place replace, because a grant appended after the administration grant can
+* shadow it (evaluation is last-applicable-grant-wins) and so take
+* administration away without removing anything.
+*/
+function assertValidGrantUpsert(grant, existing, documentType, creator) {
 	assertValidGrant(grant, documentType);
-	if (!existing.some((g) => g.id === grant.id) && existing.length >= 100) throw new InvalidGrantError(grant.id, `policy exceeds 100 grants`);
+	const exists = existing.some((g) => g.id === grant.id);
+	if (!exists && existing.length >= 100) throw new InvalidGrantError(grant.id, `policy exceeds 100 grants`);
+	assertAuthAdministrationRetained(creator, existing, exists ? existing.map((g) => g.id === grant.id ? grant : g) : [...existing, grant], grant.id);
+}
+/**
+* The request whose coverage keeps a policy administrable: a subject who may
+* SET_GRANT can upsert any grant, so every other repair stays reachable.
+*/
+const AUTH_ADMINISTRATION_REQUEST = {
+	verb: "execute",
+	scope: "auth",
+	operation: "SET_GRANT"
+};
+/**
+* Whether some subject can still administer the auth scope under this grant list.
+*
+* Asks the evaluator rather than pattern-matching a single grant: evaluation is
+* last-applicable-grant-wins, so an allow that some later deny shadows keeps
+* nothing reachable even though it is still present in the list. Only anyone and
+* address principals are candidates, because those are the ones v1 can match at
+* all; a `where` condition or a group or match principal never applies.
+*/
+function administrationReachable(grants) {
+	return grants.some((grant) => {
+		const subject = administrationCandidate(grant);
+		if (subject === void 0) return false;
+		return evaluateGrantStack(grants, subject, AUTH_ADMINISTRATION_REQUEST).decision === "allow";
+	});
+}
+/**
+* The subject to test this grant with, or undefined when the grant could never
+* carry administration for anyone.
+*/
+function administrationCandidate(grant) {
+	if (grant.effect !== "allow" || grant.where !== void 0 || !capabilityCovers(grant.capability, AUTH_ADMINISTRATION_REQUEST)) return;
+	if ("address" in grant.principal) return {
+		address: grant.principal.address,
+		key: void 0
+	};
+	if ("anyone" in grant.principal) return {
+		address: void 0,
+		key: void 0
+	};
+}
+/**
+* A creator-less policy must always retain a grant permitting execute on the
+* auth scope; on a signed document the creator carve-out keeps administration
+* reachable instead. Rejects a change that takes the last such grant away. A
+* policy already without one is left alone: the change is not what locks it.
+*/
+function assertAuthAdministrationRetained(creator, previous, next, grantId) {
+	if (creator !== void 0) return;
+	if (administrationReachable(previous) && !administrationReachable(next)) throw new AuthAdministrationLockoutError(grantId);
+}
+function capabilityCovers(capability, request) {
+	if (capability.can !== request.verb) return false;
+	const scope = capability.scope;
+	if (scope !== void 0 && scope !== "*" && scope !== request.scope) return false;
+	if (capability.can === "execute") {
+		if (capability.operation === void 0) return true;
+		return request.operation !== void 0 && capability.operation.includes(request.operation);
+	}
+	return true;
+}
+function principalMatches(principal, subject) {
+	if ("anyone" in principal) return true;
+	if ("address" in principal) return subject.address !== void 0 && subject.address.toLowerCase() === principal.address.toLowerCase();
+	return false;
+}
+/**
+* Evaluates a v1 grant stack: default deny, last applicable grant wins, and
+* reports which grant decided it. Group and match principals and `where`
+* conditions are not evaluated yet; a grant that uses any of them never applies.
+*/
+function evaluateGrantStack(grants, subject, request) {
+	let applicable;
+	for (const grant of grants) {
+		if (grant.where !== void 0) continue;
+		if (capabilityCovers(grant.capability, request) && principalMatches(grant.principal, subject)) applicable = grant;
+	}
+	if (applicable === void 0) return {
+		decision: "deny",
+		refusal: "no-applicable-grant"
+	};
+	if (applicable.effect === "deny") return {
+		decision: "deny",
+		refusal: "denied-by-grant",
+		grantId: applicable.id
+	};
+	return { decision: "allow" };
 }
 const documentModelFileExtension = "phdm";
 const documentModelInitialLocalState = {};
@@ -4847,6 +4970,8 @@ function isDocumentCreator(creatorKey, signerKey) {
 * (version 0). The input version is the policy language version and must be an
 * integer >= 1; 0 is reserved for the uninitialized state. On a signed-header
 * document it must be signed by the document creator (`header.sig.publicKey`).
+* A creator-less policy must include a grant permitting execute on the auth
+* scope, or it would be born locked out.
 */
 function applyInitializeAuthAction(document, action) {
 	assertActionInputShape(action.input);
@@ -4854,12 +4979,12 @@ function applyInitializeAuthAction(document, action) {
 	if (!Number.isInteger(version) || version < 1) throw new InvalidAuthVersionError(document.header.id, version);
 	if (document.state.auth.version !== 0) throw new AuthAlreadyInitializedError(document.header.id);
 	if (!Array.isArray(grants)) throw new InvalidActionInputError({ grants: "must be an array" });
-	assertValidInitialGrants(grants, document.header.documentType);
 	const creatorKey = document.header.sig.publicKey;
 	const signerKey = action.context?.signer?.app.key;
 	const hasCreator = Boolean(creatorKey.kty || creatorKey.x || creatorKey.y);
 	if (hasCreator && !isDocumentCreator(creatorKey, signerKey)) throw new AuthInitializerNotCreatorError(document.header.id);
 	const creator = hasCreator ? signerKey : void 0;
+	assertValidInitialGrants(grants, document.header.documentType, creator);
 	return {
 		...document,
 		state: {
@@ -4880,32 +5005,42 @@ function applySetGrantAction(document, action) {
 	assertActionInputShape(action.input);
 	const { grant } = action.input;
 	const grants = document.state.auth.grants;
-	assertValidGrantUpsert(grant, grants, document.header.documentType);
+	assertValidGrantUpsert(grant, grants, document.header.documentType, document.state.auth.creator);
 	return withGrants(document, grants.some((g) => g.id === grant.id) ? grants.map((g) => g.id === grant.id ? grant : g) : [...grants, grant]);
 }
-/** Removes a grant by id; throws if the id is not present. */
+/**
+* Removes a grant by id; throws if the id is not present or if the removal
+* would leave a creator-less policy with no auth-administration grant.
+*/
 function applyRemoveGrantAction(document, action) {
 	assertActionInputShape(action.input);
 	const { id } = action.input;
-	const grants = document.state.auth.grants;
+	const { grants, creator } = document.state.auth;
 	if (!grants.some((g) => g.id === id)) throw new GrantNotFoundError(id);
-	return withGrants(document, grants.filter((g) => g.id !== id));
+	const next = grants.filter((g) => g.id !== id);
+	assertAuthAdministrationRetained(creator, grants, next, id);
+	return withGrants(document, next);
 }
 /**
 * Moves a grant by id to a new index. Order is load-bearing (the last
 * applicable grant wins), so the relative order of the other grants is kept.
 * The target index is clamped to the valid range; an unknown id throws.
+*
+* Order alone decides which grant wins, so a move can take administration away
+* without changing the list's contents. It carries the same retention rule as
+* the two mutation paths.
 */
 function applyMoveGrantAction(document, action) {
 	assertActionInputShape(action.input);
 	const { id, index } = action.input;
-	const grants = document.state.auth.grants;
+	const { grants, creator } = document.state.auth;
 	const from = grants.findIndex((g) => g.id === id);
 	if (from === -1) throw new GrantNotFoundError(id);
 	const next = [...grants];
 	const [moved] = next.splice(from, 1);
 	const to = Math.max(0, Math.min(index, next.length));
 	next.splice(to, 0, moved);
+	assertAuthAdministrationRetained(creator, grants, next, id);
 	return withGrants(document, next);
 }
 /**
@@ -4931,6 +5066,42 @@ function assertAuthPreservedOnDuplicate(documentId, source, duplicated) {
 	if (!source || source.version === 0) return;
 	if (duplicated === void 0 || duplicated.version !== source.version || duplicated.creator !== source.creator) throw new AuthPolicyNotPreservedError(documentId);
 }
+/**
+* The auth scope a state snapshot may install, given the policy already there.
+*
+* `applyAuthAction` is the validated door onto `state.auth`, but a whole-state
+* snapshot (UPGRADE_DOCUMENT's `initialState`, LOAD_STATE's `data`) replaces the
+* scope wholesale and is authorized as a `document`-scope write. Without this,
+* a subject holding `execute` on `document` and no auth grant at all can install
+* a policy of its choosing, name itself `creator` (which exempts the policy from
+* the retention rule for good), or wipe an existing policy by carrying the
+* default uninitialized one.
+*
+* Three cases:
+*
+*   - the snapshot carries no policy, or an uninitialized one: the document
+*     keeps the policy it has, so a default-state upgrade cannot reset it;
+*   - the document is uninitialized and the snapshot carries a policy: the
+*     policy is installed after the same validation genesis applies, so it
+*     cannot be born locked out;
+*   - both carry a policy: they must agree. A duplicate preserves its source's
+*     policy (see {@link assertAuthPreservedOnDuplicate}), and anything else is
+*     an attempt to replace one policy with another.
+*/
+function resolveSnapshotAuth(documentId, documentType, current, incoming) {
+	const currentAuth = current ?? createAuthState({
+		version: 0,
+		grants: []
+	});
+	if (!incoming || !incoming.version) return currentAuth;
+	if (currentAuth.version !== 0) {
+		if (stringify$1(incoming) !== stringify$1(currentAuth)) throw new AuthPolicyNotPreservedError(documentId);
+		return incoming;
+	}
+	if (!Array.isArray(incoming.grants)) throw new InvalidActionInputError({ grants: "must be an array" });
+	assertValidInitialGrants(incoming.grants, documentType, incoming.creator);
+	return incoming;
+}
 /** UNDO, REDO and PRUNE are rejected on the auth scope. */
 function assertAuthScopeActionAllowed(action) {
 	if (action.scope === "auth" && [
@@ -4939,6 +5110,12 @@ function assertAuthScopeActionAllowed(action) {
 		"PRUNE"
 	].includes(action.type)) throw new AuthActionNotAllowedError(action.type);
 }
+/**
+* True iff authorization rejected the action.
+*/
+function isDenied(operation) {
+	return operation.deniedReason !== void 0;
+}
 const BaseDocumentHeaderSchema = object({
 	id: string(),
 	name: string(),
@@ -5121,6 +5298,22 @@ function garbageCollectV2(sortedOperations) {
 const defaultCreateState = (state) => {
 	return state;
 };
+/**
+* Records an operation in the history without applying it, which is what a
+* denied operation needs: it occupies its index and contributes no state.
+*
+* The scope defaults to the action's own, and is passed explicitly by a rebuild
+* that is walking one stream and does not want to trust the action's copy.
+*/
+function appendWithoutApplying(document, operation, scope = operation.action.scope) {
+	return {
+		...document,
+		operations: {
+			...document.operations,
+			[scope]: [...document.operations[scope] ?? [], operation]
+		}
+	};
+}
 function replayDocument(initialState, operations, reducer, header, dispatch, skipHeaderOperations = {}, options) {
 	const { checkHashes = true, reuseOperationResultingState, operationResultingStateParser = parseResultingState, skipIndexValidation } = options || {};
 	const backfilledInitialState = backfillAuthState(initialState);
@@ -5165,6 +5358,7 @@ function replayDocument(initialState, operations, reducer, header, dispatch, ski
 	};
 	let result = document;
 	if (operationsToReplay.length) result = operationsToReplay.reduce((document, operation) => {
+		if (isDenied(operation)) return appendWithoutApplying(document, operation);
 		return reducer(document, operation.action, dispatch, {
 			ignoreSkipOperations: true,
 			checkHashes,
@@ -5446,13 +5640,15 @@ function redoOperation(document, action, skip) {
 	});
 }
 function loadStateOperation(document, action) {
+	const loaded = backfillAuthState(action.state.data);
+	loaded.auth = resolveSnapshotAuth(document.header.id, document.header.documentType, backfillAuthState({ ...document.state }).auth, loaded.auth);
 	return {
 		...document,
 		header: {
 			...document.header,
 			name: action.state.name
 		},
-		state: backfillAuthState(action.state.data)
+		state: loaded
 	};
 }
 function replayOperations(initialState, clearedOperations, stateReducer, header, dispatch, documentReducer = baseReducer, skipHeaderOperations = {}, options) {
@@ -6474,10 +6670,12 @@ function applyInitialState(document, action) {
 	const input = action.input;
 	const newState = input.initialState || input.state;
 	if (newState) {
-		document.state = backfillAuthState({
+		const merged = backfillAuthState({
 			...document.state,
 			...newState
 		});
+		merged.auth = resolveSnapshotAuth(document.header.id, document.header.documentType, backfillAuthState({ ...document.state }).auth, merged.auth);
+		document.state = merged;
 		document.initialState = document.state;
 	}
 }
@@ -6655,7 +6853,8 @@ function replayDocumentVersioned(initialState, operations, config, header, dispa
 			const segEnd = k < validatedUpgrades.length ? boundaries[k]?.[s] ?? ops.length : ops.length;
 			const segOps = ops.slice(segStart, segEnd);
 			for (const op of segOps) {
-				document = reducer(document, op.action, dispatch, {
+				if (isDenied(op)) document = appendWithoutApplying(document, op, s);
+				else document = reducer(document, op.action, dispatch, {
 					ignoreSkipOperations: true,
 					checkHashes,
 					skipIndexValidation,
@@ -6672,6 +6871,7 @@ function replayDocumentVersioned(initialState, operations, config, header, dispa
 			if (!spineOp) continue;
 			const spineActionType = spineOp.action.type;
 			if (spineActionType === "CREATE_DOCUMENT" || spineActionType === "UPGRADE_DOCUMENT") continue;
+			if (isDenied(spineOp)) continue;
 			if (spineActionType === "DELETE_DOCUMENT") document = applyDeleteDocumentAction(document, spineOp.action);
 			else document = reducer(document, spineOp.action, dispatch, {
 				ignoreSkipOperations: true,
@@ -7925,4 +8125,4 @@ const driveDocumentModelModule = {
 //#endregion
 export { generateId as $, documentModelDocumentType as A, setModelId as B, createReducer as C, deleteModule as D, defaultBaseState as E, setAuthorName as F, setOperationErrorName as G, setModuleName as H, setAuthorWebsite as I, setStateSchema as J, setOperationName as K, setInitialState as L, isDocumentAction as M, redo as N, deleteOperation as O, replayDocumentVersioned as P, validateStateSchemaName as Q, setModelDescription as R, createPresignedHeader as S, createZip as T, setName as U, setModelName as V, setOperationDescription as W, validateInitialState as X, undo as Y, validateModules as Z, baseCreateDocument as _, handleTargetNameCollisions as a, baseSaveToFileHandle as b, isValidName as c, documentModelDocumentModelModule as d, logger as f, assertAuthPreservedOnDuplicate as g, addOperationError as h, generateNodesCopy as i, hashDocumentStateForScope as j, deleteOperationError as k, moveNode as l, addOperation as m, copyNode as n, isFileNode as o, addModule as p, setOperationSchema as q, driveDocumentModelModule as r, isFolderNode as s, addFolder as t, updateNode as u, baseLoadFromInput as v, createState as w, buildSignedAction as x, baseLoadFromInputVersioned as y, setModelExtension as z };
 
-//# sourceMappingURL=document-drive-BTZnoCCz.mjs.map
+//# sourceMappingURL=document-drive-CI0J7nMj.mjs.map