@cosmicdrift/kumiko-bundled-features 0.318.0 → 0.319.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.318.0",
+  "version": "0.319.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -134,12 +134,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.318.0",
-    "@cosmicdrift/kumiko-framework": "0.318.0",
-    "@cosmicdrift/kumiko-headless": "0.318.0",
-    "@cosmicdrift/kumiko-renderer": "0.318.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.318.0",
-    "@cosmicdrift/kumiko-types": "0.318.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.319.0",
+    "@cosmicdrift/kumiko-framework": "0.319.0",
+    "@cosmicdrift/kumiko-headless": "0.319.0",
+    "@cosmicdrift/kumiko-renderer": "0.319.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.319.0",
+    "@cosmicdrift/kumiko-types": "0.319.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -154,7 +154,7 @@
     "qrcode": "^1.5.4",
     "react": "^19.2.6",
     "sharp": "^0.35.4",
-    "stripe": "^22.1.1",
+    "stripe": "^22.6.2",
     "tailwind-merge": "^3.6.0"
   },
   "publishConfig": {
@@ -168,8 +168,8 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.318.0",
-    "@cosmicdrift/kumiko-locale-es": "0.318.0",
+    "@cosmicdrift/kumiko-locale-de": "0.319.0",
+    "@cosmicdrift/kumiko-locale-es": "0.319.0",
     "jsqr": "^1.4.0"
   }
 }

package/src/auth-email-password/constants.ts

@@ -1,9 +1,9 @@
 // @runtime client
-// Pure string-Konstanten — keine DB/Node-builtins. Mit `@runtime client`
-// markiert damit auch Browser-Code (Members-Screen etc.) sie importieren
-// kann ohne dass die runtime-isolation-Guard schreit. Runtime darf
-// "client"-Files importieren (siehe RUNTIME_RULES), also bleibt auch
-// der server-side Zugriff (handlers, dispatcher) erhalten.
+// Pure string constants — no DB/Node builtins. Marked `@runtime client` so
+// browser code (Members screen etc.) can import them too without the
+// runtime-isolation guard complaining. Runtime may import "client" files
+// (see RUNTIME_RULES), so server-side access (handlers, dispatcher) stays
+// intact as well.
 export const AUTH_EMAIL_PASSWORD_FEATURE = "auth-email-password" as const;
 
 // Minimum length for reset/verify hmacSecret — mirrors the ≥32-char
@@ -25,20 +25,20 @@ export const AuthHandlers = {
   // Redis lockout state.
   requestAccountUnlock: "auth-email-password:write:request-account-unlock",
   confirmAccountUnlock: "auth-email-password:write:confirm-account-unlock",
-  // Magic-Link Self-Signup (Pre-Activation-Token-Pattern). request mintet
-  // einen opaken Random-Token, speichert ihn bidirektional in Redis und
-  // sendet eine Aktivierungs-Mail. confirm löst den Token ein und legt
-  // user + tenant + Admin-Membership atomar an. emailVerified=true ab
-  // Sekunde 0 — der Klick auf den Mail-Link IST der Beweis.
+  // Magic-link self-signup (pre-activation-token pattern). Request mints an
+  // opaque random token, stores it bidirectionally in Redis and sends an
+  // activation email. Confirm redeems the token and creates
+  // user + tenant + Admin membership atomically. emailVerified=true from
+  // second 0 — clicking the mail link IS the proof.
   signupRequest: "auth-email-password:write:signup-request",
   signupConfirm: "auth-email-password:write:signup-confirm",
-  // Tenant-Invite Magic-Link (Admin lädt User in existing Tenant ein).
-  // Drei separate accept-Endpoints für klare Branch-Separation:
-  //   inviteCreate: Admin → POST email + role
-  //   inviteAccept: logged-in User → POST token (membership-add)
-  //   inviteAcceptWithLogin: anon User mit existing email → POST token + email + password
-  //   inviteSignupComplete: anon User mit neuer email → POST token + password
-  //   inviteCancel: Admin cancelt pending invite
+  // Tenant-invite magic-link (admin invites a user into an existing tenant).
+  // Three separate accept endpoints for clear branch separation:
+  //   inviteCreate: admin → POST email + role
+  //   inviteAccept: logged-in user → POST token (membership-add)
+  //   inviteAcceptWithLogin: anon user with existing email → POST token + email + password
+  //   inviteSignupComplete: anon user with new email → POST token + password
+  //   inviteCancel: admin cancels a pending invite
   inviteCreate: "auth-email-password:write:invite-create",
   inviteAccept: "auth-email-password:write:invite-accept",
   inviteAcceptWithLogin: "auth-email-password:write:invite-accept-with-login",
@@ -76,20 +76,20 @@ export const AuthErrors = {
   // code so a probing client can't distinguish tampered from stale.
   invalidUnlockToken: "invalid_unlock_token",
   unlockNotConfigured: "account_unlock_not_configured",
-  // Self-Signup: alle confirm-Failures (unbekannter Token, schon
-  // konsumiert, abgelaufen) collapsen auf diesen Code — gleicher
-  // anti-enumeration-Trade-off wie reset/verify.
+  // Self-signup: all confirm failures (unknown token, already
+  // consumed, expired) collapse onto this code — same
+  // anti-enumeration trade-off as reset/verify.
   invalidSignupToken: "invalid_signup_token",
   signupNotConfigured: "signup_not_configured",
-  // Self-Signup: confirm lehnt eine bereits registrierte Email ab statt den
-  // bestehenden User wiederzuverwenden (Account-Takeover, #365). KEIN
-  // anti-enumeration-collapse wie invalidSignupToken: wer hier ankommt,
-  // kontrolliert die Inbox (hat den Magic-Link), das Reveal "Email existiert"
-  // ist also keine neue Info.
+  // Self-signup: confirm rejects an already-registered email instead of
+  // reusing the existing user (account takeover, #365). NO
+  // anti-enumeration collapse like invalidSignupToken: whoever gets here
+  // controls the inbox (has the magic link), so revealing "email exists"
+  // is not new information.
   signupEmailAlreadyRegistered: "signup_email_already_registered",
-  // Invite-Flow: alle Token-Failures collapsen auf invalidInviteToken
-  // (anti-enumeration). emailMismatch wenn der invitee versucht den
-  // Link mit einer anderen Email zu accepten als die eingeladene.
+  // Invite flow: all token failures collapse onto invalidInviteToken
+  // (anti-enumeration). emailMismatch when the invitee tries to accept the
+  // link with a different email than the one invited.
   invalidInviteToken: "invalid_invite_token",
   inviteEmailMismatch: "invite_email_mismatch",
   inviteAlreadyMember: "invite_already_member",
@@ -100,17 +100,17 @@ export const AuthErrors = {
   // deliberate enumeration trade-off: the lockout event itself is already
   // observable to the attacker, and legit users benefit from a clear signal.
   accountLocked: "account_locked",
-  // S2.U6 (DSGVO Art. 18) — Account ist im Restricted-Status. Login wird
-  // explicit verweigert mit eigenem Code (nicht zu invalid_credentials
-  // collapsen) damit UI sagen kann "Account ist aktuell pausiert, hier
-  // klicken zum Aufheben". Enumeration-leak akzeptiert: Restriction ist
-  // user-initiiert, der User weiss dass sein Konto restricted ist.
+  // S2.U6 (GDPR Art. 18) — account is in Restricted status. Login is
+  // explicitly refused with its own code (not collapsed into
+  // invalid_credentials) so the UI can say "account is currently paused,
+  // click here to lift it". Enumeration leak accepted: restriction is
+  // user-initiated, the user already knows their account is restricted.
   accountRestricted: "account_restricted",
-  // Account ist im DeletionRequested- oder Deleted-Status. Anders als
-  // Restricted ist das nicht reversibel via Login → wir collapsen auf
-  // invalid_credentials damit Forget-Pfad nicht via Login enumerierbar
-  // wird (User der "Konto loeschen" geklickt hat soll nicht erneut sehen
-  // dass die Email-Adresse noch in der DB existiert).
+  // Account is in DeletionRequested or Deleted status. Unlike
+  // Restricted, this is not reversible via login → we collapse onto
+  // invalid_credentials so the forget-path isn't enumerable via login
+  // (a user who clicked "delete account" shouldn't see again that their
+  // email address still exists in the DB).
 } as const;
 
 // Account-lockout defaults — overridable via
@@ -132,12 +132,12 @@ export const AUTH_RESET_DEFAULT_TTL_MINUTES = 15;
 // replaying the same token re-sets the same flag.
 export const AUTH_VERIFY_DEFAULT_TTL_MINUTES = 24 * 60;
 
-// Self-Signup: 24h Default. Lang genug damit User nicht denken muss
-// "schnell aktivieren" — ein Mail-Link der morgen früh noch geht ist
-// User-Friendly. Kürzere TTLs werfen Resend-Spam weil User vergessen.
+// Self-signup: 24h default. Long enough that the user doesn't have to
+// think "activate quickly" — a mail link that still works tomorrow morning
+// is user-friendly. Shorter TTLs cause resend-spam because users forget.
 export const AUTH_SIGNUP_DEFAULT_TTL_MINUTES = 24 * 60;
 
-// Tenant-Invite: 7 Tage Default. Industry-Standard (GitHub, Linear,
-// Slack); invitees brauchen oft länger zum Reagieren als bei Self-
-// Signup wo die User-Intention frisch ist.
+// Tenant invite: 7 days default. Industry standard (GitHub, Linear,
+// Slack); invitees often need longer to respond than in self-signup,
+// where the user's intent is fresh.
 export const AUTH_INVITE_DEFAULT_TTL_MINUTES = 7 * 24 * 60;

package/src/billing-foundation/__tests__/billing-foundation.integration.test.ts

@@ -77,6 +77,7 @@ const mockProviderFeature = defineFeature("test-mock-provider", (r) => {
     // exercise — the hardened create-checkout-session now requires every
     // mode:"subscription" priceId to resolve through priceToTier.
     priceToTier: { price_pro_test: "pro", price_business_test: "business" },
+    oneOffPriceIds: ["price_topup_test"],
     createCheckoutSession: async (_ctx, options) => {
       mockCheckoutCalls.push({
         priceId: options.priceId,
@@ -178,6 +179,7 @@ function buildEvent(
     providerCustomerId: string;
     providerSubscriptionId: string;
     currentPeriodEndIso: string;
+    cancelAtIso: string | null;
     rawPayload: string;
   }> = {},
 ) {
@@ -190,6 +192,12 @@ function buildEvent(
     status: overrides.status ?? SubscriptionStatuses.active,
     tier: overrides.tier ?? "pro",
     currentPeriodEndIso: overrides.currentPeriodEndIso ?? "2026-06-01T00:00:00Z",
+    // `cancelAtIso` stays entirely absent from the payload unless an override
+    // sets it — undefined (key omitted) vs. null (explicit clear) is the
+    // 3-way distinction cancelAtSetFromPayload relies on; a `?? undefined`
+    // default here would collapse "omitted" into "explicit null" and hide a
+    // regression where a later event without the field wipes a prior value.
+    ...(overrides.cancelAtIso !== undefined && { cancelAtIso: overrides.cancelAtIso }),
     rawPayload: overrides.rawPayload ?? '{"raw":"payload"}',
   };
 }
@@ -677,7 +685,7 @@ describe("scenario 7: create-portal-session — Plugin-routing", () => {
 
     const result = (await stack.http.writeOk(
       "billing-foundation:write:create-portal-session",
-      { returnUrl: "https://example.com/return" },
+      {},
       admin,
     )) as Record<string, unknown>;
 
@@ -687,11 +695,13 @@ describe("scenario 7: create-portal-session — Plugin-routing", () => {
     // Drift-pin: portal-handler liest providerCustomerId AUS DER DB
     // (subscription-row), nicht aus der payload. Wenn ein Refactor das
     // umstellt (= Tenant könnte fremde portal-sessions öffnen), würde
-    // mockPortalCalls den falschen customer-id sehen.
+    // mockPortalCalls den falschen customer-id sehen. returnUrl is now
+    // server-computed (portalReturnUrl) — no catalog mounted here, so it
+    // collapses onto baseUrl itself.
     expect(mockPortalCalls).toHaveLength(1);
     expect(mockPortalCalls[0]).toEqual({
       providerCustomerId: "cus_3013",
-      returnUrl: "https://example.com/return",
+      returnUrl: "https://example.com",
     });
   });
 
@@ -699,7 +709,7 @@ describe("scenario 7: create-portal-session — Plugin-routing", () => {
     const admin = adminFor(3011);
     const error = await stack.http.writeErr(
       "billing-foundation:write:create-portal-session",
-      { returnUrl: "https://example.com/return" },
+      {},
       admin,
     );
     expect(JSON.stringify(error)).toMatch(/no active subscription/);
@@ -746,6 +756,68 @@ describe("scenario 8: cancel-event setzt status auf canceled, behält subscripti
   });
 });
 
+describe("scenario 8b: cancelAt — set / leave-unchanged / clear across events", () => {
+  test("event without cancelAtIso key keeps a prior value; explicit null clears it", async () => {
+    const admin = adminFor(3009);
+
+    // 1. create with cancelAt set — a Stripe cancel_at_period_end webhook.
+    await stack.http.writeOk(
+      SubscriptionFoundationHandlers.processEvent,
+      buildEvent({
+        providerEventId: "evt_3009_create",
+        providerCustomerId: "cus_3009",
+        providerSubscriptionId: "sub_3009",
+        cancelAtIso: "2026-07-01T00:00:00Z",
+      }),
+      admin,
+    );
+    let subs = (await stack.http.queryOk(
+      "billing-foundation:query:subscription:list",
+      {},
+      admin,
+    )) as { rows: Array<Record<string, unknown>> };
+    expect(subs.rows[0]?.["cancelAt"]).toBe("2026-07-01T00:00:00Z");
+
+    // 2. an unrelated update event that never mentions cancelAtIso (e.g. a
+    // price/tier change) must NOT wipe the previously recorded cancelAt.
+    await stack.http.writeOk(
+      SubscriptionFoundationHandlers.processEvent,
+      buildEvent({
+        providerEventId: "evt_3009_update",
+        type: SubscriptionEventTypes.updated,
+        providerCustomerId: "cus_3009",
+        providerSubscriptionId: "sub_3009",
+        tier: "business",
+      }),
+      admin,
+    );
+    subs = (await stack.http.queryOk("billing-foundation:query:subscription:list", {}, admin)) as {
+      rows: Array<Record<string, unknown>>;
+    };
+    expect(subs.rows[0]?.["tier"]).toBe("business");
+    expect(subs.rows[0]?.["cancelAt"]).toBe("2026-07-01T00:00:00Z");
+
+    // 3. reactivation — an update event with cancelAtIso explicitly null
+    // clears it.
+    await stack.http.writeOk(
+      SubscriptionFoundationHandlers.processEvent,
+      buildEvent({
+        providerEventId: "evt_3009_reactivate",
+        type: SubscriptionEventTypes.updated,
+        providerCustomerId: "cus_3009",
+        providerSubscriptionId: "sub_3009",
+        tier: "business",
+        cancelAtIso: null,
+      }),
+      admin,
+    );
+    subs = (await stack.http.queryOk("billing-foundation:query:subscription:list", {}, admin)) as {
+      rows: Array<Record<string, unknown>>;
+    };
+    expect(subs.rows[0]?.["cancelAt"]).toBeNull();
+  });
+});
+
 // scenario 9 (subscriptionTenantDestroyHook direct-call, default+HGB branches) removed:
 // covered end-to-end by billing-foundation/__tests__/tenant-destroy.integration.test.ts,
 // which drives the real tenant-lifecycle sweep instead of hand-feeding the hook.

package/src/billing-foundation/__tests__/billing-plans.integration.test.ts

@@ -82,6 +82,7 @@ const checkoutCalls: Array<{
   successUrl: string;
   cancelUrl: string;
   providerCustomerId?: string;
+  mode?: string;
 }> = [];
 const switchCalls: Array<{
   providerSubscriptionId: string;
@@ -89,12 +90,14 @@ const switchCalls: Array<{
   allowedPriceIds: readonly string[];
   returnUrl: string;
 }> = [];
+const portalCalls: Array<{ providerCustomerId: string; returnUrl: string }> = [];
 
 const mockPlanProviderFeature = defineFeature("test-mock-plan-provider", (r) => {
   r.requires("billing-foundation");
   const plugin: SubscriptionProviderPlugin = {
     verifyAndParseWebhook: async () => null,
     priceToTier: PRICE_TO_TIER,
+    oneOffPriceIds: ["price_topup_credits"],
     isBillingEnabled: async () => billingEnabled,
     retrievePrices: async (_ctx, priceIds) => {
       if (retrievePricesMode === "throw") throw new Error("mock provider price lookup failed");
@@ -106,9 +109,17 @@ const mockPlanProviderFeature = defineFeature("test-mock-plan-provider", (r) =>
         successUrl: options.successUrl,
         cancelUrl: options.cancelUrl,
         ...(options.providerCustomerId && { providerCustomerId: options.providerCustomerId }),
+        ...(options.mode && { mode: options.mode }),
       });
       return { url: `https://mock.example/checkout/${options.priceId}` };
     },
+    createPortalSession: async (_ctx, options) => {
+      portalCalls.push({
+        providerCustomerId: options.providerCustomerId,
+        returnUrl: options.returnUrl,
+      });
+      return { url: `https://mock.example/portal/${options.providerCustomerId}` };
+    },
     createPlanSwitchSession: async (_ctx, options) => {
       if (switchPlanErrorMode === "plan_tiers_share_product") {
         throw new UnprocessableError("plan_tiers_share_product", {
@@ -201,6 +212,7 @@ beforeEach(() => {
   switchPlanErrorMode = "ok";
   checkoutCalls.length = 0;
   switchCalls.length = 0;
+  portalCalls.length = 0;
 });
 
 function adminFor(tenantNumber: number) {
@@ -254,7 +266,7 @@ describe("billing-plans query — no subscription", () => {
       admin,
     )) as {
       enabled: boolean;
-      currentTier: { tier: string };
+      currentTier: { tier: string; benefits: Array<{ labelKey: string }> };
       canPurchase: boolean;
       subscription: unknown;
       plans: Array<{ tier: string; action: string; price: { unitAmount: number } | null }>;
@@ -262,6 +274,9 @@ describe("billing-plans query — no subscription", () => {
 
     expect(result.enabled).toBe(true);
     expect(result.currentTier.tier).toBe("free");
+    // #3316 P2: "free" is outside catalog.plans (["starter", "pro"]) — the
+    // benefits lookup must not be gated on membership in catalog.plans.
+    expect(result.currentTier.benefits).toEqual([{ labelKey: "plan.free.benefit.core" }]);
     expect(result.subscription).toBeNull();
     expect(result.canPurchase).toBe(true);
     expect(result.plans).toHaveLength(2);
@@ -294,6 +309,7 @@ describe("start-plan-checkout — no existing subscription", () => {
       priceId: "price_pro",
       successUrl: "https://app.example.com/billing/success",
       cancelUrl: "https://app.example.com/billing/cancel",
+      mode: "subscription",
     });
   });
 });
@@ -393,6 +409,47 @@ describe("active subscription — checkout blocked, switch offered", () => {
       admin,
     )) as { url: string };
     expect(result.url).toBe("https://mock.example/checkout/price_topup_credits");
+    // #3316 P8: the plugin receives mode:"payment", not silently defaulted
+    // to "subscription" or dropped.
+    expect(checkoutCalls[0]?.mode).toBe("payment");
+  });
+
+  test("create-checkout-session mode:payment rejects a priceId outside the provider's oneOffPriceIds allowlist", async () => {
+    const admin = adminFor(7025);
+    const error = await stack.http.writeErr(
+      "billing-foundation:write:create-checkout-session",
+      {
+        providerName: "mock-plan-provider",
+        priceId: "price_not_on_allowlist",
+        successUrl: "https://app.example.com/s",
+        cancelUrl: "https://app.example.com/c",
+        mode: "payment",
+      },
+      admin,
+    );
+    expect(error.httpStatus).toBe(422);
+    expect(error.i18nKey).toBe("billing-foundation.errors.unknownPrice");
+  });
+
+  // Ordering pin: mode:"payment" runs the billing-enabled gate BEFORE the
+  // oneOffPriceIds allowlist check, same as mode:"subscription" already did.
+  // Without this order, a disabled provider would leak "unknown_price" (a
+  // provider-shape detail) instead of the generic "billing disabled" signal.
+  test("create-checkout-session mode:payment with billing disabled fails feature_disabled, not unknown_price", async () => {
+    billingEnabled = false;
+    const admin = adminFor(7026);
+    const error = await stack.http.writeErr(
+      "billing-foundation:write:create-checkout-session",
+      {
+        providerName: "mock-plan-provider",
+        priceId: "price_not_on_allowlist",
+        successUrl: "https://app.example.com/s",
+        cancelUrl: "https://app.example.com/c",
+        mode: "payment",
+      },
+      admin,
+    );
+    expect(error.httpStatus).toBe(403);
   });
 });
 
@@ -798,3 +855,180 @@ describe("stale-incomplete subscription — injected clock", () => {
     expect(checkout.url).toBe("https://mock.example/checkout/price_pro");
   });
 });
+
+// =============================================================================
+// 12. create-portal-session — returnUrl computation + strict payload (#3316 P4)
+// =============================================================================
+
+describe("create-portal-session — returnUrl computation", () => {
+  test("without catalog.returnPath, returnUrl is baseUrl alone", async () => {
+    const admin = adminFor(7027);
+    await createSubscription(admin.tenantId, { tier: "starter" });
+
+    const result = (await stack.http.writeOk(
+      SubscriptionFoundationHandlers.createPortalSession,
+      {},
+      admin,
+    )) as { url: string };
+    expect(result.url).toBe(`https://mock.example/portal/cus_${admin.tenantId}`);
+    expect(portalCalls).toHaveLength(1);
+    expect(portalCalls[0]?.returnUrl).toBe("https://app.example.com");
+  });
+
+  test("an unknown-key payload (e.g. a client-supplied returnUrl) is rejected — schema is z.object({}).strict()", async () => {
+    const admin = adminFor(7028);
+    const error = await stack.http.writeErr(
+      SubscriptionFoundationHandlers.createPortalSession,
+      { returnUrl: "https://evil.example" },
+      admin,
+    );
+    expect(error.httpStatus).toBe(400);
+    expect(error.code).toBe("validation_error");
+  });
+
+  describe("with catalog.returnPath configured", () => {
+    let returnPathStack: TestStack;
+
+    beforeAll(async () => {
+      returnPathStack = await setupTestStack({
+        features: [
+          createConfigFeature(),
+          createTenantFeature(),
+          createComplianceProfilesFeature(),
+          createTenantLifecycleFeature(),
+          createBillingFoundationFeature({
+            baseUrl: "https://app.example.com",
+            catalog: catalog({ returnPath: "/billing/portal-return" }),
+          }),
+          mockPlanProviderFeature,
+        ],
+      });
+      await unsafeCreateEntityTable(returnPathStack.db, tenantEntity);
+      await unsafeCreateEntityTable(returnPathStack.db, tenantComplianceProfileEntity);
+    });
+
+    afterAll(async () => {
+      await returnPathStack.cleanup();
+    });
+
+    test("returnUrl is baseUrl + returnPath", async () => {
+      const admin = adminFor(7029);
+      await createSubscription(admin.tenantId, { tier: "starter" }, returnPathStack);
+
+      await returnPathStack.http.writeOk(
+        SubscriptionFoundationHandlers.createPortalSession,
+        {},
+        admin,
+      );
+      expect(portalCalls.at(-1)?.returnUrl).toBe("https://app.example.com/billing/portal-return");
+    });
+  });
+});
+
+// =============================================================================
+// 13. create-portal-session — catalog.purchaseRoles gates who may open the
+//     portal (#3316 P3): only that role gets in, everyone else is 403.
+// =============================================================================
+
+describe("create-portal-session — catalog.purchaseRoles", () => {
+  let purchaseRoleStack: TestStack;
+
+  beforeAll(async () => {
+    purchaseRoleStack = await setupTestStack({
+      features: [
+        createConfigFeature(),
+        createTenantFeature(),
+        createComplianceProfilesFeature(),
+        createTenantLifecycleFeature(),
+        createBillingFoundationFeature({
+          baseUrl: "https://app.example.com",
+          catalog: catalog({ purchaseRoles: ["Admin"] }),
+        }),
+        mockPlanProviderFeature,
+      ],
+    });
+    await unsafeCreateEntityTable(purchaseRoleStack.db, tenantEntity);
+    await unsafeCreateEntityTable(purchaseRoleStack.db, tenantComplianceProfileEntity);
+  });
+
+  afterAll(async () => {
+    await purchaseRoleStack.cleanup();
+  });
+
+  test("a user with only the configured purchase-role gets 200", async () => {
+    const tenantId = testTenantId(7030);
+    await createSubscription(tenantId, { tier: "starter" }, purchaseRoleStack);
+    const adminRoleUser = createTestUser({ id: 7030, tenantId, roles: ["Admin"] });
+
+    const result = (await purchaseRoleStack.http.writeOk(
+      SubscriptionFoundationHandlers.createPortalSession,
+      {},
+      adminRoleUser,
+    )) as { url: string };
+    expect(result.url).toBeTruthy();
+  });
+
+  test("a user without the configured purchase-role gets 403", async () => {
+    const tenantId = testTenantId(7031);
+    await createSubscription(tenantId, { tier: "starter" }, purchaseRoleStack);
+    const nonPurchaser = createTestUser({ id: 7031, tenantId, roles: ["TenantAdmin"] });
+
+    const error = await purchaseRoleStack.http.writeErr(
+      SubscriptionFoundationHandlers.createPortalSession,
+      {},
+      nonPurchaser,
+    );
+    expect(error.httpStatus).toBe(403);
+  });
+});
+
+// =============================================================================
+// 14. No provider registered at all — billing-plans stays enabled:false,
+//     every plan unavailable, start-plan-checkout fails feature_disabled
+//     (#3316 P5).
+// =============================================================================
+
+describe("no subscription-provider mounted at all", () => {
+  let noProviderStack: TestStack;
+
+  beforeAll(async () => {
+    noProviderStack = await setupTestStack({
+      features: [
+        createConfigFeature(),
+        createTenantFeature(),
+        createComplianceProfilesFeature(),
+        createTenantLifecycleFeature(),
+        createBillingFoundationFeature({ baseUrl: "https://app.example.com", catalog: catalog() }),
+        // Deliberately no provider plugin mounted.
+      ],
+    });
+    await unsafeCreateEntityTable(noProviderStack.db, tenantEntity);
+    await unsafeCreateEntityTable(noProviderStack.db, tenantComplianceProfileEntity);
+  });
+
+  afterAll(async () => {
+    await noProviderStack.cleanup();
+  });
+
+  test("billing-plans: enabled:false, every plan unavailable", async () => {
+    const admin = adminFor(7032);
+    const result = (await noProviderStack.http.queryOk(
+      "billing-foundation:query:billing-plans",
+      {},
+      admin,
+    )) as { enabled: boolean; plans: Array<{ action: string }> };
+    expect(result.enabled).toBe(false);
+    for (const plan of result.plans) expect(plan.action).toBe("unavailable");
+  });
+
+  test("start-plan-checkout: feature_disabled", async () => {
+    const admin = adminFor(7033);
+    const error = await noProviderStack.http.writeErr(
+      SubscriptionFoundationHandlers.startPlanCheckout,
+      { tier: "pro" },
+      admin,
+    );
+    expect(error.httpStatus).toBe(403);
+    expect(error.i18nKey).toBe("errors.feature.disabled");
+  });
+});

package/src/billing-foundation/__tests__/checkout-core.test.ts

@@ -22,6 +22,10 @@ function subscriptionView(overrides: Partial<SubscriptionView> = {}): Subscripti
     // at runtime — SubscriptionView.lastChangedAt is typed against the
     // ambient Temporal global; temporal-polyfill's own nominal Instant type
     // differs across the two .d.ts sources.
+    currentPeriodEnd: TemporalPolyfill.Instant.from(
+      "2024-02-01T00:00:00Z",
+    ) as unknown as Temporal.Instant,
+    cancelAt: null,
     lastChangedAt: TemporalPolyfill.Instant.from(
       "2024-01-01T00:00:00Z",
     ) as unknown as Temporal.Instant,

package/src/billing-foundation/__tests__/feature.test.ts

@@ -4,6 +4,7 @@ import { describe, expect, test } from "bun:test";
 import { paymentAggregateId, paymentRowId, subscriptionAggregateId } from "../aggregate-id";
 import {
   BILLING_FOUNDATION_FEATURE,
+  BILLING_PLANS_SCREEN_ID,
   SUBSCRIPTION_PROVIDER_EXTENSION,
   SubscriptionEventTypes,
   SubscriptionFoundationHandlers,
@@ -234,3 +235,22 @@ describe("createBillingFoundationFeature — factory validation", () => {
     ).toThrow(/viewRoles must not be empty/);
   });
 });
+
+describe("billingFoundationFeature — dormant billing-plans screen (#3316 P9)", () => {
+  test("not registered without a catalog", () => {
+    const feature = createBillingFoundationFeature({ baseUrl: "https://example.com" });
+    expect(feature.screens[BILLING_PLANS_SCREEN_ID]).toBeUndefined();
+  });
+
+  test("not registered with no options at all", () => {
+    expect(billingFoundationFeature.screens[BILLING_PLANS_SCREEN_ID]).toBeUndefined();
+  });
+
+  test("registered once a catalog is configured", () => {
+    const feature = createBillingFoundationFeature({
+      baseUrl: "https://example.com",
+      catalog: catalog(),
+    });
+    expect(feature.screens[BILLING_PLANS_SCREEN_ID]).toBeDefined();
+  });
+});