Skip to content

docs: add ADR-015 (web + sync auth coherence) - #229

Merged
kafkade merged 1 commit into
mainfrom
kafkade-adr-015-auth-coherence
Jul 27, 2026
Merged

docs: add ADR-015 (web + sync auth coherence)#229
kafkade merged 1 commit into
mainfrom
kafkade-adr-015-auth-coherence

Conversation

@kafkade

@kafkade kafkade commented Jul 27, 2026

Copy link
Copy Markdown
Owner

Description

Adds docs/adr/015-web-sync-auth-coherence.md (Status: Proposed) recording the decision about Toku's two authenticated account stores.

Toku today has two separate account stores that share only a single password-hardening function:

  • Web dashboardweb_users / web_sessions in the local toku.db (crates/toku-db/migrations/V16__web_auth.sql), a trusted-server design: login recomputes the SRP verifier server-side, so the process receives the plaintext password and Secret Key (crates/toku-web/src/auth.rs). There is no challenge table — it is a verifier recompute, not an SRP handshake — because the dashboard already decrypts and renders the library server-side.
  • Sync serverusers / user_srp_challenges / user_sessions in a separate sync.db (crates/toku-sync/migrations/V5__users_and_admin.sql), a zero-knowledge design: a full SRP-6a challenge/verify handshake where the server never sees the password (crates/toku-sync/src/auth.rs).

The only shared code is the srp_verifier_input() derivation in crates/toku-core/src/crypto/srp.rs; salts, verifiers, session tables, storage databases, and the authentication protocol are all independent. The two tiers share a hardening function, not accounts.

What's included

  • Decision (keep the stores separate): the two stores stay separate by design because they sit on opposite sides of Toku's trust boundary — the web dashboard must receive plaintext to render the decrypted library, while the sync relay must never receive it. Unifying would either pull plaintext handling into the zero-knowledge store or bolt a zero-knowledge handshake onto a surface that already holds plaintext (cost without benefit).
  • Blast radius documented: the split is only observable to a self-hoster running both toku serve --hosted and toku-sync; the default local dashboard reads no auth tables, and a managed offering is relay-only, so it never runs the web tier.
  • Risks + future paths: acknowledges the self-hoster support cost (two accounts, two credentials, separate lockout) — with no security, zero-knowledge, or data-ownership impact — and records two non-mandated, non-breaking convergence paths (web federating to the sync account server via the already-matching schema; a browser-local zero-knowledge WASM web client), deferring the choice to product direction.
  • Sections for Consequences, Alternatives Considered, a CI/Terraform note (docs-only, no gating-job change), and file-line references round out the document.

No code, schema, or migration changes — this is a documentation-only architecture decision record.

Related Issues

Closes #205
Relates to #207

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Documentation update
  • Refactoring (no functional changes)
  • CI / infrastructure
  • Other (describe below)

Crate

  • toku-core — Domain models, traits, state machine
  • toku-db — SQLite persistence, migrations, FTS5
  • toku-import — Importers (Goodreads, Calibre, StoryGraph)
  • toku-meta — Metadata fetching (Open Library, Google Books)
  • toku-cli — CLI binary
  • toku-export — Exporters (CSV, JSON, Markdown, BibTeX)
  • docs/ — Documentation

Data Integrity Checklist

  • No user data is sent to any server without explicit opt-in — N/A, docs-only (no code path changed)
  • Import operations are idempotent (re-importing the same file creates no duplicates) — N/A, docs-only
  • User edits to metadata are never overwritten by auto-enrichment — N/A, docs-only
  • New fields track provenance (source + timestamp) — N/A, docs-only
  • Export round-trip is preserved (if applicable) — N/A, docs-only

Checklist

  • I have read CONTRIBUTING.md
  • cargo fmt --check passes — N/A, docs-only (no Rust changed; CI skips Rust jobs via path filter)
  • cargo clippy --workspace -- -D warnings passes — N/A, docs-only (no Rust changed)
  • cargo test --workspace passes — N/A, docs-only (no Rust changed)
  • I have updated documentation (if applicable) — this PR is the documentation; markdownlint-cli2 passes with 0 issues

@kafkade
kafkade enabled auto-merge (squash) July 27, 2026 21:27
@kafkade
kafkade merged commit a351f44 into main Jul 27, 2026
9 checks passed
@kafkade
kafkade deleted the kafkade-adr-015-auth-coherence branch July 27, 2026 21:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

ADR-015 / auth coherence: unify web + sync accounts or document the split

1 participant