Merge pull request #1091 from OutstandingVick/agent/issue-1047-soft-delete-audit

Backend: introduce soft-delete and audit trails for critical entities

Author: Junirezz

backend/docs/CRITICAL_ENTITY_LIFECYCLE.md

@@ -0,0 +1,105 @@
+# Critical Entity Soft Deletion and Audit Trail
+
+Issue #1047 protects critical control-plane records from accidental,
+unaudited hard deletion.
+
+## Scope
+
+The audited lifecycle service covers:
+
+- `Tenant`
+- persisted `ApiKey`
+
+Existing `WebhookEndpoint` deletion remains a soft delete with
+`deletedAt`/`deletedBy` and admin audit logging. `ScopedAdminToken` uses
+revocation rather than deletion. Generic Prisma hard deletes are blocked
+outside tests for all four entity types and for `CriticalEntityAuditEvent`.
+
+Financial records (`Transaction`, vault state, share-price snapshots, and
+reconciliation history) are deliberately excluded. They remain immutable and
+follow the regulatory retention policy rather than a reversible application
+delete workflow.
+
+## Invariants
+
+1. Delete and restore operations require a non-empty actor and reason.
+2. State changes and `CriticalEntityAuditEvent` creation occur in one database
+   transaction.
+3. Conditional `updateMany` predicates make retries idempotent and prevent two
+   concurrent requests from producing duplicate lifecycle events.
+4. Deleting a tenant atomically disables and soft-deletes all of its active API
+   keys.
+5. Restoring a tenant does not restore credentials. Each API key requires a
+   separate audited restore after the tenant is active.
+6. Authentication rejects keys whose key record or parent tenant is deleted.
+7. Audit metadata never includes plaintext credentials or stored key hashes.
+8. Audit rows are append-only. Generic Prisma `delete`/`deleteMany` operations
+   against protected models throw outside the test environment.
+
+Raw SQL bypasses Prisma safeguards and must not be used for lifecycle changes.
+Retention cleanup that eventually hard-deletes records must use a dedicated,
+reviewed maintenance path after the documented grace period.
+
+## Service API
+
+Use `src/criticalEntityLifecycle.ts`:
+
+```ts
+await softDeleteTenant('tenant-id', {
+  actor: 'admin@example.com',
+  reason: 'Customer account closed',
+});
+
+await restoreTenant('tenant-id', {
+  actor: 'security-admin@example.com',
+  reason: 'Closure reversed after verification',
+});
+
+await softDeleteApiKey('api-key-id', {
+  actor: 'security-admin@example.com',
+  reason: 'Credential compromised',
+});
+```
+
+The result status is one of:
+
+- `changed`
+- `not_found`
+- `already_deleted`
+- `not_deleted`
+- `parent_deleted`
+
+Treat statuses other than `changed` as no-op outcomes; they never create a
+duplicate audit event.
+
+## Audit review
+
+`listCriticalEntityAuditTrail` supports entity type, entity ID, and action
+filters. Results are newest-first and capped at 500 records per call.
+
+An audit record contains:
+
+- entity type and ID
+- `soft_delete` or `restore`
+- attributable actor
+- required reason
+- non-sensitive operation metadata
+- database-generated timestamp
+
+Retain `CriticalEntityAuditEvent` records for seven years with other security
+audit data. They must not be changed or removed through application CRUD.
+
+## Deployment
+
+1. Back up the database.
+2. Apply migration
+   `20260729000000_add_critical_entity_soft_delete`.
+3. Confirm the new nullable columns and audit table exist.
+4. Delete a non-production API key through the lifecycle service.
+5. Verify authentication fails immediately.
+6. Verify exactly one `CriticalEntityAuditEvent` exists.
+7. Restore the key and verify a second audit event is appended.
+
+Rollback should restore application code first. The nullable columns and audit
+table are backward-compatible and should be retained until their data has been
+archived and a separate destructive migration is approved.

backend/prisma/migrations/20260729000000_add_critical_entity_soft_delete/migration.sql

@@ -0,0 +1,62 @@
+-- Issue #1047: soft deletion and immutable lifecycle audits for critical
+-- control-plane entities. Financial history remains immutable and is not
+-- covered by this reversible deletion mechanism.
+-- migration-safety: allow-not-null-add
+-- migration-safety: allow-nonconcurrent-indexes
+-- The added columns are nullable. The NOT NULL detector otherwise scans into
+-- the later CREATE TABLE statement. SQLite does not support CONCURRENTLY.
+
+-- Tenant and ApiKey existed in schema.prisma before they were represented in
+-- the migration history. Establish their baseline shape on clean databases;
+-- existing managed databases treat these statements as no-ops.
+CREATE TABLE IF NOT EXISTS "Tenant" (
+  "id"        TEXT     NOT NULL PRIMARY KEY,
+  "name"      TEXT     NOT NULL,
+  "createdAt" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+CREATE UNIQUE INDEX IF NOT EXISTS "Tenant_name_key" ON "Tenant"("name");
+CREATE INDEX IF NOT EXISTS "Tenant_name_idx" ON "Tenant"("name");
+
+CREATE TABLE IF NOT EXISTS "ApiKey" (
+  "id"        TEXT     NOT NULL PRIMARY KEY,
+  "tenantId"  TEXT     NOT NULL,
+  "hashedKey" TEXT     NOT NULL,
+  "role"      TEXT     NOT NULL,
+  "scopes"    TEXT     NOT NULL DEFAULT '[]',
+  "createdAt" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  "expiresAt" DATETIME,
+  "isActive"  BOOLEAN  NOT NULL DEFAULT true,
+  CONSTRAINT "ApiKey_tenantId_fkey"
+    FOREIGN KEY ("tenantId") REFERENCES "Tenant"("id") ON DELETE RESTRICT ON UPDATE CASCADE
+);
+CREATE UNIQUE INDEX IF NOT EXISTS "ApiKey_hashedKey_key" ON "ApiKey"("hashedKey");
+CREATE INDEX IF NOT EXISTS "ApiKey_tenantId_idx" ON "ApiKey"("tenantId");
+CREATE INDEX IF NOT EXISTS "ApiKey_role_idx" ON "ApiKey"("role");
+
+ALTER TABLE "Tenant" ADD COLUMN "deletedAt" DATETIME;
+ALTER TABLE "Tenant" ADD COLUMN "deletedBy" TEXT;
+ALTER TABLE "Tenant" ADD COLUMN "deletionReason" TEXT;
+
+ALTER TABLE "ApiKey" ADD COLUMN "deletedAt" DATETIME;
+ALTER TABLE "ApiKey" ADD COLUMN "deletedBy" TEXT;
+ALTER TABLE "ApiKey" ADD COLUMN "deletionReason" TEXT;
+
+CREATE TABLE "CriticalEntityAuditEvent" (
+  "id"         TEXT     NOT NULL PRIMARY KEY,
+  "entityType" TEXT     NOT NULL,
+  "entityId"   TEXT     NOT NULL,
+  "action"     TEXT     NOT NULL,
+  "actor"      TEXT     NOT NULL,
+  "reason"     TEXT     NOT NULL,
+  "metadata"   TEXT     NOT NULL DEFAULT '{}',
+  "createdAt"  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX "Tenant_deletedAt_idx" ON "Tenant"("deletedAt");
+CREATE INDEX "ApiKey_tenantId_deletedAt_idx" ON "ApiKey"("tenantId", "deletedAt");
+CREATE INDEX "ApiKey_deletedAt_idx" ON "ApiKey"("deletedAt");
+CREATE INDEX "CriticalEntityAuditEvent_entityType_entityId_createdAt_idx"
+  ON "CriticalEntityAuditEvent"("entityType", "entityId", "createdAt");
+CREATE INDEX "CriticalEntityAuditEvent_action_idx" ON "CriticalEntityAuditEvent"("action");
+CREATE INDEX "CriticalEntityAuditEvent_actor_idx" ON "CriticalEntityAuditEvent"("actor");
+CREATE INDEX "CriticalEntityAuditEvent_createdAt_idx" ON "CriticalEntityAuditEvent"("createdAt");

backend/prisma/schema.prisma

@@ -459,29 +459,57 @@ model ScopedAdminTokenRotationEvent {
 
 // Tenant model – represents a customer/organization
 model Tenant {
-  id        String   @id @default(uuid())
-  name      String   @unique
-  createdAt DateTime @default(now())
+  id             String    @id @default(uuid())
+  name           String    @unique
+  createdAt      DateTime  @default(now())
+  deletedAt      DateTime?
+  deletedBy      String?
+  deletionReason String?
   // Relations
-  apiKeys   ApiKey[]
+  apiKeys        ApiKey[]
+
   @@index([name])
+  @@index([deletedAt])
 }
 
 // API key model – scoped per tenant with role and scopes
 model ApiKey {
-  id         String   @id @default(uuid())
-  tenantId   String
-  hashedKey  String   @unique
-  role       String
-  scopes     String   @default("[]")
-  createdAt  DateTime @default(now())
-  expiresAt  DateTime?
-  isActive   Boolean  @default(true)
-
-  tenant     Tenant   @relation(fields: [tenantId], references: [id])
+  id             String    @id @default(uuid())
+  tenantId       String
+  hashedKey      String    @unique
+  role           String
+  scopes         String    @default("[]")
+  createdAt      DateTime  @default(now())
+  expiresAt      DateTime?
+  isActive       Boolean   @default(true)
+  deletedAt      DateTime?
+  deletedBy      String?
+  deletionReason String?
+
+  tenant Tenant @relation(fields: [tenantId], references: [id])
 
   @@index([tenantId])
+  @@index([tenantId, deletedAt])
   @@index([role])
+  @@index([deletedAt])
+}
+
+/// Immutable lifecycle history for critical control-plane entities.
+/// Application code may append records but must never update or delete them.
+model CriticalEntityAuditEvent {
+  id         String   @id @default(uuid())
+  entityType String
+  entityId   String
+  action     String
+  actor      String
+  reason     String
+  metadata   String   @default("{}")
+  createdAt  DateTime @default(now())
+
+  @@index([entityType, entityId, createdAt])
+  @@index([action])
+  @@index([actor])
+  @@index([createdAt])
 }
 
 // Durable write-ahead audit log for admin configuration changes (Issue #707).

backend/src/__tests__/apiKeySoftDeleteAuth.test.ts

@@ -0,0 +1,40 @@
+import { isPersistedApiKeyUsable } from '../middleware/apiKeyAuth';
+
+describe('persisted API key soft-delete authentication (Issue #1047)', () => {
+  it('rejects a soft-deleted API key', () => {
+    expect(
+      isPersistedApiKeyUsable({
+        isActive: true,
+        deletedAt: new Date(),
+        tenant: { deletedAt: null },
+      })
+    ).toBe(false);
+  });
+
+  it('rejects an otherwise active key when its tenant is deleted', () => {
+    expect(
+      isPersistedApiKeyUsable({
+        isActive: true,
+        deletedAt: null,
+        tenant: { deletedAt: new Date() },
+      })
+    ).toBe(false);
+  });
+
+  it('accepts an active key only when its tenant is also active', () => {
+    expect(
+      isPersistedApiKeyUsable({
+        isActive: true,
+        deletedAt: null,
+        tenant: { deletedAt: null },
+      })
+    ).toBe(true);
+    expect(
+      isPersistedApiKeyUsable({
+        isActive: false,
+        deletedAt: null,
+        tenant: { deletedAt: null },
+      })
+    ).toBe(false);
+  });
+});