readest/apps/readest-app/AGENTS.md at f6f446e8a0da752ddc6660f5a16b74993deae4ec

Files

T

Huang Xin 712d564e9d feat(sync): encrypted OPDS credentials + Tauri keychain (PR 4c + 4d) (#4090 )

* feat(sync): encrypt opds_catalog credentials end-to-end (TS path)

Wires encrypted-credential sync for opds_catalog via the CryptoSession
shipped in PR 4a (#4084) plus a new publish/pull crypto middleware.
TS-only — native still uses ephemeral storage (re-enter passphrase per
launch); PR 4d wires the OS keychain.

- ReplicaAdapter gains optional `encryptedFields: readonly string[]`.
  Adapters stay sync; the middleware handles the crypto round trip.
- replicaCryptoMiddleware.ts: encryptPackedFields drops the named
  fields from the push when the session is locked (no plaintext
  leak); decryptRowFields drops them on pull failure (local
  plaintext preserved by the store merge).
- replicaPublish / replicaPullAndApply invoke the middleware.
- OPDS adapter declares encryptedFields = [username, password] and
  now pack/unpack them as plaintext.
- passphraseGate.ts: ensurePassphraseUnlocked coalesces concurrent
  calls, prompts via the registered prompter with kind=setup|unlock,
  throws NO_PASSPHRASE on cancel.
- PassphrasePromptModal mounted at the Providers root; registers
  itself as the gate prompter.
- CryptoSession.forget() wipes server-side envelopes + salts.
- Migration 010 + replica_keys_forget RPC; DELETE
  /api/sync/replica-keys + client wrapper.
- SyncPassphraseSection on the user page: status / Set / Unlock /
  Lock / Forgot.
- CatalogManager pre-save: ensurePassphraseUnlocked when credentials
  are present; user cancel saves locally without sync.

Plan updated: PR 4 split documented as 4a/4b/4c/4d.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(sync): persist sync passphrase via OS keychain (Tauri)

Replaces the EphemeralPassphraseStore stub on native with real
OS-keychain storage so users don't re-enter their sync passphrase
every launch. Web stays on the in-memory ephemeral store by design.

Native bridge plugin gains 4 commands wired across all platforms:

- Rust desktop (`keyring` crate): macOS Keychain on apple-native,
  Windows Credential Manager on windows-native, Linux libsecret/
  Secret Service on sync-secret-service. Per-target features so each
  platform compiles only the backend it needs.
- iOS Swift: Security framework Keychain (kSecClassGenericPassword,
  SecItemAdd / Copy / Delete).
- Android Kotlin: androidx.security EncryptedSharedPreferences
  (AndroidKeystore-derived AES-GCM master key,
  AES256_SIV / AES256_GCM key/value encryption).

TS layer:

- TauriPassphraseStore wraps the bridge calls. set is fail-loud
  (surfaces keychain rejection); get is fail-soft (returns null on
  any error so the gate prompts).
- createPassphraseStore returns ephemeral synchronously;
  upgradeToKeychainIfAvailable swaps the singleton to
  TauriPassphraseStore on Tauri after probing the bridge. CryptoSession
  resolves the store via createPassphraseStore() each touch so the
  swap is transparent.
- CryptoSession.tryRestoreFromStore: silent unlock at boot. Stale-
  entry recovery clears the store when the account has no salt
  server-side. unlock/setup persist; forget also clears the store.
- Providers boot effect: upgrade keychain → silent restore.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(sync): make encrypted-credential pull actually decrypt + UX polish

PR 4c shipped the encrypt path but the pull side silently dropped
ciphers when locked, the modal was busy with double-rings, and web
re-prompted on every page refresh. This rolls up the post-test
fixes + UX polish:

Pull-side decrypt:
- decryptRowFields takes an `onLocked` callback the orchestrator
  wires to the passphrase gate; encountering a cipher field with a
  locked session now triggers the lazy-prompt path instead of
  dropping the field.
- replicaPullAndApply re-applies the unpacked row for metadata-only
  kinds even when a local copy exists, so the now-decrypted creds
  reach the store (the binary-kind skip-if-local optimization
  doesn't apply).
- Cipher fingerprint comparison: capture the row's `cipher.c` for
  each encrypted field, compare against the local record's
  lastSeenCipher. Same → skip prompt + decrypt entirely. Different
  (rotation / value change on another device) → prompt to
  re-decrypt. Fingerprint persists via OPDSCatalog.lastSeenCipher.

Web persistence:
- SessionStoragePassphraseStore: passphrase survives page refresh
  within the same tab, dies on tab close. Replaces
  EphemeralPassphraseStore as the default on web. Avoids
  localStorage / IndexedDB to keep the tab-scoped trust boundary.

UI:
- Renamed PassphrasePromptModal → PassphrasePrompt; modernized: filled
  input style with single subtle focus border, btn-primary +
  btn-ghost replaced with leaner custom buttons. eink-bordered +
  btn-primary classes give the dialog correct e-paper rendering.
- globals.css: suppress redundant outline/box-shadow on focused text
  inputs / textareas (the element's own border is the focus
  indicator).
- AGENTS.md: documents the e-ink convention (`eink-bordered`,
  `btn-primary` for inverted CTAs, etc.) so future widgets ship with
  e-paper support.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-08 13:22:49 +02:00

5.8 KiB

Raw Blame History

Project Overview

Readest is a cross-platform ebook reader built as a Next.js 16 + Tauri v2 hybrid app. It's part of a pnpm monorepo at /apps/readest-app/. The app runs on web (CloudFlare Workers), desktop (macOS/Windows/Linux via Tauri), and mobile (iOS/Android via Tauri).

Common Commands

# Development
pnpm dev-web               # Web-only dev server (no Rust compilation needed)
pnpm tauri dev             # Desktop dev with Tauri (compiles Rust backend)

# Building
pnpm build                 # Build Next.js for Tauri
pnpm build-web             # Build Next.js for web deployment

# Testing (see [docs/testing.md](docs/testing.md) for full details)
pnpm test                  # Unit tests (vitest + jsdom)
pnpm test -- src/__tests__/utils/misc.test.ts  # Run a single test file
pnpm test -- --watch       # Watch mode
pnpm test:browser          # Browser tests (Chromium via Playwright)
pnpm tauri:dev:test        # Start Tauri app with webdriver
pnpm test:tauri            # Run Tauri integration tests

# Linting & Formatting
pnpm lint                  # Biome (linter) + tsgo (type check)
pnpm format                # Prettier (runs from monorepo root)
pnpm format:check          # Check formatting without writing

# Rust
pnpm fmt:check             # Check formatting Rust code (src-tauri)
pnpm clippy:check          # Lint Rust code (src-tauri)

Source Layout

Directory	Purpose
`src/app/`	Next.js App Router pages and API routes
`src/components/`	React components (reader, settings, library, assistant, etc.)
`src/services/`	Business logic: TTS, translators, OPDS, sync, AI, metadata
`src/store/`	Zustand state stores
`src/hooks/`	Custom React hooks
`src/libs/`	Document loaders, payment, storage, sync
`src/utils/`	Pure utility functions
`src/types/`	TypeScript type definitions
`src/context/`	React Context providers (Auth, Env, Sync, etc.)
`src/workers/`	Web Workers for background tasks
`src-tauri/`	Rust backend: Tauri plugins, platform-specific code

Path Aliases (tsconfig)

@/* → ./src/*
@/components/ui/* → ./src/components/primitives/*

Rust Backend (`src-tauri/`)

Platform-specific code lives in src-tauri/src/{macos,windows,android,ios}/. Custom Tauri plugins are in src-tauri/plugins/.

Git Worktrees

Always use pnpm worktree:new <branch-name|pr-number> to create worktrees. Never use git worktree add directly — the script handles submodule initialization (simplecc WASM, foliate-js), dependency installation, .env copying, vendor assets, and Tauri gen symlinks that are required for lint and tests to pass.

pnpm worktree:new feat/my-feature   # New branch from origin/main
pnpm worktree:new 3837              # Checkout PR #3837 with push access to fork

Project Rules

Rules are in .claude/rules/: test-first, typescript, verification.

i18n

See docs/i18n.md for the key-as-content translation approach, stubTranslation usage in non-React modules, and extraction workflow.

Safe Area Insets

See docs/safe-area-insets.md for rules on handling top/bottom insets for UI elements near screen edges.

E-ink mode

Every new UI widget must look right under [data-eink='true']. E-ink screens have no shadows, no gradients, slow refresh, and need crisp 1px borders for delineation. The conventions live in src/styles/globals.css — reuse the existing classes instead of inventing new ones:

Surfaces / inputs — add eink-bordered. In eink mode it swaps to bg-base-100 + 1px base-content border. Use it on inputs, custom button backgrounds, ghost-styled cancel buttons, and any container that needs a visible boundary.
Primary action buttons — add btn-primary (alongside whatever Tailwind classes you use for color themes). The [data-eink] .btn-primary rule inverts to base-content bg + base-100 text so the primary CTA stays distinct from secondary actions.
.modal-box picks up no-shadow + 1px border automatically; dialogs that use it don't need additions.
Don't rely on color/shadow alone for hierarchy. Two same-tone buttons differ only by hover on color themes, and hover doesn't exist on e-ink touchscreens. Pair a borderless ghost (cancel) with a solid CTA (submit) so eink can invert one without flattening the difference.

When in doubt, toggle E-ink in Settings → Misc and check. The rules in globals.css cover most cases automatically, but composite components (custom buttons, layered cards) often need eink-bordered on the right element to stay legible.

Available gstack skills:

/plan-ceo-review — CEO/founder-mode plan review
/plan-eng-review — Eng manager-mode plan review
/plan-design-review — Designer's eye review of a live site
/design-consultation — Design system consultation
/review — Pre-landing PR review
/ship — Ship workflow (merge, test, review, bump, PR)
/browse — Fast headless browser for QA and site interaction
/qa — QA test and fix bugs
/qa-only — QA report only (no fixes)
/qa-design-review — Designer's eye QA with fixes
/setup-browser-cookies — Import cookies for authenticated testing
/retro — Weekly engineering retrospective
/document-release — Post-ship documentation update

If gstack skills aren't working, run cd .claude/skills/gstack && ./setup to build the binary and register skills.

5.8 KiB Raw Blame History