@openeudi/core 0.1.5 → 0.2.0

package/dist/index.d.cts

@@ -12,50 +12,21 @@ declare enum VerificationType {
     BOTH = "BOTH"
 }
 /**
- * Status of a verification session
+ * Status of a verification session.
+ * SCANNED has been removed — the in-flight credential exchange state
+ * is an internal wallet concern, not a session lifecycle stage.
  */
 declare enum VerificationStatus {
-    /** Session created, waiting for wallet scan */
+    /** Session created, waiting for wallet to initiate the flow */
     PENDING = "PENDING",
-    /** QR code scanned, credential exchange in progress */
-    SCANNED = "SCANNED",
     /** Verification completed successfully */
     VERIFIED = "VERIFIED",
-    /** Verification rejected (age, country, or policy) */
+    /** Verification rejected (age, country, or policy failure) */
     REJECTED = "REJECTED",
     /** Session expired before completion */
     EXPIRED = "EXPIRED"
 }
 
-/**
- * A verification session tracked by the service
- */
-interface VerificationSession {
-    /** Unique session identifier (UUIDv4) */
-    id: string;
-    /** Type of verification requested */
-    type: VerificationType;
-    /** Current session status */
-    status: VerificationStatus;
-    /** URL for wallet to initiate OpenID4VP flow */
-    walletUrl: string;
-    /** Allowed countries (ISO 3166-1 alpha-2) */
-    countryWhitelist?: string[];
-    /** Blocked countries (ISO 3166-1 alpha-2) */
-    countryBlacklist?: string[];
-    /** Redirect URL after verification completes */
-    redirectUrl?: string;
-    /** Custom metadata attached to session */
-    metadata?: Record<string, unknown>;
-    /** Session creation timestamp */
-    createdAt: Date;
-    /** Session expiry timestamp */
-    expiresAt: Date;
-    /** Completion timestamp (if verified/rejected) */
-    completedAt?: Date;
-    /** Verification result (populated after completion) */
-    result?: VerificationResult;
-}
 /**
  * Result of a completed verification
  */
@@ -77,15 +48,77 @@ interface VerificationResult {
 interface CreateSessionInput {
     /** Type of verification to perform */
     type: VerificationType;
+    /** Allowed countries (ISO 3166-1 alpha-2). Cannot be combined with countryBlacklist. */
+    countryWhitelist?: string[];
+    /** Blocked countries (ISO 3166-1 alpha-2). Cannot be combined with countryWhitelist. */
+    countryBlacklist?: string[];
+    /** Redirect URL after verification completes */
+    redirectUrl?: string;
+    /** Custom metadata to attach to session */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Fields common to all verification session states.
+ * Use the discriminated union {@link VerificationSession} in most cases.
+ */
+interface BaseSession {
+    /** Unique session identifier (UUIDv4) */
+    id: string;
+    /** Type of verification requested */
+    type: VerificationType;
+    /** URL for the wallet to initiate the OpenID4VP flow */
+    walletUrl: string;
     /** Allowed countries (ISO 3166-1 alpha-2) */
     countryWhitelist?: string[];
     /** Blocked countries (ISO 3166-1 alpha-2) */
     countryBlacklist?: string[];
     /** Redirect URL after verification completes */
     redirectUrl?: string;
-    /** Custom metadata to attach to session */
+    /** Custom metadata attached to session */
     metadata?: Record<string, unknown>;
+    /** Session creation timestamp */
+    createdAt: Date;
+    /** Session expiry timestamp */
+    expiresAt: Date;
+}
+/**
+ * A session that is waiting for wallet interaction.
+ * No result or completion timestamp is available.
+ */
+interface PendingSession extends BaseSession {
+    /** Discriminant: session is awaiting wallet scan */
+    status: VerificationStatus.PENDING;
+}
+/**
+ * A session where the wallet completed the credential exchange,
+ * either successfully (VERIFIED) or with a policy failure (REJECTED).
+ */
+interface CompletedSession extends BaseSession {
+    /** Discriminant: session finished with a terminal verified or rejected outcome */
+    status: VerificationStatus.VERIFIED | VerificationStatus.REJECTED;
+    /** Full result of the credential exchange */
+    result: VerificationResult;
+    /** Timestamp when the session transitioned to this status */
+    completedAt: Date;
+}
+/**
+ * A session that timed out before the wallet completed the flow.
+ */
+interface ExpiredSession extends BaseSession {
+    /** Discriminant: session reached its TTL without completion */
+    status: VerificationStatus.EXPIRED;
+    /** Timestamp when expiry was detected and recorded */
+    completedAt: Date;
 }
+/**
+ * Discriminated union of all possible verification session states.
+ *
+ * Narrow by checking `session.status`:
+ * - `PENDING`  => {@link PendingSession}
+ * - `VERIFIED` | `REJECTED` => {@link CompletedSession}
+ * - `EXPIRED`  => {@link ExpiredSession}
+ */
+type VerificationSession = PendingSession | CompletedSession | ExpiredSession;
 
 /**
  * Strategy interface for verification modes.
@@ -98,11 +131,11 @@ interface IVerificationMode {
      * Process a callback from a wallet (or simulated callback).
      * Called when the wallet sends credential data back.
      *
-     * @param session - The current verification session
+     * @param session - The current verification session (any state)
      * @param walletResponse - Raw data from the wallet (format depends on mode)
      * @returns Verification result
      */
-    processCallback(session: VerificationSession, walletResponse: unknown): Promise<VerificationResult>;
+    processCallback(session: BaseSession, walletResponse: unknown): Promise<VerificationResult>;
     /**
      * Optional: simulate automatic completion (used by DemoMode).
      * If implemented, the service calls this after session creation
@@ -111,7 +144,7 @@ interface IVerificationMode {
      * @param session - The session to auto-complete
      * @returns Verification result after simulated delay
      */
-    simulateCompletion?(session: VerificationSession): Promise<VerificationResult>;
+    simulateCompletion?(session: BaseSession): Promise<VerificationResult>;
     /**
      * Optional: build a custom wallet URL for the session.
      * Used by ProductionMode to generate proper OpenID4VP authorization requests.
@@ -151,6 +184,63 @@ interface VerificationServiceConfig {
     walletBaseUrl?: string;
 }
 
+/**
+ * Typed event map for {@link VerificationService}.
+ *
+ * Use this interface to get full type inference when listening to events:
+ *
+ * @example
+ * ```typescript
+ * const service = new VerificationService(config);
+ *
+ * service.on('session:verified', (session, result) => {
+ *     // session: CompletedSession, result: VerificationResult
+ * });
+ * ```
+ *
+ * Each key maps to a tuple of the listener argument types, following the
+ * Node.js `EventEmitter` typed-overload convention.
+ */
+interface VerificationEvents {
+    /**
+     * Fired after a new session is persisted to the store.
+     * @param session - The freshly created pending session
+     */
+    'session:created': [session: PendingSession];
+    /**
+     * Fired after the wallet successfully completes credential exchange
+     * and all policy checks pass.
+     * @param session - The session now carrying VERIFIED status and result
+     * @param result - The full verification result
+     */
+    'session:verified': [session: CompletedSession, result: VerificationResult];
+    /**
+     * Fired after the wallet completes credential exchange but a policy
+     * check fails (age, country, or custom rule).
+     * @param session - The session now carrying REJECTED status
+     * @param reason - Human-readable rejection reason (from result.rejectionReason)
+     */
+    'session:rejected': [session: CompletedSession, reason: string];
+    /**
+     * Fired when a pending session is detected to have passed its TTL
+     * during a {@link VerificationService.cleanupExpired} sweep.
+     * @param session - The session now carrying EXPIRED status
+     */
+    'session:expired': [session: ExpiredSession];
+    /**
+     * Fired when a caller explicitly cancels a pending session.
+     * @param session - The session at the time of cancellation
+     */
+    'session:cancelled': [session: BaseSession];
+    /**
+     * Fired when an internal error occurs that cannot be surfaced via a
+     * rejected Promise (e.g. an error inside a fire-and-forget simulation).
+     * @param error - The underlying error
+     * @param sessionId - Session ID if the error is session-scoped
+     */
+    'error': [error: Error, sessionId?: string];
+}
+
 /**
  * Thrown when a session ID is not found in the store
  */
@@ -163,6 +253,24 @@ declare class SessionNotFoundError extends Error {
 declare class SessionExpiredError extends Error {
     constructor(sessionId: string);
 }
+/**
+ * Thrown when an operation requires a session to be in PENDING status
+ * but it is in a different status (e.g., cancelling an already-completed session).
+ */
+declare class SessionNotPendingError extends Error {
+    /** The session ID that was not in PENDING status */
+    readonly sessionId: string;
+    /** The status the session was actually in */
+    readonly currentStatus: string;
+    constructor(sessionId: string, currentStatus: string);
+}
+/**
+ * Thrown when any method is called on a {@link VerificationService} instance
+ * after {@link VerificationService.destroy} has been invoked.
+ */
+declare class ServiceDestroyedError extends Error {
+    constructor();
+}
 
 /**
  * In-memory session store using a Map.
@@ -181,15 +289,15 @@ interface DemoModeConfig {
     delayMs?: number;
 }
 /**
- * Demo mode — auto-completes verification with randomized EU data.
+ * Demo mode -- auto-completes verification with randomized EU data.
  * Used for product demos and landing page previews.
  */
 declare class DemoMode implements IVerificationMode {
     readonly name = "demo";
     private delayMs;
     constructor(config?: DemoModeConfig);
-    processCallback(session: VerificationSession, _walletResponse: unknown): Promise<VerificationResult>;
-    simulateCompletion(session: VerificationSession): Promise<VerificationResult>;
+    processCallback(session: BaseSession, _walletResponse: unknown): Promise<VerificationResult>;
+    simulateCompletion(session: BaseSession): Promise<VerificationResult>;
     private pickCountry;
     private buildResult;
 }
@@ -201,7 +309,7 @@ interface MockModeConfig {
     delayMs?: number;
 }
 /**
- * Mock mode — configurable responses for integration testing.
+ * Mock mode -- configurable responses for integration testing.
  * Supports global defaults and per-session overrides.
  */
 declare class MockMode implements IVerificationMode {
@@ -214,17 +322,51 @@ declare class MockMode implements IVerificationMode {
     setSessionResult(sessionId: string, result: VerificationResult): void;
     /** Clear a per-session result override */
     clearSessionResult(sessionId: string): void;
-    processCallback(session: VerificationSession, _walletResponse: unknown): Promise<VerificationResult>;
-    simulateCompletion(session: VerificationSession): Promise<VerificationResult>;
+    processCallback(session: BaseSession, _walletResponse: unknown): Promise<VerificationResult>;
+    simulateCompletion(session: BaseSession): Promise<VerificationResult>;
 }
 
+/**
+ * Check whether a value is a valid ISO 3166-1 alpha-2 country code.
+ *
+ * The check is case-sensitive: codes must be uppercase two-letter strings
+ * (e.g. `'DE'`, `'FR'`). Lowercase variants (`'de'`), three-letter codes
+ * (`'DEU'`), empty strings, and unknown codes all return `false`.
+ *
+ * @param code - The string to validate
+ * @returns `true` if `code` is a recognised ISO 3166-1 alpha-2 code
+ *
+ * @example
+ * ```typescript
+ * isValidCountryCode('DE'); // true
+ * isValidCountryCode('de'); // false — must be uppercase
+ * isValidCountryCode('DEU'); // false — alpha-3, not alpha-2
+ * isValidCountryCode('XX'); // false — not a real country
+ * ```
+ */
+declare function isValidCountryCode(code: string): boolean;
+
 /**
  * EUDI Wallet verification session orchestrator.
  *
  * Manages the lifecycle of verification sessions: creation, status tracking,
- * wallet callback handling, expiration, and event emission.
+ * wallet callback handling, cancellation, expiration, and event emission.
  *
- * Transport-agnostic — consumers wire events to SSE, WebSocket, polling, etc.
+ * Transport-agnostic -- consumers wire events to SSE, WebSocket, polling, etc.
+ *
+ * @example
+ * ```typescript
+ * const service = new VerificationService({
+ *     mode: new DemoMode({ delayMs: 2000 }),
+ *     sessionTtlMs: 60_000,
+ * });
+ *
+ * service.on('session:verified', (session, result) => {
+ *     console.log('Verified:', session.id, result.country);
+ * });
+ *
+ * const session = await service.createSession({ type: VerificationType.AGE });
+ * ```
  */
 declare class VerificationService extends EventEmitter {
     private store;
@@ -233,30 +375,183 @@ declare class VerificationService extends EventEmitter {
     private walletBaseUrl;
     /** Track session IDs for cleanup (store interface has no list method) */
     private sessionIds;
+    /** Whether {@link destroy} has been called */
+    private destroyed;
+    /**
+     * Create a new VerificationService instance.
+     *
+     * @param config - Service configuration including mode, store, TTL, and wallet URL
+     * @throws {Error} If config.sessionTtlMs is not positive or config.walletBaseUrl is empty
+     *
+     * @example
+     * ```typescript
+     * const service = new VerificationService({
+     *     mode: new DemoMode(),
+     *     store: new InMemorySessionStore(),
+     *     sessionTtlMs: 300_000,
+     *     walletBaseUrl: 'openid4vp://verify',
+     * });
+     * ```
+     */
     constructor(config: VerificationServiceConfig);
     /**
-     * Create a new verification session
+     * Register a listener for a typed event.
+     *
+     * @param event - Event name from {@link VerificationEvents}
+     * @param listener - Callback receiving the event's typed arguments
+     * @returns this (for chaining)
+     */
+    on<K extends keyof VerificationEvents>(event: K, listener: (...args: VerificationEvents[K]) => void): this;
+    /**
+     * Register a one-time listener for a typed event.
+     *
+     * @param event - Event name from {@link VerificationEvents}
+     * @param listener - Callback receiving the event's typed arguments (called at most once)
+     * @returns this (for chaining)
      */
-    createSession(input: CreateSessionInput): Promise<VerificationSession>;
+    once<K extends keyof VerificationEvents>(event: K, listener: (...args: VerificationEvents[K]) => void): this;
     /**
-     * Get a session by ID
-     * @throws SessionNotFoundError
+     * Remove a previously registered listener for a typed event.
+     *
+     * @param event - Event name from {@link VerificationEvents}
+     * @param listener - The exact function reference that was registered
+     * @returns this (for chaining)
+     */
+    off<K extends keyof VerificationEvents>(event: K, listener: (...args: VerificationEvents[K]) => void): this;
+    /**
+     * Emit a typed event.
+     *
+     * @param event - Event name from {@link VerificationEvents}
+     * @param args - Arguments matching the event's type signature
+     * @returns true if the event had listeners, false otherwise
+     */
+    emit<K extends keyof VerificationEvents>(event: K, ...args: VerificationEvents[K]): boolean;
+    /**
+     * Create a new verification session.
+     *
+     * Builds the wallet URL, persists the session, emits `session:created`,
+     * and (if the mode supports it) kicks off background auto-completion.
+     *
+     * @param input - Session creation parameters (type, country filters, metadata)
+     * @returns The newly created pending session with a populated walletUrl
+     * @throws {ServiceDestroyedError} If the service has been destroyed
+     * @throws {Error} If input validation fails (e.g. invalid country codes)
+     * @emits session:created When the session is persisted
+     *
+     * @example
+     * ```typescript
+     * const session = await service.createSession({
+     *     type: VerificationType.AGE,
+     *     countryWhitelist: ['DE', 'FR'],
+     * });
+     * console.log(session.walletUrl); // 'openid4vp://verify?session=...'
+     * ```
+     */
+    createSession(input: CreateSessionInput): Promise<PendingSession>;
+    /**
+     * Retrieve a session by its ID.
+     *
+     * @param id - The session UUID to look up
+     * @returns The session in its current state
+     * @throws {ServiceDestroyedError} If the service has been destroyed
+     * @throws {SessionNotFoundError} If no session exists with the given ID
+     *
+     * @example
+     * ```typescript
+     * const session = await service.getSession('550e8400-e29b-41d4-a716-446655440000');
+     * if (session.status === VerificationStatus.VERIFIED) {
+     *     console.log('Already verified:', session.result);
+     * }
+     * ```
      */
     getSession(id: string): Promise<VerificationSession>;
     /**
-     * Handle a callback from the wallet
-     * @throws SessionNotFoundError
-     * @throws SessionExpiredError
+     * Handle a callback from the wallet containing credential data.
+     *
+     * Delegates to the mode's `processCallback` to evaluate the wallet response,
+     * then transitions the session to VERIFIED or REJECTED.
+     *
+     * @param sessionId - The session UUID the callback belongs to
+     * @param walletResponse - Raw credential data from the wallet
+     * @returns The verification result
+     * @throws {ServiceDestroyedError} If the service has been destroyed
+     * @throws {SessionNotFoundError} If no session exists with the given ID
+     * @throws {SessionExpiredError} If the session has passed its TTL
+     * @emits session:verified When verification succeeds
+     * @emits session:rejected When verification fails
+     *
+     * @example
+     * ```typescript
+     * const result = await service.handleCallback(sessionId, walletData);
+     * if (result.verified) {
+     *     grantAccess(result.country);
+     * }
+     * ```
      */
     handleCallback(sessionId: string, walletResponse: unknown): Promise<VerificationResult>;
     /**
-     * Remove expired sessions from the store
-     * @returns Number of sessions cleaned up
+     * Cancel a pending verification session.
+     *
+     * Only sessions in PENDING status can be cancelled. Completed or expired
+     * sessions will cause a {@link SessionNotPendingError}.
+     *
+     * @param id - The session UUID to cancel
+     * @throws {ServiceDestroyedError} If the service has been destroyed
+     * @throws {SessionNotFoundError} If no session exists with the given ID
+     * @throws {SessionNotPendingError} If the session is not in PENDING status
+     * @emits session:cancelled When the session is removed
+     *
+     * @example
+     * ```typescript
+     * await service.cancelSession(session.id);
+     * // session is now deleted from the store
+     * ```
+     */
+    cancelSession(id: string): Promise<void>;
+    /**
+     * Remove expired sessions from the store.
+     *
+     * Iterates all tracked session IDs and transitions any pending session
+     * whose TTL has elapsed to EXPIRED status before deleting it.
+     *
+     * @returns Number of sessions that were expired and removed
+     * @throws {ServiceDestroyedError} If the service has been destroyed
+     * @emits session:expired For each session that is expired
+     *
+     * @example
+     * ```typescript
+     * // Run periodically (e.g. every 60 seconds)
+     * const count = await service.cleanupExpired();
+     * console.log(`Cleaned up ${count} expired sessions`);
+     * ```
      */
     cleanupExpired(): Promise<number>;
+    /**
+     * Permanently destroy this service instance.
+     *
+     * Removes all event listeners, clears tracked session IDs, and marks
+     * the instance as destroyed. All subsequent public method calls will
+     * throw {@link ServiceDestroyedError}.
+     *
+     * @example
+     * ```typescript
+     * service.destroy();
+     * // Any further call throws ServiceDestroyedError
+     * await service.createSession({ type: VerificationType.AGE }); // throws
+     * ```
+     */
+    destroy(): void;
+    /**
+     * Guard that throws if the service has been destroyed.
+     * Called at the top of every public method.
+     */
+    private assertNotDestroyed;
+    /**
+     * Transition a session to VERIFIED or REJECTED and emit the appropriate event.
+     */
     private completeSession;
 }
 
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.2.0";
 
-export { type CreateSessionInput, DemoMode, type DemoModeConfig, type ISessionStore, type IVerificationMode, InMemorySessionStore, MockMode, type MockModeConfig, SessionExpiredError, SessionNotFoundError, VERSION, type VerificationResult, VerificationService, type VerificationServiceConfig, type VerificationSession, VerificationStatus, VerificationType };
+export { type BaseSession, type CompletedSession, type CreateSessionInput, DemoMode, type DemoModeConfig, type ExpiredSession, type ISessionStore, type IVerificationMode, InMemorySessionStore, MockMode, type MockModeConfig, type PendingSession, ServiceDestroyedError, SessionExpiredError, SessionNotFoundError, SessionNotPendingError, VERSION, type VerificationEvents, type VerificationResult, VerificationService, type VerificationServiceConfig, type VerificationSession, VerificationStatus, VerificationType, isValidCountryCode };