@cosmicdrift/kumiko-framework 0.125.2 → 0.126.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.125.2",
+  "version": "0.126.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -189,7 +189,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.125.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.126.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/auth-middleware.ts

@@ -55,6 +55,10 @@ export type AuthSessionChecker = (
 // and short-circuits the JWT path on a hit.
 export type PatResolver = (rawToken: string) => Promise<SessionUser | null>;
 
+export type TenantLifecycleStatusResolver = (
+  tenantId: TenantId,
+) => Promise<{ readonly status: string } | null>;
+
 export type AuthMiddlewareOptions = {
   // Called after JWT-verify when the token carries a sid. If the checker
   // reports anything other than "live", the request is rejected with 401.
@@ -74,6 +78,10 @@ export type AuthMiddlewareOptions = {
   // a SessionUser with id="anonymous" and roles=["anonymous"], scoped to a
   // tenantId resolved through the chain documented on AnonymousAccessConfig.
   readonly anonymousAccess?: AnonymousAccessConfig;
+  // Consulted after tenantId is resolved (JWT/PAT/anonymous). Returns 410
+  // when the tenant is in teardown (destroyRequested/destroying/destroyed).
+  // cancel-destruction is exempt while status=destroyRequested.
+  readonly resolveTenantLifecycleStatus?: TenantLifecycleStatusResolver;
 };
 
 // Resolves the tenant for an unauthenticated request. Returns null when no
@@ -127,14 +135,15 @@ type MiddlewareRejectCode =
   | "tenant_required"
   | "tenant_not_found"
   | "tenant_mismatch"
-  | "invalid_tenant_format";
+  | "invalid_tenant_format"
+  | "tenant_unavailable";
 
 // @wrapper-known error-helper
 function middlewareReject(
   c: Context,
   opts: {
     code: MiddlewareRejectCode;
-    status: 400 | 401 | 403 | 404;
+    status: 400 | 401 | 403 | 404 | 410;
     message: string;
     i18nKey: string;
     details?: Record<string, unknown>;
@@ -187,7 +196,13 @@ function extractToken(
 }
 
 export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions = {}) {
-  const { sessionChecker, strictMode = false, anonymousAccess, patResolver } = options;
+  const {
+    sessionChecker,
+    strictMode = false,
+    anonymousAccess,
+    patResolver,
+    resolveTenantLifecycleStatus,
+  } = options;
 
   return async (c: Context, next: Next) => {
     const extracted = extractToken(c);
@@ -219,7 +234,7 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
             i18nKey: "auth.errors.missingToken",
           });
         }
-        return await handleAnonymous(c, anonymousAccess, next);
+        return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus);
       }
       return middlewareReject(c, {
         code: "missing_token",
@@ -234,7 +249,7 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
     // Personal Access Token, not a JWT. Short-circuit the JWT path entirely.
     // Cookie transport is never a PAT (the browser holds the JWT).
     if (patResolver && transport === "bearer" && token.startsWith(PAT_TOKEN_PREFIX)) {
-      return await handlePat(c, patResolver, token, next);
+      return await handlePat(c, patResolver, token, next, resolveTenantLifecycleStatus);
     }
 
     let payload: Awaited<ReturnType<JwtHelper["verify"]>>;
@@ -286,6 +301,12 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
       ...(payload.claims ? { claims: payload.claims } : {}),
       ...(payload.jti ? { sid: payload.jti } : {}),
     };
+    const lifecycleReject = await rejectIfTenantTeardown(
+      c,
+      payload.tenantId,
+      resolveTenantLifecycleStatus,
+    );
+    if (lifecycleReject) return lifecycleReject;
     c.set(USER_KEY, user);
     c.set(AUTH_TRANSPORT_KEY, transport);
     await next();
@@ -311,6 +332,7 @@ async function handlePat(
   patResolver: PatResolver,
   token: string,
   next: Next,
+  resolveTenantLifecycleStatus?: TenantLifecycleStatusResolver,
 ): Promise<Response | undefined> {
   const patUser = await patResolver(token);
   if (!patUser) {
@@ -335,6 +357,12 @@ async function handlePat(
   }
   c.set(USER_KEY, patUser);
   c.set(AUTH_TRANSPORT_KEY, "bearer");
+  const lifecycleReject = await rejectIfTenantTeardown(
+    c,
+    patUser.tenantId,
+    resolveTenantLifecycleStatus,
+  );
+  if (lifecycleReject) return lifecycleReject;
   await next();
   // skip: PAT path completed — next() ran; explicit return keeps the
   // Response|undefined union honest (same as handleAnonymous).
@@ -357,6 +385,7 @@ async function handleAnonymous(
   c: Context,
   config: AnonymousAccessConfig,
   next: Next,
+  resolveTenantLifecycleStatus?: TenantLifecycleStatusResolver,
 ): Promise<Response | undefined> {
   // Step 1+2: parse client-supplied tenant. Reject malformed values before
   // they touch any downstream consumer (DB, cache, audit row).
@@ -394,6 +423,12 @@ async function handleAnonymous(
   }
 
   // Step 5: synthesise + continue.
+  const lifecycleReject = await rejectIfTenantTeardown(
+    c,
+    resolved.tenantId,
+    resolveTenantLifecycleStatus,
+  );
+  if (lifecycleReject) return lifecycleReject;
   c.set(USER_KEY, createAnonymousUser(resolved.tenantId));
   await next();
   // skip: anonymous path completed — Hono middleware contract returns void
@@ -479,8 +514,59 @@ async function resolveTenant(
 
 type RejectArgs = {
   code: MiddlewareRejectCode;
-  status: 400 | 401 | 403 | 404;
+  status: 400 | 401 | 403 | 404 | 410;
   message: string;
   i18nKey: string;
   details?: Record<string, unknown>;
 };
+
+const TENANT_LIFECYCLE_BLOCKED = new Set([
+  "destroyRequested",
+  "destroying",
+  "destroyFailed",
+  "destroyed",
+]);
+const TENANT_LIFECYCLE_CANCEL_QN = "tenant-lifecycle:write:cancel-destruction";
+
+async function requestsCancelDestruction(c: Context): Promise<boolean> {
+  if (c.req.method !== "POST") return false;
+  try {
+    const path = c.req.path;
+    const body = (await c.req.raw.clone().json()) as {
+      type?: string;
+      commands?: Array<{ type?: string }>;
+    };
+    if (path === "/api/write") {
+      return body.type === TENANT_LIFECYCLE_CANCEL_QN;
+    }
+    if (path === "/api/batch") {
+      return (
+        Array.isArray(body.commands) &&
+        body.commands.some((command) => command.type === TENANT_LIFECYCLE_CANCEL_QN)
+      );
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
+
+async function rejectIfTenantTeardown(
+  c: Context,
+  tenantId: TenantId,
+  resolveTenantLifecycleStatus: TenantLifecycleStatusResolver | undefined,
+): Promise<Response | undefined> {
+  if (!resolveTenantLifecycleStatus) return undefined;
+  const lifecycle = await resolveTenantLifecycleStatus(tenantId);
+  if (!lifecycle || !TENANT_LIFECYCLE_BLOCKED.has(lifecycle.status)) return undefined;
+  if (lifecycle.status === "destroyRequested" && (await requestsCancelDestruction(c))) {
+    return undefined;
+  }
+  return middlewareReject(c, {
+    code: "tenant_unavailable",
+    status: 410,
+    message: `tenant "${tenantId}" is unavailable (${lifecycle.status})`,
+    i18nKey: "auth.errors.tenantUnavailable",
+    details: { tenantId, status: lifecycle.status },
+  });
+}

package/src/api/auth-routes.ts

@@ -243,6 +243,8 @@ export type AuthRoutesConfig = {
   // Wired by run-prod-app when the PAT feature is mounted; unwired = no PAT
   // rate limiting.
   patRateLimiter?: LoginRateLimiter;
+  // Tenant-lifecycle 410 gate — wired by tenant-lifecycle / run-prod-app.
+  resolveTenantLifecycleStatus?: import("./auth-middleware").TenantLifecycleStatusResolver;
   // Password-reset flow. When wired, POST /auth/request-password-reset and
   // POST /auth/reset-password are mounted as public routes. The framework
   // dispatches to the feature-level handlers (authoring QNs typically come

package/src/api/index.ts

@@ -7,6 +7,7 @@ export type {
   AuthSessionStatus,
   PatResolver,
   TenantExists,
+  TenantLifecycleStatusResolver,
   TenantResolver,
 } from "./auth-middleware";
 export { authMiddleware, getUser, PAT_TOKEN_PREFIX } from "./auth-middleware";

package/src/api/server.ts

@@ -567,6 +567,9 @@ export function buildServer(options: ServerOptions): KumikoServer {
     ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
     ...(options.auth?.sessionStrictMode ? { strictMode: options.auth.sessionStrictMode } : {}),
     ...(options.auth?.patResolver ? { patResolver: options.auth.patResolver } : {}),
+    ...(options.auth?.resolveTenantLifecycleStatus
+      ? { resolveTenantLifecycleStatus: options.auth.resolveTenantLifecycleStatus }
+      : {}),
     ...(options.anonymousAccess ? { anonymousAccess: options.anonymousAccess } : {}),
   });
   app.use("/api/*", async (c, next) => {

package/src/engine/boot-validator/gdpr-storage.ts

@@ -1,4 +1,4 @@
-import { EXT_USER_DATA } from "../extension-names";
+import { EXT_TENANT_DATA, EXT_USER_DATA } from "../extension-names";
 import type { FeatureDefinition } from "../types";
 import type { PiiAnnotations } from "../types/fields";
 
@@ -120,3 +120,36 @@ export function validateGdprPiiHookCoverage(features: readonly FeatureDefinition
     }
   }
 }
+
+// V4: tenantOwned-entity-without-hook gate. Mirrors validateGdprPiiHookCoverage
+// but for EXT_TENANT_DATA when tenant-lifecycle is mounted.
+export function validateTenantDataHookCoverage(features: readonly FeatureDefinition[]): void {
+  const featureNames = new Set(features.map((f) => f.name));
+  if (!featureNames.has("tenant-lifecycle")) {
+    // skip: this guard only applies to apps that mount tenant-lifecycle
+    return;
+  }
+
+  const hookedEntities = new Set<string>();
+  for (const f of features) {
+    for (const usage of f.extensionUsages) {
+      if (usage.extensionName === EXT_TENANT_DATA) hookedEntities.add(usage.entityName);
+    }
+  }
+
+  for (const feature of features) {
+    for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+      if (hookedEntities.has(entityName)) continue;
+      const tenantSubjectFields = Object.entries(entity.fields)
+        .filter(([, field]) => {
+          const annot = field as PiiAnnotations;
+          return Boolean(annot.tenantOwned);
+        })
+        .map(([name]) => name);
+      if (tenantSubjectFields.length === 0) continue;
+      throw new Error(
+        `[kumiko:boot] Entity "${entityName}" (feature "${feature.name}") has tenant-subject fields (${tenantSubjectFields.join(", ")}) but no feature registers an EXT_TENANT_DATA destroy hook for it — tenant destroy never erases this data. Register r.useExtension(EXT_TENANT_DATA, "${entityName}", { destroy }) or a documented no-op if crypto-shredding covers it.`,
+      );
+    }
+  }
+}

package/src/engine/boot-validator/index.ts

@@ -31,6 +31,7 @@ import {
   validateGdprHookCompleteness,
   validateGdprPiiHookCoverage,
   validateGdprStoragePersistence,
+  validateTenantDataHookCoverage,
 } from "./gdpr-storage";
 import { validateI18nSurfaceKeys } from "./i18n-keys";
 import { validateOwnershipRules } from "./ownership";
@@ -184,6 +185,7 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
   validateGdprStoragePersistence(features);
   validateGdprHookCompleteness(features);
   validateGdprPiiHookCoverage(features);
+  validateTenantDataHookCoverage(features);
 
   if (hasEncryptedFields) {
     // Availability check, not env-presence: eagerly building the keyring

package/src/engine/extensions/tenant-data.ts

@@ -0,0 +1,19 @@
+// Hook-Signatur-Types für EXT_TENANT_DATA (DSGVO tenant-scoped destroy).
+//
+// Mirror of engine/extensions/user-data.ts at tenant granularity.
+// tenant-lifecycle orchestrates destroy via registry.getExtensionUsages(EXT_TENANT_DATA).
+
+import type { DbRunner } from "../../db/connection";
+import type { Registry, TenantId } from "../types";
+
+export interface TenantDataHookCtx {
+  readonly db: DbRunner;
+  readonly registry: Registry;
+  readonly tenantId: TenantId;
+}
+
+export type TenantDataDestroyHook = (ctx: TenantDataHookCtx) => Promise<void>;
+
+export interface TenantDataExtensionHooks {
+  readonly destroy: TenantDataDestroyHook;
+}

package/src/engine/index.ts

@@ -81,6 +81,11 @@ export {
   EXT_USER_DATA_ORDER,
   FILE_PROVIDER_CONFIG_KEY,
 } from "./extension-names";
+export type {
+  TenantDataDestroyHook,
+  TenantDataExtensionHooks,
+  TenantDataHookCtx,
+} from "./extensions/tenant-data";
 export type {
   TenantUserModel,
   UserDataDeleteHook,