permdock 0.0.0 → 0.2.0

package/dist/openapi-BqRBvAng.js

@@ -0,0 +1,538 @@
+import { t as compact } from "./compact-y6vfu2_f.js";
+import { _ as listPermissions, i as findPermission, p as isPermission } from "./permissions-DVoF6dMt.js";
+import { n as sha256 } from "./sha256-BO0swRXL.js";
+import { t as requiresApproval } from "./approval-required-TzNB9oQA.js";
+import { i as PROFILE_PARAMETERS, n as GNAP_RESERVED, r as PROFILE_NAMES, t as DRAFT_PINS } from "./pins-8ILTftC9.js";
+//#region src/openapi/emit.ts
+function assertScheme(options) {
+	if (options.scheme.type === "gnap") throw new TypeError(GNAP_RESERVED);
+}
+function asList(permission) {
+	return isPermission(permission) ? [permission] : permission;
+}
+function grantsOf(policy, permissions) {
+	const keys = new Set(permissions.map((leaf) => leaf.key));
+	return policy.grants.filter((grant) => keys.has(grant.permission.key));
+}
+function grantsAnyone(grant) {
+	return (Array.isArray(grant.to) ? grant.to : [grant.to]).some((grantee) => grantee.kind === "anyone");
+}
+/** Every subject is granted it: an unconditional allow to `anyone()` and no deny. */
+function isPublic(policy, permission) {
+	const grants = grantsOf(policy, [permission]);
+	return grants.every((grant) => grant.effect === "allow") && grants.some((grant) => grantsAnyone(grant) && grant.where === void 0 && grant.check === void 0 && grant.approval === void 0 && grant.closure === void 0 && grant.limit === void 0 && grant.purpose === void 0 && grant.viaOnly === void 0);
+}
+function mergeRecord(base, extra) {
+	const result = {};
+	for (const [key, value] of Object.entries(base)) result[key] = value;
+	for (const [key, value] of Object.entries(extra)) result[key] = value;
+	return result;
+}
+function scopesOf$1(policy) {
+	const scopes = {};
+	for (const leaf of listPermissions(policy.permissions)) scopes[leaf.scope] = leaf.meta.description ?? leaf.meta.title ?? leaf.key;
+	return scopes;
+}
+function flowWithScopes(flow, scopes) {
+	return mergeRecord(flow ?? {}, { scopes });
+}
+function securitySchemesOf(policy, options) {
+	assertScheme(options);
+	const target = options.target ?? "3.2";
+	const scopes = scopesOf$1(policy);
+	const name = options.scheme.name;
+	if (options.scheme.ref !== void 0 && target !== "3.1") return { [name]: { $ref: options.scheme.ref } };
+	const flowsIn = options.scheme.flows ?? { authorizationCode: {} };
+	const flows = {};
+	if (flowsIn.authorizationCode !== void 0) flows["authorizationCode"] = flowWithScopes(flowsIn.authorizationCode, scopes);
+	if (flowsIn.clientCredentials !== void 0) flows["clientCredentials"] = flowWithScopes(flowsIn.clientCredentials, scopes);
+	if (flowsIn.deviceAuthorization !== void 0) {
+		if (target === "3.1") {
+			const { deviceAuthorizationUrl, ...rest } = flowsIn.deviceAuthorization;
+			flows["x-oai-deviceAuthorization"] = flowWithScopes(compact({
+				...rest,
+				"x-oai-deviceAuthorizationUrl": deviceAuthorizationUrl
+			}), scopes);
+		} else flows["deviceAuthorization"] = flowWithScopes(flowsIn.deviceAuthorization, scopes);
+	}
+	const scheme = compact({
+		type: options.scheme.type,
+		flows: options.scheme.type === "oauth2" ? flows : void 0,
+		openIdConnectUrl: options.scheme.type === "openIdConnect" ? options.scheme.openIdConnectUrl : void 0,
+		oauth2MetadataUrl: target === "3.2" || target === "3.3" ? options.scheme.oauth2MetadataUrl : void 0,
+		"x-permdock-oauth2MetadataUrl": target === "3.1" ? options.scheme.oauth2MetadataUrl : void 0,
+		deprecated: target !== "3.1" && options.scheme.deprecated === true ? true : void 0,
+		"x-oai-deprecated": target === "3.1" && options.scheme.deprecated === true ? true : void 0,
+		"x-permdock-securityProfile": options.securityProfile
+	});
+	const schemes = { [name]: scheme };
+	if (target === "3.3" && options.securityProfile !== void 0) {
+		const profileName = options.profileScheme ?? "permdockFapi2";
+		schemes[profileName] = compact({
+			type: "profile",
+			profileMetadata: compact({
+				name: PROFILE_NAMES[options.securityProfile],
+				supportedParametersSchema: PROFILE_PARAMETERS[options.securityProfile],
+				servers: options.scheme.oauth2MetadataUrl === void 0 ? void 0 : [{
+					name: "default",
+					url: options.scheme.oauth2MetadataUrl
+				}]
+			}),
+			"x-permdock-securityProfile": options.securityProfile
+		});
+	}
+	return schemes;
+}
+function securityOf(policy, options, permissions, anyOf) {
+	assertScheme(options);
+	const name = options.scheme.name;
+	if (anyOf === true ? permissions.some((leaf) => isPublic(policy, leaf)) : permissions.length > 0 && permissions.every((leaf) => isPublic(policy, leaf))) return [];
+	if (anyOf === true) return permissions.map((leaf) => ({ [name]: [leaf.scope] }));
+	return [{ [name]: permissions.map((leaf) => leaf.scope) }];
+}
+function describeOf(policy, options, permissions, anyOf) {
+	const conditions = {};
+	const approvals = {};
+	for (const leaf of permissions) {
+		const grants = grantsOf(policy, [leaf]).filter((grant) => grant.effect === "allow");
+		const wheres = grants.filter((grant) => grant.portable).map((grant) => grant.where).filter((where) => where !== void 0);
+		const [only] = wheres;
+		if (only !== void 0) conditions[leaf.key] = wheres.length === 1 ? only : {
+			op: "or",
+			conditions: wheres
+		};
+		if (grants.some((grant) => requiresApproval(grant.approval))) approvals[leaf.key] = { reason: "human" };
+	}
+	const approval = Object.keys(approvals).length > 0;
+	return compact({
+		security: securityOf(policy, options, permissions, anyOf),
+		"x-permdock-permissions": permissions.map((leaf) => leaf.key),
+		"x-permdock-conditions": Object.keys(conditions).length > 0 ? conditions : void 0,
+		"x-permdock-approval": approval ? approvals : void 0,
+		"x-permdock-securityProfile": options.securityProfile,
+		"x-badges": options.docsHints?.badges === true && approval ? [{ name: "Approval required" }] : void 0
+	});
+}
+function catalogOf(options, extraDrafts) {
+	const target = options.target ?? "3.2";
+	const drafts = {};
+	if (target === "3.3") {
+		drafts["oas"] = DRAFT_PINS.oas;
+		drafts["securityProfiles"] = DRAFT_PINS.securityProfiles;
+	}
+	if (extraDrafts !== void 0) for (const [key, value] of Object.entries(extraDrafts)) drafts[key] = value;
+	return compact({
+		v: 1,
+		generator: "permdock/openapi",
+		drafts: Object.keys(drafts).length > 0 ? drafts : void 0
+	});
+}
+const GRANT_TYPES = {
+	authorizationCode: "authorization_code",
+	clientCredentials: "client_credentials",
+	deviceAuthorization: "urn:ietf:params:oauth:grant-type:device_code"
+};
+const FLOWS = [
+	"authorizationCode",
+	"clientCredentials",
+	"deviceAuthorization"
+];
+/** The client authentication methods FAPI 2.0 section 5.3.2.1 allows: sender-constrained, no shared secret. */
+const FAPI2_AUTH_METHODS = ["private_key_jwt", "tls_client_auth"];
+function pascal(value) {
+	return value.split(/[^A-Za-z0-9]+/u).filter((part) => part.length > 0).map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`).join("");
+}
+/**
+* One Security Profile Requirement per distinct scope set: `scopeSets` from
+* the operations, else one per permission.
+*/
+function securityProfileRequirementsOf(policy, options, scopeSets) {
+	if ((options.target ?? "3.2") !== "3.3" || options.securityProfile === void 0) return;
+	const profileName = options.profileScheme ?? "permdockFapi2";
+	const flows = options.scheme.flows ?? { authorizationCode: {} };
+	const grantTypes = FLOWS.filter((flow) => flows[flow] !== void 0).map((flow) => GRANT_TYPES[flow]);
+	const sets = scopeSets ?? listPermissions(policy.permissions).map((leaf) => [leaf.scope]);
+	const requirements = {};
+	for (const set of sets) {
+		const scopes = [...new Set(set)].toSorted();
+		if (scopes.length === 0) continue;
+		requirements[`${profileName}${pascal(scopes.join(" "))}`] = {
+			securityScheme: { $ref: `#/components/securitySchemes/${profileName}` },
+			token_endpoint_auth_methods: [...FAPI2_AUTH_METHODS],
+			grant_types: grantTypes,
+			scopes
+		};
+	}
+	return requirements;
+}
+function openapiVersion(target) {
+	switch (target) {
+		case "3.1": return "3.1.0";
+		case "3.2": return "3.2.0";
+		case "3.3": return "3.3.0";
+		default: return target;
+	}
+}
+//#endregion
+//#region src/openapi/overlay.ts
+function pointerEscape(value) {
+	return value.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+function actionKey(keys) {
+	return keys.toSorted().join(",");
+}
+/** An RFC 9535 single-quoted string literal. */
+function jsonPathString(value) {
+	return `'${value.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`;
+}
+function operationTarget(operationId) {
+	return `$.paths.*[?@.operationId == ${jsonPathString(operationId)}]`;
+}
+function hex(bytes) {
+	return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** `sha256:` over the sorted permission keys and scopes, so the same catalog gives the same Overlay. */
+function fingerprint(policy) {
+	const lines = listPermissions(policy.permissions).map((leaf) => `${leaf.key} ${leaf.scope}`).toSorted();
+	return `sha256:${hex(sha256(lines.join("\n")))}`;
+}
+function overlayOf(policy, options, overlayOptions = {}) {
+	const version = overlayOptions.version ?? "1.1";
+	const operations = (overlayOptions.operations ?? listPermissions(policy.permissions).map((leaf) => ({
+		operationId: leaf.key,
+		permissions: [leaf]
+	}))).toSorted((a, b) => a.operationId < b.operationId ? -1 : a.operationId > b.operationId ? 1 : 0);
+	const schemes = securitySchemesOf(policy, options);
+	const requirements = securityProfileRequirementsOf(policy, options, overlayOptions.operations?.map((operation) => operation.permissions.map((leaf) => leaf.scope)));
+	const catalogPin = fingerprint(policy);
+	const drafts = version === "1.2" ? { overlay: DRAFT_PINS.overlay } : void 0;
+	const info = {
+		title: "PermDock authorization metadata",
+		version: catalogPin
+	};
+	const head = [{
+		target: "$.components.securitySchemes",
+		description: "PermDock security schemes",
+		update: schemes
+	}];
+	if (requirements !== void 0) head.push({
+		target: "$.components.securityProfileRequirements",
+		description: "PermDock security profile requirements",
+		update: requirements
+	});
+	const catalogAction = {
+		target: "$",
+		description: "PermDock catalog pin",
+		update: { "x-permdock-catalog": catalogOf(options, drafts) }
+	};
+	const bodies = operations.map((operation) => {
+		const keys = operation.permissions.map((leaf) => leaf.key);
+		return {
+			operationId: operation.operationId,
+			key: actionKey(keys),
+			target: operationTarget(operation.operationId),
+			fields: describeOf(policy, options, operation.permissions)
+		};
+	});
+	if (version === "1.1") return compact({
+		overlay: "1.1.0",
+		info,
+		extends: overlayOptions.extends,
+		actions: [
+			...head,
+			...bodies.map((body) => ({
+				target: body.target,
+				description: body.key,
+				update: body.fields
+			})),
+			catalogAction
+		]
+	});
+	const reusable = {};
+	for (const body of bodies.toSorted((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0)) reusable[body.key] ??= {
+		description: body.key,
+		fields: { update: body.fields }
+	};
+	return compact({
+		overlay: "1.2.0",
+		info,
+		extends: overlayOptions.extends,
+		components: { actions: reusable },
+		actions: [
+			...head,
+			...bodies.map((body) => ({
+				$ref: `#/components/actions/${pointerEscape(body.key)}`,
+				target: body.target,
+				description: body.operationId
+			})),
+			catalogAction
+		]
+	});
+}
+//#endregion
+//#region src/openapi/create.ts
+function extendOperation(operation, extra) {
+	const result = {};
+	for (const [key, value] of Object.entries(operation)) result[key] = value;
+	for (const [key, value] of Object.entries(extra)) result[key] = value;
+	return result;
+}
+const createPermDock = (policy, options) => {
+	return {
+		securitySchemes() {
+			return securitySchemesOf(policy, options);
+		},
+		security(permission, extra) {
+			return securityOf(policy, options, asList(permission), extra?.anyOf);
+		},
+		describe(permission, extra) {
+			return describeOf(policy, options, asList(permission), extra?.anyOf);
+		},
+		spec(permission) {
+			return (operation) => extendOperation(operation, describeOf(policy, options, asList(permission)));
+		},
+		overlay(overlayOptions) {
+			return overlayOf(policy, options, overlayOptions ?? {});
+		},
+		securityProfileRequirements(scopeSets) {
+			return securityProfileRequirementsOf(policy, options, scopeSets);
+		},
+		catalog() {
+			return catalogOf(options);
+		}
+	};
+};
+//#endregion
+//#region src/openapi/operations.ts
+const METHODS = /* @__PURE__ */ new Set([
+	"GET",
+	"PUT",
+	"POST",
+	"DELETE",
+	"OPTIONS",
+	"HEAD",
+	"PATCH",
+	"TRACE",
+	"QUERY"
+]);
+function segmentsOf(path) {
+	return path.split("/").filter((segment) => segment !== "");
+}
+function isParam(segment) {
+	return segment.startsWith("{") && segment.endsWith("}");
+}
+/** The number of literal segments that match, or -1 when the template does not match. */
+function score(route, segments) {
+	if (route.segments.length !== segments.length) return -1;
+	let literal = 0;
+	for (const [index, segment] of route.segments.entries()) {
+		if (isParam(segment)) continue;
+		if (segment !== segments[index]) return -1;
+		literal += 1;
+	}
+	return literal;
+}
+function isEntryObject(entry) {
+	return !isPermission(entry);
+}
+function scopesOf(key, entry) {
+	if (!isEntryObject(entry) || entry.oauthScopes === void 0) return;
+	const scopes = entry.oauthScopes;
+	if (scopes.length === 0 || !scopes.every((scope) => typeof scope === "string" && scope !== "")) throw new TypeError(`PermDock: operation '${key}' sets oauthScopes, which must be a non-empty list of scope names`);
+	return Object.freeze([...entry.oauthScopes]);
+}
+/**
+* Operations as `"METHOD /path/{param}"` keys, the OpenAPI path template, to
+* a permission. `base` is a prefix requests carry and the keys do not
+* (`/api/v1`). A key that is not a method and a path throws.
+*/
+function operationPermissions(operations, options = {}) {
+	const routes = [];
+	const byId = /* @__PURE__ */ new Map();
+	for (const [key, entry] of Object.entries(operations)) {
+		const space = key.indexOf(" ");
+		const method = key.slice(0, space).toUpperCase();
+		const path = key.slice(space + 1).trim();
+		if (space <= 0 || !METHODS.has(method) || !path.startsWith("/")) throw new TypeError(`PermDock: operation '${key}' must be a method and a path, such as 'GET /customers/{id}'`);
+		const oauthScopes = scopesOf(key, entry);
+		if (isEntryObject(entry) && (entry.permission === void 0 ? oauthScopes === void 0 : !isPermission(entry.permission))) throw new TypeError(`PermDock: operation '${key}' needs a permission, oauthScopes or both`);
+		const route = {
+			method,
+			segments: segmentsOf(path),
+			permission: isEntryObject(entry) ? entry.permission : entry,
+			...oauthScopes === void 0 ? {} : { oauthScopes }
+		};
+		routes.push(route);
+		if (isEntryObject(entry) && entry.operationId !== void 0) byId.set(entry.operationId, route);
+	}
+	const base = segmentsOf(options.base ?? "");
+	const matchMethod = (upper, path) => {
+		const full = segmentsOf(path.split("?")[0] ?? "");
+		if (base.some((segment, index) => full[index] !== segment)) return;
+		const segments = full.slice(base.length);
+		let best;
+		let bestScore = -1;
+		for (const route of routes) {
+			if (route.method !== upper) continue;
+			const value = score(route, segments);
+			if (value > bestScore) {
+				best = route;
+				bestScore = value;
+			}
+		}
+		return best;
+	};
+	const match = (method, path) => {
+		const upper = method.toUpperCase();
+		const route = matchMethod(upper, path);
+		return route === void 0 && upper === "HEAD" ? matchMethod("GET", path) : route;
+	};
+	return {
+		forRequest(method, path) {
+			return match(method, path)?.permission;
+		},
+		forOperation(id) {
+			return byId.get(id)?.permission;
+		},
+		oauthScopesForRequest(method, path) {
+			return match(method, path)?.oauthScopes;
+		},
+		oauthScopesForOperation(id) {
+			return byId.get(id)?.oauthScopes;
+		}
+	};
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+* The operation permissions an OpenAPI document declares: every operation
+* whose `x-permdock-permissions` names exactly one permission of `tree`, keyed
+* by its method, path and `operationId`. An operation naming none, several or
+* an unknown key is left out, so a gate denies it.
+*/
+function operationPermissionsFromOpenApi(document, tree, options = {}) {
+	const operations = {};
+	const paths = isRecord(document) && isRecord(document["paths"]) ? document["paths"] : {};
+	for (const [path, item] of Object.entries(paths)) {
+		if (!isRecord(item)) continue;
+		for (const [method, operation] of Object.entries(item)) {
+			if (!METHODS.has(method.toUpperCase()) || !isRecord(operation)) continue;
+			const keys = operation["x-permdock-permissions"];
+			if (!Array.isArray(keys) || keys.length !== 1 || typeof keys[0] !== "string") continue;
+			const permission = findPermission(tree, keys[0]);
+			if (permission === void 0) continue;
+			const operationId = operation["operationId"];
+			operations[`${method.toUpperCase()} ${path}`] = typeof operationId === "string" ? {
+				permission,
+				operationId
+			} : permission;
+		}
+	}
+	return operationPermissions(operations, options);
+}
+//#endregion
+//#region src/openapi/problem-details.ts
+const TARGETS = /* @__PURE__ */ new Set([
+	"draft-2020-12",
+	"draft-07",
+	"openapi-3.0"
+]);
+const JSON_SCHEMA = Object.freeze({
+	type: "object",
+	description: "RFC 9457 Problem Details for a PermDock denial",
+	required: [
+		"type",
+		"title",
+		"status",
+		"detail"
+	],
+	properties: {
+		type: {
+			type: "string",
+			format: "uri-reference"
+		},
+		title: { type: "string" },
+		status: {
+			type: "integer",
+			minimum: 400,
+			maximum: 599
+		},
+		detail: { type: "string" },
+		instance: { type: "string" },
+		permission: { type: "string" },
+		scope: { type: "string" },
+		reason: { type: "string" }
+	},
+	additionalProperties: true
+});
+const REQUIRED_STRINGS = [
+	"type",
+	"title",
+	"detail"
+];
+function issuesOf(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return [{ message: "Expected a Problem Details object" }];
+	const issues = [];
+	const fields = new Map(Object.entries(value));
+	for (const key of REQUIRED_STRINGS) if (typeof fields.get(key) !== "string") issues.push({
+		message: `Expected a string`,
+		path: [key]
+	});
+	const status = fields.get("status");
+	if (typeof status !== "number" || !Number.isInteger(status) || status < 400 || status > 599) issues.push({
+		message: "Expected an HTTP error status",
+		path: ["status"]
+	});
+	return issues;
+}
+function isProblem(value) {
+	return issuesOf(value).length === 0;
+}
+function jsonSchema(options) {
+	if (!TARGETS.has(options.target)) throw new TypeError(`PermDock: problemDetails has no JSON Schema for target ${options.target}`);
+	return structuredClone(JSON_SCHEMA);
+}
+/**
+* The Problem Details body the adapters send on a denial, as a Standard
+* Schema with a JSON Schema, for `oc.errors({ FORBIDDEN: { data: problemDetails } })`.
+* Extension members pass through: RFC 9457 lets a problem type add them.
+*/
+const problemDetails = Object.freeze({ "~standard": Object.freeze({
+	version: 1,
+	vendor: "permdock",
+	validate: (value) => isProblem(value) ? { value } : { issues: issuesOf(value) },
+	jsonSchema: Object.freeze({
+		input: jsonSchema,
+		output: jsonSchema
+	})
+}) });
+//#endregion
+//#region src/openapi/security.ts
+function isList(permission) {
+	return Array.isArray(permission);
+}
+function listOf(permission) {
+	return isList(permission) ? permission : [permission];
+}
+/** The `x-permdock-permissions` value: the permission keys an operation enforces. */
+function permissionsExtension(permissions) {
+	return Object.freeze(listOf(permissions).map((leaf) => leaf.key));
+}
+/**
+* An operation's `security` and `x-permdock-permissions`, from permission
+* references alone. Needs no policy, so a contract package can import it.
+* Unlike `permdock openapi emit`, it never drops `security` for a public
+* permission: that needs the policy.
+*/
+function securityFor(permission, options = {}) {
+	const leaves = listOf(permission);
+	const scheme = options.scheme ?? "oauth2";
+	const security = options.anyOf === true && leaves.length > 0 ? leaves.map((leaf) => ({ [scheme]: [leaf.scope] })) : [{ [scheme]: leaves.map((leaf) => leaf.scope) }];
+	return Object.freeze({
+		security,
+		"x-permdock-permissions": permissionsExtension(leaves)
+	});
+}
+//#endregion
+export { operationPermissionsFromOpenApi as a, openapiVersion as c, operationPermissions as i, securitySchemesOf as l, securityFor as n, createPermDock as o, problemDetails as r, catalogOf as s, permissionsExtension as t };