@awell-health/navi-core/dist/auth.d.ts

Core utilities and GraphQL client for Navi care flow integration

import { JWTPayload, SessionTokenData, AuthenticationState } from "./types";
/**
 * JWT-based authentication service for Navi care flow integration.
 *
 * Handles the two-phase authentication flow:
 * 1. Session management for navi-portal backend (SessionTokenData)
 * 2. JWT generation for module-navi GraphQL API authentication (JWTPayload)
 *
 * @example Basic Session Flow
 * ```typescript
 * import { AuthService } from '@awell-health/navi-core';
 *
 * // Initialize the service
 * const authService = new AuthService();
 * await authService.initialize(process.env.JWT_SECRET);
 *
 * // Phase 1: Create session data for KV storage
 * const sessionData: SessionTokenData = {
 *   patientId: "mrn_12345",
 *   careflowId: "diabetes_management_v2",
 *   stakeholderId: "patient_john_doe",
 *   orgId: "healthcare_network_west",
 *   tenantId: "st_marys_hospital",
 *   environment: "production-us",
 *   authenticationState: "verified",
 *   exp: Math.floor(Date.now() / 1000) + (24 * 60 * 60)
 * };
 *
 * // Phase 2: Convert session to JWT for GraphQL API
 * const jwt = await authService.createJWTFromSession(
 *   sessionData,
 *   "sess_unique_identifier",
 *   "navi-portal.awellhealth.com"
 * );
 *
 * // Frontend can now use JWT to call module-navi GraphQL API
 * ```
 *
 * @example Full Authentication Flow
 * ```typescript
 * // 1. Browser requests care flow access
 * // 2. navi-portal backend creates and stores session
 * const sessionData = await kvStore.get(sessionId);
 *
 * // 3. Convert session to JWT for GraphQL API access
 * const authService = new AuthService();
 * await authService.initialize(process.env.JWT_SECRET);
 *
 * const jwt = await authService.createJWTFromSession(
 *   sessionData,
 *   sessionId,
 *   "navi-portal.awellhealth.com"
 * );
 *
 * // 4. Verify JWT when GraphQL API receives requests
 * try {
 *   const payload = await authService.verifyToken(jwt);
 *   console.log('Authenticated user:', payload.stakeholder_id);
 *   console.log('Careflow access:', payload.careflow_id);
 * } catch (error) {
 *   console.error('Authentication failed:', error.message);
 * }
 * ```
 *
 * @example Error Handling
 * ```typescript
 * try {
 *   const payload = await authService.verifyToken(suspiciousToken);
 * } catch (error) {
 *   if (error instanceof NaviAuthError) {
 *     // Log security event (HIPAA-compliant - no PHI)
 *     logger.warn('Authentication failed', {
 *       error: error.message,
 *       timestamp: new Date().toISOString(),
 *       ip: request.ip
 *     });
 *
 *     // Return generic error to client
 *     res.status(401).json({ error: 'Invalid authentication' });
 *   }
 * }
 * ```
 */
export declare class AuthService {
    private readonly secret?;
    private secretKey;
    constructor(secret?: string | undefined);
    /**
     * Initialize the auth service with a secret key
     */
    initialize(secret?: string): Promise<void>;
    /**
     * Convert SessionTokenData to JWTPayload structure
     *
     * Handles the camelCase → snake_case field mapping and adds JWT-specific claims.
     *
     * @param sessionData - Session data from KV store
     * @param sessionId - Unique session identifier
     * @param issuer - JWT issuer (e.g., "navi-portal.awellhealth.com")
     * @returns JWTPayload - Converted payload ready for JWT signing
     */
    convertSessionToJWTPayload(sessionData: SessionTokenData, sessionId: string, issuer: string, options?: {
        authenticationState?: AuthenticationState;
        naviStytchUserId?: string;
    }): JWTPayload;
    /**
     * Create a signed JWT from SessionTokenData
     *
     * This is the primary method for navi-portal backend to generate
     * JWTs for frontend GraphQL API authentication.
     *
     * @param sessionData - Session data from KV store
     * @param sessionId - Unique session identifier
     * @param issuer - JWT issuer (e.g., "navi-portal.awellhealth.com")
     * @returns Promise<string> - Signed JWT token
     * @throws NaviAuthError - If conversion fails or token creation fails
     */
    createJWTFromSession(sessionData: SessionTokenData, sessionId: string, issuer: string, options?: {
        authenticationState?: AuthenticationState;
        naviStytchUserId?: string;
    }): Promise<string>;
    /**
     * Verify a JWT token and return validated payload
     *
     * Used by module-navi GraphQL API to authenticate incoming requests.
     *
     * @param token - JWT token string to verify
     * @returns Promise<JWTPayload> - Verified and validated JWT payload
     * @throws NaviAuthError - If token is invalid, expired, or fails validation
     */
    verifyToken(token: string): Promise<JWTPayload>;
}