@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

package/src/tenant-lifecycle/feature.ts

@@ -0,0 +1,112 @@
+import {
+  defineFeature,
+  EXT_EXTERNAL_RESOURCE,
+  EXT_INFRA_RESOURCE,
+  EXT_SEARCH_ADAPTER,
+  EXT_STORAGE_PROVIDER,
+  EXT_TENANT_DATA,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { validateTenantDataHookCoverage } from "./boot-checks";
+import {
+  DESTRUCTION_CANCELLED_EVENT_SHORT,
+  DESTRUCTION_REQUESTED_EVENT_SHORT,
+  TENANT_DESTRUCTION_COMPLETED_EVENT_SHORT,
+  TENANT_DESTRUCTION_FAILED_EVENT_SHORT,
+  TENANT_DESTRUCTION_STAGE_ABANDONED_EVENT_SHORT,
+  TENANT_DESTRUCTION_STAGE_FAILED_EVENT_SHORT,
+  TENANT_DESTRUCTION_STAGE_STARTED_EVENT_SHORT,
+  TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_SHORT,
+  TENANT_DESTRUCTION_STARTED_EVENT_SHORT,
+} from "./constants";
+import {
+  destructionCancelledSchema,
+  destructionRequestedSchema,
+  tenantDestructionCompletedSchema,
+  tenantDestructionFailedSchema,
+  tenantDestructionStageAbandonedSchema,
+  tenantDestructionStageFailedSchema,
+  tenantDestructionStageStartedSchema,
+  tenantDestructionStageSucceededSchema,
+  tenantDestructionStartedSchema,
+} from "./events";
+import { cancelDestructionWrite } from "./handlers/cancel-destruction.write";
+import { requestDestructionWrite } from "./handlers/request-destruction.write";
+import { runTenantDestructionSweep } from "./run-tenant-destroy";
+
+export function createTenantLifecycleFeature(): FeatureDefinition {
+  return defineFeature("tenant-lifecycle", (r) => {
+    r.describe(
+      "Tenant-destroy lifecycle: request/cancel destruction with compliance-profile grace, auth 410 gate for teardown states, cron trigger after grace, and staged destroy runner (extension fan-out, subject-key erase, tenant tombstone).",
+    );
+    r.uiHints({
+      displayLabel: "Tenant Lifecycle · Destroy",
+      category: "compliance",
+      recommended: false,
+    });
+    r.requires("tenant", "compliance-profiles");
+    r.optionalRequires("sessions");
+    r.usesApi("compliance.forTenant");
+
+    r.extendsRegistrar(EXT_TENANT_DATA, {});
+    r.extendsRegistrar(EXT_SEARCH_ADAPTER, {});
+    r.extendsRegistrar(EXT_EXTERNAL_RESOURCE, {});
+    r.extendsRegistrar(EXT_STORAGE_PROVIDER, {});
+    r.extendsRegistrar(EXT_INFRA_RESOURCE, {});
+
+    // GDPR-storage guard V4 (#1314) — moved off the framework-internal
+    // boot-validator onto this feature's own r.bootCheck(), since it owns
+    // EXT_TENANT_DATA: its own mount is the trigger, matching the original
+    // guard's "tenant-lifecycle mounted" gate exactly.
+    r.bootCheck(({ features }) => validateTenantDataHookCoverage(features));
+
+    r.defineEvent(DESTRUCTION_REQUESTED_EVENT_SHORT, destructionRequestedSchema);
+    r.defineEvent(DESTRUCTION_CANCELLED_EVENT_SHORT, destructionCancelledSchema);
+    r.defineEvent(TENANT_DESTRUCTION_STARTED_EVENT_SHORT, tenantDestructionStartedSchema);
+    r.defineEvent(
+      TENANT_DESTRUCTION_STAGE_STARTED_EVENT_SHORT,
+      tenantDestructionStageStartedSchema,
+    );
+    r.defineEvent(
+      TENANT_DESTRUCTION_STAGE_SUCCEEDED_EVENT_SHORT,
+      tenantDestructionStageSucceededSchema,
+    );
+    r.defineEvent(TENANT_DESTRUCTION_STAGE_FAILED_EVENT_SHORT, tenantDestructionStageFailedSchema);
+    r.defineEvent(
+      TENANT_DESTRUCTION_STAGE_ABANDONED_EVENT_SHORT,
+      tenantDestructionStageAbandonedSchema,
+    );
+    r.defineEvent(TENANT_DESTRUCTION_COMPLETED_EVENT_SHORT, tenantDestructionCompletedSchema);
+    r.defineEvent(TENANT_DESTRUCTION_FAILED_EVENT_SHORT, tenantDestructionFailedSchema);
+
+    r.writeHandler(requestDestructionWrite);
+    r.writeHandler(cancelDestructionWrite);
+
+    r.job(
+      "run-tenant-destruction",
+      { trigger: { cron: "0 * * * * *" }, concurrency: "skip" },
+      async (_payload, ctx) => {
+        if (!ctx.db || !ctx.registry) {
+          throw new Error(
+            "run-tenant-destruction: ctx.db + ctx.registry required (JobContext incomplete)",
+          );
+        }
+        const T = (await import("@cosmicdrift/kumiko-framework/time")).getTemporal();
+        await runTenantDestructionSweep({
+          db: ctx.db as import("@cosmicdrift/kumiko-framework/db").DbConnection,
+          registry: ctx.registry,
+          now: T.Now.instant(),
+          log: (message) => ctx.log?.warn(message),
+        });
+      },
+    );
+
+    r.exposesApi("tenantLifecycle.runDestroySweep");
+  });
+}
+
+export {
+  TENANT_LIFECYCLE_FEATURE,
+  TenantLifecycleHandlers,
+} from "./constants";
+export { resolveTenantLifecycleGate, runTenantDestructionSweep } from "./run-tenant-destroy";

package/src/tenant-lifecycle/handlers/cancel-destruction.write.ts

@@ -0,0 +1,79 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { isWithinGracePeriod } from "../../shared";
+import { type TenantLifecycleStatus, tenantEntity, tenantTable } from "../../tenant";
+import { DESTRUCTION_CANCELLED_EVENT_QN } from "../constants";
+import { invalidateTenantLifecycleGate } from "../lifecycle-gate";
+
+export { isWithinGracePeriod };
+
+const crud = createEventStoreExecutor(tenantTable, tenantEntity, { entityName: "tenant" });
+
+type TenantLifecycleRow = {
+  status: TenantLifecycleStatus;
+  gracePeriodEnd: Temporal.Instant | null;
+};
+
+export const cancelDestructionWrite = defineWriteHandler({
+  name: "cancel-destruction",
+  schema: z.object({}),
+  access: { roles: ["TenantOwner", "Admin"] },
+  handler: async (event, ctx) => {
+    const tenantId = event.user.tenantId;
+    const row = await fetchOne<TenantLifecycleRow>(ctx.db.raw, tenantTable, { id: tenantId });
+    if (!row) {
+      return writeFailure(new UnprocessableError("tenant_not_found", { details: { tenantId } }));
+    }
+    if (row.status !== "destroyRequested") {
+      return writeFailure(
+        new UnprocessableError("no_pending_destruction", {
+          details: { status: row.status },
+        }),
+      );
+    }
+
+    if (!isWithinGracePeriod(row.gracePeriodEnd)) {
+      return writeFailure(
+        new UnprocessableError("grace_period_expired", {
+          details: { reason: "grace_period_expired" },
+        }),
+      );
+    }
+
+    const update = await crud.update(
+      {
+        id: tenantId,
+        changes: {
+          status: "active",
+          destroyRequestedAt: null,
+          destroyRequestedBy: null,
+          gracePeriodEnd: null,
+        },
+      },
+      event.user,
+      ctx.db,
+      { skipOptimisticLock: true },
+    );
+    if (!update.isSuccess) return update;
+    invalidateTenantLifecycleGate(tenantId);
+
+    await ctx.unsafeAppendEvent({
+      aggregateId: tenantId,
+      aggregateType: "tenant",
+      type: DESTRUCTION_CANCELLED_EVENT_QN,
+      payload: { cancelledBy: event.user.id },
+    });
+
+    return {
+      isSuccess: true as const,
+      data: {
+        tenantId,
+        status: "active" as const,
+        gracePeriodEnd: null as string | null,
+      },
+    };
+  },
+});

package/src/tenant-lifecycle/handlers/request-destruction.write.ts

@@ -0,0 +1,83 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { addDurationSpec } from "@cosmicdrift/kumiko-framework/compliance";
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { z } from "zod";
+import { resolveProfileForTenant } from "../../compliance-profiles";
+import { type TenantLifecycleStatus, tenantEntity, tenantTable } from "../../tenant";
+import { DESTRUCTION_REQUESTED_EVENT_QN } from "../constants";
+import { revokeTenantSessions } from "../lib/revoke-tenant-sessions";
+import { invalidateTenantLifecycleGate } from "../lifecycle-gate";
+
+const crud = createEventStoreExecutor(tenantTable, tenantEntity, { entityName: "tenant" });
+
+type TenantLifecycleRow = {
+  status: TenantLifecycleStatus;
+  gracePeriodEnd: Temporal.Instant | null;
+};
+
+export const requestDestructionWrite = defineWriteHandler({
+  name: "request-destruction",
+  schema: z.object({}),
+  access: { roles: ["TenantOwner", "Admin"] },
+  handler: async (event, ctx) => {
+    const tenantId = event.user.tenantId;
+    const row = await fetchOne<TenantLifecycleRow>(ctx.db.raw, tenantTable, { id: tenantId });
+    if (!row) {
+      return writeFailure(new UnprocessableError("tenant_not_found", { details: { tenantId } }));
+    }
+    if (row.status !== "active") {
+      return writeFailure(
+        new UnprocessableError("tenant_not_active", {
+          details: { status: row.status },
+        }),
+      );
+    }
+
+    const { profile } = await resolveProfileForTenant({ db: ctx.db.raw, tenantId });
+    const T = getTemporal();
+    const gracePeriodEnd = addDurationSpec(T.Now.instant(), profile.tenantDestroyGracePeriod);
+
+    const update = await crud.update(
+      {
+        id: tenantId,
+        changes: {
+          status: "destroyRequested",
+          destroyRequestedAt: T.Now.instant(),
+          destroyRequestedBy: event.user.id,
+          gracePeriodEnd,
+        },
+      },
+      event.user,
+      ctx.db,
+      { skipOptimisticLock: true },
+    );
+    if (!update.isSuccess) return update;
+    invalidateTenantLifecycleGate(tenantId);
+
+    await ctx.unsafeAppendEvent({
+      aggregateId: tenantId,
+      aggregateType: "tenant",
+      type: DESTRUCTION_REQUESTED_EVENT_QN,
+      payload: {
+        requestedBy: event.user.id,
+        gracePeriodEnd: gracePeriodEnd.toString(),
+      },
+    });
+
+    if (await ctx.hasFeature("sessions")) {
+      await revokeTenantSessions(ctx.db.raw, tenantId);
+    }
+
+    return {
+      isSuccess: true as const,
+      data: {
+        tenantId,
+        status: "destroyRequested" as const,
+        gracePeriodEnd: gracePeriodEnd.toString(),
+      },
+    };
+  },
+});

package/src/tenant-lifecycle/index.ts

@@ -0,0 +1,7 @@
+export {
+  TENANT_DESTRUCTION_STAGES,
+  TENANT_LIFECYCLE_FEATURE,
+  TenantLifecycleHandlers,
+} from "./constants";
+export { createTenantLifecycleFeature } from "./feature";
+export { resolveTenantLifecycleGate } from "./run-tenant-destroy";

package/src/tenant-lifecycle/lib/revoke-tenant-sessions.ts

@@ -0,0 +1,16 @@
+import { updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { userSessionTable } from "../../sessions";
+
+/** Revoke all live sessions scoped to a tenant (destruction-request gate). */
+export async function revokeTenantSessions(db: DbRunner, tenantId: TenantId): Promise<number> {
+  const updated = await updateMany(
+    db,
+    userSessionTable,
+    { revokedAt: getTemporal().Now.instant() },
+    { tenantId, revokedAt: null },
+  );
+  return updated.length;
+}

package/src/tenant-lifecycle/lifecycle-gate.ts

@@ -0,0 +1,65 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { tenantTable } from "../tenant";
+
+export type TenantLifecycleGate = {
+  readonly status: string;
+  readonly gracePeriodEnd: string | null;
+};
+
+// Every authenticated + anonymous request consults this (via auth-middleware's
+// resolveTenantLifecycleStatus) — a per-request DB round-trip otherwise.
+// invalidateTenantLifecycleGate(tenantId) clears the SAME-process entry
+// right after every status-changing write (request/cancel-destruction, the
+// sweep, tombstoneTenantRow) — the instant-visibility path for a single
+// replica. In a multi-replica deployment a write on pod A never reaches pod
+// B's Map, so a short TTL bounds the cross-pod staleness window instead of
+// leaving it unbounded (self-heals within GATE_TTL_MS even if invalidation
+// never arrives).
+// Split into its own module (not run-tenant-destroy.ts) so stages.ts can
+// invalidate too without a stages.ts <-> run-tenant-destroy.ts import cycle.
+// ponytail: unbounded Map — fine while tenant counts stay in the thousands (a
+// few bytes/entry); swap for a bounded LRU if that ever changes.
+const GATE_TTL_MS = 3000;
+const gateCache = new Map<
+  TenantId,
+  { readonly value: TenantLifecycleGate | null; readonly expiresAt: number }
+>();
+
+export function invalidateTenantLifecycleGate(tenantId: TenantId): void {
+  gateCache.delete(tenantId);
+}
+
+/** @internal test-only — resetTestTables/resetTestTable wipe rows directly
+ *  via SQL, bypassing the write handlers that invalidate normally. Tests
+ *  that reset tenantTable (and reuse a fixed tenantId across cases) must
+ *  call this in beforeEach or a later test can read an earlier test's
+ *  cached status for the same tenantId. */
+export function resetTenantLifecycleGateCacheForTests(): void {
+  gateCache.clear();
+}
+
+export async function resolveTenantLifecycleGate(
+  db: DbRunner,
+  tenantId: TenantId,
+): Promise<TenantLifecycleGate | null> {
+  const cached = gateCache.get(tenantId);
+  if (cached && cached.expiresAt > Date.now()) return cached.value;
+  const rows = await selectMany<{ status: string; gracePeriodEnd: Temporal.Instant | null }>(
+    db,
+    tenantTable,
+    { id: tenantId },
+  );
+  const row = rows[0];
+  if (!row) {
+    gateCache.set(tenantId, { value: null, expiresAt: Date.now() + GATE_TTL_MS });
+    return null;
+  }
+  const gate: TenantLifecycleGate = {
+    status: row.status,
+    gracePeriodEnd: row.gracePeriodEnd?.toString() ?? null,
+  };
+  gateCache.set(tenantId, { value: gate, expiresAt: Date.now() + GATE_TTL_MS });
+  return gate;
+}