better-supabase 0.4.0 → 0.5.0

package/dist/cli/{doctor-BOym3mbL.js → doctor-L7Z8mYTx.js}

@@ -2,17 +2,18 @@ import { a as list, r as defineCliCommand } from "./command-CK14fP91.js";
 import { n as CliError } from "./errors-4v4DTtda.js";
 import { r as writeIfChanged } from "./io-k41_z-jT.js";
 import { i as plain, r as painter } from "./style-C0NFdJRL.js";
-import { t as VERSION } from "./version-5mW_8sY1.js";
-import { c as diffEngine, d as readSupabaseToml, f as schemaPaths, l as migrationCommand, p as tomlGet, s as stdinDatabaseUrl, u as pgFunctionHooks } from "./config-D9R0o1LH.js";
-import { a as parseHookMarker, c as readPermdock, i as parseGrantsMarker, s as permdockSource, t as compiledReadSets } from "./read-sets-CMa29t9a.js";
+import { t as VERSION } from "./version-BDJuO0UR.js";
+import { c as diffEngine, d as pgFunctionHooks, f as readSupabaseToml, l as httpHooks, m as tomlGet, p as schemaPaths, s as stdinDatabaseUrl, u as migrationCommand } from "./config-CPVpXP5I.js";
+import { a as parseHookMarker, i as parseGrantsMarker, o as permdockSource, s as readPermdock, t as compiledReadSets } from "./read-sets-BfMQcKy8.js";
 import { t as byCodePoint } from "./compare-BmIWVEui.js";
-import { C as catalogOf, D as qualified, E as policyObject, O as tableObject, S as entitlementsKit, T as lineOf, c as openSource, d as snapshotFile, h as CACHE_DIR, o as loadSnapshot, r as renderFiles, s as managementTarget, w as exposed, x as PERMDOCK_RULES } from "./gen-Ccn_p90L.js";
+import { C as catalogOf, D as policyObject, E as lineOf, O as qualified, S as entitlementsKit, T as exposedSchemas, c as openSource, d as snapshotFile, h as CACHE_DIR, k as tableObject, o as loadSnapshot, r as renderFiles, s as managementTarget, w as exposed, x as PERMDOCK_RULES } from "./gen-C2osRcr5.js";
 import { n as withSpinner } from "./prompts-BNcNfAve.js";
 import { t as connect } from "./db-DOBPt660.js";
 import { dirname, resolve } from "node:path";
 import { existsSync } from "node:fs";
 import { glob, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
-import { kitLayout, renderKit, sameKitFile } from "better-supabase/sql";
+import { SQL_MODULES, contractSignature, customContracts, kitDeprecations, kitFileVersion, kitLayout, migrationOptionUses, moduleVersion, renderKit, sameKitFile } from "better-supabase/sql";
+import { DEFAULT_ACTIVE_TENANT, tenantClaimPaths } from "better-supabase/config";
 import { createHash } from "node:crypto";
 import { defineBucket, parseSize } from "better-supabase/storage";
 //#region src/cli/doctor/advisors.ts
@@ -93,7 +94,7 @@ const SLOW_CALLS = 1e3;
 /** Rows `--explain` reads, like a `findMany()` under Supabase's default `max_rows`. */
 const EXPLAIN_LIMIT = 1e3;
 const escape$2 = (name) => name.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
-const ident = (name) => `"${name.replaceAll("\"", "\"\"")}"`;
+const ident$1 = (name) => `"${name.replaceAll("\"", "\"\"")}"`;
 const literal = (text) => `'${text.replaceAll("'", "''")}'`;
 const errorText = (cause) => cause instanceof Error ? cause.message : String(cause);
 const oneLine = (query, max = 160) => {
@@ -105,7 +106,7 @@ const megabytes = (bytes) => `${(bytes / 1024 / 1024).toFixed(1)} MB`;
 /** The schema `pg_stat_statements` lives in, when the extension is installed. */
 async function statementsView(db) {
 	const [row] = await db.query(`select n.nspname as schema from pg_extension e join pg_namespace n on n.oid = e.extnamespace where e.extname = 'pg_stat_statements'`);
-	return row ? `${ident(row.schema)}.pg_stat_statements` : void 0;
+	return row ? `${ident$1(row.schema)}.pg_stat_statements` : void 0;
 }
 /** The first exposed table a statement names, to locate it in the SQL files. */
 function tableIn(query, tables) {
@@ -169,8 +170,8 @@ async function explainTable(db, table, claims) {
 		}
 		await db.query(`select set_config('request.jwt.claims', ${literal(JSON.stringify(claims))}, true)`);
 		const before = tracked ? await functionTimes(db) : /* @__PURE__ */ new Map();
-		await db.query(`set local role ${ident(role)}`);
-		const [row] = await db.query(`explain (analyze, buffers, format json) select * from ${ident(table.schema)}.${ident(table.name)} limit ${EXPLAIN_LIMIT}`);
+		await db.query(`set local role ${ident$1(role)}`);
+		const [row] = await db.query(`explain (analyze, buffers, format json) select * from ${ident$1(table.schema)}.${ident$1(table.name)} limit ${EXPLAIN_LIMIT}`);
 		const raw = row?.["QUERY PLAN"];
 		const plan = typeof raw === "string" ? JSON.parse(raw) : raw;
 		if (!plan?.[0]) throw new Error("EXPLAIN returned no plan");
@@ -337,24 +338,29 @@ const KIT_MEMBERSHIPS = /better_supabase\s*\.\s*membership_claims\b/i;
 const PERMDOCK_CALL = /\bpermdock\w*\s*\(|permdock\s*\./i;
 /** Only PermDock's generated hook sets this claim, so it marks that hook's body. */
 const PERMDOCK_HOOK = /'\{\s*(?:claims\s*,\s*)?memberships_truncated\s*\}'/i;
-const escapeRegExp = (text) => text.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
-/** The claims PermDock's hook writes that a second writer would contradict. */
-function ownedClaims(tenant) {
-	return [
+const escapeRegExp$1 = (text) => text.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+* The claims PermDock's hook writes that a second writer would contradict.
+* The tenant claim is the manifest's when there is one, since that is the
+* claim PermDock's hook really writes.
+*/
+function ownedClaims(context) {
+	const manifest = context.permdock?.manifest;
+	const tenant = manifest?.rls?.tenantClaim ?? manifest?.tenantClaim ?? context.config.claims.tenant;
+	return [.../* @__PURE__ */ new Set([
 		"roles",
 		"user_role",
 		"memberships",
-		tenant
-	];
+		tenant,
+		context.config.claims.tenant
+	])];
 }
-const quotedName = (schema, name) => `(?:"?${escapeRegExp(schema)}"?\\s*\\.\\s*)?"?${escapeRegExp(name)}"?`;
-/** A SQL file that starts with PermDock's hook marker and creates `fn`. */
+const quotedName = (schema, name) => `(?:"?${escapeRegExp$1(schema)}"?\\s*\\.\\s*)?"?${escapeRegExp$1(name)}"?`;
+const createsFunction = (fn) => new RegExp(`create\\s+(?:or\\s+replace\\s+)?function\\s+${quotedName(fn.schema, fn.name)}\\s*\\(`, "i");
+/** The SQL file that starts with PermDock's hook marker and creates `fn`. */
 function markerFileFor(context, fn) {
-	const creates = new RegExp(`create\\s+(?:or\\s+replace\\s+)?function\\s+${quotedName(fn.schema, fn.name)}\\s*\\(`, "i");
-	for (const file of context.sqlFiles ?? []) {
-		const marker = parseHookMarker(file.text);
-		if (marker && creates.test(file.text)) return marker;
-	}
+	const creates = createsFunction(fn);
+	return (context.sqlFiles ?? []).find((file) => parseHookMarker(file.text) && creates.test(file.text));
 }
 /** Whether `fn` is the hook PermDock generated: by its manifest, its marker file or its body. */
 function isPermdockHook(context, fn) {
@@ -373,7 +379,7 @@ function registeredClaims(context) {
 	for (const claim of context.permdock?.manifest?.claims ?? []) if (claim.source !== "permdock") claims.set(claim.name, claim.source);
 	if (claims.size > 0) return claims;
 	const owned = /* @__PURE__ */ new Set([
-		...ownedClaims(context.config.claims.tenant),
+		...ownedClaims(context),
 		"memberships_truncated",
 		"attrs",
 		"authz_ver"
@@ -389,7 +395,7 @@ function wrapsPermdockHook(context, source) {
 /** Which of `claims` the hook body writes through `jsonb_set` or `jsonb_build_object`. */
 function writtenClaims(source, claims) {
 	return claims.filter((claim) => {
-		const name = escapeRegExp(claim);
+		const name = escapeRegExp$1(claim);
 		return new RegExp(`jsonb_set\\s*\\([^;]*?'\\{\\s*(?:claims\\s*,\\s*)?${name}\\s*\\}'`, "i").test(source) || new RegExp(`jsonb_build_object\\s*\\([^;]*?'${name}'\\s*,`, "i").test(source);
 	});
 }
@@ -435,18 +441,28 @@ function grantProblems(fn) {
 		fix
 	};
 }
-/** The `-- permdock:grants v1` migration that grants `fn`, if any. */
-function grantsMigrationFor(context, fn) {
-	const grants = new RegExp(`grant\\s+execute\\s+on\\s+function\\s+${quotedName(fn.schema, fn.name)}\\s*\\(`, "i");
-	return (context.sqlFiles ?? []).find((file) => parseGrantsMarker(file.text) && grants.test(file.text))?.path;
+const MIGRATIONS = /(?:^|\/)supabase\/migrations\//;
+/**
+* The file that grants `fn` to `supabase_auth_admin`: a `-- permdock:grants
+* v1` migration, or under pg-delta, which carries grants, the declarative
+* schema file that defines `fn`. `supabase db diff` drops grants, so the
+* legacy engine only counts the migration.
+*/
+function grantsSourceFor(context, fn, engine) {
+	const grants = new RegExp(`grant\\s+execute\\s+on\\s+function\\s+${quotedName(fn.schema, fn.name)}\\s*\\([^)]*\\)\\s*to\\s+[^;]*\\bsupabase_auth_admin\\b`, "i");
+	const creates = createsFunction(fn);
+	return (context.sqlFiles ?? []).find((file) => grants.test(file.text) && (parseGrantsMarker(file.text) !== void 0 || engine === "pg-delta" && !MIGRATIONS.test(file.path) && creates.test(file.text)))?.path;
 }
 const PERMDOCK_GRANTS_COMMAND = "permdock supabase hook generate --grants-out supabase/migrations/<timestamp>_permdock_hook_grants.sql";
+const permdockSchemaCommand = (file) => `permdock supabase hook generate --out ${file ?? "<the schema file that defines it>"}`;
 /** Configured hook functions whose grants are wrong (BS404, `doctor --fix-grants`). */
 function hookGrantProblems(context) {
+	const engine = diffEngine(context.configToml);
 	return configuredHooks(context).flatMap(({ config, extras }) => (extras?.functions ?? []).flatMap((fn) => {
 		const { problems, fix } = grantProblems(fn);
 		if (problems.length === 0) return [];
-		const file = grantsMigrationFor(context, fn);
+		const file = grantsSourceFor(context, fn, engine);
+		const hookFile = markerFileFor(context, fn)?.path;
 		return [{
 			hook: config.hook,
 			fn,
@@ -454,7 +470,10 @@ function hookGrantProblems(context) {
 			fix: file ? {
 				kind: "migration",
 				file
-			} : isPermdockHook(context, fn) ? { kind: "permdock" } : {
+			} : isPermdockHook(context, fn) ? {
+				kind: "permdock",
+				...hookFile ? { file: hookFile } : {}
+			} : {
 				kind: "sql",
 				sql: fix
 			}
@@ -465,8 +484,8 @@ function hookGrantProblems(context) {
 function grantFixText(fix, engine) {
 	switch (fix.kind) {
 		case "sql": return engine === "pg-delta" ? `Add to the schema file that defines the function, then run \`supabase db schema declarative sync\` (\`doctor --fix-grants\` prints every block):\n${fix.sql.join("\n")}` : `Append to the migration \`supabase db diff\` wrote (\`doctor --fix-grants\` prints every block):\n${fix.sql.join("\n")}`;
-		case "permdock": return `It is PermDock's hook, so let PermDock write the grants: \`${PERMDOCK_GRANTS_COMMAND}\`.`;
-		case "migration": return `${fix.file} grants it, so the database is behind the migrations: apply them (\`supabase migration up\`).`;
+		case "permdock": return engine === "pg-delta" ? `It is PermDock's hook, so let PermDock write the grants into the schema file that defines it: \`${permdockSchemaCommand(fix.file)}\`, without \`--grants-out\` so pg-delta carries them, then run \`supabase db schema declarative sync\`.` : `It is PermDock's hook, so let PermDock write the grants: \`${PERMDOCK_GRANTS_COMMAND}\`.`;
+		case "migration": return engine === "pg-delta" ? `${fix.file} grants it, so the database is behind: run \`supabase db schema declarative sync\`, then apply the migrations (\`supabase migration up\`).` : `${fix.file} grants it, so the database is behind the migrations: apply them (\`supabase migration up\`).`;
 		default: return fix;
 	}
 }
@@ -481,10 +500,10 @@ function hookGrantBlock(problems, engine = "migra") {
 				lines.push("", `-- ${name}`, ...fix.sql);
 				break;
 			case "permdock":
-				lines.push("", `-- ${name} is PermDock's hook: ${PERMDOCK_GRANTS_COMMAND}`);
+				lines.push("", engine === "pg-delta" ? `-- ${name} is PermDock's hook: ${permdockSchemaCommand(fix.file)} (without --grants-out), then supabase db schema declarative sync` : `-- ${name} is PermDock's hook: ${PERMDOCK_GRANTS_COMMAND}`);
 				break;
 			case "migration":
-				lines.push("", `-- ${name}: ${fix.file} grants it; run \`supabase migration up\`.`);
+				lines.push("", engine === "pg-delta" ? `-- ${name}: ${fix.file} grants it; run \`supabase db schema declarative sync\`, then \`supabase migration up\`.` : `-- ${name}: ${fix.file} grants it; run \`supabase migration up\`.`);
 				break;
 			default: return fix;
 		}
@@ -495,8 +514,14 @@ const emptySearchPath = (fn) => {
 	const value = fn.settings["search_path"];
 	return value === "" || value === "\"\"" || value === "''";
 };
-async function hookClaimsSize(db, fn, userId) {
-	const call = `${ident(fn.schema)}.${ident(fn.name)}`;
+/** Auth's issuer shape (`{url}/auth/v1`); doctor has no project URL to put in it. */
+const DOCTOR_ISSUER = "https://doctor.invalid/auth/v1";
+/**
+* Runs the hook as Auth does for `userId` (as `supabase_auth_admin` when the
+* connecting role may switch to it), in a transaction that is rolled back.
+* Undefined when `auth.users` has no such user.
+*/
+async function withHookEvent(db, userId, run) {
 	await db.query("begin");
 	try {
 		await db.query(`set local statement_timeout = '10s'`);
@@ -510,6 +535,10 @@ async function hookClaimsSize(db, fn, userId) {
           'user_metadata', coalesce(u.raw_user_meta_data, '{}'::jsonb),
           'aal', 'aal1', 'session_id', gen_random_uuid(),
           'is_anonymous', coalesce(u.is_anonymous, false),
+          'amr', jsonb_build_array(jsonb_build_object(
+            'method', 'password', 'timestamp', extract(epoch from now())::int8
+          )),
+          'iss', ${literal(DOCTOR_ISSUER)},
           'iat', extract(epoch from now())::int8,
           'exp', extract(epoch from now())::int8 + 3600
         )
@@ -519,11 +548,28 @@ async function hookClaimsSize(db, fn, userId) {
 		const [role] = await db.query(`select case when exists(select 1 from pg_roles where rolname = 'supabase_auth_admin')
         then pg_has_role('supabase_auth_admin', 'member') else false end as member`);
 		if (role?.member) await db.query("set local role supabase_auth_admin");
+		return await run();
+	} finally {
+		await db.query("rollback");
+	}
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const hookCall = (fn) => `${ident$1(fn.schema)}.${ident$1(fn.name)}(current_setting('better_supabase.hook_event')::jsonb) -> 'claims'`;
+/** The claims the hook returns for `userId`, or undefined without that user. */
+async function hookClaims(db, fn, userId) {
+	return withHookEvent(db, userId, async () => {
+		const [row] = await db.query(`select ${hookCall(fn)} as claims`);
+		const claims = typeof row?.claims === "string" ? JSON.parse(row.claims) : row?.claims;
+		return isRecord(claims) ? claims : {};
+	});
+}
+async function hookClaimsSize(db, fn, userId) {
+	return withHookEvent(db, userId, async () => {
 		const [row] = await db.query(`select octet_length(c::text) as bytes,
         octet_length((c -> 'memberships')::text) as memberships,
         octet_length((c -> 'attrs')::text) as attrs,
         c ->> 'memberships_truncated' = 'true' as truncated
-      from (select ${call}(current_setting('better_supabase.hook_event')::jsonb) -> 'claims' as c) h`);
+      from (select ${hookCall(fn)} as c) h`);
 		const memberships = Number(row?.memberships ?? 0);
 		return {
 			bytes: Number(row?.bytes ?? 0),
@@ -531,9 +577,32 @@ async function hookClaimsSize(db, fn, userId) {
 			budget: memberships + Number(row?.attrs ?? 0),
 			truncated: row?.truncated === true
 		};
-	} finally {
-		await db.query("rollback");
-	}
+	});
+}
+const LOCAL_HOSTS = /* @__PURE__ */ new Set([
+	"localhost",
+	"127.0.0.1",
+	"[::1]",
+	"host.docker.internal"
+]);
+/** The `secrets = ...` line of `[auth.hook.<hook>]` reads an `env()` value. */
+function secretsFromEnv(text, hook) {
+	const start = text.search(new RegExp(`^\\s*\\[auth\\.hook\\.${hook}\\]`, "m"));
+	if (start < 0) return false;
+	const rest = text.slice(start).split("\n").slice(1);
+	const end = rest.findIndex((line) => /^\s*\[/.test(line));
+	const section = (end < 0 ? rest : rest.slice(0, end)).join("\n");
+	return /^\s*secrets\s*=\s*["']env\(/m.test(section);
+}
+/**
+* What is wrong with one Standard Webhooks secret (`v1,whsec_<base64>`), the
+* format Auth signs HTTP hook requests with. Never quotes the secret.
+*/
+function secretProblem(secret) {
+	const match = /^v1,whsec_([A-Za-z0-9+/]+={0,2})$/.exec(secret.trim());
+	if (!match) return "is not in the `v1,whsec_<base64>` format";
+	const bytes = atob(match[1]).length;
+	return bytes < 24 || bytes > 64 ? `decodes to ${bytes} bytes; Standard Webhooks secrets are 24 to 64` : void 0;
 }
 const HOOK_RULES = [
 	{
@@ -658,7 +727,7 @@ const HOOK_RULES = [
 					if (fn.source === void 0 || isPermdockHook(context, fn)) continue;
 					const kit = KIT_MEMBERSHIPS.test(fn.source);
 					const wrapper = wrapsPermdockHook(context, fn.source);
-					const written = writtenClaims(fn.source, [...ownedClaims(context.config.claims.tenant), ...wrapper ? registered.keys() : []]);
+					const written = writtenClaims(fn.source, [...ownedClaims(context), ...wrapper ? registered.keys() : []]);
 					if (!kit && written.length === 0) continue;
 					const permdock = project ? permdockSource(project) : PERMDOCK_CALL.test(fn.source) ? "the hook body" : void 0;
 					if (!permdock) continue;
@@ -683,6 +752,363 @@ const HOOK_RULES = [
 			}
 			return findings;
 		}
+	},
+	{
+		code: "BS410",
+		severity: "warning",
+		title: "HTTP auth hooks",
+		description: "Auth calls an `http://` or `https://` hook with a request signed by the Standard Webhooks secret in `secrets` (`v1,whsec_<base64>`, several joined with `|`). Doctor can't read the endpoint's code, so it reports each HTTP hook and checks what it can: the secret's format, that it comes from `env()` rather than the committed file, and that a non-local endpoint uses https. Verify the request in the endpoint with `authHook` from `better-supabase/webhooks`.",
+		check: (context) => {
+			const toml = context.configToml;
+			if (!toml) return [];
+			return httpHooks(toml.document).flatMap(({ hook, uri, secrets }) => {
+				const location = hookLocation(context, hook);
+				const at = location ? { location } : {};
+				const target = `[auth.hook.${hook}]`;
+				const findings = [{
+					severity: "info",
+					message: `${target} calls ${uri.origin}${uri.pathname} over HTTP. Doctor can't check its code; verify the signature there with authHook from better-supabase/webhooks.`,
+					target,
+					...at
+				}];
+				if (uri.protocol === "http:" && !LOCAL_HOSTS.has(uri.hostname)) findings.push({
+					message: `${target} sends claims and its signature to ${uri.host} over plain http. Use https.`,
+					target,
+					...at
+				});
+				const fromEnv = secretsFromEnv(toml.text, hook);
+				if (secrets === void 0 || secrets.trim() === "") {
+					findings.push({
+						severity: "error",
+						message: `${target} has no \`secrets\`, so Auth can't sign its requests. Set \`secrets = "env(AUTH_HOOK_SECRET)"\` with a \`v1,whsec_<base64>\` value.`,
+						target,
+						...at
+					});
+					return findings;
+				}
+				if (!fromEnv) findings.push({
+					message: `${target} has its secret written in ${toml.path}, which is committed. Move it to an env file and read it with \`secrets = "env(AUTH_HOOK_SECRET)"\`.`,
+					target,
+					...at
+				});
+				if (fromEnv && secrets.trim().startsWith("env(")) return findings;
+				const problems = secrets.split("|").flatMap((secret, index) => {
+					const problem = secretProblem(secret);
+					return problem ? [`secret ${index + 1} ${problem}`] : [];
+				});
+				if (problems.length > 0) findings.push({
+					severity: "error",
+					message: `${target}: ${problems.join("; ")}. Auth rejects the config; generate one with \`openssl rand -base64 32\` and prefix it with \`v1,whsec_\`.`,
+					target,
+					...at
+				});
+				return findings;
+			});
+		}
+	}
+];
+//#endregion
+//#region src/cli/doctor/kits.ts
+/** The non-empty string at a dotted path, as the tenant() plugin reads it. */
+function claimAt(claims, path) {
+	let value = claims;
+	for (const segment of path.split(".")) value = isRecord(value) ? value[segment] : void 0;
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function contractChecks(context) {
+	return customContracts(context.config.sql.kit, kitLayout(context.config)).flatMap((contract) => contract.functions.map((fn) => ({
+		module: contract.module,
+		schema: contract.schema,
+		name: fn.name,
+		args: contractSignature(fn, contract.idType),
+		returns: fn.returns.replaceAll("{id}", contract.idType)
+	})));
+}
+const escapeRegExp = (value) => value.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const ident = (name) => `"?${escapeRegExp(name)}"?`;
+/** Whether a `create function schema.name(` appears in the SQL files. */
+function declared(context, check) {
+	const pattern = new RegExp(`create\\s+(?:or\\s+replace\\s+)?function\\s+${ident(check.schema)}\\.${ident(check.name)}\\s*\\(`, "i");
+	return (context.sqlFiles ?? []).some((file) => pattern.test(file.text));
+}
+const normalize$1 = (types) => types.replaceAll(/\s+/g, " ").replaceAll(/\s*,\s*/g, ", ").trim();
+const PRE_REQUEST_HOOK = `select h.hook,
+  coalesce(pg_catalog.strpos(pg_catalog.pg_get_functiondef(pg_catalog.to_regproc(h.hook)), 'better_supabase.check_request') > 0, false) as calls
+from (
+  select (
+    select pg_catalog.split_part(setting, '=', 2)
+    from pg_catalog.pg_db_role_setting s
+    join pg_catalog.pg_roles r on r.oid = s.setrole
+    cross join lateral pg_catalog.unnest(s.setconfig) setting
+    where r.rolname = 'authenticator' and s.setdatabase = 0
+      and setting like 'pgrst.db_pre_request=%'
+    limit 1
+  ) as hook
+) h`;
+/** `rate-limit` in `sql.kit` without PostgREST's pre-request hook reaching `check_request()`. */
+async function rateLimitHook(context) {
+	const db = context.database;
+	if (!context.config.sql.kit.includes("rate-limit") || !db || "skipped" in db) return [];
+	let rows;
+	try {
+		rows = await db.query(PRE_REQUEST_HOOK);
+	} catch {
+		return [];
+	}
+	const [row] = rows;
+	if (!row || row.hook === "better_supabase.check_request" || row.calls) return [];
+	return [{
+		message: row.hook === null ? "pgrst.db_pre_request isn't set for authenticator, so better_supabase.check_request() never runs. Apply the migration `better-supabase sql data` writes, which sets it." : `pgrst.db_pre_request is ${row.hook}, which doesn't call better_supabase.check_request(), so rate limits never apply. Call it from ${row.hook}.`,
+		target: "authenticator pgrst.db_pre_request"
+	}];
+}
+/** Custom-mode modules whose contract functions the database or SQL files don't have. */
+async function missingContracts(context) {
+	const checks = contractChecks(context);
+	if (checks.length === 0) return [];
+	const db = context.database;
+	const live = db && !("skipped" in db) ? db : void 0;
+	if (!live) return checks.filter((check) => !declared(context, check)).map((check) => ({
+		message: `kits.${check.module} is in custom mode, but no SQL file declares ${check.schema}.${check.name}(${check.args}). Write it, or switch the module to adopt or managed.`,
+		target: `${check.schema}.${check.name}`,
+		object: {
+			kind: "function",
+			schema: check.schema,
+			name: check.name
+		}
+	}));
+	const names = checks.map((check) => `(${literal(check.schema)}, ${literal(check.name)})`).join(", ");
+	let rows;
+	try {
+		rows = await live.query(`select n.nspname as schema, p.proname as name,
+        oidvectortypes(p.proargtypes) as args,
+        format_type(p.prorettype, null) as returns
+      from pg_proc p join pg_namespace n on n.oid = p.pronamespace
+      where (n.nspname, p.proname) in (${names})`);
+	} catch (cause) {
+		return [{
+			severity: "info",
+			message: `Reading the custom kit contract functions failed: ${errorText(cause)}`,
+			target: "kits"
+		}];
+	}
+	return checks.flatMap((check) => {
+		const found = rows.filter((row) => row.schema === check.schema && row.name === check.name);
+		const target = `${check.schema}.${check.name}`;
+		const object = {
+			kind: "function",
+			schema: check.schema,
+			name: check.name
+		};
+		if (found.length === 0) return [{
+			message: `kits.${check.module} is in custom mode, but ${target}(${check.args}) doesn't exist. Write it, or switch the module to adopt or managed.`,
+			target,
+			object
+		}];
+		const match = found.find((row) => normalize$1(row.args) === normalize$1(check.args));
+		if (!match) return [{
+			message: `${target} takes (${found.map((row) => row.args).join(" | ")}); the ${check.module} contract calls it with (${check.args}).`,
+			target,
+			object
+		}];
+		if (normalize$1(match.returns) !== normalize$1(check.returns)) return [{
+			message: `${target}(${check.args}) returns ${match.returns}; the ${check.module} contract expects ${check.returns}.`,
+			target,
+			object
+		}];
+		return [];
+	});
+}
+/** With the tenant claim as the active tenant, the hook must put it in the token. */
+async function missingTenantClaim(context) {
+	if (!context.config.sql.kit.includes("tenant")) return [];
+	if ((context.config.kits.access?.activeTenant ?? DEFAULT_ACTIVE_TENANT) !== "claim") return [];
+	const userId = context.hookUser;
+	const db = context.database;
+	if (!userId || !db || "skipped" in db || !db.session) return [];
+	const claim = context.config.claims.tenant;
+	const findings = [];
+	for (const { config, extras } of configuredHooks(context)) {
+		if (config.hook !== "custom_access_token" || !extras) continue;
+		for (const fn of extras.functions) {
+			const target = `${signatureOf(fn)}:${claim}`;
+			let claims;
+			try {
+				claims = await hookClaims(db, fn, userId);
+			} catch {
+				continue;
+			}
+			if (claims === void 0) continue;
+			if (tenantClaimPaths(claim).some((path) => claimAt(claims, path) !== void 0)) continue;
+			findings.push({
+				message: `${signatureOf(fn)} returns no \`${claim}\` claim for ${userId} (top level or app_metadata), and kits.access.activeTenant is 'claim', so current_tenant_id() is null and the tenant() plugin rejects their requests. Write the claim in the hook, or set kits.access.activeTenant to 'resolver' (with ServerOptions.tenant) or a profile column.`,
+				target,
+				object: {
+					kind: "function",
+					schema: fn.schema,
+					name: fn.name
+				}
+			});
+		}
+	}
+	return findings;
+}
+/** Where a deprecated symbol is used: a call, a qualified name or a claim lookup. */
+function deprecationPattern(entry) {
+	const [first = "", second] = entry.symbol.split(".");
+	const qualified = second === void 0 ? ident(first) : `${ident(first)}\\.${ident(second)}`;
+	switch (entry.kind) {
+		case "function": return new RegExp(`${qualified}\\s*\\(`, "i");
+		case "table":
+		case "column": return new RegExp(`(?<![\\w."])${qualified}(?![\\w"])`, "i");
+		case "claim": {
+			const name = escapeRegExp(entry.symbol);
+			return new RegExp(`->>?\\s*'${name}'|#>>?\\s*'\\{[^}]*\\b${name}\\b[^}]*\\}'`, "i");
+		}
+		default: {
+			const never = entry.kind;
+			throw new TypeError(`Unknown deprecation kind ${String(never)}`);
+		}
+	}
+}
+const bareWord = (name) => new RegExp(`(?<![\\w"])${ident(name)}(?![\\w"])`, "i");
+/**
+* The line where `text` uses a deprecated symbol. A column also counts
+* unqualified (`m.org_id`) in a statement that names its table, or in a
+* policy on that table.
+*/
+function lineOfUse(entry, text, policyTable) {
+	const direct = lineOf(text, deprecationPattern(entry));
+	if (direct !== void 0 || entry.kind !== "column") return direct;
+	const [table = "", column = ""] = entry.symbol.split(".");
+	let offset = 0;
+	for (const statement of text.split(";")) {
+		const named = policyTable === table || bareWord(table).test(statement);
+		const at = statement.search(bareWord(column));
+		if (named && at !== -1) return text.slice(0, offset + at).split("\n").length;
+		offset += statement.length + 1;
+	}
+}
+/** SQL files and policies that still use a symbol a kit module deprecated or removed. */
+function deprecatedSymbols(context) {
+	const configured = new Set(Object.values(context.config.claims));
+	const entries = kitDeprecations().filter((entry) => context.config.sql.kit.includes(entry.module) && !(entry.kind === "claim" && configured.has(entry.symbol)) && !((entry.kind === "table" || entry.kind === "column") && (context.config.kits[entry.module]?.mode ?? "managed") !== "managed"));
+	if (entries.length === 0) return [];
+	const files = (context.sqlFiles ?? []).filter((file) => !file.path.startsWith("supabase/migrations/") && kitFileVersion(file.text) === void 0);
+	const findings = [];
+	for (const entry of entries) {
+		const status = entry.removed === void 0 ? `deprecated since ${entry.since}` : `removed in ${entry.removed}`;
+		const advice = `the ${entry.module} module's ${entry.kind} ${entry.symbol}, ${status}. Use ${entry.use}.`;
+		for (const file of files) {
+			const line = lineOfUse(entry, file.text);
+			if (line === void 0) continue;
+			findings.push({
+				message: `${file.path} uses ${advice}`,
+				target: `${file.path}:${entry.symbol}`,
+				location: {
+					file: file.path,
+					line
+				}
+			});
+		}
+		for (const table of catalogOf(context).tables) for (const policy of table.policies) {
+			if (lineOfUse(entry, `${policy.using ?? ""}\n${policy.check ?? ""}`, table.name) === void 0) continue;
+			findings.push({
+				message: `Policy "${policy.name}" on ${qualified(table)} uses ${advice}`,
+				target: `${qualified(table)}.${policy.name}:${entry.symbol}`,
+				object: policyObject(table, policy)
+			});
+		}
+	}
+	return findings;
+}
+/** Kit triggers and the equivalent triggers they replace. */
+const EQUIVALENT_TRIGGERS = [{
+	trigger: "bs_updated_at",
+	call: "track_updated_at",
+	pattern: /updated_at|moddatetime|touch/i
+}, {
+	trigger: "bs_audit",
+	call: "audit",
+	pattern: /audit/i
+}];
+/** Tables where a kit trigger and an older trigger do the same work. */
+function duplicateTriggers(context) {
+	return catalogOf(context).tables.flatMap((table) => EQUIVALENT_TRIGGERS.flatMap(({ trigger, call, pattern }) => {
+		if (!table.triggers.some((entry) => entry.name === trigger)) return [];
+		return table.triggers.filter((entry) => entry.name !== trigger && pattern.test(entry.function.split(".").at(-1) ?? "")).map((entry) => ({
+			message: `${qualified(table)} has ${trigger} and ${entry.name} (${entry.function}), so both run on every write. Drop ${entry.name}, or run \`select better_supabase.${call}('${qualified(table)}', replace_trigger => true)\` in a migration.`,
+			target: `${qualified(table)}.${entry.name}`,
+			object: tableObject(table)
+		}));
+	}));
+}
+/** `better_supabase` and every `kits.*.schema` that `[api] schemas` serves through the Data API. */
+function exposedKitSchemas(context) {
+	if (context.config.sql.kit.length === 0) return [];
+	const kitSchemas = /* @__PURE__ */ new Set(["better_supabase"]);
+	for (const module of Object.values(context.config.kits)) if (module?.schema !== void 0) kitSchemas.add(module.schema);
+	return exposedSchemas(context).filter((schema) => kitSchemas.has(schema)).map((schema) => ({
+		message: `The Data API serves the kit schema ${schema}, so its tables and internal helpers are reachable over REST and RPC. Remove it from [api] schemas in supabase/config.toml (and the dashboard's exposed schemas), and call the kit functions through a wrapper in an exposed schema.`,
+		target: schema
+	}));
+}
+function migrationOptions(context) {
+	const kit = new Set(context.config.sql.kit);
+	return migrationOptionUses(context.config.kits).filter((use) => kit.has(use.module)).map((use) => ({
+		message: `${use.message} It exists to adopt an existing schema; remove it once your data matches the managed default.`,
+		target: `kits.${use.module}.options.${use.option}`
+	}));
+}
+const KIT_RULES = [
+	{
+		code: "BS307",
+		severity: "error",
+		title: "Custom kit module without its contract",
+		description: "A module in `kits` uses `mode: 'custom'`, so the app writes its contract functions. One is missing or has another signature, and the modules and TypeScript APIs that call it fail at run time.",
+		check: missingContracts
+	},
+	{
+		code: "BS308",
+		severity: "warning",
+		title: "Tenant claim the hook does not write",
+		description: "With the `tenant` module and `kits.access.activeTenant: 'claim'`, `current_tenant_id()` and the `tenant()` plugin read the tenant from the `claims.tenant` claim, at the top level or in `app_metadata`. With `--as <user id>` doctor calls the custom access token hook for that user and warns when the claims it returns have neither. The default source, `'resolver'`, takes the tenant from the request instead.",
+		check: missingTenantClaim
+	},
+	{
+		code: "BS309",
+		severity: "warning",
+		title: "Deprecated SQL kit symbol",
+		description: "A schema file or policy uses a function, table, column or claim that a kit module deprecated or removed. Deprecated symbols keep a wrapper for at least one minor release; removed ones fail at run time.",
+		check: deprecatedSymbols
+	},
+	{
+		code: "BS310",
+		severity: "warning",
+		title: "Duplicate kit trigger",
+		description: "A table has a kit trigger (`bs_updated_at`, `bs_audit`) and another trigger that does the same work, so both run on every write.",
+		check: duplicateTriggers
+	},
+	{
+		code: "BS313",
+		severity: "warning",
+		title: "Rate limits not wired to PostgREST",
+		description: "The `rate-limit` module is in `sql.kit`, but on the live database `pgrst.db_pre_request` for the `authenticator` role is unset or names a function that doesn't call `better_supabase.check_request()`, so Data API requests are never counted.",
+		check: rateLimitHook
+	},
+	{
+		code: "BS312",
+		severity: "error",
+		title: "Kit schema exposed through the Data API",
+		description: "`[api] schemas` in `config.toml` lists `better_supabase` or a `kits.*.schema`. The kit schemas hold internal tables and helpers that are granted to `authenticated` for policies, so exposing them makes those callable over REST and RPC.",
+		check: exposedKitSchemas
+	},
+	{
+		code: "BS314",
+		severity: "warning",
+		title: "Migration-only kit option",
+		description: "A module in adopt mode sets an option that only exists to match an existing schema: plain invitation tokens, webhook secrets in a column, non-text webhook ids, or a custom outbox source. Remove it once the data matches the managed default.",
+		check: migrationOptions
 	}
 ];
 //#endregion
@@ -1401,6 +1827,56 @@ const DOCS_URL = "https://bettersupabase.com/docs/cli/doctor";
 const writes = (policy) => policy.command === "all" || policy.command === "insert" || policy.command === "update" || policy.command === "delete";
 const publicRoles = (policy) => policy.roles.length === 0 || policy.roles.some((role) => role === "public" || role === "anon");
 const isTrue = (expression) => expression !== null && /^\(*\s*true\s*\)*$/i.test(expression.trim());
+/** The `sql.kit` files as this release renders them, next to what is on disk. */
+async function kitFiles(context) {
+	if (context.config.sql.kit.length === 0) return [];
+	const readSets = context.readSets;
+	const skipped = readSets !== void 0 && "skipped" in readSets;
+	const files = renderKit(context.config.sql.kit, kitLayout(context.config, context.config.sql.testsDir, skipped ? [] : readSets, entitlementsKit(context))).filter((file) => !(skipped && file.module === "read-sets"));
+	return Promise.all(files.map(async (file) => {
+		const current = await readFile(resolve(context.config.root, file.path), "utf8").catch(() => void 0);
+		const version = kitFileVersion(file.contents)?.version ?? 1;
+		return {
+			file,
+			current,
+			behind: current !== void 0 && (kitFileVersion(current)?.version ?? 1) < version
+		};
+	}));
+}
+async function kitVersionsBehind(context) {
+	const findings = [];
+	const upgrade = "Run `better-supabase sql upgrade`";
+	for (const { file, current, behind } of await kitFiles(context)) {
+		if (!behind || current === void 0) continue;
+		findings.push({
+			message: `${file.path} has ${file.module} version ${String(kitFileVersion(current)?.version ?? 1)}; this release ships version ${String(kitFileVersion(file.contents)?.version ?? 1)}. ${upgrade}, then \`${migrationCommand(context.configToml)}\`.`,
+			target: file.path,
+			location: {
+				file: file.path,
+				line: 1
+			}
+		});
+	}
+	const db = context.database;
+	if (!db || "skipped" in db || context.config.sql.kit.length === 0) return findings;
+	let rows;
+	try {
+		rows = await db.query("select name, version from better_supabase.kit_modules");
+	} catch {
+		return findings;
+	}
+	for (const row of rows) {
+		const module = SQL_MODULES[row.name];
+		if (!module || !context.config.sql.kit.includes(row.name)) continue;
+		const version = moduleVersion(module);
+		if (row.version >= version) continue;
+		findings.push({
+			message: `The database has ${row.name} version ${String(row.version)}; this release ships version ${String(version)}. ${upgrade} and apply the migrations it prints.`,
+			target: `better_supabase.kit_modules.${row.name}`
+		});
+	}
+	return findings;
+}
 function authSetting(context, key) {
 	return context.configToml ? tomlGet(context.configToml.document, ["auth", key]) : void 0;
 }
@@ -1729,16 +2205,13 @@ const RULES = [
 			title: "SQL kit files are out of date",
 			description: "A module listed in `sql.kit` differs from the version in this release. Same check as `sql sync --check`.",
 			check: async (context) => {
-				if (context.config.sql.kit.length === 0) return [];
 				const stale = [];
-				const readSets = context.readSets;
-				const skipped = readSets !== void 0 && "skipped" in readSets;
-				for (const file of renderKit(context.config.sql.kit, kitLayout(context.config, context.config.sql.testsDir, skipped ? [] : readSets, entitlementsKit(context)))) {
-					if (skipped && file.module === "read-sets") continue;
-					const current = await readFile(resolve(context.config.root, file.path), "utf8").catch(() => void 0);
-					if (sameKitFile(current, file.contents)) continue;
+				for (const { file, current, behind } of await kitFiles(context)) {
+					if (behind || sameKitFile(current, file.contents)) continue;
+					const edited = current === void 0 ? "" : ` If you edited it, move the change to \`kits.${file.module}\` in better-supabase.config.ts or to the module's SQL hooks: sync overwrites the file.`;
+					const next = file.kind === "data" ? "Run `better-supabase sql sync`, which also writes the rows into a migration, since a schema diff skips them." : `Run \`better-supabase sql sync\`, then \`${migrationCommand(context.configToml)}\`.`;
 					stale.push({
-						message: `${file.path} (${file.module}) is ${current === void 0 ? "missing" : "out of date"}. Run \`better-supabase sql sync\`, then \`${migrationCommand(context.configToml)}\`.`,
+						message: `${file.path} (${file.module}) is ${current === void 0 ? "missing" : "out of date"}. ${next}${edited}`,
 						target: file.path,
 						...current === void 0 ? {} : { location: {
 							file: file.path,
@@ -1785,6 +2258,13 @@ const RULES = [
 				}));
 			}
 		},
+		{
+			code: "BS311",
+			severity: "warning",
+			title: "SQL kit module behind its current version",
+			description: "A module file or `better_supabase.kit_modules` records an older module version than this release ships. Same check as `sql upgrade --check`.",
+			check: kitVersionsBehind
+		},
 		{
 			code: "BS401",
 			severity: "warning",
@@ -1891,7 +2371,8 @@ const RULES = [
 	...SCHEMA_DESIGN_RULES,
 	...HOOK_RULES,
 	...PERMDOCK_RULES,
-	...LIVE_RULES
+	...LIVE_RULES,
+	...KIT_RULES
 ].sort((a, b) => byCodePoint(a.code, b.code));
 const RULE_CODES = RULES.map((rule) => rule.code);
 async function runRules(context, rules = RULES) {