keevault/docs/superpowers/specs/2026-05-21-mypass-design.md

# MyPass — Design Spec

**Date:** 2026-05-21  
**Status:** Approved  

---

## Overview

MyPass is a iOS + macOS password manager that reads and writes KeePass KDBX vaults. Users pick an existing `.kdbx` file from anywhere in the Files system (iCloud Drive, Dropbox, local storage) and MyPass becomes their viewer/editor for that vault. A bundled AutoFill Credential Provider extension enables password fill-in across every app on the device — not just Safari.

### Goals
- Open, browse, add, edit, and delete entries in an existing KDBX vault
- Unlock with master password once; Face ID / Touch ID on subsequent opens
- AutoFill credentials into any app via `ASCredentialProviderViewController`
- Support full KeePass entry structure: groups/subgroups, custom fields, TOTP, attachments

### Non-goals
- Creating new KDBX vaults from scratch
- Syncing or hosting vaults (the user owns the file)
- Web browser extension

---

## Architecture

### Option chosen: Local Swift Package + App Extension

A local Swift Package (`MyPassCore`) holds all vault logic. Both targets link to it. A shared App Group bridges the two processes.

```
MyPassCore (Swift Package)
├── KDBXDocument          — parse and write KDBX 3.1 / 4.0
├── Entry / Group / Attachment — value-type models
├── TOTPGenerator         — RFC 6238 TOTP from otp:// custom field
├── VaultSession          — owns the live KDBXDatabase; lock/unlock lifecycle
└── KeychainStore         — read/write master password in shared Keychain group

MyPass (Main App Target)  ──links──► MyPassCore
├── UnlockView
├── GroupBrowserView
├── EntryDetailView
├── EntryEditView
├── SearchView
├── FileBookmarkService   — security-scoped bookmark management
├── BiometricAuthService  — LAContext wrapper
└── ClipboardService      — copy with 30 s expiry

AutoFill (App Extension Target)  ──links──► MyPassCore
├── ASCredentialProviderViewController subclass
├── CredentialListView    — filtered by serviceIdentifier URL/domain
└── UnlockView (mini)     — Face ID → password fallback

Shared App Group (group.org.antiloop222.mypass)
├── UserDefaults          — security-scoped bookmark, last-opened vault, settings
└── Keychain Access Group — master password, biometric token (org.antiloop222.mypass)
```

**External dependencies (SPM)**
- KDBX parsing: KeePassKit (Objective-C, MIT). No upstream SPM support, so vendored locally as a git submodule (`Vendor/KeePassKit`) with a hand-written `Package.swift`. This pulled in the same problem three more times — none of the following had clean drop-in SPM support either, so all are vendored the same way:
  - KissXML (`Vendor/KissXML`) — XML parsing KeePassKit depends on
  - Argon2 (nested git submodule inside `Vendor/KeePassKit`) — KDBX4 key derivation
  - ChaCha20 / TwoFish — cipher implementations already bundled in KeePassKit's own source tree, wired into the SPM target
- Apple CryptoKit (built-in)
- LocalAuthentication (built-in)
- AuthenticationServices (built-in)

---

## Data Model

All types are value types (`struct`) defined in `MyPassCore`. `VaultSession` is the single owner of a live `KDBXDatabase`.

```swift
struct KDBXDatabase {
    var metadata: DatabaseMetadata   // name, description, cipher, compression
    var root: Group
}

struct Group: Identifiable {
    var id: UUID
    var name: String
    var iconIndex: Int
    var subgroups: [Group]           // recursive tree
    var entries: [Entry]
}

struct Entry: Identifiable {
    var id: UUID
    var title: String
    var username: String
    var password: ProtectedString
    var url: String
    var notes: String
    var customFields: [CustomField]
    var attachments: [Attachment]
    var totp: TOTPConfig?            // parsed from otp:// custom field
    var tags: [String]
    var iconIndex: Int
    var expiryDate: Date?
    var creationDate: Date
    var modificationDate: Date
    var history: [Entry]             // read-only previous versions
}

struct CustomField: Identifiable {
    var id: UUID
    var key: String
    var value: ProtectedString
}

struct ProtectedString {
    private(set) var value: String   // XOR-obfuscated in memory
    var isProtected: Bool
    func reveal() -> String          // decode on demand only
}

struct Attachment: Identifiable {
    var id: UUID
    var name: String
    var data: Data
}

struct TOTPConfig {
    var secret: String
    var period: Int                  // default 30s
    var digits: Int                  // default 6
    var algorithm: TOTPAlgorithm     // SHA1 / SHA256 / SHA512
}
```

`ProtectedString` XOR-obfuscates its value in memory and only decodes on explicit `reveal()` calls. It never appears in logs or debug descriptions.

---

## UI Navigation

### iOS — NavigationStack

```
UnlockView
  └─► GroupBrowserView (root group)
        ├─► GroupBrowserView (subgroup, pushed recursively)
        └─► EntryDetailView
              └─► EntryEditView (sheet)
```

- Search bar at the top of every `GroupBrowserView` filters entries globally across all groups
- Swipe-to-delete on entries; toolbar `+` button adds an entry in the current group
- Tapping a password field in `EntryDetailView` copies to clipboard (clears after 30 s)
- TOTP code displays with a countdown ring and refreshes automatically

### macOS — NavigationSplitView (3 columns)

| Sidebar | Middle | Detail |
|---|---|---|
| Group tree (expandable) | Entry list for selected group + search bar | Entry fields + Edit button |

Keyboard shortcuts: `⌘C` copies password, `⌘⌥C` copies TOTP code, `⌘E` opens edit sheet.

---

## AutoFill Credential Provider Extension

**Entitlement:** `com.apple.developer.authentication-services.autofill-credential-provider`  
**Extension point:** `com.apple.authentication-services-credential-provider-ui`

### Runtime flow

1. User taps a login field in any app → iOS shows QuickType bar with MyPass icon
2. User taps the icon → iOS instantiates `ASCredentialProviderViewController` and calls `prepareCredentialList(for: [ASCredentialServiceIdentifier])`
3. Extension checks Keychain for a valid biometric token:
   - **Token valid (vault was recently unlocked):** skip to step 5
   - **Token missing/expired:** show mini `UnlockView` → `LAContext` Face ID / Touch ID → password fallback
4. Extension resolves the security-scoped bookmark from shared App Group `UserDefaults`, opens the KDBX file, decrypts using the master password from the shared Keychain group
5. `CredentialListView` displays entries filtered by matching the `serviceIdentifier` URL/domain against each entry's URL field. Search bar allows manual lookup across all entries
6. User taps an entry → `completeRequest(withSelectedCredential: ASPasswordCredential(user:password:))` → field filled → extension dismissed

### Onboarding

Neither iOS nor macOS allows the extension to be pre-enabled — the user must turn it on manually (Settings → Passwords → AutoFill Passwords on iOS; System Settings → Extensions on macOS). The main app's first-launch flow should detect this and prompt the user with a deep link to the relevant settings screen.

### URL matching

Entry URL field is matched against the `serviceIdentifier` using host comparison (e.g. `github.com` matches `https://github.com/login` and bundle ID-based identifiers via Associated Domains). Entries with no URL are shown in a separate "All entries" section below suggestions.

### Extension constraints

- Memory limit ~50 MB: KDBX is parsed fresh on each extension invocation; no SwiftData or persistent cache inside the extension
- If KDBX parse fails, show an error alert with an "Open MyPass" deep-link button (`mypass://unlock`)

---

## Security Model

| Concern | Implementation |
|---|---|
| Master password at rest | Keychain item: `kSecAttrAccessibleWhenUnlockedThisDeviceOnly`, shared via Keychain Access Group |
| Biometric unlock | `LAContext.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics)` retrieves master password from Keychain on success |
| File access | Security-scoped bookmark in shared App Group `UserDefaults`; `startAccessingSecurityScopedResource()` / `stopAccessingSecurityScopedResource()` bracket every read/write |
| In-memory passwords | `ProtectedString` XOR-obfuscates values; decoded only on `reveal()` |
| Clipboard | `UIPasteboard` item set with 30-second expiration using `UIPasteboard.setItems(_:options:)` with `UIPasteboardOptionExpirationDate` |
| KDBX crypto | Fully delegated to the KDBX parsing library (AES-256-CBC / ChaCha20, Argon2d / AES-KDF) — no custom crypto |
| Vault lock on background | `VaultSession.lock()` called in `sceneDidEnterBackground` — zeroes master password from memory; biometric re-auth required on next foreground |

---

## Error Handling

| Scenario | Behaviour |
|---|---|
| Wrong master password | Alert: "Incorrect password" — no retry limit |
| Corrupt or unsupported KDBX | Alert with file name and format error message |
| Bookmark stale (file moved/deleted) | Alert: "Vault file not found" + "Choose file…" button |
| Biometrics unavailable | Graceful fallback to password entry field (both main app and extension) |
| Extension parse failure | Error screen + "Open MyPass" deep-link button |
| Save conflict (file modified externally) | Detect via `NSFileCoordinator`; alert user and offer to reload or overwrite |

---

## Testing

### `MyPassCoreTests` (unit)
- Parse fixture `.kdbx` files (KDBX 3.1 and 4.0 with both AES-KDF and Argon2d)
- Round-trip: parse → modify entry → write → re-parse → assert equality
- `TOTPGenerator`: known test vectors from RFC 6238
- `ProtectedString`: obfuscation / reveal symmetry
- AutoFill URL matching: table-driven tests covering exact match, subdomain, no-URL entries

### `MyPassTests` (integration)
- Unlock flow with a test KDBX fixture
- Add / edit / delete entry persisted to file

### `MyPassUITests`
- Unlock → browse groups → view entry detail → copy password
- Add entry → verify it appears in list
- Search: query returns expected entries

---

## Open Questions

1. ~~**KDBX library:** Evaluate Swift Package Manager options that support KDBX 3.1 + 4.0 with Argon2. Fallback: KeePassKit (Objective-C via bridging header).~~ **Resolved:** no SPM-native option was found; KeePassKit is used, vendored locally (see External dependencies above).
2. ~~**macOS AutoFill:** `ASCredentialProviderExtension` on macOS 13+ has reduced scope vs iOS — verify which apps support third-party fill on macOS and document limitations.~~ **Resolved:** no scope reduction found. Same `ASCredentialProviderViewController` API and "app or website" coverage as iOS. The only difference is enablement — the user must turn the extension on manually (System Settings → Extensions on macOS, Settings → Passwords → AutoFill on iOS); neither platform allows pre-enabling it via MDM/config profile. Onboarding should prompt the user to do this on first launch, on both platforms.
3. ~~**Associated Domains:** For bundle-ID-based AutoFill matching, an associated domains file may be needed for first-party apps. Evaluate at implementation time.~~ **Resolved: not applicable.** Associated Domains is the responsibility of the app *being logged into* (so the system can pass a domain-based `serviceIdentifier` instead of a bundle-ID one) — not the password manager. MyPass already handles both cases correctly: `CredentialMatcher` just matches whatever `serviceIdentifier` the system supplies against stored entry URLs, the same approach 1Password/Bitwarden use. No work needed.