@backblaze-labs/b2-sdk 0.1.0 → 0.3.0

package/dist/s3/index.d.cts

@@ -1,4 +1,28 @@
 import { AccountInfo } from '../auth/account-info.js';
+/**
+ * Trusted server-side token for intentionally allowing active-content S3 presign options.
+ *
+ * Plain objects and JSON payloads cannot satisfy the runtime identity check
+ * for this token. Pass this exported value only from trusted application code
+ * after applying your own content and response-header policy.
+ */
+export interface TrustedUnsafeS3PresignOptIn {
+    /**
+     * Internal marker used only by the runtime identity check.
+     *
+     * @internal
+     */
+    readonly __trustedUnsafeS3PresignOptIn: 'trustedUnsafeS3PresignOptIn';
+}
+/**
+ * Server-side opt-in token for unsafe S3 presign options.
+ *
+ * Use this token as the value for `allowBrowserExecutableContentType`,
+ * `allowBrowserExecutableResponseContentType`, or
+ * `allowInlineResponseContentDisposition` only when active content or inline
+ * rendering from the storage origin is intentional and trusted.
+ */
+export declare const trustedUnsafeS3PresignOptIn: TrustedUnsafeS3PresignOptIn;
 /**
  * Configuration for deriving S3-compatible client settings from B2 auth state.
  *
@@ -38,10 +62,126 @@ export interface S3ClientConfig {
     /** Always `true` for B2, which requires path-style bucket addressing. */
     readonly forcePathStyle: boolean;
 }
+/** Common options for S3-compatible presigned object URLs. */
+export interface S3PresignObjectUrlOptions extends B2S3Config {
+    /** Bucket containing the object. */
+    readonly bucketName: string;
+    /**
+     * Object key / B2 file name to sign. Keys with path segments exactly `.`
+     * or `..` cannot be presigned safely because common URL parsers normalize
+     * them before sending the request.
+     */
+    readonly fileName: string;
+    /**
+     * URL validity duration in seconds. Defaults to 3600. Must be an integer
+     * from 1 to 604800 (7 days), the AWS Signature Version 4 presign maximum.
+     * A presigned URL is a bearer credential for the signed operation; keep
+     * this as short as the calling workflow allows.
+     */
+    readonly expiresIn?: number;
+}
+/** Options for {@link presignS3GetObjectUrl}. */
+export interface PresignS3GetObjectUrlOptions extends S3PresignObjectUrlOptions {
+    /** Optional S3 version ID to include in the signed GET request. */
+    readonly versionId?: string;
+    /**
+     * Override the response Cache-Control header. Response overrides control
+     * headers served from the storage origin; do not populate them from
+     * untrusted input without an allow-list.
+     */
+    readonly responseCacheControl?: string;
+    /**
+     * Override the response Content-Disposition header. Prefer a safe
+     * attachment disposition when this value can be influenced by users. The
+     * helper rejects `inline` response dispositions by default because they can
+     * make stored bytes render from the storage origin.
+     */
+    readonly responseContentDisposition?: string;
+    /**
+     * Permit an `inline` response Content-Disposition override. Set only when
+     * the object bytes and response headers are trusted to render from the
+     * storage origin. Pass {@link trustedUnsafeS3PresignOptIn}; plain booleans
+     * from request JSON are intentionally ignored by the runtime guard.
+     */
+    readonly allowInlineResponseContentDisposition?: TrustedUnsafeS3PresignOptIn;
+    /**
+     * Override the response Content-Encoding header. Do not populate this from
+     * untrusted input without an allow-list.
+     */
+    readonly responseContentEncoding?: string;
+    /**
+     * Override the response Content-Language header. Do not populate this from
+     * untrusted input without an allow-list.
+     */
+    readonly responseContentLanguage?: string;
+    /**
+     * Override the response Content-Type header. If attacker-controlled, this
+     * can make stored bytes render as active content from the storage origin.
+     * Restrict it to known-safe values before signing. The helper's built-in
+     * rejection of known browser-executable and sniffable XML/JavaScript media
+     * types is best-effort and does not replace an application allow-list.
+     */
+    readonly responseContentType?: string;
+    /**
+     * Permit browser-executable `responseContentType` overrides such as
+     * `text/html`, JavaScript, SVG, or XML media types. Leave this unset unless
+     * the served object is intentionally meant to render active content from the
+     * storage origin. Pass {@link trustedUnsafeS3PresignOptIn}; plain booleans
+     * from request JSON are intentionally ignored by the runtime guard.
+     */
+    readonly allowBrowserExecutableResponseContentType?: TrustedUnsafeS3PresignOptIn;
+    /**
+     * Override the response Expires header. Do not populate this from
+     * untrusted input without an allow-list.
+     */
+    readonly responseExpires?: Date;
+}
+/** Options for {@link presignS3PutObjectUrl}. */
+export interface PresignS3PutObjectUrlOptions extends S3PresignObjectUrlOptions {
+    /**
+     * Optional content type for the uploaded object. When supplied, the generated
+     * URL signs the Content-Type header, so upload clients must send the same
+     * value. Browser-executable and sniffable XML/JavaScript types are rejected
+     * by default as a best-effort guard; callers accepting untrusted uploads
+     * should still enforce their own allow-list.
+     */
+    readonly contentType?: string;
+    /**
+     * Permit browser-executable `contentType` values such as `text/html`,
+     * JavaScript, SVG, or XML media types. Leave this unset unless the uploaded
+     * object is intentionally meant to render active content from the storage
+     * origin. Pass {@link trustedUnsafeS3PresignOptIn}; plain booleans from
+     * request JSON are intentionally ignored by the runtime guard.
+     */
+    readonly allowBrowserExecutableContentType?: TrustedUnsafeS3PresignOptIn;
+    /**
+     * Optional content length. Must be a non-negative safe integer. When
+     * supplied, the generated URL signs the Content-Length header, so upload
+     * clients must send the same value.
+     */
+    readonly contentLength?: number;
+    /**
+     * Optional user metadata to attach to the object. The generated URL signs
+     * matching `x-amz-meta-*` headers, so upload clients must send the same values.
+     * Pass bare metadata keys; the helper adds the `x-amz-meta-` prefix. Metadata
+     * keys must be valid HTTP header tokens and must not differ only by case.
+     */
+    readonly metadata?: Record<string, string>;
+}
+/**
+ * Options for {@link presignPutObjectUrl}.
+ *
+ * @deprecated Use {@link PresignS3PutObjectUrlOptions}.
+ */
+export type PresignPutObjectUrlOptions = PresignS3PutObjectUrlOptions;
 /**
  * Derives an S3-compatible client configuration from B2 authorization state.
  * Pass the result to `new S3Client(config)` from `@aws-sdk/client-s3`.
  *
+ * Non-standard, custom, or proxied endpoints require an explicit `region`; set
+ * it before deploying this SDK to those endpoints. The SDK no longer falls back
+ * to `us-west-004` because that can mis-sign requests.
+ *
  * @param config - B2 auth state, application key credentials, and optional region override.
  *
  * @returns Configuration ready for the AWS S3 SDK.
@@ -59,16 +199,104 @@ export interface S3ClientConfig {
  */
 export declare function createS3ClientConfig(config: B2S3Config): S3ClientConfig;
 /**
- * Constructs a presigned download URL using B2's native download authorization.
- * This is not a standard S3 presigned URL but works for B2 download endpoints.
+ * Extracts the B2 S3 region from a standard B2 S3 endpoint.
  *
- * @param downloadUrl - The B2 download URL from authorization (e.g., `https://f004.backblazeb2.com`).
+ * Custom endpoints cannot be inferred safely. Pass `region` explicitly to
+ * {@link createS3ClientConfig}, {@link presignS3GetObjectUrl}, or
+ * {@link presignS3PutObjectUrl} when this returns `null`.
+ *
+ * @param endpoint - The S3 endpoint URL.
+ *
+ * @returns The derived region, or `null` when the endpoint is not a standard B2 S3 URL.
+ */
+export declare function deriveS3RegionFromEndpoint(endpoint: string): string | null;
+/**
+ * Generates an AWS Signature Version 4 presigned GET URL for B2's S3-compatible API.
+ *
+ * This helper signs internally and does not pass the B2 application key to
+ * runtime peer dependencies. Response override options are signed into the URL
+ * and control headers served from the storage origin; do not populate them from
+ * untrusted input without an allow-list. Presign success does not prove the URL
+ * will be accepted later; keep URL-generating hosts clock-synchronized and
+ * check clock skew when downstream use returns SigV4 403 errors.
+ *
+ * @param options - B2 auth state, S3 credentials, target object, and signing options.
+ *
+ * @returns The presigned URL string.
+ */
+export declare function presignS3GetObjectUrl(options: PresignS3GetObjectUrlOptions): Promise<string>;
+/**
+ * Returns a B2-native download-authorization URL, not an S3 presigned URL.
+ *
+ * This deprecated helper preserves the legacy positional output contract where
+ * the whole file name is encoded as one URL component, including `/` as `%2F`.
+ * It keeps the legacy string-building contract for callers that relied on
+ * custom/local download URLs or permissive inputs. Use
+ * {@link createNativeDownloadAuthorizationUrl} for strict validation.
+ *
+ * @param downloadUrl - The B2 download URL from authorization.
  * @param bucketName - The bucket containing the file.
  * @param fileName - The file name (path) to download.
  * @param authorizationToken - A download authorization token from `b2_get_download_authorization`.
- * @param validDurationInSeconds - URL validity duration in seconds. Defaults to 3600 (1 hour).
+ * @param validDurationInSeconds - Compatibility-only value for the non-authoritative `expires` query.
  *
- * @returns The presigned download URL string.
+ * @returns The B2 native download-authorization URL string.
+ *
+ * @deprecated Use {@link createNativeDownloadAuthorizationUrl} for B2 native
+ * download-token URLs, or {@link presignS3GetObjectUrl} for real S3-compatible
+ * AWS Signature Version 4 presigned GET URLs.
  */
 export declare function presignGetObjectUrl(downloadUrl: string, bucketName: string, fileName: string, authorizationToken: string, validDurationInSeconds?: number): string;
+/**
+ * Generates an AWS Signature Version 4 presigned PUT URL for browser or
+ * third-party uploads through B2's S3-compatible API.
+ *
+ * This helper signs internally and does not pass the B2 application key to
+ * runtime peer dependencies. A presigned PUT URL is a replayable bearer
+ * credential for writing one key until expiry. Retried PUTs can create
+ * duplicate B2 file versions when a response is lost after B2 stored the object.
+ * Use unique keys or reconcile uploaded file IDs/checksums, and configure
+ * lifecycle/version cleanup where duplicate versions must be removed
+ * automatically. If `contentType` and `contentLength` are omitted, the holder
+ * can choose any content type, including browser-executable types, and any size
+ * accepted by B2; bind both values before handing URLs to untrusted uploaders
+ * to limit financial-DoS and content-type smuggling risk.
+ *
+ * @param options - B2 auth state, S3 credentials, target object, and signing options.
+ *
+ * @returns The presigned URL string.
+ */
+export declare function presignS3PutObjectUrl(options: PresignS3PutObjectUrlOptions): Promise<string>;
+/**
+ * Generates an AWS Signature Version 4 presigned PUT URL for B2's
+ * S3-compatible API.
+ *
+ * @param options - B2 auth state, S3 credentials, target object, and signing options.
+ *
+ * @returns The presigned URL string.
+ *
+ * @deprecated Use {@link presignS3PutObjectUrl}; this alias is retained for
+ * pre-release callers that adopted the shorter name.
+ */
+export declare function presignPutObjectUrl(options: PresignPutObjectUrlOptions): Promise<string>;
+/**
+ * Constructs a B2-native download URL using a token from `b2_get_download_authorization`.
+ * This is not an S3 presigned URL.
+ *
+ * The token lifetime is fixed when `b2_get_download_authorization` creates the
+ * token. `validDurationInSeconds` is retained only for compatibility with the
+ * legacy `presignGetObjectUrl` helper's decorative `expires` query parameter;
+ * changing it here does not shorten or extend access.
+ * Because the returned URL carries a bearer token, `downloadUrl` must be an
+ * HTTPS Backblaze download origin without userinfo, path, query, or fragment.
+ *
+ * @param downloadUrl - The B2 download URL from authorization (e.g., `https://f004.backblazeb2.com`).
+ * @param bucketName - The bucket containing the file.
+ * @param fileName - The file name (path) to download.
+ * @param authorizationToken - A download authorization token from `b2_get_download_authorization`.
+ * @param validDurationInSeconds - Compatibility-only value for the non-authoritative `expires` query.
+ *
+ * @returns The B2 native download-authorization URL string, not an S3 presigned URL.
+ */
+export declare function createNativeDownloadAuthorizationUrl(downloadUrl: string, bucketName: string, fileName: string, authorizationToken: string, validDurationInSeconds?: number): string;
 //# sourceMappingURL=index.d.ts.map

package/dist/s3/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/s3/index.js"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAE1D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU;IACzB,iEAAiE;IACjE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAA;IACjC,2DAA2D;IAC3D,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,qEAAqE;IACrE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,wFAAwF;AACxF,MAAM,WAAW,cAAc;IAC7B,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE;QACpB,+DAA+D;QAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;QAC5B,yEAAyE;QACzE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;KACjC,CAAA;IACD,yEAAyE;IACzE,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;CACjC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,GAAG,cAAc,CAcvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,kBAAkB,EAAE,MAAM,EAC1B,sBAAsB,SAAO,GAC5B,MAAM,CAGR"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/s3/index.js"],"names":[],"mappings":"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"}

package/dist/s3/index.d.ts

@@ -1,4 +1,28 @@
 import { AccountInfo } from '../auth/account-info.js';
+/**
+ * Trusted server-side token for intentionally allowing active-content S3 presign options.
+ *
+ * Plain objects and JSON payloads cannot satisfy the runtime identity check
+ * for this token. Pass this exported value only from trusted application code
+ * after applying your own content and response-header policy.
+ */
+export interface TrustedUnsafeS3PresignOptIn {
+    /**
+     * Internal marker used only by the runtime identity check.
+     *
+     * @internal
+     */
+    readonly __trustedUnsafeS3PresignOptIn: 'trustedUnsafeS3PresignOptIn';
+}
+/**
+ * Server-side opt-in token for unsafe S3 presign options.
+ *
+ * Use this token as the value for `allowBrowserExecutableContentType`,
+ * `allowBrowserExecutableResponseContentType`, or
+ * `allowInlineResponseContentDisposition` only when active content or inline
+ * rendering from the storage origin is intentional and trusted.
+ */
+export declare const trustedUnsafeS3PresignOptIn: TrustedUnsafeS3PresignOptIn;
 /**
  * Configuration for deriving S3-compatible client settings from B2 auth state.
  *
@@ -38,10 +62,126 @@ export interface S3ClientConfig {
     /** Always `true` for B2, which requires path-style bucket addressing. */
     readonly forcePathStyle: boolean;
 }
+/** Common options for S3-compatible presigned object URLs. */
+export interface S3PresignObjectUrlOptions extends B2S3Config {
+    /** Bucket containing the object. */
+    readonly bucketName: string;
+    /**
+     * Object key / B2 file name to sign. Keys with path segments exactly `.`
+     * or `..` cannot be presigned safely because common URL parsers normalize
+     * them before sending the request.
+     */
+    readonly fileName: string;
+    /**
+     * URL validity duration in seconds. Defaults to 3600. Must be an integer
+     * from 1 to 604800 (7 days), the AWS Signature Version 4 presign maximum.
+     * A presigned URL is a bearer credential for the signed operation; keep
+     * this as short as the calling workflow allows.
+     */
+    readonly expiresIn?: number;
+}
+/** Options for {@link presignS3GetObjectUrl}. */
+export interface PresignS3GetObjectUrlOptions extends S3PresignObjectUrlOptions {
+    /** Optional S3 version ID to include in the signed GET request. */
+    readonly versionId?: string;
+    /**
+     * Override the response Cache-Control header. Response overrides control
+     * headers served from the storage origin; do not populate them from
+     * untrusted input without an allow-list.
+     */
+    readonly responseCacheControl?: string;
+    /**
+     * Override the response Content-Disposition header. Prefer a safe
+     * attachment disposition when this value can be influenced by users. The
+     * helper rejects `inline` response dispositions by default because they can
+     * make stored bytes render from the storage origin.
+     */
+    readonly responseContentDisposition?: string;
+    /**
+     * Permit an `inline` response Content-Disposition override. Set only when
+     * the object bytes and response headers are trusted to render from the
+     * storage origin. Pass {@link trustedUnsafeS3PresignOptIn}; plain booleans
+     * from request JSON are intentionally ignored by the runtime guard.
+     */
+    readonly allowInlineResponseContentDisposition?: TrustedUnsafeS3PresignOptIn;
+    /**
+     * Override the response Content-Encoding header. Do not populate this from
+     * untrusted input without an allow-list.
+     */
+    readonly responseContentEncoding?: string;
+    /**
+     * Override the response Content-Language header. Do not populate this from
+     * untrusted input without an allow-list.
+     */
+    readonly responseContentLanguage?: string;
+    /**
+     * Override the response Content-Type header. If attacker-controlled, this
+     * can make stored bytes render as active content from the storage origin.
+     * Restrict it to known-safe values before signing. The helper's built-in
+     * rejection of known browser-executable and sniffable XML/JavaScript media
+     * types is best-effort and does not replace an application allow-list.
+     */
+    readonly responseContentType?: string;
+    /**
+     * Permit browser-executable `responseContentType` overrides such as
+     * `text/html`, JavaScript, SVG, or XML media types. Leave this unset unless
+     * the served object is intentionally meant to render active content from the
+     * storage origin. Pass {@link trustedUnsafeS3PresignOptIn}; plain booleans
+     * from request JSON are intentionally ignored by the runtime guard.
+     */
+    readonly allowBrowserExecutableResponseContentType?: TrustedUnsafeS3PresignOptIn;
+    /**
+     * Override the response Expires header. Do not populate this from
+     * untrusted input without an allow-list.
+     */
+    readonly responseExpires?: Date;
+}
+/** Options for {@link presignS3PutObjectUrl}. */
+export interface PresignS3PutObjectUrlOptions extends S3PresignObjectUrlOptions {
+    /**
+     * Optional content type for the uploaded object. When supplied, the generated
+     * URL signs the Content-Type header, so upload clients must send the same
+     * value. Browser-executable and sniffable XML/JavaScript types are rejected
+     * by default as a best-effort guard; callers accepting untrusted uploads
+     * should still enforce their own allow-list.
+     */
+    readonly contentType?: string;
+    /**
+     * Permit browser-executable `contentType` values such as `text/html`,
+     * JavaScript, SVG, or XML media types. Leave this unset unless the uploaded
+     * object is intentionally meant to render active content from the storage
+     * origin. Pass {@link trustedUnsafeS3PresignOptIn}; plain booleans from
+     * request JSON are intentionally ignored by the runtime guard.
+     */
+    readonly allowBrowserExecutableContentType?: TrustedUnsafeS3PresignOptIn;
+    /**
+     * Optional content length. Must be a non-negative safe integer. When
+     * supplied, the generated URL signs the Content-Length header, so upload
+     * clients must send the same value.
+     */
+    readonly contentLength?: number;
+    /**
+     * Optional user metadata to attach to the object. The generated URL signs
+     * matching `x-amz-meta-*` headers, so upload clients must send the same values.
+     * Pass bare metadata keys; the helper adds the `x-amz-meta-` prefix. Metadata
+     * keys must be valid HTTP header tokens and must not differ only by case.
+     */
+    readonly metadata?: Record<string, string>;
+}
+/**
+ * Options for {@link presignPutObjectUrl}.
+ *
+ * @deprecated Use {@link PresignS3PutObjectUrlOptions}.
+ */
+export type PresignPutObjectUrlOptions = PresignS3PutObjectUrlOptions;
 /**
  * Derives an S3-compatible client configuration from B2 authorization state.
  * Pass the result to `new S3Client(config)` from `@aws-sdk/client-s3`.
  *
+ * Non-standard, custom, or proxied endpoints require an explicit `region`; set
+ * it before deploying this SDK to those endpoints. The SDK no longer falls back
+ * to `us-west-004` because that can mis-sign requests.
+ *
  * @param config - B2 auth state, application key credentials, and optional region override.
  *
  * @returns Configuration ready for the AWS S3 SDK.
@@ -59,16 +199,104 @@ export interface S3ClientConfig {
  */
 export declare function createS3ClientConfig(config: B2S3Config): S3ClientConfig;
 /**
- * Constructs a presigned download URL using B2's native download authorization.
- * This is not a standard S3 presigned URL but works for B2 download endpoints.
+ * Extracts the B2 S3 region from a standard B2 S3 endpoint.
  *
- * @param downloadUrl - The B2 download URL from authorization (e.g., `https://f004.backblazeb2.com`).
+ * Custom endpoints cannot be inferred safely. Pass `region` explicitly to
+ * {@link createS3ClientConfig}, {@link presignS3GetObjectUrl}, or
+ * {@link presignS3PutObjectUrl} when this returns `null`.
+ *
+ * @param endpoint - The S3 endpoint URL.
+ *
+ * @returns The derived region, or `null` when the endpoint is not a standard B2 S3 URL.
+ */
+export declare function deriveS3RegionFromEndpoint(endpoint: string): string | null;
+/**
+ * Generates an AWS Signature Version 4 presigned GET URL for B2's S3-compatible API.
+ *
+ * This helper signs internally and does not pass the B2 application key to
+ * runtime peer dependencies. Response override options are signed into the URL
+ * and control headers served from the storage origin; do not populate them from
+ * untrusted input without an allow-list. Presign success does not prove the URL
+ * will be accepted later; keep URL-generating hosts clock-synchronized and
+ * check clock skew when downstream use returns SigV4 403 errors.
+ *
+ * @param options - B2 auth state, S3 credentials, target object, and signing options.
+ *
+ * @returns The presigned URL string.
+ */
+export declare function presignS3GetObjectUrl(options: PresignS3GetObjectUrlOptions): Promise<string>;
+/**
+ * Returns a B2-native download-authorization URL, not an S3 presigned URL.
+ *
+ * This deprecated helper preserves the legacy positional output contract where
+ * the whole file name is encoded as one URL component, including `/` as `%2F`.
+ * It keeps the legacy string-building contract for callers that relied on
+ * custom/local download URLs or permissive inputs. Use
+ * {@link createNativeDownloadAuthorizationUrl} for strict validation.
+ *
+ * @param downloadUrl - The B2 download URL from authorization.
  * @param bucketName - The bucket containing the file.
  * @param fileName - The file name (path) to download.
  * @param authorizationToken - A download authorization token from `b2_get_download_authorization`.
- * @param validDurationInSeconds - URL validity duration in seconds. Defaults to 3600 (1 hour).
+ * @param validDurationInSeconds - Compatibility-only value for the non-authoritative `expires` query.
  *
- * @returns The presigned download URL string.
+ * @returns The B2 native download-authorization URL string.
+ *
+ * @deprecated Use {@link createNativeDownloadAuthorizationUrl} for B2 native
+ * download-token URLs, or {@link presignS3GetObjectUrl} for real S3-compatible
+ * AWS Signature Version 4 presigned GET URLs.
  */
 export declare function presignGetObjectUrl(downloadUrl: string, bucketName: string, fileName: string, authorizationToken: string, validDurationInSeconds?: number): string;
+/**
+ * Generates an AWS Signature Version 4 presigned PUT URL for browser or
+ * third-party uploads through B2's S3-compatible API.
+ *
+ * This helper signs internally and does not pass the B2 application key to
+ * runtime peer dependencies. A presigned PUT URL is a replayable bearer
+ * credential for writing one key until expiry. Retried PUTs can create
+ * duplicate B2 file versions when a response is lost after B2 stored the object.
+ * Use unique keys or reconcile uploaded file IDs/checksums, and configure
+ * lifecycle/version cleanup where duplicate versions must be removed
+ * automatically. If `contentType` and `contentLength` are omitted, the holder
+ * can choose any content type, including browser-executable types, and any size
+ * accepted by B2; bind both values before handing URLs to untrusted uploaders
+ * to limit financial-DoS and content-type smuggling risk.
+ *
+ * @param options - B2 auth state, S3 credentials, target object, and signing options.
+ *
+ * @returns The presigned URL string.
+ */
+export declare function presignS3PutObjectUrl(options: PresignS3PutObjectUrlOptions): Promise<string>;
+/**
+ * Generates an AWS Signature Version 4 presigned PUT URL for B2's
+ * S3-compatible API.
+ *
+ * @param options - B2 auth state, S3 credentials, target object, and signing options.
+ *
+ * @returns The presigned URL string.
+ *
+ * @deprecated Use {@link presignS3PutObjectUrl}; this alias is retained for
+ * pre-release callers that adopted the shorter name.
+ */
+export declare function presignPutObjectUrl(options: PresignPutObjectUrlOptions): Promise<string>;
+/**
+ * Constructs a B2-native download URL using a token from `b2_get_download_authorization`.
+ * This is not an S3 presigned URL.
+ *
+ * The token lifetime is fixed when `b2_get_download_authorization` creates the
+ * token. `validDurationInSeconds` is retained only for compatibility with the
+ * legacy `presignGetObjectUrl` helper's decorative `expires` query parameter;
+ * changing it here does not shorten or extend access.
+ * Because the returned URL carries a bearer token, `downloadUrl` must be an
+ * HTTPS Backblaze download origin without userinfo, path, query, or fragment.
+ *
+ * @param downloadUrl - The B2 download URL from authorization (e.g., `https://f004.backblazeb2.com`).
+ * @param bucketName - The bucket containing the file.
+ * @param fileName - The file name (path) to download.
+ * @param authorizationToken - A download authorization token from `b2_get_download_authorization`.
+ * @param validDurationInSeconds - Compatibility-only value for the non-authoritative `expires` query.
+ *
+ * @returns The B2 native download-authorization URL string, not an S3 presigned URL.
+ */
+export declare function createNativeDownloadAuthorizationUrl(downloadUrl: string, bucketName: string, fileName: string, authorizationToken: string, validDurationInSeconds?: number): string;
 //# sourceMappingURL=index.d.ts.map

package/dist/s3/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/s3/index.js"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAE1D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU;IACzB,iEAAiE;IACjE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAA;IACjC,2DAA2D;IAC3D,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,qEAAqE;IACrE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,wFAAwF;AACxF,MAAM,WAAW,cAAc;IAC7B,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE;QACpB,+DAA+D;QAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;QAC5B,yEAAyE;QACzE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;KACjC,CAAA;IACD,yEAAyE;IACzE,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;CACjC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,GAAG,cAAc,CAcvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,kBAAkB,EAAE,MAAM,EAC1B,sBAAsB,SAAO,GAC5B,MAAM,CAGR"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/s3/index.js"],"names":[],"mappings":"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"}