kmsboot

Documentation

Overview

Package kmsboot fetches validator staking material from a KMS over native ZAP and injects it into argv as the three canonical `--staking-{mldsa-key,mldsa-pub-key,signer-key}-file-content` flags that luxfi/node's config layer (and every downstream fork) consumes. The bytes never touch disk — they live in argv for the duration of viper's config parse.

kmsboot has zero opinions. It does not validate the path template, it does not enforce a posture, it does not refuse classical coexistence, it does not check blob size. If a value is set, it gets used. If KMS returns garbage, lqd's config layer will reject it downstream — that's where validation belongs, not here.

Trigger: kmsboot is opt-in via the `KMS_ADDR` env var. When unset, `Inject` returns argv unchanged. When set, kmsboot dials and fetches; everything else (env, path template, pod name) is read from env and used as-is.

Quickstart

In any Lux-based binary's main():

argv := os.Args[1:]
if newArgv, err := kmsboot.Inject(context.Background(), argv); err != nil {
    fmt.Fprintf(os.Stderr, "kmsboot: %s\n", err)
    os.Exit(1)
} else {
    argv = newArgv
}
// ... rest of node init

Env vars

KMS_ADDR                  KMS host:port (e.g. kms.lux.svc:9999).
                          Empty = kmsboot is a no-op.
KMS_ENV                   KMS env slug (used as the env dimension
                          of GetAt). Empty = "".
STAKING_KMS_PATH_TEMPLATE Per-ord path. `{ord}` is substituted
                          with this pod's StatefulSet ordinal.
                          Empty = "".
POD_NAME                  metadata.name; the ordinal is the suffix
                          after the last `-`. Empty = ordinal 0.

Index

• Constants
• func Inject(ctx context.Context, argv []string) ([]string, error)
• func InjectWithFetcher(ctx context.Context, fetcher Fetcher, argv []string) ([]string, error)
• func PodOrdinal(podName string) (int, error)
• type Fetcher
  • func DefaultFetcher(ctx context.Context, addr, env string) (Fetcher, error)

Constants

const (
	EnvKMSAddr      = "KMS_ADDR"
	EnvKMSEnv       = "KMS_ENV"
	EnvPathTemplate = "STAKING_KMS_PATH_TEMPLATE"
	EnvPodName      = "POD_NAME"
)

Env var names consumed by Inject.

const (
	BlobMLDSAKey    = "mldsa.key"
	BlobMLDSAPubKey = "mldsa.pub"
	BlobSignerKey   = "signer.key"
)

Blob names under the per-ord path.

const (
	FlagMLDSAKeyContent    = "--staking-mldsa-key-file-content"
	FlagMLDSAPubKeyContent = "--staking-mldsa-pub-key-file-content"
	FlagSignerKeyContent   = "--staking-signer-key-file-content"
)

Upstream luxfi/node content-flag names. The same flags work for any Lux-derived binary that consumes the upstream config layer.

Functions

func Inject

func Inject(ctx context.Context, argv []string) ([]string, error)

Inject is the entry point. Reads env vars, dials KMS, fetches the three blobs, prepends `--staking-*-file-content=<base64>` flags to argv. Returns argv unchanged when EnvKMSAddr is unset.

All env values are used as-is — no validation, no defaulting, no posture enforcement. If your path template is malformed, lqd's config layer will complain about it after viper parses argv. That's the right place for that error.

func InjectWithFetcher

func InjectWithFetcher(ctx context.Context, fetcher Fetcher, argv []string) ([]string, error)

InjectWithFetcher does the fetch + inject given an explicit Fetcher. All env reads happen here (path template, pod name) so a test fake can run the same code path without touching the network.

func PodOrdinal

func PodOrdinal(podName string) (int, error)

PodOrdinal extracts the StatefulSet pod ordinal from a metadata.name like `lqd-3` (→ 3) or `hanzo-validator-12` (→ 12). The suffix after the LAST `-` is the ordinal. Returns (0, nil) for an empty pod name; returns (0, err) for a malformed suffix so callers who want to fail loud can.

Types

type Fetcher

type Fetcher interface {
	Get(ctx context.Context, path, name string) ([]byte, error)
	Close()
}

Fetcher is the surface kmsboot uses to pull blobs from KMS. The default implementation (returned by DefaultFetcher) wraps `github.com/luxfi/kms/pkg/zapclient`; tests substitute a fake.

func DefaultFetcher

func DefaultFetcher(ctx context.Context, addr, env string) (Fetcher, error)

DefaultFetcher dials a KMS over native ZAP at the given addr with the given env scope (env is bound at construction so it can't drift across the connection boundary).