01
Two delivery paths, one product
Both give you a separate listing on the App Store and on Google Play. The difference is what runs inside the app, and how much of your encryption you can enforce with the phone itself.
Dimension
Packaged build
The web app in a native shell
Separate native clients
Written for each platform
What ships
Packaged build
One web codebase in a native shell. Two store builds — an iOS IPA and an Android AAB.
Native
Two independent clients, Swift/SwiftUI and Kotlin/Compose, against the same backend.
What ships
Packaged build
One web codebase in a native shell. Two store builds — an iOS IPA and an Android AAB.
Native
Two independent clients, Swift/SwiftUI and Kotlin/Compose, against the same backend.
Time to first release
Packaged build
Days. The published app already produces store files.
Native
Three to five months for both, before review cycles.
Time to first release
Packaged build
Days. The published app already produces store files.
Native
Three to five months for both, before review cycles.
Code you maintain
Packaged build
One app. Mobile fixes ride along with web deploys.
Native
Three codebases and two release trains, permanently.
Code you maintain
Packaged build
One app. Mobile fixes ride along with web deploys.
Native
Three codebases and two release trains, permanently.
Key custody
Packaged build
Soft. The shell cannot reach Keychain or Keystore, so the vault key sits behind an app passcode.
Native
Hard. The operating system releases the key only after device authentication.
Key custody
Packaged build
Soft. The shell cannot reach Keychain or Keystore, so the vault key sits behind an app passcode.
Native
Hard. The operating system releases the key only after device authentication.
One-time sign-in
Packaged build
Yes — a persisted session behind a local lock screen.
Native
Yes — a refresh token in secure storage, gated by the OS.
One-time sign-in
Packaged build
Yes — a persisted session behind a local lock screen.
Native
Yes — a refresh token in secure storage, gated by the OS.
Offline access
Packaged build
Ciphertext cache only. No background sync.
Native
Encrypted local store with background refresh.
Offline access
Packaged build
Ciphertext cache only. No background sync.
Native
Encrypted local store with background refresh.
Push notifications
Packaged build
None native. In-app and email only.
Native
APNs and FCM, with metadata kept out of the payload.
Push notifications
Packaged build
None native. In-app and email only.
Native
APNs and FCM, with metadata kept out of the payload.
Store compliance
Packaged build
Standard review. Declare encryption use on every submission.
Native
Same, plus every release waits on review.
Store compliance
Packaged build
Standard review. Declare encryption use on every submission.
Native
Same, plus every release waits on review.
Cost to build
Packaged build
Low.
Native
High — two clients' worth of work for one product.
Cost to build
Packaged build
Low.
Native
High — two clients' worth of work for one product.
Recommendation — ship the shell first, go native second
Get the four data types, device registration and team linking into members' hands while the protocol settles. Reserve native clients for the moment a requirement genuinely needs the operating system's gate: passcode-bound keys, background sync, push. Everything else in this document is backend work both paths share, so nothing built now is thrown away.
The trade you accept in phase one: the vault key is protected by an app passcode rather than by the phone's hardware. That is a real difference, and section 02 is honest about it.
02
One sign-in, then a local lock
The request is a single authentication per device, then a passcode to reopen. That is achievable on both paths, but the strength of the lock is not the same on both.
- 01
First run
Email and password through the existing platform login. Nothing new to trust, nothing new to store.
- 02
Seed check
If the Genesis Ritual is unfinished it finishes here. Recovery is never optional on a phone.
- 03
Device registration
The device posts a name, a platform and a P-256 public key. The server returns a device id and a rotating refresh token bound to that id.
- 04
Key wrap
The vault key is unwrapped once, then re-wrapped under a device key derived from the app passcode with Argon2id. The raw key is never written to storage.
- 05
Relock
On backgrounding, inactivity or a failed attempt, the key is wiped from memory. The passcode derives the device key again and unwraps.
- 06
Revocation
Any signed-in session can kill a device. Its refresh token dies, its wrapped key is purged, and its next request is refused.
What a passcode check can and cannot do
No app can read or verify the phone's passcode — not ours, not anyone's. The only real difference between the two paths is who holds the key behind the gate.
App passcode
The app compares the entry against a hash it derived. Works everywhere, including the web shell. Against a casual snoop it is enough; against someone holding the device files it only holds up if the derivation is deliberately slow.
Both paths
Operating system gate
On iOS a Keychain item with a device-passcode access control; on Android a Keystore key with user authentication required. The OS releases the key only after the person authenticates. Native clients only.
Native only
Biometrics
The same gate with a different authenticator. It falls back to the device passcode when a face or finger is not recognised.
Native only
Design rule: treat the passcode as a gate, never as a secret. Do not store anything that lets an attacker confirm a guess without paying the full derivation cost, and cap the attempts.
03
What can go wrong, and the control that answers it
Written before the client, so the controls land in the backend where both paths can rely on them.
Phone stolen, unlocked
Exposure
Vault readable
Control
Relock on backgrounding, memory wipe, remote revoke from any other signed-in session.
Phone stolen, locked
Exposure
Offline attack on stored files
Control
Argon2id derivation, attempt cap, no raw key on disk. Native adds the hardware gate on top.
Refresh token lifted
Exposure
Session hijack
Control
Short-lived access tokens, rotating refresh tokens, device binding, revocation list checked on every request.
Server or database breach
Exposure
Bulk disclosure
Control
Ciphertext only. Vault keys never leave the device, so the existing end-to-end guarantee is unchanged.
Removed teammate keeps reading
Exposure
Group leakage
Control
Membership drives the read rule; removal re-wraps the group key and revokes the old wrapped copies.
Key substitution during linking
Exposure
Interception of messages
Control
Both sides compare the key fingerprint out of band — a QR code or six words — before the first message.
Team code guessed or leaked
Exposure
Stranger inside the team
Control
High-entropy, single-use, expiring codes, and an admin approval before the join takes effect.
Curious administrator
Exposure
Reads member records
Control
Admins see records, never plaintext. Searches and links are logged without the value that was searched.
The one control that cannot be deferred: a revoked device must stop working within a minute, not when its token happens to expire.
04
Team discovery and device-to-device linking
Both entry methods you asked for, sharing one rule: nobody is findable outside a team they already belong to.
Invite-only directory
An admin invites by email; the member appears in the team directory with a name and a key fingerprint. Search is an exact match on user id, scoped to teams you already share, rate-limited, and returns nothing when no team is shared.
Team code
An admin issues a high-entropy code with an expiry and a single use. A member redeems it once to join the team and the code dies. Good for onboarding a room of people without collecting addresses.
The link, end to end
01
Find or redeem
Search a teammate by id, or join a team with a code.
02
Consent
The other member sees the request and accepts. No silent links.
03
Handshake
ECDH P-256 — the primitive the vault already uses. Only wrapped key material moves.
04
Verify
Both sides compare the fingerprint out of band. Revoke any time; the wrapped key dies with the link.
Guardrails that are not negotiable
- —No public member directory, ever — discovery requires a shared team.
- —No fuzzy search: exact id only, so the directory cannot be scraped.
- —Rate limits per actor and per target, with blocks and reports.
- —Every search logged with actor and timestamp, never with the searched value.
05
Phased rollout
Each phase ends in something a member can use, and each one leaves the next cheaper rather than more expensive.
00
Foundations
2–3 weeks
Device registry, rotating refresh tokens, revocation, team membership and the audit log. All backend; both paths depend on it.
Done when
A device can be registered, listed and killed from another session.
01
Store-ready build
3–4 weeks
Packaged iOS and Android builds, the local lock screen, and deep links straight into chat, calendar, contacts and documents.
Done when
A member installs, signs in once, and reopens with a passcode.
02
Team discovery and linking
2–3 weeks
Directory search, team codes, consent, fingerprint verification and the revocation screen.
Done when
Two members connect without exchanging anything over email.
03
Native clients
3–5 months
Swift and Kotlin clients on the same API, with operating-system-gated keys, push and background sync.
Done when
The shell can be retired without losing a feature.
Phases 00 to 02 are shared work: they serve the packaged build and the native clients identically. Only phase 03 is thrown away if you never go native — and by then you will know whether you need to.
06
Decisions to lock before code
Each of these changes the shape of the build. The default in the right column is what I would take.
Which path first
Default
Packaged build, with the native decision revisited after phase 02.
Who holds the store accounts
Default
Apple Developer and Google Play under the company, not a personal login.
Default join method
Default
Invite for existing teams, team code for onboarding new ones.
Relock timing
Default
Immediate on backgrounding; five minutes only when the OS reports a trusted lock screen.
Discoverability default
Default
Off. A member opts in before any teammate can find them.
Recovery on a new device
Default
Seed phrase, unchanged. No device-to-device transfer without it.
Confirm these and phase 00 starts on the backend, where the work is identical either way.
