hardguard25

Python reference implementation of HardGuard25 — an open standard for human-safe identifiers.

0 1 2 3 4 5 6 7 8 9 A C D F G H J K M N P R U W Y

HardGuard25 is a 25-character alphabet designed to exclude common visual confusables, including patterns relevant to dyslexia-sensitive workflows. It removes 11 letters associated with predictable confusion (I L O B S Z E T V X Q). When a letter and a digit compete for the same visual slot, the digit always wins. Comparative OCR and transcription error rates have not yet been established empirically.

Install

pip install hardguard25

Requires Python 3.9+.

Quickstart

from hardguard25 import generate, validate, normalize, check_digit, verify_check_digit

generate(8)                       # e.g. "AC3H7PUW"
generate(8, check_digit=True)     # e.g. "AC3H7PUWN"  (length+1)

validate("ac3h-7puw")             # True  (case and separators tolerated)
normalize("ac3h-7puw")            # "AC3H7PUW"

check_digit("AC3H7PUW")           # "N"
verify_check_digit("AC3H7PUWN")   # True

Normalization rejects empty and separator-only input. Validation returns False for it, and check-digit calculation rejects an empty payload.

API

Type hints and py.typed marker included.

Sizing

Each character carries log2(25) = 4.64 bits of entropy.

Recommended defaults:

• 16 for internal systems up to millions of IDs
• 20 for public tokens or cross-org use
• 22 for long-lived, internet-scale identifiers

See the spec for collision-bound tables.

Implementation guidance

For project integration guidance, see:

• Human implementation guide: https://github.com/snapsynapse/hardguard25/blob/main/docs/IMPLEMENTATION.md
• Assistant guide: https://hardguard25.com/.well-known/assistant-guide.txt
• Assistant guide SHA-256: https://hardguard25.com/.well-known/assistant-guide.txt.sha256

When NOT to Use HardGuard25

• Cryptographic keys (use proper key derivation)
• Blockchain consensus (use domain-specific formats)
• Systems requiring global UUID guarantees (use UUIDv7 or ULID)
• Machine-only contexts where no human ever sees the ID

Reference

• Spec: https://github.com/snapsynapse/hardguard25/blob/main/SPEC.md
• Homepage: https://hardguard25.com/
• Source: https://github.com/snapsynapse/hardguard25
• Other languages: JavaScript, Go (same repo)

License

MIT