@raybase/core 0.0.2 → 0.3.3

package/dist/backup-crypto.js

@@ -0,0 +1,693 @@
+export const backupProviderLimits = {
+    identifierBytes: 128,
+    wrappedKeyRecords: 16,
+    wrappedKeyBytes: 16 * 1024,
+    saltBytes: 128,
+    metadataBytes: 16 * 1024,
+    metadataDepth: 8,
+    metadataProperties: 128,
+    providerStateBytes: 64 * 1024,
+    participantDirectoryPageRecords: 100,
+    restoreInputRecords: 16,
+    restoreInputValueBytes: 32 * 1024,
+    restoreInputAggregateBytes: 64 * 1024
+};
+/**
+ * Stable, audit-safe backup failure. Callers may surface `code` and `message`;
+ * provider exceptions and secret-bearing values must not be attached to it.
+ */
+export class RaybaseBackupError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "RaybaseBackupError";
+        this.code = code;
+    }
+}
+const textEncoder = new TextEncoder();
+const base64UrlAlphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+const base64UrlPattern = /^[A-Za-z0-9_-]+$/;
+const identifierPattern = /^[A-Za-z0-9][A-Za-z0-9._:/-]*$/;
+function fail(message, code = "BACKUP_PROVIDER_ENVELOPE_INVALID") {
+    throw new RaybaseBackupError(code, message);
+}
+function plainObject(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value) || ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+        return fail(`${label} must be a plain serializable object`);
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        return fail(`${label} must be a plain serializable object`);
+    }
+    return value;
+}
+function boundedIdentifier(value, label) {
+    if (typeof value !== "string" || !identifierPattern.test(value) || textEncoder.encode(value).byteLength > backupProviderLimits.identifierBytes) {
+        return fail(`${label} is invalid or exceeds ${backupProviderLimits.identifierBytes} bytes`);
+    }
+    return value;
+}
+function boundedBase64Url(value, label, maxBytes) {
+    if (typeof value !== "string" || !value || !base64UrlPattern.test(value)) {
+        return fail(`${label} must be valid unpadded base64url data`);
+    }
+    const remainder = value.length % 4;
+    if (remainder === 1)
+        return fail(`${label} must be valid unpadded base64url data`);
+    const decodedBytes = Math.floor(value.length * 3 / 4);
+    if (decodedBytes > maxBytes)
+        return fail(`${label} exceeds ${maxBytes} decoded bytes`);
+    const finalSextet = base64UrlAlphabet.indexOf(value[value.length - 1]);
+    if ((remainder === 2 && (finalSextet & 0b1111) !== 0) ||
+        (remainder === 3 && (finalSextet & 0b11) !== 0)) {
+        return fail(`${label} must use canonical unpadded base64url encoding`);
+    }
+    return value;
+}
+function assertOnlyKeys(value, allowed, label) {
+    const allowedSet = new Set(allowed);
+    const extra = Object.keys(value).find((key) => !allowedSet.has(key));
+    if (extra)
+        fail(`${label} contains unsupported field ${extra}`);
+}
+function normalizeJsonValue(value, state, label) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            fail(`${label} contains a non-finite number`);
+        return value;
+    }
+    if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+        return fail(`${label} cannot contain raw byte or key material`);
+    }
+    if (Array.isArray(value)) {
+        if (state.depth >= backupProviderLimits.metadataDepth)
+            fail(`${label} exceeds the metadata depth limit`, "BACKUP_LIMIT_EXCEEDED");
+        return value.map((item, index) => normalizeJsonValue(item, { ...state, depth: state.depth + 1 }, `${label}[${index}]`));
+    }
+    const object = plainObject(value, label);
+    if (state.depth >= backupProviderLimits.metadataDepth)
+        fail(`${label} exceeds the metadata depth limit`, "BACKUP_LIMIT_EXCEEDED");
+    const output = {};
+    for (const key of Object.keys(object).sort()) {
+        state.propertyCount.value += 1;
+        if (state.propertyCount.value > backupProviderLimits.metadataProperties) {
+            fail(`${label} exceeds the metadata property limit`, "BACKUP_LIMIT_EXCEEDED");
+        }
+        output[key] = normalizeJsonValue(object[key], { ...state, depth: state.depth + 1 }, `${label}.${key}`);
+    }
+    return output;
+}
+export function validateBackupJsonMetadata(value, label = "Backup provider metadata") {
+    const normalized = normalizeJsonValue(value, { depth: 0, propertyCount: { value: 0 } }, label);
+    if (textEncoder.encode(JSON.stringify(normalized)).byteLength > backupProviderLimits.metadataBytes) {
+        fail(`${label} exceeds ${backupProviderLimits.metadataBytes} bytes`, "BACKUP_LIMIT_EXCEEDED");
+    }
+    return normalized;
+}
+function validateKdfDescriptor(value) {
+    const object = plainObject(value, "Backup KDF descriptor");
+    const algorithm = object.algorithm;
+    if (algorithm === "HKDF-SHA-256") {
+        assertOnlyKeys(object, ["algorithm", "version", "salt", "info", "outputBytes"], "Backup KDF descriptor");
+        if (object.version !== 1 || object.outputBytes !== 32)
+            fail("HKDF descriptor version/output length is unsupported");
+        if (typeof object.info !== "string" || !object.info || textEncoder.encode(object.info).byteLength > 512) {
+            fail("HKDF info is invalid");
+        }
+        return {
+            algorithm,
+            version: 1,
+            salt: boundedBase64Url(object.salt, "HKDF salt", backupProviderLimits.saltBytes),
+            info: object.info,
+            outputBytes: 32
+        };
+    }
+    if (algorithm === "PBKDF2-SHA-256") {
+        assertOnlyKeys(object, ["algorithm", "version", "salt", "iterations", "outputBytes"], "Backup KDF descriptor");
+        if (!Number.isInteger(object.version) || object.version < 1)
+            fail("PBKDF2 descriptor version is invalid");
+        if (!Number.isInteger(object.iterations) || object.iterations < 1)
+            fail("PBKDF2 iteration count is invalid");
+        if (object.outputBytes !== 32)
+            fail("PBKDF2 output length is unsupported");
+        return {
+            algorithm,
+            version: object.version,
+            salt: boundedBase64Url(object.salt, "PBKDF2 salt", backupProviderLimits.saltBytes),
+            iterations: object.iterations,
+            outputBytes: 32
+        };
+    }
+    if (algorithm === "provider-defined") {
+        assertOnlyKeys(object, ["algorithm", "version", "name", "parameters"], "Backup KDF descriptor");
+        if (!Number.isInteger(object.version) || object.version < 1)
+            fail("Provider KDF version is invalid");
+        const descriptor = {
+            algorithm,
+            version: object.version,
+            name: boundedIdentifier(object.name, "Provider KDF name")
+        };
+        if (object.parameters !== undefined)
+            descriptor.parameters = validateBackupJsonMetadata(object.parameters, "Provider KDF parameters");
+        return descriptor;
+    }
+    return fail("Backup KDF algorithm is unsupported");
+}
+function validateWrappedKey(value, index) {
+    const object = plainObject(value, `Wrapped key record ${index}`);
+    assertOnlyKeys(object, ["id", "algorithm", "wrappedKey", "nonce", "shareId", "metadata"], `Wrapped key record ${index}`);
+    const record = {
+        id: boundedIdentifier(object.id, `Wrapped key record ${index} id`),
+        algorithm: boundedIdentifier(object.algorithm, `Wrapped key record ${index} algorithm`),
+        wrappedKey: boundedBase64Url(object.wrappedKey, `Wrapped key record ${index} ciphertext`, backupProviderLimits.wrappedKeyBytes)
+    };
+    if (object.nonce !== undefined)
+        record.nonce = boundedBase64Url(object.nonce, `Wrapped key record ${index} nonce`, 64);
+    if (object.shareId !== undefined)
+        record.shareId = boundedIdentifier(object.shareId, `Wrapped key record ${index} share id`);
+    if (object.metadata !== undefined)
+        record.metadata = validateBackupJsonMetadata(object.metadata, `Wrapped key record ${index} metadata`);
+    return record;
+}
+/**
+ * Validate and clone an untrusted provider envelope before it is serialized.
+ */
+export function validateBackupKeyEnvelope(value) {
+    const object = plainObject(value, "Backup key envelope");
+    assertOnlyKeys(object, ["version", "providerId", "providerMode", "kekKeyId", "wrapAlgorithm", "kdf", "wrappedKeys", "threshold", "metadata"], "Backup key envelope");
+    if (object.version !== 1)
+        fail("Backup key envelope version is unsupported");
+    if (object.providerMode !== "material" && object.providerMode !== "wrapping")
+        fail("Backup provider mode is unsupported");
+    if (object.wrapAlgorithm !== "AES-256-GCM" && object.wrapAlgorithm !== "provider-defined")
+        fail("Backup wrap algorithm is unsupported");
+    if (!Array.isArray(object.wrappedKeys) || object.wrappedKeys.length < 1 || object.wrappedKeys.length > backupProviderLimits.wrappedKeyRecords) {
+        fail(`Backup key envelope must contain 1-${backupProviderLimits.wrappedKeyRecords} wrapped key records`);
+    }
+    const wrappedKeys = object.wrappedKeys.map(validateWrappedKey);
+    const ids = new Set(wrappedKeys.map((record) => record.id));
+    if (ids.size !== wrappedKeys.length)
+        fail("Backup wrapped key record ids must be unique");
+    const envelope = {
+        version: 1,
+        providerId: boundedIdentifier(object.providerId, "Backup provider id"),
+        providerMode: object.providerMode,
+        kekKeyId: boundedIdentifier(object.kekKeyId, "Backup KEK key id"),
+        wrapAlgorithm: object.wrapAlgorithm,
+        wrappedKeys
+    };
+    if (object.kdf !== undefined)
+        envelope.kdf = validateKdfDescriptor(object.kdf);
+    if (object.metadata !== undefined)
+        envelope.metadata = validateBackupJsonMetadata(object.metadata);
+    if (object.threshold !== undefined) {
+        const threshold = plainObject(object.threshold, "Backup threshold descriptor");
+        assertOnlyKeys(threshold, ["requiredShares", "totalShares"], "Backup threshold descriptor");
+        if (!Number.isInteger(threshold.requiredShares) ||
+            !Number.isInteger(threshold.totalShares) ||
+            threshold.requiredShares < 1 ||
+            threshold.totalShares < threshold.requiredShares) {
+            fail("Backup threshold descriptor is invalid");
+        }
+        const shareIds = wrappedKeys.map((record) => record.shareId).filter((shareId) => Boolean(shareId));
+        if (wrappedKeys.length !== threshold.totalShares || new Set(shareIds).size !== threshold.totalShares) {
+            fail("Backup threshold envelope does not contain every declared share", "BACKUP_THRESHOLD_UNMET");
+        }
+        envelope.threshold = {
+            requiredShares: threshold.requiredShares,
+            totalShares: threshold.totalShares
+        };
+    }
+    if (envelope.providerMode === "material") {
+        if (!envelope.kdf || envelope.kdf.algorithm !== "HKDF-SHA-256")
+            fail("Material provider envelopes require an HKDF descriptor");
+        if (envelope.wrapAlgorithm !== "AES-256-GCM" || envelope.wrappedKeys.length !== 1 || envelope.threshold) {
+            fail("Material provider envelope shape is invalid");
+        }
+    }
+    return envelope;
+}
+export const deploymentBackupProviderId = "raybase.deployment-secret";
+export const backupDekBytes = 32;
+export const backupKekMaterialMinBytes = 32;
+export const backupKekMaterialMaxBytes = 128;
+function ownedBuffer(value) {
+    const copy = new Uint8Array(value.byteLength);
+    copy.set(value);
+    return copy.buffer;
+}
+function encodeBase64Url(value) {
+    let binary = "";
+    for (const byte of value)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function decodeBase64Url(value, label, maxBytes = backupKekMaterialMaxBytes) {
+    boundedBase64Url(value, label, maxBytes);
+    const padded = `${value.replace(/-/g, "+").replace(/_/g, "/")}${"=".repeat((4 - value.length % 4) % 4)}`;
+    try {
+        const bytes = Uint8Array.from(atob(padded), (character) => character.charCodeAt(0));
+        if (bytes.byteLength > maxBytes)
+            fail(`${label} exceeds ${maxBytes} decoded bytes`);
+        return bytes;
+    }
+    catch {
+        return fail(`${label} must be valid unpadded base64url data`);
+    }
+}
+/** Validate opaque request-only provider input and return fresh Core-owned copies. */
+export function validateBackupRestoreProviderInput(value) {
+    if (value === undefined || value === null)
+        return Object.freeze([]);
+    if (!Array.isArray(value) || value.length > backupProviderLimits.restoreInputRecords) {
+        fail(`Backup restore provider input supports at most ${backupProviderLimits.restoreInputRecords} records`, "BACKUP_LIMIT_EXCEEDED");
+    }
+    const copies = [];
+    let aggregateBytes = 0;
+    try {
+        for (const [index, candidate] of value.entries()) {
+            const object = plainObject(candidate, `Backup restore provider input record ${index}`);
+            assertOnlyKeys(object, ["id", "value"], `Backup restore provider input record ${index}`);
+            const id = boundedIdentifier(object.id, `Backup restore provider input record ${index} id`);
+            if (!(object.value instanceof Uint8Array)) {
+                fail("Backup restore provider input values must be bytes");
+            }
+            if (object.value.byteLength > backupProviderLimits.restoreInputValueBytes) {
+                fail("Backup restore provider input value exceeds its byte limit", "BACKUP_LIMIT_EXCEEDED");
+            }
+            aggregateBytes += object.value.byteLength;
+            if (aggregateBytes > backupProviderLimits.restoreInputAggregateBytes) {
+                fail("Backup restore provider input exceeds its aggregate byte limit", "BACKUP_LIMIT_EXCEEDED");
+            }
+            copies.push(Object.freeze({ id, value: object.value.slice() }));
+        }
+        if (new Set(copies.map((entry) => entry.id)).size !== copies.length) {
+            fail("Backup restore provider input ids must be unique");
+        }
+        return Object.freeze(copies);
+    }
+    catch (error) {
+        for (const entry of copies)
+            entry.value.fill(0);
+        throw error;
+    }
+}
+/** Decode the canonical JSON-facing base64url representation into mutable bytes. */
+export function decodeBackupRestoreProviderInput(value) {
+    if (value === undefined || value === null)
+        return Object.freeze([]);
+    if (!Array.isArray(value) || value.length > backupProviderLimits.restoreInputRecords) {
+        fail(`Backup restore provider input supports at most ${backupProviderLimits.restoreInputRecords} records`, "BACKUP_LIMIT_EXCEEDED");
+    }
+    const decoded = [];
+    try {
+        for (const [index, candidate] of value.entries()) {
+            const object = plainObject(candidate, `Backup restore provider input record ${index}`);
+            assertOnlyKeys(object, ["id", "value"], `Backup restore provider input record ${index}`);
+            const id = boundedIdentifier(object.id, `Backup restore provider input record ${index} id`);
+            if (typeof object.value !== "string")
+                fail("Backup restore provider input values must be canonical base64url strings");
+            decoded.push(Object.freeze({
+                id,
+                value: decodeBase64Url(object.value, `Backup restore provider input record ${index} value`, backupProviderLimits.restoreInputValueBytes)
+            }));
+        }
+        const validated = validateBackupRestoreProviderInput(decoded);
+        for (const entry of decoded)
+            entry.value.fill(0);
+        return validated;
+    }
+    catch (error) {
+        for (const entry of decoded)
+            entry.value.fill(0);
+        throw error;
+    }
+}
+export function clearBackupRestoreProviderInput(value) {
+    for (const entry of value ?? [])
+        entry.value.fill(0);
+}
+/**
+ * Stable provider-owned inner-ciphertext AAD. It binds provider material to
+ * the archive identity without including the mutable envelope payload.
+ */
+export function createBackupProviderAad(context, providerId) {
+    return textEncoder.encode(JSON.stringify({
+        domain: "raybase-backup-provider-aad-v1",
+        archiveId: context.archiveId,
+        product: context.product,
+        target: context.target,
+        targetId: context.targetId,
+        createdAt: context.createdAt,
+        providerId: boundedIdentifier(providerId, "Backup provider id")
+    }));
+}
+function randomBytes(byteLength, source) {
+    const value = source ? source(byteLength) : crypto.getRandomValues(new Uint8Array(byteLength));
+    if (!(value instanceof Uint8Array) || value.byteLength !== byteLength) {
+        fail(`Backup randomness source must return exactly ${byteLength} bytes`, "BACKUP_LIMIT_EXCEEDED");
+    }
+    return value.slice();
+}
+function backupProviderFailure(code, message) {
+    return new RaybaseBackupError(code, message);
+}
+function safeProviderError(error, fallbackCode, fallbackMessage) {
+    if (error instanceof RaybaseBackupError) {
+        const safeMessages = {
+            BACKUP_THRESHOLD_UNMET: "The backup key provider did not recover the required shares",
+            BACKUP_KEY_UNAVAILABLE: "The backup key version is unavailable",
+            BACKUP_PROVIDER_ENVELOPE_INVALID: "The backup key provider returned an invalid envelope",
+            BACKUP_ARCHIVE_CORRUPT: "The provider-wrapped archive key failed authentication",
+            BACKUP_ARCHIVE_IDENTITY_MISMATCH: "The provider-wrapped archive key does not match this restore target",
+            BACKUP_LIMIT_EXCEEDED: "The backup key provider exceeded a Core safety limit"
+        };
+        const message = safeMessages[error.code];
+        if (message) {
+            return backupProviderFailure(error.code, message);
+        }
+    }
+    return backupProviderFailure(fallbackCode, fallbackMessage);
+}
+async function deploymentKeyId(secretBytes) {
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", ownedBuffer(secretBytes)));
+    try {
+        return `deployment-${encodeBase64Url(digest.subarray(0, 16))}`;
+    }
+    finally {
+        digest.fill(0);
+    }
+}
+function validateKekMaterial(value) {
+    if (!(value instanceof Uint8Array)) {
+        throw backupProviderFailure("BACKUP_PROVIDER_UNAVAILABLE", "The backup key provider returned invalid key material");
+    }
+    if (value.byteLength < backupKekMaterialMinBytes || value.byteLength > backupKekMaterialMaxBytes) {
+        value.fill(0);
+        throw backupProviderFailure("BACKUP_PROVIDER_UNAVAILABLE", `Backup KEK material must contain ${backupKekMaterialMinBytes}-${backupKekMaterialMaxBytes} bytes`);
+    }
+    return value;
+}
+/**
+ * Build Core's deployment-secret material provider. Secrets are canonical
+ * unpadded base64url values containing at least 256 bits of high-entropy
+ * material. Raw decoded keys are created per operation and then zeroed by the
+ * wrapping helpers; the provider closure retains only the configured strings.
+ */
+export async function createDeploymentBackupKeyProvider(options) {
+    const configured = [options.currentSecret, ...(options.retainedSecrets ?? [])];
+    if (configured.length === 0) {
+        throw backupProviderFailure("BACKUP_ENCRYPTION_NOT_CONFIGURED", "RAYBASE_BACKUPS_KEY is not configured");
+    }
+    const keyIds = [];
+    for (const [index, encoded] of configured.entries()) {
+        let bytes;
+        try {
+            bytes = decodeBase64Url(encoded, index === 0 ? "RAYBASE_BACKUPS_KEY" : `Retained backup key ${index}`);
+        }
+        catch {
+            throw backupProviderFailure("BACKUP_ENCRYPTION_NOT_CONFIGURED", `${index === 0 ? "RAYBASE_BACKUPS_KEY" : `Retained backup key ${index}`} must be canonical base64url high-entropy key material`);
+        }
+        try {
+            if (bytes.byteLength < backupKekMaterialMinBytes) {
+                throw backupProviderFailure("BACKUP_ENCRYPTION_NOT_CONFIGURED", `Backup deployment secrets must contain at least ${backupKekMaterialMinBytes} decoded bytes`);
+            }
+            keyIds.push(await deploymentKeyId(bytes));
+        }
+        finally {
+            bytes.fill(0);
+        }
+    }
+    if (new Set(keyIds).size !== keyIds.length) {
+        throw backupProviderFailure("BACKUP_ENCRYPTION_NOT_CONFIGURED", "Backup deployment key versions must be unique");
+    }
+    const currentKeyId = keyIds[0];
+    const keyIndex = new Map(keyIds.map((keyId, index) => [keyId, index]));
+    return {
+        mode: "material",
+        id: deploymentBackupProviderId,
+        async resolveKek(request) {
+            if (request.context.signal.aborted) {
+                throw backupProviderFailure("BACKUP_PROVIDER_UNAVAILABLE", "Backup key resolution was aborted");
+            }
+            const keyId = request.kekKeyId ?? currentKeyId;
+            const index = keyIndex.get(keyId);
+            if (index === undefined) {
+                throw backupProviderFailure("BACKUP_KEY_UNAVAILABLE", `Backup key version ${keyId} is unavailable`);
+            }
+            const keyMaterial = decodeBase64Url(configured[index], `Backup deployment key ${keyId}`);
+            validateKekMaterial(keyMaterial);
+            return { kekKeyId: keyId, keyMaterial };
+        }
+    };
+}
+function keyDerivationContext(context, providerId, kekKeyId) {
+    return textEncoder.encode(JSON.stringify({
+        domain: "raybase-backup-kek-v1",
+        archiveId: context.archiveId,
+        product: context.product,
+        target: context.target,
+        targetId: context.targetId,
+        createdAt: context.createdAt,
+        providerId,
+        kekKeyId
+    }));
+}
+async function keyDerivationInfo(context, providerId, kekKeyId) {
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", ownedBuffer(keyDerivationContext(context, providerId, kekKeyId))));
+    try {
+        return `raybase-backup-kek-v1:${encodeBase64Url(digest)}`;
+    }
+    finally {
+        digest.fill(0);
+    }
+}
+function wrapAdditionalData(context, providerId, kekKeyId) {
+    return textEncoder.encode(JSON.stringify({
+        domain: "raybase-backup-dek-wrap-v1",
+        archiveId: context.archiveId,
+        product: context.product,
+        target: context.target,
+        targetId: context.targetId,
+        createdAt: context.createdAt,
+        providerId,
+        kekKeyId,
+        wrappedKeyId: "dek"
+    }));
+}
+async function deriveKek(keyMaterial, salt, info, usage) {
+    const inputKey = await crypto.subtle.importKey("raw", ownedBuffer(keyMaterial), "HKDF", false, ["deriveKey"]);
+    return crypto.subtle.deriveKey({
+        name: "HKDF",
+        hash: "SHA-256",
+        salt: ownedBuffer(salt),
+        info: ownedBuffer(textEncoder.encode(info))
+    }, inputKey, { name: "AES-GCM", length: 256 }, false, [usage]);
+}
+async function resolveMaterial(provider, context, kekKeyId) {
+    let resolution;
+    try {
+        resolution = await provider.resolveKek({ context, ...(kekKeyId ? { kekKeyId } : {}) });
+    }
+    catch (error) {
+        throw safeProviderError(error, kekKeyId ? "BACKUP_KEY_UNAVAILABLE" : "BACKUP_PROVIDER_UNAVAILABLE", kekKeyId ? "The backup key version is unavailable" : "The backup key provider could not resolve key material");
+    }
+    if (!resolution || typeof resolution.kekKeyId !== "string") {
+        if (resolution?.keyMaterial instanceof Uint8Array)
+            resolution.keyMaterial.fill(0);
+        throw backupProviderFailure("BACKUP_PROVIDER_UNAVAILABLE", "The backup key provider returned an invalid key version");
+    }
+    validateKekMaterial(resolution.keyMaterial);
+    return resolution;
+}
+function selectProviderForWrap(providers) {
+    if (providers.keyProvider?.id === deploymentBackupProviderId) {
+        throw backupProviderFailure("BACKUP_PROVIDER_ENVELOPE_INVALID", `App backup providers cannot use the reserved provider id ${deploymentBackupProviderId}`);
+    }
+    if (providers.deploymentProvider && providers.deploymentProvider.id !== deploymentBackupProviderId) {
+        throw backupProviderFailure("BACKUP_PROVIDER_ENVELOPE_INVALID", "The deployment backup provider id is invalid");
+    }
+    const provider = providers.keyProvider ?? providers.deploymentProvider;
+    if (!provider) {
+        throw backupProviderFailure("BACKUP_ENCRYPTION_NOT_CONFIGURED", "Encrypted backups require an app key provider or RAYBASE_BACKUPS_KEY");
+    }
+    return provider;
+}
+function selectProviderForUnwrap(providers, envelope) {
+    if (providers.keyProvider?.id === deploymentBackupProviderId) {
+        throw backupProviderFailure("BACKUP_PROVIDER_ENVELOPE_INVALID", `App backup providers cannot use the reserved provider id ${deploymentBackupProviderId}`);
+    }
+    if (providers.deploymentProvider && providers.deploymentProvider.id !== deploymentBackupProviderId) {
+        throw backupProviderFailure("BACKUP_PROVIDER_ENVELOPE_INVALID", "The deployment backup provider id is invalid");
+    }
+    const provider = [providers.keyProvider, providers.deploymentProvider]
+        .find((candidate) => candidate?.id === envelope.providerId);
+    if (!provider) {
+        throw backupProviderFailure("BACKUP_PROVIDER_UNAVAILABLE", `Backup key provider ${envelope.providerId} is unavailable`);
+    }
+    if (provider.mode !== envelope.providerMode) {
+        throw backupProviderFailure("BACKUP_PROVIDER_ENVELOPE_INVALID", "Backup provider mode does not match its envelope");
+    }
+    return provider;
+}
+/**
+ * Wrap a caller-owned 32-byte data-encryption key through the selected
+ * provider. Core never zeroes the caller's buffer, but it does overwrite all
+ * transient provider material and copies it hands to app wrapping providers.
+ */
+export async function wrapBackupDek(input) {
+    if (!(input.dek instanceof Uint8Array) || input.dek.byteLength !== backupDekBytes) {
+        throw backupProviderFailure("BACKUP_PROVIDER_ENVELOPE_INVALID", `Backup DEKs must contain exactly ${backupDekBytes} bytes`);
+    }
+    const provider = selectProviderForWrap(input.providers);
+    if (provider.mode === "wrapping") {
+        const providerDek = input.dek.slice();
+        try {
+            let rawEnvelope;
+            try {
+                rawEnvelope = await provider.wrapDek({
+                    context: input.context,
+                    dek: providerDek,
+                    participants: Object.freeze([...(input.participants ?? [])])
+                });
+            }
+            catch (error) {
+                throw safeProviderError(error, "BACKUP_PROVIDER_UNAVAILABLE", "The backup key provider could not wrap the archive key");
+            }
+            const envelope = validateBackupKeyEnvelope(rawEnvelope);
+            if (envelope.providerId !== provider.id || envelope.providerMode !== "wrapping") {
+                throw backupProviderFailure("BACKUP_PROVIDER_ENVELOPE_INVALID", "Backup provider identity does not match its envelope");
+            }
+            return envelope;
+        }
+        finally {
+            providerDek.fill(0);
+        }
+    }
+    const resolution = await resolveMaterial(provider, input.context);
+    const salt = randomBytes(32, input.randomSource);
+    const nonce = randomBytes(12, input.randomSource);
+    try {
+        const info = await keyDerivationInfo(input.context, provider.id, resolution.kekKeyId);
+        const kek = await deriveKek(resolution.keyMaterial, salt, info, "encrypt");
+        const ciphertext = new Uint8Array(await crypto.subtle.encrypt({
+            name: "AES-GCM",
+            iv: ownedBuffer(nonce),
+            additionalData: ownedBuffer(wrapAdditionalData(input.context, provider.id, resolution.kekKeyId)),
+            tagLength: 128
+        }, kek, ownedBuffer(input.dek)));
+        try {
+            return validateBackupKeyEnvelope({
+                version: 1,
+                providerId: provider.id,
+                providerMode: "material",
+                kekKeyId: resolution.kekKeyId,
+                wrapAlgorithm: "AES-256-GCM",
+                kdf: {
+                    algorithm: "HKDF-SHA-256",
+                    version: 1,
+                    salt: encodeBase64Url(salt),
+                    info,
+                    outputBytes: 32
+                },
+                wrappedKeys: [{
+                        id: "dek",
+                        algorithm: "AES-256-GCM",
+                        wrappedKey: encodeBase64Url(ciphertext),
+                        nonce: encodeBase64Url(nonce)
+                    }]
+            });
+        }
+        finally {
+            ciphertext.fill(0);
+        }
+    }
+    finally {
+        resolution.keyMaterial.fill(0);
+        salt.fill(0);
+        nonce.fill(0);
+    }
+}
+/**
+ * Resolve and unwrap an archive DEK. The returned mutable buffer is owned by
+ * the caller and must be overwritten immediately after importing it into a
+ * non-extractable `CryptoKey`.
+ */
+export async function unwrapBackupDek(input) {
+    const envelope = validateBackupKeyEnvelope(input.envelope);
+    const provider = selectProviderForUnwrap(input.providers, envelope);
+    if (provider.mode === "wrapping") {
+        const providerInput = validateBackupRestoreProviderInput(input.providerInput);
+        let dek;
+        try {
+            dek = await provider.unwrapDek({ context: input.context, envelope, providerInput });
+        }
+        catch (error) {
+            throw safeProviderError(error, "BACKUP_PROVIDER_UNAVAILABLE", "The backup key provider could not unwrap the archive key");
+        }
+        finally {
+            clearBackupRestoreProviderInput(providerInput);
+        }
+        if (!(dek instanceof Uint8Array) || dek.byteLength !== backupDekBytes) {
+            if (dek instanceof Uint8Array)
+                dek.fill(0);
+            throw backupProviderFailure("BACKUP_PROVIDER_ENVELOPE_INVALID", `Backup providers must return exactly ${backupDekBytes} DEK bytes`);
+        }
+        const ownedDek = dek.slice();
+        dek.fill(0);
+        return ownedDek;
+    }
+    const resolution = await resolveMaterial(provider, input.context, envelope.kekKeyId);
+    try {
+        if (resolution.kekKeyId !== envelope.kekKeyId) {
+            throw backupProviderFailure("BACKUP_KEY_UNAVAILABLE", "The backup key provider returned the wrong historical key version");
+        }
+        const kdf = envelope.kdf;
+        const wrapped = envelope.wrappedKeys[0];
+        if (!kdf || kdf.algorithm !== "HKDF-SHA-256" || !wrapped?.nonce) {
+            throw backupProviderFailure("BACKUP_PROVIDER_ENVELOPE_INVALID", "The material-provider envelope is incomplete");
+        }
+        const expectedInfo = await keyDerivationInfo(input.context, provider.id, envelope.kekKeyId);
+        if (kdf.info !== expectedInfo) {
+            throw backupProviderFailure("BACKUP_ARCHIVE_IDENTITY_MISMATCH", "The wrapped archive key does not match the restore target");
+        }
+        const salt = decodeBase64Url(kdf.salt, "Backup HKDF salt", backupProviderLimits.saltBytes);
+        const nonce = decodeBase64Url(wrapped.nonce, "Backup DEK wrap nonce", 64);
+        const ciphertext = decodeBase64Url(wrapped.wrappedKey, "Wrapped backup DEK", backupProviderLimits.wrappedKeyBytes);
+        try {
+            const kek = await deriveKek(resolution.keyMaterial, salt, kdf.info, "decrypt");
+            let plaintext;
+            try {
+                plaintext = await crypto.subtle.decrypt({
+                    name: "AES-GCM",
+                    iv: ownedBuffer(nonce),
+                    additionalData: ownedBuffer(wrapAdditionalData(input.context, provider.id, envelope.kekKeyId)),
+                    tagLength: 128
+                }, kek, ownedBuffer(ciphertext));
+            }
+            catch {
+                throw backupProviderFailure("BACKUP_ARCHIVE_CORRUPT", "The wrapped archive key failed authentication");
+            }
+            const dek = new Uint8Array(plaintext);
+            if (dek.byteLength !== backupDekBytes) {
+                dek.fill(0);
+                throw backupProviderFailure("BACKUP_PROVIDER_ENVELOPE_INVALID", "The wrapped archive key has an invalid length");
+            }
+            return dek;
+        }
+        finally {
+            salt.fill(0);
+            nonce.fill(0);
+            ciphertext.fill(0);
+        }
+    }
+    finally {
+        resolution.keyMaterial.fill(0);
+    }
+}
+export function generateBackupDek(randomSource) {
+    return randomBytes(backupDekBytes, randomSource);
+}
+//# sourceMappingURL=backup-crypto.js.map