feat(security): security audit trail, API-key alerts, and workflow version history

.npmrc

@@ -165,3 +165,8 @@ minimum-release-age-exclude[]=monaco-editor
 # Pinned to 1.4.4 (2019); the policy exclusion is only because pnpm
 # checks the latest published version of every package on resolve.
 minimum-release-age-exclude[]=qrcode-generator
+# Structural JSON diff used for the security audit log (who-changed-what).
+# Pinned to 1.0.2 (2018); stable, zero transitive deps. The exclusion is
+# only needed because pnpm checks the latest published version on resolve.
+minimum-release-age-exclude[]=deep-diff
+minimum-release-age-exclude[]=@types/deep-diff

app/api/admin/orgs/[orgId]/activate/route.ts

@@ -4,6 +4,7 @@ import { db } from "@/lib/db";
 import { organization, workflows } from "@/lib/db/schema";
 import { authenticateKhAdmin } from "@/lib/kh-admin-auth";
 import { ErrorCategory, logSystemError } from "@/lib/logging";
+import { buildAuditMetadata, recordAuditEvent } from "@/lib/security/audit-log";
 
 export async function POST(
   request: Request,
@@ -59,6 +60,19 @@ export async function POST(
       return NextResponse.json({ error: "Organization is not deactivated" }, { status: 409 });
     }
 
+    await recordAuditEvent({
+      actor: {
+        userId: null,
+        organizationId: result.orgId,
+        authMethod: "kh-admin",
+        actorLabel: "KeeperHub admin",
+      },
+      action: "org.reactivated",
+      resourceType: "organization",
+      resourceId: result.orgId,
+      metadata: buildAuditMetadata(request),
+    });
+
     return NextResponse.json(result);
   } catch (error) {
     logSystemError(ErrorCategory.DATABASE, "[Admin] Failed to activate org", error, {

app/api/admin/orgs/[orgId]/deactivate/route.ts

@@ -4,6 +4,7 @@ import { db } from "@/lib/db";
 import { organization, workflows } from "@/lib/db/schema";
 import { authenticateKhAdmin } from "@/lib/kh-admin-auth";
 import { ErrorCategory, logSystemError } from "@/lib/logging";
+import { buildAuditMetadata, recordAuditEvent } from "@/lib/security/audit-log";
 
 export async function POST(
   request: Request,
@@ -64,6 +65,23 @@ export async function POST(
       );
     }
 
+    await recordAuditEvent({
+      actor: {
+        userId: null,
+        organizationId: result.orgId,
+        authMethod: "kh-admin",
+        actorLabel: "KeeperHub admin",
+      },
+      action: "org.deactivated",
+      resourceType: "organization",
+      resourceId: result.orgId,
+      after: {
+        deactivatedAt: result.deactivatedAt?.toISOString(),
+        workflowsDeactivated: result.workflowsDeactivated,
+      },
+      metadata: buildAuditMetadata(request),
+    });
+
     return NextResponse.json(result);
   } catch (error) {
     logSystemError(ErrorCategory.DATABASE, "[Admin] Failed to deactivate org", error, {

app/api/admin/users/[userId]/activate/route.ts

@@ -4,6 +4,7 @@ import { db } from "@/lib/db";
 import { users } from "@/lib/db/schema";
 import { authenticateKhAdmin } from "@/lib/kh-admin-auth";
 import { ErrorCategory, logSystemError } from "@/lib/logging";
+import { buildAuditMetadata, recordAuditEvent } from "@/lib/security/audit-log";
 
 export async function POST(
   request: Request,
@@ -48,6 +49,19 @@ export async function POST(
       return NextResponse.json({ error: "User is not deactivated" }, { status: 409 });
     }
 
+    await recordAuditEvent({
+      actor: {
+        userId: null,
+        organizationId: null,
+        authMethod: "kh-admin",
+        actorLabel: "KeeperHub admin",
+      },
+      action: "account.reactivated",
+      resourceType: "user",
+      resourceId: result.userId,
+      metadata: buildAuditMetadata(request),
+    });
+
     return NextResponse.json(result);
   } catch (error) {
     logSystemError(ErrorCategory.DATABASE, "[Admin] Failed to activate user", error, {

app/api/admin/users/[userId]/deactivate/route.ts

@@ -5,6 +5,7 @@ import { organizationApiKeys, sessions, users } from "@/lib/db/schema";
 import { sendAccountDeactivatedEmail } from "@/lib/email";
 import { authenticateKhAdmin } from "@/lib/kh-admin-auth";
 import { ErrorCategory, logSystemError } from "@/lib/logging";
+import { buildAuditMetadata, recordAuditEvent } from "@/lib/security/audit-log";
 
 // The body is optional; callers (raita-bot auto-block, on-call tooling) may
 // POST nothing at all. notifyUser defaults to true so a deactivated user is
@@ -109,6 +110,20 @@ export async function POST(
       }
     }
 
+    await recordAuditEvent({
+      actor: {
+        userId: null,
+        organizationId: null,
+        authMethod: "kh-admin",
+        actorLabel: "KeeperHub admin",
+      },
+      action: "account.deactivated",
+      resourceType: "user",
+      resourceId: result.userId,
+      after: { deactivatedAt: result.deactivatedAt.toISOString() },
+      metadata: buildAuditMetadata(request),
+    });
+
     return NextResponse.json({
       userId: result.userId,
       deactivatedAt: result.deactivatedAt,

app/api/admin/workflows/[workflowId]/activate/route.ts

@@ -4,6 +4,7 @@ import { db } from "@/lib/db";
 import { workflows } from "@/lib/db/schema";
 import { authenticateKhAdmin } from "@/lib/kh-admin-auth";
 import { ErrorCategory, logSystemError } from "@/lib/logging";
+import { buildAuditMetadata, recordAuditEvent } from "@/lib/security/audit-log";
 
 export async function POST(
   request: Request,
@@ -53,6 +54,19 @@ export async function POST(
       return NextResponse.json({ error: "Workflow is not deactivated" }, { status: 409 });
     }
 
+    await recordAuditEvent({
+      actor: {
+        userId: null,
+        organizationId: null,
+        authMethod: "kh-admin",
+        actorLabel: "KeeperHub admin",
+      },
+      action: "workflow.reactivated",
+      resourceType: "workflow",
+      resourceId: result.workflowId,
+      metadata: buildAuditMetadata(request),
+    });
+
     return NextResponse.json(result);
   } catch (error) {
     logSystemError(ErrorCategory.DATABASE, "[Admin] Failed to activate workflow", error, {

app/api/admin/workflows/[workflowId]/deactivate/route.ts

@@ -4,6 +4,7 @@ import { db } from "@/lib/db";
 import { workflows } from "@/lib/db/schema";
 import { authenticateKhAdmin } from "@/lib/kh-admin-auth";
 import { ErrorCategory, logSystemError } from "@/lib/logging";
+import { buildAuditMetadata, recordAuditEvent } from "@/lib/security/audit-log";
 
 export async function POST(
   request: Request,
@@ -51,6 +52,20 @@ export async function POST(
       return NextResponse.json({ error: "Workflow is already deactivated" }, { status: 409 });
     }
 
+    await recordAuditEvent({
+      actor: {
+        userId: null,
+        organizationId: null,
+        authMethod: "kh-admin",
+        actorLabel: "KeeperHub admin",
+      },
+      action: "workflow.deactivated",
+      resourceType: "workflow",
+      resourceId: result.workflowId,
+      after: { deactivatedAt: result.deactivatedAt?.toISOString() },
+      metadata: buildAuditMetadata(request),
+    });
+
     return NextResponse.json(result);
   } catch (error) {
     logSystemError(ErrorCategory.DATABASE, "[Admin] Failed to deactivate workflow", error, {

app/api/agentic-wallet/[id]/approve/route.ts

@@ -37,6 +37,7 @@ import {
   requireDualFactor,
 } from "@/lib/mfa/dual-factor";
 import { requireMfaEnrolled } from "@/lib/middleware/owner-mfa-guard";
+import { buildAuditMetadata, recordAuditEvent } from "@/lib/security/audit-log";
 
 export const dynamic = "force-dynamic";
 
@@ -159,6 +160,18 @@ export async function POST(
         { status: 409 }
       );
     }
+    await recordAuditEvent({
+      actor: {
+        userId,
+        organizationId: null,
+        authMethod: "session",
+      },
+      action: "agentic_wallet.approval_granted",
+      resourceType: "agentic_wallet",
+      resourceId: id,
+      metadata: buildAuditMetadata(request),
+    });
+
     return NextResponse.json({ ok: true, status: "approved" });
   } catch (error) {
     logSystemError(ErrorCategory.DATABASE, "[Agentic] /approve failed", error, {

app/api/agentic-wallet/[id]/reject/route.ts

@@ -21,6 +21,7 @@ import {
   requireDualFactor,
 } from "@/lib/mfa/dual-factor";
 import { requireMfaEnrolled } from "@/lib/middleware/owner-mfa-guard";
+import { buildAuditMetadata, recordAuditEvent } from "@/lib/security/audit-log";
 
 export const dynamic = "force-dynamic";
 
@@ -137,6 +138,18 @@ export async function POST(
         { status: 409 }
       );
     }
+    await recordAuditEvent({
+      actor: {
+        userId,
+        organizationId: null,
+        authMethod: "session",
+      },
+      action: "agentic_wallet.approval_denied",
+      resourceType: "agentic_wallet",
+      resourceId: id,
+      metadata: buildAuditMetadata(request),
+    });
+
     return NextResponse.json({ ok: true, status: "rejected" });
   } catch (error) {
     logSystemError(ErrorCategory.DATABASE, "[Agentic] /reject failed", error, {

app/api/agentic-wallet/link/route.ts

@@ -39,6 +39,7 @@ import { auth } from "@/lib/auth";
 import { db } from "@/lib/db";
 import { agenticWallets } from "@/lib/db/schema";
 import { ErrorCategory, logSystemError } from "@/lib/logging";
+import { buildAuditMetadata, recordAuditEvent } from "@/lib/security/audit-log";
 
 export const dynamic = "force-dynamic";
 
@@ -137,6 +138,15 @@ export async function POST(request: Request): Promise<Response> {
       );
     }
 
+    await recordAuditEvent({
+      actor: { userId, organizationId: null, authMethod: "session" },
+      action: "agentic_wallet.linked",
+      resourceType: "agentic_wallet",
+      resourceId: subOrgId,
+      after: { linkedUserId: userId },
+      metadata: buildAuditMetadata(request),
+    });
+
     return Response.json({ ok: true }, { status: 200 });
   } catch (error) {
     logSystemError(ErrorCategory.DATABASE, "[Agentic] /link failed", error, {

app/api/agentic-wallet/rotate-hmac/route.ts

@@ -38,6 +38,7 @@ import { insertHmacSecret } from "@/lib/agentic-wallet/hmac-secret-store";
 import { db } from "@/lib/db";
 import { agenticWalletHmacSecrets } from "@/lib/db/schema";
 import { ErrorCategory, logSystemError } from "@/lib/logging";
+import { buildAuditMetadata, recordAuditEvent } from "@/lib/security/audit-log";
 
 export const dynamic = "force-dynamic";
 
@@ -82,6 +83,20 @@ export async function POST(request: Request): Promise<Response> {
         )
       );
 
+    await recordAuditEvent({
+      actor: {
+        userId: null,
+        organizationId: null,
+        authMethod: "internal",
+      },
+      action: "agentic_wallet.hmac_rotated",
+      resourceType: "agentic_wallet",
+      resourceId: auth.subOrgId,
+      before: { keyVersion: currentVersion },
+      after: { keyVersion: newVersion },
+      metadata: buildAuditMetadata(request),
+    });
+
     return Response.json(
       { newSecret, keyVersion: newVersion },
       { status: 200 }

app/api/agentic-wallet/sign/route.ts

@@ -48,6 +48,7 @@ import { verifyWorkflowBinding } from "@/lib/agentic-wallet/workflow-binding";
 import { db } from "@/lib/db";
 import { agenticWallets } from "@/lib/db/schema";
 import { ErrorCategory, logSystemError } from "@/lib/logging";
+import { buildAuditMetadata, recordAuditEvent } from "@/lib/security/audit-log";
 
 export const dynamic = "force-dynamic";
 
@@ -395,6 +396,24 @@ export async function POST(request: Request): Promise<Response> {
         });
       }
     }
+    // Auto-tier signature emitted. Record the operation (never the signature)
+    // so the wallet's signing activity is auditable. Ask-tier signs only after
+    // an approval, which is audited separately on /approve.
+    await recordAuditEvent({
+      actor: { userId: null, organizationId: null, authMethod: "internal" },
+      action: "agentic_wallet.signed",
+      resourceType: "agentic_wallet",
+      resourceId: auth.subOrgId,
+      after: {
+        chain,
+        risk,
+        walletAddress,
+        amountMicro: binding.expectedAmountMicro,
+        payTo: callerPayTo,
+      },
+      metadata: buildAuditMetadata(request),
+    });
+
     return Response.json({ signature }, { status: 200 });
   } catch (error) {
     // Fix-pack-3 N-2: only refund quota on TRANSIENT upstream failures. A

app/api/api-keys/[keyId]/route.ts

@@ -9,6 +9,8 @@ import {
   requireDualFactor,
 } from "@/lib/mfa/dual-factor";
 import { requireMfaEnrolled } from "@/lib/middleware/owner-mfa-guard";
+import { notifyApiKeyChange } from "@/lib/security/api-key-notification";
+import { buildAuditMetadata, recordAuditEvent } from "@/lib/security/audit-log";
 
 // DELETE - Delete an API key
 export async function DELETE(
@@ -58,15 +60,43 @@ export async function DELETE(
     }
 
     // Delete the key (only if it belongs to the user)
-    const result = await db
+    const [deleted] = await db
       .delete(apiKeys)
       .where(and(eq(apiKeys.id, keyId), eq(apiKeys.userId, session.user.id)))
-      .returning({ id: apiKeys.id });
+      .returning({
+        id: apiKeys.id,
+        name: apiKeys.name,
+        keyPrefix: apiKeys.keyPrefix,
+      });
 
-    if (result.length === 0) {
+    if (!deleted) {
       return NextResponse.json({ error: "API key not found" }, { status: 404 });
     }
 
+    // Out-of-band alert symmetric with creation: the owner learns a bypass
+    // credential was revoked even if their own session did it. Non-blocking.
+    notifyApiKeyChange({
+      email: session.user.email,
+      action: "revoked",
+      tokenName: deleted.name,
+      keyPrefix: deleted.keyPrefix,
+      when: new Date(),
+    });
+
+    // Durable forensic record of who revoked the key and from where.
+    await recordAuditEvent({
+      actor: {
+        userId: session.user.id,
+        organizationId: null,
+        authMethod: "session",
+      },
+      action: "api_key.revoked",
+      resourceType: "api_key",
+      resourceId: deleted.id,
+      before: { name: deleted.name, keyPrefix: deleted.keyPrefix },
+      metadata: buildAuditMetadata(request),
+    });
+
     return NextResponse.json({ success: true });
   } catch (error) {
     logSystemError(ErrorCategory.DATABASE, "Failed to delete API key", error, {