Architecture

ADR 0010: Vault autofill

Status: accepted, 26 Sep 2026 · Workstream: vault · Extends: ADR 0001, decisions 6 and 10 · Code: core/vault/fill.js, modules/vault-extension/

The problem#

To replace a password manager, the Vault has to put a login into a browser page. That is the one path where a value is meant to reach a screen, so it needs its own door. The door must stay shut to three callers: agents, web pages, and anyone who holds only a stolen browser profile.

Decision 10 of ADR 0001 sketched vault.match and vault.fill. This addendum settles how they work.

Threat model#

Defended:

• An agent asking for a login. No registry tool fills. vault.fill is a route on a separate listener, not a tool, so Claude and modules are never offered it and cannot call it.
• A web page calling the listener from script. Browsers attach an Origin header to cross-origin requests. The listener refuses any request whose Origin is present and is not chrome-extension://<id> or moz-extension://<id>, and it does so before it reads the body. CORS is answered only for the extension origin that asked. A page also has no device token, and it would need one even without the Origin rule.
• Phishing. A login fills a page only when the page's origin is one of the login's hosts, compared exactly on scheme, host and port. A login for https://mail.example.com is never filled into https://mail.example.com.evil.test, http://mail.example.com or https://mail.example.com:8443. match applies the same rule, so the popup offers only what will fill. The content script checks location.origin again before it sets a field, in case the tab moved between the click and the fill.
• A stolen browser profile. The device token in chrome.storage.local lists login names for a page and nothing more. A value needs a session. The session token lives in memory and chrome.storage.session, both cleared when the browser closes, and it ends 30 minutes after the proof that opened it (ADR 0028, decision 5; this ADR first said 10 minutes idle or 12 hours at most).
• Guessing the unlock passphrase with a stolen device token. 5 wrong passphrases from a device within 15 minutes lock that device out for the rest of the window, even from the right passphrase. The verifier is scrypt (N=2^17, r=8, p=1), as for the vault key.
• Guessing a pairing code. A code is 8 characters from a 31-letter alphabet with no 0, O, 1, I or L. It works once, for 5 minutes. 10 wrong codes in 15 minutes stop all pairing for the rest of the window.
• Reading tokens out of vyre.db. Every module can read vyre.db. Device and session tokens are 32 random bytes stored as sha256, which a reader cannot reverse. Pairing codes are too short for that, so they are stored as HMAC-SHA256 under a key held only in vyred's memory. A restart voids codes nobody has used yet.
• A leaked audit trail. Pairing, each unlock (ok or refused), each fill (ok or refused), lock and revoke are audit rows carrying names only, with who set to device:<id>:<name>. No value, token, code or passphrase is ever written to an audit row, an event, an error or a log.

Not defended, stated plainly:

• A module that writes to vyre.db. It could add a device row or replace the unlock verifier. vault_grants carries the same exposure today, and the answer is the same: run vyred as its own user and install only modules you trust. A later change can MAC these rows under a key derived from the master key.
• Malware in the browser or the extension's own process. It sees what the page sees once a field is filled, as it does with any password manager.
• The person filling a login into a page on the right origin that is itself compromised. The origin rule stops a lookalike host. It cannot stop an XSS on the real one.

Decisions#

A1. A separate listener, owned by the vault module#

Config: vault.fill: { host = "127.0.0.1", port }. It follows the relay listener's shape: its own HTTP server, JSON in and out, {data} or {error: {code, message}}, and a 64 KB body cap. On a box it sits behind tailscale serve, which gives the extension an https://*.ts.net address. It serves these routes and nothing else:

The device token goes in Authorization: Bearer <token>, the session in X-Vyre-Session. Requests without an Origin (curl, tests) are allowed and still need both tokens.

Error codes: origin_refused (403), unauthorized and revoked (401), bad_code (403), bad_passphrase (401), locked_out (429), not_set (409, no unlock passphrase yet), session_required and session_expired (401), wrong_origin (403), not_found (404), vault_locked (423), too_large (413).

A2. Pairing#

vyre vault pair calls vault.device.code {name?} and prints the code. The extension posts it to pair and receives a device id and a device token: 32 random bytes in base64url, stored as sha256 in vault_devices. vault.devices lists devices by name, when each was last seen and how many sessions it holds. vault.device.revoke {id} ends a device at once, sessions included.

A3. Unlock and sessions#

A device token alone never reveals a value. unlock {passphrase} opens a session: a second 32-byte token, stored as sha256 in vault_sessions, bound to that device. Since ADR 0028 (decision 5) it ends 30 minutes after it opened and use does not extend it; vault.fill.window (minutes, 1 to 30) can only shorten that. This section first said 10 minutes without a fill or 12 hours at most.

The passphrase is the unlock passphrase, set with vault.unlock-passphrase {passphrase} and kept as a scrypt verifier in vault_meta under the key unlock. It is separate from the vault key so that a box on the keychain or file keystore, which unlocks itself for agents, still asks a person before a browser gets a value. Changing it ends every session. When the keystore is passphrase, the vault passphrase is also accepted, checked through the keystore by a callback the module passes in.

Touch ID. The Capsule helper runs Touch ID and then calls vault.device.unlock {device}, which opens a session and returns only {ok, expires}. The session token waits in vyred's memory and is handed to that device once, on its next status call. No token crosses the socket, and a token nobody collects dies with the session.

A4. Who may call what#

The table of decision 6 gains these rows:

Giving access needs a person; taking it away never does, as before.

A5. The extension#

modules/vault-extension/ is a Chrome MV3 extension in plain JavaScript with no build step and no remote code. Its permissions are storage, activeTab and scripting. Its only host permission is the vyred address (default http://127.0.0.1/*; localhost and *.ts.net are optional and requested when the person saves one). A strict CSP limits connect-src to those addresses, so the extension cannot reach anything else.

• The background worker is the only part that talks to vyred. It sends the page's origin, never its path, query or content.
• The popup never holds a password. It asks the worker to fill a login by name.
• On Fill, the worker injects fill.js into the active tab's top frame with chrome.scripting.executeScript. The script sets the username, password and one-time-code inputs through the native value setter, dispatches input and change, and returns only the kinds of field it filled.
• No content script runs on any page until the person clicks.

Consequences#

• A paired browser is useless on its own: a thief also needs the unlock passphrase within five tries, or the person's finger on the Mac.
• A person proves presence at most every 30 minutes of use (ADR 0028, decision 5; first every 10 minutes of use and twice a day at most).
• Lookalike-domain phishing fails closed. A site that moved to a new origin needs its login put again with the new host, which is the price of exact matching.
• The existing vault.match tool keeps its looser hostname rule for local clients. The fill listener does not use it.