suaveplan/openspec/archive/2026-05-18-enterprise-server-keys/tasks.md

# Tasks — enterprise-server-keys

## 1. Scaffold

- [ ] 1.1 Create `packages/security/server-keys/{src/{bin,commands/{keys,files,license},prompt,otel},tests/{integration,setup}}/` tree
- [ ] 1.2 `package.json` v0.1.0, `type: module`, `sideEffects: false`, 18 `bin` entries, full subpath `exports` map
  - Deps: `@suaveplan/error` `@suaveplan/types` `@suaveplan/crypto` `@suaveplan/crypto-keys` `@suaveplan/crypto-hash` `@suaveplan/crypto-utils` `@suaveplan/crypto-vault` `@suaveplan/license` `@suaveplan/storage` `@suaveplan/storage-file` `@suaveplan/packer` `@suaveplan/bitpacker` `@suaveplan/logger` (all `workspace:^`), `@opentelemetry/api` (`catalog:observability`), `zod` (`catalog:forms`), `tslib` (`catalog:build`), `@inquirer/prompts` (catalog), `commander` (catalog)
  - DevDeps: `@suaveplan/testing` `@vitest/coverage-istanbul` `vitest` `fast-check` (`catalog:testing`), `@types/node` `typescript` (`catalog:`), `vite` `vite-plugin-dts` (`catalog:build`)
- [ ] 1.3 `tsconfig.json` + `tsconfig.lib.json` extending `../../../tsconfig.base.json`
- [ ] 1.4 `vite.config.ts` (dts, ES, externals for `@suaveplan/*` + `tslib` + `zod` + `@opentelemetry/api` + `commander` + `@inquirer/*`)
- [ ] 1.5 `vitest.config.ts` (`pool: forks`, `provider: istanbul`, thresholds 100/100/100/100, `setupFiles: ['./tests/setup/polyfills.ts']`, `testTimeout: 30000` for the integration tests)
- [ ] 1.6 `tests/setup/polyfills.ts` (crypto polyfill for node)
- [ ] 1.7 Confirm `@inquirer/prompts` + `commander` exist in root `package.json` catalogs; add to a new `cli` catalog block if not

## 2. Foundation modules

- [ ] 2.1 `src/error-codes.ts` + `.md` + test — 10 `SERVER_KEYS_*` codes + `ServerKeysError`
- [ ] 2.2 `src/otel/instruments.ts` + `.md` + test — counter `server_keys.command_total{command,outcome}`, histogram `server_keys.command_duration_ms{command}`
- [ ] 2.3 `src/run-function.ts` + `.md` + test — top-level `.action(...)` wrapper that catches/exits, increments OTel, AbortSignal-aware
- [ ] 2.4 `src/prompt/prompt.ts` + `.md` + test — `promptForPassword`, `promptForNewPassword` with injectable `inputStream` for tests

## 3. Command modules (the library surface the bins call into)

- [ ] 3.1 `src/commands/keys/keys.ts` + `.md` + `.test.ts` — port upstream `commands/keys/keys.ts` (628 LOC). Re-point `@suaveplan/keys` calls to `@suaveplan/crypto` + `@suaveplan/crypto-keys`. Functions: `createRootKeysCommand`, `createServerKeysCommand`, `rollServerKeysCommand`, `createRootKeysChainCommand`, `createServerKeysChainCommand`, `rollServerKeysChainCommand`, `verifyKeyChainCommand`, `viewKeysCommand`, `viewVaultCommand`, `viewPublicKeyFileCommand`, `viewChainPublicCommand`
- [ ] 3.2 `src/commands/files/files.ts` + `.md` + `.test.ts` — `prepareFileCommand`, `validateFileCommand`, `getFileStatsCommand`, `validatePacketCommand`
- [ ] 3.3 `src/commands/files/serve-file.ts` + `.md` + `.test.ts` — `serveFileCommand`
- [ ] 3.4 `src/commands/license/license.ts` + `.md` + `.test.ts` — `licenseCommand` with `generate`/`validate`/`parse`/`revoke` sub-commands wrapping `@suaveplan/license` `LicenseManager`

## 4. Bin entry points (one .ts per bin; thin wrappers calling commands)

- [ ] 4.1 `src/bin/index.ts` — `suaveplan` dispatcher with all 17 sub-commands lazy-imported
- [ ] 4.2 `src/bin/create-root-keys.ts`, `create-root-keys-chain.ts`, `create-server-keys.ts`, `create-server-keys-chain.ts`, `roll-server-keys.ts`, `roll-server-keys-chain.ts`, `verify-key-chain.ts`
- [ ] 4.3 `src/bin/view-keys.ts`, `view-vault.ts`, `view-public-key-file.ts`, `view-chain-public.ts`
- [ ] 4.4 `src/bin/prepare-file.ts`, `serve-file.ts`, `validate-file.ts`, `get-file-stats.ts`, `validate-packet.ts`
- [ ] 4.5 `src/bin/license.ts`
- [ ] 4.6 `src/bin/index.test.ts` — asserts every bin parses `--help`

## 5. Tests

- [ ] 5.1 Co-located `*.test.ts` covers every scenario in the spec delta
- [ ] 5.2 `src/server-keys.spec-conformance.test.ts` — pins (a) every `SERVER_KEYS_*` code thrown, (b) Zod boundary wired, (c) OTel instruments fire, (d) `expectTypeOf` on every exported function signature
- [ ] 5.3 `tests/integration/prepare-serve-roundtrip.test.ts` — real temp dir, real `storage-file`, real packer, real crypto — full prepare → serve byte-identical reconstruction
- [ ] 5.4 `tests/integration/end-to-end-chain.test.ts` — real `create-root` → `create-server` → `roll-server` → `verify-chain` happy path + tamper-detection
- [ ] 5.5 `tests/integration/license-bin.test.ts` — real `generate` → `validate` → `revoke` against a real server vault
- [ ] 5.6 `tests/property.test.ts` — fast-check chain round-trip + packet manifest round-trip
- [ ] 5.7 `tests/dep-graph.test.ts` — subpath exports, sibling `.md`, no `export *`, dep allowlist
- [ ] 5.8 Every `it(...)` has `{ timeout: 5000 }` (or 30000 for integration tests)
- [ ] 5.9 All tests import runner from `@suaveplan/testing/runner`

## 6. Documentation

- [ ] 6.1 Sibling `.md` for every implementation `.ts` (≥200 words, basic + advanced examples, full API reference)
- [ ] 6.2 `README.md` — package description, install, all 18 bins listed under `## Commands`, programmatic-API quick-start, Modules section linking every `.md`

## 7. Gates (run in order; stop on first red)

- [ ] 7.1 `bunx turbo lint typecheck test --filter=@suaveplan/server-keys` — green
- [ ] 7.2 `bunx turbo test:coverage --filter=@suaveplan/server-keys` — 100/100/100/100
- [ ] 7.3 `bun scripts/openspec-conformance.ts @suaveplan/server-keys` — exit 0
- [ ] 7.4 `bunx turbo build --filter=@suaveplan/server-keys` — green
- [ ] 7.5 Banned-pattern scan (0 hits): `grep -rn "@deprecated\|TODO\|FIXME\|ts-ignore\|ts-expect-error\|\.skip\|\.only\|\bany\b\|console\.log\|biome-ignore" packages/security/server-keys/src/ --include="*.ts"` (false-positive `any` in JSDoc prose is OK)
- [ ] 7.6 No `export *` in feature barrels (grep gate)
- [ ] 7.7 No direct `vitest`/`bun:test` imports (grep gate)

## 8. Archive

- [ ] 8.1 Fold `specs/server-keys/spec.md` → `openspec/specs/server-keys/spec.md`
- [ ] 8.2 Move `openspec/changes/enterprise-server-keys/` → `openspec/archive/2026-05-17-enterprise-server-keys/`
- [ ] 8.3 Refresh MANIFEST (`bun scripts/folder-reorg/generate-manifest.ts`)
- [ ] 8.4 Update root `STATUS.md` — `@suaveplan/server-keys` `–` → `✅`