@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/sessions/handlers/cleanup.job.ts

@@ -0,0 +1,109 @@
+// Retention/cleanup job for user_sessions. Without this the table grows
+// monotonically: every login adds one row, logout only flips revokedAt. A
+// long-lived app would eventually accumulate millions of dead rows that
+// slow the sessionChecker point-read down and bloat backups.
+//
+// Policy:
+//   - Delete rows whose expiresAt is older than `olderThanDays` (default
+//     30d). Expired sessions can never go live again; the audit trail
+//     isn't useful past the retention window.
+//   - Delete rows whose revokedAt is older than `olderThanDays`. Same
+//     reasoning: a session revoked months ago has no operational value.
+//   - NEVER delete currently-live rows. Safe by construction — the WHERE
+//     clause requires either expiresAt OR revokedAt to be past-cutoff.
+//
+// Chunked DELETE (default 1000/batch) keeps lock durations bounded. Ops
+// schedules this daily (manual trigger by default — opt-in to cron in the
+// app's feature-wiring so a dev environment doesn't churn through a fresh
+// seed). Mirror of secrets/retention.job in shape.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { JobHandlerFn } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { or, sql } from "drizzle-orm";
+import { userSessionTable } from "../schema/user-session";
+
+const DEFAULT_OLDER_THAN_DAYS = 30;
+const DEFAULT_BATCH_SIZE = 1000;
+
+export type SessionCleanupPayload = {
+  readonly olderThanDays?: number;
+  readonly batchSize?: number;
+  readonly maxDurationMs?: number;
+};
+
+export type SessionCleanupResult = {
+  readonly deleted: number;
+  readonly batchesProcessed: number;
+  readonly stoppedReason: "empty" | "timeout" | "signal";
+};
+
+export const cleanupJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
+  const payload = rawPayload as SessionCleanupPayload;
+  if (!ctx.db) {
+    throw new InternalError({
+      message: "[sessions:cleanup] ctx.db missing — job context requires a database connection.",
+    });
+  }
+  const db = ctx.db as DbConnection;
+
+  // Coerce-and-validate: BullMQ payloads arrive as opaque JSON, so TS types
+  // don't survive. Guard before the value is interpolated into SQL.
+  const olderThanDaysRaw = payload.olderThanDays ?? DEFAULT_OLDER_THAN_DAYS;
+  const olderThanDays = Number(olderThanDaysRaw);
+  if (!Number.isFinite(olderThanDays) || olderThanDays < 0 || !Number.isInteger(olderThanDays)) {
+    throw new InternalError({
+      message: `[sessions:cleanup] olderThanDays must be a non-negative integer (got ${String(olderThanDaysRaw)})`,
+    });
+  }
+  const batchSize = payload.batchSize ?? DEFAULT_BATCH_SIZE;
+  const deadline = payload.maxDurationMs
+    ? Date.now() + payload.maxDurationMs
+    : Number.POSITIVE_INFINITY;
+
+  const cutoff = sql`now() - (${olderThanDays} * interval '1 day')`;
+
+  let deleted = 0;
+  let batchesProcessed = 0;
+  let stoppedReason: SessionCleanupResult["stoppedReason"] = "empty";
+
+  while (true) {
+    if (ctx.signal?.aborted) {
+      stoppedReason = "signal";
+      break;
+    }
+    if (Date.now() >= deadline) {
+      stoppedReason = "timeout";
+      break;
+    }
+
+    // DELETE-by-id-subquery with an explicit LIMIT so the lock stays short.
+    // The WHERE clause is the safety net: we only touch rows that are
+    // PAST-CUTOFF (expired OR revoked), never currently-live sessions. A
+    // null-check in PG semantics: `x < cutoff` already excludes null.
+    const rows = await db
+      .delete(userSessionTable)
+      .where(
+        sql`${userSessionTable["id"]} in (
+          select ${userSessionTable["id"]}
+          from ${userSessionTable}
+          where ${or(
+            sql`${userSessionTable["expiresAt"]} < ${cutoff}`,
+            sql`${userSessionTable["revokedAt"]} < ${cutoff}`,
+          )}
+          limit ${batchSize}
+        )`,
+      )
+      .returning({ id: userSessionTable["id"] });
+
+    if (rows.length === 0) break;
+
+    deleted += rows.length;
+    batchesProcessed++;
+
+    if (rows.length < batchSize) break;
+  }
+
+  const result: SessionCleanupResult = { deleted, batchesProcessed, stoppedReason };
+  ctx.log?.info?.(`[sessions:cleanup] complete: ${JSON.stringify(result)}`);
+};

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

@@ -0,0 +1,35 @@
+import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { desc } from "drizzle-orm";
+import { z } from "zod";
+import { userSessionTable } from "../schema/user-session";
+
+// Admin view of every session in the active tenant. Tenant admins use this
+// to investigate "who is logged in right now" or revoke a suspicious
+// device. Unlike `session:mine` this does NOT filter by userId — it's the
+// whole tenant. Tenant-scoping comes from ctx.db (TenantDb applies a tenant
+// filter automatically on select from tables with a tenantId column), so
+// cross-tenant bleed is impossible.
+//
+// Includes revoked rows too — distinct column in the response tells the UI
+// which entries are historical vs. live. The default ordering puts the
+// newest first so a security review starts at the recent activity.
+export const listQuery = defineQueryHandler({
+  name: "user-session:list",
+  schema: z.object({}),
+  access: { roles: access.admin },
+  handler: async (_query, ctx) => {
+    const rows = await ctx.db
+      .select({
+        id: userSessionTable["id"],
+        userId: userSessionTable["userId"],
+        createdAt: userSessionTable["createdAt"],
+        expiresAt: userSessionTable["expiresAt"],
+        revokedAt: userSessionTable["revokedAt"],
+        ip: userSessionTable["ip"],
+        userAgent: userSessionTable["userAgent"],
+      })
+      .from(userSessionTable)
+      .orderBy(desc(userSessionTable["createdAt"]));
+    return rows;
+  },
+});

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

@@ -0,0 +1,37 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { and, desc, eq, isNull } from "drizzle-orm";
+import { z } from "zod";
+import { userSessionTable } from "../schema/user-session";
+
+// "My live sessions" — the backing data for a devices/sessions UI. Returns
+// ONLY the current user's own, currently-live sessions, ordered by most-
+// recently-used first. Revoked rows are excluded (they survive in DB for
+// audit but the UI shouldn't show them as active).
+//
+// Note the `current` marker: we compare against the caller's `user.sid` so
+// the UI can label the entry the user is looking at ("this device"). A user
+// without a sid (stateless-JWT deployment) will simply see `current: false`
+// on every row — the feature still works, just without the marker.
+export const mineQuery = defineQueryHandler({
+  name: "user-session:mine",
+  schema: z.object({}),
+  access: { openToAll: true },
+  handler: async (query, ctx) => {
+    const rows = await ctx.db
+      .select({
+        id: userSessionTable["id"],
+        createdAt: userSessionTable["createdAt"],
+        expiresAt: userSessionTable["expiresAt"],
+        ip: userSessionTable["ip"],
+        userAgent: userSessionTable["userAgent"],
+      })
+      .from(userSessionTable)
+      .where(
+        and(eq(userSessionTable["userId"], query.user.id), isNull(userSessionTable["revokedAt"])),
+      )
+      .orderBy(desc(userSessionTable["createdAt"]));
+
+    const currentSid = query.user.sid;
+    return rows.map((r) => ({ ...r, current: currentSid === r["id"] }));
+  },
+});

package/src/sessions/handlers/revoke-all-others.write.ts

@@ -0,0 +1,42 @@
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { and, eq, isNull, ne } from "drizzle-orm";
+import { Temporal } from "temporal-polyfill";
+import { z } from "zod";
+import { SessionErrors } from "../constants";
+import { userSessionTable } from "../schema/user-session";
+
+// "Sign out everywhere else" — keep the caller's current session, kill all
+// other live sessions for this user. Requires `user.sid` so "keep current"
+// is well-defined; without it we refuse loudly rather than silently nuking
+// the caller's own session along with the others.
+export const revokeAllOthersWrite = defineWriteHandler({
+  name: "user-session:revoke-all-others",
+  schema: z.object({}),
+  access: { openToAll: true },
+  handler: async (event, ctx) => {
+    const keepSid = event.user.sid;
+    if (!keepSid) {
+      return writeFailure(
+        new UnprocessableError(SessionErrors.sessionRequired, {
+          i18nKey: "sessions.errors.sessionRequired",
+          details: { userId: event.user.id },
+        }),
+      );
+    }
+
+    const updated = await ctx.db
+      .update(userSessionTable)
+      .set({ revokedAt: Temporal.Now.instant() })
+      .where(
+        and(
+          eq(userSessionTable["userId"], event.user.id),
+          isNull(userSessionTable["revokedAt"]),
+          ne(userSessionTable["id"], keepSid),
+        ),
+      )
+      .returning();
+
+    return { isSuccess: true, data: { count: updated.length } };
+  },
+});

package/src/sessions/handlers/revoke.write.ts

@@ -0,0 +1,76 @@
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { and, eq, isNull } from "drizzle-orm";
+import { Temporal } from "temporal-polyfill";
+import { z } from "zod";
+import { SessionErrors } from "../constants";
+import { userSessionTable } from "../schema/user-session";
+
+// Revoke a single session by id (= JWT jti). Three distinguishable outcomes:
+//
+//   - Success: row existed, belonged to the caller, was live → revokedAt
+//     stamped to now().
+//   - already_revoked: row existed, belonged to the caller, was ALREADY
+//     revoked → distinct error so UIs can show "logged out at <time>"
+//     instead of a generic access-denied. Audit's original revokedAt is
+//     preserved (isNull-guard on the UPDATE).
+//   - ownership_denied: row didn't exist OR belonged to another user. Same
+//     response for both branches = no existence oracle for other users' sids.
+//
+// Try the UPDATE first with the full constraint set (id + userId + live);
+// if it touches zero rows, a second SELECT disambiguates the reason. The
+// second roundtrip only happens on the error path — success stays single-
+// roundtrip.
+export const revokeWrite = defineWriteHandler({
+  name: "user-session:revoke",
+  schema: z.object({
+    id: z.uuid(),
+  }),
+  access: { openToAll: true },
+  handler: async (event, ctx) => {
+    const updated = await ctx.db
+      .update(userSessionTable)
+      .set({ revokedAt: Temporal.Now.instant() })
+      .where(
+        and(
+          eq(userSessionTable["id"], event.payload.id),
+          eq(userSessionTable["userId"], event.user.id),
+          isNull(userSessionTable["revokedAt"]),
+        ),
+      )
+      .returning();
+
+    if (updated.length > 0) {
+      return { isSuccess: true, data: { id: event.payload.id } };
+    }
+
+    // Zero rows touched — disambiguate between "not yours" and "already
+    // revoked" via a point-read. Only hits on the error path.
+    const [row] = await ctx.db
+      .select({ userId: userSessionTable["userId"], revokedAt: userSessionTable["revokedAt"] })
+      .from(userSessionTable)
+      .where(eq(userSessionTable["id"], event.payload.id))
+      .limit(1);
+
+    if (row && row["userId"] === event.user.id && row["revokedAt"] !== null) {
+      return writeFailure(
+        new UnprocessableError(SessionErrors.alreadyRevoked, {
+          i18nKey: "sessions.errors.alreadyRevoked",
+          details: { id: event.payload.id },
+        }),
+      );
+    }
+
+    return writeFailure(
+      new UnprocessableError(SessionErrors.ownershipDenied, {
+        i18nKey: "errors.ownershipDenied",
+        details: {
+          scope: "entity",
+          entityName: "user-session",
+          action: "revoke",
+          userId: event.user.id,
+        },
+      }),
+    );
+  },
+});

package/src/sessions/index.ts

@@ -0,0 +1,17 @@
+export {
+  DEFAULT_SESSION_CACHE_TTL_MS,
+  DEFAULT_SESSION_EXPIRY_MS,
+  SESSIONS_FEATURE,
+  SessionErrors,
+  SessionHandlers,
+  SessionQueries,
+} from "./constants";
+export type { SessionsFeatureOptions } from "./feature";
+export { createSessionsFeature } from "./feature";
+export { userSessionEntity, userSessionTable } from "./schema/user-session";
+export type {
+  SessionCallbacks,
+  SessionCallbacksOptions,
+  SessionMassRevoker,
+} from "./session-callbacks";
+export { createSessionCallbacks } from "./session-callbacks";

package/src/sessions/schema/index.ts

@@ -0,0 +1,5 @@
+// Re-exports aus den schema/<entity>.ts Files. Eine Datei pro Entity
+// — wenn das Feature später weitere Entities hinzubekommt, kommen sie
+// als zusätzliche Datei rein und werden hier exportiert.
+
+export * from "./user-session";

package/src/sessions/schema/user-session.ts

@@ -0,0 +1,67 @@
+import { buildDrizzleTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  createEntity,
+  createTextField,
+  createTimestampField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// userSession — one row per signed-in client (browser tab, mobile app).
+// The PRIMARY key is the sid — generated by the framework at login time and
+// embedded in the JWT's `jti` claim. Using sid-as-PK means the auth middleware
+// can look a session up with a single point-read instead of a (userId, sid)
+// lookup, which matters because the check runs on every authenticated request.
+//
+// Fields that are system-managed (userId, revokedAt, expiresAt, etc.) are
+// write-locked to the privileged role so the feature's handlers can still
+// mutate them via ctx.db inside a transaction, but no user request can bypass
+// the revocation flow by poking the column directly.
+export const userSessionEntity = createEntity({
+  // Entity-Key ist "user-session" (mit Dash), toTableName's snake-case-
+  // Transform käme auf "read_user-sessions" → kein valides SQL ohne Quoting.
+  // Deshalb expliziter Override auf den read_-konformen Namen.
+  table: "read_user_sessions",
+  // sid-as-PK: the sessionCreator callback generates the UUID, returns it to
+  // the framework; the framework stamps it as `jti`; here the same value is
+  // the row primary key. Single source of truth for the identifier.
+  // No softDelete: revocation is its own lifecycle (revokedAt timestamp), not
+  // a delete — we want to keep the audit trail of revoked sessions for the
+  // "your devices" UI ("signed out 3 days ago").
+  softDelete: false,
+  fields: {
+    userId: createTextField({
+      required: true,
+      maxLength: 36,
+      access: { write: access.privileged },
+    }),
+    tenantId: createTextField({
+      required: true,
+      maxLength: 36,
+      access: { write: access.privileged },
+    }),
+    createdAt: createTimestampField({
+      required: true,
+      access: { write: access.privileged },
+    }),
+    expiresAt: createTimestampField({
+      required: true,
+      access: { write: access.privileged },
+    }),
+    // Set when the session is revoked (logout, switch-tenant, password-change,
+    // admin action). Middleware treats `revokedAt != null` as "blocked" and
+    // returns 401; the row sticks around for the audit trail.
+    revokedAt: createTimestampField({
+      access: { write: access.privileged },
+    }),
+    ip: createTextField({
+      maxLength: 64,
+      access: { write: access.privileged },
+    }),
+    userAgent: createTextField({
+      maxLength: 512,
+      access: { write: access.privileged },
+    }),
+  },
+});
+
+export const userSessionTable = buildDrizzleTable("user_session", userSessionEntity);

package/src/sessions/session-callbacks.ts

@@ -0,0 +1,110 @@
+import type {
+  AuthSessionStatus,
+  SessionChecker,
+  SessionCreator,
+  SessionMetadata,
+  SessionRevoker,
+} from "@cosmicdrift/kumiko-framework/api";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import { and, eq, isNull } from "drizzle-orm";
+import { Temporal } from "temporal-polyfill";
+import { DEFAULT_SESSION_EXPIRY_MS } from "./constants";
+import { userSessionTable } from "./schema/user-session";
+
+// Why the callbacks live at the raw-DB level rather than going through the
+// dispatcher: session-create/revoke/check run on the hot path of every
+// login and every request. The (createdAt/revokedAt/ip/userAgent) columns
+// already are the audit trail — a dispatcher roundtrip buys nothing.
+
+// Mass-revoke for a single user. Used by the password-change hook and
+// "sign out everywhere" flows. Returns the count of rows flipped so a
+// caller can log "revoked N other sessions".
+export type SessionMassRevoker = (userId: string) => Promise<number>;
+
+export type SessionCallbacksOptions = {
+  readonly db: DbConnection;
+  // Session lifetime. MVP uses a single flat window; per-app policies can
+  // come later (e.g. longer for "remember me", shorter for admin).
+  readonly expiresInMs?: number;
+};
+
+export type SessionCallbacks = {
+  sessionCreator: SessionCreator;
+  sessionRevoker: SessionRevoker;
+  sessionChecker: SessionChecker;
+  sessionMassRevoker: SessionMassRevoker;
+};
+
+export function createSessionCallbacks(opts: SessionCallbacksOptions): SessionCallbacks {
+  const ttlMs = opts.expiresInMs ?? DEFAULT_SESSION_EXPIRY_MS;
+  const { db } = opts;
+
+  return {
+    async sessionCreator(user: SessionUser, meta: SessionMetadata): Promise<string> {
+      const sid = generateId();
+      const now = Temporal.Now.instant();
+      const expiresAt = now.add({ milliseconds: ttlMs });
+      await db.insert(userSessionTable).values({
+        id: sid,
+        tenantId: user.tenantId,
+        userId: user.id,
+        createdAt: now,
+        expiresAt,
+        ip: meta.ip,
+        userAgent: meta.userAgent,
+      });
+      return sid;
+    },
+
+    async sessionRevoker(sid: string): Promise<void> {
+      // Audit-preserving: `isNull(revokedAt)` in WHERE means a second call
+      // on an already-revoked sid is a no-op instead of overwriting the
+      // original timestamp. Double-revoke races land here via logout +
+      // switch-tenant on the same sid. (Password-change uses a different
+      // callback — sessionMassRevoker — and isn't in scope for this guard.)
+      await db
+        .update(userSessionTable)
+        .set({ revokedAt: Temporal.Now.instant() })
+        .where(and(eq(userSessionTable.id, sid), isNull(userSessionTable.revokedAt)));
+    },
+
+    async sessionChecker(sid: string, expectedUserId: string): Promise<AuthSessionStatus> {
+      const rows = await db
+        .select({
+          userId: userSessionTable.userId,
+          revokedAt: userSessionTable.revokedAt,
+          expiresAt: userSessionTable.expiresAt,
+        })
+        .from(userSessionTable)
+        .where(eq(userSessionTable.id, sid))
+        .limit(1);
+      const row = rows[0];
+      if (!row) return "missing";
+      // Cross-user check: if the sid belongs to someone else, treat it
+      // identically to "missing" so a compromised sid paired with a valid
+      // JWT from a different user gets the same opaque response as a
+      // forged sid. No existence oracle on other users' sids.
+      if (row.userId !== expectedUserId) return "missing";
+      if (row.revokedAt !== null) return "revoked";
+      // Temporal-native clock read (Sprint F migration) — keeps the feature
+      // free of raw Date.now() for consistency with the rest of the codebase.
+      if (row.expiresAt.epochMilliseconds <= Temporal.Now.instant().epochMilliseconds) {
+        return "expired";
+      }
+      return "live";
+    },
+
+    async sessionMassRevoker(userId: string): Promise<number> {
+      // Count is accurate because we only touch live rows — a previously
+      // revoked row stays in its state and isn't double-counted.
+      const result = await db
+        .update(userSessionTable)
+        .set({ revokedAt: Temporal.Now.instant() })
+        .where(and(eq(userSessionTable.userId, userId), isNull(userSessionTable.revokedAt)))
+        .returning({ id: userSessionTable.id });
+      return result.length;
+    },
+  };
+}

package/src/sessions/testing.ts

@@ -0,0 +1,42 @@
+// Testing helpers for the sessions feature. The factory below turns a
+// `LateBoundHolder<SessionCallbacks>` into the two shapes a test needs:
+//
+//   const holder = createLateBoundHolder<SessionCallbacks>("session-callbacks");
+//   const bound = sessionCallbacksFromLateBound(holder);
+//
+//   stack = await setupTestStack({
+//     features: [..., createSessionsFeature({
+//       autoRevokeOnPasswordChange: bound.asMassRevoker(),
+//     })],
+//     authConfig: { ...bound.asAuthConfig(), membershipQuery, loginHandler },
+//   });
+//   holder.set(createSessionCallbacks({ db: stack.db }));
+//
+// Why the helper lives in bundled-features/sessions rather than framework/testing:
+// it closes over `AuthRoutesConfig` + `SessionCallbacks`, both of which the
+// sessions feature owns. framework/testing only provides the generic
+// `createLateBoundHolder<T>` — shape-independent.
+
+import type { AuthRoutesConfig } from "@cosmicdrift/kumiko-framework/api";
+import type { LateBoundHolder } from "@cosmicdrift/kumiko-framework/testing";
+import type { SessionCallbacks, SessionMassRevoker } from "./session-callbacks";
+
+export type BoundSessionCallbacks = {
+  /** auth-config fragment: creator + revoker + checker, all late-bound. */
+  asAuthConfig(): Pick<AuthRoutesConfig, "sessionCreator" | "sessionRevoker" | "sessionChecker">;
+  /** mass-revoker function for sessionsFeature({ autoRevokeOnPasswordChange }). */
+  asMassRevoker(): SessionMassRevoker;
+};
+
+export function sessionCallbacksFromLateBound(
+  holder: LateBoundHolder<SessionCallbacks>,
+): BoundSessionCallbacks {
+  return {
+    asAuthConfig: () => ({
+      sessionCreator: (user, meta) => holder.get().sessionCreator(user, meta),
+      sessionRevoker: (sid) => holder.get().sessionRevoker(sid),
+      sessionChecker: (sid, userId) => holder.get().sessionChecker(sid, userId),
+    }),
+    asMassRevoker: () => (userId) => holder.get().sessionMassRevoker(userId),
+  };
+}

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

@@ -0,0 +1,106 @@
+// feature.ts contract tests for subscription-mollie.
+
+import { describe, expect, test } from "vitest";
+import { MOLLIE_PROVIDER_NAME, SUBSCRIPTION_MOLLIE_FEATURE } from "../constants";
+import { createSubscriptionMollieFeature } from "../feature";
+
+const VALID_OPTIONS = {
+  apiKey: "test_dummy_apikey",
+  webhookUrl: "https://app.example.com/api/subscription/webhook/mollie",
+  priceToTier: { plan_pro: "pro" },
+  priceToConfig: {
+    plan_pro: {
+      amountValue: "9.99",
+      amountCurrency: "EUR",
+      interval: "1 month",
+      description: "Pro Plan",
+    },
+  },
+};
+
+describe("createSubscriptionMollieFeature — shape", () => {
+  test("has the expected name", () => {
+    const feature = createSubscriptionMollieFeature(VALID_OPTIONS);
+    expect(feature.name).toBe(SUBSCRIPTION_MOLLIE_FEATURE);
+    expect(feature.name).toBe("subscription-mollie");
+  });
+
+  test("requires only subscription-foundation (alles app-wide via factory-options)", () => {
+    const feature = createSubscriptionMollieFeature(VALID_OPTIONS);
+    expect(feature.requires).toContain("billing-foundation");
+    expect(feature.requires).not.toContain("config");
+    expect(feature.requires).not.toContain("secrets");
+  });
+});
+
+describe("createSubscriptionMollieFeature — module-load validation", () => {
+  test("throws bei empty apiKey", () => {
+    expect(() => createSubscriptionMollieFeature({ ...VALID_OPTIONS, apiKey: "" })).toThrow(
+      /apiKey is empty/,
+    );
+  });
+
+  test("throws bei empty webhookUrl", () => {
+    expect(() => createSubscriptionMollieFeature({ ...VALID_OPTIONS, webhookUrl: "" })).toThrow(
+      /webhookUrl is empty/,
+    );
+  });
+
+  test("throws bei priceToTier ↔ priceToConfig drift (priceId nur in tier)", () => {
+    expect(() =>
+      createSubscriptionMollieFeature({
+        ...VALID_OPTIONS,
+        priceToTier: { plan_pro: "pro", plan_business: "business" },
+        // plan_business fehlt in config
+      }),
+    ).toThrow(/missing config:.*plan_business/);
+  });
+
+  test("throws bei priceToTier ↔ priceToConfig drift (priceId nur in config)", () => {
+    expect(() =>
+      createSubscriptionMollieFeature({
+        ...VALID_OPTIONS,
+        priceToConfig: {
+          ...VALID_OPTIONS.priceToConfig,
+          plan_extra: {
+            amountValue: "29.99",
+            amountCurrency: "EUR",
+            interval: "1 month",
+            description: "Extra",
+          },
+        },
+        // plan_extra fehlt in tier
+      }),
+    ).toThrow(/missing tier:.*plan_extra/);
+  });
+});
+
+describe("subscription-mollie — plugin-registration", () => {
+  test("registers under entityName 'mollie' for subscription-foundation extension", () => {
+    const feature = createSubscriptionMollieFeature(VALID_OPTIONS);
+    expect(
+      feature.extensionUsages.some(
+        (u) => u.extensionName === "subscriptionProvider" && u.entityName === MOLLIE_PROVIDER_NAME,
+      ),
+    ).toBe(true);
+  });
+
+  test("plugin has verifyAndParseWebhook + createCheckoutSession; KEIN portal/cancel (Mollie-Limit)", () => {
+    // Drift-Pin: Mollie's Plugin-shape ist intentional schmaler als Stripe.
+    // Wenn jemand einen createPortalSession-stub hinzufügt der "not-supported"
+    // wirft, würde das die foundation-error-Story ändern. Phase-5.3-MVP
+    // lässt die optional-Fields KOMPLETT weg.
+    const feature = createSubscriptionMollieFeature(VALID_OPTIONS);
+    const usage = feature.extensionUsages.find((u) => u.entityName === MOLLIE_PROVIDER_NAME);
+    const plugin = usage?.options as {
+      verifyAndParseWebhook?: unknown;
+      createCheckoutSession?: unknown;
+      createPortalSession?: unknown;
+      cancelSubscription?: unknown;
+    };
+    expect(typeof plugin?.verifyAndParseWebhook).toBe("function");
+    expect(typeof plugin?.createCheckoutSession).toBe("function");
+    expect(plugin?.createPortalSession).toBeUndefined();
+    expect(plugin?.cancelSubscription).toBeUndefined();
+  });
+});