@valentine-efagene/qshelter-common 2.0.63 → 2.0.64

package/dist/src/auth/index.d.ts

@@ -1,3 +1,2 @@
-export * from './permission-cache';
 export * from './policy-evaluator';
 export * from './types';

package/dist/src/auth/index.js

@@ -1,3 +1,2 @@
-export * from './permission-cache';
 export * from './policy-evaluator';
 export * from './types';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentine-efagene/qshelter-common",
-  "version": "2.0.63",
+  "version": "2.0.64",
   "description": "Shared database schemas and utilities for QShelter services",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",

package/prisma/migrations/20260105130633_add_api_keys/migration.sql

@@ -0,0 +1,26 @@
+-- CreateTable
+CREATE TABLE `api_keys` (
+    `id` VARCHAR(191) NOT NULL,
+    `tenantId` VARCHAR(191) NOT NULL,
+    `name` VARCHAR(191) NOT NULL,
+    `description` TEXT NULL,
+    `provider` VARCHAR(191) NOT NULL,
+    `secretRef` VARCHAR(191) NOT NULL,
+    `scopes` JSON NOT NULL,
+    `enabled` BOOLEAN NOT NULL DEFAULT true,
+    `expiresAt` DATETIME(3) NULL,
+    `lastUsedAt` DATETIME(3) NULL,
+    `revokedAt` DATETIME(3) NULL,
+    `revokedBy` VARCHAR(191) NULL,
+    `createdBy` VARCHAR(191) NULL,
+    `createdAt` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+    `updatedAt` DATETIME(3) NOT NULL,
+
+    INDEX `api_keys_tenantId_idx`(`tenantId`),
+    INDEX `api_keys_provider_idx`(`provider`),
+    INDEX `api_keys_enabled_idx`(`enabled`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- AddForeignKey
+ALTER TABLE `api_keys` ADD CONSTRAINT `api_keys_tenantId_fkey` FOREIGN KEY (`tenantId`) REFERENCES `tenants`(`id`) ON DELETE CASCADE ON UPDATE CASCADE;

package/prisma/schema.prisma

@@ -321,10 +321,67 @@ model Tenant {
   documentTemplates DocumentTemplate[]
   offerLetters      OfferLetter[]
 
+  // API keys for third-party integrations
+  apiKeys ApiKey[]
+
   @@index([subdomain])
   @@map("tenants")
 }
 
+// =============================================================================
+// API KEYS - Third-party integration credentials
+// =============================================================================
+// ApiKey enables partners/integrations to authenticate via token exchange.
+// 
+// Flow:
+// 1. Admin creates API key for a partner (POST /api-keys)
+// 2. System generates secret, stores in Secrets Manager, returns id.secret ONCE
+// 3. Partner calls token endpoint with id.secret (POST /api-keys/:id/token)
+// 4. Token endpoint validates via Secrets Manager, returns short-lived JWT
+// 5. Partner uses JWT for API requests; authorizer validates + resolves scopes
+//
+// Security:
+// - Raw secret stored ONLY in AWS Secrets Manager (secretRef = ARN)
+// - Secret returned only once at creation; admin must rotate if lost
+// - Scopes define allowed operations (e.g., ["contract:read", "payment:read"])
+// - Short-lived JWTs (5-15 min) minimize exposure on key compromise
+// =============================================================================
+
+model ApiKey {
+  id          String    @id @default(cuid())
+  tenantId    String
+  tenant      Tenant    @relation(fields: [tenantId], references: [id], onDelete: Cascade)
+
+  // Identification
+  name        String                // Human-readable name (e.g., "Paystack Integration")
+  description String?   @db.Text    // Optional description
+  provider    String                // Partner/vendor name (e.g., "paystack", "flutterwave")
+
+  // Secret management (NEVER store raw secret in DB)
+  secretRef   String                // AWS Secrets Manager ARN or name
+
+  // Permissions - scopes this API key is allowed to request
+  // Examples: ["contract:read", "payment:*", "property:read"]
+  scopes      Json                  // JSON array of scope strings
+
+  // Lifecycle
+  enabled     Boolean   @default(true)
+  expiresAt   DateTime?             // Optional expiration date
+  lastUsedAt  DateTime?             // Updated on each token exchange
+  revokedAt   DateTime?             // Set when key is revoked
+  revokedBy   String?               // User ID who revoked
+
+  // Audit
+  createdBy   String?               // User ID who created
+  createdAt   DateTime  @default(now())
+  updatedAt   DateTime  @updatedAt
+
+  @@index([tenantId])
+  @@index([provider])
+  @@index([enabled])
+  @@map("api_keys")
+}
+
 model RefreshToken {
   id        String   @id @default(cuid())
   // Use the JWT `jti` for indexed lookups and keep the raw JWT (optional)