@raybase/core 0.0.2 → 0.3.3

package/dist/backup-format.js

@@ -0,0 +1,1247 @@
+import { RaybaseBackupError, generateBackupDek, unwrapBackupDek, validateBackupJsonMetadata, validateBackupKeyEnvelope, wrapBackupDek } from "./backup-crypto.js";
+export const backupBinaryContentType = "application/vnd.raybase.backup";
+export const backupArchiveMagic = new Uint8Array([0x52, 0x41, 0x59, 0x42, 0x41, 0x53, 0x45, 0x32]); // RAYBASE2
+export const backupArchiveFormatVersion = 2;
+export const backupLogicalFormatVersion = 2;
+export const backupFrameFormatVersion = 1;
+export const backupLogicalRecordVersion = 1;
+export const defaultBackupFramePlaintextBytes = 1024 * 1024;
+export const backupFrameHeaderBytes = 12;
+export const backupFrameTagBytes = 16;
+export const backupFormatLimits = {
+    headerBytes: 64 * 1024,
+    logicalRecordBytes: 16 * 1024 * 1024,
+    ddlStatementBytes: 100 * 1024,
+    identifierBytes: 256,
+    columnsPerTable: 512,
+    valuesPerRow: 512,
+    textValueBytes: 16 * 1024 * 1024,
+    blobValueBytes: 16 * 1024 * 1024
+};
+const recordKind = {
+    "database-metadata": 0x01,
+    "table-schema": 0x02,
+    ddl: 0x03,
+    "table-start": 0x04,
+    row: 0x05,
+    "table-end": 0x06,
+    "logical-end": 0x7f
+};
+const requiredRecordFlag = 0x01;
+const recordHeaderBytes = 6;
+const archiveHeaderPrefixBytes = backupArchiveMagic.byteLength + 4;
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder("utf-8", { fatal: true });
+const identifierPattern = /^[A-Za-z0-9][A-Za-z0-9._:/-]*$/;
+const base64UrlPattern = /^[A-Za-z0-9_-]+$/;
+const sha256Pattern = /^[a-f0-9]{64}$/;
+function formatError(message, code = "BACKUP_ARCHIVE_CORRUPT") {
+    throw new RaybaseBackupError(code, message);
+}
+function plainObject(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value) || ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+        return formatError(`${label} must be an object`);
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return formatError(`${label} must be an object`);
+    return value;
+}
+function assertOnlyKeys(value, allowed, label) {
+    const allowedSet = new Set(allowed);
+    const extra = Object.keys(value).find((key) => !allowedSet.has(key));
+    if (extra)
+        formatError(`${label} contains unsupported field ${extra}`);
+}
+function boundedString(value, label, maxBytes = backupFormatLimits.identifierBytes) {
+    if (typeof value !== "string" || !value || textEncoder.encode(value).byteLength > maxBytes) {
+        return formatError(`${label} is missing or exceeds ${maxBytes} bytes`, "BACKUP_LIMIT_EXCEEDED");
+    }
+    return value;
+}
+function boundedIdentifier(value, label) {
+    const stringValue = boundedString(value, label);
+    if (!identifierPattern.test(stringValue))
+        return formatError(`${label} is invalid`);
+    return stringValue;
+}
+function encodeFormatBase64Url(value) {
+    let binary = "";
+    for (const byte of value)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function decodeCanonicalFormatBase64Url(value, label, byteLength) {
+    if (typeof value !== "string" || !base64UrlPattern.test(value)) {
+        return formatError(`${label} must be canonical unpadded base64url data`);
+    }
+    const padded = `${value.replace(/-/g, "+").replace(/_/g, "/")}${"=".repeat((4 - value.length % 4) % 4)}`;
+    let decoded;
+    try {
+        decoded = Uint8Array.from(atob(padded), (character) => character.charCodeAt(0));
+    }
+    catch {
+        return formatError(`${label} must be canonical unpadded base64url data`);
+    }
+    if (decoded.byteLength !== byteLength || encodeFormatBase64Url(decoded) !== value) {
+        decoded.fill(0);
+        return formatError(`${label} must encode exactly ${byteLength} bytes canonically`);
+    }
+    return decoded;
+}
+function nonNegativeInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        return formatError(`${label} must be a non-negative safe integer`);
+    return value;
+}
+function canonicalize(value) {
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            formatError("Canonical backup JSON cannot contain a non-finite number");
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonicalize).join(",")}]`;
+    const object = plainObject(value, "Canonical backup JSON");
+    return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${canonicalize(object[key])}`).join(",")}}`;
+}
+export function canonicalBackupJson(value) {
+    return textEncoder.encode(canonicalize(value));
+}
+function parseJson(bytes, label) {
+    try {
+        return JSON.parse(textDecoder.decode(bytes));
+    }
+    catch {
+        return formatError(`${label} is not valid UTF-8 JSON`);
+    }
+}
+function writeUint32(value) {
+    const bytes = new Uint8Array(4);
+    new DataView(bytes.buffer).setUint32(0, value, false);
+    return bytes;
+}
+function concatBytes(parts) {
+    const length = parts.reduce((total, part) => total + part.byteLength, 0);
+    const output = new Uint8Array(length);
+    let offset = 0;
+    for (const part of parts) {
+        output.set(part, offset);
+        offset += part.byteLength;
+    }
+    return output;
+}
+function normalizeHeader(value) {
+    const object = plainObject(value, "Backup archive header");
+    assertOnlyKeys(object, ["format", "archiveId", "product", "target", "targetId", "createdAt", "logical", "encryption", "keyEnvelope"], "Backup archive header");
+    if (object.format !== 2)
+        formatError("Backup archive format is unsupported", "BACKUP_ARCHIVE_VERSION_UNSUPPORTED");
+    if (object.product !== "core" && object.product !== "pro")
+        formatError("Backup archive product is unsupported");
+    if (object.target !== "core" && object.target !== "control-plane" && object.target !== "app-data")
+        formatError("Backup archive target is unsupported");
+    const logical = plainObject(object.logical, "Backup logical descriptor");
+    assertOnlyKeys(logical, ["format", "recordVersion", "encoding"], "Backup logical descriptor");
+    if (logical.format !== 2 || logical.recordVersion !== 1 || logical.encoding !== "raybase-logical") {
+        formatError("Backup logical record version is unsupported", "BACKUP_RECORD_VERSION_UNSUPPORTED");
+    }
+    const encryption = plainObject(object.encryption, "Backup encryption descriptor");
+    assertOnlyKeys(encryption, ["scheme", "frameVersion", "framePlaintextBytes", "noncePrefix"], "Backup encryption descriptor");
+    if (encryption.scheme !== "AES-256-GCM" || encryption.frameVersion !== 1) {
+        formatError("Backup frame version is unsupported", "BACKUP_FRAME_VERSION_UNSUPPORTED");
+    }
+    if (!Number.isInteger(encryption.framePlaintextBytes) || encryption.framePlaintextBytes < 1024 || encryption.framePlaintextBytes > 16 * 1024 * 1024) {
+        formatError("Backup frame plaintext size is invalid", "BACKUP_LIMIT_EXCEEDED");
+    }
+    const noncePrefixBytes = decodeCanonicalFormatBase64Url(encryption.noncePrefix, "Backup nonce prefix", 8);
+    noncePrefixBytes.fill(0);
+    const createdAt = boundedString(object.createdAt, "Backup created time", 64);
+    if (!Number.isFinite(Date.parse(createdAt)))
+        formatError("Backup created time is invalid");
+    return {
+        format: 2,
+        archiveId: boundedIdentifier(object.archiveId, "Backup archive id"),
+        product: object.product,
+        target: object.target,
+        targetId: boundedIdentifier(object.targetId, "Backup target id"),
+        createdAt,
+        logical: { format: 2, recordVersion: 1, encoding: "raybase-logical" },
+        encryption: {
+            scheme: "AES-256-GCM",
+            frameVersion: 1,
+            framePlaintextBytes: encryption.framePlaintextBytes,
+            noncePrefix: encryption.noncePrefix
+        },
+        keyEnvelope: validateBackupKeyEnvelope(object.keyEnvelope)
+    };
+}
+/**
+ * Encode the cleartext, authenticated format-2 archive header.
+ */
+export function encodeBackupArchiveHeader(header) {
+    const normalized = normalizeHeader(header);
+    const body = canonicalBackupJson(normalized);
+    if (body.byteLength > backupFormatLimits.headerBytes)
+        formatError("Backup archive header exceeds its byte limit", "BACKUP_LIMIT_EXCEEDED");
+    return concatBytes([backupArchiveMagic, writeUint32(body.byteLength), body]);
+}
+export function decodeBackupArchiveHeader(bytes) {
+    if (bytes.byteLength < archiveHeaderPrefixBytes)
+        formatError("Backup archive header is truncated", "BACKUP_ARCHIVE_TRUNCATED");
+    for (let index = 0; index < backupArchiveMagic.byteLength; index += 1) {
+        if (bytes[index] !== backupArchiveMagic[index])
+            formatError("Backup archive magic is invalid", "BACKUP_ARCHIVE_VERSION_UNSUPPORTED");
+    }
+    const bodyLength = new DataView(bytes.buffer, bytes.byteOffset + backupArchiveMagic.byteLength, 4).getUint32(0, false);
+    if (bodyLength > backupFormatLimits.headerBytes)
+        formatError("Backup archive header exceeds its byte limit", "BACKUP_LIMIT_EXCEEDED");
+    const bytesRead = archiveHeaderPrefixBytes + bodyLength;
+    if (bytes.byteLength < bytesRead)
+        formatError("Backup archive header is truncated", "BACKUP_ARCHIVE_TRUNCATED");
+    const body = bytes.subarray(archiveHeaderPrefixBytes, bytesRead);
+    const header = normalizeHeader(parseJson(body, "Backup archive header"));
+    const canonical = canonicalBackupJson(header);
+    if (canonical.byteLength !== body.byteLength || canonical.some((value, index) => value !== body[index])) {
+        formatError("Backup archive header is not canonically encoded");
+    }
+    return { header, bytesRead };
+}
+function normalizeDatabaseMetadata(value) {
+    const object = plainObject(value, "Database metadata record");
+    assertOnlyKeys(object, ["kind", "applicationId", "userVersion", "schemaFingerprint", "metadata"], "Database metadata record");
+    const record = {
+        kind: "database-metadata",
+        schemaFingerprint: boundedIdentifier(object.schemaFingerprint, "Database schema fingerprint")
+    };
+    if (object.applicationId !== undefined)
+        record.applicationId = nonNegativeInteger(object.applicationId, "Database application id");
+    if (object.userVersion !== undefined)
+        record.userVersion = nonNegativeInteger(object.userVersion, "Database user version");
+    if (object.metadata !== undefined)
+        record.metadata = validateBackupJsonMetadata(object.metadata, "Database backup metadata");
+    return record;
+}
+function normalizeColumn(value, index) {
+    const object = plainObject(value, `Table column ${index}`);
+    assertOnlyKeys(object, ["name", "declaredType"], `Table column ${index}`);
+    const column = { name: boundedString(object.name, `Table column ${index} name`) };
+    if (object.declaredType !== undefined)
+        column.declaredType = boundedString(object.declaredType, `Table column ${index} declared type`, 128);
+    return column;
+}
+function normalizeTableSchema(value) {
+    const object = plainObject(value, "Table schema record");
+    assertOnlyKeys(object, ["kind", "tableId", "tableName", "columns", "insertSql", "pagination"], "Table schema record");
+    if (!Array.isArray(object.columns) || object.columns.length < 1 || object.columns.length > backupFormatLimits.columnsPerTable) {
+        formatError("Table schema column count is invalid", "BACKUP_LIMIT_EXCEEDED");
+    }
+    const columns = object.columns.map(normalizeColumn);
+    if (new Set(columns.map((column) => column.name)).size !== columns.length)
+        formatError("Table schema column names must be unique");
+    const pagination = plainObject(object.pagination, "Table pagination descriptor");
+    const paginationKind = pagination.kind;
+    let normalizedPagination;
+    if (paginationKind === "rowid") {
+        assertOnlyKeys(pagination, ["kind", "column"], "Table pagination descriptor");
+        normalizedPagination = { kind: "rowid", column: boundedString(pagination.column, "Table rowid column") };
+    }
+    else if (paginationKind === "primary-key") {
+        assertOnlyKeys(pagination, ["kind", "columns"], "Table pagination descriptor");
+        if (!Array.isArray(pagination.columns) || pagination.columns.length < 1 || pagination.columns.length > columns.length) {
+            formatError("Table primary-key pagination columns are invalid");
+        }
+        normalizedPagination = {
+            kind: "primary-key",
+            columns: pagination.columns.map((column, index) => boundedString(column, `Table primary-key column ${index}`))
+        };
+    }
+    else {
+        return formatError("Table pagination kind is unsupported");
+    }
+    const insertSql = boundedString(object.insertSql, "Table insert statement", backupFormatLimits.ddlStatementBytes);
+    return {
+        kind: "table-schema",
+        tableId: boundedIdentifier(object.tableId, "Table id"),
+        tableName: boundedString(object.tableName, "Table name"),
+        columns,
+        insertSql,
+        pagination: normalizedPagination
+    };
+}
+function normalizeDdl(value) {
+    const object = plainObject(value, "DDL record");
+    assertOnlyKeys(object, ["kind", "sql"], "DDL record");
+    return { kind: "ddl", sql: boundedString(object.sql, "DDL statement", backupFormatLimits.ddlStatementBytes) };
+}
+function normalizeBoundary(value, kind) {
+    const object = plainObject(value, `${kind} record`);
+    assertOnlyKeys(object, ["kind", "tableId"], `${kind} record`);
+    return { kind, tableId: boundedIdentifier(object.tableId, `${kind} table id`) };
+}
+function normalizeLogicalEnd(value) {
+    const object = plainObject(value, "Logical end record");
+    assertOnlyKeys(object, ["kind", "recordCount", "rowCount", "tableCount", "plaintextSha256"], "Logical end record");
+    if (typeof object.plaintextSha256 !== "string" || !sha256Pattern.test(object.plaintextSha256)) {
+        formatError("Logical end plaintext digest is invalid");
+    }
+    return {
+        kind: "logical-end",
+        recordCount: nonNegativeInteger(object.recordCount, "Logical record count"),
+        rowCount: nonNegativeInteger(object.rowCount, "Logical row count"),
+        tableCount: nonNegativeInteger(object.tableCount, "Logical table count"),
+        plaintextSha256: object.plaintextSha256
+    };
+}
+function encodeTypedValue(value) {
+    switch (value.type) {
+        case "null":
+            return new Uint8Array([0]);
+        case "integer": {
+            if (value.value < -(1n << 63n) || value.value > (1n << 63n) - 1n)
+                formatError("Logical integer is outside signed 64-bit range");
+            const bytes = new Uint8Array(9);
+            bytes[0] = 1;
+            new DataView(bytes.buffer).setBigInt64(1, value.value, false);
+            return bytes;
+        }
+        case "real": {
+            if (!Number.isFinite(value.value))
+                formatError("Logical real must be finite");
+            const bytes = new Uint8Array(9);
+            bytes[0] = 2;
+            new DataView(bytes.buffer).setFloat64(1, value.value, false);
+            return bytes;
+        }
+        case "text": {
+            const body = textEncoder.encode(value.value);
+            if (body.byteLength > backupFormatLimits.textValueBytes)
+                formatError("Logical text exceeds its byte limit", "BACKUP_LIMIT_EXCEEDED");
+            return concatBytes([new Uint8Array([3]), writeUint32(body.byteLength), body]);
+        }
+        case "blob": {
+            if (!(value.value instanceof Uint8Array))
+                formatError("Logical BLOB must be a Uint8Array");
+            if (value.value.byteLength > backupFormatLimits.blobValueBytes)
+                formatError("Logical BLOB exceeds its byte limit", "BACKUP_LIMIT_EXCEEDED");
+            return concatBytes([new Uint8Array([4]), writeUint32(value.value.byteLength), value.value]);
+        }
+    }
+}
+function encodeRow(record) {
+    const tableId = textEncoder.encode(boundedIdentifier(record.tableId, "Row table id"));
+    if (tableId.byteLength > 0xffff)
+        formatError("Row table id exceeds its byte limit", "BACKUP_LIMIT_EXCEEDED");
+    if (!Array.isArray(record.values) || record.values.length > backupFormatLimits.valuesPerRow) {
+        formatError("Row value count exceeds its limit", "BACKUP_LIMIT_EXCEEDED");
+    }
+    const prefix = new Uint8Array(2 + tableId.byteLength + 2);
+    const view = new DataView(prefix.buffer);
+    view.setUint16(0, tableId.byteLength, false);
+    prefix.set(tableId, 2);
+    view.setUint16(2 + tableId.byteLength, record.values.length, false);
+    return concatBytes([prefix, ...record.values.map(encodeTypedValue)]);
+}
+function readLengthPrefixedValue(payload, state, label, maxBytes) {
+    if (state.offset + 4 > payload.byteLength)
+        formatError(`${label} length is truncated`, "BACKUP_ARCHIVE_TRUNCATED");
+    const length = new DataView(payload.buffer, payload.byteOffset + state.offset, 4).getUint32(0, false);
+    state.offset += 4;
+    if (length > maxBytes)
+        formatError(`${label} exceeds its byte limit`, "BACKUP_LIMIT_EXCEEDED");
+    if (state.offset + length > payload.byteLength)
+        formatError(`${label} bytes are truncated`, "BACKUP_ARCHIVE_TRUNCATED");
+    const value = payload.slice(state.offset, state.offset + length);
+    state.offset += length;
+    return value;
+}
+function decodeTypedValue(payload, state) {
+    if (state.offset >= payload.byteLength)
+        formatError("Logical value tag is truncated", "BACKUP_ARCHIVE_TRUNCATED");
+    const tag = payload[state.offset++];
+    if (tag === 0)
+        return { type: "null" };
+    if (tag === 1) {
+        if (state.offset + 8 > payload.byteLength)
+            formatError("Logical integer is truncated", "BACKUP_ARCHIVE_TRUNCATED");
+        const value = new DataView(payload.buffer, payload.byteOffset + state.offset, 8).getBigInt64(0, false);
+        state.offset += 8;
+        return { type: "integer", value };
+    }
+    if (tag === 2) {
+        if (state.offset + 8 > payload.byteLength)
+            formatError("Logical real is truncated", "BACKUP_ARCHIVE_TRUNCATED");
+        const value = new DataView(payload.buffer, payload.byteOffset + state.offset, 8).getFloat64(0, false);
+        state.offset += 8;
+        if (!Number.isFinite(value))
+            formatError("Logical real must be finite");
+        return { type: "real", value };
+    }
+    if (tag === 3) {
+        const bytes = readLengthPrefixedValue(payload, state, "Logical text", backupFormatLimits.textValueBytes);
+        try {
+            return { type: "text", value: textDecoder.decode(bytes) };
+        }
+        catch {
+            return formatError("Logical text is not valid UTF-8");
+        }
+    }
+    if (tag === 4)
+        return { type: "blob", value: readLengthPrefixedValue(payload, state, "Logical BLOB", backupFormatLimits.blobValueBytes) };
+    return formatError(`Logical value tag ${tag} is unsupported`, "BACKUP_RECORD_VERSION_UNSUPPORTED");
+}
+function decodeRow(payload) {
+    if (payload.byteLength < 4)
+        formatError("Row record is truncated", "BACKUP_ARCHIVE_TRUNCATED");
+    const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+    const tableIdLength = view.getUint16(0, false);
+    if (2 + tableIdLength + 2 > payload.byteLength)
+        formatError("Row table id is truncated", "BACKUP_ARCHIVE_TRUNCATED");
+    let tableId;
+    try {
+        tableId = textDecoder.decode(payload.subarray(2, 2 + tableIdLength));
+    }
+    catch {
+        return formatError("Row table id is not valid UTF-8");
+    }
+    boundedIdentifier(tableId, "Row table id");
+    const valueCount = view.getUint16(2 + tableIdLength, false);
+    if (valueCount > backupFormatLimits.valuesPerRow)
+        formatError("Row value count exceeds its limit", "BACKUP_LIMIT_EXCEEDED");
+    const state = { offset: 2 + tableIdLength + 2 };
+    const values = [];
+    for (let index = 0; index < valueCount; index += 1)
+        values.push(decodeTypedValue(payload, state));
+    if (state.offset !== payload.byteLength)
+        formatError("Row record contains trailing bytes");
+    return { kind: "row", tableId, values };
+}
+function encodeRecordPayload(record) {
+    switch (record.kind) {
+        case "database-metadata":
+            return canonicalBackupJson(normalizeDatabaseMetadata(record));
+        case "table-schema":
+            return canonicalBackupJson(normalizeTableSchema(record));
+        case "ddl":
+            return canonicalBackupJson(normalizeDdl(record));
+        case "table-start":
+        case "table-end":
+            return canonicalBackupJson(normalizeBoundary(record, record.kind));
+        case "row":
+            return encodeRow(record);
+        case "logical-end":
+            return canonicalBackupJson(normalizeLogicalEnd(record));
+    }
+}
+export function encodeBackupLogicalRecord(record) {
+    const payload = encodeRecordPayload(record);
+    if (payload.byteLength > backupFormatLimits.logicalRecordBytes)
+        formatError("Logical record exceeds its byte limit", "BACKUP_LIMIT_EXCEEDED");
+    const header = new Uint8Array(recordHeaderBytes);
+    header[0] = recordKind[record.kind];
+    header[1] = requiredRecordFlag;
+    new DataView(header.buffer).setUint32(2, payload.byteLength, false);
+    return concatBytes([header, payload]);
+}
+function decodeJsonRecord(payload, normalize, label) {
+    const value = normalize(parseJson(payload, label));
+    const canonical = canonicalBackupJson(value);
+    if (canonical.byteLength !== payload.byteLength || canonical.some((byte, index) => byte !== payload[index])) {
+        formatError(`${label} is not canonically encoded`);
+    }
+    return value;
+}
+export class BackupLogicalDecoder {
+    #buffer = new Uint8Array(0);
+    #state = {
+        metadataSeen: false,
+        schemas: new Map(),
+        currentTable: null,
+        ended: false,
+        recordCount: 0,
+        rowCount: 0,
+        tableCount: 0
+    };
+    push(chunk) {
+        if (!(chunk instanceof Uint8Array))
+            formatError("Logical decoder input must be a Uint8Array");
+        if (this.#state.ended && chunk.byteLength > 0)
+            formatError("Logical stream contains records after its end");
+        if (this.#buffer.byteLength + chunk.byteLength > backupFormatLimits.logicalRecordBytes + recordHeaderBytes) {
+            formatError("Logical decoder retained bytes exceed the record limit", "BACKUP_LIMIT_EXCEEDED");
+        }
+        this.#buffer = new Uint8Array(concatBytes([this.#buffer, chunk]));
+        const records = [];
+        while (this.#buffer.byteLength >= recordHeaderBytes) {
+            const view = new DataView(this.#buffer.buffer, this.#buffer.byteOffset, recordHeaderBytes);
+            const kind = this.#buffer[0];
+            const flags = this.#buffer[1];
+            const length = view.getUint32(2, false);
+            if ((flags & ~requiredRecordFlag) !== 0)
+                formatError("Logical record flags are unsupported", "BACKUP_RECORD_VERSION_UNSUPPORTED");
+            if (length > backupFormatLimits.logicalRecordBytes)
+                formatError("Logical record exceeds its byte limit", "BACKUP_LIMIT_EXCEEDED");
+            if (this.#buffer.byteLength < recordHeaderBytes + length)
+                break;
+            const payload = this.#buffer.slice(recordHeaderBytes, recordHeaderBytes + length);
+            this.#buffer = this.#buffer.slice(recordHeaderBytes + length);
+            if (this.#state.ended)
+                formatError("Logical stream contains records after its end");
+            const record = this.#decodeRecord(kind, flags, payload);
+            if (record) {
+                this.#accept(record);
+                records.push(record);
+            }
+            else {
+                this.#state.recordCount += 1;
+            }
+        }
+        return records;
+    }
+    finish() {
+        if (this.#buffer.byteLength > 0)
+            formatError("Logical stream ends inside a record", "BACKUP_ARCHIVE_TRUNCATED");
+        if (!this.#state.ended)
+            formatError("Logical stream is missing its end record", "BACKUP_ARCHIVE_TRUNCATED");
+    }
+    #decodeRecord(kind, flags, payload) {
+        if (kind === recordKind["database-metadata"])
+            return decodeJsonRecord(payload, normalizeDatabaseMetadata, "Database metadata record");
+        if (kind === recordKind["table-schema"])
+            return decodeJsonRecord(payload, normalizeTableSchema, "Table schema record");
+        if (kind === recordKind.ddl)
+            return decodeJsonRecord(payload, normalizeDdl, "DDL record");
+        if (kind === recordKind["table-start"])
+            return decodeJsonRecord(payload, (value) => normalizeBoundary(value, "table-start"), "Table start record");
+        if (kind === recordKind.row)
+            return decodeRow(payload);
+        if (kind === recordKind["table-end"])
+            return decodeJsonRecord(payload, (value) => normalizeBoundary(value, "table-end"), "Table end record");
+        if (kind === recordKind["logical-end"])
+            return decodeJsonRecord(payload, normalizeLogicalEnd, "Logical end record");
+        if ((flags & requiredRecordFlag) !== 0)
+            formatError(`Required logical record kind ${kind} is unsupported`, "BACKUP_RECORD_VERSION_UNSUPPORTED");
+        return null;
+    }
+    #accept(record) {
+        if (this.#state.ended)
+            formatError("Logical stream contains records after its end");
+        if (record.kind === "logical-end") {
+            if (this.#state.currentTable)
+                formatError("Logical stream ended before the current table closed");
+            if (record.recordCount !== this.#state.recordCount ||
+                record.rowCount !== this.#state.rowCount ||
+                record.tableCount !== this.#state.tableCount) {
+                formatError("Logical end totals do not match decoded records");
+            }
+            this.#state.ended = true;
+            return;
+        }
+        this.#state.recordCount += 1;
+        if (record.kind === "database-metadata") {
+            if (this.#state.metadataSeen)
+                formatError("Logical stream contains duplicate database metadata");
+            if (this.#state.schemas.size > 0 || this.#state.currentTable)
+                formatError("Database metadata must precede table records");
+            this.#state.metadataSeen = true;
+            return;
+        }
+        if (record.kind === "table-schema") {
+            if (this.#state.currentTable)
+                formatError("Table schema cannot appear inside table rows");
+            if (this.#state.schemas.has(record.tableId))
+                formatError(`Logical stream contains duplicate schema ${record.tableId}`);
+            this.#state.schemas.set(record.tableId, record);
+            return;
+        }
+        if (record.kind === "ddl") {
+            if (this.#state.currentTable)
+                formatError("DDL cannot appear inside table rows");
+            return;
+        }
+        if (record.kind === "table-start") {
+            if (this.#state.currentTable)
+                formatError("Logical stream contains nested table starts");
+            if (!this.#state.schemas.has(record.tableId))
+                formatError(`Table ${record.tableId} started before its schema`);
+            this.#state.currentTable = record.tableId;
+            return;
+        }
+        if (record.kind === "row") {
+            const schema = this.#state.schemas.get(record.tableId);
+            if (!schema)
+                formatError(`Row for ${record.tableId} appeared before its schema`);
+            if (this.#state.currentTable !== record.tableId)
+                formatError(`Row for ${record.tableId} appeared outside its table boundary`);
+            if (record.values.length !== schema.columns.length)
+                formatError(`Row for ${record.tableId} has the wrong value count`);
+            this.#state.rowCount += 1;
+            return;
+        }
+        if (record.kind === "table-end") {
+            if (this.#state.currentTable !== record.tableId)
+                formatError(`Table end for ${record.tableId} does not match the active table`);
+            this.#state.currentTable = null;
+            this.#state.tableCount += 1;
+        }
+    }
+}
+const backupDataFrameKind = 1;
+const backupFinalFrameKind = 2;
+const backupFinalFrameMaxBytes = 4096;
+const maximumUint32 = 0xffff_ffff;
+const frameAadDomain = textEncoder.encode("raybase-backup-frame-v1\0");
+function backupOwnedBuffer(value) {
+    const copy = new Uint8Array(value.byteLength);
+    copy.set(value);
+    return copy.buffer;
+}
+function sha256HexBytes(value) {
+    return Array.from(value, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function equalBackupBytes(left, right) {
+    if (left.byteLength !== right.byteLength)
+        return false;
+    let difference = 0;
+    for (let index = 0; index < left.byteLength; index += 1)
+        difference |= left[index] ^ right[index];
+    return difference === 0;
+}
+/**
+ * Workers-native bounded SHA-256 sink. Node-based unit tests can inject an
+ * equivalent incremental factory without changing production randomness or
+ * buffering an archive.
+ */
+export function createBackupSha256Digest() {
+    const DigestStreamConstructor = crypto.DigestStream;
+    if (typeof DigestStreamConstructor === "undefined") {
+        throw new RaybaseBackupError("BACKUP_ENCRYPTION_NOT_CONFIGURED", "This runtime does not provide the streaming SHA-256 primitive required for encrypted backups");
+    }
+    const stream = new DigestStreamConstructor("SHA-256");
+    const writer = stream.getWriter();
+    let finished = false;
+    return {
+        async write(bytes) {
+            if (finished)
+                throw new RaybaseBackupError("BACKUP_ARCHIVE_CORRUPT", "Backup digest is already finalized");
+            await writer.write(backupOwnedBuffer(bytes));
+        },
+        async finish() {
+            if (finished)
+                throw new RaybaseBackupError("BACKUP_ARCHIVE_CORRUPT", "Backup digest is already finalized");
+            finished = true;
+            try {
+                await writer.close();
+                return new Uint8Array(await stream.digest);
+            }
+            catch (error) {
+                try {
+                    await stream.digest;
+                }
+                catch {
+                    // Observe the paired digest rejection before preserving the primary
+                    // close/finalization failure.
+                }
+                throw error;
+            }
+        },
+        async abort(reason) {
+            if (finished)
+                return;
+            finished = true;
+            try {
+                await writer.abort(reason);
+            }
+            catch {
+                // Digest teardown is best effort after the primary failure.
+            }
+            try {
+                await stream.digest;
+            }
+            catch {
+                // Aborting a DigestStream rejects its digest promise with the same
+                // primary reason; observe it so runtimes do not report it unhandled.
+            }
+        }
+    };
+}
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((resolvePromise, rejectPromise) => {
+        resolve = resolvePromise;
+        reject = rejectPromise;
+    });
+    return { promise, resolve, reject };
+}
+function assertSafeCounter(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        formatError(`${label} exceeds the safe integer limit`, "BACKUP_LIMIT_EXCEEDED");
+    }
+}
+function normalizeLogicalTotals(value) {
+    return {
+        recordCount: nonNegativeInteger(value.recordCount, "Backup logical record count"),
+        rowCount: nonNegativeInteger(value.rowCount, "Backup logical row count"),
+        tableCount: nonNegativeInteger(value.tableCount, "Backup logical table count")
+    };
+}
+function frameHeader(kind, sequence, plaintextBytes) {
+    const bytes = new Uint8Array(backupFrameHeaderBytes);
+    const view = new DataView(bytes.buffer);
+    bytes[0] = backupFrameFormatVersion;
+    bytes[1] = kind;
+    view.setUint16(2, 0, false);
+    view.setUint32(4, sequence, false);
+    view.setUint32(8, plaintextBytes, false);
+    return bytes;
+}
+function frameNonce(prefix, sequence) {
+    const nonce = new Uint8Array(12);
+    nonce.set(prefix, 0);
+    new DataView(nonce.buffer).setUint32(8, sequence, false);
+    return nonce;
+}
+function frameAdditionalData(headerSha256, header) {
+    return concatBytes([frameAadDomain, headerSha256, header]);
+}
+function decodeCanonicalFinalFrame(value) {
+    const parsed = plainObject(parseJson(value, "Backup final frame"), "Backup final frame");
+    assertOnlyKeys(parsed, ["version", "frameCount", "plaintextBytes", "recordCount", "rowCount", "tableCount", "plaintextSha256"], "Backup final frame");
+    if (parsed.version !== 1)
+        formatError("Backup final frame version is unsupported", "BACKUP_FRAME_VERSION_UNSUPPORTED");
+    if (typeof parsed.plaintextSha256 !== "string" || !sha256Pattern.test(parsed.plaintextSha256)) {
+        formatError("Backup final frame plaintext digest is invalid");
+    }
+    const normalized = {
+        version: 1,
+        frameCount: nonNegativeInteger(parsed.frameCount, "Backup final frame count"),
+        plaintextBytes: nonNegativeInteger(parsed.plaintextBytes, "Backup final plaintext bytes"),
+        recordCount: nonNegativeInteger(parsed.recordCount, "Backup final logical record count"),
+        rowCount: nonNegativeInteger(parsed.rowCount, "Backup final logical row count"),
+        tableCount: nonNegativeInteger(parsed.tableCount, "Backup final logical table count"),
+        plaintextSha256: parsed.plaintextSha256
+    };
+    const canonical = canonicalBackupJson(normalized);
+    if (!equalBackupBytes(canonical, value))
+        formatError("Backup final frame is not canonically encoded");
+    return normalized;
+}
+async function importBackupFrameKey(raw, usage) {
+    return crypto.subtle.importKey("raw", backupOwnedBuffer(raw), { name: "AES-GCM" }, false, [usage]);
+}
+function operationContext(identity, purpose, signal, environment) {
+    return {
+        ...identity,
+        purpose,
+        signal,
+        ...(environment ? { environment } : {})
+    };
+}
+export async function createBackupArchiveEncryptor(options) {
+    const framePlaintextBytes = options.framePlaintextBytes ?? defaultBackupFramePlaintextBytes;
+    if (!Number.isInteger(framePlaintextBytes) || framePlaintextBytes < 1024 || framePlaintextBytes > 16 * 1024 * 1024) {
+        formatError("Backup frame plaintext size is invalid", "BACKUP_LIMIT_EXCEEDED");
+    }
+    const maximumFrameSequence = options.maximumFrameSequence ?? maximumUint32;
+    if (!Number.isInteger(maximumFrameSequence) || maximumFrameSequence < 0 || maximumFrameSequence > maximumUint32) {
+        formatError("Backup frame sequence limit is invalid", "BACKUP_LIMIT_EXCEEDED");
+    }
+    const signal = options.signal ?? new AbortController().signal;
+    if (signal.aborted)
+        throw new RaybaseBackupError("BACKUP_PROVIDER_UNAVAILABLE", "Backup encryption was aborted");
+    const context = operationContext(options.identity, "wrap", signal, options.environment);
+    const dek = generateBackupDek(options.randomSource);
+    let envelope;
+    let frameKey;
+    try {
+        envelope = await wrapBackupDek({
+            dek,
+            context,
+            providers: options.providers,
+            ...(options.participants ? { participants: options.participants } : {}),
+            ...(options.randomSource ? { randomSource: options.randomSource } : {})
+        });
+        frameKey = await importBackupFrameKey(dek, "encrypt");
+    }
+    finally {
+        dek.fill(0);
+    }
+    const noncePrefix = options.randomSource
+        ? options.randomSource(8).slice()
+        : crypto.getRandomValues(new Uint8Array(8));
+    if (noncePrefix.byteLength !== 8)
+        formatError("Backup randomness source must return exactly 8 bytes", "BACKUP_LIMIT_EXCEEDED");
+    const header = {
+        format: 2,
+        ...options.identity,
+        logical: {
+            format: 2,
+            recordVersion: 1,
+            encoding: "raybase-logical"
+        },
+        encryption: {
+            scheme: "AES-256-GCM",
+            frameVersion: 1,
+            framePlaintextBytes,
+            noncePrefix: encodeFormatBase64Url(noncePrefix)
+        },
+        keyEnvelope: envelope
+    };
+    noncePrefix.fill(0);
+    const headerBytes = encodeBackupArchiveHeader(header);
+    const headerSha256 = new Uint8Array(await crypto.subtle.digest("SHA-256", backupOwnedBuffer(headerBytes)));
+    const decodedNoncePrefix = decodeCanonicalFormatBase64Url(header.encryption.noncePrefix, "Backup nonce prefix", 8);
+    const digestFactory = options.digestFactory ?? createBackupSha256Digest;
+    const plaintextDigest = digestFactory();
+    const ciphertextDigest = digestFactory();
+    const completionState = deferred();
+    let sequence = 0;
+    let plaintextBytes = 0;
+    let ciphertextBytes = 0;
+    let pending = new Uint8Array(0);
+    let failed = false;
+    const abortDigests = async (reason) => {
+        await Promise.allSettled([
+            plaintextDigest.abort(reason),
+            ciphertextDigest.abort(reason)
+        ]);
+    };
+    const emitCiphertext = async (controller, bytes) => {
+        assertSafeCounter(ciphertextBytes + bytes.byteLength, "Backup ciphertext byte count");
+        await ciphertextDigest.write(bytes);
+        ciphertextBytes += bytes.byteLength;
+        controller.enqueue(bytes);
+    };
+    const encryptFrame = async (kind, framePlaintext, controller) => {
+        if (sequence > maximumFrameSequence) {
+            formatError("Backup frame sequence space is exhausted before finalization", "BACKUP_LIMIT_EXCEEDED");
+        }
+        if (kind === backupDataFrameKind && sequence >= maximumFrameSequence) {
+            formatError("Backup frame sequence space is exhausted before nonce reuse", "BACKUP_LIMIT_EXCEEDED");
+        }
+        const wireHeader = frameHeader(kind, sequence, framePlaintext.byteLength);
+        const nonce = frameNonce(decodedNoncePrefix, sequence);
+        let ciphertext;
+        try {
+            ciphertext = new Uint8Array(await crypto.subtle.encrypt({
+                name: "AES-GCM",
+                iv: backupOwnedBuffer(nonce),
+                additionalData: backupOwnedBuffer(frameAdditionalData(headerSha256, wireHeader)),
+                tagLength: 128
+            }, frameKey, backupOwnedBuffer(framePlaintext)));
+        }
+        finally {
+            nonce.fill(0);
+        }
+        try {
+            await emitCiphertext(controller, concatBytes([wireHeader, ciphertext]));
+        }
+        finally {
+            ciphertext.fill(0);
+        }
+        sequence += 1;
+    };
+    const transform = new TransformStream({
+        async start(controller) {
+            try {
+                await emitCiphertext(controller, headerBytes);
+            }
+            catch (error) {
+                failed = true;
+                decodedNoncePrefix.fill(0);
+                headerSha256.fill(0);
+                await abortDigests(error);
+                completionState.reject(error);
+                throw error;
+            }
+        },
+        async transform(chunk, controller) {
+            try {
+                if (signal.aborted)
+                    throw new RaybaseBackupError("BACKUP_PROVIDER_UNAVAILABLE", "Backup encryption was aborted");
+                if (!(chunk instanceof Uint8Array))
+                    formatError("Backup encryptor input must be a Uint8Array");
+                if (chunk.byteLength === 0)
+                    return;
+                assertSafeCounter(plaintextBytes + chunk.byteLength, "Backup plaintext byte count");
+                for (let digestOffset = 0; digestOffset < chunk.byteLength; digestOffset += framePlaintextBytes) {
+                    await plaintextDigest.write(chunk.subarray(digestOffset, Math.min(digestOffset + framePlaintextBytes, chunk.byteLength)));
+                }
+                plaintextBytes += chunk.byteLength;
+                let offset = 0;
+                if (pending.byteLength > 0) {
+                    const take = Math.min(framePlaintextBytes - pending.byteLength, chunk.byteLength);
+                    pending = concatBytes([pending, chunk.subarray(0, take)]);
+                    offset = take;
+                    if (pending.byteLength === framePlaintextBytes) {
+                        await encryptFrame(backupDataFrameKind, pending, controller);
+                        pending.fill(0);
+                        pending = new Uint8Array(0);
+                    }
+                }
+                while (chunk.byteLength - offset >= framePlaintextBytes) {
+                    await encryptFrame(backupDataFrameKind, chunk.subarray(offset, offset + framePlaintextBytes), controller);
+                    offset += framePlaintextBytes;
+                }
+                if (offset < chunk.byteLength)
+                    pending = chunk.slice(offset);
+            }
+            catch (error) {
+                failed = true;
+                pending.fill(0);
+                decodedNoncePrefix.fill(0);
+                headerSha256.fill(0);
+                await abortDigests(error);
+                completionState.reject(error);
+                throw error;
+            }
+        },
+        async flush(controller) {
+            if (failed)
+                return;
+            try {
+                if (signal.aborted)
+                    throw new RaybaseBackupError("BACKUP_PROVIDER_UNAVAILABLE", "Backup encryption was aborted");
+                if (pending.byteLength > 0) {
+                    await encryptFrame(backupDataFrameKind, pending, controller);
+                    pending.fill(0);
+                    pending = new Uint8Array(0);
+                }
+                const plaintextSha256Bytes = await plaintextDigest.finish();
+                const plaintextSha256 = sha256HexBytes(plaintextSha256Bytes);
+                plaintextSha256Bytes.fill(0);
+                const logicalTotals = normalizeLogicalTotals(typeof options.logicalTotals === "function"
+                    ? await options.logicalTotals()
+                    : options.logicalTotals);
+                const finalFrame = {
+                    version: 1,
+                    frameCount: sequence,
+                    plaintextBytes,
+                    ...logicalTotals,
+                    plaintextSha256
+                };
+                const finalPlaintext = canonicalBackupJson(finalFrame);
+                if (finalPlaintext.byteLength > backupFinalFrameMaxBytes) {
+                    formatError("Backup final frame exceeds its byte limit", "BACKUP_LIMIT_EXCEEDED");
+                }
+                await encryptFrame(backupFinalFrameKind, finalPlaintext, controller);
+                finalPlaintext.fill(0);
+                const ciphertextSha256Bytes = await ciphertextDigest.finish();
+                const completion = {
+                    header,
+                    frameCount: finalFrame.frameCount,
+                    plaintextBytes,
+                    plaintextSha256,
+                    ciphertextBytes,
+                    ciphertextSha256: sha256HexBytes(ciphertextSha256Bytes),
+                    logicalTotals
+                };
+                ciphertextSha256Bytes.fill(0);
+                decodedNoncePrefix.fill(0);
+                headerSha256.fill(0);
+                completionState.resolve(completion);
+            }
+            catch (error) {
+                failed = true;
+                pending.fill(0);
+                decodedNoncePrefix.fill(0);
+                headerSha256.fill(0);
+                await abortDigests(error);
+                completionState.reject(error);
+                throw error;
+            }
+        },
+        async cancel(reason) {
+            if (failed)
+                return;
+            failed = true;
+            pending.fill(0);
+            decodedNoncePrefix.fill(0);
+            headerSha256.fill(0);
+            await abortDigests(reason);
+            completionState.reject(reason ?? new RaybaseBackupError("BACKUP_ARCHIVE_TRUNCATED", "Backup encryption stream was cancelled"));
+        }
+    });
+    return {
+        header: decodeBackupArchiveHeader(headerBytes).header,
+        headerBytes: headerBytes.slice(),
+        transform,
+        completion: completionState.promise
+    };
+}
+function validateExpectedCiphertext(options, bytes, sha256) {
+    if (options.expectedCiphertextBytes !== undefined && options.expectedCiphertextBytes !== bytes) {
+        formatError("Backup ciphertext byte count does not match its manifest");
+    }
+    if (options.expectedCiphertextSha256 !== undefined && options.expectedCiphertextSha256 !== sha256) {
+        formatError("Backup ciphertext SHA-256 does not match its manifest");
+    }
+}
+export function createBackupArchiveDecryptor(options) {
+    const signal = options.signal ?? new AbortController().signal;
+    const digestFactory = options.digestFactory ?? createBackupSha256Digest;
+    const plaintextDigest = digestFactory();
+    const ciphertextDigest = digestFactory();
+    const headerState = deferred();
+    const completionState = deferred();
+    let buffer = new Uint8Array(archiveHeaderPrefixBytes);
+    let bufferLength = 0;
+    let parsedHeader = null;
+    let headerSha256 = new Uint8Array(0);
+    let noncePrefix = new Uint8Array(0);
+    let frameKey = null;
+    let sequence = 0;
+    let plaintextBytes = 0;
+    let ciphertextBytes = 0;
+    let ended = false;
+    let failed = false;
+    let finalCompletion = null;
+    const abortDigests = async (reason) => {
+        await Promise.allSettled([
+            plaintextDigest.abort(reason),
+            ciphertextDigest.abort(reason)
+        ]);
+    };
+    const failTransform = async (error) => {
+        failed = true;
+        buffer.fill(0);
+        headerSha256.fill(0);
+        noncePrefix.fill(0);
+        await abortDigests(error);
+        headerState.reject(error);
+        completionState.reject(error);
+        throw error;
+    };
+    const expandUnitBuffer = () => {
+        if (bufferLength !== backupFrameHeaderBytes) {
+            formatError("Backup frame decoder prefix state is invalid");
+        }
+        let requiredBytes;
+        if (!parsedHeader) {
+            const bodyLength = new DataView(buffer.buffer, buffer.byteOffset + backupArchiveMagic.byteLength, 4).getUint32(0, false);
+            if (bodyLength > backupFormatLimits.headerBytes) {
+                formatError("Backup archive header exceeds its byte limit", "BACKUP_LIMIT_EXCEEDED");
+            }
+            requiredBytes = archiveHeaderPrefixBytes + bodyLength;
+        }
+        else {
+            const view = new DataView(buffer.buffer, buffer.byteOffset, backupFrameHeaderBytes);
+            const kind = buffer[1];
+            const plaintextLength = view.getUint32(8, false);
+            const maximum = kind === backupFinalFrameKind
+                ? backupFinalFrameMaxBytes
+                : parsedHeader.encryption.framePlaintextBytes;
+            if (plaintextLength > maximum)
+                formatError("Backup frame exceeds its plaintext byte limit", "BACKUP_LIMIT_EXCEEDED");
+            requiredBytes = backupFrameHeaderBytes + plaintextLength + backupFrameTagBytes;
+        }
+        if (requiredBytes === buffer.byteLength)
+            return;
+        const expanded = new Uint8Array(requiredBytes);
+        expanded.set(buffer.subarray(0, bufferLength));
+        buffer.fill(0);
+        buffer = expanded;
+    };
+    const acceptHeader = async () => {
+        const encoded = buffer.subarray(0, bufferLength);
+        const decoded = decodeBackupArchiveHeader(encoded);
+        if (decoded.bytesRead !== encoded.byteLength)
+            formatError("Backup archive header contains trailing bytes");
+        if (options.validateHeader)
+            await options.validateHeader(decoded.header);
+        const context = operationContext(decoded.header, "unwrap", signal, options.environment);
+        const dek = await unwrapBackupDek({
+            envelope: decoded.header.keyEnvelope,
+            context,
+            providers: options.providers,
+            ...(options.providerInput ? { providerInput: options.providerInput } : {})
+        });
+        try {
+            frameKey = await importBackupFrameKey(dek, "decrypt");
+        }
+        finally {
+            dek.fill(0);
+        }
+        parsedHeader = decoded.header;
+        headerSha256 = new Uint8Array(await crypto.subtle.digest("SHA-256", backupOwnedBuffer(encoded)));
+        noncePrefix = decodeCanonicalFormatBase64Url(decoded.header.encryption.noncePrefix, "Backup nonce prefix", 8);
+        buffer.fill(0);
+        buffer = new Uint8Array(backupFrameHeaderBytes);
+        bufferLength = 0;
+        headerState.resolve(decoded.header);
+    };
+    const acceptFrame = async (controller) => {
+        if (!parsedHeader || !frameKey)
+            formatError("Backup frame appeared before its archive header");
+        const wireHeader = buffer.subarray(0, backupFrameHeaderBytes);
+        const view = new DataView(wireHeader.buffer, wireHeader.byteOffset, wireHeader.byteLength);
+        const version = wireHeader[0];
+        const kind = wireHeader[1];
+        const flags = view.getUint16(2, false);
+        const encodedSequence = view.getUint32(4, false);
+        const plaintextLength = view.getUint32(8, false);
+        if (version !== backupFrameFormatVersion) {
+            formatError("Backup frame version is unsupported", "BACKUP_FRAME_VERSION_UNSUPPORTED");
+        }
+        if (kind !== backupDataFrameKind && kind !== backupFinalFrameKind) {
+            formatError("Backup frame kind is unsupported", "BACKUP_FRAME_VERSION_UNSUPPORTED");
+        }
+        if (flags !== 0)
+            formatError("Backup frame flags are unsupported", "BACKUP_FRAME_VERSION_UNSUPPORTED");
+        if (encodedSequence !== sequence)
+            formatError("Backup frame sequence is missing, duplicated, or reordered");
+        if (kind === backupDataFrameKind && sequence >= maximumUint32) {
+            formatError("Backup frame sequence space is exhausted before a final frame", "BACKUP_LIMIT_EXCEEDED");
+        }
+        if ((kind === backupDataFrameKind && plaintextLength > parsedHeader.encryption.framePlaintextBytes) ||
+            (kind === backupFinalFrameKind && plaintextLength > backupFinalFrameMaxBytes)) {
+            formatError("Backup frame exceeds its plaintext byte limit", "BACKUP_LIMIT_EXCEEDED");
+        }
+        const ciphertext = buffer.subarray(backupFrameHeaderBytes, bufferLength);
+        const nonce = frameNonce(noncePrefix, sequence);
+        let plaintext;
+        try {
+            try {
+                plaintext = new Uint8Array(await crypto.subtle.decrypt({
+                    name: "AES-GCM",
+                    iv: backupOwnedBuffer(nonce),
+                    additionalData: backupOwnedBuffer(frameAdditionalData(headerSha256, wireHeader)),
+                    tagLength: 128
+                }, frameKey, backupOwnedBuffer(ciphertext)));
+            }
+            catch {
+                return formatError("Backup frame failed authenticated decryption");
+            }
+        }
+        finally {
+            nonce.fill(0);
+        }
+        if (plaintext.byteLength !== plaintextLength) {
+            plaintext.fill(0);
+            formatError("Backup frame plaintext length is invalid");
+        }
+        buffer.fill(0);
+        buffer = new Uint8Array(backupFrameHeaderBytes);
+        bufferLength = 0;
+        if (kind === backupDataFrameKind) {
+            assertSafeCounter(plaintextBytes + plaintext.byteLength, "Backup plaintext byte count");
+            await plaintextDigest.write(plaintext);
+            plaintextBytes += plaintext.byteLength;
+            controller.enqueue(plaintext);
+            sequence += 1;
+            return;
+        }
+        const finalFrame = decodeCanonicalFinalFrame(plaintext);
+        plaintext.fill(0);
+        if (finalFrame.frameCount !== sequence ||
+            finalFrame.plaintextBytes !== plaintextBytes) {
+            formatError("Backup final frame totals do not match the decrypted stream");
+        }
+        const plaintextSha256Bytes = await plaintextDigest.finish();
+        const expectedPlaintextSha256 = sha256HexBytes(plaintextSha256Bytes);
+        plaintextSha256Bytes.fill(0);
+        if (finalFrame.plaintextSha256 !== expectedPlaintextSha256) {
+            formatError("Backup plaintext SHA-256 does not match its authenticated final frame");
+        }
+        ended = true;
+        sequence += 1;
+        const ciphertextSha256Bytes = await ciphertextDigest.finish();
+        const ciphertextSha256 = sha256HexBytes(ciphertextSha256Bytes);
+        ciphertextSha256Bytes.fill(0);
+        validateExpectedCiphertext(options, ciphertextBytes, ciphertextSha256);
+        headerSha256.fill(0);
+        noncePrefix.fill(0);
+        finalCompletion = {
+            header: parsedHeader,
+            frameCount: finalFrame.frameCount,
+            plaintextBytes,
+            plaintextSha256: expectedPlaintextSha256,
+            ciphertextBytes,
+            ciphertextSha256,
+            logicalTotals: {
+                recordCount: finalFrame.recordCount,
+                rowCount: finalFrame.rowCount,
+                tableCount: finalFrame.tableCount
+            }
+        };
+    };
+    const transform = new TransformStream({
+        async transform(chunk, controller) {
+            try {
+                if (signal.aborted)
+                    throw new RaybaseBackupError("BACKUP_PROVIDER_UNAVAILABLE", "Backup decryption was aborted");
+                if (!(chunk instanceof Uint8Array))
+                    formatError("Backup decryptor input must be a Uint8Array");
+                if (chunk.byteLength === 0)
+                    return;
+                if (ended)
+                    formatError("Backup archive contains frames or bytes after its final frame");
+                assertSafeCounter(ciphertextBytes + chunk.byteLength, "Backup ciphertext byte count");
+                for (let digestOffset = 0; digestOffset < chunk.byteLength; digestOffset += defaultBackupFramePlaintextBytes) {
+                    await ciphertextDigest.write(chunk.subarray(digestOffset, Math.min(digestOffset + defaultBackupFramePlaintextBytes, chunk.byteLength)));
+                }
+                ciphertextBytes += chunk.byteLength;
+                let offset = 0;
+                while (offset < chunk.byteLength) {
+                    if (ended)
+                        formatError("Backup archive contains frames or bytes after its final frame");
+                    const take = Math.min(buffer.byteLength - bufferLength, chunk.byteLength - offset);
+                    if (take <= 0)
+                        formatError("Backup frame decoder made no progress");
+                    buffer.set(chunk.subarray(offset, offset + take), bufferLength);
+                    bufferLength += take;
+                    offset += take;
+                    if (bufferLength === buffer.byteLength) {
+                        if (buffer.byteLength === backupFrameHeaderBytes) {
+                            expandUnitBuffer();
+                        }
+                        if (bufferLength === buffer.byteLength) {
+                            if (!parsedHeader)
+                                await acceptHeader();
+                            else
+                                await acceptFrame(controller);
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                return failTransform(error);
+            }
+        },
+        async flush() {
+            if (failed)
+                return;
+            if (!parsedHeader || bufferLength > 0 || !ended) {
+                return failTransform(new RaybaseBackupError("BACKUP_ARCHIVE_TRUNCATED", !parsedHeader
+                    ? "Backup archive ended inside its clear header"
+                    : bufferLength > 0
+                        ? "Backup archive ended inside an authenticated frame"
+                        : "Backup archive is missing its authenticated final frame"));
+            }
+            if (!finalCompletion) {
+                return failTransform(new RaybaseBackupError("BACKUP_ARCHIVE_CORRUPT", "Backup final frame did not produce completion metadata"));
+            }
+            completionState.resolve(finalCompletion);
+        },
+        async cancel(reason) {
+            if (failed)
+                return;
+            failed = true;
+            buffer.fill(0);
+            headerSha256.fill(0);
+            noncePrefix.fill(0);
+            await abortDigests(reason);
+            const error = reason ?? new RaybaseBackupError("BACKUP_ARCHIVE_TRUNCATED", "Backup decryption stream was cancelled");
+            headerState.reject(error);
+            completionState.reject(error);
+        }
+    });
+    return {
+        transform,
+        header: headerState.promise,
+        completion: completionState.promise
+    };
+}
+//# sourceMappingURL=backup-format.js.map