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 removes the Unicode White_Space set pinned by the specification plus -, _, and ., and rejects empty or separator-only input. Validation returns False for invalid input, 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.

These values are possible payload strings, not safe random issuance counts. Random issuance must account for birthday collisions. An appended check digit is derived from the payload and does not add random 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