@sebastienrousseau/crypto-cli 0.0.8 → 0.0.24

package/README.md

@@ -75,7 +75,23 @@ yarn add @sebastienrousseau/crypto-cli
 
 ## Quick Start
 
-Launch the interactive menu:
+Run a subcommand, for scripts and CI:
+
+```bash
+crypto-cli hash --json < file.txt
+crypto-cli hash --algorithm blake3 file.txt
+crypto-cli cbom scan src --output cbom.json
+
+openssl rand -hex 32 > secret.key && chmod 600 secret.key
+crypto-cli encrypt --key-file secret.key file.txt > file.txt.sealed
+crypto-cli decrypt --key-file secret.key file.txt.sealed > file.txt.out
+
+crypto-cli keygen --algorithm ed25519 --json > signer.json && chmod 600 signer.json
+crypto-cli sign --key-file signer.json file.txt > file.txt.sig
+crypto-cli verify --key-file signer.json --signature-file file.txt.sig file.txt
+```
+
+Run it with no arguments in a terminal for the interactive menu:
 
 ```bash
 cryptocli
@@ -134,8 +150,10 @@ crypto-cli is the command-line interface for the Crypto Service
 Suite. It offers both legacy OpenPGP commands (key generation,
 encryption, decryption, signing, verification, revocation) and
 modern v2 commands using `@noble/*` primitives with post-quantum
-algorithm support. All operations run interactively via a guided
-prompt menu.
+algorithm support. Hashing, key generation, symmetric encryption,
+signing, password hashing and CBOM scan and audit also run as
+non-interactive subcommands with JSON output; every operation is
+available from the interactive menu.
 
 <p align="right"><a href="#contents">Back to Top</a></p>
 
@@ -164,6 +182,670 @@ prompt menu.
 | `Modern Sign`    | Sign and verify with 8 algorithms including ML-DSA          |
 | `Password Hash`  | Hash and verify passwords with 3 Argon2 variants            |
 
+### Non-interactive commands
+
+With arguments, `crypto-cli` runs a subcommand instead of the menu:
+
+- `--json` prints the result as one line of JSON on stdout, and
+  nothing else goes to stdout.
+- A command that takes a file reads standard input when the file is
+  omitted or `-`.
+- Errors, usage and notes go to stderr.
+- Exit codes: `0` success, `1` the operation failed (unreadable input,
+  a cryptographic error, a wrong key or modified ciphertext, a
+  signature or password that does not verify, an invalid CBOM, a CBOM
+  audit with status `FAIL`), `2` usage error (unknown command or
+  option, missing or invalid argument, no key or password source, key
+  and data both on standard input).
+- With no arguments, the interactive menu starts only when stdin and
+  stdout are both terminals; otherwise usage goes to stderr and the
+  exit code is `2`.
+
+Keys and passwords are never command-line values, which other users
+can see in the process list and shells keep in their history:
+
+- `encrypt`, `decrypt`, `sign` and `verify` read the key from
+  `--key-file <path>`, or from standard input with `--key-stdin`, in
+  which case the data must be a file argument (a run with both on
+  standard input exits `2`). `password hash` and `password verify`
+  take `--password-file <path>` or `--password-stdin` in the same way
+  (one trailing line break is ignored), and otherwise ask for the
+  password with a hidden prompt when standard input is a terminal
+  (twice for `password hash`).
+- `encrypt` and `decrypt` use XChaCha20-Poly1305 (crypto-lib's
+  secretbox). The key is 32 bytes, written as 64 hexadecimal
+  characters or raw. `encrypt` prints base64 of the 24-byte nonce,
+  the ciphertext and the 16-byte tag; `decrypt` reads that or the
+  `encrypt --json` line and writes the plaintext bytes unchanged
+  (base64 in its `--json` output).
+- `sign` reads a key pair saved from `keygen --json` (Ed25519,
+  Ed448, P-256, P-384 or ML-DSA) and prints the signature in hex.
+  `verify` reads the same file, or JSON with only `algorithm` and
+  `publicKey`, and prints `valid` or `invalid` (`{"valid": ...}` with
+  `--json`), exiting `1` when the signature does not verify.
+- `password hash` uses Argon2id with crypto-lib's defaults (t=3,
+  m=64 MiB, p=4) and prints a PHC string; `password verify` reads it
+  from a file or standard input.
+- On Linux and macOS, a secret file that its group or other users can
+  read gets a warning on stderr (`chmod 600` it); the command still
+  runs, because secrets mounted by container platforms are often
+  group- or world-readable. Windows has no such mode bits, so nothing
+  is checked there.
+
+The reference below is generated from the command definitions
+(`pnpm run readme:usage`); a test fails when it is out of date.
+
+<!-- cli-usage:start (generated: pnpm run readme:usage) -->
+
+#### `crypto-cli`
+
+```text
+Usage: crypto-cli [options] [command]
+
+Cryptographic operations from the command line. Run without arguments in a
+terminal for the interactive menu.
+
+Options:
+  -V, --version             print the version
+  -h, --help                print help
+
+Commands:
+  hash [options] [file]     Hash a file, or standard input when no file is given
+  keygen [options]          Generate a key pair (the private key is printed to
+                            stdout)
+  encrypt [options] [file]  Encrypt with XChaCha20-Poly1305 and print the sealed
+                            box as base64
+  decrypt [options] [file]  Decrypt the output of encrypt; exits 1 on a wrong
+                            key or modified input
+  sign [options] [file]     Sign a file with a key pair from keygen --json and
+                            print the signature in hex
+  verify [options] [file]   Verify a signature from sign; exits 1 when it is not
+                            valid
+  password                  Hash or verify a password (Argon2id)
+  cbom                      Generate or audit a Cryptographic Bill of Materials
+  stream                    Post-quantum hybrid streaming AEAD operations
+  opaque                    OPAQUE zero-knowledge password authentication (RFC
+                            9807)
+  hpke                      Hybrid Public Key Encryption (HPKE RFC 9180 and PQ
+                            hybrid)
+  kms                       Key Management Service (KMS) operations across
+                            native cloud providers
+```
+
+#### `crypto-cli hash`
+
+```text
+Usage: crypto-cli hash [options] [file]
+
+Hash a file, or standard input when no file is given
+
+Arguments:
+  file                    file to hash; '-' or omitted reads standard input
+
+Options:
+  -a, --algorithm <name>  hash algorithm (choices: "sha256", "sha384", "sha512",
+                          "sha3-256", "sha3-512", "blake2b", "blake3", default:
+                          "sha256")
+  --json                  print the result as one line of JSON
+  -h, --help              print help
+```
+
+#### `crypto-cli keygen`
+
+```text
+Usage: crypto-cli keygen [options]
+
+Generate a key pair (the private key is printed to stdout)
+
+Options:
+  -a, --algorithm <name>  key algorithm (choices: "ed25519", "x25519", "ed448",
+                          "x448", "p256", "p384", "ml-kem-512", "ml-kem-768",
+                          "ml-kem-1024", "ml-dsa-44", "ml-dsa-65", "ml-dsa-87")
+  --kid <id>              key ID (default: thumbprint of the public key)
+  --use <use>             intended key usage (choices: "sig", "enc")
+  --json                  print the key pair as one line of JSON
+  -h, --help              print help
+```
+
+#### `crypto-cli encrypt`
+
+```text
+Usage: crypto-cli encrypt [options] [file]
+
+Encrypt with XChaCha20-Poly1305 and print the sealed box as base64
+
+Arguments:
+  file               file to encrypt; '-' or omitted reads standard input
+
+Options:
+  --key-file <path>  read the key from a file: 32 bytes, as 64 hex characters or
+                     raw
+  --key-stdin        read the key from standard input (the data must then be a
+                     file argument)
+  --json             print the result as one line of JSON
+  -h, --help         print help
+```
+
+#### `crypto-cli decrypt`
+
+```text
+Usage: crypto-cli decrypt [options] [file]
+
+Decrypt the output of encrypt; exits 1 on a wrong key or modified input
+
+Arguments:
+  file               output of encrypt (base64 or its --json line); '-' or
+                     omitted reads standard input
+
+Options:
+  --key-file <path>  read the key from a file: 32 bytes, as 64 hex characters or
+                     raw
+  --key-stdin        read the key from standard input (the data must then be a
+                     file argument)
+  --json             print the result as one line of JSON
+  -h, --help         print help
+```
+
+#### `crypto-cli sign`
+
+```text
+Usage: crypto-cli sign [options] [file]
+
+Sign a file with a key pair from keygen --json and print the signature in hex
+
+Arguments:
+  file               file to sign; '-' or omitted reads standard input
+
+Options:
+  --key-file <path>  read the key pair from a file: keygen --json output
+                     (ed25519, ed448, p256, p384, ml-dsa-44, ml-dsa-65,
+                     ml-dsa-87)
+  --key-stdin        read the key pair from standard input (the data must then
+                     be a file argument)
+  --json             print the result as one line of JSON
+  -h, --help         print help
+```
+
+#### `crypto-cli verify`
+
+```text
+Usage: crypto-cli verify [options] [file]
+
+Verify a signature from sign; exits 1 when it is not valid
+
+Arguments:
+  file                     file to verify; '-' or omitted reads standard input
+
+Options:
+  --key-file <path>        read the public key from a file: keygen --json
+                           output, or JSON with algorithm and publicKey
+  --key-stdin              read the public key from standard input (the data
+                           must then be a file argument)
+  --signature <hex>        the signature, in hex
+  --signature-file <path>  read the signature from a file (sign output or its
+                           --json line)
+  --json                   print the result as one line of JSON
+  -h, --help               print help
+```
+
+#### `crypto-cli password`
+
+```text
+Usage: crypto-cli password [options] [command]
+
+Hash or verify a password (Argon2id)
+
+Options:
+  -h, --help               print help
+
+Commands:
+  hash [options]           Hash a password with Argon2id (crypto-lib defaults:
+                           t=3, m=64 MiB, p=4) and print its PHC string
+  verify [options] [file]  Check a password against a PHC string; exits 1 when
+                           it does not match
+```
+
+#### `crypto-cli password hash`
+
+```text
+Usage: crypto-cli password hash [options]
+
+Hash a password with Argon2id (crypto-lib defaults: t=3, m=64 MiB, p=4) and
+print its PHC string
+
+Options:
+  --password-file <path>  read the password from a file: one trailing line break
+                          is ignored
+  --password-stdin        read the password from standard input
+  --json                  print the result as one line of JSON
+  -h, --help              print help
+```
+
+#### `crypto-cli password verify`
+
+```text
+Usage: crypto-cli password verify [options] [file]
+
+Check a password against a PHC string; exits 1 when it does not match
+
+Arguments:
+  file                    PHC string (password hash output or its --json line);
+                          '-' or omitted reads standard input
+
+Options:
+  --password-file <path>  read the password from a file: one trailing line break
+                          is ignored
+  --password-stdin        read the password from standard input (the data must
+                          then be a file argument)
+  --json                  print the result as one line of JSON
+  -h, --help              print help
+```
+
+#### `crypto-cli cbom`
+
+```text
+Usage: crypto-cli cbom [options] [command]
+
+Generate or audit a Cryptographic Bill of Materials
+
+Options:
+  -h, --help                  print help
+
+Commands:
+  scan [options] [directory]  Scan source code and print its CBOM
+  audit [options] [file]      Validate and audit a CBOM; exits 1 when the audit
+                              status is FAIL
+```
+
+#### `crypto-cli cbom scan`
+
+```text
+Usage: crypto-cli cbom scan [options] [directory]
+
+Scan source code and print its CBOM
+
+Arguments:
+  directory              directory or file to scan (default: ".")
+
+Options:
+  -f, --format <format>  CBOM standard (choices: "cyclonedx", "spdx", default:
+                         "cyclonedx")
+  -o, --output <file>    write the CBOM to a file, not stdout
+  --json                 print the CBOM as one line of JSON
+  -h, --help             print help
+```
+
+#### `crypto-cli cbom audit`
+
+```text
+Usage: crypto-cli cbom audit [options] [file]
+
+Validate and audit a CBOM; exits 1 when the audit status is FAIL
+
+Arguments:
+  file                 CBOM JSON file; '-' or omitted reads standard input
+
+Options:
+  -o, --output <file>  write the audit report to a file, not stdout
+  --json               print the audit report as one line of JSON
+  -h, --help           print help
+```
+
+#### `crypto-cli stream`
+
+```text
+Usage: crypto-cli stream [options] [command]
+
+Post-quantum hybrid streaming AEAD operations
+
+Options:
+  -h, --help                      print help
+
+Commands:
+  encrypt [options] [file]        Encrypt with post-quantum hybrid STREAM AEAD
+                                  (X25519 + ML-KEM-768)
+  decrypt [options] [file]        Decrypt post-quantum hybrid STREAM ciphertext;
+                                  exits 1 on error
+  multi-encrypt [options] [file]  Encrypt for multiple recipients with
+                                  post-quantum hybrid STREAM AEAD
+  multi-decrypt [options] [file]  Decrypt multi-recipient post-quantum hybrid
+                                  STREAM ciphertext; exits 1 on error
+  help [command]                  display help for command
+```
+
+#### `crypto-cli stream encrypt`
+
+```text
+Usage: crypto-cli stream encrypt [options] [file]
+
+Encrypt with post-quantum hybrid STREAM AEAD (X25519 + ML-KEM-768)
+
+Arguments:
+  file                       file to encrypt; '-' or omitted reads standard
+                             input
+
+Options:
+  -x, --x25519-public <hex>  recipient X25519 public key (hex)
+  -m, --ml-kem-public <hex>  recipient ML-KEM-768 public key (hex)
+  -c, --chunk-size <bytes>   chunk size in bytes (minimum 64, default 65536)
+  --json                     print the result as one line of JSON
+  -h, --help                 print help
+```
+
+#### `crypto-cli stream decrypt`
+
+```text
+Usage: crypto-cli stream decrypt [options] [file]
+
+Decrypt post-quantum hybrid STREAM ciphertext; exits 1 on error
+
+Arguments:
+  file                       output of stream encrypt (base64 or its --json
+                             line)
+
+Options:
+  -x, --x25519-secret <hex>  recipient X25519 secret key (hex)
+  -m, --ml-kem-secret <hex>  recipient ML-KEM-768 secret key (hex)
+  -c, --chunk-size <bytes>   chunk size in bytes
+  --json                     print the result as one line of JSON
+  -h, --help                 print help
+```
+
+#### `crypto-cli stream multi-encrypt`
+
+```text
+Usage: crypto-cli stream multi-encrypt [options] [file]
+
+Encrypt for multiple recipients with post-quantum hybrid STREAM AEAD
+
+Arguments:
+  file                             file to encrypt; '-' or omitted reads
+                                   standard input
+
+Options:
+  -r, --recipients <json-or-path>  JSON array string or file path containing
+                                   recipient public key descriptors
+  -c, --chunk-size <bytes>         chunk size in bytes (minimum 1024, default
+                                   65536)
+  --json                           print the result as one line of JSON
+  -h, --help                       print help
+```
+
+#### `crypto-cli stream multi-decrypt`
+
+```text
+Usage: crypto-cli stream multi-decrypt [options] [file]
+
+Decrypt multi-recipient post-quantum hybrid STREAM ciphertext; exits 1 on error
+
+Arguments:
+  file                       output of stream multi-encrypt (base64 or its
+                             --json line)
+
+Options:
+  -x, --x25519-secret <hex>  recipient X25519 secret key (hex)
+  -m, --ml-kem-secret <hex>  recipient ML-KEM-768 secret key (hex)
+  -i, --recipient-id <id>    optional recipient identifier for direct slot
+                             lookup
+  -c, --chunk-size <bytes>   chunk size in bytes
+  --json                     print the result as one line of JSON
+  -h, --help                 print help
+```
+
+#### `crypto-cli opaque`
+
+```text
+Usage: crypto-cli opaque [options] [command]
+
+OPAQUE zero-knowledge password authentication (RFC 9807)
+
+Options:
+  -h, --help               print help
+
+Commands:
+  setup [options]          Generate server long-term keys and fake record
+  register [options] <id>  Register a password with an OPAQUE server
+  login [options] <id>     Authenticate against an OPAQUE server
+```
+
+#### `crypto-cli opaque setup`
+
+```text
+Usage: crypto-cli opaque setup [options]
+
+Generate server long-term keys and fake record
+
+Options:
+  -s, --suite <name>  ciphersuite (choices: "P256-SHA256",
+                      "ristretto255-SHA512", default: "P256-SHA256")
+  --json              print result as JSON
+  -h, --help          print help
+```
+
+#### `crypto-cli opaque register`
+
+```text
+Usage: crypto-cli opaque register [options] <id>
+
+Register a password with an OPAQUE server
+
+Options:
+  -u, --server-url <url>  server base URL
+  -s, --suite <name>      ciphersuite (choices: "P256-SHA256",
+                          "ristretto255-SHA512", default: "P256-SHA256")
+  --json                  print result as JSON
+  --password-file <path>  read the password from a file: one trailing line break
+                          is ignored
+  --password-stdin        read the password from standard input
+  -h, --help              print help
+```
+
+#### `crypto-cli opaque login`
+
+```text
+Usage: crypto-cli opaque login [options] <id>
+
+Authenticate against an OPAQUE server
+
+Options:
+  -u, --server-url <url>  server base URL
+  -s, --suite <name>      ciphersuite (choices: "P256-SHA256",
+                          "ristretto255-SHA512", default: "P256-SHA256")
+  --json                  print result as JSON
+  --password-file <path>  read the password from a file: one trailing line break
+                          is ignored
+  --password-stdin        read the password from standard input
+  -h, --help              print help
+```
+
+#### `crypto-cli hpke`
+
+```text
+Usage: crypto-cli hpke [options] [command]
+
+Hybrid Public Key Encryption (HPKE RFC 9180 and PQ hybrid)
+
+Options:
+  -h, --help             print help
+
+Commands:
+  keygen [options]       Generate an HPKE key pair
+  seal [options] [file]  Encrypt a message using HPKE
+  open [options] [file]  Decrypt an HPKE ciphertext
+  help [command]         display help for command
+```
+
+#### `crypto-cli hpke keygen`
+
+```text
+Usage: crypto-cli hpke keygen [options]
+
+Generate an HPKE key pair
+
+Options:
+  -k, --kem <kem>  key encapsulation mechanism (choices: "x25519-ml-kem-768",
+                   "x25519", "p256", default: "x25519-ml-kem-768")
+  --json           print key pair as JSON
+  -h, --help       print help
+```
+
+#### `crypto-cli hpke seal`
+
+```text
+Usage: crypto-cli hpke seal [options] [file]
+
+Encrypt a message using HPKE
+
+Options:
+  -p, --public-key <hex>  recipient public key (hex)
+  -k, --kem <kem>         key encapsulation mechanism (choices:
+                          "x25519-ml-kem-768", "x25519", "p256", default:
+                          "x25519-ml-kem-768")
+  -a, --aead <aead>       authenticated encryption algorithm (choices:
+                          "chacha20-poly1305", "aes-128-gcm", default:
+                          "chacha20-poly1305")
+  --info <info>           application-supplied info string
+  --aad <aad>             additional authenticated data
+  --json                  print ciphertext and encapsulated key as JSON
+  -h, --help              print help
+```
+
+#### `crypto-cli hpke open`
+
+```text
+Usage: crypto-cli hpke open [options] [file]
+
+Decrypt an HPKE ciphertext
+
+Options:
+  -s, --secret-key <hex>        recipient private key (hex)
+  -e, --encapsulated-key <hex>  encapsulated key (hex)
+  -k, --kem <kem>               key encapsulation mechanism (choices:
+                                "x25519-ml-kem-768", "x25519", "p256", default:
+                                "x25519-ml-kem-768")
+  -a, --aead <aead>             authenticated encryption algorithm (choices:
+                                "chacha20-poly1305", "aes-128-gcm", default:
+                                "chacha20-poly1305")
+  --info <info>                 application-supplied info string
+  --aad <aad>                   additional authenticated data
+  --json                        print plaintext and hex as JSON
+  -h, --help                    print help
+```
+
+#### `crypto-cli kms`
+
+```text
+Usage: crypto-cli kms [options] [command]
+
+Key Management Service (KMS) operations across native cloud providers
+
+Options:
+  -h, --help                   print help
+
+Commands:
+  create-key [options]         Create a new managed key in KMS
+  generate-data-key [options]  Generate a Data Encryption Key (DEK) via KMS
+  wrap [options] [file]        Wrap (encrypt) a key using a KMS key
+  unwrap [options] [file]      Unwrap a wrapped key using a KMS key
+  encrypt [options] [file]     Encrypt data using a KMS key
+  decrypt [options] [file]     Decrypt ciphertext using a KMS key
+  help [command]               display help for command
+```
+
+#### `crypto-cli kms create-key`
+
+```text
+Usage: crypto-cli kms create-key [options]
+
+Create a new managed key in KMS
+
+Options:
+  -a, --algorithm <alg>  Key algorithm (default: "aes-256-gcm")
+  -u, --usage <usage>    Key usage (choices: "encrypt", "sign", "wrap", default:
+                         "encrypt")
+  -p, --provider <name>  KMS provider (local, aws, gcp, vault, azure) (default:
+                         "local")
+  --json                 Emit output as JSON
+  -h, --help             print help
+```
+
+#### `crypto-cli kms generate-data-key`
+
+```text
+Usage: crypto-cli kms generate-data-key [options]
+
+Generate a Data Encryption Key (DEK) via KMS
+
+Options:
+  -k, --key-id <id>      Key ID
+  -s, --key-spec <spec>  Key spec (e.g. AES_256) (default: "AES_256")
+  -p, --provider <name>  KMS provider (default: "local")
+  --json                 Emit output as JSON
+  -h, --help             print help
+```
+
+#### `crypto-cli kms wrap`
+
+```text
+Usage: crypto-cli kms wrap [options] [file]
+
+Wrap (encrypt) a key using a KMS key
+
+Options:
+  -k, --key-id <id>      Wrapping Key ID
+  -w, --key <hex>        Raw key material to wrap
+  -p, --provider <name>  KMS provider (default: "local")
+  --json                 Emit output as JSON
+  -h, --help             print help
+```
+
+#### `crypto-cli kms unwrap`
+
+```text
+Usage: crypto-cli kms unwrap [options] [file]
+
+Unwrap a wrapped key using a KMS key
+
+Options:
+  -k, --key-id <id>        Wrapping Key ID
+  -w, --wrapped-key <str>  Wrapped key string
+  -p, --provider <name>    KMS provider (default: "local")
+  --json                   Emit output as JSON
+  -h, --help               print help
+```
+
+#### `crypto-cli kms encrypt`
+
+```text
+Usage: crypto-cli kms encrypt [options] [file]
+
+Encrypt data using a KMS key
+
+Options:
+  -k, --key-id <id>      Key ID
+  -d, --data <text>      Plaintext data to encrypt
+  -p, --provider <name>  KMS provider (default: "local")
+  --json                 Emit output as JSON
+  -h, --help             print help
+```
+
+#### `crypto-cli kms decrypt`
+
+```text
+Usage: crypto-cli kms decrypt [options] [file]
+
+Decrypt ciphertext using a KMS key
+
+Options:
+  -k, --key-id <id>       Key ID
+  -c, --ciphertext <str>  Ciphertext to decrypt
+  -p, --provider <name>   KMS provider (default: "local")
+  --json                  Emit output as JSON
+  -h, --help              print help
+```
+
+<!-- cli-usage:end -->
+
 <p align="right"><a href="#contents">Back to Top</a></p>
 
 ## Configuration