@cosmicdrift/kumiko-bundled-features 0.60.2 → 0.61.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.60.2",
+  "version": "0.61.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>",

package/src/tags/__tests__/feature.test.ts

@@ -111,6 +111,32 @@ describe("createTagsFeature access-options", () => {
   });
 });
 
+describe("createTagsFeature toggleable-option (tier-gating)", () => {
+  test("without toggleable: feature is always-on (toggleableDefault undefined)", () => {
+    expect(createTagsFeature().toggleableDefault).toBeUndefined();
+    expect(createTagsFeature({ access: { openToAll: true } }).toggleableDefault).toBeUndefined();
+  });
+
+  test("toggleable:{default:false} makes the feature tier-gatable, fail-closed", () => {
+    const feature = createTagsFeature({
+      access: { openToAll: true },
+      toggleable: { default: false },
+    });
+    expect(feature.toggleableDefault).toBe(false);
+  });
+
+  test("toggleable:{default:true} declares toggleable, enabled-by-default", () => {
+    expect(createTagsFeature({ toggleable: { default: true } }).toggleableDefault).toBe(true);
+  });
+
+  test("toggleable alone (no access/roles) builds a fresh, non-singleton feature", () => {
+    const feature = createTagsFeature({ toggleable: { default: false } });
+    expect(feature).not.toBe(createTagsFeature());
+    // access still defaults when only toggleable is set
+    expect(writeAccess(feature, "create-tag")).toEqual([...DEFAULT_TAG_ROLES]);
+  });
+});
+
 describe("createTagPayloadSchema", () => {
   test("accepts name only", () => {
     expect(createTagPayloadSchema.safeParse({ name: "Kunde Müller" }).success).toBe(true);

package/src/tags/feature.ts

@@ -28,11 +28,27 @@ import { createAssignTagHandler } from "./handlers/assign-tag.write";
 import { createCreateTagHandler } from "./handlers/create-tag.write";
 import { createRemoveTagHandler } from "./handlers/remove-tag.write";
 
-function registerTags(r: FeatureRegistrar<typeof TAGS_FEATURE_NAME>, access: AccessRule): void {
+// Opt-in tier-gating: when set, the feature declares itself r.toggleable so the
+// dispatcher gate + feature-toggles + tier-engine can switch the WHOLE feature
+// (handlers, queries, hooks) on/off per tenant — no host-side hook. `default`
+// is the enablement when no toggle row / tier override exists. For a tier-gated
+// feature use { default: false } (fail-closed) and list the feature name in the
+// entitling tiers' TierMap; tenants below it get every tag path disabled.
+type TagsToggleable = { readonly default: boolean };
+
+function registerTags(
+  r: FeatureRegistrar<typeof TAGS_FEATURE_NAME>,
+  access: AccessRule,
+  toggleable: TagsToggleable | undefined,
+): void {
   r.describe(
-    "Generic, host-agnostic tagging for any entity. Owns two event-sourced entities — the per-tenant `tag` catalog (`read_tags`) and `tag-assignment` join rows keyed by (entityType, entityId) (`read_tag_assignments`) — so tagging adds NO column to the host entity and needs no relational pivot or JOIN. Provides write-handlers `create-tag`, `assign-tag` (idempotent), `remove-tag` (idempotent) and list queries for the catalog and the assignments. Read which tags an entity has, or which entities carry a tag, by listing `tag-assignment` filtered on `entityId` or `tagId` and composing in the read-layer. Every path uses one access rule — adopt the host's model with createTagsFeature({ access: { openToAll: true } }) or pin roles with createTagsFeature({ roles }).",
+    "Generic, host-agnostic tagging for any entity. Owns two event-sourced entities — the per-tenant `tag` catalog (`read_tags`) and `tag-assignment` join rows keyed by (entityType, entityId) (`read_tag_assignments`) — so tagging adds NO column to the host entity and needs no relational pivot or JOIN. Provides write-handlers `create-tag`, `assign-tag` (idempotent), `remove-tag` (idempotent) and list queries for the catalog and the assignments. Read which tags an entity has, or which entities carry a tag, by listing `tag-assignment` filtered on `entityId` or `tagId` and composing in the read-layer. Every path uses one access rule — adopt the host's model with createTagsFeature({ access: { openToAll: true } }) or pin roles with createTagsFeature({ roles }). Pass { toggleable: { default: false } } to make the whole feature tier-gatable via the tier-engine (no host hook).",
   );
 
+  // Tier-gating is a framework concern, not a per-app hook: declaring the
+  // feature toggleable lets tier-engine/feature-toggles cut it per tenant.
+  if (toggleable !== undefined) r.toggleable(toggleable);
+
   r.entity("tag", tagEntity);
   r.entity("tag-assignment", tagAssignmentEntity);
 
@@ -45,7 +61,7 @@ function registerTags(r: FeatureRegistrar<typeof TAGS_FEATURE_NAME>, access: Acc
 }
 
 export const tagsFeature = defineFeature(TAGS_FEATURE_NAME, (r) =>
-  registerTags(r, DEFAULT_TAG_ACCESS),
+  registerTags(r, DEFAULT_TAG_ACCESS, undefined),
 );
 
 export type TagsFeatureOptions = {
@@ -56,6 +72,11 @@ export type TagsFeatureOptions = {
   readonly access?: AccessRule;
   /** Shorthand for { access: { roles } }. Ignored when `access` is set. */
   readonly roles?: readonly string[];
+  /** Make the whole feature tier-gatable: declares r.toggleable so the
+   *  tier-engine/feature-toggles can enable/disable every tag path per tenant.
+   *  `default` applies when no toggle/tier override exists — use { default: false }
+   *  for fail-closed tier-gating. Omit to keep tags always-on (default). */
+  readonly toggleable?: TagsToggleable;
 };
 
 function resolveAccess(opts: TagsFeatureOptions): AccessRule {
@@ -65,11 +86,11 @@ function resolveAccess(opts: TagsFeatureOptions): AccessRule {
 }
 
 // Backwards-compat / options wrapper. Without options returns the module-level
-// singleton (no rebuild). access/roles build a fresh feature-definition.
+// singleton (no rebuild). access/roles/toggleable build a fresh feature-definition.
 export function createTagsFeature(opts: TagsFeatureOptions = {}): typeof tagsFeature {
-  if (opts.access === undefined && opts.roles === undefined) {
+  if (opts.access === undefined && opts.roles === undefined && opts.toggleable === undefined) {
     return tagsFeature;
   }
   const access = resolveAccess(opts);
-  return defineFeature(TAGS_FEATURE_NAME, (r) => registerTags(r, access));
+  return defineFeature(TAGS_FEATURE_NAME, (r) => registerTags(r, access, opts.toggleable));
 }

package/src/user/schema/user.ts

@@ -141,6 +141,17 @@ export const userEntity = createEntity({
     gracePeriodEnd: createTimestampField({
       access: { write: access.privileged },
     }),
+
+    // Replay-Schutz für den anonymen email-Token-Deletion-Flow (#354/1).
+    // Gesetzt von request-deletion-by-email (eine UUID pro Mail-Antrag),
+    // genullt von cancel-deletion. confirm-deletion-by-token faltet diese ID
+    // in die HMAC-Purpose des Tokens — ein nach einem Cancel nachgespieltes
+    // (noch TTL-gültiges) Token verifiziert gegen die genullte/erneuerte ID
+    // nicht mehr. NULL solange kein email-Antrag offen ist.
+    pendingDeletionRequestId: createTextField({
+      maxLength: 36,
+      access: { write: access.privileged },
+    }),
   },
 });
 

package/src/user-data-rights/__tests__/anonymous-deletion.integration.test.ts

@@ -31,6 +31,7 @@ import type { SendDeletionVerificationEmailFn } from "../handlers/request-deleti
 
 const REQUEST_BY_EMAIL = "user-data-rights:write:request-deletion-by-email";
 const CONFIRM_BY_TOKEN = "user-data-rights:write:confirm-deletion-by-token";
+const CANCEL_DELETION = "user-data-rights:write:cancel-deletion";
 const DELETION_SECRET = "test-deletion-secret-0123456789abcdef";
 const VERIFY_URL = "https://app.example.test/delete-account/confirm";
 
@@ -166,8 +167,9 @@ describe("anonymous deletion flow", () => {
     expect(first.status).toBe(200);
     expect(await statusOf()).toBe(USER_STATUS.DeletionRequested);
 
-    // Token ist bewusst replaybar (kein single-use); die Replay-Sicherheit kommt
-    // allein aus dem Active-State-Guard — zweites Confirm trifft non-active → 422.
+    // Pre-cancel-Replay: zweites Confirm trifft den noch-pending User
+    // (DeletionRequested) → der Active-State-Guard schlägt zu → 422. (Den
+    // post-cancel-Replay deckt der requestId-Test darunter ab.)
     const second = await stack.http.raw("POST", "/api/write", {
       type: CONFIRM_BY_TOKEN,
       payload: { token },
@@ -187,6 +189,82 @@ describe("anonymous deletion flow", () => {
     expect(serialized).not.toContain(USER_STATUS.DeletionRequested);
   });
 
+  test("replay-after-cancel (#354/1): Token nach cancel-deletion re-armt NICHT → 422, bleibt Active", async () => {
+    await seedAlice();
+    await stack.http.raw("POST", "/api/write", {
+      type: REQUEST_BY_EMAIL,
+      payload: { email: ALICE_EMAIL },
+    });
+    const token = tokenFromLastVerifyCall();
+
+    // 1. Confirm armt die Grace-Period.
+    expect(
+      (await stack.http.raw("POST", "/api/write", { type: CONFIRM_BY_TOKEN, payload: { token } }))
+        .status,
+    ).toBe(200);
+    expect(await statusOf()).toBe(USER_STATUS.DeletionRequested);
+
+    // 2. User loggt sich (innerhalb der Grace) ein und bricht ab → Active,
+    //    pendingDeletionRequestId genullt.
+    await stack.http.writeOk(CANCEL_DELETION, {}, aliceUser);
+    expect(await statusOf()).toBe(USER_STATUS.Active);
+
+    // 3. Dasselbe, noch TTL-gültige Token nachspielen → die genullte requestId
+    //    lässt die HMAC-Purpose nicht mehr aufgehen → 422, kein re-arm.
+    const replay = await stack.http.raw("POST", "/api/write", {
+      type: CONFIRM_BY_TOKEN,
+      payload: { token },
+    });
+    expect(replay.status).toBe(422);
+    expect(await statusOf()).toBe(USER_STATUS.Active);
+  });
+
+  test("supersede (#354/1): altes Token re-armt NICHT, nachdem ein zweiter Antrag eine neue requestId setzt", async () => {
+    // Der diskriminierende Fall gegen einen presence-only-Check: nach cancel
+    // macht ein FRISCHER Antrag den marker wieder non-null (neue requestId).
+    // Ein presence-only-Guard würde das alte Token jetzt fälschlich akzeptieren;
+    // der requestId-Match lehnt es ab (token1 trägt R1, Row hält R2).
+    await seedAlice();
+
+    await stack.http.raw("POST", "/api/write", {
+      type: REQUEST_BY_EMAIL,
+      payload: { email: ALICE_EMAIL },
+    });
+    const token1 = tokenFromLastVerifyCall();
+
+    await stack.http.raw("POST", "/api/write", {
+      type: CONFIRM_BY_TOKEN,
+      payload: { token: token1 },
+    });
+    await stack.http.writeOk(CANCEL_DELETION, {}, aliceUser);
+    expect(await statusOf()).toBe(USER_STATUS.Active);
+
+    // Zweiter Antrag → neue requestId R2 auf der Row + token2.
+    verifyCalls.length = 0;
+    await stack.http.raw("POST", "/api/write", {
+      type: REQUEST_BY_EMAIL,
+      payload: { email: ALICE_EMAIL },
+    });
+    const token2 = tokenFromLastVerifyCall();
+    expect(token2).not.toBe(token1);
+
+    // Altes token1 (R1) gegen Row mit R2 → bad_signature → 422, kein re-arm.
+    const replayOld = await stack.http.raw("POST", "/api/write", {
+      type: CONFIRM_BY_TOKEN,
+      payload: { token: token1 },
+    });
+    expect(replayOld.status).toBe(422);
+    expect(await statusOf()).toBe(USER_STATUS.Active);
+
+    // Gegenprobe: das aktuelle token2 (R2) armt regulär.
+    const confirmNew = await stack.http.raw("POST", "/api/write", {
+      type: CONFIRM_BY_TOKEN,
+      payload: { token: token2 },
+    });
+    expect(confirmNew.status).toBe(200);
+    expect(await statusOf()).toBe(USER_STATUS.DeletionRequested);
+  });
+
   test("request-by-email für nicht-existente Email → success, KEINE Mail (enumeration-safe)", async () => {
     await seedAlice();
     const res = await stack.http.raw("POST", "/api/write", {
@@ -221,7 +299,19 @@ describe("anonymous deletion flow", () => {
 
   test("confirm mit falsch-signiertem Token → 422", async () => {
     await seedAlice();
-    const { token } = signDeletionToken(aliceUser.id, 60, "the-wrong-secret-totally-different");
+    // Erst einen echten Antrag stellen, damit eine requestId auf der Row liegt
+    // — sonst greift schon der no-outstanding-request-Guard und der Bad-
+    // Signature-Pfad würde nie erreicht.
+    await stack.http.raw("POST", "/api/write", {
+      type: REQUEST_BY_EMAIL,
+      payload: { email: ALICE_EMAIL },
+    });
+    const { token } = signDeletionToken(
+      aliceUser.id,
+      "forged-request-id",
+      60,
+      "the-wrong-secret-totally-different",
+    );
     const res = await stack.http.raw("POST", "/api/write", {
       type: CONFIRM_BY_TOKEN,
       payload: { token },
@@ -282,7 +372,7 @@ describe("anonymous deletion flow — not configured (kein Secret)", () => {
   });
 
   test("confirm ohne Secret → 422", async () => {
-    const { token } = signDeletionToken(aliceUser.id, 60, DELETION_SECRET);
+    const { token } = signDeletionToken(aliceUser.id, "req-id", 60, DELETION_SECRET);
     const res = await bareStack.http.raw("POST", "/api/write", {
       type: CONFIRM_BY_TOKEN,
       payload: { token },

package/src/user-data-rights/deletion-token.ts

@@ -4,13 +4,13 @@
 // flow, so it reuses the same self-contained token mechanism (no DB row, no
 // Redis: the userId + expiry are baked into the signed token).
 //
-// The token is NOT single-use: replaying it on a still-pending (non-active)
-// user is a no-op (confirm hits non-active → cannot_process_deletion). That
-// idempotency is only bounded though — after a cancel-deletion the user is
-// active again and a still-valid token re-arms a second grace period. The
-// replay window is bounded by the TTL; the full fix (per-request requestId
-// bound into the token + the user row, nulled on cancel) is deferred as review
-// finding #354/1 (needs a shared user-entity migration).
+// Replay-after-cancel (#354/1): the per-request `requestId` is folded INTO the
+// HMAC purpose (`deletion-request:<requestId>`), not carried in the token body.
+// The same id is stored on the user row when the request is minted and nulled
+// on cancel. confirm recomputes the HMAC with the row's CURRENT id, so a token
+// from a cancelled cycle (row id nulled) or a superseded one (row holds a newer
+// id) fails verification — the bounded-TTL replay window is closed without
+// touching the shared signToken/verifyToken primitive.
 
 import type { Temporal } from "temporal-polyfill";
 import { signToken, verifyToken } from "../auth-email-password";
@@ -21,21 +21,42 @@ export type VerifyResult =
   | { readonly ok: true; readonly userId: string; readonly expiresAtMs: number }
   | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
 
-// @wrapper-known semantic-alias
+function deletionPurpose(requestId: string): string {
+  return `${DELETION_REQUEST_PURPOSE}:${requestId}`;
+}
+
 export function signDeletionToken(
   userId: string,
+  requestId: string,
   ttlMinutes: number,
   secret: string,
   now?: Temporal.Instant,
 ): { token: string; expiresAt: Temporal.Instant } {
-  return signToken(userId, DELETION_REQUEST_PURPOSE, ttlMinutes, secret, now);
+  return signToken(userId, deletionPurpose(requestId), ttlMinutes, secret, now);
 }
 
-// @wrapper-known semantic-alias
 export function verifyDeletionToken(
   token: string,
+  requestId: string,
   secret: string,
   now?: Temporal.Instant,
 ): VerifyResult {
-  return verifyToken(token, DELETION_REQUEST_PURPOSE, secret, now);
+  return verifyToken(token, deletionPurpose(requestId), secret, now);
+}
+
+// Reads the userId from the token body WITHOUT verifying the HMAC — used only
+// to look up the row's current requestId, which is itself an input to the
+// verification below. The signature is still the gate; this peek never grants
+// trust. Token format is `<userId>.<expiresAtMs>.<sig>`.
+//
+// Mirrors verifyToken's structural malformed-checks so an obviously-bogus token
+// returns null here (→ generic reject) instead of reaching the DB lookup.
+export function peekDeletionTokenUserId(token: string): string | null {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  const [userId, expiresAtRaw, sig] = parts;
+  if (!userId || !expiresAtRaw || !sig) return null;
+  const expiresAtMs = Number(expiresAtRaw);
+  if (!Number.isFinite(expiresAtMs) || String(expiresAtMs) !== expiresAtRaw) return null;
+  return userId;
 }

package/src/user-data-rights/handlers/cancel-deletion.write.ts

@@ -67,6 +67,10 @@ export const cancelDeletionWrite = defineWriteHandler({
       {
         status: USER_STATUS.Active,
         gracePeriodEnd: null,
+        // #354/1: schließt das replay-after-cancel-Fenster — ein noch
+        // TTL-gültiges email-Token verifiziert gegen die genullte requestId
+        // nicht mehr und kann keine zweite Grace-Period armen.
+        pendingDeletionRequestId: null,
       },
       { id: event.user.id },
     );

package/src/user-data-rights/handlers/confirm-deletion-by-token.write.ts

@@ -1,8 +1,9 @@
-import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineWriteHandler, type HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
-import { USER_STATUS } from "../../user";
-import { verifyDeletionToken } from "../deletion-token";
+import { USER_STATUS, userTable } from "../../user";
+import { peekDeletionTokenUserId, verifyDeletionToken } from "../deletion-token";
 import { startDeletionGracePeriod } from "./deletion-grace-period";
 
 export type ConfirmDeletionByTokenOptions = {
@@ -17,18 +18,35 @@ function invalidToken(): UnprocessableError {
   });
 }
 
+// userId stammt aus dem noch-unverifizierten Token (Angreifer-Eingabe). Ein
+// fehlgeschlagener Lookup — z.B. eine typfremde id auf einer int/uuid-Spalte —
+// darf nicht als 500 durchschlagen; null behandelt der Caller wie "kein offener
+// Antrag" (generischer 422). Die HMAC-Prüfung bleibt der eigentliche Gate.
+async function readPendingDeletionRequestId(
+  ctx: HandlerContext,
+  userId: string,
+): Promise<string | null> {
+  try {
+    const row = await fetchOne<{ pendingDeletionRequestId: string | null }>(ctx.db.raw, userTable, {
+      id: userId,
+    });
+    return row?.["pendingDeletionRequestId"] ?? null;
+  } catch {
+    return null;
+  }
+}
+
 // Anonymer Apex-Flow Schritt 2: Verify-Link-Target. Verifiziert das
 // HMAC-Token, extrahiert die userId und startet die Grace-Period über die
 // geteilte Logik.
 //
-// Idempotenz ist NUR bounded: ein zweites Confirm auf einen noch-pending
-// (DeletionRequested) User trifft non-active → cannot_process_deletion. ABER
-// nach einem cancel-deletion (status → Active, gracePeriodEnd → null) ist der
-// User wieder aktiv; ein noch-gültiges Token (TTL aus request-deletion-by-email)
-// re-armt dann eine zweite Grace-Period (replay-after-cancel). Das Risiko ist
-// durch die Token-TTL begrenzt; der vollständige Fix (requestId pro Request im
-// Token + auf der User-Row, vom cancel genullt) ist als review-finding #354/1
-// deferred — er braucht eine Migration der geteilten user-Entity.
+// Replay-Schutz (#354/1): die requestId der Row ist Teil des Verify-Keys. Wir
+// lesen sie über die (unverifizierte, nur-Lookup) userId aus dem Token, lehnen
+// einen fehlenden Eintrag ab und verifizieren das Token gegen die CURRENT
+// requestId. Ein zweites Confirm auf einen noch-pending User trifft zudem
+// non-active → cannot_process_deletion. Nach einem cancel-deletion (status →
+// Active, pendingDeletionRequestId → null) schlägt ein nachgespieltes Token an
+// der genullten/erneuerten requestId fehl — kein re-arm mehr.
 export function createConfirmDeletionByTokenHandler(opts: ConfirmDeletionByTokenOptions = {}) {
   return defineWriteHandler({
     name: "confirm-deletion-by-token",
@@ -38,7 +56,22 @@ export function createConfirmDeletionByTokenHandler(opts: ConfirmDeletionByToken
     handler: async (event, ctx) => {
       if (!opts.deletionTokenSecret) return writeFailure(invalidToken());
 
-      const verified = verifyDeletionToken(event.payload.token, opts.deletionTokenSecret);
+      const peekedUserId = peekDeletionTokenUserId(event.payload.token);
+      if (!peekedUserId) return writeFailure(invalidToken());
+
+      // Die requestId der Row ist Teil des Verify-Keys (HMAC-Purpose). Kein
+      // offener Antrag (null) → das Token gehört zu einem abgebrochenen Zyklus
+      // → Reject ohne weitere Signal-Preisgabe (gleicher generischer 422). Der
+      // peekedUserId ist unverifizierte Angreifer-Eingabe — ein Lookup-Fehler
+      // (z.B. typfremde id) wird zu demselben generischen 422, nie zu einem 500.
+      const requestId = await readPendingDeletionRequestId(ctx, peekedUserId);
+      if (!requestId) return writeFailure(invalidToken());
+
+      const verified = verifyDeletionToken(
+        event.payload.token,
+        requestId,
+        opts.deletionTokenSecret,
+      );
       if (!verified.ok) return writeFailure(invalidToken());
 
       const res = await startDeletionGracePeriod(ctx, verified.userId, event.user.tenantId);

package/src/user-data-rights/handlers/request-deletion-by-email.write.ts

@@ -1,4 +1,4 @@
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { fetchOne, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { USER_STATUS, userTable } from "../../user";
@@ -75,8 +75,20 @@ export function createRequestDeletionByEmailHandler(opts: RequestDeletionByEmail
         return success;
       }
 
+      // Replay-Schutz (#354/1): pro Antrag eine frische requestId, die auf der
+      // user-Row landet und in die Token-HMAC-Purpose gefaltet wird. cancel
+      // nullt sie → ein nach Cancel nachgespieltes Token verifiziert nicht mehr.
+      const requestId = crypto.randomUUID();
+      await updateMany(
+        ctx.db.raw,
+        userTable,
+        { pendingDeletionRequestId: requestId },
+        { id: userRow["id"] },
+      );
+
       const { token, expiresAt } = signDeletionToken(
         userRow["id"],
+        requestId,
         DELETION_VERIFY_TTL_MINUTES,
         opts.deletionTokenSecret,
       );