@incodetech/core 2.1.0-rc.1 → 2.1.0-rc.3

package/dist/personhood.d.ts

@@ -0,0 +1,534 @@
+import "./warmup-BJZPQIiX.js";
+import { n as StateMachine, t as AnyStateMachine } from "./StateMachine-C_AY4cs7.js";
+import { t as Manager } from "./Manager-CJ3G2zqi.js";
+import { t as ActorRefFrom } from "./Actor-CGEelYtQ.js";
+import { t as CameraStream } from "./camera-CNVUo-bC.js";
+import "./types-DgGlgyZT.js";
+import "./types-D_IceWxT.js";
+import { t as IncodeCanvas } from "./canvas-CJUmoXSD.js";
+import "./createFaceAvatar-B8pFpy6o.js";
+import "./types-BsYXnC5s.js";
+import { i as IStorageCapability, t as IWasmUtilCapability } from "./IWasmUtilCapability-d2XvzaCk.js";
+import { n as PermissionStatus, t as PermissionResult } from "./types-Duy2rDxF.js";
+import { n as DetectionStatus } from "./types-CxW2e0Ar.js";
+import { t as FaceDetectionProvider } from "./FaceDetectionProvider-B78455D4.js";
+import { t as StreamCanvasCapture } from "./StreamCanvasCapture-DS1TOoiH.js";
+import { t as DeepsightService } from "./deepsightService-CMB9XjES.js";
+
+//#region src/modules/personhood/types.d.ts
+
+/**
+ * Head pose (degrees) computed per-frame from the WASM face detector.
+ * Used internally by the personhood detection actor to accumulate the
+ * yaw/pitch range that feeds the server-side `headMotion` spoof check.
+ *
+ * Re-exported from `@incodetech/core/personhood` as a convenience type
+ * for integrators running their own face-tracking pipelines (e.g.
+ * MediaPipe FaceLandmarker) that want to share a pose shape with
+ * other code that consumes personhood internals — the SDK itself
+ * does not expose a runtime pose stream.
+ *
+ * `faceSizeRatio` is an orientation-invariant 0–1 proxy for how close
+ * the user is to the camera, computed by the producer as
+ * `sqrt(face.width * face.height) / min(frame.width, frame.height)`.
+ * Same value on landscape (laptop) or portrait (phone) cameras since
+ * the denominator is the frame's *narrower* dimension. Optional —
+ * absent when the producer doesn't have access to frame size.
+ */
+type HeadPose = {
+  pitch: number;
+  yaw: number;
+  roll: number;
+  faceSizeRatio?: number;
+};
+/** Signals we hand back to the integrator alongside the human verdict. */
+type DeviceBehavioralSignals = {
+  /** Visitor fingerprint hash from the Thumbmark provider. */
+  deviceFingerprint: string;
+  /** Standard browser / OS info (model, os, browser name + version). */
+  userAgentClass: string;
+  /** Matches automation markers (phantom, nightmare, domAutomation, etc.). */
+  emulator: boolean;
+  /** `navigator.webdriver` is truthy — chromedriver / geckodriver / playwright. */
+  webdriver: boolean;
+  /** Liveness / injection surface reported by local detection. */
+  headlessHints: readonly string[];
+};
+/**
+ * One element of the `spoofCheckResults` array. Carries a single
+ * anti-spoof / liveness / automation check the on-device pipeline
+ * ran, with its outcome and (when failed) a short tag explaining
+ * why. The same shape is sent to `/omni/personhood/verify` and
+ * exposed on {@link PersonhoodVerdict.spoofCheckResults} so
+ * integrators and UIs can introspect what passed and what failed
+ * without parsing the comma-joined `reason` string.
+ *
+ * Check ids the SDK currently emits:
+ *   - `physicalAttack`   — Deepsight pipeline anti-spoof. Failed
+ *     when `analysisStatus` carries an explicit spoof signal
+ *     (`spoof_suspected`, `injection`, etc.).
+ *   - `virtualCamera`    — label-based detection of OBS / ManyCam /
+ *     etc. on the camera track.
+ *   - `motionLiveness`   — Deepsight's motion-based liveness check
+ *     (accelerometer + temporal frame analysis).
+ *   - `headMotion`       — accumulated yaw + pitch range. Failed
+ *     when below the minimum motion threshold (user held still).
+ *   - `faceDetection`    — terminal detection outcome (success vs
+ *     timeout / error).
+ *   - `webdriver`        — `navigator.webdriver` is truthy.
+ *   - `emulator`         — automation framework markers
+ *     (PhantomJS / Selenium / Nightmare / etc.).
+ *   - `headlessBrowser`  — headless-browser fingerprinting hints.
+ *
+ * `result: 'unknown'` is reserved for checks that ran but couldn't
+ * render a definitive verdict (e.g. desktop with no accelerometer
+ * permission for motion liveness). Absence of evidence is
+ * intentionally not the same as evidence of a spoof.
+ *
+ * `reason` is populated only when `result === 'failed'` and gives
+ * a short stable tag the integrator's server can pattern-match on:
+ * the same tags that show up in the verdict's `reason` string
+ * (`no_motion`, `spoof_suspected`, `virtual_camera`, etc.) plus
+ * raw underlying values (`analysisStatus` strings, detection
+ * outcome) where useful.
+ */
+type SpoofCheckResult = {
+  check: string;
+  result: 'passed' | 'failed' | 'unknown';
+  reason?: string;
+};
+/** On-device liveness outcome — filled in after the detection loop succeeds. */
+type LivenessOutcome = {
+  /** True when the camera stream is a known virtual cam (OBS/ManyCam/etc.). */
+  virtualCamera: boolean;
+  /** Opaque Deepsight pipeline check status (string like "PASS"/"FAIL"). */
+  analysisStatus: string;
+  /** Deepsight motion status string. */
+  motionStatus: string;
+  /** Range of yaw observed during detection (degrees). */
+  yawRange: number;
+  /** Range of pitch observed during detection (degrees). */
+  pitchRange: number;
+  /**
+   * Full Deepsight metadata blob from `wasmUtil.getMetadata()`. Opaque
+   * string (typically a JSON-serialized payload of the pipeline's
+   * collected signals — frame quality, motion features, environment
+   * fingerprints, etc.) intended for server-side cross-referencing
+   * with the evidence record. Empty when the Deepsight pipeline isn't
+   * available (e.g. WASM init failed).
+   */
+  metadata: string;
+  /**
+   * Deepsight pipeline state string (e.g. running / completed / error
+   * substates). Useful for diagnosing why an analysis status came
+   * back negative — the state often carries the underlying cause that
+   * `analysisStatus` only summarizes.
+   */
+  pipelineState: string;
+};
+/** Final verdict returned from `/omni/personhood/verify`. */
+type PersonhoodVerdict = {
+  human: boolean;
+  confidence: number;
+  evidenceId: string;
+  /**
+   * Comma-joined list of failure tags when `human === false`. Same
+   * tags that appear individually in {@link spoofCheckResults}
+   * entries' `reason` fields — kept for backward compat and quick
+   * inspection. Undefined when the verdict is human.
+   */
+  reason?: string;
+  signals: DeviceBehavioralSignals;
+  /** Present for the on-device path. Absent on server fallback. */
+  liveness?: LivenessOutcome;
+  /**
+   * Per-check breakdown of every anti-spoof / liveness / automation
+   * gate the on-device pipeline ran. Lets integrators see WHICH
+   * checks passed or failed instead of having to parse the
+   * collapsed `reason` string. The same array is the body of the
+   * `/omni/personhood/verify` POST. Empty on the server-fallback
+   * path (no on-device pipeline ran).
+   */
+  spoofCheckResults: SpoofCheckResult[];
+};
+type PersonhoodConfig = {
+  /** Integrator's site key (equivalent to a reCAPTCHA site key). */
+  siteKey: string;
+  /**
+   * OAuth2 client-credentials used to mint the `Authorization: Bearer`
+   * token for the verify hop (`POST /omni/oauth2/token`,
+   * `grant_type=client_credentials&scope=openid`). Required for the
+   * live (non-mock) flow; without them the token fetch fails and the
+   * flow halts before the camera opens.
+   *
+   * ⚠️ These are sent from the browser, so `clientSecret` is exposed to
+   * anyone who can read the page's source / network traffic. Acceptable
+   * only where that exposure is tolerable; a server-minted Bearer token
+   * is the hardened alternative.
+   */
+  clientId?: string;
+  clientSecret?: string;
+  /**
+   * Origin of the authorization server that mints the OAuth2 Bearer token
+   * (e.g. `https://auth.stage.incode.com`). The path is fixed — the token
+   * is `POST`ed to this origin's own `/oauth2/token`.
+   *
+   * When set, the browser calls the auth server DIRECTLY through a
+   * dedicated HTTP client (topology B): the auth origin is separate from
+   * the omni `apiURL`, so this is a genuine cross-origin call and the auth
+   * server must allow the integrator's `Origin` (CORS). The dedicated
+   * client inherits the omni client's `customHeaders` (notably
+   * `x-api-key`, which the auth server requires) from the active SDK
+   * config, so no extra credential plumbing is needed here.
+   *
+   * When omitted, the token is minted through the shared omni client at
+   * `/omni/oauth2/token` — i.e. the omni gateway is expected to front the
+   * auth server (topology A). Single-origin deployments need not set this.
+   *
+   * Only the auth-token hop honors this; the verify hop
+   * (`/omni/personhood/verify`) always uses the omni `apiURL`.
+   */
+  authBaseUrl?: string;
+  /**
+   * Minimum confidence required to pass. Default: `0.75`
+   * (`DEFAULT_PERSONHOOD_THRESHOLD`). Exposed so integrators can tighten or
+   * loosen gates per use case.
+   */
+  threshold?: number;
+  /**
+   * When true, `/omni/personhood/verify` is bypassed and a canned verdict
+   * is returned (the local on-device verdict is used as-is). Defaults to
+   * `false`. Set to `true` in dev environments where the backend is not
+   * yet available.
+   */
+  mockVerify?: boolean;
+  /**
+   * Time-to-live (ms) for cached proofs of the same browser session. Not yet
+   * enforced at phase 0 (documented for forward-compat).
+   */
+  cacheTtlMs?: number;
+  /** Optional: called every time an interesting signal is observed. */
+  onSignal?: (event: {
+    type: 'pose' | 'detection' | 'verdict' | 'error';
+    payload: unknown;
+  }) => void;
+  /** Hides the initial tutorial screen. Default: false. */
+  showTutorial?: boolean;
+  /**
+   * When true, the detection flow auto-completes with whatever frame
+   * is available after a short hard deadline, regardless of why
+   * WASM's autocapture criteria didn't fire (user too far, bad
+   * framing, low light, occlusion, etc). The deadline starts ticking
+   * the moment the camera produces its first frame — not when
+   * detection begins — so a slow camera cold-start doesn't eat into
+   * the user's capture window. Once the deadline lands, the
+   * provider's best frame (or the most recent processed frame if no
+   * best-shot was recorded) is pushed through to liveness analysis.
+   *
+   * The resulting verdict usually has lower confidence — a non-ideal
+   * frame gives the detector less signal — but at least produces a
+   * definitive `human: true | false` outcome instead of leaving the
+   * modal stuck.
+   *
+   * If the camera never produces a frame at all (e.g. the user
+   * blocked permission mid-flow, browser failed to start the stream)
+   * this flag does nothing — there's literally no frame to capture
+   * — and the standard error path applies.
+   *
+   * Default: `false`.
+   */
+  autoComplete?: boolean;
+};
+type PersonhoodDependencies = {
+  storage: IStorageCapability;
+  getWasmUtil: () => Promise<IWasmUtilCapability>;
+};
+declare const PERSONHOOD_ERROR_CODES: {
+  readonly CAMERA_DENIED: "CAMERA_DENIED";
+  readonly DETECTION_FAILED: "DETECTION_FAILED";
+  /**
+   * The OAuth2 token fetch (`POST /omni/oauth2/token`,
+   * client-credentials) failed — non-2xx, network error, or no
+   * `access_token` in the response. The flow halts before the user
+   * opens the camera so a misconfigured `clientId` / `clientSecret`
+   * surfaces immediately instead of walking them through a capture we
+   * can't authenticate the verify hop for.
+   */
+  readonly AUTH_TOKEN_FAILED: "AUTH_TOKEN_FAILED";
+  readonly VERIFY_FAILED: "VERIFY_FAILED";
+  readonly INJECTION_SUSPECTED: "INJECTION_SUSPECTED";
+  readonly EMULATOR_DETECTED: "EMULATOR_DETECTED";
+  readonly TIMEOUT: "TIMEOUT";
+  readonly UNKNOWN: "UNKNOWN";
+};
+type PersonhoodErrorCode = (typeof PERSONHOOD_ERROR_CODES)[keyof typeof PERSONHOOD_ERROR_CODES];
+//#endregion
+//#region src/modules/personhood/personhoodStateMachine.d.ts
+type PersonhoodInput = {
+  config: PersonhoodConfig;
+  dependencies: PersonhoodDependencies;
+};
+type PersonhoodMachineContext = {
+  config: PersonhoodConfig;
+  dependencies: PersonhoodDependencies;
+  permissionResult: PermissionResult | 'refresh' | undefined;
+  /**
+   * Why the server-fallback path was taken, so `requestServerFallback` reports
+   * the real cause instead of a hardcoded value. `undefined` means
+   * `permission_denied` (the original/most common cause).
+   */
+  fallbackReason: 'no_camera' | 'permission_denied' | 'unsupported_browser' | undefined;
+  stream: CameraStream | undefined;
+  provider: FaceDetectionProvider | undefined;
+  frameCapturer: StreamCanvasCapture | undefined;
+  deepsightService: DeepsightService | undefined;
+  detectionStatus: DetectionStatus;
+  /**
+   * Yaw + pitch ranges captured during detection (in degrees). Accumulated
+   * in the detection actor's closure and committed to context once when
+   * DETECTION_SUCCESS fires — not per-frame. Pose itself never lives in
+   * context: per-frame samples are consumed inside the detection actor
+   * (and discarded) so the manager-subscribed UI tree doesn't churn at
+   * camera frame rate.
+   */
+  yawRange: number;
+  pitchRange: number;
+  capturedImage: IncodeCanvas | undefined;
+  livenessOutcome: LivenessOutcome | undefined;
+  signals: DeviceBehavioralSignals | undefined;
+  /**
+   * Personhood session token from `GET /omni/personhood/token`. Lives
+   * in actor context (not a module-level slot) so two
+   * `createPersonhoodManager()` instances active concurrently can't
+   * trample each other's tokens, and so `actor.stop()` cleans it up
+   * implicitly. Threaded into the `analyzeLiveness` and
+   * `verifyOnDevice` actor inputs; those actors attach it as an
+   * `Authorization: Bearer` header explicitly rather than going
+   * through the shared `api` wrapper's auto-injection (which only
+   * carries `currentToken` for the main session). `undefined` until
+   * the parallel-init phase completes.
+   */
+  token: string | undefined;
+  /**
+   * Verdict computed locally from device signals + on-device
+   * liveness analysis. Kept separately from `verdict` (the final,
+   * server-authoritative one) so the verify-on-server step can use
+   * it as a fallback when the network call fails. Once verify
+   * succeeds, `verdict` is the server's response and this stays as
+   * a debug reference; integrators only see `verdict`.
+   */
+  localVerdict: PersonhoodVerdict | undefined;
+  verdict: PersonhoodVerdict | undefined;
+  error: {
+    code: PersonhoodErrorCode;
+    message?: string;
+  } | undefined;
+  resetDetection: (() => void) | undefined;
+};
+type PersonhoodEvent = {
+  type: 'LOAD';
+} | {
+  type: 'NEXT_STEP';
+} | {
+  type: 'REQUEST_PERMISSION';
+} | {
+  type: 'GO_TO_LEARN_MORE';
+} | {
+  type: 'BACK';
+} | {
+  type: 'QUIT';
+} | {
+  type: 'RESET';
+}
+/**
+ * Triggered from the UI when the user declines camera access but still
+ * wants a verdict (server fallback). Also dispatched automatically when
+ * the device has no camera at all.
+ */ | {
+  type: 'USE_FALLBACK';
+} | {
+  type: 'DETECTION_UPDATE';
+  status: DetectionStatus;
+} | {
+  type: 'DETECTION_SUCCESS';
+  canvas?: IncodeCanvas;
+  /** Final observed head-pose yaw range (max − min) in degrees. */
+  yawRange: number;
+  /** Final observed head-pose pitch range (max − min) in degrees. */
+  pitchRange: number;
+} | {
+  type: 'DETECTION_RESET_READY';
+  reset: () => void;
+};
+declare const _personhoodMachine: AnyStateMachine;
+type PersonhoodMachine = typeof _personhoodMachine;
+/**
+ * Public machine value. Typed as `AnyStateMachine` for declaration file
+ * portability — mirrors the convention used by `selfieMachine` and the
+ * other Core modules. Type safety is enforced by the `setup()` config
+ * above, not by the exported binding.
+ */
+declare const personhoodMachine: AnyStateMachine;
+/**
+ * Narrow typed machine used by the Actor helpers. The non-context/event/
+ * input slots are widened to `any` because XState's full generic surface
+ * isn't worth threading through every module — we only need the slots
+ * the actor + manager actually consume. Same pattern as `SelfieMachine`.
+ */
+type PersonhoodTypedMachine = StateMachine<PersonhoodMachineContext, PersonhoodEvent, any, any, any, any, any, any, any, PersonhoodInput, any, any, any, any>;
+//#endregion
+//#region src/modules/personhood/personhoodActor.d.ts
+type CreatePersonhoodActorOptions = {
+  config: PersonhoodConfig;
+  dependencies?: PersonhoodDependencies;
+};
+type PersonhoodActor = ActorRefFrom<PersonhoodTypedMachine>;
+/**
+ * Creates and starts a Personhood XState actor. Defaults to the production
+ * browser storage + WASM providers; passing `dependencies` lets tests and the
+ * extensibility layer swap them for fakes.
+ */
+declare function createPersonhoodActor(options: CreatePersonhoodActorOptions): PersonhoodActor;
+//#endregion
+//#region src/modules/personhood/personhoodManager.d.ts
+/** Initial state (before `load()` is invoked). */
+type PersonhoodIdleState = {
+  status: 'idle';
+};
+/** Collecting local device + behavioural signals before any UI is shown. */
+type PersonhoodLoadingState = {
+  status: 'loading';
+  phase: 'collectingSignals' | 'checkingPermission';
+};
+/** Optional opt-in tutorial screen. */
+type PersonhoodTutorialState = {
+  status: 'tutorial';
+};
+/** Camera permission handshake. */
+type PersonhoodPermissionsState = {
+  status: 'permissions';
+  permissionStatus: PermissionStatus | 'denied';
+};
+/**
+ * Live camera + avatar-driving state.
+ *
+ * `stream` is the active camera MediaStream. It is **not** displayed to
+ * the user by default (the whole UX promise is "stylized avatar, not
+ * raw camera feed"); it's exposed so integrators can render the avatar
+ * by piping the stream into their own face-tracking pipeline (e.g.
+ * MediaPipe FaceLandmarker). Head-pose is intentionally **not** on
+ * this state type — the SDK extracts pose internally for the
+ * server-side `headMotion` spoof check, but UI consumers should
+ * compute their own pose off `stream` rather than subscribing to a
+ * frame-rate channel here (which would re-render on every frame).
+ */
+type PersonhoodCaptureState = {
+  status: 'capture';
+  captureStatus: 'initializing' | 'detecting';
+  detectionStatus: DetectionStatus;
+  stream: MediaStream | undefined;
+};
+/** Synthesizing the local on-device verdict. No network call — the primary path. */
+type PersonhoodProcessingState = {
+  status: 'processing';
+  /**
+   * Which stage of the local pipeline we're on:
+   *  - 'analyzing' → Deepsight analysis + pose-motion guard (post-capture)
+   *  - 'local' → synthesizing verdict from the collected signals
+   *  - 'fallback' → server-side liveness fallback (no camera / denied)
+   */
+  source: 'analyzing' | 'local' | 'fallback';
+};
+/** Verdict is in. Integrators read `verdict` to obtain `{ human, confidence, evidenceId, signals }`. */
+type PersonhoodFinishedState = {
+  status: 'finished';
+  verdict: PersonhoodVerdict;
+};
+type PersonhoodClosedState = {
+  status: 'closed';
+};
+type PersonhoodErrorState = {
+  status: 'error';
+  error: {
+    code: PersonhoodErrorCode;
+    message?: string;
+  };
+};
+type PersonhoodState = PersonhoodIdleState | PersonhoodLoadingState | PersonhoodTutorialState | PersonhoodPermissionsState | PersonhoodCaptureState | PersonhoodProcessingState | PersonhoodFinishedState | PersonhoodClosedState | PersonhoodErrorState;
+/**
+ * Manager built from an externally-owned actor (extensibility path).
+ */
+declare function createPersonhoodManagerFromActor(actor: PersonhoodActor): Manager<PersonhoodState> & {
+  /** Starts the flow (goes to tutorial or capture depending on config). */
+  load(): void;
+  /** Advances from tutorial → capture. */
+  nextStep(): void;
+  /** Triggers `getUserMedia` when in `permissions.idle`. */
+  requestPermission(): void;
+  /** Shows the permission rationale view. */
+  goToLearnMore(): void;
+  /** Returns from learn-more → permission prompt. */
+  back(): void;
+  /** Dismisses the widget into the terminal `closed` state. */
+  close(): void;
+  /** Resets from the (non-final) `error` state back to `idle`. */
+  reset(): void;
+  /**
+   * Skip the on-device path and hit the server fallback. Wired to the
+   * "Continue without camera" button on the permission-denied screen; also
+   * dispatched automatically when the device has no camera at all.
+   */
+  useFallback(): void;
+};
+/**
+ * Creates a Personhood manager for the drop-in widget.
+ *
+ * The manager exposes:
+ * - `state: PersonhoodState` via `getState()` / `subscribe()`
+ * - Lifecycle controls: `load`, `nextStep`, `requestPermission`,
+ *   `goToLearnMore`, `back`, `close`, `reset`, `useFallback`, `stop`
+ *
+ * Head-pose is intentionally **not** exposed as a stream. The SDK
+ * extracts pose internally for the server-side `headMotion` spoof
+ * check; UI consumers that need a frame-rate pose signal (avatar
+ * mirroring, etc.) should run their own face-tracking pipeline
+ * (e.g. MediaPipe FaceLandmarker) against `state.stream` instead.
+ *
+ * @example
+ * ```ts
+ * const manager = createPersonhoodManager({
+ *   config: { siteKey: 'demo', mockVerify: true },
+ * });
+ * manager.subscribe((state) => {
+ *   if (state.status === 'finished') {
+ *     console.log('human?', state.verdict.human);
+ *   }
+ * });
+ * manager.load();
+ * ```
+ */
+declare function createPersonhoodManager(options: CreatePersonhoodActorOptions): Manager<PersonhoodState> & {
+  /** Starts the flow (goes to tutorial or capture depending on config). */
+  load(): void;
+  /** Advances from tutorial → capture. */
+  nextStep(): void;
+  /** Triggers `getUserMedia` when in `permissions.idle`. */
+  requestPermission(): void;
+  /** Shows the permission rationale view. */
+  goToLearnMore(): void;
+  /** Returns from learn-more → permission prompt. */
+  back(): void;
+  /** Dismisses the widget into the terminal `closed` state. */
+  close(): void;
+  /** Resets from the (non-final) `error` state back to `idle`. */
+  reset(): void;
+  /**
+   * Skip the on-device path and hit the server fallback. Wired to the
+   * "Continue without camera" button on the permission-denied screen; also
+   * dispatched automatically when the device has no camera at all.
+   */
+  useFallback(): void;
+};
+type PersonhoodManager = ReturnType<typeof createPersonhoodManager>;
+//#endregion
+export { type CreatePersonhoodActorOptions, type DeviceBehavioralSignals, type HeadPose, type LivenessOutcome, PERSONHOOD_ERROR_CODES, type PersonhoodActor, type PersonhoodCaptureState, type PersonhoodClosedState, type PersonhoodConfig, type PersonhoodDependencies, type PersonhoodErrorCode, type PersonhoodErrorState, type PersonhoodEvent, type PersonhoodFinishedState, type PersonhoodIdleState, type PersonhoodInput, type PersonhoodLoadingState, type PersonhoodMachine, type PersonhoodMachineContext, type PersonhoodManager, type PersonhoodPermissionsState, type PersonhoodProcessingState, type PersonhoodState, type PersonhoodTutorialState, type PersonhoodVerdict, type SpoofCheckResult, createPersonhoodActor, createPersonhoodManager, createPersonhoodManagerFromActor, personhoodMachine };