@cloudbitmaps/gcs 0.20.0 → 0.22.0

package/dist/index.js

@@ -1,16 +1,31 @@
 // src/backend.ts
-import { ValidationError as ValidationError6, brandAsBackend } from "@cloudbitmaps/core/driver-kit";
+import {
+  ValidationError as ValidationError5,
+  brandAsBackend,
+  refuseUnknownOptions
+} from "@cloudbitmaps/core/driver-kit";
 import { Storage as GcsClient } from "@google-cloud/storage";
 
+// src/defined.ts
+function defined(values) {
+  return Object.fromEntries(Object.entries(values).filter(([, v]) => v !== void 0));
+}
+
 // src/storage.ts
 import {
+  errorKind,
   NotFoundError,
   TransientError as TransientError2,
   ValidationError as ValidationError3,
   WriteConflictError,
-  isNotFoundError,
-  isValidationError,
-  isWriteConflictError
+  concatBytes,
+  normalizeObjectPrefix,
+  parseGenerationFromKey,
+  requireBool,
+  requirePositiveInt,
+  segmentObjectPrefix,
+  storageObjectKey,
+  toTransient
 } from "@cloudbitmaps/core/driver-kit";
 import { createHash, randomBytes } from "node:crypto";
 import { once as once2 } from "node:events";
@@ -19,6 +34,10 @@ import { once as once2 } from "node:events";
 import { TransientError } from "@cloudbitmaps/core/driver-kit";
 
 // src/gcs-errors.ts
+import {
+  ValidationError,
+  isTransportFault as isNodeTransportFault
+} from "@cloudbitmaps/core/driver-kit";
 function httpStatus(err) {
   const e = err;
   if (typeof e?.code === "number") return e.code;
@@ -46,6 +65,17 @@ function isMissingBucket(err) {
   if (says(e.message)) return true;
   return Array.isArray(e.errors) && e.errors.some((inner) => says(inner?.message));
 }
+function missingBucketError(bucket, cause) {
+  return Object.assign(
+    new ValidationError(
+      `the GCS bucket does not exist: ${bucket}; check the bucket name and the project the client is built for`
+    ),
+    { cause }
+  );
+}
+function asMissingBucket(err, bucket) {
+  return isMissingBucket(err) ? missingBucketError(bucket, err) : err;
+}
 function isInvalidRange(err) {
   return httpStatus(err) === 416;
 }
@@ -53,22 +83,11 @@ var SDK_RETRIED_STATUSES = [408, 429, 500, 502, 503, 504];
 function isSdkConnectionProblem(reason) {
   return reason.includes("eai_again") || reason === "econnreset" || reason === "unexpected connection closure" || reason === "epipe" || reason === "socket connection timeout";
 }
-var TRANSPORT_CODES = /* @__PURE__ */ new Set([
-  "ECONNRESET",
-  "ECONNREFUSED",
-  "ECONNABORTED",
-  "ETIMEDOUT",
-  "ENOTFOUND",
-  "EAI_AGAIN",
-  "EHOSTUNREACH",
-  "ENETUNREACH",
-  "EPIPE",
-  "ERR_STREAM_PREMATURE_CLOSE"
-]);
+function isConnectionFault(err) {
+  return isNodeTransportFault(err) || networkCode(err) === "ERR_STREAM_PREMATURE_CLOSE";
+}
 function isTransportFault(err) {
-  if (httpStatus(err) !== void 0) return false;
-  const code = networkCode(err);
-  return code !== void 0 && TRANSPORT_CODES.has(code);
+  return httpStatus(err) === void 0 && isConnectionFault(err);
 }
 function isDownloadRetryable(err) {
   if (err === null || typeof err !== "object") return false;
@@ -92,12 +111,16 @@ function isTransient(err) {
   const status = httpStatus(err);
   if (status === 408 || status === 429 || status !== void 0 && status >= 500 && status < 600)
     return true;
-  const net = networkCode(err);
-  return net !== void 0 && TRANSPORT_CODES.has(net);
+  return isConnectionFault(err);
+}
+function transientFaultMessage(err) {
+  const e = err;
+  return `transient GCS fault: ${String(e?.code ?? e?.name ?? "unknown")}`;
 }
 
 // src/scrub-error.ts
-var DROPPED = /* @__PURE__ */ new Set([
+import { types } from "node:util";
+var TRANSPORT = /* @__PURE__ */ new Set([
   "request",
   "agent",
   "socket",
@@ -107,73 +130,349 @@ var DROPPED = /* @__PURE__ */ new Set([
   "res",
   "config"
 ]);
-var CREDENTIAL_NAME = /^(?:proxy-)?authorization$|^cookie$|^set-cookie$|^x-api-key$/i;
-var CREDENTIAL_LINES = /^((?:proxy-)?authorization|cookie|set-cookie|x-api-key):[^\r\n]*/gim;
+var RESPONSE_FIELDS = ["status", "statusText", "statusCode", "statusMessage"];
+var CREDENTIAL_NAMES = [
+  "authorization",
+  "proxy-authorization",
+  "cookie",
+  "set-cookie",
+  "x-api-key",
+  "x-goog-api-key",
+  "x-goog-encryption-key",
+  "x-goog-copy-source-encryption-key",
+  "encryption-key",
+  "encryption-key-base64",
+  "x-goog-signature",
+  "x-goog-credential",
+  "signature",
+  "signature-provided",
+  "canonical-request",
+  "token",
+  "access-token",
+  "refresh-token",
+  "id-token",
+  "subject-token",
+  "client-secret",
+  "private-key",
+  "assertion"
+];
+var fold = (name) => name.trim().replace(/:$/, "").replace(/[-_]/g, "").toLowerCase();
+var CREDENTIAL_NAME = new Set(CREDENTIAL_NAMES.map(fold));
+var LONGEST_NAME = 64;
+var CREDENTIAL_LINES = /^((?:proxy-)?authorization|cookie|set-cookie|x-api-key|x-goog-api-key|x-goog-(?:copy-source-)?encryption-key):[^\r\n]*/gim;
+var AUTHORIZATION_VALUE = /((?:proxy-)?authorization\\?["']?\s*(?::|=|%3D)\s*\\?["']?)(?:[A-Za-z][\w-]*(?:\s+|%20|\+))?[^\s&"'<>\\,;]+/gi;
+var COOKIE_VALUE = /(?<![\w-])((?:set-)?cookie\\?["']?\s*:\s*\\?["']?)[^\r\n"'<>\\]+/gi;
+var NAMED = "x-goog-(?:copy-source-)?encryption-key|x-goog-api-key|x-goog-signature|x-goog-credential|(?:access|refresh|id|subject)[-_]token|client[-_]secret";
+var NAMED_SECRET = new RegExp(
+  `((?:${NAMED})\\\\?["']?\\s*(?::|=|%3D)\\s*\\\\?["']?)[^\\s&"'<>\\\\,;]+`,
+  "gi"
+);
+var BEARER = /\b(Bearer)(\s+|%20|\+)(?=[A-Za-z0-9\-._~+/]{16})[A-Za-z0-9\-._~+/]+=*/gi;
+var TOKEN_TEXT = /ya29\.(?=[A-Za-z0-9_.-]{16})[A-Za-z0-9_.-]+|(?<![A-Za-z0-9_-])eyJ(?=[A-Za-z0-9_-]{8})[A-Za-z0-9_-]+\.eyJ(?=[A-Za-z0-9_-]{8})[A-Za-z0-9_-]+\.(?=[A-Za-z0-9_-]{16})[A-Za-z0-9_-]+/g;
+var SIGNATURE_NAME = /Signature(?:=|%3D)/gi;
+var SIGNATURE_RUN = /[A-Za-z0-9+/=_.-]*/y;
+var SIGNATURE_MIN = 16;
+var PEM_OPEN = /-----BEGIN [A-Z0-9 ]{0,40}PRIVATE KEY-----/y;
+var PEM_CLOSE = /-----END [A-Z0-9 ]{0,40}PRIVATE KEY-----/y;
+var ELEMENT = /(<([A-Za-z][\w.:-]{0,63})>)([^<]*)(<\/\2>)/g;
+var CELL = /(<([A-Za-z][\w-]{0,15})\b[^<>]{0,256}>\s{0,32}([^<>\s](?:[^<>]{0,62}[^<>\s])?)\s{0,32}<\/\2\s{0,32}>(?:\s{0,32}<\/[A-Za-z][\w-]{0,15}\s{0,32}>){0,4}(?:\s{0,32}<[A-Za-z][\w-]{0,15}\b[^<>]{0,256}>){1,4})([^<]*)/g;
 var REDACTED = "[redacted]";
+var MAX_DEPTH = 10;
 var isPlain = (value) => {
   const proto = Object.getPrototypeOf(value);
   return proto === Object.prototype || proto === null;
 };
-function responseSummary(response) {
-  const out = {};
-  for (const key of ["status", "statusText"]) {
-    const value = response[key];
-    if (typeof value === "number" || typeof value === "string") out[key] = value;
+var isError = (value) => value instanceof Error || types.isNativeError(value);
+var isCredentialName = (text) => text.length <= LONGEST_NAME && CREDENTIAL_NAME.has(fold(text));
+function redactText(text) {
+  try {
+    const named = redactPrivateKeys(text).replace(CREDENTIAL_LINES, `$1: ${REDACTED}`).replace(AUTHORIZATION_VALUE, `$1${REDACTED}`).replace(COOKIE_VALUE, `$1${REDACTED}`).replace(NAMED_SECRET, `$1${REDACTED}`).replace(BEARER, `$1$2${REDACTED}`).replace(TOKEN_TEXT, REDACTED);
+    return redactCells(
+      redactSignatures(named).replace(
+        ELEMENT,
+        (whole, open, tag, inner, close) => isCredentialName(tag) && inner.trim() !== "" ? `${open}${REDACTED}${close}` : whole
+      )
+    );
+  } catch {
+    return REDACTED;
+  }
+}
+function redactPrivateKeys(text) {
+  let out = "";
+  let from = 0;
+  for (let at = text.indexOf("-----BEGIN "); at !== -1; at = text.indexOf("-----BEGIN ", Math.max(at + 1, from))) {
+    PEM_OPEN.lastIndex = at;
+    const open = PEM_OPEN.exec(text);
+    if (open === null) continue;
+    const body = at + open[0].length;
+    const end = text.indexOf("-----END", body);
+    let close = "";
+    if (end !== -1) {
+      PEM_CLOSE.lastIndex = end;
+      close = PEM_CLOSE.exec(text)?.[0] ?? "";
+    }
+    out += `${text.slice(from, body)}${REDACTED}${close}`;
+    from = end === -1 ? text.length : end + close.length;
+  }
+  return from === 0 ? text : out + text.slice(from);
+}
+function redactSignatures(text) {
+  let out = "";
+  let from = 0;
+  SIGNATURE_NAME.lastIndex = 0;
+  for (let m = SIGNATURE_NAME.exec(text); m !== null; m = SIGNATURE_NAME.exec(text)) {
+    const start = m.index + m[0].length;
+    let end = start;
+    for (; ; ) {
+      SIGNATURE_RUN.lastIndex = end;
+      SIGNATURE_RUN.exec(text);
+      end = SIGNATURE_RUN.lastIndex;
+      if (text[end] !== "%" || text.startsWith("%26", end)) break;
+      end += 1;
+    }
+    if (end - start >= SIGNATURE_MIN) {
+      out += `${text.slice(from, start)}${REDACTED}`;
+      from = end;
+    }
+    SIGNATURE_NAME.lastIndex = end;
+  }
+  return from === 0 ? text : out + text.slice(from);
+}
+function redactCells(text) {
+  let out = "";
+  let from = 0;
+  CELL.lastIndex = 0;
+  for (let m = CELL.exec(text); m !== null; m = CELL.exec(text)) {
+    const [whole, head, , name, value] = m;
+    if (isCredentialName(name) && value.trim() !== "") {
+      out += `${text.slice(from, m.index)}${head}${REDACTED}`;
+      from = m.index + whole.length;
+    } else {
+      CELL.lastIndex = m.index + 1;
+    }
   }
-  return out;
+  return from === 0 ? text : out + text.slice(from);
 }
-function clean(value, copies) {
-  if (typeof value === "string") return value.replace(CREDENTIAL_LINES, `$1: ${REDACTED}`);
-  if (typeof value !== "object" || value === null) {
-    return typeof value === "function" || typeof value === "symbol" ? void 0 : value;
-  }
-  if (copies.has(value)) return copies.get(value);
-  if (Array.isArray(value)) {
-    const list = [];
-    copies.set(value, list);
-    for (const item of value) list.push(clean(item, copies));
-    return list;
-  }
-  const isError = value instanceof Error;
-  if (!isError && !isPlain(value)) return void 0;
-  const copy = Object.create(Object.getPrototypeOf(value));
-  copies.set(value, copy);
+var OMIT = /* @__PURE__ */ Symbol("omit");
+var INDEX = /^(?:0|[1-9]\d*)$/;
+var isIndex = (key) => typeof key === "string" && INDEX.test(key) && Number(key) < 2 ** 32 - 1;
+function hasNamedKeys(value) {
+  if (!Array.isArray(value)) return Reflect.ownKeys(value).length > 0;
+  return Reflect.ownKeys(value).some((key) => key !== "length" && !isIndex(key));
+}
+function define(copy, key, value, enumerable) {
+  Object.defineProperty(copy, key, { value, writable: true, configurable: true, enumerable });
+}
+function copyOf(value, ctx, depth) {
+  if (typeof value === "string") {
+    const clean = redactText(value);
+    if (clean !== value) ctx.changed = true;
+    return clean;
+  }
+  if (typeof value === "function" || typeof value === "symbol") {
+    ctx.changed = true;
+    return OMIT;
+  }
+  if (typeof value !== "object" || value === null) return value;
+  if (ctx.copies.has(value)) return ctx.copies.get(value);
+  if (depth > MAX_DEPTH) {
+    ctx.changed = true;
+    return OMIT;
+  }
+  if (Array.isArray(value)) return copyList(value, ctx, depth);
+  if (value instanceof Map) return copyMap(value, ctx, depth);
+  if (value instanceof Set) return copySet(value, ctx, depth);
+  return copyRecord(value, ctx, depth);
+}
+function copyList(value, ctx, depth) {
+  const list = new Array(value.length);
+  ctx.copies.set(value, list);
+  if (hasNamedKeys(value)) ctx.changed = true;
+  let hidden = false;
+  let last = -1;
   for (const key of Reflect.ownKeys(value)) {
-    if (typeof key === "string" && DROPPED.has(key)) continue;
+    if (!isIndex(key)) continue;
+    const index = Number(key);
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (descriptor === void 0 || !("value" in descriptor)) {
+      ctx.changed = true;
+      hidden = false;
+      continue;
+    }
+    const item = descriptor.value;
+    if (hidden && index === last + 1 && item != null) {
+      list[index] = REDACTED;
+      if (item !== REDACTED) ctx.changed = true;
+    } else {
+      const kept = copyOf(item, ctx, depth + 1);
+      if (kept === OMIT) delete list[index];
+      else list[index] = kept;
+    }
+    hidden = typeof item === "string" && isCredentialName(item);
+    last = index;
+  }
+  return list;
+}
+function copyMap(value, ctx, depth) {
+  const map = /* @__PURE__ */ new Map();
+  ctx.copies.set(value, map);
+  if (hasNamedKeys(value)) ctx.changed = true;
+  for (const [k, v] of value) {
+    const key = copyOf(k, ctx, depth + 1);
+    if (key === OMIT) continue;
+    if (typeof k === "string" && isCredentialName(k) && v != null) {
+      map.set(key, REDACTED);
+      if (v !== REDACTED) ctx.changed = true;
+      continue;
+    }
+    const kept = copyOf(v, ctx, depth + 1);
+    if (kept !== OMIT) map.set(key, kept);
+  }
+  return map;
+}
+function copySet(value, ctx, depth) {
+  const set = /* @__PURE__ */ new Set();
+  ctx.copies.set(value, set);
+  if (hasNamedKeys(value)) ctx.changed = true;
+  for (const v of value) {
+    const kept = copyOf(v, ctx, depth + 1);
+    if (kept !== OMIT) set.add(kept);
+  }
+  return set;
+}
+function copyRecord(value, ctx, depth) {
+  const errorLike = isError(value);
+  if (!errorLike && !isPlain(value)) {
+    ctx.changed = true;
+    return OMIT;
+  }
+  const copy = errorLike ? Object.setPrototypeOf(new Error(), Object.getPrototypeOf(value)) : Object.create(Object.getPrototypeOf(value));
+  ctx.copies.set(value, copy);
+  if (errorLike) delete copy.stack;
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key === "string" && TRANSPORT.has(key)) {
+      ctx.changed = true;
+    } else if (errorLike && key === "stack") {
+      copyStack(value, copy, ctx, depth);
+    } else {
+      copyField(value, copy, key, ctx, depth);
+    }
+  }
+  if (errorLike) keepSlotFields(value, copy, ctx, depth);
+  redactPairs(value, copy, errorLike, ctx);
+  return copy;
+}
+var DESCRIBING = /* @__PURE__ */ new Set([
+  "message",
+  "domain",
+  "reason",
+  "location",
+  "locationType",
+  "extendedHelp"
+]);
+function redactPairs(original, copy, errorLike, ctx) {
+  const names = Reflect.ownKeys(original).filter((key) => {
+    if (typeof key !== "string" || DESCRIBING.has(key)) return false;
+    const held = Object.getOwnPropertyDescriptor(original, key)?.value;
+    return typeof held === "string" && isCredentialName(held);
+  });
+  if (names.length === 0) return;
+  const values = errorLike ? names.filter((key) => /name$/i.test(key)).map((key) => `${key.slice(0, -4)}value`.toLowerCase()) : void 0;
+  for (const key of Reflect.ownKeys(copy)) {
+    if (typeof key !== "string" || names.includes(key) || DESCRIBING.has(key)) continue;
+    if (values !== void 0 && !values.includes(key.toLowerCase())) continue;
+    const descriptor = Object.getOwnPropertyDescriptor(copy, key);
+    if (descriptor?.value == null || descriptor.value === REDACTED) continue;
+    if (typeof descriptor.value !== "string" && typeof descriptor.value !== "object") continue;
+    define(copy, key, REDACTED, descriptor.enumerable ?? false);
+    ctx.changed = true;
+  }
+}
+function isSummary(value) {
+  return isPlain(value) && Reflect.ownKeys(value).every((key) => {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    const held = descriptor?.value;
+    return typeof key === "string" && RESPONSE_FIELDS.includes(key) && (typeof held === "number" || typeof held === "string");
+  });
+}
+function copyResponse(response, ctx, depth) {
+  if (isSummary(response)) return copyOf(response, ctx, depth);
+  ctx.changed = true;
+  const summary = {};
+  for (const key of RESPONSE_FIELDS) {
     let held;
     try {
-      held = value[key];
+      held = response[key];
     } catch {
       continue;
     }
-    const descriptor = Object.getOwnPropertyDescriptor(value, key);
-    let kept;
-    if (typeof key === "string" && CREDENTIAL_NAME.test(key)) kept = held == null ? held : REDACTED;
-    else if (key === "response" && typeof held === "object" && held !== null) {
-      kept = responseSummary(held);
-    } else kept = clean(held, copies);
-    if (kept === void 0 && held !== void 0) continue;
-    Object.defineProperty(copy, key, {
-      value: kept,
-      writable: true,
-      configurable: true,
-      enumerable: descriptor?.enumerable ?? true
-    });
+    if (typeof held === "number" || typeof held === "string") {
+      summary[key] = copyOf(held, ctx, depth + 1);
+    }
   }
-  return copy;
+  return summary;
 }
-function holdsTransport(err, seen) {
-  if (seen.has(err)) return false;
-  seen.add(err);
-  if (Object.getOwnPropertyNames(err).some((key) => DROPPED.has(key) || key === "response")) {
-    return true;
+function copyStack(original, copy, ctx, depth) {
+  let stack;
+  try {
+    stack = original.stack;
+  } catch {
+    return;
+  }
+  const kept = copyOf(stack, ctx, depth + 1);
+  if (kept !== OMIT) define(copy, "stack", kept, false);
+}
+function copyField(original, copy, key, ctx, depth) {
+  const descriptor = Object.getOwnPropertyDescriptor(original, key);
+  if (descriptor === void 0) return;
+  if (!("value" in descriptor)) {
+    ctx.changed = true;
+    return;
+  }
+  const name = typeof key === "string" ? redactText(key) : key;
+  if (name !== key) ctx.changed = true;
+  const held = descriptor.value;
+  let kept;
+  if (typeof key === "string" && isCredentialName(key) && held != null) {
+    kept = REDACTED;
+    if (held !== REDACTED) ctx.changed = true;
+  } else if (key === "response" && typeof held === "object" && held !== null) {
+    kept = copyResponse(held, ctx, depth + 1);
+  } else {
+    kept = copyOf(held, ctx, depth + 1);
+    if (kept === OMIT) return;
+  }
+  Object.defineProperty(copy, name, {
+    value: kept,
+    writable: descriptor.writable ?? true,
+    configurable: true,
+    enumerable: descriptor.enumerable ?? false
+  });
+}
+function keepSlotFields(original, copy, ctx, depth) {
+  for (const key of ["name", "message", "code"]) {
+    if (Object.prototype.hasOwnProperty.call(original, key)) continue;
+    let held;
+    try {
+      held = original[key];
+    } catch {
+      continue;
+    }
+    let read = OMIT;
+    try {
+      read = copy[key];
+    } catch {
+    }
+    if (read === held) continue;
+    const kept = copyOf(held, ctx, depth + 1);
+    if (kept !== OMIT) define(copy, key, kept, false);
   }
-  const cause = err.cause;
-  return typeof cause === "object" && cause !== null && holdsTransport(cause, seen);
 }
 function scrubCredentials(err) {
   if (typeof err !== "object" || err === null) return err;
-  return holdsTransport(err, /* @__PURE__ */ new Set()) ? clean(err, /* @__PURE__ */ new WeakMap()) : err;
+  const ctx = { copies: /* @__PURE__ */ new WeakMap(), changed: false };
+  const copy = copyOf(err, ctx, 0);
+  return ctx.changed && copy !== OMIT ? copy : err;
 }
 
 // src/bucket-presence.ts
@@ -186,7 +485,7 @@ var BucketPresence = class {
   bucket;
   settled = false;
   asking;
-  /** Resolve when a 404 can be read as an object's; reject when the bucket does not exist or the listing failed in transit. */
+  /** Resolve when a 404 can be read as an object's; reject with `ValidationError` when the bucket does not exist, `TransientError` when the listing failed in transit. */
   async confirm() {
     if (this.settled) return;
     this.asking ??= this.ask().finally(() => {
@@ -205,7 +504,7 @@ var BucketPresence = class {
       const err = scrubCredentials(failure.raised);
       const status = err?.code;
       if (status === 404) {
-        throw new Error(`the GCS bucket does not exist: ${this.bucket}`, { cause: err });
+        throw missingBucketError(this.bucket, err);
       }
       if (isTransient(err)) {
         throw new TransientError(
@@ -221,34 +520,6 @@ var BucketPresence = class {
   }
 };
 
-// src/keys.ts
-import {
-  ValidationError,
-  encodeNameForKey,
-  namespaceKeyPart,
-  prefixPart,
-  validateSegmentRef
-} from "@cloudbitmaps/core/driver-kit";
-import { normalizeObjectPrefix } from "@cloudbitmaps/core/driver-kit";
-var SUFFIX = ".crbm";
-function segmentObjectPrefix(prefix, ref) {
-  validateSegmentRef(ref);
-  return `${prefixPart(prefix)}${namespaceKeyPart(ref.namespace)}/segments/${encodeNameForKey(ref.segment)}.`;
-}
-function storageObjectName(prefix, key) {
-  if (!Number.isInteger(key.generation) || key.generation < 0) {
-    throw new ValidationError(`generation must be a non-negative integer; got ${key.generation}`);
-  }
-  return `${segmentObjectPrefix(prefix, key)}${key.generation}${SUFFIX}`;
-}
-function parseGenerationFromName(segmentPrefix, objectName) {
-  if (!objectName.startsWith(segmentPrefix) || !objectName.endsWith(SUFFIX)) return null;
-  const middle = objectName.slice(segmentPrefix.length, objectName.length - SUFFIX.length);
-  if (!/^(0|[1-9]\d*)$/.test(middle)) return null;
-  const generation = Number(middle);
-  return Number.isSafeInteger(generation) ? generation : null;
-}
-
 // src/read-timeout.ts
 import { ValidationError as ValidationError2 } from "@cloudbitmaps/core/driver-kit";
 var DEFAULT_READ_TIMEOUT_MS = 0;
@@ -411,13 +682,18 @@ function readOnce(file, options, maxBytes, oversize, deadline) {
 }
 
 // src/storage.ts
-var DEFAULT_MAX_OBJECT_BYTES = 5 * 1024 * 1024 * 1024 * 1024;
+var GCS_MAX_OBJECT_BYTES = 5 * 1024 ** 4;
 var WRITE_ID_KEY = "cbwid";
 var THROTTLE_RESENDS = 3;
 var THROTTLE_BASE_DELAY_MS = 500;
 var REAL_TIME = {
   sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
 };
+var REAL_RNG = { next: () => Math.random() };
+function isTypedPassThrough(err) {
+  const kind = errorKind(err);
+  return kind === "ValidationError" || kind === "WriteConflictError" || kind === "NotFoundError";
+}
 var DEFAULT_UPLOAD_THRESHOLD_BYTES = 8 * 1024 * 1024;
 var GcsStorageDriver = class {
   storage;
@@ -428,34 +704,25 @@ var GcsStorageDriver = class {
   threshold;
   readTimeoutMs;
   clock;
+  rng;
   presence;
   conditionalDelete;
   constructor(options) {
     this.storage = options.storage;
-    if (options.conditionalDelete !== void 0 && typeof options.conditionalDelete !== "boolean") {
-      throw new ValidationError3(
-        `conditionalDelete must be a boolean; got ${String(options.conditionalDelete)}`
-      );
-    }
-    this.conditionalDelete = options.conditionalDelete ?? false;
+    this.conditionalDelete = requireBool("conditionalDelete", options.conditionalDelete) ?? false;
     this.clock = options.clock ?? REAL_TIME;
+    this.rng = options.rng ?? REAL_RNG;
     this.readStorage = options.readStorage ?? options.storage;
     this.bucket = options.bucket;
     this.prefix = normalizeObjectPrefix(options.prefix);
-    for (const [name, value] of [
-      ["maxObjectBytes", options.maxObjectBytes],
-      ["simpleUploadThresholdBytes", options.simpleUploadThresholdBytes]
-    ]) {
-      if (value !== void 0 && (!Number.isSafeInteger(value) || value < 1)) {
-        throw new ValidationError3(`${name} must be a positive safe integer; got ${value}`);
-      }
-    }
-    if (options.maxObjectBytes !== void 0 && options.maxObjectBytes > 5 * 1024 ** 4) {
+    requirePositiveInt("maxObjectBytes", options.maxObjectBytes);
+    requirePositiveInt("simpleUploadThresholdBytes", options.simpleUploadThresholdBytes);
+    if (options.maxObjectBytes !== void 0 && options.maxObjectBytes > GCS_MAX_OBJECT_BYTES) {
       throw new ValidationError3(
-        `maxObjectBytes must be at most GCS's 5 TiB object limit (${5 * 1024 ** 4}); got ${options.maxObjectBytes}`
+        `maxObjectBytes must be at most GCS's 5 TiB object limit (${GCS_MAX_OBJECT_BYTES}); got ${options.maxObjectBytes}`
       );
     }
-    this.maxObjectBytes = options.maxObjectBytes ?? DEFAULT_MAX_OBJECT_BYTES;
+    this.maxObjectBytes = options.maxObjectBytes ?? GCS_MAX_OBJECT_BYTES;
     this.threshold = options.simpleUploadThresholdBytes ?? DEFAULT_UPLOAD_THRESHOLD_BYTES;
     this.readTimeoutMs = resolveReadTimeoutMs(options.readTimeoutMs);
     this.presence = new BucketPresence(this.storage, this.bucket);
@@ -480,12 +747,13 @@ var GcsStorageDriver = class {
     return startDeadline(this.readTimeoutMs, `${read} of ${key.segment}.${key.generation}`);
   }
   async putImmutable(key, write) {
-    const objectName = storageObjectName(this.prefix, key);
+    const objectName = storageObjectKey(this.prefix, key);
     const sink = new GcsUploadSink(
       this.file(objectName),
       this.maxObjectBytes,
       this.threshold,
-      this.clock
+      this.clock,
+      this.rng
     );
     try {
       await write(sink);
@@ -497,7 +765,8 @@ var GcsStorageDriver = class {
           `generation already exists (write-once): ${key.segment}.${key.generation}`
         );
       }
-      if (isValidationError(err) || isWriteConflictError(err) || isNotFoundError(err)) throw err;
+      if (isTypedPassThrough(err)) throw err;
+      if (isNotFound(err)) await this.presence.confirm();
       throw this.mapError(err);
     }
   }
@@ -506,7 +775,7 @@ var GcsStorageDriver = class {
       throw new ValidationError3(`invalid range offset=${offset} length=${length}`);
     }
     if (length === 0) return new Uint8Array(0);
-    const objectName = storageObjectName(this.prefix, key);
+    const objectName = storageObjectKey(this.prefix, key);
     try {
       const deadline = this.deadline("range read", key);
       const res = await retryDownload(
@@ -565,16 +834,16 @@ var GcsStorageDriver = class {
     );
   }
   async getTail(key, maxBytes) {
-    const objectName = storageObjectName(this.prefix, key);
+    const objectName = storageObjectKey(this.prefix, key);
+    if (!Number.isSafeInteger(maxBytes)) {
+      throw new ValidationError3(`invalid tail length ${String(maxBytes)}`);
+    }
     const deadline = this.deadline("tail read", key);
     try {
       if (maxBytes <= 0) {
         const meta = await this.metadataOf(objectName, deadline);
         return withVersion({ bytes: new Uint8Array(0), size: meta.size }, meta.version);
       }
-      if (!Number.isSafeInteger(maxBytes)) {
-        throw new ValidationError3(`invalid tail length ${maxBytes}`);
-      }
       let res;
       try {
         res = await retryDownload(
@@ -662,7 +931,7 @@ var GcsStorageDriver = class {
     return new ValidationError3(`GCS tail read of ${key.segment}.${key.generation} refused: ${why}`);
   }
   async delete(key, options) {
-    const objectName = storageObjectName(this.prefix, key);
+    const objectName = storageObjectKey(this.prefix, key);
     const ifVersion = options?.ifVersion;
     const conditional = ifVersion !== void 0 && this.conditionalDelete;
     try {
@@ -699,10 +968,11 @@ var GcsStorageDriver = class {
     try {
       [files] = await this.storage.bucket(this.bucket).getFiles({ prefix });
     } catch (err) {
+      if (isNotFound(err)) throw missingBucketError(this.bucket, scrubCredentials(err));
       throw this.mapError(err);
     }
     for (const f of files) {
-      const generation = parseGenerationFromName(prefix, f.name);
+      const generation = parseGenerationFromKey(prefix, f.name);
       if (generation !== null) {
         yield { namespace: ref.namespace, segment: ref.segment, generation };
       }
@@ -716,38 +986,25 @@ var GcsStorageDriver = class {
   /** Map GCS read errors to the driver vocabulary; pass everything else through {@link mapError}. */
   mapReadError(err, key) {
     err = scrubCredentials(err);
-    if (isValidationError(err)) return err;
+    if (errorKind(err) === "ValidationError") return err;
     if (isNotFound(err))
       return new NotFoundError(`no such generation: ${key.segment}.${key.generation}`);
     if (isInvalidRange(err)) {
       return new ValidationError3(`range out of bounds for ${key.segment}.${key.generation}`);
     }
     if (err instanceof ReadTimedOut) return new TransientError2(err.message, { cause: err });
-    if (isTransportFault(err)) {
-      return new TransientError2(
-        `transient GCS fault: ${String(err.code)}`,
-        {
-          cause: err
-        }
-      );
-    }
     return this.mapError(err);
   }
   /**
-   * Reclassify a transient GCS fault (throttle/5xx/dropped connection) as a retryable {@link TransientError},
-   * so the store's read retry can ride it out and a write's caller can tell it from a deterministic failure;
-   * everything else propagates unchanged. The final fallback at every client-call site: an HTTP status and a fault
-   * in transit arrive typed, and anything else (a checksum mismatch, a credentials failure) as the SDK raised it.
+   * Reclassify a transient GCS fault (throttle/5xx/dropped connection) as a retryable {@link TransientError}, so the
+   * store's read retry can ride it out and a write's caller can tell it from a deterministic failure, and a missing
+   * bucket as a `ValidationError` that names it; everything else propagates unchanged. The final fallback at every
+   * client-call site: an HTTP status and a fault in transit arrive typed, and anything else (a checksum mismatch, a
+   * credentials failure) as the SDK raised it.
    */
   mapError(err) {
-    err = scrubCredentials(err);
-    if (isTransient(err)) {
-      return new TransientError2(
-        `transient GCS fault: ${err?.code ?? "unknown"}`,
-        { cause: err }
-      );
-    }
-    return err;
+    const scrubbed = asMissingBucket(scrubCredentials(err), this.bucket);
+    return toTransient(scrubbed, isTransient, transientFaultMessage);
   }
 };
 function withVersion(tail, version) {
@@ -764,26 +1021,19 @@ function generationOf(version, key) {
   }
   return Number(version);
 }
-function concatBytes(parts, total) {
-  const out = new Uint8Array(total);
-  let offset = 0;
-  for (const p of parts) {
-    out.set(p, offset);
-    offset += p.length;
-  }
-  return out;
-}
 var GcsUploadSink = class _GcsUploadSink {
-  constructor(file, maxObjectBytes, threshold, clock) {
+  constructor(file, maxObjectBytes, threshold, clock, rng) {
     this.file = file;
     this.maxObjectBytes = maxObjectBytes;
     this.threshold = threshold;
     this.clock = clock;
+    this.rng = rng;
   }
   file;
   maxObjectBytes;
   threshold;
   clock;
+  rng;
   hash = createHash("sha256");
   total = 0;
   buffered = [];
@@ -837,7 +1087,7 @@ var GcsUploadSink = class _GcsUploadSink {
       this.failure ??= e;
     });
     this.done.catch(() => void 0);
-    const buf = concatBytes(this.buffered, this.bufferedLen);
+    const buf = concatBytes(this.buffered);
     this.buffered.length = 0;
     this.bufferedLen = 0;
     stream.write(buf);
@@ -845,7 +1095,7 @@ var GcsUploadSink = class _GcsUploadSink {
   async finish() {
     const sha256 = this.hash.digest("hex");
     if (this.stream === void 0) {
-      await this.sendSimple(concatBytes(this.buffered, this.bufferedLen));
+      await this.sendSimple(concatBytes(this.buffered));
       return { size: this.total, sha256 };
     }
     try {
@@ -881,7 +1131,7 @@ var GcsUploadSink = class _GcsUploadSink {
             { cause: err }
           );
         }
-        await this.clock.sleep(Math.floor(Math.random() * THROTTLE_BASE_DELAY_MS * 2 ** resent));
+        await this.clock.sleep(Math.floor(this.rng.next() * THROTTLE_BASE_DELAY_MS * 2 ** resent));
       }
     }
   }
@@ -906,9 +1156,10 @@ import {
   MAX_ROW_BYTES,
   ObjectStoreRegistry,
   TransientError as TransientError3,
-  ValidationError as ValidationError4,
   WriteConflictError as WriteConflictError2,
-  normalizeObjectPrefix as normalizeObjectPrefix2
+  normalizeObjectPrefix as normalizeObjectPrefix2,
+  requireBool as requireBool2,
+  toTransient as toTransient2
 } from "@cloudbitmaps/core/driver-kit";
 
 // src/crc32c.ts
@@ -976,7 +1227,7 @@ var GcsRegistryStore = class {
         await this.presence.confirm();
         return null;
       }
-      throw mapReadError(err);
+      throw mapReadError(err, this.bucket);
     }
     if (res.status !== 200) {
       throw new IntegrityError(`registry read answered HTTP ${res.status}, not 200: ${key}`);
@@ -1004,7 +1255,8 @@ var GcsRegistryStore = class {
       if (isPreconditionFailed(err)) {
         throw new WriteConflictError2(`registry OCC conflict for ${key}`);
       }
-      throw mapError(err);
+      if (isNotFound(err)) await this.presence.confirm();
+      throw mapError(err, this.bucket);
     }
   }
   async delete(key, expect) {
@@ -1015,7 +1267,7 @@ var GcsRegistryStore = class {
         if (isNotFound(err)) await this.presence.confirm();
         throw new WriteConflictError2(`registry OCC conflict deleting ${key}`);
       }
-      throw mapError(err);
+      throw mapError(err, this.bucket);
     }
   }
   async *listKeys(prefix) {
@@ -1026,7 +1278,8 @@ var GcsRegistryStore = class {
       try {
         [files, next] = await this.storage.bucket(this.bucket).getFiles({ prefix, autoPaginate: false, maxResults: 1e3, pageToken });
       } catch (err) {
-        throw mapError(err);
+        if (isNotFound(err)) throw missingBucketError(this.bucket, scrubCredentials(err));
+        throw mapError(err, this.bucket);
       }
       for (const f of files ?? []) yield f.name;
       if (next?.pageToken !== void 0 && next.pageToken === pageToken) {
@@ -1043,34 +1296,17 @@ function generationFence(version, key) {
   }
   return generation;
 }
-function mapReadError(err) {
+function mapReadError(err, bucket) {
   err = scrubCredentials(err);
   if (err instanceof ReadTimedOut) return new TransientError3(err.message, { cause: err });
-  if (isTransportFault(err)) {
-    return new TransientError3(`transient GCS fault: ${String(err.code)}`, {
-      cause: err
-    });
-  }
-  return mapError(err);
-}
-function mapError(err) {
-  err = scrubCredentials(err);
-  if (isTransient(err)) {
-    return new TransientError3(
-      `transient GCS fault: ${err?.code ?? err?.name ?? "unknown"}`,
-      { cause: err }
-    );
-  }
-  return err;
+  return mapError(err, bucket);
 }
-function resolveConditionalDelete(value) {
-  if (value === void 0) {
-    return false;
-  }
-  if (typeof value !== "boolean") {
-    throw new ValidationError4(`conditionalDelete must be a boolean; got ${String(value)}`);
-  }
-  return value;
+function mapError(err, bucket) {
+  return toTransient2(
+    asMissingBucket(scrubCredentials(err), bucket),
+    isTransient,
+    transientFaultMessage
+  );
 }
 var GcsRegistryDriver = class extends ObjectStoreRegistry {
   constructor(options) {
@@ -1080,7 +1316,7 @@ var GcsRegistryDriver = class extends ObjectStoreRegistry {
         options.readStorage ?? options.storage,
         options.bucket,
         resolveReadTimeoutMs(options.readTimeoutMs),
-        resolveConditionalDelete(options.conditionalDelete)
+        requireBool2("conditionalDelete", options.conditionalDelete) ?? false
       ),
       normalizeObjectPrefix2(options.prefix),
       options.now ?? (() => Date.now())
@@ -1089,7 +1325,7 @@ var GcsRegistryDriver = class extends ObjectStoreRegistry {
 };
 
 // src/read-client.ts
-import { ValidationError as ValidationError5 } from "@cloudbitmaps/core/driver-kit";
+import { ValidationError as ValidationError4 } from "@cloudbitmaps/core/driver-kit";
 function downloadClient(client, supplied) {
   if (!isSdkClient(client)) {
     if (client.retryOptions?.autoRetry === false) return client;
@@ -1135,12 +1371,12 @@ function isSdkClient(client) {
   return client.authClient !== void 0 && typeof factory === "function" && factory.authClient === client.authClient;
 }
 function overridesBucket(client) {
-  let defined = 0;
+  let defined2 = 0;
   for (let proto = Object.getPrototypeOf(client); proto !== null; ) {
-    if (Object.hasOwn(proto, "bucket")) defined++;
+    if (Object.hasOwn(proto, "bucket")) defined2++;
     proto = Object.getPrototypeOf(proto);
   }
-  return defined > 1;
+  return defined2 > 1;
 }
 function twinOf(client) {
   const Own = client.constructor;
@@ -1190,7 +1426,7 @@ function unfaithful(client, twin) {
   return void 0;
 }
 function refusal(supplied, why, remedy, cause) {
-  const err = new ValidationError5(
+  const err = new ValidationError4(
     (supplied ? `GcsStorage cannot send the supplied client's downloads without the SDK's retries: ${why}` : `GcsStorage cannot build a client that sends downloads without the SDK's retries: ${why}`) + (remedy === void 0 ? "" : `. ${remedy}`)
   );
   if (cause !== void 0) err.cause = scrubCredentials(cause);
@@ -1211,20 +1447,6 @@ var GCS_STORAGE_OPTION_KEYS = [
   "conditionalDelete"
 ];
 var CLIENT_SETTINGS = ["projectId", "apiEndpoint"];
-function refuseUnknown(name, options, keys, hint) {
-  if (options === null || typeof options !== "object") {
-    throw new ValidationError6(
-      `${name} needs an options object \u2014 got ${options === null ? "null" : typeof options}`
-    );
-  }
-  const unknown = Object.keys(options).filter((k) => !keys.includes(k));
-  if (unknown.length > 0) {
-    const list = (ks) => ks.map((k) => `\`${k}\``).join(", ");
-    throw new ValidationError6(
-      `${name} does not take ${list(unknown)}. It takes ${list(keys)}; ${hint}.`
-    );
-  }
-}
 var GcsStorage = class {
   storage;
   registry;
@@ -1232,54 +1454,52 @@ var GcsStorage = class {
   client;
   constructor(options) {
     let readClient;
-    refuseUnknown(
+    refuseUnknownOptions(
       "GcsStorage",
       options,
       GCS_STORAGE_OPTION_KEYS,
       "a @google-cloud/storage client goes in `client`"
     );
     if (typeof options.bucket !== "string" || options.bucket.length === 0) {
-      throw new ValidationError6("GcsStorage needs a `bucket`: the name of one, a non-empty string");
+      throw new ValidationError5("GcsStorage needs a `bucket`: the name of one, a non-empty string");
     }
     if (options.now !== void 0 && typeof options.now !== "function") {
-      throw new ValidationError6(
+      throw new ValidationError5(
         "GcsStorage's `now` must be a function that returns epoch milliseconds"
       );
     }
     if (options.client !== void 0 && options.client !== null) {
       const ignored = CLIENT_SETTINGS.filter((k) => options[k] !== void 0);
       if (ignored.length > 0) {
-        throw new ValidationError6(
+        throw new ValidationError5(
           `GcsStorage takes \`client\` OR ${CLIENT_SETTINGS.map((k) => `\`${k}\``).join(" / ")}, not both \u2014 got \`client\` with ${ignored.map((k) => `\`${k}\``).join(", ")}; the \`client\` already carries them, so configure them on the client, or drop \`client\``
         );
       }
       this.client = options.client;
       readClient = downloadClient(options.client, true);
     } else {
-      const settings = {
-        ...options.projectId === void 0 ? {} : { projectId: options.projectId },
-        ...options.apiEndpoint === void 0 ? {} : { apiEndpoint: options.apiEndpoint }
-      };
-      this.client = new GcsClient(settings);
+      this.client = new GcsClient(
+        defined({ projectId: options.projectId, apiEndpoint: options.apiEndpoint })
+      );
       readClient = downloadClient(this.client, false);
     }
     const shared = {
       storage: this.client,
       readStorage: readClient,
       bucket: options.bucket,
-      ...options.prefix === void 0 ? {} : { prefix: options.prefix },
-      ...options.readTimeoutMs === void 0 ? {} : { readTimeoutMs: options.readTimeoutMs }
+      ...defined({ prefix: options.prefix, readTimeoutMs: options.readTimeoutMs })
     };
     this.storage = new GcsStorageDriver({
       ...shared,
-      ...options.maxObjectBytes === void 0 ? {} : { maxObjectBytes: options.maxObjectBytes },
-      ...options.simpleUploadThresholdBytes === void 0 ? {} : { simpleUploadThresholdBytes: options.simpleUploadThresholdBytes },
-      ...options.conditionalDelete === void 0 ? {} : { conditionalDelete: options.conditionalDelete }
+      ...defined({
+        maxObjectBytes: options.maxObjectBytes,
+        simpleUploadThresholdBytes: options.simpleUploadThresholdBytes,
+        conditionalDelete: options.conditionalDelete
+      })
     });
     this.registry = new GcsRegistryDriver({
       ...shared,
-      ...options.now === void 0 ? {} : { now: options.now },
-      ...options.conditionalDelete === void 0 ? {} : { conditionalDelete: options.conditionalDelete }
+      ...defined({ now: options.now, conditionalDelete: options.conditionalDelete })
     });
     brandAsBackend(this);
   }