@cosmicdrift/kumiko-bundled-features 0.317.0 → 0.319.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.317.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>",
@@ -55,6 +55,7 @@
     "./ledger": "./src/ledger/index.ts",
     "./ledger/web": "./src/ledger/web/index.ts",
     "./billing-foundation": "./src/billing-foundation/index.ts",
+    "./billing-foundation/web": "./src/billing-foundation/web/index.ts",
     "./subscription-stripe": "./src/subscription-stripe/index.ts",
     "./subscription-mollie": "./src/subscription-mollie/index.ts",
     "./foundation-shared": "./src/foundation-shared/index.ts",
@@ -133,12 +134,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.317.0",
-    "@cosmicdrift/kumiko-framework": "0.317.0",
-    "@cosmicdrift/kumiko-headless": "0.317.0",
-    "@cosmicdrift/kumiko-renderer": "0.317.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.317.0",
-    "@cosmicdrift/kumiko-types": "0.317.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",
@@ -153,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": {
@@ -167,8 +168,8 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.317.0",
-    "@cosmicdrift/kumiko-locale-es": "0.317.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

@@ -47,7 +47,7 @@ import {
   SubscriptionFoundationHandlers,
   SubscriptionStatuses,
 } from "../constants";
-import { billingFoundationFeature } from "../feature";
+import { createBillingFoundationFeature } from "../feature";
 import { paymentsProjectionTable, subscriptionsProjectionTable } from "../projection";
 import type { PaymentEvent, SubscriptionProviderPlugin } from "../types";
 import { createSubscriptionWebhookRoute } from "../webhook-handler";
@@ -73,6 +73,11 @@ const mockProviderFeature = defineFeature("test-mock-provider", (r) => {
   r.requires("billing-foundation");
   const plugin: SubscriptionProviderPlugin = {
     verifyAndParseWebhook: async () => null,
+    // Only the two tiers scenario 6's subscription-mode checkouts actually
+    // 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,
@@ -131,7 +136,7 @@ beforeAll(async () => {
       createTenantFeature(),
       createComplianceProfilesFeature(),
       createTenantLifecycleFeature(),
-      billingFoundationFeature,
+      createBillingFoundationFeature({ baseUrl: "https://example.com" }),
       mockProviderFeature,
       mockPaymentProviderFeature,
     ],
@@ -174,6 +179,7 @@ function buildEvent(
     providerCustomerId: string;
     providerSubscriptionId: string;
     currentPeriodEndIso: string;
+    cancelAtIso: string | null;
     rawPayload: string;
   }> = {},
 ) {
@@ -186,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"}',
   };
 }
@@ -480,7 +492,10 @@ describe("scenario 5: Provider-Wechsel mid-period (Disney+-Pattern)", () => {
 describe("scenario 6: create-checkout-session — Plugin-routing", () => {
   test("happy-path: valid provider → URL durchgereicht + plugin mit korrekten args aufgerufen", async () => {
     mockCheckoutCalls.length = 0;
-    const admin = adminFor(3009);
+    // Not 3009 — scenario 5 reuses that tenant number and leaves it with a
+    // non-terminal "pro" subscription; openCheckout's new existing-
+    // subscription conflict-gate would reject this checkout for it.
+    const admin = adminFor(3016);
     const result = (await stack.http.writeOk(
       "billing-foundation:write:create-checkout-session",
       {
@@ -525,7 +540,26 @@ describe("scenario 6: create-checkout-session — Plugin-routing", () => {
 
   test("optional providerCustomerId wird durchgereicht (Plan-Wechsel-Flow)", async () => {
     mockCheckoutCalls.length = 0;
-    const admin = adminFor(3012);
+    // Not 3012 — that tenant already gets its own subscription in the
+    // crypto-shredding test further down and would collide.
+    const admin = adminFor(3018);
+
+    // The provider customer-id must belong to the caller's own subscription
+    // (even if canceled) — otherwise the foreign_provider_customer guard fires.
+    await stack.http.writeOk(
+      SubscriptionFoundationHandlers.processEvent,
+      {
+        ...buildEvent({
+          providerEventId: "evt_3018_create",
+          providerCustomerId: "cus_existing_xyz",
+          providerSubscriptionId: "sub_3018",
+          status: SubscriptionStatuses.canceled,
+        }),
+        providerName: "mock",
+      },
+      admin,
+    );
+
     await stack.http.writeOk(
       "billing-foundation:write:create-checkout-session",
       {
@@ -540,6 +574,59 @@ describe("scenario 6: create-checkout-session — Plugin-routing", () => {
     expect(mockCheckoutCalls[0]?.providerCustomerId).toBe("cus_existing_xyz");
   });
 
+  test("fremde providerCustomerId wird abgelehnt (foreign_provider_customer)", async () => {
+    mockCheckoutCalls.length = 0;
+    const other = adminFor(3019);
+    await stack.http.writeOk(
+      SubscriptionFoundationHandlers.processEvent,
+      {
+        ...buildEvent({
+          providerEventId: "evt_3019_create",
+          providerCustomerId: "cus_belongs_to_tenant_3019",
+          providerSubscriptionId: "sub_3019",
+        }),
+        providerName: "mock",
+      },
+      other,
+    );
+
+    const admin = adminFor(3017);
+    const error = await stack.http.writeErr(
+      "billing-foundation:write:create-checkout-session",
+      {
+        providerName: "mock",
+        priceId: "price_pro_test",
+        successUrl: "https://example.com/s",
+        cancelUrl: "https://example.com/c",
+        providerCustomerId: "cus_belongs_to_tenant_3019",
+      },
+      admin,
+    );
+    expect(error.httpStatus).toBe(422);
+    expect(error.i18nKey).toBe("billing-foundation.errors.foreignProviderCustomer");
+    expect(mockCheckoutCalls).toHaveLength(0);
+  });
+
+  test("fremde providerCustomerId wird auch im mode:payment abgelehnt", async () => {
+    mockCheckoutCalls.length = 0;
+    const admin = adminFor(3020);
+    const error = await stack.http.writeErr(
+      "billing-foundation:write:create-checkout-session",
+      {
+        providerName: "mock",
+        priceId: "price_topup_test",
+        successUrl: "https://example.com/s",
+        cancelUrl: "https://example.com/c",
+        providerCustomerId: "cus_belongs_to_tenant_3019",
+        mode: "payment",
+      },
+      admin,
+    );
+    expect(error.httpStatus).toBe(422);
+    expect(error.i18nKey).toBe("billing-foundation.errors.foreignProviderCustomer");
+    expect(mockCheckoutCalls).toHaveLength(0);
+  });
+
   test("optional mode wird durchgereicht (One-off-Payment-Flow, fw#2755)", async () => {
     mockCheckoutCalls.length = 0;
     const admin = adminFor(3014);
@@ -598,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>;
 
@@ -608,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",
     });
   });
 
@@ -620,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/);
@@ -667,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-admin-only.integration.test.ts

@@ -0,0 +1,158 @@
+// Admin-only billing-plans catalog — a separate stack (own viewRoles/
+// purchaseRoles: ["Admin"]) instead of a describe-block inside
+// billing-plans.integration.test.ts, matching how show-pony pins a distinct
+// role-shape against its own setupTestStack rather than layering it onto a
+// shared one. Proves the catalog's role-gate isn't hardcoded to
+// TenantAdmin/SystemAdmin: an app that restricts billing to a custom "Admin"
+// role locks TenantAdmin out of both the query and the purchase-handlers.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import {
+  createComplianceProfilesFeature,
+  tenantComplianceProfileEntity,
+} from "../../compliance-profiles";
+import { createConfigFeature } from "../../config";
+import { createTenantFeature } from "../../tenant/feature";
+import { tenantEntity } from "../../tenant/schema/tenant";
+import { createTenantLifecycleFeature } from "../../tenant-lifecycle";
+import { subscriptionAggregateId } from "../aggregate-id";
+import { SubscriptionFoundationHandlers, SubscriptionStatuses } from "../constants";
+import { createBillingFoundationFeature } from "../feature";
+import { subscriptionsProjectionTable } from "../projection";
+import type { BillingPlanCatalog, ProviderPrice, SubscriptionProviderPlugin } from "../types";
+
+const PRICE_TO_TIER: Readonly<Record<string, string>> = { price_pro: "pro" };
+
+const PRICES: readonly ProviderPrice[] = [
+  {
+    priceId: "price_pro",
+    unitAmount: 1900,
+    currency: "usd",
+    interval: "month",
+    intervalCount: 1,
+    active: true,
+    metadata: {},
+  },
+];
+
+const checkoutCalls: Array<{ priceId: string }> = [];
+
+const adminOnlyProviderFeature = defineFeature("test-mock-admin-only-provider", (r) => {
+  r.requires("billing-foundation");
+  const plugin: SubscriptionProviderPlugin = {
+    verifyAndParseWebhook: async () => null,
+    priceToTier: PRICE_TO_TIER,
+    retrievePrices: async (_ctx, priceIds) => PRICES.filter((p) => priceIds.includes(p.priceId)),
+    createCheckoutSession: async (_ctx, options) => {
+      checkoutCalls.push({ priceId: options.priceId });
+      return { url: `https://mock.example/checkout/${options.priceId}` };
+    },
+  };
+  r.useExtension("subscriptionProvider", "mock-admin-only-provider", plugin);
+});
+
+async function resolveCurrentTier(db: TenantDb, tenantId: string): Promise<string> {
+  const rows = await db.selectMany(
+    subscriptionsProjectionTable,
+    { id: subscriptionAggregateId(tenantId) },
+    { limit: 1 },
+  );
+  const row = rows[0];
+  if (!row) return "free";
+  const status = row["status"] as string;
+  return status === SubscriptionStatuses.active || status === SubscriptionStatuses.trialing
+    ? (row["tier"] as string)
+    : "free";
+}
+
+const adminOnlyCatalog: BillingPlanCatalog<"pro"> = {
+  plans: ["pro"],
+  tierLabelKey: (tier) => `plan.${tier}.label`,
+  benefits: () => [],
+  resolveCurrentTier,
+  viewRoles: ["Admin"],
+  purchaseRoles: ["Admin"],
+  successPath: "/billing/success",
+  cancelPath: "/billing/cancel",
+  providerName: "mock-admin-only-provider",
+};
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createTenantFeature(),
+      createComplianceProfilesFeature(),
+      createTenantLifecycleFeature(),
+      createBillingFoundationFeature({
+        baseUrl: "https://app.example.com",
+        catalog: adminOnlyCatalog,
+      }),
+      adminOnlyProviderFeature,
+    ],
+  });
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafeCreateEntityTable(stack.db, tenantComplianceProfileEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("billing-plans catalog with viewRoles/purchaseRoles restricted to a custom Admin role", () => {
+  test("an Admin can query the catalog and start a checkout through to the mock provider", async () => {
+    const admin = createTestUser({ id: 8001, tenantId: testTenantId(8001), roles: ["Admin"] });
+
+    const result = (await stack.http.queryOk(
+      "billing-foundation:query:billing-plans",
+      {},
+      admin,
+    )) as {
+      canPurchase: boolean;
+      plans: Array<{ tier: string; action: string }>;
+    };
+    expect(result.canPurchase).toBe(true);
+    expect(result.plans.find((p) => p.tier === "pro")?.action).toBe("checkout");
+
+    const checkout = (await stack.http.writeOk(
+      SubscriptionFoundationHandlers.startPlanCheckout,
+      { tier: "pro" },
+      admin,
+    )) as { url: string };
+    expect(checkout.url).toBe("https://mock.example/checkout/price_pro");
+    expect(checkoutCalls).toEqual([{ priceId: "price_pro" }]);
+  });
+
+  test("a TenantAdmin without the Admin role is rejected on both query and start-plan-checkout", async () => {
+    const tenantAdmin = createTestUser({
+      id: 8002,
+      tenantId: testTenantId(8002),
+      roles: ["TenantAdmin"],
+    });
+
+    const queryError = await stack.http.queryErr(
+      "billing-foundation:query:billing-plans",
+      {},
+      tenantAdmin,
+    );
+    expect(queryError.httpStatus).toBe(403);
+
+    const writeError = await stack.http.writeErr(
+      SubscriptionFoundationHandlers.startPlanCheckout,
+      { tier: "pro" },
+      tenantAdmin,
+    );
+    expect(writeError.httpStatus).toBe(403);
+  });
+});