---
slug: rooms/keys/chain
version: "0.2"
title: "Rooms Keys — Chain"
summary: "A member hands their key-holding agent the room's epoch key chain, so it can open records sealed before they joined — and the room's epoch floor, below which it keeps nothing."
status: draft
targetFrameworkVersion: "0.5.0"
category: ai-agents
# keywords and authors are OPTIONAL, and omitted here on purpose: the build derives
# keywords from the slug segments + category, and authors from CODEOWNERS (falling
# back to this folder's git history). Declare them only where the derivation would
# be wrong — a term a searcher would use that appears nowhere in the slug, or an
# editor who is not this slug's CODEOWNER.
#   keywords: [rooms, keys, chain, a-term-a-searcher-would-use]
#   authors:
#     - Your Name (https://github.com/your-handle)
parties:
  - role: Member
    requirement: REQUIRED
    member: issuer
    identifierScope: pairwise
  - role: KeyHolder
    requirement: REQUIRED
    member: recipient
proofRequirement:
  requirement: REQUIRED
  rationale: >-
    The request hands the recipient key material to retain and act on. One whose origin depended on the transport would let a compromised channel fill a member's own key holder with rungs of somebody else's choosing.
issuedAtRequirement:
  requirement: REQUIRED
  rationale: "A replayed delivery is harmless — rungs are idempotent by epoch — but an undated one cannot be reasoned about when a member is re-establishing a key holder from more than one source."
sideEffects:
  level: mutating
  rationale: >-
    The recipient retains the rungs above the room's epoch floor — they are what lets it open records sealed before its principal joined — and discards everything it holds below a floor it is handed.
exposure:
  discloses: metadata
  ingests: secret
  actsAsSubject: false
  rationale: >-
    The request carries wrapped key material INTO the recipient — that is what a rung is — so `ingests` is `secret` even though the response discloses only how far back the recipient can now read. The recipient is the member's own key holder, which is the only party this may be sent to.
retention:
  class: durable
  rationale: >-
    The rungs are kept for the life of the room, down to its epoch floor; the floor itself is kept for as long as anything is held for the room. Discarding rungs above the floor means the recipient can no longer open what they reach, and re-fetching them is the only repair.
errorCodes:
  - code: rooms/keys/chain:notAMember
    meaning: "The recipient holds no group state for this room, so there is nothing for the rungs to extend."
    retryable: false
related:
  - rooms/epoch/chain
  - rooms/epoch/prune
  - rooms/keys/backfill
  - rooms/keys/open
  - rooms/keys/welcome
---

## Abstract

A member hands their **key holder** — the party that holds their room keys and opens records on their agent's behalf — the room's epoch key chain, so that it can open records sealed before they joined.

[`rooms/epoch/chain`](../../../epoch/chain/0.2/spec.md) gets the rungs from the room's host to the member. This gets them the last leg, from the member to the party that will actually use them. The two are not the same delivery and cannot be collapsed: a host is not permitted to speak to a member's key holder, and a key holder does not present the member's credentials to a host.

Without it a member who joins reads the room's history in their own client and their **agent** does not, which is the more confusing half of the same failure: an agent recalling from a room it is plainly a member of, finding nothing older than the day it arrived.

A key holder accrues rungs on its own for every membership change it lives through — each [`rooms/keys/commit`](../../commit/0.1/spec.md) carries one. This task is for the history it did **not** live through.

Version 0.2 carries the room's **epoch floor** with the rungs. When a room's owner prunes the
chain ([`rooms/epoch/prune`](../../../epoch/prune/0.2/spec.md)) the host erases its rungs, but a
key holder keeps a copy of its own, and nothing in 0.1 told it to let go — or stopped a member
relaying a mirror's chain from handing the rungs back. In 0.2 the member relays the floor the
host served, and the key holder discards what it holds below it and keeps nothing below it again
([`EpochFloor`](../../../_shared/0.1/room.schema.json)).

## Status of this Document

This specification is a **draft** ([SPEC §5.3](/SPEC.md#53-maturity-levels)). It targets framework version 0.5.0 and may change without a version bump while it remains a draft ([SPEC §5.2](/SPEC.md#52-compatibility-rules)).

### What changed from 0.1

- `epochFloor` in the request, relayed from the host's [`rooms/epoch/chain`](../../../epoch/chain/0.2/spec.md)
  0.2 response; `links` becomes optional, so a member can pass on a floor alone. At least one of
  the two is required.
- `epochFloor` in the response: the floor the recipient now holds.
- The recipient discards what it holds below the floor and does not store a rung at or below
  it, from this or any other source.

New members on closed payloads and new obligations: a `MINOR` increment per
[SPEC §5.2](/SPEC.md#52-compatibility-rules). A recipient implementing 0.2 **SHOULD** continue to
accept 0.1, and **MUST** apply the floor it holds there too — not storing a rung at or below it
— since a 0.1 request is exactly how a rung the room has forgotten would come back.

## Conformance

The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY** and **OPTIONAL** in this document are to be interpreted as described in [BCP 14](https://www.rfc-editor.org/info/bcp14) when, and only when, they appear in all capitals.

A conforming producer and consumer satisfy [SPEC §7.1 and §7.2](/SPEC.md#7-minimum-requirements) in addition to the requirements stated here.

## Authorization

**The entitlement is being the recipient's own principal.** A key holder holds one member's room keys, and this task extends what it can decrypt — so what authorizes it is not a credential the room issued but the standing relationship between a member and their own key holder. A conforming consumer **MUST** accept this only from the party whose keys it holds, established by the same means it establishes that for every other custody task in this family, and **MUST** refuse it for a room it holds no group state for.

That is deliberately narrower than the grant used to *obtain* the rungs. Fetching them from a host takes a `read` chain the room issued ([`rooms/epoch/chain`](../../../epoch/chain/0.2/spec.md)); handing them onward takes no room credential at all, because the recipient is not being asked to believe anything about the room — it is being handed material it will verify by trying to use it.

Per [SPEC §7.2 item 10](/SPEC.md#72-consumer-requirements), verifying the VID, `issuer`, `recipient` or `proof` establishes *who sent this* and *that it is unaltered* — never that they were entitled to the outcome. Here those two happen to coincide, because the entitlement *is* an identity relationship; a consumer must still make the check deliberately rather than treat a valid proof as the answer.

**What a wrongly accepted request costs.** Not disclosure — the sender learns nothing, and the response says only how far back the recipient can read. It costs the recipient's storage, and the risk that its principal's records stop opening if it is fed rungs that displace real ones. That is why a rung already held is never replaced, which is the same rule the host side follows.

## Definitions

**`roomId`** — the room these rungs belong to. The recipient **MUST** already hold group state for it, and **MUST NOT** create any on the strength of this request: a rung is inert without an epoch key, so retaining rungs for a room one is not in is retaining key material for nothing.

**`links`** — the rungs, in any order. Order does not matter because a rung is identified by the epoch it opens under, and the chain is walked on demand rather than on receipt.

**`epochFloor`** — the room's epoch floor, as the host served it with the rungs. The recipient applies the higher of it and the floor it already holds.

**`earliestReadableEpoch`** (response) — the earliest epoch the recipient can now derive a key for, having walked what it holds. Never below the floor.

### The epoch floor

A member relaying rungs from a [`rooms/epoch/chain`](../../../epoch/chain/0.2/spec.md) 0.2
response **MUST** relay the `epochFloor` it carried, and **SHOULD** send a floor on its own
whenever it learns one higher than it last relayed — that is the only way a key holder that
never reads the chain itself learns that the room has forgotten something.

A conforming recipient:

1. **MUST** keep, per room, the highest floor it has learnt from any source, and **MUST NOT**
   lower it.
2. On a floor higher than the one it held, **MUST** do everything
   [`EpochFloor`](../../../_shared/0.1/room.schema.json) requires before answering: discard every
   rung numbered at or below it, every storage key, file key or other key material for an epoch
   below it, and keep nothing it later derives there in passing.
3. **MUST NOT** store a rung numbered at or below the floor it holds, whoever sends it — and
   **MUST NOT** refuse the request for carrying one. Such rungs are not counted in `stored`.
4. **MUST** report `epochFloor` as the floor it now holds, and **MUST NOT** report an
   `earliestReadableEpoch` below it.

The rule that a rung below a gap is early rather than wrong (below) holds above the floor and
only there: a rung below the floor is not early, it is forgotten.

**`stored`** (response) — how many rungs were new to the recipient.

### The response answers a question the request cannot

`earliestReadableEpoch` is not a restatement of what was sent. A rung extends reach only if every rung above it is present too, so a caller that supplied a set with a gap in it learns so here — rather than at the first record that will not open, which reads like corruption.

This is also why the recipient **MUST NOT** reject rungs it cannot currently use. A rung below a gap is not wrong; it is early, and it becomes useful the moment the gap is filled by a later delivery. Refusing it would make the natural repair — fetch more and send again — fail on the attempt that was about to succeed.

Note what the recipient can honestly claim here and a host could not. The host serving [`rooms/epoch/chain`](../../../epoch/chain/0.2/spec.md) can say how many rungs it holds, and nothing about whether they *work*; a member cannot check that claim without walking them. The key holder **is** the party that walks them, so `earliestReadableEpoch` is computed from keys it actually derived.

## Request

A **Member** sends this to their **KeyHolder** — their own key-holding agent, and no one else. The payload is the top-level schema in [`payload.schema.json`](payload.schema.json).

### A member who has just joined delivers the chain they fetched

Three rungs, taking the key holder from the epoch its Welcome arrived at back to the room's first.

```json
{
  "id": "urn:uuid:00000000-0000-4000-8000-000000000001",
  "type": "https://trusttasks.org/spec/rooms/keys/chain/0.2#request",
  "issuer": "did:example:member",
  "recipient": "did:example:keyholder",
  "issuedAt": "2026-01-01T00:00:00Z",
  "threadId": "urn:uuid:00000000-0000-4000-8000-0000000000ff",
  "payload": {
    "roomId": "did:webvh:example.com:rooms:northwind",
    "links": [
      { "epoch": 4, "wrapped": "Lp3wXc9TgYw2mQnR4vBk8Q", "nonce": "c1Au9Rn3Zr2tWwS1" },
      { "epoch": 3, "wrapped": "Tf6yNb2VhZx5pRoS7wCl9Q", "nonce": "d2Bv0So4As3uXxT2" },
      { "epoch": 2, "wrapped": "Wq8zMd4XjBy7rTqU9yEn1Q", "nonce": "e3Cw1Tp5Bt4vYyU3" }
    ]
  }
}
```

## Response

The **KeyHolder** responds, using the sub-schema reachable via `$anchor: "response"`.

Failures use a `trust-task-error` document rather than a `#response`, per [SPEC §8.1](/SPEC.md#81-the-trust-task-error-specification).

### The whole history is now reachable

`earliestReadableEpoch: 1` is the answer a joining member is looking for. Had one rung been missing, this would name the epoch the walk stopped at instead — and `stored` would still count what arrived.

```json
{
  "id": "urn:uuid:00000000-0000-4000-8000-000000000002",
  "type": "https://trusttasks.org/spec/rooms/keys/chain/0.2#response",
  "issuer": "did:example:keyholder",
  "recipient": "did:example:member",
  "issuedAt": "2026-01-01T00:00:01Z",
  "threadId": "urn:uuid:00000000-0000-4000-8000-0000000000ff",
  "payload": {
    "roomId": "did:webvh:example.com:rooms:northwind",
    "earliestReadableEpoch": 1,
    "stored": 3
  }
}
```

### A floor relayed on its own

The owner pruned the room's history before epoch 3. The member read the floor from the host and
passes it on; the key holder discards rungs 2 and 3 and the keys of epochs 1 and 2.

```json
{
  "id": "urn:uuid:00000000-0000-4000-8000-000000000003",
  "type": "https://trusttasks.org/spec/rooms/keys/chain/0.2#request",
  "issuer": "did:example:member",
  "recipient": "did:example:keyholder",
  "issuedAt": "2026-01-02T00:00:00Z",
  "threadId": "urn:uuid:00000000-0000-4000-8000-0000000000fe",
  "payload": {
    "roomId": "did:webvh:example.com:rooms:northwind",
    "epochFloor": 3
  }
}
```

```json
{
  "id": "urn:uuid:00000000-0000-4000-8000-000000000004",
  "type": "https://trusttasks.org/spec/rooms/keys/chain/0.2#response",
  "issuer": "did:example:keyholder",
  "recipient": "did:example:member",
  "issuedAt": "2026-01-02T00:00:01Z",
  "threadId": "urn:uuid:00000000-0000-4000-8000-0000000000fe",
  "payload": {
    "roomId": "did:webvh:example.com:rooms:northwind",
    "earliestReadableEpoch": 3,
    "stored": 0,
    "epochFloor": 3
  }
}
```

## Security & Privacy

### Data carried

The request carries **wrapped key material**: each rung is one epoch's storage key sealed under the next. The response carries two integers.

**Who this may be sent to is the whole of its security.** A rung is inert to anyone holding no epoch key, so the chain is safe to fetch from a host and safe to carry over the network — but the recipient here is by definition a party that *does* hold one, and handing it the chain extends what it can decrypt to the room's whole retained history. A member **MUST** send this only to their own key holder. There is no version of this task addressed to somebody else's.

A producer **MUST NOT** put record content, member identifiers, or anything descriptive in `ext`. Everything the room seals is sealed so that exchanges like this one do not disclose it.

### Correlation

The recipient is the member's own infrastructure and already knows which rooms it holds keys for, so this discloses nothing to it that it did not have.

To an observer, the shape is the informative part: this is sent about **once** — on joining, or after restoring a key holder — so its presence says a member has just joined or just recovered. It is worth sending over the same transport as the member's ordinary traffic with their key holder rather than a distinguishable one.

`links` discloses how many epochs the room has had to anyone who sees the request, which is what the room's epoch number already discloses to anyone who can read it.

### Retention

The recipient keeps the rungs for the life of the room, down to its epoch floor, and the floor itself for as long as it holds anything for the room. Below the floor it keeps nothing, and it cannot recall what it already returned to its principal. Above the floor, discarding rungs means it can no longer open what they reach, and re-fetching is the only repair. They are exactly as sensitive as the keys they wrap and belong wherever that key holder's other room key material lives.

The member's own copy is not needed once delivered — the response says how far the recipient can now read, which is the only thing the member wanted to know.

### Consent/purpose

The chain is delivered so that a member's agent can read the room its principal is a member of. It confers nothing the member did not already hold: they fetched these rungs with a `read` grant the room issued, and this hands them to the party that acts for them.

This specification describes purpose only. Per [SPEC §7.3 item 13](/SPEC.md#73-specification-requirements) it does **not** declare that consent, approval or a step-up is required.
