@checkstack/auth-backend 0.4.33 → 0.5.0

package/drizzle/meta/_journal.json

@@ -36,6 +36,13 @@
       "when": 1768390244988,
       "tag": "0004_lucky_power_man",
       "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1780358648193,
+      "tag": "0005_ambitious_oracle",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/auth-backend",
-  "version": "0.4.33",
+  "version": "0.5.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -16,24 +16,26 @@
   },
   "dependencies": {
     "@checkstack/auth-common": "0.7.2",
-    "@checkstack/backend-api": "0.18.0",
+    "@checkstack/backend-api": "0.20.0",
     "@checkstack/notification-common": "1.2.1",
-    "@checkstack/command-backend": "0.1.31",
-    "better-auth": "^1.4.7",
+    "@checkstack/command-backend": "0.1.33",
+    "better-auth": "^1.6.13",
     "drizzle-orm": "^0.45.0",
-    "hono": "^4.12.14",
+    "hono": "^4.12.23",
     "kysely": "^0.28.17",
-    "jose": "^6.1.3",
+    "jose": "^6.2.3",
     "zod": "^4.2.1",
     "@checkstack/common": "0.12.0",
-    "@orpc/server": "^1.13.2"
+    "@orpc/server": "^1.14.4"
   },
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.5",
     "@checkstack/scripts": "0.3.4",
     "@checkstack/tsconfig": "0.0.7",
     "@types/node": "^20.0.0",
+    "@types/pg": "^8.20.0",
     "drizzle-kit": "^0.31.10",
+    "pg": "^8.21.0",
     "typescript": "^5.0.0"
   }
 }

package/src/dcr-ratelimit.it.test.ts

@@ -0,0 +1,133 @@
+/**
+ * DCR rate-limit shared-Postgres conformance (matrix #10).
+ *
+ * The DCR endpoint throttle MUST hold across pods, because an in-memory per-pod
+ * limiter would let N pods each allow the cap = N x the intended limit. This
+ * test simulates TWO pods (two independent pools to the SAME schema) hammering
+ * the same key and asserts the combined count respects the single shared cap.
+ *
+ * Gated behind `CHECKSTACK_IT=1`; connection from `CHECKSTACK_IT_PG_URL`. Runs
+ * in a freshly created, self-cleaning schema.
+ */
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { sql } from "drizzle-orm";
+import { Pool } from "pg";
+import type { SafeDatabase } from "@checkstack/backend-api";
+import * as schema from "./schema";
+import { checkRateLimit } from "./rate-limit";
+
+const PG_URL =
+  process.env.CHECKSTACK_IT_PG_URL ??
+  "postgres://postgres:postgres@localhost:5432/postgres";
+
+const SCHEMA = `it_dcr_ratelimit_${crypto.randomUUID().replace(/-/g, "")}`;
+
+interface Pod {
+  pool: Pool;
+  db: SafeDatabase<typeof schema>;
+  end(): Promise<void>;
+}
+
+function makePod(): Pod {
+  const pool = new Pool({
+    connectionString: PG_URL,
+    options: `-c search_path=${SCHEMA}`,
+  });
+  const db = drizzle(pool, { schema }) as unknown as SafeDatabase<typeof schema>;
+  return { pool, db, end: () => pool.end() };
+}
+
+describe.skipIf(!process.env.CHECKSTACK_IT)("DCR rate-limit (shared Postgres)", () => {
+  let admin: Pool;
+  let podA: Pod;
+  let podB: Pod;
+
+  beforeAll(async () => {
+    admin = new Pool({ connectionString: PG_URL });
+    await admin.query(`CREATE SCHEMA "${SCHEMA}"`);
+    await admin.query(
+      `CREATE TABLE "${SCHEMA}".ai_rate_limit (
+        key text NOT NULL,
+        window_start timestamp NOT NULL,
+        count integer NOT NULL DEFAULT 0,
+        PRIMARY KEY (key, window_start)
+      )`,
+    );
+    podA = makePod();
+    podB = makePod();
+  });
+
+  afterAll(async () => {
+    await podA?.end();
+    await podB?.end();
+    await admin.query(`DROP SCHEMA IF EXISTS "${SCHEMA}" CASCADE`);
+    await admin.end();
+  });
+
+  it("enforces ONE shared cap across two pods (no N x cap leak)", async () => {
+    const key = `dcr:203.0.113.5`;
+    const max = 5;
+    const windowSeconds = 3600;
+    const now = new Date("2026-06-02T12:00:00.000Z");
+
+    // Alternate pods, sharing the same window. After `max` calls the limit is
+    // hit regardless of WHICH pod served the call.
+    const results = [];
+    for (let i = 0; i < 8; i++) {
+      const pod = i % 2 === 0 ? podA : podB;
+      results.push(
+        await checkRateLimit({ db: pod.db, key, max, windowSeconds, now }),
+      );
+    }
+
+    const allowedCount = results.filter((r) => r.allowed).length;
+    // Exactly `max` allowed across BOTH pods — not `max` per pod.
+    expect(allowedCount).toBe(max);
+    expect(results[results.length - 1].allowed).toBe(false);
+    expect(results[results.length - 1].count).toBe(8);
+  });
+
+  it("resets in the next window", async () => {
+    const key = `dcr:198.51.100.9`;
+    const first = await checkRateLimit({
+      db: podA.db,
+      key,
+      max: 1,
+      windowSeconds: 60,
+      now: new Date("2026-06-02T12:00:30.000Z"),
+    });
+    expect(first.allowed).toBe(true);
+    const sameWindow = await checkRateLimit({
+      db: podB.db,
+      key,
+      max: 1,
+      windowSeconds: 60,
+      now: new Date("2026-06-02T12:00:45.000Z"),
+    });
+    expect(sameWindow.allowed).toBe(false);
+    const nextWindow = await checkRateLimit({
+      db: podA.db,
+      key,
+      max: 1,
+      windowSeconds: 60,
+      now: new Date("2026-06-02T12:01:05.000Z"),
+    });
+    expect(nextWindow.allowed).toBe(true); // fresh window, counter reset
+  });
+
+  it("verifies the counter is visible from a second pod (durable, not pod-local)", async () => {
+    const key = `dcr:192.0.2.1`;
+    const now = new Date("2026-06-02T13:00:00.000Z");
+    await checkRateLimit({ db: podA.db, key, max: 10, windowSeconds: 3600, now });
+    // Pod B reads the SAME counter row written by pod A.
+    const windowStart = new Date("2026-06-02T13:00:00.000Z");
+    const rows = await podB.db
+      .select({ count: schema.aiRateLimit.count })
+      .from(schema.aiRateLimit)
+      .where(
+        sql`${schema.aiRateLimit.key} = ${key} AND ${schema.aiRateLimit.windowStart} = ${windowStart}`,
+      );
+    expect(rows[0]?.count).toBe(1);
+  });
+});

package/src/index.ts

@@ -3,12 +3,14 @@ import * as socialProviderFactories from "better-auth/social-providers";
 import { drizzleAdapter } from "better-auth/adapters/drizzle";
 import { APIError, createAuthEndpoint } from "better-auth/api";
 import { setSessionCookie } from "better-auth/cookies";
+import { mcp } from "better-auth/plugins";
 import { z } from "zod";
 import {
   createBackendPlugin,
   coreServices,
   coreHooks,
   authenticationStrategyServiceRef,
+  assertMigrationChainFromV1,
   type AuthStrategy,
 } from "@checkstack/backend-api";
 import {
@@ -20,12 +22,12 @@ import {
 } from "@checkstack/auth-common";
 import { NotificationApi } from "@checkstack/notification-common";
 import * as schema from "./schema";
-import { eq, inArray } from "drizzle-orm";
+import { eq } from "drizzle-orm";
 import { SafeDatabase } from "@checkstack/backend-api";
 import { BetterAuthOptions, User } from "better-auth/types";
 import { verifyPassword } from "better-auth/crypto";
 import { createExtensionPoint } from "@checkstack/backend-api";
-import { enrichUser } from "./utils/user";
+import { enrichUser, enrichApplicationPrincipal } from "./utils/user";
 import { ADMIN_ROLE_ID, createAuthRouter } from "./router";
 import { validateStrategySchema } from "./utils/validate-schema";
 import {
@@ -37,9 +39,29 @@ import {
   PLATFORM_REGISTRATION_CONFIG_VERSION,
   PLATFORM_REGISTRATION_CONFIG_ID,
 } from "./platform-registration-config";
+import {
+  mcpOAuthConfigV1,
+  MCP_OAUTH_CONFIG_VERSION,
+  MCP_OAUTH_CONFIG_ID,
+} from "./mcp-oauth-config";
+import {
+  narrowedPrincipalFromSession,
+  introspectOpaqueToken,
+  opaqueBearerToken,
+} from "./oauth-branch";
+import { checkRateLimit } from "./rate-limit";
 import { registerSearchProvider } from "@checkstack/command-backend";
 import { resolveRoute, extractErrorMessage} from "@checkstack/common";
 
+/** Best-effort client IP for the DCR rate-limit key (proxy headers first). */
+function clientIpOf(req: Request): string {
+  return (
+    req.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ||
+    req.headers.get("x-real-ip") ||
+    "unknown"
+  );
+}
+
 export interface BetterAuthExtensionPoint {
   addStrategy(strategy: AuthStrategy<unknown>): void;
 }
@@ -316,6 +338,19 @@ export default createBackendPlugin({
         // Validate that the strategy schema doesn't have required fields without defaults
         try {
           validateStrategySchema(s.configSchema, s.id);
+          // Fail fast at registration (boot) if the strategy's
+          // v1->configVersion migration chain is incomplete or broken.
+          // Auth's read path migrates-then-validates via
+          // `configService.get(id, schema, configVersion, migrations)`, so a
+          // missing covering migration would otherwise only surface LAZILY
+          // on the first stale read. This guard surfaces it at boot for
+          // every registered strategy exactly once — `addStrategy` is the
+          // single canonical registration chokepoint (all read sites in
+          // index.ts/router.ts only consume the already-registered list).
+          assertMigrationChainFromV1({
+            version: s.configVersion,
+            migrations: s.migrations ?? [],
+          });
         } catch (error) {
           const message =
             extractErrorMessage(error);
@@ -388,48 +423,22 @@ export default createBackendPlugin({
                       // Ignore errors from lastUsedAt update
                     });
 
-                  // Fetch roles and compute access rules for the application
-                  const appRoles = await db
-                    .select({ roleId: schema.applicationRole.roleId })
-                    .from(schema.applicationRole)
-                    .where(
-                      eq(schema.applicationRole.applicationId, applicationId),
-                    );
-
-                  const roleIds = appRoles.map((r) => r.roleId);
-
-                  // Get access rules for these roles
-                  let accessRulesArray: string[] = [];
-                  if (roleIds.length > 0) {
-                    const rolePerms = await db
-                      .select({
-                        accessRuleId: schema.roleAccessRule.accessRuleId,
-                      })
-                      .from(schema.roleAccessRule)
-                      .where(inArray(schema.roleAccessRule.roleId, roleIds));
-
-                    accessRulesArray = [
-                      ...new Set(rolePerms.map((rp) => rp.accessRuleId)),
-                    ];
-                  }
-
-                  // Get team memberships for this application
-                  const appTeams = await db
-                    .select({ teamId: schema.applicationTeam.teamId })
-                    .from(schema.applicationTeam)
-                    .where(
-                      eq(schema.applicationTeam.applicationId, applicationId),
-                    );
-                  const teamIds = appTeams.map((t) => t.teamId);
+                  // Resolve roles, access rules, and teams via the shared
+                  // helper (same path as the app-principal token branch).
+                  const enriched = await enrichApplicationPrincipal(
+                    applicationId,
+                    db,
+                  );
+                  if (!enriched) return;
 
                   // Return ApplicationUser
                   return {
                     type: "application" as const,
-                    id: app.id,
-                    name: app.name,
-                    roles: roleIds,
-                    accessRules: accessRulesArray,
-                    teamIds,
+                    id: enriched.id,
+                    name: enriched.name,
+                    roles: enriched.roles,
+                    accessRules: enriched.accessRules,
+                    teamIds: enriched.teamIds,
                   };
                 }
               }
@@ -438,6 +447,40 @@ export default createBackendPlugin({
           return; // Invalid API key
         }
 
+        // Bearer OAuth-access-token branch (AI platform MCP / OAuth AS).
+        //
+        // Tokens are OPAQUE (decision §11): introspect the token against the
+        // oidcProvider-owned token table, then build a principal whose access
+        // rules are the token's GRANTED scopes intersected with the bound
+        // user's LIVE access rules. Narrow-only, re-evaluated live every call.
+        // autoAuthMiddleware remains the single enforcement point; this branch
+        // only PRODUCES the narrowed principal. A miss falls through to session.
+        const opaqueToken = opaqueBearerToken(request);
+        if (opaqueToken) {
+          const session = await introspectOpaqueToken({
+            db,
+            token: opaqueToken,
+          });
+          if (session) {
+            const userRow = await db
+              .select()
+              .from(schema.user)
+              .where(eq(schema.user.id, session.userId))
+              .limit(1);
+            if (userRow.length > 0) {
+              const base = await enrichUser(userRow[0], db);
+              const catalogRows = await db
+                .select({ id: schema.accessRule.id })
+                .from(schema.accessRule);
+              const narrowed = narrowedPrincipalFromSession({
+                session,
+                principal: { base, catalog: catalogRows.map((r) => r.id) },
+              });
+              if (narrowed) return narrowed;
+            }
+          }
+        }
+
         // Fall back to session-based authentication (better-auth)
         if (!auth) {
           return; // Not initialized yet
@@ -628,6 +671,39 @@ export default createBackendPlugin({
           const registrationAllowed =
             platformRegistrationConfig?.allowRegistration ?? true;
 
+          // AI platform OAuth AS + MCP server settings (off by default).
+          const mcpOAuthConfig = await config.get(
+            MCP_OAUTH_CONFIG_ID,
+            mcpOAuthConfigV1,
+            MCP_OAUTH_CONFIG_VERSION,
+          );
+          const mcpEnabled = mcpOAuthConfig?.enabled ?? false;
+
+          // The OAuth AS + MCP plugin. Enabled only when an operator opts in.
+          //
+          // The `mcp` plugin internally instantiates `oidcProvider` from its
+          // `oidcConfig`, so we add ONLY `mcp` here (adding `oidcProvider`
+          // separately would double-register its endpoints). oidcProvider
+          // issues OPAQUE access tokens and owns the token / client / consent
+          // tables (added to the Drizzle schema). The DCR endpoint
+          // (`/mcp/register`) is gated by `allowDynamicClientRegistration`; the
+          // per-IP DCR rate-limit is a separate shared-Postgres counter
+          // enforced in the API route handler below.
+          const aiOAuthPlugins = mcpEnabled
+            ? [
+                mcp({
+                  loginPage: "/auth/login",
+                  resource: `${baseUrl}/api/ai/mcp`,
+                  oidcConfig: {
+                    loginPage: "/auth/login",
+                    consentPage: "/auth/oauth-consent",
+                    allowDynamicClientRegistration:
+                      mcpOAuthConfig?.allowDynamicClientRegistration ?? false,
+                  },
+                }),
+              ]
+            : [];
+
           logger.debug(
             `[auth-backend] Initializing Better Auth with ${
               Object.keys(socialProviders).length
@@ -716,7 +792,7 @@ export default createBackendPlugin({
                 },
               },
             },
-            plugins: [checkstackBridge],
+            plugins: [checkstackBridge, ...aiOAuthPlugins],
           };
 
           return betterAuth(authOptions);
@@ -808,8 +884,44 @@ export default createBackendPlugin({
         );
         rpc.registerRouter(authRouter, authContract);
 
-        // 5. Register Better Auth native handler
-        rpc.registerHttpHandler((req: Request) => auth!.handler(req));
+        // 5. Register Better Auth native handler.
+        //
+        // The Dynamic Client Registration endpoint (`/api/auth/mcp/register`)
+        // is throttled per client IP by a SHARED-POSTGRES fixed-window counter
+        // (state-and-scale §14.5 — never in-memory, so the cap holds across all
+        // pods) BEFORE delegating to better-auth. Every other auth route passes
+        // straight through.
+        rpc.registerHttpHandler(async (req: Request) => {
+          const url = new URL(req.url);
+          if (
+            req.method === "POST" &&
+            url.pathname.endsWith("/mcp/register")
+          ) {
+            const cfg = await config.get(
+              MCP_OAUTH_CONFIG_ID,
+              mcpOAuthConfigV1,
+              MCP_OAUTH_CONFIG_VERSION,
+            );
+            const ip = clientIpOf(req);
+            const result = await checkRateLimit({
+              db: database as SafeDatabase<typeof schema>,
+              key: `dcr:${ip}`,
+              max: cfg?.dcrRateLimitMax ?? 5,
+              windowSeconds: cfg?.dcrRateLimitWindowSeconds ?? 3600,
+            });
+            if (!result.allowed) {
+              return Response.json(
+                {
+                  error: "rate_limit_exceeded",
+                  error_description:
+                    "Too many client registrations from this IP. Try again later.",
+                },
+                { status: 429 },
+              );
+            }
+          }
+          return auth!.handler(req);
+        });
 
         // All auth management endpoints are now via oRPC (see ./router.ts)
         // Note: Admin user seeding removed - handled via onboarding flow
@@ -943,3 +1055,30 @@ export * from "./utils/auth-error-redirect";
 
 // Re-export hooks for cross-plugin communication
 export { authHooks } from "./hooks";
+
+// AI platform OAuth AS surface: scope narrowing, the introspect-time branch,
+// and the shared-Postgres rate limiter (reused/tested by ai-backend + docs).
+export {
+  narrowScopes,
+  expandBundles,
+  SCOPE_BUNDLE,
+  type ScopeBundle,
+} from "./scope-narrowing";
+export {
+  narrowedPrincipalFromSession,
+  introspectOpaqueToken,
+  opaqueBearerToken,
+  type IntrospectedOAuthSession,
+  type LivePrincipal,
+} from "./oauth-branch";
+export {
+  checkRateLimit,
+  windowStartFor,
+  type RateLimitResult,
+} from "./rate-limit";
+export {
+  mcpOAuthConfigV1,
+  MCP_OAUTH_CONFIG_ID,
+  MCP_OAUTH_CONFIG_VERSION,
+  type McpOAuthConfig,
+} from "./mcp-oauth-config";

package/src/mcp-oauth-config.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+
+/**
+ * Platform-level configuration for the AI platform OAuth Authorization Server
+ * and MCP server (Phase 2). Controls Dynamic Client Registration (DCR) and the
+ * per-IP DCR rate-limit. Token/consent/client state itself is owned by the
+ * better-auth `oidcProvider` tables; this is only the operator-facing toggle.
+ */
+export const mcpOAuthConfigV1 = z.object({
+  /**
+   * Whether the OAuth Authorization Server + MCP server are enabled at all.
+   * Off by default so the AS surface only exists once an operator opts in.
+   */
+  enabled: z
+    .boolean()
+    .default(false)
+    .describe(
+      "When enabled, Checkstack acts as an OAuth Authorization Server and serves the MCP endpoint.",
+    ),
+  /**
+   * Whether Dynamic Client Registration (`POST /mcp/register`) is open. When
+   * false, MCP clients must be registered out-of-band by an admin.
+   */
+  allowDynamicClientRegistration: z
+    .boolean()
+    .default(false)
+    .describe(
+      "When enabled, MCP clients may self-register via Dynamic Client Registration.",
+    ),
+  /**
+   * Max DCR registrations allowed per client IP within the fixed window.
+   * Enforced by a shared-Postgres counter (never in-memory) so the cap holds
+   * across all pods.
+   */
+  dcrRateLimitMax: z
+    .number()
+    .int()
+    .positive()
+    .default(5)
+    .describe("Maximum DCR registrations per IP per window."),
+  /** DCR rate-limit window length, in seconds. */
+  dcrRateLimitWindowSeconds: z
+    .number()
+    .int()
+    .positive()
+    .default(3600)
+    .describe("DCR rate-limit fixed-window length in seconds."),
+});
+
+export type McpOAuthConfig = z.infer<typeof mcpOAuthConfigV1>;
+
+export const MCP_OAUTH_CONFIG_VERSION = 1;
+export const MCP_OAUTH_CONFIG_ID = "ai.mcp-oauth";

package/src/migration-chain-contract.test.ts

@@ -0,0 +1,108 @@
+/**
+ * Contract test: every auth strategy registered via the
+ * `betterAuthExtensionPoint.addStrategy` chokepoint MUST have a COMPLETE,
+ * contiguous migration chain from version 1 to its current `configVersion`.
+ *
+ * Auth strategies do NOT use `Versioned`; they expose a bespoke shape
+ * `{ configVersion, configSchema, migrations }` and the read path migrates-
+ * then-validates via `configService.get(id, schema, configVersion, migrations)`.
+ * A missing covering migration would therefore only surface LAZILY on the
+ * first stale read. The boot guard wired into `addStrategy` (see
+ * `index.ts`, `assertMigrationChainFromV1`) turns that into a registration-
+ * time (boot) failure, and this test pins the contract:
+ *
+ *  - the structural guard accepts a representative strategy whose chain is
+ *    complete (the happy path every concrete strategy must satisfy), and
+ *  - the guard BITES on a deliberately-broken chain (so it can never be
+ *    silently no-op'd).
+ *
+ * The concrete core strategies live in their own plugin packages
+ * (`auth-github-backend`, `auth-ldap-backend`, `auth-saml-backend`,
+ * `auth-credential-backend`) — auth-backend does not depend on them, so they
+ * are guarded at THEIR registration via the same shared `addStrategy` boot
+ * guard rather than re-enumerated here. This test owns the guard's contract;
+ * a pure STRUCTURAL check (no `migrate()` runs), so it carries zero per-
+ * strategy upkeep.
+ */
+import { describe, expect, it } from "bun:test";
+import { z } from "zod";
+import {
+  assertMigrationChainFromV1,
+  type AuthStrategy,
+  type Migration,
+} from "@checkstack/backend-api";
+
+const passThrough = (fromVersion: number, toVersion: number): Migration => ({
+  fromVersion,
+  toVersion,
+  description: `pass-through ${fromVersion}->${toVersion}`,
+  migrate: (data) => data,
+});
+
+// Representative strategies mirroring the real shapes: a v1 no-migration
+// strategy (like `credential`) and a v>1 strategy with a complete chain
+// (like `ldap` at v3).
+const v1Strategy: AuthStrategy<{ token: string }> = {
+  id: "fixture-v1",
+  displayName: "Fixture v1",
+  configVersion: 1,
+  configSchema: z.object({ token: z.string().default("") }),
+  requiresManualRegistration: true,
+};
+
+const v3Strategy: AuthStrategy<{ host: string }> = {
+  id: "fixture-v3",
+  displayName: "Fixture v3",
+  configVersion: 3,
+  configSchema: z.object({ host: z.string().default("") }),
+  requiresManualRegistration: false,
+  migrations: [passThrough(1, 2), passThrough(2, 3)],
+};
+
+describe("auth strategy migration-chain contract", () => {
+  it("the registration guard accepts strategies with a complete v1->version chain", () => {
+    for (const strategy of [v1Strategy, v3Strategy]) {
+      expect(
+        () =>
+          assertMigrationChainFromV1({
+            version: strategy.configVersion,
+            migrations: strategy.migrations ?? [],
+          }),
+        `Strategy "${strategy.id}" (configVersion ${strategy.configVersion}) should have a complete chain`,
+      ).not.toThrow();
+    }
+  });
+
+  it("the registration guard rejects a v>1 strategy missing its migrations", () => {
+    const broken: AuthStrategy<{ host: string }> = {
+      id: "fixture-broken-empty",
+      displayName: "Fixture broken",
+      configVersion: 3,
+      configSchema: z.object({ host: z.string().default("") }),
+      requiresManualRegistration: false,
+    };
+    expect(() =>
+      assertMigrationChainFromV1({
+        version: broken.configVersion,
+        migrations: broken.migrations ?? [],
+      }),
+    ).toThrow(/incomplete/);
+  });
+
+  it("the registration guard rejects a gapped chain", () => {
+    const gapped: AuthStrategy<{ host: string }> = {
+      id: "fixture-broken-gap",
+      displayName: "Fixture gapped",
+      configVersion: 3,
+      configSchema: z.object({ host: z.string().default("") }),
+      requiresManualRegistration: false,
+      migrations: [passThrough(1, 2)],
+    };
+    expect(() =>
+      assertMigrationChainFromV1({
+        version: gapped.configVersion,
+        migrations: gapped.migrations ?? [],
+      }),
+    ).toThrow(/incomplete: reaches version 2/);
+  });
+});