feat(#353): Create VaultService NestJS module for OpenBao Transit

Implements secure credential encryption using OpenBao Transit API with
automatic fallback to AES-256-GCM when OpenBao is unavailable.

Features:
- AppRole authentication with automatic token renewal at 50% TTL
- Transit encrypt/decrypt with 4 named keys
- Automatic fallback to CryptoService when OpenBao unavailable
- Auto-detection of ciphertext format (vault:v1: vs AES)
- Request timeout protection (5s default)
- Health indicator for monitoring
- Backward compatible with existing AES-encrypted data

Security:
- ERROR-level logging for fallback
- Proper error propagation (no silent failures)
- Request timeouts prevent hung operations
- Secure credential file reading

Migrations:
- Account encryption middleware uses VaultService
- Uses TransitKey.ACCOUNT_TOKENS for OAuth tokens
- Backward compatible with existing encrypted data

Tests: 56 tests passing (36 VaultService + 20 middleware)

Closes #353

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

apps/api/src/prisma/account-encryption.middleware.spec.ts

@@ -399,8 +399,8 @@ describe("AccountEncryptionMiddleware", () => {
       expect(result.accessToken).toBe(plaintextToken);
     });
 
-    it("should handle vault ciphertext format (future-proofing)", async () => {
-      // Simulate future Transit encryption format
+    it("should throw error on vault ciphertext when OpenBao unavailable", async () => {
+      // Simulate vault Transit encryption format when OpenBao is unavailable
       const vaultCiphertext = "vault:v1:base64encodeddata";
 
       const mockParams = {
@@ -419,13 +419,13 @@ describe("AccountEncryptionMiddleware", () => {
         accessToken: vaultCiphertext,
         refreshToken: null,
         idToken: null,
-        encryptionVersion: "vault", // Future: vault encryption
+        encryptionVersion: "vault", // vault encryption
       }));
 
-      const result = (await middlewareFunction(mockParams, mockNext)) as any;
-
-      // Should pass through unchanged (vault not implemented yet)
-      expect(result.accessToken).toBe(vaultCiphertext);
+      // Should throw error because VaultService can't decrypt vault:v1: without OpenBao
+      await expect(middlewareFunction(mockParams, mockNext)).rejects.toThrow(
+        "Failed to decrypt account credentials"
+      );
     });
 
     it("should use encryptionVersion as primary discriminator", async () => {
@@ -457,7 +457,7 @@ describe("AccountEncryptionMiddleware", () => {
       expect(result.accessToken).toBe(fakeEncryptedToken);
     });
 
-    it("should handle corrupted encrypted data gracefully", async () => {
+    it("should throw error on corrupted encrypted data", async () => {
       // Test with malformed/corrupted encrypted token
       const corruptedToken = "deadbeef:cafebabe:corrupted_data_xyz"; // Valid format but wrong data
 
@@ -480,15 +480,13 @@ describe("AccountEncryptionMiddleware", () => {
         encryptionVersion: "aes", // Marked as encrypted
       }));
 
-      // Should not throw - just log error and pass through
-      const result = (await middlewareFunction(mockParams, mockNext)) as any;
-
-      // Token should remain unchanged if decryption fails
-      expect(result.accessToken).toBe(corruptedToken);
-      expect(result.encryptionVersion).toBe("aes");
+      // Should throw error - decryption failures are now propagated to prevent silent corruption
+      await expect(middlewareFunction(mockParams, mockNext)).rejects.toThrow(
+        "Failed to decrypt account credentials"
+      );
     });
 
-    it("should handle completely malformed encrypted format", async () => {
+    it("should throw error on completely malformed encrypted format", async () => {
       // Test with data that doesn't match expected format at all
       const malformedToken = "this:is:not:valid:encrypted:data:too:many:parts";
 
@@ -511,10 +509,10 @@ describe("AccountEncryptionMiddleware", () => {
         encryptionVersion: "aes",
       }));
 
-      // Should not throw - decryption will fail and token passes through
-      const result = (await middlewareFunction(mockParams, mockNext)) as any;
-
-      expect(result.accessToken).toBe(malformedToken);
+      // Should throw error - malformed data cannot be decrypted
+      await expect(middlewareFunction(mockParams, mockNext)).rejects.toThrow(
+        "Failed to decrypt account credentials"
+      );
     });
   });
 

apps/api/src/prisma/account-encryption.middleware.ts

@@ -21,7 +21,8 @@
 
 import { Logger } from "@nestjs/common";
 import type { PrismaClient } from "@prisma/client";
-import type { CryptoService } from "../federation/crypto.service";
+import type { VaultService } from "../vault/vault.service";
+import { TransitKey } from "../vault/vault.constants";
 
 /**
  * Token fields to encrypt/decrypt in Account model
@@ -59,11 +60,11 @@ interface AccountData extends Record<string, unknown> {
  * Register account encryption middleware on Prisma client
  *
  * @param prisma - Prisma client instance
- * @param cryptoService - Crypto service for encryption/decryption
+ * @param vaultService - Vault service for encryption/decryption
  */
 export function registerAccountEncryptionMiddleware(
   prisma: PrismaClient,
-  cryptoService: CryptoService
+  vaultService: VaultService
 ): void {
   const logger = new Logger("AccountEncryptionMiddleware");
 
@@ -88,15 +89,15 @@ export function registerAccountEncryptionMiddleware(
         params.action === "updateMany"
       ) {
         if (params.args.data) {
-          encryptTokens(params.args.data as AccountData, cryptoService);
+          await encryptTokens(params.args.data as AccountData, vaultService);
         }
       } else if (params.action === "upsert") {
         // Handle upsert - encrypt both create and update data
         if (params.args.create) {
-          encryptTokens(params.args.create as AccountData, cryptoService);
+          await encryptTokens(params.args.create as AccountData, vaultService);
         }
         if (params.args.update) {
-          encryptTokens(params.args.update as AccountData, cryptoService);
+          await encryptTokens(params.args.update as AccountData, vaultService);
         }
       }
 
@@ -106,15 +107,15 @@ export function registerAccountEncryptionMiddleware(
       // Decrypt on read operations
       if (params.action === "findUnique" || params.action === "findFirst") {
         if (result && typeof result === "object") {
-          decryptTokens(result as AccountData, cryptoService, logger);
+          await decryptTokens(result as AccountData, vaultService, logger);
         }
       } else if (params.action === "findMany") {
         if (Array.isArray(result)) {
-          result.forEach((account: unknown) => {
+          for (const account of result) {
             if (account && typeof account === "object") {
-              decryptTokens(account as AccountData, cryptoService, logger);
+              await decryptTokens(account as AccountData, vaultService, logger);
             }
-          });
+          }
         }
       }
 
@@ -128,39 +129,43 @@ export function registerAccountEncryptionMiddleware(
  * Modifies data in-place
  *
  * @param data - Account data object
- * @param cryptoService - Crypto service
+ * @param vaultService - Vault service
  */
-function encryptTokens(data: AccountData, cryptoService: CryptoService): void {
+async function encryptTokens(data: AccountData, vaultService: VaultService): Promise<void> {
   let encrypted = false;
+  let encryptionVersion: "aes" | "vault" | null = null;
 
-  TOKEN_FIELDS.forEach((field) => {
+  for (const field of TOKEN_FIELDS) {
     const value = data[field];
 
     // Skip null/undefined values
     if (value == null) {
-      return;
+      continue;
     }
 
     // Skip if already encrypted (idempotent)
     if (typeof value === "string" && isEncrypted(value)) {
-      return;
+      continue;
     }
 
     // Encrypt plaintext value
     if (typeof value === "string") {
-      data[field] = cryptoService.encrypt(value);
+      const ciphertext = await vaultService.encrypt(value, TransitKey.ACCOUNT_TOKENS);
+      data[field] = ciphertext;
       encrypted = true;
-    }
-  });
 
-  // Mark as encrypted with AES if any tokens were encrypted
-  // Note: This condition is necessary because TypeScript's control flow analysis doesn't track
-  // the `encrypted` flag through forEach closures. The flag starts as false and is only set to
-  // true when a token is actually encrypted. This prevents setting encryptionVersion='aes' on
-  // records that have no tokens or only null/already-encrypted tokens (idempotent safety).
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-  if (encrypted) {
-    data.encryptionVersion = "aes";
+      // Determine encryption version from ciphertext format
+      if (ciphertext.startsWith("vault:v1:")) {
+        encryptionVersion = "vault";
+      } else {
+        encryptionVersion = "aes";
+      }
+    }
+  }
+
+  // Mark encryption version if any tokens were encrypted
+  if (encrypted && encryptionVersion) {
+    data.encryptionVersion = encryptionVersion;
   }
 }
 
@@ -172,49 +177,56 @@ function encryptTokens(data: AccountData, cryptoService: CryptoService): void {
  * if decryption is needed, falling back to pattern matching for
  * records without the field (migration compatibility).
  *
+ * Throws errors on decryption failure to prevent silent corruption.
+ *
  * @param account - Account record
- * @param cryptoService - Crypto service
- * @param logger - NestJS logger for error reporting
+ * @param vaultService - Vault service
+ * @param _logger - NestJS logger (unused, kept for compatibility with middleware signature)
+ * @throws Error with user-facing message when decryption fails
  */
-function decryptTokens(account: AccountData, cryptoService: CryptoService, logger: Logger): void {
+async function decryptTokens(
+  account: AccountData,
+  vaultService: VaultService,
+  _logger: Logger
+): Promise<void> {
   // Check encryptionVersion field first (primary discriminator)
-  const shouldDecrypt = account.encryptionVersion === "aes";
+  const shouldDecrypt =
+    account.encryptionVersion === "aes" || account.encryptionVersion === "vault";
 
-  TOKEN_FIELDS.forEach((field) => {
+  for (const field of TOKEN_FIELDS) {
     const value = account[field];
 
     // Skip null/undefined values
     if (value == null) {
-      return;
+      continue;
     }
 
     if (typeof value === "string") {
       // Primary path: Use encryptionVersion field
       if (shouldDecrypt) {
         try {
-          account[field] = cryptoService.decrypt(value);
+          account[field] = await vaultService.decrypt(value, TransitKey.ACCOUNT_TOKENS);
         } catch (error) {
-          // Log decryption failure but don't crash
-          // This allows the app to continue if a token is corrupted
-          // Security: Only log error type, not stack trace which may contain encrypted/decrypted data
-          const errorType = error instanceof Error ? error.constructor.name : "Unknown";
-          logger.error(`Failed to decrypt ${field} for account: ${errorType}`);
+          const errorMsg = error instanceof Error ? error.message : "Unknown error";
+          throw new Error(
+            `Failed to decrypt account credentials. Please reconnect this account. Details: ${errorMsg}`
+          );
         }
       }
       // Fallback: For records without encryptionVersion (migration compatibility)
-      else if (!account.encryptionVersion && isAESEncrypted(value)) {
+      else if (!account.encryptionVersion && isEncrypted(value)) {
         try {
-          account[field] = cryptoService.decrypt(value);
+          account[field] = await vaultService.decrypt(value, TransitKey.ACCOUNT_TOKENS);
         } catch (error) {
-          // Security: Only log error type, not stack trace which may contain encrypted/decrypted data
-          const errorType = error instanceof Error ? error.constructor.name : "Unknown";
-          logger.error(`Failed to decrypt ${field} (fallback mode): ${errorType}`);
+          const errorMsg = error instanceof Error ? error.message : "Unknown error";
+          throw new Error(
+            `Failed to decrypt account credentials. Please reconnect this account. Details: ${errorMsg}`
+          );
         }
       }
-      // Vault format (encryptionVersion === 'vault') - pass through for now (Phase 2)
       // Legacy plaintext (no encryptionVersion) - pass through unchanged
     }
-  });
+  }
 }
 
 /**

apps/api/src/prisma/prisma.module.ts

@@ -1,18 +1,19 @@
 import { Global, Module } from "@nestjs/common";
 import { ConfigModule } from "@nestjs/config";
 import { PrismaService } from "./prisma.service";
-import { CryptoService } from "../federation/crypto.service";
+import { VaultModule } from "../vault/vault.module";
 
 /**
  * Global Prisma module providing database access throughout the application
  * Marked as @Global() so PrismaService is available in all modules without importing
  *
- * Includes CryptoService for transparent Account token encryption (Issue #352)
+ * Includes VaultModule for transparent Account token encryption via OpenBao Transit
+ * with AES-256-GCM fallback (Issue #353)
  */
 @Global()
 @Module({
-  imports: [ConfigModule],
-  providers: [PrismaService, CryptoService],
+  imports: [ConfigModule, VaultModule],
+  providers: [PrismaService],
   exports: [PrismaService],
 })
 export class PrismaModule {}

apps/api/src/prisma/prisma.service.spec.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import { Test, TestingModule } from "@nestjs/testing";
 import { ConfigService } from "@nestjs/config";
 import { PrismaService } from "./prisma.service";
+import { VaultService } from "../vault/vault.service";
 import { CryptoService } from "../federation/crypto.service";
 
 describe("PrismaService", () => {
@@ -12,11 +13,13 @@ describe("PrismaService", () => {
     // Mock ConfigService with a valid test encryption key
     mockConfigService = {
       get: vi.fn((key: string) => {
-        if (key === "ENCRYPTION_KEY") {
-          // Valid 64-character hex string (32 bytes)
-          return "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
-        }
-        return null;
+        const config: Record<string, string> = {
+          ENCRYPTION_KEY: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+          OPENBAO_ADDR: "http://localhost:8200",
+          OPENBAO_ROLE_ID: "test-role-id",
+          OPENBAO_SECRET_ID: "test-secret-id",
+        };
+        return config[key] || null;
       }),
     };
 
@@ -27,6 +30,7 @@ describe("PrismaService", () => {
           provide: ConfigService,
           useValue: mockConfigService,
         },
+        VaultService,
         CryptoService,
       ],
     }).compile();

apps/api/src/prisma/prisma.service.ts

@@ -1,20 +1,21 @@
 import { Injectable, Logger, OnModuleDestroy, OnModuleInit } from "@nestjs/common";
 import { PrismaClient } from "@prisma/client";
-import { CryptoService } from "../federation/crypto.service";
+import { VaultService } from "../vault/vault.service";
 import { registerAccountEncryptionMiddleware } from "./account-encryption.middleware";
 
 /**
  * Prisma service that manages database connection lifecycle
  * Extends PrismaClient to provide connection management and health checks
  *
- * IMPORTANT: CryptoService is required (not optional) because it will throw
- * if ENCRYPTION_KEY is not configured, providing fail-fast behavior.
+ * IMPORTANT: VaultService is required (not optional) for encryption/decryption
+ * of sensitive Account tokens. It automatically falls back to AES-256-GCM when
+ * OpenBao is unavailable.
  */
 @Injectable()
 export class PrismaService extends PrismaClient implements OnModuleInit, OnModuleDestroy {
   private readonly logger = new Logger(PrismaService.name);
 
-  constructor(private readonly cryptoService: CryptoService) {
+  constructor(private readonly vaultService: VaultService) {
     super({
       log: process.env.NODE_ENV === "development" ? ["query", "info", "warn", "error"] : ["error"],
     });
@@ -29,8 +30,8 @@ export class PrismaService extends PrismaClient implements OnModuleInit, OnModul
       this.logger.log("Database connection established");
 
       // Register Account token encryption middleware
-      // CryptoService constructor will have already validated ENCRYPTION_KEY exists
-      registerAccountEncryptionMiddleware(this, this.cryptoService);
+      // VaultService provides OpenBao Transit encryption with AES-256-GCM fallback
+      registerAccountEncryptionMiddleware(this, this.vaultService);
       this.logger.log("Account encryption middleware registered");
     } catch (error) {
       this.logger.error("Failed to connect to database", error);