better-supabase 0.2.0 → 0.4.0

package/dist/{mfa-CpLfJSde.js → mfa-byfjruR9.js}

@@ -1,5 +1,6 @@
-import { n as dbError } from "./errors-Bl3rkOzo.js";
+import { n as dbError } from "./errors-L0xK41y_.js";
 import { t as consoleLogger } from "./logger-glM28NVN.js";
+import { n as decodeJwtPayload } from "./base64-D2gsioCY.js";
 import { DEFAULT_COOKIE_OPTIONS, createChunks, isChunkLike, parseCookieHeader, serializeCookieHeader, stringFromBase64URL, stringToBase64URL } from "@supabase/ssr";
 import { extractCredentials, verifyCredentials } from "@supabase/server/core";
 //#region src/auth/impersonation.ts
@@ -22,6 +23,65 @@ function impersonatorOf(claims) {
 	} : { id: sub };
 }
 //#endregion
+//#region src/auth/actor.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function copyAct(level) {
+	const entries = Object.entries(level).map(([key, value]) => [key, key === "act" && isRecord(value) ? copyAct(value) : value]);
+	return Object.fromEntries(entries);
+}
+/**
+* Reads only `act` and `client_id`, the way PermDock's `actorOf` does. An
+* `act` that is not a chain of objects each with a non-empty `sub` is
+* `{ ok: false }`: the session must not pass as the user alone.
+*/
+function actorOf(claims) {
+	const outer = claims["act"];
+	if (outer !== void 0) {
+		let level = outer;
+		while (level !== void 0) {
+			if (!isRecord(level)) return {
+				ok: false,
+				reason: "invalid-chain"
+			};
+			const sub = level["sub"];
+			if (typeof sub !== "string" || sub === "") return {
+				ok: false,
+				reason: "invalid-chain"
+			};
+			level = level["act"];
+		}
+		if (!isRecord(outer) || typeof outer["sub"] !== "string") return {
+			ok: false,
+			reason: "invalid-chain"
+		};
+		return {
+			ok: true,
+			actor: {
+				id: outer["sub"],
+				kind: "oauth-client",
+				chain: copyAct(outer)
+			}
+		};
+	}
+	const client = claims["client_id"];
+	if (typeof client === "string" && client !== "") return {
+		ok: true,
+		actor: {
+			id: client,
+			kind: "oauth-client"
+		}
+	};
+	return { ok: true };
+}
+/** The OAuth `scope` claim (a space-separated string or a list); `undefined` when empty. */
+function delegationOf(claims) {
+	const scope = claims["scope"];
+	const scopes = typeof scope === "string" ? scope.split(/\s+/u).filter(Boolean) : Array.isArray(scope) ? scope.filter((item) => typeof item === "string") : [];
+	return scopes.length > 0 ? { scopes } : void 0;
+}
+//#endregion
 //#region src/auth/refresh.ts
 /**
 * How long a finished refresh is reused for requests still carrying the old
@@ -29,6 +89,7 @@ function impersonatorOf(claims) {
 * refresh-token reuse interval of Supabase Auth.
 */
 const REUSE_MS = 1e4;
+const DEFAULT_TIMEOUT_MS = 5e3;
 const inflight = /* @__PURE__ */ new Map();
 const recent = /* @__PURE__ */ new Map();
 function shared(outcome) {
@@ -38,10 +99,14 @@ function shared(outcome) {
 	} : outcome;
 }
 function prune(now) {
-	for (const [token, entry] of recent) if (entry.until <= now) recent.delete(token);
+	for (const [token, entry] of recent) {
+		if (entry.until > now) return;
+		recent.delete(token);
+	}
 }
 async function request(refreshToken, options, now) {
 	const doFetch = options.fetch ?? fetch;
+	const signal = AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
 	let response;
 	try {
 		response = await doFetch(`${options.url}/auth/v1/token?grant_type=refresh_token`, {
@@ -51,7 +116,8 @@ async function request(refreshToken, options, now) {
 				"content-type": "application/json",
 				...options.forwardedFor ? { "sb-forwarded-for": options.forwardedFor.ip } : {}
 			},
-			body: JSON.stringify({ refresh_token: refreshToken })
+			body: JSON.stringify({ refresh_token: refreshToken }),
+			signal
 		});
 	} catch (cause) {
 		return {
@@ -61,6 +127,11 @@ async function request(refreshToken, options, now) {
 		};
 	}
 	const body = await response.json().catch(() => null);
+	if (signal.aborted) return {
+		ok: false,
+		reason: "network",
+		message: "refresh timed out"
+	};
 	if (!response.ok || !body || typeof body["access_token"] !== "string" || typeof body["refresh_token"] !== "string") {
 		const message = typeof body?.["msg"] === "string" ? body["msg"] : typeof body?.["error_description"] === "string" ? body["error_description"] : `Refresh failed with ${String(response.status)}`;
 		return {
@@ -94,12 +165,16 @@ function refreshSession(refreshToken, options) {
 	const pending = inflight.get(refreshToken);
 	if (pending) return pending.then(shared);
 	const promise = request(refreshToken, options, now).then((outcome) => {
-		inflight.delete(refreshToken);
-		if (outcome.ok) recent.set(refreshToken, {
-			outcome,
-			until: now + REUSE_MS
-		});
+		if (outcome.ok || outcome.reason === "rejected") {
+			recent.delete(refreshToken);
+			recent.set(refreshToken, {
+				outcome,
+				until: now + REUSE_MS
+			});
+		}
 		return outcome;
+	}).finally(() => {
+		inflight.delete(refreshToken);
 	});
 	inflight.set(refreshToken, promise);
 	return promise;
@@ -115,8 +190,15 @@ const AUTH_CACHE_HEADERS = {
 };
 /** `sb-<first label of the hostname>-auth-token`, the supabase-js default. */
 function sessionCookieName(url) {
-	return `sb-${new URL(url).hostname.split(".")[0] ?? ""}-auth-token`;
+	let name = cookieNames.get(url);
+	if (name === void 0) {
+		name = `sb-${new URL(url).hostname.split(".")[0] ?? ""}-auth-token`;
+		if (cookieNames.size < 16) cookieNames.set(url, name);
+	}
+	return name;
 }
+/** Project URLs come from configuration, so a handful of entries suffice. */
+const cookieNames = /* @__PURE__ */ new Map();
 function parseCookies(header) {
 	return header ? parseCookieHeader(header) : [];
 }
@@ -191,20 +273,9 @@ function applyCookieWrites(cookies, writes) {
 }
 //#endregion
 //#region src/auth/resolve.ts
-function decodePayload(token) {
-	const part = token.split(".")[1];
-	if (!part) return void 0;
-	try {
-		const json = atob(part.replace(/-/g, "+").replace(/_/g, "/"));
-		const parsed = JSON.parse(json);
-		return typeof parsed === "object" && parsed !== null ? parsed : void 0;
-	} catch {
-		return;
-	}
-}
 function expiryOf(session) {
 	if (typeof session.expires_at === "number") return session.expires_at;
-	const exp = decodePayload(session.access_token)?.["exp"];
+	const exp = decodeJwtPayload(session.access_token)?.["exp"];
 	return typeof exp === "number" ? exp : void 0;
 }
 function serverEnv(options) {
@@ -248,8 +319,31 @@ function remembered(memo, token, now) {
 	memo.set(token, hit);
 	return hit;
 }
-function remember(memo, token, user) {
-	if (user.expiresAt === null) return;
+const NO_SCHEMA = {};
+const checkedByMemo = /* @__PURE__ */ new WeakMap();
+/**
+* Tokens that already passed (or failed) the claims and `userMetadata`
+* schemas, per verification memo and schema pair, so a memo hit skips
+* validation too.
+*/
+function checkedFor(memo, options) {
+	const claims = options.claims ?? NO_SCHEMA;
+	const metadata = options.userMetadata ?? NO_SCHEMA;
+	let byClaims = checkedByMemo.get(memo);
+	if (!byClaims) checkedByMemo.set(memo, byClaims = /* @__PURE__ */ new WeakMap());
+	let byMetadata = byClaims.get(claims);
+	if (!byMetadata) byClaims.set(claims, byMetadata = /* @__PURE__ */ new WeakMap());
+	let checked = byMetadata.get(metadata);
+	if (!checked) byMetadata.set(metadata, checked = /* @__PURE__ */ new Map());
+	return checked;
+}
+function withoutSource(state) {
+	if (state.kind !== "user") return state;
+	const { source: _source, ...rest } = state;
+	return rest;
+}
+function remember(memo, token, user, expiresAt) {
+	if (expiresAt === null) return;
 	memo.set(token, user);
 	if (memo.size > MEMO_SIZE) memo.delete(memo.keys().next().value);
 }
@@ -258,10 +352,20 @@ async function verify(credentials, modes, options, source) {
 	const memo = token ? memoFor(options) : void 0;
 	if (token && memo) {
 		const hit = remembered(memo, token, Math.floor((options.now ?? Date.now)() / 1e3));
-		if (hit) return checkUser({
-			...hit,
-			source
-		}, options);
+		if (hit) {
+			const checked = checkedFor(memo, options);
+			const known = checked.get(token);
+			if (known) return known.kind === "user" ? {
+				...known,
+				source
+			} : known;
+			const state = await checkUser({
+				...hit,
+				source
+			}, options);
+			remember(checked, token, withoutSource(state), hit.expiresAt);
+			return state;
+		}
 	}
 	const state = await verifyOnce(credentials, modes, options, source);
 	if (token && memo && state.kind === "user") remember(memo, token, {
@@ -270,12 +374,20 @@ async function verify(credentials, modes, options, source) {
 		claims: state.claims,
 		user: state.user,
 		expiresAt: state.expiresAt
-	});
-	return checkUser(state, options);
+	}, state.expiresAt);
+	const checked = await checkUser(state, options);
+	if (token && memo && state.kind === "user") remember(checkedFor(memo, options), token, withoutSource(checked), state.expiresAt);
+	return checked;
 }
 /** Validates a user's claims against `options.claims`, keeping every JWT claim. */
 async function checkClaims(state, options) {
-	if (state.kind !== "user" || !options.claims) return state;
+	if (state.kind !== "user") return state;
+	if (!actorOf(state.claims).ok) return {
+		kind: "invalid",
+		reason: "actor",
+		error: dbError("unauthorized", "The token's act claim is not a chain of actors with a sub", { code: "ACTOR_INVALID" })
+	};
+	if (!options.claims) return state;
 	let outcome = options.claims["~standard"].validate(state.claims);
 	if (outcome instanceof Promise) outcome = await outcome;
 	if (outcome.issues) {
@@ -313,16 +425,40 @@ async function checkUser(state, options) {
 	};
 	if (!warnedMetadata.has(schema)) {
 		warnedMetadata.add(schema);
-		(options.logger ?? consoleLogger).warn("user_metadata does not match sb.userMetadata(schema); session.profile is undefined", { paths: outcome.issues.map((issue) => issue.path?.map((segment) => typeof segment === "object" ? String(segment.key) : String(segment)).join(".") ?? "") });
+		(options.logger ?? consoleLogger).warn("user_metadata does not match betterSupabase.userMetadata(schema); session.profile is undefined", { paths: outcome.issues.map((issue) => issue.path?.map((segment) => typeof segment === "object" ? String(segment.key) : String(segment)).join(".") ?? "") });
 	}
 	return user;
 }
+/** A token whose `kid` matches no key: verifying it loads the JWKS and fails. */
+const PREFETCH_TOKEN = `${base64url(JSON.stringify({
+	alg: "ES256",
+	kid: "better-supabase-prefetch",
+	typ: "JWT"
+}))}.e30.AA`;
+function base64url(text) {
+	return btoa(text).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+/**
+* Loads the remote JWKS into the verifier's cache so the first request
+* doesn't wait for it. Never throws; a failure leaves the first request to
+* fetch it as before.
+*/
+function prefetchJwks(options) {
+	if (options.jwks !== void 0) return Promise.resolve();
+	return verifyCredentials({
+		token: PREFETCH_TOKEN,
+		apikey: null
+	}, {
+		auth: ["user"],
+		env: serverEnv(options)
+	}).then(() => {}, () => {});
+}
 async function verifyOnce(credentials, modes, options, source) {
 	const { data, error } = await verifyCredentials(credentials, {
 		auth: modes,
 		env: serverEnv(options),
-		...options.audience !== void 0 ? { audience: options.audience } : {},
-		...options.issuer !== void 0 ? { issuer: options.issuer } : {}
+		...options.audience === void 0 ? {} : { audience: options.audience },
+		...options.issuer === void 0 ? {} : { issuer: options.issuer }
 	});
 	if (error) {
 		const kind = error.code === "JWKS_FETCH_FAILED" ? "network" : error.status >= 500 ? "unexpected" : "unauthorized";
@@ -351,11 +487,16 @@ async function verifyOnce(credentials, modes, options, source) {
 }
 function resolution(auth, cookies, writes = []) {
 	const headers = writes.length > 0 ? AUTH_CACHE_HEADERS : {};
+	let requestCookies;
 	return {
 		auth,
 		cookies: writes,
 		headers,
-		requestCookies: writes.length > 0 ? applyCookieWrites(cookies, writes) : cookies,
+		/** Parsed on first read: bearer requests rarely need their cookies. */
+		get requestCookies() {
+			requestCookies ??= writes.length > 0 ? applyCookieWrites(cookies(), writes) : cookies();
+			return requestCookies;
+		},
 		apply(response) {
 			if (writes.length === 0) return response;
 			let target = response;
@@ -385,7 +526,8 @@ function clientIp(request) {
 * set, through a single-flight request, and only then are cookies written.
 */
 async function resolveAuth(request, options) {
-	const cookies = parseCookies(request.headers.get("cookie"));
+	let parsed;
+	const cookies = () => parsed ??= parseCookies(request.headers.get("cookie"));
 	for (const resolver of options.resolvers ?? []) {
 		const state = await resolver.resolve(request);
 		if (!state) continue;
@@ -405,10 +547,10 @@ async function resolveAuth(request, options) {
 		apikey: credentials.apikey
 	}, options.secret === true ? ["secret"] : options.secret.map((name) => `secret:${name}`), options, "bearer"), cookies);
 	const name = options.cookie?.name ?? sessionCookieName(options.env.url);
-	const session = readSession(cookies, name);
+	const session = readSession(cookies(), name);
 	if (!session) {
-		const stale = cookies.some((cookie) => cookie.name === name || cookie.name.startsWith(`${name}.`));
-		const writes = stale && options.refresh ? writeSession(cookies, name, null, options.cookie?.options) : [];
+		const stale = cookies().some((cookie) => cookie.name === name || cookie.name.startsWith(`${name}.`));
+		const writes = stale && options.refresh ? writeSession(cookies(), name, null, options.cookie?.options) : [];
 		return resolution({
 			kind: "anon",
 			reason: stale ? "signed_out" : "none"
@@ -416,12 +558,13 @@ async function resolveAuth(request, options) {
 	}
 	const now = Math.floor((options.now ?? Date.now)() / 1e3);
 	const expiry = expiryOf(session);
-	if (expiry !== void 0 && expiry - (options.leeway ?? 60) > now) {
+	const leeway = options.refresh ? options.leeway ?? 60 : 0;
+	if (expiry !== void 0 && expiry - leeway > now) {
 		const state = await verify({
 			token: session.access_token,
 			apikey: null
 		}, ["user"], options, "cookie");
-		if (state.kind !== "invalid" || state.reason === "claims" || state.error.kind === "network") return resolution(state, cookies);
+		if (state.kind !== "invalid" || state.reason !== "token" || state.error.kind === "network") return resolution(state, cookies);
 		if (!options.refresh) return resolution({
 			kind: "anon",
 			reason: "signed_out"
@@ -441,7 +584,8 @@ async function resolveAuth(request, options) {
 			secretKey
 		} } : {},
 		...options.fetch ? { fetch: options.fetch } : {},
-		...options.now ? { now: options.now } : {}
+		...options.now ? { now: options.now } : {},
+		...options.refreshTimeoutMs === void 0 ? {} : { timeoutMs: options.refreshTimeoutMs }
 	});
 	options.onRefresh?.({
 		ok: outcome.ok,
@@ -456,9 +600,9 @@ async function resolveAuth(request, options) {
 		return resolution({
 			kind: "anon",
 			reason: "signed_out"
-		}, cookies, writeSession(cookies, name, null, options.cookie?.options));
+		}, cookies, writeSession(cookies(), name, null, options.cookie?.options));
 	}
-	const writes = writeSession(cookies, name, outcome.session, options.cookie?.options);
+	const writes = writeSession(cookies(), name, outcome.session, options.cookie?.options);
 	return resolution(await verify({
 		token: outcome.session.access_token,
 		apikey: null
@@ -473,8 +617,8 @@ function authContext(auth) {
 				actor: {
 					id: auth.user.id,
 					kind: "user",
-					...auth.user.role !== void 0 ? { role: auth.user.role } : {},
-					...auth.user.email !== void 0 ? { email: auth.user.email } : {},
+					...auth.user.role === void 0 ? {} : { role: auth.user.role },
+					...auth.user.email === void 0 ? {} : { email: auth.user.email },
 					...impersonator ? { impersonator: impersonator.id } : {}
 				},
 				claims: auth.claims
@@ -538,4 +682,4 @@ function checkAal(auth, required) {
 	});
 }
 //#endregion
-export { clientIp as a, applyCookieWrites as c, serializeCookie as d, sessionCookieName as f, impersonatorOf as g, actClaim as h, authContext as i, parseCookies as l, refreshSession as m, amrOf as n, resolveAuth as o, writeSession as p, checkAal as r, AUTH_CACHE_HEADERS as s, aalOf as t, readSession as u };
+export { delegationOf as _, clientIp as a, AUTH_CACHE_HEADERS as c, readSession as d, serializeCookie as f, actorOf as g, refreshSession as h, authContext as i, applyCookieWrites as l, writeSession as m, amrOf as n, prefetchJwks as o, sessionCookieName as p, checkAal as r, resolveAuth as s, aalOf as t, parseCookies as u, actClaim as v, impersonatorOf as y };

package/dist/next/image/index.js

@@ -21,13 +21,16 @@ const clamp = (value, min, max) => Math.min(max, Math.max(min, Math.round(value)
 */
 function createImageLoader(options) {
 	const storage = `${options.url.replace(/\/+$/, "")}/storage/v1`;
-	const publicPrefixes = [`${storage}/object/public/`, `${storage}/render/image/public/`];
+	const publicPrefixes = [`${storage}/object/public/`, `${storage}/render/image/public/`].map((prefix) => ({
+		prefix,
+		length: new URL(prefix).pathname.length
+	}));
 	const fallback = options.fallback ?? (({ src }) => src);
 	return (props) => {
-		const prefix = publicPrefixes.find((candidate) => props.src.startsWith(candidate));
+		const prefix = publicPrefixes.find((candidate) => props.src.startsWith(candidate.prefix));
 		if (prefix === void 0) return fallback(props);
 		const source = new URL(props.src);
-		const object = source.pathname.slice(new URL(prefix).pathname.length);
+		const object = source.pathname.slice(prefix.length);
 		const target = new URL(`${storage}/render/image/public/${object}`);
 		for (const [key, value] of source.searchParams) target.searchParams.set(key, value);
 		target.searchParams.set("width", String(clamp(props.width, 1, MAX_WIDTH)));

package/dist/next/index.d.ts

@@ -1,12 +1,12 @@
-import { n as AnyModels, t as AnyFunctions } from "../types-C83v5SQz.js";
-import { p as DbError } from "../result-CTkCZ6JA.js";
-import { B as ReadSet, P as DbStats, Z as QuerySpec, l as CacheAdapter, t as BetterSupabase } from "../define-e3zI4_4g.js";
-import { n as AmrEntry, s as Impersonator, t as Aal } from "../mfa-TVia554c.js";
-import { r as AuthState } from "../resolve-CjHILk2w.js";
-import { d as ServerContext, f as ServerOptions, l as BetterServer, n as GuardOptions, t as AuthKind } from "../respond-Dne1ARSa.js";
-import { n as toSession, t as AuthSession } from "../view-D1s0wa0T.js";
-import { r as LiveCountSeed, t as CountRunner } from "../live-DJyZMD6w.js";
-import { n as MembershipClaim, r as hasEntitlement, t as EntitlementKey } from "../entitlements-Dng-ctuT.js";
+import { n as AnyModels, t as AnyFunctions } from "../types-DONv9SHN.js";
+import { p as DbError } from "../result-CqEsbgYs.js";
+import { B as ReadSet, P as DbStats, Z as QuerySpec, l as CacheAdapter, t as BetterSupabase } from "../define-CRS2MRV3.js";
+import { n as AmrEntry, s as Impersonator, t as Aal } from "../mfa-C7MNQ1Ob.js";
+import { r as AuthState } from "../resolve-BAqQcwMW.js";
+import { d as ContextOptions, f as ServerContext, n as GuardOptions, p as ServerOptions, t as AuthKind, u as BetterServer } from "../respond-DgIbdrt8.js";
+import { n as toSession, t as AuthSession } from "../view-B64o81wp.js";
+import { r as LiveCountSeed, t as CountRunner } from "../live-BHakSWWo.js";
+import { n as MembershipClaim, r as hasEntitlement, t as EntitlementKey } from "../entitlements-Dm-FHpNH.js";
 import { NextRequest } from "next/server.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/next/collector.d.ts
@@ -17,8 +17,8 @@ interface DbBudget {
   readonly waves?: number;
 }
 //#endregion
-//#region src/next/index.d.ts
-export interface NextOptions extends ServerOptions {
+//#region src/next/create.d.ts
+interface NextOptions extends ServerOptions {
   /** Invalidate `tagFor(table)` cache tags after mutations. Defaults to true. */
   readonly cacheTags?: boolean;
   /** Include internal error messages in Problem Details. Defaults to development only. */
@@ -26,19 +26,19 @@ export interface NextOptions extends ServerOptions {
   /** Per-request database call counts. See the Budget docs. */
   readonly debug?: NextDebugOptions;
 }
-export interface NextDebugOptions {
+interface NextDebugOptions {
   /** Collect outside development too, e.g. for e2e runs against `next start`. */
   readonly enabled?: boolean;
   /** Header with `calls;waves;ms` on route handler responses. Defaults to `x-bs-db-calls`. */
   readonly header?: string;
   /** Warns in development when one render goes over it. */
   readonly budget?: DbBudget;
-  /** Where `next.debugRoute()` is mounted. Defaults to `/api/bs-stats`. */
+  /** Where `bs.debugRoute()` is mounted. Defaults to `/api/bs-stats`. */
   readonly route?: string;
 }
-/** Response header with the URL of the request's totals on `next.debugRoute()`. */
+/** Response header with the URL of the request's totals on `bs.debugRoute()`. */
 export declare const STATS_URL_HEADER = "x-bs-stats";
-export interface ProxyOptions<C = unknown, U = unknown> {
+interface ProxyOptions<C = unknown, P = unknown> {
   /**
    * Another middleware to compose with, such as next-intl's. It runs on the
    * original request, alongside auth; its rewrite, redirect or request
@@ -46,16 +46,16 @@ export interface ProxyOptions<C = unknown, U = unknown> {
    */
   readonly before?: (request: NextRequest) => Response | undefined | Promise<Response | undefined>;
   /** Answer before rendering, e.g. redirect signed-out users. Refreshed cookies are kept. */
-  readonly protect?: (auth: AuthState<C, U>, request: NextRequest) => Response | undefined | Promise<Response | undefined>;
+  readonly protect?: (auth: AuthState<C, P>, request: NextRequest) => Response | undefined | Promise<Response | undefined>;
   /** Post-processes the final response; return a new one to replace it. */
-  readonly after?: (response: Response, auth: AuthState<C, U>) => Response | undefined | void | Promise<Response | undefined | void>;
+  readonly after?: (response: Response, auth: AuthState<C, P>) => Response | undefined | void | Promise<Response | undefined | void>;
   /**
    * Adds `Server-Timing: bs-proxy;dur=..., bs-verify;dur=...` (ms): the whole
    * proxy, and resolving the session (a local verify, or a refresh).
    */
   readonly serverTiming?: boolean;
 }
-export type ActionResult<T> = {
+type ActionResult<T> = {
   readonly ok: true;
   readonly data: T;
   readonly error: null;
@@ -64,7 +64,7 @@ export type ActionResult<T> = {
   readonly data: null;
   readonly error: DbError;
 };
-export interface ActionOptions<S extends StandardSchemaV1 | undefined> extends GuardOptions {
+interface ActionOptions<S extends StandardSchemaV1 | undefined> extends GuardOptions {
   /** Validates the input (plain object or `FormData`) with any Standard Schema. */
   readonly input?: S;
 }
@@ -76,57 +76,66 @@ type Unwrapped<T> = T extends {
 } | {
   readonly ok: false;
 } ? D : T;
-export interface BetterNext<M extends AnyModels, F extends AnyFunctions, E, C = unknown, U = unknown> extends BetterServer<M, F, E, C, U> {
+interface BetterNext<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> extends BetterServer<M, F, E, C, P> {
   /** `proxy.ts`: refreshes sessions for page loads and server actions. */
-  proxy(request: NextRequest, options?: ProxyOptions<C, U>): Promise<Response>;
-  /** Server Components and actions: the caller's context, memoized per request. */
-  server(): Promise<ServerContext<M, F, E, C, U>>;
+  proxy(request: NextRequest, options?: ProxyOptions<C, P>): Promise<Response>;
+  /**
+   * The caller's context. Without a request (Server Components, actions) it
+   * reads the incoming headers and is memoized per request.
+   */
+  context(request?: Request, options?: ContextOptions): Promise<ServerContext<M, F, E, C, P>>;
   /**
    * The verified caller as serializable data (no token, no clients), memoized
    * per request. Wrap it in a `'use cache: private'` function with Cache
    * Components and pass the promise to `<SessionProvider>`.
    */
-  session(): Promise<AuthSession<C, U>>;
+  session(): Promise<AuthSession<C, P>>;
   /**
    * The context for a session and its token, without reading the request.
    * The token is verified again (memoized, no network call); a token for
    * another user than `session` gives an `invalid` context.
    */
-  serverFor(session: AuthSession<C, U>, options: {
+  contextForSession(session: AuthSession<C, P>, options: {
     readonly token: string | null;
-  }): Promise<ServerContext<M, F, E, C, U>>;
+  }): Promise<ServerContext<M, F, E, C, P>>;
   /**
    * First statement of an app-authored `'use cache: private'` function: sets
-   * `cacheLife` from the session's expiry (`sessionStale`), tags the entry
-   * `bs:session:<user id>` and returns the caller's context plus `session`.
+   * `cacheLife` from the session's expiry (`sessionStale`, capped by
+   * `life.stale`), tags the entry `bs:session:<user id>` plus `tags`, and
+   * returns the caller's context plus `session`.
    *
    * ```ts
    * async function getCustomers() {
    *   'use cache: private';
-   *   const { db } = await next.cached();
+   *   const { db } = await bs.cached();
    *   return db.customers.findMany().orThrow();
    * }
    * ```
    */
-  cached(options?: CachedOptions): Promise<CachedContext<M, F, E, C, U>>;
-  /** Drops every `next.cached()` entry of a user, e.g. after a role change. */
-  invalidateSession(userId: string): void;
+  cached(options?: CachedOptions): Promise<CachedContext<M, F, E, C, P>>;
+  /**
+   * Drops every `bs.cached()` entry of a user, e.g. after a role change,
+   * and the entries tagged with `tags` (such as PermDock's `snapshotTag(userId)`).
+   */
+  invalidateSession(userId: string, options?: {
+    readonly tags?: readonly string[];
+  }): void;
   /**
    * Counts on the server and returns a serializable seed for
    * `useLiveCount(seed)`, so the badge renders with a number and the client
    * only refetches on changes. Pass `db` inside `'use cache: private'`
-   * (from `next.cached()`); otherwise it uses `next.server()`. A failed
+   * (from `bs.cached()`); otherwise it uses `bs.context()`. A failed
    * count gives `count: null` instead of throwing.
    */
   liveCount<T extends Extract<keyof M, string>>(spec: QuerySpec<T, "count", number>, db?: CountRunner): Promise<LiveCountSeed<T>>;
   /** Route handler with auth, Result unwrapping and Problem Details errors. */
-  route<P = Record<string, string | string[]>>(handler: (request: NextRequest, ctx: ServerContext<M, F, E, C, U> & {
-    readonly params: P;
+  route<Params = Record<string, string | string[]>>(handler: (request: NextRequest, ctx: ServerContext<M, F, E, C, P> & {
+    readonly params: Params;
   }) => unknown, options?: GuardOptions): (request: NextRequest, segment: {
-    readonly params: Promise<P>;
+    readonly params: Promise<Params>;
   }) => Promise<Response>;
   /** Server action returning a serializable `ActionResult`. */
-  action<S extends StandardSchemaV1 | undefined, T>(options: ActionOptions<S>, fn: (input: ActionParsed<S>, ctx: ServerContext<M, F, E, C, U>) => Promise<T> | T): (input: ActionInput<S>) => Promise<ActionResult<Unwrapped<Awaited<T>>>>;
+  action<S extends StandardSchemaV1 | undefined, T>(options: ActionOptions<S>, fn: (input: ActionParsed<S>, ctx: ServerContext<M, F, E, C, P>) => Promise<T> | T): (input: ActionInput<S>) => Promise<ActionResult<Unwrapped<Awaited<T>>>>;
   /** Tags the current `"use cache"` scope with a table (and row) tag. */
   cacheTag(table: Extract<keyof M, string>, id?: string | number): void;
   /**
@@ -141,7 +150,7 @@ export interface BetterNext<M extends AnyModels, F extends AnyFunctions, E, C =
    */
   debugRoute(): (request: Request) => Promise<Response>;
 }
-export interface SessionStaleOptions {
+interface SessionStaleOptions {
   /** Below this, the result would not be prefetched anyway. Defaults to 30. */
   readonly min?: number;
   /** 300 (5 minutes) joins the route's App Shell. Defaults to 300. */
@@ -152,17 +161,24 @@ export interface SessionStaleOptions {
  * the token's expiry, and at least `min`.
  */
 export declare function sessionStale(session: AuthSession, options?: SessionStaleOptions, now?: number): number;
-export interface CachedOptions {
-  /** `cacheLife` for the entry. `stale` comes from `sessionStale`. */
+interface CachedOptions {
+  /**
+   * `cacheLife` for the entry. `stale` is `sessionStale`, and never more than
+   * `stale` when it is set: pass PermDock's `cacheLifeFor(snapshot)` so the
+   * entry goes stale with the snapshot too.
+   */
   readonly life?: SessionStaleOptions & {
+    readonly stale?: number;
     readonly revalidate?: number;
     readonly expire?: number;
   };
+  /** More `cacheTag`s for the entry, e.g. `snapshotTag(sub)` or `org:<id>`. */
+  readonly tags?: readonly string[];
 }
-export type CachedContext<M extends AnyModels, F extends AnyFunctions, E, C = unknown, U = unknown> = ServerContext<M, F, E, C, U> & {
-  readonly session: AuthSession<C, U>;
+type CachedContext<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> = ServerContext<M, F, E, C, P> & {
+  readonly session: AuthSession<C, P>;
 };
-/** The tag `next.cached()` puts on a user's entries. */
+/** The tag `bs.cached()` puts on a user's entries. */
 export declare function sessionTag(userId: string): string;
 /** `bs:<table>` or `bs:<table>:<id>`. Mutations invalidate both. */
 export declare function tagFor(table: string, id?: string | number): string;
@@ -172,7 +188,7 @@ export declare function tagFor(table: string, id?: string | number): string;
  * `cacheTags: false`.
  */
 export declare function nextCache(): CacheAdapter;
-export interface RequireAalOptions {
+interface RequireAalOptions {
   /**
    * Page that enrolls or challenges a second factor. Signed-in users below
    * the level are redirected there with `?next=<path>`; without it they get
@@ -189,7 +205,7 @@ export interface RequireAalOptions {
  * combine it with your sign-in redirect.
  *
  * ```ts
- * next.proxy(request, {
+ * bs.proxy(request, {
  *   protect: requireAal('aal2', { redirect: '/mfa', match: (path) => path.startsWith('/settings') }),
  * });
  * ```
@@ -202,9 +218,9 @@ export declare function shouldRefresh(request: Request): boolean;
  * actions and cache tags, on top of `createServer`.
  *
  * ```ts
- * export const next = createNext(sb);
+ * export const bs = createNext(betterSupabase);
  * ```
  */
-export declare function createNext<M extends AnyModels, D, F extends AnyFunctions, E, C = unknown, U = unknown>(sb: BetterSupabase<M, D, F, E, C, U>, options?: NextOptions): BetterNext<M, F, E, C, U>;
+export declare function createNext<M extends AnyModels, D, F extends AnyFunctions, E, C = unknown, P = unknown>(betterSupabase: BetterSupabase<M, D, F, E, C, P>, options?: NextOptions): BetterNext<M, F, E, C, P>;
 //#endregion
-export { type Aal, type AmrEntry, type AuthKind, type AuthSession, type DbBudget, type DbStats, type EntitlementKey, type GuardOptions, type Impersonator, type MembershipClaim, hasEntitlement, toSession };
+export { type Aal, type ActionOptions, type ActionResult, type AmrEntry, type AuthKind, type AuthSession, type BetterNext, type CachedContext, type CachedOptions, type DbBudget, type DbStats, type EntitlementKey, type GuardOptions, type Impersonator, type LiveCountSeed, type MembershipClaim, type NextDebugOptions, type NextOptions, type ProxyOptions, type RequireAalOptions, type SessionStaleOptions, hasEntitlement, toSession };