Documentation Index
Fetch the complete documentation index at: https://docs.algovoi.co.uk/llms.txt
Use this file to discover all available pages before exploring further.
The PQC substrate layer is the AlgoVoi-authored binding between
the canonicalisation discipline and
post-quantum signature primitives. It binds RFC 8785 JCS canonical bytes
to FIPS 204 (ML-DSA-65) and FIPS 206 (Falcon-1024) signature schemes
under a single signature_algorithm open-enum convention with a
fail-closed verifier rule.
It is published as standalone reference implementations:
Both are Apache-2.0 licensed, browser + Node + Bun + Deno + CPython 3.10+
compatible, and depend on audited upstream PQC libraries (PQClean via
pqcrypto on Python, @noble/post-quantum by Paul Miller on TypeScript).
Honest layer-split
The PQC primitives themselves are not AlgoVoi-authored. The substrate
convention sits above audited upstream PQC implementations:
| Layer | Owner |
|---|
| Falcon-1024 algorithm (FIPS 206 / FN-DSA) | Academic cryptographers + NIST |
| Falcon-1024 reference C implementation | PQClean (open-source community) |
| Python wrapper around PQClean | pqcrypto package (Backbone Authors, Apache-2.0) |
| Pure-JS PQC implementation | @noble/post-quantum (Paul Miller, MIT) |
| Java audit-grade PQC implementation | Bouncy Castle 1.84 (MLDSASigner + FalconSigner) |
| ML-DSA-65 algorithm (FIPS 204) | NIST + academic cryptographers |
| JCS canonicalisation rule (RFC 8785) | Anders Rundgren et al. |
| AP2 PaymentMandate schema v0.1 | Google agentic-commerce |
| JCS+PQC integration pattern | AlgoVoi |
signature_algorithm open-enum + fail-closed verifier discipline | AlgoVoi |
| Cross-implementor byte-anchor convergence proof methodology | AlgoVoi |
| Multi-language verifier suite (Python + TS + Ruby + PHP + Perl + Java) | AlgoVoi |
signature_algorithm open-enum (12 rows)
The 12-row recommended-values registry covers classical, post-quantum,
and HMAC families. Case-sensitive lookup per RFC 7517 §4.1. Verifiers
MUST treat unknown identifiers as opaque and refuse to verify
(fail-closed).
| Identifier | Family | Source | Notes |
|---|
ECDSA | Classical | Generic ECDSA | Backward-compat alias; new deployments SHOULD use the specific JOSE identifier. |
ES256 | Classical | RFC 7518 §3.4 | ECDSA P-256 SHA-256. |
ES256K | Classical | RFC 8812 | ECDSA secp256k1 SHA-256. |
Ed25519 | Classical | RFC 8032 / RFC 8037 | EdDSA Ed25519. |
ML-DSA-44 | PQC | FIPS 204 / draft-ietf-cose-dilithium | NIST Level 2. |
ML-DSA-65 | PQC | FIPS 204 / draft-ietf-cose-dilithium | NIST Level 3. |
ML-DSA-87 | PQC | FIPS 204 / draft-ietf-cose-dilithium | NIST Level 5. |
Falcon-512 | PQC | FIPS 206 (FN-DSA) | NIST Level 1. |
Falcon-1024 | PQC | FIPS 206 (FN-DSA) | NIST Level 5. |
SLH-DSA-SHA2-128s | PQC stateless-hash | FIPS 205 | SPHINCS+ small. |
HMAC-SHA-256 | HMAC | RFC 2104 | Internal-channel only. |
HMAC-SHA-384 | HMAC | RFC 2104 / FIPS 198-1 | PQC-conservative HMAC. |
Cross-product matrix attestation
The substrate-author convention is producer-verifier symmetric —
signatures emitted in any language verify in any other language for the
schemes available in each environment. Demonstrated by a 4-producer ×
6-verifier matrix that runs every producer artefact against every
available verifier.
Matrix attestation document
| Producer ↓ \ Verifier → | python | ts | ruby | php | java | perl |
|---|
| python (4 schemes) | 5/5 ✅ | 5/5 ✅ | 4/4 ✅ | 4/4 ✅ | 6/6 ✅ | JCS 2/2 ✅ |
| ts (4 schemes) | 5/5 ✅ | 5/5 ✅ | 4/4 ✅ | 4/4 ✅ | 6/6 ✅ | JCS 2/2 ✅ |
| ruby (2 schemes) | 3/3 ✅ | 3/3 ✅ | 4/4 ✅ | 4/4 ✅ | 4/4 ✅ | JCS 2/2 ✅ |
| php (2 schemes) | 3/3 ✅ | 3/3 ✅ | 4/4 ✅ | 4/4 ✅ | 4/4 ✅ | JCS 2/2 ✅ |
sha256:cc8315f7696c65b2a07eb278de0e45c3149319526c8d443c7e38a17de04c28e0
— four independent JCS canonicalisation implementations producing
byte-identical canonical bytes from the same payload.
Reproduce locally:
git clone https://github.com/chopmob-cloud/algovoi-substrate-pqc
cd algovoi-substrate-pqc
python scripts/cross_product_matrix.py
Three audit-grade PQC implementations cross-validated
The strongest substrate-author signal: three independent audit-grade
PQC implementations agree byte-for-byte on Falcon-1024 and ML-DSA-65
signatures over identical canonical bytes.
PQClean (Python pqcrypto)
|
| byte-for-byte
v
@noble/post-quantum (TS) <----> Bouncy Castle (Java)
byte-for-byte
| Implementation | Falcon-1024 | ML-DSA-65 | Notes |
|---|
PQClean (Python via pqcrypto v0.4.0) | ✓ | ✓ | Reference C implementation |
@noble/post-quantum (TypeScript, Paul Miller, MIT) | ✓ | ✓ | Pure JS, audit-grade |
Bouncy Castle 1.84 (Java, MLDSASigner + FalconSigner) | ✓ (experimental) | ✓ (production) | Established crypto library |
verifiers/java/.
PQC cross-implementor contribution
The ML-DSA-65 cross-implementor fixture this substrate verifies against
was contributed by PQSafe (@rayc0) per
the AP2 #250 joint conformance fixture.
PQSafe is named co-maintainer of the joint conformance repo per the
published policy.
Credit is scoped to that ML-DSA-65 contribution only.
Substrate-author work for this layer (the signature_algorithm open-enum
convention, the JCS+PQC binding pattern, the fail-closed verifier
discipline, the byte-anchor convergence proof methodology, the
multi-language verifier suite) is AlgoVoi’s.
Multi-language verifier suite
In addition to the Python + TypeScript reference impls, the substrate
ships verifier scripts in additional scripting languages — all
demonstrating that the JCS canonicalisation + classical-signature
discipline reproduces in any environment with standard primitives:
| Language | Coverage | Source |
|---|
| Ruby 3.4+ | JCS + ES256 + Ed25519 (OpenSSL stdlib) | verifiers/ruby/verify.rb |
| PHP 8.4+ | JCS + ES256 + Ed25519 (openssl + sodium) | verifiers/php/verify.php |
| Perl 5.38+ | JCS canonical-bytes proof (core modules); ES256 + Ed25519 with CryptX | verifiers/perl/verify.pl |
| Lua 5.4+ | JCS + ES256 + Ed25519 (lua-openssl) | Pending — install path documented |
| Elixir 1.17+ | JCS + ES256 + Ed25519 (:public_key + :crypto Erlang stdlib) | Pending — install path documented |
docs/CROSS_RUNTIME.md
document.
Why no scripting-language PQC
PQC schemes (Falcon-1024, ML-DSA-65) are out of scope for the
scripting-language verifiers (Ruby, PHP, Perl, Lua, Elixir). No
audit-grade PQC libraries exist in those ecosystems at this time. The
alternative — vendoring PQClean’s reference C source ourselves and
binding via FFI per language — was explicitly considered and rejected
in the design phase because:
- Falcon-1024 patent encumbrance. Patent US7308097B2 covers parts
of Falcon; FRAND-style royalty-free pledge applies via FIPS 206
standardisation. Vendoring PQClean source makes the substrate
package a named redistributor of patent-encumbered code. The current
wrap-existing-audited-package design avoids this status.
- Per-language FFI maintenance burden. Each scripting-language
FFI binding would require per-language audit + maintenance + patent
disclosure surface. Not justified for the substrate-author claim
when the canonicalisation + classical-signature coverage already
demonstrates substrate is environment-independent.
PQC verification is established by the Python + TypeScript + Java
implementations, which span the JVM and non-JVM ecosystems with three
audit-grade PQC implementations.
Verifier discipline (fail-closed)
Verifiers MUST treat unknown signature_algorithm values as opaque
and refuse to verify.
This is the substrate-author fail-closed normative discipline that
allows the signature_algorithm registry to evolve without breaking
schema changes. Implementors MAY declare any value. Verifiers MUST
reject unknown values or escalate to a registered extension, rather
than guessing.
The Python implementation surfaces this rule as
UnknownSignatureAlgorithm raised from lookup_signature_algorithm().
The TypeScript implementation throws
UnknownSignatureAlgorithmError. Both consistent in semantics.
Install + quickstart
Python
pip install algovoi-substrate-pqc
from algovoi_substrate_pqc import (
build_convergence_artefact,
generate_falcon_1024_keypair,
generate_ml_dsa_65_keypair,
sign_ed25519, sign_es256, sign_falcon_1024, sign_ml_dsa_65,
verify_artefact,
)
# ...build artefact, sign with 4 schemes, verify cross-language
TypeScript
npm install @algovoi/substrate-pqc
import {
buildConvergenceArtefact,
generateFalcon1024Keypair, generateMLDSA65Keypair,
signEd25519, signES256, signFalcon1024, signMLDSA65,
verifyArtefact,
} from '@algovoi/substrate-pqc';
Java (Bouncy Castle)
cd verifiers/java
bash fetch-deps.sh
javac -cp "lib/*" -d out Verify.java
java -cp "out;lib/*" Verify path/to/artefact.json
See also
License
Apache 2.0. Same as the rest of the AlgoVoi substrate.
