@backblaze-labs/b2-sdk 0.1.0

package/dist/simulator/index.js

@@ -0,0 +1,1560 @@
+import { sha1Hex } from "../streams/hash.js";
+import { Capability } from "../types/auth.js";
+import { BucketRetentionMode } from "../types/bucket.js";
+import { EncryptionMode } from "../types/encryption.js";
+import { FileAction } from "../types/file.js";
+import { accountId, bucketId, fileId } from "../types/ids.js";
+import { utf8Encoder, utf8Decoder } from "../util/text-codec.js";
+import { toError } from "../util/to-error.js";
+import { missingCapabilitiesFor } from "./capabilities.js";
+import { validateFileName, validateFileInfo, validateBucketName, validateBucketInfo, validateMaxCount } from "./validation.js";
+import { BUCKET_INFO_MAX_KEYS, BUCKET_INFO_VALUE_MAX, BUCKET_NAME_MAX, BUCKET_NAME_MIN, FILE_INFO_TOTAL_MAX, FILE_INFO_VALUE_MAX, FILE_NAME_MAX_BYTES, LIST_ENDPOINT_CAPS } from "./validation.js";
+function parseRangeHeader(header, totalSize) {
+  const m = header.match(/^bytes=(\d*)-(\d*)$/);
+  if (!m) return { kind: "malformed" };
+  const [, startStr, endStr] = m;
+  const hasStart = startStr !== "";
+  const hasEnd = endStr !== "";
+  if (!hasStart && !hasEnd) return { kind: "malformed" };
+  if (totalSize === 0) return { kind: "unsatisfiable" };
+  let start;
+  let end;
+  if (!hasStart) {
+    const suffixLen = Number.parseInt(endStr ?? "0", 10);
+    if (!Number.isFinite(suffixLen) || suffixLen <= 0) return { kind: "malformed" };
+    start = Math.max(0, totalSize - suffixLen);
+    end = totalSize - 1;
+  } else if (!hasEnd) {
+    start = Number.parseInt(startStr ?? "0", 10);
+    end = totalSize - 1;
+  } else {
+    start = Number.parseInt(startStr ?? "0", 10);
+    end = Number.parseInt(endStr ?? "0", 10);
+  }
+  if (!Number.isFinite(start) || !Number.isFinite(end) || start < 0 || start > end) {
+    return { kind: "malformed" };
+  }
+  if (start >= totalSize) return { kind: "unsatisfiable" };
+  end = Math.min(end, totalSize - 1);
+  return { kind: "ok", start, end };
+}
+function parseFileInfoHeaders(headers) {
+  const info = {};
+  const prefix = "x-bz-info-";
+  for (const [key, value] of Object.entries(headers)) {
+    if (!key.startsWith(prefix)) continue;
+    const fileInfoKey = decodeURIComponent(key.slice(prefix.length));
+    info[fileInfoKey] = decodeURIComponent(value);
+  }
+  return info;
+}
+class B2Simulator {
+  buckets = /* @__PURE__ */ new Map();
+  accountId = "sim_account_0001";
+  largeFiles = /* @__PURE__ */ new Map();
+  keys = /* @__PURE__ */ new Map();
+  notificationRules = /* @__PURE__ */ new Map();
+  minimumPartSize;
+  recommendedPartSize;
+  faults = [];
+  nextFaultId = 1;
+  onWebhookDeliver;
+  onReplicate;
+  onHookError;
+  strictAuth;
+  authTokenTtlMs;
+  /**
+   * Issued auth tokens with their associated grant scope + expiry. In
+   * permissive mode (`strictAuth: false`) this is still populated by
+   * `authorize` but never consulted on subsequent requests. In strict
+   * mode each request looks up its `Authorization` header here.
+   */
+  issuedTokens = /* @__PURE__ */ new Map();
+  /**
+   * Virtual-clock offset applied to `Date.now()` for expiry checks.
+   * Defaults to 0. Tests advance via {@link advanceTime} to fast-forward
+   * past auth-token expiry without sleeping.
+   */
+  clockOffsetMs = 0;
+  /**
+   * Per-instance monotonic counter used to mint realistic-looking
+   * IDs (`b2_bucket_<24-hex>`, `4_z<24-hex>`, etc.) and auth tokens.
+   * Module-global previously, which leaked state across `B2Simulator`
+   * instances in the same Vitest worker — concurrent tests could see
+   * colliding tokens. Per-instance ensures determinism within a single
+   * simulator's lifetime.
+   */
+  nextId = 1;
+  /**
+   * Last-issued upload timestamp. The simulator enforces strict
+   * monotonicity so version ordering is deterministic for tests; if
+   * two writes hit the same `Date.now()` millisecond, the second
+   * receives `lastTimestamp + 1`.
+   */
+  lastTimestamp = 0;
+  /**
+   * Outstanding fire-and-forget hook invocations. Tracked so tests
+   * (and future {@link flushHooks} callers) can wait for every
+   * dispatched `onWebhookDeliver` / `onReplicate` callback to settle
+   * before asserting against observable side effects. The microtask
+   * dance in fidelity tests was previously brittle: positive cases
+   * flushed twice, negative cases flushed once, and any addition to
+   * the hook dispatch chain quietly broke the negative path.
+   */
+  pendingHooks = /* @__PURE__ */ new Set();
+  /**
+   * Constructs a new in-memory B2 simulator.
+   * @param options - Optional simulator overrides. See {@link B2SimulatorOptions}.
+   */
+  constructor(options = {}) {
+    this.minimumPartSize = options.minimumPartSize ?? 5e6;
+    this.recommendedPartSize = options.recommendedPartSize ?? 1e8;
+    if (options.onWebhookDeliver !== void 0) this.onWebhookDeliver = options.onWebhookDeliver;
+    if (options.onReplicate !== void 0) this.onReplicate = options.onReplicate;
+    if (options.onHookError !== void 0) this.onHookError = options.onHookError;
+    this.strictAuth = options.strictAuth ?? false;
+    this.authTokenTtlMs = options.authTokenTtlMs ?? 24 * 60 * 60 * 1e3;
+  }
+  /**
+   * Advance the simulator's virtual clock by `ms` milliseconds. Used in
+   * conjunction with `strictAuth: true` + a finite `authTokenTtlMs` to
+   * force token expiry without `setTimeout`-based delays.
+   *
+   * @param ms - Milliseconds to advance. Negative values rewind (rarely useful).
+   */
+  advanceTime(ms) {
+    this.clockOffsetMs += ms;
+  }
+  /**
+   * Current simulator time. Equal to `Date.now() + clockOffsetMs`.
+   *
+   * @returns Unix milliseconds.
+   */
+  now() {
+    return Date.now() + this.clockOffsetMs;
+  }
+  /**
+   * Generate a deterministic-but-realistic-looking B2 identifier of the
+   * shape `<prefix>_<24-hex-counter>`, which approximates the visual
+   * width of real B2 wire IDs. The counter is monotonic per instance
+   * so test fixtures are deterministic across runs of the same
+   * simulator.
+   *
+   * @param prefix - B2-style prefix (`'b2_bucket'`, `'4_z'`, etc.).
+   *
+   * @returns A simulator-issued identifier that looks like a B2 wire ID.
+   */
+  genId(prefix) {
+    const n = this.nextId++;
+    return `${prefix}_${n.toString(16).padStart(24, "0")}`;
+  }
+  /**
+   * Return a strictly-increasing upload timestamp, even when multiple
+   * writes land in the same `Date.now()` millisecond. Tests rely on
+   * `uploadTimestamp` ordering to discriminate file versions; ties from
+   * coarse system-clock resolution would otherwise make version
+   * selection nondeterministic.
+   *
+   * @returns Unix milliseconds.
+   */
+  monotonicTimestamp() {
+    const now = Date.now();
+    if (now <= this.lastTimestamp) {
+      this.lastTimestamp += 1;
+    } else {
+      this.lastTimestamp = now;
+    }
+    return this.lastTimestamp;
+  }
+  /**
+   * Wait for every fire-and-forget hook (`onWebhookDeliver`,
+   * `onReplicate`) currently in flight to settle. Use in tests after
+   * an upload/copy/finish-large-file call to deterministically observe
+   * hook side effects without microtask-flush guesswork.
+   *
+   * @returns A promise that resolves once every pending hook callback
+   *   has either resolved or rejected.
+   */
+  async flushHooks() {
+    while (this.pendingHooks.size > 0) {
+      const snapshot = [...this.pendingHooks];
+      await Promise.allSettled(snapshot);
+    }
+  }
+  /**
+   * Authorize a request against the strict-auth bookkeeping. Returns
+   * a `SimulatorJsonResponse` error on failure or `null` on success.
+   * Only consulted when `strictAuth: true`.
+   *
+   * @param authToken - The `Authorization` header value from the request.
+   * @param endpoint - B2 endpoint name being invoked.
+   * @param bucketId - Optional bucket ID the request operates on, for scope check.
+   * @param fileName - Optional file name the request operates on, for prefix check.
+   *
+   * @returns `null` when the request is authorized, otherwise a 401/403 response.
+   */
+  authorizeRequest(authToken, endpoint, bucketId2, fileName) {
+    const required = missingCapabilitiesFor(endpoint, []);
+    const noCheckNeeded = required.length === 0 && endpoint === "b2_authorize_account";
+    if (noCheckNeeded) return null;
+    if (authToken === void 0 || authToken === "") {
+      return this.error(401, "bad_auth_token", "missing Authorization header");
+    }
+    const token = this.issuedTokens.get(authToken);
+    if (!token) {
+      return this.error(401, "bad_auth_token", "unknown auth token");
+    }
+    if (this.now() > token.expiresAt) {
+      return this.error(401, "expired_auth_token", "auth token has expired; reauthorize");
+    }
+    const missing = missingCapabilitiesFor(endpoint, token.capabilities);
+    if (missing.length > 0) {
+      return this.error(
+        403,
+        "unauthorized",
+        `application key lacks required capabilities: ${missing.join(", ")}`
+      );
+    }
+    if (token.bucketId !== null && bucketId2 !== void 0 && bucketId2 !== token.bucketId) {
+      return this.error(
+        403,
+        "unauthorized",
+        `application key is scoped to bucket ${token.bucketId}; cannot access ${bucketId2}`
+      );
+    }
+    if (token.namePrefix !== null && fileName !== void 0 && !fileName.startsWith(token.namePrefix)) {
+      return this.error(
+        403,
+        "unauthorized",
+        `application key is scoped to prefix "${token.namePrefix}"; "${fileName}" is outside scope`
+      );
+    }
+    return null;
+  }
+  /**
+   * Look up the application key matching the `Authorization` header on
+   * an `authorize_account` request. The header is in the form
+   * `Basic base64(applicationKeyId:applicationKey)`.
+   *
+   * Returns `null` for the implicit master credential (anything that
+   * does not match a key minted via `b2_create_key`); in that case
+   * `authorize` grants the full master capability set.
+   *
+   * @param authzHeader - Raw HTTP `Authorization` header value.
+   *
+   * @returns The matching key's grant scope, or `null` for the master.
+   */
+  findKeyForAuthHeader(authzHeader) {
+    if (!authzHeader || !authzHeader.startsWith("Basic ")) return null;
+    const decoded = (() => {
+      try {
+        return atob(authzHeader.slice(6));
+      } catch {
+        return null;
+      }
+    })();
+    if (decoded === null) return null;
+    const idx = decoded.indexOf(":");
+    if (idx === -1) return null;
+    const applicationKeyId = decoded.slice(0, idx);
+    const applicationKey = decoded.slice(idx + 1);
+    const stored = this.keys.get(applicationKeyId);
+    if (!stored || stored.applicationKey !== applicationKey) return null;
+    return {
+      capabilities: stored.capabilities,
+      bucketId: stored.bucketId,
+      namePrefix: stored.namePrefix,
+      applicationKeyId
+    };
+  }
+  /**
+   * Creates an {@link HttpTransport} that routes requests to this simulator.
+   * @returns A transport instance backed by this in-memory simulator.
+   */
+  transport() {
+    return new SimulatorTransport(this);
+  }
+  /**
+   * Register a synthetic failure to inject on requests whose URL contains
+   * `spec.on`. Use this to exercise retry / backoff / error-handling
+   * paths in tests without hand-rolling a wrapping `HttpTransport`. The
+   * fault is consumed in registration order on each matched request;
+   * once its `count` budget is exhausted it auto-retires.
+   *
+   * Faults are checked BEFORE the simulator's real handlers run, so a
+   * matched request never touches in-memory state — failed uploads
+   * don't create partial parts, failed deletes don't remove anything.
+   *
+   * @param spec - The failure to inject. See {@link FaultSpec}.
+   *
+   * @returns A handle whose `clear()` method removes this specific
+   *   fault registration (other faults remain in effect).
+   *
+   * @example
+   * ```ts
+   * // Fail the next 2 b2_upload_part calls with 503, then succeed.
+   * sim.injectFailure({ on: 'b2_upload_part', status: 503, count: 2 })
+   *
+   * // Fail every b2_authorize_account with 401 + Retry-After: 5.
+   * const handle = sim.injectFailure({
+   *   on: 'b2_authorize_account',
+   *   status: 401,
+   *   code: 'expired_auth_token',
+   *   retryAfter: 5,
+   * })
+   * // ... later
+   * handle.clear()
+   * ```
+   */
+  injectFailure(spec) {
+    const id = this.nextFaultId++;
+    const fault = {
+      id,
+      spec,
+      remainingSkip: spec.skip ?? 0,
+      remainingCount: spec.count ?? Number.POSITIVE_INFINITY
+    };
+    this.faults.push(fault);
+    return {
+      clear: () => {
+        const idx = this.faults.findIndex((f) => f.id === id);
+        if (idx !== -1) this.faults.splice(idx, 1);
+      }
+    };
+  }
+  /**
+   * Remove every registered fault. Equivalent to calling `.clear()` on
+   * every handle returned by {@link injectFailure}, plus a defensive
+   * reset for tests that re-use a simulator across cases.
+   */
+  clearFaults() {
+    this.faults.length = 0;
+  }
+  /**
+   * Internal: checks the registered faults for a match on the given URL
+   * and consumes one if it should fire. Called from
+   * {@link SimulatorTransport.send} before any real handler runs.
+   *
+   * @param url - The request URL to match against each fault's `on`
+   *   substring.
+   *
+   * @returns The fault to apply, or `null` if no fault should fire.
+   *
+   * @internal
+   */
+  consumeMatchingFault(url) {
+    for (let i = 0; i < this.faults.length; i++) {
+      const fault = this.faults[i];
+      if (!url.includes(fault.spec.on)) continue;
+      if (fault.remainingSkip > 0) {
+        fault.remainingSkip -= 1;
+        continue;
+      }
+      if (fault.remainingCount <= 0) continue;
+      fault.remainingCount -= 1;
+      if (fault.remainingCount <= 0) {
+        this.faults.splice(i, 1);
+      }
+      return fault.spec;
+    }
+    return null;
+  }
+  /**
+   * Dispatches a JSON API request to the appropriate handler.
+   * @param _method - The HTTP method (unused).
+   * @param path - The request URL path containing the B2 endpoint name.
+   * @param headers - The HTTP request headers; consulted by the
+   *   strict-auth gate to look up the issued auth token.
+   * @param body - The parsed JSON request body.
+   *
+   * @returns An object with HTTP status and JSON response body.
+   */
+  async handleRequest(_method, path, headers, body) {
+    const endpoint = path.split("/").pop() ?? "";
+    if (this.strictAuth) {
+      const authError = this.authorizeRequest(headers["authorization"], endpoint);
+      if (authError !== null) return authError;
+    }
+    switch (endpoint) {
+      case "b2_authorize_account":
+        return this.authorize(headers["authorization"]);
+      case "b2_create_bucket":
+        return this.createBucket(
+          body
+        );
+      case "b2_list_buckets":
+        return this.listBuckets();
+      case "b2_delete_bucket":
+        return this.deleteBucket(body);
+      case "b2_update_bucket":
+        return this.updateBucket(body);
+      case "b2_get_upload_url":
+        return this.getUploadUrl(body);
+      case "b2_list_file_names":
+        return this.listFileNames(
+          body
+        );
+      case "b2_list_file_versions":
+        return this.listFileVersions(
+          body
+        );
+      case "b2_get_file_info":
+        return this.getFileInfo(body);
+      case "b2_hide_file":
+        return this.hideFile(body);
+      case "b2_delete_file_version":
+        return this.deleteFileVersion(
+          body
+        );
+      case "b2_copy_file":
+        return this.copyFile(
+          body
+        );
+      case "b2_start_large_file":
+        return this.startLargeFile(
+          body
+        );
+      case "b2_get_upload_part_url":
+        return this.getUploadPartUrl(body);
+      case "b2_finish_large_file":
+        return this.finishLargeFile(body);
+      case "b2_cancel_large_file":
+        return this.cancelLargeFile(body);
+      case "b2_list_unfinished_large_files":
+        return this.listUnfinishedLargeFiles(
+          body
+        );
+      case "b2_list_parts":
+        return this.listParts(
+          body
+        );
+      case "b2_copy_part":
+        return await this.copyPart(
+          body
+        );
+      case "b2_get_download_authorization":
+        return this.getDownloadAuthorization(
+          body
+        );
+      case "b2_create_key":
+        return this.createKey(
+          body
+        );
+      case "b2_list_keys":
+        return this.listKeys(
+          body
+        );
+      case "b2_delete_key":
+        return this.deleteKey(body);
+      case "b2_update_file_retention":
+        return this.updateFileRetention(
+          body
+        );
+      case "b2_update_file_legal_hold":
+        return this.updateFileLegalHold(
+          body
+        );
+      case "b2_get_bucket_notification_rules":
+        return this.getBucketNotificationRules(body);
+      case "b2_set_bucket_notification_rules":
+        return this.setBucketNotificationRules(
+          body
+        );
+      default:
+        return {
+          status: 400,
+          body: { status: 400, code: "bad_request", message: `Unknown endpoint: ${endpoint}` }
+        };
+    }
+  }
+  /**
+   * Handles file and part upload requests (`b2_upload_file`, `b2_upload_part`).
+   * Dispatches to the appropriate internal handler based on the URL.
+   * @param url - The upload endpoint URL used to determine the upload type.
+   * @param headers - The HTTP headers containing file metadata and authorization.
+   * @param data - The raw file or part content as bytes.
+   *
+   * @returns An object with HTTP status and JSON response body.
+   */
+  handleUpload(url, headers, data) {
+    const isPart = url.includes("b2_upload_part");
+    if (this.strictAuth) {
+      const endpoint = isPart ? "b2_upload_part" : "b2_upload_file";
+      const authError = this.authorizeRequest(headers["authorization"], endpoint);
+      if (authError !== null) return authError;
+    }
+    if (isPart) {
+      return this.handleUploadPart(url, headers, data);
+    }
+    return this.handleUploadFile(url, headers, data);
+  }
+  /**
+   * Handles file download requests (`b2_download_file_by_id`, `/file/` by name).
+   * Returns the file data along with B2 response headers.
+   * @param path - The request URL path identifying the file to download.
+   * @param headers - The HTTP request headers for range or authorization.
+   * @param method - The HTTP method; `'HEAD'` suppresses the response body.
+   *
+   * @returns The download response containing file data and B2 headers.
+   */
+  handleDownload(path, headers, method = "GET") {
+    if (path.includes("b2_download_file_by_id")) {
+      if (this.strictAuth) {
+        const authError = this.authorizeRequest(headers["authorization"], "b2_download_file_by_id");
+        if (authError !== null) return this.errorAsDownload(authError);
+      }
+      const url = new URL(`http://localhost${path}`);
+      const fileId2 = url.searchParams.get("fileId") ?? "";
+      return this.finalizeDownload(this.downloadById(fileId2, headers["range"]), url, method);
+    }
+    const fileMatch = path.match(/^([^?]+)/)?.[1]?.match(/\/file\/([^/]+)\/(.+)/);
+    if (fileMatch) {
+      const bucketName = decodeURIComponent(fileMatch[1] ?? "");
+      const fileName = decodeURIComponent(fileMatch[2] ?? "");
+      if (this.strictAuth) {
+        const authError = this.authorizeRequest(
+          headers["authorization"],
+          "b2_download_file_by_name",
+          void 0,
+          fileName
+        );
+        if (authError !== null) return this.errorAsDownload(authError);
+      }
+      const url = new URL(`http://localhost${path}`);
+      return this.finalizeDownload(
+        this.downloadByName(bucketName, fileName, headers["range"]),
+        url,
+        method
+      );
+    }
+    return { status: 404, headers: {}, data: null };
+  }
+  /**
+   * Convert a synthetic JSON error body into a `SimulatorDownloadResponse`
+   * shape so the strict-auth gate on download paths can surface 401/403s
+   * through the same transport plumbing as a regular failed download.
+   *
+   * @param json - The JSON error from {@link authorizeRequest}.
+   *
+   * @returns A download-shaped response with the error body bytes inline.
+   */
+  errorAsDownload(json) {
+    return {
+      status: json.status,
+      headers: { "Content-Type": "application/json" },
+      data: utf8Encoder.encode(JSON.stringify(json.body))
+    };
+  }
+  /**
+   * Applies HEAD-method body suppression and `b2Content*` response-header
+   * overrides parsed from the download URL's query string. Mirrors what the
+   * real B2 service does: any `b2Content*` query parameter is echoed back as
+   * the corresponding response header.
+   *
+   * @param response - The download response produced by {@link downloadById} or {@link downloadByName}.
+   * @param url - The parsed download URL (used to read `b2Content*` query params).
+   * @param method - The HTTP method of the originating request.
+   *
+   * @returns The response with overrides applied.
+   */
+  finalizeDownload(response, url, method) {
+    const overrideMap = {
+      b2ContentDisposition: "Content-Disposition",
+      b2ContentLanguage: "Content-Language",
+      b2ContentEncoding: "Content-Encoding",
+      b2ContentType: "Content-Type",
+      b2CacheControl: "Cache-Control",
+      b2Expires: "Expires"
+    };
+    const newHeaders = { ...response.headers };
+    for (const [param, header] of Object.entries(overrideMap)) {
+      const value = url.searchParams.get(param);
+      if (value !== null) newHeaders[header] = value;
+    }
+    const data = method === "HEAD" ? null : response.data;
+    return { status: response.status, headers: newHeaders, data };
+  }
+  handleUploadFile(url, headers, data) {
+    const bucketId2 = new URL(url).searchParams.get("bucketId");
+    if (!bucketId2) return this.error(400, "bad_request", "Missing bucketId");
+    const bucket = this.buckets.get(bucketId2);
+    if (!bucket) return this.error(400, "bad_bucket_id", "Bucket not found");
+    const fileName = decodeURIComponent(headers["x-bz-file-name"] ?? "");
+    const contentType = headers["content-type"] ?? "application/octet-stream";
+    const sha1 = headers["x-bz-content-sha1"] ?? "none";
+    const fileNameError = validateFileName(fileName);
+    if (fileNameError) return this.error(400, fileNameError.code, fileNameError.message);
+    const fileInfo = parseFileInfoHeaders(headers);
+    const fileInfoError = validateFileInfo(fileInfo);
+    if (fileInfoError) return this.error(400, fileInfoError.code, fileInfoError.message);
+    const fileVersion = this.makeFileVersion({
+      bucketId: bucketId2,
+      fileName,
+      contentType,
+      contentLength: data.byteLength,
+      contentSha1: sha1,
+      action: FileAction.Upload
+    });
+    const stored = { fileVersion, data };
+    const existing = bucket.files.get(fileName);
+    if (existing) {
+      existing.push(stored);
+    } else {
+      bucket.files.set(fileName, [stored]);
+    }
+    this.firePostUploadHooks(fileVersion, bucketId2, "b2:ObjectCreated:Upload");
+    return { status: 200, body: fileVersion };
+  }
+  handleUploadPart(url, headers, data) {
+    const fileId2 = new URL(url).searchParams.get("fileId");
+    if (!fileId2) return this.error(400, "bad_request", "Missing fileId");
+    const large = this.largeFiles.get(fileId2);
+    if (!large) return this.error(400, "bad_request", "Large file not found");
+    const partNumber = Number.parseInt(headers["x-bz-part-number"] ?? "0", 10);
+    const sha1 = headers["x-bz-content-sha1"] ?? "none";
+    large.parts.set(partNumber, { data, sha1 });
+    return {
+      status: 200,
+      body: {
+        fileId: large.fileId,
+        partNumber,
+        contentLength: data.byteLength,
+        contentSha1: sha1,
+        serverSideEncryption: { mode: EncryptionMode.None },
+        uploadTimestamp: Date.now()
+      }
+    };
+  }
+  downloadById(fileId2, range) {
+    const found = this.findFile(fileId2);
+    if (found === null) return { status: 404, headers: {}, data: null };
+    return this.serveFile(found.stored, range);
+  }
+  downloadByName(bucketName, fileName, range) {
+    for (const bucket of this.buckets.values()) {
+      if (bucket.info.bucketName !== bucketName) continue;
+      const versions = bucket.files.get(fileName);
+      if (!versions || versions.length === 0) break;
+      const latest = versions[versions.length - 1];
+      if (!latest || latest.fileVersion.action === FileAction.Hide) {
+        return { status: 404, headers: {}, data: null };
+      }
+      return this.serveFile(latest, range);
+    }
+    return { status: 404, headers: {}, data: null };
+  }
+  serveFile(stored, range) {
+    const fullData = stored.data;
+    let data = fullData;
+    let status = 200;
+    let contentRange = null;
+    if (range) {
+      const parsed = parseRangeHeader(range, fullData.byteLength);
+      if (parsed.kind === "ok") {
+        data = fullData.subarray(parsed.start, parsed.end + 1);
+        status = 206;
+        contentRange = `bytes ${parsed.start}-${parsed.end}/${fullData.byteLength}`;
+      } else if (parsed.kind === "unsatisfiable") {
+        return {
+          status: 416,
+          headers: {
+            "Content-Type": stored.fileVersion.contentType,
+            "Content-Range": `bytes */${fullData.byteLength}`
+          },
+          data: new Uint8Array(0)
+        };
+      }
+    }
+    const fv = stored.fileVersion;
+    const headers = {
+      "Content-Type": fv.contentType,
+      "Content-Length": String(data.byteLength),
+      "X-Bz-File-Id": fv.fileId,
+      "X-Bz-File-Name": encodeURIComponent(fv.fileName),
+      "X-Bz-Content-Sha1": fv.contentSha1 ?? "none",
+      "X-Bz-Upload-Timestamp": String(fv.uploadTimestamp),
+      "X-Bz-Info-src_last_modified_millis": String(fv.uploadTimestamp)
+    };
+    if (contentRange !== null) {
+      headers["Content-Range"] = contentRange;
+    }
+    return { status, headers, data };
+  }
+  // --- API handlers ---
+  authorize(authzHeader) {
+    const capabilities = [
+      Capability.ListBuckets,
+      Capability.ReadBuckets,
+      Capability.WriteBuckets,
+      Capability.DeleteBuckets,
+      Capability.ListFiles,
+      Capability.ReadFiles,
+      Capability.WriteFiles,
+      Capability.DeleteFiles,
+      Capability.ListKeys,
+      Capability.WriteKeys,
+      Capability.DeleteKeys,
+      Capability.ShareFiles,
+      Capability.ReadBucketNotifications,
+      Capability.WriteBucketNotifications
+    ];
+    const keyForAuth = this.findKeyForAuthHeader(authzHeader);
+    const tokenStr = `sim_auth_token_${this.nextId++}`;
+    this.issuedTokens.set(tokenStr, {
+      capabilities: keyForAuth?.capabilities ?? capabilities,
+      bucketId: keyForAuth?.bucketId ?? null,
+      namePrefix: keyForAuth?.namePrefix ?? null,
+      expiresAt: this.now() + this.authTokenTtlMs,
+      applicationKeyId: keyForAuth?.applicationKeyId ?? null
+    });
+    return {
+      status: 200,
+      body: {
+        accountId: accountId(this.accountId),
+        // `AuthToken` has no public factory by design — auth tokens are
+        // minted by B2, not constructed by user code. The simulator is
+        // the only legitimate place that needs to forge one.
+        authorizationToken: tokenStr,
+        apiInfo: {
+          storageApi: {
+            absoluteMinimumPartSize: this.minimumPartSize,
+            apiUrl: "http://localhost:0",
+            bucketId: keyForAuth?.bucketId ?? null,
+            bucketName: null,
+            downloadUrl: "http://localhost:0",
+            infoType: "storageApi",
+            namePrefix: keyForAuth?.namePrefix ?? null,
+            recommendedPartSize: this.recommendedPartSize,
+            s3ApiUrl: "http://localhost:0",
+            allowed: {
+              capabilities: keyForAuth?.capabilities ?? capabilities,
+              bucketId: keyForAuth?.bucketId ?? null,
+              bucketName: null,
+              namePrefix: keyForAuth?.namePrefix ?? null
+            }
+          }
+        },
+        applicationKeyExpirationTimestamp: null
+      }
+    };
+  }
+  createBucket(req) {
+    const nameError = validateBucketName(req.bucketName);
+    if (nameError) return this.error(400, nameError.code, nameError.message);
+    if (req.bucketInfo !== void 0) {
+      const infoError = validateBucketInfo(req.bucketInfo);
+      if (infoError) return this.error(400, infoError.code, infoError.message);
+    }
+    for (const b of this.buckets.values()) {
+      if (b.info.bucketName === req.bucketName) {
+        return this.error(400, "duplicate_bucket_name", "Bucket name already in use");
+      }
+    }
+    const bid = bucketId(this.genId("b2_bucket"));
+    const defaultRetention = req.defaultRetention ?? {
+      mode: BucketRetentionMode.None,
+      period: null
+    };
+    const info = {
+      accountId: accountId(req.accountId),
+      bucketId: bid,
+      bucketName: req.bucketName,
+      bucketType: req.bucketType,
+      bucketInfo: req.bucketInfo ?? {},
+      corsRules: req.corsRules ?? [],
+      defaultServerSideEncryption: req.defaultServerSideEncryption ?? { mode: EncryptionMode.None },
+      fileLockConfiguration: {
+        isClientAuthorizedToRead: true,
+        value: {
+          isFileLockEnabled: req.fileLockEnabled ?? false,
+          defaultRetention
+        }
+      },
+      lifecycleRules: req.lifecycleRules ?? [],
+      options: [],
+      revision: 1,
+      defaultRetention,
+      replicationConfiguration: req.replicationConfiguration ?? {
+        asReplicationSource: null,
+        asReplicationDestination: null
+      }
+    };
+    this.buckets.set(bid, { info, files: /* @__PURE__ */ new Map() });
+    return { status: 200, body: info };
+  }
+  listBuckets() {
+    const buckets = [...this.buckets.values()].map((b) => b.info);
+    return { status: 200, body: { buckets } };
+  }
+  deleteBucket(req) {
+    const bucket = this.buckets.get(req.bucketId);
+    if (!bucket) return this.error(400, "bad_bucket_id", "Bucket not found");
+    this.buckets.delete(req.bucketId);
+    return { status: 200, body: bucket.info };
+  }
+  updateBucket(req) {
+    const bucket = this.buckets.get(req["bucketId"]);
+    if (!bucket) return this.error(400, "bad_bucket_id", "Bucket not found");
+    if (req["bucketInfo"] !== void 0) {
+      const infoError = validateBucketInfo(req["bucketInfo"]);
+      if (infoError) return this.error(400, infoError.code, infoError.message);
+    }
+    const updated = {
+      ...bucket.info,
+      ...req["bucketType"] !== void 0 ? { bucketType: req["bucketType"] } : {},
+      ...req["bucketInfo"] !== void 0 ? { bucketInfo: req["bucketInfo"] } : {},
+      ...req["lifecycleRules"] !== void 0 ? { lifecycleRules: req["lifecycleRules"] } : {},
+      ...req["corsRules"] !== void 0 ? { corsRules: req["corsRules"] } : {},
+      ...req["replicationConfiguration"] !== void 0 ? {
+        replicationConfiguration: req["replicationConfiguration"]
+      } : {},
+      ...req["defaultRetention"] !== void 0 ? {
+        defaultRetention: req["defaultRetention"],
+        fileLockConfiguration: {
+          isClientAuthorizedToRead: true,
+          value: {
+            isFileLockEnabled: bucket.info.fileLockConfiguration.value?.isFileLockEnabled ?? false,
+            defaultRetention: req["defaultRetention"]
+          }
+        }
+      } : {},
+      ...req["defaultServerSideEncryption"] !== void 0 ? {
+        defaultServerSideEncryption: req["defaultServerSideEncryption"]
+      } : {},
+      revision: bucket.info.revision + 1
+    };
+    this.buckets.set(req["bucketId"], { info: updated, files: bucket.files });
+    return { status: 200, body: updated };
+  }
+  getUploadUrl(req) {
+    if (!this.buckets.has(req.bucketId)) return this.error(400, "bad_bucket_id", "Bucket not found");
+    return {
+      status: 200,
+      body: {
+        bucketId: req.bucketId,
+        uploadUrl: `http://localhost:0/b2api/v3/b2_upload_file?bucketId=${req.bucketId}`,
+        authorizationToken: "sim_upload_token"
+      }
+    };
+  }
+  listFileNames(req) {
+    const bucket = this.buckets.get(req.bucketId);
+    if (!bucket) return this.error(400, "bad_bucket_id", "Bucket not found");
+    const countError = validateMaxCount(req.maxFileCount, "b2_list_file_names");
+    if (countError) return this.error(400, countError.code, countError.message);
+    const max = req.maxFileCount ?? 1e3;
+    const prefix = req.prefix ?? "";
+    let allFiles = [...bucket.files.entries()].filter(([name]) => name.startsWith(prefix)).map(([_, versions]) => versions[versions.length - 1]).filter((v) => v !== void 0).map((v) => v.fileVersion).sort((a, b) => a.fileName.localeCompare(b.fileName));
+    if (req.startFileName) {
+      const start = req.startFileName;
+      allFiles = allFiles.filter((f) => f.fileName >= start);
+    }
+    const files = allFiles.slice(0, max);
+    const nextFileName = allFiles.length > max ? allFiles[max]?.fileName ?? null : null;
+    return { status: 200, body: { files, nextFileName } };
+  }
+  listFileVersions(req) {
+    const bucket = this.buckets.get(req.bucketId);
+    if (!bucket) return this.error(400, "bad_bucket_id", "Bucket not found");
+    const countError = validateMaxCount(req.maxFileCount, "b2_list_file_versions");
+    if (countError) return this.error(400, countError.code, countError.message);
+    const max = req.maxFileCount ?? 1e3;
+    const prefix = req.prefix ?? "";
+    const allVersions = [...bucket.files.entries()].filter(([name]) => name.startsWith(prefix)).flatMap(([_, versions]) => versions.map((v) => v.fileVersion)).sort((a, b) => {
+      const nameCmp = a.fileName.localeCompare(b.fileName);
+      if (nameCmp !== 0) return nameCmp;
+      return b.uploadTimestamp - a.uploadTimestamp;
+    });
+    let startIdx = 0;
+    if (req.startFileName !== void 0) {
+      const startName = req.startFileName;
+      const startId = req.startFileId;
+      const nameIdx = allVersions.findIndex((f) => f.fileName >= startName);
+      if (nameIdx === -1) {
+        startIdx = allVersions.length;
+      } else if (startId !== void 0) {
+        const exactIdx = allVersions.findIndex((f, i) => i >= nameIdx && f.fileId === startId);
+        startIdx = exactIdx !== -1 ? exactIdx : nameIdx;
+      } else {
+        startIdx = nameIdx;
+      }
+    }
+    const sliced = allVersions.slice(startIdx, startIdx + max);
+    const hasMore = startIdx + max < allVersions.length;
+    const nextFileName = hasMore ? allVersions[startIdx + max]?.fileName ?? null : null;
+    const nextFileId = hasMore ? allVersions[startIdx + max]?.fileId ?? null : null;
+    return { status: 200, body: { files: sliced, nextFileName, nextFileId } };
+  }
+  getFileInfo(req) {
+    const found = this.findFile(req.fileId);
+    if (found === null) return this.error(404, "file_not_present", "File not found");
+    return { status: 200, body: found.stored.fileVersion };
+  }
+  hideFile(req) {
+    const bucket = this.buckets.get(req.bucketId);
+    if (!bucket) return this.error(400, "bad_bucket_id", "Bucket not found");
+    const nameError = validateFileName(req.fileName);
+    if (nameError) return this.error(400, nameError.code, nameError.message);
+    const fileVersion = this.makeFileVersion({
+      bucketId: req.bucketId,
+      fileName: req.fileName,
+      contentType: "application/octet-stream",
+      contentLength: 0,
+      contentSha1: "none",
+      action: FileAction.Hide
+    });
+    const existing = bucket.files.get(req.fileName);
+    const stored = { fileVersion, data: new Uint8Array(0) };
+    if (existing) {
+      existing.push(stored);
+    } else {
+      bucket.files.set(req.fileName, [stored]);
+    }
+    return { status: 200, body: fileVersion };
+  }
+  deleteFileVersion(req) {
+    const found = this.findFile(req.fileId);
+    if (found === null || found.stored.fileVersion.fileName !== req.fileName) {
+      return this.error(400, "file_not_present", "File version not found");
+    }
+    const fv = found.stored.fileVersion;
+    const retention = fv.fileRetention?.value;
+    const legalHold = fv.legalHold?.value;
+    const now = Date.now();
+    if (legalHold === "on") {
+      return this.error(
+        400,
+        "file_lock_legal_hold_protected",
+        "File is on legal hold and cannot be deleted"
+      );
+    }
+    if (retention?.mode === "compliance" && retention.retainUntilTimestamp !== null && retention.retainUntilTimestamp > now) {
+      return this.error(
+        400,
+        "file_lock_compliance_protected",
+        `File is under compliance-mode retention and cannot be deleted until ${new Date(retention.retainUntilTimestamp).toISOString()}`
+      );
+    }
+    if (retention?.mode === "governance" && retention.retainUntilTimestamp !== null && retention.retainUntilTimestamp > now && req.bypassGovernance !== true) {
+      return this.error(
+        400,
+        "file_lock_governance_protected",
+        "File is under governance-mode retention; pass bypassGovernance: true to delete"
+      );
+    }
+    found.versions.splice(found.index, 1);
+    if (found.versions.length === 0) found.bucket.files.delete(req.fileName);
+    return { status: 200, body: { fileId: req.fileId, fileName: req.fileName } };
+  }
+  copyFile(req) {
+    const nameError = validateFileName(req.fileName);
+    if (nameError) return this.error(400, nameError.code, nameError.message);
+    const found = this.findFile(req.sourceFileId);
+    if (found === null) return this.error(404, "file_not_present", "Source file not found");
+    const sourceStored = found.stored;
+    const destBucketId = req.destinationBucketId ?? found.bucketId;
+    const destBucket = this.buckets.get(destBucketId);
+    if (!destBucket) return this.error(400, "bad_bucket_id", "Destination bucket not found");
+    const fileVersion = this.makeFileVersion({
+      bucketId: destBucketId,
+      fileName: req.fileName,
+      contentType: sourceStored.fileVersion.contentType,
+      contentLength: sourceStored.data.byteLength,
+      contentSha1: sourceStored.fileVersion.contentSha1 ?? "none",
+      action: FileAction.Copy
+    });
+    const copied = { fileVersion, data: new Uint8Array(sourceStored.data) };
+    const existing = destBucket.files.get(req.fileName);
+    if (existing) {
+      existing.push(copied);
+    } else {
+      destBucket.files.set(req.fileName, [copied]);
+    }
+    this.firePostUploadHooks(fileVersion, destBucketId, "b2:ObjectCreated:Copy");
+    return { status: 200, body: fileVersion };
+  }
+  startLargeFile(req) {
+    if (!this.buckets.has(req.bucketId)) return this.error(400, "bad_bucket_id", "Bucket not found");
+    const nameError = validateFileName(req.fileName);
+    if (nameError) return this.error(400, nameError.code, nameError.message);
+    if (req.fileInfo !== void 0) {
+      const infoError = validateFileInfo(req.fileInfo);
+      if (infoError) return this.error(400, infoError.code, infoError.message);
+    }
+    const fid = this.genId("4_z");
+    const large = {
+      fileId: fid,
+      bucketId: req.bucketId,
+      fileName: req.fileName,
+      contentType: req.contentType,
+      fileInfo: req.fileInfo ?? {},
+      parts: /* @__PURE__ */ new Map()
+    };
+    this.largeFiles.set(fid, large);
+    return {
+      status: 200,
+      body: {
+        fileId: fid,
+        fileName: req.fileName,
+        accountId: this.accountId,
+        bucketId: req.bucketId,
+        contentType: req.contentType,
+        fileInfo: large.fileInfo
+      }
+    };
+  }
+  getUploadPartUrl(req) {
+    if (!this.largeFiles.has(req.fileId))
+      return this.error(400, "bad_request", "Large file not found");
+    return {
+      status: 200,
+      body: {
+        fileId: req.fileId,
+        uploadUrl: `http://localhost:0/b2api/v3/b2_upload_part?fileId=${req.fileId}`,
+        authorizationToken: "sim_part_token"
+      }
+    };
+  }
+  finishLargeFile(req) {
+    const large = this.largeFiles.get(req.fileId);
+    if (!large) return this.error(400, "bad_request", "Large file not found");
+    const bucket = this.buckets.get(large.bucketId);
+    if (!bucket) return this.error(400, "bad_bucket_id", "Bucket not found");
+    const sortedParts = [...large.parts.entries()].sort((a, b) => a[0] - b[0]);
+    if (sortedParts.length > 1e4) {
+      return this.error(
+        400,
+        "bad_request",
+        `multipart upload has ${sortedParts.length} parts; B2 caps at 10000`
+      );
+    }
+    for (const [partNumber] of sortedParts) {
+      if (!Number.isInteger(partNumber) || partNumber < 1 || partNumber > 1e4) {
+        return this.error(
+          400,
+          "bad_request",
+          `partNumber ${partNumber} is outside the [1, 10000] range B2 accepts`
+        );
+      }
+    }
+    if (req.partSha1Array.length !== sortedParts.length) {
+      return this.error(
+        400,
+        "bad_request",
+        `partSha1Array has ${req.partSha1Array.length} entries but ${sortedParts.length} parts were uploaded`
+      );
+    }
+    for (let i = 0; i < sortedParts.length - 1; i++) {
+      const [partNumber, part] = sortedParts[i];
+      if (part.data.byteLength < this.minimumPartSize) {
+        return this.error(
+          400,
+          "bad_request",
+          `part ${partNumber} (${part.data.byteLength} bytes) is smaller than the minimum part size of ${this.minimumPartSize}`
+        );
+      }
+    }
+    let totalSize = 0;
+    for (const [_, part] of sortedParts) totalSize += part.data.byteLength;
+    const combined = new Uint8Array(totalSize);
+    let offset = 0;
+    for (const [_, part] of sortedParts) {
+      combined.set(part.data, offset);
+      offset += part.data.byteLength;
+    }
+    const fileVersion = this.makeFileVersion({
+      bucketId: large.bucketId,
+      fileName: large.fileName,
+      contentType: large.contentType,
+      contentLength: totalSize,
+      contentSha1: "none",
+      action: FileAction.Upload
+    });
+    const stored = { fileVersion, data: combined };
+    const existing = bucket.files.get(large.fileName);
+    if (existing) {
+      existing.push(stored);
+    } else {
+      bucket.files.set(large.fileName, [stored]);
+    }
+    this.largeFiles.delete(req.fileId);
+    this.firePostUploadHooks(fileVersion, large.bucketId, "b2:ObjectCreated:Upload");
+    return { status: 200, body: fileVersion };
+  }
+  cancelLargeFile(req) {
+    const large = this.largeFiles.get(req.fileId);
+    if (!large) return this.error(400, "bad_request", "Large file not found");
+    this.largeFiles.delete(req.fileId);
+    return {
+      status: 200,
+      body: {
+        fileId: large.fileId,
+        accountId: this.accountId,
+        bucketId: large.bucketId,
+        fileName: large.fileName
+      }
+    };
+  }
+  listUnfinishedLargeFiles(req) {
+    const countError = validateMaxCount(req.maxFileCount, "b2_list_unfinished_large_files");
+    if (countError) return this.error(400, countError.code, countError.message);
+    const prefix = req.namePrefix ?? "";
+    const max = req.maxFileCount ?? 100;
+    const candidates = [...this.largeFiles.values()].filter((f) => f.bucketId === req.bucketId).filter((f) => f.fileName.startsWith(prefix)).sort((a, b) => a.fileName.localeCompare(b.fileName));
+    let startIndex = 0;
+    if (req.startFileId !== void 0) {
+      const found = candidates.findIndex((f) => f.fileId === req.startFileId);
+      startIndex = found >= 0 ? found : 0;
+    }
+    const slice = candidates.slice(startIndex, startIndex + max);
+    const files = slice.map((f) => ({
+      fileId: f.fileId,
+      fileName: f.fileName,
+      accountId: this.accountId,
+      bucketId: f.bucketId,
+      contentType: f.contentType,
+      fileInfo: f.fileInfo
+    }));
+    const hasMore = startIndex + max < candidates.length;
+    const nextFileId = hasMore ? candidates[startIndex + max]?.fileId ?? null : null;
+    return { status: 200, body: { files, nextFileId } };
+  }
+  listParts(req) {
+    const large = this.largeFiles.get(req.fileId);
+    if (!large) return this.error(400, "bad_request", "Large file not found");
+    const countError = validateMaxCount(req.maxPartCount, "b2_list_parts");
+    if (countError) return this.error(400, countError.code, countError.message);
+    const start = req.startPartNumber ?? 1;
+    const max = req.maxPartCount ?? 1e3;
+    const allParts = [...large.parts.entries()].filter(([n]) => n >= start).sort((a, b) => a[0] - b[0]).map(([partNumber, part]) => ({
+      fileId: req.fileId,
+      partNumber,
+      contentLength: part.data.byteLength,
+      contentSha1: part.sha1,
+      uploadTimestamp: Date.now()
+    }));
+    const parts = allParts.slice(0, max);
+    const nextPartNumber = allParts.length > max ? allParts[max]?.partNumber ?? null : null;
+    return { status: 200, body: { parts, nextPartNumber } };
+  }
+  async copyPart(req) {
+    const large = this.largeFiles.get(req.largeFileId);
+    if (!large) return this.error(400, "bad_request", "Large file not found");
+    const found = this.findFile(req.sourceFileId);
+    if (found === null) return this.error(404, "file_not_present", "Source file not found");
+    const sourceStored = found.stored;
+    let partData = sourceStored.data;
+    if (req.range) {
+      const match = req.range.match(/bytes=(\d+)-(\d+)?/);
+      if (match) {
+        const rs = Number.parseInt(match[1] ?? "0", 10);
+        const re = match[2] !== void 0 ? Number.parseInt(match[2], 10) : sourceStored.data.byteLength - 1;
+        partData = sourceStored.data.slice(rs, re + 1);
+      }
+    }
+    const sha1 = await sha1Hex(partData);
+    large.parts.set(req.partNumber, { data: new Uint8Array(partData), sha1 });
+    return {
+      status: 200,
+      body: {
+        fileId: req.largeFileId,
+        partNumber: req.partNumber,
+        contentLength: partData.byteLength,
+        contentSha1: sha1
+      }
+    };
+  }
+  getDownloadAuthorization(req) {
+    if (!this.buckets.has(req.bucketId)) return this.error(400, "bad_bucket_id", "Bucket not found");
+    return {
+      status: 200,
+      body: {
+        bucketId: req.bucketId,
+        fileNamePrefix: req.fileNamePrefix,
+        authorizationToken: `sim_dl_auth_${this.genId("tok")}`
+      }
+    };
+  }
+  // --- Keys ---
+  createKey(req) {
+    const kid = this.genId("sim_key");
+    const appKey = this.genId("sim_secret");
+    const expiration = req.validDurationInSeconds !== void 0 ? Date.now() + req.validDurationInSeconds * 1e3 : null;
+    const stored = {
+      applicationKeyId: kid,
+      keyName: req.keyName,
+      capabilities: req.capabilities,
+      accountId: req.accountId,
+      applicationKey: appKey,
+      bucketId: req.bucketId ?? null,
+      namePrefix: req.namePrefix ?? null,
+      expirationTimestamp: expiration
+    };
+    this.keys.set(kid, stored);
+    return {
+      status: 200,
+      body: {
+        keyName: stored.keyName,
+        applicationKeyId: stored.applicationKeyId,
+        applicationKey: stored.applicationKey,
+        capabilities: stored.capabilities,
+        accountId: stored.accountId,
+        expirationTimestamp: stored.expirationTimestamp,
+        bucketId: stored.bucketId,
+        namePrefix: stored.namePrefix,
+        options: []
+      }
+    };
+  }
+  listKeys(req) {
+    const countError = validateMaxCount(req.maxKeyCount, "b2_list_keys");
+    if (countError) return this.error(400, countError.code, countError.message);
+    const max = req.maxKeyCount ?? 1e3;
+    let allKeys = [...this.keys.values()].sort(
+      (a, b) => a.applicationKeyId.localeCompare(b.applicationKeyId)
+    );
+    if (req.startApplicationKeyId) {
+      const start = req.startApplicationKeyId;
+      allKeys = allKeys.filter((k) => k.applicationKeyId >= start);
+    }
+    const keys = allKeys.slice(0, max).map((k) => ({
+      keyName: k.keyName,
+      applicationKeyId: k.applicationKeyId,
+      capabilities: k.capabilities,
+      accountId: k.accountId,
+      expirationTimestamp: k.expirationTimestamp,
+      bucketId: k.bucketId,
+      namePrefix: k.namePrefix,
+      options: []
+    }));
+    const nextId = allKeys.length > max ? allKeys[max]?.applicationKeyId ?? null : null;
+    return { status: 200, body: { keys, nextApplicationKeyId: nextId } };
+  }
+  deleteKey(req) {
+    const key = this.keys.get(req.applicationKeyId);
+    if (!key) return this.error(400, "bad_request", "Key not found");
+    this.keys.delete(req.applicationKeyId);
+    for (const [token, scope] of this.issuedTokens.entries()) {
+      if (scope.applicationKeyId === req.applicationKeyId) {
+        this.issuedTokens.delete(token);
+      }
+    }
+    return {
+      status: 200,
+      body: {
+        keyName: key.keyName,
+        applicationKeyId: key.applicationKeyId,
+        capabilities: key.capabilities,
+        accountId: key.accountId,
+        expirationTimestamp: key.expirationTimestamp,
+        bucketId: key.bucketId,
+        namePrefix: key.namePrefix,
+        options: []
+      }
+    };
+  }
+  // --- File lock ---
+  updateFileRetention(req) {
+    const found = this.findFile(req.fileId);
+    if (found === null || found.stored.fileVersion.fileName !== req.fileName) {
+      return this.error(404, "file_not_present", "File not found");
+    }
+    found.versions[found.index] = {
+      fileVersion: {
+        ...found.stored.fileVersion,
+        fileRetention: { isClientAuthorizedToRead: true, value: req.fileRetention }
+      },
+      data: found.stored.data
+    };
+    return {
+      status: 200,
+      body: {
+        fileName: req.fileName,
+        fileId: req.fileId,
+        fileRetention: req.fileRetention
+      }
+    };
+  }
+  updateFileLegalHold(req) {
+    const found = this.findFile(req.fileId);
+    if (found === null || found.stored.fileVersion.fileName !== req.fileName) {
+      return this.error(404, "file_not_present", "File not found");
+    }
+    found.versions[found.index] = {
+      fileVersion: {
+        ...found.stored.fileVersion,
+        legalHold: {
+          isClientAuthorizedToRead: true,
+          value: req.legalHold
+        }
+      },
+      data: found.stored.data
+    };
+    return {
+      status: 200,
+      body: {
+        fileName: req.fileName,
+        fileId: req.fileId,
+        legalHold: req.legalHold
+      }
+    };
+  }
+  // --- Notifications ---
+  getBucketNotificationRules(req) {
+    if (!this.buckets.has(req.bucketId)) return this.error(400, "bad_bucket_id", "Bucket not found");
+    const rules = this.notificationRules.get(req.bucketId) ?? [];
+    return { status: 200, body: { bucketId: req.bucketId, eventNotificationRules: rules } };
+  }
+  setBucketNotificationRules(req) {
+    if (!this.buckets.has(req.bucketId)) return this.error(400, "bad_bucket_id", "Bucket not found");
+    this.notificationRules.set(req.bucketId, req.eventNotificationRules);
+    return {
+      status: 200,
+      body: { bucketId: req.bucketId, eventNotificationRules: req.eventNotificationRules }
+    };
+  }
+  // --- Helpers ---
+  /**
+   * Locates a stored file version by its `fileId`, scanning every bucket.
+   *
+   * Returns enough context to support read-only inspection (`stored`,
+   * `bucketId`) AND in-place mutation (`versions`, `index`) so callers
+   * that need to splice the version out can do so without re-scanning.
+   *
+   * Real B2 fileIds embed the bucketId, so production lookups are O(1);
+   * the simulator's flat ID generator (`this.genId('4_z')`) doesn't, so this
+   * is O(buckets × files × versions). Acceptable for tests.
+   *
+   * @param fileId - The file version ID to locate.
+   *
+   * @returns The location of the matching version, or `null` if not found.
+   */
+  findFile(fileId2) {
+    for (const [bid, bucket] of this.buckets.entries()) {
+      for (const versions of bucket.files.values()) {
+        const idx = versions.findIndex((v) => v.fileVersion.fileId === fileId2);
+        if (idx !== -1) {
+          const stored = versions[idx];
+          return { stored, bucketId: bid, bucket, versions, index: idx };
+        }
+      }
+    }
+    return null;
+  }
+  makeFileVersion(params) {
+    return {
+      accountId: accountId(this.accountId),
+      action: params.action,
+      bucketId: bucketId(params.bucketId),
+      contentLength: params.contentLength,
+      contentMd5: null,
+      contentSha1: params.contentSha1,
+      contentType: params.contentType,
+      fileId: fileId(this.genId("4_z")),
+      fileInfo: {},
+      fileName: params.fileName,
+      fileRetention: { isClientAuthorizedToRead: true, value: null },
+      legalHold: { isClientAuthorizedToRead: true, value: null },
+      replicationStatus: null,
+      serverSideEncryption: { mode: EncryptionMode.None },
+      uploadTimestamp: this.monotonicTimestamp()
+    };
+  }
+  error(status, code, message) {
+    return { status, body: { status, code, message } };
+  }
+  /**
+   * Fire the pluggable post-upload hooks for a file that just landed in
+   * a bucket: matching event-notification rules → `onWebhookDeliver`,
+   * configured replication source rules → `onReplicate`. Errors thrown
+   * from user-supplied hooks are swallowed so a buggy listener never
+   * masks an otherwise-successful API response.
+   *
+   * Fired-and-forgotten (no await) by the handler so the synthetic
+   * response is returned to the caller as fast as production B2 would
+   * acknowledge the write.
+   *
+   * @param fileVersion - The freshly-stored file metadata.
+   * @param bucketId - The bucket the upload landed in.
+   * @param eventType - The B2 event-type tag (e.g. `'b2:ObjectCreated:Upload'`)
+   *   used to match against `EventNotificationRule.eventTypes` globs.
+   */
+  firePostUploadHooks(fileVersion, bucketId2, eventType) {
+    const bucket = this.buckets.get(bucketId2);
+    if (!bucket) return;
+    if (this.onWebhookDeliver !== void 0) {
+      const rules = this.notificationRules.get(bucketId2) ?? [];
+      for (const rule of rules) {
+        if (!rule.isEnabled) continue;
+        const matches = rule.eventTypes.some((pattern) => eventTypeMatches(pattern, eventType));
+        if (!matches) continue;
+        const hook = this.onWebhookDeliver;
+        this.dispatchHook("webhook", () => hook({ rule, fileVersion, bucketId: bucketId2 }));
+      }
+    }
+    if (this.onReplicate !== void 0) {
+      const replConfig = bucket.info.replicationConfiguration;
+      const sourceRules = replConfig.asReplicationSource?.replicationRules ?? [];
+      for (const rule of sourceRules) {
+        if (!rule.isEnabled) continue;
+        if (rule.fileNamePrefix && !fileVersion.fileName.startsWith(rule.fileNamePrefix)) continue;
+        const hook = this.onReplicate;
+        this.dispatchHook(
+          "replication",
+          () => hook({
+            sourceFileVersion: fileVersion,
+            sourceBucketId: bucketId2,
+            destinationBucketId: rule.destinationBucketId
+          })
+        );
+      }
+    }
+  }
+  /**
+   * Schedule a user-supplied hook callback. Errors are routed to
+   * `onHookError` if configured, swallowed otherwise. The returned
+   * promise is tracked in {@link pendingHooks} so `flushHooks()` can
+   * wait for every dispatched hook to settle.
+   *
+   * @param kind - Which hook this is (`'webhook'` or `'replication'`).
+   * @param fn - Thunk that performs the hook invocation.
+   */
+  dispatchHook(kind, fn) {
+    const task = Promise.resolve().then(() => fn()).catch((err) => {
+      if (this.onHookError !== void 0) {
+        this.onHookError({ kind, error: toError(err) });
+      }
+    }).finally(() => {
+      this.pendingHooks.delete(task);
+    });
+    this.pendingHooks.add(task);
+  }
+}
+const eventTypeRegexCache = /* @__PURE__ */ new Map();
+function eventTypeMatches(pattern, eventType) {
+  if (!pattern.includes("*")) return pattern === eventType;
+  let compiled = eventTypeRegexCache.get(pattern);
+  if (compiled === void 0) {
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    compiled = new RegExp(`^${escaped}$`);
+    eventTypeRegexCache.set(pattern, compiled);
+  }
+  return compiled.test(eventType);
+}
+function buildFaultResponse(fault) {
+  const status = fault.status ?? 503;
+  const code = fault.code ?? "service_unavailable";
+  const message = fault.message ?? "simulated failure";
+  const body = JSON.stringify({ status, code, message });
+  const headers = new Headers({ "Content-Type": "application/json" });
+  if (fault.retryAfter !== void 0) {
+    headers.set("Retry-After", String(fault.retryAfter));
+  }
+  return {
+    status,
+    headers,
+    body: new ReadableStream({
+      start(controller) {
+        controller.enqueue(utf8Encoder.encode(body));
+        controller.close();
+      }
+    }),
+    json: () => Promise.resolve(JSON.parse(body)),
+    text: () => Promise.resolve(body),
+    arrayBuffer: () => Promise.resolve(utf8Encoder.encode(body).buffer)
+  };
+}
+class SimulatorTransport {
+  constructor(sim) {
+    this.sim = sim;
+  }
+  async send(request) {
+    const url = request.url;
+    const fault = this.sim.consumeMatchingFault(url);
+    if (fault !== null) {
+      return buildFaultResponse(fault);
+    }
+    const headers = {};
+    if (request.headers) {
+      for (const [k, v] of Object.entries(request.headers)) {
+        headers[k.toLowerCase()] = v;
+      }
+    }
+    const isUpload = url.includes("b2_upload_file") || url.includes("b2_upload_part");
+    const parsedUrl = new URL(url);
+    const isDownload = parsedUrl.pathname.includes("b2_download_file_by_id") || parsedUrl.pathname.includes("/file/");
+    if (isDownload) {
+      const method = request.method === "HEAD" ? "HEAD" : "GET";
+      const result2 = this.sim.handleDownload(parsedUrl.pathname + parsedUrl.search, headers, method);
+      const data = result2.data ?? new Uint8Array(0);
+      const responseHeaders = new Headers(result2.headers);
+      responseHeaders.set(
+        "Content-Type",
+        result2.headers["Content-Type"] ?? "application/octet-stream"
+      );
+      const body = method === "HEAD" || result2.data === null ? null : new ReadableStream({
+        start(controller) {
+          controller.enqueue(data);
+          controller.close();
+        }
+      });
+      return {
+        status: result2.status,
+        headers: responseHeaders,
+        body,
+        json: () => Promise.reject(new Error("Download response is not JSON")),
+        text: () => Promise.resolve(utf8Decoder.decode(data)),
+        arrayBuffer: () => Promise.resolve(
+          data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength)
+        )
+      };
+    }
+    let result;
+    if (isUpload && request.body) {
+      const data = new Uint8Array(
+        request.body instanceof ArrayBuffer ? request.body : request.body instanceof Uint8Array ? request.body.buffer.slice(
+          request.body.byteOffset,
+          request.body.byteOffset + request.body.byteLength
+        ) : await new Response(request.body).arrayBuffer()
+      );
+      result = this.sim.handleUpload(url, headers, data);
+    } else {
+      let body = null;
+      if (request.body) {
+        const text = typeof request.body === "string" ? request.body : await new Response(request.body).text();
+        try {
+          body = JSON.parse(text);
+        } catch {
+          body = text;
+        }
+      }
+      result = await this.sim.handleRequest(request.method, parsedUrl.pathname, headers, body);
+    }
+    const responseBody = JSON.stringify(result.body);
+    return {
+      status: result.status,
+      headers: new Headers({ "Content-Type": "application/json" }),
+      body: new ReadableStream({
+        start(controller) {
+          controller.enqueue(utf8Encoder.encode(responseBody));
+          controller.close();
+        }
+      }),
+      json: () => Promise.resolve(result.body),
+      text: () => Promise.resolve(responseBody),
+      arrayBuffer: () => Promise.resolve(utf8Encoder.encode(responseBody).buffer)
+    };
+  }
+}
+export {
+  B2Simulator,
+  BUCKET_INFO_MAX_KEYS,
+  BUCKET_INFO_VALUE_MAX,
+  BUCKET_NAME_MAX,
+  BUCKET_NAME_MIN,
+  FILE_INFO_TOTAL_MAX,
+  FILE_INFO_VALUE_MAX,
+  FILE_NAME_MAX_BYTES,
+  LIST_ENDPOINT_CAPS
+};
+//# sourceMappingURL=index.js.map