@zamatica/auth-cli

Admin + user CLI commands for the zamatica fleet-env cert auth scheme. Hosted as a library — consumers side-effect-import this package's command modules to register them with @zamatica/bootstrap's commander program.

Phase 1 commands (this lib's current surface)

| Command | Purpose | |---|---| | init-root --fleet-env <env> | Generate root keypair + CRL-signer subkey + trust bundle for a new fleet-env. Writes to ~/.<acronym>-admin/<fleet-env>/. Loud warning to MOVE the root private key offline. | | sign-user --name <user> --fleet-env <env> [--pubkey <path>] [--roles <comma-sep>] [--expires <duration>] | Issue a user cert signed by the fleet-env's root. If --pubkey is omitted, also generates a user keypair (with a loud warning about protecting it). Writes <user>@<acronym>.<fleet-env>.access.json. |

Future commands (per the auth design plan): revoke-user, publish-crl, emergency-extend, rotate-root, list-users, list-revoked, renewals-due, export-ci-cert, login, logout, whoami, remote add/list/remove/default/inspect, audit.

How a consumer registers these commands

// In your app's CLI bootstrap (e.g. apps/headless/src/cli/bootstrap.ts):
import { bootstrap as bootstrapApp } from '@zamatica/bootstrap';
import { APP_IDENTITY } from '../shared/app-manifest.js';

// Side-effect imports register every @CliCommand decorator in the lib.
import '@zamatica/auth-cli';

// Plus the consumer's own commands:
import './commands/status.js';
import './commands/install.js';

export async function runCli(argv: readonly string[]): Promise<void> {
  const { run } = bootstrapApp(APP_IDENTITY);
  await run(argv);
}

The @CliCommand decorator on each command pushes into @zamatica/bootstrap's module-singleton registry at import time. As long as the imports run BEFORE bootstrap(), commander sees them all when building the program.

fleet-env naming

The --fleet-env <env> argument is a flat string carrying a compound concept: a fleet identifier plus its target deployment environment. Examples: prod-internal, acme-staging, local-dev. Code treats it as opaque — no parsing or decomposition. The trust bundle's fleetEnv field, the cert's fleetEnv field, and the daemon's MTZ_FLEET_ENV env var all consume the same string.

Output layout

init-root --fleet-env <env> writes (relative to ~/.<acronym>-admin/<env>/):

<acronym>.<env>.private.pem               ← ROOT private key (MOVE OFFLINE immediately)
<acronym>.<env>.public.pem                ← ROOT public key (bake into daemon deploys)
<acronym>.<env>.crl-signer.private.pem    ← CRL signer (day-to-day signing happens with this)
<acronym>.<env>.crl-signer.public.pem
<acronym>.<env>.trust-bundle.json         ← roots + crl signer + roleMap; daemons load this

sign-user --name <user> --fleet-env <env> writes (when --pubkey is omitted, the keypair lives next to the cert):

<user>.<acronym>.<env>.private.pem        ← USER private key (give to the user; warn them)
<user>.<acronym>.<env>.public.pem         ← USER public key
<user>@<acronym>.<env>.access.json        ← signed cert (distribute via Slack DM, 1Password, etc.)

Development

bunx nx build auth-cli
bunx nx test auth-cli