@btravstack/storage 0.36.0 → 0.38.0

package/README.md

@@ -121,7 +121,7 @@ which is this list's one detailed home.
 ## What it decides, and what it does not
 
 **It decides** that a missing object is an ordinary answer rather than a fault
-(counted `not_found`, logged at `info`), that `delete` is idempotent, that
+(counted `not_found`, logged at `info`), that a held key under `putIfAbsent` is an ordinary answer (`ObjectExists`, counted `exists`), that `delete` is idempotent, that `copy` and `head` never move the bytes through the process, that
 presigning asks the store nothing — and that an adapter which cannot presign
 says so instead of minting a URL that would fail only in production.
 

package/dist/index.cjs

@@ -1,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_storage = require("./storage-QVPXOcO6.cjs");
+const require_storage = require("./storage-EA671z1R.cjs");
+let node_crypto = require("node:crypto");
 let _btravstack_di = require("@btravstack/di");
 let unthrown = require("unthrown");
 let _btravstack_core = require("@btravstack/core");
@@ -11,6 +12,8 @@ let _btravstack_core = require("@btravstack/core");
 * which would be the worst kind of double — one that passes locally and fails in
 * the deployment for a reason no test could have shown.
 *
+* `kmsKeyId` is accepted and ignored: nothing is encrypted at rest here.
+*
 * ponytail: no size limit, so a process storing unbounded objects grows
 * unbounded. The upgrade path is the S3 adapter.
 */
@@ -19,14 +22,42 @@ const memoryStorageBackend = () => {
 	return {
 		put: (key, bytes, options) => {
 			objects.set(key, {
-				bytes,
+				bytes: bytes.slice(),
+				contentType: options.contentType
+			});
+			return (0, unthrown.OkAsync)();
+		},
+		putIfAbsent: (key, bytes, options) => {
+			if (objects.has(key)) return (0, unthrown.ErrAsync)(new require_storage.ObjectExists({ key }));
+			objects.set(key, {
+				bytes: bytes.slice(),
+				contentType: options.contentType
+			});
+			return (0, unthrown.OkAsync)();
+		},
+		copy: (from, to, options) => {
+			const object = objects.get(from);
+			if (object === void 0) return (0, unthrown.ErrAsync)(new require_storage.ObjectNotFound({ key: from }));
+			objects.set(to, {
+				bytes: object.bytes.slice(),
 				contentType: options.contentType
 			});
 			return (0, unthrown.OkAsync)();
 		},
+		head: (key) => {
+			const object = objects.get(key);
+			return object === void 0 ? (0, unthrown.ErrAsync)(new require_storage.ObjectNotFound({ key })) : (0, unthrown.OkAsync)({
+				size: object.bytes.byteLength,
+				contentType: object.contentType,
+				sha256: (0, node_crypto.createHash)("sha256").update(object.bytes).digest("hex")
+			});
+		},
 		get: (key) => {
 			const object = objects.get(key);
-			return object === void 0 ? (0, unthrown.ErrAsync)(new require_storage.ObjectNotFound({ key })) : (0, unthrown.OkAsync)(object);
+			return object === void 0 ? (0, unthrown.ErrAsync)(new require_storage.ObjectNotFound({ key })) : (0, unthrown.OkAsync)({
+				...object,
+				bytes: object.bytes.slice()
+			});
 		},
 		delete: (key) => {
 			objects.delete(key);
@@ -59,17 +90,23 @@ const memoryStorage = () => (0, _btravstack_di.Module)("MemoryStorage")({
 */
 const failed = (failure) => {
 	const cause = failure.tag === "Err" ? failure.error : failure.cause;
-	const ordinary = failure.tag !== "Err" ? void 0 : failure.error._tag === "ObjectNotFound" ? "the object was not there" : failure.error._tag === "PresignNotSupported" ? "this store cannot mint a url" : void 0;
+	const ordinary = failure.tag !== "Err" ? void 0 : failure.error._tag === "ObjectExists" ? {
+		result: "exists",
+		reason: "an object already held the key"
+	} : failure.error._tag === "ObjectNotFound" ? {
+		result: "not_found",
+		reason: "the object was not there"
+	} : failure.error._tag === "PresignNotSupported" ? {
+		result: "not_found",
+		reason: "this store cannot mint a url"
+	} : void 0;
 	return ordinary === void 0 ? {
 		outcome: "error",
 		attributes: { result: "error" },
 		cause
 	} : {
 		outcome: "ok",
-		attributes: {
-			result: "not_found",
-			reason: ordinary
-		}
+		attributes: ordinary
 	};
 };
 /** The KEY is a detail, not a dimension: on the span and the line, never on an instrument. */
@@ -90,7 +127,10 @@ const instrument = (backend, observers) => {
 	const observe = through(observers);
 	return {
 		put: (key, bytes, options) => observe("put", key, () => backend.put(key, bytes, options)),
+		putIfAbsent: (key, bytes, options) => observe("put_if_absent", key, () => backend.putIfAbsent(key, bytes, options)),
 		get: (key) => observe("get", key, () => backend.get(key)),
+		copy: (from, to, options) => observe("copy", from, () => backend.copy(from, to, options)),
+		head: (key) => observe("head", key, () => backend.head(key)),
 		delete: (key) => observe("delete", key, () => backend.delete(key)),
 		presignedUrl: (key, options) => observe("presigned_url", key, () => backend.presignedUrl(key, options)),
 		presignedUpload: (key, options) => observe("presigned_upload", key, () => backend.presignedUpload(key, options))
@@ -139,6 +179,7 @@ const storage = ({ adapter }) => {
 	});
 };
 //#endregion
+exports.ObjectExists = require_storage.ObjectExists;
 exports.ObjectNotFound = require_storage.ObjectNotFound;
 exports.PresignNotSupported = require_storage.PresignNotSupported;
 exports.Storage = require_storage.Storage;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { a as StorageService, i as StorageBackend, n as PresignNotSupported, o as StorageUnavailable, r as Storage, s as StoredObject, t as ObjectNotFound } from "./storage-BLJtJ7KF.cjs";
+import { a as Storage, c as StorageUnavailable, i as PresignNotSupported, l as StoredObject, n as ObjectHead, o as StorageBackend, r as ObjectNotFound, s as StorageService, t as ObjectExists, u as WriteOptions } from "./storage-BavPXZpA.cjs";
 import { Module, Provider } from "@btravstack/di";
 import { HealthChecks } from "@btravstack/core";
 //#region src/memory.d.ts
@@ -9,6 +9,8 @@ import { HealthChecks } from "@btravstack/core";
  * which would be the worst kind of double — one that passes locally and fails in
  * the deployment for a reason no test could have shown.
  *
+ * `kmsKeyId` is accepted and ignored: nothing is encrypted at rest here.
+ *
  * ponytail: no size limit, so a process storing unbounded objects grows
  * unbounded. The upgrade path is the S3 adapter.
  */
@@ -47,4 +49,4 @@ type StorageOptions<E, N> = {
  */
 export declare const storage: <E, N>({ adapter }: StorageOptions<E, N>) => Module<Storage | HealthChecks, E, N>;
 //#endregion
-export { ObjectNotFound, PresignNotSupported, Storage, StorageBackend, type StorageOptions, type StorageService, StorageUnavailable, type StoredObject };
+export { ObjectExists, type ObjectHead, ObjectNotFound, PresignNotSupported, Storage, StorageBackend, type StorageOptions, type StorageService, StorageUnavailable, type StoredObject, type WriteOptions };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as StorageService, i as StorageBackend, n as PresignNotSupported, o as StorageUnavailable, r as Storage, s as StoredObject, t as ObjectNotFound } from "./storage-BLJtJ7KF.mjs";
+import { a as Storage, c as StorageUnavailable, i as PresignNotSupported, l as StoredObject, n as ObjectHead, o as StorageBackend, r as ObjectNotFound, s as StorageService, t as ObjectExists, u as WriteOptions } from "./storage-BavPXZpA.mjs";
 import { Module, Provider } from "@btravstack/di";
 import { HealthChecks } from "@btravstack/core";
 //#region src/memory.d.ts
@@ -9,6 +9,8 @@ import { HealthChecks } from "@btravstack/core";
  * which would be the worst kind of double — one that passes locally and fails in
  * the deployment for a reason no test could have shown.
  *
+ * `kmsKeyId` is accepted and ignored: nothing is encrypted at rest here.
+ *
  * ponytail: no size limit, so a process storing unbounded objects grows
  * unbounded. The upgrade path is the S3 adapter.
  */
@@ -47,4 +49,4 @@ type StorageOptions<E, N> = {
  */
 export declare const storage: <E, N>({ adapter }: StorageOptions<E, N>) => Module<Storage | HealthChecks, E, N>;
 //#endregion
-export { ObjectNotFound, PresignNotSupported, Storage, StorageBackend, type StorageOptions, type StorageService, StorageUnavailable, type StoredObject };
+export { ObjectExists, type ObjectHead, ObjectNotFound, PresignNotSupported, Storage, StorageBackend, type StorageOptions, type StorageService, StorageUnavailable, type StoredObject, type WriteOptions };

package/dist/index.mjs

@@ -1,4 +1,5 @@
-import { a as StorageUnavailable, i as StorageBackend, n as PresignNotSupported, r as Storage, t as ObjectNotFound } from "./storage-CRkwIhac.mjs";
+import { a as StorageBackend, i as Storage, n as ObjectNotFound, o as StorageUnavailable, r as PresignNotSupported, t as ObjectExists } from "./storage-BIKstQ72.mjs";
+import { createHash } from "node:crypto";
 import { Module, Provider } from "@btravstack/di";
 import { Err, ErrAsync, Ok, OkAsync, P } from "unthrown";
 import { HealthCheckFailed, HealthChecks, Observers, noObserverMember, observed } from "@btravstack/core";
@@ -10,6 +11,8 @@ import { HealthCheckFailed, HealthChecks, Observers, noObserverMember, observed
 * which would be the worst kind of double — one that passes locally and fails in
 * the deployment for a reason no test could have shown.
 *
+* `kmsKeyId` is accepted and ignored: nothing is encrypted at rest here.
+*
 * ponytail: no size limit, so a process storing unbounded objects grows
 * unbounded. The upgrade path is the S3 adapter.
 */
@@ -18,14 +21,42 @@ const memoryStorageBackend = () => {
 	return {
 		put: (key, bytes, options) => {
 			objects.set(key, {
-				bytes,
+				bytes: bytes.slice(),
+				contentType: options.contentType
+			});
+			return OkAsync();
+		},
+		putIfAbsent: (key, bytes, options) => {
+			if (objects.has(key)) return ErrAsync(new ObjectExists({ key }));
+			objects.set(key, {
+				bytes: bytes.slice(),
+				contentType: options.contentType
+			});
+			return OkAsync();
+		},
+		copy: (from, to, options) => {
+			const object = objects.get(from);
+			if (object === void 0) return ErrAsync(new ObjectNotFound({ key: from }));
+			objects.set(to, {
+				bytes: object.bytes.slice(),
 				contentType: options.contentType
 			});
 			return OkAsync();
 		},
+		head: (key) => {
+			const object = objects.get(key);
+			return object === void 0 ? ErrAsync(new ObjectNotFound({ key })) : OkAsync({
+				size: object.bytes.byteLength,
+				contentType: object.contentType,
+				sha256: createHash("sha256").update(object.bytes).digest("hex")
+			});
+		},
 		get: (key) => {
 			const object = objects.get(key);
-			return object === void 0 ? ErrAsync(new ObjectNotFound({ key })) : OkAsync(object);
+			return object === void 0 ? ErrAsync(new ObjectNotFound({ key })) : OkAsync({
+				...object,
+				bytes: object.bytes.slice()
+			});
 		},
 		delete: (key) => {
 			objects.delete(key);
@@ -58,17 +89,23 @@ const memoryStorage = () => Module("MemoryStorage")({
 */
 const failed = (failure) => {
 	const cause = failure.tag === "Err" ? failure.error : failure.cause;
-	const ordinary = failure.tag !== "Err" ? void 0 : failure.error._tag === "ObjectNotFound" ? "the object was not there" : failure.error._tag === "PresignNotSupported" ? "this store cannot mint a url" : void 0;
+	const ordinary = failure.tag !== "Err" ? void 0 : failure.error._tag === "ObjectExists" ? {
+		result: "exists",
+		reason: "an object already held the key"
+	} : failure.error._tag === "ObjectNotFound" ? {
+		result: "not_found",
+		reason: "the object was not there"
+	} : failure.error._tag === "PresignNotSupported" ? {
+		result: "not_found",
+		reason: "this store cannot mint a url"
+	} : void 0;
 	return ordinary === void 0 ? {
 		outcome: "error",
 		attributes: { result: "error" },
 		cause
 	} : {
 		outcome: "ok",
-		attributes: {
-			result: "not_found",
-			reason: ordinary
-		}
+		attributes: ordinary
 	};
 };
 /** The KEY is a detail, not a dimension: on the span and the line, never on an instrument. */
@@ -89,7 +126,10 @@ const instrument = (backend, observers) => {
 	const observe = through(observers);
 	return {
 		put: (key, bytes, options) => observe("put", key, () => backend.put(key, bytes, options)),
+		putIfAbsent: (key, bytes, options) => observe("put_if_absent", key, () => backend.putIfAbsent(key, bytes, options)),
 		get: (key) => observe("get", key, () => backend.get(key)),
+		copy: (from, to, options) => observe("copy", from, () => backend.copy(from, to, options)),
+		head: (key) => observe("head", key, () => backend.head(key)),
 		delete: (key) => observe("delete", key, () => backend.delete(key)),
 		presignedUrl: (key, options) => observe("presigned_url", key, () => backend.presignedUrl(key, options)),
 		presignedUpload: (key, options) => observe("presigned_upload", key, () => backend.presignedUpload(key, options))
@@ -138,4 +178,4 @@ const storage = ({ adapter }) => {
 	});
 };
 //#endregion
-export { ObjectNotFound, PresignNotSupported, Storage, StorageBackend, StorageUnavailable, memoryStorage, memoryStorageBackend, memoryStorageProvider, storage };
+export { ObjectExists, ObjectNotFound, PresignNotSupported, Storage, StorageBackend, StorageUnavailable, memoryStorage, memoryStorageBackend, memoryStorageProvider, storage };

package/dist/s3.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_storage = require("./storage-QVPXOcO6.cjs");
+const require_storage = require("./storage-EA671z1R.cjs");
 let _btravstack_di = require("@btravstack/di");
 let unthrown = require("unthrown");
 let _aws_sdk_client_s3 = require("@aws-sdk/client-s3");
@@ -35,8 +35,18 @@ const unavailable = (operation, key, cause) => new require_storage.StorageUnavai
 	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;
 /** 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
@@ -47,8 +57,17 @@ const s3StorageBackend = (client, bucket) => ({
 		Bucket: bucket,
 		Key: key,
 		Body: bytes,
-		ContentType: options.contentType
+		ContentType: options.contentType,
+		...encryption(options)
 	})), (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: "*",
+		...encryption(options)
+	})), (cause) => isPreconditionFailed(cause) ? new require_storage.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
@@ -56,6 +75,25 @@ const s3StorageBackend = (client, bucket) => ({
 		bytes: await response.Body.transformToByteArray(),
 		contentType: response.ContentType ?? "application/octet-stream"
 	})), (cause) => isMissing(cause) ? new require_storage.ObjectNotFound({ key }) : unavailable("get", key, cause)),
+	copy: (from, to, options) => (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,
+		...encryption(options)
+	})))(), (cause) => isMissing(cause) ? new require_storage.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) => ({
+		size: response.ContentLength ?? 0,
+		contentType: response.ContentType ?? "application/octet-stream",
+		...response.ChecksumSHA256 === void 0 || response.ChecksumType === "COMPOSITE" ? {} : { sha256: base64ToHex(response.ChecksumSHA256) }
+	})), (cause) => isMissing(cause) ? new require_storage.ObjectNotFound({ key }) : unavailable("head", key, cause)),
 	delete: (key) => (0, unthrown.fromPromise)(client.send(new _aws_sdk_client_s3.DeleteObjectCommand({
 		Bucket: bucket,
 		Key: key
@@ -68,10 +106,12 @@ const s3StorageBackend = (client, bucket) => ({
 		Bucket: bucket,
 		Key: key,
 		ContentType: options.contentType,
-		ContentLength: options.contentLength
+		ContentLength: options.contentLength,
+		...options.sha256 === void 0 ? {} : { ChecksumSHA256: hexToBase64(options.sha256) }
 	}), {
 		expiresIn: Math.ceil(options.ttlMs / 1e3),
-		signableHeaders: /* @__PURE__ */ new Set(["content-type"])
+		signableHeaders: /* @__PURE__ */ new Set(["content-type"]),
+		...options.sha256 === void 0 ? {} : { unhoistableHeaders: /* @__PURE__ */ new Set(["x-amz-checksum-sha256"]) }
 	}), (cause) => unavailable("presignedUpload", key, cause))
 });
 /**

package/dist/s3.d.cts

@@ -1,4 +1,4 @@
-import { a as StorageService, i as StorageBackend } from "./storage-BLJtJ7KF.cjs";
+import { o as StorageBackend, s as StorageService } from "./storage-BavPXZpA.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 StorageService, i as StorageBackend } from "./storage-BLJtJ7KF.mjs";
+import { o as StorageBackend, s as StorageService } from "./storage-BavPXZpA.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 StorageUnavailable, i as StorageBackend, t as ObjectNotFound } from "./storage-CRkwIhac.mjs";
+import { a as StorageBackend, n as ObjectNotFound, o as StorageUnavailable, t as ObjectExists } from "./storage-BIKstQ72.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
@@ -34,8 +34,18 @@ const unavailable = (operation, key, cause) => new StorageUnavailable({
 	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;
 /** 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
@@ -46,8 +56,17 @@ const s3StorageBackend = (client, bucket) => ({
 		Bucket: bucket,
 		Key: key,
 		Body: bytes,
-		ContentType: options.contentType
+		ContentType: options.contentType,
+		...encryption(options)
 	})), (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: "*",
+		...encryption(options)
+	})), (cause) => isPreconditionFailed(cause) ? new ObjectExists({ key }) : unavailable("putIfAbsent", key, cause)).map(() => void 0),
 	get: (key) => fromPromise(client.send(new GetObjectCommand({
 		Bucket: bucket,
 		Key: key
@@ -55,6 +74,25 @@ 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) => 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,
+		...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) => ({
+		size: response.ContentLength ?? 0,
+		contentType: response.ContentType ?? "application/octet-stream",
+		...response.ChecksumSHA256 === void 0 || response.ChecksumType === "COMPOSITE" ? {} : { 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
@@ -67,10 +105,12 @@ const s3StorageBackend = (client, bucket) => ({
 		Bucket: bucket,
 		Key: key,
 		ContentType: options.contentType,
-		ContentLength: options.contentLength
+		ContentLength: options.contentLength,
+		...options.sha256 === void 0 ? {} : { ChecksumSHA256: hexToBase64(options.sha256) }
 	}), {
 		expiresIn: Math.ceil(options.ttlMs / 1e3),
-		signableHeaders: /* @__PURE__ */ new Set(["content-type"])
+		signableHeaders: /* @__PURE__ */ new Set(["content-type"]),
+		...options.sha256 === void 0 ? {} : { unhoistableHeaders: /* @__PURE__ */ new Set(["x-amz-checksum-sha256"]) }
 	}), (cause) => unavailable("presignedUpload", key, cause))
 });
 /**

package/dist/{storage-CRkwIhac.mjs → storage-BIKstQ72.mjs}

@@ -1,8 +1,10 @@
 import { Port } from "@btravstack/di";
 import { TaggedError } from "unthrown";
 //#region src/storage.ts
-/** The key is not there. Only `get` answers it — see `delete` and `presignedUrl` below. */
+/** The key is not there. Only `get`, `head` and `copy` (its source) answer it — see `delete` and `presignedUrl` below. */
 var ObjectNotFound = class extends TaggedError("ObjectNotFound") {};
+/** An object already holds the key. Only `putIfAbsent` answers it. */
+var ObjectExists = class extends TaggedError("ObjectExists") {};
 /** The store could not answer — the endpoint is down, the credentials were refused, the bucket is gone. */
 var StorageUnavailable = class extends TaggedError("StorageUnavailable") {};
 /** The adapter cannot mint a time-limited URL, and says so rather than pretending. */
@@ -22,4 +24,4 @@ var Storage = class extends Port("Storage") {};
 /** The port every adapter provides, and the one an application never depends on. */
 var StorageBackend = class extends Port("StorageBackend") {};
 //#endregion
-export { StorageUnavailable as a, StorageBackend as i, PresignNotSupported as n, Storage as r, ObjectNotFound as t };
+export { StorageBackend as a, Storage as i, ObjectNotFound as n, StorageUnavailable as o, PresignNotSupported as r, ObjectExists as t };

package/dist/{storage-BLJtJ7KF.d.cts → storage-BavPXZpA.d.cts}

@@ -6,14 +6,19 @@ type StoredObject = {
   readonly contentType: string;
 };
 declare const ObjectNotFound_base: import("unthrown").TaggedErrorConstructor<"ObjectNotFound">;
-/** The key is not there. Only `get` answers it — see `delete` and `presignedUrl` below. */
+/** 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 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" | "get" | "delete" | "presignedUrl" | "presignedUpload";
+  readonly operation: "put" | "putIfAbsent" | "get" | "copy" | "head" | "delete" | "presignedUrl" | "presignedUpload";
   readonly key: string;
   readonly reason: string;
 }> {}
@@ -22,11 +27,39 @@ declare const PresignNotSupported_base: import("unthrown").TaggedErrorConstructo
 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;
+  readonly contentType: string;
+  /** Lowercase hex of the SHA-256 the store holds for the object; absent when none was supplied at write time. */
+  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;
+};
 type StorageService = {
-  readonly put: (key: string, bytes: Uint8Array, options: {
-    readonly contentType: string;
-  }) => AsyncResult<void, StorageUnavailable>;
+  readonly put: (key: string, bytes: Uint8Array, options: WriteOptions) => AsyncResult<void, 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 | StorageUnavailable>;
   readonly get: (key: string) => AsyncResult<StoredObject, ObjectNotFound | StorageUnavailable>;
+  /**
+   * Copies `from` to `to` inside the store: no bytes pass through this process.
+   * The copy takes `contentType` (the source's is replaced) and, with
+   * `kmsKeyId`, is encrypted with that key. An existing `to` is overwritten.
+   */
+  readonly copy: (from: string, to: string, options: WriteOptions) => AsyncResult<void, ObjectNotFound | 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 (such as through `presignedUpload` with `sha256`), 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>;
   /**
@@ -53,6 +86,11 @@ type StorageService = {
    * 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).
+   *
    * 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.
@@ -61,6 +99,7 @@ type StorageService = {
     readonly ttlMs: number;
     readonly contentType: string;
     readonly contentLength: number;
+    readonly sha256?: string;
   }) => AsyncResult<string, PresignNotSupported | StorageUnavailable>;
 };
 declare const Storage_base: import("@btravstack/di").PortClass<"Storage">;
@@ -80,4 +119,4 @@ declare const StorageBackend_base: import("@btravstack/di").PortClass<"StorageBa
 /** The port every adapter provides, and the one an application never depends on. */
 declare class StorageBackend extends StorageBackend_base<StorageService> {}
 //#endregion
-export { StorageService as a, StorageBackend as i, PresignNotSupported as n, StorageUnavailable as o, Storage as r, StoredObject as s, ObjectNotFound as t };
+export { Storage as a, StorageUnavailable as c, PresignNotSupported as i, StoredObject as l, ObjectHead as n, StorageBackend as o, ObjectNotFound as r, StorageService as s, ObjectExists as t, WriteOptions as u };

package/dist/{storage-BLJtJ7KF.d.mts → storage-BavPXZpA.d.mts}

@@ -6,14 +6,19 @@ type StoredObject = {
   readonly contentType: string;
 };
 declare const ObjectNotFound_base: import("unthrown").TaggedErrorConstructor<"ObjectNotFound">;
-/** The key is not there. Only `get` answers it — see `delete` and `presignedUrl` below. */
+/** 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 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" | "get" | "delete" | "presignedUrl" | "presignedUpload";
+  readonly operation: "put" | "putIfAbsent" | "get" | "copy" | "head" | "delete" | "presignedUrl" | "presignedUpload";
   readonly key: string;
   readonly reason: string;
 }> {}
@@ -22,11 +27,39 @@ declare const PresignNotSupported_base: import("unthrown").TaggedErrorConstructo
 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;
+  readonly contentType: string;
+  /** Lowercase hex of the SHA-256 the store holds for the object; absent when none was supplied at write time. */
+  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;
+};
 type StorageService = {
-  readonly put: (key: string, bytes: Uint8Array, options: {
-    readonly contentType: string;
-  }) => AsyncResult<void, StorageUnavailable>;
+  readonly put: (key: string, bytes: Uint8Array, options: WriteOptions) => AsyncResult<void, 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 | StorageUnavailable>;
   readonly get: (key: string) => AsyncResult<StoredObject, ObjectNotFound | StorageUnavailable>;
+  /**
+   * Copies `from` to `to` inside the store: no bytes pass through this process.
+   * The copy takes `contentType` (the source's is replaced) and, with
+   * `kmsKeyId`, is encrypted with that key. An existing `to` is overwritten.
+   */
+  readonly copy: (from: string, to: string, options: WriteOptions) => AsyncResult<void, ObjectNotFound | 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 (such as through `presignedUpload` with `sha256`), 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>;
   /**
@@ -53,6 +86,11 @@ type StorageService = {
    * 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).
+   *
    * 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.
@@ -61,6 +99,7 @@ type StorageService = {
     readonly ttlMs: number;
     readonly contentType: string;
     readonly contentLength: number;
+    readonly sha256?: string;
   }) => AsyncResult<string, PresignNotSupported | StorageUnavailable>;
 };
 declare const Storage_base: import("@btravstack/di").PortClass<"Storage">;
@@ -80,4 +119,4 @@ declare const StorageBackend_base: import("@btravstack/di").PortClass<"StorageBa
 /** The port every adapter provides, and the one an application never depends on. */
 declare class StorageBackend extends StorageBackend_base<StorageService> {}
 //#endregion
-export { StorageService as a, StorageBackend as i, PresignNotSupported as n, StorageUnavailable as o, Storage as r, StoredObject as s, ObjectNotFound as t };
+export { Storage as a, StorageUnavailable as c, PresignNotSupported as i, StoredObject as l, ObjectHead as n, StorageBackend as o, ObjectNotFound as r, StorageService as s, ObjectExists as t, WriteOptions as u };

package/dist/{storage-QVPXOcO6.cjs → storage-EA671z1R.cjs}

@@ -1,8 +1,10 @@
 let _btravstack_di = require("@btravstack/di");
 let unthrown = require("unthrown");
 //#region src/storage.ts
-/** The key is not there. Only `get` answers it — see `delete` and `presignedUrl` below. */
+/** The key is not there. Only `get`, `head` and `copy` (its source) answer it — see `delete` and `presignedUrl` below. */
 var ObjectNotFound = class extends (0, unthrown.TaggedError)("ObjectNotFound") {};
+/** An object already holds the key. Only `putIfAbsent` answers it. */
+var ObjectExists = class extends (0, unthrown.TaggedError)("ObjectExists") {};
 /** The store could not answer — the endpoint is down, the credentials were refused, the bucket is gone. */
 var StorageUnavailable = class extends (0, unthrown.TaggedError)("StorageUnavailable") {};
 /** The adapter cannot mint a time-limited URL, and says so rather than pretending. */
@@ -22,6 +24,12 @@ var Storage = class extends (0, _btravstack_di.Port)("Storage") {};
 /** The port every adapter provides, and the one an application never depends on. */
 var StorageBackend = class extends (0, _btravstack_di.Port)("StorageBackend") {};
 //#endregion
+Object.defineProperty(exports, "ObjectExists", {
+	enumerable: true,
+	get: function() {
+		return ObjectExists;
+	}
+});
 Object.defineProperty(exports, "ObjectNotFound", {
 	enumerable: true,
 	get: function() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/storage",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "A Storage port for @btravstack/core: an in-memory adapter, an S3-compatible adapter with presigned reads, and a composition that spans, counts and logs every operation",
   "keywords": [
     "dependency-injection",
@@ -55,11 +55,11 @@
   "devDependencies": {
     "@aws-sdk/client-s3": "3.1149.0",
     "@aws-sdk/s3-request-presigner": "3.1149.0",
-    "@btravstack/config": "0.36.0",
-    "@btravstack/core": "0.36.0",
-    "@btravstack/di": "0.36.0",
+    "@btravstack/config": "0.38.0",
+    "@btravstack/core": "0.38.0",
+    "@btravstack/di": "0.38.0",
     "@btravstack/internal-test-infra": "0.0.0",
-    "@btravstack/observability": "0.36.0",
+    "@btravstack/observability": "0.38.0",
     "@btravstack/tsconfig": "0.4.0",
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/sdk-metrics": "2.12.0",
@@ -76,9 +76,9 @@
   "peerDependencies": {
     "@aws-sdk/client-s3": "^3.1000.0",
     "@aws-sdk/s3-request-presigner": "^3.1000.0",
-    "@btravstack/config": "^0.36.0",
-    "@btravstack/core": "^0.36.0",
-    "@btravstack/di": "^0.36.0",
+    "@btravstack/config": "^0.38.0",
+    "@btravstack/core": "^0.38.0",
+    "@btravstack/di": "^0.38.0",
     "unthrown": "^5.0.0"
   },
   "peerDependenciesMeta": {