permdock 0.3.1 → 0.5.0

package/dist/server-DqCT4CgZ.js

@@ -0,0 +1,453 @@
+import { t as compact } from "./compact-CAf557ZB.js";
+import { a as ownRecord } from "./paths-DXSHAMIa.js";
+import { m as annotationsFor, n as findPermission } from "./permission-registry-Br4jSNVi.js";
+import { n as isThenable } from "./thenable-yD7SabqG.js";
+import { f as nowMillis, g as secondsOf, m as rfc3339, o as epochSeconds, u as isoAt } from "./time-DkWjdL98.js";
+import { t as bytesToBase64Url } from "./sha256-D9ihqmvd.js";
+import { n as parseSupportSession } from "./support-session-C6xJQYut.js";
+import { t as anonymousSubject } from "./subject-BGoM5o8B.js";
+import { c as credentialEvent } from "./sink-BEZSlMS_.js";
+import { i as credentialTenant, n as credentialPolicyViolation, o as isFeedId, r as credentialSubject, s as parseCredential } from "./credential-DM2um3ha.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 characters of `alphabet`. */
+function checksum(text, alphabet) {
+	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 = "";
+	const base = alphabet.length;
+	for (let index = 0; index < CHECKSUM_LENGTH; index += 1) {
+		out = (alphabet[value % base] ?? "") + out;
+		value = Math.floor(value / base);
+	}
+	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}`, ALPHABET) ? {
+		id,
+		secret
+	} : void 0;
+}
+const FEED_PREFIX = "pdfeed_";
+const FEED_ALPHABET = "abcdefghijklmnopqrstuvwxyz234567";
+const FEED_SECRET_LENGTH = 26;
+const FEED_TAIL = /* @__PURE__ */ new RegExp(`^[a-z2-7]{${String(32)}}$`, "u");
+/**
+* Splits `pdfeed_<id>_<secret><checksum>`. `id` is `isFeedId`, the secret is
+* 26 lowercase base32 characters and the checksum is 6 more. A checksum that
+* does not match is `undefined`.
+*/
+function parseFeedKey(key) {
+	if (typeof key !== "string" || key.length > 56 || !key.startsWith(FEED_PREFIX)) return;
+	const body = key.slice(7);
+	const cut = body.lastIndexOf("_");
+	if (cut <= 0) return;
+	const id = body.slice(0, cut);
+	const tail = body.slice(cut + 1);
+	if (!isFeedId(id) || !FEED_TAIL.test(tail)) return;
+	const secret = tail.slice(0, FEED_SECRET_LENGTH);
+	return tail.slice(FEED_SECRET_LENGTH) === checksum(`${FEED_PREFIX}${id}_${secret}`, FEED_ALPHABET) ? {
+		id,
+		secret
+	} : void 0;
+}
+/**
+* A fresh `pdfeed_<id>_<secret><checksum>`: 26 lowercase base32 characters
+* (130 bits) and a 6-character CRC-32 checksum. The whole key is lowercase.
+*/
+function generateFeedKey(id) {
+	if (!isFeedId(id)) throw new TypeError("PermDock: a feed id is 1 to 16 of a-z, 0-9 and -");
+	let secret = "";
+	const bytes = /* @__PURE__ */ new Uint8Array(64);
+	while (secret.length < FEED_SECRET_LENGTH) {
+		globalThis.crypto.getRandomValues(bytes);
+		for (const byte of bytes) if (secret.length < FEED_SECRET_LENGTH) secret += FEED_ALPHABET[byte % 32];
+	}
+	const key = `${FEED_PREFIX}${id}_${secret}`;
+	return `${key}${checksum(key, FEED_ALPHABET)}`;
+}
+/**
+* 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, ALPHABET)}`;
+}
+/** 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 = secret.startsWith(FEED_PREFIX) ? parseFeedKey(secret) : 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 memoryCredentialStore(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 = credential.kind === "feed" ? generateFeedKey(credential.id) : 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, isoAt(at.epochMilliseconds));
+		},
+		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);
+		}
+	});
+}
+function isPrincipalRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) && Object.hasOwn(value, "id") && "id" in value && typeof value.id === "string";
+}
+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.principals === void 0) return { ok: true };
+		const owner = await options.principals.principal(credential.principal, tenant === void 0 ? {} : { tenant });
+		if (!isPrincipalRecord(owner)) 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, { epochMilliseconds: nowMillis() });
+		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
+	}))]);
+}
+function anonymous() {
+	return anonymousSubject();
+}
+/**
+* Resolves an opaque API key (`pdk_<id>_<secret>`) 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, source or callback) is
+* the anonymous subject, never a throw.
+*/
+async function subjectFromApiKey(key, options) {
+	const tenant = 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 feedKey = key.startsWith(FEED_PREFIX);
+	const parts = feedKey ? parseFeedKey(key) : 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 || feedKey !== (credential.kind === "feed") || options.kinds !== void 0 && !options.kinds.includes(credential.kind)) return deny("invalid-claims");
+	if (credential.expiresAt !== void 0 && Date.parse(credential.expiresAt) <= nowMillis()) 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
+//#region src/server/support-session.ts
+const SUPPORT_SESSION_TYP = "vnd.permdock.support-session+jwt";
+/**
+* Signs a granted `SupportSession` as a `vnd.permdock.support-session+jwt`
+* (`sub` the viewed principal, `act` the support actor, `jti` the session
+* id) that expires with the session. Throws a `TypeError` for a record
+* `parseSupportSession` refuses.
+*/
+function signSupportSession(session, signer, options = {}) {
+	const parsed = parseSupportSession(session);
+	if (parsed === void 0) throw new TypeError("PermDock: invalid support session");
+	return signer.sign(compact({
+		v: 1,
+		sub: parsed.principal,
+		act: {
+			sub: parsed.actor,
+			kind: "support"
+		},
+		tenant: parsed.tenant,
+		reason: parsed.reason,
+		permissions: parsed.permissions,
+		approved_by: parsed.approvedBy,
+		reference: parsed.reference
+	}), compact({
+		typ: SUPPORT_SESSION_TYP,
+		audience: options.audience,
+		expiresAt: secondsOf(parsed.expiresAt),
+		issuedAt: secondsOf(parsed.startedAt),
+		jti: parsed.id
+	}));
+}
+function sessionOf(claims) {
+	const record = ownRecord(claims);
+	const act = ownRecord(record?.["act"]);
+	const { iat, exp } = record ?? {};
+	if (record === void 0 || act === void 0 || act["kind"] !== "support" || act["act"] !== void 0 || typeof iat !== "number" || typeof exp !== "number" || !Number.isSafeInteger(iat) || !Number.isSafeInteger(exp)) return;
+	return parseSupportSession({
+		v: record["v"],
+		id: record["jti"],
+		principal: record["sub"],
+		actor: act["sub"],
+		tenant: record["tenant"],
+		reason: record["reason"],
+		permissions: record["permissions"],
+		startedAt: rfc3339(iat),
+		expiresAt: rfc3339(exp),
+		approvedBy: record["approved_by"],
+		reference: record["reference"]
+	});
+}
+async function load(principals, id, tenant) {
+	try {
+		const loaded = await principals.principal(id, { tenant });
+		const record = ownRecord(loaded);
+		if (record === void 0 || record["id"] !== id) return;
+		return loaded;
+	} catch {
+		return;
+	}
+}
+async function ended(sessions, id) {
+	if (sessions === void 0) return false;
+	try {
+		const live = ownRecord(await sessions.session(id));
+		return live === void 0 || live["id"] !== id || live["ended"] === true;
+	} catch {
+		return true;
+	}
+}
+/**
+* Resolves a `vnd.permdock.support-session+jwt` into the subject each
+* request of the session acts as: the viewed principal loaded live, a
+* `support` actor, the session's permissions as the delegation and
+* `context.supportSession`. The actor must still exist. Every failure is the
+* anonymous subject, never a throw.
+*/
+async function subjectFromSupportSession(token, options) {
+	if (typeof token !== "string" || token.length === 0) return anonymousSubject();
+	const deny = (cause) => {
+		try {
+			options.onAuth?.(compact({
+				reason: "invalid-token",
+				cause,
+				source: "support-session",
+				typ: SUPPORT_SESSION_TYP,
+				issuer: options.issuer,
+				requestId: options.requestId
+			}));
+		} catch {}
+		return anonymousSubject();
+	};
+	let session;
+	try {
+		const verified = await options.verifier.verify(token, compact({
+			typ: SUPPORT_SESSION_TYP,
+			audience: options.audience,
+			issuer: options.issuer,
+			clockTolerance: options.clockTolerance
+		}));
+		if (!verified.ok) return deny(verified.cause);
+		if (verified.header.typ?.toLowerCase().replace(/^application\//u, "") !== SUPPORT_SESSION_TYP) return deny("wrong-token-type");
+		session = sessionOf(verified.claims);
+	} catch {
+		return deny("malformed");
+	}
+	if (session === void 0) return deny("invalid-claims");
+	if ((secondsOf(session.expiresAt) ?? 0) <= epochSeconds()) return deny("expired");
+	if (await ended(options.sessions, session.id)) return deny("session-ended");
+	if (await load(options.principals, session.actor, session.tenant) === void 0) return deny("actor-unavailable");
+	const principal = await load(options.principals, session.principal, session.tenant);
+	if (principal === void 0) return deny("principal-unavailable");
+	const scopes = [];
+	let readOnly = true;
+	for (const key of session.permissions) {
+		const leaf = findPermission(options.permissions, key);
+		if (leaf === void 0) return deny("invalid-claims");
+		scopes.push(leaf.scope);
+		readOnly &&= annotationsFor(leaf).readOnlyHint;
+	}
+	return Object.freeze(compact({
+		principal: Object.freeze({
+			...principal,
+			tenant: session.tenant
+		}),
+		actor: Object.freeze(compact({
+			id: session.actor,
+			kind: "support",
+			readOnly: readOnly || void 0
+		})),
+		delegation: Object.freeze({ scopes }),
+		context: Object.freeze({ supportSession: Object.freeze(compact({
+			id: session.id,
+			reason: session.reason,
+			approvedBy: session.approvedBy,
+			reference: session.reference
+		})) }),
+		expiresAt: secondsOf(session.expiresAt)
+	}));
+}
+//#endregion
+export { generateFeedKey as a, parseApiKey as c, generateApiKey as i, parseFeedKey as l, subjectFromSupportSession as n, hashApiKey as o, apiKeyVerifier as r, memoryCredentialStore as s, signSupportSession as t, subjectFromApiKey as u };