@build0.ai/credentials

A higher-order function for Next.js API routes that automatically handles encrypted credential retrieval and injection.

Features

• 🔐 Automatic credential decryption using AES-256-GCM
• 🚀 Environment variable fallback for improved performance
• 🛡️ Type-safe credential handling with Zod validation
• 🔄 Seamless integration with Next.js API routes
• 📦 Zero-config setup

Installation

npm install @build0.ai/credentials

Quick Start

import { withCredentials, RequestWithCredentials } from '@build0.ai/credentials';

export const GET = withCredentials(async (request: RequestWithCredentials) => {
  // Access decrypted credentials
  const credentials = request.appCredentials;
  
  // Use credentials to make authenticated API calls
  return NextResponse.json({ status: 'success' });
});

Configuration

Environment Variables

The package requires the following environment variables:

# Required: Encryption key for credential decryption
ENCRYPTION_KEY=your-32-byte-hex-encryption-key

# Option 1: Pre-encrypted credentials (recommended for performance)
ENCRYPTED_APP_CREDENTIALS=iv:authTag:encryptedData

# Option 2: Fallback credential endpoint
GET_CREDENTIALS_URL=https://your-api.com/credentials

Credential Sources

The package supports two credential sources with automatic fallback:

1. Environment Variable (Primary): ENCRYPTED_APP_CREDENTIALS

   • Fastest option - no HTTP requests
   • Ideal for production deployments

2. HTTP Endpoint (Fallback): GET_CREDENTIALS_URL

   • Fetches credentials from remote endpoint
   • Forwards cookies for authentication
   • Used when ENCRYPTED_APP_CREDENTIALS is not available

API Reference

withCredentials(handler)

Higher-order function that wraps your API route handler.

Parameters:

• handler: Your API route handler function

Returns:

• Enhanced handler that provides appCredentials on the request object

RequestWithCredentials

Extended Next.js request interface with credentials attached.

Properties:

• appCredentials: Decrypted and validated credentials object
• All standard NextRequest properties

Credential Structure

Credentials follow this TypeScript interface:

type Credentials = Record<string, {
  type: string;      // Credential type
  provider: string;  // Credential provider
  [key: string]: any; // Additional provider-specific fields
}>;

Error Handling

The package throws CredentialError when:

• Credentials cannot be decrypted
• Network requests fail
• Credential validation fails

API routes return a 401 status with error details:

{
  "error": "Credential access failed",
  "message": "Detailed error message"
}

Security

• Uses AES-256-GCM encryption with authentication
• Supports Additional Authenticated Data (AAD)
• Validates credential structure with Zod schemas
• Secure key management via environment variables

Example Usage

Basic API Route

// app/api/example/route.ts
import { withCredentials, RequestWithCredentials } from '@build0.ai/credentials';
import { NextResponse } from 'next/server';

export const GET = withCredentials(async (request: RequestWithCredentials) => {
  const { appCredentials } = request;
  
  // Access specific integration credentials
  const githubCreds = appCredentials.github;
  const slackCreds = appCredentials.slack;
  
  // Make authenticated API calls
  // ...
  
  return NextResponse.json({ message: 'Success' });
});

With Error Handling

export const POST = withCredentials(async (request: RequestWithCredentials) => {
  try {
    const { appCredentials } = request;
    // Your logic here
    return NextResponse.json({ success: true });
  } catch (error) {
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
});

Development

# Install dependencies
npm install

# Build the package
npm run build

# Publish to npm
npm publish

License

MIT

Support

For issues and questions, please visit the GitHub repository.