27 KiB
vault1984 — Full Repositioning Document
Prepared: 2026-03-10
Based on: L2_AGENT_ENCRYPTION.md, vault1984-hn-article.md, app/README.md, website/templates/
Executive Summary
The new 3-tier encryption architecture changes everything about the story vault1984 tells. The current positioning is "AI-native password manager with field-level access control." The new positioning must be: "The only password manager where a server breach gives attackers nothing. Mathematically."
This isn't a feature update. It's a category shift. The current framing competes with Bitwarden on AI features. The new framing makes the SaaS password manager category structurally obsolete.
The HN article has the thesis exactly right. The problem: the README and website have not caught up.
Part 1: README Changes
What Currently Says the Wrong Thing
1. The opening tagline
> *The vault that knows who it's talking to.*
This frames vault1984 as an access control story ("knows who it's talking to"). The real story is a breach story. No password manager should be interesting to steal. The tagline should communicate that, not identity routing.
2. The lead sentence
A password manager built for humans who have AI assistants.
Wrong hook entirely. This positions vault1984 as an AI productivity tool. The actual differentiator is a cryptographic property — a stolen database is worthless. The AI angle is real and important, but it's second. Security architecture is first.
3. The "How it works" section frames L1 as acceptable
Shared — server-encrypted (your AI can read these)
API keys, SSH keys, passwords, TOTP seeds, logins...
Under the new architecture, these are L2 — not server-encrypted. Server-encrypted means the server CAN read them, which means they're exposed in a breach. The README currently and correctly admits this in the security table:
Full server compromise | Exposed | Cannot decrypt
This is honest. It also means the current README is documenting the exact vulnerability that the new architecture eliminates. Once L2 is implemented, this table row becomes: Full server compromise | Worthless ciphertext | Cannot decrypt. That's the headline.
4. The security model table is accurate but buried The table at the bottom of the README is the most important thing in the document. It should be near the top, not at the bottom.
5. "Shared" / "Personal" naming is inconsistent with the website The website uses "Agent fields" / "Sealed fields." The README uses "Shared" / "Personal." Neither reflects the new 3-tier model (L1/L2/L3). Pick one naming system and use it everywhere.
6. The README has no breach narrative No mention of LastPass, no mention of the stolen-vault attack vector, no articulation of why the server holding decryption keys is architecturally broken. A developer reading the README has no idea why this architecture matters in the threat landscape. They just see "two tiers of encryption" — and assume this is similar to what Bitwarden does.
What's Missing
- The core security thesis: "If the server is breached, the attacker gets ciphertext. That ciphertext cannot be decrypted without a key that was never on the server."
- The threat model framing: SaaS password managers are high-value targets precisely because they hold both encrypted vaults AND the decryption capability.
- Explicit comparison to the LastPass breach — not to trash LastPass, but to show the structural problem is universal.
- The L2 architecture: passwords and API keys encrypted with a key that exists only in agent tokens and browser sessions — never stored on the server.
- The L3 distinction: even agents can't reach card numbers and government IDs — hardware authenticator required.
Proposed New README Structure
# vault1984
> "If you want to keep a secret, you must also hide it from yourself."
> — George Orwell, 1984
**The password manager where a server breach gives attackers nothing.**
Self-hosted. Open source. Three encryption tiers.
One Docker command. Free forever.
Then: The Security Thesis (2–3 paragraphs, before any feature lists).
Then: The Three Tiers (the actual architecture, with the table moved up).
Then: Quick Start (one command).
Then: MCP Setup (the agent use case, now in proper context).
Then: Features (the feature list, as supporting detail not the lead).
Then: Import, Backups, Testing, License.
Proposed README Opening (Draft Copy)
See Part 4 for the actual draft text.
Part 2: Website Changes
Homepage (index.tmpl)
Hero Section — What Needs to Change
Current hero copy:
"If you want to keep a secret, you must also hide it from yourself."
We did. Your Sealed key is derived in your browser from your Touch ID. Our servers
have never seen it. They could not decrypt your private fields even if they wanted
to. Or anybody else.
This is actually good — the Orwell quote as hero is correct and should stay. But the subhead only talks about Sealed (L3) fields. After the architecture update, it should also establish that passwords and API keys (L2) are also server-opaque. The current copy implies only the "private fields" (credit cards, passports) are safe. The new reality is that everything except metadata is cryptographically inaccessible to the server.
What to change: The subhead paragraph needs to lead with the complete picture — database theft gets you nothing — and then explain the hierarchy.
The hero SVG diagram currently shows two columns: "L1 — AI can read" vs "L2 — you only." After the new architecture, this becomes a three-column story: L1 (metadata, server-readable), L2 (agent-readable, server-opaque), L3 (hardware-only, agents can't reach). The SVG needs to be rebuilt. This is significant visual work but essential — the diagram is the fastest way to explain the tier model.
"The Problem" Section — Needs Complete Rewrite
Current framing: Three red cards: "All-or-nothing is broken," "Policy isn't security," "Agents need credentials."
This frames the problem as "existing password managers don't have good AI integration." That's true, but minor. The actual problem — and the one that makes people switch — is "your SaaS password manager is a breach waiting to happen, and when it happens, your passwords are exposed."
The "Policy isn't security" card is the only one that hints at the real problem. It says: "If the server can read it, it's not truly private. Math beats policy every time." This is exactly right. It should be card 1, not card 2, and it should be expanded massively.
What to change: Rewrite this section as "The Structural Problem" — one card for the breach architecture problem, one for iteration count arms race, one for why incumbents can't fix it. The AI access control story moves downstream as an additional benefit of the architecture, not the primary problem statement.
Keep: The "Policy isn't security" copy (it's good). Strengthen and promote it.
"How It Works" Section — Partial Rewrite
Current:
- Two cards: "Agent fields" (AI-readable) vs "Sealed fields" (Touch ID only)
Post-architecture:
- Three cards/tiers: L1 (metadata), L2 (agent-readable, server-opaque), L3 (hardware-only)
- The key message is now that L2 (where passwords and API keys live) is encrypted before it reaches the server — the server stores ciphertext it cannot decrypt
- This is the new thing. The current website doesn't have this.
Section header copy needs to change:
Current: "Your assistant can book your flights. Not read your diary."
This frames L1/L2 split as the main story. The new main story is: "If someone breaches the server, they get a pile of ciphertext they cannot read."
Keep: The structure of "what each tier can do." Update the number of tiers and the descriptions.
"Built Different" (Features Section) — Update, Don't Rebuild
Current 6 feature cards:
- Field-level AI visibility
- WebAuthn PRF
- AI-powered 2FA
- Scoped MCP tokens
- One binary, one file
- LLM field mapping
What to change:
- Card 1 ("Field-level AI visibility") needs to lead with the server-opacity property, not the AI access control property. The security property is stronger.
- Card 2 ("WebAuthn PRF") is good but currently only explains L3 (Sealed). Add a sentence about L2 key derivation.
- Add a new card for the core thesis: "Stolen database: worthless." This deserves its own feature card — it's the most important security property.
- The "One binary, one file" card can stay as-is — it's strong and accurate.
Keep: Cards 3, 4, 5, 6 can stay with minor tweaks.
"The Competition" Section — Significant Update
Current: 6 red cards quoting forums about UX complaints (extension bugs, autofill failures) + the LastPass breach quote.
The LastPass card currently says:
vault1984: Self-host or use hosted with L2 encryption — we mathematically cannot read
your private fields. No vault data to breach.
This is partially true today (L3 / Sealed fields) but will be fully true after the L2 implementation. Update this card to reflect the complete architecture: both L2 and L3 fields are server-opaque. The stolen database is worthless across the board.
New card to add: The structural argument — not about UX, but about architecture. Something like:
1PASSWORD / BITWARDEN / DASHLANE — The Architectural Trap
Enterprise admin controls, visibility features, and team sharing all require the server to decrypt. Their business model depends on server authority. They cannot offer true end-to-end encryption without destroying their product. This isn't laziness — it's structural. vault1984 started with no such constraint.
Keep: The UX complaint cards are genuinely useful social proof that the incumbents have real problems. Keep all 6 but add the architectural critique card.
Hosted CTA Section — Minor Update
Current:
Your Sealed keys never leave your browser — we mathematically cannot read your private fields.
After L2 implementation:
Your passwords, API keys, and private fields never leave your browser decryptable — even in
hosted mode, we cannot read them. The database on our servers is worthless to steal.
The "mathematically cannot" claim extends from just Sealed fields to all L2+ fields. Update accordingly.
Quick Install Section
The install section mentions VAULT_KEY for the "Agent field data." After the architecture change, VAULT_KEY covers L1 only. L2 is derived from the user's hardware authenticator. This needs a note to clarify that the vault key is for L1 metadata/titles — passwords and sensitive data are protected by a key that never exists on the server.
Pricing Page (pricing.tmpl)
Current FAQ entry:
Can hosted vault1984 read my Sealed fields?
No. Sealed fields are encrypted client-side with WebAuthn PRF.
Needs expansion: After L2 implementation, the question should be broadened: "Can you read ANY of my passwords?" The answer is no — and the explanation needs to cover all three tiers:
- L1 (metadata): server can read titles and URLs. Acceptable — knowing you have a Coinbase account isn't an attack.
- L2 (passwords, API keys, TOTP): server stores ciphertext it cannot decrypt. Agent tokens carry the decryption key.
- L3 (card numbers, government IDs): hardware authenticator required. Neither server nor agents can read these.
Keep: The pricing structure itself is good. Free self-hosted + $12/yr hosted is clean.
Install Page (install.tmpl)
Step 2 ("Set your vault key") is misleading after L2 implementation. The current copy says:
The vault key encrypts your Agent field data at rest. If you lose this key, Agent field
data cannot be recovered.
Post-architecture, the vault key encrypts L1 data (metadata). L2 data (passwords, API keys) is encrypted with a user-held key derived from their hardware authenticator. The vault key being compromised no longer means passwords are exposed — only metadata.
This step should be renamed and its explanation updated to reflect what it actually protects (metadata/titles) and what it doesn't (passwords — those have a different, stronger protection).
What to Add (New Pages or Sections)
1. Dedicated Security Architecture page
The threat model is the product's strongest argument. It deserves its own page, not just a footer mention. This page should walk through:
- The stolen-vault attack (how LastPass breach worked)
- Why iteration count arms race is the wrong solution
- The three tiers and what each protects
- The key derivation diagram from L2_AGENT_ENCRYPTION.md (the HKDF tree)
- The threat model matrix (which scenarios expose what)
- Why the incumbents can't fix this
2. Update the hero SVG to show three tiers, not two.
Part 3: What NOT to Change
The Orwell quote as hero. "If you want to keep a secret, you must also hide it from yourself." — This is perfect. It's the thesis. It should remain the centerpiece of the hero. Do not replace it with a more "marketable" headline.
Port 1984. Memorable, thematic, immediately gets it. Keep.
The competition section concept. Real quotes from real people about real problems. This is unusually honest and effective. Keep all 6 complaint cards. Add to it, don't replace it.
The scoped token / multi-agent diagram. Visually strong, technically accurate, genuinely differentiating. Keep.
One binary, one file. This copy is exact and true. Every SaaS alternative requires Docker + a database server + cloud accounts. "One Go binary, one SQLite file" is a killshot that self-hosting competitors can't match. Don't soften this.
LLM field mapping. The form DOM serialization approach is genuinely novel. The "works on SPAs, obfuscated field names, multi-step flows" claim is real. Keep this feature card.
The WebAuthn PRF explanation. "Encrypted client-side with WebAuthn PRF. The server never sees the plaintext. Ever." — Accurate, punchy, correct. The word "Ever." with a period is good. Keep the pattern.
The pricing page structure. Free self-hosted + $12/yr hosted is clean. The "Is the self-hosted version missing any features? No." answer is powerful. Keep.
The auto-lock behavior. "60s idle timeout + 15s countdown, then full vault lock" — this is a real security property that no other manager has. Should stay in docs/README.
The audit log. "Every read logged with actor (web/extension/mcp/agent name)" — small feature, big implication for AI oversight. Worth keeping prominent.
"No content scripts" for the extension. The claim that the extension injects nothing into pages is genuinely differentiating and addresses a real security complaint. Keep.
Part 4: New Copy Proposals
README Opening
# vault1984
> "If you want to keep a secret, you must also hide it from yourself."
> — George Orwell, 1984
**A self-hosted password manager where a breached server gives attackers nothing.**
Not because we delete the data. Not because we encrypt it harder.
Because the decryption key was never there to begin with.
Self-hosted. Open source. Three-tier encryption.
One binary. One SQLite file. Free forever.
[GitHub badge] [License badge] [Discord/community badge]
README Security Section (the "Security Model" block, moved up)
## Why the architecture matters
In 2022, attackers stole the entire LastPass vault database. The encryption worked
exactly as designed. The problem was structural: when you store encrypted data on a
server that also holds the decryption capability, a breach gives attackers unlimited
offline time to crack. They're still cracking. The industry's response has been higher
iteration counts — making the vault harder to crack. vault1984's response was to make
it worthless to steal.
**Three encryption tiers:**
| Tier | Contains | Who can read |
|------|----------|--------------|
| **L1** | Titles, URLs, usernames | Server (by design — knowing you have a Coinbase account isn't an attack) |
| **L2** | Passwords, API keys, TOTP secrets, SSH keys | Your agents only — server stores ciphertext it cannot decrypt |
| **L3** | Card numbers, CVV, government IDs, seed phrases | You only — hardware authenticator required, agents cannot reach |
**The L2 guarantee:** When you store a password, your browser encrypts it with a key
derived from your hardware authenticator before it leaves the browser. The server stores
ciphertext. Agents decrypt locally using a key embedded in their token — a key the
server never stored. Breach the server: get a database of ciphertext with no key to
decrypt it.
**The L3 guarantee:** Card numbers and government IDs never leave your device
unencrypted. The AES-256 key is derived from your WebAuthn authenticator's PRF output
and exists only in browser session memory. Not in the database. Not in agent tokens.
Not on the server.
Threat model matrix:
| Scenario | L1 | L2 | L3 |
|----------|----|----|-----|
| Database stolen | Readable (with vault key) | Worthless ciphertext | Worthless ciphertext |
| Server memory dump | Visible during request | Ciphertext only | Not present |
| Agent token compromised | Via MCP | Decryptable | Not present |
| Hardware key + PIN stolen | Everything | Everything | Everything |
*If someone steals your hardware authenticator, they have the root of trust for everything.
Store it accordingly.*
README: "How It Works" (the three-tier explainer)
## How it works
L1 — Metadata (server-readable, by design) Entry titles, URLs, username labels Knowing you have a GitHub account isn't an attack.
L2 — Secrets (agent-readable, server-opaque) Passwords, API keys, TOTP secrets, SSH keys Browser encrypts with your L2 public key before saving. Server stores ciphertext it cannot decrypt. Agents decrypt locally — key is in the token, never on server.
L3 — High-value (hardware-only, agents cannot reach) Card numbers, CVV, passport, SSN, seed phrases Key derived from WebAuthn PRF output. Requires physical authenticator tap. Never stored anywhere. Even a fully compromised agent gets nothing.
Key derivation uses a single root of trust — your hardware authenticator's PRF output —
split into two independent HKDF branches: one for L2 (asymmetric, embedded in agent tokens),
one for L3 (symmetric, browser-only). One tap unlocks both in the browser. Neither branch
can derive the other.
Website: Hero Subhead (replacement for current paragraph)
Option A (breach-first framing):
Steal our server. You'll get ciphertext.
Your passwords and API keys are encrypted before they leave your browser, with a key
derived from your hardware authenticator. We store the result. We cannot undo it.
That's not a policy — it's the math of public-key cryptography.
Neither can anyone who breaches us.
Option B (three-tier framing, same paragraph):
Three tiers. One root of trust: your fingerprint.
Metadata lives on the server — knowing you have a Coinbase account isn't an attack.
Passwords and API keys are encrypted with a key the server never held — agents
decrypt them locally. Card numbers and government IDs require a hardware tap —
even agents can't reach those.
Breach the server: get a pile of ciphertext with no key to decrypt it.
Option C (punchy, closer to HN article):
We cannot be LastPass'd. Mathematically.
Your passwords are encrypted with a key derived from your hardware authenticator.
It's in your browser session and your agent tokens. Never on our server.
Breach us and you get exactly what we get when we look at your passwords: nothing.
Recommendation: Option C for the hero subhead — it's the most direct and most shareable. Pair it with a brief "Here's how:" before the three-tier explainer below it.
Website: "The Problem" Section Rewrite
New section title: "The structural problem with SaaS password managers"
Three new cards:
Card 1 — The stolen-vault attack
The correct lesson from LastPass
In 2022, 33 million encrypted vaults were stolen. The encryption worked.
The problem was architectural: the attacker got unlimited offline time with
the ciphertext. The industry's response: higher iteration counts. Faster
hardware erodes that every year. The iteration count arms race has no winner.
The correct answer: make the vault worthless to steal.
Card 2 — Server authority is the trap
"Zero-knowledge" is a legal term, not a security property
SaaS password managers claim zero-knowledge. Most of them can read your vault
server-side — they need to, for admin features, AI integrations, team sharing.
Their business models require server authority. They are architecturally trapped.
They cannot offer true end-to-end encryption without destroying what makes them
enterprise-grade.
vault1984 started with no such constraint.
Card 3 — What actually prevents the attack
The decryption capability doesn't exist server-side
There's one architectural principle that makes stolen-vault attacks impossible:
the decryption key never touches the server. Our server stores ciphertext.
Agents carry the key to L2 secrets in their tokens. L3 secrets require a hardware
tap that was never part of any server transaction.
Breach us. You'll get a database. It won't decrypt.
Website: Security Architecture Section (New)
This should be a new <section> on the homepage or a dedicated /security page:
THE THREE TIERS
┌──────────────────────────────┐
│ Hardware Authenticator │
│ (Touch ID / YubiKey) │
│ PRF Output = Root of Trust │
└──────────┬───────────────────┘
│
┌─────────────────┴──────────────────┐
│ │
▼ ▼
HKDF → L2 keypair HKDF → L3 key
(asymmetric, X25519) (symmetric, AES-256)
│ │
├── public key → server └── browser only
└── private key → agent tokens never leaves device
NEVER stored on server
L1 — Title, URLs, username labels ← Server can read (acceptable)
L2 — Passwords, API keys, TOTP ← Server stores ciphertext. Cannot decrypt.
L3 — Cards, passport, seed phrases ← Hardware tap required. Agents cannot reach.
Website: Hero Diagram (Updated SVG Concept)
The current two-column SVG (L1 green / L2 red) needs to become three columns reflecting the actual tiers. Proposed layout:
- Left column (L1, blue/gray): Titles, URLs — labeled "Server sees this"
- Center column (L2, green): Passwords, API keys, TOTP — labeled "AI agent reads this" with a lock icon and "server stores ciphertext"
- Right column (L3, red): Cards, passport, SSN — labeled "Hardware only" with a padlock
- Bottom: A single root node labeled "Your fingerprint" with lines going up to L2 and L3 branches
- Visual emphasis: The center column (L2) is new. It's the architectural breakthrough. Make it visually distinct.
Website: Updated Hosted CTA Copy
Self-hosted or hosted — the cryptographic guarantees are identical.
In hosted mode, your passwords and API keys are encrypted before they leave your
browser. We store ciphertext. The decryption key lives in your hardware authenticator
and your agent tokens — never on our infrastructure.
Breach our servers: get a database. It won't decrypt.
$12/year. 22 regions. Same math, anywhere.
Website: FAQ Addition (Pricing Page)
Add this question:
Q: If hosted vault1984 gets breached, are my passwords exposed?
A: No. Passwords, API keys, TOTP secrets, and SSH keys are L2 — encrypted in your
browser with a key derived from your hardware authenticator before they reach our
server. We store ciphertext. The decryption key is embedded in your agent tokens
and exists in browser session memory. It was never on our server.
Card numbers, government IDs, and seed phrases are L3 — hardware authenticator
required. Neither we nor your agents can reach these.
What we can read: entry titles, URLs, username labels. Knowing you have a GitHub
account isn't useful to an attacker. The passwords to that account are what matter —
and those are ciphertext to us.
This isn't a policy. It's the math of public-key cryptography.
Part 5: Naming Convention Recommendation
The current codebase/README uses "Shared" / "Personal."
The current website uses "Agent fields" / "Sealed fields."
The architecture doc uses "L1" / "L2" / "L3."
Recommendation: Use the tier naming (L1/L2/L3) throughout, with human-readable labels as secondary descriptors:
- L1 — Metadata (server-readable)
- L2 — Secrets (agent-readable, server-opaque)
- L3 — Private (hardware-only)
The short forms "L1," "L2," "L3" work well in technical contexts (README, code comments, threat model tables). The descriptive names work well in marketing copy. Use both together where appropriate: "L2 (agent-readable, server-opaque)" on first mention, then "L2" thereafter.
Retire "Shared" (too informal, doesn't communicate security property) and "Personal" (implies preferences, not cryptographic isolation). "Agent fields" and "Sealed fields" from the website are better but don't scale to three tiers.
Implementation Priority
Immediate (before the architecture ships):
- README: Replace the opening paragraph and tagline with the breach-first framing
- README: Move the security model table to the top, update it to reflect the L2 guarantee once implemented
- README: Add the "Why the architecture matters" section explaining the LastPass structural problem
When L2 ships: 4. Website homepage: Update hero subhead (Option C recommended) 5. Website homepage: Rewrite "The Problem" section with the three structural cards 6. Website homepage: Update the "How it works" section to three tiers 7. Website homepage: Rebuild the hero SVG for three tiers 8. Pricing page: Expand the FAQ entry for hosted security 9. Install page: Update VAULT_KEY explanation
After:
10. Add dedicated /security page with full threat model
11. Update the competition section with the architectural critique card
Final Note
The HN article is the repositioning in miniature — it's exactly the right story, told well. The README should open with the thesis of that article. The website should put it in the hero. The pitch isn't "better AI password manager" — it's "mathematically impossible to betray you."
SaaS password manager = trust someone else with your secrets.
vault1984 = the decryption capability doesn't exist on the server.
Those are different categories, not different products. The repositioning should make that unavoidable.