//! Generated by `trust-tasks-codegen` — do not edit by hand.
//!
//! Spec slug: `rooms/keys/chain`. Version: `0.2`.
/// Why this specification version is deprecated (SPEC "Superseded and
/// Withdrawn Versions"), or `None` while it is current.
pub const DEPRECATION: Option<&str> = None;
#[allow(unused_imports)]
use serde::{Deserialize, Serialize};
/// Error types.
pub mod error {
/// Error from a `TryFrom` or `FromStr` implementation.
pub struct ConversionError(::std::borrow::Cow<'static, str>);
impl ::std::error::Error for ConversionError {}
impl ::std::fmt::Display for ConversionError {
fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> Result<(), ::std::fmt::Error> {
::std::fmt::Display::fmt(&self.0, f)
}
}
impl ::std::fmt::Debug for ConversionError {
fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> Result<(), ::std::fmt::Error> {
::std::fmt::Debug::fmt(&self.0, f)
}
}
impl From<&'static str> for ConversionError {
fn from(value: &'static str) -> Self {
Self(value.into())
}
}
impl From<String> for ConversionError {
fn from(value: String) -> Self {
Self(value.into())
}
}
}
/**
The earliest epoch whose storage key a room still lets anybody derive: its chain was pruned below it (`rooms/epoch/prune`), and every epoch under it is meant to be unreadable — at the host, and, as far as each of them conforms, at every member's key holder. Absent means the room's chain has never been pruned.
**The off-by-one, stated once.** A rung (`EpochLink`) numbered `e` opens with epoch `e`'s key and yields epoch `e − 1`'s. A prune with `beforeEpoch: N` drops the rungs numbered below `N`, so rung `N` survives and still yields epoch `N − 1`'s key; the floor after it is therefore `N − 1`, never `N`. A party applying a floor `F` discards the rungs numbered `F` and below — rung `F` would yield `F − 1` — and every key for an epoch below `F`.
**Monotonic.** A floor only rises. A host raises the room's to the higher of the floor it held and `beforeEpoch − 1` at each prune it performs, and never lowers it; every other party keeps the highest it has learnt for the room, from any source, and never lowers it either. A lower floor learnt later — from a stale response, or a host that has not been pruned — changes nothing.
**A host** that holds a floor for a room MUST NOT store, accept or serve a rung numbered at or below it, and MUST serve the floor wherever a response can carry it (`rooms/epoch/chain` 0.2, `rooms/epoch/prune` 0.2).
**A member's key holder** — and any client of the member that keeps the room's rungs or keys itself — on learning a floor `F` above the one it held, by any means (`rooms/epoch/chain` 0.2 in its own reads, `rooms/keys/backfill` 0.2, `rooms/keys/chain` 0.2 from its principal):
1. MUST discard every rung it holds for the room numbered `F` or below, and every storage key, file key or other key material it holds or has cached for an epoch below `F` — including one it derived in passing while applying commits through those epochs (`rooms/keys/commit`, `rooms/epoch/commits`);
2. MUST NOT store such a rung or key again from any source — a delivery from its principal, a backfill, a repair, a catch-up, or a host that has not been pruned — and MUST NOT ask for one;
3. MUST refuse to derive or use a key for an epoch below `F`, answering exactly as it answers for an epoch its chain does not reach (`beyondChain`, with an earliest epoch at or above `F`), whatever it still holds;
4. MUST keep `F` itself for as long as it holds anything for the room, since it is what makes items 2 and 3 enforceable after the material is gone.
A key holder SHOULD learn the floor whenever it fetches rungs or catches up, and SHOULD ask for it — a `rooms/epoch/chain` 0.2 read carries it whatever `fromEpoch` and `limit` it names — at least as often as it otherwise reads the room. One that never asks never learns, and keeps what it held.
**What a floor does not do, stated plainly.** It is honoured by parties that conform; it does not reach into one that does not, and it recalls nothing. Plaintext a key holder already returned, records a member already opened, files already downloaded and decrypted, exports, and any key a member's own software extracted are beyond it. What it guarantees cryptographically is what the prune guarantees: a party that had not derived a key below the floor before the host erased its rungs can never derive it afterwards. What it adds is that every conforming key holder stops being able to — so that a restart, a new device or an agent's next recall reads nothing below the floor, rather than everything its holder happened to keep.*/
///
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[serde(transparent)]
pub struct EpochFloor(pub ::std::num::NonZeroU64);
impl ::std::ops::Deref for EpochFloor {
type Target = ::std::num::NonZeroU64;
fn deref(&self) -> &::std::num::NonZeroU64 {
&self.0
}
}
impl ::std::convert::From<EpochFloor> for ::std::num::NonZeroU64 {
fn from(value: EpochFloor) -> Self {
value.0
}
}
impl ::std::convert::From<::std::num::NonZeroU64> for EpochFloor {
fn from(value: ::std::num::NonZeroU64) -> Self {
Self(value)
}
}
impl ::std::str::FromStr for EpochFloor {
type Err = <::std::num::NonZeroU64 as ::std::str::FromStr>::Err;
fn from_str(value: &str) -> ::std::result::Result<Self, Self::Err> {
Ok(Self(value.parse()?))
}
}
impl ::std::convert::TryFrom<&str> for EpochFloor {
type Error = <::std::num::NonZeroU64 as ::std::str::FromStr>::Err;
fn try_from(value: &str) -> ::std::result::Result<Self, Self::Error> {
value.parse()
}
}
impl ::std::convert::TryFrom<String> for EpochFloor {
type Error = <::std::num::NonZeroU64 as ::std::str::FromStr>::Err;
fn try_from(value: String) -> ::std::result::Result<Self, Self::Error> {
value.parse()
}
}
impl ::std::fmt::Display for EpochFloor {
fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> ::std::fmt::Result {
self.0.fmt(f)
}
}
///One rung of a room's epoch key chain: the storage key of epoch `epoch - 1`, sealed under the storage key of `epoch`. A group key schedule offers no way to derive an earlier epoch's key from a later one — that property is what makes removing a member mean something — so without a chain the first membership change makes every record already in the room unopenable by everyone, including whoever wrote it. The chain is the one-way street run deliberately the other way: a member holding the current key walks it backwards to any retained epoch, and a member holding an earlier key still derives nothing later. Removal stays forward-only; reading stays possible. What a chain costs is stated where it is chosen, in the room's retention policy.
///
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
pub struct EpochLink {
///The epoch whose storage key opens this link; it wraps the storage key of `epoch - 1`. Never 1: a room's first epoch has no predecessor, so a link claiming one wraps something that is not an earlier epoch's key.
pub epoch: i64,
///AEAD nonce, base64url.
pub nonce: ::std::string::String,
///The wrapped predecessor key, base64url. Bound by AEAD associated data to `roomId` and to this link's own position in the chain, so a link lifted to another rung, or served under another room, fails to open rather than yielding a key that is wrong. The binding is load-bearing rather than decorative: every rung is a fixed-length key sealed under a fixed-length key, so nothing about the ciphertext itself says where it belongs.
pub wrapped: ::std::string::String,
}
impl EpochLink {
pub fn builder() -> builder::EpochLink {
Default::default()
}
}
///Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.
///
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[serde(transparent)]
pub struct Ext(pub ::std::collections::HashMap<ExtKey, ::serde_json::Value>);
impl ::std::ops::Deref for Ext {
type Target = ::std::collections::HashMap<ExtKey, ::serde_json::Value>;
fn deref(&self) -> &::std::collections::HashMap<ExtKey, ::serde_json::Value> {
&self.0
}
}
impl ::std::convert::From<Ext> for ::std::collections::HashMap<ExtKey, ::serde_json::Value> {
fn from(value: Ext) -> Self {
value.0
}
}
impl ::std::convert::From<::std::collections::HashMap<ExtKey, ::serde_json::Value>> for Ext {
fn from(value: ::std::collections::HashMap<ExtKey, ::serde_json::Value>) -> Self {
Self(value)
}
}
///`ExtKey`
///
#[derive(::serde::Serialize, Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
#[serde(transparent)]
pub struct ExtKey(::std::string::String);
impl ::std::ops::Deref for ExtKey {
type Target = ::std::string::String;
fn deref(&self) -> &::std::string::String {
&self.0
}
}
impl ::std::convert::From<ExtKey> for ::std::string::String {
fn from(value: ExtKey) -> Self {
value.0
}
}
impl ::std::str::FromStr for ExtKey {
type Err = self::error::ConversionError;
fn from_str(value: &str) -> ::std::result::Result<Self, self::error::ConversionError> {
static PATTERN: ::std::sync::LazyLock<::regress::Regex> =
::std::sync::LazyLock::new(|| {
::regress::Regex::new("^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$").unwrap()
});
if PATTERN.find(value).is_none() {
return Err("doesn't match pattern \"^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$\"".into());
}
Ok(Self(value.to_string()))
}
}
impl ::std::convert::TryFrom<&str> for ExtKey {
type Error = self::error::ConversionError;
fn try_from(value: &str) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<&::std::string::String> for ExtKey {
type Error = self::error::ConversionError;
fn try_from(
value: &::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl ::std::convert::TryFrom<::std::string::String> for ExtKey {
type Error = self::error::ConversionError;
fn try_from(
value: ::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
impl<'de> ::serde::Deserialize<'de> for ExtKey {
fn deserialize<D>(deserializer: D) -> ::std::result::Result<Self, D::Error>
where
D: ::serde::Deserializer<'de>,
{
::std::string::String::deserialize(deserializer)?
.parse()
.map_err(|e: self::error::ConversionError| {
<D::Error as ::serde::de::Error>::custom(e.to_string())
})
}
}
///`Payload`
///
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
pub struct Payload {
///The room's epoch floor, exactly as the host served it in the `rooms/epoch/chain` 0.2 response the rungs came from. A member relaying rungs MUST relay it when the host served one, and MAY send it alone, with no `links`, to pass on a floor it has just learnt. The recipient applies it as `EpochFloor` requires.
#[serde(
rename = "epochFloor",
default,
skip_serializing_if = "::std::option::Option::is_none"
)]
pub epoch_floor: ::std::option::Option<EpochFloor>,
///Ecosystem-defined extension members per SPEC.md §4.5.1.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub ext: ::std::option::Option<Ext>,
///The rungs, in any order. A recipient stores those numbered above the room's epoch floor — the higher of the one it holds and `epochFloor` — and reports how far back it can now reach; see the response's `earliestReadableEpoch`. Absent when the request only relays a floor.
#[serde(default, skip_serializing_if = "::std::vec::Vec::is_empty")]
pub links: ::std::vec::Vec<EpochLink>,
///The room whose chain these rungs belong to. The recipient MUST hold group state for it, and MUST NOT create any on the strength of this request: rungs are inert without an epoch key, so accepting them for a room one is not in would retain key material for nothing.
#[serde(rename = "roomId")]
pub room_id: ::std::string::String,
}
impl Payload {
pub fn builder() -> builder::Payload {
Default::default()
}
}
///Success response to rooms/keys/chain. Type https://trusttasks.org/spec/rooms/keys/chain/0.2#response.
///
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
pub struct Response {
///The earliest epoch the recipient can now derive a key for, having walked the chain it holds. **This is the answer worth having**, and it is not a restatement of what was sent: a rung only extends reach if every rung above it is present too, so a caller that supplied a set with a gap in it learns that here rather than at the first record that will not open. `1` means the room's whole history is reachable.
#[serde(rename = "earliestReadableEpoch")]
pub earliest_readable_epoch: ::std::num::NonZeroU64,
///The room's epoch floor the recipient now holds — the highest it has learnt from any source. Absent when it holds none. `earliestReadableEpoch` is never below it.
#[serde(
rename = "epochFloor",
default,
skip_serializing_if = "::std::option::Option::is_none"
)]
pub epoch_floor: ::std::option::Option<EpochFloor>,
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub ext: ::std::option::Option<Ext>,
#[serde(rename = "roomId")]
pub room_id: ::std::string::String,
///How many rungs the recipient did not already hold and kept. Rungs numbered at or below the room's epoch floor are not kept and not counted, and are not an error: a member relaying a mirror's chain may hold some. Zero is a success, not a no-op: it means the caller's chain was already delivered, which is what a retry looks like.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub stored: ::std::option::Option<u64>,
}
impl Response {
pub fn builder() -> builder::Response {
Default::default()
}
}
/// Types for composing complex structures.
pub mod builder {
#[derive(Clone, Debug)]
pub struct EpochLink {
epoch: ::std::result::Result<i64, ::std::string::String>,
nonce: ::std::result::Result<::std::string::String, ::std::string::String>,
wrapped: ::std::result::Result<::std::string::String, ::std::string::String>,
}
impl ::std::default::Default for EpochLink {
fn default() -> Self {
Self {
epoch: Err("no value supplied for epoch".to_string()),
nonce: Err("no value supplied for nonce".to_string()),
wrapped: Err("no value supplied for wrapped".to_string()),
}
}
}
impl EpochLink {
pub fn epoch<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<i64>,
T::Error: ::std::fmt::Display,
{
self.epoch = value
.try_into()
.map_err(|e| format!("error converting supplied value for epoch: {e}"));
self
}
pub fn nonce<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::string::String>,
T::Error: ::std::fmt::Display,
{
self.nonce = value
.try_into()
.map_err(|e| format!("error converting supplied value for nonce: {e}"));
self
}
pub fn wrapped<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::string::String>,
T::Error: ::std::fmt::Display,
{
self.wrapped = value
.try_into()
.map_err(|e| format!("error converting supplied value for wrapped: {e}"));
self
}
}
impl ::std::convert::TryFrom<EpochLink> for super::EpochLink {
type Error = super::error::ConversionError;
fn try_from(
value: EpochLink,
) -> ::std::result::Result<Self, super::error::ConversionError> {
Ok(Self {
epoch: value.epoch?,
nonce: value.nonce?,
wrapped: value.wrapped?,
})
}
}
impl ::std::convert::From<super::EpochLink> for EpochLink {
fn from(value: super::EpochLink) -> Self {
Self {
epoch: Ok(value.epoch),
nonce: Ok(value.nonce),
wrapped: Ok(value.wrapped),
}
}
}
#[derive(Clone, Debug)]
pub struct Payload {
epoch_floor:
::std::result::Result<::std::option::Option<super::EpochFloor>, ::std::string::String>,
ext: ::std::result::Result<::std::option::Option<super::Ext>, ::std::string::String>,
links: ::std::result::Result<::std::vec::Vec<super::EpochLink>, ::std::string::String>,
room_id: ::std::result::Result<::std::string::String, ::std::string::String>,
}
impl ::std::default::Default for Payload {
fn default() -> Self {
Self {
epoch_floor: Ok(Default::default()),
ext: Ok(Default::default()),
links: Ok(Default::default()),
room_id: Err("no value supplied for room_id".to_string()),
}
}
}
impl Payload {
pub fn epoch_floor<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::option::Option<super::EpochFloor>>,
T::Error: ::std::fmt::Display,
{
self.epoch_floor = value
.try_into()
.map_err(|e| format!("error converting supplied value for epoch_floor: {e}"));
self
}
pub fn ext<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::option::Option<super::Ext>>,
T::Error: ::std::fmt::Display,
{
self.ext = value
.try_into()
.map_err(|e| format!("error converting supplied value for ext: {e}"));
self
}
pub fn links<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::vec::Vec<super::EpochLink>>,
T::Error: ::std::fmt::Display,
{
self.links = value
.try_into()
.map_err(|e| format!("error converting supplied value for links: {e}"));
self
}
pub fn room_id<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::string::String>,
T::Error: ::std::fmt::Display,
{
self.room_id = value
.try_into()
.map_err(|e| format!("error converting supplied value for room_id: {e}"));
self
}
}
impl ::std::convert::TryFrom<Payload> for super::Payload {
type Error = super::error::ConversionError;
fn try_from(value: Payload) -> ::std::result::Result<Self, super::error::ConversionError> {
Ok(Self {
epoch_floor: value.epoch_floor?,
ext: value.ext?,
links: value.links?,
room_id: value.room_id?,
})
}
}
impl ::std::convert::From<super::Payload> for Payload {
fn from(value: super::Payload) -> Self {
Self {
epoch_floor: Ok(value.epoch_floor),
ext: Ok(value.ext),
links: Ok(value.links),
room_id: Ok(value.room_id),
}
}
}
#[derive(Clone, Debug)]
pub struct Response {
earliest_readable_epoch:
::std::result::Result<::std::num::NonZeroU64, ::std::string::String>,
epoch_floor:
::std::result::Result<::std::option::Option<super::EpochFloor>, ::std::string::String>,
ext: ::std::result::Result<::std::option::Option<super::Ext>, ::std::string::String>,
room_id: ::std::result::Result<::std::string::String, ::std::string::String>,
stored: ::std::result::Result<::std::option::Option<u64>, ::std::string::String>,
}
impl ::std::default::Default for Response {
fn default() -> Self {
Self {
earliest_readable_epoch: Err(
"no value supplied for earliest_readable_epoch".to_string()
),
epoch_floor: Ok(Default::default()),
ext: Ok(Default::default()),
room_id: Err("no value supplied for room_id".to_string()),
stored: Ok(Default::default()),
}
}
}
impl Response {
pub fn earliest_readable_epoch<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::num::NonZeroU64>,
T::Error: ::std::fmt::Display,
{
self.earliest_readable_epoch = value.try_into().map_err(|e| {
format!("error converting supplied value for earliest_readable_epoch: {e}")
});
self
}
pub fn epoch_floor<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::option::Option<super::EpochFloor>>,
T::Error: ::std::fmt::Display,
{
self.epoch_floor = value
.try_into()
.map_err(|e| format!("error converting supplied value for epoch_floor: {e}"));
self
}
pub fn ext<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::option::Option<super::Ext>>,
T::Error: ::std::fmt::Display,
{
self.ext = value
.try_into()
.map_err(|e| format!("error converting supplied value for ext: {e}"));
self
}
pub fn room_id<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::string::String>,
T::Error: ::std::fmt::Display,
{
self.room_id = value
.try_into()
.map_err(|e| format!("error converting supplied value for room_id: {e}"));
self
}
pub fn stored<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::option::Option<u64>>,
T::Error: ::std::fmt::Display,
{
self.stored = value
.try_into()
.map_err(|e| format!("error converting supplied value for stored: {e}"));
self
}
}
impl ::std::convert::TryFrom<Response> for super::Response {
type Error = super::error::ConversionError;
fn try_from(value: Response) -> ::std::result::Result<Self, super::error::ConversionError> {
Ok(Self {
earliest_readable_epoch: value.earliest_readable_epoch?,
epoch_floor: value.epoch_floor?,
ext: value.ext?,
room_id: value.room_id?,
stored: value.stored?,
})
}
}
impl ::std::convert::From<super::Response> for Response {
fn from(value: super::Response) -> Self {
Self {
earliest_readable_epoch: Ok(value.earliest_readable_epoch),
epoch_floor: Ok(value.epoch_floor),
ext: Ok(value.ext),
room_id: Ok(value.room_id),
stored: Ok(value.stored),
}
}
}
}
impl crate::Payload for Payload {
const TYPE_URI: &'static str = "https://trusttasks.org/spec/rooms/keys/chain/0.2";
const IS_PROOF_REQUIRED: bool = true;
const IS_ISSUED_AT_REQUIRED: bool = true;
const IS_RECIPIENT_REQUIRED: bool = true;
const PAYLOAD_SCHEMA: Option<&'static str> = Some(
"{\"$defs\":{\"EpochFloor\":{\"description\":\"The earliest epoch whose storage key a room still lets anybody derive: its chain was pruned below it (`rooms/epoch/prune`), and every epoch under it is meant to be unreadable — at the host, and, as far as each of them conforms, at every member's key holder. Absent means the room's chain has never been pruned.\\n\\n**The off-by-one, stated once.** A rung (`EpochLink`) numbered `e` opens with epoch `e`'s key and yields epoch `e − 1`'s. A prune with `beforeEpoch: N` drops the rungs numbered below `N`, so rung `N` survives and still yields epoch `N − 1`'s key; the floor after it is therefore `N − 1`, never `N`. A party applying a floor `F` discards the rungs numbered `F` and below — rung `F` would yield `F − 1` — and every key for an epoch below `F`.\\n\\n**Monotonic.** A floor only rises. A host raises the room's to the higher of the floor it held and `beforeEpoch − 1` at each prune it performs, and never lowers it; every other party keeps the highest it has learnt for the room, from any source, and never lowers it either. A lower floor learnt later — from a stale response, or a host that has not been pruned — changes nothing.\\n\\n**A host** that holds a floor for a room MUST NOT store, accept or serve a rung numbered at or below it, and MUST serve the floor wherever a response can carry it (`rooms/epoch/chain` 0.2, `rooms/epoch/prune` 0.2).\\n\\n**A member's key holder** — and any client of the member that keeps the room's rungs or keys itself — on learning a floor `F` above the one it held, by any means (`rooms/epoch/chain` 0.2 in its own reads, `rooms/keys/backfill` 0.2, `rooms/keys/chain` 0.2 from its principal):\\n 1. MUST discard every rung it holds for the room numbered `F` or below, and every storage key, file key or other key material it holds or has cached for an epoch below `F` — including one it derived in passing while applying commits through those epochs (`rooms/keys/commit`, `rooms/epoch/commits`);\\n 2. MUST NOT store such a rung or key again from any source — a delivery from its principal, a backfill, a repair, a catch-up, or a host that has not been pruned — and MUST NOT ask for one;\\n 3. MUST refuse to derive or use a key for an epoch below `F`, answering exactly as it answers for an epoch its chain does not reach (`beyondChain`, with an earliest epoch at or above `F`), whatever it still holds;\\n 4. MUST keep `F` itself for as long as it holds anything for the room, since it is what makes items 2 and 3 enforceable after the material is gone.\\n\\nA key holder SHOULD learn the floor whenever it fetches rungs or catches up, and SHOULD ask for it — a `rooms/epoch/chain` 0.2 read carries it whatever `fromEpoch` and `limit` it names — at least as often as it otherwise reads the room. One that never asks never learns, and keeps what it held.\\n\\n**What a floor does not do, stated plainly.** It is honoured by parties that conform; it does not reach into one that does not, and it recalls nothing. Plaintext a key holder already returned, records a member already opened, files already downloaded and decrypted, exports, and any key a member's own software extracted are beyond it. What it guarantees cryptographically is what the prune guarantees: a party that had not derived a key below the floor before the host erased its rungs can never derive it afterwards. What it adds is that every conforming key holder stops being able to — so that a restart, a new device or an agent's next recall reads nothing below the floor, rather than everything its holder happened to keep.\",\"minimum\":1,\"title\":\"EpochFloor\",\"type\":\"integer\"},\"EpochLink\":{\"additionalProperties\":false,\"description\":\"One rung of a room's epoch key chain: the storage key of epoch `epoch - 1`, sealed under the storage key of `epoch`. A group key schedule offers no way to derive an earlier epoch's key from a later one — that property is what makes removing a member mean something — so without a chain the first membership change makes every record already in the room unopenable by everyone, including whoever wrote it. The chain is the one-way street run deliberately the other way: a member holding the current key walks it backwards to any retained epoch, and a member holding an earlier key still derives nothing later. Removal stays forward-only; reading stays possible. What a chain costs is stated where it is chosen, in the room's retention policy.\",\"properties\":{\"epoch\":{\"description\":\"The epoch whose storage key opens this link; it wraps the storage key of `epoch - 1`. Never 1: a room's first epoch has no predecessor, so a link claiming one wraps something that is not an earlier epoch's key.\",\"minimum\":2,\"type\":\"integer\"},\"nonce\":{\"description\":\"AEAD nonce, base64url.\",\"type\":\"string\"},\"wrapped\":{\"description\":\"The wrapped predecessor key, base64url. Bound by AEAD associated data to `roomId` and to this link's own position in the chain, so a link lifted to another rung, or served under another room, fails to open rather than yielding a key that is wrong. The binding is load-bearing rather than decorative: every rung is a fixed-length key sealed under a fixed-length key, so nothing about the ciphertext itself says where it belongs.\",\"type\":\"string\"}},\"required\":[\"epoch\",\"wrapped\",\"nonce\"],\"title\":\"EpochLink\",\"type\":\"object\"},\"Ext\":{\"additionalProperties\":true,\"description\":\"Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.\",\"minProperties\":1,\"propertyNames\":{\"pattern\":\"^[a-z][a-z0-9-]*(\\\\.[a-z0-9-]+)+$\"},\"title\":\"Ext\",\"type\":\"object\"},\"Response\":{\"$anchor\":\"response\",\"additionalProperties\":false,\"description\":\"Success response to rooms/keys/chain. Type https://trusttasks.org/spec/rooms/keys/chain/0.2#response.\",\"properties\":{\"earliestReadableEpoch\":{\"description\":\"The earliest epoch the recipient can now derive a key for, having walked the chain it holds. **This is the answer worth having**, and it is not a restatement of what was sent: a rung only extends reach if every rung above it is present too, so a caller that supplied a set with a gap in it learns that here rather than at the first record that will not open. `1` means the room's whole history is reachable.\",\"minimum\":1,\"type\":\"integer\"},\"epochFloor\":{\"$ref\":\"#/$defs/EpochFloor\",\"description\":\"The room's epoch floor the recipient now holds — the highest it has learnt from any source. Absent when it holds none. `earliestReadableEpoch` is never below it.\"},\"ext\":{\"$ref\":\"#/$defs/Ext\"},\"roomId\":{\"type\":\"string\"},\"stored\":{\"description\":\"How many rungs the recipient did not already hold and kept. Rungs numbered at or below the room's epoch floor are not kept and not counted, and are not an error: a member relaying a mirror's chain may hold some. Zero is a success, not a no-op: it means the caller's chain was already delivered, which is what a retry looks like.\",\"minimum\":0,\"type\":\"integer\"}},\"required\":[\"roomId\",\"earliestReadableEpoch\"],\"title\":\"Rooms Keys Chain — response payload\",\"type\":\"object\"}},\"$id\":\"https://trusttasks.org/spec/rooms/keys/chain/0.2\",\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"additionalProperties\":false,\"anyOf\":[{\"required\":[\"links\"]},{\"required\":[\"epochFloor\"]}],\"properties\":{\"epochFloor\":{\"$ref\":\"#/$defs/EpochFloor\",\"description\":\"The room's epoch floor, exactly as the host served it in the `rooms/epoch/chain` 0.2 response the rungs came from. A member relaying rungs MUST relay it when the host served one, and MAY send it alone, with no `links`, to pass on a floor it has just learnt. The recipient applies it as `EpochFloor` requires.\"},\"ext\":{\"$ref\":\"#/$defs/Ext\",\"description\":\"Ecosystem-defined extension members per SPEC.md §4.5.1.\"},\"links\":{\"description\":\"The rungs, in any order. A recipient stores those numbered above the room's epoch floor — the higher of the one it holds and `epochFloor` — and reports how far back it can now reach; see the response's `earliestReadableEpoch`. Absent when the request only relays a floor.\",\"items\":{\"$ref\":\"#/$defs/EpochLink\"},\"minItems\":1,\"type\":\"array\"},\"roomId\":{\"description\":\"The room whose chain these rungs belong to. The recipient MUST hold group state for it, and MUST NOT create any on the strength of this request: rungs are inert without an epoch key, so accepting them for a room one is not in would retain key material for nothing.\",\"type\":\"string\"}},\"required\":[\"roomId\"],\"title\":\"Rooms Keys Chain — payload\",\"type\":\"object\"}\n",
);
}
impl crate::Payload for Response {
const TYPE_URI: &'static str = "https://trusttasks.org/spec/rooms/keys/chain/0.2#response";
const IS_PROOF_REQUIRED: bool = true;
const IS_ISSUED_AT_REQUIRED: bool = true;
const IS_RECIPIENT_REQUIRED: bool = true;
const PAYLOAD_SCHEMA: Option<&'static str> = Some(
"{\"$defs\":{\"EpochFloor\":{\"description\":\"The earliest epoch whose storage key a room still lets anybody derive: its chain was pruned below it (`rooms/epoch/prune`), and every epoch under it is meant to be unreadable — at the host, and, as far as each of them conforms, at every member's key holder. Absent means the room's chain has never been pruned.\\n\\n**The off-by-one, stated once.** A rung (`EpochLink`) numbered `e` opens with epoch `e`'s key and yields epoch `e − 1`'s. A prune with `beforeEpoch: N` drops the rungs numbered below `N`, so rung `N` survives and still yields epoch `N − 1`'s key; the floor after it is therefore `N − 1`, never `N`. A party applying a floor `F` discards the rungs numbered `F` and below — rung `F` would yield `F − 1` — and every key for an epoch below `F`.\\n\\n**Monotonic.** A floor only rises. A host raises the room's to the higher of the floor it held and `beforeEpoch − 1` at each prune it performs, and never lowers it; every other party keeps the highest it has learnt for the room, from any source, and never lowers it either. A lower floor learnt later — from a stale response, or a host that has not been pruned — changes nothing.\\n\\n**A host** that holds a floor for a room MUST NOT store, accept or serve a rung numbered at or below it, and MUST serve the floor wherever a response can carry it (`rooms/epoch/chain` 0.2, `rooms/epoch/prune` 0.2).\\n\\n**A member's key holder** — and any client of the member that keeps the room's rungs or keys itself — on learning a floor `F` above the one it held, by any means (`rooms/epoch/chain` 0.2 in its own reads, `rooms/keys/backfill` 0.2, `rooms/keys/chain` 0.2 from its principal):\\n 1. MUST discard every rung it holds for the room numbered `F` or below, and every storage key, file key or other key material it holds or has cached for an epoch below `F` — including one it derived in passing while applying commits through those epochs (`rooms/keys/commit`, `rooms/epoch/commits`);\\n 2. MUST NOT store such a rung or key again from any source — a delivery from its principal, a backfill, a repair, a catch-up, or a host that has not been pruned — and MUST NOT ask for one;\\n 3. MUST refuse to derive or use a key for an epoch below `F`, answering exactly as it answers for an epoch its chain does not reach (`beyondChain`, with an earliest epoch at or above `F`), whatever it still holds;\\n 4. MUST keep `F` itself for as long as it holds anything for the room, since it is what makes items 2 and 3 enforceable after the material is gone.\\n\\nA key holder SHOULD learn the floor whenever it fetches rungs or catches up, and SHOULD ask for it — a `rooms/epoch/chain` 0.2 read carries it whatever `fromEpoch` and `limit` it names — at least as often as it otherwise reads the room. One that never asks never learns, and keeps what it held.\\n\\n**What a floor does not do, stated plainly.** It is honoured by parties that conform; it does not reach into one that does not, and it recalls nothing. Plaintext a key holder already returned, records a member already opened, files already downloaded and decrypted, exports, and any key a member's own software extracted are beyond it. What it guarantees cryptographically is what the prune guarantees: a party that had not derived a key below the floor before the host erased its rungs can never derive it afterwards. What it adds is that every conforming key holder stops being able to — so that a restart, a new device or an agent's next recall reads nothing below the floor, rather than everything its holder happened to keep.\",\"minimum\":1,\"title\":\"EpochFloor\",\"type\":\"integer\"},\"EpochLink\":{\"additionalProperties\":false,\"description\":\"One rung of a room's epoch key chain: the storage key of epoch `epoch - 1`, sealed under the storage key of `epoch`. A group key schedule offers no way to derive an earlier epoch's key from a later one — that property is what makes removing a member mean something — so without a chain the first membership change makes every record already in the room unopenable by everyone, including whoever wrote it. The chain is the one-way street run deliberately the other way: a member holding the current key walks it backwards to any retained epoch, and a member holding an earlier key still derives nothing later. Removal stays forward-only; reading stays possible. What a chain costs is stated where it is chosen, in the room's retention policy.\",\"properties\":{\"epoch\":{\"description\":\"The epoch whose storage key opens this link; it wraps the storage key of `epoch - 1`. Never 1: a room's first epoch has no predecessor, so a link claiming one wraps something that is not an earlier epoch's key.\",\"minimum\":2,\"type\":\"integer\"},\"nonce\":{\"description\":\"AEAD nonce, base64url.\",\"type\":\"string\"},\"wrapped\":{\"description\":\"The wrapped predecessor key, base64url. Bound by AEAD associated data to `roomId` and to this link's own position in the chain, so a link lifted to another rung, or served under another room, fails to open rather than yielding a key that is wrong. The binding is load-bearing rather than decorative: every rung is a fixed-length key sealed under a fixed-length key, so nothing about the ciphertext itself says where it belongs.\",\"type\":\"string\"}},\"required\":[\"epoch\",\"wrapped\",\"nonce\"],\"title\":\"EpochLink\",\"type\":\"object\"},\"Ext\":{\"additionalProperties\":true,\"description\":\"Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.\",\"minProperties\":1,\"propertyNames\":{\"pattern\":\"^[a-z][a-z0-9-]*(\\\\.[a-z0-9-]+)+$\"},\"title\":\"Ext\",\"type\":\"object\"},\"Response\":{\"$anchor\":\"response\",\"additionalProperties\":false,\"description\":\"Success response to rooms/keys/chain. Type https://trusttasks.org/spec/rooms/keys/chain/0.2#response.\",\"properties\":{\"earliestReadableEpoch\":{\"description\":\"The earliest epoch the recipient can now derive a key for, having walked the chain it holds. **This is the answer worth having**, and it is not a restatement of what was sent: a rung only extends reach if every rung above it is present too, so a caller that supplied a set with a gap in it learns that here rather than at the first record that will not open. `1` means the room's whole history is reachable.\",\"minimum\":1,\"type\":\"integer\"},\"epochFloor\":{\"$ref\":\"#/$defs/EpochFloor\",\"description\":\"The room's epoch floor the recipient now holds — the highest it has learnt from any source. Absent when it holds none. `earliestReadableEpoch` is never below it.\"},\"ext\":{\"$ref\":\"#/$defs/Ext\"},\"roomId\":{\"type\":\"string\"},\"stored\":{\"description\":\"How many rungs the recipient did not already hold and kept. Rungs numbered at or below the room's epoch floor are not kept and not counted, and are not an error: a member relaying a mirror's chain may hold some. Zero is a success, not a no-op: it means the caller's chain was already delivered, which is what a retry looks like.\",\"minimum\":0,\"type\":\"integer\"}},\"required\":[\"roomId\",\"earliestReadableEpoch\"],\"title\":\"Rooms Keys Chain — response payload\",\"type\":\"object\"}},\"$ref\":\"#/$defs/Response\",\"$schema\":\"https://json-schema.org/draft/2020-12/schema\"}\n",
);
}
impl crate::RequestPayload for Payload {
type Response = Response;
}
/// The earlier `MAJOR.MINOR` of this slug that this version declares it
/// extends (front matter `extends`, SPEC §5.2 "Declared extension"), or
/// `None`. Only the direct declaration; walk a chain with
/// [`crate::extension::extends_for`].
pub const EXTENDS: Option<&str> = None;
/// The extended error codes this specification declares (SPEC §7.3 item 9,
/// §8.5), in declaration order. Empty when it declares none.
pub const ERROR_CODES: &[crate::DeclaredErrorCode] = &[error_codes::NOT_A_MEMBER];
/// One constant per extended error code this specification declares
/// (SPEC §7.3 item 9), named for its local part.
///
/// Emit these rather than a string literal: the code is read from the
/// specification, so it cannot name a code the specification never
/// declared.
pub mod error_codes {
/// `rooms/keys/chain:notAMember`
///
/// The recipient holds no group state for this room, so there is nothing for the rungs to extend.
///
/// Declared `retryable: false`.
pub const NOT_A_MEMBER: crate::DeclaredErrorCode = crate::DeclaredErrorCode {
code: "rooms/keys/chain:notAMember",
retryable: false,
details_schema: ::core::option::Option::None,
};
}