@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/auth-mfa/web/mfa-regenerate-recovery-dialog.tsx

@@ -0,0 +1,69 @@
+// @runtime client
+// MfaRegenerateRecoveryDialog — confirm-with-code, then the caller reveals
+// the new codes. The reveal itself can't live inside this Dialog: Dialog
+// closes in a `finally` right after onConfirm resolves (see profile-screen.
+// tsx's delete-account dialog for the same constraint), so there's no way
+// to keep it open to show the result. onRegenerated hands the new codes to
+// the caller, which is expected to render them via MfaRecoveryCodesReveal
+// (or equivalent) once the dialog has closed.
+
+import { useDispatcher, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+import { AuthMfaHandlers } from "../constants.js";
+
+export type MfaRegenerateRecoveryDialogProps = {
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+  readonly onRegenerated: (codes: readonly string[]) => void;
+  readonly onError: (i18nKey: string) => void;
+};
+
+// kumiko-lint-ignore no-custom-primitives Uses usePrimitives().Dialog internally, name is an MFA domain action, not a primitive reimplementation
+export function MfaRegenerateRecoveryDialog({
+  open,
+  onOpenChange,
+  onRegenerated,
+  onError,
+}: MfaRegenerateRecoveryDialogProps): ReactNode {
+  const t = useTranslation();
+  const { Dialog, Field, Input } = usePrimitives();
+  const dispatcher = useDispatcher();
+  const [code, setCode] = useState("");
+
+  const confirm = async (): Promise<void> => {
+    const res = await dispatcher.write<{ recoveryCodes: readonly string[] }>(
+      AuthMfaHandlers.regenerateRecovery,
+      { code },
+    );
+    setCode("");
+    if (!res.isSuccess) {
+      onError(res.error.i18nKey);
+      return;
+    }
+    onRegenerated(res.data.recoveryCodes);
+  };
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={onOpenChange}
+      title={t("auth.mfa.regenerate.title")}
+      description={t("auth.mfa.regenerate.description")}
+      confirmLabel={t("auth.mfa.regenerate.confirm")}
+      cancelLabel={t("auth.mfa.regenerate.cancel")}
+      onConfirm={confirm}
+      testId="mfa-regenerate-recovery-dialog"
+    >
+      <Field id="mfa-regenerate-code" label={t("auth.mfa.regenerate.code")} required>
+        <Input
+          kind="text"
+          id="mfa-regenerate-code"
+          name="mfa-regenerate-code"
+          value={code}
+          onChange={setCode}
+          autoComplete="one-time-code"
+        />
+      </Field>
+    </Dialog>
+  );
+}

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

@@ -0,0 +1,269 @@
+// @runtime client
+// Consumers that type-check this source never include the ambient declaration on their own.
+/// <reference path="./qrcode-browser.d.ts" />
+// Pre-auth twin of the declarative auth-mfa-enable secretMint screen: a user
+// blocked at login by MFA enforcement and not yet enrolled lands here
+// straight out of the login flow — there is no session yet. Identity comes
+// entirely from the preauthSetupToken login()'s mfa-setup-required result
+// carries (see auth-client.ts's LoginResult). Calls startMfaSetupPreauth/confirmMfa-
+// SetupPreauth directly via fetch (mfa-client.ts) — no useSession(), no
+// useDispatcher(), both assume a real session that doesn't exist here.
+//
+// Session contract: a successful confirm mints cookie+JWT server-side, but
+// THIS component does not refresh the session itself (unlike MfaVerify-
+// Screen, which calls session.refresh() internally). onSuccess fires right
+// after confirm — the caller (e.g. auth-gate's LoginRoute, which already
+// has useSession() in scope) must call refresh() there, otherwise the app
+// stays "unauthenticated" until the next reload.
+
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+// qrcode's package.json#browser remap avoids Node-only deps (yargs/pngjs)
+// for bundlers that honor it — Metro doesn't, hence the explicit subpath.
+import QRCode from "qrcode/lib/browser.js";
+import { type FormEvent, type ReactNode, useState } from "react";
+// kumiko-lint-ignore cross-feature-import client-only component, the feature's server barrel has no web/ re-export
+import { AuthCard } from "../../auth-email-password/web/index.js";
+import { confirmMfaSetupPreauth, startMfaSetupPreauth } from "./mfa-client.js";
+
+type SetupState = {
+  readonly setupToken: string;
+  readonly secretParam: string;
+  readonly recoveryCodes: readonly string[];
+  readonly qrSvg: string;
+};
+
+// otpauth:// URIs put the secret in the query string — extract it for the
+// manual-entry fallback (authenticator apps without a camera / desktop use).
+function extractSecret(otpauthUri: string): string {
+  const query = otpauthUri.split("?")[1] ?? "";
+  return new URLSearchParams(query).get("secret") ?? "";
+}
+
+function reasonToKey(reason: string): string {
+  switch (reason) {
+    case "invalid_totp_code":
+      return "auth.mfa.errors.invalidCode";
+    case "mfa_already_enabled":
+      return "auth.mfa.errors.mfaAlreadyEnabled";
+    case "invalid_setup_token":
+      return "auth.mfa.errors.invalidSetupToken";
+    case "invalid_challenge_token":
+      return "auth.mfa.errors.challengeExpired";
+    case "too_many_attempts":
+      return "auth.mfa.errors.tooManyAttempts";
+    case "rate_limited":
+      return "auth.errors.rateLimited";
+    default:
+      return "auth.mfa.errors.setupFailed";
+  }
+}
+
+export type MfaSetupPreauthScreenProps = {
+  readonly preauthSetupToken: string;
+  /** Account label for the otpauth:// URI (typically the email typed at
+   *  login) — without a session there's no session.user.email to derive it from. */
+  readonly accountLabel: string;
+  readonly title?: string;
+  readonly subtitle?: ReactNode;
+  /** Fired once confirm succeeds — the caller owns session refresh, see the
+   *  file-level comment above. */
+  readonly onSuccess?: () => void;
+  readonly onCancel?: () => void;
+};
+
+export function MfaSetupPreauthScreen({
+  preauthSetupToken,
+  accountLabel,
+  title,
+  subtitle,
+  onSuccess,
+  onCancel,
+}: MfaSetupPreauthScreenProps): ReactNode {
+  const t = useTranslation();
+  const { Button, Banner, Field, Form, Input, Section } = usePrimitives();
+
+  const [setup, setSetup] = useState<SetupState | null>(null);
+  const [acknowledged, setAcknowledged] = useState(false);
+  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
+      // camera/lighting issues than the default, no downside for a code
+      // this short-lived.
+      const qrSvg = await QRCode.toString(res.data.otpauthUri, {
+        type: "svg",
+        errorCorrectionLevel: "H",
+      });
+      setSetup({
+        setupToken: res.data.setupToken,
+        secretParam: extractSecret(res.data.otpauthUri),
+        recoveryCodes: res.data.recoveryCodes,
+        qrSvg,
+      });
+      setAcknowledged(false);
+      setCode("");
+    } catch {
+      setError("setup_failed");
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const confirmSetup = async (): Promise<void> => {
+    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?.();
+    } catch {
+      setError("setup_failed");
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const onSubmit = (e?: FormEvent): void => {
+    e?.preventDefault();
+    void confirmSetup();
+  };
+
+  return (
+    <AuthCard
+      title={title ?? t("auth.mfa.setup.title")}
+      subtitle={subtitle ?? t("auth.mfa.setup.subtitle")}
+    >
+      <div className="p-6 pt-0 flex flex-col gap-4">
+        {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
+            testId="mfa-setup-preauth-intro"
+            actions={
+              <Button
+                variant="primary"
+                onClick={() => void startSetup()}
+                loading={busy}
+                disabled={busy}
+              >
+                {t("auth.mfa.setup.start")}
+              </Button>
+            }
+          >
+            <span className="text-sm text-muted-foreground">{t("auth.mfa.setup.intro")}</span>
+          </Section>
+        )}
+
+        {setup && (
+          <Form onSubmit={onSubmit}>
+            <Section
+              testId="mfa-setup-preauth-setup"
+              actions={
+                <Button
+                  type="submit"
+                  variant="primary"
+                  loading={busy}
+                  disabled={busy || !acknowledged || code.length !== 6}
+                >
+                  {t("auth.mfa.setup.confirm")}
+                </Button>
+              }
+            >
+              <div className="flex flex-col items-center gap-2 text-center">
+                <span className="text-sm font-semibold">{t("auth.mfa.enable.scanTitle")}</span>
+                {/* qrcode's own SVG string output, not user input — safe to inline */}
+                <div
+                  className="h-40 w-40"
+                  // biome-ignore lint/security/noDangerouslySetInnerHtml: qrcode-generated SVG, no user input
+                  dangerouslySetInnerHTML={{ __html: setup.qrSvg }}
+                />
+                <span className="text-xs text-muted-foreground">
+                  {t("auth.mfa.enable.manualEntry")}
+                </span>
+                <code className="inline-block break-all rounded bg-muted px-3 py-2 font-mono text-sm">
+                  {setup.secretParam}
+                </code>
+              </div>
+
+              <div className="flex flex-col gap-2">
+                <span className="text-sm font-semibold">{t("auth.mfa.enable.recoveryTitle")}</span>
+                <span className="text-xs text-muted-foreground">
+                  {t("auth.mfa.enable.recoveryHint")}
+                </span>
+                <code className="block whitespace-pre-wrap break-all rounded bg-muted px-3 py-2 font-mono text-sm">
+                  {setup.recoveryCodes.join("\n")}
+                </code>
+                <Field id="mfa-setup-preauth-ack" label={t("auth.mfa.enable.acknowledge")}>
+                  <Input
+                    kind="boolean"
+                    id="mfa-setup-preauth-ack"
+                    name="mfa-setup-preauth-ack"
+                    value={acknowledged}
+                    onChange={setAcknowledged}
+                  />
+                </Field>
+              </div>
+
+              <Field id="mfa-setup-preauth-code" label={t("auth.mfa.enable.code")} required>
+                <Input
+                  kind="text"
+                  id="mfa-setup-preauth-code"
+                  name="mfa-setup-preauth-code"
+                  value={code}
+                  onChange={setCode}
+                  disabled={busy || !acknowledged}
+                  autoComplete="one-time-code"
+                />
+              </Field>
+            </Section>
+          </Form>
+        )}
+
+        {onCancel ? (
+          <div className="flex justify-center">
+            <Button type="button" variant="secondary" onClick={onCancel} disabled={busy}>
+              {t("auth.mfa.verify.backToLogin")}
+            </Button>
+          </div>
+        ) : null}
+      </div>
+    </AuthCard>
+  );
+}

package/packages/bundled-features/src/auth-mfa/web/mfa-verify-screen.tsx

@@ -0,0 +1,117 @@
+// @runtime client
+// Login-Challenge-Step, gerendert wenn LoginScreen's onMfaChallenge feuert
+// (/auth/login antwortete mfaRequired). Stilistisch wie login-screen.tsx:
+// useState + direkter fetch-Call, kein Dispatcher — es existiert noch kein
+// JWT. Nach Erfolg ruft es session.refresh() statt eines Hard-Reloads, weil
+// der Aufrufer (typisch ein Wizard-State im App-Root) sofort neu rendern
+// will, sobald status:"authenticated" ankommt.
+
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type FormEvent, type ReactNode, useState } from "react";
+// kumiko-lint-ignore cross-feature-import client-only barrel, the feature's server barrel has no web/ re-export
+import { AuthCard, useSession } from "../../auth-email-password/web/index.js";
+import { verifyMfaChallenge } from "./mfa-client.js";
+
+export type MfaVerifyScreenProps = {
+  readonly challengeToken: string;
+  readonly title?: string;
+  readonly subtitle?: ReactNode;
+  readonly submitLabel?: string;
+  /** Called after the server confirms the code and the session state has
+   *  refreshed. Optional — apps that swap this screen back out purely on
+   *  session.status changing to "authenticated" don't need it. */
+  readonly onSuccess?: () => void;
+  // Some failures (challenge_expired, too_many_attempts) have no retry path —
+  // the challengeToken is dead. Without this, the host has no way back to
+  // login short of a full page reload. Optional: apps that always mount
+  // this screen fresh per challenge can omit it.
+  readonly onCancel?: () => void;
+};
+
+function reasonToKey(reason: string): string {
+  switch (reason) {
+    case "invalid_totp_code":
+    case "invalid_recovery_code":
+    case "invalid_code":
+      return "auth.mfa.errors.invalidCode";
+    case "challenge_expired":
+    case "invalid_challenge_token":
+      return "auth.mfa.errors.challengeExpired";
+    case "too_many_attempts":
+      return "auth.mfa.errors.tooManyAttempts";
+    case "rate_limited":
+      return "auth.errors.rateLimited";
+    default:
+      return "auth.mfa.errors.verifyFailed";
+  }
+}
+
+export function MfaVerifyScreen({
+  challengeToken,
+  title,
+  subtitle,
+  submitLabel,
+  onSuccess,
+  onCancel,
+}: MfaVerifyScreenProps): ReactNode {
+  const t = useTranslation();
+  const { Form, Field, Input, Button, Banner } = usePrimitives();
+  const session = useSession();
+  const [code, setCode] = useState("");
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const doSubmit = async (): Promise<void> => {
+    setSubmitting(true);
+    setError(null);
+    const res = await verifyMfaChallenge(challengeToken, code);
+    if (res.kind === "success") {
+      await session.refresh();
+      setSubmitting(false);
+      onSuccess?.();
+      return;
+    }
+    setSubmitting(false);
+    setError(res.error.reason);
+  };
+
+  const onSubmit = (e?: FormEvent): void => {
+    e?.preventDefault();
+    void doSubmit();
+  };
+
+  return (
+    <AuthCard
+      title={title ?? t("auth.mfa.verify.title")}
+      subtitle={subtitle ?? t("auth.mfa.verify.subtitle")}
+    >
+      <div className="p-6 pt-0 flex flex-col gap-4">
+        <Form onSubmit={onSubmit}>
+          <Field id="mfa-verify-code" label={t("auth.mfa.verify.code")} required>
+            <Input
+              kind="text"
+              id="mfa-verify-code"
+              name="mfa-verify-code"
+              value={code}
+              onChange={setCode}
+              disabled={submitting}
+              required
+              autoComplete="one-time-code"
+            />
+          </Field>
+          {error !== null ? <Banner variant="error">{t(reasonToKey(error))}</Banner> : null}
+          <Button type="submit" loading={submitting} disabled={submitting}>
+            {submitting
+              ? t("auth.mfa.verify.submitting")
+              : (submitLabel ?? t("auth.mfa.verify.submit"))}
+          </Button>
+          {onCancel ? (
+            <Button type="button" variant="secondary" onClick={onCancel} disabled={submitting}>
+              {t("auth.mfa.verify.backToLogin")}
+            </Button>
+          ) : null}
+        </Form>
+      </div>
+    </AuthCard>
+  );
+}

package/packages/bundled-features/src/auth-mfa/web/qrcode-browser.d.ts

@@ -0,0 +1,11 @@
+// @types/qrcode only declares the main "qrcode" entry, not the browser-only
+// subpath (see mfa-setup-preauth-screen.tsx's import — the main entry pulls
+// in Node-only deps like yargs/pngjs via qrcode's own package.json#browser
+// remap, which Metro doesn't honor). Same runtime shape, just re-typed.
+// `export *` never re-exports a default — `import QRCode from "..."`
+// resolving here relies on the consuming app's esModuleInterop/
+// allowSyntheticDefaultImports (which synthesizes a default from the
+// namespace); without it, the default import comes back undefined.
+declare module "qrcode/lib/browser.js" {
+  export * from "qrcode";
+}

package/packages/bundled-features/src/auth-mfa-user-data/changes.json

@@ -0,0 +1 @@
+[]

package/packages/bundled-features/src/auth-mfa-user-data/hooks.ts

@@ -0,0 +1,60 @@
+// EXT_USER_DATA hooks for userMfa (GDPR Art. 15/17/20). Both totpSecret and
+// recoveryCodes are annotated `personal: { of: "userId" }` in the schema
+// for exactly this: on forget, the row must actually disappear — a
+// leftover TOTP secret or recovery-code hash under an anonymized user is
+// still a live credential nobody can rotate. Mirrors
+// folders-user-data/hooks.ts's executor-based delete (rebuild-safe: forget
+// replays via the event, a raw DELETE would be resurrected by a
+// projection rebuild).
+
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createSystemUser,
+  type UserDataDeleteHook,
+  type UserDataExportHook,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { userMfaEntity, userMfaTable } from "../auth-mfa/index.js";
+import { collectErasureFailure, throwIfErasureFailed } from "../shared/index.js";
+
+const executor = createEventStoreExecutor(userMfaTable, userMfaEntity, {
+  entityName: "user-mfa",
+});
+
+// Never includes totpSecret/recoveryCodes — secret-derived credential
+// material, not portable personal data (same reasoning as api-token's
+// tokenHash exclusion in user-data-rights-defaults). Just confirms
+// enrollment + when, which is what a data subject actually needs to see.
+export const userMfaExportHook: UserDataExportHook = async (ctx) => {
+  const rows = await ctx.db.selectMany<{ id: string; enabledAt: unknown }>(userMfaTable, {
+    userId: ctx.userId,
+    tenantId: ctx.tenantId,
+  });
+  if (rows.length === 0) return null;
+  return {
+    entity: "user-mfa",
+    rows: rows.map((r) => ({ enrolled: true, enabledAt: String(r.enabledAt ?? "") })),
+  };
+};
+
+// Always a real hard-delete regardless of the incoming strategy — a 2FA
+// secret can't be anonymized, and `personal: { of: "userId" }` already
+// means this row belongs to exactly one user (never shared tenant data).
+export const userMfaDeleteHook: UserDataDeleteHook = async (ctx) => {
+  const rows = await ctx.db.selectMany<{ id: string }>(userMfaTable, {
+    userId: ctx.userId,
+    tenantId: ctx.tenantId,
+  });
+  // skip: nothing enrolled for this user — no row to erase
+  if (rows.length === 0) return;
+  const systemUser = createSystemUser(ctx.tenantId);
+  const failures: string[] = [];
+  for (const row of rows) {
+    collectErasureFailure(
+      await executor.forget({ id: row.id }, systemUser, ctx.db),
+      "user-mfa",
+      row.id,
+      failures,
+    );
+  }
+  throwIfErasureFailed(failures);
+};

package/packages/bundled-features/src/auth-mfa-user-data/index.ts

@@ -0,0 +1,21 @@
+// Provides the EXT_USER_DATA export/delete hooks for the `user-mfa` entity as
+// a standalone feature — mount it alongside `auth-mfa` + `user-data-rights`
+// when an app needs 2FA enrollment in its GDPR export/forget pipeline. Kept
+// separate from `auth-mfa` (which only requires "user"/"config") so auth-mfa
+// consumers without the user-data-rights stack don't pull a hard dependency.
+// Mirrors folders-user-data.
+
+import { defineFeature, EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engine";
+import { userMfaDeleteHook, userMfaExportHook } from "./hooks.js";
+
+export const authMfaUserDataFeature = defineFeature("auth-mfa-user-data", (r) => {
+  r.describe(
+    "GDPR (Art. 20 export / Art. 17 erasure) coverage for the `auth-mfa` feature's `user-mfa` entity. Mounts the EXT_USER_DATA export + delete hooks so 2FA enrollment status is included in the user-data export bundle and a user's TOTP secret + recovery codes are hard-deleted (via executor.forget, rebuild-safe) on a data-subject erasure request. Kept separate from `auth-mfa` so consumers without the user-data-rights pipeline don't pull a hard dependency — requires `user-data-rights`, optionalRequires `auth-mfa`.",
+  );
+  r.requires("user-data-rights");
+  r.optionalRequires("auth-mfa");
+  r.useExtension(EXT_USER_DATA, "user-mfa", {
+    export: userMfaExportHook,
+    delete: userMfaDeleteHook,
+  });
+});

package/packages/bundled-features/src/billing-foundation/aggregate-id.ts

@@ -0,0 +1,74 @@
+import { v5 as uuidv5 } from "uuid";
+
+// Fixed UUID-namespace für die deterministic aggregate-id-Ableitung.
+// Generiert einmalig (2026-05-03), in Stein gemeißelt: ein Wechsel
+// würde jeden existing aggregate-Stream re-keyen → kaputter
+// Subscription-State, kaputte Audit-History. Drift-Pin in
+// __tests__/feature.test.ts pinnt die UUID.
+
+/** Pro Plattform-Tenant existiert genau EIN subscription-Aggregate. */
+const SUBSCRIPTION_NAMESPACE = "5c3b2d1e-9a4f-4e8c-b7a3-1f8d6c2e9a4b";
+
+/** Exactly ONE payment-aggregate-stream exists per platform tenant (it
+ *  collects many payment-received events — one stream per tenant, not one
+ *  per payment). Generated 2026-09-11, likewise set in stone. */
+const PAYMENT_NAMESPACE = "dec0b897-646d-4da3-be3c-e9a35a83f4e0";
+
+/** Namespace for deriving a `read_payments` row-id (PK) from
+ *  `(tenantId, providerName, providerEventId)` — see `paymentRowId` below.
+ *  StoredEvent.id is a bigserial (global chronological sequence), not a
+ *  UUID, so it can't back a uuid-typed PK. Generated 2026-09-11, set in
+ *  stone (same rationale as the two namespaces above). */
+const PAYMENT_ROW_NAMESPACE = "3a1c9f4e-6b2d-4c8a-9e5f-7d4b1a2c8e6f";
+
+/** Namespace for the system-tenant stream of an unmatched termination
+ *  declaration (one stream per request). Generated 2026-10-03, set in stone. */
+const TERMINATION_UNMATCHED_NAMESPACE = "7e2f4b9a-3c1d-4a68-8d05-b6c9e1f27a34";
+
+/**
+ * Deterministic aggregate-id für die subscription eines Plattform-
+ * Tenants. EINE Subscription pro Tenant (Add-Ons sind line-items in
+ * derselben subscription, nicht eigene). Provider-Wechsel (z.B.
+ * Stripe→Mollie-Migration) appended einen neuen event auf denselben
+ * Stream — selber Tenant, selber Aggregate-Stream.
+ */
+// @wrapper-known uuid-domain
+export function subscriptionAggregateId(tenantId: string): string {
+  return uuidv5(tenantId, SUBSCRIPTION_NAMESPACE);
+}
+
+/**
+ * Deterministic aggregate-id for a platform tenant's payment-stream. A
+ * tenant can make arbitrarily many one-off-payments — all land as
+ * payment-received events on the same stream (like the subscription-
+ * stream); the read_payments-projection creates its own row per event
+ * (PK = paymentRowId(...), not aggregateId).
+ */
+// @wrapper-known uuid-domain
+export function paymentAggregateId(tenantId: string): string {
+  return uuidv5(tenantId, PAYMENT_NAMESPACE);
+}
+
+/** Deterministic `read_payments` row-id — keyed off `(tenantId, providerName,
+ *  providerEventId)` rather than the event-store's bigserial `event.id` (not
+ *  a UUID) or the shared per-tenant aggregateId (one row per payment). */
+// @wrapper-known uuid-domain
+export function paymentRowId(
+  tenantId: string,
+  providerName: string,
+  providerEventId: string,
+): string {
+  // tenantId is part of the key because the idempotency scan in
+  // process-payment-event.write.ts is per-tenant: two tenants can
+  // legitimately see the same providerEventId (multiple Stripe accounts,
+  // test/prod mix) — without it, the second tenant's INSERT would silently
+  // no-op (ON CONFLICT DO NOTHING) against the first tenant's row, losing
+  // the payment with no error anywhere.
+  return uuidv5(`${tenantId}:${providerName}:${providerEventId}`, PAYMENT_ROW_NAMESPACE);
+}
+
+/** Stream id of one unmatched termination declaration, derived from its request id. */
+// @wrapper-known uuid-domain
+export function terminationUnmatchedAggregateId(requestId: string): string {
+  return uuidv5(requestId, TERMINATION_UNMATCHED_NAMESPACE);
+}