@cosmicdrift/kumiko-bundled-features 0.158.2 → 0.160.0

package/src/sessions/__tests__/sessions.integration.test.ts

@@ -1,5 +1,6 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
+import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   configureBlindIndexKey,
@@ -13,6 +14,7 @@ import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   setupTestStack,
   type TestStack,
+  TestUsers,
   testTenantId,
   unsafeCreateEntityTable,
   unsafePushTables,
@@ -65,6 +67,7 @@ beforeAll(async () => {
       createUserFeature(),
       createTenantFeature(),
       createAuthEmailPasswordFeature(),
+      authFoundationFeature,
       createSessionsFeature(),
     ],
     extraContext: { configResolver: resolver, configEncryption: encryption },
@@ -75,7 +78,7 @@ beforeAll(async () => {
     },
   });
   callbacks.set(createSessionCallbacks({ db: stack.db }));
-  h = makeSessionHelpers(stack, TENANT);
+  h = makeSessionHelpers(stack, TENANT, bound.asAuthConfig().sessionCreator);
 
   await unsafeCreateEntityTable(stack.db, userEntity);
   await unsafeCreateEntityTable(stack.db, tenantEntity);
@@ -97,9 +100,10 @@ describe("sessions feature — login → check → revoke → rejected", () => {
     const { sid } = await h.login("persist@example.com", "pw-long-enough");
 
     const rows = await selectMany(stack.db, userSessionTable);
-    expect(rows).toHaveLength(1);
-    expect(rows[0]?.["id"]).toBe(sid);
-    expect(rows[0]?.["revokedAt"]).toBeNull();
+    const userRows = rows.filter((r) => r["userId"] !== TestUsers.systemAdmin.id);
+    expect(userRows).toHaveLength(1);
+    expect(userRows[0]?.["id"]).toBe(sid);
+    expect(userRows[0]?.["revokedAt"]).toBeNull();
   });
 
   test("authenticated request passes while session is live, 401s once revoked", async () => {
@@ -138,8 +142,9 @@ describe("sessions feature — login → check → revoke → rejected", () => {
     expect(logoutRes.status).toBe(200);
 
     const rows = await selectMany(stack.db, userSessionTable);
-    expect(rows[0]?.["id"]).toBe(sid);
-    expect(rows[0]?.["revokedAt"]).not.toBeNull();
+    const row = rows.find((r) => r["id"] === sid);
+    expect(row?.["id"]).toBe(sid);
+    expect(row?.["revokedAt"]).not.toBeNull();
 
     const next = await h.authedPost("/api/query", token, {
       type: "user:query:user:me",
@@ -294,12 +299,13 @@ describe("sessions feature — login → check → revoke → rejected", () => {
     expect(body.error?.details?.reason).toBe("ownership_denied");
   });
 
-  test("revoke-all-others on a sidless JWT refuses loudly (session_required)", async () => {
+  test("revoke-all-others on a sidless JWT is rejected by the middleware (no_sid)", async () => {
     const { userId } = await h.seedUser("sidless@example.com", "pw-long-enough");
 
-    // Hand-sign a JWT without jti — simulates a stateless-JWT deployment
-    // or a rolling-deploy gap. "sign out everywhere else" is ill-defined
-    // without knowing which session is "current", so refuse.
+    // Hand-sign a JWT without jti. Once a sessionChecker is wired there is
+    // no relaxed mode (see session-strict-mode.integration.test.ts) — the
+    // middleware rejects it with no_sid before the handler's own
+    // session_required guard is ever reached.
     const tokenNoSid = await stack.jwt.sign({ id: userId, tenantId: TENANT, roles: ["User"] });
 
     const res = await stack.http.raw(
@@ -308,9 +314,9 @@ describe("sessions feature — login → check → revoke → rejected", () => {
       { type: SessionHandlers.revokeAllOthers, payload: {} },
       { Authorization: `Bearer ${tokenNoSid}` },
     );
-    expect(res.status).toBe(422);
+    expect(res.status).toBe(401);
     const body = (await res.json()) as { error?: { details?: { reason?: string } } };
-    expect(body.error?.details?.reason).toBe("session_required");
+    expect(body.error?.details?.reason).toBe("no_sid");
   });
 
   test("N concurrent revoke+logout requests on the same sid converge safely", async () => {
@@ -491,10 +497,13 @@ describe("sessions feature — login → check → revoke → rejected", () => {
         revokedAt: string | null;
       }>;
     };
-    // Three rows total: Alice's pre-promotion session, Alice's post-promotion
-    // session, Bob's session. Two distinct users.
-    expect(body.data).toHaveLength(3);
-    const userIds = new Set(body.data.map((r) => r.userId));
+    // Three rows total for the two test users: Alice's pre-promotion session,
+    // Alice's post-promotion session, Bob's session. seedUser's bootstrap
+    // actor (systemAdmin) also holds live sessions in this tenant — exclude
+    // them, they aren't part of what this test pins.
+    const nonSystemRows = body.data.filter((r) => r.userId !== TestUsers.systemAdmin.id);
+    expect(nonSystemRows).toHaveLength(3);
+    const userIds = new Set(nonSystemRows.map((r) => r.userId));
     expect(userIds.size).toBe(2);
 
     // Order: most-recently-created first. aliceAsAdmin's session was the
@@ -552,7 +561,9 @@ describe("sessions feature — login → check → revoke → rejected", () => {
   // different tenant must not be able to read another tenant's session rows.
   test("session:detail and session:list never leak sessions across tenants", async () => {
     const TENANT_2 = testTenantId(2);
-    const h2 = makeSessionHelpers(stack, TENANT_2);
+    const h2 = makeSessionHelpers(stack, TENANT_2, (user, meta) =>
+      callbacks.get().sessionCreator(user, meta),
+    );
 
     const { userId: carolId } = await h.seedUser("carol4@example.com", "pw-long-enough");
     await updateRows(

package/src/sessions/__tests__/test-helpers.ts

@@ -9,12 +9,14 @@
 //   const res = await h.authedPost("/api/query", token, { type, payload });
 
 import { expect } from "bun:test";
+import type { SessionCreator } from "@cosmicdrift/kumiko-framework/api";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { type TestStack, TestUsers } from "@cosmicdrift/kumiko-framework/stack";
 import * as jose from "jose";
 import { hashPassword } from "../../shared";
 import { seedTenantMembership } from "../../tenant/seeding";
 import { UserHandlers } from "../../user";
+import { withMintedSession } from "../testing";
 
 export type LoginResult = {
   readonly token: string;
@@ -25,7 +27,15 @@ export type LoginResult = {
 // `ReturnType<typeof makeSessionHelpers>` — no separate type export to
 // keep in sync with the implementation. Params are typed inline on each
 // method so the inference is sharp.
-export function makeSessionHelpers(stack: TestStack, tenantId: TenantId) {
+// `sessionCreator` is only needed when the suite wires a real sessionChecker
+// (auth-middleware then rejects the sidless systemAdmin bootstrap actor
+// used by seedUser). Suites without a sessionChecker (e.g. PAT tests) can
+// omit it.
+export function makeSessionHelpers(
+  stack: TestStack,
+  tenantId: TenantId,
+  sessionCreator?: SessionCreator,
+) {
   return {
     async seedUser(
       email: string,
@@ -33,10 +43,13 @@ export function makeSessionHelpers(stack: TestStack, tenantId: TenantId) {
       opts?: { roles?: readonly string[] },
     ): Promise<{ userId: string }> {
       const hash = await hashPassword(password);
+      const actor = sessionCreator
+        ? await withMintedSession(sessionCreator, TestUsers.systemAdmin)
+        : TestUsers.systemAdmin;
       const created = await stack.http.writeOk<{ id: string }>(
         UserHandlers.create,
         { email, passwordHash: hash, displayName: email.split("@")[0] ?? "u" },
-        TestUsers.systemAdmin,
+        actor,
       );
       await seedTenantMembership(stack.db, {
         userId: created.id,

package/src/sessions/feature.ts

@@ -1,3 +1,8 @@
+import {
+  EXT_SESSION_STORE,
+  type SessionStore,
+  type SessionStoreProvider,
+} from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import { buildEntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
@@ -14,7 +19,11 @@ import { revokeAllForUserWrite } from "./handlers/revoke-all-for-user.write";
 import { revokeAllOthersWrite } from "./handlers/revoke-all-others.write";
 import { SESSIONS_I18N } from "./i18n";
 import { userSessionEntity } from "./schema/user-session";
-import type { SessionAllOthersRevoker, SessionMassRevoker } from "./session-callbacks";
+import {
+  createSessionCallbacks,
+  type SessionAllOthersRevoker,
+  type SessionMassRevoker,
+} from "./session-callbacks";
 
 export type SessionsFeatureOptions = {
   // A successful update on the `user` entity that changes the `passwordHash`
@@ -76,7 +85,7 @@ export function bindAutoRevokeFromFeature(
 export function createSessionsFeature(options?: SessionsFeatureOptions): FeatureDefinition {
   return defineFeature("sessions", (r) => {
     r.describe(
-      "Tracks signed-in clients in the `store_user_sessions` table (one row per JWT, keyed by the `sid`/`jti` claim) and exposes handlers for `mine` (list your sessions), `revoke`, and `revokeAllOthers`. Session creation and revocation on the hot auth path are handled by `createSessionCallbacks()`, wired into `buildServer({ auth: { ... } })` outside the dispatcher; the feature also ships a manual-trigger cleanup job for pruning expired rows and an optional `autoRevokeOnPasswordChange` hook that mass-revokes all sessions for a user whenever their `passwordHash` changes.",
+      "Tracks signed-in clients in the `store_user_sessions` table (one row per JWT, keyed by the `sid`/`jti` claim) and exposes handlers for `mine` (list your sessions), `revoke`, and `revokeAllOthers`. Session creation and revocation on the hot auth path are handled by `createSessionCallbacks()`, wired into `buildServer({ auth: { ... } })` outside the dispatcher; the same callbacks are also registered as an auth-foundation sessionStore provider, resolvable generically via `resolveSessionStore()`. The feature also ships a manual-trigger cleanup job for pruning expired rows and an optional `autoRevokeOnPasswordChange` hook that mass-revokes all sessions for a user whenever their `passwordHash` changes.",
     );
     r.uiHints({
       displayLabel: "Sessions · Server-side Logout",
@@ -86,7 +95,9 @@ export function createSessionsFeature(options?: SessionsFeatureOptions): Feature
     // sessionChecker reads read_users on every authenticated request (status
     // gate for locked accounts) — make that a boot-time dependency so a
     // sessions-without-user wiring fails validateBoot instead of 500ing live.
-    r.requires("user");
+    // auth-foundation owns EXT_SESSION_STORE, which the useExtension below
+    // registers against.
+    r.requires("user", "auth-foundation");
     // store_user_sessions is a hot-path direct-write store: sessionCreator
     // inserts and the revoke handlers update rows WITHOUT emitting lifecycle
     // events (the row columns ARE the audit trail). Registering it as
@@ -102,6 +113,23 @@ export function createSessionsFeature(options?: SessionsFeatureOptions): Feature
       piiEncryptedOnWrite: true,
     });
 
+    // Self-registers as auth-foundation's sessionStore provider (#1371) —
+    // wraps the same createSessionCallbacks() used by the manual
+    // buildServer({ auth: { ... } }) wiring above; a future issue (#1372)
+    // removes that manual wiring once the middleware resolves generically
+    // via resolveSessionStore().
+    r.useExtension(EXT_SESSION_STORE, "default", {
+      build: (deps): SessionStore => {
+        const callbacks = createSessionCallbacks({ db: deps.db });
+        return {
+          creator: callbacks.sessionCreator,
+          revoker: callbacks.sessionRevoker,
+          checker: callbacks.sessionChecker,
+          massRevoker: callbacks.sessionMassRevoker,
+        };
+      },
+    } satisfies SessionStoreProvider);
+
     const handlers = {
       revoke: r.writeHandler(revokeWrite),
       revokeAllOthers: r.writeHandler(revokeAllOthersWrite),

package/src/sessions/handlers/detail.query.ts

@@ -27,9 +27,9 @@ export const detailQuery = defineQueryHandler({
       createdAt: row.createdAt,
       expiresAt: row.expiresAt,
       revokedAt: row.revokedAt,
-      ip: row.ip ? await decryptStoredPii(row.ip, "sessions:detail") : row.ip,
+      ip: row.ip ? await decryptStoredPii(row.ip, "ip", "sessions:detail") : row.ip,
       userAgent: row.userAgent
-        ? await decryptStoredPii(row.userAgent, "sessions:detail")
+        ? await decryptStoredPii(row.userAgent, "userAgent", "sessions:detail")
         : row.userAgent,
     };
   },

package/src/sessions/handlers/list.query.ts

@@ -30,8 +30,10 @@ export const listQuery = defineQueryHandler({
         createdAt: r.createdAt,
         expiresAt: r.expiresAt,
         revokedAt: r.revokedAt,
-        ip: r.ip ? await decryptStoredPii(r.ip, "sessions:list") : r.ip,
-        userAgent: r.userAgent ? await decryptStoredPii(r.userAgent, "sessions:list") : r.userAgent,
+        ip: r.ip ? await decryptStoredPii(r.ip, "ip", "sessions:list") : r.ip,
+        userAgent: r.userAgent
+          ? await decryptStoredPii(r.userAgent, "userAgent", "sessions:list")
+          : r.userAgent,
       })),
     );
   },

package/src/sessions/handlers/mine.query.ts

@@ -32,8 +32,10 @@ export const mineQuery = defineQueryHandler({
         id: r.id,
         createdAt: r.createdAt,
         expiresAt: r.expiresAt,
-        ip: r.ip ? await decryptStoredPii(r.ip, "sessions:mine") : r.ip,
-        userAgent: r.userAgent ? await decryptStoredPii(r.userAgent, "sessions:mine") : r.userAgent,
+        ip: r.ip ? await decryptStoredPii(r.ip, "ip", "sessions:mine") : r.ip,
+        userAgent: r.userAgent
+          ? await decryptStoredPii(r.userAgent, "userAgent", "sessions:mine")
+          : r.userAgent,
         current: currentSid === r.id,
       })),
     );

package/src/sessions/testing.ts

@@ -17,7 +17,8 @@
 // sessions feature owns. framework/testing only provides the generic
 // `createLateBoundHolder<T>` — shape-independent.
 
-import type { AuthRoutesConfig } from "@cosmicdrift/kumiko-framework/api";
+import type { AuthRoutesConfig, SessionCreator } from "@cosmicdrift/kumiko-framework/api";
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
 import type { LateBoundHolder } from "@cosmicdrift/kumiko-framework/testing";
 import type { SessionCallbacks, SessionMassRevoker } from "./session-callbacks";
 
@@ -40,3 +41,15 @@ export function sessionCallbacksFromLateBound(
     asMassRevoker: () => (userId) => holder.get().sessionMassRevoker(userId),
   };
 }
+
+// Bootstrap actors (system-admin seed writes) need a real sid once a
+// sessionChecker is wired — auth-middleware rejects sidless JWTs as
+// forged/pre-session-tracking. Mints a live session row and returns the
+// actor with `sid` attached so `stack.http.writeOk(..., actor)` passes.
+export async function withMintedSession(
+  sessionCreator: SessionCreator,
+  user: SessionUser,
+): Promise<SessionUser> {
+  const sid = await sessionCreator(user, { ip: "127.0.0.1", userAgent: "test" });
+  return { ...user, sid };
+}

package/src/shared/__tests__/chunked-entity-migration.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, test } from "bun:test";
+import { runChunkedMigration } from "../chunked-entity-migration";
+
+describe("runChunkedMigration", () => {
+  test("processes all batches and stops with 'done' when nextBatch returns empty", async () => {
+    const batches: readonly number[][] = [[1, 2], [3], []];
+    let call = 0;
+    const migrated: number[] = [];
+
+    const result = await runChunkedMigration<number>({
+      nextBatch: async () => batches[call++] ?? [],
+      migrateRow: async (row) => {
+        migrated.push(row);
+        return "migrated";
+      },
+      maxFailures: 10,
+      deadlineAt: Number.POSITIVE_INFINITY,
+    });
+
+    expect(migrated).toEqual([1, 2, 3]);
+    expect(result).toEqual({
+      migrated: 3,
+      skipped: 0,
+      failed: 0,
+      batchesProcessed: 2,
+      stoppedReason: "done",
+    });
+  });
+
+  test("counts skipped and failed outcomes separately from migrated", async () => {
+    let call = 0;
+    const rows = [
+      { id: 1, outcome: "migrated" as const },
+      { id: 2, outcome: "skipped" as const },
+      { id: 3, outcome: "failed" as const },
+    ];
+
+    const result = await runChunkedMigration({
+      nextBatch: async () => (call++ === 0 ? rows : []),
+      migrateRow: async (row) => row.outcome,
+      maxFailures: 10,
+      deadlineAt: Number.POSITIVE_INFINITY,
+    });
+
+    expect(result.migrated).toBe(1);
+    expect(result.skipped).toBe(1);
+    expect(result.failed).toBe(1);
+    expect(result.stoppedReason).toBe("done");
+  });
+
+  test("a thrown migrateRow counts as failed and invokes onRowError", async () => {
+    let call = 0;
+    const errors: unknown[] = [];
+    const boom = new Error("boom");
+
+    const result = await runChunkedMigration<number>({
+      nextBatch: async () => (call++ === 0 ? [1] : []),
+      migrateRow: async () => {
+        throw boom;
+      },
+      maxFailures: 10,
+      deadlineAt: Number.POSITIVE_INFINITY,
+      onRowError: (row, err) => errors.push([row, err]),
+    });
+
+    expect(result.failed).toBe(1);
+    expect(errors).toEqual([[1, boom]]);
+  });
+
+  test("stops with 'too_many_failures' once failed >= maxFailures, mid-batch", async () => {
+    let call = 0;
+    const seen: number[] = [];
+
+    const result = await runChunkedMigration<number>({
+      nextBatch: async () => (call++ === 0 ? [1, 2, 3] : []),
+      migrateRow: async (row) => {
+        seen.push(row);
+        return "failed";
+      },
+      maxFailures: 2,
+      deadlineAt: Number.POSITIVE_INFINITY,
+    });
+
+    // The circuit-breaker checks before each row — row 3 is never attempted.
+    expect(seen).toEqual([1, 2]);
+    expect(result.failed).toBe(2);
+    expect(result.stoppedReason).toBe("too_many_failures");
+  });
+
+  test("stops with 'too_many_failures' checked between batches too", async () => {
+    let call = 0;
+    const batches = [["a"], ["b"], ["c"]];
+
+    const result = await runChunkedMigration<string>({
+      nextBatch: async () => batches[call++] ?? [],
+      migrateRow: async () => "failed",
+      maxFailures: 1,
+      deadlineAt: Number.POSITIVE_INFINITY,
+    });
+
+    // Batch 1 processes "a" and pushes failed to 1; the breaker is only
+    // checked at the TOP of the loop, so batch 2 is fetched (batchesProcessed
+    // becomes 2) before the breaker trips and its row is never touched.
+    expect(result.batchesProcessed).toBe(2);
+    expect(result.stoppedReason).toBe("too_many_failures");
+  });
+
+  test("stops with 'timeout' once the deadline has passed, without calling nextBatch again", async () => {
+    let nextBatchCalls = 0;
+
+    const result = await runChunkedMigration<number>({
+      nextBatch: async () => {
+        nextBatchCalls++;
+        return [];
+      },
+      migrateRow: async () => "migrated",
+      maxFailures: 10,
+      deadlineAt: Date.now() - 1,
+    });
+
+    expect(nextBatchCalls).toBe(0);
+    expect(result.batchesProcessed).toBe(0);
+    expect(result.stoppedReason).toBe("timeout");
+  });
+
+  test("stops with 'signal' when the AbortSignal is already aborted", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    let nextBatchCalls = 0;
+
+    const result = await runChunkedMigration<number>({
+      nextBatch: async () => {
+        nextBatchCalls++;
+        return [];
+      },
+      migrateRow: async () => "migrated",
+      maxFailures: 10,
+      deadlineAt: Number.POSITIVE_INFINITY,
+      signal: controller.signal,
+    });
+
+    expect(nextBatchCalls).toBe(0);
+    expect(result.stoppedReason).toBe("signal");
+  });
+});

package/src/shared/decrypt-stored-pii.ts

@@ -6,14 +6,21 @@ import {
 
 // Raw reads (fetchOne/selectMany) return the stored column value — with an
 // active KMS that is ciphertext (self-describing: it names its own subject,
-// so no entity/field context is needed). An erased subject yields the
-// sentinel, which matches no real value.
-export async function decryptStoredPii(value: string, fallbackRequestId: string): Promise<string> {
+// so no entity/field context is needed for key selection). `field` must
+// still match the field name used at encrypt time — it is part of the
+// AAD (#1263), so a mismatch fails decrypt loud rather than silently
+// letting ciphertext cut-and-pasted from another field decrypt. An erased
+// subject yields the sentinel, which matches no real value.
+export async function decryptStoredPii(
+  value: string,
+  field: string,
+  fallbackRequestId: string,
+): Promise<string> {
   const kms = configuredPiiSubjectKms();
   if (!kms) return value;
-  const out = await decryptPiiFieldValues({ value }, ["value"], kms, {
+  const out = await decryptPiiFieldValues({ [field]: value }, [field], kms, {
     requestId: requestContext.get()?.requestId ?? fallbackRequestId,
   });
-  const decrypted = out["value"];
+  const decrypted = out[field];
   return typeof decrypted === "string" ? decrypted : value;
 }

package/src/subscription-mollie/__tests__/feature.test.ts

@@ -1,8 +1,13 @@
 // feature.ts contract tests for subscription-mollie.
 
 import { describe, expect, test } from "bun:test";
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { MollieClient } from "@mollie/api-client";
+import { describeSubscriptionProviderContract } from "../../billing-foundation/__tests__/subscription-provider-contract";
 import { MOLLIE_PROVIDER_NAME, SUBSCRIPTION_MOLLIE_FEATURE } from "../constants";
 import { createSubscriptionMollieFeature } from "../feature";
+import { createMollieCheckoutSession } from "../plugin-methods";
+import { type MollieClientShape, verifyAndParseMollieWebhook } from "../verify-webhook";
 
 const VALID_OPTIONS = {
   apiKey: "test_dummy_apikey",
@@ -98,9 +103,91 @@ describe("subscription-mollie — plugin-registration", () => {
       createPortalSession?: unknown;
       cancelSubscription?: unknown;
     };
+    // Checks the mounted feature (the contract below builds its plugin
+    // by hand-wiring and would not catch a wiring gap here).
     expect(typeof plugin?.verifyAndParseWebhook).toBe("function");
     expect(typeof plugin?.createCheckoutSession).toBe("function");
     expect(plugin?.createPortalSession).toBeUndefined();
     expect(plugin?.cancelSubscription).toBeUndefined();
   });
 });
+
+// =============================================================================
+// SubscriptionProviderPlugin contract
+// =============================================================================
+//
+// Built directly from the plugin-method constructors (not from
+// createSubscriptionMollieFeature's mounted plugin) — same reasoning as
+// subscription-stripe's contract fixture: keeps SDK-call mocking local to
+// the fixture instead of routing through the full feature-mount.
+
+const CONTRACT_TENANT_ID = "tenant-contract";
+const CONTRACT_PRICE_ID = "plan_pro";
+
+function buildMollieContractFixture() {
+  const subscription = {
+    id: "sub_contract_001",
+    customerId: "cst_contract_001",
+    status: "active",
+    nextPaymentDate: "2026-06-15",
+    startDate: "2026-05-15",
+    metadata: { tenantId: CONTRACT_TENANT_ID, priceId: CONTRACT_PRICE_ID },
+    // biome-ignore lint/suspicious/noExplicitAny: minimal Mollie-SDK-shape mock
+  } as any;
+  const payment = {
+    id: "tr_contract_001",
+    customerId: "cst_contract_001",
+    subscriptionId: "sub_contract_001",
+    sequenceType: "first",
+    status: "paid",
+    // biome-ignore lint/suspicious/noExplicitAny: minimal Mollie-SDK-shape mock
+  } as any;
+
+  const webhookClient: MollieClientShape = {
+    payments: { get: async () => payment },
+    customerSubscriptions: {
+      get: async () => subscription,
+      list: async () => [],
+      create: async () => subscription,
+    },
+  };
+
+  const checkoutClient = {
+    customers: { create: async () => ({ id: "cus_contract" }) },
+    payments: {
+      create: async () => ({
+        getCheckoutUrl: () => "https://www.mollie.com/checkout/contract-test",
+      }),
+    },
+  } as unknown as MollieClient;
+
+  return {
+    plugin: {
+      verifyAndParseWebhook: verifyAndParseMollieWebhook(webhookClient, {
+        priceToTier: VALID_OPTIONS.priceToTier,
+        priceToConfig: VALID_OPTIONS.priceToConfig,
+      }),
+      createCheckoutSession: createMollieCheckoutSession(
+        checkoutClient,
+        VALID_OPTIONS.priceToConfig,
+        VALID_OPTIONS.webhookUrl,
+      ),
+      // createPortalSession + cancelSubscription deliberately omitted — Mollie limitation.
+    },
+    ctx: {} as HandlerContext,
+    checkout: {
+      priceId: CONTRACT_PRICE_ID,
+      tenantId: CONTRACT_TENANT_ID,
+      successUrl: "https://example.com/success",
+      cancelUrl: "https://example.com/cancel",
+    },
+    webhook: {
+      rawBody: JSON.stringify({ id: "tr_contract_001" }),
+      headers: { "content-type": "application/json" },
+      expectedTenantId: CONTRACT_TENANT_ID,
+      expectedTier: "pro",
+    },
+  };
+}
+
+describeSubscriptionProviderContract("subscription-mollie", buildMollieContractFixture);