[WAL-1347] feat(mdoc): implement NFC proximity transport

[szijpeter]

Summary

Implements holder-side NFC engagement and device retrieval for WAL-1347, so the existing proximity session can use conventional ISO NFC handover/retrieval and an isolated provisional NFC Engagement v2 profile through the same wallet contract.

This PR is stacked on the complete WAL-1346 wallet integration and application-configurable reader-trust policy in walt-id/waltid-identity#2160. The implementation follows the architecture contract in walt-id/waltid-architecture#60. The stacked demo-host integration is in walt-id/waltid-identity#2166.

What Changed

Shared mdoc and transport protocol

• Adds exact conventional NFC NDEF, Connection Handover, Type 4 Tag/TNEP, ISO 7816 APDU, retrieval, transcript, status, termination, limits, and lifecycle state under shared KMP ownership.
• Adds a distinct provisional NFCv2 connection method, AID, CBOR handover, same-channel/hybrid transport, and session-message sequence profile without enabling the unresolved DIS 9.2.3 TNEP placeholder capability.
• Keeps engagement selection, first-connection ownership, session handover, response processing, and cleanup in the common proximity engine.

Platform integration

• Adds an Android HCE adapter and generation-bound APDU service registry with validated AIDs, foreground routing, field-loss handling, bounded asynchronous response ownership, and deterministic cleanup.
• Adds a Swift-owned Core NFC CardSession bridge for native and Compose hosts. Public Core NFC support and eligibility remain runtime-gated. Presentment-intent assertion acquisition is best-effort and does not block an eligible CardSession; the assertion is released on every finish path.
• Completes the new public NFC-remediation action across every existing Compose and Swift demo consumer, while leaving actual NFC host registration and callback wiring to the stacked child PR.

Wallet SDK

• Exposes precise conventional and provisional-NFCv2 retrieval configurations through sealed Kotlin variants and Swift-native value types, avoiding illegal combinations such as QR plus NFCv2 retrieval.
• Extends capability preparation, session lifecycle, Kotlin ABI, Swift facade, DocC parameter coverage, and regression coverage without leaking platform or implementation-detail types.

Architecture Notes

• The implementation is walt-owned. No external wallet-stack artifact or source enters the runtime, dependency graph, public ABI, or platform facade.
• Shared code owns protocol bytes, APDU/handover state, races, sequence semantics, and errors. Android and Apple adapters own only OS service/session callbacks and byte delivery.
• The literal handoverSessionEstablishment capability remains unadvertised until the unresolved DIS placeholder can be reconciled with authoritative material.
• The provisional NFCv2 profile emits direction-local, monotonic seq values. Structurally valid inbound values are non-enforcing in this provisional profile; malformed values and any seq on conventional sessions fail closed.

Caveats and Follow-Ups

• Conventional Android Negotiated Handover through NFC to a reader-selected BLE bearer completed end to end against an external identity reader on a frozen earlier ancestry. A later QR-to-NFC hybrid canary also passed on frozen [WAL-1348] feat(mdoc): implement Wi-Fi Aware retrieval #2168 head ae4efeb2dfaf60fa7daaab80db4415c4a63c57b0; neither result is cross-credited to the rewritten head, so exact-head physical qualification remains open.
• The official ISO/IEC TS 18013-6:2025 Appendix 2 holder catalogue now provides conventional NFC technology cases mDL_Tech_DE_NFC_01 through _17 and mDL_Tech_DR_NFC_01 through _07. They are mapped into the qualification plan in architecture PR #61; the normative TS main text is still required before any conformance claim.
• NFCv2 remains provisional because the published appendices do not define the NFCv2 AID, Action Point 112.05 behavior, or handoverSessionEstablishment. Bounded Android direct and NFCv2-to-BLE hybrid interoperability, early field-loss handling, fresh-session recovery, and a 42,507-byte single-APDU response remain exact-build evidence rather than standards qualification.
• Apple has approved HCE access for the Compose and native wallet host bundle identifiers and the requested AID prefixes. Child PR [WAL-1347] feat(wallet): integrate NFC proximity in demos #2166 contains the matching host entitlements, and a native SwiftUI development build carrying that capability completed the bounded physical conventional NFC-to-BLE exchange recorded in architecture PR #61. Compose iOS HCE, direct NFC retrieval, provisional NFCv2 variants, refreshed distribution signing, release-build entitlement inspection, and the broader Appendix 2 matrix remain open.

Breaking

• The unreleased mobile SDK proximity retrieval configuration is tightened into conventional and provisional-NFCv2 variants. No compatibility shim or migration is provided because the mobile SDK is not published.

[linear-code]

WAL-1347

WAL-1346

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: 1359934e-afcf-418b-88d0-6e06651ce03e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sonarqubecloud]

❌ The last analysis has failed.

See analysis details on SonarQube Cloud