Native Swift package for iOS apps

[scarlettmueller96]

Update: the two smaller API gaps originally filed here have been split out as requested —
#496 (additional parameters on token requests) and #497 (Migration.setTokens not seeding the
snapshot nonce, filed as a bug). This issue now covers only the Swift package.

Summary

The docs say a Swift package for native iOS apps is "still pending". I'd like to help make that
happen, and I have a working proposal in #495 — but I'd rather agree the shape with you than have you
spend review time on something you'd want built differently.

Context: we're currently migrating a production Android app from AppAuth to Lokksmith — the work is
in progress and not released yet — and we'd like to do the same for our native Swift iOS app, which
is what led me here. So this comes from wanting to use Lokksmith in production rather than from
wanting to write a library.

The API isn't reachable from Swift

Even with a framework in hand, lokksmith-core's public surface doesn't survive Objective-C export:

• create / getOrCreate take a CreateContext builder configured through write-only extension
  properties (CreateContext.id, .discoveryUrl, .metadata). Extension properties aren't
  exported as settable members, so a client cannot be created from Swift at all.
• Lokksmith.Options needs CoroutineScope, HttpClientEngine and SuspendFunction0<Instant>,
  and Objective-C export drops default arguments — so Swift would have to supply all five.
• Client.key / Client.id are value classes.
• Client.tokens is a StateFlow; runWithTokens takes a suspend function type, which cannot be
  exported as a parameter at all.
• Scope is a sealed class; errors are Kotlin exception types, which surface as opaque NSErrors
  without @Throws.

So a hand-written facade is needed regardless — which I think is fine, and arguably better than
exporting core wholesale: the facade can be small and shaped for Swift rather than mirroring Kotlin.

There's no artifact to link

No Package.swift, no XCFramework in the release.

Why Objective-C export rather than Kotlin's native Swift export

Worth being explicit about this, since Swift export is the more modern answer and it would be
reasonable to ask why the proposal doesn't use it.

Kotlin's native Swift export is genuinely nicer where it applies: suspend maps to Swift async,
Flow to AsyncSequence, and there's no Objective-C layer flattening namespaces or renaming enum
entries. We already use it for one of our own internal KMP packages and it's working well so far, so
this isn't scepticism about the feature.

Two reasons we didn't propose it here:

1. It's still Alpha, with breaking changes expected. Choosing a not-yet-stable export mechanism
   is a very different decision for a published library than for our own internal package, where we
   control both sides and can absorb churn on our own schedule. That call belongs to you, not to a
   contributor — so proposing it felt out of place.
2. It doesn't produce a distributable artifact yet. As far as I can see, it emits Swift sources
   plus a static library into the Xcode build directory, for a workflow where Xcode drives the Kotlin
   build. That's fine when the consumer builds the Kotlin themselves — it's how our internal package
   works — but a published Swift package has to ship a prebuilt binary that SPM can fetch from a
   release, and I don't think Swift export can do that today. Happy to be corrected.

So Objective-C export plus the XCFramework() DSL and an SPM .binaryTarget looks like the only
route that gets a native iOS app a real dependency today. If Swift export becomes the right answer
later, the facade module is the natural place to switch: its whole job is to be the boundary, so the
public Swift shape could stay similar while the mechanism underneath changes.

What's in #495

A lokksmith-swift module, verified end to end on Kotlin 2.4.10 / Xcode 26.6:

import Lokksmith

let lokksmith = LokksmithManager()
let client = try await lokksmith.getOrCreateClient(
    key: "main",
    configuration: .companion.discovery(
        clientId: "my-client-id",
        discoveryUrl: "https://example.com/.well-known/openid-configuration"
    )
)

let request = LokksmithAuthorizationRequest(redirectUri: "my-app://openid-response")
request.scopes = ["profile", "email"]

// Presents ASWebAuthenticationSession, exchanges the code, validates and persists.
// nil when the user dismissed the browser.
if let tokens = try await client.authorize(request: request) { … }

// Synchronous, no network — for "is the user signed in?"
if client.isAuthenticated { … }

// Refreshes only when needed.
let accessToken = try await client.freshTokens().accessToken.token

Notable points:

• lokksmith-core stays an implementation dependency and is deliberately not exported, so the
  generated header contains only Lokksmith* declarations. Verified against the built header.
• LokksmithFailure.kind separates a provider rejection (oAuthRejection) from a transient
  transport failure — the distinction a client app has to act on, and one that is currently
  awkward to recover from a bare NSError.
• A swiftApiSmokeTest Gradle task type-checks a real Swift sample against the assembled
  XCFramework and is wired into check. Since CI already runs on macos-latest, this guards the
  exported surface and the documented snippets. I confirmed it fails on a deliberate break — worth
  having, because interop regressions (a default argument added, an enum renamed) are invisible from
  Kotlin.
• Release flow: a packageSwiftArtifact task zips the XCFramework and prints the SHA-256, which I
  verified matches swift package compute-checksum. Wiring that into your release automation is
  your call — I left Package.swift with a placeholder checksum rather than guess at how you'd want
  release-please to update it.

Open questions, all yours to decide

• Naming. I used LokksmithManager, LokksmithClient, LokksmithTokens. The Lokksmith
  prefix is needed because Objective-C export has no namespaces, but LokksmithManager for the
  thing that is Lokksmith in Kotlin is a compromise. Open to anything.
• Scope of the facade. I covered create/get/delete client, authorization, refresh, freshTokens,
  reset, end-session and migration. I left out Snapshot, Jwt/Claims and multiple-client
  niceties.
• Targets. iosArm64 + iosSimulatorArm64, matching core. No iosX64, so Intel Macs can't run
  it in the simulator. Adding it would mean adding the target to core too.
• iOS 15 minimum, which is just Kotlin/Native's default here.
• Whether you want this as a module in this repo at all, versus a separate one.

---

AI disclosure: this issue text, the description of #495 and the module code in it were written
with the help of Claude (Claude Code, Opus 5), with me directing and reviewing. The commit on #495
carries a Co-Authored-By: Claude Opus 5 trailer. The verification claims above were actually
executed rather than asserted — see #495 for what was and wasn't checked.

[svenjacobs]

Thanks for the very detailed write-up — and for offering to do the work rather than just asking for it. That's a lot to take in at once, so let me answer in parts.

1 and 2: Both sound reasonable to me. Could you open them as separate issues so we can track and discuss them independently? The nonce one reads more like a bug than a feature request, so feel free to file it as such. PRs are welcome for both.

3, the Swift package: This is definitely something I want for Lokksmith, so I'm glad you're bringing it up. Two things on timing, just so expectations are clear:

• I'm not really familiar with Objective-C, Swift or iOS, so please allow me some time to dig into these topics before I can properly review a proposal of this size. Your write-up is a good starting point for that.
• I'd also like to get the encryption work (Encrypt tokens at rest #486) merged first — I'm still reviewing and testing it — before we start on a Swift package.

So realistically, the Swift package won't be merged in the next few days, and probably not in the next few weeks either. I'd rather say that upfront than have you sitting on a PR waiting for me.

One last thing: if a pull request description or any commits were created with the help of AI, please state so clearly. I'm not against AI at all, I just want full transparency. Thank you very much for your understanding, and thanks again for the thorough proposal!

[scarlettmueller96]

Thanks for the quick and clear answer — all of that makes sense.

AI disclosure first, since you asked directly. Yes. The issue text here, the description of #495
and the module code in it were written with the help of Claude (Claude Code, Opus 5), with me
directing and reviewing. The commit on #495 carries a Co-Authored-By: Claude Opus 5 trailer, and
I've now made it explicit in the commit message body too rather than leaving it to the trailer alone.
I've added the same disclosure to #494, #496 and #497. Thanks for asking plainly — I should have
stated it upfront rather than waiting to be asked.

One thing worth separating out: the verification claims in #495 aren't AI-asserted. The XCFramework
was actually assembled, the generated header inspected to confirm no core types leak, and the Swift
sample type-checked against the built framework. I also deliberately broke the sample to confirm the
new check task fails rather than silently passing. What was not done is a live authorization flow
against a real provider from a native app — that's called out in the PR.

1 and 2: split out as you asked — #496 for the token-request parameters, and #497 for the nonce,
filed as a bug since that's what it is. I'll hold off on PRs for those until you've had a chance to
say which shape you'd prefer for #496; the fix for #497 looks like one line, so I'm happy to send it
whenever it suits you.

3, timing: completely fine, and thank you for saying it upfront — that's much more useful than
optimism. Getting #486 in first is obviously the right order; encryption at rest matters more to
users than iOS reachability does, and I'd rather not have a Swift package land on top of storage
internals that are about to change. Please take the time you need on the Objective-C and iOS side —
I've left #495 as a draft precisely because it isn't waiting on anything, and I'm not blocked: our
iOS app stays on AppAuth for now, which works fine.

If it helps when you do dig in, I've added a section to #494 explaining why the proposal uses
Objective-C export rather than Kotlin's native Swift export, since that's the first question I'd
expect. Short version: Swift export is the nicer mechanism and we already use it for one of our own
internal KMP packages with good results, but it's still Alpha with breaking changes expected, and as
far as I can see it can't yet produce a prebuilt artifact that SPM can fetch from a release — it
emits Swift sources plus a static library for a workflow where Xcode drives the Kotlin build. Picking
a not-yet-stable export mechanism is also a very different decision for a published library than for
an internal package where you control both sides, and that call is yours rather than a contributor's.
Happy to be corrected on any of it — you may well reach a different conclusion once you've looked,
and I'd rather you did than defer to my write-up.

Also happy to answer Objective-C/Swift interop questions as they come up, or to trim the PR down if a
smaller first step would be easier to review.