B2 Transfer

Backblaze B2 data-plane transfers via the Native API v4 — the thirteen upload, download and large-file operations, guarded. Inventories the interrupted large uploads B2 bills for invisibly, proves a bucket is readable and writable end to end, and refuses to move more than 100 MB without an explicit override.

First publish of @sntxrr/b2/transfer — the B2 data plane, completing this suite's coverage of all 33 Native API v4 operations.

Thirteen operations across seven methods: scan, upload, download, authorize_download, list_parts, copy_part, delete.

Guarded on purpose. Streaming multi-gigabyte objects through a Deno subprocess produces no meaningful typed state, and restic already moves those bytes over S3, so upload and download refuse anything over maxTransferBytes (100 MB default) — checked before b2_authorize_account, which is itself class-C, so a refused transfer costs nothing at all. A pre-flight check also rejects a model-level cap above 1 GiB, because raising it permanently is how a guarded validation tool quietly becomes an unguarded data mover.

What it is for: proving a bucket is readable and writable independently of restic (upload a canary, download it, compare the SHA-1), and surfacing interrupted large uploads — which B2 stores and bills indefinitely, and which appear in neither b2_list_file_names nor the console's file browser. On the estate this was built for, scan found ten stuck since 2021.

The download authorization token is never persisted. Unlike an application key's one-shot secret it can be re-minted at will, so storing a copy is all risk and no benefit. Enforced as tokenPersisted: z.literal(false).

Honest nulls throughout: sha1Verified null means NOT CHECKED, distinct from false meaning checked-and-mismatched — branch on === false. partCount null means list_parts was never run, not zero parts.

Live-verified end to end in a purpose-built scratch bucket: small upload with SHA-1 verification, multi-part upload from a local file, download by id and by name, a byte-for-byte round trip, a minted-and-verified download authorization, server-side assembly from two source ranges compared byte-for-byte against a locally built expectation, plus ten real cancels and a repeat cancel on the production fleet.

Live exercise found three defects mocks could not: delete was not idempotent (B2 returns catch-all bad_request, not file_not_present, for an already-cancelled file); a pre-flight check gating delete on an acknowledgement made the documented per-run path impossible and forced arming destruction permanently; and copy_part was outright unreachable, so it now owns the whole start/copy/finish lifecycle.