canonchain
v0.1.0
Published
Authentication identifier canonicalization security testing for Unicode identity pipelines
Maintainers
Readme
CanonChain
Authentication identifier canonicalization security testing for Unicode identity pipelines.
CanonChain finds security bugs created when validators, normalizers, databases, mailers, protocol encoders, and cryptographic code disagree about the same username, email address, or credential. It reports the smallest input and exact stage where semantic identity changes or distinct accepted identifiers collide.
Why this exists
Unicode standards and PRECIS provide essential single-stage rules. CanonChain does not replace them. It verifies the application's real ordering and composition: validate → normalize → store → parse → encode → use. That relational pipeline is where validate-before-canonicalize and lossy-encoding defects emerge.
Quick start
npm install -g https://github.com/virajsabhaya23/canonchain/releases/download/v0.1.0/canonchain-0.1.0.tgz
canonchain verify --contract examples/email-magic-link.json
canonchain verify --contract examples/legacy-credential-encoding.json --format sarif --out canonchain.sarifNo account, network call, credential, or paid service is required. CanonChain executes only built-in declarative stages; it does not evaluate JavaScript from contracts.
Built-in stages
- Unicode normalization: NFC, NFD, NFKC, NFKD
- locale-aware lowercase and trimming
- single-ASCII-
@validation and Unicode regular-expression validation - deterministic string replacement
- a legacy Latin-1 loss model for testing credential collisions
Extractors model email-recipient identity, username identity, or UTF-8 byte identity. Generators cover compatibility separators, whitespace, and case. Every trace records before/after strings, code points, acceptance, and semantic identity.
Security model
Version 1 is an offline verifier. It sends no mail, makes no network calls, attempts no login, and stores no credentials. Use synthetic identifiers only. Contracts can express preserveSemanticIdentity and noCollisions; output supports text, JSON, SARIF, CI exit codes, and SHA-256 evidence hashes.
Evidence and adoption path
Build a versioned corpus containing confirmed advisories, seeded composed-stage failures, and safe controls. Submit minimized fixtures upstream to authentication and identity libraries. Preserve exact Unicode/runtime versions, stage traces, issue/PR/advisory links, independent integrations, external contributors, and confirmed before/after fixes.
Research basis
- Auth.js GHSA-7rqj-j65f-68wh
- Jetty GHSA-2fvj-hgj9-j2gr
- Unicode UTS #39
- RFC 8265: PRECIS usernames and passwords
Apache-2.0 licensed. Contributions are welcome.
