[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#254 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.91667% with 1 line in your changes missing coverage. Please review.

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

📢 Thoughts on this report? Let us know!

[jessevanmuijden]

Superseded by #80: the same commits, opened from a branch in this repo so the SonarCloud scan gets its token (fork PRs never do). Nothing else changed.