permdock 0.0.0 → 0.1.0

package/dist/openapi-DcqM8nU7.js

@@ -0,0 +1,306 @@
+import { t as compact } from "./compact-y6vfu2_f.js";
+import { f as isPermission, g as listPermissions } from "./permissions-DC7GROPA.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-CqE1jZuF.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(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(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
+export { securitySchemesOf as i, catalogOf as n, openapiVersion as r, createPermDock as t };