vrk digest

vrk digest hashes stdin with SHA-256, MD5, or SHA-512, with HMAC support and cross-platform consistency.

The problem

sha256sum exists on Linux but not macOS. shasum -a 256 exists on macOS but the output format differs. A verification script that works locally breaks on the other OS. For HMAC, openssl dgst exists but the flag syntax is hostile and differs across versions.

The solution

vrk digest hashes with SHA-256 (default), MD5, or SHA-512. Works the same on macOS and Linux. Compare file hashes with --compare, compute HMACs with --hmac, and verify them with --verify. Uses constant-time comparison for verification to resist timing attacks.

Before and after

Before

# macOS: shasum -a 256 file.tar.gz
# Linux: sha256sum file.tar.gz
# Different output formats, different commands

After

vrk digest --file file.tar.gz

Example

vrk digest --file release.tar.gz --compare

Exit codes

Code	Meaning
0	Success, hash written, or –verify matched
1	File not found, read error, or –verify mismatch
2	Unknown algorithm, –hmac without –key, –verify without –hmac

Flags

Flag	Short	Type	Description
`--algo`	-a	string	Hash algorithm: sha256, md5, sha512
`--bare`	-b	bool	Output hex hash only, without algo: prefix
`--file`		[]string	Path to file to hash (repeatable)
`--compare`		bool	Compare hashes of all –file inputs
`--hmac`		bool	Compute HMAC instead of plain hash
`--key`	-k	string	HMAC secret key (required with –hmac)
`--verify`		string	Known HMAC hex to verify against
`--json`	-j	bool	Emit JSON object instead of algo:hash line
`--quiet`	-q	bool	Suppress stderr output

How it works

Hash from stdin

$ echo 'hello' | vrk digest
sha256:5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03

Default format is algo:hash. Use --bare for just the hash:

$ echo 'hello' | vrk digest --bare
5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03

Hash a file

$ vrk digest --file release.tar.gz
sha256:a1b2c3d4e5f6...

Streams the file, so it works on files larger than available memory.

Different algorithms

$ echo 'hello' | vrk digest --algo md5
md5:b1946ac92492d2347c6235b4d2611184

$ echo 'hello' | vrk digest --algo sha512
sha512:e7c22b994c59d...

JSON output

$ echo 'hello' | vrk digest --algo md5 --json
{"algo":"md5","hash":"b1946ac92492d2347c6235b4d2611184","input_bytes":6}

Compare file hashes

Check if multiple files have identical content:

vrk digest --file original.txt --file copy.txt --compare

HMAC computation and verification

# Compute HMAC
$ echo 'message' | vrk digest --hmac --key 'secret'
sha256:...

# Verify HMAC (constant-time comparison)
$ echo 'message' | vrk digest --hmac --key 'secret' --verify 'expected-hash'
$ echo $?
0

The --verify flag uses constant-time comparison to prevent timing attacks.

Pipeline integration

Cache-key generation for LLM responses

# Use content hash as a cache key
KEY=$(cat document.txt | vrk digest --bare)
CACHED=$(vrk kv get --ns llm-cache "$KEY" 2>/dev/null)
if [ -z "$CACHED" ]; then
  RESULT=$(cat document.txt | vrk prompt --system 'Summarize')
  vrk kv set --ns llm-cache "$KEY" "$RESULT" --ttl 24h
  echo "$RESULT"
else
  echo "$CACHED"
fi

Verify downloaded files

vrk digest --file download.tar.gz --bare | \
  vrk assert --contains "$EXPECTED_HASH" -m 'Checksum mismatch'

When it fails

Unknown algorithm:

$ echo 'hello' | vrk digest --algo sha384
usage error: digest: unsupported algorithm "sha384"
$ echo $?
2

HMAC without key:

$ echo 'hello' | vrk digest --hmac
usage error: digest: --key is required with --hmac
$ echo $?
2

Verify mismatch:

$ echo 'hello' | vrk digest --hmac --key 'secret' --verify 'wrong'
error: digest: HMAC mismatch
$ echo $?
1