//! Generated by `trust-tasks-codegen` — do not edit by hand.
//!
//! Spec slug: `rooms/records/get`. Version: `0.1`.
#[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())
}
}
}
///What a party presents to act on a room. Carries the whole authority chain: a host MUST NOT dereference an authority credential's `parent` to fetch a link it was not given. Resolving over the network would make verification depend on availability, turn every identifier into a request the host can be induced to make against an address the holder chooses, and signal credential use to whoever hosts the identifier. A host MUST bind the presenter to the chain's leaf. A chain that verifies is evidence that authority was conferred on somebody; it is not evidence that the party presenting it is that somebody. The leaf's subject MUST equal the party the host authenticated for this request — an identity the transport established or a document `proof` proved, never one named in a payload. A host that omits this check authorizes every captured presentation, and the omission is silent, because the chain still verifies.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "title": "AuthorityPresentation",
/// "description": "What a party presents to act on a room. Carries the whole authority chain: a host MUST NOT dereference an authority credential's `parent` to fetch a link it was not given. Resolving over the network would make verification depend on availability, turn every identifier into a request the host can be induced to make against an address the holder chooses, and signal credential use to whoever hosts the identifier. A host MUST bind the presenter to the chain's leaf. A chain that verifies is evidence that authority was conferred on somebody; it is not evidence that the party presenting it is that somebody. The leaf's subject MUST equal the party the host authenticated for this request — an identity the transport established or a document `proof` proved, never one named in a payload. A host that omits this check authorizes every captured presentation, and the omission is silent, because the chain still verifies.",
/// "type": "object",
/// "required": [
/// "authority",
/// "membership"
/// ],
/// "properties": {
/// "authority": {
/// "description": "The authority chain, LEAF FIRST: the first element is the credential being relied on and the last MUST be one issued by the room itself. Every link the presenter relies on is present, because the host will not fetch one. Capped at 8: verification is linear in chain length and runs on every operation, so an unbounded chain is a denial-of-service surface against the host. The known uses need 2 to 3 — a person attenuating to an agent, and that agent to a sub-agent.",
/// "type": "array",
/// "items": {
/// "type": "string"
/// },
/// "maxItems": 8,
/// "minItems": 1
/// },
/// "membership": {
/// "description": "The presenter's membership credential for this room, or — on a `private` room — a zero-knowledge presentation of it. Serialized per the governing profile.",
/// "type": "string"
/// },
/// "subjectBinding": {
/// "description": "REQUIRED on a `private` room, where the subject identifier is withheld: a proof that the membership credential and the authority chain's leaf describe the SAME subject. Without it two parties pool credentials — one contributes membership, the other authority — and the combination verifies as a single party holding both. A host MUST refuse a private-room presentation that omits this.",
/// "type": "string"
/// }
/// },
/// "additionalProperties": false
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
pub struct AuthorityPresentation {
///The authority chain, LEAF FIRST: the first element is the credential being relied on and the last MUST be one issued by the room itself. Every link the presenter relies on is present, because the host will not fetch one. Capped at 8: verification is linear in chain length and runs on every operation, so an unbounded chain is a denial-of-service surface against the host. The known uses need 2 to 3 — a person attenuating to an agent, and that agent to a sub-agent.
pub authority: ::std::vec::Vec<::std::string::String>,
///The presenter's membership credential for this room, or — on a `private` room — a zero-knowledge presentation of it. Serialized per the governing profile.
pub membership: ::std::string::String,
///REQUIRED on a `private` room, where the subject identifier is withheld: a proof that the membership credential and the authority chain's leaf describe the SAME subject. Without it two parties pool credentials — one contributes membership, the other authority — and the combination verifies as a single party holding both. A host MUST refuse a private-room presentation that omits this.
#[serde(
rename = "subjectBinding",
default,
skip_serializing_if = "::std::option::Option::is_none"
)]
pub subject_binding: ::std::option::Option<::std::string::String>,
}
impl AuthorityPresentation {
pub fn builder() -> builder::AuthorityPresentation {
Default::default()
}
}
/**
The root of the room's record tree — a host's commitment to *which records the room holds*, as distinct from what any one of them says.
A room's records are already signed and room-bound, so a host cannot forge, alter or relocate one. What it can do for free is stay silent: a listing that omits a record is indistinguishable from a room that never held it. This value is what makes that omission detectable, so it is only worth anything when the reader can compare it against a copy the host did not choose for them — one it gave another member, one it gave the same member earlier, or the witnessed anchor. A commitment read once, in isolation, proves nothing.
**A root on its own is not comparable, and an earlier revision of this description said it was.** It claimed a host showing two members two different roots had been caught, which is false while a room can move between two reads: the host answers *there was a write*, and nothing contradicts it. Comparison needs the state each root describes, which is what `HeadVersion` names — and `RecordCount` is the other half of the same omission, since Certificate Transparency's signed tree head is a root *and a size* and this family shipped only the root. A reader that receives a `dataCommitment` **without** them can use it against a witnessed anchor, where the epoch pins the state, and **MUST NOT** compare it against another root.
**The construction is normative**, because two hosts that compute different roots over the same room make every comparison meaningless:
1. Take every record the room holds — including tombstones, which are records — and order them by `key` using unsigned byte order.
2. Leaf: `SHA-256(0x00 || JCS(record))`, where the record is a `CommittedRecord` — that definition fixes the members exactly, and this step used to name a *projection* instead, which two implementations could read two ways — JCS is its RFC 8785 canonicalization, and `0x00` is RFC 6962's leaf-domain prefix.
3. Internal node: `SHA-256(0x01 || left || right)`.
4. A level with an odd number of nodes promotes the last one unchanged. It MUST NOT be duplicated: duplicating makes a tree of n leaves collide with one of n+1 whose last is repeated, so two different rooms commit to the same root.
5. A room holding no records commits to `SHA-256("")`, a distinguished value rather than zeroes — a root of zeroes is what an uninitialised buffer looks like, and an empty room is a real state a host must be able to commit to honestly.
The leaf covers the whole record rather than its body, and that is deliberate: a host that could flip `status` from active to retracted, move `pinned`, or rewrite `author` on an `attributed` room would rewrite what the room means without touching a byte of ciphertext. The **plaintext is never involved** — on the sealed tiers the host holds ciphertext and commits to exactly what it stores.
The commitment is over the **whole room**, never over the page being returned. A page-scoped root is one a host satisfies by construction and could never fail.
Proving that a *particular* record sits under this root is a separate question, answered by `RecordTrace` on a single-record read. A commitment catches a host that equivocates; a trace binds one record to what the host committed to. Neither is the other, and a reader wanting completeness needs both plus a root it did not get from the host it is checking.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "title": "DataCommitment",
/// "description": "\nThe root of the room's record tree — a host's commitment to *which records the room holds*, as distinct from what any one of them says.\n\nA room's records are already signed and room-bound, so a host cannot forge, alter or relocate one. What it can do for free is stay silent: a listing that omits a record is indistinguishable from a room that never held it. This value is what makes that omission detectable, so it is only worth anything when the reader can compare it against a copy the host did not choose for them — one it gave another member, one it gave the same member earlier, or the witnessed anchor. A commitment read once, in isolation, proves nothing.\n\n**A root on its own is not comparable, and an earlier revision of this description said it was.** It claimed a host showing two members two different roots had been caught, which is false while a room can move between two reads: the host answers *there was a write*, and nothing contradicts it. Comparison needs the state each root describes, which is what `HeadVersion` names — and `RecordCount` is the other half of the same omission, since Certificate Transparency's signed tree head is a root *and a size* and this family shipped only the root. A reader that receives a `dataCommitment` **without** them can use it against a witnessed anchor, where the epoch pins the state, and **MUST NOT** compare it against another root.\n\n**The construction is normative**, because two hosts that compute different roots over the same room make every comparison meaningless:\n 1. Take every record the room holds — including tombstones, which are records — and order them by `key` using unsigned byte order.\n 2. Leaf: `SHA-256(0x00 || JCS(record))`, where the record is a `CommittedRecord` — that definition fixes the members exactly, and this step used to name a *projection* instead, which two implementations could read two ways — JCS is its RFC 8785 canonicalization, and `0x00` is RFC 6962's leaf-domain prefix.\n 3. Internal node: `SHA-256(0x01 || left || right)`.\n 4. A level with an odd number of nodes promotes the last one unchanged. It MUST NOT be duplicated: duplicating makes a tree of n leaves collide with one of n+1 whose last is repeated, so two different rooms commit to the same root.\n 5. A room holding no records commits to `SHA-256(\"\")`, a distinguished value rather than zeroes — a root of zeroes is what an uninitialised buffer looks like, and an empty room is a real state a host must be able to commit to honestly.\n\nThe leaf covers the whole record rather than its body, and that is deliberate: a host that could flip `status` from active to retracted, move `pinned`, or rewrite `author` on an `attributed` room would rewrite what the room means without touching a byte of ciphertext. The **plaintext is never involved** — on the sealed tiers the host holds ciphertext and commits to exactly what it stores.\n\nThe commitment is over the **whole room**, never over the page being returned. A page-scoped root is one a host satisfies by construction and could never fail.\n\nProving that a *particular* record sits under this root is a separate question, answered by `RecordTrace` on a single-record read. A commitment catches a host that equivocates; a trace binds one record to what the host committed to. Neither is the other, and a reader wanting completeness needs both plus a root it did not get from the host it is checking.",
/// "$ref": "#/definitions/DigestMultibase"
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[serde(transparent)]
pub struct DataCommitment(pub DigestMultibase);
impl ::std::ops::Deref for DataCommitment {
type Target = DigestMultibase;
fn deref(&self) -> &DigestMultibase {
&self.0
}
}
impl ::std::convert::From<DataCommitment> for DigestMultibase {
fn from(value: DataCommitment) -> Self {
value.0
}
}
impl ::std::convert::From<DigestMultibase> for DataCommitment {
fn from(value: DigestMultibase) -> Self {
Self(value)
}
}
impl ::std::str::FromStr for DataCommitment {
type Err = <DigestMultibase 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 DataCommitment {
type Error = <DigestMultibase as ::std::str::FromStr>::Err;
fn try_from(value: &str) -> ::std::result::Result<Self, Self::Error> {
value.parse()
}
}
impl ::std::convert::TryFrom<String> for DataCommitment {
type Error = <DigestMultibase as ::std::str::FromStr>::Err;
fn try_from(value: String) -> ::std::result::Result<Self, Self::Error> {
value.parse()
}
}
impl ::std::fmt::Display for DataCommitment {
fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> ::std::fmt::Result {
self.0.fmt(f)
}
}
/**
A cryptographic digest as a multibase-encoded multihash — the encoding the W3C Verifiable Credentials Data Model 2.0 defines for `digestMultibase`, and the one `did:webvh` uses for its SCID and entry hashes.
Multihash carries the hash algorithm in-band, so the value is self-describing and the wire format survives an algorithm change without a schema revision; multibase does the same for the base encoding, so a verifier never infers base58 from base64url by context. A bare hex string or a `sha-256:`-style prefix hard-codes one algorithm into the wire contract and is non-conforming here.
This definition constrains the *encoding only*. What the digest is computed over is stated by each referencing field, because it differs legitimately: a digest over a JSON document is taken over its RFC 8785 (JCS) canonicalization, while a digest over an opaque artifact is taken over its bytes. A field whose input is a JSON document and which does not name a canonicalization is not reproducible.
Restricted to the two multibase headers W3C Controlled Identifiers 1.0 §2.4 normatively requires — `z` (base58btc) and `u` (base64url-no-pad). CID permits others but states that "interoperability is not guaranteed between implementations using such values", and a registry whose purpose is interoperability should not mint digests a conforming verifier may be unable to read. The alphabets are enforced rather than assumed: base58btc excludes 0, O, I and l, and an earlier permissive pattern let three published examples carry digests that were not valid base58 at all. base58btc is RECOMMENDED, for consistency with `did:key` and `did:webvh`.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "title": "DigestMultibase",
/// "description": "\nA cryptographic digest as a multibase-encoded multihash — the encoding the W3C Verifiable Credentials Data Model 2.0 defines for `digestMultibase`, and the one `did:webvh` uses for its SCID and entry hashes.\n\nMultihash carries the hash algorithm in-band, so the value is self-describing and the wire format survives an algorithm change without a schema revision; multibase does the same for the base encoding, so a verifier never infers base58 from base64url by context. A bare hex string or a `sha-256:`-style prefix hard-codes one algorithm into the wire contract and is non-conforming here.\n\nThis definition constrains the *encoding only*. What the digest is computed over is stated by each referencing field, because it differs legitimately: a digest over a JSON document is taken over its RFC 8785 (JCS) canonicalization, while a digest over an opaque artifact is taken over its bytes. A field whose input is a JSON document and which does not name a canonicalization is not reproducible.\n\nRestricted to the two multibase headers W3C Controlled Identifiers 1.0 §2.4 normatively requires — `z` (base58btc) and `u` (base64url-no-pad). CID permits others but states that \"interoperability is not guaranteed between implementations using such values\", and a registry whose purpose is interoperability should not mint digests a conforming verifier may be unable to read. The alphabets are enforced rather than assumed: base58btc excludes 0, O, I and l, and an earlier permissive pattern let three published examples carry digests that were not valid base58 at all. base58btc is RECOMMENDED, for consistency with `did:key` and `did:webvh`.",
/// "examples": [
/// "zQmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR"
/// ],
/// "type": "string",
/// "minLength": 16,
/// "pattern": "^(z[1-9A-HJ-NP-Za-km-z]+|u[A-Za-z0-9_-]+)$"
///}
/// ```
/// </details>
#[derive(::serde::Serialize, Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
#[serde(transparent)]
pub struct DigestMultibase(::std::string::String);
impl ::std::ops::Deref for DigestMultibase {
type Target = ::std::string::String;
fn deref(&self) -> &::std::string::String {
&self.0
}
}
impl ::std::convert::From<DigestMultibase> for ::std::string::String {
fn from(value: DigestMultibase) -> Self {
value.0
}
}
impl ::std::str::FromStr for DigestMultibase {
type Err = self::error::ConversionError;
fn from_str(value: &str) -> ::std::result::Result<Self, self::error::ConversionError> {
if value.chars().count() < 16usize {
return Err("shorter than 16 characters".into());
}
static PATTERN: ::std::sync::LazyLock<::regress::Regex> =
::std::sync::LazyLock::new(|| {
::regress::Regex::new("^(z[1-9A-HJ-NP-Za-km-z]+|u[A-Za-z0-9_-]+)$").unwrap()
});
if PATTERN.find(value).is_none() {
return Err(
"doesn't match pattern \"^(z[1-9A-HJ-NP-Za-km-z]+|u[A-Za-z0-9_-]+)$\"".into(),
);
}
Ok(Self(value.to_string()))
}
}
impl ::std::convert::TryFrom<&str> for DigestMultibase {
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 DigestMultibase {
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 DigestMultibase {
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 DigestMultibase {
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())
})
}
}
///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.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "title": "Ext",
/// "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.",
/// "type": "object",
/// "minProperties": 1,
/// "additionalProperties": true,
/// "propertyNames": {
/// "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$"
/// }
///}
/// ```
/// </details>
#[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`
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "type": "string",
/// "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$"
///}
/// ```
/// </details>
#[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())
})
}
}
/**
The highest version among the records `DataCommitment` covers. `0` for a room that holds none.
**Derived from the same set as the root, and not read from the room's own counter.** The two agree for any host that has never erased a record — versions are assigned strictly increasing and a retraction keeps its tombstone — but they are not interchangeable, because a root and a counter are *two reads*, and two reads are not a snapshot. A write landing between them yields a pair that is individually correct and jointly false: two members holding roots taken over different trees, labelled with one version. That reads as equivocation and is not, and a **false accusation discredits the mechanism rather than the host** — the worst outcome available here. Taken from the committed set, the version cannot disagree with the root it labels, whatever else is happening to the room.
The corollary is worth stating: a host that **erases** a record — as distinct from retracting it, which leaves a tombstone in the tree — moves the root without necessarily moving this value, and two members straddling that erasure would see one version over two roots. Erasure is a retention act with its own answer, and a family that exposes one owes this definition another look.
**This is what makes two roots comparable at all**, and without it the comparison this family is built on cannot be performed. A room moves: every put, curate and retraction assigns a new version, so two roots taken at two moments differ legitimately and a reader learns nothing from the difference. Shown two different roots, a host that equivocated and a host that was merely written to are indistinguishable — the first can always answer *the room moved between your reads*, and nothing contradicts it.
A version is assigned by exactly the mutations that change the tree — every put, curate and retraction takes the next one — so the highest of them names the **state** the root describes. Two roots carrying the same `headVersion` and differing is a host caught: there is no write to attribute the difference to. Two roots carrying different ones are simply two moments, and a reader should draw nothing from them.
A host can lie about this number too, and it is then lying about the counter it also uses for optimistic concurrency (`expectedVersion`) and for incremental sync (`sinceVersion`) — so a member holding a signed acknowledgement of a write at version `V` contradicts any head below `V` directly.
**Not a timestamp.** A time is host-asserted, unverifiable and useless for this: two roots a second apart are not evidence of anything, while two roots at one version are.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "title": "HeadVersion",
/// "description": "\nThe highest version among the records `DataCommitment` covers. `0` for a room that holds none.\n\n**Derived from the same set as the root, and not read from the room's own counter.** The two agree for any host that has never erased a record — versions are assigned strictly increasing and a retraction keeps its tombstone — but they are not interchangeable, because a root and a counter are *two reads*, and two reads are not a snapshot. A write landing between them yields a pair that is individually correct and jointly false: two members holding roots taken over different trees, labelled with one version. That reads as equivocation and is not, and a **false accusation discredits the mechanism rather than the host** — the worst outcome available here. Taken from the committed set, the version cannot disagree with the root it labels, whatever else is happening to the room.\n\nThe corollary is worth stating: a host that **erases** a record — as distinct from retracting it, which leaves a tombstone in the tree — moves the root without necessarily moving this value, and two members straddling that erasure would see one version over two roots. Erasure is a retention act with its own answer, and a family that exposes one owes this definition another look.\n\n**This is what makes two roots comparable at all**, and without it the comparison this family is built on cannot be performed. A room moves: every put, curate and retraction assigns a new version, so two roots taken at two moments differ legitimately and a reader learns nothing from the difference. Shown two different roots, a host that equivocated and a host that was merely written to are indistinguishable — the first can always answer *the room moved between your reads*, and nothing contradicts it.\n\nA version is assigned by exactly the mutations that change the tree — every put, curate and retraction takes the next one — so the highest of them names the **state** the root describes. Two roots carrying the same `headVersion` and differing is a host caught: there is no write to attribute the difference to. Two roots carrying different ones are simply two moments, and a reader should draw nothing from them.\n\nA host can lie about this number too, and it is then lying about the counter it also uses for optimistic concurrency (`expectedVersion`) and for incremental sync (`sinceVersion`) — so a member holding a signed acknowledgement of a write at version `V` contradicts any head below `V` directly.\n\n**Not a timestamp.** A time is host-asserted, unverifiable and useless for this: two roots a second apart are not evidence of anything, while two roots at one version are.",
/// "type": "integer",
/// "minimum": 0.0
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[serde(transparent)]
pub struct HeadVersion(pub u64);
impl ::std::ops::Deref for HeadVersion {
type Target = u64;
fn deref(&self) -> &u64 {
&self.0
}
}
impl ::std::convert::From<HeadVersion> for u64 {
fn from(value: HeadVersion) -> Self {
value.0
}
}
impl ::std::convert::From<u64> for HeadVersion {
fn from(value: u64) -> Self {
Self(value)
}
}
impl ::std::str::FromStr for HeadVersion {
type Err = <u64 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 HeadVersion {
type Error = <u64 as ::std::str::FromStr>::Err;
fn try_from(value: &str) -> ::std::result::Result<Self, Self::Error> {
value.parse()
}
}
impl ::std::convert::TryFrom<String> for HeadVersion {
type Error = <u64 as ::std::str::FromStr>::Err;
fn try_from(value: String) -> ::std::result::Result<Self, Self::Error> {
value.parse()
}
}
impl ::std::fmt::Display for HeadVersion {
fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> ::std::fmt::Result {
self.0.fmt(f)
}
}
///`Payload`
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "$id": "https://trusttasks.org/spec/rooms/records/get/0.1",
/// "title": "Payload",
/// "type": "object",
/// "required": [
/// "key",
/// "presentation",
/// "roomId"
/// ],
/// "properties": {
/// "ext": {
/// "description": "Ecosystem-defined extension members per SPEC.md §4.5.1.",
/// "$ref": "#/definitions/Ext"
/// },
/// "key": {
/// "description": "The record to read.",
/// "type": "string",
/// "maxLength": 512
/// },
/// "presentation": {
/// "description": "Must confer the `read` action at this room's scope. A read presents exactly as a write does, and on a `private` room requires no host session at all — authorizing reads by session would hand the host a member identifier on every access, and a week of access logs would reconstruct the membership the tier exists to withhold.",
/// "$ref": "#/definitions/AuthorityPresentation"
/// },
/// "roomId": {
/// "description": "The room's identifier.",
/// "type": "string"
/// }
/// },
/// "additionalProperties": false
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
pub struct Payload {
///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 record to read.
pub key: PayloadKey,
///Must confer the `read` action at this room's scope. A read presents exactly as a write does, and on a `private` room requires no host session at all — authorizing reads by session would hand the host a member identifier on every access, and a week of access logs would reconstruct the membership the tier exists to withhold.
pub presentation: AuthorityPresentation,
///The room's identifier.
#[serde(rename = "roomId")]
pub room_id: ::std::string::String,
}
impl Payload {
pub fn builder() -> builder::Payload {
Default::default()
}
}
///The record to read.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "The record to read.",
/// "type": "string",
/// "maxLength": 512
///}
/// ```
/// </details>
#[derive(::serde::Serialize, Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
#[serde(transparent)]
pub struct PayloadKey(::std::string::String);
impl ::std::ops::Deref for PayloadKey {
type Target = ::std::string::String;
fn deref(&self) -> &::std::string::String {
&self.0
}
}
impl ::std::convert::From<PayloadKey> for ::std::string::String {
fn from(value: PayloadKey) -> Self {
value.0
}
}
impl ::std::str::FromStr for PayloadKey {
type Err = self::error::ConversionError;
fn from_str(value: &str) -> ::std::result::Result<Self, self::error::ConversionError> {
if value.chars().count() > 512usize {
return Err("longer than 512 characters".into());
}
Ok(Self(value.to_string()))
}
}
impl ::std::convert::TryFrom<&str> for PayloadKey {
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 PayloadKey {
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 PayloadKey {
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 PayloadKey {
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())
})
}
}
/**
How many records the room held when `DataCommitment` was computed — the number of leaves in that tree, tombstones included, since a tombstone is a record.
**Why a root needs this.** Certificate Transparency's signed tree head is a root *and a tree size*; this family shipped the root alone, and the half that was dropped is the half that makes a listing checkable. A reader holding a **complete, unfiltered** listing cannot recompute the root — a leaf commits to a whole record and a listing returns a projection without the body — but it can count. A host that omits a record from a listing while committing to a tree that holds it now contradicts itself in the same response, with no second party and no anchor involved.
A host can of course understate both together. That is the point rather than a hole: the omission stops being silence and becomes a **specific claim about how many records the room holds**, which any other member's view, or any writer's signed put acknowledgement, contradicts. Making an omission attributable is the whole of what this machinery buys; it never claimed to make one impossible.
**It counts the room, never the page.** The same rule `DataCommitment` states, and the same trap: a count scoped to what was returned is one a host satisfies by construction. So this is only comparable against a listing read to the end with **no** `prefix` and **no** `sinceVersion` — a filtered listing legitimately holds fewer, and a reader that compares one against this has found a discrepancy it created itself.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "title": "RecordCount",
/// "description": "\nHow many records the room held when `DataCommitment` was computed — the number of leaves in that tree, tombstones included, since a tombstone is a record.\n\n**Why a root needs this.** Certificate Transparency's signed tree head is a root *and a tree size*; this family shipped the root alone, and the half that was dropped is the half that makes a listing checkable. A reader holding a **complete, unfiltered** listing cannot recompute the root — a leaf commits to a whole record and a listing returns a projection without the body — but it can count. A host that omits a record from a listing while committing to a tree that holds it now contradicts itself in the same response, with no second party and no anchor involved.\n\nA host can of course understate both together. That is the point rather than a hole: the omission stops being silence and becomes a **specific claim about how many records the room holds**, which any other member's view, or any writer's signed put acknowledgement, contradicts. Making an omission attributable is the whole of what this machinery buys; it never claimed to make one impossible.\n\n**It counts the room, never the page.** The same rule `DataCommitment` states, and the same trap: a count scoped to what was returned is one a host satisfies by construction. So this is only comparable against a listing read to the end with **no** `prefix` and **no** `sinceVersion` — a filtered listing legitimately holds fewer, and a reader that compares one against this has found a discrepancy it created itself.",
/// "type": "integer",
/// "minimum": 0.0
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[serde(transparent)]
pub struct RecordCount(pub u64);
impl ::std::ops::Deref for RecordCount {
type Target = u64;
fn deref(&self) -> &u64 {
&self.0
}
}
impl ::std::convert::From<RecordCount> for u64 {
fn from(value: RecordCount) -> Self {
value.0
}
}
impl ::std::convert::From<u64> for RecordCount {
fn from(value: u64) -> Self {
Self(value)
}
}
impl ::std::str::FromStr for RecordCount {
type Err = <u64 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 RecordCount {
type Error = <u64 as ::std::str::FromStr>::Err;
fn try_from(value: &str) -> ::std::result::Result<Self, Self::Error> {
value.parse()
}
}
impl ::std::convert::TryFrom<String> for RecordCount {
type Error = <u64 as ::std::str::FromStr>::Err;
fn try_from(value: String) -> ::std::result::Result<Self, Self::Error> {
value.parse()
}
}
impl ::std::fmt::Display for RecordCount {
fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> ::std::fmt::Result {
self.0.fmt(f)
}
}
/**
The path from one record's leaf to the room's `DataCommitment` — a Merkle inclusion proof, in the vocabulary this work already uses for it.
**It is not called `proof`** because in this framework that word is taken: `proof` is the document's data-integrity proof (SPEC §7.3), and a payload member of the same name in the same document invites reading one for the other. The two are not interchangeable and the confusion would be silent.
**To verify**, given the `CommittedRecord` reassembled from the same response:
1. `h = SHA-256(0x00 || JCS(record))` — the leaf, by `DataCommitment` step 2.
2. For each step in order: `h = SHA-256(0x01 || sibling || h)` when `siblingIsLeft` is true, and `SHA-256(0x01 || h || sibling)` when it is false.
3. `h` **MUST** equal the `dataCommitment` **carried in the same response**. Not one from an earlier read, and not one from a listing: a room moves, and a trace is only ever a statement about the tree it was cut from. A host **MUST** compute the trace and the commitment from the same snapshot.
An **empty array is valid** and is not the same as an absent member. It says the room holds exactly one record, whose leaf is the root; absence of `trace` says the host offered no trace at all.
A trace is **not** always `ceil(log2 n)` steps. A level that promotes an odd node unchanged (`DataCommitment` step 4) contributes no step for that node, so a reader must follow the steps it was given rather than count them against a tree size it assumed.
`maxItems` bounds a tree of 2⁶⁴ records. Verification cost is the reader's and the array is the host's, so the ceiling is stated rather than left to whoever writes the loop.
**What a trace does not prove.** It binds a record to a root. It says nothing about whether that root is the room's — only comparing the root against one the host did not choose does that, exactly as `DataCommitment` describes. A reader that verifies a trace against a root received in the same breath has checked the host's arithmetic and nothing else. The two mechanisms answer different questions and neither substitutes for the other.*/
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "title": "RecordTrace",
/// "description": "\nThe path from one record's leaf to the room's `DataCommitment` — a Merkle inclusion proof, in the vocabulary this work already uses for it.\n\n**It is not called `proof`** because in this framework that word is taken: `proof` is the document's data-integrity proof (SPEC §7.3), and a payload member of the same name in the same document invites reading one for the other. The two are not interchangeable and the confusion would be silent.\n\n**To verify**, given the `CommittedRecord` reassembled from the same response:\n 1. `h = SHA-256(0x00 || JCS(record))` — the leaf, by `DataCommitment` step 2.\n 2. For each step in order: `h = SHA-256(0x01 || sibling || h)` when `siblingIsLeft` is true, and `SHA-256(0x01 || h || sibling)` when it is false.\n 3. `h` **MUST** equal the `dataCommitment` **carried in the same response**. Not one from an earlier read, and not one from a listing: a room moves, and a trace is only ever a statement about the tree it was cut from. A host **MUST** compute the trace and the commitment from the same snapshot.\n\nAn **empty array is valid** and is not the same as an absent member. It says the room holds exactly one record, whose leaf is the root; absence of `trace` says the host offered no trace at all.\n\nA trace is **not** always `ceil(log2 n)` steps. A level that promotes an odd node unchanged (`DataCommitment` step 4) contributes no step for that node, so a reader must follow the steps it was given rather than count them against a tree size it assumed.\n\n`maxItems` bounds a tree of 2⁶⁴ records. Verification cost is the reader's and the array is the host's, so the ceiling is stated rather than left to whoever writes the loop.\n\n**What a trace does not prove.** It binds a record to a root. It says nothing about whether that root is the room's — only comparing the root against one the host did not choose does that, exactly as `DataCommitment` describes. A reader that verifies a trace against a root received in the same breath has checked the host's arithmetic and nothing else. The two mechanisms answer different questions and neither substitutes for the other.",
/// "type": "array",
/// "items": {
/// "type": "object",
/// "required": [
/// "sibling",
/// "siblingIsLeft"
/// ],
/// "properties": {
/// "sibling": {
/// "description": "The sibling node's hash — a leaf hash or an internal node hash of this room's record tree, encoded exactly as `DataCommitment` is. A digest over **bytes**, produced by one of the two prefixed constructions in `DataCommitment`, not over a JSON document.",
/// "$ref": "#/definitions/DigestMultibase"
/// },
/// "siblingIsLeft": {
/// "description": "Whether the sibling is the **left** child of the parent; the node being proved is the other one. Concatenation order is the whole of what a Merkle proof asserts, so this bit is load-bearing — inverting it on a single step yields a different root, and a reader that infers it from the record's position has assumed a tree shape the host never stated.",
/// "type": "boolean"
/// }
/// },
/// "additionalProperties": false
/// },
/// "maxItems": 64
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[serde(transparent)]
pub struct RecordTrace(pub ::std::vec::Vec<RecordTraceItem>);
impl ::std::ops::Deref for RecordTrace {
type Target = ::std::vec::Vec<RecordTraceItem>;
fn deref(&self) -> &::std::vec::Vec<RecordTraceItem> {
&self.0
}
}
impl ::std::convert::From<RecordTrace> for ::std::vec::Vec<RecordTraceItem> {
fn from(value: RecordTrace) -> Self {
value.0
}
}
impl ::std::convert::From<::std::vec::Vec<RecordTraceItem>> for RecordTrace {
fn from(value: ::std::vec::Vec<RecordTraceItem>) -> Self {
Self(value)
}
}
///`RecordTraceItem`
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "type": "object",
/// "required": [
/// "sibling",
/// "siblingIsLeft"
/// ],
/// "properties": {
/// "sibling": {
/// "description": "The sibling node's hash — a leaf hash or an internal node hash of this room's record tree, encoded exactly as `DataCommitment` is. A digest over **bytes**, produced by one of the two prefixed constructions in `DataCommitment`, not over a JSON document.",
/// "$ref": "#/definitions/DigestMultibase"
/// },
/// "siblingIsLeft": {
/// "description": "Whether the sibling is the **left** child of the parent; the node being proved is the other one. Concatenation order is the whole of what a Merkle proof asserts, so this bit is load-bearing — inverting it on a single step yields a different root, and a reader that infers it from the record's position has assumed a tree shape the host never stated.",
/// "type": "boolean"
/// }
/// },
/// "additionalProperties": false
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
pub struct RecordTraceItem {
///The sibling node's hash — a leaf hash or an internal node hash of this room's record tree, encoded exactly as `DataCommitment` is. A digest over **bytes**, produced by one of the two prefixed constructions in `DataCommitment`, not over a JSON document.
pub sibling: DigestMultibase,
///Whether the sibling is the **left** child of the parent; the node being proved is the other one. Concatenation order is the whole of what a Merkle proof asserts, so this bit is load-bearing — inverting it on a single step yields a different root, and a reader that infers it from the record's position has assumed a tree shape the host never stated.
#[serde(rename = "siblingIsLeft")]
pub sibling_is_left: bool,
}
impl RecordTraceItem {
pub fn builder() -> builder::RecordTraceItem {
Default::default()
}
}
///Success response to rooms/records/get. Type https://trusttasks.org/spec/rooms/records/get/0.1#response.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "title": "Response",
/// "description": "Success response to rooms/records/get. Type https://trusttasks.org/spec/rooms/records/get/0.1#response.",
/// "type": "object",
/// "required": [
/// "key",
/// "version"
/// ],
/// "properties": {
/// "author": {
/// "description": "\nThe member who wrote it. Present on `open` and `attributed`, absent on `private` where the author is sealed with the body. Committed. Mirrors `CommittedRecord`, which fixes the leaf preimage; see the note on `trace`.\n\nThis member is new to this response and is a **disclosure**: `rooms/records/list` already returns it on those tiers, so it tells a reader nothing the family withheld, but a host serving a single record now names its writer where before it did not. It is not conditional on `trace` — a reader wanting the record without the writer's identifier is asking for a different room tier, not a different response.",
/// "type": "string"
/// },
/// "cleartext": {
/// "description": "Present on an `open` room.",
/// "type": "object",
/// "additionalProperties": true
/// },
/// "dataCommitment": {
/// "description": "The room's data commitment at the moment this record was read. Carried on a single-record read as well as a listing so a reader can tell whether the room moved between two reads — and so a `trace` returned beside it has a root to reach.",
/// "$ref": "#/definitions/DataCommitment"
/// },
/// "ext": {
/// "$ref": "#/definitions/Ext"
/// },
/// "headVersion": {
/// "description": "The room's highest assigned record version, as of `dataCommitment`. Present only beside `dataCommitment`, and computed from the same snapshot: it describes the state that root was taken over, and a head that does not belong to that root is worse than none. Without it two roots are not comparable at all: a host shown to have served two different ones answers that the room moved, and nothing contradicts it.",
/// "$ref": "#/definitions/HeadVersion"
/// },
/// "key": {
/// "type": "string"
/// },
/// "pinned": {
/// "description": "Present **only** when the record is pinned; absent means it is not. Committed. Mirrors `CommittedRecord`, which fixes the leaf preimage; see the note on `trace`. `false` is not a permitted spelling: absent is how false is written in the preimage, and two spellings would give one record two roots.",
/// "type": "boolean",
/// "const": true
/// },
/// "recordCount": {
/// "description": "How many records the room holds, as of `dataCommitment`. Present only beside `dataCommitment`, and computed from the same snapshot: it describes the state that root was taken over, and a head that does not belong to that root is worse than none.",
/// "$ref": "#/definitions/RecordCount"
/// },
/// "sealed": {
/// "description": "Present on an `attributed` or `private` room.",
/// "$ref": "#/definitions/SealedRecord"
/// },
/// "status": {
/// "description": "Curation state. Committed. Mirrors `CommittedRecord`, which fixes the leaf preimage; see the note on `trace`. A host that serves a `trace` MUST serve this, because a reader cannot reach the leaf without it — and a host that could omit it could retract a record without touching a byte of it.",
/// "type": "string",
/// "enum": [
/// "active",
/// "deprecated",
/// "retracted"
/// ]
/// },
/// "trace": {
/// "description": "\nThe path from this record's leaf to `dataCommitment`, proving the record sits under the root the host just asserted.\n\n**The leaf preimage is this response payload with its verification members — `dataCommitment`, `recordCount`, `headVersion` and `trace` — and `ext` removed** — which is exactly `CommittedRecord`, and a reader MAY validate the object it assembles against that definition before hashing it. Nothing is reconstructed and no member is carried twice; the reader deletes three members from what it already holds.\n\nOPTIONAL, on the same reasoning as `dataCommitment`: a host that maintains no tree must not invent one. A host that serves this MUST have computed it and `dataCommitment` from the same snapshot, and MUST serve every committed member it holds — an omitted `status`, `updatedAt`, `pinned` or `author` yields a leaf the reader cannot reach, so the failure is a refused trace rather than a false one.",
/// "$ref": "#/definitions/RecordTrace"
/// },
/// "updatedAt": {
/// "description": "RFC 3339. Committed. Mirrors `CommittedRecord`, which fixes the leaf preimage; see the note on `trace`. Required alongside a `trace` for the same reason `status` is.",
/// "type": "string",
/// "format": "date-time"
/// },
/// "version": {
/// "type": "integer",
/// "minimum": 1.0
/// }
/// },
/// "additionalProperties": false,
/// "$anchor": "response",
/// "dependentRequired": {
/// "headVersion": [
/// "dataCommitment"
/// ],
/// "recordCount": [
/// "dataCommitment"
/// ],
/// "trace": [
/// "dataCommitment",
/// "status",
/// "updatedAt"
/// ]
/// }
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
pub struct Response {
/**
The member who wrote it. Present on `open` and `attributed`, absent on `private` where the author is sealed with the body. Committed. Mirrors `CommittedRecord`, which fixes the leaf preimage; see the note on `trace`.
This member is new to this response and is a **disclosure**: `rooms/records/list` already returns it on those tiers, so it tells a reader nothing the family withheld, but a host serving a single record now names its writer where before it did not. It is not conditional on `trace` — a reader wanting the record without the writer's identifier is asking for a different room tier, not a different response.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub author: ::std::option::Option<::std::string::String>,
///Present on an `open` room.
#[serde(default, skip_serializing_if = "::serde_json::Map::is_empty")]
pub cleartext: ::serde_json::Map<::std::string::String, ::serde_json::Value>,
///The room's data commitment at the moment this record was read. Carried on a single-record read as well as a listing so a reader can tell whether the room moved between two reads — and so a `trace` returned beside it has a root to reach.
#[serde(
rename = "dataCommitment",
default,
skip_serializing_if = "::std::option::Option::is_none"
)]
pub data_commitment: ::std::option::Option<DataCommitment>,
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub ext: ::std::option::Option<Ext>,
///The room's highest assigned record version, as of `dataCommitment`. Present only beside `dataCommitment`, and computed from the same snapshot: it describes the state that root was taken over, and a head that does not belong to that root is worse than none. Without it two roots are not comparable at all: a host shown to have served two different ones answers that the room moved, and nothing contradicts it.
#[serde(
rename = "headVersion",
default,
skip_serializing_if = "::std::option::Option::is_none"
)]
pub head_version: ::std::option::Option<HeadVersion>,
pub key: ::std::string::String,
///Present **only** when the record is pinned; absent means it is not. Committed. Mirrors `CommittedRecord`, which fixes the leaf preimage; see the note on `trace`. `false` is not a permitted spelling: absent is how false is written in the preimage, and two spellings would give one record two roots.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub pinned: ::std::option::Option<bool>,
///How many records the room holds, as of `dataCommitment`. Present only beside `dataCommitment`, and computed from the same snapshot: it describes the state that root was taken over, and a head that does not belong to that root is worse than none.
#[serde(
rename = "recordCount",
default,
skip_serializing_if = "::std::option::Option::is_none"
)]
pub record_count: ::std::option::Option<RecordCount>,
///Present on an `attributed` or `private` room.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub sealed: ::std::option::Option<SealedRecord>,
///Curation state. Committed. Mirrors `CommittedRecord`, which fixes the leaf preimage; see the note on `trace`. A host that serves a `trace` MUST serve this, because a reader cannot reach the leaf without it — and a host that could omit it could retract a record without touching a byte of it.
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub status: ::std::option::Option<ResponseStatus>,
/**
The path from this record's leaf to `dataCommitment`, proving the record sits under the root the host just asserted.
**The leaf preimage is this response payload with its verification members — `dataCommitment`, `recordCount`, `headVersion` and `trace` — and `ext` removed** — which is exactly `CommittedRecord`, and a reader MAY validate the object it assembles against that definition before hashing it. Nothing is reconstructed and no member is carried twice; the reader deletes three members from what it already holds.
OPTIONAL, on the same reasoning as `dataCommitment`: a host that maintains no tree must not invent one. A host that serves this MUST have computed it and `dataCommitment` from the same snapshot, and MUST serve every committed member it holds — an omitted `status`, `updatedAt`, `pinned` or `author` yields a leaf the reader cannot reach, so the failure is a refused trace rather than a false one.*/
#[serde(default, skip_serializing_if = "::std::option::Option::is_none")]
pub trace: ::std::option::Option<RecordTrace>,
///RFC 3339. Committed. Mirrors `CommittedRecord`, which fixes the leaf preimage; see the note on `trace`. Required alongside a `trace` for the same reason `status` is.
#[serde(
rename = "updatedAt",
default,
skip_serializing_if = "::std::option::Option::is_none"
)]
pub updated_at: ::std::option::Option<::chrono::DateTime<::chrono::offset::Utc>>,
pub version: ::std::num::NonZeroU64,
}
impl Response {
pub fn builder() -> builder::Response {
Default::default()
}
}
///Curation state. Committed. Mirrors `CommittedRecord`, which fixes the leaf preimage; see the note on `trace`. A host that serves a `trace` MUST serve this, because a reader cannot reach the leaf without it — and a host that could omit it could retract a record without touching a byte of it.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "description": "Curation state. Committed. Mirrors `CommittedRecord`, which fixes the leaf preimage; see the note on `trace`. A host that serves a `trace` MUST serve this, because a reader cannot reach the leaf without it — and a host that could omit it could retract a record without touching a byte of it.",
/// "type": "string",
/// "enum": [
/// "active",
/// "deprecated",
/// "retracted"
/// ]
///}
/// ```
/// </details>
#[derive(
::serde::Deserialize,
::serde::Serialize,
Clone,
Copy,
Debug,
Eq,
Hash,
Ord,
PartialEq,
PartialOrd,
)]
#[non_exhaustive]
pub enum ResponseStatus {
#[serde(rename = "active")]
Active,
#[serde(rename = "deprecated")]
Deprecated,
#[serde(rename = "retracted")]
Retracted,
}
impl ::std::fmt::Display for ResponseStatus {
fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> ::std::fmt::Result {
match *self {
Self::Active => f.write_str("active"),
Self::Deprecated => f.write_str("deprecated"),
Self::Retracted => f.write_str("retracted"),
}
}
}
impl ::std::str::FromStr for ResponseStatus {
type Err = self::error::ConversionError;
fn from_str(value: &str) -> ::std::result::Result<Self, self::error::ConversionError> {
match value {
"active" => Ok(Self::Active),
"deprecated" => Ok(Self::Deprecated),
"retracted" => Ok(Self::Retracted),
_ => Err("invalid value".into()),
}
}
}
impl ::std::convert::TryFrom<&str> for ResponseStatus {
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 ResponseStatus {
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 ResponseStatus {
type Error = self::error::ConversionError;
fn try_from(
value: ::std::string::String,
) -> ::std::result::Result<Self, self::error::ConversionError> {
value.parse()
}
}
///A record as a host stores it on an `attributed` or `private` room. Title, description, body, author and tags are sealed together in one blob rather than separately: splitting them would let a host learn the shape of the material from ciphertext lengths, for no benefit, since a reader decrypts the whole record either way.
///
/// <details><summary>JSON schema</summary>
///
/// ```json
///{
/// "title": "SealedRecord",
/// "description": "A record as a host stores it on an `attributed` or `private` room. Title, description, body, author and tags are sealed together in one blob rather than separately: splitting them would let a host learn the shape of the material from ciphertext lengths, for no benefit, since a reader decrypts the whole record either way.",
/// "type": "object",
/// "required": [
/// "ciphertext",
/// "epoch",
/// "nonce"
/// ],
/// "properties": {
/// "ciphertext": {
/// "description": "The sealed record, base64url. Bound by AEAD associated data to `roomId`, `key`, `version` and `epoch`, so a host that relocates it to another key, version, epoch or room produces a mismatch and the open fails. The record cannot be moved undetected even though the host holds every byte of it.",
/// "type": "string"
/// },
/// "epoch": {
/// "description": "The key epoch this record was sealed under. Cleartext because the host must serve the right ciphertext, and bound into the associated data so that relabelling it fails authentication rather than causing a reader to try the wrong key.",
/// "type": "integer",
/// "minimum": 1.0
/// },
/// "nonce": {
/// "description": "AEAD nonce, base64url.",
/// "type": "string"
/// }
/// },
/// "additionalProperties": false
///}
/// ```
/// </details>
#[derive(::serde::Deserialize, ::serde::Serialize, Clone, Debug)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
pub struct SealedRecord {
///The sealed record, base64url. Bound by AEAD associated data to `roomId`, `key`, `version` and `epoch`, so a host that relocates it to another key, version, epoch or room produces a mismatch and the open fails. The record cannot be moved undetected even though the host holds every byte of it.
pub ciphertext: ::std::string::String,
///The key epoch this record was sealed under. Cleartext because the host must serve the right ciphertext, and bound into the associated data so that relabelling it fails authentication rather than causing a reader to try the wrong key.
pub epoch: ::std::num::NonZeroU64,
///AEAD nonce, base64url.
pub nonce: ::std::string::String,
}
impl SealedRecord {
pub fn builder() -> builder::SealedRecord {
Default::default()
}
}
/// Types for composing complex structures.
pub mod builder {
#[derive(Clone, Debug)]
pub struct AuthorityPresentation {
authority:
::std::result::Result<::std::vec::Vec<::std::string::String>, ::std::string::String>,
membership: ::std::result::Result<::std::string::String, ::std::string::String>,
subject_binding: ::std::result::Result<
::std::option::Option<::std::string::String>,
::std::string::String,
>,
}
impl ::std::default::Default for AuthorityPresentation {
fn default() -> Self {
Self {
authority: Err("no value supplied for authority".to_string()),
membership: Err("no value supplied for membership".to_string()),
subject_binding: Ok(Default::default()),
}
}
}
impl AuthorityPresentation {
pub fn authority<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::vec::Vec<::std::string::String>>,
T::Error: ::std::fmt::Display,
{
self.authority = value
.try_into()
.map_err(|e| format!("error converting supplied value for authority: {e}"));
self
}
pub fn membership<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::string::String>,
T::Error: ::std::fmt::Display,
{
self.membership = value
.try_into()
.map_err(|e| format!("error converting supplied value for membership: {e}"));
self
}
pub fn subject_binding<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::option::Option<::std::string::String>>,
T::Error: ::std::fmt::Display,
{
self.subject_binding = value
.try_into()
.map_err(|e| format!("error converting supplied value for subject_binding: {e}"));
self
}
}
impl ::std::convert::TryFrom<AuthorityPresentation> for super::AuthorityPresentation {
type Error = super::error::ConversionError;
fn try_from(
value: AuthorityPresentation,
) -> ::std::result::Result<Self, super::error::ConversionError> {
Ok(Self {
authority: value.authority?,
membership: value.membership?,
subject_binding: value.subject_binding?,
})
}
}
impl ::std::convert::From<super::AuthorityPresentation> for AuthorityPresentation {
fn from(value: super::AuthorityPresentation) -> Self {
Self {
authority: Ok(value.authority),
membership: Ok(value.membership),
subject_binding: Ok(value.subject_binding),
}
}
}
#[derive(Clone, Debug)]
pub struct Payload {
ext: ::std::result::Result<::std::option::Option<super::Ext>, ::std::string::String>,
key: ::std::result::Result<super::PayloadKey, ::std::string::String>,
presentation: ::std::result::Result<super::AuthorityPresentation, ::std::string::String>,
room_id: ::std::result::Result<::std::string::String, ::std::string::String>,
}
impl ::std::default::Default for Payload {
fn default() -> Self {
Self {
ext: Ok(Default::default()),
key: Err("no value supplied for key".to_string()),
presentation: Err("no value supplied for presentation".to_string()),
room_id: Err("no value supplied for room_id".to_string()),
}
}
}
impl Payload {
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 key<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<super::PayloadKey>,
T::Error: ::std::fmt::Display,
{
self.key = value
.try_into()
.map_err(|e| format!("error converting supplied value for key: {e}"));
self
}
pub fn presentation<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<super::AuthorityPresentation>,
T::Error: ::std::fmt::Display,
{
self.presentation = value
.try_into()
.map_err(|e| format!("error converting supplied value for presentation: {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 {
ext: value.ext?,
key: value.key?,
presentation: value.presentation?,
room_id: value.room_id?,
})
}
}
impl ::std::convert::From<super::Payload> for Payload {
fn from(value: super::Payload) -> Self {
Self {
ext: Ok(value.ext),
key: Ok(value.key),
presentation: Ok(value.presentation),
room_id: Ok(value.room_id),
}
}
}
#[derive(Clone, Debug)]
pub struct RecordTraceItem {
sibling: ::std::result::Result<super::DigestMultibase, ::std::string::String>,
sibling_is_left: ::std::result::Result<bool, ::std::string::String>,
}
impl ::std::default::Default for RecordTraceItem {
fn default() -> Self {
Self {
sibling: Err("no value supplied for sibling".to_string()),
sibling_is_left: Err("no value supplied for sibling_is_left".to_string()),
}
}
}
impl RecordTraceItem {
pub fn sibling<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<super::DigestMultibase>,
T::Error: ::std::fmt::Display,
{
self.sibling = value
.try_into()
.map_err(|e| format!("error converting supplied value for sibling: {e}"));
self
}
pub fn sibling_is_left<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<bool>,
T::Error: ::std::fmt::Display,
{
self.sibling_is_left = value
.try_into()
.map_err(|e| format!("error converting supplied value for sibling_is_left: {e}"));
self
}
}
impl ::std::convert::TryFrom<RecordTraceItem> for super::RecordTraceItem {
type Error = super::error::ConversionError;
fn try_from(
value: RecordTraceItem,
) -> ::std::result::Result<Self, super::error::ConversionError> {
Ok(Self {
sibling: value.sibling?,
sibling_is_left: value.sibling_is_left?,
})
}
}
impl ::std::convert::From<super::RecordTraceItem> for RecordTraceItem {
fn from(value: super::RecordTraceItem) -> Self {
Self {
sibling: Ok(value.sibling),
sibling_is_left: Ok(value.sibling_is_left),
}
}
}
#[derive(Clone, Debug)]
pub struct Response {
author: ::std::result::Result<
::std::option::Option<::std::string::String>,
::std::string::String,
>,
cleartext: ::std::result::Result<
::serde_json::Map<::std::string::String, ::serde_json::Value>,
::std::string::String,
>,
data_commitment: ::std::result::Result<
::std::option::Option<super::DataCommitment>,
::std::string::String,
>,
ext: ::std::result::Result<::std::option::Option<super::Ext>, ::std::string::String>,
head_version:
::std::result::Result<::std::option::Option<super::HeadVersion>, ::std::string::String>,
key: ::std::result::Result<::std::string::String, ::std::string::String>,
pinned: ::std::result::Result<::std::option::Option<bool>, ::std::string::String>,
record_count:
::std::result::Result<::std::option::Option<super::RecordCount>, ::std::string::String>,
sealed: ::std::result::Result<
::std::option::Option<super::SealedRecord>,
::std::string::String,
>,
status: ::std::result::Result<
::std::option::Option<super::ResponseStatus>,
::std::string::String,
>,
trace:
::std::result::Result<::std::option::Option<super::RecordTrace>, ::std::string::String>,
updated_at: ::std::result::Result<
::std::option::Option<::chrono::DateTime<::chrono::offset::Utc>>,
::std::string::String,
>,
version: ::std::result::Result<::std::num::NonZeroU64, ::std::string::String>,
}
impl ::std::default::Default for Response {
fn default() -> Self {
Self {
author: Ok(Default::default()),
cleartext: Ok(Default::default()),
data_commitment: Ok(Default::default()),
ext: Ok(Default::default()),
head_version: Ok(Default::default()),
key: Err("no value supplied for key".to_string()),
pinned: Ok(Default::default()),
record_count: Ok(Default::default()),
sealed: Ok(Default::default()),
status: Ok(Default::default()),
trace: Ok(Default::default()),
updated_at: Ok(Default::default()),
version: Err("no value supplied for version".to_string()),
}
}
}
impl Response {
pub fn author<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::option::Option<::std::string::String>>,
T::Error: ::std::fmt::Display,
{
self.author = value
.try_into()
.map_err(|e| format!("error converting supplied value for author: {e}"));
self
}
pub fn cleartext<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<
::serde_json::Map<::std::string::String, ::serde_json::Value>,
>,
T::Error: ::std::fmt::Display,
{
self.cleartext = value
.try_into()
.map_err(|e| format!("error converting supplied value for cleartext: {e}"));
self
}
pub fn data_commitment<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::option::Option<super::DataCommitment>>,
T::Error: ::std::fmt::Display,
{
self.data_commitment = value
.try_into()
.map_err(|e| format!("error converting supplied value for data_commitment: {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 head_version<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::option::Option<super::HeadVersion>>,
T::Error: ::std::fmt::Display,
{
self.head_version = value
.try_into()
.map_err(|e| format!("error converting supplied value for head_version: {e}"));
self
}
pub fn key<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::string::String>,
T::Error: ::std::fmt::Display,
{
self.key = value
.try_into()
.map_err(|e| format!("error converting supplied value for key: {e}"));
self
}
pub fn pinned<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::option::Option<bool>>,
T::Error: ::std::fmt::Display,
{
self.pinned = value
.try_into()
.map_err(|e| format!("error converting supplied value for pinned: {e}"));
self
}
pub fn record_count<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::option::Option<super::RecordCount>>,
T::Error: ::std::fmt::Display,
{
self.record_count = value
.try_into()
.map_err(|e| format!("error converting supplied value for record_count: {e}"));
self
}
pub fn sealed<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::option::Option<super::SealedRecord>>,
T::Error: ::std::fmt::Display,
{
self.sealed = value
.try_into()
.map_err(|e| format!("error converting supplied value for sealed: {e}"));
self
}
pub fn status<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::option::Option<super::ResponseStatus>>,
T::Error: ::std::fmt::Display,
{
self.status = value
.try_into()
.map_err(|e| format!("error converting supplied value for status: {e}"));
self
}
pub fn trace<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::option::Option<super::RecordTrace>>,
T::Error: ::std::fmt::Display,
{
self.trace = value
.try_into()
.map_err(|e| format!("error converting supplied value for trace: {e}"));
self
}
pub fn updated_at<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<
::std::option::Option<::chrono::DateTime<::chrono::offset::Utc>>,
>,
T::Error: ::std::fmt::Display,
{
self.updated_at = value
.try_into()
.map_err(|e| format!("error converting supplied value for updated_at: {e}"));
self
}
pub fn version<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::num::NonZeroU64>,
T::Error: ::std::fmt::Display,
{
self.version = value
.try_into()
.map_err(|e| format!("error converting supplied value for version: {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 {
author: value.author?,
cleartext: value.cleartext?,
data_commitment: value.data_commitment?,
ext: value.ext?,
head_version: value.head_version?,
key: value.key?,
pinned: value.pinned?,
record_count: value.record_count?,
sealed: value.sealed?,
status: value.status?,
trace: value.trace?,
updated_at: value.updated_at?,
version: value.version?,
})
}
}
impl ::std::convert::From<super::Response> for Response {
fn from(value: super::Response) -> Self {
Self {
author: Ok(value.author),
cleartext: Ok(value.cleartext),
data_commitment: Ok(value.data_commitment),
ext: Ok(value.ext),
head_version: Ok(value.head_version),
key: Ok(value.key),
pinned: Ok(value.pinned),
record_count: Ok(value.record_count),
sealed: Ok(value.sealed),
status: Ok(value.status),
trace: Ok(value.trace),
updated_at: Ok(value.updated_at),
version: Ok(value.version),
}
}
}
#[derive(Clone, Debug)]
pub struct SealedRecord {
ciphertext: ::std::result::Result<::std::string::String, ::std::string::String>,
epoch: ::std::result::Result<::std::num::NonZeroU64, ::std::string::String>,
nonce: ::std::result::Result<::std::string::String, ::std::string::String>,
}
impl ::std::default::Default for SealedRecord {
fn default() -> Self {
Self {
ciphertext: Err("no value supplied for ciphertext".to_string()),
epoch: Err("no value supplied for epoch".to_string()),
nonce: Err("no value supplied for nonce".to_string()),
}
}
}
impl SealedRecord {
pub fn ciphertext<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::string::String>,
T::Error: ::std::fmt::Display,
{
self.ciphertext = value
.try_into()
.map_err(|e| format!("error converting supplied value for ciphertext: {e}"));
self
}
pub fn epoch<T>(mut self, value: T) -> Self
where
T: ::std::convert::TryInto<::std::num::NonZeroU64>,
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
}
}
impl ::std::convert::TryFrom<SealedRecord> for super::SealedRecord {
type Error = super::error::ConversionError;
fn try_from(
value: SealedRecord,
) -> ::std::result::Result<Self, super::error::ConversionError> {
Ok(Self {
ciphertext: value.ciphertext?,
epoch: value.epoch?,
nonce: value.nonce?,
})
}
}
impl ::std::convert::From<super::SealedRecord> for SealedRecord {
fn from(value: super::SealedRecord) -> Self {
Self {
ciphertext: Ok(value.ciphertext),
epoch: Ok(value.epoch),
nonce: Ok(value.nonce),
}
}
}
}
impl crate::Payload for Payload {
const TYPE_URI: &'static str = "https://trusttasks.org/spec/rooms/records/get/0.1";
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(
"{\n \"$defs\": {\n \"AuthorityPresentation\": {\n \"additionalProperties\": false,\n \"description\": \"What a party presents to act on a room. Carries the whole authority chain: a host MUST NOT dereference an authority credential's `parent` to fetch a link it was not given. Resolving over the network would make verification depend on availability, turn every identifier into a request the host can be induced to make against an address the holder chooses, and signal credential use to whoever hosts the identifier. A host MUST bind the presenter to the chain's leaf. A chain that verifies is evidence that authority was conferred on somebody; it is not evidence that the party presenting it is that somebody. The leaf's subject MUST equal the party the host authenticated for this request — an identity the transport established or a document `proof` proved, never one named in a payload. A host that omits this check authorizes every captured presentation, and the omission is silent, because the chain still verifies.\",\n \"properties\": {\n \"authority\": {\n \"description\": \"The authority chain, LEAF FIRST: the first element is the credential being relied on and the last MUST be one issued by the room itself. Every link the presenter relies on is present, because the host will not fetch one. Capped at 8: verification is linear in chain length and runs on every operation, so an unbounded chain is a denial-of-service surface against the host. The known uses need 2 to 3 — a person attenuating to an agent, and that agent to a sub-agent.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"maxItems\": 8,\n \"minItems\": 1,\n \"type\": \"array\"\n },\n \"membership\": {\n \"description\": \"The presenter's membership credential for this room, or — on a `private` room — a zero-knowledge presentation of it. Serialized per the governing profile.\",\n \"type\": \"string\"\n },\n \"subjectBinding\": {\n \"description\": \"REQUIRED on a `private` room, where the subject identifier is withheld: a proof that the membership credential and the authority chain's leaf describe the SAME subject. Without it two parties pool credentials — one contributes membership, the other authority — and the combination verifies as a single party holding both. A host MUST refuse a private-room presentation that omits this.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"membership\",\n \"authority\"\n ],\n \"title\": \"AuthorityPresentation\",\n \"type\": \"object\"\n },\n \"DataCommitment\": {\n \"$ref\": \"#/$defs/DigestMultibase\",\n \"description\": \"The root of the room's record tree — a host's commitment to *which records the room holds*, as distinct from what any one of them says.\\n\\nA room's records are already signed and room-bound, so a host cannot forge, alter or relocate one. What it can do for free is stay silent: a listing that omits a record is indistinguishable from a room that never held it. This value is what makes that omission detectable, so it is only worth anything when the reader can compare it against a copy the host did not choose for them — one it gave another member, one it gave the same member earlier, or the witnessed anchor. A commitment read once, in isolation, proves nothing.\\n\\n**A root on its own is not comparable, and an earlier revision of this description said it was.** It claimed a host showing two members two different roots had been caught, which is false while a room can move between two reads: the host answers *there was a write*, and nothing contradicts it. Comparison needs the state each root describes, which is what `HeadVersion` names — and `RecordCount` is the other half of the same omission, since Certificate Transparency's signed tree head is a root *and a size* and this family shipped only the root. A reader that receives a `dataCommitment` **without** them can use it against a witnessed anchor, where the epoch pins the state, and **MUST NOT** compare it against another root.\\n\\n**The construction is normative**, because two hosts that compute different roots over the same room make every comparison meaningless:\\n 1. Take every record the room holds — including tombstones, which are records — and order them by `key` using unsigned byte order.\\n 2. Leaf: `SHA-256(0x00 || JCS(record))`, where the record is a `CommittedRecord` — that definition fixes the members exactly, and this step used to name a *projection* instead, which two implementations could read two ways — JCS is its RFC 8785 canonicalization, and `0x00` is RFC 6962's leaf-domain prefix.\\n 3. Internal node: `SHA-256(0x01 || left || right)`.\\n 4. A level with an odd number of nodes promotes the last one unchanged. It MUST NOT be duplicated: duplicating makes a tree of n leaves collide with one of n+1 whose last is repeated, so two different rooms commit to the same root.\\n 5. A room holding no records commits to `SHA-256(\\\"\\\")`, a distinguished value rather than zeroes — a root of zeroes is what an uninitialised buffer looks like, and an empty room is a real state a host must be able to commit to honestly.\\n\\nThe leaf covers the whole record rather than its body, and that is deliberate: a host that could flip `status` from active to retracted, move `pinned`, or rewrite `author` on an `attributed` room would rewrite what the room means without touching a byte of ciphertext. The **plaintext is never involved** — on the sealed tiers the host holds ciphertext and commits to exactly what it stores.\\n\\nThe commitment is over the **whole room**, never over the page being returned. A page-scoped root is one a host satisfies by construction and could never fail.\\n\\nProving that a *particular* record sits under this root is a separate question, answered by `RecordTrace` on a single-record read. A commitment catches a host that equivocates; a trace binds one record to what the host committed to. Neither is the other, and a reader wanting completeness needs both plus a root it did not get from the host it is checking.\",\n \"title\": \"DataCommitment\"\n },\n \"DigestMultibase\": {\n \"description\": \"A cryptographic digest as a multibase-encoded multihash — the encoding the W3C Verifiable Credentials Data Model 2.0 defines for `digestMultibase`, and the one `did:webvh` uses for its SCID and entry hashes.\\n\\nMultihash carries the hash algorithm in-band, so the value is self-describing and the wire format survives an algorithm change without a schema revision; multibase does the same for the base encoding, so a verifier never infers base58 from base64url by context. A bare hex string or a `sha-256:`-style prefix hard-codes one algorithm into the wire contract and is non-conforming here.\\n\\nThis definition constrains the *encoding only*. What the digest is computed over is stated by each referencing field, because it differs legitimately: a digest over a JSON document is taken over its RFC 8785 (JCS) canonicalization, while a digest over an opaque artifact is taken over its bytes. A field whose input is a JSON document and which does not name a canonicalization is not reproducible.\\n\\nRestricted to the two multibase headers W3C Controlled Identifiers 1.0 §2.4 normatively requires — `z` (base58btc) and `u` (base64url-no-pad). CID permits others but states that \\\"interoperability is not guaranteed between implementations using such values\\\", and a registry whose purpose is interoperability should not mint digests a conforming verifier may be unable to read. The alphabets are enforced rather than assumed: base58btc excludes 0, O, I and l, and an earlier permissive pattern let three published examples carry digests that were not valid base58 at all. base58btc is RECOMMENDED, for consistency with `did:key` and `did:webvh`.\",\n \"examples\": [\n \"zQmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR\"\n ],\n \"minLength\": 16,\n \"pattern\": \"^(z[1-9A-HJ-NP-Za-km-z]+|u[A-Za-z0-9_-]+)$\",\n \"title\": \"DigestMultibase\",\n \"type\": \"string\"\n },\n \"Ext\": {\n \"additionalProperties\": true,\n \"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.\",\n \"minProperties\": 1,\n \"propertyNames\": {\n \"pattern\": \"^[a-z][a-z0-9-]*(\\\\.[a-z0-9-]+)+$\"\n },\n \"title\": \"Ext\",\n \"type\": \"object\"\n },\n \"HeadVersion\": {\n \"description\": \"The highest version among the records `DataCommitment` covers. `0` for a room that holds none.\\n\\n**Derived from the same set as the root, and not read from the room's own counter.** The two agree for any host that has never erased a record — versions are assigned strictly increasing and a retraction keeps its tombstone — but they are not interchangeable, because a root and a counter are *two reads*, and two reads are not a snapshot. A write landing between them yields a pair that is individually correct and jointly false: two members holding roots taken over different trees, labelled with one version. That reads as equivocation and is not, and a **false accusation discredits the mechanism rather than the host** — the worst outcome available here. Taken from the committed set, the version cannot disagree with the root it labels, whatever else is happening to the room.\\n\\nThe corollary is worth stating: a host that **erases** a record — as distinct from retracting it, which leaves a tombstone in the tree — moves the root without necessarily moving this value, and two members straddling that erasure would see one version over two roots. Erasure is a retention act with its own answer, and a family that exposes one owes this definition another look.\\n\\n**This is what makes two roots comparable at all**, and without it the comparison this family is built on cannot be performed. A room moves: every put, curate and retraction assigns a new version, so two roots taken at two moments differ legitimately and a reader learns nothing from the difference. Shown two different roots, a host that equivocated and a host that was merely written to are indistinguishable — the first can always answer *the room moved between your reads*, and nothing contradicts it.\\n\\nA version is assigned by exactly the mutations that change the tree — every put, curate and retraction takes the next one — so the highest of them names the **state** the root describes. Two roots carrying the same `headVersion` and differing is a host caught: there is no write to attribute the difference to. Two roots carrying different ones are simply two moments, and a reader should draw nothing from them.\\n\\nA host can lie about this number too, and it is then lying about the counter it also uses for optimistic concurrency (`expectedVersion`) and for incremental sync (`sinceVersion`) — so a member holding a signed acknowledgement of a write at version `V` contradicts any head below `V` directly.\\n\\n**Not a timestamp.** A time is host-asserted, unverifiable and useless for this: two roots a second apart are not evidence of anything, while two roots at one version are.\",\n \"minimum\": 0,\n \"title\": \"HeadVersion\",\n \"type\": \"integer\"\n },\n \"RecordCount\": {\n \"description\": \"How many records the room held when `DataCommitment` was computed — the number of leaves in that tree, tombstones included, since a tombstone is a record.\\n\\n**Why a root needs this.** Certificate Transparency's signed tree head is a root *and a tree size*; this family shipped the root alone, and the half that was dropped is the half that makes a listing checkable. A reader holding a **complete, unfiltered** listing cannot recompute the root — a leaf commits to a whole record and a listing returns a projection without the body — but it can count. A host that omits a record from a listing while committing to a tree that holds it now contradicts itself in the same response, with no second party and no anchor involved.\\n\\nA host can of course understate both together. That is the point rather than a hole: the omission stops being silence and becomes a **specific claim about how many records the room holds**, which any other member's view, or any writer's signed put acknowledgement, contradicts. Making an omission attributable is the whole of what this machinery buys; it never claimed to make one impossible.\\n\\n**It counts the room, never the page.** The same rule `DataCommitment` states, and the same trap: a count scoped to what was returned is one a host satisfies by construction. So this is only comparable against a listing read to the end with **no** `prefix` and **no** `sinceVersion` — a filtered listing legitimately holds fewer, and a reader that compares one against this has found a discrepancy it created itself.\",\n \"minimum\": 0,\n \"title\": \"RecordCount\",\n \"type\": \"integer\"\n },\n \"RecordTrace\": {\n \"description\": \"The path from one record's leaf to the room's `DataCommitment` — a Merkle inclusion proof, in the vocabulary this work already uses for it.\\n\\n**It is not called `proof`** because in this framework that word is taken: `proof` is the document's data-integrity proof (SPEC §7.3), and a payload member of the same name in the same document invites reading one for the other. The two are not interchangeable and the confusion would be silent.\\n\\n**To verify**, given the `CommittedRecord` reassembled from the same response:\\n 1. `h = SHA-256(0x00 || JCS(record))` — the leaf, by `DataCommitment` step 2.\\n 2. For each step in order: `h = SHA-256(0x01 || sibling || h)` when `siblingIsLeft` is true, and `SHA-256(0x01 || h || sibling)` when it is false.\\n 3. `h` **MUST** equal the `dataCommitment` **carried in the same response**. Not one from an earlier read, and not one from a listing: a room moves, and a trace is only ever a statement about the tree it was cut from. A host **MUST** compute the trace and the commitment from the same snapshot.\\n\\nAn **empty array is valid** and is not the same as an absent member. It says the room holds exactly one record, whose leaf is the root; absence of `trace` says the host offered no trace at all.\\n\\nA trace is **not** always `ceil(log2 n)` steps. A level that promotes an odd node unchanged (`DataCommitment` step 4) contributes no step for that node, so a reader must follow the steps it was given rather than count them against a tree size it assumed.\\n\\n`maxItems` bounds a tree of 2⁶⁴ records. Verification cost is the reader's and the array is the host's, so the ceiling is stated rather than left to whoever writes the loop.\\n\\n**What a trace does not prove.** It binds a record to a root. It says nothing about whether that root is the room's — only comparing the root against one the host did not choose does that, exactly as `DataCommitment` describes. A reader that verifies a trace against a root received in the same breath has checked the host's arithmetic and nothing else. The two mechanisms answer different questions and neither substitutes for the other.\",\n \"items\": {\n \"additionalProperties\": false,\n \"properties\": {\n \"sibling\": {\n \"$ref\": \"#/$defs/DigestMultibase\",\n \"description\": \"The sibling node's hash — a leaf hash or an internal node hash of this room's record tree, encoded exactly as `DataCommitment` is. A digest over **bytes**, produced by one of the two prefixed constructions in `DataCommitment`, not over a JSON document.\"\n },\n \"siblingIsLeft\": {\n \"description\": \"Whether the sibling is the **left** child of the parent; the node being proved is the other one. Concatenation order is the whole of what a Merkle proof asserts, so this bit is load-bearing — inverting it on a single step yields a different root, and a reader that infers it from the record's position has assumed a tree shape the host never stated.\",\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"sibling\",\n \"siblingIsLeft\"\n ],\n \"type\": \"object\"\n },\n \"maxItems\": 64,\n \"title\": \"RecordTrace\",\n \"type\": \"array\"\n },\n \"Response\": {\n \"$anchor\": \"response\",\n \"additionalProperties\": false,\n \"dependentRequired\": {\n \"headVersion\": [\n \"dataCommitment\"\n ],\n \"recordCount\": [\n \"dataCommitment\"\n ],\n \"trace\": [\n \"dataCommitment\",\n \"status\",\n \"updatedAt\"\n ]\n },\n \"description\": \"Success response to rooms/records/get. Type https://trusttasks.org/spec/rooms/records/get/0.1#response.\",\n \"properties\": {\n \"author\": {\n \"description\": \"The member who wrote it. Present on `open` and `attributed`, absent on `private` where the author is sealed with the body. Committed. Mirrors `CommittedRecord`, which fixes the leaf preimage; see the note on `trace`.\\n\\nThis member is new to this response and is a **disclosure**: `rooms/records/list` already returns it on those tiers, so it tells a reader nothing the family withheld, but a host serving a single record now names its writer where before it did not. It is not conditional on `trace` — a reader wanting the record without the writer's identifier is asking for a different room tier, not a different response.\",\n \"type\": \"string\"\n },\n \"cleartext\": {\n \"additionalProperties\": true,\n \"description\": \"Present on an `open` room.\",\n \"type\": \"object\"\n },\n \"dataCommitment\": {\n \"$ref\": \"#/$defs/DataCommitment\",\n \"description\": \"The room's data commitment at the moment this record was read. Carried on a single-record read as well as a listing so a reader can tell whether the room moved between two reads — and so a `trace` returned beside it has a root to reach.\"\n },\n \"ext\": {\n \"$ref\": \"#/$defs/Ext\"\n },\n \"headVersion\": {\n \"$ref\": \"#/$defs/HeadVersion\",\n \"description\": \"The room's highest assigned record version, as of `dataCommitment`. Present only beside `dataCommitment`, and computed from the same snapshot: it describes the state that root was taken over, and a head that does not belong to that root is worse than none. Without it two roots are not comparable at all: a host shown to have served two different ones answers that the room moved, and nothing contradicts it.\"\n },\n \"key\": {\n \"type\": \"string\"\n },\n \"pinned\": {\n \"const\": true,\n \"description\": \"Present **only** when the record is pinned; absent means it is not. Committed. Mirrors `CommittedRecord`, which fixes the leaf preimage; see the note on `trace`. `false` is not a permitted spelling: absent is how false is written in the preimage, and two spellings would give one record two roots.\",\n \"type\": \"boolean\"\n },\n \"recordCount\": {\n \"$ref\": \"#/$defs/RecordCount\",\n \"description\": \"How many records the room holds, as of `dataCommitment`. Present only beside `dataCommitment`, and computed from the same snapshot: it describes the state that root was taken over, and a head that does not belong to that root is worse than none.\"\n },\n \"sealed\": {\n \"$ref\": \"#/$defs/SealedRecord\",\n \"description\": \"Present on an `attributed` or `private` room.\"\n },\n \"status\": {\n \"description\": \"Curation state. Committed. Mirrors `CommittedRecord`, which fixes the leaf preimage; see the note on `trace`. A host that serves a `trace` MUST serve this, because a reader cannot reach the leaf without it — and a host that could omit it could retract a record without touching a byte of it.\",\n \"enum\": [\n \"active\",\n \"deprecated\",\n \"retracted\"\n ],\n \"type\": \"string\"\n },\n \"trace\": {\n \"$ref\": \"#/$defs/RecordTrace\",\n \"description\": \"The path from this record's leaf to `dataCommitment`, proving the record sits under the root the host just asserted.\\n\\n**The leaf preimage is this response payload with its verification members — `dataCommitment`, `recordCount`, `headVersion` and `trace` — and `ext` removed** — which is exactly `CommittedRecord`, and a reader MAY validate the object it assembles against that definition before hashing it. Nothing is reconstructed and no member is carried twice; the reader deletes three members from what it already holds.\\n\\nOPTIONAL, on the same reasoning as `dataCommitment`: a host that maintains no tree must not invent one. A host that serves this MUST have computed it and `dataCommitment` from the same snapshot, and MUST serve every committed member it holds — an omitted `status`, `updatedAt`, `pinned` or `author` yields a leaf the reader cannot reach, so the failure is a refused trace rather than a false one.\"\n },\n \"updatedAt\": {\n \"description\": \"RFC 3339. Committed. Mirrors `CommittedRecord`, which fixes the leaf preimage; see the note on `trace`. Required alongside a `trace` for the same reason `status` is.\",\n \"format\": \"date-time\",\n \"type\": \"string\"\n },\n \"version\": {\n \"minimum\": 1,\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"key\",\n \"version\"\n ],\n \"title\": \"Rooms Records Get — response payload\",\n \"type\": \"object\"\n },\n \"SealedRecord\": {\n \"additionalProperties\": false,\n \"description\": \"A record as a host stores it on an `attributed` or `private` room. Title, description, body, author and tags are sealed together in one blob rather than separately: splitting them would let a host learn the shape of the material from ciphertext lengths, for no benefit, since a reader decrypts the whole record either way.\",\n \"properties\": {\n \"ciphertext\": {\n \"description\": \"The sealed record, base64url. Bound by AEAD associated data to `roomId`, `key`, `version` and `epoch`, so a host that relocates it to another key, version, epoch or room produces a mismatch and the open fails. The record cannot be moved undetected even though the host holds every byte of it.\",\n \"type\": \"string\"\n },\n \"epoch\": {\n \"description\": \"The key epoch this record was sealed under. Cleartext because the host must serve the right ciphertext, and bound into the associated data so that relabelling it fails authentication rather than causing a reader to try the wrong key.\",\n \"minimum\": 1,\n \"type\": \"integer\"\n },\n \"nonce\": {\n \"description\": \"AEAD nonce, base64url.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"ciphertext\",\n \"nonce\",\n \"epoch\"\n ],\n \"title\": \"SealedRecord\",\n \"type\": \"object\"\n }\n },\n \"$id\": \"https://trusttasks.org/spec/rooms/records/get/0.1\",\n \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n \"additionalProperties\": false,\n \"properties\": {\n \"ext\": {\n \"$ref\": \"#/$defs/Ext\",\n \"description\": \"Ecosystem-defined extension members per SPEC.md §4.5.1.\"\n },\n \"key\": {\n \"description\": \"The record to read.\",\n \"maxLength\": 512,\n \"type\": \"string\"\n },\n \"presentation\": {\n \"$ref\": \"#/$defs/AuthorityPresentation\",\n \"description\": \"Must confer the `read` action at this room's scope. A read presents exactly as a write does, and on a `private` room requires no host session at all — authorizing reads by session would hand the host a member identifier on every access, and a week of access logs would reconstruct the membership the tier exists to withhold.\"\n },\n \"roomId\": {\n \"description\": \"The room's identifier.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"roomId\",\n \"key\",\n \"presentation\"\n ],\n \"title\": \"Rooms Records Get — payload\",\n \"type\": \"object\"\n}\n",
);
}
impl crate::Payload for Response {
const TYPE_URI: &'static str = "https://trusttasks.org/spec/rooms/records/get/0.1#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(
"{\n \"$defs\": {\n \"AuthorityPresentation\": {\n \"additionalProperties\": false,\n \"description\": \"What a party presents to act on a room. Carries the whole authority chain: a host MUST NOT dereference an authority credential's `parent` to fetch a link it was not given. Resolving over the network would make verification depend on availability, turn every identifier into a request the host can be induced to make against an address the holder chooses, and signal credential use to whoever hosts the identifier. A host MUST bind the presenter to the chain's leaf. A chain that verifies is evidence that authority was conferred on somebody; it is not evidence that the party presenting it is that somebody. The leaf's subject MUST equal the party the host authenticated for this request — an identity the transport established or a document `proof` proved, never one named in a payload. A host that omits this check authorizes every captured presentation, and the omission is silent, because the chain still verifies.\",\n \"properties\": {\n \"authority\": {\n \"description\": \"The authority chain, LEAF FIRST: the first element is the credential being relied on and the last MUST be one issued by the room itself. Every link the presenter relies on is present, because the host will not fetch one. Capped at 8: verification is linear in chain length and runs on every operation, so an unbounded chain is a denial-of-service surface against the host. The known uses need 2 to 3 — a person attenuating to an agent, and that agent to a sub-agent.\",\n \"items\": {\n \"type\": \"string\"\n },\n \"maxItems\": 8,\n \"minItems\": 1,\n \"type\": \"array\"\n },\n \"membership\": {\n \"description\": \"The presenter's membership credential for this room, or — on a `private` room — a zero-knowledge presentation of it. Serialized per the governing profile.\",\n \"type\": \"string\"\n },\n \"subjectBinding\": {\n \"description\": \"REQUIRED on a `private` room, where the subject identifier is withheld: a proof that the membership credential and the authority chain's leaf describe the SAME subject. Without it two parties pool credentials — one contributes membership, the other authority — and the combination verifies as a single party holding both. A host MUST refuse a private-room presentation that omits this.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"membership\",\n \"authority\"\n ],\n \"title\": \"AuthorityPresentation\",\n \"type\": \"object\"\n },\n \"DataCommitment\": {\n \"$ref\": \"#/$defs/DigestMultibase\",\n \"description\": \"The root of the room's record tree — a host's commitment to *which records the room holds*, as distinct from what any one of them says.\\n\\nA room's records are already signed and room-bound, so a host cannot forge, alter or relocate one. What it can do for free is stay silent: a listing that omits a record is indistinguishable from a room that never held it. This value is what makes that omission detectable, so it is only worth anything when the reader can compare it against a copy the host did not choose for them — one it gave another member, one it gave the same member earlier, or the witnessed anchor. A commitment read once, in isolation, proves nothing.\\n\\n**A root on its own is not comparable, and an earlier revision of this description said it was.** It claimed a host showing two members two different roots had been caught, which is false while a room can move between two reads: the host answers *there was a write*, and nothing contradicts it. Comparison needs the state each root describes, which is what `HeadVersion` names — and `RecordCount` is the other half of the same omission, since Certificate Transparency's signed tree head is a root *and a size* and this family shipped only the root. A reader that receives a `dataCommitment` **without** them can use it against a witnessed anchor, where the epoch pins the state, and **MUST NOT** compare it against another root.\\n\\n**The construction is normative**, because two hosts that compute different roots over the same room make every comparison meaningless:\\n 1. Take every record the room holds — including tombstones, which are records — and order them by `key` using unsigned byte order.\\n 2. Leaf: `SHA-256(0x00 || JCS(record))`, where the record is a `CommittedRecord` — that definition fixes the members exactly, and this step used to name a *projection* instead, which two implementations could read two ways — JCS is its RFC 8785 canonicalization, and `0x00` is RFC 6962's leaf-domain prefix.\\n 3. Internal node: `SHA-256(0x01 || left || right)`.\\n 4. A level with an odd number of nodes promotes the last one unchanged. It MUST NOT be duplicated: duplicating makes a tree of n leaves collide with one of n+1 whose last is repeated, so two different rooms commit to the same root.\\n 5. A room holding no records commits to `SHA-256(\\\"\\\")`, a distinguished value rather than zeroes — a root of zeroes is what an uninitialised buffer looks like, and an empty room is a real state a host must be able to commit to honestly.\\n\\nThe leaf covers the whole record rather than its body, and that is deliberate: a host that could flip `status` from active to retracted, move `pinned`, or rewrite `author` on an `attributed` room would rewrite what the room means without touching a byte of ciphertext. The **plaintext is never involved** — on the sealed tiers the host holds ciphertext and commits to exactly what it stores.\\n\\nThe commitment is over the **whole room**, never over the page being returned. A page-scoped root is one a host satisfies by construction and could never fail.\\n\\nProving that a *particular* record sits under this root is a separate question, answered by `RecordTrace` on a single-record read. A commitment catches a host that equivocates; a trace binds one record to what the host committed to. Neither is the other, and a reader wanting completeness needs both plus a root it did not get from the host it is checking.\",\n \"title\": \"DataCommitment\"\n },\n \"DigestMultibase\": {\n \"description\": \"A cryptographic digest as a multibase-encoded multihash — the encoding the W3C Verifiable Credentials Data Model 2.0 defines for `digestMultibase`, and the one `did:webvh` uses for its SCID and entry hashes.\\n\\nMultihash carries the hash algorithm in-band, so the value is self-describing and the wire format survives an algorithm change without a schema revision; multibase does the same for the base encoding, so a verifier never infers base58 from base64url by context. A bare hex string or a `sha-256:`-style prefix hard-codes one algorithm into the wire contract and is non-conforming here.\\n\\nThis definition constrains the *encoding only*. What the digest is computed over is stated by each referencing field, because it differs legitimately: a digest over a JSON document is taken over its RFC 8785 (JCS) canonicalization, while a digest over an opaque artifact is taken over its bytes. A field whose input is a JSON document and which does not name a canonicalization is not reproducible.\\n\\nRestricted to the two multibase headers W3C Controlled Identifiers 1.0 §2.4 normatively requires — `z` (base58btc) and `u` (base64url-no-pad). CID permits others but states that \\\"interoperability is not guaranteed between implementations using such values\\\", and a registry whose purpose is interoperability should not mint digests a conforming verifier may be unable to read. The alphabets are enforced rather than assumed: base58btc excludes 0, O, I and l, and an earlier permissive pattern let three published examples carry digests that were not valid base58 at all. base58btc is RECOMMENDED, for consistency with `did:key` and `did:webvh`.\",\n \"examples\": [\n \"zQmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR\"\n ],\n \"minLength\": 16,\n \"pattern\": \"^(z[1-9A-HJ-NP-Za-km-z]+|u[A-Za-z0-9_-]+)$\",\n \"title\": \"DigestMultibase\",\n \"type\": \"string\"\n },\n \"Ext\": {\n \"additionalProperties\": true,\n \"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.\",\n \"minProperties\": 1,\n \"propertyNames\": {\n \"pattern\": \"^[a-z][a-z0-9-]*(\\\\.[a-z0-9-]+)+$\"\n },\n \"title\": \"Ext\",\n \"type\": \"object\"\n },\n \"HeadVersion\": {\n \"description\": \"The highest version among the records `DataCommitment` covers. `0` for a room that holds none.\\n\\n**Derived from the same set as the root, and not read from the room's own counter.** The two agree for any host that has never erased a record — versions are assigned strictly increasing and a retraction keeps its tombstone — but they are not interchangeable, because a root and a counter are *two reads*, and two reads are not a snapshot. A write landing between them yields a pair that is individually correct and jointly false: two members holding roots taken over different trees, labelled with one version. That reads as equivocation and is not, and a **false accusation discredits the mechanism rather than the host** — the worst outcome available here. Taken from the committed set, the version cannot disagree with the root it labels, whatever else is happening to the room.\\n\\nThe corollary is worth stating: a host that **erases** a record — as distinct from retracting it, which leaves a tombstone in the tree — moves the root without necessarily moving this value, and two members straddling that erasure would see one version over two roots. Erasure is a retention act with its own answer, and a family that exposes one owes this definition another look.\\n\\n**This is what makes two roots comparable at all**, and without it the comparison this family is built on cannot be performed. A room moves: every put, curate and retraction assigns a new version, so two roots taken at two moments differ legitimately and a reader learns nothing from the difference. Shown two different roots, a host that equivocated and a host that was merely written to are indistinguishable — the first can always answer *the room moved between your reads*, and nothing contradicts it.\\n\\nA version is assigned by exactly the mutations that change the tree — every put, curate and retraction takes the next one — so the highest of them names the **state** the root describes. Two roots carrying the same `headVersion` and differing is a host caught: there is no write to attribute the difference to. Two roots carrying different ones are simply two moments, and a reader should draw nothing from them.\\n\\nA host can lie about this number too, and it is then lying about the counter it also uses for optimistic concurrency (`expectedVersion`) and for incremental sync (`sinceVersion`) — so a member holding a signed acknowledgement of a write at version `V` contradicts any head below `V` directly.\\n\\n**Not a timestamp.** A time is host-asserted, unverifiable and useless for this: two roots a second apart are not evidence of anything, while two roots at one version are.\",\n \"minimum\": 0,\n \"title\": \"HeadVersion\",\n \"type\": \"integer\"\n },\n \"RecordCount\": {\n \"description\": \"How many records the room held when `DataCommitment` was computed — the number of leaves in that tree, tombstones included, since a tombstone is a record.\\n\\n**Why a root needs this.** Certificate Transparency's signed tree head is a root *and a tree size*; this family shipped the root alone, and the half that was dropped is the half that makes a listing checkable. A reader holding a **complete, unfiltered** listing cannot recompute the root — a leaf commits to a whole record and a listing returns a projection without the body — but it can count. A host that omits a record from a listing while committing to a tree that holds it now contradicts itself in the same response, with no second party and no anchor involved.\\n\\nA host can of course understate both together. That is the point rather than a hole: the omission stops being silence and becomes a **specific claim about how many records the room holds**, which any other member's view, or any writer's signed put acknowledgement, contradicts. Making an omission attributable is the whole of what this machinery buys; it never claimed to make one impossible.\\n\\n**It counts the room, never the page.** The same rule `DataCommitment` states, and the same trap: a count scoped to what was returned is one a host satisfies by construction. So this is only comparable against a listing read to the end with **no** `prefix` and **no** `sinceVersion` — a filtered listing legitimately holds fewer, and a reader that compares one against this has found a discrepancy it created itself.\",\n \"minimum\": 0,\n \"title\": \"RecordCount\",\n \"type\": \"integer\"\n },\n \"RecordTrace\": {\n \"description\": \"The path from one record's leaf to the room's `DataCommitment` — a Merkle inclusion proof, in the vocabulary this work already uses for it.\\n\\n**It is not called `proof`** because in this framework that word is taken: `proof` is the document's data-integrity proof (SPEC §7.3), and a payload member of the same name in the same document invites reading one for the other. The two are not interchangeable and the confusion would be silent.\\n\\n**To verify**, given the `CommittedRecord` reassembled from the same response:\\n 1. `h = SHA-256(0x00 || JCS(record))` — the leaf, by `DataCommitment` step 2.\\n 2. For each step in order: `h = SHA-256(0x01 || sibling || h)` when `siblingIsLeft` is true, and `SHA-256(0x01 || h || sibling)` when it is false.\\n 3. `h` **MUST** equal the `dataCommitment` **carried in the same response**. Not one from an earlier read, and not one from a listing: a room moves, and a trace is only ever a statement about the tree it was cut from. A host **MUST** compute the trace and the commitment from the same snapshot.\\n\\nAn **empty array is valid** and is not the same as an absent member. It says the room holds exactly one record, whose leaf is the root; absence of `trace` says the host offered no trace at all.\\n\\nA trace is **not** always `ceil(log2 n)` steps. A level that promotes an odd node unchanged (`DataCommitment` step 4) contributes no step for that node, so a reader must follow the steps it was given rather than count them against a tree size it assumed.\\n\\n`maxItems` bounds a tree of 2⁶⁴ records. Verification cost is the reader's and the array is the host's, so the ceiling is stated rather than left to whoever writes the loop.\\n\\n**What a trace does not prove.** It binds a record to a root. It says nothing about whether that root is the room's — only comparing the root against one the host did not choose does that, exactly as `DataCommitment` describes. A reader that verifies a trace against a root received in the same breath has checked the host's arithmetic and nothing else. The two mechanisms answer different questions and neither substitutes for the other.\",\n \"items\": {\n \"additionalProperties\": false,\n \"properties\": {\n \"sibling\": {\n \"$ref\": \"#/$defs/DigestMultibase\",\n \"description\": \"The sibling node's hash — a leaf hash or an internal node hash of this room's record tree, encoded exactly as `DataCommitment` is. A digest over **bytes**, produced by one of the two prefixed constructions in `DataCommitment`, not over a JSON document.\"\n },\n \"siblingIsLeft\": {\n \"description\": \"Whether the sibling is the **left** child of the parent; the node being proved is the other one. Concatenation order is the whole of what a Merkle proof asserts, so this bit is load-bearing — inverting it on a single step yields a different root, and a reader that infers it from the record's position has assumed a tree shape the host never stated.\",\n \"type\": \"boolean\"\n }\n },\n \"required\": [\n \"sibling\",\n \"siblingIsLeft\"\n ],\n \"type\": \"object\"\n },\n \"maxItems\": 64,\n \"title\": \"RecordTrace\",\n \"type\": \"array\"\n },\n \"Response\": {\n \"$anchor\": \"response\",\n \"additionalProperties\": false,\n \"dependentRequired\": {\n \"headVersion\": [\n \"dataCommitment\"\n ],\n \"recordCount\": [\n \"dataCommitment\"\n ],\n \"trace\": [\n \"dataCommitment\",\n \"status\",\n \"updatedAt\"\n ]\n },\n \"description\": \"Success response to rooms/records/get. Type https://trusttasks.org/spec/rooms/records/get/0.1#response.\",\n \"properties\": {\n \"author\": {\n \"description\": \"The member who wrote it. Present on `open` and `attributed`, absent on `private` where the author is sealed with the body. Committed. Mirrors `CommittedRecord`, which fixes the leaf preimage; see the note on `trace`.\\n\\nThis member is new to this response and is a **disclosure**: `rooms/records/list` already returns it on those tiers, so it tells a reader nothing the family withheld, but a host serving a single record now names its writer where before it did not. It is not conditional on `trace` — a reader wanting the record without the writer's identifier is asking for a different room tier, not a different response.\",\n \"type\": \"string\"\n },\n \"cleartext\": {\n \"additionalProperties\": true,\n \"description\": \"Present on an `open` room.\",\n \"type\": \"object\"\n },\n \"dataCommitment\": {\n \"$ref\": \"#/$defs/DataCommitment\",\n \"description\": \"The room's data commitment at the moment this record was read. Carried on a single-record read as well as a listing so a reader can tell whether the room moved between two reads — and so a `trace` returned beside it has a root to reach.\"\n },\n \"ext\": {\n \"$ref\": \"#/$defs/Ext\"\n },\n \"headVersion\": {\n \"$ref\": \"#/$defs/HeadVersion\",\n \"description\": \"The room's highest assigned record version, as of `dataCommitment`. Present only beside `dataCommitment`, and computed from the same snapshot: it describes the state that root was taken over, and a head that does not belong to that root is worse than none. Without it two roots are not comparable at all: a host shown to have served two different ones answers that the room moved, and nothing contradicts it.\"\n },\n \"key\": {\n \"type\": \"string\"\n },\n \"pinned\": {\n \"const\": true,\n \"description\": \"Present **only** when the record is pinned; absent means it is not. Committed. Mirrors `CommittedRecord`, which fixes the leaf preimage; see the note on `trace`. `false` is not a permitted spelling: absent is how false is written in the preimage, and two spellings would give one record two roots.\",\n \"type\": \"boolean\"\n },\n \"recordCount\": {\n \"$ref\": \"#/$defs/RecordCount\",\n \"description\": \"How many records the room holds, as of `dataCommitment`. Present only beside `dataCommitment`, and computed from the same snapshot: it describes the state that root was taken over, and a head that does not belong to that root is worse than none.\"\n },\n \"sealed\": {\n \"$ref\": \"#/$defs/SealedRecord\",\n \"description\": \"Present on an `attributed` or `private` room.\"\n },\n \"status\": {\n \"description\": \"Curation state. Committed. Mirrors `CommittedRecord`, which fixes the leaf preimage; see the note on `trace`. A host that serves a `trace` MUST serve this, because a reader cannot reach the leaf without it — and a host that could omit it could retract a record without touching a byte of it.\",\n \"enum\": [\n \"active\",\n \"deprecated\",\n \"retracted\"\n ],\n \"type\": \"string\"\n },\n \"trace\": {\n \"$ref\": \"#/$defs/RecordTrace\",\n \"description\": \"The path from this record's leaf to `dataCommitment`, proving the record sits under the root the host just asserted.\\n\\n**The leaf preimage is this response payload with its verification members — `dataCommitment`, `recordCount`, `headVersion` and `trace` — and `ext` removed** — which is exactly `CommittedRecord`, and a reader MAY validate the object it assembles against that definition before hashing it. Nothing is reconstructed and no member is carried twice; the reader deletes three members from what it already holds.\\n\\nOPTIONAL, on the same reasoning as `dataCommitment`: a host that maintains no tree must not invent one. A host that serves this MUST have computed it and `dataCommitment` from the same snapshot, and MUST serve every committed member it holds — an omitted `status`, `updatedAt`, `pinned` or `author` yields a leaf the reader cannot reach, so the failure is a refused trace rather than a false one.\"\n },\n \"updatedAt\": {\n \"description\": \"RFC 3339. Committed. Mirrors `CommittedRecord`, which fixes the leaf preimage; see the note on `trace`. Required alongside a `trace` for the same reason `status` is.\",\n \"format\": \"date-time\",\n \"type\": \"string\"\n },\n \"version\": {\n \"minimum\": 1,\n \"type\": \"integer\"\n }\n },\n \"required\": [\n \"key\",\n \"version\"\n ],\n \"title\": \"Rooms Records Get — response payload\",\n \"type\": \"object\"\n },\n \"SealedRecord\": {\n \"additionalProperties\": false,\n \"description\": \"A record as a host stores it on an `attributed` or `private` room. Title, description, body, author and tags are sealed together in one blob rather than separately: splitting them would let a host learn the shape of the material from ciphertext lengths, for no benefit, since a reader decrypts the whole record either way.\",\n \"properties\": {\n \"ciphertext\": {\n \"description\": \"The sealed record, base64url. Bound by AEAD associated data to `roomId`, `key`, `version` and `epoch`, so a host that relocates it to another key, version, epoch or room produces a mismatch and the open fails. The record cannot be moved undetected even though the host holds every byte of it.\",\n \"type\": \"string\"\n },\n \"epoch\": {\n \"description\": \"The key epoch this record was sealed under. Cleartext because the host must serve the right ciphertext, and bound into the associated data so that relabelling it fails authentication rather than causing a reader to try the wrong key.\",\n \"minimum\": 1,\n \"type\": \"integer\"\n },\n \"nonce\": {\n \"description\": \"AEAD nonce, base64url.\",\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"ciphertext\",\n \"nonce\",\n \"epoch\"\n ],\n \"title\": \"SealedRecord\",\n \"type\": \"object\"\n }\n },\n \"$ref\": \"#/$defs/Response\",\n \"$schema\": \"https://json-schema.org/draft/2020-12/schema\"\n}\n",
);
}
impl crate::RequestPayload for Payload {
type Response = Response;
}
/// 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_AUTHORIZED,
error_codes::NOT_FOUND,
error_codes::CHAIN_TOO_DEEP,
error_codes::SUBJECT_BINDING_MISSING,
];
/// 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/records/get:notAuthorized`
///
/// The presentation does not confer `read` at this room's scope, or its chain does not reach the room.
///
/// Declared `retryable: false`.
pub const NOT_AUTHORIZED: crate::DeclaredErrorCode = crate::DeclaredErrorCode {
code: "rooms/records/get:notAuthorized",
retryable: false,
};
/// `rooms/records/get:notFound`
///
/// No record with that key in this room.
///
/// Declared `retryable: false`.
pub const NOT_FOUND: crate::DeclaredErrorCode = crate::DeclaredErrorCode {
code: "rooms/records/get:notFound",
retryable: false,
};
/// `rooms/records/get:chainTooDeep`
///
/// The authority chain exceeds the maximum of 8 links.
///
/// Declared `retryable: false`.
pub const CHAIN_TOO_DEEP: crate::DeclaredErrorCode = crate::DeclaredErrorCode {
code: "rooms/records/get:chainTooDeep",
retryable: false,
};
/// `rooms/records/get:subjectBindingMissing`
///
/// A `private` room presentation omitted the required same-subject proof.
///
/// Declared `retryable: false`.
pub const SUBJECT_BINDING_MISSING: crate::DeclaredErrorCode = crate::DeclaredErrorCode {
code: "rooms/records/get:subjectBindingMissing",
retryable: false,
};
}