Argon2id derives master key from zero user-secret entropy - add Mode B opt-in (F-A1)

[ehsan6sha]

Severity: HIGH (per audit findings fula-client-audit-findings.md — finding F-A1)

Bug

auth_service.dart:535-549 (FxFiles) derives the master encryption key with:

final input = '${_currentUser!.provider.name}:${_currentUser!.id}:$email';
await fula.deriveKey(context: 'fula-files-v1', input: utf8.encode(input));

Inside fula-crypto::hashing::derive_key_argon2id, the context bytes double as the salt (padded to 8 bytes if shorter). So the actual KDF is:

master_KEK = Argon2id(
  input  = "google:<sub>:<email>",
  salt   = "fula-files-v1\0...",   // constant, global
  m=64MiB, t=3, p=1
)

Every input component is a public identity attribute. Anyone who obtains a single artifact carrying (provider, sub, email) together — an OAuth ID token, a JWT, a crash dump, a leaked profile row — computes the master key directly in one Argon2id invocation (~0.5–1 s). No brute force, no probabilistic search. Argon2id's memory-hardness is wasted because there is no password.

Compounds with F-A3 (the global users-index is enumerable by hashed user_id, so an attacker who confirms a target is a Fula user can then derive their key).

Scope of this fix

Per user decision (2026-05-18, with consultation from Gemini and Codex advisors):

• Mode A — OAuth-only is unchanged for existing users. We do NOT run an auto-migration on the ~10K Mode-A users — the salt-only "improvement" is marginal (salt isn't secret) and a forced rotation has more downside than upside.
• Mode B — OAuth + seed (passphrase) is added as an opt-in path. Users tap "Add a password for stronger security" in Settings, set a seed, and the app re-wraps every per-file DEK from K_old (Mode A) to K_new (Mode B). After migration, K_new = Argon2id(input="provider:sub:email:seed", salt=per-user-random).
• Mode C — Seed-only (no OAuth) is out of scope for this release. Mode C requires a new server-side challenge-response auth endpoint (no OAuth to anchor identity) — substantial work that is best designed and shipped separately.

The Codex advisor also flagged that the audit's earlier note about "delete the chunks" in F-A5 was unsafe — that observation has already been applied to F-A5. For F-A1 the equivalent concern is migration safety under partial failure — addressed below by a staged migration with persisted state.

Design

Client side (FxFiles + fula-flutter FFI)

1. New FFI derive_key_with_salt(context: String, input: Vec<u8>, salt: Vec<u8>) -> Vec<u8> (additive). Backed by fula_crypto::hashing::derive_key_argon2id_with_salt(context, input, salt) -> [u8; 32]. The existing derive_key is left in place (Mode A users keep deriving as today).
2. auth_service.dart gains:
   • enableModeB(String seed) — runs the A→B migration with staged state:
     1. Read current K_old (Mode A).
     2. Generate per-user random 32-byte salt.
     3. Derive K_new = Argon2id("fula-files-v1-google-pw", "provider:sub:email:seed", salt).
     4. Persist derivationMigrationState = migrating_to_v2_mode_B + new salt to SecureStorage.
     5. Call FulaApiService.rotateAllBuckets(K_old, K_new) — rotates every bucket. Resumable: if killed mid-way, next enableModeB resumes from the last completed bucket.
     6. Verify a read with K_new succeeds across all buckets.
     7. Atomically persist keyDerivationVersion = 2_mode_B, then zeroize K_old.
   • signInModeB(String seed) — used on subsequent launches and new devices once profile is fetched.
3. Persistent state in SecureStorage:
   • keyDerivationVersion: 1_mode_A (default for all existing users) or 2_mode_B
   • derivationSalt (base64) — present only for Mode B
   • derivationMigrationState — transient, set during A→B rotation
4. Cross-device (Phase 2 in this issue — see below): server-side derivation profile lookup so a new device can fetch (mode, salt) on first sign-in.

Server side (fula-api)

Phase 2 — server-side derivation profile API for cross-device:

• Add derivation_profile: Option<DerivationProfile> field to the per-user bucketsIndex CBOR (additive — old clients ignore it).
• DerivationProfile = { mode: ModeTag, salt: [u8; 32], updated_at: u64 }. mode is either ModeA (legacy, no salt) or ModeB (with salt). salt is not a secret — its purpose is uniqueness, not confidentiality.
• Client POSTs the derivation profile alongside the existing bucketsIndex update on every Mode B sign-in / change.
• Server validates: one profile per authenticated user (JWT-scoped). Server cannot verify the BLAKE3 of the seed (it doesn't have the seed) — it simply trusts the client's claim. The worst a malicious client can do is publish wrong data for their own user, which is self-harm.

Recovery mnemonic (Phase 2)

24-word BIP39 mnemonic generated by the system at Mode B opt-in time. Stored ONLY on the user's device until shown, never persisted to disk after. UX per Gemini advisor:

• Partial verification (3 of 24 words at random positions) — not full re-type.
• Clear UI separation between "your password" (daily use) and "your recovery key" (backup).
• Hold-to-confirm full-screen red warning before enabling Mode B.

Migration safety guarantees

No existing Mode A user is affected. Mode A's KDF is unchanged. Existing users see no UI difference unless they explicitly opt in to Mode B in Settings.

Mode B opt-in is staged + resumable. The derivationMigrationState flag in SecureStorage ensures that if the app is killed mid-rotation:

• On next launch, the app sees migrating_to_v2_mode_B + both keys derivable (K_old via mode A, K_new via stored salt + the seed re-entered by the user on resume) → resumes rotation from the last-completed bucket.
• The keyDerivationVersion = 2_mode_B flag is set ONLY after a verify-read succeeds with K_new across all buckets.
• K_old is zeroized only AFTER keyDerivationVersion = 2_mode_B is persisted.

Forest sync prerequisite met: fula-api v0.5.4 (issue #12 fix, commit b63c58c) keeps forest user_metadata in sync during rotate_bucket — required for Mode A → Mode B migration's per-file DEK rewrap.

Tests

Failing-first tests (compile against post-fix API):

• fula-crypto: derive_key_argon2id_with_salt produces distinct outputs for distinct salts on the same input.
• fula-crypto: derive_key_argon2id_with_salt matches derive_key_argon2id when salt is the context bytes (back-compat).
• fula-flutter: FFI binding for derive_key_with_salt round-trips bytes correctly.

Phase 2 tests (after server + UI integration):

• Mode A → Mode B opt-in: data uploaded in Mode A still readable after migration.
• Cross-device: Device A migrates A→B; Device B signs in with seed, decrypts.
• Partial-failure resume: kill app mid-rotation; relaunch resumes and completes.
• Wrong-seed rejection on Mode B sign-in.

Phasing

Phase	Scope	Ships with
Phase 1 (this session)	derive_key_argon2id_with_salt in fula-crypto + FFI; service-layer enableModeB / signInModeB skeleton in auth_service.dart (no UI polish yet); tests	fula-api 0.5.5 + a non-user-facing Mode B beta hook in FxFiles
Phase 2	Server-side derivation profile API (cross-device); FxFiles UI screens (tier-action layout, partial mnemonic verification, less-secure / recommended labels per Gemini); recovery flow; full-screen Mode-B warnings; opt-in entry point in Settings	Follow-up release

Phase 1 does NOT expose Mode B to end users yet — the wiring lands without UI so the crypto + service layer can be unit-tested and reviewed in isolation. Phase 2 ships the UX once the underlying mechanism is validated.

References

• Audit finding F-A1 in fula-client-audit-findings.md
• Gemini advisor UX review (2026-05-18): tier-action layout, partial mnemonic verification, "yellow shield" Mode A warning, server-stored derivation profile for cross-device
• Codex advisor correctness review (2026-05-18): server-stored salt is the right call; staged migration with persisted state; derive_key_with_salt FFI rather than encoding salt in input; Mode C requires a new auth endpoint (scope-out for this release)

[ehsan6sha]

Phase 1 shipped in commit 6dfedb9: derive_key_argon2id_with_salt in fula-crypto + derive_key_with_salt FFI in fula-flutter, with 7 unit tests covering distinct-salts, distinct-contexts, determinism, short-salt rejection, and explicit non-equivalence to the legacy function. Mode A users are unaffected (legacy derive_key is unchanged).

Phase 1.5 (blocked on dev env): flutter_rust_bridge_codegen generate failed because the dev machine lacks LLVM / libclang. Once LLVM is installed (or codegen is run on a CI box that has it), the Dart binding deriveKeyWithSalt will appear in packages/fula_client/lib/src/api/encrypted.dart and the FxFiles app can call it.

Phase 2 (UI + server-side cross-device profile): scoped per the issue body. Pending Phase 1.5.

[ehsan6sha]

2026-05-18 — scope revision (per maintainer guidance)

Earlier "Mode B opt-in in Settings + cross-device server profile + per-user salt" design is scrapped. New simplified scope:

Goals (revised)

• Nothing sensitive on the server. No per-user salt, no derivation profile, no opt-in flag. Server has no signal of which mode any given user is in.
• Existing users unchanged forever. All Mode A users (today's ~10K) continue using KDF = Argon2id("fula-files-v1", "provider:sub:email") exactly as today. Zero migration, zero touch.
• New users get a choice at sign-up: OAuth alone (Mode A — less secure) OR OAuth + Password (Mode B — recommended). Both paths are first-class. No mode is hidden.
• No FFI changes required. Existing deriveKey(context, input) is reused; Mode B simply changes the input string to append the password.
• The derive_key_argon2id_with_salt / derive_key_with_salt functions shipped in commit 6dfedb9 are unused on the FxFiles path. They stay in the codebase as harmless additions; revisit / remove in a future cleanup pass.

Sign-up UX (FxFiles, new users only)

On the first-time-sign-in screen:

┌─────────────────────────────────────────────┐
│  Welcome to FxFiles                         │
│                                             │
│  Sign in with Google + Password (RECOMMENDED) │
│  ────────────────────────────────────────── │
│  Sign in with Google                        │
│                                             │
│  (Apple equivalents below on iOS)           │
└─────────────────────────────────────────────┘

• Mode B (recommended): OAuth flow → prompt for a password → derive KDF = Argon2id("fula-files-v1-google-pw", "provider:sub:email:password") → persist keyDerivationVersion: 2_mode_B in SecureStorage.
• Mode A: OAuth flow only → derive KDF = Argon2id("fula-files-v1", "provider:sub:email") (today's path) → persist keyDerivationVersion: 1_mode_A.

Gemini's earlier UX advice still applies — make Mode B the prominent default, keep Mode A as a secondary "less secure" option.

Detection on a new device (Mode B user signing in on iOS after Android)

auth_service.dart sign-in flow:

1. OAuth completes → app has (provider, sub, email).
2. App checks SecureStorage for keyDerivationVersion. If absent → first-time-on-this-device path.
3. First-time path: try Mode A KDF first. Attempt to decrypt the master forest.
4. If decrypt succeeds → user is Mode A. Persist keyDerivationVersion: 1_mode_A.
5. If decrypt fails with an AEAD error → prompt user "Enter the password you set on your other device". Re-derive with Mode B KDF. Retry decrypt.
6. If Mode B decrypt succeeds → persist keyDerivationVersion: 2_mode_B. From now on, this device also publishes userKey_v2 (F-A3 hook).
7. If both Mode A and Mode B (with the entered password) fail → surface "wrong password / no data found" to the user.

No server lookup needed for the "what mode is this user" decision — the decrypt outcome IS the signal.

Existing-user upgrade (deferred)

A future "Settings → Add a password to your account" flow would rotate a Mode A user's data to Mode B via rotate_bucket. Not in scope for this release. Existing users on Mode A keep their current key forever unless we add the upgrade path later.

Tests

• New user picks Mode A → KDF matches today's bytes (regression check against the existing v1 path).
• New user picks Mode B → KDF input includes the password; different password → different key.
• Mode B user on a new device: Mode A decrypt fails → prompt → Mode B decrypt succeeds → key cached, mode persisted.
• Mode B user on a new device with wrong password: error surfaces cleanly without locking the account.
• The keyDerivationVersion flag persists across app restarts; sign-in skips the fall-through.

What ships in fula-api / fula-flutter

• Nothing new on the Rust side beyond the already-shipped derive_key_argon2id_with_salt (which the FxFiles path doesn't use, but is harmless). All F-A1 work is FxFiles auth_service.dart logic + new sign-up UI.
• The GitHub Actions release flow regenerates Dart bindings as today. FxFiles bumps fula_client to the new release version after publish.

References

• Maintainer guidance 2026-05-18: nothing sensitive on server; both paths first-class
• Gemini advisor UX review 2026-05-18: tier-action layout, partial mnemonic verification (still applies for recovery codes)
• Codex advisor review 2026-05-18: confirms detection-via-decrypt-failure is safe; no server-side mode flag is the right call
• Audit finding F-A1 in fula-client-audit-findings.md

[ehsan6sha]

2026-05-18 — advisor-integrated revision

Codex + Gemini independently flagged a must-fix-before-implementation gap in the earlier "decrypt-fall-through" design: a new device could overwrite an existing user's data by accidentally picking Mode B at sign-up. Revised flow integrates a Discovery Phase + First-Root CAS:

Discovery Phase (mandatory, runs after OAuth on every new-device sign-in)

1. OAuth completes → app has (provider, sub, email).
2. Compute hashed_user_id_v1 = BLAKE3("fula:user_id:" || user_id)[..16].
3. Probe: does the gateway report any existing data for this user?
     - Cheapest probe: GET /v1/users/me/has-data → boolean (server-side: any bucket registered to hashed_user_id_v1).
     - Fallback: try to fetch the user's bucketsIndex CID.
4a. If NO existing data:
     - Truly new user. SHOW sign-up choice screen (Mode A vs Mode B). Proceed to "First-Root Write".
4b. If existing data found:
     - Existing user. SKIP sign-up choice screen entirely.
     - Try Mode A decrypt of any one existing forest envelope (a "probe object" with known-good AAD).
     - If Mode A succeeds → user is Mode A. Persist locally. Done.
     - If Mode A fails with AEAD-tag-mismatch → prompt "Enter your password" → try Mode B → persist if works.
     - If both fail → "wrong password" error, NEVER auto-fall-through to sign-up.
5. Network / operational errors during the probe → show "Sync error, retry" — DO NOT collapse into "wrong password" or a fresh sign-up screen.

First-Root Write (Mode A or Mode B sign-up)

After the mode-choice screen, the app immediately writes a minimal authenticated forest envelope so subsequent devices can probe it via the Discovery Phase. This eliminates the "empty account on Device 1, fresh sign-up on Device 2" race that would split-brain the account.

• The first-root write uses conditional PUT with If-None-Match so two simultaneous sign-ups can't both succeed silently.
• The minimal envelope is a single zero-byte forest header AEAD-authenticated with the chosen-mode KDF output. Subsequent uploads append normally.

Canonical KDF input encoding (Codex)

Raw colon concatenation ("provider:sub:email:password") is ambiguous — a password containing : would collide. Use length-prefixed bytes:

input_bytes = NFKC(u32_le(len_provider)
                 || provider
                 || u32_le(len_sub)
                 || sub
                 || u32_le(len_email_normalized)
                 || lowercase(email)
                 || u32_le(len_password)        // Mode B only
                 || NFKC(password))             // Mode B only

• email_normalized = lowercase(email) (Apple may return mixed case).
• password = NFKC-normalized to defeat homoglyph drift.

Drop the -google- from the context tag (other providers exist):

• Mode A: context = "fula-files-v2-mode-a"
• Mode B: context = "fula-files-v2-mode-b"

(Mode A v2 context differs from today's "fula-files-v1" so EXISTING users continue to use the legacy "fula-files-v1" derivation. The v2 contexts are reserved for new sign-ups.)

Recovery mnemonic (Mode B)

24-word BIP39 mnemonic generated at Mode B sign-up. Per Gemini's UX advice:

• Shown ONCE on a full-screen "save your recovery phrase or risk losing access" screen.
• Partial verification (3 of 24 words at random positions) before sign-up completes.
• "Forgot password?" flow on subsequent sign-in goes to mnemonic-entry screen.

Mnemonic-derived seed gates a second KDF path that recovers the master key; mnemonic is never sent to the server.

Sign-up UX (Gemini)

• Primary button: "Protect with Password" — enhanced E2E.
• Secondary link: "Skip Password" — standard E2E.
• Frame as "Standard" vs "Maximum" security, NOT "less secure" warning.
• Visuals: blue shield for Standard, gold/purple shield for Maximum.

Existing Mode A users

Untouched. Their device's SecureStorage has no v2 flag, no v2 derivation context. They keep deriving with Argon2id("fula-files-v1", "provider:sub:email") forever. A future "Settings → Add a password" feature would rotate them — out of scope for this release.

Edge case: existing Mode A user with no uploaded data

Codex flagged this as a split-brain risk. Resolution: every sign-up (Mode A or Mode B) writes a minimal authenticated first-root envelope (above). So an "empty Mode A account" still has a probe object the Discovery Phase can read. Device 2 can never accidentally write a fresh Mode B root over it — the conditional PUT with If-None-Match fails on the second writer.

Operational error vs wrong-password — clear separation

A specific UI requirement: AEAD-tag-mismatch is the ONLY trigger for the "wrong password" path. Any other failure (404, 500, network, parse error) takes the user to a "Sync error, retry" screen with no password prompt. Codex flagged this explicitly.

Tests (failing-first)

• New user picks Mode A → KDF bytes match the v2-mode-a canonical encoding.
• New user picks Mode B → KDF input includes the canonicalized password.
• Discovery probe with NO existing data → sign-up choice shown.
• Discovery probe WITH existing Mode A data → no choice shown; Mode A restore.
• Discovery probe with existing Mode B data → password prompt shown.
• First-root CAS: two simultaneous sign-ups → exactly one wins.
• Canonical encoding: password with : (e.g., "pass:word") derives same key as a different password that would collide under naive concatenation.
• NFKC normalization: visually-identical passwords typed with different Unicode codepoints derive the same key.
• Operational error during probe (gateway 503) → "Sync error" screen, NEVER falls through to password prompt.

Scope split

Piece	Where	This session?
KDF context tags v2-mode-a / v2-mode-b	fula-crypto + FxFiles auth_service.dart	Update issue, defer to FxFiles work
Canonical length-prefixed encoding helper	fula-crypto	Could ship; small
Discovery probe endpoint GET /v1/users/me/has-data	fula-cli (new)	Could ship; small
First-root CAS write	fula-client (encryption.rs)	Substantial; defer
Recovery mnemonic UI	FxFiles	Defer
Sign-up screen, "wrong password" UX	FxFiles	Defer

The fula-api-side pieces (Discovery endpoint + canonical-encoding helper) can ship in this release. The FxFiles UI + first-root CAS is the bulk of the work and is its own follow-up.

References

• Maintainer guidance 2026-05-18: both modes first-class for new users; existing users unchanged
• Codex review 2026-05-18: must-fix discovery phase, canonical encoding, first-root CAS, operational-vs-wrong-password split
• Gemini review 2026-05-18: discovery before mode-choice, mandatory recovery mnemonic, primary-Mode-B UX
• Audit finding F-A1 in fula-client-audit-findings.md

[ehsan6sha]

2026-05-18 — final design (post-advisor review)

The earlier "header-based" / "separate userKey_v2 endpoint + dual-publish" designs are scrapped. After consulting Gemini, Codex, and Copilot, and reviewing the actual code (gateway only DECODES JWTs; the JWT issuer is a separate team-owned service that signs with the shared HS256 secret), the design adopted is:

"Seed IS the user" — effective_user_id in the JWT sub

The user's seed never leaves the client. The system has no concept of "alice" or "bob" — only effective_user_id. Whoever can compute a given effective_user_id IS that user.

• Mode A (existing users; unchanged forever): JWT sub = oauth_sub exactly as today. Identity-derivable. Existing users continue with no migration.
• Mode B (new option for new users — OAuth + seed): client computes the JWT sub locally; issuer signs after verifying OAuth + the client's proof-of-seed-knowledge (Ed25519 signature over a challenge).
• Mode C (new — seed-only, no OAuth): client computes the JWT sub locally; issuer signs after verifying the client's proof-of-seed-knowledge. No OAuth identity involved.

The gateway (fula-cli) is unchanged — it continues to treat the JWT sub opaquely. Because Mode B / Mode C sub values are seed-derived (16-byte BLAKE3 hashes of high-entropy input), they are non-enumerable from the published users-index CBOR. This closes F-A3 naturally for Mode B / Mode C users. Mode A users remain enumerable, by accepting that they opted out of the seed.

Derivation specification

DOMAIN_MODE_B      = b"fula:effective-uid:v2:mode-b"
DOMAIN_MODE_C      = b"fula:effective-uid:v2:mode-c"
DOMAIN_SIGNING_KEY = b"fula:signing-key:v2"

effective_user_id_b(provider, oauth_sub, seed) =
    BLAKE3(DOMAIN_MODE_B
        || u32_le(len(provider))           || provider
        || u32_le(len(oauth_sub))          || oauth_sub
        || u32_le(len(NFKC(seed))))        || NFKC(seed)
        )[..16]

effective_user_id_c(seed) =
    BLAKE3(DOMAIN_MODE_C
        || u32_le(len(NFKC(seed)))         || NFKC(seed)
        )[..16]

signing_seed(seed) =
    BLAKE3_derive_key(DOMAIN_SIGNING_KEY, NFKC(seed))[..32]
ed25519_keypair = Ed25519::from_bytes(signing_seed)

Canonicalization rules (per Codex):

• Length-prefixed (u32 LE) byte concatenation — defends against separator-injection ambiguity.
• Seed: NFKC-normalized. Visually-identical passwords typed with different Unicode codepoints produce the same id.
• OAuth sub: opaque bytes, NOT normalized. IDP-issued opaque identifier — normalizing would alter semantics.
• Domain tags ensure user-id and signing-key derivations are independent functions of the seed.

Shipped in this repo (commit 7fa2f32)

• fula_crypto::effective_user_id module with three functions:
  • compute_effective_user_id_mode_b(provider, oauth_sub, seed) -> [u8; 16]
  • compute_effective_user_id_mode_c(seed) -> [u8; 16]
  • derive_signing_seed_from_seed(seed) -> [u8; 32]
• fula-flutter FFI exports (Dart bindings regenerated by CI on next fula_client publish).
• 18 unit tests covering determinism, domain separation, NFKC normalization, separator-attack resistance, Ed25519 round-trip.
• unicode-normalization workspace dep added.

fula-cli (the gateway) is untouched — no changes were needed. ef56a7a (the earlier "userKey_v2 + dual-publish CBOR" design) was reverted in 9117250 as superseded by this design.

Issuer-side work (NOT in this repo — pinning-service / wherever JWTs are minted today)

This is the work the maintainer needs to add to the team's JWT-issuing service.

Storage

A small registry: effective_user_id_hex → (mode, public_key, registered_at, last_used_at).

• effective_user_id_hex: 32-character lowercase hex (the BLAKE3-16 output).
• mode: "B" or "C".
• public_key: 32-byte Ed25519 public key.

For Mode B, ALSO record the original OAuth identity (provider, oauth_sub) so an account-recovery / audit query can find it. Optional but recommended.

New endpoints

POST /auth/register-mode-b — first sign-up via Mode B.

Request body:

{
  "provider": "google",
  "oauth_token": "<google id token>",
  "effective_user_id": "<32 hex chars>",
  "public_key": "<base64 32 bytes>",
  "challenge": "<base64 32 bytes>",     // random nonce the client generated
  "challenge_signature": "<base64 64 bytes>" // Ed25519 signature over the challenge
}

Server flow:

1. Verify the OAuth token with Google/Apple (existing flow).
2. Verify the Ed25519 signature on challenge using the supplied public_key. Proves the client holds the private key.
3. Look up effective_user_id in the registry:
   • If absent: register (effective_user_id → "B", public_key, oauth_sub). Continue.
   • If present and matches the supplied public_key: idempotent — re-registration is fine.
   • If present but public_key differs: reject (would silently take over an existing account).
4. Issue HS256 JWT with sub = effective_user_id, signed with the existing JWT_SECRET. Standard scopes / expiry as today.

POST /auth/register-mode-c — first sign-up via Mode C (no OAuth).

Same as above minus provider / oauth_token. Rate-limit per IP to prevent spam-creating namespaces.

POST /auth/challenge — issue a nonce for sign-in.

Request body:

{ "effective_user_id": "<32 hex chars>" }

Server flow:

1. Look up effective_user_id in the registry. If absent: return 404.
2. Generate a cryptographic random nonce (32 bytes). Stash it in a short-TTL cache (e.g., Redis) keyed by (effective_user_id, nonce) with a 60-second expiry.
3. Return { "challenge": "<base64 nonce>" }.

POST /auth/sign-in — verify signed challenge and issue JWT.

Request body:

{
  "effective_user_id": "<32 hex chars>",
  "challenge": "<base64 nonce>",
  "challenge_signature": "<base64 64 bytes>"
}

Server flow:

1. Look up effective_user_id → public_key. 404 if absent.
2. Look up the nonce in the cache. 401 if not present or expired.
3. Verify the Ed25519 signature on the nonce using the stored public_key. 401 if bad.
4. Invalidate the nonce (single-use).
5. Issue HS256 JWT with sub = effective_user_id.
6. Update last_used_at.

Squatting / takeover defenses

Per Copilot's review: the registration endpoint must reject a re-registration that supplies a different public_key for an already-registered effective_user_id. Squatting is otherwise infeasible because:

• For Mode B: effective_user_id depends on (oauth_sub, seed). An attacker without the seed cannot compute a victim's eventual id (128-bit guess).
• For Mode C: same logic, using just the seed.

The registry's per-id public-key binding is the load-bearing protection.

Mode A interaction

Untouched. Existing Mode A users keep getting JWTs from the existing OAuth-only flow. No client changes. Their JWT sub = oauth_sub, which is enumerable but acceptable since they opted out of seed-based identity.

FxFiles (client) work

Skeleton flow once the FFI bindings are regenerated by CI:

// On sign-up screen:
// (A) Continue with Google → existing flow, no changes.
// (B) Continue with Google + Password:
final oauthIdentity = await GoogleSignIn.signIn();
final password = await promptPassword();
final eid = await fula.computeEffectiveUserIdModeB(
  provider: 'google',
  oauthSub: oauthIdentity.id,
  seed: password,
);
final signingSeed = await fula.deriveSigningSeed(seed: password);
final keyPair = ed25519.SigningKey.fromBytes(signingSeed);
final challenge = generateRandomBytes(32);
final signature = keyPair.sign(challenge);
final jwt = await issuerClient.registerModeB(
  provider: 'google',
  oauthToken: oauthIdentity.idToken,
  effectiveUserId: hex.encode(eid),
  publicKey: base64.encode(keyPair.publicKey.bytes),
  challenge: base64.encode(challenge),
  challengeSignature: base64.encode(signature),
);
// Use jwt for all subsequent gateway calls.
// Persist: keyDerivationVersion=2_mode_B
// DO NOT persist the seed itself.

// (C) Continue with Passphrase only:
final passphrase = await promptPassphrase();
final eid = await fula.computeEffectiveUserIdModeC(seed: passphrase);
// ... same shape, calls registerModeC instead.

// On subsequent app launches:
// - Read keyDerivationVersion from SecureStorage.
// - For Mode A: existing flow.
// - For Mode B/C: re-prompt for the seed, derive signing key, do
//   challenge-response with the issuer to get a fresh JWT.

Master KEK derivation for Mode B/C (also F-A1 fix)

The audit's F-A1 finding was about the MASTER ENCRYPTION KEY being derived from public attributes. Under the redesign, master-KEK derivation follows the same input as the user-id but with a different domain — so a seed-leak doesn't compromise content via the user-id and vice versa:

master_KEK_mode_b = Argon2id(
    context = "fula-files-v2-mode-b",
    input   = u32_le(len(provider))   || provider
           || u32_le(len(oauth_sub))   || oauth_sub
           || u32_le(len(NFKC(seed))) || NFKC(seed),
    salt    = blake3("fula:kek-salt:v2:mode-b" || effective_user_id_b)[..16]
)

Mode C analogous, with mode-c domain. Mode A unchanged.

This re-uses the existing derive_key_argon2id_with_salt function shipped in 6dfedb9. FxFiles will call it with the canonical inputs.

Scope sequencing

Item	Where	Status
Crypto primitives + tests	fula-crypto	✓ Shipped 7fa2f32
FFI exports	fula-flutter	✓ Shipped 7fa2f32 (Dart bindings regen by CI)
Issuer registry storage	pinning-service (separate repo)	TODO (maintainer)
Issuer endpoints (register / challenge / sign-in)	pinning-service	TODO (maintainer)
FxFiles sign-up UI (Mode B + Mode C buttons)	FxFiles	TODO (maintainer)
FxFiles auth_service.dart challenge-response flow	FxFiles	TODO (maintainer)
fula_client package republish	CI on next release	TODO (maintainer)

References

• Gemini advisor UX review 2026-05-18: tier-action layout, vault labeling, recovery mnemonic
• Codex advisor correctness review 2026-05-18: length-prefixed encoding, NFKC on seed only (not oauth_sub), Ed25519 proof-of-knowledge, registry uniqueness
• Copilot advisor security review 2026-05-18: squatting defense via per-id public-key binding, issuer-compromise risk analysis
• Built-in advisor (full transcript review): converged scope, three decisions surfaced to maintainer
• Maintainer decisions 2026-05-18: option Walkability #3 (cryptographic proof), separate vaults per mode (no cross-mode merge)

[ehsan6sha]

Issuer-side endpoints shipped in pinning-service commit 25280a1:

• POST /auth/register-mode-b (OAuth + seed)
• POST /auth/register-mode-c (seed-only)
• POST /auth/challenge (issue nonce)
• POST /auth/sign-in (verify signed nonce, mint JWT)

New table seed_users (effective_user_id PK, mode, public_key, oauth_sub, provider). Migration runs inside existing initializeDatabase. JWTs minted via existing generateJwtApiKey (HS256, same shape, sub = effective_user_id_hex). Fula-cli unchanged.

15 vitest cases cover: happy path, idempotent re-register, squatting (409 PUBLIC_KEY_MISMATCH), bad signatures, cross-purpose/cross-user signature replay, challenge replay, challenge tampering, no-prior-challenge, malformed inputs. Tests skip when Postgres unreachable.

Remaining TODO at maintainer:

• FxFiles auth_service.dart to call the new endpoints (sign-up screen, sign-in flow, Mode-C recovery mnemonic UX).
• Free-tier-per-OAuth-sub mitigation (currently each Mode B/C vault gets fresh default credits — discussed but deferred per scope).

[ehsan6sha]

Final-audit finding #1 — Registration replay (CRITICAL)

POST /auth/register-mode-b and POST /auth/register-mode-c accept a client-generated challenge in the request body. The server verifies the Ed25519 signature against that client challenge but never records the challenge as single-use. Anyone who captures a valid registration request body can replay it indefinitely to mint fresh JWTs.

Severity is amplified by DT-1 (JWTs intentionally have no exp claim): every replay produces a perpetually-valid JWT. Rotating JWT_SECRET is the only way to invalidate them en masse.

• Mode C is worst — no OAuth-token-expiry bound. The replay window is forever.
• Mode B is bounded by the OAuth token's TTL (≈ 1 hour for Google ID tokens), but every replay within that window mints another no-exp JWT, persisting beyond the OAuth window.

Fix: extend the existing POST /auth/challenge to accept a purpose parameter ('sign-in', 'register-mode-b', 'register-mode-c'). The two register endpoints must consume a server-issued challenge (via challengeStore.takeIfValid(uid, 'register-mode-{b,c}')) instead of accepting client nonces. FxFiles signInModeB / signInModeC add the challenge round-trip before signing.

Test: capture a valid register-mode-c request body, replay it after the first call succeeds; second call must return 401 CHALLENGE_INVALID.

[ehsan6sha]

Final-audit finding #2 — NFKC inconsistency (CRITICAL)

_canonicalKekInputModeB / _canonicalKekInputModeC in FxFiles/lib/core/services/auth_service.dart build the Argon2id input from utf8.encode(seed) — raw, NOT NFC-normalized. The fula-crypto FFI's compute_effective_user_id_mode_b/c and derive_signing_seed_from_seed apply .nfc() to the seed.

Consequence: a Mode B user typing a non-ASCII password on Device A (NFC-composed) and Device B (NFD-decomposed via a different IME) computes:

• Same effective_user_id → same vault on the server.
• Different master KEKs → cross-device decryption fails silently.

Mode C BIP39 mnemonics are ASCII-only so are unaffected. Mode B users with ASCII passwords (overwhelming majority) are also unaffected — but the failure mode for affected users is permanent data loss for their Device B view.

Documentation bug also caught: my commit messages and the audit transcript use "NFKC", but the Rust code calls .nfc() (canonical-composed NFC, not the compatibility-decomposing NFKC). Both are fine; the code is consistent with itself; the docs should say NFC for accuracy.

Fix: add the unicode_normalization Dart package (pure Dart, no native deps) and NFC the seed in _canonicalKekInputModeB/C before encoding.

Test: derive Mode B KEKs from "caf\u{00E9}" (precomposed) and "cafe\u{0301}" (decomposed); they must be byte-equal after the fix.

[ehsan6sha]

Final-audit finding #3 — Mode B signing key not OAuth-bound (CRITICAL)

derive_signing_seed_from_seed(seed) takes only the seed (password/passphrase). The same password produces the same Ed25519 keypair regardless of OAuth identity.

Exploitable scenario (Codex advisor 2026-05-18):

1. Alice signs up Mode B with provider=google, oauth_sub=alice_sub, password="P@ssw0rd".
2. Alice's effective_user_id_A = BLAKE3(... || alice_sub || "P@ssw0rd" || ...).
3. Alice's signing keypair = f(NFC("P@ssw0rd")).
4. Bob signs up Mode B with provider=google, oauth_sub=bob_sub, password="P@ssw0rd" (same common password).
5. Bob's effective_user_id_B differs (different oauth_sub).
6. Bob's signing keypair is identical to Alice's (same password → same key).
7. Bob's effective_user_id_B lands in the public global users-index CBOR.
8. Alice reads it, runs /auth/sign-in with effective_user_id_B + Alice's signing key.
9. Server's stored public key for effective_user_id_B equals Alice's public key.
10. Server mints a JWT for Bob's vault to Alice.

For Mode A this attack is intrinsically impossible (KDF input includes (provider, sub, email)). For Mode B it's possible because the signing key is derived from the seed alone.

Fix: bind Mode B's signing seed to (provider, oauth_sub, seed). Concretely, in FxFiles _deriveSigningKeypair for Mode B, pass a composed string (e.g., "mode-b\x00${provider}\x00${oauthSub}\x00${NFC(password)}") to fula.deriveSigningSeed so the resulting Ed25519 key is unique per (OAuth identity, password) tuple. Mode C stays seed-only (no OAuth to bind to).

Test: two Dart-side derivations with provider="google", oauth_sub=A vs provider="google", oauth_sub=B, same password — public keys must differ after the fix.

[ehsan6sha]

Final-audit finding #4 — has_mode_a flag is misleading + unused (IMPORTANT)

The has_mode_a field on the register-mode-b response is computed by counting seed_users rows with the same oauth_sub. If count > 1 → true. This actually means "another seed-based vault exists for this OAuth identity", not "a Mode A account exists". Mode A users live in webui_users keyed by SHA-256(email), never in seed_users.

Also: the FxFiles UI receives has_mode_a in the IssuerClient.SeedAuthResult but does not surface it to the user — so even if the flag fired correctly, no warning would appear. Gemini advisor flagged the "Mode A user accidentally creates a Mode B vault and thinks Device 1 was wiped" UX risk.

Fix:

1. Server-side: compute has_mode_a correctly by joining on webui_users.user_id = sha256(lowercase(email)) for the same OAuth email claim. (Or use an explicit oauth_sub_index column once added.) Until that's available, return null rather than a possibly-misleading boolean.
2. Client-side: surface a warning on the Mode B success path when has_mode_a == true: "You have an existing Standard (Mode A) vault on this Google account. The new Maximum-Security vault you just created is SEPARATE — your existing files are still on Device 1 but won't appear here."

Test: register a Mode A user via /auth/google, then /auth/register-mode-b for the same email under a Mode B vault; the response's has_mode_a must be true.

[ehsan6sha]

Final-audit finding #5 — Downstream encrypted_email = NULL audit (IMPORTANT)

Mode B / Mode C webui_users rows are inserted with encrypted_email = NULL. Any downstream code that joins on email, computes initials from email, displays "signed in as ..." copy, or assumes a non-null encrypted_email may break or misattribute for these users.

Maintainer's proposed fix: instead of leaving encrypted_email = NULL, store effective_user_id_hex in the encrypted_email slot for Mode B/C users (since "email is essentially userid all over the system").

Plan:

1. First grep every read of webui_users.encrypted_email (and the legacy email column) across pinning-service to identify call sites that would behave differently for non-NULL synthetic values.
2. Verify the maintainer's suggestion has no side effect (e.g., wallet linking that compares email format; credit-history that returns email in API response and would now leak the synthetic value).
3. If grep is clean → store effective_user_id_hex directly in encrypted_email for Mode B/C rows (no encryption necessary since the value is already opaque/server-stored).
4. If grep surfaces a path that would break → keep NULL and add per-call-site null handling instead.

Test: insert a Mode C user, then exercise every code path that reads encrypted_email (credit lookup, wallet listing, pin attribution, profile delete) — no path should crash or produce malformed output.