SecureIDsafeSECUREIDsafe
Back to site
Planning document · decision record

Two ways to put SecureIDsafe in a pocket

Chat, calendar, contacts and documents on a phone — signed in once, then reopened with a passcode. Plus team discovery and device-to-device linking. Here is what each delivery path really buys, and where the security actually lives.

Two store apps

Both paths produce a separate iOS and Android listing.

OS passcode gate

Reachable from native clients only — never from a web shell.

Shared backend

Devices, revocation and team linking serve both paths.

Nothing in this document has been built — it is a plan, not a release.

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.

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.

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.

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.

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.

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.

  1. 01

    First run

    Email and password through the existing platform login. Nothing new to trust, nothing new to store.

  2. 02

    Seed check

    If the Genesis Ritual is unfinished it finishes here. Recovery is never optional on a phone.

  3. 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.

  4. 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.

  5. 05

    Relock

    On backgrounding, inactivity or a failed attempt, the key is wiped from memory. The passcode derives the device key again and unwraps.

  6. 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.

01

Which path first

Default

Packaged build, with the native decision revisited after phase 02.

02

Who holds the store accounts

Default

Apple Developer and Google Play under the company, not a personal login.

03

Default join method

Default

Invite for existing teams, team code for onboarding new ones.

04

Relock timing

Default

Immediate on backgrounding; five minutes only when the OS reports a trusted lock screen.

05

Discoverability default

Default

Off. A member opts in before any teammate can find them.

06

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.