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 – → ✅