better-supabase 0.7.1 → 0.9.0

package/dist/access-sql-DUSSMaC3.js

@@ -0,0 +1,201 @@
+import { a as sqlString } from "./template-DdgYjIZ5.js";
+//#region src/core/access-sql.ts
+const SCOPE = /^[a-z][a-z0-9_]*$/;
+/** Whether `name` can be a scope: it is put unquoted into templates. */
+const isScopeName = (name) => SCOPE.test(name);
+/** The placeholders each authorization template may use. */
+const TEMPLATE_PLACEHOLDERS = {
+	idsWith: ["permission", "scope"],
+	isPlatform: ["permission"],
+	idsWithFor: [
+		"user",
+		"permission",
+		"scope"
+	],
+	isPlatformFor: ["user", "permission"],
+	memberIds: ["scope"],
+	memberIdsFor: ["user", "scope"],
+	canAssign: [
+		"role",
+		"tenant",
+		"scope"
+	],
+	canAssignFor: [
+		"user",
+		"role",
+		"tenant",
+		"scope"
+	],
+	permissionsFor: [
+		"user",
+		"tenant",
+		"scope"
+	],
+	canApprove: [
+		"tool",
+		"tenant",
+		"scope"
+	],
+	isApprover: [
+		"kind",
+		"subject",
+		"tenant",
+		"requester",
+		"scope"
+	],
+	holdersOf: [
+		"permission",
+		"tenant",
+		"scope"
+	],
+	actorMayWrite: [],
+	permitted: [
+		"permission",
+		"id",
+		"tenant",
+		"resource",
+		"scope"
+	]
+};
+/** The Postgres types a scope's ids can have. */
+const SCOPE_ID_TYPES = [
+	"uuid",
+	"text",
+	"bigint",
+	"integer"
+];
+/**
+* What is wrong with a provider's scopes: an unknown tenant scope or
+* parent, a parent cycle, an id type outside `SCOPE_ID_TYPES`, or a tenant
+* scope without one.
+*/
+function scopeProblems(provider) {
+	const problems = [];
+	const byName = new Map(provider.scopes.map((scope) => [scope.name, scope]));
+	for (const scope of provider.scopes) {
+		if (scope.idType !== void 0 && !SCOPE_ID_TYPES.includes(scope.idType)) problems.push(`scope "${scope.name}" has idType "${scope.idType}"; use ${SCOPE_ID_TYPES.join(", ")}`);
+		if (scope.parent !== void 0 && !byName.has(scope.parent)) problems.push(`scope "${scope.name}" has parent "${scope.parent}", which is not a scope`);
+	}
+	const cyclic = /* @__PURE__ */ new Set();
+	for (const scope of provider.scopes) {
+		const seen = /* @__PURE__ */ new Set();
+		let current = scope.name;
+		while (current !== void 0 && !seen.has(current)) {
+			seen.add(current);
+			current = byName.get(current)?.parent;
+		}
+		if (current !== void 0 && !cyclic.has(current)) {
+			for (const name of seen) cyclic.add(name);
+			problems.push(`scope "${current}" is its own ancestor (a parent cycle)`);
+		}
+	}
+	const tenant = byName.get(provider.tenantScope);
+	if (tenant === void 0) problems.push(`tenantScope "${provider.tenantScope}" is not a scope`);
+	else if (tenant.idType === void 0) problems.push(`tenant scope "${tenant.name}" has no idType`);
+	return problems;
+}
+const CALL_KEYWORDS = /* @__PURE__ */ new Set([
+	"all",
+	"and",
+	"any",
+	"array",
+	"as",
+	"cast",
+	"coalesce",
+	"exists",
+	"from",
+	"greatest",
+	"in",
+	"is",
+	"least",
+	"not",
+	"nullif",
+	"on",
+	"or",
+	"row",
+	"select",
+	"some",
+	"values",
+	"when",
+	"where"
+]);
+/**
+* What makes a template unsafe to put into generated SQL: a `$$`, `;` or
+* `--` (outside string literals), or a function call without a schema.
+*/
+function templateProblems(template) {
+	const code = template.replaceAll(/'(?:[^']|'')*'/g, "''").replaceAll(/\{(\w+)\}/g, "$1");
+	const problems = [];
+	for (const token of [
+		"$$",
+		";",
+		"--"
+	]) if (code.includes(token)) problems.push(`contains "${token}"`);
+	for (const match of code.matchAll(/(?<![\w$.":])"?([a-z_][\w$]*)"?\s*\(/gi)) {
+		const name = match[1];
+		if (CALL_KEYWORDS.has(name.toLowerCase())) continue;
+		problems.push(`calls ${name}() without a schema`);
+	}
+	return problems;
+}
+/** The `{name}` placeholders in a template. */
+const templatePlaceholders = (template) => [...new Set([...template.matchAll(/\{(\w+)\}/g)].map((match) => match[1]))];
+/**
+* Fills a template's `{name}` placeholders. `where` names the setting in
+* the error for a placeholder `values` doesn't have.
+*/
+function fillTemplate(where, template, values) {
+	return template.replaceAll(/\{(\w+)\}/g, (match, name) => {
+		const value = values[name];
+		if (value === void 0) throw new TypeError(`${where}: ${match} is not available here. Use ${Object.keys(values).map((key) => `{${key}}`).join(", ")}`);
+		return value;
+	});
+}
+/** The `schema.name` of every schema-qualified function a template calls, with `{scope}` filled. */
+function templateFunctions(template, scope) {
+	const filled = scope === void 0 ? template : template.replaceAll("{scope}", scope);
+	return [...new Set([...filled.matchAll(/(?<![\w$."])"?([a-z_][\w$]*)"?\s*\.\s*"?([a-z_][\w${}]*)"?\s*\(/gi)].map((match) => `${match[1]}.${match[2]}`))];
+}
+/**
+* `target` with `sql: "provider"` replaced by the provider's `idsWith` and
+* `isPlatform`. `where` names the policy in the error when there is no
+* provider.
+*/
+function resolveProviderSql(where, target, functions) {
+	if (target.sql !== "provider") return target;
+	if (functions === void 0) throw new TypeError(`${where}: sql "provider" needs \`authorization\` in better-supabase.config.ts`);
+	return {
+		...target,
+		sql: {
+			idsWith: functions.idsWith,
+			isPlatform: functions.isPlatform
+		}
+	};
+}
+/**
+* The SQL condition for one permission key of an access policy. `id` is the
+* text expression holding the scope id, compared as text so a malformed path
+* never raises a cast error. Without `sql` it calls the access contract
+* (`tenant_ids_with`, `is_platform`); with it, the templates.
+*/
+function accessCheck(where, target, key, id) {
+	if (key === "") throw new TypeError(`${where}: a permission key is empty`);
+	const scope = target.scope ?? "tenant";
+	const permission = sqlString(key);
+	if (target.sql === "provider") throw new TypeError(`${where}: sql "provider" needs the config's authorization provider; write the policy with \`better-supabase gen\` or pass its templates`);
+	if (!target.sql) {
+		if (scope === "platform") return `(select better_supabase.is_platform(${permission}))`;
+		if (scope !== "tenant") throw new TypeError(`${where}: scope "${scope}" needs sql templates; without them use "tenant" or "platform"`);
+		if (id === void 0) throw new TypeError(`${where}: scope "tenant" needs a segment`);
+		return `${id} in (select t::text from better_supabase.tenant_ids_with(${permission}) t)`;
+	}
+	if (scope === "platform") return `(select ${fillTemplate(`${where} sql.isPlatform`, target.sql.isPlatform, { permission })})`;
+	if (!isScopeName(scope)) throw new TypeError(`${where}: invalid scope "${scope}"`);
+	if (id === void 0) throw new TypeError(`${where}: scope "${scope}" needs a segment`);
+	return `${id} in (select t.id::text from ${fillTemplate(`${where} sql.idsWith`, target.sql.idsWith, {
+		permission,
+		scope
+	})} as t(id))`;
+}
+//#endregion
+export { isScopeName as a, templateFunctions as c, fillTemplate as i, templatePlaceholders as l, TEMPLATE_PLACEHOLDERS as n, resolveProviderSql as o, accessCheck as r, scopeProblems as s, SCOPE_ID_TYPES as t, templateProblems as u };

package/dist/actor-BAhb-d1S.d.ts

@@ -0,0 +1,104 @@
+//#region src/auth/actor.d.ts
+/** One level of an RFC 8693 `act` chain: who acts, and who acted before it. */
+interface ActClaim {
+  readonly sub: string;
+  readonly act?: ActClaim;
+  readonly [claim: string]: unknown;
+}
+/**
+ * Who acts for the user, from the outermost level of the RFC 8693 `act`
+ * claim, by its `kind`:
+ *
+ * - `oauth-client`: an `act` without `kind` (prior actors stay on `chain`),
+ *   else the OAuth `client_id` of a Supabase OAuth server token. Only this
+ *   kind is limited to the scopes the user delegated.
+ * - `support`: an admin in a support session (`act.kind: "support"`, from
+ *   `supportClaims`). An `act` without `kind` but with `session_id`, as
+ *   0.5.0 minted it, is an invalid chain.
+ * - `impersonation`: an admin acting as the user (`act.kind:
+ *   "impersonation"`, from `actClaim`).
+ * - `agent`: an AI agent running tools for the user (`act.kind: "agent"`,
+ *   from `agentClaims`). Its writes run under the user's permissions, and
+ *   a token that also carries a `scope` limits it to those scopes.
+ */
+type SessionActor = {
+  readonly kind: "oauth-client";
+  readonly id: string;
+  readonly chain?: ActClaim;
+} | {
+  readonly kind: "support";
+  readonly id: string;
+  readonly sessionId: string;
+  /** `act.read_only`; a support token without it is read-only. */
+  readonly readOnly: boolean;
+  readonly reason?: string;
+} | {
+  readonly kind: "impersonation";
+  readonly id: string;
+  readonly reason?: string;
+} | {
+  readonly kind: "agent";
+  readonly id: string;
+  /**
+   * `act.tools`: the tools the run may call. Missing means every tool;
+   * `[]` means none.
+   */
+  readonly tools?: readonly string[];
+  /** `act.read_only`; an agent without it may write as the user. */
+  readonly readOnly: boolean;
+  /** The full `act` level, with whoever acted before the agent. */
+  readonly chain: ActClaim;
+};
+/** What the user delegated to the actor: the token's OAuth `scope`. */
+interface SessionDelegation {
+  readonly scopes: readonly string[];
+  readonly chain?: ActClaim;
+}
+type ActorOutcome = {
+  readonly ok: true;
+  readonly actor?: SessionActor;
+} | {
+  readonly ok: false;
+  readonly reason: "invalid-chain";
+};
+/**
+ * Reads only `act` and `client_id`. An
+ * `act` that is not a chain of objects each with a non-empty `sub`, a
+ * `kind` other than `support`, `impersonation` or `agent`, a support level
+ * without a `session_id`, an agent level whose `tools` is not a list of
+ * names, a non-boolean `read_only` on a support or agent level, or a
+ * `session_id` without `kind` is `{ ok: false }`: the session must not pass as the user
+ * alone.
+ */
+declare function actorOf(claims: Readonly<Record<string, unknown>>): ActorOutcome;
+/** `agentClaims(claims, { agent, tools, readOnly })`: the agent that acts, and what it may do. */
+interface AgentActOptions {
+  readonly agent: string;
+  /** The tools the run may call. Leave it out for every tool; `[]` allows none. */
+  readonly tools?: readonly string[];
+  /** Writes `read_only: true`, so `actor_may_write()` refuses the run's writes. */
+  readonly readOnly?: boolean;
+}
+/**
+ * The user's claims with the agent as the outermost `act` level. An `act`
+ * already on the claims (an OAuth client, say) moves below it, so the run
+ * keeps the user's delegation. Pass the result to `asUser` or `forContext`
+ * for the agent's database calls.
+ */
+declare function agentClaims<C extends Readonly<Record<string, unknown>>>(claims: C, options: AgentActOptions): C & {
+  readonly act: ActClaim;
+};
+/**
+ * OpenID Connect scopes that ask for identity claims or a refresh token.
+ * They grant no permission, so `delegationOf` leaves them out.
+ */
+declare const IDENTITY_SCOPES: ReadonlySet<string>;
+/**
+ * The OAuth `scope` claim (a space-separated string or a list), without
+ * `IDENTITY_SCOPES`. `undefined` when the token names no scope. A token
+ * that names only identity scopes gets `{ scopes: [] }`, so an actor
+ * limited to its delegation stays limited.
+ */
+declare function delegationOf(claims: Readonly<Record<string, unknown>>): SessionDelegation | undefined;
+//#endregion
+export { SessionActor as a, agentClaims as c, IDENTITY_SCOPES as i, delegationOf as l, ActorOutcome as n, SessionDelegation as o, AgentActOptions as r, actorOf as s, ActClaim as t };

package/dist/actor-KHDOKGb1.js

@@ -0,0 +1,151 @@
+import { n as dbError } from "./errors-8i6tSICm.js";
+import { n as isRecord } from "./guards-6F2bCtQR.js";
+//#region src/auth/actor.ts
+function copyAct(level) {
+	const entries = Object.entries(level).map(([key, value]) => [key, key === "act" && isRecord(value) ? copyAct(value) : value]);
+	return Object.fromEntries(entries);
+}
+function isString(value) {
+	return typeof value === "string";
+}
+const INVALID = {
+	ok: false,
+	reason: "invalid-chain"
+};
+function actorAt(outer, id) {
+	const kind = outer["kind"];
+	const sessionId = outer["session_id"];
+	const readOnly = outer["read_only"];
+	const reason = outer["reason"];
+	if (kind === "support") {
+		if (typeof sessionId !== "string" || sessionId === "") return INVALID;
+		if (readOnly !== void 0 && typeof readOnly !== "boolean") return INVALID;
+		return {
+			ok: true,
+			actor: {
+				kind: "support",
+				id,
+				sessionId,
+				readOnly: readOnly ?? true,
+				...typeof reason === "string" ? { reason } : {}
+			}
+		};
+	}
+	if (kind === "impersonation") return {
+		ok: true,
+		actor: {
+			kind: "impersonation",
+			id,
+			...typeof reason === "string" ? { reason } : {}
+		}
+	};
+	if (kind === "agent") {
+		if (sessionId !== void 0) return INVALID;
+		const tools = outer["tools"];
+		if (readOnly !== void 0 && typeof readOnly !== "boolean") return INVALID;
+		if (tools !== void 0 && !(Array.isArray(tools) && tools.every((tool) => typeof tool === "string" && tool !== ""))) return INVALID;
+		return {
+			ok: true,
+			actor: {
+				kind: "agent",
+				id,
+				...Array.isArray(tools) ? { tools: tools.filter(isString) } : {},
+				readOnly: readOnly ?? false,
+				chain: copyAct(outer)
+			}
+		};
+	}
+	if (kind !== void 0 || sessionId !== void 0) return INVALID;
+	return {
+		ok: true,
+		actor: {
+			kind: "oauth-client",
+			id,
+			chain: copyAct(outer)
+		}
+	};
+}
+/**
+* Reads only `act` and `client_id`. An
+* `act` that is not a chain of objects each with a non-empty `sub`, a
+* `kind` other than `support`, `impersonation` or `agent`, a support level
+* without a `session_id`, an agent level whose `tools` is not a list of
+* names, a non-boolean `read_only` on a support or agent level, or a
+* `session_id` without `kind` is `{ ok: false }`: the session must not pass as the user
+* alone.
+*/
+function actorOf(claims) {
+	const outer = claims["act"];
+	if (outer !== void 0) {
+		if (!isRecord(outer)) return INVALID;
+		const id = outer["sub"];
+		if (typeof id !== "string" || id === "") return INVALID;
+		let level = outer["act"];
+		while (level !== void 0) {
+			if (!isRecord(level)) return INVALID;
+			const sub = level["sub"];
+			if (typeof sub !== "string" || sub === "") return INVALID;
+			level = level["act"];
+		}
+		return actorAt(outer, id);
+	}
+	const client = claims["client_id"];
+	if (typeof client === "string" && client !== "") return {
+		ok: true,
+		actor: {
+			id: client,
+			kind: "oauth-client"
+		}
+	};
+	return { ok: true };
+}
+/**
+* The user's claims with the agent as the outermost `act` level. An `act`
+* already on the claims (an OAuth client, say) moves below it, so the run
+* keeps the user's delegation. Pass the result to `asUser` or `forContext`
+* for the agent's database calls.
+*/
+function agentClaims(claims, options) {
+	const prior = claims["act"];
+	const act = {
+		kind: "agent",
+		sub: options.agent,
+		...options.tools === void 0 ? {} : { tools: [...options.tools] },
+		...options.readOnly === void 0 ? {} : { read_only: options.readOnly },
+		...isRecord(prior) ? { act: copyAct(prior) } : {}
+	};
+	return {
+		...claims,
+		act
+	};
+}
+/** The 401 for a session whose `act` claim `actorOf` refuses (`ACTOR_INVALID`). */
+function invalidActorError() {
+	return dbError("unauthorized", "The token's act claim is not a valid chain of actors: every level needs a sub, and kind must be support, impersonation, agent or absent", { code: "ACTOR_INVALID" });
+}
+/**
+* OpenID Connect scopes that ask for identity claims or a refresh token.
+* They grant no permission, so `delegationOf` leaves them out.
+*/
+const IDENTITY_SCOPES = /* @__PURE__ */ new Set([
+	"openid",
+	"email",
+	"profile",
+	"phone",
+	"address",
+	"offline_access"
+]);
+/**
+* The OAuth `scope` claim (a space-separated string or a list), without
+* `IDENTITY_SCOPES`. `undefined` when the token names no scope. A token
+* that names only identity scopes gets `{ scopes: [] }`, so an actor
+* limited to its delegation stays limited.
+*/
+function delegationOf(claims) {
+	const scope = claims["scope"];
+	const named = typeof scope === "string" ? scope.split(/\s+/u).filter(Boolean) : Array.isArray(scope) ? scope.filter((item) => typeof item === "string" && item !== "") : [];
+	if (named.length === 0) return;
+	return { scopes: named.filter((item) => !IDENTITY_SCOPES.has(item)) };
+}
+//#endregion
+export { invalidActorError as a, delegationOf as i, actorOf as n, agentClaims as r, IDENTITY_SCOPES as t };