@ism/verify-sdk 0.0.0-stage → 1.1.118

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ISM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,198 @@
-# Temporary Holding Version
+# @ism/verify-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Verify with ISM** for your backend. Ask a person to prove something about themselves — that
+they are over 18, that they hold a given cédula or passport, which country issued their document —
+and receive only the answer, read from the document's own chip by the ID Protekt app and recorded
+with a consent receipt.
+
+Your backend makes two calls. The person does the rest on their phone.
+
+```
+your backend ── start() ──▶ api.ism.ec ──▶ verifyUrl ──▶ the person, in ID Protekt
+     ▲                                                          │
+     └──── exchange(code) / fetchResult(req) ◀── redirect or webhook ◀┘
+```
+
+- Node.js 18 or later. No dependencies. CommonJS and ES modules. Types included.
+- Your client secret stays on your server. It is sent only in the `Authorization` header of the
+  two calls, and never logged.
+
+## Install
+
+```sh
+npm install @ism/verify-sdk
+```
+
+## What you need from the console
+
+| | |
+|---|---|
+| `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. 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.
+
+## 1 · Start a verification
+
+```js
+import { randomUUID } from 'node:crypto';
+import { Verify } from '@ism/verify-sdk';
+
+const ism = new Verify({
+  clientId: process.env.ISM_VERIFY_CLIENT_ID,
+  clientSecret: process.env.ISM_VERIFY_CLIENT_SECRET,
+});
+
+const state = randomUUID();          // store it with your own record
+const { req, verifyUrl, expiresAt } = await ism.start({
+  bundle: 'bn_…',
+  redirectUri: 'https://your-site.example/verify/return',
+  state,
+});
+// Send the person to verifyUrl: a redirect, a link in a message, or a QR code on a desktop page.
+```
+
+Instead of a bundle you can compose the request in code, within what your client is entitled to:
+
+```js
+await ism.start({
+  claims: ['age_over_18'],
+  level: 'L1',
+  purpose: 'Confirm you are of legal age',
+  redirectUri: 'https://your-site.example/verify/return',
+  state,
+});
+```
+
+To confirm that the person holds a specific document, ask for `subject_is` with the document's
+qualified reference — `EC-ID-<cédula>` for an Ecuadorian cédula, `<country>-P-<number>` for a
+passport. It releases one boolean and nothing else:
+
+```js
+await ism.start({ claims: ['subject_is:EC-ID-0000000000'], level: 'L4', purpose: '…', redirectUri, state });
+```
+
+A link is valid for a few minutes before the person first opens it; `expiresAt` says until when.
+
+### 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
+
+**When the person comes back** to your `redirectUri`:
+
+```js
+app.get('/verify/return', async (request, response) => {
+  const back = await ism.handleReturn(new URL(request.url, 'https://your-site.example'), {
+    expectedState: storedState,               // the state you passed to start()
+  });
+  if (!back.ok) {
+    // back.outcome: 'denied' (the person declined), 'failed' or 'abandoned'
+    return response.send('The verification was not completed.');
+  }
+  const { claims, consentReceiptId } = back.result;
+  // claims → { age_over_18: true }
+});
+```
+
+**When the person finishes in the app and does not come back**, your webhook receives
+`verification.completed`; fetch the result by the `req` from `start()`:
+
+```js
+import { verifyWebhook } from '@ism/verify-sdk';
+
+app.post('/verify/webhook', express.raw({ type: 'application/json' }), async (request, response) => {
+  const event = verifyWebhook({
+    rawBody: request.body,                    // the raw bytes, never a re-serialised object
+    signature: request.get('ISM-Signature'),
+    secret: process.env.ISM_VERIFY_WEBHOOK_SECRET,   // whsec_…, not the client secret
+  });
+  response.sendStatus(200);                   // answer within 10 seconds, then do the work
+  if (event.type === 'verification.completed') {
+    const result = await ism.fetchResult(event.data.req);
+  }
+});
+```
+
+Webhooks carry no personal data — only the outcome, your `state` and the `req`. De-duplicate on
+`event.id`: retries and replays keep it.
+
+### The result
+
+```js
+{
+  req: 'Xk2…',                     // the reference start() returned
+  claims: { age_over_18: true },   // only what you asked for
+  assurance: 'L1',
+  verifiedBy: 'device',            // or 'server'
+  deviceAttestation: 'verified',   // a genuine ID Protekt app on genuine hardware
+  verifiedAt: '2026-10-29T15:04:05.000Z',
+  consentReceiptId: 'rc_…',        // the person's consent, on record
+  state: '…',                      // yours, echoed back
+}
+```
+
+🔴 **A result is released once.** Whichever of `exchange(code)`, `handleReturn()` and
+`fetchResult(req)` asks first receives it; every later request is refused. It is kept for 24 hours
+after the person finishes. Store what you need from it when it arrives.
+
+## Errors
+
+Every failed call throws a `VerifyError` with `status` (HTTP, or 0 when nothing came back) and
+`code`:
+
+| `code` | Meaning |
+|---|---|
+| `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; `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?, idempotencyKey? })` | → `{ req, verifyUrl, expiresAt, replayed }` |
+| `exchange(code)` | → result |
+| `fetchResult(req)` | → result |
+| `handleReturn(url, { expectedState? })` | → `{ ok: true, result }` or `{ ok: false, error, outcome, state }` |
+| `Verify.parseReturn(url)` | reads a return URL without calling anything |
+| `verifyWebhook({ rawBody, signature, secret, toleranceSeconds?, now? })` | → the event, or throws |
+
+`network` and `endUserIp` apply to clients with network signals: pass the IP your backend saw the
+person's browser connect from, and the result reports where each step of the verification
+connected from.
+
+The API underneath is plain HTTPS and JSON — `POST /par` and `POST /token`, authenticated with
+HTTP Basic — so any language can integrate without this package.
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,117 @@
+export declare const DEFAULT_BASE_URL: string;
+
+export type AssuranceLevel = 'L1' | 'L2' | 'L3' | 'L4';
+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, idempotency_conflict, client_suspended, rate_limited, timeout, network_error, invalid_signature, state_mismatch, … */
+	readonly code: string;
+}
+
+export interface VerifyOptions {
+	clientId: string;
+	clientSecret: string;
+	/** Defaults to https://api.ism.ec/verify/v1 */
+	baseUrl?: string;
+	/** Per call. Default 10 000. */
+	timeoutMs?: number;
+	fetch?: typeof fetch;
+}
+
+interface StartCommon {
+	/** Exactly one of the URLs registered on your client. */
+	redirectUri: string;
+	/** Your own value, returned on the redirect, on the result and on webhooks. */
+	state?: string;
+	/** Network signals, for a client with that add-on. */
+	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' };
+}
+
+export interface StartWithBundle extends StartCommon {
+	/** A bundle id (`bn_…`) configured in the console. */
+	bundle: string;
+}
+
+export interface StartComposed extends StartCommon {
+	/** e.g. ['age_over_18'], ['subject_is:EC-ID-0000000000'] */
+	claims: string[];
+	level: AssuranceLevel;
+	/** Shown to the person and recorded on the consent receipt. */
+	purpose: string;
+	retention?: string;
+	claimLabels?: Record<string, string>;
+}
+
+export interface Started {
+	/** The verification's reference. Keep it with your record. */
+	req: string;
+	/** 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 {
+	req: string;
+	/** Only the claims you asked for: booleans for predicates, values otherwise. */
+	claims: Record<string, unknown>;
+	assurance: AssuranceLevel;
+	/** 'device' or 'server' — who computed the claims. */
+	verifiedBy: string;
+	/** 'verified' when a genuine ISM app on genuine hardware reported the result. */
+	deviceAttestation: string;
+	verifiedAt: string;
+	consentReceiptId: string;
+	state: string | null;
+	/** Present only with the network-signals add-on. */
+	network?: Record<string, unknown>;
+}
+
+export type ParsedReturn =
+	| { code: string; state: string | null; outcome: 'completed' }
+	| { code: null; error: string; outcome: Outcome; state: string | null };
+
+export type HandledReturn =
+	| { ok: true; result: VerificationResult }
+	| { ok: false; error: string; outcome: Outcome; state: string | null };
+
+export declare class Verify {
+	constructor(options: VerifyOptions);
+	readonly clientId: string;
+	start(options: StartWithBundle | StartComposed): Promise<Started>;
+	exchange(code: string): Promise<VerificationResult>;
+	fetchResult(req: string): Promise<VerificationResult>;
+	handleReturn(url: string | URL, options?: { expectedState?: string }): Promise<HandledReturn>;
+	static parseReturn(url: string | URL): ParsedReturn;
+}
+
+export interface WebhookEvent {
+	id: string;
+	type: 'verification.completed' | 'verification.denied' | 'verification.failed' | 'verification.abandoned';
+	created: string;
+	data: { client_id: string; environment: string; req: string; state: string | null; outcome: Outcome };
+}
+
+export declare function verifyWebhook(input: {
+	rawBody: string | Buffer;
+	/** The ISM-Signature header. */
+	signature: string;
+	/** The webhook's whsec_… secret. */
+	secret: string;
+	toleranceSeconds?: number;
+	/** Milliseconds. */
+	now?: number;
+}): WebhookEvent;

package/index.js

@@ -0,0 +1,285 @@
+'use strict';
+// @ism/verify-sdk — the relying-party side of Verify with ISM, for a backend.
+//
+// Two HTTP calls and a signature check: `/par` to start a verification, `/token` to collect the
+// result, and the HMAC on a webhook. Zero dependencies, Node 18+ (global fetch).
+//
+// Rules this file holds to:
+// - 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 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 LEVEL = /^L[0-9]$/;
+const IDEMPOTENCY_KEY = /^[\x21-\x7e]{8,255}$/;
+const EVIDENCE_SOURCES = ['chip'];
+
+class VerifyError extends Error {
+	/**
+	 * @param {string} message
+	 * @param {{ status?: number, code?: string }} [details]
+	 */
+	constructor(message, { status = 0, code = 'network_error' } = {}) {
+		super(message);
+		this.name = 'VerifyError';
+		/** HTTP status, or 0 when no response arrived. */
+		this.status = status;
+		/** The API's error code: invalid_client, invalid_request, not_entitled, … */
+		this.code = code;
+	}
+}
+
+const requireString = (value, name) => {
+	if (typeof value !== 'string' || value.trim() === '') {
+		throw new TypeError(`${name} is required and must be a non-empty string.`);
+	}
+	return value;
+};
+
+const basicAuth = (id, secret) =>
+	'Basic ' + Buffer.from(`${encodeURIComponent(id)}:${encodeURIComponent(secret)}`, 'utf8').toString('base64');
+
+/** The API's result, in the SDK's names. Fields the API did not send are left out. */
+const toResult = (body) => {
+	const result = {
+		req: body.req,
+		claims: body.claims || {},
+		assurance: body.assurance,
+		verifiedBy: body.verified_by,
+		deviceAttestation: body.device_attestation,
+		verifiedAt: body.verified_at,
+		consentReceiptId: body.consent_receipt_id,
+		state: body.state ?? null
+	};
+	if (body.network) result.network = body.network;
+	return result;
+};
+
+class Verify {
+	#clientId;
+	#clientSecret;
+	#baseUrl;
+	#timeoutMs;
+	#fetch;
+
+	/**
+	 * @param {object} options
+	 * @param {string} options.clientId      `cl_…`, from the console
+	 * @param {string} options.clientSecret  `sk_…`, shown once when the client was created
+	 * @param {string} [options.baseUrl]     defaults to https://api.ism.ec/verify/v1
+	 * @param {number} [options.timeoutMs]   per call, default 10 000
+	 * @param {typeof fetch} [options.fetch] an alternative fetch implementation
+	 */
+	constructor({ clientId, clientSecret, baseUrl = DEFAULT_BASE_URL, timeoutMs = DEFAULT_TIMEOUT_MS, fetch } = {}) {
+		this.#clientId = requireString(clientId, 'clientId');
+		this.#clientSecret = requireString(clientSecret, 'clientSecret');
+		const url = new URL(requireString(baseUrl, 'baseUrl'));
+		if (url.protocol !== 'https:') throw new TypeError('baseUrl must be https.');
+		this.#baseUrl = url.toString().replace(/\/+$/, '');
+		if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new TypeError('timeoutMs must be a positive number.');
+		this.#timeoutMs = timeoutMs;
+		this.#fetch = fetch || globalThis.fetch;
+		if (typeof this.#fetch !== 'function') throw new TypeError('No fetch available: use Node 18 or later, or pass options.fetch.');
+	}
+
+	get clientId() { return this.#clientId; }
+
+	/** What `console.log(client)` and `JSON.stringify(client)` show: never the secret. */
+	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, { withHeaders = false } = {}) {
+		let response;
+		try {
+			response = await this.#fetch(`${this.#baseUrl}${path}`, {
+				method: 'POST',
+				headers: {
+					'Content-Type': 'application/json',
+					Accept: 'application/json',
+					Authorization: basicAuth(this.#clientId, this.#clientSecret)
+				},
+				body: JSON.stringify(body),
+				redirect: 'error',
+				signal: AbortSignal.timeout(this.#timeoutMs)
+			});
+		} catch (err) {
+			const timedOut = err && (err.name === 'TimeoutError' || err.name === 'AbortError');
+			throw new VerifyError(timedOut ? `${path} timed out after ${this.#timeoutMs} ms.` : `${path} could not be reached: ${err && err.message}`,
+				{ status: 0, code: timedOut ? 'timeout' : 'network_error' });
+		}
+		const text = await response.text();
+		let parsed = null;
+		try { parsed = text ? JSON.parse(text) : null; } catch { /* not JSON */ }
+		if (!response.ok) {
+			throw new VerifyError(
+				(parsed && parsed.message) || `${path} answered HTTP ${response.status}.`,
+				{ status: response.status, code: (parsed && parsed.error) || 'http_error' }
+			);
+		}
+		if (!parsed || typeof parsed !== 'object') {
+			throw new VerifyError(`${path} answered with a body that is not JSON.`, { status: response.status, code: 'invalid_response' });
+		}
+		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 — 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, replayed: boolean }>}
+	 */
+	async start(options = {}) {
+		const {
+			bundle, claims, level, purpose, retention, claimLabels,
+			redirectUri, state, network, endUserIp, evidence, idempotencyKey
+		} = options;
+
+		const source = evidence === undefined ? 'chip' : evidence && evidence.source;
+		if (!EVIDENCE_SOURCES.includes(source)) {
+			throw new TypeError(`evidence.source must be one of: ${EVIDENCE_SOURCES.join(', ')}.`);
+		}
+		requireString(redirectUri, 'redirectUri');
+		if (state !== undefined && state !== null) requireString(state, 'state');
+
+		const body = { redirect_uri: redirectUri };
+		if (bundle !== undefined) {
+			requireString(bundle, 'bundle');
+			if (claims !== undefined || level !== undefined || purpose !== undefined) {
+				throw new TypeError('Pass either bundle, or claims + level + purpose — not both.');
+			}
+			body.plan_id = bundle;
+		} else {
+			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 (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;
+			body.purpose = purpose;
+			if (retention !== undefined) body.retention = requireString(retention, 'retention');
+			if (claimLabels !== undefined) body.claim_labels = claimLabels;
+		}
+		if (state !== undefined && state !== null) body.state = state;
+		if (network !== undefined) {
+			if (typeof network !== 'boolean') throw new TypeError('network must be true or false.');
+			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 { 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,
+			replayed: Boolean(headers && typeof headers.get === 'function' && headers.get('idempotent-replayed') === 'true')
+		};
+	}
+
+	/**
+	 * Exchanges the `code` from your redirect for the result. A result is released once: a
+	 * second exchange, or one after `fetchResult`, is refused.
+	 */
+	async exchange(code) {
+		requireString(code, 'code');
+		return toResult(await this.#post('/token', { grant_type: 'authorization_code', code }));
+	}
+
+	/**
+	 * Collects the result by the `req` that `start` returned — for a person who finished in the
+	 * app and never came back, typically after a `verification.completed` webhook. Kept 24 hours
+	 * after completion and released once, whichever of this and `exchange` asks first.
+	 */
+	async fetchResult(req) {
+		requireString(req, 'req');
+		return toResult(await this.#post('/token', { grant_type: 'request', req }));
+	}
+
+	/**
+	 * Handles the request that arrived at your `redirectUri`: checks `state` against the one you
+	 * stored, then exchanges the code. A person who declined, or whose verification did not
+	 * succeed, arrives with an error instead of a code; that is returned, not thrown.
+	 *
+	 * @param {string|URL} url  the full URL the browser opened
+	 * @param {{ expectedState?: string }} [options]
+	 * @returns {Promise<{ ok: true, result: object } | { ok: false, error: string, outcome: string, state: string|null }>}
+	 */
+	async handleReturn(url, { expectedState } = {}) {
+		const back = Verify.parseReturn(url);
+		if (expectedState !== undefined && back.state !== expectedState) {
+			throw new VerifyError('state does not match the one this verification was started with.', { code: 'state_mismatch' });
+		}
+		if (!back.code) return { ok: false, error: back.error, outcome: back.outcome, state: back.state };
+		return { ok: true, result: await this.exchange(back.code) };
+	}
+
+	/**
+	 * Reads a return URL without calling anything.
+	 * `outcome` is `completed`, `denied`, `failed` or `abandoned`.
+	 */
+	static parseReturn(url) {
+		const params = (url instanceof URL ? url : new URL(String(url))).searchParams;
+		const state = params.get('state');
+		const code = params.get('code');
+		if (code) return { code, state, outcome: 'completed' };
+		const error = params.get('error');
+		if (!error) throw new VerifyError('The return URL carries neither code nor error.', { code: 'invalid_return' });
+		return { code: null, error, outcome: params.get('ism_outcome') || 'denied', state };
+	}
+}
+
+/**
+ * Checks a webhook's `ISM-Signature` header and returns the parsed event. Throws a
+ * `VerifyError` (code `invalid_signature`) when the signature, or its timestamp, does not hold.
+ *
+ * Pass the raw body exactly as it arrived — a re-serialised parse will not verify.
+ *
+ * @param {{ rawBody: string|Buffer, signature: string, secret: string, toleranceSeconds?: number, now?: number }} input
+ *   `secret` is the webhook's `whsec_…`, not the client secret. `now` is milliseconds.
+ */
+const verifyWebhook = ({ rawBody, signature, secret, toleranceSeconds = 300, now = Date.now() } = {}) => {
+	requireString(secret, 'secret');
+	if (typeof rawBody !== 'string' && !Buffer.isBuffer(rawBody)) {
+		throw new TypeError('rawBody must be the raw request body, as a string or Buffer.');
+	}
+	const body = Buffer.isBuffer(rawBody) ? rawBody.toString('utf8') : rawBody;
+	const parts = String(signature || '').split(',').map((p) => p.trim().split('='));
+	const t = Number(parts.find(([k]) => k === 't')?.[1]);
+	const v1 = parts.filter(([k]) => k === 'v1').map(([, v]) => v || '');
+	const refuse = (why) => new VerifyError(why, { code: 'invalid_signature' });
+	if (!Number.isFinite(t) || v1.length === 0) throw refuse('Malformed ISM-Signature header.');
+	if (Math.abs(Math.floor(now / 1000) - t) > toleranceSeconds) throw refuse('Webhook timestamp is outside the tolerance.');
+	const expected = crypto.createHmac('sha256', secret).update(`${t}.${body}`, 'utf8').digest();
+	const matches = v1.some((v) => {
+		const got = Buffer.from(v, 'hex');
+		return got.length === expected.length && crypto.timingSafeEqual(got, expected);
+	});
+	if (!matches) throw refuse('Webhook signature does not match.');
+	try {
+		return JSON.parse(body);
+	} catch {
+		throw refuse('Webhook body is not JSON.');
+	}
+};
+
+module.exports = { Verify, VerifyError, verifyWebhook, DEFAULT_BASE_URL };

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@ism/verify-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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": {
+    "test": "node --test index.test.js"
+  },
+  "keywords": [
+    "ism",
+    "identity",
+    "verification",
+    "kyc",
+    "ecuador"
+  ],
+  "author": "ISM",
+  "license": "MIT",
+  "type": "commonjs",
+  "types": "index.d.ts",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "homepage": "https://id.ism.ec",
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "44d2fc4511c4e4fd3a685616fc74ed2bafa0b69f"
+}