@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/dist/s3/sigv4.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sigv4.cjs","names":[],"sources":["../../src/s3/sigv4.ts"],"sourcesContent":["import { redactUrlForError } from '../internal/url-redaction.ts'\nimport { hexEncode, hmacSha256, sha256Hex } from '../util/crypto.ts'\nimport { hasHttpHeaderControlCharacter } from '../util/http.ts'\nimport { assertSafeBucketName, assertValidB2FileName } from './validation.ts'\n\nconst MAX_PRESIGN_EXPIRES_IN = 604_800\nconst UNSIGNED_PAYLOAD = 'UNSIGNED-PAYLOAD'\nconst SERVICE = 's3'\nconst TERMINATOR = 'aws4_request'\n/** Default S3 presigned URL validity duration in seconds. */\nexport const DEFAULT_PRESIGN_EXPIRES_IN = 3600\n\n/** Date input accepted by SigV4 presign internals and deterministic tests. */\nexport type S3PresignDate = Date | number\n\n/** Query parameter included in the SigV4 canonical query string. */\nexport type QueryParam = readonly [name: string, value: string]\n\n/** HTTP header included in the SigV4 signed headers list. */\nexport type SignedHeader = readonly [name: string, value: string]\n\n/** Internal inputs required to presign one S3-compatible object request. */\nexport interface SigV4PresignRequestOptions {\n  /** S3-compatible endpoint URL. */\n  readonly endpoint: string\n  /** S3 signing region. */\n  readonly region: string\n  /** S3 access key ID. */\n  readonly accessKeyId: string\n  /** S3 secret access key. */\n  readonly secretAccessKey: string\n  /** Bucket containing the object. */\n  readonly bucketName: string\n  /** Object key / B2 file name. */\n  readonly fileName: string\n  /** Optional URL validity duration in seconds. */\n  readonly expiresIn?: number\n  /** Optional signing clock override. */\n  readonly signingDate?: S3PresignDate\n}\n\n/**\n * Generates an AWS Signature Version 4 presigned S3-compatible request URL.\n *\n * This module owns only canonical SigV4 mechanics: canonical URI/query/header\n * construction, signing-key derivation, and signature encoding. Public B2 S3\n * option validation and naming stay in `index.ts`.\n *\n * @param method - HTTP method to presign.\n * @param options - S3 endpoint, credentials, object key, and signing options.\n * @param extraQuery - Operation-specific query parameters to sign.\n * @param extraHeaders - Operation-specific request headers to sign.\n *\n * @returns The presigned request URL.\n */\nexport async function presignS3Request(\n  method: 'GET' | 'PUT',\n  options: SigV4PresignRequestOptions,\n  extraQuery: readonly QueryParam[],\n  extraHeaders: readonly SignedHeader[],\n): Promise<string> {\n  const endpoint = parseEndpoint(options.endpoint)\n  assertHttpsEndpoint(endpoint)\n  const expiresIn = normalizeExpiresIn(options.expiresIn)\n  const { shortDate, longDate } = formatSigningDate(options.signingDate)\n  const credentialScope = `${shortDate}/${options.region}/${SERVICE}/${TERMINATOR}`\n  const credential = `${options.accessKeyId}/${credentialScope}`\n  assertSafeBucketName(options.bucketName)\n  assertValidB2FileName(options.fileName)\n  const canonicalUri = buildCanonicalUri(endpoint.pathname, options.bucketName, options.fileName)\n  const headers = normalizeSignedHeaders([['host', canonicalHostHeader(endpoint)], ...extraHeaders])\n  const signedHeaders = headers.map(([name]) => name).join(';')\n\n  const query: QueryParam[] = [\n    ['X-Amz-Algorithm', 'AWS4-HMAC-SHA256'],\n    ['X-Amz-Credential', credential],\n    ['X-Amz-Content-Sha256', UNSIGNED_PAYLOAD],\n    ['X-Amz-Date', longDate],\n    ['X-Amz-Expires', String(expiresIn)],\n    ['X-Amz-SignedHeaders', signedHeaders],\n    ...extraQuery,\n  ]\n  const canonicalQuery = canonicalQueryString(query)\n  const canonicalHeaders = headers.map(([name, value]) => `${name}:${value}\\n`).join('')\n  const canonicalRequest = [\n    method,\n    canonicalUri,\n    canonicalQuery,\n    canonicalHeaders,\n    signedHeaders,\n    UNSIGNED_PAYLOAD,\n  ].join('\\n')\n  const stringToSign = [\n    'AWS4-HMAC-SHA256',\n    longDate,\n    credentialScope,\n    await sha256Hex(canonicalRequest),\n  ].join('\\n')\n  const signingKey = await deriveSigningKey(options.secretAccessKey, shortDate, options.region)\n  const signature = hexEncode(await hmacSha256(signingKey, stringToSign))\n  const finalQuery = canonicalQueryString([...query, ['X-Amz-Signature', signature]])\n\n  return `${endpoint.origin}${canonicalUri}?${finalQuery}`\n}\n\nfunction normalizeExpiresIn(expiresIn: number | undefined): number {\n  const value = expiresIn ?? DEFAULT_PRESIGN_EXPIRES_IN\n  if (!Number.isInteger(value) || value < 1 || value > MAX_PRESIGN_EXPIRES_IN) {\n    throw new RangeError(\n      `expiresIn must be an integer from 1 to ${MAX_PRESIGN_EXPIRES_IN} seconds; received ${String(value)}.`,\n    )\n  }\n  return value\n}\n\nfunction formatSigningDate(input: S3PresignDate | undefined): {\n  readonly shortDate: string\n  readonly longDate: string\n} {\n  const date = input === undefined ? new Date() : new Date(input)\n  if (!Number.isFinite(date.getTime())) {\n    throw new RangeError('signingDate must be a valid Date or timestamp.')\n  }\n\n  const year = String(date.getUTCFullYear()).padStart(4, '0')\n  const month = String(date.getUTCMonth() + 1).padStart(2, '0')\n  const day = String(date.getUTCDate()).padStart(2, '0')\n  const hour = String(date.getUTCHours()).padStart(2, '0')\n  const minute = String(date.getUTCMinutes()).padStart(2, '0')\n  const second = String(date.getUTCSeconds()).padStart(2, '0')\n  const shortDate = `${year}${month}${day}`\n  return {\n    shortDate,\n    longDate: `${shortDate}T${hour}${minute}${second}Z`,\n  }\n}\n\nfunction buildCanonicalUri(endpointPath: string, bucketName: string, fileName: string): string {\n  const basePath =\n    endpointPath === '' || endpointPath === '/' ? '' : endpointPath.replace(/\\/+$/, '')\n  return `${basePath}/${awsPercentEncode(bucketName)}/${encodePath(fileName)}`\n}\n\nfunction canonicalHostHeader(endpoint: URL): string {\n  const host = endpoint.host\n  if (endpoint.protocol === 'https:' && host.endsWith(':443')) {\n    return host.slice(0, -4)\n  }\n  return host\n}\n\nfunction parseEndpoint(endpoint: string): URL {\n  try {\n    return new URL(endpoint)\n  } catch (cause) {\n    throw new TypeError(\n      `S3 presigned URL endpoint must be a valid URL; received \"${redactUrlForError(endpoint, {\n        invalidUrlLabel: '<invalid S3 endpoint URL>',\n      })}\".`,\n      { cause },\n    )\n  }\n}\n\nfunction assertHttpsEndpoint(endpoint: URL): void {\n  if (endpoint.protocol !== 'https:') {\n    throw new TypeError(\n      `S3 presigned URLs require an https: endpoint; received \"${redactUrlForError(endpoint)}\".`,\n    )\n  }\n}\n\nfunction encodePath(path: string): string {\n  return path.split('/').map(awsPercentEncode).join('/')\n}\n\nfunction canonicalQueryString(query: readonly QueryParam[]): string {\n  return query\n    .map(([name, value]) => [awsPercentEncode(name), awsPercentEncode(value)] as const)\n    .sort(([aName, aValue], [bName, bValue]) => {\n      if (aName < bName) return -1\n      if (aName > bName) return 1\n      if (aValue < bValue) return -1\n      if (aValue > bValue) return 1\n      return 0\n    })\n    .map(([name, value]) => `${name}=${value}`)\n    .join('&')\n}\n\n/**\n * Percent-encode according to AWS SigV4 canonical request rules.\n *\n * @param value - Raw value to encode.\n *\n * @returns AWS-compatible percent-encoded value.\n */\nfunction awsPercentEncode(value: string): string {\n  return encodeURIComponent(value).replace(\n    /[!'()*]/g,\n    (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`,\n  )\n}\n\nfunction normalizeSignedHeaders(headers: readonly SignedHeader[]): SignedHeader[] {\n  const combinedHeaders = new Map<string, string[]>()\n  for (const [name, value] of headers) {\n    const normalizedName = name.toLowerCase()\n    const values = combinedHeaders.get(normalizedName)\n    if (values) {\n      values.push(normalizeHeaderValue(value))\n    } else {\n      combinedHeaders.set(normalizedName, [normalizeHeaderValue(value)])\n    }\n  }\n\n  return [...combinedHeaders.entries()]\n    .map(([name, values]) => [name, values.join(',')] as const)\n    .sort(([a], [b]) => {\n      if (a < b) return -1\n      if (a > b) return 1\n      return 0\n    })\n}\n\nfunction normalizeHeaderValue(value: string): string {\n  if (hasHttpHeaderControlCharacter(value)) {\n    throw new TypeError('signed header values must not contain control characters.')\n  }\n\n  return value.trim().replace(/ +/g, ' ')\n}\n\nasync function deriveSigningKey(\n  secretAccessKey: string,\n  shortDate: string,\n  region: string,\n): Promise<Uint8Array> {\n  const dateKey = await hmacSha256(`AWS4${secretAccessKey}`, shortDate)\n  const dateRegionKey = await hmacSha256(dateKey, region)\n  const dateRegionServiceKey = await hmacSha256(dateRegionKey, SERVICE)\n  return await hmacSha256(dateRegionServiceKey, TERMINATOR)\n}\n"],"mappings":"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"}

package/dist/s3/sigv4.d.cts

@@ -0,0 +1,43 @@
+/** Default S3 presigned URL validity duration in seconds. */
+export declare const DEFAULT_PRESIGN_EXPIRES_IN = 3600;
+/** Date input accepted by SigV4 presign internals and deterministic tests. */
+export type S3PresignDate = Date | number;
+/** Query parameter included in the SigV4 canonical query string. */
+export type QueryParam = readonly [name: string, value: string];
+/** HTTP header included in the SigV4 signed headers list. */
+export type SignedHeader = readonly [name: string, value: string];
+/** Internal inputs required to presign one S3-compatible object request. */
+export interface SigV4PresignRequestOptions {
+    /** S3-compatible endpoint URL. */
+    readonly endpoint: string;
+    /** S3 signing region. */
+    readonly region: string;
+    /** S3 access key ID. */
+    readonly accessKeyId: string;
+    /** S3 secret access key. */
+    readonly secretAccessKey: string;
+    /** Bucket containing the object. */
+    readonly bucketName: string;
+    /** Object key / B2 file name. */
+    readonly fileName: string;
+    /** Optional URL validity duration in seconds. */
+    readonly expiresIn?: number;
+    /** Optional signing clock override. */
+    readonly signingDate?: S3PresignDate;
+}
+/**
+ * Generates an AWS Signature Version 4 presigned S3-compatible request URL.
+ *
+ * This module owns only canonical SigV4 mechanics: canonical URI/query/header
+ * construction, signing-key derivation, and signature encoding. Public B2 S3
+ * option validation and naming stay in `index.ts`.
+ *
+ * @param method - HTTP method to presign.
+ * @param options - S3 endpoint, credentials, object key, and signing options.
+ * @param extraQuery - Operation-specific query parameters to sign.
+ * @param extraHeaders - Operation-specific request headers to sign.
+ *
+ * @returns The presigned request URL.
+ */
+export declare function presignS3Request(method: 'GET' | 'PUT', options: SigV4PresignRequestOptions, extraQuery: readonly QueryParam[], extraHeaders: readonly SignedHeader[]): Promise<string>;
+//# sourceMappingURL=sigv4.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sigv4.d.ts","sourceRoot":"","sources":["../../src/s3/sigv4.js"],"names":[],"mappings":"AASA,6DAA6D;AAC7D,eAAO,MAAM,0BAA0B,OAAO,CAAA;AAE9C,8EAA8E;AAC9E,MAAM,MAAM,aAAa,GAAG,IAAI,GAAG,MAAM,CAAA;AAEzC,oEAAoE;AACpE,MAAM,MAAM,UAAU,GAAG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAA;AAE/D,6DAA6D;AAC7D,MAAM,MAAM,YAAY,GAAG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAA;AAEjE,4EAA4E;AAC5E,MAAM,WAAW,0BAA0B;IACzC,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,wBAAwB;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,4BAA4B;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,oCAAoC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,iDAAiD;IACjD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,uCAAuC;IACvC,QAAQ,CAAC,WAAW,CAAC,EAAE,aAAa,CAAA;CACrC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,KAAK,GAAG,KAAK,EACrB,OAAO,EAAE,0BAA0B,EACnC,UAAU,EAAE,SAAS,UAAU,EAAE,EACjC,YAAY,EAAE,SAAS,YAAY,EAAE,GACpC,OAAO,CAAC,MAAM,CAAC,CA2CjB"}

package/dist/s3/sigv4.d.ts

@@ -0,0 +1,43 @@
+/** Default S3 presigned URL validity duration in seconds. */
+export declare const DEFAULT_PRESIGN_EXPIRES_IN = 3600;
+/** Date input accepted by SigV4 presign internals and deterministic tests. */
+export type S3PresignDate = Date | number;
+/** Query parameter included in the SigV4 canonical query string. */
+export type QueryParam = readonly [name: string, value: string];
+/** HTTP header included in the SigV4 signed headers list. */
+export type SignedHeader = readonly [name: string, value: string];
+/** Internal inputs required to presign one S3-compatible object request. */
+export interface SigV4PresignRequestOptions {
+    /** S3-compatible endpoint URL. */
+    readonly endpoint: string;
+    /** S3 signing region. */
+    readonly region: string;
+    /** S3 access key ID. */
+    readonly accessKeyId: string;
+    /** S3 secret access key. */
+    readonly secretAccessKey: string;
+    /** Bucket containing the object. */
+    readonly bucketName: string;
+    /** Object key / B2 file name. */
+    readonly fileName: string;
+    /** Optional URL validity duration in seconds. */
+    readonly expiresIn?: number;
+    /** Optional signing clock override. */
+    readonly signingDate?: S3PresignDate;
+}
+/**
+ * Generates an AWS Signature Version 4 presigned S3-compatible request URL.
+ *
+ * This module owns only canonical SigV4 mechanics: canonical URI/query/header
+ * construction, signing-key derivation, and signature encoding. Public B2 S3
+ * option validation and naming stay in `index.ts`.
+ *
+ * @param method - HTTP method to presign.
+ * @param options - S3 endpoint, credentials, object key, and signing options.
+ * @param extraQuery - Operation-specific query parameters to sign.
+ * @param extraHeaders - Operation-specific request headers to sign.
+ *
+ * @returns The presigned request URL.
+ */
+export declare function presignS3Request(method: 'GET' | 'PUT', options: SigV4PresignRequestOptions, extraQuery: readonly QueryParam[], extraHeaders: readonly SignedHeader[]): Promise<string>;
+//# sourceMappingURL=sigv4.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sigv4.d.ts","sourceRoot":"","sources":["../../src/s3/sigv4.js"],"names":[],"mappings":"AASA,6DAA6D;AAC7D,eAAO,MAAM,0BAA0B,OAAO,CAAA;AAE9C,8EAA8E;AAC9E,MAAM,MAAM,aAAa,GAAG,IAAI,GAAG,MAAM,CAAA;AAEzC,oEAAoE;AACpE,MAAM,MAAM,UAAU,GAAG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAA;AAE/D,6DAA6D;AAC7D,MAAM,MAAM,YAAY,GAAG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAA;AAEjE,4EAA4E;AAC5E,MAAM,WAAW,0BAA0B;IACzC,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,wBAAwB;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,4BAA4B;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,oCAAoC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,iDAAiD;IACjD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,uCAAuC;IACvC,QAAQ,CAAC,WAAW,CAAC,EAAE,aAAa,CAAA;CACrC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,KAAK,GAAG,KAAK,EACrB,OAAO,EAAE,0BAA0B,EACnC,UAAU,EAAE,SAAS,UAAU,EAAE,EACjC,YAAY,EAAE,SAAS,YAAY,EAAE,GACpC,OAAO,CAAC,MAAM,CAAC,CA2CjB"}

package/dist/s3/sigv4.js

@@ -0,0 +1,148 @@
+import { redactUrlForError } from "../internal/url-redaction.js";
+import { hexEncode, hmacSha256, sha256Hex } from "../util/crypto.js";
+import { hasHttpHeaderControlCharacter } from "../util/http.js";
+import { assertSafeBucketName, assertValidB2FileName } from "./validation.js";
+//#region src/s3/sigv4.ts
+var MAX_PRESIGN_EXPIRES_IN = 604800;
+var UNSIGNED_PAYLOAD = "UNSIGNED-PAYLOAD";
+var SERVICE = "s3";
+var TERMINATOR = "aws4_request";
+/** Default S3 presigned URL validity duration in seconds. */
+var DEFAULT_PRESIGN_EXPIRES_IN = 3600;
+/**
+* Generates an AWS Signature Version 4 presigned S3-compatible request URL.
+*
+* This module owns only canonical SigV4 mechanics: canonical URI/query/header
+* construction, signing-key derivation, and signature encoding. Public B2 S3
+* option validation and naming stay in `index.ts`.
+*
+* @param method - HTTP method to presign.
+* @param options - S3 endpoint, credentials, object key, and signing options.
+* @param extraQuery - Operation-specific query parameters to sign.
+* @param extraHeaders - Operation-specific request headers to sign.
+*
+* @returns The presigned request URL.
+*/
+async function presignS3Request(method, options, extraQuery, extraHeaders) {
+	const endpoint = parseEndpoint(options.endpoint);
+	assertHttpsEndpoint(endpoint);
+	const expiresIn = normalizeExpiresIn(options.expiresIn);
+	const { shortDate, longDate } = formatSigningDate(options.signingDate);
+	const credentialScope = `${shortDate}/${options.region}/${SERVICE}/${TERMINATOR}`;
+	const credential = `${options.accessKeyId}/${credentialScope}`;
+	assertSafeBucketName(options.bucketName);
+	assertValidB2FileName(options.fileName);
+	const canonicalUri = buildCanonicalUri(endpoint.pathname, options.bucketName, options.fileName);
+	const headers = normalizeSignedHeaders([["host", canonicalHostHeader(endpoint)], ...extraHeaders]);
+	const signedHeaders = headers.map(([name]) => name).join(";");
+	const query = [
+		["X-Amz-Algorithm", "AWS4-HMAC-SHA256"],
+		["X-Amz-Credential", credential],
+		["X-Amz-Content-Sha256", UNSIGNED_PAYLOAD],
+		["X-Amz-Date", longDate],
+		["X-Amz-Expires", String(expiresIn)],
+		["X-Amz-SignedHeaders", signedHeaders],
+		...extraQuery
+	];
+	const stringToSign = [
+		"AWS4-HMAC-SHA256",
+		longDate,
+		credentialScope,
+		await sha256Hex([
+			method,
+			canonicalUri,
+			canonicalQueryString(query),
+			headers.map(([name, value]) => `${name}:${value}\n`).join(""),
+			signedHeaders,
+			UNSIGNED_PAYLOAD
+		].join("\n"))
+	].join("\n");
+	const signature = hexEncode(await hmacSha256(await deriveSigningKey(options.secretAccessKey, shortDate, options.region), stringToSign));
+	const finalQuery = canonicalQueryString([...query, ["X-Amz-Signature", signature]]);
+	return `${endpoint.origin}${canonicalUri}?${finalQuery}`;
+}
+function normalizeExpiresIn(expiresIn) {
+	const value = expiresIn ?? 3600;
+	if (!Number.isInteger(value) || value < 1 || value > MAX_PRESIGN_EXPIRES_IN) throw new RangeError(`expiresIn must be an integer from 1 to ${MAX_PRESIGN_EXPIRES_IN} seconds; received ${String(value)}.`);
+	return value;
+}
+function formatSigningDate(input) {
+	const date = input === void 0 ? /* @__PURE__ */ new Date() : new Date(input);
+	if (!Number.isFinite(date.getTime())) throw new RangeError("signingDate must be a valid Date or timestamp.");
+	const year = String(date.getUTCFullYear()).padStart(4, "0");
+	const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+	const day = String(date.getUTCDate()).padStart(2, "0");
+	const hour = String(date.getUTCHours()).padStart(2, "0");
+	const minute = String(date.getUTCMinutes()).padStart(2, "0");
+	const second = String(date.getUTCSeconds()).padStart(2, "0");
+	const shortDate = `${year}${month}${day}`;
+	return {
+		shortDate,
+		longDate: `${shortDate}T${hour}${minute}${second}Z`
+	};
+}
+function buildCanonicalUri(endpointPath, bucketName, fileName) {
+	return `${endpointPath === "" || endpointPath === "/" ? "" : endpointPath.replace(/\/+$/, "")}/${awsPercentEncode(bucketName)}/${encodePath(fileName)}`;
+}
+function canonicalHostHeader(endpoint) {
+	const host = endpoint.host;
+	if (endpoint.protocol === "https:" && host.endsWith(":443")) return host.slice(0, -4);
+	return host;
+}
+function parseEndpoint(endpoint) {
+	try {
+		return new URL(endpoint);
+	} catch (cause) {
+		throw new TypeError(`S3 presigned URL endpoint must be a valid URL; received "${redactUrlForError(endpoint, { invalidUrlLabel: "<invalid S3 endpoint URL>" })}".`, { cause });
+	}
+}
+function assertHttpsEndpoint(endpoint) {
+	if (endpoint.protocol !== "https:") throw new TypeError(`S3 presigned URLs require an https: endpoint; received "${redactUrlForError(endpoint)}".`);
+}
+function encodePath(path) {
+	return path.split("/").map(awsPercentEncode).join("/");
+}
+function canonicalQueryString(query) {
+	return query.map(([name, value]) => [awsPercentEncode(name), awsPercentEncode(value)]).sort(([aName, aValue], [bName, bValue]) => {
+		if (aName < bName) return -1;
+		if (aName > bName) return 1;
+		if (aValue < bValue) return -1;
+		if (aValue > bValue) return 1;
+		return 0;
+	}).map(([name, value]) => `${name}=${value}`).join("&");
+}
+/**
+* Percent-encode according to AWS SigV4 canonical request rules.
+*
+* @param value - Raw value to encode.
+*
+* @returns AWS-compatible percent-encoded value.
+*/
+function awsPercentEncode(value) {
+	return encodeURIComponent(value).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+function normalizeSignedHeaders(headers) {
+	const combinedHeaders = /* @__PURE__ */ new Map();
+	for (const [name, value] of headers) {
+		const normalizedName = name.toLowerCase();
+		const values = combinedHeaders.get(normalizedName);
+		if (values) values.push(normalizeHeaderValue(value));
+		else combinedHeaders.set(normalizedName, [normalizeHeaderValue(value)]);
+	}
+	return [...combinedHeaders.entries()].map(([name, values]) => [name, values.join(",")]).sort(([a], [b]) => {
+		if (a < b) return -1;
+		if (a > b) return 1;
+		return 0;
+	});
+}
+function normalizeHeaderValue(value) {
+	if (hasHttpHeaderControlCharacter(value)) throw new TypeError("signed header values must not contain control characters.");
+	return value.trim().replace(/ +/g, " ");
+}
+async function deriveSigningKey(secretAccessKey, shortDate, region) {
+	return await hmacSha256(await hmacSha256(await hmacSha256(await hmacSha256(`AWS4${secretAccessKey}`, shortDate), region), SERVICE), TERMINATOR);
+}
+//#endregion
+export { DEFAULT_PRESIGN_EXPIRES_IN, presignS3Request };
+
+//# sourceMappingURL=sigv4.js.map

package/dist/s3/sigv4.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sigv4.js","names":[],"sources":["../../src/s3/sigv4.ts"],"sourcesContent":["import { redactUrlForError } from '../internal/url-redaction.ts'\nimport { hexEncode, hmacSha256, sha256Hex } from '../util/crypto.ts'\nimport { hasHttpHeaderControlCharacter } from '../util/http.ts'\nimport { assertSafeBucketName, assertValidB2FileName } from './validation.ts'\n\nconst MAX_PRESIGN_EXPIRES_IN = 604_800\nconst UNSIGNED_PAYLOAD = 'UNSIGNED-PAYLOAD'\nconst SERVICE = 's3'\nconst TERMINATOR = 'aws4_request'\n/** Default S3 presigned URL validity duration in seconds. */\nexport const DEFAULT_PRESIGN_EXPIRES_IN = 3600\n\n/** Date input accepted by SigV4 presign internals and deterministic tests. */\nexport type S3PresignDate = Date | number\n\n/** Query parameter included in the SigV4 canonical query string. */\nexport type QueryParam = readonly [name: string, value: string]\n\n/** HTTP header included in the SigV4 signed headers list. */\nexport type SignedHeader = readonly [name: string, value: string]\n\n/** Internal inputs required to presign one S3-compatible object request. */\nexport interface SigV4PresignRequestOptions {\n  /** S3-compatible endpoint URL. */\n  readonly endpoint: string\n  /** S3 signing region. */\n  readonly region: string\n  /** S3 access key ID. */\n  readonly accessKeyId: string\n  /** S3 secret access key. */\n  readonly secretAccessKey: string\n  /** Bucket containing the object. */\n  readonly bucketName: string\n  /** Object key / B2 file name. */\n  readonly fileName: string\n  /** Optional URL validity duration in seconds. */\n  readonly expiresIn?: number\n  /** Optional signing clock override. */\n  readonly signingDate?: S3PresignDate\n}\n\n/**\n * Generates an AWS Signature Version 4 presigned S3-compatible request URL.\n *\n * This module owns only canonical SigV4 mechanics: canonical URI/query/header\n * construction, signing-key derivation, and signature encoding. Public B2 S3\n * option validation and naming stay in `index.ts`.\n *\n * @param method - HTTP method to presign.\n * @param options - S3 endpoint, credentials, object key, and signing options.\n * @param extraQuery - Operation-specific query parameters to sign.\n * @param extraHeaders - Operation-specific request headers to sign.\n *\n * @returns The presigned request URL.\n */\nexport async function presignS3Request(\n  method: 'GET' | 'PUT',\n  options: SigV4PresignRequestOptions,\n  extraQuery: readonly QueryParam[],\n  extraHeaders: readonly SignedHeader[],\n): Promise<string> {\n  const endpoint = parseEndpoint(options.endpoint)\n  assertHttpsEndpoint(endpoint)\n  const expiresIn = normalizeExpiresIn(options.expiresIn)\n  const { shortDate, longDate } = formatSigningDate(options.signingDate)\n  const credentialScope = `${shortDate}/${options.region}/${SERVICE}/${TERMINATOR}`\n  const credential = `${options.accessKeyId}/${credentialScope}`\n  assertSafeBucketName(options.bucketName)\n  assertValidB2FileName(options.fileName)\n  const canonicalUri = buildCanonicalUri(endpoint.pathname, options.bucketName, options.fileName)\n  const headers = normalizeSignedHeaders([['host', canonicalHostHeader(endpoint)], ...extraHeaders])\n  const signedHeaders = headers.map(([name]) => name).join(';')\n\n  const query: QueryParam[] = [\n    ['X-Amz-Algorithm', 'AWS4-HMAC-SHA256'],\n    ['X-Amz-Credential', credential],\n    ['X-Amz-Content-Sha256', UNSIGNED_PAYLOAD],\n    ['X-Amz-Date', longDate],\n    ['X-Amz-Expires', String(expiresIn)],\n    ['X-Amz-SignedHeaders', signedHeaders],\n    ...extraQuery,\n  ]\n  const canonicalQuery = canonicalQueryString(query)\n  const canonicalHeaders = headers.map(([name, value]) => `${name}:${value}\\n`).join('')\n  const canonicalRequest = [\n    method,\n    canonicalUri,\n    canonicalQuery,\n    canonicalHeaders,\n    signedHeaders,\n    UNSIGNED_PAYLOAD,\n  ].join('\\n')\n  const stringToSign = [\n    'AWS4-HMAC-SHA256',\n    longDate,\n    credentialScope,\n    await sha256Hex(canonicalRequest),\n  ].join('\\n')\n  const signingKey = await deriveSigningKey(options.secretAccessKey, shortDate, options.region)\n  const signature = hexEncode(await hmacSha256(signingKey, stringToSign))\n  const finalQuery = canonicalQueryString([...query, ['X-Amz-Signature', signature]])\n\n  return `${endpoint.origin}${canonicalUri}?${finalQuery}`\n}\n\nfunction normalizeExpiresIn(expiresIn: number | undefined): number {\n  const value = expiresIn ?? DEFAULT_PRESIGN_EXPIRES_IN\n  if (!Number.isInteger(value) || value < 1 || value > MAX_PRESIGN_EXPIRES_IN) {\n    throw new RangeError(\n      `expiresIn must be an integer from 1 to ${MAX_PRESIGN_EXPIRES_IN} seconds; received ${String(value)}.`,\n    )\n  }\n  return value\n}\n\nfunction formatSigningDate(input: S3PresignDate | undefined): {\n  readonly shortDate: string\n  readonly longDate: string\n} {\n  const date = input === undefined ? new Date() : new Date(input)\n  if (!Number.isFinite(date.getTime())) {\n    throw new RangeError('signingDate must be a valid Date or timestamp.')\n  }\n\n  const year = String(date.getUTCFullYear()).padStart(4, '0')\n  const month = String(date.getUTCMonth() + 1).padStart(2, '0')\n  const day = String(date.getUTCDate()).padStart(2, '0')\n  const hour = String(date.getUTCHours()).padStart(2, '0')\n  const minute = String(date.getUTCMinutes()).padStart(2, '0')\n  const second = String(date.getUTCSeconds()).padStart(2, '0')\n  const shortDate = `${year}${month}${day}`\n  return {\n    shortDate,\n    longDate: `${shortDate}T${hour}${minute}${second}Z`,\n  }\n}\n\nfunction buildCanonicalUri(endpointPath: string, bucketName: string, fileName: string): string {\n  const basePath =\n    endpointPath === '' || endpointPath === '/' ? '' : endpointPath.replace(/\\/+$/, '')\n  return `${basePath}/${awsPercentEncode(bucketName)}/${encodePath(fileName)}`\n}\n\nfunction canonicalHostHeader(endpoint: URL): string {\n  const host = endpoint.host\n  if (endpoint.protocol === 'https:' && host.endsWith(':443')) {\n    return host.slice(0, -4)\n  }\n  return host\n}\n\nfunction parseEndpoint(endpoint: string): URL {\n  try {\n    return new URL(endpoint)\n  } catch (cause) {\n    throw new TypeError(\n      `S3 presigned URL endpoint must be a valid URL; received \"${redactUrlForError(endpoint, {\n        invalidUrlLabel: '<invalid S3 endpoint URL>',\n      })}\".`,\n      { cause },\n    )\n  }\n}\n\nfunction assertHttpsEndpoint(endpoint: URL): void {\n  if (endpoint.protocol !== 'https:') {\n    throw new TypeError(\n      `S3 presigned URLs require an https: endpoint; received \"${redactUrlForError(endpoint)}\".`,\n    )\n  }\n}\n\nfunction encodePath(path: string): string {\n  return path.split('/').map(awsPercentEncode).join('/')\n}\n\nfunction canonicalQueryString(query: readonly QueryParam[]): string {\n  return query\n    .map(([name, value]) => [awsPercentEncode(name), awsPercentEncode(value)] as const)\n    .sort(([aName, aValue], [bName, bValue]) => {\n      if (aName < bName) return -1\n      if (aName > bName) return 1\n      if (aValue < bValue) return -1\n      if (aValue > bValue) return 1\n      return 0\n    })\n    .map(([name, value]) => `${name}=${value}`)\n    .join('&')\n}\n\n/**\n * Percent-encode according to AWS SigV4 canonical request rules.\n *\n * @param value - Raw value to encode.\n *\n * @returns AWS-compatible percent-encoded value.\n */\nfunction awsPercentEncode(value: string): string {\n  return encodeURIComponent(value).replace(\n    /[!'()*]/g,\n    (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`,\n  )\n}\n\nfunction normalizeSignedHeaders(headers: readonly SignedHeader[]): SignedHeader[] {\n  const combinedHeaders = new Map<string, string[]>()\n  for (const [name, value] of headers) {\n    const normalizedName = name.toLowerCase()\n    const values = combinedHeaders.get(normalizedName)\n    if (values) {\n      values.push(normalizeHeaderValue(value))\n    } else {\n      combinedHeaders.set(normalizedName, [normalizeHeaderValue(value)])\n    }\n  }\n\n  return [...combinedHeaders.entries()]\n    .map(([name, values]) => [name, values.join(',')] as const)\n    .sort(([a], [b]) => {\n      if (a < b) return -1\n      if (a > b) return 1\n      return 0\n    })\n}\n\nfunction normalizeHeaderValue(value: string): string {\n  if (hasHttpHeaderControlCharacter(value)) {\n    throw new TypeError('signed header values must not contain control characters.')\n  }\n\n  return value.trim().replace(/ +/g, ' ')\n}\n\nasync function deriveSigningKey(\n  secretAccessKey: string,\n  shortDate: string,\n  region: string,\n): Promise<Uint8Array> {\n  const dateKey = await hmacSha256(`AWS4${secretAccessKey}`, shortDate)\n  const dateRegionKey = await hmacSha256(dateKey, region)\n  const dateRegionServiceKey = await hmacSha256(dateRegionKey, SERVICE)\n  return await hmacSha256(dateRegionServiceKey, TERMINATOR)\n}\n"],"mappings":"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"}

package/dist/s3/validation.cjs

@@ -0,0 +1,69 @@
+const require_b2_naming = require("../internal/b2-naming.cjs");
+//#region src/s3/validation.ts
+/**
+* Validate a B2 bucket name before signing or embedding it in a URL path.
+*
+* @param bucketName - Bucket name supplied by the caller.
+*
+* @throws TypeError when the bucket name is empty, contains control characters,
+* is a dot-only path segment, contains path separators, or violates B2 bucket
+* naming rules.
+*/
+function assertSafeBucketName(bucketName) {
+	if (typeof bucketName !== "string" || bucketName.length === 0) throw new TypeError("bucketName must be a non-empty string.");
+	if (require_b2_naming.hasB2FileNameControlCharacter(bucketName)) throw new TypeError("bucketName must not contain control characters.");
+	if (bucketName === "." || bucketName === ".." || /[/\\]/.test(bucketName)) throw new TypeError("bucketName must not be \".\" or \"..\" and must not contain path separators.");
+	if (bucketName.length < 6 || bucketName.length > 63) throw new TypeError(`bucketName must be 6-63 characters.`);
+	if (require_b2_naming.isB2BucketNameIpv4Address(bucketName)) throw new TypeError("bucketName must not be formatted as an IPv4 address.");
+	if (!require_b2_naming.hasValidB2BucketNameShape(bucketName)) throw new TypeError("bucketName must contain only letters, digits, hyphens, and periods, cannot start or end with punctuation, and cannot contain consecutive periods.");
+	if (bucketName.startsWith("b2-")) throw new TypeError(`bucketName cannot start with the reserved prefix "b2-".`);
+}
+/**
+* Validate a B2-native download URL file name.
+*
+* Native download-authorization URLs use path-preserving B2 file-name encoding,
+* so this stricter guard rejects slash boundary patterns that would make the
+* URL path ambiguous in common clients.
+*
+* @param fileName - B2 file name supplied by the caller.
+*
+* @throws TypeError when the file name is not valid for the native download
+* authorization URL path.
+*/
+function assertNativeDownloadFileName(fileName) {
+	assertValidB2FileName(fileName);
+	if (fileName.startsWith("/") || fileName.endsWith("/") || fileName.includes("//")) throw new TypeError("fileName cannot start with \"/\", end with \"/\", or contain \"//\".");
+}
+/**
+* Validate a B2 file name for URL signing safety.
+*
+* This is presign-safety validation, not full native B2 file-name validation.
+* S3-compatible object keys may use leading, trailing, or repeated slash
+* patterns that native B2 download URLs reject. Native download URLs apply the
+* stricter {@link assertNativeDownloadFileName} path-boundary guard. This guard
+* only enforces size, control-character, and dot-segment constraints needed
+* before signing. Dot-only path segments are rejected because URL parsers can
+* normalize them before the request is sent.
+*
+* @param fileName - B2 file name supplied by the caller.
+*
+* @throws TypeError when the file name is empty, too large, contains control
+* characters, or contains dot-only path segments.
+*/
+function assertValidB2FileName(fileName) {
+	assertB2FileNameCore(fileName);
+	if (fileName.split("/").some((segment) => segment === "." || segment === "..")) throw new TypeError("fileName must not contain dot-only path segments because URL parsers can normalize presigned paths.");
+}
+function assertB2FileNameCore(fileName) {
+	if (typeof fileName !== "string" || fileName.length === 0) throw new TypeError("fileName must be a non-empty string.");
+	if (fileName === "." || fileName === "..") throw new TypeError("fileName cannot be exactly \".\" or \"..\".");
+	if (require_b2_naming.getB2FileNameByteLength(fileName) === null) throw new TypeError(`fileName must be at most ${require_b2_naming.FILE_NAME_MAX_BYTES} UTF-8 bytes.`);
+	if (require_b2_naming.hasB2FileNameControlCharacter(fileName)) throw new TypeError("fileName must not contain control characters (U+0000-U+001F or U+007F).");
+}
+//#endregion
+exports.FILE_NAME_MAX_BYTES = require_b2_naming.FILE_NAME_MAX_BYTES;
+exports.assertNativeDownloadFileName = assertNativeDownloadFileName;
+exports.assertSafeBucketName = assertSafeBucketName;
+exports.assertValidB2FileName = assertValidB2FileName;
+
+//# sourceMappingURL=validation.cjs.map

package/dist/s3/validation.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.cjs","names":[],"sources":["../../src/s3/validation.ts"],"sourcesContent":["import {\n  BUCKET_NAME_MAX,\n  BUCKET_NAME_MIN,\n  BUCKET_NAME_RESERVED_PREFIX,\n  FILE_NAME_MAX_BYTES,\n  getB2FileNameByteLength,\n  hasB2FileNameControlCharacter,\n  hasValidB2BucketNameShape,\n  isB2BucketNameIpv4Address,\n} from '../internal/b2-naming.ts'\n\nexport { FILE_NAME_MAX_BYTES }\n\n/**\n * Validate a B2 bucket name before signing or embedding it in a URL path.\n *\n * @param bucketName - Bucket name supplied by the caller.\n *\n * @throws TypeError when the bucket name is empty, contains control characters,\n * is a dot-only path segment, contains path separators, or violates B2 bucket\n * naming rules.\n */\nexport function assertSafeBucketName(bucketName: string): void {\n  if (typeof bucketName !== 'string' || bucketName.length === 0) {\n    throw new TypeError('bucketName must be a non-empty string.')\n  }\n  if (hasB2FileNameControlCharacter(bucketName)) {\n    throw new TypeError('bucketName must not contain control characters.')\n  }\n  if (bucketName === '.' || bucketName === '..' || /[/\\\\]/.test(bucketName)) {\n    throw new TypeError('bucketName must not be \".\" or \"..\" and must not contain path separators.')\n  }\n  if (bucketName.length < BUCKET_NAME_MIN || bucketName.length > BUCKET_NAME_MAX) {\n    throw new TypeError(`bucketName must be ${BUCKET_NAME_MIN}-${BUCKET_NAME_MAX} characters.`)\n  }\n  if (isB2BucketNameIpv4Address(bucketName)) {\n    throw new TypeError('bucketName must not be formatted as an IPv4 address.')\n  }\n  if (!hasValidB2BucketNameShape(bucketName)) {\n    throw new TypeError(\n      'bucketName must contain only letters, digits, hyphens, and periods, cannot start or end with punctuation, and cannot contain consecutive periods.',\n    )\n  }\n  if (bucketName.startsWith(BUCKET_NAME_RESERVED_PREFIX)) {\n    throw new TypeError(\n      `bucketName cannot start with the reserved prefix \"${BUCKET_NAME_RESERVED_PREFIX}\".`,\n    )\n  }\n}\n\n/**\n * Validate a B2-native download URL file name.\n *\n * Native download-authorization URLs use path-preserving B2 file-name encoding,\n * so this stricter guard rejects slash boundary patterns that would make the\n * URL path ambiguous in common clients.\n *\n * @param fileName - B2 file name supplied by the caller.\n *\n * @throws TypeError when the file name is not valid for the native download\n * authorization URL path.\n */\nexport function assertNativeDownloadFileName(fileName: string): void {\n  assertValidB2FileName(fileName)\n\n  if (fileName.startsWith('/') || fileName.endsWith('/') || fileName.includes('//')) {\n    throw new TypeError('fileName cannot start with \"/\", end with \"/\", or contain \"//\".')\n  }\n}\n\n/**\n * Validate a B2 file name for URL signing safety.\n *\n * This is presign-safety validation, not full native B2 file-name validation.\n * S3-compatible object keys may use leading, trailing, or repeated slash\n * patterns that native B2 download URLs reject. Native download URLs apply the\n * stricter {@link assertNativeDownloadFileName} path-boundary guard. This guard\n * only enforces size, control-character, and dot-segment constraints needed\n * before signing. Dot-only path segments are rejected because URL parsers can\n * normalize them before the request is sent.\n *\n * @param fileName - B2 file name supplied by the caller.\n *\n * @throws TypeError when the file name is empty, too large, contains control\n * characters, or contains dot-only path segments.\n */\nexport function assertValidB2FileName(fileName: string): void {\n  assertB2FileNameCore(fileName)\n\n  if (fileName.split('/').some((segment) => segment === '.' || segment === '..')) {\n    throw new TypeError(\n      'fileName must not contain dot-only path segments because URL parsers can normalize presigned paths.',\n    )\n  }\n}\n\nfunction assertB2FileNameCore(fileName: string): void {\n  if (typeof fileName !== 'string' || fileName.length === 0) {\n    throw new TypeError('fileName must be a non-empty string.')\n  }\n\n  if (fileName === '.' || fileName === '..') {\n    throw new TypeError('fileName cannot be exactly \".\" or \"..\".')\n  }\n\n  const byteLength = getB2FileNameByteLength(fileName)\n  if (byteLength === null) {\n    throw new TypeError(`fileName must be at most ${FILE_NAME_MAX_BYTES} UTF-8 bytes.`)\n  }\n\n  if (hasB2FileNameControlCharacter(fileName)) {\n    throw new TypeError('fileName must not contain control characters (U+0000-U+001F or U+007F).')\n  }\n}\n"],"mappings":";;;;;;;;;;;AAsBA,SAAgB,qBAAqB,YAA0B;CAC7D,IAAI,OAAO,eAAe,YAAY,WAAW,WAAW,GAC1D,MAAM,IAAI,UAAU,wCAAwC;CAE9D,IAAI,kBAAA,8BAA8B,UAAU,GAC1C,MAAM,IAAI,UAAU,iDAAiD;CAEvE,IAAI,eAAe,OAAO,eAAe,QAAQ,QAAQ,KAAK,UAAU,GACtE,MAAM,IAAI,UAAU,8EAA0E;CAEhG,IAAI,WAAW,SAAA,KAA4B,WAAW,SAAA,IACpD,MAAM,IAAI,UAAU,qCAAsE;CAE5F,IAAI,kBAAA,0BAA0B,UAAU,GACtC,MAAM,IAAI,UAAU,sDAAsD;CAE5E,IAAI,CAAC,kBAAA,0BAA0B,UAAU,GACvC,MAAM,IAAI,UACR,mJACF;CAEF,IAAI,WAAW,WAAA,KAAsC,GACnD,MAAM,IAAI,UACR,yDACF;AAEJ;;;;;;;;;;;;;AAcA,SAAgB,6BAA6B,UAAwB;CACnE,sBAAsB,QAAQ;CAE9B,IAAI,SAAS,WAAW,GAAG,KAAK,SAAS,SAAS,GAAG,KAAK,SAAS,SAAS,IAAI,GAC9E,MAAM,IAAI,UAAU,sEAAgE;AAExF;;;;;;;;;;;;;;;;;AAkBA,SAAgB,sBAAsB,UAAwB;CAC5D,qBAAqB,QAAQ;CAE7B,IAAI,SAAS,MAAM,GAAG,CAAC,CAAC,MAAM,YAAY,YAAY,OAAO,YAAY,IAAI,GAC3E,MAAM,IAAI,UACR,qGACF;AAEJ;AAEA,SAAS,qBAAqB,UAAwB;CACpD,IAAI,OAAO,aAAa,YAAY,SAAS,WAAW,GACtD,MAAM,IAAI,UAAU,sCAAsC;CAG5D,IAAI,aAAa,OAAO,aAAa,MACnC,MAAM,IAAI,UAAU,6CAAyC;CAI/D,IADmB,kBAAA,wBAAwB,QACvC,MAAe,MACjB,MAAM,IAAI,UAAU,4BAA4B,kBAAA,oBAAoB,cAAc;CAGpF,IAAI,kBAAA,8BAA8B,QAAQ,GACxC,MAAM,IAAI,UAAU,yEAAyE;AAEjG"}

package/dist/s3/validation.d.cts

@@ -0,0 +1,43 @@
+import { FILE_NAME_MAX_BYTES } from '../internal/b2-naming.js';
+export { FILE_NAME_MAX_BYTES };
+/**
+ * Validate a B2 bucket name before signing or embedding it in a URL path.
+ *
+ * @param bucketName - Bucket name supplied by the caller.
+ *
+ * @throws TypeError when the bucket name is empty, contains control characters,
+ * is a dot-only path segment, contains path separators, or violates B2 bucket
+ * naming rules.
+ */
+export declare function assertSafeBucketName(bucketName: string): void;
+/**
+ * Validate a B2-native download URL file name.
+ *
+ * Native download-authorization URLs use path-preserving B2 file-name encoding,
+ * so this stricter guard rejects slash boundary patterns that would make the
+ * URL path ambiguous in common clients.
+ *
+ * @param fileName - B2 file name supplied by the caller.
+ *
+ * @throws TypeError when the file name is not valid for the native download
+ * authorization URL path.
+ */
+export declare function assertNativeDownloadFileName(fileName: string): void;
+/**
+ * Validate a B2 file name for URL signing safety.
+ *
+ * This is presign-safety validation, not full native B2 file-name validation.
+ * S3-compatible object keys may use leading, trailing, or repeated slash
+ * patterns that native B2 download URLs reject. Native download URLs apply the
+ * stricter {@link assertNativeDownloadFileName} path-boundary guard. This guard
+ * only enforces size, control-character, and dot-segment constraints needed
+ * before signing. Dot-only path segments are rejected because URL parsers can
+ * normalize them before the request is sent.
+ *
+ * @param fileName - B2 file name supplied by the caller.
+ *
+ * @throws TypeError when the file name is empty, too large, contains control
+ * characters, or contains dot-only path segments.
+ */
+export declare function assertValidB2FileName(fileName: string): void;
+//# sourceMappingURL=validation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/s3/validation.js"],"names":[],"mappings":"AAAA,OAAO,EAIL,mBAAmB,EAKpB,MAAM,0BAA0B,CAAA;AAEjC,OAAO,EAAE,mBAAmB,EAAE,CAAA;AAE9B;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CA0B7D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAMnE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAQ5D"}

package/dist/s3/validation.d.ts

@@ -0,0 +1,43 @@
+import { FILE_NAME_MAX_BYTES } from '../internal/b2-naming.js';
+export { FILE_NAME_MAX_BYTES };
+/**
+ * Validate a B2 bucket name before signing or embedding it in a URL path.
+ *
+ * @param bucketName - Bucket name supplied by the caller.
+ *
+ * @throws TypeError when the bucket name is empty, contains control characters,
+ * is a dot-only path segment, contains path separators, or violates B2 bucket
+ * naming rules.
+ */
+export declare function assertSafeBucketName(bucketName: string): void;
+/**
+ * Validate a B2-native download URL file name.
+ *
+ * Native download-authorization URLs use path-preserving B2 file-name encoding,
+ * so this stricter guard rejects slash boundary patterns that would make the
+ * URL path ambiguous in common clients.
+ *
+ * @param fileName - B2 file name supplied by the caller.
+ *
+ * @throws TypeError when the file name is not valid for the native download
+ * authorization URL path.
+ */
+export declare function assertNativeDownloadFileName(fileName: string): void;
+/**
+ * Validate a B2 file name for URL signing safety.
+ *
+ * This is presign-safety validation, not full native B2 file-name validation.
+ * S3-compatible object keys may use leading, trailing, or repeated slash
+ * patterns that native B2 download URLs reject. Native download URLs apply the
+ * stricter {@link assertNativeDownloadFileName} path-boundary guard. This guard
+ * only enforces size, control-character, and dot-segment constraints needed
+ * before signing. Dot-only path segments are rejected because URL parsers can
+ * normalize them before the request is sent.
+ *
+ * @param fileName - B2 file name supplied by the caller.
+ *
+ * @throws TypeError when the file name is empty, too large, contains control
+ * characters, or contains dot-only path segments.
+ */
+export declare function assertValidB2FileName(fileName: string): void;
+//# sourceMappingURL=validation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/s3/validation.js"],"names":[],"mappings":"AAAA,OAAO,EAIL,mBAAmB,EAKpB,MAAM,0BAA0B,CAAA;AAEjC,OAAO,EAAE,mBAAmB,EAAE,CAAA;AAE9B;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CA0B7D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAMnE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAQ5D"}

package/dist/s3/validation.js

@@ -0,0 +1,66 @@
+import { FILE_NAME_MAX_BYTES, getB2FileNameByteLength, hasB2FileNameControlCharacter, hasValidB2BucketNameShape, isB2BucketNameIpv4Address } from "../internal/b2-naming.js";
+//#region src/s3/validation.ts
+/**
+* Validate a B2 bucket name before signing or embedding it in a URL path.
+*
+* @param bucketName - Bucket name supplied by the caller.
+*
+* @throws TypeError when the bucket name is empty, contains control characters,
+* is a dot-only path segment, contains path separators, or violates B2 bucket
+* naming rules.
+*/
+function assertSafeBucketName(bucketName) {
+	if (typeof bucketName !== "string" || bucketName.length === 0) throw new TypeError("bucketName must be a non-empty string.");
+	if (hasB2FileNameControlCharacter(bucketName)) throw new TypeError("bucketName must not contain control characters.");
+	if (bucketName === "." || bucketName === ".." || /[/\\]/.test(bucketName)) throw new TypeError("bucketName must not be \".\" or \"..\" and must not contain path separators.");
+	if (bucketName.length < 6 || bucketName.length > 63) throw new TypeError(`bucketName must be 6-63 characters.`);
+	if (isB2BucketNameIpv4Address(bucketName)) throw new TypeError("bucketName must not be formatted as an IPv4 address.");
+	if (!hasValidB2BucketNameShape(bucketName)) throw new TypeError("bucketName must contain only letters, digits, hyphens, and periods, cannot start or end with punctuation, and cannot contain consecutive periods.");
+	if (bucketName.startsWith("b2-")) throw new TypeError(`bucketName cannot start with the reserved prefix "b2-".`);
+}
+/**
+* Validate a B2-native download URL file name.
+*
+* Native download-authorization URLs use path-preserving B2 file-name encoding,
+* so this stricter guard rejects slash boundary patterns that would make the
+* URL path ambiguous in common clients.
+*
+* @param fileName - B2 file name supplied by the caller.
+*
+* @throws TypeError when the file name is not valid for the native download
+* authorization URL path.
+*/
+function assertNativeDownloadFileName(fileName) {
+	assertValidB2FileName(fileName);
+	if (fileName.startsWith("/") || fileName.endsWith("/") || fileName.includes("//")) throw new TypeError("fileName cannot start with \"/\", end with \"/\", or contain \"//\".");
+}
+/**
+* Validate a B2 file name for URL signing safety.
+*
+* This is presign-safety validation, not full native B2 file-name validation.
+* S3-compatible object keys may use leading, trailing, or repeated slash
+* patterns that native B2 download URLs reject. Native download URLs apply the
+* stricter {@link assertNativeDownloadFileName} path-boundary guard. This guard
+* only enforces size, control-character, and dot-segment constraints needed
+* before signing. Dot-only path segments are rejected because URL parsers can
+* normalize them before the request is sent.
+*
+* @param fileName - B2 file name supplied by the caller.
+*
+* @throws TypeError when the file name is empty, too large, contains control
+* characters, or contains dot-only path segments.
+*/
+function assertValidB2FileName(fileName) {
+	assertB2FileNameCore(fileName);
+	if (fileName.split("/").some((segment) => segment === "." || segment === "..")) throw new TypeError("fileName must not contain dot-only path segments because URL parsers can normalize presigned paths.");
+}
+function assertB2FileNameCore(fileName) {
+	if (typeof fileName !== "string" || fileName.length === 0) throw new TypeError("fileName must be a non-empty string.");
+	if (fileName === "." || fileName === "..") throw new TypeError("fileName cannot be exactly \".\" or \"..\".");
+	if (getB2FileNameByteLength(fileName) === null) throw new TypeError(`fileName must be at most ${FILE_NAME_MAX_BYTES} UTF-8 bytes.`);
+	if (hasB2FileNameControlCharacter(fileName)) throw new TypeError("fileName must not contain control characters (U+0000-U+001F or U+007F).");
+}
+//#endregion
+export { FILE_NAME_MAX_BYTES, assertNativeDownloadFileName, assertSafeBucketName, assertValidB2FileName };
+
+//# sourceMappingURL=validation.js.map

package/dist/s3/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","names":[],"sources":["../../src/s3/validation.ts"],"sourcesContent":["import {\n  BUCKET_NAME_MAX,\n  BUCKET_NAME_MIN,\n  BUCKET_NAME_RESERVED_PREFIX,\n  FILE_NAME_MAX_BYTES,\n  getB2FileNameByteLength,\n  hasB2FileNameControlCharacter,\n  hasValidB2BucketNameShape,\n  isB2BucketNameIpv4Address,\n} from '../internal/b2-naming.ts'\n\nexport { FILE_NAME_MAX_BYTES }\n\n/**\n * Validate a B2 bucket name before signing or embedding it in a URL path.\n *\n * @param bucketName - Bucket name supplied by the caller.\n *\n * @throws TypeError when the bucket name is empty, contains control characters,\n * is a dot-only path segment, contains path separators, or violates B2 bucket\n * naming rules.\n */\nexport function assertSafeBucketName(bucketName: string): void {\n  if (typeof bucketName !== 'string' || bucketName.length === 0) {\n    throw new TypeError('bucketName must be a non-empty string.')\n  }\n  if (hasB2FileNameControlCharacter(bucketName)) {\n    throw new TypeError('bucketName must not contain control characters.')\n  }\n  if (bucketName === '.' || bucketName === '..' || /[/\\\\]/.test(bucketName)) {\n    throw new TypeError('bucketName must not be \".\" or \"..\" and must not contain path separators.')\n  }\n  if (bucketName.length < BUCKET_NAME_MIN || bucketName.length > BUCKET_NAME_MAX) {\n    throw new TypeError(`bucketName must be ${BUCKET_NAME_MIN}-${BUCKET_NAME_MAX} characters.`)\n  }\n  if (isB2BucketNameIpv4Address(bucketName)) {\n    throw new TypeError('bucketName must not be formatted as an IPv4 address.')\n  }\n  if (!hasValidB2BucketNameShape(bucketName)) {\n    throw new TypeError(\n      'bucketName must contain only letters, digits, hyphens, and periods, cannot start or end with punctuation, and cannot contain consecutive periods.',\n    )\n  }\n  if (bucketName.startsWith(BUCKET_NAME_RESERVED_PREFIX)) {\n    throw new TypeError(\n      `bucketName cannot start with the reserved prefix \"${BUCKET_NAME_RESERVED_PREFIX}\".`,\n    )\n  }\n}\n\n/**\n * Validate a B2-native download URL file name.\n *\n * Native download-authorization URLs use path-preserving B2 file-name encoding,\n * so this stricter guard rejects slash boundary patterns that would make the\n * URL path ambiguous in common clients.\n *\n * @param fileName - B2 file name supplied by the caller.\n *\n * @throws TypeError when the file name is not valid for the native download\n * authorization URL path.\n */\nexport function assertNativeDownloadFileName(fileName: string): void {\n  assertValidB2FileName(fileName)\n\n  if (fileName.startsWith('/') || fileName.endsWith('/') || fileName.includes('//')) {\n    throw new TypeError('fileName cannot start with \"/\", end with \"/\", or contain \"//\".')\n  }\n}\n\n/**\n * Validate a B2 file name for URL signing safety.\n *\n * This is presign-safety validation, not full native B2 file-name validation.\n * S3-compatible object keys may use leading, trailing, or repeated slash\n * patterns that native B2 download URLs reject. Native download URLs apply the\n * stricter {@link assertNativeDownloadFileName} path-boundary guard. This guard\n * only enforces size, control-character, and dot-segment constraints needed\n * before signing. Dot-only path segments are rejected because URL parsers can\n * normalize them before the request is sent.\n *\n * @param fileName - B2 file name supplied by the caller.\n *\n * @throws TypeError when the file name is empty, too large, contains control\n * characters, or contains dot-only path segments.\n */\nexport function assertValidB2FileName(fileName: string): void {\n  assertB2FileNameCore(fileName)\n\n  if (fileName.split('/').some((segment) => segment === '.' || segment === '..')) {\n    throw new TypeError(\n      'fileName must not contain dot-only path segments because URL parsers can normalize presigned paths.',\n    )\n  }\n}\n\nfunction assertB2FileNameCore(fileName: string): void {\n  if (typeof fileName !== 'string' || fileName.length === 0) {\n    throw new TypeError('fileName must be a non-empty string.')\n  }\n\n  if (fileName === '.' || fileName === '..') {\n    throw new TypeError('fileName cannot be exactly \".\" or \"..\".')\n  }\n\n  const byteLength = getB2FileNameByteLength(fileName)\n  if (byteLength === null) {\n    throw new TypeError(`fileName must be at most ${FILE_NAME_MAX_BYTES} UTF-8 bytes.`)\n  }\n\n  if (hasB2FileNameControlCharacter(fileName)) {\n    throw new TypeError('fileName must not contain control characters (U+0000-U+001F or U+007F).')\n  }\n}\n"],"mappings":";;;;;;;;;;;AAsBA,SAAgB,qBAAqB,YAA0B;CAC7D,IAAI,OAAO,eAAe,YAAY,WAAW,WAAW,GAC1D,MAAM,IAAI,UAAU,wCAAwC;CAE9D,IAAI,8BAA8B,UAAU,GAC1C,MAAM,IAAI,UAAU,iDAAiD;CAEvE,IAAI,eAAe,OAAO,eAAe,QAAQ,QAAQ,KAAK,UAAU,GACtE,MAAM,IAAI,UAAU,8EAA0E;CAEhG,IAAI,WAAW,SAAA,KAA4B,WAAW,SAAA,IACpD,MAAM,IAAI,UAAU,qCAAsE;CAE5F,IAAI,0BAA0B,UAAU,GACtC,MAAM,IAAI,UAAU,sDAAsD;CAE5E,IAAI,CAAC,0BAA0B,UAAU,GACvC,MAAM,IAAI,UACR,mJACF;CAEF,IAAI,WAAW,WAAA,KAAsC,GACnD,MAAM,IAAI,UACR,yDACF;AAEJ;;;;;;;;;;;;;AAcA,SAAgB,6BAA6B,UAAwB;CACnE,sBAAsB,QAAQ;CAE9B,IAAI,SAAS,WAAW,GAAG,KAAK,SAAS,SAAS,GAAG,KAAK,SAAS,SAAS,IAAI,GAC9E,MAAM,IAAI,UAAU,sEAAgE;AAExF;;;;;;;;;;;;;;;;;AAkBA,SAAgB,sBAAsB,UAAwB;CAC5D,qBAAqB,QAAQ;CAE7B,IAAI,SAAS,MAAM,GAAG,CAAC,CAAC,MAAM,YAAY,YAAY,OAAO,YAAY,IAAI,GAC3E,MAAM,IAAI,UACR,qGACF;AAEJ;AAEA,SAAS,qBAAqB,UAAwB;CACpD,IAAI,OAAO,aAAa,YAAY,SAAS,WAAW,GACtD,MAAM,IAAI,UAAU,sCAAsC;CAG5D,IAAI,aAAa,OAAO,aAAa,MACnC,MAAM,IAAI,UAAU,6CAAyC;CAI/D,IADmB,wBAAwB,QACvC,MAAe,MACjB,MAAM,IAAI,UAAU,4BAA4B,oBAAoB,cAAc;CAGpF,IAAI,8BAA8B,QAAQ,GACxC,MAAM,IAAI,UAAU,yEAAyE;AAEjG"}