Documentation
¶
Overview ¶
Package kms embeds luxfi/kms in-process inside the unified Hanzo Cloud binary per HIP-0106 ("all Go embeds in cloud"), replacing the legacy Infisical fork.
It has two faces, both backed by the SAME embedded luxfi/kms library:
KMSClient — the in-process cloud.KMSClient (GetSecret/PutSecret/Sign) other
subsystems call via deps.KMS. No RPC, no external DB. Built once
in build.go's pickKMSClient and reused by Mount.
/v1/kms/* — the secrets-manager REST surface the KMS console (kms.hanzo.ai)
calls, mounted onto cloud's Fiber app: JWT-gated, org-scoped
secrets CRUD + a real health probe + the SPA admin config.
STORAGE — luxfi/kms's SecretStore is an embedded ZapDB (github.com/luxfi/zapdb) KV opened UNDER CLOUD_DATA_DIR/kms (the RWO PVC where per-tenant SQLite lives), so there is no PostgreSQL and no external DB. cloud runs replicas=1/Recreate, so the single-writer KV is safe. Secrets are sealed with AES-256-GCM envelope encryption (store.Seal: a fresh per-secret DEK sealed under the 32-byte master key) BEFORE they hit the store — plaintext never touches disk. The KV itself is ALSO opened with ZapDB block-level encryption under the same key (defense in depth). See New for the fail-secure open strategy across the health-only↔keyed transition.
BOOTSTRAP — cloud hosting the secret store is a chicken-and-egg: cloud cannot fetch its OWN master key from the KMS it hosts. The 32-byte master key is injected by the operator via a K8s Secret env (CLOUD_KMS_MASTER_KEY_REF, base64 of 32 bytes) and read ONLY from env — never from the store, never logged, never persisted in plaintext. When the master key is absent the subsystem mounts in a fail-closed HEALTH-ONLY mode: /v1/kms/health reports 503, every secret op returns a clear "master key not configured" error, and the store is backed by an EPHEMERAL in-memory KV (never an unencrypted on-disk one), so a later keyed boot opens a clean encrypted store rather than a bricked one. Never a silent insecure default.
SIGN — luxfi/kms's Sign is MPC-backed (threshold signing via the MPC daemon). cloud does not co-host the MPC cluster; Sign therefore fails CLOSED with a clear error whenever the MPC backend is not configured (CLOUD_KMS_MPC_ADDR / CLOUD_KMS_MPC_VAULT_ID unset). A signature is NEVER fabricated.
SECURITY — the REST surface (clients/kms) reuses cloud's ONE auth boundary (SanitizeIdentity in serve.go establishes the validated principal; handlers read c.Org()/c.IsAdmin()) rather than a parallel JWT stack. This package is the cloud-free CLIENT core (the types.KMSClient impl + sealed store access); it imports NO cloud package so build.go's BuildDeps can construct it without an import cycle (cloud → clients/kms → cloud/types only). The Fiber routes that expose it live in the clients/kms subsystem, which imports this package.
Index ¶
- Constants
- Variables
- func ValidSegment(s string, max int) bool
- func ValidSubpath(p string) bool
- type Client
- func (c *Client) Close() error
- func (c *Client) Delete(path, name, env string) error
- func (c *Client) Get(path, name, env string) ([]byte, error)
- func (c *Client) GetSecret(ctx context.Context, ref string) ([]byte, error)
- func (c *Client) List(path, env string) ([]SecretMeta, error)
- func (c *Client) Put(path, name, env string, value []byte) error
- func (c *Client) PutSecret(ctx context.Context, ref string, value []byte) error
- func (c *Client) Ready() bool
- func (c *Client) Sign(ctx context.Context, keyRef string, payload []byte) ([]byte, error)
- func (c *Client) SigningConfigured() bool
- type Config
- type SecretMeta
Constants ¶
const ( MaxNameLen = maxNameLen MaxEnvLen = maxEnvLen )
MaxSegmentLens exposes the name/env bounds so the HTTP subsystem can produce specific 400 messages using the same limits the store methods enforce.
Variables ¶
var ErrInvalidKey = errors.New("kms: invalid secret coordinate (name/env must be non-empty, within length bounds, and contain no '/', NUL, or control characters)")
ErrInvalidKey is returned when a secret coordinate (name/env) contains a byte that would smuggle structure into the store key (a '/', NUL, or control char) or is out of length bounds. Enforced in ONE place — the store-access methods — so every entry point (the HTTP subsystem AND the in-process KMSClient facade) keys clean, unambiguous records.
var ErrMasterKeyMissing = errors.New("kms: master key not configured (operator must inject CLOUD_KMS_MASTER_KEY_REF)")
ErrMasterKeyMissing is the fail-closed error every secret op returns when no master key is configured. It is honest (mirrors the DisabledKMS pattern): the caller knows the operator must inject CLOUD_KMS_MASTER_KEY_REF.
var ErrSecretNotFound = kmsstore.ErrSecretNotFound
ErrSecretNotFound is re-exported so the REST subsystem can map a missing secret to a 404 without importing luxfi/kms's store package directly.
ErrSignUnavailable is the fail-closed error Sign returns when the MPC backend is not configured. Signing is threshold-MPC-backed; cloud never fabricates a signature.
Functions ¶
func ValidSegment ¶ added in v1.786.32
ValidSegment reports whether s is a valid single store-key segment (name or env): non-empty, within max bytes, and free of '/', NUL, and ASCII control characters. Exported so the HTTP subsystem reuses the exact same rule.
func ValidSubpath ¶ added in v1.786.32
ValidSubpath reports whether p is a valid store subpath: '/'-separated non-empty segments, none of which is "." or ".." or contains a control char, within the length bound. An empty/"/"-only path is valid (the org/collection root). Exported so the HTTP subsystem reuses the exact same rule.
Types ¶
type Client ¶ added in v1.786.32
type Client struct {
// contains filtered or unexported fields
}
Client is the in-process cloud.KMSClient backed by the embedded luxfi/kms SecretStore. GetSecret/PutSecret seal/open through the AES-256-GCM envelope; Sign fails closed (MPC is never co-hosted here).
The zero value is not usable; construct with New.
func New ¶ added in v1.786.32
New opens the embedded KMS store under cfg.DataDir and returns the in-process Client. A malformed or missing master key is NOT fatal: the store still opens (so health can report + list metadata) but the Client runs in health-only mode where every secret op fails closed with ErrMasterKeyMissing. A bad DataDir / store-open failure IS fatal (the subsystem cannot serve at all).
The master key is decoded from base64, validated to be exactly 32 bytes, and held in memory only. It is never logged and never written to the store.
func (*Client) Close ¶ added in v1.786.32
Close releases the embedded store. Safe to call once at shutdown.
func (*Client) Delete ¶ added in v1.786.32
Delete removes a secret. Returns ErrSecretNotFound verbatim for a 404 mapping.
func (*Client) Get ¶ added in v1.786.32
Get reads a sealed secret at (path, name, env) and returns the opened plaintext. Fails closed with ErrMasterKeyMissing when no master key is set.
func (*Client) GetSecret ¶ added in v1.786.32
GetSecret resolves a flat ref to (path, name, env), reads the sealed record from the store, and returns the AES-256-GCM-opened plaintext. Fails closed with ErrMasterKeyMissing when no master key is configured.
ref grammar (see parseRef): "name" | "path/name" | "path/name@env". A bare name resolves to (path="/", name, env="default").
func (*Client) List ¶ added in v1.786.32
func (c *Client) List(path, env string) ([]SecretMeta, error)
List returns the metadata (never ciphertext/plaintext) of the secrets at a path/env. It does not require the master key: nothing sensitive is decrypted.
func (*Client) Put ¶ added in v1.786.32
Put seals value under a fresh per-secret DEK (wrapped by the master key) and upserts it. Plaintext is sealed before it reaches the store — never stored raw. Fails closed with ErrMasterKeyMissing when no master key is set.
func (*Client) PutSecret ¶ added in v1.786.32
PutSecret seals value under a fresh per-secret DEK (wrapped by the master key) and upserts it into the store. Plaintext is never persisted. Fails closed with ErrMasterKeyMissing when no master key is configured.
func (*Client) Ready ¶ added in v1.786.32
Ready reports whether the Client can perform secret ops (a valid master key is configured). Used to fail closed uniformly across the KMSClient + REST paths, and surfaced to build.go for the boot log.
func (*Client) Sign ¶ added in v1.786.32
Sign is threshold-MPC-backed in luxfi/kms and cloud does not co-host the MPC cluster, so it fails closed with ErrSignUnavailable unless an MPC backend is explicitly configured. It NEVER returns a fabricated signature.
When an MPC backend IS configured the caller should route signing to the dedicated MPC/keys deployment (deps.KMS ZAP RPC); in-process co-hosting of the MPC signer is intentionally out of scope for the application-tier binary.
func (*Client) SigningConfigured ¶ added in v1.786.32
SigningConfigured reports whether an MPC backend is wired. Sign fails closed when false — no signature is fabricated.
type Config ¶ added in v1.786.32
type Config struct {
DataDir string // CLOUD_DATA_DIR; the store opens under {DataDir}/kms
MasterKeyB64 string // base64 of the 32-byte master key (CLOUD_KMS_MASTER_KEY_REF)
MPCAddr string // MPC daemon host:port(,...) — CLOUD_KMS_MPC_ADDR
MPCVaultID string // MPC vault id — CLOUD_KMS_MPC_VAULT_ID
}
Config is the embedded KMS configuration resolved from cloud.Config + env by New. All fields are optional: an empty MasterKeyB64 yields the fail-closed health-only mode; empty MPC fields make Sign fail closed.
type SecretMeta ¶ added in v1.786.32
type SecretMeta struct {
Name string `json:"name"`
Path string `json:"path"`
Env string `json:"env"`
Scheme string `json:"scheme"`
}
SecretMeta is a secret's non-sensitive descriptor (never any ciphertext or plaintext), returned by List for the console's secret browser.
Source Files