@smileid/usesmileid 12.0.1 → 12.1.0

package/src/presentation/flow/validation/flow_validator.ts

@@ -1,462 +0,0 @@
-import type { MLConfig } from "../../../core/models/ml_config";
-import { CaptureType } from "../../../core/models/ml_config";
-import type { NetworkConfig } from "../../../core/models/network_config";
-import type {
-  BiometricKYCParams,
-  ConsentInformation,
-  DocumentVerificationParams,
-  EnhancedDocumentVerificationParams,
-  EnhancedKYCParams,
-  UserDetails,
-} from "../../../core/models/params";
-import { JobType } from "../../../core/models/job_type";
-import type {
-  DocumentCaptureConfigBuilder,
-  ScreenSpec,
-  SelfieCaptureConfigBuilder,
-} from "../dsl/builder/screens_builder";
-
-type ConsentScreenStep = Extract<ScreenSpec, { kind: "consent" }>;
-import { IssueSeverity } from "../../../core/exception/issue_severity";
-import {
-  InvalidConsentConfigException,
-  InvalidConsentInformationException,
-} from "../../../core/exception/consent_validation_exceptions";
-import {
-  InvalidFieldValueException,
-  MissingJobTypeException,
-  MissingMLConfigurationBlockException,
-  MissingNetworkConfigurationBlockException,
-} from "../../../core/exception/job_validation_exceptions";
-import {
-  AgentModeWithEnhancedLivenessException,
-  InvalidDocumentCaptureConfigException,
-  InvalidMissingCaptureTypeException,
-} from "../../../core/exception/capture_validation_exceptions";
-import { EmptyScreensBlockException } from "../../../core/exception/screen_config_validation_exceptions";
-import { ValidationState, type ValidationIssue } from "./validation_state";
-import { collectJobTypeIssues } from "./job_type_validator";
-
-/**
- * Pure flow validator — returns typed `UseSmileIDValidationException`
- * instances. The same instances are exposed via `b.validate()` and
- * thrown by `b.build()` (after picking the first `error`-severity
- * issue), so partner regex-matchers and `instanceof` checks see the
- * same object whether they're inspecting validate-state or catching
- * a thrown error.
- *
- * `runFlowValidation` owns only the builder / job-agnostic concerns:
- * empty screens, per-screen capture / consent config, ML / Network
- * block presence, missing job type, the standalone param validators,
- * and the consent-mutex check. Every flow-composition rule — screen
- * ordering, duplicate screen types, preview placement, analyzer
- * dependencies, and per-job field requirements — is owned by the
- * per-`JobType` validators in `job_type_validator.ts`, dispatched via
- * `collectJobTypeIssues`.
- *
- * Rule order, message wording, severity, and `errorCode` values are
- * the contract surface partners see. Don't reword existing rules
- * without a coordinated change — partner tooling regex-matches on
- * the message text and pivots on the `errorCode`.
- */
-
-type FlowValidatorInput = {
-  readonly steps: readonly ScreenSpec[];
-  readonly network?: NetworkConfig | undefined;
-  readonly ml?: MLConfig | undefined;
-  readonly consentInformation?: ConsentInformation | undefined;
-  readonly enhancedKYCParams?: EnhancedKYCParams | undefined;
-  readonly biometricKYCParams?: BiometricKYCParams | undefined;
-  readonly documentVerificationParams?: DocumentVerificationParams | undefined;
-  readonly enhancedDocumentVerificationParams?:
-    | EnhancedDocumentVerificationParams
-    | undefined;
-  readonly userDetails?: UserDetails | undefined;
-};
-
-/**
- * Agent mode captures on the rear lens while the head-turn challenge is only
- * validated for front-camera framing, so the pair is refused rather than
- * silently dropping one of them.
- */
-function selfieConfigIssues(
-  config: SelfieCaptureConfigBuilder | undefined,
-): ValidationIssue[] {
-  if (config?.allowAgentMode && config.enableEnhancedLiveness) {
-    return [new AgentModeWithEnhancedLivenessException()];
-  }
-  return [];
-}
-
-/** Surfaces at most one issue: missing block > missing type > bad aspect ratio. */
-function documentConfigIssues(
-  config: DocumentCaptureConfigBuilder | undefined,
-): ValidationIssue[] {
-  if (config === undefined) {
-    return [
-      new InvalidDocumentCaptureConfigException({
-        reason: "document is required when mode is Document",
-      }),
-    ];
-  }
-  if (config.documentType === undefined) {
-    return [
-      new InvalidDocumentCaptureConfigException({
-        reason: "documentType is required for document capture",
-      }),
-    ];
-  }
-  if (
-    config.knownIdAspectRatio !== undefined &&
-    config.knownIdAspectRatio <= 0
-  ) {
-    return [
-      new InvalidDocumentCaptureConfigException({
-        reason: "knownIdAspectRatio must be > 0 if provided",
-      }),
-    ];
-  }
-  return [];
-}
-
-/**
- * Quick triage of the in-progress builder state. Today the only rule
- * surfaced is the empty-screens-block error — `b.screens(...)` must
- * register at least one screen before the builder can produce a flow.
- * `b.validate()` calls this; the full rule set runs inside `build()`.
- */
-export function runBuilderValidation(
-  steps: readonly ScreenSpec[],
-): ValidationIssue[] {
-  const issues: ValidationIssue[] = [];
-  if (steps.length === 0) {
-    issues.push(new EmptyScreensBlockException());
-  }
-  return issues;
-}
-
-/**
- * Run every flow-level validation rule and return the collected
- * issues. Empty array means valid.
- *
- * Rule order is deterministic so callers diffing two outputs see
- * stable output. `build()` returns `{kind: 'invalid'}` carrying these
- * issues when any are `error`-severity.
- */
-export function runFlowValidation(
-  input: FlowValidatorInput,
-): ValidationIssue[] {
-  const issues: ValidationIssue[] = [];
-
-  if (input.steps.length === 0) {
-    issues.push(new EmptyScreensBlockException());
-    // Without screens, every other rule is vacuous — short-circuit
-    // to avoid producing follow-on noise.
-    return issues;
-  }
-
-  // Capture screens must declare a captureType. Partners set this inside
-  // the configure block; if they forget, surface the typed exception so
-  // it routes through `onResult.failure` like every other validation issue.
-  for (const step of input.steps) {
-    if (step.kind === "capture") {
-      if (step.config.captureType === undefined) {
-        issues.push(new InvalidMissingCaptureTypeException());
-      }
-      if (step.config.captureType === CaptureType.selfie) {
-        issues.push(...selfieConfigIssues(step.config.selfieConfig));
-      }
-      if (step.config.captureType === CaptureType.document) {
-        issues.push(...documentConfigIssues(step.config.documentConfig));
-      }
-    }
-  }
-
-  const hasCaptureScreen = input.steps.some((s) => s.kind === "capture");
-  const hasProcessingScreen = input.steps.some((s) => s.kind === "processing");
-
-  if (hasCaptureScreen && !input.ml) {
-    issues.push(new MissingMLConfigurationBlockException());
-  }
-  if (hasProcessingScreen && !input.network) {
-    issues.push(new MissingNetworkConfigurationBlockException());
-  }
-  // A processing screen always requires a resolved jobType. Fail the
-  // build (ERROR) whenever it's missing — whether or not a network
-  // block was provided. The missing-network WARNING above still fires
-  // alongside this when the block is absent.
-  if (hasProcessingScreen) {
-    const jobType = input.network?.config?.jobType;
-    if (jobType === undefined || jobType === JobType.unknown) {
-      issues.push(new MissingJobTypeException());
-    }
-  }
-
-  // Consent screen config validation — partnerName must be non-empty
-  // when a consent screen is in the flow. The consent screen's
-  // attribution line renders blank without it, which partners
-  // typically don't notice until QA.
-  const consentStep = input.steps.find(
-    (s): s is ConsentScreenStep => s.kind === "consent",
-  );
-  if (
-    consentStep &&
-    (!consentStep.config.partnerName || !consentStep.config.partnerName.trim())
-  ) {
-    issues.push(
-      new InvalidConsentConfigException({
-        reason: "partnerName cannot be empty",
-      }),
-    );
-  }
-  if (consentStep && consentStep.config.partnerIcon === undefined) {
-    issues.push(
-      new InvalidConsentConfigException({
-        reason: "partnerIcon is required for the consent screen",
-      }),
-    );
-  }
-  if (
-    consentStep &&
-    (consentStep.config.partnerPrivacyPolicyUrl === undefined ||
-      !consentStep.config.partnerPrivacyPolicyUrl.trim())
-  ) {
-    issues.push(
-      new InvalidConsentConfigException({
-        reason: "partnerPrivacyPolicyUrl is required for the consent screen",
-      }),
-    );
-  }
-
-  const hasConsentScreen = consentStep !== undefined;
-  if (hasConsentScreen && input.consentInformation !== undefined) {
-    issues.push(
-      new InvalidConsentConfigException({
-        reason:
-          "Exactly one form of consent is required — remove the consent { } screen if using consentInformation, or clear consentInformation if using the consent screen",
-      }),
-    );
-  }
-
-  if (input.consentInformation) {
-    issues.push(...runConsentValidation(input.consentInformation));
-  }
-  if (input.enhancedKYCParams) {
-    issues.push(...runEnhancedKYCParamsValidation(input.enhancedKYCParams));
-  }
-  if (input.biometricKYCParams) {
-    issues.push(...runBiometricKYCParamsValidation(input.biometricKYCParams));
-  }
-  if (input.documentVerificationParams) {
-    issues.push(
-      ...runDocumentVerificationParamsValidation(
-        input.documentVerificationParams,
-      ),
-    );
-  }
-  if (input.enhancedDocumentVerificationParams) {
-    issues.push(
-      ...runEnhancedDocumentVerificationParamsValidation(
-        input.enhancedDocumentVerificationParams,
-      ),
-    );
-  }
-  if (input.userDetails) {
-    issues.push(...runUserDetailsValidation(input.userDetails));
-  }
-
-  // Every flow-composition rule (screen ordering, duplicate screens,
-  // preview placement, analyzer dependencies, per-job field
-  // requirements) lives in job_type_validator.ts. FlowValidator owns
-  // only the builder / job-agnostic concerns above and delegates the
-  // per-jobType pass here. The dispatch resolves a validator from the
-  // configured jobType, falling back to a generic structural validator
-  // when the jobType is unknown so prototyping flows still get
-  // ordering / duplicate / preview feedback.
-  collectJobTypeIssues(input, issues);
-
-  return issues;
-}
-
-/**
- * Validate an `EnhancedKYCParams` payload in isolation. Used by
- * `b.validateEnhancedKYCParams(params)` so partners can pre-flight a
- * payload before assigning it to the builder.
- */
-export function runEnhancedKYCParamsValidation(
-  params: EnhancedKYCParams,
-): ValidationIssue[] {
-  return runKYCParamsValidation(params);
-}
-
-/**
- * Validate a `BiometricKYCParams` payload in isolation. Used by
- * `b.validateBiometricKYCParams(params)`.
- */
-export function runBiometricKYCParamsValidation(
-  params: BiometricKYCParams,
-): ValidationIssue[] {
-  return runKYCParamsValidation(params);
-}
-
-/**
- * Validate a `DocumentVerificationParams` payload in isolation. `country`
- * must be non-blank; `idType` is optional, but a present-but-blank value
- * is rejected.
- */
-export function runDocumentVerificationParamsValidation(
-  params: DocumentVerificationParams,
-): ValidationIssue[] {
-  const issues: ValidationIssue[] = [];
-  if (!params.country || !params.country.trim()) {
-    issues.push(
-      new InvalidFieldValueException({
-        fieldName: "country",
-        reason: "must not be blank",
-      }),
-    );
-  }
-  if (params.idType !== undefined && !params.idType.trim()) {
-    issues.push(
-      new InvalidFieldValueException({
-        fieldName: "idType",
-        reason: "must not be blank",
-      }),
-    );
-  }
-  return issues;
-}
-
-/**
- * Validate an `EnhancedDocumentVerificationParams` payload in isolation.
- * Both `country` and `idType` are required and must be non-blank.
- */
-export function runEnhancedDocumentVerificationParamsValidation(
-  params: EnhancedDocumentVerificationParams,
-): ValidationIssue[] {
-  const issues: ValidationIssue[] = [];
-  for (const field of ["country", "idType"] as const) {
-    const value = params[field];
-    if (!value || !value.trim()) {
-      issues.push(
-        new InvalidFieldValueException({
-          fieldName: field,
-          reason: "must not be blank",
-        }),
-      );
-    }
-  }
-  return issues;
-}
-
-/**
- * Validate a `ConsentInformation` payload in isolation. Used by
- * `b.validateConsent(consent)` so partners can pre-flight a payload
- * pulled from their own storage before assigning it to the builder.
- */
-export function runConsentValidation(
-  consent: ConsentInformation,
-): ValidationIssue[] {
-  const issues: ValidationIssue[] = [];
-  if (!consent.granted) {
-    issues.push(
-      new InvalidConsentInformationException({
-        detail: "granted must be true",
-      }),
-    );
-  }
-  for (const field of [
-    "grantedAt",
-    "noticeLanguage",
-    "noticePrivacyPolicyUrl",
-  ] as const) {
-    if (!consent[field] || !consent[field].trim()) {
-      issues.push(
-        new InvalidConsentInformationException({
-          detail: `${field} must not be blank`,
-        }),
-      );
-    }
-  }
-  return issues;
-}
-
-function runKYCParamsValidation(
-  params: EnhancedKYCParams | BiometricKYCParams,
-): ValidationIssue[] {
-  const issues: ValidationIssue[] = [];
-
-  // Top-level required fields on the params object.
-  for (const field of ["idType", "idNumber", "country"] as const) {
-    const value = params[field];
-    if (!value || !value.trim()) {
-      issues.push(
-        new InvalidFieldValueException({
-          fieldName: field,
-          reason: "must not be blank",
-        }),
-      );
-    }
-  }
-
-  return issues;
-}
-
-/**
- * Validate a top-level `UserDetails` payload. Required fields use the
- * dotted path (`userDetails.givenNames`) so partner regex-matchers
- * keep working unchanged after the consolidation away from nesting
- * `userDetails` inside the KYC param shapes.
- *
- * Exposed via `b.validateUserDetails(payload)` so partners can
- * pre-flight a payload before assigning to `b.userDetails`, mirroring
- * the existing `b.validateConsent` / `b.validateEnhancedKYCParams`
- * pattern.
- */
-export function runUserDetailsValidation(
-  userDetails: UserDetails,
-): ValidationIssue[] {
-  const issues: ValidationIssue[] = [];
-  for (const field of ["givenNames", "lastName"] as const) {
-    const value = userDetails[field];
-    if (!value || !value.trim()) {
-      issues.push(
-        new InvalidFieldValueException({
-          fieldName: `userDetails.${field}`,
-          reason: "must not be blank",
-        }),
-      );
-    }
-  }
-  // At-least-one-of contact rule: email and phoneNumber are each
-  // optional, but the partner must supply one of them.
-  const hasEmail = !!userDetails.email && userDetails.email.trim().length > 0;
-  const hasPhone =
-    !!userDetails.phoneNumber && userDetails.phoneNumber.trim().length > 0;
-  if (!hasEmail && !hasPhone) {
-    issues.push(
-      new InvalidFieldValueException({
-        fieldName: "userDetails",
-        reason: "at least one of email or phoneNumber must be non blank",
-      }),
-    );
-  }
-  return issues;
-}
-
-/**
- * Find the first `error`-severity issue in a state. Returns
- * `undefined` for a valid state, or for a state whose only issues
- * are `warning`-severity (which never block `build()`).
- *
- * `build()` calls this to convert validator output into a thrown
- * `Error` (the issue itself, since every issue is also an exception
- * class). Partner regex on the message keeps working across the
- * refactor.
- */
-export function firstErrorIssue(
-  state: ValidationState,
-): ValidationIssue | undefined {
-  if (state.valid) return undefined;
-  return state.issues.find((i) => i.severity === IssueSeverity.error);
-}