Skip to content

Latest commit

 

History

History
691 lines (555 loc) · 26.1 KB

CLI.md

File metadata and controls

691 lines (555 loc) · 26.1 KB

pqforge CLI Guide

The pqforge executable is for local machines, server jobs, release pipelines, and admin workflows that need post-quantum encryption or signatures without writing an app first.

Install it from pub.dev:

dart pub global activate pqforge

Or from a local checkout, or run it in place without installing:

dart pub global activate --source path .   # from a clone
dart run pqforge --help                    # no install, inside the repo

Uninstall

pqforge uninstall removes the install however you set it up: for a global pub install it runs dart pub global deactivate pqforge for you; for a downloaded standalone binary it prints the path to delete.

pqforge uninstall            # confirm, then remove a global pub install
pqforge uninstall --dry-run  # show what would happen, change nothing
pqforge uninstall --yes      # skip the confirmation prompt

The plain pub equivalent is dart pub global deactivate pqforge.

Key Storage

keygen writes reusable keys into the directory passed to --out-dir.

By default keygen emits the full hybrid keyset — ML-KEM + ML-DSA, a profile-matched SLH-DSA SHAKE-f key, plus the classical X25519, Ed25519, and ECDSA-P256 keypairs — so hybrid encryption, hybrid signing, and hash-based signatures work out of the box. --classical <algo> narrows the classical set, --no-classical keeps the post-quantum bundle, --classical-only emits just the classical keys, --slh-dsa <set> selects specific FIPS 205 parameter sets, --no-slh-dsa skips hash-based keys, and --slh-dsa-only emits only SLH-DSA (see Classical Keys and SLH-DSA Keys).

Public keys are not secret:

  • <key-id>.kem.public.json
  • <key-id>.sign.public.json
  • <key-id>.slh-dsa-shake-128f.public.json (compact; balanced uses 192f, maximum 256f)
  • <key-id>.x25519.public.json, <key-id>.ed25519.public.json, <key-id>.ecdsa-p256.public.json

Secret keys should be wrapped:

  • <key-id>.kem.secret.wrapped.json
  • <key-id>.sign.secret.wrapped.json
  • <key-id>.slh-dsa-shake-128f.secret.wrapped.json
  • <key-id>.x25519.secret.wrapped.json, <key-id>.ed25519.secret.wrapped.json, <key-id>.ecdsa-p256.secret.wrapped.json

Wrapped secret keys use PqWrappedKey: Argon2id derives a wrapping key from the passphrase, and AES-256-GCM encrypts the secret key bytes with authenticated metadata. With --passphrase-env the wraps run on a small isolate pool (--wrap-concurrency, default 2).

export PQFORGE_PASSPHRASE='load-this-from-a-secret-manager'
dart run pqforge keygen \
  --profile maximum \
  --key-id vault \
  --out-dir keys \
  --passphrase-env PQFORGE_PASSPHRASE

Passphrase sources:

Option Use
--passphrase-env NAME CI/server jobs where NAME is populated by a secret manager
--passphrase-file path Local scripts that read from protected files
--passphrase value Short-lived testing only; it can leak through shell history

If no passphrase source is supplied, keygen writes raw secret-key JSON and prints a warning. Use raw secret files only for disposable tests.

File Encryption

dart run pqforge encrypt \
  --recipient-public keys/vault.kem.public.json \
  --profile maximum \
  --in report.pdf \
  --out report.pdf.pqf

dart run pqforge decrypt \
  --recipient-secret keys/vault.kem.secret.wrapped.json \
  --passphrase-env PQFORGE_PASSPHRASE \
  --in report.pdf.pqf \
  --out report.open.pdf

The file name is bound into structured pqforge/file/v1 AAD. If you pass --aad, that value is also bound into the envelope and must be supplied again for decryption.

Folder Encryption

Folder encryption writes one .pqf envelope per file and preserves relative paths.

dart run pqforge encrypt-folder \
  --recipient-public keys/vault.kem.public.json \
  --profile maximum \
  --in-dir ./records \
  --out-dir ./records.pqf \
  --aad tenant:county-a

dart run pqforge decrypt-folder \
  --recipient-secret keys/vault.kem.secret.wrapped.json \
  --passphrase-env PQFORGE_PASSPHRASE \
  --in-dir ./records.pqf \
  --out-dir ./records.open \
  --aad tenant:county-a

Each relative path is bound into pqforge/folder-entry/v1 AAD, so a folder entry cannot be moved to another path and still authenticate.

Folder, pack, unpack, encrypt, decrypt, text, media, sign, verify, hybrid-sign, hybrid-verify, ecdsa-sign, and ecdsa-verify commands print a live, throttled progress line. Folder and pack/unpack jobs add a per-file SUCCESS or FAILED summary with throughput, including byte progress inside a large entry — folder jobs forward those bytes from background isolates so concurrent files cannot overwrite each other's totals. --digest hybrid/ECDSA signing reports hashing progress. keygen reports per-key wrapping progress when a passphrase is used. --quiet / -q mutes those per-file lines and skip warnings; the completion summary still prints. A folder job that fails any file exits non-zero. decrypt-text without --out writes plaintext to stdout and does not attach a progress line.

dart run pqforge encrypt-folder --quiet \
  --recipient-public keys/vault.kem.public.json \
  --in-dir ./records --out-dir ./records.pqf

Listing skips sockets, FIFOs, broken symlinks, and unreadable files instead of failing the whole tree (a warning is printed unless --quiet).

Text Encryption

Use text commands for short UTF-8 strings, prompts, notes, and secrets.

dart run pqforge encrypt-text \
  --recipient-public keys/vault.kem.public.json \
  --text 'private memo' \
  --text-id memo-2026-001 \
  --out memo.pqf

dart run pqforge decrypt-text \
  --recipient-secret keys/vault.kem.secret.wrapped.json \
  --passphrase-env PQFORGE_PASSPHRASE \
  --in memo.pqf

For larger text files:

dart run pqforge encrypt-text \
  --recipient-public keys/vault.kem.public.json \
  --in memo.txt \
  --text-id memo-2026-001 \
  --out memo.txt.pqf

Media Encryption

Use media commands for images, audio, video, PDFs, and other content where MIME type matters.

dart run pqforge encrypt-media \
  --recipient-public keys/vault.kem.public.json \
  --in cover.png \
  --media-id cover-2026-001 \
  --mime-type image/png \
  --out cover.png.pqf

dart run pqforge decrypt-media \
  --recipient-secret keys/vault.kem.secret.wrapped.json \
  --passphrase-env PQFORGE_PASSPHRASE \
  --in cover.png.pqf \
  --out cover.open.png

If --mime-type is omitted, the CLI infers common extensions and otherwise uses application/octet-stream.

Encryption Options

The bulk encrypt commands (encrypt, encrypt-folder, encrypt-text, encrypt-media, and pack) share a small set of flags. The matching decrypt commands need none of them — every choice is recorded in the self-describing container and auto-detected on read.

Flag Effect
--hybrid Add an X25519 leg (finds <key-id>.x25519.public.json next to --recipient-public); confidentiality holds while ML-KEM or X25519 stands. --recipient-x25519-public overrides the lookup.
--recipient-public (repeatable) Encrypt once, key-wrap the payload key to several recipients (first = primary).
--cipher chacha20-poly1305 Use ChaCha20-Poly1305 instead of AES-256-GCM (~2.6× faster in pure Dart, ideal where hardware AES is not dispatched). Recorded as a tamper-evident aeadSuite marker.
--engine cryptography|pure-dart Pick the AEAD backend. cryptography (default) is ~10× the PointyCastle throughput even in pure Dart and hardware-backed on Flutter; pure-dart is the PointyCastle reference. Wire formats are engine-independent.
--fips Global. Refuse ChaCha20-Poly1305, Argon2id, X-Wing, and an HPKE AEAD other than AES-256-GCM. keygen then wraps with PBKDF2-HMAC-SHA256 (--pbkdf2-iterations, default 600000). Not a validated module.
--profile / --kem / --sig Composition strength. --kem/--sig decouple the KEM and signature levels (e.g. a strong KEM with a lighter signature).
--signer-secret Sign the envelope/header with an ML-DSA key (cost is O(1) in file size).
# Hybrid + ChaCha20-Poly1305 + two recipients, in ONE ciphertext:
dart run pqforge encrypt --hybrid --cipher chacha20-poly1305 \
  --recipient-public keys/alice.kem.public.json \
  --recipient-public keys/bob.kem.public.json \
  --in report.pdf --out report.pqf

The primary recipient decrypts with their --recipient-secret; each additional recipient opens the same file with their own secret key and no extra flags.

Large Files And Streaming

Inputs at or above 8 MiB automatically switch to the .pqfs streaming container: a signed master header followed by independently authenticated frames, with a working set of roughly two frames regardless of total size. Per-frame sequence and final-flag binding prevent truncation, reordering, duplication, and splicing. No flag is needed — encrypt and encrypt-media detect the size and the decrypt side detects the format.

dart run pqforge encrypt \
  --recipient-public keys/vault.kem.public.json \
  --in movie.mp4 --out movie.mp4.pqf   # auto-streams; bounded memory

dart run pqforge decrypt \
  --recipient-secret keys/vault.kem.secret.wrapped.json \
  --passphrase-env PQFORGE_PASSPHRASE \
  --in movie.mp4.pqf --out movie.open.mp4

For the library streaming API (PqForgeStreamCipher), import package:pqforge/pqforge_io.dart — see API.md.

Pack Archives

pack collapses a whole folder into one encrypted streaming archive — a single KEM encapsulation and signature for the entire tree — and unpack restores it path-traversal-safe. Both stream end to end (no plaintext temp spool), and a failed unpack removes everything it created. For many small files this is far less overhead than one envelope per file.

dart run pqforge pack \
  --recipient-public keys/vault.kem.public.json \
  --in-dir ./site --out ./site.pqfs

dart run pqforge unpack \
  --recipient-secret keys/vault.kem.secret.wrapped.json \
  --passphrase-env PQFORGE_PASSPHRASE \
  --in ./site.pqfs --out-dir ./site.open

Use encrypt-folder (one .pqf per file) when recipients fetch individual files; use pack when the whole tree moves together.

Inspecting Artifacts

inspect describes any .pqf, .pqfs, key, or signature file without decrypting it — format, profile, suite, engine, signature, recipients, and metadata:

dart run pqforge inspect --in report.pqf
# → format, profile, suite (e.g. ML-KEM-1024 + X25519 → HKDF-SHA-512 →
#   AES-256-GCM), engine, signature, recipients, and metadata

Signatures

The sign command supports recipe-specific signature containers. The signer key may be ML-DSA (<key-id>.sign.secret.wrapped.json) or SLH-DSA (<key-id>.slh-dsa-….secret.wrapped.json).

dart run pqforge sign \
  --signer-secret keys/vault.sign.secret.wrapped.json \
  --passphrase-env PQFORGE_PASSPHRASE \
  --kind document \
  --in contract.pdf \
  --document-id contract-2026-001 \
  --out contract.sig.json

dart run pqforge verify \
  --signer-public keys/vault.sign.public.json \
  --in contract.pdf \
  --signature contract.sig.json

Supported --kind values:

Kind Bound fields
document document id, payload hash, payload length
text text id, UTF-8 encoding, payload hash, payload length
media media id, MIME type, payload hash, payload length
artifact artifact id, version, artifact hash
webhook event type, timestamp, payload hash

Media signing example:

dart run pqforge sign \
  --signer-secret keys/vault.sign.secret.wrapped.json \
  --passphrase-env PQFORGE_PASSPHRASE \
  --kind media \
  --in cover.png \
  --media-id cover-2026-001 \
  --mime-type image/png \
  --out cover.sig.json

dart run pqforge verify \
  --signer-public keys/vault.sign.public.json \
  --in cover.png \
  --signature cover.sig.json

Artifact signing example:

dart run pqforge sign \
  --signer-secret keys/vault.sign.secret.wrapped.json \
  --passphrase-env PQFORGE_PASSPHRASE \
  --kind artifact \
  --in release.tar.gz \
  --artifact-id pqforge-release \
  --version 7 \
  --out release.sig.json

Signed Envelopes

Encryption commands accept --signer-secret to sign the encrypted envelope:

dart run pqforge encrypt \
  --recipient-public keys/vault.kem.public.json \
  --signer-secret keys/vault.sign.secret.wrapped.json \
  --passphrase-env PQFORGE_PASSPHRASE \
  --signer-key-id vault-signer \
  --in report.pdf \
  --out report.signed.pqf

Decrypt signed envelopes with the signer public key:

dart run pqforge decrypt \
  --recipient-secret keys/vault.kem.secret.wrapped.json \
  --passphrase-env PQFORGE_PASSPHRASE \
  --signer-public keys/vault.sign.public.json \
  --in report.signed.pqf \
  --out report.open.pdf

Classical Keys

keygen emits all classical keypairs by default — x25519 (hybrid key agreement), ed25519, and ecdsa-p256 (hybrid/standalone signers) — next to the ML-KEM/ML-DSA bundle, so hybrid workflows need no extra step. Narrow or opt out:

Flag Result
(none) ML-KEM + ML-DSA + profile SLH-DSA and X25519 + Ed25519 + ECDSA-P256
--classical ed25519 --classical ecdsa-p256 ML-KEM + ML-DSA + profile SLH-DSA plus only the listed classical keys (repeatable)
--no-classical Post-quantum bundle only (ML-KEM + ML-DSA + profile SLH-DSA)
--classical-only Classical keys only, no post-quantum bundle
# Post-quantum bundle plus only the two signing keys
dart run pqforge keygen \
  --key-id vault \
  --out-dir keys \
  --classical ed25519 \
  --classical ecdsa-p256 \
  --passphrase-env PQFORGE_PASSPHRASE

Classical keys follow the <key-id>.<algo>.public.json / <key-id>.<algo>.secret[.wrapped].json naming, and secret keys are wrapped with Argon2id + AES-256-GCM when a passphrase source is supplied — the same custody path as ML-KEM/ML-DSA secrets. Only the secret key is stored; the public key is recomputed from it when signing.

SLH-DSA Keys

keygen emits one profile-matched SHAKE-f SLH-DSA keypair by default, using the same signature-public / signature-secret kinds as ML-DSA and an algorithmId such as slh-dsa-shake-128f. Files are named <key-id>.slh-dsa-<hash>-<size><s|f>.{public,secret}.json.

Flag Result
(none) Profile default: compact slh-dsa-shake-128f, balanced 192f, maximum 256f
--slh-dsa slh-dsa-sha2-128s --slh-dsa slh-dsa-shake-128f Exactly the listed FIPS 205 sets (repeatable; all 12 ids are allowed)
--no-slh-dsa Skip hash-based keys
--slh-dsa-only SLH-DSA keys only (no ML-KEM/ML-DSA, no classical)
# Hash-based archival key (SHAKE-128f) next to the compact ML-DSA bundle
dart run pqforge keygen \
  --profile compact \
  --key-id archive \
  --out-dir keys \
  --no-classical \
  --passphrase-env PQFORGE_PASSPHRASE

dart run pqforge sign \
  --signer-secret keys/archive.slh-dsa-shake-128f.secret.wrapped.json \
  --passphrase-env PQFORGE_PASSPHRASE \
  --kind document \
  --in firmware.bin \
  --out firmware.slh.sig.json

dart run pqforge sign \
  --signer-secret keys/archive.slh-dsa-shake-128f.secret.wrapped.json \
  --passphrase-env PQFORGE_PASSPHRASE \
  --kind webhook \
  --event-type invoice.paid \
  --timestamp-ms 1700000000000 \
  --in payload.json \
  --out payload.slh.sig.json

s (small signature) sets are slow by design; pqcrypto requires an explicit opt-in to sign with them. The CLI passes that opt-in when you hand it an s-set secret. Envelope --signer-secret and hybrid-sign still reject SLH-DSA keys. compose-sign accepts an SLH-DSA leg because you passed --slh-secret.

Composed signatures

compose-sign is 2 legs (dual) or 3 legs (triple). Each flag is one algorithm. Omit a flag and that algorithm is not in the signature.

Flag Leg
--ml-dsa-secret the ML-DSA set stored in that key
--slh-secret the SLH-DSA set stored in that key
--classical-secret Ed25519, ECDSA-P256, ECDSA-P384, or ECDSA-P521. Repeatable

ECDSA-P384 and ECDSA-P521 are not in the default keygen set:

dart run pqforge keygen \
  --key-id vault \
  --out-dir keys \
  --classical ecdsa-p384 \
  --classical ecdsa-p521 \
  --passphrase-env PQFORGE_PASSPHRASE

dart run pqforge compose-sign \
  --ml-dsa-secret keys/vault.sign.secret.wrapped.json \
  --slh-secret keys/vault.slh-dsa-shake-128f.secret.wrapped.json \
  --classical-secret keys/vault.ecdsa-p384.secret.wrapped.json \
  --passphrase-env PQFORGE_PASSPHRASE \
  --policy require-all \
  --in firmware.bin \
  --out firmware.triple.json

dart run pqforge compose-verify \
  --ml-dsa-public keys/vault.sign.public.json \
  --slh-public keys/vault.slh-dsa-shake-128f.public.json \
  --classical-public keys/vault.ecdsa-p384.public.json \
  --in firmware.bin \
  --signature firmware.triple.json

--policy on compose-verify is the caller's policy and defaults to require-all. It must equal the policy stored in the signature. The file cannot widen require-all into accept-any. accept-any succeeds when one leg verifies, but only when both the signer and the verifier chose it. hybrid-sign is still exactly one ML-DSA leg plus one classical leg, and that classical leg may now be P-384 or P-521. ecdsa-sign follows the key's algorithm id.

Hybrid Signatures

hybrid-sign produces one ML-DSA signature and one classical signature (Ed25519 or ECDSA-P256, chosen by the classical key) bound over the same message. The post-quantum profile is inferred from the ML-DSA key.

dart run pqforge hybrid-sign \
  --signer-secret keys/vault.sign.secret.wrapped.json \
  --classical-secret keys/vault.ecdsa-p256.secret.wrapped.json \
  --passphrase-env PQFORGE_PASSPHRASE \
  --in release.tar.gz \
  --out release.hybrid.json \
  --context release:v7

dart run pqforge hybrid-verify \
  --signer-public keys/vault.sign.public.json \
  --classical-public keys/vault.ecdsa-p256.public.json \
  --in release.tar.gz \
  --signature release.hybrid.json

--context is an optional domain-separation string; when supplied to hybrid-sign it is stored in the signature JSON and reused automatically by hybrid-verify (override it with --context if needed). --policy is recorded by hybrid-sign and must be passed again to hybrid-verify. The default is require-both, which fails unless both signatures verify. accept-either succeeds when one signature verifies, but only when the verifier passes the same policy. The signature file cannot widen the check.

For gigabyte inputs, add --digest: hybrid-sign --digest signs the streamed SHA-256 of the input (O(1) memory) under a domain-separation label, recorded in the signature JSON so hybrid-verify re-hashes automatically — no --digest flag needed on verify.

Standalone ECDSA

ecdsa-sign / ecdsa-verify follow the key: P-256, P-384, or P-521 (RFC 6979 deterministic nonces, canonical low-S) over the raw file bytes. No post-quantum key is involved. P-384 and P-521 are keygen --classical opt-ins. They also accept --digest for the same streamed SHA-256 pre-hash described above. P-521 here is a signature, not an HPKE share and not a TLS group.

dart run pqforge ecdsa-sign \
  --secret keys/vault.ecdsa-p256.secret.wrapped.json \
  --passphrase-env PQFORGE_PASSPHRASE \
  --in firmware.bin \
  --out firmware.ecdsa.json

dart run pqforge ecdsa-verify \
  --public keys/vault.ecdsa-p256.public.json \
  --in firmware.bin \
  --signature firmware.ecdsa.json

verify, hybrid-verify, and ecdsa-verify exit 0 on a valid signature and 1 on a failed one, so they slot directly into shell && chains and CI gates.

HPKE (X-Wing)

hpke is not encrypt and not keygen. It does not read or write .pqf or .pqfs. The output magic is XW01. --kem accepts only xwing. PQXDH and the Sparse Post-Quantum Ratchet are not flags here. The Double Ratchet is a library session, not a CLI command.

dart run pqforge hpke keygen --key-id demo --out-dir keys
dart run pqforge hpke seal \
  --recipient-public keys/demo.xwing.public.json \
  --in note.txt \
  --out note.xwing
dart run pqforge hpke open \
  --recipient-secret keys/demo.xwing.secret.json \
  --in note.xwing \
  --out note.opened.txt

keygen writes demo.xwing.public.json (kind xwing-public) and demo.xwing.secret.json (kind xwing-secret). algorithmId is xwing. seal refuses a different kind. --cipher is aes-256-gcm (the default), aes-128-gcm, or chacha20-poly1305. --fips refuses this command, because the KEM is X-Wing, and refuses an AEAD other than AES-256-GCM on the DHKEMs. The default keygen and encrypt commands are unchanged.

Certificates

cert speaks the same objects as openssl req and openssl x509 -req. PEM is the default. --der writes the raw encoding. --key reads the PEM private key openssl req -keyout writes (PRIVATE KEY, EC PRIVATE KEY, or RSA PRIVATE KEY). --secret reads a keygen JSON file instead.

OpenSSL pqforge
req -new -key key.pem -subj ... -addext ... -out req.pem cert req --key key.pem --subj ... --addext ... --out req.pem
req -x509 -key key.pem -days 365 -subj ... -out cert.pem cert issue --key key.pem --days 365 --subj ... --out cert.pem
x509 -req -in req.pem -CA ca.pem -CAkey ca.key -copy_extensions copy cert sign --in req.pem --ca ca.pem --ca-key ca.key --out cert.pem
req -in req.pem -noout -verify -text cert inspect --in req.pem
x509 -in cert.pem -noout -text cert inspect --in cert.pem
verify -CAfile ca.pem cert.pem cert verify --in cert.pem --anchor ca.pem

--subj is the OpenSSL subject string. It starts with / and uses C, ST, L, O, OU, CN, and emailAddress. + joins one RDN. --cn is shorthand for /CN=. --addext is repeatable and accepts subjectAltName (DNS, IP, email, URI), keyUsage, extendedKeyUsage (serverAuth, clientAuth), and basicConstraints. A request's extensions are copied when cert sign issues the certificate.

openssl ecparam -name prime256v1 -genkey -noout -out leaf.key
dart run pqforge cert req \
  --key leaf.key \
  --subj /C=KE/ST=Nairobi/O=pqforge/CN=localhost \
  --addext subjectAltName=DNS:localhost \
  --out localhost.csr
openssl req -in localhost.csr -noout -verify

dart run pqforge cert issue --key ca.key --subj /CN=pqforge-ca --ca --out ca.pem
dart run pqforge cert sign --in localhost.csr --ca ca.pem --ca-key ca.key --out localhost.pem
openssl verify -CAfile ca.pem localhost.pem

This is not openssl req -config, not an interactive prompt, and not -newkey. Generate the key with keygen or with OpenSSL, then pass it in. It is not a WebPKI CA and not a trust store.

cert inspect --in file.pem prints each PEM block: version, serial, algorithm, issuer, subject, validity, public key, basic constraints, key usage, extended key usage, subject alternative names, and whether the signature matches the key in that file. A private-key block prints the algorithm and the public key only. The secret is not printed.

cert verify exits 0 when the chain is trusted and 1 when it is not.

Threshold roots (pqthreshold companion)

pqforge covers single-party hybrid keys on each device (ML-KEM, ML-DSA, X25519, Ed25519, ECDSA-P256). Organizational / enclave roots that no single officer holds use the sibling package pqthreshold — FROST Ed25519 threshold signing, Feldman VSS, and Gennaro DKG.

Use both tools with the same custody model: public material as JSON or .pqth files; secrets wrapped with PqWrappedKey (Argon2id + AES-256-GCM) and --passphrase-env PQFORGE_PASSPHRASE (or --passphrase-file).

Typical stack workflow

# 1) Device identity / sealing keys (each member) — pqforge
export PQFORGE_PASSPHRASE='load-from-secret-manager'
dart run pqforge keygen --key-id officer-alice --out-dir ~/.pq/keys/alice \
  --passphrase-env PQFORGE_PASSPHRASE

# 2) Threshold root parameters (officers) — pqthreshold CLI
dart pub global activate pqthreshold   # or: dart run pqthreshold from a clone
pqthreshold params export --t 3 --n 5 --out root-ceremony/params.pqth
pqthreshold inspect --in root-ceremony/params.pqth

# 3) DKG + threshold signing (Phase 3+) — pqthreshold ceremony commands
#    Combined signatures verify as ordinary Ed25519 (hybrid-verify / PqClassical)
Concern Tool
Day-to-day encrypt / sign / hybrid workflows pqforge (this CLI)
Root DKG, shares, quorum signing pqthreshold
Wrapped secret storage Same PqWrappedKey envelope for both
Combined root signature verify pqforge verify / Ed25519 path on joint public key

Full cross-package terminal runbook: pqthreshold doc/TERMINAL.md. Ceremony logic: pqthreshold doc/CEREMONIES.md.

Color, Quiet, And Help

Run pqforge with no arguments (or pqforge --help) for a grouped command overview, and pqforge <command> --help for per-command options and examples. Colors auto-disable when output is piped or NO_COLOR is set; force them off with --no-color. pqforge --version (or pqforge version) prints the version, which is single-sourced from pubspec.yaml.

--quiet / -q on encrypt/decrypt (file, text, media, folder), pack/unpack, sign, verify, hybrid-sign, hybrid-verify, ecdsa-sign, ecdsa-verify, and keygen mutes line-by-line file completion summaries and skip warnings. The final "complete: N file(s)" line still prints. keygen --quiet still warns if raw secret-key JSON was written. decrypt-text without --out never mixes a progress line into the plaintext.

Operational Notes

  • Keep wrapped secret-key JSON in a protected store.
  • Prefer --passphrase-env for automation.
  • Rotate keys according to the app's retention and risk policy.
  • Keep public-key trust explicit; a self-provided public key is not an identity.
  • Multi-GB files are handled automatically: inputs ≥ 8 MiB stream through the bounded-memory .pqfs container, and --digest signing avoids loading whole artifacts into memory. No application-level chunking is required.