@payez/next-mvp 3.9.1 → 4.0.1

package/dist/auth/types/auth-types.d.ts

@@ -1,417 +0,0 @@
-/**
- * ============================================================================
- * AUTH TYPES - Single Source of Truth
- * ============================================================================
- *
- * This file defines ALL authentication-related types for the PayEz Next MVP.
- * Every type has ONE name and ONE meaning. No aliases. No confusion.
- *
- * GLOSSARY:
- * ---------
- * RedisSessionId    - UUID stored in browser cookie, keys into Redis session
- * IdpAccessToken    - JWT from PayEz IDP, used for backend API calls
- * IdpRefreshToken   - JWT from PayEz IDP, used to get new access tokens
- * OAuthProviderToken - Token from Google/Microsoft/etc (NOT for our APIs)
- *
- * DATA FLOW:
- * ----------
- * 1. User logs in (credentials or OAuth)
- * 2. IDP returns IdpAccessToken + IdpRefreshToken
- * 3. We create RedisSessionData in Redis, get back RedisSessionId
- * 4. RedisSessionId goes in NextAuth JWT cookie (browser)
- * 5. On each request: cookie -> RedisSessionId -> Redis -> tokens
- *
- * SECURITY NOTES:
- * ---------------
- * - Tokens NEVER stored in NextAuth JWT (only RedisSessionId)
- * - Tokens ONLY stored in Redis (server-side)
- * - Browser only sees RedisSessionId (opaque UUID)
- *
- * @version 1.0.0
- * @since auth-refactor-2026-01
- */
-/**
- * UUID key for Redis session storage.
- *
- * This is what gets stored in the browser's NextAuth cookie.
- * It's an opaque identifier - the browser cannot decode it to get tokens.
- *
- * Format: UUID v4 (e.g., "550e8400-e29b-41d4-a716-446655440000")
- *
- * OLD NAMES (do not use):
- * - sessionToken
- * - token.redisSessionId
- */
-export type RedisSessionId = string & {
-    readonly __brand: 'RedisSessionId';
-};
-/**
- * JWT issued by PayEz IDP for calling backend APIs.
- *
- * This token:
- * - Is signed by the IDP's private key
- * - Contains user claims (sub, email, roles, client_id, etc.)
- * - Has short expiry (typically 1 hour)
- * - Goes in Authorization header for API calls
- *
- * OLD NAMES (do not use):
- * - accessToken
- * - idpAccessToken
- * - token.accessToken
- * - responseData.result.access_token
- */
-export type IdpAccessToken = string & {
-    readonly __brand: 'IdpAccessToken';
-};
-/**
- * JWT issued by PayEz IDP for refreshing the access token.
- *
- * This token:
- * - Is signed by the IDP's private key
- * - Has longer expiry (typically 30 days)
- * - Is single-use (rotated on each refresh)
- * - NEVER sent to frontend, ONLY stored in Redis
- *
- * OLD NAMES (do not use):
- * - refreshToken
- * - idpRefreshToken
- * - token.refreshToken
- */
-export type IdpRefreshToken = string & {
-    readonly __brand: 'IdpRefreshToken';
-};
-/**
- * Access token from OAuth provider (Google, Microsoft, etc.)
- *
- * This is NOT used for our APIs. It's the token from the OAuth provider
- * that we received during OAuth flow. We store it in case the app needs
- * to call the provider's APIs (e.g., Google Calendar).
- *
- * OLD NAMES (do not use):
- * - account.access_token
- * - oauthAccessToken
- */
-export type OAuthProviderToken = string & {
-    readonly __brand: 'OAuthProviderToken';
-};
-export declare function toRedisSessionId(value: string): RedisSessionId;
-export declare function toIdpAccessToken(value: string): IdpAccessToken;
-export declare function toIdpRefreshToken(value: string): IdpRefreshToken;
-export declare function toOAuthProviderToken(value: string): OAuthProviderToken;
-/**
- * What we store in the NextAuth JWT cookie.
- *
- * MINIMAL by design. The JWT cookie is sent with every request, so we
- * keep it small. All the real data lives in Redis.
- *
- * WHAT'S IN THE COOKIE:
- * - redisSessionId: Key to look up session in Redis
- * - sub: User ID (for quick access without Redis round-trip)
- * - iss: Issuer URL (for SSO token validation)
- *
- * WHAT'S NOT IN THE COOKIE:
- * - Access tokens (security risk if cookie stolen)
- * - Refresh tokens (security risk if cookie stolen)
- * - User details (wastes bandwidth)
- */
-export interface NextAuthJwtPayload {
-    /** Redis session key - the ONLY way to get tokens */
-    redisSessionId: RedisSessionId;
-    /** User ID from IDP (sub claim) */
-    sub: string;
-    /** JWT issuer - AUTH_ISSUER_URL for SSO validation */
-    iss: string;
-    /** JWT issued at timestamp */
-    iat?: number;
-    /** JWT expiry timestamp */
-    exp?: number;
-}
-/**
- * The complete session data stored in Redis.
- *
- * This is the single source of truth for a user's session state.
- * Everything about the session lives here - tokens, MFA status, user info.
- *
- * REDIS KEY FORMAT: "session:{redisSessionId}"
- * TTL: Matches refresh token expiry (typically 30 days)
- */
-export interface RedisSessionData {
-    /** User ID from IDP (matches JWT sub claim) */
-    userId: string;
-    /** User's email address */
-    email: string;
-    /** Display name (from OAuth profile or IDP) */
-    name?: string;
-    /** User's roles from IDP (e.g., ['user', 'admin']) */
-    roles: string[];
-    /** JWT for backend API calls */
-    idpAccessToken: IdpAccessToken;
-    /** JWT for refreshing access token */
-    idpRefreshToken: IdpRefreshToken;
-    /** When idpAccessToken expires (Unix ms) */
-    idpAccessTokenExpires: number;
-    /** When idpRefreshToken expires (Unix ms) - session dies when this expires */
-    idpRefreshTokenExpires?: number;
-    /**
-     * Decoded access token claims (cached to avoid repeated JWT parsing)
-     * Contains: sub, email, roles, client_id, merchant_id, amr, acr, etc.
-     */
-    decodedAccessToken?: DecodedIdpAccessToken;
-    /**
-     * Bearer Key ID (kid from JWT header).
-     *
-     * This is the key ID used to sign the IDP access token.
-     * CRITICAL: This is from the JWT HEADER, not the payload.
-     * Do NOT confuse with client_id (which is in the payload).
-     *
-     * Used for:
-     * - Key governance verification
-     * - Identifying which IDP signing key was used
-     * - Token validation on the backend
-     *
-     * May be undefined for sessions created before this field was added.
-     */
-    bearerKeyId?: string;
-    /**
-     * Has the user completed MFA for this session?
-     *
-     * TRUE means: User has verified their identity with a second factor
-     * FALSE means: User is in "provisional" state, limited access
-     *
-     * OLD NAMES (do not use):
-     * - twoFactorComplete
-     * - twoFactorSessionVerified
-     * - requiresTwoFactor (this was the INVERSE, very confusing)
-     */
-    mfaVerified: boolean;
-    /** How the user completed MFA */
-    mfaMethod?: 'email' | 'sms' | 'totp' | 'authenticator';
-    /** When MFA was completed (Unix ms) */
-    mfaCompletedAt?: number;
-    /** When MFA verification expires, requiring re-verification (Unix ms) */
-    mfaExpiresAt?: number;
-    /** How long MFA is valid (hours) - from client config */
-    mfaValidityHours?: number;
-    /**
-     * Authentication methods used (AMR claim from token)
-     * e.g., ['pwd', 'mfa', 'otp']
-     */
-    authenticationMethods?: string[];
-    /**
-     * Authentication context class (ACR claim from token)
-     * '1' = single factor, '2' = multi-factor
-     */
-    authenticationLevel?: string;
-    /** Which OAuth provider was used (e.g., 'google', 'microsoft') */
-    oauthProvider?: string;
-    /** Token from the OAuth provider (for calling provider APIs) */
-    oauthProviderToken?: OAuthProviderToken;
-    /** Refresh token from OAuth provider */
-    oauthProviderRefreshToken?: string;
-    /** IDP client ID this session belongs to */
-    idpClientId?: string;
-    /** Merchant ID for payment processing */
-    merchantId?: string;
-}
-/**
- * Claims extracted from the IdpAccessToken JWT.
- *
- * We cache this in Redis to avoid parsing the JWT on every request.
- * These are the claims that the IDP puts in the access token.
- */
-export interface DecodedIdpAccessToken {
-    /** Subject - User ID */
-    sub: string;
-    /** Issuer - IDP URL */
-    iss: string;
-    /** Audience - who this token is for */
-    aud?: string | string[];
-    /** Expiration time (Unix seconds) */
-    exp: number;
-    /** Issued at time (Unix seconds) */
-    iat: number;
-    /** Not before time (Unix seconds) */
-    nbf?: number;
-    /** JWT ID - unique identifier for this token */
-    jti?: string;
-    /** User's email (may be in different claim names) */
-    email?: string;
-    'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'?: string;
-    /** User's roles */
-    role?: string | string[];
-    roles?: string | string[];
-    /** Client ID this token was issued for */
-    client_id?: string;
-    /** Client slug (human-readable identifier) */
-    client_slug?: string;
-    /** Merchant ID for payment processing */
-    merchant_id?: string;
-    /** Authentication methods used */
-    amr?: string | string[];
-    /** Authentication context class */
-    acr?: string;
-    /** MFA completion time (Unix seconds) */
-    mfa_time?: number;
-    /** MFA expiry time (Unix seconds) */
-    mfa_expires?: number;
-    /** MFA validity period (hours) */
-    mfa_validity_hours?: number;
-}
-/**
- * The session object returned by NextAuth's useSession() hook.
- *
- * This is what React components receive. It contains user info and
- * session metadata, but NOT raw tokens (those stay server-side).
- *
- * To make API calls, use the API routes which have access to Redis.
- */
-export interface AppSession {
-    user: {
-        /** User ID from IDP */
-        id: string;
-        /** User's email */
-        email: string;
-        /** Display name */
-        name?: string;
-        /** User's roles */
-        roles: string[];
-        /** Has user completed MFA? */
-        mfaVerified: boolean;
-        /** OAuth provider if applicable */
-        oauthProvider?: string;
-    };
-    /** Redis session key (for API routes that need it) */
-    redisSessionId: RedisSessionId;
-    /** Session expiry info */
-    expires: string;
-    /** Error state if something went wrong */
-    error?: 'SessionNotFound' | 'RefreshFailed' | 'MfaExpired' | 'TokenExpired';
-}
-/**
- * Response from IDP login endpoint (/api/ExternalAuth/login)
- *
- * Note: IDP returns snake_case. We normalize to camelCase at the boundary.
- */
-export interface IdpLoginResponse {
-    success: boolean;
-    result?: {
-        access_token: string;
-        refresh_token: string;
-        expires_in: number;
-        token_type: 'Bearer';
-        user?: {
-            userId: number;
-            email: string;
-            fullName?: string;
-            isEmailConfirmed?: boolean;
-            isSmsConfirmed?: boolean;
-            roles?: string[];
-        };
-    };
-    error?: {
-        code: string;
-        message: string;
-        details?: {
-            errors?: Array<{
-                code: string;
-                message: string;
-            }>;
-            attempts_remaining?: number;
-        };
-    };
-}
-/**
- * Response from IDP OAuth callback (/api/ExternalAuth/oauth-callback)
- */
-export interface IdpOAuthCallbackResponse {
-    success: boolean;
-    data?: {
-        accessToken: string;
-        refreshToken: string;
-        isNewUser: boolean;
-        user?: {
-            userId: number;
-            email: string;
-            fullName?: string;
-            roles?: string[];
-        };
-    };
-    error?: {
-        code: string;
-        message: string;
-    };
-}
-/**
- * Response from IDP token refresh (/api/ExternalAuth/refresh)
- */
-export interface IdpRefreshResponse {
-    success: boolean;
-    data?: {
-        access_token: string;
-        refresh_token?: string;
-        expires_in: number;
-    };
-    error?: {
-        code: string;
-        message: string;
-    };
-}
-/**
- * Result of the ensureFreshToken() utility
- */
-export type EnsureFreshTokenResult = {
-    success: true;
-    idpAccessToken: IdpAccessToken;
-    sessionData: RedisSessionData;
-} | {
-    success: false;
-    error: AuthError;
-    message: string;
-};
-/**
- * Possible auth errors
- */
-export type AuthError = 'NO_SESSION' | 'NO_TOKEN' | 'TOKEN_EXPIRED' | 'REFRESH_FAILED' | 'MFA_REQUIRED' | 'MFA_EXPIRED' | 'SESSION_INVALID' | 'CLIENT_MISMATCH';
-/**
- * Credentials submitted via the login form
- */
-export interface LoginCredentials {
-    email: string;
-    password: string;
-}
-/**
- * What the CredentialsProvider.authorize() function returns
- */
-export interface AuthorizeResult {
-    /** User ID from IDP */
-    id: string;
-    /** User's email */
-    email: string;
-    /** User's roles */
-    roles: string[];
-    /** Redis session ID (created during authorize) */
-    redisSessionId: RedisSessionId;
-    /** Whether user needs to complete MFA */
-    mfaRequired: boolean;
-    /** Available MFA methods */
-    mfaMethod?: 'email' | 'sms' | 'totp';
-}
-/**
- * OAuth account info from NextAuth
- */
-export interface OAuthAccountInfo {
-    provider: string;
-    providerAccountId: string;
-    access_token?: string;
-    refresh_token?: string;
-    expires_at?: number;
-}
-/**
- * OAuth user info from provider
- */
-export interface OAuthUserInfo {
-    id?: string;
-    email?: string;
-    name?: string;
-    image?: string;
-}

package/dist/auth/types/auth-types.js

@@ -1,53 +0,0 @@
-"use strict";
-/**
- * ============================================================================
- * AUTH TYPES - Single Source of Truth
- * ============================================================================
- *
- * This file defines ALL authentication-related types for the PayEz Next MVP.
- * Every type has ONE name and ONE meaning. No aliases. No confusion.
- *
- * GLOSSARY:
- * ---------
- * RedisSessionId    - UUID stored in browser cookie, keys into Redis session
- * IdpAccessToken    - JWT from PayEz IDP, used for backend API calls
- * IdpRefreshToken   - JWT from PayEz IDP, used to get new access tokens
- * OAuthProviderToken - Token from Google/Microsoft/etc (NOT for our APIs)
- *
- * DATA FLOW:
- * ----------
- * 1. User logs in (credentials or OAuth)
- * 2. IDP returns IdpAccessToken + IdpRefreshToken
- * 3. We create RedisSessionData in Redis, get back RedisSessionId
- * 4. RedisSessionId goes in NextAuth JWT cookie (browser)
- * 5. On each request: cookie -> RedisSessionId -> Redis -> tokens
- *
- * SECURITY NOTES:
- * ---------------
- * - Tokens NEVER stored in NextAuth JWT (only RedisSessionId)
- * - Tokens ONLY stored in Redis (server-side)
- * - Browser only sees RedisSessionId (opaque UUID)
- *
- * @version 1.0.0
- * @since auth-refactor-2026-01
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.toRedisSessionId = toRedisSessionId;
-exports.toIdpAccessToken = toIdpAccessToken;
-exports.toIdpRefreshToken = toIdpRefreshToken;
-exports.toOAuthProviderToken = toOAuthProviderToken;
-// ============================================================================
-// HELPER FUNCTIONS - Create branded types from raw strings
-// ============================================================================
-function toRedisSessionId(value) {
-    return value;
-}
-function toIdpAccessToken(value) {
-    return value;
-}
-function toIdpRefreshToken(value) {
-    return value;
-}
-function toOAuthProviderToken(value) {
-    return value;
-}

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

@@ -1,6 +0,0 @@
-/**
- * Auth Types - Public Exports
- *
- * Import from '@payez/next-mvp/auth/types' or '@payez/next-mvp/auth'
- */
-export * from './auth-types';

package/dist/auth/types/index.js

@@ -1,22 +0,0 @@
-"use strict";
-/**
- * Auth Types - Public Exports
- *
- * Import from '@payez/next-mvp/auth/types' or '@payez/next-mvp/auth'
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./auth-types"), exports);

package/dist/auth/unauthenticated-routes.d.ts

@@ -1 +0,0 @@
-export * from './route-config';

package/dist/auth/unauthenticated-routes.js

@@ -1,19 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-// src/auth/unauthenticated-routes.ts
-// Re-exporting from route-config for backward compatibility
-__exportStar(require("./route-config"), exports);

package/dist/auth/utils/idp-client.d.ts

@@ -1,94 +0,0 @@
-/**
- * IDP Client Utilities
- *
- * Functions for calling PayEz IDP API endpoints.
- * Handles login, OAuth callback, token refresh, and 2FA verification.
- *
- * URL USAGE:
- * - IDP_URL: Used for all calls to the PayEz Identity Provider
- * - INTERNAL_API_URL: NOT used here - that's for calling THIS app's own endpoints
- *
- * @version 1.0.0
- * @since auth-refactor-2026-01
- */
-import type { IdpLoginResponse, IdpOAuthCallbackResponse, IdpRefreshResponse, LoginCredentials } from '../types/auth-types';
-/**
- * Get IDP base URL. Throws if not configured.
- */
-export declare function getIdpUrl(): string;
-/**
- * Get client ID for this application.
- */
-export declare function getClientId(): string;
-/**
- * Authenticate user with email/password via IDP.
- *
- * @param credentials - User's email and password
- * @param clientHeaders - Headers to forward (IP, User-Agent for audit)
- * @returns IDP login response with tokens or error
- */
-export declare function idpLogin(credentials: LoginCredentials, clientHeaders?: {
-    ip?: string;
-    userAgent?: string;
-}): Promise<IdpLoginResponse>;
-/**
- * Register/authenticate OAuth user with IDP.
- *
- * Called after OAuth provider (Google, etc.) redirects back.
- * Creates or retrieves IDP user and returns IDP tokens.
- *
- * @param oauthData - Data from OAuth provider
- * @returns IDP response with tokens and user info
- */
-export declare function idpOAuthCallback(oauthData: {
-    provider: string;
-    providerAccountId: string;
-    email: string;
-    name?: string;
-    image?: string;
-    accessToken?: string;
-    refreshToken?: string;
-    expiresAt?: number;
-}): Promise<IdpOAuthCallbackResponse>;
-/**
- * Refresh an expired access token using the refresh token.
- *
- * @param refreshToken - The refresh token from previous login
- * @param mfaContext - MFA context to preserve across refresh
- * @returns New tokens or error
- */
-export declare function idpRefreshToken(refreshToken: string, mfaContext?: {
-    amr?: string[];
-    acr?: string;
-    twoFactorVerified?: boolean;
-    twoFactorMethod?: string;
-    twoFactorCompletedAt?: number;
-}): Promise<IdpRefreshResponse>;
-/**
- * Verify 2FA code with IDP.
- *
- * @param sessionToken - Redis session ID
- * @param code - The 2FA code entered by user
- * @param method - The 2FA method ('email' | 'sms' | 'totp')
- * @returns Success status and updated tokens
- */
-export declare function idpVerify2FA(accessToken: string, code: string, method: 'email' | 'sms' | 'totp'): Promise<{
-    success: boolean;
-    error?: {
-        code: string;
-        message: string;
-    };
-}>;
-/**
- * Request a new 2FA code to be sent.
- *
- * @param accessToken - User's access token
- * @param method - How to send the code ('email' | 'sms')
- */
-export declare function idpSend2FACode(accessToken: string, method: 'email' | 'sms'): Promise<{
-    success: boolean;
-    error?: {
-        code: string;
-        message: string;
-    };
-}>;