@cloudbitmaps/s3 0.21.0 → 0.23.0

package/dist/index.js

@@ -2,7 +2,11 @@
 import {
   ValidationError as ValidationError5,
   brandAsBackend,
+  normalizeObjectPrefix as normalizeObjectPrefix3,
+  prefixPart,
   refuseUnknownOptions,
+  requireBool as requireBool3,
+  requireNonEmptyString,
   requirePositiveInt as requirePositiveInt2
 } from "@cloudbitmaps/core/driver-kit";
 import { S3Client } from "@aws-sdk/client-s3";
@@ -12,40 +16,9 @@ function defined(values) {
   return Object.fromEntries(Object.entries(values).filter(([, v]) => v !== void 0));
 }
 
-// src/storage.ts
-import {
-  IntegrityError,
-  NotFoundError as NotFoundError2,
-  TransientError as TransientError2,
-  ValidationError as ValidationError3,
-  WriteConflictError,
-  concatBytes,
-  isNotFoundError,
-  isValidationError,
-  isWriteConflictError,
-  normalizeObjectPrefix,
-  parseGenerationFromKey,
-  requireBool,
-  requirePositiveInt,
-  segmentObjectPrefix,
-  storageObjectKey,
-  toTransient
-} from "@cloudbitmaps/core/driver-kit";
-import { createHash, randomBytes } from "node:crypto";
-import {
-  AbortMultipartUploadCommand,
-  CompleteMultipartUploadCommand,
-  CreateMultipartUploadCommand,
-  DeleteObjectCommand as DeleteObjectCommand2,
-  GetObjectCommand,
-  HeadObjectCommand,
-  ListObjectsV2Command,
-  PutObjectCommand as PutObjectCommand2,
-  UploadPartCommand
-} from "@aws-sdk/client-s3";
-
-// src/s3-errors.ts
-import { ValidationError } from "@cloudbitmaps/core/driver-kit";
+// src/lifecycle.ts
+import { GetBucketLifecycleConfigurationCommand } from "@aws-sdk/client-s3";
+import { TransientError as TransientError2 } from "@cloudbitmaps/core/driver-kit";
 
 // src/aws-errors.ts
 import { isTransportFault } from "@cloudbitmaps/core/driver-kit";
@@ -76,7 +49,422 @@ function isNetworkOrTimeout(err) {
   return NETWORK_MESSAGE.test(err?.message ?? "");
 }
 
+// src/read-timeout.ts
+import { TransientError, 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 (!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;
+}
+async function timedRead(operation, timeoutMs, read) {
+  if (timeoutMs === 0) return read(void 0);
+  const controller = new AbortController();
+  let timer;
+  const timedOut = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new TransientError(`S3 ${operation} timed out after ${timeoutMs} ms`));
+      controller.abort();
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([read({ abortSignal: controller.signal }), timedOut]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// src/scrub-error.ts
+import { types } from "node:util";
+var TRANSPORT = /* @__PURE__ */ new Set([
+  "$response",
+  "$responseBodyText",
+  "socket",
+  "_httpMessage",
+  "req",
+  "request",
+  "connection",
+  "agent"
+]);
+var PRIVATE_HEADERS = "x-amz-security-token|x-amz-s3session-token|x-amz-(?:copy-source-)?server-side-encryption-customer-key";
+var CREDENTIAL_NAME = new RegExp(
+  `^(?:(?:proxy-)?authorization|cookie|set-cookie|x-api-key|${PRIVATE_HEADERS}|x-amz-credential|x-amz-signature|(?:copysource)?ssecustomerkey|secretaccesskey|sessiontoken|signatureprovided|canonicalrequest(?:bytes)?|token(?:-\\d+)?)$`,
+  "i"
+);
+var isCredentialName = (text) => CREDENTIAL_NAME.test(text.trim().replace(/:$/, ""));
+var CREDENTIAL_LINES = new RegExp(
+  `^((?:proxy-)?authorization|cookie|set-cookie|x-api-key|${PRIVATE_HEADERS}):[^\\r\\n]*`,
+  "gim"
+);
+var NAMED_SECRET = new RegExp(
+  `((?:${PRIVATE_HEADERS})["']?\\s*(?::|=|%3D)\\s*["']?)[^\\s&"'<>\\\\,;]+`,
+  "gi"
+);
+var SIGNATURE = /(Signature(?:=|%3D))[0-9A-Fa-f]{16,}/gi;
+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);
+function redactText(text) {
+  try {
+    return text.replace(CREDENTIAL_LINES, `$1: ${REDACTED}`).replace(NAMED_SECRET, `$1${REDACTED}`).replace(SIGNATURE, `$1${REDACTED}`);
+  } catch {
+    return REDACTED;
+  }
+}
+var OMIT = /* @__PURE__ */ Symbol("omit");
+var INDEX = /^(?:0|[1-9]\d*)$/;
+function hasNamedKeys(value) {
+  if (!Array.isArray(value)) return Reflect.ownKeys(value).length > 0;
+  return Reflect.ownKeys(value).some(
+    (key) => key !== "length" && !(typeof key === "string" && INDEX.test(key) && Number(key) < 2 ** 32 - 1)
+  );
+}
+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 = [];
+  ctx.copies.set(value, list);
+  if (hasNamedKeys(value)) ctx.changed = true;
+  let hidden = false;
+  for (const item of value) {
+    if (hidden && item != null) {
+      list.push(REDACTED);
+      if (item !== REDACTED) ctx.changed = true;
+    } else {
+      const kept = copyOf(item, ctx, depth + 1);
+      list.push(kept === OMIT ? void 0 : kept);
+    }
+    hidden = typeof item === "string" && isCredentialName(item);
+  }
+  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;
+}
+function redactPairs(original, copy, errorLike, ctx) {
+  const names = Reflect.ownKeys(original).filter((key) => {
+    if (typeof key !== "string") 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)) 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 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;
+  let kept;
+  if (typeof key === "string" && isCredentialName(key) && descriptor.value != null) {
+    kept = REDACTED;
+    if (descriptor.value !== REDACTED) ctx.changed = true;
+  } else {
+    kept = copyOf(descriptor.value, 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_NAMED_RULES = 3;
+var READABLE_CLASSES = /* @__PURE__ */ new Set([
+  "STANDARD",
+  "STANDARD_IA",
+  "ONEZONE_IA",
+  "GLACIER_IR",
+  "INTELLIGENT_TIERING"
+]);
+var ARCHIVE_CLASSES = /* @__PURE__ */ new Set(["GLACIER", "DEEP_ARCHIVE"]);
+var INFREQUENT_CLASSES = /* @__PURE__ */ new Set([
+  "STANDARD_IA",
+  "ONEZONE_IA",
+  "GLACIER_IR"
+]);
+var cut = (text, max) => text.length > max ? text.slice(0, max) : text;
+var overlaps = (a, b) => a.startsWith(b) || b.startsWith(a);
+function rulePrefix(rule) {
+  return rule.Filter?.Prefix ?? rule.Filter?.And?.Prefix ?? rule.Prefix ?? "";
+}
+var hasTagFilter = (rule) => rule.Filter?.Tag !== void 0 || (rule.Filter?.And?.Tags?.length ?? 0) > 0;
+var isEnabled = (rule) => rule.Status !== "Disabled";
+function threat(rule) {
+  if (rule.Expiration?.Days !== void 0 || rule.Expiration?.Date !== void 0) {
+    return "expires current objects";
+  }
+  const classes = (rule.Transitions ?? []).map((t) => t.StorageClass);
+  const archive = classes.find((c) => c !== void 0 && ARCHIVE_CLASSES.has(c));
+  if (archive !== void 0) return `moves current objects to ${archive}`;
+  const unknown = (rule.Transitions ?? []).find(
+    (t) => t.StorageClass === void 0 || !READABLE_CLASSES.has(t.StorageClass)
+  );
+  return unknown === void 0 ? void 0 : `moves current objects to ${cut(String(unknown.StorageClass ?? "no storage class"), MAX_FIELD)}, a storage class this check does not know`;
+}
+var label = (rule) => {
+  const id = rule.ID === void 0 ? "" : `${JSON.stringify(cut(rule.ID, MAX_FIELD))} `;
+  return `${id}(prefix ${JSON.stringify(cut(rulePrefix(rule), MAX_FIELD))})`;
+};
+var sitsInside = (rule, prefix) => prefix !== "" && rulePrefix(rule).startsWith(prefix);
+function coversGenerations(rule, prefix) {
+  const own = rulePrefix(rule);
+  if (prefix.startsWith(own)) return true;
+  return !own.slice(prefix.length).startsWith("registry/");
+}
+var ABORT_ADVICE = "No rule aborts incomplete multipart uploads under this prefix; add one (AbortIncompleteMultipartUpload, a few days) so an upload a crashed writer abandoned stops billing for its parts.";
+var INTELLIGENT_TIERING_ADVICE = "A rule moves current objects to INTELLIGENT_TIERING: if the bucket turns on its archive access tiers, an object in one needs a restore before it can be read, so leave them off for this prefix.";
+var INFREQUENT_ADVICE = "A rule moves current objects to an infrequent-access class or GLACIER_IR: they stay readable, but each has a minimum storage duration and a per-GB retrieval fee that reads of the store will pay.";
+function judgeRules(rules, prefix) {
+  const live = rules.filter((r) => isEnabled(r) && overlaps(rulePrefix(r), prefix));
+  const untagged = live.filter((r) => !hasTagFilter(r));
+  const threats = untagged.flatMap((r) => {
+    const how = threat(r);
+    return how === void 0 ? [] : [{ text: `rule ${label(r)} ${how}`, inside: sitsInside(r, prefix) }];
+  });
+  const problems = threats.map((t) => t.text);
+  const transitionsTo = (classes) => untagged.some(
+    (r) => (r.Transitions ?? []).some(
+      (t) => t.StorageClass !== void 0 && classes.has(t.StorageClass)
+    )
+  );
+  const advice = [
+    live.some((r) => r.AbortIncompleteMultipartUpload !== void 0 && coversGenerations(r, prefix)) ? "" : ABORT_ADVICE,
+    transitionsTo(/* @__PURE__ */ new Set(["INTELLIGENT_TIERING"])) ? INTELLIGENT_TIERING_ADVICE : "",
+    transitionsTo(INFREQUENT_CLASSES) ? INFREQUENT_ADVICE : ""
+  ].filter((a) => a !== "").map((a) => ` ${a}`).join("");
+  if (problems.length > 0) {
+    const named = problems.slice(0, MAX_NAMED_RULES).join("; ");
+    const more = problems.length > MAX_NAMED_RULES ? ` and ${problems.length - MAX_NAMED_RULES} more` : "";
+    const quoted = JSON.stringify(cut(prefix, MAX_FIELD));
+    const narrow = `Narrow the rule's prefix 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 every bucket-wide or prefixed rule can reach it: give the store a prefix, or scope the rule away from its paths." : [
+      threats.some((t) => !t.inside) ? narrow : "",
+      threats.some((t) => t.inside) ? retarget : ""
+    ].filter((x) => x !== "").join(" ");
+    return {
+      status: "problem",
+      detail: `${named}${more}. The store keeps current objects it must be able to read back. ${where}${advice}`
+    };
+  }
+  return {
+    status: "ok",
+    detail: `no enabled lifecycle rule under ${JSON.stringify(cut(prefix, MAX_FIELD))} expires or archives current objects.${advice}`
+  };
+}
+function unchecked(err) {
+  if (err instanceof TransientError2) {
+    return {
+      status: "unchecked",
+      detail: "the read of the bucket lifecycle configuration got no answer in time (readTimeoutMs); run the check again"
+    };
+  }
+  const scrubbed = scrubCredentials(err);
+  if (errorName(scrubbed) === "AccessDenied") {
+    return {
+      status: "unchecked",
+      detail: "the identity may not read the bucket lifecycle configuration: grant s3:GetLifecycleConfiguration on the bucket to check it, or confirm by hand that no rule expires or archives current objects under this prefix"
+    };
+  }
+  const name = cut(String(errorName(scrubbed) ?? "Error"), MAX_FIELD);
+  const raw = scrubbed?.message;
+  const message = typeof raw === "string" ? `: ${raw.slice(0, MAX_MESSAGE)}` : "";
+  return {
+    status: "unchecked",
+    detail: `could not read the bucket lifecycle configuration (${name}${message}); check it by hand`
+  };
+}
+async function checkS3Lifecycle(client, bucket, prefix, readTimeoutMs = 0) {
+  try {
+    const out = await timedRead(
+      "GetBucketLifecycleConfiguration",
+      readTimeoutMs,
+      (options) => client.send(new GetBucketLifecycleConfigurationCommand({ Bucket: bucket }), options)
+    );
+    return judgeRules(out.Rules ?? [], prefix);
+  } catch (err) {
+    try {
+      if (errorName(err) === "NoSuchLifecycleConfiguration") {
+        return judgeRules([], prefix);
+      }
+      return unchecked(err);
+    } catch {
+      return { status: "unchecked", detail: "could not read the bucket lifecycle configuration" };
+    }
+  }
+}
+
+// src/storage.ts
+import {
+  errorKind,
+  IntegrityError,
+  NotFoundError as NotFoundError2,
+  TransientError as TransientError3,
+  ValidationError as ValidationError3,
+  WriteConflictError,
+  concatBytes,
+  normalizeObjectPrefix,
+  parseGenerationFromKey,
+  checkDeleteOptions,
+  requireBool,
+  requirePositiveInt,
+  segmentObjectPrefix,
+  storageObjectKey,
+  toTransient
+} from "@cloudbitmaps/core/driver-kit";
+import { createHash, randomBytes } from "node:crypto";
+import {
+  AbortMultipartUploadCommand,
+  CompleteMultipartUploadCommand,
+  CreateMultipartUploadCommand,
+  DeleteObjectCommand as DeleteObjectCommand2,
+  GetObjectCommand,
+  HeadObjectCommand,
+  ListObjectsV2Command,
+  PutObjectCommand as PutObjectCommand2,
+  UploadPartCommand
+} from "@aws-sdk/client-s3";
+
 // src/s3-errors.ts
+import { ValidationError as ValidationError2 } from "@cloudbitmaps/core/driver-kit";
 function isPreconditionFailed(err) {
   return errorName(err) === "PreconditionFailed" || httpStatus(err) === 412;
 }
@@ -84,7 +472,8 @@ function isConditionalConflict(err) {
   return isPreconditionFailed(err) || errorName(err) === "ConditionalRequestConflict" || httpStatus(err) === 409;
 }
 function isThrottle(err) {
-  return errorName(err) === "SlowDown" || httpStatus(err) === 503;
+  const status = httpStatus(err);
+  return errorName(err) === "SlowDown" || status === 503 || status === 429;
 }
 function isNoSuchUpload(err) {
   return errorName(err) === "NoSuchUpload";
@@ -95,7 +484,7 @@ function isMissingBucket(err) {
 function asMissingBucket(err, bucket) {
   if (!isMissingBucket(err)) return err;
   return Object.assign(
-    new ValidationError(
+    new ValidationError2(
       `the S3 bucket does not exist: ${bucket}; check the bucket name, and the region and endpoint of the client`
     ),
     { cause: err }
@@ -115,7 +504,7 @@ function isClockSkewCorrected(err) {
 }
 function isTransient(err) {
   if (isConditionalConflict(err) || isNotFound(err) || isInvalidRange(err)) return false;
-  return errorName(err) === "SlowDown" || isServerSide(err) || isNetworkOrTimeout(err) || isSdkRetryable(err) || isClockSkewCorrected(err);
+  return isThrottle(err) || isServerSide(err) || isNetworkOrTimeout(err) || isSdkRetryable(err) || isClockSkewCorrected(err);
 }
 function transientFaultMessage(err) {
   return `transient S3 fault: ${errorName(err) ?? "unknown"}`;
@@ -136,43 +525,6 @@ function totalFromContentRange(contentRange) {
   return Number.isSafeInteger(total) ? total : void 0;
 }
 
-// src/read-timeout.ts
-import { TransientError, 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 (!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;
-}
-async function timedRead(operation, timeoutMs, read) {
-  if (timeoutMs === 0) return read(void 0);
-  const controller = new AbortController();
-  let timer;
-  const timedOut = new Promise((_, reject) => {
-    timer = setTimeout(() => {
-      reject(new TransientError(`S3 ${operation} timed out after ${timeoutMs} ms`));
-      controller.abort();
-    }, timeoutMs);
-  });
-  try {
-    return await Promise.race([read({ abortSignal: controller.signal }), timedOut]);
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
 // src/send-once.ts
 var NO_RETRY = {
   name: "retryMiddleware",
@@ -186,7 +538,7 @@ function sendOnce(client, command) {
 }
 
 // src/bounded-body.ts
-import { NotFoundError } from "@cloudbitmaps/core";
+import { NotFoundError } from "@cloudbitmaps/core/driver-kit";
 function destroyBody(body) {
   body?.destroy?.();
 }
@@ -224,89 +576,6 @@ async function readBounded(body, maxBytes, oversize, advertised) {
   return out;
 }
 
-// src/scrub-error.ts
-var TRANSPORT = /* @__PURE__ */ new Set([
-  "$response",
-  "socket",
-  "_httpMessage",
-  "req",
-  "request",
-  "connection",
-  "agent"
-]);
-var CREDENTIAL_NAME = /^(?:proxy-)?authorization$|^cookie$|^set-cookie$|^x-api-key$|^x-amz-security-token$|^x-amz-credential$|^x-amz-signature$/i;
-var CREDENTIAL_LINE = new RegExp(
-  "^((?:proxy-)?authorization|cookie|set-cookie|x-api-key|x-amz-security-token):[^\\r\\n]*",
-  "im"
-);
-var CREDENTIAL_LINES = new RegExp(CREDENTIAL_LINE.source, "gim");
-var REDACTED = "[redacted]";
-var MAX_DEPTH = 6;
-var isPlain = (value) => {
-  const proto = Object.getPrototypeOf(value);
-  return proto === Object.prototype || proto === null || Array.isArray(value);
-};
-function redact(node, seen, depth) {
-  if (seen.has(node) || depth > MAX_DEPTH) return;
-  seen.add(node);
-  if (Array.isArray(node)) {
-    for (let i = 0; i + 1 < node.length; i++) {
-      const item = node[i];
-      if (typeof item === "string" && CREDENTIAL_NAME.test(item)) node[i + 1] = REDACTED;
-    }
-  }
-  for (const key of Reflect.ownKeys(node)) {
-    try {
-      const record = node;
-      const value = record[key];
-      if (typeof key === "string" && CREDENTIAL_NAME.test(key) && value != null) {
-        record[key] = REDACTED;
-      } else if (typeof value === "string" && CREDENTIAL_LINE.test(value)) {
-        record[key] = value.replace(CREDENTIAL_LINES, `$1: ${REDACTED}`);
-      } else if (typeof value === "object" && value !== null && isPlain(value)) {
-        redact(value, seen, depth + 1);
-      }
-    } catch {
-    }
-  }
-}
-function copyOf(err, depth) {
-  const copy = Object.create(Object.getPrototypeOf(err));
-  for (const key of Reflect.ownKeys(err)) {
-    if (typeof key === "string" && TRANSPORT.has(key)) continue;
-    const descriptor = Object.getOwnPropertyDescriptor(err, key);
-    if (descriptor === void 0) continue;
-    if (key === "cause" && "value" in descriptor) {
-      const cause = descriptor.value;
-      if (typeof cause === "object" && cause !== null && depth < MAX_DEPTH) {
-        descriptor.value = copyOf(cause, depth + 1);
-      }
-    }
-    if (key === "stack") {
-      Object.defineProperty(copy, key, {
-        value: err.stack,
-        writable: true,
-        configurable: true,
-        enumerable: false
-      });
-      continue;
-    }
-    Object.defineProperty(copy, key, descriptor);
-  }
-  return copy;
-}
-function holdsTransport(err, depth) {
-  if (Object.getOwnPropertyNames(err).some((key) => TRANSPORT.has(key))) return true;
-  const cause = err.cause;
-  return typeof cause === "object" && cause !== null && depth < MAX_DEPTH ? holdsTransport(cause, depth + 1) : false;
-}
-function scrubCredentials(err) {
-  if (typeof err !== "object" || err === null) return err;
-  const safe = holdsTransport(err, 0) ? copyOf(err, 0) : err;
-  redact(safe, /* @__PURE__ */ new WeakSet(), 0);
-  return safe;
-}
-
 // src/client-probe.ts
 import { DeleteObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3";
 var PROBE_KEY = "cloudbitmaps-probe";
@@ -410,15 +679,15 @@ var S3_LABELS = /* @__PURE__ */ new Set([
 var S3_DASH_REGION_LABEL = /^s3-(fips-)?[a-z]{2}(-gov)?-[a-z]+-\d$/;
 var S3_EXPRESS_LABEL = /^s3express-[a-z0-9-]+$/;
 var REGION_LABEL = /^[a-z]{2}(-[a-z]+)+-\d+$/;
-var isS3Label = (label) => S3_LABELS.has(label) || S3_DASH_REGION_LABEL.test(label) || S3_EXPRESS_LABEL.test(label);
+var isS3Label = (label2) => S3_LABELS.has(label2) || S3_DASH_REGION_LABEL.test(label2) || S3_EXPRESS_LABEL.test(label2);
 function isAwsS3Host(hostname) {
   const host = hostname.toLowerCase().replace(/\.$/, "");
   const domain = AWS_DOMAINS.find((d) => host.endsWith(d));
   if (domain === void 0) return false;
   const labels = host.slice(0, -domain.length).split(".");
   let at = -1;
-  labels.forEach((label, i) => {
-    if (isS3Label(label)) at = i;
+  labels.forEach((label2, i) => {
+    if (isS3Label(label2)) at = i;
   });
   if (at === -1) return false;
   const rest = labels.slice(at + 1);
@@ -440,6 +709,10 @@ var THROTTLE_BASE_DELAY_MS = 500;
 var REAL_TIME = {
   sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
 };
+function isTypedPassThrough(err) {
+  const kind = errorKind(err);
+  return kind === "ValidationError" || kind === "WriteConflictError" || kind === "NotFoundError";
+}
 var REAL_RNG = { next: () => Math.random() };
 var S3StorageDriver = class {
   client;
@@ -516,9 +789,7 @@ var S3StorageDriver = class {
           `generation already exists (write-once): ${key.segment}.${key.generation}`
         );
       }
-      if (isValidationError(err) || isWriteConflictError(err) || isNotFoundError(err)) {
-        throw err;
-      }
+      if (isTypedPassThrough(err)) throw err;
       throw this.mapError(err);
     }
   }
@@ -649,7 +920,7 @@ var S3StorageDriver = class {
   }
   async delete(key, options) {
     const objectKey = storageObjectKey(this.prefix, key);
-    const ifVersion = options?.ifVersion;
+    const ifVersion = checkDeleteOptions(options);
     if (ifVersion !== void 0 && this.explicitConditionalDelete !== false) await this.settle();
     const conditional = ifVersion !== void 0 && appliesDeleteIfMatch(this.explicitConditionalDelete, this.facts);
     try {
@@ -680,7 +951,7 @@ var S3StorageDriver = class {
       await this.head(key, objectKey);
       return true;
     } catch (err) {
-      if (isNotFoundError(err)) return false;
+      if (errorKind(err) === "NotFoundError") return false;
       throw err;
     }
   }
@@ -719,7 +990,7 @@ var S3StorageDriver = class {
   /** Map S3 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 NotFoundError2(`no such generation: ${key.segment}.${key.generation}`);
     }
@@ -793,7 +1064,7 @@ var S3MultipartSink = class {
         })
       );
       if (res2.UploadId === void 0) {
-        throw new TransientError2("S3 CreateMultipartUpload returned no UploadId");
+        throw new TransientError3("S3 CreateMultipartUpload returned no UploadId");
       }
       this.uploadId = res2.UploadId;
     }
@@ -881,7 +1152,7 @@ var S3MultipartSink = class {
           const stored = await this.storedObject();
           if (stored?.id === this.writeId) return;
           if (stored === void 0 && !isPreconditionFailed(err)) {
-            throw new TransientError2(
+            throw new TransientError3(
               `S3 ${operation}: ${this.objectKey} is not stored, and the first send may still be applying`,
               { cause: err }
             );
@@ -891,7 +1162,7 @@ var S3MultipartSink = class {
         }
         if (!isThrottle(err)) throw err;
         if (resent >= THROTTLE_RESENDS) {
-          throw new TransientError2(
+          throw new TransientError3(
             `S3 ${operation} was throttled on each of its ${resent + 1} sends; the object may or may not exist`,
             { cause: err }
           );
@@ -936,8 +1207,8 @@ var S3MultipartSink = class {
 
 // src/registry.ts
 import {
+  errorKind as errorKind2,
   IntegrityError as IntegrityError2,
-  isIntegrityError,
   MAX_ROW_BYTES,
   ObjectStoreRegistry,
   ValidationError as ValidationError4,
@@ -1021,7 +1292,7 @@ var S3RegistryStore = class {
         return { bytes, version: res.ETag ?? "" };
       } catch (err) {
         destroyBody(res.Body);
-        throw isIntegrityError(err) ? err : mapError(err, this.bucket);
+        throw errorKind2(err) === "IntegrityError" ? err : mapError(err, this.bucket);
       }
     });
   }
@@ -1200,6 +1471,48 @@ function emit(sink, event) {
 }
 
 // src/backend.ts
+function checkCredentials(credentials) {
+  if (credentials === void 0) return;
+  if (typeof credentials === "function") {
+    throw new ValidationError5(
+      "S3Storage: `credentials` must be an object of `accessKeyId` and `secretAccessKey`, not a provider function; pass a provider on an S3Client given as `client`"
+    );
+  }
+  const keys = [
+    "accessKeyId",
+    "secretAccessKey",
+    "sessionToken",
+    "$source",
+    "credentialScope",
+    "accountId",
+    "expiration"
+  ];
+  refuseUnknownOptions("S3Storage credentials", credentials, keys);
+  const given = credentials;
+  const needText = (key, value) => {
+    if (typeof value !== "string" || value.trim().length === 0) {
+      throw new ValidationError5(
+        `S3Storage: \`credentials.${key}\` must be a non-empty string; got ${typeof value === "string" ? "an empty string" : value === null || value === void 0 ? String(value) : `a ${typeof value}`}`
+      );
+    }
+  };
+  needText("accessKeyId", given.accessKeyId);
+  needText("secretAccessKey", given.secretAccessKey);
+  if (given.sessionToken !== void 0) needText("sessionToken", given.sessionToken);
+}
+function checkEndpointUrl(endpoint) {
+  let url;
+  try {
+    url = new URL(endpoint);
+  } catch {
+    url = void 0;
+  }
+  if (url === void 0 || !/^https?:$/.test(url.protocol) || url.hostname.length === 0) {
+    throw new ValidationError5(
+      'S3Storage: `endpoint` must be an http or https URL such as "http://localhost:9000"'
+    );
+  }
+}
 var S3_STORAGE_OPTION_KEYS = [
   "bucket",
   "prefix",
@@ -1247,6 +1560,18 @@ var S3Storage = class {
   /** The client both halves share — built here unless one was supplied. */
   client;
   sockets;
+  bucket;
+  /** The key prefix every object sits under: `''`, or `trimmed/`. */
+  keyPrefix;
+  readTimeoutMs;
+  /**
+   * Builds the S3 backend over one bucket, which `bucket` names. Pass `client`, or `region`, `endpoint`, `pathStyle`,
+   * `credentials` and `maxSockets` to have one built, not both. `prefix` puts every object under a key prefix. Throws
+   * `ValidationError` for an unknown option, no bucket, a `now` that is not a function, a client setting beside
+   * `client`, a `maxSockets` (with no `client`) that is not a positive integer, a `partBytes` or `maxObjectBytes` that
+   * is not a positive integer, a `conditionalDelete` that is not a boolean, a `region` or `endpoint` that is empty or not a string, a `pathStyle` that
+   * is not a boolean, `credentials` that are not complete, or an invalid `prefix` or `readTimeoutMs`.
+   */
   constructor(options) {
     refuseUnknownOptions(
       "S3Storage",
@@ -1254,7 +1579,7 @@ var S3Storage = class {
       S3_STORAGE_OPTION_KEYS,
       "an S3 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("S3Storage needs a `bucket`: the name of one, a non-empty string");
     }
     if (options.now !== void 0 && typeof options.now !== "function") {
@@ -1269,9 +1594,24 @@ var S3Storage = class {
           `S3Storage 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\``
         );
       }
+      if (typeof options.client.send !== "function") {
+        throw new ValidationError5(
+          "S3Storage: `client` must be an S3Client from @aws-sdk/client-s3 (an object with `send`)"
+        );
+      }
       this.client = options.client;
     } else {
       const maxSockets = requirePositiveInt2("maxSockets", options.maxSockets) ?? DEFAULT_MAX_SOCKETS;
+      const region = options.region;
+      if (region !== void 0 && (typeof region !== "string" || region.trim().length === 0)) {
+        throw new ValidationError5(
+          "S3Storage's `region` must be a non-empty string such as 'us-east-1'"
+        );
+      }
+      const endpoint = requireNonEmptyString("S3Storage: `endpoint`", options.endpoint);
+      if (endpoint !== void 0) checkEndpointUrl(endpoint);
+      requireBool3("S3Storage: `pathStyle`", options.pathStyle);
+      checkCredentials(options.credentials);
       this.client = new S3Client(
         defined({
           credentials: options.credentials,
@@ -1282,6 +1622,9 @@ var S3Storage = class {
       );
       limitSockets(this.client, maxSockets);
     }
+    this.bucket = options.bucket;
+    this.keyPrefix = prefixPart(normalizeObjectPrefix3(options.prefix));
+    this.readTimeoutMs = resolveReadTimeoutMs(options.readTimeoutMs);
     this.sockets = new SocketAdvisory(this.client, options.bucket);
     const shared = {
       client: this.client,
@@ -1310,6 +1653,18 @@ var S3Storage = class {
   attachMetrics(sink) {
     this.sockets.attach(sink);
   }
+  /**
+   * Reads the bucket's lifecycle configuration (one `GetBucketLifecycleConfiguration` request, plus the SDK's own
+   * retries, bounded by `readTimeoutMs` when it is set) and reports a rule that would expire, or move to GLACIER,
+   * DEEP_ARCHIVE or a class it does not know, the current objects under this store's prefix, generations and registry
+   * rows alike. Needs `s3:GetLifecycleConfiguration`, which a load never uses (`store.preflight()`'s
+   * lifecycle step does): without it the
+   * answer is `unchecked`, naming the permission. A missing rule that aborts incomplete multipart uploads is advice in
+   * `detail`, not a problem. Never rejects; a `detail` carries no credential. Rule reading: see the production guide.
+   */
+  checkLifecycle() {
+    return checkS3Lifecycle(this.client, this.bucket, this.keyPrefix, this.readTimeoutMs);
+  }
 };
 export {
   S3Storage