From 4a5320eee046425dd7da1d178518179cca742800 Mon Sep 17 00:00:00 2001 From: forkwright Date: Wed, 26 Aug 2026 15:57:36 -0500 Subject: [PATCH] docs(akroasis): correct Sphragis review boundary --- docs/MANIFEST.toml | 8 ++---- docs/fjall-column-encryption.md | 12 +++++--- docs/pq-content-key-wrapping.md | 51 +++++++++++++++++++++------------ docs/reference-store.md | 9 +++--- 4 files changed, 49 insertions(+), 31 deletions(-) diff --git a/docs/MANIFEST.toml b/docs/MANIFEST.toml index b64ddcb..0f2daf6 100644 --- a/docs/MANIFEST.toml +++ b/docs/MANIFEST.toml @@ -39,17 +39,15 @@ description = "Layout of the long-term offline reference store and its ownership [[doc]] path = "docs/fjall-column-encryption.md" -type = "decision-record" +type = "authored" evergreen = true description = "Corrected Pinax/Akroasis authority boundary for reference-library encryption." -decided = "2026-08-17" [[doc]] path = "docs/pq-content-key-wrapping.md" -type = "decision-record" +type = "authored" evergreen = true -description = "Post-quantum content-key wrapping for multi-device key distribution." -decided = "2026-08-17" +description = "Living Sphragis boundary and promotion gates for future content-key distribution." # WHY authored and not generated: it is a hand-written example config a reader copies from, not output # any command reproduces — a generate_cmd here would be a claim nobody could run. diff --git a/docs/fjall-column-encryption.md b/docs/fjall-column-encryption.md index c0e3d8d..4eb6e71 100644 --- a/docs/fjall-column-encryption.md +++ b/docs/fjall-column-encryption.md @@ -8,8 +8,8 @@ relational engine and its page-at-rest encryption. Akroasis owns only the reference-library domain-envelope policy above that engine. The historical filename remains so existing issue and review links still -resolve. This note records the corrected authority boundary; it is not an -implementation of #132. +resolve. This living note maintains the corrected authority boundary. It is not +an implementation of #132. ## Current State @@ -63,8 +63,12 @@ only while the preview contract explicitly permits that behavior. separate credential-vault domain. - Do not copy Pinax page-encryption policy into Akroasis or treat page encryption as recipient distribution. -- Do not call Sphragis `hazmat` or raw KEM operations. The reviewed profile API - is the only permitted recipient-wrapping boundary. +- Do not call Sphragis `hazmat` or raw KEM operations. Its versioned profile API + is the only permitted recipient-wrapping boundary. Sphragis exposes its PQ + profile as an unaudited, default-inert preview. + [`forkwright/sphragis#43`](https://github.com/forkwright/sphragis/issues/43) + owns qualified review and release promotion. Akroasis #395 owns the exact + consumer handoff. ## Review gates diff --git a/docs/pq-content-key-wrapping.md b/docs/pq-content-key-wrapping.md index 125f1db..54f7fc3 100644 --- a/docs/pq-content-key-wrapping.md +++ b/docs/pq-content-key-wrapping.md @@ -1,35 +1,50 @@ # PQ Content-Key Wrapping -Design decision for #131 (multi-device content-key distribution) is finalized. -Implementation lives in the standalone crate `forkwright/sphragis`. +The construction selected through #131 (multi-device content-key distribution) +remains the historical design basis. Implementation and cryptographic review +live in the standalone [`forkwright/sphragis`](https://github.com/forkwright/sphragis) +crate. Akroasis has no Sphragis dependency and has not adopted a release for a +durable consumer. -## Adopted Design +## Construction boundary **X-Wing hybrid KEM** (X25519 + ML-KEM-768), HKDF-SHA256 envelope, ChaCha20-Poly1305 seal, per-recipient `WrappedContentKey` (CBOR). Full rationale in `forkwright/sphragis/DECISION.md`. -The earlier note's "PQ-only ML-KEM" direction is superseded. The hybrid construction -is the correct choice: an adversary must break both ML-KEM and X25519, matching -TLS 1.3 (`X25519MLKEM768`), Signal (PQXDH), and the CFRG general-purpose answer -(X-Wing). +The hybrid design supersedes the earlier note's "PQ-only ML-KEM" direction. +The selected future profile uses a hybrid construction so its security goal +does not depend on only ML-KEM or only X25519. Akroasis may consume only +Sphragis's versioned profile API. Akroasis must not call `hazmat` or raw-KEM +operations. -## Dependency +## Consumer adoption -```toml -sphragis = { git = "https://github.com/forkwright/sphragis", features = ["preview-pq"] } -``` +Sphragis exposes its PQ profile as an unaudited, default-inert preview. No +published Sphragis tag is a reviewed consumer handoff. If #395 introduces a +preview integration before a reviewed release exists, it must remain behind a +default-off Akroasis feature and pin Sphragis to an exact immutable revision. +A moving Git branch or repository HEAD is not an acceptable dependency. + +The intended wire domain is `WRAP_DOMAIN_V1 = "sphragis-ck-wrap-v1"`. + +## Evidence and promotion ownership -Wire format: `WRAP_DOMAIN_V1 = "sphragis-ck-wrap-v1"`. +Known-answer tests for X-Wing, HKDF, and X25519 establish conformance to their +claimed vectors. They do not establish implementation security or substitute +for qualified independent cryptographic review. -## Status +[`forkwright/sphragis#43`](https://github.com/forkwright/sphragis/issues/43) +owns qualified review and promotion to a reviewed Sphragis release. Akroasis +#395 owns the exact immutable revision or release tag accepted by the first +consumer. Akroasis must keep preview use default-off before that exact handoff. -Unaudited preview behind `preview-pq`. The known-answer tests (X-Wing draft KAT, -RFC 5869, RFC 7748) prove the construction; cryptographic review per #131 -done-criterion 6 is the remaining gate before promotion to default. +## Preview verification -## Acceptance gate +Verification belongs to Sphragis, not the Akroasis workspace. Run it in a +Sphragis checkout at the exact immutable revision recorded by the consumer, or +use Sphragis CI for that same revision: ```sh -cargo test -p sphragis --features preview-pq # 12 tests +cargo test --features preview-pq ``` diff --git a/docs/reference-store.md b/docs/reference-store.md index d5b10d4..e4b805d 100644 --- a/docs/reference-store.md +++ b/docs/reference-store.md @@ -18,10 +18,11 @@ temporary blocking adapter. The encryption authorities are distinct. Pinax owns encryption of its database pages at rest. Akroasis owns the domain-envelope policy for reference content, including which payloads require envelopes and how content-key epochs map to -the application model. Sphragis supplies recipient distribution for those -content keys through its reviewed profile API; it does not replace Pinax page -encryption, and Pinax page encryption does not replace recipient-scoped -envelopes. Issue #395 tracks the integration and promotion gates. +the application model. Sphragis is the producer for recipient distribution. +Its versioned profile API exposes an unaudited, default-inert PQ preview. +Sphragis does not replace Pinax page encryption, and Pinax page encryption does +not replace recipient-scoped envelopes. Issue #395 tracks the integration and +exact-handoff gates. ## Canonical path