@ism/verify-sdk 1.0.116 → 1.1.118

package/README.md

@@ -30,7 +30,7 @@ npm install @ism/verify-sdk
 | `clientId` | `cl_…` |
 | `clientSecret` | `sk_…` — shown once, when the client is created. Keep it in your secret store |
 | A bundle | `bn_…` — what you ask for, at which assurance level, and the purpose the person reads |
-| A redirect URI | where the person returns after the app. It must match one registered on your client exactly |
+| A redirect URI | where the person returns after the app. It must match one registered on your client exactly. Every new client starts with `https://id.ism.ec/listo`, a page that tells the person they are done, so you can start before your own page exists |
 | A webhook (recommended) | so you learn the outcome even when the person does not come back |
 
 Sandbox clients behave exactly like production ones, with the same API and the same app.
@@ -76,7 +76,25 @@ await ism.start({ claims: ['subject_is:EC-ID-0000000000'], level: 'L4', purpose:
 ```
 
 A link is valid for a few minutes before the person first opens it; `expiresAt` says until when.
-Each `start()` call starts a new verification.
+
+### Retrying safely
+
+Each `start()` call starts a new verification. To make a retry safe — after a timeout, or from a
+job runner that may run twice — pass an `idempotencyKey`, such as your own record's id:
+
+```js
+const { req, verifyUrl, replayed } = await ism.start({
+  bundle: 'bn_…',
+  redirectUri,
+  state,
+  idempotencyKey: `onboarding-${application.id}`,
+});
+```
+
+The same key with the same request, while its link is still valid, returns the verification the
+first call started (`replayed: true`) instead of a second one. Once the link has expired the key
+starts a new one. Reusing a key for a *different* request fails with `idempotency_conflict`. Keys
+are scoped to your client and stored only as a hash.
 
 ## 2 · Collect the result
 
@@ -147,20 +165,21 @@ Every failed call throws a `VerifyError` with `status` (HTTP, or 0 when nothing
 | `invalid_client` | the client id or secret was refused |
 | `not_entitled` | the request asks for more than your client may — a claim, a level, a redirect URI. The message says which |
 | `invalid_request` | a malformed request; on `/token`, also a code or reference that is unknown, expired or already released — deliberately indistinguishable |
+| `idempotency_conflict` | the `idempotencyKey` was already used for a different request |
 | `client_suspended` | the client is not active |
 | `rate_limited` | slow down |
 | `timeout`, `network_error` | no answer arrived. **Do not retry `exchange` or `fetchResult` blindly**: the result may already have been released to the lost response |
 | `invalid_signature` | `verifyWebhook` refused the body |
 | `state_mismatch` | `handleReturn` was given a URL whose `state` is not yours |
 
-No call is retried by the SDK.
+No call is retried by the SDK; `idempotencyKey` is what makes your own retry of `start()` safe.
 
 ## Reference
 
 | | |
 |---|---|
 | `new Verify({ clientId, clientSecret, baseUrl?, timeoutMs?, fetch? })` | `baseUrl` defaults to `https://api.ism.ec/verify/v1`; `timeoutMs` to 10 000 |
-| `start({ bundle \| claims, level, purpose, retention?, claimLabels?, redirectUri, state?, network?, endUserIp? })` | → `{ req, verifyUrl, expiresAt }` |
+| `start({ bundle \| claims, level, purpose, retention?, claimLabels?, redirectUri, state?, network?, endUserIp?, idempotencyKey? })` | → `{ req, verifyUrl, expiresAt, replayed }` |
 | `exchange(code)` | → result |
 | `fetchResult(req)` | → result |
 | `handleReturn(url, { expectedState? })` | → `{ ok: true, result }` or `{ ok: false, error, outcome, state }` |

package/index.d.ts

@@ -6,7 +6,7 @@ export type Outcome = 'completed' | 'denied' | 'failed' | 'abandoned';
 export declare class VerifyError extends Error {
 	/** HTTP status, or 0 when no response arrived. */
 	readonly status: number;
-	/** invalid_client, invalid_request, not_entitled, client_suspended, rate_limited, timeout, network_error, invalid_signature, state_mismatch, … */
+	/** invalid_client, invalid_request, not_entitled, idempotency_conflict, client_suspended, rate_limited, timeout, network_error, invalid_signature, state_mismatch, … */
 	readonly code: string;
 }
 
@@ -29,6 +29,12 @@ interface StartCommon {
 	network?: boolean;
 	/** The person's IP as your backend saw it, for network signals. */
 	endUserIp?: string;
+	/**
+	 * Makes a retried start safe: the same key with the same request, while its link is still
+	 * valid, returns the first verification instead of starting a second. Use your own record's
+	 * id. 8–255 printable ASCII characters, no spaces.
+	 */
+	idempotencyKey?: string;
 	/** Where the document evidence comes from. Default: the document's chip. */
 	evidence?: { source: 'chip' };
 }
@@ -54,6 +60,8 @@ export interface Started {
 	/** Send the person here. */
 	verifyUrl: string;
 	expiresAt: string;
+	/** true when an idempotencyKey matched an earlier start and this is that verification. */
+	replayed: boolean;
 }
 
 export interface VerificationResult {

package/index.js

@@ -8,15 +8,17 @@
 // - The client secret travels only in the Authorization header of `/par` and `/token`, never in
 //   a body, a URL, an error or a log line. It lives in a private field, so printing the client
 //   does not print it.
-// - No call is retried. `/par` mints a new verification on every call, and `/token` releases a
-//   result exactly once: a retry after a lost response would find it already released.
+// - No call is retried by the SDK. `/par` mints a new verification on every call unless the
+//   caller passes `idempotencyKey`, which makes the caller's own retry safe; `/token` releases a
+//   result exactly once, so a retry after a lost response would find it already released.
 // - This file logs nothing. Claims are personal data, and logging is the caller's decision.
 
 const crypto = require('node:crypto');
 
 const DEFAULT_BASE_URL = 'https://api.ism.ec/verify/v1';
 const DEFAULT_TIMEOUT_MS = 10_000;
-const LEVELS = ['L1', 'L2', 'L3', 'L4'];
+const LEVEL = /^L[0-9]$/;
+const IDEMPOTENCY_KEY = /^[\x21-\x7e]{8,255}$/;
 const EVIDENCE_SOURCES = ['chip'];
 
 class VerifyError extends Error {
@@ -93,7 +95,7 @@ class Verify {
 	toJSON() { return { clientId: this.#clientId, baseUrl: this.#baseUrl }; }
 	[Symbol.for('nodejs.util.inspect.custom')]() { return `Verify { clientId: '${this.#clientId}', baseUrl: '${this.#baseUrl}' }`; }
 
-	async #post(path, body) {
+	async #post(path, body, { withHeaders = false } = {}) {
 		let response;
 		try {
 			response = await this.#fetch(`${this.#baseUrl}${path}`, {
@@ -124,21 +126,23 @@ class Verify {
 		if (!parsed || typeof parsed !== 'object') {
 			throw new VerifyError(`${path} answered with a body that is not JSON.`, { status: response.status, code: 'invalid_response' });
 		}
-		return parsed;
+		return withHeaders ? { body: parsed, headers: response.headers } : parsed;
 	}
 
 	/**
 	 * Starts a verification. Send the person to `verifyUrl`; keep `req` beside your own record.
 	 *
 	 * Name a bundle configured in the console (`bundle`), or compose the request here (`claims`,
-	 * `level`, `purpose`). Each call starts a new verification.
+	 * `level`, `purpose`). Each call starts a new verification — unless it carries an
+	 * `idempotencyKey` already used for the same request while its link is still valid, which
+	 * answers with that first verification instead (`replayed: true`).
 	 *
-	 * @returns {Promise<{ req: string, verifyUrl: string, expiresAt: string }>}
+	 * @returns {Promise<{ req: string, verifyUrl: string, expiresAt: string, replayed: boolean }>}
 	 */
 	async start(options = {}) {
 		const {
 			bundle, claims, level, purpose, retention, claimLabels,
-			redirectUri, state, network, endUserIp, evidence
+			redirectUri, state, network, endUserIp, evidence, idempotencyKey
 		} = options;
 
 		const source = evidence === undefined ? 'chip' : evidence && evidence.source;
@@ -159,7 +163,7 @@ class Verify {
 			if (!Array.isArray(claims) || claims.length === 0 || !claims.every((c) => typeof c === 'string' && c)) {
 				throw new TypeError('claims must be a non-empty array of claim names, or pass bundle.');
 			}
-			if (!LEVELS.includes(level)) throw new TypeError(`level must be one of: ${LEVELS.join(', ')}.`);
+			if (typeof level !== 'string' || !LEVEL.test(level)) throw new TypeError('level must be an assurance level such as L1 or L4.');
 			requireString(purpose, 'purpose');
 			body.claims = claims;
 			body.level = level;
@@ -173,12 +177,23 @@ class Verify {
 			body.network = network;
 		}
 		if (endUserIp !== undefined && endUserIp !== null) body.end_user_ip = requireString(endUserIp, 'endUserIp');
+		if (idempotencyKey !== undefined && idempotencyKey !== null) {
+			if (typeof idempotencyKey !== 'string' || !IDEMPOTENCY_KEY.test(idempotencyKey)) {
+				throw new TypeError('idempotencyKey must be 8–255 printable ASCII characters, with no spaces.');
+			}
+			body.idempotency_key = idempotencyKey;
+		}
 
-		const answer = await this.#post('/par', body);
+		const { body: answer, headers } = await this.#post('/par', body, { withHeaders: true });
 		if (typeof answer.req !== 'string' || typeof answer.verify_url !== 'string') {
 			throw new VerifyError('/par answered without req and verify_url.', { status: 200, code: 'invalid_response' });
 		}
-		return { req: answer.req, verifyUrl: answer.verify_url, expiresAt: answer.expires_at };
+		return {
+			req: answer.req,
+			verifyUrl: answer.verify_url,
+			expiresAt: answer.expires_at,
+			replayed: Boolean(headers && typeof headers.get === 'function' && headers.get('idempotent-replayed') === 'true')
+		};
 	}
 
 	/**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ism/verify-sdk",
-  "version": "1.0.116",
+  "version": "1.1.118",
   "description": "Verify with ISM for relying-party backends: start a verification, collect the result, check webhook signatures.",
   "main": "index.js",
   "scripts": {
@@ -30,5 +30,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "20cf21925ff3f8d038c5063b6cc2547977b8f6fc"
+  "gitHead": "44d2fc4511c4e4fd3a685616fc74ed2bafa0b69f"
 }