[Task: intentvision-mgn.1] Prod secrets + rotation runbook

.github/workflows/terraform-plan.yml

@@ -14,9 +14,10 @@ on:
     branches: [main]
     paths:
       - 'infrastructure/terraform/**'
-  schedule:
-    # Run daily at 6 AM UTC for drift detection
-    - cron: '0 6 * * *'
+  # schedule disabled — burns Actions minutes
+  # schedule:
+  #   # Run daily at 6 AM UTC for drift detection
+  #   - cron: '0 6 * * *'
   workflow_dispatch:
     inputs:
       environment:

000-docs/065-AT-RNBK-secrets-management.md

@@ -0,0 +1,203 @@
+# Secrets Management Runbook
+
+**Document ID:** 065-AT-RNBK-secrets-management
+**Category:** AT (Artifact) - RNBK (Runbook)
+**Status:** Active
+**Last Updated:** 2026-02-03
+
+---
+
+## Overview
+
+IntentVision uses Google Cloud Secret Manager for all sensitive credentials. Secrets are created via Terraform and values are set manually or via CI.
+
+## Naming Convention
+
+```
+{environment}-{service}-{key}
+```
+
+| Environment | Examples |
+|-------------|----------|
+| `staging` | `staging-turso-url`, `staging-nixtla-api-key` |
+| `production` | `production-turso-url`, `production-nixtla-api-key` |
+
+## Secret Inventory
+
+| Secret Name | Purpose | Required | Rotation |
+|-------------|---------|----------|----------|
+| `{env}-turso-url` | Turso database connection URL | Yes | On compromise |
+| `{env}-turso-token` | Turso authentication token | Yes | 90 days |
+| `{env}-nixtla-api-key` | Nixtla TimeGPT API key | No | On compromise |
+| `{env}-resend-api-key` | Resend email service API key | No | On compromise |
+
+## Creating Secrets (Terraform)
+
+Secrets are created empty by Terraform:
+
+```bash
+cd infrastructure/terraform
+
+# Staging
+terraform apply -var-file=environments/staging/terraform.tfvars
+
+# Production
+terraform apply -var-file=environments/production/terraform.tfvars
+```
+
+## Setting Secret Values
+
+### Via gcloud CLI
+
+```bash
+# Set a new secret value
+echo -n "your-secret-value" | gcloud secrets versions add {secret-name} --data-file=-
+
+# Example: Set production Turso URL
+echo -n "libsql://your-db.turso.io" | gcloud secrets versions add production-turso-url --data-file=-
+
+# Example: Set production Turso token
+echo -n "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..." | gcloud secrets versions add production-turso-token --data-file=-
+```
+
+### Via Console
+
+1. Go to [Secret Manager Console](https://console.cloud.google.com/security/secret-manager?project=intentvision)
+2. Click on the secret name
+3. Click "New Version"
+4. Enter the secret value
+5. Click "Add New Version"
+
+## Viewing Secrets
+
+```bash
+# List all secrets
+gcloud secrets list --filter="labels.app=intentvision"
+
+# List versions of a secret
+gcloud secrets versions list {secret-name}
+
+# Access latest version (requires secretAccessor role)
+gcloud secrets versions access latest --secret={secret-name}
+```
+
+## Rotation Procedure
+
+### 1. Generate New Credential
+
+Obtain new credential from the service provider:
+- **Turso:** Dashboard > Database > Generate Token
+- **Nixtla:** Dashboard > API Keys > Create
+- **Resend:** Dashboard > API Keys > Create
+
+### 2. Add New Version
+
+```bash
+echo -n "new-credential-value" | gcloud secrets versions add {secret-name} --data-file=-
+```
+
+### 3. Verify Application
+
+```bash
+# Trigger a new Cloud Run revision to pick up the new secret
+gcloud run services update intentvision-api-{env} \
+  --region=us-central1 \
+  --update-env-vars=ROTATION_TRIGGER=$(date +%s)
+
+# Verify health
+# Staging: https://stg.intentvision.intent-solutions.io/health
+# Production: https://api.intentvision.io/health
+curl https://{your-environment-url}/health
+```
+
+### 4. Disable Old Version (After Verification)
+
+```bash
+# List versions
+gcloud secrets versions list {secret-name}
+
+# Disable old version (keep for rollback window)
+gcloud secrets versions disable {version-id} --secret={secret-name}
+
+# Destroy old version (after 7 days)
+gcloud secrets versions destroy {version-id} --secret={secret-name}
+```
+
+## Emergency Rotation
+
+If a secret is compromised:
+
+```bash
+# 1. Immediately rotate at source (revoke old, create new)
+# 2. Add new version
+echo -n "new-value" | gcloud secrets versions add {secret-name} --data-file=-
+
+# 3. Force redeploy (replace {env} with staging or production)
+gcloud run services update intentvision-api-{env} \
+  --region=us-central1 \
+  --update-env-vars=EMERGENCY_ROTATION=$(date +%s)
+
+# 4. Destroy compromised version (find ID via: gcloud secrets versions list {secret-name})
+gcloud secrets versions destroy {version-id} --secret={secret-name}
+
+# 5. Audit access logs
+gcloud logging read 'resource.type="secretmanager.googleapis.com/Secret"' --limit=100
+```
+
+## Rotation Schedule
+
+| Secret Type | Frequency | Next Rotation |
+|-------------|-----------|---------------|
+| Turso tokens | 90 days | Track in calendar |
+| API keys | On compromise | N/A |
+
+## Access Control
+
+Secrets are accessible only to:
+- Cloud Run service account (`intentvision-api-{env}@intentvision.iam.gserviceaccount.com`)
+- Project owners (for management)
+
+IAM is granted per-secret, not project-wide (least privilege).
+
+## Troubleshooting
+
+### Secret Not Found
+
+```bash
+# Verify secret exists
+gcloud secrets describe {secret-name}
+
+# Check IAM bindings
+gcloud secrets get-iam-policy {secret-name}
+```
+
+### Access Denied
+
+```bash
+# Verify service account has access
+gcloud secrets get-iam-policy {secret-name} \
+  --format="table(bindings.role,bindings.members)"
+
+# Grant access if missing (via Terraform preferred)
+gcloud secrets add-iam-policy-binding {secret-name} \
+  --member="serviceAccount:{sa-email}" \
+  --role="roles/secretmanager.secretAccessor"
+```
+
+### Application Not Picking Up New Secret
+
+Cloud Run caches secrets. Force a new revision:
+
+```bash
+gcloud run services update intentvision-api-{env} \
+  --region=us-central1 \
+  --update-env-vars=SECRET_REFRESH=$(date +%s)
+```
+
+---
+
+## References
+
+- [Secret Manager Documentation](https://cloud.google.com/secret-manager/docs)
+- [Terraform secrets.tf](../infrastructure/terraform/secrets.tf)
+- [Deploy Runbook](./051-AT-RNBK-intentvision-deploy-rollback.md)

Dockerfile

@@ -31,6 +31,7 @@ RUN npm ci --include=dev
 
 # Copy source code
 COPY packages/ ./packages/
+COPY db/ ./db/
 COPY tsconfig*.json ./
 
 # Build all packages in dependency order

package.json

@@ -23,7 +23,7 @@
     "db:migrate": "npx tsx db/migrate.ts run",
     "db:status": "npx tsx db/migrate.ts status",
     "arv": "./scripts/ci/arv-check.sh",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc -p packages/contracts --noEmit && tsc -p packages/pipeline --noEmit && tsc -p packages/sdk --noEmit"
   },
   "repository": {
     "type": "git",

packages/api/src/agent/a2a-client.ts

@@ -95,7 +95,7 @@ export class A2AGatewayClient {
    */
   async health(): Promise<GatewayHealth> {
     const response = await this.fetch('/health');
-    return response as GatewayHealth;
+    return response as unknown as GatewayHealth;
   }
 
   // ===========================================================================
@@ -107,15 +107,15 @@ export class A2AGatewayClient {
    */
   async listAgents(): Promise<string[]> {
     const response = await this.fetch('/agents');
-    return response as string[];
+    return response as unknown as string[];
   }
 
   /**
    * Get agent card for A2A protocol discovery
    */
   async getAgentCard(agentName: string): Promise<AgentCard> {
     const response = await this.fetch(`/agents/${agentName}/.well-known/agent-card.json`);
-    return response as AgentCard;
+    return response as unknown as AgentCard;
   }
 
   // ===========================================================================
@@ -130,7 +130,7 @@ export class A2AGatewayClient {
       method: 'POST',
       body: JSON.stringify(request),
     });
-    return response as TaskStatus;
+    return response as unknown as TaskStatus;
   }
 
   // ===========================================================================
@@ -148,7 +148,7 @@ export class A2AGatewayClient {
       method: 'POST',
       body: JSON.stringify(request),
     });
-    return response as ChatResponse;
+    return response as unknown as ChatResponse;
   }
 
   // ===========================================================================
@@ -243,7 +243,7 @@ export class A2AGatewayClient {
         );
       }
 
-      return await response.json();
+      return await response.json() as Record<string, unknown>;
     } catch (error) {
       clearTimeout(timeoutId);
 

packages/api/src/tests/health.test.ts

@@ -7,7 +7,7 @@
  * Tests response structure without requiring external dependencies.
  */
 
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi } from 'vitest';
 import { ServerResponse } from 'http';
 import {
   handleBasicHealth,

packages/contracts/src/metrics-spine.ts

@@ -178,6 +178,9 @@ export interface TimeSeries {
 
     /** Detected resolution (e.g., "1m", "5m", "1h") */
     resolution?: string;
+
+    /** Aggregation method (e.g., "avg", "sum", "max") */
+    aggregation?: string;
   };
 }
 

packages/contracts/tsconfig.json

@@ -13,7 +13,8 @@
     "declaration": true,
     "declarationMap": true,
     "sourceMap": true,
-    "resolveJsonModule": true
+    "resolveJsonModule": true,
+    "composite": true
   },
   "include": ["src/**/*"],
   "exclude": ["node_modules", "dist", "tests", "fixtures"]

packages/operator/src/api/router.ts

@@ -185,7 +185,7 @@ export function createDefaultRouter(): ApiRouter {
 
   // Create API key (admin scope required)
   router.route('POST', '/api/v1/keys', async (req, ctx) => {
-    const body = req.body as { name?: string; scopes?: string[]; expires_in_days?: number };
+    const body = req.body as { name?: string; roles?: string[]; expires_in_days?: number };
     if (!body?.name) {
       return {
         status: 400,
@@ -197,7 +197,7 @@ export function createDefaultRouter(): ApiRouter {
     const { key, rawKey } = await manager.createKey({
       orgId: ctx.orgId,
       name: body.name,
-      scopes: body.scopes,
+      roles: body.roles,
       expiresInDays: body.expires_in_days,
     });
 
@@ -207,7 +207,7 @@ export function createDefaultRouter(): ApiRouter {
         key_id: key.keyId,
         raw_key: rawKey,
         name: key.name,
-        scopes: key.scopes,
+        roles: key.roles,
         expires_at: key.expiresAt,
         message: 'Store this key securely - it will not be shown again',
       },

packages/operator/src/auth/api-key.ts

@@ -207,7 +207,7 @@ export class ApiKeyManager {
       args: [orgId],
     });
 
-    return result.rows.map((row) => ({
+    return result.rows.map((row: Record<string, unknown>) => ({
       keyId: row.key_id as string,
       keyHash: row.key_hash as string,
       orgId: row.org_id as string,

packages/operator/src/auth/api-keys.ts

@@ -257,7 +257,7 @@ export class ApiKeyManager {
       args: [orgId],
     });
 
-    return result.rows.map((row) => ({
+    return result.rows.map((row: Record<string, unknown>) => ({
       keyId: row.key_id as string,
       keyHash: row.key_hash as string,
       orgId: row.org_id as string,

packages/operator/src/auth/middleware.ts

@@ -47,6 +47,8 @@ export interface AuthResult {
 export interface AuthMiddlewareConfig {
   /** Required permissions for this endpoint */
   requiredPermissions?: Permission[];
+  /** Required scopes for this endpoint */
+  requiredScopes?: string[];
   /** Allow unauthenticated requests */
   allowAnonymous?: boolean;
 }

packages/operator/src/tenant/context.ts

@@ -10,7 +10,7 @@
  */
 
 import { v4 as uuidv4 } from 'uuid';
-import type { ApiKey } from '../auth/api-key.js';
+import type { ApiKey } from '../auth/api-keys.js';
 
 // =============================================================================
 // Types

packages/operator/tsconfig.json

@@ -7,10 +7,10 @@
     "strict": true,
     "skipLibCheck": true,
     "outDir": "./dist",
-    "rootDir": "./src",
+    "rootDir": "../..",
     "declaration": true,
     "declarationMap": true
   },
-  "include": ["src/**/*"],
+  "include": ["src/**/*", "../../db/**/*"],
   "exclude": ["node_modules", "dist", "tests"]
 }