Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 3 additions & 5 deletions docs/MANIFEST.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
12 changes: 8 additions & 4 deletions docs/fjall-column-encryption.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
51 changes: 33 additions & 18 deletions docs/pq-content-key-wrapping.md
Original file line number Diff line number Diff line change
@@ -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
```
9 changes: 5 additions & 4 deletions docs/reference-store.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down