@suaveplan/drive-storage-archive-core - Shared archive-mounting primitives for the Suaveplan drive: magic-byte format sniffing, split-volume sibling resolution, password hook contract, mutation-mode enforcement, error code registry, and a conformance harness consumed by every per-format drive-storage adapter.

Shared archive-mounting primitives for the Suaveplan drive: magic-byte format sniffing, split-volume sibling resolution, password hook contract, mutation-mode enforcement, error code registry, and a conformance harness consumed by every per-format drive-storage-* adapter (zip, tar, gz, tgz, rar, 7z).

This package is the FOUNDATION layer — it does not itself read any archive. The per-format adapters live in sibling packages and depend on this one for their cross-cutting concerns.

Documentation tree

errors — Declares the ARCHIVE_CODES registry — ten stable string identifiers covering every failure mode the archive core surf…
- error-codes — Declares the ARCHIVE_CODES registry — ten stable string identifiers covering every failure mode the archive core surf…
factory — Implements the public openArchiveStorage(source, options) factory plus the test-injection seam setDynamicImporter.…
- open-archive-storage — Implements the public openArchiveStorage(source, options) factory plus the test-injection seam setDynamicImporter.…
pending-mutations — Provides the pendingMutations<T>() factory and the PendingMutations<T> overlay interface that per-format archive ad…
validate-mode — Provides validateMode(mode, capabilities) and assertNotReadOnly(mode) — the two helpers every per-format archive ad…
password — Implements the small set of helpers every per-format archive adapter calls when handling encrypted entries: `wrapPasswo…
- password-hook — Implements the small set of helpers every per-format archive adapter calls when handling encrypted entries: `wrapPasswo…
rar-sibling-resolver — Default ResolveSibling factory for split-rar archives. Handles BOTH split-naming conventions transparently — the mode…
seven-zip-sibling-resolver — Default ResolveSibling factory for split-7z archives following the canonical <basename>.7z.NNN naming convention. U…
sibling-host — Declares the minimal SiblingHost structural-view interface that the default sibling-volume resolvers (`zipSiblingReso…
zip-sibling-resolver — Default ResolveSibling factory for split-zip archives following the PKZIP App-Note §8.5.3 convention: intermediate vo…
sniff — Identifies an archive's container format by inspecting magic bytes (and, where appropriate, structural artefacts like t…
- sniff-format — Identifies an archive's container format by inspecting magic bytes (and, where appropriate, structural artefacts like t…
testing — Implements runArchiveConformance(adapterFactory, opts) — the cross-format conformance harness every per-format archiv…
- run-archive-conformance — Implements runArchiveConformance(adapterFactory, opts) — the cross-format conformance harness every per-format archiv…
archive-capabilities — Declares the ArchiveCapabilities record shape that every per-format archive adapter MUST expose so consumers (and the…
archive-codec — Declares the ArchiveCodec interface — the contract a single byte-level compression codec (gzip, bzip2, xz, zstd…) MUS…
archive-format — Declares the canonical ArchiveFormat string-literal union that names every archive container format the Suaveplan dri…
archive-mode — Declares the ArchiveMode string-literal union (read-only, copy-on-write, rewrite) that every per-format archive…
entry-reader — Declares the EntryReader interface that every per-format archive adapter implements internally to surface a single en…
open-archive-storage-options — Declares the option bag passed to openArchiveStorage(source, options) plus the supporting types used by the dynamic-i…
password-hook — Declares the PasswordHook callback signature used by every archive adapter to fetch passwords lazily for encrypted en…
resolve-sibling — Declares the ResolveSibling callback contract that per-format archive adapters use to fetch additional split-volume b…

Quick start

import { openArchiveStorage } from "@suaveplan/drive-storage-archive-core";

const adapter = await openArchiveStorage(zipBytes, {
    format: "auto",
    mode: "read-only",
    password: async () => "correct horse battery staple",
});

console.log(adapter.mode); // "read-only"

Modules

types/ — ArchiveFormat, ArchiveMode, ArchiveCodec, ArchiveCapabilities, EntryReader, PasswordHook, ResolveSibling, OpenArchiveStorageOptions.
sniff/ — sniffFormat + sniffFormatWithReason magic-byte detector covering ZIP, RAR4, RAR5, 7z, GZIP, USTAR tar.
factory/ — openArchiveStorage(source, options) dispatcher + setDynamicImporter test seam.
errors/ — ARCHIVE_CODES registry (10 stable identifiers) + ArchiveError subclass.
resolvers/ — default SiblingHost-backed resolvers for split-zip / split-rar / split-7z.
modes/ — validateMode, assertNotReadOnly, pendingMutations<T>() overlay with TOMBSTONE.
password/ — wrapPasswordHook, assertPasswordHook, consumePassword, withPassword.
testing/ (subpath export ./testing) — runArchiveConformance(adapterFactory, opts) harness.

Error codes

Ten stable identifiers via defineCodes("ARCHIVE", [...]):

ARCHIVE.FORMAT_UNKNOWN — magic bytes did not match any known signature.
ARCHIVE.FORMAT_MISMATCH — caller's declared extension disagrees with the sniffed format (warning).
ARCHIVE.SPLIT_MISSING_VOLUME — resolveSibling returned null for a required volume.
ARCHIVE.PASSWORD_REQUIRED — encrypted entry encountered without a hook.
ARCHIVE.PASSWORD_INVALID — hook returned a value that failed authenticated decryption.
ARCHIVE.MODE_READ_ONLY — mutation attempted on a read-only adapter.
ARCHIVE.FLUSH_REQUIRED — adapter disposed with pending overlay mutations.
ARCHIVE.CORRUPT — structural validation failed.
ARCHIVE.UNSUPPORTED_FEATURE — archive uses a feature the adapter does not implement.
ARCHIVE.CODEC_MISSING — composed adapter constructed without the required codec slot OR per-format package not installed.

Status

0.1.0 — initial bottom-up landing.