permdock 0.3.1 → 0.5.0

package/dist/permission-registry-Br4jSNVi.js

@@ -0,0 +1,385 @@
+import { n as isReadonlyArray, t as compact } from "./compact-CAf557ZB.js";
+import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
+import { i as ownKeys, n as isForbiddenKey, t as assertSafeKey } from "./paths-DXSHAMIa.js";
+import { r as parseAppData, t as assertAppData } from "./app-data-MuyzVqX8.js";
+import { f as normaliseRelation, h as restrictedStopsOf, i as assertIncludes, n as RESOURCE_NAME, r as assertGraphTargets, t as LEVEL_NAME } from "./resource-relations-D_jw0BFx.js";
+//#region src/core/brands.ts
+const RESOURCE_BRAND = Symbol.for("permdock.resource");
+const TREE_REGISTRY = Symbol.for("permdock.registry");
+const NODE_RESOURCE = Symbol.for("permdock.resource");
+const TREE_LEAVES = Symbol.for("permdock.leaves");
+const LEAF_FORMER = Symbol.for("permdock.former");
+//#endregion
+//#region src/core/permission-leaf.ts
+function isStandardSchema(value) {
+	return value !== null && typeof value === "object" && "~standard" in value && typeof value["~standard"]?.version === "number";
+}
+function isResourceInit(value) {
+	return value !== null && typeof value === "object" && RESOURCE_BRAND in value && value[RESOURCE_BRAND] === true;
+}
+function isResourceOptions(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) && !isStandardSchema(value);
+}
+function metaFor(list, action, schema) {
+	if (list === void 0 || Array.isArray(list)) return freezeDeep({});
+	const meta = list[action];
+	if (meta?.x === void 0) return freezeDeep({ ...meta });
+	return freezeDeep({
+		...meta,
+		x: parseAppData(schema, meta.x, `meta.x of action '${action}'`)
+	});
+}
+function resourceMetaFor(name, meta, schema) {
+	if (meta === void 0) return;
+	assertAppData(meta, `meta of resource '${name}'`);
+	for (const field of ["title", "description"]) if (meta[field] !== void 0 && typeof meta[field] !== "string") throw new TypeError(`PermDock: meta.${field} of resource '${name}' must be a string`);
+	return freezeDeep(compact({
+		title: meta.title,
+		description: meta.description,
+		x: meta.x === void 0 ? void 0 : parseAppData(schema, meta.x, `meta.x of resource '${name}'`)
+	}));
+}
+/**
+* MCP and WebMCP tool hints from a permission's `meta`. Hints only inform the
+* client; every call is still decided on the server.
+*/
+function annotationsFor(permission) {
+	const { meta } = permission;
+	const readOnlyHint = meta.readOnly ?? (permission.action === "read" || permission.action === "list");
+	return compact({
+		readOnlyHint,
+		destructiveHint: readOnlyHint ? void 0 : meta.destructive,
+		idempotentHint: meta.idempotent
+	});
+}
+function actionNames(list) {
+	if (list === void 0) return [];
+	if (isReadonlyArray(list)) return list;
+	return Object.keys(list);
+}
+function keyToScope(key) {
+	return key.replaceAll(".", ":");
+}
+function makeLeaf(key, resourceName, action, meta, kind, former) {
+	const leaf = {
+		key,
+		scope: keyToScope(key),
+		resource: resourceName,
+		action,
+		meta
+	};
+	Object.defineProperty(leaf, "kind", {
+		value: kind,
+		enumerable: false,
+		writable: false,
+		configurable: false
+	});
+	if (former !== void 0 && former.length > 0) Object.defineProperty(leaf, LEAF_FORMER, {
+		value: Object.freeze([...former].toSorted()),
+		enumerable: false,
+		writable: false,
+		configurable: false
+	});
+	return Object.freeze(leaf);
+}
+/**
+* The keys `permission` was renamed from, sorted. Empty for a leaf without
+* renames and for one that crossed a serialisation boundary.
+*/
+function formerKeys(permission) {
+	if (!Object.hasOwn(permission, LEAF_FORMER)) return [];
+	const value = Reflect.get(permission, LEAF_FORMER);
+	return isReadonlyArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+/** The OAuth scope strings `permission` used to have: each former key with `.` as `:`. */
+function formerScopes(permission) {
+	return formerKeys(permission).map(keyToScope);
+}
+function resource(schemaOrOptions, options) {
+	if (schemaOrOptions === void 0 && options === void 0) throw new Error("PermDock: resource() requires a schema or options");
+	if (isStandardSchema(schemaOrOptions)) return {
+		[RESOURCE_BRAND]: true,
+		schema: schemaOrOptions,
+		options: options ?? {}
+	};
+	if (isResourceOptions(schemaOrOptions) && options === void 0) return {
+		[RESOURCE_BRAND]: true,
+		schema: void 0,
+		options: schemaOrOptions
+	};
+	throw new Error("PermDock: resource() first argument must be a schema or options");
+}
+//#endregion
+//#region src/core/materialise-resource.ts
+function materialiseResource(init, path, registry, leaves, build) {
+	const { former } = build;
+	const segment = path.at(-1);
+	if (segment === void 0) throw new Error("PermDock: resource() cannot be the root of definePermissions");
+	const name = init.options.name ?? segment;
+	assertSafeKey(name, "resource");
+	if (init.options.name !== void 0 && !RESOURCE_NAME.test(name)) throw new Error(`PermDock: resource name '${name}' must start with a letter and hold only letters, digits, '_' and '-'`);
+	if (registry.has(name)) throw new Error(`PermDock: duplicate resource name '${name}'`);
+	const prefix = path.join(".");
+	const instanceNames = actionNames(init.options.actions);
+	const collectionNames = actionNames(init.options.collection);
+	if (instanceNames.length === 0 && collectionNames.length === 0) throw new Error(`PermDock: resource '${name}' has no actions or collection`);
+	const instanceSet = /* @__PURE__ */ new Set();
+	const collectionSet = /* @__PURE__ */ new Set();
+	const node = {};
+	for (const action of instanceNames) {
+		assertSafeKey(action, "action");
+		if (instanceSet.has(action)) throw new Error(`PermDock: duplicate action '${action}' on '${name}'`);
+		instanceSet.add(action);
+		const key = `${prefix}.${action}`;
+		const leaf = makeLeaf(key, name, action, metaFor(init.options.actions, action, build.x?.permission), "instance", former.get(key));
+		node[action] = leaf;
+		leaves.push(leaf);
+	}
+	for (const action of collectionNames) {
+		assertSafeKey(action, "action");
+		if (instanceSet.has(action) || collectionSet.has(action)) throw new Error(`PermDock: duplicate action '${action}' on '${name}'`);
+		collectionSet.add(action);
+		const key = `${prefix}.${action}`;
+		const leaf = makeLeaf(key, name, action, metaFor(init.options.collection, action, build.x?.permission), "collection", former.get(key));
+		node[action] = leaf;
+		leaves.push(leaf);
+	}
+	const parent = init.options.parent;
+	if (parent !== void 0) {
+		assertSafeKey(parent.field, "parent field");
+		assertSafeKey(parent.resource, "parent resource");
+	}
+	const version = init.options.version;
+	if (version !== void 0) assertSafeKey(version, "version field");
+	const restrictedOption = init.options.restricted;
+	const restricted = typeof restrictedOption === "string" ? restrictedOption : restrictedOption?.field;
+	if (restrictedOption !== void 0) {
+		if (typeof restricted !== "string") throw new TypeError(`PermDock: resource "${name}" restricted must name a field`);
+		assertSafeKey(restricted, "restricted field");
+	}
+	const disclosure = init.options.disclosure ?? "reveal";
+	if (disclosure !== "hide" && disclosure !== "reveal") throw new Error(`PermDock: resource "${name}" disclosure must be 'hide' or 'reveal'`);
+	const relations = {};
+	for (const [relationName, spec] of Object.entries(init.options.relations ?? {})) {
+		assertSafeKey(relationName, "relation");
+		relations[relationName] = freezeDeep(normaliseRelation(name, relationName, spec));
+	}
+	const links = {};
+	for (const [linkName, link] of Object.entries(init.options.links ?? {})) {
+		assertSafeKey(linkName, "link");
+		if (linkName === "parent") throw new Error(`PermDock: link 'parent' on '${name}' is reserved; declare it as parent`);
+		assertSafeKey(link.field, "link field");
+		assertSafeKey(link.resource, "link resource");
+		links[linkName] = freezeDeep({
+			field: link.field,
+			resource: link.resource
+		});
+	}
+	const restrictedStopList = typeof restrictedOption === "object" ? restrictedStopsOf(name, restrictedOption, parent, links) : void 0;
+	const levels = {};
+	for (const [levelName, condition] of Object.entries(init.options.levels ?? {})) {
+		if (!LEVEL_NAME.test(levelName)) throw new Error(`PermDock: level '${levelName}' on '${name}' must match ^[a-z][a-z0-9_]*$`);
+		if (condition === null || typeof condition !== "object" || Array.isArray(condition)) throw new Error(`PermDock: level '${levelName}' on '${name}' must be a condition object`);
+		levels[levelName] = freezeDeep({ ...condition });
+	}
+	if (Object.keys(levels).length > 0 && instanceSet.size === 0) throw new Error(`PermDock: resource '${name}' declares levels but no instance actions`);
+	const meta = resourceMetaFor(name, init.options.meta, build.x?.resource);
+	const resourceNode = Object.freeze({
+		...meta === void 0 ? {} : { meta },
+		name,
+		path: prefix,
+		schema: init.schema,
+		id: init.options.id ?? "id",
+		parent: parent === void 0 ? void 0 : freezeDeep({ ...parent }),
+		links: freezeDeep(links),
+		relations: freezeDeep(relations),
+		version,
+		restricted,
+		...restrictedStopList === void 0 ? {} : { restrictedStops: restrictedStopList },
+		disclosure,
+		instanceActions: instanceSet,
+		collectionActions: collectionSet,
+		levels: Object.freeze(levels)
+	});
+	assertIncludes(resourceNode);
+	registry.set(name, resourceNode);
+	Object.defineProperty(node, NODE_RESOURCE, {
+		value: resourceNode,
+		enumerable: false,
+		writable: false,
+		configurable: false
+	});
+	return freezeDeep(node);
+}
+/** The resource a `definePermissions` resource node was built from, read from the node itself. */
+function resourceOfNode(node) {
+	if (!Object.hasOwn(node, NODE_RESOURCE)) return;
+	const value = Reflect.get(node, NODE_RESOURCE);
+	return isResourceNode(value) ? value : void 0;
+}
+function isResourceNode(value) {
+	return value !== null && typeof value === "object" && "name" in value && "instanceActions" in value;
+}
+function walk(input, path, registry, leaves, depth, build) {
+	if (depth > 10) throw new Error(`PermDock: permission group nesting exceeds 10`);
+	if (isResourceInit(input)) return materialiseResource(input, path, registry, leaves, build);
+	if (input === null || typeof input !== "object" || Array.isArray(input)) throw new Error(`PermDock: definePermissions expected a group or resource at '${path.join(".")}'`);
+	const group = {};
+	for (const key of Object.keys(input)) {
+		assertSafeKey(key, "group");
+		group[key] = walk(input[key], [...path, key], registry, leaves, depth + 1, build);
+	}
+	return group;
+}
+function attachRegistry(tree, registry, leaves) {
+	const attached = tree;
+	Object.defineProperty(attached, TREE_REGISTRY, {
+		value: registry,
+		enumerable: false,
+		writable: false,
+		configurable: false
+	});
+	Object.defineProperty(attached, TREE_LEAVES, {
+		value: Object.freeze([...leaves]),
+		enumerable: false,
+		writable: false,
+		configurable: false
+	});
+	return attached;
+}
+//#endregion
+//#region src/core/permission-registry.ts
+function isRegistryTree(tree) {
+	return TREE_REGISTRY in tree;
+}
+function getRegistry(tree) {
+	if (!isRegistryTree(tree)) throw new Error("PermDock: permission tree is missing its registry");
+	return tree[TREE_REGISTRY];
+}
+function getResource(tree, name) {
+	if (isForbiddenKey(name)) return;
+	return getRegistry(tree).get(name);
+}
+const RENAMED_KEY = /^\S+$/u;
+/** Current key to its former keys, from the `renamed` option; targets are checked once leaves exist. */
+function formerByKey(renamed) {
+	const former = /* @__PURE__ */ new Map();
+	if (renamed === void 0) return former;
+	if (renamed === null || typeof renamed !== "object") throw new TypeError("PermDock: renamed must map old keys to current keys");
+	for (const [old, current] of Object.entries(renamed)) {
+		if (!RENAMED_KEY.test(old) || old.split(".").some(isForbiddenKey)) throw new Error(`PermDock: renamed key '${old}' is not a valid key`);
+		if (typeof current !== "string") throw new TypeError(`PermDock: renamed key '${old}' must map to a current key`);
+		former.set(current, [...former.get(current) ?? [], old]);
+	}
+	return former;
+}
+/**
+* Every current key is unique, every former key names exactly one leaf, and
+* no former key is also a current key, so a string resolves to one leaf.
+*/
+function assertKeys(leaves, former) {
+	const current = /* @__PURE__ */ new Set();
+	for (const leaf of leaves) {
+		if (current.has(leaf.key))
+ /* v8 ignore next */
+		throw new Error(`PermDock: duplicate permission key '${leaf.key}'`);
+		current.add(leaf.key);
+	}
+	for (const target of former?.keys() ?? []) if (!current.has(target)) throw new Error(`PermDock: renamed target '${target}' is not a permission key`);
+	const olds = /* @__PURE__ */ new Map();
+	for (const leaf of leaves) for (const old of formerKeys(leaf)) {
+		if (current.has(old)) throw new Error(`PermDock: renamed key '${old}' is still a permission key`);
+		const other = olds.get(old);
+		if (other !== void 0 && other !== leaf.key) throw new Error(`PermDock: renamed key '${old}' maps to both '${other}' and '${leaf.key}'`);
+		olds.set(old, leaf.key);
+	}
+}
+function collectLeaves(node) {
+	if ("key" in node && "scope" in node && "action" in node) return [node];
+	const out = [];
+	for (const key of ownKeys(node)) {
+		const child = node[key];
+		if (child !== void 0) out.push(...collectLeaves(child));
+	}
+	return out;
+}
+function listPermissions(tree) {
+	if (isRegistryTree(tree)) return tree[TREE_LEAVES];
+	return collectLeaves(tree);
+}
+function findPermission(tree, keyOrScope) {
+	if (isForbiddenKey(keyOrScope)) return;
+	const leaves = listPermissions(tree);
+	for (const leaf of leaves) if (leaf.key === keyOrScope || leaf.scope === keyOrScope) return leaf;
+	for (const leaf of leaves) if (formerKeys(leaf).includes(keyOrScope) || formerScopes(leaf).includes(keyOrScope)) return leaf;
+}
+/**
+* A permission leaf: string `key`, `scope`, `resource` and `action` plus an
+* object `meta`. `kind` is non-enumerable and does not survive
+* `JSON.stringify`, so a leaf that crossed a serialisation boundary passes
+* without it; when present it must be `instance` or `collection`.
+*/
+function isPermission(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	for (const field of [
+		"key",
+		"scope",
+		"resource",
+		"action"
+	]) if (!Object.hasOwn(value, field) || typeof Reflect.get(value, field) !== "string") return false;
+	const meta = Object.hasOwn(value, "meta") ? Reflect.get(value, "meta") : void 0;
+	if (meta === null || typeof meta !== "object" || Array.isArray(meta)) return false;
+	if (!Object.hasOwn(value, "kind")) return true;
+	const kind = Reflect.get(value, "kind");
+	return kind === "instance" || kind === "collection";
+}
+function mergeNodes(target, source, keys, registry, sourceRegistry) {
+	for (const key of ownKeys(source)) {
+		assertSafeKey(key, "group");
+		const incoming = source[key];
+		if (incoming === void 0)
+ /* v8 ignore next */
+		continue;
+		const existing = target[key];
+		if (existing === void 0) {
+			target[key] = incoming;
+			if (isPermission(incoming)) {
+				if (keys.has(incoming.key))
+ /* v8 ignore next */
+				throw new Error(`PermDock: duplicate permission key '${incoming.key}'`);
+				keys.add(incoming.key);
+			}
+			continue;
+		}
+		if (isPermission(existing) || isPermission(incoming)) {
+			const keyName = isPermission(incoming) ? incoming.key : isPermission(existing) ? existing.key : key;
+			throw new Error(`PermDock: duplicate permission key '${keyName}'`);
+		}
+		const nested = { ...existing };
+		mergeNodes(nested, incoming, keys, registry, sourceRegistry);
+		target[key] = freezeDeep(nested);
+	}
+	if (sourceRegistry !== void 0) for (const [name, node] of sourceRegistry) {
+		if (registry.has(name) && registry.get(name) !== node) throw new Error(`PermDock: duplicate resource name '${name}'`);
+		registry.set(name, node);
+	}
+}
+function mergePermissions(...trees) {
+	if (trees.length === 0) throw new Error("PermDock: mergePermissions() requires at least one tree");
+	const merged = {};
+	const keys = /* @__PURE__ */ new Set();
+	const registry = /* @__PURE__ */ new Map();
+	for (const tree of trees) mergeNodes(merged, tree, keys, registry, isRegistryTree(tree) ? tree[TREE_REGISTRY] : void 0);
+	assertGraphTargets(registry);
+	const leaves = collectLeaves(merged);
+	assertKeys(leaves);
+	return freezeDeep(attachRegistry(merged, registry, leaves));
+}
+/** Former key to current key, for every leaf of `tree`. */
+function renamedKeys(tree) {
+	const map = /* @__PURE__ */ new Map();
+	for (const leaf of listPermissions(tree)) for (const old of formerKeys(leaf)) map.set(old, leaf.key);
+	return map;
+}
+//#endregion
+export { resource as _, getResource as a, listPermissions as c, attachRegistry as d, resourceOfNode as f, formerScopes as g, formerKeys as h, getRegistry as i, mergePermissions as l, annotationsFor as m, findPermission as n, isPermission as o, walk as p, formerByKey as r, isRegistryTree as s, assertKeys as t, renamedKeys as u };

package/dist/permissions-B-wCP5ZC.js

@@ -0,0 +1,30 @@
+import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
+import { d as attachRegistry, p as walk, r as formerByKey, t as assertKeys } from "./permission-registry-Br4jSNVi.js";
+import { r as assertGraphTargets } from "./resource-relations-D_jw0BFx.js";
+//#region src/core/operation-risks.ts
+/** Every `meta.risk` level, lowest first. */
+const OPERATION_RISKS = Object.freeze([
+	"low",
+	"medium",
+	"high",
+	"critical"
+]);
+function isOperationRisk(value) {
+	return OPERATION_RISKS.some((risk) => risk === value);
+}
+//#endregion
+//#region src/core/permissions.ts
+function definePermissions(input, options) {
+	const registry = /* @__PURE__ */ new Map();
+	const leaves = [];
+	const former = formerByKey(options?.renamed);
+	const tree = walk(input, [], registry, leaves, 0, {
+		former,
+		x: options?.x
+	});
+	assertKeys(leaves, former);
+	assertGraphTargets(registry);
+	return freezeDeep(attachRegistry(tree, registry, leaves));
+}
+//#endregion
+export { OPERATION_RISKS as n, isOperationRisk as r, definePermissions as t };

package/dist/{permissions-RJrovw98.js → permissions-CZKiUfFM.js}

@@ -1,6 +1,7 @@
-import { b as resource, n as definePermissions } from "./permissions-DVoF6dMt.js";
-import { s as crud } from "./src-BDwEZWrZ.js";
-import { b as definePlans, x as defineRoles } from "./grantee-Cv5Sogfv.js";
+import { i as crud } from "./src-DLfUWFAI.js";
+import { _ as resource } from "./permission-registry-Br4jSNVi.js";
+import { f as definePlans, p as defineRoles } from "./grantee-Cn1HyUsI.js";
+import { t as definePermissions } from "./permissions-B-wCP5ZC.js";
 //#region src/testing/saas/schema.ts
 function accepts(kind, value) {
 	switch (kind) {

package/dist/{permissions-CDgvKG5L.d.ts → permissions-oEWfl-kl.d.ts}

@@ -1,5 +1,4 @@
-import { g as ResourceInit, u as InferPermissionTree } from "./permissions-DttnqqxC.js";
-import { r as Role, t as Plan } from "./vocabulary-DA8a8zif.js";
+import { C as InferPermissionTree, k as ResourceInit, r as Role, t as Plan } from "./vocabulary-D6lPdb4Z.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/testing/saas/permissions.d.ts
 declare const SaasProjectSchema: StandardSchemaV1<SaasProject>;