permdock 0.0.0 → 0.2.0

package/dist/better-auth/index.js

@@ -0,0 +1,344 @@
+import { n as isReadonlyArray, t as compact } from "../compact-y6vfu2_f.js";
+import { n as freezeDeep } from "../freeze-CrU8nQeX.js";
+import { _ as listPermissions } from "../permissions-DVoF6dMt.js";
+import { m as role, t as allow } from "../policy-xyWg7QdR.js";
+import { t as ignoreRejection } from "../thenable-okc2xDsj.js";
+import { t as anonymousSubject } from "../subject-C6dLxqHU.js";
+import { i as membershipEvent } from "../sink-Bd9PSyfq.js";
+//#region src/better-auth/parse.ts
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function asRoles(value) {
+	if (typeof value === "string") return value === "" ? [] : value.split(",").map((item) => item.trim()).filter((item) => item !== "");
+	if (!Array.isArray(value)) return [];
+	return value.filter((item) => typeof item === "string");
+}
+function asStatements(value) {
+	if (!isRecord(value)) return {};
+	const out = {};
+	for (const [resource, actions] of Object.entries(value)) {
+		if (!Array.isArray(actions)) continue;
+		out[resource] = actions.filter((action) => typeof action === "string");
+	}
+	return out;
+}
+function expiresAtSeconds(value) {
+	if (typeof value === "number" && Number.isFinite(value)) return value > 0xe8d4a51000 ? Math.floor(value / 1e3) : Math.floor(value);
+	if (value instanceof Date) {
+		const ms = value.getTime();
+		return Number.isFinite(ms) ? Math.floor(ms / 1e3) : void 0;
+	}
+	if (typeof value === "string") {
+		const parsed = Date.parse(value);
+		return Number.isNaN(parsed) ? void 0 : Math.floor(parsed / 1e3);
+	}
+}
+function unwrapList(value) {
+	if (Array.isArray(value)) return value;
+	if (!isRecord(value)) return [];
+	for (const key of [
+		"members",
+		"teams",
+		"organizations",
+		"roles",
+		"data",
+		"items"
+	]) {
+		const inner = value[key];
+		if (Array.isArray(inner)) return inner;
+	}
+	return [];
+}
+/**
+* Member rows for `userId` only. `listMembers` returns every member of an
+* organization, so a row without the caller's `userId` is never theirs.
+*/
+function parseMemberRows(value, userId, requireUserId = true) {
+	const out = [];
+	const rows = isRecord(value) && typeof value["organizationId"] === "string" ? [value] : unwrapList(value);
+	for (const item of rows) {
+		if (!isRecord(item)) continue;
+		const owner = typeof item["userId"] === "string" ? item["userId"] : void 0;
+		if (owner === void 0 ? requireUserId : owner !== userId) continue;
+		const tenant = typeof item["organizationId"] === "string" ? item["organizationId"] : void 0;
+		const roles = asRoles(item["role"] ?? item["roles"]);
+		if (tenant === void 0 || roles.length === 0) continue;
+		out.push(compact({
+			tenant,
+			roles
+		}));
+	}
+	return out;
+}
+function parseTeamRows(value, userId) {
+	const out = [];
+	for (const item of unwrapList(value)) {
+		if (!isRecord(item)) continue;
+		if (typeof item["userId"] === "string" && item["userId"] !== userId) continue;
+		const teamRecord = isRecord(item["team"]) ? item["team"] : void 0;
+		const team = typeof item["teamId"] === "string" ? item["teamId"] : typeof teamRecord?.["id"] === "string" ? teamRecord["id"] : void 0;
+		const tenant = typeof item["organizationId"] === "string" ? item["organizationId"] : typeof teamRecord?.["organizationId"] === "string" ? teamRecord["organizationId"] : void 0;
+		const roles = asRoles(item["role"] ?? item["roles"]);
+		if (team === void 0 || roles.length === 0) continue;
+		out.push(compact({
+			tenant,
+			team,
+			roles,
+			via: `team:${team}`
+		}));
+	}
+	return out;
+}
+function parseOrganizationRoles(value) {
+	const out = [];
+	for (const item of unwrapList(value)) {
+		if (!isRecord(item)) continue;
+		const name = typeof item["role"] === "string" ? item["role"] : typeof item["name"] === "string" ? item["name"] : void 0;
+		if (name === void 0 || name === "") continue;
+		out.push({
+			name,
+			statements: asStatements(item["permission"] ?? item["permissions"] ?? item["statements"])
+		});
+	}
+	return out;
+}
+function statementsCover(candidate, required) {
+	for (const [resource, actions] of Object.entries(required)) {
+		const held = candidate[resource];
+		if (held === void 0) return false;
+		const set = new Set(held);
+		for (const action of actions) if (!set.has(action)) return false;
+	}
+	return true;
+}
+//#endregion
+//#region src/better-auth/roles.ts
+function statementsOf(accessRole) {
+	return asStatements(accessRole.statements ?? accessRole.permissions);
+}
+function rolesFromAccessControl(access, permissions, options = {}) {
+	const leaves = listPermissions(permissions);
+	const unmatched = [];
+	const roles = [];
+	for (const [name, accessRole] of Object.entries(access.roles)) {
+		const statements = statementsOf(accessRole);
+		const grants = [];
+		for (const [resource, actions] of Object.entries(statements)) for (const action of actions) {
+			const leaf = leaves.find((item) => item.resource === resource && item.action === action);
+			if (leaf === void 0) {
+				unmatched.push({
+					role: name,
+					resource,
+					action
+				});
+				continue;
+			}
+			grants.push(allow(leaf));
+		}
+		roles.push(options.on === "tenant" ? role(name, grants, { on: "tenant" }) : role(name, grants));
+	}
+	return Object.assign(roles, { unmatched });
+}
+function betterAuthRoleSource(auth, options = {}) {
+	const assignableRoles = options.assignable ?? [];
+	return {
+		async rolesFor(tenant) {
+			try {
+				return parseOrganizationRoles(await auth.api?.listOrganizationRoles?.({
+					query: { organizationId: tenant },
+					headers: options.headers
+				})).map((item) => freezeDeep(compact({
+					tenant,
+					name: item.name,
+					includes: assignableRoles.filter((declared) => statementsCover(item.statements, declared.statements)).map((declared) => declared.name)
+				})));
+			} catch {
+				return [];
+			}
+		},
+		assignable() {
+			return assignableRoles.map((item) => item.name);
+		}
+	};
+}
+/** A team role sits in the second scope inside its organization; an organization role in the first. */
+function scopeOfChange(event) {
+	const tenant = event.organizationId;
+	if (tenant === void 0) return {};
+	return event.teamId === void 0 ? {
+		scope: "tenant",
+		id: tenant
+	} : {
+		scope: "team",
+		id: event.teamId,
+		within: { tenant }
+	};
+}
+function onRoleChange(refresh, options = {}) {
+	return async (event) => {
+		await refresh(event);
+		const sink = options.sink;
+		if (sink === void 0 || event.userId === void 0) return;
+		const added = event.role !== void 0 && event.role !== event.previousRole ? [event.role] : [];
+		const removed = event.previousRole !== void 0 && event.previousRole !== event.role ? [event.previousRole] : [];
+		const operation = event.previousRole === void 0 ? "added" : event.role === void 0 ? "removed" : "changed";
+		try {
+			await sink.write([membershipEvent(compact({
+				source: "better-auth",
+				operation,
+				principal: { id: event.userId },
+				...scopeOfChange(event),
+				roles: {
+					added,
+					removed
+				},
+				by: event.by
+			}))]);
+		} catch {}
+	};
+}
+//#endregion
+//#region src/better-auth/subject.ts
+const PROFILE_FIELDS = /* @__PURE__ */ new Set([
+	"name",
+	"image",
+	"displayName"
+]);
+function validateClaims(extra, schema) {
+	const result = schema["~standard"].validate(extra);
+	if (result instanceof Promise) {
+		ignoreRejection(result);
+		return;
+	}
+	if ("issues" in result && result.issues !== void 0) return;
+	const value = result.value;
+	return isRecord(value) ? value : void 0;
+}
+function extraFields(user) {
+	const reserved = /* @__PURE__ */ new Set([
+		"id",
+		"role",
+		"roles",
+		"email",
+		"emailVerified",
+		"createdAt",
+		"updatedAt",
+		"banned",
+		"banReason",
+		"banExpires"
+	]);
+	const extra = {};
+	for (const [key, value] of Object.entries(user)) {
+		if (reserved.has(key) || PROFILE_FIELDS.has(key)) continue;
+		extra[key] = value;
+	}
+	return extra;
+}
+function isTrustedSession(session) {
+	if (!isRecord(session)) return false;
+	return isRecord(session["user"]) || isRecord(session["session"]);
+}
+async function settle(load, fallback) {
+	try {
+		return await load();
+	} catch {
+		return fallback;
+	}
+}
+async function organizationIds(auth, tenant, options) {
+	const list = auth.api?.listOrganizations;
+	if (options.memberships === "active" || list === void 0) return tenant === void 0 ? [] : [tenant];
+	const ids = (await settle(async () => {
+		const value = await list({ headers: options.headers });
+		return isReadonlyArray(value) ? value : [];
+	}, [])).map((row) => isRecord(row) && typeof row["id"] === "string" ? row["id"] : void 0).filter((id) => id !== void 0 && id !== "");
+	return [...new Set(ids)];
+}
+const MEMBER_LIMIT = 5e3;
+/** Every member row of the user in one adapter query, or `undefined` without an adapter. */
+async function memberRows(auth, userId) {
+	try {
+		const findMany = (await auth.$context)?.adapter?.findMany;
+		if (findMany === void 0) return;
+		return parseMemberRows(await findMany({
+			model: "member",
+			where: [{
+				field: "userId",
+				value: userId
+			}],
+			limit: MEMBER_LIMIT
+		}), userId);
+	} catch {
+		return;
+	}
+}
+function memberIn(auth, userId, organizationId, tenant, headers) {
+	const active = auth.api?.getActiveMember;
+	if (organizationId === tenant && active !== void 0) return settle(async () => parseMemberRows(await active({ headers }), userId), []);
+	const list = auth.api?.listMembers;
+	if (list === void 0) return Promise.resolve([]);
+	return settle(async () => parseMemberRows(await list({
+		query: {
+			organizationId,
+			filterField: "userId",
+			filterOperator: "eq",
+			filterValue: userId
+		},
+		headers
+	}), userId).filter((item) => item.tenant === organizationId), []);
+}
+async function loadMemberships(auth, session, user, userId, tenant, options) {
+	let members = parseMemberRows(session["members"] ?? session["member"] ?? user["members"], userId, false);
+	let teams = parseTeamRows(session["teamMembers"] ?? session["teams"] ?? user["teamMembers"], userId);
+	const headers = options.headers;
+	if (members.length === 0) {
+		const rows = options.memberships === "active" ? void 0 : await memberRows(auth, userId);
+		if (rows === void 0) {
+			const ids = await organizationIds(auth, tenant, options);
+			members = (await Promise.all(ids.map((id) => memberIn(auth, userId, id, tenant, headers)))).flat();
+		} else members = rows;
+	}
+	const listUserTeams = auth.api?.listUserTeams;
+	if (teams.length === 0 && listUserTeams !== void 0) teams = await settle(async () => parseTeamRows(await listUserTeams({ headers }), userId), []);
+	if (options.memberships === "active" && tenant !== void 0) {
+		members = members.filter((item) => item.tenant === tenant);
+		teams = teams.filter((item) => item.tenant === tenant);
+	}
+	return [...members, ...teams];
+}
+async function subjectFromBetterAuth(auth, session, options = {}) {
+	try {
+		if (session === null || session === void 0 || !isTrustedSession(session)) return anonymousSubject();
+		if (!isRecord(session["user"])) return anonymousSubject();
+		const user = session["user"];
+		const record = isRecord(session["session"]) ? session["session"] : void 0;
+		const id = typeof user["id"] === "string" ? user["id"] : void 0;
+		if (id === void 0 || id === "") return anonymousSubject();
+		const tenant = typeof record?.["activeOrganizationId"] === "string" ? record["activeOrganizationId"] : void 0;
+		const roles = asRoles(user["role"] ?? user["roles"]);
+		const declared = options.declared;
+		const globalRoles = declared === void 0 ? roles : roles.filter((role) => declared.includes(role));
+		const extra = options.schema === void 0 ? {} : validateClaims(extraFields(user), options.schema) ?? {};
+		const memberships = await loadMemberships(auth, session, user, id, tenant, options);
+		const principal = compact({
+			id,
+			kind: "user",
+			roles: globalRoles,
+			tenant,
+			memberships,
+			email: typeof user["email"] === "string" ? user["email"] : void 0,
+			claims: Object.keys(extra).length === 0 ? void 0 : extra
+		});
+		return freezeDeep(compact({
+			principal,
+			context: {},
+			session: typeof record?.["id"] === "string" ? record["id"] : void 0,
+			expiresAt: expiresAtSeconds(record?.["expiresAt"])
+		}));
+	} catch {
+		return anonymousSubject();
+	}
+}
+//#endregion
+export { betterAuthRoleSource, onRoleChange, rolesFromAccessControl, subjectFromBetterAuth };

package/dist/better-supabase/index.d.ts

@@ -0,0 +1,206 @@
+import { $t as CredentialPrincipal, Pr as Subject, ln as PermDock, nt as CredentialVerifier } from "../policy-CFZAr_Al.js";
+import { f as Permission, m as PermissionTree } from "../permissions-DttnqqxC.js";
+import { g as SupabaseSubjectOptions, m as SupabaseSessionLike, u as SupabasePrincipal } from "../types-yF5LmQVD.js";
+import { AuthorizationProvider } from "better-supabase/config";
+import { AccessTopicPolicy } from "better-supabase/realtime";
+import { AccessBucketPolicy } from "better-supabase/storage";
+import { ApiKey, ApiKeyClaimsOptions, ApiKeys } from "better-supabase/blocks/api-keys";
+import { CredentialProvider } from "better-supabase/credentials";
+import { ToolDecision, ToolRef } from "better-supabase/mcp";
+import { EntitlementClaimOptions } from "better-supabase/blocks/entitlements";
+import { AuthSession } from "better-supabase/server";
+//#region src/better-supabase/provider.d.ts
+type AuthorizationProviderOptions = {
+  /** `permdock.manifest.json`, parsed or as JSON text, from `permdock supabase inspect --out`. */
+  readonly manifest: unknown;
+  /**
+   * `permissions.catalog.json` from `permdock catalog`. Without it the
+   * provider lists no permissions, so better-supabase refuses every key in
+   * a bucket, topic or module check.
+   */
+  readonly catalog?: unknown;
+  /** The scope tenants are; defaults to the manifest's one root scope. */
+  readonly scope?: string;
+  /**
+   * The permission that lets a user decide a tool call waiting for approval
+   * in a tenant, for better-supabase's `canApprove`. The approver is never
+   * the user who asked (`approvals.distinctApprover`). Without it the chat's
+   * owner decides.
+   */
+  readonly approver?: Permission;
+};
+/**
+ * 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.
+ */
+export declare function authorizationProvider(options: AuthorizationProviderOptions): AuthorizationProvider;
+//#endregion
+//#region src/better-supabase/policies.d.ts
+type AccessPolicyOptions = {
+  /** `permdock.manifest.json`, parsed or as JSON text: it names the helpers' schema and the scopes. */
+  readonly manifest: unknown;
+  /** `permissions.catalog.json`: only keys it marks `rowConditions: false` are accepted. */
+  readonly catalog: unknown;
+  /** A scope in the manifest's `rls.scopes`, or `platform` for permissions granted globally. */
+  readonly scope: string;
+  /** 1-based path or topic segment holding the scope id; better-supabase's default is the `{organizationId}` segment. */
+  readonly segment?: number;
+};
+type BucketAccess = {
+  /** Downloads, signed URLs, renders and metadata reads. */
+  readonly read: Permission;
+  /** Listing; without it `read` covers listing too. */
+  readonly list?: Permission;
+  /** Uploads, updates and moves; also deletes unless `delete` is set. */
+  readonly write: Permission;
+  readonly delete?: Permission;
+};
+type TopicAccess = {
+  readonly receive: Permission;
+  /** Lets clients send on the topic. */
+  readonly send?: 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.
+ */
+export declare function bucketPolicy(access: BucketAccess, options: AccessPolicyOptions): AccessBucketPolicy;
+/** As {@link bucketPolicy}, for a better-supabase Realtime topic. */
+export declare function topicPolicy(access: TopicAccess, options: AccessPolicyOptions): AccessTopicPolicy;
+//#endregion
+//#region src/better-supabase/api-keys.d.ts
+/** The roles a tenant key holds in its tenant: a list, or one per key. */
+type ServiceRoles<K> = readonly string[] | ((key: K) => readonly string[]);
+type ApiKeyVerifierOptions = {
+  /** `createApiKeys()` over a service transport. */
+  readonly keys: Pick<ApiKeys, "verify">;
+  /**
+   * `permdock.manifest.json`, whose `rls.apiKeys.serviceRoles` is the
+   * default for `serviceRoles`.
+   */
+  readonly manifest?: unknown;
+  /**
+   * The roles a tenant key holds in its tenant, as a `service` principal.
+   * Without it or a manifest with `rls.apiKeys`, a tenant key verifies to
+   * `null`.
+   */
+  readonly serviceRoles?: ServiceRoles<ApiKey>;
+  /** The permissions `*` stands for. Without it, a key with `*` verifies to `null`. */
+  readonly allPermissions?: readonly Permission[];
+};
+/**
+ * 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.
+ */
+export declare function apiKeyVerifier(options: ApiKeyVerifierOptions): CredentialVerifier;
+/**
+ * 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`.
+ */
+export declare function apiKeyClaimOptions(manifest: unknown): Pick<ApiKeyClaimsOptions, "claim" | "tenantClaim">;
+//#endregion
+//#region src/better-supabase/credentials.d.ts
+type CredentialGuardOptions = {
+  /** The request's PermDock instance. */
+  readonly permdock: () => PermDock | Promise<PermDock>;
+  /** The permission that resolves a token or connects an account; decided on the ref. */
+  readonly use: Permission;
+  /** The permission that revokes a stored credential; defaults to `use`. */
+  readonly revoke?: Permission;
+};
+/**
+ * `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.
+ */
+export declare function credentialGuard(provider: CredentialProvider, options: CredentialGuardOptions): CredentialProvider;
+//#endregion
+//#region src/better-supabase/mcp.d.ts
+/** What better-supabase's `createMcp` hooks see of a tool. */
+type McpToolRef = Pick<ToolRef, "meta">;
+/** The outcome of better-supabase's `createMcp` `authorize` hook. */
+type McpToolDecision = ToolDecision;
+type ToolPolicyOptions<C> = {
+  /** The request's PermDock instance, from the hook's context. */
+  readonly permdock: (ctx: C) => PermDock | Promise<PermDock>;
+  /**
+   * The row an instance permission is decided on, from the validated
+   * arguments. Without it the call is decided without a row, which an
+   * instance permission with a row condition denies.
+   */
+  readonly data?: (ctx: C, tool: McpToolRef, args: unknown) => unknown;
+};
+type ToolPolicy<C> = {
+  readonly authorize: (ctx: C, tool: McpToolRef, args: unknown) => Promise<McpToolDecision>;
+  readonly visible: (ctx: C, tool: McpToolRef) => Promise<boolean>;
+};
+/**
+ * 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.
+ */
+export declare function toolPolicy<C>(options: ToolPolicyOptions<C>): ToolPolicy<C>;
+//#endregion
+//#region src/better-supabase/subject.d.ts
+/** An `AuthSession` of kind `apiKey`, from better-supabase's api-keys middleware. */
+type ApiKeySession = Extract<AuthSession, {
+  readonly kind: "apiKey";
+}>;
+type ApiKeySessionOptions = {
+  /** The definitions: the key's scopes become the subject's delegation, and `*` stands for all of them. */
+  readonly permissions: PermissionTree;
+  /** `permdock.manifest.json`, whose `rls.apiKeys.serviceRoles` is the default for `serviceRoles`. */
+  readonly manifest?: unknown;
+  /** The roles a tenant key holds in its tenant. Without it or a manifest with `rls.apiKeys`, a tenant key is anonymous. */
+  readonly serviceRoles?: ServiceRoles<ApiKeySession>;
+};
+/** The claim, and the short code better-supabase writes for each feature key. */
+type FeatureClaim = EntitlementClaimOptions;
+type BetterSupabaseSubjectOptions = Omit<SupabaseSubjectOptions, "plans"> & {
+  /** How `kind: 'apiKey'` sessions map. Without it they are anonymous. */
+  readonly apiKeys?: ApiKeySessionOptions;
+  /**
+   * The claim `principal.plans` reads: its name (default `features`), or
+   * `{ claim, keys }` with the same `entitlements.claim.keys` better-supabase
+   * writes short codes with, so `plans` holds the feature keys. A code
+   * without a key is dropped.
+   */
+  readonly plans?: string | FeatureClaim;
+};
+/**
+ * `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.
+ */
+export declare function subjectFromBetterSupabase(session: SupabaseSessionLike | ApiKeySession | null | undefined, options?: BetterSupabaseSubjectOptions): Subject<SupabasePrincipal> | Subject<CredentialPrincipal> | Subject;
+//#endregion
+export type { AccessPolicyOptions, ApiKeySession, ApiKeySessionOptions, ApiKeyVerifierOptions, AuthorizationProviderOptions, BetterSupabaseSubjectOptions, BucketAccess, CredentialGuardOptions, McpToolDecision, McpToolRef, ServiceRoles, SupabasePrincipal, ToolPolicy, ToolPolicyOptions, TopicAccess };