diff --git a/packages/cultcache-ts/README.md b/packages/cultcache-ts/README.md index c887c1c1..7fd0b0dd 100644 --- a/packages/cultcache-ts/README.md +++ b/packages/cultcache-ts/README.md @@ -41,11 +41,12 @@ MessagePack decoder accepts it. What the type guarantees is that a payload cannot be read or assigned directly: a decoder call, an assignment to `Uint8Array` and `new Uint8Array(payload)` fail to compile. It does not stop what the -runtime value allows. Because the value is a `Uint8Array`, a check such as `payload instanceof -Uint8Array` narrows it back to bytes, and a cast does the same; a read made that way sees the raw -bytes, which for a codec or formatter document are not the document. Read through -`decodeDocumentPayload`, and when you need the bytes themselves (hashing, signing, a store write) -take them with `documentPayloadBytes`. +runtime value allows, because the value is a `Uint8Array`. These routes read it without the owner: +`instanceof Uint8Array` or `ArrayBuffer.isView` narrowing, `Object.values`, `Object.assign` onto a +`Uint8Array`, a JSON round trip, `Reflect.get`, and a cast. A read made that way sees the raw bytes, +which for a codec or formatter document are not the document. No lint or guard closes them. Read +through `decodeDocumentPayload`, and when you need the bytes themselves (hashing, signing, a store +write) take them with `documentPayloadBytes`, the sanctioned escape. - `decodeDocumentPayload(definition, payload)` reads a payload through the definition's formatter, codec or plain map and then its schema. The definition is required. diff --git a/packages/cultcache-ts/src/document.ts b/packages/cultcache-ts/src/document.ts index 8df6eb82..4c6ea040 100644 --- a/packages/cultcache-ts/src/document.ts +++ b/packages/cultcache-ts/src/document.ts @@ -86,9 +86,10 @@ export function defineDocumentType( * The key is a plain string, not a unique symbol, so two installed copies of this package stay compatible. * * What the type guarantees: a payload cannot be read or assigned directly (a decoder call, `const b: Uint8Array = p`, - * `new Uint8Array(p)` fail to compile). What it does not: the runtime value is a `Uint8Array`, so runtime narrowing - * (`p instanceof Uint8Array`) or a cast gets the raw bytes back, and a codec or formatter document read that way is not - * the document. The escape for bytes is `documentPayloadBytes`; the reader is `decodeDocumentPayload`. + * `new Uint8Array(p)` fail to compile). What it does not: the runtime value is a `Uint8Array`, so these routes read it + * without the owner: `instanceof Uint8Array` or `ArrayBuffer.isView` narrowing, `Object.values`, `Object.assign` onto a + * `Uint8Array`, a JSON round trip, `Reflect.get`, and a cast. A codec or formatter document read that way is raw bytes, + * not the document. The sanctioned escape for bytes is `documentPayloadBytes`; the reader is `decodeDocumentPayload`. */ export interface DocumentPayload { readonly "cultcache.documentPayload": true;