better-supabase 0.13.0 → 0.15.0

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

@@ -0,0 +1,946 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult } from "./result-DZeA5KS6.js";
+import { Ft as RequestContext, O as AnyFunctions, k as AnyModels } from "./types-DFdg_4yN.js";
+import { o as EventHub } from "./events-vcqenSYU.js";
+import { o as EnvSource, t as BetterSupabaseEnv } from "./index-NRMMhhEi.js";
+import { a as ResolveAuthOptions, m as CookieWrite, o as ResolvePhase, r as AuthState, t as AuthResolution } from "./resolve-CXX6DHv3.js";
+import { r as CredentialProvider } from "./provider-CqwEOLCA.js";
+import { n as SqlClient } from "./executor-hGjrop3A.js";
+import { a as ProblemFormat } from "./problem-DNwN8iGz.js";
+import { c as AuthzVersionCache, t as AnyAuthorizer, u as RequestMemo } from "./authorizer-B6X09otb.js";
+import { J as DbStats, X as StatsRecorder, t as BetterSupabase, v as Db } from "./define-DFBnQyYg.js";
+import { k as StorageApi, n as Bucket } from "./bucket-CiNi8sIw.js";
+import { t as ImpersonationOptions } from "./impersonation-YTa9dZUv.js";
+import { i as EventSink } from "./cloud-event-CzZTJkXv.js";
+import { _ as SupportAuthorize, b as TicketSubject, i as AuthorizationHooks } from "./authorization-hooks-Cs1vP_ej.js";
+import { s as SqlClaims, t as BetterPostgres } from "./pool-CrtT4dg-.js";
+import { SupabaseClient } from "@supabase/supabase-js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+import { JWTClaims } from "@supabase/server";
+//#region src/auth/snapshot.d.ts
+/**
+ * A verified user session, frozen and serializable. Times are epoch seconds,
+ * like `AuthSession.expiresAt`, because the snapshot crosses `use cache`
+ * serialization (ADR 0095).
+ */
+interface SessionSnapshot<C = unknown> {
+  readonly accessToken: string;
+  readonly claims: Readonly<JWTClaims & C>;
+  /** The Auth session id (`session_id`), or `null` for tokens without one. */
+  readonly sessionId: string | null;
+  readonly userId: string;
+  /** Seconds since epoch, from `exp`. */
+  readonly expiresAt: number | null;
+  /** Seconds since epoch, from `iat`. */
+  readonly issuedAt: number | null;
+  /** The `authz_ver` claim, or `null` when the token has none. */
+  readonly authzVersion: number | null;
+}
+/** Verified JWT claims, read by name. */
+type Claims = Readonly<Record<string, unknown>>;
+/** The `iat` claim in epoch seconds, or `null`. */
+declare function issuedAtOf(claims: Claims): number | null;
+/** The `authz_ver` claim as a number, or `null` when absent or malformed. */
+declare function authzVersionOf(claims: Claims): number | null;
+/**
+ * Whether `value` is a snapshot this process built from a verified token. A
+ * snapshot that crossed serialization, or was built by hand, is not.
+ */
+declare function isSessionSnapshot(value: unknown): value is SessionSnapshot;
+/** The snapshot of a verified user, or `null` for any other caller. */
+declare function snapshotOf<C, P>(auth: AuthState<C, P>): SessionSnapshot<C> | null;
+/**
+ * A stable cache key for a session: user, Auth session and authorization
+ * version. It never contains the token, which rotates hourly and would churn
+ * every key.
+ */
+declare function sessionCacheKey(snapshot: Pick<SessionSnapshot, "userId" | "sessionId" | "authzVersion">): string;
+interface SessionMemoOptions {
+  /** The most sessions kept; the least recently used goes first. Default: 1000. */
+  readonly max?: number;
+  /**
+   * Milliseconds an entry lives at most. It never outlives the token's `exp`.
+   * Default: 300000 (5 minutes).
+   */
+  readonly ttlMs?: number;
+  /** Epoch milliseconds. */
+  readonly now?: () => number;
+}
+interface SessionMemoStats {
+  /** Lookups answered by a stored or in-flight verification. */
+  readonly hits: number;
+  /** Lookups that ran a verification. */
+  readonly misses: number;
+  readonly size: number;
+}
+/**
+ * Verified sessions by a SHA-256 of the access token. Every `use cache` scope
+ * of a request resolves the same token; the first one verifies it and the
+ * others await the same promise.
+ */
+interface SessionMemo<T> {
+  /**
+   * The stored value for `token`, else `load()`'s. A `null` result is not
+   * stored. Read the clock (call this) only after the request's dynamic APIs
+   * (`cookies()`) have been awaited.
+   */
+  get(token: string, load: () => Promise<T | null>): Promise<T | null>;
+  /** Stores a value verified elsewhere (a refresh, a sign-in). */
+  seed(token: string, value: T): Promise<void>;
+  /** Drops every entry `match` returns true for (a user's sessions). */
+  evict(match: (value: T) => boolean): void;
+  clear(): void;
+  stats(): SessionMemoStats;
+}
+/**
+ * A bounded LRU of verified sessions. Keys derive only from the token, never
+ * from a user id or a header, so one instance can serve many users at once
+ * (Fluid compute). Create it once at module scope; `createServer` owns one.
+ */
+declare function sessionMemo<T>(expiresAt: (value: T) => number | null, options?: SessionMemoOptions): SessionMemo<T>;
+//#endregion
+//#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 = "bsb-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 `impersonation` 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.impersonation.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 `impersonation` 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 = "bsb-support";
+interface SupportCookieOptions {
+  /** Defaults to `bsb-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.impersonation.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['impersonation'].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 `bsb-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>>;
+}
+/** `bsb.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 `bsb.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 {
+  /**
+   * A loaded env, or the variables to load it from (`{ SUPABASE_URL, ... }`),
+   * read without falling back to the runtime's. Defaults to the variables
+   * `getEnv` from `@supabase/middleware` reads: Workers bindings, then
+   * `process.env`, then `Deno.env`.
+   */
+  readonly env?: BetterSupabaseEnv | EnvSource;
+  /** 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.permissions.activeTenant: 'resolver'`). It becomes
+   * `context.tenant` for `membershipsExtension()`, the `better_supabase.tenant`
+   * setting over Postgres and the `x-bsb-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;
+  /**
+   * The authorization library's version cache, created once at module scope. It
+   * reaches every authorizer decision (`AuthorizerRuntime.versions`), and
+   * `invalidateSession` evicts the user from it.
+   */
+  readonly versions?: AuthzVersionCache;
+  /**
+   * The verified-session memo `snapshot()` and adapters share across cache
+   * scopes: size and lifetime, or `false` to verify in every scope.
+   */
+  readonly sessions?: SessionMemoOptions | false;
+}
+/** The verified-session memo of a server (`server.sessions`). */
+interface ServerSessions<C = unknown, P = unknown> {
+  stats(): SessionMemoStats;
+  /**
+   * Stores a user verified elsewhere (the proxy after a refresh, a sign-in), so
+   * the render's first scope doesn't verify again.
+   */
+  seed(auth: AuthState<C, P>): Promise<void>;
+  /** Forgets a user's sessions (sign-out, role change). */
+  evict(userId: string): void;
+  clear(): void;
+}
+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 `bsb_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-bsb-tenant";
+interface ServerContext<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown, B = 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, B>;
+  /**
+   * Repositories over direct Postgres as the caller, when `postgres` is
+   * configured.
+   */
+  readonly sql: Db<M, F, E, undefined, B> | 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, `bsb-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 `bsb-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;
+  /** Work this context's permission checks share (`AuthorizerRuntime.memo`). */
+  readonly memo?: RequestMemo;
+}
+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 `bsb-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;
+}
+/**
+ * The repositories `bsb.admin()` returns: a secret-key `Db` with the Auth admin
+ * API.
+ */
+type AdminDb<M extends AnyModels, F extends AnyFunctions, E, B = unknown> = Db<M, F, E, SupabaseClient, B> & {
+  /**
+   * `auth.admin` of the secret-key client: create, invite, list, update and
+   * delete users. Request repositories have no such handle, since their client
+   * holds no secret key.
+   */
+  readonly $authAdmin: SupabaseClient["auth"]["admin"];
+};
+/**
+ * A server built by `createServer`, `createHono` or `createNext`, handed to
+ * another adapter to share.
+ */
+type SharedServer = Pick<BetterServer<AnyModels, AnyFunctions, unknown>, "env" | "events" | "resolve">;
+interface BetterServer<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown, B = 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;
+    /**
+     * With `refresh`, refresh a token expiring within this many seconds.
+     * Defaults to `auth.leeway`, else 60.
+     */
+    readonly leeway?: number;
+    /** Milliseconds per phase, for `Server-Timing`. */
+    readonly onTiming?: (phase: ResolvePhase, ms: number) => void;
+  }): 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, B>>;
+  /**
+   * 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, B>;
+  /**
+   * 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, B>;
+  /**
+   * 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, B>;
+  /**
+   * Service-role repositories. Bypasses RLS; the actor is `service`. With `as`,
+   * every request carries the `x-bsb-actor` header, so the audit log and
+   * `track_actor` columns record that user for writes the secret key makes.
+   * Only a service caller can set it; the database ignores it for anyone else.
+   */
+  admin(context?: RequestContext, options?: {
+    readonly as?: string;
+  }): AdminDb<M, F, E, B>;
+  /**
+   * 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, B>;
+  /**
+   * 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, B>>;
+  /** Support sessions; every method fails without `ServerOptions.support`. */
+  readonly support: SupportApi;
+  /** `options.authorizer`, when the server has one, bound to `options.versions`. */
+  readonly authorizer: AnyAuthorizer | undefined;
+  /** `options.authorization`, when the server has one. */
+  readonly authorization: AuthorizationHooks | undefined;
+  /** `options.versions`, when the server has one. */
+  readonly versions: AuthzVersionCache | undefined;
+  /**
+   * The verified session of a request, shared by every scope that resolves the
+   * same token: the first verifies it, the rest await that verification. `null`
+   * for anyone but a signed-in user with a valid token. Never refreshes.
+   */
+  snapshot(request: Request): Promise<SessionSnapshot<C> | null>;
+  /**
+   * The context of a session snapshot: stateless clients and the claims, with
+   * no cookie access and no network call. A snapshot this process didn't build
+   * (one that crossed serialization) is verified again through the memo; one
+   * whose token doesn't verify, or names another user, gets an `invalid`
+   * context. `null` (no session) gets an anonymous one.
+   */
+  contextFromSession(snapshot: SessionSnapshot<C> | null, options?: ContextOptions): Promise<ServerContext<M, F, E, C, P, B>>;
+  /** The verified-session memo behind `snapshot()`. */
+  readonly sessions: ServerSessions<C, P>;
+  /**
+   * Evicts the user from the session memo and `versions`. Adapters with a cache
+   * layer also invalidate its tags.
+   */
+  forgetSession(userId: string): Promise<void>;
+}
+type ServerKeys = keyof BetterServer<AnyModels, AnyFunctions, unknown>;
+//#endregion
+export { SessionMemoStats as $, supportCookieValue as A, SupportSessionStore as B, SupportSessions as C, SupportCookieOptions as D, SUPPORT_COOKIE as E, SupportEndedBy as F, PRIMARY_COOKIE as G, sqlSupportStore as H, SupportListFilter as I, DeleteAccountOptions as J, ReplicaState as K, SupportRequest as L, SupportApprovalQuery as M, SupportApprover as N, clearSupportCookie as O, SupportCallerClaims as P, SessionMemoOptions as Q, SupportRequestInput as R, SupportPolicy as S, supportSessions as T, supportClaims as U, SupportStartInput as V, RequestIdOptions as W, deleteAccount as X, DeleteAccountResult as Y, SessionMemo as Z, suspendAccount as _, ServerContext as a, sessionMemo as at, SupportExpireRouteOptions as b, ServerOptions as c, EndSessionsResult as d, SessionSnapshot as et, LastSignIn as f, lastSignIns as g, endSessions as h, ForContextOptions as i, sessionCacheKey as it, SqlSupportStoreOptions as j, supportCookie as k, SharedServer as l, SuspendAccountResult as m, BetterServer as n, isSessionSnapshot as nt, ServerDbOptions as o, snapshotOf as ot, SuspendAccountOptions as p, LiteDriver as q, ContextOptions as r, issuedAtOf as rt, ServerKeys as s, AdminDb as t, authzVersionOf as tt, TENANT_HEADER as u, ActiveSupport as v, SupportStartRequest as w, SupportOptions as x, SupportApi as y, SupportSession as z };