@sekyro/web 0.1.0-rc.7 → 0.1.0-rc.8

package/dist/icao-gate-D8qm1O2t.d.cts

@@ -0,0 +1,1655 @@
+interface Point {
+    x: number;
+    y: number;
+}
+interface Box {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The face geometry the gate needs, in SOURCE (stream) pixels. */
+interface FaceGeometry {
+    /** Eye centres, ordered by image x (`left` = smaller x). */
+    leftEye: Point;
+    rightEye: Point;
+    /** Inter-ocular distance (px). */
+    iod: number;
+    /** Bounding box of the landmark mesh (forehead to chin). */
+    box: Box;
+    /** Nose tip (landmark 1): splits the face into halves for the lighting ratio. */
+    nose: Point;
+    /** Eye-contour boxes (glare), same order as the eyes. */
+    leftEyeBox: Box;
+    rightEyeBox: Box;
+}
+/**
+ * Normalised Face Landmarker landmarks (0..1) → source-pixel geometry.
+ * `null` when the mesh is too short to carry the eyes.
+ */
+declare function faceGeometry(landmarks: readonly Point[], width: number, height: number): FaceGeometry | null;
+interface HeadPose {
+    yaw: number;
+    pitch: number;
+    roll: number;
+}
+/**
+ * Yaw / pitch / roll (degrees) of the Face Landmarker's facial transformation
+ * matrix (4×4, `layout` of `data`; MediaPipe emits column-major). Rotation
+ * order R = Rz(roll)·Ry(yaw)·Rx(pitch): yaw turns about the vertical axis,
+ * pitch nods, roll tilts. Only magnitudes are gated, so sign conventions never
+ * change a verdict. `null` for a malformed matrix.
+ */
+declare function poseFromMatrix(data: readonly number[], layout?: "column" | "row"): HeadPose | null;
+/** Roll from the eye line (degrees) — the fallback when no matrix is available. */
+declare function eyeLineRoll(g: Pick<FaceGeometry, "leftEye" | "rightEye">): number;
+/** The ICAO canvas (icao.py): 480×640, eye midpoint at x = 240, eye line at y = 289, IOD 120–160. */
+declare const ICAO_CANVAS: {
+    readonly width: 480;
+    readonly height: 640;
+    readonly eyeX: 240;
+    readonly eyeY: 289;
+    readonly iodMin: 120;
+    readonly iodMax: 160;
+};
+/**
+ * The source-pixel window the server's ICAO crop is cut from: scale 1 when the
+ * IOD already lies in 120–160, else the scale that brings it to 120 (icao.py:
+ * "120 when outside the band"), the eye midpoint at (240, 289) of the window.
+ */
+declare function icaoWindow(g: Pick<FaceGeometry, "leftEye" | "rightEye" | "iod">): Box;
+/** How far a window spills outside the frame (0 = inside), as a fraction of its size. */
+declare function windowOverflow(window: Box, frameWidth: number, frameHeight: number): number;
+/**
+ * The region of the full-resolution still the SDK uploads: the ICAO window
+ * grown by `margin` about its centre (so the server re-crops with its own
+ * landmarks), at least `minWidth × minHeight`, 3:4 portrait, then fitted into
+ * the frame — the margin shrinks first, then the box slides inside, and only
+ * a window larger than the frame is cut to it. Integer pixels.
+ */
+declare function portraitCropRegion(g: Pick<FaceGeometry, "leftEye" | "rightEye" | "iod">, frameWidth: number, frameHeight: number, opts: {
+    margin: number;
+    minWidth: number;
+    minHeight: number;
+}): Box;
+
+/** Server-tunable thresholds (`capture.icao.backgroundCheck`); defaults below. */
+interface BackgroundCheckTuning {
+    /** Run the check at all (ICAO on). Default `true`. */
+    enabled: boolean;
+    /** Measurements per second (the face gate runs faster). Default 3. */
+    hz: number;
+    /** The segmenter must load within this window, else the strip fallback. Default 8000 ms. */
+    segmenterTimeoutMs: number;
+    /** A segmentation slower than this (moving average) switches to the strip fallback. Default 120 ms. */
+    segmenterBudgetMs: number;
+    /** Person confidence at or above this is the person (excluded). Default 0.5. */
+    maskThreshold: number;
+    /** Max RMS colour standard deviation (0..255). Default 28. */
+    maxColorStd: number;
+    /** Max share of textured neighbour pairs (0..1). Default 0.08. */
+    maxEdgeDensity: number;
+    /** Luma step (0..255) that counts as an edge. Default 24. */
+    edgeLuma: number;
+    /** Max left/right or top/bottom brightness difference (0..1). Default 0.18. */
+    maxGradient: number;
+    /** Fewer background pixels than this = not measurable (never blocks). Default 300. */
+    minPixels: number;
+    /** A non-uniform background holds the shot at most this long, then the shot proceeds. Default 4000 ms. */
+    timeoutMs: number;
+}
+/** Person confidence per pixel (0..1 floats, or 0..255 bytes), any resolution (scaled to the frame). */
+interface PersonMask {
+    data: Float32Array | Uint8Array | Uint8ClampedArray;
+    width: number;
+    height: number;
+}
+/** One measurement — numbers only (telemetry and the `gate` block). */
+interface BackgroundUniformity {
+    method: "segmenter" | "strip";
+    uniform: boolean;
+    colorStd: number;
+    edgeDensity: number;
+    gradient: number;
+    /** Background pixels measured (after sampling). */
+    pixels: number;
+}
+
+/** The device (coaching) limits of each profile — the server limits moved towards strict. */
+declare const ICAO_DEVICE_LIMITS: {
+    readonly id_document: {
+        readonly pose: {
+            readonly yawDeg: 7;
+            readonly pitchDeg: 7;
+            readonly rollDeg: 5;
+            readonly pitchOffsetDeg: 4;
+        };
+        readonly eyes: {
+            readonly relativeMin: 0.62;
+            readonly blinkMax: 0.48;
+        };
+        readonly mouth: {
+            readonly jawOpenMax: 0.13;
+            readonly smileMax: 0.28;
+            readonly puckerMax: 0.28;
+        };
+        readonly lighting: {
+            readonly faceLuma: readonly [95, 185];
+            readonly halfRatio: readonly [0.77, 1.31];
+            readonly clippedMax: 0.015;
+        };
+        readonly background: {
+            readonly required: true;
+            readonly lumaMin: 165;
+            readonly lumaSdMax: 20;
+        };
+        readonly resolution: {
+            readonly minIodPx: 110;
+            readonly minWidth: 480;
+            readonly minHeight: 640;
+        };
+    };
+    readonly selfie: {
+        readonly pose: {
+            readonly yawDeg: 7;
+            readonly pitchDeg: 7;
+            readonly rollDeg: 7;
+            readonly pitchOffsetDeg: 4;
+        };
+        readonly eyes: {
+            readonly relativeMin: 0.62;
+            readonly blinkMax: 0.48;
+        };
+        readonly mouth: {
+            readonly jawOpenMax: 0.13;
+            readonly smileMax: 0.28;
+            readonly puckerMax: 0.28;
+        };
+        readonly lighting: {
+            readonly faceLuma: readonly [95, 185];
+            readonly halfRatio: readonly [0.77, 1.31];
+            readonly clippedMax: 0.015;
+        };
+        readonly background: {
+            readonly required: false;
+            readonly lumaMin: 165;
+            readonly lumaSdMax: 20;
+        };
+        readonly resolution: {
+            readonly minIodPx: 100;
+            readonly minWidth: 480;
+            readonly minHeight: 640;
+        };
+    };
+};
+
+/** The ICAO threshold set (`id_document`: ID photo; `selfie`: no background rule). */
+type IcaoProfile = keyof typeof ICAO_DEVICE_LIMITS;
+/** `capture.icao` as the server sends it (every field optional on the wire). */
+interface IcaoCaptureTuning {
+    /** The threshold set these limits come from (default `id_document`; it also picks the fallbacks). */
+    profile?: "id_document" | "selfie";
+    yawDeg?: number;
+    pitchDeg?: number;
+    /**
+     * Subtracted from the measured pitch before `pitchDeg` applies (degrees). Where
+     * "looking straight" sits relative to the Landmarker's zero; kyc-portrait applies the
+     * same `PORTRAIT_POSE_PITCH_OFFSET_DEG`, so keep them equal (D9a, 2026-10-22).
+     */
+    pitchOffsetDeg?: number;
+    rollDeg?: number;
+    holdMs?: number;
+    /** `alert` policy: the clip starts this long after the face was accepted even if the ICAO gate is not ready (default 3000). */
+    alertGraceMs?: number;
+    eyes?: {
+        relativeMin?: number;
+        blinkMax?: number;
+        earMin?: number;
+    };
+    mouth?: {
+        jawOpenMax?: number;
+        smileMax?: number;
+        puckerMax?: number;
+    };
+    lighting?: {
+        faceLuma?: [number, number];
+        halfRatio?: [number, number];
+        clippedMax?: number;
+    };
+    /** `required: false` (the `selfie` profile): the background is not evaluated, coached or reported. */
+    background?: {
+        required?: boolean;
+        lumaMin?: number;
+        lumaSdMax?: number;
+    };
+    resolution?: {
+        minIodPx?: number;
+        minWidth?: number;
+        minHeight?: number;
+    };
+    /** Client-only knobs (no server field today; read when the server adds them). */
+    holdFrames?: number;
+    cadenceHz?: number;
+    baseline?: {
+        windowMs?: number;
+        minSamples?: number;
+        percentile?: number;
+    };
+    sharpnessMin?: number;
+    glare?: {
+        specularMax?: number;
+    };
+    softGraceMs?: number;
+    cropMargin?: number;
+    camera?: {
+        width?: number;
+        height?: number;
+    };
+    /**
+     * The client background-uniformity check (ID mode; defaults in
+     * core/portrait/background-uniformity.ts `BACKGROUND_CHECK_DEFAULTS`).
+     * Skipped entirely when `background.required` is false.
+     */
+    backgroundCheck?: Partial<BackgroundCheckTuning>;
+}
+/** Fully resolved limits the gate runs on. */
+interface ResolvedIcaoTuning {
+    profile: IcaoProfile;
+    yawDeg: number;
+    pitchDeg: number;
+    pitchOffsetDeg: number;
+    rollDeg: number;
+    holdMs: number;
+    alertGraceMs: number;
+    eyes: {
+        relativeMin: number;
+        blinkMax: number;
+    };
+    mouth: {
+        jawOpenMax: number;
+        smileMax: number;
+        puckerMax: number;
+    };
+    lighting: {
+        faceLuma: [number, number];
+        halfRatio: [number, number];
+        clippedMax: number;
+    };
+    background: {
+        required: boolean;
+        lumaMin: number;
+        lumaSdMax: number;
+    };
+    resolution: {
+        minIodPx: number;
+        minWidth: number;
+        minHeight: number;
+    };
+    holdFrames: number;
+    cadenceHz: number;
+    baseline: {
+        windowMs: number;
+        minSamples: number;
+        percentile: number;
+    };
+    sharpnessMin: number;
+    glare: {
+        specularMax: number;
+    };
+    softGraceMs: number;
+    cropMargin: number;
+    camera: {
+        width: number;
+        height: number;
+    };
+    backgroundCheck: BackgroundCheckTuning;
+    /** The server's `capture.tuningVersion`, echoed on submit (`null` when absent). */
+    tuningVersion: string | null;
+}
+/** Bundled fallbacks: the `id_document` device limits (never looser than the server). */
+declare const ICAO_FALLBACK: Omit<ResolvedIcaoTuning, "tuningVersion">;
+/**
+ * Resolve `capture.icao` (any shape, possibly absent) over {@link ICAO_FALLBACK},
+ * field by field: an out-of-range or malformed field keeps its fallback.
+ */
+declare function resolveIcaoTuning(raw: unknown, tuningVersion?: unknown): ResolvedIcaoTuning;
+
+/** Session lifecycle status (spec §4 two-field status/outcome model). */
+type SessionStatus = "created" | "in_progress" | "review_pending" | "completed" | "expired" | "failed";
+/** Terminal verdict, orthogonal to `status`; `null` until terminal/review. */
+type SessionOutcome = "approved" | "review" | "rejected";
+/** Per-check seven-state machine (spec §4.3). */
+type CheckState = "pending" | "input_required" | "processing" | "passed" | "failed" | "review" | "skipped";
+/**
+ * The frozen check-type vocabulary (CHECK_TYPES). `phone_otp` joined in Task 13;
+ * `nfc_chip` (M-nfc) is read by the native SDKs only; `email_otp` (Plan 8,
+ * profile v2 §4.6.5) confirms an email address with a one-time code;
+ * `eid_auth` (SDK spec §3.2) is the national eID sign-in (Houwiyeti in MR).
+ */
+type CheckType = "liveness" | "face_match" | "doc_ocr" | "population_registry" | "phone_otp" | "nfc_chip" | "email_otp" | "portrait_icao" | "eid_auth";
+type LivenessReason = "no_face" | "media_unreadable" | "clip_too_short" | "spoof_detected" | "review_band" | "liveness_inconclusive" | "device_integrity_failed" | "mobile_required" | "uncalibrated_capture_channel";
+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";
+type FaceMatchReason = "no_face_source" | "no_face_reference" | "low_quality_reference" | "below_threshold" | "review_band" | "match_inconclusive" | "subject_revoked" | "probe_not_from_liveness";
+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";
+/**
+ * Profile v2 step 3 matching reasons: a field the partner sent at session
+ * create (`subject`) differs from the reference identity (document or
+ * registry). All four are final. `document_number_mismatch` is `doc_ocr` only.
+ */
+type MatchReason = "name_mismatch" | "birth_date_mismatch" | "nationality_mismatch" | "document_number_mismatch";
+/**
+ * Profile v2 step 4 decision-mode reasons (the app decides automatically
+ * instead of sending the case to human review). These park the step at
+ * `input_required` while attempts remain: `liveness_inconclusive` /
+ * `match_inconclusive` (middle score band) and `document_authenticity`
+ * (retake the original card). `mobile_required` is kept for compatibility:
+ * the backend now answers a non-phone capture with a request-level
+ * `409 mobile_required` (continue on a phone; nothing used, not billed).
+ */
+type DecisionReason = "liveness_inconclusive" | "match_inconclusive" | "document_authenticity" | "mobile_required";
+/**
+ * phone_otp reasons (Task 13). All transient — the caller fixes them by
+ * re-entering / resending: `otp_mismatch` (wrong or missing code),
+ * `otp_expired` (code lapsed or no active send), `otp_send_failed` (the OTP
+ * service was unreachable / a send returned no token).
+ */
+type PhoneOtpReason = "otp_mismatch" | "otp_expired" | "otp_send_failed" | "otp_channel_unavailable" | "otp_destination_not_allowed" | "otp_rate_limited" | "otp_destination_unknown";
+/**
+ * email_otp reasons (Plan 8, profile v2 §4.6.5). All transient: a wrong or
+ * expired code, a send outage, too many sends, an address that cannot receive
+ * mail (`email_invalid`), or a disposable address the app blocks
+ * (`email_disposable`) — the person enters another address or resends.
+ */
+type EmailOtpReason = "otp_mismatch" | "otp_expired" | "otp_send_failed" | "otp_rate_limited" | "email_invalid" | "email_disposable";
+/**
+ * nfc_chip reasons (M-nfc, SDK spec §4.3). Native SDKs read the chip; the web
+ * never does — on web the step arrives `skipped` (`platform_unsupported`) or
+ * the session shows `failureReason: 'platform_unsupported'`.
+ */
+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";
+/**
+ * eid_auth reasons (SDK spec §3.2, generic national eID; Houwiyeti in MR).
+ * Retryable: `eid_identifier_invalid` (re-enter the number), `eid_code_invalid`
+ * (re-enter the code, see `eid.codeAttemptsRemaining`), `eid_code_expired`
+ * (ask for a new code), `eid_unavailable` (the provider is down; try again or
+ * use the camera), `eid_resend_too_soon` (wait for `eid.resendAvailableAt`),
+ * `eid_resend_limit` (no more codes; type the last code received).
+ * Final: `eid_locked` (too many wrong codes), `eid_not_enrolled` (the number
+ * has no account in the provider's app).
+ * With `eid_not_enrolled`, `eid_unavailable` or `eid_locked` the person may
+ * switch to the camera path when the session offers it.
+ */
+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";
+/**
+ * Any frozen reason code. The backend declares the field `string`, but the
+ * taxonomy is frozen (do-not-drift) — the union IS the contract. NB: liveness
+ * and face_match both carry `review_band`.
+ */
+type CheckReason = LivenessReason | PopulationReason | FaceMatchReason | DocReason | PhoneOtpReason | EmailOtpReason | NfcChipReason | PortraitIcaoReason | EidReason;
+/**
+ * Session-level failure reasons: the session was stopped by a policy gate,
+ * not by a failed check. All are terminal (no retry on this session):
+ *  - `location_not_allowed` / `anonymizer_blocked` (profile v2 step 2): the
+ *    person's IP location is not allowed, or an anonymizer (VPN / proxy / Tor)
+ *    was detected while the app blocks them;
+ *  - `capture_tampered` (step 4): the device reported a tampered capture
+ *    (virtual camera, hooking, emulator…) while the app blocks it;
+ *  - `device_velocity_exceeded` (step 4): this device already verified too
+ *    many different people while the app blocks it;
+ *  - `device_cooldown` (step 4): this device had too many rejected sessions —
+ *    {@link HostedSessionView.retryAfter} says when it may try again;
+ *  - `platform_unsupported` (M-nfc): a chip read is required and this client
+ *    can't read one (web); the session stays open for a native app.
+ */
+type SessionFailureReason = "location_not_allowed" | "anonymizer_blocked" | "capture_tampered" | "device_velocity_exceeded" | "device_cooldown" | "platform_unsupported";
+/**
+ * The profile-v2 policy reasons a session can end on: the two session-level
+ * reasons plus the failed check's policy reasons (`document_type_not_accepted`,
+ * `nationality_not_allowed`, `underage`, `age_unverifiable`,
+ * `document_nni_mismatch`).
+ */
+type PolicyFailureReason = SessionFailureReason | "document_type_not_accepted" | "nationality_not_allowed" | "underage" | "age_unverifiable" | "document_nni_mismatch";
+/**
+ * How the person proves their identity when the app makes the document
+ * optional for registry nationals (profile v2 step 3): type their national
+ * number (NNI) and skip the document, or photograph their document.
+ * `document_chip` is offered only to native clients with NFC (M-nfc).
+ * `national_eid` (SDK spec §3.2) signs in with the country's national eID
+ * (Houwiyeti in MR) instead of the camera path — see
+ * {@link MethodChoiceView.nationalEid}.
+ */
+type IdentityMethod = "national_number" | "document_photo" | "document_chip" | "national_eid";
+/**
+ * The national eID provider a session offers (`MethodChoiceView.nationalEid`).
+ * `provider` is `{ISO2}.{provider}` (e.g. `MR.houwiyeti`); `providerName` is
+ * the display name ("Houwiyeti").
+ */
+interface NationalEidOption {
+    provider: string;
+    providerName: string;
+    /** ISO 3166-1 alpha-2 country of the provider. */
+    country: string;
+    /**
+     * What follows a passed eID (flow model 2026-10-23): `end` (the session ends,
+     * the default) or `continue` (the live photo follows). Absent on older APIs = `end`.
+     */
+    afterPass?: EidAfterPass;
+}
+/** What follows a passed national eID (`nationalEid.afterPass`). */
+type EidAfterPass = "end" | "continue";
+/**
+ * The section a step belongs to (flow model 2026-10-23, SDK spec §3.7): Step 1
+ * `contact`, Step 2 `identity`, Step 3 `live_photo`. Open: a value this SDK
+ * does not know is kept as is, so a client still places the step.
+ */
+type StepSection = "contact" | "identity" | "live_photo" | (string & {});
+/** A contact channel of a `one_of` session (`otpChoice.options`). */
+type ContactChannel = "phone" | "email";
+/**
+ * Step 1 contact choice (`HostedSessionView.otpChoice`), present only on a
+ * `contact.mode = one_of` session: the person confirms a phone number OR an
+ * email address. `selected` is `null` until they choose
+ * ({@link HostedClient.selectContact}, or implicitly with the first OTP
+ * submission); `locked` once a contact step passed.
+ */
+interface OtpChoiceView {
+    options: ContactChannel[];
+    selected: ContactChannel | null;
+    locked: boolean;
+}
+/** Where the identity summary's data came from. */
+type IdentitySummarySource = "registry" | "document" | "chip";
+/**
+ * Step 2b summary and confirm (`HostedSessionView.identitySummary`): the
+ * identity data read so far, shown to the person before the live photo. Only
+ * on the session-token view and only while the confirmation is pending; masks
+ * keep the last 4 characters. Never log or store these values.
+ */
+interface IdentitySummaryView {
+    /**
+     * `full` (document / chip: the record and the photo) or `partial` (the
+     * registry from a typed NNI: the short name "Mohamed S.", the birth year,
+     * the NNI's last 4, no photo).
+     */
+    kind: "full" | "partial" | (string & {});
+    source: IdentitySummarySource | (string & {});
+    /** The full name (`full`), or the short form "Mohamed S." (`partial`). */
+    fullName?: string;
+    /** `YYYY-MM-DD` (`full`). */
+    birthDate?: string;
+    /** `YYYY` (`partial`). */
+    birthYear?: string;
+    /** ISO 3166-1 alpha-2 (or alpha-3) nationality. */
+    nationality?: string;
+    documentType?: string;
+    documentNumberMasked?: string;
+    nniMasked?: string;
+    /** `YYYY-MM-DD`. */
+    expiryDate?: string;
+    /** A portrait can be fetched ({@link HostedClient.identityPortrait}). */
+    portrait: {
+        available: boolean;
+    };
+    /** A retake is still possible (attempts left, not a `supplied` summary). */
+    retakeAvailable: boolean;
+    /** What a retake re-opens. */
+    retakeTarget?: "document" | "national_number" | (string & {});
+}
+/** The answer to the identity summary ({@link HostedClient.confirmIdentity}). */
+type IdentityConfirmDecision = "confirm" | "retake";
+/**
+ * The identity-method choice of a session (`HostedSessionView.methodChoice`).
+ * While `available && selected === null` no check can be submitted (409
+ * `method_required`): the page asks first and sends the answer with
+ * `POST /hosted/method` ({@link HostedClient.selectMethod}).
+ */
+interface MethodChoiceView {
+    /** The session offers the choice (the app's document mode is `optional`). */
+    available: boolean;
+    /** The chosen method, or `null` while the person has not chosen. */
+    selected: IdentityMethod | null;
+    /** The methods to offer, in display order (`national_eid` first when offered). */
+    options: IdentityMethod[];
+    /**
+     * The national eID provider behind the `national_eid` option ("Verify with
+     * Houwiyeti"). Absent when the option is not offered (and on older APIs).
+     */
+    nationalEid?: NationalEidOption;
+}
+/** A document type the backend reads (kyc-docs-v2 vocabulary; `carte_identite` = identity card of any issuer). */
+type AcceptedDocumentType = "carte_identite" | "passport" | "residence_permit";
+/**
+ * Accepted document types per issuing country (profile v2 §5.3a): an issuer
+ * uses `byIssuer[iso2] ?? default`; `"*"` = every type.
+ */
+interface HostedAcceptedDocuments {
+    default: "*" | AcceptedDocumentType[];
+    byIssuer?: Record<string, AcceptedDocumentType[]>;
+}
+/**
+ * phone_otp DISPLAY-SAFE surface (Task 16). The backend stashes the OTP
+ * service `verifToken` on the check's persisted outputs (the doc_ocr partial
+ * mechanism), but that token is NEVER projected here — only the fields the
+ * hosted OTP step renders. `numberSource` (org-authored config) drives the
+ * send-phase UI (prefilled display vs entry); the rest appear ONLY once a send
+ * has parked the check (`sentToMasked` present ⇒ verify phase).
+ */
+interface HostedOtpView {
+    /**
+     * Per-step `config.numberSource` — drives the send-phase UI (prefilled
+     * display vs entry). Narrowed to the frontend contract; the backend field is
+     * `string` (dynamic config) but the projection only ever emits these three.
+     */
+    numberSource?: "prefilled" | "user_entered" | "prefilled_or_entered";
+    /** Masked target the last send went to (e.g. `+222 ** ** 34 56`); absent pre-send. */
+    sentToMasked?: string;
+    /** Delivery channel of the last send. */
+    channel?: "sms" | "whatsapp";
+    /** ISO-8601 OTP expiry from the last send — drives the verify-phase countdown. */
+    expiresAt?: string;
+    /**
+     * Profile v2 §4.6.4: the channels the person may choose from, in display
+     * order (WhatsApp first; a channel the org or app turned off is absent).
+     * Absent on a session created before channel choice (no picker; SMS).
+     */
+    channels?: ("whatsapp" | "sms")[];
+    /** ISO-8601 end of the server-side resend cooldown (after a send). */
+    resendAvailableAt?: string;
+}
+/**
+ * email_otp DISPLAY-SAFE surface (Plan 8, profile v2 §4.6.5): never the
+ * provider handle, never the address (only its mask).
+ */
+interface HostedEmailOtpView {
+    /** Where the address comes from; drives the send-phase UI (notice vs entry). */
+    emailSource?: "prefilled" | "user_entered" | "prefilled_or_entered";
+    /** Masked target of the last send (e.g. `a•••@e•••.com`); absent pre-send. */
+    sentToMasked?: string;
+    /** ISO-8601 code expiry from the last send. */
+    expiresAt?: string;
+    /** ISO-8601 end of the server-side resend cooldown (after a send). */
+    resendAvailableAt?: string;
+}
+/**
+ * portrait_icao reasons (SDK spec §4.9, ID mode). The first failing ICAO
+ * criterion; every one is retryable (re-run only the ICAO gate).
+ * `media_unreadable` (no report) is shared with liveness.
+ */
+type PortraitIcaoReason = "icao_pose" | "icao_eyes" | "icao_mouth" | "icao_occlusion" | "icao_lighting" | "icao_background" | "icao_resolution" | "portrait_not_from_liveness";
+/** One ICAO criterion of the server's portrait report (SDK spec §4.9). */
+type IcaoCriterion = "pose" | "eyes" | "mouth" | "occlusion" | "glare" | "lighting" | "background" | "resolution";
+/** The ICAO policy of a session's selfie (spec 2026-10-24 selfie ICAO policy §10). */
+interface HostedIcaoPolicy {
+    /** `reject`: the gate blocks and the server asks for retakes; `alert`: coaching only, never blocking. */
+    policy: "reject" | "alert";
+    /** The threshold set: `id_document` (ID photo, uniform background) or `selfie` (no background rule). */
+    profile: "id_document" | "selfie";
+}
+/** `HostedSessionView.portrait`. */
+type HostedPortraitView = NonNullable<HostedSessionView["portrait"]>;
+/** One row of the portrait_icao report: the server's measurement — coaching only. */
+interface IcaoReportEntry {
+    criterion: IcaoCriterion;
+    value: number | null;
+    threshold: number | string | null;
+    pass: boolean;
+}
+/**
+ * eid_auth DISPLAY-SAFE surface (SDK spec §3.2): never the identifier, never
+ * the code. `awaiting` drives the screen: `identifier` (type the national
+ * number, unless `identifierBound`) → `code` (type the code shown in the
+ * provider's app).
+ */
+interface HostedEidView {
+    /** `{ISO2}.{provider}`, e.g. `MR.houwiyeti`. */
+    provider: string;
+    /** Display name, e.g. "Houwiyeti". */
+    providerName: string;
+    /** ISO 3166-1 alpha-2 country of the provider. */
+    country: string;
+    /** `app_code`: the provider's app shows a code the person types here (the only challenge today). */
+    challenge: "app_code";
+    awaiting: "identifier" | "code";
+    /** The session is bound to the national number — `start` sends no identifier. */
+    identifierBound: boolean;
+    /** ISO-8601 expiry of the current code. */
+    expiresAt?: string;
+    /** ISO-8601 time from which a new code may be asked for. */
+    resendAvailableAt?: string;
+    /** New codes the person may still ask for in this session. */
+    resendsRemaining?: number;
+    /** Wrong codes left before `eid_locked`. */
+    codeAttemptsRemaining?: number;
+    /** What follows a pass (flow model 2026-10-23); absent = `end`. */
+    afterPass?: EidAfterPass;
+}
+/** `nfc_chip` step hints (M-nfc). `chipHint` is UI copy only, never a gate. */
+interface NfcStepView {
+    mode: "preferred" | "mandatory";
+    access: ("PACE" | "BAC")[];
+    optionalDataGroups: ("DG11" | "DG12" | "DG13")[];
+    chipHint: {
+        default: Record<string, true | "unknown">;
+        byIssuer: Record<string, Record<string, true | "unknown">>;
+    };
+}
+/**
+ * Per-check projection in a {@link HostedSessionView} — the spec'd hosted step
+ * shape. NEVER carries `calibratedScore` or the raw check `outputs`; the only
+ * output-derived data is the phone_otp `HostedOtpView` display subset
+ * (masked number/channel/expiry — never the verifToken).
+ */
+interface HostedStepView {
+    checkType: CheckType;
+    state: CheckState;
+    /** Frozen-taxonomy reason code explaining a `failed`/`review` state. */
+    reason?: CheckReason;
+    /**
+     * Submissions the page may still make for this check (`max(0, cap - attempts)`).
+     * Meaningful only while the check is executable — a finalized check may still
+     * report more than 0, but re-submitting it 409s regardless.
+     */
+    attemptsRemaining: number;
+    /** doc_ocr only: sides already accepted into the partial accumulator (['recto'] or ['verso']). */
+    acceptedSides?: ("recto" | "verso")[];
+    /** phone_otp only: the display-safe OTP send/config surface (never the verifToken). */
+    otp?: HostedOtpView;
+    /** email_otp only: the display-safe email send surface (never the handle or the address). */
+    emailOtp?: HostedEmailOtpView;
+    /**
+     * The check failed after using all of its attempts — no retry is left.
+     * Absent on older APIs (treat absent as `false`).
+     */
+    attemptsExhausted?: boolean;
+    /**
+     * population_registry only: the session is not bound to an NNI, but the
+     * document step already read a valid one — the page submits the registry
+     * check with an EMPTY input (no NNI field) and the backend uses the
+     * document's number. Absent on older APIs.
+     */
+    nniFromDocument?: boolean;
+    /**
+     * liveness / face_match (profile v2 step 4, decision mode `automatic`): the
+     * capture must come from a phone — the liveness band is calibrated on
+     * mobile captures only. A desktop page hands the person off to their phone
+     * instead of capturing (a desktop submission answers `mobile_required`).
+     * Absent on older APIs and in `review` mode.
+     */
+    requiresMobile?: boolean;
+    /** nfc_chip only (M-nfc). */
+    nfc?: NfcStepView;
+    /** portrait_icao only (SDK spec §4.9): the last attempt's per-criterion report. */
+    icao?: {
+        report: IcaoReportEntry[];
+    };
+    /** eid_auth only (SDK spec §3.2): the display-safe eID surface. */
+    eid?: HostedEidView;
+    /**
+     * The section of the flow this step belongs to (flow model 2026-10-23).
+     * Absent on older APIs (derive it from the check type).
+     */
+    section?: StepSection;
+    /**
+     * doc_ocr only, on an open step: the client reads the chip next, so the MRZ is
+     * read on device for the chip key (`mrz_for_chip`). Native NFC clients only.
+     */
+    docCapture?: {
+        mode: "mrz_for_chip" | (string & {});
+    };
+}
+/** A locale the Sekyro AI-hosted voice clips are recorded in. */
+type HostedVoiceLocale = "ar" | "fr" | "en";
+/**
+ * The session's Sekyro AI-hosted voice-guidance clips (the active clip set).
+ *
+ * `clips[locale]` maps a voice key (`fcv3.*`, the `@sekyro/react` voice-key
+ * namespace) to an ABSOLUTE URL on the Sekyro AI assets host
+ * (`https://assets.sekyro.ai/voice/<setId>/<locale>/<name>.mp3`; staging:
+ * `assets-staging.sekyro.ai`). URLs are immutable per `setId`. A locale or key
+ * may be missing — the player falls back to the device voice for it.
+ *
+ * A page with a Content-Security-Policy must allow the assets origin in
+ * `media-src` for the clips to play (see the partner web-SDK guide, CSP note).
+ */
+interface HostedVoiceView {
+    /** Identifier of the active clip set (part of every clip URL). */
+    setId: string;
+    /** Per-locale map of voice key (`fcv3.*`) → absolute clip URL. */
+    clips: {
+        readonly [L in HostedVoiceLocale]?: Readonly<Record<string, string>>;
+    };
+}
+/** A branding colour key (each value is `#rrggbb`). */
+type HostedBrandingColorKey = "brand" | "brandFg" | "bg" | "surface" | "fg" | "fgMuted" | "danger" | "success" | "warning";
+/**
+ * The org / app branding of a session (`HostedSessionView.branding`): only the
+ * fields set in the dashboard, merged per field (app over org). A field the
+ * org and app left unset is ABSENT — keep your default for it; the whole
+ * object is absent when nothing is set. `logoUrl` is a short-lived signed URL
+ * (15 minutes).
+ */
+interface HostedBranding {
+    /** Signed URL of the logo (PNG or sanitized SVG); absent when none is set. */
+    logoUrl?: string;
+    /** Colours as `#rrggbb`. */
+    colors?: Partial<Record<HostedBrandingColorKey, string>>;
+    /** Corner radius step. */
+    radius?: "none" | "sm" | "md" | "lg" | "full";
+    /** Font choice (system fallbacks when the font is not installed). */
+    fontFamily?: "system" | "inter" | "ibm-plex-sans-arabic" | "noto-sans-arabic" | "roboto";
+}
+/**
+ * Token-addressed hosted-page bootstrap (`GET /hosted/session`). A separate
+ * shape from the partner `SessionView`: `sessionId` instead of `id`,
+ * hosted step hints, the consent flag, and the org display name (may be `''`
+ * when the org lookup degrades).
+ */
+/**
+ * Server-delivered capture tuning (`HostedSessionView.capture`, SDK spec §3.5).
+ * Coaching values only. `@sekyro/web` does not apply it yet (its built-in v3
+ * values stay in force until the adopting minor release); native SDKs apply it
+ * field by field over their bundled fallbacks and ignore unknown fields.
+ */
+interface HostedCaptureTuning {
+    tuningVersion?: string;
+    liveness?: Record<string, unknown>;
+    document?: Record<string, unknown>;
+    /** SDK spec §5.4 ID mode: the strict ICAO gate's coaching limits (present with `portrait`). */
+    icao?: IcaoCaptureTuning;
+    /**
+     * Step 3 one-capture live photo (flow model 2026-10-23): one camera session
+     * records the clip AND a full-resolution still (long side at least
+     * `still.minLongSidePx`, JPEG `still.jpegQuality`).
+     */
+    livePhoto?: HostedLivePhotoTuning;
+}
+/** `capture.livePhoto` (flow model 2026-10-23, Step 3). */
+interface HostedLivePhotoTuning {
+    oneCapture: boolean;
+    still: {
+        minLongSidePx: number;
+        jpegQuality: number;
+    };
+}
+/**
+ * {@link HostedCaptureTuning} with the native-only document fields typed. The wire shape is
+ * the same; `HostedSessionView.capture` stays the open {@link HostedCaptureTuning} so existing
+ * consumers keep compiling. Narrow it where the typed fields are read:
+ * `const capture = view.capture as HostedNativeCaptureTuning | undefined`.
+ */
+interface HostedNativeCaptureTuning extends HostedCaptureTuning {
+    document?: HostedDocumentCaptureTuning;
+}
+/**
+ * `capture.document`. Only the native-only fields the SDKs share a name for are typed;
+ * the rest (gate, aspect, upload, …) stay open. Web ignores the whole block.
+ */
+interface HostedDocumentCaptureTuning {
+    [field: string]: unknown;
+    /** Native document scan machine thresholds (web does not read them). */
+    scan?: HostedDocumentScanTuning;
+    /** Native on-device OCR tuning (web ignores it; SDK spec §5.2). */
+    ocr?: HostedOcrTuning;
+}
+/** `capture.document.scan` — native scan thresholds; only the blur gate is typed here. */
+interface HostedDocumentScanTuning {
+    [field: string]: unknown;
+    /** Blur gate: a captured photo whose native sharpness is under this is refused and retaken. */
+    blurRefuseSharpnessMax?: number;
+}
+/** `capture.document.ocr` — native on-device OCR tuning (web ignores it; SDK spec §5.2). */
+interface HostedOcrTuning {
+    enabledOnline?: boolean;
+    enabledOffline?: boolean;
+    warmup?: boolean;
+    maxDeviceLatencyMs?: number;
+    deviceTimeoutMs?: number;
+    minAvailMemoryMb?: number;
+    minConfidenceForRetake?: number;
+    minSegmentsForRetake?: number;
+    submitGraceMs?: number;
+    reportSampleRate?: number;
+    readBudgetMs?: number;
+    classifyBudgetMs?: number;
+    deferArabicOnline?: boolean;
+    detectorLimit?: number;
+    detectorThreadsMax?: number;
+    recognizerThreads?: number;
+    recognitionWorkersMax?: number;
+    linesInFlight?: number;
+    widestLineFirst?: boolean;
+    scriptRouting?: boolean;
+    arabicColumnFirst?: boolean;
+    confidentLatinScore?: number;
+    minLatinLetters?: number;
+    arabicColumnStart?: number;
+    arabicOnlyScore?: number;
+    portraitProbeLimit?: number;
+}
+/** Native device attestation parameters (`HostedSessionView.integrity`, SDK spec §6.7). Web ignores it. */
+interface HostedIntegrity {
+    mode: "off" | "signal" | "enforce";
+    android?: {
+        cloudProjectNumber: number;
+    };
+    ios?: {
+        appAttest: true;
+    };
+}
+interface HostedSessionView {
+    sessionId: string;
+    status: SessionStatus;
+    outcome: SessionOutcome | null;
+    steps: HostedStepView[];
+    /** ISO-8601 timestamp (Date on the server, string on the wire). */
+    expiresAt: string;
+    consentRecorded: boolean;
+    orgName: string;
+    /**
+     * The FIRST allowlisted web-SDK origin of the owning org (Task 12), or null
+     * when none is registered. The hosted page posts the SDK popup postMessage
+     * events (event name + sessionId ONLY) to exactly this origin — never `'*'`.
+     * The backend declares it required (`string | null`); optional here so
+     * pre-Task-12 consumers/fixtures stay valid (additive field, always on the
+     * wire from Task 12 onward).
+     */
+    sdkOrigin?: string | null;
+    /**
+     * Cloudflare Turnstile site key the browser must solve an execute-mode
+     * challenge against before submitting `liveness` (Plan A Task 5): the org's
+     * own widget key when the request origin is one of the org's allowlisted SDK
+     * origins, else the hosted widget key, else `null`. `null` means the session
+     * cannot be attested from the browser — the SDK sends `{sandbox: true}`,
+     * which the backend honours ONLY on sandbox sessions (fails closed on live).
+     */
+    turnstileSiteKey: string | null;
+    /**
+     * The session was minted with a server-bound NNI (`POST /sessions`
+     * `input.nni`, Plan A Task 2): `population_registry` is submitted with an
+     * EMPTY input and the backend reads the sealed value. `false` means the
+     * person must supply the NNI (hosted population form); the SDK never submits
+     * the registry check on an unbound session. The VALUE is never exposed. The
+     * backend declares it required; optional here so pre-Task-8 fixtures stay
+     * valid (additive field, always on the wire from Task 8 onward).
+     */
+    nniBound?: boolean;
+    /**
+     * The Sekyro AI-hosted voice-guidance clips of this session, or `null` when no
+     * clip set is active (the device voice is used). Optional: older APIs omit
+     * the field — treat absent like `null`.
+     */
+    voice?: HostedVoiceView | null;
+    /**
+     * Why the session ended, when a profile-v2 policy stopped it: a
+     * {@link SessionFailureReason}, or the failed check's reason when it is a
+     * policy reason (eligibility, or `document_nni_mismatch`). Absent otherwise
+     * (and on older APIs).
+     */
+    failureReason?: PolicyFailureReason;
+    /**
+     * The document types the person may pick, resolved for issuer `MR`,
+     * `carte_identite`/`passport` only (older pickers). Absent on older APIs —
+     * treat absent as both.
+     */
+    acceptedDocumentTypes?: AcceptedDocumentType[];
+    /**
+     * Accepted document types per issuing country — drives the issuer-first
+     * picker. Absent on older APIs (fall back to `acceptedDocumentTypes` for MR).
+     */
+    acceptedDocuments?: HostedAcceptedDocuments;
+    /**
+     * The identity-method choice (profile v2 step 3). Absent when the session
+     * has no choice (and on older APIs). While `available && selected === null`
+     * every check submission answers 409 `method_required`.
+     */
+    methodChoice?: MethodChoiceView;
+    /**
+     * ISO-8601 time from which this device may verify again — set with
+     * `failureReason: 'device_cooldown'` (profile v2 step 4). Absent otherwise
+     * (and on older APIs).
+     */
+    retryAfter?: string;
+    /**
+     * A returning-user session (profile v2 step 5): the person verified before
+     * and this session only confirms it is still them — liveness and a face
+     * match against their stored photo. Hosts read it to say "Confirm it's
+     * you". Absent on full sessions (and on older APIs).
+     */
+    returning?: true;
+    /**
+     * The org / app branding (settings spec §5.1). Absent on older APIs — keep
+     * the default theme. Map it with `brandingToTheme()` from `@sekyro/react`.
+     */
+    branding?: HostedBranding;
+    /** Capture coaching tuning (SDK spec §3.5). Absent on older APIs. */
+    capture?: HostedCaptureTuning;
+    /** Native device attestation parameters; absent for web-only apps and on older APIs. */
+    integrity?: HostedIntegrity;
+    /**
+     * SDK spec §3.5: present when the session runs the ICAO portrait step — the
+     * client runs the ICAO gate (read it with `icaoPolicyOf`). `icao` is absent on
+     * older servers, which send `{ purpose: "id_document" }` alone (= `reject`, `id_document`).
+     */
+    portrait?: {
+        purpose: "id_document";
+        /** Present whenever a `portrait_icao` step runs (absent on older servers): `reject` / `id_document`. */
+        icao?: HostedIcaoPolicy;
+    } | {
+        /** A verification selfie checked against the ICAO selfie rules (selfie ICAO policy). */
+        purpose: "verification";
+        icao: HostedIcaoPolicy;
+    };
+    /** Step 1 contact choice of a `one_of` session (flow model 2026-10-23). */
+    otpChoice?: OtpChoiceView;
+    /** Step 2b identity summary, present only while its confirmation is pending. */
+    identitySummary?: IdentitySummaryView;
+}
+/** `POST /hosted/consent` result — 201 on first record, 200 `{alreadyRecorded: true}` on replay. */
+interface RecordConsentResult {
+    alreadyRecorded: boolean;
+}
+/** Consent locale — the page's `[locale]` URL segment echoed back (HostedConsentSchema picklist). */
+type ConsentLocale = "ar" | "fr" | "en";
+/** Per-check projection in a {@link SessionView} — enum/id only, never civil data. */
+interface SessionStepView {
+    checkType: CheckType;
+    state: CheckState;
+    reason?: CheckReason;
+    calibratedScore?: number;
+    /** The check failed after using all of its attempts. Absent on older APIs. */
+    attemptsExhausted?: boolean;
+    /** portrait_icao only (SDK spec §4.9): the last attempt's per-criterion report. */
+    report?: IcaoReportEntry[];
+}
+/**
+ * Client-facing session projection returned by
+ * `POST /sessions/:id/checks/:checkType`. Whitelist-only — never the client token.
+ */
+interface SessionView {
+    id: string;
+    status: SessionStatus;
+    outcome: SessionOutcome | null;
+    /** Profile-v2 policy stop reason; absent on ordinary failures and older APIs. */
+    failureReason?: PolicyFailureReason;
+    steps: SessionStepView[];
+    /** ISO-8601 timestamp (Date on the server, string on the wire). */
+    expiresAt: string;
+    /** ISO-8601 timestamp (Date on the server, string on the wire). */
+    createdAt?: string;
+}
+/** Media class — selects size cap, MIME allowlist and promoted prefix (media.policy.ts). */
+type MediaKind = "image" | "clip";
+/**
+ * Body of `POST /sessions/:id/media`. `contentType`/`contentLength` are the
+ * exact values SIGNED into the presigned PUT — the PUT must send them verbatim.
+ * Allowlists (media.policy.ts): image → image/jpeg | image/png (5 MB cap);
+ * clip → video/webm | video/mp4 (15 MB cap). BARE types only — no `;codecs=` params.
+ */
+interface PresignRequest {
+    kind: MediaKind;
+    contentType: string;
+    contentLength: number;
+    /** D8: the live-camera capture proof (image / clip from the SDK capture flows only). */
+    capture?: CaptureProof;
+}
+/**
+ * D8 — the proof a live-camera image / clip presign carries: a single-use nonce
+ * from `POST /sessions/:id/media/capture-nonces`, plus the capture engine and how
+ * long the capture took. A picked file (or a client without the capture flow)
+ * sends none; the backend then flags (or, in `enforce`, refuses) the upload.
+ */
+interface CaptureProof {
+    nonce: string;
+    engine?: string;
+    captureMs?: number;
+}
+/** D8: `POST /sessions/:id/media/capture-nonces` response. */
+interface CaptureNoncesResult {
+    nonces: string[];
+    /** Seconds each nonce stays usable. */
+    expiresIn: number;
+}
+/** D8: what a capture flow knows about its capture when it presigns. */
+interface CaptureContext {
+    /** Capture engine id (`v1` / `v3` liveness, `document`, `portrait`). */
+    engine?: string;
+    /** How long the camera capture took, ms (→ `captureMs`; informational). */
+    durationMs?: number;
+}
+/** Result of a presign — the presigned PUT URL plus the pending object key. */
+interface PresignUploadResult {
+    key: string;
+    uploadUrl: string;
+    /** Presign TTL in seconds (900 = 15 min). */
+    expiresIn: number;
+}
+/** Result of `POST /sessions/:id/media/complete` — the PROMOTED (class-prefixed) key. */
+interface CompleteMediaResult {
+    ready: true;
+    /** e.g. `clips/{sessionId}/{uuid}` or `doc-images/{sessionId}/{uuid}` — submit THIS key, not the pending one. */
+    key: string;
+}
+/**
+ * Liveness attestation bag (attestation-verifier.service.ts). The web SDK sends
+ * `{channel: 'hosted_web', siteKey, turnstileToken}` — `siteKey` echoes the
+ * `HostedSessionView.turnstileSiteKey` the challenge was rendered with, so the
+ * backend picks the matching widget secret deterministically (Turnstile tokens
+ * are single-use: siteverify runs exactly once, never "org then global").
+ * `sandbox: true` and `signature` are honored only on sandbox sessions;
+ * native SDKs will use platform attestation.
+ */
+interface AttestationInput {
+    sandbox?: boolean;
+    signature?: string;
+    channel?: "hosted_web";
+    turnstileToken?: string;
+    /** The Turnstile site key the token was minted with (selects the verifying secret). */
+    siteKey?: string;
+}
+/**
+ * liveness executor input: a promoted `clips/…` key + optional attestation.
+ * `faceMatch` (v2 latency §3.2) carries the already-promoted `doc-images/…`
+ * keyframe so the backend can run face_match IN THE SAME submission when its
+ * bundle flag is on and `face_match` is the next pending step. Backends that
+ * do not bundle ignore it (the input bag is an open record) — the SDK then
+ * submits `face_match` itself with the same key (see liveness-flow.ts).
+ */
+interface LivenessInput {
+    clipKey: string;
+    attestation?: AttestationInput;
+    /** Declared capture channel — the liveness band is mobile-calibrated, so the
+     *  backend clamps non-mobile verdicts to review (uncalibrated_capture_channel).
+     *  Client-declared by design (not a security boundary); absent = legacy
+     *  clients, treated as mobile server-side during the rollout window. */
+    captureChannel?: 'mobile' | 'desktop';
+    /** Capture metadata (engine, dimensions, clip length, face-capture timing)
+     *  — the backend's allowlisted, non-PII `capture` block (session insights). */
+    capture?: LivenessCaptureInput;
+    /** The promoted face_match probe key, for a bundled liveness + face_match run. */
+    faceMatch?: {
+        imageKey: string;
+    };
+    /**
+     * Step 3 one-capture live photo (flow model 2026-10-23): the ICAO still of the
+     * same capture — exactly the `portrait_icao` body. When `portrait_icao` is the
+     * next pending step the server runs it in parallel with liveness.
+     */
+    portraitIcao?: PortraitIcaoInput;
+}
+/** `LivenessInput.capture`: what the SDK's `captured` event measured. All ms are whole, ≥ 0. */
+interface LivenessCaptureInput {
+    engine?: 'v1' | 'v3';
+    width?: number;
+    height?: number;
+    clipMs?: number;
+    cameraReadyMs?: number;
+    faceAcquireMs?: number;
+    captureMs?: number;
+}
+/**
+ * population_registry adapter input. `nni` is the 10-digit NNI for an UNBOUND
+ * session; a session minted with a server-side `input.nni` is BOUND to it
+ * (Plan A Task 2) — the browser submits `{}` and the backend reads the sealed
+ * value. Sending a DIFFERENT nni on a bound session answers 409 `nni_locked`.
+ */
+interface PopulationInput {
+    nni?: string;
+}
+/**
+ * face_match executor input: a promoted `doc-images/…` key (the source selfie frame).
+ * The same key may already have ridden along as {@link LivenessInput.faceMatch}.
+ */
+interface FaceMatchInput {
+    imageKey: string;
+}
+/** Document side (docs.types.ts DocSide). */
+type DocSide = "recto" | "verso" | "single";
+/** doc_ocr executor input: a promoted `doc-images/…` key + which side it shows. */
+interface DocOcrInput {
+    imageKey: string;
+    side: DocSide;
+    /**
+     * Web live MRZ (spec 2026-10-21 D6): the device-read HINT of a live-MRZ capture — where the MRZ is in the uploaded
+     * image and that every hard check digit validated on the device. Geometry, a format, counts and a salted digest
+     * only (never MRZ text); the server re-reads the pixels and decides. Omitted when not ready at POST time.
+     */
+    deviceRead?: DocDeviceRead;
+}
+/** The `doc_ocr` device-read hint (identity-backend DeviceReadSchema; strict, text-free). */
+interface DocDeviceRead {
+    engine: string;
+    source: "live_mrz";
+    format: "TD1" | "TD2" | "TD3";
+    lineCount: number;
+    checkDigitsValid: true;
+    stillConfirmed?: boolean;
+    /** [x, y, w, h] normalized to the uploaded image. */
+    band: [number, number, number, number];
+    /** sha256("sekyro-mrz-1\0" + sessionId + "\0" + canonical MRZ lines), 64 hex. */
+    digest: string;
+    framesToValid: number;
+    msToValid: number;
+}
+/**
+ * phone_otp executor input (Task 13): a two-phase check. `send` dispatches (or
+ * resends) an OTP — resolving the number from the trusted server-side prefill
+ * or the user-entered `phone` per the step's `numberSource`; `verify` checks
+ * the entered `code` against the parked token. `phone` is IGNORED for a
+ * `prefilled` step (a client number is never trusted as "prefilled").
+ */
+interface PhoneOtpInput {
+    /** Phase selector: `send` dispatches/resends, `verify` checks the code. Defaults to `send`. */
+    action: "send" | "verify";
+    /** USER-entered E.164 number (`user_entered` / `prefilled_or_entered` sends only). */
+    phone?: string;
+    /** The code the user typed — `verify` only. */
+    code?: string;
+    /**
+     * The channel the person chose for `send`. Must be one of the step's
+     * `otp.channels` when the view lists them; a session without channels
+     * defaults to `sms`.
+     */
+    channel?: "sms" | "whatsapp";
+    /** OTP message locale override for `send`. */
+    locale?: "ar" | "fr" | "en";
+}
+/**
+ * email_otp executor input (Plan 8, profile v2 §4.6.5): `send` emails a code to
+ * the trusted prefill or the user-entered `email` (per `emailOtp.emailSource`;
+ * ignored for `prefilled`), `verify` checks the entered `code`.
+ */
+interface EmailOtpInput {
+    /** Phase selector: `send` dispatches/resends, `verify` checks the code. */
+    action: "send" | "verify";
+    /** USER-entered address (`user_entered` / `prefilled_or_entered` sends only). */
+    email?: string;
+    /** The code the user typed — `verify` only. */
+    code?: string;
+    /** Email copy locale override for `send`. */
+    locale?: "ar" | "fr" | "en";
+}
+/**
+ * portrait_icao executor input (SDK spec §4.9): the ICAO gate's frame
+ * (uploaded as media kind `image`). The server re-runs every criterion; only
+ * `gate.baselineEyeOpenness` (0–1, the user's own eye-openness baseline) is used.
+ */
+interface PortraitIcaoInput {
+    media: {
+        portrait: string;
+    };
+    gate?: {
+        baselineEyeOpenness?: number;
+        /**
+         * The device verdict on the submitted still, with the server's criterion names
+         * (`framing` folds into `resolution`; unmeasured criteria are omitted, and
+         * `background` when the profile does not require it). Compared with the server
+         * report, never trusted. Values are booleans keyed by {@link IcaoCriterion}
+         * (the 0.1 type is kept: the public API only grows).
+         */
+        criteria?: Record<string, unknown>;
+        /** The client background-uniformity measurement (numbers only; telemetry — the server decides). */
+        backgroundCheck?: Record<string, unknown>;
+    };
+    tuningVersion?: string;
+}
+/**
+ * eid_auth executor input (SDK spec §3.2): `start` asks the provider for a
+ * code (with the person's `identifier` — the NNI in MR — unless the session is
+ * bound to it), `verify` checks the typed `code`, `resend` asks for a new code.
+ * On a bound session a different `identifier` answers 409 `nni_locked`.
+ */
+interface EidAuthInput {
+    action: "start" | "verify" | "resend";
+    /** `start` only: the national number, omitted on a bound session. */
+    identifier?: string;
+    /** `verify` only: the code shown in the provider's app. */
+    code?: string;
+}
+/** Per-check-type submission input shapes, keyed by the frozen vocabulary. */
+interface CheckInputByType {
+    liveness: LivenessInput;
+    face_match: FaceMatchInput;
+    doc_ocr: DocOcrInput;
+    population_registry: PopulationInput;
+    phone_otp: PhoneOtpInput;
+    /** M-nfc: read and submitted by the native SDKs only — the web never submits it. */
+    nfc_chip: never;
+    email_otp: EmailOtpInput;
+    /** SDK spec §4.9: the web ICAO gate ships with M1b; the shape is ready for headless use. */
+    portrait_icao: PortraitIcaoInput;
+    /** SDK spec §3.2: the national eID sign-in. */
+    eid_auth: EidAuthInput;
+}
+/**
+ * Body of `POST /sessions/:id/checks/:checkType` (SubmitCheckSchema).
+ * `forceOutcome` is SANDBOX-ONLY (plan D-C) — a live session rejects it with
+ * 403 `force_outcome_forbidden`.
+ */
+interface SubmitCheckBody {
+    input?: Record<string, unknown>;
+    forceOutcome?: "pass" | "fail";
+}
+
+/**
+ * Strip MIME parameters: `video/webm;codecs=vp8,opus` → `video/webm`.
+ *
+ * The capture engine (Task 4) emits `clipMimeType` WITH codec parameters, but
+ * the presign allowlist holds BARE types only (['video/webm','video/mp4'] /
+ * ['image/jpeg','image/png']) and the presigned PUT signs the exact declared
+ * Content-Type. Exported so pages can normalize once and stay byte-consistent
+ * between presign and PUT.
+ */
+declare function stripMimeParams(contentType: string): string;
+/** Media-bearing check types → the input field the promoted key goes into. */
+declare const MEDIA_INPUT_FIELD: {
+    readonly liveness: "clipKey";
+    readonly face_match: "imageKey";
+    readonly doc_ocr: "imageKey";
+};
+/** Check types that take an uploaded media key (population_registry does not). */
+type MediaCheckType = keyof typeof MEDIA_INPUT_FIELD;
+interface SubmitOptions {
+    /**
+     * Sent as `x-idempotency-key` (the header IdempotencyInterceptor reads).
+     * One key per LOGICAL submit — a flaky-network retry with the same key
+     * replays the first response without burning another attempt.
+     */
+    idempotencyKey?: string;
+    /** SANDBOX-ONLY deterministic override (plan D-C); a live session 403s it. */
+    forceOutcome?: "pass" | "fail";
+}
+interface UploadMedia {
+    kind: MediaKind;
+    blob: Blob;
+    /** May carry codec params (engine `clipMimeType`) — stripped before presign AND PUT. */
+    contentType: string;
+}
+interface HostedClientOptions {
+    /** API origin, e.g. `https://api.sekyro.ai` — paths are `${apiOrigin}/api/v2/...`. */
+    apiOrigin: string;
+    /** The raw session token from the hosted URL (short code; legacy `cst_` during its TTL) — sent as `x-session-token` on every API call. */
+    sessionToken: string;
+    /** Injection seam (tests / non-window contexts). Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Per-request timeout for API calls (NOT the Spaces PUT). Default 30 000 ms. */
+    requestTimeoutMs?: number;
+    /**
+     * Tuning for the ONLY automatic retry the client performs: 409
+     * `idempotency_in_progress` (a concurrent identical request is mid-flight
+     * server-side; the real response lands once it finishes). `attempts` counts
+     * retries AFTER the first try. Defaults: 5 × 400 ms.
+     */
+    inProgressRetry?: {
+        attempts?: number;
+        delayMs?: number;
+    };
+}
+/**
+ * Hand-authored typed client for the five session-token endpoints:
+ *
+ *   GET  /api/v2/hosted/session                     → {@link getSession}
+ *   POST /api/v2/hosted/consent                     → {@link recordConsent}
+ *   POST /api/v2/hosted/method                      → {@link selectMethod}
+ *   POST /api/v2/hosted/contact                     → {@link selectContact}
+ *   POST /api/v2/hosted/identity/confirm            → {@link confirmIdentity}
+ *   GET  /api/v2/hosted/identity/portrait           → {@link identityPortrait}
+ *   POST /api/v2/sessions/:id/media                 → {@link presign}
+ *   POST /api/v2/sessions/:id/media/complete        → {@link completeMedia}
+ *   POST /api/v2/sessions/:id/checks/:checkType     → {@link submitCheck}
+ *
+ * plus the bare presigned Spaces PUT ({@link uploadToSpaces}) and the
+ * presign→PUT→complete→submit composition ({@link uploadAndSubmit}).
+ *
+ * Envelopes (verified against sessions-docs.e2e-spec.ts):
+ *  - success: `{success: true, data}` — unwrapped here, methods return the payload;
+ *  - error: flat `{code, message}` → thrown as {@link HostedApiError}.
+ *
+ * The media/checks routes are `:id`-addressed while the token itself is the
+ * only credential the page starts with — the client learns its sessionId from
+ * `GET /hosted/session` (token-addressed) and lazily bootstraps it when a
+ * `:id` route is called first.
+ *
+ * No automatic retry EXCEPT bounded short-delay retry on 409
+ * `idempotency_in_progress`. Everything else — including 429 with its parsed
+ * `retryAfterSeconds` — is surfaced to the page to handle.
+ */
+declare class HostedClient {
+    private readonly apiOrigin;
+    private readonly sessionToken;
+    private readonly fetchImpl;
+    private readonly requestTimeoutMs;
+    private readonly retryAttempts;
+    private readonly retryDelayMs;
+    private sessionId;
+    private bootstrap;
+    /** D8: prefetched capture nonces (`armCapture`), each with its local expiry. */
+    private captureNonces;
+    private captureFetch;
+    constructor(opts: HostedClientOptions);
+    /** Token-addressed bootstrap — the hosted page's first call. Caches the sessionId. */
+    getSession(): Promise<HostedSessionView>;
+    /**
+     * Record consent once (201; an idempotent replay answers 200 with
+     * `alreadyRecorded: true`). Until recorded, media presign/complete AND check
+     * submission answer 409 `consent_required`.
+     */
+    recordConsent(locale: ConsentLocale): Promise<RecordConsentResult>;
+    /**
+     * Send the person's identity method (profile v2 step 3) when the view offers
+     * a choice (`methodChoice.available`). Returns the updated hosted view —
+     * continue from it. 409 `method_locked` when the method can no longer
+     * change (a check of the chosen method was already submitted).
+     */
+    selectMethod(method: IdentityMethod): Promise<HostedSessionView>;
+    /**
+     * Choose how the person confirms their contact (flow model 2026-10-23, Step 1)
+     * on a `one_of` session (`otpChoice` in the view): `phone` or `email`. Returns
+     * the updated hosted view. The person may switch until a contact step passed;
+     * then (or on a session without the choice) 409 `contact_locked`.
+     */
+    selectContact(channel: ContactChannel): Promise<HostedSessionView>;
+    /**
+     * Answer the identity summary (`identitySummary` in the view, Step 2b):
+     * `confirm` lifts the live-photo gate, `retake` re-opens the identity checks
+     * that produced the data. Returns the updated hosted view; 409
+     * `identity_confirm_locked` when nothing is pending or no retake is left.
+     */
+    confirmIdentity(decision: IdentityConfirmDecision): Promise<HostedSessionView>;
+    /**
+     * The summary portrait (`identitySummary.portrait.available`) as a JPEG
+     * `Blob`, fetched with the session-token header (`Cache-Control: no-store`).
+     * Show it from memory (`URL.createObjectURL`, revoked when done) — never
+     * cache or store it.
+     */
+    identityPortrait(): Promise<Blob>;
+    /**
+     * Presign a Spaces PUT for a new pending object. `contentType` is stripped of
+     * MIME parameters defensively (the allowlist holds bare types; the engine's
+     * `clipMimeType` carries codec params) — PUT with the SAME bare type, or the
+     * signed-header check rejects the upload.
+     */
+    presign(kind: MediaKind, contentType: string, contentLength: number): Promise<PresignUploadResult>;
+    /**
+     * D8: prefetch live-camera capture nonces when a camera capture STARTS, so the
+     * presigns that follow (`presignCapture`) need no extra round trip. Never
+     * throws; an older backend without the route simply leaves the pool empty.
+     */
+    armCapture(count?: number): void;
+    /**
+     * D8: presign a LIVE-CAMERA image / clip — like {@link presign}, plus the
+     * capture proof: a fresh single-use nonce (pooled by {@link armCapture}, else
+     * fetched now), the engine and the capture duration. When no nonce can be had
+     * (route absent, network) the presign goes out without a proof — the backend
+     * decides (`signal` flags it, `enforce` refuses it). Only the SDK's own capture
+     * flows call this; a picked file goes through {@link presign}.
+     */
+    presignCapture(kind: MediaKind, contentType: string, contentLength: number, context?: CaptureContext): Promise<PresignUploadResult>;
+    /** D8: one pooled (still fresh) nonce, else one fetched now; undefined when none can be had. */
+    private takeCaptureNonce;
+    /** D8: fetch `count` nonces into the pool (one request in flight at a time). Never throws. */
+    private fillCaptureNonces;
+    /**
+     * Bare PUT to the presigned Spaces URL: EXACTLY the signed headers — the
+     * declared Content-Type and the blob body. NO `x-session-token` (the
+     * signature IS the credential; an extra header breaks nothing but leaks the
+     * token to a third-party host) and no JSON envelope.
+     *
+     * `contentType` is param-stripped here too (idempotent for bare types): the
+     * presign strips internally, so a caller composing manually with the engine's
+     * parameterful `clipMimeType` would otherwise sign `video/webm` but PUT
+     * `video/webm;codecs=…` — a signed-header mismatch S3 rejects at runtime.
+     *
+     * Timeout: 15 min (`AbortSignal.timeout(900_000)`, matching the presign TTL)
+     * rather than the API calls' 30 s — a 15 MB clip on a slow link legitimately
+     * exceeds 30 s, but a stalled in-flight socket must still be bounded (the TTL
+     * alone only bounds when a PUT can START).
+     *
+     * Failures are ALWAYS typed: non-2xx throws {@link HostedApiError} with the
+     * client-synthesized `upload_failed` (message carries a truncated S3 body
+     * snippet — e.g. SignatureDoesNotMatch); a mid-transfer drop → `network_error`;
+     * the timeout → `timeout`.
+     */
+    uploadToSpaces(uploadUrl: string, blob: Blob, contentType: string): Promise<void>;
+    /** Finalize an upload: the backend sniffs + promotes; returns the PROMOTED key to submit. */
+    completeMedia(key: string): Promise<CompleteMediaResult>;
+    /**
+     * Submit one check. Sends `{input, forceOutcome?}` (SubmitCheckSchema) and the
+     * optional `x-idempotency-key` header. Returns the whitelisted SessionView.
+     */
+    submitCheck<T extends CheckType>(checkType: T, input: CheckInputByType[T], opts?: SubmitOptions): Promise<SessionView>;
+    /**
+     * Convenience composition: presign → PUT → complete → submit, passing the
+     * PROMOTED key (from complete's response — never the pending presign key)
+     * into the check's media input field (`clipKey` for liveness, `imageKey` for
+     * face_match/doc_ocr). `extraInput` carries the remaining input fields
+     * (liveness `attestation`, doc_ocr `side`). The media content type is
+     * param-stripped ONCE and used for both presign and PUT, so the signed
+     * header always matches.
+     */
+    uploadAndSubmit<T extends MediaCheckType>(checkType: T, media: UploadMedia, extraInput: Omit<CheckInputByType[T], (typeof MEDIA_INPUT_FIELD)[T]>, opts?: SubmitOptions): Promise<SessionView>;
+    /** The token's own sessionId — cached from getSession(), lazily bootstrapped. */
+    private ensureSessionId;
+    /**
+     * One API request: `${apiOrigin}/api/v2${path}`, `x-session-token` always,
+     * AbortSignal timeout (30 s default), `{success, data}` unwrap on 2xx, flat
+     * `{code, message}` → {@link HostedApiError} on non-2xx. EVERY failure is
+     * typed: a rejected fetch → `network_error`, the timeout → `timeout`, an
+     * unparseable 2xx body → `unknown_error` — the page never sees a raw
+     * TypeError/DOMException. The ONLY automatic retry is 409
+     * `idempotency_in_progress` (bounded, short delay).
+     */
+    private api;
+}
+
+/** Luma at or above this counts as clipped / specular. */
+declare const CLIPPED_LUMA = 250;
+/** Laplacian-variance reference (same as the liveness gate's frame-quality SHARP_REF). */
+declare const ICAO_SHARP_REF = 180;
+interface LumaPlane {
+    data: Uint8Array;
+    width: number;
+    height: number;
+}
+/** Rec.601 luma of RGBA pixels. */
+declare function lumaPlane(image: {
+    data: Uint8ClampedArray | Uint8Array;
+    width: number;
+    height: number;
+}): LumaPlane;
+interface RegionStats {
+    mean: number;
+    sd: number;
+    /** Fraction of pixels at or above {@link CLIPPED_LUMA}. */
+    clipped: number;
+    count: number;
+}
+/** Mean / SD / clipped fraction of a box, optionally excluding a second box. */
+declare function regionStats(plane: LumaPlane, box: Box, exclude?: Box): RegionStats;
+interface FaceLighting {
+    faceLuma: number;
+    /** Left-half / right-half mean luma (image halves, split at the nose). */
+    halfRatio: number;
+    clipped: number;
+}
+declare function faceLighting(plane: LumaPlane, g: FaceGeometry): FaceLighting | null;
+/** Specular fraction inside both eye regions (spec §5.4 glasses glare). */
+declare function eyeSpecular(plane: LumaPlane, g: FaceGeometry): number | null;
+interface BackgroundStats {
+    luma: number;
+    sd: number;
+    /** Pixels measured — too few means the corners left the frame. */
+    count: number;
+}
+/**
+ * Background heuristic: the two top corners of the ICAO window (each 20 % wide,
+ * 25 % tall from 4 % down), minus the head (the face box widened by 40 % and
+ * extended to the top of the window for hair). `null` when nothing is left.
+ */
+declare function backgroundStats(plane: LumaPlane, g: FaceGeometry): BackgroundStats | null;
+/** Laplacian variance over the face core on a ≤96×96 grid, normalised 0..1 by {@link ICAO_SHARP_REF}. */
+declare function faceSharpness(plane: LumaPlane, g: FaceGeometry): number | null;
+/** Every pixel measure of one frame (`null` fields: not measurable). */
+interface IcaoPixelStats {
+    lighting: FaceLighting | null;
+    eyeSpecular: number | null;
+    background: BackgroundStats | null;
+    sharpness: number | null;
+}
+declare function icaoPixelStats(plane: LumaPlane, g: FaceGeometry): IcaoPixelStats;
+
+/** The client gate's criteria, in coaching priority order. */
+declare const ICAO_GATE_CRITERIA: readonly ["face", "framing", "pose", "eyes", "mouth", "glare", "lighting", "background", "resolution", "sharpness"];
+type IcaoGateCriterion = (typeof ICAO_GATE_CRITERIA)[number];
+/** Coaching keys (copy `portrait.coach.<key>`). */
+type IcaoCoachKey = "no_face" | "multiple_faces" | "center" | "too_close" | "pose" | "eyes" | "mouth" | "glare" | "lighting" | "lighting_side" | "background" | "resolution" | "hold_still" | "hold";
+/** One frame as the gate sees it. Geometry in SOURCE (stream) pixels. */
+interface IcaoFrameObservation {
+    frameWidth: number;
+    frameHeight: number;
+    /** Faces the landmarker found (the gate wants exactly one). */
+    faces: number;
+    geometry: FaceGeometry | null;
+    /** Facial transformation matrix (4×4, column-major), when produced. */
+    matrix?: readonly number[] | null;
+    /** Blendshape scores by category name (`eyeBlinkLeft`, `jawOpen`, …). */
+    blendshapes?: Readonly<Record<string, number>> | null;
+    /** Pixel heuristics on the analysis frame; `null` when not measured. */
+    stats?: IcaoPixelStats | null;
+    /**
+     * The background-uniformity check (segmenter, or the strip fallback), the
+     * latest measurement — it runs a few times per second, not on every frame.
+     * When present it decides the `background` criterion; `null` = not measurable.
+     */
+    backgroundCheck?: BackgroundUniformity | null;
+}
+interface IcaoCriterionState {
+    criterion: IcaoGateCriterion;
+    pass: boolean;
+    /** Passed continuously for `holdMs`. */
+    held: boolean;
+    /** A failing soft criterion the gate stopped waiting for. */
+    waived: boolean;
+    /** The measured value (degrees, ratio, luma, px…) — coaching / telemetry only. */
+    value: number | null;
+    /** Coaching key when failing. */
+    coach: IcaoCoachKey | null;
+}
+interface IcaoGateUpdate {
+    criteria: IcaoCriterionState[];
+    /** The one message to show (`hold` when everything passes and the gate is counting down). */
+    coach: IcaoCoachKey;
+    /** The lowest failing criterion (`null` when all pass or are waived). */
+    failing: IcaoGateCriterion | null;
+    /** 0..1 — held criteria, for a progress ring. */
+    progress: number;
+    /** Take the portrait frame now. */
+    ready: boolean;
+    /**
+     * The user's own eye-openness baseline, once known. Unit (D9d, everywhere): openness =
+     * 1 − the Landmarker's `eyeBlink{Left,Right}` blendshape; per frame the mean of the
+     * two eyes; the baseline is the `baseline.percentile` (0.8) quantile over the recent
+     * frontal, single-face frames. kyc-portrait compares the lower eye against it.
+     */
+    baseline: number | null;
+    pose: HeadPose | null;
+}
+/** The on-device result submitted with the portrait (`gate`, §4.9): numbers only. */
+interface IcaoGateSummary {
+    /** In (0, 1]: the gate's eye baseline (1 − blink blendshape; see {@link IcaoGateUpdate.baseline}). */
+    baselineEyeOpenness?: number;
+    criteria: Partial<Record<IcaoGateCriterion, {
+        pass: boolean;
+        value: number | null;
+        waived?: boolean;
+    }>>;
+    /**
+     * The device verdict with the server's criterion names — the submission's
+     * `gate.criteria`: `framing` folds into `resolution`, unmeasured criteria are
+     * omitted (occlusion always; background when the profile does not require it).
+     */
+    verdict?: Partial<Record<IcaoCriterion, boolean>>;
+    /** The background-uniformity measurement behind the `background` criterion (numbers only). */
+    backgroundCheck?: Omit<BackgroundUniformity, "pixels">;
+}
+interface Measured {
+    pass: boolean;
+    value: number | null;
+    coach: IcaoCoachKey | null;
+    /** Not measured on this frame (left out of the verdict). */
+    none?: true;
+}
+/** The criteria a profile sets limits for (conformance.json `criteria`). */
+type IcaoJudgedCriterion = "pose" | "eyes" | "mouth" | "lighting" | "background" | "resolution";
+/**
+ * One frame's measures in the server's units (conformance.json `measures`);
+ * `null` = not measured on this frame.
+ */
+interface IcaoMeasures {
+    /** Degrees; `pitch` is RAW (before `pitchOffsetDeg`). `null` = no transformation matrix. */
+    pose: HeadPose | null;
+    /** The value shown for a pose without matrix (roll from the eye line). */
+    eyeLineRoll?: number;
+    /** Openness of each eye (1 − the `eyeBlink*` blendshape). */
+    eyes: {
+        left: number;
+        right: number;
+    } | null;
+    /** The person's eye-openness baseline; `null` = the absolute floor only. */
+    baseline: number | null;
+    /** Blendshapes: `jawOpen`, the larger `mouthSmile*`, `mouthPucker`. */
+    mouth: {
+        jawOpen: number;
+        smile: number;
+        pucker: number;
+    } | null;
+    lighting: {
+        faceLuma: number;
+        halfRatio: number;
+        clipped: number;
+    } | null;
+    background: {
+        luma: number;
+        sd: number;
+    } | null;
+    /** The web background-uniformity check; when present (and enabled) it decides the background. */
+    uniformity?: Pick<BackgroundUniformity, "uniform" | "colorStd"> | null;
+    iod: number;
+    frameWidth: number;
+    frameHeight: number;
+}
+/**
+ * The per-criterion decision on one frame's measures — pure, the same rule as
+ * kyc-portrait and the native gates (packages/sekyro-contract/icao/conformance.json;
+ * limits are inclusive).
+ */
+declare function judgeIcao(m: IcaoMeasures, t: ResolvedIcaoTuning): Record<IcaoJudgedCriterion, Measured>;
+/** Openness of one eye from the Landmarker's blink blendshape (1 − blink). */
+declare function eyeOpenness(blendshapes: Readonly<Record<string, number>> | null | undefined): {
+    left: number;
+    right: number;
+    blinkLeft: number;
+    blinkRight: number;
+} | null;
+/** The `p`-quantile (0..1) of a sample, nearest-rank. */
+declare function percentile(values: readonly number[], p: number): number | null;
+/** Score one frame against the limits. Pure; `baseline` is the eye baseline so far. */
+declare function scoreFrame(frame: IcaoFrameObservation, t: ResolvedIcaoTuning, baseline: number | null): {
+    results: Record<IcaoGateCriterion, Measured>;
+    pose: HeadPose | null;
+};
+interface IcaoGate {
+    push(frame: IcaoFrameObservation, nowMs: number): IcaoGateUpdate;
+    /** The last update (`null` before the first frame). */
+    last(): IcaoGateUpdate | null;
+    /** The submission's `gate` block from the last update. */
+    summary(): IcaoGateSummary;
+    /** Start the holds over (a retake). The eye baseline is kept: it describes the person. */
+    reset(): void;
+}
+interface IcaoGateOptions {
+    /** `alert`: coaching only — ready `alertGraceMs` after the face was accepted at the latest. Default `reject`. */
+    policy?: "reject" | "alert";
+}
+declare function createIcaoGate(t: ResolvedIcaoTuning, options?: IcaoGateOptions): IcaoGate;
+
+export { type PopulationReason as $, type AcceptedDocumentType as A, type IcaoCoachKey as B, type CheckReason as C, type DecisionReason as D, type EidAfterPass as E, type FaceMatchReason as F, type IcaoCriterion as G, type HeadPose as H, type IcaoCaptureTuning as I, type IcaoCriterionState as J, type IcaoGateCriterion as K, type IcaoGateSummary as L, type IcaoGateUpdate as M, type IcaoReportEntry as N, type IdentityConfirmDecision as O, type IdentityMethod as P, type IdentitySummarySource as Q, type IdentitySummaryView as R, type LivenessReason as S, type MatchReason as T, type MethodChoiceView as U, type NationalEidOption as V, type NfcChipReason as W, type NfcStepView as X, type OtpChoiceView as Y, type PhoneOtpReason as Z, type PolicyFailureReason as _, type CheckState as a, type MediaCheckType as a$, type PortraitIcaoInput as a0, type PortraitIcaoReason as a1, type SessionFailureReason as a2, type SessionOutcome as a3, type SessionStatus as a4, type StepSection as a5, type SessionView as a6, type BackgroundStats as a7, type Box as a8, CLIPPED_LUMA as a9, icaoWindow as aA, judgeIcao as aB, lumaPlane as aC, percentile as aD, portraitCropRegion as aE, poseFromMatrix as aF, regionStats as aG, resolveIcaoTuning as aH, scoreFrame as aI, windowOverflow as aJ, type PersonMask as aK, HostedClient as aL, type AttestationInput as aM, type CaptureContext as aN, type CaptureNoncesResult as aO, type CaptureProof as aP, type CheckInputByType as aQ, type CompleteMediaResult as aR, type ConsentLocale as aS, type DocDeviceRead as aT, type DocOcrInput as aU, type DocSide as aV, type EmailOtpInput as aW, type FaceMatchInput as aX, type HostedClientOptions as aY, type LivenessCaptureInput as aZ, type LivenessInput as a_, type FaceGeometry as aa, type FaceLighting as ab, ICAO_CANVAS as ac, ICAO_FALLBACK as ad, ICAO_GATE_CRITERIA as ae, ICAO_SHARP_REF as af, type IcaoFrameObservation as ag, type IcaoGate as ah, type IcaoGateOptions as ai, type IcaoJudgedCriterion as aj, type IcaoMeasures as ak, type IcaoPixelStats as al, type IcaoProfile as am, type LumaPlane as an, type Point as ao, type RegionStats as ap, type ResolvedIcaoTuning as aq, backgroundStats as ar, createIcaoGate as as, eyeLineRoll as at, eyeOpenness as au, eyeSpecular as av, faceGeometry as aw, faceLighting as ax, faceSharpness as ay, icaoPixelStats as az, type CheckType as b, type MediaKind as b0, type PhoneOtpInput as b1, type PopulationInput as b2, type PresignRequest as b3, type PresignUploadResult as b4, type RecordConsentResult as b5, type SessionStepView as b6, type SubmitCheckBody as b7, type SubmitOptions as b8, type UploadMedia as b9, stripMimeParams as ba, type ContactChannel as c, type DocReason as d, type EidAuthInput as e, type EidReason as f, type EmailOtpReason as g, type HostedAcceptedDocuments as h, type HostedBranding as i, type HostedBrandingColorKey as j, type HostedCaptureTuning as k, type HostedDocumentCaptureTuning as l, type HostedDocumentScanTuning as m, type HostedEidView as n, type HostedEmailOtpView as o, type HostedIcaoPolicy as p, type HostedIntegrity as q, type HostedLivePhotoTuning as r, type HostedNativeCaptureTuning as s, type HostedOcrTuning as t, type HostedOtpView as u, type HostedPortraitView as v, type HostedSessionView as w, type HostedStepView as x, type HostedVoiceLocale as y, type HostedVoiceView as z };