@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/dist/s3/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":["../../src/s3/index.ts"],"sourcesContent":["/**\n * S3-compatible helpers for using B2 with the AWS SDK.\n *\n * Provides {@link createS3ClientConfig} to derive endpoint, region, and\n * credentials from B2 authorization state, plus {@link presignGetObjectUrl}\n * for generating download URLs using B2 native download authorization.\n *\n * @packageDocumentation\n */\n\nimport type { AccountInfo } from '../auth/account-info.ts'\n\n/**\n * Configuration for deriving S3-compatible client settings from B2 auth state.\n *\n * Per B2's S3-compatible API contract, the S3 `accessKeyId` is the\n * `applicationKeyId` and the S3 `secretAccessKey` is the\n * `applicationKey`. These are NOT the native `accountId` /\n * `authorizationToken` returned by `b2_authorize_account` — those won't\n * authenticate against the S3 endpoint. Both must be supplied here\n * because `AccountInfo` doesn't retain the application key after\n * authorization for security reasons.\n *\n * @see https://www.backblaze.com/apidocs/s3-compatible-api\n */\nexport interface B2S3Config {\n  /** The authorized AccountInfo containing the S3 endpoint URL. */\n  readonly accountInfo: AccountInfo\n  /** B2 application key ID. Used as the S3 `accessKeyId`. */\n  readonly applicationKeyId: string\n  /** B2 application key (secret). Used as the S3 `secretAccessKey`. */\n  readonly applicationKey: string\n  /** Override the S3 region. If omitted, extracted from the S3 API URL. */\n  readonly region?: string\n}\n\n/** Configuration object compatible with `@aws-sdk/client-s3`'s S3Client constructor. */\nexport interface S3ClientConfig {\n  /** The S3-compatible endpoint URL (e.g., `https://s3.us-west-004.backblazeb2.com`). */\n  readonly endpoint: string\n  /** The S3 region identifier (e.g., `us-west-004`). */\n  readonly region: string\n  /** AWS-style credentials — the B2 application key pair. */\n  readonly credentials: {\n    /** The B2 application key ID, used as the S3 access key ID. */\n    readonly accessKeyId: string\n    /** The B2 application key (secret), used as the S3 secret access key. */\n    readonly secretAccessKey: string\n  }\n  /** Always `true` for B2, which requires path-style bucket addressing. */\n  readonly forcePathStyle: boolean\n}\n\n/**\n * Derives an S3-compatible client configuration from B2 authorization state.\n * Pass the result to `new S3Client(config)` from `@aws-sdk/client-s3`.\n *\n * @param config - B2 auth state, application key credentials, and optional region override.\n *\n * @returns Configuration ready for the AWS S3 SDK.\n *\n * @example\n * ```ts\n * const { B2_APPLICATION_KEY_ID, B2_APPLICATION_KEY } = process.env\n * if (!B2_APPLICATION_KEY_ID || !B2_APPLICATION_KEY) throw new Error('Missing B2 credentials')\n * const s3 = new S3Client(createS3ClientConfig({\n *   accountInfo: client.accountInfo,\n *   applicationKeyId: B2_APPLICATION_KEY_ID,\n *   applicationKey: B2_APPLICATION_KEY,\n * }))\n * ```\n */\nexport function createS3ClientConfig(config: B2S3Config): S3ClientConfig {\n  const s3Url = config.accountInfo.getS3ApiUrl()\n  const regionMatch = s3Url.match(/s3\\.([^.]+)\\.backblazeb2\\.com/)\n  const region = config.region ?? regionMatch?.[1] ?? 'us-west-004'\n\n  return {\n    endpoint: s3Url,\n    region,\n    credentials: {\n      accessKeyId: config.applicationKeyId,\n      secretAccessKey: config.applicationKey,\n    },\n    forcePathStyle: true,\n  }\n}\n\n/**\n * Constructs a presigned download URL using B2's native download authorization.\n * This is not a standard S3 presigned URL but works for B2 download endpoints.\n *\n * @param downloadUrl - The B2 download URL from authorization (e.g., `https://f004.backblazeb2.com`).\n * @param bucketName - The bucket containing the file.\n * @param fileName - The file name (path) to download.\n * @param authorizationToken - A download authorization token from `b2_get_download_authorization`.\n * @param validDurationInSeconds - URL validity duration in seconds. Defaults to 3600 (1 hour).\n *\n * @returns The presigned download URL string.\n */\nexport function presignGetObjectUrl(\n  downloadUrl: string,\n  bucketName: string,\n  fileName: string,\n  authorizationToken: string,\n  validDurationInSeconds = 3600,\n): string {\n  const expires = Math.floor(Date.now() / 1000) + validDurationInSeconds\n  return `${downloadUrl}/file/${encodeURIComponent(bucketName)}/${encodeURIComponent(fileName)}?Authorization=${encodeURIComponent(authorizationToken)}&expires=${expires}`\n}\n"],"names":[],"mappings":";;AAwEO,SAAS,qBAAqB,QAAoC;AACvE,QAAM,QAAQ,OAAO,YAAY,YAAA;AACjC,QAAM,cAAc,MAAM,MAAM,+BAA+B;AAC/D,QAAM,SAAS,OAAO,UAAU,cAAc,CAAC,KAAK;AAEpD,SAAO;AAAA,IACL,UAAU;AAAA,IACV;AAAA,IACA,aAAa;AAAA,MACX,aAAa,OAAO;AAAA,MACpB,iBAAiB,OAAO;AAAA,IAAA;AAAA,IAE1B,gBAAgB;AAAA,EAAA;AAEpB;AAcO,SAAS,oBACd,aACA,YACA,UACA,oBACA,yBAAyB,MACjB;AACR,QAAM,UAAU,KAAK,MAAM,KAAK,IAAA,IAAQ,GAAI,IAAI;AAChD,SAAO,GAAG,WAAW,SAAS,mBAAmB,UAAU,CAAC,IAAI,mBAAmB,QAAQ,CAAC,kBAAkB,mBAAmB,kBAAkB,CAAC,YAAY,OAAO;AACzK;;;"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../../src/s3/index.ts"],"sourcesContent":["/**\n * S3-compatible helpers for using B2 with the AWS SDK and S3 clients.\n *\n * Provides {@link createS3ClientConfig} to derive endpoint, region, and\n * credentials from B2 authorization state, plus {@link presignS3GetObjectUrl}\n * and {@link presignS3PutObjectUrl} for generating AWS Signature Version 4\n * presigned URLs against B2's S3-compatible API.\n *\n * @packageDocumentation\n */\n\nimport type { AccountInfo } from '../auth/account-info.ts'\nimport { hostMatchesAllowedSuffix } from '../http/url-guard.ts'\nimport { redactUrlForError } from '../internal/url-redaction.ts'\nimport { encodeFileName } from '../raw/encoding.ts'\nimport { hasHttpHeaderControlCharacter } from '../util/http.ts'\nimport {\n  presignS3Request,\n  type QueryParam,\n  type SignedHeader,\n  type SigV4PresignRequestOptions,\n} from './sigv4.ts'\nimport { assertNativeDownloadFileName, assertSafeBucketName } from './validation.ts'\n\nconst HTTP_HEADER_TOKEN = /^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$/\nconst HTTP_MEDIA_TYPE = /^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+\\/[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$/\nconst DEFAULT_NATIVE_DOWNLOAD_URL_EXPIRES_IN = 3600\nconst TRUSTED_NATIVE_DOWNLOAD_HOST_SUFFIXES = [\n  'backblazeb2.com',\n  'backblaze.com',\n  'backblaze.net',\n  'b2-staging.io',\n] as const\nconst BROWSER_EXECUTABLE_CONTENT_TYPES = new Set([\n  'text/html',\n  'application/xhtml+xml',\n  'image/svg+xml',\n  'application/javascript',\n  'text/javascript',\n  'application/x-javascript',\n  'text/x-javascript',\n  'application/ecmascript',\n  'text/ecmascript',\n  'application/x-ecmascript',\n  'text/x-ecmascript',\n  'text/xml',\n  'application/xml',\n])\n\n/**\n * Trusted server-side token for intentionally allowing active-content S3 presign options.\n *\n * Plain objects and JSON payloads cannot satisfy the runtime identity check\n * for this token. Pass this exported value only from trusted application code\n * after applying your own content and response-header policy.\n */\nexport interface TrustedUnsafeS3PresignOptIn {\n  /**\n   * Internal marker used only by the runtime identity check.\n   *\n   * @internal\n   */\n  readonly __trustedUnsafeS3PresignOptIn: 'trustedUnsafeS3PresignOptIn'\n}\n\nconst trustedUnsafeS3PresignOptInValue: TrustedUnsafeS3PresignOptIn = Object.freeze({\n  __trustedUnsafeS3PresignOptIn: 'trustedUnsafeS3PresignOptIn',\n})\n\n/**\n * Server-side opt-in token for unsafe S3 presign options.\n *\n * Use this token as the value for `allowBrowserExecutableContentType`,\n * `allowBrowserExecutableResponseContentType`, or\n * `allowInlineResponseContentDisposition` only when active content or inline\n * rendering from the storage origin is intentional and trusted.\n */\nexport const trustedUnsafeS3PresignOptIn: TrustedUnsafeS3PresignOptIn =\n  trustedUnsafeS3PresignOptInValue\n\n/**\n * Configuration for deriving S3-compatible client settings from B2 auth state.\n *\n * Per B2's S3-compatible API contract, the S3 `accessKeyId` is the\n * `applicationKeyId` and the S3 `secretAccessKey` is the\n * `applicationKey`. These are NOT the native `accountId` /\n * `authorizationToken` returned by `b2_authorize_account` — those won't\n * authenticate against the S3 endpoint. Both must be supplied here\n * because `AccountInfo` doesn't retain the application key after\n * authorization for security reasons.\n *\n * @see https://www.backblaze.com/apidocs/s3-compatible-api\n */\nexport interface B2S3Config {\n  /** The authorized AccountInfo containing the S3 endpoint URL. */\n  readonly accountInfo: AccountInfo\n  /** B2 application key ID. Used as the S3 `accessKeyId`. */\n  readonly applicationKeyId: string\n  /** B2 application key (secret). Used as the S3 `secretAccessKey`. */\n  readonly applicationKey: string\n  /** Override the S3 region. If omitted, extracted from the S3 API URL. */\n  readonly region?: string\n}\n\n/** Configuration object compatible with `@aws-sdk/client-s3`'s S3Client constructor. */\nexport interface S3ClientConfig {\n  /** The S3-compatible endpoint URL (e.g., `https://s3.us-west-004.backblazeb2.com`). */\n  readonly endpoint: string\n  /** The S3 region identifier (e.g., `us-west-004`). */\n  readonly region: string\n  /** AWS-style credentials — the B2 application key pair. */\n  readonly credentials: {\n    /** The B2 application key ID, used as the S3 access key ID. */\n    readonly accessKeyId: string\n    /** The B2 application key (secret), used as the S3 secret access key. */\n    readonly secretAccessKey: string\n  }\n  /** Always `true` for B2, which requires path-style bucket addressing. */\n  readonly forcePathStyle: boolean\n}\n\n/** Common options for S3-compatible presigned object URLs. */\nexport interface S3PresignObjectUrlOptions extends B2S3Config {\n  /** Bucket containing the object. */\n  readonly bucketName: string\n  /**\n   * Object key / B2 file name to sign. Keys with path segments exactly `.`\n   * or `..` cannot be presigned safely because common URL parsers normalize\n   * them before sending the request.\n   */\n  readonly fileName: string\n  /**\n   * URL validity duration in seconds. Defaults to 3600. Must be an integer\n   * from 1 to 604800 (7 days), the AWS Signature Version 4 presign maximum.\n   * A presigned URL is a bearer credential for the signed operation; keep\n   * this as short as the calling workflow allows.\n   */\n  readonly expiresIn?: number\n}\n\n/** Options for {@link presignS3GetObjectUrl}. */\nexport interface PresignS3GetObjectUrlOptions extends S3PresignObjectUrlOptions {\n  /** Optional S3 version ID to include in the signed GET request. */\n  readonly versionId?: string\n  /**\n   * Override the response Cache-Control header. Response overrides control\n   * headers served from the storage origin; do not populate them from\n   * untrusted input without an allow-list.\n   */\n  readonly responseCacheControl?: string\n  /**\n   * Override the response Content-Disposition header. Prefer a safe\n   * attachment disposition when this value can be influenced by users. The\n   * helper rejects `inline` response dispositions by default because they can\n   * make stored bytes render from the storage origin.\n   */\n  readonly responseContentDisposition?: string\n  /**\n   * Permit an `inline` response Content-Disposition override. Set only when\n   * the object bytes and response headers are trusted to render from the\n   * storage origin. Pass {@link trustedUnsafeS3PresignOptIn}; plain booleans\n   * from request JSON are intentionally ignored by the runtime guard.\n   */\n  readonly allowInlineResponseContentDisposition?: TrustedUnsafeS3PresignOptIn\n  /**\n   * Override the response Content-Encoding header. Do not populate this from\n   * untrusted input without an allow-list.\n   */\n  readonly responseContentEncoding?: string\n  /**\n   * Override the response Content-Language header. Do not populate this from\n   * untrusted input without an allow-list.\n   */\n  readonly responseContentLanguage?: string\n  /**\n   * Override the response Content-Type header. If attacker-controlled, this\n   * can make stored bytes render as active content from the storage origin.\n   * Restrict it to known-safe values before signing. The helper's built-in\n   * rejection of known browser-executable and sniffable XML/JavaScript media\n   * types is best-effort and does not replace an application allow-list.\n   */\n  readonly responseContentType?: string\n  /**\n   * Permit browser-executable `responseContentType` overrides such as\n   * `text/html`, JavaScript, SVG, or XML media types. Leave this unset unless\n   * the served object is intentionally meant to render active content from the\n   * storage origin. Pass {@link trustedUnsafeS3PresignOptIn}; plain booleans\n   * from request JSON are intentionally ignored by the runtime guard.\n   */\n  readonly allowBrowserExecutableResponseContentType?: TrustedUnsafeS3PresignOptIn\n  /**\n   * Override the response Expires header. Do not populate this from\n   * untrusted input without an allow-list.\n   */\n  readonly responseExpires?: Date\n}\n\n/** Options for {@link presignS3PutObjectUrl}. */\nexport interface PresignS3PutObjectUrlOptions extends S3PresignObjectUrlOptions {\n  /**\n   * Optional content type for the uploaded object. When supplied, the generated\n   * URL signs the Content-Type header, so upload clients must send the same\n   * value. Browser-executable and sniffable XML/JavaScript types are rejected\n   * by default as a best-effort guard; callers accepting untrusted uploads\n   * should still enforce their own allow-list.\n   */\n  readonly contentType?: string\n  /**\n   * Permit browser-executable `contentType` values such as `text/html`,\n   * JavaScript, SVG, or XML media types. Leave this unset unless the uploaded\n   * object is intentionally meant to render active content from the storage\n   * origin. Pass {@link trustedUnsafeS3PresignOptIn}; plain booleans from\n   * request JSON are intentionally ignored by the runtime guard.\n   */\n  readonly allowBrowserExecutableContentType?: TrustedUnsafeS3PresignOptIn\n  /**\n   * Optional content length. Must be a non-negative safe integer. When\n   * supplied, the generated URL signs the Content-Length header, so upload\n   * clients must send the same value.\n   */\n  readonly contentLength?: number\n  /**\n   * Optional user metadata to attach to the object. The generated URL signs\n   * matching `x-amz-meta-*` headers, so upload clients must send the same values.\n   * Pass bare metadata keys; the helper adds the `x-amz-meta-` prefix. Metadata\n   * keys must be valid HTTP header tokens and must not differ only by case.\n   */\n  readonly metadata?: Record<string, string>\n}\n\n/**\n * Options for {@link presignPutObjectUrl}.\n *\n * @deprecated Use {@link PresignS3PutObjectUrlOptions}.\n */\nexport type PresignPutObjectUrlOptions = PresignS3PutObjectUrlOptions\n\n/**\n * Derives an S3-compatible client configuration from B2 authorization state.\n * Pass the result to `new S3Client(config)` from `@aws-sdk/client-s3`.\n *\n * Non-standard, custom, or proxied endpoints require an explicit `region`; set\n * it before deploying this SDK to those endpoints. The SDK no longer falls back\n * to `us-west-004` because that can mis-sign requests.\n *\n * @param config - B2 auth state, application key credentials, and optional region override.\n *\n * @returns Configuration ready for the AWS S3 SDK.\n *\n * @example\n * ```ts\n * const { B2_APPLICATION_KEY_ID, B2_APPLICATION_KEY } = process.env\n * if (!B2_APPLICATION_KEY_ID || !B2_APPLICATION_KEY) throw new Error('Missing B2 credentials')\n * const s3 = new S3Client(createS3ClientConfig({\n *   accountInfo: client.accountInfo,\n *   applicationKeyId: B2_APPLICATION_KEY_ID,\n *   applicationKey: B2_APPLICATION_KEY,\n * }))\n * ```\n */\nexport function createS3ClientConfig(config: B2S3Config): S3ClientConfig {\n  const s3Url = config.accountInfo.getS3ApiUrl()\n  const region = config.region ?? deriveRequiredS3Region(s3Url)\n  assertNonEmptyStringOption('applicationKeyId', config.applicationKeyId)\n  assertNonEmptyStringOption('applicationKey', config.applicationKey)\n  assertNonEmptyStringOption('region', region)\n  assertSigV4CredentialScopeComponent('applicationKeyId', config.applicationKeyId)\n  assertSigV4CredentialScopeComponent('region', region)\n\n  return {\n    endpoint: s3Url,\n    region,\n    credentials: {\n      accessKeyId: config.applicationKeyId,\n      secretAccessKey: config.applicationKey,\n    },\n    forcePathStyle: true,\n  }\n}\n\n/**\n * Extracts the B2 S3 region from a standard B2 S3 endpoint.\n *\n * Custom endpoints cannot be inferred safely. Pass `region` explicitly to\n * {@link createS3ClientConfig}, {@link presignS3GetObjectUrl}, or\n * {@link presignS3PutObjectUrl} when this returns `null`.\n *\n * @param endpoint - The S3 endpoint URL.\n *\n * @returns The derived region, or `null` when the endpoint is not a standard B2 S3 URL.\n */\nexport function deriveS3RegionFromEndpoint(endpoint: string): string | null {\n  let hostname: string\n  try {\n    hostname = new URL(endpoint).hostname.toLowerCase()\n  } catch {\n    return null\n  }\n\n  const match = /^s3\\.([a-z0-9-]+)\\.backblazeb2\\.com$/.exec(hostname)\n  return match?.[1] ?? null\n}\n\n// S3 SigV4 presign helpers.\n\n/**\n * Generates an AWS Signature Version 4 presigned GET URL for B2's S3-compatible API.\n *\n * This helper signs internally and does not pass the B2 application key to\n * runtime peer dependencies. Response override options are signed into the URL\n * and control headers served from the storage origin; do not populate them from\n * untrusted input without an allow-list. Presign success does not prove the URL\n * will be accepted later; keep URL-generating hosts clock-synchronized and\n * check clock skew when downstream use returns SigV4 403 errors.\n *\n * @param options - B2 auth state, S3 credentials, target object, and signing options.\n *\n * @returns The presigned URL string.\n */\nexport async function presignS3GetObjectUrl(\n  options: PresignS3GetObjectUrlOptions,\n): Promise<string> {\n  const query: QueryParam[] = [['x-id', 'GetObject']]\n  if (options.versionId !== undefined) {\n    assertSafeQueryValue('versionId', options.versionId)\n    query.push(['versionId', options.versionId])\n  }\n  if (options.responseCacheControl !== undefined) {\n    assertSafeResponseOverride('responseCacheControl', options.responseCacheControl)\n    query.push(['response-cache-control', options.responseCacheControl])\n  }\n  if (options.responseContentDisposition !== undefined) {\n    assertSafeResponseContentDisposition(\n      options.responseContentDisposition,\n      isTrustedUnsafeS3PresignOptIn(options.allowInlineResponseContentDisposition),\n    )\n    query.push(['response-content-disposition', options.responseContentDisposition])\n  }\n  if (options.responseContentEncoding !== undefined) {\n    assertSafeResponseOverride('responseContentEncoding', options.responseContentEncoding)\n    query.push(['response-content-encoding', options.responseContentEncoding])\n  }\n  if (options.responseContentLanguage !== undefined) {\n    assertSafeResponseOverride('responseContentLanguage', options.responseContentLanguage)\n    query.push(['response-content-language', options.responseContentLanguage])\n  }\n  if (options.responseContentType !== undefined) {\n    if (isTrustedUnsafeS3PresignOptIn(options.allowBrowserExecutableResponseContentType)) {\n      assertSafeContentTypeValue(\n        'responseContentType',\n        options.responseContentType,\n        'response header value',\n      )\n    } else {\n      assertSafeResponseContentType(options.responseContentType)\n    }\n    query.push(['response-content-type', options.responseContentType])\n  }\n  if (options.responseExpires !== undefined) {\n    query.push(['response-expires', normalizeResponseExpires(options.responseExpires)])\n  }\n\n  return await presignS3Request('GET', createSigV4PresignOptions(options), query, [])\n}\n\n/**\n * Returns a B2-native download-authorization URL, not an S3 presigned URL.\n *\n * This deprecated helper preserves the legacy positional output contract where\n * the whole file name is encoded as one URL component, including `/` as `%2F`.\n * It keeps the legacy string-building contract for callers that relied on\n * custom/local download URLs or permissive inputs. Use\n * {@link createNativeDownloadAuthorizationUrl} for strict validation.\n *\n * @param downloadUrl - The B2 download URL from authorization.\n * @param bucketName - The bucket containing the file.\n * @param fileName - The file name (path) to download.\n * @param authorizationToken - A download authorization token from `b2_get_download_authorization`.\n * @param validDurationInSeconds - Compatibility-only value for the non-authoritative `expires` query.\n *\n * @returns The B2 native download-authorization URL string.\n *\n * @deprecated Use {@link createNativeDownloadAuthorizationUrl} for B2 native\n * download-token URLs, or {@link presignS3GetObjectUrl} for real S3-compatible\n * AWS Signature Version 4 presigned GET URLs.\n */\nexport function presignGetObjectUrl(\n  downloadUrl: string,\n  bucketName: string,\n  fileName: string,\n  authorizationToken: string,\n  validDurationInSeconds?: number,\n): string {\n  const expires =\n    Math.floor(Date.now() / 1000) +\n    (validDurationInSeconds ?? DEFAULT_NATIVE_DOWNLOAD_URL_EXPIRES_IN)\n  return `${downloadUrl}/file/${encodeURIComponent(bucketName)}/${encodeURIComponent(fileName)}?Authorization=${encodeURIComponent(authorizationToken)}&expires=${expires}`\n}\n\n/**\n * Generates an AWS Signature Version 4 presigned PUT URL for browser or\n * third-party uploads through B2's S3-compatible API.\n *\n * This helper signs internally and does not pass the B2 application key to\n * runtime peer dependencies. A presigned PUT URL is a replayable bearer\n * credential for writing one key until expiry. Retried PUTs can create\n * duplicate B2 file versions when a response is lost after B2 stored the object.\n * Use unique keys or reconcile uploaded file IDs/checksums, and configure\n * lifecycle/version cleanup where duplicate versions must be removed\n * automatically. If `contentType` and `contentLength` are omitted, the holder\n * can choose any content type, including browser-executable types, and any size\n * accepted by B2; bind both values before handing URLs to untrusted uploaders\n * to limit financial-DoS and content-type smuggling risk.\n *\n * @param options - B2 auth state, S3 credentials, target object, and signing options.\n *\n * @returns The presigned URL string.\n */\nexport async function presignS3PutObjectUrl(\n  options: PresignS3PutObjectUrlOptions,\n): Promise<string> {\n  const headers: SignedHeader[] = []\n  if (options.contentType !== undefined) {\n    if (isTrustedUnsafeS3PresignOptIn(options.allowBrowserExecutableContentType)) {\n      assertSafeContentTypeValue('contentType', options.contentType, 'stored object Content-Type')\n    } else {\n      assertSafePutContentType(options.contentType)\n    }\n    headers.push(['content-type', options.contentType])\n  }\n  if (options.contentLength !== undefined) {\n    headers.push(['content-length', normalizeContentLength(options.contentLength)])\n  }\n  headers.push(...normalizeMetadataHeaders(options.metadata))\n\n  return await presignS3Request(\n    'PUT',\n    createSigV4PresignOptions(options),\n    [['x-id', 'PutObject']],\n    headers,\n  )\n}\n\n/**\n * Generates an AWS Signature Version 4 presigned PUT URL for B2's\n * S3-compatible API.\n *\n * @param options - B2 auth state, S3 credentials, target object, and signing options.\n *\n * @returns The presigned URL string.\n *\n * @deprecated Use {@link presignS3PutObjectUrl}; this alias is retained for\n * pre-release callers that adopted the shorter name.\n */\nexport async function presignPutObjectUrl(options: PresignPutObjectUrlOptions): Promise<string> {\n  return await presignS3PutObjectUrl(options)\n}\n\n// B2-native download authorization helper.\n\n/**\n * Constructs a B2-native download URL using a token from `b2_get_download_authorization`.\n * This is not an S3 presigned URL.\n *\n * The token lifetime is fixed when `b2_get_download_authorization` creates the\n * token. `validDurationInSeconds` is retained only for compatibility with the\n * legacy `presignGetObjectUrl` helper's decorative `expires` query parameter;\n * changing it here does not shorten or extend access.\n * Because the returned URL carries a bearer token, `downloadUrl` must be an\n * HTTPS Backblaze download origin without userinfo, path, query, or fragment.\n *\n * @param downloadUrl - The B2 download URL from authorization (e.g., `https://f004.backblazeb2.com`).\n * @param bucketName - The bucket containing the file.\n * @param fileName - The file name (path) to download.\n * @param authorizationToken - A download authorization token from `b2_get_download_authorization`.\n * @param validDurationInSeconds - Compatibility-only value for the non-authoritative `expires` query.\n *\n * @returns The B2 native download-authorization URL string, not an S3 presigned URL.\n */\nexport function createNativeDownloadAuthorizationUrl(\n  downloadUrl: string,\n  bucketName: string,\n  fileName: string,\n  authorizationToken: string,\n  validDurationInSeconds = DEFAULT_NATIVE_DOWNLOAD_URL_EXPIRES_IN,\n): string {\n  return buildNativeDownloadAuthorizationUrl(\n    downloadUrl,\n    bucketName,\n    fileName,\n    authorizationToken,\n    validDurationInSeconds,\n    encodeFileName,\n    assertNativeDownloadFileName,\n  )\n}\n\nfunction deriveRequiredS3Region(endpoint: string): string {\n  const region = deriveS3RegionFromEndpoint(endpoint)\n  if (region !== null) return region\n\n  throw new Error(\n    `Unable to derive B2 S3 region from endpoint \"${redactUrlForError(endpoint, {\n      invalidUrlLabel: '<invalid S3 endpoint URL>',\n    })}\". Pass an explicit \\`region\\` option before deploying custom or proxied endpoints.`,\n  )\n}\n\nfunction createSigV4PresignOptions(options: S3PresignObjectUrlOptions): SigV4PresignRequestOptions {\n  const clientConfig = createS3ClientConfig(options)\n  return {\n    endpoint: clientConfig.endpoint,\n    region: clientConfig.region,\n    accessKeyId: clientConfig.credentials.accessKeyId,\n    secretAccessKey: clientConfig.credentials.secretAccessKey,\n    bucketName: options.bucketName,\n    fileName: options.fileName,\n    ...(options.expiresIn !== undefined ? { expiresIn: options.expiresIn } : {}),\n  }\n}\n\nfunction normalizeContentLength(contentLength: number): string {\n  if (!Number.isSafeInteger(contentLength) || contentLength < 0) {\n    throw new RangeError(\n      `contentLength must be a non-negative safe integer; received ${String(contentLength)}.`,\n    )\n  }\n\n  return String(contentLength)\n}\n\nfunction normalizeValidDurationInSeconds(validDurationInSeconds: number): number {\n  if (!Number.isSafeInteger(validDurationInSeconds) || validDurationInSeconds < 0) {\n    throw new RangeError(\n      `validDurationInSeconds must be a non-negative safe integer; received ${String(\n        validDurationInSeconds,\n      )}.`,\n    )\n  }\n\n  return validDurationInSeconds\n}\n\nfunction assertNonEmptyStringOption(name: string, value: unknown): asserts value is string {\n  if (typeof value !== 'string' || value.trim().length === 0) {\n    throw new TypeError(`${name} must be a non-empty string.`)\n  }\n}\n\nfunction assertSigV4CredentialScopeComponent(name: string, value: string): void {\n  if (/[\\s/]/u.test(value) || hasHttpHeaderControlCharacter(value)) {\n    throw new TypeError(\n      `${name} must not contain whitespace, control characters, or \"/\" because it is embedded in the SigV4 credential scope.`,\n    )\n  }\n}\n\nfunction isTrustedUnsafeS3PresignOptIn(value: unknown): value is TrustedUnsafeS3PresignOptIn {\n  return value === trustedUnsafeS3PresignOptIn\n}\n\nfunction buildNativeDownloadAuthorizationUrl(\n  downloadUrl: string,\n  bucketName: string,\n  fileName: string,\n  authorizationToken: string,\n  validDurationInSeconds: number,\n  encodeFileNameForUrl: (fileName: string) => string,\n  assertFileName: (fileName: string) => void,\n): string {\n  const baseUrl = parseNativeDownloadBaseUrl(downloadUrl)\n  assertSafeBucketName(bucketName)\n  assertFileName(fileName)\n  const expires =\n    Math.floor(Date.now() / 1000) + normalizeValidDurationInSeconds(validDurationInSeconds)\n  return `${baseUrl}/file/${encodeURIComponent(bucketName)}/${encodeFileNameForUrl(fileName)}?Authorization=${encodeURIComponent(authorizationToken)}&expires=${expires}`\n}\n\nfunction parseNativeDownloadBaseUrl(downloadUrl: string): string {\n  let base: URL\n  try {\n    base = new URL(downloadUrl)\n  } catch {\n    throw new TypeError(\n      `Native download-authorization URLs require a valid https: downloadUrl; received \"${redactUrlForError(\n        downloadUrl,\n        { invalidUrlLabel: '<invalid downloadUrl>' },\n      )}\".`,\n    )\n  }\n\n  if (base.protocol !== 'https:') {\n    throw new TypeError(\n      `Native download-authorization URLs require an https: downloadUrl; received \"${redactUrlForError(\n        base,\n      )}\".`,\n    )\n  }\n  if (base.username !== '' || base.password !== '') {\n    throw new TypeError('Native download-authorization URLs must not include userinfo.')\n  }\n  if (base.search !== '' || base.hash !== '') {\n    throw new TypeError('Native download-authorization URLs must not include query or fragment.')\n  }\n  if (base.pathname !== '' && base.pathname !== '/') {\n    throw new TypeError('Native download-authorization URLs must not include a path.')\n  }\n  if (!isTrustedNativeDownloadHost(base.hostname)) {\n    throw new TypeError(\n      `Native download-authorization URLs require a Backblaze download host; received \"${redactUrlForError(\n        base,\n      )}\".`,\n    )\n  }\n\n  return base.origin\n}\n\nfunction normalizeMetadataHeaders(metadata: Record<string, string> | undefined): SignedHeader[] {\n  const headers: SignedHeader[] = []\n  const seenKeys = new Set<string>()\n\n  for (const [key, value] of Object.entries(metadata ?? {})) {\n    if (!HTTP_HEADER_TOKEN.test(key)) {\n      throw new TypeError(`metadata key \"${key}\" must be a non-empty valid HTTP header token.`)\n    }\n    if (typeof value !== 'string') {\n      throw new TypeError(`metadata value for \"${key}\" must be a string.`)\n    }\n\n    const lowerKey = key.toLowerCase()\n    if (seenKeys.has(lowerKey)) {\n      throw new TypeError(`metadata key \"${key}\" must not differ only by case.`)\n    }\n\n    seenKeys.add(lowerKey)\n    headers.push([`x-amz-meta-${lowerKey}`, value])\n  }\n\n  return headers\n}\n\nfunction normalizeResponseExpires(responseExpires: Date): string {\n  if (!Number.isFinite(responseExpires.getTime())) {\n    throw new RangeError('responseExpires must be a valid Date.')\n  }\n\n  return responseExpires.toUTCString()\n}\n\nfunction assertSafeResponseOverride(name: string, value: string): void {\n  assertSafeHeaderValue(name, value, 'response header value')\n}\n\nfunction assertSafeQueryValue(name: string, value: string): void {\n  if (hasHttpHeaderControlCharacter(value)) {\n    throw new TypeError(\n      `${name} must not contain control characters because it becomes a query parameter.`,\n    )\n  }\n}\n\nfunction assertSafeHeaderValue(name: string, value: string, target: string): void {\n  if (hasHttpHeaderControlCharacter(value)) {\n    throw new TypeError(\n      `${name} must not contain control characters because it becomes a ${target}.`,\n    )\n  }\n}\n\nfunction assertSafeResponseContentType(contentType: string): void {\n  assertNonExecutableContentType(\n    'responseContentType',\n    contentType,\n    'response header value',\n    'allow-list a safe content type before signing response overrides',\n  )\n}\n\nfunction assertSafePutContentType(contentType: string): void {\n  assertNonExecutableContentType(\n    'contentType',\n    contentType,\n    'stored object Content-Type',\n    'pass allowBrowserExecutableContentType only when active content is intentional',\n  )\n}\n\nfunction assertSafeResponseContentDisposition(\n  contentDisposition: string,\n  allowInline: boolean,\n): void {\n  assertSafeResponseOverride('responseContentDisposition', contentDisposition)\n\n  const disposition = contentDisposition.split(';', 1)[0]?.trim().toLowerCase()\n  if (!allowInline && disposition === 'inline') {\n    throw new TypeError(\n      'responseContentDisposition must not force inline rendering; use an attachment disposition for response overrides.',\n    )\n  }\n}\n\nfunction mediaTypeFor(contentType: string): string {\n  return contentType.split(';', 1)[0]?.trim().toLowerCase() ?? ''\n}\n\nfunction assertSafeContentTypeValue(name: string, contentType: string, target: string): string {\n  assertSafeHeaderValue(name, contentType, target)\n\n  const mediaType = mediaTypeFor(contentType)\n  if (mediaType.length === 0) {\n    throw new TypeError(`${name} must include a non-empty media type.`)\n  }\n  if (!HTTP_MEDIA_TYPE.test(mediaType)) {\n    throw new TypeError(`${name} must include a valid media type.`)\n  }\n\n  return mediaType\n}\n\nfunction assertNonExecutableContentType(\n  name: string,\n  contentType: string,\n  target: string,\n  guidance: string,\n): void {\n  const mediaType = assertSafeContentTypeValue(name, contentType, target)\n  if (isBrowserExecutableContentType(mediaType)) {\n    throw new TypeError(`${name} \"${mediaType}\" can execute in browsers; ${guidance}.`)\n  }\n}\n\nfunction isBrowserExecutableContentType(mediaType: string): boolean {\n  return BROWSER_EXECUTABLE_CONTENT_TYPES.has(mediaType) || mediaType.endsWith('+xml')\n}\n\nfunction isTrustedNativeDownloadHost(hostname: string): boolean {\n  return TRUSTED_NATIVE_DOWNLOAD_HOST_SUFFIXES.some((suffix) =>\n    hostMatchesAllowedSuffix(hostname, suffix),\n  )\n}\n"],"mappings":"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"}

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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"}