permdock 0.0.0 → 0.2.0

package/dist/credential-8P81ff4u.js

@@ -0,0 +1,306 @@
+import { n as isReadonlyArray, t as compact } from "./compact-y6vfu2_f.js";
+import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
+import { _ as listPermissions, a as formerKeys } from "./permissions-DVoF6dMt.js";
+import { n as sha256, t as bytesToBase64Url } from "./sha256-BO0swRXL.js";
+import { t as coveredByDelegation } from "./delegation-D8pUEuce.js";
+import { t as anonymousSubject } from "./subject-C6dLxqHU.js";
+import { a as ownRecord, n as idList, r as isId } from "./capability-4qPdO9gk.js";
+//#region src/core/credential.ts
+const MAX_NAME = 256;
+function policies(policy) {
+	return isReadonlyArray(policy) ? policy : [policy];
+}
+/**
+* The first rule of `policy` the credential breaks, or `undefined`. A key
+* without `expiresAt` passes only when some policy sets `allowNoExpiry` and
+* none sets `maxTtl`; an empty list therefore refuses it.
+*/
+function credentialPolicyViolation(credential, policy) {
+	const list = policies(policy);
+	for (const item of list) if (item.kinds !== void 0 && !item.kinds.includes(credential.kind)) return "kind";
+	if (credential.expiresAt === void 0) return list.some((item) => item.allowNoExpiry === true) && list.every((item) => item.maxTtl === void 0) ? void 0 : "no-expiry";
+	for (const item of list) {
+		const max = item.maxTtl;
+		if (max !== void 0 && (typeof max !== "number" || !Number.isFinite(max) || max < 0 || credential.expiresAt - credential.createdAt > max)) return "ttl";
+	}
+}
+function parsePermissions(value) {
+	if (!Array.isArray(value) || value.length === 0) return;
+	const out = [];
+	for (const item of value) {
+		const entry = ownRecord(item);
+		if (entry === void 0 || !isId(entry["permission"])) return;
+		const ids = entry["ids"] === void 0 ? void 0 : idList(entry["ids"]);
+		if (entry["ids"] !== void 0 && ids === void 0) return;
+		out.push(compact({
+			permission: entry["permission"],
+			ids
+		}));
+	}
+	return out;
+}
+function isTime(value) {
+	return typeof value === "number" && Number.isFinite(value);
+}
+/**
+* Validates an untrusted credential record and returns a frozen copy with
+* only the v1 fields, or `undefined`. Unknown fields are dropped; a wrong
+* type in a known field, a service credential without `tenant` and `roles`,
+* or a user credential with `roles`, rejects the whole record.
+*/
+function parseCredential(input) {
+	const value = ownRecord(input);
+	if (value === void 0 || value["v"] !== 1 || !isId(value["id"])) return;
+	if (value["kind"] !== "user" && value["kind"] !== "service") return;
+	if (!isId(value["principal"]) || !isId(value["createdBy"])) return;
+	const permissions = parsePermissions(value["permissions"]);
+	if (permissions === void 0 || !isTime(value["createdAt"])) return;
+	if (value["expiresAt"] !== void 0 && !isTime(value["expiresAt"])) return;
+	if (value["name"] !== void 0 && (typeof value["name"] !== "string" || value["name"].length > MAX_NAME)) return;
+	let tenant;
+	let roles;
+	if (value["kind"] === "service") {
+		roles = idList(value["roles"]);
+		if (!isId(value["tenant"]) || roles === void 0) return;
+		tenant = value["tenant"];
+	} else if (value["roles"] !== void 0 || value["tenant"] !== void 0 && !isId(value["tenant"])) return;
+	else tenant = value["tenant"];
+	return freezeDeep(compact({
+		v: 1,
+		id: value["id"],
+		kind: value["kind"],
+		principal: value["principal"],
+		tenant,
+		roles,
+		permissions,
+		createdBy: value["createdBy"],
+		createdAt: value["createdAt"],
+		expiresAt: value["expiresAt"],
+		name: value["name"]
+	}));
+}
+function leafByKey(tree) {
+	const byKey = /* @__PURE__ */ new Map();
+	for (const leaf of listPermissions(tree)) {
+		byKey.set(leaf.key, leaf);
+		for (const old of formerKeys(leaf)) byKey.set(old, leaf);
+	}
+	return byKey;
+}
+/**
+* The delegation a credential narrows its principal to: OAuth scopes for
+* permissions on every instance, one RFC 9396 entry per id otherwise. A key
+* the definitions no longer declare is dropped, so a credential whose every
+* key is gone delegates nothing and every check is denied.
+*/
+function credentialDelegation(credential, permissions) {
+	const leaves = leafByKey(permissions);
+	const scopes = [];
+	const details = [];
+	for (const entry of credential.permissions) {
+		const leaf = leaves.get(entry.permission);
+		if (leaf === void 0) continue;
+		if (entry.ids === void 0) {
+			scopes.push(leaf.scope);
+			continue;
+		}
+		for (const id of entry.ids) details.push({
+			type: leaf.resource,
+			actions: [leaf.action],
+			identifier: id
+		});
+	}
+	return compact({
+		scopes: scopes.length > 0 || details.length === 0 ? scopes : void 0,
+		authorizationDetails: details.length > 0 ? details : void 0
+	});
+}
+/**
+* The subject a verified credential acts as. A `user` credential is its
+* owner, passed live as `owner` (roles and memberships as of this request),
+* with the credential's delegation: every check is the owner's rights
+* intersected with the key's. One that names a `tenant` makes it the active
+* tenant, and `createPermDock` then keeps only the owner's memberships
+* inside it and no global role. A `service` credential is a `service`
+* principal whose only membership is `roles` in `tenant`. An owner whose id
+* is not the credential's `principal`, or who is not a user, is anonymous.
+*/
+function credentialSubject(credential, options) {
+	const delegation = credentialDelegation(credential, options.permissions);
+	let principal;
+	if (credential.kind === "user") {
+		const owner = options.owner ?? {
+			id: credential.principal,
+			kind: "user"
+		};
+		if (owner.id !== credential.principal || owner.kind !== void 0 && owner.kind !== "user") return anonymousSubject();
+		principal = compact({
+			...owner,
+			kind: "user",
+			tenant: credential.tenant ?? owner.tenant,
+			credential
+		});
+	} else {
+		const membership = compact({
+			tenant: credential.tenant,
+			roles: credential.roles ?? [],
+			via: "credential"
+		});
+		principal = compact({
+			id: credential.principal,
+			kind: "service",
+			tenant: credential.tenant,
+			memberships: [membership],
+			credential
+		});
+	}
+	return freezeDeep(compact({
+		principal,
+		delegation,
+		context: {},
+		expiresAt: credential.expiresAt
+	}));
+}
+function credentialToken(credential) {
+	const payload = JSON.stringify({
+		t: "credential",
+		id: credential.id,
+		kind: credential.kind,
+		principal: credential.principal,
+		tenant: credential.tenant ?? null,
+		roles: credential.roles ?? null,
+		permissions: credential.permissions,
+		createdBy: credential.createdBy,
+		expiresAt: credential.expiresAt ?? null,
+		name: credential.name ?? null
+	});
+	return `pd1.${bytesToBase64Url(sha256(payload))}`;
+}
+function denied(reason, detail) {
+	return freezeDeep({
+		outcome: "denied",
+		denials: [compact({
+			role: null,
+			reason,
+			detail
+		})]
+	});
+}
+function permissionEntries(request, declared) {
+	if (!isReadonlyArray(request.permissions) || request.permissions.length === 0) return;
+	const out = [];
+	for (const item of request.permissions) {
+		const entry = permissionEntry(item);
+		if (entry === void 0 || declared.get(entry.leaf.key) === void 0) return;
+		out.push(entry);
+	}
+	return out;
+}
+function permissionEntry(item) {
+	if (!isScopedInput(item)) return { leaf: item };
+	const ids = idList(item.ids);
+	return ids === void 0 ? void 0 : {
+		leaf: item.permission,
+		ids
+	};
+}
+function isScopedInput(item) {
+	return "permission" in item && "ids" in item;
+}
+function refuse(reason, detail) {
+	return {
+		ok: false,
+		decision: denied(reason, detail)
+	};
+}
+function checkRequest(permdock, request, now) {
+	const creator = permdock.subject.principal;
+	if (creator === null) return refuse("anonymous");
+	if (creator.kind === "link" || "credential" in creator) return refuse("exceeds-creator", { creator: creator.kind === "link" ? "link" : "credential" });
+	const entries = permissionEntries(request, leafByKey(permdock.permissions));
+	if (entries === void 0 || !isId(request.id) || request.expiresAt !== void 0 && (!isTime(request.expiresAt) || request.expiresAt <= now)) return refuse("validation");
+	const subject = permdock.subject;
+	for (const entry of entries) for (const id of entry.ids ?? [void 0]) if (coveredByDelegation(entry.leaf, subject.delegation, id, subject.actor !== void 0) !== void 0) return refuse("exceeds-creator", { permission: entry.leaf.key });
+	const credential = parseCredential(compact({
+		v: 1,
+		id: request.id,
+		kind: request.kind,
+		principal: request.kind === "service" ? request.principal ?? request.id : creator.id,
+		tenant: request.tenant,
+		roles: request.kind === "service" ? request.roles : void 0,
+		permissions: entries.map((entry) => compact({
+			permission: entry.leaf.key,
+			ids: entry.ids
+		})),
+		createdBy: creator.id,
+		createdAt: now,
+		expiresAt: request.expiresAt === void 0 ? void 0 : Math.floor(request.expiresAt),
+		name: request.name
+	}));
+	if (credential === void 0) return refuse("validation");
+	if (credential.tenant !== void 0) {
+		const tenant = credential.tenant;
+		if (!permdock.tenants().includes(tenant)) return refuse("exceeds-creator", { tenant });
+	}
+	if (credential.kind === "service" && credential.tenant !== void 0) {
+		const tenant = credential.tenant;
+		const roles = new Set(permdock.assignableRoles({ tenant }).map((role) => role.key));
+		for (const name of credential.roles ?? []) if (!roles.has(name)) return refuse("exceeds-creator", { role: name });
+		const ceiling = new Set(permdock.assignablePermissions({ tenant }).map((leaf) => leaf.key));
+		for (const entry of credential.permissions) if (!ceiling.has(entry.permission)) return refuse("exceeds-creator", { permission: entry.permission });
+	}
+	return {
+		ok: true,
+		credential
+	};
+}
+/**
+* The tenant whose `credentials` policy governs a credential: the key's own
+* tenant, otherwise `active` (the creator's or the request's).
+*/
+function credentialTenant(credential, active) {
+	return credential.tenant ?? active;
+}
+/**
+* Decides whether the subject of `permdock` may create the credential in
+* `request`. The creator must be a signed-in user or service that is not
+* itself a link or a credential; a delegated creator hands out only what its
+* delegation covers. A key's tenant must be one the creator is a member of;
+* a service key's roles among the creator's `assignableRoles` there and its
+* permissions within `assignablePermissions` there (`exceeds-creator`). The
+* `credentials` policy of the key's tenant (its own, or for a user key
+* without one the creator's active tenant) then applies (`credential-policy`; a
+* settings source that throws denies with `rule: 'unavailable'`), and
+* `approval` makes the result `approval-required` until `approved` carries
+* its token. PermDock never stores the credential; the application does,
+* after a `granted` result.
+*/
+async function decideCredential(permdock, request, options = {}) {
+	const checked = checkRequest(permdock, request, options.now ?? Math.floor(Date.now() / 1e3));
+	if (!checked.ok) return checked.decision;
+	const { credential } = checked;
+	const tenant = credentialTenant(credential, permdock.subject.principal?.tenant);
+	let policy;
+	if (options.settings !== void 0 && tenant !== void 0) try {
+		policy = (await options.settings.settingsFor(tenant))?.credentials;
+	} catch {
+		return denied("credential-policy", { rule: "unavailable" });
+	}
+	const list = policy === void 0 ? [] : [policy];
+	const violation = credentialPolicyViolation(credential, list);
+	if (violation !== void 0) return denied("credential-policy", { rule: violation });
+	if (list.some((item) => item.approval === true)) {
+		const token = credentialToken(credential);
+		if (options.approved !== token) return freezeDeep({
+			outcome: "approval-required",
+			credential,
+			token
+		});
+	}
+	return freezeDeep({
+		outcome: "granted",
+		credential
+	});
+}
+//#endregion
+export { decideCredential as a, credentialTenant as i, credentialPolicyViolation as n, parseCredential as o, credentialSubject as r, credentialDelegation as t };

package/dist/delegation-D8pUEuce.js

@@ -0,0 +1,103 @@
+import { i as findPermission, o as formerScopes, t as annotationsFor } from "./permissions-DVoF6dMt.js";
+import { d as matchGrantee, s as flattenGrantee } from "./grantee-Cv5Sogfv.js";
+import { t as isActive } from "./validity-uOp8UpYn.js";
+//#region src/core/delegation.ts
+/** The permission's scope and any scope it was renamed from: tokens issued before a rename keep working. */
+function scopeNames(permission) {
+	return [permission.scope, ...formerScopes(permission)];
+}
+/**
+* Whether a delegated caller may use a permission its principal holds, through
+* OAuth `scopes`, RFC 9396 `authorizationDetails` or GNAP `access`.
+* `undefined` means covered; otherwise the denial reason `decide` would add.
+*/
+function coveredByDelegation(permission, delegation, resourceId, hasActor = false) {
+	const unscoped = hasActor ? "no-delegation" : void 0;
+	if (delegation === void 0) return unscoped;
+	const hasScopes = delegation.scopes !== void 0;
+	const hasDetails = delegation.authorizationDetails !== void 0;
+	const hasAccess = delegation.access !== void 0;
+	if (!hasScopes && !hasDetails && !hasAccess) return unscoped;
+	const emptyScopes = hasScopes && (delegation.scopes?.length ?? 0) === 0;
+	const emptyAccess = hasAccess && (delegation.access?.length ?? 0) === 0;
+	if (emptyScopes && !hasDetails && !hasAccess) return "no-delegation";
+	if (emptyAccess && !hasScopes && !hasDetails) return "no-delegation";
+	if (emptyScopes && emptyAccess && !hasDetails) return "no-delegation";
+	const scopes = scopeNames(permission);
+	const scopeOk = delegation.scopes?.some((scope) => scopes.includes(scope)) ?? false;
+	const detailOk = delegation.authorizationDetails?.some((detail) => {
+		if (detail.type !== permission.resource) return false;
+		const identifier = detail["identifier"];
+		if (identifier !== void 0 && (typeof identifier !== "string" || identifier !== resourceId)) return false;
+		const actions = detail.actions;
+		if (actions === void 0) return true;
+		return Array.isArray(actions) && actions.includes(permission.action);
+	}) ?? false;
+	const accessOk = accessCovers(permission, delegation.access, resourceId);
+	if (scopeOk || detailOk || accessOk) return;
+	return "not-delegated";
+}
+function coversRequirements(tree, requires, delegation, resourceId, hasActor = false) {
+	return (requires ?? []).every((key) => {
+		const leaf = findPermission(tree, key);
+		return leaf !== void 0 && coveredByDelegation(leaf, delegation, resourceId, hasActor) === void 0;
+	});
+}
+function requiresStandIn(grant) {
+	return (grant.requires ?? []).length > 0 && annotationsFor(grant.permission).readOnlyHint && !flattenGrantee(grant.to).some((item) => item.kind === "role");
+}
+function accessCovers(permission, access, resourceId) {
+	if (access === void 0) return false;
+	return access.some((entry) => {
+		if (typeof entry === "string") return scopeNames(permission).includes(entry);
+		if (entry === null || typeof entry !== "object") return false;
+		const type = entry["type"];
+		if (typeof type !== "string" || !typeMatches(type, permission.resource)) return false;
+		const actions = entry["actions"];
+		if (actions !== void 0 && (!Array.isArray(actions) || !actions.includes(permission.action))) return false;
+		const identifier = entry["identifier"];
+		if (identifier !== void 0 && (typeof identifier !== "string" || identifier !== resourceId)) return false;
+		return true;
+	});
+}
+function typeMatches(type, resource) {
+	if (type === resource) return true;
+	return type.endsWith(`/${resource}`);
+}
+/**
+* Whether the subject's principal is a `from` of the delegation: every item
+* matches, with roles checked against the roles the principal holds here
+* (`matchGrantee` leaves role holding to the caller) and nothing that needs a
+* row.
+*/
+function handsOver(delegation, subject, heldRoles, now) {
+	const items = flattenGrantee(delegation.from);
+	if (items.length === 0 || subject.principal === null) return false;
+	return items.every((item) => {
+		if (item.kind === "role") return heldRoles.has(item.role);
+		if (item.kind === "relation") return false;
+		const match = matchGrantee(item, subject, now, void 0);
+		return match.matched && match.where === void 0;
+	});
+}
+/**
+* The permission keys the policy's delegations let `subject.actor` use for
+* `subject.principal` right now: the union over every active delegation whose
+* `to` matches the actor and whose `from` the principal holds. `undefined`
+* when none applies, so the call falls back to the token delegation alone.
+* An actor with `readOnly: true` gets only each delegation's read-only keys.
+* Attenuation only: a key here still needs a matching allow and no deny.
+*/
+function delegatedPermissions(delegations, subject, heldRoles, now) {
+	const actor = subject.actor;
+	if (actor === void 0 || delegations === void 0) return;
+	let keys;
+	for (const delegation of delegations) {
+		if (delegation.to.kind !== actor.kind || delegation.to.id !== void 0 && delegation.to.id !== actor.id || delegation.to.client !== void 0 && delegation.to.client !== actor.client || !isActive(delegation.validity, now) || !handsOver(delegation, subject, heldRoles, now)) continue;
+		keys ??= /* @__PURE__ */ new Set();
+		for (const key of actor.readOnly === true ? delegation.readOnly : delegation.permissions) keys.add(key);
+	}
+	return keys;
+}
+//#endregion
+export { requiresStandIn as i, coversRequirements as n, delegatedPermissions as r, coveredByDelegation as t };

package/dist/describe-B_gVZEVi.js

@@ -0,0 +1,94 @@
+import { i as flattenApprovers } from "./approvers-DT4AVyIg.js";
+import { r as requiredPlans } from "./problem-details-_AMOYz-w.js";
+//#region src/core/describe.ts
+const TENANT_REASONS = /* @__PURE__ */ new Set([
+	"tenant-mismatch",
+	"no-membership",
+	"expired-membership",
+	"scope"
+]);
+const DELEGATION_REASONS = /* @__PURE__ */ new Set(["not-delegated", "no-delegation"]);
+function labelGrantee(grantee) {
+	switch (grantee.kind) {
+		case "role": return grantee.role;
+		case "plan": return grantee.plan;
+		case "actor": return grantee.actor;
+		case "authenticated": return "an authenticated user";
+		case "anyone": return "anyone";
+		case "relation": return grantee.relation;
+		case "inherit": return grantee.permission;
+		case "assurance": {
+			const parts = [];
+			if (grantee.acr !== void 0 && grantee.acr.length > 0) parts.push(`acr ${grantee.acr.join("/")}`);
+			if (grantee.amr !== void 0 && grantee.amr.length > 0) parts.push(`amr ${grantee.amr.join("/")}`);
+			return parts.length > 0 ? parts.join(" ") : "step-up";
+		}
+		default: return grantee;
+	}
+}
+const TITLES = {
+	granted: "Granted",
+	denied: "Denied",
+	approval: "Approval required",
+	tenant: "Wrong tenant",
+	delegation: "Not delegated",
+	"server-only": "Server only",
+	upgrade: "Upgrade required"
+};
+function labelApprover(approver) {
+	if (approver.kind === "user") return `user ${approver.id}`;
+	if (approver.kind === "permission") return `a holder of ${approver.permission}`;
+	if (approver.kind === "any-of") return `one of (${approver.of.map((entry) => flattenApprovers(entry).map(labelApprover).join(" and ")).join(", ")})`;
+	return labelGrantee(approver);
+}
+function approvers(approval) {
+	if (approval === void 0 || approval === "human") return [];
+	return [...flattenApprovers(approval.by), ...(approval.stages ?? []).flatMap((stage) => flattenApprovers(stage.by))].map(labelApprover);
+}
+function approvalDetail(permission, labels) {
+	if (labels.length === 0) return `${permission} requires human approval.`;
+	return `${permission} requires approval from ${labels.join(" and ")}.`;
+}
+function describe(decision, options) {
+	const messages = options?.messages;
+	const titleOf = (kind) => messages?.titles?.[kind] ?? TITLES[kind];
+	if (decision.outcome === "granted") {
+		const { permission } = decision.matched;
+		return {
+			kind: "granted",
+			title: titleOf("granted"),
+			detail: messages?.granted?.(permission) ?? `${permission} granted.`,
+			alternatives: []
+		};
+	}
+	if (decision.outcome === "approval-required") {
+		const { permission } = decision.grant;
+		const labels = approvers(decision.grant.approval);
+		return {
+			kind: "approval",
+			title: titleOf("approval"),
+			detail: messages?.approval?.(permission, labels) ?? approvalDetail(permission, labels),
+			alternatives: []
+		};
+	}
+	const plans = requiredPlans(decision);
+	if (plans.length > 0) return {
+		kind: "upgrade",
+		title: titleOf("upgrade"),
+		detail: messages?.upgrade?.(plans) ?? `${plans.join(" or ")} plan required.`,
+		alternatives: decision.alternatives,
+		plans
+	};
+	const reasons = decision.denials.map((denial) => denial.reason);
+	const kind = reasons.some((reason) => TENANT_REASONS.has(reason)) ? "tenant" : reasons.some((reason) => DELEGATION_REASONS.has(reason)) ? "delegation" : reasons.includes("opaque-condition") || reasons.includes("server-only") ? "server-only" : "denied";
+	const texts = messages?.reasons;
+	const detail = reasons.map((reason) => (typeof texts === "function" ? texts(reason, decision) : texts?.[reason]) ?? reason).join(messages?.separator ?? ", ");
+	return {
+		kind,
+		title: titleOf(kind),
+		detail,
+		alternatives: decision.alternatives
+	};
+}
+//#endregion
+export { describe as t };

package/dist/describe-PdoqESvg.d.ts

@@ -0,0 +1,36 @@
+import { Qn as DeniedDecision, Yn as Decision, Zn as DenialReason } from "./policy-CFZAr_Al.js";
+import { f as Permission } from "./permissions-DttnqqxC.js";
+//#region src/core/describe.d.ts
+type DecisionDescription = {
+  readonly kind: "granted" | "denied" | "approval" | "tenant" | "delegation" | "server-only" | "upgrade";
+  readonly title: string;
+  readonly detail: string;
+  readonly alternatives: readonly Permission[];
+  /** On `upgrade`: the plans any of which would grant the permission. */
+  readonly plans?: readonly string[];
+};
+/**
+ * Localised text for `describe`. Every entry is optional and falls back to the
+ * English default; `kind` and `alternatives` never change.
+ */
+type DescribeMessages = {
+  readonly titles?: Partial<Record<DecisionDescription["kind"], string>>;
+  /**
+   * Text per denial reason; a denied detail joins the texts of its reasons
+   * with `separator`. The function form also sees the decision; `undefined`
+   * keeps the reason code, as a missing record entry does.
+   */
+  readonly reasons?: Partial<Record<DenialReason, string>> | ((reason: DenialReason, decision: DeniedDecision) => string | undefined);
+  /** Joins denial reason texts. Default `', '`. */
+  readonly separator?: string;
+  readonly granted?: (permission: string) => string;
+  /** `approvers` is empty for `'human'` approval. */
+  readonly approval?: (permission: string, approvers: readonly string[]) => string;
+  readonly upgrade?: (plans: readonly string[]) => string;
+};
+type DescribeOptions = {
+  readonly messages?: DescribeMessages;
+};
+declare function describe(decision: Decision, options?: DescribeOptions): DecisionDescription;
+//#endregion
+export { describe as i, DescribeMessages as n, DescribeOptions as r, DecisionDescription as t };