crypto-agility.json: a proposal for publishing cryptographic posture at a well-known URL

The migration off quantum-vulnerable cryptography is a coordination problem across millions of independent parties, and the parties reading each other's posture are increasingly software: an AI coding agent proposing dependency updates, a build gate deciding whether to ship, an auditor or regulator or journalist wanting to know where a sector stands. Every one of them, today, has to reverse-engineer the answer or take a human's word for it, because there is no conventional place to look. The web solved this class of problem before, one small well-known file at a time.

What it publishes

• Posture: a readiness score, a hybrid-key-exchange flag (operator-assertable, since a static scan cannot observe a negotiated TLS group), and quantum-vulnerable finding counts by severity.
• CBOM summary: the algorithm families in use and a link to the full cryptographic bill of materials, so the manifest stays small while the detail is one hop away.
• Attestation: an optional link to an independently verifiable credential, recorded verbatim and never fetched by the emitter.
• Policy: the deadlines the project commits to, defaulting to the named ones (deprecate classical public-key algorithms after 2030, disallow after 2035), with a citation.

How a machine would use it

• An agent updating your code reads a dependency's manifest and declines to pull one still on a deprecated curve.
• A CI gate fails a build whose own manifest slipped below the bar the project set.
• A researcher reads the manifests across a sector and publishes the distribution without commissioning a single audit, which is what the PQC Observatory does by hand today, made cheap and continuous.

A claim, not a proof

It is worth being honest about what a self-published file is. Anyone can serve any JSON at a well-known address, so a self-reported readiness score is worth exactly the reader's trust in the reporter, which on its own is little. That is why one field is a link to an attestation a third party has verified and anyone can check. The manifest is the front door; the attestation is the thing behind it that does not depend on believing the owner. security.txt gives you a contact; this gives you a contact and a checkable record.

It is a proposal, and it reuses what exists

To be clear: `crypto-agility.json` is not a ratified standard, it is a convention we are proposing. It invents as little as possible, borrowing the well-known-URI mechanism (RFC 8615), the model of security.txt (RFC 9116), and the CycloneDX cryptography bill of materials, and pointing them at the one question none of them answers. A convention is worth only the number of parties who adopt it, so the specification is small, public, and deliberately boring. If the idea has merit, it is worth other people's edits.

Publish one today

The spec lives with our open-source tooling, and qScan produces the file from a scan you are probably already running: `qscan crypto-agility emit ./ -o public/.well-known/crypto-agility.json`, and `qscan crypto-agility validate <file>` checks a manifest against the schema, offline. A network fetch-and-validate and an MCP reader (so an agent can query a project's posture over the existing transport) are the obvious next steps, and are noted as follow-ups in the spec.

References

• RFC 8615 - Well-Known Uniform Resource Identifiers - the `/.well-known/` mechanism.
• RFC 9116 - A File Format to Aid in Security Vulnerability Disclosure (security.txt) - the model this echoes.
• CycloneDX Cryptography Bill of Materials (CBOM) - the machine-readable crypto inventory the manifest summarizes.
• NIST IR 8547 - Transition to Post-Quantum Cryptography Standards - the source of the default policy deadlines.