SPB Git

Repository Public

README.md 21.2 KB 306 lines markdown

1# SP Vault — native apps (macOS, iOS, iPadOS)23Native clients of [SP Vault](https://vault.spboucher.ai), the end-to-end encrypted password manager: Swift 6, SwiftUI,4no WebView anywhere. Both apps ship an **AutoFill credential-provider extension** (passwords, passkeys, one-time5codes). All cryptography and sync logic lives in the Swift package `SharedVaultKit`, a method-for-method port of the6web engine that is tested against the real server.78Author: Simon-Pierre Boucher — contact@spboucher.ai910> **Not independently audited.** The protocol is documented in `docs/crypto-spec/SPV1.md`, the threat model in11> `THREAT_MODEL.md`. Read `docs/TEST_REPORT.md` for what was and was **not** verified on real hardware.1213## Status1415As of 2026-11-19 (details and the full not-verified list: `docs/TEST_REPORT.md`):1617- Debug builds of the four targets: zero warnings. Unit tests: 27 / 27 on macOS and on the iPhone simulator.18- XCUITest journeys pass on the iPhone simulator (join, recovery kit, item life cycle, import, Security Center,19  recovery on a fresh install), on the iPad simulator (split layout) and for cross-device pairing (iPhone simulator ↔ Mac).20- macOS click-level UI tests are written but did not run: this Mac needs an administrator authentication to enable21  Automation Mode. The Mac was exercised with scripted scenarios instead (`Scripts/mac-scenarios.sh`).22- Release macOS archive signed with Developer ID and both profiles verifies (`codesign --verify --deep --strict`);23  Release iOS archive builds with automatic provisioning. Not notarized, not uploaded.24- Nothing was run on a physical device: biometrics, Secure Enclave policies, the shared Keychain group, the system25  passkey sheet, AutoFill in Safari and the camera are unverified.2627### UI journeys2829- `Scripts/ui-tests.sh iphone | ipad | mac | pair | all` — XCUITest journeys (`Tests/UITests`) of the Dev variant against30  the local server; screenshots go to `docs/screenshots/`. `mac` needs Automation Mode enabled on the Mac and takes31  over keyboard and mouse while it runs.32- `Scripts/mac-scenarios.sh main | recover | pair` — the same journeys on macOS without Automation Mode: the Dev app33  runs scripted steps through its own model (`App/Shared/Model/DevScenario.swift`, SPV_DEV only). Not click-level.34- The main window on macOS and iPad is a two-column split (sidebar + list/detail side by side), not a three-column35  `NavigationSplitView`: tool pages get the full width and the macOS 27 double-height layout issue is avoided.3637## Layout3839```40apple/41  project.yml                 XcodeGen definition → SPVault.xcodeproj (generated, git-ignored)42  SharedVaultKit/             Swift package: SPV1 crypto, VaultEngine, VaultReader, stores, key stores (+ tests)43  App/Shared/Core/            compiled into the apps AND the extensions: AppEnvironment, PendingItems,44                              CredentialIdentities, DevSupport (SPV_DEV only)45  App/Shared/Design/          palette, typography, buttons, callouts (also used by the extension UI)46  App/Shared/Model/           AppModel (the observable object behind every screen), Preferences, services47  App/Shared/Views/           screens shared by macOS and iOS48  App/macOS/  App/iOS/        platform shells: windows, menus, menu bar extra, tab bar, camera scanner…49  App/Resources/              Info.plists, entitlements, asset catalog (icon, accent colour)50  AutoFill/Shared|macOS|iOS/  the credential-provider extension51  Tests/Unit/  Tests/UITests/ XCTest and XCUITest sources (built for both platforms)52  Scripts/                    build, test, dev server, release, notarization, provisioning53  docs/                       TEST_REPORT.md, screenshots54```5556### Targets5758| Target | Platform | Bundle identifier (Release / Debug) | Notes |59|---|---|---|---|60| `SPVault` | macOS 15+ | `ai.spboucher.spvault` / `….spvault.dev` | app "SP Vault" / "SP Vault Dev"; sandboxed, hardened runtime, Developer ID |61| `SPVaultAutoFill` | macOS 15+ | `ai.spboucher.spvault.autofill` / `….dev.autofill` | credential-provider extension, embedded in the app |62| `SPVault-iOS` | iOS / iPadOS 18+ | `ai.spboucher.spvault.ios` / `….ios.dev` | iPhone + iPad, automatic signing |63| `SPVaultAutoFill-iOS` | iOS / iPadOS 18+ | `ai.spboucher.spvault.ios.autofill` / `….ios.dev.autofill` | credential-provider extension |64| `SPVaultTests`, `SPVaultTests-iOS` | | | unit tests (hosted by the Dev app) |65| `SPVaultUITests`, `SPVaultUITests-iOS` | | | XCUITest journeys against the local real server |6667Team `3YM54G49SN`. Bundle identifiers, capabilities and the two macOS Developer ID provisioning profiles68("SP Vault Developer ID", "SP Vault AutoFill Developer ID") are created by `Scripts/provision.py` (idempotent; uses the69existing App Store Connect API key and Developer ID certificate, creates no certificate).7071## Build and run7273Requirements: Xcode 27, `xcodegen`, and for the Dev variant Node + pnpm dependencies of the repository74(`pnpm install` at the repository root) and a local PostgreSQL.7576```bash77cd apple78Scripts/build.sh mac            # "SP Vault Dev" (Debug) + extension — errors and warnings only79Scripts/build.sh mac Release    # Release configuration (needs the Developer ID identity and profiles)80Scripts/build.sh ios            # iOS Debug for the dedicated simulator "SPVault iPhone" (created on first use)81Scripts/build.sh ipad           # same for "SPVault iPad"82Scripts/build.sh generate       # only regenerate SPVault.xcodeproj83```8485Build products go to `~/Library/Developer/SPVault/DerivedData` (override with `SPV_DD`), never under `~/Desktop`.86Only the simulators named "SPVault iPhone" and "SPVault iPad" are used.8788### The development variant — "SP Vault Dev" (Debug, compile flag `SPV_DEV`)8990Debug builds are a separate app with its own bundle identifiers that talks to a **local copy of the real server**91instead of production. Everything specific to it is in `App/Shared/Core/DevSupport.swift`, which is compiled only with92`SPV_DEV`; the release scripts check that none of it is present in a Release binary.9394| | Release ("SP Vault") | Debug ("SP Vault Dev") |95|---|---|---|96| Server | `https://vault.spboucher.ai` | `http://localhost:8781`, RP ID `localhost` |97| Passkey | system passkey sheet (Associated Domains) | software WebAuthn authenticator, credentials in a file |98| Device keys | Secure Enclave, user presence (biometrics or passcode) | software P-256 keys in a JSON file, no prompt |99| Storage | app-group container | macOS: `~/Library/Application Support/SPVaultDev/<profile>/`; iOS simulator: app-group container `…/SPVaultDev/<profile>/` |100| macOS signing | Developer ID + provisioning profiles, sandboxed | ad hoc ("Sign to Run Locally"), **not sandboxed**, no restricted entitlement |101102The Dev variant exists so that automated runs never block on a system prompt. It protects nothing: never put real103secrets in it.104105Consequence on macOS: the Dev app is not sandboxed and keeps its files in the user's Application Support, while an106extension is always sandboxed — so **the macOS Dev AutoFill extension builds but is not functional**. AutoFill on107macOS needs the Release-signed build (shared app group and keychain group come from the provisioning profiles).108109Environment variables read by the Dev variant (set them with `XCUIApplication.launchEnvironment`, or110`SIMCTL_CHILD_<NAME>` with `xcrun simctl launch`):111112| Variable | Meaning |113|---|---|114| `SPV_DEV_SERVER` | base URL of the test server (default `http://localhost:8781`) |115| `SPV_DEV_PROFILE` | name of the local profile directory (default `default`) — two "devices" on one machine |116| `SPV_DEV_PASSKEY_FILE` | host path of the software-passkey file shared by the "devices" of one account |117| `SPV_DEV_PAIRING_FILE` | host path where a new device also writes its pairing code and 6-digit fingerprint |118| `SPV_DEV_RESET=1` | erase the profile at launch |119120### Local server121122```bash123Scripts/dev-server.sh up        # createdb if missing, start the real API on http://localhost:8781, wait until ready124Scripts/dev-server.sh invite    # prints an invitation token and the link http://localhost:8781/#/join/<token>125Scripts/dev-server.sh status126Scripts/dev-server.sh reset     # stop, drop and recreate the schema, start again127Scripts/dev-server.sh down      # stops only the process it started128```129130It runs `node_modules/.bin/tsx services/api/src/index.ts` from the repository root with131`DATABASE_URL=postgres://127.0.0.1/sp_vault_native_test`, `SPV_ORIGIN=http://localhost:8781`, `SPV_RP_ID=localhost`132and a data directory, PID file and log under `apple/build/dev-server/`. Nothing in the server is stubbed, except the133breach-range upstream which points back at the server itself (no outside request). Only port 8781134(`SPV_DEV_PORT`, 8781–8789) and that database are touched.135136To try the Dev app by hand: `Scripts/dev-server.sh up`, `Scripts/dev-server.sh invite`, launch "SP Vault Dev",137choose *I have an invitation* and paste the link or the token.138139## Tests140141```bash142Scripts/t.sh kit                # SharedVaultKit: swift test (crypto vectors, parity with TypeScript, engine vs real server)143Scripts/t.sh mac                # unit tests of the app (SPVaultTests)144Scripts/t.sh ios                # unit tests on the "SPVault iPhone" simulator145Scripts/t.sh ui-mac             # XCUITest journeys on macOS (starts the dev server)146Scripts/t.sh ui-ios             # XCUITest journeys on the "SPVault iPhone" simulator147Scripts/t.sh ui-ipad            # the same on "SPVault iPad"148Scripts/t.sh ui-ios -only-testing:SPVaultUITests-iOS/<Class>/<test>     # extra arguments go to xcodebuild149```150151Output is limited to failures and the summary line; full logs are in `build/logs/`. `docs/TEST_REPORT.md` lists what152is verified by automated test, what was verified by hand with evidence, and what is **not** verified.153154## Release155156Release steps are run by the owner. The scripts never create certificates and never print credentials.157158### macOS (Developer ID, outside the App Store)159160```bash161Scripts/provision.py            # once / when a capability changes: bundle ids, capabilities, Developer ID profiles162Scripts/release-mac.sh          # archive (Developer ID + the two profiles) → dist/SP Vault.app, checks no SPV_DEV artefact163Scripts/verify-release.sh       # signatures, hardened runtime, sandbox, entitlements of app and extension (printed), no web engine164Scripts/notarize.sh             # notarytool (keychain profile MacLustr-Notarize): app → staple → DMG → staple165```166167`notarize.sh` prints "notarized" only when Apple answered *Accepted*. Until then `spctl` rejects the app as an168unnotarized Developer ID build: that is expected, and `verify-release.sh` reports it as information only.169170### iOS / iPadOS (TestFlight)171172```bash173Scripts/release-ios.sh archive  # Release archive for generic/platform=iOS, -allowProvisioningUpdates (Xcode account)174Scripts/release-ios.sh export   # IPA for App Store Connect (Scripts/ExportOptions.plist)175Scripts/release-ios.sh validate176Scripts/release-ios.sh upload   # altool with the App Store Connect API key (ASC_KEY_ID / ASC_ISSUER_ID)177```178179The archive is signed with the Apple ID configured in Xcode because an App Store Connect API key cannot provision180App Groups. The app declares `ITSAppUsesNonExemptEncryption = false` (standard encryption only), consistent with the181owner's other apps.182183## Architecture184185```186            ┌────────────────────────── app (SwiftUI) ──────────────────────────┐187            │ AppModel ── VaultEngine (actor) ── URLSessionTransport ── server  │188            │                │            └── SystemPasskeys (ASAuthorization)  │189            │                ├── SQLiteStore  (read-write)                      │190            │                └── SecureEnclaveKeyStore (.userPresence)          │191            └───────┬───────────────────┬───────────────────────┬───────────────┘192   app-group container          shared Keychain group        ASCredentialIdentityStore193   vault.sqlite + pending/      device keys + identity       (site names, usernames — system-owned)194            ┌───────┴───────────────────┴───────────────────────┴───────────────┐195            │ AutoFill extension: VaultReader (read-only, offline, no network)  │196            └────────────────────────────────────────────────────────────────────┘197```198199- **Engine.** `VaultEngine` holds every key and every decrypted item in memory only while unlocked. The server200  receives ciphertext, public keys, identifiers and counters. Unlocking is offline: the account root key is wrapped201  for this device's encryption key and unwrapped by the Secure Enclave; the passkey is only needed to (re)open a202  server session. Writes go to a local outbox and survive being offline.203- **App model.** `AppModel` mirrors the engine's snapshots for SwiftUI and carries what is the same on both204  platforms: unlock/lock, auto-lock, the expiring clipboard, live events, AutoFill identities, ingestion of items205  created by the extension.206- **Live updates.** A small Server-Sent-Events client (`URLSession.bytes`) on `/api/v1/events` with the bearer token.207  Events are pokes without content (`sync`, `devices`, `pairing`, `shares`, `approval`, `activity`): the app then208  syncs or reloads the matching screen. Notifications for pairing requests and agent approvals carry fixed,209  content-free text.210211### Shared storage: app ⇄ extension2122131. **SQLite store in the app-group container** (`<group>/Vault/vault.sqlite`). The engine in the app is the only214   writer. The extension opens the same file **read-only** through `VaultReader`. The file holds ciphertext and215   public material only (record envelopes, vault-key grants, member public keys, cursors, the outbox, pins).216   macOS group: `3YM54G49SN.ai.spboucher.spvault`; iOS group: `group.ai.spboucher.spvault.ios`.2172. **Device keys in a shared Keychain access group**218   (`3YM54G49SN.ai.spboucher.spvault.shared` / `3YM54G49SN.ai.spboucher.spvault.ios.shared`):219   `SecureEnclaveKeyStore(accessGroup:, policy: .userPresence)`. The private keys are Secure Enclave keys; using them220   requires biometrics **or** the device passcode, so a changed fingerprint or a broken sensor does not lock the user221   out. The Keychain items are `WhenUnlockedThisDeviceOnly` and never synchronised. One `LAContext` is evaluated once222   and handed to both keys, so a single prompt covers an unlock — in the app and, separately, in the extension.223   Macs without a Secure Enclave fall back to software keys and are shown as "software" in the device list.2243. **`ASCredentialIdentityStore`.** After each unlock and each sync the app replaces the system's list of225   identities: for a login, a **site name and a username**; for a passkey, the relying party, account name and226   credential ID; for a one-time code, a site name and a label. **Never a password, a private key or a TOTP secret.**227   The operating system keeps this list so that it can offer entries in the keyboard / QuickType bar and in Safari228   without launching the extension; it is outside SP Vault's encryption, which is why Settings explains it and lets229   the user turn suggestions off (the list is then erased). It is also erased on sign-out and on "remove this230   device". Only `https` origins (and loopback) are advertised, and logins whose URL rule is "never" are excluded.2314. **Pending items** (`<group>/Vault/pending/*.json`). When the extension registers a new passkey it must save an232   item, but it has no network session and must not write to the database: the engine keeps the outbox in memory and233   rewrites it as a whole, so a second SQLite writer would be overwritten or would corrupt a sync in flight. The234   extension therefore drops one small file per item, **sealed with HPKE (P-256, AES-256-GCM) to this device's235   encryption key**. Only this device's Secure Enclave key can open it; the plaintext never touches the disk; the236   extension needs no vault key and no network. The app ingests the files through the engine at its next unlock237   (same authenticated context, no extra prompt), tells the user how many items were saved, and deletes them.238   Until then the extension can open its own pending files, so a passkey works right after it was created.239   HPKE base mode does not authenticate the sender: anything able to write in the app-group container (the app and240   its own extension) could drop an item — that is the trust boundary of the app itself. See the header of241   `App/Shared/Core/PendingItems.swift`.242243## AutoFill: what is supported, and where244245The extension is a system **credential provider** (`com.apple.authentication-services-credential-provider-ui`).246According to the SDK headers of the deployment targets (iOS 18 / macOS 15) it declares, on both platforms:247248| Capability (`ASCredentialProviderExtensionCapabilities`) | API |249|---|---|250| `ProvidesPasswords` | `ASPasswordCredential`, credential list and single-credential requests |251| `ProvidesPasskeys` | passkey assertion and registration (`ASPasskeyCredentialRequest`, iOS 17 / macOS 14) |252| `ProvidesOneTimeCodes` | `ASOneTimeCodeCredential` (iOS 18 / macOS 15) |253254Not claimed: saving passwords offered by the system and system-driven password generation255(`SupportsSavePasswordCredentials`, iOS 26.2 only, unavailable on macOS), text insertion, conditional passkey256registration.257258Where it works — and only there:259260- **Safari, and apps that use the system AutoFill** (native text fields with the right content types, apps and261  browsers that go through `ASAuthorizationController` / the system passkey sheet).262- The user must **enable SP Vault first**: iOS / iPadOS *Settings → General → AutoFill & Passwords*; macOS263  *System Settings → General → AutoFill & Passwords*. The app cannot turn this on by itself.264- **No universal browser support is claimed.** Third-party browsers that do not use the system credential-provider265  mechanism (some of them on macOS in particular) will not offer SP Vault; copy and paste from the app or the menu266  bar extra remains available, with the expiring clipboard.267268Behaviour: the extension never answers without user interaction (it always asks for biometrics or the passcode269first), never touches the network, and never returns a credential for a site that does not match the item's URL270rule (registrable-domain matching with the Public Suffix List, never `https` → `http`) unless the user picked it271from the full list after a confirmation naming both the site and the item. A look-alike domain is flagged with a272warning row.273274## Security behaviours of the apps275276- **Lock.** Auto-lock after a configurable idle delay; macOS locks when the Mac sleeps, the screen locks or the277  screensaver starts; iOS locks after a configurable time in the background. Locking wipes keys and decrypted items278  from memory.279- **Privacy cover.** iOS covers the content whenever the scene is not active (app switcher). macOS excludes its280  windows from screenshots, recording and screen sharing ("Hide from screen capture", on by default) and blurs the281  content when the app is not active.282- **Clipboard.** Copied secrets expire: on macOS the entry is marked `org.nspasteboard.ConcealedType` and cleared283  after the delay if the clipboard still holds it; on iOS the entry is local-only (no Universal Clipboard) with a284  system-enforced expiration date. This is best effort: another app may read the clipboard before it is cleared.285- **No telemetry.** No analytics, no crash-reporting SDK, no remote favicons. Logs carry no secrets286  (`os.Logger`, private by default). Notifications carry fixed text only.287- **Spotlight (macOS).** Nothing is indexed by default. An opt-in setting indexes item *titles only*, with the288  trade-off explained: titles then live in the system index, outside the vault's encryption.289- **Sensitive actions** (plaintext export, revoking a device, rekey, releasing the kill switch…) ask for290  confirmation and, where the server requires it, a fresh proof of presence signed by the device key.291- **Security errors.** Any failure of a check that protects against a malicious server (key substitution, rollback,292  altered audit chain) is shown as a prominent "Security warning", never as an ordinary error.293- **Connect & Agents** is a different trust model and says so on every screen: managed secrets are **not**294  zero-knowledge — the server can decrypt them in order to use them on the owner's behalf. Text supplied by an agent295  is always boxed and labelled as untrusted.296297## Limits to keep in mind298299- What the server still sees: account handle, device labels, vault membership, record sizes and timing, IP300  addresses — see `THREAT_MODEL.md`.301- The recovery key is shown once. Without a trusted device or that key, nobody can recover the vault.302- Attachments are not part of the encrypted backup file.303- Behaviour that depends on real hardware (Face ID / Touch ID prompts, Secure Enclave access control, the shared304  keychain group between app and extension, the system passkey sheet, AutoFill in Safari, the camera) is listed in305  `docs/TEST_REPORT.md` with its verification status.306
Files main
Menu

Theme