attestid_js_sdk 0.1.11 → 0.1.13

package/dist/core/index.d.cts

@@ -4,6 +4,11 @@ interface RetryOptions {
     attempts?: number;
     /** Base backoff in ms (doubled each retry). Default 500. */
     baseDelayMs?: number;
+    /**
+     * How long to keep waiting while the server says the same request is still
+     * in progress (409 idempotency_request_in_progress). Default 120 000 ms.
+     */
+    inProgressWaitMs?: number;
 }
 
 type IdType = 'national_id' | 'passport' | 'drivers_licence';
@@ -74,10 +79,35 @@ interface LivenessCredentials {
     expiration: string;
     region: string;
 }
+/**
+ * Whether to ask for the back of a national ID / driver's licence. Each
+ * company decides on the AttestID dashboard (Settings):
+ *   - 'off'      — don't ask; a back sent anyway is ignored by the API.
+ *   - 'optional' — ask, and let the user skip it.
+ *   - 'required' — the back must be sent and its MRZ must be readable,
+ *                  otherwise POST /kyc/start fails with
+ *                  document_back_required / document_back_unreadable.
+ * Never applies to passports.
+ */
+type DocumentBackPolicy = 'off' | 'optional' | 'required';
+/** What the document capture should ask for, as set by the company. */
+interface CaptureSettings {
+    document_back: DocumentBackPolicy;
+}
 interface StartKYCOptions {
     userId: string;
     idType: IdType;
     idPhoto: File | Blob;
+    /**
+     * Optional photo of the BACK of a national ID / driver's licence. Many
+     * cards (ICAO 9303 TD1) print their machine-readable zone (MRZ) on the back;
+     * when this photo carries one, the API cross-checks its date of birth and
+     * expiry against the front and rejects a mismatch (document_sides_mismatch).
+     * A back with no MRZ is ignored, never a failure. Not accepted with
+     * idType 'passport'. Use checkBackPhotoQuality() to tell the user whether
+     * an MRZ was found before sending it.
+     */
+    idPhotoBack?: File | Blob;
     /**
      * Stated purpose for biometric processing. Defaults to 'identity_verification'.
      * One of: 'identity_verification', 'kyc_onboarding', 'kyc_refresh',
@@ -260,6 +290,12 @@ declare class AttestID {
      * TypeScript's type check are still rejected here at runtime.
      */
     startVerification(options: StartKYCOptions): Promise<StartKYCResponse>;
+    /**
+     * The company's capture settings, set on the AttestID dashboard. Read
+     * `document_back` before the document step to know whether to ask for the
+     * back of a national ID / driver's licence (see DocumentBackPolicy).
+     */
+    getCaptureSettings(userId: string): Promise<CaptureSettings>;
     /**
      * Fetch temporary AWS credentials and the Cognito identity pool ID from the
      * backend. Call this alongside startVerification() for the same userId to
@@ -502,6 +538,19 @@ interface PhotoQualityResult {
     ok: boolean;
     issues: string[];
 }
+interface BackPhotoQualityResult extends PhotoQualityResult {
+    /** True when an MRZ (the lines of letters, numbers and <<<) was found. */
+    hasMrz: boolean;
+}
+/**
+ * Checks a photo of the BACK of an ID card / driver's licence (the optional
+ * StartKYCOptions.idPhotoBack). The back is only useful to the API when it
+ * carries an ICAO 9303 MRZ, so `ok` means "an MRZ was found and is legible
+ * enough to send". When `hasMrz` is false the caller should offer a retake
+ * or let the user skip the back: many cards have no MRZ at all, and the
+ * verification never needs one.
+ */
+declare function checkBackPhotoQuality(photo: Blob): Promise<BackPhotoQualityResult>;
 /**
  * Analyses a photo for blur, exposure, and (where the browser supports it)
  * face presence before it is submitted to the AttestID API. Returns a list
@@ -582,4 +631,4 @@ declare function currentUrlWithoutHandoffParams(): string;
 /** Strips our own handoff params from the visible address bar, without a page reload. Call once, after reading them. */
 declare function clearHandoffParamsFromAddressBar(): void;
 
-export { AttestID, type AttestIDConfig, type AttestIDConfigBrowser, type AttestIDConfigServer, AttestIDError, type AttestationClaims, AuthError, CAPTURE_ISSUE_PROMPTS, CameraError, type CaptureAssurance, type CaptureConditions, type CaptureIssue, type ChecksInfo, DOC_ASPECT, type DocumentInfo, FLASH_CSS, HANDOFF_PARAM_KEYS, type HandoffParams, type IdType, KYCError, type KYCResult, LIVENESS_PROMPTS, type LivenessAction, type LivenessChallenge, type LivenessCredentials, type LivenessProvider, type LivenessRecording, type LivenessSegment, type LivenessVideoResult, MAX_GOOD_BRIGHTNESS, MIN_GOOD_BRIGHTNESS, MIN_GOOD_FPS, type PhotoQualityResult, type QrErrorCorrection, RECORDING_TAIL_MS, RETRYABLE_LIVENESS_REASONS, type RecordLivenessOptions, type SdkSessionResponse, SignatureError, type StartKYCOptions, type StartKYCResponse, type SubmitLivenessVideoOptions, ValidationError, type VerifyAttestationOptions, type VerifyWebhookOptions, type WaitForLivenessOptions, buildHandoffUrl, canRetryLiveness, canonicalJson, checkCaptureConditions, checkPhotoQuality, classifyConditions, clearHandoffParamsFromAddressBar, createSdkSession, currentUrlWithoutHandoffParams, faceMatchOutcome, generateHandoffToken, getQrMatrix, isMobileDevice, livenessCaptureSupported, meanLuma, openCameraSession, openFrontCamera, pickRecorderMimeType, promptFor, rawSessionId, readHandoffParams, recordLiveness, scriptDurationMs, segmentAt, verifyAttestation, verifyWebhook };
+export { AttestID, type AttestIDConfig, type AttestIDConfigBrowser, type AttestIDConfigServer, AttestIDError, type AttestationClaims, AuthError, type BackPhotoQualityResult, CAPTURE_ISSUE_PROMPTS, CameraError, type CaptureAssurance, type CaptureConditions, type CaptureIssue, type CaptureSettings, type ChecksInfo, DOC_ASPECT, type DocumentBackPolicy, type DocumentInfo, FLASH_CSS, HANDOFF_PARAM_KEYS, type HandoffParams, type IdType, KYCError, type KYCResult, LIVENESS_PROMPTS, type LivenessAction, type LivenessChallenge, type LivenessCredentials, type LivenessProvider, type LivenessRecording, type LivenessSegment, type LivenessVideoResult, MAX_GOOD_BRIGHTNESS, MIN_GOOD_BRIGHTNESS, MIN_GOOD_FPS, type PhotoQualityResult, type QrErrorCorrection, RECORDING_TAIL_MS, RETRYABLE_LIVENESS_REASONS, type RecordLivenessOptions, type SdkSessionResponse, SignatureError, type StartKYCOptions, type StartKYCResponse, type SubmitLivenessVideoOptions, ValidationError, type VerifyAttestationOptions, type VerifyWebhookOptions, type WaitForLivenessOptions, buildHandoffUrl, canRetryLiveness, canonicalJson, checkBackPhotoQuality, checkCaptureConditions, checkPhotoQuality, classifyConditions, clearHandoffParamsFromAddressBar, createSdkSession, currentUrlWithoutHandoffParams, faceMatchOutcome, generateHandoffToken, getQrMatrix, isMobileDevice, livenessCaptureSupported, meanLuma, openCameraSession, openFrontCamera, pickRecorderMimeType, promptFor, rawSessionId, readHandoffParams, recordLiveness, scriptDurationMs, segmentAt, verifyAttestation, verifyWebhook };

package/dist/core/index.d.ts

@@ -4,6 +4,11 @@ interface RetryOptions {
     attempts?: number;
     /** Base backoff in ms (doubled each retry). Default 500. */
     baseDelayMs?: number;
+    /**
+     * How long to keep waiting while the server says the same request is still
+     * in progress (409 idempotency_request_in_progress). Default 120 000 ms.
+     */
+    inProgressWaitMs?: number;
 }
 
 type IdType = 'national_id' | 'passport' | 'drivers_licence';
@@ -74,10 +79,35 @@ interface LivenessCredentials {
     expiration: string;
     region: string;
 }
+/**
+ * Whether to ask for the back of a national ID / driver's licence. Each
+ * company decides on the AttestID dashboard (Settings):
+ *   - 'off'      — don't ask; a back sent anyway is ignored by the API.
+ *   - 'optional' — ask, and let the user skip it.
+ *   - 'required' — the back must be sent and its MRZ must be readable,
+ *                  otherwise POST /kyc/start fails with
+ *                  document_back_required / document_back_unreadable.
+ * Never applies to passports.
+ */
+type DocumentBackPolicy = 'off' | 'optional' | 'required';
+/** What the document capture should ask for, as set by the company. */
+interface CaptureSettings {
+    document_back: DocumentBackPolicy;
+}
 interface StartKYCOptions {
     userId: string;
     idType: IdType;
     idPhoto: File | Blob;
+    /**
+     * Optional photo of the BACK of a national ID / driver's licence. Many
+     * cards (ICAO 9303 TD1) print their machine-readable zone (MRZ) on the back;
+     * when this photo carries one, the API cross-checks its date of birth and
+     * expiry against the front and rejects a mismatch (document_sides_mismatch).
+     * A back with no MRZ is ignored, never a failure. Not accepted with
+     * idType 'passport'. Use checkBackPhotoQuality() to tell the user whether
+     * an MRZ was found before sending it.
+     */
+    idPhotoBack?: File | Blob;
     /**
      * Stated purpose for biometric processing. Defaults to 'identity_verification'.
      * One of: 'identity_verification', 'kyc_onboarding', 'kyc_refresh',
@@ -260,6 +290,12 @@ declare class AttestID {
      * TypeScript's type check are still rejected here at runtime.
      */
     startVerification(options: StartKYCOptions): Promise<StartKYCResponse>;
+    /**
+     * The company's capture settings, set on the AttestID dashboard. Read
+     * `document_back` before the document step to know whether to ask for the
+     * back of a national ID / driver's licence (see DocumentBackPolicy).
+     */
+    getCaptureSettings(userId: string): Promise<CaptureSettings>;
     /**
      * Fetch temporary AWS credentials and the Cognito identity pool ID from the
      * backend. Call this alongside startVerification() for the same userId to
@@ -502,6 +538,19 @@ interface PhotoQualityResult {
     ok: boolean;
     issues: string[];
 }
+interface BackPhotoQualityResult extends PhotoQualityResult {
+    /** True when an MRZ (the lines of letters, numbers and <<<) was found. */
+    hasMrz: boolean;
+}
+/**
+ * Checks a photo of the BACK of an ID card / driver's licence (the optional
+ * StartKYCOptions.idPhotoBack). The back is only useful to the API when it
+ * carries an ICAO 9303 MRZ, so `ok` means "an MRZ was found and is legible
+ * enough to send". When `hasMrz` is false the caller should offer a retake
+ * or let the user skip the back: many cards have no MRZ at all, and the
+ * verification never needs one.
+ */
+declare function checkBackPhotoQuality(photo: Blob): Promise<BackPhotoQualityResult>;
 /**
  * Analyses a photo for blur, exposure, and (where the browser supports it)
  * face presence before it is submitted to the AttestID API. Returns a list
@@ -582,4 +631,4 @@ declare function currentUrlWithoutHandoffParams(): string;
 /** Strips our own handoff params from the visible address bar, without a page reload. Call once, after reading them. */
 declare function clearHandoffParamsFromAddressBar(): void;
 
-export { AttestID, type AttestIDConfig, type AttestIDConfigBrowser, type AttestIDConfigServer, AttestIDError, type AttestationClaims, AuthError, CAPTURE_ISSUE_PROMPTS, CameraError, type CaptureAssurance, type CaptureConditions, type CaptureIssue, type ChecksInfo, DOC_ASPECT, type DocumentInfo, FLASH_CSS, HANDOFF_PARAM_KEYS, type HandoffParams, type IdType, KYCError, type KYCResult, LIVENESS_PROMPTS, type LivenessAction, type LivenessChallenge, type LivenessCredentials, type LivenessProvider, type LivenessRecording, type LivenessSegment, type LivenessVideoResult, MAX_GOOD_BRIGHTNESS, MIN_GOOD_BRIGHTNESS, MIN_GOOD_FPS, type PhotoQualityResult, type QrErrorCorrection, RECORDING_TAIL_MS, RETRYABLE_LIVENESS_REASONS, type RecordLivenessOptions, type SdkSessionResponse, SignatureError, type StartKYCOptions, type StartKYCResponse, type SubmitLivenessVideoOptions, ValidationError, type VerifyAttestationOptions, type VerifyWebhookOptions, type WaitForLivenessOptions, buildHandoffUrl, canRetryLiveness, canonicalJson, checkCaptureConditions, checkPhotoQuality, classifyConditions, clearHandoffParamsFromAddressBar, createSdkSession, currentUrlWithoutHandoffParams, faceMatchOutcome, generateHandoffToken, getQrMatrix, isMobileDevice, livenessCaptureSupported, meanLuma, openCameraSession, openFrontCamera, pickRecorderMimeType, promptFor, rawSessionId, readHandoffParams, recordLiveness, scriptDurationMs, segmentAt, verifyAttestation, verifyWebhook };
+export { AttestID, type AttestIDConfig, type AttestIDConfigBrowser, type AttestIDConfigServer, AttestIDError, type AttestationClaims, AuthError, type BackPhotoQualityResult, CAPTURE_ISSUE_PROMPTS, CameraError, type CaptureAssurance, type CaptureConditions, type CaptureIssue, type CaptureSettings, type ChecksInfo, DOC_ASPECT, type DocumentBackPolicy, type DocumentInfo, FLASH_CSS, HANDOFF_PARAM_KEYS, type HandoffParams, type IdType, KYCError, type KYCResult, LIVENESS_PROMPTS, type LivenessAction, type LivenessChallenge, type LivenessCredentials, type LivenessProvider, type LivenessRecording, type LivenessSegment, type LivenessVideoResult, MAX_GOOD_BRIGHTNESS, MIN_GOOD_BRIGHTNESS, MIN_GOOD_FPS, type PhotoQualityResult, type QrErrorCorrection, RECORDING_TAIL_MS, RETRYABLE_LIVENESS_REASONS, type RecordLivenessOptions, type SdkSessionResponse, SignatureError, type StartKYCOptions, type StartKYCResponse, type SubmitLivenessVideoOptions, ValidationError, type VerifyAttestationOptions, type VerifyWebhookOptions, type WaitForLivenessOptions, buildHandoffUrl, canRetryLiveness, canonicalJson, checkBackPhotoQuality, checkCaptureConditions, checkPhotoQuality, classifyConditions, clearHandoffParamsFromAddressBar, createSdkSession, currentUrlWithoutHandoffParams, faceMatchOutcome, generateHandoffToken, getQrMatrix, isMobileDevice, livenessCaptureSupported, meanLuma, openCameraSession, openFrontCamera, pickRecorderMimeType, promptFor, rawSessionId, readHandoffParams, recordLiveness, scriptDurationMs, segmentAt, verifyAttestation, verifyWebhook };

package/dist/core/index.js

@@ -99,6 +99,8 @@ function randomId() {
 // src/core/http.ts
 var RETRY_FRESH_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
 var MAX_RETRY_AFTER_MS = 1e4;
+var DEFAULT_IN_PROGRESS_WAIT_MS = 12e4;
+var IN_PROGRESS_ERROR = "idempotency_request_in_progress";
 var defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 var sleep = defaultSleep;
 function retryAfterMs(res, fallback) {
@@ -106,9 +108,19 @@ function retryAfterMs(res, fallback) {
   const secs = raw ? Number(raw) : NaN;
   return Number.isFinite(secs) && secs >= 0 ? Math.min(secs * 1e3, MAX_RETRY_AFTER_MS) : fallback;
 }
+async function isInProgress(res) {
+  try {
+    const body = await (res.clone ? res.clone() : res).json();
+    return (body?.detail?.error ?? body?.error) === IN_PROGRESS_ERROR;
+  } catch {
+    return false;
+  }
+}
 async function postIdempotent(fetchImpl, url, build, options = {}) {
   const attempts = Math.max(1, options.attempts ?? 3);
   const base = options.baseDelayMs ?? 500;
+  const inProgressBudget = options.inProgressWaitMs ?? DEFAULT_IN_PROGRESS_WAIT_MS;
+  let inProgressWaited = 0;
   let key = randomId();
   let req = await build();
   for (let attempt = 1; ; attempt++) {
@@ -125,11 +137,17 @@ async function postIdempotent(fetchImpl, url, build, options = {}) {
       await sleep(base * 2 ** (attempt - 1));
       continue;
     }
-    if (last || res.ok) return res;
+    if (res.ok) return res;
     if (res.status === 409) {
-      await sleep(retryAfterMs(res, base));
+      if (!await isInProgress(res)) return res;
+      const delay = retryAfterMs(res, base);
+      if (inProgressWaited + delay > inProgressBudget) return res;
+      inProgressWaited += delay;
+      await sleep(delay);
+      attempt--;
       continue;
     }
+    if (last) return res;
     if (RETRY_FRESH_STATUSES.has(res.status)) {
       await sleep(retryAfterMs(res, base * 2 ** (attempt - 1)));
       key = randomId();
@@ -186,6 +204,8 @@ function countTextRows(grey, w, h, x0, aw) {
   return textRows;
 }
 var EDGE_DELTA = 28;
+var EDGE_DELTA_MIN = 12;
+var EDGE_DELTA_P99_FRACTION = 0.8;
 var NOISY_MEDIAN_STEP = 9;
 var SKEW_TANS = [0, 0.0175, -0.0175, 0.0349, -0.0349, 0.0524, -0.0524, 0.0699, -0.0699];
 var STRIPS = 8;
@@ -201,14 +221,15 @@ function idTextNotFoundMessage(idType) {
   const doc = idType === "drivers_licence" ? "driver's licence" : "ID card";
   return `We could not detect readable printed details on your ${doc}. Photograph the front of the card (the side with your photo, name and ID number) so it fills the frame, in good light and without glare.`;
 }
-function measureTextBands(grey, w, h, x0 = 0, aw = w) {
+function measureTextBands(grey, w, h, x0 = 0, aw = w, edgeDeltaOverride) {
   const src = medianStep(grey, w, h, x0, aw) >= NOISY_MEDIAN_STEP ? boxSmooth(grey, w, h, x0, aw) : null;
   const at = src ? (y, x) => src[y * aw + x] : (y, x) => grey[y * w + x0 + x];
+  const edgeDelta = edgeDeltaOverride ?? edgeThreshold(at, aw, h);
   const ex = [];
   const ey = [];
   for (let y = 0; y < h; y++) {
     for (let x = 0; x < aw - 1; x++) {
-      if (Math.abs(at(y, x + 1) - at(y, x)) > EDGE_DELTA) {
+      if (Math.abs(at(y, x + 1) - at(y, x)) > edgeDelta) {
         ex.push(x);
         ey.push(y);
       }
@@ -311,6 +332,7 @@ function measureTextBands(grey, w, h, x0 = 0, aw = w) {
         height,
         strip: s,
         firstCell: first,
+        lastCell: last,
         spanFrac: span / cps,
         coverage: active / span,
         density: inside / (span * CELL * height),
@@ -346,6 +368,25 @@ function medianStep(grey, w, h, x0, aw) {
   }
   return 255;
 }
+function edgeThreshold(at, aw, h) {
+  const hist = new Uint32Array(256);
+  let n = 0;
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < aw - 1; x++) {
+      hist[Math.min(255, Math.round(Math.abs(at(y, x + 1) - at(y, x))))]++;
+      n++;
+    }
+  }
+  let acc = 0, p99 = 255;
+  for (let v = 0; v < 256; v++) {
+    acc += hist[v];
+    if (acc >= n * 0.99) {
+      p99 = v;
+      break;
+    }
+  }
+  return Math.max(EDGE_DELTA_MIN, Math.min(EDGE_DELTA, Math.round(p99 * EDGE_DELTA_P99_FRACTION)));
+}
 function boxSmooth(grey, w, h, x0, aw) {
   const out = new Float32Array(aw * h);
   for (let y = 0; y < h; y++) {
@@ -391,15 +432,17 @@ function periodicity(profile, glyphHeight) {
   }
   return best;
 }
-function analyseTextLayout(grey, w, h, x0 = 0, aw = w) {
-  const { bands, fullWidthLines } = measureTextBands(grey, w, h, x0, aw);
+function analyseTextLayout(grey, w, h, x0 = 0, aw = w, edgeDeltaOverride) {
+  const { bands, fullWidthLines } = measureTextBands(grey, w, h, x0, aw, edgeDeltaOverride);
   const stripCells = Math.ceil(Math.max(1, Math.floor(aw / STRIPS)) / CELL);
   const clean = bands.filter((b) => b.spanFrac >= 0.2 && b.coverage >= 0.35 && b.bleed <= TEXT_MAX_BLEED && b.spanFrac * stripCells * CELL / b.height >= 3);
   const textLines = clusterBands(clean).length;
   let alignedLines = 0;
   for (const b of clean) {
-    const n = clean.filter((o) => o.strip === b.strip && Math.abs(o.firstCell - b.firstCell) <= 1).length;
-    alignedLines = Math.max(alignedLines, n);
+    const sameStrip = clean.filter((o) => o.strip === b.strip);
+    const left = sameStrip.filter((o) => Math.abs(o.firstCell - b.firstCell) <= 1).length;
+    const right = sameStrip.filter((o) => Math.abs(o.lastCell - b.lastCell) <= 1).length;
+    alignedLines = Math.max(alignedLines, left, right);
   }
   const isMrzLine = (l) => l.bleed <= MRZ_MAX_BLEED && l.periodicity >= MRZ_MIN_PERIODICITY;
   const stacked = (p, q) => {
@@ -407,19 +450,23 @@ function analyseTextLayout(grey, w, h, x0 = 0, aw = w) {
     const pitch = q.center - p.center;
     return pitch >= 1.3 * avgH && pitch <= 2.8 * avgH && Math.max(p.height, q.height) / Math.min(p.height, q.height) <= 1.4;
   };
-  let hasMrz = false;
+  let hasMrz2 = false;
   let runStart = 0;
   for (let i = 1; i <= fullWidthLines.length; i++) {
     if (i < fullWidthLines.length && stacked(fullWidthLines[i - 1], fullWidthLines[i])) continue;
     const run = fullWidthLines.slice(runStart, i);
     if (run.length >= 2 && run.length <= 3) {
       for (let j = 1; j < run.length; j++) {
-        if (isMrzLine(run[j - 1]) && isMrzLine(run[j])) hasMrz = true;
+        if (isMrzLine(run[j - 1]) && isMrzLine(run[j])) hasMrz2 = true;
       }
     }
     runStart = i;
   }
-  return { textLines, alignedLines, hasMrz };
+  return { textLines, alignedLines, hasMrz: hasMrz2 };
+}
+var MRZ_RETRY_EDGE_DELTA = 14;
+function hasMrz(grey, w, h, x0 = 0, aw = w) {
+  return analyseTextLayout(grey, w, h, x0, aw).hasMrz || analyseTextLayout(grey, w, h, x0, aw, MRZ_RETRY_EDGE_DELTA).hasMrz;
 }
 async function detectText(source) {
   const TextDetectorCtor = globalThis.TextDetector;
@@ -448,14 +495,14 @@ function laplacianVariance(grey, w, h, x0, aw) {
 function checkPassportDocument(grey, w, h, browserFoundMrz = false) {
   const ratio = w / h;
   const regions = ratio > 2 ? [{ x0: 0, aw: Math.floor(w / 2) }, { x0: Math.floor(w / 2), aw: w - Math.floor(w / 2) }] : [{ x0: 0, aw: w }];
-  let dataPage = regions.find(({ x0, aw }) => analyseTextLayout(grey, w, h, x0, aw).hasMrz);
+  let dataPage = regions.find(({ x0, aw }) => hasMrz(grey, w, h, x0, aw));
   if (!dataPage && browserFoundMrz) {
     dataPage = regions.reduce((best, r) => countTextRows(grey, w, h, r.x0, r.aw) > countTextRows(grey, w, h, best.x0, best.aw) ? r : best);
   }
   if (!dataPage) return [MRZ_NOT_FOUND_MESSAGE];
   if (laplacianVariance(grey, w, h, dataPage.x0, dataPage.aw) < BLUR_THRESHOLD) {
     return [
-      "The data page is too blurry \u2014 hold the camera steady and ensure the MRZ text at the bottom of the data page is in sharp focus."
+      "The data page is too blurry. Hold the camera steady and make sure the MRZ text at the bottom of the data page is in sharp focus."
     ];
   }
   return [];
@@ -463,6 +510,7 @@ function checkPassportDocument(grey, w, h, browserFoundMrz = false) {
 function checkReadableText(grey, w, h, idType, browserTextBlocks = null) {
   if ((browserTextBlocks ?? 0) >= 3) return [];
   const layout = analyseTextLayout(grey, w, h);
+  if (layout.hasMrz) return [];
   if (layout.textLines >= MIN_ID_TEXT_LINES && layout.alignedLines >= MIN_ID_ALIGNED_LINES) return [];
   return [idTextNotFoundMessage(idType)];
 }
@@ -471,7 +519,7 @@ function checkDocumentIdentity(grey, w, h, idType, precomputedTotalTextRows) {
   const totalTextRows = precomputedTotalTextRows ?? countTextRows(grey, w, h, 0, w);
   if (totalTextRows < Math.max(2, h * 0.02)) {
     return [
-      "This does not look like an identity document \u2014 no printed text was detected. Please photograph your ID card or passport data page on a plain, well-lit background."
+      "This does not look like an identity document: no printed text was detected. Please photograph your ID card or passport data page on a plain, well-lit background."
     ];
   }
   if (idType === "passport") {
@@ -487,14 +535,68 @@ function checkDocumentIdentity(grey, w, h, idType, precomputedTotalTextRows) {
   }
   return [];
 }
+var BACK_MRZ_NOT_FOUND_MESSAGE = "We could not read the machine-readable zone (MRZ) on the back of your card: the 3 lines of letters, numbers and <<< along the bottom. This usually means the photo is blurry or the card is too small in the frame. Fill the frame with the back of the card, hold the phone steady, and wait for the <<< lines to come into focus before capturing. Avoid glare on the card.";
+function checkBackOfCard(grey, w, h, browserFoundMrz = false) {
+  let total = 0;
+  for (let i = 0; i < grey.length; i++) total += grey[i];
+  const brightness = total / grey.length;
+  const issues = [];
+  if (brightness < DARK_THRESHOLD) issues.push("Image is too dark. Move to a well-lit area.");
+  if (brightness > BRIGHT_THRESHOLD)
+    issues.push("Image is overexposed. Avoid direct light or glare shining onto the card.");
+  const mrzFound = browserFoundMrz || hasMrz(grey, w, h);
+  if (mrzFound && laplacianVariance(grey, w, h, 0, w) < BLUR_THRESHOLD) {
+    issues.push("The back of the card is too blurry. Hold the camera steady so the lines of <<< are sharp.");
+  }
+  if (!mrzFound && issues.length === 0) issues.push(BACK_MRZ_NOT_FOUND_MESSAGE);
+  return { ok: issues.length === 0, issues, hasMrz: mrzFound };
+}
+async function checkBackPhotoQuality(photo) {
+  if (photo.size < MIN_FILE_BYTES) {
+    return { ok: false, hasMrz: false, issues: ["File is too small. This does not appear to be a real photo."] };
+  }
+  if (!await hasSupportedMagicBytes(photo)) {
+    return { ok: false, hasMrz: false, issues: ["Unsupported file type. Please upload a JPEG or PNG photo."] };
+  }
+  return new Promise((resolve) => {
+    const img = new Image();
+    const url = URL.createObjectURL(photo);
+    img.onerror = () => {
+      URL.revokeObjectURL(url);
+      resolve({ ok: false, hasMrz: false, issues: ["Could not read the image. Please try a different photo."] });
+    };
+    img.onload = async () => {
+      URL.revokeObjectURL(url);
+      const scale = Math.min(1, 640 / Math.max(img.width, img.height));
+      const w = Math.round(img.width * scale);
+      const h = Math.round(img.height * scale);
+      const canvas = document.createElement("canvas");
+      canvas.width = w;
+      canvas.height = h;
+      const ctx = canvas.getContext("2d");
+      ctx.imageSmoothingEnabled = false;
+      ctx.drawImage(img, 0, 0, w, h);
+      const textPromise = detectText(canvas);
+      const { data } = ctx.getImageData(0, 0, w, h);
+      const grey = new Float32Array(w * h);
+      for (let i = 0; i < grey.length; i++) {
+        grey[i] = 0.299 * data[i * 4] + 0.587 * data[i * 4 + 1] + 0.114 * data[i * 4 + 2];
+      }
+      const texts = await textPromise;
+      const browserFoundMrz = texts?.some((t) => looksLikeMrzLine(t.rawValue ?? "")) ?? false;
+      resolve(checkBackOfCard(grey, w, h, browserFoundMrz));
+    };
+    img.src = url;
+  });
+}
 async function checkPhotoQuality(photo, idType = "national_id") {
   const issues = [];
   if (photo.size < MIN_FILE_BYTES) {
-    issues.push("File is too small \u2014 this does not appear to be a real photo.");
+    issues.push("File is too small. This does not appear to be a real photo.");
     return { ok: false, issues };
   }
   if (!await hasSupportedMagicBytes(photo)) {
-    issues.push("Unsupported file type \u2014 please upload a JPEG or PNG photo.");
+    issues.push("Unsupported file type. Please upload a JPEG or PNG photo.");
     return { ok: false, issues };
   }
   return new Promise((resolve) => {
@@ -502,7 +604,7 @@ async function checkPhotoQuality(photo, idType = "national_id") {
     const url = URL.createObjectURL(photo);
     img.onerror = () => {
       URL.revokeObjectURL(url);
-      resolve({ ok: false, issues: ["Could not read the image \u2014 please try a different photo."] });
+      resolve({ ok: false, issues: ["Could not read the image. Please try a different photo."] });
     };
     img.onload = async () => {
       URL.revokeObjectURL(url);
@@ -528,11 +630,11 @@ async function checkPhotoQuality(photo, idType = "national_id") {
       }
       const brightness = totalLum / len;
       if (idType !== "passport" && laplacianVariance(grey, w, h, 0, w) < BLUR_THRESHOLD)
-        issues.push("Photo is too blurry \u2014 hold the camera steady and ensure the document is in sharp focus.");
+        issues.push("Photo is too blurry. Hold the camera steady and make sure the document is in sharp focus.");
       if (brightness < DARK_THRESHOLD)
-        issues.push("Image is too dark \u2014 move to a well-lit area.");
+        issues.push("Image is too dark. Move to a well-lit area.");
       if (brightness > BRIGHT_THRESHOLD)
-        issues.push("Image is overexposed \u2014 avoid direct light or glare shining onto the document.");
+        issues.push("Image is overexposed. Avoid direct light or glare shining onto the document.");
       const totalTextRows = countTextRows(grey, w, h, 0, w);
       const identityIssues = checkDocumentIdentity(grey, w, h, idType, totalTextRows);
       issues.push(...identityIssues);
@@ -564,12 +666,14 @@ var fetchOf = (t) => t?.fetch ?? ((input, init) => fetch(input, init));
 async function extractErrorMessage(res) {
   const text = await res.text();
   try {
-    const detail = JSON.parse(text).detail;
+    const parsed = JSON.parse(text);
+    const detail = parsed.detail;
     if (typeof detail === "string") return detail;
     if (detail !== null && typeof detail === "object") {
       const message = detail.message;
       if (typeof message === "string") return message;
     }
+    if (detail === void 0 && typeof parsed.message === "string") return parsed.message;
   } catch {
   }
   return text;
@@ -604,13 +708,22 @@ function sdkHeaders(sdkToken, livenessFlows) {
 }
 async function startKYC(apiUrl, sdkToken, options, transport, signCapture2, livenessFlows) {
   if (!await hasSupportedMagicBytes(options.idPhoto)) {
-    throw new ValidationError("Unsupported image format \u2014 only JPEG and PNG photos are accepted.");
+    throw new ValidationError("Unsupported image format. Only JPEG and PNG photos are accepted.");
+  }
+  if (options.idPhotoBack) {
+    if (options.idType === "passport") {
+      throw new ValidationError("idPhotoBack is only accepted for national IDs and driver's licences.");
+    }
+    if (!await hasSupportedMagicBytes(options.idPhotoBack)) {
+      throw new ValidationError("Unsupported image format for the back of the card. Only JPEG and PNG photos are accepted.");
+    }
   }
   const build = async () => {
     const form = new FormData();
     form.append("user_id", options.userId);
     form.append("id_type", options.idType);
     form.append("id_photo", options.idPhoto);
+    if (options.idPhotoBack) form.append("id_photo_back", options.idPhotoBack);
     form.append("consent_given_at", options.consentGivenAt.toISOString());
     form.append("processing_purpose", options.processingPurpose ?? "identity_verification");
     const signature = signCapture2 ? await signCapture2() : null;
@@ -622,6 +735,13 @@ async function startKYC(apiUrl, sdkToken, options, transport, signCapture2, live
   const res = await postIdempotent(fetchOf(transport), `${apiUrl}/v1/kyc/start`, build, transport?.retry);
   return handleResponse(res);
 }
+async function getCaptureSettings(apiUrl, sdkToken, transport) {
+  const res = await fetchOf(transport)(`${apiUrl}/v1/kyc/capture-settings`, {
+    headers: { "Authorization": `Bearer ${sdkToken}` }
+  });
+  if (res.status === 404) return { document_back: "off" };
+  return handleResponse(res);
+}
 async function getLivenessCredentials(apiUrl, sdkToken, transport) {
   const res = await fetchOf(transport)(`${apiUrl}/v1/kyc/liveness-credentials`, {
     headers: { "Authorization": `Bearer ${sdkToken}` }
@@ -761,22 +881,26 @@ async function registerDeviceKey(fetchImpl, apiUrl, token, pair) {
   });
   return res.device_key_id;
 }
-function captureMessage(imageSha256Hex, userId, nonce, ts) {
+function captureMessage(imageSha256Hex, userId, nonce, ts, backImageSha256Hex) {
+  if (backImageSha256Hex !== void 0) {
+    return `attestid-capture-v2|${imageSha256Hex}|${backImageSha256Hex}|${userId}|${nonce}|${ts}`;
+  }
   return `attestid-capture-v1|${imageSha256Hex}|${userId}|${nonce}|${ts}`;
 }
-async function signCapture(fetchImpl, apiUrl, token, userId, photo) {
+async function signCapture(fetchImpl, apiUrl, token, userId, photo, backPhoto) {
   try {
     if (!deviceBindingSupported()) return null;
     const pair = await getDeviceKeyPair();
     const deviceKeyId = await registerDeviceKey(fetchImpl, apiUrl, token, pair);
     const imageHash = bytesToHex(await sha256(new Uint8Array(await photo.arrayBuffer())));
+    const backHash = backPhoto ? bytesToHex(await sha256(new Uint8Array(await backPhoto.arrayBuffer()))) : void 0;
     const nonce = await challenge(fetchImpl, apiUrl, token);
     const ts = Math.floor(Date.now() / 1e3);
     const sig = new Uint8Array(
       await subtle().sign(
         { name: "ECDSA", hash: "SHA-256" },
         pair.privateKey,
-        buf(utf8(captureMessage(imageHash, userId, nonce, ts)))
+        buf(utf8(captureMessage(imageHash, userId, nonce, ts, backHash)))
       )
     );
     return {
@@ -841,12 +965,12 @@ function assertSecureApiUrl(apiUrl) {
   try {
     url = new URL(apiUrl);
   } catch {
-    throw new AttestIDError(`apiUrl must be a valid absolute URL \u2014 got "${apiUrl}".`, "INSECURE_CONFIG");
+    throw new AttestIDError(`apiUrl must be a valid absolute URL, got "${apiUrl}".`, "INSECURE_CONFIG");
   }
   if (url.protocol === "https:") return;
   if (url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname)) return;
   throw new AttestIDError(
-    `apiUrl must use https:// \u2014 got "${apiUrl}". Sending it over plain http exposes your API key, SDK token, and uploaded ID photos to anyone on the network path. http://localhost (or 127.0.0.1/::1) is allowed for local development against a backend running without TLS.`,
+    `apiUrl must use https://, got "${apiUrl}". Sending it over plain http exposes your API key, SDK token, and uploaded ID photos to anyone on the network path. http://localhost (or 127.0.0.1/::1) is allowed for local development against a backend running without TLS.`,
     "INSECURE_CONFIG"
   );
 }
@@ -863,7 +987,7 @@ var AttestID = class {
     assertSecureApiUrl(config.apiUrl);
     if (isServerConfig(config) && !isTrustedServerEnvironment()) {
       throw new AttestIDError(
-        "apiKey/accessKeyId must only be used in a trusted Node.js backend process \u2014 a bundler would ship this long-lived secret to every client, letting anyone extract it. In browser or mobile app code, configure `getSdkToken` instead: a callback that fetches an already-minted sdk_token from your own backend, which holds apiKey server-side and calls POST /kyc/session. See the integration guide for the backend-proxy pattern.",
+        "apiKey/accessKeyId must only be used in a trusted Node.js backend process. A bundler would ship this long-lived secret to every client, letting anyone extract it. In browser or mobile app code, configure `getSdkToken` instead: a callback that fetches an already-minted sdk_token from your own backend, which holds apiKey server-side and calls POST /kyc/session. See the integration guide for the backend-proxy pattern.",
         "INSECURE_CONFIG"
       );
     }
@@ -892,7 +1016,7 @@ var AttestID = class {
     const minted = sessionPromise.then((session) => {
       if (!session?.sdk_token) {
         throw new AuthError(
-          "getSdkToken() did not return a valid sdk_token \u2014 check that your backend's /api/attestid-session endpoint (or equivalent) returned a successful response."
+          "getSdkToken() did not return a valid sdk_token. Check that your backend's /api/attestid-session endpoint (or equivalent) returned a successful response."
         );
       }
       this.tokenExpiresAt = Date.now() + session.expires_in * 1e3;
@@ -922,16 +1046,25 @@ var AttestID = class {
   async startVerification(options) {
     if (!options.consentGivenAt) {
       throw new AttestIDError(
-        "consentGivenAt is required \u2014 capture the timestamp of an explicit user consent action before starting verification",
+        "consentGivenAt is required: capture the timestamp of an explicit user consent action before starting verification",
         "CONSENT_REQUIRED"
       );
     }
     const token = await this.getSdkToken(options.userId);
     const { apiUrl } = this.config;
     const fetchImpl = this.transport.fetch ?? ((input, init) => fetch(input, init));
-    const signer = this.deviceBinding ? () => signCapture(fetchImpl, apiUrl, token, options.userId, options.idPhoto) : void 0;
+    const signer = this.deviceBinding ? () => signCapture(fetchImpl, apiUrl, token, options.userId, options.idPhoto, options.idPhotoBack) : void 0;
     return startKYC(apiUrl, token, options, this.transport, signer, this.livenessFlows);
   }
+  /**
+   * The company's capture settings, set on the AttestID dashboard. Read
+   * `document_back` before the document step to know whether to ask for the
+   * back of a national ID / driver's licence (see DocumentBackPolicy).
+   */
+  async getCaptureSettings(userId) {
+    const token = await this.getSdkToken(userId);
+    return getCaptureSettings(this.config.apiUrl, token, this.transport);
+  }
   /**
    * Fetch temporary AWS credentials and the Cognito identity pool ID from the
    * backend. Call this alongside startVerification() for the same userId to
@@ -2248,6 +2381,7 @@ export {
   buildHandoffUrl,
   canRetryLiveness,
   canonicalJson,
+  checkBackPhotoQuality,
   checkCaptureConditions,
   checkPhotoQuality,
   classifyConditions,