SPB Git

Repository Public

README.md 21.2 KB

# 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 in THREAT_MODEL.md. Read docs/TEST_REPORT.md for 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 to docs/screenshots/. mac needs 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

text
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, screenshots

# Targets

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.

bash
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.xcodeproj

Build 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

bash
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 started

It 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

bash
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 xcodebuild

Output 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)

bash
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 → staple

notarize.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)

bash
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

text
            ┌────────────────────────── 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. VaultEngine holds 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. AppModel mirrors 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/events with 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

  1. 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 through VaultReader. 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.
  2. 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 are WhenUnlockedThisDeviceOnly and never synchronised. One LAContext is 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.
  3. 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". Only https origins (and loopback) are advertised, and logins whose URL rule is "never" are excluded.
  4. 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 of App/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.ConcealedType and 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.md with its verification status.
Files main
Menu

Theme