From a6bc29d5b3ffa38277ce584b5e9b38bf89c19753 Mon Sep 17 00:00:00 2001
From: thestreamcode <dev@mikesoft.it>
Date: Sat, 1 Aug 2026 22:44:58 +0200
Subject: [PATCH 1/2] fix(generator): honor "exclude similar characters" for
 guaranteed characters

The password generator filters look-alike characters out of the pool it draws
from, but the one character it guarantees per selected set was picked from the
unfiltered alphabet. A generated password could therefore still contain i, l, 1,
L, o, 0 or O right after the user excluded them; a digits-only password could be
returned containing 0 or 1.

Filter every alphabet up front and build the draw pool from the filtered sets, so
the guarantee and the pool cannot disagree. Empty alphabets are dropped rather
than sampled, and the guaranteed prefix is capped at the requested length so the
function can no longer return more characters than asked for (reachable only
through direct API use: the in-app slider starts at 8).

Also document the accepted cryptographic trade-offs in docs/security.md under a
new "Known Limitations" section - shared AES/HMAC key, PBKDF2-SHA1 backup KDF,
six-digit master PIN keyspace, no unlock throttling, opt-in screenshot
protection, transition-based auto-lock, Android 13+ clipboard previews and the
trusted OTA channel. No cryptographic behavior changed and no stored data format
was touched.

Remove the unimported Divider component and the unused JSX.IntrinsicElements
augmentation, and correct the nativewind-env.d.ts header: the className
augmentations serve react-native-web, not NativeWind, which is not a dependency.

Verified with bun run verify: format, typecheck, lint, 195 tests across 29
suites, expo-doctor 20/20.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .gitignore                                   |  4 +-
 AGENTS.md                                    |  5 +-
 CHANGELOG.md                                 | 43 ++++++++++++++
 docs/security.md                             | 57 ++++++++++++++++++
 nativewind-env.d.ts                          | 14 ++---
 src/__tests__/services/CryptoService.test.ts | 62 ++++++++++++++++++++
 src/components/ui/divider.tsx                | 20 -------
 src/services/crypto/cryptoService.ts         | 45 ++++++++------
 src/services/utils/clipboardService.ts       |  6 +-
 9 files changed, 204 insertions(+), 52 deletions(-)
 delete mode 100644 src/components/ui/divider.tsx

diff --git a/.gitignore b/.gitignore
index 87c9470..ee27eb2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -59,6 +59,7 @@ test-passwords.json
 .claude/
 .opencode/
 .agents/
+.codex/
 
 # Testing
 coverage/
@@ -69,6 +70,3 @@ build/
 *.apk
 *.aab
 *.ipa
-
-# Claude Code local settings
-.claude/settings.local.json
diff --git a/AGENTS.md b/AGENTS.md
index 6a93950..7c3716b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -56,6 +56,9 @@
 - Local secrets live in `.secrets/` and must never be committed.
 - The project requires no local environment variables. Keep `.env.example` non-secret, never put credentials in `EXPO_PUBLIC_*`, and use EAS/GitHub secret stores for automation credentials.
 - Treat imported files and KDF metadata as untrusted. Preserve backup/file-size and KDF-cost bounds when changing validation or crypto code.
+- Password generation must apply every enabled option to every character set. The set that guarantees one character per class is the easy place to reintroduce an excluded character; keep it filtered and keep `src/__tests__/services/CryptoService.test.ts` generator coverage green.
+- Read `docs/security.md` "Known Limitations" before touching crypto. The shared AES/HMAC key and the PBKDF2 backup KDF are known, documented trade-offs, **not** bugs to fix in place: changing either silently makes every existing vault and every exported `KS1-PW1` backup undecryptable. Any change there needs a new format version plus a migration that runs in an authenticated session.
+- Do not alter the KS1/KS1-PW1 payload layout, the storage keys in `storageService.ts`, or the default KDF parameters of an existing vault. Vaults carry their own KDF parameters, so new capabilities (a longer master password, for instance) can be added without breaking old data — prefer that route.
 - Persist encrypted storage mutations before updating decrypted caches. Reset only Keysoft-owned keys; do not use `AsyncStorage.clear()`.
 - Clear backup passwords/ciphertext from UI state and remove temporary export files after sharing.
 
@@ -102,7 +105,7 @@
 - `README.md` is the public project overview and setup guide.
 - `CHANGELOG.md` tracks notable release and unreleased changes.
 - `docs/architecture.md` documents system structure and data flow.
-- `docs/security.md` documents the cryptographic and storage model.
+- `docs/security.md` documents the cryptographic and storage model, plus the accepted trade-offs under "Known Limitations".
 - `docs/development.md` documents local workflow, coding standards, and verification.
 - `docs/release.md` documents release readiness, Android permissions, and security checks.
 - Update `README.md`, `CHANGELOG.md`, and the relevant `docs/` file for significant changes.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0d1ad69..00b929f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,49 @@ All notable project changes are documented here.
 
 ## [Unreleased]
 
+### Fixed
+
+- The password generator now applies "exclude similar characters" to every selected
+  character set. The one character guaranteed per set was previously picked from the
+  unfiltered alphabet, so a generated password could still contain `i`, `l`, `1`, `L`,
+  `o`, `0`, or `O` after the user excluded them — a digits-only password, for example,
+  could still be handed back containing `0` or `1`.
+- The password generator no longer returns more characters than requested when the
+  requested length is shorter than the number of selected character sets. The in-app
+  slider starts at 8, so this was only reachable through direct API use.
+
+### Removed
+
+- `src/components/ui/divider.tsx`. The component had no importers anywhere in the
+  application or the test suite, and its only styling was a Tailwind class left over from
+  a NativeWind setup the project no longer uses.
+- The unused `JSX.IntrinsicElements` augmentation in `nativewind-env.d.ts`, which declared
+  a `style` intrinsic element as `any`. No JSX `<style>` element exists in the codebase and
+  the declaration only weakened type checking globally.
+
+### Tooling
+
+- Added `.codex/` to the ignored local agent-state directories, so a future Codex session
+  cannot leave working state staged by accident, and folded the redundant trailing
+  `.claude/settings.local.json` rule into the `.claude/` entry that already covered it.
+
+### Documentation
+
+- Documented the accepted cryptographic and operational trade-offs in `docs/security.md`
+  under a new "Known Limitations" section: the shared AES/HMAC key, the PBKDF2-SHA1 backup
+  KDF, the six-digit master PIN keyspace, the absence of unlock throttling, opt-in
+  screenshot protection, transition-based auto-lock, Android 13+ clipboard previews, and
+  the trust placed in the over-the-air update channel. No cryptographic behavior changed.
+- Clarified in `nativewind-env.d.ts` that the `className` augmentations exist for
+  react-native-web CSS hooks, not for NativeWind or Tailwind, neither of which is a
+  dependency.
+
+### Tests
+
+- Added regression coverage for the password generator, which previously had none:
+  character-set exclusion, requested length, short-length behavior, empty option set, and
+  alphabet containment.
+
 ## [3.3.0] - 2026-08-01
 
 ### Release
diff --git a/docs/security.md b/docs/security.md
index dbbb6f3..8d56100 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -71,6 +71,18 @@ Vault data uses the KS1 format:
 
 Decryption verifies the MAC before trusting plaintext output.
 
+### Key separation
+
+KS1 derives a single 256-bit key and uses that same value both as the AES-256-CBC
+encryption key and as the HMAC-SHA256 authentication key. Standard practice is to split
+the KDF output into two independent subkeys (for example with HKDF). No practical attack
+on AES-CBC + HMAC-SHA256 under a shared key is known, and encrypt-then-MAC still provides
+integrity, but the construction does not follow the key-separation principle.
+
+Changing this is a vault-format break: every existing vault and every previously exported
+`KS1-PW1` backup would stop decrypting. It must not be changed without an explicit,
+versioned migration that re-encrypts vault data during an authenticated session.
+
 ## Backup Encryption
 
 Encrypted backup payloads use `KS1-PW1`.
@@ -83,6 +95,17 @@ The payload contains:
 
 The export password is never used directly as a KS1 key. It is first passed through a KDF to derive a valid encryption key.
 
+That KDF is PBKDF2 at 100,000 iterations with the `crypto-js` default hash (HMAC-SHA1),
+recorded in the payload as `memory = 0`. It is therefore materially weaker than the
+Argon2id used to unlock the vault itself, and it offers no memory hardness against
+GPU or ASIC cracking of an exported file. Users should treat an encrypted export as
+only as strong as the export password they choose, and should pick a long passphrase
+rather than a short one. Backups are the one vault artifact that can leave the device,
+so this is the weakest link in the current design.
+
+The KDF identifier is part of the `KS1-PW1` payload, so a stronger KDF can only be
+introduced as a new payload version that still reads `KS1-PW1` files.
+
 Backup imports are limited to 10 MiB and validate collection sizes and field lengths before any object reaches storage. Export passwords and imported ciphertext are removed from UI state on close, while temporary export files are deleted after sharing completes.
 
 ## Biometric Authentication
@@ -141,6 +164,40 @@ Production error logs contain only the sanitized message. Error objects and stru
 
 Operational secrets belong in `.secrets/`, which is ignored by git. Keystores, credentials, environment files, certificates, and signing material must never be committed. Keep Android signing files locally or in the platform-provided secret store used by EAS/Play Console.
 
+## Known Limitations
+
+These are accepted, documented properties of the current design rather than defects to be
+silently patched. Each one is a deliberate trade-off; changing any of them requires a
+security-design review, and the first two additionally require a versioned data migration.
+
+- **Shared encryption/authentication key.** See "Key separation" above.
+- **Backup KDF is PBKDF2-SHA1, not Argon2id.** See "Backup Encryption" above.
+- **The master secret is a 6-digit PIN.** The onboarding and unlock flows accept exactly
+  six digits, so the keyspace is 10^6. Argon2id makes each guess expensive, but an
+  attacker who extracts both the SecureStore metadata (salt and verifier) and the
+  encrypted AsyncStorage vault from a compromised or rooted device can mount an offline
+  search. Supporting a longer or alphanumeric master password would raise this ceiling
+  and can be added without breaking existing vaults, because each vault already stores
+  its own KDF parameters.
+- **No failed-attempt throttling or lockout.** Unlock attempts are limited only by the
+  cost of Argon2id; there is no attempt counter, backoff, or wipe-after-N-failures.
+- **Screenshot protection is opt-in.** `screenshotProtectionEnabled` defaults to `false`,
+  so by default vault screens can be screenshotted and appear in the Android recents
+  preview. The setting is exposed in Settings.
+- **Auto-lock is transition-based.** The vault locks when the app returns to the
+  foreground after spending longer than the configured timeout in the background. There is
+  no idle timer while the app stays in the foreground, so a session left open on an
+  unattended unlocked device stays unlocked.
+- **Clipboard previews on Android 13+.** Copied secrets are cleared automatically after
+  the configured timeout, but the system clipboard preview can still display the value at
+  copy time. Suppressing it requires the ClipData "is sensitive" extra, which the
+  `expo-clipboard` version bundled with Expo SDK 57 does not expose through
+  `SetStringOptions`. Re-evaluate when upgrading `expo-clipboard`.
+- **Over-the-air updates are trusted.** `expo-updates` can replace application JavaScript
+  after install. The update channel is therefore part of the trusted computing base: an
+  attacker controlling it could ship code that reads an unlocked vault. Vault data itself
+  is never transmitted.
+
 ## Security Verification
 
 Run before release:
diff --git a/nativewind-env.d.ts b/nativewind-env.d.ts
index c718223..427c9c2 100644
--- a/nativewind-env.d.ts
+++ b/nativewind-env.d.ts
@@ -1,5 +1,9 @@
-// Type augmentations for NativeWind className support
-// Expo SDK 54+ uses babel-preset-expo for className → style transformation
+// Type augmentations that allow `className` on React Native components.
+//
+// Keysoft does NOT use NativeWind or Tailwind (the file name is historical). The
+// prop is consumed only by react-native-web, which forwards `className` to the
+// rendered DOM node so `src/utils/webScrollFix.ts` can style scroll containers
+// with plain CSS. On Android and iOS the prop is inert.
 
 import 'react-native';
 
@@ -32,9 +36,3 @@ declare module 'react-native' {
     className?: string;
   }
 }
-
-declare namespace JSX {
-  interface IntrinsicElements {
-    style: any;
-  }
-}
diff --git a/src/__tests__/services/CryptoService.test.ts b/src/__tests__/services/CryptoService.test.ts
index 3218d01..5c3b8d0 100644
--- a/src/__tests__/services/CryptoService.test.ts
+++ b/src/__tests__/services/CryptoService.test.ts
@@ -197,4 +197,66 @@ describe('CryptoService', () => {
       }
     });
   });
+
+  describe('generatePassword', () => {
+    const SIMILAR_CHARACTERS = 'il1Lo0O';
+    const allOptions = {
+      includeLowercase: true,
+      includeUppercase: true,
+      includeNumbers: true,
+      includeSymbols: true,
+    };
+
+    it('returns an empty string when no character set is selected', () => {
+      expect(
+        CryptoService.generatePassword(16, {
+          includeLowercase: false,
+          includeUppercase: false,
+          includeNumbers: false,
+          includeSymbols: false,
+        }),
+      ).toBe('');
+    });
+
+    it('honors the requested length', () => {
+      expect(CryptoService.generatePassword(16, allOptions)).toHaveLength(16);
+      expect(CryptoService.generatePassword(8, { includeLowercase: true })).toHaveLength(8);
+    });
+
+    it('never emits more characters than requested when the length is very short', () => {
+      // Four character sets are selected but only two characters are requested.
+      expect(CryptoService.generatePassword(2, allOptions)).toHaveLength(2);
+    });
+
+    it('excludes look-alike characters from every selected set, including the guaranteed ones', () => {
+      const generated = CryptoService.generatePassword(16, {
+        ...allOptions,
+        excludeSimilarCharacters: true,
+      });
+
+      expect(generated).toHaveLength(16);
+      for (const character of SIMILAR_CHARACTERS) {
+        expect(generated).not.toContain(character);
+      }
+    });
+
+    it('excludes look-alike characters when a single set would otherwise guarantee one', () => {
+      // Regression: the guaranteed character used to be picked from the unfiltered
+      // alphabet, so a digits-only password could still contain "0" or "1".
+      const generated = CryptoService.generatePassword(10, {
+        includeNumbers: true,
+        excludeSimilarCharacters: true,
+      });
+
+      expect(generated).toHaveLength(10);
+      expect(generated).not.toContain('0');
+      expect(generated).not.toContain('1');
+      expect(generated).toMatch(/^[2-9]+$/);
+    });
+
+    it('only emits characters from the selected sets', () => {
+      const generated = CryptoService.generatePassword(24, { includeNumbers: true });
+      expect(generated).toMatch(/^[0-9]+$/);
+    });
+  });
 });
diff --git a/src/components/ui/divider.tsx b/src/components/ui/divider.tsx
deleted file mode 100644
index 8ce0d79..0000000
--- a/src/components/ui/divider.tsx
+++ /dev/null
@@ -1,20 +0,0 @@
-import React from 'react';
-import { View } from 'react-native';
-import { useTheme } from '../../contexts/ThemeContext';
-
-interface DividerProps {
-  className?: string;
-  style?: any;
-}
-
-export function Divider({ className, style }: DividerProps) {
-  const { theme } = useTheme();
-  return (
-    <View
-      className={`h-px ${className ?? ''}`}
-      style={[{ backgroundColor: theme.colors.divider }, style]}
-    />
-  );
-}
-
-export default Divider;
diff --git a/src/services/crypto/cryptoService.ts b/src/services/crypto/cryptoService.ts
index bf1b46d..d702914 100644
--- a/src/services/crypto/cryptoService.ts
+++ b/src/services/crypto/cryptoService.ts
@@ -492,32 +492,39 @@ export const generatePassword = (length: number, options: PasswordGeneratorOptio
   const symbols = '!@#$%^&*()_+-=[]{}|;:,.<>?';
   const similar = 'il1Lo0O';
 
-  let chars = '';
-  if (options.includeLowercase) chars += lowercase;
-  if (options.includeUppercase) chars += uppercase;
-  if (options.includeNumbers) chars += numbers;
-  if (options.includeSymbols) chars += symbols;
-
-  if (options.excludeSimilarCharacters) {
-    chars = chars
-      .split('')
-      .filter((char) => !similar.includes(char))
-      .join('');
-  }
+  // Apply the "exclude similar characters" option to every alphabet, so the
+  // characters guaranteed below cannot reintroduce a look-alike the user excluded.
+  const applyExclusions = (source: string): string =>
+    options.excludeSimilarCharacters
+      ? source
+          .split('')
+          .filter((char) => !similar.includes(char))
+          .join('')
+      : source;
+
+  const selectedAlphabets: string[] = [];
+  if (options.includeLowercase) selectedAlphabets.push(applyExclusions(lowercase));
+  if (options.includeUppercase) selectedAlphabets.push(applyExclusions(uppercase));
+  if (options.includeNumbers) selectedAlphabets.push(applyExclusions(numbers));
+  if (options.includeSymbols) selectedAlphabets.push(applyExclusions(symbols));
+
+  // An alphabet can in principle be emptied by the exclusion filter; picking from
+  // it would throw, so only non-empty alphabets can guarantee a character.
+  const minimumChars = selectedAlphabets.filter((alphabet) => alphabet.length > 0);
+  const chars = minimumChars.join('');
 
   if (chars.length === 0) return '';
 
-  const minimumChars: string[] = [];
-  if (options.includeLowercase) minimumChars.push(lowercase);
-  if (options.includeUppercase) minimumChars.push(uppercase);
-  if (options.includeNumbers) minimumChars.push(numbers);
-  if (options.includeSymbols) minimumChars.push(symbols);
-
   function pickChar(source: string): string {
     return source.charAt(randomInt(source.length));
   }
 
-  let password = minimumChars.map((source) => pickChar(source)).join('');
+  // Never emit more characters than requested: when the requested length is shorter
+  // than the number of selected alphabets, only the first ones can be guaranteed.
+  let password = minimumChars
+    .slice(0, Math.max(0, length))
+    .map((source) => pickChar(source))
+    .join('');
 
   for (let i = password.length; i < length; i++) {
     password += chars.charAt(randomInt(chars.length));
diff --git a/src/services/utils/clipboardService.ts b/src/services/utils/clipboardService.ts
index 3f639d1..5767002 100644
--- a/src/services/utils/clipboardService.ts
+++ b/src/services/utils/clipboardService.ts
@@ -43,7 +43,11 @@ export class ClipboardService {
       // Clear any existing timer with the same identifier
       this.clearTimeout(identifier);
 
-      // Copy the text to the clipboard
+      // Copy the text to the clipboard.
+      // NOTE: on Android 13+ the system shows a clipboard preview containing the
+      // copied value. Suppressing it needs the ClipData "is sensitive" extra, which
+      // the expo-clipboard version bundled with Expo SDK 57 does not expose through
+      // `SetStringOptions`. See docs/security.md ("Known Limitations").
       await Clipboard.setStringAsync(text);
 
       // When the timeout is greater than the warning threshold, schedule a warning timer

From 9ef2629abab8f2f4d121e5d8084a409a53cbdcd7 Mon Sep 17 00:00:00 2001
From: thestreamcode <dev@mikesoft.it>
Date: Sat, 1 Aug 2026 22:48:05 +0200
Subject: [PATCH 2/2] docs(readme): refresh the reported test-suite count

The generator regression tests added in this branch take the suite from 189 to
195. Only the two README lines that describe current repository state are
updated; docs/releases/*.md and docs/pre-build-security-ui-review.md record what
was true at their respective releases and are left as the audit trail.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index e5d0f7b..dd04e0c 100644
--- a/README.md
+++ b/README.md
@@ -21,7 +21,7 @@ Keysoft works offline for vault management. Network access is limited to platfor
 | Expo SDK            | 57.0.9                             |
 | React Native        | 0.86.2                             |
 | TypeScript          | 6.0.3, strict mode                 |
-| Test suite          | 29 suites, 189 tests               |
+| Test suite          | 29 suites, 195 tests               |
 | Health check        | `expo-doctor` 20/20                |
 
 Keysoft 3.3.0 is published on [Google Play](https://play.google.com/store/apps/details?id=it.mikesoft.keysoft). Production build numbers are managed remotely by EAS; the 3.3.0 release uses Android versionCode 129. `app.config.js` mirrors that value for local manifest visibility, while `appVersionSource: "remote"` keeps EAS authoritative for future build numbers.
@@ -157,7 +157,7 @@ Current verified state:
 
 - `bun run typecheck`: passing
 - `bun run lint`: passing
-- `bun run test:ci`: passing, 29 suites and 189 tests
+- `bun run test:ci`: passing, 29 suites and 195 tests
 - `bunx expo-doctor`: passing, 20/20 checks
 - `bunx expo export --platform android --output-dir C:\tmp\keysoft-android-export`: passing
 - `bunx expo export --platform ios --output-dir C:\tmp\keysoft-ios-export`: passing