# 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

```ts
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

```ts
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.