feat: high-impact override approval workflow with state machine and audit trail

src/app.ts

@@ -14,7 +14,7 @@
 import { createDisputesRouter } from './routes/disputes.routes';
 import { createMetricsRouter } from './routes/metrics.routes';
 import { metricsAuthMiddleware } from './middleware/metricsAuth';
 import reputationRouter, { createReputationRouter } from './routes/reputation.routes';
 import authRouter from './routes/auth.routes';
 import configRouter from './routes/config.routes';
 import dependencyScanRouter from './routes/dependency-scan.routes';
@@ -28,6 +28,7 @@
 import { ReputationService } from './services/reputation.service';
 import { getDb } from './db/database';
 import { requestContextMiddleware } from './context';
+import { createOverrideRequestsRouter } from './modules/overrideRequests/overrideRequest.routes';
 
 interface AppFactoryOptions {
   includeTerminalHandlers?: boolean;
@@ -88,6 +89,7 @@
     app.use('/api/v1/webhook-subscriptions', webhookSubscriptionRouter);
   }
   app.use('/api/v1/metrics', metricsAuthMiddleware, createMetricsRouter(metricsService));
+  app.use('/api/v1/override-requests', createOverrideRequestsRouter());
 
   if (includeTerminalHandlers) {
     attachTerminalHandlers(app);

src/audit/service.ts

@@ -36,6 +36,9 @@
   'AUTH_LOCKOUT_TRIGGERED', 'AUTH_LOCKOUT_RELEASED',
   'ADMIN_ACTION',
   'ENDPOINT_ACCESS', 'ENDPOINT_MUTATION',
+  // Override request workflow (#1221)
+  'OVERRIDE_REQUESTED', 'OVERRIDE_APPROVED', 'OVERRIDE_REJECTED',
+  'OVERRIDE_APPLIED', 'OVERRIDE_EXPIRED',
 ]);
 
 export const VALID_SEVERITIES = new Set<AuditSeverity>(['INFO', 'WARNING', 'CRITICAL']);
@@ -110,7 +113,7 @@
   if (cursor) {
     try {
       decodeCursor(cursor);
     } catch (_error) {
       throw new Error('Invalid cursor format');
     }
   }

src/audit/types.ts

@@ -40,6 +40,12 @@ export const AUDIT_ACTIONS = [
   'ENDPOINT_MUTATION',
   'DEPLOYMENT_PROMOTED',
   'DEPLOYMENT_ROLLED_BACK',
+  // Override request workflow (#1221)
+  'OVERRIDE_REQUESTED',
+  'OVERRIDE_APPROVED',
+  'OVERRIDE_REJECTED',
+  'OVERRIDE_APPLIED',
+  'OVERRIDE_EXPIRED',
 ] as const;
 
 /** Categories of sensitive state changes that must be audited. */
@@ -69,7 +75,13 @@ export type AuditAction =
   | 'DEPLOYMENT_ROLLED_BACK'
   | 'MILESTONES_CREATED'
   | 'MILESTONES_UPDATED'
-  | 'MILESTONES_DELETED';
+  | 'MILESTONES_DELETED'
+  // Override request workflow (#1221)
+  | 'OVERRIDE_REQUESTED'
+  | 'OVERRIDE_APPROVED'
+  | 'OVERRIDE_REJECTED'
+  | 'OVERRIDE_APPLIED'
+  | 'OVERRIDE_EXPIRED';
 
 export const AUDIT_SEVERITIES = ['INFO', 'WARNING', 'CRITICAL'] as const;
 

src/db/migrations.ts

@@ -818,3 +818,79 @@ MIGRATIONS.push({
     }
   },
 });
+
+// Version 18: override_requests table for high-impact override approval workflow.
+//
+// Each row tracks one override request through its state machine:
+//   requested → approved → applied   (happy path)
+//   requested → rejected             (denied)
+//   requested/approved → expired     (TTL elapsed before apply)
+//
+// Security notes:
+//  - requester_id and approver_id must be different (enforced at service layer).
+//  - tenant_id provides row-level isolation between tenants.
+//  - expires_at is written at creation time and evaluated on every read/apply.
+//  - applied_at records when the override was actually executed.
+MIGRATIONS.push({
+  version: 18,
+  name: "create_override_requests_table",
+  checksumSource: [
+    "CREATE TABLE IF NOT EXISTS override_requests (",
+    "id TEXT PRIMARY KEY,",
+    "tenant_id TEXT NOT NULL,",
+    "resource_type TEXT NOT NULL,",
+    "resource_id TEXT NOT NULL,",
+    "action TEXT NOT NULL,",
+    "requester_id TEXT NOT NULL,",
+    "approver_id TEXT,",
+    "status TEXT NOT NULL DEFAULT 'requested',",
+    "reason TEXT NOT NULL,",
+    "rejection_reason TEXT,",
+    "expires_at TEXT NOT NULL,",
+    "approved_at TEXT,",
+    "applied_at TEXT,",
+    "rejected_at TEXT,",
+    "metadata TEXT NOT NULL DEFAULT '{}',",
+    "created_at TEXT NOT NULL,",
+    "updated_at TEXT NOT NULL",
+  ].join("\n"),
+  up: (db) => {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS override_requests (
+        id              TEXT    PRIMARY KEY,
+        tenant_id       TEXT    NOT NULL,
+        resource_type   TEXT    NOT NULL,
+        resource_id     TEXT    NOT NULL,
+        action          TEXT    NOT NULL,
+        requester_id    TEXT    NOT NULL,
+        approver_id     TEXT,
+        status          TEXT    NOT NULL DEFAULT 'requested'
+                                CHECK (status IN ('requested', 'approved', 'rejected', 'applied', 'expired')),
+        reason          TEXT    NOT NULL CHECK (length(reason) >= 10 AND length(reason) <= 5000),
+        rejection_reason TEXT,
+        expires_at      TEXT    NOT NULL,
+        approved_at     TEXT,
+        applied_at      TEXT,
+        rejected_at     TEXT,
+        metadata        TEXT    NOT NULL DEFAULT '{}',
+        created_at      TEXT    NOT NULL,
+        updated_at      TEXT    NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_override_requests_tenant_id
+        ON override_requests(tenant_id);
+
+      CREATE INDEX IF NOT EXISTS idx_override_requests_status
+        ON override_requests(status);
+
+      CREATE INDEX IF NOT EXISTS idx_override_requests_requester_id
+        ON override_requests(requester_id);
+
+      CREATE INDEX IF NOT EXISTS idx_override_requests_resource
+        ON override_requests(resource_type, resource_id);
+
+      CREATE INDEX IF NOT EXISTS idx_override_requests_expires_at
+        ON override_requests(expires_at);
+    `);
+  },
+});

src/lib/types.ts

@@ -17,7 +17,8 @@ export type Resource =
   | "settings"
   | "disputes"
   | "health"
-  | "reputation";
+  | "reputation"
+  | "override-requests";
 
 export type Action = "create" | "read" | "update" | "delete" | "list" | "correct";