@cosmicdrift/kumiko-bundled-features 0.165.0 → 2.0.0

package/src/auth-mfa/handlers/reencrypt.job.ts

@@ -14,7 +14,7 @@
 // decryptForRead), so it must peel that PII layer itself before the envelope
 // cipher ever sees the value, mirroring decryptForRead's PII-then-envelope
 // order — an envelope decrypt on a still-PII-wrapped string throws
-// "legacy single-key format" instead of rotating anything.
+// "[envelope-cipher] stored value is not valid JSON" instead of rotating anything.
 //
 // Idempotent: re-running skips rows already on the current kekVersion.
 // Every write is a normal executor.update — after a full run even a
@@ -66,17 +66,20 @@ export type MfaReencryptJobResult = {
   readonly stoppedReason: ChunkedMigrationStopReason;
 };
 
-function needsReencrypt(value: string, targetVersion: number): boolean {
-  // legacy single-key format (base64 — can never start with "{")
-  if (!value.startsWith("{")) return true;
+type EnvelopeClassification = "rotate" | "current" | "unrecognized";
+
+// After PII peel (when configured), values must be current-cipher envelopes.
+// Non-JSON / non-envelope is not a supported legacy decrypt path — fail the
+// row instead of treating it as "needs rotate" (#1541, mirrors config #1513).
+function classifyEnvelope(value: string, targetVersion: number): EnvelopeClassification {
+  let parsed: unknown;
   try {
-    const parsed: unknown = JSON.parse(value);
-    if (!isStoredEnvelope(parsed)) return true;
-    return parsed.kekVersion !== targetVersion;
+    parsed = JSON.parse(value);
   } catch {
-    // malformed JSON — let the decrypt attempt surface the real error
-    return true;
+    return "unrecognized";
   }
+  if (!isStoredEnvelope(parsed)) return "unrecognized";
+  return parsed.kekVersion === targetVersion ? "current" : "rotate";
 }
 
 export const mfaReencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
@@ -152,7 +155,7 @@ export const mfaReencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<vo
   async function migrateRow(row: UserMfaRow): Promise<"migrated" | "skipped" | "failed"> {
     const tenantId = row.tenantId as TenantId; // @cast-boundary db-row
 
-    // Peel the PII layer first (if active) so needsReencrypt/cipher.decrypt
+    // Peel the PII layer first (if active) so classifyEnvelope/cipher.decrypt
     // below only ever see envelope strings, same order as decryptForRead.
     let envelopeValues: { totpSecret: string; recoveryCodes: string } = row;
     if (piiKms) {
@@ -163,20 +166,26 @@ export const mfaReencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<vo
       envelopeValues = unwrapped as { totpSecret: string; recoveryCodes: string }; // @cast-boundary engine-payload
     }
 
-    const totpNeedsRotation = needsReencrypt(envelopeValues.totpSecret, targetVersion);
-    const recoveryNeedsRotation = needsReencrypt(envelopeValues.recoveryCodes, targetVersion);
-    if (!totpNeedsRotation && !recoveryNeedsRotation) {
+    const totpClass = classifyEnvelope(envelopeValues.totpSecret, targetVersion);
+    const recoveryClass = classifyEnvelope(envelopeValues.recoveryCodes, targetVersion);
+    if (totpClass === "unrecognized" || recoveryClass === "unrecognized") {
+      ctx.log?.warn?.(
+        `[auth-mfa:reencrypt] row ${row.id} has a field that is not a current-cipher envelope, not re-encryptable`,
+      );
+      return "failed";
+    }
+    if (totpClass === "current" && recoveryClass === "current") {
       alreadyCurrent++;
       return "skipped";
     }
 
-    // decrypt failure (missing legacy key, unknown kekVersion, tamper)
-    // throws → counted as failed via onRowError; the row stays untouched.
+    // decrypt failure (unknown kekVersion, tamper) throws → counted as
+    // failed via onRowError; the row stays untouched.
     const changes: Record<string, string> = {};
-    if (totpNeedsRotation) {
+    if (totpClass === "rotate") {
       changes["totpSecret"] = await cipher.decrypt(envelopeValues.totpSecret, { tenantId });
     }
-    if (recoveryNeedsRotation) {
+    if (recoveryClass === "rotate") {
       changes["recoveryCodes"] = await cipher.decrypt(envelopeValues.recoveryCodes, { tenantId });
     }
 

package/src/auth-mfa/handlers/regenerate-recovery.write.ts

@@ -1,5 +1,6 @@
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { findUserMfaRow } from "../db/queries";
 import { invalidTotpCode, mfaNotEnabled } from "../errors";
@@ -34,7 +35,20 @@ export function createRegenerateRecoveryHandler(opts: RegenerateRecoveryOptions)
       // (deliberately) one of the very codes about to be replaced both
       // count, since either way the presented code is consumed/irrelevant
       // afterward.
-      const replay = ctx.redis ? { redis: ctx.redis, userId: event.user.id } : undefined;
+      //
+      // Fail closed, matching verify.write.ts/enable-confirm-preauth.write.ts
+      // (#1467): without ctx.redis, verifyMfaFactor's TOTP-replay burn is
+      // skipped, letting an observed code be replayed within the ±1-step
+      // window to regenerate (and thus invalidate) recovery codes — a
+      // session-authed route, so pre-unwiring JWTs stay a valid attack path.
+      if (!ctx.redis) {
+        return writeFailure(
+          new InternalError({
+            message: "regenerate-recovery (mfa) requires ctx.redis for TOTP replay protection",
+          }),
+        );
+      }
+      const replay = { redis: ctx.redis, userId: event.user.id };
       const verify = await verifyMfaFactor(row, event.payload.code, replay);
       if (!verify.ok) return invalidTotpCode();
 

package/src/auth-mfa/handlers/verify.write.ts

@@ -5,6 +5,7 @@ import {
   defineWriteHandler,
   type SessionUser,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import { z } from "zod";
 import { burnToken } from "../../shared";
@@ -53,17 +54,31 @@ export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
       if (!verified.ok) return invalidChallengeToken();
       const { userId, tenantId } = verified.payload;
 
+      // Fail closed, matching enable-confirm-preauth.write.ts (#1467):
+      // this route sits behind a challenge token from a successful login,
+      // but its own secret is still just a short TOTP/recovery code —
+      // silently skipping the brute-force cap and single-use burn when
+      // ctx.redis is absent would let a stolen challenge token be guessed
+      // against unboundedly, and let a recovery code be replayed via a
+      // reissued challenge (mfa-verify-attempts.ts's counter is deliberately
+      // NOT reset by reissuance, precisely to survive this).
+      if (!ctx.redis) {
+        return writeFailure(
+          new InternalError({
+            message: "verify (mfa) requires ctx.redis for the brute-force cap and single-use burn",
+          }),
+        );
+      }
+
       // Per-account brute-force cap — survives challenge-token reissuance
       // on purpose (see mfa-verify-attempts.ts header). Checked BEFORE the
       // TOTP/recovery verify so a locked account can't be guessed against.
-      if (ctx.redis) {
-        const state = await getMfaVerifyLockoutState(ctx.redis, userId);
-        if (state?.lockedUntil !== null && state?.lockedUntil !== undefined) {
-          const now = Date.now();
-          if (state.lockedUntil > now) {
-            const retryAfterSeconds = Math.max(1, Math.ceil((state.lockedUntil - now) / 1000));
-            return tooManyAttempts(retryAfterSeconds);
-          }
+      const state = await getMfaVerifyLockoutState(ctx.redis, userId);
+      if (state?.lockedUntil !== null && state?.lockedUntil !== undefined) {
+        const now = Date.now();
+        if (state.lockedUntil > now) {
+          const retryAfterSeconds = Math.max(1, Math.ceil((state.lockedUntil - now) / 1000));
+          return tooManyAttempts(retryAfterSeconds);
         }
       }
 
@@ -78,12 +93,10 @@ export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
       // bad code, no detail leak about account state.
       if (!row) return invalidChallengeToken();
 
-      const replay = ctx.redis ? { redis: ctx.redis, userId } : undefined;
+      const replay = { redis: ctx.redis, userId };
       const verify = await verifyMfaFactor(row, event.payload.code, replay);
       if (!verify.ok) {
-        if (ctx.redis) {
-          await recordFailedMfaVerifyAttempt(ctx.redis, userId, maxAttempts, lockoutMinutes);
-        }
+        await recordFailedMfaVerifyAttempt(ctx.redis, userId, maxAttempts, lockoutMinutes);
         return invalidTotpCode();
       }
 
@@ -95,15 +108,8 @@ export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
       // is reached, so this burn only needs to guard a DIFFERENT code
       // (recovery, or a still-valid-but-not-yet-burned TOTP step) reused
       // against the same challenge token.
-      if (ctx.redis) {
-        const burnResult = await burnToken(
-          ctx.redis,
-          "mfa-challenge",
-          userId,
-          verified.expiresAtMs,
-        );
-        if (burnResult === "already-used") return invalidChallengeToken();
-      }
+      const burnResult = await burnToken(ctx.redis, "mfa-challenge", userId, verified.expiresAtMs);
+      if (burnResult === "already-used") return invalidChallengeToken();
 
       // Recovery-code use consumes the code — persist the reduced hash-list
       // immediately so it can't be replayed. Without this a recovery code
@@ -121,9 +127,7 @@ export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
         if (!updateResult.isSuccess) return updateResult;
       }
 
-      if (ctx.redis) {
-        await clearMfaVerifyAttempts(ctx.redis, userId);
-      }
+      await clearMfaVerifyAttempts(ctx.redis, userId);
 
       // Re-derive the full session the way login.write.ts would have, for
       // the SAME tenant the challenge token already committed to (no

package/src/auth-mfa/web/__tests__/mfa-client.test.ts

@@ -1,12 +1,16 @@
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 import { confirmMfaSetupPreauth, startMfaSetupPreauth, verifyMfaChallenge } from "../mfa-client";
 
+const originalFetch = globalThis.fetch;
+
 beforeEach(() => {
   globalThis.fetch = mock(
     async () => new Response(null, { status: 200 }),
   ) as unknown as typeof fetch;
 });
-afterEach(() => {});
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
 
 function jsonResponse(body: unknown, status = 200): Response {
   return new Response(JSON.stringify(body), { status });

package/src/auth-mfa/web/__tests__/mfa-enable-screen.test.tsx

@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, mock, test } from "bun:test";
+import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
 import {
   createStaticLocaleResolver,
   LocaleProvider,
@@ -34,6 +34,15 @@ mock.module("qrcode/lib/browser", () => ({
   default: { toString: mock(async () => "<svg></svg>") },
 }));
 
+// bun's mock.module is process-global and outlives this file — without
+// restoring it, any later suite in the same test run that needs the real
+// useDispatcher from @cosmicdrift/kumiko-renderer silently gets this mock
+// instead (green-by-accident or a confusing foreign-suite failure,
+// depending on test order).
+afterAll(() => {
+  mock.module("@cosmicdrift/kumiko-renderer", () => actual_renderer);
+});
+
 const { MfaEnableScreen } = await import("../mfa-enable-screen");
 
 const session = makeSessionApi();

package/src/auth-mfa/web/__tests__/mfa-setup-preauth-screen.test.tsx

@@ -242,7 +242,11 @@ describe("MfaSetupPreauthScreen", () => {
     expect(confirm.disabled).toBe(false);
   });
 
-  test("confirm schlägt mit invalid_setup_token fehl → übersetztes Banner (Neustart-Pfad)", async () => {
+  // #1470: the banner told the user to "start over", but setup stayed
+  // non-null — the intro block (with the only "start setup" button) never
+  // came back, leaving the user stuck without a reload (which loses the
+  // preauthSetupToken entirely).
+  test("confirm schlägt mit invalid_setup_token fehl → Neustart-Pfad: Start-Button kommt zurück (#1470)", async () => {
     globalThis.fetch = mock(async (input: RequestInfo | URL) => {
       const url = String(input);
       if (url.includes("preauth-enable-start")) return jsonResponse(startBody);
@@ -272,5 +276,104 @@ describe("MfaSetupPreauthScreen", () => {
         screen.getByText("Die Einrichtung ist abgelaufen. Bitte erneut starten."),
       ).toBeTruthy();
     });
+    // The actual fix: intro re-appears with a working start button, the QR/
+    // recovery-codes section from the dead setup is gone.
+    expect(screen.getByRole("button", { name: "Einrichtung starten" })).toBeTruthy();
+    expect(screen.queryByText("ABCD1234")).toBeNull();
+  });
+
+  test("confirm schlägt mit invalid_challenge_token fehl → auch Neustart-Pfad (#1470)", async () => {
+    globalThis.fetch = mock(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.includes("preauth-enable-start")) return jsonResponse(startBody);
+      if (url.includes("preauth-confirm")) {
+        return jsonResponse({ isSuccess: false, error: "invalid_challenge_token" });
+      }
+      return jsonResponse({ isSuccess: false, error: "unexpected_url" }, 500);
+    }) as unknown as typeof fetch;
+
+    render(
+      <Wrapper>
+        <MfaSetupPreauthScreen preauthSetupToken="preauth-1" accountLabel="user@example.com" />
+      </Wrapper>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Einrichtung starten" }));
+    await waitFor(() => {
+      expect(screen.getByText("ABCD1234")).toBeTruthy();
+    });
+    fireEvent.click(screen.getByLabelText("Ich habe die Recovery-Codes gespeichert."));
+    fireEvent.change(screen.getByLabelText(/^Code aus der Authenticator-App/), {
+      target: { value: "123456" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Einrichtung abschließen" }));
+
+    await waitFor(() => {
+      expect(screen.getByRole("button", { name: "Einrichtung starten" })).toBeTruthy();
+    });
+  });
+
+  // kumiko-framework#1470: confirmMfaSetupPreauth already extracts
+  // retryAfterSeconds from error.details (see mfa-client.test.ts), but the
+  // screen used to drop it and show a generic "too many attempts" banner
+  // with no wait-time. Pins that the seconds actually reach the UI.
+  test("confirm schlägt mit too_many_attempts fehl → Banner zeigt retryAfterSeconds (#1470)", async () => {
+    globalThis.fetch = mock(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.includes("preauth-enable-start")) return jsonResponse(startBody);
+      if (url.includes("preauth-confirm")) {
+        return jsonResponse({
+          isSuccess: false,
+          error: { code: "too_many_attempts", details: { retryAfterSeconds: 42 } },
+        });
+      }
+      return jsonResponse({ isSuccess: false, error: "unexpected_url" }, 500);
+    }) as unknown as typeof fetch;
+
+    render(
+      <Wrapper>
+        <MfaSetupPreauthScreen preauthSetupToken="preauth-1" accountLabel="user@example.com" />
+      </Wrapper>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Einrichtung starten" }));
+    await waitFor(() => {
+      expect(screen.getByText("ABCD1234")).toBeTruthy();
+    });
+    fireEvent.click(screen.getByLabelText("Ich habe die Recovery-Codes gespeichert."));
+    fireEvent.change(screen.getByLabelText(/^Code aus der Authenticator-App/), {
+      target: { value: "123456" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Einrichtung abschließen" }));
+
+    await waitFor(() => {
+      expect(
+        screen.getByText(
+          "Zu viele Fehlversuche. Bitte in 42 Sekunden erneut versuchen oder neu einloggen.",
+        ),
+      ).toBeTruthy();
+    });
+  });
+
+  // kumiko-framework#1470: server validates z.string().length(6) — a 7th
+  // pasted digit must not make the button look submittable, it would only
+  // 400 as invalid_body.
+  test("7-stelliger Code hält den Bestätigen-Button disabled", async () => {
+    render(
+      <Wrapper>
+        <MfaSetupPreauthScreen preauthSetupToken="preauth-1" accountLabel="user@example.com" />
+      </Wrapper>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Einrichtung starten" }));
+    await waitFor(() => {
+      expect(screen.getByText("ABCD1234")).toBeTruthy();
+    });
+    fireEvent.click(screen.getByLabelText("Ich habe die Recovery-Codes gespeichert."));
+    fireEvent.change(screen.getByLabelText(/^Code aus der Authenticator-App/), {
+      target: { value: "1234567" },
+    });
+
+    const confirm = screen.getByRole("button", {
+      name: "Einrichtung abschließen",
+    }) as HTMLButtonElement;
+    expect(confirm.disabled).toBe(true);
   });
 });

package/src/auth-mfa/web/__tests__/mfa-verify-screen.test.tsx

@@ -25,12 +25,16 @@ function renderScreen(ui: ReactElement, session = makeSessionApi()): RenderResul
   );
 }
 
+const originalFetch = globalThis.fetch;
+
 beforeEach(() => {
   globalThis.fetch = mock(
     async () => new Response(null, { status: 200 }),
   ) as unknown as typeof fetch;
 });
-afterEach(() => {});
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
 
 describe("MfaVerifyScreen", () => {
   test("rendert Titel + Code-Feld + Submit-Button (de)", () => {

package/src/auth-mfa/web/i18n.ts

@@ -20,6 +20,8 @@ export const defaultTranslations: TranslationsByLocale = {
       "Die Anmeldung ist abgelaufen. Bitte erneut einloggen.",
     "auth.mfa.errors.challengeExpired": "Die Anmeldung ist abgelaufen. Bitte erneut einloggen.",
     "auth.mfa.errors.tooManyAttempts": "Zu viele Fehlversuche. Bitte erneut einloggen.",
+    "auth.mfa.errors.tooManyAttemptsWithSeconds":
+      "Zu viele Fehlversuche. Bitte in {seconds} Sekunden erneut versuchen oder neu einloggen.",
     "auth.mfa.errors.verifyFailed": "Bestätigung fehlgeschlagen.",
     "auth.mfa.errors.mfaAlreadyEnabled": "Zwei-Faktor-Authentifizierung ist bereits aktiv.",
     "auth.mfa.errors.mfaNotEnabled": "Zwei-Faktor-Authentifizierung ist nicht aktiv.",
@@ -80,6 +82,8 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.mfa.errors.invalidChallengeToken": "Your sign-in has expired. Please sign in again.",
     "auth.mfa.errors.challengeExpired": "Your sign-in has expired. Please sign in again.",
     "auth.mfa.errors.tooManyAttempts": "Too many failed attempts. Please sign in again.",
+    "auth.mfa.errors.tooManyAttemptsWithSeconds":
+      "Too many failed attempts. Try again in {seconds} seconds, or sign in again.",
     "auth.mfa.errors.verifyFailed": "Verification failed.",
     "auth.mfa.errors.mfaAlreadyEnabled": "Two-factor authentication is already enabled.",
     "auth.mfa.errors.mfaNotEnabled": "Two-factor authentication is not enabled.",

package/src/auth-mfa/web/mfa-client.ts

@@ -93,7 +93,13 @@ export async function startMfaSetupPreauth(
     setupToken?: string;
     otpauthUri?: string;
     recoveryCodes?: readonly string[];
-    error?: { code?: string; message?: string; details?: { reason?: string } } | string;
+    error?:
+      | {
+          code?: string;
+          message?: string;
+          details?: { reason?: string; retryAfterSeconds?: number };
+        }
+      | string;
   };
   if (
     body.isSuccess === true &&
@@ -115,9 +121,14 @@ export async function startMfaSetupPreauth(
     return { kind: "failure", error: { reason: err } };
   }
   const reason = err?.details?.reason ?? err?.code ?? "setup_failed";
+  const retry = err?.details?.retryAfterSeconds;
   return {
     kind: "failure",
-    error: { reason, ...(err?.message !== undefined && { message: err.message }) },
+    error: {
+      reason,
+      ...(err?.message !== undefined && { message: err.message }),
+      ...(retry !== undefined && { retryAfterSeconds: retry }),
+    },
   };
 }
 

package/src/auth-mfa/web/mfa-enable-screen.tsx

@@ -161,7 +161,7 @@ export function MfaEnableScreen({
                 variant="primary"
                 onClick={() => void confirmSetup()}
                 loading={busy}
-                disabled={busy || !acknowledged || code.length < 6}
+                disabled={busy || !acknowledged || code.length !== 6}
               >
                 {t("auth.mfa.enable.confirm")}
               </Button>

package/src/auth-mfa/web/mfa-setup-preauth-screen.tsx

@@ -85,14 +85,17 @@ export function MfaSetupPreauthScreen({
   const [code, setCode] = useState("");
   const [busy, setBusy] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const [retryAfterSeconds, setRetryAfterSeconds] = useState<number | null>(null);
 
   const startSetup = async (): Promise<void> => {
     setBusy(true);
     setError(null);
+    setRetryAfterSeconds(null);
     try {
       const res = await startMfaSetupPreauth(preauthSetupToken, accountLabel);
       if (res.kind !== "success") {
         setError(res.error.reason);
+        setRetryAfterSeconds(res.error.retryAfterSeconds ?? null);
         return;
       }
       // errorCorrectionLevel "H" (~30% redundancy) — more resilient to
@@ -121,10 +124,24 @@ export function MfaSetupPreauthScreen({
     if (!setup) return;
     setBusy(true);
     setError(null);
+    setRetryAfterSeconds(null);
     try {
       const res = await confirmMfaSetupPreauth(setup.setupToken, code);
       if (res.kind !== "success") {
         setError(res.error.reason);
+        setRetryAfterSeconds(res.error.retryAfterSeconds ?? null);
+        // An expired or already-burned setupToken can never succeed again —
+        // drop back to the intro so the "start setup" button reappears,
+        // otherwise the user is stuck on this screen with no way forward
+        // short of a full reload (which loses the preauthSetupToken).
+        if (
+          res.error.reason === "invalid_setup_token" ||
+          res.error.reason === "invalid_challenge_token"
+        ) {
+          setSetup(null);
+          setAcknowledged(false);
+          setCode("");
+        }
         return;
       }
       onSuccess?.();
@@ -146,7 +163,13 @@ export function MfaSetupPreauthScreen({
       subtitle={subtitle ?? t("auth.mfa.setup.subtitle")}
     >
       <div className="p-6 pt-0 flex flex-col gap-4">
-        {error !== null ? <Banner variant="error">{t(reasonToKey(error))}</Banner> : null}
+        {error !== null ? (
+          <Banner variant="error">
+            {error === "too_many_attempts" && retryAfterSeconds !== null
+              ? t("auth.mfa.errors.tooManyAttemptsWithSeconds", { seconds: retryAfterSeconds })
+              : t(reasonToKey(error))}
+          </Banner>
+        ) : null}
 
         {!setup && (
           <Section
@@ -175,7 +198,7 @@ export function MfaSetupPreauthScreen({
                   type="submit"
                   variant="primary"
                   loading={busy}
-                  disabled={busy || !acknowledged || code.length < 6}
+                  disabled={busy || !acknowledged || code.length !== 6}
                 >
                   {t("auth.mfa.setup.confirm")}
                 </Button>

package/src/billing-foundation/__tests__/subscription-provider-contract.ts

@@ -25,9 +25,19 @@ export type SubscriptionProviderContractFixture = {
   };
 };
 
+export type SubscriptionProviderContractOptions = {
+  // Providers without portal/cancel support (e.g. Mollie) must say so
+  // explicitly — a bare `if (!plugin.x) return` inside the test body makes
+  // the skip invisible in test output (a coverage illusion: Stripe's
+  // portal/cancel tests and Mollie's "skip" both show as green) (#1339).
+  readonly hasPortal: boolean;
+  readonly hasCancel: boolean;
+};
+
 export function describeSubscriptionProviderContract(
   name: string,
   factory: () => SubscriptionProviderContractFixture | Promise<SubscriptionProviderContractFixture>,
+  options: SubscriptionProviderContractOptions,
 ): void {
   describe(`${name} — SubscriptionProviderPlugin contract`, () => {
     test("implements verifyAndParseWebhook", async () => {
@@ -52,18 +62,32 @@ export function describeSubscriptionProviderContract(
       expect(result.url.length).toBeGreaterThan(0);
     });
 
-    test("createPortalSession returns a hosted-page url — providers without a portal skip", async () => {
-      const { plugin, ctx, portal } = await factory();
-      if (!plugin.createPortalSession || !portal) return;
-      const result = await plugin.createPortalSession(ctx, portal);
-      expect(typeof result.url).toBe("string");
-      expect(result.url.length).toBeGreaterThan(0);
-    });
+    (options.hasPortal ? test : test.skip)(
+      "createPortalSession returns a hosted-page url",
+      async () => {
+        const { plugin, ctx, portal } = await factory();
+        if (!plugin.createPortalSession || !portal) {
+          throw new Error(
+            "describeSubscriptionProviderContract: hasPortal:true but the fixture has no createPortalSession/portal",
+          );
+        }
+        const result = await plugin.createPortalSession(ctx, portal);
+        expect(typeof result.url).toBe("string");
+        expect(result.url.length).toBeGreaterThan(0);
+      },
+    );
 
-    test("cancelSubscription resolves without throwing — providers without cancel-support skip", async () => {
-      const { plugin, ctx, cancelSubscriptionId } = await factory();
-      if (!plugin.cancelSubscription || !cancelSubscriptionId) return;
-      await expect(plugin.cancelSubscription(ctx, cancelSubscriptionId)).resolves.toBeUndefined();
-    });
+    (options.hasCancel ? test : test.skip)(
+      "cancelSubscription resolves without throwing",
+      async () => {
+        const { plugin, ctx, cancelSubscriptionId } = await factory();
+        if (!plugin.cancelSubscription || !cancelSubscriptionId) {
+          throw new Error(
+            "describeSubscriptionProviderContract: hasCancel:true but the fixture has no cancelSubscription/cancelSubscriptionId",
+          );
+        }
+        await expect(plugin.cancelSubscription(ctx, cancelSubscriptionId)).resolves.toBeUndefined();
+      },
+    );
   });
 }

package/src/config/__tests__/backing-secrets.integration.test.ts

@@ -207,6 +207,10 @@ describe("config backing=secrets — fail-loud when secrets unwired", () => {
   test("cascade read on backing=secrets without secretsReader throws", async () => {
     // Write succeeds on the wired stack; then resolve via a bare resolver
     // (no secretsReader) so readBackingSecret fails loud on the cascade path.
+    // Direct resolver call is deliberate here, not a bypass: stack.http always
+    // uses a properly-wired resolver (secretsReader present) — there's no
+    // HTTP path that reaches an unwired resolver, so this is the only way to
+    // exercise the missing-secretsReader failure mode (kumiko-framework#1437).
     await stack.http.writeOk(
       ConfigHandlers.set,
       { key: API_KEY, value: "sk-live-planted", scope: "system" },

package/src/config/__tests__/cascade.integration.test.ts

@@ -528,8 +528,19 @@ describe("config:query:cascade handler", () => {
   });
 });
 
-// getAll is a bulk reader — never reached via the cascade query handlers
-// above, so it stays uncovered unless called directly on the resolver.
+// getAll is public ConfigResolver surface (packages/types/src/config.ts)
+// for app authors that need every config key for a scope at once (bulk
+// export/backup tooling, admin dashboards) — NOT wired to any handler in
+// this repo. `resolver.getAll(...)` is the ONLY call site in the whole
+// codebase (verified via grep, kumiko-framework#1529); there is no handler
+// to route this through, so calling it directly isn't the
+// handfed-context/createTestDispatcher anti-pattern the "echte HTTP-Calls"
+// rule targets — that rule is about bypassing a REAL handler's dispatch
+// path, and none exists here to bypass. This deliberately stays in the
+// .integration.test.ts file rather than a standalone .test.ts because it
+// shares the cascadeFeature/seed fixture above (duplicating that ~100-line
+// setup just to rename the file would cost more than it buys — see
+// kumiko-framework#1437).
 describe("getAll", () => {
   test("getAll picks the most specific row (user > tenant > system)", async () => {
     await stack.http.writeOk(

package/src/config/__tests__/pii-encrypted.integration.test.ts

@@ -141,10 +141,10 @@ describe("piiEncrypted config keys", () => {
   });
 
   test("write without a configured KMS fails loud instead of silently storing plaintext", async () => {
-    resetPiiSubjectKmsForTests();
-    expect(configuredPiiSubjectKms()).toBeUndefined();
-
     try {
+      resetPiiSubjectKmsForTests();
+      expect(configuredPiiSubjectKms()).toBeUndefined();
+
       const res = await stack.http.write(
         ConfigHandlers.set,
         { key: BILLING_ADDRESS_KEY, value: "no-kms-value" },
@@ -166,10 +166,10 @@ describe("piiEncrypted config keys", () => {
       tenantAdmin,
     );
 
-    resetPiiSubjectKmsForTests();
-    expect(configuredPiiSubjectKms()).toBeUndefined();
-
     try {
+      resetPiiSubjectKmsForTests();
+      expect(configuredPiiSubjectKms()).toBeUndefined();
+
       const res = await stack.http.query(ConfigQueries.values, {}, tenantAdmin);
       expect(res.status).toBe(500);
     } finally {