ak-vaultby AgentKit
Protocol v1 · in security review

Security model, in plain language.

Who ak-vault defends against, how protocol v1 does it, and what remains your risk. This page summarizes the normative protocol v1 specification; where they differ, the spec wins.

Scope and status

What is being protected

The assets are your secret values and everything that describes them: names, descriptions, tags, profiles, portable policy and the audit trail. All of them are encrypted on your devices before upload. The server keeps ciphertext, wrapped vault keys and the operational metadata it needs to order and authorize writes.

Status: protocol v1 is Proposed. It is not approved for production credentials until the security gate in issue #8 records an external review sign-off. Until then the production sync API stays behind a kill switch.

Out of scope by design: decryption in a web browser, server-held vault keys or KMS, and automatic revocation of plaintext that has already been disclosed.

Adversaries

Threats we design against

Each card lists the defence in protocol v1 and the residual risk that stays with you.

Malicious or compromised server

Defence
Client-side AEAD for all sensitive data; signed records; owner-signed, hash-chained membership; signed checkpoints that refuse rollback or forks; injected key recipients rejected.
Residual risk
It can withhold updates a new or long-offline device has never witnessed, and it sees operational metadata.

Network attacker

Defence
TLS, plus a per-request device signature bound to method, URL, token and body hash, valid for 60 seconds with single-use IDs.
Residual risk
Request timing and sizes are observable.

Stolen or revoked device

Defence
Device-bound ES256 tokens; revoked sessions and devices are checked on every request and fail closed. Removing a device requires a rekey before new writes.
Residual risk
Values already decrypted on that device stay exposed. Rotate them.

Removed member of a shared vault

Defence
Removal triggers a new key epoch wrapped only to remaining members, and affected items are marked to rotate.
Residual risk
Previously exposed values cannot be clawed back.

Stale or conflicting devices

Defence
Revision compare-and-swap with preserved conflict branches, idempotent writes and tombstones. An offline device cannot resurrect a deleted secret.
Residual risk
Conflicts need an explicit decision from you.

Hostile shared metadata (prompt injection)

Defence
Descriptions, URLs and profiles are untrusted, author-attributed data and are never read as instructions. Portable policy can only narrow local grants. High-sensitivity secrets always need fresh approval.
Residual risk
An agent you grant a secret to receives its plaintext.

Design guarantees

  • No custom cryptographyXChaCha20-Poly1305, Ed25519, X25519, HKDF-SHA256, Argon2id via audited libraries. Unknown algorithm IDs fail closed. §1
  • Cross-language test vectorsGo and TypeScript must reproduce every vector byte for byte, including rejection cases.
  • Local-firstresolve never depends on the network; sync-off causes zero network requests.
  • Recovery without trusting the serverThe recovery bundle carries the owner's signing key and newest witnessed checkpoint, so a fresh device does not take the server's word. §3.4
  • Encrypted, chained auditReordering, dropping or overwriting audit entries since a witnessed checkpoint is detected. §7
  • Least-privilege authorizationToken scope intersected with vault membership; readers and machine identities are read-only; no cross-vault access. §9

Known limitations

  • Vault-wide keyA vault key decrypts every item in that vault. v1 makes no per-secret access claim; use separate vaults for least privilege. §3
  • Freeze attackUpdates never witnessed by a device can be withheld. Detection needs a second channel; transparency logs and gossip are out of scope for v1. §6
  • Plaintext to child processak secrets run releases the value to the approved process by design.
  • Visible metadataRandom IDs, revisions, sizes, timestamps, device public keys, roles and request metadata.
  • Key loss is finalLose every enrolled device, the master password and the recovery key, and the vault cannot be decrypted by anyone.
  • TOFU at genesisThe owner's key is pinned on first use unless it arrives via the recovery bundle or a SAS-verified pairing. §4
Release gate

What must be true before general availability

  • The protocol ADR is approved and the cross-language vectors pass.
  • Malicious server, member and device scenarios are exercised in staging.
  • A full dump of the Worker and its storage, logs, telemetry and API errors contains no plaintext secret values or names.
  • Concurrent updates keep conflicting ciphertexts, tombstones hold, and signed rollback is detected after a witnessed checkpoint.
  • Revoked devices and sessions are denied; removed members lose access to new keys and ciphertext.
  • No unexpected outbound calls with sync disabled.
  • An independent security review signs off. This cannot be self-attested.

The full list lives in the epic and issue #8.

Sources

Read the primary documents

Disclosure

Found a problem?

Please report suspected vulnerabilities privately through GitHub security advisories for ak-vault rather than a public issue.

Reviewing with an AI assistant? Use the Markdown version of this page.

Open in ChatGPT Open in Claude