@cloudbitmaps/gcs 0.21.0 → 0.23.0

package/dist/index.js

@@ -2,7 +2,10 @@
 import {
   ValidationError as ValidationError5,
   brandAsBackend,
-  refuseUnknownOptions
+  normalizeObjectPrefix as normalizeObjectPrefix3,
+  prefixPart,
+  refuseUnknownOptions,
+  requireNonEmptyString
 } from "@cloudbitmaps/core/driver-kit";
 import { Storage as GcsClient } from "@google-cloud/storage";
 
@@ -11,18 +14,538 @@ function defined(values) {
   return Object.fromEntries(Object.entries(values).filter(([, v]) => v !== void 0));
 }
 
+// src/read-timeout.ts
+import { ValidationError } from "@cloudbitmaps/core/driver-kit";
+var DEFAULT_READ_TIMEOUT_MS = 0;
+var MAX_TIMER_MS = 2147483647;
+function resolveReadTimeoutMs(value) {
+  if (value === void 0) return DEFAULT_READ_TIMEOUT_MS;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > MAX_TIMER_MS) {
+    throw new ValidationError(
+      `readTimeoutMs must be a non-negative safe integer no larger than ${MAX_TIMER_MS}; got ${describe(value)}`
+    );
+  }
+  return value;
+}
+function describe(value) {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  return value === null ? "null" : typeof value;
+}
+var ReadTimedOut = class extends Error {
+  code = "ETIMEDOUT";
+  constructor(read, ms, cause) {
+    super(`GCS ${read} timed out after ${ms} ms`, cause === void 0 ? void 0 : { cause });
+    this.name = "ReadTimedOut";
+  }
+};
+var Deadline = class {
+  constructor(ms, read) {
+    this.ms = ms;
+    this.read = read;
+    this.endsAt = performance.now() + ms;
+  }
+  ms;
+  read;
+  endsAt;
+  /** What is left of it, in milliseconds: 0 once it has passed. */
+  remaining() {
+    return Math.max(0, this.endsAt - performance.now());
+  }
+  /** The error a read fails with once this has passed; `cause` is the last attempt's own error, if one failed. */
+  expired(cause) {
+    return new ReadTimedOut(this.read, this.ms, cause);
+  }
+};
+function startDeadline(ms, read) {
+  return ms === 0 ? void 0 : new Deadline(ms, read);
+}
+function withDeadline(send, deadline) {
+  if (deadline === void 0) return send();
+  if (deadline.remaining() === 0) return Promise.reject(deadline.expired());
+  const request = send();
+  let timer;
+  const timedOut = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(deadline.expired()), deadline.remaining());
+  });
+  return Promise.race([request, timedOut]).finally(() => clearTimeout(timer));
+}
+
+// src/scrub-error.ts
+import { types } from "node:util";
+var TRANSPORT = /* @__PURE__ */ new Set([
+  "request",
+  "agent",
+  "socket",
+  "_httpMessage",
+  "connection",
+  "req",
+  "res",
+  "config"
+]);
+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;
+};
+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 from === 0 ? text : out + text.slice(from);
+}
+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 (!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 = response[key];
+    } catch {
+      continue;
+    }
+    if (typeof held === "number" || typeof held === "string") {
+      summary[key] = copyOf(held, ctx, depth + 1);
+    }
+  }
+  return summary;
+}
+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);
+  }
+}
+function scrubCredentials(err) {
+  if (typeof err !== "object" || err === null) return err;
+  const ctx = { copies: /* @__PURE__ */ new WeakMap(), changed: false };
+  const copy = copyOf(err, ctx, 0);
+  return ctx.changed && copy !== OMIT ? copy : err;
+}
+
+// src/lifecycle.ts
+var MAX_MESSAGE = 200;
+var MAX_FIELD = 64;
+var MAX_CONDITION = 120;
+var MAX_NAMED_RULES = 3;
+var cut = (text, max) => text.length > max ? text.slice(0, max) : text;
+var SAFE_ACTIONS = /* @__PURE__ */ new Set([
+  "SetStorageClass",
+  "AbortIncompleteMultipartUpload"
+]);
+var NAME_SUFFIXES = [".crbm", ".reg"];
+var prefixRelated = (a, b) => a.startsWith(b) || b.startsWith(a);
+var suffixRelated = (a, b) => a.endsWith(b) || b.endsWith(a);
+var strings = (value) => Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+var record = (value) => typeof value === "object" && value !== null ? value : {};
+var NONCURRENT_ONLY = ["daysSinceNoncurrentTime", "noncurrentTimeBefore"];
+var metByLiveObject = (value) => typeof value !== "number" || value < 1;
+var actionOf = (rule) => {
+  const type = record(record(rule).action).type;
+  return typeof type === "string" && type !== "" ? type : void 0;
+};
+var isRule = (rule) => typeof rule === "object" && rule !== null;
+function deletesOurs(rule, prefix) {
+  if (!isRule(rule)) return false;
+  const type = actionOf(rule);
+  if (type !== void 0 && SAFE_ACTIONS.has(type)) return false;
+  const when = record(record(rule).condition);
+  if (when.isLive === false) return false;
+  if (NONCURRENT_ONLY.some((key) => when[key] !== void 0)) return false;
+  if (!metByLiveObject(when.numNewerVersions)) return false;
+  const prefixes = strings(when.matchesPrefix);
+  if (prefixes.length > 0 && !prefixes.some((p) => prefixRelated(p, prefix))) return false;
+  const suffixes = strings(when.matchesSuffix);
+  return suffixes.length === 0 || suffixes.some((s) => NAME_SUFFIXES.some((ours) => suffixRelated(s, ours)));
+}
+function sitsInside(rule, prefix) {
+  const prefixes = strings(record(record(rule).condition).matchesPrefix);
+  return prefix !== "" && prefixes.length > 0 && !prefixes.some((p) => p !== prefix && prefix.startsWith(p));
+}
+function judgeMetadata(metadata, prefix) {
+  const rules = record(record(metadata).lifecycle).rule;
+  const found = (Array.isArray(rules) ? rules : []).filter(
+    (r) => deletesOurs(r, prefix)
+  );
+  if (found.length > 0) {
+    const named = found.slice(0, MAX_NAMED_RULES).map(
+      (r) => `${cut(actionOf(r) ?? "no action type", MAX_FIELD)} when ${cut(JSON.stringify(record(r).condition ?? {}), MAX_CONDITION)}`
+    ).join("; ");
+    const more = found.length > MAX_NAMED_RULES ? ` and ${found.length - MAX_NAMED_RULES} more` : "";
+    const quoted = JSON.stringify(cut(prefix, MAX_FIELD));
+    const narrow = `Narrow the rule with matchesPrefix to exclude ${quoted}, or restrict it to noncurrent versions.`;
+    const retarget = `A rule that sits inside ${quoted} cannot be narrowed to exclude it: remove it or retarget it to another prefix, or restrict it to noncurrent versions.`;
+    const where = prefix === "" ? "The store has no prefix, so a rule on any prefix can reach it: give the store a prefix, or scope the rule away from its paths." : [
+      found.some((r) => !sitsInside(r, prefix)) ? narrow : "",
+      found.some((r) => sitsInside(r, prefix)) ? retarget : ""
+    ].filter((x) => x !== "").join(" ");
+    return {
+      status: "problem",
+      detail: `${found.length} bucket lifecycle rule(s) with a Delete action, or one this check does not know, can match objects under ${quoted}: ${named}${more}. The store keeps current objects it must be able to read back. ${where}`
+    };
+  }
+  return {
+    status: "ok",
+    detail: `no bucket lifecycle rule deletes live objects under ${JSON.stringify(cut(prefix, MAX_FIELD))}`
+  };
+}
+function unchecked(err) {
+  if (err instanceof ReadTimedOut) {
+    return {
+      status: "unchecked",
+      detail: "the read of the bucket metadata got no answer in time (readTimeoutMs); run the check again"
+    };
+  }
+  const scrubbed = scrubCredentials(err);
+  const { code, message, name } = record(scrubbed);
+  if (code === 403) {
+    return {
+      status: "unchecked",
+      detail: "the identity may not read the bucket metadata: grant storage.buckets.get on the bucket to check its lifecycle rules, or confirm by hand that no rule deletes current objects under this prefix"
+    };
+  }
+  const shown = typeof message === "string" ? `: ${message.slice(0, MAX_MESSAGE)}` : "";
+  const label = typeof name === "string" ? cut(name, MAX_FIELD) : "Error";
+  const status = typeof code === "number" ? ` ${code}` : "";
+  return {
+    status: "unchecked",
+    detail: `could not read the bucket metadata (${label}${status}${shown}); check the lifecycle rules by hand`
+  };
+}
+async function checkGcsLifecycle(client, bucket, prefix, readTimeoutMs = 0) {
+  try {
+    const [metadata] = await withDeadline(
+      () => client.bucket(bucket).getMetadata(),
+      startDeadline(readTimeoutMs, "bucket metadata read")
+    );
+    return judgeMetadata(metadata, prefix);
+  } catch (err) {
+    try {
+      return unchecked(err);
+    } catch {
+      return { status: "unchecked", detail: "could not read the bucket metadata" };
+    }
+  }
+}
+
 // src/storage.ts
 import {
+  errorKind,
   NotFoundError,
   TransientError as TransientError2,
   ValidationError as ValidationError3,
   WriteConflictError,
   concatBytes,
-  isNotFoundError,
-  isValidationError,
-  isWriteConflictError,
   normalizeObjectPrefix,
   parseGenerationFromKey,
+  checkDeleteOptions,
   requireBool,
   requirePositiveInt,
   segmentObjectPrefix,
@@ -37,7 +560,7 @@ import { TransientError } from "@cloudbitmaps/core/driver-kit";
 
 // src/gcs-errors.ts
 import {
-  ValidationError,
+  ValidationError as ValidationError2,
   isTransportFault as isNodeTransportFault
 } from "@cloudbitmaps/core/driver-kit";
 function httpStatus(err) {
@@ -69,7 +592,7 @@ function isMissingBucket(err) {
 }
 function missingBucketError(bucket, cause) {
   return Object.assign(
-    new ValidationError(
+    new ValidationError2(
       `the GCS bucket does not exist: ${bucket}; check the bucket name and the project the client is built for`
     ),
     { cause }
@@ -120,86 +643,6 @@ function transientFaultMessage(err) {
   return `transient GCS fault: ${String(e?.code ?? e?.name ?? "unknown")}`;
 }
 
-// src/scrub-error.ts
-var DROPPED = /* @__PURE__ */ new Set([
-  "request",
-  "agent",
-  "socket",
-  "_httpMessage",
-  "connection",
-  "req",
-  "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 REDACTED = "[redacted]";
-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;
-  }
-  return out;
-}
-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);
-  for (const key of Reflect.ownKeys(value)) {
-    if (typeof key === "string" && DROPPED.has(key)) continue;
-    let held;
-    try {
-      held = value[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
-    });
-  }
-  return copy;
-}
-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;
-  }
-  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;
-}
-
 // src/bucket-presence.ts
 var BucketPresence = class {
   constructor(storage, bucket) {
@@ -245,65 +688,6 @@ var BucketPresence = class {
   }
 };
 
-// src/read-timeout.ts
-import { ValidationError as ValidationError2 } from "@cloudbitmaps/core/driver-kit";
-var DEFAULT_READ_TIMEOUT_MS = 0;
-var MAX_TIMER_MS = 2147483647;
-function resolveReadTimeoutMs(value) {
-  if (value === void 0) return DEFAULT_READ_TIMEOUT_MS;
-  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > MAX_TIMER_MS) {
-    throw new ValidationError2(
-      `readTimeoutMs must be a non-negative safe integer no larger than ${MAX_TIMER_MS}; got ${describe(value)}`
-    );
-  }
-  return value;
-}
-function describe(value) {
-  if (typeof value === "string") return JSON.stringify(value);
-  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
-    return String(value);
-  }
-  return value === null ? "null" : typeof value;
-}
-var ReadTimedOut = class extends Error {
-  code = "ETIMEDOUT";
-  constructor(read, ms, cause) {
-    super(`GCS ${read} timed out after ${ms} ms`, cause === void 0 ? void 0 : { cause });
-    this.name = "ReadTimedOut";
-  }
-};
-var Deadline = class {
-  constructor(ms, read) {
-    this.ms = ms;
-    this.read = read;
-    this.endsAt = performance.now() + ms;
-  }
-  ms;
-  read;
-  endsAt;
-  /** What is left of it, in milliseconds: 0 once it has passed. */
-  remaining() {
-    return Math.max(0, this.endsAt - performance.now());
-  }
-  /** The error a read fails with once this has passed; `cause` is the last attempt's own error, if one failed. */
-  expired(cause) {
-    return new ReadTimedOut(this.read, this.ms, cause);
-  }
-};
-function startDeadline(ms, read) {
-  return ms === 0 ? void 0 : new Deadline(ms, read);
-}
-function withDeadline(send, deadline) {
-  if (deadline === void 0) return send();
-  if (deadline.remaining() === 0) return Promise.reject(deadline.expired());
-  const request = send();
-  let timer;
-  const timedOut = new Promise((_, reject) => {
-    timer = setTimeout(() => reject(deadline.expired()), deadline.remaining());
-  });
-  return Promise.race([request, timedOut]).finally(() => clearTimeout(timer));
-}
-
 // src/download-retry.ts
 var RETRIES = 3;
 var BASE_DELAY_MS = 100;
@@ -415,6 +799,10 @@ 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;
@@ -486,7 +874,7 @@ 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);
     }
@@ -653,7 +1041,7 @@ var GcsStorageDriver = class {
   }
   async delete(key, options) {
     const objectName = storageObjectKey(this.prefix, key);
-    const ifVersion = options?.ifVersion;
+    const ifVersion = checkDeleteOptions(options);
     const conditional = ifVersion !== void 0 && this.conditionalDelete;
     try {
       await this.file(objectName).delete(
@@ -707,7 +1095,7 @@ 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)) {
@@ -761,6 +1149,10 @@ var GcsUploadSink = class _GcsUploadSink {
   bufferedLen = 0;
   stream;
   // set once we cross the threshold → resumable mode
+  /** The SDK's resumable upload under {@link stream}, which {@link abort} ends with an error: see there. */
+  upload;
+  /** Set by {@link abort}: the held upload starts no request from then on. */
+  abandoned = false;
   done;
   failure;
   static WRITE_OPTS = {
@@ -801,6 +1193,7 @@ var GcsUploadSink = class _GcsUploadSink {
   }
   /** Cross into resumable streaming: open the stream, flush the buffered bytes, keep only ~one threshold resident. */
   startResumable() {
+    this.holdUpload();
     const stream = this.file.createWriteStream({ resumable: true, ...this.tagged() });
     this.stream = stream;
     this.done = once2(stream, "finish");
@@ -866,8 +1259,56 @@ var GcsUploadSink = class _GcsUploadSink {
       throw err;
     }
   }
+  /**
+   * Keep the SDK's resumable upload, the writable its write stream pipes into, so {@link abort} can end its request.
+   * The SDK hands it to the stream's duplex through `setWritable` in `startResumableUpload_`, a method of the `File`
+   * its types declare; this wraps that method on this sink's own `File`, which no other write shares. Where the method
+   * or the duplex's `setWritable` is missing, the SDK runs unchanged, nothing is kept, and an abort destroys the
+   * stream alone, as it did before.
+   */
+  holdUpload() {
+    const file = this.file;
+    const start = file.startResumableUpload_;
+    if (typeof start !== "function") return;
+    file.startResumableUpload_ = (dup, options) => {
+      const setWritable = dup.setWritable;
+      if (typeof setWritable === "function") {
+        dup.setWritable = (writable) => {
+          this.hold(writable);
+          setWritable.call(dup, writable);
+        };
+      }
+      start.call(file, dup, options);
+    };
+  }
+  /**
+   * Keep `upload`, and let it start no request once this sink is abandoned. The SDK registers the listener that
+   * aborts an upload's request only as that request starts, after the session is created, so an upload abandoned
+   * before then would start its request anyway, with nothing left to end it. Each request that sends the upload's
+   * bytes, its first and every retry, begins in `startUploading`, a public method of the SDK's `Upload`. On an
+   * abandoned upload it resolves at once: the upload is destroyed already, and some of the SDK's callers do not
+   * catch a rejection.
+   */
+  hold(upload) {
+    this.upload = upload;
+    const held = upload;
+    const startUploading = held.startUploading;
+    if (typeof startUploading !== "function") return;
+    held.startUploading = () => this.abandoned ? Promise.resolve() : startUploading.call(held);
+  }
+  /**
+   * End an upload that will not be committed. Destroying the write stream alone leaves the resumable upload's request
+   * open: the SDK destroys its upload with no error, aborts the request only when the upload errors, and its request
+   * body waits for bytes that never come, so the socket stays open and the process alive until the service drops the
+   * connection. So the upload is destroyed with an error first, which aborts its request; the body was never ended, so
+   * no object is finalized. An upload whose request has not started yet starts none: see {@link hold}. The error is
+   * the sink's own and reaches no caller.
+   */
   async abort() {
-    if (this.stream !== void 0 && !this.stream.destroyed) this.stream.destroy();
+    this.abandoned = true;
+    const abandoned = new Error("the upload was abandoned before its object was committed");
+    if (this.upload !== void 0 && !this.upload.destroyed) this.upload.destroy(abandoned);
+    if (this.stream !== void 0 && !this.stream.destroyed) this.stream.destroy(abandoned);
   }
 };
 
@@ -1173,6 +1614,17 @@ var GcsStorage = class {
   registry;
   /** The client both halves share — built here unless one was supplied. */
   client;
+  bucket;
+  /** The name prefix every object sits under: `''`, or `trimmed/`. */
+  keyPrefix;
+  readTimeoutMs;
+  /**
+   * Builds the GCS backend over one bucket, which `bucket` names. Pass `client`, or `projectId` and `apiEndpoint` to
+   * have one built, not both. `prefix` puts every object under a name prefix. Throws `ValidationError` for an unknown
+   * option, no bucket, a `now` that is not a function, a client setting beside `client`, a `maxObjectBytes` or
+   * `simpleUploadThresholdBytes` that is not a positive integer, a `conditionalDelete` that is not a boolean, an
+   * empty or non-string `apiEndpoint` or `projectId`, or an invalid `prefix` or `readTimeoutMs`.
+   */
   constructor(options) {
     let readClient;
     refuseUnknownOptions(
@@ -1181,7 +1633,7 @@ var GcsStorage = class {
       GCS_STORAGE_OPTION_KEYS,
       "a @google-cloud/storage client goes in `client`"
     );
-    if (typeof options.bucket !== "string" || options.bucket.length === 0) {
+    if (typeof options.bucket !== "string" || options.bucket.trim().length === 0) {
       throw new ValidationError5("GcsStorage needs a `bucket`: the name of one, a non-empty string");
     }
     if (options.now !== void 0 && typeof options.now !== "function") {
@@ -1199,11 +1651,21 @@ var GcsStorage = class {
       this.client = options.client;
       readClient = downloadClient(options.client, true);
     } else {
+      const apiEndpoint = requireNonEmptyString("GcsStorage: `apiEndpoint`", options.apiEndpoint);
+      if (apiEndpoint !== void 0 && /^[a-z][a-z0-9+.-]*:\/*$/i.test(apiEndpoint.trim())) {
+        throw new ValidationError5(
+          'GcsStorage: `apiEndpoint` must name a host, such as "http://localhost:4443" or "storage.googleapis.com"'
+        );
+      }
+      requireNonEmptyString("GcsStorage: `projectId`", options.projectId);
       this.client = new GcsClient(
         defined({ projectId: options.projectId, apiEndpoint: options.apiEndpoint })
       );
       readClient = downloadClient(this.client, false);
     }
+    this.bucket = options.bucket;
+    this.keyPrefix = prefixPart(normalizeObjectPrefix3(options.prefix));
+    this.readTimeoutMs = resolveReadTimeoutMs(options.readTimeoutMs);
     const shared = {
       storage: this.client,
       readStorage: readClient,
@@ -1224,6 +1686,17 @@ var GcsStorage = class {
     });
     brandAsBackend(this);
   }
+  /**
+   * Reads the bucket's metadata (one request, plus the SDK's own retries, bounded by `readTimeoutMs` when it is set) and
+   * reports a lifecycle rule with a `Delete` action (or one it does not know) that applies to live
+   * objects whose names can be this store's: generations and registry rows alike. Needs `storage.buckets.get`, which
+   * a load never uses (`store.preflight()`'s lifecycle step does) and `roles/storage.objectAdmin` does not include: without it the answer is
+   * `unchecked`, naming the permission. Never rejects; a `detail` carries no credential. Rule reading: see the
+   * production guide.
+   */
+  checkLifecycle() {
+    return checkGcsLifecycle(this.client, this.bucket, this.keyPrefix, this.readTimeoutMs);
+  }
 };
 export {
   GcsStorage