@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,110 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-07-08
+
+### Added
+
+- **New `sha1` sync compare mode.** `CompareMode` now accepts `'sha1'`, and `SyncPath` exposes an optional `contentSha1` field plus `contentSha1State` for custom scanners that can supply explicit trust state. The synchronizer hashes local files only when cheaper metadata cannot already prove drift and compares against B2 SHA-1 metadata. B2's verified single-part `contentSha1` can prove equality; multipart `fileInfo.large_file_sha1` and `unverified:<hex>` values are untrusted hints and are verified by hashing the selected B2 version before they can suppress a transfer. Files whose SHA-1 is genuinely unavailable, or whose untrusted B2 bytes cannot be verified before the configured deadline or byte ceiling, are skipped with a surfaced event rather than failing the whole run. SHA-1 comparison uses bounded workers, dry-runs still hash matching-size local files but do not download B2 bytes for untrusted metadata, and `compare` events report local hash reads in `bytesHashed` plus B2 verification reads in `bytesVerified`. Local hashing rejects non-regular files and bounds reads to the scanned size; local and B2 SHA-1 reads use `sha1ReadTimeoutMillis` as an idle/no-progress timeout with a bounded default. Untrusted B2 verification is also bounded by selected-version byte length and `sha1VerificationTimeoutMillis`, with `sha1VerificationMaxBytes` available as a lower per-file byte ceiling. The SDK does not cache untrusted B2 verification results across runs, so unchanged multipart objects can incur full-object B2 download reads every `sha1` sync. Custom scanners can use the exported `selectB2ComparableSha1()`, `parseSyncContentSha1()`, `syncSha1StateOf()`, `untrustedSha1()`, `isUntrustedSha1()`, and `untrustedSha1Prefix` helpers to mark or inspect SHA-1 metadata without duplicating sentinel strings. This is an accidental drift detector, not a cryptographic tamper guarantee. Closes #29.
+- **S3-compatible AWS Signature Version 4 presigned URLs and release hardening.** New `presignS3GetObjectUrl()` and `presignS3PutObjectUrl()` helpers generate real S3-compatible presigned URLs for B2 without passing application-key secrets to runtime peer packages. PUT presigns can bind `Content-Type`, `Content-Length`, and metadata headers for browser / third-party uploads. Trusted server code can opt into intentionally inline or browser-executable response overrides by passing `trustedUnsafeS3PresignOptIn` to `allowInlineResponseContentDisposition`, `allowBrowserExecutableResponseContentType`, or `allowBrowserExecutableContentType`; plain booleans from request JSON are ignored. PUT presigned URLs are replayable until expiry and retries can create duplicate file versions if B2 stored the object but the client missed the response; use unique keys, reconcile by listed file IDs/checksums, and configure lifecycle/version cleanup when needed. The shorter `presignPutObjectUrl()` name remains as a deprecated alias for pre-release adopters. The existing B2-native `presignGetObjectUrl()` positional helper remains as a deprecated compatibility alias; use `createNativeDownloadAuthorizationUrl()` when you intentionally want a B2 download-authorization-token URL. The release workflow now verifies a packed artifact before publishing it with npm trusted publishing and GitHub Release artifact reuse.
+- **Sync include/exclude filters.** `SyncOptions` now accepts `include` and `exclude` filters using SDK glob strings or best-effort guarded regular expressions, with exported `SyncFilterOptions` and `SyncFilterPattern` types for reusable configuration. Filters apply to both local and B2 sides during sync, and `SyncFolder.scan()` accepts the same filter object for standalone scans. Glob filters use the SDK segment dialect (`*` / `?` within one segment, whole-segment `**` across directories, slash-less basename/ancestor matching) and excludes win over includes. RegExp acceptance is a safety heuristic whose exact accepted subset may change as protections tighten; paths beyond the RegExp input guard are skipped whenever any RegExp filter is configured, including exclude-only RegExp deny-lists.
+- **B2 sync scan diagnostics.** `SyncFolder.scan()` accepts `SyncScanOptions.onSkip`, and `synchronize()` surfaces built-in scanner diagnostics as `skip` events with exported `SyncSkipReason` values for objects outside the configured prefix, unsafe relative names, local-filesystem-unsafe names, normalized or local-canonical path collisions, filesystem read errors, paths beyond the RegExp input guard, and aggregated scanner diagnostic overflow. Raw B2 prefixes preserve backslashes as key characters; pass `/` explicitly for slash-delimited prefixes. Custom scanners can use the exported `pathPassesSyncFilters`, `directoryMayContainSyncPaths`, `filterSyncPaths`, `literalPrefixForSyncFilters`, and `pathSkippedByRegExpInputLimit` helpers to match the SDK filter dialect. Built-in scans sort before yielding and B2 scans group listed versions before yielding, so exclude filters and non-literal includes do not bound the scanner memory footprint. `SyncOptions.maxScanEntries` / `SyncScanOptions.maxScanEntries` provide a defined scan-limit failure mode for unexpectedly large scans; B2 scans count every listed file-version record, including versions later skipped by prefix, safety, or filter checks, while local and fallback scans count retained sync paths. Pass `Infinity` only when the process heap is sized for the full result set; raising the limit increases peak scanner memory.
+- **Raw JSON request options bags are public.** `RawRequestOptions` is exported, and `RawClient.getUploadUrl`, `getUploadPartUrl`, `uploadFile`, and `uploadPart` accept options bags for `signal` and `retry`. The older `JsonPostOptions` export remains as a deprecated alias for source compatibility.
+- **Multipart resume exposes public diagnostics and tuning controls.** `ResumeFileIdMismatchError`, `onResumeCandidateRejected`, `onResumePartReused`, `ResumeCandidateRejectedEvent`, `ResumeCandidateRejectedReason`, `ResumePartReusedEvent`, `ResumePartReusedListener`, and the `resumeMaxListPages` / `resumeMaxPartCandidates` / `resumeMaxPartPages` / `resumeDiscoveryTimeoutMs` options are exported or available on high-level upload APIs.
+- **Public B2 response metadata types are exported.** New response-facing types include `PublicEncryptionSetting`, `SseCPublicSetting`, `NoEncryptionWireSetting`, `ReadableFileRetention`, `ReadableLegalHold`, and `UnfinishedLargeFileMetadata`.
+- **`FileSource(path)` / `FileSource.fromPath(path)` for Node local-file uploads.** `FileSource` is exported from the main entry and `@backblaze-labs/b2-sdk/streams`, supports random-access `slice()` reads for multipart uploads, rejects non-regular files and leaf path swaps on a best-effort filesystem identity check, and lets local-to-B2 sync upload files without first buffering them with `readFile`. It detects size/mtime changes and, on POSIX platforms, ctime changes so same-size rewrites with restored mtime are rejected. Parent directory symlinks are followed by the OS unless the caller validates the containing root first; B2-to-local sync rejects symlinked download parents. On Windows, same-size rewrites with restored mtime can be undetectable through Node's portable stat fields; use an independent digest when tamper-resistant integrity is required. `fromPath()` performs asynchronous filesystem validation for async hot paths. `toContentSource(input, size)` also accepts async iterables such as Node `Readable` streams for forward-only uploads.
+- **Multipart cleanup diagnostics.** Multipart upload, streaming upload, and multipart copy options now accept `onCleanupFailure`, and the root export includes `CleanupFailureEvent` / `CleanupFailureListener`, so failed best-effort `b2_cancel_large_file` cleanup and deliberately skipped cleanup after ambiguous finish responses are observable with the relevant `fileId`.
+
+### Changed
+
+- **Sync error summary wording now reports total sync errors.** The terminal summary event changed from `N action(s) failed` to `N sync error(s) occurred` because SHA-1 preparation failures are surfaced alongside transfer/action failures.
+- **Sync concurrency validation is now strict.** `SyncOptions.concurrency` must be a positive integer; invalid values such as `0`, negative numbers, `NaN`, or fractions throw `RangeError` before sync scanning begins.
+- **Sync scan errors now preserve readable-file progress.** Non-root local scan errors are surfaced as per-path `error` events while readable siblings continue; if any scan error occurs, destination-only delete/orphan actions are skipped to avoid removing paths hidden by scan failures.
+- **`compare` events now expose `bytesHashed`.** In `sha1` mode, local bytes read for hashing are reported as `compare.bytesHashed`; `compare.size` remains `0` for compatibility with the previous metadata-only compare event shape. At the type level, `compare` is now represented by `SyncCompareEvent` rather than `SyncActionEventType`, so TypeScript consumers that narrow on action-event types should handle compare events separately.
+- **Node.js 22.3+ is now the minimum supported Node runtime.** `FileSource(path)` validates local files synchronously through Node's `process.getBuiltinModule()` API so `size` is available at construction time; async code should prefer `FileSource.fromPath(path)`.
+- **`REALM_URLS` keeps its mutable `Record<string, string>` source shape.** Runtime realm resolution still trusts only the built-in verified aliases plus direct custom URLs passed to `B2Client`; the export remains mutable for compatibility with existing source that adds local aliases.
+- **S3 region derivation now fails closed for custom endpoints.** `createS3ClientConfig()` and the S3 presign helpers derive the region from standard `s3.<region>.backblazeb2.com` endpoints. Custom, proxied, or non-standard endpoints must pass `region` explicitly and should call `createS3ClientConfig()` during startup or deployment health checks before serving traffic; the SDK no longer falls back to `us-west-004`, which could mis-sign requests.
+- **B2-native download authorization URLs now use B2 file-name path encoding.** The explicit `createNativeDownloadAuthorizationUrl()` helper preserves `/` path separators in file names and percent-encodes each segment, matching B2 download URL conventions. The deprecated `presignGetObjectUrl()` compatibility alias keeps the legacy slash-escaped output format and permissive string-building behavior until a planned breaking release. The explicit helper requires an `https:` Backblaze download origin without userinfo, path, query, or fragment, rejects unsafe bucket names, control characters, or non-integer / negative `validDurationInSeconds`, and builds the bearer URL from the parsed origin rather than raw-concatenating the caller's `downloadUrl`.
+- **S3 presigned GET response overrides fail closed for browser-executable responses.** `presignS3GetObjectUrl()` now rejects unsafe `responseContentType` overrides such as HTML, SVG, XML, and JavaScript media types, malformed media types, `inline` response dispositions, and control characters in response header overrides unless trusted server code passes `trustedUnsafeS3PresignOptIn` to the unsafe opt-in option. S3 object keys with `.` or `..` path segments cannot be presigned safely because common URL parsers normalize them before sending; rename those objects, use a B2-native download authorization URL where appropriate, or proxy the download through a trusted server. The built-in active-content checks are best-effort denylists, not a complete browser security policy; callers should allow-list safe response headers before signing URLs for untrusted users. Presigned URL validity depends on the signing host's clock, so check clock skew when downstream URL use returns SigV4 403s.
+- **S3 presigned PUT helpers fail closed for executable content types and HTTP endpoints.** `presignS3PutObjectUrl()` rejects cleartext `http:` endpoints before emitting bearer URLs and rejects malformed or browser-executable bound `Content-Type` values such as HTML, SVG, XML, and JavaScript media types unless trusted server code passes `trustedUnsafeS3PresignOptIn` to `allowBrowserExecutableContentType`. Omitting `contentType` still lets the URL holder choose any B2-accepted content type, including executable browser content. The built-in media-type check is a best-effort denylist and does not replace an application allow-list or response headers such as `X-Content-Type-Options: nosniff`.
+- **Redacted URL error messages now remove every path segment.** SDK-wide redacted URLs keep the origin but collapse non-empty paths to `/...`, and continue removing userinfo, query strings, and fragments before interpolation into errors.
+- **Response encryption metadata now uses public B2 response shapes.** `FileVersion.serverSideEncryption`, `UploadPartResponse.serverSideEncryption`, and unfinished-large-file encryption metadata are typed as `PublicEncryptionSetting`, so SSE-C response values do not expose customer-key material and B2's `{ mode: null, algorithm: null }` no-encryption wire shape is represented. This is a TypeScript contract change for callers that reused response encryption objects as upload options; migrate by choosing an explicit upload setting such as `SSE_B2`, `SSE_NONE`, or `sseCustomer(...)`.
+- **`ListUnfinishedLargeFilesRequest.startFileId` is documented as inclusive.** The simulator and real-B2 integration coverage now match the B2 cursor behavior used by `b2_list_unfinished_large_files`; callers with hand-written pagination loops should avoid assuming the previous exclusive wording.
+- **Upload response-body failure retries default off for every upload mode.** Single-file, multipart part, and write-stream uploads all disable ambiguous response-body retries unless `retryResponseBodyFailures: true` is set. Opt in only when duplicate versions or replayed parts are acceptable. Fresh upload URL recovery for 408/5xx, stale upload URLs, expired or invalid upload tokens, and network failures is a public upload-layer behavior; bound it with `retry.maxRetries` and observe it with `onUploadRetry`.
+
+### Deprecated
+
+- **RawClient request-control positional overloads are deprecated.** The legacy `signal` / `retry` positional arguments on `getUploadUrl`, `getUploadPartUrl`, `uploadFile`, and `uploadPart` remain source-compatible, but callers should use the `RawRequestOptions` options-bag form.
+
+### Fixed
+
+- **Package version metadata no longer leaks unrelated package fields into built runtime chunks.** The Vite build now replaces `src/version.ts`'s `package.json` import with a version-only virtual module, while `verify:exports` fails if built JS/CJS files contain package metadata tokens such as `devDependencies`, `scripts`, or `packageManager`. This keeps `VERSION` and the User-Agent in sync with `package.json` without shipping a runtime copy of the full package manifest. Closes #66.
+- **Release and runtime-support docs now match the actual gates.** The README now qualifies Cloudflare Workers and Vercel Edge as compatible but not CI-smoke-tested targets, and the release/contributor docs now list the configured coverage thresholds instead of the older 95% statement target.
+- **Multipart resume now verifies unfinished large-file identity before reuse.** Automatic `resume: true` same-name discovery remains supported, and explicit `resumeFileId` remains the targeted path for callers that deliberately trust one unfinished large-file ID. Both paths check upload options, caller file info, freshly fetched effective bucket-default encryption and readable default retention, explicit Object Lock settings, and uploaded part lengths before reuse; unreadable bucket default retention, candidate retention, or candidate legal-hold fields fail closed. Discovery is bounded by page/candidate limits and by `resumeDiscoveryTimeoutMs` only when supplied, or by the caller's abort signal. Automatic resume reuploads planned parts, while explicit resume recomputes local part SHA-1 and skips only parts whose local digest matches B2's part SHA-1. The SDK does not write managed resume keys into durable file metadata. SSE-C is excluded from automatic and explicit resume because B2 does not expose customer-key identity, and incompatible unfinished uploads are left for caller cleanup or lifecycle rules.
+- **`B2Client.getBucket(name)` now falls back to an unfiltered bucket listing when B2 returns no result for the filtered lookup.** This keeps bucket lookup robust when the server-side name filter is temporarily inconsistent while preserving the existing `null` result when no bucket with that name exists.
+- **Sync local writes and deletes are hardened against symlink swaps.** B2-to-local downloads now stream into a unique same-directory temp file and rename it into place, so a leaf symlink swapped in after path validation is replaced rather than followed. Local-to-B2 uploads reopen scanned files with no-follow semantics and verify the opened file remains inside the source root before reading. Local delete paths are revalidated immediately before unlinking. Local sync roots that contain symlinked path components are rejected for downloads and local deletes; the remaining threat model assumes no concurrent untrusted process can replace already-validated parent directories inside the sync root during the final rename or unlink window.
+- **Sync action results stream incrementally after a complete inventory.** `synchronize()` now waits for source and destination inventories to complete successfully before starting mutating actions, then yields upload, download, copy, delete, hide, skip, and per-action error events as actions settle. This prevents a streaming scanner/listing failure from committing partial mutations based on an incomplete inventory. Closing the iterator early aborts and awaits started actions before `return()` settles. The terminal aggregate error event includes `failureCount`, up to 100 `failedPaths`, and `failedPathOmittedCount` when more paths were omitted.
+- **Sync aggregate error paths are distinct.** Repeated failures for the same sync-relative path are counted in `failureCount` but appear only once in the bounded `failedPaths` list, preserving room for additional distinct paths.
+- **Sync transfers honor abort signals and stalled downloads fail fast.** Upload, download, B2 copy, hide, remote delete, and local delete actions receive the sync action abort signal for in-flight cancellation, and built-in scanners check `SyncOptions.signal` during enumeration. B2-to-local download body reads now use `downloadIdleTimeoutMillis` (default 60 seconds) so a half-open response stream releases its concurrency slot with an error instead of hanging indefinitely.
+- **Sync B2 mutation targets are prefix-validated.** Upload replacement, hide, and remote-delete actions no longer trust a custom B2 destination scanner's raw `selectedVersion.fileName` unless it belongs to the configured prefix and normalizes back to the reported sync path.
+- **Sync scanners keep read-only scan semantics and tolerate B2-reserved basenames.** Local scans exclude the managed `.b2sdk-download-staging` directory only when SDK staging markers are present; unmarked lookalikes remain user content. Stale marked staging entries are reaped on later download setup only when marker and partial-file activity is old and unchanged immediately before removal, so active partial downloads are not removed by another setup. B2 scans no longer reject Windows-reserved basenames such as `aux.txt` at scan time, so B2-to-B2 syncs preserve those valid B2 object names; B2-to-local sync skips Windows-dangerous names and case/Unicode-canonical local path collisions before local writes.
+- **B2 include-prefix pushdown preserves backslash-normalized keys.** B2 listing prefixes derived from include globs no longer narrow past a normalized path separator, so a raw key such as `docs\readme.md` can still be listed and filtered as `docs/readme.md` instead of being silently hidden by a `docs/readme.md` include.
+- **`ActionFactory` has a B2SyncPath-aware copy hook while preserving `copy(source, destRelativePath)`.** Custom action factories continue receiving sync-relative destination strings from `copy()`. B2SyncPath-aware implementations can add `copyB2Path(source, dest)` and use `dest.selectedVersion.fileName` when a raw B2 prefix or normalized sync path differs from the stored destination object key.
+- **`ActionFactory` has a B2SyncPath-aware hide hook while preserving `hide(path: string)`.** Custom action factories can continue implementing `hide(path: string)`; B2SyncPath-aware implementations can add `hideB2Path(path: B2SyncPath)` and use `path.selectedVersion.fileName` when they need the stored B2 object key. This keeps hide actions correct when a raw B2 prefix or normalized sync path differs from the object name without breaking existing custom factories.
+- **`realm: 'staging'` now resolves to the staging authorize endpoint.** It previously
+  aliased production (`https://api.backblazeb2.com`), so callers who explicitly
+  configured staging silently authorized against production. Existing
+  `FileAccountInfo` auth caches created with the old staging alias are ignored
+  once bound to the new staging realm so a stale production authorization
+  response is not reused. Persisted `FileAccountInfo` entries are also bound to
+  the configured application key ID so a shared cache path cannot replay auth
+  written by another key. Legacy caches without key-binding metadata are ignored
+  after binding and will re-authorize once without truncating the shared cache
+  file. During a rolling deploy, old and new code resolve `realm: 'staging'` to
+  different hosts; avoid staging-realm traffic during the upgrade window if that
+  split matters for the deployment. For shared `FileAccountInfo` paths, prefer
+  one cache path per resolved realm and application key, and wire `onDiscard`
+  during the upgrade to observe any cache entries ignored by the new binding.
+  Custom-realm cache reuse now only accepts cached endpoints on the exact realm
+  host or its subdomains, and loopback/sibling public-suffix endpoints are
+  discarded by default.
+  The new `https://api.backblaze.net` staging host matches the Backblaze Python
+  SDK realm map. This is a runtime host change for users of `realm: 'staging'`.
+  Closes #34.
+- **Realm URLs are validated before authorization sends credentials.** Custom
+  realm values must be absolute HTTPS URLs, except loopback IP literal HTTP URLs
+  used for local testing. Non-URL strings, unsupported schemes, malformed URLs,
+  URLs with userinfo/query/fragment, hostnames such as `localhost`, and
+  non-loopback plaintext HTTP now throw `B2RealmConfigurationError` before the
+  application key is sent. `getRealmUrl()` remains a resolver-only helper:
+  unknown strings are returned unchanged so callers can resolve custom aliases,
+  and validation happens at authorization time. Accepted custom HTTPS hosts are
+  trusted with the application key, so do not derive `realm` from untrusted
+  input. Loopback HTTP sends application-key credentials unencrypted and is
+  intended only for local simulator or proxy testing.
+- **Redirect handling is now guard-checked in `FetchTransport`.** Same-origin
+  GET/HEAD redirects are followed by default after each target passes the SSRF
+  guard. POST redirects and cross-origin redirects surface as non-retryable
+  `B2RedirectError`, exported from the package root and
+  `@backblaze-labs/b2-sdk/errors`, with request and Location URLs sanitized
+  before they appear in error messages. Pass `followSameOriginRedirects: false`
+  to block even same-origin GET/HEAD redirects. Browser and edge runtimes may
+  report cross-origin manual redirects as opaque redirects with no readable
+  Location, so those remain blocked. Monitor or catch `B2RedirectError` during
+  rollout if your deployment might depend on CDN, proxy, or regional redirect
+  behavior.
+- **Downloads now verify whole-file SHA-1 checksums when B2 provides a verifiable digest.** Full-body GET downloads wrap the response stream and throw `ChecksumMismatchError` if the bytes do not match `X-Bz-Content-Sha1`; parallel ranged downloads verify the assembled stream in order and reject cross-range header disagreements. HEAD requests, partial range GETs, and files whose download SHA-1 is unavailable (`none` / `null`) continue to skip verification because no matching whole-body digest exists. Closes #25.
+- **`B2Simulator` `b2_copy_file` now honors `metadataDirective`, `contentType`, `fileInfo`, and `range`.** A `COPY` directive (default) preserves the source's content type and file info; `REPLACE` applies the request's (and is rejected with `400 bad_request` when `contentType` is missing, matching real B2, with the supplied `fileInfo` validated). A byte `range` copies only the requested slice and recomputes its SHA-1, rejecting an unsatisfiable range with `416`. Previously the simulator ignored all four and always did a whole-file COPY.
+- **Retry transient 5xx responses.** `internal_error` / HTTP 500 (and 502 Bad Gateway, 504 Gateway Timeout) are now classified as retryable, so `RetryTransport` retries them with backoff alongside 408/429/503. Previously a transient 500 surfaced as an immediate, non-retryable failure. 501 Not Implemented remains non-retryable (deterministic). Upload endpoints (`b2_upload_file` / `b2_upload_part`) do not retry pod failures in place: they are URL-pinned, so retryable pod failures now bubble to the upload layer for fresh-URL recovery. HTTP 429 upload throttling still backs off on the same upload URL to avoid amplifying account-level rate limits with extra URL fetches. Each request attempt now has a configurable `retry.requestTimeoutMs` timeout, defaulting to 15 minutes. It covers request dispatch, upload request bodies, and non-streaming response-body reads; streamed download bodies use the same value as an idle/no-progress timeout that resets after each received chunk. Slow large-part uploads may need a higher value or `0` to disable the SDK timeout and rely on caller cancellation.
+- **Uploads now retry transient failures with fresh upload URLs.** Single-file uploads, multipart parts, stream-backed multipart uploads, and `createWriteStream()` evict a failed upload URL, back off with one upload retry budget, fetch a fresh upload URL / part URL without nested transport retries, and retry there for 408/5xx, stale upload URLs, expired or invalid upload tokens, request timeouts, and network failures. New public `onUploadRetry` and `retryResponseBodyFailures` options are available on high-level upload APIs, and `UploadRetryEvent` / `UploadRetryListener` / `UploadResponseBodyError` are exported from the package root. `onUploadRetry` reports file name, part number, attempt, delay, and classified error before each retry; observer exceptions are ignored so telemetry failures do not abort retry recovery. Direct raw upload endpoint calls no longer receive nested transport retries for upload-pod network failures; use the high-level upload APIs for fresh-URL recovery. If the first upload POST succeeded but the response was lost, retrying can create a duplicate file version, so response-body failures do not re-send payloads by default. Set `retryResponseBodyFailures: true` to opt into that at-least-once behavior when availability is preferred over duplicate-version avoidance, and use lifecycle or version-retention rules when buckets need automatic cleanup.
+  During a rolling deploy, older SDK processes may still retry lost response
+  bodies while newer processes report the ambiguous upload as an error; reconcile
+  by comparing returned or listed file IDs and SHA-1 values for the target file
+  name.
+- **Ambiguous `b2_finish_large_file` response-body failures no longer trigger cleanup.** If the finish request may have committed but its JSON body cannot be read, high-level upload/copy paths throw `FinishLargeFileResponseBodyError` and do not cancel the large file, avoiding a blind re-upload that could create duplicate versions. The error carries `fileId` plus high-level `bucketId`/`fileName` when available, and the cleanup observer is notified with `reason: "finish-ambiguous"` so operators can reconcile the possible orphan or committed file.
+- **Correct browser SHA-1 for buffer-backed views.** `sha1Hex`'s WebCrypto path hashed `data.buffer` (the whole backing `ArrayBuffer`) instead of the `Uint8Array` view's `byteOffset`/`byteLength`, so a subarray (e.g. a carved multipart part) produced a wrong digest in browsers and other non-Node runtimes. It now hashes the view directly. (`IncrementalSha1`'s WebCrypto fallback was already correct, since it copies chunks into an exact-sized buffer before hashing; it now passes that buffer directly too, for consistency.) The Node `crypto` path was always correct.
+- **`B2Simulator` now verifies upload SHA-1 and persists `fileInfo` across all upload paths.** `b2_upload_file` and `b2_upload_part` recompute the body's SHA-1 and reject a mismatch with `400 bad_request` ("Sha1 did not match data received"), honoring the `none` / `do_not_verify` / `unverified:<hex>` sentinels and the `hex_digits_at_end` trailing-digest mode (the trailing 40 bytes are verified and stripped, not stored as content). `finishLargeFile` verifies each `partSha1Array` entry against the stored part's SHA-1 (rejecting a mismatch with `400 bad_request`). Uploaded `fileInfo` is now persisted for both single-file and multipart (`finishLargeFile`) uploads and returned by `getFileInfo`, list, and `download` (serialized as `X-Bz-Info-*` headers using the same B2 `encodeFileName` encoding the download parser decodes with). Closes gaps where the test backend accepted any hash and silently discarded metadata. `B2Simulator.handleUpload` is now `async`.
+
 ## [0.1.0] - 2026-05-28
 
 First public release of `@backblaze-labs/b2-sdk`. Everything below is new in this version.
@@ -22,9 +126,9 @@ First public release of `@backblaze-labs/b2-sdk`. Everything below is new in thi
 
 ### Added — source-level isomorphism
 
-- **`.ts` extensions on every internal relative import.** `tsconfig.json` enables `allowImportingTsExtensions` + `rewriteRelativeImportExtensions`. One source tree now runs unmodified in Node 22+, Bun, Deno (no build step, no `node_modules`, no `npm:` shim), browsers, Cloudflare Workers, and Vercel Edge. Vite rewrites the extensions during build so consumers still see `./foo.js` in dist/.
+- **`.ts` extensions on every internal relative import.** `tsconfig.json` enables `allowImportingTsExtensions` + `rewriteRelativeImportExtensions`. One source tree now runs unmodified in Node 22.3+, Bun, Deno (no build step, no `node_modules`, no `npm:` shim), and browsers, while targeting the same Web APIs used by Cloudflare Workers and Vercel Edge. Vite rewrites the extensions during build so consumers still see `./foo.js` in dist/.
 - **Deno typecheck workflow** verifies the property on every push: `deno check examples/...` resolves `@backblaze-labs/b2-sdk` straight at `../src/*.ts` via `examples/deno.json`. If a `.js` extension ever sneaks back into an internal import, the workflow fails immediately.
-- **JSON-imported version constant.** `src/version.ts` does `import pkg from '../package.json' with { type: 'json' }; export const VERSION = pkg.version`. Bumping the package version automatically propagates to the User-Agent header and the published artifact — no separate `src/version.ts` to maintain, no sync script. Rollup tree-shakes the JSON down to a 133-byte module containing only the version field; no devDependency or metadata leak to consumers.
+- **JSON-imported version constant.** `src/version.ts` does `import pkg from '../package.json' with { type: 'json' }; export const VERSION = pkg.version`. Bumping the package version automatically propagates to the User-Agent header and the published artifact — no separate `src/version.ts` to maintain, no sync script. The release build emits a version-only JSON shim so runtime chunks do not carry unrelated package metadata.
 
 ### Added — telemetry & identity
 
@@ -41,9 +145,9 @@ First public release of `@backblaze-labs/b2-sdk`. Everything below is new in thi
 
 ### Added — CI & examples
 
-- **`real-examples` CI job** runs every documented `npx tsx examples/...` command against a real B2 account after the integration suite passes (Node 22 + 24, serialised). The runner asserts content round-trip equality for both `node-download` and `node-backup-cli restore`. A renamed flag, swapped argument order, or stale README command fails CI before reaching users.
+- **`real-examples` CI job** runs every documented `npx tsx examples/...` command against a real B2 account after the integration suite passes (Node 22.18 + 24, serialised). The runner asserts content round-trip equality for both `node-download` and `node-backup-cli restore`. A renamed flag, swapped argument order, or stale README command fails CI before reaching users.
 - **`smoke-examples` CI job** runs the same examples against an in-memory `B2Simulator` on every push and PR — zero credentials, zero network, zero cost. Exercises the `npx tsx`/`exports`-map resolution path the same way an `npm install`-ed consumer would.
-- **Real-B2 integration workflow** (`.github/workflows/integration.yml`) runs the integration suite sequentially across Node 22 + 24 with `max-parallel: 1`, on push, PR, weekly schedule, and `workflow_dispatch`. Defensive `sdk-test-*` bucket sweep at startup absorbs leftovers from crashed runs.
+- **Real-B2 integration workflow** (`.github/workflows/integration.yml`) runs the integration suite sequentially across Node 22.18 + 24 with `max-parallel: 1`, on push, PR, weekly schedule, and `workflow_dispatch`. Defensive `sdk-test-*` bucket sweep at startup absorbs leftovers from crashed runs.
 - **Examples Deno + Bun typecheck jobs.** `bunx tsc --noEmit -p examples/tsconfig.json` and `deno check` (via `examples/deno.json` import map) run on every push.
 
 ### Changed — lint gate
@@ -117,5 +221,6 @@ First public release of `@backblaze-labs/b2-sdk`. Everything below is new in thi
 - TypeDoc for API documentation
 - Vitest test suite with 486 tests across 20 files at ≥ 95% statement coverage. Tests run cleanly under both vitest (Node) and Bun's vitest-compat (no module-level mocking required)
 
-[Unreleased]: https://github.com/backblaze-labs/b2-sdk-typescript/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/backblaze-labs/b2-sdk-typescript/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/backblaze-labs/b2-sdk-typescript/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/backblaze-labs/b2-sdk-typescript/releases/tag/v0.1.0

package/README.md

@@ -5,12 +5,12 @@
 [![npm](https://img.shields.io/npm/v/@backblaze-labs/b2-sdk?color=cb3837)](https://www.npmjs.com/package/@backblaze-labs/b2-sdk)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A522-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A522.3-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
 [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](package.json)
 
-The official Backblaze B2 Cloud Storage SDK for TypeScript and JavaScript.
+A Backblaze-maintained TypeScript and JavaScript SDK for Backblaze B2 Cloud Storage, currently incubating in [Backblaze Labs](https://github.com/backblaze-labs).
 
-**Isomorphic at the source level.** One source tree runs unmodified in Node.js 22+, Bun, Deno, browsers, Cloudflare Workers, and Vercel Edge. Internal imports use `.ts` extensions so Deno reads `src/` directly with no build step. See [Source isomorphism](#source-isomorphism).
+**Isomorphic at the source level.** One source tree runs unmodified in Node.js 22.3+, Bun, Deno, and browsers, and is designed around the same Web APIs used by Cloudflare Workers and Vercel Edge. Internal imports use `.ts` extensions so Deno reads `src/` directly with no build step. See [Source isomorphism](#source-isomorphism).
 
 **Async-first.** Built on Web Streams, `AbortSignal`, and `crypto.subtle`. No callbacks, no legacy APIs.
 
@@ -85,7 +85,7 @@ await bucket.delete()
 Small files (under the recommended part size, typically 100 MB) are uploaded in a single request. Larger files automatically use multipart upload with parallel part uploads.
 
 ```ts
-import { BufferSource, BlobSource } from '@backblaze-labs/b2-sdk'
+import { BufferSource, BlobSource, FileSource, toContentSource } from '@backblaze-labs/b2-sdk'
 
 // From a Uint8Array
 await bucket.upload({
@@ -100,10 +100,22 @@ await bucket.upload({
   contentType: 'image/jpeg',
 })
 
-// Large file with progress tracking
+// From a local file path (Node)
+await bucket.upload({
+  fileName: 'backups/db.dump',
+  source: await FileSource.fromPath('/var/backups/db.dump'),
+})
+
+// From a forward-only stream or async iterable (size required)
+await bucket.upload({
+  fileName: 'exports/report.ndjson',
+  source: toContentSource(nodeReadable, knownByteLength),
+})
+
+// Large file with progress tracking (Node)
 await bucket.upload({
   fileName: 'backup.tar.gz',
-  source: new BlobSource(largeBlob),
+  source: await FileSource.fromPath('/path/to/backup.tar.gz'),
   concurrency: 8,
   partSize: 64 * 1024 * 1024,
   onProgress: (event) => {
@@ -113,9 +125,44 @@ await bucket.upload({
 })
 ```
 
+`FileSource` rejects non-regular leaf paths, later leaf path swaps, and same-size rewrites that restore mtime on POSIX platforms. Parent directory symlinks are followed unless your application validates the containing root first. On Windows, `FileSource` skips unreliable dev/inode and ctime comparisons and validates size and mtime instead.
+
+Transient upload failures are retried with a fresh B2 upload URL, matching B2's documented flow. If the first upload POST succeeded but its response was lost, retrying can create a duplicate file version.
+
+Use `onUploadRetry` to log or count retry attempts, compare returned file IDs and SHA-1 values when reconciling uploads, and configure lifecycle or version-retention rules for buckets where duplicate versions must be cleaned up automatically. Retry diagnostics are event-only: the SDK does not log, count, or persist them unless this listener records them. Payload re-POSTs and fresh-URL fetches spend one upload retry budget and are bounded by `retry.maxRetries + 1` attempts per file or part; aggregate retries scale with multipart transfer concurrency. Upload 429 throttling backs off on the same upload URL instead of fetching a new one.
+
+Uploads do not retry lost success response bodies or upload POST network errors by default because re-posting `b2_upload_file` can create duplicate versions, especially in versioned or Object Lock buckets. If callers opt into this ambiguity with `retryResponseBodyFailures: true`, retryable upload POST network errors and unreadable response bodies can re-post the payload with a fresh URL, bounded by `retry.maxRetries`; any uploaded `fileRetention` or `legalHold` applies to each duplicate version and can prevent deletion until the retention policy expires or the hold is cleared. Multipart callers may also opt in when replaying the same `partNumber` is acceptable before `finishLargeFile`, including SSE-B2 encrypted parts.
+
+Large-file part retries are coordinated per part, not by a shared circuit breaker. During a B2 pod or main-API incident, concurrent parts can independently back off with jitter, fetch fresh part URLs, and retry in parallel; aggregate fresh-URL traffic scales with multipart concurrency and `retry.maxRetries`. Multipart workers abort sibling work promptly after a fatal part failure, and best-effort cleanup is bounded so aborting a stream does not hang indefinitely. Tune `concurrency`, `retry`, and `onUploadRetry` for operators that need outage counters or stricter load shedding. Each HTTP attempt has a 15 minute deadline by default; for streamed download bodies the timeout is idle/no-progress and resets after each chunk. Set `retry.requestTimeoutMs` higher for very slow upload links or to `0` to rely only on your own `AbortSignal`.
+
+`FileSource` is the Node.js-only content adapter. It is safe to import from the
+main package in browser builds, but `FileSource.fromPath()` and its read methods
+need local filesystem APIs at runtime. The source records the validated file
+identity and fails with `FileSource file changed after validation` if the path is
+replaced, truncated, content-modified, or has ctime-changing metadata updates
+while a multipart upload is reading it. On platforms without `O_NOFOLLOW`,
+leaf-symlink swaps are rejected by the post-open identity check rather than by
+the open flag. Retry after active writers stop changing the file.
+
 #### Resume a failed multipart upload
 
-Pass `resume: true` and the SDK looks up the matching unfinished large file via `b2_list_unfinished_large_files`, checks which parts are already on the server, and only re-uploads the missing ones. Parts whose locally-recomputed SHA-1 matches the server's are skipped.
+Resume has two paths. `resumeFileId` targets a known unfinished large-file ID returned by B2 when the multipart upload was started. `resume: true` without `resumeFileId` runs bounded same-name discovery and may continue uploading into the newest compatible unfinished upload; incompatible candidates are skipped and a fresh upload starts. Automatic discovery reuploads every planned part into the selected unfinished file instead of trusting pre-existing server parts by SHA-1 alone. With explicit `resumeFileId`, each local part is hashed again and matching server parts are skipped only when the locally recomputed SHA-1 equals B2's part SHA-1.
+
+Resume discovery is intentionally conservative. The SDK reuses only the newest unfinished large file whose file name, content type, caller-provided file info, encryption, Object Lock retention, legal hold, and uploaded part lengths match the current call. If those checks fail, a new large file is started instead. Caller-provided file info such as `large_file_sha1` or `src_last_modified_millis` is part of that identity, so keep it stable across retries. Discovery does not add SDK metadata to unfinished or finished file info.
+
+Automatic resume requires a stable content type. When the upload uses the SDK default `b2/x-auto`, same-name discovery starts a fresh large file unless B2 lists the unfinished file with the same `b2/x-auto` value. Provide an explicit `contentType` for automatic resume, or use `resumeFileId` when the caller deliberately trusts a specific unfinished file's listed content type. Explicit content types still require an exact match.
+
+Automatic resume discovery does not use B2's stored part SHA-1 to skip local bytes because B2 unfinished-large-file records do not identify the writer that started them. It may still finish a compatible same-name unfinished upload after overwriting planned parts with locally read bytes, so use exact file names and stable caller-owned file info when shared buckets have concurrent writers. Use `resumeFileId` only when the caller deliberately trusts the specific unfinished file ID.
+
+The discovery scan is bounded to avoid unbounded prefix-flood work in shared buckets, but it still runs before the first upload byte. By default the SDK inspects up to 10 unfinished-file pages, up to 25 metadata-compatible candidates, and up to 10 part pages per candidate, so a worst-case resume attempt can add many sequential B2 list calls before data transfer starts. Tune `resumeMaxListPages`, `resumeMaxPartCandidates`, and `resumeMaxPartPages` for buckets with many concurrent same-prefix uploads. The SDK does not install a default resume discovery timeout; set `resumeDiscoveryTimeoutMs` or pass an abort signal such as `AbortSignal.timeout(...)` when discovery needs a first-byte time budget. If the scan is truncated, the SDK reports `search-truncated`; when a compatible candidate was already scanned, that candidate may still be reused.
+
+Rejected candidates and failed attempts that reused an existing unfinished file are left unfinished. B2 stores uploaded parts for unfinished large files until they are finished, cancelled, or removed by a lifecycle rule, so stricter matching or repeated prefix-flood truncation can leave billable unfinished uploads behind. Applications with strict resume matching should configure lifecycle cleanup or periodically use `listUnfinishedLargeFiles` and `cancelLargeFile` to remove stale unfinished uploads.
+
+When the caller omits `serverSideEncryption`, high-level bucket and object uploads verify candidates against the bucket's current default encryption freshly fetched from B2, including default SSE-B2 or no encryption. Explicit `serverSideEncryption: { mode: 'none' }` still requires an unencrypted candidate. SSE-C uploads are not resumed automatically or with `resumeFileId` because B2 does not expose a non-secret customer-key identity for unfinished files. With `resume: true`, an SSE-C retry starts a new large file. With `resumeFileId`, SSE-C fails with `ResumeFileIdMismatchError` rather than risking a finish under an unverified key.
+
+Object Lock state must also be verified before reuse. When the caller omits `fileRetention`, high-level bucket and object uploads use the readable bucket default retention freshly fetched from B2; candidates without the exact required default retention window are skipped. Unreadable bucket default retention, candidate retention, or candidate legal-hold fields fail closed. Explicit retention or legal-hold values still require readable matching candidate metadata.
+
+Pass `onResumeCandidateRejected` to collect diagnostic events when a same-name unfinished large file is skipped, including reasons such as `file-info-mismatch`, `part-length-mismatch`, `search-truncated`, or `sse-c-unsupported`. Resume diagnostics are event-only: without this listener, a conservative resume decline falls back to a fresh upload without SDK logging or counters. Candidate-specific events include `requestedFileName` and `candidateFileName` so logging can distinguish the intended upload name from the rejected unfinished file. Pass `onResumePartReused` to observe each pre-existing server part accepted by explicit `resumeFileId` through the SHA-1 equality gate. If a supplied `resumeFileId` is incompatible or cannot be verified through B2's unfinished-large-file listing, `ResumeFileIdMismatchError` is thrown instead of silently starting a different large file.
 
 ```ts
 // Restart the upload that crashed at part 47 of 100
@@ -123,13 +170,6 @@ await bucket.upload({
   fileName: 'backup.tar.gz',
   source: new BlobSource(largeBlob),
   partSize: 64 * 1024 * 1024,
-  resume: true,
-})
-
-// Or target a specific in-progress large file explicitly
-await bucket.upload({
-  fileName: 'backup.tar.gz',
-  source: new BlobSource(largeBlob),
   resumeFileId: knownLargeFileId,
 })
 ```
@@ -150,7 +190,7 @@ const fileVersion = await done
 console.log(`Streamed upload finished: ${fileVersion.fileName} (${fileVersion.contentLength} bytes)`)
 ```
 
-> Streaming uploads do not support resume because the total size and per-part SHA-1s are not known in advance. Use the buffered `upload` path with `resume: true` when that matters.
+> Streaming uploads do not support resume because the total size and per-part SHA-1s are not known in advance. Use the buffered `upload` path with `resumeFileId` when that matters.
 
 ### Downloads
 
@@ -165,16 +205,23 @@ const partial = await bucket.download('large-file.bin', {
 })
 
 // Parallel ranged download (for large files).
-// Each range is retried independently with exponential backoff so a single
-// transient 503 does not kill the whole transfer.
+// Each range uses the client's configured RetryTransport budget, so transient
+// 503s are retried without adding a second default retry layer per chunk.
 const obj = bucket.file('big-dataset.parquet')
 const stream = obj.createReadStream(fileId, totalSize, {
   concurrency: 4,
   rangeSize: 10 * 1024 * 1024,
-  maxRetries: 5,
 })
 ```
 
+Full-body downloads are automatically verified when B2 returns a real `X-Bz-Content-Sha1` digest. If the downloaded bytes do not match, the body stream errors with `ChecksumMismatchError`; discard any partially written output when piping to disk. HEAD requests, range GETs, and files whose SHA-1 is unavailable are not verified because no matching whole-body digest exists.
+
+### Sync SHA-1 comparisons
+
+`compareMode: 'sha1'` hashes matching-size local files and compares them with verifiable B2 SHA-1 metadata. B2 multipart objects do not have an authoritative `contentSha1`; when only `fileInfo.large_file_sha1` or another untrusted hint is available, a real sync downloads that selected B2 version and hashes the full object before skipping a transfer. The SDK does not persist that verification result, so an unchanged 100 GB multipart object can cost 100 GB of B2 download reads on every SHA-1 sync run. `compare.bytesVerified` reports those B2 verification bytes for the run. Use `sha1VerificationMaxBytes` to skip objects above your per-file verification budget, raise `sha1VerificationTimeoutMillis` for large objects on slow links, or use `size`/`modtime` mode when recurring verification egress is not acceptable.
+
+B2-to-local sync streams downloads through a private managed staging directory under the destination root before renaming into place. The scanner ignores that managed directory and stale SDK-owned staging entries are reaped on later download setup. New files are published as 0600 by default, replacements keep the previous file mode, and download body stalls use `downloadIdleTimeoutMillis` (60 seconds by default) rather than `sha1ReadTimeoutMillis`. `B2Folder` prefixes are raw B2 key prefixes: use `photos/` for a slash-delimited folder, or `photos` to match every key beginning with those bytes.
+
 ### File operations
 
 ```ts
@@ -251,7 +298,7 @@ import { Capability } from '@backblaze-labs/b2-sdk'
 const key = await client.createKey({
   capabilities: [Capability.ReadFiles, Capability.WriteFiles],
   keyName: 'my-app-key',
-  bucketId: bucket.id,
+  bucketIds: [bucket.id],
   namePrefix: 'uploads/',
   validDurationInSeconds: 86400,
 })
@@ -386,7 +433,10 @@ const auth = await bucket.getDownloadAuthorization('photos/', 3600)
 import { B2Client } from '@backblaze-labs/b2-sdk'
 import { FileAccountInfo } from '@backblaze-labs/b2-sdk/auth/file'
 
-const accountInfo = new FileAccountInfo('/var/cache/my-app/b2-auth.json')
+const accountInfo = new FileAccountInfo('/var/cache/my-app/b2-auth.json', {
+  onDiscard: (event) => console.warn('ignored stale B2 auth cache', event.reason),
+  onWriteError: (event) => console.warn('could not persist B2 auth cache', event.error),
+})
 await accountInfo.load() // populate from disk if the file exists
 
 const client = new B2Client({
@@ -400,7 +450,7 @@ if (accountInfo.getAuth() === null) {
 }
 ```
 
-`load()` returns silently on missing or corrupt files (a fresh `authorize()` will populate fresh state). Call `await accountInfo.flushed()` before process exit if you need to guarantee the latest state has hit disk.
+`load()` returns silently on missing or corrupt files (a fresh `authorize()` will populate fresh state). `onDiscard` fires when a loaded cache entry is ignored because its realm, application key ID, or cached endpoints do not match the current client; `onWriteError` reports asynchronous write failures that would otherwise be best-effort. Call `await accountInfo.flushed()` before process exit if you need to guarantee the latest state has hit disk.
 
 ## Subpath exports
 
@@ -436,15 +486,57 @@ import {
 // Sync engine (local <-> B2)
 import { synchronize, LocalFolder, B2Folder } from '@backblaze-labs/b2-sdk/sync'
 
-// S3-compatible helpers (requires @aws-sdk/client-s3 peer dependency)
-import { createS3ClientConfig, presignGetObjectUrl } from '@backblaze-labs/b2-sdk/s3'
+// S3-compatible helpers
+import {
+  createS3ClientConfig,
+  presignS3GetObjectUrl,
+  presignS3PutObjectUrl,
+} from '@backblaze-labs/b2-sdk/s3'
 
 // In-memory B2 server for tests (no network required)
 import { B2Simulator } from '@backblaze-labs/b2-sdk/simulator'
 ```
 
+`createS3ClientConfig()` is for `@aws-sdk/client-s3`; install that optional peer
+before constructing an AWS `S3Client`. The presign helpers sign internally and
+do not require AWS presigner packages.
+
+Raw methods use a trailing options bag for request controls such as cancellation
+and per-request retry overrides: pass `{ signal, retry }` to `getUploadUrl`,
+`getUploadPartUrl`, `uploadFile`, and `uploadPart`. The older positional
+`signal, retry` form remains available only for source compatibility.
+
 Every export is documented with full type signatures in the [API reference](https://backblaze-labs.github.io/b2-sdk-typescript/).
 
+## Sync filters
+
+`synchronize()` and the built-in `LocalFolder` / `B2Folder` scanners accept `include` and `exclude` filters for paths relative to each sync root:
+
+```ts
+for await (const event of synchronize({
+  source: new LocalFolder('./site'),
+  dest: new B2Folder(bucket, 'site/'),
+  bucket,
+  prefix: 'site/',
+  options: {
+    compareMode: 'modtime',
+    keepMode: 'no-delete',
+    include: ['assets/**', '*.html'],
+    exclude: ['*.tmp', 'node_modules', 'dist/cache/**'],
+  },
+})) {
+  console.log(event)
+}
+```
+
+Glob strings use the SDK dialect: `*` and `?` stay within one path segment, a whole `**` segment crosses directories, slash-less patterns match any basename or ancestor directory, and excludes win over includes. Use `dir/**` for directory-subtree patterns such as `dist/cache/**`; a slash-containing literal such as `dist/cache` matches only that exact path. RegExp filters are guarded by a best-effort synchronous safety heuristic whose exact subset may change as protections tighten. Paths beyond the RegExp input guard are skipped when any RegExp filter is present, including exclude-only RegExp deny-lists. B2 prefixes are raw object-name prefixes; backslashes are not rewritten to `/`.
+
+`SyncFolder.scan()` direct consumers should expect paths sorted with `compareSyncRelativePaths`, exported from `@backblaze-labs/b2-sdk/sync`. During `synchronize()`, custom folders are filtered before pairing even when they set `appliesScanFilters: true`; scanner-side filtering is an optimization, not the policy boundary. Custom scanner authors can call `filterSyncPaths(paths, options)` and forward `SyncScanOptions.onSkip` so RegExp input-limit diagnostics are preserved. Custom folders that do not set `appliesScanSorting: true` are sorted before pairing. The built-in local and B2 scanners set both flags. `SyncOptions.maxScanEntries` / `SyncScanOptions.maxScanEntries` default to the SDK scan ceiling and fail with a defined scan-limit error when exceeded; B2 scans count every listed file-version record, including versions later skipped by prefix, safety, or filter checks, while local and fallback scans count retained sync paths. Pass `Infinity` only when the process heap is sized for the full result set; raising the limit increases peak scanner memory because built-in scans sort or group results before yielding.
+
+Built-in scanner skip diagnostics use `SyncSkipReason` values such as `outside-prefix`, `unsafe-name`, `local-unsafe-name`, `relative-path-collision`, `local-path-collision`, `filesystem-error`, and `path-too-long-for-regexp`. The `onSkip` callback receives every diagnostic; the `SyncEvent` stream buffers the first 100 scanner diagnostics and then reports overflow with `scan-skip-overflow`.
+
+B2-to-local sync skips object names that are unsafe on local filesystems, including NTFS alternate data stream names, DOS device basenames, trailing dot/space names, the reserved `.b2sdk-download-staging` namespace, and case/Unicode-canonical collisions. Downloads stream into private per-download entries under the destination root's managed `.b2sdk-download-staging` directory and publish completed files into place; SDK-owned staging roots and entries carry `.b2sdk-staging-marker.partial` files. Local scans are read-only and exclude the managed staging directory when those markers are present so abandoned staging state is not uploaded as source content. Later download setup reaps stale SDK-owned staging entries only when marker and partial-file activity is old and unchanged immediately before removal. Download body reads have a 60 second idle timeout by default; set `downloadIdleTimeoutMillis` to tune it or `Infinity` to disable the watchdog. Downloads and local deletes reject symlinked local roots and symlinked path components under the root, then revalidate root, parent, and leaf identity immediately before filesystem operations. Uploads support symlinked source roots by binding the resolved root identity before scanning, then reopening scanned files with no-follow semantics and verifying the opened file remains inside that bound source root before reading. Per-action failures are emitted as `error` events; the terminal aggregate error includes `failureCount`, up to 100 `failedPaths`, and `failedPathOmittedCount` when more paths were omitted.
+
 ## Custom transport
 
 The SDK uses a pluggable transport layer. The default `FetchTransport` uses the native `fetch` API. You can provide your own:
@@ -470,7 +562,7 @@ const client = new B2Client({
 Every request the SDK issues carries a User-Agent header that Backblaze can grep server logs by:
 
 ```
-b2-sdk-typescript/0.1.0 (typescript; @backblaze-labs/b2-sdk; node/24.14.1; linux; x64)
+b2-sdk-typescript/<version> (typescript; @backblaze-labs/b2-sdk; node/<node-version>; linux; x64)
 ```
 
 Both `b2-sdk-typescript/` (stable product token) and `@backblaze-labs/b2-sdk` (npm package name) are part of the documented contract — log queries that match either one find every request issued by this SDK. The comment block also reports the runtime (`node/<version>`, `bun/<version>`, `deno/<version>`, or `browser`) plus the OS and architecture on non-browser runtimes.
@@ -485,7 +577,7 @@ const client = new B2Client({
   applicationKey,
   userAgent: 'my-app/1.0',
 })
-// → "my-app/1.0 b2-sdk-typescript/0.1.0 (typescript; @backblaze-labs/b2-sdk; node/24.14.1; linux; x64)"
+// → "my-app/1.0 b2-sdk-typescript/<version> (typescript; @backblaze-labs/b2-sdk; node/<node-version>; linux; x64)"
 ```
 
 ## SSRF guard
@@ -513,6 +605,10 @@ new B2Client({
 })
 ```
 
+Passing `allowedHostSuffixes: []` disables the guard entirely and should be reserved for trusted tests or controlled local harnesses. For custom realms, the SDK uses the hosts returned by `b2_authorize_account` as scoped suffixes, allowing those hosts and their subdomains without broadening unknown domains to public suffixes such as `co.uk`.
+
+The default transport follows same-origin `GET` / `HEAD` redirects after each target passes the SSRF guard. Cross-origin redirects and `POST` redirects are blocked with `B2RedirectError`. Pass `followSameOriginRedirects: false` to the `B2Client` constructor to block same-origin redirects as well.
+
 Passing a custom `transport` opts out of the guard (your transport, your threat model).
 
 ## Retry behavior
@@ -520,7 +616,7 @@ Passing a custom `transport` opts out of the guard (your transport, your threat
 The SDK automatically retries transient errors with exponential backoff:
 
 - **401 expired_auth_token**: re-authorizes and retries
-- **503, 408, 429**: exponential backoff with jitter, respects `Retry-After` header
+- **408, 429, transient 5xx (500, 502, 503, 504)**: exponential backoff with jitter, respects `Retry-After` header
 - **Network errors**: retried with backoff
 - **Permanent errors** (403 cap_exceeded, 404 not_found, etc.): thrown immediately
 
@@ -534,10 +630,21 @@ const client = new B2Client({
     maxRetries: 10,
     maxRetryDelayMs: 120_000,
     initialRetryDelayMs: 500,
+    requestTimeoutMs: 30 * 60_000,
   },
 })
 ```
 
+`requestTimeoutMs` covers request dispatch, upload POST bodies, and
+non-streaming response-body reads. For `response.body` download streams it is an
+idle/no-progress timeout that resets after each received chunk, so healthy large
+downloads are not aborted merely because the total transfer takes longer than
+the timeout. Slow large-part uploads may need a higher value or `0` to rely on
+your own `AbortSignal`. Worst-case terminal latency can be roughly
+`(retry.maxRetries + 1) * requestTimeoutMs` plus backoff when an endpoint hangs.
+
+When a multipart upload, streaming upload, or multipart copy fails, the SDK calls `b2_cancel_large_file` on a best-effort basis. Pass `onCleanupFailure` on those operations to observe failed cancellation or a skipped cancellation after an ambiguous `b2_finish_large_file` response, with the relevant `fileId` so operators can reconcile unfinished or possibly committed large files. Pair long-running resume workflows with lifecycle or version-retention cleanup so orphaned unfinished large files do not accumulate past the bounded resume discovery scan.
+
 ## Testing with the simulator
 
 The SDK ships an in-memory B2 simulator for unit testing without network access:
@@ -581,7 +688,7 @@ describe('my app', () => {
 
 ## Error handling
 
-All B2 API errors are thrown as typed `B2Error` subclasses (13 in total). Client-side capability checks throw `B2InsufficientCapabilityError`.
+All B2 API errors are thrown as typed `B2Error` subclasses (30 in total). Client-side capability checks throw `B2InsufficientCapabilityError`.
 
 ```ts
 import { BucketType } from '@backblaze-labs/b2-sdk'
@@ -611,7 +718,7 @@ try {
 
 The high-level surface (`B2Client`, `Bucket`, `B2Object`) gives you direct access to features that live in B2's native API:
 
-- **Per-part and whole-file SHA-1 verification** on multipart uploads.
+- **Per-part and whole-file SHA-1 verification** on multipart uploads, plus automatic whole-file verification on downloads when B2 provides a digest.
 - **`b2_copy_part` server-side multipart copy** via `bucket.copyLargeFile()` — no client-side bytes touched.
 - **File retention + legal hold** (object lock) on `bucket.updateFileRetention()` and `bucket.updateFileLegalHold()`.
 - **Time-scoped download tokens** via `bucket.getDownloadAuthorization()` for sharing without exposing the application key.
@@ -619,7 +726,11 @@ The high-level surface (`B2Client`, `Bucket`, `B2Object`) gives you direct acces
 - **Event notification rules** via `bucket.getNotificationRules()` and `bucket.setNotificationRules()`.
 - **Application key restrictions** (per-bucket, per-prefix, per-capability) via `client.createKey()`.
 
-When you want S3 compatibility instead — for tooling that already speaks S3, or for the Bandwidth Alliance proxy pattern — `@backblaze-labs/b2-sdk/s3` exposes `createS3ClientConfig()` and `presignGetObjectUrl()` so the same SDK covers both surfaces.
+When you want S3 compatibility instead — for tooling that already speaks S3, browser direct uploads, or for the Bandwidth Alliance proxy pattern — `@backblaze-labs/b2-sdk/s3` exposes `createS3ClientConfig()`, `presignS3GetObjectUrl()`, and `presignS3PutObjectUrl()` so the same SDK covers both surfaces.
+
+S3 presigned URLs are bearer credentials. The helpers only emit `https:` URLs and require an explicit `region` for custom or proxied endpoints whose region cannot be derived from `s3.<region>.backblazeb2.com`; set `region` and call `createS3ClientConfig()` during startup or deployment health checks before serving traffic. Object keys with path segments exactly `.` or `..` cannot be S3-presigned safely because common URL parsers normalize them before sending; rename those objects, proxy the download through a trusted server, or use a B2-native download authorization URL when that fits the access model. URL validity depends on the signing host's clock, so URL-generating hosts should be NTP-synced, and downstream SigV4 403s should include a clock-skew check. For untrusted uploads, bind `contentType` and `contentLength` when you can; omitting `contentType` lets the uploader store any B2-accepted type, including browser-executable HTML, SVG, XML, or JavaScript. Bound active content types are rejected unless trusted server code passes `trustedUnsafeS3PresignOptIn` to `allowBrowserExecutableContentType`; booleans from request JSON are ignored. GET response overrides that force inline rendering or active content require the same token on their unsafe opt-in fields. The SDK's active-content checks are best-effort denylists, not a complete browser security policy; the SDK cannot set `X-Content-Type-Options: nosniff`, so callers accepting untrusted content should enforce their own content-type allow-list. Presigned PUT URLs are replayable until expiry; if a client retries after B2 stored the object but before the response was observed, the retry can create another file version. Use unique object keys or reconcile by listed file IDs/checksums, and configure lifecycle or version cleanup where duplicate versions must be removed automatically.
+
+The deprecated `presignGetObjectUrl()` helper returns a B2-native download-authorization URL, not an S3 presigned URL. It keeps the legacy slash-escaped URL shape and permissive string-building behavior for compatibility. Use `createNativeDownloadAuthorizationUrl()` for new B2-native download-token URLs; it uses B2 path-preserving file-name encoding, requires an `https:` Backblaze download origin without userinfo, path, query, or fragment, rejects unsafe bucket names, control characters, invalid compatibility durations, and path-normalizing file names, and constructs the bearer URL from the parsed origin rather than raw-concatenating caller input.
 
 ## Source isomorphism
 
@@ -644,14 +755,14 @@ So you get both: an `npm install`-ready `dist/` (ESM + CJS + DTS), *and* a `src/
 
 | Runtime | Version | Status |
 |---|---|---|
-| Node.js | 22+ | Primary target. CI runs the full suite on Node 22 and 24 across Linux, Windows, and macOS. |
+| Node.js | 22.3+ | Primary target. CI runs the fast suite on Linux, Windows, and macOS for Node 22.18 + 24; slow and coverage jobs run on Linux. `FileSource` uses weaker size/mtime validation on Windows because portable dev/inode and ctime fields are unreliable there. |
 | Bun | latest | Tested in CI via `bun test src/` + example typecheck. |
 | Deno | 2.x | Source isomorphism verified in CI via `deno check` against `src/`. |
 | Browsers | Chromium, Firefox, WebKit (last 2 evergreen) | Tested in CI via Playwright. |
-| Cloudflare Workers | - | Supported. |
-| Vercel Edge | - | Supported. |
+| Cloudflare Workers | - | Compatible target when the standard Web APIs above are available; not yet smoke-tested in CI with a Workers runtime. |
+| Vercel Edge | - | Compatible target when the standard Web APIs above are available; not yet smoke-tested in CI with Vercel Edge. |
 
-Requires: `fetch`, Web Streams, `crypto.subtle`, `AbortSignal`. Node < 22 is not supported (Node 20 reached EOL April 2026).
+Requires: `fetch`, Web Streams, `crypto.subtle`, `AbortSignal`. Node < 22.3 is not supported (Node 20 reached EOL April 2026). `FileSource(path)` throws on older Node 22.x runtimes that lack synchronous `process.getBuiltinModule()`; `FileSource.fromPath(path)` remains the async construction path for supported Node filesystem platforms. On Windows, `FileSource` is supported with weaker size/mtime validation because portable dev/inode and ctime fields are unreliable there.
 
 The browser test suite (`pnpm test:browser`) runs the same source against real Chromium, Firefox, and WebKit instances. Only Node-specific tests (filename pattern `*.node.test.ts`, covering `node:fs`, `node:os`, `node:util.inspect`) are skipped.
 

package/dist/_virtual/_b2-sdk-version-json.cjs

@@ -0,0 +1,4 @@
+//#region \0b2-sdk-version-json
+var _b2_sdk_version_json_default = { "version": "0.2.0" };
+//#endregion
+exports.default = _b2_sdk_version_json_default;

package/dist/_virtual/_b2-sdk-version-json.js

@@ -0,0 +1,4 @@
+//#region \0b2-sdk-version-json
+var _b2_sdk_version_json_default = { "version": "0.2.0" };
+//#endregion
+export { _b2_sdk_version_json_default as default };

package/dist/auth/account-info.d.cts

@@ -7,12 +7,42 @@ export interface UploadUrlEntry {
     /** Authorization token to include with the upload request. */
     readonly authorizationToken: string;
 }
+/**
+ * Optional extension for persistent auth stores that need to bind cached auth
+ * to the current client configuration. `B2Client` calls these hooks during
+ * construction before it reuses any loaded auth.
+ */
+export interface AuthContextAwareAccountInfo {
+    /**
+     * Bind persistent auth caches to the resolved realm URL. Implementations that
+     * persist auth should discard loaded state written for a different realm.
+     */
+    setRealmUrl(realmUrl: string): void;
+    /**
+     * Bind persistent auth caches to the configured application key ID.
+     * Implementations that persist auth should discard loaded state written for a
+     * different key ID.
+     */
+    setApplicationKeyId(applicationKeyId: string): void;
+}
 /**
  * Stores B2 authorization state between requests.
  * Implementations cache the authorize-account response and manage
  * pools of reusable upload URLs (checkout/checkin/evict pattern).
  */
 export interface AccountInfo {
+    /**
+     * @deprecated Persistent auth stores should implement
+     * {@link AuthContextAwareAccountInfo}. This optional hook remains for
+     * source compatibility with older integrations.
+     */
+    setRealmUrl?(realmUrl: string): void;
+    /**
+     * @deprecated Persistent auth stores should implement
+     * {@link AuthContextAwareAccountInfo}. This optional hook remains for
+     * source compatibility with older integrations.
+     */
+    setApplicationKeyId?(applicationKeyId: string): void;
     /** Store a fresh authorization response, replacing any previous state. */
     setAuth(auth: AuthorizeAccountResponse): void;
     /** Return the current authorization response, or null if not authorized. */
@@ -35,6 +65,8 @@ export interface AccountInfo {
     getS3ApiUrl(): string;
     /** Bucket ID the key is restricted to, or null if unrestricted. */
     getAllowedBucketId(): BucketId | null;
+    /** Bucket IDs the key is restricted to, or null if unrestricted. */
+    getAllowedBucketIds(): readonly BucketId[] | null;
     /** Take an upload URL from the pool for the given bucket, or null if none available. */
     checkoutUploadUrl(bucketId: BucketId): UploadUrlEntry | null;
     /** Return a still-valid upload URL to the pool for reuse. */