@payez/next-mvp 3.0.0

package/dist/lib/roles.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * Vibe Role Constants and Utilities
+ *
+ * Centralized role definitions for consistent authorization across the stack.
+ *
+ * @version 1.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROLE_HIERARCHY = exports.CLIENT_ADMIN_ROLES = exports.PLATFORM_ADMIN_ROLES = exports.ADMIN_ROLES = exports.VibeRoles = exports.AppRoles = exports.GlobalRoles = void 0;
+exports.hasRole = hasRole;
+exports.hasAnyRole = hasAnyRole;
+exports.hasAllRoles = hasAllRoles;
+exports.isAdmin = isAdmin;
+exports.isPlatformAdmin = isPlatformAdmin;
+exports.isClientAdmin = isClientAdmin;
+exports.getHighestRoleLevel = getHighestRoleLevel;
+// =============================================================================
+// Role Constants
+// =============================================================================
+/**
+ * Global platform roles (IDP-level)
+ * These roles are managed at the IDP and grant cross-client access.
+ */
+exports.GlobalRoles = {
+    /** Platform super admin - full access to everything */
+    PAYEZ_ADMIN: 'payez_admin',
+    /** IDP client admin - manages IDP client configuration */
+    IDP_CLIENT_ADMIN: 'idp_client_admin',
+    /** Vibe platform admin - manages Vibe infrastructure globally */
+    VIBE_APP_ADMIN: 'vibe_app_admin',
+    /** Vibe client admin - manages Vibe for a specific tenant */
+    VIBE_CLIENT_ADMIN: 'vibe_client_admin',
+    /** Vibe agents user - AI agents operating via CLI/automation */
+    VIBE_AGENTS_USER: 'vibe_agents_user',
+};
+/**
+ * Application-level roles (per-client)
+ * These roles are scoped to a specific client/tenant.
+ */
+exports.AppRoles = {
+    /** Standard authenticated user */
+    VIBE_APP_USER: 'vibe_app_user',
+};
+/**
+ * All Vibe roles combined
+ */
+exports.VibeRoles = {
+    ...exports.GlobalRoles,
+    ...exports.AppRoles,
+};
+// =============================================================================
+// Role Groups
+// =============================================================================
+/**
+ * Roles that grant admin access to the /admin section.
+ * Any of these roles allows access to admin pages.
+ */
+exports.ADMIN_ROLES = [
+    exports.GlobalRoles.PAYEZ_ADMIN,
+    exports.GlobalRoles.VIBE_APP_ADMIN,
+    exports.GlobalRoles.VIBE_CLIENT_ADMIN,
+    exports.GlobalRoles.IDP_CLIENT_ADMIN,
+];
+/**
+ * Roles that grant platform-wide admin access (not client-scoped).
+ * These can access/modify any client's data.
+ */
+exports.PLATFORM_ADMIN_ROLES = [
+    exports.GlobalRoles.PAYEZ_ADMIN,
+    exports.GlobalRoles.VIBE_APP_ADMIN,
+];
+/**
+ * Roles that grant client-scoped admin access.
+ * These can only access their own client's data.
+ */
+exports.CLIENT_ADMIN_ROLES = [
+    exports.GlobalRoles.VIBE_CLIENT_ADMIN,
+    exports.GlobalRoles.IDP_CLIENT_ADMIN,
+];
+// =============================================================================
+// Role Checking Utilities
+// =============================================================================
+/**
+ * Check if user has a specific role
+ */
+function hasRole(userRoles, role) {
+    if (!userRoles || !Array.isArray(userRoles))
+        return false;
+    return userRoles.includes(role);
+}
+/**
+ * Check if user has any of the specified roles
+ */
+function hasAnyRole(userRoles, roles) {
+    if (!userRoles || !Array.isArray(userRoles))
+        return false;
+    return roles.some(role => userRoles.includes(role));
+}
+/**
+ * Check if user has all of the specified roles
+ */
+function hasAllRoles(userRoles, roles) {
+    if (!userRoles || !Array.isArray(userRoles))
+        return false;
+    return roles.every(role => userRoles.includes(role));
+}
+/**
+ * Check if user has admin access (any admin role)
+ */
+function isAdmin(userRoles) {
+    return hasAnyRole(userRoles, exports.ADMIN_ROLES);
+}
+/**
+ * Check if user has platform-wide admin access
+ */
+function isPlatformAdmin(userRoles) {
+    return hasAnyRole(userRoles, exports.PLATFORM_ADMIN_ROLES);
+}
+/**
+ * Check if user is a client-scoped admin (not platform admin)
+ */
+function isClientAdmin(userRoles) {
+    return hasAnyRole(userRoles, exports.CLIENT_ADMIN_ROLES) && !isPlatformAdmin(userRoles);
+}
+// =============================================================================
+// Role Hierarchy
+// =============================================================================
+/**
+ * Role hierarchy (higher index = more access)
+ *
+ * payez_admin (4) - IDP super admin, can do anything
+ * vibe_app_admin (3) - Platform admin, manages Vibe globally
+ * vibe_client_admin (2) - Client admin, manages their own tenant
+ * idp_client_admin (2) - IDP client admin, manages IDP config
+ * vibe_app_user (1) - Regular authenticated user
+ * (anonymous) (0) - No authentication
+ */
+exports.ROLE_HIERARCHY = {
+    [exports.GlobalRoles.PAYEZ_ADMIN]: 4,
+    [exports.GlobalRoles.VIBE_APP_ADMIN]: 3,
+    [exports.GlobalRoles.VIBE_CLIENT_ADMIN]: 2,
+    [exports.GlobalRoles.IDP_CLIENT_ADMIN]: 2,
+    [exports.AppRoles.VIBE_APP_USER]: 1,
+};
+/**
+ * Get the highest role level for a user
+ */
+function getHighestRoleLevel(userRoles) {
+    if (!userRoles || !Array.isArray(userRoles))
+        return 0;
+    return Math.max(0, ...userRoles.map(role => exports.ROLE_HIERARCHY[role] || 0));
+}
+exports.default = {
+    VibeRoles: exports.VibeRoles,
+    GlobalRoles: exports.GlobalRoles,
+    AppRoles: exports.AppRoles,
+    ADMIN_ROLES: exports.ADMIN_ROLES,
+    PLATFORM_ADMIN_ROLES: exports.PLATFORM_ADMIN_ROLES,
+    CLIENT_ADMIN_ROLES: exports.CLIENT_ADMIN_ROLES,
+    hasRole,
+    hasAnyRole,
+    hasAllRoles,
+    isAdmin,
+    isPlatformAdmin,
+    isClientAdmin,
+    getHighestRoleLevel,
+};

package/dist/lib/secret-validation.d.ts

@@ -0,0 +1,4 @@
+export declare function validateNextAuthSecret(secret: string): {
+    valid: boolean;
+    reason?: string;
+};

package/dist/lib/secret-validation.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateNextAuthSecret = validateNextAuthSecret;
+function validateNextAuthSecret(secret) {
+    if (!secret || typeof secret !== 'string')
+        return { valid: false, reason: 'missing' };
+    if (secret.length < 32)
+        return { valid: false, reason: 'too_short' };
+    const classes = [/[a-z]/, /[A-Z]/, /[0-9]/, /[^a-zA-Z0-9]/];
+    const score = classes.reduce((acc, re) => acc + (re.test(secret) ? 1 : 0), 0);
+    if (score < 3)
+        return { valid: false, reason: 'weak' };
+    return { valid: true };
+}

package/dist/lib/session-store.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Session Store for `@payez/next-mvp` using ioredis
+ *
+ * This module provides a Redis-backed session store that is compatible with the
+ * `ioredis` client. It handles the creation, retrieval, and deletion of
+ * session data, which is the single source of truth for authentication.
+ *
+ * Includes advanced distributed refresh coordination with version control.
+ */
+import { SessionData } from '../models/SessionModel';
+export type { SessionData } from '../models/SessionModel';
+export interface RefreshLockInfo {
+    sessionToken: string;
+    acquiredAt: number;
+    acquiredBy: string;
+    lockVersion: number;
+}
+/**
+ * Generates a new session token.
+ * @returns A new session token string.
+ */
+export declare function generateSessionToken(): string;
+/**
+ * Creates a new session in Redis.
+ *
+ * @param data The session data to store.
+ * @returns The generated session token (redisSessionId).
+ */
+export declare function createSession(data: SessionData): Promise<string>;
+/**
+ * Retrieves a session from Redis.
+ *
+ * @param sessionToken The session token (redisSessionId) to look up.
+ * @returns The session data, or null if not found.
+ */
+export declare function getSession(sessionToken: string): Promise<SessionData | null>;
+/**
+ * Retrieves a session along with a version identifier for optimistic locking.
+ * @param sessionToken The session token to look up.
+ * @returns An object with session and version, or null if not found.
+ */
+export declare function getSessionWithVersion(sessionToken: string): Promise<{
+    session: SessionData;
+    version: string;
+} | null>;
+/**
+ * Checks if the access token in a session is still fresh (not expired).
+ * @param sessionToken The session token to check.
+ * @param currentAccessToken The current access token to compare.
+ * @param currentVersion Optional version to check for changes.
+ * @returns Object with freshness status and latest token info.
+ */
+export declare function isAccessTokenFresh(sessionToken: string, currentAccessToken: string, currentVersion?: string): Promise<{
+    isFresh: boolean;
+    latestAccessToken?: string;
+    latestVersion?: string;
+    versionChanged: boolean;
+}>;
+/**
+ * Deletes a session from Redis.
+ * @param sessionToken The session token to delete.
+ */
+export declare function deleteSession(sessionToken: string): Promise<void>;
+/**
+ * Sets a session directly (for testing or migrations).
+ * @param sessionToken The session token.
+ * @param data The session data.
+ */
+export declare function setSession(sessionToken: string, data: SessionData): Promise<void>;
+/**
+ * Updates tokens within an existing session.
+ * @param sessionToken The session token to update.
+ * @param updates Partial session data to update.
+ * @returns The updated session data, or null if the session was not found.
+ */
+export declare function updateSession(sessionToken: string, updates: Partial<SessionData>): Promise<SessionData | null>;
+/**
+ * Transitions a session to a MFA-completed state.
+ * @param sessionToken The session token to update.
+ * @param tokens The new tokens received after MFA completion.
+ * @param mfaMethod The MFA method used (email, sms, totp) - required for token refresh.
+ * @returns The updated session data.
+ */
+export declare function transitionTo2FASession(sessionToken: string, tokens: {
+    accessToken?: string;
+    refreshToken?: string;
+    accessTokenExpires?: number;
+    refreshTokenExpires?: number;
+    idpAccessToken?: string;
+    idpRefreshToken?: string;
+    idpAccessTokenExpires?: number;
+    idpRefreshTokenExpires?: number;
+}, mfaMethod?: 'email' | 'sms' | 'totp'): Promise<SessionData | null>;
+/**
+ * Updates IDP tokens and their expiries in an existing session.
+ * @param sessionToken The session token to update.
+ * @param idpAccessToken The new IDP access token.
+ * @param idpRefreshToken The new IDP refresh token.
+ * @param idpAccessTokenExpires The access token expiry timestamp.
+ * @param idpRefreshTokenExpires The refresh token expiry timestamp (optional).
+ * @returns The updated session data.
+ */
+export declare function updateTokens(sessionToken: string, idpAccessToken: string, idpRefreshToken: string, idpAccessTokenExpires: number, idpRefreshTokenExpires?: number): Promise<SessionData | null>;
+/**
+ * Marks a session as having completed MFA.
+ * @param sessionToken The session token to update.
+ * @returns The updated session data.
+ */
+export declare function mark2FAComplete(sessionToken: string): Promise<SessionData | null>;
+/**
+ * Checks if MFA is complete for a session.
+ * @param sessionToken The session token.
+ * @returns True if MFA is complete.
+ */
+export declare function is2FAComplete(sessionToken: string): Promise<boolean>;
+/**
+ * Gets IDP tokens from a session.
+ * @param sessionToken The session token.
+ * @returns The tokens or null if session not found.
+ */
+export declare function getTokens(sessionToken: string): Promise<{
+    accessToken: string;
+    refreshToken: string;
+    idpAccessToken: string;
+    idpRefreshToken: string;
+} | null>;
+/**
+ * Refreshes a JWT session (placeholder for compatibility).
+ * @param sessionToken The session token.
+ * @returns The session data or null.
+ */
+export declare function refreshJWTSession(sessionToken: string): Promise<SessionData | null>;
+/**
+ * Clears all sessions (for testing only).
+ */
+export declare function clearAllSessions(): Promise<void>;
+/**
+ * Lists all sessions (for testing/debugging only).
+ * @returns An empty array (placeholder).
+ */
+export declare function listAllSessions(): Promise<string[]>;
+/**
+ * Attempt to acquire a refresh lock for a session
+ * Uses Redis SET with NX (Not eXists) for atomic lock acquisition
+ */
+export declare function acquireRefreshLock(sessionToken: string, requestId: string, maxWaitMs?: number): Promise<{
+    acquired: boolean;
+    lockInfo?: RefreshLockInfo;
+}>;
+/**
+ * Release a refresh lock
+ * Uses Lua script to ensure atomic validation and release
+ */
+export declare function releaseRefreshLock(sessionToken: string, requestId: string, lockVersion?: number): Promise<boolean>;
+/**
+ * Check if a refresh lock exists for a session
+ */
+export declare function checkRefreshLock(sessionToken: string): Promise<RefreshLockInfo | null>;
+/**
+ * Simple check if a refresh is currently in progress for a session
+ */
+export declare function isRefreshInProgress(sessionToken: string): Promise<boolean>;
+/**
+ * Force cleanup of expired or orphaned refresh locks
+ */
+export declare function cleanupRefreshLocks(): Promise<number>;