ADR 0010: Crypto capability negotiation

Use strict reader/writer capability documents and bridge releases to stage future cryptographic-suite migrations without unsafe downgrades.

Status: accepted as algorithm-migration groundwork.

Persisted version numbers alone do not prove that two concurrently deployed application clients can read each other’s cryptographic suites. A rollout that enables a new writer before every active reader understands it can make newly written records or recovery material unavailable to older clients.

@ownfold/core therefore publishes PersistedCryptoCapabilities.current, a strict ownfold.crypto-capabilities V1 document. For encrypted envelopes, Recovery Kits, device envelopes, and protected local device keys, it separately declares the suite identifiers readable by this release and the suite emitted by new writes. Recovery suite identifiers include fixed KDF parameters because changing them is a cryptographic migration, not configuration drift.

PersistedCryptoCapabilities.checkCompatibility(local, remote) requires both releases to read the other release’s writer suite for every persisted cryptographic format. It returns a discriminated incompatibility value naming the first unsafe format and both directional results. The capability parser rejects unknown fields, duplicate readers, empty lists, unsupported document versions, and a writer absent from its own read list.

Future migrations use three stages:

1. The old release reads and writes suite A.
2. A bridge release reads A and B but continues writing A.
3. Only after the bridge is deployed across the supported client population may a later release read A and B while writing B.

The host application may exchange these public, non-secret documents through its own deployment or coordination system. Ownfold does not add a hosted negotiation service or automatically downgrade writers based on untrusted remote input. Capability documents are compatibility evidence, not an authentication mechanism; a malicious deployment is already inside the browser trust boundary.

Adding suite B still requires a separate primitive ADR, expert review, implementation, immutable vectors, parser and authenticated-data changes, migration logic, rollback analysis, and an independent security audit. This decision creates the rollout contract only; it does not approve a second suite.