{"_id":"@build0.ai/integration-credentials","name":"@build0.ai/integration-credentials","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@build0.ai/integration-credentials","version":"1.0.0","description":"Build0-specific function for retrieving integration credentials","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","prepublishOnly":"npm run build","test":"echo \"Error: no test specified\" && exit 1"},"keywords":["credentials","encryption","api","middleware","authentication","build0"],"author":{"name":"Build0.ai"},"license":"MIT","dependencies":{"zod":"^3.22.0"},"devDependencies":{"@types/node":"^20.0.0","typescript":"^5.0.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_id":"@build0.ai/integration-credentials@1.0.0","gitHead":"aa007632c4486710494aba1677c51d8dd819159a","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-Q0BVlyX2wC32/W2jH8CwWY7X4+C6L8147S5nsk+CX3F6+7EtufSGLKZ5V0aY322ETd4WzaJpC9b8Jg0H+3JmWg==","shasum":"2b5bb921794dcad20a8bdcc3b3c3f5159dfd4bf9","tarball":"https://registry.npmjs.org/@build0.ai/integration-credentials/-/integration-credentials-1.0.0.tgz","fileCount":4,"unpackedSize":9551,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD+OAiMqfa5rb/ODTAjqSWomFG1W4WN0AK2DuwF8Y6yPQIhAM3LhKkdR9jmUqnSGPhwY4m9eFcmIoUtd2RZXYwCSLa6"}]},"_npmUser":{"name":"phil_build0","email":"phil@build0.ai","actor":{"name":"phil_build0","email":"phil@build0.ai","type":"user"}},"directories":{},"maintainers":[{"name":"phil_build0","email":"phil@build0.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/integration-credentials_1.0.0_1751145735894_0.16895022192955333"},"_hasShrinkwrap":false}},"time":{"created":"2025-06-28T21:22:15.798Z","1.0.0":"2025-06-28T21:22:16.086Z","modified":"2025-06-28T21:22:16.403Z"},"maintainers":[{"name":"phil_build0","email":"phil@build0.ai"}],"description":"Build0-specific function for retrieving integration credentials","keywords":["credentials","encryption","api","middleware","authentication","build0"],"author":{"name":"Build0.ai"},"license":"MIT","readme":"# @build0.ai/credentials\n\nA higher-order function for Next.js API routes that automatically handles encrypted credential retrieval and injection.\n\n## Features\n\n- 🔐 Automatic credential decryption using AES-256-GCM\n- 🚀 Environment variable fallback for improved performance\n- 🛡️ Type-safe credential handling with Zod validation\n- 🔄 Seamless integration with Next.js API routes\n- 📦 Zero-config setup\n\n## Installation\n\n```bash\nnpm install @build0.ai/credentials\n```\n\n## Quick Start\n\n```typescript\nimport { withCredentials, RequestWithCredentials } from '@build0.ai/credentials';\n\nexport const GET = withCredentials(async (request: RequestWithCredentials) => {\n  // Access decrypted credentials\n  const credentials = request.appCredentials;\n  \n  // Use credentials to make authenticated API calls\n  return NextResponse.json({ status: 'success' });\n});\n```\n\n## Configuration\n\n### Environment Variables\n\nThe package requires the following environment variables:\n\n```bash\n# Required: Encryption key for credential decryption\nENCRYPTION_KEY=your-32-byte-hex-encryption-key\n\n# Option 1: Pre-encrypted credentials (recommended for performance)\nENCRYPTED_APP_CREDENTIALS=iv:authTag:encryptedData\n\n# Option 2: Fallback credential endpoint\nGET_CREDENTIALS_URL=https://your-api.com/credentials\n```\n\n### Credential Sources\n\nThe package supports two credential sources with automatic fallback:\n\n1. **Environment Variable** (Primary): `ENCRYPTED_APP_CREDENTIALS`\n   - Fastest option - no HTTP requests\n   - Ideal for production deployments\n\n2. **HTTP Endpoint** (Fallback): `GET_CREDENTIALS_URL`\n   - Fetches credentials from remote endpoint\n   - Forwards cookies for authentication\n   - Used when `ENCRYPTED_APP_CREDENTIALS` is not available\n\n## API Reference\n\n### `withCredentials(handler)`\n\nHigher-order function that wraps your API route handler.\n\n**Parameters:**\n- `handler`: Your API route handler function\n\n**Returns:**\n- Enhanced handler that provides `appCredentials` on the request object\n\n### `RequestWithCredentials`\n\nExtended Next.js request interface with credentials attached.\n\n**Properties:**\n- `appCredentials`: Decrypted and validated credentials object\n- All standard `NextRequest` properties\n\n### Credential Structure\n\nCredentials follow this TypeScript interface:\n\n```typescript\ntype Credentials = Record<string, {\n  type: string;      // Credential type\n  provider: string;  // Credential provider\n  [key: string]: any; // Additional provider-specific fields\n}>;\n```\n\n## Error Handling\n\nThe package throws `CredentialError` when:\n- Credentials cannot be decrypted\n- Network requests fail\n- Credential validation fails\n\nAPI routes return a 401 status with error details:\n\n```json\n{\n  \"error\": \"Credential access failed\",\n  \"message\": \"Detailed error message\"\n}\n```\n\n## Security\n\n- Uses AES-256-GCM encryption with authentication\n- Supports Additional Authenticated Data (AAD)\n- Validates credential structure with Zod schemas\n- Secure key management via environment variables\n\n## Example Usage\n\n### Basic API Route\n\n```typescript\n// app/api/example/route.ts\nimport { withCredentials, RequestWithCredentials } from '@build0.ai/credentials';\nimport { NextResponse } from 'next/server';\n\nexport const GET = withCredentials(async (request: RequestWithCredentials) => {\n  const { appCredentials } = request;\n  \n  // Access specific integration credentials\n  const githubCreds = appCredentials.github;\n  const slackCreds = appCredentials.slack;\n  \n  // Make authenticated API calls\n  // ...\n  \n  return NextResponse.json({ message: 'Success' });\n});\n```\n\n### With Error Handling\n\n```typescript\nexport const POST = withCredentials(async (request: RequestWithCredentials) => {\n  try {\n    const { appCredentials } = request;\n    // Your logic here\n    return NextResponse.json({ success: true });\n  } catch (error) {\n    return NextResponse.json(\n      { error: 'Internal server error' },\n      { status: 500 }\n    );\n  }\n});\n```\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the package\nnpm run build\n\n# Publish to npm\nnpm publish\n```\n\n## License\n\nMIT\n\n## Support\n\nFor issues and questions, please visit the [GitHub repository](https://github.com/build0-ai/credentials). ","readmeFilename":"README.md","_rev":"1-1c2c54b32c11dfb86d7128ec0d7c1193"}