[jessevanmuijden]

Fixes #77

A hard gate on issuance: the user's face must match the photo on the document's chip, not only the photo printed on it.

Why

FaceTec reports two face matches:

• matchLevel compares the live FaceMap with the photo printed on the document. The SPOCP rules check it (face-match-level >= 06).
• matchLevelNFCToFaceMap compares the live FaceMap with the photo on the chip (DG2). facetec-api ignored it.

The chip gates (#66, #64) prove the chip is genuine, and the printed-photo match proves the face matches the data page. Nothing tied the chip to the person in front of the camera, so a genuine document with a substituted printed photo passed every check. Its holder's name, birth date and chip portrait would be issued to someone else.

The gate

• Parsing: ExtractScanResult reads matchLevelNFCToFaceMap into IDScanResult.ChipFaceMatchLevel. It's a pointer, so "not reported" stays distinct from 0. A value of the wrong type is an error (fail closed), like the other result fields.
• The rule: a scan is refused with chip_photo_mismatch (new code) when the chip match is below facetec.min_chip_face_match_level, or when FaceTec reported none.
  • The setting is FACETEC_MIN_CHIP_FACE_MATCH_LEVEL, default 6, the same as the default face-match-level rule.
  • 0 selects the default, so the gate cannot be switched off; values outside 0–10 are refused at startup.
• Order: on /process-request it runs after the NFC and chip gates and before the expiry gate. The order is now liveness → NFC → chip → chip photo → expiry → SPOCP.
• Audit: the issuance record gains chip_face_match_level (-1 when not reported).

Legacy /v1/id-scan

The legacy path gets the same gate. It reads matchLevelNFCToFaceMap from FaceTec's legacy response if present. If that response does not carry it, every legacy issuance is now refused (fail closed). I think that's acceptable: the only legacy clients are the SDKs' FaceTec 9 delegates, which cannot run against FaceTec 10 (siros-sdk-kotlin#246). The apps use /process-request. Say so if the legacy path should be exempt instead.

Evidence

FaceTec Server 10.1.4 returns the field. In a recorded session on the dev stack it is 0 on the response before the chip read and 7 on the final response, after an authenticated read (nfcAuthenticationStatusEnumInt: 4).

Apps

chip_photo_mismatch is a new refusal code. Until the apps and SDKs below merge, clients show their generic "could not be verified" text.

• Apps: a specific message in all five languages, in Explain chip_photo_mismatch refusals wallet-android-wrapper#44 and Explain chip_photo_mismatch refusals wallet-ios-wrapper#22.
• SDKs: a typed error (ChipPhotoMismatch / chipPhotoMismatch, errorCode idv_chip_photo_mismatch), in feat(idv): typed error for chip_photo_mismatch siros-sdk-kotlin#255 and feat(idv): typed error for chip_photo_mismatch siros-sdk-swift#191.

The check itself stays server-side; the clients only explain the refusal.

Tests

• Parsing of matchLevelNFCToFaceMap: reported, reported as 0, absent, and a non-numeric value (an error).
• chipFaceRejection: not reported, below, at and above the minimum, a 0 level, the default minimum, and a stricter configured one.
• The photo-substitution case: printed match 9 with chip match 2 is refused before the policy.
• Gate behaviour: the default and a configured minimum, ordering after the NFC gate, and the legacy /v1/id-scan path.
• Config: default 6, and Validate bounds.
• Existing fixtures gained a passing chip match.
• Results: go vet is clean, and go test -race ./... passes, including tests/integration.

[codecov]

Codecov Report

❌ Patch coverage is 97.95918% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/apiv1/chip.go	92.30%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

🟡 Changes recommended

The gate accepts malformed score inputs and introduces an undocumented Info-level biometric score.

4 open findings

• Reject scores outside the documented 0–10 range · New
• Avoid exposing biometric match scores in Info logs · New
• Reject numeric strings for strict integer field validation · New
• Remove duplicate matchLevelNFCToFaceMap fixture member · New

What changed in this PR

Adds a hard issuance gate requiring the live face to match the authenticated chip portrait.

Changes:

• Parses and validates chip-face match scores across both issuance paths.
• Adds configuration, rejection codes, audit fields, documentation, and tests.
• Updates the indirect golang.org/x/net dependency.

File	Description
README.md	Documents the gate and configuration.
configs/​config.yaml	Adds the default threshold.
go.mod	Updates x/net.
go.sum	Updates dependency checksums.
internal/​apiv1/​chip.go	Implements gate and audit field.
internal/​apiv1/​chip_face_test.go	Tests gate behavior.
internal/​apiv1/​chip_test.go	Updates chip fixtures.
internal/​apiv1/​client.go	Applies gate to both issuance paths.
internal/​apiv1/​liveness_expiry_test.go	Updates expiry fixtures.
internal/​apiv1/​process_request_test.go	Updates NFC fixtures.
internal/​config/​config.go	Adds threshold configuration.
internal/​config/​config_test.go	Tests defaults and bounds.
internal/​facetec/​process_request.go	Extracts the chip-match score.
internal/​facetec/​process_request_test.go	Tests score extraction.
internal/​facetec/​types.go	Adds the score field.
internal/​idverrors/​errors.go	Adds the rejection code.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
95.7% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[s-jairl]

Looks good AFAICT!