@sekyro/web 0.0.0-stage → 0.1.0-rc.2

package/dist/internal/index.d.ts

@@ -0,0 +1,431 @@
+import { n as DeviceClass, h as CaptureState, b as CaptureArtifacts, c as CaptureErrorKind } from '../capture-session-v3-BJ8ciaWl.js';
+export { C as CENTERED_FACTOR, a as CIRCLE_RADIUS_FACTOR, I as IN_CIRCLE_FACTOR } from '../capture-constraints-BujkZcfb.js';
+import { k as VerificationResult } from '../create-verification-CjLnJ0w6.js';
+export { A as AttestationError, o as CLIP_MIME_ALLOWLIST, p as CaptureEngine, H as HostedClientLike, q as LivenessCaptureInternalHandle, r as LivenessCaptureInternals, s as LivenessFlowDeps, t as LivenessFlowOutcome, P as PROCESSING_POLL_DELAY_MS, u as PROCESSING_POLL_MAX, v as REGISTRY_RETRY_DELAY_MS, w as SubmitExecutor, x as SubmitRuntime, T as TRANSPORT_REPLAY_ATTEMPTS, y as TRANSPORT_REPLAY_DELAY_MS, z as VerificationInternals, B as createLivenessCaptureInternal, E as createVerificationInternal, F as mapEngineState, I as mapErrorKind, J as mapGuidanceHint, K as randomUuid, M as runLivenessFlow, N as runSubmission } from '../create-verification-CjLnJ0w6.js';
+import { C as CheckReason, c as HostedSessionView, d as HostedStepView, h as SessionView, b as CheckType } from '../hosted-client-BpvBqu9f.js';
+import '../detect-worker-CKXHlXx9.js';
+
+/** Physical geometry the scanner frames (ISO/IEC 7810 / ICAO 9303). */
+type DocFormat = "ID-1" | "ID-3";
+type DocSide = "recto" | "verso" | "single";
+interface DocCatalogEntry {
+    /** kyc-docs-v2 `document_type`, verbatim. */
+    docType: "carte_identite" | "passport";
+    format: DocFormat;
+    /** Capture sequence the hosted doc step walks, in order. */
+    sides: readonly DocSide[];
+    /** MRZ geometry: td1 = 3×30 (ID-1 verso), td3 = 2×44 (passport data page). */
+    mrz: "none" | "td1" | "td3";
+    /** Which side carries the holder photo (drives portrait expectations). */
+    portraitSide: DocSide;
+    /** Physical width/height ratio of the framed page. */
+    aspectRatio: number;
+    /** Where the subject identifier (NNI) is parsed from, when the doc carries one. */
+    identifierSource?: "mrz";
+}
+/**
+ * Plausibility aspect bands per format (Task 34 gate input): ID-1 cards are
+ * 85.6×53.98mm → 1.586; an ID-3 passport DATA PAGE frames at ≈125×88mm → 1.42
+ * (wider tolerance — page curl and hinge shadow skew the detected quad).
+ */
+declare const ASPECT_BANDS: Record<DocFormat, {
+    center: number;
+    tolerance: number;
+}>;
+/** Aspect band for a format — helper the DocGateV1 plausibility check calls. */
+declare function aspectBand(format: DocFormat): {
+    center: number;
+    tolerance: number;
+};
+/** The MR docTypes facet (findings §4). Order = the hosted picker's display order. */
+declare const MR_DOC_CATALOG: readonly DocCatalogEntry[];
+
+/** Detect-frame width the session downscales to (findings §1: 25ms median).
+ *  Lives HERE (not detector-scanic.ts) so the session can import it without
+ *  statically pulling the scanic chunk into host bundles. */
+declare const DOC_DETECT_WIDTH = 480;
+interface DocQuadPoint {
+    x: number;
+    y: number;
+}
+/** Detected document quad, image-space pixels (scanic CornerPoints shape). */
+interface DocQuad {
+    topLeft: DocQuadPoint;
+    topRight: DocQuadPoint;
+    bottomRight: DocQuadPoint;
+    bottomLeft: DocQuadPoint;
+}
+interface DocGateThresholds {
+    /** Quad area / frame area below which the doc is too far. */
+    MIN_AREA_FRAC: number;
+    /** A corner this close to (or past) a frame edge counts as clipped. */
+    EDGE_CLIP_MARGIN_PX: number;
+    /** Consecutive stable plausible+quality ticks required to fire. */
+    STABLE_TICKS: number;
+    /** Quad-bbox IoU with the previous tick at/above which the streak holds. */
+    IOU_STABLE_MIN: number;
+    /** Integrator slopes, per second — mirrors FaceGateV3's gentle drain. */
+    RISE_PER_S: number;
+    FALL_PER_S: number;
+    /** Quality guidance trigger levels (same semantics as the face gate). */
+    GUIDE_EXPOSURE: number;
+    GUIDE_SHARPNESS: number;
+    /** ID-3 (MRZ-band mode): band width / frame width floor. */
+    ID3_BAND_MIN_WIDTH_FRAC: number;
+    /** ID-3 (MRZ-band mode): band aspect (w/h) sanity bounds. */
+    ID3_BAND_ASPECT_MIN: number;
+    ID3_BAND_ASPECT_MAX: number;
+}
+/** Frozen defaults (plan Task 34 — do not retune without a golden update). */
+declare const DOC_GATE_V1_DEFAULTS: Readonly<DocGateThresholds>;
+interface DocGateQuality {
+    /** frame-quality.sharpness on the quad crop. */
+    sharpness: number;
+    /** frame-quality.exposure on the quad crop. */
+    exposure: number;
+    /** Mean crop luma — picks more_light vs too_bright. */
+    meanLuma: number;
+}
+interface DocGateTickInput {
+    timestampMs: number;
+    quad: DocQuad | null;
+    quality: DocGateQuality;
+    frameWidth: number;
+    frameHeight: number;
+}
+/** Per-tick output — the scanner chrome contract. */
+interface DocGateTick {
+    at: number;
+    quad: DocQuad | null;
+    /** Geometry passed: present × big enough × in frame × right shape. */
+    plausible: boolean;
+    /** Integrated progress 0..1 (the overlay ring). */
+    p: number;
+    /** dcv1.* message key (host translates; never prose). */
+    guidanceKey: string;
+    /** Fire signal: plausible × quality × STABLE_TICKS consecutive high-IoU ticks. */
+    ready: boolean;
+    /** Current stability streak length (diagnostics/telemetry). */
+    stableTicks: number;
+}
+/** Shoelace area of the quad as a fraction of the frame area. */
+declare function quadAreaFrac(quad: DocQuad, frameWidth: number, frameHeight: number): number;
+/** IoU of the two quads' axis-aligned bounding boxes (stability metric). */
+declare function quadIou(a: DocQuad, b: DocQuad): number;
+/** Axis-aligned bounds (width/height) of a quad — the ID-3 band-mode geometry. */
+declare function quadBounds(quad: DocQuad): {
+    width: number;
+    height: number;
+};
+declare class DocGateV1 {
+    private readonly t;
+    private readonly format;
+    private p;
+    private lastTickAt;
+    private lastQuad;
+    private streak;
+    constructor(format: DocFormat, overrides?: Partial<DocGateThresholds>);
+    reset(): void;
+    tick(input: DocGateTickInput): DocGateTick;
+    private edgeClipped;
+}
+
+interface MrzBand {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Mean qualifying-row stroke density (diagnostics/telemetry). */
+    density: number;
+}
+interface MrzBandThresholds {
+    /** Luma step that counts as a text stroke edge. */
+    EDGE_LUMA_DELTA: number;
+    /** Min fraction of a row's pixels that are stroke edges to qualify. */
+    MIN_ROW_DENSITY: number;
+    /** Row must have stroke edges spread across ≥ this fraction of 12 columns. */
+    MIN_COLUMN_COVERAGE: number;
+    /** Band width (stroke x-extent) as a fraction of frame width. */
+    MIN_WIDTH_FRAC: number;
+    /** Band height bounds as fractions of frame height (2–3 OCR-B lines). */
+    MIN_HEIGHT_FRAC: number;
+    MAX_HEIGHT_FRAC: number;
+    /** Rows this close together merge into one band (inter-line gap). */
+    ROW_MERGE_GAP: number;
+}
+/** Frozen defaults (goldens in test/doc/mrz-band.test.ts — retune together). */
+declare const MRZ_BAND_DEFAULTS: Readonly<MrzBandThresholds>;
+/**
+ * Detect the MRZ stroke band on a (≤480px) grayscale-able frame. Returns the
+ * tight band rect in frame pixels, or null when no qualifying band exists
+ * (no MRZ in view, or only a partial/narrow slice of one).
+ */
+declare function detectMrzBand(frame: ImageData, overrides?: Partial<MrzBandThresholds>): MrzBand | null;
+
+type FramingStatus = "no_document" | "too_far" | "too_close" | "edge_clipped" | "wrong_shape" | "tilted" | "ok";
+type LightingStatus = "too_dark" | "too_bright" | "ok";
+type BlurStatus = "blurry" | "ok";
+type GlareStatus = "glare" | "ok";
+/** The per-frame analysis vector (every axis judged independently). */
+interface DocFrameAnalysis {
+    framing: FramingStatus;
+    lighting: LightingStatus;
+    blur: BlurStatus;
+    glare: GlareStatus;
+    /** All-clear: every axis ok — the gate's integrator/stability input. */
+    acceptable: boolean;
+}
+interface DocFrameMeasures {
+    /** frame-quality sharpness on the doc-region crop (0..1). */
+    sharpness: number;
+    /** frame-quality exposure on the doc-region crop (0..1). */
+    exposure: number;
+    /** Mean crop luma (0..255) — picks too_dark vs too_bright. */
+    meanLuma: number;
+    /** Fraction of crop pixels at/above the specular ceiling (0..1). */
+    specularFraction: number;
+}
+/** Analysis thresholds beyond the gate's — frozen defaults (round 4). */
+declare const DOC_ANALYSIS_DEFAULTS: Readonly<{
+    /** Doc area fraction above which the camera is too close (capture would crop). */
+    MAX_AREA_FRAC: 0.92;
+    /** Opposite-side length ratio beyond which the view is too oblique. */
+    TILT_MAX_SIDE_RATIO: 1.3;
+    /** Specular-pixel fraction at/above which the frame reads as glare. */
+    GLARE_MAX_SPECULAR_FRAC: 0.025;
+}>;
+/** Fraction of crop pixels with luma ≥ 252 — cheap specular-highlight measure. */
+declare function specularFraction(crop: ImageData): number;
+/** Opposite-side length ratio of the quad (1 = fronto-parallel). */
+declare function quadTiltRatio(quad: DocQuad): number;
+/**
+ * Judge one frame. `detectionMode` mirrors the gate: ID-1 quads carry
+ * area/aspect/tilt semantics; ID-3 MRZ bands carry width-fraction semantics
+ * (band rects are axis-aligned, so tilt/aspect checks are band-specific).
+ */
+declare function analyzeDocFrame(input: {
+    format: DocFormat;
+    quad: DocQuad | null;
+    frameWidth: number;
+    frameHeight: number;
+    measures: DocFrameMeasures;
+    thresholds?: Partial<DocGateThresholds>;
+}): DocFrameAnalysis;
+
+/** Feedback vocabulary (dcv2.* message keys on the hosted side). */
+type DocFeedbackKey = "sensing" | "too_far" | "too_close" | "edge_clipped" | "wrong_shape" | "tilted" | "too_dark" | "too_bright" | "blurry" | "glare" | "hold_still" | "processing" | "side_captured" | "captured";
+/** Reticle rendering mode per feedback state (the stage maps to visuals). */
+type ReticleType = "searching" | "coaching" | "locking" | "processing" | "flip" | "done";
+interface DocFeedbackState {
+    key: DocFeedbackKey;
+    reticle: ReticleType;
+    /** The state holds the UI at least this long (ms) before a switch. */
+    minDurationMs: number;
+}
+declare const DOC_FEEDBACK_STATES: Readonly<Record<DocFeedbackKey, DocFeedbackState>>;
+/** Frame analysis → the feedback vote it casts (worst axis speaks). */
+declare function feedbackVoteOf(analysis: DocFrameAnalysis): DocFeedbackKey;
+/** Sliding vote window + exponential decay + per-state minimum hold. */
+declare class DocFeedbackAggregator {
+    private readonly windowMs;
+    /** Per-second decay factor — recent frames outvote stale ones. */
+    private readonly decayPerSecond;
+    private votes;
+    private current;
+    private currentSinceMs;
+    constructor(windowMs?: number, 
+    /** Per-second decay factor — recent frames outvote stale ones. */
+    decayPerSecond?: number);
+    reset(): void;
+    /** Force a terminal/choreography state (capture fired, side flip, upload). */
+    force(key: Extract<DocFeedbackKey, "processing" | "side_captured" | "captured">, nowMs: number): DocFeedbackState;
+    /** Cast this frame's vote and return the (possibly held) winning state. */
+    tick(vote: DocFeedbackKey, nowMs: number): DocFeedbackState;
+}
+
+/**
+ * Pre-fetch + cache the scanic chunk (call when the scan surface MOUNTS, before
+ * the camera is even granted) so the first detect tick pays no chunk-fetch
+ * latency. Fire-and-forget; failures fall back to the lazy path.
+ */
+declare function warmDocDetector(): void;
+/** Doc detect cadence per device class — scanic @480px is ~3–8× a face tick,
+ *  so the doc loop paces slower than the face profiles (findings §1: 2–5 Hz). */
+declare const DOC_CADENCE_HZ: Readonly<Record<DeviceClass, number>>;
+interface DocChecksPayload {
+    engine: "docv1";
+    /** Gate integrator 0..1 — the overlay ring. */
+    p: number;
+    plausible: boolean;
+    stableTicks: number;
+    quad: DocQuad | null;
+    /** Detect-frame size the quad coordinates live in (overlay scaling). */
+    frameWidth: number;
+    frameHeight: number;
+    /** Capture-v2 per-frame status vector (framing/lighting/blur/glare). */
+    analysis: DocFrameAnalysis;
+}
+/** Artifacts: `keyframe` = the full-res still of the framed side (JPEG). */
+type DocArtifacts = CaptureArtifacts & {
+    side?: DocSide;
+};
+interface CaptureSessionDocEvents {
+    statechange: {
+        state: CaptureState;
+    };
+    checks: DocChecksPayload;
+    /** dcv1.* message KEY — hosts translate; never prose. Deduped. */
+    guidance: {
+        key: string;
+    };
+    /** Capture-v2 AGGREGATED feedback (time-decay voted, min-duration held) —
+     *  the stage's message + reticle channel. Deduped on state key. */
+    feedback: DocFeedbackState;
+    artifacts: DocArtifacts;
+    error: {
+        kind: CaptureErrorKind;
+        retryable: boolean;
+    };
+}
+interface CaptureSessionDocOptions {
+    /** Host-owned <video playsInline muted>. */
+    video: HTMLVideoElement;
+    format?: DocFormat;
+    /** Side label stamped on the artifacts event (recto→verso sequencing). */
+    side?: DocSide;
+    thresholds?: Partial<DocGateThresholds>;
+    deviceClass?: DeviceClass;
+    /** (navigator.mediaDevices.getUserMedia — environment camera) */
+    getUserMedia?: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
+    /** (vendored scanic detectQuad) */
+    detect?: (image: ImageData) => Promise<DocQuad | null>;
+    /** (canvas downscale of the live video to the 480px detect frame) */
+    grabDetectFrame?: (video: HTMLVideoElement, targetWidth: number) => ImageData | null;
+    /** (full-res canvas still → JPEG blob + preview; quad passed for telemetry) */
+    captureStill?: (video: HTMLVideoElement, quad: DocQuad, detectSize: {
+        width: number;
+        height: number;
+    }) => Promise<{
+        blob: Blob;
+        previewDataUrl: string;
+    }>;
+    /** (performance.now) */
+    now?: () => number;
+    /** (setTimeout/clearTimeout) — the cadence pacer. */
+    setTimer?: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    clearTimer?: (id: ReturnType<typeof setTimeout>) => void;
+}
+type Handler<K extends keyof CaptureSessionDocEvents> = (payload: CaptureSessionDocEvents[K]) => void;
+declare class CaptureSessionDoc {
+    private readonly opts;
+    private readonly gate;
+    private readonly cadenceMs;
+    private readonly handlers;
+    private stream;
+    private timer;
+    private state;
+    private lastGuidance;
+    private attempt;
+    private capturing;
+    private readonly feedback;
+    private lastFeedbackKey;
+    constructor(opts: CaptureSessionDocOptions);
+    on<K extends keyof CaptureSessionDocEvents>(event: K, handler: Handler<K>): () => void;
+    private emit;
+    start(): Promise<void>;
+    /** Restart the gate for another side / a retake (same stream). */
+    rearm(side?: DocSide): void;
+    destroy(): void;
+    private setState;
+    private scheduleTick;
+    private tick;
+    /**
+     * BEST-FRAME capture window (capture-v2): the first ready tick captures a
+     * candidate immediately, then up to CAPTURE_EXTRA_CANDIDATES more stills are
+     * taken at CAPTURE_CANDIDATE_SPACING_MS while the user holds — each scored
+     * by the live detect-tick sharpness at its capture moment — and the SHARPEST
+     * wins. Beats first-acceptable-frame capture without decoding stills.
+     */
+    private fire;
+}
+/** Best-frame window: 2 extra candidates, 260ms apart, ≥8% sharper to replace. */
+declare const CAPTURE_EXTRA_CANDIDATES = 2;
+declare const CAPTURE_CANDIDATE_SPACING_MS = 260;
+
+/**
+ * Reasons the backend parks at `input_required` while attempts remain
+ * (identity-backend/src/checks/check-reasons.ts isRetryable tables — the single
+ * source of truth; identity-hosted/lib/reason-copy.ts mirrors the same rows).
+ */
+declare const RETRYABLE_REASONS: ReadonlySet<CheckReason>;
+/** A check the browser may still submit. */
+declare function isExecutable(step: HostedStepView | undefined): boolean;
+/** The session accepts no further submissions. */
+declare function isTerminalView(view: Pick<HostedSessionView, "status">): boolean;
+/** First step in `steps[]` order with state `pending | input_required` (the backend's frontier). */
+declare function frontierStep(view: HostedSessionView): HostedStepView | undefined;
+declare function stepOf(view: HostedSessionView, checkType: CheckType): HostedStepView | undefined;
+/**
+ * Fold a submit response (partner `SessionView`: no attemptsRemaining) into the
+ * hosted view: status/outcome/step states+reasons come from the response; the
+ * submitted check's `attemptsRemaining` is decremented locally (every accepted
+ * submit consumes exactly one attempt server-side — `max(0, cap - attempts)`).
+ * This keeps the happy path free of extra `GET /hosted/session` round-trips.
+ */
+declare function mergeSessionView(prev: HostedSessionView, next: SessionView, submitted: CheckType): HostedSessionView;
+/**
+ * Map the session view to the public result:
+ *  - `completed/approved → approved`, `completed/review` or `review_pending → review`,
+ *    `failed` or `completed/rejected → rejected` (reason = the deciding step's);
+ *  - `expired → unavailable` (no reason);
+ *  - in flight: a biometric step parked at `input_required` with a retryable
+ *    reason → `retry` when `autoRetry` and attempts remain, else `rejected`
+ *    (the partner opted out of retries — this capture was refused); a step in
+ *    `review` with nothing executable left → `review`; otherwise `unavailable`
+ *    (a non-biometric frontier the SDK cannot drive, or still processing).
+ */
+declare function mapSessionResult(view: HostedSessionView, opts: {
+    autoRetry: boolean;
+}): VerificationResult;
+
+declare const TURNSTILE_SCRIPT_SRC = "https://challenges.cloudflare.com/turnstile/v0/api.js";
+/** Bound on a single execute round-trip (challenge fetch + solve). */
+declare const TURNSTILE_EXECUTE_TIMEOUT_MS = 30000;
+interface TurnstileRenderParams {
+    sitekey: string;
+    callback: (token: string) => void;
+    "error-callback"?: (code?: string) => void;
+    execution?: "render" | "execute";
+    appearance?: "always" | "execute" | "interaction-only";
+}
+/** The subset of the Turnstile JS API this module uses. */
+interface TurnstileApi {
+    render(container: HTMLElement, params: TurnstileRenderParams): string | undefined;
+    execute(widgetId: string): void;
+    remove(widgetId: string): void;
+}
+/** Test-only: reset the module singleton between cases. */
+declare function resetTurnstileForTests(): void;
+/** Load the Turnstile script once (singleton; a load failure resets it so a
+ *  retry can re-attempt). */
+declare function loadTurnstile(): Promise<TurnstileApi>;
+/** Options of {@link executeTurnstile}. */
+interface ExecuteTurnstileOptions {
+    /** Bound on the challenge round-trip; default {@link TURNSTILE_EXECUTE_TIMEOUT_MS}. */
+    timeoutMs?: number;
+    /**
+     * Aborts the challenge: the promise rejects and the widget, its container and
+     * the timeout are cleaned up at once. `createVerification().destroy()` passes
+     * its own signal so a torn-down verification never leaves a widget behind.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Run one invisible execute-mode challenge and resolve its token. Rejects on
+ * challenge error, on `signal` abort, or after {@link TURNSTILE_EXECUTE_TIMEOUT_MS}
+ * — the verification maps a failure to `result {status:'unavailable',
+ * reason:'attestation'}` after one retry.
+ */
+declare function executeTurnstile(siteKey: string, opts?: ExecuteTurnstileOptions): Promise<string>;
+
+export { ASPECT_BANDS, type BlurStatus, CAPTURE_CANDIDATE_SPACING_MS, CAPTURE_EXTRA_CANDIDATES, CaptureSessionDoc, type CaptureSessionDocEvents, type CaptureSessionDocOptions, DOC_ANALYSIS_DEFAULTS, DOC_CADENCE_HZ, DOC_DETECT_WIDTH, DOC_FEEDBACK_STATES, DOC_GATE_V1_DEFAULTS, type DocArtifacts, type DocCatalogEntry, type DocChecksPayload, DocFeedbackAggregator, type DocFeedbackKey, type DocFeedbackState, type DocFormat, type DocFrameAnalysis, type DocFrameMeasures, type DocGateQuality, type DocGateThresholds, type DocGateTick, type DocGateTickInput, DocGateV1, type DocQuad, type DocQuadPoint, type DocSide, type ExecuteTurnstileOptions, type FramingStatus, type GlareStatus, type LightingStatus, MRZ_BAND_DEFAULTS, MR_DOC_CATALOG, type MrzBand, type MrzBandThresholds, RETRYABLE_REASONS, type ReticleType, TURNSTILE_EXECUTE_TIMEOUT_MS, TURNSTILE_SCRIPT_SRC, type TurnstileApi, type TurnstileRenderParams, analyzeDocFrame, aspectBand, detectMrzBand, executeTurnstile, feedbackVoteOf, frontierStep, isExecutable, isTerminalView, loadTurnstile, mapSessionResult, mergeSessionView, quadAreaFrac, quadBounds, quadIou, quadTiltRatio, resetTurnstileForTests, specularFraction, stepOf, warmDocDetector };