@openeudi/core

Framework-agnostic EUDI Wallet verification protocol engine.

npm install @openeudi/core

Quick Start

import {
    VerificationService,
    DemoMode,
    VerificationType,
    VerificationStatus,
} from "@openeudi/core";

const service = new VerificationService({ mode: new DemoMode() });

// Typed events -- event name typos are caught at compile time
service.on("session:created", (session) => {
    console.log("Session ready:", session.walletUrl);
});
service.on("session:verified", (session, result) => {
    console.log("Verified:", result.country, "age:", result.ageVerified);
});
service.on("session:rejected", (session, reason) => {
    console.warn("Rejected:", reason);
});
service.on("error", (err, sessionId) => {
    console.error("Background error for session", sessionId, err);
});

const session = await service.createSession({ type: VerificationType.BOTH });
console.log(session.walletUrl); // openid4vp://verify?session=<uuid>

// Teardown when done
service.destroy();

Modes

DemoMode

Auto-completes sessions with randomized EU citizen data after a configurable delay. Ideal for product demos and landing pages.

import { DemoMode } from "@openeudi/core";

const mode = new DemoMode({
    delayMs: 2000, // auto-complete after 2s (default: 3000)
});

MockMode

Returns deterministic results for integration testing. Supports global defaults and per-session overrides.

import { MockMode } from "@openeudi/core";

const mode = new MockMode({
    defaultResult: { verified: true, country: "FR", ageVerified: true },
    delayMs: 100,
});

const service = new VerificationService({ mode });
const session = await service.createSession({ type: VerificationType.AGE });

// Override result for a specific session
mode.setSessionResult(session.id, {
    verified: false,
    rejectionReason: "underage",
});

// Remove override
mode.clearSessionResult(session.id);

Custom Mode

Implement IVerificationMode to connect to a real EUDI Wallet relying party:

import type {
    IVerificationMode,
    BaseSession,
    VerificationResult,
} from "@openeudi/core";

class ProductionMode implements IVerificationMode {
    readonly name = "production";

    async processCallback(
        session: BaseSession,
        walletResponse: unknown,
    ): Promise<VerificationResult> {
        const claims = await verifyVPToken(walletResponse); // your OpenID4VP logic
        return { verified: true, country: claims.country, ageVerified: claims.age >= 18 };
    }
}

Custom Storage

The default InMemorySessionStore works for single-process deployments. Implement ISessionStore for Redis, PostgreSQL, etc:

import type { ISessionStore, VerificationSession } from "@openeudi/core";

class RedisSessionStore implements ISessionStore {
    constructor(private redis: Redis) {}

    async get(id: string): Promise<VerificationSession | null> {
        const data = await this.redis.get(`session:${id}`);
        return data ? JSON.parse(data) : null;
    }
    async set(session: VerificationSession): Promise<void> {
        const ttl = Math.max(0, session.expiresAt.getTime() - Date.now());
        await this.redis.set(`session:${session.id}`, JSON.stringify(session), "PX", ttl);
    }
    async delete(id: string): Promise<void> {
        await this.redis.del(`session:${id}`);
    }
}

const service = new VerificationService({
    mode: new DemoMode(),
    store: new RedisSessionStore(new Redis()),
});

Discriminated Union Types

VerificationSession is a discriminated union. Narrow by session.status to access phase-specific fields:

import {
    VerificationStatus,
    type VerificationSession,
    type PendingSession,
    type CompletedSession,
    type ExpiredSession,
} from "@openeudi/core";

function inspect(session: VerificationSession) {
    switch (session.status) {
        case VerificationStatus.PENDING:
            // session is PendingSession here
            console.log("Waiting for wallet, url:", session.walletUrl);
            break;

        case VerificationStatus.VERIFIED:
        case VerificationStatus.REJECTED:
            // session is CompletedSession here
            // .result and .completedAt are available
            console.log("Result:", session.result, "at:", session.completedAt);
            break;

        case VerificationStatus.EXPIRED:
            // session is ExpiredSession here
            console.log("Expired at:", session.completedAt);
            break;
    }
}

Fields by type:

Field	BaseSession	PendingSession	CompletedSession	ExpiredSession
id, type, status, walletUrl, createdAt, expiresAt	yes	yes	yes	yes
result, completedAt	-	-	yes	yes

Events

VerificationService extends EventEmitter with fully typed events. Listener argument types are inferred from the event name -- no casting needed.

Event	Handler Signature	Description
session:created	(session: PendingSession) => void	Session created, wallet URL ready
session:verified	(session: CompletedSession, result: VerificationResult) => void	Verification passed
session:rejected	(session: CompletedSession, reason: string) => void	Verification rejected
session:expired	(session: ExpiredSession) => void	Session TTL exceeded
session:cancelled	(session: PendingSession) => void	Session cancelled by caller
error	(err: Error, sessionId?: string) => void	Background simulation error

service.on("session:created", (session) =>
    sendSSE(session.id, { walletUrl: session.walletUrl })
);
service.on("session:verified", (session, result) =>
    sendSSE(session.id, { status: "verified", country: result.country })
);
service.on("session:rejected", (session, reason) =>
    sendSSE(session.id, { status: "rejected", reason })
);
service.on("session:expired", (session) =>
    sendSSE(session.id, { status: "expired" })
);
service.on("session:cancelled", (session) =>
    sendSSE(session.id, { status: "cancelled" })
);
service.on("error", (err, sessionId) =>
    console.error("Service error:", err.message, sessionId)
);

Input Validation

createSession() validates inputs and throws synchronously on bad data:

• countryWhitelist and countryBlacklist are mutually exclusive
• All country codes must be valid ISO 3166-1 alpha-2 (e.g. "DE", "FR")
• isValidCountryCode(code) is exported for use in your own validation layer

import { isValidCountryCode } from "@openeudi/core";

isValidCountryCode("DE"); // true
isValidCountryCode("XX"); // false
isValidCountryCode("deu"); // false (must be 2 uppercase letters)

Constructor config is also validated:

• sessionTtlMs must be a positive integer
• walletBaseUrl must be a non-empty string

Service Lifecycle

const service = new VerificationService({ mode: new DemoMode() });

// ... normal usage ...

// Teardown: removes all listeners, clears session tracking, prevents future calls
service.destroy();

// All calls after destroy() throw ServiceDestroyedError
await service.createSession({ type: VerificationType.AGE }); // throws

Use destroy() in server shutdown handlers to prevent memory leaks when hot-reloading.

QR Code

Optional helper to generate QR code data URIs. Requires the qrcode peer dependency:

npm install qrcode

import { generateQRCode } from "@openeudi/core/qr";

const session = await service.createSession({ type: VerificationType.AGE });
const dataUri = await generateQRCode(session.walletUrl);
// => "data:image/png;base64,..."

API Reference

VerificationService

Method	Returns	Description
constructor(config)	VerificationService	Create service with mode, optional store, TTL, and wallet URL
createSession(input)	Promise<PendingSession>	Create a new verification session
getSession(id)	Promise<VerificationSession>	Retrieve session by ID (throws SessionNotFoundError)
handleCallback(sessionId, walletResponse)	Promise<VerificationResult>	Process wallet callback (throws SessionNotFoundError, SessionExpiredError)
cancelSession(id)	Promise<void>	Cancel a pending session (throws SessionNotPendingError if not pending)
cleanupExpired()	Promise<number>	Remove expired sessions, returns count cleaned
destroy()	void	Permanently destroy the service and prevent further use

Configuration

interface VerificationServiceConfig {
    mode: IVerificationMode; // Required -- DemoMode, MockMode, or custom
    store?: ISessionStore;   // Default: InMemorySessionStore
    sessionTtlMs?: number;   // Default: 300_000 (5 minutes)
    walletBaseUrl?: string;  // Default: 'openid4vp://verify'
}

Error Classes

Class	Thrown by	Description
SessionNotFoundError	getSession, handleCallback, cancelSession	No session with the given ID
SessionExpiredError	handleCallback	Session TTL has elapsed
SessionNotPendingError	cancelSession	Session is not in PENDING status
ServiceDestroyedError	All public methods	Service has been destroyed

Types

All types are exported from the main entry point:

import type {
    VerificationSession,    // Discriminated union (Pending | Completed | Expired)
    BaseSession,            // Common fields shared by all session states
    PendingSession,         // Status: PENDING
    CompletedSession,       // Status: VERIFIED or REJECTED (.result, .completedAt present)
    ExpiredSession,         // Status: EXPIRED (.completedAt present)
    VerificationResult,     // Outcome of a verification
    CreateSessionInput,     // Input for createSession()
    VerificationServiceConfig, // Constructor config
    VerificationEvents,     // Event map for typed EventEmitter
    IVerificationMode,      // Strategy interface for modes
    ISessionStore,          // Storage adapter interface
    DemoModeConfig,         // DemoMode constructor options
    MockModeConfig,         // MockMode constructor options
} from "@openeudi/core";

import {
    VerificationType,       // AGE | COUNTRY | BOTH
    VerificationStatus,     // PENDING | VERIFIED | REJECTED | EXPIRED
    SessionNotFoundError,
    SessionExpiredError,
    SessionNotPendingError,
    ServiceDestroyedError,
    isValidCountryCode,
    VERSION,                // '0.2.0'
} from "@openeudi/core";

Migration from v0.1.x

Discriminated union sessions

session.result and session.completedAt no longer exist on all sessions. Narrow by session.status:

// Before (v0.1.x)
if (session.result?.verified) { ... }

// After (v0.2.0)
if (session.status === VerificationStatus.VERIFIED) {
    // session.result is available here (TypeScript knows this)
    console.log(session.result.country);
}

VerificationStatus.SCANNED removed

Remove any handling for VerificationStatus.SCANNED -- it no longer exists.

IVerificationMode.processCallback signature

Custom modes must accept BaseSession instead of VerificationSession:

// Before
async processCallback(session: VerificationSession, ...): Promise<VerificationResult>

// After
async processCallback(session: BaseSession, ...): Promise<VerificationResult>

createSession return type

createSession() now returns Promise<PendingSession>. This is a narrowing of the previous Promise<VerificationSession> and is backward-compatible in most cases, but update type annotations accordingly.

New required error handling

Listen for the error event to handle DemoMode simulation failures:

service.on("error", (err, sessionId) => {
    console.error("Simulation failed:", err.message);
});

License

Apache 2.0

Related

eIDAS Pro -- managed verification service with WooCommerce/Shopify plugins, admin dashboard, and compliance tools built on @openeudi/core.