open-standards/openpay/docs/08-ffi-swift-progress.md

Phase 8 — op-ffi-swift Complete (Swift / iOS / macOS bridge)

Status: Draft v0.8 Date: 2026-05-17

What shipped

op-ffi-swift: the bridge that exposes the OpenPay Rust core to Swift / iOS / macOS callers. Dual surface:

1. swift-bridge 0.1.59 — idiomatic Swift API generated from a single #[swift_bridge::bridge] declaration. Default build path.
2. Plain C ABI — extern "C" functions with raw-pointer ownership. Fallback for consumers that don't want swift-bridge-build in their Xcode workflow; they hand-roll Swift wrappers via @_silgen_name.

Why two surfaces

The compact summary distilled this from this turn's reasoning: swift-bridge is purpose-built for Rust↔Swift and generates idiomatic Swift directly, but adds a swift-bridge-build build dependency that some teams will not accept (especially in monorepos with strict build-tool policies). The plain C ABI is universally consumable — Objective-C, Swift via @_silgen_name, C, even AppleScript via Foundation's C bridge. Shipping both costs ~600 LOC and gives every consumer a path.

Why no card / A2A rails

Card and A2A rail crates are heavy on transport dependencies (ureq, rustls, OAuth, mTLS). Most iOS apps don't submit payments directly — they hand a tokenized credential to a PSP SDK (Stripe, Adyen, Braintree) that handles the wire protocol. The Swift bridge therefore exposes vault + fraud + token handoff, not the rail drivers. Apps that need direct rail submission link the rail crates at the workspace level and bridge them via a custom extension.

This is the standard architectural pattern in the iOS payment ecosystem: the merchant app touches a tokenized credential only.

Verified ground truth

Claim	Source
swift-bridge 0.1.59 is latest stable	docs.rs/crate/swift-bridge May 2026
Inspired by cxx-rs; emits idiomatic Swift directly	chinedufn/swift-bridge README
Supports Option<OpaqueRust>, Result, async, opaque types	swift-bridge release notes
Target triples: aarch64-apple-ios, aarch64-apple-ios-sim, x86_64-apple-ios (all tier-2)	rustc book platform-support/apple-ios
Simulator distinction via -sim suffix encoded into LC_BUILD_VERSION	rustc book; Apple Developer Forums thread 678075
xcodebuild -create-xcframework is the canonical packaging command	Apple Developer Forums thread 673387
Lipo simulator arches into a fat lib before xcodebuild	Apple Developer Forums; rhonabwy.com 2023 XCFramework guide
iOS Keychain kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly is the correct class for background-accessible non-migrating tokens	Apple Developer Documentation

Crate layout

crates/op-ffi-swift/
├── Cargo.toml                          # crate-type=[staticlib, cdylib, rlib]
├── build.rs                            # invokes swift_bridge_build::parse_bridges
├── src/
│   ├── lib.rs                          # crate root, modules, attrs
│   ├── error.rs                        # FfiError #[repr(i32)] (11 tests)
│   ├── bridge.rs                       # swift-bridge module + impls (15 tests)
│   ├── c_api.rs                        # plain C ABI (13 tests)
│   └── tests.rs                        # cross-surface integration (5 tests)
├── scripts/
│   └── build-xcframework.sh            # full Apple toolchain workflow
└── swift/
    ├── Package.swift                   # SwiftPM manifest
    ├── README.md                       # consumer integration guide
    └── OpenPay/OpenPay.swift           # idiomatic Swift wrapper layer

The bridge surface

#[swift_bridge::bridge]
mod ffi {
    // Shared enums
    enum FraudDecisionFfi { Approve, Review, Decline, Freeze }
    enum TokenFormatFfi { Random, Deterministic }
    enum TokenLifetimeFfi { Reusable, SingleUse }

    // Shared struct (transparent both sides)
    struct TokenizationPolicyFfi {
        format: TokenFormatFfi,
        lifetime: TokenLifetimeFfi,
        ttl_seconds: u64,
    }

    extern "Rust" {
        // CardData
        type RustCardData;
        #[swift_bridge(associated_to = "RustCardData")]
        fn new(pan: &str, exp_month: u8, exp_year: u16) -> Option<RustCardData>;
        fn first_six(&self) -> String;
        fn last_four(&self) -> String;
        fn exp_month(&self) -> u8;
        fn exp_year(&self) -> u16;

        // VaultRef
        type RustVaultRef;
        fn as_string(&self) -> String;

        // Vault
        type RustVault;
        #[swift_bridge(associated_to = "RustVault")]
        fn ephemeral(name: &str) -> RustVault;
        fn tokenize(&self, card: RustCardData, policy: TokenizationPolicyFfi) -> Option<RustVaultRef>;
        fn detokenize(&self, token: &RustVaultRef) -> Option<RustCardData>;
        fn exists(&self, token: &RustVaultRef) -> bool;
        fn delete(&self, token: &RustVaultRef) -> bool;

        // Scorer
        type RustHeuristicScorer;
        #[swift_bridge(associated_to = "RustHeuristicScorer")]
        fn default() -> RustHeuristicScorer;
        fn name(&self) -> String;

        // Per-thread last-error slots
        fn last_error_vault(v: &RustVault) -> i32;
        fn last_error_card() -> i32;
    }
}

Wrapper types RustCardData, RustVaultRef, RustVault, RustHeuristicScorer wrap the underlying op-vault and op-fraud types. Method bodies live in plain Rust outside the macro. Errors populate thread-local slots that Swift reads via last_error_*.

Oracle discipline preserved at the FFI boundary

The FfiError enum collapses op_vault::Error::NotFound, AuthFailed, and InvalidToken into a single VaultLookupFailed discriminant — same rule as the vault layer, surfaced consistently to Swift. A Swift caller cannot probe to distinguish "this token exists with the wrong key" from "this token never existed." Tested in error.rs::vault_not_found_and_auth_failed_collapse_to_lookup_failed.

Thread-local last-error pattern

Each surface (bridge, C ABI) has its own thread_local! Cell of FfiError. A method that returns Option<T> / bool / null pointer on failure writes the discriminant to the thread-local before returning. Swift / C reads the slot via last_error_*() immediately after a failing call.

Why thread-locals rather than out-parameters: out-parameters would require Swift to allocate scratch space per call, which is awkward in the swift-bridge surface where Option<T> is the natural Swift idiom. The C ABI also benefits — Swift's @_silgen_name callers don't need to declare inout parameters.

Caveat: an iOS app that mixes UI work (main thread) and a worker thread for tokenization must be careful to read last_error_* on the same thread that made the failing call. This is a documented contract in the README.

C ABI ownership protocol

Documented at the module level in c_api.rs. Summary:

• op_*_new / op_*_create returns a *mut T allocated with Box::into_raw. Caller frees via op_*_free.
• op_*_free on null is a no-op.
• op_vault_tokenize consumes the OpCardData pointer (the card box is dropped on the Rust side, even on failure, to honor the ownership contract Swift expects from swift-bridge's API).
• Status-returning calls return i32: 0 = success, positive = data, -1 = error (read op_last_error).
• Pointer-returning calls return null on error.
• All strings are NUL-terminated UTF-8, freed via op_string_free.

Build flow

scripts/build-xcframework.sh produces target/OpenPay.xcframework:

1. cargo build --target {aarch64-apple-ios,aarch64-apple-ios-sim,x86_64-apple-ios,aarch64-apple-darwin,x86_64-apple-darwin} — five .a outputs.
2. lipo -create aarch64-apple-ios-sim.a x86_64-apple-ios.a -output sim-fat/.a — combine simulator arches.
3. lipo -create aarch64-apple-darwin.a x86_64-apple-darwin.a -output mac-fat/.a — combine macOS arches.
4. xcodebuild -create-xcframework -library aarch64-apple-ios.a -library sim-fat.a -library mac-fat.a -output OpenPay.xcframework.
5. Copy swift-bridge generated OpenPay.swift, openpay-swift-bridge.h, and module.modulemap into target/swift/ for SwiftPM consumption.

Verified workflow against the Apple Developer Forums threads on static library packaging (the canonical pattern is lipo simulator slices first, then xcodebuild -create-xcframework with one library per platform variant).

Test coverage

Module	Tests	Notes
error.rs	11	i32 round-trip, oracle collapse, message-non-leakage, all variants
bridge.rs	15	CardData construction (valid/invalid), vault round-trip, NotFound→VaultLookupFailed, malformed token collapse, policy decoding (single-use, ttl=0, deterministic), delete idempotency, exists, scorer name, thread-local isolation, success-clears-error
c_api.rs	13	Card lifecycle, invalid PAN, null PAN, vault round-trip, detokenize unknown, exists+delete, null pointer status returns, scorer lifecycle, string_free null, free null, tokenize null-card consumption, policy decode (single-use, unknown format)
tests.rs	5	Cross-surface coexistence, independent thread-local error slots, ephemeral vault on both surfaces, scorer name consistency, 100-iteration string-free loop
Phase 8 total	44
Cumulative Phases 1–8	391

Design decisions

1. Dual surface (swift-bridge primary, C ABI fallback)

Chose swift-bridge as the default because the deliverable is Swift, and idiomatic Swift output is what merchant teams actually want to read. cxx-rs would require an extra C++→Swift hop. Plain C ABI is parallel for consumers without swift-bridge-build, which costs ~250 extra LOC and gives universal compatibility.

2. Thread-local errors over Result types

swift-bridge does support Result<T, OpaqueErr> returns, but Swift would see them as throwing functions where the error type is an opaque Rust struct. We want Swift callers to see a Swift enum OpenPayError, not an opaque handle. Thread-local i32 codes + a Swift wrapper layer that converts to OpenPayError is the straightforward path.

3. No bridged Vault trait

We did NOT use extern "Swift" to let Swift code implement the Rust Vault trait. The pattern would enable a Swift KeychainVault that plugs into the Rust orchestrator. We considered it and deferred:

• iOS Keychain access is async at scale (background thread, biometric prompts) and bridging async-Swift to sync-Rust is fragile.
• The accessibility class, biometric policy, and access control flags are deployment decisions, not library decisions. We would have to expose a configuration surface that captures all of them, which is iOS-specific noise in a cross-platform crate.

The path forward (Phase 7.1+): ship a KeychainVault Swift class that implements its own Vault-like protocol entirely in Swift, with the Rust orchestrator calling into it via an extern "Swift" block. Defer until merchant feedback says it's the right factoring.

4. Pinned swift-bridge = "0.1"

The chinedufn/swift-bridge README explicitly notes that the MSSV policy is tight ("the short support window is disrupting projects"). We pin to the 0.1 series and treat minor upgrades as project events rather than dependabot-driven background updates.

5. unsafe_code at module level

lib.rs declares #![deny(unsafe_code)] at crate level. The c_api module annotates with #[allow(unsafe_code)] because raw-pointer FFI requires unsafe. The bridge module remains safe code — swift-bridge's macro generates the FFI code separately, outside of our crate's namespace. The unsafe footprint is small, audited, and concentrated.

Note: an earlier version used #![forbid(unsafe_code)] which cannot be relaxed at module level. Switched to deny for that reason.

Bugs caught during construction

1. forbid(unsafe_code) blocked the C ABI module. forbid is a hard limit that no inner #[allow] can override. Switched to deny + module-level #[allow].
2. Initial directory creation used a literal brace pattern. Bash without extglob interpreted {src,swift,scripts} as a directory name. Corrected.
3. op-core direct dep was unused. Pulled transitively through op-vault and op-fraud. Removed.
4. Bridge tests' last_error_card access was via crate::bridge. The pub fn last_error_card() lives at module scope in bridge.rs, not inside the mod ffi { ... } macro block. The integration tests reference it correctly.
5. Scorer trait import oscillated. First version called Scorer::name(&self.inner) requiring the trait import; second removed the trait import in favor of method-syntax; but HeuristicScorer has no inherent name method, so the trait must be in scope. Final: trait imported, called via self.inner.name().

What's NOT in this phase (explicitly deferred)

• KeychainVault Swift implementation. Belongs in consumer code or a follow-up phase (Phase 7.1+).
• Apple Pay PKPayment handling. Apple Pay payment tokens are network tokens, not PANs. They go to a PSP that resolves the cryptogram. Out of scope for OpenPay.
• Async APIs. swift-bridge supports async fn, but the OpenPay vault surface is synchronous by design (encryption is fast; the bottleneck is the rail driver which lives outside the FFI). We can add async wrappers in a future phase if merchant apps need them.
• Network token bridging. Visa VTS / Mastercard MDES. These are rail-driver concerns, not FFI concerns.
• Orchestrator bridging. The orchestrator type itself isn't exposed yet (no separate op-orchestrator crate exists). Phase 11 will add this.

Next: Phase 9 — op-ffi-jni (Kotlin / Android)

Same architectural shape as Phase 8 but using the jni crate to bridge to Kotlin/Java. The vault on Android maps to AndroidKeystore via EncryptedSharedPreferences + MasterKey (AndroidX Security 1.1.x) backed by TEE / StrongBox. Same Vault trait surface, different platform adapter.