better-supabase 0.0.0 → 0.1.0

package/dist/respond-4-dhoV7x.js

@@ -0,0 +1,380 @@
+import { n as dbError, o as isDbError, r as dbErrorOf } from "./errors-Bl3rkOzo.js";
+import { i as ok, n as err, o as toDbError, t as AsyncResult } from "./result-DWXatkd6.js";
+import { a as postgrestExecutor, n as StatsRecorder } from "./stats-3iy8u3_P.js";
+import { a as problemResponse } from "./problem-DPu6Fh-t.js";
+import { i as loadEnv } from "./env-BEToab0I.js";
+import { h as actClaim, i as authContext, o as resolveAuth, r as checkAal } from "./mfa-CpogP66z.js";
+import { n as postgresExecutor } from "./executor-Ceq60hPM.js";
+import { createClient } from "@supabase/supabase-js";
+//#region src/server/replicas.ts
+/** Cookie holding the epoch ms until which reads stay on the primary. */
+const PRIMARY_COOKIE = "bs-primary-until";
+/** Default time reads stay on the primary after a write. */
+const DEFAULT_PIN_MS = 5e3;
+function replicaState(pinnedUntil = 0, now = Date.now()) {
+	let wrote = false;
+	const inherited = pinnedUntil > now;
+	return {
+		get pinned() {
+			return wrote || inherited;
+		},
+		get wrote() {
+			return wrote;
+		},
+		pin() {
+			wrote = true;
+		}
+	};
+}
+/** `bs-primary-until` from a `cookie` header, or 0. */
+function pinnedUntil(cookieHeader) {
+	if (!cookieHeader) return 0;
+	for (const part of cookieHeader.split(";")) {
+		const [name, value] = part.trim().split("=", 2);
+		if (name === "bs-primary-until") {
+			const until = Number(value);
+			return Number.isFinite(until) ? until : 0;
+		}
+	}
+	return 0;
+}
+/** A `Set-Cookie` value keeping the next requests on the primary for `pinMs`. */
+function primaryCookie(pinMs, now = Date.now()) {
+	const seconds = Math.max(1, Math.ceil(pinMs / 1e3));
+	return `${PRIMARY_COOKIE}=${String(now + pinMs)}; Path=/; Max-Age=${String(seconds)}; HttpOnly; SameSite=Lax`;
+}
+/**
+* Reads go to `replica` until the context is pinned; writes, and every read
+* after a successful write, go to `primary`.
+*/
+function routedExecutor(primary, replica, state) {
+	const batch = primary.batch?.bind(primary);
+	const replicaBatch = replica.batch?.bind(replica);
+	return {
+		name: primary.name,
+		...primary.functionSources && replica.functionSources ? { functionSources: true } : {},
+		async execute(op, context) {
+			if (op.kind === "select" && !state.pinned) return replica.execute(op, context);
+			const result = await primary.execute(op, context);
+			if (op.kind !== "select" && result.ok) state.pin();
+			return result;
+		},
+		...primary.rpc ? { async rpc(name, args, context) {
+			if (context.get && !state.pinned && replica.rpc) return replica.rpc(name, args, context);
+			const result = await primary.rpc(name, args, context);
+			if (!context.get && result.ok) state.pin();
+			return result;
+		} } : {},
+		...batch ? { batch: (ops, context) => !state.pinned && replicaBatch ? replicaBatch(ops, context) : batch(ops, context) } : {}
+	};
+}
+//#endregion
+//#region src/server/delete-account.ts
+const REMOVE_BATCH = 1e3;
+/** Maps an `AuthApiError` from `auth.admin.deleteUser` to a `DbError`. */
+function fromAuthError(raw) {
+	if (isDbError(raw)) return raw;
+	const failure = typeof raw === "object" && raw !== null ? raw : {};
+	const message = failure.message ?? "Auth request failed";
+	const base = {
+		table: "auth.users",
+		...failure.code ? { code: failure.code } : {}
+	};
+	if (failure.code === "user_not_found" || failure.status === 404) return dbError("not_found", message, base);
+	if (/database error deleting user/i.test(message)) return dbError("conflict", message, {
+		...base,
+		hint: "A foreign key to auth.users without on delete cascade or set null blocks the delete (doctor BS406)"
+	});
+	if (failure.status === 401) return dbError("unauthorized", message, base);
+	if (failure.status === 403) return dbError("forbidden", message, base);
+	return failure.name === "AuthRetryableFetchError" || (failure.status ?? 0) >= 500 ? dbError("network", message, base) : dbError("unexpected", message, base);
+}
+/**
+* Removes a user's Storage objects, then the Auth user, then announces the
+* delete. Rows referencing `auth.users` follow their foreign keys.
+*/
+function deleteAccount(sb, service, userId, options = {}) {
+	return AsyncResult.from(async () => {
+		const client = service();
+		const removed = {};
+		for (const bucket of options.buckets ?? []) {
+			const param = bucket.owner;
+			if (!param) continue;
+			options.signal?.throwIfAborted();
+			const storage = bucket.connect(client);
+			const listed = await storage.list({ [param]: userId }, options.signal ? { signal: options.signal } : {});
+			if (!listed.ok) return listed;
+			const paths = listed.data.map((object) => object.path).filter((path) => {
+				return bucket.match(path)?.[param] === userId;
+			});
+			for (let start = 0; start < paths.length; start += REMOVE_BATCH) {
+				const batch = await storage.remove(paths.slice(start, start + REMOVE_BATCH));
+				if (!batch.ok) return batch;
+			}
+			removed[bucket.id] = paths.length;
+		}
+		options.signal?.throwIfAborted();
+		try {
+			const { error } = await client.auth.admin.deleteUser(userId);
+			if (error) return err(fromAuthError(error));
+		} catch (cause) {
+			return err(fromAuthError(cause));
+		}
+		const context = options.context ?? {};
+		sb.events.emit("mutation", {
+			table: "auth.users",
+			kind: "delete",
+			rows: [{ id: userId }],
+			context
+		});
+		for (const table of options.cascades ?? []) sb.events.emit("mutation", {
+			table,
+			kind: "delete",
+			rows: [],
+			context
+		});
+		return ok({
+			userId,
+			removed
+		});
+	});
+}
+//#endregion
+//#region src/server/server.ts
+const STATELESS = {
+	persistSession: false,
+	autoRefreshToken: false,
+	detectSessionInUrl: false
+};
+/** `{ ...server, ...extra }` without reading the lazy `env` getter. */
+function extendServer(server, extra) {
+	return Object.defineProperties({}, {
+		...Object.getOwnPropertyDescriptors(server),
+		...Object.getOwnPropertyDescriptors(extra)
+	});
+}
+/** `{ ...base, ...extra }` that keeps lazy getters lazy. */
+function withExtra(base, extra) {
+	return Object.defineProperties({}, {
+		...Object.getOwnPropertyDescriptors(base),
+		...Object.getOwnPropertyDescriptors(extra)
+	});
+}
+/**
+* Server-side entry point for APIs, jobs, MCP servers and framework
+* adapters. Holds the secrets; `sb` stays isomorphic.
+*/
+function createServer(sb, options = {}) {
+	let loaded;
+	const env = () => loaded ??= options.env ?? loadEnv();
+	let adminClient;
+	let anonClient;
+	const secretKey = () => {
+		const key = env().secretKey;
+		if (!key) throw new TypeError("admin() needs SUPABASE_SECRET_KEY; it is not set");
+		return key;
+	};
+	const serviceClient = () => {
+		adminClient ??= createClient(env().url, secretKey(), { auth: STATELESS });
+		return adminClient;
+	};
+	const readUrl = () => options.readUrl === false ? void 0 : options.readUrl?.replace(/\/+$/, "") ?? env().readUrl;
+	/** Clients for the primary share the service and anon clients; others don't. */
+	const supabaseAt = (url, auth, headers = {}) => {
+		const global = Object.keys(headers).length > 0 ? { global: { headers } } : void 0;
+		const shared = !global && url === env().url;
+		switch (auth.kind) {
+			case "user": return createClient(url, env().publishableKey, {
+				accessToken: () => Promise.resolve(auth.token),
+				...global
+			});
+			case "service": return shared ? serviceClient() : createClient(url, secretKey(), {
+				auth: STATELESS,
+				...global
+			});
+			case "anon":
+			case "invalid":
+				if (!shared) return createClient(url, env().publishableKey, {
+					auth: STATELESS,
+					...global
+				});
+				anonClient ??= createClient(url, env().publishableKey, { auth: STATELESS });
+				return anonClient;
+			default: return auth;
+		}
+	};
+	const supabaseFor = (auth, headers = {}) => supabaseAt(env().url, auth, headers);
+	const dbFor = (auth, context = {}) => sb.connect(supabaseFor(auth), {
+		...authContext(auth),
+		...context
+	});
+	const sqlFor = (claims, context, stats) => {
+		if (!options.postgres) throw new TypeError("Direct Postgres access needs createServer(sb, { postgres: createPostgres() })");
+		return sb.connect(postgresExecutor(options.postgres.asUser(claims)), context, stats ? { stats } : {});
+	};
+	/** Clients and repositories are built on first access: most scopes use one of them. */
+	const contextFor = (resolution, headers, parent, until = 0) => {
+		const { auth } = resolution;
+		const context = authContext(auth);
+		const recorder = new StatsRecorder(parent);
+		let supabase;
+		let db;
+		let sql;
+		const sqlClaims = auth.kind === "user" ? auth.claims : auth.kind === "anon" ? { role: "anon" } : void 0;
+		const client = () => supabase ??= supabaseFor(auth, headers);
+		let replica;
+		const replicaUrl = () => {
+			const url = readUrl();
+			if (url) replica ??= replicaState(until);
+			return url;
+		};
+		return {
+			auth,
+			resolution,
+			get supabase() {
+				return client();
+			},
+			get db() {
+				if (db) return db;
+				const url = replicaUrl();
+				db = sb.connect(client(), context, {
+					stats: recorder,
+					...url && replica ? { executor: routedExecutor(postgrestExecutor(client()), postgrestExecutor(supabaseAt(url, auth, headers)), replica) } : {}
+				});
+				return db;
+			},
+			get replica() {
+				replicaUrl();
+				return replica;
+			},
+			get sql() {
+				if (!options.postgres || !sqlClaims) return void 0;
+				sql ??= sqlFor(sqlClaims, context, recorder);
+				return sql;
+			},
+			stats: () => recorder.snapshot()
+		};
+	};
+	const resolve = async (request, resolveOptions = {}) => {
+		const claims = options.auth?.claims ?? sb.claimsSchema;
+		const resolution = await resolveAuth(request, {
+			...options.auth,
+			...claims ? { claims } : {},
+			env: env(),
+			...resolveOptions.refresh !== void 0 ? { refresh: resolveOptions.refresh } : {},
+			onRefresh: (event) => {
+				options.auth?.onRefresh?.(event);
+				sb.events.emit("refresh", event);
+			}
+		});
+		if (sb.events.has("auth")) {
+			const { auth } = resolution;
+			sb.events.emit("auth", {
+				source: auth.kind === "user" ? auth.source === "cookie" ? "cookie" : "bearer" : auth.kind === "service" ? "bearer" : "none",
+				ok: auth.kind !== "invalid",
+				...auth.kind === "user" ? { userId: auth.user.id } : {}
+			});
+		}
+		return resolution;
+	};
+	return {
+		get env() {
+			return env();
+		},
+		resolve,
+		supabaseFor,
+		dbFor,
+		contextFor: (auth, contextOptions = {}) => contextFor({
+			auth,
+			cookies: [],
+			headers: {},
+			requestCookies: [],
+			apply: (response) => response
+		}, {}, contextOptions.stats, contextOptions.pinnedUntil),
+		async context(request, contextOptions = {}) {
+			const resolution = await resolve(request, { refresh: contextOptions.refresh ?? false });
+			return contextFor(resolution, options.headers?.(request) ?? {}, contextOptions.stats, contextOptions.pinnedUntil ?? pinnedUntil(request.headers.get("cookie")));
+		},
+		admin: (context = {}) => sb.connect(serviceClient(), {
+			actor: {
+				id: "service",
+				kind: "service",
+				role: "service_role"
+			},
+			claims: { role: "service_role" },
+			...context
+		}),
+		deleteAccount: (userId, deleteOptions) => deleteAccount(sb, serviceClient, userId, deleteOptions),
+		actingAs: (userId, claims = {}, impersonation) => {
+			const full = {
+				role: "authenticated",
+				...claims,
+				sub: userId,
+				...impersonation ? { act: actClaim(impersonation) } : {}
+			};
+			return sqlFor(full, {
+				actor: {
+					id: userId,
+					kind: "user",
+					role: full.role ?? "authenticated",
+					...impersonation ? { impersonator: impersonation.actor } : {}
+				},
+				claims: full
+			});
+		}
+	};
+}
+//#endregion
+//#region src/server/respond.ts
+/** `undefined` when `auth` may pass; otherwise the 401/403 error to send. */
+function guard(auth, allow = ["user"], aal = "aal1") {
+	if (auth.kind === "invalid") return auth.error;
+	if (allow.includes(auth.kind)) return checkAal(auth, aal);
+	return auth.kind === "anon" ? dbError("unauthorized", "Sign in to continue", { code: "MISSING_CREDENTIALS" }) : dbError("forbidden", `A ${auth.kind} caller is not allowed here`);
+}
+function isResult(value) {
+	return typeof value === "object" && value !== null && "ok" in value && "data" in value && "error" in value;
+}
+/**
+* Settles a handler's return value: `Result`s and `AsyncResult`s unwrap,
+* thrown `DbException`s (or errors whose `cause` is a `DbError`) become
+* errors, anything else is data. Other thrown
+* errors propagate.
+*/
+async function settle(run) {
+	try {
+		const value = await run();
+		if (!isResult(value)) return {
+			ok: true,
+			data: value
+		};
+		if (value.ok) return {
+			ok: true,
+			data: value.data
+		};
+		return {
+			ok: false,
+			error: isDbError(value.error) ? value.error : toDbError(value.error)
+		};
+	} catch (cause) {
+		const thrown = dbErrorOf(cause);
+		if (thrown) return {
+			ok: false,
+			error: thrown
+		};
+		throw cause;
+	}
+}
+/** A handler's value as a response: `Response` as is, data as JSON, errors as Problem Details. */
+async function respond(run, options = {}) {
+	const settled = await settle(run);
+	if (!settled.ok) return problemResponse(settled.error, options);
+	if (settled.data instanceof Response) return settled.data;
+	if (settled.data === void 0) return new Response(null, { status: 204 });
+	return Response.json(settled.data, { status: options.status ?? 200 });
+}
+function defaultExpose() {
+	return typeof process !== "undefined" && process.env["NODE_ENV"] === "development";
+}
+//#endregion
+export { settle as a, withExtra as c, primaryCookie as d, respond as i, DEFAULT_PIN_MS as l, guard as n, createServer as o, isResult as r, extendServer as s, defaultExpose as t, PRIMARY_COOKIE as u };

package/dist/respond-PoTpy5DT.d.ts

@@ -0,0 +1,169 @@
+import { n as AnyModels, t as AnyFunctions } from "./types-C2fslP1z.js";
+import { p as DbError, t as AsyncResult } from "./result-CTkCZ6JA.js";
+import { I as StatsRecorder, P as DbStats, t as BetterSupabase, y as Db } from "./define-CTfWw-SS.js";
+import { h as RequestContext } from "./plugin-HvGqCurB.js";
+import { t as BetterSupabaseEnv } from "./index-Dy6kuF0P.js";
+import { r as SqlClaims, t as Postgres } from "./pool-BFeqzwQS.js";
+import { o as ImpersonationOptions, t as Aal } from "./mfa-TVia554c.js";
+import { a as ResolveAuthOptions, r as AuthState, t as AuthResolution } from "./resolve-DW8h9NPm.js";
+import { n as Bucket } from "./index-Nxo3TJcm.js";
+import { SupabaseClient } from "@supabase/supabase-js";
+//#region src/server/delete-account.d.ts
+interface DeleteAccountOptions {
+  /**
+   * Buckets to clear first. Objects whose `owner` placeholder (`{userId}`,
+   * or `owner.param` for `owner` buckets) is the user are removed; buckets
+   * without one are skipped.
+   */
+  readonly buckets?: readonly Bucket<string>[];
+  /**
+   * App keys of tables whose rows the database deletes or updates with the
+   * user (`on delete cascade` or `set null` to `auth.users`). They get a
+   * table-wide `mutation` notice, so caches drop their reads.
+   */
+  readonly cascades?: readonly string[];
+  readonly context?: RequestContext;
+  readonly signal?: AbortSignal;
+}
+interface DeleteAccountResult {
+  readonly userId: string;
+  /** Removed objects per bucket id. */
+  readonly removed: Readonly<Record<string, number>>;
+}
+//#endregion
+//#region src/server/replicas.d.ts
+/** Cookie holding the epoch ms until which reads stay on the primary. */
+declare const PRIMARY_COOKIE = "bs-primary-until";
+/** Where a request context sends its reads. */
+interface ReplicaState {
+  /** Reads go to the primary: this context wrote, or a recent request did. */
+  readonly pinned: boolean;
+  /** This context wrote through its repositories (or called `pin()`). */
+  readonly wrote: boolean;
+  /** Sends later reads to the primary, e.g. after a write through `$client` or `$sql`. */
+  pin(): void;
+}
+//#endregion
+//#region src/server/server.d.ts
+interface ServerOptions {
+  /** Defaults to `loadEnv()`. */
+  readonly env?: BetterSupabaseEnv;
+  /** Enables `ctx.sql` and `actingAs()`. */
+  readonly postgres?: Postgres;
+  readonly auth?: Omit<ResolveAuthOptions, "env">;
+  /**
+   * Extra headers on the caller's PostgREST requests, readable in Postgres as
+   * `current_setting('request.headers')` (channel, request id, client IP for audit).
+   */
+  readonly headers?: (request: Request) => Readonly<Record<string, string>>;
+  /**
+   * PostgREST URL for the caller's reads: a read replica or the `<ref>-all`
+   * load balancer. Defaults to `SUPABASE_READ_URL`; `false` reads from the
+   * primary.
+   */
+  readonly readUrl?: string | false;
+  readonly replicas?: {
+    /** How long the next requests read from the primary after a write. Defaults to 5 s. */
+    readonly pinMs?: number;
+  };
+}
+interface ServerContext<M extends AnyModels, F extends AnyFunctions, E, C = unknown> {
+  readonly auth: AuthState<C>;
+  readonly resolution: AuthResolution<C>;
+  /** supabase-js client scoped to the caller (RLS applies). */
+  readonly supabase: SupabaseClient;
+  /** Repositories over PostgREST as the caller. */
+  readonly db: Db<M, F, E, SupabaseClient>;
+  /** Repositories over direct Postgres as the caller, when `postgres` is configured. */
+  readonly sql: Db<M, F, E, undefined> | undefined;
+  /** Calls, waves, tables and time for `db` and `sql` together. */
+  stats(): DbStats;
+  /** Where `db` reads go, when a read URL is configured. */
+  readonly replica: ReplicaState | undefined;
+}
+interface ContextOptions {
+  readonly refresh?: boolean;
+  /** Epoch ms until which `db` reads from the primary (the `bs-primary-until` cookie). */
+  readonly pinnedUntil?: number;
+  /** Also records this context's calls into a request-wide recorder. */
+  readonly stats?: StatsRecorder;
+}
+interface BetterServer<M extends AnyModels, F extends AnyFunctions, E, C = unknown> {
+  readonly env: BetterSupabaseEnv;
+  resolve(request: Request, options?: {
+    readonly refresh?: boolean;
+  }): Promise<AuthResolution<C>>;
+  /**
+   * Resolves auth and binds repositories to the caller. Refreshes an expired
+   * cookie session only with `refresh: true`; send `ctx.resolution.apply(response)`.
+   */
+  context(request: Request, options?: ContextOptions): Promise<ServerContext<M, F, E, C>>;
+  /** The context for an auth state resolved elsewhere (the proxy, a queue message). */
+  contextFor(auth: AuthState<C>, options?: ContextOptions): ServerContext<M, F, E, C>;
+  /** A stateless supabase-js client for an auth state, optionally with extra request headers. */
+  supabaseFor(auth: AuthState, headers?: Readonly<Record<string, string>>): SupabaseClient;
+  /** Repositories for an auth state (e.g. one resolved by the proxy). */
+  dbFor(auth: AuthState, context?: RequestContext): Db<M, F, E, SupabaseClient>;
+  /** Service-role repositories. Bypasses RLS; the actor is `service`. */
+  admin(context?: RequestContext): Db<M, F, E, SupabaseClient>;
+  /**
+   * Deletes a user: their objects in `buckets`, then the Auth user, then a
+   * `mutation` notice for `auth.users`. Needs the secret key. Access tokens
+   * already issued stay valid until they expire.
+   */
+  deleteAccount(userId: string, options?: DeleteAccountOptions): AsyncResult<DeleteAccountResult>;
+  /**
+   * Repositories running as a user, with RLS, over direct Postgres. With
+   * `impersonation`, the claims carry `act: { sub: actor, reason }`, which
+   * the `audit` and `actor` SQL kit modules record.
+   */
+  actingAs(userId: string, claims?: Omit<SqlClaims, "sub" | "act">, impersonation?: ImpersonationOptions): Db<M, F, E, undefined>;
+}
+/**
+ * Server-side entry point for APIs, jobs, MCP servers and framework
+ * adapters. Holds the secrets; `sb` stays isomorphic.
+ */
+declare function createServer<M extends AnyModels, D, F extends AnyFunctions, E, C = unknown>(sb: BetterSupabase<M, D, F, E, C>, options?: ServerOptions): BetterServer<M, F, E, C>;
+//#endregion
+//#region src/server/respond.d.ts
+type AuthKind = AuthState["kind"];
+interface GuardOptions {
+  /** Auth kinds allowed through. Defaults to `['user']`. */
+  readonly allow?: readonly Exclude<AuthKind, "invalid">[];
+  /**
+   * Assurance level user sessions need. `aal2` answers 403 with
+   * `required: 'aal2'` until the user verifies a second factor.
+   */
+  readonly aal?: Aal;
+}
+/** `undefined` when `auth` may pass; otherwise the 401/403 error to send. */
+declare function guard(auth: AuthState, allow?: GuardOptions["allow"], aal?: Aal): DbError | undefined;
+declare function isResult(value: unknown): value is {
+  ok: boolean;
+  data: unknown;
+  error: unknown;
+};
+type Settled = {
+  readonly ok: true;
+  readonly data: unknown;
+} | {
+  readonly ok: false;
+  readonly error: DbError;
+};
+/**
+ * Settles a handler's return value: `Result`s and `AsyncResult`s unwrap,
+ * thrown `DbException`s (or errors whose `cause` is a `DbError`) become
+ * errors, anything else is data. Other thrown
+ * errors propagate.
+ */
+declare function settle(run: () => unknown): Promise<Settled>;
+interface RespondOptions {
+  readonly instance?: string;
+  readonly expose?: boolean;
+  /** Status for data responses. Defaults to 200 (204 without data). */
+  readonly status?: number;
+}
+/** A handler's value as a response: `Response` as is, data as JSON, errors as Problem Details. */
+declare function respond(run: () => unknown, options?: RespondOptions): Promise<Response>;
+//#endregion
+export { DeleteAccountResult as _, guard as a, settle as c, ServerContext as d, ServerOptions as f, DeleteAccountOptions as g, ReplicaState as h, Settled as i, BetterServer as l, PRIMARY_COOKIE as m, GuardOptions as n, isResult as o, createServer as p, RespondOptions as r, respond as s, AuthKind as t, ContextOptions as u };