SP Vault — native apps (macOS, iOS, iPadOS)
Native clients of SP Vault, the end-to-end encrypted password manager: Swift 6, SwiftUI,
no WebView anywhere. Both apps ship an AutoFill credential-provider extension (passwords, passkeys, one-time
codes). All cryptography and sync logic lives in the Swift package SharedVaultKit, a method-for-method port of the
web engine that is tested against the real server.
Author: Simon-Pierre Boucher — contact@spboucher.ai
Not independently audited. The protocol is documented in
docs/crypto-spec/SPV1.md, the threat model inTHREAT_MODEL.md. Readdocs/TEST_REPORT.mdfor what was and was not verified on real hardware.
Status
As of 2026-11-19 (details and the full not-verified list: docs/TEST_REPORT.md):
- Debug builds of the four targets: zero warnings. Unit tests: 27 / 27 on macOS and on the iPhone simulator.
- XCUITest journeys pass on the iPhone simulator (join, recovery kit, item life cycle, import, Security Center, recovery on a fresh install), on the iPad simulator (split layout) and for cross-device pairing (iPhone simulator ↔ Mac).
- macOS click-level UI tests are written but did not run: this Mac needs an administrator authentication to enable
Automation Mode. The Mac was exercised with scripted scenarios instead (
Scripts/mac-scenarios.sh). - Release macOS archive signed with Developer ID and both profiles verifies (
codesign --verify --deep --strict); Release iOS archive builds with automatic provisioning. Not notarized, not uploaded. - Nothing was run on a physical device: biometrics, Secure Enclave policies, the shared Keychain group, the system passkey sheet, AutoFill in Safari and the camera are unverified.
UI journeys
Scripts/ui-tests.sh iphone | ipad | mac | pair | all— XCUITest journeys (Tests/UITests) of the Dev variant against the local server; screenshots go todocs/screenshots/.macneeds Automation Mode enabled on the Mac and takes over keyboard and mouse while it runs.Scripts/mac-scenarios.sh main | recover | pair— the same journeys on macOS without Automation Mode: the Dev app runs scripted steps through its own model (App/Shared/Model/DevScenario.swift, SPV_DEV only). Not click-level.- The main window on macOS and iPad is a two-column split (sidebar + list/detail side by side), not a three-column
NavigationSplitView: tool pages get the full width and the macOS 27 double-height layout issue is avoided.
Layout
apple/
project.yml XcodeGen definition → SPVault.xcodeproj (generated, git-ignored)
SharedVaultKit/ Swift package: SPV1 crypto, VaultEngine, VaultReader, stores, key stores (+ tests)
App/Shared/Core/ compiled into the apps AND the extensions: AppEnvironment, PendingItems,
CredentialIdentities, DevSupport (SPV_DEV only)
App/Shared/Design/ palette, typography, buttons, callouts (also used by the extension UI)
App/Shared/Model/ AppModel (the observable object behind every screen), Preferences, services
App/Shared/Views/ screens shared by macOS and iOS
App/macOS/ App/iOS/ platform shells: windows, menus, menu bar extra, tab bar, camera scanner…
App/Resources/ Info.plists, entitlements, asset catalog (icon, accent colour)
AutoFill/Shared|macOS|iOS/ the credential-provider extension
Tests/Unit/ Tests/UITests/ XCTest and XCUITest sources (built for both platforms)
Scripts/ build, test, dev server, release, notarization, provisioning
docs/ TEST_REPORT.md, screenshotsTargets
| Target | Platform | Bundle identifier (Release / Debug) | Notes |
|---|---|---|---|
SPVault |
macOS 15+ | ai.spboucher.spvault / ….spvault.dev |
app "SP Vault" / "SP Vault Dev"; sandboxed, hardened runtime, Developer ID |
SPVaultAutoFill |
macOS 15+ | ai.spboucher.spvault.autofill / ….dev.autofill |
credential-provider extension, embedded in the app |
SPVault-iOS |
iOS / iPadOS 18+ | ai.spboucher.spvault.ios / ….ios.dev |
iPhone + iPad, automatic signing |
SPVaultAutoFill-iOS |
iOS / iPadOS 18+ | ai.spboucher.spvault.ios.autofill / ….ios.dev.autofill |
credential-provider extension |
SPVaultTests, SPVaultTests-iOS |
unit tests (hosted by the Dev app) | ||
SPVaultUITests, SPVaultUITests-iOS |
XCUITest journeys against the local real server |
Team 3YM54G49SN. Bundle identifiers, capabilities and the two macOS Developer ID provisioning profiles
("SP Vault Developer ID", "SP Vault AutoFill Developer ID") are created by Scripts/provision.py (idempotent; uses the
existing App Store Connect API key and Developer ID certificate, creates no certificate).
Build and run
Requirements: Xcode 27, xcodegen, and for the Dev variant Node + pnpm dependencies of the repository
(pnpm install at the repository root) and a local PostgreSQL.
cd apple
Scripts/build.sh mac # "SP Vault Dev" (Debug) + extension — errors and warnings only
Scripts/build.sh mac Release # Release configuration (needs the Developer ID identity and profiles)
Scripts/build.sh ios # iOS Debug for the dedicated simulator "SPVault iPhone" (created on first use)
Scripts/build.sh ipad # same for "SPVault iPad"
Scripts/build.sh generate # only regenerate SPVault.xcodeprojBuild products go to ~/Library/Developer/SPVault/DerivedData (override with SPV_DD), never under ~/Desktop.
Only the simulators named "SPVault iPhone" and "SPVault iPad" are used.
The development variant — "SP Vault Dev" (Debug, compile flag SPV_DEV)
Debug builds are a separate app with its own bundle identifiers that talks to a local copy of the real server
instead of production. Everything specific to it is in App/Shared/Core/DevSupport.swift, which is compiled only with
SPV_DEV; the release scripts check that none of it is present in a Release binary.
| Release ("SP Vault") | Debug ("SP Vault Dev") | |
|---|---|---|
| Server | https://vault.spboucher.ai |
http://localhost:8781, RP ID localhost |
| Passkey | system passkey sheet (Associated Domains) | software WebAuthn authenticator, credentials in a file |
| Device keys | Secure Enclave, user presence (biometrics or passcode) | software P-256 keys in a JSON file, no prompt |
| Storage | app-group container | macOS: ~/Library/Application Support/SPVaultDev/<profile>/; iOS simulator: app-group container …/SPVaultDev/<profile>/ |
| macOS signing | Developer ID + provisioning profiles, sandboxed | ad hoc ("Sign to Run Locally"), not sandboxed, no restricted entitlement |
The Dev variant exists so that automated runs never block on a system prompt. It protects nothing: never put real secrets in it.
Consequence on macOS: the Dev app is not sandboxed and keeps its files in the user's Application Support, while an extension is always sandboxed — so the macOS Dev AutoFill extension builds but is not functional. AutoFill on macOS needs the Release-signed build (shared app group and keychain group come from the provisioning profiles).
Environment variables read by the Dev variant (set them with XCUIApplication.launchEnvironment, or
SIMCTL_CHILD_<NAME> with xcrun simctl launch):
| Variable | Meaning |
|---|---|
SPV_DEV_SERVER |
base URL of the test server (default http://localhost:8781) |
SPV_DEV_PROFILE |
name of the local profile directory (default default) — two "devices" on one machine |
SPV_DEV_PASSKEY_FILE |
host path of the software-passkey file shared by the "devices" of one account |
SPV_DEV_PAIRING_FILE |
host path where a new device also writes its pairing code and 6-digit fingerprint |
SPV_DEV_RESET=1 |
erase the profile at launch |
Local server
Scripts/dev-server.sh up # createdb if missing, start the real API on http://localhost:8781, wait until ready
Scripts/dev-server.sh invite # prints an invitation token and the link http://localhost:8781/#/join/<token>
Scripts/dev-server.sh status
Scripts/dev-server.sh reset # stop, drop and recreate the schema, start again
Scripts/dev-server.sh down # stops only the process it startedIt runs node_modules/.bin/tsx services/api/src/index.ts from the repository root with
DATABASE_URL=postgres://127.0.0.1/sp_vault_native_test, SPV_ORIGIN=http://localhost:8781, SPV_RP_ID=localhost
and a data directory, PID file and log under apple/build/dev-server/. Nothing in the server is stubbed, except the
breach-range upstream which points back at the server itself (no outside request). Only port 8781
(SPV_DEV_PORT, 8781–8789) and that database are touched.
To try the Dev app by hand: Scripts/dev-server.sh up, Scripts/dev-server.sh invite, launch "SP Vault Dev",
choose I have an invitation and paste the link or the token.
Tests
Scripts/t.sh kit # SharedVaultKit: swift test (crypto vectors, parity with TypeScript, engine vs real server)
Scripts/t.sh mac # unit tests of the app (SPVaultTests)
Scripts/t.sh ios # unit tests on the "SPVault iPhone" simulator
Scripts/t.sh ui-mac # XCUITest journeys on macOS (starts the dev server)
Scripts/t.sh ui-ios # XCUITest journeys on the "SPVault iPhone" simulator
Scripts/t.sh ui-ipad # the same on "SPVault iPad"
Scripts/t.sh ui-ios -only-testing:SPVaultUITests-iOS/<Class>/<test> # extra arguments go to xcodebuildOutput is limited to failures and the summary line; full logs are in build/logs/. docs/TEST_REPORT.md lists what
is verified by automated test, what was verified by hand with evidence, and what is not verified.
Release
Release steps are run by the owner. The scripts never create certificates and never print credentials.
macOS (Developer ID, outside the App Store)
Scripts/provision.py # once / when a capability changes: bundle ids, capabilities, Developer ID profiles
Scripts/release-mac.sh # archive (Developer ID + the two profiles) → dist/SP Vault.app, checks no SPV_DEV artefact
Scripts/verify-release.sh # signatures, hardened runtime, sandbox, entitlements of app and extension (printed), no web engine
Scripts/notarize.sh # notarytool (keychain profile MacLustr-Notarize): app → staple → DMG → staplenotarize.sh prints "notarized" only when Apple answered Accepted. Until then spctl rejects the app as an
unnotarized Developer ID build: that is expected, and verify-release.sh reports it as information only.
iOS / iPadOS (TestFlight)
Scripts/release-ios.sh archive # Release archive for generic/platform=iOS, -allowProvisioningUpdates (Xcode account)
Scripts/release-ios.sh export # IPA for App Store Connect (Scripts/ExportOptions.plist)
Scripts/release-ios.sh validate
Scripts/release-ios.sh upload # altool with the App Store Connect API key (ASC_KEY_ID / ASC_ISSUER_ID)The archive is signed with the Apple ID configured in Xcode because an App Store Connect API key cannot provision
App Groups. The app declares ITSAppUsesNonExemptEncryption = false (standard encryption only), consistent with the
owner's other apps.
Architecture
┌────────────────────────── app (SwiftUI) ──────────────────────────┐
│ AppModel ── VaultEngine (actor) ── URLSessionTransport ── server │
│ │ └── SystemPasskeys (ASAuthorization) │
│ ├── SQLiteStore (read-write) │
│ └── SecureEnclaveKeyStore (.userPresence) │
└───────┬───────────────────┬───────────────────────┬───────────────┘
app-group container shared Keychain group ASCredentialIdentityStore
vault.sqlite + pending/ device keys + identity (site names, usernames — system-owned)
┌───────┴───────────────────┴───────────────────────┴───────────────┐
│ AutoFill extension: VaultReader (read-only, offline, no network) │
└────────────────────────────────────────────────────────────────────┘- Engine.
VaultEngineholds every key and every decrypted item in memory only while unlocked. The server receives ciphertext, public keys, identifiers and counters. Unlocking is offline: the account root key is wrapped for this device's encryption key and unwrapped by the Secure Enclave; the passkey is only needed to (re)open a server session. Writes go to a local outbox and survive being offline. - App model.
AppModelmirrors the engine's snapshots for SwiftUI and carries what is the same on both platforms: unlock/lock, auto-lock, the expiring clipboard, live events, AutoFill identities, ingestion of items created by the extension. - Live updates. A small Server-Sent-Events client (
URLSession.bytes) on/api/v1/eventswith the bearer token. Events are pokes without content (sync,devices,pairing,shares,approval,activity): the app then syncs or reloads the matching screen. Notifications for pairing requests and agent approvals carry fixed, content-free text.
Shared storage: app ⇄ extension
- SQLite store in the app-group container (
<group>/Vault/vault.sqlite). The engine in the app is the only writer. The extension opens the same file read-only throughVaultReader. The file holds ciphertext and public material only (record envelopes, vault-key grants, member public keys, cursors, the outbox, pins). macOS group:3YM54G49SN.ai.spboucher.spvault; iOS group:group.ai.spboucher.spvault.ios. - Device keys in a shared Keychain access group
(
3YM54G49SN.ai.spboucher.spvault.shared/3YM54G49SN.ai.spboucher.spvault.ios.shared):SecureEnclaveKeyStore(accessGroup:, policy: .userPresence). The private keys are Secure Enclave keys; using them requires biometrics or the device passcode, so a changed fingerprint or a broken sensor does not lock the user out. The Keychain items areWhenUnlockedThisDeviceOnlyand never synchronised. OneLAContextis evaluated once and handed to both keys, so a single prompt covers an unlock — in the app and, separately, in the extension. Macs without a Secure Enclave fall back to software keys and are shown as "software" in the device list. ASCredentialIdentityStore. After each unlock and each sync the app replaces the system's list of identities: for a login, a site name and a username; for a passkey, the relying party, account name and credential ID; for a one-time code, a site name and a label. Never a password, a private key or a TOTP secret. The operating system keeps this list so that it can offer entries in the keyboard / QuickType bar and in Safari without launching the extension; it is outside SP Vault's encryption, which is why Settings explains it and lets the user turn suggestions off (the list is then erased). It is also erased on sign-out and on "remove this device". Onlyhttpsorigins (and loopback) are advertised, and logins whose URL rule is "never" are excluded.- Pending items (
<group>/Vault/pending/*.json). When the extension registers a new passkey it must save an item, but it has no network session and must not write to the database: the engine keeps the outbox in memory and rewrites it as a whole, so a second SQLite writer would be overwritten or would corrupt a sync in flight. The extension therefore drops one small file per item, sealed with HPKE (P-256, AES-256-GCM) to this device's encryption key. Only this device's Secure Enclave key can open it; the plaintext never touches the disk; the extension needs no vault key and no network. The app ingests the files through the engine at its next unlock (same authenticated context, no extra prompt), tells the user how many items were saved, and deletes them. Until then the extension can open its own pending files, so a passkey works right after it was created. HPKE base mode does not authenticate the sender: anything able to write in the app-group container (the app and its own extension) could drop an item — that is the trust boundary of the app itself. See the header ofApp/Shared/Core/PendingItems.swift.
AutoFill: what is supported, and where
The extension is a system credential provider (com.apple.authentication-services-credential-provider-ui).
According to the SDK headers of the deployment targets (iOS 18 / macOS 15) it declares, on both platforms:
Capability (ASCredentialProviderExtensionCapabilities) |
API |
|---|---|
ProvidesPasswords |
ASPasswordCredential, credential list and single-credential requests |
ProvidesPasskeys |
passkey assertion and registration (ASPasskeyCredentialRequest, iOS 17 / macOS 14) |
ProvidesOneTimeCodes |
ASOneTimeCodeCredential (iOS 18 / macOS 15) |
Not claimed: saving passwords offered by the system and system-driven password generation
(SupportsSavePasswordCredentials, iOS 26.2 only, unavailable on macOS), text insertion, conditional passkey
registration.
Where it works — and only there:
- Safari, and apps that use the system AutoFill (native text fields with the right content types, apps and
browsers that go through
ASAuthorizationController/ the system passkey sheet). - The user must enable SP Vault first: iOS / iPadOS Settings → General → AutoFill & Passwords; macOS System Settings → General → AutoFill & Passwords. The app cannot turn this on by itself.
- No universal browser support is claimed. Third-party browsers that do not use the system credential-provider mechanism (some of them on macOS in particular) will not offer SP Vault; copy and paste from the app or the menu bar extra remains available, with the expiring clipboard.
Behaviour: the extension never answers without user interaction (it always asks for biometrics or the passcode
first), never touches the network, and never returns a credential for a site that does not match the item's URL
rule (registrable-domain matching with the Public Suffix List, never https → http) unless the user picked it
from the full list after a confirmation naming both the site and the item. A look-alike domain is flagged with a
warning row.
Security behaviours of the apps
- Lock. Auto-lock after a configurable idle delay; macOS locks when the Mac sleeps, the screen locks or the screensaver starts; iOS locks after a configurable time in the background. Locking wipes keys and decrypted items from memory.
- Privacy cover. iOS covers the content whenever the scene is not active (app switcher). macOS excludes its windows from screenshots, recording and screen sharing ("Hide from screen capture", on by default) and blurs the content when the app is not active.
- Clipboard. Copied secrets expire: on macOS the entry is marked
org.nspasteboard.ConcealedTypeand cleared after the delay if the clipboard still holds it; on iOS the entry is local-only (no Universal Clipboard) with a system-enforced expiration date. This is best effort: another app may read the clipboard before it is cleared. - No telemetry. No analytics, no crash-reporting SDK, no remote favicons. Logs carry no secrets
(
os.Logger, private by default). Notifications carry fixed text only. - Spotlight (macOS). Nothing is indexed by default. An opt-in setting indexes item titles only, with the trade-off explained: titles then live in the system index, outside the vault's encryption.
- Sensitive actions (plaintext export, revoking a device, rekey, releasing the kill switch…) ask for confirmation and, where the server requires it, a fresh proof of presence signed by the device key.
- Security errors. Any failure of a check that protects against a malicious server (key substitution, rollback, altered audit chain) is shown as a prominent "Security warning", never as an ordinary error.
- Connect & Agents is a different trust model and says so on every screen: managed secrets are not zero-knowledge — the server can decrypt them in order to use them on the owner's behalf. Text supplied by an agent is always boxed and labelled as untrusted.
Limits to keep in mind
- What the server still sees: account handle, device labels, vault membership, record sizes and timing, IP
addresses — see
THREAT_MODEL.md. - The recovery key is shown once. Without a trusted device or that key, nobody can recover the vault.
- Attachments are not part of the encrypted backup file.
- Behaviour that depends on real hardware (Face ID / Touch ID prompts, Secure Enclave access control, the shared
keychain group between app and extension, the system passkey sheet, AutoFill in Safari, the camera) is listed in
docs/TEST_REPORT.mdwith its verification status.