Merge branch 'main' into krishna9358/template-library

Signed-off-by: Krishna Mohan <krishanmohank974@gmail.com>

Author: krishna9358

AGENTS.md

@@ -27,6 +27,16 @@ just instance show     # Print active instance number
 just instance use 5    # Set active instance for this workspace
 ```
 
+**Instance env files**:
+
+```bash
+just instance-init 5           # Initialize .instances/instance-5/*.env
+just instance-env init 5       # Create from app/.env or app/.env.example
+just instance-env update 5     # Re-apply instance-scoped vars
+just instance-env copy 5 6     # Copy env setup from instance 5 -> 6
+just instance-env show 6       # Show file status and computed values
+```
+
 **URLs**:
 
 - Frontend: `http://localhost:${5173 + instance*100}`
@@ -43,14 +53,15 @@ Local development runs as **multiple app instances** (PM2) on top of **one share
 - Per-instance apps: `shipsec-{frontend,backend,worker}-N`.
 - Isolation is via per-instance DB + Temporal namespace/task queue + Kafka topic suffixing + instance-scoped Kafka consumer groups/client IDs (not per-instance infra containers).
 - The workspace can have an **active instance** (stored in `.shipsec-instance`, gitignored).
+- Instance env files are stored at `.instances/instance-N/{backend,worker,frontend}.env` and can be managed with `just instance-env ...`.
 
 **Agent rule:** before running any dev commands, ensure you’re targeting the intended instance.
 
 - Always check: `just instance show`
 - If the task is ambiguous (logs, curl, E2E, “run locally”, etc.), ask the user which instance to use.
 - If the user says “use instance N”, prefer either:
   - `just instance use N` then run `just dev` / `bun run test:e2e`, or
-  - explicit instance invocation (`just dev N ...`) for one-off commands.
+  - explicit env override (`SHIPSEC_INSTANCE=N just dev ...`) for one-off commands.
 
 **Ports / URLs**
 
@@ -61,7 +72,7 @@ Local development runs as **multiple app instances** (PM2) on top of **one share
 **E2E tests**
 
 - E2E targets the backend for `SHIPSEC_INSTANCE` (or the active instance).
-- When asked to run E2E, confirm the instance and ensure that instance is running: `just dev N start`.
+- When asked to run E2E, confirm the instance and ensure that instance is running: `SHIPSEC_INSTANCE=N just dev start` (or `just instance use N` then `just dev start`).
 
 **Keep docs in sync**
 

README.md

@@ -137,8 +137,12 @@ Run multiple isolated dev instances on one machine for parallel feature work:
 # Instance 0 (default)
 just dev
 
-# Instance 1 — offset ports (frontend :5273, backend :3311)
-SHIPSEC_INSTANCE=1 just dev
+# Switch active workspace instance
+just instance use 1
+just dev
+
+# Manage per-instance env files
+just instance-env init 1
 ```
 
 Each instance gets its own frontend port, backend port, database, and Temporal namespace while sharing a single Docker infra stack. See [Multi-Instance Development Guide](docs/MULTI-INSTANCE-DEV.md) for full details.

backend/drizzle/0020_create-audit-logs.sql

@@ -0,0 +1,21 @@
+CREATE TABLE IF NOT EXISTS "audit_logs" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "organization_id" varchar(191),
+  "actor_id" varchar(191),
+  "actor_type" varchar(32) NOT NULL,
+  "actor_display" varchar(191),
+  "action" varchar(64) NOT NULL,
+  "resource_type" varchar(32) NOT NULL,
+  "resource_id" varchar(191),
+  "resource_name" varchar(191),
+  "metadata" jsonb,
+  "ip" varchar(64),
+  "user_agent" text,
+  "created_at" timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS "audit_logs_org_created_at_idx" ON "audit_logs" ("organization_id", "created_at" DESC);
+CREATE INDEX IF NOT EXISTS "audit_logs_org_resource_idx" ON "audit_logs" ("organization_id", "resource_type", "resource_id");
+CREATE INDEX IF NOT EXISTS "audit_logs_org_action_created_at_idx" ON "audit_logs" ("organization_id", "action", "created_at" DESC);
+CREATE INDEX IF NOT EXISTS "audit_logs_org_actor_created_at_idx" ON "audit_logs" ("organization_id", "actor_id", "created_at" DESC);
+

backend/scripts/generate-openapi.ts

@@ -11,6 +11,12 @@ async function generateOpenApi() {
   // Skip ingest services that require external connections during OpenAPI generation
   process.env.SKIP_INGEST_SERVICES = 'true';
   process.env.SHIPSEC_SKIP_MIGRATION_CHECK = 'true';
+  // Ensure encryption services can bootstrap during schema generation.
+  // This key is only used to construct the Nest application for OpenAPI output.
+  process.env.SECRET_STORE_MASTER_KEY =
+    process.env.SECRET_STORE_MASTER_KEY ?? 'shipsec-openapi-master-key-32bxx';
+  process.env.INTEGRATION_STORE_MASTER_KEY =
+    process.env.INTEGRATION_STORE_MASTER_KEY ?? 'shipsec-openapi-master-key-32bxx';
 
   const { AppModule } = await import('../src/app.module');
 

backend/src/analytics/analytics.controller.ts

@@ -22,6 +22,7 @@ import {
   UpdateAnalyticsSettingsDto,
   TIER_LIMITS,
 } from './dto/analytics-settings.dto';
+import { AuditLogService } from '../audit/audit-log.service';
 import { CurrentAuth } from '../auth/auth-context.decorator';
 import { Public } from '../auth/public.decorator';
 import type { AuthContext } from '../auth/types';
@@ -43,6 +44,7 @@ export class AnalyticsController {
     private readonly organizationSettingsService: OrganizationSettingsService,
     private readonly openSearchTenantService: OpenSearchTenantService,
     private readonly configService: ConfigService,
+    private readonly auditLogService: AuditLogService,
   ) {
     this.internalServiceToken = this.configService.get<string>('INTERNAL_SERVICE_TOKEN') || '';
   }
@@ -106,6 +108,19 @@ export class AnalyticsController {
       throw new BadRequestException(`Invalid from: maximum is ${MAX_QUERY_FROM}`);
     }
 
+    this.auditLogService.record(auth, {
+      action: 'analytics.query',
+      resourceType: 'analytics',
+      resourceId: null,
+      resourceName: null,
+      metadata: {
+        size,
+        from,
+        hasQuery: Boolean(queryDto.query),
+        hasAggs: Boolean(queryDto.aggs),
+      },
+    });
+
     // Call the service to execute the query
     return this.securityAnalyticsService.query(auth.organizationId, {
       query: queryDto.query,

backend/src/api-keys/api-keys.service.ts

@@ -14,6 +14,7 @@ import * as crypto from 'crypto';
 import * as bcrypt from 'bcryptjs';
 import type { CreateApiKeyDto, ListApiKeysQueryDto, UpdateApiKeyDto } from './dto/api-key.dto';
 import type { AuthContext } from '../auth/types';
+import { AuditLogService } from '../audit/audit-log.service';
 
 const KEY_PREFIX = 'sk_live_';
 
@@ -24,6 +25,7 @@ export class ApiKeysService {
   constructor(
     @Inject(DRIZZLE_TOKEN)
     private readonly db: NodePgDatabase<typeof schema>,
+    private readonly auditLogService: AuditLogService,
   ) {}
 
   async create(auth: AuthContext, dto: CreateApiKeyDto) {
@@ -51,6 +53,17 @@ export class ApiKeysService {
       })
       .returning();
 
+    this.auditLogService.record(auth, {
+      action: 'api_key.create',
+      resourceType: 'api_key',
+      resourceId: apiKey.id,
+      resourceName: apiKey.name,
+      metadata: {
+        isActive: apiKey.isActive,
+        expiresAt: apiKey.expiresAt?.toISOString() ?? null,
+      },
+    });
+
     return { apiKey, plainKey };
   }
 
@@ -109,6 +122,23 @@ export class ApiKeysService {
       throw new NotFoundException('API key not found');
     }
 
+    const action =
+      dto.isActive === false
+        ? 'api_key.revoke'
+        : dto.isActive === true
+          ? 'api_key.reactivate'
+          : 'api_key.update';
+    this.auditLogService.record(auth, {
+      action,
+      resourceType: 'api_key',
+      resourceId: apiKey.id,
+      resourceName: apiKey.name,
+      metadata: {
+        updatedFields: Object.keys(dto),
+        isActive: apiKey.isActive,
+      },
+    });
+
     return apiKey;
   }
 
@@ -117,13 +147,27 @@ export class ApiKeysService {
       throw new NotFoundException('API key not found');
     }
 
+    const existing = await this.db
+      .select()
+      .from(apiKeys)
+      .where(and(eq(apiKeys.id, id), eq(apiKeys.organizationId, auth.organizationId)))
+      .limit(1)
+      .then((rows) => rows[0] ?? null);
+
     const result = await this.db
       .delete(apiKeys)
       .where(and(eq(apiKeys.id, id), eq(apiKeys.organizationId, auth.organizationId)));
 
     if (result.rowCount === 0) {
       throw new NotFoundException('API key not found');
     }
+
+    this.auditLogService.record(auth, {
+      action: 'api_key.delete',
+      resourceType: 'api_key',
+      resourceId: id,
+      resourceName: existing?.name ?? null,
+    });
   }
 
   async validateKey(plainKey: string): Promise<ApiKey | null> {

backend/src/api-keys/dto/api-key.dto.ts

@@ -8,11 +8,17 @@ export const ApiKeyPermissionsSchema = z.object({
     run: z.boolean(),
     list: z.boolean(),
     read: z.boolean(),
+    create: z.boolean().optional(),
+    update: z.boolean().optional(),
+    delete: z.boolean().optional(),
   }),
   runs: z.object({
     read: z.boolean(),
     cancel: z.boolean(),
   }),
+  audit: z.object({
+    read: z.boolean(),
+  }),
 });
 
 export const CreateApiKeySchema = z.object({

backend/src/app.module.ts

@@ -27,6 +27,7 @@ import { SchedulesModule } from './schedules/schedules.module';
 import { AnalyticsModule } from './analytics/analytics.module';
 import { McpModule } from './mcp/mcp.module';
 import { StudioMcpModule } from './studio-mcp/studio-mcp.module';
+import { AuditModule } from './audit/audit.module';
 
 import { ApiKeysModule } from './api-keys/api-keys.module';
 import { WebhooksModule } from './webhooks/webhooks.module';
@@ -54,6 +55,7 @@ const coreModules = [
   McpModule,
   StudioMcpModule,
   TemplatesModule,
+  AuditModule,
 ];
 
 const testingModules = process.env.NODE_ENV === 'production' ? [] : [TestingSupportModule];

backend/src/audit/__tests__/audit-log.service.spec.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from 'bun:test';
+
+import type { AuthContext } from '../../auth/types';
+import { AuditLogService } from '../audit-log.service';
+import type { AuditLogRepository } from '../audit-log.repository';
+
+function makeAuth(overrides: Partial<AuthContext> = {}): AuthContext {
+  return {
+    userId: 'user-1',
+    organizationId: 'org-1',
+    roles: ['MEMBER'],
+    isAuthenticated: true,
+    provider: 'local',
+    ...overrides,
+  };
+}
+
+describe('AuditLogService', () => {
+  it('allows org admins to read audit logs', () => {
+    const repo: AuditLogRepository = {
+      insert: async () => {},
+      list: async () => [],
+    } as any;
+    const service = new AuditLogService(repo);
+    expect(service.canRead(makeAuth({ roles: ['ADMIN'] }))).toBe(true);
+  });
+
+  it('allows API keys with audit.read=true to read audit logs', () => {
+    const repo: AuditLogRepository = {
+      insert: async () => {},
+      list: async () => [],
+    } as any;
+    const service = new AuditLogService(repo);
+    expect(
+      service.canRead(
+        makeAuth({
+          provider: 'api-key',
+          roles: ['MEMBER'],
+          apiKeyPermissions: {
+            workflows: { run: false, list: false, read: false },
+            runs: { read: false, cancel: false },
+            audit: { read: true },
+          },
+        }),
+      ),
+    ).toBe(true);
+  });
+
+  it('denies API keys without audit.read', () => {
+    const repo: AuditLogRepository = {
+      insert: async () => {},
+      list: async () => [],
+    } as any;
+    const service = new AuditLogService(repo);
+    expect(
+      service.canRead(
+        makeAuth({
+          provider: 'api-key',
+          roles: ['MEMBER'],
+          apiKeyPermissions: {
+            workflows: { run: true, list: true, read: true },
+            runs: { read: true, cancel: true },
+            audit: { read: false },
+          },
+        }),
+      ),
+    ).toBe(false);
+  });
+
+  it('record() never throws even if repository insert fails', async () => {
+    let called = false;
+    const repo: AuditLogRepository = {
+      insert: async () => {
+        called = true;
+        throw new Error('db down');
+      },
+      list: async () => [],
+    } as any;
+    const service = new AuditLogService(repo);
+
+    expect(() =>
+      service.record(makeAuth({ roles: ['ADMIN'] }), {
+        action: 'secret.access',
+        resourceType: 'secret',
+        resourceId: 'secret-1',
+        resourceName: 'foo',
+        metadata: { requestedVersion: 1 },
+      }),
+    ).not.toThrow();
+
+    // Flush microtasks (record uses queueMicrotask).
+    await Promise.resolve();
+    expect(called).toBe(true);
+  });
+});