GM.KYC.Identomat 1.0.0

GM.KYC

Know-your-customer verification for the GM.* ecosystem — document validity and liveness checks via Identomat, behind a provider-agnostic surface so a second vendor is a registration change, not a consumer change.

services.AddGMKyc(o => o.MaxImageDimension = 2000)
        .AddIdentomat(o => o.CompanyKeySecretName = "Identomat:CompanyKey")
        .AddKycPersistence(o => o.UseNpgsql(connectionString));

AddGMKyc() names no vendor; AddIdentomat() plugs one in. A second provider later is .AddXyz() — AddGMKyc never has to be renamed.

How it fits the ecosystem

The orchestrator does the cross-cutting work once, so the provider never re-implements it:

• GM.Documents.Images — every submitted document/liveness image is resized and EXIF/GPS-stripped before it leaves your service. (KYC-specific concerns like face-crop/quality scoring live here in KYC, not in the generic image package — this is the KYC domain layer over it.)
• GM.FileStorage — the normalized image is persisted via IFileStorageService (its key is recorded for correlation/audit) before submission.
• GM.Secrets — the Identomat companyKey and webhook secret come from ISecretsService, never appsettings or code.
• GM.Idempotency — Identomat callbacks are at-least-once; the webhook is deduped (by a hash of the exact body, so retransmissions drop while genuine status transitions still flow).
• GM.Audit — does not exist yet. Until it does, GM.KYC.Persistence owns the audit trail behind the thin IKycAuditStore seam, which is built to forward to GM.Audit rather than duplicate it.

The flow (Identomat is a hosted-widget vendor)

1. InitiateVerificationAsync → Identomat POST /begin → returns a session id and a widget URL. Redirect the applicant there; they complete capture and liveness in Identomat's widget.
2. SubmitDocumentAsync / SubmitLivenessCheckAsync → normalize + store the image, then attach it to the session (/upload-file) for flows that accept supplementary files.
3. GetVerificationStatusAsync → Identomat POST /result → mapped to a VerificationResult.
4. The webhook (IKycWebhookProcessor) verifies the signature, dedupes, fetches the authoritative result, and records it. Wire it to any endpoint (see the sample).

Status mapping

Identomat approved → Approved, rejected → Rejected (or RequiresResubmission for a configured recoverable reject_reason.value), in-progress → Pending. Liveness comes from Identomat's live / similarity fields.

⚠ Verify against your Identomat account

Built against Identomat's public API reference (external-api.identomat.com). A few things aren't fully specified there and are isolated + flagged so they're trivial to correct — all in IdentomatOptions or one class:

• Webhook signature scheme — the public reference doesn't document it. This assumes HMAC-SHA256 over the raw body with a secret from GM.Secrets (header X-Identomat-Signature). Confirm the exact algorithm/header and adjust IdentomatWebhookSignatureVerifier. (AllowUnsignedWebhooks exists for when verification is terminated upstream.)
• Document attach step/question keys — Identomat captures documents in the widget; the upload-file attach path needs your flow's stepKey/questionKey (IdentomatOptions.DocumentStepKey, …).
• reject_reason.value vocabulary — populate ResubmissionRejectCodes with the codes that mean "recoverable" for your config; everything else rejected is treated as final.
• document_type strings and the exact webhook body shape (session-id field name) — best-effort mappings, flagged in IdentomatStatusMapper / the webhook parser.

Tested

11 tests: the orchestrator (normalize + GPS-strip + store + delegate, over GM.Documents.Images and a GM.Testing.Fakes storage double), the Identomat provider and status mapping (via a stubbed HttpClient, companyKey sourced from a fake secrets service), and the webhook (HMAC verification + at-least-once dedup over a real in-memory GM.Idempotency). Runnable usage: GM.KYC.Samples.