Initial Commit

openspec/specs/crypto-bin/spec.md

@@ -0,0 +1,61 @@
+# crypto-bin Specification
+
+## Purpose
+
+TBD - created by archiving change crypto-completion. Update Purpose after archive.
+
+## Requirements
+
+### Requirement: hash-password CLI hash mode
+
+The package SHALL ship a `suaveplan-hash-password` bin that, when invoked with `--password <pw>` and no `--verify`, hashes the password using the requested algorithm (default `argon2id`, opt-in `--algo blake2b`) and writes the resulting stored-hash string to stdout, exiting with code 0. The CLI SHALL route through `@suaveplan/cli`'s arg parser (so `--help` works automatically) and SHALL NEVER call `process.exit` directly — it SHALL use `cli.exit(code)` to keep test harness compatibility.
+
+#### Scenario: argon2id mode prints stored hash
+
+- **WHEN** `suaveplan-hash-password --password "correct horse battery staple"` is invoked
+- **THEN** stdout contains a string starting with `"$argon2id$"` AND the exit code is 0
+
+#### Scenario: blake2b mode prints stored hash
+
+- **WHEN** `suaveplan-hash-password --password "..." --algo blake2b` is invoked
+- **THEN** stdout contains a string starting with `"$blake2b$"` AND the exit code is 0
+
+**Verified by:** `packages/crypto/crypto-bin/src/hash-password/hash-password.test.ts::"argon2id mode writes a $argon2id$-prefixed hash to stdout and exits 0"` AND `packages/crypto/crypto-bin/src/hash-password/hash-password.test.ts::"blake2b mode writes a $blake2b$-prefixed hash to stdout and exits 0"`
+
+---
+
+### Requirement: hash-password CLI verify mode
+
+When invoked with `--password <pw>` and `--verify <stored>`, the bin SHALL detect the algorithm from the stored hash's prefix, run the matching verify function (`verifyPasswordArgon2id` or `verifyPasswordBlake2b`), exit with code 0 on match and code 1 on mismatch. The bin SHALL NOT print anything to stdout in verify mode (so the exit code is the only signal — suitable for use in shell pipelines).
+
+#### Scenario: matching password exits 0
+
+- **WHEN** the stored hash and the password agree
+- **THEN** the exit code is 0 AND stdout is empty
+
+#### Scenario: non-matching password exits 1
+
+- **WHEN** the stored hash and the password disagree
+- **THEN** the exit code is 1 AND stdout is empty
+
+**Verified by:** `packages/crypto/crypto-bin/src/hash-password/hash-password.test.ts::"verify mode exits 0 when password matches stored hash"` AND `packages/crypto/crypto-bin/src/hash-password/hash-password.test.ts::"verify mode exits 1 when password does not match stored hash"`
+
+---
+
+### Requirement: hash-password CLI argument validation
+
+The bin SHALL reject malformed invocations (missing `--password`, unknown `--algo`, malformed `--verify` value) with a non-zero exit code and a `SuaveplanError` whose code is one of `CRYPTO.HASH_PASSWORD_CLI_BAD_ARGS`, `CRYPTO.HASH_PASSWORD_CLI_UNKNOWN_ALGO`, or `CRYPTO.HASH_PASSWORD_CLI_VERIFY_FAILED`. The error message SHALL be human-readable and SHALL be printed to stderr (not stdout, so it does not contaminate pipe output).
+
+#### Scenario: missing --password rejected
+
+- **WHEN** `suaveplan-hash-password` is invoked with no `--password`
+- **THEN** the exit code is non-zero AND stderr mentions `--password` AND the underlying error code is `CRYPTO.HASH_PASSWORD_CLI_BAD_ARGS`
+
+#### Scenario: unknown algorithm rejected
+
+- **WHEN** `suaveplan-hash-password --password pw --algo bcrypt` is invoked
+- **THEN** the exit code is non-zero AND the underlying error code is `CRYPTO.HASH_PASSWORD_CLI_UNKNOWN_ALGO` AND `context.algo === "bcrypt"`
+
+**Verified by:** `packages/crypto/crypto-bin/src/hash-password/hash-password.spec-conformance.test.ts::"missing --password emits HASH_PASSWORD_CLI_BAD_ARGS"` AND `packages/crypto/crypto-bin/src/hash-password/hash-password.spec-conformance.test.ts::"unknown --algo emits HASH_PASSWORD_CLI_UNKNOWN_ALGO"`
+
+<!-- markdownlint-enable MD024 -->