permdock 0.0.0 → 0.1.0

package/dist/credentials-BgRX3WEg.js

@@ -0,0 +1,268 @@
+import { t as compact } from "./compact-y6vfu2_f.js";
+import { i as credentialTenant, n as credentialPolicyViolation, o as parseCredential, r as credentialSubject } from "./credential-B_rkUNlY.js";
+import { t as bytesToBase64Url } from "./sha256-BO0swRXL.js";
+import { n as isThenable } from "./thenable-okc2xDsj.js";
+import { t as anonymousSubject } from "./subject-C6dLxqHU.js";
+import { r as credentialEvent } from "./sink-Bd9PSyfq.js";
+//#region src/server/credentials.ts
+const PREFIX = "pdk_";
+const ID = /^[\w-]{1,128}$/u;
+const TAIL = /^[A-Za-z\d]{49}$/u;
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+const SECRET_LENGTH = 43;
+const CHECKSUM_LENGTH = 6;
+const MAX_KEY = 182;
+const CRC_TABLE = (() => {
+	const table = /* @__PURE__ */ new Uint32Array(256);
+	for (let index = 0; index < 256; index += 1) {
+		let value = index;
+		for (let bit = 0; bit < 8; bit += 1) value = value & 1 ? 3988292384 ^ value >>> 1 : value >>> 1;
+		table[index] = value >>> 0;
+	}
+	return table;
+})();
+/** CRC-32 (IEEE 802.3) of the key's ASCII bytes, as 6 base62 characters. */
+function checksum(text) {
+	let crc = 4294967295;
+	for (let index = 0; index < text.length; index += 1) crc = (CRC_TABLE[(crc ^ (text.codePointAt(index) ?? 0)) & 255] ?? 0) ^ crc >>> 8;
+	let value = (crc ^ 4294967295) >>> 0;
+	let out = "";
+	for (let index = 0; index < CHECKSUM_LENGTH; index += 1) {
+		out = (ALPHABET[value % 62] ?? "") + out;
+		value = Math.floor(value / 62);
+	}
+	return out;
+}
+/**
+* Splits `pdk_<id>_<secret><checksum>`: `id` is 1 to 128 of `A-Z a-z 0-9 _ -`,
+* the secret 43 base62 characters and the checksum the 6 base62 characters of
+* the CRC-32 of everything before it. Anything else, including a checksum
+* that does not match, is `undefined`.
+*/
+function parseApiKey(key) {
+	if (typeof key !== "string" || key.length > MAX_KEY || !key.startsWith(PREFIX)) return;
+	const body = key.slice(4);
+	const cut = body.lastIndexOf("_");
+	if (cut <= 0) return;
+	const id = body.slice(0, cut);
+	const tail = body.slice(cut + 1);
+	if (!ID.test(id) || !TAIL.test(tail)) return;
+	const secret = tail.slice(0, SECRET_LENGTH);
+	return tail.slice(SECRET_LENGTH) === checksum(`${PREFIX}${id}_${secret}`) ? {
+		id,
+		secret
+	} : void 0;
+}
+/**
+* A fresh `pdk_<id>_<secret><checksum>`: a 43-character base62 secret (about
+* 256 bits) and a 6-character CRC-32 checksum, so a secret scanner can tell a
+* real key from a lookalike without calling the issuer.
+*/
+function generateApiKey(id) {
+	if (!ID.test(id)) throw new TypeError("PermDock: an API key id is 1 to 128 of A-Z, a-z, 0-9, _ and -");
+	let secret = "";
+	const bytes = /* @__PURE__ */ new Uint8Array(64);
+	while (secret.length < SECRET_LENGTH) {
+		globalThis.crypto.getRandomValues(bytes);
+		for (const byte of bytes) if (byte < 248 && secret.length < SECRET_LENGTH) secret += ALPHABET[byte % 62];
+	}
+	const key = `${PREFIX}${id}_${secret}`;
+	return `${key}${checksum(key)}`;
+}
+/** base64url SHA-256 of the whole key, the value to store and compare. */
+async function hashApiKey(key) {
+	const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(key));
+	return bytesToBase64Url(new Uint8Array(digest));
+}
+function sameHash(left, right) {
+	if (left.length !== right.length) return false;
+	let difference = 0;
+	for (let index = 0; index < left.length; index += 1) difference |= (left.codePointAt(index) ?? 0) ^ (right.codePointAt(index) ?? 0);
+	return difference === 0;
+}
+/**
+* A `CredentialVerifier` over the application's own table: `find` looks a
+* key up by the id in it, and the key's hash is compared in constant time.
+* A record that is not a valid v1 credential, or whose id is not the key's,
+* verifies to `null`. A throwing `find` propagates, so the resolver denies
+* with `source-threw`.
+*/
+function apiKeyVerifier(options) {
+	return Object.freeze({
+		...options.touch === void 0 ? {} : { touch: options.touch },
+		async verify(secret) {
+			const parts = parseApiKey(secret);
+			if (parts === void 0) return null;
+			const stored = await options.find(parts.id);
+			if (stored === null || stored === void 0) return null;
+			const credential = parseCredential(stored.credential);
+			if (credential === void 0 || credential.id !== parts.id || typeof stored.hash !== "string" || !sameHash(await hashApiKey(secret), stored.hash)) return null;
+			return credential;
+		}
+	});
+}
+function write(sink, event) {
+	try {
+		const written = sink.write(event);
+		if (isThenable(written)) Promise.resolve(written).catch(() => void 0);
+	} catch {}
+}
+/**
+* In-process credentials for tests and single-replica apps. `issue`, `rotate`
+* and `revoke` write `credential` events to `sink` when one is given.
+*/
+function memoryCredentials(options = {}) {
+	const records = /* @__PURE__ */ new Map();
+	const used = /* @__PURE__ */ new Map();
+	const verifier = apiKeyVerifier({ find: (id) => records.get(id) });
+	const emit = (operation, credential) => {
+		if (options.sink !== void 0) write(options.sink, [credentialEvent(compact({
+			operation,
+			credential,
+			source: options.source
+		}))]);
+	};
+	const store = async (credential) => {
+		const key = generateApiKey(credential.id);
+		records.set(credential.id, {
+			credential,
+			hash: await hashApiKey(key)
+		});
+		return key;
+	};
+	return Object.freeze({
+		verify: (secret) => verifier.verify(secret),
+		touch(id, at) {
+			if (records.has(id)) used.set(id, at);
+		},
+		lastUsedAt(id) {
+			return used.get(id);
+		},
+		async issue(input) {
+			const credential = parseCredential(input);
+			if (credential === void 0) throw new TypeError("PermDock: not a valid v1 credential");
+			if (records.has(credential.id)) throw new Error(`PermDock: credential '${credential.id}' exists`);
+			const key = await store(credential);
+			emit("created", credential);
+			return key;
+		},
+		async rotate(id) {
+			const current = records.get(id);
+			if (current === void 0) return;
+			const key = await store(current.credential);
+			emit("rotated", current.credential);
+			return key;
+		},
+		revoke(id) {
+			const current = records.get(id);
+			if (current === void 0) return false;
+			records.delete(id);
+			used.delete(id);
+			emit("revoked", current.credential);
+			return true;
+		},
+		list() {
+			return [...records.values()].map((record) => record.credential);
+		}
+	});
+}
+async function checkStores(options, credential, active) {
+	try {
+		const tenant = credentialTenant(credential, active);
+		const policy = options.settings === void 0 || tenant === void 0 ? void 0 : (await options.settings.settingsFor(tenant))?.credentials;
+		if (policy !== void 0 && credentialPolicyViolation(credential, policy) !== void 0) return {
+			ok: false,
+			cause: "credential-policy"
+		};
+		if (options.revoked !== void 0 && await options.revoked(credential.id)) return {
+			ok: false,
+			cause: "credential-revoked"
+		};
+		if (credential.kind !== "user" || options.owner === void 0) return { ok: true };
+		const owner = await options.owner(credential.principal);
+		if (owner === null || owner === void 0) return {
+			ok: false,
+			cause: "owner-unavailable"
+		};
+		return {
+			ok: true,
+			owner
+		};
+	} catch {
+		return { ok: false };
+	}
+}
+function touch(verifier, id) {
+	if (verifier.touch === void 0) return;
+	try {
+		const touched = verifier.touch(id, Math.floor(Date.now() / 1e3));
+		if (isThenable(touched)) Promise.resolve(touched).catch(() => void 0);
+	} catch {}
+}
+function sampled(sample) {
+	if (sample === 1) return true;
+	const draw = /* @__PURE__ */ new Uint32Array(1);
+	globalThis.crypto.getRandomValues(draw);
+	return (draw[0] ?? 0) / 4294967296 < sample;
+}
+function reportUse(options, credential) {
+	const sample = options.sample ?? 1;
+	if (options.sink === void 0 || !Number.isFinite(sample) || sample <= 0 || sample > 1 || !sampled(sample)) return;
+	write(options.sink, [credentialEvent(compact({
+		operation: "used",
+		credential,
+		source: options.source,
+		sample
+	}))]);
+}
+/**
+* A `SubjectResolver` for opaque API keys (`pdk_<id>_<secret>`): each call
+* resolves a key into the subject its credential acts as. Every failure (a
+* malformed or unknown key, a record that is not a valid credential, expiry,
+* a tenant policy the key breaks, a revoked id, a missing owner, a throwing
+* verifier or callback) is the anonymous subject, never a throw.
+*/
+function subjectFromApiKey(options) {
+	return (key, resolve) => resolveApiKey(key, options, resolve?.tenant);
+}
+function anonymous() {
+	return anonymousSubject();
+}
+async function resolveApiKey(key, options, tenant) {
+	if (typeof key !== "string" || key.length === 0) return anonymous();
+	const deny = (cause, reason = "invalid-token") => {
+		try {
+			options.onAuth?.(compact({
+				reason,
+				cause,
+				source: "api-key",
+				requestId: options.requestId
+			}));
+		} catch {}
+		return anonymous();
+	};
+	const parts = parseApiKey(key);
+	if (parts === void 0) return deny("malformed");
+	let verified;
+	try {
+		verified = await options.verifier.verify(key);
+	} catch {
+		return deny(void 0, "source-threw");
+	}
+	if (verified === null || verified === void 0) return deny("unknown-credential");
+	const credential = parseCredential(verified);
+	if (credential === void 0 || credential.id !== parts.id) return deny("invalid-claims");
+	if (credential.expiresAt !== void 0 && credential.expiresAt <= Date.now() / 1e3) return deny("expired");
+	const checked = await checkStores(options, credential, tenant);
+	if (!checked.ok) return checked.cause === void 0 ? deny(void 0, "source-threw") : deny(checked.cause);
+	const subject = credentialSubject(credential, compact({
+		permissions: options.permissions,
+		owner: checked.owner
+	}));
+	if (subject.principal === null) return deny("owner-unavailable");
+	reportUse(options, credential);
+	touch(options.verifier, credential.id);
+	return subject;
+}
+//#endregion
+export { parseApiKey as a, memoryCredentials as i, generateApiKey as n, subjectFromApiKey as o, hashApiKey as r, apiKeyVerifier as t };

package/dist/describe-Bt1YD5uS.js

@@ -0,0 +1,99 @@
+import { t as flattenApprovers } from "./approvers-aH0PJkmf.js";
+import { s as flattenGrantee } from "./grantee-Bv04_Vzf.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 "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;
+	}
+}
+/**
+* The plans named by the `not-entitled` denials of a decision, when every
+* denial is `not-entitled`; otherwise empty, since a plan alone would not grant.
+*/
+function requiredPlans(decision) {
+	if (decision.outcome !== "denied" || decision.denials.length === 0 || decision.denials.some((denial) => denial.reason !== "not-entitled")) return [];
+	const plans = /* @__PURE__ */ new Set();
+	for (const denial of decision.denials) for (const item of flattenGrantee(denial.to)) if (item.kind === "plan") plans.add(item.plan);
+	return [...plans];
+}
+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) {
+	return approver.kind === "user" ? `user ${approver.id}` : 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 detail = reasons.map((reason) => messages?.reasons?.[reason] ?? reason).join(messages?.separator ?? ", ");
+	return {
+		kind,
+		title: titleOf(kind),
+		detail,
+		alternatives: decision.alternatives
+	};
+}
+//#endregion
+export { requiredPlans as n, describe as t };

package/dist/describe-DernyItf.d.ts

@@ -0,0 +1,37 @@
+import { Mn as Decision, Pn as DenialReason } from "./policy-CInmNGkM.js";
+import { d as Permission } from "./permissions-B4apnahQ.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[];
+};
+/**
+ * The plans named by the `not-entitled` denials of a decision, when every
+ * denial is `not-entitled`; otherwise empty, since a plan alone would not grant.
+ */
+declare function requiredPlans(decision: Decision): 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`. */
+  readonly reasons?: Partial<Record<DenialReason, string>>;
+  /** 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 { requiredPlans as a, describe as i, DescribeMessages as n, DescribeOptions as r, DecisionDescription as t };

package/dist/diff-BUzf5Poi.js

@@ -0,0 +1,48 @@
+import { i as globalArgs, s as stringArg, t as COMMAND_DESCRIPTIONS } from "./commands-BMh_Etm2.js";
+import { defineCommand } from "citty";
+//#region src/cli/commands/diff.ts
+function diff(ctx) {
+	return defineCommand({
+		meta: {
+			name: "diff",
+			description: COMMAND_DESCRIPTIONS.diff
+		},
+		args: {
+			...globalArgs,
+			before: {
+				type: "positional",
+				required: false,
+				description: "A permissions.catalog.json or a module exporting policy"
+			},
+			after: {
+				type: "positional",
+				required: false,
+				description: "The same, for the new side"
+			},
+			impact: {
+				type: "boolean",
+				description: "Run the fixtures through both sides and report changed outcomes"
+			},
+			fixtures: {
+				type: "string",
+				description: "Fixtures file for --impact",
+				valueHint: "file"
+			}
+		},
+		async run({ args: parsed }) {
+			const result = await (await import("./diff-x5Il8LVa.js")).runDiff({
+				cwd: ctx.cwd,
+				config: ctx.config,
+				sources: parsed._,
+				impact: parsed.impact === true,
+				fixtures: stringArg(parsed.fixtures),
+				json: ctx.json,
+				now: ctx.now,
+				io: ctx.io
+			});
+			ctx.report(result);
+		}
+	});
+}
+//#endregion
+export { diff };