permdock 0.4.0 → 0.5.0

package/dist/policy-from-catalog-DzhEc3Y9.js

@@ -0,0 +1,450 @@
+import { r as isRecord, t as compact } from "./compact-CAf557ZB.js";
+import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
+import { p as normalizeWhere } from "./role-builder-CXbis5-X.js";
+import { n as PermDockValidationError } from "./validation-error-ZfUHbKvf.js";
+import { _ as resource, i as getRegistry, n as findPermission } from "./permission-registry-Br4jSNVi.js";
+import { n as defineScopes } from "./scopes-CUPSjo9q.js";
+import { f as definePlans, p as defineRoles } from "./grantee-Cn1HyUsI.js";
+import { r as readWireValidity } from "./validity-CZ7-y0Cj.js";
+import { i as indexPolicy, u as normalizeDelegation } from "./policy-DLZJ5gAp.js";
+import { r as isPortableCondition } from "./hosted-BZIAYvon.js";
+import { t as definePermissions } from "./permissions-B-wCP5ZC.js";
+import { n as copyJson, t as checkSchema } from "./json-schema-B-vAwlde.js";
+import { t as parseCatalog } from "./parse-Cxq0WxrA.js";
+import { n as parsePushedPolicy } from "./pushed-policy-DobP7AHI.js";
+//#region src/catalog/json-schema-validator.ts
+const ANNOTATIONS = /* @__PURE__ */ new Set([
+	"$schema",
+	"$id",
+	"$comment",
+	"title",
+	"description",
+	"default",
+	"examples",
+	"deprecated",
+	"readOnly",
+	"writeOnly"
+]);
+const NUMBERS = [
+	"minLength",
+	"maxLength",
+	"minimum",
+	"maximum",
+	"exclusiveMinimum",
+	"exclusiveMaximum",
+	"minItems",
+	"maxItems"
+];
+const TYPES = /* @__PURE__ */ new Set([
+	"object",
+	"array",
+	"string",
+	"boolean",
+	"integer",
+	"number",
+	"null"
+]);
+function isType(value) {
+	return TYPES.has(value);
+}
+function readList(value, keyword) {
+	if (!Array.isArray(value)) return keyword;
+	const nodes = [];
+	for (const item of value) {
+		const read = readNode(item);
+		if ("unsupported" in read) return read.unsupported;
+		nodes.push(read.node);
+	}
+	return nodes;
+}
+function readMap(value, keyword) {
+	if (!isRecord(value)) return keyword;
+	const out = {};
+	for (const [key, child] of Object.entries(value)) {
+		const read = readNode(child);
+		if ("unsupported" in read) return read.unsupported;
+		Object.defineProperty(out, key, {
+			value: read.node,
+			enumerable: true,
+			writable: true,
+			configurable: true
+		});
+	}
+	return out;
+}
+/**
+* Reads one JSON Schema node into the subset `checkSchema` interprets. Any
+* other keyword is reported, so the caller can refuse the schema instead of
+* validating less than the code did. `format` is accepted only next to a
+* `pattern` that enforces it.
+*/
+function readNode(value) {
+	if (value === true) return { node: {} };
+	if (value === false) return { node: { enum: [] } };
+	if (!isRecord(value)) return { unsupported: "a non-object schema" };
+	const node = {};
+	for (const [keyword, raw] of Object.entries(value)) {
+		if (ANNOTATIONS.has(keyword)) continue;
+		switch (keyword) {
+			case "format":
+				if (typeof value["pattern"] !== "string") return { unsupported: "format" };
+				break;
+			case "type":
+				if (!(isType(raw) || Array.isArray(raw) && raw.every(isType))) return { unsupported: "type" };
+				node["type"] = raw;
+				break;
+			case "const":
+			case "enum":
+			case "required":
+			case "uniqueItems":
+			case "$ref":
+				node[keyword] = raw;
+				break;
+			case "pattern":
+				if (typeof raw !== "string") return { unsupported: "pattern" };
+				node["pattern"] = raw;
+				break;
+			case "minLength":
+			case "maxLength":
+			case "minimum":
+			case "maximum":
+			case "exclusiveMinimum":
+			case "exclusiveMaximum":
+			case "minItems":
+			case "maxItems":
+				if (typeof raw !== "number") return { unsupported: keyword };
+				node[keyword] = raw;
+				break;
+			case "items":
+			case "additionalProperties": {
+				if (keyword === "additionalProperties" && raw === false) {
+					node[keyword] = false;
+					break;
+				}
+				const read = readNode(raw);
+				if ("unsupported" in read) return read;
+				node[keyword] = read.node;
+				break;
+			}
+			case "properties":
+			case "$defs": {
+				const read = readMap(raw, keyword);
+				if (typeof read === "string") return { unsupported: read };
+				node[keyword] = read;
+				break;
+			}
+			case "oneOf":
+			case "anyOf":
+			case "allOf": {
+				const read = readList(raw, keyword);
+				if (typeof read === "string") return { unsupported: read };
+				node[keyword] = read;
+				break;
+			}
+			default: return { unsupported: keyword };
+		}
+	}
+	if (NUMBERS.some((key) => key in node && !Number.isFinite(node[key]))) return { unsupported: "a non-finite bound" };
+	if (typeof node["$ref"] === "string" && !/^#\/\$defs\/[^/]+$/u.test(node["$ref"])) return { unsupported: "$ref" };
+	return { node };
+}
+function refusing(keyword) {
+	const message = `PermDock: the catalog schema uses ${keyword}, which policyFromCatalog does not interpret`;
+	return freezeDeep({ "~standard": {
+		version: 1,
+		vendor: "permdock",
+		validate: () => ({ issues: [{ message }] })
+	} });
+}
+/**
+* A Standard Schema that validates against a catalog resource's JSON Schema.
+* `null` (no JSON Schema in the catalog) gives `undefined`. A schema that uses
+* a keyword outside the supported subset rejects every value, so a hosted
+* check never validates less than the code did.
+*/
+function resourceSchemaFromJson(json) {
+	if (json === null || json === void 0) return;
+	const read = readNode(json);
+	if ("unsupported" in read) return refusing(read.unsupported);
+	const root = read.node;
+	return freezeDeep({ "~standard": {
+		version: 1,
+		vendor: "permdock",
+		validate: (value) => {
+			const issues = [];
+			const copy = copyJson(value, [], issues, /* @__PURE__ */ new Set());
+			if (issues.length === 0) try {
+				checkSchema(root, copy, [], issues);
+			} catch {
+				issues.push({ message: "Unresolvable $ref" });
+			}
+			return issues.length === 0 ? { value } : { issues };
+		}
+	} });
+}
+//#endregion
+//#region src/catalog/policy-from-catalog.ts
+/**
+* Stands in for a condition that only code can evaluate: an allow that holds
+* it never matches and a deny that holds it always applies.
+*/
+const CODE_CONDITION = freezeDeep({
+	op: "opaque",
+	sql: "",
+	fingerprint: "permdock:closure"
+});
+function invalid(message, cause) {
+	throw new PermDockValidationError({
+		code: "invalid-data",
+		permission: "",
+		resource: "",
+		boundary: "catalog",
+		issues: [{ message }],
+		message: `PermDock: policyFromCatalog: ${message}`,
+		...cause === void 0 ? {} : { cause }
+	});
+}
+function actionsOf(permissions, arity) {
+	const entries = permissions.filter((leaf) => leaf.arity === arity).map((leaf) => [leaf.action, { ...leaf.meta }]);
+	return entries.length === 0 ? void 0 : Object.fromEntries(entries);
+}
+function resourceInit(name, entry, permissions) {
+	const options = compact({
+		name,
+		id: entry.id,
+		actions: actionsOf(permissions, "instance"),
+		collection: actionsOf(permissions, "collection"),
+		parent: entry.parent,
+		links: entry.links,
+		disclosure: entry.disclosure,
+		relations: entry.relations,
+		version: entry.version,
+		restricted: entry.restricted === void 0 ? void 0 : entry.restrictedStops === void 0 ? entry.restricted : {
+			field: entry.restricted,
+			stops: entry.restrictedStops
+		},
+		meta: entry.meta
+	});
+	const schema = resourceSchemaFromJson(entry.schema);
+	return schema === void 0 ? resource(options) : resource(schema, options);
+}
+function setPath(root, path, value, key) {
+	let node = root;
+	for (const segment of path.slice(0, -1)) {
+		const next = Object.hasOwn(node, segment) ? node[segment] : void 0;
+		if (next === void 0) {
+			const child = {};
+			node[segment] = child;
+			node = child;
+		} else if (typeof next === "object" && next !== null && Object.getOwnPropertySymbols(next).length === 0) node = next;
+		else invalid(`permission '${key}' nests under another resource`);
+	}
+	const last = path.at(-1);
+	if (last === void 0 || Object.hasOwn(node, last)) invalid(`permission '${key}' collides with another resource path`);
+	node[last] = value;
+}
+function permissionTree(catalog) {
+	const byResource = /* @__PURE__ */ new Map();
+	for (const leaf of catalog.permissions) byResource.set(leaf.resource, [...byResource.get(leaf.resource) ?? [], leaf]);
+	const input = {};
+	const renamed = {};
+	for (const [name, leaves] of byResource) {
+		const entry = Object.hasOwn(catalog.resources, name) ? catalog.resources[name] : void 0;
+		const first = leaves[0];
+		if (entry === void 0 || first === void 0) invalid(`resource '${name}' is missing from catalog.resources`);
+		const suffix = `.${first.action}`;
+		if (!first.key.endsWith(suffix)) invalid(`permission '${first.key}' does not end in its action`);
+		const path = first.key.slice(0, -suffix.length).split(".");
+		for (const leaf of leaves) {
+			if (leaf.key !== `${path.join(".")}.${leaf.action}`) invalid(`permission '${leaf.key}' sits apart from resource '${name}'`);
+			for (const former of leaf.renamedFrom ?? []) renamed[former] = leaf.key;
+		}
+		setPath(input, path, resourceInit(name, entry, leaves), first.key);
+	}
+	try {
+		return definePermissions(input, { renamed });
+	} catch (error) {
+		return invalid(error instanceof Error ? error.message : "invalid permission tree", error);
+	}
+}
+/** A portable grant's condition must be in the portable subset; a non-portable one is read as written and fails closed where it cannot evaluate. */
+function condition(value, label, portable) {
+	if (value === void 0) return;
+	if (portable && !isPortableCondition(value)) return invalid(`${label} is not a portable condition`);
+	try {
+		return normalizeWhere(value);
+	} catch (error) {
+		return invalid(`${label} is not a valid condition`, error);
+	}
+}
+function buildGrant(tree, raw) {
+	const permission = findPermission(tree, raw.permission);
+	if (permission === void 0 || permission.key !== raw.permission) invalid(`grant names unknown permission '${raw.permission}'`);
+	const validity = readWireValidity(raw.validity, raw.effect);
+	const where = raw.closure === true ? CODE_CONDITION : condition(raw.where, `grant '${raw.permission}' where`, raw.portable !== false);
+	return freezeDeep(compact({
+		permission,
+		effect: raw.effect,
+		to: raw.to,
+		role: raw.role,
+		where,
+		check: condition(raw.check, `grant '${raw.permission}' check`, raw.portable !== false),
+		approval: raw.approval,
+		portable: raw.portable !== false,
+		limit: raw.limit,
+		fields: raw.fields,
+		scope: raw.scope ?? "global",
+		name: raw.name,
+		meta: raw.meta,
+		obligations: raw.obligations,
+		purpose: raw.purpose,
+		breakGlass: raw.breakGlass,
+		viaOnly: raw.viaOnly,
+		validity,
+		requires: raw.requires
+	}));
+}
+function roleOn(role, grants, resources, tree) {
+	if (role?.on === void 0) return;
+	if (role.on !== "resource") return role.on;
+	const nodes = [...new Set(grants.flatMap((grant) => typeof grant.scope === "object" ? [grant.scope.resource] : []))].flatMap((name) => {
+		const node = resources.get(name);
+		const first = node === void 0 ? void 0 : leafOf(tree, node);
+		return first === void 0 ? [] : [first];
+	});
+	return nodes.length === 1 ? nodes[0] : nodes;
+}
+/** The subtree of `node`: its path walked from the root of `tree`. */
+function leafOf(tree, node) {
+	let current = tree;
+	for (const segment of node.path.split(".")) current = typeof current === "object" && current !== null && Object.hasOwn(current, segment) ? Reflect.get(current, segment) : void 0;
+	return current;
+}
+function activationOf(role) {
+	const activation = role.activation;
+	if (activation === void 0) return;
+	return compact({
+		maxDuration: activation.maxDuration,
+		justification: activation.justification,
+		approval: activation.approval === true ? "human" : void 0,
+		assurance: activation.assurance
+	});
+}
+function binding(name, role, grants, on) {
+	return freezeDeep(compact({
+		name,
+		grants,
+		on,
+		assignable: role?.assignable ?? on !== void 0,
+		exclusiveWith: role?.exclusiveWith,
+		min: role?.min,
+		max: role?.max,
+		transferOnly: role?.transferOnly,
+		assigns: role?.assigns,
+		for: role?.for,
+		meta: role?.audience === void 0 ? void 0 : { audience: role.audience },
+		activation: role === void 0 ? void 0 : activationOf(role),
+		support: role?.supportAccess === void 0 ? void 0 : {
+			role: name,
+			actorRequired: role.supportAccess.actorRequired,
+			consent: {
+				by: [],
+				durations: role.supportAccess.durations
+			},
+			group: role.supportAccess.group
+		}
+	}));
+}
+function delegationsOf(catalog, tree) {
+	if (catalog.delegations === void 0) return;
+	return catalog.delegations.map((entry, index) => {
+		const permissions = entry.permissions.map((key) => {
+			const leaf = findPermission(tree, key);
+			if (leaf === void 0) invalid(`delegations[${String(index)}] names unknown permission '${key}'`);
+			return leaf;
+		});
+		const input = {
+			from: entry.from,
+			to: entry.to,
+			permissions,
+			validFrom: entry.validity?.from,
+			validUntil: entry.validity?.until
+		};
+		try {
+			return normalizeDelegation(input, index, tree);
+		} catch (error) {
+			return invalid(`delegations[${String(index)}] is invalid`, error);
+		}
+	});
+}
+function identity(user) {
+	return user;
+}
+/**
+* Rebuilds an evaluable `Policy` from a catalog (`permissions.catalog.json`)
+* and the policy `permdock cloud push` sent with it, for a service that holds
+* no application code: the hosted AuthZEN endpoint or a `mergeHostedGrants`
+* pre-check. Throws `PermDockValidationError` when either input is malformed
+* or the two disagree.
+*
+* What only code can answer fails closed: an allow whose condition is a
+* closure never grants and such a deny always applies; a resource schema
+* keyword outside the supported JSON Schema subset rejects every value; a
+* support role has no one who may consent. Grant levels and OAuth scopes
+* are not in a catalog, so the rebuilt policy has none.
+*/
+function policyFromCatalog(catalogInput, pushedInput, options = {}) {
+	const catalog = parseCatalog(catalogInput);
+	const pushed = parsePushedPolicy(pushedInput);
+	const permissions = permissionTree(catalog);
+	const resources = getRegistry(permissions);
+	const scopes = defineScopes(pushed.scopes === void 0 ? catalog.scopes === void 0 ? void 0 : Object.fromEntries(catalog.scopes.map((scope) => [scope.name, compact({
+		key: scope.key,
+		within: scope.within
+	})])) : Object.fromEntries(pushed.scopes.map((scope) => [scope.name, compact({
+		key: scope.key,
+		within: scope.within
+	})])));
+	const grants = pushed.grants.map((raw) => buildGrant(permissions, raw));
+	const catalogRoles = new Map((catalog.roles ?? []).map((role) => [role.key, role]));
+	const roleNames = [.../* @__PURE__ */ new Set([...grants.flatMap((grant) => grant.role === null ? [] : [grant.role]), ...(catalog.roles ?? []).map((role) => role.key)])];
+	const roles = roleNames.flatMap((name) => {
+		const role = catalogRoles.get(name);
+		const own = grants.filter((grant) => grant.role === name);
+		if (own.length === 0 && role?.activation === void 0 && role?.supportAccess === void 0) return [];
+		return [binding(name, role, own, roleOn(role, own, resources, permissions))];
+	});
+	const vocabulary = freezeDeep({
+		permissions,
+		roles: defineRoles(Object.fromEntries(roleNames.map((name) => {
+			const role = catalogRoles.get(name);
+			return [name, compact({
+				on: role?.on === void 0 || role.on === "resource" ? void 0 : role.on,
+				assignable: role?.assignable,
+				meta: role?.audience === void 0 ? void 0 : { audience: role.audience }
+			})];
+		}))),
+		plans: definePlans(Object.fromEntries((catalog.plans ?? []).map((plan) => [plan.key, {}])))
+	});
+	const subject = options.subject ?? identity;
+	const delegations = delegationsOf(catalog, permissions);
+	const hostable = catalog.permissions.filter((leaf) => leaf.hostable === true).map((leaf) => leaf.key);
+	return freezeDeep(compact({
+		permissions,
+		roles,
+		rolesByName: new Map(roles.map((role) => [role.name, role])),
+		grants,
+		vocabulary,
+		scopes,
+		principal: subject,
+		subject,
+		validate: "boundary",
+		fingerprint: pushed.fingerprint,
+		resources,
+		hostable,
+		delegations,
+		index: indexPolicy(roles, grants, vocabulary)
+	}));
+}
+//#endregion
+export { resourceSchemaFromJson as n, policyFromCatalog as t };

package/dist/policy-module-CTlwMvLI.js

@@ -0,0 +1,89 @@
+import { t as byCodePoint } from "./compare-pfyVnBjE.js";
+import { t as emitPermissionsModule } from "./generate-CNU1pIOo.js";
+//#region src/cli/importers/policy-module.ts
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/u;
+/** Actions a collection permission decides: there is no row yet, or a list of rows. */
+const COLLECTION_ACTIONS = /* @__PURE__ */ new Set(["create", "list"]);
+/** Whether `name` can be a resource or action key in generated code. */
+function isIdentifier(name) {
+	return IDENTIFIER.test(name);
+}
+function quote(value) {
+	return `'${value.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`;
+}
+function isValueList(value) {
+	return Array.isArray(value);
+}
+function renderValue(value) {
+	if (value === null) return "null";
+	if (isValueList(value)) return `[${value.map((item) => renderValue(item)).join(", ")}]`;
+	if (typeof value === "object") return `principal.${value.principal}`;
+	return typeof value === "string" ? quote(value) : String(value);
+}
+function propertyKey(name) {
+	return isIdentifier(name) ? name : quote(name);
+}
+function renderWhere(where) {
+	if ("and" in where) return `{ and: [${where.and.map(renderWhere).join(", ")}] }`;
+	if ("or" in where) return `{ or: [${where.or.map(renderWhere).join(", ")}] }`;
+	if ("not" in where) return `{ not: ${renderWhere(where.not)} }`;
+	const value = renderValue(where.value);
+	return where.op === "eq" ? `{ ${propertyKey(where.field)}: ${value} }` : `{ ${propertyKey(where.field)}: { ${where.op}: ${value} } }`;
+}
+function renderGrant(grant) {
+	const options = [...grant.where === void 0 ? [] : [`where: ${renderWhere(grant.where)}`], ...grant.fields === void 0 ? [] : [`fields: [${grant.fields.map(quote).join(", ")}]`]];
+	const permission = `permissions.${grant.resource}.${grant.action}`;
+	return options.length === 0 ? `${grant.effect}(${permission})` : `${grant.effect}(${permission}, { ${options.join(", ")} })`;
+}
+function usesPrincipal(where) {
+	return where !== void 0 && JSON.stringify(where).includes("\"principal\"");
+}
+/** Resources keyed by name, each with its actions split into instance and collection ones. */
+function resourcesOf(actions) {
+	return [...actions.entries()].toSorted(([a], [b]) => byCodePoint(a, b)).map(([name, set]) => {
+		const sorted = [...set].toSorted();
+		return {
+			path: [name],
+			actions: sorted.filter((action) => !COLLECTION_ACTIONS.has(action)),
+			collection: sorted.filter((action) => COLLECTION_ACTIONS.has(action))
+		};
+	});
+}
+/**
+* A deterministic module with the imported `permissions` and a `policy` of
+* their roles. Rules stay data: an import writes declarations and grants,
+* never code an application maintains by hand.
+*/
+function emitPolicyModule(input) {
+	const permissionsModule = emitPermissionsModule({
+		generator: input.generator,
+		schema: void 0,
+		resources: resourcesOf(input.actions),
+		...input.exports === void 0 ? {} : { exports: input.exports }
+	});
+	const grants = input.roles.flatMap((role) => role.grants);
+	const names = /* @__PURE__ */ new Set([
+		"definePermissions",
+		"definePolicy",
+		"resource",
+		"role"
+	]);
+	for (const grant of grants) names.add(grant.effect);
+	if (grants.some((grant) => usesPrincipal(grant.where))) names.add("principal");
+	const imports = `import { ${[...names].toSorted().join(", ")} } from 'permdock'`;
+	const roles = input.roles.toSorted((a, b) => byCodePoint(a.name, b.name)).map((role) => {
+		const body = role.grants.map((grant) => `      ${renderGrant(grant)},`);
+		return body.length === 0 ? `    role(${quote(role.name)}, []),` : `    role(${quote(role.name)}, [\n${body.join("\n")}\n    ]),`;
+	});
+	return `${permissionsModule.replace("import { definePermissions, resource } from 'permdock'", imports)}
+export const policy = definePolicy(permissions, {
+  roles: [
+${roles.join("\n")}
+  ],
+  subject: (user: { readonly id: string; readonly roles: readonly string[] }) =>
+    user,
+})
+`;
+}
+//#endregion
+export { isIdentifier as n, emitPolicyModule as t };