Implement Secure Credential Management System

[coderabbitai]

Overview

Build a secure system for storing and managing API keys, OAuth tokens, and other credentials used by plugins.

Context

Related to PR #40 - Plugins need secure credential storage with encryption.

Implementation Steps

1. Database Schema

Update prisma/schema.prisma:

model Credential {
  id            String    @id @default(cuid())
  userId        String
  name          String
  type          String    // 'api-key', 'oauth2', 'custom'
  pluginName    String
  
  // Encrypted credential data
  encryptedData String    @db.Text
  
  // OAuth2 specific
  accessToken   String?   @db.Text
  refreshToken  String?   @db.Text
  expiresAt     DateTime?
  
  createdAt     DateTime  @default(now())
  updatedAt     DateTime  @updatedAt
  
  user          User      @relation(fields: [userId], references: [id], onDelete: Cascade)
  
  @@index([userId, pluginName])
}

2. Credential Manager

Create src/lib/plugin-system/credential-manager.ts:

• saveCredential(): Encrypt and store credentials
• getCredential(): Decrypt and return credentials
• refreshOAuth2Token(): Auto-refresh expired OAuth tokens
• deleteCredential(): Securely delete credentials
• listUserCredentials(): List credentials for a user

3. Encryption Implementation

• Use AES-256-GCM for encryption
• Store encryption key in environment variable: CREDENTIAL_ENCRYPTION_KEY
• IV (Initialization Vector) generated per credential
• Auth tag for integrity verification

4. OAuth2 Flow

Create src/app/api/auth/oauth/callback/route.ts:

• Handle OAuth callback
• Exchange code for tokens
• Store encrypted tokens
• Redirect back to plugin configuration

5. Credential UI

Create src/components/credentials/:

• credential-selector.tsx: Select existing credential or create new
• credential-form.tsx: Form for API key / custom auth
• oauth-button.tsx: Button to initiate OAuth flow
• credential-list.tsx: Manage user's credentials

6. Security Measures

• Never log decrypted credentials
• Use secure HTTP-only cookies for OAuth state
• Implement CSRF protection
• Rate limiting on credential endpoints
• Audit log for credential access

Acceptance Criteria

• Prisma schema updated and migration created
• Encryption/decryption functions work correctly
• OAuth2 flow tested with Google (example)
• Token refresh works automatically
• Credentials UI components functional
• No credentials exposed in logs or errors
• Security audit passed
• Documentation written

Security Checklist

• Encryption key is 32 bytes (256 bits)
• New IV generated for each encryption
• Auth tags verified on decryption
• OAuth state parameter used (CSRF)
• Credentials never sent to frontend (only IDs)

Dependencies

• Issue feat: tRPC Initalized #1 (Plugin System Foundation)

Estimated Effort

• Large (10-12 hours)

---

Backlink: #40

[github-actions]

👋 Thanks for opening another issue, @coderabbitai[bot]! We appreciate your continued engagement with the project.

Quick checklist:

• Clear description of the issue
• Steps to reproduce (if applicable)
• Expected vs actual behavior

We'll take a look as soon as possible!

[coderabbitai]

Coding Plan

Approach

Build a secure credential management system that enables users to store API keys and OAuth tokens with AES-256-GCM encryption, manage them through a UI, and make them available for workflow nodes to use when calling external APIs.

Observations

The project is a Next.js 15 workflow automation platform using tRPC for API communication, Prisma with PostgreSQL for data persistence, and Better Auth for user authentication. The codebase follows a feature-based organization pattern with UI components from shadcn/ui. Currently, there is no encryption infrastructure, and the HTTP Request node lacks authentication header support. A credentials page stub exists at src/app/(dashboard)/(rest)/credentials/ but is not implemented. The credential system will be separate from Better Auth's Account model, which is reserved for user authentication providers.

Assumptions

Assumption 1: Sensitive Field Encryption Strategy

Options Considered:

1. Store everything in a single encryptedData JSON blob (simpler schema, single decryption)
2. Keep separate fields but encrypt all sensitive fields individually (easier token refresh access)

Chosen Option: 2

Rationale: Keep separate fields per ticket schema, but encrypt accessToken and refreshToken fields in addition to encryptedData, as all credentials must be protected at rest.

Assumption 2: OAuth Provider Configuration Approach

Options Considered:

1. Environment-based provider configs (GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, etc.)
2. Database-stored provider configs allowing users to add their own OAuth apps

Chosen Option: 1

Rationale: Use environment variables for OAuth provider credentials, following the existing pattern used by Polar integration in src/lib/polar.ts. This is simpler and matches the ticket's security approach.

Assumption 3: pluginName Field Type

Options Considered:

1. Use NodeType enum for type safety and alignment with node system
2. Use free-form string for flexibility beyond current NodeType values

Chosen Option: 2

Rationale: Use free-form string as specified in the ticket schema. This allows credentials for integrations that may not yet have corresponding node types and provides flexibility for the plugin system.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Database and Encryption Foundation

Establish the data persistence layer and cryptographic utilities required for secure credential storage.

Task 1: Create Credential Prisma Model

Add the Credential model to the database schema following existing conventions and generate the migration.

• Add Credential model to prisma/schema.prisma with all fields from ticket (id, userId, name, type, pluginName, encryptedData, accessToken, refreshToken, expiresAt, timestamps)
• Add relation to User model with onDelete: Cascade following existing patterns
• Add composite index on [userId, pluginName] as specified
• Add @@map("credential") for consistent table naming
• Update User model to include credentials Credential[] relation
• Generate and apply Prisma migration

Task 2: Implement AES-256-GCM Encryption Utilities

Create cryptographic utilities for encrypting and decrypting sensitive credential data.

• Create src/lib/encryption.ts with encrypt and decrypt functions using Node.js crypto module
• Implement AES-256-GCM encryption with 256-bit key from CREDENTIAL_ENCRYPTION_KEY environment variable
• Generate unique IV (Initialization Vector) per encryption operation
• Include auth tag in encrypted output for integrity verification
• Store IV and auth tag alongside ciphertext (format: iv:authTag:ciphertext base64 encoded)
• Add key validation helper to ensure encryption key is exactly 32 bytes
• Implement secure error handling that never exposes plaintext in error messages

🤖 Prompt for AI agents

Establish the database schema and cryptographic foundation for secure credential
storage. This phase creates the data model and encryption utilities needed for
the entire credential management system.

**Database Schema:**
- Add a Credential model to `prisma/schema.prisma` with fields: id, userId,
name, type, pluginName, encryptedData, accessToken, refreshToken, expiresAt,
createdAt, updatedAt
- Create relation to User model with cascade delete behavior
- Add composite index on `[userId, pluginName]`
- Use `@@map("credential")` for table naming consistency
- Update User model to include the credentials relation
- Generate and apply the Prisma migration

**Encryption Utilities:**
- Create `src/lib/encryption.ts` with encrypt and decrypt functions
- Use Node.js crypto module to implement AES-256-GCM encryption
- Read encryption key from `CREDENTIAL_ENCRYPTION_KEY` environment variable
(must be 32 bytes)
- Generate a unique IV for each encryption operation
- Include authentication tag for integrity verification
- Format encrypted output as `iv:authTag:ciphertext` (base64 encoded)
- Add key validation to ensure proper key length
- Implement error handling that prevents plaintext exposure in error messages

Phase 2: Backend API Layer

Build the service layer and API endpoints for credential management operations.

Task 1: Create Credential Manager Service

Implement the core credential management logic with encryption integration.

• Create src/lib/credential-manager.ts with the following functions:
• saveCredential(): Encrypt sensitive fields and persist to database
• getCredential(): Retrieve and decrypt credential data, returning decrypted values
• deleteCredential(): Remove credential with user ownership verification
• listUserCredentials(): Return user's credentials with sensitive fields excluded (only IDs and metadata)
• refreshOAuth2Token(): Check token expiration, call provider's token refresh endpoint, encrypt and update tokens
• All functions must scope operations to the authenticated user's ID
• Never log or expose decrypted credential values in error messages

Task 2: Create Credentials tRPC Router

Expose credential operations through protected tRPC procedures.

• Create src/features/credentials/server/routers.ts following workflow router patterns
• Implement create mutation with zod validation for name, type, pluginName, and credential data
• Implement list query returning credentials with sensitive fields stripped (id, name, type, pluginName, createdAt only)
• Implement get query for retrieving single credential metadata (no decrypted values to frontend)
• Implement delete mutation with user ownership check
• Register router in src/trpc/routers/_app.ts
• Use protectedProcedure for all endpoints to require authentication

🤖 Prompt for AI agents

Build the backend service layer and tRPC API for credential management
operations. This phase implements the core business logic with encryption and
exposes it through protected API endpoints.

**Credential Manager Service:**
- Create `src/lib/credential-manager.ts` with core credential operations
- Implement `saveCredential()` to encrypt sensitive fields (accessToken,
refreshToken, encryptedData) before persisting to database
- Implement `getCredential()` to retrieve and decrypt credential data for
authenticated use
- Implement `deleteCredential()` with user ownership verification before
deletion
- Implement `listUserCredentials()` to return only metadata (id, name, type,
pluginName, createdAt) without sensitive data
- Implement `refreshOAuth2Token()` to check expiration, call provider token
refresh endpoint, and update encrypted tokens
- All functions must scope operations to the authenticated user's ID for
security
- Ensure error messages never expose decrypted credential values

**tRPC Router:**
- Create `src/features/credentials/server/routers.ts` following existing
workflow router patterns
- Implement `create` mutation with zod validation for name, type, pluginName,
and credential data fields
- Implement `list` query that returns credentials with sensitive fields stripped
out
- Implement `get` query for single credential metadata (no decrypted values sent
to frontend)
- Implement `delete` mutation with user ownership verification
- Use `protectedProcedure` for all endpoints to enforce authentication
- Register the credentials router in `src/trpc/routers/_app.ts`

Phase 3: OAuth2 Integration

Implement the OAuth2 authorization flow for token-based integrations.

Task 1: Create OAuth2 Callback Handler

Build the API route to handle OAuth provider callbacks and securely store tokens.

• Create src/app/api/auth/oauth/callback/route.ts as GET handler
• Validate state parameter against stored session state (CSRF protection)
• Extract authorization code from callback query parameters
• Exchange code for access/refresh tokens using provider's token endpoint
• Encrypt tokens using encryption utilities before storage
• Create or update Credential record with encrypted tokens and expiration
• Store OAuth state in HTTP-only secure cookie before redirect (in initiation flow)
• Redirect user back to credentials page or original plugin configuration on success
• Handle errors gracefully without exposing token values

Task 2: Create OAuth Flow Initiation Utility

Build the server-side logic to start OAuth authorization flows.

• Create src/lib/oauth-providers.ts with provider configurations (Google as example per ticket)
• Define provider interface with: authorizationUrl, tokenUrl, clientId (from env), scopes
• Create initiateOAuthFlow() function that generates state, builds authorization URL, sets state cookie
• Create server action in src/features/credentials/server/actions.ts for initiating OAuth from UI
• State should include user ID, provider name, and return URL for post-auth redirect

🤖 Prompt for AI agents

Implement the OAuth2 authorization flow to enable users to connect token-based
integrations. This phase handles OAuth initiation and callback processing with
secure token storage.

**OAuth2 Callback Handler:**
- Create `src/app/api/auth/oauth/callback/route.ts` as a GET route handler
- Validate the state parameter against stored session state for CSRF protection
- Extract the authorization code from callback query parameters
- Exchange the authorization code for access/refresh tokens via provider's token
endpoint
- Encrypt tokens using the encryption utilities before database storage
- Create or update a Credential record with encrypted tokens and expiration
timestamp
- Store OAuth state in HTTP-only secure cookie during the initiation flow (for
validation)
- Redirect user back to credentials page or original plugin configuration on
successful completion
- Implement error handling that doesn't expose token values

**OAuth Flow Initiation:**
- Create `src/lib/oauth-providers.ts` with provider configuration objects
- Define provider interface containing: authorizationUrl, tokenUrl, clientId
(from environment), scopes
- Include Google as example provider per ticket requirements
- Implement `initiateOAuthFlow()` function to generate state token, build
authorization URL, and set state cookie
- Create server action in `src/features/credentials/server/actions.ts` for UI to
trigger OAuth flow
- State should encode user ID, provider name, and return URL for
post-authentication redirect

Phase 4: Credential Management UI

Build the user interface for viewing, creating, and managing credentials.

Task 1: Implement Credentials List Page

Create the main credentials management page using the existing stub.

• Update src/app/(dashboard)/(rest)/credentials/page.tsx to fetch and display user credentials
• Use tRPC credentials.list query to load credential data
• Display credentials in a Table component with columns: name, type, pluginName, created date, actions
• Add "Add Credential" button that opens credential form dialog
• Implement delete action with AlertDialog confirmation
• Show Empty component when no credentials exist
• Include Badge component to indicate credential type (api-key, oauth2, custom)

Task 2: Create Credential Form Dialog

Build the form for creating API key and custom credential types.

• Create src/features/credentials/components/credential-dialog.tsx
• Implement form with react-hook-form and zod validation
• Include fields: name (text), type (select: api-key, oauth2, custom), pluginName (text or select)
• Conditionally show credential input field for api-key type (password input with show/hide toggle)
• Conditionally show custom fields input for custom type (key-value pairs)
• For oauth2 type, show OAuth button instead of manual credential input
• Use tRPC mutation for form submission with success/error toasts
• Reset form and close dialog on successful creation

Task 3: Create OAuth Button and Credential Selector Components

Build reusable components for OAuth initiation and credential selection in node dialogs.

• Create src/features/credentials/components/oauth-button.tsx that triggers OAuth flow for a given provider
• Button should call server action to initiate OAuth, handling the redirect
• Create src/features/credentials/components/credential-selector.tsx as a Select/Combobox component
• Selector filters credentials by pluginName prop to show only relevant credentials
• Include option to create new credential (opens credential dialog)
• Selector returns only credential ID (never exposes sensitive data to frontend)
• Export components from src/features/credentials/components/index.ts for easy imports

🤖 Prompt for AI agents

Build the user interface for credential management, including the main
credentials page, creation form, and reusable components. This phase provides
users with a complete UI to view, create, and manage their credentials.

**Credentials List Page:**
- Update `src/app/(dashboard)/(rest)/credentials/page.tsx` to display user
credentials
- Use tRPC `credentials.list` query to fetch credential data
- Display credentials in a Table component with columns: name, type, pluginName,
created date, actions
- Add "Add Credential" button to open the credential form dialog
- Implement delete action with AlertDialog confirmation before deletion
- Show Empty component when user has no credentials
- Use Badge component to visually indicate credential type (api-key, oauth2,
custom)

**Credential Form Dialog:**
- Create `src/features/credentials/components/credential-dialog.tsx` as a dialog
component
- Implement form using react-hook-form with zod validation
- Add form fields: name (text input), type (select dropdown with
api-key/oauth2/custom), pluginName (text or select)
- Conditionally render credential input field for api-key type (password input
with show/hide toggle)
- Conditionally render custom fields input for custom type (key-value pair
inputs)
- For oauth2 type, show OAuth button component instead of manual input
- Submit form using tRPC mutation with success/error toasts for user feedback
- Reset form and close dialog on successful credential creation

**OAuth Button and Credential Selector:**
- Create `src/features/credentials/components/oauth-button.tsx` to trigger OAuth
flow for a specified provider
- Button calls server action to initiate OAuth and handles redirect flow
- Create `src/features/credentials/components/credential-selector.tsx` as
Select/Combobox component
- Filter credentials by pluginName prop to show only relevant credentials for
the integration
- Include option to create new credential (opens credential dialog)
- Return only credential ID (never expose sensitive data to frontend)
- Export all components from `src/features/credentials/components/index.ts`

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Establish the database schema and cryptographic foundation for secure credential
storage. This phase creates the data model and encryption utilities needed for
the entire credential management system.

**Database Schema:**
- Add a Credential model to `prisma/schema.prisma` with fields: id, userId,
name, type, pluginName, encryptedData, accessToken, refreshToken, expiresAt,
createdAt, updatedAt
- Create relation to User model with cascade delete behavior
- Add composite index on `[userId, pluginName]`
- Use `@@map("credential")` for table naming consistency
- Update User model to include the credentials relation
- Generate and apply the Prisma migration

**Encryption Utilities:**
- Create `src/lib/encryption.ts` with encrypt and decrypt functions
- Use Node.js crypto module to implement AES-256-GCM encryption
- Read encryption key from `CREDENTIAL_ENCRYPTION_KEY` environment variable
(must be 32 bytes)
- Generate a unique IV for each encryption operation
- Include authentication tag for integrity verification
- Format encrypted output as `iv:authTag:ciphertext` (base64 encoded)
- Add key validation to ensure proper key length
- Implement error handling that prevents plaintext exposure in error messages
===============================================================================

Task: 2

Build the backend service layer and tRPC API for credential management
operations. This phase implements the core business logic with encryption and
exposes it through protected API endpoints.

**Credential Manager Service:**
- Create `src/lib/credential-manager.ts` with core credential operations
- Implement `saveCredential()` to encrypt sensitive fields (accessToken,
refreshToken, encryptedData) before persisting to database
- Implement `getCredential()` to retrieve and decrypt credential data for
authenticated use
- Implement `deleteCredential()` with user ownership verification before
deletion
- Implement `listUserCredentials()` to return only metadata (id, name, type,
pluginName, createdAt) without sensitive data
- Implement `refreshOAuth2Token()` to check expiration, call provider token
refresh endpoint, and update encrypted tokens
- All functions must scope operations to the authenticated user's ID for
security
- Ensure error messages never expose decrypted credential values

**tRPC Router:**
- Create `src/features/credentials/server/routers.ts` following existing
workflow router patterns
- Implement `create` mutation with zod validation for name, type, pluginName,
and credential data fields
- Implement `list` query that returns credentials with sensitive fields stripped
out
- Implement `get` query for single credential metadata (no decrypted values sent
to frontend)
- Implement `delete` mutation with user ownership verification
- Use `protectedProcedure` for all endpoints to enforce authentication
- Register the credentials router in `src/trpc/routers/_app.ts`
===============================================================================

Task: 3

Implement the OAuth2 authorization flow to enable users to connect token-based
integrations. This phase handles OAuth initiation and callback processing with
secure token storage.

**OAuth2 Callback Handler:**
- Create `src/app/api/auth/oauth/callback/route.ts` as a GET route handler
- Validate the state parameter against stored session state for CSRF protection
- Extract the authorization code from callback query parameters
- Exchange the authorization code for access/refresh tokens via provider's token
endpoint
- Encrypt tokens using the encryption utilities before database storage
- Create or update a Credential record with encrypted tokens and expiration
timestamp
- Store OAuth state in HTTP-only secure cookie during the initiation flow (for
validation)
- Redirect user back to credentials page or original plugin configuration on
successful completion
- Implement error handling that doesn't expose token values

**OAuth Flow Initiation:**
- Create `src/lib/oauth-providers.ts` with provider configuration objects
- Define provider interface containing: authorizationUrl, tokenUrl, clientId
(from environment), scopes
- Include Google as example provider per ticket requirements
- Implement `initiateOAuthFlow()` function to generate state token, build
authorization URL, and set state cookie
- Create server action in `src/features/credentials/server/actions.ts` for UI to
trigger OAuth flow
- State should encode user ID, provider name, and return URL for
post-authentication redirect
===============================================================================

Task: 4

Build the user interface for credential management, including the main
credentials page, creation form, and reusable components. This phase provides
users with a complete UI to view, create, and manage their credentials.

**Credentials List Page:**
- Update `src/app/(dashboard)/(rest)/credentials/page.tsx` to display user
credentials
- Use tRPC `credentials.list` query to fetch credential data
- Display credentials in a Table component with columns: name, type, pluginName,
created date, actions
- Add "Add Credential" button to open the credential form dialog
- Implement delete action with AlertDialog confirmation before deletion
- Show Empty component when user has no credentials
- Use Badge component to visually indicate credential type (api-key, oauth2,
custom)

**Credential Form Dialog:**
- Create `src/features/credentials/components/credential-dialog.tsx` as a dialog
component
- Implement form using react-hook-form with zod validation
- Add form fields: name (text input), type (select dropdown with
api-key/oauth2/custom), pluginName (text or select)
- Conditionally render credential input field for api-key type (password input
with show/hide toggle)
- Conditionally render custom fields input for custom type (key-value pair
inputs)
- For oauth2 type, show OAuth button component instead of manual input
- Submit form using tRPC mutation with success/error toasts for user feedback
- Reset form and close dialog on successful credential creation

**OAuth Button and Credential Selector:**
- Create `src/features/credentials/components/oauth-button.tsx` to trigger OAuth
flow for a specified provider
- Button calls server action to initiate OAuth and handles redirect flow
- Create `src/features/credentials/components/credential-selector.tsx` as
Select/Combobox component
- Filter credentials by pluginName prop to show only relevant credentials for
the integration
- Include option to create new credential (opens credential dialog)
- Return only credential ID (never expose sensitive data to frontend)
- Export all components from `src/features/credentials/components/index.ts`

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!