@btravstack/storage 0.37.0 → 0.39.0

package/README.md

@@ -67,7 +67,7 @@ export const invoices = InvoiceProvider(Invoices)({
         // is swallowed because an observer already recorded it and
         // counted it one layer down.
         .recoverErrCases((matcher) =>
-          matcher.with(P.tag("StorageUnavailable"), () => undefined),
+          matcher.with(P.tag("StorageUnavailable"), P.tag("InvalidStorageOptions"), P.tag("ChecksumMismatch"), () => undefined),
         ),
     // Serving bytes through your own process is the anti-pattern this arm
     // exists to avoid: the caller fetches the object directly, for a minute.
@@ -106,13 +106,16 @@ export const InvoicesApp = Module("InvoicesApp")({
 
 ## Options
 
-| Option                                                      | Where                              | What it is                                               |
-| ----------------------------------------------------------- | ---------------------------------- | -------------------------------------------------------- |
-| `adapter`                                                   | `storage({ adapter })`             | the adapter module providing `StorageBackend` — required |
-| `STORAGE_S3_ENDPOINT`                                       | environment, read by `s3Storage()` | the store's endpoint — required                          |
-| `STORAGE_S3_BUCKET`                                         | environment                        | the bucket — required                                    |
-| `STORAGE_S3_ACCESS_KEY_ID` / `STORAGE_S3_SECRET_ACCESS_KEY` | environment                        | the credentials — required                               |
-| `STORAGE_S3_REGION`                                         | environment                        | default `us-east-1`                                      |
+| Option                                                      | Where                              | What it is                                                                    |
+| ----------------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------- |
+| `sha256` / `metadata`                                       | `put` / `putIfAbsent`              | verify the write digest and atomically describe the object                    |
+| `checksum` / `metadata`                                     | `copy`                             | compute SHA-256 server side and replace the description                       |
+| `kmsKeyId`                                                  | writes, copy and `presignedUpload` | select per-object SSE-KMS; upload clients send both signed encryption headers |
+| `adapter`                                                   | `storage({ adapter })`             | the adapter module providing `StorageBackend` — required                      |
+| `STORAGE_S3_ENDPOINT`                                       | environment, read by `s3Storage()` | the store's endpoint — required                                               |
+| `STORAGE_S3_BUCKET`                                         | environment                        | the bucket — required                                                         |
+| `STORAGE_S3_ACCESS_KEY_ID` / `STORAGE_S3_SECRET_ACCESS_KEY` | environment                        | the credentials — required                                                    |
+| `STORAGE_S3_REGION`                                         | environment                        | default `us-east-1`                                                           |
 
 The full table — defaults, semantics and the reasoning — lives on
 [the reference page](https://btravstack.github.io/btravstack/reference/storage),
@@ -121,7 +124,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 a held key under `putIfAbsent` is an ordinary answer (`ObjectExists`, counted `exists`), that `delete` is idempotent, that
+(counted `not_found`, without a fault line), 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 writes can verify SHA-256 and publish user metadata atomically, that copies replace metadata and can compute SHA-256 server side, that presigned uploads can require a per-object KMS key, 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-DlAQXJ1t.cjs");
+const require_options = require("./options-BhML_i5p.cjs");
+let node_crypto = require("node:crypto");
 let _btravstack_di = require("@btravstack/di");
 let unthrown = require("unthrown");
 let _btravstack_core = require("@btravstack/core");
@@ -11,48 +12,74 @@ 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.
 */
 const memoryStorageBackend = () => {
 	const objects = /* @__PURE__ */ new Map();
+	const verify = (key, bytes, options) => require_options.validateOptions(key, options).flatMap(() => options.sha256 !== void 0 && (0, node_crypto.createHash)("sha256").update(bytes).digest("hex") !== options.sha256 ? (0, unthrown.Err)(new require_options.ChecksumMismatch({ key })) : (0, unthrown.Ok)());
 	return {
-		put: (key, bytes, options) => {
+		put: (key, bytes, options) => verify(key, bytes, options).map(() => {
 			objects.set(key, {
-				bytes,
-				contentType: options.contentType
+				bytes: Uint8Array.from(bytes),
+				contentType: options.contentType,
+				metadata: { ...options.metadata }
 			});
-			return (0, unthrown.OkAsync)();
-		},
-		putIfAbsent: (key, bytes, options) => {
-			if (objects.has(key)) return (0, unthrown.ErrAsync)(new require_storage.ObjectExists({ key }));
+		}).toAsync(),
+		putIfAbsent: (key, bytes, options) => verify(key, bytes, options).flatMap(() => {
+			if (objects.has(key)) return (0, unthrown.Err)(new require_options.ObjectExists({ key }));
 			objects.set(key, {
-				bytes,
-				contentType: options.contentType
+				bytes: Uint8Array.from(bytes),
+				contentType: options.contentType,
+				metadata: { ...options.metadata }
+			});
+			return (0, unthrown.Ok)();
+		}).toAsync(),
+		copy: (from, to, options) => require_options.validateOptions(to, options).flatMap(() => {
+			const object = objects.get(from);
+			if (object === void 0) return (0, unthrown.Err)(new require_options.ObjectNotFound({ key: from }));
+			objects.set(to, {
+				bytes: object.bytes.slice(),
+				contentType: options.contentType,
+				metadata: { ...options.metadata }
+			});
+			return (0, unthrown.Ok)();
+		}).toAsync(),
+		head: (key) => {
+			const object = objects.get(key);
+			return object === void 0 ? (0, unthrown.ErrAsync)(new require_options.ObjectNotFound({ key })) : (0, unthrown.OkAsync)({
+				metadata: { ...object.metadata },
+				size: object.bytes.byteLength,
+				contentType: object.contentType,
+				sha256: (0, node_crypto.createHash)("sha256").update(object.bytes).digest("hex")
 			});
-			return (0, unthrown.OkAsync)();
 		},
 		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_options.ObjectNotFound({ key })) : (0, unthrown.OkAsync)({
+				contentType: object.contentType,
+				bytes: object.bytes.slice()
+			});
 		},
 		delete: (key) => {
 			objects.delete(key);
 			return (0, unthrown.OkAsync)();
 		},
-		presignedUrl: (key) => (0, unthrown.ErrAsync)(new require_storage.PresignNotSupported({ key })),
-		presignedUpload: (key) => (0, unthrown.ErrAsync)(new require_storage.PresignNotSupported({ key }))
+		presignedUrl: (key) => (0, unthrown.ErrAsync)(new require_options.PresignNotSupported({ key })),
+		presignedUpload: (key) => (0, unthrown.ErrAsync)(new require_options.PresignNotSupported({ key }))
 	};
 };
 /** The adapter as a provider, which is the shape `@btravstack/testing`'s `overridden` takes. */
-const memoryStorageProvider = () => (0, _btravstack_di.Provider)(require_storage.StorageBackend)({
+const memoryStorageProvider = () => (0, _btravstack_di.Provider)(require_options.StorageBackend)({
 	inject: {},
 	sync: () => memoryStorageBackend()
 });
 /** The adapter as a module, which is the shape `storage({ adapter })` takes. */
 const memoryStorage = () => (0, _btravstack_di.Module)("MemoryStorage")({
 	provides: [memoryStorageProvider()],
-	exports: [require_storage.StorageBackend]
+	exports: [require_options.StorageBackend]
 });
 //#endregion
 //#region src/instrument.ts
@@ -60,8 +87,8 @@ const memoryStorage = () => (0, _btravstack_di.Module)("MemoryStorage")({
 * **A missing object settles `ok` with `result: "not_found"`, not `error`.**
 * Asking for something that is not there is an ordinary answer, and a dashboard
 * that treats it as a fault teaches its readers to ignore the fault line.
-* `StorageUnavailable` is what pages somebody, and it is the only one that
-* settles as an error. The two ordinary answers keep their own words in
+* `StorageUnavailable` is what pages somebody; invalid options and checksum
+* mismatches also settle as errors. The two ordinary answers keep their own words in
 * `reason`, so an operator is not left hunting an object sitting where they put
 * it.
 */
@@ -103,9 +130,29 @@ const through = (observers) => (operation, key, call) => (0, _btravstack_core.ob
 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)),
+		put: (key, bytes, options) => {
+			const snapshot = {
+				...options,
+				metadata: { ...options.metadata }
+			};
+			return observe("put", key, () => backend.put(key, bytes, snapshot));
+		},
+		putIfAbsent: (key, bytes, options) => {
+			const snapshot = {
+				...options,
+				metadata: { ...options.metadata }
+			};
+			return observe("put_if_absent", key, () => backend.putIfAbsent(key, bytes, snapshot));
+		},
 		get: (key) => observe("get", key, () => backend.get(key)),
+		copy: (from, to, options) => {
+			const snapshot = {
+				...options,
+				metadata: { ...options.metadata }
+			};
+			return observe("copy", from, () => backend.copy(from, to, snapshot));
+		},
+		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))
@@ -131,7 +178,7 @@ const instrument = (backend, observers) => {
 */
 const storage = ({ adapter }) => {
 	const healthCheck = _btravstack_di.Provider.member(_btravstack_core.HealthChecks)({
-		inject: { backend: require_storage.StorageBackend },
+		inject: { backend: require_options.StorageBackend },
 		sync: ({ backend }) => ({
 			name: "storage",
 			check: () => backend.get("btravstack:health").map(() => void 0).flatMapErrCases((matcher) => matcher.with(unthrown.P.tag("ObjectNotFound"), () => (0, unthrown.Ok)(void 0)).with(unthrown.P.tag("StorageUnavailable"), ({ reason }) => (0, unthrown.Err)(new _btravstack_core.HealthCheckFailed({ reason: `storage unavailable (${reason})` }))))
@@ -141,25 +188,27 @@ const storage = ({ adapter }) => {
 		imports: [adapter],
 		provides: [
 			_btravstack_core.noObserverMember,
-			(0, _btravstack_di.Provider)(require_storage.Storage)({
+			(0, _btravstack_di.Provider)(require_options.Storage)({
 				inject: {
-					backend: require_storage.StorageBackend,
+					backend: require_options.StorageBackend,
 					observers: _btravstack_core.Observers
 				},
 				sync: ({ backend, observers }) => instrument(backend, observers)
 			}),
 			healthCheck
 		],
-		exports: [require_storage.Storage, _btravstack_core.HealthChecks]
+		exports: [require_options.Storage, _btravstack_core.HealthChecks]
 	});
 };
 //#endregion
-exports.ObjectExists = require_storage.ObjectExists;
-exports.ObjectNotFound = require_storage.ObjectNotFound;
-exports.PresignNotSupported = require_storage.PresignNotSupported;
-exports.Storage = require_storage.Storage;
-exports.StorageBackend = require_storage.StorageBackend;
-exports.StorageUnavailable = require_storage.StorageUnavailable;
+exports.ChecksumMismatch = require_options.ChecksumMismatch;
+exports.InvalidStorageOptions = require_options.InvalidStorageOptions;
+exports.ObjectExists = require_options.ObjectExists;
+exports.ObjectNotFound = require_options.ObjectNotFound;
+exports.PresignNotSupported = require_options.PresignNotSupported;
+exports.Storage = require_options.Storage;
+exports.StorageBackend = require_options.StorageBackend;
+exports.StorageUnavailable = require_options.StorageUnavailable;
 exports.memoryStorage = memoryStorage;
 exports.memoryStorageBackend = memoryStorageBackend;
 exports.memoryStorageProvider = memoryStorageProvider;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { a as StorageBackend, c as StoredObject, i as Storage, n as ObjectNotFound, o as StorageService, r as PresignNotSupported, s as StorageUnavailable, t as ObjectExists } from "./storage-uSBWFyB2.cjs";
+import { a as ObjectHead, c as Storage, d as StorageUnavailable, f as StoredObject, i as ObjectExists, l as StorageBackend, n as CopyOptions, o as ObjectNotFound, p as WriteOptions, r as InvalidStorageOptions, s as PresignNotSupported, t as ChecksumMismatch, u as StorageService } from "./storage-CfN3KqWm.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 { ObjectExists, ObjectNotFound, PresignNotSupported, Storage, StorageBackend, type StorageOptions, type StorageService, StorageUnavailable, type StoredObject };
+export { ChecksumMismatch, type CopyOptions, InvalidStorageOptions, 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 StorageBackend, c as StoredObject, i as Storage, n as ObjectNotFound, o as StorageService, r as PresignNotSupported, s as StorageUnavailable, t as ObjectExists } from "./storage-uSBWFyB2.mjs";
+import { a as ObjectHead, c as Storage, d as StorageUnavailable, f as StoredObject, i as ObjectExists, l as StorageBackend, n as CopyOptions, o as ObjectNotFound, p as WriteOptions, r as InvalidStorageOptions, s as PresignNotSupported, t as ChecksumMismatch, u as StorageService } from "./storage-CfN3KqWm.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 { ObjectExists, ObjectNotFound, PresignNotSupported, Storage, StorageBackend, type StorageOptions, type StorageService, StorageUnavailable, type StoredObject };
+export { ChecksumMismatch, type CopyOptions, InvalidStorageOptions, 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 StorageBackend, i as Storage, n as ObjectNotFound, o as StorageUnavailable, r as PresignNotSupported, t as ObjectExists } from "./storage-BmbyYPIE.mjs";
+import { a as ObjectNotFound, c as StorageBackend, i as ObjectExists, l as StorageUnavailable, n as ChecksumMismatch, o as PresignNotSupported, r as InvalidStorageOptions, s as Storage, t as validateOptions } from "./options-DYPXkWb9.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,30 +11,56 @@ 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.
 */
 const memoryStorageBackend = () => {
 	const objects = /* @__PURE__ */ new Map();
+	const verify = (key, bytes, options) => validateOptions(key, options).flatMap(() => options.sha256 !== void 0 && createHash("sha256").update(bytes).digest("hex") !== options.sha256 ? Err(new ChecksumMismatch({ key })) : Ok());
 	return {
-		put: (key, bytes, options) => {
+		put: (key, bytes, options) => verify(key, bytes, options).map(() => {
 			objects.set(key, {
-				bytes,
-				contentType: options.contentType
+				bytes: Uint8Array.from(bytes),
+				contentType: options.contentType,
+				metadata: { ...options.metadata }
 			});
-			return OkAsync();
-		},
-		putIfAbsent: (key, bytes, options) => {
-			if (objects.has(key)) return ErrAsync(new ObjectExists({ key }));
+		}).toAsync(),
+		putIfAbsent: (key, bytes, options) => verify(key, bytes, options).flatMap(() => {
+			if (objects.has(key)) return Err(new ObjectExists({ key }));
 			objects.set(key, {
-				bytes,
-				contentType: options.contentType
+				bytes: Uint8Array.from(bytes),
+				contentType: options.contentType,
+				metadata: { ...options.metadata }
+			});
+			return Ok();
+		}).toAsync(),
+		copy: (from, to, options) => validateOptions(to, options).flatMap(() => {
+			const object = objects.get(from);
+			if (object === void 0) return Err(new ObjectNotFound({ key: from }));
+			objects.set(to, {
+				bytes: object.bytes.slice(),
+				contentType: options.contentType,
+				metadata: { ...options.metadata }
+			});
+			return Ok();
+		}).toAsync(),
+		head: (key) => {
+			const object = objects.get(key);
+			return object === void 0 ? ErrAsync(new ObjectNotFound({ key })) : OkAsync({
+				metadata: { ...object.metadata },
+				size: object.bytes.byteLength,
+				contentType: object.contentType,
+				sha256: createHash("sha256").update(object.bytes).digest("hex")
 			});
-			return OkAsync();
 		},
 		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({
+				contentType: object.contentType,
+				bytes: object.bytes.slice()
+			});
 		},
 		delete: (key) => {
 			objects.delete(key);
@@ -59,8 +86,8 @@ const memoryStorage = () => Module("MemoryStorage")({
 * **A missing object settles `ok` with `result: "not_found"`, not `error`.**
 * Asking for something that is not there is an ordinary answer, and a dashboard
 * that treats it as a fault teaches its readers to ignore the fault line.
-* `StorageUnavailable` is what pages somebody, and it is the only one that
-* settles as an error. The two ordinary answers keep their own words in
+* `StorageUnavailable` is what pages somebody; invalid options and checksum
+* mismatches also settle as errors. The two ordinary answers keep their own words in
 * `reason`, so an operator is not left hunting an object sitting where they put
 * it.
 */
@@ -102,9 +129,29 @@ const through = (observers) => (operation, key, call) => observed(observers, {
 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)),
+		put: (key, bytes, options) => {
+			const snapshot = {
+				...options,
+				metadata: { ...options.metadata }
+			};
+			return observe("put", key, () => backend.put(key, bytes, snapshot));
+		},
+		putIfAbsent: (key, bytes, options) => {
+			const snapshot = {
+				...options,
+				metadata: { ...options.metadata }
+			};
+			return observe("put_if_absent", key, () => backend.putIfAbsent(key, bytes, snapshot));
+		},
 		get: (key) => observe("get", key, () => backend.get(key)),
+		copy: (from, to, options) => {
+			const snapshot = {
+				...options,
+				metadata: { ...options.metadata }
+			};
+			return observe("copy", from, () => backend.copy(from, to, snapshot));
+		},
+		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))
@@ -153,4 +200,4 @@ const storage = ({ adapter }) => {
 	});
 };
 //#endregion
-export { ObjectExists, ObjectNotFound, PresignNotSupported, Storage, StorageBackend, StorageUnavailable, memoryStorage, memoryStorageBackend, memoryStorageProvider, storage };
+export { ChecksumMismatch, InvalidStorageOptions, ObjectExists, ObjectNotFound, PresignNotSupported, Storage, StorageBackend, StorageUnavailable, memoryStorage, memoryStorageBackend, memoryStorageProvider, storage };

package/dist/{storage-DlAQXJ1t.cjs → options-BhML_i5p.cjs}

@@ -1,10 +1,14 @@
 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") {};
+/** Invalid options are refused before any write or signature is attempted. */
+var InvalidStorageOptions = class extends (0, unthrown.TaggedError)("InvalidStorageOptions") {};
+/** The supplied SHA-256 did not match the body; no object was written. */
+var ChecksumMismatch = class extends (0, unthrown.TaggedError)("ChecksumMismatch") {};
 /** 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. */
@@ -24,6 +28,31 @@ 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
+//#region src/options.ts
+const validateOptions = (key, options) => {
+	if (options.sha256 !== void 0 && !/^[a-f0-9]{64}$/.test(options.sha256)) return (0, unthrown.Err)(new InvalidStorageOptions({
+		key,
+		reason: "invalid_sha256"
+	}));
+	if (Object.keys(options.metadata ?? {}).some((name) => !/^[!#$%&'*+\-.^_`|~0-9a-z]+$/.test(name))) return (0, unthrown.Err)(new InvalidStorageOptions({
+		key,
+		reason: "invalid_metadata_key"
+	}));
+	return (0, unthrown.Ok)();
+};
+//#endregion
+Object.defineProperty(exports, "ChecksumMismatch", {
+	enumerable: true,
+	get: function() {
+		return ChecksumMismatch;
+	}
+});
+Object.defineProperty(exports, "InvalidStorageOptions", {
+	enumerable: true,
+	get: function() {
+		return InvalidStorageOptions;
+	}
+});
 Object.defineProperty(exports, "ObjectExists", {
 	enumerable: true,
 	get: function() {
@@ -60,3 +89,9 @@ Object.defineProperty(exports, "StorageUnavailable", {
 		return StorageUnavailable;
 	}
 });
+Object.defineProperty(exports, "validateOptions", {
+	enumerable: true,
+	get: function() {
+		return validateOptions;
+	}
+});

package/dist/{storage-BmbyYPIE.mjs → options-DYPXkWb9.mjs}

@@ -1,10 +1,14 @@
 import { Port } from "@btravstack/di";
-import { TaggedError } from "unthrown";
+import { Err, Ok, 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") {};
+/** Invalid options are refused before any write or signature is attempted. */
+var InvalidStorageOptions = class extends TaggedError("InvalidStorageOptions") {};
+/** The supplied SHA-256 did not match the body; no object was written. */
+var ChecksumMismatch = class extends TaggedError("ChecksumMismatch") {};
 /** 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. */
@@ -24,4 +28,17 @@ 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 { StorageBackend as a, Storage as i, ObjectNotFound as n, StorageUnavailable as o, PresignNotSupported as r, ObjectExists as t };
+//#region src/options.ts
+const validateOptions = (key, options) => {
+	if (options.sha256 !== void 0 && !/^[a-f0-9]{64}$/.test(options.sha256)) return Err(new InvalidStorageOptions({
+		key,
+		reason: "invalid_sha256"
+	}));
+	if (Object.keys(options.metadata ?? {}).some((name) => !/^[!#$%&'*+\-.^_`|~0-9a-z]+$/.test(name))) return Err(new InvalidStorageOptions({
+		key,
+		reason: "invalid_metadata_key"
+	}));
+	return Ok();
+};
+//#endregion
+export { ObjectNotFound as a, StorageBackend as c, ObjectExists as i, StorageUnavailable as l, ChecksumMismatch as n, PresignNotSupported as o, InvalidStorageOptions as r, Storage as s, validateOptions as t };