Encrypted Collections for Portable Web Spaces v0.1

A key epoch is one generation of a collection's encryption key. Rather than encrypting every resource in a collection under a single long-lived key, this profile encrypts each resource under the key of whichever epoch was current when the resource was written. The collection's descriptor carries the full roster of epochs (an append-only history), and each epoch records which recipients hold a wrap of that epoch's secret.

Informally: you can think of the current epoch as "the set of keys, held by clients and people, that can decrypt what is written to this collection today". Each earlier epoch is the same answer for an earlier stretch of the collection's history, so the epoch roster as a whole reads as the collection's access history.

Epochs are what give key rotation and reader removal their meaning:

• Rotating a collection's key means appending a new epoch, not re-encrypting history. Resources written earlier remain sealed under the epochs of their writing; new writes seal under the new current epoch.
• Removing a reader means omitting them from the new epoch's recipients. They cryptographically lose access to everything written from that epoch onward, while their access to earlier epochs is unchanged: ciphertext they could once decrypt is not retroactively protected from them by a key change alone.

An era, by contrast, is not a per-collection concept but a design regime: a span of the profile's life during which stored artifacts follow one key-management construction, such that a reader would need era-specific logic to tell which construction a given artifact uses. Multiple eras force every future reader to carry branches for every past construction -- and each branch is a downgrade surface. This profile avoids that cost outright by having exactly one era, as the next section defines.

This profile has exactly one era. An encrypted collection's descriptor carries a key-epoch roster from the moment the collection exists, and every envelope seals to an epoch key and binds the epoch it sealed under. There is no descriptor-less era, no epoch-less envelope, and consequently no acceptance branch for either anywhere in the profile:

• A descriptor declaring the edv scheme without an epoch roster is non-conforming (5.4 An epoch-less descriptor is refused).
• An envelope without the pws binding, or without pws.epoch, is refused (8.5 The pws binding).
• A reader's own key-agreement key is never a decryption candidate; reads route through resolved epoch keys only (9.2 Reads).

The persistent identifier of this specification is https://w3id.org/pws/encrypted-collections.

That string is the specs key a server lists this profile under. It names the specification, not the document's current location, and it never carries a version -- the version entries under the key carry those. Clients compare the key as an opaque string, with no URL normalization.

A version entry under this profile's identifier is a JSON object with the members [PWS] defines for every entry, plus this profile's features array:

• version (REQUIRED) - The version of this profile the server implements, a bare major.minor string. This document is version 0.1.
• url (OPTIONAL) - The URL of this document at exactly that version.
• features (OPTIONAL) - An array of feature tokens from 4.3 Feature tokens, naming the optional affordances of this profile the server serves. An absent array means the same as an empty one: the server serves neither affordance.

An entry means the server conforms to this profile's required server-visible surface at that version. That surface is the chunk endpoints of 10. Chunked resources: a server that lists this profile serves them, and no feature token advertises them separately (10. Chunked resources). The rest of this profile binds clients, so there is nothing else for the entry to claim.

A server that does not implement this profile lists no entry under the identifier. A client that finds none MUST NOT infer that encrypted collections are unavailable -- the construction is client-side, and a baseline PWS server stores its envelopes -- only that the chunk endpoints and both affordances below are absent.

Example: the specs member of a service description, for a server serving both affordances (other keys elided):

{
  "specs": {
    "https://w3id.org/pws/encrypted-collections": [
      {
        "version": "0.1",
        "url": "https://w3c-ccg.github.io/wallet-attached-storage-spec/ec/",
        "features": ["blinded-index-query", "governed-history-logs"]
      }
    ]
  }
}

Two affordances of this profile are optional, each because the profile defines a way to work without it. Each is advertised by one token:

• blinded-index-query - The server serves the blinded-index query profile of [PWS] over a collection's blinded tokens, and enforces the unique attribute constraint. Without it a client fetches and filters locally, and a uniqueness constraint is at best a racy client-side read-then-write (11. The blinded index, 17. What this profile does not provide).
• governed-history-logs - The server serves a collection's meta/log sub-resource and derives the governed encryption member of the collection's Metadata object from that log's head entry. This is the server side of the log form of an encryption descriptor (13.1 Point state and log form). Without it a deployment stays on point state and gets its epoch-configuration integrity from the client-held epoch pin (7. Epoch-configuration integrity).

The token vocabulary is open and additive. A client MUST ignore a token it does not recognize, and MUST treat an absent token as "not supported"; it MUST NOT infer support for one affordance from the presence of the other.

An encrypted collection's encryption descriptor is a JSON object with the following members. All of scheme, epochs, and currentEpoch are REQUIRED from the descriptor's creation onward; there is no state of a conforming descriptor in which any of them is absent.

• scheme (REQUIRED) - The string edv.
• version (OPTIONAL) - The positive-integer version of the edv envelope wire format, per the PWS Encryption Scheme Registry. An absent version means 1. This document describes version 1.
• type (OPTIONAL) - The string WasEpochConfiguration, the descriptor's schema identifier under the log form (13.1 Point state and log form). Inside a log entry's state the member is REQUIRED (13.5 Entry format). A point-state projection served beside a log carries the same member, so that the projection equals the verified head's state once history is stripped. A descriptor no log governs MAY omit it.
• epochs (REQUIRED) - A non-empty array of epoch entries (6.1 Epoch entries), append-only across the descriptor's life.
• currentEpoch (REQUIRED) - The id of the epoch new writes encrypt under. MUST name an entry in epochs and never moves to an older epoch.
• history (OPTIONAL) - The log-form dispatch hint (13.1 Point state and log form): an object with resource, the URL of the log resource governing this descriptor, and method, an echo of the log's format identifier, named to mirror the in-log parameters.method. The member appears only on the point-state projection of a log-governed collection, not inside a log entry's state -- the log resource reserves the name there (13.4 The log resource). The hint is never authoritative: the log's own genesis commits the format identifier, and a served method that contradicts it is refused, not dispatched on.
• hmac (OPTIONAL) - The collection's blinding key: its permanent id and type, and the wrap of the blinding secret to each recipient (11.1 The blinding key). Present from the descriptor's creation or never, and never rotated (11.2 Fixed at provisioning).

The descriptor's scheme and version are set-once for the life of the collection, per [PWS], whose Epoch data model and Encryption Scheme Registry define the server-visible checks over these members (shape validation, epochs append-only enforcement, currentEpoch monotonicity, and the structural fail-closed rejection of plaintext writes). These checks do not cover type, history, or hmac: the server stores and returns those members opaquely, with no shape validation of its own (11.1 The blinding key for hmac). A descriptor MUST NOT be combined with a server-side plaintext-index (indexes) declaration -- the server cannot extract attributes from an opaque envelope; an encrypted collection indexes by blinded tokens instead (11. The blinded index).

Declaring a collection encrypted and installing its first epoch are one provisioning act. A writer that provisions an encrypted collection MUST ensure, before the collection's first content write, that its descriptor carries an epoch roster; the reference construction performs this as a two-step -- a crypto-free container ensure, then an EDV-bearing create-if-absent epoch install -- with these properties, all REQUIRED:

• The epoch secret of the first epoch (and of every later epoch) MUST be freshly generated for that epoch. It MUST NOT be, or be derived from, any longer-lived key -- not the owner's key-agreement key, not any account-level or wallet-level key, not a key any other collection uses. A rotation or an external share can wrap an epoch secret to a new recipient at any time; a secret that is also a longer-lived key would hand that recipient the longer-lived key.
• The first epoch MUST wrap to at least one recipient, and the owner MUST be among the initial recipients of a collection provisioned in their own Space.
• The install MUST be create-if-absent and adopting: a descriptor that already carries epochs -- including one written by a concurrent provisioner that won the guarded create or compare-and-swap race -- MUST be adopted as-is and MUST NOT be overwritten. Re-running the install against a settled collection performs only reads. Exactly one first epoch ever exists. (A client library MAY additionally expose an explicit initialization operation that refuses, rather than adopts, an existing roster; it MUST NOT overwrite one.)
• A torn provisioning run (the collection declared encrypted, the epoch install not yet landed) MUST be repairable by re-running the same install. No checkpoint state beyond the descriptor itself is required to detect completion.

An encrypted collection's descriptor, with its epoch roster, MUST be published before the collection's first content push, so that no envelope reaches the collection sealed under an epoch the published descriptor does not carry.

A writer that mints envelopes eagerly against a cached descriptor and then loses the descriptor create to another provisioner MUST adopt the winner's descriptor and re-encrypt any pending envelopes the adopted roster cannot route under the winner's current epoch before pushing them. This is legal precisely because pending envelopes have no server-side existence: an envelope that has reached the collection is immutable and is never re-encrypted in place, but a local, never-pushed envelope may be re-minted freely (12. Deferred minting).

A descriptor whose scheme is edv but which carries no epochs roster does not describe a state this profile admits. A client encountering one:

• MUST NOT construct a cipher for the collection -- in particular it MUST NOT fall back to sealing envelopes directly to any reader's key-agreement key;
• MUST treat the state as a torn provisioning to repair by re-running the first-epoch install (5.2 The first epoch), or as a served-descriptor integrity failure, whichever its role implies;
• MUST fail closed (no reads, no writes) until an epoch-bearing descriptor is obtained.

Each entry of epochs is a JSON object:

• id (REQUIRED) - The epoch's identifier: the did:key DID of the epoch's public key-agreement key (6.2 Epoch identifiers).
• recipients (REQUIRED) - A non-empty array of recipient entries (6.3 Recipient entries), one per recipient of this epoch.

epochs is append-only: an epoch, once written, is never removed and its id never changes, so resources stored under it remain readable. Entries within an existing epoch's recipients MAY change (adding a recipient wraps existing epoch secrets to it, 6.4 Roster operations).

An epoch's id is the did:key DID [DID-KEY] of the epoch's public X25519 key-agreement key -- a did:key:z6LS... string. The epoch key's full key id is that DID with itself as the fragment, did:key:z6LS...#z6LS..., and it is this key id that appears as the JWE recipient kid of every envelope sealed under the epoch.

Two consequences are load-bearing:

• An envelope names its epoch structurally: the JWE recipient kid up to the # is the epoch id, resolvable by any standard did:key resolver. Envelopes are roster-blind -- they name the epoch key, not any per-recipient key.
• Epoch ids are collision-free rather than ordinal. Two independently minted epochs are two distinct epochs; no counter coordination exists or is needed.

Each entry of an epoch's recipients array reuses the JWE General Serialization recipient shape ([RFC7516] section 7.2) verbatim:

• header (REQUIRED) - A JSON object with at least:
  • kid (REQUIRED) - The recipient's key-agreement key id.
  • alg (REQUIRED) - ECDH-ES+A256KW.
  • epk, apu, apv - The ephemeral public key ({ "kty": "OKP", "crv": "X25519", "x": ... } [RFC8037]) and the agreement info of the wrap: apu is the unpadded base64url ephemeral public key, apv the unpadded base64url UTF-8 of the recipient's kid (all base64url in the entry, x and encrypted_key included, is unpadded).
• encrypted_key (REQUIRED) - The wrapped payload: the raw 32-byte epoch secret, key-wrapped to the recipient's key-agreement key (ephemeral-static ECDH, the [RFC7518] Concat KDF, [RFC3394] AES key wrap), byte-exactly the derivation of 8.3.1 The key-wrap derivation.

Nothing secret appears in the descriptor: recipient entries hold public key identifiers and wrapped-key ciphertext only. The server never holds key material, never unwraps, and never verifies that a wrap is correct -- that is unverifiable without the keys, by construction.

All descriptor mutation goes through conditional writes of the Collection Metadata object: If-Match against its metaVersion validator, and guarded create with If-None-Match: *, per [PWS]. The operations:

• The first-epoch install, defined in 5.2 The first epoch.
• Adding a recipient MUST wrap every epoch's secret to it (adding a reader admits it to the collection's history -- the escrow decision), MUST be idempotent, and leaves the epoch configuration untouched (recipient entries are not part of it).
• Removing a recipient MUST mint a fresh epoch wrapped to each remaining recipient of the current epoch (never the union of historical recipients), append it, repoint currentEpoch -- and only then revoke the removed reader's capabilities. Rotate first, then revoke, as one indivisible removal: a client library SHOULD NOT expose a rotate-without-revoke or revoke-without-rotate variant of removal.
• Replacing a recipient's key -- retiring one key-agreement key in favor of its successor, the operation behind key-rotation cascades -- composes the two in one conditional write: the successor key is escrowed into every epoch like an add, and a fresh epoch excluding the retiring key is appended like a removal. History stays readable to the successor; the retiring key is sealed out of everything written after.

On an indexable collection, each of these operations also maintains the blinding key's wraps (11.2 Fixed at provisioning).

On a precondition failure (a concurrent descriptor write won), the client re-reads the descriptor, re-applies its change to the fresh state, and retries, bounded.

A resource in an encrypted collection is stored as an Encrypted Data Vault Encrypted Document: the JSON object { "id": ..., "sequence": ..., "jwe": ..., "indexed": ... } (with indexed optional; 11.3 Indexed entries), whose jwe is a JWE in JSON Serialization carrying the sealed plaintext. The stored content type is application/jose+json where the server parses it, with application/json as the portable default an unmodified PWS server accepts. The envelope shape and the server's structural fail-closed validation of it are the edv scheme registration of [PWS]'s Encryption Scheme Registry.

The envelope's sequence member is carried, and no server enforces it. In a native Encrypted Data Vault it is a monotonic counter the server checks as previous + 1. Here concurrency control is [PWS]'s conditional writes instead: a guarded create (If-None-Match: *) for an insert, and If-Match pinned to the observed ETag for an update (9.1 Writes), with the Collection Metadata object's metaVersion precondition guarding descriptor writes (6.4 Roster operations). A writer SHOULD advance sequence on each write and a reader MUST NOT rely on it for freshness or ordering.

The plaintext document carried inside the JWE declares its own inner content type and encoding (8.2 The plaintext document). Nothing user-visible -- content, plaintext type, user metadata -- appears outside the ciphertext. The one plaintext-derived exception is the opaque blinded tokens of an indexable collection's indexed member (11.3 Indexed entries), from which no attribute name or value is recoverable.

Every envelope names exactly one JWE recipient: the epoch key of the epoch it sealed under (6.2 Epoch identifiers). A conforming writer MUST NOT name any other recipient -- per-reader access rides the epoch roster, not per-envelope wraps -- and MUST NOT seal an envelope to any key that is not an epoch key (2.2 The single epoch era).

The JWE plaintext is the UTF-8 JSON serialization of a document object with the following members, and no others (a chunked document additionally seals its stream state; see the "chunked" row below):

• content (REQUIRED) - The sealed content, in the shape meta.encoding selects (below).
• meta (REQUIRED on a content envelope) - A JSON object describing content:
  • contentType (REQUIRED) - The media type of the plaintext content, a string (application/json for JSON content written without a declared type).
  • encoding (OPTIONAL) - How content carries the plaintext. A writer MUST use exactly one of the values below, and a reader MUST refuse a value it does not recognize rather than fall back to any interpretation of content.

meta.encoding and content are paired as follows:

An absent meta.encoding means JSON. A reader MUST select the content shape from meta.encoding alone and MUST NOT infer an encoding from the shape of content: a caller object that happens to be { "text": "..." } or { "bytes": "..." }, written as JSON, round-trips as that JSON object. The writer's meta.encoding is the only in-band discriminator, and it is inside the AEAD.

A metadata envelope -- the encrypted custom object of a resource's or the Collection's metadata (8.5 The pws binding) -- seals the custom object itself as content, verbatim, and carries no meta: the custom object is always JSON, and the absent-encoding rule above applies. A reader of a metadata envelope MUST treat its content as the custom object, whatever shape it has.

• Key agreement and wrap: ECDH-ES+A256KW only, over X25519 [RFC8037], with the [RFC7518] Concat KDF (SHA-256).
• Content encryption: XC20P (XChaCha20-Poly1305 [XCHACHA], the extended-nonce variant of [RFC8439]) is the profile conforming writers use; readers additionally accept C20P [RFC8439] and A256GCM [RFC7518] (the upstream EDV FIPS suite) on decrypt only. A fresh content-encryption key is generated per envelope, so envelope bytes are nondeterministic across re-encryptions of identical plaintext -- deduplication keys on decrypted content identity rather than on envelope bytes or resource id.
• Content-encryption key length: 32 bytes (256 bits), for XC20P, C20P, and A256GCM alike. The wrapped encrypted_key of an envelope recipient is therefore always a 40-byte AES key wrap output.

uint32be(1) || Z || uint32be(14) || "ECDH-ES+A256KW"
           || uint32be(32) || ephemeral public key
           || uint32be(len(kid)) || kid
           || uint32be(256)

An immutable (content-addressed) collection derives each resource id from the envelope's ciphertext after encryption: "z" + base58btc(0x00 0x10 || first 16 bytes of SHA-256(base64url-decode(jwe.ciphertext))) (base58btc per [BASE58]). Because encryption is randomized, the id identifies the stored envelope, not the plaintext; two replicas independently encrypting identical plaintext produce distinct resource ids, and convergence is defined on decrypted content, not on envelope bytes.

Every envelope MUST carry a pws parameter in its JWE protected header, bound into the AEAD (so a successful decrypt proves it authentic):

• v (REQUIRED) - The edv scheme version the envelope was written under (the descriptor's version; 1 in this document).
• epoch (REQUIRED) - The id of the epoch the envelope sealed under: the writer's current epoch at encrypt time.
• resource (OPTIONAL) - The resource id the envelope is bound to. Present whenever the id is known at encrypt time; absent only when no resource id exists to bind: a content-derived id, which does not exist until after encryption (8.4 Content-derived resource ids), or a Collection Metadata envelope, which belongs to no resource.
• collection (OPTIONAL) - The Collection id the envelope is bound to: the Collection's id, the {collection_id} path segment of [PWS]'s URL templates. Present on exactly one envelope kind, the Collection Metadata envelope; an envelope in any resource slot -- content or resource metadata -- MUST NOT bind it.

A resource metadata envelope (the encrypted custom object of a resource's metadata, per [PWS]) binds pws exactly like a content envelope, with resource always present -- bound to the resource's id, not to the metadata envelope's own internal document id -- and epoch the write epoch like every write.

A Collection Metadata envelope (the encrypted custom object of the Collection's own metadata, per [PWS]) belongs to no resource. It MUST bind collection -- the id of the Collection it was written for -- and MUST NOT bind resource; epoch is the write epoch like every write. Each of the profile's slots is thereby declared positively, by the member set of its envelope: resource marks a resource-slot envelope, collection marks the Collection Metadata envelope, and a content-derived content envelope binds neither -- which is exactly why the Collection Metadata slot requires a present collection rather than merely a missing resource (8.6 Binding verification).

After every successful decrypt, and before the plaintext is used, a reader MUST verify the pws binding. The checks, in order, all unconditional:

1. A missing pws parameter is refused: every envelope of this profile binds pws at encrypt time, so its absence means a writer this scheme does not admit. There is no unbound-envelope acceptance (2.2 The single epoch era).
2. A pws.v that is absent, or present but not a JSON number, is refused like a missing pws: an envelope that does not declare its scheme version is outside the profile. There is no default version to assume.
3. A pws.v greater than the scheme version the reader implements is refused: a future-scheme envelope this reader does not understand. The version the reader implements is the one the collection's descriptor declares (its version, 5.1 Members), which the reader has already confirmed it supports before building any cipher.
4. When the read targeted a known resource id (a content or resource metadata read): a present pws.collection is refused before any id comparison (the Collection's metadata envelope was served in a resource slot). A string pws.resource MUST equal the targeted id (a mismatch is a server-side swap of two resources' envelopes); without a string pws.resource the envelope is treated as a content-derived write, and the id re-derived from its ciphertext (8.4 Content-derived resource ids) MUST equal the targeted id (a mismatch means the envelope was served under an id it was not written for).
5. When the read targeted the Collection Metadata slot: a present pws.resource is refused (a resource's envelope was served in the Collection's slot), and a string pws.collection MUST be present and equal the id of the Collection the read addressed. A missing pws.collection means an envelope of some other slot -- notably a content-derived content envelope, whose member set is otherwise identical -- and a mismatched one is one Collection's metadata served as another's.
6. A missing or non-string pws.epoch is refused like a missing pws. Present, it MUST equal the epoch of the key that actually decrypted the envelope (the did:key before the # of that key's id); a mismatch is a replay of the envelope under a different epoch's key. The check has no epoch-less carve-out: there is no epoch-less envelope to admit.

The first three failures, and the absence of pws.epoch in the last, are scheme refusals (the envelope is outside the profile); the rest are integrity failures (the server misrepresented what it stored). A reader SHOULD keep the two classes distinct in its error taxonomy and MUST NOT mask either as a routine decryption miss. The four scheme-refusal cases are thus: no pws; no usable pws.v; a future pws.v; no usable pws.epoch.

• A write MUST encrypt under the descriptor's currentEpoch and bind it as pws.epoch.
• A content write SHOULD declare its epoch to the server (the Key-Epoch request header, per [PWS]), so listings and the changes feed can serve the epoch stamp and a replicating reader can select its key before fetching the envelope. The server-served stamp is advisory routing metadata; the authoritative binding is the envelope's own AEAD-bound pws.epoch.
• Inserts use guarded creates (If-None-Match: *) and updates use If-Match, per the collection's mutability class and [PWS]'s conditional requests.

A reader resolves its epoch keys from the descriptor: for each epoch whose recipients name the reader's key-agreement key, unwrapping the epoch secret and reconstructing the epoch key. The write epoch is currentEpoch when the reader holds it, and MUST be unwrapped eagerly (write readiness: a wrap that fails to unwrap surfaces as its typed failure at key resolution, not at the first write); other held epochs MAY unwrap lazily on first use. A reader that does not hold currentEpoch -- a removed or archive reader, whose writes the server rejects via its revoked capability anyway -- selects as its write epoch, deterministically, the last epoch in the descriptor's canonical epochs order that names it. The incidental order in which secrets happened to unwrap plays no part in the selection.

Decryption routes by the stored envelope's JWE recipient kid against the resolved epoch keys, and only those:

• The reader's own key-agreement key is NEVER a decryption candidate. An envelope sealed to anything other than a resolved epoch key is unroutable, whatever key it names (2.2 The single epoch era).
• An envelope naming an epoch the reader's cached descriptor does not carry is the unknown-epoch signal. Because an epoch rotation is a write of the Collection Metadata object and emits no changes-feed entry, a reader holding a stale cached descriptor can meet envelopes stamped with an unseen epoch; the remedy is exactly one descriptor re-read, key-resolution rebuild, and retry -- guarded to once per collection per session, so a genuinely foreign envelope cannot drive a refetch loop. Still unknown after the refresh, the envelope is refused as unroutable.
• A failed unwrap of a recipient entry that names the reader is a typed failure rather than a silently absent key: key servers whose unwrap resolves a null key on mismatch are surfaced as the typed failure, not treated as "try the next candidate succeeded".
• An AEAD authentication failure after a successful key unwrap is an integrity failure of the stored envelope. It MUST be surfaced as such and MUST NOT be masked as a key miss or routine decryption error.

A reader that is not a recipient of any epoch of a collection fails closed with a recipiency error -- the read axis is absent, whatever its capability (fetch axis) status.

A single chunk is addressed in member form (no trailing slash), and a resource's chunk set is listed in container form (trailing slash), following [PWS]'s trailing-slash convention:

• PUT / GET / HEAD / DELETE /space/{space_id}/{collection_id}/{resource_id}/chunks/{index} -- store, read, head, and delete a single chunk.
• GET /space/{space_id}/{collection_id}/{resource_id}/chunks/ -- list the resource's chunks.

As elsewhere in [PWS], a request to the non-canonical variant of either form is redirected to the canonical one with 308 Permanent Redirect (which, unlike a 302, requires the client to replay the same method and body): a GET of the member-form chunks container without its trailing slash redirects to the trailing-slash form, and a member PUT (or other member method) carrying a trailing slash redirects to the no-slash form.

The {index} path segment MUST be a canonical non-negative decimal integer: a single 0, or a digit run with no leading zero, no sign, and no non-digit characters (so 0, 1, 42 are valid; 01, +1, -1, 1e3, 1.0 are not). A server MUST reject a non-canonical index with an invalid-id (400) error. Requiring one canonical serialization keeps each chunk addressable at exactly one URL.

A resource's chunks are bound to the resource. Deleting the parent resource (see [PWS]'s Delete Resource operation) MUST cascade-delete all of its chunks; there is no way to leave chunks behind a deleted resource. A resource's chunks are carried alongside its content by a Space export and restored by the matching import (the export reserved segment of [PWS]).

Chunk writes and deletes are invisible to [PWS]'s changes query profile: storing or deleting a chunk affects only the chunk's own ETag validator and MUST NOT advance the parent resource's position in the feed, and the feed enumerates resources only, not chunks. A client replicating a chunked resource MUST therefore finish the write by updating the parent resource's own content (its envelope; see 10.8 Chunked envelopes) after its chunks are stored: that final resource write is what surfaces the change to replicating readers. A client that mutates a resource purely through its chunks never appears on the feed.

Chunk operations use the same authorization model as every other [PWS] operation (see [PWS]'s Authorization): writes (PUT, DELETE) are capability-only, while reads (GET, HEAD, and the container listing) are capability-or-policy. A chunk write's capability invocationTarget MUST be the chunk's own full URL (member form), and the listing's the chunks/ container URL -- the same exact-match target rule that governs every PWS URL (see [PWS-AUTHZ]). For a read, the governing access-control policy is the parent resource's: a chunk exposes a fragment of the same content the resource holds, so whoever may read the resource may read its chunks, and the maximum-privacy not-found rule applies to a chunk exactly as to the resource.

A large or streamed document is stored as chunks. The envelope stays the resource's own content and carries the extent of the stream; each chunk carries one sealed fragment.

1. The client writes the document envelope first, as an ordinary resource. This satisfies the 10.2 Store chunk operation rule that the parent resource must exist before any of its chunks. The envelope's plaintext document declares meta.encoding "chunked" (8.2 The plaintext document) and seals its stream state, so a reader can learn the extent of the stream from the document alone.
2. For each chunk i in 0 .. chunks - 1, the client serializes the [EDV] chunk object { index, offset, sequence, jwe } to JSON and PUTs it to chunk index i under the application/octet-stream content type. The octet-stream type is deliberate: it routes the chunk through the server's raw-binary write path, bounded by the backend's maxUploadBytes (tens of MiB) rather than by the much smaller body-size limit servers typically impose on JSON-parsed requests (the reference server's is 1 MiB), which a full encrypted chunk would exceed. The server stores the bytes verbatim and never parses them, so a reader decodes and parses the chunk object back client-side.
3. A reader fetches the document envelope, decrypts it, reads stream.chunks, fetches chunk indexes 0 .. chunks - 1 (10.3 Read chunk operation), and decrypts each jwe client-side to reassemble the stream.

The stream member of a chunked document's plaintext (8.2 The plaintext document) is a JSON object carrying the extent of the stream:

• chunks (REQUIRED once the stream is complete) - The total number of chunks the stream occupies, a non-negative integer. A reader reads indexes 0 through chunks - 1.
• sequence (OPTIONAL) - The envelope's own sequence at the write that recorded the chunk count. Carried, and not enforced by the server (8.1 The stored envelope).
• pending (OPTIONAL) - true on the reserve write of the two-step sequence above, where the envelope exists but its chunk count is not yet known. A reader that meets pending with no chunks MUST refuse the document as incomplete rather than read zero chunks.

The reassembled stream's media type is the document's own meta.contentType (8.2 The plaintext document); stream carries no content type of its own. The chunks of a stream belong to the resource whose envelope declares them: the envelope's id, bound into the AEAD as pws.resource (8.5 The pws binding), is the resource whose chunk address (10.1 The chunk address) holds them. A reader MUST read a stream's chunks from that resource and from no other.

An indexable collection's descriptor carries the OPTIONAL hmac member, a JSON object:

• id (REQUIRED) - A non-empty string identifying the blinding key, opaque and permanent for the life of the collection (the reference construction mints a urn:uuid: URN). Every indexed entry and every query names the key by this id.
• type (REQUIRED) - The string Sha256HmacKey2019. Any other value MUST be refused; a reader never infers the blinding algorithm from anything but this member.
• recipients (REQUIRED) - A non-empty array of recipient entries in exactly the shape of an epoch's (6.3 Recipient entries): the raw 32-byte blinding secret, key-wrapped to each recipient's key-agreement key. One wrap construction serves both kinds of secret; there is no separate blinding-key wrap format to review.

The blinding secret MUST be 32 freshly generated random bytes. Like an epoch secret, it MUST NOT be, or be derived from, any longer-lived key or any other collection's key (5.2 The first epoch), and nothing secret appears in the descriptor.

Recipiency of the blinding key is granted by the same roster operations that grant epoch recipiency (11.2 Fixed at provisioning). A declared hmac member from which a client can resolve no secret -- no entry names its key-agreement key, or the entry that does fails to unwrap -- is a typed failure, exactly as for an epoch wrap (9.2 Reads). Indexing and querying fail closed: the client MUST NOT downgrade to writing un-indexed envelopes on an indexable collection, which would write envelopes no query can find. Plain reads do not involve the blinding key.

Indexability is a property fixed at the collection's birth, and the blinding key never changes afterward:

• The key MUST be minted in the same provisioning act as the first epoch (5.2 The first epoch) and wrapped to the same initial recipients. It MUST NOT be added to a descriptor that already carries an epoch roster without one. A retro-fitted key would leave every envelope written before it without tokens, silently absent from every query, so mid-life addition is refused rather than half-honored.
• The install shares the first epoch's adoption rule: an hmac member already present in the descriptor is always adopted as-is (not overwritten). Exactly one blinding key ever exists per collection.
• The key never rotates, not on epoch rotation, not on recipient removal. Blinded tokens MUST compare across the collection's whole history; a successor key would split every query at the switchover, with a re-blind of the whole history the only repair.
• The roster operations of 6.4 Roster operations maintain the blinding key's recipients alongside the epochs'. Adding a recipient MUST wrap the blinding secret to it, idempotently. Removing a recipient drops the leaver's wrap entry as housekeeping only: the key itself is unchanged, and the operation MUST NOT mint a replacement key (18.8 The blinding key survives removal states the asymmetry this accepts). Replacing a recipient's key composes the two, as for epochs.

A descriptor without an hmac member describes a collection that is not indexable. That is a conforming state, not an error; only a request to make such a collection indexable after the fact is refused.

Under the log form (13.1 Point state and log form) each entry's state carries the full descriptor, hmac included, so the entry proof covers the member exactly as it covers the epoch configuration -- and fixed-at-provisioning becomes a claim a verifier can check across the entry chain: one permanent id, present from the first entry or absent from all. On pure point state the member has no client-side guard of its own (the epoch pin does not cover it), and a host serving a substituted hmac member knows its secret, so it can test guessed attribute values against the reader's subsequent query tokens. The log form is what closes that, as with any configuration substitution (7. Epoch-configuration integrity).

A content envelope of an indexable collection MAY carry the EDV indexed member (8.1 The stored envelope): the blinded tokens the server matches queries against. The structure is the [EDV] Encrypted Document's indexed array, reused verbatim, with this profile's cardinalities:

• At most one entry, a JSON object whose hmac.id and hmac.type MUST equal the descriptor hmac member's id and type -- one blinding key per collection, so one entry per envelope.
• The entry's sequence is the envelope's own sequence.
• The entry's attributes is an array of { "name": ..., "value": ..., "unique": ... } objects (unique optional), one per blinded token pair, computed as 11.4 Token computation defines. An attribute with "unique": true claims per-collection uniqueness of its token pair; enforcing the claim is the server-visible half, the unique-blinded-attributes rule of [PWS]'s blinded-index profile.

An envelope of a collection with no blinding key MUST NOT carry indexed. Neither does any metadata envelope -- a resource metadata envelope and the Collection Metadata envelope alike MUST NOT carry the member. Only content envelopes are indexed; queries match content, and the index schema itself rides the Collection Metadata envelope (11.5 The index schema).

indexed lives outside the JWE, in the clear, and that is its function: the server stores and matches it without being able to invert a token. It is consequently outside the AEAD and the pws binding. A reader MUST NOT treat indexed as authenticated: query results are candidate envelopes, and integrity rests where it always does, on each envelope's decrypt and binding verification (8.6 Binding verification). A tampering server can suppress or misreport matches -- a fetch-axis failure (18.2 Fetch and decrypt are separate axes) no per-envelope construction detects -- but cannot forge an envelope that decrypts.

Every writer of a collection MUST blind identically, or queries stop matching history. The choices below are therefore permanent byte-level values, baked into every stored token. Throughout, HMAC is HMAC-SHA-256 [RFC2104] under the collection's 32-byte blinding secret, || is byte concatenation, and base64url is unpadded [RFC4648] (section 5).

An indexed attribute is named by a dotted path into the sealed plaintext document, rooted at content (the document's content) or meta (the document's own inner type descriptor: contentType and encoding). The path never addresses the PWS resource metadata slot, which is a separate envelope (8.5 The pws binding). A literal . inside a path segment is escaped as \., and the name digest below is taken over the full path string as written, escapes included. For a simple attribute with path name holding plaintext value value:

• The name digest is SHA-256(UTF-8(name)) -- the path string itself, uncanonicalized.
• The value digest is SHA-256(UTF-8(JCS(value))), where JCS is the JSON Canonicalization Scheme [RFC8785]. The value is canonicalized as a JSON value: a string digests with its quotes, a number in its canonical JSON form.
• The name token is base64url(HMAC(name digest)).
• The value token is base64url(HMAC(SHA-256(name digest || value digest))). Folding the name digest in salts the value, so equal values under different attribute names produce unrelated tokens.

An attribute whose value is an array blinds each element as its own token pair.

A compound index -- an ordered list of paths declared as one index (11.5 The index schema) -- blinds one token pair per leading prefix of the list, so a query may constrain any prefix. The prefix's name digest is SHA-256(name digest 1 || ... || name digest k), and its value digest SHA-256(value digest 1 || ... || value digest k); both feed the same HMAC-and-salt step as a simple attribute's digests. Two boundary rules keep writer and querier aligned:

• A one-member prefix is blinded in this compound (digest-of-digests) form -- unless the same path is also declared as a simple index, in which case the simple form already covers it and the compound form is not emitted.
• unique is carried only by the full-length prefix. A shorter one cannot claim the whole combination's uniqueness.

Multi-valued members spread combinatorially, one token pair per combination of element values.

Which attributes a collection indexes -- and with which unique and compound declarations -- is configuration every writer and every later-added reader must agree on: a writer blinds exactly the declared attributes at write time, and a reader can only query what it knows is declared. This profile persists that schema encrypted, inside the Collection Metadata envelope (8.5 The pws binding), as the indexSchema member of the Collection Metadata object's custom member:

• revision (REQUIRED) - A non-negative integer, incremented by each declaration write; the empty schema is revision 0.
• indexes (REQUIRED) - An array of declarations, each a JSON object:
  • attribute (REQUIRED) - A dotted path (a simple index) or an array of dotted paths (a compound index), per 11.4 Token computation. A one-member array MUST be normalized to the bare path: it declares the same simple index, not a one-member compound (the two forms blind differently, so only one may exist).
  • unique (OPTIONAL) - true to declare the index unique.
  • addedIn (REQUIRED) - The revision at which the declaration was added.

Declaring an index appends an entry and increments revision, through a conditional write of the Collection Metadata object (If-Match against metaVersion, per [PWS]), so concurrent declarations serialize. The object has a single validator, covering its plaintext members and its custom envelope alike, so a declaration contends with every plaintext configuration write of the same Collection. A concurrent rename or backend change makes the declaration's compare-and-swap fail with a precondition failure. The client MUST then re-read the object and retry the declaration against the fresh validator, resending the plaintext members it just read, because the write is a full replacement. Declarations are add-only in this profile. Re-declaring an existing index on identical terms is a no-op; changing a declaration's unique in place MUST be refused -- the server has been enforcing, or not enforcing, the claim for every envelope already written.

addedIn is the partial-coverage marker: envelopes written before a declaration carry no tokens for it, so matches on a later-added attribute MAY be partial over the collection's earlier history. A reader that needs full coverage backfills by re-writing each earlier envelope's indexed entries under the current schema -- a client-side sweep of the whole history, the same cost class that makes rotating the blinding key untenable (11.2 Fixed at provisioning).

A reader MUST NOT blind a query for an attribute the persisted schema does not declare: there is nothing for the tokens to match, and failing closed keeps a typo from reading as an empty collection. An absent or empty indexSchema on an indexable collection means nothing is declared yet -- indexable, but nothing to query. A persisted indexSchema that does not conform to this shape, or a non-conforming entry within one, yields no declarations rather than a refusal: the schema is discovery metadata riding a shared custom object, and the fail-closed guard is the undeclared-attribute refusal above.

The schema rides the encrypted custom envelope rather than a plaintext member of the Collection Metadata object. Attribute names and index structure reveal the collection's data model, and the server cannot read inside custom (18.9 What the index reveals).

An encryption descriptor as defined above is point state: the current configuration, served whole, its invariants enforced by the server. Under the log form the same resource is governed as a hash-linked log of full-state entries, each entry proof-carrying and externally authorized, and the encryption descriptor is one of the log's state schemas.

Under the log form:

• Each log entry's state carries the full descriptor at that version, under a type member identifying its schema -- for this profile's descriptors, the string WasEpochConfiguration (5.1 Members). The rules of this profile apply to the state of the verified head entry exactly as they apply to a served point-state descriptor: same members (5.1 Members), same first-epoch and append-only rules, same fail-closed refusal of an epoch-less state.
• Epoch history and log history are distinct axes. epochs remains append-only WITHIN each state (a resource-level invariant a verifier can check across consecutive entries), while the log records the succession of whole configurations -- so "epochs is append-only" and "currentEpoch never moves backwards" become verifiable claims over the entry chain rather than server-enforced rules.
• Authorship of a configuration is established by the entry's Data Integrity proof, verified against the deployment's root of trust per the external-authorization rule (13.8 Authorization); the entry proof covers the full epoch configuration, and the hash chain with a pinned head makes any rollback a chain break -- the log form is what carries this profile's epoch-configuration integrity (7. Epoch-configuration integrity).
• A point-state descriptor served beside a log is a projection bound to the log. The projection's history member names the governing log (5.1 Members), and a verifying consumer acts only on a projection equal to the verified head's state after stripping history -- the one member the projection carries and an entry's state never does (13.4 The log resource).

The log form's server-side half -- serving the collection's meta/log sub-resource and deriving the governed encryption member from its verified head -- is served only where the server's version entry for this profile carries the governed-history-logs token (4.3 Feature tokens). A writer MUST consult the token before choosing a framing, since the two are written through different endpoints. A deployment on a server without the token keeps point state and the client-held epoch pin (7. Epoch-configuration integrity).

Nothing in this profile's epoch rules depends on which framing carries the descriptor; a deployment adopts the log form per collection.

A resource log is an append-only sequence of log entries, each carrying the full state of one co-managed resource at that point in its history. Each entry is hash-chained to its predecessor, and signed by the client that appended it. The current state of the resource is the state of the verified head entry; earlier entries exist so that any reader can verify how the resource got there, entirely client-side, against a host that (for threat modeling purposes) can be assumed adversarial.

Three parties appear in this profile:

• The controller document -- the DID document of the Space's controller, resolved and verified by the reader independently of the storage server (for a did:webvh controller, by fetching and verifying its own hash-chained log). It is the log's root of authority; the set of keys that may authorize appends is defined there and only there.
• The writers -- enrolled clients (typically, the account's other wallet installations; [APP-CONNECT] describes them informatively from the connecting application's side), each holding a key listed in the controller document. Any number of writers may append; the profile assumes no coordination between them beyond the storage server's Conditional Request compare-and-swap primitive (see 13.10 Appending).
• The host -- the storage server holding the log resource. Under [PWS] the host is trusted to enforce authorization on writes; this profile deliberately does not lean on that trust. For log verification the host is treated as a minimal store that linearizes concurrent appends and nothing more, and every guarantee below must hold even against a host that serves stale, forged, truncated, or forked logs.

The log's identifier is self-certifying (the SCID in its genesis entry commits to the genesis content, so a host cannot substitute one log for another under the same identity, see 13.6 Entry hashing and the SCID), while its authority is externalized (no entry is valid on the log's own say-so; every entry's signer must be found in the externally verified controller document, see 13.8 Authorization). The rationale for this split is given in 13.14 Design rationale: externalized log authorization.

A resource log is stored as a single resource, serialized as JSON Lines [JSON-LINES]: one log entry as one JSON object per line, in order, first line first. Normatively, each line is a single JSON text [RFC8259] serialized without embedded newlines, and lines are separated by U+000A LINE FEED.

The log resource is the only serving of the resource it governs: this profile defines no companion point-state document, and the governed resource's current state exists only as the state of the verified head entry (13.9 Chain verification).

The member name history is reserved in entry state: a log entry's state MUST NOT contain a history member.

A log entry is a JSON object with exactly five members, all REQUIRED:

A verifier MUST reject an entry carrying members other than these five.

parameters rules. Unlike did:webvh, parameters do not evolve: format changes travel through the handover mechanism (13.12 The terminal handover entry), and not through parameter mutation.

• The genesis entry's parameters MUST carry method (the format identifier, 13.13 Format identifiers) and scid (the SCID), and MAY carry previousLog (successor logs only, 13.12 The terminal handover entry). No other member is permitted.
• Every other entry's parameters MUST be {}, with one exception: a terminal entry's parameters is exactly { "nextLog": { "method": ..., "scid": ... } } (13.12 The terminal handover entry).
• A verifier MUST reject an entry whose parameters carry any member this profile does not define for that entry position. This is deliberate fail-closed extensibility: the deleted did:webvh key-management parameters, in particular, MUST NOT be accepted, so a served log can never smuggle authorization semantics this profile removed.

versionTime is advisory. A writer MUST set it to its best knowledge of the current time, and a verifier MUST NOT refuse an entry on temporal grounds -- not for being out of order with respect to its neighbors, and not for being in the future. Ordering authority rests entirely with the hash chain.

Example: a two-entry log (shown pretty-printed; on the wire each entry is one line; hash, DID, and key values are illustrative):

{
  "versionId": "1-QmUv7Yx3mvL2mLpp9pRgTvNqEcYtT7yiV1sfMx6xEBcCyD",
  "versionTime": "2026-08-06T17:00:00Z",
  "parameters": {
    "method": "resource-log:0.1",
    "scid": "QmXbWpS3fY9uNnQhJcM4kR8vT2eDgAqLx5oPiZsE6wHtUa"
  },
  "state": { "type": "WasEpochConfiguration", "...": "..." },
  "proof": [{ "...": "..." }]
}
{
  "versionId": "2-Qma8fN4kQjTr2vXwYhPzUdE9cLmB5oGsKiR7tD3eVpMnHx",
  "versionTime": "2026-08-07T09:30:00Z",
  "parameters": {},
  "state": { "type": "WasEpochConfiguration", "...": "..." },
  "proof": [{
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "proofPurpose": "assertionMethod",
    "verificationMethod": "did:webvh:QmScid...:wallet-storage.example:space:81246131-69a4-45ab-9bff-9c946b59cf2e:id?versionId=6-QmDocVersion...#z6MkclientKey...",
    "proofValue": "z..."
  }]
}

Canonicalization throughout this profile is JCS [RFC8785], over strict JSON values (no undefined, no non-finite numbers).

The hash serialization format. Every hash this profile mints, including the entry hash, the SCID, and the scid values carried in nextLog and previousLog, is serialized the same way: the SHA-256 digest of the canonicalized input, wrapped as a multihash (the bytes 0x12, 0x20, then the 32 digest bytes), encoded with the base58btc alphabet, with no multibase prefix. This is byte-for-byte the did:webvh entry-hash format. It is deliberately NOT the z-prefixed multibase serialization, and NOT the base64urlserialization used for content addressing elsewhere in [PWS]; one format, chosen once, so a verifier never has to guess.

The entry hash. The entryHash of entry n is the hash, as above, of the entry with its proof member removed and its versionId member replaced by the predecessor's versionId -- for the genesis entry, by the SCID. The entry's own versionId is then <n>-<entryHash>. This is what makes the chain a chain: each entry's identifier is a commitment to its predecessor's identifier and transitively to the entire log back to genesis.

The genesis entry and the SCID (self-certifying identifier). The genesis entry is built in two passes:

1. Build the preliminary entry with the literal placeholder string {SCID} as the value of both versionId and parameters.scid (and anywhere else the SCID will appear). The SCID is the hash, as above, of this preliminary entry.
2. Replace every {SCID} placeholder with the SCID, then compute the entry hash normally (versionId input value: the SCID). The genesis versionId is 1-<entryHash>.

A verifier MUST recompute the SCID by the inverse procedure (substitute the log's parameters.scid value back to {SCID}, hash, compare) and MUST reject a log whose SCID does not verify.

Because parameters.method is inside the hashed genesis content, the SCID commits to the format identifier: a host cannot downgrade a log's format without changing its identity. And because every later entry hash chains to the genesis through the versionId substitution rule, every entry hash in the system is transitively bound to that identifier. Together with the fixed five-member input shape, this is this profile's domain separation: no entry hash can collide with a hash minted over any other structure.

Each element of an entry's proof array MUST be a Data Integrity proof [VC-DATA-INTEGRITY] with:

• type: DataIntegrityProof
• cryptosuite: eddsa-jcs-2022 [VC-DI-EDDSA] -- no other cryptosuite is permitted
• proofPurpose: assertionMethod
• verificationMethod: a DID URL identifying the signing key in the controller document, carrying the controller versionId described below
• proofValue: the proof value per [VC-DI-EDDSA]

The proof input is the complete entry, including its final versionId, with the proof member absent. Because the versionId is a commitment to the whole chain (13.6 Entry hashing and the SCID), the signature covers the chain link; an entry cannot be re-parented without breaking its proof.

A verifier MUST verify every proof in the array. One failing proof rejects the entry.

The controller versionId. Where the controller's DID method provides versioned document resolution (as did:webvh does), the proof's verificationMethod MUST carry a versionId DID parameter [DID-CORE] naming the controller-document version the entry was authorized under, e.g. did:webvh:...:id?versionId=6-Qm...#z6Mk.... The versionId parameter MUST be the only DID parameter on the verificationMethod, and its value MUST be the versionId verbatim (no percent-encoding). A verifier MUST reject a verificationMethod whose query carries any other parameter or an empty versionId. The controller versionId is inside the signed proof options, so it cannot be altered without breaking the proof. Where the controller's document is unversioned (a static DID such as did:key), the controller versionId is omitted and every controller-versionId rule below reads "the controller document".

Multiple proofs carry one controller version. All proofs of an entry MUST carry the same controller version and MUST be by distinct signing keys. A verifier MUST reject an entry whose proofs disagree on the controller version or whose proofs share a signing key.

An entry is authorized by exactly one rule:

Every proof's signing key MUST be listed as a verification method under the assertionMethod relation of the controller document at the entry's controller version, where the controller document is resolved and verified by the reader independently of the host serving the log.

The entry's controller version is the common controller version its proofs carry (13.7 The entry proof and its controller versionId): every proof of an entry carries the same value, so the entry has exactly one. Every signing key is checked for assertionMethod membership at that one value, not at any per-proof value.

The rule's parts, unpacked, each normative:

1. The document comes from the reader's own verification, not from the channel. The verifier MUST resolve the controller document through its own verified resolution pipeline, cryptographically verifying every step: for a did:webvh controller, it fetches the controller log itself, verifies it end-to-end (SCID, entry hash chain, proofs, and its own head pin, where it keeps one), and answers the controller-version lookup from that verified history. A verifier MUST NOT obtain the signing key by dereferencing the proof's verificationMethod URL as an ordinary resource fetch, and MUST NOT accept controller-document material supplied by the host outside that independently verified resolution -- the host serving the resource log is the same party a doctored controller document would come from. (In implementation terms: the document loader handed to the proof-verification library answers DID URL lookups from the verified controller log, not from the wire.)
2. The controller version must be present. The controller versionId MUST identify a version present in the reader's verified controller log, at or before its head. A controller versionId naming an unknown version rejects the entry.
3. Controller versions are monotone along the log. Each entry's controller version MUST be the same as, or a descendant of (for a linear controller log: at or after), the previous entry's controller version. An entry whose controller version is behind its predecessor rejects the log.
4. The relation is assertionMethod. The log format's fixed proof shape ([DID-WEBVH]) sets proofPurpose: assertionMethod, and Data Integrity verification [VC-DATA-INTEGRITY] already requires a proof's verification method to be authorized under the controller-document relation matching the proof's purpose. The authorization rule uses that same relation, so proof verification and authorization are one membership check, enforceable with standard proof-verification tooling -- no second relation a signing key must be dual-listed under, and no custom verifier overriding the purpose-relation match. The flip side is that listing a key under assertionMethod is precisely what entitles it to append: a controller whose logs are governed by this profile MUST NOT list a key under assertionMethod unless that key is entitled to co-manage the account's governed resources. Keys listed under other relations only (a keyAgreement-only recovery key, an authentication-only login key) remain structurally excluded.

Writers name their verified head. A writer appending an entry MUST carry the head of the controller document as the writer last verified it. Together with controller-version monotonicity this yields the profile's historical verification: entries verify as-of-append. A client revoked from the controller document keeps its past entries verifiable (they carry versions where its key was present) while losing the ability to have new entries accepted under post-revocation controller versions.

The sealing append. After a controller-document change that removes a verification method, the controller's clients MUST ensure that each governed resource log receives at least one subsequent entry carrying a controller version at or after the new document version. Controller-version monotonicity then makes the removal effective for that log: no later entry can carry a controller version behind the seal, so the removed key can never validly append again. Until a log's sealing append operation lands, the removed key can still extend that log under a pre-removal controller version -- a residual window with the same shape, detection, and repair story as any other torn multi-resource ceremony. The staleness is visible in durable state (a log whose head controller version predates the membership change), and re-running the sealing pass will converge on the same state.

A verifier MUST run the following checks over the full log, in order, and MUST treat any failure as rejecting the log (not just the failing entry). A verifier MUST NOT accept any stated or served head, digest, or count in place of recomputing from the entries themselves.

1. Parse. Parse the resource as JSON Lines (13.4 The log resource). Reject on any non-object line, on any entry violating 13.5 Entry format (member set, parameters rules, state.type), and on any versionId whose ordinal is not the entry's 1-based position.
2. Genesis. Recompute and check the SCID (13.6 Entry hashing and the SCID). Check that parameters.method names a format this verifier implements (13.13 Format identifiers); where a chain-head pin or the referencing profile supplied an expected method, check that it matches.
3. Chain. For each entry, recompute the entry hash from the predecessor-substituted input and check it against the versionId.
4. Proofs. For each entry, verify every proof per 13.7 The entry proof and its controller versionId.
5. Authorization. For each entry, apply 13.8 Authorization: first reduce the entry's proofs to its one controller version -- check that every proof carries a controller version (or, under an unversioned controller, that none does), that the proofs agree, and that no signing key repeats across them, rejecting the entry otherwise (13.7 The entry proof and its controller versionId). Then, once for the entry, check that the controller version is known and check controller-version monotonicity. Then check assertionMethod membership of every signing key at that one controller version.
6. Termination. If any entry is a terminal entry, check that it is the last entry; reject a log with entries after a terminal entry, and refuse to append past one (13.12 The terminal handover entry).
7. Continuity. Compare the verified head against the chain-head pin, where one is held (13.11 Head pinning).

The resource's current state is the verified head entry's state.

Appending is linearized by the host's compare-and-swap (CAS) primitive (conditional writes on the log resource's entity tag, per [PWS]); the chain itself carries no consensus mechanism, and none is needed: concurrent writers produce a CAS conflict as opposed to a fork.

Conditional writes are a baseline requirement of [PWS], so every host serving resource logs supports them. A writer MUST NOT fall back to an unconditional write: without the precondition, concurrent appends silently overwrite one another instead of failing into the retry loop below.

A writer MUST:

1. Read the full log and verify it per 13.9 Chain verification -- an entry is never built on an unverified head.
2. Build the new entry against the verified head (full state, hash, controller versionId, proof) and write the extended log conditionally on the entity tag of the read from step 1.
3. On a conditional-write conflict: re-read, re-verify, rebase the change on the new head, and retry.
4. Confirm by reading back. A write acknowledgement is a promise, not a fact: the writer MUST read the log back and verify that the extended, verified log contains its entry before treating the append -- or any ceremony step gated on it -- as durable.

This procedure is single-writer: one party builds the entry, its controller versionId, and its proof against one verified head. Where an entry carries more than one proof, that same writer assembles all of them in step 2, and all of them carry that writer's verified head's controller version. The procedure defines no step in which separate parties sign one entry against different verified heads.

A reader that returns to a log across sessions MUST keep a chain-head pin per log: the log's format identifier (parameters.method), its SCID, and the versionId of the latest verified head. The pin is client-local durable state; where it is stored and how it is protected are left up to client implementers.

• The pin is established at first contact: the first full verification of a log the reader has no pin for. First contact is trust-on-first-use, and what it establishes is the log's identity (the SCID); see 18.7 Resource log trust bounds for the limits and implications.
• The pin is updated only after a full verification (13.9 Chain verification) of a log whose head is the pinned head or a descendant of it, or after a verified handover (13.12 The terminal handover entry), which replaces the pin with the successor's (method, SCID, head).
• A served log whose SCID or method differs from the pin, outside a verified handover, MUST be refused as a continuity break.
• A served log whose head is behind the pin (the pinned head's ordinal exceeds the served head's, with the served log an ancestor-prefix of what was pinned) is reconcilable divergence -- possibly replication lag. The reader MUST NOT adopt it and MUST NOT regress its pin; it MAY retry.
• A served log that has forked -- it shares a prefix with the pinned history but diverges at some version, so neither is an ancestor of the other -- MUST be refused, and the reader SHOULD retain both the served log and its pinned evidence: every entry is signed, so a conflicting pair of logs under one SCID is transferable, independently verifiable evidence of equivocation.

A pin record MAY carry an extensible set of attached proofs (for example, a host-signed checkpoint, or witness co-signatures adopted later as policy), under the rule that a reader ignores proofs it cannot attribute. This lets stronger continuity evidence be layered on without a format change. A reader MAY additionally render the pinned head as a short human-comparable fingerprint for out-of-band comparison between clients.

One mechanism serves both log compaction (truncating a long history) and format migration (moving to a successor format): a signed, in-chain terminal entry that closes the log and names its successor.

• A terminal entry is an ordinary entry (13.5 Entry format, 13.7 The entry proof and its controller versionId, 13.8 Authorization all apply) whose parameters is exactly { "nextLog": { "method": ..., "scid": ... } }: the successor log's format identifier and its SCID. Its state MUST equal its predecessor's state -- a handover changes no resource state.
• The successor log's genesis parameters additionally carries previousLog: { "scid": ..., "head": ... }: the prior log's SCID and the versionId of the prior log's last regular entry -- the terminal entry's predecessor. (The reference cannot name the terminal entry itself: the terminal entry commits to the successor's SCID, so the successor's genesis must exist first.)
• For a compaction, the successor's genesis state is the full current state, so the successor log stands alone; the prior log may then be retained or discarded as evidence policy dictates.

A verifier crossing a handover MUST check the link from both sides: the terminal entry's nextLog.scid equals the successor's SCID and the methods are consistent with what each log's own genesis declares; the successor's previousLog.scid equals the prior log's SCID; and the successor's previousLog.head equals the versionId of the terminal entry's immediate predecessor -- that is, the terminal entry chains directly off the head the successor references. A successor served without this verifiable link MUST be refused as a continuity break.

Every verifier of this profile MUST recognize terminal entries and MUST refuse to append past one -- even though nothing currently emits them. This is what makes the mechanism a safe migration path: a v1 verifier meeting a handed-over log refuses to extend the frozen log, rather than continuing a history its author has closed.

The format identifier for this profile is the byte-significant string resource-log:0.1. The identifier is compared only for byte equality and never parsed: the 0.1 is part of the opaque identifier, not an orderable version number. A future revision of this profile is a different identifier reached only through the handover mechanism (13.12 The terminal handover entry), not a "greater version" of this one.

The identifier appears at two seams plus the pin, with a strict authority ordering:

1. Authoritative: parameters.method in the genesis entry. It is SCID-committed and proof-covered (13.6 Entry hashing and the SCID), which makes it the only downgrade-safe location: a host cannot alter it without changing the log's identity and breaking its genesis proof.
2. Payload schema: the state document's own type member (13.5 Entry format) -- the resource schema, versioned by the referencing profile independently of the log format.
3. The pin: the chain-head pin stores the method beside the SCID and head, so a served format switch outside the handover mechanism (13.12 The terminal handover entry) is refused as a continuity break rather than dispatched to a different verifier.

The roster reuses this profile's encryption descriptor verbatim: epoch entries (6.1 Epoch entries), epoch ids (6.2 Epoch identifiers), recipient entries (6.3 Recipient entries), and the roster operations (6.4 Roster operations) apply unchanged, as do the epoch-configuration integrity guards (7. Epoch-configuration integrity) and the log form (13.1 Point state and log form). What differs is what the epoch secret is for. A content collection's epoch secret seeds an epoch key that seals envelopes; the roster describes no content and seals nothing. Its epoch secret IS the payload: the current epoch's secret is the account's current user key, and holding a wrap in the current epoch is how an enrolled client receives it. Rotating the user key is the ordinary removal operation of 6.4 Roster operations -- a fresh epoch (a fresh user key) wrapped to each remaining recipient, currentEpoch repointed.

This composes with the first-epoch freshness rule (5.2 The first epoch) rather than excepting it. The user key is minted fresh with its epoch -- the two are one generation, so the roster's epoch secret is not, and does not derive from, any longer-lived key. The rule's account-level clause then does its work one level down: a content collection's epoch secret MUST NOT be, or be derived from, the user key, so no collection-epoch escrow can ever hand an external recipient the account key. The user key sits above collection epochs by wrap direction alone: its derived key-agreement key (14. Recipient-key derivation) receives wraps of collection epoch secrets; the user key itself is wrapped only in the roster.

The roster is a delivery channel, not a source of authority. Possession of the roster resource confers nothing: its entries hold public key ids and wrapped-key ciphertext only (6.3 Recipient entries), its recipients are resolved from the account controller document (15.2 Document-backed recipients), and under the log form authorship of every configuration is grounded in that document's keys. An implementation that keeps an epoch pin (7. Epoch-configuration integrity) SHOULD retain it even when it also pins the log head: the epoch pin still guards a client whose chain-head state was lost.

The roster's recipients are the account's enrolled wallet clients, and their key-agreement keys resolve from the verified account controller document rather than from the roster:

• A wrap is minted only to a key the verified document currently lists under keyAgreement. A recipient entry whose kid matches no such verification method MUST be dropped from resolution: it receives no wrap of any fresh epoch.
• A removal from the document is what retires a recipient. After an edit removes a client's verification methods, one rotation retires every current-epoch recipient the post-edit document no longer backs -- a converging operation a re-run completes, with no per-client pairing state required beyond the document itself.
• Where the roster is log-governed, that post-edit rotation carries a controller version at or past the edit, satisfying the sealing rule imposed after an authorized-writer removal (13.8 Authorization).

Resolving recipients from the document requires pairing each enrolled client with the keyAgreement verification method that is its own. The document may carry keyAgreement methods that belong to no enrolled client (a recovery key held against loss, for one), and nothing in [DID-CORE] ties a keyAgreement method to a sibling signing method. The controller marker is the write-side convention that records the tie in the document itself.

On the write side:

• Each enrolled client's keyAgreement verification method MUST be published with its controller set to the client's own did:key DID -- the DID of the client's Ed25519 signing key -- rather than the account DID. The method's id is unchanged by the marker.
• No other verification method carries the marker. Signing methods MUST keep the account DID as controller (a proof verifies against the controller the method names, and the account's proofs name the account). A keyAgreement method that belongs to no enrolled client, such as a recovery key, MUST keep the account DID as controller, so client listings and revocation removals never match it structurally.
• The marked key MUST be the canonical X25519 twin of the client's signing key, by the conversion of 14. Recipient-key derivation. An enrollment offering a key-agreement key that is not that twin MUST be refused before anything is published. The marker asserts that the key-agreement key belongs to that signing key; the twin check is what makes the assertion true of every method a conforming wallet publishes.

On the read side:

• A client's key-agreement key is the keyAgreement method whose controller equals the client's did:key DID. A client with no marked method has no resolvable key-agreement key; a reader MUST NOT fall back to deriving the twin. Refusing beats guessing: a guessed key would let a removal report success over a method still in the document.
• A removal MUST remove every keyAgreement method whose controller matches the removed client's did:key DID -- the full set, not a first match -- so a client that published more than one is fully retired.

The marker makes the document agree with the roster's kid shape. A recipient kid is did:key:z6Mk...#z6LS... (14. Recipient-key derivation): the controller DID, then its derived twin as the fragment. Under the marker, the document's keyAgreement method for that client carries exactly that controller DID. The DID half of a recipient's key id and the controller of its published method state the same fact, so a reader moving between the roster and the document never needs a pairing table.

Epoch rotation protects resources written after the rotation, and nothing else. It never claws back data a removed reader already fetched; resources stored under an earlier epoch remain readable to a removed reader that obtains their ciphertext (a backup, a colluding reader, a feed pull made before revocation); and it provides no post-compromise security for the removed reader's past traffic. Closing those gaps requires re-encrypting the collection under the new epoch -- a client-side bulk rewrite outside this profile. Documentation and libraries built on this profile MUST state these limitations rather than imply stronger guarantees.

The PWS capability governs fetch (server-enforced, immediate on revocation); epoch recipiency governs decrypt (mathematics, prospective only). Removing a reader means acting on both, rotate first (6.4 Roster operations); neither alone suffices, and documentation and error messages should never conflate them.

Because the binding checks of 8.6 Binding verification are unconditional and the profile admits no descriptor-less or epoch-less state, a tampering server has no fallback path to steer a reader onto: it cannot serve a stripped descriptor to induce direct-to-key sealing (5.4 An epoch-less descriptor is refused), and it cannot serve an unbound envelope and have it accepted.

pws.collection binds the Collection's id, which [PWS] scopes to the Space. Two collections carrying the same id in different Spaces are therefore not distinguished by the binding; they are distinguished by their keys alone (every epoch secret is fresh and per-collection, 5.2 The first epoch), so serving one such collection's metadata envelope as the other's fails as a key miss rather than as a named integrity failure. The space id is deliberately not bound: it is server-relative, and baking it into permanent envelope bytes would break decrypt across replicas and Space re-homing, for no gain against the attack that remains -- a server aliasing an entire collection, descriptor included, which no per-envelope binding can detect and which is descriptor-authenticity territory (the epoch pin and log form, 18.6 Configuration replay).

An epoch rotation is a write of the Collection Metadata object and emits no changes-feed entry. The unknown-epoch refresh of 9.2 Reads is the required remedy, and its once-per-collection-per-session guard is what keeps a foreign envelope from becoming a descriptor-refetch denial of service.

A served point-state descriptor carries nothing that lets a client detect the replay of an entire prior consistent configuration -- the server's checks bind its own storage, not what it chooses to serve. Deployments needing rollback protection keep client-side monotonic state (an epoch pin) or adopt the log form, whose hash chain and pinned head make any rollback a chain break (13.1 Point state and log form).

The resource log profile (13. The resource log profile) is designed against a host that serves stale, forged, truncated, or forked logs, and its guarantees come entirely from client-side recomputation: the chain from the SCID forward, every proof, and every authorization check against the independently verified controller document. Nothing served -- a stated head, a digest, a count -- is accepted without the log confirming it.

Three attacks remain outside the model, and stating them is part of the design:

First-contact substitution. A reader with no chain-head pin for a log accepts whichever verifying log the host serves first. The SCID prevents substitution under a known identity, and the authorization rule means any substitute must still be signed entirely by the account's own enrolled keys -- so what first contact actually risks is being shown a stale or truncated history that genuine writers produced, not a forged one. From the pin onward, rollback and forks are refused.

Per-client equivocation. A host can serve different (individually valid) extensions of one log to different clients that have not compared pins. Each client's own pin keeps its own view consistent; the gap is cross-client. The mitigations are layered rather than structural: any two clients that ever compare heads (or exchange logs) hold transferable, independently verifiable evidence of the equivocation, since every entry is signed and both logs claim one SCID (13.11 Head pinning); and the pin's extensible proof set leaves room for witness cosignatures as a policy upgrade without a format change. Writers are better protected than pure readers: the append procedure's read-back confirmation (13.10 Appending) means a host that hides one writer's entry from another forces a visible CAS conflict or a visible missing entry, not a silent split.

The revocation window. Between a membership-removing controller-document edit and a given log's sealing append (13.8 Authorization), the removed key can still extend that log under a pre-removal controller version. The window is the same one any multi-resource revocation cascade has; what the profile adds is that the window's state is durably visible (a head controller version predating the membership change) and closes idempotently by re-running the seal.

Removing a recipient rotates the epoch but never the blinding key (11.2 Fixed at provisioning), so a removed recipient keeps the ability to compute blinded tokens forever. Against the server alone this is harmless: the server gates the query profile behind a capability the removed reader no longer holds. The residual is collusion. A server willing to run the removed recipient's queries, or to hand it the stored indexed entries, lets it confirm guessed attribute values against any envelope in the collection, past and future writes alike. The asymmetry is accepted by design -- the alternative, rotating the blinding key on removal, would orphan the tokens of the collection's whole history -- and it grants no content, only equality tests against values the remover already guessed. Documentation and libraries built on this profile MUST state the asymmetry alongside the limitations of 18.1 The limitations of rotation.

Blinded tokens hide names and values but not structure. The server learns, by design, which envelopes carry equal values for equal attributes (matching is token equality), how many attributes each envelope indexes, and which tokens a querying reader asks about; unique declarations additionally mark which attributes claim collection-wide uniqueness. Deployments should index the few attributes they query, not everything they store.

The schema itself is sensitive for the same reason: attribute names and compound structure describe the collection's data model. That is why indexSchema lives inside the encrypted Collection Metadata envelope (11.5 The index schema) rather than among the Collection Metadata object's plaintext, server-visible members, and why the descriptor's hmac member carries a key id and wrapped bytes only, with no attribute names.