@backblaze-labs/b2-sdk 0.2.0 → 0.4.0

package/dist/partner/redaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.d.ts","sourceRoot":"","sources":["../../src/partner/redaction.js"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,yBAAyB,EACzB,uBAAuB,EAEvB,wBAAwB,EAKxB,iCAAiC,EACjC,+BAA+B,EAChC,MAAM,qBAAqB,CAAA;AAG5B,OAAO,EACL,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,6BAA6B,CAAA;AAEpC;;;GAGG;AACH,MAAM,WAAW,oCACf,SAAQ,IAAI,CAAC,wBAAwB,EAAE,oBAAoB,CAAC;IAC5D,wDAAwD;IACxD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;CACpC;AAED;;;;;GAKG;AACH,MAAM,MAAM,mCAAmC,GAAG,IAAI,CACpD,uBAAuB,EACvB,gBAAgB,CACjB,GAAG;IACF,mDAAmD;IACnD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAChC,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,qCAAqC,GAAG,mCAAmC,CAAA;AAEvF;;;;;GAKG;AACH,MAAM,MAAM,2CAA2C,GAAG,IAAI,CAC5D,+BAA+B,EAC/B,gBAAgB,CACjB,GAAG;IACF,mDAAmD;IACnD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAChC,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,6CAA6C,GACvD,2CAA2C,CAAA;AAiK7C;;;;;;GAMG;AACH,wBAAgB,sCAAsC,CACpD,IAAI,EAAE,wBAAwB,GAC7B,oCAAoC,CAgBtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,qCAAqC,CACnD,MAAM,EAAE,uBAAuB,GAC9B,mCAAmC,CAMrC;AAED;;;;;;;;GAQG;AACH,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,yBAAyB,GAClC,qCAAqC,CAEvC;AAED;;;;;;;;GAQG;AACH,wBAAgB,6CAA6C,CAC3D,MAAM,EAAE,+BAA+B,GACtC,2CAA2C,CAY7C;AAED;;;;;;;;GAQG;AACH,wBAAgB,+CAA+C,CAC7D,QAAQ,EAAE,iCAAiC,GAC1C,6CAA6C,CAE/C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,wBAAwB,GAC7B,wBAAwB,CAqB1B;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,uBAAuB,GAC9B,uBAAuB,CAMzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,yBAAyB,GAClC,yBAAyB,CAiB3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qCAAqC,CACnD,MAAM,EAAE,+BAA+B,GACtC,+BAA+B,CAMjC;AAED;;;;;;;;;GASG;AACH,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,iCAAiC,GAC1C,iCAAiC,CAiBnC"}

package/dist/partner/redaction.js

@@ -0,0 +1,281 @@
+import { B2PartnerAuthorizationError } from "../errors/index.js";
+import { APPLICATION_KEY_REDACTED, PARTNER_TOKEN_REDACTED } from "./redaction-placeholders.js";
+//#region src/partner/redaction.ts
+var inspectSymbol = Symbol.for("nodejs.util.inspect.custom");
+function partnerGroupsApiInfoToRedactedJson(info) {
+	return {
+		capabilities: [...info.capabilities],
+		groupsApiUrl: info.groupsApiUrl,
+		infoType: info.infoType
+	};
+}
+function partnerBackupApiInfoToRedactedJson(info) {
+	return {
+		capabilities: [...info.capabilities],
+		backupApiUrl: info.backupApiUrl,
+		infoType: info.infoType
+	};
+}
+function partnerStorageApiInfoToRedactedJson(info) {
+	return {
+		absoluteMinimumPartSize: info.absoluteMinimumPartSize,
+		apiUrl: info.apiUrl,
+		bucketId: info.bucketId,
+		bucketName: info.bucketName,
+		capabilities: [...info.capabilities],
+		downloadUrl: info.downloadUrl,
+		infoType: info.infoType,
+		namePrefix: info.namePrefix,
+		recommendedPartSize: info.recommendedPartSize,
+		s3ApiUrl: info.s3ApiUrl
+	};
+}
+function partnerApiInfoToRedactedJson(apiInfo) {
+	const redacted = {};
+	if (apiInfo.storageApi !== void 0) redacted.storageApi = partnerStorageApiInfoToRedactedJson(apiInfo.storageApi);
+	if (apiInfo.groupsApi !== void 0) redacted.groupsApi = partnerGroupsApiInfoToRedactedJson(apiInfo.groupsApi);
+	if (apiInfo.backupApi !== void 0) redacted.backupApi = partnerBackupApiInfoToRedactedJson(apiInfo.backupApi);
+	return redacted;
+}
+function partnerGroupMemberToRedactedJson(groupMember) {
+	return {
+		accountId: groupMember.accountId,
+		email: groupMember.email,
+		groupId: groupMember.groupId,
+		groupName: groupMember.groupName,
+		region: groupMember.region,
+		s3Endpoint: groupMember.s3Endpoint
+	};
+}
+function isSingleJsonObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isCredentialBearing(response) {
+	return isSingleJsonObject(response) && typeof response["applicationKey"] === "string" && typeof response["applicationKeyId"] === "string";
+}
+function matchesGroupMemberShape(groupMember) {
+	return isSingleJsonObject(groupMember) && typeof groupMember["accountId"] === "string" && typeof groupMember["email"] === "string" && typeof groupMember["groupId"] === "string" && typeof groupMember["groupName"] === "string" && typeof groupMember["region"] === "string" && typeof groupMember["s3Endpoint"] === "string";
+}
+function matchesReserveTrialAccountShape(response) {
+	return typeof response.accountId === "string" && typeof response.s3Endpoint === "string" && typeof response.startDate === "string" && typeof response.endDate === "string" && typeof response.email === "string" && typeof response.bucketName === "string" && typeof response.bucketId === "string";
+}
+function redactApplicationKeyShallow(target) {
+	return {
+		...target,
+		applicationKey: APPLICATION_KEY_REDACTED
+	};
+}
+function installPortableJsonHook(target, toJson) {
+	const originalPrototype = Object.getPrototypeOf(target);
+	const redactionPrototype = Object.create(originalPrototype);
+	Object.defineProperty(redactionPrototype, "toJSON", {
+		value: toJson,
+		enumerable: false,
+		configurable: true
+	});
+	Object.setPrototypeOf(target, redactionPrototype);
+	Object.defineProperty(target, "toJSON", {
+		value: toJson,
+		enumerable: false,
+		configurable: true
+	});
+}
+function redactWithHooks(value, toRedactedJsonForTarget, toRedactedString) {
+	const target = Object.isExtensible(value) ? value : { ...value };
+	const toRedactedJson = () => toRedactedJsonForTarget(target);
+	installPortableJsonHook(target, toRedactedJson);
+	Object.defineProperties(target, {
+		toString: {
+			value: toRedactedString,
+			enumerable: false,
+			configurable: true
+		},
+		[inspectSymbol]: {
+			value: toRedactedJson,
+			enumerable: false,
+			configurable: true
+		}
+	});
+	return target;
+}
+/**
+* Returns a redacted copy for log serializers that intentionally hide tokens.
+*
+* @param auth - Partner authorization response to render safely.
+*
+* @returns A plain object with the Partner token replaced by a placeholder.
+*/
+function partnerAuthorizeResponseToRedactedJson(auth) {
+	const redacted = {
+		accountId: auth.accountId,
+		authorizationToken: PARTNER_TOKEN_REDACTED,
+		apiInfo: partnerApiInfoToRedactedJson(auth.apiInfo),
+		applicationKeyExpirationTimestamp: auth.applicationKeyExpirationTimestamp
+	};
+	if (auth.groupsApiUrl !== void 0) redacted.groupsApiUrl = auth.groupsApiUrl;
+	if (auth.backupApiUrl !== void 0) redacted.backupApiUrl = auth.backupApiUrl;
+	if (auth.groupsCapabilities !== void 0) redacted.groupsCapabilities = [...auth.groupsCapabilities];
+	if (auth.backupCapabilities !== void 0) redacted.backupCapabilities = [...auth.backupCapabilities];
+	return redacted;
+}
+/**
+* Returns a redacted copy for log serializers that intentionally hide group-member keys.
+*
+* @param result - Create group member result to render safely.
+*
+* @returns A plain object with the application key secret replaced by a placeholder.
+*
+* @experimental Partner API surface; shape may change as the Partner API docs evolve.
+*/
+function createGroupMemberResultToRedactedJson(result) {
+	return {
+		applicationKeyId: result.applicationKeyId,
+		applicationKey: APPLICATION_KEY_REDACTED,
+		groupMember: partnerGroupMemberToRedactedJson(result.groupMember)
+	};
+}
+/**
+* Returns a redacted copy for log serializers that intentionally hide group-member keys.
+*
+* @param response - Create group member response to render safely.
+*
+* @returns A plain object with the application key secret replaced by a placeholder.
+*
+* @experimental Partner API surface; shape may change as the Partner API docs evolve.
+*/
+function createGroupMemberResponseToRedactedJson(response) {
+	return createGroupMemberResultToRedactedJson(response);
+}
+/**
+* Returns a redacted copy for log serializers that intentionally hide trial account keys.
+*
+* @param result - Reserve trial account result to render safely.
+*
+* @returns A plain object with the application key secret replaced by a placeholder.
+*
+* @experimental Partner API surface; shape may change as the Partner API docs evolve.
+*/
+function reserveTrialCreateAccountResultToRedactedJson(result) {
+	return {
+		accountId: result.accountId,
+		applicationKey: APPLICATION_KEY_REDACTED,
+		applicationKeyId: result.applicationKeyId,
+		s3Endpoint: result.s3Endpoint,
+		startDate: result.startDate,
+		endDate: result.endDate,
+		email: result.email,
+		bucketName: result.bucketName,
+		bucketId: result.bucketId
+	};
+}
+/**
+* Returns a redacted copy for log serializers that intentionally hide trial account keys.
+*
+* @param response - Reserve trial account response to render safely.
+*
+* @returns A plain object with the application key secret replaced by a placeholder.
+*
+* @experimental Partner API surface; shape may change as the Partner API docs evolve.
+*/
+function reserveTrialCreateAccountResponseToRedactedJson(response) {
+	return reserveTrialCreateAccountResultToRedactedJson(response);
+}
+/**
+* Adds non-enumerable serialization and inspection hooks that redact the
+* Partner token through `JSON.stringify`, `toString`, and Node `util.inspect`
+* while preserving direct property access.
+*
+* `JSON.stringify` no longer round-trips `authorizationToken` from protected
+* authorize responses. Persist trusted auth caches with
+* `partnerAuthorizeResponseForPersistence(auth)` only into encrypted or
+* otherwise credential-grade storage, or read `authorizationToken` directly
+* into secure storage before serializing.
+*
+* This does not make the object universally log-safe: object spread,
+* `Object.assign`, `Object.entries`, `structuredClone`, and serializers that
+* walk enumerable properties can still expose the raw token.
+*
+* @param auth - Partner authorization response to protect from accidental inspection.
+*
+* @returns The same auth object with inspection hooks installed when possible.
+*/
+function redactPartnerAuthorizeResponse(auth) {
+	const target = Object.isExtensible(auth) ? auth : { ...auth };
+	const toRedactedJson = () => partnerAuthorizeResponseToRedactedJson(target);
+	const toRedactedString = () => `[PartnerAuthorizeResponse ${PARTNER_TOKEN_REDACTED}]`;
+	installPortableJsonHook(target, toRedactedJson);
+	Object.defineProperties(target, {
+		toString: {
+			value: toRedactedString,
+			enumerable: false,
+			configurable: true
+		},
+		[inspectSymbol]: {
+			value: toRedactedJson,
+			enumerable: false,
+			configurable: true
+		}
+	});
+	return target;
+}
+/**
+* Adds non-enumerable serialization and inspection hooks that redact the
+* application key secret while preserving direct property access.
+*
+* @param result - Create group member result to protect from accidental logging.
+*
+* @returns The same result object with redaction hooks installed when possible.
+*/
+function redactCreateGroupMemberResult(result) {
+	return redactWithHooks(result, createGroupMemberResultToRedactedJson, () => `[CreateGroupMemberResult ${APPLICATION_KEY_REDACTED}]`);
+}
+/**
+* Adds non-enumerable serialization and inspection hooks that redact the
+* create-group-member application key secret while preserving direct access.
+*
+* @param response - Create group member response to protect from accidental logging.
+*
+* @returns The same response object with redaction hooks installed when possible.
+*
+* @throws B2PartnerAuthorizationError if the response carries no usable application key.
+*/
+function redactCreateGroupMemberResponse(response) {
+	if (!isCredentialBearing(response)) throw new B2PartnerAuthorizationError("b2_create_group_member response did not contain a usable application key");
+	if (matchesGroupMemberShape(response.groupMember)) return redactCreateGroupMemberResult(response);
+	return redactWithHooks(response, redactApplicationKeyShallow, () => `[CreateGroupMemberResponse ${APPLICATION_KEY_REDACTED}]`);
+}
+/**
+* Adds non-enumerable serialization and inspection hooks that redact the
+* application key secret while preserving direct property access.
+*
+* `JSON.stringify` redacts because the response contains newly minted
+* application key secrets that are commonly logged with responses. Callers
+* that need to persist the key should read `applicationKey` directly into
+* secure storage before serializing the object.
+*
+* @param result - Reserve trial account result to protect from accidental logging.
+*
+* @returns The same result object with redaction hooks installed when possible.
+*/
+function redactReserveTrialCreateAccountResult(result) {
+	return redactWithHooks(result, reserveTrialCreateAccountResultToRedactedJson, () => `[ReserveTrialCreateAccountResult ${APPLICATION_KEY_REDACTED}]`);
+}
+/**
+* Adds non-enumerable serialization and inspection hooks that redact the
+* reserve-trial application key secret while preserving direct property access.
+*
+* @param response - Reserve trial account response to protect from accidental logging.
+*
+* @returns The same response object with redaction hooks installed when possible.
+*
+* @throws B2PartnerAuthorizationError if the response carries no usable application key.
+*/
+function redactReserveTrialCreateAccountResponse(response) {
+	if (!isCredentialBearing(response)) throw new B2PartnerAuthorizationError("b2_reserve_trial_create_account response did not contain a usable application key");
+	if (matchesReserveTrialAccountShape(response)) return redactReserveTrialCreateAccountResult(response);
+	return redactWithHooks(response, redactApplicationKeyShallow, () => `[ReserveTrialCreateAccountResponse ${APPLICATION_KEY_REDACTED}]`);
+}
+//#endregion
+export { APPLICATION_KEY_REDACTED, PARTNER_TOKEN_REDACTED, createGroupMemberResponseToRedactedJson, createGroupMemberResultToRedactedJson, partnerAuthorizeResponseToRedactedJson, redactCreateGroupMemberResponse, redactCreateGroupMemberResult, redactPartnerAuthorizeResponse, redactReserveTrialCreateAccountResponse, redactReserveTrialCreateAccountResult, reserveTrialCreateAccountResponseToRedactedJson, reserveTrialCreateAccountResultToRedactedJson };
+
+//# sourceMappingURL=redaction.js.map

package/dist/partner/redaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.js","names":[],"sources":["../../src/partner/redaction.ts"],"sourcesContent":["import { B2PartnerAuthorizationError } from '../errors/index.ts'\nimport type {\n  CreateGroupMemberResponse,\n  CreateGroupMemberResult,\n  PartnerApiInfo,\n  PartnerAuthorizeResponse,\n  PartnerBackupApiInfo,\n  PartnerGroupMember,\n  PartnerGroupsApiInfo,\n  PartnerStorageApiInfo,\n  ReserveTrialCreateAccountResponse,\n  ReserveTrialCreateAccountResult,\n} from '../types/partner.ts'\nimport { APPLICATION_KEY_REDACTED, PARTNER_TOKEN_REDACTED } from './redaction-placeholders.ts'\n\nexport {\n  APPLICATION_KEY_REDACTED,\n  PARTNER_TOKEN_REDACTED,\n} from './redaction-placeholders.ts'\n\n/**\n * JSON-safe Partner authorize response with the Partner token replaced by a\n * placeholder string.\n */\nexport interface RedactedPartnerAuthorizeResponseJson\n  extends Omit<PartnerAuthorizeResponse, 'authorizationToken'> {\n  /** Redacted Partner authorization token placeholder. */\n  readonly authorizationToken: string\n}\n\n/**\n * JSON-safe create-group-member result with the one-time application key\n * secret replaced by a placeholder string.\n *\n * @experimental Partner API surface; shape may change as the Partner API docs evolve.\n */\nexport type RedactedCreateGroupMemberResultJson = Omit<\n  CreateGroupMemberResult,\n  'applicationKey'\n> & {\n  /** Redacted application key secret placeholder. */\n  readonly applicationKey: string\n}\n\n/**\n * JSON-safe create-group-member response with the one-time application key\n * secret replaced by a placeholder string.\n *\n * @experimental Partner API surface; shape may change as the Partner API docs evolve.\n */\nexport type RedactedCreateGroupMemberResponseJson = RedactedCreateGroupMemberResultJson\n\n/**\n * JSON-safe reserve-trial account result with the one-time application key\n * secret replaced by a placeholder string.\n *\n * @experimental Partner API surface; shape may change as the Partner API docs evolve.\n */\nexport type RedactedReserveTrialCreateAccountResultJson = Omit<\n  ReserveTrialCreateAccountResult,\n  'applicationKey'\n> & {\n  /** Redacted application key secret placeholder. */\n  readonly applicationKey: string\n}\n\n/**\n * JSON-safe reserve-trial account response with the one-time application key\n * secret replaced by a placeholder string.\n *\n * @experimental Partner API surface; shape may change as the Partner API docs evolve.\n */\nexport type RedactedReserveTrialCreateAccountResponseJson =\n  RedactedReserveTrialCreateAccountResultJson\n\nconst inspectSymbol = Symbol.for('nodejs.util.inspect.custom')\n\ntype Writable<T> = { -readonly [K in keyof T]: T[K] }\n\nfunction partnerGroupsApiInfoToRedactedJson(info: PartnerGroupsApiInfo): PartnerGroupsApiInfo {\n  return {\n    capabilities: [...info.capabilities],\n    groupsApiUrl: info.groupsApiUrl,\n    infoType: info.infoType,\n  }\n}\n\nfunction partnerBackupApiInfoToRedactedJson(info: PartnerBackupApiInfo): PartnerBackupApiInfo {\n  return {\n    capabilities: [...info.capabilities],\n    backupApiUrl: info.backupApiUrl,\n    infoType: info.infoType,\n  }\n}\n\nfunction partnerStorageApiInfoToRedactedJson(info: PartnerStorageApiInfo): PartnerStorageApiInfo {\n  return {\n    absoluteMinimumPartSize: info.absoluteMinimumPartSize,\n    apiUrl: info.apiUrl,\n    bucketId: info.bucketId,\n    bucketName: info.bucketName,\n    capabilities: [...info.capabilities],\n    downloadUrl: info.downloadUrl,\n    infoType: info.infoType,\n    namePrefix: info.namePrefix,\n    recommendedPartSize: info.recommendedPartSize,\n    s3ApiUrl: info.s3ApiUrl,\n  }\n}\n\nfunction partnerApiInfoToRedactedJson(apiInfo: PartnerApiInfo): PartnerApiInfo {\n  const redacted: Writable<PartnerApiInfo> = {}\n  if (apiInfo.storageApi !== undefined) {\n    redacted.storageApi = partnerStorageApiInfoToRedactedJson(apiInfo.storageApi)\n  }\n  if (apiInfo.groupsApi !== undefined) {\n    redacted.groupsApi = partnerGroupsApiInfoToRedactedJson(apiInfo.groupsApi)\n  }\n  if (apiInfo.backupApi !== undefined) {\n    redacted.backupApi = partnerBackupApiInfoToRedactedJson(apiInfo.backupApi)\n  }\n  return redacted\n}\n\nfunction partnerGroupMemberToRedactedJson(groupMember: PartnerGroupMember): PartnerGroupMember {\n  return {\n    accountId: groupMember.accountId,\n    email: groupMember.email,\n    groupId: groupMember.groupId,\n    groupName: groupMember.groupName,\n    region: groupMember.region,\n    s3Endpoint: groupMember.s3Endpoint,\n  }\n}\n\nfunction isSingleJsonObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value)\n}\n\n// The one invariant a create/reserve redaction wrapper must never violate: a\n// usable one-time credential must survive. B2 mints the application key exactly\n// once, after the (non-deletable) account already exists, so throwing the\n// response away over an unexpected *non-credential* field would destroy an\n// unrecoverable secret — the core hazard of #280. We hard-fail only when there\n// is no usable credential to preserve (nothing is lost in that case).\nfunction isCredentialBearing(\n  response: unknown,\n): response is { applicationKey: string; applicationKeyId: string } {\n  return (\n    isSingleJsonObject(response) &&\n    typeof response['applicationKey'] === 'string' &&\n    typeof response['applicationKeyId'] === 'string'\n  )\n}\n\n// True when `groupMember` matches every documented field type, so the\n// field-specific (allowlist) redaction copies the full shape without dropping\n// unexpected fields. A partial/variant object falls back to shallow redaction.\nfunction matchesGroupMemberShape(groupMember: unknown): groupMember is PartnerGroupMember {\n  return (\n    isSingleJsonObject(groupMember) &&\n    typeof groupMember['accountId'] === 'string' &&\n    typeof groupMember['email'] === 'string' &&\n    typeof groupMember['groupId'] === 'string' &&\n    typeof groupMember['groupName'] === 'string' &&\n    typeof groupMember['region'] === 'string' &&\n    typeof groupMember['s3Endpoint'] === 'string'\n  )\n}\n\n// True when the reserve-trial response also matches every documented\n// non-credential field, so the field-specific (allowlist) redaction is exact.\nfunction matchesReserveTrialAccountShape(response: ReserveTrialCreateAccountResponse): boolean {\n  return (\n    typeof response.accountId === 'string' &&\n    typeof response.s3Endpoint === 'string' &&\n    typeof response.startDate === 'string' &&\n    typeof response.endDate === 'string' &&\n    typeof response.email === 'string' &&\n    typeof response.bucketName === 'string' &&\n    typeof response.bucketId === 'string'\n  )\n}\n\n// Redaction hook for a credential-bearing response whose surrounding shape is\n// unexpected: shallow-copy every field the server sent and redact only the\n// one-time secret, so the response is never discarded and never logs the key.\nfunction redactApplicationKeyShallow<T extends object>(target: T): unknown {\n  return { ...target, applicationKey: APPLICATION_KEY_REDACTED }\n}\n\n// Bun/WebKit only honor object toJSON hooks when they are inherited, while Node\n// honors own hooks. Install both shapes so SDK safe serialization is portable.\nfunction installPortableJsonHook<T extends object>(target: T, toJson: () => unknown): void {\n  const originalPrototype = Object.getPrototypeOf(target)\n  const redactionPrototype = Object.create(originalPrototype) as object\n  Object.defineProperty(redactionPrototype, 'toJSON', {\n    value: toJson,\n    enumerable: false,\n    configurable: true,\n  })\n  Object.setPrototypeOf(target, redactionPrototype)\n  Object.defineProperty(target, 'toJSON', {\n    value: toJson,\n    enumerable: false,\n    configurable: true,\n  })\n}\n\nfunction redactWithHooks<T extends object>(\n  value: T,\n  toRedactedJsonForTarget: (target: T) => unknown,\n  toRedactedString: () => string,\n): T {\n  const target = Object.isExtensible(value) ? value : ({ ...value } as T)\n  const toRedactedJson = (): unknown => toRedactedJsonForTarget(target)\n\n  installPortableJsonHook(target, toRedactedJson)\n  Object.defineProperties(target, {\n    toString: {\n      value: toRedactedString,\n      enumerable: false,\n      configurable: true,\n    },\n    [inspectSymbol]: {\n      value: toRedactedJson,\n      enumerable: false,\n      configurable: true,\n    },\n  })\n\n  return target\n}\n\n/**\n * Returns a redacted copy for log serializers that intentionally hide tokens.\n *\n * @param auth - Partner authorization response to render safely.\n *\n * @returns A plain object with the Partner token replaced by a placeholder.\n */\nexport function partnerAuthorizeResponseToRedactedJson(\n  auth: PartnerAuthorizeResponse,\n): RedactedPartnerAuthorizeResponseJson {\n  const redacted: Writable<RedactedPartnerAuthorizeResponseJson> = {\n    accountId: auth.accountId,\n    authorizationToken: PARTNER_TOKEN_REDACTED,\n    apiInfo: partnerApiInfoToRedactedJson(auth.apiInfo),\n    applicationKeyExpirationTimestamp: auth.applicationKeyExpirationTimestamp,\n  }\n  if (auth.groupsApiUrl !== undefined) redacted.groupsApiUrl = auth.groupsApiUrl\n  if (auth.backupApiUrl !== undefined) redacted.backupApiUrl = auth.backupApiUrl\n  if (auth.groupsCapabilities !== undefined) {\n    redacted.groupsCapabilities = [...auth.groupsCapabilities]\n  }\n  if (auth.backupCapabilities !== undefined) {\n    redacted.backupCapabilities = [...auth.backupCapabilities]\n  }\n  return redacted\n}\n\n/**\n * Returns a redacted copy for log serializers that intentionally hide group-member keys.\n *\n * @param result - Create group member result to render safely.\n *\n * @returns A plain object with the application key secret replaced by a placeholder.\n *\n * @experimental Partner API surface; shape may change as the Partner API docs evolve.\n */\nexport function createGroupMemberResultToRedactedJson(\n  result: CreateGroupMemberResult,\n): RedactedCreateGroupMemberResultJson {\n  return {\n    applicationKeyId: result.applicationKeyId,\n    applicationKey: APPLICATION_KEY_REDACTED,\n    groupMember: partnerGroupMemberToRedactedJson(result.groupMember),\n  }\n}\n\n/**\n * Returns a redacted copy for log serializers that intentionally hide group-member keys.\n *\n * @param response - Create group member response to render safely.\n *\n * @returns A plain object with the application key secret replaced by a placeholder.\n *\n * @experimental Partner API surface; shape may change as the Partner API docs evolve.\n */\nexport function createGroupMemberResponseToRedactedJson(\n  response: CreateGroupMemberResponse,\n): RedactedCreateGroupMemberResponseJson {\n  return createGroupMemberResultToRedactedJson(response)\n}\n\n/**\n * Returns a redacted copy for log serializers that intentionally hide trial account keys.\n *\n * @param result - Reserve trial account result to render safely.\n *\n * @returns A plain object with the application key secret replaced by a placeholder.\n *\n * @experimental Partner API surface; shape may change as the Partner API docs evolve.\n */\nexport function reserveTrialCreateAccountResultToRedactedJson(\n  result: ReserveTrialCreateAccountResult,\n): RedactedReserveTrialCreateAccountResultJson {\n  return {\n    accountId: result.accountId,\n    applicationKey: APPLICATION_KEY_REDACTED,\n    applicationKeyId: result.applicationKeyId,\n    s3Endpoint: result.s3Endpoint,\n    startDate: result.startDate,\n    endDate: result.endDate,\n    email: result.email,\n    bucketName: result.bucketName,\n    bucketId: result.bucketId,\n  }\n}\n\n/**\n * Returns a redacted copy for log serializers that intentionally hide trial account keys.\n *\n * @param response - Reserve trial account response to render safely.\n *\n * @returns A plain object with the application key secret replaced by a placeholder.\n *\n * @experimental Partner API surface; shape may change as the Partner API docs evolve.\n */\nexport function reserveTrialCreateAccountResponseToRedactedJson(\n  response: ReserveTrialCreateAccountResponse,\n): RedactedReserveTrialCreateAccountResponseJson {\n  return reserveTrialCreateAccountResultToRedactedJson(response)\n}\n\n/**\n * Adds non-enumerable serialization and inspection hooks that redact the\n * Partner token through `JSON.stringify`, `toString`, and Node `util.inspect`\n * while preserving direct property access.\n *\n * `JSON.stringify` no longer round-trips `authorizationToken` from protected\n * authorize responses. Persist trusted auth caches with\n * `partnerAuthorizeResponseForPersistence(auth)` only into encrypted or\n * otherwise credential-grade storage, or read `authorizationToken` directly\n * into secure storage before serializing.\n *\n * This does not make the object universally log-safe: object spread,\n * `Object.assign`, `Object.entries`, `structuredClone`, and serializers that\n * walk enumerable properties can still expose the raw token.\n *\n * @param auth - Partner authorization response to protect from accidental inspection.\n *\n * @returns The same auth object with inspection hooks installed when possible.\n */\nexport function redactPartnerAuthorizeResponse(\n  auth: PartnerAuthorizeResponse,\n): PartnerAuthorizeResponse {\n  const target = Object.isExtensible(auth) ? auth : { ...auth }\n  const toRedactedJson = (): RedactedPartnerAuthorizeResponseJson =>\n    partnerAuthorizeResponseToRedactedJson(target)\n  const toRedactedString = (): string => `[PartnerAuthorizeResponse ${PARTNER_TOKEN_REDACTED}]`\n\n  installPortableJsonHook(target, toRedactedJson)\n  Object.defineProperties(target, {\n    toString: {\n      value: toRedactedString,\n      enumerable: false,\n      configurable: true,\n    },\n    [inspectSymbol]: {\n      value: toRedactedJson,\n      enumerable: false,\n      configurable: true,\n    },\n  })\n\n  return target\n}\n\n/**\n * Adds non-enumerable serialization and inspection hooks that redact the\n * application key secret while preserving direct property access.\n *\n * @param result - Create group member result to protect from accidental logging.\n *\n * @returns The same result object with redaction hooks installed when possible.\n */\nexport function redactCreateGroupMemberResult(\n  result: CreateGroupMemberResult,\n): CreateGroupMemberResult {\n  return redactWithHooks(\n    result,\n    createGroupMemberResultToRedactedJson,\n    () => `[CreateGroupMemberResult ${APPLICATION_KEY_REDACTED}]`,\n  )\n}\n\n/**\n * Adds non-enumerable serialization and inspection hooks that redact the\n * create-group-member application key secret while preserving direct access.\n *\n * @param response - Create group member response to protect from accidental logging.\n *\n * @returns The same response object with redaction hooks installed when possible.\n *\n * @throws B2PartnerAuthorizationError if the response carries no usable application key.\n */\nexport function redactCreateGroupMemberResponse(\n  response: CreateGroupMemberResponse,\n): CreateGroupMemberResponse {\n  if (!isCredentialBearing(response)) {\n    throw new B2PartnerAuthorizationError(\n      'b2_create_group_member response did not contain a usable application key',\n    )\n  }\n  // Full documented shape → field-specific (allowlist) redaction.\n  if (matchesGroupMemberShape(response.groupMember)) {\n    return redactCreateGroupMemberResult(response)\n  }\n  // Credential present but the surrounding shape is unexpected: never discard a\n  // provisioned one-time key. Return it with only the secret redacted for logs.\n  return redactWithHooks(\n    response,\n    redactApplicationKeyShallow,\n    () => `[CreateGroupMemberResponse ${APPLICATION_KEY_REDACTED}]`,\n  )\n}\n\n/**\n * Adds non-enumerable serialization and inspection hooks that redact the\n * application key secret while preserving direct property access.\n *\n * `JSON.stringify` redacts because the response contains newly minted\n * application key secrets that are commonly logged with responses. Callers\n * that need to persist the key should read `applicationKey` directly into\n * secure storage before serializing the object.\n *\n * @param result - Reserve trial account result to protect from accidental logging.\n *\n * @returns The same result object with redaction hooks installed when possible.\n */\nexport function redactReserveTrialCreateAccountResult(\n  result: ReserveTrialCreateAccountResult,\n): ReserveTrialCreateAccountResult {\n  return redactWithHooks(\n    result,\n    reserveTrialCreateAccountResultToRedactedJson,\n    () => `[ReserveTrialCreateAccountResult ${APPLICATION_KEY_REDACTED}]`,\n  )\n}\n\n/**\n * Adds non-enumerable serialization and inspection hooks that redact the\n * reserve-trial application key secret while preserving direct property access.\n *\n * @param response - Reserve trial account response to protect from accidental logging.\n *\n * @returns The same response object with redaction hooks installed when possible.\n *\n * @throws B2PartnerAuthorizationError if the response carries no usable application key.\n */\nexport function redactReserveTrialCreateAccountResponse(\n  response: ReserveTrialCreateAccountResponse,\n): ReserveTrialCreateAccountResponse {\n  if (!isCredentialBearing(response)) {\n    throw new B2PartnerAuthorizationError(\n      'b2_reserve_trial_create_account response did not contain a usable application key',\n    )\n  }\n  // Full documented shape → field-specific (allowlist) redaction.\n  if (matchesReserveTrialAccountShape(response)) {\n    return redactReserveTrialCreateAccountResult(response)\n  }\n  // Credential present but the surrounding shape is unexpected: never discard a\n  // provisioned one-time key. Return it with only the secret redacted for logs.\n  return redactWithHooks(\n    response,\n    redactApplicationKeyShallow,\n    () => `[ReserveTrialCreateAccountResponse ${APPLICATION_KEY_REDACTED}]`,\n  )\n}\n"],"mappings":"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"}

package/dist/raw/encoding.cjs

@@ -7,6 +7,16 @@ const require_text_codec = require("../util/text-codec.cjs");
 * must be percent-encoded using UTF-8 byte values.
 */
 var SAFE_CHARS = new Set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~!$&'()*+,;=:@/".split(""));
+var FILE_INFO_VALUE_SAFE_CHARS = new Set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~".split(""));
+function encodeWithSafeChars(value, safeChars) {
+	const encoded = [];
+	for (const char of value) if (safeChars.has(char)) encoded.push(char);
+	else {
+		const bytes = require_text_codec.utf8Encoder.encode(char);
+		for (const byte of bytes) encoded.push(`%${byte.toString(16).toUpperCase().padStart(2, "0")}`);
+	}
+	return encoded.join("");
+}
 /**
 * Percent-encodes a file name using the B2-specific encoding rules.
 *
@@ -19,13 +29,21 @@ var SAFE_CHARS = new Set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01
 * @returns The percent-encoded file name suitable for `X-Bz-File-Name` headers.
 */
 function encodeFileName(name) {
-	const encoded = [];
-	for (const char of name) if (SAFE_CHARS.has(char)) encoded.push(char);
-	else {
-		const bytes = require_text_codec.utf8Encoder.encode(char);
-		for (const byte of bytes) encoded.push(`%${byte.toString(16).toUpperCase().padStart(2, "0")}`);
-	}
-	return encoded.join("");
+	return encodeWithSafeChars(name, SAFE_CHARS);
+}
+/**
+* Percent-encodes a file-info value using the stricter B2 metadata value rules.
+*
+* File-info values must be decoded by B2 before storage. Live B2 rejects comma
+* and other RFC punctuation when left raw in these values, so only RFC 3986
+* unreserved characters are passed through.
+*
+* @param value - The raw (unencoded) file-info value.
+*
+* @returns The percent-encoded value suitable for `X-Bz-Info-*` header values.
+*/
+function encodeFileInfoValue(value) {
+	return encodeWithSafeChars(value, FILE_INFO_VALUE_SAFE_CHARS);
 }
 /**
 * Decodes a B2 percent-encoded file name back to a plain string.
@@ -43,8 +61,9 @@ function decodeFileName(encoded) {
 /**
 * Converts a file-info map into `X-Bz-Info-*` HTTP headers.
 *
-* Both keys and values are percent-encoded with {@link encodeFileName}
-* to satisfy B2 header requirements.
+* Keys use B2 file-name encoding. Values use stricter B2 file-info value
+* encoding so punctuation such as commas is percent-encoded before B2 decodes
+* and validates stored metadata.
 *
 * @param fileInfo - Key/value pairs to attach as custom file info, or `undefined`.
 *
@@ -53,7 +72,7 @@ function decodeFileName(encoded) {
 function buildFileInfoHeaders(fileInfo) {
 	if (!fileInfo) return {};
 	const headers = {};
-	for (const [key, value] of Object.entries(fileInfo)) headers[`X-Bz-Info-${encodeFileName(key)}`] = encodeFileName(value);
+	for (const [key, value] of Object.entries(fileInfo)) headers[`X-Bz-Info-${encodeFileName(key)}`] = encodeFileInfoValue(value);
 	return headers;
 }
 /**

package/dist/raw/encoding.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"encoding.cjs","names":[],"sources":["../../src/raw/encoding.ts"],"sourcesContent":["import { utf8Encoder } from '../util/text-codec.ts'\n\n/**\n * Characters that B2 treats as safe (not percent-encoded) in file names.\n *\n * Per the B2 docs, everything except `a-z A-Z 0-9 - . _ ~ / ! $ & ' ( ) * + , ; = : @`\n * must be percent-encoded using UTF-8 byte values.\n */\nconst SAFE_CHARS = new Set(\n  \"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~!$&'()*+,;=:@/\".split(''),\n)\n\n/**\n * Percent-encodes a file name using the B2-specific encoding rules.\n *\n * Unlike standard `encodeURIComponent`, B2 keeps `/` and several other\n * characters unencoded while encoding all other non-ASCII and special\n * characters as uppercase percent-encoded UTF-8 bytes.\n *\n * @param name - The raw (unencoded) file name.\n *\n * @returns The percent-encoded file name suitable for `X-Bz-File-Name` headers.\n */\nexport function encodeFileName(name: string): string {\n  const encoded: string[] = []\n  for (const char of name) {\n    if (SAFE_CHARS.has(char)) {\n      encoded.push(char)\n    } else {\n      const bytes = utf8Encoder.encode(char)\n      for (const byte of bytes) {\n        encoded.push(`%${byte.toString(16).toUpperCase().padStart(2, '0')}`)\n      }\n    }\n  }\n  return encoded.join('')\n}\n\n/**\n * Decodes a B2 percent-encoded file name back to a plain string.\n *\n * B2 percent-encoding is compatible with standard `decodeURIComponent`,\n * so this is a thin wrapper.\n *\n * @param encoded - The percent-encoded file name from B2.\n *\n * @returns The decoded file name.\n */\nexport function decodeFileName(encoded: string): string {\n  return decodeURIComponent(encoded)\n}\n\n/**\n * Converts a file-info map into `X-Bz-Info-*` HTTP headers.\n *\n * Both keys and values are percent-encoded with {@link encodeFileName}\n * to satisfy B2 header requirements.\n *\n * @param fileInfo - Key/value pairs to attach as custom file info, or `undefined`.\n *\n * @returns A record of header name/value pairs (empty if `fileInfo` is `undefined`).\n */\nexport function buildFileInfoHeaders(\n  fileInfo: Record<string, string> | undefined,\n): Record<string, string> {\n  if (!fileInfo) return {}\n  const headers: Record<string, string> = {}\n  for (const [key, value] of Object.entries(fileInfo)) {\n    headers[`X-Bz-Info-${encodeFileName(key)}`] = encodeFileName(value)\n  }\n  return headers\n}\n\n/**\n * Extracts custom file-info key/value pairs from B2 response headers.\n *\n * Scans for headers prefixed with `x-bz-info-` and decodes both the\n * key suffix and value using {@link decodeFileName}.\n *\n * @param headers - The HTTP response headers from a B2 download or file-info call.\n *\n * @returns A record of decoded file-info key/value pairs.\n */\nexport function parseFileInfoHeaders(headers: Headers): Record<string, string> {\n  const info: Record<string, string> = {}\n  headers.forEach((value, key) => {\n    const lower = key.toLowerCase()\n    if (lower.startsWith('x-bz-info-')) {\n      const infoKey = decodeFileName(lower.slice('x-bz-info-'.length))\n      info[infoKey] = decodeFileName(value)\n    }\n  })\n  return info\n}\n"],"mappings":";;;;;;;;AAQA,IAAM,aAAa,IAAI,IACrB,mFAAmF,MAAM,EAAE,CAC7F;;;;;;;;;;;;AAaA,SAAgB,eAAe,MAAsB;CACnD,MAAM,UAAoB,CAAC;CAC3B,KAAK,MAAM,QAAQ,MACjB,IAAI,WAAW,IAAI,IAAI,GACrB,QAAQ,KAAK,IAAI;MACZ;EACL,MAAM,QAAQ,mBAAA,YAAY,OAAO,IAAI;EACrC,KAAK,MAAM,QAAQ,OACjB,QAAQ,KAAK,IAAI,KAAK,SAAS,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC,SAAS,GAAG,GAAG,GAAG;CAEvE;CAEF,OAAO,QAAQ,KAAK,EAAE;AACxB;;;;;;;;;;;AAYA,SAAgB,eAAe,SAAyB;CACtD,OAAO,mBAAmB,OAAO;AACnC;;;;;;;;;;;AAYA,SAAgB,qBACd,UACwB;CACxB,IAAI,CAAC,UAAU,OAAO,CAAC;CACvB,MAAM,UAAkC,CAAC;CACzC,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,QAAQ,GAChD,QAAQ,aAAa,eAAe,GAAG,OAAO,eAAe,KAAK;CAEpE,OAAO;AACT;;;;;;;;;;;AAYA,SAAgB,qBAAqB,SAA0C;CAC7E,MAAM,OAA+B,CAAC;CACtC,QAAQ,SAAS,OAAO,QAAQ;EAC9B,MAAM,QAAQ,IAAI,YAAY;EAC9B,IAAI,MAAM,WAAW,YAAY,GAAG;GAClC,MAAM,UAAU,eAAe,MAAM,MAAM,EAAmB,CAAC;GAC/D,KAAK,WAAW,eAAe,KAAK;EACtC;CACF,CAAC;CACD,OAAO;AACT"}
+{"version":3,"file":"encoding.cjs","names":[],"sources":["../../src/raw/encoding.ts"],"sourcesContent":["import { utf8Encoder } from '../util/text-codec.ts'\n\n/**\n * Characters that B2 treats as safe (not percent-encoded) in file names.\n *\n * Per the B2 docs, everything except `a-z A-Z 0-9 - . _ ~ / ! $ & ' ( ) * + , ; = : @`\n * must be percent-encoded using UTF-8 byte values.\n */\nconst SAFE_CHARS = new Set(\n  \"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~!$&'()*+,;=:@/\".split(''),\n)\n\nconst FILE_INFO_VALUE_SAFE_CHARS = new Set(\n  'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~'.split(''),\n)\n\nfunction encodeWithSafeChars(value: string, safeChars: ReadonlySet<string>): string {\n  const encoded: string[] = []\n  for (const char of value) {\n    if (safeChars.has(char)) {\n      encoded.push(char)\n    } else {\n      const bytes = utf8Encoder.encode(char)\n      for (const byte of bytes) {\n        encoded.push(`%${byte.toString(16).toUpperCase().padStart(2, '0')}`)\n      }\n    }\n  }\n  return encoded.join('')\n}\n\n/**\n * Percent-encodes a file name using the B2-specific encoding rules.\n *\n * Unlike standard `encodeURIComponent`, B2 keeps `/` and several other\n * characters unencoded while encoding all other non-ASCII and special\n * characters as uppercase percent-encoded UTF-8 bytes.\n *\n * @param name - The raw (unencoded) file name.\n *\n * @returns The percent-encoded file name suitable for `X-Bz-File-Name` headers.\n */\nexport function encodeFileName(name: string): string {\n  return encodeWithSafeChars(name, SAFE_CHARS)\n}\n\n/**\n * Percent-encodes a file-info value using the stricter B2 metadata value rules.\n *\n * File-info values must be decoded by B2 before storage. Live B2 rejects comma\n * and other RFC punctuation when left raw in these values, so only RFC 3986\n * unreserved characters are passed through.\n *\n * @param value - The raw (unencoded) file-info value.\n *\n * @returns The percent-encoded value suitable for `X-Bz-Info-*` header values.\n */\nfunction encodeFileInfoValue(value: string): string {\n  return encodeWithSafeChars(value, FILE_INFO_VALUE_SAFE_CHARS)\n}\n\n/**\n * Decodes a B2 percent-encoded file name back to a plain string.\n *\n * B2 percent-encoding is compatible with standard `decodeURIComponent`,\n * so this is a thin wrapper.\n *\n * @param encoded - The percent-encoded file name from B2.\n *\n * @returns The decoded file name.\n */\nexport function decodeFileName(encoded: string): string {\n  return decodeURIComponent(encoded)\n}\n\n/**\n * Converts a file-info map into `X-Bz-Info-*` HTTP headers.\n *\n * Keys use B2 file-name encoding. Values use stricter B2 file-info value\n * encoding so punctuation such as commas is percent-encoded before B2 decodes\n * and validates stored metadata.\n *\n * @param fileInfo - Key/value pairs to attach as custom file info, or `undefined`.\n *\n * @returns A record of header name/value pairs (empty if `fileInfo` is `undefined`).\n */\nexport function buildFileInfoHeaders(\n  fileInfo: Record<string, string> | undefined,\n): Record<string, string> {\n  if (!fileInfo) return {}\n  const headers: Record<string, string> = {}\n  for (const [key, value] of Object.entries(fileInfo)) {\n    headers[`X-Bz-Info-${encodeFileName(key)}`] = encodeFileInfoValue(value)\n  }\n  return headers\n}\n\n/**\n * Extracts custom file-info key/value pairs from B2 response headers.\n *\n * Scans for headers prefixed with `x-bz-info-` and decodes both the\n * key suffix and value using {@link decodeFileName}.\n *\n * @param headers - The HTTP response headers from a B2 download or file-info call.\n *\n * @returns A record of decoded file-info key/value pairs.\n */\nexport function parseFileInfoHeaders(headers: Headers): Record<string, string> {\n  const info: Record<string, string> = {}\n  headers.forEach((value, key) => {\n    const lower = key.toLowerCase()\n    if (lower.startsWith('x-bz-info-')) {\n      const infoKey = decodeFileName(lower.slice('x-bz-info-'.length))\n      info[infoKey] = decodeFileName(value)\n    }\n  })\n  return info\n}\n"],"mappings":";;;;;;;;AAQA,IAAM,aAAa,IAAI,IACrB,mFAAmF,MAAM,EAAE,CAC7F;AAEA,IAAM,6BAA6B,IAAI,IACrC,qEAAqE,MAAM,EAAE,CAC/E;AAEA,SAAS,oBAAoB,OAAe,WAAwC;CAClF,MAAM,UAAoB,CAAC;CAC3B,KAAK,MAAM,QAAQ,OACjB,IAAI,UAAU,IAAI,IAAI,GACpB,QAAQ,KAAK,IAAI;MACZ;EACL,MAAM,QAAQ,mBAAA,YAAY,OAAO,IAAI;EACrC,KAAK,MAAM,QAAQ,OACjB,QAAQ,KAAK,IAAI,KAAK,SAAS,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC,SAAS,GAAG,GAAG,GAAG;CAEvE;CAEF,OAAO,QAAQ,KAAK,EAAE;AACxB;;;;;;;;;;;;AAaA,SAAgB,eAAe,MAAsB;CACnD,OAAO,oBAAoB,MAAM,UAAU;AAC7C;;;;;;;;;;;;AAaA,SAAS,oBAAoB,OAAuB;CAClD,OAAO,oBAAoB,OAAO,0BAA0B;AAC9D;;;;;;;;;;;AAYA,SAAgB,eAAe,SAAyB;CACtD,OAAO,mBAAmB,OAAO;AACnC;;;;;;;;;;;;AAaA,SAAgB,qBACd,UACwB;CACxB,IAAI,CAAC,UAAU,OAAO,CAAC;CACvB,MAAM,UAAkC,CAAC;CACzC,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,QAAQ,GAChD,QAAQ,aAAa,eAAe,GAAG,OAAO,oBAAoB,KAAK;CAEzE,OAAO;AACT;;;;;;;;;;;AAYA,SAAgB,qBAAqB,SAA0C;CAC7E,MAAM,OAA+B,CAAC;CACtC,QAAQ,SAAS,OAAO,QAAQ;EAC9B,MAAM,QAAQ,IAAI,YAAY;EAC9B,IAAI,MAAM,WAAW,YAAY,GAAG;GAClC,MAAM,UAAU,eAAe,MAAM,MAAM,EAAmB,CAAC;GAC/D,KAAK,WAAW,eAAe,KAAK;EACtC;CACF,CAAC;CACD,OAAO;AACT"}

package/dist/raw/encoding.d.cts

@@ -24,8 +24,9 @@ export declare function decodeFileName(encoded: string): string;
 /**
  * Converts a file-info map into `X-Bz-Info-*` HTTP headers.
  *
- * Both keys and values are percent-encoded with {@link encodeFileName}
- * to satisfy B2 header requirements.
+ * Keys use B2 file-name encoding. Values use stricter B2 file-info value
+ * encoding so punctuation such as commas is percent-encoded before B2 decodes
+ * and validates stored metadata.
  *
  * @param fileInfo - Key/value pairs to attach as custom file info, or `undefined`.
  *

package/dist/raw/encoding.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../src/raw/encoding.js"],"names":[],"mappings":"AAYA;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAanD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAC3C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAU7E"}
+{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../src/raw/encoding.js"],"names":[],"mappings":"AA+BA;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAiBD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAC3C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAU7E"}

package/dist/raw/encoding.d.ts

@@ -24,8 +24,9 @@ export declare function decodeFileName(encoded: string): string;
 /**
  * Converts a file-info map into `X-Bz-Info-*` HTTP headers.
  *
- * Both keys and values are percent-encoded with {@link encodeFileName}
- * to satisfy B2 header requirements.
+ * Keys use B2 file-name encoding. Values use stricter B2 file-info value
+ * encoding so punctuation such as commas is percent-encoded before B2 decodes
+ * and validates stored metadata.
  *
  * @param fileInfo - Key/value pairs to attach as custom file info, or `undefined`.
  *

package/dist/raw/encoding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../src/raw/encoding.js"],"names":[],"mappings":"AAYA;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAanD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAC3C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAU7E"}
+{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../src/raw/encoding.js"],"names":[],"mappings":"AA+BA;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAiBD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAC3C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAU7E"}

package/dist/raw/encoding.js

@@ -7,6 +7,16 @@ import { utf8Encoder } from "../util/text-codec.js";
 * must be percent-encoded using UTF-8 byte values.
 */
 var SAFE_CHARS = new Set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~!$&'()*+,;=:@/".split(""));
+var FILE_INFO_VALUE_SAFE_CHARS = new Set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~".split(""));
+function encodeWithSafeChars(value, safeChars) {
+	const encoded = [];
+	for (const char of value) if (safeChars.has(char)) encoded.push(char);
+	else {
+		const bytes = utf8Encoder.encode(char);
+		for (const byte of bytes) encoded.push(`%${byte.toString(16).toUpperCase().padStart(2, "0")}`);
+	}
+	return encoded.join("");
+}
 /**
 * Percent-encodes a file name using the B2-specific encoding rules.
 *
@@ -19,13 +29,21 @@ var SAFE_CHARS = new Set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01
 * @returns The percent-encoded file name suitable for `X-Bz-File-Name` headers.
 */
 function encodeFileName(name) {
-	const encoded = [];
-	for (const char of name) if (SAFE_CHARS.has(char)) encoded.push(char);
-	else {
-		const bytes = utf8Encoder.encode(char);
-		for (const byte of bytes) encoded.push(`%${byte.toString(16).toUpperCase().padStart(2, "0")}`);
-	}
-	return encoded.join("");
+	return encodeWithSafeChars(name, SAFE_CHARS);
+}
+/**
+* Percent-encodes a file-info value using the stricter B2 metadata value rules.
+*
+* File-info values must be decoded by B2 before storage. Live B2 rejects comma
+* and other RFC punctuation when left raw in these values, so only RFC 3986
+* unreserved characters are passed through.
+*
+* @param value - The raw (unencoded) file-info value.
+*
+* @returns The percent-encoded value suitable for `X-Bz-Info-*` header values.
+*/
+function encodeFileInfoValue(value) {
+	return encodeWithSafeChars(value, FILE_INFO_VALUE_SAFE_CHARS);
 }
 /**
 * Decodes a B2 percent-encoded file name back to a plain string.
@@ -43,8 +61,9 @@ function decodeFileName(encoded) {
 /**
 * Converts a file-info map into `X-Bz-Info-*` HTTP headers.
 *
-* Both keys and values are percent-encoded with {@link encodeFileName}
-* to satisfy B2 header requirements.
+* Keys use B2 file-name encoding. Values use stricter B2 file-info value
+* encoding so punctuation such as commas is percent-encoded before B2 decodes
+* and validates stored metadata.
 *
 * @param fileInfo - Key/value pairs to attach as custom file info, or `undefined`.
 *
@@ -53,7 +72,7 @@ function decodeFileName(encoded) {
 function buildFileInfoHeaders(fileInfo) {
 	if (!fileInfo) return {};
 	const headers = {};
-	for (const [key, value] of Object.entries(fileInfo)) headers[`X-Bz-Info-${encodeFileName(key)}`] = encodeFileName(value);
+	for (const [key, value] of Object.entries(fileInfo)) headers[`X-Bz-Info-${encodeFileName(key)}`] = encodeFileInfoValue(value);
 	return headers;
 }
 /**

package/dist/raw/encoding.js.map

@@ -1 +1 @@
-{"version":3,"file":"encoding.js","names":[],"sources":["../../src/raw/encoding.ts"],"sourcesContent":["import { utf8Encoder } from '../util/text-codec.ts'\n\n/**\n * Characters that B2 treats as safe (not percent-encoded) in file names.\n *\n * Per the B2 docs, everything except `a-z A-Z 0-9 - . _ ~ / ! $ & ' ( ) * + , ; = : @`\n * must be percent-encoded using UTF-8 byte values.\n */\nconst SAFE_CHARS = new Set(\n  \"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~!$&'()*+,;=:@/\".split(''),\n)\n\n/**\n * Percent-encodes a file name using the B2-specific encoding rules.\n *\n * Unlike standard `encodeURIComponent`, B2 keeps `/` and several other\n * characters unencoded while encoding all other non-ASCII and special\n * characters as uppercase percent-encoded UTF-8 bytes.\n *\n * @param name - The raw (unencoded) file name.\n *\n * @returns The percent-encoded file name suitable for `X-Bz-File-Name` headers.\n */\nexport function encodeFileName(name: string): string {\n  const encoded: string[] = []\n  for (const char of name) {\n    if (SAFE_CHARS.has(char)) {\n      encoded.push(char)\n    } else {\n      const bytes = utf8Encoder.encode(char)\n      for (const byte of bytes) {\n        encoded.push(`%${byte.toString(16).toUpperCase().padStart(2, '0')}`)\n      }\n    }\n  }\n  return encoded.join('')\n}\n\n/**\n * Decodes a B2 percent-encoded file name back to a plain string.\n *\n * B2 percent-encoding is compatible with standard `decodeURIComponent`,\n * so this is a thin wrapper.\n *\n * @param encoded - The percent-encoded file name from B2.\n *\n * @returns The decoded file name.\n */\nexport function decodeFileName(encoded: string): string {\n  return decodeURIComponent(encoded)\n}\n\n/**\n * Converts a file-info map into `X-Bz-Info-*` HTTP headers.\n *\n * Both keys and values are percent-encoded with {@link encodeFileName}\n * to satisfy B2 header requirements.\n *\n * @param fileInfo - Key/value pairs to attach as custom file info, or `undefined`.\n *\n * @returns A record of header name/value pairs (empty if `fileInfo` is `undefined`).\n */\nexport function buildFileInfoHeaders(\n  fileInfo: Record<string, string> | undefined,\n): Record<string, string> {\n  if (!fileInfo) return {}\n  const headers: Record<string, string> = {}\n  for (const [key, value] of Object.entries(fileInfo)) {\n    headers[`X-Bz-Info-${encodeFileName(key)}`] = encodeFileName(value)\n  }\n  return headers\n}\n\n/**\n * Extracts custom file-info key/value pairs from B2 response headers.\n *\n * Scans for headers prefixed with `x-bz-info-` and decodes both the\n * key suffix and value using {@link decodeFileName}.\n *\n * @param headers - The HTTP response headers from a B2 download or file-info call.\n *\n * @returns A record of decoded file-info key/value pairs.\n */\nexport function parseFileInfoHeaders(headers: Headers): Record<string, string> {\n  const info: Record<string, string> = {}\n  headers.forEach((value, key) => {\n    const lower = key.toLowerCase()\n    if (lower.startsWith('x-bz-info-')) {\n      const infoKey = decodeFileName(lower.slice('x-bz-info-'.length))\n      info[infoKey] = decodeFileName(value)\n    }\n  })\n  return info\n}\n"],"mappings":";;;;;;;;AAQA,IAAM,aAAa,IAAI,IACrB,mFAAmF,MAAM,EAAE,CAC7F;;;;;;;;;;;;AAaA,SAAgB,eAAe,MAAsB;CACnD,MAAM,UAAoB,CAAC;CAC3B,KAAK,MAAM,QAAQ,MACjB,IAAI,WAAW,IAAI,IAAI,GACrB,QAAQ,KAAK,IAAI;MACZ;EACL,MAAM,QAAQ,YAAY,OAAO,IAAI;EACrC,KAAK,MAAM,QAAQ,OACjB,QAAQ,KAAK,IAAI,KAAK,SAAS,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC,SAAS,GAAG,GAAG,GAAG;CAEvE;CAEF,OAAO,QAAQ,KAAK,EAAE;AACxB;;;;;;;;;;;AAYA,SAAgB,eAAe,SAAyB;CACtD,OAAO,mBAAmB,OAAO;AACnC;;;;;;;;;;;AAYA,SAAgB,qBACd,UACwB;CACxB,IAAI,CAAC,UAAU,OAAO,CAAC;CACvB,MAAM,UAAkC,CAAC;CACzC,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,QAAQ,GAChD,QAAQ,aAAa,eAAe,GAAG,OAAO,eAAe,KAAK;CAEpE,OAAO;AACT;;;;;;;;;;;AAYA,SAAgB,qBAAqB,SAA0C;CAC7E,MAAM,OAA+B,CAAC;CACtC,QAAQ,SAAS,OAAO,QAAQ;EAC9B,MAAM,QAAQ,IAAI,YAAY;EAC9B,IAAI,MAAM,WAAW,YAAY,GAAG;GAClC,MAAM,UAAU,eAAe,MAAM,MAAM,EAAmB,CAAC;GAC/D,KAAK,WAAW,eAAe,KAAK;EACtC;CACF,CAAC;CACD,OAAO;AACT"}
+{"version":3,"file":"encoding.js","names":[],"sources":["../../src/raw/encoding.ts"],"sourcesContent":["import { utf8Encoder } from '../util/text-codec.ts'\n\n/**\n * Characters that B2 treats as safe (not percent-encoded) in file names.\n *\n * Per the B2 docs, everything except `a-z A-Z 0-9 - . _ ~ / ! $ & ' ( ) * + , ; = : @`\n * must be percent-encoded using UTF-8 byte values.\n */\nconst SAFE_CHARS = new Set(\n  \"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~!$&'()*+,;=:@/\".split(''),\n)\n\nconst FILE_INFO_VALUE_SAFE_CHARS = new Set(\n  'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~'.split(''),\n)\n\nfunction encodeWithSafeChars(value: string, safeChars: ReadonlySet<string>): string {\n  const encoded: string[] = []\n  for (const char of value) {\n    if (safeChars.has(char)) {\n      encoded.push(char)\n    } else {\n      const bytes = utf8Encoder.encode(char)\n      for (const byte of bytes) {\n        encoded.push(`%${byte.toString(16).toUpperCase().padStart(2, '0')}`)\n      }\n    }\n  }\n  return encoded.join('')\n}\n\n/**\n * Percent-encodes a file name using the B2-specific encoding rules.\n *\n * Unlike standard `encodeURIComponent`, B2 keeps `/` and several other\n * characters unencoded while encoding all other non-ASCII and special\n * characters as uppercase percent-encoded UTF-8 bytes.\n *\n * @param name - The raw (unencoded) file name.\n *\n * @returns The percent-encoded file name suitable for `X-Bz-File-Name` headers.\n */\nexport function encodeFileName(name: string): string {\n  return encodeWithSafeChars(name, SAFE_CHARS)\n}\n\n/**\n * Percent-encodes a file-info value using the stricter B2 metadata value rules.\n *\n * File-info values must be decoded by B2 before storage. Live B2 rejects comma\n * and other RFC punctuation when left raw in these values, so only RFC 3986\n * unreserved characters are passed through.\n *\n * @param value - The raw (unencoded) file-info value.\n *\n * @returns The percent-encoded value suitable for `X-Bz-Info-*` header values.\n */\nfunction encodeFileInfoValue(value: string): string {\n  return encodeWithSafeChars(value, FILE_INFO_VALUE_SAFE_CHARS)\n}\n\n/**\n * Decodes a B2 percent-encoded file name back to a plain string.\n *\n * B2 percent-encoding is compatible with standard `decodeURIComponent`,\n * so this is a thin wrapper.\n *\n * @param encoded - The percent-encoded file name from B2.\n *\n * @returns The decoded file name.\n */\nexport function decodeFileName(encoded: string): string {\n  return decodeURIComponent(encoded)\n}\n\n/**\n * Converts a file-info map into `X-Bz-Info-*` HTTP headers.\n *\n * Keys use B2 file-name encoding. Values use stricter B2 file-info value\n * encoding so punctuation such as commas is percent-encoded before B2 decodes\n * and validates stored metadata.\n *\n * @param fileInfo - Key/value pairs to attach as custom file info, or `undefined`.\n *\n * @returns A record of header name/value pairs (empty if `fileInfo` is `undefined`).\n */\nexport function buildFileInfoHeaders(\n  fileInfo: Record<string, string> | undefined,\n): Record<string, string> {\n  if (!fileInfo) return {}\n  const headers: Record<string, string> = {}\n  for (const [key, value] of Object.entries(fileInfo)) {\n    headers[`X-Bz-Info-${encodeFileName(key)}`] = encodeFileInfoValue(value)\n  }\n  return headers\n}\n\n/**\n * Extracts custom file-info key/value pairs from B2 response headers.\n *\n * Scans for headers prefixed with `x-bz-info-` and decodes both the\n * key suffix and value using {@link decodeFileName}.\n *\n * @param headers - The HTTP response headers from a B2 download or file-info call.\n *\n * @returns A record of decoded file-info key/value pairs.\n */\nexport function parseFileInfoHeaders(headers: Headers): Record<string, string> {\n  const info: Record<string, string> = {}\n  headers.forEach((value, key) => {\n    const lower = key.toLowerCase()\n    if (lower.startsWith('x-bz-info-')) {\n      const infoKey = decodeFileName(lower.slice('x-bz-info-'.length))\n      info[infoKey] = decodeFileName(value)\n    }\n  })\n  return info\n}\n"],"mappings":";;;;;;;;AAQA,IAAM,aAAa,IAAI,IACrB,mFAAmF,MAAM,EAAE,CAC7F;AAEA,IAAM,6BAA6B,IAAI,IACrC,qEAAqE,MAAM,EAAE,CAC/E;AAEA,SAAS,oBAAoB,OAAe,WAAwC;CAClF,MAAM,UAAoB,CAAC;CAC3B,KAAK,MAAM,QAAQ,OACjB,IAAI,UAAU,IAAI,IAAI,GACpB,QAAQ,KAAK,IAAI;MACZ;EACL,MAAM,QAAQ,YAAY,OAAO,IAAI;EACrC,KAAK,MAAM,QAAQ,OACjB,QAAQ,KAAK,IAAI,KAAK,SAAS,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC,SAAS,GAAG,GAAG,GAAG;CAEvE;CAEF,OAAO,QAAQ,KAAK,EAAE;AACxB;;;;;;;;;;;;AAaA,SAAgB,eAAe,MAAsB;CACnD,OAAO,oBAAoB,MAAM,UAAU;AAC7C;;;;;;;;;;;;AAaA,SAAS,oBAAoB,OAAuB;CAClD,OAAO,oBAAoB,OAAO,0BAA0B;AAC9D;;;;;;;;;;;AAYA,SAAgB,eAAe,SAAyB;CACtD,OAAO,mBAAmB,OAAO;AACnC;;;;;;;;;;;;AAaA,SAAgB,qBACd,UACwB;CACxB,IAAI,CAAC,UAAU,OAAO,CAAC;CACvB,MAAM,UAAkC,CAAC;CACzC,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,QAAQ,GAChD,QAAQ,aAAa,eAAe,GAAG,OAAO,oBAAoB,KAAK;CAEzE,OAAO;AACT;;;;;;;;;;;AAYA,SAAgB,qBAAqB,SAA0C;CAC7E,MAAM,OAA+B,CAAC;CACtC,QAAQ,SAAS,OAAO,QAAQ;EAC9B,MAAM,QAAQ,IAAI,YAAY;EAC9B,IAAI,MAAM,WAAW,YAAY,GAAG;GAClC,MAAM,UAAU,eAAe,MAAM,MAAM,EAAmB,CAAC;GAC/D,KAAK,WAAW,eAAe,KAAK;EACtC;CACF,CAAC;CACD,OAAO;AACT"}