Introduce Multipaz Pass file format.

The Multipaz `.mpzpass` file format provides a standardized, lightweight
mechanism for the exchange of low-assurance verifiable credentials.

In scenarios where strict cryptographic device-binding introduces unnecessary
friction — such as when a user expects their digital assets to seamlessly
synchronize across their entire ecosystem of devices — this format offers
a pragmatic, portable solution. It is engineered specifically for use cases
where the risk of credential sharing is negligible, such as event and movie
ticketing, transit passes, or generic membership cards.

This format explicitly trades anti-cloning guarantees for portability. Because
the credential data and any associated keys are stored in a highly portable
container, the credential can be trivially copied.

For high-value credentials where cloning or replay attacks are active threat
vectors (e.g., mobile driving licenses or financial instruments), this file
format is inherently unsuitable. In those high-assurance scenarios, issuers
must leverage a robust provisioning protocol like
[OpenID4VCI](https://github.com/openid/OpenID4VCI) to ensure secure delivery
and hardware-backed device-binding at the time of issuance.

This PR has three main components

- Defintion of the format with example files, in the `mpzpass` directory
- Support routines and import/export in the core Multipaz library
- Support in TestApp for generating and importing `.mpzpass` files

Additionally, extend `SimplePresentmentSource` to support more than
one domain for a given credential type. This is needed because if
using this to import a credential with a software-backed key and the
app already has a domain for with and without user authentication (and
the domain is picked according to a setting of whether user
authentication should be used), the software-backed credential (which
never has any user authentication) need to be consulted in both cases.

This PR also fixes problems with the compose TestApp on iOS and it
also makes Credential.replacementForDeleted() internal which it should
have been from the start.

Test: Unit test and manually tested on both Android and iOS.
Signed-off-by: David Zeuthen <zeuthen@google.com>

Author: davidz25

mpzpass/README.md

@@ -0,0 +1,114 @@
+# Multipaz Pass file format
+
+The Multipaz `.mpzpass` file format provides a standardized, lightweight mechanism
+for the exchange of low-assurance verifiable credentials.
+
+In scenarios where strict cryptographic device-binding introduces unnecessary
+friction — such as when a user expects their digital assets to seamlessly synchronize
+across their entire ecosystem of devices — this format offers a pragmatic, portable
+solution. It is engineered specifically for use cases where the risk of credential
+sharing is negligible, such as event and movie ticketing, transit passes, or generic
+membership cards.
+
+## Security Boundary and Anti-Cloning
+
+This format explicitly trades anti-cloning guarantees for portability. Because the
+credential data and any associated keys are stored in a highly portable container,
+the credential can be trivially copied.
+
+For high-value credentials where cloning or replay attacks are active threat
+vectors (e.g., mobile driving licenses or financial instruments), this file format
+is inherently unsuitable. In those high-assurance scenarios, issuers must leverage
+a robust provisioning protocol like [OpenID4VCI](https://github.com/openid/OpenID4VCI) to ensure secure delivery and
+hardware-backed device-binding at the time of issuance.
+
+## Data format
+
+The data is encoded in [CBOR](https://datatracker.ietf.org/doc/html/rfc8949) conforming to the following [CDDL](https://datatracker.ietf.org/doc/html/rfc8610):
+
+```cddl
+; Top-level container.
+;
+MpzPass = [
+  "MpzPass",
+  CompressedCredentialDataBytes,
+]
+
+; Contains CredentialDataBytes compressed using DEFLATE algorithm according
+; to [RFC 1951](https://www.ietf.org/rfc/rfc1951.txt).
+;
+CompressedCredentialDataBytes = bstr
+
+CredentialDataBytes = bstr .cbor CredentialData
+
+CredentialData = {
+  "display": Display,
+  "credential": Credential,
+}
+
+; Display data.
+;
+Display = {
+  ? "name": tstr,         ; Display name, e.g. "Erika's Driving License"
+  ? "typeName" : tstr     ; Credential type, e.g. "Utopia Driving License"
+  ? "cardArt" bstr,       ; PNG or JPEG with aspect ratio of 1.586 (cf. ID-1 from ISO/IEC 7810)
+}
+
+; The data for the credential.
+;
+; At least one of the credential formats must be present. If both credential formats
+; are present they must include identical data.
+;
+; To protect the holder's privacy and prevent RP collusion, multiple credentials may be
+; included for a single format, allowing the wallet to rotate between credentials and/or
+; implement policy decisions such as single-use. If multiple credentials are included,
+; they must all include the same data except for key material and slight variances in
+; the validity period necessary to avoid RPs being able to correlate credentials from the
+; same batch.
+;
+Credential = {
+  ? "isoMdoc": [+ IsoMdocCredential],
+  ? "sdJwtVc": [+ SdJwtVcCredential],
+}
+
+SdJwtVcCredential = {
+  ; The verifiable credential type.
+  ;
+  vct: tstr,
+  
+  ; The private key for the key-binding JWT, if used.
+  ;
+  ? "deviceKeyPrivate": COSE_Key,
+
+  ; The compact serialization of the SD-JWT VC, according to RFC 9901.
+  ;
+  "compactSerialization": tstr,
+}
+
+IsoMdocCredential = {
+  ; The document type.
+  ;
+  "docType": tstr,
+
+  ; The private key corresponding to DeviceKey in `issuerSigned`.
+  ;
+  "deviceKeyPrivate": COSE_Key,
+
+  ; IssuerSigned according to ISO/IEC 18013-5:2021 clause 8.3.2.1.2.2
+  ;
+  "issuerSigned": IssuerSigned,
+}
+```
+
+## MIME Type and file extension
+
+The MIME type `application/vnd.multipaz.mpzpass` shall be used for data containing credentials
+encoded in this format and the file extension `.mpzpass` shall be used for files containing
+credentials encoded in this format.
+
+## Examples files
+
+- [Driving license ISO mdoc](https://apps.multipaz.org/mpzpass/mDL.mpzpass)
+- [EU PID SD-JWT VC](https://apps.multipaz.org/mpzpass/EuPidSdJwt.mpzpass)
+- [Utopia Movie ticket SD-JWT VC w/o key-binding key](https://apps.multipaz.org/mpzpass/MovieTicketSdJwtKeyless.mpzpass)
+

multipaz-dcapi/src/commonTest/kotlin/org/multipaz/presentment/DocumentStoreTestHarness.kt

@@ -142,10 +142,10 @@ class DocumentStoreTestHarness {
             documentTypeRepository = documentTypeRepository,
             showConsentPromptFn = ::promptModelSilentConsent,
             preferSignatureToKeyAgreement = true,
-            domainMdocSignature = "mdoc",
-            domainMdocKeyAgreement = "mdoc_key_agreement",
-            domainKeylessSdJwt = "sdjwt_keyless",
-            domainKeyBoundSdJwt = "sdjwt"
+            domainsMdocSignature = listOf("mdoc"),
+            domainsMdocKeyAgreement = listOf("mdoc_key_agreement"),
+            domainsKeylessSdJwt = listOf("sdjwt_keyless"),
+            domainsKeyBoundSdJwt = listOf("sdjwt")
         )
 
         val now = Clock.System.now().truncateToWholeSeconds()

multipaz/src/commonMain/kotlin/org/multipaz/credential/Credential.kt

@@ -31,8 +31,12 @@ import kotlinx.coroutines.sync.withLock
 import kotlin.time.Instant
 import kotlinx.io.bytestring.ByteString
 import org.multipaz.cbor.buildCborMap
+import org.multipaz.mpzpass.MpzPass
+import org.multipaz.securearea.KeyUnlockData
+import org.multipaz.securearea.software.SoftwareSecureArea
 import org.multipaz.tags.Tags
 import kotlin.concurrent.Volatile
+import kotlin.coroutines.cancellation.CancellationException
 
 /**
  * Base class for credentials.
@@ -326,7 +330,7 @@ abstract class Credential {
 
     // Deleted identifier for which this one is a replacement
     // Called by Document.deleteCredential()
-    suspend fun replacementForDeleted() {
+    internal suspend fun replacementForDeleted() {
         lock.withLock {
             replacementForIdentifier = null
             save()
@@ -341,6 +345,22 @@ abstract class Credential {
      */
     open fun addSerializedData(builder: MapBuilder<CborBuilder>) {}
 
+    /**
+     * Exports the credential as a [MpzPass] which can be shared with other applications.
+     *
+     * Note: If the credential is using key-binding, it must be backed by a [SoftwareSecureArea] in order
+     * for this to work.
+     *
+     * @param keyUnlockData Optional unlock data required to read the underlying private key, if applicable.
+     * @return The generated [MpzPass].
+     * @throws IllegalStateException if the credential does not use a SoftwareSecureArea or if the credential
+     * doesn't support being exported.
+     */
+    @Throws(IllegalStateException::class, CancellationException::class)
+    open suspend fun exportToMpzPass(keyUnlockData: KeyUnlockData? = null): MpzPass {
+        throw IllegalStateException("This credential does not support export")
+    }
+
     /**
      * Serializes the credential.
      *

multipaz/src/commonMain/kotlin/org/multipaz/document/DocumentStore.kt

@@ -27,12 +27,21 @@ import kotlinx.coroutines.flow.asSharedFlow
 import kotlinx.coroutines.sync.Mutex
 import kotlinx.coroutines.sync.withLock
 import kotlinx.io.bytestring.ByteString
+import kotlinx.io.bytestring.encodeToByteString
 import org.multipaz.cbor.Cbor
+import org.multipaz.cbor.buildCborMap
 import org.multipaz.credential.Credential
 import org.multipaz.credential.CredentialLoaderBuilder
+import org.multipaz.mdoc.credential.MdocCredential
+import org.multipaz.mpzpass.MpzPass
 import org.multipaz.provisioning.Provisioning
+import org.multipaz.sdjwt.credential.KeyBoundSdJwtVcCredential
+import org.multipaz.sdjwt.credential.KeylessSdJwtVcCredential
+import org.multipaz.securearea.software.SoftwareCreateKeySettings
+import org.multipaz.securearea.software.SoftwareSecureArea
 import org.multipaz.storage.NoRecordStorageException
 import org.multipaz.tags.Tags
+import kotlin.coroutines.cancellation.CancellationException
 import kotlin.time.Clock
 import kotlin.time.Instant
 
@@ -262,6 +271,112 @@ class DocumentStore private constructor(
         return storage.getTable(documentTableSpec)
     }
 
+    /**
+     * Imports an [MpzPass] into a [DocumentStore].
+     *
+     * Reconstructs the [Document] and internal credential objects (either ISO mDoc, SD-JWT VC, or both)
+     * using the extracted data and keys in the passed-in [mpzPass] for credentials.
+     *
+     * The returned document will have the [Document.provisioned] flag set to `true`.
+     *
+     * @param mpzPass The []MpzPass] to import.
+     * @param isoMdocDomain The domain string to use when creating ISO mdoc credentials.
+     * @param sdJwtVcDomain The domain string to use when creating SD-JWT VC credentials.
+     * @param keylessSdJwtVcDomain the domain string to use when creating keyless SD-JWT VC credentials.
+     * @return The newly created [Document] containing the provisioned credentials.
+     * @throws IllegalStateException if a SoftwareSecureArea implementation cannot be found in the repository.
+     * @throws ImportMpzPassException if credential creation or certification fails.
+     */
+    @Throws(IllegalStateException::class, ImportMpzPassException::class, CancellationException::class)
+    suspend fun importMpzPass(
+        mpzPass: MpzPass,
+        isoMdocDomain: String = "mdoc",
+        sdJwtVcDomain: String = "sdjwtvc",
+        keylessSdJwtVcDomain: String = "sdjwtvc_keyless"
+    ): Document {
+        val softwareSecureArea = secureAreaRepository.getImplementation(SoftwareSecureArea.IDENTIFIER)
+            ?: throw IllegalStateException(
+                "No SoftwareSecureArea implementation found"
+            )
+
+        val document = try {
+            createDocument(
+                displayName = mpzPass.name,
+                typeDisplayName = mpzPass.typeName,
+                cardArt = mpzPass.cardArt,
+            )
+        } catch (e: Exception) {
+            if (e is CancellationException) throw e
+            throw ImportMpzPassException("Failed to create document", e)
+        }
+
+        try {
+            mpzPass.isoMdoc.forEach { isoMdoc ->
+                val importedKeyInfo = softwareSecureArea.createKey(
+                    alias = null,
+                    createKeySettings = SoftwareCreateKeySettings.Builder()
+                        .setPrivateKey(isoMdoc.deviceKeyPrivate)
+                        .build()
+                )
+                val credential = MdocCredential.createForExistingAlias(
+                    document = document,
+                    asReplacementForIdentifier = null,
+                    domain = isoMdocDomain,
+                    secureArea = softwareSecureArea,
+                    docType = isoMdoc.docType,
+                    existingKeyAlias = importedKeyInfo.alias,
+                )
+                credential.certify(
+                    issuerProvidedAuthenticationData = ByteString(
+                        Cbor.encode(buildCborMap {
+                            put("nameSpaces", isoMdoc.issuerNamespaces.toDataItem())
+                            put("issuerAuth", isoMdoc.issuerAuth.toDataItem())
+                        })
+                    )
+                )
+            }
+
+            mpzPass.sdJwtVc.forEach { sdJwtVc ->
+                val credential = if (sdJwtVc.deviceKeyPrivate != null) {
+                    val importedKeyInfo = softwareSecureArea.createKey(
+                        alias = null,
+                        createKeySettings = SoftwareCreateKeySettings.Builder()
+                            .setPrivateKey(sdJwtVc.deviceKeyPrivate)
+                            .build()
+                    )
+                    KeyBoundSdJwtVcCredential.createForExistingAlias(
+                        document = document,
+                        asReplacementForIdentifier = null,
+                        domain = sdJwtVcDomain,
+                        secureArea = softwareSecureArea,
+                        vct = sdJwtVc.vct,
+                        existingKeyAlias = importedKeyInfo.alias,
+                    )
+                } else {
+                    KeylessSdJwtVcCredential.create(
+                        document = document,
+                        asReplacementForIdentifier = null,
+                        domain = keylessSdJwtVcDomain,
+                        vct = sdJwtVc.vct
+                    )
+                }
+
+                credential.certify(
+                    issuerProvidedAuthenticationData = sdJwtVc.compactSerialization.encodeToByteString()
+                )
+            }
+
+            document.edit {
+                provisioned = true
+            }
+            return document
+        } catch (e: Exception) {
+            deleteDocument(document.identifier)
+            if (e is CancellationException) throw e
+            throw ImportMpzPassException("Failed importing credentials", e)
+        }
+    }
+
     /**
      * A builder for DocumentStore.
      *

multipaz/src/commonMain/kotlin/org/multipaz/document/ImportMpzPassException.kt

@@ -0,0 +1,9 @@
+package org.multipaz.document
+
+/**
+ * Thrown when importing a [org.multipaz.mpzpass.MpzPass] into [DocumentStore] fails.
+ *
+ * @property message the message or `null`.
+ * @property cause the cause of `null`.
+ */
+class ImportMpzPassException(message: String? = null, cause: Throwable? = null) : Exception(message, cause)