@sekyro/web 0.1.0-rc.1 → 0.1.0-rc.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (127) hide show
  1. package/CHANGELOG.md +225 -0
  2. package/LICENSE +25 -16
  3. package/README.md +105 -61
  4. package/THIRD-PARTY-NOTICES.txt +154 -0
  5. package/dist/background-monitor-A7FKJOAG.js +1 -0
  6. package/dist/capture-constraints-B5omafmk.d.cts +44 -0
  7. package/dist/capture-constraints-B5omafmk.d.ts +44 -0
  8. package/dist/capture-session-doc-DMQ7T3HC.js +1 -0
  9. package/dist/{capture-session-v3-CAoWM8iT.d.cts → capture-session-v3-CCHws1mz.d.cts} +174 -15
  10. package/dist/{capture-session-v3-BJ8ciaWl.d.ts → capture-session-v3-DYrhYJoM.d.ts} +174 -15
  11. package/dist/chunk-73M7LS4H.js +1 -0
  12. package/dist/chunk-7ZCZY3ZP.js +1 -0
  13. package/dist/chunk-A3FUGHAH.js +2 -0
  14. package/dist/chunk-AHD4DA2V.js +1 -0
  15. package/dist/chunk-BPE5NSQ2.js +1 -0
  16. package/dist/chunk-CJHMFPL6.js +1 -0
  17. package/dist/chunk-DFTCAWMP.js +1 -0
  18. package/dist/chunk-DK5YPBDQ.js +1 -0
  19. package/dist/chunk-FHJ7HO3M.js +1 -0
  20. package/dist/chunk-FPXL63KZ.js +1 -0
  21. package/dist/chunk-FUHDOEBP.js +1 -0
  22. package/dist/chunk-G6LKLN4U.js +1 -0
  23. package/dist/chunk-GI3UFGRQ.js +1 -0
  24. package/dist/chunk-GT2ZLGF7.js +1 -0
  25. package/dist/chunk-HHCGQSD4.js +1 -0
  26. package/dist/chunk-IJLHPX35.js +1 -0
  27. package/dist/chunk-JDGEZ542.js +1 -0
  28. package/dist/chunk-LUKTHL6K.js +1 -0
  29. package/dist/chunk-MXNZMTC2.js +1 -0
  30. package/dist/chunk-MXWLCDFX.js +1 -0
  31. package/dist/chunk-O5WKNZ2C.js +1 -0
  32. package/dist/chunk-OKWG3PVH.js +1 -0
  33. package/dist/chunk-OWU22VXP.js +1 -0
  34. package/dist/chunk-POIQGEZM.js +1 -0
  35. package/dist/chunk-RI3E7GBN.js +1 -0
  36. package/dist/chunk-SMKCBUJL.js +1 -0
  37. package/dist/chunk-TDLIXFDT.js +1 -0
  38. package/dist/chunk-U6TYL2IJ.js +1 -0
  39. package/dist/chunk-URUKV6NC.js +1 -0
  40. package/dist/chunk-V5K2JLC7.js +1 -0
  41. package/dist/client/index.cjs +1 -357
  42. package/dist/client/index.d.cts +37 -3
  43. package/dist/client/index.d.ts +37 -3
  44. package/dist/client/index.js +1 -15
  45. package/dist/core/index.cjs +1 -1605
  46. package/dist/core/index.d.cts +5 -4
  47. package/dist/core/index.d.ts +5 -4
  48. package/dist/core/index.js +1 -139
  49. package/dist/core/ocr/worker.bundle.js +42 -0
  50. package/dist/core/ocr/worker.cjs +42 -0
  51. package/dist/core/ocr/worker.d.cts +84 -0
  52. package/dist/core/ocr/worker.d.ts +84 -0
  53. package/dist/core/ocr/worker.js +41 -0
  54. package/dist/core/v3/detect-worker.cjs +1 -392
  55. package/dist/core/v3/detect-worker.d.cts +1 -1
  56. package/dist/core/v3/detect-worker.d.ts +1 -1
  57. package/dist/core/v3/detect-worker.js +1 -13
  58. package/dist/create-document-capture-FV4XGUKQ.js +1 -0
  59. package/dist/create-portrait-capture-C462EIB6.js +1 -0
  60. package/dist/create-verification-CmJzn7sq.d.ts +3041 -0
  61. package/dist/create-verification-CzLrQjeM.d.cts +3041 -0
  62. package/dist/{detect-worker-CKXHlXx9.d.cts → detect-worker-DclNxkZT.d.cts} +6 -0
  63. package/dist/{detect-worker-CKXHlXx9.d.ts → detect-worker-DclNxkZT.d.ts} +6 -0
  64. package/dist/detector-scanic-YCDNLCGV.js +1 -0
  65. package/dist/icao-gate-BeznQECA.d.cts +500 -0
  66. package/dist/icao-gate-Bw5sQVlt.d.ts +500 -0
  67. package/dist/icao-gate-PWBMKRGC.js +1 -0
  68. package/dist/icao-tuning-4GGVX6B4.js +1 -0
  69. package/dist/index.cjs +1 -2580
  70. package/dist/index.d.cts +84 -5
  71. package/dist/index.d.ts +84 -5
  72. package/dist/index.js +1 -28
  73. package/dist/internal/index.cjs +1 -4110
  74. package/dist/internal/index.d.cts +364 -324
  75. package/dist/internal/index.d.ts +364 -324
  76. package/dist/internal/index.js +1 -647
  77. package/dist/keyframe-rank-YAJLYJYF.js +1 -0
  78. package/dist/landmarker-KB7LVXAU.js +1 -0
  79. package/dist/mrz-band-VYHOTDHY.js +1 -0
  80. package/dist/plan-runner-ZVAY4FSB.js +1 -0
  81. package/dist/popup/index.cjs +1 -76
  82. package/dist/popup/index.d.cts +7 -1
  83. package/dist/popup/index.d.ts +7 -1
  84. package/dist/popup/index.js +1 -11
  85. package/dist/scanic-ml-stub-KW7IZHUT.js +1 -0
  86. package/dist/segmenter-USLNBX65.js +1 -0
  87. package/dist/turnstile-FATNZ4AG.js +1 -0
  88. package/dist/types-BWyAHKt_.d.cts +1435 -0
  89. package/dist/types-BWyAHKt_.d.ts +1435 -0
  90. package/package.json +25 -10
  91. package/sbom.cdx.json +195 -0
  92. package/dist/capture-constraints-BujkZcfb.d.cts +0 -21
  93. package/dist/capture-constraints-BujkZcfb.d.ts +0 -21
  94. package/dist/chunk-LOTAJDRE.js +0 -1094
  95. package/dist/chunk-LOTAJDRE.js.map +0 -1
  96. package/dist/chunk-MWNFSNMP.js +0 -52
  97. package/dist/chunk-MWNFSNMP.js.map +0 -1
  98. package/dist/chunk-NILNKLK6.js +0 -50
  99. package/dist/chunk-NILNKLK6.js.map +0 -1
  100. package/dist/chunk-NU4YOLCN.js +0 -796
  101. package/dist/chunk-NU4YOLCN.js.map +0 -1
  102. package/dist/chunk-NWF46H7K.js +0 -359
  103. package/dist/chunk-NWF46H7K.js.map +0 -1
  104. package/dist/chunk-WY6U7AIK.js +0 -193
  105. package/dist/chunk-WY6U7AIK.js.map +0 -1
  106. package/dist/chunk-YVFF4Q4G.js +0 -327
  107. package/dist/chunk-YVFF4Q4G.js.map +0 -1
  108. package/dist/client/index.cjs.map +0 -1
  109. package/dist/client/index.js.map +0 -1
  110. package/dist/core/index.cjs.map +0 -1
  111. package/dist/core/index.js.map +0 -1
  112. package/dist/core/v3/detect-worker.cjs.map +0 -1
  113. package/dist/core/v3/detect-worker.js.map +0 -1
  114. package/dist/create-verification--ldwakXV.d.cts +0 -341
  115. package/dist/create-verification-BlAPWeW5.d.ts +0 -341
  116. package/dist/detector-scanic-4C6IEW2K.js +0 -787
  117. package/dist/detector-scanic-4C6IEW2K.js.map +0 -1
  118. package/dist/hosted-client-BpvBqu9f.d.cts +0 -408
  119. package/dist/hosted-client-BpvBqu9f.d.ts +0 -408
  120. package/dist/index.cjs.map +0 -1
  121. package/dist/index.js.map +0 -1
  122. package/dist/internal/index.cjs.map +0 -1
  123. package/dist/internal/index.js.map +0 -1
  124. package/dist/popup/index.cjs.map +0 -1
  125. package/dist/popup/index.js.map +0 -1
  126. package/dist/scanic-ml-stub-S2OZ6HEF.js +0 -10
  127. package/dist/scanic-ml-stub-S2OZ6HEF.js.map +0 -1
@@ -0,0 +1,1435 @@
1
+ /** Server-tunable thresholds (`capture.icao.backgroundCheck`); defaults below. */
2
+ interface BackgroundCheckTuning {
3
+ /** Run the check at all (ICAO on). Default `true`. */
4
+ enabled: boolean;
5
+ /** Measurements per second (the face gate runs faster). Default 3. */
6
+ hz: number;
7
+ /** The segmenter must load within this window, else the strip fallback. Default 8000 ms. */
8
+ segmenterTimeoutMs: number;
9
+ /** A segmentation slower than this (moving average) switches to the strip fallback. Default 120 ms. */
10
+ segmenterBudgetMs: number;
11
+ /** Person confidence at or above this is the person (excluded). Default 0.5. */
12
+ maskThreshold: number;
13
+ /** Max RMS colour standard deviation (0..255). Default 28. */
14
+ maxColorStd: number;
15
+ /** Max share of textured neighbour pairs (0..1). Default 0.08. */
16
+ maxEdgeDensity: number;
17
+ /** Luma step (0..255) that counts as an edge. Default 24. */
18
+ edgeLuma: number;
19
+ /** Max left/right or top/bottom brightness difference (0..1). Default 0.18. */
20
+ maxGradient: number;
21
+ /** Fewer background pixels than this = not measurable (never blocks). Default 300. */
22
+ minPixels: number;
23
+ /** A non-uniform background holds the shot at most this long, then the shot proceeds. Default 4000 ms. */
24
+ timeoutMs: number;
25
+ }
26
+ /** Person confidence per pixel (0..1 floats, or 0..255 bytes), any resolution (scaled to the frame). */
27
+ interface PersonMask {
28
+ data: Float32Array | Uint8Array | Uint8ClampedArray;
29
+ width: number;
30
+ height: number;
31
+ }
32
+ /** One measurement — numbers only (telemetry and the `gate` block). */
33
+ interface BackgroundUniformity {
34
+ method: "segmenter" | "strip";
35
+ uniform: boolean;
36
+ colorStd: number;
37
+ edgeDensity: number;
38
+ gradient: number;
39
+ /** Background pixels measured (after sampling). */
40
+ pixels: number;
41
+ }
42
+
43
+ /** The device (coaching) limits of each profile — the server limits moved towards strict. */
44
+ declare const ICAO_DEVICE_LIMITS: {
45
+ readonly id_document: {
46
+ readonly pose: {
47
+ readonly yawDeg: 7;
48
+ readonly pitchDeg: 7;
49
+ readonly rollDeg: 5;
50
+ readonly pitchOffsetDeg: 4;
51
+ };
52
+ readonly eyes: {
53
+ readonly relativeMin: 0.62;
54
+ readonly blinkMax: 0.48;
55
+ };
56
+ readonly mouth: {
57
+ readonly jawOpenMax: 0.13;
58
+ readonly smileMax: 0.28;
59
+ readonly puckerMax: 0.28;
60
+ };
61
+ readonly lighting: {
62
+ readonly faceLuma: readonly [95, 185];
63
+ readonly halfRatio: readonly [0.77, 1.31];
64
+ readonly clippedMax: 0.015;
65
+ };
66
+ readonly background: {
67
+ readonly required: true;
68
+ readonly lumaMin: 165;
69
+ readonly lumaSdMax: 20;
70
+ };
71
+ readonly resolution: {
72
+ readonly minIodPx: 110;
73
+ readonly minWidth: 480;
74
+ readonly minHeight: 640;
75
+ };
76
+ };
77
+ readonly selfie: {
78
+ readonly pose: {
79
+ readonly yawDeg: 7;
80
+ readonly pitchDeg: 7;
81
+ readonly rollDeg: 7;
82
+ readonly pitchOffsetDeg: 4;
83
+ };
84
+ readonly eyes: {
85
+ readonly relativeMin: 0.62;
86
+ readonly blinkMax: 0.48;
87
+ };
88
+ readonly mouth: {
89
+ readonly jawOpenMax: 0.13;
90
+ readonly smileMax: 0.28;
91
+ readonly puckerMax: 0.28;
92
+ };
93
+ readonly lighting: {
94
+ readonly faceLuma: readonly [95, 185];
95
+ readonly halfRatio: readonly [0.77, 1.31];
96
+ readonly clippedMax: 0.015;
97
+ };
98
+ readonly background: {
99
+ readonly required: false;
100
+ readonly lumaMin: 165;
101
+ readonly lumaSdMax: 20;
102
+ };
103
+ readonly resolution: {
104
+ readonly minIodPx: 100;
105
+ readonly minWidth: 480;
106
+ readonly minHeight: 640;
107
+ };
108
+ };
109
+ };
110
+
111
+ /** The ICAO threshold set (`id_document`: ID photo; `selfie`: no background rule). */
112
+ type IcaoProfile = keyof typeof ICAO_DEVICE_LIMITS;
113
+ /** `capture.icao` as the server sends it (every field optional on the wire). */
114
+ interface IcaoCaptureTuning {
115
+ /** The threshold set these limits come from (default `id_document`; it also picks the fallbacks). */
116
+ profile?: "id_document" | "selfie";
117
+ yawDeg?: number;
118
+ pitchDeg?: number;
119
+ /**
120
+ * Subtracted from the measured pitch before `pitchDeg` applies (degrees). Where
121
+ * "looking straight" sits relative to the Landmarker's zero; kyc-portrait applies the
122
+ * same `PORTRAIT_POSE_PITCH_OFFSET_DEG`, so keep them equal (D9a, 2026-10-22).
123
+ */
124
+ pitchOffsetDeg?: number;
125
+ rollDeg?: number;
126
+ holdMs?: number;
127
+ /** `alert` policy: the clip starts this long after the face was accepted even if the ICAO gate is not ready (default 3000). */
128
+ alertGraceMs?: number;
129
+ eyes?: {
130
+ relativeMin?: number;
131
+ blinkMax?: number;
132
+ earMin?: number;
133
+ };
134
+ mouth?: {
135
+ jawOpenMax?: number;
136
+ smileMax?: number;
137
+ puckerMax?: number;
138
+ };
139
+ lighting?: {
140
+ faceLuma?: [number, number];
141
+ halfRatio?: [number, number];
142
+ clippedMax?: number;
143
+ };
144
+ /** `required: false` (the `selfie` profile): the background is not evaluated, coached or reported. */
145
+ background?: {
146
+ required?: boolean;
147
+ lumaMin?: number;
148
+ lumaSdMax?: number;
149
+ };
150
+ resolution?: {
151
+ minIodPx?: number;
152
+ minWidth?: number;
153
+ minHeight?: number;
154
+ };
155
+ /** Client-only knobs (no server field today; read when the server adds them). */
156
+ holdFrames?: number;
157
+ cadenceHz?: number;
158
+ baseline?: {
159
+ windowMs?: number;
160
+ minSamples?: number;
161
+ percentile?: number;
162
+ };
163
+ sharpnessMin?: number;
164
+ glare?: {
165
+ specularMax?: number;
166
+ };
167
+ softGraceMs?: number;
168
+ cropMargin?: number;
169
+ camera?: {
170
+ width?: number;
171
+ height?: number;
172
+ };
173
+ /**
174
+ * The client background-uniformity check (ID mode; defaults in
175
+ * core/portrait/background-uniformity.ts `BACKGROUND_CHECK_DEFAULTS`).
176
+ * Skipped entirely when `background.required` is false.
177
+ */
178
+ backgroundCheck?: Partial<BackgroundCheckTuning>;
179
+ }
180
+ /** Fully resolved limits the gate runs on. */
181
+ interface ResolvedIcaoTuning {
182
+ profile: IcaoProfile;
183
+ yawDeg: number;
184
+ pitchDeg: number;
185
+ pitchOffsetDeg: number;
186
+ rollDeg: number;
187
+ holdMs: number;
188
+ alertGraceMs: number;
189
+ eyes: {
190
+ relativeMin: number;
191
+ blinkMax: number;
192
+ };
193
+ mouth: {
194
+ jawOpenMax: number;
195
+ smileMax: number;
196
+ puckerMax: number;
197
+ };
198
+ lighting: {
199
+ faceLuma: [number, number];
200
+ halfRatio: [number, number];
201
+ clippedMax: number;
202
+ };
203
+ background: {
204
+ required: boolean;
205
+ lumaMin: number;
206
+ lumaSdMax: number;
207
+ };
208
+ resolution: {
209
+ minIodPx: number;
210
+ minWidth: number;
211
+ minHeight: number;
212
+ };
213
+ holdFrames: number;
214
+ cadenceHz: number;
215
+ baseline: {
216
+ windowMs: number;
217
+ minSamples: number;
218
+ percentile: number;
219
+ };
220
+ sharpnessMin: number;
221
+ glare: {
222
+ specularMax: number;
223
+ };
224
+ softGraceMs: number;
225
+ cropMargin: number;
226
+ camera: {
227
+ width: number;
228
+ height: number;
229
+ };
230
+ backgroundCheck: BackgroundCheckTuning;
231
+ /** The server's `capture.tuningVersion`, echoed on submit (`null` when absent). */
232
+ tuningVersion: string | null;
233
+ }
234
+ /** Bundled fallbacks: the `id_document` device limits (never looser than the server). */
235
+ declare const ICAO_FALLBACK: Omit<ResolvedIcaoTuning, "tuningVersion">;
236
+ /**
237
+ * Resolve `capture.icao` (any shape, possibly absent) over {@link ICAO_FALLBACK},
238
+ * field by field: an out-of-range or malformed field keeps its fallback.
239
+ */
240
+ declare function resolveIcaoTuning(raw: unknown, tuningVersion?: unknown): ResolvedIcaoTuning;
241
+
242
+ /** Session lifecycle status (spec §4 two-field status/outcome model). */
243
+ type SessionStatus = "created" | "in_progress" | "review_pending" | "completed" | "expired" | "failed";
244
+ /** Terminal verdict, orthogonal to `status`; `null` until terminal/review. */
245
+ type SessionOutcome = "approved" | "review" | "rejected";
246
+ /**
247
+ * What a finished session proved (spec 2026-10-29 §3.2): `1` a live, real
248
+ * person, `2` that person's identity, `3` an identity corroborated by an
249
+ * independent source; `0` on a rejected session.
250
+ */
251
+ type VerificationLevel = 0 | 1 | 2 | 3;
252
+ /** How a session's {@link VerificationLevel} was proved (spec 2026-10-29 §3.4). */
253
+ type VerificationAssurance = "live_only" | "live_unique" | "document_biometric" | "chip_biometric" | "registry_biometric" | "supplied_biometric" | "eid_authenticated";
254
+ /** Per-check seven-state machine (spec §4.3). */
255
+ type CheckState = "pending" | "input_required" | "processing" | "passed" | "failed" | "review" | "skipped";
256
+ /**
257
+ * The frozen check-type vocabulary (CHECK_TYPES). `phone_otp` joined in Task 13;
258
+ * `nfc_chip` (M-nfc) is read by the native SDKs only; `email_otp` (Plan 8,
259
+ * profile v2 §4.6.5) confirms an email address with a one-time code;
260
+ * `eid_auth` (SDK spec §3.2) is the national eID sign-in (Houwiyeti in MR).
261
+ */
262
+ type CheckType = "liveness" | "face_match" | "doc_ocr" | "population_registry" | "phone_otp" | "nfc_chip" | "email_otp" | "portrait_icao" | "eid_auth";
263
+ type LivenessReason = "no_face" | "media_unreadable" | "clip_too_short" | "spoof_detected" | "review_band" | "liveness_inconclusive" | "device_integrity_failed" | "mobile_required" | "uncalibrated_capture_channel" | "capture_back_camera" | "capture_not_upright" | "camera_unavailable";
264
+ type PopulationReason = "nni_not_found" | "nni_invalid" | "registry_unavailable" | "result_from_cache" | "nationality_not_allowed" | "underage" | "age_unverifiable" | "name_mismatch" | "birth_date_mismatch" | "nationality_mismatch" | "nni_recheck";
265
+ type FaceMatchReason = "no_face_source" | "no_face_reference" | "low_quality_reference" | "below_threshold" | "review_band" | "match_inconclusive" | "subject_revoked" | "probe_not_from_liveness";
266
+ type DocReason = "side_missing" | "mrz_checksum_failed" | "unreadable" | "expired_document" | "authenticity_review" | "document_authenticity" | "registry_mismatch" | "document_nni_mismatch" | "nationality_unreadable" | "document_type_not_accepted" | "nationality_not_allowed" | "underage" | "age_unverifiable" | "name_mismatch" | "birth_date_mismatch" | "nationality_mismatch" | "document_number_mismatch";
267
+ /**
268
+ * Profile v2 step 3 matching reasons: a field the partner sent at session
269
+ * create (`subject`) differs from the reference identity (document or
270
+ * registry). All four are final. `document_number_mismatch` is `doc_ocr` only.
271
+ */
272
+ type MatchReason = "name_mismatch" | "birth_date_mismatch" | "nationality_mismatch" | "document_number_mismatch";
273
+ /**
274
+ * Profile v2 step 4 decision-mode reasons (the app decides automatically
275
+ * instead of sending the case to human review). These park the step at
276
+ * `input_required` while attempts remain: `liveness_inconclusive` /
277
+ * `match_inconclusive` (middle score band) and `document_authenticity`
278
+ * (retake the original card). `mobile_required` is kept for compatibility:
279
+ * the backend now answers a non-phone capture with a request-level
280
+ * `409 mobile_required` (continue on a phone; nothing used, not billed).
281
+ */
282
+ type DecisionReason = "liveness_inconclusive" | "match_inconclusive" | "document_authenticity" | "mobile_required";
283
+ /**
284
+ * phone_otp reasons (Task 13). All transient — the caller fixes them by
285
+ * re-entering / resending: `otp_mismatch` (wrong or missing code),
286
+ * `otp_expired` (code lapsed or no active send), `otp_send_failed` (the OTP
287
+ * service was unreachable / a send returned no token).
288
+ */
289
+ type PhoneOtpReason = "otp_mismatch" | "otp_expired" | "otp_send_failed" | "otp_channel_unavailable" | "otp_destination_not_allowed" | "otp_rate_limited" | "otp_destination_unknown" | "otp_daily_cap_reached";
290
+ /**
291
+ * email_otp reasons (Plan 8, profile v2 §4.6.5). All transient: a wrong or
292
+ * expired code, a send outage, too many sends, an address that cannot receive
293
+ * mail (`email_invalid`), or a disposable address the app blocks
294
+ * (`email_disposable`) — the person enters another address or resends.
295
+ */
296
+ type EmailOtpReason = "otp_mismatch" | "otp_expired" | "otp_send_failed" | "otp_rate_limited" | "email_invalid" | "email_disposable" | "otp_daily_cap_reached";
297
+ /**
298
+ * nfc_chip reasons (M-nfc, SDK spec §4.3). Native SDKs read the chip; the web
299
+ * never does — on web the step arrives `skipped` (`platform_unsupported`) or
300
+ * the session shows `failureReason: 'platform_unsupported'`.
301
+ */
302
+ type NfcChipReason = "chip_read_failed" | "chip_access_denied" | "chip_parse_failed" | "chip_not_present" | "nfc_unavailable" | "chip_document_mismatch" | "chip_integrity_failed" | "registry_mismatch" | "document_nni_mismatch" | "platform_unsupported";
303
+ /**
304
+ * eid_auth reasons (SDK spec §3.2, generic national eID; Houwiyeti in MR).
305
+ * Retryable: `eid_identifier_invalid` (re-enter the number), `eid_code_invalid`
306
+ * (re-enter the code, see `eid.codeAttemptsRemaining`), `eid_code_expired`
307
+ * (ask for a new code), `eid_unavailable` (the provider is down; try again or
308
+ * use the camera), `eid_resend_too_soon` (wait for `eid.resendAvailableAt`),
309
+ * `eid_resend_limit` (no more codes; type the last code received).
310
+ * Final: `eid_locked` (too many wrong codes), `eid_not_enrolled` (the number
311
+ * has no account in the provider's app).
312
+ * With `eid_not_enrolled`, `eid_unavailable` or `eid_locked` the person may
313
+ * switch to the camera path when the session offers it.
314
+ */
315
+ type EidReason = "eid_identifier_invalid" | "eid_code_invalid" | "eid_code_expired" | "eid_locked" | "eid_not_enrolled" | "eid_unavailable" | "eid_resend_too_soon" | "eid_resend_limit";
316
+ /**
317
+ * Any frozen reason code. The backend declares the field `string`, but the
318
+ * taxonomy is frozen (do-not-drift) — the union IS the contract. NB: liveness
319
+ * and face_match both carry `review_band`.
320
+ */
321
+ type CheckReason = LivenessReason | PopulationReason | FaceMatchReason | DocReason | PhoneOtpReason | EmailOtpReason | NfcChipReason | PortraitIcaoReason | EidReason
322
+ /**
323
+ * Spec 2026-10-27 (Sandbox testers), tester-bound sessions only:
324
+ * `tester_document_mismatch` (doc_ocr, nfc_chip) when the document read is
325
+ * not the bound tester's; `tester_phone_mismatch` (phone_otp) when the
326
+ * number is not the one the tester enrolled with.
327
+ */
328
+ | "tester_document_mismatch" | "tester_phone_mismatch";
329
+ /**
330
+ * Session-level failure reasons: the session was stopped by a policy gate,
331
+ * not by a failed check. All are terminal (no retry on this session):
332
+ * - `location_not_allowed` / `anonymizer_blocked` (profile v2 step 2): the
333
+ * person's IP location is not allowed, or an anonymizer (VPN / proxy / Tor)
334
+ * was detected while the app blocks them;
335
+ * - `capture_tampered` (step 4): the device reported a tampered capture
336
+ * (virtual camera, hooking, emulator…) while the app blocks it;
337
+ * - `device_velocity_exceeded` (step 4): this device already verified too
338
+ * many different people while the app blocks it;
339
+ * - `device_cooldown` (step 4): this device had too many rejected sessions —
340
+ * {@link HostedSessionView.retryAfter} says when it may try again;
341
+ * - `platform_unsupported` (M-nfc): a chip read is required and this client
342
+ * can't read one (web); the session stays open for a native app.
343
+ */
344
+ type SessionFailureReason = "location_not_allowed" | "anonymizer_blocked" | "capture_tampered" | "device_velocity_exceeded" | "device_cooldown" | "platform_unsupported";
345
+ /**
346
+ * The profile-v2 policy reasons a session can end on: the two session-level
347
+ * reasons plus the failed check's policy reasons (`document_type_not_accepted`,
348
+ * `nationality_not_allowed`, `underage`, `age_unverifiable`,
349
+ * `document_nni_mismatch`).
350
+ */
351
+ type PolicyFailureReason = SessionFailureReason | "document_type_not_accepted" | "nationality_not_allowed" | "underage" | "age_unverifiable" | "document_nni_mismatch" | "camera_unavailable";
352
+ /**
353
+ * Why the person has no camera (spec 2026-10-29 §3.4, 2026-10-30): `denied` when the camera permission was refused,
354
+ * `no_camera` when there is no usable camera (none found, an insecure page or a browser that cannot capture).
355
+ */
356
+ type CameraUnavailableCause = "denied" | "no_camera";
357
+ /**
358
+ * How the person proves their identity when the app makes the document
359
+ * optional for registry nationals (profile v2 step 3): type their national
360
+ * number (NNI) and skip the document, or photograph their document.
361
+ * `document_chip` is offered only to native clients with NFC (M-nfc).
362
+ * `national_eid` (SDK spec §3.2) signs in with the country's national eID
363
+ * (Houwiyeti in MR) instead of the camera path — see
364
+ * {@link MethodChoiceView.nationalEid}.
365
+ */
366
+ type IdentityMethod = "national_number" | "document_photo" | "document_chip" | "national_eid";
367
+ /**
368
+ * The national eID provider a session offers (`MethodChoiceView.nationalEid`).
369
+ * `provider` is `{ISO2}.{provider}` (e.g. `MR.houwiyeti`); `providerName` is
370
+ * the display name ("Houwiyeti").
371
+ */
372
+ interface NationalEidOption {
373
+ provider: string;
374
+ providerName: string;
375
+ /** ISO 3166-1 alpha-2 country of the provider. */
376
+ country: string;
377
+ /**
378
+ * What follows a passed eID (flow model 2026-10-23): `end` (the session ends,
379
+ * the default) or `continue` (the live photo follows). Absent on older APIs = `end`.
380
+ */
381
+ afterPass?: EidAfterPass;
382
+ }
383
+ /** What follows a passed national eID (`nationalEid.afterPass`). */
384
+ type EidAfterPass = "end" | "continue";
385
+ /**
386
+ * The section a step belongs to (flow model 2026-10-23, SDK spec §3.7): Step 1
387
+ * `contact`, Step 2 `identity`, Step 3 `live_photo`. Open: a value this SDK
388
+ * does not know is kept as is, so a client still places the step.
389
+ */
390
+ type StepSection = "contact" | "identity" | "live_photo" | "screening" | (string & {});
391
+ /** A contact channel of a contact choice (`phone_otp` → `phone`, `email_otp` → `email`). */
392
+ type ContactChannel = "phone" | "email";
393
+ /**
394
+ * @deprecated Sekyro flows: the contact choice is `plan.choice` (kind `contact`,
395
+ * {@link PlanChoiceView}); the view no longer carries this shape.
396
+ */
397
+ interface OtpChoiceView {
398
+ options: ContactChannel[];
399
+ selected: ContactChannel | null;
400
+ locked: boolean;
401
+ }
402
+ /** The flow version a session runs (`HostedSessionView.flow`). */
403
+ interface HostedFlowRef {
404
+ id: string;
405
+ slug: string;
406
+ version: number;
407
+ }
408
+ /** The kind of a choice node (Sekyro flows §7.4); a newer server's kind is kept as is. */
409
+ type PlanChoiceKind = "identity_method" | "contact" | "generic" | (string & {});
410
+ /** One option of a choice node, in the server's display order. */
411
+ interface PlanChoiceOption {
412
+ /** The option id sent back with {@link HostedClient.choose} (`document`, `registry`, `phone`, …). */
413
+ id: string;
414
+ /** The service of the option's lane (`document`, `nfc`, `population_registry`, `national_eid`, `phone_otp`, `email_otp`, …). */
415
+ service: string;
416
+ /** Unavailable options are omitted by the server; always `true` when listed. */
417
+ available: boolean;
418
+ /** `national_eid` options: the provider ("Verify with Houwiyeti"); absent or `null` otherwise and on older APIs. */
419
+ nationalEid?: NationalEidOption | null;
420
+ }
421
+ /** `plan.choice`: the choice the person makes now (or may still switch, while `locked` is false). */
422
+ interface PlanChoiceView {
423
+ nodeId: string;
424
+ kind: PlanChoiceKind;
425
+ /** The chosen option id, `null` before a pick. */
426
+ selected: string | null;
427
+ /** The choice can no longer change (a submission into the chosen lane, or the option settled). */
428
+ locked: boolean;
429
+ options: PlanChoiceOption[];
430
+ }
431
+ /** Submissions used on a step and its cap (remaining = `max - used`). */
432
+ interface PlanAttempts {
433
+ used: number;
434
+ max: number;
435
+ }
436
+ /**
437
+ * A step of the plan (a visited node or the current one, never an untaken lane):
438
+ * its node id, service and state plus today's per-type extras (`otp`, `emailOtp`,
439
+ * `eid`, `nfc`, `docCapture`, `nniFromDocument`, `reason`, `icao`, `requiresMobile`, …).
440
+ * A node with two checks yields two steps (`n_live` liveness, `n_live.icao` the ICAO portrait).
441
+ */
442
+ interface PlanStepView extends Omit<HostedStepView, "checkType" | "attemptsRemaining" | "section"> {
443
+ /** The node id (`n_doc`), stable across views; `<node>.icao` for the ICAO portrait of a liveness node. */
444
+ id: string;
445
+ /** The catalog service of the node (`document`, `liveness`, `summary_confirm`, …). */
446
+ service: string;
447
+ /** The check this step submits (`doc_ocr`, `portrait_icao`, `identity_confirm`, …). */
448
+ checkType: CheckType | (string & {});
449
+ section: StepSection;
450
+ attempts: PlanAttempts;
451
+ }
452
+ /** A segment of the progress bar (`plan.sections`): the sections still possible on any remaining path. */
453
+ interface PlanSectionView {
454
+ id: StepSection;
455
+ state: "done" | "current" | "upcoming";
456
+ }
457
+ /** `HostedSessionView.plan` (Sekyro flows §8.1). */
458
+ interface HostedPlanView {
459
+ /** A choice node id (`plan.choice.nodeId`) or a step id; `null` while nothing waits on the person. */
460
+ current: string | null;
461
+ /** Present while `current` is a choice (and, on newer servers, while its lane can still be switched). */
462
+ choice?: PlanChoiceView;
463
+ steps: PlanStepView[];
464
+ sections: PlanSectionView[];
465
+ }
466
+ /** Where the identity summary's data came from. */
467
+ type IdentitySummarySource = "registry" | "document" | "chip";
468
+ /**
469
+ * Step 2b summary and confirm (`HostedSessionView.identitySummary`): the
470
+ * identity data read so far, shown to the person before the live photo. Only
471
+ * on the session-token view and only while the confirmation is pending; masks
472
+ * keep the last 4 characters. Never log or store these values.
473
+ */
474
+ interface IdentitySummaryView {
475
+ /**
476
+ * `full` (document / chip: the record and the photo) or `partial` (the
477
+ * registry from a typed NNI: the short name "Mohamed S.", the birth year,
478
+ * the NNI's last 4, no photo).
479
+ */
480
+ kind: "full" | "partial" | (string & {});
481
+ source: IdentitySummarySource | (string & {});
482
+ /** The full name (`full`), or the short form "Mohamed S." (`partial`). */
483
+ fullName?: string;
484
+ /** `YYYY-MM-DD` (`full`). */
485
+ birthDate?: string;
486
+ /** `YYYY` (`partial`). */
487
+ birthYear?: string;
488
+ /** ISO 3166-1 alpha-2 (or alpha-3) nationality. */
489
+ nationality?: string;
490
+ documentType?: string;
491
+ documentNumberMasked?: string;
492
+ nniMasked?: string;
493
+ /** `YYYY-MM-DD`. */
494
+ expiryDate?: string;
495
+ /** A portrait can be fetched ({@link HostedClient.identityPortrait}). */
496
+ portrait: {
497
+ available: boolean;
498
+ };
499
+ /** A retake is still possible (attempts left, not a `supplied` summary). */
500
+ retakeAvailable: boolean;
501
+ /** What a retake re-opens. */
502
+ retakeTarget?: "document" | "national_number" | (string & {});
503
+ }
504
+ /** The answer to the identity summary ({@link HostedClient.confirmIdentity}). */
505
+ type IdentityConfirmDecision = "confirm" | "retake";
506
+ /**
507
+ * The pending identity-method choice in the 0.1 vocabulary, read from
508
+ * `plan.choice` (`kind: identity_method`): `document` → `document_photo`,
509
+ * `nfc` → `document_chip`, `population_registry` → `national_number`,
510
+ * `national_eid` → `national_eid`. See {@link Verification.methodChoice}.
511
+ */
512
+ interface MethodChoiceView {
513
+ /** The session offers the choice (the app's document mode is `optional`). */
514
+ available: boolean;
515
+ /** The chosen method, or `null` while the person has not chosen. */
516
+ selected: IdentityMethod | null;
517
+ /** The methods to offer, in display order (`national_eid` first when offered). */
518
+ options: IdentityMethod[];
519
+ /**
520
+ * The national eID provider behind the `national_eid` option ("Verify with
521
+ * Houwiyeti"). Absent when the option is not offered (and on older APIs).
522
+ */
523
+ nationalEid?: NationalEidOption;
524
+ }
525
+ /** A document type the backend reads (kyc-docs-v2 vocabulary; `carte_identite` = identity card of any issuer). */
526
+ type AcceptedDocumentType = "carte_identite" | "passport" | "residence_permit";
527
+ /**
528
+ * Accepted document types per issuing country (profile v2 §5.3a): an issuer
529
+ * uses `byIssuer[iso2] ?? default`; `"*"` = every type.
530
+ */
531
+ interface HostedAcceptedDocuments {
532
+ default: "*" | AcceptedDocumentType[];
533
+ byIssuer?: Record<string, AcceptedDocumentType[]>;
534
+ }
535
+ /**
536
+ * phone_otp DISPLAY-SAFE surface (Task 16). The backend stashes the OTP
537
+ * service `verifToken` on the check's persisted outputs (the doc_ocr partial
538
+ * mechanism), but that token is NEVER projected here — only the fields the
539
+ * hosted OTP step renders. `numberSource` (org-authored config) drives the
540
+ * send-phase UI (prefilled display vs entry); the rest appear ONLY once a send
541
+ * has parked the check (`sentToMasked` present ⇒ verify phase).
542
+ */
543
+ interface HostedOtpView {
544
+ /**
545
+ * Per-step `config.numberSource` — drives the send-phase UI (prefilled
546
+ * display vs entry). Narrowed to the frontend contract; the backend field is
547
+ * `string` (dynamic config) but the projection only ever emits these three.
548
+ */
549
+ numberSource?: "prefilled" | "user_entered" | "prefilled_or_entered";
550
+ /** Masked target the last send went to (e.g. `+222 ** ** 34 56`); absent pre-send. */
551
+ sentToMasked?: string;
552
+ /** Delivery channel of the last send. */
553
+ channel?: "sms" | "whatsapp";
554
+ /** ISO-8601 OTP expiry from the last send — drives the verify-phase countdown. */
555
+ expiresAt?: string;
556
+ /**
557
+ * Profile v2 §4.6.4: the channels the person may choose from, in display
558
+ * order (WhatsApp first; a channel the org or app turned off is absent).
559
+ * Absent on a session created before channel choice (no picker; SMS).
560
+ */
561
+ channels?: ("whatsapp" | "sms")[];
562
+ /** ISO-8601 end of the server-side resend cooldown (after a send). */
563
+ resendAvailableAt?: string;
564
+ }
565
+ /**
566
+ * email_otp DISPLAY-SAFE surface (Plan 8, profile v2 §4.6.5): never the
567
+ * provider handle, never the address (only its mask).
568
+ */
569
+ interface HostedEmailOtpView {
570
+ /** Where the address comes from; drives the send-phase UI (notice vs entry). */
571
+ emailSource?: "prefilled" | "user_entered" | "prefilled_or_entered";
572
+ /** Masked target of the last send (e.g. `a•••@e•••.com`); absent pre-send. */
573
+ sentToMasked?: string;
574
+ /** ISO-8601 code expiry from the last send. */
575
+ expiresAt?: string;
576
+ /** ISO-8601 end of the server-side resend cooldown (after a send). */
577
+ resendAvailableAt?: string;
578
+ }
579
+ /**
580
+ * portrait_icao reasons (SDK spec §4.9, ID mode). The first failing ICAO
581
+ * criterion; every one is retryable (re-run only the ICAO gate).
582
+ * `media_unreadable` (no report) is shared with liveness.
583
+ */
584
+ type PortraitIcaoReason = "icao_pose" | "icao_eyes" | "icao_mouth" | "icao_occlusion" | "icao_lighting" | "icao_background" | "icao_resolution" | "portrait_not_from_liveness";
585
+ /** One ICAO criterion of the server's portrait report (SDK spec §4.9). */
586
+ type IcaoCriterion = "pose" | "eyes" | "mouth" | "occlusion" | "glare" | "lighting" | "background" | "resolution";
587
+ /** The ICAO policy of a session's selfie (spec 2026-10-24 selfie ICAO policy §10). */
588
+ interface HostedIcaoPolicy {
589
+ /** `reject`: the gate blocks and the server asks for retakes; `alert`: coaching only, never blocking. */
590
+ policy: "reject" | "alert";
591
+ /** The threshold set: `id_document` (ID photo, uniform background) or `selfie` (no background rule). */
592
+ profile: "id_document" | "selfie";
593
+ }
594
+ /** `HostedSessionView.portrait`. */
595
+ type HostedPortraitView = NonNullable<HostedSessionView["portrait"]>;
596
+ /** One row of the portrait_icao report: the server's measurement — coaching only. */
597
+ interface IcaoReportEntry {
598
+ criterion: IcaoCriterion;
599
+ value: number | null;
600
+ threshold: number | string | null;
601
+ pass: boolean;
602
+ }
603
+ /**
604
+ * eid_auth DISPLAY-SAFE surface (SDK spec §3.2): never the identifier, never
605
+ * the code. `awaiting` drives the screen: `identifier` (type the national
606
+ * number, unless `identifierBound`) → `code` (type the code shown in the
607
+ * provider's app).
608
+ */
609
+ interface HostedEidView {
610
+ /** `{ISO2}.{provider}`, e.g. `MR.houwiyeti`. */
611
+ provider: string;
612
+ /** Display name, e.g. "Houwiyeti". */
613
+ providerName: string;
614
+ /** ISO 3166-1 alpha-2 country of the provider. */
615
+ country: string;
616
+ /** `app_code`: the provider's app shows a code the person types here (the only challenge today). */
617
+ challenge: "app_code";
618
+ awaiting: "identifier" | "code";
619
+ /** The session is bound to the national number — `start` sends no identifier. */
620
+ identifierBound: boolean;
621
+ /** ISO-8601 expiry of the current code. */
622
+ expiresAt?: string;
623
+ /** ISO-8601 time from which a new code may be asked for. */
624
+ resendAvailableAt?: string;
625
+ /** New codes the person may still ask for in this session. */
626
+ resendsRemaining?: number;
627
+ /** Wrong codes left before `eid_locked`. */
628
+ codeAttemptsRemaining?: number;
629
+ /** What follows a pass (flow model 2026-10-23); absent = `end`. */
630
+ afterPass?: EidAfterPass;
631
+ }
632
+ /** `nfc_chip` step hints (M-nfc). `chipHint` is UI copy only, never a gate. */
633
+ interface NfcStepView {
634
+ mode: "preferred" | "mandatory";
635
+ access: ("PACE" | "BAC")[];
636
+ optionalDataGroups: ("DG11" | "DG12" | "DG13")[];
637
+ chipHint: {
638
+ default: Record<string, true | "unknown">;
639
+ byIssuer: Record<string, Record<string, true | "unknown">>;
640
+ };
641
+ /**
642
+ * Sekyro flows §7.7: where the chip key's MRZ comes from — `capture` (an
643
+ * MRZ-only scan before the chip read) or `document` (the earlier document step).
644
+ */
645
+ mrz?: {
646
+ source: "capture" | "document" | (string & {});
647
+ };
648
+ }
649
+ /**
650
+ * Liveness v7 §5.2: the retake hint's closed set (service `pipeline/retake_hint.py`, backend
651
+ * provenance picklist, copy keys `hints.*`): `appearance` (pad, deepfake, temporal signals),
652
+ * `motion` (no parallax or a high motion residual), `lighting` (low face luminance),
653
+ * `framing` (a small or clipped face box).
654
+ */
655
+ type RetakeHint = "appearance" | "motion" | "lighting" | "framing";
656
+ /**
657
+ * Per-check projection in a {@link HostedSessionView} — the spec'd hosted step
658
+ * shape. NEVER carries `calibratedScore` or the raw check `outputs`; the only
659
+ * output-derived data is the phone_otp `HostedOtpView` display subset
660
+ * (masked number/channel/expiry — never the verifToken).
661
+ */
662
+ interface HostedStepView {
663
+ checkType: CheckType;
664
+ state: CheckState;
665
+ /** Frozen-taxonomy reason code explaining a `failed`/`review` state. */
666
+ reason?: CheckReason;
667
+ /**
668
+ * Liveness v7 §5.2: what to change for the next capture, on a liveness step parked at
669
+ * `input_required` (the signal that weighed most in the inconclusive score). Absent on older
670
+ * APIs, on decisive results and on the other checks: then the reason's generic copy applies.
671
+ */
672
+ retakeHint?: RetakeHint;
673
+ /**
674
+ * Spec 2026-10-27: a Sandbox check answered by simulation (no provider or
675
+ * model ran). Absent on Live, on real Sandbox checks and on older APIs.
676
+ */
677
+ simulated?: boolean;
678
+ /**
679
+ * Submissions the page may still make for this check (`max(0, cap - attempts)`).
680
+ * Meaningful only while the check is executable — a finalized check may still
681
+ * report more than 0, but re-submitting it 409s regardless.
682
+ */
683
+ attemptsRemaining: number;
684
+ /** doc_ocr only: sides already accepted into the partial accumulator (['recto'] or ['verso']). */
685
+ acceptedSides?: ("recto" | "verso")[];
686
+ /** phone_otp only: the display-safe OTP send/config surface (never the verifToken). */
687
+ otp?: HostedOtpView;
688
+ /** email_otp only: the display-safe email send surface (never the handle or the address). */
689
+ emailOtp?: HostedEmailOtpView;
690
+ /**
691
+ * The check failed after using all of its attempts — no retry is left.
692
+ * Absent on older APIs (treat absent as `false`).
693
+ */
694
+ attemptsExhausted?: boolean;
695
+ /**
696
+ * population_registry only: the session is not bound to an NNI, but the
697
+ * document step already read a valid one — the page submits the registry
698
+ * check with an EMPTY input (no NNI field) and the backend uses the
699
+ * document's number. Absent on older APIs.
700
+ */
701
+ nniFromDocument?: boolean;
702
+ /**
703
+ * liveness / face_match (profile v2 step 4, decision mode `automatic`): the
704
+ * capture must come from a phone — the liveness band is calibrated on
705
+ * mobile captures only. A desktop page hands the person off to their phone
706
+ * instead of capturing (a desktop submission answers `mobile_required`).
707
+ * Absent on older APIs and in `review` mode.
708
+ */
709
+ requiresMobile?: boolean;
710
+ /** nfc_chip only (M-nfc). */
711
+ nfc?: NfcStepView;
712
+ /** portrait_icao only (SDK spec §4.9): the last attempt's per-criterion report. */
713
+ icao?: {
714
+ report: IcaoReportEntry[];
715
+ };
716
+ /** eid_auth only (SDK spec §3.2): the display-safe eID surface. */
717
+ eid?: HostedEidView;
718
+ /**
719
+ * The section of the flow this step belongs to (flow model 2026-10-23).
720
+ * Absent on older APIs (derive it from the check type).
721
+ */
722
+ section?: StepSection;
723
+ /**
724
+ * doc_ocr only, on an open step: the client reads the chip next, so the MRZ is
725
+ * read on device for the chip key (`mrz_for_chip`). Native NFC clients only.
726
+ */
727
+ docCapture?: {
728
+ mode: "mrz_for_chip" | (string & {});
729
+ };
730
+ }
731
+ /** A locale the Sekyro AI-hosted voice clips are recorded in. */
732
+ type HostedVoiceLocale = "ar" | "fr" | "en";
733
+ /**
734
+ * The session's Sekyro AI-hosted voice-guidance clips (the active clip set).
735
+ *
736
+ * `clips[locale]` maps a voice key (`fcv3.*`, the `@sekyro/react` voice-key
737
+ * namespace) to an ABSOLUTE URL on the Sekyro AI assets host
738
+ * (`https://assets.sekyro.ai/voice/<setId>/<locale>/<name>.mp3`; staging:
739
+ * `assets-staging.sekyro.ai`). URLs are immutable per `setId`. A locale or key
740
+ * may be missing — the player falls back to the device voice for it.
741
+ *
742
+ * A page with a Content-Security-Policy must allow the assets origin in
743
+ * `media-src` for the clips to play (see the partner web-SDK guide, CSP note).
744
+ */
745
+ interface HostedVoiceView {
746
+ /** Identifier of the active clip set (part of every clip URL). */
747
+ setId: string;
748
+ /** Per-locale map of voice key (`fcv3.*`) → absolute clip URL. */
749
+ clips: {
750
+ readonly [L in HostedVoiceLocale]?: Readonly<Record<string, string>>;
751
+ };
752
+ }
753
+ /** A branding colour key (each value is `#rrggbb`). */
754
+ type HostedBrandingColorKey = "brand" | "brandFg" | "bg" | "surface" | "fg" | "fgMuted" | "danger" | "success" | "warning";
755
+ /**
756
+ * The org / app branding of a session (`HostedSessionView.branding`): only the
757
+ * fields set in the dashboard, merged per field (app over org). A field the
758
+ * org and app left unset is ABSENT — keep your default for it; the whole
759
+ * object is absent when nothing is set. `logoUrl` is a short-lived signed URL
760
+ * (15 minutes).
761
+ */
762
+ interface HostedBranding {
763
+ /** Signed URL of the logo (PNG or sanitized SVG); absent when none is set. */
764
+ logoUrl?: string;
765
+ /** Colours as `#rrggbb`. */
766
+ colors?: Partial<Record<HostedBrandingColorKey, string>>;
767
+ /** Corner radius step. */
768
+ radius?: "none" | "sm" | "md" | "lg" | "full";
769
+ /** Font choice (system fallbacks when the font is not installed). */
770
+ fontFamily?: "system" | "inter" | "ibm-plex-sans-arabic" | "noto-sans-arabic" | "roboto";
771
+ /**
772
+ * Spec 2026-10-29 D16: the org hides the "Verified by Sekyro AI" attribution (hosted frame and SDK footer).
773
+ * Present (true) only then; absent on older APIs.
774
+ */
775
+ hideAttribution?: boolean;
776
+ }
777
+ /**
778
+ * Token-addressed hosted-page bootstrap (`GET /hosted/session`). A separate
779
+ * shape from the partner `SessionView`: `sessionId` instead of `id`,
780
+ * hosted step hints, the consent flag, and the org display name (may be `''`
781
+ * when the org lookup degrades).
782
+ */
783
+ /**
784
+ * Server-delivered capture tuning (`HostedSessionView.capture`, SDK spec §3.5).
785
+ * Coaching values only. `@sekyro/web` does not apply it yet (its built-in v3
786
+ * values stay in force until the adopting minor release); native SDKs apply it
787
+ * field by field over their bundled fallbacks and ignore unknown fields.
788
+ */
789
+ interface HostedCaptureTuning {
790
+ tuningVersion?: string;
791
+ liveness?: HostedLivenessCaptureTuning;
792
+ document?: Record<string, unknown>;
793
+ /** SDK spec §5.4 ID mode: the strict ICAO gate's coaching limits (present with `portrait`). */
794
+ icao?: IcaoCaptureTuning;
795
+ /**
796
+ * Step 3 one-capture live photo (flow model 2026-10-23): one camera session
797
+ * records the clip AND a full-resolution still (long side at least
798
+ * `still.minLongSidePx`, JPEG `still.jpegQuality`).
799
+ */
800
+ livePhoto?: HostedLivePhotoTuning;
801
+ /**
802
+ * Who films the face, set in the flow (always present on current backends):
803
+ * - `self` — the person films themselves: front camera only, no camera
804
+ * choice, phone held upright;
805
+ * - `assisted` — an agent films the person: back camera by default, the
806
+ * front/back switch allowed, phone held upright.
807
+ * `@sekyro/web` enforces it on a capture bound to the session; an absent
808
+ * value falls back to {@link HostedCaptureTuning.cameraSwitch}, then `self`.
809
+ */
810
+ mode?: CaptureMode;
811
+ /**
812
+ * @deprecated Mirror of `mode === 'assisted'`, kept for older clients. Read
813
+ * {@link HostedCaptureTuning.mode}.
814
+ */
815
+ cameraSwitch?: boolean;
816
+ }
817
+ /**
818
+ * Who films the face (`HostedSessionView.capture.mode`, a flow setting):
819
+ * `self` (the person, front camera) or `assisted` (an agent, back camera).
820
+ */
821
+ type CaptureMode = "self" | "assisted";
822
+ /** `capture.livePhoto` (flow model 2026-10-23, Step 3). */
823
+ interface HostedLivePhotoTuning {
824
+ oneCapture: boolean;
825
+ still: {
826
+ minLongSidePx: number;
827
+ jpegQuality: number;
828
+ };
829
+ }
830
+ /**
831
+ * `capture.liveness`: the face gate's coaching values (open; web keeps its built-in v3 values) and, from liveness v7,
832
+ * the screen-ramp challenge the web SDK renders while the clip records.
833
+ */
834
+ interface HostedLivenessCaptureTuning {
835
+ [field: string]: unknown;
836
+ /**
837
+ * Liveness v7 §4.4: the server-issued screen-ramp challenge of this session. Absent (older backends, assisted
838
+ * sessions, the ramp switched off): no ramp is rendered and the submit carries no `screenRamp`.
839
+ */
840
+ screenRamp?: ScreenRampChallenge;
841
+ }
842
+ /**
843
+ * The closed palette of the screen ramp (liveness v7 §4.4). Each name maps to one fixed sRGB value in `@sekyro/web`
844
+ * (`screenRampColourValue`); the service verifies the clip against the same values.
845
+ */
846
+ type ScreenRampColour = 'rose' | 'peach' | 'sand' | 'mint' | 'sky' | 'lilac';
847
+ /**
848
+ * The screen-ramp challenge issued per session (liveness v7 §4.4, §4.5 item 1): three colours shown for 400 ms each,
849
+ * starting at `onsetsMs[i]` on the clip's own timeline (the backend jitters each onset inside its slot). The layer
850
+ * returns to transparent at 2,000 ms. The client renders exactly this and reports what it rendered
851
+ * ({@link ScreenRampReport}); the backend forwards the issued challenge to the model service.
852
+ */
853
+ interface ScreenRampChallenge {
854
+ /** Ties the report to the issued challenge (echoed in {@link ScreenRampReport.nonce}). */
855
+ nonce: string;
856
+ colours: [ScreenRampColour, ScreenRampColour, ScreenRampColour];
857
+ /** Whole ms on the clip timeline, ascending, each inside the 800 to 2,000 ms window. */
858
+ onsetsMs: [number, number, number];
859
+ /** The palette the colours were drawn from (informational; the client renders `colours`). */
860
+ palette: ScreenRampColour[];
861
+ }
862
+ /** One rendered colour change: `tMs` on the clip timeline (whole ms, ≥ 0). */
863
+ interface ScreenRampRendered {
864
+ tMs: number;
865
+ colour: ScreenRampColour;
866
+ }
867
+ /** `LivenessCaptureInput.screenRamp`: what the SDK rendered against the issued {@link ScreenRampChallenge}. */
868
+ interface ScreenRampReport {
869
+ nonce: string;
870
+ /** In render order, at most three entries. */
871
+ rendered: ScreenRampRendered[];
872
+ }
873
+ /**
874
+ * `LivenessCaptureInput.provenance` (liveness v7 §4.5 item 2): how the web capture was made. Signals only, no media,
875
+ * no raw device identifiers. The backend allowlists it into the capture metadata; the model service turns it into
876
+ * the `virtual_camera | capture_tampered | replay_suspected` signals with its own thresholds and label list.
877
+ */
878
+ interface CaptureProvenance {
879
+ /** The selected video track's `getSettings()`; `deviceIdHash` is the first 16 hex of SHA-256(deviceId). */
880
+ trackSettings: {
881
+ facingMode?: 'user' | 'environment' | 'left' | 'right';
882
+ frameRate?: number;
883
+ width?: number;
884
+ height?: number;
885
+ deviceIdHash?: string;
886
+ };
887
+ /** `MediaStreamTrack.getCapabilities` exists on this browser (absent on Firefox; virtual stacks often lack it). */
888
+ capabilitiesPresent: boolean;
889
+ /**
890
+ * The track label against the SDK's small list of virtual-camera products (`known_virtual`), the platform's own
891
+ * camera naming (`platform`), or anything else, an empty label included (`unknown`).
892
+ */
893
+ labelClass: 'known_virtual' | 'unknown' | 'platform';
894
+ /**
895
+ * `requestVideoFrameCallback` statistics over the recording: frames seen, mean and standard deviation of the
896
+ * inter-frame gap (ms), and the mean `presentationTime - captureTime` (ms) when the browser reports `captureTime`
897
+ * (null otherwise). All zero with `n: 0` when the browser has no `requestVideoFrameCallback`.
898
+ */
899
+ rvfc: {
900
+ n: number;
901
+ meanGapMs: number;
902
+ stdGapMs: number;
903
+ captureLatencyMs: number | null;
904
+ };
905
+ /** `getUserMedia` and `MediaStreamTrack.prototype.getSettings` are still native code (not replaced by a page script). */
906
+ prototypesIntact: boolean;
907
+ /**
908
+ * The engine ran this capture with a screen-ramp painter: a self capture handed the session's challenge with a
909
+ * `ramp` listener bound. `false` for a host that never binds `ramp`, an assisted capture, a keyframe-only capture
910
+ * or a session without a challenge. The backend keys `ramp_missing` on this flag, not on the SDK version: a
911
+ * `true` capture without `screenRamp` is missing, a `false` one is a client without the ramp.
912
+ */
913
+ rampPainter: boolean;
914
+ }
915
+ /**
916
+ * {@link HostedCaptureTuning} with the native-only document fields typed. The wire shape is
917
+ * the same; `HostedSessionView.capture` stays the open {@link HostedCaptureTuning} so existing
918
+ * consumers keep compiling. Narrow it where the typed fields are read:
919
+ * `const capture = view.capture as HostedNativeCaptureTuning | undefined`.
920
+ */
921
+ interface HostedNativeCaptureTuning extends HostedCaptureTuning {
922
+ document?: HostedDocumentCaptureTuning;
923
+ }
924
+ /**
925
+ * `capture.document`. Only the native-only fields the SDKs share a name for are typed;
926
+ * the rest (gate, aspect, upload, …) stay open. Web ignores the whole block.
927
+ */
928
+ interface HostedDocumentCaptureTuning {
929
+ [field: string]: unknown;
930
+ /** Native document scan machine thresholds (web does not read them). */
931
+ scan?: HostedDocumentScanTuning;
932
+ /** Native on-device OCR tuning (web ignores it; SDK spec §5.2). */
933
+ ocr?: HostedOcrTuning;
934
+ }
935
+ /** `capture.document.scan` — native scan thresholds; only the blur gate is typed here. */
936
+ interface HostedDocumentScanTuning {
937
+ [field: string]: unknown;
938
+ /** Blur gate: a captured photo whose native sharpness is under this is refused and retaken. */
939
+ blurRefuseSharpnessMax?: number;
940
+ }
941
+ /** `capture.document.ocr` — native on-device OCR tuning (web ignores it; SDK spec §5.2). */
942
+ interface HostedOcrTuning {
943
+ enabledOnline?: boolean;
944
+ enabledOffline?: boolean;
945
+ warmup?: boolean;
946
+ maxDeviceLatencyMs?: number;
947
+ deviceTimeoutMs?: number;
948
+ minAvailMemoryMb?: number;
949
+ minConfidenceForRetake?: number;
950
+ minSegmentsForRetake?: number;
951
+ submitGraceMs?: number;
952
+ reportSampleRate?: number;
953
+ readBudgetMs?: number;
954
+ classifyBudgetMs?: number;
955
+ deferArabicOnline?: boolean;
956
+ detectorLimit?: number;
957
+ detectorThreadsMax?: number;
958
+ recognizerThreads?: number;
959
+ recognitionWorkersMax?: number;
960
+ linesInFlight?: number;
961
+ widestLineFirst?: boolean;
962
+ scriptRouting?: boolean;
963
+ arabicColumnFirst?: boolean;
964
+ confidentLatinScore?: number;
965
+ minLatinLetters?: number;
966
+ arabicColumnStart?: number;
967
+ arabicOnlyScore?: number;
968
+ portraitProbeLimit?: number;
969
+ }
970
+ /** Native device attestation parameters (`HostedSessionView.integrity`, SDK spec §6.7). Web ignores it. */
971
+ interface HostedIntegrity {
972
+ mode: "off" | "signal" | "enforce";
973
+ android?: {
974
+ cloudProjectNumber: number;
975
+ };
976
+ ios?: {
977
+ appAttest: true;
978
+ };
979
+ }
980
+ interface HostedSessionView {
981
+ sessionId: string;
982
+ status: SessionStatus;
983
+ outcome: SessionOutcome | null;
984
+ /** ISO-8601 timestamp (Date on the server, string on the wire). */
985
+ expiresAt: string;
986
+ consentRecorded: boolean;
987
+ orgName: string;
988
+ /**
989
+ * The FIRST allowlisted web-SDK origin of the owning org (Task 12), or null
990
+ * when none is registered. The hosted page posts the SDK popup postMessage
991
+ * events (event name, sessionId and the level when known) to exactly this origin — never `'*'`.
992
+ * The backend declares it required (`string | null`); optional here so
993
+ * pre-Task-12 consumers/fixtures stay valid (additive field, always on the
994
+ * wire from Task 12 onward).
995
+ */
996
+ sdkOrigin?: string | null;
997
+ /**
998
+ * Cloudflare Turnstile site key the browser must solve an execute-mode
999
+ * challenge against before submitting `liveness` (Plan A Task 5): the org's
1000
+ * own widget key when the request origin is one of the org's allowlisted SDK
1001
+ * origins, else the hosted widget key, else `null`. `null` means the session
1002
+ * cannot be attested from the browser — the SDK sends `{sandbox: true}`,
1003
+ * which the backend honours ONLY on sandbox sessions (fails closed on live).
1004
+ */
1005
+ turnstileSiteKey: string | null;
1006
+ /**
1007
+ * A Sandbox (test) session: the hosted page marks it as a test session.
1008
+ * Optional: absent on an older backend.
1009
+ */
1010
+ sandbox?: boolean;
1011
+ /** Spec 2026-10-27: this session enrolls a Sandbox tester (the hosted page shows the removal link at the end). */
1012
+ testerEnrollment?: boolean;
1013
+ /**
1014
+ * The session was minted with a server-bound NNI (`POST /sessions`
1015
+ * `input.nni`, Plan A Task 2): `population_registry` is submitted with an
1016
+ * EMPTY input and the backend reads the sealed value. `false` means the
1017
+ * person must supply the NNI (hosted population form); the SDK never submits
1018
+ * the registry check on an unbound session. The VALUE is never exposed. The
1019
+ * backend declares it required; optional here so pre-Task-8 fixtures stay
1020
+ * valid (additive field, always on the wire from Task 8 onward).
1021
+ */
1022
+ nniBound?: boolean;
1023
+ /**
1024
+ * The Sekyro AI-hosted voice-guidance clips of this session, or `null` when no
1025
+ * clip set is active (the device voice is used). Optional: older APIs omit
1026
+ * the field — treat absent like `null`.
1027
+ */
1028
+ voice?: HostedVoiceView | null;
1029
+ /**
1030
+ * Why the session ended, when a profile-v2 policy stopped it: a
1031
+ * {@link SessionFailureReason}, or the failed check's reason when it is a
1032
+ * policy reason (eligibility, or `document_nni_mismatch`). Absent otherwise
1033
+ * (and on older APIs).
1034
+ */
1035
+ failureReason?: PolicyFailureReason;
1036
+ /**
1037
+ * The document types the person may pick, resolved for issuer `MR`,
1038
+ * `carte_identite`/`passport` only (older pickers). Absent on older APIs —
1039
+ * treat absent as both.
1040
+ */
1041
+ acceptedDocumentTypes?: AcceptedDocumentType[];
1042
+ /**
1043
+ * Accepted document types per issuing country — drives the issuer-first
1044
+ * picker. Absent on older APIs (fall back to `acceptedDocumentTypes` for MR).
1045
+ */
1046
+ acceptedDocuments?: HostedAcceptedDocuments;
1047
+ /**
1048
+ * ISO-8601 time from which this device may verify again — set with
1049
+ * `failureReason: 'device_cooldown'` (profile v2 step 4). Absent otherwise
1050
+ * (and on older APIs).
1051
+ */
1052
+ retryAfter?: string;
1053
+ /**
1054
+ * What the session proved, once it is terminal (spec 2026-10-29 §3.2);
1055
+ * `null` while it runs. Absent on older APIs.
1056
+ */
1057
+ level?: VerificationLevel | null;
1058
+ /** How the level was proved, once terminal; `null` while it runs. Absent on older APIs. */
1059
+ assurance?: VerificationAssurance | null;
1060
+ /** The subject (person) the session is linked to, once known. Absent on older APIs. */
1061
+ subjectId?: string;
1062
+ /**
1063
+ * A returning-user session (profile v2 step 5): the person verified before
1064
+ * and this session only confirms it is still them — liveness and a face
1065
+ * match against their stored photo. Hosts read it to say "Confirm it's
1066
+ * you". Absent on full sessions (and on older APIs).
1067
+ */
1068
+ returning?: true;
1069
+ /**
1070
+ * The org / app branding (settings spec §5.1). Absent on older APIs — keep
1071
+ * the default theme. Map it with `brandingToTheme()` from `@sekyro/react`.
1072
+ */
1073
+ branding?: HostedBranding;
1074
+ /** Capture coaching tuning (SDK spec §3.5). Absent on older APIs. */
1075
+ capture?: HostedCaptureTuning;
1076
+ /** Native device attestation parameters; absent for web-only apps and on older APIs. */
1077
+ integrity?: HostedIntegrity;
1078
+ /**
1079
+ * SDK spec §3.5: present when the session runs the ICAO portrait step — the
1080
+ * client runs the ICAO gate (read it with `icaoPolicyOf`). `icao` is absent on
1081
+ * older servers, which send `{ purpose: "id_document" }` alone (= `reject`, `id_document`).
1082
+ */
1083
+ portrait?: {
1084
+ purpose: "id_document";
1085
+ /** Present whenever a `portrait_icao` step runs (absent on older servers): `reject` / `id_document`. */
1086
+ icao?: HostedIcaoPolicy;
1087
+ } | {
1088
+ /** A verification selfie checked against the ICAO selfie rules (selfie ICAO policy). */
1089
+ purpose: "verification";
1090
+ icao: HostedIcaoPolicy;
1091
+ };
1092
+ /** The flow version the session runs (Sekyro flows §9.2). */
1093
+ flow?: HostedFlowRef;
1094
+ /**
1095
+ * What the person does now (Sekyro flows §8.1), the only source of the
1096
+ * steps: render `plan.current`. Absent on an active session only from a
1097
+ * backend older than the flows release (the SDK then asks for an update).
1098
+ */
1099
+ plan?: HostedPlanView;
1100
+ /** Step 2b identity summary, present only while its confirmation is pending. */
1101
+ identitySummary?: IdentitySummaryView;
1102
+ /**
1103
+ * Spec 2026-10-29 §6.7: the copy set the session's screens use: `human` (the person proves they are a real person:
1104
+ * one intro line, the short Human consent terms) or `identity`. Absent on older APIs: treat as `identity`.
1105
+ */
1106
+ purpose?: "human" | "identity";
1107
+ /**
1108
+ * Spec 2026-10-29 §3.4: `true` when a flow fallback takes over a missing camera at the live step
1109
+ * (`POST /hosted/camera-unavailable` continues the session instead of ending it). Absent otherwise and on
1110
+ * older APIs. Offer "continue without a camera" only then, or on a `human` session.
1111
+ */
1112
+ cameraUnavailableHandled?: true;
1113
+ /**
1114
+ * Spec 2026-10-29 D12: where the hosted completion screen sends the person (`returnUrl`, checked at session
1115
+ * create against the app's web origins or native scheme) and the partner's opaque `state`. Never the result.
1116
+ * Absent when the session has no return link (and on older APIs).
1117
+ */
1118
+ link?: {
1119
+ returnUrl?: string;
1120
+ state?: string;
1121
+ };
1122
+ }
1123
+ /** `POST /hosted/consent` result — 201 on first record, 200 `{alreadyRecorded: true}` on replay. */
1124
+ /**
1125
+ * `POST /hosted/consent` answer (Sekyro flows §8.2): the hosted view with
1126
+ * `consentRecorded: true`, plus whether consent was already on record.
1127
+ */
1128
+ type HostedConsentView = HostedSessionView & RecordConsentResult;
1129
+ interface RecordConsentResult {
1130
+ alreadyRecorded: boolean;
1131
+ }
1132
+ /**
1133
+ * Consent locale: the page's `[locale]` URL segment echoed back (HostedConsentSchema picklist). The six end-user
1134
+ * locales (spec 2026-10-29 §9); a backend older than Plan C accepts ar/fr/en only.
1135
+ */
1136
+ type ConsentLocale = "ar" | "fr" | "en" | "es" | "pt" | "de";
1137
+ /** Per-check projection in a {@link SessionView} — enum/id only, never civil data. */
1138
+ interface SessionStepView {
1139
+ checkType: CheckType;
1140
+ state: CheckState;
1141
+ reason?: CheckReason;
1142
+ /**
1143
+ * Spec 2026-10-27: a Sandbox check answered by simulation (no provider or
1144
+ * model ran). Absent on Live, on real Sandbox checks and on older APIs.
1145
+ */
1146
+ simulated?: boolean;
1147
+ calibratedScore?: number;
1148
+ /** The check failed after using all of its attempts. Absent on older APIs. */
1149
+ attemptsExhausted?: boolean;
1150
+ /** portrait_icao only (SDK spec §4.9): the last attempt's per-criterion report. */
1151
+ report?: IcaoReportEntry[];
1152
+ }
1153
+ /**
1154
+ * Client-facing session projection returned by
1155
+ * `POST /sessions/:id/checks/:checkType`. Whitelist-only — never the client token.
1156
+ */
1157
+ interface SessionView {
1158
+ id: string;
1159
+ status: SessionStatus;
1160
+ outcome: SessionOutcome | null;
1161
+ /** Profile-v2 policy stop reason; absent on ordinary failures and older APIs. */
1162
+ failureReason?: PolicyFailureReason;
1163
+ steps: SessionStepView[];
1164
+ /** ISO-8601 timestamp (Date on the server, string on the wire). */
1165
+ expiresAt: string;
1166
+ /** ISO-8601 timestamp (Date on the server, string on the wire). */
1167
+ createdAt?: string;
1168
+ }
1169
+ /** Media class — selects size cap, MIME allowlist and promoted prefix (media.policy.ts). */
1170
+ type MediaKind = "image" | "clip";
1171
+ /**
1172
+ * Body of `POST /sessions/:id/media`. `contentType`/`contentLength` are the
1173
+ * exact values SIGNED into the presigned PUT — the PUT must send them verbatim.
1174
+ * Allowlists (media.policy.ts): image → image/jpeg | image/png (5 MB cap);
1175
+ * clip → video/webm | video/mp4 (15 MB cap). BARE types only — no `;codecs=` params.
1176
+ */
1177
+ interface PresignRequest {
1178
+ kind: MediaKind;
1179
+ contentType: string;
1180
+ contentLength: number;
1181
+ /** D8: the live-camera capture proof (image / clip from the SDK capture flows only). */
1182
+ capture?: CaptureProof;
1183
+ }
1184
+ /**
1185
+ * D8 — the proof a live-camera image / clip presign carries: a single-use nonce
1186
+ * from `POST /sessions/:id/media/capture-nonces`, plus the capture engine and how
1187
+ * long the capture took. A picked file (or a client without the capture flow)
1188
+ * sends none; the backend then flags (or, in `enforce`, refuses) the upload.
1189
+ */
1190
+ interface CaptureProof {
1191
+ nonce: string;
1192
+ engine?: string;
1193
+ captureMs?: number;
1194
+ }
1195
+ /** D8: `POST /sessions/:id/media/capture-nonces` response. */
1196
+ interface CaptureNoncesResult {
1197
+ nonces: string[];
1198
+ /** Seconds each nonce stays usable. */
1199
+ expiresIn: number;
1200
+ }
1201
+ /** D8: what a capture flow knows about its capture when it presigns. */
1202
+ interface CaptureContext {
1203
+ /** Capture engine id (`v1` / `v3` liveness, `document`, `portrait`). */
1204
+ engine?: string;
1205
+ /** How long the camera capture took, ms (→ `captureMs`; informational). */
1206
+ durationMs?: number;
1207
+ }
1208
+ /** Result of a presign — the presigned PUT URL plus the pending object key. */
1209
+ interface PresignUploadResult {
1210
+ key: string;
1211
+ uploadUrl: string;
1212
+ /** Presign TTL in seconds (900 = 15 min). */
1213
+ expiresIn: number;
1214
+ }
1215
+ /** Result of `POST /sessions/:id/media/complete` — the PROMOTED (class-prefixed) key. */
1216
+ interface CompleteMediaResult {
1217
+ ready: true;
1218
+ /** e.g. `clips/{sessionId}/{uuid}` or `doc-images/{sessionId}/{uuid}` — submit THIS key, not the pending one. */
1219
+ key: string;
1220
+ }
1221
+ /**
1222
+ * Liveness attestation bag (attestation-verifier.service.ts). The web SDK sends
1223
+ * `{channel: 'hosted_web', siteKey, turnstileToken}` — `siteKey` echoes the
1224
+ * `HostedSessionView.turnstileSiteKey` the challenge was rendered with, so the
1225
+ * backend picks the matching widget secret deterministically (Turnstile tokens
1226
+ * are single-use: siteverify runs exactly once, never "org then global").
1227
+ * `sandbox: true` and `signature` are honored only on sandbox sessions;
1228
+ * native SDKs will use platform attestation.
1229
+ */
1230
+ interface AttestationInput {
1231
+ sandbox?: boolean;
1232
+ signature?: string;
1233
+ channel?: "hosted_web";
1234
+ turnstileToken?: string;
1235
+ /** The Turnstile site key the token was minted with (selects the verifying secret). */
1236
+ siteKey?: string;
1237
+ }
1238
+ /**
1239
+ * liveness executor input: a promoted `clips/…` key + optional attestation.
1240
+ * `faceMatch` (v2 latency §3.2) carries the already-promoted `doc-images/…`
1241
+ * keyframe so the backend can run face_match IN THE SAME submission when its
1242
+ * bundle flag is on and `face_match` is the next pending step. Backends that
1243
+ * do not bundle ignore it (the input bag is an open record) — the SDK then
1244
+ * submits `face_match` itself with the same key (see liveness-flow.ts).
1245
+ */
1246
+ interface LivenessInput {
1247
+ clipKey: string;
1248
+ attestation?: AttestationInput;
1249
+ /** Declared capture channel — the liveness band is mobile-calibrated, so the
1250
+ * backend clamps non-mobile verdicts to review (uncalibrated_capture_channel).
1251
+ * Client-declared by design (not a security boundary); absent = legacy
1252
+ * clients, treated as mobile server-side during the rollout window. */
1253
+ captureChannel?: 'mobile' | 'desktop';
1254
+ /** Capture metadata (engine, dimensions, clip length, face-capture timing)
1255
+ * — the backend's allowlisted, non-PII `capture` block (session insights). */
1256
+ capture?: LivenessCaptureInput;
1257
+ /** The promoted face_match probe key, for a bundled liveness + face_match run. */
1258
+ faceMatch?: {
1259
+ imageKey: string;
1260
+ };
1261
+ /**
1262
+ * Step 3 one-capture live photo (flow model 2026-10-23): the ICAO still of the
1263
+ * same capture — exactly the `portrait_icao` body. When `portrait_icao` is the
1264
+ * next pending step the server runs it in parallel with liveness.
1265
+ */
1266
+ portraitIcao?: PortraitIcaoInput;
1267
+ }
1268
+ /** `LivenessInput.capture`: what the SDK's `captured` event measured. All ms are whole, ≥ 0. */
1269
+ interface LivenessCaptureInput {
1270
+ engine?: 'v1' | 'v3';
1271
+ width?: number;
1272
+ height?: number;
1273
+ clipMs?: number;
1274
+ cameraReadyMs?: number;
1275
+ faceAcquireMs?: number;
1276
+ captureMs?: number;
1277
+ /** The camera the clip was filmed with (`environment` = back). */
1278
+ facingMode?: 'user' | 'environment';
1279
+ /** The capture mode the SDK applied (the session's `capture.mode`; the server's own value is the authority). */
1280
+ mode?: 'self' | 'assisted';
1281
+ /** The device kind. With `mode` set, the server applies the upright requirement (`capture_not_upright`) to `phone` only. */
1282
+ formFactor?: 'phone' | 'tablet' | 'desktop';
1283
+ /**
1284
+ * Liveness v7 §4.5 item 1: the screen ramp the SDK rendered against the session's issued challenge. Absent when no
1285
+ * challenge was issued, in an assisted capture, in a keyframe-only capture, or when no host painted the ramp.
1286
+ */
1287
+ screenRamp?: ScreenRampReport;
1288
+ /** Liveness v7 §4.5 item 2: how the capture was made. Sent whenever the engine had a camera track. */
1289
+ provenance?: CaptureProvenance;
1290
+ }
1291
+ /**
1292
+ * population_registry adapter input. `nni` is the 10-digit NNI for an UNBOUND
1293
+ * session; a session minted with a server-side `input.nni` is BOUND to it
1294
+ * (Plan A Task 2) — the browser submits `{}` and the backend reads the sealed
1295
+ * value. Sending a DIFFERENT nni on a bound session answers 409 `nni_locked`.
1296
+ */
1297
+ interface PopulationInput {
1298
+ nni?: string;
1299
+ }
1300
+ /**
1301
+ * face_match executor input: a promoted `doc-images/…` key (the source selfie frame).
1302
+ * The same key may already have ridden along as {@link LivenessInput.faceMatch}.
1303
+ */
1304
+ interface FaceMatchInput {
1305
+ imageKey: string;
1306
+ }
1307
+ /** Document side (docs.types.ts DocSide). */
1308
+ type DocSide = "recto" | "verso" | "single";
1309
+ /** doc_ocr executor input: a promoted `doc-images/…` key + which side it shows. */
1310
+ interface DocOcrInput {
1311
+ imageKey: string;
1312
+ side: DocSide;
1313
+ /**
1314
+ * Web live MRZ (spec 2026-10-21 D6): the device-read HINT of a live-MRZ capture — where the MRZ is in the uploaded
1315
+ * image and that every hard check digit validated on the device. Geometry, a format, counts and a salted digest
1316
+ * only (never MRZ text); the server re-reads the pixels and decides. Omitted when not ready at POST time.
1317
+ */
1318
+ deviceRead?: DocDeviceRead;
1319
+ }
1320
+ /** The `doc_ocr` device-read hint (identity-backend DeviceReadSchema; strict, text-free). */
1321
+ interface DocDeviceRead {
1322
+ engine: string;
1323
+ source: "live_mrz";
1324
+ format: "TD1" | "TD2" | "TD3";
1325
+ lineCount: number;
1326
+ checkDigitsValid: true;
1327
+ stillConfirmed?: boolean;
1328
+ /** [x, y, w, h] normalized to the uploaded image. */
1329
+ band: [number, number, number, number];
1330
+ /** sha256("sekyro-mrz-1\0" + sessionId + "\0" + canonical MRZ lines), 64 hex. */
1331
+ digest: string;
1332
+ framesToValid: number;
1333
+ msToValid: number;
1334
+ }
1335
+ /**
1336
+ * phone_otp executor input (Task 13): a two-phase check. `send` dispatches (or
1337
+ * resends) an OTP — resolving the number from the trusted server-side prefill
1338
+ * or the user-entered `phone` per the step's `numberSource`; `verify` checks
1339
+ * the entered `code` against the parked token. `phone` is IGNORED for a
1340
+ * `prefilled` step (a client number is never trusted as "prefilled").
1341
+ */
1342
+ interface PhoneOtpInput {
1343
+ /** Phase selector: `send` dispatches/resends, `verify` checks the code. Defaults to `send`. */
1344
+ action: "send" | "verify";
1345
+ /** USER-entered E.164 number (`user_entered` / `prefilled_or_entered` sends only). */
1346
+ phone?: string;
1347
+ /** The code the user typed — `verify` only. */
1348
+ code?: string;
1349
+ /**
1350
+ * The channel the person chose for `send`. Must be one of the step's
1351
+ * `otp.channels` when the view lists them; a session without channels
1352
+ * defaults to `sms`.
1353
+ */
1354
+ channel?: "sms" | "whatsapp";
1355
+ /** OTP message locale override for `send`. */
1356
+ locale?: "ar" | "fr" | "en";
1357
+ }
1358
+ /**
1359
+ * email_otp executor input (Plan 8, profile v2 §4.6.5): `send` emails a code to
1360
+ * the trusted prefill or the user-entered `email` (per `emailOtp.emailSource`;
1361
+ * ignored for `prefilled`), `verify` checks the entered `code`.
1362
+ */
1363
+ interface EmailOtpInput {
1364
+ /** Phase selector: `send` dispatches/resends, `verify` checks the code. */
1365
+ action: "send" | "verify";
1366
+ /** USER-entered address (`user_entered` / `prefilled_or_entered` sends only). */
1367
+ email?: string;
1368
+ /** The code the user typed — `verify` only. */
1369
+ code?: string;
1370
+ /** Email copy locale override for `send`. */
1371
+ locale?: "ar" | "fr" | "en";
1372
+ }
1373
+ /**
1374
+ * portrait_icao executor input (SDK spec §4.9): the ICAO gate's frame
1375
+ * (uploaded as media kind `image`). The server re-runs every criterion; only
1376
+ * `gate.baselineEyeOpenness` (0–1, the user's own eye-openness baseline) is used.
1377
+ */
1378
+ interface PortraitIcaoInput {
1379
+ media: {
1380
+ portrait: string;
1381
+ };
1382
+ gate?: {
1383
+ baselineEyeOpenness?: number;
1384
+ /**
1385
+ * The device verdict on the submitted still, with the server's criterion names
1386
+ * (`framing` folds into `resolution`; unmeasured criteria are omitted, and
1387
+ * `background` when the profile does not require it). Compared with the server
1388
+ * report, never trusted. Values are booleans keyed by {@link IcaoCriterion}
1389
+ * (the 0.1 type is kept: the public API only grows).
1390
+ */
1391
+ criteria?: Record<string, unknown>;
1392
+ /** The client background-uniformity measurement (numbers only; telemetry — the server decides). */
1393
+ backgroundCheck?: Record<string, unknown>;
1394
+ };
1395
+ tuningVersion?: string;
1396
+ }
1397
+ /**
1398
+ * eid_auth executor input (SDK spec §3.2): `start` asks the provider for a
1399
+ * code (with the person's `identifier` — the NNI in MR — unless the session is
1400
+ * bound to it), `verify` checks the typed `code`, `resend` asks for a new code.
1401
+ * On a bound session a different `identifier` answers 409 `nni_locked`.
1402
+ */
1403
+ interface EidAuthInput {
1404
+ action: "start" | "verify" | "resend";
1405
+ /** `start` only: the national number, omitted on a bound session. */
1406
+ identifier?: string;
1407
+ /** `verify` only: the code shown in the provider's app. */
1408
+ code?: string;
1409
+ }
1410
+ /** Per-check-type submission input shapes, keyed by the frozen vocabulary. */
1411
+ interface CheckInputByType {
1412
+ liveness: LivenessInput;
1413
+ face_match: FaceMatchInput;
1414
+ doc_ocr: DocOcrInput;
1415
+ population_registry: PopulationInput;
1416
+ phone_otp: PhoneOtpInput;
1417
+ /** M-nfc: read and submitted by the native SDKs only — the web never submits it. */
1418
+ nfc_chip: never;
1419
+ email_otp: EmailOtpInput;
1420
+ /** SDK spec §4.9: the web ICAO gate ships with M1b; the shape is ready for headless use. */
1421
+ portrait_icao: PortraitIcaoInput;
1422
+ /** SDK spec §3.2: the national eID sign-in. */
1423
+ eid_auth: EidAuthInput;
1424
+ }
1425
+ /**
1426
+ * Body of `POST /sessions/:id/checks/:checkType` (SubmitCheckSchema).
1427
+ * `forceOutcome` is SANDBOX-ONLY (plan D-C) — a live session rejects it with
1428
+ * 403 `force_outcome_forbidden`.
1429
+ */
1430
+ interface SubmitCheckBody {
1431
+ input?: Record<string, unknown>;
1432
+ forceOutcome?: "pass" | "fail";
1433
+ }
1434
+
1435
+ export { type IdentitySummaryView as $, type AcceptedDocumentType as A, type BackgroundUniformity as B, type ConsentLocale as C, type DecisionReason as D, type EidAfterPass as E, type FaceMatchReason as F, type HostedIntegrity as G, type HostedSessionView as H, type IdentityConfirmDecision as I, type HostedLivePhotoTuning as J, type HostedLivenessCaptureTuning as K, type HostedNativeCaptureTuning as L, type MediaKind as M, type HostedOcrTuning as N, type HostedOtpView as O, type PresignUploadResult as P, type HostedPlanView as Q, type ResolvedIcaoTuning as R, type ScreenRampColour as S, type HostedPortraitView as T, type HostedStepView as U, type HostedVoiceLocale as V, type HostedVoiceView as W, type IcaoCaptureTuning as X, type IcaoReportEntry as Y, type IdentityMethod as Z, type IdentitySummarySource as _, type HostedConsentView as a, type LivenessReason as a0, type MatchReason as a1, type MethodChoiceView as a2, type NationalEidOption as a3, type NfcChipReason as a4, type NfcStepView as a5, type OtpChoiceView as a6, type PhoneOtpReason as a7, type PlanAttempts as a8, type PlanChoiceKind as a9, type DocOcrInput as aA, type DocSide as aB, type EmailOtpInput as aC, type FaceMatchInput as aD, type LivenessCaptureInput as aE, type LivenessInput as aF, type PhoneOtpInput as aG, type PopulationInput as aH, type PresignRequest as aI, type RecordConsentResult as aJ, type SessionStepView as aK, type SessionView as aL, type SubmitCheckBody as aM, type PlanChoiceOption as aa, type PlanChoiceView as ab, type PlanSectionView as ac, type PlanStepView as ad, type PolicyFailureReason as ae, type PopulationReason as af, type PortraitIcaoInput as ag, type PortraitIcaoReason as ah, type RetakeHint as ai, type ScreenRampChallenge as aj, type ScreenRampRendered as ak, type ScreenRampReport as al, type SessionFailureReason as am, type SessionOutcome as an, type SessionStatus as ao, type StepSection as ap, type VerificationAssurance as aq, type VerificationLevel as ar, ICAO_FALLBACK as as, type IcaoProfile as at, resolveIcaoTuning as au, type PersonMask as av, type AttestationInput as aw, type CaptureNoncesResult as ax, type CaptureProof as ay, type DocDeviceRead as az, type CameraUnavailableCause as b, type CaptureContext as c, type CompleteMediaResult as d, type CheckType as e, type CheckInputByType as f, type IcaoCriterion as g, type CaptureMode as h, type CaptureProvenance as i, type CheckReason as j, type CheckState as k, type ContactChannel as l, type DocReason as m, type EidAuthInput as n, type EidReason as o, type EmailOtpReason as p, type HostedAcceptedDocuments as q, type HostedBranding as r, type HostedBrandingColorKey as s, type HostedCaptureTuning as t, type HostedDocumentCaptureTuning as u, type HostedDocumentScanTuning as v, type HostedEidView as w, type HostedEmailOtpView as x, type HostedFlowRef as y, type HostedIcaoPolicy as z };