Skip to content

docs: design doc and deployment guides for three use cases#7

Merged
ceejbot merged 1 commit into
latestfrom
docs/usage-guides
Mar 29, 2026
Merged

docs: design doc and deployment guides for three use cases#7
ceejbot merged 1 commit into
latestfrom
docs/usage-guides

Conversation

@ceejbot

@ceejbot ceejbot commented Mar 29, 2026

Copy link
Copy Markdown
Owner

Summary

Replaces 11 stale implementation spec files and the old deployment architecture doc with four focused documents for a technical audience evaluating zerolease for security-sensitive deployments.

New docs

design.md — The foundational document. Covers:

  • The problem (why static credentials are dangerous for AI agents)
  • Threat model (what we defend against, what we don't, trust boundaries)
  • Core abstractions (vault, leases, transports, proxy)
  • Design decisions with rationale (deny-by-default, newtypes, zeroize, decoupled storage/audit, no TLS termination, token dies with provisioner)
  • What this is not (not a secrets manager, not a general proxy, not an HSM)

guide-embedded.md — For integrating zerolease into a Rust application:

  • Backend selection (keychain + rusqlite)
  • Initialization, policy, lease-and-access pattern
  • Notes on adapting zeroclaw's built-in vault

guide-cloud-service.md — For running the vault as a shared server:

  • Backend selection (KMS + PostgreSQL or AWS SM)
  • Authenticator implementation
  • Client usage (UDS and TCP)
  • Monitoring via tracing events

guide-vm-deployment.md — The full production deployment with VMs:

  • Architecture diagram
  • VM image requirements (no credentials — security requirement, not convention)
  • iptables network jail (default-deny outbound, proxy-only exit)
  • Complete lifecycle: boot → proxy → provision → agent → revocation → destroy
  • Credential manifest with all three injection mechanisms
  • Proxy hardening (SSRF, DoS, port restriction, case normalization)
  • Security assumptions, residual risks
  • What the orchestrator provides vs what zerolease provides

Removed

  • 11 implementation spec files from the pre-workspace era (design decisions are now in design.md)
  • deployment-architecture.md (superseded by guide-vm-deployment.md)

Test plan

  • No code changes — docs only
  • CI green (workflow triggers on doc changes? If not, n/a)

New documentation for technical audiences evaluating zerolease:

- design.md: Threat model, trust boundaries, core abstractions,
  design decisions (why deny-by-default, why newtypes, why the proxy
  doesn't terminate TLS), and what this is not.

- guide-embedded.md: Integrating zerolease into a Rust app like
  zeroclaw. In-process vault with rusqlite, per-tool leasing pattern,
  notes on adapting zeroclaw's built-in vault.

- guide-cloud-service.md: Running the vault as a server with
  PostgreSQL/AWS SM backends. Authenticator implementation, client
  usage, monitoring.

- guide-vm-deployment.md: Full lifecycle of the QEMU VM deployment.
  Image requirements (no credentials), iptables network jail, boot
  sequence (proxy → provision → source env → claude), proxy hardening,
  security assumptions and residual risks, what the Claw provides.

Removes 11 stale implementation spec files from the pre-workspace era
and the old deployment-architecture.md (superseded by the VM guide).
@ceejbot ceejbot merged commit 893421f into latest Mar 29, 2026
2 checks passed
@ceejbot ceejbot deleted the docs/usage-guides branch March 29, 2026 04:06
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.

1 participant