{"_id":"@divami-labs/nestjs-api-key-management","_rev":"2-8c2ac7feed445953ea341675701ebdee","name":"@divami-labs/nestjs-api-key-management","dist-tags":{"latest":"0.0.2"},"versions":{"0.0.1":{"name":"@divami-labs/nestjs-api-key-management","version":"0.0.1","keywords":["nestjs","api-key","authentication","service-account","typeorm"],"author":"","license":"MIT","_id":"@divami-labs/nestjs-api-key-management@0.0.1","maintainers":[{"name":"divami-artefacts","email":"devops@divami.com"}],"dist":{"shasum":"409c9b1ab2765564c211bca5915df8b405bff3ad","tarball":"https://registry.npmjs.org/@divami-labs/nestjs-api-key-management/-/nestjs-api-key-management-0.0.1.tgz","fileCount":26,"integrity":"sha512-e+jp6sB6/Kt2Zga8+Mc2gvSYUbd6qfAazXmPr9MWW7QuxYRidgG1nj+B90G+G0E+m0ICDHOSwfkk1NmJwAcgKg==","signatures":[{"sig":"MEUCIA/YVCd0121XF6d7mVoFS3d/FSFlKt3C+YjL/m/E6RI+AiEA6xCue2ZAsA3ui0tgdJgnCTyjzw33na/N7LtMop8o/ik=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":81710},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"53125fe9f64c7bed321993d7895497c5e0ea4fad","private":false,"scripts":{"build":"tsc -p tsconfig.json","prepublishOnly":"npm run build"},"_npmUser":{"name":"divami-artefacts","email":"devops@divami.com"},"repository":{"url":"","type":"git"},"_npmVersion":"10.8.2","description":"A NestJS library for API key management with service account support","directories":{},"_nodeVersion":"18.20.8","dependencies":{"bcrypt":"^6.0.0","@types/bcrypt":"^6.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.0.0","@types/node":"^25.0.0","@types/express":"^5.0.6","class-validator":"^0.14.0","reflect-metadata":"^0.2.0","class-transformer":"^0.5.0"},"peerDependencies":{"typeorm":"^0.3.28","@nestjs/core":"^11.0.0","@nestjs/common":"^11.0.0","@nestjs/typeorm":"^11.0.0"},"_npmOperationalInternal":{"tmp":"tmp/nestjs-api-key-management_0.0.1_1770621245973_0.6378447893940642","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@divami-labs/nestjs-api-key-management","version":"0.0.2","description":"A NestJS library for API key management with service account support","main":"dist/index.js","types":"dist/index.d.ts","private":false,"publishConfig":{"access":"public"},"scripts":{"build":"tsc -p tsconfig.json","prepublishOnly":"npm run build"},"keywords":["nestjs","api-key","authentication","service-account","typeorm"],"author":"","license":"MIT","repository":{"type":"git","url":""},"peerDependencies":{"@nestjs/common":">=10.0.0 <12.0.0","@nestjs/core":">=10.0.0 <12.0.0","@nestjs/typeorm":">=10.0.0 <12.0.0","typeorm":">=0.3.21 <0.4.0"},"devDependencies":{"@types/express":"^5.0.6","@types/node":"^25.0.0","class-transformer":"^0.5.0","class-validator":"^0.14.0","reflect-metadata":"^0.2.0","typescript":"^5.0.0"},"dependencies":{},"_id":"@divami-labs/nestjs-api-key-management@0.0.2","gitHead":"b7acde19ad2bb6ec7aca967e201a44fc54be0a11","_nodeVersion":"18.20.8","_npmVersion":"10.8.2","dist":{"integrity":"sha512-QmEG1PpitxEHqN3SOqGn31gabfg5AVzgseeS276LUPTp23ejh76MHO3u8ovIPpGBcQCk6Xz2DxYBtJtJz2MiBw==","shasum":"c3107eacaa28730a5709a3c1e354d2f8016f3e3b","tarball":"https://registry.npmjs.org/@divami-labs/nestjs-api-key-management/-/nestjs-api-key-management-0.0.2.tgz","fileCount":28,"unpackedSize":82982,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCwztisTDYdRxDCqEnQU/NOZugC7lDsmSKNfoUZ8bwXgAIgXyyRsQIklZ/cGH273mnb1Cj43uUcQ/6vrRkgadl9lY8="}]},"_npmUser":{"name":"divami-artefacts","email":"devops@divami.com"},"directories":{},"maintainers":[{"name":"divami-artefacts","email":"devops@divami.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/nestjs-api-key-management_0.0.2_1770806062805_0.1034643195707805"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-09T07:14:05.884Z","modified":"2026-02-11T10:34:23.066Z","0.0.1":"2026-02-09T07:14:06.124Z","0.0.2":"2026-02-11T10:34:22.944Z"},"license":"MIT","keywords":["nestjs","api-key","authentication","service-account","typeorm"],"repository":{"type":"git","url":""},"description":"A NestJS library for API key management with service account support","maintainers":[{"name":"divami-artefacts","email":"devops@divami.com"}],"readme":"# API Key Management Library\n\nA robust, production-ready NestJS library for managing API keys with service account authentication, soft delete functionality, and comprehensive key lifecycle management.\n\n## Features\n\n✅ **Two-Tier Authentication Architecture**\n- User → Service Account → API Keys hierarchy\n- Client credential authentication (client_id + client_secret)\n- Multiple API keys per service account\n\n✅ **Secure Key Management**\n- Base64 encoded random byte generation (32 bytes)\n- Automatic service account creation\n- Secure client secret handling\n\n✅ **Advanced Key Operations**\n- Create API keys with custom metadata (name, description)\n- Validate keys with client credentials\n- Update key expiry and active status\n- Soft delete with audit trails\n\n✅ **Powerful Query Capabilities**\n- Page-based pagination (configurable limit, max 100)\n- Search by name or description (case-insensitive)\n- Sort by multiple fields (created_at, updated_at, expiry_date, name, is_active)\n- Filter by client_id, status, and deleted state\n\n✅ **Enterprise-Ready**\n- TypeScript with full type definitions\n- TypeORM integration for PostgreSQL\n- Comprehensive error handling\n- Audit logging (created_by, updated_by, deleted_by)\n- Soft delete support\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                         User                            │\n│                    (user_id: 123)                       │\n└───────────────────┬─────────────────────────────────────┘\n                    │\n                    ▼\n┌─────────────────────────────────────────────────────────┐\n│                   Service Account                       │\n│                      (sa_info)                          │\n│  ┌───────────────────────────────────────────────────┐  │\n│  │ client_id: \"550e8400-e29b-41d4-a716-446655440000\" │  │\n│  │ client_secret: \"base64_encoded_secret\"            │  │\n│  │ user_id: 123                                      │  │\n│  └───────────────────────────────────────────────────┘  │\n└───────────────────┬─────────────────────────────────────┘\n                    │\n        ┌───────────┼───────────┐\n        ▼           ▼           ▼\n    ┌───────┐   ┌───────┐   ┌───────┐\n    │ API   │   │ API   │   │ API   │\n    │ Key 1 │   │ Key 2 │   │ Key 3 │\n    └───────┘   └───────┘   └───────┘\n```\n\n### Database Schema\n\n**sa_info (Service Accounts)**\n- `id` (UUID, Primary Key)\n- `user_id` (Integer, Foreign Key)\n- `client_secret` (String, Unique, Base64 encoded)\n- `description` (String, Nullable)\n- `created_at`, `updated_at`, `created_by`, `updated_by`\n- `deleted_at`, `deleted_by` (Soft delete)\n\n**api_keys**\n- `id` (Integer, Primary Key)\n- `sa_info_id` (UUID, Foreign Key → sa_info.id)\n- `api_key` (String, Base64 encoded, 32 random bytes)\n- `name` (String, Required)\n- `description` (String, Nullable)\n- `is_active` (Boolean, Default: true)\n- `expires_at` (Timestamp, Nullable)\n- `created_at`, `updated_at`, `created_by`, `updated_by`\n- `deleted_at`, `deleted_by` (Soft delete)\n\n## Installation\n\n```bash\nnpm install key-manager-lib\n```\n\n## Quick Start\n\n### 1. Module Setup\n\n```typescript\nimport { Module } from '@nestjs/common';\nimport { TypeOrmModule } from '@nestjs/typeorm';\nimport { KeyManagerModule } from 'key-manager-lib';\n\n@Module({\n  imports: [\n    TypeOrmModule.forRoot({\n      type: 'postgres',\n      host: 'localhost',\n      port: 5432,\n      username: 'your_username',\n      password: 'your_password',\n      database: 'your_database',\n      entities: [__dirname + '/**/*.entity{.ts,.js}'],\n      synchronize: true, // Disable in production\n    }),\n    KeyManagerModule,\n  ],\n})\nexport class AppModule {}\n```\n\n### 2. Create Your First API Key\n\n```typescript\nimport { Controller, Post, Body } from '@nestjs/common';\nimport { KeyManagerService } from 'key-manager-lib';\n\n@Controller('api/keys')\nexport class KeyController {\n  constructor(private readonly keyManager: KeyManagerService) {}\n\n  @Post()\n  async createKey(@Body() dto: any) {\n    return await this.keyManager.createApiKey(dto);\n  }\n}\n```\n\n**Request:**\n```bash\nPOST /api/keys\nContent-Type: application/json\n\n{\n  \"user_id\": 123,\n  \"name\": \"Production API Key\",\n  \"description\": \"Main production environment key\",\n  \"is_active\": true,\n  \"expires_at\": \"2027-12-31T23:59:59.000Z\"\n}\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"message\": \"API key created successfully\",\n  \"data\": {\n    \"key_id\": 1,\n    \"raw_key\": \"aGVsbG93b3JsZGJhc2U2NGVuY29kZWRrZXk=\",\n    \"client_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"client_secret\": \"bXlzZWNyZXRiYXNlNjRlbmNvZGVkc3RyaW5n\",\n    \"name\": \"Production API Key\",\n    \"description\": \"Main production environment key\",\n    \"is_active\": true,\n    \"created_at\": \"2026-01-30T10:00:00.000Z\",\n    \"expires_at\": \"2027-12-31T23:59:59.000Z\",\n    \"status\": \"active\"\n  }\n}\n```\n\n> ⚠️ **Important**: Save `client_secret` securely! It's only returned when the service account is first created.\n\n### 3. Validate an API Key\n\n```typescript\n@Post('validate')\nasync validateKey(@Body() dto: any) {\n  return await this.keyManager.validateKey(dto);\n}\n```\n\n**Request:**\n```bash\nPOST /api/keys/validate\nContent-Type: application/json\n\n{\n  \"client_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"client_secret\": \"bXlzZWNyZXRiYXNlNjRlbmNvZGVkc3RyaW5n\",\n  \"api_key\": \"aGVsbG93b3JsZGJhc2U2NGVuY29kZWRrZXk=\"\n}\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"message\": \"API key is valid\",\n  \"code\": \"KEY_VALID\",\n  \"data\": {\n    \"key_id\": 1,\n    \"user_id\": 123,\n    \"client_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"expires_at\": \"2027-12-31T23:59:59.000Z\",\n    \"status\": \"active\"\n  }\n}\n```\n\n## API Endpoints\n\n### Create API Key\n```\nPOST /api/keys\n```\nCreates a new API key. Automatically creates a service account if this is the user's first key.\n\n**Body Parameters:**\n- `user_id` (number, required): User identifier\n- `name` (string, required): Display name for the key\n- `description` (string, optional): Key description\n- `is_active` (boolean, optional): Active status (default: true)\n- `expires_at` (ISO 8601, optional): Expiration timestamp\n\n### Validate API Key\n```\nPOST /api/keys/validate\n```\nValidates an API key with client credentials.\n\n**Body Parameters:**\n- `client_id` (UUID, required): Service account client ID\n- `client_secret` (string, required): Service account client secret\n- `api_key` (string, required): The API key to validate\n\n### Update API Key\n```\nPUT /api/keys/:id\n```\nUpdates an existing API key's expiry date or active status.\n\n**Body Parameters:**\n- `expires_at` (ISO 8601, optional): New expiration timestamp\n- `is_active` (boolean, optional): Active status\n\n### Remove API Key\n```\nDELETE /api/keys/:id\n```\nSoft deletes an API key (sets deleted_at timestamp).\n\n### List API Keys\n```\nGET /api/keys?page=1&limit=20&search=production\n```\nRetrieves API keys with advanced filtering and pagination.\n\n**Query Parameters:**\n- `client_id` (UUID, optional): Filter by service account\n- `status` (string, optional): Filter by status (active, inactive, expired, deleted)\n- `page` (number, optional): Page number (default: 1)\n- `limit` (number, optional): Results per page (default: 10, max: 100)\n- `search` (string, optional): Search in name/description\n- `sort_by` (string, optional): Sort field (created_at, updated_at, expiry_date, name, is_active)\n- `sort_order` (string, optional): ASC or DESC (default: DESC)\n- `include_deleted` (boolean, optional): Include soft-deleted keys (default: false)\n\n## Development\n\n### Prerequisites\n- Node.js >= 14.x\n- PostgreSQL >= 12.x\n- npm or yarn\n\n### Setup\n\n1. Clone the repository:\n```bash\ngit clone <repository-url>\ncd API-Key-Management\n```\n\n2. Install dependencies:\n```bash\nnpm install\n```\n\n3. Configure database connection in your environment or `TypeOrmModule.forRoot()`\n\n4. Build the library:\n```bash\nnpm run build\n```\n\n5. Run in development mode:\n```bash\nnpm run start:dev\n```\n\n### Project Structure\n\n```\nsrc/\n├── entities/\n│   ├── api-key.entity.ts       # API key database model\n│   └── sa-info.entity.ts       # Service account database model\n├── interfaces/\n│   ├── dto.interface.ts        # Data transfer object types\n│   ├── model.interface.ts      # Domain model types\n│   └── service.interface.ts    # Service contract types\n├── models/\n│   └── api-key.model.ts        # Business logic models\n├── services/\n│   ├── key-generation.service.ts   # Key generation logic\n│   └── key-validation.service.ts   # Key validation logic\n├── utils/\n│   └── logger.util.ts          # Logging utilities\n├── key-manager.module.ts       # NestJS module definition\n├── key-manager.service.ts      # Main service implementation\n└── index.ts                     # Public API exports\n```\n\n## Testing\n\nImport the included Postman collection for comprehensive API testing:\n\n```bash\n# Located at project root\npostman_collection.json\n```\n\n**Test Coverage:**\n- Service account creation and reuse\n- API key CRUD operations\n- Validation with client credentials\n- Soft delete scenarios\n- Pagination and search\n- Error handling\n- Security tests (SQL injection prevention)\n\n## Error Handling\n\nAll endpoints return structured error responses:\n\n```json\n{\n  \"success\": false,\n  \"message\": \"API key not found or already deleted\",\n  \"code\": \"KEY_NOT_FOUND\",\n  \"timestamp\": \"2026-01-30T10:00:00.000Z\"\n}\n```\n\n### Common Error Codes\n- `KEY_NOT_FOUND`: API key doesn't exist or is deleted\n- `KEY_EXPIRED`: API key has expired\n- `KEY_INACTIVE`: API key is not active\n- `KEY_ALREADY_DELETED`: Attempting to delete an already deleted key\n- `INVALID_CLIENT_CREDENTIALS`: Client ID or secret is incorrect\n- `SERVICE_ACCOUNT_NOT_FOUND`: Service account doesn't exist\n- `EXPIRY_DATE_PAST`: Expiry date must be in the future\n- `INVALID_LIMIT`: Pagination limit exceeds maximum (100)\n\n## Best Practices\n\n1. **Store Credentials Securely**\n   - Never commit `client_secret` values to version control\n   - Use environment variables or secure vaults\n   - Rotate secrets periodically\n\n2. **API Key Lifecycle**\n   - Set appropriate expiration dates\n   - Monitor expiring keys proactively\n   - Remove unused keys promptly\n\n3. **Validation Flow**\n   - Always validate both client credentials and API key together\n   - Cache validation results with short TTL (if needed)\n   - Log validation attempts for security monitoring\n\n4. **Pagination**\n   - Use reasonable limit values (10-50) for better performance\n   - Implement cursor-based pagination for large datasets if needed\n\n5. **Soft Delete**\n   - Soft-deleted records are excluded by default\n   - Use `include_deleted=true` only when necessary\n   - Implement hard delete policies for compliance (GDPR, etc.)\n\n## Configuration\n\nEnvironment variables (optional):\n\n```env\n# Database\nDB_HOST=localhost\nDB_PORT=5432\nDB_USERNAME=your_username\nDB_PASSWORD=your_password\nDB_DATABASE=api_key_management\n\n# Application\nNODE_ENV=production\nLOG_LEVEL=info\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n\n---\n\n**Built with** ❤️ **using NestJS and TypeORM**\n","readmeFilename":"README.md"}