better-supabase 0.4.0 → 0.5.1

package/dist/{server-BA75B0mT.js → server-B1mZ7CgQ.js}

@@ -1,9 +1,10 @@
-import { n as dbError, o as isDbError, r as dbErrorOf } from "./errors-L0xK41y_.js";
-import { i as ok, n as err, o as toDbError, t as AsyncResult } from "./result-Bj6yt33D.js";
-import { a as postgrestExecutor, n as StatsRecorder } from "./stats-C_YxA2r1.js";
-import { a as problemResponse } from "./problem-BihjPR0t.js";
+import { n as dbError, o as isDbError, r as dbErrorOf } from "./errors-DtwXa6b8.js";
+import { i as ok, n as err, o as toDbError, t as AsyncResult } from "./result-BKiliPY7.js";
+import { a as postgrestExecutor, n as StatsRecorder } from "./stats-Bqob3WqT.js";
+import { a as problemResponse } from "./problem-BW1KhzSG.js";
+import { a as delegationOf, i as actorOf, r as userContext, t as actClaim } from "./impersonation-BgSHAYLf.js";
 import { loadEnv } from "./env/index.js";
-import { _ as delegationOf, g as actorOf, i as authContext, o as prefetchJwks, r as checkAal, s as resolveAuth, v as actClaim } from "./mfa-byfjruR9.js";
+import { a as checkAal, c as prefetchJwks, l as rememberVerified, o as authContext, t as isAnonymousUser, u as resolveAuth } from "./view-Bn6HNKUe.js";
 import { parseCookieHeader, serializeCookieHeader } from "@supabase/ssr";
 import { createClient } from "@supabase/supabase-js";
 import { PostgrestClient } from "@supabase/postgrest-js";
@@ -34,14 +35,35 @@ function pinnedUntil(cookies) {
 	const until = Number(value);
 	return value !== void 0 && Number.isFinite(until) ? until : 0;
 }
-/** A `Set-Cookie` value keeping the next requests on the primary for `pinMs`. */
-function primaryCookie(pinMs, now = Date.now()) {
-	return serializeCookieHeader(PRIMARY_COOKIE, String(now + pinMs), {
+/** Options of the `bs-primary-until` cookie, for frameworks that set cookies themselves. */
+function primaryCookieOptions(pinMs) {
+	return {
 		path: "/",
 		maxAge: Math.max(1, Math.ceil(pinMs / 1e3)),
 		httpOnly: true,
 		sameSite: "lax"
-	});
+	};
+}
+/** A `Set-Cookie` value keeping the next requests on the primary for `pinMs`. */
+function primaryCookie(pinMs, now = Date.now()) {
+	return serializeCookieHeader(PRIMARY_COOKIE, String(now + pinMs), primaryCookieOptions(pinMs));
+}
+/**
+* `response` with the `bs-primary-until` cookie when the request wrote, so the
+* caller's next requests read their own writes. A response with immutable
+* headers is copied.
+*/
+function withPrimaryPin(response, replica, pinMs) {
+	if (!replica?.wrote) return response;
+	const cookie = primaryCookie(pinMs);
+	try {
+		response.headers.append("set-cookie", cookie);
+		return response;
+	} catch {
+		const copy = new Response(response.body, response);
+		copy.headers.append("set-cookie", cookie);
+		return copy;
+	}
 }
 /**
 * Reads go to `replica` until the context is pinned; writes, and every read
@@ -101,7 +123,7 @@ function deleteAccount(betterSupabase, service, userId, options = {}) {
 			const param = bucket.owner;
 			if (!param) continue;
 			options.signal?.throwIfAborted();
-			const storage = bucket.connect(client);
+			const storage = bucket.connect(client, { allTenants: true });
 			const listed = await storage.list({ [param]: userId }, options.signal ? { signal: options.signal } : {});
 			if (!listed.ok) return listed;
 			const paths = listed.data.map((object) => object.path).filter((path) => {
@@ -140,19 +162,39 @@ function deleteAccount(betterSupabase, service, userId, options = {}) {
 	});
 }
 //#endregion
+//#region src/core/json.ts
+/** A `JSON.stringify` replacer: `bigint` values become decimal strings, as the wire codec writes them. */
+function jsonReplacer(_key, value) {
+	return typeof value === "bigint" ? value.toString() : value;
+}
+/** `Response.json` that writes `bigint` values as decimal strings instead of throwing. */
+function jsonResponse(data, init = {}) {
+	const headers = new Headers(init.headers);
+	if (!headers.has("content-type")) headers.set("content-type", "application/json");
+	return new Response(JSON.stringify(data, jsonReplacer), {
+		...init,
+		headers
+	});
+}
+//#endregion
 //#region src/server/respond.ts
-/** The scopes a delegated user token lacks; empty for the user's own session. */
+/**
+* The scopes a delegated user token lacks. Empty for the user's own session,
+* which a support or impersonated session counts as: only an `oauth-client`
+* actor is limited to what the user delegated.
+*/
 function missingScopes(auth, required) {
 	if (required.length === 0) return [];
 	const outcome = actorOf(auth.claims);
-	if (!outcome.ok || !outcome.actor) return [];
+	if (!outcome.ok || outcome.actor?.kind !== "oauth-client") return [];
 	const granted = new Set(delegationOf(auth.claims)?.scopes);
 	return required.filter((scope) => !granted.has(scope));
 }
 /** `undefined` when `auth` may pass; otherwise the 401/403 error to send. */
 function guard(auth, allow = ["user"], aal = "aal1", scopes = []) {
 	if (auth.kind === "invalid") return auth.error;
-	if (allow.includes(auth.kind)) {
+	const anonymous = auth.kind === "user" && isAnonymousUser(auth.claims);
+	if (anonymous ? allow.includes("anonymous") : allow.includes(auth.kind)) {
 		const denied = checkAal(auth, aal);
 		if (denied || auth.kind !== "user") return denied;
 		const missing = missingScopes(auth, scopes);
@@ -161,6 +203,7 @@ function guard(auth, allow = ["user"], aal = "aal1", scopes = []) {
 			scopes
 		}) : void 0;
 	}
+	if (anonymous) return dbError("forbidden", "Sign up to continue", { code: "ANONYMOUS_USER" });
 	return auth.kind === "anon" ? dbError("unauthorized", "Sign in to continue", { code: "MISSING_CREDENTIALS" }) : dbError("forbidden", `A ${auth.kind} caller is not allowed here`);
 }
 function isResult(value) {
@@ -202,7 +245,7 @@ async function respond(run, options = {}) {
 	if (!settled.ok) return problemResponse(settled.error, options);
 	if (settled.data instanceof Response) return settled.data;
 	if (settled.data === void 0) return new Response(null, { status: 204 });
-	return Response.json(settled.data, { status: options.status ?? 200 });
+	return jsonResponse(settled.data, { status: options.status ?? 200 });
 }
 /** Prefetching the JWKS would add a network call to every test that builds a server. */
 function defaultPrefetchJwks() {
@@ -212,7 +255,56 @@ function defaultExpose() {
 	return typeof process !== "undefined" && process.env["NODE_ENV"] === "development";
 }
 //#endregion
+//#region src/auth/support-cookie.ts
+/** The cookie that carries the support session id. */
+const SUPPORT_COOKIE = "bs-support";
+/** `Set-Cookie` for a session: HttpOnly, SameSite=Lax, gone when the session expires. */
+function supportCookie(session, options = {}, now = Date.now()) {
+	const maxAge = Math.max(0, Math.ceil((session.expiresAt.epochMilliseconds - now) / 1e3));
+	return cookieLine(options, encodeURIComponent(session.id), maxAge);
+}
+/** `Set-Cookie` that removes the support cookie. */
+function clearSupportCookie(options = {}) {
+	return cookieLine(options, "", 0);
+}
+function cookieLine(options, value, maxAge) {
+	return [
+		`${options.name ?? "bs-support"}=${value}`,
+		`Path=${options.path ?? "/"}`,
+		`Max-Age=${String(maxAge)}`,
+		"HttpOnly",
+		"SameSite=Lax",
+		...options.secure === false ? [] : ["Secure"]
+	].join("; ");
+}
+/** The support session id in a `Cookie` header, or `undefined`. */
+function supportCookieValue(cookieHeader, name = SUPPORT_COOKIE) {
+	if (!cookieHeader) return void 0;
+	for (const part of cookieHeader.split(";")) {
+		const index = part.indexOf("=");
+		if (index === -1 || part.slice(0, index).trim() !== name) continue;
+		const value = decodeURIComponent(part.slice(index + 1).trim());
+		return value === "" ? void 0 : value;
+	}
+}
+//#endregion
+//#region src/server/support-off.ts
+const NOT_CONFIGURED = "Support sessions need createServer(betterSupabase, { support: supportSessions({ store }) })";
+const notConfigured = () => AsyncResult.err(dbError("unexpected", NOT_CONFIGURED));
+/** `bs.support` without `ServerOptions.support`: every call fails. */
+const supportOff = {
+	start: notConfigured,
+	stop: notConfigured,
+	revoke: notConfigured,
+	current: () => Promise.resolve(void 0),
+	list: notConfigured,
+	sessionIdOf: () => void 0,
+	clearCookie: () => clearSupportCookie()
+};
+//#endregion
 //#region src/server/server.ts
+/** The header `current_tenant_id()` reads over the Data API. */
+const TENANT_HEADER = "x-bs-tenant";
 const STATELESS = {
 	persistSession: false,
 	autoRefreshToken: false,
@@ -252,15 +344,24 @@ function createServer(betterSupabase, options = {}) {
 		if (!key) throw new TypeError("admin() needs SUPABASE_SECRET_KEY; it is not set");
 		return key;
 	};
+	const customFetch = options.fetch ? { fetch: options.fetch } : void 0;
+	const sharedGlobal = customFetch ? { global: customFetch } : {};
 	const serviceClient = () => {
-		adminClient ??= createClient(env().url, secretKey(), { auth: STATELESS });
+		adminClient ??= createClient(env().url, secretKey(), {
+			auth: STATELESS,
+			...sharedGlobal
+		});
 		return adminClient;
 	};
 	const readUrl = () => options.readUrl === false ? void 0 : options.readUrl?.replace(/\/+$/, "") ?? env().readUrl;
 	/** Clients for the primary share the service and anon clients; others don't. */
 	const supabaseAt = (url, auth, headers = {}) => {
-		const global = Object.keys(headers).length > 0 ? { global: { headers } } : void 0;
-		const shared = !global && url === env().url;
+		const custom = Object.keys(headers).length > 0;
+		const global = custom ? { global: {
+			headers,
+			...customFetch
+		} } : sharedGlobal;
+		const shared = !custom && url === env().url;
 		switch (auth.kind) {
 			case "user": return createClient(url, env().publishableKey, {
 				accessToken: () => Promise.resolve(auth.token),
@@ -276,7 +377,10 @@ function createServer(betterSupabase, options = {}) {
 					auth: STATELESS,
 					...global
 				});
-				anonClient ??= createClient(url, env().publishableKey, { auth: STATELESS });
+				anonClient ??= createClient(url, env().publishableKey, {
+					auth: STATELESS,
+					...sharedGlobal
+				});
 				return anonClient;
 			default: return auth;
 		}
@@ -290,11 +394,14 @@ function createServer(betterSupabase, options = {}) {
 	const restAt = (url, auth, headers = {}) => {
 		if (auth.kind !== "user") return supabaseAt(url, auth, headers);
 		const key = env().publishableKey;
-		return new PostgrestClient(new URL("rest/v1", url.endsWith("/") ? url : `${url}/`).href, { headers: {
-			...headers,
-			apikey: key,
-			Authorization: `Bearer ${auth.token}`
-		} });
+		return new PostgrestClient(new URL("rest/v1", url.endsWith("/") ? url : `${url}/`).href, {
+			headers: {
+				...headers,
+				apikey: key,
+				Authorization: `Bearer ${auth.token}`
+			},
+			...customFetch
+		});
 	};
 	/** `$client` stays the full Supabase client, built when first read. */
 	const withLazyClient = (db, client) => Object.defineProperty(db, "$client", {
@@ -311,14 +418,101 @@ function createServer(betterSupabase, options = {}) {
 		});
 		return withLazyClient(db, () => supabase ??= supabaseFor(auth));
 	};
-	const sqlFor = (claims, context, stats) => {
+	const sqlFor = (claims, context, stats, session) => {
 		if (!options.postgres) throw new TypeError("Direct Postgres access needs createServer(betterSupabase, { postgres: createPostgres() })");
-		return betterSupabase.connect(options.postgres.executorFor(claims), context, stats ? { stats } : {});
+		return betterSupabase.connect(session ? options.postgres.executorFor(claims, session) : options.postgres.executorFor(claims), context, stats ? { stats } : {});
+	};
+	/** `ServerOptions.tenant` outside `context()`, where it can't be awaited. */
+	const syncTenant = (request, auth) => {
+		const tenant = options.tenant?.(request, auth);
+		if (tenant !== void 0 && typeof tenant !== "string") throw new TypeError("ServerOptions.tenant returned a promise: use context(request), or pass { tenant } to contextFromResolution");
+		return tenant;
+	};
+	const pinMs = options.replicas?.pinMs ?? 5e3;
+	if (options.support && !options.postgres) throw new TypeError("Support sessions need createServer(betterSupabase, { postgres: createPostgres(), support })");
+	const support = options.support ? options.support.create(betterSupabase.events, options.auth?.claims ?? betterSupabase.claimsSchema) : supportOff;
+	/**
+	* The target's context in a support session. Queries run over direct
+	* Postgres with the target's claims plus `act`, read-only unless the
+	* session allows writes; nothing reaches Supabase with the admin's token.
+	*/
+	const supportContextFor = (resolution, active, parent, tenant) => {
+		const { session, claims } = active;
+		const record = (key) => {
+			const value = claims[key];
+			return typeof value === "object" && value !== null && !Array.isArray(value) ? Object.fromEntries(Object.entries(value)) : void 0;
+		};
+		const appMetadata = record("app_metadata");
+		const userMetadata = record("user_metadata");
+		const user = {
+			id: session.targetUserId,
+			role: typeof claims["role"] === "string" ? claims["role"] : "authenticated",
+			...typeof claims["email"] === "string" ? { email: claims["email"] } : {},
+			...appMetadata ? { appMetadata } : {},
+			...userMetadata ? { userMetadata } : {}
+		};
+		const auth = {
+			kind: "user",
+			token: "",
+			claims,
+			user,
+			source: "support",
+			expiresAt: Math.floor(session.expiresAt.epochMilliseconds / 1e3)
+		};
+		const scope = tenant ?? session.tenant;
+		const base = userContext(user, claims);
+		const context = scope === void 0 ? base : {
+			...base,
+			tenant: scope
+		};
+		const sessionOptions = {
+			...session.readOnly ? { readOnly: true } : {},
+			...scope === void 0 ? {} : { settings: { "better_supabase.tenant": scope } }
+		};
+		const recorder = new StatsRecorder(parent);
+		const sqlClaims = claims;
+		const unavailable = () => {
+			throw new TypeError("ctx.supabase and ctx.db.$client are not available in a support session; ctx.db and ctx.sql run as the target");
+		};
+		let db;
+		let sql;
+		return {
+			auth,
+			resolution,
+			support: active,
+			get supabase() {
+				return unavailable();
+			},
+			get db() {
+				db ??= Object.defineProperty(sqlFor(sqlClaims, context, recorder, sessionOptions), "$client", {
+					get: unavailable,
+					enumerable: true,
+					configurable: true
+				});
+				return db;
+			},
+			get sql() {
+				sql ??= sqlFor(sqlClaims, context, recorder, sessionOptions);
+				return sql;
+			},
+			replica: void 0,
+			stats: () => recorder.snapshot(),
+			apply: (response) => resolution.apply(response)
+		};
 	};
 	/** Clients and repositories are built on first access: most scopes use one of them. */
-	const contextFor = (resolution, headers, parent, until = 0) => {
+	const contextFor = (resolution, requestHeaders, parent, until = 0, tenant, active) => {
+		if (active) return supportContextFor(resolution, active, parent, tenant);
 		const { auth } = resolution;
-		const context = authContext(auth);
+		const context = tenant === void 0 ? authContext(auth) : {
+			...authContext(auth),
+			tenant
+		};
+		const headers = tenant === void 0 ? requestHeaders : {
+			...requestHeaders,
+			[TENANT_HEADER]: tenant
+		};
+		const session = tenant === void 0 ? void 0 : { settings: { "better_supabase.tenant": tenant } };
 		const recorder = new StatsRecorder(parent);
 		let supabase;
 		let db;
@@ -354,13 +548,14 @@ function createServer(betterSupabase, options = {}) {
 			},
 			get sql() {
 				if (!options.postgres || !sqlClaims) return;
-				sql ??= sqlFor(sqlClaims, context, recorder);
+				sql ??= sqlFor(sqlClaims, context, recorder, session);
 				return sql;
 			},
-			stats: () => recorder.snapshot()
+			stats: () => recorder.snapshot(),
+			apply: (response) => withPrimaryPin(resolution.apply(response), replica, pinMs)
 		};
 	};
-	const fromResolution = (resolution, request, contextOptions) => contextFor(resolution, options.headers?.(request) ?? {}, contextOptions.stats, contextOptions.pinnedUntil ?? (readUrl() ? pinnedUntil(resolution.requestCookies) : 0));
+	const fromResolution = (resolution, request, contextOptions, tenant) => contextFor(resolution, options.headers?.(request) ?? {}, contextOptions.stats, contextOptions.pinnedUntil ?? (readUrl() ? pinnedUntil(resolution.requestCookies) : 0), tenant, contextOptions.support);
 	const resolve = async (request, resolveOptions = {}) => {
 		const claims = options.auth?.claims ?? betterSupabase.claimsSchema;
 		const userMetadata = betterSupabase.userMetadataSchema;
@@ -371,6 +566,7 @@ function createServer(betterSupabase, options = {}) {
 			...userMetadata ? { userMetadata } : {},
 			env: env(),
 			...resolveOptions.refresh === void 0 ? {} : { refresh: resolveOptions.refresh },
+			...resolveOptions.cookies === void 0 ? {} : { cookies: resolveOptions.cookies },
 			onRefresh: (event) => {
 				options.auth?.onRefresh?.(event);
 				betterSupabase.events.emit("refresh", event);
@@ -381,12 +577,16 @@ function createServer(betterSupabase, options = {}) {
 			betterSupabase.events.emit("auth", {
 				source: auth.kind === "user" ? auth.source === "cookie" ? "cookie" : "bearer" : auth.kind === "service" ? "bearer" : "none",
 				ok: auth.kind !== "invalid",
-				...auth.kind === "user" ? { userId: auth.user.id } : {}
+				...auth.kind === "user" ? {
+					userId: auth.user.id,
+					rawSource: auth.source
+				} : {},
+				...auth.kind === "anon" || auth.kind === "invalid" ? { reason: auth.reason } : {}
 			});
 		}
 		return resolution;
 	};
-	return {
+	const server = {
 		get env() {
 			return env();
 		},
@@ -399,12 +599,19 @@ function createServer(betterSupabase, options = {}) {
 			headers: {},
 			requestCookies: [],
 			apply: (response) => response
-		}, {}, contextOptions.stats, contextOptions.pinnedUntil),
+		}, {}, contextOptions.stats, contextOptions.pinnedUntil, contextOptions.tenant, contextOptions.support),
 		async context(request, contextOptions = {}) {
-			const resolution = await resolve(request, { refresh: contextOptions.refresh ?? false });
-			return fromResolution(resolution, request, contextOptions);
+			const resolution = await resolve(request, {
+				refresh: contextOptions.refresh ?? false,
+				...contextOptions.cookies === void 0 ? {} : { cookies: contextOptions.cookies }
+			});
+			const [tenant, active] = await Promise.all([contextOptions.tenant ?? options.tenant?.(request, resolution.auth), contextOptions.support ?? support.current(request, resolution.auth)]);
+			return fromResolution(resolution, request, active ? {
+				...contextOptions,
+				support: active
+			} : contextOptions, tenant);
 		},
-		contextFromResolution: (resolution, request, contextOptions = {}) => fromResolution(resolution, request, contextOptions),
+		contextFromResolution: (resolution, request, contextOptions = {}) => fromResolution(resolution, request, contextOptions, contextOptions.tenant ?? syncTenant(request, resolution.auth)),
 		admin: (context = {}) => betterSupabase.connect(serviceClient(), {
 			actor: {
 				id: "service",
@@ -414,6 +621,7 @@ function createServer(betterSupabase, options = {}) {
 			claims: { role: "service_role" },
 			...context
 		}),
+		support,
 		deleteAccount: (userId, deleteOptions) => deleteAccount(betterSupabase, serviceClient, userId, deleteOptions),
 		actingAs: (userId, claims = {}, impersonation) => {
 			const full = {
@@ -433,6 +641,20 @@ function createServer(betterSupabase, options = {}) {
 			});
 		}
 	};
+	verifiedSeeders.set(server, (verified) => rememberVerified({
+		...options.auth,
+		env: env()
+	}, verified));
+	return server;
+}
+const verifiedSeeders = /* @__PURE__ */ new WeakMap();
+/**
+* Hands `server` a bearer token another layer verified for this request
+* (`@supabase/server`'s `withSupabase`), so `context()` doesn't verify it
+* again. See `rememberVerified` for when it is accepted.
+*/
+function rememberVerifiedFor(server, verified) {
+	return verifiedSeeders.get(server)?.(verified) ?? false;
 }
 //#endregion
-export { guard as a, settle as c, primaryCookie as d, defaultExpose as i, DEFAULT_PIN_MS as l, extendServer as n, isResult as o, withExtra as r, respond as s, createServer as t, PRIMARY_COOKIE as u };
+export { DEFAULT_PIN_MS as _, withExtra as a, withPrimaryPin as b, supportCookie as c, guard as d, isResult as f, jsonResponse as g, jsonReplacer as h, rememberVerifiedFor as i, supportCookieValue as l, settle as m, createServer as n, SUPPORT_COOKIE as o, respond as p, extendServer as r, clearSupportCookie as s, TENANT_HEADER as t, defaultExpose as u, PRIMARY_COOKIE as v, primaryCookieOptions as y };

package/dist/{shared-DnoCdMDr.js → shared-D1dRUrAg.js}

@@ -1,4 +1,4 @@
-import { n as dbError, t as DbException } from "./errors-L0xK41y_.js";
+import { n as dbError, t as DbException } from "./errors-DtwXa6b8.js";
 import { t as lookupOf } from "./lookup-BaP5bI27.js";
 //#region src/plugins/shared.ts
 /** Database column name for an app column, or `undefined` if it is unknown. */
@@ -35,6 +35,20 @@ function withDefault(row, column, value) {
 		[column]: value
 	};
 }
+/**
+* Refuses caller-supplied values for columns a plugin fills (timestamps,
+* actor, soft delete) unless the call passes `{ override: true }`. Returns
+* whether the caller may keep its own values.
+*/
+function guardManaged(op, columns, plugin, options) {
+	if (options["override"] === true) return true;
+	const rows = op.kind === "insert" ? op.rows : op.kind === "update" ? [op.set] : [];
+	for (const column of columns) {
+		if (column === void 0) continue;
+		if (rows.some((row) => column in row)) throw new DbException(dbError("invalid_request", `"${column}" on ${op.table.key} is filled by ${plugin}(); pass { override: true } to set it yourself`, { table: op.table.key }));
+	}
+	return false;
+}
 /** Upserts that may update existing rows must not overwrite "created" columns. */
 function insertsOnly(op) {
 	return !op.onConflict || op.onConflict.action === "ignore";
@@ -55,4 +69,4 @@ function toDb(table, row) {
 	return out;
 }
 //#endregion
-export { isNotNull as a, toDb as c, insertsOnly as i, withDefault as l, equals as n, isNull as o, forbidden as r, toApp as s, dbName as t };
+export { insertsOnly as a, toApp as c, guardManaged as i, toDb as l, equals as n, isNotNull as o, forbidden as r, isNull as s, dbName as t, withDefault as u };

package/dist/signers-Cc6r98SW.d.ts

@@ -0,0 +1,162 @@
+/// <reference lib="esnext.temporal" />
+import { t as KitTransport } from "./kit-transport-B82k1djG.js";
+//#region src/webhooks/url-policy.d.ts
+/** Decides whether a webhook may be sent to `url`. Rejecting counts as `false`. */
+type AllowUrl = (url: URL) => boolean | Promise<boolean>;
+/** The addresses a host name resolves to. */
+type ResolveHost = (hostname: string) => Promise<readonly string[]>;
+interface PublicUrlOptions {
+  /**
+   * Resolves host names so each address can be checked. Defaults to
+   * `node:dns` where the runtime has it (Node, Bun, Deno); pass one on other
+   * runtimes, or `false` to check only the URL.
+   */
+  readonly resolve?: ResolveHost | false;
+  /** Allow `http:` URLs, e.g. for local development. */
+  readonly allowHttp?: boolean;
+  /** Host names that skip every check, e.g. an internal receiver you trust. */
+  readonly allowHosts?: readonly string[];
+}
+/**
+ * Whether an IP address is reachable on the public internet: not loopback,
+ * private, link-local (cloud metadata), carrier-grade NAT, multicast or
+ * reserved. Returns `false` for anything that isn't an IP address.
+ */
+declare function isPublicAddress(address: string): boolean;
+/**
+ * The default `allowUrl`: HTTPS only, no credentials in the URL, no local
+ * host names, and every address the host resolves to must be public. The
+ * delivery transport calls it again for each redirect.
+ *
+ * DNS can change between this check and the connection. Route webhooks
+ * through an egress proxy when that matters.
+ */
+declare function publicUrl(options?: PublicUrlOptions): AllowUrl;
+//#endregion
+//#region src/webhooks/http.d.ts
+interface WebhookRequest {
+  readonly url: string;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: string;
+  readonly signal?: AbortSignal;
+}
+interface WebhookResponse {
+  readonly status: number;
+  readonly body: string;
+  /** Seconds from the `Retry-After` header, when the receiver sent one. */
+  readonly retryAfter?: number;
+}
+/**
+ * Sends one signed webhook request. Throw `WebhookPolicyError` when the
+ * request must never be retried (a blocked URL); any other error retries.
+ */
+interface WebhookTransport {
+  readonly apiVersion: 1;
+  readonly name: string;
+  send(request: WebhookRequest): Promise<WebhookResponse>;
+}
+/** A delivery that must not be retried, e.g. a URL `allowUrl` rejected. */
+declare class WebhookPolicyError extends Error {
+  override readonly name = "WebhookPolicyError";
+}
+interface FetchTransportOptions {
+  readonly fetch?: typeof fetch;
+  /** Checked before the first request and before each redirect. */
+  readonly allowUrl?: AllowUrl;
+  /**
+   * Defaults to 0: a redirect fails the delivery without a retry. Each hop
+   * you allow is checked with `allowUrl` first.
+   */
+  readonly maxRedirects?: number;
+  /** Per request. Defaults to 10 seconds. */
+  readonly timeoutMs?: number;
+  /** The response body bytes kept; the rest is not read. Defaults to 64 KiB. */
+  readonly maxResponseBytes?: number;
+}
+/** Sends webhooks with `fetch`, following redirects only to allowed URLs. */
+declare function fetchTransport(options?: FetchTransportOptions): WebhookTransport;
+//#endregion
+//#region src/webhooks/secrets.d.ts
+interface RotateSecretOptions {
+  /** How long older secrets keep signing, e.g. `'24 hours'` (the default). */
+  readonly overlap?: string;
+  /** Use this secret instead of a generated one, e.g. when migrating. */
+  readonly secret?: string;
+}
+/**
+ * Where endpoint signing secrets live. `sqlSecretStore` (Vault or a
+ * column, set in `kits.webhooks-out.options.secretStorage`) is the default;
+ * implement it for a KMS or a secrets manager.
+ */
+interface WebhookSecretStore {
+  readonly apiVersion: 1;
+  /** The live secrets of an endpoint, newest first. */
+  secrets(endpointId: string): Promise<readonly string[]>;
+  /** Creates a new secret and returns it once. */
+  rotate?(endpointId: string, options?: RotateSecretOptions): Promise<string>;
+}
+/** The kit's `webhook_secrets` and `rotate_webhook_secret` functions. */
+declare function sqlSecretStore(transport: KitTransport, options?: {
+  readonly schema?: string;
+}): WebhookSecretStore;
+//#endregion
+//#region src/webhooks/signers.d.ts
+interface WebhookSignInput {
+  /** The delivery id, the same on every retry so receivers can deduplicate. */
+  readonly id: string;
+  readonly body: string;
+  readonly timestamp: Temporal.Instant;
+  /** The endpoint's live secrets, newest first. Sign with each while rotating. */
+  readonly secrets: readonly string[];
+}
+/**
+ * Adds the signature headers to an outgoing webhook. `standardWebhooks()`
+ * is the default; `hmacSigner()` covers custom header and payload formats.
+ */
+interface WebhookSigner {
+  readonly apiVersion: 1;
+  readonly name: string;
+  sign(input: WebhookSignInput): Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;
+}
+interface StandardWebhooksOptions {
+  /** Header names, for receivers that expect a prefix such as `svix-`. */
+  readonly headers?: {
+    readonly id?: string;
+    readonly timestamp?: string;
+    readonly signature?: string;
+  };
+}
+/**
+ * Signs with the [Standard Webhooks](https://www.standardwebhooks.com/)
+ * scheme: `webhook-id`, `webhook-timestamp` and one `v1,` signature per
+ * secret in `webhook-signature`. `verifyWebhook` checks it.
+ */
+declare function standardWebhooks(options?: StandardWebhooksOptions): WebhookSigner;
+interface HmacSignerOptions {
+  readonly name?: string;
+  /** e.g. `x-acme-signature`. */
+  readonly signatureHeader: string;
+  /** Sends the epoch-seconds timestamp in this header. */
+  readonly timestampHeader?: string;
+  /** Sends the delivery id in this header. */
+  readonly idHeader?: string;
+  /** The signed text. Defaults to `${timestamp}.${body}`. */
+  readonly content?: (input: {
+    readonly id: string;
+    readonly timestamp: string;
+    readonly body: string;
+  }) => string;
+  /** Defaults to `hex`. */
+  readonly encoding?: "hex" | "base64";
+  /** Written before each signature. Defaults to `v1=`. */
+  readonly prefix?: string;
+  /** Joins the signatures of several secrets. Defaults to `,`. */
+  readonly separator?: string;
+}
+/**
+ * HMAC-SHA256 with the secret's UTF-8 bytes as the key, for receivers that
+ * verify an existing format, e.g. `v1=<hex>` over `timestamp.body`.
+ */
+declare function hmacSigner(options: HmacSignerOptions): WebhookSigner;
+//#endregion
+export { PublicUrlOptions as _, hmacSigner as a, publicUrl as b, WebhookSecretStore as c, WebhookPolicyError as d, WebhookRequest as f, AllowUrl as g, fetchTransport as h, WebhookSigner as i, sqlSecretStore as l, WebhookTransport as m, StandardWebhooksOptions as n, standardWebhooks as o, WebhookResponse as p, WebhookSignInput as r, RotateSecretOptions as s, HmacSignerOptions as t, FetchTransportOptions as u, ResolveHost as v, isPublicAddress as y };