better-supabase 0.7.1 → 0.9.0

package/dist/server-types-OohhIQb2.d.ts

@@ -0,0 +1,737 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult } from "./result-Cj3yWhjH.js";
+import { a as AnyModels, i as AnyFunctions } from "./types-YfwpIE-d.js";
+import { o as EventHub } from "./events-CTreRrgP.js";
+import { m as RequestContext } from "./plugin-CDLJRFFg.js";
+import { t as BetterSupabaseEnv } from "./index-CETRk4YO.js";
+import { a as ResolveAuthOptions, p as CookieWrite, r as AuthState, t as AuthResolution } from "./resolve-w9EpHzuM.js";
+import { r as CredentialProvider } from "./provider-9gBq9W6k.js";
+import { n as SqlClient } from "./executor-BBHgjUJu.js";
+import { a as ProblemFormat } from "./problem-CEjyhV5T.js";
+import { t as AnyAuthorizer } from "./authorizer-eiOjo-3l.js";
+import { i as EventSink } from "./cloud-event-5rCEzIgK.js";
+import { S as Bucket, t as StorageApi } from "./storage-api-Cx-1iWBd.js";
+import { Kt as StatsRecorder, Wt as DbStats, _ as Db, t as BetterSupabase } from "./define-DxHHbNEb.js";
+import { t as ImpersonationOptions } from "./impersonation-D5chOkrO.js";
+import { _ as SupportAuthorize, b as TicketSubject, i as AuthorizationHooks } from "./authorization-hooks-DkmrnDX7.js";
+import { s as SqlClaims, t as BetterPostgres } from "./pool-CwOCsX9e.js";
+import { SupabaseClient } from "@supabase/supabase-js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#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;
+  /**
+   * Direct Postgres with rights on `auth.users` (`postgres.admin`). When the
+   * Auth server reports a database error, the delete is replayed in a
+   * statement that is rolled back, and the database's own error (its
+   * SQLSTATE and hint, such as `ORGANIZATION_OWNER_REQUIRED`) is returned
+   * instead of Auth's generic one. `server.deleteAccount` passes its
+   * `postgres.admin`.
+   */
+  readonly sql?: SqlClient;
+}
+interface DeleteAccountResult {
+  readonly userId: string;
+  /** Removed objects per bucket id. */
+  readonly removed: Readonly<Record<string, number>>;
+}
+/**
+ * Deletes the Auth user, then removes their Storage objects, then announces
+ * the delete. Rows referencing `auth.users` follow their foreign keys. The
+ * objects are listed first and removed only once the user is gone, so a
+ * delete the database refuses leaves them in place.
+ *
+ * `server.deleteAccount` calls it with the server's service client. Apps on
+ * the `@supabase/server` pipeline call it with theirs:
+ * `deleteAccount(betterSupabase, ctx.supabaseAdmin, userId)`.
+ */
+declare function deleteAccount<M extends AnyModels, D, F extends AnyFunctions, E, C>(betterSupabase: BetterSupabase<M, D, F, E, C>, service: SupabaseClient | (() => SupabaseClient), userId: string, options?: DeleteAccountOptions): AsyncResult<DeleteAccountResult>;
+//#endregion
+//#region src/server/lite.d.ts
+/** The `[db] driver` values Supabase Lite reads from `supabase/config.toml`. */
+type LiteDriver = "sqlite-postgres" | "sqlite" | "pglite" | "postgres";
+//#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 `ctx.sql`. */
+  pin(): void;
+}
+//#endregion
+//#region src/server/request-ids.d.ts
+interface RequestIdOptions {
+  readonly requestHeader?: string;
+  readonly correlationHeader?: string;
+  readonly incoming?: boolean;
+  readonly generate?: boolean;
+}
+//#endregion
+//#region src/auth/support.d.ts
+type SupportEndedBy = "admin" | "expired" | "revoked";
+/** A support session: a platform admin viewing the app as `targetUserId`. */
+interface SupportSession {
+  readonly id: string;
+  readonly adminId: string;
+  readonly targetUserId: string;
+  readonly reason: string;
+  /** Writes fail while it is true (`begin read only`). */
+  readonly readOnly: boolean;
+  readonly tenant?: string;
+  readonly startedAt: Temporal.Instant;
+  readonly expiresAt: Temporal.Instant;
+  readonly endedAt?: Temporal.Instant;
+  readonly endedBy?: SupportEndedBy;
+  /** App data, such as a ticket id. */
+  readonly metadata: Readonly<Record<string, unknown>>;
+}
+interface SupportStartInput {
+  readonly adminId: string;
+  /**
+   * The admin's verified claims. The SQL store runs `start_support_session`
+   * with them, so `is_platform()` checks the admin in the database too.
+   */
+  readonly adminClaims: Readonly<Record<string, unknown>>;
+  readonly targetUserId: string;
+  readonly reason: string;
+  readonly ttlSeconds: number;
+  readonly readOnly: boolean;
+  readonly tenant?: string;
+  readonly metadata: Readonly<Record<string, unknown>>;
+  /** The approved request this start uses, when the server found one. */
+  readonly requestId?: string;
+}
+/**
+ * A request for a support session that waits for a second admin. A start
+ * uses an approved request once; `approvedBy` is never `adminId`.
+ */
+interface SupportRequest {
+  readonly id: string;
+  readonly adminId: string;
+  readonly targetUserId: string;
+  readonly reason: string;
+  readonly readOnly: boolean;
+  readonly tenant?: string;
+  readonly metadata: Readonly<Record<string, unknown>>;
+  readonly requestedAt: Temporal.Instant;
+  /** An unapproved or unused request is closed after this. */
+  readonly expiresAt: Temporal.Instant;
+  readonly approvedBy?: string;
+  readonly approvedAt?: Temporal.Instant;
+  /** The session the approval started. */
+  readonly sessionId?: string;
+}
+interface SupportRequestInput {
+  readonly adminId: string;
+  /** The admin's verified claims; the SQL store asks as the admin with them. */
+  readonly adminClaims: Readonly<Record<string, unknown>>;
+  readonly targetUserId: string;
+  readonly reason: string;
+  readonly readOnly: boolean;
+  readonly tenant?: string;
+  readonly metadata: Readonly<Record<string, unknown>>;
+  /**
+   * An approver the server's authorization hook already decided, never the
+   * admin. The SQL store then records the request approved, over the admin
+   * connection.
+   */
+  readonly approvedBy?: string;
+}
+/** Who approves a request: with `claims` the store runs as them and decides eligibility itself. */
+interface SupportApprover {
+  readonly id: string;
+  readonly claims?: SupportCallerClaims;
+}
+/** What `approvedRequest` looks up. */
+interface SupportApprovalQuery {
+  readonly adminId: string;
+  readonly targetUserId: string;
+  readonly tenant?: string;
+  readonly readOnly: boolean;
+}
+/** A caller's verified claims, which the store runs a call with. */
+type SupportCallerClaims = Readonly<Record<string, unknown>>;
+interface SupportListFilter {
+  readonly adminId?: string;
+  readonly targetUserId?: string;
+  /** `true`: running sessions only; `false`: ended or expired ones only. */
+  readonly active?: boolean;
+  /** Defaults to 50. */
+  readonly limit?: number;
+}
+/**
+ * Where support sessions live. `sqlSupportStore` uses the `support-sessions`
+ * SQL module; implement this for another store and check it with
+ * `testSupportSessionStore` from `better-supabase/testing`.
+ */
+interface SupportSessionStore {
+  readonly apiVersion: 1;
+  readonly name: string;
+  /** Starts a session and ends the admin's previous one. Rejects when the store refuses. */
+  start(input: SupportStartInput): Promise<SupportSession>;
+  /**
+   * The admin's session while it is running; `undefined` once ended or
+   * expired. With the admin's `claims`, the store also checks that the admin
+   * may still start sessions.
+   */
+  get(sessionId: string, adminId: string, claims?: SupportCallerClaims): Promise<SupportSession | undefined>;
+  /**
+   * `false` when it was not running. With `claims`, it runs as that caller:
+   * the session's admin, or staff with the revoke permission.
+   */
+  end(sessionId: string, endedBy: SupportEndedBy, claims?: SupportCallerClaims): Promise<boolean>;
+  /** With `claims`, only what that caller may view. */
+  list(filter?: SupportListFilter, claims?: SupportCallerClaims): Promise<readonly SupportSession[]>;
+  /** The claims `targetUserId` would get, when the store can build them. */
+  claims?(targetUserId: string): Promise<Readonly<Record<string, unknown>>>;
+  /**
+   * Ends every running session past its expiry with `endedBy: "expired"`
+   * and returns them. Optional; `support.expire()` fails without it.
+   */
+  expire?(): Promise<readonly SupportSession[]>;
+  /**
+   * The store with `namespace` for its time values, unless it was given one
+   * itself. Optional; `createServer` calls it with the definition's
+   * `temporal`.
+   */
+  withTemporal?(namespace: typeof Temporal): SupportSessionStore;
+  /**
+   * Records a request for a session that waits for a second admin.
+   * Optional; without it and the two methods below, starts that need an
+   * approval are refused.
+   */
+  request?(input: SupportRequestInput): Promise<SupportRequest>;
+  /** A request by id, or `undefined`. */
+  getRequest?(requestId: string): Promise<SupportRequest | undefined>;
+  /** Approves a request. Rejects when the approver is the requester. */
+  approve?(requestId: string, approver: SupportApprover): Promise<SupportRequest>;
+  /** The approved, unused, unexpired request a start would use, or `undefined`. */
+  approvedRequest?(query: SupportApprovalQuery): Promise<SupportRequest | undefined>;
+}
+interface SqlSupportStoreOptions {
+  /** `blocks.support-sessions.schema`. Defaults to `better_supabase`. */
+  readonly schema?: string;
+  /**
+   * The Temporal namespace for the sessions' time values, for runtimes
+   * without a global one. Defaults to the one `createServer` passes from the
+   * definition, then the provided or global Temporal.
+   */
+  readonly temporal?: typeof Temporal;
+}
+/**
+ * Support sessions in the `support-sessions` SQL module. `start` runs
+ * as the admin, so the module's `is_platform()` gate applies; the reads run
+ * on the admin connection.
+ */
+declare function sqlSupportStore(postgres: Pick<BetterPostgres, "admin" | "asUser">, options?: SqlSupportStoreOptions): SupportSessionStore;
+/**
+ * The claims a support session runs with: the target's, plus `act` naming
+ * the admin, the reason and the session (the audit module records all three),
+ * marked `kind: "support"` so `actorOf` never reads it as an OAuth client.
+ * `role` falls back to `authenticated`; the admin's claims never leak in.
+ */
+declare function supportClaims(session: Pick<SupportSession, "id" | "adminId" | "targetUserId" | "reason" | "readOnly">, target: Readonly<Record<string, unknown>>): Record<string, unknown>;
+//#endregion
+//#region src/auth/support-cookie.d.ts
+/** The cookie that carries the support session id. */
+declare const SUPPORT_COOKIE = "bs-support";
+interface SupportCookieOptions {
+  /** Defaults to `bs-support`. */
+  readonly name?: string;
+  /** Defaults to `/`. */
+  readonly path?: string;
+  /** Defaults to true; set false for plain-HTTP local development. */
+  readonly secure?: boolean;
+}
+/** `Set-Cookie` for a session: HttpOnly, SameSite=Lax, gone when the session expires. */
+declare function supportCookie(session: Pick<SupportSession, "id" | "expiresAt">, options?: SupportCookieOptions, now?: number): string;
+/** `Set-Cookie` that removes the support cookie. */
+declare function clearSupportCookie(options?: SupportCookieOptions): string;
+/** The support session id in a `Cookie` header, or `undefined`. */
+declare function supportCookieValue(cookieHeader: string | null, name?: string): string | undefined;
+//#endregion
+//#region src/server/support.d.ts
+interface SupportPolicy {
+  /** Seconds a session lasts. Defaults to 1800 (30 minutes). */
+  readonly ttl?: number;
+  /** The longest `ttl` a start may ask for. Defaults to 14400 (4 hours). */
+  readonly maxTtl?: number;
+  /** Defaults to true. */
+  readonly requireReason?: boolean;
+  /**
+   * `always` (the default): every session is read-only. `default`: read-only
+   * unless the start passes `readOnly: false`.
+   */
+  readonly readOnly?: "always" | "default";
+  /**
+   * `distinct` (the default): a start needs a request that another admin
+   * approved (`support.request`, then `support.approve`), or an `authorize`
+   * decision of `{ approvedBy }` naming someone else. `none`: no second
+   * admin. Set `blocks.support-sessions.options.approval` to the same
+   * value, because the SQL store checks it again.
+   */
+  readonly approval?: "distinct" | "none";
+}
+interface SupportOptions {
+  readonly store: SupportSessionStore;
+  /**
+   * Whether `admin` may view the app as the target. Without it, the
+   * authorization hooks' `support.authorize` decides, and without those
+   * every start is refused (`SUPPORT_FORBIDDEN`). A throw or rejection
+   * counts as a deny. `true` still needs a second admin under
+   * `policy.approval: 'distinct'`; `{ approvedBy }` names that admin.
+   *
+   * `'store'` hands the decision to the store alone: the SQL store checks
+   * `is_platform(blocks["support-sessions"].permissions.start)` and nothing
+   * else, so use it only when that permission is the whole rule.
+   */
+  readonly authorize?: SupportAuthorize | "store";
+  /**
+   * The claims the target gets. Defaults to `store.claims` (the SQL store
+   * runs your custom access token hook), then `{ role: 'authenticated' }`.
+   */
+  readonly claims?: (targetUserId: string) => Readonly<Record<string, unknown>> | Promise<Readonly<Record<string, unknown>>>;
+  readonly policy?: SupportPolicy;
+  readonly cookie?: SupportCookieOptions;
+  /**
+   * Where a request names its support session, for apps that keep it in a
+   * header or their own request store instead of the `bs-support` cookie.
+   * Defaults to reading the cookie.
+   */
+  readonly sessionId?: (request: Request) => string | undefined;
+}
+interface SupportStartRequest {
+  readonly targetUserId: string;
+  readonly reason?: string;
+  /** Seconds; defaults to `policy.ttl`. */
+  readonly ttl?: number;
+  /** Honoured only with `policy.readOnly: 'default'`. */
+  readonly readOnly?: boolean;
+  readonly tenant?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Options for `support.expireRoute`. */
+interface SupportExpireRouteOptions {
+  /** The bearer token the cron caller sends, such as `process.env.CRON_SECRET`. */
+  readonly secret: string | undefined;
+  /** Rewrites the Problem Details bodies of the route's errors. */
+  readonly problem?: ProblemFormat;
+}
+/** A running support session, as the request that carries its cookie sees it. */
+interface ActiveSupport {
+  readonly session: SupportSession;
+  /** The admin behind the session, from their own verified token. */
+  readonly admin: {
+    readonly id: string;
+    readonly email?: string;
+  };
+  /** The target's claims plus `act`, which repositories run with. */
+  readonly claims: Readonly<Record<string, unknown>>;
+}
+/** `bs.support`: start, stop and inspect support sessions. */
+interface SupportApi {
+  /**
+   * Starts a session for a signed-in admin and returns it with the
+   * `Set-Cookie` value that switches the admin's next requests to the target.
+   */
+  start(admin: AuthState, request: SupportStartRequest): AsyncResult<{
+    readonly session: SupportSession;
+    readonly cookie: string;
+  }>;
+  /**
+   * Asks for a session that a second admin approves with `approve`; the
+   * policy checks of `start` apply. `ttl` is not stored: `start` passes it.
+   */
+  request(admin: AuthState, request: SupportStartRequest): AsyncResult<SupportRequest>;
+  /**
+   * Approves a request as `approver`, who is never the admin who asked. With
+   * the hooks' `approverOf`, it decides who may approve; otherwise the
+   * store does (the SQL store: the provider's `isApprover`, else the start
+   * permission).
+   */
+  approve(approver: AuthState, requestId: string): AsyncResult<SupportRequest>;
+  /** Ends the admin's own session and returns the `Set-Cookie` that clears the cookie. */
+  stop(admin: AuthState, sessionId: string): AsyncResult<{
+    readonly ended: boolean;
+    readonly cookie: string;
+  }>;
+  /**
+   * Ends a session as `caller`: the SQL store allows the session's admin and
+   * staff with the revoke permission.
+   */
+  revoke(caller: AuthState, sessionId: string): AsyncResult<boolean>;
+  /** The running session the request names (`sessionIdOf`) for `auth`, if any. */
+  current(request: Request, auth: AuthState): Promise<ActiveSupport | undefined>;
+  /**
+   * The running session `sessionId` for the admin in `auth`, if any. Use it
+   * when the app keeps the session id in its own request context; pass the
+   * result to `contextFor(auth, { support })` or `dbFor(auth, context, { support })`.
+   */
+  resolve(sessionId: string, auth: AuthState): Promise<ActiveSupport | undefined>;
+  /** The sessions `caller` may view (the SQL store checks the view permission). */
+  list(caller: AuthState, filter?: SupportListFilter): AsyncResult<readonly SupportSession[]>;
+  /**
+   * Ends every session past its expiry through the store and emits
+   * `support.ended` with `endedBy: "expired"` for each; the SQL store runs
+   * over `postgres.admin`. Returns the sessions it ended.
+   */
+  expire(): AsyncResult<readonly SupportSession[]>;
+  /**
+   * A `GET` or `POST` handler for a cron caller that runs `expire()` and
+   * answers `{ expired }`, the number of sessions it ended.
+   */
+  expireRoute(options: SupportExpireRouteOptions): (request: Request) => Promise<Response>;
+  /** The support session id a request names: `options.sessionId`, or the cookie. */
+  sessionIdOf(request: Request): string | undefined;
+  /** `Set-Cookie` that clears the support cookie. */
+  clearCookie(): string;
+}
+/** `ServerOptions.support`, from `supportSessions(options)`. */
+interface SupportSessions {
+  readonly options: SupportOptions;
+  /**
+   * Builds `bs.support`; `createServer` calls it once, with the definition's
+   * `temporal`, which goes on to the store's `withTemporal`, and the
+   * server's authorization hooks.
+   */
+  readonly create: (events: EventHub, claimsSchema: StandardSchemaV1 | undefined, temporal?: typeof Temporal, authorization?: AuthorizationHooks) => SupportApi;
+}
+/**
+ * Support sessions for `createServer(betterSupabase, { support })`. Apps that
+ * never import it don't bundle the support code.
+ */
+declare function supportSessions(options: SupportOptions): SupportSessions;
+//#endregion
+//#region src/server/suspend-account.d.ts
+interface EndSessionsResult {
+  readonly userId: string;
+  readonly ended: number;
+}
+interface SuspendAccountOptions {
+  readonly suspended: boolean;
+  /** A Go duration for the ban, such as `"24h"`. Defaults to 100 years. */
+  readonly duration?: string;
+  /**
+   * Also end the sessions when suspending. Defaults to `false`: the sessions
+   * stay, so Auth answers refresh and `/user` with `user_banned` and the app
+   * can show why. Without the `sessions` SQL module, an access token keeps
+   * working against the Data API until it expires; set this to end the
+   * sessions at once instead.
+   */
+  readonly endSessions?: boolean;
+}
+interface SuspendAccountResult {
+  readonly userId: string;
+  readonly suspended: boolean;
+  /**
+   * The sessions deleted: `0` on a suspension (unless `endSessions` is set),
+   * and the user's remaining sessions when the ban is lifted.
+   */
+  readonly ended: number;
+}
+declare function endSessions(sql: SqlClient, userId: string): AsyncResult<EndSessionsResult>;
+interface LastSignIn {
+  readonly userId: string;
+  /** `null` for a user who never signed in. */
+  readonly lastSignInAt: Temporal.Instant | null;
+}
+/**
+ * The last sign-in of each user, in one query (`better_supabase.last_sign_ins`
+ * from the `sessions` module, which only the service role may call). Users
+ * that don't exist are missing from the map.
+ */
+declare function lastSignIns(sql: SqlClient, userIds: readonly string[]): AsyncResult<ReadonlyMap<string, LastSignIn>>;
+declare function suspendAccount(service: SupabaseClient | (() => SupabaseClient), sql: SqlClient, userId: string, options: SuspendAccountOptions): AsyncResult<SuspendAccountResult>;
+//#endregion
+//#region src/server/server-types.d.ts
+/**
+ * PostgREST request settings for the caller's repositories and the shared
+ * service and anon clients, the `db` options supabase-js takes.
+ */
+interface ServerDbOptions {
+  /** Aborts each PostgREST request after this many milliseconds with a `timeout` error. */
+  readonly timeout?: number;
+  /**
+   * postgrest-js retries of idempotent requests (GET and HEAD) on network
+   * errors, 503 and 520. Defaults to postgrest-js's setting, which is on.
+   */
+  readonly retry?: boolean;
+  /**
+   * The longest query string one read sends. Defaults to the definition's
+   * `urlLengthLimit`, else 6000.
+   */
+  readonly urlLengthLimit?: number;
+}
+interface ServerOptions {
+  /**
+   * Defaults to the variables `getEnv` from `@supabase/middleware` reads:
+   * Workers bindings, then `process.env`, then `Deno.env`.
+   */
+  readonly env?: BetterSupabaseEnv;
+  /** Enables `ctx.sql` and `actingAs()`. */
+  readonly postgres?: BetterPostgres;
+  readonly auth?: Omit<ResolveAuthOptions, "env">;
+  /**
+   * `"lite"` for Supabase Lite: tokens verify with `SUPABASE_JWT_SECRET`, no
+   * JWKS prefetch, and `rpc()` is `unsupported` on its SQLite drivers.
+   */
+  readonly backend?: "supabase" | "lite";
+  /** Lite's `[db] driver`, default `sqlite-postgres`; `postgres` needs `postgres`. */
+  readonly liteDriver?: LiteDriver;
+  /**
+   * Fetch the JWKS when the server is created, so the first request verifies
+   * its token without waiting for it. Applies when neither `auth.jwks` nor
+   * `env.jwks` (`SUPABASE_JWKS`) holds the keys inline. Defaults to true, except under `NODE_ENV=test`.
+   */
+  readonly prefetchJwks?: boolean;
+  /**
+   * 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>>;
+  readonly requestIds?: RequestIdOptions | false;
+  /**
+   * 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;
+  /**
+   * `fetch` for the PostgREST and supabase-js clients, e.g. `tracedFetch()`
+   * from `better-supabase/otel`. Auth refreshes use `auth.fetch`.
+   */
+  readonly fetch?: typeof globalThis.fetch;
+  readonly replicas?: {
+    /** How long the next requests read from the primary after a write. Defaults to 5 s. */
+    readonly pinMs?: number;
+  };
+  /**
+   * The active tenant of a request when it doesn't come from a claim, e.g.
+   * from a URL slug (`blocks.access.activeTenant: 'resolver'`). It becomes
+   * `context.tenant` for the `tenant()` plugin, the `better_supabase.tenant`
+   * setting over Postgres and the `x-bs-tenant` header over PostgREST, which
+   * `current_tenant_id()` reads only while the caller is a member. Async
+   * resolvers need `context(request)`; `contextFromResolution` takes
+   * `options.tenant` instead. Under `createNext`, Server Components and
+   * actions pass a request with the incoming headers and a placeholder URL,
+   * so read a header there, not the path.
+   */
+  readonly tenant?: (request: Request, auth: AuthState) => string | undefined | PromiseLike<string | undefined>;
+  /**
+   * Support sessions ("view as user") from `supportSessions(options)`: a platform admin's requests that carry
+   * the support cookie run as the target user, read-only by default. Needs
+   * `postgres`, since the target's queries run over direct Postgres.
+   */
+  readonly support?: SupportSessions;
+  /**
+   * The claims `forContext()` adds for a user, the ones a custom access token
+   * hook would put in their token (roles, organization lists). Read them
+   * fresh: a job can run after the user lost access. `sub`, `role`, `act` and
+   * `tenant_id` come from the context and win.
+   */
+  readonly claimsFor?: (userId: string, context: RequestContext) => SqlClaims | PromiseLike<SqlClaims>;
+  /** PostgREST request settings: `timeout`, `retry` and `urlLengthLimit`. */
+  readonly db?: ServerDbOptions;
+  /**
+   * Resolves the `credential_ref`s third-party calls use, e.g.
+   * `vaultCredentials()` from `better-supabase/credentials`. It becomes
+   * `ctx.credentials`; pass `subjectFor(ctx)` as the subject.
+   */
+  readonly credentials?: CredentialProvider;
+  /**
+   * Where the server's audit trail goes, such as `audit.sink()` from
+   * `better-supabase/blocks/audit`. `suspendAccount`, `deleteAccount` and
+   * `endSessions` send `dev.better-supabase.account.*` CloudEvents, and
+   * `support.denied` events are forwarded. A failed send is logged and never
+   * fails the action.
+   */
+  readonly audit?: EventSink;
+  /**
+   * The authorization decision point (`Authorizer` v1) that resources,
+   * actions, routes and MCP tools ask for their `permission`. Without one, a
+   * declared permission denies.
+   */
+  readonly authorizer?: AnyAuthorizer;
+  /**
+   * The runtime hooks of an authorization provider (`AuthorizationHooks`
+   * v1). Support sessions read `support.authorize` and `approverOf`, and
+   * `forContext` reads `tickets.subject`, when their own options are unset.
+   */
+  readonly authorization?: AuthorizationHooks;
+}
+interface ForContextOptions {
+  /** Recorded as `act.reason` when the context carries an impersonator. Defaults to `"job"`. */
+  readonly reason?: string;
+  /**
+   * Resolves a context's `ticket` into the context the work runs as.
+   * Defaults to `ServerOptions.authorization.tickets.subject`.
+   */
+  readonly ticket?: TicketSubject;
+  /**
+   * The permission keys the work may use (`*` and `prefix.*` match as in
+   * grants). Set as the `bs_permission_cap` claim, which the access
+   * functions check through `better_supabase.cap_allows`, so a key outside
+   * the cap is refused even when the user holds it. A cap the context
+   * already carries is narrowed, never widened.
+   */
+  readonly permissions?: readonly string[];
+}
+/** The header `current_tenant_id()` reads over the Data API. */
+declare const TENANT_HEADER = "x-bs-tenant";
+interface ServerContext<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> {
+  readonly auth: AuthState<C, P>;
+  readonly resolution: AuthResolution<C, P>;
+  /**
+   * supabase-js client scoped to the caller (RLS applies). Throws in a
+   * support session: Realtime, Storage and Auth would act as the admin.
+   */
+  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;
+  /**
+   * `response` with this request's cookies: refreshed session cookies
+   * (`resolution.apply`) and, after a write, `bs-primary-until`.
+   */
+  apply(response: Response): Response;
+  /**
+   * The cookies `apply` would set, for frameworks that write cookies through
+   * a cookie store instead of a response (`cookies().set`, `setResponseHeaders`).
+   * Read it after the handler ran: a write adds `bs-primary-until`.
+   */
+  cookies(): readonly CookieWrite[];
+  /**
+   * Set while an admin views the app as another user: `auth`, `db` and
+   * `sql` are the target's, and `resolution` stays the admin's.
+   */
+  readonly support?: ActiveSupport;
+  /**
+   * Set in a support session, where `ctx.supabase` throws: Storage read as
+   * the target, with the file API of `supabase.storage`. Listings, `exists`
+   * and `info` run over Postgres as the target; downloads and signed URLs
+   * are checked there, then served with the service client. Writes are
+   * refused. Needs `SUPABASE_SECRET_KEY`.
+   */
+  readonly storage?: StorageApi;
+  /** `options.credentials`, when the server has one. */
+  readonly credentials?: CredentialProvider;
+  readonly requestId?: string;
+  readonly correlationId?: string;
+}
+interface ContextOptions {
+  readonly refresh?: boolean;
+  /** Read the session cookie. Defaults to true; `false` resolves bearer tokens only. */
+  readonly cookies?: 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;
+  /** The active tenant, instead of `ServerOptions.tenant`. */
+  readonly tenant?: string;
+  /**
+   * The request's support session, from `support.current()`. `context()`
+   * looks it up itself; `contextFromResolution` only uses this.
+   */
+  readonly support?: ActiveSupport;
+  readonly requestId?: string;
+  readonly correlationId?: string;
+}
+interface BetterServer<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> {
+  readonly env: BetterSupabaseEnv;
+  /** The definition's events; adapters pass `events.settled()` to `waitUntil`. */
+  readonly events: EventHub;
+  resolve(request: Request, options?: {
+    readonly refresh?: boolean;
+    readonly cookies?: boolean;
+    readonly checkSession?: boolean;
+  }): Promise<AuthResolution<C, P>>;
+  /**
+   * Resolves auth and binds repositories to the caller. Refreshes an expired
+   * cookie session only with `refresh: true`; send `ctx.apply(response)`.
+   */
+  context(request: Request, options?: ContextOptions): Promise<ServerContext<M, F, E, C, P>>;
+  /**
+   * The context for a resolution from `resolve(request)`, so one resolution
+   * can back several contexts without verifying the token again.
+   */
+  contextFromResolution(resolution: AuthResolution<C, P>, request: Request, options?: Omit<ContextOptions, "refresh">): ServerContext<M, F, E, C, P>;
+  /** The context for an auth state resolved elsewhere (the proxy, a queue message). */
+  contextFor(auth: AuthState<C, P>, options?: ContextOptions): ServerContext<M, F, E, C, P>;
+  /** 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). With
+   * `options.support`, from `support.resolve()` or `support.current()`, they
+   * run as the support session's target, like `contextFor(auth, { support }).db`.
+   */
+  dbFor(auth: AuthState, context?: RequestContext, options?: {
+    readonly support?: ActiveSupport;
+  }): 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: the Auth user, then their objects in `buckets`, then a
+   * `mutation` notice for `auth.users`. Needs the secret key. With
+   * `postgres`, a delete the database refuses returns its own error and
+   * hint. Access tokens already issued stay valid until they expire.
+   */
+  deleteAccount(userId: string, options?: DeleteAccountOptions): AsyncResult<DeleteAccountResult>;
+  endSessions(userId: string): AsyncResult<EndSessionsResult>;
+  /**
+   * Bans the user in Auth and keeps their sessions, so Auth answers with
+   * `user_banned` (`endSessions: true` deletes them too). Lifting the ban
+   * ends the sessions first, so the user signs in again.
+   */
+  suspendAccount(userId: string, options: SuspendAccountOptions): AsyncResult<SuspendAccountResult>;
+  /**
+   * Repositories running as a user, with RLS, over direct Postgres. With
+   * `impersonation`, the claims carry `act: { kind: "impersonation", sub, reason }`, which
+   * the `audit` and `actor` SQL modules record.
+   */
+  actingAs(userId: string, claims?: Omit<SqlClaims, "sub" | "act">, impersonation?: ImpersonationOptions): Db<M, F, E, undefined>;
+  /**
+   * Repositories for the user in a recorded context (`job.context`), with
+   * RLS, over direct Postgres: `actingAs` with the context's tenant and
+   * `ServerOptions.claimsFor`. A delegated token's `client_id`, `scope`,
+   * `authorization_details` and `act` chain go back into the claims, so
+   * the work stays as narrow as the token that queued it; `claimsFor`
+   * can't set them. A context with a `ticket` runs as the context
+   * `options.ticket` or `authorization.tickets.subject` resolves it to.
+   * Fails with `forbidden` when the actor is not a user, the `act` chain
+   * or delegation is malformed, or the ticket has no resolver or is
+   * refused; it never falls back to the recorded actor or `admin()`.
+   */
+  forContext(context: RequestContext, options?: ForContextOptions): AsyncResult<Db<M, F, E, undefined>>;
+  /** Support sessions; every method fails without `ServerOptions.support`. */
+  readonly support: SupportApi;
+  /** `options.authorizer`, when the server has one. */
+  readonly authorizer: AnyAuthorizer | undefined;
+  /** `options.authorization`, when the server has one. */
+  readonly authorization: AuthorizationHooks | undefined;
+}
+type ServerKeys = keyof BetterServer<AnyModels, AnyFunctions, unknown>;
+//#endregion
+export { SupportApprovalQuery as A, sqlSupportStore as B, supportSessions as C, supportCookie as D, clearSupportCookie as E, SupportRequest as F, LiteDriver as G, RequestIdOptions as H, SupportRequestInput as I, deleteAccount as J, DeleteAccountOptions as K, SupportSession as L, SupportCallerClaims as M, SupportEndedBy as N, supportCookieValue as O, SupportListFilter as P, SupportSessionStore as R, SupportStartRequest as S, SupportCookieOptions as T, PRIMARY_COOKIE as U, supportClaims as V, ReplicaState as W, SupportApi as _, ServerDbOptions as a, SupportPolicy as b, TENANT_HEADER as c, SuspendAccountOptions as d, SuspendAccountResult as f, ActiveSupport as g, suspendAccount as h, ServerContext as i, SupportApprover as j, SqlSupportStoreOptions as k, EndSessionsResult as l, lastSignIns as m, ContextOptions as n, ServerKeys as o, endSessions as p, DeleteAccountResult as q, ForContextOptions as r, ServerOptions as s, BetterServer as t, LastSignIn as u, SupportExpireRouteOptions as v, SUPPORT_COOKIE as w, SupportSessions as x, SupportOptions as y, SupportStartInput as z };