permdock 0.0.0 → 0.2.0

package/dist/better-supabase/index.js

@@ -0,0 +1,620 @@
+import { n as freezeDeep } from "../freeze-CrU8nQeX.js";
+import { _ as listPermissions, p as isPermission } from "../permissions-DVoF6dMt.js";
+import { t as anonymousSubject } from "../subject-C6dLxqHU.js";
+import { t as mayUse } from "../may-use-DndQ5tQ-.js";
+import { o as parseCredential, r as credentialSubject } from "../credential-8P81ff4u.js";
+import { i as quoteSqlLiteral, o as sqlIdent } from "../sql-xdg5f4Fi.js";
+import { o as subjectFromSupabaseSession, t as parseSupabaseManifest } from "../manifest-iaoBXHKc.js";
+import { t as parseCatalog } from "../parse-BuyjxhZV.js";
+import { AsyncResult, dbError } from "better-supabase";
+//#region src/better-supabase/provider.ts
+/**
+* The helper each template calls (with `{scope}` unfilled), its default
+* argument types and the role that calls it: `postgres` for the templates
+* better-supabase runs inside its own `security definer` functions.
+*/
+const TEMPLATES = {
+	idsWith: {
+		helper: "permitted_{scope}_ids_by_permission",
+		listedAs: "permitted_{scope}_ids",
+		args: "text",
+		role: "authenticated",
+		sql: "permitted_{scope}_ids_by_permission({permission})"
+	},
+	isPlatform: {
+		helper: "permdock_has_permission",
+		listedAs: "permdock_has",
+		args: "text",
+		role: "authenticated",
+		sql: "permdock_has_permission({permission})"
+	},
+	idsWithFor: {
+		helper: "permitted_{scope}_ids_by_permission_for",
+		listedAs: "permitted_{scope}_ids_for",
+		args: "uuid, text",
+		role: "postgres",
+		sql: "permitted_{scope}_ids_by_permission_for({user}, {permission})"
+	},
+	isPlatformFor: {
+		helper: "permdock_has_permission_for",
+		listedAs: "permdock_has_for",
+		args: "uuid, text",
+		role: "postgres",
+		sql: "permdock_has_permission_for({user}, {permission})"
+	},
+	memberIds: {
+		helper: "member_{scope}_ids",
+		args: "",
+		role: "authenticated",
+		sql: "member_{scope}_ids()"
+	},
+	memberIdsFor: {
+		helper: "member_{scope}_ids_for",
+		args: "uuid",
+		role: "supabase_auth_admin",
+		sql: "member_{scope}_ids_for({user})"
+	},
+	canAssign: {
+		helper: "permdock_can_assign",
+		args: "text, text",
+		role: "authenticated",
+		sql: "permdock_can_assign({role}, {tenant}::text)"
+	},
+	canAssignFor: {
+		helper: "permdock_can_assign_for",
+		args: "uuid, text, text",
+		role: "postgres",
+		sql: "permdock_can_assign_for({user}, {role}, {tenant}::text)"
+	},
+	permissionsFor: {
+		helper: "permitted_{scope}_permission_keys_for",
+		args: "uuid, uuid",
+		role: "postgres",
+		sql: "array(select {schema}.permitted_{scope}_permission_keys_for({user}, {tenant}))"
+	}
+};
+const ASSIGN_ANY = {
+	canAssign: {
+		helper: "permdock_can_assign_any",
+		args: "text, uuid, text, text",
+		role: "authenticated",
+		sql: "permdock_can_assign_any({role}, {tenant}, '{scope}', {tenant}::text)"
+	},
+	canAssignFor: {
+		helper: "permdock_can_assign_any_for",
+		args: "uuid, text, uuid, text, text",
+		role: "postgres",
+		sql: "permdock_can_assign_any_for({user}, {role}, {tenant}, '{scope}', {tenant}::text)"
+	}
+};
+const listedName = (entry) => entry.listedAs ?? entry.helper;
+const OPTIONAL = [
+	"idsWithFor",
+	"isPlatformFor",
+	"memberIds",
+	"memberIdsFor",
+	"canAssign",
+	"canAssignFor",
+	"permissionsFor"
+];
+/** Postgres aliases of the id types better-supabase reads (`uuid`, `text`, `bigint`, `integer`). */
+const ID_TYPES = {
+	uuid: "uuid",
+	text: "text",
+	bigint: "bigint",
+	int8: "bigint",
+	integer: "integer",
+	int: "integer",
+	int4: "integer"
+};
+const withSchema = (schema, sql) => sql.includes("{schema}") ? sql.replaceAll("{schema}", schema) : `${schema}.${sql}`;
+/** `p_user uuid, p_grant text` as `uuid, text`. */
+const argTypes = (args) => args.split(",").map((arg) => arg.trim().split(/\s+/u).slice(1).join(" ")).filter((type) => type !== "").join(", ");
+function tenantScopeOf(manifest, explicit) {
+	const names = manifest.rls.scopes.map((scope) => scope.name);
+	if (explicit !== void 0) {
+		if (!names.includes(explicit)) throw new TypeError(`PermDock: scope "${explicit}" is not in the manifest's rls.scopes (${names.join(", ")}).`);
+		return explicit;
+	}
+	const roots = manifest.rls.scopes.filter((scope) => scope.within === void 0);
+	const [root] = roots;
+	if (root === void 0 || roots.length > 1) throw new TypeError(`PermDock: the manifest has ${roots.length} root scopes (${roots.map((scope) => scope.name).join(", ") || "none"}), so it can't tell which scope tenants are. Pass { scope } with one of ${names.join(", ")}.`);
+	return root.name;
+}
+function covers(membership, scope) {
+	return !("value" in membership.scope) || membership.scope.value === scope;
+}
+/** `source` as better-supabase reads it, for a source that covers `scope`. */
+function membershipOf(source, scope, problems) {
+	if ("through" in source.user) {
+		problems.push(`${source.table} reads its user id through ${source.user.through.table}, which better-supabase's membership reads don't follow.`);
+		return;
+	}
+	return {
+		table: source.table,
+		userColumn: source.user.column,
+		scope: "column" in source.scope ? { column: source.scope.column } : { value: scope },
+		idColumn: source.id.column
+	};
+}
+function roleSourceOf(source) {
+	const role = source.role;
+	if (Array.isArray(role) || !("column" in role) || !("through" in role)) return;
+	return {
+		table: source.table,
+		role: {
+			column: role.column,
+			through: {
+				table: role.through.table,
+				id: role.through.id,
+				column: role.through.column
+			}
+		}
+	};
+}
+function disabledRow(row) {
+	return {
+		table: row.table,
+		id: row.id,
+		...row.disabledAt === void 0 ? {} : { disabledAt: row.disabledAt },
+		...row.status === void 0 || row.active === void 0 ? {} : {
+			status: row.status,
+			active: row.active
+		}
+	};
+}
+function permissionsOf(catalog, scopes) {
+	return catalog.permissions.map((permission) => {
+		const granted = /* @__PURE__ */ new Set();
+		for (const grant of catalog.grants ?? []) if (grant.permission === permission.key && typeof grant.scope === "string" && scopes.has(grant.scope)) granted.add(grant.scope);
+		return {
+			key: permission.key,
+			sqlComplete: !permission.rowConditions,
+			...granted.size > 0 ? { scopes: [...granted].toSorted() } : {}
+		};
+	});
+}
+function tokenHookOf(manifest) {
+	const owned = manifest.claims.filter((claim) => claim.source === "permdock");
+	const registered = manifest.claims.filter((claim) => claim.source !== "permdock");
+	const budgeted = manifest.claims.filter((claim) => claim.budget);
+	return {
+		function: `${manifest.hook.schema}.${manifest.hook.function}`,
+		tenantClaim: manifest.tenantClaim,
+		ownedClaims: owned.map((claim) => claim.name),
+		...registered.length > 0 ? { registeredClaims: registered.map((claim) => ({
+			name: claim.name,
+			function: claim.source
+		})) } : {},
+		budget: {
+			claims: budgeted.map((claim) => claim.name),
+			bytes: manifest.budget.bytes,
+			...owned.some((claim) => claim.name === "memberships_truncated") ? { truncatedClaim: "memberships_truncated" } : {}
+		},
+		markers: {
+			hook: `-- permdock:hook ${manifest.markers.hook}`,
+			grants: `-- permdock:grants ${manifest.markers.grants}`
+		},
+		grantsCommand: `permdock supabase hook generate --grants-out supabase/migrations/<timestamp>_permdock_hook_grants.sql`
+	};
+}
+/**
+* better-supabase's `authorization` config value, built from PermDock's
+* manifest and catalog: the scopes, the `rls generate` helpers as SQL
+* templates, the membership tables, suspension rows, the token hook and
+* every catalog key with `sqlComplete` set from its `rowConditions`. A
+* `_for` template and `permissionsFor` are set only when the manifest lists
+* their helper, which `rls.mode: 'database'` writes; `canApprove` only with
+* `approver`. Throws when the manifest or catalog is invalid, or when the
+* tenant scope is ambiguous.
+*/
+function authorizationProvider(options) {
+	const manifest = parseSupabaseManifest(options.manifest);
+	const catalog = options.catalog === void 0 ? void 0 : parseCatalog(options.catalog);
+	const rls = manifest.rls;
+	const problems = [];
+	if (catalog === void 0) problems.push("No catalog: better-supabase cannot check that the permission keys its SQL modules use (ai_chat, workflow, inbox and the rest) exist. Pass `catalog`.");
+	const tenantScope = tenantScopeOf(manifest, options.scope);
+	const scopeNames = rls.scopes.map((scope) => scope.name);
+	const helpers = new Map(rls.helpers.map((helper) => [helper.name, helper]));
+	const schema = sqlIdent(rls.schema);
+	const rootTenant = rls.scopes.find((scope) => scope.name === tenantScope)?.within === void 0;
+	const assignAny = rls.customRoles === true && rootTenant;
+	const entryOf = (template) => assignAny && (template === "canAssign" || template === "canAssignFor") ? ASSIGN_ANY[template] : TEMPLATES[template];
+	const listed = (template, scope) => helpers.has(listedName(entryOf(template)).replaceAll("{scope}", scope));
+	const templates = [
+		"idsWith",
+		"isPlatform",
+		...OPTIONAL.filter((template) => listed(template, tenantScope))
+	];
+	for (const template of ["idsWith", "isPlatform"]) if (!listed(template, tenantScope)) problems.push(`The manifest's rls.helpers has no ${rls.schema}.${listedName(TEMPLATES[template]).replaceAll("{scope}", tenantScope)}. Run \`permdock rls generate\`, then \`permdock supabase inspect --out\`.`);
+	if (rls.customRoles === true && !rootTenant && templates.includes("canAssign")) problems.push(`The tenant scope "${tenantScope}" is not a root scope, so canAssign checks declared roles only: ${rls.schema}.${ASSIGN_ANY.canAssign.helper}, which also answers for custom roles, takes the root tenant id.`);
+	const optional = {};
+	const requires = [];
+	const required = /* @__PURE__ */ new Set();
+	for (const template of templates) {
+		const entry = entryOf(template);
+		optional[template] = withSchema(schema, entry.sql);
+		for (const scope of entry.helper.includes("{scope}") ? scopeNames : [tenantScope]) {
+			const name = entry.helper.replaceAll("{scope}", scope);
+			const fn = `${schema}.${sqlIdent(name)}`;
+			if (required.has(fn)) continue;
+			required.add(fn);
+			const helper = helpers.get(name);
+			const args = helper === void 0 ? entry.args : argTypes(helper.args);
+			requires.push({
+				function: fn,
+				...args === "" ? {} : { args },
+				role: entry.role
+			});
+		}
+	}
+	const memberships = [];
+	const roleSources = [];
+	for (const source of rls.memberships) {
+		if (!covers(source, tenantScope)) continue;
+		const membership = membershipOf(source, tenantScope, problems);
+		if (membership) memberships.push(membership);
+		const roleSource = roleSourceOf(source);
+		if (roleSource) roleSources.push(roleSource);
+	}
+	const users = rls.suspension?.users;
+	const tenants = rls.suspension?.scopes?.[tenantScope];
+	const approver = options.approver;
+	let canApprove;
+	if (approver !== void 0) {
+		if (catalog !== void 0 && !catalog.permissions.some((permission) => permission.key === approver.key)) problems.push(`The approver permission ${approver.key} is not in the catalog. Run \`permdock catalog\` after adding it to the policy.`);
+		const name = `permitted_${tenantScope}_ids_by_permission`;
+		canApprove = `{tenant} in (select ${schema}.${sqlIdent(name)}(${quoteSqlLiteral(approver.key)}))`;
+		requires.push({
+			function: `${schema}.${sqlIdent(name)}`,
+			args: "text",
+			role: "postgres"
+		});
+	}
+	const functions = {
+		...optional,
+		idsWith: `${schema}.${TEMPLATES.idsWith.sql}`,
+		isPlatform: `${schema}.${TEMPLATES.isPlatform.sql}`,
+		...canApprove === void 0 ? {} : { canApprove }
+	};
+	const scopes = rls.scopes.map((scope) => {
+		const idType = ID_TYPES[scope.type.trim().toLowerCase()];
+		if (idType === void 0) problems.push(`Scope "${scope.name}" has ids of type ${scope.type}; better-supabase reads uuid, text, bigint and integer ids.`);
+		return scope.within === void 0 ? {
+			name: scope.name,
+			idType: idType ?? scope.type
+		} : {
+			name: scope.name,
+			idType: idType ?? scope.type,
+			parent: scope.within
+		};
+	});
+	return freezeDeep({
+		apiVersion: 1,
+		name: "PermDock",
+		scopes,
+		tenantScope,
+		functions,
+		requires,
+		...catalog ? { permissions: permissionsOf(catalog, new Set(scopeNames)) } : {},
+		...memberships.length > 0 ? { memberships } : {},
+		...users || tenants ? { suspension: {
+			...users ? { user: disabledRow(users) } : {},
+			...tenants ? { tenant: disabledRow(tenants) } : {}
+		} } : {},
+		...roleSources.length > 0 ? { roleSources } : {},
+		...canApprove === void 0 ? {} : { approvals: { distinctApprover: true } },
+		decidingColumns: manifest.decidingColumns,
+		tokenHook: tokenHookOf(manifest),
+		...problems.length > 0 ? { problems } : {}
+	});
+}
+//#endregion
+//#region src/better-supabase/policies.ts
+/** PermDock splits a key with row conditions into `key#1`, `key#2`, ... in the policies it generates. */
+const SPLIT_KEY = /#\d+$/u;
+function checkedKey(where, permission, catalog, scope) {
+	const key = permission.key;
+	if (SPLIT_KEY.test(key)) throw new TypeError(`PermDock: ${where} "${key}" is one part of a permission split by row condition. Use the policies \`permdock rls generate\` writes for it.`);
+	const entry = catalog.permissions.find((candidate) => candidate.key === key);
+	if (!entry) throw new TypeError(`PermDock: ${where} "${key}" is not in permissions.catalog.json. Run \`permdock catalog\`.`);
+	if (entry.rowConditions) throw new TypeError(`PermDock: ${where} "${key}" has row conditions (rowConditions: true), which the SQL helpers don't check, so the policy would grant every object in the scope. Use the policies \`permdock rls generate\` writes for it.`);
+	const grantScope = scope === "platform" ? "global" : scope;
+	const scopes = (catalog.grants ?? []).flatMap((grant) => grant.permission === key && typeof grant.scope === "string" ? [grant.scope] : []);
+	if (scopes.length > 0 && !scopes.includes(grantScope)) throw new TypeError(`PermDock: ${where} "${key}" is granted at ${[...new Set(scopes)].join(", ")}, not at ${grantScope}. Check it at one of those scopes.`);
+	return key;
+}
+function target(options) {
+	const manifest = parseSupabaseManifest(options.manifest);
+	const catalog = parseCatalog(options.catalog);
+	const names = manifest.rls.scopes.map((scope) => scope.name);
+	if (options.scope !== "platform" && !names.includes(options.scope)) throw new TypeError(`PermDock: scope "${options.scope}" is not in the manifest's rls.scopes (${names.join(", ")}) and is not "platform".`);
+	const schema = sqlIdent(manifest.rls.schema);
+	return {
+		catalog,
+		sql: {
+			idsWith: `${schema}.permitted_{scope}_ids_by_permission({permission})`,
+			isPlatform: `${schema}.permdock_has_permission({permission})`
+		}
+	};
+}
+/**
+* A better-supabase bucket `policy` that checks PermDock permissions with
+* the `rls generate` helpers at `scope`. The helpers check role and scope
+* only, so a permission the catalog doesn't mark `rowConditions: false`, or
+* doesn't grant at `scope`, throws.
+*/
+function bucketPolicy(access, options) {
+	const { catalog, sql } = target(options);
+	const key = (name, permission) => checkedKey(`bucket access.${name}`, permission, catalog, options.scope);
+	return freezeDeep({
+		access: {
+			read: key("read", access.read),
+			...access.list ? { list: key("list", access.list) } : {},
+			write: key("write", access.write),
+			...access.delete ? { delete: key("delete", access.delete) } : {}
+		},
+		scope: options.scope,
+		...options.segment === void 0 ? {} : { segment: options.segment },
+		sql
+	});
+}
+/** As {@link bucketPolicy}, for a better-supabase Realtime topic. */
+function topicPolicy(access, options) {
+	const { catalog, sql } = target(options);
+	const key = (name, permission) => checkedKey(`topic ${name}`, permission, catalog, options.scope);
+	return freezeDeep({
+		receive: key("receive", access.receive),
+		...access.send ? { send: key("send", access.send) } : {},
+		scope: options.scope,
+		...options.segment === void 0 ? {} : { segment: options.segment },
+		sql
+	});
+}
+//#endregion
+//#region src/better-supabase/api-keys.ts
+const seconds = (instant) => Math.floor(instant.epochMilliseconds / 1e3);
+/** When a key stops verifying: its expiry, or the end of a rotated key's grace period. */
+function endOf(key) {
+	const { expiresAt, revokedAt } = key;
+	if (revokedAt === void 0) return expiresAt;
+	if (expiresAt === void 0) return revokedAt;
+	return revokedAt.epochMilliseconds < expiresAt.epochMilliseconds ? revokedAt : expiresAt;
+}
+/** `rls.apiKeys.serviceRoles` from the manifest, when it has `rls.apiKeys`. */
+function manifestServiceRoles(manifest) {
+	return manifest === void 0 ? void 0 : parseSupabaseManifest(manifest).rls.apiKeys?.serviceRoles;
+}
+/**
+* A personal key as a `user` credential acting as its user, a tenant key as
+* a `service` credential holding `roles` in its tenant; `null` when `*`
+* has no expansion, a tenant key has no roles, or the record is invalid.
+*/
+function keyCredential(key, roles, allPermissions) {
+	const scopes = key.scopes.includes("*") ? allPermissions?.map((permission) => permission.key) : key.scopes;
+	if (scopes === void 0) return null;
+	const owner = key.userId;
+	const base = {
+		v: 1,
+		id: key.id,
+		permissions: scopes.map((permission) => ({ permission })),
+		createdBy: key.createdBy ?? owner ?? key.id,
+		createdAt: key.createdAt ?? 0,
+		...key.expiresAt === void 0 ? {} : { expiresAt: key.expiresAt },
+		name: key.name
+	};
+	if (owner !== void 0) return parseCredential({
+		...base,
+		kind: "user",
+		principal: owner,
+		...key.organizationId === void 0 ? {} : { tenant: key.organizationId }
+	}) ?? null;
+	if (roles === void 0 || key.organizationId === void 0) return null;
+	return parseCredential({
+		...base,
+		kind: "service",
+		principal: key.id,
+		tenant: key.organizationId,
+		roles
+	}) ?? null;
+}
+/**
+* better-supabase's API keys as a `CredentialVerifier`, for
+* `subjectFromApiKey` from `permdock/server`, which reads PermDock's
+* `pdk_<id>_<secret>` format: create the keys with `prefix: "pdk"`. The
+* credential id is the key's `publicId`, the id in the token. A personal key
+* is a `user` credential acting as its user (inside its tenant when the key
+* is limited to one), a tenant key a `service` credential holding
+* `serviceRoles` in its tenant, and the key's scopes are the credential's
+* permissions. better-supabase records the use when it verifies, so there is
+* no `touch`. A rotated key in its grace period verifies, and its credential
+* expires when the grace period ends. An invalid, revoked, expired or
+* rate-limited key, and a failed lookup, are `null`. `permdock/server` exports a different
+* `apiKeyVerifier`, over the application's own key records.
+*/
+function apiKeyVerifier(options) {
+	const fallback = manifestServiceRoles(options.manifest);
+	return freezeDeep({ async verify(secret) {
+		try {
+			const checked = await options.keys.verify(secret);
+			if (!checked.ok || checked.data.status !== "ok") return null;
+			const { key } = checked.data;
+			if (key.state !== "active" && key.state !== "grace") return null;
+			const end = endOf(key);
+			const roles = typeof options.serviceRoles === "function" ? options.serviceRoles(key) : options.serviceRoles ?? fallback;
+			return keyCredential({
+				id: key.publicId,
+				name: key.name,
+				scopes: key.scopes,
+				createdAt: seconds(key.createdAt),
+				...key.organizationId === void 0 ? {} : { organizationId: key.organizationId },
+				...key.userId === void 0 ? {} : { userId: key.userId },
+				...key.createdBy === void 0 ? {} : { createdBy: key.createdBy },
+				...end === void 0 ? {} : { expiresAt: seconds(end) }
+			}, roles, options.allPermissions);
+		} catch {
+			return null;
+		}
+	} });
+}
+/**
+* The `claim` and `tenantClaim` options of better-supabase's
+* `apiKeyClaims()`, from the manifest's `rls.apiKeys`, so a key's token
+* carries the scopes ceiling, tenant and roles the `rls generate` helpers
+* read. Throws when the manifest has no `rls.apiKeys`.
+*/
+function apiKeyClaimOptions(manifest) {
+	const rls = parseSupabaseManifest(manifest).rls;
+	const apiKeys = rls.apiKeys;
+	if (!apiKeys) throw new TypeError("PermDock: the manifest has no rls.apiKeys. Set rls.apiKeys in permdock.config.ts, then run `permdock rls generate` and `permdock supabase inspect --out`.");
+	return freezeDeep({
+		claim: {
+			name: apiKeys.claim,
+			scopes: apiKeys.scopes,
+			tenant: apiKeys.tenant,
+			roles: apiKeys.roles,
+			serviceRoles: apiKeys.serviceRoles
+		},
+		tenantClaim: rls.tenantClaim
+	});
+}
+//#endregion
+//#region src/better-supabase/credentials.ts
+/**
+* `provider` with every `getToken`, `startAuthorization`,
+* `completeAuthorization` and `revoke` decided by PermDock first, on the
+* `CredentialRef` as the row. Anything but `granted` is a `forbidden`
+* error with hint `PERMDOCK_DENIED`, and a failed check is one too.
+* `capabilities` and `verifyInbound` (a third party's request, with no
+* user) pass through. Build it per request, with that request's PermDock.
+*/
+function credentialGuard(provider, options) {
+	const allowed = async (permission, ref) => {
+		try {
+			return (await options.permdock()).can(permission, ref);
+		} catch {
+			return false;
+		}
+	};
+	const guarded = (permission, ref, run) => AsyncResult.from(async () => await allowed(permission, ref) ? run() : AsyncResult.err(dbError("forbidden", `PermDock denied ${permission.key}`, { hint: "PERMDOCK_DENIED" })));
+	const revoke = options.revoke ?? options.use;
+	const start = provider.startAuthorization?.bind(provider);
+	const complete = provider.completeAuthorization?.bind(provider);
+	const inbound = provider.verifyInbound?.bind(provider);
+	return Object.freeze({
+		apiVersion: 1,
+		name: provider.name,
+		getToken: (ref, getOptions) => guarded(options.use, ref, () => provider.getToken(ref, getOptions)),
+		capabilities: (ref) => provider.capabilities(ref),
+		...start === void 0 ? {} : { startAuthorization: (ref, startOptions) => guarded(options.use, ref, () => start(ref, startOptions)) },
+		...complete === void 0 ? {} : { completeAuthorization: (ref, completeOptions) => guarded(options.use, ref, () => complete(ref, completeOptions)) },
+		revoke: (ref, revokeOptions) => guarded(revoke, ref, () => provider.revoke(ref, revokeOptions)),
+		...inbound === void 0 ? {} : { verifyInbound: inbound }
+	});
+}
+//#endregion
+//#region src/better-supabase/mcp.ts
+const refused = (reason) => ({
+	allowed: false,
+	reason
+});
+/**
+* The `authorize` and `visible` hooks of better-supabase's `createMcp`, for
+* tools whose `meta` is a PermDock permission. A tool without a permission
+* is hidden and refused. `authorize` grants only a `granted` decision: an
+* approval-required call is refused, because `createMcp`
+* has no approval flow. A throw anywhere refuses.
+*/
+function toolPolicy(options) {
+	return Object.freeze({
+		async authorize(ctx, tool, args) {
+			const permission = tool.meta;
+			if (!isPermission(permission)) return refused("This tool has no PermDock permission.");
+			try {
+				const permdock = await options.permdock(ctx);
+				const data = await options.data?.(ctx, tool, args);
+				const decision = permdock.decide(permission, data);
+				switch (decision.outcome) {
+					case "granted": return { allowed: true };
+					case "approval-required": return refused(`${permission.key} needs approval, which this server does not collect.`);
+					case "denied": return refused(`PermDock denied ${permission.key}.`);
+					default: return decision;
+				}
+			} catch {
+				return refused("The permission check failed.");
+			}
+		},
+		async visible(ctx, tool) {
+			const permission = tool.meta;
+			if (!isPermission(permission)) return false;
+			try {
+				return mayUse(await options.permdock(ctx), permission);
+			} catch {
+				return false;
+			}
+		}
+	});
+}
+//#endregion
+//#region src/better-supabase/subject.ts
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** `session` with the short codes in `claim` turned back into feature keys. */
+function decodedFeatures(session, claim, keys) {
+	const claims = session?.claims;
+	if (session === null || session === void 0 || !isRecord(claims)) return session;
+	const coded = claims[claim];
+	if (!isRecord(coded)) return session;
+	const byCode = new Map(Object.entries(keys).map(([key, code]) => [code, key]));
+	const decoded = Object.fromEntries(Object.entries(coded).map(([tenant, codes]) => [tenant, Array.isArray(codes) ? codes.flatMap((code) => {
+		const key = typeof code === "string" ? byCode.get(code) : void 0;
+		return key === void 0 ? [] : [key];
+	}) : codes]));
+	return {
+		...session,
+		claims: {
+			...claims,
+			[claim]: decoded
+		}
+	};
+}
+function isApiKeySession(session) {
+	if (typeof session !== "object" || session === null) return false;
+	const record = Object.fromEntries(Object.entries(session));
+	return record["kind"] === "apiKey" && typeof record["keyId"] === "string" && typeof record["name"] === "string" && Array.isArray(record["scopes"]) && record["scopes"].every((scope) => typeof scope === "string");
+}
+function apiKeySubject(session, options) {
+	const roles = typeof options.serviceRoles === "function" ? options.serviceRoles(session) : options.serviceRoles ?? manifestServiceRoles(options.manifest);
+	const credential = keyCredential({
+		id: session.keyId,
+		name: session.name,
+		scopes: session.scopes,
+		...session.organizationId === void 0 ? {} : { organizationId: session.organizationId },
+		...session.userId === void 0 ? {} : { userId: session.userId },
+		...session.createdBy === void 0 ? {} : { createdBy: session.createdBy },
+		...session.createdAt === void 0 ? {} : { createdAt: session.createdAt }
+	}, roles, listPermissions(options.permissions));
+	return credential === null ? anonymousSubject() : credentialSubject(credential, { permissions: options.permissions });
+}
+/**
+* `subjectFromSupabaseSession` for better-supabase's `AuthSession`, reading
+* `memberships` for the memberships and the entitlements module's `features`
+* claim for `principal.plans` (`plans` names another claim). With `apiKeys`,
+* a verified `apiKey` session is the key's credential subject: a personal key
+* acts as its user within the key's scopes, a tenant key as a `service`
+* principal holding `serviceRoles`. Without `apiKeys`, and for `anon`,
+* `service` and `invalid` sessions, the subject is anonymous.
+*/
+function subjectFromBetterSupabase(session, options = {}) {
+	const { apiKeys, plans = "features", ...rest } = options;
+	if (isApiKeySession(session)) return apiKeys === void 0 ? anonymousSubject() : apiKeySubject(session, apiKeys);
+	const claim = typeof plans === "string" ? plans : plans.claim ?? "features";
+	const keys = typeof plans === "string" ? void 0 : plans.keys;
+	return subjectFromSupabaseSession(keys === void 0 ? session : decodedFeatures(session, claim, keys), {
+		memberships: "memberships",
+		...rest,
+		plans: claim
+	});
+}
+//#endregion
+export { apiKeyClaimOptions, apiKeyVerifier, authorizationProvider, bucketPolicy, credentialGuard, subjectFromBetterSupabase, toolPolicy, topicPolicy };

package/dist/bind-CVy3Espv.d.ts

@@ -0,0 +1,25 @@
+import { f as ApprovalStore } from "./types-vKyAMtcX.js";
+import { t as InstanceOptions } from "./instance-options-BK_rNOSC.js";
+import { r as PdpFactory } from "./types-BVyImy5I.js";
+import { o as OtelWrap } from "./types-vNSDF7Dq.js";
+import { T as TenantOption, b as WebBotAuthVerifier } from "./create-BWyx3jua.js";
+//#region src/server/bind.d.ts
+/** The options of every framework adapter; `TContext` is what its callbacks receive. */
+type ServerAdapterOptions<TContext, TUser = unknown> = InstanceOptions & ServerAdapterServices & {
+  readonly subject: (context: TContext) => TUser | Promise<TUser>;
+  /** The agent or service acting for the subject; anything but an `Actor` is ignored. */
+  readonly actor?: (context: TContext) => unknown;
+  readonly tenant?: TenantOption<TContext>;
+};
+/** The services an adapter hands to its kernel unchanged. */
+type ServerAdapterServices = {
+  readonly store?: ApprovalStore;
+  /** `createPermDock` from `permdock/pdp`; `protect` then decides delegated permissions remotely. */
+  readonly pdp?: PdpFactory;
+  /** `(permdock) => withOtel(permdock, options)` from `permdock/otel`. */
+  readonly otel?: OtelWrap;
+  /** `(request) => verifyWebBotAuth(request, options)`; a verified bot becomes the actor. */
+  readonly webBotAuth?: WebBotAuthVerifier;
+};
+//#endregion
+export { ServerAdapterServices as n, ServerAdapterOptions as t };