[WAL-1344] feat(mdoc): add shared proximity protocol engine

[szijpeter]

Summary

This adds the radio-independent Kotlin Multiplatform protocol foundation for ISO mdoc proximity presentation, covering the shared models, session engine, matching, authentication, trust seams, and response construction defined by WAL-1344.

The WAL-1344 commits are based directly on current main, including the holder-key foundation merged through walt-id/waltid-identity#2154. This PR is the root of the remaining WAL-1335 stack; each child targets its immediate predecessor. Proximity QR rendering is owned later by demo PR #2160, with no independent WAL-1376 dependency.

Architecture contract: walt-id/waltid-architecture#60.

What Changed

Protocol models

• Completes DeviceEngagement, retrieval-method, session-message, status/termination, extended-request, encrypted-response, ZKP, and edition-2 use-case structures.
• Preserves tagged embedded CBOR and RFU/extension fields at the structures where exact bytes are security-relevant.
• Corrects typed mDL age identifiers and CBOR representations, including native Boolean age attestations and binary biometric templates with base64url text round-trips.
• Represents device authentication as a sealed Signature/Mac hierarchy, so both-or-neither combinations cannot be constructed.
• Tightens DeviceRequest and DeviceResponse invariants, version handling, and document-authentication boundaries.
• Keeps 2021 and edition-2/DIS interoperability profiles explicit, deriving DeviceEngagement 1.0/1.1 from the capability fields selected for the session rather than from the profile label alone.

Shared holder engine

• Adds cipher-suite 1 ECDH/XDH, HKDF-SHA-256, directional AES-GCM counters, replay rejection, limits, timeouts, repeated exchanges, and deterministic cleanup.
• Publishes truthful engagement, connection, repeated-request, and termination phases instead of requiring higher layers to infer them.
• Adds deterministic multi-document matching, alternatives, issuer constraints, wallet-retained presentation choices, use cases, response-size enforcement, selective disclosure, device signature/MAC, and HPKE document-response encryption.
• Resolves requested age_over_NN statements to the nearest sufficient attestation and omits disclosure when the credential cannot prove the requested result.
• Separates reader-signature validity from trust/path/revocation policy, preserving whole-request and per-document reader-authentication context with ReaderAuthAll, RICAL, and ZKP provider seams.
• Enforces Android certificate constraints in the shared trust path instead of accepting platform-parser output as sufficient validation.
• Carries wallet-validated, display-safe application-profile authorization details, eligible credential choices, and an opaque result-binding digest through preview, consent, and submission without interpreting ecosystem-specific extensions.
• Produces the exact encoded device-key bytes once for both Device Engagement and transport configuration.

Transport and test boundaries

• Defines a small opaque-message transport SPI plus fake/loopback implementations; Android and Apple radio APIs do not enter the protocol module.
• Exercises the common engine on JVM and JS, including signed and MAC exchanges, malformed CBOR, replay, stale consent, oversize input, trust failures, cancellation, observable phase order, and resource cleanup.
• Covers production response construction across QR, NFC static-handover, and NFC negotiated-handover transcripts for both DeviceSignature and DeviceMAC, with independent authentication verification.

Architecture Notes

• Parsing, cryptography, credential selection, consent binding, trust evidence, and disclosure stay in common KMP code. Platform work is limited to radio/lifecycle adapters.
• Exact request, transcript, and response bytes are immutable at trust and consent boundaries.
• Transport support and protocol features are represented as explicit implemented/profile/runtime/session capabilities; unsupported key specifications fail closed.
• The module uses focused walt-owned interfaces and existing crypto/CBOR building blocks rather than importing a full proximity stack.

Caveats and Follow-Ups

• BLE, NFC, and Wi-Fi Aware platform adapters remain in WAL-1345, WAL-1347, and WAL-1348.
• Wallet SDK integration is in walt-id/waltid-identity#2159, with all three demo journeys in walt-id/waltid-identity#2160. Device interoperability and release qualification remain in WAL-1349.
• Concrete ecosystem ZKP and RICAL providers plug into the shared seams; this PR does not select a broad-stack implementation dependency.

Breaking

• DeviceAuth is a sealed Signature/Mac hierarchy; callers construct and pattern-match one variant instead of nullable signature/MAC fields.
• DeviceResponse document collections use non-empty List values when present.
• Legacy waltid-crypto mdoc device-authentication overloads are removed; the shared path uses crypto2 keys and explicit algorithm policy.

[linear-code]

WAL-1344

[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: c1e5f66b-a1d5-41eb-8464-90521ef038a3

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]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud