@cosmicdrift/kumiko-bundled-features 0.286.0 → 0.287.0

package/src/shared/signed-token.ts

@@ -0,0 +1,101 @@
+// HMAC-signed single-purpose tokens for out-of-band auth flows
+// (password-reset, email-verification, future: magic-link).
+//
+// Format: <userId>.<expiresAtMs>.<hmac-base64url>
+//
+// The `purpose` is mixed INTO the HMAC input so a token minted for one
+// purpose (e.g. password-reset) can't be replayed against an endpoint that
+// expects another (e.g. verify-email), even if the caller knows the
+// userId and a valid expiry. Purpose is NOT carried in the token body —
+// verify() takes the purpose as argument and recomputes.
+//
+// Timing-safe comparison on verify so a valid-length forgery can't leak
+// signal through a short-circuit.
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { Temporal } from "temporal-polyfill";
+
+export type VerifyResult =
+  | { readonly ok: true; readonly userId: string; readonly expiresAtMs: number }
+  | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
+
+function sign(input: string, secret: string): string {
+  return createHmac("sha256", secret).update(input).digest("base64url");
+}
+
+function payload(purpose: string, userId: string, expiresAtMs: number): string {
+  return `${purpose}:${userId}.${expiresAtMs}`;
+}
+
+export function signToken(
+  userId: string,
+  purpose: string,
+  ttlMinutes: number,
+  secret: string,
+  now: Temporal.Instant = Temporal.Now.instant(),
+): { token: string; expiresAt: Temporal.Instant } {
+  const expiresAt = now.add({ minutes: ttlMinutes });
+  const expiresAtMs = expiresAt.epochMilliseconds;
+  const signature = sign(payload(purpose, userId, expiresAtMs), secret);
+  return {
+    token: `${userId}.${expiresAtMs}.${signature}`,
+    expiresAt,
+  };
+}
+
+// Reads the subject out of the token body WITHOUT checking the HMAC. Only
+// safe as a lookup key for something that is itself an input to the
+// verification below — the signature stays the gate. Mirrors verifyToken's
+// structural checks, which is why it lives next to it: a token this rejects
+// must never reach a DB lookup.
+export function peekTokenSubject(token: string): string | null {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  const [subject, expiresAtRaw, sig] = parts;
+  if (!subject || !expiresAtRaw || !sig) return null;
+  const expiresAtMs = Number(expiresAtRaw);
+  if (!Number.isFinite(expiresAtMs) || String(expiresAtMs) !== expiresAtRaw) return null;
+  return subject;
+}
+
+export function verifyToken(
+  token: string,
+  purpose: string,
+  secret: string,
+  now: Temporal.Instant = Temporal.Now.instant(),
+): VerifyResult {
+  const parts = token.split(".");
+  if (parts.length !== 3) return { ok: false, reason: "malformed" };
+  const [userId, expiresAtRaw, providedSig] = parts;
+  if (!userId || !expiresAtRaw || !providedSig) return { ok: false, reason: "malformed" };
+
+  const expiresAtMs = Number(expiresAtRaw);
+  if (!Number.isFinite(expiresAtMs) || String(expiresAtMs) !== expiresAtRaw) {
+    return { ok: false, reason: "malformed" };
+  }
+
+  const expected = sign(payload(purpose, userId, expiresAtMs), secret);
+  const expectedBuf = Buffer.from(expected, "base64url");
+  const providedBuf = Buffer.from(providedSig, "base64url");
+  // Length mismatch fails BEFORE timingSafeEqual, which throws on different
+  // lengths — but that throw itself leaks via timing. Explicit length check
+  // keeps the path uniform.
+  if (expectedBuf.length !== providedBuf.length) return { ok: false, reason: "bad_signature" };
+  if (!timingSafeEqual(expectedBuf, providedBuf)) return { ok: false, reason: "bad_signature" };
+
+  if (Temporal.Instant.compare(now, Temporal.Instant.fromEpochMilliseconds(expiresAtMs)) > 0) {
+    return { ok: false, reason: "expired" };
+  }
+
+  // expiresAtMs surfaces so callers (burn-store TTL, telemetry, …) don't
+  // have to re-parse the token themselves.
+  return { ok: true, userId, expiresAtMs };
+}
+
+// Canonical purposes baked into the framework. Features that introduce new
+// flows extend this set (or just pass an inline string).
+export const TokenPurpose = {
+  passwordReset: "reset",
+  emailVerification: "verify",
+  accountUnlock: "unlock",
+} as const;

package/src/tenant/seeding.ts

@@ -234,6 +234,10 @@ export async function seedTenant(
     tdb,
   );
   if (!result.isSuccess) {
+    // Same idempotency case as the stream-version check above, only detected
+    // one instruction later: a dispatcher cycle appended to the stream between
+    // that read and this create. Both paths return without firing postSave.
+    if (result.error.code === "version_conflict") return { id: options.id };
     throw new Error(
       `seedTenant failed: ${result.error.code} — ${JSON.stringify(result.error.details ?? {})}`,
     );

package/src/user-data-rights/__tests__/deletion-token-compat.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test";
+import { Temporal } from "temporal-polyfill";
+import { signToken } from "../../shared";
+import { redeemDeletionToken, signDeletionToken } from "../deletion-token";
+
+const SECRET = "deletion-token-compat-secret";
+const USER_ID = "user-7";
+const REQUEST_ID = "req-99";
+const NOW = Temporal.Instant.fromEpochMilliseconds(1_700_000_000_000);
+
+// Deletion tokens sit in mails that are already out. Moving the minting onto
+// shared/row-bound-grant must not change a single byte of them, so this pins
+// the wire format against the formula the hand-rolled version used:
+// signToken(userId, `deletion-request:${requestId}`, ...).
+describe("deletion token wire format", () => {
+  test("a token minted with the pre-refactor formula still redeems", async () => {
+    const legacy = signToken(USER_ID, `deletion-request:${REQUEST_ID}`, 30, SECRET).token;
+
+    const result = await redeemDeletionToken({
+      token: legacy,
+      secret: SECRET,
+      loadPendingRequestId: async () => REQUEST_ID,
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.ok && result.subject).toBe(USER_ID);
+  });
+
+  test("minting produces exactly the pre-refactor bytes", () => {
+    const minted = signDeletionToken(USER_ID, REQUEST_ID, 30, SECRET, NOW);
+    const legacy = signToken(USER_ID, `deletion-request:${REQUEST_ID}`, 30, SECRET, NOW);
+
+    expect(minted.token).toBe(legacy.token);
+  });
+});

package/src/user-data-rights/__tests__/run-export-jobs.integration.test.ts

@@ -24,6 +24,7 @@ import {
   createInMemoryFileProvider,
   type FileStorageProvider,
 } from "@cosmicdrift/kumiko-framework/files";
+import type { MetricsHandle } from "@cosmicdrift/kumiko-framework/observability";
 import {
   createTestUser,
   setupTestStack,
@@ -43,7 +44,7 @@ import { createSessionsFeature, userSessionEntity } from "../../sessions";
 import { tenantMembershipsTable } from "../../tenant";
 import { createUserFeature, USER_STATUS, userEntity, userTable } from "../../user";
 import { createUserDataRightsFeature } from "../feature";
-import { runExportJobs } from "../run-export-jobs";
+import { EXPORT_CLEANUP_BACKLOG_AGE_METRIC, runExportJobs } from "../run-export-jobs";
 import { exportDownloadTokenEntity, exportDownloadTokensTable } from "../schema/download-token";
 import { EXPORT_JOB_STATUS, exportJobEntity, exportJobsTable } from "../schema/export-job";
 import { hashDownloadToken } from "../token-helpers";
@@ -133,6 +134,20 @@ function buildProvider(tenantId: string): Promise<FileStorageProvider> {
   return Promise.resolve(p);
 }
 
+// Typed fake standing in for the ctx.meter-backed MetricsHandle feature.ts
+// builds for the real cron — records `set()` calls without a Meter/registry.
+function createRecordingMetricsHandle(): MetricsHandle & { readonly values: Map<string, number> } {
+  const values = new Map<string, number>();
+  return {
+    values,
+    inc: () => {},
+    observe: () => {},
+    set: (name, value) => {
+      values.set(name, value);
+    },
+  };
+}
+
 // Seedet einen pending Job via realen request-export-Handler — echter
 // ES-Pfad (crud.create emittiert event "export-job.created"), nicht
 // direct-INSERT. Direct-INSERT wuerde stream-version=0/row-version=1
@@ -444,6 +459,80 @@ describe("runExportJobs :: storage-cleanup", () => {
   });
 });
 
+describe("runExportJobs :: export-cleanup backlog metric", () => {
+  test("done-Job mit abgelaufener TTL + weiterhin gesetztem downloadStorageKey → Metrik > 0", async () => {
+    const jobId = await seedPendingJob();
+    const T = getTemporal();
+    const longAgo = T.Instant.fromEpochMilliseconds(Date.now() - 365 * 24 * 60 * 60 * 1000);
+    const storageKey = `exports/${tenantA}/${jobId}.zip`;
+    const provider = await buildProvider(tenantA);
+    await provider.write(storageKey, new Uint8Array([7, 8, 9]));
+
+    await updateRows(
+      stack.db,
+      exportJobsTable,
+      {
+        status: EXPORT_JOB_STATUS.Done,
+        startedAt: longAgo,
+        completedAt: longAgo,
+        downloadStorageKey: storageKey,
+        expiresAt: longAgo,
+      },
+      { id: jobId },
+    );
+
+    const metrics = createRecordingMetricsHandle();
+    await runExportJobs({
+      db: stack.db,
+      registry: stack.registry,
+      buildStorageProvider: async () => ({
+        ...provider,
+        delete: async () => {
+          throw new Error("synthetic storage delete failure");
+        },
+      }),
+      now: NOW(),
+      metrics,
+    });
+
+    expect(metrics.values.get(EXPORT_CLEANUP_BACKLOG_AGE_METRIC)).toBeGreaterThan(0);
+  });
+
+  test("done-Job wird erfolgreich cleaned → Metrik ist 0", async () => {
+    const jobId = await seedPendingJob();
+    const T = getTemporal();
+    const longAgo = T.Instant.fromEpochMilliseconds(Date.now() - 365 * 24 * 60 * 60 * 1000);
+    const storageKey = `exports/${tenantA}/${jobId}.zip`;
+    const provider = await buildProvider(tenantA);
+    await provider.write(storageKey, new Uint8Array([1, 2, 3]));
+
+    await updateRows(
+      stack.db,
+      exportJobsTable,
+      {
+        status: EXPORT_JOB_STATUS.Done,
+        startedAt: longAgo,
+        completedAt: longAgo,
+        downloadStorageKey: storageKey,
+        expiresAt: longAgo,
+      },
+      { id: jobId },
+    );
+
+    const metrics = createRecordingMetricsHandle();
+    const result = await runExportJobs({
+      db: stack.db,
+      registry: stack.registry,
+      buildStorageProvider: buildProvider,
+      now: NOW(),
+      metrics,
+    });
+
+    expect(result.cleanedJobIds).toContain(jobId);
+    expect(metrics.values.get(EXPORT_CLEANUP_BACKLOG_AGE_METRIC)).toBe(0);
+  });
+});
+
 describe("runExportJobs :: idempotency", () => {
   test("zweiter Run nach done ist no-op fuer den selben Job", async () => {
     const jobId = await seedPendingJob();

package/src/user-data-rights/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.287.0",
+    "type": "improvement",
+    "title": "export-cleanup cron now emits an export_cleanup_backlog_age gauge to surface stalled runs",
+    "detail": "storageCleanupPass deletes expired export bundles via provider.delete, but the storage provider only exposes list() (no timestamps), so a silent failure left unencrypted PII bundles sitting in the bucket with no signal. runExportJobs now accepts an optional MetricsHandle and, after the cleanup loop, reports the age in seconds of the oldest done-status job whose expiresAt+grace has passed while downloadStorageKey is still set (0 if none) via the new EXPORT_CLEANUP_BACKLOG_AGE_METRIC (\"export_cleanup_backlog_age\", a gauge — no _total/_seconds suffix per validateMetricName, unit: \"seconds\" carried in the r.metric() definition instead). feature.ts's job handler builds the handle itself with createMetricsHandle(ctx.meter, \"user-data-rights\") since JobContext has no bound ctx.metrics (that only exists on HandlerContext, built per write/query dispatch) — falls back to createNoopMetricsHandle() when ctx.meter is unset. Metric emission is wrapped in try/catch so an observability hiccup never fails an otherwise-successful cleanup pass. Scope is deliberately done-status only; failed-status cleanup candidates have no expiresAt/TTL."
+  },
+  {
+    "version": "0.287.0",
+    "type": "fix",
+    "title": "GDPR forget only hard-deletes files that are PII of the forgotten person",
+    "detail": "fileRefDeleteHook picked rows via insertedById (who uploaded the file) and treated every matched row the same on strategy=\"delete\", so forgetting an uploader hard-deleted third-party business files they had merely uploaded (e.g. a dealer's vehicle photos uploaded by an employee). FileFieldDef/ImageFieldDef/FilesFieldDef/ImagesFieldDef now support \"& ResolvedPiiFlags\" like every other field type (createFileField/createImageField/createFilesField/createImagesField thread personal/reason through expandPersonalAnnotations), and fileRefDeleteHook's strategy=\"delete\" branch splits rows per-row via the new isPersonalFileRow/isPersonalPiiField predicates: pii/userOwned/recordOwned fields take the existing hard-delete path (storageProvider.delete() + derivatives + row), every other row (explicit personal:false, tenantOwned, subjectRef, no annotation, or an unresolvable entity/field) goes through severPersonLink instead, same as the existing strategy=\"anonymize\" path. Unattached uploads (no entityType/fieldName) still hard-delete. Derivatives have no own file_refs row, so they keep following their original's decision (the #2461 \"GDPR derivatives survive forget\" test stays green). POST /files now resolves entityType/fieldName against the registry and rejects the upload with 400 when they're set but don't resolve to a real field, closing the gap that let a client attach a file to a field the forget-hook could never look up; both unset (unattached upload) still passes. No new column or migration — the decision uses the entityType/fieldName file_refs already stores."
+  },
   {
     "version": "0.285.2",
     "type": "fix",

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

@@ -1,62 +1,56 @@
-// Thin wrapper around the shared HMAC-signed-token primitive, pinning the
-// purpose to "deletion-request". Mirrors auth-email-password/reset-token.ts —
-// email-verified account deletion is an auth-adjacent proof-of-email-ownership
-// flow, so it reuses the same self-contained token mechanism (no DB row, no
-// Redis: the userId + expiry are baked into the signed token).
+// Email-verified account deletion, expressed as a row-bound grant: the
+// subject is the user, the anchor is the pending request id stored on the
+// user row. Minting and verification both run through
+// shared/row-bound-grant, so a token from a cancelled cycle (id nulled) or a
+// superseded one (row holds a newer id) fails verification — see #354/1.
 //
-// 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.
+// The purpose string and the anchoring are unchanged from the hand-rolled
+// version this replaced, so tokens stay byte-compatible.
 
 import type { Temporal } from "temporal-polyfill";
-import { signToken, verifyToken } from "../auth-email-password";
+import { type RowBoundGrantResult, redeemRowBoundGrant, signRowBoundGrant } from "../shared";
 
 const DELETION_REQUEST_PURPOSE = "deletion-request";
 
-export type VerifyResult =
-  | { readonly ok: true; readonly userId: string; readonly expiresAtMs: number }
-  | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
-
-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, deletionPurpose(requestId), ttlMinutes, secret, now);
+): { readonly token: string; readonly expiresAt: Temporal.Instant } {
+  return signRowBoundGrant({
+    subject: userId,
+    purpose: DELETION_REQUEST_PURPOSE,
+    anchor: requestId,
+    ttlMinutes,
+    secret,
+    now,
+  });
 }
 
-export function verifyDeletionToken(
-  token: string,
-  requestId: string,
-  secret: string,
-  now?: Temporal.Instant,
-): VerifyResult {
-  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;
+export function redeemDeletionToken(args: {
+  readonly token: string;
+  readonly secret: string | undefined;
+  readonly loadPendingRequestId: (userId: string) => Promise<string | null>;
+  readonly now?: Temporal.Instant;
+}): Promise<RowBoundGrantResult> {
+  return redeemRowBoundGrant({
+    token: args.token,
+    purpose: DELETION_REQUEST_PURPOSE,
+    secret: args.secret,
+    loadAnchor: args.loadPendingRequestId,
+    commitAnchor: {
+      unsafeSkip: {
+        reason:
+          "pendingDeletionRequestId may only be changed through updateUserLifecycle — a " +
+          "conditional UPDATE would bypass the user.updated event and lose the field on a " +
+          "projection rebuild (see update-user-lifecycle.ts). The concurrent-redeem window " +
+          "this leaves open predates row-bound grants: startDeletionGracePeriod already " +
+          "read-then-writes the Active check. Closing it needs an atomic lifecycle " +
+          "transition, which is its own change.",
+      },
+    },
+    now: args.now,
+  });
 }

package/src/user-data-rights/feature.ts

@@ -7,6 +7,10 @@ import {
   i18nKey,
   SYSTEM_USER_ID,
 } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createMetricsHandle,
+  createNoopMetricsHandle,
+} from "@cosmicdrift/kumiko-framework/observability";
 import { validateGdprHookCompleteness, validateGdprPiiHookCoverage } from "./boot-checks";
 import {
   EXPORT_SECTION_EXTENSION_NAME,
@@ -49,6 +53,7 @@ import { makeTenantMailTransportResolver } from "./lib/mail-transport-resolver";
 import { resolveAppTenantModel } from "./lib/resolve-tenant-model";
 import { makeTenantStorageProviderResolver } from "./lib/storage-provider-resolver";
 import {
+  EXPORT_CLEANUP_BACKLOG_AGE_METRIC,
   runExportJobs,
   type SendExportFailedEmailFn,
   type SendExportReadyEmailFn,
@@ -528,6 +533,21 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
       },
     });
 
+    // Surfaces a stalled export-cleanup cron: if the daily
+    // pass stops running, done-status export bundles keep sitting in
+    // storage past their TTL+grace with downloadStorageKey still set
+    // (unencrypted PII at rest). Emitted from the same job that cleans up
+    // (see handler below) — a dead cron makes the metric go stale too,
+    // which an `absent()` alert catches without a second liveness signal.
+    // Scope: Done-status bundles only — Failed-status cleanup candidates
+    // have no expiresAt/TTL (immediate cleanup, see storageCleanupPass).
+    r.metric(EXPORT_CLEANUP_BACKLOG_AGE_METRIC, {
+      type: "gauge",
+      unit: "seconds",
+      description:
+        "Age in seconds of the oldest done-status export bundle whose expiresAt+grace has passed but downloadStorageKey is still set. 0 when the storage-cleanup pass has no backlog.",
+    });
+
     // S2.U3 Atom 3b — Worker fuer Async Export-Pipeline. Cron-getriggert.
     const RUN_EXPORT_JOBS_REASON = "processes pending export jobs across every tenant";
     r.job({
@@ -548,6 +568,12 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
           RUN_EXPORT_JOBS_REASON,
         ) as import("@cosmicdrift/kumiko-framework/db").DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
         const exportRegistry = ctx.registry;
+        // JobContext carries ctx.meter (raw), not ctx.metrics — that bound
+        // handle only exists on HandlerContext (built per write/query call
+        // in dispatch-shared.ts). Build the same handle explicitly here.
+        const exportMetrics = ctx.meter
+          ? createMetricsHandle(ctx.meter, "user-data-rights")
+          : createNoopMetricsHandle();
 
         // C6 — ohne eigene send*Email-Opts aber mit gemountetem mail-transport
         // versendet der Cron die Export-Notifications selbst (Default-Templates).
@@ -612,6 +638,7 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
           }),
           escapeHatchAuditSink: ctx._escapeHatchAuditSink,
           actor: ctx.systemUser.id,
+          metrics: exportMetrics,
         });
       },
     });

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

@@ -7,7 +7,7 @@ import {
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { USER_STATUS, userTable } from "../../user";
-import { peekDeletionTokenUserId, verifyDeletionToken } from "../deletion-token";
+import { redeemDeletionToken } from "../deletion-token";
 import { startDeletionGracePeriod } from "./deletion-grace-period";
 
 export type ConfirmDeletionByTokenOptions = {
@@ -66,24 +66,14 @@ export function createConfirmDeletionByTokenHandler(opts: ConfirmDeletionByToken
     agent: { expose: false },
     rateLimit: { per: "ip", limit: 10, windowSeconds: 60 },
     handler: async (event, ctx) => {
-      if (!opts.deletionTokenSecret) return writeFailure(invalidToken());
-
-      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,
-      );
+      // The row's requestId is part of the verify key, so a token from a
+      // cancelled or superseded cycle fails. Every error path ends in the same
+      // generic 422.
+      const verified = await redeemDeletionToken({
+        token: event.payload.token,
+        secret: opts.deletionTokenSecret,
+        loadPendingRequestId: (userId) => readPendingDeletionRequestId(ctx, userId),
+      });
       if (!verified.ok) return writeFailure(invalidToken());
 
       // @cast-boundary engine-payload — queryAs returns unknown, narrowed to
@@ -95,7 +85,7 @@ export function createConfirmDeletionByTokenHandler(opts: ConfirmDeletionByToken
       )) as { profile: { userRights: { gracePeriod: DurationSpec } } };
       const res = await startDeletionGracePeriod(
         ctx,
-        verified.userId,
+        verified.subject,
         profile.profile.userRights.gracePeriod,
         ctx.db.unsafeRaw("appends the user lifecycle event on the SYSTEM_TENANT_ID user stream"),
       );

package/src/user-data-rights/run-export-jobs.ts

@@ -61,6 +61,7 @@ import {
   tenantExportPrefix,
   type ZipEntry,
 } from "@cosmicdrift/kumiko-framework/files";
+import type { MetricsHandle } from "@cosmicdrift/kumiko-framework/observability";
 import type { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import { resolveProfileForTenant } from "../compliance-profiles";
 import { decryptStoredPii } from "../shared";
@@ -73,6 +74,12 @@ import { generateDownloadToken } from "./token-helpers";
 
 type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
 
+// Gauge short name (feature.ts registers it via r.metric + resolves ctx.meter
+// into a MetricsHandle — jobs get no bound ctx.metrics, see feature.ts).
+// No "_seconds"/"_total" suffix: validateMetricName rejects both on a gauge.
+// Unit lives in the r.metric() `unit: "seconds"` declaration instead.
+export const EXPORT_CLEANUP_BACKLOG_AGE_METRIC = "export_cleanup_backlog_age";
+
 const crud = createEventStoreExecutor(exportJobsTable, exportJobEntity, {
   entityName: "export-job",
 });
@@ -165,6 +172,12 @@ export interface RunExportJobsArgs {
   // systemUser.id); threaded into runUserExport's per-hook TenantDb.
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
   readonly actor?: string;
+
+  /**
+   * Reports EXPORT_CLEANUP_BACKLOG_AGE_METRIC after the storage-cleanup
+   * pass. Optional so callers without an observability provider still work.
+   */
+  readonly metrics?: MetricsHandle;
 }
 
 export interface ExportJobError {
@@ -302,6 +315,7 @@ export async function runExportJobs(args: RunExportJobsArgs): Promise<RunExportJ
     db,
     buildStorageProvider,
     now,
+    metrics: args.metrics,
   });
 
   return {
@@ -621,8 +635,9 @@ async function storageCleanupPass(args: {
   db: DbConnection;
   buildStorageProvider: (tenantId: TenantId) => Promise<FileStorageProvider>;
   now: Instant;
+  metrics?: MetricsHandle;
 }): Promise<readonly string[]> {
-  const { db, buildStorageProvider, now } = args;
+  const { db, buildStorageProvider, now, metrics } = args;
 
   // Zwei Cleanup-Pfade:
   //
@@ -659,6 +674,13 @@ async function storageCleanupPass(args: {
   );
 
   const cleaned: string[] = [];
+  // Done-status candidates past expiresAt+grace, keyed by that due-instant —
+  // used below to report how far cleanup has fallen behind if a candidate
+  // is still standing (delete threw, or the version-checked null-out lost
+  // a race) once the pass is done. Failed-status jobs have no expiresAt
+  // (immediate cleanup, no TTL) so they're out of scope for this signal —
+  // see EXPORT_CLEANUP_BACKLOG_AGE_METRIC's r.metric() description.
+  const overdueDoneCleanupAfterMs = new Map<string, number>();
   for (const c of candidates) {
     if (!c.downloadStorageKey) continue;
 
@@ -674,6 +696,7 @@ async function storageCleanupPass(args: {
         c.expiresAt.epochMilliseconds +
         profile.profile.userRights.exportStorageCleanupGraceHours * 60 * 60 * 1000;
       if (now.epochMilliseconds < cleanupAfter) continue;
+      overdueDoneCleanupAfterMs.set(c.id, cleanupAfter);
     }
     // Failed-Job-Branch: kein TTL-Check, sofort cleanup.
 
@@ -696,9 +719,54 @@ async function storageCleanupPass(args: {
     );
     if (result.isSuccess) cleaned.push(c.id);
   }
+
+  reportOldestOverdueAge(metrics, overdueDoneCleanupAfterMs, cleaned, now);
+
   return cleaned;
 }
 
+// Seconds since the longest-overdue Done-status bundle should have been
+// deleted (expiresAt+grace passed) but still isn't — 0 when the pass
+// cleaned everything that was due, or nothing was due.
+function oldestOverdueAgeSeconds(
+  overdueDoneCleanupAfterMs: ReadonlyMap<string, number>,
+  cleanedIds: readonly string[],
+  now: Instant,
+): number {
+  const cleaned = new Set(cleanedIds);
+  let oldestAgeSeconds = 0;
+  for (const [id, cleanupAfterMs] of overdueDoneCleanupAfterMs) {
+    if (cleaned.has(id)) continue;
+    const ageSeconds = (now.epochMilliseconds - cleanupAfterMs) / 1000;
+    if (ageSeconds > oldestAgeSeconds) oldestAgeSeconds = ageSeconds;
+  }
+  return oldestAgeSeconds;
+}
+
+// Best-effort like the email callbacks above: an observability hiccup
+// (metric not yet registered on this meter, provider misconfig) must not
+// fail a pass that otherwise cleaned up fine.
+function reportOldestOverdueAge(
+  metrics: MetricsHandle | undefined,
+  overdueDoneCleanupAfterMs: ReadonlyMap<string, number>,
+  cleanedIds: readonly string[],
+  now: Instant,
+): void {
+  // skip: no meter configured means there is nothing to report — the cleanup pass itself already ran to completion.
+  if (!metrics) return;
+  try {
+    metrics.set(
+      EXPORT_CLEANUP_BACKLOG_AGE_METRIC,
+      oldestOverdueAgeSeconds(overdueDoneCleanupAfterMs, cleanedIds, now),
+    );
+  } catch (err) {
+    // biome-ignore lint/suspicious/noConsole: operator-visibility for observability-emit-failure
+    console.warn(
+      `[user-data-rights:run-export-jobs] metrics.set(${EXPORT_CLEANUP_BACKLOG_AGE_METRIC}) failed err=${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
 // Wrapper: crud.update braucht TenantDb. ExportJob ist tenant-agnostisch
 // (1 Job pro userId), aber der event-store-Stream-Lookup erwartet einen
 // Tenant-Context. system-mode TenantDb bypassed den auto-tenant-filter