Initial Commit

packages/networking/drive/drive-plugin-chunks/src/pipeline/decrypt-chunk.md

@@ -0,0 +1,57 @@
+# 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.