@btravstack/storage 0.37.0 → 0.39.0

package/dist/s3.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_storage = require("./storage-DlAQXJ1t.cjs");
+const require_options = require("./options-BhML_i5p.cjs");
 let _btravstack_di = require("@btravstack/di");
 let unthrown = require("unthrown");
 let _aws_sdk_client_s3 = require("@aws-sdk/client-s3");
@@ -30,41 +30,90 @@ const s3Schema = _btravstack_config.Config.object({
 * close — so the client rides the graph and the scope closing destroys it.
 */
 var S3Connection = class extends (0, _btravstack_di.Port)("S3Connection") {};
-const unavailable = (operation, key, cause) => new require_storage.StorageUnavailable({
+const unavailable = (operation, key, cause) => new require_options.StorageUnavailable({
 	operation,
 	key,
 	reason: cause instanceof Error ? cause.message : String(cause)
 });
 /** S3's answer to `If-None-Match: *` on a key that is held: HTTP 412. */
 const isPreconditionFailed = (cause) => cause?.$metadata?.httpStatusCode === 412;
+const isChecksumMismatch = (cause) => cause instanceof Error && (cause.name === "BadDigest" || cause.name === "InvalidDigest");
 /** A missing key is S3's `NoSuchKey`, which is a different fact from "the store is down". */
 const isMissing = (cause) => cause instanceof Error && (cause.name === "NoSuchKey" || cause.name === "NotFound");
+/** SSE-KMS parameters when a key is named; none otherwise, so the bucket's default applies. */
+const encryption = (options) => options.kmsKeyId === void 0 ? {} : {
+	ServerSideEncryption: "aws:kms",
+	SSEKMSKeyId: options.kmsKeyId
+};
+/** S3 reports and takes checksums in base64; the port speaks hex. */
+const hexToBase64 = (hex) => Buffer.from(hex, "hex").toString("base64");
+const base64ToHex = (base64) => Buffer.from(base64, "base64").toString("hex");
 /**
 * The adapter's service over a client and a bucket. A delete of a key nobody
 * stored answers `Ok`, which is S3's own idempotent behaviour rather than a
 * fiction layered over it.
 */
 const s3StorageBackend = (client, bucket) => ({
-	put: (key, bytes, options) => (0, unthrown.fromPromise)(client.send(new _aws_sdk_client_s3.PutObjectCommand({
-		Bucket: bucket,
-		Key: key,
-		Body: bytes,
-		ContentType: options.contentType
-	})), (cause) => unavailable("put", key, cause)).map(() => void 0),
-	putIfAbsent: (key, bytes, options) => (0, unthrown.fromPromise)(client.send(new _aws_sdk_client_s3.PutObjectCommand({
-		Bucket: bucket,
-		Key: key,
-		Body: bytes,
-		ContentType: options.contentType,
-		IfNoneMatch: "*"
-	})), (cause) => isPreconditionFailed(cause) ? new require_storage.ObjectExists({ key }) : unavailable("putIfAbsent", key, cause)).map(() => void 0),
+	put: (key, bytes, options) => {
+		const validated = require_options.validateOptions(key, options);
+		if (!validated.isOk()) return validated.toAsync();
+		return (0, unthrown.fromPromise)(client.send(new _aws_sdk_client_s3.PutObjectCommand({
+			Bucket: bucket,
+			Key: key,
+			Body: bytes,
+			ContentType: options.contentType,
+			Metadata: { ...options.metadata },
+			...options.sha256 === void 0 ? {} : { ChecksumSHA256: hexToBase64(options.sha256) },
+			...encryption(options)
+		})), (cause) => isChecksumMismatch(cause) ? new require_options.ChecksumMismatch({ key }) : unavailable("put", key, cause)).map(() => void 0);
+	},
+	putIfAbsent: (key, bytes, options) => {
+		const validated = require_options.validateOptions(key, options);
+		if (!validated.isOk()) return validated.toAsync();
+		return (0, unthrown.fromPromise)(client.send(new _aws_sdk_client_s3.PutObjectCommand({
+			Bucket: bucket,
+			Key: key,
+			Body: bytes,
+			ContentType: options.contentType,
+			IfNoneMatch: "*",
+			Metadata: { ...options.metadata },
+			...options.sha256 === void 0 ? {} : { ChecksumSHA256: hexToBase64(options.sha256) },
+			...encryption(options)
+		})), (cause) => isChecksumMismatch(cause) ? new require_options.ChecksumMismatch({ key }) : isPreconditionFailed(cause) ? new require_options.ObjectExists({ key }) : unavailable("putIfAbsent", key, cause)).map(() => void 0);
+	},
 	get: (key) => (0, unthrown.fromPromise)(client.send(new _aws_sdk_client_s3.GetObjectCommand({
 		Bucket: bucket,
 		Key: key
 	})).then(async (response) => ({
 		bytes: await response.Body.transformToByteArray(),
 		contentType: response.ContentType ?? "application/octet-stream"
-	})), (cause) => isMissing(cause) ? new require_storage.ObjectNotFound({ key }) : unavailable("get", key, cause)),
+	})), (cause) => isMissing(cause) ? new require_options.ObjectNotFound({ key }) : unavailable("get", key, cause)),
+	copy: (from, to, options) => {
+		const validated = require_options.validateOptions(to, options);
+		if (!validated.isOk()) return validated.toAsync();
+		return (0, unthrown.fromPromise)((async () => client.send(new _aws_sdk_client_s3.CopyObjectCommand({
+			Bucket: bucket,
+			Key: to,
+			CopySource: `${bucket}/${from.split("/").map(encodeURIComponent).join("/")}`,
+			MetadataDirective: "REPLACE",
+			TaggingDirective: "REPLACE",
+			AnnotationDirective: "EXCLUDE",
+			ContentType: options.contentType,
+			Metadata: { ...options.metadata },
+			...options.checksum === void 0 ? {} : { ChecksumAlgorithm: "SHA256" },
+			...encryption(options)
+		})))(), (cause) => isMissing(cause) ? new require_options.ObjectNotFound({ key: from }) : unavailable("copy", from, cause)).map(() => void 0);
+	},
+	head: (key) => (0, unthrown.fromPromise)(client.send(new _aws_sdk_client_s3.HeadObjectCommand({
+		Bucket: bucket,
+		Key: key,
+		ChecksumMode: "ENABLED"
+	})).then((response) => ({
+		metadata: { ...response.Metadata },
+		size: response.ContentLength ?? 0,
+		contentType: response.ContentType ?? "application/octet-stream",
+		...response.ChecksumSHA256 === void 0 || response.ChecksumType === "COMPOSITE" || !/^[A-Za-z0-9+/]{43}=$/.test(response.ChecksumSHA256) ? {} : { sha256: base64ToHex(response.ChecksumSHA256) }
+	})), (cause) => isMissing(cause) ? new require_options.ObjectNotFound({ key }) : unavailable("head", key, cause)),
 	delete: (key) => (0, unthrown.fromPromise)(client.send(new _aws_sdk_client_s3.DeleteObjectCommand({
 		Bucket: bucket,
 		Key: key
@@ -73,15 +122,26 @@ const s3StorageBackend = (client, bucket) => ({
 		Bucket: bucket,
 		Key: key
 	}), { expiresIn: Math.ceil(options.ttlMs / 1e3) }), (cause) => unavailable("presignedUrl", key, cause)),
-	presignedUpload: (key, options) => (0, unthrown.fromPromise)((0, _aws_sdk_s3_request_presigner.getSignedUrl)(client, new _aws_sdk_client_s3.PutObjectCommand({
-		Bucket: bucket,
-		Key: key,
-		ContentType: options.contentType,
-		ContentLength: options.contentLength
-	}), {
-		expiresIn: Math.ceil(options.ttlMs / 1e3),
-		signableHeaders: /* @__PURE__ */ new Set(["content-type"])
-	}), (cause) => unavailable("presignedUpload", key, cause))
+	presignedUpload: (key, options) => {
+		const command = new _aws_sdk_client_s3.PutObjectCommand({
+			Bucket: bucket,
+			Key: key,
+			ContentType: options.contentType,
+			ContentLength: options.contentLength,
+			...encryption(options),
+			...options.sha256 === void 0 ? {} : { ChecksumSHA256: hexToBase64(options.sha256) }
+		});
+		const expiresIn = Math.ceil(options.ttlMs / 1e3);
+		return require_options.validateOptions(key, options).toAsync().flatMap(() => (0, unthrown.fromPromise)((0, _aws_sdk_s3_request_presigner.getSignedUrl)(client, command, {
+			expiresIn,
+			signableHeaders: /* @__PURE__ */ new Set(["content-type"]),
+			unhoistableHeaders: /* @__PURE__ */ new Set([
+				"x-amz-checksum-sha256",
+				"x-amz-server-side-encryption",
+				"x-amz-server-side-encryption-aws-kms-key-id"
+			])
+		}), (cause) => unavailable("presignedUpload", key, cause)));
+	}
 });
 /**
 * The S3 adapter: one client, built with the scope and destroyed with it, and
@@ -111,12 +171,12 @@ const s3Storage = () => (0, _btravstack_di.Module)("S3Storage")({
 				client.destroy();
 			}
 		}),
-		(0, _btravstack_di.Provider)(require_storage.StorageBackend)({
+		(0, _btravstack_di.Provider)(require_options.StorageBackend)({
 			inject: { connection: S3Connection },
 			sync: ({ connection }) => s3StorageBackend(connection.client, connection.bucket)
 		})
 	],
-	exports: [require_storage.StorageBackend]
+	exports: [require_options.StorageBackend]
 });
 //#endregion
 exports.s3Storage = s3Storage;

package/dist/s3.d.cts

@@ -1,4 +1,4 @@
-import { a as StorageBackend, o as StorageService } from "./storage-uSBWFyB2.cjs";
+import { l as StorageBackend, u as StorageService } from "./storage-CfN3KqWm.cjs";
 import { Module, Scope } from "@btravstack/di";
 import { S3Client } from "@aws-sdk/client-s3";
 import { ConfigInvalid, EnvReading } from "@btravstack/config";

package/dist/s3.d.mts

@@ -1,4 +1,4 @@
-import { a as StorageBackend, o as StorageService } from "./storage-uSBWFyB2.mjs";
+import { l as StorageBackend, u as StorageService } from "./storage-CfN3KqWm.mjs";
 import { Module, Scope } from "@btravstack/di";
 import { S3Client } from "@aws-sdk/client-s3";
 import { ConfigInvalid, EnvReading } from "@btravstack/config";

package/dist/s3.mjs

@@ -1,7 +1,7 @@
-import { a as StorageBackend, n as ObjectNotFound, o as StorageUnavailable, t as ObjectExists } from "./storage-BmbyYPIE.mjs";
+import { a as ObjectNotFound, c as StorageBackend, i as ObjectExists, l as StorageUnavailable, n as ChecksumMismatch, t as validateOptions } from "./options-DYPXkWb9.mjs";
 import { Module, Port, Provider } from "@btravstack/di";
 import { Ok, fromPromise } from "unthrown";
-import { DeleteObjectCommand, GetObjectCommand, PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
+import { CopyObjectCommand, DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
 import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
 import { Config, Env } from "@btravstack/config";
 //#region src/s3.ts
@@ -36,27 +36,50 @@ const unavailable = (operation, key, cause) => new StorageUnavailable({
 });
 /** S3's answer to `If-None-Match: *` on a key that is held: HTTP 412. */
 const isPreconditionFailed = (cause) => cause?.$metadata?.httpStatusCode === 412;
+const isChecksumMismatch = (cause) => cause instanceof Error && (cause.name === "BadDigest" || cause.name === "InvalidDigest");
 /** A missing key is S3's `NoSuchKey`, which is a different fact from "the store is down". */
 const isMissing = (cause) => cause instanceof Error && (cause.name === "NoSuchKey" || cause.name === "NotFound");
+/** SSE-KMS parameters when a key is named; none otherwise, so the bucket's default applies. */
+const encryption = (options) => options.kmsKeyId === void 0 ? {} : {
+	ServerSideEncryption: "aws:kms",
+	SSEKMSKeyId: options.kmsKeyId
+};
+/** S3 reports and takes checksums in base64; the port speaks hex. */
+const hexToBase64 = (hex) => Buffer.from(hex, "hex").toString("base64");
+const base64ToHex = (base64) => Buffer.from(base64, "base64").toString("hex");
 /**
 * The adapter's service over a client and a bucket. A delete of a key nobody
 * stored answers `Ok`, which is S3's own idempotent behaviour rather than a
 * fiction layered over it.
 */
 const s3StorageBackend = (client, bucket) => ({
-	put: (key, bytes, options) => fromPromise(client.send(new PutObjectCommand({
-		Bucket: bucket,
-		Key: key,
-		Body: bytes,
-		ContentType: options.contentType
-	})), (cause) => unavailable("put", key, cause)).map(() => void 0),
-	putIfAbsent: (key, bytes, options) => fromPromise(client.send(new PutObjectCommand({
-		Bucket: bucket,
-		Key: key,
-		Body: bytes,
-		ContentType: options.contentType,
-		IfNoneMatch: "*"
-	})), (cause) => isPreconditionFailed(cause) ? new ObjectExists({ key }) : unavailable("putIfAbsent", key, cause)).map(() => void 0),
+	put: (key, bytes, options) => {
+		const validated = validateOptions(key, options);
+		if (!validated.isOk()) return validated.toAsync();
+		return fromPromise(client.send(new PutObjectCommand({
+			Bucket: bucket,
+			Key: key,
+			Body: bytes,
+			ContentType: options.contentType,
+			Metadata: { ...options.metadata },
+			...options.sha256 === void 0 ? {} : { ChecksumSHA256: hexToBase64(options.sha256) },
+			...encryption(options)
+		})), (cause) => isChecksumMismatch(cause) ? new ChecksumMismatch({ key }) : unavailable("put", key, cause)).map(() => void 0);
+	},
+	putIfAbsent: (key, bytes, options) => {
+		const validated = validateOptions(key, options);
+		if (!validated.isOk()) return validated.toAsync();
+		return fromPromise(client.send(new PutObjectCommand({
+			Bucket: bucket,
+			Key: key,
+			Body: bytes,
+			ContentType: options.contentType,
+			IfNoneMatch: "*",
+			Metadata: { ...options.metadata },
+			...options.sha256 === void 0 ? {} : { ChecksumSHA256: hexToBase64(options.sha256) },
+			...encryption(options)
+		})), (cause) => isChecksumMismatch(cause) ? new ChecksumMismatch({ key }) : isPreconditionFailed(cause) ? new ObjectExists({ key }) : unavailable("putIfAbsent", key, cause)).map(() => void 0);
+	},
 	get: (key) => fromPromise(client.send(new GetObjectCommand({
 		Bucket: bucket,
 		Key: key
@@ -64,6 +87,32 @@ const s3StorageBackend = (client, bucket) => ({
 		bytes: await response.Body.transformToByteArray(),
 		contentType: response.ContentType ?? "application/octet-stream"
 	})), (cause) => isMissing(cause) ? new ObjectNotFound({ key }) : unavailable("get", key, cause)),
+	copy: (from, to, options) => {
+		const validated = validateOptions(to, options);
+		if (!validated.isOk()) return validated.toAsync();
+		return fromPromise((async () => client.send(new CopyObjectCommand({
+			Bucket: bucket,
+			Key: to,
+			CopySource: `${bucket}/${from.split("/").map(encodeURIComponent).join("/")}`,
+			MetadataDirective: "REPLACE",
+			TaggingDirective: "REPLACE",
+			AnnotationDirective: "EXCLUDE",
+			ContentType: options.contentType,
+			Metadata: { ...options.metadata },
+			...options.checksum === void 0 ? {} : { ChecksumAlgorithm: "SHA256" },
+			...encryption(options)
+		})))(), (cause) => isMissing(cause) ? new ObjectNotFound({ key: from }) : unavailable("copy", from, cause)).map(() => void 0);
+	},
+	head: (key) => fromPromise(client.send(new HeadObjectCommand({
+		Bucket: bucket,
+		Key: key,
+		ChecksumMode: "ENABLED"
+	})).then((response) => ({
+		metadata: { ...response.Metadata },
+		size: response.ContentLength ?? 0,
+		contentType: response.ContentType ?? "application/octet-stream",
+		...response.ChecksumSHA256 === void 0 || response.ChecksumType === "COMPOSITE" || !/^[A-Za-z0-9+/]{43}=$/.test(response.ChecksumSHA256) ? {} : { sha256: base64ToHex(response.ChecksumSHA256) }
+	})), (cause) => isMissing(cause) ? new ObjectNotFound({ key }) : unavailable("head", key, cause)),
 	delete: (key) => fromPromise(client.send(new DeleteObjectCommand({
 		Bucket: bucket,
 		Key: key
@@ -72,15 +121,26 @@ const s3StorageBackend = (client, bucket) => ({
 		Bucket: bucket,
 		Key: key
 	}), { expiresIn: Math.ceil(options.ttlMs / 1e3) }), (cause) => unavailable("presignedUrl", key, cause)),
-	presignedUpload: (key, options) => fromPromise(getSignedUrl(client, new PutObjectCommand({
-		Bucket: bucket,
-		Key: key,
-		ContentType: options.contentType,
-		ContentLength: options.contentLength
-	}), {
-		expiresIn: Math.ceil(options.ttlMs / 1e3),
-		signableHeaders: /* @__PURE__ */ new Set(["content-type"])
-	}), (cause) => unavailable("presignedUpload", key, cause))
+	presignedUpload: (key, options) => {
+		const command = new PutObjectCommand({
+			Bucket: bucket,
+			Key: key,
+			ContentType: options.contentType,
+			ContentLength: options.contentLength,
+			...encryption(options),
+			...options.sha256 === void 0 ? {} : { ChecksumSHA256: hexToBase64(options.sha256) }
+		});
+		const expiresIn = Math.ceil(options.ttlMs / 1e3);
+		return validateOptions(key, options).toAsync().flatMap(() => fromPromise(getSignedUrl(client, command, {
+			expiresIn,
+			signableHeaders: /* @__PURE__ */ new Set(["content-type"]),
+			unhoistableHeaders: /* @__PURE__ */ new Set([
+				"x-amz-checksum-sha256",
+				"x-amz-server-side-encryption",
+				"x-amz-server-side-encryption-aws-kms-key-id"
+			])
+		}), (cause) => unavailable("presignedUpload", key, cause)));
+	}
 });
 /**
 * The S3 adapter: one client, built with the scope and destroyed with it, and

package/dist/storage-CfN3KqWm.d.cts

@@ -0,0 +1,154 @@
+import { AsyncResult } from "unthrown";
+//#region src/storage.d.ts
+/** One stored object: its bytes and what they are. */
+type StoredObject = {
+  readonly bytes: Uint8Array;
+  readonly contentType: string;
+};
+declare const ObjectNotFound_base: import("unthrown").TaggedErrorConstructor<"ObjectNotFound">;
+/** The key is not there. Only `get`, `head` and `copy` (its source) answer it — see `delete` and `presignedUrl` below. */
+declare class ObjectNotFound extends ObjectNotFound_base<{
+  readonly key: string;
+}> {}
+declare const ObjectExists_base: import("unthrown").TaggedErrorConstructor<"ObjectExists">;
+/** An object already holds the key. Only `putIfAbsent` answers it. */
+declare class ObjectExists extends ObjectExists_base<{
+  readonly key: string;
+}> {}
+declare const InvalidStorageOptions_base: import("unthrown").TaggedErrorConstructor<"InvalidStorageOptions">;
+/** Invalid options are refused before any write or signature is attempted. */
+declare class InvalidStorageOptions extends InvalidStorageOptions_base<{
+  readonly key: string;
+  readonly reason: "invalid_sha256" | "invalid_metadata_key";
+}> {}
+declare const ChecksumMismatch_base: import("unthrown").TaggedErrorConstructor<"ChecksumMismatch">;
+/** The supplied SHA-256 did not match the body; no object was written. */
+declare class ChecksumMismatch extends ChecksumMismatch_base<{
+  readonly key: string;
+}> {}
+declare const StorageUnavailable_base: import("unthrown").TaggedErrorConstructor<"StorageUnavailable">;
+/** The store could not answer — the endpoint is down, the credentials were refused, the bucket is gone. */
+declare class StorageUnavailable extends StorageUnavailable_base<{
+  readonly operation: "put" | "putIfAbsent" | "get" | "copy" | "head" | "delete" | "presignedUrl" | "presignedUpload";
+  readonly key: string;
+  readonly reason: string;
+}> {}
+declare const PresignNotSupported_base: import("unthrown").TaggedErrorConstructor<"PresignNotSupported">;
+/** The adapter cannot mint a time-limited URL, and says so rather than pretending. */
+declare class PresignNotSupported extends PresignNotSupported_base<{
+  readonly key: string;
+}> {}
+/** What the store knows about an object without sending its bytes. */
+type ObjectHead = {
+  readonly size: number;
+  /** An owned snapshot of user metadata; empty when none was written. */
+  readonly metadata: Readonly<Record<string, string>>;
+  readonly contentType: string;
+  /** Lowercase hex of a full-object SHA-256; absent when the store holds none. Composite multipart checksums are excluded. */
+  readonly sha256?: string;
+};
+/**
+ * Written with `kmsKeyId`, an object is encrypted at rest with that KMS key
+ * (SSE-KMS); without it, the store's own default applies.
+ */
+type WriteOptions = {
+  readonly contentType: string;
+  readonly kmsKeyId?: string;
+  /** Lowercase, 64-character hex. The store verifies the body before publishing it. */
+  readonly sha256?: string;
+  /** Lowercase ASCII HTTP-token keys, without `x-amz-meta-`. No normalization; uppercase keys (and thus case collisions) are refused. The caller respects S3's 2 KB UTF-8 key/value limit. */
+  readonly metadata?: Readonly<Record<string, string>>;
+  readonly checksum?: never;
+};
+/** A destination description and optional server-computed checksum; no write digest is accepted. */
+type CopyOptions = {
+  readonly contentType: string;
+  readonly kmsKeyId?: string;
+  readonly metadata?: Readonly<Record<string, string>>;
+  readonly checksum?: "sha256";
+  readonly sha256?: never;
+};
+type StorageService = {
+  readonly put: (key: string, bytes: Uint8Array, options: WriteOptions) => AsyncResult<void, InvalidStorageOptions | ChecksumMismatch | StorageUnavailable>;
+  /** Writes the object only if no object holds the key: the first writer wins, atomically, in the store. */
+  readonly putIfAbsent: (key: string, bytes: Uint8Array, options: WriteOptions) => AsyncResult<void, ObjectExists | InvalidStorageOptions | ChecksumMismatch | StorageUnavailable>;
+  readonly get: (key: string) => AsyncResult<StoredObject, ObjectNotFound | StorageUnavailable>;
+  /**
+   * Copies `from` to `to` inside the store: no bytes pass through this process.
+   * The copy replaces metadata (empty when omitted) and `contentType`, and, with
+   * `kmsKeyId`, is encrypted with that key. An existing `to` is overwritten.
+   */
+  readonly copy: (from: string, to: string, options: CopyOptions) => AsyncResult<void, ObjectNotFound | InvalidStorageOptions | StorageUnavailable>;
+  /**
+   * Size, type and checksum of an object, without reading it. `sha256` is
+   * present only if the store holds one: S3 keeps it for an object written with
+   * a SHA-256 checksum (write/presign `sha256`, or copy `checksum`), and
+   * reports it base64-encoded, which the adapter converts to hex.
+   */
+  readonly head: (key: string) => AsyncResult<ObjectHead, ObjectNotFound | StorageUnavailable>;
+  /** Deleting a key nobody stored is `Ok`: delete is idempotent, which is S3's own behaviour rather than a fiction over it. */
+  readonly delete: (key: string) => AsyncResult<void, StorageUnavailable>;
+  /**
+   * A URL that reads the object for `ttlMs`, without the caller holding
+   * credentials.
+   *
+   * There is **no `ObjectNotFound` arm**: presigning is a signature computation
+   * that asks the store nothing, so a URL for an absent key is minted happily
+   * and 404s when followed. Checking would cost a HEAD per call.
+   */
+  readonly presignedUrl: (key: string, options: {
+    readonly ttlMs: number;
+  }) => AsyncResult<string, PresignNotSupported | StorageUnavailable>;
+  /**
+   * A URL that writes the object for `ttlMs`, without the caller holding
+   * credentials — so the bytes go from the client to the store and never
+   * through this process.
+   *
+   * **`contentType` and `contentLength` are signed, not advisory.** They are
+   * part of the signature, so a client sending different ones is refused by the
+   * store. The same URL can write the key repeatedly until expiry, replacing
+   * the previous object with different bytes of that size and type. Neither
+   * signed header proves the bytes. `contentLength` is required — an unsigned
+   * length would allow an unbounded single write, and there is no ceiling a
+   * presigned PUT can express other than the exact number.
+   *
+   * **`sha256` (lowercase hex, 64 characters) is optional.** When given, the
+   * checksum header is signed too, so the store refuses any body that does not
+   * hash to it, and keeps it for `head`. The client must send the same value as
+   * `x-amz-checksum-sha256` (base64 of the digest).
+   *
+   * With `kmsKeyId`, both `x-amz-server-side-encryption: aws:kms` and
+   * `x-amz-server-side-encryption-aws-kms-key-id` are mandatory signed headers.
+   * The client sends the exact key id used here. Omitting or changing either
+   * breaks the signature. Malformed `sha256` returns `InvalidStorageOptions`.
+   *
+   * The application still decides every input: whether this caller may write
+   * this key, how long the URL lives, and what size it is willing to accept.
+   * The adapter computes a signature over that decision and nothing more.
+   */
+  readonly presignedUpload: (key: string, options: {
+    readonly ttlMs: number;
+    readonly contentType: string;
+    readonly contentLength: number;
+    readonly sha256?: string;
+    readonly kmsKeyId?: string;
+  }) => AsyncResult<string, PresignNotSupported | InvalidStorageOptions | StorageUnavailable>;
+};
+declare const Storage_base: import("@btravstack/di").PortClass<"Storage">;
+/**
+ * The port an application depends on.
+ *
+ * Keys are plain strings the caller composes, tenant included: a store is an
+ * application service, and the framework has no concept of a tenant to put in a
+ * slot.
+ *
+ * **Bytes, not streams.** An object here is a document. Streaming would change
+ * every signature, adapter and test to serve a case that wants a different
+ * design anyway — a stated non-goal, not an oversight.
+ */
+declare class Storage extends Storage_base<StorageService> {}
+declare const StorageBackend_base: import("@btravstack/di").PortClass<"StorageBackend">;
+/** The port every adapter provides, and the one an application never depends on. */
+declare class StorageBackend extends StorageBackend_base<StorageService> {}
+//#endregion
+export { ObjectHead as a, Storage as c, StorageUnavailable as d, StoredObject as f, ObjectExists as i, StorageBackend as l, CopyOptions as n, ObjectNotFound as o, WriteOptions as p, InvalidStorageOptions as r, PresignNotSupported as s, ChecksumMismatch as t, StorageService as u };

package/dist/storage-CfN3KqWm.d.mts

@@ -0,0 +1,154 @@
+import { AsyncResult } from "unthrown";
+//#region src/storage.d.ts
+/** One stored object: its bytes and what they are. */
+type StoredObject = {
+  readonly bytes: Uint8Array;
+  readonly contentType: string;
+};
+declare const ObjectNotFound_base: import("unthrown").TaggedErrorConstructor<"ObjectNotFound">;
+/** The key is not there. Only `get`, `head` and `copy` (its source) answer it — see `delete` and `presignedUrl` below. */
+declare class ObjectNotFound extends ObjectNotFound_base<{
+  readonly key: string;
+}> {}
+declare const ObjectExists_base: import("unthrown").TaggedErrorConstructor<"ObjectExists">;
+/** An object already holds the key. Only `putIfAbsent` answers it. */
+declare class ObjectExists extends ObjectExists_base<{
+  readonly key: string;
+}> {}
+declare const InvalidStorageOptions_base: import("unthrown").TaggedErrorConstructor<"InvalidStorageOptions">;
+/** Invalid options are refused before any write or signature is attempted. */
+declare class InvalidStorageOptions extends InvalidStorageOptions_base<{
+  readonly key: string;
+  readonly reason: "invalid_sha256" | "invalid_metadata_key";
+}> {}
+declare const ChecksumMismatch_base: import("unthrown").TaggedErrorConstructor<"ChecksumMismatch">;
+/** The supplied SHA-256 did not match the body; no object was written. */
+declare class ChecksumMismatch extends ChecksumMismatch_base<{
+  readonly key: string;
+}> {}
+declare const StorageUnavailable_base: import("unthrown").TaggedErrorConstructor<"StorageUnavailable">;
+/** The store could not answer — the endpoint is down, the credentials were refused, the bucket is gone. */
+declare class StorageUnavailable extends StorageUnavailable_base<{
+  readonly operation: "put" | "putIfAbsent" | "get" | "copy" | "head" | "delete" | "presignedUrl" | "presignedUpload";
+  readonly key: string;
+  readonly reason: string;
+}> {}
+declare const PresignNotSupported_base: import("unthrown").TaggedErrorConstructor<"PresignNotSupported">;
+/** The adapter cannot mint a time-limited URL, and says so rather than pretending. */
+declare class PresignNotSupported extends PresignNotSupported_base<{
+  readonly key: string;
+}> {}
+/** What the store knows about an object without sending its bytes. */
+type ObjectHead = {
+  readonly size: number;
+  /** An owned snapshot of user metadata; empty when none was written. */
+  readonly metadata: Readonly<Record<string, string>>;
+  readonly contentType: string;
+  /** Lowercase hex of a full-object SHA-256; absent when the store holds none. Composite multipart checksums are excluded. */
+  readonly sha256?: string;
+};
+/**
+ * Written with `kmsKeyId`, an object is encrypted at rest with that KMS key
+ * (SSE-KMS); without it, the store's own default applies.
+ */
+type WriteOptions = {
+  readonly contentType: string;
+  readonly kmsKeyId?: string;
+  /** Lowercase, 64-character hex. The store verifies the body before publishing it. */
+  readonly sha256?: string;
+  /** Lowercase ASCII HTTP-token keys, without `x-amz-meta-`. No normalization; uppercase keys (and thus case collisions) are refused. The caller respects S3's 2 KB UTF-8 key/value limit. */
+  readonly metadata?: Readonly<Record<string, string>>;
+  readonly checksum?: never;
+};
+/** A destination description and optional server-computed checksum; no write digest is accepted. */
+type CopyOptions = {
+  readonly contentType: string;
+  readonly kmsKeyId?: string;
+  readonly metadata?: Readonly<Record<string, string>>;
+  readonly checksum?: "sha256";
+  readonly sha256?: never;
+};
+type StorageService = {
+  readonly put: (key: string, bytes: Uint8Array, options: WriteOptions) => AsyncResult<void, InvalidStorageOptions | ChecksumMismatch | StorageUnavailable>;
+  /** Writes the object only if no object holds the key: the first writer wins, atomically, in the store. */
+  readonly putIfAbsent: (key: string, bytes: Uint8Array, options: WriteOptions) => AsyncResult<void, ObjectExists | InvalidStorageOptions | ChecksumMismatch | StorageUnavailable>;
+  readonly get: (key: string) => AsyncResult<StoredObject, ObjectNotFound | StorageUnavailable>;
+  /**
+   * Copies `from` to `to` inside the store: no bytes pass through this process.
+   * The copy replaces metadata (empty when omitted) and `contentType`, and, with
+   * `kmsKeyId`, is encrypted with that key. An existing `to` is overwritten.
+   */
+  readonly copy: (from: string, to: string, options: CopyOptions) => AsyncResult<void, ObjectNotFound | InvalidStorageOptions | StorageUnavailable>;
+  /**
+   * Size, type and checksum of an object, without reading it. `sha256` is
+   * present only if the store holds one: S3 keeps it for an object written with
+   * a SHA-256 checksum (write/presign `sha256`, or copy `checksum`), and
+   * reports it base64-encoded, which the adapter converts to hex.
+   */
+  readonly head: (key: string) => AsyncResult<ObjectHead, ObjectNotFound | StorageUnavailable>;
+  /** Deleting a key nobody stored is `Ok`: delete is idempotent, which is S3's own behaviour rather than a fiction over it. */
+  readonly delete: (key: string) => AsyncResult<void, StorageUnavailable>;
+  /**
+   * A URL that reads the object for `ttlMs`, without the caller holding
+   * credentials.
+   *
+   * There is **no `ObjectNotFound` arm**: presigning is a signature computation
+   * that asks the store nothing, so a URL for an absent key is minted happily
+   * and 404s when followed. Checking would cost a HEAD per call.
+   */
+  readonly presignedUrl: (key: string, options: {
+    readonly ttlMs: number;
+  }) => AsyncResult<string, PresignNotSupported | StorageUnavailable>;
+  /**
+   * A URL that writes the object for `ttlMs`, without the caller holding
+   * credentials — so the bytes go from the client to the store and never
+   * through this process.
+   *
+   * **`contentType` and `contentLength` are signed, not advisory.** They are
+   * part of the signature, so a client sending different ones is refused by the
+   * store. The same URL can write the key repeatedly until expiry, replacing
+   * the previous object with different bytes of that size and type. Neither
+   * signed header proves the bytes. `contentLength` is required — an unsigned
+   * length would allow an unbounded single write, and there is no ceiling a
+   * presigned PUT can express other than the exact number.
+   *
+   * **`sha256` (lowercase hex, 64 characters) is optional.** When given, the
+   * checksum header is signed too, so the store refuses any body that does not
+   * hash to it, and keeps it for `head`. The client must send the same value as
+   * `x-amz-checksum-sha256` (base64 of the digest).
+   *
+   * With `kmsKeyId`, both `x-amz-server-side-encryption: aws:kms` and
+   * `x-amz-server-side-encryption-aws-kms-key-id` are mandatory signed headers.
+   * The client sends the exact key id used here. Omitting or changing either
+   * breaks the signature. Malformed `sha256` returns `InvalidStorageOptions`.
+   *
+   * The application still decides every input: whether this caller may write
+   * this key, how long the URL lives, and what size it is willing to accept.
+   * The adapter computes a signature over that decision and nothing more.
+   */
+  readonly presignedUpload: (key: string, options: {
+    readonly ttlMs: number;
+    readonly contentType: string;
+    readonly contentLength: number;
+    readonly sha256?: string;
+    readonly kmsKeyId?: string;
+  }) => AsyncResult<string, PresignNotSupported | InvalidStorageOptions | StorageUnavailable>;
+};
+declare const Storage_base: import("@btravstack/di").PortClass<"Storage">;
+/**
+ * The port an application depends on.
+ *
+ * Keys are plain strings the caller composes, tenant included: a store is an
+ * application service, and the framework has no concept of a tenant to put in a
+ * slot.
+ *
+ * **Bytes, not streams.** An object here is a document. Streaming would change
+ * every signature, adapter and test to serve a case that wants a different
+ * design anyway — a stated non-goal, not an oversight.
+ */
+declare class Storage extends Storage_base<StorageService> {}
+declare const StorageBackend_base: import("@btravstack/di").PortClass<"StorageBackend">;
+/** The port every adapter provides, and the one an application never depends on. */
+declare class StorageBackend extends StorageBackend_base<StorageService> {}
+//#endregion
+export { ObjectHead as a, Storage as c, StorageUnavailable as d, StoredObject as f, ObjectExists as i, StorageBackend as l, CopyOptions as n, ObjectNotFound as o, WriteOptions as p, InvalidStorageOptions as r, PresignNotSupported as s, ChecksumMismatch as t, StorageService as u };