better-supabase 0.14.0 → 0.15.1

package/dist/authorization-hooks-D_pwXlBs.d.ts

@@ -0,0 +1,221 @@
+import { Ft as RequestContext } from "./types-DFdg_4yN.js";
+import { r as AuthState } from "./resolve-CXX6DHv3.js";
+//#region src/core/contracts/authorization-hooks.d.ts
+/**
+ * An email address or chat user, as a bot or a mail webhook sees it. The value
+ * is what the platform reports; it names no one until an identity link maps it
+ * to a user or a contact.
+ */
+interface IdentityRef {
+  readonly kind: "email" | "chat";
+  /** `slack`, `teams`, `whatsapp`, an email provider; unset for a plain address. */
+  readonly provider?: string;
+  /** The address (lower case) or the platform's user id. */
+  readonly value: string;
+  /** The platform workspace, such as a Slack team id. */
+  readonly workspace?: string;
+}
+/** Where an identity link points: an app user or a contact the app stores. */
+type IdentityTarget = {
+  readonly kind: "user";
+  readonly userId: string;
+} | {
+  readonly kind: "contact";
+  readonly contactId: string;
+};
+/**
+ * Looks up the verified link for an identity. `null` for an identity no
+ * signed-in link flow or verified address created; the caller then treats the
+ * author as anonymous.
+ */
+type PrincipalByIdentity = (identity: IdentityRef) => IdentityTarget | null | Promise<IdentityTarget | null>;
+/** The fields of an event a subscriber check reads. */
+interface SubscriberEvent {
+  readonly type: string;
+  readonly tenant: string | null;
+  /** The user who caused the event, or `null` for service work. */
+  readonly actorId: string | null;
+  readonly payload: unknown;
+  /** The event's subject, such as `invoices/123`, when it has one. */
+  readonly subject?: string | null;
+}
+/**
+ * A subscription a fan-out may deliver to. `principal` is the user who owns it,
+ * or the id of the service principal an organization-owned subscription runs as
+ * (`kind: "service"`).
+ */
+interface Subscriber {
+  readonly principal: string;
+  readonly kind?: "user" | "service";
+}
+/**
+ * Narrows a fan-out to the subscribers that may read the event: webhook
+ * endpoints, outbox consumers, realtime members and notification recipients. It
+ * returns a subset of `subscribers`; a subscriber it leaves out gets nothing,
+ * and a throw or rejection delivers to no one.
+ */
+type SubscriberPolicy = <S extends Subscriber>(event: SubscriberEvent, subscribers: readonly S[]) => readonly S[] | Promise<readonly S[]>;
+/** A request that waits for someone other than the requester to approve it. */
+interface ApprovalRequestRef {
+  /** `ai-tool` (an AI tool call), `support-session`, or the app's own kind. */
+  readonly kind: string;
+  /** The tool name for `ai-tool`, the request id for `support-session`. */
+  readonly subject: string;
+  readonly tenant?: string;
+  /** The user who asked; never their own approver. */
+  readonly requester?: string;
+}
+/** The signed-in user who would approve, with their verified claims. */
+interface Approver {
+  readonly userId: string;
+  readonly claims: Readonly<Record<string, unknown>>;
+}
+/**
+ * Whether `approver` may decide `request`. The SQL side is the `isApprover`
+ * template of the authorization provider; this is the same decision for server
+ * code. A throw counts as `false`, and better-supabase refuses the requester
+ * before it asks.
+ */
+type ApproverOf = (approver: Approver, request: ApprovalRequestRef) => boolean | Promise<boolean>;
+/** What `mayPublish` and `runAs` get about a published automation. */
+interface AutomationRef {
+  /** The user who published it, or `null` for an organization-owned automation. */
+  readonly publisher: string | null;
+  readonly tenant: string | null;
+  /** The permissions its nodes need, as stored at publish. */
+  readonly permissions: readonly string[];
+}
+/** How a provider decides published automations (workflow builder versions). */
+interface AutomationHooks {
+  /** Whether the publisher may publish a version whose nodes need `permissions`. */
+  readonly mayPublish?: (automation: AutomationRef & {
+    readonly claims: Readonly<Record<string, unknown>>;
+  }) => boolean | Promise<boolean>;
+  /**
+   * The claims a step of a published version runs with: the publisher's current
+   * claims narrowed to `permissions`, or the service principal's for an
+   * organization-owned automation. `null` when the publisher is gone, suspended
+   * or no longer holds a stored permission; the step then fails and never falls
+   * back to the service role.
+   *
+   * Put the cap under `PERMISSION_CAP_CLAIM` (`bsb_permission_cap`, from
+   * `better-supabase/server`): `cap_allows` refuses every key outside it. 0.15
+   * still reads the 0.14 name, `bs_permission_cap`, and warns once.
+   */
+  readonly runAs?: (automation: AutomationRef) => Readonly<Record<string, unknown>> | null | Promise<Readonly<Record<string, unknown>> | null>;
+}
+/**
+ * Turns an opaque run ticket back into the context a job or a workflow step
+ * runs as. `null` or a throw refuses the ticket (expired, revoked, or for a
+ * principal that is gone), and the run fails instead of running as anyone else.
+ * The ticket is stored in plain text as a run attribute, so it is an id the
+ * provider looks up, never a bearer secret.
+ */
+type TicketSubject = (ticket: string) => RequestContext | null | Promise<RequestContext | null>;
+/**
+ * A delegated token, as `forContext` sees it: an OAuth client or agent acting
+ * for a user.
+ */
+interface DelegationRef {
+  readonly userId: string;
+  readonly tenant?: string;
+  /** The OAuth client, when the token has a `client_id`. */
+  readonly clientId?: string;
+  /** The scopes the user granted, split on spaces. */
+  readonly scopes: readonly string[];
+  /** RFC 9396 `authorization_details`, when the token has them. */
+  readonly authorizationDetails?: readonly {
+    readonly type: string;
+    readonly [field: string]: unknown;
+  }[];
+}
+/**
+ * The permission keys a delegated token may use, for scopes the provider maps
+ * at runtime (`authorization.delegation.scopes` is the static form in SQL).
+ * `forContext` caps the work to them, narrowed by its own `permissions`; a
+ * throw grants nothing.
+ */
+type DelegationPermissions = (delegation: DelegationRef) => readonly string[] | Promise<readonly string[]>;
+/** A button a chat user pressed on a message the app sent. */
+interface ChatAction {
+  /** The action id the card declared, such as `approve`. */
+  readonly id: string;
+  readonly value?: string;
+  /** The chat user, as the platform reports them. */
+  readonly author: IdentityRef;
+}
+/**
+ * Decides a chat action for its linked author: `undefined` when the provider
+ * does not handle the action. An approval button is decided here, through the
+ * provider; an unlinked author is refused.
+ */
+type ChatActionHook = (action: ChatAction, author: IdentityTarget | null) => {
+  readonly allowed: boolean;
+  readonly userId?: string;
+} | undefined | Promise<{
+  readonly allowed: boolean;
+  readonly userId?: string;
+} | undefined>;
+/** A support session start the `authorize` hook decides. */
+interface SupportAuthorizeInput {
+  readonly admin: Extract<AuthState, {
+    kind: "user";
+  }>;
+  readonly targetUserId: string;
+  /** Never empty: a start without a reason is refused before `authorize` runs. */
+  readonly reason: string;
+  readonly readOnly: boolean;
+  readonly tenant?: string;
+  readonly metadata: Readonly<Record<string, unknown>>;
+}
+/**
+ * `true` allows a support start that still needs a second approver unless
+ * approval is off; `{ approvedBy }` allows it and names the distinct approver
+ * the provider checked. `false`, a throw and an `approvedBy` equal to the admin
+ * refuse it.
+ */
+type SupportDecision = boolean | {
+  readonly approvedBy: string;
+};
+/** Decides a support session start. */
+type SupportAuthorize = (input: SupportAuthorizeInput) => SupportDecision | Promise<SupportDecision>;
+/**
+ * The runtime half of an authorization provider (`apiVersion: 1`). The
+ * `authorization` config key is plain data for SQL; these hooks decide the same
+ * things in server code, so one provider can own automations, support sessions,
+ * delivery, identity links, chat actions, approvals and delegated tokens end to
+ * end. Every hook is optional, and a slot passed to a block directly wins over
+ * the hook.
+ */
+interface AuthorizationHooks {
+  readonly apiVersion: 1;
+  /** The provider's name, for messages. */
+  readonly name: string;
+  readonly automation?: AutomationHooks;
+  readonly support?: {
+    readonly authorize: SupportAuthorize;
+  };
+  readonly delivery?: {
+    /** Webhook endpoints, outbox consumers and realtime members. */
+    readonly subscribers?: SubscriberPolicy;
+    /** Notification recipients. */
+    readonly audience?: SubscriberPolicy;
+  };
+  readonly identities?: {
+    readonly principalByIdentity: PrincipalByIdentity;
+  };
+  readonly chat?: {
+    readonly onAction?: ChatActionHook;
+  };
+  readonly approverOf?: ApproverOf;
+  readonly tickets?: {
+    readonly subject: TicketSubject;
+  };
+  readonly delegation?: {
+    readonly permissions: DelegationPermissions;
+  };
+}
+/** Types `hooks` and freezes it; better-supabase never mutates a provider. */
+declare function defineAuthorizationHooks<const H extends AuthorizationHooks>(hooks: H): H;
+//#endregion
+export { SupportAuthorize as _, AutomationHooks as a, TicketSubject as b, ChatActionHook as c, IdentityRef as d, IdentityTarget as f, SubscriberPolicy as g, SubscriberEvent as h, AuthorizationHooks as i, DelegationPermissions as l, Subscriber as m, Approver as n, AutomationRef as o, PrincipalByIdentity as p, ApproverOf as r, ChatAction as s, ApprovalRequestRef as t, DelegationRef as u, SupportAuthorizeInput as v, defineAuthorizationHooks as x, SupportDecision as y };

package/dist/authorizer-B6X09otb.d.ts

@@ -0,0 +1,118 @@
+//#region src/core/authorizer.d.ts
+type JsonObject = Readonly<Record<string, unknown>>;
+/** Who asks (AuthZEN Subject). Always built from the verified request context. */
+interface AuthorizationSubject {
+  /**
+   * `user`, `service`, `anon`, or `agent` for a delegated token with an `act`
+   * chain.
+   */
+  readonly type: string;
+  readonly id: string;
+  /**
+   * `role`, `email` and `impersonator` when set, and `claims`: the verified
+   * access-token claims (a frozen copy, including what a token hook wrote, such
+   * as `memberships`, `roles` and `act`). The client never supplies them.
+   * Anonymous subjects have no properties.
+   */
+  readonly properties?: JsonObject;
+}
+/** What is acted on (AuthZEN Resource): a table, a topic or an action's target. */
+interface AuthorizationResource {
+  readonly type: string;
+  readonly id?: string;
+  /** The row, for decisions that read it (`get`, `update`, `delete`). */
+  readonly properties?: JsonObject;
+}
+/**
+ * One access request, in the AuthZEN Authorization API 1.0 information model
+ * (`SPEC_PINS.authzen`): subject, action, resource and context. `action` is the
+ * permission reference the authorizer understands.
+ */
+interface AuthorizationRequest<Ref = string> {
+  readonly subject: AuthorizationSubject;
+  readonly action: Ref;
+  readonly resource: AuthorizationResource;
+  /** The tenant, assurance level and scopes of the request. */
+  readonly context: JsonObject;
+}
+type AuthorizationOutcome = {
+  readonly outcome: "granted";
+  readonly context?: JsonObject;
+} | {
+  readonly outcome: "denied";
+  readonly reason?: string;
+  readonly context?: JsonObject;
+} | {
+  readonly outcome: "approval-required";
+  readonly approval?: {
+    readonly id: string;
+  };
+  readonly context?: JsonObject;
+};
+/**
+ * A runtime authorization decision point (API v1). Authorization libraries ship
+ * an adapter that implements it; better-supabase builds every request and fails
+ * closed on anything but `granted`.
+ */
+interface Authorizer<Ref = string> {
+  readonly apiVersion: 1;
+  readonly name: string;
+  /** The stable key of a permission reference, for specs, SQL and messages. */
+  key(ref: Ref): string;
+  /**
+   * The default permission for a table operation; lets `permissions: true`
+   * work.
+   */
+  forOperation?(table: string, operation: string): Ref | undefined;
+  evaluate(request: AuthorizationRequest<Ref>, runtime?: AuthorizerRuntime): AuthorizationOutcome | Promise<AuthorizationOutcome>;
+  /**
+   * The batch form (AuthZEN Access Evaluations); results keep the request
+   * order.
+   */
+  evaluations?(requests: readonly AuthorizationRequest<Ref>[], runtime?: AuthorizerRuntime): Promise<readonly AuthorizationOutcome[]>;
+}
+/**
+ * A process-wide cache of authorization versions per user, owned by the
+ * authorization library and typed structurally here. Create it once at module
+ * scope and pass it to `createServer({ versions })`; never per request or per
+ * cache scope.
+ */
+interface AuthzVersionCache {
+  /** Forgets a user's version, so the next decision reads it again. */
+  evict(userId: string): void | PromiseLike<void>;
+}
+/**
+ * Work shared within one request scope: the caller creates it and passes it in,
+ * so nothing request-specific lives in module state. Each `use cache` scope
+ * gets its own; sharing across scopes goes through `AuthzVersionCache`.
+ */
+interface RequestMemo {
+  /** `load()`'s promise, run once per key for this memo. */
+  once<T>(key: string, load: () => Promise<T>): Promise<T>;
+}
+/** A new memo for one request scope. */
+declare function requestMemo(): RequestMemo;
+/**
+ * What better-supabase hands an authorizer next to each request. Optional, so
+ * authorizers written for API v1 keep working.
+ */
+interface AuthorizerRuntime {
+  /** `ServerOptions.versions`, when the server has one. */
+  readonly versions?: AuthzVersionCache;
+  /** The scope's memo, for reads several checks in one scope share. */
+  readonly memo?: RequestMemo;
+}
+/**
+ * `authorizer` with `runtime` merged under the runtime of every call, so a
+ * server's `versions` reaches each decision.
+ */
+declare function bindAuthorizer<A extends AnyAuthorizer | undefined>(authorizer: A, runtime: AuthorizerRuntime): A;
+type AnyAuthorizer = Authorizer<any>;
+/** The permission reference type of an authorizer, `string` without one. */
+type PermissionRef<A> = A extends Authorizer<infer R> ? R : string;
+/** Identity helper that fixes `apiVersion` and infers `Ref`. */
+declare function defineAuthorizer<Ref = string>(authorizer: Omit<Authorizer<Ref>, "apiVersion"> & {
+  readonly apiVersion?: 1;
+}): Authorizer<Ref>;
+//#endregion
+export { AuthorizationSubject as a, AuthzVersionCache as c, bindAuthorizer as d, defineAuthorizer as f, AuthorizationResource as i, PermissionRef as l, AuthorizationOutcome as n, Authorizer as o, requestMemo as p, AuthorizationRequest as r, AuthorizerRuntime as s, AnyAuthorizer as t, RequestMemo as u };

package/dist/authorizer-BGhXaDmo.js

@@ -0,0 +1,172 @@
+import { n as deepFreeze, r as isPlainObject, t as cloneValue } from "./clone-CkG0-hlI.js";
+import { n as dbError } from "./errors-BVFgt8BZ.js";
+import { a as ok, r as err } from "./result-ntFBW2p2.js";
+//#region src/core/authorizer.ts
+/**
+* Runs `evaluate`, passing the runtime only when there is one, so authorizers
+* written before it see the call they always did.
+*/
+async function evaluateWith(authorizer, request, runtime) {
+	return runtime ? authorizer.evaluate(request, runtime) : authorizer.evaluate(request);
+}
+/** Whether `value` is a `RequestMemo`. */
+function isRequestMemo(value) {
+	return typeof value === "object" && value !== null && "once" in value && typeof value.once === "function";
+}
+/** A new memo for one request scope. */
+function requestMemo() {
+	const entries = /* @__PURE__ */ new Map();
+	return { once(key, load) {
+		const known = entries.get(key);
+		if (known) return known;
+		const promise = load();
+		entries.set(key, promise);
+		promise.catch(() => {
+			entries.delete(key);
+		});
+		return promise;
+	} };
+}
+/**
+* `authorizer` with `runtime` merged under the runtime of every call, so a
+* server's `versions` reaches each decision.
+*/
+function bindAuthorizer(authorizer, runtime) {
+	if (!authorizer || runtime.versions === void 0) return authorizer;
+	const inner = authorizer;
+	const merged = (call) => ({
+		...runtime,
+		...call
+	});
+	const evaluations = inner.evaluations?.bind(inner);
+	const forOperation = inner.forOperation?.bind(inner);
+	return {
+		apiVersion: inner.apiVersion,
+		name: inner.name,
+		key: (ref) => inner.key(ref),
+		...forOperation ? { forOperation } : {},
+		evaluate: (request, call) => inner.evaluate(request, merged(call)),
+		...evaluations ? { evaluations: (requests, call) => evaluations(requests, merged(call)) } : {}
+	};
+}
+/** Identity helper that fixes `apiVersion` and infers `Ref`. */
+function defineAuthorizer(authorizer) {
+	return {
+		...authorizer,
+		apiVersion: 1
+	};
+}
+const ANONYMOUS = {
+	type: "anon",
+	id: "anonymous"
+};
+function scopesOf(claims) {
+	const scope = claims?.["scope"];
+	return typeof scope === "string" ? scope.split(" ").filter(Boolean) : [];
+}
+/** A frozen copy of the verified claims, so an authorizer cannot change them. */
+function claimsProperty(claims) {
+	if (!isPlainObject(claims)) return {};
+	return { claims: deepFreeze(cloneValue(claims)) };
+}
+/** The subject and context of a request, from the verified context only. */
+function requestOf(context) {
+	const actor = context?.actor;
+	const claims = context?.claims;
+	const act = claims?.["act"];
+	const subject = actor ? {
+		type: typeof act === "object" && act !== null && actor.kind === "user" ? "agent" : actor.kind,
+		id: actor.id,
+		properties: {
+			...actor.role === void 0 ? {} : { role: actor.role },
+			...actor.email === void 0 ? {} : { email: actor.email },
+			...actor.impersonator === void 0 ? {} : { impersonator: actor.impersonator },
+			...claimsProperty(claims)
+		}
+	} : ANONYMOUS;
+	const aal = claims?.["aal"];
+	return {
+		subject,
+		context: {
+			...context?.tenant === void 0 ? {} : { tenant: context.tenant },
+			...typeof aal === "string" ? { aal } : {},
+			scopes: scopesOf(claims)
+		}
+	};
+}
+function isOutcome(value) {
+	if (typeof value !== "object" || value === null || !("outcome" in value)) return false;
+	const { outcome } = value;
+	return outcome === "granted" || outcome === "denied" || outcome === "approval-required";
+}
+/** The `forbidden` error for an outcome other than `granted`, or `undefined`. */
+function outcomeError(outcome, permission) {
+	if (!isOutcome(outcome)) return dbError("forbidden", `The authorizer gave no decision for ${permission}`, {
+		code: "PERMISSION_DENIED",
+		permission
+	});
+	switch (outcome.outcome) {
+		case "granted": return;
+		case "denied": return dbError("forbidden", outcome.reason ?? `Permission ${permission} is required`, {
+			code: "PERMISSION_DENIED",
+			permission
+		});
+		case "approval-required": return dbError("forbidden", `${permission} needs an approval`, {
+			code: "APPROVAL_REQUIRED",
+			permission,
+			...outcome.approval ? { approval: { id: outcome.approval.id } } : {}
+		});
+		default: return outcome;
+	}
+}
+/**
+* Checks one permission and fails closed: a missing authorizer, a throw or an
+* unknown outcome all deny. Never throws (invariant 4).
+*/
+async function checkPermission(options) {
+	const { authorizer, permission } = options;
+	if (!authorizer) return err(dbError("forbidden", "A permission is declared, but no authorizer is set", { code: "PERMISSION_DENIED" }));
+	let key;
+	try {
+		key = authorizer.key(permission);
+	} catch {
+		return err(dbError("forbidden", "Unknown permission", { code: "PERMISSION_DENIED" }));
+	}
+	const { subject, context } = requestOf(options.context);
+	try {
+		const error = outcomeError(await evaluateWith(authorizer, {
+			subject,
+			action: permission,
+			resource: options.resource,
+			context
+		}, options.runtime), key);
+		return error ? err(error) : ok(void 0);
+	} catch {
+		return err(dbError("forbidden", `The authorizer failed for ${key}`, {
+			code: "PERMISSION_DENIED",
+			permission: key
+		}));
+	}
+}
+/**
+* Checks one permission per resource, with `evaluations` when the authorizer
+* has it. Returns whether each one is granted, in order; any failure denies.
+*/
+async function checkEach(authorizer, permission, resources, context, runtime) {
+	if (!authorizer || resources.length === 0) return resources.map(() => false);
+	const { subject, context: requestContext } = requestOf(context);
+	const requests = resources.map((resource) => ({
+		subject,
+		action: permission,
+		resource,
+		context: requestContext
+	}));
+	try {
+		const outcomes = authorizer.evaluations ? await (runtime ? authorizer.evaluations(requests, runtime) : authorizer.evaluations(requests)) : await Promise.all(requests.map((request) => evaluateWith(authorizer, request, runtime)));
+		return requests.map((_, index) => isOutcome(outcomes[index]) && outcomes[index].outcome === "granted");
+	} catch {
+		return resources.map(() => false);
+	}
+}
+//#endregion
+export { isRequestMemo as a, defineAuthorizer as i, checkEach as n, requestMemo as o, checkPermission as r, requestOf as s, bindAuthorizer as t };

package/dist/automation-D41DXyvT.js

@@ -0,0 +1,75 @@
+import { n as dbError } from "./errors-BVFgt8BZ.js";
+import { r as err } from "./result-ntFBW2p2.js";
+//#region src/core/automation.ts
+/**
+* Declares an action the action registry runs for automations, workflow steps
+* and sequence steps.
+*/
+function defineAction(spec) {
+	return {
+		...spec,
+		apiVersion: 1
+	};
+}
+function errorText(cause) {
+	return cause instanceof Error ? cause.message : String(cause);
+}
+function configError(kind, issues) {
+	return dbError("validation", `The ${kind} action's config is invalid`, {
+		hint: "ACTION_CONFIG_INVALID",
+		issues: issues.map((issue) => ({
+			message: issue.message,
+			...issue.path === void 0 ? {} : { path: issue.path.map((part) => typeof part === "object" ? part.key : part) }
+		}))
+	});
+}
+/**
+* One registry over the actions of every installed block, for the automation
+* dispatcher, the workflow editor's action steps and sequence action steps.
+*
+* ```ts
+* const actions = createActionRegistry([
+*   notifyAction(blocks.notifications),
+*   taskFromConversationAction({ clients }),
+* ]);
+* ```
+*/
+function createActionRegistry(actions) {
+	const byKind = /* @__PURE__ */ new Map();
+	for (const action of actions) {
+		const version = action.apiVersion;
+		if (version !== 1) throw new TypeError(`The ${action.kind} action has apiVersion ${String(version)}; this release reads 1`);
+		if (byKind.has(action.kind)) throw new TypeError(`Two actions handle the kind ${action.kind}`);
+		byKind.set(action.kind, action);
+	}
+	return {
+		kinds: () => [...byKind.values()].map((action) => ({
+			kind: action.kind,
+			title: action.title,
+			...action.description === void 0 ? {} : { description: action.description }
+		})),
+		has: (kind) => byKind.has(kind),
+		run: async (call) => {
+			const action = byKind.get(call.action.kind);
+			if (action === void 0) return err(dbError("invalid_request", `No action handles the kind "${call.action.kind}"`, { hint: "ACTION_UNKNOWN" }));
+			try {
+				if (action.config !== void 0) {
+					const checked = await action.config["~standard"].validate(call.action.config ?? {});
+					if (checked.issues !== void 0) return err(configError(action.kind, checked.issues));
+				}
+				return await action.run(call);
+			} catch (cause) {
+				return err(dbError("unexpected", errorText(cause)));
+			}
+		}
+	};
+}
+/**
+* A key for one action of one origin for one event, the same on every retry of
+* the event.
+*/
+function actionKey(origin, kind, context) {
+	return `${origin.type === "automation" ? "rule" : origin.type}:${origin.id}:${kind}:${context.eventId ?? `${context.subjectType}/${context.subjectId}`}`;
+}
+//#endregion
+export { createActionRegistry as n, defineAction as r, actionKey as t };