@openvtc/trust-tasks 0.28.14 → 0.28.15

package/src/rooms/records/put/0.1/payload.ts

@@ -6,7 +6,7 @@
 import type { AuthorityPresentation, Ext, SealedRecord } from "../../../../_shared/components.js";
 
 
-/** @deprecated superseded by rooms/records/put/0.4 */
+/** @deprecated superseded by rooms/records/put/0.5 */
 export interface RoomsRecordsPutPayload {
   /**
    * The room's identifier. A host verifies the presentation against credentials issued by this identifier, never against a member list of its own — which is what lets a room move hosts without reissuing a credential.
@@ -48,7 +48,7 @@ export interface RoomsRecordsPutPayload {
 /**
  * Success response to rooms/records/put. Type https://trusttasks.org/spec/rooms/records/put/0.1#response.
  *
- * @deprecated superseded by rooms/records/put/0.4
+ * @deprecated superseded by rooms/records/put/0.5
  */
 export interface RoomsRecordsPutResponsePayload {
   /**
@@ -86,12 +86,12 @@ export const EXTENDS: string | null = null;
  * this package in a later scheduled batch (SPEC "Superseded and Withdrawn
  * Versions").
  */
-export const DEPRECATION: string | null = "superseded by rooms/records/put/0.4";
+export const DEPRECATION: string | null = "superseded by rooms/records/put/0.5";
 
 /**
  * Stable alias for this specification's request payload shape.
  *
- * @deprecated superseded by rooms/records/put/0.4
+ * @deprecated superseded by rooms/records/put/0.5
  */
 export type Payload = RoomsRecordsPutPayload;
 
@@ -101,7 +101,7 @@ export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/rooms/records/put/
 /**
  * Stable alias for this specification's success-response payload shape.
  *
- * @deprecated superseded by rooms/records/put/0.4
+ * @deprecated superseded by rooms/records/put/0.5
  */
 export type Response = RoomsRecordsPutResponsePayload;
 

package/src/rooms/records/put/0.2/payload.ts

@@ -9,7 +9,7 @@ import type { AuthorityPresentation, BlobRef, DigestMultibase, Ext, SealedRecord
 /**
  * A member writes a record to a data room, authorized by an authority chain the room itself issued. 0.2 adds `blobs`: a record can carry a file, whose ciphertext the host stores outside the record and whose description is sealed inside it.
  *
- * @deprecated superseded by rooms/records/put/0.4
+ * @deprecated superseded by rooms/records/put/0.5
  */
 export interface RoomsRecordsPutPayload {
   /**
@@ -59,7 +59,7 @@ export interface RoomsRecordsPutPayload {
 /**
  * Success response to rooms/records/put. Type https://trusttasks.org/spec/rooms/records/put/0.2#response.
  *
- * @deprecated superseded by rooms/records/put/0.4
+ * @deprecated superseded by rooms/records/put/0.5
  */
 export interface RoomsRecordsPutResponsePayload {
   /**
@@ -97,12 +97,12 @@ export const EXTENDS: string | null = null;
  * this package in a later scheduled batch (SPEC "Superseded and Withdrawn
  * Versions").
  */
-export const DEPRECATION: string | null = "superseded by rooms/records/put/0.4";
+export const DEPRECATION: string | null = "superseded by rooms/records/put/0.5";
 
 /**
  * Stable alias for this specification's request payload shape.
  *
- * @deprecated superseded by rooms/records/put/0.4
+ * @deprecated superseded by rooms/records/put/0.5
  */
 export type Payload = RoomsRecordsPutPayload;
 
@@ -112,7 +112,7 @@ export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/rooms/records/put/
 /**
  * Stable alias for this specification's success-response payload shape.
  *
- * @deprecated superseded by rooms/records/put/0.4
+ * @deprecated superseded by rooms/records/put/0.5
  */
 export type Response = RoomsRecordsPutResponsePayload;
 

package/src/rooms/records/put/0.3/payload.ts

@@ -9,7 +9,7 @@ import type { AuthorityPresentation, BlobRef, DigestMultibase, Ext, PermittedUse
 /**
  * A member writes a record to a data room, authorized by an authority chain the room itself issued. 0.2 added `blobs`: a record can carry a file, whose ciphertext the host stores outside the record and whose description is sealed inside it. 0.3 lets an `open` room's `cleartext` carry the record's provenance — `basis`, `confidence`, `evidence`, `validFor` — and its `validUntil`, which the sealed tiers carry inside the signed `SealedRecordBody`.
  *
- * @deprecated superseded by rooms/records/put/0.4
+ * @deprecated superseded by rooms/records/put/0.5
  */
 export interface RoomsRecordsPutPayload {
   /**
@@ -70,7 +70,7 @@ export interface RoomsRecordsPutPayload {
 /**
  * Success response to rooms/records/put. Type https://trusttasks.org/spec/rooms/records/put/0.3#response.
  *
- * @deprecated superseded by rooms/records/put/0.4
+ * @deprecated superseded by rooms/records/put/0.5
  */
 export interface RoomsRecordsPutResponsePayload {
   /**
@@ -108,12 +108,12 @@ export const EXTENDS: string | null = null;
  * this package in a later scheduled batch (SPEC "Superseded and Withdrawn
  * Versions").
  */
-export const DEPRECATION: string | null = "superseded by rooms/records/put/0.4";
+export const DEPRECATION: string | null = "superseded by rooms/records/put/0.5";
 
 /**
  * Stable alias for this specification's request payload shape.
  *
- * @deprecated superseded by rooms/records/put/0.4
+ * @deprecated superseded by rooms/records/put/0.5
  */
 export type Payload = RoomsRecordsPutPayload;
 
@@ -123,7 +123,7 @@ export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/rooms/records/put/
 /**
  * Stable alias for this specification's success-response payload shape.
  *
- * @deprecated superseded by rooms/records/put/0.4
+ * @deprecated superseded by rooms/records/put/0.5
  */
 export type Response = RoomsRecordsPutResponsePayload;
 

package/src/rooms/records/put/0.4/payload.ts

@@ -8,6 +8,8 @@ import type { AuthorityPresentation, BlobRef, DigestMultibase, Ext, FileManifest
 
 /**
  * A member writes a record to a data room, authorized by an authority chain the room itself issued. 0.2 added `blobs`: a record can carry a file, whose ciphertext the host stores outside the record and whose description is sealed inside it. 0.3 lets an `open` room's `cleartext` carry the record's provenance — `basis`, `confidence`, `evidence`, `validFor` — and its `validUntil`, which the sealed tiers carry inside the signed `SealedRecordBody`. 0.4 lets an `open` room's record carry a file: its `FileManifest`, with the file key it was sealed under, in `cleartext.file`.
+ *
+ * @deprecated superseded by rooms/records/put/0.5
  */
 export interface RoomsRecordsPutPayload {
   /**
@@ -71,6 +73,8 @@ export interface RoomsRecordsPutPayload {
 }
 /**
  * Success response to rooms/records/put. Type https://trusttasks.org/spec/rooms/records/put/0.3#response.
+ *
+ * @deprecated superseded by rooms/records/put/0.5
  */
 export interface RoomsRecordsPutResponsePayload {
   /**
@@ -108,15 +112,23 @@ export const EXTENDS: string | null = "0.3";
  * this package in a later scheduled batch (SPEC "Superseded and Withdrawn
  * Versions").
  */
-export const DEPRECATION: string | null = null;
+export const DEPRECATION: string | null = "superseded by rooms/records/put/0.5";
 
-/** Stable alias for this specification's request payload shape. */
+/**
+ * Stable alias for this specification's request payload shape.
+ *
+ * @deprecated superseded by rooms/records/put/0.5
+ */
 export type Payload = RoomsRecordsPutPayload;
 
 /** Trust Task response type URI (request type URI + "#response"). */
 export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/rooms/records/put/0.4#response" as const;
 
-/** Stable alias for this specification's success-response payload shape. */
+/**
+ * Stable alias for this specification's success-response payload shape.
+ *
+ * @deprecated superseded by rooms/records/put/0.5
+ */
 export type Response = RoomsRecordsPutResponsePayload;
 
 /**
@@ -299,7 +311,7 @@ export const PAYLOAD_SCHEMA = {
         "segmentSize",
         "blobRef"
       ],
-      "description": "Everything that describes a file. On an `attributed` or `private` room it is the `file` member of the sealed record body: sealed with the record, signed by the record's author, and never seen by the host. On an `open` room it is the `file` member of the record's `cleartext` (rooms/records/put/0.4), carrying its own `fileKey`, and the host reads it like the rest of the record. Defined here so that clients interoperate.\n\n**Byte encodings.** In every derivation below, `fileId` is its **32 decoded bytes**, never its base64url text; `roomId` is the **UTF-8 bytes** of the room identifier exactly as it appears on the wire; string constants are their ASCII bytes; `u8`, `u32be` and `u64be` are unsigned integers of that width, big-endian. Epochs are unsigned 64-bit on the wire. An implementation that holds epochs in a narrower type **MUST** refuse a value it cannot represent with `malformedRequest` (or, reading a manifest, refuse the file), and **MUST NOT** truncate it.\n\n**The file key.** `file_key = HKDF-SHA256(ikm = storage_key(epoch), salt = fileId, info = \"openvtc/room/file/v1\" || roomId || u64be(epoch))`, where `storage_key(epoch)` is the room's per-epoch storage key, the one records are sealed under. It is derived per file and never stored. It is bound to the room and the epoch, so a key released for one room cannot open a blob relocated from another, and releasing it exposes one file and nothing else.\n\n**The file key on an `open` room.** An open room has no group and so no storage key to derive from. There the uploader mints the file key itself — 32 bytes from a cryptographically secure random source, for this file only — and carries it in `fileKey`; a reader uses that key and derives nothing. Everything else below (padding, STREAM, the associated data, reading) is the same on every tier, with `epoch` the room's epoch when the file was written. `fileKey` **MUST** be present in an open room's manifest and **MUST** be absent from a sealed record body's, where the key is derived; a reader **MUST** refuse a file whose manifest breaks either rule. The key in the clear withholds nothing from the host or from anyone it serves the record to — the open tier withholds nothing from them — but it keeps the stored blob opaque to whoever holds only the storage, and keeps one blob format, and one reader, for every tier.\n\n**Padding.** With `padding: \"padme\"`, the plaintext of length `L = size` is extended with zero bytes to `padme(L)`: for `L < 2`, `padme(L) = L`; otherwise `E = floor(log2 L)`, `S = floor(log2 E) + 1`, `z = E − S`, `mask = 2^z − 1`, and `padme(L) = (L + mask) & ~mask`. The padded length is `padme(size)`; without padding it is `size`. Padding bytes **MUST** be zero.\n\n**The STREAM construction.** The padded plaintext is cut into `segmentSize`-byte segments, the last holding the remainder; an empty plaintext is one empty final segment. Segment `i` is sealed with ChaCha20-Poly1305 under `file_key`, with nonce `u32be(0) || u64be(i)` and associated data `\"openvtc/room/file/v1\" || roomId || fileId || u64be(epoch) || u64be(i) || u8(final)`, where `final` is 1 on the last segment and 0 on every other. A host that truncates, reorders or splices ciphertext produces an authentication failure, never a shorter or rearranged file. The nonces are counters, so a `file_key` MUST NOT seal two different files; a fresh random `fileId` is what guarantees it. Each sealed segment is one transfer chunk of the blob (BlobManifest), so `segmentSize + 16` is the blob's `chunks.chunkSize`, and an empty file is one 16-byte chunk.\n\n**Reading.** A reader opens the record, derives or obtains the file key, and **MUST**, before trusting a byte:\n- check that the blob's `chunks.chunkSize` equals `segmentSize + 16` and that `chunks.chunkCount` equals `max(1, ceil(paddedLength / segmentSize))`, and refuse the file otherwise;\n- decrypt every segment in order, refusing the file on any authentication failure or on a final flag anywhere but the last segment;\n- check that the decrypted length equals the padded length, that every padding byte is zero, and, after removing the padding, that the plaintext matches `digest`.\n\nA reader **MUST** refuse a file that fails any check, and **MUST NOT** present it with a warning instead. A reader that streams **MUST NOT** treat the plaintext as received — save it under its final name, render it, or hand it to another component — until the digest has verified; it writes to a temporary destination and discards that destination on a mismatch.",
+      "description": "Everything that describes a file. On an `attributed` or `private` room it is the `file` member of the sealed record body: sealed with the record, signed by the record's author, and never seen by the host. On an `open` room it is the `file` member of the record's `cleartext` (rooms/records/put/0.4), carrying its own `fileKey`, and the host reads it like the rest of the record. Defined here so that clients interoperate.\n\n**Byte encodings.** In every derivation below, `fileId` is its **32 decoded bytes**, never its base64url text; `roomId` is the **UTF-8 bytes** of the room identifier exactly as it appears on the wire; string constants are their ASCII bytes; `u8`, `u32be` and `u64be` are unsigned integers of that width, big-endian. Epochs are unsigned 64-bit on the wire. An implementation that holds epochs in a narrower type **MUST** refuse a value it cannot represent with `malformedRequest` (or, reading a manifest, refuse the file), and **MUST NOT** truncate it.\n\n**The file key.** `file_key = HKDF-SHA256(ikm = storage_key(epoch), salt = fileId, info = \"openvtc/room/file/v1\" || roomId || u64be(epoch))`, where `storage_key(epoch)` is the room's per-epoch storage key, the one records are sealed under. It is derived per file and never stored. It is bound to the room and the epoch, so a key released for one room cannot open a blob relocated from another, and releasing it exposes one file and nothing else.\n\n**The file key on an `open` room.** An open room has no group and so no storage key to derive from. There the uploader mints the file key itself — 32 bytes from a cryptographically secure random source, for this file only — and carries it in `fileKey`; a reader uses that key and derives nothing. Everything else below (padding, STREAM, the associated data, reading) is the same on every tier, with `epoch` the room's epoch when the file was written. `fileKey` **MUST** be present in an open room's manifest and **MUST** be absent from a sealed record body's, where the key is derived; a reader **MUST** refuse a file whose manifest breaks either rule. The key in the clear withholds nothing from the host or from anyone it serves the record to — the open tier withholds nothing from them — but it keeps the stored blob opaque to whoever holds only the storage, and keeps one blob format, and one reader, for every tier.\n\n**Padding.** With `padding: \"padme\"`, the plaintext of length `L = size` is extended with zero bytes to `padme(L)`: for `L < 2`, `padme(L) = L`; otherwise `E = floor(log2 L)`, `S = floor(log2 E) + 1`, `z = E − S`, `mask = 2^z − 1`, and `padme(L) = (L + mask) & ~mask`. The padded length is `padme(size)`; without padding it is `size`. Padding bytes **MUST** be zero.\n\n**The STREAM construction.** The padded plaintext is cut into `segmentSize`-byte segments, the last holding the remainder; an empty plaintext is one empty final segment. Segment `i` is sealed with ChaCha20-Poly1305 under `file_key`, with nonce `u32be(0) || u64be(i)` and associated data `\"openvtc/room/file/v1\" || roomId || fileId || u64be(epoch) || u64be(i) || u8(final)`, where `final` is 1 on the last segment and 0 on every other. A host that truncates, reorders or splices ciphertext produces an authentication failure, never a shorter or rearranged file. The nonces are counters, so a `file_key` MUST NOT seal two different files; a fresh random `fileId` is what guarantees it. Each sealed segment is one transfer chunk of the blob (BlobManifest), so `segmentSize + 16` is the blob's `chunks.chunkSize`, and an empty file is one 16-byte chunk.\n\n**Reading.** A reader opens the record, derives or obtains the file key, and **MUST**, before trusting a byte:\n- check that the blob's `chunks.chunkSize` equals `segmentSize + 16` and that `chunks.chunkCount` equals `max(1, ceil(paddedLength / segmentSize))`, and refuse the file otherwise;\n- decrypt every segment in order, refusing the file on any authentication failure or on a final flag anywhere but the last segment;\n- check that the decrypted length equals the padded length, that every padding byte is zero, and, after removing the padding, that the plaintext matches `digest`.\n\nA reader **MUST** refuse a file that fails any check, and **MUST NOT** present it with a warning instead. A reader that streams **MUST NOT** treat the plaintext as received — save it under its final name, render it, or hand it to another component — until the digest has verified; it writes to a temporary destination and discards that destination on a mismatch.\n\n**An image's size and preview.** `width`, `height` and `preview` are OPTIONAL and advisory: they let a reader lay out an image, and show something, before it fetches and decrypts the blob. A reader that fetches the file checks them against the bytes — the decoded image's dimensions, and that the file is an image at all — and on a mismatch uses the bytes and discards them; it MUST NOT treat any of them as evidence about the file. On `attributed` and `private` rooms they are inside the sealed, signed body like the rest of the manifest, so the host learns nothing from them; on an `open` room they are in the clear, as everything there is, and a writer carries them only with `rooms/records/put/0.5` or later. A writer uses them only once the room's profile lists them in `recordMembers` (`RoomProfile`), as with the other members a reader that predates them refuses.",
       "properties": {
         "fileId": {
           "type": "string",
@@ -353,6 +365,45 @@ export const PAYLOAD_SCHEMA = {
           "type": "string",
           "pattern": "^[A-Za-z0-9_-]{43}$",
           "description": "The file key itself, 32 bytes base64url without padding: present on an `open` room only, where there is no storage key to derive it from. Minted by the uploader from a cryptographically secure random source for this one file and never reused. MUST be absent on `attributed` and `private` rooms, where the key is derived and never stored."
+        },
+        "width": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1048576,
+          "description": "The image's width in pixels, as the uploader read it. Advisory. A writer sets `width` and `height` together or neither; a reader ignores one without the other. A reader checks it against the decoded image."
+        },
+        "height": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1048576,
+          "description": "The image's height in pixels, as the uploader read it. Advisory. A writer sets `width` and `height` together or neither; a reader ignores one without the other. A reader checks it against the decoded image."
+        },
+        "preview": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "mediaType",
+            "data"
+          ],
+          "description": "A small image standing in for the file until it is fetched: at most 8192 bytes before encoding, enough for a blurred thumbnail and small enough not to swell the record every listing reader opens. A reader renders it only as a raster image it decodes itself — never as SVG or any other type that can carry active content, never as a link, never fetching anything — and replaces it with the file once fetched. It is the uploader's rendering of the file, not a digest of it: a reader MUST NOT present it as the file's contents.",
+          "properties": {
+            "mediaType": {
+              "type": "string",
+              "enum": [
+                "image/jpeg",
+                "image/png",
+                "image/webp"
+              ],
+              "description": "The preview's own media type. Raster types only."
+            },
+            "data": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9_-]+$",
+              "minLength": 1,
+              "maxLength": 10923,
+              "description": "The preview's bytes, base64url without padding: at most 8192 bytes decoded."
+            }
+          }
         }
       }
     },
@@ -624,7 +675,7 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
         "segmentSize",
         "blobRef"
       ],
-      "description": "Everything that describes a file. On an `attributed` or `private` room it is the `file` member of the sealed record body: sealed with the record, signed by the record's author, and never seen by the host. On an `open` room it is the `file` member of the record's `cleartext` (rooms/records/put/0.4), carrying its own `fileKey`, and the host reads it like the rest of the record. Defined here so that clients interoperate.\n\n**Byte encodings.** In every derivation below, `fileId` is its **32 decoded bytes**, never its base64url text; `roomId` is the **UTF-8 bytes** of the room identifier exactly as it appears on the wire; string constants are their ASCII bytes; `u8`, `u32be` and `u64be` are unsigned integers of that width, big-endian. Epochs are unsigned 64-bit on the wire. An implementation that holds epochs in a narrower type **MUST** refuse a value it cannot represent with `malformedRequest` (or, reading a manifest, refuse the file), and **MUST NOT** truncate it.\n\n**The file key.** `file_key = HKDF-SHA256(ikm = storage_key(epoch), salt = fileId, info = \"openvtc/room/file/v1\" || roomId || u64be(epoch))`, where `storage_key(epoch)` is the room's per-epoch storage key, the one records are sealed under. It is derived per file and never stored. It is bound to the room and the epoch, so a key released for one room cannot open a blob relocated from another, and releasing it exposes one file and nothing else.\n\n**The file key on an `open` room.** An open room has no group and so no storage key to derive from. There the uploader mints the file key itself — 32 bytes from a cryptographically secure random source, for this file only — and carries it in `fileKey`; a reader uses that key and derives nothing. Everything else below (padding, STREAM, the associated data, reading) is the same on every tier, with `epoch` the room's epoch when the file was written. `fileKey` **MUST** be present in an open room's manifest and **MUST** be absent from a sealed record body's, where the key is derived; a reader **MUST** refuse a file whose manifest breaks either rule. The key in the clear withholds nothing from the host or from anyone it serves the record to — the open tier withholds nothing from them — but it keeps the stored blob opaque to whoever holds only the storage, and keeps one blob format, and one reader, for every tier.\n\n**Padding.** With `padding: \"padme\"`, the plaintext of length `L = size` is extended with zero bytes to `padme(L)`: for `L < 2`, `padme(L) = L`; otherwise `E = floor(log2 L)`, `S = floor(log2 E) + 1`, `z = E − S`, `mask = 2^z − 1`, and `padme(L) = (L + mask) & ~mask`. The padded length is `padme(size)`; without padding it is `size`. Padding bytes **MUST** be zero.\n\n**The STREAM construction.** The padded plaintext is cut into `segmentSize`-byte segments, the last holding the remainder; an empty plaintext is one empty final segment. Segment `i` is sealed with ChaCha20-Poly1305 under `file_key`, with nonce `u32be(0) || u64be(i)` and associated data `\"openvtc/room/file/v1\" || roomId || fileId || u64be(epoch) || u64be(i) || u8(final)`, where `final` is 1 on the last segment and 0 on every other. A host that truncates, reorders or splices ciphertext produces an authentication failure, never a shorter or rearranged file. The nonces are counters, so a `file_key` MUST NOT seal two different files; a fresh random `fileId` is what guarantees it. Each sealed segment is one transfer chunk of the blob (BlobManifest), so `segmentSize + 16` is the blob's `chunks.chunkSize`, and an empty file is one 16-byte chunk.\n\n**Reading.** A reader opens the record, derives or obtains the file key, and **MUST**, before trusting a byte:\n- check that the blob's `chunks.chunkSize` equals `segmentSize + 16` and that `chunks.chunkCount` equals `max(1, ceil(paddedLength / segmentSize))`, and refuse the file otherwise;\n- decrypt every segment in order, refusing the file on any authentication failure or on a final flag anywhere but the last segment;\n- check that the decrypted length equals the padded length, that every padding byte is zero, and, after removing the padding, that the plaintext matches `digest`.\n\nA reader **MUST** refuse a file that fails any check, and **MUST NOT** present it with a warning instead. A reader that streams **MUST NOT** treat the plaintext as received — save it under its final name, render it, or hand it to another component — until the digest has verified; it writes to a temporary destination and discards that destination on a mismatch.",
+      "description": "Everything that describes a file. On an `attributed` or `private` room it is the `file` member of the sealed record body: sealed with the record, signed by the record's author, and never seen by the host. On an `open` room it is the `file` member of the record's `cleartext` (rooms/records/put/0.4), carrying its own `fileKey`, and the host reads it like the rest of the record. Defined here so that clients interoperate.\n\n**Byte encodings.** In every derivation below, `fileId` is its **32 decoded bytes**, never its base64url text; `roomId` is the **UTF-8 bytes** of the room identifier exactly as it appears on the wire; string constants are their ASCII bytes; `u8`, `u32be` and `u64be` are unsigned integers of that width, big-endian. Epochs are unsigned 64-bit on the wire. An implementation that holds epochs in a narrower type **MUST** refuse a value it cannot represent with `malformedRequest` (or, reading a manifest, refuse the file), and **MUST NOT** truncate it.\n\n**The file key.** `file_key = HKDF-SHA256(ikm = storage_key(epoch), salt = fileId, info = \"openvtc/room/file/v1\" || roomId || u64be(epoch))`, where `storage_key(epoch)` is the room's per-epoch storage key, the one records are sealed under. It is derived per file and never stored. It is bound to the room and the epoch, so a key released for one room cannot open a blob relocated from another, and releasing it exposes one file and nothing else.\n\n**The file key on an `open` room.** An open room has no group and so no storage key to derive from. There the uploader mints the file key itself — 32 bytes from a cryptographically secure random source, for this file only — and carries it in `fileKey`; a reader uses that key and derives nothing. Everything else below (padding, STREAM, the associated data, reading) is the same on every tier, with `epoch` the room's epoch when the file was written. `fileKey` **MUST** be present in an open room's manifest and **MUST** be absent from a sealed record body's, where the key is derived; a reader **MUST** refuse a file whose manifest breaks either rule. The key in the clear withholds nothing from the host or from anyone it serves the record to — the open tier withholds nothing from them — but it keeps the stored blob opaque to whoever holds only the storage, and keeps one blob format, and one reader, for every tier.\n\n**Padding.** With `padding: \"padme\"`, the plaintext of length `L = size` is extended with zero bytes to `padme(L)`: for `L < 2`, `padme(L) = L`; otherwise `E = floor(log2 L)`, `S = floor(log2 E) + 1`, `z = E − S`, `mask = 2^z − 1`, and `padme(L) = (L + mask) & ~mask`. The padded length is `padme(size)`; without padding it is `size`. Padding bytes **MUST** be zero.\n\n**The STREAM construction.** The padded plaintext is cut into `segmentSize`-byte segments, the last holding the remainder; an empty plaintext is one empty final segment. Segment `i` is sealed with ChaCha20-Poly1305 under `file_key`, with nonce `u32be(0) || u64be(i)` and associated data `\"openvtc/room/file/v1\" || roomId || fileId || u64be(epoch) || u64be(i) || u8(final)`, where `final` is 1 on the last segment and 0 on every other. A host that truncates, reorders or splices ciphertext produces an authentication failure, never a shorter or rearranged file. The nonces are counters, so a `file_key` MUST NOT seal two different files; a fresh random `fileId` is what guarantees it. Each sealed segment is one transfer chunk of the blob (BlobManifest), so `segmentSize + 16` is the blob's `chunks.chunkSize`, and an empty file is one 16-byte chunk.\n\n**Reading.** A reader opens the record, derives or obtains the file key, and **MUST**, before trusting a byte:\n- check that the blob's `chunks.chunkSize` equals `segmentSize + 16` and that `chunks.chunkCount` equals `max(1, ceil(paddedLength / segmentSize))`, and refuse the file otherwise;\n- decrypt every segment in order, refusing the file on any authentication failure or on a final flag anywhere but the last segment;\n- check that the decrypted length equals the padded length, that every padding byte is zero, and, after removing the padding, that the plaintext matches `digest`.\n\nA reader **MUST** refuse a file that fails any check, and **MUST NOT** present it with a warning instead. A reader that streams **MUST NOT** treat the plaintext as received — save it under its final name, render it, or hand it to another component — until the digest has verified; it writes to a temporary destination and discards that destination on a mismatch.\n\n**An image's size and preview.** `width`, `height` and `preview` are OPTIONAL and advisory: they let a reader lay out an image, and show something, before it fetches and decrypts the blob. A reader that fetches the file checks them against the bytes — the decoded image's dimensions, and that the file is an image at all — and on a mismatch uses the bytes and discards them; it MUST NOT treat any of them as evidence about the file. On `attributed` and `private` rooms they are inside the sealed, signed body like the rest of the manifest, so the host learns nothing from them; on an `open` room they are in the clear, as everything there is, and a writer carries them only with `rooms/records/put/0.5` or later. A writer uses them only once the room's profile lists them in `recordMembers` (`RoomProfile`), as with the other members a reader that predates them refuses.",
       "properties": {
         "fileId": {
           "type": "string",
@@ -678,6 +729,45 @@ export const RESPONSE_PAYLOAD_SCHEMA = {
           "type": "string",
           "pattern": "^[A-Za-z0-9_-]{43}$",
           "description": "The file key itself, 32 bytes base64url without padding: present on an `open` room only, where there is no storage key to derive it from. Minted by the uploader from a cryptographically secure random source for this one file and never reused. MUST be absent on `attributed` and `private` rooms, where the key is derived and never stored."
+        },
+        "width": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1048576,
+          "description": "The image's width in pixels, as the uploader read it. Advisory. A writer sets `width` and `height` together or neither; a reader ignores one without the other. A reader checks it against the decoded image."
+        },
+        "height": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1048576,
+          "description": "The image's height in pixels, as the uploader read it. Advisory. A writer sets `width` and `height` together or neither; a reader ignores one without the other. A reader checks it against the decoded image."
+        },
+        "preview": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "mediaType",
+            "data"
+          ],
+          "description": "A small image standing in for the file until it is fetched: at most 8192 bytes before encoding, enough for a blurred thumbnail and small enough not to swell the record every listing reader opens. A reader renders it only as a raster image it decodes itself — never as SVG or any other type that can carry active content, never as a link, never fetching anything — and replaces it with the file once fetched. It is the uploader's rendering of the file, not a digest of it: a reader MUST NOT present it as the file's contents.",
+          "properties": {
+            "mediaType": {
+              "type": "string",
+              "enum": [
+                "image/jpeg",
+                "image/png",
+                "image/webp"
+              ],
+              "description": "The preview's own media type. Raster types only."
+            },
+            "data": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9_-]+$",
+              "minLength": 1,
+              "maxLength": 10923,
+              "description": "The preview's bytes, base64url without padding: at most 8192 bytes decoded."
+            }
+          }
         }
       }
     },