@nifrajs/storage 1.3.1 → 1.5.0

package/README.md

@@ -20,12 +20,25 @@ const keys = await storage.list({ prefix: "avatars/" })
 | Adapter | Use | Notes |
 |---|---|---|
 | `MemoryStorage` | dev / tests | not durable, not shared across instances |
-| `FileStorage(root)` | a long-running server (Bun/Node/Deno) | bytes-only: `contentType` inferred from the extension, custom metadata not persisted |
+| `FileStorage(root)` | a long-running server (Bun/Node/Deno) | persists content type + custom metadata in an adjacent sidecar tree; legacy objects still infer MIME from extension |
 | `R2Storage(env.BUCKET)` | the edge (Cloudflare R2) | round-trips `contentType` + metadata; binding typed structurally (no `@cloudflare/workers-types`) |
 
 Implement `StorageAdapter` (`put` / `get` / `delete` / `exists` / `list`) for **S3 / GCS / anything else** —
 the same five methods, and your routes don't change.
 
+Run the executable contract against third-party adapters:
+
+```ts
+import { assertStorageAdapterConformance } from "@nifrajs/storage"
+
+await assertStorageAdapterConformance({ createAdapter: () => new MyStorage() })
+```
+
+Provider-specific mechanics stay optional: implement `PagedStorageAdapter`, `PresignableStorageAdapter`,
+and/or `MovableStorageAdapter` only when the provider supports cursor listing, URL signing, or server-side
+copy/move. Asset sensitivity, bucket routing, credentials, and TTL policy belong in the consuming app or
+private package—not in these mechanical interfaces.
+
 ## Key safety
 
 Keys are POSIX-ish relative paths (`avatars/u1.png`). **Every** adapter rejects unsafe keys — absolute
@@ -42,3 +55,5 @@ import { assertSafeKey, StorageKeyError } from "@nifrajs/storage"
 - `put(key, data, { contentType?, metadata? })` — `data` is `Uint8Array | ArrayBuffer | string`.
 - `get(key)` → `{ body, size, contentType?, metadata? } | null` · `delete(key)` · `exists(key)` · `list({ prefix?, limit? })`.
 - `assertSafeKey(key)` / `StorageKeyError` · `toBytes(data)`.
+- `assertStorageAdapterConformance({ createAdapter })` — dependency-free executable adapter contract.
+- Optional interfaces: `PagedStorageAdapter` · `PresignableStorageAdapter` · `MovableStorageAdapter`.

package/dist/conformance.d.ts

@@ -0,0 +1,23 @@
+import type { StorageAdapter } from "./types.js";
+/** Construction and cleanup hooks for {@link assertStorageAdapterConformance}. */
+export interface StorageAdapterConformanceOptions {
+    /** Return an empty, isolated adapter for this run. */
+    readonly createAdapter: () => StorageAdapter | Promise<StorageAdapter>;
+}
+/** A failed invariant reported by {@link assertStorageAdapterConformance}. */
+export declare class StorageAdapterConformanceError extends Error {
+    readonly check: string;
+    constructor(check: string, message: string, cause?: unknown);
+}
+/**
+ * Execute the observable {@link StorageAdapter} contract without depending on a test runner.
+ *
+ * The adapter must be isolated because this writes deterministic conformance keys. The promise resolves
+ * only after proving byte + metadata round-trips, overwrite, missing/delete semantics, prefix/limit listing,
+ * and uniform unsafe-key rejection across every key-taking method. When the adapter also implements an
+ * optional capability ({@link PagedStorageAdapter}, {@link PresignableStorageAdapter},
+ * {@link MovableStorageAdapter}), that capability's contract is proven too — implementing a capability
+ * partially or unsafely fails conformance rather than silently escaping it.
+ */
+export declare function assertStorageAdapterConformance(options: StorageAdapterConformanceOptions): Promise<void>;
+//# sourceMappingURL=conformance.d.ts.map

package/dist/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../src/conformance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAIV,cAAc,EACf,MAAM,YAAY,CAAA;AAEnB,kFAAkF;AAClF,MAAM,WAAW,gCAAgC;IAC/C,sDAAsD;IACtD,QAAQ,CAAC,aAAa,EAAE,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;CACvE;AAED,8EAA8E;AAC9E,qBAAa,8BAA+B,SAAQ,KAAK;IAErD,QAAQ,CAAC,KAAK,EAAE,MAAM;gBAAb,KAAK,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO;CAKlB;AAkBD;;;;;;;;;GASG;AACH,wBAAsB,+BAA+B,CACnD,OAAO,EAAE,gCAAgC,GACxC,OAAO,CAAC,IAAI,CAAC,CA4Jf"}

package/dist/conformance.js

@@ -0,0 +1,178 @@
+/** A failed invariant reported by {@link assertStorageAdapterConformance}. */
+export class StorageAdapterConformanceError extends Error {
+    check;
+    constructor(check, message, cause) {
+        super(`StorageAdapter conformance failed (${check}): ${message}`, { cause });
+        this.check = check;
+        this.name = "StorageAdapterConformanceError";
+    }
+}
+const fail = (check, message, cause) => {
+    throw new StorageAdapterConformanceError(check, message, cause);
+};
+const decode = (bytes) => new TextDecoder().decode(bytes);
+const hasPaging = (storage) => typeof storage.listPage === "function";
+const hasPresign = (storage) => typeof storage.presign === "function";
+const hasMove = (storage) => typeof storage.copy === "function" &&
+    typeof storage.move === "function";
+/**
+ * Execute the observable {@link StorageAdapter} contract without depending on a test runner.
+ *
+ * The adapter must be isolated because this writes deterministic conformance keys. The promise resolves
+ * only after proving byte + metadata round-trips, overwrite, missing/delete semantics, prefix/limit listing,
+ * and uniform unsafe-key rejection across every key-taking method. When the adapter also implements an
+ * optional capability ({@link PagedStorageAdapter}, {@link PresignableStorageAdapter},
+ * {@link MovableStorageAdapter}), that capability's contract is proven too — implementing a capability
+ * partially or unsafely fails conformance rather than silently escaping it.
+ */
+export async function assertStorageAdapterConformance(options) {
+    let storage;
+    try {
+        storage = await options.createAdapter();
+    }
+    catch (error) {
+        return fail("construction", "createAdapter failed", error);
+    }
+    const a = "nifra-conformance/a/one.txt";
+    const b = "nifra-conformance/a/two.bin";
+    const c = "nifra-conformance/b/three.bin";
+    try {
+        await storage.put(a, "one", {
+            contentType: "text/x-nifra-conformance",
+            metadata: { owner: "nifra", purpose: "conformance" },
+        });
+        const object = (await storage.get(a)) ?? fail("round trip", "put object was not readable");
+        if (!(object.body instanceof Uint8Array))
+            fail("round trip", "body must be Uint8Array");
+        if (decode(object.body) !== "one" || object.size !== 3) {
+            fail("round trip", "body or size changed during round-trip");
+        }
+        if (object.contentType !== "text/x-nifra-conformance") {
+            fail("metadata", "contentType did not round-trip");
+        }
+        if (object.metadata?.owner !== "nifra" || object.metadata.purpose !== "conformance") {
+            fail("metadata", "custom metadata did not round-trip");
+        }
+        if (!(await storage.exists(a)))
+            fail("exists", "stored key was reported missing");
+        if (await storage.exists("nifra-conformance/missing")) {
+            fail("exists", "missing key was reported present");
+        }
+        if ((await storage.get("nifra-conformance/missing")) !== null) {
+            fail("missing", "get must return null for a missing key");
+        }
+        await storage.put(a, "overwritten");
+        const overwritten = await storage.get(a);
+        if (overwritten === null || decode(overwritten.body) !== "overwritten") {
+            fail("overwrite", "put did not replace the existing body");
+        }
+        await storage.put(b, "two");
+        await storage.put(c, "three");
+        const prefixed = [...(await storage.list({ prefix: "nifra-conformance/a/" }))].sort();
+        if (prefixed.length !== 2 || prefixed[0] !== a || prefixed[1] !== b) {
+            fail("list prefix", "prefix listing returned unexpected keys");
+        }
+        if ((await storage.list({ prefix: "nifra-conformance/", limit: 1 })).length !== 1) {
+            fail("list limit", "limit was not respected");
+        }
+        const unsafeCalls = [
+            ["put", () => storage.put("../escape", "x")],
+            ["get", () => storage.get("../escape")],
+            ["delete", () => storage.delete("../escape")],
+            ["exists", () => storage.exists("../escape")],
+        ];
+        if (hasPaging(storage)) {
+            const paged = storage;
+            // The cursor walk must reproduce exactly the keys list() reports, without duplicates,
+            // and must terminate by omitting the cursor on the final page.
+            const all = [...(await paged.list({ prefix: "nifra-conformance/" }))].sort();
+            const walked = [];
+            let cursor;
+            for (let page = 0; page <= all.length; page++) {
+                const result = await paged.listPage({
+                    prefix: "nifra-conformance/",
+                    limit: 1,
+                    ...(cursor !== undefined ? { cursor } : {}),
+                });
+                if (result.keys.length > 1)
+                    fail("listPage limit", "page exceeded the requested limit");
+                walked.push(...result.keys);
+                cursor = result.cursor;
+                if (cursor === undefined)
+                    break;
+            }
+            if (cursor !== undefined)
+                fail("listPage cursor", "cursor never terminated");
+            const sortedWalk = [...walked].sort();
+            if (new Set(walked).size !== walked.length) {
+                fail("listPage cursor", "cursor walk returned duplicate keys");
+            }
+            if (sortedWalk.length !== all.length || sortedWalk.some((key, i) => key !== all[i])) {
+                fail("listPage cursor", "cursor walk and list() disagree on the key set");
+            }
+        }
+        if (hasMove(storage)) {
+            const movable = storage;
+            const copied = "nifra-conformance/b/copied.bin";
+            const moved = "nifra-conformance/b/moved.bin";
+            await movable.copy(c, copied);
+            const copyTarget = await movable.get(copied);
+            const copySource = await movable.get(c);
+            if (copyTarget === null || decode(copyTarget.body) !== "three") {
+                fail("copy", "copied object is missing or has different bytes");
+            }
+            if (copySource === null)
+                fail("copy", "copy must not remove the source object");
+            await movable.move(copied, moved);
+            const moveTarget = await movable.get(moved);
+            if (moveTarget === null || decode(moveTarget.body) !== "three") {
+                fail("move", "moved object is missing or has different bytes");
+            }
+            if ((await movable.exists(copied)) || (await movable.get(copied)) !== null) {
+                fail("move", "move must remove the source object");
+            }
+            await movable.delete(moved);
+            unsafeCalls.push(["copy source", () => movable.copy("../escape", copied)], ["copy destination", () => movable.copy(c, "../escape")], ["move source", () => movable.move("../escape", moved)], ["move destination", () => movable.move(c, "../escape")]);
+        }
+        if (hasPresign(storage)) {
+            const presignable = storage;
+            for (const operation of ["get", "put"]) {
+                const presigned = await presignable.presign(a, operation, {
+                    expiresInSeconds: 60,
+                    ...(operation === "put" ? { contentType: "text/plain", contentLength: 3 } : {}),
+                });
+                if (typeof presigned.url !== "string" || presigned.url.length === 0) {
+                    fail("presign", `${operation} presign did not return a URL`);
+                }
+                if (presigned.expiresAt !== undefined && presigned.expiresAt.getTime() <= Date.now()) {
+                    fail("presign", `${operation} presign returned an already-expired URL`);
+                }
+            }
+            unsafeCalls.push(["presign", () => presignable.presign("../escape", "get")]);
+        }
+        for (const [method, call] of unsafeCalls) {
+            try {
+                await call();
+                fail("key safety", `${method} accepted a traversal key`);
+            }
+            catch (error) {
+                if (error instanceof StorageAdapterConformanceError)
+                    throw error;
+            }
+        }
+        await storage.delete(a);
+        if ((await storage.get(a)) !== null || (await storage.exists(a))) {
+            fail("delete", "deleted object remained readable");
+        }
+        await storage.delete(a);
+    }
+    catch (error) {
+        if (error instanceof StorageAdapterConformanceError)
+            throw error;
+        fail("operation", "adapter operation rejected unexpectedly", error);
+    }
+    finally {
+        await Promise.allSettled([storage.delete(a), storage.delete(b), storage.delete(c)]);
+    }
+}
+//# sourceMappingURL=conformance.js.map

package/dist/conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.js","sourceRoot":"","sources":["../src/conformance.ts"],"names":[],"mappings":"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"}

package/dist/file.d.ts

@@ -1,10 +1,17 @@
 import { type ListOptions, type PutOptions, type StorageAdapter, type StorageData, type StorageObject } from "./types.js";
 export declare class FileStorage implements StorageAdapter {
     private readonly root;
+    private readonly metadataRoot;
     constructor(root: string);
+    private metadataPathFor;
     /** Resolve `key` to an absolute path, asserting it stays inside `root` (defense-in-depth on top of `assertSafeKey`). */
     private pathFor;
-    put(key: string, data: StorageData, _options?: PutOptions): Promise<void>;
+    private symlinkError;
+    /** Reject existing symbolic links below `base`; missing suffixes are safe for later creation. */
+    private assertNoSymlinkPath;
+    /** Create parents, re-check them, and refuse a final-component symlink at open time. */
+    private writeContained;
+    put(key: string, data: StorageData, options?: PutOptions): Promise<void>;
     get(key: string): Promise<StorageObject | null>;
     delete(key: string): Promise<void>;
     exists(key: string): Promise<boolean>;

package/dist/file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../src/file.ts"],"names":[],"mappings":"AASA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,aAAa,EAEnB,MAAM,YAAY,CAAA;AA4BnB,qBAAa,WAAY,YAAW,cAAc;IAChD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAQ;gBAEjB,IAAI,EAAE,MAAM;IAIxB,wHAAwH;IACxH,OAAO,CAAC,OAAO;IAST,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAM7E,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAc/C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASrC,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;YAU1C,IAAI;CAgBnB"}
+{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../src/file.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,aAAa,EAEnB,MAAM,YAAY,CAAA;AA4BnB,qBAAa,WAAY,YAAW,cAAc;IAChD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAQ;IAC7B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;gBAEzB,IAAI,EAAE,MAAM;IAOxB,OAAO,CAAC,eAAe;IAWvB,wHAAwH;IACxH,OAAO,CAAC,OAAO;IASf,OAAO,CAAC,YAAY;IAMpB,iGAAiG;YACnF,mBAAmB;IAsBjC,wFAAwF;YAC1E,cAAc;IA0BtB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB5E,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IA+B/C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYrC,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;YAU1C,IAAI;CAiBnB"}

package/dist/file.js

@@ -1,10 +1,11 @@
 /**
  * Local-filesystem {@link StorageAdapter} for long-running servers (Bun/Node/Deno). Keys map to paths
  * under `root`; `assertSafeKey` plus a resolved-path containment check keep writes inside `root` (no
- * traversal). Bytes-only: `contentType` is inferred from the key's extension on read, and custom metadata
- * is NOT persisted — use `MemoryStorage`/`R2Storage` (or your own adapter) if you need metadata round-tripped.
+ * traversal). Explicit content type and custom metadata are persisted in an adjacent sidecar tree;
+ * objects created before sidecar support still infer content type from their extension.
  */
-import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readdir, readFile, rm, stat } from "node:fs/promises";
 import { dirname, join, posix, resolve, sep } from "node:path";
 import { assertSafeKey, StorageKeyError } from "./key.js";
 import { toBytes, } from "./types.js";
@@ -34,8 +35,20 @@ function inferContentType(key) {
 }
 export class FileStorage {
     root;
+    metadataRoot;
     constructor(root) {
         this.root = resolve(root);
+        // Keep bookkeeping outside the object tree so every otherwise-safe key remains usable, including
+        // `.nifra-metadata/*`, and list() never needs a reserved-prefix exception.
+        this.metadataRoot = `${this.root}.nifra-metadata`;
+    }
+    metadataPathFor(key) {
+        assertSafeKey(key);
+        const full = resolve(this.metadataRoot, `${key}.json`);
+        if (!full.startsWith(this.metadataRoot + sep)) {
+            throw new StorageKeyError(`storage metadata key ${JSON.stringify(key)} escapes the storage root`);
+        }
+        return full;
     }
     /** Resolve `key` to an absolute path, asserting it stays inside `root` (defense-in-depth on top of `assertSafeKey`). */
     pathFor(key) {
@@ -46,35 +59,128 @@ export class FileStorage {
         }
         return full;
     }
-    async put(key, data, _options = {}) {
-        const path = this.pathFor(key);
+    symlinkError(key) {
+        return new StorageKeyError(`storage key ${JSON.stringify(key)} crosses a symbolic link beneath the storage root`);
+    }
+    /** Reject existing symbolic links below `base`; missing suffixes are safe for later creation. */
+    async assertNoSymlinkPath(base, path, key) {
+        try {
+            if ((await lstat(base)).isSymbolicLink())
+                throw this.symlinkError(key);
+        }
+        catch (error) {
+            if (error instanceof StorageKeyError)
+                throw error;
+            if (error.code === "ENOENT")
+                return;
+            throw error;
+        }
+        const suffix = path.slice(base.length + sep.length);
+        let current = base;
+        for (const segment of suffix.split(sep)) {
+            current = join(current, segment);
+            try {
+                if ((await lstat(current)).isSymbolicLink())
+                    throw this.symlinkError(key);
+            }
+            catch (error) {
+                if (error instanceof StorageKeyError)
+                    throw error;
+                if (error.code === "ENOENT")
+                    return;
+                throw error;
+            }
+        }
+    }
+    /** Create parents, re-check them, and refuse a final-component symlink at open time. */
+    async writeContained(base, path, key, data) {
+        await this.assertNoSymlinkPath(base, path, key);
         await mkdir(dirname(path), { recursive: true });
-        await writeFile(path, toBytes(data));
+        await this.assertNoSymlinkPath(base, path, key);
+        try {
+            const handle = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW, 0o666);
+            try {
+                await handle.writeFile(data);
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch (error) {
+            if (error.code === "ELOOP")
+                throw this.symlinkError(key);
+            throw error;
+        }
+    }
+    async put(key, data, options = {}) {
+        const path = this.pathFor(key);
+        await this.writeContained(this.root, path, key, toBytes(data));
+        const metadataPath = this.metadataPathFor(key);
+        if (options.contentType !== undefined || options.metadata !== undefined) {
+            await this.writeContained(this.metadataRoot, metadataPath, key, JSON.stringify({
+                ...(options.contentType !== undefined ? { contentType: options.contentType } : {}),
+                ...(options.metadata !== undefined ? { metadata: options.metadata } : {}),
+            }));
+        }
+        else {
+            await this.assertNoSymlinkPath(this.metadataRoot, metadataPath, key);
+            await rm(metadataPath, { force: true });
+        }
     }
     async get(key) {
         const path = this.pathFor(key);
+        await this.assertNoSymlinkPath(this.root, path, key);
         let body;
         try {
             body = new Uint8Array(await readFile(path));
         }
-        catch {
-            return null; // ENOENT (or unreadable) → treated as missing
+        catch (error) {
+            if (error.code === "ENOENT")
+                return null;
+            throw error;
         }
-        const contentType = inferContentType(key);
-        return contentType === undefined
-            ? { body, size: body.byteLength }
-            : { body, size: body.byteLength, contentType };
+        let stored = {};
+        try {
+            const metadataPath = this.metadataPathFor(key);
+            await this.assertNoSymlinkPath(this.metadataRoot, metadataPath, key);
+            stored = JSON.parse(await readFile(metadataPath, "utf8"));
+        }
+        catch (error) {
+            if (error instanceof StorageKeyError)
+                throw error;
+            if (error.code !== "ENOENT" && !(error instanceof SyntaxError)) {
+                throw error;
+            }
+            // Objects created before sidecar support still infer a useful MIME type from their extension.
+        }
+        const contentType = stored.contentType ?? inferContentType(key);
+        return {
+            body,
+            size: body.byteLength,
+            ...(contentType !== undefined ? { contentType } : {}),
+            ...(stored.metadata !== undefined ? { metadata: stored.metadata } : {}),
+        };
     }
     async delete(key) {
-        await rm(this.pathFor(key), { force: true });
+        const path = this.pathFor(key);
+        const metadataPath = this.metadataPathFor(key);
+        await Promise.all([
+            this.assertNoSymlinkPath(this.root, path, key),
+            this.assertNoSymlinkPath(this.metadataRoot, metadataPath, key),
+        ]);
+        await Promise.all([rm(path, { force: true }), rm(metadataPath, { force: true })]);
     }
     async exists(key) {
+        const path = this.pathFor(key);
+        await this.assertNoSymlinkPath(this.root, path, key);
         try {
-            await stat(this.pathFor(key));
+            await stat(path);
             return true;
         }
-        catch {
-            return false;
+        catch (error) {
+            if (error.code === "ENOENT")
+                return false;
+            throw error;
         }
     }
     async list(options = {}) {
@@ -99,7 +205,9 @@ export class FileStorage {
             const full = join(dir, name);
             // POSIX-join the key segments so listed keys are portable regardless of the host separator.
             const key = prefix === "" ? name : posix.join(prefix, name);
-            const info = await stat(full);
+            const info = await lstat(full);
+            if (info.isSymbolicLink())
+                continue;
             if (info.isDirectory())
                 await this.walk(full, key, out);
             else if (info.isFile())

package/dist/file.js.map

@@ -1 +1 @@
-{"version":3,"file":"file.js","sourceRoot":"","sources":["../src/file.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"file.js","sourceRoot":"","sources":["../src/file.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -9,9 +9,10 @@
  *   await storage.put("avatars/u1.png", bytes, { contentType: "image/png" })
  *   const object = await storage.get("avatars/u1.png")
  */
+export { assertStorageAdapterConformance, StorageAdapterConformanceError, type StorageAdapterConformanceOptions, } from "./conformance.js";
 export { FileStorage } from "./file.js";
 export { assertSafeKey, StorageKeyError } from "./key.js";
 export { MemoryStorage } from "./memory.js";
 export { type R2BucketLike, type R2ObjectLike, R2Storage } from "./r2.js";
-export { type ListOptions, type PutOptions, type StorageAdapter, type StorageData, type StorageObject, toBytes, } from "./types.js";
+export { type ListOptions, type MovableStorageAdapter, type PagedStorageAdapter, type PresignableStorageAdapter, type PutOptions, type StorageAdapter, type StorageData, type StorageListPage, type StorageListPageOptions, type StorageObject, type StoragePresignedUrl, type StoragePresignOperation, type StoragePresignOptions, toBytes, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACzE,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,OAAO,GACR,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,+BAA+B,EAC/B,8BAA8B,EAC9B,KAAK,gCAAgC,GACtC,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACzE,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,OAAO,GACR,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -9,6 +9,7 @@
  *   await storage.put("avatars/u1.png", bytes, { contentType: "image/png" })
  *   const object = await storage.get("avatars/u1.png")
  */
+export { assertStorageAdapterConformance, StorageAdapterConformanceError, } from "./conformance.js";
 export { FileStorage } from "./file.js";
 export { assertSafeKey, StorageKeyError } from "./key.js";
 export { MemoryStorage } from "./memory.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAwC,SAAS,EAAE,MAAM,SAAS,CAAA;AACzE,OAAO,EAML,OAAO,GACR,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,+BAA+B,EAC/B,8BAA8B,GAE/B,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAwC,SAAS,EAAE,MAAM,SAAS,CAAA;AACzE,OAAO,EAcL,OAAO,GACR,MAAM,YAAY,CAAA"}

package/dist/key.d.ts

@@ -5,7 +5,7 @@
  * portable across them, and so the check can't be forgotten on the one adapter where it's a vulnerability.
  */
 export declare class StorageKeyError extends Error {
-    readonly name = "StorageKeyError";
+    constructor(message: string);
 }
 /** Throw {@link StorageKeyError} unless `key` is a safe relative storage key. */
 export declare function assertSafeKey(key: string): void;

package/dist/key.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../src/key.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAkB,IAAI,qBAAoB;CAC3C;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAc/C"}
+{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../src/key.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAc/C"}

package/dist/key.js

@@ -5,7 +5,10 @@
  * portable across them, and so the check can't be forgotten on the one adapter where it's a vulnerability.
  */
 export class StorageKeyError extends Error {
-    name = "StorageKeyError";
+    constructor(message) {
+        super(message);
+        this.name = "StorageKeyError";
+    }
 }
 /** Throw {@link StorageKeyError} unless `key` is a safe relative storage key. */
 export function assertSafeKey(key) {

package/dist/key.js.map

@@ -1 +1 @@
-{"version":3,"file":"key.js","sourceRoot":"","sources":["../src/key.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACtB,IAAI,GAAG,iBAAiB,CAAA;CAC3C;AAED,iFAAiF;AACjF,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;QAC1C,MAAM,IAAI,eAAe,CAAC,yCAAyC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAA;IACnF,CAAC;IACD,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACpE,MAAM,IAAI,eAAe,CACvB,sBAAsB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,gCAAgC,CAC1E,CAAA;IACH,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACrC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,MAAM,IAAI,eAAe,CAAC,sBAAsB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAA;QAC9F,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"key.js","sourceRoot":"","sources":["../src/key.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAA;IAC/B,CAAC;CACF;AAED,iFAAiF;AACjF,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;QAC1C,MAAM,IAAI,eAAe,CAAC,yCAAyC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAA;IACnF,CAAC;IACD,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACpE,MAAM,IAAI,eAAe,CACvB,sBAAsB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,gCAAgC,CAC1E,CAAA;IACH,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACrC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,MAAM,IAAI,eAAe,CAAC,sBAAsB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAA;QAC9F,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/memory.d.ts

@@ -1,6 +1,7 @@
 import { type ListOptions, type PutOptions, type StorageAdapter, type StorageData, type StorageObject } from "./types.js";
 export declare class MemoryStorage implements StorageAdapter {
     private readonly objects;
+    constructor();
     put(key: string, data: StorageData, options?: PutOptions): Promise<void>;
     get(key: string): Promise<StorageObject | null>;
     delete(key: string): Promise<void>;

package/dist/memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,aAAa,EAEnB,MAAM,YAAY,CAAA;AAQnB,qBAAa,aAAc,YAAW,cAAc;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IAE7C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAU5E,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAY/C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKrC,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAMzD"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,aAAa,EAEnB,MAAM,YAAY,CAAA;AAQnB,qBAAa,aAAc,YAAW,cAAc;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;;IAMtC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAU5E,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAY/C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKrC,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAMzD"}

package/dist/memory.js

@@ -6,7 +6,10 @@
 import { assertSafeKey } from "./key.js";
 import { toBytes, } from "./types.js";
 export class MemoryStorage {
-    objects = new Map();
+    objects;
+    constructor() {
+        this.objects = new Map();
+    }
     async put(key, data, options = {}) {
         assertSafeKey(key);
         const entry = { body: toBytes(data) };

package/dist/memory.js.map

@@ -1 +1 @@
-{"version":3,"file":"memory.js","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAML,OAAO,GACR,MAAM,YAAY,CAAA;AAQnB,MAAM,OAAO,aAAa;IACP,OAAO,GAAG,IAAI,GAAG,EAAiB,CAAA;IAEnD,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,IAAiB,EAAE,UAAsB,EAAE;QAChE,aAAa,CAAC,GAAG,CAAC,CAAA;QAClB,MAAM,KAAK,GAAU,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,CAAA;QAC5C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE;YACpB,GAAG,KAAK;YACR,GAAG,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAClF,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1E,CAAC,CAAA;IACJ,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,aAAa,CAAC,GAAG,CAAC,CAAA;QAClB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACnC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,IAAI,CAAA;QACpC,OAAO;YACL,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU;YAC3B,GAAG,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9E,GAAG,CAAC,KAAK,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACtE,CAAA;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,aAAa,CAAC,GAAG,CAAC,CAAA;QAClB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAC1B,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,aAAa,CAAC,GAAG,CAAC,CAAA;QAClB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC9B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,UAAuB,EAAE;QAClC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,EAAE,CAAA;QACnC,IAAI,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QAC9E,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAA;QACpE,OAAO,IAAI,CAAA;IACb,CAAC;CACF"}
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAML,OAAO,GACR,MAAM,YAAY,CAAA;AAQnB,MAAM,OAAO,aAAa;IACP,OAAO,CAAoB;IAE5C;QACE,IAAI,CAAC,OAAO,GAAG,IAAI,GAAG,EAAE,CAAA;IAC1B,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,IAAiB,EAAE,UAAsB,EAAE;QAChE,aAAa,CAAC,GAAG,CAAC,CAAA;QAClB,MAAM,KAAK,GAAU,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,CAAA;QAC5C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE;YACpB,GAAG,KAAK;YACR,GAAG,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAClF,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1E,CAAC,CAAA;IACJ,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,aAAa,CAAC,GAAG,CAAC,CAAA;QAClB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACnC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,IAAI,CAAA;QACpC,OAAO;YACL,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU;YAC3B,GAAG,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9E,GAAG,CAAC,KAAK,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACtE,CAAA;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,aAAa,CAAC,GAAG,CAAC,CAAA;QAClB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAC1B,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,aAAa,CAAC,GAAG,CAAC,CAAA;QAClB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC9B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,UAAuB,EAAE;QAClC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,EAAE,CAAA;QACnC,IAAI,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QAC9E,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAA;QACpE,OAAO,IAAI,CAAA;IACb,CAAC;CACF"}

package/dist/types.d.ts

@@ -25,6 +25,31 @@ export interface ListOptions {
     /** Cap the number of keys returned. */
     readonly limit?: number;
 }
+/** One page of keys from stores that expose cursor-based listing. */
+export interface StorageListPage {
+    readonly keys: readonly string[];
+    /** Opaque cursor for the next page; absent when this is the final page. */
+    readonly cursor?: string;
+}
+/** Cursor-aware listing options. `cursor` is adapter-owned and must be treated as opaque. */
+export interface StorageListPageOptions extends ListOptions {
+    readonly cursor?: string;
+}
+/** Operation represented by a presigned storage URL. */
+export type StoragePresignOperation = "get" | "put";
+/** Mechanical constraints applied while minting a presigned URL. */
+export interface StoragePresignOptions {
+    readonly expiresInSeconds?: number;
+    /** For PUT URLs, pin the declared MIME type. */
+    readonly contentType?: string;
+    /** For PUT URLs, pin the exact request-body size. */
+    readonly contentLength?: number;
+}
+/** A provider-minted URL and its known expiry. */
+export interface StoragePresignedUrl {
+    readonly url: string;
+    readonly expiresAt?: Date;
+}
 /**
  * A blob store keyed by string. Keys are POSIX-ish paths (`avatars/u1.png`); every adapter rejects unsafe
  * keys (absolute, `..` traversal, NUL, backslash) so a key valid in one adapter is valid in all. All
@@ -42,6 +67,19 @@ export interface StorageAdapter {
     /** List stored keys (optionally filtered by prefix + capped). */
     list(options?: ListOptions): Promise<string[]>;
 }
+/** Optional cursor-listing capability. Kept out of {@link StorageAdapter} for simple stores. */
+export interface PagedStorageAdapter extends StorageAdapter {
+    listPage(options?: StorageListPageOptions): Promise<StorageListPage>;
+}
+/** Optional provider-side URL-signing capability. Asset sensitivity and TTL policy stay with callers. */
+export interface PresignableStorageAdapter extends StorageAdapter {
+    presign(key: string, operation: StoragePresignOperation, options?: StoragePresignOptions): Promise<StoragePresignedUrl>;
+}
+/** Optional server-side copy/move capability. */
+export interface MovableStorageAdapter extends StorageAdapter {
+    copy(sourceKey: string, destinationKey: string): Promise<void>;
+    move(sourceKey: string, destinationKey: string): Promise<void>;
+}
 /** Normalize any accepted payload to bytes. */
 export declare function toBytes(data: StorageData): Uint8Array;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,qEAAqE;AACrE,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,WAAW,GAAG,MAAM,CAAA;AAE3D,MAAM,WAAW,UAAU;IACzB,iEAAiE;IACjE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CACrD;AAED,sGAAsG;AACtG,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CACrD;AAED,MAAM,WAAW,WAAW;IAC1B,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,uCAAuC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACxE,+DAA+D;IAC/D,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAA;IAC/C,+CAA+C;IAC/C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,yCAAyC;IACzC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACrC,iEAAiE;IACjE,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;CAC/C;AAED,+CAA+C;AAC/C,wBAAgB,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,CAIrD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA6CH,+CAA+C;AAC/C,MAAM,UAAU,OAAO,CAAC,IAAiB;IACvC,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IACnE,IAAI,IAAI,YAAY,UAAU;QAAE,OAAO,IAAI,CAAA;IAC3C,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,CAAA;AAC7B,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA+FH,+CAA+C;AAC/C,MAAM,UAAU,OAAO,CAAC,IAAiB;IACvC,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IACnE,IAAI,IAAI,YAAY,UAAU;QAAE,OAAO,IAAI,CAAA;IAC3C,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,CAAA;AAC7B,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nifrajs/storage",
-  "version": "1.3.1",
-  "description": "Blob storage for nifra — one StorageAdapter interface with memory, local-filesystem, and Cloudflare R2 adapters (key-traversal-safe). The persistence half of @nifrajs/uploads. Dependency-free; bring your own adapter for S3/GCS.",
+  "version": "1.5.0",
+  "description": "Blob storage mechanics for nifra — traversal-safe memory, filesystem, and R2 adapters, optional provider capabilities, and executable adapter conformance.",
   "keywords": [
     "bun",
     "typescript",

package/src/conformance.ts

@@ -0,0 +1,210 @@
+import type {
+  MovableStorageAdapter,
+  PagedStorageAdapter,
+  PresignableStorageAdapter,
+  StorageAdapter,
+} from "./types.ts"
+
+/** Construction and cleanup hooks for {@link assertStorageAdapterConformance}. */
+export interface StorageAdapterConformanceOptions {
+  /** Return an empty, isolated adapter for this run. */
+  readonly createAdapter: () => StorageAdapter | Promise<StorageAdapter>
+}
+
+/** A failed invariant reported by {@link assertStorageAdapterConformance}. */
+export class StorageAdapterConformanceError extends Error {
+  constructor(
+    readonly check: string,
+    message: string,
+    cause?: unknown,
+  ) {
+    super(`StorageAdapter conformance failed (${check}): ${message}`, { cause })
+    this.name = "StorageAdapterConformanceError"
+  }
+}
+
+const fail = (check: string, message: string, cause?: unknown): never => {
+  throw new StorageAdapterConformanceError(check, message, cause)
+}
+
+const decode = (bytes: Uint8Array): string => new TextDecoder().decode(bytes)
+
+const hasPaging = (storage: StorageAdapter): storage is PagedStorageAdapter =>
+  typeof (storage as PagedStorageAdapter).listPage === "function"
+
+const hasPresign = (storage: StorageAdapter): storage is PresignableStorageAdapter =>
+  typeof (storage as PresignableStorageAdapter).presign === "function"
+
+const hasMove = (storage: StorageAdapter): storage is MovableStorageAdapter =>
+  typeof (storage as MovableStorageAdapter).copy === "function" &&
+  typeof (storage as MovableStorageAdapter).move === "function"
+
+/**
+ * Execute the observable {@link StorageAdapter} contract without depending on a test runner.
+ *
+ * The adapter must be isolated because this writes deterministic conformance keys. The promise resolves
+ * only after proving byte + metadata round-trips, overwrite, missing/delete semantics, prefix/limit listing,
+ * and uniform unsafe-key rejection across every key-taking method. When the adapter also implements an
+ * optional capability ({@link PagedStorageAdapter}, {@link PresignableStorageAdapter},
+ * {@link MovableStorageAdapter}), that capability's contract is proven too — implementing a capability
+ * partially or unsafely fails conformance rather than silently escaping it.
+ */
+export async function assertStorageAdapterConformance(
+  options: StorageAdapterConformanceOptions,
+): Promise<void> {
+  let storage: StorageAdapter
+  try {
+    storage = await options.createAdapter()
+  } catch (error) {
+    return fail("construction", "createAdapter failed", error)
+  }
+
+  const a = "nifra-conformance/a/one.txt"
+  const b = "nifra-conformance/a/two.bin"
+  const c = "nifra-conformance/b/three.bin"
+
+  try {
+    await storage.put(a, "one", {
+      contentType: "text/x-nifra-conformance",
+      metadata: { owner: "nifra", purpose: "conformance" },
+    })
+    const object = (await storage.get(a)) ?? fail("round trip", "put object was not readable")
+    if (!(object.body instanceof Uint8Array)) fail("round trip", "body must be Uint8Array")
+    if (decode(object.body) !== "one" || object.size !== 3) {
+      fail("round trip", "body or size changed during round-trip")
+    }
+    if (object.contentType !== "text/x-nifra-conformance") {
+      fail("metadata", "contentType did not round-trip")
+    }
+    if (object.metadata?.owner !== "nifra" || object.metadata.purpose !== "conformance") {
+      fail("metadata", "custom metadata did not round-trip")
+    }
+
+    if (!(await storage.exists(a))) fail("exists", "stored key was reported missing")
+    if (await storage.exists("nifra-conformance/missing")) {
+      fail("exists", "missing key was reported present")
+    }
+    if ((await storage.get("nifra-conformance/missing")) !== null) {
+      fail("missing", "get must return null for a missing key")
+    }
+
+    await storage.put(a, "overwritten")
+    const overwritten = await storage.get(a)
+    if (overwritten === null || decode(overwritten.body) !== "overwritten") {
+      fail("overwrite", "put did not replace the existing body")
+    }
+
+    await storage.put(b, "two")
+    await storage.put(c, "three")
+    const prefixed = [...(await storage.list({ prefix: "nifra-conformance/a/" }))].sort()
+    if (prefixed.length !== 2 || prefixed[0] !== a || prefixed[1] !== b) {
+      fail("list prefix", "prefix listing returned unexpected keys")
+    }
+    if ((await storage.list({ prefix: "nifra-conformance/", limit: 1 })).length !== 1) {
+      fail("list limit", "limit was not respected")
+    }
+
+    const unsafeCalls: Array<readonly [string, () => Promise<unknown>]> = [
+      ["put", () => storage.put("../escape", "x")],
+      ["get", () => storage.get("../escape")],
+      ["delete", () => storage.delete("../escape")],
+      ["exists", () => storage.exists("../escape")],
+    ]
+    if (hasPaging(storage)) {
+      const paged = storage
+
+      // The cursor walk must reproduce exactly the keys list() reports, without duplicates,
+      // and must terminate by omitting the cursor on the final page.
+      const all = [...(await paged.list({ prefix: "nifra-conformance/" }))].sort()
+      const walked: string[] = []
+      let cursor: string | undefined
+      for (let page = 0; page <= all.length; page++) {
+        const result = await paged.listPage({
+          prefix: "nifra-conformance/",
+          limit: 1,
+          ...(cursor !== undefined ? { cursor } : {}),
+        })
+        if (result.keys.length > 1) fail("listPage limit", "page exceeded the requested limit")
+        walked.push(...result.keys)
+        cursor = result.cursor
+        if (cursor === undefined) break
+      }
+      if (cursor !== undefined) fail("listPage cursor", "cursor never terminated")
+      const sortedWalk = [...walked].sort()
+      if (new Set(walked).size !== walked.length) {
+        fail("listPage cursor", "cursor walk returned duplicate keys")
+      }
+      if (sortedWalk.length !== all.length || sortedWalk.some((key, i) => key !== all[i])) {
+        fail("listPage cursor", "cursor walk and list() disagree on the key set")
+      }
+    }
+
+    if (hasMove(storage)) {
+      const movable = storage
+      const copied = "nifra-conformance/b/copied.bin"
+      const moved = "nifra-conformance/b/moved.bin"
+
+      await movable.copy(c, copied)
+      const copyTarget = await movable.get(copied)
+      const copySource = await movable.get(c)
+      if (copyTarget === null || decode(copyTarget.body) !== "three") {
+        fail("copy", "copied object is missing or has different bytes")
+      }
+      if (copySource === null) fail("copy", "copy must not remove the source object")
+
+      await movable.move(copied, moved)
+      const moveTarget = await movable.get(moved)
+      if (moveTarget === null || decode(moveTarget.body) !== "three") {
+        fail("move", "moved object is missing or has different bytes")
+      }
+      if ((await movable.exists(copied)) || (await movable.get(copied)) !== null) {
+        fail("move", "move must remove the source object")
+      }
+      await movable.delete(moved)
+
+      unsafeCalls.push(
+        ["copy source", () => movable.copy("../escape", copied)],
+        ["copy destination", () => movable.copy(c, "../escape")],
+        ["move source", () => movable.move("../escape", moved)],
+        ["move destination", () => movable.move(c, "../escape")],
+      )
+    }
+
+    if (hasPresign(storage)) {
+      const presignable = storage
+      for (const operation of ["get", "put"] as const) {
+        const presigned = await presignable.presign(a, operation, {
+          expiresInSeconds: 60,
+          ...(operation === "put" ? { contentType: "text/plain", contentLength: 3 } : {}),
+        })
+        if (typeof presigned.url !== "string" || presigned.url.length === 0) {
+          fail("presign", `${operation} presign did not return a URL`)
+        }
+        if (presigned.expiresAt !== undefined && presigned.expiresAt.getTime() <= Date.now()) {
+          fail("presign", `${operation} presign returned an already-expired URL`)
+        }
+      }
+      unsafeCalls.push(["presign", () => presignable.presign("../escape", "get")])
+    }
+
+    for (const [method, call] of unsafeCalls) {
+      try {
+        await call()
+        fail("key safety", `${method} accepted a traversal key`)
+      } catch (error) {
+        if (error instanceof StorageAdapterConformanceError) throw error
+      }
+    }
+
+    await storage.delete(a)
+    if ((await storage.get(a)) !== null || (await storage.exists(a))) {
+      fail("delete", "deleted object remained readable")
+    }
+    await storage.delete(a)
+  } catch (error) {
+    if (error instanceof StorageAdapterConformanceError) throw error
+    fail("operation", "adapter operation rejected unexpectedly", error)
+  } finally {
+    await Promise.allSettled([storage.delete(a), storage.delete(b), storage.delete(c)])
+  }
+}

package/src/file.ts

@@ -1,10 +1,11 @@
 /**
  * Local-filesystem {@link StorageAdapter} for long-running servers (Bun/Node/Deno). Keys map to paths
  * under `root`; `assertSafeKey` plus a resolved-path containment check keep writes inside `root` (no
- * traversal). Bytes-only: `contentType` is inferred from the key's extension on read, and custom metadata
- * is NOT persisted — use `MemoryStorage`/`R2Storage` (or your own adapter) if you need metadata round-tripped.
+ * traversal). Explicit content type and custom metadata are persisted in an adjacent sidecar tree;
+ * objects created before sidecar support still infer content type from their extension.
  */
-import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises"
+import { constants } from "node:fs"
+import { lstat, mkdir, open, readdir, readFile, rm, stat } from "node:fs/promises"
 import { dirname, join, posix, resolve, sep } from "node:path"
 import { assertSafeKey, StorageKeyError } from "./key.ts"
 import {
@@ -44,9 +45,24 @@ function inferContentType(key: string): string | undefined {
 
 export class FileStorage implements StorageAdapter {
   private readonly root: string
+  private readonly metadataRoot: string
 
   constructor(root: string) {
     this.root = resolve(root)
+    // Keep bookkeeping outside the object tree so every otherwise-safe key remains usable, including
+    // `.nifra-metadata/*`, and list() never needs a reserved-prefix exception.
+    this.metadataRoot = `${this.root}.nifra-metadata`
+  }
+
+  private metadataPathFor(key: string): string {
+    assertSafeKey(key)
+    const full = resolve(this.metadataRoot, `${key}.json`)
+    if (!full.startsWith(this.metadataRoot + sep)) {
+      throw new StorageKeyError(
+        `storage metadata key ${JSON.stringify(key)} escapes the storage root`,
+      )
+    }
+    return full
   }
 
   /** Resolve `key` to an absolute path, asserting it stays inside `root` (defense-in-depth on top of `assertSafeKey`). */
@@ -59,36 +75,132 @@ export class FileStorage implements StorageAdapter {
     return full
   }
 
-  async put(key: string, data: StorageData, _options: PutOptions = {}): Promise<void> {
-    const path = this.pathFor(key)
+  private symlinkError(key: string): StorageKeyError {
+    return new StorageKeyError(
+      `storage key ${JSON.stringify(key)} crosses a symbolic link beneath the storage root`,
+    )
+  }
+
+  /** Reject existing symbolic links below `base`; missing suffixes are safe for later creation. */
+  private async assertNoSymlinkPath(base: string, path: string, key: string): Promise<void> {
+    try {
+      if ((await lstat(base)).isSymbolicLink()) throw this.symlinkError(key)
+    } catch (error) {
+      if (error instanceof StorageKeyError) throw error
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return
+      throw error
+    }
+    const suffix = path.slice(base.length + sep.length)
+    let current = base
+    for (const segment of suffix.split(sep)) {
+      current = join(current, segment)
+      try {
+        if ((await lstat(current)).isSymbolicLink()) throw this.symlinkError(key)
+      } catch (error) {
+        if (error instanceof StorageKeyError) throw error
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") return
+        throw error
+      }
+    }
+  }
+
+  /** Create parents, re-check them, and refuse a final-component symlink at open time. */
+  private async writeContained(
+    base: string,
+    path: string,
+    key: string,
+    data: Uint8Array | string,
+  ): Promise<void> {
+    await this.assertNoSymlinkPath(base, path, key)
     await mkdir(dirname(path), { recursive: true })
-    await writeFile(path, toBytes(data))
+    await this.assertNoSymlinkPath(base, path, key)
+    try {
+      const handle = await open(
+        path,
+        constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW,
+        0o666,
+      )
+      try {
+        await handle.writeFile(data)
+      } finally {
+        await handle.close()
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ELOOP") throw this.symlinkError(key)
+      throw error
+    }
+  }
+
+  async put(key: string, data: StorageData, options: PutOptions = {}): Promise<void> {
+    const path = this.pathFor(key)
+    await this.writeContained(this.root, path, key, toBytes(data))
+    const metadataPath = this.metadataPathFor(key)
+    if (options.contentType !== undefined || options.metadata !== undefined) {
+      await this.writeContained(
+        this.metadataRoot,
+        metadataPath,
+        key,
+        JSON.stringify({
+          ...(options.contentType !== undefined ? { contentType: options.contentType } : {}),
+          ...(options.metadata !== undefined ? { metadata: options.metadata } : {}),
+        }),
+      )
+    } else {
+      await this.assertNoSymlinkPath(this.metadataRoot, metadataPath, key)
+      await rm(metadataPath, { force: true })
+    }
   }
 
   async get(key: string): Promise<StorageObject | null> {
     const path = this.pathFor(key)
+    await this.assertNoSymlinkPath(this.root, path, key)
     let body: Uint8Array
     try {
       body = new Uint8Array(await readFile(path))
-    } catch {
-      return null // ENOENT (or unreadable) → treated as missing
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return null
+      throw error
+    }
+    let stored: { contentType?: string; metadata?: Readonly<Record<string, string>> } = {}
+    try {
+      const metadataPath = this.metadataPathFor(key)
+      await this.assertNoSymlinkPath(this.metadataRoot, metadataPath, key)
+      stored = JSON.parse(await readFile(metadataPath, "utf8")) as typeof stored
+    } catch (error) {
+      if (error instanceof StorageKeyError) throw error
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT" && !(error instanceof SyntaxError)) {
+        throw error
+      }
+      // Objects created before sidecar support still infer a useful MIME type from their extension.
+    }
+    const contentType = stored.contentType ?? inferContentType(key)
+    return {
+      body,
+      size: body.byteLength,
+      ...(contentType !== undefined ? { contentType } : {}),
+      ...(stored.metadata !== undefined ? { metadata: stored.metadata } : {}),
     }
-    const contentType = inferContentType(key)
-    return contentType === undefined
-      ? { body, size: body.byteLength }
-      : { body, size: body.byteLength, contentType }
   }
 
   async delete(key: string): Promise<void> {
-    await rm(this.pathFor(key), { force: true })
+    const path = this.pathFor(key)
+    const metadataPath = this.metadataPathFor(key)
+    await Promise.all([
+      this.assertNoSymlinkPath(this.root, path, key),
+      this.assertNoSymlinkPath(this.metadataRoot, metadataPath, key),
+    ])
+    await Promise.all([rm(path, { force: true }), rm(metadataPath, { force: true })])
   }
 
   async exists(key: string): Promise<boolean> {
+    const path = this.pathFor(key)
+    await this.assertNoSymlinkPath(this.root, path, key)
     try {
-      await stat(this.pathFor(key))
+      await stat(path)
       return true
-    } catch {
-      return false
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return false
+      throw error
     }
   }
 
@@ -113,7 +225,8 @@ export class FileStorage implements StorageAdapter {
       const full = join(dir, name)
       // POSIX-join the key segments so listed keys are portable regardless of the host separator.
       const key = prefix === "" ? name : posix.join(prefix, name)
-      const info = await stat(full)
+      const info = await lstat(full)
+      if (info.isSymbolicLink()) continue
       if (info.isDirectory()) await this.walk(full, key, out)
       else if (info.isFile()) out.push(key)
     }

package/src/index.ts

@@ -10,15 +10,28 @@
  *   const object = await storage.get("avatars/u1.png")
  */
 
+export {
+  assertStorageAdapterConformance,
+  StorageAdapterConformanceError,
+  type StorageAdapterConformanceOptions,
+} from "./conformance.ts"
 export { FileStorage } from "./file.ts"
 export { assertSafeKey, StorageKeyError } from "./key.ts"
 export { MemoryStorage } from "./memory.ts"
 export { type R2BucketLike, type R2ObjectLike, R2Storage } from "./r2.ts"
 export {
   type ListOptions,
+  type MovableStorageAdapter,
+  type PagedStorageAdapter,
+  type PresignableStorageAdapter,
   type PutOptions,
   type StorageAdapter,
   type StorageData,
+  type StorageListPage,
+  type StorageListPageOptions,
   type StorageObject,
+  type StoragePresignedUrl,
+  type StoragePresignOperation,
+  type StoragePresignOptions,
   toBytes,
 } from "./types.ts"

package/src/key.ts

@@ -6,7 +6,10 @@
  */
 
 export class StorageKeyError extends Error {
-  override readonly name = "StorageKeyError"
+  constructor(message: string) {
+    super(message)
+    this.name = "StorageKeyError"
+  }
 }
 
 /** Throw {@link StorageKeyError} unless `key` is a safe relative storage key. */

package/src/memory.ts

@@ -20,7 +20,11 @@ interface Entry {
 }
 
 export class MemoryStorage implements StorageAdapter {
-  private readonly objects = new Map<string, Entry>()
+  private readonly objects: Map<string, Entry>
+
+  constructor() {
+    this.objects = new Map()
+  }
 
   async put(key: string, data: StorageData, options: PutOptions = {}): Promise<void> {
     assertSafeKey(key)

package/src/types.ts

@@ -30,6 +30,36 @@ export interface ListOptions {
   readonly limit?: number
 }
 
+/** One page of keys from stores that expose cursor-based listing. */
+export interface StorageListPage {
+  readonly keys: readonly string[]
+  /** Opaque cursor for the next page; absent when this is the final page. */
+  readonly cursor?: string
+}
+
+/** Cursor-aware listing options. `cursor` is adapter-owned and must be treated as opaque. */
+export interface StorageListPageOptions extends ListOptions {
+  readonly cursor?: string
+}
+
+/** Operation represented by a presigned storage URL. */
+export type StoragePresignOperation = "get" | "put"
+
+/** Mechanical constraints applied while minting a presigned URL. */
+export interface StoragePresignOptions {
+  readonly expiresInSeconds?: number
+  /** For PUT URLs, pin the declared MIME type. */
+  readonly contentType?: string
+  /** For PUT URLs, pin the exact request-body size. */
+  readonly contentLength?: number
+}
+
+/** A provider-minted URL and its known expiry. */
+export interface StoragePresignedUrl {
+  readonly url: string
+  readonly expiresAt?: Date
+}
+
 /**
  * A blob store keyed by string. Keys are POSIX-ish paths (`avatars/u1.png`); every adapter rejects unsafe
  * keys (absolute, `..` traversal, NUL, backslash) so a key valid in one adapter is valid in all. All
@@ -48,6 +78,26 @@ export interface StorageAdapter {
   list(options?: ListOptions): Promise<string[]>
 }
 
+/** Optional cursor-listing capability. Kept out of {@link StorageAdapter} for simple stores. */
+export interface PagedStorageAdapter extends StorageAdapter {
+  listPage(options?: StorageListPageOptions): Promise<StorageListPage>
+}
+
+/** Optional provider-side URL-signing capability. Asset sensitivity and TTL policy stay with callers. */
+export interface PresignableStorageAdapter extends StorageAdapter {
+  presign(
+    key: string,
+    operation: StoragePresignOperation,
+    options?: StoragePresignOptions,
+  ): Promise<StoragePresignedUrl>
+}
+
+/** Optional server-side copy/move capability. */
+export interface MovableStorageAdapter extends StorageAdapter {
+  copy(sourceKey: string, destinationKey: string): Promise<void>
+  move(sourceKey: string, destinationKey: string): Promise<void>
+}
+
 /** Normalize any accepted payload to bytes. */
 export function toBytes(data: StorageData): Uint8Array {
   if (typeof data === "string") return new TextEncoder().encode(data)