hanzo/kms
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: modernize + LLM.md + cross-links (one-way SDK model)

Browse Source
This commit is contained in:
z
2026-07-24 12:43:34 -07:00
parent 53a4a5bb5d
commit e7b64bfad8
1 changed files with 53 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+53 -156
View File
@@ -1,194 +1,91 @@
<p align="center"><img src=".github/hero.svg" alt="kms" width="880"></p>
<p align="center"><img src=".github/hero.svg" alt="Hanzo KMS" width="880"></p>
# kms
# Hanzo KMS
Secrets and signing for the Hanzo platform. Per-org namespaces, AI-aware approval policies, dynamic secrets, SSH/PKI/certificate management.
Secrets, keys, and threshold signing for the Hanzo platform — per-org namespaces, IAM-gated, ZAP-native, MPC-backed. A thin Go server over the canonical [`luxfi/kms`](https://github.com/luxfi/kms) primitives.
[![Status](https://img.shields.io/badge/status-stable-green)]()
[![License](https://img.shields.io/badge/license-MIT-blue)]()
## Quick start
```bash
docker run -p 80:80 ghcr.io/hanzoai/kms:latest
```
Open `http://localhost:80`.
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![Go](https://img.shields.io/badge/go-1.26-00ADD8)]()
## What this is
`kms` is the canonical secret store and signing service for every Hanzo deployment. Holds per-tenant DEKs that back `base`, provider API keys consumed by `ai` and `gateway`, certificate material, and signing keys. AI agents are first-class identities: every secret has a policy controlling whether Claude / GPT / any agent can read it (auto-approve, requires-approval, blocked) with full per-agent audit trail.
Hanzo KMS is the canonical secret store and signing service for every Hanzo deployment. It holds the per-tenant DEKs that back Hanzo Base, the provider API keys the AI and gateway services consume, certificate material, and validator signing keys.
## Specs
AI agents are first-class identities: every secret carries a policy that controls whether an agent may read it — `auto-approve`, `requires-approval`, or `blocked` — with a full per-agent audit trail.
Implements:
- HIP-0027 KMS
- HIP-0106 Unified Cloud Binary (kms subsystem)
- HIP-0302 Encrypted SQLite + ZapDB Durability (DEK source)
All server logic lives in `luxfi/kms`. This module wires those primitives with Hanzo defaults (IAM at `hanzo.id`, encrypted-at-rest storage, S3 replication) and adds JWT verification, the audit ledger, version CAS, and header hygiene. It mounts into the unified cloud binary (`kms.Mount`) and also ships as a standalone daemon.
## Architecture
## Quick start
```
service / agent -> kms (zip.App) -> per-org namespace
|
IAM identity (HIP-0026 JWT)
|
policy gate: auto-approve | requires-approval | blocked
|
master DEK -> HKDF per-org -> per-record DEK (base / replicate)
|
audit log: who, what secret, when, why
Build from source — pure Go, no database toolchain required:
```bash
make kmsd kms # builds ./kmsd (daemon) and ./kms (admin CLI)
KMS_ENV=dev ./kmsd # HTTP on :8443, ZAP on :9999
```
Or run the container image (pin a released tag — never `:latest`):
---
```bash
docker run -p 8443:8443 ghcr.io/hanzoai/kms:vX.Y.Z
```
<h1 align="center">
KMS
</h1>
<p align="center">
<p align="center"><b>Open-source Key Management Service</b>: Manage secrets, API keys, certificates, and encryption keys across your infrastructure.</p>
</p>
In any non-dev environment the daemon refuses to boot without full JWT config (`KMS_EXPECTED_ISSUER`, `KMS_EXPECTED_AUDIENCE`, `KMS_JWKS_URL`) — fail-closed by design.
<h4 align="center">
<a href="https://hanzo.ai/discord">Discord</a> |
<a href="https://kms.hanzo.ai">KMS Cloud</a> |
<a href="https://kms.hanzo.ai/docs/self-hosting/overview">Self-Hosting</a> |
<a href="https://kms.hanzo.ai/docs">Docs</a> |
<a href="https://hanzo.ai">Hanzo AI</a>
</h4>
## AI access control
<h4 align="center">
<a href="https://github.com/hanzoai/kms/blob/main/LICENSE">
<img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="KMS is released under the MIT license." />
</a>
<a href="https://github.com/hanzoai/kms/blob/main/CONTRIBUTING.md">
<img src="https://img.shields.io/badge/PRs-Welcome-brightgreen" alt="PRs welcome!" />
</a>
<a href="https://github.com/hanzoai/kms/issues">
<img src="https://img.shields.io/github/commit-activity/m/hanzoai/kms" alt="git commit activity" />
</a>
</h4>
Your secrets, your rules. AI agents are first-class citizens — and so is your ability to block them.
## Introduction
**Hanzo KMS** is the open-source key management service built for the AI era — centralize secrets, API keys, and certificates across your infrastructure with first-class AI access controls.
Built by [Hanzo AI](https://hanzo.ai), we believe you should always control what AI can access. Every secret has a policy: some auto-approve for development velocity, others require explicit human sign-off before any AI agent can read them.
## AI Access Control
**Your secrets, your rules.** AI agents are first-class citizens in Hanzo KMS — and so is your ability to block them.
- **Per-secret AI policies**: Mark any secret as _human-approval required_ for AI access. Claude, GPT, or any agent requesting that secret triggers a real-time approval request.
- **Auto-approve mode**: Building fast? Set policies to auto-approve for your team's agents — flip to manual approval before shipping.
- **Device & agent tracking**: See exactly which AI model, tool, or agent accessed which secret and when.
- **Full audit trail**: Every secret read by an AI is logged with the agent identity, timestamp, and reason.
- **One-tap approval**: Approve or deny AI secret requests from Slack, email, or the KMS dashboard.
- **Per-secret policies** — mark any secret `requires-approval`; a read from any agent triggers a real-time approval prompt.
- **Auto-approve mode** — move fast in development, escalate specific secrets to manual sign-off before production.
- **Identity tracking** — see exactly which model, tool, or agent accessed which secret, and when.
- **Full audit trail** — every AI-originated read is logged with agent identity, timestamp, and reason.
```
Secret: STRIPE_LIVE_KEY
AI Access Policy: requires-human-approval
Last accessed by: claude-sonnet-4-6 via hanzo-mcp
Status: waiting for your approval → [Approve] [Deny]
policy: requires-approval
reader: agent via hanzo-mcp
status: waiting for approval → [approve] [deny]
```
## Features
## API surface
### Secrets Management
Everything is served under `/v1/kms` — one canonical path per operation, no aliases, no `/api/`. Every endpoint requires a Hanzo IAM JWT (RS/ES/PS/EdDSA — never HS\*, never `none`) or an explicit admin role.
- **Dashboard**: Manage secrets across projects and environments through a user-friendly interface.
- **Secret Syncs**: Sync secrets to platforms like GitHub, Vercel, AWS, and use tools like Terraform, Ansible, and more.
- **Secret versioning** and **Point-in-Time Recovery**: Track every secret and project state; roll back when needed.
- **Secret Rotation**: Rotate secrets at regular intervals for services like PostgreSQL, MySQL, AWS IAM, and more.
- **Dynamic Secrets**: Generate ephemeral secrets on-demand for services like PostgreSQL, MySQL, RabbitMQ, and more.
- **Secret Scanning and Leak Prevention**: Prevent secrets from leaking to git.
- **Kubernetes Operator**: Deliver secrets to your Kubernetes workloads and automatically reload deployments.
- **KMS Agent**: Inject secrets into applications without modifying any code logic.
| Group | Endpoints |
|-------|-----------|
| Auth | `POST /v1/kms/auth/login` — machine-identity client credentials → IAM token |
| Secrets (per-org) | `GET / POST / PATCH / DELETE /v1/kms/orgs/{org}/secrets/…` — `env` is a first-class key component; writes require an explicit `env`; `PATCH` requires version CAS via `If-Match` |
| MPC keys | `POST /v1/kms/keys/generate` · `/{id}/sign` · `/{id}/rotate` · `GET /v1/kms/keys` · `/v1/kms/status` — threshold BLS / round signing via `luxfi/mpc` |
| Health | `GET /healthz` — liveness, no auth |
### Certificate Management
A sub-100µs binary **ZAP** transport (default `:9999`) mirrors the HTTP surface for in-cluster callers under the identical JWT + role model. The Go client at [`sdk/go`](sdk/go) (HTTP with ZAP fallback) is what every other Hanzo service uses to fetch secrets at runtime.
- **Internal CA**: Create and manage a private CA hierarchy directly within KMS.
- **External CA**: Integrate with third-party certificate authorities such as Let's Encrypt, DigiCert, Microsoft AD CS, and more.
- **Certificate Lifecycle Management**: Create certificate profiles and policies to control how certificates are issued.
- **Certificate Syncs**: Sync certificates to external platforms like AWS Certificate Manager and Azure Key Vault.
- **Alerting**: Configure alerting for expiring CA and end-entity certificates.
## Storage & durability
### Key Management System (KMS)
- **At rest** — ZapDB (LSM) at `$KMS_DATA_DIR`; per-secret 256-bit DEK wrapped under the master key (AES-256-GCM).
- **Replication** — age-encrypted incremental + snapshot backups streamed to S3 (off when unset).
- **Audit** — buffered SQLite side-table; single writer, never blocks the request path.
- **Cryptographic Keys**: Centrally manage keys across projects through a user-friendly interface or via the API.
- **Encrypt and Decrypt Data**: Use symmetric keys to encrypt and decrypt data.
## Specs
### SSH Management
- **Signed SSH Certificates**: Issue ephemeral SSH credentials for secure, short-lived, and centralized access to infrastructure.
### AI Access Control (New)
- **AI Identity Tracking**: Identify which AI model or agent is requesting secrets — Claude, GPT, Gemini, or any MCP-compatible tool.
- **Per-secret AI policies**: Set `auto-approve`, `requires-approval`, or `blocked` per secret per AI identity.
- **Real-time approval requests**: Pending AI secret reads appear in your dashboard, Slack, or email — one tap to approve or deny.
- **Auto-approve mode**: Teams move fast by default; escalate specific secrets to manual approval as you go to production.
- **Device registry**: Register and manage AI agent devices; revoke access instantly.
- **AI audit log**: Separate audit trail for all AI-originated secret reads, with model ID, tool name, and request context.
### General Platform
- **Authentication Methods**: Authenticate machine identities with KMS using cloud-native or platform agnostic authentication methods (Kubernetes Auth, GCP Auth, Azure Auth, AWS Auth, OIDC Auth, Universal Auth).
- **Access Controls**: Define advanced authorization controls for users and machine identities with RBAC, additional privileges, temporary access, access requests, approval workflows, and more.
- **Audit logs**: Track every action taken on the platform.
- **Self-hosting**: Deploy KMS on-prem or cloud with ease; keep data on your own infrastructure.
- **SDKs**: Interact with KMS via client SDKs (Node, Python, Go, Ruby, Java, .NET)
- **CLI**: Interact with KMS via CLI; useful for injecting secrets into local development and CI/CD pipelines.
- **API**: Interact with KMS via REST API.
## Getting Started
### Run KMS locally
To set up and run KMS locally, make sure you have Git and Docker installed on your system. Then run:
**Linux/macOS:**
```console
git clone https://github.com/hanzoai/kms && cd kms && cp .env.dev.example .env && docker compose -f docker-compose.prod.yml up
```
**Windows Command Prompt:**
```console
git clone https://github.com/hanzoai/kms && cd kms && copy .env.dev.example .env && docker compose -f docker-compose.prod.yml up
```
Create an account at `http://localhost:80`
### Scan and prevent secret leaks
Scan for over 140+ secret types in your files, directories, and git repositories.
To scan your full git history, run:
```
hanzo-kms scan --verbose
```
Install pre-commit hook to scan each commit before you push:
```
hanzo-kms scan install --pre-commit-hook
```
## Open-source vs. paid
This repo is available under the [MIT license](https://github.com/hanzoai/kms/blob/main/LICENSE) in its entirety. Portions are derived from Infisical (MIT, Copyright 2022 Infisical Inc.); see `NOTICE`.
If you are interested in managed KMS Cloud or self-hosted Enterprise offering, visit [kms.hanzo.ai](https://kms.hanzo.ai) or [contact us](https://hanzo.ai/contact).
- **HIP-0027** — KMS
- **HIP-0106** — Unified Cloud Binary (kms subsystem)
- **HIP-0302** — Encrypted SQLite + ZapDB durability (DEK source)
## Security
Please do not file GitHub issues or post on public forums for security vulnerabilities, as they are public!
Please do not open public GitHub issues for security vulnerabilities. Email **security@hanzo.ai** with a description and, ideally, a reproduction. We respond quickly.
KMS takes security issues very seriously. If you have any concerns or believe you have uncovered a vulnerability, please get in touch via email at security@hanzo.ai. In the message, try to provide a description of the issue and ideally a way of reproducing it. The security team will get back to you as soon as possible.
## License
## Contributing
MIT — see [LICENSE](LICENSE). Portions are derived from Infisical (MIT, © 2022 Infisical Inc.); see [NOTICE](NOTICE). The current request path is a thin wrapper over `luxfi/kms`; no original upstream server code remains on the wire.
Whether it's big or small, we love contributions. Check out our guide to see how to [get started](https://kms.hanzo.ai/docs/contributing/getting-started).
---
Not sure where to get started? Join our [Discord](https://hanzo.ai/discord) and ask us any questions there.
## Hanzo — the Open AI Cloud
Open source · every language · on-chain settlement. [hanzo.ai](https://hanzo.ai) · [docs.hanzo.ai](https://docs.hanzo.ai)
**SDKs in every language** — [Python](https://github.com/hanzoai/python-sdk) (flagship) · [TypeScript](https://github.com/hanzo-js/sdk) · [Go](https://github.com/hanzo-go/sdk) · [Rust](https://github.com/hanzo-rs/sdk) · [C++](https://github.com/hanzo-cpp/sdk) · [Swift](https://github.com/hanzo-swift/sdk) · [Kotlin](https://github.com/hanzo-kt/sdk) · [umbrella](https://github.com/hanzoai/sdk)