# qpass

`qpass` is a small Go password generator with a conservative cryptographic
randomness model.

By default it uses Go's `crypto/rand` OS CSPRNG. It can also run in hybrid mode,
where local OS randomness is mixed with bytes from an external quantum,
hardware, or certified randomness source. The external source is additive: it
never replaces the OS CSPRNG as the safety baseline.

## Usage

```bash
go run ./cmd/qpass
go run ./cmd/qpass -stats
go run ./cmd/qpass -length 32 -count 5
go run ./cmd/qpass -length 32 -symbols=false
```

Hybrid entropy mode:

```bash
go run ./cmd/qpass -rng hybrid -entropy-file random-bytes.bin
go run ./cmd/qpass -rng hybrid -entropy-device /dev/qrandom
qrng-tool --raw | go run ./cmd/qpass -rng hybrid -entropy-stdin
```

Legacy compatibility:

```bash
go run ./cmd/qpass -length 32 -quantum-file random-bytes.bin
qrng-tool --raw | go run ./cmd/qpass -length 32 -quantum-file -
```

`-quantum-file` is kept as an alias for older usage. New scripts should prefer
`-rng hybrid` with `-entropy-file`, `-entropy-device`, or `-entropy-stdin`.

Entropy checks:

```bash
go run ./cmd/qpass entropy status
go run ./cmd/qpass entropy test -entropy-file random-bytes.bin
go run ./cmd/qpass entropy test -entropy-device /dev/qrandom -require-external
```

## Notes

- `-rng os` uses only Go's `crypto/rand.Reader`.
- `-rng hybrid` mixes `crypto/rand.Reader` with the configured external source
  using SHA-512 domain-separated blocks.
- Without `-require-external`, hybrid mode degrades to OS CSPRNG if the external
  source runs out or fails, and prints a warning on stderr.
- With `-require-external`, generation fails when the external source cannot
  provide enough bytes.
- `-replace-global-rand` installs the selected engine as `crypto/rand.Reader`
  for this process. It is an advanced integration option; normal password
  generation passes the reader explicitly.
- Entanglement-based randomness certification needs physical hardware and a
  Bell-test/randomness-amplification protocol.
- A normal laptop cannot reproduce that guarantee in software.
- For everyday password generation, OS CSPRNG via `crypto/rand` is the
  practical baseline.
- `qpass` prints only passwords by default. Use `-stats` when you want the
  alphabet size and estimated entropy on stderr.

## Development

```bash
make fmt
make test
make build
```