# quantum-sign — CLI Reference

## NAME

quantum-sign — post‑quantum code‑signing CLI (ML‑DSA‑87, Level‑5)

## SYNOPSIS

`quantum-sign <SUBCOMMAND> [OPTIONS]`

## DESCRIPTION

Quantum‑Sign signs and verifies artifacts using ML‑DSA‑87 (FIPS 204) with strict, policy‑driven controls. All operations are pure Rust and offline‑verifiable.

## GLOBALS

- `--help` Show help for any command or subcommand
- `--version` Show version

## SUBCOMMANDS

### keygen

Generate a signing key pair.

```
quantum-sign keygen \
  --profile mldsa-87 \
  --secret <PATH> \
  --public <PATH>
```

Outputs raw secret/public key bytes. The KID (first 16 hex of SHA‑256(SPKI)) identifies the signer.

### sign

Prepare an intent for signing a file with a policy (computes digest and writes `<sig>.qsi`).

```
quantum-sign sign \
  --inp <FILE> \
  --sig <OUTPUT.qsig> \
  --policy <policy.json> \
  [--digest sha512|sha256|shake256-64]
```

### verify

Offline verification against a trust database.

```
quantum-sign verify \
  --inp <FILE> \
  --sig <FILE.qsig> \
  --trustdb <DIR> \
  [--json]
```

### trust

Manage trusted verifying keys (SPKI DER, stored as `trust/<KID>.spki`).

```
quantum-sign trust import --public <PUBLIC> --trustdb <DIR>
quantum-sign trust list   --trustdb <DIR>
```

### quorum

Multi‑party workflows (also used for single‑signer flows).

```
# Initialize intent + journal (.qsi + .qsig.part)
quantum-sign quorum init \
  --artifact <FILE> \
  --policy <policy.json> \
  --digest sha512 \
  [--allowed-kid <KID> ...]

# Create a fragment from a secret key and append into journal
quantum-sign quorum cosign \
  --intent <FILE.qsi> \
  --secret <secret.sk> \
  --public <public.vk> \
  --fragment <out.csf> \
  --append <FILE.qsig.part>

# Seal journal into final .qsig (verifies all fragments against trust)
quantum-sign quorum seal \
  --part <FILE.qsig.part> \
  --out <FILE.qsig> \
  --trust-dir <DIR>

# One‑shot: produce minimal, production‑ready release
quantum-sign quorum package \
  --artifact <FILE> \
  --policy <policy.json> \
  --digest sha512 \
  [--secret <secret.sk> --public <public.vk>] \
  [--out-dir ./release] [--zip true]
```

#### package output (exactly 4 files)

- `<artifact>`
- `<artifact>.qsig`
- `policy.json` (canonical JSON serialization)
- `trust/<KID>.spki`

No `.qsi`, `.qsig.part`, `.csf`, secret keys, or platform metadata are emitted in the release.

## EXAMPLES

### One‑shot packaging and verify

```
quantum-sign quorum package \
  --artifact ./AnubisQuantumCipher.png \
  --policy ./policy.json \
  --digest sha512 \
  --secret ./keys/sicarii.sk \
  --public ./keys/sicarii.vk \
  --out-dir ./release \
  --zip true

quantum-sign verify --json \
  --inp ./release/AnubisQuantumCipher.png \
  --sig ./release/AnubisQuantumCipher.qsig \
  --trustdb ./release/trust
```

Expected JSON fields include: `status: ok`, `alg: mldsa-87`, `digest_alg: sha512`, `kids_verified`, `m`, `n`, `canonical`, `policy_hash_hex`, `file_digest_hex`.

### Add a key to trust

```
quantum-sign trust import --public alice.pub --trustdb ./trust
quantum-sign trust list   --trustdb ./trust
```

## EXIT CODES

- `0` success
- `2` crypto error
- `3` policy error
- `4` I/O error
- `1` other errors

## NOTES

- Policies can include human‐readable `comments` (e.g., owner info). The policy’s canonical hash is bound into signature claims.
- Keys are never placed into the packaged release; only the SPKI (verifying key) is included under `trust/<KID>.spki`.

