iOS SDK

dependencies: [
    .package(url: "https://github.com/your-org/thirdfactor-obsidian.git", from: "1.0.0"),
],
targets: [
    .target(name: "YourApp", dependencies: [
        .product(name: "ThirdFactorKYC", package: "thirdfactor-obsidian"),
        // add only if you need native NFC chip reading:
        .product(name: "ThirdFactorKYCNFC", package: "thirdfactor-obsidian"),
    ]),
]

<key>NSCameraUsageDescription</key>
<string>We use the camera to verify your identity.</string>
<key>NSMicrophoneUsageDescription</key>
<string>We use the microphone during liveness checks.</string>

import ThirdFactorKYC

// sessionURL is the `url` your backend got from POST /v3/session/
func startKYC(sessionURL: URL) {
    Task {
        let result = await ThirdFactor.verify(from: self, url: sessionURL)
        if result.status == .approved { showSuccess() }   // then confirm server-side
    }
}

public static func verify(
    from presenter: UIViewController,
    url: URL,
    options: VerifyOptions = .init()
) async -> VerificationResult

var options = VerifyOptions(title: "Verify identity", autoClose: true)
let result = await ThirdFactor.verify(from: self, url: sessionURL, options: options)

public struct VerificationResult {
    let status: VerificationStatus   // .approved .declined .inReview .cancelled .error
    let sessionId: String?           // echoed from the flow when available
    let rawStatus: String?           // raw server status, e.g. "abandoned"
    let error: ThirdFactorError?     // set only when status == .error
}

var options = VerifyOptions()
options.onEvent = { event in print("event:", event) }   // ready/completed/error/close

let result = await ThirdFactor.verify(from: self, url: sessionURL, options: options)
switch result.status {
case .approved:  proceed()                              // confirm server-side first
case .declined:  showFailure()
case .inReview:  showPending()
case .cancelled: break
case .error:
    if result.error?.code == "expired" { reMintSession() }
    else { showError(result.error) }
}

<!-- YourApp.entitlements -->
<key>com.apple.developer.nfc.readersession.formats</key>
<array>
    <string>TAG</string>
</array>

<key>NFCReaderUsageDescription</key>
<string>We read your passport/ID chip to verify your identity.</string>

<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
    <string>A0000002471001</string>          <!-- eMRTD (ePassport) — REQUIRED -->
    <string>A00000045645444C2D3031</string>  <!-- (optional) some national eIDs -->
    <string>A0000002472001</string>          <!-- (optional) eID/CardAccess -->
</array>

import ThirdFactorKYC
import ThirdFactorKYCNFC

var options = VerifyOptions()
if #available(iOS 15, *) {
    options.nativeCommandHandler = ThirdFactorNFC.commandHandler()
}
let result = await ThirdFactor.verify(from: self, url: sessionURL, options: options)

import ThirdFactorKYCNFC

func scanPassport() async {
    let key = MRZKey(
        documentNumber: "L898902C3",   // from the MRZ
        dateOfBirth:    "740812",      // YYMMDD
        dateOfExpiry:   "120415"       // YYMMDD
    )
    // Default data groups: [.DG1, .DG2, .SOD].
    let result = await ThirdFactorNFC.read(mrzKey: key, dataGroups: [.DG1, .DG2, .SOD])

    if result.success, let data = result.data {
        let payload = data.asDictionary()  // ["sod_b64": …, "dg1_b64": …, "dg2_b64": …, "aa": …, "chipAuth": …]
        upload(payload)                    // POST to your backend for passive auth
    } else {
        // result.errorCode ∈ user_cancelled | tag_lost | wrong_key |
        //                     unsupported | nfc_disabled | timeout
        print("NFC failed:", result.errorCode ?? "", result.errorMessage ?? "")
    }
}

@available(iOS 15, *)
public enum ThirdFactorNFC {
    static func read(mrzKey: MRZKey,
                     dataGroups: [DataGroupId] = [.DG1, .DG2, .SOD]) async -> NfcReadResult
    static func commandHandler() -> NativeCommandHandler   // for the hosted flow
}

public struct MRZKey {
    init(rawKey: String)
    init(documentNumber: String, dateOfBirth: String, dateOfExpiry: String)  // dates YYMMDD
}

import SwiftUI
import ThirdFactorKYC
import ThirdFactorKYCNFC

struct KYCScreen: View {
    @State private var showKYC = false
    @State private var sessionURL: URL?
    @State private var statusText = "Not verified"

    var body: some View {
        VStack(spacing: 16) {
            Text(statusText)
            Button("Verify identity") {
                Task { await startVerification() }
            }
        }
        .thirdFactorVerification(
            isPresented: $showKYC,
            url: sessionURL ?? URL(string: "about:blank")!,
            options: makeOptions()
        ) { result in
            handle(result)
        }
    }

    /// Calls YOUR backend, which in turn calls POST /v3/session/ with your
    /// secret API key. Never call the Obsidian API directly from the app.
    func startVerification() async {
        guard let url = await fetchSessionURL() else { return }
        sessionURL = url
        showKYC = true
    }

    func fetchSessionURL() async -> URL? {
        var request = URLRequest(url: URL(string: "https://api.acme.com/kyc/session")!)
        request.httpMethod = "POST"
        guard let (data, _) = try? await URLSession.shared.data(for: request),
              let json = try? JSONSerialization.jsonObject(with: data) as? [String: String],
              let urlString = json["url"] else { return nil }
        return URL(string: urlString)
    }

    func makeOptions() -> VerifyOptions {
        var options = VerifyOptions(title: "Verify your identity", autoClose: true)
        if #available(iOS 15, *) {
            options.nativeCommandHandler = ThirdFactorNFC.commandHandler()
        }
        options.onEvent = { event in print("[kyc]", event) }
        return options
    }

    func handle(_ result: VerificationResult) {
        switch result.status {
        case .approved:
            statusText = "Approved (pending server confirmation)"
        case .declined:
            statusText = "Declined"
        case .inReview:
            statusText = "Under review"
        case .cancelled:
            statusText = "Cancelled"
        case .error:
            statusText = "Error: \(result.error?.code ?? "unknown")"
        }
    }
}