nuxt-filer 0.0.11 → 0.0.13

package/README.md

@@ -136,6 +136,30 @@ const res = await transformImage(buffer, { width: 64, format: 'webp' })
 | `external?.push(groupId, id, data, meta)` | Push to external system |
 | `external?.pull(groupId, ref)` | Pull from external system |
 
+### Serving raw files with `sendStoredFile()`
+
+The IPX route serves **images** with full HTTP caching. For everything else — original PDFs, non-image downloads, the unprocessed bytes of any file — `sendStoredFile()` streams a stored file back through an H3 event with the same revalidation story.
+
+```ts
+// server/api/files/[groupId]/[id].get.ts
+export default defineEventHandler((event) => {
+  const { groupId, id } = getRouterParams(event)
+  return sendStoredFile(event, groupId, id) // 404 if missing
+})
+```
+
+It sets `content-type` from `meta.mime`, a `content-disposition` filename from `meta.name`, and `cache-control` / `last-modified` / `etag`, honoring `if-modified-since` / `if-none-match` (`304`) — just like the IPX route. `HEAD` requests get the headers without a body.
+
+```ts
+sendStoredFile(event, groupId, id, {
+  disposition: 'attachment', // force a download ('inline' is the default)
+  filename: 'invoice-2026.pdf', // override the download name (default: meta.name)
+  maxAge: 3600, // cache-control max-age in seconds (default: 1 year; 0 = no-cache)
+})
+```
+
+`sendStoredFile` is auto-imported in your server routes — no need to import it.
+
 ## `@nuxt/image` Integration
 
 If `@nuxt/image` is installed alongside `nuxt-filer`, the module automatically registers a `filer` image provider and an IPX endpoint that pulls bytes from your storage provider, runs them through Sharp, and returns the result.
@@ -169,9 +193,42 @@ filer: {
 
 `@nuxt/image` and `ipx` are declared as optional peer dependencies — they only need to be installed if you want to use this integration.
 
+## S3 storage
+
+For durable object storage (AWS S3, Cloudflare R2, MinIO, …) use the built-in
+`createS3Provider`. It stores each file as a data object plus a JSON metadata
+sidecar, and — unlike unstorage's generic `s3` driver — `list()`/`findByMeta()`
+use real S3 prefix listing with continuation pagination, so a group stays
+correctly scoped even inside a large or shared bucket.
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['nuxt-filer'],
+  filer: { provider: 'custom' },
+})
+```
+
+```ts
+// server/plugins/file-provider.ts
+export default defineNitroPlugin(() => {
+  const { s3 } = useRuntimeConfig()
+  setFileStorageProvider(createS3Provider({
+    accessKeyId: s3.accessKeyId,
+    secretAccessKey: s3.secretAccessKey,
+    endpoint: s3.endpoint,   // e.g. https://<acct>.r2.cloudflarestorage.com
+    region: s3.region,       // R2: 'auto'
+    bucket: s3.bucket,
+    // prefix: 'media/',      // optional: namespace within a shared bucket
+  }))
+})
+```
+
+> `createS3Provider` requires the optional [`aws4fetch`](https://github.com/mhart/aws4fetch) peer dependency (`npm i aws4fetch`). Pass a custom `client` to use a different transport or to unit-test without network.
+
 ## Custom Provider
 
-For advanced use cases (database-backed metadata, S3 storage, external file sync), implement the `FileStorageProvider` interface and register it in a Nitro plugin:
+For advanced use cases (database-backed metadata, external file sync), implement the `FileStorageProvider` interface and register it in a Nitro plugin:
 
 ```ts
 // nuxt.config.ts

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-filer",
   "configKey": "filer",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -22,6 +22,10 @@ const module = defineNuxtModule({
       {
         name: "transformImage",
         from: resolver.resolve("./runtime/server/utils/image")
+      },
+      {
+        name: "sendStoredFile",
+        from: resolver.resolve("./runtime/server/utils/send")
       }
     ]);
     const providerSpecifier = resolver.resolve("./runtime/server/provider");
@@ -33,6 +37,10 @@ const module = defineNuxtModule({
       {
         name: "createUnstorageProvider",
         from: resolver.resolve("./runtime/server/providers/unstorage")
+      },
+      {
+        name: "createS3Provider",
+        from: resolver.resolve("./runtime/server/providers/s3")
       }
     ]);
     const typesSpecifier = "nuxt-filer/runtime/types";

package/dist/runtime/server/providers/s3.d.ts

@@ -0,0 +1,40 @@
+import type { FileStorageProvider } from '../../../runtime/types.js';
+/**
+ * Minimal S3 object-store surface the provider needs. Abstracted so the
+ * provider can be unit-tested with an in-memory fake (pass `client`), and so
+ * the real implementation (aws4fetch) stays isolated.
+ *
+ * `listKeys` MUST list with a server-side prefix and paginate through every
+ * page — that's the whole point of this provider over unstorage's generic s3
+ * driver, which lists the bucket root and caps at 1000 keys.
+ */
+export interface S3Client {
+    put(key: string, body: Buffer | Uint8Array, contentType?: string): Promise<void>;
+    get(key: string): Promise<Buffer | null>;
+    head(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    listKeys(prefix: string): AsyncGenerator<string, void, unknown>;
+}
+export interface S3ProviderOptions {
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    /** S3 API endpoint, e.g. https://<acct>.r2.cloudflarestorage.com */
+    endpoint?: string;
+    /** SigV4 region. R2 uses 'auto' (the default). */
+    region?: string;
+    bucket?: string;
+    /** Optional key prefix to namespace files within a shared bucket. */
+    prefix?: string;
+    /** Inject a custom S3 client (testing or alternative transport). */
+    client?: S3Client;
+}
+/**
+ * S3-backed {@link FileStorageProvider}. Binary data and a JSON metadata
+ * sidecar are stored as separate objects per file, mirroring the built-in
+ * unstorage provider's semantics — but `list`/`findByMeta` use real S3 prefix
+ * listing with continuation pagination, so a group is correctly scoped even
+ * inside a large shared bucket.
+ *
+ * Key layout: `${prefix}${groupId}/data/${id}` and `${prefix}${groupId}/meta/${id}`.
+ */
+export declare function createS3Provider(options: S3ProviderOptions): FileStorageProvider;

package/dist/runtime/server/providers/s3.js

@@ -0,0 +1,215 @@
+import { randomUUID } from "node:crypto";
+export function createS3Provider(options) {
+  const prefix = options.prefix ? options.prefix.replace(/\/+$/, "") + "/" : "";
+  let clientPromise;
+  const getClient = () => clientPromise ??= options.client ? Promise.resolve(options.client) : createAwsS3Client(options);
+  const dataKey = (groupId, id) => `${prefix}${groupId}/data/${id}`;
+  const metaKey = (groupId, id) => `${prefix}${groupId}/meta/${id}`;
+  const metaPrefix = (groupId) => `${prefix}${groupId}/meta/`;
+  const groupIdFromMetaKey = (key) => {
+    const rel = key.slice(prefix.length);
+    return rel.slice(0, rel.lastIndexOf("/meta/"));
+  };
+  const idFromKey = (key) => key.slice(key.lastIndexOf("/") + 1);
+  const readMeta = async (client, key) => {
+    const raw = await client.get(key);
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw.toString("utf8"));
+    } catch {
+      return null;
+    }
+  };
+  const toStoredFile = (id, groupId, meta, data) => ({
+    id,
+    groupId,
+    data: data ?? void 0,
+    meta: stripInternal(meta),
+    createdAt: meta?._createdAt ? new Date(meta._createdAt) : void 0,
+    updatedAt: meta?._updatedAt ? new Date(meta._updatedAt) : void 0
+  });
+  return {
+    async create(groupId, data, meta) {
+      const client = await getClient();
+      const id = randomUUID();
+      await client.put(dataKey(groupId, id), data, meta?.mime);
+      if (meta) {
+        const now = (/* @__PURE__ */ new Date()).toISOString();
+        await client.put(
+          metaKey(groupId, id),
+          Buffer.from(JSON.stringify({ ...meta, _createdAt: now, _updatedAt: now })),
+          "application/json"
+        );
+      }
+      return { id };
+    },
+    async get(groupId, id) {
+      const client = await getClient();
+      const [data, meta] = await Promise.all([
+        client.get(dataKey(groupId, id)),
+        readMeta(client, metaKey(groupId, id))
+      ]);
+      if (!data && !meta) return null;
+      return toStoredFile(id, groupId, meta, data ?? void 0);
+    },
+    async getData(groupId, id) {
+      return (await getClient()).get(dataKey(groupId, id));
+    },
+    async getMeta(id) {
+      const client = await getClient();
+      for await (const key of client.listKeys(prefix)) {
+        if (key.endsWith(`/meta/${id}`)) {
+          return stripInternal(await readMeta(client, key));
+        }
+      }
+      return null;
+    },
+    async list(groupId) {
+      const client = await getClient();
+      const files = [];
+      for await (const key of client.listKeys(metaPrefix(groupId))) {
+        const meta = await readMeta(client, key);
+        if (!meta) continue;
+        files.push(toStoredFile(idFromKey(key), groupId, meta));
+      }
+      return files;
+    },
+    async update(id, meta) {
+      const client = await getClient();
+      for await (const key of client.listKeys(prefix)) {
+        if (!key.endsWith(`/meta/${id}`)) continue;
+        const existing = await readMeta(client, key) ?? {};
+        await client.put(
+          key,
+          Buffer.from(
+            JSON.stringify({ ...existing, ...meta, _updatedAt: (/* @__PURE__ */ new Date()).toISOString() })
+          ),
+          "application/json"
+        );
+        return;
+      }
+      throw new Error(`File metadata not found: ${id}`);
+    },
+    async remove(groupId, id) {
+      const client = await getClient();
+      await Promise.all([
+        client.delete(dataKey(groupId, id)),
+        client.delete(metaKey(groupId, id))
+      ]);
+    },
+    async clear(groupId) {
+      const client = await getClient();
+      for await (const key of client.listKeys(`${prefix}${groupId}/`)) {
+        await client.delete(key);
+      }
+    },
+    async has(groupId, id) {
+      return (await getClient()).head(dataKey(groupId, id));
+    },
+    async findByMeta(filter) {
+      const client = await getClient();
+      const scanPrefix = filter.groupId ? metaPrefix(filter.groupId) : prefix;
+      for await (const key of client.listKeys(scanPrefix)) {
+        if (!key.includes("/meta/")) continue;
+        const meta = await readMeta(client, key);
+        if (!meta) continue;
+        if (meta[filter.key] === filter.value) {
+          return toStoredFile(idFromKey(key), groupIdFromMetaKey(key), meta);
+        }
+      }
+      return null;
+    }
+  };
+}
+function stripInternal(meta) {
+  if (!meta) return { name: "", mime: "", type: "", version: 0 };
+  const { _createdAt, _updatedAt, ...rest } = meta;
+  return rest;
+}
+async function createAwsS3Client(options) {
+  for (const key of ["accessKeyId", "secretAccessKey", "endpoint", "bucket"]) {
+    if (!options[key]) {
+      throw new Error(`[nuxt-filer] createS3Provider: missing required option "${key}"`);
+    }
+  }
+  let AwsClient;
+  try {
+    ({ AwsClient } = await import("aws4fetch"));
+  } catch {
+    throw new Error(
+      '[nuxt-filer] createS3Provider needs the optional "aws4fetch" dependency. Install it: npm i aws4fetch'
+    );
+  }
+  const aws = new AwsClient({
+    service: "s3",
+    accessKeyId: options.accessKeyId,
+    secretAccessKey: options.secretAccessKey,
+    region: options.region || "auto"
+  });
+  const base = `${options.endpoint.replace(/\/+$/, "")}/${options.bucket}`;
+  const objectUrl = (key) => `${base}/${key.split("/").map(encodeURIComponent).join("/")}`;
+  const signedFetch = (url, init) => aws.sign(url, init).then((req) => fetch(req));
+  return {
+    async put(key, body, contentType) {
+      const res = await signedFetch(objectUrl(key), {
+        method: "PUT",
+        body,
+        headers: contentType ? { "content-type": contentType } : void 0
+      });
+      if (!res.ok) {
+        throw new Error(`[nuxt-filer] S3 PUT ${key}: ${res.status} ${res.statusText}`);
+      }
+    },
+    async get(key) {
+      const res = await signedFetch(objectUrl(key));
+      if (res.status === 404) return null;
+      if (!res.ok) {
+        throw new Error(`[nuxt-filer] S3 GET ${key}: ${res.status} ${res.statusText}`);
+      }
+      return Buffer.from(await res.arrayBuffer());
+    },
+    async head(key) {
+      const res = await signedFetch(objectUrl(key), { method: "HEAD" });
+      if (res.status === 404) return false;
+      if (!res.ok) {
+        throw new Error(`[nuxt-filer] S3 HEAD ${key}: ${res.status} ${res.statusText}`);
+      }
+      return true;
+    },
+    async delete(key) {
+      const res = await signedFetch(objectUrl(key), { method: "DELETE" });
+      if (!res.ok && res.status !== 404) {
+        throw new Error(`[nuxt-filer] S3 DELETE ${key}: ${res.status} ${res.statusText}`);
+      }
+    },
+    async *listKeys(keyPrefix) {
+      let token;
+      do {
+        const url = new URL(base);
+        url.searchParams.set("list-type", "2");
+        if (keyPrefix) url.searchParams.set("prefix", keyPrefix);
+        if (token) url.searchParams.set("continuation-token", token);
+        const res = await signedFetch(url.toString());
+        if (!res.ok) {
+          throw new Error(`[nuxt-filer] S3 LIST ${keyPrefix}: ${res.status} ${res.statusText}`);
+        }
+        const xml = await res.text();
+        for (const key of parseListKeys(xml)) yield key;
+        token = matchTag(xml, "IsTruncated") === "true" ? matchTag(xml, "NextContinuationToken") : void 0;
+      } while (token);
+    }
+  };
+}
+function parseListKeys(xml) {
+  const keys = [];
+  const re = /<Key>([\s\S]*?)<\/Key>/g;
+  let match;
+  while (match = re.exec(xml)) keys.push(decodeXml(match[1]));
+  return keys;
+}
+function matchTag(xml, tag) {
+  return xml.match(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`))?.[1];
+}
+function decodeXml(value) {
+  return value.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, "&");
+}

package/dist/runtime/server/utils/send.d.ts

@@ -0,0 +1,33 @@
+import { type H3Event } from 'h3';
+import type { StoredFile } from '../../../runtime/types.js';
+export type { StoredFile };
+export interface SendStoredFileOptions {
+    /**
+     * `content-disposition` type. `'inline'` (the default) lets the browser
+     * render the file in place; `'attachment'` forces a download.
+     */
+    disposition?: 'inline' | 'attachment';
+    /** Override the download filename. Defaults to the stored `meta.name`. */
+    filename?: string;
+    /**
+     * `cache-control` max-age in seconds. Default: one year — matching the IPX
+     * route. Pass `0` to mark the response uncacheable.
+     */
+    maxAge?: number;
+}
+/**
+ * Stream a stored file back through an H3 event with the same HTTP revalidation
+ * story as the IPX image route: `content-type` from `meta.mime`, a
+ * `content-disposition` filename from `meta.name`, and
+ * `cache-control` / `last-modified` / `etag` honoring `if-modified-since` /
+ * `if-none-match` (304). Throws a 404 when the file does not exist.
+ *
+ * ```ts
+ * // server/api/files/[groupId]/[id].get.ts
+ * export default defineEventHandler((event) => {
+ *   const { groupId, id } = getRouterParams(event)
+ *   return sendStoredFile(event, groupId, id)
+ * })
+ * ```
+ */
+export declare function sendStoredFile(event: H3Event, groupId: string, id: string, options?: SendStoredFileOptions): Promise<Buffer | null>;

package/dist/runtime/server/utils/send.js

@@ -0,0 +1,64 @@
+import {
+  getRequestHeader,
+  setResponseHeader,
+  setResponseStatus,
+  createError
+} from "h3";
+import { useFileStorageProvider } from "../provider.js";
+const DEFAULT_MAX_AGE = 60 * 60 * 24 * 365;
+function fileMtime(file) {
+  return file.updatedAt ?? file.createdAt ?? void 0;
+}
+function cacheValidators(file) {
+  const mtime = fileMtime(file);
+  if (!mtime) return {};
+  return { etag: `W/"${mtime.getTime().toString(16)}"`, lastModified: mtime };
+}
+function contentDisposition(type, name) {
+  const asciiName = name.replace(/[^\x20-\x7E]|["\\]/g, "_");
+  return `${type}; filename="${asciiName}"; filename*=UTF-8''${encodeURIComponent(name)}`;
+}
+export async function sendStoredFile(event, groupId, id, options = {}) {
+  const provider = useFileStorageProvider();
+  const file = await provider.get(groupId, id);
+  if (!file) {
+    throw createError({ statusCode: 404, statusMessage: "File not found" });
+  }
+  const maxAge = options.maxAge ?? DEFAULT_MAX_AGE;
+  const { etag, lastModified } = cacheValidators(file);
+  setResponseHeader(
+    event,
+    "cache-control",
+    maxAge > 0 ? `public, max-age=${maxAge}` : "no-cache"
+  );
+  if (etag) setResponseHeader(event, "etag", etag);
+  if (lastModified)
+    setResponseHeader(event, "last-modified", lastModified.toUTCString());
+  const ifNoneMatch = getRequestHeader(event, "if-none-match");
+  const ifModifiedSince = getRequestHeader(event, "if-modified-since");
+  const notModified = etag ? ifNoneMatch === etag : !!lastModified && !!ifModifiedSince && lastModified.getTime() <= Date.parse(ifModifiedSince);
+  if (notModified) {
+    setResponseStatus(event, 304);
+    return null;
+  }
+  setResponseHeader(
+    event,
+    "content-type",
+    file.meta.mime || "application/octet-stream"
+  );
+  setResponseHeader(
+    event,
+    "content-disposition",
+    contentDisposition(
+      options.disposition ?? "inline",
+      options.filename ?? file.meta.name
+    )
+  );
+  const data = await provider.getData(groupId, id);
+  if (!data) {
+    throw createError({ statusCode: 404, statusMessage: "File not found" });
+  }
+  setResponseHeader(event, "content-length", data.length);
+  if (event.method === "HEAD") return null;
+  return data;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-filer",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "File storage module for Nuxt",
   "repository": {
     "type": "git",
@@ -36,17 +36,6 @@
     "dist",
     "src/runtime"
   ],
-  "scripts": {
-    "prepack": "nuxt-module-build build",
-    "dev": "npm run dev:prepare && nuxi dev playground",
-    "dev:build": "nuxi build playground",
-    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
-    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
-    "lint": "eslint .",
-    "test": "vitest run",
-    "test:watch": "vitest watch",
-    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
-  },
   "dependencies": {
     "@nuxt/kit": "^4.4.2",
     "consola": "^3.4.2",
@@ -56,6 +45,7 @@
     "@nuxt/devtools": "^3.2.4",
     "@nuxt/eslint-config": "^1.15.2",
     "@nuxt/image": "^2.0.0",
+    "aws4fetch": "^1.0.20",
     "@nuxt/module-builder": "^1.0.2",
     "@nuxt/schema": "^4.4.2",
     "@nuxt/test-utils": "^4.0.0",
@@ -71,6 +61,7 @@
   },
   "peerDependencies": {
     "@nuxt/image": "^2.0.0",
+    "aws4fetch": "^1.0.20",
     "ipx": "^3.0.0",
     "sharp": "^0.33.0 || ^0.34.0"
   },
@@ -78,6 +69,9 @@
     "@nuxt/image": {
       "optional": true
     },
+    "aws4fetch": {
+      "optional": true
+    },
     "ipx": {
       "optional": true
     },
@@ -85,11 +79,14 @@
       "optional": true
     }
   },
-  "packageManager": "pnpm@10.33.0",
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild",
-      "sharp"
-    ]
+  "scripts": {
+    "dev": "npm run dev:prepare && nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
   }
-}
+}

package/src/runtime/server/providers/s3.ts

@@ -0,0 +1,314 @@
+import { randomUUID } from 'node:crypto';
+import type {
+  FileStorageProvider,
+  FileMeta,
+  StoredFile,
+} from '../../../runtime/types';
+
+/**
+ * Minimal S3 object-store surface the provider needs. Abstracted so the
+ * provider can be unit-tested with an in-memory fake (pass `client`), and so
+ * the real implementation (aws4fetch) stays isolated.
+ *
+ * `listKeys` MUST list with a server-side prefix and paginate through every
+ * page — that's the whole point of this provider over unstorage's generic s3
+ * driver, which lists the bucket root and caps at 1000 keys.
+ */
+export interface S3Client {
+  put(key: string, body: Buffer | Uint8Array, contentType?: string): Promise<void>;
+  get(key: string): Promise<Buffer | null>;
+  head(key: string): Promise<boolean>;
+  delete(key: string): Promise<void>;
+  listKeys(prefix: string): AsyncGenerator<string, void, unknown>;
+}
+
+export interface S3ProviderOptions {
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  /** S3 API endpoint, e.g. https://<acct>.r2.cloudflarestorage.com */
+  endpoint?: string;
+  /** SigV4 region. R2 uses 'auto' (the default). */
+  region?: string;
+  bucket?: string;
+  /** Optional key prefix to namespace files within a shared bucket. */
+  prefix?: string;
+  /** Inject a custom S3 client (testing or alternative transport). */
+  client?: S3Client;
+}
+
+type InternalMeta = FileMeta & { _createdAt?: string; _updatedAt?: string };
+
+/**
+ * S3-backed {@link FileStorageProvider}. Binary data and a JSON metadata
+ * sidecar are stored as separate objects per file, mirroring the built-in
+ * unstorage provider's semantics — but `list`/`findByMeta` use real S3 prefix
+ * listing with continuation pagination, so a group is correctly scoped even
+ * inside a large shared bucket.
+ *
+ * Key layout: `${prefix}${groupId}/data/${id}` and `${prefix}${groupId}/meta/${id}`.
+ */
+export function createS3Provider(options: S3ProviderOptions): FileStorageProvider {
+  const prefix = options.prefix ? options.prefix.replace(/\/+$/, '') + '/' : '';
+
+  let clientPromise: Promise<S3Client> | undefined;
+  const getClient = () =>
+    (clientPromise ??= options.client
+      ? Promise.resolve(options.client)
+      : createAwsS3Client(options));
+
+  const dataKey = (groupId: string, id: string) => `${prefix}${groupId}/data/${id}`;
+  const metaKey = (groupId: string, id: string) => `${prefix}${groupId}/meta/${id}`;
+  const metaPrefix = (groupId: string) => `${prefix}${groupId}/meta/`;
+
+  /** `${prefix}${groupId}/meta/${id}` → groupId (groups may contain '/'). */
+  const groupIdFromMetaKey = (key: string) => {
+    const rel = key.slice(prefix.length);
+    return rel.slice(0, rel.lastIndexOf('/meta/'));
+  };
+  const idFromKey = (key: string) => key.slice(key.lastIndexOf('/') + 1);
+
+  const readMeta = async (client: S3Client, key: string): Promise<InternalMeta | null> => {
+    const raw = await client.get(key);
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw.toString('utf8')) as InternalMeta;
+    } catch {
+      return null;
+    }
+  };
+
+  const toStoredFile = (
+    id: string,
+    groupId: string,
+    meta: InternalMeta | null,
+    data?: Buffer,
+  ): StoredFile => ({
+    id,
+    groupId,
+    data: data ?? undefined,
+    meta: stripInternal(meta),
+    createdAt: meta?._createdAt ? new Date(meta._createdAt) : undefined,
+    updatedAt: meta?._updatedAt ? new Date(meta._updatedAt) : undefined,
+  });
+
+  return {
+    async create(groupId, data, meta) {
+      const client = await getClient();
+      const id = randomUUID();
+
+      await client.put(dataKey(groupId, id), data, meta?.mime);
+
+      if (meta) {
+        const now = new Date().toISOString();
+        await client.put(
+          metaKey(groupId, id),
+          Buffer.from(JSON.stringify({ ...meta, _createdAt: now, _updatedAt: now })),
+          'application/json',
+        );
+      }
+
+      return { id };
+    },
+
+    async get(groupId, id) {
+      const client = await getClient();
+      const [data, meta] = await Promise.all([
+        client.get(dataKey(groupId, id)),
+        readMeta(client, metaKey(groupId, id)),
+      ]);
+      if (!data && !meta) return null;
+      return toStoredFile(id, groupId, meta, data ?? undefined);
+    },
+
+    async getData(groupId, id) {
+      return (await getClient()).get(dataKey(groupId, id));
+    },
+
+    async getMeta(id) {
+      // No groupId: scan meta objects (bounded by `prefix` when set). The
+      // serving path uses get/getData (which carry a groupId), so this is the
+      // only non-group-scoped lookup.
+      const client = await getClient();
+      for await (const key of client.listKeys(prefix)) {
+        if (key.endsWith(`/meta/${id}`)) {
+          return stripInternal(await readMeta(client, key));
+        }
+      }
+      return null;
+    },
+
+    async list(groupId) {
+      const client = await getClient();
+      const files: StoredFile[] = [];
+      for await (const key of client.listKeys(metaPrefix(groupId))) {
+        const meta = await readMeta(client, key);
+        if (!meta) continue;
+        files.push(toStoredFile(idFromKey(key), groupId, meta));
+      }
+      return files;
+    },
+
+    async update(id, meta) {
+      const client = await getClient();
+      for await (const key of client.listKeys(prefix)) {
+        if (!key.endsWith(`/meta/${id}`)) continue;
+        const existing = (await readMeta(client, key)) ?? ({} as InternalMeta);
+        await client.put(
+          key,
+          Buffer.from(
+            JSON.stringify({ ...existing, ...meta, _updatedAt: new Date().toISOString() }),
+          ),
+          'application/json',
+        );
+        return;
+      }
+      throw new Error(`File metadata not found: ${id}`);
+    },
+
+    async remove(groupId, id) {
+      const client = await getClient();
+      await Promise.all([
+        client.delete(dataKey(groupId, id)),
+        client.delete(metaKey(groupId, id)),
+      ]);
+    },
+
+    async clear(groupId) {
+      const client = await getClient();
+      for await (const key of client.listKeys(`${prefix}${groupId}/`)) {
+        await client.delete(key);
+      }
+    },
+
+    async has(groupId, id) {
+      return (await getClient()).head(dataKey(groupId, id));
+    },
+
+    async findByMeta(filter) {
+      const client = await getClient();
+      const scanPrefix = filter.groupId ? metaPrefix(filter.groupId) : prefix;
+      for await (const key of client.listKeys(scanPrefix)) {
+        if (!key.includes('/meta/')) continue;
+        const meta = await readMeta(client, key);
+        if (!meta) continue;
+        if (meta[filter.key] === filter.value) {
+          return toStoredFile(idFromKey(key), groupIdFromMetaKey(key), meta);
+        }
+      }
+      return null;
+    },
+  };
+}
+
+function stripInternal(meta: InternalMeta | null): FileMeta {
+  if (!meta) return { name: '', mime: '', type: '', version: 0 };
+  const { _createdAt, _updatedAt, ...rest } = meta;
+  return rest as FileMeta;
+}
+
+/** Default {@link S3Client} backed by aws4fetch (SigV4 over fetch). */
+async function createAwsS3Client(options: S3ProviderOptions): Promise<S3Client> {
+  for (const key of ['accessKeyId', 'secretAccessKey', 'endpoint', 'bucket'] as const) {
+    if (!options[key]) {
+      throw new Error(`[nuxt-filer] createS3Provider: missing required option "${key}"`);
+    }
+  }
+
+  let AwsClient: typeof import('aws4fetch').AwsClient;
+  try {
+    ({ AwsClient } = await import('aws4fetch'));
+  } catch {
+    throw new Error(
+      '[nuxt-filer] createS3Provider needs the optional "aws4fetch" dependency. Install it: npm i aws4fetch',
+    );
+  }
+
+  const aws = new AwsClient({
+    service: 's3',
+    accessKeyId: options.accessKeyId!,
+    secretAccessKey: options.secretAccessKey!,
+    region: options.region || 'auto',
+  });
+
+  const base = `${options.endpoint!.replace(/\/+$/, '')}/${options.bucket}`;
+  const objectUrl = (key: string) =>
+    `${base}/${key.split('/').map(encodeURIComponent).join('/')}`;
+
+  const signedFetch = (url: string, init?: RequestInit) =>
+    aws.sign(url, init).then((req) => fetch(req));
+
+  return {
+    async put(key, body, contentType) {
+      const res = await signedFetch(objectUrl(key), {
+        method: 'PUT',
+        body: body as BodyInit,
+        headers: contentType ? { 'content-type': contentType } : undefined,
+      });
+      if (!res.ok) {
+        throw new Error(`[nuxt-filer] S3 PUT ${key}: ${res.status} ${res.statusText}`);
+      }
+    },
+    async get(key) {
+      const res = await signedFetch(objectUrl(key));
+      if (res.status === 404) return null;
+      if (!res.ok) {
+        throw new Error(`[nuxt-filer] S3 GET ${key}: ${res.status} ${res.statusText}`);
+      }
+      return Buffer.from(await res.arrayBuffer());
+    },
+    async head(key) {
+      const res = await signedFetch(objectUrl(key), { method: 'HEAD' });
+      if (res.status === 404) return false;
+      if (!res.ok) {
+        throw new Error(`[nuxt-filer] S3 HEAD ${key}: ${res.status} ${res.statusText}`);
+      }
+      return true;
+    },
+    async delete(key) {
+      const res = await signedFetch(objectUrl(key), { method: 'DELETE' });
+      if (!res.ok && res.status !== 404) {
+        throw new Error(`[nuxt-filer] S3 DELETE ${key}: ${res.status} ${res.statusText}`);
+      }
+    },
+    async *listKeys(keyPrefix) {
+      let token: string | undefined;
+      do {
+        const url = new URL(base);
+        url.searchParams.set('list-type', '2');
+        if (keyPrefix) url.searchParams.set('prefix', keyPrefix);
+        if (token) url.searchParams.set('continuation-token', token);
+
+        const res = await signedFetch(url.toString());
+        if (!res.ok) {
+          throw new Error(`[nuxt-filer] S3 LIST ${keyPrefix}: ${res.status} ${res.statusText}`);
+        }
+        const xml = await res.text();
+        for (const key of parseListKeys(xml)) yield key;
+
+        token =
+          matchTag(xml, 'IsTruncated') === 'true' ? matchTag(xml, 'NextContinuationToken') : undefined;
+      } while (token);
+    },
+  };
+}
+
+function parseListKeys(xml: string): string[] {
+  const keys: string[] = [];
+  const re = /<Key>([\s\S]*?)<\/Key>/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(xml))) keys.push(decodeXml(match[1]!));
+  return keys;
+}
+
+function matchTag(xml: string, tag: string): string | undefined {
+  return xml.match(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`))?.[1];
+}
+
+function decodeXml(value: string): string {
+  return value
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, '&');
+}

package/src/runtime/server/utils/send.ts

@@ -0,0 +1,135 @@
+import {
+  type H3Event,
+  getRequestHeader,
+  setResponseHeader,
+  setResponseStatus,
+  createError,
+} from 'h3';
+import type { StoredFile } from '../../../runtime/types';
+import { useFileStorageProvider } from '../provider';
+
+export type { StoredFile };
+
+export interface SendStoredFileOptions {
+  /**
+   * `content-disposition` type. `'inline'` (the default) lets the browser
+   * render the file in place; `'attachment'` forces a download.
+   */
+  disposition?: 'inline' | 'attachment';
+  /** Override the download filename. Defaults to the stored `meta.name`. */
+  filename?: string;
+  /**
+   * `cache-control` max-age in seconds. Default: one year — matching the IPX
+   * route. Pass `0` to mark the response uncacheable.
+   */
+  maxAge?: number;
+}
+
+const DEFAULT_MAX_AGE = 60 * 60 * 24 * 365; // 1 year, matching the IPX route.
+
+/** The mtime the IPX route also uses: prefer `updatedAt`, fall back to `createdAt`. */
+function fileMtime(file: StoredFile): Date | undefined {
+  return file.updatedAt ?? file.createdAt ?? undefined;
+}
+
+/**
+ * Build a weak validator from the file's mtime so revalidation can be answered
+ * without reading the bytes back. Mirrors the IPX route, which keys its etag /
+ * last-modified off the same mtime.
+ */
+function cacheValidators(file: StoredFile): {
+  etag?: string;
+  lastModified?: Date;
+} {
+  const mtime = fileMtime(file);
+  if (!mtime) return {};
+  return { etag: `W/"${mtime.getTime().toString(16)}"`, lastModified: mtime };
+}
+
+/** RFC 6266 `content-disposition` value with an ASCII fallback + UTF-8 form. */
+function contentDisposition(type: string, name: string): string {
+  // Strip anything outside printable ASCII (plus quote/backslash) for the
+  // legacy `filename=`; the `filename*=` form carries the real UTF-8 name.
+  const asciiName = name.replace(/[^\x20-\x7E]|["\\]/g, '_');
+  return `${type}; filename="${asciiName}"; filename*=UTF-8''${encodeURIComponent(name)}`;
+}
+
+/**
+ * Stream a stored file back through an H3 event with the same HTTP revalidation
+ * story as the IPX image route: `content-type` from `meta.mime`, a
+ * `content-disposition` filename from `meta.name`, and
+ * `cache-control` / `last-modified` / `etag` honoring `if-modified-since` /
+ * `if-none-match` (304). Throws a 404 when the file does not exist.
+ *
+ * ```ts
+ * // server/api/files/[groupId]/[id].get.ts
+ * export default defineEventHandler((event) => {
+ *   const { groupId, id } = getRouterParams(event)
+ *   return sendStoredFile(event, groupId, id)
+ * })
+ * ```
+ */
+export async function sendStoredFile(
+  event: H3Event,
+  groupId: string,
+  id: string,
+  options: SendStoredFileOptions = {}
+): Promise<Buffer | null> {
+  const provider = useFileStorageProvider();
+
+  const file = await provider.get(groupId, id);
+  if (!file) {
+    throw createError({ statusCode: 404, statusMessage: 'File not found' });
+  }
+
+  const maxAge = options.maxAge ?? DEFAULT_MAX_AGE;
+  const { etag, lastModified } = cacheValidators(file);
+
+  setResponseHeader(
+    event,
+    'cache-control',
+    maxAge > 0 ? `public, max-age=${maxAge}` : 'no-cache'
+  );
+  if (etag) setResponseHeader(event, 'etag', etag);
+  if (lastModified)
+    setResponseHeader(event, 'last-modified', lastModified.toUTCString());
+
+  // Conditional request handling — answer 304 before touching the bytes.
+  const ifNoneMatch = getRequestHeader(event, 'if-none-match');
+  const ifModifiedSince = getRequestHeader(event, 'if-modified-since');
+  const notModified = etag
+    ? ifNoneMatch === etag
+    : !!lastModified
+      && !!ifModifiedSince
+      && lastModified.getTime() <= Date.parse(ifModifiedSince);
+  if (notModified) {
+    setResponseStatus(event, 304);
+    return null;
+  }
+
+  setResponseHeader(
+    event,
+    'content-type',
+    file.meta.mime || 'application/octet-stream'
+  );
+  setResponseHeader(
+    event,
+    'content-disposition',
+    contentDisposition(
+      options.disposition ?? 'inline',
+      options.filename ?? file.meta.name
+    )
+  );
+
+  const data = await provider.getData(groupId, id);
+  if (!data) {
+    throw createError({ statusCode: 404, statusMessage: 'File not found' });
+  }
+
+  setResponseHeader(event, 'content-length', data.length);
+
+  // HEAD requests get the full header set but no body.
+  if (event.method === 'HEAD') return null;
+
+  return data;
+}