@sekyro/web 0.1.0-rc.10 → 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 (55) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/dist/{capture-session-doc-GK6G7JOI.js → capture-session-doc-DMQ7T3HC.js} +1 -1
  3. package/dist/{capture-session-v3-CmJw_bK0.d.cts → capture-session-v3-CCHws1mz.d.cts} +34 -3
  4. package/dist/{capture-session-v3-DGG2stO6.d.ts → capture-session-v3-DYrhYJoM.d.ts} +34 -3
  5. package/dist/{chunk-SEC64KZ3.js → chunk-73M7LS4H.js} +1 -1
  6. package/dist/chunk-AHD4DA2V.js +1 -0
  7. package/dist/chunk-GT2ZLGF7.js +1 -0
  8. package/dist/chunk-HHCGQSD4.js +1 -0
  9. package/dist/chunk-IJLHPX35.js +1 -0
  10. package/dist/{chunk-FFDB6LQN.js → chunk-JDGEZ542.js} +1 -1
  11. package/dist/{chunk-BAGSM67V.js → chunk-LUKTHL6K.js} +1 -1
  12. package/dist/chunk-MXNZMTC2.js +1 -0
  13. package/dist/{chunk-UGMHAFEY.js → chunk-OWU22VXP.js} +1 -1
  14. package/dist/chunk-U6TYL2IJ.js +1 -0
  15. package/dist/chunk-URUKV6NC.js +1 -0
  16. package/dist/chunk-V5K2JLC7.js +1 -0
  17. package/dist/client/index.cjs +1 -1
  18. package/dist/client/index.d.cts +5 -3
  19. package/dist/client/index.d.ts +5 -3
  20. package/dist/client/index.js +1 -1
  21. package/dist/core/index.cjs +1 -1
  22. package/dist/core/index.d.cts +3 -2
  23. package/dist/core/index.d.ts +3 -2
  24. package/dist/core/index.js +1 -1
  25. package/dist/{create-document-capture-IGUQP2NS.js → create-document-capture-FV4XGUKQ.js} +1 -1
  26. package/dist/{create-portrait-capture-RJSFY37D.js → create-portrait-capture-C462EIB6.js} +1 -1
  27. package/dist/{create-verification-Bb20j6zk.d.ts → create-verification-CmJzn7sq.d.ts} +81 -8
  28. package/dist/{create-verification-CtqF4A9W.d.cts → create-verification-CzLrQjeM.d.cts} +81 -8
  29. package/dist/icao-gate-BeznQECA.d.cts +500 -0
  30. package/dist/icao-gate-Bw5sQVlt.d.ts +500 -0
  31. package/dist/index.cjs +1 -1
  32. package/dist/index.d.cts +16 -5
  33. package/dist/index.d.ts +16 -5
  34. package/dist/index.js +1 -1
  35. package/dist/internal/index.cjs +1 -1
  36. package/dist/internal/index.d.cts +17 -8
  37. package/dist/internal/index.d.ts +17 -8
  38. package/dist/internal/index.js +1 -1
  39. package/dist/{plan-runner-QCK2SOGS.js → plan-runner-ZVAY4FSB.js} +1 -1
  40. package/dist/popup/index.cjs +1 -1
  41. package/dist/popup/index.d.cts +7 -1
  42. package/dist/popup/index.d.ts +7 -1
  43. package/dist/popup/index.js +1 -1
  44. package/dist/{icao-gate-terzKYD7.d.cts → types-BWyAHKt_.d.cts} +164 -499
  45. package/dist/{icao-gate-terzKYD7.d.ts → types-BWyAHKt_.d.ts} +164 -499
  46. package/package.json +1 -1
  47. package/sbom.cdx.json +7 -7
  48. package/dist/chunk-3MSUJYBO.js +0 -1
  49. package/dist/chunk-ETY6SAAZ.js +0 -1
  50. package/dist/chunk-HAO6EQTH.js +0 -1
  51. package/dist/chunk-HWAXEQD5.js +0 -1
  52. package/dist/chunk-SXZCL5NO.js +0 -1
  53. package/dist/chunk-SZ7YGNUZ.js +0 -1
  54. package/dist/chunk-WKJJEPWA.js +0 -1
  55. package/dist/chunk-XR64UFLK.js +0 -1
@@ -0,0 +1,500 @@
1
+ import { H as HostedSessionView, C as ConsentLocale, a as HostedConsentView, b as CameraUnavailableCause, I as IdentityConfirmDecision, M as MediaKind, P as PresignUploadResult, c as CaptureContext, d as CompleteMediaResult, e as CheckType, f as CheckInputByType, g as IcaoCriterion, B as BackgroundUniformity, R as ResolvedIcaoTuning } from './types-BWyAHKt_.js';
2
+
3
+ interface Point {
4
+ x: number;
5
+ y: number;
6
+ }
7
+ interface Box {
8
+ x: number;
9
+ y: number;
10
+ width: number;
11
+ height: number;
12
+ }
13
+ /** The face geometry the gate needs, in SOURCE (stream) pixels. */
14
+ interface FaceGeometry {
15
+ /** Eye centres, ordered by image x (`left` = smaller x). */
16
+ leftEye: Point;
17
+ rightEye: Point;
18
+ /** Inter-ocular distance (px). */
19
+ iod: number;
20
+ /** Bounding box of the landmark mesh (forehead to chin). */
21
+ box: Box;
22
+ /** Nose tip (landmark 1): splits the face into halves for the lighting ratio. */
23
+ nose: Point;
24
+ /** Eye-contour boxes (glare), same order as the eyes. */
25
+ leftEyeBox: Box;
26
+ rightEyeBox: Box;
27
+ }
28
+ /**
29
+ * Normalised Face Landmarker landmarks (0..1) → source-pixel geometry.
30
+ * `null` when the mesh is too short to carry the eyes.
31
+ */
32
+ declare function faceGeometry(landmarks: readonly Point[], width: number, height: number): FaceGeometry | null;
33
+ interface HeadPose {
34
+ yaw: number;
35
+ pitch: number;
36
+ roll: number;
37
+ }
38
+ /**
39
+ * Yaw / pitch / roll (degrees) of the Face Landmarker's facial transformation
40
+ * matrix (4×4, `layout` of `data`; MediaPipe emits column-major). Rotation
41
+ * order R = Rz(roll)·Ry(yaw)·Rx(pitch): yaw turns about the vertical axis,
42
+ * pitch nods, roll tilts. Only magnitudes are gated, so sign conventions never
43
+ * change a verdict. `null` for a malformed matrix.
44
+ */
45
+ declare function poseFromMatrix(data: readonly number[], layout?: "column" | "row"): HeadPose | null;
46
+ /** Roll from the eye line (degrees) — the fallback when no matrix is available. */
47
+ declare function eyeLineRoll(g: Pick<FaceGeometry, "leftEye" | "rightEye">): number;
48
+ /** The ICAO canvas (icao.py): 480×640, eye midpoint at x = 240, eye line at y = 289, IOD 120–160. */
49
+ declare const ICAO_CANVAS: {
50
+ readonly width: 480;
51
+ readonly height: 640;
52
+ readonly eyeX: 240;
53
+ readonly eyeY: 289;
54
+ readonly iodMin: 120;
55
+ readonly iodMax: 160;
56
+ };
57
+ /**
58
+ * The source-pixel window the server's ICAO crop is cut from: scale 1 when the
59
+ * IOD already lies in 120–160, else the scale that brings it to 120 (icao.py:
60
+ * "120 when outside the band"), the eye midpoint at (240, 289) of the window.
61
+ */
62
+ declare function icaoWindow(g: Pick<FaceGeometry, "leftEye" | "rightEye" | "iod">): Box;
63
+ /** How far a window spills outside the frame (0 = inside), as a fraction of its size. */
64
+ declare function windowOverflow(window: Box, frameWidth: number, frameHeight: number): number;
65
+ /**
66
+ * The region of the full-resolution still the SDK uploads: the ICAO window
67
+ * grown by `margin` about its centre (so the server re-crops with its own
68
+ * landmarks), at least `minWidth × minHeight`, 3:4 portrait, then fitted into
69
+ * the frame — the margin shrinks first, then the box slides inside, and only
70
+ * a window larger than the frame is cut to it. Integer pixels.
71
+ */
72
+ declare function portraitCropRegion(g: Pick<FaceGeometry, "leftEye" | "rightEye" | "iod">, frameWidth: number, frameHeight: number, opts: {
73
+ margin: number;
74
+ minWidth: number;
75
+ minHeight: number;
76
+ }): Box;
77
+
78
+ /**
79
+ * Strip MIME parameters: `video/webm;codecs=vp8,opus` → `video/webm`.
80
+ *
81
+ * The capture engine (Task 4) emits `clipMimeType` WITH codec parameters, but
82
+ * the presign allowlist holds BARE types only (['video/webm','video/mp4'] /
83
+ * ['image/jpeg','image/png']) and the presigned PUT signs the exact declared
84
+ * Content-Type. Exported so pages can normalize once and stay byte-consistent
85
+ * between presign and PUT.
86
+ */
87
+ declare function stripMimeParams(contentType: string): string;
88
+ /** Media-bearing check types → the input field the promoted key goes into. */
89
+ declare const MEDIA_INPUT_FIELD: {
90
+ readonly liveness: "clipKey";
91
+ readonly face_match: "imageKey";
92
+ readonly doc_ocr: "imageKey";
93
+ };
94
+ /** Check types that take an uploaded media key (population_registry does not). */
95
+ type MediaCheckType = keyof typeof MEDIA_INPUT_FIELD;
96
+ interface SubmitOptions {
97
+ /**
98
+ * Sent as `x-idempotency-key` (the header IdempotencyInterceptor reads).
99
+ * One key per LOGICAL submit — a flaky-network retry with the same key
100
+ * replays the first response without burning another attempt.
101
+ */
102
+ idempotencyKey?: string;
103
+ /** SANDBOX-ONLY deterministic override (plan D-C); a live session 403s it. */
104
+ forceOutcome?: "pass" | "fail";
105
+ }
106
+ interface UploadMedia {
107
+ kind: MediaKind;
108
+ blob: Blob;
109
+ /** May carry codec params (engine `clipMimeType`) — stripped before presign AND PUT. */
110
+ contentType: string;
111
+ }
112
+ interface HostedClientOptions {
113
+ /** API origin, e.g. `https://api.sekyro.ai` — paths are `${apiOrigin}/api/v2/...`. */
114
+ apiOrigin: string;
115
+ /** The raw session token from the hosted URL (short code; legacy `cst_` during its TTL) — sent as `x-session-token` on every API call. */
116
+ sessionToken: string;
117
+ /** Injection seam (tests / non-window contexts). Defaults to `globalThis.fetch`. */
118
+ fetch?: typeof globalThis.fetch;
119
+ /** Per-request timeout for API calls (NOT the Spaces PUT). Default 30 000 ms. */
120
+ requestTimeoutMs?: number;
121
+ /**
122
+ * Tuning for the ONLY automatic retry the client performs: 409
123
+ * `idempotency_in_progress` (a concurrent identical request is mid-flight
124
+ * server-side; the real response lands once it finishes). `attempts` counts
125
+ * retries AFTER the first try. Defaults: 5 × 400 ms.
126
+ */
127
+ inProgressRetry?: {
128
+ attempts?: number;
129
+ delayMs?: number;
130
+ };
131
+ }
132
+ /**
133
+ * Hand-authored typed client for the five session-token endpoints:
134
+ *
135
+ * GET /api/v2/hosted/session → {@link getSession}
136
+ * POST /api/v2/hosted/consent → {@link recordConsent}
137
+ * POST /api/v2/hosted/choice → {@link choose}
138
+ * POST /api/v2/hosted/identity/confirm → {@link confirmIdentity}
139
+ * GET /api/v2/hosted/identity/portrait → {@link identityPortrait}
140
+ * POST /api/v2/sessions/:id/media → {@link presign}
141
+ * POST /api/v2/sessions/:id/media/complete → {@link completeMedia}
142
+ * POST /api/v2/sessions/:id/checks/:checkType → {@link submitCheck}
143
+ *
144
+ * plus the bare presigned Spaces PUT ({@link uploadToSpaces}) and the
145
+ * presign→PUT→complete→submit composition ({@link uploadAndSubmit}).
146
+ *
147
+ * Envelopes (verified against sessions-docs.e2e-spec.ts):
148
+ * - success: `{success: true, data}` — unwrapped here, methods return the payload;
149
+ * - error: flat `{code, message}` → thrown as {@link HostedApiError}.
150
+ *
151
+ * The media/checks routes are `:id`-addressed while the token itself is the
152
+ * only credential the page starts with — the client learns its sessionId from
153
+ * `GET /hosted/session` (token-addressed) and lazily bootstraps it when a
154
+ * `:id` route is called first.
155
+ *
156
+ * No automatic retry EXCEPT bounded short-delay retry on 409
157
+ * `idempotency_in_progress`. Everything else — including 429 with its parsed
158
+ * `retryAfterSeconds` — is surfaced to the page to handle.
159
+ */
160
+ declare class HostedClient {
161
+ private readonly apiOrigin;
162
+ private readonly sessionToken;
163
+ private readonly fetchImpl;
164
+ private readonly requestTimeoutMs;
165
+ private readonly retryAttempts;
166
+ private readonly retryDelayMs;
167
+ private sessionId;
168
+ private bootstrap;
169
+ /** D8: prefetched capture nonces (`armCapture`), each with its local expiry. */
170
+ private captureNonces;
171
+ private captureFetch;
172
+ constructor(opts: HostedClientOptions);
173
+ /** Token-addressed bootstrap — the hosted page's first call. Caches the sessionId. */
174
+ getSession(): Promise<HostedSessionView>;
175
+ /**
176
+ * Record consent once (201; an idempotent replay answers 200 with
177
+ * `alreadyRecorded: true`). Until recorded, media presign/complete AND check
178
+ * submission answer 409 `consent_required`.
179
+ */
180
+ recordConsent(locale: ConsentLocale): Promise<HostedConsentView>;
181
+ /**
182
+ * Spec 2026-10-29 §3.4: the device has no usable camera. The server fails the frontier liveness step with
183
+ * `camera_unavailable` (no attempt, nothing billed) and lets the flow decide: a fallback step, else the session
184
+ * ends at level 0. Returns the hosted view; 409 `check_out_of_order` when the frontier is not a liveness step.
185
+ * `cause` (2026-10-30) says why (`denied` | `no_camera`); omitted, the body stays `{}` and nothing is recorded.
186
+ */
187
+ reportCameraUnavailable(cause?: CameraUnavailableCause): Promise<HostedSessionView>;
188
+ /**
189
+ * Pick an option of the current choice (Sekyro flows §7.4): `plan.choice`'s
190
+ * `nodeId` and one of its option ids. Returns the updated hosted view —
191
+ * render it. The person may switch while `plan.choice.locked` is false.
192
+ * Errors: 409 `choice_locked`, 409 `choice_option_unavailable`, 404 `choice_not_found`.
193
+ */
194
+ choose(nodeId: string, option: string): Promise<HostedSessionView>;
195
+ /**
196
+ * Answer the identity summary (`identitySummary` in the view, Step 2b):
197
+ * `confirm` lifts the live-photo gate, `retake` re-opens the identity checks
198
+ * that produced the data. Returns the updated hosted view; 409
199
+ * `identity_confirm_locked` when nothing is pending or no retake is left.
200
+ */
201
+ confirmIdentity(decision: IdentityConfirmDecision): Promise<HostedSessionView>;
202
+ /**
203
+ * The summary portrait (`identitySummary.portrait.available`) as a JPEG
204
+ * `Blob`, fetched with the session-token header (`Cache-Control: no-store`).
205
+ * Show it from memory (`URL.createObjectURL`, revoked when done) — never
206
+ * cache or store it.
207
+ */
208
+ identityPortrait(): Promise<Blob>;
209
+ /**
210
+ * Presign a Spaces PUT for a new pending object. `contentType` is stripped of
211
+ * MIME parameters defensively (the allowlist holds bare types; the engine's
212
+ * `clipMimeType` carries codec params) — PUT with the SAME bare type, or the
213
+ * signed-header check rejects the upload.
214
+ */
215
+ presign(kind: MediaKind, contentType: string, contentLength: number): Promise<PresignUploadResult>;
216
+ /**
217
+ * D8: prefetch live-camera capture nonces when a camera capture STARTS, so the
218
+ * presigns that follow (`presignCapture`) need no extra round trip. Never
219
+ * throws; an older backend without the route simply leaves the pool empty.
220
+ */
221
+ armCapture(count?: number): void;
222
+ /**
223
+ * D8: presign a LIVE-CAMERA image / clip — like {@link presign}, plus the
224
+ * capture proof: a fresh single-use nonce (pooled by {@link armCapture}, else
225
+ * fetched now), the engine and the capture duration. When no nonce can be had
226
+ * (route absent, network) the presign goes out without a proof — the backend
227
+ * decides (`signal` flags it, `enforce` refuses it). Only the SDK's own capture
228
+ * flows call this; a picked file goes through {@link presign}.
229
+ */
230
+ presignCapture(kind: MediaKind, contentType: string, contentLength: number, context?: CaptureContext): Promise<PresignUploadResult>;
231
+ /** D8: one pooled (still fresh) nonce, else one fetched now; undefined when none can be had. */
232
+ private takeCaptureNonce;
233
+ /** D8: fetch `count` nonces into the pool (one request in flight at a time). Never throws. */
234
+ private fillCaptureNonces;
235
+ /**
236
+ * Bare PUT to the presigned Spaces URL: EXACTLY the signed headers — the
237
+ * declared Content-Type and the blob body. NO `x-session-token` (the
238
+ * signature IS the credential; an extra header breaks nothing but leaks the
239
+ * token to a third-party host) and no JSON envelope.
240
+ *
241
+ * `contentType` is param-stripped here too (idempotent for bare types): the
242
+ * presign strips internally, so a caller composing manually with the engine's
243
+ * parameterful `clipMimeType` would otherwise sign `video/webm` but PUT
244
+ * `video/webm;codecs=…` — a signed-header mismatch S3 rejects at runtime.
245
+ *
246
+ * Timeout: 15 min (`AbortSignal.timeout(900_000)`, matching the presign TTL)
247
+ * rather than the API calls' 30 s — a 15 MB clip on a slow link legitimately
248
+ * exceeds 30 s, but a stalled in-flight socket must still be bounded (the TTL
249
+ * alone only bounds when a PUT can START).
250
+ *
251
+ * Failures are ALWAYS typed: non-2xx throws {@link HostedApiError} with the
252
+ * client-synthesized `upload_failed` (message carries a truncated S3 body
253
+ * snippet — e.g. SignatureDoesNotMatch); a mid-transfer drop → `network_error`;
254
+ * the timeout → `timeout`.
255
+ */
256
+ uploadToSpaces(uploadUrl: string, blob: Blob, contentType: string): Promise<void>;
257
+ /** Finalize an upload: the backend sniffs + promotes; returns the PROMOTED key to submit. */
258
+ completeMedia(key: string): Promise<CompleteMediaResult>;
259
+ /**
260
+ * Submit one check. Sends `{input, forceOutcome?}` (SubmitCheckSchema) and the
261
+ * optional `x-idempotency-key` header. Returns the hosted view after the
262
+ * submission (Sekyro flows §8.2: with its `plan`) — render it.
263
+ */
264
+ submitCheck<T extends CheckType>(checkType: T, input: CheckInputByType[T], opts?: SubmitOptions): Promise<HostedSessionView>;
265
+ /**
266
+ * Convenience composition: presign → PUT → complete → submit, passing the
267
+ * PROMOTED key (from complete's response — never the pending presign key)
268
+ * into the check's media input field (`clipKey` for liveness, `imageKey` for
269
+ * face_match/doc_ocr). `extraInput` carries the remaining input fields
270
+ * (liveness `attestation`, doc_ocr `side`). The media content type is
271
+ * param-stripped ONCE and used for both presign and PUT, so the signed
272
+ * header always matches.
273
+ */
274
+ uploadAndSubmit<T extends MediaCheckType>(checkType: T, media: UploadMedia, extraInput: Omit<CheckInputByType[T], (typeof MEDIA_INPUT_FIELD)[T]>, opts?: SubmitOptions): Promise<HostedSessionView>;
275
+ /** The token's own sessionId — cached from getSession(), lazily bootstrapped. */
276
+ private ensureSessionId;
277
+ /**
278
+ * One API request: `${apiOrigin}/api/v2${path}`, `x-session-token` always,
279
+ * AbortSignal timeout (30 s default), `{success, data}` unwrap on 2xx, flat
280
+ * `{code, message}` → {@link HostedApiError} on non-2xx. EVERY failure is
281
+ * typed: a rejected fetch → `network_error`, the timeout → `timeout`, an
282
+ * unparseable 2xx body → `unknown_error` — the page never sees a raw
283
+ * TypeError/DOMException. The ONLY automatic retry is 409
284
+ * `idempotency_in_progress` (bounded, short delay).
285
+ */
286
+ private api;
287
+ }
288
+
289
+ /** Luma at or above this counts as clipped / specular. */
290
+ declare const CLIPPED_LUMA = 250;
291
+ /** Laplacian-variance reference (same as the liveness gate's frame-quality SHARP_REF). */
292
+ declare const ICAO_SHARP_REF = 180;
293
+ interface LumaPlane {
294
+ data: Uint8Array;
295
+ width: number;
296
+ height: number;
297
+ }
298
+ /** Rec.601 luma of RGBA pixels. */
299
+ declare function lumaPlane(image: {
300
+ data: Uint8ClampedArray | Uint8Array;
301
+ width: number;
302
+ height: number;
303
+ }): LumaPlane;
304
+ interface RegionStats {
305
+ mean: number;
306
+ sd: number;
307
+ /** Fraction of pixels at or above {@link CLIPPED_LUMA}. */
308
+ clipped: number;
309
+ count: number;
310
+ }
311
+ /** Mean / SD / clipped fraction of a box, optionally excluding a second box. */
312
+ declare function regionStats(plane: LumaPlane, box: Box, exclude?: Box): RegionStats;
313
+ interface FaceLighting {
314
+ faceLuma: number;
315
+ /** Left-half / right-half mean luma (image halves, split at the nose). */
316
+ halfRatio: number;
317
+ clipped: number;
318
+ }
319
+ declare function faceLighting(plane: LumaPlane, g: FaceGeometry): FaceLighting | null;
320
+ /** Specular fraction inside both eye regions (spec §5.4 glasses glare). */
321
+ declare function eyeSpecular(plane: LumaPlane, g: FaceGeometry): number | null;
322
+ interface BackgroundStats {
323
+ luma: number;
324
+ sd: number;
325
+ /** Pixels measured — too few means the corners left the frame. */
326
+ count: number;
327
+ }
328
+ /**
329
+ * Background heuristic: the two top corners of the ICAO window (each 20 % wide,
330
+ * 25 % tall from 4 % down), minus the head (the face box widened by 40 % and
331
+ * extended to the top of the window for hair). `null` when nothing is left.
332
+ */
333
+ declare function backgroundStats(plane: LumaPlane, g: FaceGeometry): BackgroundStats | null;
334
+ /** Laplacian variance over the face core on a ≤96×96 grid, normalised 0..1 by {@link ICAO_SHARP_REF}. */
335
+ declare function faceSharpness(plane: LumaPlane, g: FaceGeometry): number | null;
336
+ /** Every pixel measure of one frame (`null` fields: not measurable). */
337
+ interface IcaoPixelStats {
338
+ lighting: FaceLighting | null;
339
+ eyeSpecular: number | null;
340
+ background: BackgroundStats | null;
341
+ sharpness: number | null;
342
+ }
343
+ declare function icaoPixelStats(plane: LumaPlane, g: FaceGeometry): IcaoPixelStats;
344
+
345
+ /** The client gate's criteria, in coaching priority order. */
346
+ declare const ICAO_GATE_CRITERIA: readonly ["face", "framing", "pose", "eyes", "mouth", "glare", "lighting", "background", "resolution", "sharpness"];
347
+ type IcaoGateCriterion = (typeof ICAO_GATE_CRITERIA)[number];
348
+ /** Coaching keys (copy `portrait.coach.<key>`). */
349
+ type IcaoCoachKey = "no_face" | "multiple_faces" | "center" | "too_close" | "pose" | "eyes" | "mouth" | "glare" | "lighting" | "lighting_side" | "background" | "resolution" | "hold_still" | "hold";
350
+ /** One frame as the gate sees it. Geometry in SOURCE (stream) pixels. */
351
+ interface IcaoFrameObservation {
352
+ frameWidth: number;
353
+ frameHeight: number;
354
+ /** Faces the landmarker found (the gate wants exactly one). */
355
+ faces: number;
356
+ geometry: FaceGeometry | null;
357
+ /** Facial transformation matrix (4×4, column-major), when produced. */
358
+ matrix?: readonly number[] | null;
359
+ /** Blendshape scores by category name (`eyeBlinkLeft`, `jawOpen`, …). */
360
+ blendshapes?: Readonly<Record<string, number>> | null;
361
+ /** Pixel heuristics on the analysis frame; `null` when not measured. */
362
+ stats?: IcaoPixelStats | null;
363
+ /**
364
+ * The background-uniformity check (segmenter, or the strip fallback), the
365
+ * latest measurement — it runs a few times per second, not on every frame.
366
+ * When present it decides the `background` criterion; `null` = not measurable.
367
+ */
368
+ backgroundCheck?: BackgroundUniformity | null;
369
+ }
370
+ interface IcaoCriterionState {
371
+ criterion: IcaoGateCriterion;
372
+ pass: boolean;
373
+ /** Passed continuously for `holdMs`. */
374
+ held: boolean;
375
+ /** A failing soft criterion the gate stopped waiting for. */
376
+ waived: boolean;
377
+ /** The measured value (degrees, ratio, luma, px…) — coaching / telemetry only. */
378
+ value: number | null;
379
+ /** Coaching key when failing. */
380
+ coach: IcaoCoachKey | null;
381
+ }
382
+ interface IcaoGateUpdate {
383
+ criteria: IcaoCriterionState[];
384
+ /** The one message to show (`hold` when everything passes and the gate is counting down). */
385
+ coach: IcaoCoachKey;
386
+ /** The lowest failing criterion (`null` when all pass or are waived). */
387
+ failing: IcaoGateCriterion | null;
388
+ /** 0..1 — held criteria, for a progress ring. */
389
+ progress: number;
390
+ /** Take the portrait frame now. */
391
+ ready: boolean;
392
+ /**
393
+ * The user's own eye-openness baseline, once known. Unit (D9d, everywhere): openness =
394
+ * 1 − the Landmarker's `eyeBlink{Left,Right}` blendshape; per frame the mean of the
395
+ * two eyes; the baseline is the `baseline.percentile` (0.8) quantile over the recent
396
+ * frontal, single-face frames. kyc-portrait compares the lower eye against it.
397
+ */
398
+ baseline: number | null;
399
+ pose: HeadPose | null;
400
+ }
401
+ /** The on-device result submitted with the portrait (`gate`, §4.9): numbers only. */
402
+ interface IcaoGateSummary {
403
+ /** In (0, 1]: the gate's eye baseline (1 − blink blendshape; see {@link IcaoGateUpdate.baseline}). */
404
+ baselineEyeOpenness?: number;
405
+ criteria: Partial<Record<IcaoGateCriterion, {
406
+ pass: boolean;
407
+ value: number | null;
408
+ waived?: boolean;
409
+ }>>;
410
+ /**
411
+ * The device verdict with the server's criterion names — the submission's
412
+ * `gate.criteria`: `framing` folds into `resolution`, unmeasured criteria are
413
+ * omitted (occlusion always; background when the profile does not require it).
414
+ */
415
+ verdict?: Partial<Record<IcaoCriterion, boolean>>;
416
+ /** The background-uniformity measurement behind the `background` criterion (numbers only). */
417
+ backgroundCheck?: Omit<BackgroundUniformity, "pixels">;
418
+ }
419
+ interface Measured {
420
+ pass: boolean;
421
+ value: number | null;
422
+ coach: IcaoCoachKey | null;
423
+ /** Not measured on this frame (left out of the verdict). */
424
+ none?: true;
425
+ }
426
+ /** The criteria a profile sets limits for (conformance.json `criteria`). */
427
+ type IcaoJudgedCriterion = "pose" | "eyes" | "mouth" | "lighting" | "background" | "resolution";
428
+ /**
429
+ * One frame's measures in the server's units (conformance.json `measures`);
430
+ * `null` = not measured on this frame.
431
+ */
432
+ interface IcaoMeasures {
433
+ /** Degrees; `pitch` is RAW (before `pitchOffsetDeg`). `null` = no transformation matrix. */
434
+ pose: HeadPose | null;
435
+ /** The value shown for a pose without matrix (roll from the eye line). */
436
+ eyeLineRoll?: number;
437
+ /** Openness of each eye (1 − the `eyeBlink*` blendshape). */
438
+ eyes: {
439
+ left: number;
440
+ right: number;
441
+ } | null;
442
+ /** The person's eye-openness baseline; `null` = the absolute floor only. */
443
+ baseline: number | null;
444
+ /** Blendshapes: `jawOpen`, the larger `mouthSmile*`, `mouthPucker`. */
445
+ mouth: {
446
+ jawOpen: number;
447
+ smile: number;
448
+ pucker: number;
449
+ } | null;
450
+ lighting: {
451
+ faceLuma: number;
452
+ halfRatio: number;
453
+ clipped: number;
454
+ } | null;
455
+ background: {
456
+ luma: number;
457
+ sd: number;
458
+ } | null;
459
+ /** The web background-uniformity check; when present (and enabled) it decides the background. */
460
+ uniformity?: Pick<BackgroundUniformity, "uniform" | "colorStd"> | null;
461
+ iod: number;
462
+ frameWidth: number;
463
+ frameHeight: number;
464
+ }
465
+ /**
466
+ * The per-criterion decision on one frame's measures — pure, the same rule as
467
+ * kyc-portrait and the native gates (packages/sekyro-contract/icao/conformance.json;
468
+ * limits are inclusive).
469
+ */
470
+ declare function judgeIcao(m: IcaoMeasures, t: ResolvedIcaoTuning): Record<IcaoJudgedCriterion, Measured>;
471
+ /** Openness of one eye from the Landmarker's blink blendshape (1 − blink). */
472
+ declare function eyeOpenness(blendshapes: Readonly<Record<string, number>> | null | undefined): {
473
+ left: number;
474
+ right: number;
475
+ blinkLeft: number;
476
+ blinkRight: number;
477
+ } | null;
478
+ /** The `p`-quantile (0..1) of a sample, nearest-rank. */
479
+ declare function percentile(values: readonly number[], p: number): number | null;
480
+ /** Score one frame against the limits. Pure; `baseline` is the eye baseline so far. */
481
+ declare function scoreFrame(frame: IcaoFrameObservation, t: ResolvedIcaoTuning, baseline: number | null): {
482
+ results: Record<IcaoGateCriterion, Measured>;
483
+ pose: HeadPose | null;
484
+ };
485
+ interface IcaoGate {
486
+ push(frame: IcaoFrameObservation, nowMs: number): IcaoGateUpdate;
487
+ /** The last update (`null` before the first frame). */
488
+ last(): IcaoGateUpdate | null;
489
+ /** The submission's `gate` block from the last update. */
490
+ summary(): IcaoGateSummary;
491
+ /** Start the holds over (a retake). The eye baseline is kept: it describes the person. */
492
+ reset(): void;
493
+ }
494
+ interface IcaoGateOptions {
495
+ /** `alert`: coaching only — ready `alertGraceMs` after the face was accepted at the latest. Default `reject`. */
496
+ policy?: "reject" | "alert";
497
+ }
498
+ declare function createIcaoGate(t: ResolvedIcaoTuning, options?: IcaoGateOptions): IcaoGate;
499
+
500
+ export { lumaPlane as A, type BackgroundStats as B, CLIPPED_LUMA as C, percentile as D, portraitCropRegion as E, type FaceGeometry as F, poseFromMatrix as G, type HeadPose as H, type IcaoCoachKey as I, regionStats as J, scoreFrame as K, type LumaPlane as L, windowOverflow as M, HostedClient as N, type HostedClientOptions as O, type Point as P, type MediaCheckType as Q, type RegionStats as R, type SubmitOptions as S, stripMimeParams as T, type UploadMedia as U, type IcaoCriterionState as a, type IcaoGateCriterion as b, type IcaoGateSummary as c, type IcaoGateUpdate as d, type Box as e, type FaceLighting as f, ICAO_CANVAS as g, ICAO_GATE_CRITERIA as h, ICAO_SHARP_REF as i, type IcaoFrameObservation as j, type IcaoGate as k, type IcaoGateOptions as l, type IcaoJudgedCriterion as m, type IcaoMeasures as n, type IcaoPixelStats as o, backgroundStats as p, createIcaoGate as q, eyeLineRoll as r, eyeOpenness as s, eyeSpecular as t, faceGeometry as u, faceLighting as v, faceSharpness as w, icaoPixelStats as x, icaoWindow as y, judgeIcao as z };