@payez/next-mvp 3.0.0 → 3.1.1

package/dist/vibe/enterprise-auth.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * =============================================================================
+ * VIBE ENTERPRISE AUTHENTICATION
+ * =============================================================================
+ *
+ * Server-side HMAC authentication for enterprise/service account requests.
+ * Validates incoming requests with X-Vibe-Client-Id, X-Vibe-Timestamp, and
+ * X-Vibe-Signature headers.
+ *
+ * Usage in Next.js API routes:
+ *   import { validateEnterpriseAuth, hasEnterpriseAuthHeaders } from '@payez/next-mvp/vibe/enterprise-auth'
+ *
+ *   export async function GET(request: NextRequest) {
+ *     if (hasEnterpriseAuthHeaders(request)) {
+ *       const auth = await validateEnterpriseAuth(request, ENTERPRISE_CLIENTS);
+ *       if (!auth.success) {
+ *         return NextResponse.json({ error: auth.error }, { status: 401 });
+ *       }
+ *       // Use auth.clientId for authenticated requests
+ *     }
+ *   }
+ *
+ * =============================================================================
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateEnterpriseAuth = validateEnterpriseAuth;
+exports.hasEnterpriseAuthHeaders = hasEnterpriseAuthHeaders;
+exports.generateBackendHmacSignature = generateBackendHmacSignature;
+const crypto_1 = __importDefault(require("crypto"));
+/**
+ * Validates enterprise HMAC authentication headers on incoming requests.
+ *
+ * Expected headers:
+ * - X-Vibe-Client-Id: The client identifier
+ * - X-Vibe-Timestamp: Unix timestamp in seconds
+ * - X-Vibe-Signature: HMAC-SHA256 signature of "{timestamp}|{method}|{path}"
+ *
+ * Security features:
+ * - Constant-time signature comparison (prevents timing attacks)
+ * - Timestamp validation with 5-minute window (prevents replay attacks)
+ * - Base64-encoded secret keys
+ *
+ * @param request - The Next.js request object
+ * @param enterpriseClients - Map of client IDs to secret keys
+ * @returns Authentication result with success status and client ID
+ *
+ * @example
+ * const CLIENTS = {
+ *   'vibe_abc123': 'base64SecretKey=='
+ * };
+ * const result = await validateEnterpriseAuth(request, CLIENTS);
+ * if (result.success) {
+ *   console.log(`Authenticated client: ${result.clientId}`);
+ * }
+ */
+async function validateEnterpriseAuth(request, enterpriseClients) {
+    // Check for required headers
+    const clientId = request.headers.get('X-Vibe-Client-Id');
+    const timestamp = request.headers.get('X-Vibe-Timestamp');
+    const signature = request.headers.get('X-Vibe-Signature');
+    // If any header is missing, this is not an enterprise auth request
+    if (!clientId || !timestamp || !signature) {
+        return {
+            success: false,
+            error: 'MISSING_ENTERPRISE_HEADERS'
+        };
+    }
+    // Validate client ID exists in configuration
+    const secretKey = enterpriseClients[clientId];
+    if (!secretKey) {
+        return {
+            success: false,
+            error: 'INVALID_CLIENT_ID'
+        };
+    }
+    // Validate timestamp is recent (within 5 minutes)
+    const now = Math.floor(Date.now() / 1000);
+    const requestTime = parseInt(timestamp, 10);
+    if (isNaN(requestTime)) {
+        return {
+            success: false,
+            error: 'INVALID_TIMESTAMP'
+        };
+    }
+    const timeDiff = Math.abs(now - requestTime);
+    if (timeDiff > 300) { // 5 minutes
+        return {
+            success: false,
+            error: 'TIMESTAMP_EXPIRED'
+        };
+    }
+    // Compute expected signature
+    // Format: "{timestamp}|{method}|{path}"
+    const method = request.method;
+    const url = new URL(request.url);
+    const path = url.pathname;
+    const message = `${timestamp}|${method}|${path}`;
+    const expectedSignature = crypto_1.default
+        .createHmac('sha256', Buffer.from(secretKey, 'base64'))
+        .update(message)
+        .digest('base64');
+    // Compare signatures (constant-time comparison to prevent timing attacks)
+    if (!crypto_1.default.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
+        return {
+            success: false,
+            error: 'INVALID_SIGNATURE'
+        };
+    }
+    // Enterprise auth successful
+    return {
+        success: true,
+        clientId
+    };
+}
+/**
+ * Checks if request has enterprise authentication headers.
+ * Does not validate - just checks if all required headers are present.
+ *
+ * @param request - The Next.js request object
+ * @returns True if all enterprise auth headers are present
+ *
+ * @example
+ * if (hasEnterpriseAuthHeaders(request)) {
+ *   // Validate the headers
+ *   const auth = await validateEnterpriseAuth(request, clients);
+ * } else {
+ *   // Fall back to user session auth
+ *   const token = await ensureFreshToken(request);
+ * }
+ */
+function hasEnterpriseAuthHeaders(request) {
+    return !!(request.headers.get('X-Vibe-Client-Id') &&
+        request.headers.get('X-Vibe-Timestamp') &&
+        request.headers.get('X-Vibe-Signature'));
+}
+/**
+ * Generates HMAC signature for backend API requests.
+ * Used when frontend needs to proxy enterprise auth requests to backend
+ * with a different path (e.g., /api/vibe/* -> /v1/collections/*).
+ *
+ * @param clientId - The Vibe client ID
+ * @param secretKey - Base64-encoded HMAC secret key
+ * @param timestamp - Unix timestamp (seconds) as string
+ * @param method - HTTP method (GET, POST, etc)
+ * @param backendPath - The backend API path (e.g., "/v1/collections/agent_mail/tables")
+ * @returns HMAC signature for the backend request
+ *
+ * @example
+ * // Frontend received request for /api/vibe/agent_mail/tables
+ * // Need to call backend at /v1/collections/agent_mail/tables
+ * const signature = generateBackendHmacSignature(
+ *   'vibe_abc123',
+ *   'base64SecretKey==',
+ *   '1234567890',
+ *   'GET',
+ *   '/v1/collections/agent_mail/tables'
+ * );
+ * // Use signature in backend request headers
+ */
+function generateBackendHmacSignature(clientId, secretKey, timestamp, method, backendPath) {
+    if (!secretKey) {
+        throw new Error(`No secret key provided for client ID: ${clientId}`);
+    }
+    const message = `${timestamp}|${method}|${backendPath}`;
+    return crypto_1.default
+        .createHmac('sha256', Buffer.from(secretKey, 'base64'))
+        .update(message)
+        .digest('base64');
+}

package/dist/vibe/index.d.ts

@@ -21,3 +21,5 @@ export { createLoginSession, getUserSessions, getAllSessions, getSessionById, re
 export type { CreateSessionInput, SessionQueryOptions } from './sessions';
 export { vibeCollection, vibeTable, vibeTablePath, vibeQueryPath, vibeGridPath, unwrapVibeDocument, extractVibeDocuments, GenericCollection, GenericTableDelegate, } from './generic';
 export type { VibeDocumentWrapper } from './generic';
+export { validateEnterpriseAuth, hasEnterpriseAuthHeaders, generateBackendHmacSignature, } from './enterprise-auth';
+export type { EnterpriseClientsConfig, EnterpriseAuthResult, } from './enterprise-auth';

package/dist/vibe/index.js

@@ -14,7 +14,7 @@
  * =============================================================================
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GenericTableDelegate = exports.GenericCollection = exports.extractVibeDocuments = exports.unwrapVibeDocument = exports.vibeGridPath = exports.vibeQueryPath = exports.vibeTablePath = exports.vibeTable = exports.vibeCollection = exports.getSessionStats = exports.checkSessionRevocation = exports.isSessionValid = exports.updateSessionActivity = exports.revokeAllUserSessions = exports.revokeSession = exports.getSessionById = exports.getAllSessions = exports.getUserSessions = exports.createLoginSession = exports.VibeServiceError = exports.VibeConflictError = exports.VibeRateLimitError = exports.VibeAuthError = exports.VibeValidationError = exports.VibeNotFoundError = exports.VibeError = exports.VibeSiteLog = exports.VibeComment = exports.VibeTag = exports.VibeActivityLog = exports.VibeNotification = exports.VibeFile = exports.VibeSetting = exports.VibeProfile = exports.VibeLoginSession = exports.VibeUser = exports.VibeTableDelegate = exports.VibeClient = exports.createVibeClient = exports.vibe = void 0;
+exports.generateBackendHmacSignature = exports.hasEnterpriseAuthHeaders = exports.validateEnterpriseAuth = exports.GenericTableDelegate = exports.GenericCollection = exports.extractVibeDocuments = exports.unwrapVibeDocument = exports.vibeGridPath = exports.vibeQueryPath = exports.vibeTablePath = exports.vibeTable = exports.vibeCollection = exports.getSessionStats = exports.checkSessionRevocation = exports.isSessionValid = exports.updateSessionActivity = exports.revokeAllUserSessions = exports.revokeSession = exports.getSessionById = exports.getAllSessions = exports.getUserSessions = exports.createLoginSession = exports.VibeServiceError = exports.VibeConflictError = exports.VibeRateLimitError = exports.VibeAuthError = exports.VibeValidationError = exports.VibeNotFoundError = exports.VibeError = exports.VibeSiteLog = exports.VibeComment = exports.VibeTag = exports.VibeActivityLog = exports.VibeNotification = exports.VibeFile = exports.VibeSetting = exports.VibeProfile = exports.VibeLoginSession = exports.VibeUser = exports.VibeTableDelegate = exports.VibeClient = exports.createVibeClient = exports.vibe = void 0;
 // Client exports
 var client_1 = require("./client");
 Object.defineProperty(exports, "vibe", { enumerable: true, get: function () { return client_1.vibe; } });
@@ -65,3 +65,8 @@ Object.defineProperty(exports, "unwrapVibeDocument", { enumerable: true, get: fu
 Object.defineProperty(exports, "extractVibeDocuments", { enumerable: true, get: function () { return generic_1.extractVibeDocuments; } });
 Object.defineProperty(exports, "GenericCollection", { enumerable: true, get: function () { return generic_1.GenericCollection; } });
 Object.defineProperty(exports, "GenericTableDelegate", { enumerable: true, get: function () { return generic_1.GenericTableDelegate; } });
+// Enterprise authentication exports
+var enterprise_auth_1 = require("./enterprise-auth");
+Object.defineProperty(exports, "validateEnterpriseAuth", { enumerable: true, get: function () { return enterprise_auth_1.validateEnterpriseAuth; } });
+Object.defineProperty(exports, "hasEnterpriseAuthHeaders", { enumerable: true, get: function () { return enterprise_auth_1.hasEnterpriseAuthHeaders; } });
+Object.defineProperty(exports, "generateBackendHmacSignature", { enumerable: true, get: function () { return enterprise_auth_1.generateBackendHmacSignature; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/lib/idp-client-config.ts

@@ -177,7 +177,8 @@ export async function getIDPClientConfig(forceRefresh: boolean = false): Promise
 
             // Set IDENTITY_CLIENT_BASE_EXTERNAL_URL from cached config
             // AUTH_TRUST_HOST=true tells NextAuth to derive OAuth callback URLs from headers.
-            if (redisConfig.baseClientUrl) {
+            // Only set if not already defined (allows deployment override for beta/staging)
+            if (redisConfig.baseClientUrl && !process.env.IDENTITY_CLIENT_BASE_EXTERNAL_URL) {
                 process.env.IDENTITY_CLIENT_BASE_EXTERNAL_URL = redisConfig.baseClientUrl;
             }
 
@@ -215,7 +216,8 @@ export async function getIDPClientConfig(forceRefresh: boolean = false): Promise
 
             // Set IDENTITY_CLIENT_BASE_EXTERNAL_URL from config
             // AUTH_TRUST_HOST=true tells NextAuth to derive OAuth callback URLs from headers.
-            if (config.baseClientUrl) {
+            // Only set if not already defined (allows deployment override for beta/staging)
+            if (config.baseClientUrl && !process.env.IDENTITY_CLIENT_BASE_EXTERNAL_URL) {
                 process.env.IDENTITY_CLIENT_BASE_EXTERNAL_URL = config.baseClientUrl;
                 console.log("[IDP_CONFIG] Set IDENTITY_CLIENT_BASE_EXTERNAL_URL:", config.baseClientUrl);
             }

package/src/vibe/enterprise-auth.ts

@@ -0,0 +1,208 @@
+/**
+ * =============================================================================
+ * VIBE ENTERPRISE AUTHENTICATION
+ * =============================================================================
+ *
+ * Server-side HMAC authentication for enterprise/service account requests.
+ * Validates incoming requests with X-Vibe-Client-Id, X-Vibe-Timestamp, and
+ * X-Vibe-Signature headers.
+ *
+ * Usage in Next.js API routes:
+ *   import { validateEnterpriseAuth, hasEnterpriseAuthHeaders } from '@payez/next-mvp/vibe/enterprise-auth'
+ *
+ *   export async function GET(request: NextRequest) {
+ *     if (hasEnterpriseAuthHeaders(request)) {
+ *       const auth = await validateEnterpriseAuth(request, ENTERPRISE_CLIENTS);
+ *       if (!auth.success) {
+ *         return NextResponse.json({ error: auth.error }, { status: 401 });
+ *       }
+ *       // Use auth.clientId for authenticated requests
+ *     }
+ *   }
+ *
+ * =============================================================================
+ */
+
+import { NextRequest } from 'next/server';
+import crypto from 'crypto';
+
+/**
+ * Enterprise client credentials configuration
+ * Maps client IDs to their HMAC secret keys (base64-encoded)
+ */
+export interface EnterpriseClientsConfig {
+  [clientId: string]: string; // clientId -> base64-encoded secret key
+}
+
+export interface EnterpriseAuthResult {
+  success: boolean;
+  clientId?: string;
+  error?: string;
+}
+
+/**
+ * Validates enterprise HMAC authentication headers on incoming requests.
+ *
+ * Expected headers:
+ * - X-Vibe-Client-Id: The client identifier
+ * - X-Vibe-Timestamp: Unix timestamp in seconds
+ * - X-Vibe-Signature: HMAC-SHA256 signature of "{timestamp}|{method}|{path}"
+ *
+ * Security features:
+ * - Constant-time signature comparison (prevents timing attacks)
+ * - Timestamp validation with 5-minute window (prevents replay attacks)
+ * - Base64-encoded secret keys
+ *
+ * @param request - The Next.js request object
+ * @param enterpriseClients - Map of client IDs to secret keys
+ * @returns Authentication result with success status and client ID
+ *
+ * @example
+ * const CLIENTS = {
+ *   'vibe_abc123': 'base64SecretKey=='
+ * };
+ * const result = await validateEnterpriseAuth(request, CLIENTS);
+ * if (result.success) {
+ *   console.log(`Authenticated client: ${result.clientId}`);
+ * }
+ */
+export async function validateEnterpriseAuth(
+  request: NextRequest,
+  enterpriseClients: EnterpriseClientsConfig
+): Promise<EnterpriseAuthResult> {
+  // Check for required headers
+  const clientId = request.headers.get('X-Vibe-Client-Id');
+  const timestamp = request.headers.get('X-Vibe-Timestamp');
+  const signature = request.headers.get('X-Vibe-Signature');
+
+  // If any header is missing, this is not an enterprise auth request
+  if (!clientId || !timestamp || !signature) {
+    return {
+      success: false,
+      error: 'MISSING_ENTERPRISE_HEADERS'
+    };
+  }
+
+  // Validate client ID exists in configuration
+  const secretKey = enterpriseClients[clientId];
+  if (!secretKey) {
+    return {
+      success: false,
+      error: 'INVALID_CLIENT_ID'
+    };
+  }
+
+  // Validate timestamp is recent (within 5 minutes)
+  const now = Math.floor(Date.now() / 1000);
+  const requestTime = parseInt(timestamp, 10);
+
+  if (isNaN(requestTime)) {
+    return {
+      success: false,
+      error: 'INVALID_TIMESTAMP'
+    };
+  }
+
+  const timeDiff = Math.abs(now - requestTime);
+  if (timeDiff > 300) { // 5 minutes
+    return {
+      success: false,
+      error: 'TIMESTAMP_EXPIRED'
+    };
+  }
+
+  // Compute expected signature
+  // Format: "{timestamp}|{method}|{path}"
+  const method = request.method;
+  const url = new URL(request.url);
+  const path = url.pathname;
+
+  const message = `${timestamp}|${method}|${path}`;
+  const expectedSignature = crypto
+    .createHmac('sha256', Buffer.from(secretKey, 'base64'))
+    .update(message)
+    .digest('base64');
+
+  // Compare signatures (constant-time comparison to prevent timing attacks)
+  if (!crypto.timingSafeEqual(
+    Buffer.from(signature),
+    Buffer.from(expectedSignature)
+  )) {
+    return {
+      success: false,
+      error: 'INVALID_SIGNATURE'
+    };
+  }
+
+  // Enterprise auth successful
+  return {
+    success: true,
+    clientId
+  };
+}
+
+/**
+ * Checks if request has enterprise authentication headers.
+ * Does not validate - just checks if all required headers are present.
+ *
+ * @param request - The Next.js request object
+ * @returns True if all enterprise auth headers are present
+ *
+ * @example
+ * if (hasEnterpriseAuthHeaders(request)) {
+ *   // Validate the headers
+ *   const auth = await validateEnterpriseAuth(request, clients);
+ * } else {
+ *   // Fall back to user session auth
+ *   const token = await ensureFreshToken(request);
+ * }
+ */
+export function hasEnterpriseAuthHeaders(request: NextRequest): boolean {
+  return !!(
+    request.headers.get('X-Vibe-Client-Id') &&
+    request.headers.get('X-Vibe-Timestamp') &&
+    request.headers.get('X-Vibe-Signature')
+  );
+}
+
+/**
+ * Generates HMAC signature for backend API requests.
+ * Used when frontend needs to proxy enterprise auth requests to backend
+ * with a different path (e.g., /api/vibe/* -> /v1/collections/*).
+ *
+ * @param clientId - The Vibe client ID
+ * @param secretKey - Base64-encoded HMAC secret key
+ * @param timestamp - Unix timestamp (seconds) as string
+ * @param method - HTTP method (GET, POST, etc)
+ * @param backendPath - The backend API path (e.g., "/v1/collections/agent_mail/tables")
+ * @returns HMAC signature for the backend request
+ *
+ * @example
+ * // Frontend received request for /api/vibe/agent_mail/tables
+ * // Need to call backend at /v1/collections/agent_mail/tables
+ * const signature = generateBackendHmacSignature(
+ *   'vibe_abc123',
+ *   'base64SecretKey==',
+ *   '1234567890',
+ *   'GET',
+ *   '/v1/collections/agent_mail/tables'
+ * );
+ * // Use signature in backend request headers
+ */
+export function generateBackendHmacSignature(
+  clientId: string,
+  secretKey: string,
+  timestamp: string,
+  method: string,
+  backendPath: string
+): string {
+  if (!secretKey) {
+    throw new Error(`No secret key provided for client ID: ${clientId}`);
+  }
+
+  const message = `${timestamp}|${method}|${backendPath}`;
+  return crypto
+    .createHmac('sha256', Buffer.from(secretKey, 'base64'))
+    .update(message)
+    .digest('base64');
+}

package/src/vibe/index.ts

@@ -119,3 +119,14 @@ export {
   GenericTableDelegate,
 } from './generic';
 export type { VibeDocumentWrapper } from './generic';
+
+// Enterprise authentication exports
+export {
+  validateEnterpriseAuth,
+  hasEnterpriseAuthHeaders,
+  generateBackendHmacSignature,
+} from './enterprise-auth';
+export type {
+  EnterpriseClientsConfig,
+  EnterpriseAuthResult,
+} from './enterprise-auth';