Unpacker

(no submodules)

Purpose

Whole-file unpacker. Reverses the Packer pipeline — optionally verifies the ed25519 server signature, AEAD-decrypts, gunzips, optionally verifies the SHA-256 checksum — and returns { data: Uint8Array, metadata: PackedDataMetadata }. The metadata that arrived with the packed envelope is passed through unchanged so callers retain the timestamp, mime, custom fields, etc.

Features

ed25519 signature verification (off by default; opt-in via verifySignature: true).
AEAD decryption with algorithm picked from metadata.encryptionAlgorithm.
gzip decompression triggered by metadata.compressionAlgorithm === "gzip".
SHA-256 checksum verification (opt-in via verifyChecksum: true).
Typed events unpack:start, unpack:verified, unpack:decrypted, unpack:decompressed, unpack:complete.

Usage: Basic Example

import { Unpacker } from "@suaveplan/packer";

const unpacker = new Unpacker();
const { data } = await unpacker.unpack(packedEnvelope);

Usage: Advanced Example

import { Unpacker } from "@suaveplan/packer";

const unpacker = new Unpacker();
const result = await unpacker.unpack(packedEnvelope, {
    key: fileKey,
    verifySignature: true,
    verifyKey: serverPubKey,
    verifyChecksum: true,
});
// result.data === original plaintext, byte-identical

API Reference

class Unpacker extends AbstractPacker
- unpack(packed: PackedData, opts?: UnpackOptions): Promise<UnpackResult>.
- pack() — inherited contract; throws PackerError(PACKER.INVALID_FORMAT) (use Packer for packing).

Failure modes

PACKER.VERIFICATION_FAILED — signature did not verify; verifyKey not supplied while verifySignature: true; verifyKey of wrong length; checksum mismatch.
PACKER.INVALID_FORMAT — metadata.signed set but signature missing; metadata.encrypted set but key/nonce/aeadTag/encryptionAlgorithm missing.

Implementation Notes

The order of operations on the receive path is the reverse of the send path: verify → decrypt → decompress → checksum. Signature verification runs against the post-encryption ciphertext (matching how Packer signs), so it works without the AEAD key — a peer can forward signed-but-encrypted packed bundles and recipients verify provenance without ever decrypting. Checksum verification runs against the post-decompression plaintext, matching what Packer.checksum(...) computed pre-transform — a true integrity round-trip.

2.5 KiB Raw Blame History