permdock 0.4.0 → 0.5.0

package/dist/catalog/index.js

@@ -1,2 +1,51 @@
-import { n as rowConditionKeys, t as parseCatalog } from "../parse-CVFQHk6c.js";
-export { parseCatalog, rowConditionKeys };
+import { n as freezeDeep } from "../freeze-CrU8nQeX.js";
+import { t as hostedGrantDrops } from "../hosted-BZIAYvon.js";
+import { n as rowConditionKeys, t as parseCatalog } from "../parse-Cxq0WxrA.js";
+import { t as operationFindings } from "../operation-findings-DgATDpvh.js";
+import { n as resourceSchemaFromJson, t as policyFromCatalog } from "../policy-from-catalog-DzhEc3Y9.js";
+import { n as parsePushedPolicy, r as pushedPolicy, t as PUSHED_POLICY_SCHEMA } from "../pushed-policy-DobP7AHI.js";
+//#region src/catalog/drift.ts
+/** The finding a drop reason becomes; `null` for a reason the catalog did not cause. */
+function findingCode(reason) {
+	switch (reason) {
+		case "unknown-permission": return "permission-removed";
+		case "not-hostable": return "not-hostable";
+		case "unknown-grantee": return "grantee-removed";
+		case "weaker-approval": return "approval-tightened";
+		case "non-portable":
+		case "invalid": return null;
+		default: return reason;
+	}
+}
+/**
+* The hosted grants of `document` that `policy` no longer accepts, as drift
+* findings with the grant id set. A grant dropped for a reason the catalog
+* cannot cause (`non-portable`, `invalid`) is not a finding.
+*/
+function hostedGrantFindings(policy, document) {
+	if (document === null) return [];
+	return hostedGrantDrops(policy, document).flatMap((drop) => {
+		const code = findingCode(drop.reason);
+		return code === null ? [] : [freezeDeep({
+			code,
+			permission: drop.permission,
+			...drop.grant === "" ? {} : { grant: drop.grant }
+		})];
+	});
+}
+/**
+* The `data` of a `com.permdock.catalog.drifted` event: the hosted grants
+* `next` breaks, then the operations whose risk rose or whose approval was
+* removed between `previous` and `next`.
+*/
+function catalogDrift(input) {
+	const findings = [...hostedGrantFindings(input.policy, input.document ?? null), ...operationFindings(input.previous, input.next)];
+	return freezeDeep({
+		kind: "drift",
+		fingerprint: input.next.fingerprint ?? "",
+		...input.previous.fingerprint === void 0 ? {} : { previous: input.previous.fingerprint },
+		findings
+	});
+}
+//#endregion
+export { PUSHED_POLICY_SCHEMA, catalogDrift, hostedGrantFindings, operationFindings, parseCatalog, parsePushedPolicy, policyFromCatalog, pushedPolicy, resourceSchemaFromJson, rowConditionKeys };

package/dist/{catalog-tZUyOfOv.js → catalog-BECMPrwc.js}

@@ -1,8 +1,10 @@
+import { r as isRecord } from "./compact-CAf557ZB.js";
 import { r as listSourceFiles, t as defaultSrcPath } from "./files-D_JIzUrP.js";
-import { a as formatCatalogMarkdown, i as formatCatalogJson, r as catalogSchemaDocument, t as buildCatalog } from "./catalog-doc-DWtg0gGR.js";
-import { a as loadModule, i as loadConfiguredPolicy, r as leavesOf, s as pickNamed, t as asPermissionTree } from "./load-C3_oTHyO.js";
-import { i as scanSources, r as runCollect } from "./collect-2SrB7lfk.js";
-import { existsSync } from "node:fs";
+import { a as formatCatalogJson, i as catalogSchemaDocument, o as formatCatalogMarkdown, t as buildCatalog } from "./catalog-doc-C9wjsfNY.js";
+import { a as loadModule, i as loadConfiguredPolicy, r as leavesOf, s as pickNamed, t as asPermissionTree } from "./load-DFS_ry0W.js";
+import { a as loadConfiguredOperations, i as scanSources, r as runCollect } from "./collect-CrZJJnEF.js";
+import { n as fileSummary, t as applyFiles } from "./files-C5ZI27eV.js";
+import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 //#region src/cli/catalog.ts
 async function runCatalog(input) {
@@ -22,7 +24,7 @@ async function runCatalog(input) {
 		const srcPath = input.config.collect?.srcPath ?? defaultSrcPath();
 		const files = listSourceFiles(input.cwd, srcPath);
 		const scan = scanSources(input.cwd, files, new Set(leavesOf(tree).map((leaf) => leaf.key)));
-		document = buildCatalog(tree, scan, input.now.toISOString(), await loadConfiguredPolicy(input.cwd, input.config.policy));
+		document = buildCatalog(tree, scan, input.now.toISOString(), await loadConfiguredPolicy(input.cwd, input.config.policy), await loadConfiguredOperations(input.cwd, input.config.operations));
 	} else {
 		const collected = await runCollect({
 			cwd: input.cwd,
@@ -51,5 +53,48 @@ async function runCatalog(input) {
 		output: formatCatalogJson(filtered)
 	};
 }
+/** The comparable form of a catalog file: without the fields every run changes. */
+function comparable(text) {
+	try {
+		const parsed = JSON.parse(text);
+		if (isRecord(parsed)) {
+			const { generatedAt: _generatedAt, generator: _generator, ...rest } = parsed;
+			return JSON.stringify(rest);
+		}
+	} catch {}
+	return text;
+}
+/** `catalog --out`: writes the export, or with `--check` exits 1 when the file differs. */
+function catalogFile(cwd, out, text, check) {
+	if (check) {
+		const path = resolve(cwd, out);
+		if (!existsSync(path)) return {
+			code: 1,
+			output: `catalog missing: ${out}`,
+			data: {
+				out,
+				stale: true
+			}
+		};
+		const stale = comparable(readFileSync(path, "utf8")) !== comparable(text);
+		return {
+			code: stale ? 1 : 0,
+			output: stale ? `catalog stale: ${out}` : `${out} is up to date`,
+			data: {
+				out,
+				stale
+			}
+		};
+	}
+	const applied = applyFiles(cwd, [{
+		path: out,
+		text
+	}]);
+	return {
+		code: 0,
+		output: fileSummary(applied, false),
+		data: { files: applied }
+	};
+}
 //#endregion
-export { runCatalog as t };
+export { runCatalog as n, catalogFile as t };

package/dist/catalog-DjhMYYCq.js

@@ -0,0 +1 @@
+export { t as catalogFile, n as runCatalog } from "./catalog-BECMPrwc.js";

package/dist/catalog-R_A__RsH.js

@@ -0,0 +1,52 @@
+import { c as missingInput } from "./errors-CWTY6uih.js";
+import { t as defineLeaf } from "./command-L8EstFNm.js";
+import { c as given, l as outFlag, t as checkFlag, u as permissionsFlag } from "./flags-C3DktBDY.js";
+//#region src/cli/commands/catalog.ts
+const RUN_FORMAT = {
+	catalog: "json",
+	"json-schema": "schema",
+	markdown: "markdown"
+};
+const catalog = defineLeaf({
+	flags: {
+		kind: {
+			type: "enum",
+			options: [
+				"catalog",
+				"json-schema",
+				"markdown"
+			],
+			default: "catalog",
+			description: "What to print: the catalog, its JSON Schema, or a Markdown table"
+		},
+		...permissionsFlag,
+		include: {
+			type: "string",
+			repeatable: true,
+			description: "Permission keys or prefixes to keep",
+			valueHint: "key"
+		},
+		...outFlag,
+		...checkFlag
+	},
+	async run(ctx, { flags }) {
+		const { catalogFile, runCatalog } = await import("./catalog-DjhMYYCq.js");
+		const result = await runCatalog({
+			cwd: ctx.cwd,
+			config: ctx.config,
+			format: RUN_FORMAT[flags.kind],
+			from: given(flags.permissions),
+			include: flags.include,
+			now: ctx.now,
+			io: ctx.io
+		});
+		const out = given(flags.out === "-" ? "" : flags.out);
+		if (out === void 0) {
+			if (flags.check) throw missingInput("catalog --check", ["--out"], "the file to compare");
+			return result;
+		}
+		return result.code === 0 ? catalogFile(ctx.cwd, out, result.output, flags.check) : result;
+	}
+});
+//#endregion
+export { catalog };

package/dist/{catalog-doc-DWtg0gGR.js → catalog-doc-C9wjsfNY.js}

@@ -1,11 +1,12 @@
-import { t as catalogFingerprint } from "./src-Bb7no-hS.js";
-import { a as getResource, c as listPermissions, h as formerKeys } from "./permission-registry-BsblpB-z.js";
-import { m as findRole } from "./grantee-CXY-0C87.js";
-import { t as canonicalJson } from "./canonical-json-CFKyFOke.js";
+import { a as getResource, c as listPermissions, h as formerKeys } from "./permission-registry-Br4jSNVi.js";
+import { t as canonicalJson } from "./canonical-json-BC8_nMTw.js";
+import { m as findRole, v as listRoles } from "./grantee-Cn1HyUsI.js";
+import { i as wireValidity } from "./validity-CZ7-y0Cj.js";
 import { t as byCodePoint } from "./compare-pfyVnBjE.js";
-import { t as catalogSchema } from "./schema-DjQBcAP9.js";
+import { t as catalogFingerprint } from "./catalog-fingerprint-CCP0-yQS.js";
+import { t as catalogSchema } from "./schema-B4v0Qrac.js";
 import { t as policyRowConditionKeys } from "./row-conditions-h2HythXQ.js";
-import { s as generatorBanner, t as CATALOG_SCHEMA } from "./version-BEogC-rB.js";
+import { c as generatorBanner, n as CATALOG_SCHEMA } from "./version-CEbQ5UeM.js";
 //#region src/cli/catalog-doc.ts
 function leafLevels(tree, leaf) {
 	if (leaf.kind !== "instance") return;
@@ -13,7 +14,7 @@ function leafLevels(tree, leaf) {
 	return names.length === 0 ? void 0 : names;
 }
 /** With `policy`, permissions carry `hostable` and a known `rowConditions` (without, it is `true`), and roles carry `on`, `assignable` and their ownership rules. */
-function buildCatalog(tree, scan, generatedAt, policy) {
+function buildCatalog(tree, scan, generatedAt, policy, operations) {
 	const hostable = new Set(policy?.hostable ?? []);
 	const rowConditions = policy === void 0 ? void 0 : policyRowConditionKeys(policy);
 	const resources = {};
@@ -21,18 +22,13 @@ function buildCatalog(tree, scan, generatedAt, policy) {
 	for (const leaf of listPermissions(tree)) {
 		if (resources[leaf.resource] !== void 0) continue;
 		const node = getResource(tree, leaf.resource);
-		resources[leaf.resource] = compactResource(definedIn === void 0 ? {
+		resources[leaf.resource] = compactResource({
 			id: node?.id ?? "id",
 			schema: node === void 0 ? null : jsonSchemaOf(node),
-			relations: node?.relations,
-			version: node?.version,
-			restricted: node?.restricted,
-			restrictedStops: node?.restrictedStops,
-			meta: node?.meta
-		} : {
-			id: node?.id ?? "id",
-			schema: node === void 0 ? null : jsonSchemaOf(node),
-			definedIn,
+			...definedIn === void 0 ? {} : { definedIn },
+			parent: node?.parent,
+			links: node?.links,
+			disclosure: node?.disclosure,
 			relations: node?.relations,
 			version: node?.version,
 			restricted: node?.restricted,
@@ -63,7 +59,9 @@ function buildCatalog(tree, scan, generatedAt, policy) {
 		...catalogRoles(scan.roleNames, policy),
 		...scan.planNames.length === 0 ? {} : { plans: scan.planNames.map((key) => ({ key })) },
 		...policy === void 0 ? {} : { grants: catalogGrants(policy) },
-		...policy?.delegations === void 0 ? {} : { delegations: catalogDelegations(policy) }
+		...policy?.delegations === void 0 ? {} : { delegations: catalogDelegations(policy) },
+		...operations === void 0 ? {} : { operations },
+		...policy?.oauthScopes === void 0 || policy.oauthScopes.length === 0 ? {} : { oauthScopes: catalogOAuthScopes(policy.oauthScopes) }
 	};
 	const head = {
 		$schema: CATALOG_SCHEMA,
@@ -116,7 +114,7 @@ function catalogGrant(grant) {
 			check: grant.portable ? grant.check : void 0,
 			approval: catalogApproval(grant.approval),
 			fields: grant.fields,
-			validity: grant.validity,
+			validity: wireValidity(grant.validity),
 			name: grant.name,
 			purpose: grant.purpose,
 			requires: grant.requires?.length === 1 ? grant.requires[0] : grant.requires,
@@ -152,13 +150,19 @@ function catalogDelegations(policy) {
 		from: delegation.from,
 		to: delegation.to,
 		permissions: delegation.permissions,
-		validity: delegation.validity
+		validity: wireValidity(delegation.validity)
 	})).toSorted((a, b) => {
 		const left = canonicalJson(a);
 		const right = canonicalJson(b);
 		return left < right ? -1 : left > right ? 1 : 0;
 	});
 }
+function catalogOAuthScopes(declared) {
+	return declared.map((entry) => ({
+		scope: entry.scope,
+		permissions: [...new Set(entry.permissions)].toSorted(byCodePoint)
+	})).toSorted((a, b) => byCodePoint(a.scope, b.scope));
+}
 /** Per permission key, the distinct approvals the code allows require, in policy order. */
 function codeApprovals(policy) {
 	const out = /* @__PURE__ */ new Map();
@@ -199,11 +203,23 @@ function catalogScopes(policy) {
 }
 function catalogRoles(scanned, policy) {
 	if (policy === void 0) return scanned.length === 0 ? {} : { roles: scanned.map((key) => ({ key })) };
-	const names = [.../* @__PURE__ */ new Set([...scanned, ...policy.roles.map((role) => role.name)])].toSorted();
+	const names = [.../* @__PURE__ */ new Set([
+		...scanned,
+		...policy.roles.map((role) => role.name),
+		...listRoles(policy.vocabulary?.roles).map((leaf) => leaf.key)
+	])].toSorted();
 	if (names.length === 0) return {};
 	return { roles: names.map((key) => {
 		const binding = policy.rolesByName.get(key);
-		if (binding === void 0) return { key };
+		if (binding === void 0) {
+			const leaf = findRole(policy.vocabulary?.roles, key);
+			return leaf === void 0 ? { key } : withDefined({
+				key,
+				on: leaf.on,
+				assignable: leaf.assignable,
+				audience: leaf.meta.audience
+			});
+		}
 		const audience = binding.meta?.audience ?? findRole(policy.vocabulary.roles, key)?.meta.audience;
 		return withDefined({
 			key,
@@ -240,6 +256,12 @@ function compactResource(resource) {
 		schema: resource.schema,
 		...withDefined({
 			definedIn: resource.definedIn,
+			parent: resource.parent === void 0 ? void 0 : {
+				field: resource.parent.field,
+				resource: resource.parent.resource
+			},
+			links: resource.links === void 0 || Object.keys(resource.links).length === 0 ? void 0 : resource.links,
+			disclosure: resource.disclosure === "hide" ? "hide" : void 0,
 			relations,
 			version: resource.version,
 			restricted: resource.restricted,
@@ -290,4 +312,4 @@ function catalogSchemaDocument() {
 	return catalogSchema;
 }
 //#endregion
-export { formatCatalogMarkdown as a, formatCatalogJson as i, catalogForCompare as n, jsonSchemaOf as o, catalogSchemaDocument as r, buildCatalog as t };
+export { formatCatalogJson as a, catalogSchemaDocument as i, catalogForCompare as n, formatCatalogMarkdown as o, catalogOAuthScopes as r, jsonSchemaOf as s, buildCatalog as t };

package/dist/catalog-fingerprint-CCP0-yQS.js

@@ -0,0 +1,153 @@
+import { r as isRecord, t as compact } from "./compact-CAf557ZB.js";
+import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
+import { n as isForbiddenKey } from "./paths-DXSHAMIa.js";
+import { l as isRfc3339 } from "./time-DkWjdL98.js";
+import { t as canonicalJson } from "./canonical-json-BC8_nMTw.js";
+import { r as sha256Digest } from "./sha256-D9ihqmvd.js";
+import { C as EVENT_SCHEMA_IDS, T as SINK_EVENT_SCHEMAS, i as RESERVED_CLOUD_EVENT_TYPES, l as isAbsoluteUri, r as CLOUD_EVENT_TYPES, s as cloudEventType, u as isTraceparent, v as CATALOG_EVENT_SCHEMA } from "./sink-BEZSlMS_.js";
+import { n as copyJson, t as checkSchema } from "./json-schema-B-vAwlde.js";
+//#region src/core/parse-sink-events.ts
+function hasUnsafeKey(value) {
+	if (Array.isArray(value)) return value.some(hasUnsafeKey);
+	if (!isRecord(value)) return false;
+	return Object.keys(value).some((key) => isForbiddenKey(key) || hasUnsafeKey(value[key]));
+}
+/** A JSON copy of `value` that matches `schema`, or `null`. */
+function jsonMatching(value, schema) {
+	const issues = [];
+	const copy = copyJson(value, [], issues, /* @__PURE__ */ new Set());
+	if (issues.length > 0 || !isRecord(copy) || hasUnsafeKey(copy)) return null;
+	checkSchema(schema, copy, [], issues);
+	return issues.length === 0 ? copy : null;
+}
+function timesValid(event) {
+	const membership = event["membership"];
+	return isRfc3339(event["at"]) && (event["expiresAt"] === void 0 || isRfc3339(event["expiresAt"])) && (!isRecord(membership) || membership["expiresAt"] === void 0 || isRfc3339(membership["expiresAt"]));
+}
+function rulesHold(event) {
+	if (event["type"] === "membership") return event["scope"] === void 0 === (event["id"] === void 0) && (event["within"] === void 0 || event["scope"] !== void 0);
+	if (event["type"] === "credential") return event["sample"] === void 0 || event["operation"] === "used";
+	if (event["type"] === "automation") return event["run"] === void 0 === (event["operation"] !== "run");
+	if (event["type"] === "delivery") return event["operation"] === "failed" || event["cause"] === void 0 && event["retryable"] === void 0;
+	return true;
+}
+/**
+* Validates one untrusted sink event against its family's schema and returns
+* a frozen copy, or `null` for anything else. Never throws.
+*/
+function parseSinkEvent(value) {
+	if (!isRecord(value)) return null;
+	const type = value["type"];
+	if (typeof type !== "string" || !Object.hasOwn(SINK_EVENT_SCHEMAS, type)) return null;
+	const schema = SINK_EVENT_SCHEMAS[type];
+	const copy = jsonMatching(value, schema);
+	if (copy === null || !timesValid(copy) || !rulesHold(copy)) return null;
+	return freezeDeep(copy);
+}
+/**
+* Validates an untrusted list of sink events, such as a request body a sink
+* receiver read. Each event that fails its schema is dropped, and a value
+* that is not an array yields no events. Never throws.
+*/
+function parseSinkEvents(value) {
+	if (!Array.isArray(value)) return Object.freeze([]);
+	return Object.freeze(value.flatMap((item) => {
+		const event = parseSinkEvent(item);
+		return event === null ? [] : [event];
+	}));
+}
+/** Validates the data of a `com.permdock.catalog.*` CloudEvent; `null` when it does not match. */
+function parseCatalogEventData(value) {
+	const copy = jsonMatching(value, CATALOG_EVENT_SCHEMA);
+	return copy === null ? null : freezeDeep(copy);
+}
+const RESERVED = new Set(RESERVED_CLOUD_EVENT_TYPES);
+const TYPES = new Set(Object.values(CLOUD_EVENT_TYPES).filter((type) => !RESERVED.has(type)));
+function catalogType(data) {
+	return data.kind === "publish" ? CLOUD_EVENT_TYPES.catalogPublished : CLOUD_EVENT_TYPES.catalogDrifted;
+}
+function envelopeValid(value) {
+	return value["specversion"] === "1.0" && typeof value["type"] === "string" && TYPES.has(value["type"]) && isAbsoluteUri(value["source"]) && typeof value["id"] === "string" && value["id"] !== "" && isRfc3339(value["time"]) && (value["subject"] === void 0 || typeof value["subject"] === "string") && (value["datacontenttype"] === void 0 || value["datacontenttype"] === "application/json") && (value["traceparent"] === void 0 || isTraceparent(value["traceparent"])) && (value["tracestate"] === void 0 || typeof value["tracestate"] === "string");
+}
+/**
+* Validates one CloudEvent against the closed type list, its `dataschema` and
+* its data shape; `null` for anything else, a reserved type included. Never
+* throws.
+*/
+function parseCloudEvent(value) {
+	if (!isRecord(value) || hasUnsafeKey(value) || !envelopeValid(value)) return null;
+	const type = value["type"];
+	const raw = value["data"];
+	let data;
+	let expected;
+	let schema;
+	if (type === CLOUD_EVENT_TYPES.catalogPublished || type === CLOUD_EVENT_TYPES.catalogDrifted) {
+		const catalog = parseCatalogEventData(raw);
+		data = catalog;
+		expected = catalog === null ? void 0 : catalogType(catalog);
+		schema = EVENT_SCHEMA_IDS.catalog;
+	} else {
+		const event = parseSinkEvent(raw);
+		data = event;
+		expected = event === null ? void 0 : cloudEventType(event);
+		schema = event === null ? "" : EVENT_SCHEMA_IDS[event.type];
+	}
+	if (data === null || expected !== type || value["dataschema"] !== schema) return null;
+	return freezeDeep(compact({
+		specversion: "1.0",
+		type: expected,
+		source: value["source"],
+		subject: value["subject"],
+		id: value["id"],
+		time: value["time"],
+		datacontenttype: "application/json",
+		dataschema: schema,
+		traceparent: value["traceparent"],
+		tracestate: value["tracestate"],
+		data
+	}));
+}
+/**
+* Validates a CloudEvents JSON batch (`application/cloudevents-batch+json`):
+* `null` unless the value is an array and every event in it is valid.
+*/
+function parseCloudEventBatch(value) {
+	if (!Array.isArray(value)) return null;
+	const events = [];
+	for (const item of value) {
+		const event = parseCloudEvent(item);
+		if (event === null) return null;
+		events.push(event);
+	}
+	return Object.freeze(events);
+}
+//#endregion
+//#region src/core/catalog-fingerprint.ts
+const OMITTED_TOP_LEVEL = /* @__PURE__ */ new Set([
+	"generatedAt",
+	"generator",
+	"fingerprint"
+]);
+function fingerprintInput(catalog) {
+	const out = {};
+	for (const [key, value] of Object.entries(catalog)) {
+		if (OMITTED_TOP_LEVEL.has(key)) continue;
+		out[key] = key === "permissions" && Array.isArray(value) ? value.map((permission) => {
+			if (!isRecord(permission)) return permission;
+			const { usages: _usages, ...rest } = permission;
+			return rest;
+		}) : value;
+	}
+	return out;
+}
+/**
+* The catalog v1 fingerprint: the `sha-256:` digest of its RFC 8785 JSON without `generatedAt`, `generator`, `fingerprint`
+* and every `permissions[].usages`, so neither the CLI version, the clock nor
+* call sites change it.
+*/
+function catalogFingerprint(catalog) {
+	if (!isRecord(catalog)) throw new TypeError("PermDock: a catalog must be an object");
+	return sha256Digest(canonicalJson(fingerprintInput(catalog)));
+}
+//#endregion
+export { parseSinkEvent as a, parseCloudEventBatch as i, parseCatalogEventData as n, parseSinkEvents as o, parseCloudEvent as r, catalogFingerprint as t };

package/dist/chat/index.d.ts

@@ -0,0 +1,2 @@
+import { a as ChatCommandResult, c as createPermDock, d as SubjectFromChatOptions, f as isChatAuthor, i as ChatCommandContext, l as ChatAuthor, n as ChatActionResult, o as ChatPermDock, p as subjectFromChat, r as ChatCommand, s as ChatPermDockOptions, t as ChatAction, u as ChatPrincipal } from "../create-0VZ7Pdiu.js";
+export { type ChatAction, type ChatActionResult, type ChatAuthor, type ChatCommand, type ChatCommandContext, type ChatCommandResult, type ChatPermDock, type ChatPermDockOptions, type ChatPrincipal, type SubjectFromChatOptions, createPermDock, isChatAuthor, subjectFromChat };