@backblaze-labs/b2-sdk 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,150 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-08-18
+
+### Added
+
+- **Download response headers.** `DownloadHeaders` now exposes optional `contentDisposition`, `contentLanguage`, `contentEncoding`, `cacheControl`, `expires`, `contentRange`, `serverSideEncryption`, readable `fileRetention`/`legalHold`, typed `clientUnauthorizedToRead`, and `headerParseIssues`; new `DownloadHeaderName`, `DownloadClientUnauthorizedToReadMarker`, `DownloadServerSideEncryption`, and `SseCDownloadSetting` exports document the added surface.
+- **Large-file part metadata.** Raw large-file response types now expose documented v4 metadata fields: `contentMd5` on `UploadPartResponse` and `PartInfo`, `serverSideEncryption` and `uploadTimestamp` on `CopyPartResponse`, `serverSideEncryption` on `PartInfo`, and `replicationStatus` on unfinished large-file metadata via the exported `ReplicationStatus` alias.
+- **Custom upload timestamps.** Upload options now accept numeric `customUploadTimestamp` values to override B2's `uploadTimestamp`, distinct from `lastModifiedMillis` source metadata. Raw `b2_upload_file` headers serialize the value as `X-Bz-Custom-Upload-Timestamp`; raw `StartLargeFileRequest` accepts B2's documented decimal string/null body shape. Multipart uploads now also persist `lastModifiedMillis` as `src_last_modified_millis`, matching the small-file path; this metadata is included in multipart resume identity and older unfinished uploads that lack it can report `file-info-mismatch`. Custom timestamps require B2 account enablement, and resume diagnostics can report `upload-timestamp-mismatch` for incompatible unfinished large files.
+- **Bucket lifecycle-rule capabilities.** `Capability` now exports `ReadBucketLifecycleRules` and `WriteBucketLifecycleRules`.
+- **Partner authorize runtime surface.** New `@backblaze-labs/b2-sdk/partner` subpath exports `PartnerRawClient.authorizePartner()`, `PartnerAccountInfo`, and `InMemoryPartnerAccountInfo` for Master Application Key authorization against the Partner and Computer Backup suites.
+- **Partner API runtime bindings.** `PartnerRawClient` now includes `createGroupMember()`, `ejectGroupMember()`, `listGroups()`, `listGroupMembers()`, and `reserveTrialCreateAccount()` bindings for Partner API group management and B2 Reserve trial-account creation.
+- **High-level Partner facade.** The `@backblaze-labs/b2-sdk/partner` subpath now exports the experimental `PartnerClient` facade plus `PartnerClientOptions`, `PartnerAuthorizeOptions`, `ListGroupsOptions`, `PaginateGroupsOptions`, `ListGroupMembersOptions`, `PaginateGroupMembersOptions`, `CreateGroupMemberOptions`, `EjectGroupMemberOptions`, and `ReserveTrialAccountsOptions` for ergonomic Partner group/member pagination and B2 Reserve trial-account workflows.
+- **Computer Backup runtime facade.** The new `@backblaze-labs/b2-sdk/backup` subpath exports experimental `BackupClient` and `BackupRawClient` bindings for Partner-authorized Computer Backup listing, pagination, and delete workflows.
+- **Partner API and Computer Backup typed error subclasses.** New exported `TooManyMembersError`, `InvalidGroupIdError`, `InvalidEmailError`, `InvalidRegionError`, `InvalidSmsPhoneError`, `MethodFailureError`, `InvalidMemberAccountIdError`, `InvalidAccountIdError`, and `InvalidComputerIdError` classify Partner API and Computer Backup error codes; Partner 401 overload codes map to non-auth subclasses so they do not trigger reauth. Compatibility aliases preserve the issue-specified `TooManyGroupMembersError`, `MissingSmsPhoneError`, and `GroupMemberCreationFailedError` names.
+- **Partner API and Computer Backup type layer.** Public exports now include Partner API and Computer Backup request/response types, branded `groupId()` / `computerId()` factories, `PartnerCapability`, and `Region`. The response types document each Partner and Backup endpoint's wire shape (array-shaped or single-object per the API docs) and preserve numeric-looking group IDs and B2 statistics counts as strings. Endpoint types still awaiting runtime methods are marked experimental until those methods are implemented and exercised.
+
+### Changed
+
+- **Computer Backup facade validates list pages.** `BackupRawClient.listComputers()` returns the documented single-object `bz_list_computers` wire response, and `BackupClient.listComputers()` validates that page object and returns its `computers` and `nextComputerId`, rejecting malformed wire shapes before pagination can silently truncate results.
+- **Partner auth cache validation is non-destructive during construction.** `PartnerClient` and `BackupClient` ignore unsafe cached Partner authorization locally until `authorize()` replaces it, instead of clearing a shared `PartnerAccountInfo` store from a client constructor.
+- **Partner authorize JSON serialization redacts tokens.** BREAKING: `JSON.stringify()` of `PartnerRawClient.authorizePartner()`, `PartnerClient.authorize()`, and `PartnerAccountInfo.getAuth()` responses now emits `[redacted Partner token]` instead of round-tripping `authorizationToken`. Trusted durable auth caches should stringify `partnerAuthorizeResponseForPersistence(auth)` only for encrypted or otherwise credential-grade storage, or store `authorizationToken` directly in secure storage before rehydrating with `setAuth()`. Rehydrating the redacted placeholder now fails fast instead of sending it as a Partner API bearer token.
+- **Replication status metadata matches B2's wire shape.** BREAKING: `ReplicationStatus` values changed from lowercase (`'pending' | 'completed' | 'failed' | 'replica' | null`) to B2's documented uppercase values (`'PENDING' | 'COMPLETED' | 'FAILED' | 'REPLICA'`), and `FileVersion.replicationStatus`, `StartLargeFileResponse.replicationStatus`, and `UnfinishedLargeFile.replicationStatus` are now omitted instead of `null` when the file is not covered by a replication rule. Callers switching on lowercase literals or `null` must update those comparisons.
+- **Event notification rule target type narrowed.** `EventNotificationRule.targetConfiguration.targetType` is now the string literal `'webhook'` instead of `string` (the only value B2 accepts, corrected from the earlier `'url'` documentation placeholder), and the rule configuration gained an optional `maxEventsPerBatch` field. Code that annotated `targetType` as an arbitrary `string` may need a cast (#123).
+
+### Fixed
+
+- **Unfinished large-file SHA-1 sentinel normalized.** `startLargeFile` and `listUnfinishedLargeFiles` now collapse B2's `contentSha1: 'none'` wire sentinel to `null`, matching finished and file-list endpoints; the optional `UnfinishedLargeFileMetadata.contentSha1` type is widened to `string | null`.
+- **SHA-1 reader aborts classify as `AbortError`.** Pending stream reads aborted without an explicit reason now reject with an `AbortError` DOMException, and abort classification is centralized so abort-aware sync and upload-finish paths handle those cancellations consistently. Closes #208.
+- **SSE-C keys serialized into JSON request bodies.** `copyFile`, `copyPart`, and `startLargeFile` now serialize customer-managed SSE-C key material into the `b2_copy_file` / `b2_copy_part` / `b2_start_large_file` JSON request bodies instead of the redacting `EncryptionKey` wrapper, which previously emitted the `[redacted SSE-C key]` placeholder and produced a `403` on server-side copy and large-file start with SSE-C. Header-based upload and download paths were unaffected. Closes #206.
+- **B2 endpoint URL path hardening.** `b2Url()` now rejects literal and percent-encoded backslashes in prefix, version, and endpoint path components so WHATWG URL normalization cannot smuggle an endpoint into another path segment.
+- **Real-B2 integration evidence is explicit and diagnosable.** Same-repo integration workflow runs now fail when required B2 secrets are missing instead of silently accepting an all-skipped suite, integration setup logs per-step timings and timeout failures for authorization, bucket listing, stale cleanup, and bucket creation, and contributor/release docs now spell out simulator-vs-live-B2 expectations.
+- **B2Simulator upload write-path fidelity.** Simulator uploads now reject Content-Length/body mismatches, reject upload_part and copy_part part numbers outside B2's 1-10000 range, classify copy_part malformed ranges as 400 and unsatisfiable ranges as 416, verify large-file finish part SHA-1 entries, and report stored monotonic part timestamps from list_parts. Closes #21.
+- **B2Simulator SSE-C fidelity.** Simulator uploads, large-file parts, downloads, copyFile, and copyPart now validate SSE-C customer-key headers more closely to B2, preserve destination encryption semantics, and keep customer keys out of public response metadata.
+- **B2Simulator bucket-deletion fidelity.** `b2_delete_bucket` now rejects buckets that still contain file versions or unfinished large files with `400 cannot_delete_non_empty_bucket`, matching real B2.
+- **B2Simulator bucket-configuration fidelity.** `b2_create_bucket` and `b2_update_bucket` now validate CORS, lifecycle, replication, and default retention rule shapes; `b2_list_buckets` honors the `bucketName`, `bucketId`, and `bucketTypes` filters; and `b2_update_bucket` enforces `ifRevisionIs` with a `409 conflict`. Closes #22.
+- **B2Simulator create_key validation.** `b2_create_key` now rejects unknown or empty capabilities and out-of-range key names, and rejects capabilities that exceed the creating key's grant, matching real B2. Closes #18.
+- **B2Simulator authorize grant fidelity.** `b2_authorize_account` now derives the response `allowed` capabilities and bucket/name-prefix scope from the authorizing key instead of always returning the full master grant, so a restricted key reports its real scope. Closes #19.
+- **B2Simulator object-lock update fidelity.** `b2_update_file_retention` and `b2_update_file_legal_hold` now enforce retention and legal-hold update rules, governance-bypass requirements, and retention-clock validation, matching real B2. Closes #122.
+- **B2Simulator download authorization fidelity.** `b2_get_download_authorization` tokens are now enforced on download: bucket/prefix scope validation, header normalization, and by-id download-auth source restriction. Closes #121.
+- **B2Simulator notification-rule validation.** `b2_set_bucket_notification_rules` now validates event-notification rule shapes before accepting them. Closes #123.
+
+## [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 +166,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 +185,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 +261,7 @@ 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]: git+https://github.com/backblaze-labs/b2-sdk-typescript/compare/v0.3.0...HEAD
+[0.3.0]: git+https://github.com/backblaze-labs/b2-sdk-typescript/compare/v0.2.0...v0.3.0
+[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