@openvtc/trust-tasks 0.27.0 → 0.27.2

package/dist/rooms/keys/chain/0.2/payload.d.ts

@@ -0,0 +1,450 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/rooms/keys/chain/0.2/payload.schema.json
+ */
+import type { EpochFloor, EpochLink, Ext } from "../../../../_shared/components.js";
+export type RoomsKeysChainPayload = {
+    [k: string]: unknown | undefined;
+} & {
+    /**
+     * The room whose chain these rungs belong to. The recipient MUST hold group state for it, and MUST NOT create any on the strength of this request: rungs are inert without an epoch key, so accepting them for a room one is not in would retain key material for nothing.
+     */
+    roomId: string;
+    /**
+     * The rungs, in any order. A recipient stores those numbered above the room's epoch floor — the higher of the one it holds and `epochFloor` — and reports how far back it can now reach; see the response's `earliestReadableEpoch`. Absent when the request only relays a floor.
+     *
+     * @minItems 1
+     */
+    links?: [EpochLink, ...EpochLink[]];
+    /**
+     * The room's epoch floor, exactly as the host served it in the `rooms/epoch/chain` 0.2 response the rungs came from. A member relaying rungs MUST relay it when the host served one, and MAY send it alone, with no `links`, to pass on a floor it has just learnt. The recipient applies it as `EpochFloor` requires.
+     */
+    epochFloor?: EpochFloor;
+    /**
+     * Ecosystem-defined extension members per SPEC.md §4.5.1.
+     */
+    ext?: Ext;
+};
+/**
+ * Success response to rooms/keys/chain. Type https://trusttasks.org/spec/rooms/keys/chain/0.2#response.
+ */
+export interface RoomsKeysChainResponsePayload {
+    roomId: string;
+    /**
+     * The earliest epoch the recipient can now derive a key for, having walked the chain it holds. **This is the answer worth having**, and it is not a restatement of what was sent: a rung only extends reach if every rung above it is present too, so a caller that supplied a set with a gap in it learns that here rather than at the first record that will not open. `1` means the room's whole history is reachable.
+     */
+    earliestReadableEpoch: number;
+    /**
+     * How many rungs the recipient did not already hold and kept. Rungs numbered at or below the room's epoch floor are not kept and not counted, and are not an error: a member relaying a mirror's chain may hold some. Zero is a success, not a no-op: it means the caller's chain was already delivered, which is what a retry looks like.
+     */
+    stored?: number;
+    /**
+     * The room's epoch floor the recipient now holds — the highest it has learnt from any source. Absent when it holds none. `earliestReadableEpoch` is never below it.
+     */
+    epochFloor?: EpochFloor;
+    ext?: Ext;
+}
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { EpochFloor, EpochLink, Ext };
+/** Trust Task type URI. */
+export declare const TYPE_URI: "https://trusttasks.org/spec/rooms/keys/chain/0.2";
+/** Stable alias for this specification's request payload shape. */
+export type Payload = RoomsKeysChainPayload;
+/** Trust Task response type URI (request type URI + "#response"). */
+export declare const RESPONSE_TYPE_URI: "https://trusttasks.org/spec/rooms/keys/chain/0.2#response";
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = RoomsKeysChainResponsePayload;
+/**
+ * This specification's payload schema, as a value.
+ *
+ * SPEC.md §7.2 item 2 is performed against this. It is shipped as data
+ * rather than only as a `.json` file because TypeScript types are erased
+ * at runtime: without a schema a consumer has nothing to validate, and
+ * every REQUIRED payload member is optional in practice. Cross-file
+ * `$ref`s are already inlined, so it needs no resolver.
+ */
+export declare const PAYLOAD_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://trusttasks.org/spec/rooms/keys/chain/0.2";
+    readonly title: "Rooms Keys Chain — payload";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["roomId"];
+    readonly properties: {
+        readonly roomId: {
+            readonly type: "string";
+            readonly description: "The room whose chain these rungs belong to. The recipient MUST hold group state for it, and MUST NOT create any on the strength of this request: rungs are inert without an epoch key, so accepting them for a room one is not in would retain key material for nothing.";
+        };
+        readonly links: {
+            readonly type: "array";
+            readonly minItems: 1;
+            readonly description: "The rungs, in any order. A recipient stores those numbered above the room's epoch floor — the higher of the one it holds and `epochFloor` — and reports how far back it can now reach; see the response's `earliestReadableEpoch`. Absent when the request only relays a floor.";
+            readonly items: {
+                readonly $ref: "#/$defs/EpochLink";
+            };
+        };
+        readonly epochFloor: {
+            readonly $ref: "#/$defs/EpochFloor";
+            readonly description: "The room's epoch floor, exactly as the host served it in the `rooms/epoch/chain` 0.2 response the rungs came from. A member relaying rungs MUST relay it when the host served one, and MAY send it alone, with no `links`, to pass on a floor it has just learnt. The recipient applies it as `EpochFloor` requires.";
+        };
+        readonly ext: {
+            readonly $ref: "#/$defs/Ext";
+            readonly description: "Ecosystem-defined extension members per SPEC.md §4.5.1.";
+        };
+    };
+    readonly $defs: {
+        readonly Response: {
+            readonly $anchor: "response";
+            readonly title: "Rooms Keys Chain — response payload";
+            readonly description: "Success response to rooms/keys/chain. Type https://trusttasks.org/spec/rooms/keys/chain/0.2#response.";
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["roomId", "earliestReadableEpoch"];
+            readonly properties: {
+                readonly roomId: {
+                    readonly type: "string";
+                };
+                readonly earliestReadableEpoch: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly description: "The earliest epoch the recipient can now derive a key for, having walked the chain it holds. **This is the answer worth having**, and it is not a restatement of what was sent: a rung only extends reach if every rung above it is present too, so a caller that supplied a set with a gap in it learns that here rather than at the first record that will not open. `1` means the room's whole history is reachable.";
+                };
+                readonly stored: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                    readonly description: "How many rungs the recipient did not already hold and kept. Rungs numbered at or below the room's epoch floor are not kept and not counted, and are not an error: a member relaying a mirror's chain may hold some. Zero is a success, not a no-op: it means the caller's chain was already delivered, which is what a retry looks like.";
+                };
+                readonly epochFloor: {
+                    readonly $ref: "#/$defs/EpochFloor";
+                    readonly description: "The room's epoch floor the recipient now holds — the highest it has learnt from any source. Absent when it holds none. `earliestReadableEpoch` is never below it.";
+                };
+                readonly ext: {
+                    readonly $ref: "#/$defs/Ext";
+                };
+            };
+        };
+        readonly Ext: {
+            readonly title: "Ext";
+            readonly 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.";
+            readonly type: "object";
+            readonly minProperties: 1;
+            readonly additionalProperties: true;
+            readonly propertyNames: {
+                readonly pattern: "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$";
+            };
+        };
+        readonly EpochFloor: {
+            readonly title: "EpochFloor";
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly description: "The earliest epoch whose storage key a room still lets anybody derive: its chain was pruned below it (`rooms/epoch/prune`), and every epoch under it is meant to be unreadable — at the host, and, as far as each of them conforms, at every member's key holder. Absent means the room's chain has never been pruned.\n\n**The off-by-one, stated once.** A rung (`EpochLink`) numbered `e` opens with epoch `e`'s key and yields epoch `e − 1`'s. A prune with `beforeEpoch: N` drops the rungs numbered below `N`, so rung `N` survives and still yields epoch `N − 1`'s key; the floor after it is therefore `N − 1`, never `N`. A party applying a floor `F` discards the rungs numbered `F` and below — rung `F` would yield `F − 1` — and every key for an epoch below `F`.\n\n**Monotonic.** A floor only rises. A host raises the room's to the higher of the floor it held and `beforeEpoch − 1` at each prune it performs, and never lowers it; every other party keeps the highest it has learnt for the room, from any source, and never lowers it either. A lower floor learnt later — from a stale response, or a host that has not been pruned — changes nothing.\n\n**A host** that holds a floor for a room MUST NOT store, accept or serve a rung numbered at or below it, and MUST serve the floor wherever a response can carry it (`rooms/epoch/chain` 0.2, `rooms/epoch/prune` 0.2).\n\n**A member's key holder** — and any client of the member that keeps the room's rungs or keys itself — on learning a floor `F` above the one it held, by any means (`rooms/epoch/chain` 0.2 in its own reads, `rooms/keys/backfill` 0.2, `rooms/keys/chain` 0.2 from its principal):\n  1. MUST discard every rung it holds for the room numbered `F` or below, and every storage key, file key or other key material it holds or has cached for an epoch below `F` — including one it derived in passing while applying commits through those epochs (`rooms/keys/commit`, `rooms/epoch/commits`);\n  2. MUST NOT store such a rung or key again from any source — a delivery from its principal, a backfill, a repair, a catch-up, or a host that has not been pruned — and MUST NOT ask for one;\n  3. MUST refuse to derive or use a key for an epoch below `F`, answering exactly as it answers for an epoch its chain does not reach (`beyondChain`, with an earliest epoch at or above `F`), whatever it still holds;\n  4. MUST keep `F` itself for as long as it holds anything for the room, since it is what makes items 2 and 3 enforceable after the material is gone.\n\nA key holder SHOULD learn the floor whenever it fetches rungs or catches up, and SHOULD ask for it — a `rooms/epoch/chain` 0.2 read carries it whatever `fromEpoch` and `limit` it names — at least as often as it otherwise reads the room. One that never asks never learns, and keeps what it held.\n\n**What a floor does not do, stated plainly.** It is honoured by parties that conform; it does not reach into one that does not, and it recalls nothing. Plaintext a key holder already returned, records a member already opened, files already downloaded and decrypted, exports, and any key a member's own software extracted are beyond it. What it guarantees cryptographically is what the prune guarantees: a party that had not derived a key below the floor before the host erased its rungs can never derive it afterwards. What it adds is that every conforming key holder stops being able to — so that a restart, a new device or an agent's next recall reads nothing below the floor, rather than everything its holder happened to keep.";
+        };
+        readonly EpochLink: {
+            readonly title: "EpochLink";
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["epoch", "wrapped", "nonce"];
+            readonly description: "One rung of a room's epoch key chain: the storage key of epoch `epoch - 1`, sealed under the storage key of `epoch`. A group key schedule offers no way to derive an earlier epoch's key from a later one — that property is what makes removing a member mean something — so without a chain the first membership change makes every record already in the room unopenable by everyone, including whoever wrote it. The chain is the one-way street run deliberately the other way: a member holding the current key walks it backwards to any retained epoch, and a member holding an earlier key still derives nothing later. Removal stays forward-only; reading stays possible. What a chain costs is stated where it is chosen, in the room's retention policy.";
+            readonly properties: {
+                readonly epoch: {
+                    readonly type: "integer";
+                    readonly minimum: 2;
+                    readonly description: "The epoch whose storage key opens this link; it wraps the storage key of `epoch - 1`. Never 1: a room's first epoch has no predecessor, so a link claiming one wraps something that is not an earlier epoch's key.";
+                };
+                readonly wrapped: {
+                    readonly type: "string";
+                    readonly description: "The wrapped predecessor key, base64url. Bound by AEAD associated data to `roomId` and to this link's own position in the chain, so a link lifted to another rung, or served under another room, fails to open rather than yielding a key that is wrong. The binding is load-bearing rather than decorative: every rung is a fixed-length key sealed under a fixed-length key, so nothing about the ciphertext itself says where it belongs.";
+                };
+                readonly nonce: {
+                    readonly type: "string";
+                    readonly description: "AEAD nonce, base64url.";
+                };
+            };
+        };
+    };
+    readonly anyOf: readonly [{
+        readonly required: readonly ["links"];
+    }, {
+        readonly required: readonly ["epochFloor"];
+    }];
+};
+/** As {@link PAYLOAD_SCHEMA}, for the success-response variant. */
+export declare const RESPONSE_PAYLOAD_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $ref: "#/$defs/Response";
+    readonly $defs: {
+        readonly Response: {
+            readonly $anchor: "response";
+            readonly title: "Rooms Keys Chain — response payload";
+            readonly description: "Success response to rooms/keys/chain. Type https://trusttasks.org/spec/rooms/keys/chain/0.2#response.";
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["roomId", "earliestReadableEpoch"];
+            readonly properties: {
+                readonly roomId: {
+                    readonly type: "string";
+                };
+                readonly earliestReadableEpoch: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly description: "The earliest epoch the recipient can now derive a key for, having walked the chain it holds. **This is the answer worth having**, and it is not a restatement of what was sent: a rung only extends reach if every rung above it is present too, so a caller that supplied a set with a gap in it learns that here rather than at the first record that will not open. `1` means the room's whole history is reachable.";
+                };
+                readonly stored: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                    readonly description: "How many rungs the recipient did not already hold and kept. Rungs numbered at or below the room's epoch floor are not kept and not counted, and are not an error: a member relaying a mirror's chain may hold some. Zero is a success, not a no-op: it means the caller's chain was already delivered, which is what a retry looks like.";
+                };
+                readonly epochFloor: {
+                    readonly $ref: "#/$defs/EpochFloor";
+                    readonly description: "The room's epoch floor the recipient now holds — the highest it has learnt from any source. Absent when it holds none. `earliestReadableEpoch` is never below it.";
+                };
+                readonly ext: {
+                    readonly $ref: "#/$defs/Ext";
+                };
+            };
+        };
+        readonly Ext: {
+            readonly title: "Ext";
+            readonly 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.";
+            readonly type: "object";
+            readonly minProperties: 1;
+            readonly additionalProperties: true;
+            readonly propertyNames: {
+                readonly pattern: "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$";
+            };
+        };
+        readonly EpochFloor: {
+            readonly title: "EpochFloor";
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly description: "The earliest epoch whose storage key a room still lets anybody derive: its chain was pruned below it (`rooms/epoch/prune`), and every epoch under it is meant to be unreadable — at the host, and, as far as each of them conforms, at every member's key holder. Absent means the room's chain has never been pruned.\n\n**The off-by-one, stated once.** A rung (`EpochLink`) numbered `e` opens with epoch `e`'s key and yields epoch `e − 1`'s. A prune with `beforeEpoch: N` drops the rungs numbered below `N`, so rung `N` survives and still yields epoch `N − 1`'s key; the floor after it is therefore `N − 1`, never `N`. A party applying a floor `F` discards the rungs numbered `F` and below — rung `F` would yield `F − 1` — and every key for an epoch below `F`.\n\n**Monotonic.** A floor only rises. A host raises the room's to the higher of the floor it held and `beforeEpoch − 1` at each prune it performs, and never lowers it; every other party keeps the highest it has learnt for the room, from any source, and never lowers it either. A lower floor learnt later — from a stale response, or a host that has not been pruned — changes nothing.\n\n**A host** that holds a floor for a room MUST NOT store, accept or serve a rung numbered at or below it, and MUST serve the floor wherever a response can carry it (`rooms/epoch/chain` 0.2, `rooms/epoch/prune` 0.2).\n\n**A member's key holder** — and any client of the member that keeps the room's rungs or keys itself — on learning a floor `F` above the one it held, by any means (`rooms/epoch/chain` 0.2 in its own reads, `rooms/keys/backfill` 0.2, `rooms/keys/chain` 0.2 from its principal):\n  1. MUST discard every rung it holds for the room numbered `F` or below, and every storage key, file key or other key material it holds or has cached for an epoch below `F` — including one it derived in passing while applying commits through those epochs (`rooms/keys/commit`, `rooms/epoch/commits`);\n  2. MUST NOT store such a rung or key again from any source — a delivery from its principal, a backfill, a repair, a catch-up, or a host that has not been pruned — and MUST NOT ask for one;\n  3. MUST refuse to derive or use a key for an epoch below `F`, answering exactly as it answers for an epoch its chain does not reach (`beyondChain`, with an earliest epoch at or above `F`), whatever it still holds;\n  4. MUST keep `F` itself for as long as it holds anything for the room, since it is what makes items 2 and 3 enforceable after the material is gone.\n\nA key holder SHOULD learn the floor whenever it fetches rungs or catches up, and SHOULD ask for it — a `rooms/epoch/chain` 0.2 read carries it whatever `fromEpoch` and `limit` it names — at least as often as it otherwise reads the room. One that never asks never learns, and keeps what it held.\n\n**What a floor does not do, stated plainly.** It is honoured by parties that conform; it does not reach into one that does not, and it recalls nothing. Plaintext a key holder already returned, records a member already opened, files already downloaded and decrypted, exports, and any key a member's own software extracted are beyond it. What it guarantees cryptographically is what the prune guarantees: a party that had not derived a key below the floor before the host erased its rungs can never derive it afterwards. What it adds is that every conforming key holder stops being able to — so that a restart, a new device or an agent's next recall reads nothing below the floor, rather than everything its holder happened to keep.";
+        };
+        readonly EpochLink: {
+            readonly title: "EpochLink";
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["epoch", "wrapped", "nonce"];
+            readonly description: "One rung of a room's epoch key chain: the storage key of epoch `epoch - 1`, sealed under the storage key of `epoch`. A group key schedule offers no way to derive an earlier epoch's key from a later one — that property is what makes removing a member mean something — so without a chain the first membership change makes every record already in the room unopenable by everyone, including whoever wrote it. The chain is the one-way street run deliberately the other way: a member holding the current key walks it backwards to any retained epoch, and a member holding an earlier key still derives nothing later. Removal stays forward-only; reading stays possible. What a chain costs is stated where it is chosen, in the room's retention policy.";
+            readonly properties: {
+                readonly epoch: {
+                    readonly type: "integer";
+                    readonly minimum: 2;
+                    readonly description: "The epoch whose storage key opens this link; it wraps the storage key of `epoch - 1`. Never 1: a room's first epoch has no predecessor, so a link claiming one wraps something that is not an earlier epoch's key.";
+                };
+                readonly wrapped: {
+                    readonly type: "string";
+                    readonly description: "The wrapped predecessor key, base64url. Bound by AEAD associated data to `roomId` and to this link's own position in the chain, so a link lifted to another rung, or served under another room, fails to open rather than yielding a key that is wrong. The binding is load-bearing rather than decorative: every rung is a fixed-length key sealed under a fixed-length key, so nothing about the ciphertext itself says where it belongs.";
+                };
+                readonly nonce: {
+                    readonly type: "string";
+                    readonly description: "AEAD nonce, base64url.";
+                };
+            };
+        };
+    };
+};
+/**
+ * SPEC.md §7.2 policy for the request variant, from this specification's
+ * front matter. Pass to `consumeInbound` — items 5b, 7 and 8 are
+ * per-specification and cannot be derived from the document alone, and
+ * item 2 needs the schema this carries.
+ */
+export declare const SPEC: {
+    readonly typeUri: "https://trusttasks.org/spec/rooms/keys/chain/0.2";
+    readonly isBearer: false;
+    readonly isProofRequired: true;
+    readonly isRecipientRequired: true;
+    readonly isIssuedAtRequired: true;
+    readonly payloadSchema: {
+        readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+        readonly $id: "https://trusttasks.org/spec/rooms/keys/chain/0.2";
+        readonly title: "Rooms Keys Chain — payload";
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["roomId"];
+        readonly properties: {
+            readonly roomId: {
+                readonly type: "string";
+                readonly description: "The room whose chain these rungs belong to. The recipient MUST hold group state for it, and MUST NOT create any on the strength of this request: rungs are inert without an epoch key, so accepting them for a room one is not in would retain key material for nothing.";
+            };
+            readonly links: {
+                readonly type: "array";
+                readonly minItems: 1;
+                readonly description: "The rungs, in any order. A recipient stores those numbered above the room's epoch floor — the higher of the one it holds and `epochFloor` — and reports how far back it can now reach; see the response's `earliestReadableEpoch`. Absent when the request only relays a floor.";
+                readonly items: {
+                    readonly $ref: "#/$defs/EpochLink";
+                };
+            };
+            readonly epochFloor: {
+                readonly $ref: "#/$defs/EpochFloor";
+                readonly description: "The room's epoch floor, exactly as the host served it in the `rooms/epoch/chain` 0.2 response the rungs came from. A member relaying rungs MUST relay it when the host served one, and MAY send it alone, with no `links`, to pass on a floor it has just learnt. The recipient applies it as `EpochFloor` requires.";
+            };
+            readonly ext: {
+                readonly $ref: "#/$defs/Ext";
+                readonly description: "Ecosystem-defined extension members per SPEC.md §4.5.1.";
+            };
+        };
+        readonly $defs: {
+            readonly Response: {
+                readonly $anchor: "response";
+                readonly title: "Rooms Keys Chain — response payload";
+                readonly description: "Success response to rooms/keys/chain. Type https://trusttasks.org/spec/rooms/keys/chain/0.2#response.";
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["roomId", "earliestReadableEpoch"];
+                readonly properties: {
+                    readonly roomId: {
+                        readonly type: "string";
+                    };
+                    readonly earliestReadableEpoch: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                        readonly description: "The earliest epoch the recipient can now derive a key for, having walked the chain it holds. **This is the answer worth having**, and it is not a restatement of what was sent: a rung only extends reach if every rung above it is present too, so a caller that supplied a set with a gap in it learns that here rather than at the first record that will not open. `1` means the room's whole history is reachable.";
+                    };
+                    readonly stored: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                        readonly description: "How many rungs the recipient did not already hold and kept. Rungs numbered at or below the room's epoch floor are not kept and not counted, and are not an error: a member relaying a mirror's chain may hold some. Zero is a success, not a no-op: it means the caller's chain was already delivered, which is what a retry looks like.";
+                    };
+                    readonly epochFloor: {
+                        readonly $ref: "#/$defs/EpochFloor";
+                        readonly description: "The room's epoch floor the recipient now holds — the highest it has learnt from any source. Absent when it holds none. `earliestReadableEpoch` is never below it.";
+                    };
+                    readonly ext: {
+                        readonly $ref: "#/$defs/Ext";
+                    };
+                };
+            };
+            readonly Ext: {
+                readonly title: "Ext";
+                readonly 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.";
+                readonly type: "object";
+                readonly minProperties: 1;
+                readonly additionalProperties: true;
+                readonly propertyNames: {
+                    readonly pattern: "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$";
+                };
+            };
+            readonly EpochFloor: {
+                readonly title: "EpochFloor";
+                readonly type: "integer";
+                readonly minimum: 1;
+                readonly description: "The earliest epoch whose storage key a room still lets anybody derive: its chain was pruned below it (`rooms/epoch/prune`), and every epoch under it is meant to be unreadable — at the host, and, as far as each of them conforms, at every member's key holder. Absent means the room's chain has never been pruned.\n\n**The off-by-one, stated once.** A rung (`EpochLink`) numbered `e` opens with epoch `e`'s key and yields epoch `e − 1`'s. A prune with `beforeEpoch: N` drops the rungs numbered below `N`, so rung `N` survives and still yields epoch `N − 1`'s key; the floor after it is therefore `N − 1`, never `N`. A party applying a floor `F` discards the rungs numbered `F` and below — rung `F` would yield `F − 1` — and every key for an epoch below `F`.\n\n**Monotonic.** A floor only rises. A host raises the room's to the higher of the floor it held and `beforeEpoch − 1` at each prune it performs, and never lowers it; every other party keeps the highest it has learnt for the room, from any source, and never lowers it either. A lower floor learnt later — from a stale response, or a host that has not been pruned — changes nothing.\n\n**A host** that holds a floor for a room MUST NOT store, accept or serve a rung numbered at or below it, and MUST serve the floor wherever a response can carry it (`rooms/epoch/chain` 0.2, `rooms/epoch/prune` 0.2).\n\n**A member's key holder** — and any client of the member that keeps the room's rungs or keys itself — on learning a floor `F` above the one it held, by any means (`rooms/epoch/chain` 0.2 in its own reads, `rooms/keys/backfill` 0.2, `rooms/keys/chain` 0.2 from its principal):\n  1. MUST discard every rung it holds for the room numbered `F` or below, and every storage key, file key or other key material it holds or has cached for an epoch below `F` — including one it derived in passing while applying commits through those epochs (`rooms/keys/commit`, `rooms/epoch/commits`);\n  2. MUST NOT store such a rung or key again from any source — a delivery from its principal, a backfill, a repair, a catch-up, or a host that has not been pruned — and MUST NOT ask for one;\n  3. MUST refuse to derive or use a key for an epoch below `F`, answering exactly as it answers for an epoch its chain does not reach (`beyondChain`, with an earliest epoch at or above `F`), whatever it still holds;\n  4. MUST keep `F` itself for as long as it holds anything for the room, since it is what makes items 2 and 3 enforceable after the material is gone.\n\nA key holder SHOULD learn the floor whenever it fetches rungs or catches up, and SHOULD ask for it — a `rooms/epoch/chain` 0.2 read carries it whatever `fromEpoch` and `limit` it names — at least as often as it otherwise reads the room. One that never asks never learns, and keeps what it held.\n\n**What a floor does not do, stated plainly.** It is honoured by parties that conform; it does not reach into one that does not, and it recalls nothing. Plaintext a key holder already returned, records a member already opened, files already downloaded and decrypted, exports, and any key a member's own software extracted are beyond it. What it guarantees cryptographically is what the prune guarantees: a party that had not derived a key below the floor before the host erased its rungs can never derive it afterwards. What it adds is that every conforming key holder stops being able to — so that a restart, a new device or an agent's next recall reads nothing below the floor, rather than everything its holder happened to keep.";
+            };
+            readonly EpochLink: {
+                readonly title: "EpochLink";
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["epoch", "wrapped", "nonce"];
+                readonly description: "One rung of a room's epoch key chain: the storage key of epoch `epoch - 1`, sealed under the storage key of `epoch`. A group key schedule offers no way to derive an earlier epoch's key from a later one — that property is what makes removing a member mean something — so without a chain the first membership change makes every record already in the room unopenable by everyone, including whoever wrote it. The chain is the one-way street run deliberately the other way: a member holding the current key walks it backwards to any retained epoch, and a member holding an earlier key still derives nothing later. Removal stays forward-only; reading stays possible. What a chain costs is stated where it is chosen, in the room's retention policy.";
+                readonly properties: {
+                    readonly epoch: {
+                        readonly type: "integer";
+                        readonly minimum: 2;
+                        readonly description: "The epoch whose storage key opens this link; it wraps the storage key of `epoch - 1`. Never 1: a room's first epoch has no predecessor, so a link claiming one wraps something that is not an earlier epoch's key.";
+                    };
+                    readonly wrapped: {
+                        readonly type: "string";
+                        readonly description: "The wrapped predecessor key, base64url. Bound by AEAD associated data to `roomId` and to this link's own position in the chain, so a link lifted to another rung, or served under another room, fails to open rather than yielding a key that is wrong. The binding is load-bearing rather than decorative: every rung is a fixed-length key sealed under a fixed-length key, so nothing about the ciphertext itself says where it belongs.";
+                    };
+                    readonly nonce: {
+                        readonly type: "string";
+                        readonly description: "AEAD nonce, base64url.";
+                    };
+                };
+            };
+        };
+        readonly anyOf: readonly [{
+            readonly required: readonly ["links"];
+        }, {
+            readonly required: readonly ["epochFloor"];
+        }];
+    };
+};
+/**
+ * SPEC.md §7.2 policy for the success-response variant. `isRecipientRequired`
+ * tracks the *issuer* party's requirement because a response swaps the
+ * parties (§7.3 item 5).
+ */
+export declare const RESPONSE_SPEC: {
+    readonly typeUri: "https://trusttasks.org/spec/rooms/keys/chain/0.2#response";
+    readonly isBearer: false;
+    readonly isProofRequired: true;
+    readonly isRecipientRequired: true;
+    readonly isIssuedAtRequired: true;
+    readonly payloadSchema: {
+        readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+        readonly $ref: "#/$defs/Response";
+        readonly $defs: {
+            readonly Response: {
+                readonly $anchor: "response";
+                readonly title: "Rooms Keys Chain — response payload";
+                readonly description: "Success response to rooms/keys/chain. Type https://trusttasks.org/spec/rooms/keys/chain/0.2#response.";
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["roomId", "earliestReadableEpoch"];
+                readonly properties: {
+                    readonly roomId: {
+                        readonly type: "string";
+                    };
+                    readonly earliestReadableEpoch: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                        readonly description: "The earliest epoch the recipient can now derive a key for, having walked the chain it holds. **This is the answer worth having**, and it is not a restatement of what was sent: a rung only extends reach if every rung above it is present too, so a caller that supplied a set with a gap in it learns that here rather than at the first record that will not open. `1` means the room's whole history is reachable.";
+                    };
+                    readonly stored: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                        readonly description: "How many rungs the recipient did not already hold and kept. Rungs numbered at or below the room's epoch floor are not kept and not counted, and are not an error: a member relaying a mirror's chain may hold some. Zero is a success, not a no-op: it means the caller's chain was already delivered, which is what a retry looks like.";
+                    };
+                    readonly epochFloor: {
+                        readonly $ref: "#/$defs/EpochFloor";
+                        readonly description: "The room's epoch floor the recipient now holds — the highest it has learnt from any source. Absent when it holds none. `earliestReadableEpoch` is never below it.";
+                    };
+                    readonly ext: {
+                        readonly $ref: "#/$defs/Ext";
+                    };
+                };
+            };
+            readonly Ext: {
+                readonly title: "Ext";
+                readonly 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.";
+                readonly type: "object";
+                readonly minProperties: 1;
+                readonly additionalProperties: true;
+                readonly propertyNames: {
+                    readonly pattern: "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$";
+                };
+            };
+            readonly EpochFloor: {
+                readonly title: "EpochFloor";
+                readonly type: "integer";
+                readonly minimum: 1;
+                readonly description: "The earliest epoch whose storage key a room still lets anybody derive: its chain was pruned below it (`rooms/epoch/prune`), and every epoch under it is meant to be unreadable — at the host, and, as far as each of them conforms, at every member's key holder. Absent means the room's chain has never been pruned.\n\n**The off-by-one, stated once.** A rung (`EpochLink`) numbered `e` opens with epoch `e`'s key and yields epoch `e − 1`'s. A prune with `beforeEpoch: N` drops the rungs numbered below `N`, so rung `N` survives and still yields epoch `N − 1`'s key; the floor after it is therefore `N − 1`, never `N`. A party applying a floor `F` discards the rungs numbered `F` and below — rung `F` would yield `F − 1` — and every key for an epoch below `F`.\n\n**Monotonic.** A floor only rises. A host raises the room's to the higher of the floor it held and `beforeEpoch − 1` at each prune it performs, and never lowers it; every other party keeps the highest it has learnt for the room, from any source, and never lowers it either. A lower floor learnt later — from a stale response, or a host that has not been pruned — changes nothing.\n\n**A host** that holds a floor for a room MUST NOT store, accept or serve a rung numbered at or below it, and MUST serve the floor wherever a response can carry it (`rooms/epoch/chain` 0.2, `rooms/epoch/prune` 0.2).\n\n**A member's key holder** — and any client of the member that keeps the room's rungs or keys itself — on learning a floor `F` above the one it held, by any means (`rooms/epoch/chain` 0.2 in its own reads, `rooms/keys/backfill` 0.2, `rooms/keys/chain` 0.2 from its principal):\n  1. MUST discard every rung it holds for the room numbered `F` or below, and every storage key, file key or other key material it holds or has cached for an epoch below `F` — including one it derived in passing while applying commits through those epochs (`rooms/keys/commit`, `rooms/epoch/commits`);\n  2. MUST NOT store such a rung or key again from any source — a delivery from its principal, a backfill, a repair, a catch-up, or a host that has not been pruned — and MUST NOT ask for one;\n  3. MUST refuse to derive or use a key for an epoch below `F`, answering exactly as it answers for an epoch its chain does not reach (`beyondChain`, with an earliest epoch at or above `F`), whatever it still holds;\n  4. MUST keep `F` itself for as long as it holds anything for the room, since it is what makes items 2 and 3 enforceable after the material is gone.\n\nA key holder SHOULD learn the floor whenever it fetches rungs or catches up, and SHOULD ask for it — a `rooms/epoch/chain` 0.2 read carries it whatever `fromEpoch` and `limit` it names — at least as often as it otherwise reads the room. One that never asks never learns, and keeps what it held.\n\n**What a floor does not do, stated plainly.** It is honoured by parties that conform; it does not reach into one that does not, and it recalls nothing. Plaintext a key holder already returned, records a member already opened, files already downloaded and decrypted, exports, and any key a member's own software extracted are beyond it. What it guarantees cryptographically is what the prune guarantees: a party that had not derived a key below the floor before the host erased its rungs can never derive it afterwards. What it adds is that every conforming key holder stops being able to — so that a restart, a new device or an agent's next recall reads nothing below the floor, rather than everything its holder happened to keep.";
+            };
+            readonly EpochLink: {
+                readonly title: "EpochLink";
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["epoch", "wrapped", "nonce"];
+                readonly description: "One rung of a room's epoch key chain: the storage key of epoch `epoch - 1`, sealed under the storage key of `epoch`. A group key schedule offers no way to derive an earlier epoch's key from a later one — that property is what makes removing a member mean something — so without a chain the first membership change makes every record already in the room unopenable by everyone, including whoever wrote it. The chain is the one-way street run deliberately the other way: a member holding the current key walks it backwards to any retained epoch, and a member holding an earlier key still derives nothing later. Removal stays forward-only; reading stays possible. What a chain costs is stated where it is chosen, in the room's retention policy.";
+                readonly properties: {
+                    readonly epoch: {
+                        readonly type: "integer";
+                        readonly minimum: 2;
+                        readonly description: "The epoch whose storage key opens this link; it wraps the storage key of `epoch - 1`. Never 1: a room's first epoch has no predecessor, so a link claiming one wraps something that is not an earlier epoch's key.";
+                    };
+                    readonly wrapped: {
+                        readonly type: "string";
+                        readonly description: "The wrapped predecessor key, base64url. Bound by AEAD associated data to `roomId` and to this link's own position in the chain, so a link lifted to another rung, or served under another room, fails to open rather than yielding a key that is wrong. The binding is load-bearing rather than decorative: every rung is a fixed-length key sealed under a fixed-length key, so nothing about the ciphertext itself says where it belongs.";
+                    };
+                    readonly nonce: {
+                        readonly type: "string";
+                        readonly description: "AEAD nonce, base64url.";
+                    };
+                };
+            };
+        };
+    };
+};
+//# sourceMappingURL=payload.d.ts.map

package/dist/rooms/keys/chain/0.2/payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../../../../src/rooms/keys/chain/0.2/payload.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,mCAAmC,CAAC;AAGpF,MAAM,MAAM,qBAAqB,GAAG;IAClC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CAClC,GAAG;IACF;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;IACpC;;OAEG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;;OAEG;IACH,GAAG,CAAC,EAAE,GAAG,CAAC;CACX,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,qBAAqB,EAAE,MAAM,CAAC;IAC9B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,GAAG,CAAC,EAAE,GAAG,CAAC;CACX;AAED,kHAAkH;AAClH,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC;AAE3C,2BAA2B;AAC3B,eAAO,MAAM,QAAQ,EAAG,kDAA2D,CAAC;AAEpF,mEAAmE;AACnE,MAAM,MAAM,OAAO,GAAG,qBAAqB,CAAC;AAE5C,qEAAqE;AACrE,eAAO,MAAM,iBAAiB,EAAG,2DAAoE,CAAC;AAEtG,4EAA4E;AAC5E,MAAM,MAAM,QAAQ,GAAG,6BAA6B,CAAC;AAErD;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwHjB,CAAC;AAEX,mEAAmE;AACnE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgF1B,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAOP,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAOhB,CAAC"}