better-supabase 0.1.0 → 0.3.0

package/dist/plugins/rules/index.d.ts

@@ -1,5 +1,5 @@
-import { g as Operation } from "../../executor-Bazhgsgq.js";
-import { f as Plugin, m as RepositoryExtension } from "../../plugin-HvGqCurB.js";
+import { g as Operation } from "../../executor-DynmIWhq.js";
+import { f as Plugin, m as RepositoryExtension } from "../../plugin-DVRB8qNE.js";
 //#region src/plugins/rules/index.d.ts
 export type RuleLevel = "off" | "warn" | "error";
 /** A level, or a level with the rule's option: `['error', 500]`. */
@@ -20,7 +20,8 @@ export interface RuleSet {
   readonly maxIncludeDepth?: RuleSetting<number>;
   /**
    * Tenant tables queried without a tenant: neither `context.tenant` nor the
-   * given claim (default `org_id`). Service connections are exempt.
+   * given claim (default `config.claims.tenant`, `tenant_id`). Service
+   * connections are exempt.
    */
   readonly requireTenantContext?: RuleSetting<string>;
   /** A service-role connection used where `window` and `document` exist. */

package/dist/plugins/rules/index.js

@@ -1,5 +1,6 @@
 import { n as dbError, t as DbException } from "../../errors-Bl3rkOzo.js";
 import { n as definePlugin } from "../../plugin-BqR6wKMB.js";
+import { n as claimAt, r as claimsOf } from "../../claims-CoTobNC-.js";
 //#region src/plugins/rules/index.ts
 /** Catches data-exposure and correctness mistakes; everything else off. */
 function safe() {
@@ -54,15 +55,7 @@ function sensitiveColumns(selection, table) {
 	return found;
 }
 function isBrowser() {
-	return typeof globalThis.window !== "undefined" && typeof globalThis.document !== "undefined";
-}
-function claimValue(context, claim) {
-	let value = context.claims;
-	for (const part of claim.split(".")) {
-		if (typeof value !== "object" || value === null) return void 0;
-		value = value[part];
-	}
-	return value;
+	return globalThis.window !== void 0 && globalThis.document !== void 0;
 }
 const TEXT_TYPES = /* @__PURE__ */ new Set([
 	"text",
@@ -75,7 +68,7 @@ const templatesBySchema = /* @__PURE__ */ new WeakMap();
 function bucketTemplates(schema) {
 	let templates = templatesBySchema.get(schema);
 	if (!templates) {
-		templates = Object.values(schema.buckets ?? {}).filter((bucket) => bucket.path.replace(/\{[^}]*\}|\//g, "").length > 0).map((bucket) => new RegExp(`^${bucket.path.split(/\{[^}]*\}/).map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("[^/]+")}$`));
+		templates = Object.values(schema.buckets ?? {}).filter((bucket) => bucket.path.replaceAll(/\{[^}]*\}|\//g, "").length > 0).map((bucket) => new RegExp(`^${bucket.path.split(/\{[^}]*\}/).map((part) => part.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("[^/]+")}$`));
 		templatesBySchema.set(schema, templates);
 	}
 	return templates;
@@ -107,14 +100,14 @@ function checks(rules) {
 			const depth = selection ? includeDepth(selection) : 0;
 			return depth > max ? `includes nest ${depth} levels deep (maximum ${max})` : void 0;
 		},
-		requireTenantContext: (op, { context }) => {
-			if (!op.table.flags.tenant || context.actor?.kind === "service") return void 0;
-			const claim = optionOf(rules.requireTenantContext, "org_id");
-			return context.tenant === void 0 && claimValue(context, claim) === void 0 ? `"${op.table.key}" is tenant-scoped but the request has no tenant (context.tenant or claim "${claim}")` : void 0;
+		requireTenantContext: (op, { context, schema }) => {
+			if (!op.table.flags.tenant || context.actor?.kind === "service") return;
+			const claim = optionOf(rules.requireTenantContext, claimsOf(schema).tenant);
+			return context.tenant === void 0 && claimAt(context.claims, claim) === void 0 ? `"${op.table.key}" is tenant-scoped but the request has no tenant (context.tenant or claim "${claim}")` : void 0;
 		},
 		noAdminInBrowser: (_op, { context }) => context.actor?.kind === "service" && isBrowser() ? "a service-role connection is running in a browser" : void 0,
 		noSensitiveSelect: (op, { options }) => {
-			if (options["sensitive"] === true) return void 0;
+			if (options["sensitive"] === true) return;
 			const selection = op.kind === "select" ? op.selection : op.returning;
 			const columns = selection ? sensitiveColumns(selection, op.table) : [];
 			return columns.length > 0 ? `reads sensitive column(s) ${columns.join(", ")}; pass { sensitive: true } to allow` : void 0;

package/dist/plugins/soft-delete/index.d.ts

@@ -1,6 +1,6 @@
-import { y as PrimaryKeyValue } from "../../types-C2fslP1z.js";
-import { t as AsyncResult } from "../../result-CTkCZ6JA.js";
-import { f as Plugin, m as RepositoryExtension, o as HasFlag } from "../../plugin-HvGqCurB.js";
+import { C as PrimaryKeyValue } from "../../types-DONv9SHN.js";
+import { t as AsyncResult } from "../../result-c2OYgCV2.js";
+import { f as Plugin, m as RepositoryExtension, o as HasFlag } from "../../plugin-DVRB8qNE.js";
 //#region src/plugins/soft-delete/index.d.ts
 export interface SoftDeleteFindArgs {
   /** Include soft-deleted rows of the queried table. */

package/dist/plugins/soft-delete/index.js

@@ -45,14 +45,14 @@ function softDelete() {
 			return {
 				kind: "update",
 				table,
-				set: { [column]: now().toISOString() },
+				set: { [column]: now().toString() },
 				where: op.where,
 				returning: void 0
 			};
 		},
 		repository({ table, base }) {
 			const flag = table.flags.softDelete;
-			if (!flag) return void 0;
+			if (!flag) return;
 			const update = base["update"];
 			return { restore: (key, args) => AsyncResult.from(async () => {
 				const result = await update(key, { [flag]: null }, {

package/dist/plugins/tenant/index.d.ts

@@ -1,4 +1,5 @@
-import { f as Plugin, h as RequestContext, m as RepositoryExtension, o as HasFlag } from "../../plugin-HvGqCurB.js";
+import { A as SchemaMeta } from "../../types-DONv9SHN.js";
+import { f as Plugin, h as RequestContext, m as RepositoryExtension, o as HasFlag } from "../../plugin-DVRB8qNE.js";
 //#region src/plugins/tenant/index.d.ts
 /**
  * Dotted paths to the string claims of `C` (up to three levels), e.g.
@@ -10,7 +11,9 @@ type StringPaths<T, Depth extends readonly unknown[]> = T extends object ? T ext
 export interface TenantOptions<C = unknown> {
   /**
    * JWT claim path(s) holding the tenant id when `context.tenant` is not set.
-   * Dots walk into objects. Default `['org_id', 'app_metadata.org_id']`.
+   * Dots walk into objects. Defaults to `config.claims.tenant` (`tenant_id`),
+   * then the same key in `app_metadata`. `user_metadata` is never a source:
+   * users can write it.
    */
   readonly claim?: ClaimPath<C> | readonly ClaimPath<C>[];
   /** Custom resolution, e.g. from a header validated against memberships. */
@@ -30,8 +33,11 @@ export interface TenantExtension extends RepositoryExtension {
   readonly methods: unknown;
   readonly deleteArgs: HasFlag<this["M"], this["T"], "tenant"> extends true ? TenantFindArgs : unknown;
 }
-/** The tenant for a request: `context.tenant`, then the configured claim. */
-export declare function resolveTenant<C = unknown>(context: RequestContext, options?: TenantOptions<C>): string | undefined;
+/**
+ * The tenant for a request: `context.tenant`, then the configured claim.
+ * `schema` supplies the default claim (`config.claims.tenant`).
+ */
+export declare function resolveTenant<C = unknown>(context: RequestContext, options?: TenantOptions<C>, schema?: Pick<SchemaMeta, "claims">): string | undefined;
 /**
  * Multi-tenancy for tables generated with `Flags.tenant`. Scopes reads,
  * updates and deletes to the request's tenant (nested includes and relation

package/dist/plugins/tenant/index.js

@@ -1,21 +1,23 @@
 import { n as dbError, t as DbException } from "../../errors-Bl3rkOzo.js";
 import { n as definePlugin } from "../../plugin-BqR6wKMB.js";
 import { n as scopeOperation } from "../../scope-CDHcS7dE.js";
+import { i as tenantClaimPaths, n as claimAt, r as claimsOf } from "../../claims-CoTobNC-.js";
 import { n as equals, r as forbidden, t as dbName } from "../../shared-_6-uPL7E.js";
 //#region src/plugins/tenant/index.ts
-/** The tenant for a request: `context.tenant`, then the configured claim. */
-function resolveTenant(context, options = {}) {
+/**
+* The tenant for a request: `context.tenant`, then the configured claim.
+* `schema` supplies the default claim (`config.claims.tenant`).
+*/
+function resolveTenant(context, options = {}, schema) {
 	if (options.resolve) return options.resolve(context);
 	if (typeof context.tenant === "string") return context.tenant;
 	const claim = options.claim;
-	const paths = typeof claim === "string" ? [claim] : claim ?? DEFAULT_CLAIMS;
+	const paths = typeof claim === "string" ? [claim] : claim ?? tenantClaimPaths(claimsOf(schema).tenant);
 	for (const path of paths) {
-		let value = context.claims;
-		for (const segment of path.split(".")) value = typeof value === "object" && value !== null ? value[segment] : void 0;
-		if (typeof value === "string" && value.length > 0) return value;
+		const value = claimAt(context.claims, path);
+		if (value !== void 0) return value;
 	}
 }
-const DEFAULT_CLAIMS = ["org_id", "app_metadata.org_id"];
 function tenantColumn(table) {
 	return dbName(table, table.flags.tenant);
 }
@@ -28,26 +30,26 @@ function tenantColumn(table) {
 */
 function tenant(options = {}) {
 	const onMissing = options.onMissing ?? "error";
-	const current = (table, context) => {
-		const id = resolveTenant(context, options);
+	const current = (table, context, schema) => {
+		const id = resolveTenant(context, options, schema);
 		if (id === void 0 && onMissing === "error" && tenantColumn(table)) throw new DbException(dbError("forbidden", `No tenant in the request context for "${table.key}"`));
 		return id;
 	};
 	return definePlugin({
 		name: "tenant",
-		transformQuery(op, { context, options: call }) {
+		transformQuery(op, { context, schema, options: call }) {
 			if (call["allTenants"] === true) return op;
-			const id = current(op.table, context);
+			const id = current(op.table, context, schema);
 			if (id === void 0) return op;
 			return scopeOperation(op, (table) => {
 				const column = tenantColumn(table);
 				return column ? equals(column, id) : void 0;
 			});
 		},
-		beforeMutation(op, { table, context, options: call }) {
+		beforeMutation(op, { table, context, schema, options: call }) {
 			const column = tenantColumn(table);
 			if (!column || call["allTenants"] === true) return op;
-			const id = current(table, context);
+			const id = current(table, context, schema);
 			if (id === void 0) return op;
 			switch (op.kind) {
 				case "insert": return {

package/dist/plugins/timestamps/index.d.ts

@@ -1,4 +1,4 @@
-import { f as Plugin } from "../../plugin-HvGqCurB.js";
+import { f as Plugin } from "../../plugin-DVRB8qNE.js";
 //#region src/plugins/timestamps/index.d.ts
 /**
  * Stamps the columns generated as `Flags.timestamps`: `createdAt` on insert,

package/dist/plugins/timestamps/index.js

@@ -14,7 +14,7 @@ function timestamps() {
 			if (!flags) return op;
 			const created = dbName(table, flags.createdAt);
 			const updated = dbName(table, flags.updatedAt);
-			const stamp = now().toISOString();
+			const stamp = now().toString();
 			switch (op.kind) {
 				case "insert": {
 					const stampCreated = insertsOnly(op);

package/dist/plugins/validation/index.d.ts

@@ -1,5 +1,5 @@
-import { f as Plugin } from "../../plugin-HvGqCurB.js";
-import { t as StandardSchemaV1 } from "../../standard-CyhRzctb.js";
+import { f as Plugin } from "../../plugin-DVRB8qNE.js";
+import { t as StandardSchemaV1 } from "../../standard-eudBiRk1.js";
 //#region src/plugins/validation/index.d.ts
 export interface TableValidators {
   /** Validates inserts and upserts, with app-cased keys. */

package/dist/pool-B9qsLyFR.d.ts

@@ -0,0 +1,71 @@
+import { t as SqlClient } from "./executor-B26lgbHD.js";
+//#region src/postgres/pool.d.ts
+/** The part of a `pg` pool client `createPostgres` uses. */
+interface PgPoolClient {
+  query(text: string, values?: unknown[]): Promise<{
+    rows: unknown[];
+  }>;
+  release(): void;
+}
+/** The part of a `pg.Pool` `createPostgres` uses. */
+interface PgPool {
+  connect(): Promise<PgPoolClient>;
+  end(): Promise<void>;
+}
+/** Statement timeouts in milliseconds by the role a transaction runs as. */
+interface PostgresTimeouts {
+  /** The connection-string role (`admin` and `transaction` without claims). Unset by default. */
+  readonly admin?: number;
+  /** Defaults to 8000, Supabase's setting for the role. */
+  readonly authenticated?: number;
+  /** Defaults to 3000, Supabase's setting for the role. */
+  readonly anon?: number;
+}
+interface PostgresOptions {
+  /** Defaults to `$SUPABASE_DB_URL`, then `$DATABASE_URL`. */
+  readonly connectionString?: string;
+  /** An existing pool to run on instead of opening one. `end()` ends it. */
+  readonly pool?: PgPool;
+  readonly max?: number;
+  /**
+   * Statement timeout in milliseconds, applied per transaction: one value
+   * for every role, or one per role. `set role` doesn't apply the role's own
+   * `statement_timeout`, so `authenticated` and `anon` get Supabase's 8 s
+   * and 3 s unless you set them.
+   */
+  readonly statementTimeout?: number | PostgresTimeouts;
+  /** Ends a session that stays idle inside a transaction this long, in milliseconds. */
+  readonly idleInTransactionTimeout?: number;
+  /** How long `connect` waits for a connection, in milliseconds. Defaults to 10000. */
+  readonly connectionTimeout?: number;
+  /** How long an unused connection stays open, in milliseconds. Defaults to 10000. */
+  readonly idleTimeout?: number;
+}
+/** JWT claims to run as. `role` must be `authenticated` or `anon`. */
+interface SqlClaims {
+  readonly sub?: string;
+  readonly role?: string;
+  readonly [claim: string]: unknown;
+}
+interface Postgres {
+  /** Connects as the connection-string role. On Supabase that bypasses RLS. */
+  readonly admin: SqlClient;
+  /** Runs every query as the given user, with RLS, like PostgREST does. */
+  asUser(claims: SqlClaims): SqlClient;
+  /** Runs every query as `anon`. */
+  readonly anon: SqlClient;
+  /** Runs `fn` in one transaction. Pass claims to run it as a user. */
+  transaction<T>(fn: (client: SqlClient) => Promise<T>, options?: {
+    readonly claims?: SqlClaims;
+  }): Promise<T>;
+  end(): Promise<void>;
+  [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * A pooled Postgres connection for jobs, scripts and tests. Each query (or
+ * transaction) runs in its own transaction; claims and role are
+ * transaction-local, so nothing leaks back into the pool.
+ */
+declare function createPostgres(options?: PostgresOptions): Postgres;
+//#endregion
+export { PostgresTimeouts as a, PostgresOptions as i, PgPoolClient as n, SqlClaims as o, Postgres as r, createPostgres as s, PgPool as t };

package/dist/postgres/index.d.ts

@@ -1,7 +1,7 @@
-import { g as Operation } from "../executor-Bazhgsgq.js";
-import { n as fromPgError, r as postgresExecutor, t as SqlClient } from "../executor-Bje4suQF.js";
-import { i as createPostgres, n as PostgresOptions, r as SqlClaims, t as Postgres } from "../pool-BFeqzwQS.js";
-import { t as Compiler } from "../compiler-DL18ukPe.js";
+import { g as Operation } from "../executor-DynmIWhq.js";
+import { n as fromPgError, r as postgresExecutor, t as SqlClient } from "../executor-B26lgbHD.js";
+import { a as PostgresTimeouts, i as PostgresOptions, n as PgPoolClient, o as SqlClaims, r as Postgres, s as createPostgres, t as PgPool } from "../pool-B9qsLyFR.js";
+import { t as Compiler } from "../compiler-2zqGzxVZ.js";
 //#region src/compile/sql.d.ts
 interface SqlQuery {
   readonly text: string;
@@ -17,6 +17,11 @@ interface SqlPlan {
   readonly count: SqlQuery | undefined;
   /** No row can match; the executor returns an empty result without a query. */
   readonly never: boolean;
+  /**
+   * The rest of an insert split to stay under the bind-parameter limit. They
+   * run after this plan, in the same transaction; rows and counts add up.
+   */
+  readonly chunks?: readonly SqlPlan[];
 }
 export declare function quoteIdent(name: string): string;
 /** Compiles an operation to parameterized SQL. Rows come back as json. */
@@ -25,4 +30,4 @@ export declare function compileSql(op: Operation): SqlPlan;
 //#region src/postgres/compiler.d.ts
 export declare const sqlCompiler: Compiler<SqlPlan>;
 //#endregion
-export { type Postgres, type PostgresOptions, type SqlClaims, type SqlClient, type SqlPlan, type SqlQuery, createPostgres, fromPgError, postgresExecutor };
+export { type PgPool, type PgPoolClient, type Postgres, type PostgresOptions, type PostgresTimeouts, type SqlClaims, type SqlClient, type SqlPlan, type SqlQuery, createPostgres, fromPgError, postgresExecutor };

package/dist/postgres/index.js

@@ -1,35 +1,55 @@
-import { n as quoteIdent, t as compileSql } from "../sql-M8l3fnS0.js";
-import { n as postgresExecutor, t as fromPgError } from "../executor-Ceq60hPM.js";
+import { n as quoteIdent, t as compileSql } from "../sql-BIgk12ew.js";
+import { n as postgresExecutor, t as fromPgError } from "../executor-C57jx2pn.js";
 import { Pool } from "pg";
 //#region src/postgres/pool.ts
+const DEFAULT_TIMEOUTS = {
+	authenticated: 8e3,
+	anon: 3e3
+};
 const ROLES = /* @__PURE__ */ new Set(["authenticated", "anon"]);
 function roleOf(claims) {
 	const role = claims.role ?? (claims.sub ? "authenticated" : "anon");
 	if (!ROLES.has(role)) throw new TypeError(`Cannot run as role "${role}": only "authenticated" and "anon" are assumed. Use postgres.admin for service work.`);
 	return role;
 }
+function openPool(options) {
+	const connectionString = options.connectionString ?? process.env["SUPABASE_DB_URL"] ?? process.env["DATABASE_URL"];
+	if (!connectionString) throw new TypeError("createPostgres needs a connectionString, $SUPABASE_DB_URL or $DATABASE_URL");
+	return new Pool({
+		connectionString,
+		max: options.max ?? 10,
+		connectionTimeoutMillis: options.connectionTimeout ?? 1e4,
+		idleTimeoutMillis: options.idleTimeout ?? 1e4
+	});
+}
 /**
 * A pooled Postgres connection for jobs, scripts and tests. Each query (or
 * transaction) runs in its own transaction; claims and role are
 * transaction-local, so nothing leaks back into the pool.
 */
 function createPostgres(options = {}) {
-	const connectionString = options.connectionString ?? process.env["SUPABASE_DB_URL"] ?? process.env["DATABASE_URL"];
-	if (!connectionString) throw new TypeError("createPostgres needs a connectionString, $SUPABASE_DB_URL or $DATABASE_URL");
-	const pool = new Pool({
-		connectionString,
-		max: options.max ?? 10
-	});
+	const pool = options.pool ?? openPool(options);
+	const timeouts = typeof options.statementTimeout === "number" ? {
+		admin: options.statementTimeout,
+		authenticated: options.statementTimeout,
+		anon: options.statementTimeout
+	} : {
+		...DEFAULT_TIMEOUTS,
+		...options.statementTimeout
+	};
+	/** Opens the transaction, then sets the timeouts, claims and role in one round trip. */
 	async function begin(client, session) {
 		await client.query("begin");
-		if (options.statementTimeout !== void 0) await client.query(`set local statement_timeout = ${Math.trunc(options.statementTimeout)}`);
-		if (session) {
-			await client.query("select set_config('request.jwt.claims', $1, true)", [JSON.stringify({
-				...session.claims,
-				role: session.role
-			})]);
-			await client.query(`set local role ${session.role}`);
-		}
+		const settings = [];
+		const timeout = session?.role === "authenticated" ? timeouts.authenticated : session?.role === "anon" ? timeouts.anon : timeouts.admin;
+		if (timeout !== void 0) settings.push(["statement_timeout", String(Math.trunc(timeout))]);
+		if (options.idleInTransactionTimeout !== void 0) settings.push(["idle_in_transaction_session_timeout", String(Math.trunc(options.idleInTransactionTimeout))]);
+		if (session) settings.push(["request.jwt.claims", JSON.stringify({
+			...session.claims,
+			role: session.role
+		})], ["role", session.role]);
+		if (settings.length === 0) return;
+		await client.query(`select ${settings.map((_, index) => `set_config($${index * 2 + 1}, $${index * 2 + 2}, true)`).join(", ")}`, settings.flat());
 	}
 	async function transaction(session, fn) {
 		const client = await pool.connect();

package/dist/{postgrest-Dm-vhY6R.d.ts → postgrest-DmBlevh-.d.ts}

@@ -1,4 +1,4 @@
-import { g as Operation } from "./executor-Bazhgsgq.js";
+import { g as Operation } from "./executor-DynmIWhq.js";
 //#region src/compile/postgrest.d.ts
 /**
  * A compiled PostgREST request, expressed as calls on the public

package/dist/{problem-DPu6Fh-t.js → problem-CGt1ADix.js}

@@ -33,7 +33,7 @@ const INTERNAL = /* @__PURE__ */ new Set([
 /** Converts a `DbError` to Problem Details. */
 function toProblem(error, options = {}) {
 	const problem = {
-		type: `${PROBLEM_TYPE_BASE}${error.kind.replace(/_/g, "-")}`,
+		type: `${PROBLEM_TYPE_BASE}${error.kind.replaceAll("_", "-")}`,
 		title: TITLES[error.kind],
 		status: error.status,
 		kind: error.kind
@@ -43,26 +43,31 @@ function toProblem(error, options = {}) {
 	if (error.code) problem["code"] = error.code;
 	if (error.hint) problem["hint"] = error.hint;
 	if ("constraint" in error && error.constraint) problem["constraint"] = error.constraint;
-	if ("columns" in error && error.columns) problem["columns"] = error.columns;
+	if ("columns" in error) problem["columns"] = error.columns;
 	if ("column" in error && error.column) problem["column"] = error.column;
 	if ("issues" in error) problem["issues"] = error.issues;
-	if ("required" in error && error.required) problem["required"] = error.required;
-	if ("retryAfter" in error && error.retryAfter !== void 0) problem["retryAfter"] = error.retryAfter;
+	if ("required" in error) problem["required"] = error.required;
+	if ("scopes" in error) problem["scopes"] = error.scopes;
+	if ("retryAfter" in error) problem["retryAfter"] = error.retryAfter;
 	return problem;
 }
 /**
-* An `application/problem+json` response. A 401 carries an RFC 6750
-* `WWW-Authenticate: Bearer` challenge.
+* An `application/problem+json` response. A 401, and a 403 for a missing
+* OAuth scope, carry an RFC 6750 `WWW-Authenticate: Bearer` challenge.
 */
 function problemResponse(error, options = {}) {
 	const headers = new Headers(options.headers);
 	headers.set("content-type", PROBLEM_CONTENT_TYPE);
+	const realm = (options.realm ?? "supabase").replaceAll("\"", "");
 	if (error.status === 401 && !headers.has("www-authenticate")) {
-		const realm = (options.realm ?? "supabase").replace(/"/g, "");
 		const params = error.code === "MISSING_CREDENTIALS" ? "" : ", error=\"invalid_token\"";
 		headers.set("www-authenticate", `Bearer realm="${realm}"${params}`);
 	}
-	if ("retryAfter" in error && error.retryAfter !== void 0 && !headers.has("retry-after")) headers.set("retry-after", String(error.retryAfter));
+	if ("scopes" in error && error.code === "INSUFFICIENT_SCOPE" && !headers.has("www-authenticate")) {
+		const scope = error.scopes.join(" ").replaceAll("\"", "");
+		headers.set("www-authenticate", `Bearer realm="${realm}", error="insufficient_scope", scope="${scope}"`);
+	}
+	if ("retryAfter" in error && !headers.has("retry-after")) headers.set("retry-after", String(error.retryAfter));
 	return new Response(JSON.stringify(toProblem(error, options)), {
 		status: error.status,
 		headers
@@ -87,6 +92,7 @@ function fromProblem(problem) {
 		"columns",
 		"column",
 		"required",
+		"scopes",
 		"retryAfter"
 	]) if (problem[key] !== void 0) extra[key] = problem[key];
 	extra["issues"] = problem.issues ?? [];

package/dist/{problem-DlgB0lYl.d.ts → problem-Z2RTQjZD.d.ts}

@@ -1,4 +1,4 @@
-import { b as ValidationIssue, m as DbErrorKind, p as DbError } from "./result-CTkCZ6JA.js";
+import { b as ValidationIssue, m as DbErrorKind, p as DbError } from "./result-c2OYgCV2.js";
 //#region src/core/problem.d.ts
 /** RFC 9457 Problem Details, with the `DbError` fields as extension members. */
 interface ProblemDetails {
@@ -17,6 +17,8 @@ interface ProblemDetails {
   readonly issues?: readonly ValidationIssue[];
   /** The assurance level a `forbidden` answer needs (`aal2`). */
   readonly required?: "aal1" | "aal2";
+  /** The OAuth scopes a `forbidden` answer needs. */
+  readonly scopes?: readonly string[];
   /** Seconds until a `rate_limited` caller may retry. */
   readonly retryAfter?: number;
 }
@@ -29,15 +31,15 @@ interface ProblemOptions {
   readonly expose?: boolean;
 }
 interface ProblemResponseOptions extends ProblemOptions {
-  readonly headers?: HeadersInit;
+  readonly headers?: ConstructorParameters<typeof Headers>[0];
   /** `realm` of the RFC 6750 challenge on 401. */
   readonly realm?: string;
 }
 /** Converts a `DbError` to Problem Details. */
 declare function toProblem(error: DbError, options?: ProblemOptions): ProblemDetails;
 /**
- * An `application/problem+json` response. A 401 carries an RFC 6750
- * `WWW-Authenticate: Bearer` challenge.
+ * An `application/problem+json` response. A 401, and a 403 for a missing
+ * OAuth scope, carry an RFC 6750 `WWW-Authenticate: Bearer` challenge.
  */
 declare function problemResponse(error: DbError, options?: ProblemResponseOptions): Response;
 declare function isProblem(value: unknown): value is ProblemDetails;

package/dist/query/index.d.ts

@@ -1,2 +1,2 @@
-import { a as QueryHelpers, c as TableQueries, d as queryCache, f as BetterQueryMeta, i as Queries, l as createQueries, n as InfiniteOptionsOf, o as QueryKeyOf, p as invalidateTables, r as MutationOptionsOf, s as QueryOptionsOf, t as CreateQueriesOptions, u as invalidateOnMutation } from "../index-Dup-nSe9.js";
-export { type BetterQueryMeta, CreateQueriesOptions, InfiniteOptionsOf, MutationOptionsOf, Queries, QueryHelpers, QueryKeyOf, QueryOptionsOf, TableQueries, createQueries, invalidateOnMutation, invalidateTables, queryCache };
+import { a as QueryHelpers, c as TableQueries, d as queryCache, f as BetterQueryMeta, i as Queries, l as createQueries, n as InfiniteOptionsOf, o as QueryKeyOf, p as invalidateTables, r as MutationOptionsOf, s as QueryOptionsOf, t as CreateQueriesOptions, u as invalidateOnMutation } from "../index-CriFFJ_p.js";
+export { type BetterQueryMeta, type CreateQueriesOptions, type InfiniteOptionsOf, type MutationOptionsOf, type Queries, type QueryHelpers, type QueryKeyOf, type QueryOptionsOf, type TableQueries, createQueries, invalidateOnMutation, invalidateTables, queryCache };

package/dist/query/index.js

@@ -1,3 +1,3 @@
 import { t as invalidateTables } from "../invalidate-DbxuL2jL.js";
-import { n as invalidateOnMutation, r as queryCache, t as createQueries } from "../query-ChvDbsDE.js";
+import { n as invalidateOnMutation, r as queryCache, t as createQueries } from "../query-BdKLTPlj.js";
 export { createQueries, invalidateOnMutation, invalidateTables, queryCache };

package/dist/{query-ChvDbsDE.js → query-BdKLTPlj.js}

@@ -1,7 +1,7 @@
 import { t as DbException } from "./errors-Bl3rkOzo.js";
-import { t as invalidationTargets } from "./tables-rZxRxNPW.js";
+import { t as invalidationTargets } from "./tables-Dhha3BXM.js";
 import { t as invalidateTables } from "./invalidate-DbxuL2jL.js";
-//#region src/query/index.ts
+//#region src/query/queries.ts
 /** Query errors stay `DbException`s, even for an `sb` with `mapError()`. */
 const asException = (error) => new DbException(error);
 function isSkip(value) {

package/dist/react/index.d.ts

@@ -1,7 +1,7 @@
-import { s as Impersonator } from "../mfa-TVia554c.js";
-import { t as AuthSession } from "../view-B0ltUmTi.js";
-import { r as LiveCountSeed } from "../live-6b9i72Ux.js";
-import { n as hasEntitlement, t as EntitlementKey } from "../entitlements-BBg61DQZ.js";
-import { n as SessionProviderProps, r as useSession, t as SessionProvider } from "../session-C3osL21k.js";
-import { a as BrowserLike, c as LiveCountHookOptions, d as useAuth, f as useBroadcast, h as useSupabase, i as BroadcastOptions, l as LiveQueryHookOptions, m as useLiveQuery, n as BetterSupabaseProvider, o as ClaimsOf, p as useLiveCount, r as BetterSupabaseProviderProps, s as LiveCount, t as BetterHooks, u as createHooks } from "../index-Hf8PP9sP.js";
-export { type AuthSession, BetterHooks, BetterSupabaseProvider, BetterSupabaseProviderProps, BroadcastOptions, BrowserLike, ClaimsOf, type EntitlementKey, type Impersonator, LiveCount, LiveCountHookOptions, type LiveCountSeed, LiveQueryHookOptions, SessionProvider, type SessionProviderProps, createHooks, hasEntitlement, useAuth, useBroadcast, useLiveCount, useLiveQuery, useSession, useSupabase };
+import { s as Impersonator } from "../mfa-x3V3vGh-.js";
+import { t as AuthSession } from "../view-3Po_PVlr.js";
+import { r as LiveCountSeed } from "../live-QE3UPbGm.js";
+import { n as MembershipClaim, r as hasEntitlement, t as EntitlementKey } from "../entitlements-DvJXoI02.js";
+import { a as BrowserLike, c as LiveCountHookOptions, d as createHooks, f as useAuth, g as useSupabase, h as useLiveQuery, i as BroadcastOptions, l as LiveQueryHookOptions, m as useLiveCount, n as BetterSupabaseProvider, o as ClaimsOf, p as useBroadcast, r as BetterSupabaseProviderProps, s as LiveCount, t as BetterHooks, u as ProfileOf } from "../index-BNsABq7P.js";
+import { SessionProvider, SessionProviderProps, useSession } from "./session.js";
+export { type AuthSession, type BetterHooks, BetterSupabaseProvider, type BetterSupabaseProviderProps, type BroadcastOptions, type BrowserLike, type ClaimsOf, type EntitlementKey, type Impersonator, type LiveCount, type LiveCountHookOptions, type LiveCountSeed, type LiveQueryHookOptions, type MembershipClaim, type ProfileOf, SessionProvider, type SessionProviderProps, createHooks, hasEntitlement, useAuth, useBroadcast, useLiveCount, useLiveQuery, useSession, useSupabase };

package/dist/react/index.js

@@ -1,5 +1,5 @@
 "use client";
-import { n as useSession, t as SessionProvider } from "../session-CD-3orO_.js";
-import { t as hasEntitlement } from "../entitlements-BC_khwRy.js";
-import { a as useLiveCount, i as useBroadcast, n as createHooks, o as useLiveQuery, r as useAuth, s as useSupabase, t as BetterSupabaseProvider } from "../react-CrOvrnIP.js";
+import { SessionProvider, useSession } from "./session.js";
+import { a as useLiveCount, i as useBroadcast, n as createHooks, o as useLiveQuery, r as useAuth, s as useSupabase, t as BetterSupabaseProvider } from "../react-DNBYNazu.js";
+import { t as hasEntitlement } from "../entitlements-CTEBm7IB.js";
 export { BetterSupabaseProvider, SessionProvider, createHooks, hasEntitlement, useAuth, useBroadcast, useLiveCount, useLiveQuery, useSession, useSupabase };

package/dist/react/server.d.ts

@@ -1,13 +1,13 @@
-import { t as AuthSession } from "../view-B0ltUmTi.js";
-import { n as SessionProviderProps, t as SessionProvider } from "../session-C3osL21k.js";
-import { a as BrowserLike, d as useAuth, f as useBroadcast, h as useSupabase, i as BroadcastOptions, l as LiveQueryHookOptions, m as useLiveQuery, n as BetterSupabaseProvider, o as ClaimsOf, r as BetterSupabaseProviderProps, t as BetterHooks } from "../index-Hf8PP9sP.js";
+import { t as AuthSession } from "../view-3Po_PVlr.js";
+import { a as BrowserLike, f as useAuth, g as useSupabase, h as useLiveQuery, i as BroadcastOptions, l as LiveQueryHookOptions, n as BetterSupabaseProvider, o as ClaimsOf, p as useBroadcast, r as BetterSupabaseProviderProps, t as BetterHooks, u as ProfileOf } from "../index-BNsABq7P.js";
+import { SessionProvider, SessionProviderProps } from "./session.js";
 //#region src/react/server.d.ts
 /** The `react-server` build of `useSession`: await `next.session()` instead. */
-export declare const useSession: <C = unknown>() => AuthSession<C>;
+export declare const useSession: <C = unknown, P = unknown>() => AuthSession<C, P>;
 /**
  * The `react-server` build of `createHooks`: importing a module that creates
  * hooks is safe on the server, calling a hook there throws.
  */
 export declare function createHooks<B extends BrowserLike>(): BetterHooks<B>;
 //#endregion
-export { type AuthSession, type BetterHooks, BetterSupabaseProvider, type BetterSupabaseProviderProps, type BroadcastOptions, type BrowserLike, type ClaimsOf, type LiveQueryHookOptions, SessionProvider, type SessionProviderProps, useAuth, useBroadcast, useLiveQuery, useSupabase };
+export { type AuthSession, type BetterHooks, BetterSupabaseProvider, type BetterSupabaseProviderProps, type BroadcastOptions, type BrowserLike, type ClaimsOf, type LiveQueryHookOptions, type ProfileOf, SessionProvider, type SessionProviderProps, useAuth, useBroadcast, useLiveQuery, useSupabase };

package/dist/react/server.js

@@ -1,4 +1,4 @@
-import { i as useBroadcast, o as useLiveQuery, r as useAuth, s as useSupabase, t as BetterSupabaseProvider } from "../react-CrOvrnIP.js";
+import { i as useBroadcast, o as useLiveQuery, r as useAuth, s as useSupabase, t as BetterSupabaseProvider } from "../react-DNBYNazu.js";
 import { SessionProvider } from "./session.js";
 //#region src/react/server.ts
 function clientOnly(name) {

package/dist/react/session.d.ts

@@ -1,2 +1,21 @@
-import { n as SessionProviderProps, r as useSession, t as SessionProvider } from "../session-C3osL21k.js";
-export { SessionProvider, SessionProviderProps, useSession };
+import { t as AuthSession } from "../view-3Po_PVlr.js";
+import { ReactNode } from "react";
+//#region src/react/session.d.ts
+export interface SessionProviderProps {
+  /**
+   * An unresolved `next.session()` promise, created inside a `<Suspense>`
+   * boundary so the layout itself never waits for auth.
+   */
+  readonly sessionPromise: Promise<AuthSession>;
+  readonly children?: ReactNode;
+}
+/** Shares the server-verified session with Client Components. */
+export declare function SessionProvider(props: SessionProviderProps): ReactNode;
+/**
+ * The session from the nearest `<SessionProvider>`. Suspends until the
+ * promise resolves, so render it inside `<Suspense>`. `C` types the claims
+ * (the output of `sb.claims(schema)`) and `P` the profile (the output of
+ * `sb.userMetadata(schema)`); `createHooks().useSession` infers both.
+ */
+export declare function useSession<C = unknown, P = unknown>(): AuthSession<C, P>;
+//#endregion