specs/vta/shared/v0_1/backup_transfer library

Classes

ChunkedDescriptor

A descriptor for the chunkedTrustTask algorithm. Carries no address and no bearer token: every chunk moves in a Trust Task document whose sender the transport authenticates, so possession of a token would add nothing and would be one more secret to leak.

ChunkManifest

The terms of a chunkedTrustTask transfer, committed before any chunk moves. On export the recipient states them in the descriptor; on import the producer pre-commits them in the request and the recipient echoes them. Either way the manifest arrives in a document whose proof is REQUIRED, so the per-chunk digests are authenticated by the party that computed them and each chunk can be verified — and a single bad chunk re-fetched or refused — on arrival rather than only after reassembly. Consistency rules JSON Schema cannot state: chunkCount MUST equal ceil(expectedSizeBytes / chunkSize) for the bundle the manifest describes, and chunkDigests MUST have exactly chunkCount items. A party receiving a manifest violating either MUST refuse it.

StreamDescriptor

A descriptor for a transfer that happens outside Trust Task documents, at an address the recipient publishes — the stream algorithm, and any other algorithm a recipient offers that is shaped as an address plus a bearer credential. Identical in members to the vta/backup/*/1.0 descriptor.

Extension Types

ChunkedDescriptorAlgorithm

Discriminates this shape from StreamDescriptor.

Typedefs

BundleDescriptor = Object?

The control-plane account of a bundle transfer: which algorithm, on what terms, until when. Exactly one of the two shapes — they are mutually exclusive, since StreamDescriptor requires transportUrl and transportToken and forbids chunks, and ChunkedDescriptor requires chunks and forbids both.

BundleId = String

Handle for a bundle across its whole lifecycle. Recipient-generated and unguessable, which is what lets an unauthorized reference be answered as not-found without confirming existence. Opaque: a producer quotes what it was given and must not derive, guess or enumerate one.

ChunkCount = int

Number of chunks in the bundle, equal to ceil(expectedSizeBytes / chunkSize). Bounded at 4096 so that the manifest itself — one digest per chunk — fits in the single document that carries it under the same message-size reasoning as a chunk.

ChunkData = String

The chunk's bytes, base64url-encoded without padding (RFC 4648 §5). Bounded at 349526 characters, the unpadded encoding of a 262144-byte chunk. These are bytes of the encrypted bundle, so a chunk read in isolation reveals nothing of the agent's state — but a complete set of chunks is the export, and is to be handled as such.

ChunkIndex = int

Zero-based position of a chunk within its bundle. Valid values are 0 to chunkCount − 1; an index outside that range is refused with chunkOutOfRange rather than validated here, because the bound depends on the bundle.

ChunkSize = int

Size in bytes of every chunk except the last, which carries the remainder and is between 1 and this value inclusive. The ceiling of 262144 (256 KiB) is normative and is derived in vta/backup/initiate-export/1.1 under Chunked transfer: it is the largest power of two whose get-chunk or put-chunk document still fits a 1 MiB mediator message after base64url encoding of data, DIDComm authcrypt encoding, and two nested forward wrappers. The floor of 16384 keeps a 1 GiB bundle within ChunkCount's ceiling at sizes a constrained transport can still choose.

DigestMultibase = String

A cryptographic digest as a multibase-encoded multihash — the encoding the W3C Verifiable Credentials Data Model 2.0 defines for digestMultibase, and the one did:webvh uses for its SCID and entry hashes. Multihash carries the hash algorithm in-band, so the value is self-describing and the wire format survives an algorithm change without a schema revision; multibase does the same for the base encoding, so a verifier never infers base58 from base64url by context. A bare hex string or a sha-256:-style prefix hard-codes one algorithm into the wire contract and is non-conforming here. This definition constrains the encoding only. What the digest is computed over is stated by each referencing field, because it differs legitimately: a digest over a JSON document is taken over its RFC 8785 (JCS) canonicalization, while a digest over an opaque artifact is taken over its bytes. A field whose input is a JSON document and which does not name a canonicalization is not reproducible. Restricted to the two multibase headers W3C Controlled Identifiers 1.0 §2.4 normatively requires — z (base58btc) and u (base64url-no-pad). CID permits others but states that "interoperability is not guaranteed between implementations using such values", and a registry whose purpose is interoperability should not mint digests a conforming verifier may be unable to read. The alphabets are enforced rather than assumed: base58btc excludes 0, O, I and l, and an earlier permissive pattern let three published examples carry digests that were not valid base58 at all. base58btc is RECOMMENDED, for consistency with did:key and did:webvh.

ExpectedSha256 = String

Lowercase hex SHA-256 of the whole bundle's bytes. Kept in the hex form the 1.0 descriptor published rather than moved to DigestMultibase, because it is an unchanged member of an existing descriptor and re-encoding it would break every stream producer for no gain in what it checks. For a chunked transfer it is the check over the reassembled bundle, applied after every chunk has verified individually, so that a correct set of chunks assembled in the wrong order is still caught.

ExpectedSizeBytes = int

Total byte count of the bundle. A zero-length bundle is not a degenerate success — nothing was serialized — so the floor is 1.

ExpiresAt = String

After which the bundle is collected: staged bytes discarded, tokens and chunk requests refused. Short by design. For a chunked transfer a recipient may move it later as chunks are exchanged, never past its own ceiling — each chunk response reports the current value.