decrypt-chunk

Purpose

The single-chunk decryption helper that runs on the read side of the pipeline. Given chunk metadata (already parsed via header.parseHeader), the chunk ciphertext, and the file key, it concatenates the ciphertext with the embedded AEAD tag and asks @suaveplan/crypto-cipher/xchacha20-poly1305 to verify-and-decrypt in one call.

Features

decryptChunk(metadata, ciphertext, fileKey): Uint8Array — returns plaintext bytes; the caller is expected to truncate to metadata.payloadLen.
Tag-failure path is structured: a decrypt failure is wrapped as ChunksError(CHUNKS.AEAD_TAG_INVALID) regardless of whether the underlying error was a tag mismatch, an invalid nonce length, or an internal @noble/ciphers rejection.
Allocation-light — only one fresh buffer (fullCiphertext) is allocated per call.

Usage: Basic Example

import { decryptChunk, parseChunk } from "@suaveplan/drive-plugin-chunks";

const chunk = parseChunk(rawChunk);
const plain = decryptChunk(chunk.metadata, chunk.ciphertext, fileKey);
const trimmed = plain.slice(0, chunk.metadata.payloadLen);

Usage: Advanced Example

import {
    CHUNKS_CODES,
    ChunksError,
    decryptChunk,
    parseChunk,
} from "@suaveplan/drive-plugin-chunks";

async function reassembleSafely(rawChunks: Uint8Array[], fileKey: Uint8Array) {
    const out: Uint8Array[] = [];
    for (const raw of rawChunks) {
        const c = parseChunk(raw);
        try {
            const plain = decryptChunk(c.metadata, c.ciphertext, fileKey);
            out.push(plain.slice(0, c.metadata.payloadLen));
        } catch (err) {
            if (err instanceof ChunksError && err.code === CHUNKS_CODES.AEAD_TAG_INVALID) {
                return null; // request a re-fetch from a different peer
            }
            throw err;
        }
    }
    return out;
}

API Reference

decryptChunk(metadata: ChunkMetadata, ciphertext: Uint8Array, fileKey: Uint8Array): Uint8Array — concatenates ciphertext || metadata.aeadTag and runs XChaCha20-Poly1305 decrypt under fileKey and metadata.nonce. Throws ChunksError(CHUNKS.AEAD_TAG_INVALID) on any verification failure.

Implementation Notes

The function does NOT trim the output to payloadLen — that's the caller's job. This avoids a redundant .slice allocation in transport code that already writes plaintext into a preallocated reassembly buffer. The error message is intentionally generic ("chunk AEAD tag verification failed") so consumers cannot use the message text to distinguish between attacker-induced tag mismatches and accidental ciphertext corruption — both are fatal.

2.6 KiB Raw Blame History