196 lines
14 KiB
Markdown
196 lines
14 KiB
Markdown
# @suaveplan/server-keys - Operator-facing CLI bundle for the Suaveplan server-key lifecycle: 18 bins covering root + server keychain generation (including hierarchical ChainedKeySigner chains), encrypted vault persistence via @suaveplan/crypto-vault, key rotation, vault/key viewing, signed file packet preparation/serving/validation via @suaveplan/packer + @suaveplan/storage-file, and license issuance via @suaveplan/license. suaveplan-enterprise additions: SuaveplanError-typed SERVER_KEYS_* codes, OTel command counter + duration histogram, Zod boundary validation, injectable AbortSignal, LoggerLike injection, 100% coverage.
|
|
|
|
Operator-facing CLI bundle for the Suaveplan server-key lifecycle:
|
|
18 bins covering root + server keychain generation (including
|
|
hierarchical `ChainedKeySigner` chains via `@suaveplan/crypto-keys`),
|
|
encrypted vault persistence via `@suaveplan/crypto-vault`, key rotation,
|
|
vault / public-key / chain inspection, signed file packet
|
|
preparation / serving / validation via `@suaveplan/packer`, and license
|
|
issuance via `@suaveplan/license`. suaveplan-enterprise additions:
|
|
`SuaveplanError`-typed `SERVER_KEYS_*` codes, OTel command counter +
|
|
duration histogram, Zod-style input validation, `AbortSignal`
|
|
threading, injectable `LoggerLike`.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [create-root-keys-chain](./src/bin/create-root-keys-chain.md) — Commander entry point for the `create-root-keys-chain` operator command. Parses CLI flags, prompts for any required pas…
|
|
- [create-root-keys](./src/bin/create-root-keys.md) — Commander entry point for the `create-root-keys` operator command. Parses CLI flags, prompts for any required passwords…
|
|
- [create-server-keys-chain](./src/bin/create-server-keys-chain.md) — Commander entry point for the `create-server-keys-chain` operator command. Parses CLI flags, prompts for any required p…
|
|
- [create-server-keys](./src/bin/create-server-keys.md) — Commander entry point for the `create-server-keys` operator command. Parses CLI flags, prompts for any required passwor…
|
|
- [get-file-stats](./src/bin/get-file-stats.md) — Commander entry point for the `get-file-stats` operator command. Parses CLI flags, prompts for any required passwords v…
|
|
- [index](./src/bin/index.md) — Commander entry point for the `index` operator command. Parses CLI flags, prompts for any required passwords via `@suav…
|
|
- [license](./src/bin/license.md) — Commander entry point for the `license` operator command. Parses CLI flags, prompts for any required passwords via `@su…
|
|
- [prepare-file](./src/bin/prepare-file.md) — Commander entry point for the `prepare-file` operator command. Parses CLI flags, prompts for any required passwords via…
|
|
- [roll-server-keys-chain](./src/bin/roll-server-keys-chain.md) — Commander entry point for the `roll-server-keys-chain` operator command. Parses CLI flags, prompts for any required pas…
|
|
- [roll-server-keys](./src/bin/roll-server-keys.md) — Commander entry point for the `roll-server-keys` operator command. Parses CLI flags, prompts for any required passwords…
|
|
- [serve-file](./src/bin/serve-file.md) — Commander entry point for the `serve-file` operator command. Parses CLI flags, prompts for any required passwords via `…
|
|
- [validate-file](./src/bin/validate-file.md) — Commander entry point for the `validate-file` operator command. Parses CLI flags, prompts for any required passwords vi…
|
|
- [validate-packet](./src/bin/validate-packet.md) — Commander entry point for the `validate-packet` operator command. Parses CLI flags, prompts for any required passwords…
|
|
- [verify-key-chain](./src/bin/verify-key-chain.md) — Commander entry point for the `verify-key-chain` operator command. Parses CLI flags, prompts for any required passwords…
|
|
- [view-chain-public](./src/bin/view-chain-public.md) — Commander entry point for the `view-chain-public` operator command. Parses CLI flags, prompts for any required password…
|
|
- [view-keys](./src/bin/view-keys.md) — Commander entry point for the `view-keys` operator command. Parses CLI flags, prompts for any required passwords via `@…
|
|
- [view-public-key-file](./src/bin/view-public-key-file.md) — Commander entry point for the `view-public-key-file` operator command. Parses CLI flags, prompts for any required passw…
|
|
- [view-vault](./src/bin/view-vault.md) — Commander entry point for the `view-vault` operator command. Parses CLI flags, prompts for any required passwords via `…
|
|
- [files](./src/commands/files/files.md) — Local-packer file-transport commands: `prepareFileCommand`, `validateFileCommand`, `getFileStatsCommand`, `validatePack…
|
|
- [files](./src/commands/files/files.md) — Local-packer file-transport commands: `prepareFileCommand`, `validateFileCommand`, `getFileStatsCommand`, `validatePack…
|
|
- [packet-io](./src/commands/files/packet-io.md) — Shared on-disk format helpers for the file-transport commands. Holds the canonical packet envelope `{ data, signature,…
|
|
- [serve-file](./src/commands/files/serve-file.md) — Reconstructs the original file from a directory of prepared packets by verifying each packet's ed25519 signature + sha2…
|
|
- [keys](./src/commands/keys/keys.md) — Non-chain key-lifecycle commands for `@suaveplan/server-keys`. These functions are the library surface every key/view b…
|
|
- [keys-chain](./src/commands/keys/keys-chain.md) — Hierarchical `ChainedKeySigner`-backed key-lifecycle commands. Each chain command wraps the matching crypto-vault orche…
|
|
- [keys-io](./src/commands/keys/keys-io.md) — Private I/O and orchestration-layer helpers shared by every public keys command. Extracted from `keys.ts` to keep each…
|
|
- [keys](./src/commands/keys/keys.md) — Non-chain key-lifecycle commands for `@suaveplan/server-keys`. These functions are the library surface every key/view b…
|
|
- [license](./src/commands/license/license.md) — Wraps `@suaveplan/license` `LicenseManager` into the five sub-commands the operator-facing `license` bin exposes: `keyg…
|
|
- [hex](./src/commands/license/hex.md) — Tiny shared hex encode/decode helpers used by the license sub-commands to serialise and deserialise the secp256k1 key m…
|
|
- [license](./src/commands/license/license.md) — Wraps `@suaveplan/license` `LicenseManager` into the five sub-commands the operator-facing `license` bin exposes: `keyg…
|
|
- [error-codes](./src/error-codes/error-codes.md) — Defines the stable `SERVER_KEYS_*` error-code registry used throughout `@suaveplan/server-keys`. Each code is a namespa…
|
|
- [error-codes](./src/error-codes/error-codes.md) — Defines the stable `SERVER_KEYS_*` error-code registry used throughout `@suaveplan/server-keys`. Each code is a namespa…
|
|
- [otel](./src/otel/instruments.md) — Registers the OpenTelemetry counter and histogram that every CLI command in `@suaveplan/server-keys` emits exactly once…
|
|
- [instruments](./src/otel/instruments.md) — Registers the OpenTelemetry counter and histogram that every CLI command in `@suaveplan/server-keys` emits exactly once…
|
|
- [prompt](./src/prompt/prompt.md) — Thin, test-injectable wrappers around `@inquirer/prompts`' password prompt for the two interactive flows every server-k…
|
|
- [prompt](./src/prompt/prompt.md) — Thin, test-injectable wrappers around `@inquirer/prompts`' password prompt for the two interactive flows every server-k…
|
|
- [run-function](./src/run-function/run-function.md) — `runFunction` is the single wrapper every server-keys CLI bin uses for its commander `.action(...)` body. It standardis…
|
|
- [run-function](./src/run-function/run-function.md) — `runFunction` is the single wrapper every server-keys CLI bin uses for its commander `.action(...)` body. It standardis…
|
|
<!-- end:auto-docs -->
|
|
|
|
## Install
|
|
|
|
```bash
|
|
bun add @suaveplan/server-keys
|
|
# or, to install all 18 bins globally:
|
|
bun link
|
|
```
|
|
|
|
## Commands
|
|
|
|
| Bin | Purpose |
|
|
| --- | --- |
|
|
| `suaveplan` | Top-level dispatcher routing to the 17 sub-commands below |
|
|
| `create-root-keys` | Create root keychain (vault + signed public-key file) |
|
|
| `create-root-keys-chain` | Create root keychain with self-signed chain |
|
|
| `create-server-keys` | Derive a server keychain from a root vault |
|
|
| `create-server-keys-chain` | Derive a chained server keychain |
|
|
| `roll-server-keys` | Rotate a server keychain to `currentVersion + 1` |
|
|
| `roll-server-keys-chain` | Rotate a chained server keychain to `currentVersion + 1` |
|
|
| `verify-key-chain` | Verify a chain file against a trusted root file |
|
|
| `view-keys` | Decrypt a vault and print a keychain summary |
|
|
| `view-vault` | Print vault file metadata without decryption |
|
|
| `view-public-key-file` | Decode and print a signed public-key file |
|
|
| `view-chain-public` | Decode a public-key file with optional signature verification |
|
|
| `prepare-file` | Pack a file into signed packets under an output directory |
|
|
| `serve-file` | Reconstruct a file from prepared packets (byte-identical) |
|
|
| `validate-file` | Walk every packet in a prepared directory and verify integrity |
|
|
| `get-file-stats` | Print file packing statistics without packing |
|
|
| `validate-packet` | Validate a single packet against an explicit verify key |
|
|
| `license` | Generate / validate / parse / revoke software license keys |
|
|
|
|
## Programmatic-API quick-start
|
|
|
|
```ts
|
|
import {
|
|
createRootKeysCommand,
|
|
createServerKeysCommand,
|
|
} from "@suaveplan/server-keys/commands/keys/keys";
|
|
import {
|
|
prepareFileCommand,
|
|
} from "@suaveplan/server-keys/commands/files/files";
|
|
import { serveFileCommand } from "@suaveplan/server-keys/commands/files/serve-file";
|
|
import {
|
|
keygen,
|
|
generate,
|
|
validate,
|
|
} from "@suaveplan/server-keys/commands/license/license";
|
|
import { runFunction } from "@suaveplan/server-keys/run-function";
|
|
|
|
// Provision keys
|
|
await createRootKeysCommand("rootpw1234", { output: "./keys" });
|
|
await createServerKeysCommand(
|
|
"./keys/root.vault",
|
|
"rootpw1234",
|
|
"serverpw1234",
|
|
{ output: "./keys" },
|
|
);
|
|
|
|
// Prepare + serve a file with cooperative abort
|
|
const ac = new AbortController();
|
|
await prepareFileCommand(
|
|
"./data.bin",
|
|
"./keys/server.vault",
|
|
"serverpw1234",
|
|
{ output: "./prepared", packetSize: 256 * 1024, signal: ac.signal },
|
|
);
|
|
await serveFileCommand("./prepared", {
|
|
output: "./reconstructed.bin",
|
|
signal: ac.signal,
|
|
});
|
|
|
|
// License lifecycle
|
|
const kp = await keygen("./lic/keys.json", 1);
|
|
const lic = await generate({
|
|
signingKeyPath: "./lic/keys.json",
|
|
productId: 42,
|
|
tier: 2,
|
|
expirationDays: 365,
|
|
});
|
|
const checked = await validate(lic.key, {
|
|
publicKeysPath: "./lic/public-keys.json",
|
|
});
|
|
|
|
// Top-level wrapper for custom CLI integrations
|
|
await runFunction("custom-cmd", async (signal) => {
|
|
// ...your work; OTel + exit(1)-on-fail handled for you
|
|
});
|
|
```
|
|
|
|
## Modules
|
|
|
|
- [`error-codes`](src/error-codes/error-codes.md) — `SERVER_KEYS_*`
|
|
registry + `ServerKeysError`.
|
|
- [`otel/instruments`](src/otel/instruments.md) — counter + histogram +
|
|
`recordCommand`.
|
|
- [`run-function`](src/run-function.md) — top-level `.action(...)`
|
|
wrapper with OTel + structured error + abort plumbing.
|
|
- [`prompt/prompt`](src/prompt/prompt.md) — `promptForPassword`,
|
|
`promptForNewPassword` with injectable seam for tests.
|
|
- [`commands/keys/keys`](src/commands/keys/keys.md) — non-chain keys
|
|
commands.
|
|
- [`commands/keys/keys-chain`](src/commands/keys/keys-chain.md) —
|
|
chain variants + `verifyKeyChainCommand`.
|
|
- [`commands/keys/keys-io`](src/commands/keys/keys-io.md) — shared I/O
|
|
- decryption helpers.
|
|
- [`commands/files/files`](src/commands/files/files.md) — local-packer
|
|
`prepare` / `validate` / `stats` / `validate-packet`.
|
|
- [`commands/files/serve-file`](src/commands/files/serve-file.md) —
|
|
reconstruction.
|
|
- [`commands/files/packet-io`](src/commands/files/packet-io.md) —
|
|
packet wire format helpers.
|
|
- [`commands/license/license`](src/commands/license/license.md) —
|
|
`keygen` / `generate` / `validate` / `parse` / `revoke`.
|
|
- [`commands/license/hex`](src/commands/license/hex.md) — hex
|
|
encode / decode helpers.
|
|
|
|
## Architectural decisions
|
|
|
|
- **Local packer for file-transport bins.** Upstream's
|
|
`prepare-file` / `serve-file` / `validate-file` / `get-file-stats` /
|
|
`validate-packet` are HTTP clients pointed at a separate
|
|
`file-server`. Ships these as local packers backed by
|
|
`@suaveplan/packer`'s whole-file `Packer` / `Unpacker` + plain Node
|
|
`fs`. No network hop, no separate deployment dependency, byte-name
|
|
stable manifest + packet artefacts.
|
|
- **suaveplan-native vault wire format.** Vault and signed-public-key
|
|
files are NOT byte-compatible with the upstream `@suaveplan/keys`
|
|
BitPacker-based format — the crypto-vault orchestration is the
|
|
format owner. A future `@suaveplan/keys-migration` package will
|
|
ship the conversion path.
|
|
- **Plain Node `fs` instead of `@suaveplan/storage-file` for vault I/O.**
|
|
storage-file appends `.data` / `.meta` extensions to every key
|
|
on write, which would force operator scripts to address artefacts by
|
|
`root.vault.data` instead of the conventional `root.vault`. The CLI
|
|
contract is byte-name-stable across upstream and suaveplan.
|
|
- **Vault sign slot = ed25519, license sign slot = secp256k1.** The
|
|
license format requires secp256k1; the vault's sign slot is
|
|
ed25519. The license bin therefore uses its own `keygen` sub-command
|
|
rather than trying to reuse the vault's signing key.
|
|
|