@openeudi/core 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -12,7 +12,6 @@ var VerificationType = /* @__PURE__ */ ((VerificationType2) => {
 })(VerificationType || {});
 var VerificationStatus = /* @__PURE__ */ ((VerificationStatus2) => {
   VerificationStatus2["PENDING"] = "PENDING";
-  VerificationStatus2["SCANNED"] = "SCANNED";
   VerificationStatus2["VERIFIED"] = "VERIFIED";
   VerificationStatus2["REJECTED"] = "REJECTED";
   VerificationStatus2["EXPIRED"] = "EXPIRED";
@@ -34,6 +33,26 @@ var SessionExpiredError = class extends Error {
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
+var SessionNotPendingError = class extends Error {
+  /** The session ID that was not in PENDING status */
+  sessionId;
+  /** The status the session was actually in */
+  currentStatus;
+  constructor(sessionId, currentStatus) {
+    super(`Session ${sessionId} is not pending (current status: ${currentStatus})`);
+    this.name = "SessionNotPendingError";
+    this.sessionId = sessionId;
+    this.currentStatus = currentStatus;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var ServiceDestroyedError = class extends Error {
+  constructor() {
+    super("VerificationService has been destroyed and cannot accept new operations");
+    this.name = "ServiceDestroyedError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
 
 // src/storage/memory.store.ts
 var InMemorySessionStore = class {
@@ -143,6 +162,299 @@ var MockMode = class {
     return this.processCallback(session, {});
   }
 };
+
+// src/validation.ts
+var ISO_3166_1_ALPHA2 = /* @__PURE__ */ new Set([
+  "AF",
+  "AX",
+  "AL",
+  "DZ",
+  "AS",
+  "AD",
+  "AO",
+  "AI",
+  "AQ",
+  "AG",
+  "AR",
+  "AM",
+  "AW",
+  "AU",
+  "AT",
+  "AZ",
+  "BS",
+  "BH",
+  "BD",
+  "BB",
+  "BY",
+  "BE",
+  "BZ",
+  "BJ",
+  "BM",
+  "BT",
+  "BO",
+  "BQ",
+  "BA",
+  "BW",
+  "BV",
+  "BR",
+  "IO",
+  "BN",
+  "BG",
+  "BF",
+  "BI",
+  "CV",
+  "KH",
+  "CM",
+  "CA",
+  "KY",
+  "CF",
+  "TD",
+  "CL",
+  "CN",
+  "CX",
+  "CC",
+  "CO",
+  "KM",
+  "CG",
+  "CD",
+  "CK",
+  "CR",
+  "CI",
+  "HR",
+  "CU",
+  "CW",
+  "CY",
+  "CZ",
+  "DK",
+  "DJ",
+  "DM",
+  "DO",
+  "EC",
+  "EG",
+  "SV",
+  "GQ",
+  "ER",
+  "EE",
+  "SZ",
+  "ET",
+  "FK",
+  "FO",
+  "FJ",
+  "FI",
+  "FR",
+  "GF",
+  "PF",
+  "TF",
+  "GA",
+  "GM",
+  "GE",
+  "DE",
+  "GH",
+  "GI",
+  "GR",
+  "GL",
+  "GD",
+  "GP",
+  "GU",
+  "GT",
+  "GG",
+  "GN",
+  "GW",
+  "GY",
+  "HT",
+  "HM",
+  "VA",
+  "HN",
+  "HK",
+  "HU",
+  "IS",
+  "IN",
+  "ID",
+  "IR",
+  "IQ",
+  "IE",
+  "IM",
+  "IL",
+  "IT",
+  "JM",
+  "JP",
+  "JE",
+  "JO",
+  "KZ",
+  "KE",
+  "KI",
+  "KP",
+  "KR",
+  "KW",
+  "KG",
+  "LA",
+  "LV",
+  "LB",
+  "LS",
+  "LR",
+  "LY",
+  "LI",
+  "LT",
+  "LU",
+  "MO",
+  "MG",
+  "MW",
+  "MY",
+  "MV",
+  "ML",
+  "MT",
+  "MH",
+  "MQ",
+  "MR",
+  "MU",
+  "YT",
+  "MX",
+  "FM",
+  "MD",
+  "MC",
+  "MN",
+  "ME",
+  "MS",
+  "MA",
+  "MZ",
+  "MM",
+  "NA",
+  "NR",
+  "NP",
+  "NL",
+  "NC",
+  "NZ",
+  "NI",
+  "NE",
+  "NG",
+  "NU",
+  "NF",
+  "MK",
+  "MP",
+  "NO",
+  "OM",
+  "PK",
+  "PW",
+  "PS",
+  "PA",
+  "PG",
+  "PY",
+  "PE",
+  "PH",
+  "PN",
+  "PL",
+  "PT",
+  "PR",
+  "QA",
+  "RE",
+  "RO",
+  "RU",
+  "RW",
+  "BL",
+  "SH",
+  "KN",
+  "LC",
+  "MF",
+  "PM",
+  "VC",
+  "WS",
+  "SM",
+  "ST",
+  "SA",
+  "SN",
+  "RS",
+  "SC",
+  "SL",
+  "SG",
+  "SX",
+  "SK",
+  "SI",
+  "SB",
+  "SO",
+  "ZA",
+  "GS",
+  "SS",
+  "ES",
+  "LK",
+  "SD",
+  "SR",
+  "SJ",
+  "SE",
+  "CH",
+  "SY",
+  "TW",
+  "TJ",
+  "TZ",
+  "TH",
+  "TL",
+  "TG",
+  "TK",
+  "TO",
+  "TT",
+  "TN",
+  "TR",
+  "TM",
+  "TC",
+  "TV",
+  "UG",
+  "UA",
+  "AE",
+  "GB",
+  "US",
+  "UM",
+  "UY",
+  "UZ",
+  "VU",
+  "VE",
+  "VN",
+  "VG",
+  "VI",
+  "WF",
+  "EH",
+  "YE",
+  "ZM",
+  "ZW"
+]);
+function isValidCountryCode(code) {
+  return ISO_3166_1_ALPHA2.has(code);
+}
+function validateConfig(config) {
+  if (config.sessionTtlMs !== void 0) {
+    if (config.sessionTtlMs <= 0) {
+      throw new Error(
+        `sessionTtlMs must be a positive number, received: ${config.sessionTtlMs}`
+      );
+    }
+  }
+  if (config.walletBaseUrl !== void 0) {
+    if (config.walletBaseUrl.trim().length === 0) {
+      throw new Error("walletBaseUrl must be a non-empty string");
+    }
+  }
+}
+function validateSessionInput(input) {
+  if (input.countryWhitelist !== void 0 && input.countryBlacklist !== void 0) {
+    throw new Error(
+      "countryWhitelist and countryBlacklist cannot both be provided; use one or the other"
+    );
+  }
+  if (input.countryWhitelist !== void 0) {
+    const invalid = input.countryWhitelist.filter((code) => !isValidCountryCode(code));
+    if (invalid.length > 0) {
+      throw new Error(
+        `countryWhitelist contains invalid ISO 3166-1 alpha-2 codes: ${invalid.join(", ")}`
+      );
+    }
+  }
+  if (input.countryBlacklist !== void 0) {
+    const invalid = input.countryBlacklist.filter((code) => !isValidCountryCode(code));
+    if (invalid.length > 0) {
+      throw new Error(
+        `countryBlacklist contains invalid ISO 3166-1 alpha-2 codes: ${invalid.join(", ")}`
+      );
+    }
+  }
+}
 var DEFAULT_TTL_MS = 3e5;
 var DEFAULT_WALLET_BASE_URL = "openid4vp://verify";
 var VerificationService = class extends events.EventEmitter {
@@ -152,25 +464,110 @@ var VerificationService = class extends events.EventEmitter {
   walletBaseUrl;
   /** Track session IDs for cleanup (store interface has no list method) */
   sessionIds = /* @__PURE__ */ new Set();
+  /** Whether {@link destroy} has been called */
+  destroyed = false;
+  /**
+   * 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) {
     super();
+    validateConfig(config);
     this.mode = config.mode;
     this.store = config.store ?? new InMemorySessionStore();
     this.sessionTtlMs = config.sessionTtlMs ?? DEFAULT_TTL_MS;
     this.walletBaseUrl = config.walletBaseUrl ?? DEFAULT_WALLET_BASE_URL;
   }
+  // -----------------------------------------------------------------------
+  // Typed EventEmitter overrides
+  // -----------------------------------------------------------------------
+  /**
+   * 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(event, listener) {
+    return super.on(event, listener);
+  }
+  /**
+   * 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)
+   */
+  once(event, listener) {
+    return super.once(event, listener);
+  }
+  /**
+   * 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(event, listener) {
+    return super.off(event, listener);
+  }
+  /**
+   * 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(event, ...args) {
+    return super.emit(event, ...args);
+  }
+  // -----------------------------------------------------------------------
+  // Public API
+  // -----------------------------------------------------------------------
   /**
-   * Create a new verification session
+   * 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=...'
+   * ```
    */
   async createSession(input) {
+    this.assertNotDestroyed();
+    validateSessionInput(input);
     const id = uuid.v4();
     const now = /* @__PURE__ */ new Date();
+    const walletUrl = this.mode.buildWalletUrl ? await this.mode.buildWalletUrl(id, input) : `${this.walletBaseUrl}?session=${id}`;
     const session = {
       id,
       type: input.type,
       status: "PENDING" /* PENDING */,
-      walletUrl: "",
-      // set below, may be async from mode
+      walletUrl,
       countryWhitelist: input.countryWhitelist,
       countryBlacklist: input.countryBlacklist,
       redirectUrl: input.redirectUrl,
@@ -178,7 +575,6 @@ var VerificationService = class extends events.EventEmitter {
       createdAt: now,
       expiresAt: new Date(now.getTime() + this.sessionTtlMs)
     };
-    session.walletUrl = this.mode.buildWalletUrl ? await this.mode.buildWalletUrl(id, input) : `${this.walletBaseUrl}?session=${id}`;
     await this.store.set(session);
     this.sessionIds.add(id);
     this.emit("session:created", session);
@@ -188,16 +584,30 @@ var VerificationService = class extends events.EventEmitter {
         if (current && current.status === "PENDING" /* PENDING */) {
           await this.completeSession(current, result);
         }
-      }).catch(() => {
+      }).catch((error) => {
+        this.emit("error", error instanceof Error ? error : new Error(String(error)), id);
       });
     }
     return session;
   }
   /**
-   * Get a session by ID
-   * @throws SessionNotFoundError
+   * 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);
+   * }
+   * ```
    */
   async getSession(id) {
+    this.assertNotDestroyed();
     const session = await this.store.get(id);
     if (!session) {
       throw new SessionNotFoundError(id);
@@ -205,11 +615,30 @@ var VerificationService = class extends events.EventEmitter {
     return session;
   }
   /**
-   * 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);
+   * }
+   * ```
    */
   async handleCallback(sessionId, walletResponse) {
+    this.assertNotDestroyed();
     const session = await this.store.get(sessionId);
     if (!session) {
       throw new SessionNotFoundError(sessionId);
@@ -222,10 +651,55 @@ var VerificationService = class extends events.EventEmitter {
     return result;
   }
   /**
-   * 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
+   * ```
+   */
+  async cancelSession(id) {
+    this.assertNotDestroyed();
+    const session = await this.store.get(id);
+    if (!session) {
+      throw new SessionNotFoundError(id);
+    }
+    if (session.status !== "PENDING" /* PENDING */) {
+      throw new SessionNotPendingError(id, session.status);
+    }
+    await this.store.delete(id);
+    this.sessionIds.delete(id);
+    this.emit("session:cancelled", session);
+  }
+  /**
+   * 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`);
+   * ```
    */
   async cleanupExpired() {
+    this.assertNotDestroyed();
     const now = /* @__PURE__ */ new Date();
     let count = 0;
     for (const id of this.sessionIds) {
@@ -235,7 +709,11 @@ var VerificationService = class extends events.EventEmitter {
         continue;
       }
       if (now > session.expiresAt && session.status === "PENDING" /* PENDING */) {
-        const expired = { ...session, status: "EXPIRED" /* EXPIRED */ };
+        const expired = {
+          ...session,
+          status: "EXPIRED" /* EXPIRED */,
+          completedAt: now
+        };
         await this.store.set(expired);
         await this.store.delete(id);
         this.sessionIds.delete(id);
@@ -245,6 +723,40 @@ var VerificationService = class extends events.EventEmitter {
     }
     return count;
   }
+  /**
+   * 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() {
+    this.removeAllListeners();
+    this.sessionIds.clear();
+    this.destroyed = true;
+  }
+  // -----------------------------------------------------------------------
+  // Private helpers
+  // -----------------------------------------------------------------------
+  /**
+   * Guard that throws if the service has been destroyed.
+   * Called at the top of every public method.
+   */
+  assertNotDestroyed() {
+    if (this.destroyed) {
+      throw new ServiceDestroyedError();
+    }
+  }
+  /**
+   * Transition a session to VERIFIED or REJECTED and emit the appropriate event.
+   */
   async completeSession(session, result) {
     const status = result.verified ? "VERIFIED" /* VERIFIED */ : "REJECTED" /* REJECTED */;
     const updated = {
@@ -254,25 +766,29 @@ var VerificationService = class extends events.EventEmitter {
       result
     };
     await this.store.set(updated);
+    this.sessionIds.delete(session.id);
     if (result.verified) {
       this.emit("session:verified", updated, result);
     } else {
-      this.emit("session:rejected", updated, result.rejectionReason);
+      this.emit("session:rejected", updated, result.rejectionReason ?? "");
     }
   }
 };
 
 // src/index.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.0";
 
 exports.DemoMode = DemoMode;
 exports.InMemorySessionStore = InMemorySessionStore;
 exports.MockMode = MockMode;
+exports.ServiceDestroyedError = ServiceDestroyedError;
 exports.SessionExpiredError = SessionExpiredError;
 exports.SessionNotFoundError = SessionNotFoundError;
+exports.SessionNotPendingError = SessionNotPendingError;
 exports.VERSION = VERSION;
 exports.VerificationService = VerificationService;
 exports.VerificationStatus = VerificationStatus;
 exports.VerificationType = VerificationType;
+exports.isValidCountryCode = isValidCountryCode;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map