@stowage/adapter-s3 0.0.0 → 0.1.0

package/dist/index.js

@@ -0,0 +1,2483 @@
+import { StorageError, errorCodeForStatus, invalidKeyReason, isStorageError, isTransientStatus, withRetry } from "@stowage/core";
+//#region src/storage-error.ts
+function s3Error(bucket, fields) {
+	return new StorageError({
+		...fields,
+		bucket,
+		provider: "s3"
+	});
+}
+/**
+* The same failure told against the storage it happened in. A credential resolver is
+* written outside the adapter and knows neither bucket nor operation, so the error it
+* throws arrives without them and is re-issued here rather than reaching a caller with
+* the placeholders it was built from (spec 4.10).
+*/
+function inStorage(failure, bucket, operation, key) {
+	if (!isStorageError(failure)) return failure;
+	return s3Error(bucket, {
+		...fieldsOf(failure),
+		operation,
+		key: key ?? failure.key
+	});
+}
+/** The same failure, counting the attempts made where the one that failed does not know. */
+function withAttemptsMade(failure, attempts) {
+	return s3Error(failure.bucket, {
+		...fieldsOf(failure),
+		attempts
+	});
+}
+/**
+* Every field of `StorageErrorFields` is named below, so a field added to that type has
+* to be added here too or it is dropped on the way through.
+*/
+function fieldsOf(failure) {
+	return {
+		code: failure.code,
+		message: failure.message,
+		operation: failure.operation,
+		key: failure.key,
+		attempts: failure.attempts,
+		status: failure.status,
+		providerCode: failure.providerCode,
+		requestId: failure.requestId,
+		retryable: failure.retryable,
+		capability: failure.capability,
+		cause: failure.cause
+	};
+}
+//#endregion
+//#region src/options.ts
+const operationOptionKeys = ["signal"];
+const putOptionKeys = [
+	...operationOptionKeys,
+	"contentType",
+	"userMetadata"
+];
+const getOptionKeys = [...operationOptionKeys, "range"];
+const presignGetOptionKeys = [
+	"expiresIn",
+	"responseContentType",
+	"responseContentDisposition",
+	"responseCacheControl",
+	"responseExpires"
+];
+const presignPutOptionKeys = [
+	"expiresIn",
+	"contentType",
+	"contentLength"
+];
+const listOptionKeys = [
+	...operationOptionKeys,
+	"prefix",
+	"delimiter",
+	"pageSize",
+	"cursor"
+];
+/**
+* Refuses an option key the spec does not list (spec 4.3). TypeScript catches one at the
+* call site; this catches the rest.
+*/
+function requireKnownOptions(bucket, options, known, operation) {
+	if (options === void 0) return;
+	for (const key of Object.keys(options)) {
+		if (known.includes(key)) continue;
+		throw optionError$1(bucket, key, "is not one this storage takes", operation);
+	}
+}
+function optionError$1(bucket, option, expectation, operation) {
+	return s3Error(bucket, {
+		code: "InvalidOption",
+		message: `The option \`${option}\` ${expectation}`,
+		operation,
+		attempts: 0
+	});
+}
+//#endregion
+//#region src/configuration.ts
+const adapterOptionKeys = [
+	"bucket",
+	"region",
+	"endpoint",
+	"forcePathStyle",
+	"credentials",
+	"retry",
+	"multipart"
+];
+const retryOptionKeys = ["maxAttempts"];
+const multipartOptionKeys = ["partSize", "concurrency"];
+const mebibyte = 1048576;
+const defaultMaxAttempts = 3;
+const defaultPartSize = 8 * mebibyte;
+const defaultConcurrency = 4;
+const maxAttemptsRange = {
+	least: 1,
+	most: 3
+};
+const partSizeRange = {
+	least: 5 * mebibyte,
+	most: 5120 * mebibyte
+};
+const concurrencyRange = {
+	least: 1,
+	most: 16
+};
+/**
+* IPv4 loopback is the whole `127.0.0.0/8` block and IPv6 loopback the single `::1`.
+* `localhost` stands beside them because RFC 6761 binds the name to one of the two, which
+* is what makes it an address spec 7.1 accepts rather than a host that might be anywhere.
+*/
+const loopbackHosts = /^(?:localhost|127(?:\.\d{1,3}){3}|\[::1\])$/u;
+/**
+* Spec 7.1: every option is validated where the storage is constructed, an unknown key
+* and a value outside its range are `InvalidOption` naming the key, and no value is
+* clamped onto the range it missed.
+*/
+function readConfiguration(options) {
+	const bucket = typeof options.bucket === "string" ? options.bucket : "";
+	requireKnownOptions(bucket, options, adapterOptionKeys, "s3Storage");
+	requireFilled$1(bucket, options.bucket, "bucket");
+	requireFilled$1(bucket, options.region, "region");
+	if (options.credentials === void 0) throw optionError(bucket, "credentials", "is required: v0.1 sends no unsigned request");
+	const forcePathStyle = readFlag(bucket, options.forcePathStyle, "forcePathStyle");
+	const endpoint = readEndpoint(bucket, options, forcePathStyle);
+	return {
+		bucket: options.bucket,
+		region: options.region,
+		...endpoint,
+		forcePathStyle,
+		credentials: options.credentials,
+		maxAttempts: readMaxAttempts(bucket, options.retry),
+		...readMultipart(bucket, options.multipart)
+	};
+}
+/**
+* Spec 7.1: no endpoint addresses AWS S3, a configured one is an absolute URL without
+* userinfo, query and fragment, and `http:` is accepted for a loopback host alone.
+* Addressing is virtual-hosted unless `forcePathStyle` moves the bucket into the path.
+*/
+function readEndpoint(bucket, options, forcePathStyle) {
+	if (options.endpoint === void 0) return {
+		protocol: "https:",
+		host: hostFor(`s3.${options.region}.amazonaws.com`, options.bucket, forcePathStyle),
+		basePath: ""
+	};
+	if (typeof options.endpoint !== "string") throw optionError(bucket, "endpoint", "is no absolute URL");
+	const parsed = URL.parse(options.endpoint);
+	if (parsed === null) throw optionError(bucket, "endpoint", "is no absolute URL");
+	if (parsed.username !== "" || parsed.password !== "") throw optionError(bucket, "endpoint", "carries userinfo");
+	if (parsed.search !== "") throw optionError(bucket, "endpoint", "carries a query");
+	if (parsed.hash !== "") throw optionError(bucket, "endpoint", "carries a fragment");
+	if (parsed.protocol !== "https:" && !isLoopbackHttp(parsed)) throw optionError(bucket, "endpoint", "is neither `https:` nor `http:` to a loopback host");
+	return {
+		protocol: parsed.protocol,
+		host: hostFor(parsed.host, options.bucket, forcePathStyle),
+		basePath: parsed.pathname === "/" ? "" : parsed.pathname.replace(/\/$/u, "")
+	};
+}
+function isLoopbackHttp(endpoint) {
+	return endpoint.protocol === "http:" && loopbackHosts.test(endpoint.hostname);
+}
+function hostFor(host, bucket, forcePathStyle) {
+	return forcePathStyle ? host : `${bucket}.${host}`;
+}
+function readMaxAttempts(bucket, retry) {
+	if (retry === false) return 1;
+	if (retry === void 0) return defaultMaxAttempts;
+	requireGroup(bucket, retry, "retry");
+	requireKnownOptions(bucket, retry, retryOptionKeys, "s3Storage");
+	return readInRange(bucket, retry.maxAttempts, "maxAttempts", maxAttemptsRange, defaultMaxAttempts);
+}
+function readMultipart(bucket, multipart) {
+	if (multipart !== void 0) {
+		requireGroup(bucket, multipart, "multipart");
+		requireKnownOptions(bucket, multipart, multipartOptionKeys, "s3Storage");
+	}
+	return {
+		partSize: readInRange(bucket, multipart?.partSize, "partSize", partSizeRange, defaultPartSize),
+		concurrency: readInRange(bucket, multipart?.concurrency, "concurrency", concurrencyRange, defaultConcurrency)
+	};
+}
+function readInRange(bucket, value, option, range, fallback) {
+	if (value === void 0) return fallback;
+	if (!Number.isInteger(value) || value < range.least || value > range.most) throw optionError(bucket, option, `takes the integers ${range.least} to ${range.most}`);
+	return value;
+}
+function readFlag(bucket, value, option) {
+	if (value === void 0) return false;
+	if (typeof value !== "boolean") throw optionError(bucket, option, "takes a boolean");
+	return value;
+}
+/**
+* A group of options is an object. Without this, `Object.keys` reads `retry: true` as a
+* group with no key and hands back the default, and `retry: null` throws a `TypeError`
+* where spec 7.1 asks for `InvalidOption`.
+*/
+function requireGroup(bucket, group, option) {
+	if (typeof group === "object" && group !== null) return;
+	throw optionError(bucket, option, "takes a group of options");
+}
+function requireFilled$1(bucket, value, option) {
+	if (typeof value === "string" && value !== "") return;
+	throw optionError(bucket, option, "is empty");
+}
+function optionError(bucket, option, expectation) {
+	return optionError$1(bucket, option, expectation, "s3Storage");
+}
+//#endregion
+//#region src/provider-code.ts
+/**
+* The table of spec 7.9, holding both vendors' strings: a code recognized here decides
+* the error code alone, and an unrecognized one falls to the status mapping of spec 4.10.
+* Whether the condition is transient is never read from here — ADR 0013 decides that by
+* the status, so that an unknown `5xx` is treated no worse than one stowage has heard of.
+*/
+const providerCodes = /* @__PURE__ */ new Map([
+	["NoSuchKey", "NotFound"],
+	["NoSuchBucket", "NotFound"],
+	["AccessDenied", "AccessDenied"],
+	["InvalidAccessKeyId", "InvalidCredentials"],
+	["SignatureDoesNotMatch", "InvalidCredentials"],
+	["Unauthorized", "InvalidCredentials"],
+	["ExpiredToken", "Expired"],
+	["ExpiredRequest", "Expired"],
+	["RequestTimeTooSkewed", "InvalidRequest"],
+	["InvalidRange", "InvalidRequest"],
+	["InvalidRequest", "InvalidRequest"],
+	["InvalidArgument", "InvalidRequest"],
+	["MetadataTooLarge", "InvalidRequest"],
+	["EntityTooLarge", "InvalidRequest"],
+	["EntityTooSmall", "InvalidRequest"],
+	["InvalidPart", "InvalidRequest"],
+	["InvalidPartOrder", "InvalidRequest"],
+	["BadDigest", "InvalidRequest"],
+	["MalformedXML", "InvalidRequest"],
+	["InvalidDigest", "InvalidRequest"],
+	["InvalidObjectName", "InvalidKey"],
+	["KeyTooLongError", "InvalidKey"],
+	["NoSuchUpload", "ProviderError"],
+	["SlowDown", "ProviderError"],
+	["TooManyRequests", "ProviderError"],
+	["ServiceUnavailable", "ProviderError"],
+	["InternalError", "ProviderError"],
+	["RequestTimeout", "ProviderError"]
+]);
+const permanentRedirect = 301;
+const badRequest = 400;
+/** The longest key AWS S3 and R2 hold, in UTF-8 bytes, above which they answer `KeyTooLongError`. */
+const longestHeldKey = 1024;
+const utf8$5 = new TextEncoder();
+/**
+* What the provider's answer means, decided by its own code where the table recognizes
+* one and by the status where it does not. The message is the provider's word for word
+* (spec 4.10), except where spec 7.9 has the failure name the option that is wrong: a
+* caller can act on `region` and on `cursor`, and cannot on a message about either.
+*/
+function readProviderFailure(answer) {
+	const said = answer.providerMessage ?? `The provider answered ${answer.status} to \`${answer.method}\``;
+	if (answer.status === permanentRedirect || answer.providerCode === "PermanentRedirect") return {
+		code: "InvalidOption",
+		message: `The option \`region\` is not the bucket's${answer.bucketRegion === void 0 ? "" : `, which is \`${answer.bucketRegion}\``}: ${said}`
+	};
+	if (answer.method === "HEAD" && answer.status === badRequest && answer.key !== void 0 && utf8$5.encode(answer.key).byteLength > longestHeldKey) return {
+		code: "InvalidKey",
+		message: `The key is longer than the ${longestHeldKey} bytes the provider holds: ${said}`
+	};
+	if (answer.providerCode === "InvalidArgument" && answer.operation === "list" && answer.hasContinuationToken) return {
+		code: "InvalidOption",
+		message: `The option \`cursor\` is not one the provider continued from: ${said}`
+	};
+	return {
+		code: (answer.providerCode === void 0 ? void 0 : providerCodes.get(answer.providerCode)) ?? errorCodeForStatus(answer.status) ?? "ProviderError",
+		message: said
+	};
+}
+/**
+* The codes of the table a provider answers with a transient status: the five the table
+* leaves to the status, as spec 7.9 notes beside them.
+*/
+const transientProviderCodes = /* @__PURE__ */ new Set([
+	"SlowDown",
+	"TooManyRequests",
+	"ServiceUnavailable",
+	"InternalError",
+	"RequestTimeout"
+]);
+/**
+* A failure the provider reported inside a `200`, such as one key of a `DeleteObjects` or
+* a `CopyObject` that failed after the answer began. No status speaks for it, so the code
+* decides alone; whether it is transient is read off the code, since spec 4.7 has the
+* entry carry `retryable` for a caller who repeats it. Nothing here is repeated: ADR 0013
+* lets no provider code into the retry group.
+*/
+function readEmbeddedFailure(providerCode, providerMessage) {
+	return {
+		code: providerCodes.get(providerCode) ?? "ProviderError",
+		message: providerMessage,
+		retryable: transientProviderCodes.has(providerCode)
+	};
+}
+//#endregion
+//#region src/xml.ts
+/** A document outside the subset ADR 0003 reads, reported rather than read around. */
+var XmlSyntaxError = class extends Error {
+	name = "XmlSyntaxError";
+};
+/**
+* The root element of an XML document of the subset S3 answers a listing with: elements,
+* attributes, text and comments under one optional declaration.
+*/
+function parseXml(document) {
+	const scanner = new Scanner(document);
+	scanner.skipDeclaration();
+	scanner.skipMisc();
+	const root = scanner.readElement();
+	scanner.skipMisc();
+	scanner.requireEnd();
+	return root;
+}
+const namePattern = /[:A-Z_a-z\u00C0-\uFFFF][:A-Z_a-z\u00C0-\uFFFF.\d-]*/uy;
+const whitespacePattern = /[ \t\r\n]*/y;
+const entityPattern = /&(?:#x([\da-fA-F]+)|#(\d+)|([A-Za-z]\w*));/uy;
+/** `Char` of XML 1.0, section 2.2: what a character reference may name. */
+function isXmlCharacter(codePoint) {
+	return codePoint === 9 || codePoint === 10 || codePoint === 13 || codePoint >= 32 && codePoint <= 55295 || codePoint >= 57344 && codePoint <= 65533 || codePoint >= 65536 && codePoint <= 1114111;
+}
+/** The five entities XML defines without a DTD, which is every one a document here has. */
+const predefinedEntities = /* @__PURE__ */ new Map([
+	["amp", "&"],
+	["lt", "<"],
+	["gt", ">"],
+	["quot", "\""],
+	["apos", "'"]
+]);
+const xmlEscapes = {
+	"&": "&amp;",
+	"<": "&lt;",
+	">": "&gt;",
+	"\"": "&quot;",
+	"'": "&apos;"
+};
+/** Text as it stands inside an element of a request document stowage writes. */
+function escapeXml(text) {
+	return text.replaceAll(/[&<>"']/gu, (character) => xmlEscapes[character] ?? character);
+}
+var Scanner = class {
+	#document;
+	#position = 0;
+	constructor(document) {
+		this.#document = document;
+	}
+	skipDeclaration() {
+		if (!this.#startsWith("<?xml")) return;
+		this.#position = this.#positionPast("?>", "The XML declaration is never closed");
+	}
+	/** Whitespace and comments, which are all that may stand beside the root element. */
+	skipMisc() {
+		for (;;) {
+			this.#skipWhitespace();
+			if (this.#startsWith("<!DOCTYPE")) throw this.#error("A DTD is refused");
+			if (!this.#startsWith("<!--")) return;
+			this.#skipComment();
+		}
+	}
+	requireEnd() {
+		if (this.#position < this.#document.length) throw this.#error("Something follows the root element");
+	}
+	readElement() {
+		this.#expect("<");
+		const name = this.#readName();
+		if (this.#readStartTagEnd() === "empty") return {
+			name,
+			children: [],
+			text: ""
+		};
+		const children = [];
+		let text = "";
+		for (;;) {
+			if (this.#position >= this.#document.length) throw this.#error(`The element <${name}> is never closed`);
+			if (this.#startsWith("</")) {
+				this.#position += 2;
+				this.#closeElement(name);
+				return {
+					name,
+					children,
+					text
+				};
+			}
+			if (this.#startsWith("<!--")) this.#skipComment();
+			else if (this.#startsWith("<![CDATA[")) throw this.#error("A CDATA section is refused");
+			else if (this.#startsWith("<")) children.push(this.readElement());
+			else text += this.#readText();
+		}
+	}
+	#closeElement(name) {
+		const closing = this.#readName();
+		if (closing !== name) throw this.#error(`The element <${name}> is closed by </${closing}>`);
+		this.#skipWhitespace();
+		this.#expect(">");
+	}
+	#readStartTagEnd() {
+		for (;;) {
+			const before = this.#position;
+			this.#skipWhitespace();
+			if (this.#startsWith("/>")) {
+				this.#position += 2;
+				return "empty";
+			}
+			if (this.#startsWith(">")) {
+				this.#position += 1;
+				return "open";
+			}
+			if (this.#position === before) throw this.#error("An attribute follows no whitespace");
+			this.#readName();
+			this.#skipWhitespace();
+			this.#expect("=");
+			this.#skipWhitespace();
+			this.#skipQuoted();
+		}
+	}
+	#skipQuoted() {
+		const quote = this.#document[this.#position];
+		if (quote !== "\"" && quote !== "'") throw this.#error("An attribute value is not quoted");
+		this.#position = this.#positionPast(quote, "An attribute value is never closed", 1);
+	}
+	/** Text up to the next markup, every `&` in it the start of an entity it decodes. */
+	#readText() {
+		const markup = this.#document.indexOf("<", this.#position);
+		const end = markup === -1 ? this.#document.length : markup;
+		let text = "";
+		while (this.#position < end) {
+			const ampersand = this.#document.indexOf("&", this.#position);
+			if (ampersand === -1 || ampersand >= end) {
+				text += this.#document.slice(this.#position, end);
+				this.#position = end;
+				break;
+			}
+			text += this.#document.slice(this.#position, ampersand);
+			this.#position = ampersand;
+			text += this.#readEntity();
+		}
+		return text;
+	}
+	#readEntity() {
+		entityPattern.lastIndex = this.#position;
+		const found = entityPattern.exec(this.#document);
+		if (found === null) throw this.#error("An `&` starts no entity");
+		const [entity, hex, decimal, name] = found;
+		if (name !== void 0) {
+			const character = predefinedEntities.get(name);
+			if (character === void 0) throw this.#error(`The entity ${entity} is not defined`);
+			this.#position = entityPattern.lastIndex;
+			return character;
+		}
+		const codePoint = hex === void 0 ? Number(decimal) : Number.parseInt(hex, 16);
+		if (!isXmlCharacter(codePoint)) throw this.#error(`The reference ${entity} names no character XML carries`);
+		this.#position = entityPattern.lastIndex;
+		return String.fromCodePoint(codePoint);
+	}
+	#skipComment() {
+		this.#position = this.#positionPast("-->", "A comment is never closed", 4);
+	}
+	#readName() {
+		namePattern.lastIndex = this.#position;
+		const found = namePattern.exec(this.#document);
+		if (found === null) throw this.#error("A name is missing where one belongs");
+		this.#position = namePattern.lastIndex;
+		return found[0];
+	}
+	#skipWhitespace() {
+		whitespacePattern.lastIndex = this.#position;
+		whitespacePattern.exec(this.#document);
+		this.#position = whitespacePattern.lastIndex;
+	}
+	#expect(literal) {
+		if (!this.#startsWith(literal)) throw this.#error(`\`${literal}\` is missing`);
+		this.#position += literal.length;
+	}
+	#positionPast(terminator, unterminated, offset = 0) {
+		const end = this.#document.indexOf(terminator, this.#position + offset);
+		if (end === -1) throw this.#error(unterminated);
+		return end + terminator.length;
+	}
+	#startsWith(literal) {
+		return this.#document.startsWith(literal, this.#position);
+	}
+	#error(message) {
+		return new XmlSyntaxError(`${message} (at character ${this.#position})`);
+	}
+};
+//#endregion
+//#region src/answer-document.ts
+/**
+* The root of the document a `200` carries, read through the parser of spec 7.4. S3 may
+* answer a `CopyObject` or a `DeleteObjects` with `200` and an `<Error>` in the body once
+* the answer has begun, so a root of that name is the failure it reports, told with the
+* provider's code and message, and not repeated (ADR 0013 lets no code into the group).
+*/
+async function readAnswerDocument(request, response, expectedRoot) {
+	const requestId = response.headers.get("x-amz-request-id") ?? void 0;
+	const context = {
+		operation: request.operation,
+		key: request.key,
+		attempts: 1,
+		status: response.status,
+		requestId
+	};
+	const root = parseAnswer(request, await readBody$1(request, response, context), context);
+	if (root.name === "Error") throw embeddedFailure(request, context, root);
+	if (root.name !== expectedRoot) throw malformed$1(request, context, `a <${root.name}> where a <${expectedRoot}> belongs`);
+	return root;
+}
+/**
+* The failure an `<Error>` element inside a `200` reports: a whole answer's, or one key's
+* of a `DeleteObjects`. No status speaks for it, so its code decides alone.
+*/
+function embeddedFailure(request, context, element) {
+	const providerCode = textOf$1(element, "Code") ?? "";
+	const failure = readEmbeddedFailure(providerCode, textOf$1(element, "Message") ?? `The provider failed ${request.subject}: ${providerCode}`);
+	return s3Error(request.bucket, {
+		...context,
+		code: failure.code,
+		message: failure.message,
+		providerCode: providerCode === "" ? void 0 : providerCode,
+		retryable: failure.retryable
+	});
+}
+function textOf$1(element, name) {
+	return element.children.find((child) => child.name === name)?.text;
+}
+async function readBody$1(request, response, context) {
+	try {
+		return await response.text();
+	} catch (failure) {
+		if (failure instanceof Error && failure.name === "AbortError") throw failure;
+		throw s3Error(request.bucket, {
+			...context,
+			code: "NetworkError",
+			message: `The answer to ${request.subject} broke while it was read: ${String(failure)}`,
+			retryable: true,
+			cause: failure
+		});
+	}
+}
+function parseAnswer(request, body, context) {
+	try {
+		return parseXml(body);
+	} catch (failure) {
+		if (failure instanceof XmlSyntaxError) throw malformed$1(request, context, `a document outside the XML stowage reads: ${failure.message}`, failure);
+		throw failure;
+	}
+}
+function malformed$1(request, context, what, cause) {
+	return s3Error(request.bucket, {
+		...context,
+		code: "ProviderError",
+		message: `The provider answered ${request.subject} with ${what}`,
+		cause
+	});
+}
+//#endregion
+//#region src/canonical.ts
+/** What `encodeURIComponent` leaves alone and RFC 3986 counts as reserved. */
+const reservedByEncodeUriComponent = /[!'()*]/g;
+/** Runs of whitespace inside a header value, which SigV4 folds to one space. */
+const whitespaceRun = /\s+/g;
+function encodeRfc3986(value) {
+	return encodeURIComponent(value).replace(reservedByEncodeUriComponent, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+/**
+* The canonical URI: the path percent-encoded segment by segment, so that a slash stays
+* a slash and `#`, `%`, `?`, `+`, a space and everything above ASCII travel encoded
+* (spec 7.4). S3 encodes the path once and normalizes nothing, which is why no `URL` is
+* built from it: the constructor folds a `..` segment away and decodes what it was
+* handed, and both would sign a path other than the one the request carries.
+*/
+function encodePath(path) {
+	return path.split("/").map(encodeRfc3986).join("/");
+}
+/** The canonical query string: every pair encoded, sorted by name and then by value. */
+function encodeQuery(query) {
+	return query.map(([name, value]) => [encodeRfc3986(name), encodeRfc3986(value)]).toSorted(compareFields).map(([name, value]) => `${name}=${value}`).join("&");
+}
+/**
+* The canonical headers: names folded to lower case, values trimmed with their inner
+* runs of whitespace folded to one space, fields of one name joined in the order they
+* arrived, and the whole sorted by name.
+*/
+function canonicalHeaders(fields) {
+	const joined = /* @__PURE__ */ new Map();
+	for (const [name, value] of fields) {
+		const folded = name.toLowerCase();
+		const trimmed = value.trim().replace(whitespaceRun, " ");
+		const held = joined.get(folded);
+		joined.set(folded, held === void 0 ? trimmed : `${held},${trimmed}`);
+	}
+	const sorted = [...joined].toSorted(compareFields);
+	return {
+		lines: sorted.map(([name, value]) => `${name}:${value}\n`).join(""),
+		names: sorted.map(([name]) => name).join(";")
+	};
+}
+function compareFields(one, other) {
+	if (one[0] !== other[0]) return one[0] < other[0] ? -1 : 1;
+	if (one[1] !== other[1]) return one[1] < other[1] ? -1 : 1;
+	return 0;
+}
+//#endregion
+//#region src/range.ts
+/** Refuses bounds the spec does not allow, before any request goes out (spec 4.3). */
+function requireRange(bucket, range) {
+	if (range === void 0) return;
+	const { start, end } = range;
+	if (!isOffset(start) || end !== void 0 && (!isOffset(end) || end < start)) throw optionError$1(bucket, "range", "takes two whole numbers from zero up, `start` at most `end`", "get");
+}
+/** The `Range` field of RFC 9110, both ends inclusive as `ByteRange` is. */
+function rangeHeader(range) {
+	return `bytes=${range.start}-${range.end ?? ""}`;
+}
+const contentRange = /^bytes (\d+)-(\d+)\/(\d+)$/u;
+/**
+* The size of the whole object out of a `206`'s `Content-Range`, which is what spec 4.4
+* has a ranged `get` report rather than the length of the range.
+*/
+function wholeSizeOf(response) {
+	const found = contentRange.exec(response.headers.get("content-range")?.trim() ?? "");
+	const size = Number(found?.[3]);
+	return Number.isSafeInteger(size) ? size : void 0;
+}
+/**
+* A provider that answers a ranged `GET` with `200` sent the whole object instead, which
+* RFC 9110 allows. Where the range covers the object, clipped as spec 4.3 clips it, that
+* is the body asked for. For an object the range starts beyond, which is how S3 answers a
+* range on an empty object, it is the refusal spec 4.3 names; for any other it is a body
+* the caller did not ask for.
+*/
+function wholeAnswerFailure(bucket, key, range, size) {
+	if (range.start === 0 && size > 0 && (range.end === void 0 || range.end >= size - 1)) return;
+	if (range.start >= size) return s3Error(bucket, {
+		code: "InvalidRequest",
+		message: `The range starts beyond the ${size} bytes under the key ${JSON.stringify(key)}`,
+		operation: "get",
+		key,
+		attempts: 1
+	});
+	return s3Error(bucket, {
+		code: "ProviderError",
+		message: `The provider answered a range of the object under ${JSON.stringify(key)} with the whole of it`,
+		operation: "get",
+		key,
+		attempts: 1
+	});
+}
+function isOffset(value) {
+	return Number.isInteger(value) && value >= 0;
+}
+//#endregion
+//#region src/user-metadata.ts
+const headerPrefix = "x-amz-meta-";
+/** Spec 4.3 bounds the set at 2 KB of the header bytes it costs once it is encoded. */
+const headerByteLimit = 2048;
+/** The characters RFC 9110 allows in a field name, which is what a user metadata key is. */
+const httpToken = /^[!#$%&'*+.^_`|~\dA-Za-z-]+$/u;
+/**
+* What survives a header field as it stands: printable ASCII with no space at either end,
+* which HTTP trims, and no `=?`, which the reader would take for the start of an encoded
+* word.
+*/
+const travelsAsWritten = /^(?:[\x21-\x7e](?:[\x20-\x7e]*[\x21-\x7e])?)?$/u;
+const encodedWordStart = "=?UTF-8?B?";
+const encodedWordEnd = "?=";
+/**
+* RFC 2047 bounds an encoded word at 75 characters; 45 bytes are 60 characters of base64,
+* which leaves room for the 12 the word's frame costs.
+*/
+const bytesPerEncodedWord = 45;
+const utf8$4 = new TextEncoder();
+/**
+* The header fields `userMetadata` travels in, refused with `InvalidRequest` before the
+* request is signed where a key is no ASCII HTTP token or the whole set is above 2 KB of
+* encoded header bytes (spec 4.3). A key outside ASCII is refused rather than sent,
+* because R2 strips it on the way out and a write would lose it silently (ADR 0014).
+*/
+function userMetadataHeaders(bucket, userMetadata, key) {
+	const headers = [];
+	const held = Object.create(null);
+	let headerBytes = 0;
+	for (const [name, value] of Object.entries(userMetadata ?? {})) {
+		if (!httpToken.test(name)) throw refusal$1(bucket, `The user metadata key ${JSON.stringify(name)} is no ASCII HTTP token`, key);
+		const folded = name.toLowerCase();
+		if (folded in held) throw refusal$1(bucket, `The user metadata key ${JSON.stringify(folded)} is given more than once`, key);
+		const encoded = encodeValue(value);
+		held[folded] = value;
+		headers.push([`${headerPrefix}${folded}`, encoded]);
+		headerBytes += folded.length + encoded.length;
+	}
+	if (headerBytes > headerByteLimit) throw refusal$1(bucket, `The user metadata is ${headerBytes} encoded header bytes, above the limit of ${headerByteLimit}`, key);
+	return {
+		headers,
+		held: Object.freeze(held)
+	};
+}
+/**
+* The user metadata a `GET` or a `HEAD` response carries. AWS decodes an encoded word
+* before it stores the value and encodes it again on the way out, in a form of its own
+* choosing, so every form RFC 2047 allows is read and not only the one written.
+*/
+function readUserMetadata(headers) {
+	const held = Object.create(null);
+	for (const [name, value] of headers) {
+		if (!name.startsWith(headerPrefix)) continue;
+		held[name.slice(11)] = decodeValue(value);
+	}
+	return Object.freeze(held);
+}
+function encodeValue(value) {
+	if (travelsAsWritten.test(value) && !value.includes("=?")) return value;
+	return utf8PiecesOf(value).map((piece) => `${encodedWordStart}${btoa(String.fromCharCode(...piece))}${encodedWordEnd}`).join(" ");
+}
+/** The UTF-8 bytes in pieces of at most one encoded word, each ending on a character. */
+function utf8PiecesOf(value) {
+	const pieces = [];
+	let pending = [];
+	for (const character of value) {
+		const bytes = utf8$4.encode(character);
+		if (pending.length + bytes.length > bytesPerEncodedWord) {
+			pieces.push(Uint8Array.from(pending));
+			pending = [];
+		}
+		pending.push(...bytes);
+	}
+	pieces.push(Uint8Array.from(pending));
+	return pieces;
+}
+const encodedWord = /=\?([^?\s]+)\?([BbQq])\?([^?\s]*)\?=/gu;
+const whitespaceOnly = /^[ \t]+$/u;
+const hexPair = /^[\dA-Fa-f]{2}$/u;
+function decodeValue(value) {
+	let decoded = "";
+	let last = 0;
+	let previousWasEncoded = false;
+	for (const match of value.matchAll(encodedWord)) {
+		const between = value.slice(last, match.index);
+		const word = decodeWord(match[1] ?? "", match[2] ?? "", match[3] ?? "");
+		if (!(previousWasEncoded && word !== void 0 && whitespaceOnly.test(between))) decoded += between;
+		decoded += word ?? match[0];
+		previousWasEncoded = word !== void 0;
+		last = match.index + match[0].length;
+	}
+	return decoded + value.slice(last);
+}
+/** The text of one encoded word, or `undefined` where it names what cannot be read. */
+function decodeWord(charset, encoding, text) {
+	const bytes = encoding.toUpperCase() === "B" ? base64Bytes(text) : quotedBytes(text);
+	if (bytes === void 0) return void 0;
+	try {
+		return new TextDecoder(charset, { fatal: true }).decode(bytes);
+	} catch {
+		return;
+	}
+}
+function base64Bytes(text) {
+	try {
+		return Uint8Array.from(atob(text), (character) => character.charCodeAt(0));
+	} catch {
+		return;
+	}
+}
+/** The `Q` encoding: `_` is a space and `=XX` one byte in hex. */
+function quotedBytes(text) {
+	const bytes = [];
+	for (let index = 0; index < text.length; index += 1) {
+		const character = text[index];
+		if (character === "_") bytes.push(32);
+		else if (character === "=") {
+			const pair = text.slice(index + 1, index + 3);
+			if (!hexPair.test(pair)) return void 0;
+			bytes.push(Number.parseInt(pair, 16));
+			index += 2;
+		} else bytes.push(text.charCodeAt(index));
+	}
+	return Uint8Array.from(bytes);
+}
+function refusal$1(bucket, message, key) {
+	return s3Error(bucket, {
+		code: "InvalidRequest",
+		message,
+		operation: "put",
+		key,
+		attempts: 0
+	});
+}
+//#endregion
+//#region src/description.ts
+const defaultContentType = "application/octet-stream";
+/** The description a `GET` or a `HEAD` response carries in its headers (spec 4.4). */
+function describeResponse(bucket, key, operation, response) {
+	return {
+		key,
+		size: sizeOf$1(bucket, key, operation, response),
+		lastModified: lastModifiedOf(bucket, key, operation, response),
+		etag: etagOf$1(response),
+		contentType: response.headers.get("content-type") ?? "application/octet-stream",
+		userMetadata: readUserMetadata(response.headers)
+	};
+}
+/**
+* What `put` wrote, described from what it sent: a `PutObject` answer carries the entity
+* tag and the time the provider accepted the object, and neither length nor type. Spec
+* 4.4 has that time come from the provider, so an answer without one is reported rather
+* than dated from this clock. `CompleteMultipartUpload` carries its entity tag in the
+* body instead, and hands it in as `etag`.
+*/
+function describeWrite(bucket, key, size, contentType, userMetadata, response, etag = etagOf$1(response)) {
+	const accepted = Date.parse(response.headers.get("date") ?? "");
+	if (Number.isNaN(accepted)) throw incomplete(bucket, key, "put", "no time it was accepted");
+	return {
+		key,
+		size,
+		lastModified: new Date(accepted),
+		etag,
+		contentType,
+		userMetadata
+	};
+}
+function etagOf$1(response) {
+	const etag = response.headers.get("etag");
+	if (etag === null) return void 0;
+	return unquotedEtag(etag);
+}
+function unquotedEtag(etag) {
+	return etag.replace(/^"|"$/gu, "");
+}
+function sizeOf$1(bucket, key, operation, response) {
+	if (response.status === 206) {
+		const size = wholeSizeOf(response);
+		if (size === void 0) throw incomplete(bucket, key, operation, "no size of the whole object");
+		return size;
+	}
+	const header = response.headers.get("content-length");
+	if (header === null || header.trim() === "") throw incomplete(bucket, key, operation, "no length");
+	const length = Number(header);
+	if (!Number.isInteger(length) || length < 0) throw incomplete(bucket, key, operation, "no length");
+	return length;
+}
+function lastModifiedOf(bucket, key, operation, response) {
+	const modified = Date.parse(response.headers.get("last-modified") ?? "");
+	if (Number.isNaN(modified)) throw incomplete(bucket, key, operation, "no last-modified time");
+	return new Date(modified);
+}
+function incomplete(bucket, key, operation, missing) {
+	return s3Error(bucket, {
+		code: "ProviderError",
+		message: `The provider described the object under ${JSON.stringify(key)} with ${missing}`,
+		operation,
+		key,
+		attempts: 1
+	});
+}
+//#endregion
+//#region src/credentials.ts
+/** The three fields spec 7.1 names, and the whole set a resolved credential may carry. */
+const credentialFields = /* @__PURE__ */ new Set([
+	"accessKeyId",
+	"secretAccessKey",
+	"sessionToken"
+]);
+const accessKeyIdVariable = "AWS_ACCESS_KEY_ID";
+const secretAccessKeyVariable = "AWS_SECRET_ACCESS_KEY";
+const sessionTokenVariable = "AWS_SESSION_TOKEN";
+/**
+* Spec 7.3: the credential is resolved before every request that is signed and nothing
+* is cached between calls, so a rotation the resolver performs reaches the next request.
+*/
+async function resolveCredentials(source, options) {
+	return validate(typeof source === "function" ? await source(options) : source);
+}
+/**
+* A resolver, passed as `credentials: fromEnv` rather than called, so that a rotated
+* `AWS_SESSION_TOKEN` reaches the next request. Reading the three variables again is
+* what a refresh is here, so the options it is handed decide nothing (ADR 0007).
+*/
+function fromEnv(_options) {
+	const accessKeyId = readEnvironment(accessKeyIdVariable);
+	const secretAccessKey = readEnvironment(secretAccessKeyVariable);
+	const sessionToken = readEnvironment(sessionTokenVariable);
+	if (accessKeyId === "") throw emptyVariable(accessKeyIdVariable);
+	if (secretAccessKey === "") throw emptyVariable(secretAccessKeyVariable);
+	return sessionToken === "" ? {
+		accessKeyId,
+		secretAccessKey
+	} : {
+		accessKeyId,
+		secretAccessKey,
+		sessionToken
+	};
+}
+/**
+* ADR 0007: `process.env` is the one route through Node, Bun, Deno's compatibility layer
+* and a Worker under `nodejs_compat`. A Worker without it has no `process` at all, and
+* Deno without `--allow-env` throws `NotCapable` rather than answering `undefined`, so
+* both leave the value empty. The three names are read one at a time, because
+* enumerating `process.env` needs the unscoped permission in Deno.
+*/
+function readEnvironment(name) {
+	try {
+		if (typeof process === "undefined") return "";
+		return process?.env?.[name] ?? "";
+	} catch {
+		return "";
+	}
+}
+/**
+* Spec 7.3: both required fields are non-empty strings and every key of the resolved
+* object is one of the three, checked before signing rather than a round trip later.
+*/
+function validate(credentials) {
+	if (typeof credentials !== "object" || credentials === null) throw refusal("The resolved credential is not an object");
+	for (const field of Object.keys(credentials)) if (!credentialFields.has(field)) throw refusal(`The credential field \`${field}\` is not one of the three S3 takes`);
+	requireFilled(credentials.accessKeyId, "accessKeyId");
+	requireFilled(credentials.secretAccessKey, "secretAccessKey");
+	return credentials;
+}
+function requireFilled(value, field) {
+	if (typeof value === "string" && value !== "") return;
+	throw refusal(`The credential field \`${field}\` is empty`);
+}
+function emptyVariable(name) {
+	return refusal(`The environment variable \`${name}\` is empty`);
+}
+function refusal(message) {
+	return s3Error("", {
+		code: "InvalidCredentials",
+		message,
+		operation: "credentials",
+		attempts: 0
+	});
+}
+//#endregion
+//#region src/error-document.ts
+/**
+* The `Code` and `Message` a provider answers a failed request with. The parser spec 7.4
+* puts in front of a listing reads a structure; a failure needs two texts out of one flat
+* element, and a body that is no error document — an HTML page from a proxy in between,
+* a body the provider left empty — leaves both unset rather than failing on its way to
+* reporting a failure.
+*/
+function readErrorDocument(body) {
+	return {
+		code: textOf(body, "Code"),
+		message: textOf(body, "Message")
+	};
+}
+function textOf(body, element) {
+	const text = new RegExp(`<${element}>([^<]*)</${element}>`, "u").exec(body)?.[1];
+	return text === void 0 ? void 0 : decodeEntities(text);
+}
+function decodeEntities(text) {
+	return text.replaceAll(/&(#x[\da-f]+|#\d+|[a-z]+);/giu, (entity, name) => {
+		if (name.startsWith("#")) {
+			const codePoint = Number(name.startsWith("#x") ? `0x${name.slice(2)}` : name.slice(1));
+			return Number.isInteger(codePoint) && codePoint >= 0 && codePoint <= 1114111 ? String.fromCodePoint(codePoint) : entity;
+		}
+		return predefinedEntities.get(name.toLowerCase()) ?? entity;
+	});
+}
+//#endregion
+//#region src/hash.ts
+const utf8$3 = new TextEncoder();
+/**
+* ADR 0009: Web Crypto defines SHA-256 as one shot over a `BufferSource` and has no
+* incremental form, so the adapter holds what it hashes whole.
+*/
+async function sha256Hex(data) {
+	return hex(await crypto.subtle.digest("SHA-256", bytesOf$1(data)));
+}
+async function hmacSha256(key, data) {
+	const imported = await crypto.subtle.importKey("raw", key, {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	return await crypto.subtle.sign("HMAC", imported, utf8$3.encode(data));
+}
+function hex(buffer) {
+	return Array.from(new Uint8Array(buffer), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function bytesOf$1(data) {
+	return typeof data === "string" ? utf8$3.encode(data) : data;
+}
+//#endregion
+//#region src/sign.ts
+const signingAlgorithm = "AWS4-HMAC-SHA256";
+async function signRequest(request) {
+	const amzDate = amzDateOf(request.date);
+	const scope = scopeOf(request, amzDate);
+	const toSend = [
+		...request.headers,
+		["x-amz-date", amzDate],
+		...sessionTokenField(request.credentials)
+	];
+	const canonical = canonicalHeaders([...toSend, ["host", request.host]]);
+	const signed = await signCanonical(request, {
+		query: request.query,
+		headers: canonical,
+		payloadHash: request.payloadHash,
+		amzDate,
+		scope
+	});
+	const authorization = `${signingAlgorithm} Credential=${request.credentials.accessKeyId}/${scope}, SignedHeaders=${canonical.names}, Signature=${signed.signature}`;
+	return {
+		headers: [...toSend, ["authorization", authorization]],
+		...signed
+	};
+}
+/**
+* Spec 7.4 and ADR 0011: the payload hash a presigned URL signs, which excludes the body
+* from the signature because the signer never sees it. It is written here and nowhere
+* else, so a request the adapter sends itself has no way to carry it.
+*/
+const unsignedPayload = "UNSIGNED-PAYLOAD";
+/**
+* SigV4 query signing: the authorization travels in the query rather than in headers, so
+* that a client holding no credential can send the request. The headers it binds are
+* signed and not handed back, because whoever calls the URL sends them.
+*/
+async function presignRequest(request) {
+	const amzDate = amzDateOf(request.date);
+	const scope = scopeOf(request, amzDate);
+	const canonical = canonicalHeaders([...request.headers, ["host", request.host]]);
+	const query = [
+		...request.query,
+		["X-Amz-Algorithm", signingAlgorithm],
+		["X-Amz-Credential", `${request.credentials.accessKeyId}/${scope}`],
+		["X-Amz-Date", amzDate],
+		["X-Amz-Expires", String(request.expiresIn)],
+		["X-Amz-SignedHeaders", canonical.names],
+		...sessionTokenParameter(request.credentials)
+	];
+	const signed = await signCanonical(request, {
+		query,
+		headers: canonical,
+		payloadHash: unsignedPayload,
+		amzDate,
+		scope
+	});
+	return {
+		query: [...query, ["X-Amz-Signature", signed.signature]],
+		canonicalRequest: signed.canonicalRequest,
+		stringToSign: signed.stringToSign
+	};
+}
+async function signCanonical(request, input) {
+	const canonicalRequest = [
+		request.method,
+		encodePath(request.path),
+		encodeQuery(input.query),
+		input.headers.lines,
+		input.headers.names,
+		input.payloadHash
+	].join("\n");
+	const stringToSign = [
+		signingAlgorithm,
+		input.amzDate,
+		input.scope,
+		await sha256Hex(canonicalRequest)
+	].join("\n");
+	return {
+		canonicalRequest,
+		stringToSign,
+		signature: hex(await hmacSha256(await signingKey(request, input.amzDate.slice(0, 8)), stringToSign))
+	};
+}
+function scopeOf(request, amzDate) {
+	return `${amzDate.slice(0, 8)}/${request.region}/${request.service}/aws4_request`;
+}
+/** `20150830T123600Z`, which is what `x-amz-date` and the credential scope are written in. */
+function amzDateOf(date) {
+	return `${date.toISOString().replaceAll(/[.:-]/gu, "").slice(0, 15)}Z`;
+}
+function sessionTokenField(credentials) {
+	if (credentials.sessionToken === void 0) return [];
+	return [["x-amz-security-token", credentials.sessionToken]];
+}
+function sessionTokenParameter(credentials) {
+	if (credentials.sessionToken === void 0) return [];
+	return [["X-Amz-Security-Token", credentials.sessionToken]];
+}
+async function signingKey(request, dateStamp) {
+	return await hmacSha256(await hmacSha256(await hmacSha256(await hmacSha256(new TextEncoder().encode(`AWS4${request.credentials.secretAccessKey}`), dateStamp), request.region), request.service), "aws4_request");
+}
+//#endregion
+//#region src/request.ts
+const emptyBody = /* @__PURE__ */ new Uint8Array(0);
+/**
+* Spec 4.4 reads `size` off `Content-Length`, and a provider that compresses on the offer
+* `fetch` makes of its own on Node, Bun and Deno drops that header: R2 does for JSON and
+* text. It is sent unsigned, because it concerns the transfer rather than what the
+* provider acts on, and a hop that rewrites it would otherwise break the signature.
+*/
+const identityEncoding = ["accept-encoding", "identity"];
+const service = "s3";
+/**
+* One S3 request, answered by the response the provider sent or rejected with the failure
+* it reported. Spec 7.4 computes the payload hash once and signs every attempt again; the
+* loop of spec 7.5 lives in `@stowage/core`, as the one definition of the budget and the
+* curve that a third-party adapter reads too.
+*/
+async function send(configuration, request) {
+	const payloadHash = await sha256Hex(request.body ?? emptyBody);
+	let requestsSent = 0;
+	try {
+		return await withRetry(async () => {
+			try {
+				return await attemptWithRefresh(configuration, request, payloadHash);
+			} catch (failure) {
+				if (!isStorageError(failure)) throw failure;
+				requestsSent += failure.attempts;
+				if (request.repeatWithoutResponse === false && receivedNoResponse(failure)) throw new Unrepeated(withAttemptsMade(failure, requestsSent));
+				throw failure;
+			}
+		}, {
+			maxAttempts: configuration.maxAttempts,
+			signal: request.signal
+		});
+	} catch (thrown) {
+		if (thrown instanceof Unrepeated) throw thrown.failure;
+		throw thrown;
+	}
+}
+/**
+* A failure carried past `withRetry`, which repeats every `retryable` `StorageError` it
+* sees; the one that must not be repeated still reaches the caller as `retryable`,
+* because spec 4.10 has that flag state the condition and not what stowage did about it.
+*/
+var Unrepeated = class {
+	failure;
+	constructor(failure) {
+		this.failure = failure;
+	}
+};
+function receivedNoResponse(failure) {
+	return failure.code === "NetworkError" && failure.status === void 0;
+}
+/**
+* One attempt, which spec 7.3 has cost a second request where the provider answered
+* `Expired`: the credential is resolved again under `forceRefresh` and the request goes
+* out without a delay, because no wait makes a credential fresher. `retry: false` does
+* not switch that repeat off, so an attempt costs one request or two and an operation at
+* most six (ADR 0013).
+*/
+async function attemptWithRefresh(configuration, request, payloadHash) {
+	try {
+		return await attemptOnce(configuration, request, payloadHash, false, 1);
+	} catch (failure) {
+		if (!isStorageError(failure) || failure.code !== "Expired") throw failure;
+		return await attemptOnce(configuration, request, payloadHash, true, 2);
+	}
+}
+/** One signed request, which is the attempt CONTEXT.md names and what a repeat repeats. */
+async function attemptOnce(configuration, request, payloadHash, forceRefresh, attempts) {
+	const path = pathOf(configuration, request.key);
+	const query = request.query ?? [];
+	const credentials = await resolveCredentials(configuration.credentials, { forceRefresh }).catch((failure) => {
+		throw inStorage(failure, configuration.bucket, request.operation, request.key);
+	});
+	const signed = await signRequest({
+		method: request.method,
+		host: configuration.host,
+		path,
+		query,
+		headers: [...request.headers ?? [], ["x-amz-content-sha256", payloadHash]],
+		payloadHash,
+		credentials,
+		region: configuration.region,
+		service,
+		date: /* @__PURE__ */ new Date()
+	});
+	const url = urlOf(configuration, path, query);
+	let response;
+	try {
+		response = await fetch(url, {
+			method: request.method,
+			headers: [...signed.headers, identityEncoding].map(([name, value]) => [name, value]),
+			body: request.body,
+			signal: request.signal
+		});
+	} catch (failure) {
+		throw transportFailure(configuration, request, failure, attempts);
+	}
+	if (response.ok) return response;
+	throw await failureOf(configuration, request, response, attempts);
+}
+/**
+* Spec 7.1: the bucket is addressed virtual-hosted through the host, and path-style
+* through the first segment of the path. The key follows as it stands; `encodePath` is
+* what percent-encodes it, on the URL and in the signature alike.
+*/
+function pathOf(configuration, key) {
+	const prefix = configuration.forcePathStyle ? `${configuration.basePath}/${configuration.bucket}` : configuration.basePath;
+	if (key === void 0) return prefix === "" ? "/" : prefix;
+	return `${prefix}/${key}`;
+}
+/**
+* The URL a request is sent to, its path and query encoded as SigV4 signs them: the
+* provider rebuilds the canonical request from what the URL carries, so the two may not
+* differ by a single escape.
+*/
+function urlOf(configuration, path, query) {
+	const search = query.length === 0 ? "" : `?${encodeQuery(query)}`;
+	return `${configuration.protocol}//${configuration.host}${encodePath(path)}${search}`;
+}
+/**
+* Spec 7.9: the provider's own code decides where the table recognizes one, the status of
+* spec 4.10 decides where it does not, and the status alone decides whether the condition
+* is transient. `status`, `providerCode`, `requestId` and the provider's message travel
+* along, which is what makes a failure traceable at the provider.
+*/
+async function failureOf(configuration, request, response, attempts) {
+	const document = await readFailure(request, response);
+	const failure = readProviderFailure({
+		status: response.status,
+		operation: request.operation,
+		method: request.method,
+		key: request.key,
+		hasContinuationToken: request.query?.some(([name]) => name === "continuation-token"),
+		providerCode: document.code,
+		providerMessage: document.message,
+		bucketRegion: response.headers.get("x-amz-bucket-region") ?? void 0
+	});
+	return s3Error(configuration.bucket, {
+		code: failure.code,
+		message: failure.message,
+		operation: request.operation,
+		key: request.key,
+		attempts,
+		status: response.status,
+		providerCode: document.code,
+		requestId: response.headers.get("x-amz-request-id") ?? void 0,
+		retryable: isTransientStatus(response.status)
+	});
+}
+/**
+* Spec 7.9: `HEAD` carries no body, so `stat` and `exists` report the status alone. Every
+* other failed request is answered with the provider's error document, and reading it to
+* the end is also what releases the connection the next attempt needs.
+*/
+async function readFailure(request, response) {
+	if (request.method === "HEAD") {
+		await response.body?.cancel();
+		return {};
+	}
+	try {
+		return readErrorDocument(await response.text());
+	} catch {
+		return {};
+	}
+}
+function transportFailure(configuration, request, failure, attempts) {
+	if (failure instanceof Error && failure.name === "AbortError") return failure;
+	return s3Error(configuration.bucket, {
+		code: "NetworkError",
+		message: `The request received no response: ${String(failure)}`,
+		operation: request.operation,
+		key: request.key,
+		attempts,
+		retryable: true,
+		cause: failure
+	});
+}
+//#endregion
+//#region src/copy.ts
+/**
+* Spec 7.8: one `CopyObject`, with the provider's refusal of a source too large for it as
+* the answer rather than a fallback to `UploadPartCopy` (ADR 0016). S3's default
+* directive keeps the source's content type and user metadata, which spec 4.11 asks of a
+* copy. Its answer names neither the size nor the user metadata of what it wrote, so a `HEAD`
+* of the destination describes it.
+*/
+async function copyObject(configuration, from, to, operation, signal) {
+	const { bucket } = configuration;
+	signal?.throwIfAborted();
+	const response = await send(configuration, {
+		method: "PUT",
+		operation,
+		key: to,
+		headers: [["x-amz-copy-source", encodePath(`/${bucket}/${from}`)]],
+		signal
+	}).catch((failure) => {
+		if (isStorageError(failure) && failure.providerCode === "NoSuchKey") throw inStorage(failure, bucket, operation, from);
+		throw failure;
+	});
+	await readAnswerDocument({
+		bucket,
+		operation,
+		key: to,
+		subject: "the copy"
+	}, response, "CopyObjectResult");
+	return describeResponse(bucket, to, operation, await send(configuration, {
+		method: "HEAD",
+		operation,
+		key: to,
+		signal
+	}));
+}
+//#endregion
+//#region src/key.ts
+/** The error the key violating the rule is reported as, or `undefined` where it holds. */
+function keyError(bucket, key, rule, operation) {
+	const reason = invalidKeyReason(key, rule);
+	if (reason === void 0) return void 0;
+	return s3Error(bucket, {
+		code: "InvalidKey",
+		message: `The key ${JSON.stringify(key)} ${reason}`,
+		operation,
+		key,
+		attempts: 0
+	});
+}
+function requireKey(bucket, key, rule, operation) {
+	const error = keyError(bucket, key, rule, operation);
+	if (error !== void 0) throw error;
+}
+//#endregion
+//#region src/cursor.ts
+const cursorTag = "stowage-s3-1:";
+const unitDigits = 4;
+const hexPosition = new RegExp(`^(?:[\\da-f]{${unitDigits}})*$`);
+/** The provider's continuation token, as the opaque string that continues from there. */
+function encodeCursor(continuationToken) {
+	return btoa(`${cursorTag}${hexOf(continuationToken)}`);
+}
+/** The token the cursor continues from, or `undefined` for one this adapter did not produce. */
+function decodeCursor(cursor) {
+	let decoded;
+	try {
+		decoded = atob(cursor);
+	} catch {
+		return;
+	}
+	if (!decoded.startsWith(cursorTag)) return void 0;
+	const position = decoded.slice(13);
+	return position.length > 0 && hexPosition.test(position) ? tokenOf(position) : void 0;
+}
+function hexOf(token) {
+	const units = [];
+	for (let index = 0; index < token.length; index += 1) units.push(token.charCodeAt(index).toString(16).padStart(unitDigits, "0"));
+	return units.join("");
+}
+function tokenOf(position) {
+	const units = [];
+	for (let index = 0; index < position.length; index += unitDigits) units.push(String.fromCharCode(Number.parseInt(position.slice(index, index + unitDigits), 16)));
+	return units.join("");
+}
+//#endregion
+//#region src/listing-document.ts
+/**
+* What the provider listed, read through the parser of ADR 0003. Spec 4.6 makes an entry
+* that arrives without a key, a size or a last-modified time a `ProviderError`, and
+* spec 7.4 a document outside the subset the parser reads; both leave the page unread
+* rather than hand the caller a value made up for what was missing.
+*/
+function readListingDocument(answer, body) {
+	const root = parse(answer, body);
+	if (root.name !== "ListBucketResult") throw malformed(answer, `a <${root.name}> where a <ListBucketResult> belongs`);
+	return {
+		objects: childrenNamed(root, "Contents").map((entry) => readEntry(answer, entry)),
+		prefixes: childrenNamed(root, "CommonPrefixes").map((prefix) => {
+			const text = textOf$1(prefix, "Prefix");
+			if (text === void 0 || text === "") throw malformed(answer, "a pseudo-directory with no prefix");
+			return text;
+		}),
+		continuationToken: continuationOf(answer, root)
+	};
+}
+function parse(answer, body) {
+	try {
+		return parseXml(body);
+	} catch (failure) {
+		if (failure instanceof XmlSyntaxError) throw malformed(answer, `a document outside the XML stowage reads: ${failure.message}`, failure);
+		throw failure;
+	}
+}
+function readEntry(answer, entry) {
+	const key = textOf$1(entry, "Key");
+	if (key === void 0 || key === "") throw malformed(answer, "an object with no key");
+	const size = sizeOf(textOf$1(entry, "Size"));
+	if (size === void 0) throw malformed(answer, `the object under ${JSON.stringify(key)} with no size`);
+	const lastModified = Date.parse(textOf$1(entry, "LastModified") ?? "");
+	if (Number.isNaN(lastModified)) throw malformed(answer, `the object under ${JSON.stringify(key)} with no last-modified time`);
+	return {
+		key,
+		size,
+		lastModified: new Date(lastModified),
+		etag: etagOf(textOf$1(entry, "ETag"))
+	};
+}
+const decimalDigits = /^\d+$/u;
+function sizeOf(text) {
+	if (text === void 0 || !decimalDigits.test(text)) return void 0;
+	const size = Number(text);
+	return Number.isSafeInteger(size) ? size : void 0;
+}
+function etagOf(text) {
+	if (text === void 0 || text === "") return void 0;
+	return unquotedEtag(text);
+}
+/**
+* The token the next page continues from. A listing the provider calls truncated and
+* hands no token for would end early without a word, so that is malformed too.
+*/
+function continuationOf(answer, root) {
+	const truncated = textOf$1(root, "IsTruncated");
+	if (truncated === "false") return void 0;
+	if (truncated !== "true") throw malformed(answer, "no word on whether the listing is complete");
+	const token = textOf$1(root, "NextContinuationToken");
+	if (token === void 0 || token === "") throw malformed(answer, "a listing it calls incomplete and no position to continue from");
+	return token;
+}
+function childrenNamed(element, name) {
+	return element.children.filter((child) => child.name === name);
+}
+function malformed(answer, what, cause) {
+	return s3Error(answer.bucket, {
+		code: "ProviderError",
+		message: `The provider answered the listing with ${what}`,
+		operation: answer.operation,
+		attempts: 1,
+		status: answer.status,
+		requestId: answer.requestId,
+		cause
+	});
+}
+//#endregion
+//#region src/listing.ts
+const defaultPageSize = 1e3;
+const maxPageSize = 1e3;
+/**
+* Spec 4.6: a listing sends no request until it is read, so an option it refuses reaches
+* the caller from `page()` and from the iteration and not from `list`.
+*/
+function createListing(configuration, options) {
+	return {
+		async page() {
+			const document = await requestPage(configuration, readListRequest(configuration.bucket, options));
+			return {
+				objects: document.objects,
+				prefixes: document.prefixes,
+				cursor: document.continuationToken === void 0 ? void 0 : encodeCursor(document.continuationToken)
+			};
+		},
+		async *[Symbol.asyncIterator]() {
+			for await (const document of walkPages(configuration, readListRequest(configuration.bucket, options))) yield* document.objects;
+		}
+	};
+}
+/**
+* Every page of the listing from where the request starts to its end, which `list`
+* iterates and `deleteAll` deletes page by page as it arrives.
+*/
+async function* walkPages(configuration, request) {
+	for (let { continuationToken } = request;;) {
+		const document = await requestPage(configuration, {
+			...request,
+			continuationToken
+		});
+		if (document.continuationToken !== void 0 && document.continuationToken === continuationToken) throw s3Error(configuration.bucket, {
+			code: "ProviderError",
+			message: "The provider repeated the continuation token it was sent",
+			operation: request.operation,
+			attempts: 1
+		});
+		yield document;
+		if (document.continuationToken === void 0) return;
+		continuationToken = document.continuationToken;
+	}
+}
+/** Everything spec 4.11 has `list` refuse without asking the provider. */
+function readListRequest(bucket, options) {
+	requireKnownOptions(bucket, options, listOptionKeys, "list");
+	const prefix = options?.prefix ?? "";
+	requireKey(bucket, prefix, "prefix", "list");
+	const pageSize = options?.pageSize ?? defaultPageSize;
+	if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > 1e3) throw optionError$1(bucket, "pageSize", `takes a whole number from 1 to ${maxPageSize}`, "list");
+	if (options?.delimiter === "") throw optionError$1(bucket, "delimiter", "takes at least one character", "list");
+	const cursor = options?.cursor;
+	const continuationToken = cursor === void 0 ? void 0 : decodeCursor(cursor);
+	if (cursor !== void 0 && continuationToken === void 0) throw optionError$1(bucket, "cursor", "takes a cursor this storage handed out", "list");
+	return {
+		operation: "list",
+		prefix,
+		delimiter: options?.delimiter,
+		pageSize,
+		continuationToken,
+		signal: options?.signal
+	};
+}
+async function requestPage(configuration, request) {
+	request.signal?.throwIfAborted();
+	const query = [["list-type", "2"], ["max-keys", String(request.pageSize)]];
+	if (request.prefix !== "") query.push(["prefix", request.prefix]);
+	if (request.delimiter !== void 0) query.push(["delimiter", request.delimiter]);
+	if (request.continuationToken !== void 0) query.push(["continuation-token", request.continuationToken]);
+	const response = await send(configuration, {
+		method: "GET",
+		operation: request.operation,
+		query,
+		signal: request.signal
+	});
+	const answer = {
+		bucket: configuration.bucket,
+		operation: request.operation,
+		status: response.status,
+		requestId: response.headers.get("x-amz-request-id") ?? void 0
+	};
+	return readListingDocument(answer, await readBody(answer, response));
+}
+/**
+* Spec 7.5 repeats a transport failure that received no response; this one received its
+* response and broke in the body, which spec 4.5 leaves unresumed for `get` as well.
+*/
+async function readBody(answer, response) {
+	try {
+		return await response.text();
+	} catch (failure) {
+		if (failure instanceof Error && failure.name === "AbortError") throw failure;
+		throw s3Error(answer.bucket, {
+			code: "NetworkError",
+			message: `The listing broke while it was read: ${String(failure)}`,
+			operation: answer.operation,
+			attempts: 1,
+			status: answer.status,
+			requestId: answer.requestId,
+			retryable: true,
+			cause: failure
+		});
+	}
+}
+//#endregion
+//#region src/md5.ts
+/** The per-round shift amounts of RFC 1321, section 3.4. */
+const shifts = [
+	7,
+	12,
+	17,
+	22,
+	7,
+	12,
+	17,
+	22,
+	7,
+	12,
+	17,
+	22,
+	7,
+	12,
+	17,
+	22,
+	5,
+	9,
+	14,
+	20,
+	5,
+	9,
+	14,
+	20,
+	5,
+	9,
+	14,
+	20,
+	5,
+	9,
+	14,
+	20,
+	4,
+	11,
+	16,
+	23,
+	4,
+	11,
+	16,
+	23,
+	4,
+	11,
+	16,
+	23,
+	4,
+	11,
+	16,
+	23,
+	6,
+	10,
+	15,
+	21,
+	6,
+	10,
+	15,
+	21,
+	6,
+	10,
+	15,
+	21,
+	6,
+	10,
+	15,
+	21
+];
+/** `floor(abs(sin(i + 1)) × 2^32)`, the table T of RFC 1321, section 3.4. */
+const sines = Array.from({ length: 64 }, (_, index) => Math.floor(Math.abs(Math.sin(index + 1)) * 2 ** 32) >>> 0);
+const blockBytes = 64;
+/**
+* The base64 of the MD5 digest, which is the form `Content-MD5` carries. `DeleteObjects`
+* is the one request AWS refuses without an integrity header, and ADR 0009 sends no
+* `x-amz-checksum-*`; Web Crypto offers no MD5 and `node:crypto` is not on every runtime
+* of spec 2, so the digest is computed here.
+*/
+function md5Base64(message) {
+	const digest = md5(message);
+	return btoa(String.fromCharCode(...digest));
+}
+function md5(message) {
+	const padded = pad(message);
+	const words = new DataView(padded.buffer);
+	const state = [
+		1732584193,
+		4023233417,
+		2562383102,
+		271733878
+	];
+	for (let offset = 0; offset < padded.byteLength; offset += blockBytes) compress(state, words, offset);
+	const digest = /* @__PURE__ */ new Uint8Array(16);
+	const view = new DataView(digest.buffer);
+	for (const [index, word] of state.entries()) view.setUint32(index * 4, word, true);
+	return digest;
+}
+/** A `1` bit, zeros up to 56 bytes into a block, and the bit length as 64 bits, low first. */
+function pad(message) {
+	const length = Math.ceil((message.byteLength + 9) / blockBytes) * blockBytes;
+	const padded = new Uint8Array(length);
+	const view = new DataView(padded.buffer);
+	const bits = message.byteLength * 8;
+	padded.set(message);
+	padded[message.byteLength] = 128;
+	view.setUint32(length - 8, bits >>> 0, true);
+	view.setUint32(length - 4, Math.floor(bits / 2 ** 32), true);
+	return padded;
+}
+function compress(state, words, offset) {
+	let [a, b, c, d] = state;
+	for (let round = 0; round < 64; round += 1) {
+		let mixed;
+		let word;
+		if (round < 16) {
+			mixed = b & c | ~b & d;
+			word = round;
+		} else if (round < 32) {
+			mixed = d & b | ~d & c;
+			word = (5 * round + 1) % 16;
+		} else if (round < 48) {
+			mixed = b ^ c ^ d;
+			word = (3 * round + 5) % 16;
+		} else {
+			mixed = c ^ (b | ~d);
+			word = 7 * round % 16;
+		}
+		const sum = a + mixed + (sines[round] ?? 0) + words.getUint32(offset + word * 4, true) >>> 0;
+		const shift = shifts[round] ?? 0;
+		a = d;
+		d = c;
+		c = b;
+		b = b + (sum << shift | sum >>> 32 - shift) >>> 0;
+	}
+	state[0] = state[0] + a >>> 0;
+	state[1] = state[1] + b >>> 0;
+	state[2] = state[2] + c >>> 0;
+	state[3] = state[3] + d >>> 0;
+}
+//#endregion
+//#region src/delete.ts
+/** What one `DeleteObjects` names at most, and so what spec 4.1 sends one request per. */
+const keysPerRequest = 1e3;
+const utf8$2 = new TextEncoder();
+/**
+* Spec 4.7: every key is reported, the invalid ones as `InvalidKey` without being sent,
+* and a failure of a request as a whole rejects the call instead of filling the report.
+*/
+async function deleteKeys(configuration, keys, batch) {
+	const failed = [];
+	const sendable = [];
+	for (const key of keys) {
+		const refusal = refusalOf(configuration.bucket, key, batch.operation);
+		if (refusal === void 0) sendable.push(key);
+		else failed.push(refusal);
+	}
+	for (let offset = 0; offset < sendable.length; offset += keysPerRequest) {
+		const slice = sendable.slice(offset, offset + keysPerRequest);
+		failed.push(...await deleteBatch(configuration, slice, batch));
+	}
+	return {
+		requested: keys.length,
+		failed
+	};
+}
+/**
+* Spec 4.11: every object below the prefix, listed a page at a time and each page deleted
+* as it arrives, so the call holds one page of keys whatever the prefix holds.
+*/
+async function deleteBelow(configuration, prefix, signal) {
+	const operation = "deleteAll";
+	const failed = [];
+	let requested = 0;
+	for await (const page of walkPages(configuration, {
+		operation,
+		prefix,
+		pageSize: maxPageSize,
+		signal
+	})) {
+		const report = await deleteKeys(configuration, page.objects.map((entry) => entry.key), {
+			operation,
+			signal
+		});
+		requested += report.requested;
+		failed.push(...report.failed);
+	}
+	return {
+		requested,
+		failed
+	};
+}
+function refusalOf(bucket, key, operation) {
+	const invalid = keyError(bucket, key, "addressable", operation);
+	if (invalid !== void 0) return invalid;
+	if (key.isWellFormed()) return void 0;
+	return s3Error(bucket, {
+		code: "InvalidKey",
+		message: `The key ${JSON.stringify(key)} holds a lone surrogate, which has no UTF-8 form`,
+		operation,
+		key,
+		attempts: 0
+	});
+}
+async function deleteBatch(configuration, keys, batch) {
+	if (keys.length === 0) return [];
+	batch.signal?.throwIfAborted();
+	const body = utf8$2.encode(deleteDocument(keys));
+	const response = await send(configuration, {
+		method: "POST",
+		operation: batch.operation,
+		query: [["delete", ""]],
+		headers: [["content-type", "application/xml"], ["content-md5", md5Base64(body)]],
+		body,
+		signal: batch.signal
+	});
+	const requestId = response.headers.get("x-amz-request-id") ?? void 0;
+	const answered = {
+		bucket: configuration.bucket,
+		operation: batch.operation,
+		subject: "the deletion"
+	};
+	return (await readAnswerDocument(answered, response, "DeleteResult")).children.filter((child) => child.name === "Error").map((entry) => keyFailure(answered, entry, requestId));
+}
+/** `Quiet` has the provider answer with the keys it failed alone. */
+function deleteDocument(keys) {
+	return `<?xml version="1.0" encoding="UTF-8"?><Delete><Quiet>true</Quiet>${keys.map((key) => `<Object><Key>${escapeXml(key)}</Key></Object>`).join("")}</Delete>`;
+}
+/**
+* One key the provider failed, told as the answer's failure is, without the `200` that
+* spoke for the whole request. Spec 4.7 has every entry carry its key, so an entry the
+* provider names no key for leaves the answer unread rather than reported keyless.
+*/
+function keyFailure(request, entry, requestId) {
+	const key = textOf$1(entry, "Key");
+	if (key === void 0 || key === "") throw s3Error(request.bucket, {
+		code: "ProviderError",
+		message: `The provider answered ${request.subject} with a failed key it did not name`,
+		operation: request.operation,
+		attempts: 1,
+		requestId
+	});
+	return embeddedFailure(request, {
+		operation: request.operation,
+		key,
+		attempts: 1,
+		requestId
+	}, entry);
+}
+//#endregion
+//#region src/presign.ts
+/** The ceiling SigV4 query signing sets on `X-Amz-Expires`, a week in seconds. */
+const longestLifetime = 604800;
+/** Each override of spec 7.10 and the query parameter S3 answers as its response header. */
+const responseOverrides = [
+	["responseContentType", "response-content-type"],
+	["responseContentDisposition", "response-content-disposition"],
+	["responseCacheControl", "response-cache-control"],
+	["responseExpires", "response-expires"]
+];
+/** Spec 7.10: `GetObject` on an addressable key, the overrides carried in the query. */
+async function presignGet(configuration, key, options) {
+	const operation = "presignGet";
+	requireKey(configuration.bucket, key, "addressable", operation);
+	const given = readGroup(configuration.bucket, options, presignGetOptionKeys, operation);
+	const expiresIn = readExpiresIn(configuration.bucket, given.expiresIn, operation);
+	const query = [];
+	for (const [option, parameter] of responseOverrides) {
+		const value = given[option];
+		if (value === void 0) continue;
+		query.push([parameter, readText(configuration.bucket, value, option, operation)]);
+	}
+	return await presignedUrl(configuration, {
+		method: "GET",
+		operation,
+		key,
+		query,
+		headers: [],
+		expiresIn
+	});
+}
+/**
+* Spec 7.10: `PutObject` on a writable key, with the content type and the content length
+* bound through signed headers. Nothing else is signed in: no user metadata and no
+* checksum, which the browser would have to match exactly for a `403` that names nothing
+* (ADR 0011).
+*/
+async function presignPut(configuration, key, options) {
+	const operation = "presignPut";
+	requireKey(configuration.bucket, key, "writable", operation);
+	const given = readGroup(configuration.bucket, options, presignPutOptionKeys, operation);
+	const expiresIn = readExpiresIn(configuration.bucket, given.expiresIn, operation);
+	const contentType = readText(configuration.bucket, given.contentType, "contentType", operation);
+	const contentLength = readContentLength(configuration.bucket, given.contentLength, operation);
+	return await presignedUrl(configuration, {
+		method: "PUT",
+		operation,
+		key,
+		query: [],
+		headers: [["content-type", contentType], ["content-length", contentLength]],
+		expiresIn
+	});
+}
+/**
+* Spec 7.10: nothing is sent, so the one failure left after the options is the
+* credential's. It is resolved for every URL, as for every request (spec 7.3).
+*/
+async function presignedUrl(configuration, request) {
+	const credentials = await resolveCredentials(configuration.credentials, { forceRefresh: false }).catch((failure) => {
+		if (isStorageError(failure) && failure.code === "InvalidCredentials") throw inStorage(failure, configuration.bucket, request.operation, request.key);
+		throw s3Error(configuration.bucket, {
+			code: "InvalidCredentials",
+			message: "The credential resolver failed",
+			operation: request.operation,
+			key: request.key,
+			attempts: 0,
+			cause: failure
+		});
+	});
+	const path = pathOf(configuration, request.key);
+	return urlOf(configuration, path, (await presignRequest({
+		method: request.method,
+		host: configuration.host,
+		path,
+		query: request.query,
+		headers: request.headers,
+		credentials,
+		region: configuration.region,
+		service: "s3",
+		date: /* @__PURE__ */ new Date(),
+		expiresIn: request.expiresIn
+	})).query);
+}
+/**
+* The options as a group whose keys are all known. A caller outside TypeScript may hand
+* no group at all, which reads as one holding nothing, so the required `expiresIn` is
+* what the refusal names.
+*/
+function readGroup(bucket, options, known, operation) {
+	if (typeof options !== "object" || options === null) return {};
+	requireKnownOptions(bucket, options, known, operation);
+	return { ...options };
+}
+/** ADR 0011: outside the week SigV4 allows, refused rather than signed for a `403`. */
+function readExpiresIn(bucket, value, operation) {
+	if (typeof value === "number" && value >= 1 && value <= longestLifetime && Number.isInteger(value)) return value;
+	throw optionError$1(bucket, "expiresIn", `takes the whole seconds 1 to ${longestLifetime}, the lifetime SigV4 allows`, operation);
+}
+function readContentLength(bucket, value, operation) {
+	if (typeof value === "number" && Number.isInteger(value) && value >= 0) return BigInt(value).toString();
+	throw optionError$1(bucket, "contentLength", "takes a finite, non-negative integer", operation);
+}
+function readText(bucket, value, option, operation) {
+	if (typeof value === "string" && value !== "") return value;
+	throw optionError$1(bucket, option, "takes a non-empty string", operation);
+}
+//#endregion
+//#region src/stored-object.ts
+/**
+* Spec 4.5: the description and the body come out of one response, the body is read
+* once, and a stream that breaks after `get` resolved errors with a `StorageError`
+* whichever of the four readers took it.
+*/
+function createStoredObject(bucket, stat, response) {
+	let read = false;
+	const take = () => {
+		if (read) throw s3Error(bucket, {
+			code: "InvalidRequest",
+			message: "The body of this stored object has already been read",
+			operation: "get",
+			key: stat.key,
+			attempts: 0
+		});
+		read = true;
+	};
+	const broken = (failure) => s3Error(bucket, {
+		code: "NetworkError",
+		message: `The body of the object broke while it was read: ${String(failure)}`,
+		operation: "get",
+		key: stat.key,
+		attempts: 1,
+		retryable: true,
+		requestId: response.headers.get("x-amz-request-id") ?? void 0,
+		cause: failure
+	});
+	const asText = async () => {
+		take();
+		try {
+			return await response.text();
+		} catch (failure) {
+			throw broken(failure);
+		}
+	};
+	return {
+		stat,
+		stream() {
+			let body;
+			try {
+				take();
+				body = response.body ?? emptyStream();
+			} catch (refusal) {
+				return new ReadableStream({ start(controller) {
+					controller.error(refusal);
+				} });
+			}
+			return reportingFailure(body, broken);
+		},
+		async bytes() {
+			take();
+			try {
+				return new Uint8Array(await response.arrayBuffer());
+			} catch (failure) {
+				throw broken(failure);
+			}
+		},
+		text: asText,
+		async json() {
+			return JSON.parse(await asText());
+		}
+	};
+}
+function emptyStream() {
+	return new ReadableStream({ start(controller) {
+		controller.close();
+	} });
+}
+/**
+* The same bytes, with a break of the response body reported as a `StorageError`. A
+* cancel reaches the response through the reader, which is what cancels the request
+* behind the stream (spec 4.5).
+*/
+function reportingFailure(body, asStorageError) {
+	const reader = body.getReader();
+	return new ReadableStream({
+		async pull(controller) {
+			try {
+				const { done, value } = await reader.read();
+				if (done) controller.close();
+				else controller.enqueue(value);
+			} catch (failure) {
+				controller.error(asStorageError(failure));
+			}
+		},
+		async cancel(reason) {
+			await reader.cancel(reason);
+		}
+	});
+}
+//#endregion
+//#region src/part-reader.ts
+/** Where a buffer starts before the stream has shown whether it fills a part. */
+const initialCapacity = 65536;
+/**
+* A stream read into parts of one size (spec 7.6). A part is known to be the last only
+* once the stream has ended behind it, so a full part looks one chunk ahead; that chunk
+* is the stream's own and becomes the start of the next part.
+*
+* A part handed back through `recycle` lends its buffer to a later one. Spec 7.6 bounds
+* an upload at `partSize × concurrency` of buffers, and a fresh buffer per part would
+* keep the settled ones alive until the collector noticed them.
+*
+* Until a part has filled, the buffer grows by doubling, because ADR 0009 has a body
+* shorter than a part allocate only what it needs. Once one has, the stream is known to
+* go as a multipart upload, and every buffer after it starts at the full part size.
+*/
+var PartReader = class {
+	#reader;
+	#partSize;
+	#signal;
+	#cancelOnAbort = () => {
+		this.#reader.cancel(this.#signal?.reason).catch(() => {});
+	};
+	#free = [];
+	#ahead;
+	#filledOnce = false;
+	constructor(stream, partSize, signal) {
+		this.#reader = stream.getReader();
+		this.#partSize = partSize;
+		this.#signal = signal;
+		signal?.addEventListener("abort", this.#cancelOnAbort, { once: true });
+	}
+	async next() {
+		let bytes = this.#freshBuffer();
+		let filled = 0;
+		while (filled < this.#partSize) {
+			const chunk = this.#ahead ?? await this.#read();
+			this.#ahead = void 0;
+			if (chunk === void 0) return {
+				bytes: bytes.subarray(0, filled),
+				last: true
+			};
+			const taken = Math.min(chunk.byteLength, this.#partSize - filled);
+			if (filled + taken > bytes.byteLength) bytes = this.#grown(bytes, filled + taken);
+			bytes.set(chunk.subarray(0, taken), filled);
+			filled += taken;
+			if (taken < chunk.byteLength) this.#ahead = chunk.subarray(taken);
+		}
+		this.#filledOnce = true;
+		this.#ahead ??= await this.#read();
+		return {
+			bytes,
+			last: this.#ahead === void 0
+		};
+	}
+	/** The part's request settled, so nothing reads its bytes any more. */
+	recycle(part) {
+		if (part.bytes.buffer.byteLength === this.#partSize) this.#free.push(part.bytes.buffer);
+	}
+	/** Spec 4.2 leaves the stream canceled where `put` rejects before reading it to its end. */
+	async cancel(reason) {
+		await this.#reader.cancel(reason).catch(() => {});
+	}
+	release() {
+		this.#signal?.removeEventListener("abort", this.#cancelOnAbort);
+		this.#reader.releaseLock();
+	}
+	#freshBuffer() {
+		const pooled = this.#free.pop();
+		if (pooled !== void 0) return new Uint8Array(pooled);
+		return new Uint8Array(this.#filledOnce ? this.#partSize : Math.min(this.#partSize, initialCapacity));
+	}
+	#grown(bytes, needed) {
+		let capacity = bytes.byteLength;
+		while (capacity < needed) capacity *= 2;
+		const larger = new Uint8Array(Math.min(capacity, this.#partSize));
+		larger.set(bytes);
+		return larger;
+	}
+	async #read() {
+		for (;;) {
+			const { done, value } = await this.#reader.read();
+			this.#signal?.throwIfAborted();
+			if (done) return void 0;
+			if (value.byteLength > 0) return value;
+		}
+	}
+};
+//#endregion
+//#region src/upload.ts
+/** The object's own headers, which a multipart upload sends with the request that starts it. */
+function objectHeaders(write) {
+	return [["content-type", write.contentType], ...write.userMetadata.headers];
+}
+/** Spec 7.6: bytes the adapter holds go as one `PUT`, which it never splits. */
+async function putObject(configuration, write, bytes) {
+	const response = await send(configuration, {
+		method: "PUT",
+		operation: "put",
+		key: write.key,
+		headers: objectHeaders(write),
+		body: bytes,
+		signal: write.signal
+	});
+	await response.body?.cancel();
+	return describeWrite(configuration.bucket, write.key, bytes.byteLength, write.contentType, write.userMetadata.held, response);
+}
+/**
+* Spec 7.6: a stream is read into parts of `partSize`, and one that ends within the first
+* goes as the `PUT` held bytes get.
+*/
+async function uploadStream(configuration, write, stream) {
+	const parts = new PartReader(stream, configuration.partSize, write.signal);
+	try {
+		const first = await parts.next();
+		if (first.last) return await putObject(configuration, write, first.bytes);
+		return await multipartUpload(configuration, write, parts, first);
+	} catch (failure) {
+		await parts.cancel(failure);
+		throw failure;
+	} finally {
+		parts.release();
+	}
+}
+const s3Namespace = "http://s3.amazonaws.com/doc/2006-03-01/";
+/** The provider's limit on both sides, which ADR 0016 leaves no option to lift. */
+const maxParts = 1e4;
+/**
+* Spec 7.6: a multipart upload aborts itself once it failed, after the parts in flight
+* and the source stream were canceled.
+*/
+async function multipartUpload(configuration, write, parts, first) {
+	const uploadId = await createUpload(configuration, write);
+	let sent;
+	try {
+		sent = await sendParts(configuration, write, uploadId, parts, first);
+	} catch (failure) {
+		await parts.cancel(failure);
+		await abortUpload(configuration, write, uploadId);
+		throw failure;
+	}
+	return await completeUpload(configuration, write, uploadId, sent);
+}
+/**
+* Spec 7.6: `concurrency` parts in flight, and the next part read only once one of them
+* settled, so the part buffers never outnumber the parts in flight. The first failure
+* stops the parts still in flight, and is what the upload rejects with once they settled.
+*/
+async function sendParts(configuration, write, uploadId, parts, first) {
+	const stop = new AbortController();
+	const partWrite = {
+		...write,
+		signal: write.signal === void 0 ? stop.signal : AbortSignal.any([write.signal, stop.signal])
+	};
+	const inFlight = /* @__PURE__ */ new Set();
+	const uploaded = [];
+	let failure;
+	let size = 0;
+	const fail = (reason) => {
+		failure ??= { reason };
+		stop.abort();
+		parts.cancel(reason);
+	};
+	const sendPart = async (number, part) => {
+		try {
+			const etag = await uploadPart(configuration, partWrite, uploadId, number, part);
+			uploaded.push({
+				number,
+				etag
+			});
+		} catch (reason) {
+			fail(reason);
+		} finally {
+			parts.recycle(part);
+		}
+	};
+	try {
+		for (let number = 1, part = first; !stop.signal.aborted; number += 1) {
+			if (number === maxParts && !part.last) throw tooManyParts(configuration, write);
+			const sending = sendPart(number, part);
+			inFlight.add(sending);
+			sending.finally(() => inFlight.delete(sending));
+			size += part.bytes.byteLength;
+			if (part.last) break;
+			while (inFlight.size >= configuration.concurrency) await Promise.race(inFlight);
+			part = await parts.next();
+		}
+	} catch (reason) {
+		fail(reason);
+	}
+	await Promise.all(inFlight);
+	if (failure !== void 0) throw failure.reason;
+	return {
+		uploaded: uploaded.toSorted((one, other) => one.number - other.number),
+		size
+	};
+}
+async function createUpload(configuration, write) {
+	const response = await send(configuration, {
+		method: "POST",
+		operation: "put",
+		key: write.key,
+		query: [["uploads", ""]],
+		headers: objectHeaders(write),
+		signal: write.signal
+	});
+	const subject = "the start of the upload";
+	const uploadId = textOf$1(await readAnswerDocument(answeredRequest(configuration, write, subject), response, "InitiateMultipartUploadResult"), "UploadId");
+	if (uploadId === void 0 || uploadId === "") throw incompleteAnswer(configuration, write, response, subject, "no upload id");
+	return uploadId;
+}
+async function uploadPart(configuration, write, uploadId, number, part) {
+	const response = await send(configuration, {
+		method: "PUT",
+		operation: "put",
+		key: write.key,
+		query: [["partNumber", String(number)], ["uploadId", uploadId]],
+		body: part.bytes,
+		signal: write.signal
+	});
+	await response.body?.cancel();
+	const etag = response.headers.get("etag");
+	if (etag === null || etag === "") throw incompleteAnswer(configuration, write, response, `part ${number}`, "no entity tag");
+	return etag;
+}
+async function completeUpload(configuration, write, uploadId, { uploaded, size }) {
+	let response;
+	let document;
+	try {
+		response = await send(configuration, {
+			method: "POST",
+			operation: "put",
+			key: write.key,
+			query: [["uploadId", uploadId]],
+			headers: [["content-type", "application/xml"]],
+			body: utf8$1.encode(completeDocument(uploaded)),
+			signal: write.signal,
+			repeatWithoutResponse: false
+		});
+		document = await readAnswerDocument(answeredRequest(configuration, write, "the completion of the upload"), response, "CompleteMultipartUploadResult");
+	} catch (failure) {
+		if (!mayHaveCommitted(failure, write.signal)) await abortUpload(configuration, write, uploadId);
+		throw failure;
+	}
+	const etag = textOf$1(document, "ETag");
+	return describeWrite(configuration.bucket, write.key, size, write.contentType, write.userMetadata.held, response, etag === void 0 ? void 0 : unquotedEtag(etag));
+}
+/**
+* Spec 7.7 leaves a completion that received no response unaborted, because an abort
+* could meet a commit still on its way. The same holds for a `200` that broke before its
+* body said how the commit went, since S3 sends that status before it has decided, and
+* for the caller's abort while the completion was out: the request may have arrived.
+* Only the provider's answer that it did not commit is aborted.
+*/
+function mayHaveCommitted(failure, signal) {
+	if (signal?.aborted) return true;
+	return isStorageError(failure) && failure.code === "NetworkError";
+}
+/**
+* Spec 7.6: sent without a signal, because the caller's may be the one that just fired,
+* and never reported, because the failure that led here is what the caller is owed. What
+* a failed abort leaves behind is removed by the lifecycle rule of spec 7.2.
+*/
+async function abortUpload(configuration, write, uploadId) {
+	try {
+		await (await send(configuration, {
+			method: "DELETE",
+			operation: "put",
+			key: write.key,
+			query: [["uploadId", uploadId]]
+		})).body?.cancel();
+	} catch {}
+}
+const utf8$1 = new TextEncoder();
+function completeDocument(uploaded) {
+	const parts = uploaded.map(({ number, etag }) => `<Part><PartNumber>${number}</PartNumber><ETag>${escapeXml(etag)}</ETag></Part>`).join("");
+	return `<?xml version="1.0" encoding="UTF-8"?><CompleteMultipartUpload xmlns="${s3Namespace}">${parts}</CompleteMultipartUpload>`;
+}
+function answeredRequest(configuration, write, subject) {
+	return {
+		bucket: configuration.bucket,
+		operation: "put",
+		key: write.key,
+		subject
+	};
+}
+/**
+* Spec 7.6: known once the last part the provider takes is full and the stream goes on.
+* ADR 0016 fixes the part size before the first part, so the way past it is a larger one.
+*/
+function tooManyParts(configuration, write) {
+	return s3Error(configuration.bucket, {
+		code: "InvalidRequest",
+		message: `The stream needs more than ${maxParts} parts of the configured \`partSize\` of ${configuration.partSize} bytes; a larger \`multipart.partSize\` carries it`,
+		operation: "put",
+		key: write.key,
+		attempts: 0
+	});
+}
+function incompleteAnswer(configuration, write, response, subject, missing) {
+	return s3Error(configuration.bucket, {
+		code: "ProviderError",
+		message: `The provider answered ${subject} with ${missing}`,
+		operation: "put",
+		key: write.key,
+		attempts: 1,
+		status: response.status,
+		requestId: response.headers.get("x-amz-request-id") ?? void 0
+	});
+}
+//#endregion
+//#region src/index.ts
+function s3Storage(options) {
+	return new SimpleStorageServiceStorage(options);
+}
+/** Spec 7.1, in the order `capabilityNames` of spec 4.9 lists the names. */
+const s3Capabilities = Object.freeze([
+	"presignedUrls",
+	"rangeReads",
+	"userMetadata"
+]);
+const utf8 = new TextEncoder();
+var SimpleStorageServiceStorage = class {
+	provider = "s3";
+	bucket;
+	capabilities = s3Capabilities;
+	#configuration;
+	constructor(options) {
+		this.#configuration = readConfiguration(options);
+		this.bucket = this.#configuration.bucket;
+	}
+	async put(key, body, options) {
+		try {
+			return await this.#put(key, body, options);
+		} catch (failure) {
+			if (isStream(body) && !body.locked) await body.cancel(failure).catch(() => {});
+			throw failure;
+		}
+	}
+	async #put(key, body, options) {
+		requireKey(this.bucket, key, "writable", "put");
+		requireKnownOptions(this.bucket, options, putOptionKeys, "put");
+		const write = {
+			key,
+			userMetadata: userMetadataHeaders(this.bucket, options?.userMetadata, key),
+			contentType: this.#readContentType(options?.contentType),
+			signal: options?.signal
+		};
+		options?.signal?.throwIfAborted();
+		if (isStream(body)) return await uploadStream(this.#configuration, write, body);
+		return await putObject(this.#configuration, write, bytesOf(body));
+	}
+	async get(key, options) {
+		requireKey(this.bucket, key, "addressable", "get");
+		requireKnownOptions(this.bucket, options, getOptionKeys, "get");
+		const range = options?.range;
+		requireRange(this.bucket, range);
+		options?.signal?.throwIfAborted();
+		const response = await send(this.#configuration, {
+			method: "GET",
+			operation: "get",
+			key,
+			headers: range === void 0 ? [] : [["range", rangeHeader(range)]],
+			signal: options?.signal
+		});
+		const stat = describeResponse(this.bucket, key, "get", response);
+		const refusal = range === void 0 || response.status === 206 ? void 0 : wholeAnswerFailure(this.bucket, key, range, stat.size);
+		if (refusal !== void 0) {
+			await response.body?.cancel();
+			throw refusal;
+		}
+		return createStoredObject(this.bucket, stat, response);
+	}
+	async stat(key, options) {
+		return describeResponse(this.bucket, key, "stat", await this.#head(key, "stat", options));
+	}
+	async exists(key, options) {
+		try {
+			await this.#head(key, "exists", options);
+			return true;
+		} catch (failure) {
+			if (isStorageError(failure) && failure.code === "NotFound") return false;
+			throw failure;
+		}
+	}
+	list(options) {
+		return createListing(this.#configuration, options);
+	}
+	async delete(...keys) {
+		return await deleteKeys(this.#configuration, keys, { operation: "delete" });
+	}
+	async deleteAll(prefix, options) {
+		requireKey(this.bucket, prefix, "prefix", "deleteAll");
+		requireKnownOptions(this.bucket, options, operationOptionKeys, "deleteAll");
+		options?.signal?.throwIfAborted();
+		return await deleteBelow(this.#configuration, prefix, options?.signal);
+	}
+	async copy(from, to, options) {
+		this.#requireCopyKeys(from, to, options, "copy");
+		return await copyObject(this.#configuration, from, to, "copy", options?.signal);
+	}
+	/**
+	* Spec 4.10: `copy`, then the source deleted, each failure told as `move`'s. The
+	* destination is described before the source goes, so a failing delete leaves both in
+	* place and a repeated `move` is safe.
+	*/
+	async move(from, to, options) {
+		this.#requireCopyKeys(from, to, options, "move");
+		const written = await copyObject(this.#configuration, from, to, "move", options?.signal);
+		await (await send(this.#configuration, {
+			method: "DELETE",
+			operation: "move",
+			key: from,
+			signal: options?.signal
+		})).body?.cancel();
+		return written;
+	}
+	async presignGet(key, options) {
+		return await presignGet(this.#configuration, key, options);
+	}
+	async presignPut(key, options) {
+		return await presignPut(this.#configuration, key, options);
+	}
+	async #head(key, operation, options) {
+		requireKey(this.bucket, key, "addressable", operation);
+		requireKnownOptions(this.bucket, options, operationOptionKeys, operation);
+		options?.signal?.throwIfAborted();
+		return await send(this.#configuration, {
+			method: "HEAD",
+			operation,
+			key,
+			signal: options?.signal
+		});
+	}
+	/**
+	* Spec 4.8 checks both keys before acting on either, and spec 7.8 has a copy of a key
+	* onto itself stop before it leaves the process; a `move` onto itself would otherwise
+	* delete the one object it named.
+	*/
+	#requireCopyKeys(from, to, options, operation) {
+		requireKey(this.bucket, from, "addressable", operation);
+		requireKey(this.bucket, to, "writable", operation);
+		requireKnownOptions(this.bucket, options, operationOptionKeys, operation);
+		if (from !== to) return;
+		throw s3Error(this.bucket, {
+			code: "InvalidRequest",
+			message: "A copy names one key as its source and another as its destination",
+			operation,
+			key: from,
+			attempts: 0
+		});
+	}
+	#readContentType(contentType) {
+		if (contentType === void 0) return defaultContentType;
+		if (typeof contentType !== "string" || contentType === "") throw optionError$1(this.bucket, "contentType", "takes a non-empty string", "put");
+		return contentType;
+	}
+};
+/** Spec 4.2: a string travels as its UTF-8 bytes. */
+function bytesOf(body) {
+	return typeof body === "string" ? utf8.encode(body) : heldBytes(body);
+}
+/**
+* The same bytes as a view Web Crypto takes: `BufferSource` rules out a view on a
+* `SharedArrayBuffer`, which is the one body copied rather than hashed and sent where it
+* lies. ADR 0009 already spends the memory of holding a body whole, and a copy of every
+* one of them would spend it twice.
+*/
+function heldBytes(body) {
+	const { buffer } = body;
+	if (buffer instanceof ArrayBuffer) return new Uint8Array(buffer, body.byteOffset, body.byteLength);
+	return new Uint8Array(body);
+}
+function isStream(body) {
+	return typeof body !== "string" && !(body instanceof Uint8Array);
+}
+//#endregion
+export { fromEnv, s3Storage };