attestid_js_sdk 0.1.11 → 0.1.12

package/README.md

@@ -107,6 +107,28 @@ States: `idle`, `quality_check`, `uploading`, `retrying`, `liveness`, `completin
 
 Supported `idType` values: `national_id`, `passport`, `drivers_licence`.
 
+### Back of the card (optional)
+
+Many ID cards and driver's licences print their machine-readable zone (MRZ, the lines of `<<<`) on the back. For `national_id` and `drivers_licence` you can also send a photo of the back. The API cross-checks the MRZ's date of birth and expiry against the front, and rejects a mismatch as `document_sides_mismatch`. A back with no MRZ adds nothing, so check it first and only send it when an MRZ was found:
+
+```ts
+import { checkBackPhotoQuality } from 'attestid_js_sdk';
+
+const back = await checkBackPhotoQuality(backPhoto);
+startVerification({
+  userId, idType: 'national_id', idPhoto, consentGivenAt,
+  idPhotoBack: back.hasMrz ? backPhoto : undefined,
+});
+```
+
+Whether to ask for the back is each company's choice, set on the AttestID dashboard under Settings: `off` (the default; a back sent anyway is ignored), `optional` (ask, but the user can skip it) or `required` (the back must be sent with a readable MRZ). Read it with `client.getCaptureSettings(userId)`:
+
+```ts
+const { document_back } = await client.getCaptureSettings(userId); // 'off' | 'optional' | 'required'
+```
+
+`AttestIDVerifier` handles all of this for you. It reads the setting, then after the front it asks for the back when the policy is `optional` (with a skip button) or `required` (no skip).
+
 ## Verify results on your backend
 
 Always verify `result.attestation` on your backend before acting on a result.

package/dist/core/index.cjs

@@ -40,6 +40,7 @@ __export(core_exports, {
   buildHandoffUrl: () => buildHandoffUrl,
   canRetryLiveness: () => canRetryLiveness,
   canonicalJson: () => canonicalJson,
+  checkBackPhotoQuality: () => checkBackPhotoQuality,
   checkCaptureConditions: () => checkCaptureConditions,
   checkPhotoQuality: () => checkPhotoQuality,
   classifyConditions: () => classifyConditions,
@@ -254,6 +255,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;
@@ -269,14 +272,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);
       }
@@ -379,6 +383,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),
@@ -414,6 +419,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++) {
@@ -459,15 +483,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) => {
@@ -475,19 +501,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;
@@ -516,14 +546,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 [];
@@ -531,6 +561,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)];
 }
@@ -539,7 +570,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") {
@@ -555,14 +586,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) => {
@@ -570,7 +655,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);
@@ -596,11 +681,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);
@@ -672,13 +757,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;
@@ -690,6 +784,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}` }
@@ -829,22 +930,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 {
@@ -909,12 +1014,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"
   );
 }
@@ -931,7 +1036,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"
       );
     }
@@ -960,7 +1065,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;
@@ -990,16 +1095,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
@@ -2317,6 +2431,7 @@ function clearHandoffParamsFromAddressBar() {
   buildHandoffUrl,
   canRetryLiveness,
   canonicalJson,
+  checkBackPhotoQuality,
   checkCaptureConditions,
   checkPhotoQuality,
   classifyConditions,