./vckiostest is a test app. to run:
- Build an xcframework from this root:
./gradlew assembleVck-iosDebugXCFramework - The debug framework is LINKED from the vckiostest XCode app, no no copying
- Build and run iOS app on simulator or physical device (issuance needs a physical device:
BasicWalletgets a Wallet Instance Attestation and key attestations fromwallet-provider.a-sit.plusvia App Attest, as Valera does, so the wallet provider must accept the app's App ID) - Enjoy
The Swift adapter is bundled into the framework by SKIE; external default-argument overload generation stays disabled.
import vck_ios
let keyMaterial = OpenId4VciClientDefaults.keyMaterial
let wallet = OpenId4VciClientAdapter(
clientId: "https://wallet.example",
proofCreators: [JwtProofCreator(keyMaterial: keyMaterial)] // first one the issuer accepts is used
)
let details = wallet.buildAuthorizationDetails(credentialConfigurationId: "pid")
let clock = ClockAdapter.system // Kotlin Clock.System
let metadata = try VckSerializer.shared.joseDeserializeIssuerMetadata(jsonData)
let json = try VckSerializer.shared.joseSerializeIssuerMetadata(metadata)
let tokenResponse = TokenResponseParameters(accessToken: "token", tokenType: "Bearer")
// One request per credential, each with a fresh c_nonce from the issuer's nonce endpoint:
for prepared in try wallet.prepareCredentialRequests(
tokenResponse: tokenResponse, metadata: metadata, credentialFormats: [credentialFormat]
) {
let request = try await wallet.createCredential(request: prepared, metadata: metadata, clientNonce: freshNonce())
}
// Without credential_identifiers in the token response, also without it:
let single = try await wallet.createCredential(metadata: metadata, credentialConfigurationId: "pid")
// Or all requests with one nonce, as before:
let requests = try await wallet.createCredential(
tokenResponse: tokenResponse, metadata: metadata, credentialFormat: credentialFormat
)Use wallet.client for the remaining OpenId4VciClient API (VC-K 9 renamed
WalletService; the old adapter names remain as deprecated aliases). Optional constructor arguments (including the proof clock) and
createCredential's nonce, scope, and client ID can all be overridden. Pass
proofCreators: (e.g. JwtProofCreator, AttestationProofCreator) to choose the proofs; the
initializer taking keyMaterial: and loadKeyAttestation: is deprecated, like VC-K's. Since VC-K 9, createCredential only
requests the given credentialFormat, even if the token's scope grants more.
OpenId4VciClientDefaults and ClockAdapter expose Swift static accessors.
Default key material and encryption services are fresh
instances on each access.
Swift closures can implement Kotlin suspend callbacks without handwritten protocol conformance:
let retriever = SwiftSuspendFunction1 { (input: RemoteResourceRetrieverInput) -> String? in
guard let url = URL(string: input.url) else { throw URLError(.badURL) }
let (data, _) = try await URLSession.shared.data(from: url)
return String(data: data, encoding: .utf8)
}
let wallet = OpenId4VciClientAdapter(remoteResourceRetriever: retriever, proofCreators: proofCreators)
let response = try await retriever(input) // safe callable syntax, not the raw invoke export
let kotlinBytes = try Data([0, 128, 255]).kotlinByteArray
let swiftBytes = kotlinBytes.bytes // or kotlinBytes.data
let value = try kotlinValue(result) // safe, typed KmmResult unwrappingSwiftSuspendFunction0, SwiftSuspendFunction1, and SwiftSuspendFunction2 accept
async throws closures. Specify the actual Kotlin parameter and return types;
primitive nullable parameters may arrive as Kotlin number wrappers. Ordinary
non-suspending Kotlin lambdas already export as Swift closures and need no shim.
Conversions copy byte buffers, preserving unsigned Swift byte values.
The retrieval example handles GET responses; implement POST and header handling
when required by the issuer's flow.
loadKeyAttestation must return a KmmResult containing a typed compact JWS, not
a String or KmmResult<NSString>. Parse the compact attestationProof string in Kotlin:
let loadAttestation = SwiftSuspendFunction1 { (input: OpenId4VciClient.KeyAttestationInput) in
let attestationProof: String = try await fetchAttestationProof(input)
return KmmResult(value: try VckSerializer.shared.joseDeserializeKeyAttestationJwt(attestationProof))
}
let wallet = OpenId4VciClientAdapter(proofCreators: [
JwtProofCreator(keyMaterial: keyMaterial, loadKeyAttestation: loadAttestation),
AttestationProofCreator(loadKeyAttestation: loadAttestation),
])The throwing helper returns JwsTyped<JwsCompact, KeyAttestationJwt>; Kotlin's
JwsCompactTyped typealias is exported as JwsTyped. Invalid compact JWS or payload
data throws a Swift error. Wrap the parsed value in KmmResult for the callback.
Parsing does not verify the attestation's signature.
Use callable syntax (try await callback(argument)) when invoking callbacks from
Swift. It routes through a Kotlin export annotated with @Throws(Throwable::class).
The raw invoke export only allows Kotlin CancellationException; other Swift
errors become ObjCErrorException and can abort the process. Similarly, use
try kotlinValue(result) rather than an unannotated getOrThrow() across the Swift boundary.
The adapters preserve thrown Swift CancellationError as Kotlin cancellation, but
Kotlin cancelling a coroutine does not cancel an already-running Swift closure.
SKIE documents this limitation
for Swift implementations of suspend interfaces.
Keep side effects in callbacks aware of the lifetime of the operation.
Run the saved simulator checks with a booted ARM64 iOS simulator:
zsh checks/interop.sh
# These modes intentionally reproduce process-aborting error exports:
zsh checks/interop.sh booted --raw-error
zsh checks/interop.sh booted --raw-store-error
zsh checks/interop.sh booted --raw-store-cancellation
zsh checks/interop.sh booted --raw-result-errorThe store reproducer uses a minimal Swift SubjectCredentialStore implementation;
it does not reproduce any historical app crash without its stack trace.
Swift stores can implement SwiftCredentialStore with ordinary getCredentials
and storeCredential method names and Swift arrays. Pass the thin adapter to Kotlin:
let store = SubjectCredentialStoreAdapter(SwiftSubjectCredentialStore())
let wallet = BasicWallet(keyMaterial: keyMaterial, subjectCredentialStore: store)The adapter contains the __ protocol requirements, reports read failures as
KmmResult failures, and converts thrown Swift cancellation to Kotlin cancellation.
Write failures still require a Kotlin caller that catches them or exports them
with @Throws; the raw upstream storeCredential export allows only cancellation.
OpenID4VP protocol clients return HTTP exchanges for any HTTP stack. Run them with
URLSession (redirects are not followed, as in VC-K's ktor clients):
let client = OpenId4VpProtocolClient(openId4VpHolder: builder.build())
let state = try await client.prepareAuthorizationResponse(input: requestUrl)
.run(as: AuthorizationResponsePreparationState.self)
// ... finalizeAuthorizationResponse on the holder, then for direct_post:
let redirectUri = try await client.sendAuthorizationResponse(response: post).run(as: String?.self)OID4VCI runs the same way with OpenId4VciProtocolClient, which handles the token request, DPoP and the
credential request. Build one per issuance flow, and keep it until the credential is received, as it holds the
flow's PKCE, DPoP and attestation state. protocolClient uses the adapter's clientId for the OAuth 2.0 client and
the proofs:
let wallet = OpenId4VciClientAdapter(clientId: "https://wallet.example", proofCreators: proofCreators)
let vci = wallet.protocolClient(redirectUrl: "wallet://callback", clientAttestation: clientAttestation)
let metadata = try await vci.loadIssuerMetadata(credentialIssuer: issuer).run(as: IssuerMetadata.self)To configure the parts yourself, use OAuth2Client.create, OAuth2ProtocolClient.create,
IssuerMetadataValidator.create (which takes seconds, see below) and OpenId4VciProtocolClient.create.
Errors from the issuer or authorization server are OAuth2Exceptions. Get one from a thrown Swift error with
error.oauth2Exception (also when it is the cause of another Kotlin exception, see error.kotlinThrowable), and
read its error and errorDescription, not the description_ that SKIE renames each subclass's description to:
do {
let received = try await vci.credentialRequest(
request: request, issuerMetadata: metadata, tokenResponse: token, credentialFormat: format
).run(as: [ReceivedCredential].self)
} catch let error where error.oauth2Exception is OAuth2Exception.InvalidNonce {
// Fetch a fresh c_nonce and create the request again.
}To decode a credential response received some other way, use wallet.decodeCredentialResponse(...), which
replaces the deprecated parseCredentialResponse and validates nothing: prepare the storage of each
ReceivedCredential with prepareCredentialStorage, which validates it.
Validation takes a ValidationPolicy, which has no default in VC-K 9. Kotlin's
Duration reaches Swift as raw Int64 bits, so build policies and validators with
the factories, which take seconds and supply Kotlin's defaults (pass signatureCheck, clock,
requiredClaimsResolver or zlibService to replace them):
let policy = try ValidationPolicy.create(
trust: TrustPolicyIntegrityOnly.shared, status: StatusPolicySkip.shared,
timeLeeway: 300, requireTimeliness: true
)
builder.relyingPartyValidator = try RelyingPartyValidator.create(trust: .create(accessCertificates: anchors))
holderBuilder.credentialValidator = CredentialValidator.create(trustAnchors: issuerAnchors)A Swift SwiftCredentialStore implements getCredentials and storeCredential(entry:);
persist entries with VckSerializer.shared.joseSerializeStoreEntry(_:). VckSerializer
also (de)serializes ProvisioningContext and AuthorizationResponsePreparationState
(to resume flows after the app was killed), TokenResponseParameters,
OAuth2AuthorizationServerMetadata, and JsonWebKey (instead of the deprecated
serialize()).