davepi-plugin-object-storage 0.1.0

package/README.md

@@ -0,0 +1,267 @@
+# davepi-plugin-object-storage
+
+Presigned-URL file uploads for [dAvePi][davepi]. Auto-registers a generic `file` schema, mounts upload-url / complete / download-url routes that hand the client a presigned URL so bytes travel **client → bucket** without proxying through the API server. Pluggable backend supports AWS S3, Cloudflare R2, MinIO, and Google Cloud Storage.
+
+[davepi]: https://docs.davepi.dev
+
+## Why this plugin (vs. the in-tree `type: 'File'` field)
+
+The framework already ships a per-field, server-proxied upload pipeline via [`type: 'File'`](https://docs.davepi.dev/features/files/). That covers small attachments (avatars, document scans, logos). This plugin solves a different shape:
+
+- **Big files.** Multi-GB uploads can't ride a multer multipart request — and on serverless (Lambda ~6 MB, Vercel ~4.5 MB) they can't ride the request body at all.
+- **Direct-to-bucket.** Client → bucket is one network hop; client → API → bucket is two. With presigned URLs the API server never sees the bytes, so you don't pay egress/ingress twice or burn API CPU/RAM.
+- **Files as a first-class resource.** Instead of an embedded `FileMeta` on a parent record, this plugin gives you a real `file` collection — queryable, paginated, deletable, joinable. Right shape for media libraries, chat attachments, CMS asset pickers, anything where the file isn't anchored to one parent.
+- **R2 / MinIO / GCS.** The in-tree field is `local` or `s3` only; this plugin adds Cloudflare R2, self-hosted MinIO, and Google Cloud Storage behind a shared API.
+
+Both pipelines coexist in the same app. Use whichever fits.
+
+## Install
+
+```bash
+npm install davepi-plugin-object-storage
+```
+
+Add it to your project's `package.json` under `davepi.plugins`:
+
+```json
+{
+  "davepi": {
+    "plugins": ["davepi-plugin-object-storage"]
+  }
+}
+```
+
+Set the bucket in `.env`:
+
+```bash
+S3_BACKEND=aws            # or r2 / minio / gcs
+S3_BUCKET=my-uploads
+S3_REGION=us-east-1
+S3_ACCESS_KEY_ID=...
+S3_SECRET_ACCESS_KEY=...
+```
+
+That's it — on boot, the plugin constructs the backend adapter, registers the `file` schema, mounts the three custom routes under `/api/files`, and starts a background reaper that sweeps abandoned `pending` uploads.
+
+## Quick start
+
+```js
+// 1. Client requests a presigned PUT URL.
+const presign = await fetch('/api/files/upload-url', {
+  method:  'POST',
+  headers: { Authorization: `Bearer ${jwt}`, 'Content-Type': 'application/json' },
+  body:    JSON.stringify({
+    contentType:  'image/png',
+    originalName: 'company-logo.png',
+    size:         12345,             // optional, used for max-bytes gate
+    metadata:     { tag: 'avatar' }, // optional, free-form per-record metadata
+  }),
+}).then((r) => r.json());
+// presign = { fileId, key, url, expiresIn, contentType }
+
+// 2. Client PUTs the bytes directly to S3.
+await fetch(presign.url, {
+  method:  'PUT',
+  headers: { 'Content-Type': 'image/png' },
+  body:    blob,
+});
+
+// 3. Client tells the server the upload landed.
+await fetch(`/api/files/${presign.fileId}/complete`, {
+  method:  'POST',
+  headers: { Authorization: `Bearer ${jwt}` },
+}).then((r) => r.json());
+// → { fileId, status: 'uploaded', size, etag, ... }
+
+// 4. Later — fetch a short-lived download URL for the file.
+const dl = await fetch(`/api/files/${presign.fileId}/download-url`, {
+  headers: { Authorization: `Bearer ${jwt}` },
+}).then((r) => r.json());
+// → { fileId, url, expiresIn }
+```
+
+## Configure
+
+All config is env-driven.
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `S3_BACKEND`              | no | `aws` | One of `aws` / `r2` / `minio` / `gcs`. Picks the adapter. |
+| `S3_BUCKET`               | **yes** (else dormant) | — | Bucket name. |
+| `S3_REGION`               | yes for `aws` | from `AWS_REGION` | e.g. `us-east-1`. |
+| `S3_ENDPOINT`             | required for `r2` / `minio` | — | Custom endpoint URL. |
+| `S3_ACCESS_KEY_ID`        | dev / standalone | — | Falls back to AWS SDK default credential chain (IRSA, EC2/ECS metadata, `~/.aws/credentials`). |
+| `S3_SECRET_ACCESS_KEY`    | dev / standalone | — | Same. |
+| `S3_FORCE_PATH_STYLE`     | no | `true` for minio, else `false` | Forces `bucket-in-path` URLs. |
+| `S3_PUBLIC_BASE_URL`      | no | computed | CDN base for `publicUrl` overrides (e.g. `https://cdn.example.com`). |
+| `S3_PUT_URL_TTL_SECONDS`  | no | `300` | Lifetime of presigned PUT URLs. |
+| `S3_GET_URL_TTL_SECONDS`  | no | `600` | Lifetime of presigned GET URLs. |
+| `S3_MAX_BYTES`            | no | `52428800` (50 MiB) | Max accepted `size` for an upload-url request, and the cap re-checked at `/complete` time. |
+| `S3_ALLOWED_MIME`         | no | *(any)* | Comma-separated allowlist (e.g. `image/png,image/jpeg,application/pdf`). Wildcards like `image/*` are honoured. |
+| `S3_CASCADE_DELETE`       | no | `false` | If `true`, deleting a `file` record via `DELETE /api/v1/file/:id` also deletes the underlying object. Irreversible — opt-in. |
+| `S3_VERIFY_ON_COMPLETE`   | no | `true` | If `true`, `/complete` HEADs the object to verify presence + size before flipping status. Disable only when you trust the upload path end-to-end (e.g. a S3 event-trigger Lambda already verified it). |
+| `S3_REAP_ENABLED`         | no | `true` | Background sweep of orphaned `pending` records. Disable when you run cron separately. |
+| `S3_REAP_INTERVAL_MS`     | no | `300000` (5 min) | Sweep frequency. |
+| `S3_REAP_MULTIPLIER`      | no | `3` | A `pending` record is reaped when `createdAt + putUrlTtl × multiplier < now`. The multiplier gives slow networks comfortable headroom before cleanup. |
+| `S3_FILE_PATH`            | no | `file` | Schema path. Override if your project already has its own `file` schema. |
+| `S3_FILE_VERSION`         | no | `v1` | Schema version key. |
+| `S3_ROUTE_PREFIX`         | no | `/api/files` | Where the upload-url / complete / download-url routes mount. |
+| `GCS_PROJECT_ID`          | required for `gcs` | — | GCS project. |
+| `GCS_KEY_FILE`            | required for `gcs` | — | Path to a service-account JSON. |
+
+## What gets written
+
+The plugin registers a `file` schema. Each row carries:
+
+| Field | Description |
+|-------|-------------|
+| `userId`       | Owner. Tenant-scope predicate for every read. |
+| `accountId`    | Owner's accountId, when present on the JWT. |
+| `key`          | Storage key (`<userId>/<8-hex>/<safe-original-name>`). Write-locked at the API layer. |
+| `bucket`       | Bucket the object lives in. Write-locked. |
+| `contentType`  | MIME at upload time. Write-locked. |
+| `size`         | Bytes, validated against `S3_MAX_BYTES`. Write-locked. |
+| `status`       | `pending` → `uploaded`. Write-locked. The plugin's own routes are the only writers. |
+| `originalName` | Client-supplied filename. Writable via the regular PUT route. |
+| `metadata`     | Free-form `Mixed`. Writable via the regular PUT route so consumers can attach labels. |
+| `uploadedAt`   | Set on `/complete`. Write-locked. |
+| `etag`         | Storage etag at `/complete`. Write-locked. |
+
+Write-locks use the same sentinel-ACL trick `davepi-plugin-audit` uses for its `audit` collection — the framework's `filterWritable` strips these keys from any inbound POST / PUT body so no client can lie about where their bytes live.
+
+## Reading the file collection
+
+The `file` schema is registered like any other dAvePi schema, so every standard surface works:
+
+```bash
+# List my files
+GET /api/v1/file?status=uploaded&__sort=createdAt:desc
+
+# Read one
+GET /api/v1/file/<id>
+
+# Update metadata
+PUT /api/v1/file/<id>
+{ "metadata": { "tag": "hero-image" } }
+
+# Hard-delete (also removes the blob if S3_CASCADE_DELETE=true)
+DELETE /api/v1/file/<id>
+```
+
+GraphQL: `file`, `files`, `fileFilter`, `fileUpdateById`, `fileRemoveById` — same shape as any other dAvePi resource.
+
+## Programmatic API
+
+For schema lifecycle hooks and custom routes:
+
+```js
+const storage = require('davepi-plugin-object-storage');
+
+// Issue a presigned PUT URL from inside a hook.
+const { url, fileId } = await storage.createUploadUrl({
+  user: req.user,
+  contentType: 'image/png',
+  originalName: 'avatar.png',
+  size: 12345,
+  metadata: { kind: 'avatar' },
+});
+
+// Sign a short-lived GET URL. Returns null if the file isn't owned by
+// the caller — same tenant-isolation posture as the REST route.
+const dl = await storage.createDownloadUrl({ user: req.user, fileId });
+
+// Server-side delete (both the blob and the record).
+await storage.deleteFile({ user: req.user, fileId });
+
+// Adapter escape hatch — call provider-specific APIs directly.
+const head = await storage.adapter.headObject({ key });
+```
+
+## Bucket CORS
+
+The bucket must allow `PUT` from the origins your client runs on. Paste the JSON below into the bucket's CORS configuration.
+
+### AWS S3
+
+```json
+[
+  {
+    "AllowedHeaders": ["*"],
+    "AllowedMethods": ["PUT", "GET"],
+    "AllowedOrigins": ["https://app.example.com"],
+    "ExposeHeaders":  ["ETag"],
+    "MaxAgeSeconds":  3000
+  }
+]
+```
+
+Paste at AWS Console → S3 → Bucket → Permissions → CORS.
+
+### Cloudflare R2
+
+R2 uses the same JSON shape as AWS. Paste at Cloudflare Dashboard → R2 → Bucket → Settings → CORS Policy.
+
+```json
+[
+  {
+    "AllowedHeaders": ["content-type", "content-length"],
+    "AllowedMethods": ["PUT", "GET"],
+    "AllowedOrigins": ["https://app.example.com"],
+    "ExposeHeaders":  ["ETag"]
+  }
+]
+```
+
+### MinIO
+
+MinIO has CORS off by default; enable via the `mc` CLI:
+
+```bash
+mc admin config set local cors_allow_origin="https://app.example.com"
+mc admin service restart local
+```
+
+### Google Cloud Storage
+
+GCS uses a slightly different shape — `gsutil` (or the `gcloud storage` newer equivalent) applies CORS from a JSON file:
+
+```json
+[
+  {
+    "origin":         ["https://app.example.com"],
+    "method":         ["PUT", "GET"],
+    "responseHeader": ["Content-Type", "ETag"],
+    "maxAgeSeconds":  3000
+  }
+]
+```
+
+Apply with `gsutil cors set cors.json gs://my-bucket`.
+
+## Soft delete vs. cascade delete
+
+The `file` schema declares `softDelete: false`: a `DELETE /api/v1/file/:id` is a *hard* delete by design. File records track a mutable external resource — leaving a tombstoned row whose blob may or may not still exist in the bucket is more confusing than helpful.
+
+`S3_CASCADE_DELETE` controls whether the **storage object** is removed at the same time. Off by default because storage deletion is irreversible — a misconfigured admin endpoint that runs `DELETE` on every row would otherwise empty the bucket. Once you've validated the operator surface, flip it on.
+
+## Multi-tenant isolation
+
+The same rules as every other dAvePi resource:
+
+- Keys are namespaced by `userId` (`<userId>/<8-hex>/<safe-name>`), so a flat `aws s3 ls` already shows ownership.
+- Every route filters by `req.user.user_id`. Foreign-tenant `fileId`s return `404 NOT_FOUND` — never `403 FORBIDDEN`, so the response shape doesn't leak existence.
+- The `/complete` and `/download-url` routes refuse to issue presigned URLs for files whose `userId` doesn't match the caller.
+- The plugin's own setUp goes through `schemaLoader.moveErrorHandlerToEnd()` after mounting routes so plugin-thrown errors land in the framework's centralised `{ error: { code, message } }` shape.
+
+## Tests
+
+```bash
+cd packages/davepi-plugin-object-storage
+npm test
+```
+
+67 unit tests via `node --test` (config, key generation, AWS adapter, GCS adapter, routes, reaper, plugin setup). Plus an integration test under the framework's Jest suite (`test/plugin-object-storage-integration.test.js`) that drives a real `loadPlugins` → REST upload-url → complete → download-url flow against `mongodb-memory-server` with a mock adapter, asserting tenant isolation, mime/size allowlists, and cascade-delete behaviour.
+
+## License
+
+ISC

package/index.js

@@ -0,0 +1,326 @@
+'use strict';
+
+/**
+ * davepi-plugin-object-storage
+ *
+ * Presigned-URL file uploads for dAvePi. Mounted by listing the package
+ * under the consumer project's `package.json -> davepi.plugins`:
+ *
+ *   {
+ *     "davepi": { "plugins": ["davepi-plugin-object-storage"] }
+ *   }
+ *
+ * Where this fits in the framework: the in-tree `type: 'File'` field
+ * is the per-record-field, proxy-the-bytes pipeline that's fine for
+ * avatars and document attachments. This plugin is the "client uploads
+ * straight to the bucket" pipeline: the API never sees the bytes, big
+ * files don't choke serverless request limits, and files become a
+ * first-class queryable resource (one row per file, not embedded on a
+ * parent record). Both can coexist in the same app.
+ *
+ * Behaviour at setup:
+ *
+ *   1. If `S3_BUCKET` is unset (or `S3_BACKEND=gcs` with no GCS SDK
+ *      installed), the plugin stays dormant. Routes are not mounted,
+ *      the schema is not registered, the reaper does not start. Calls
+ *      to `createUploadUrl` / `deleteFile` throw a clear "configure
+ *      S3_BUCKET" message.
+ *   2. The configured adapter is constructed (aws / r2 / minio / gcs).
+ *   3. The `file` schema is registered via `schemaLoader.loadSchema`
+ *      so REST / GraphQL / MCP / Swagger / the admin SPA see it.
+ *   4. Three routes are mounted under `S3_ROUTE_PREFIX` (default
+ *      `/api/files`): upload-url, :id/complete, :id/download-url.
+ *   5. The reaper starts (unless `S3_REAP_ENABLED=false`) and sweeps
+ *      orphaned `pending` records every `S3_REAP_INTERVAL_MS`.
+ *
+ * The plugin also exports a small programmatic API for callers who want
+ * to drive uploads from a schema lifecycle hook or a custom route:
+ * `createUploadUrl`, `createDownloadUrl`, `deleteFile`. Each requires a
+ * `user` parameter (the JWT payload) so tenant scoping is explicit.
+ */
+
+const { readConfig, validateUploadRequest } = require('./lib/config');
+const { createAdapter } = require('./lib/adapters');
+const { buildFileSchema } = require('./lib/schema');
+const { buildRouter } = require('./lib/routes');
+const { createReaper } = require('./lib/reaper');
+const { buildKey } = require('./lib/keys');
+
+/**
+ * Resolve a framework / peer-dep module by name, wrapping a MODULE_NOT_FOUND
+ * with a message that points the operator at the broken peer dep
+ * instead of leaving them with a bare require stack. The package's own
+ * unit tests bypass this entirely by injecting stubs at `createPlugin`
+ * time — so this only fires for the dep-resolution path that real
+ * consumers walk.
+ */
+function requireOrFail(name) {
+  try {
+    return require(name);
+  } catch (err) {
+    throw new Error(
+      `davepi-plugin-object-storage: failed to load required module '${name}'. ` +
+      'Ensure the davepi peer dependency is installed (>= 1.0.5). ' +
+      `Underlying error: ${err && err.message}`
+    );
+  }
+}
+
+function createPlugin(opts = {}) {
+  const env = opts.env || process.env;
+  const config = { ...readConfig(env), ...(opts.configOverrides || {}) };
+  const sdkOverrides = opts.sdkOverrides || {};
+  const adapterOverride = opts.adapter || null;
+  const injectedErrors = opts.errors || null;
+  const injectedAuth = opts.auth || null;
+  const injectedAsyncHandler = opts.asyncHandler || null;
+  const injectedMongoose = opts.mongoose || null;
+  const injectedExpress = opts.express || null;
+
+  const state = {
+    enabled: false,
+    adapter: null,
+    Model: null,
+    reaper: null,
+    log: null,
+    // Captured at setup() so the programmatic API can route its
+    // ValidationError throws through the same constructors the REST
+    // layer uses. Lets `createUploadUrl` share `validateUploadRequest`
+    // with the route handler — the reviewer's footgun fix on PR #122.
+    errors: null,
+  };
+
+  function ensureEnabled(call) {
+    if (!state.enabled) {
+      throw new Error(
+        `davepi-plugin-object-storage: ${call} called but plugin is dormant ` +
+        '(S3_BUCKET not set, or setup has not run yet)'
+      );
+    }
+  }
+
+  async function createUploadUrl({ user, contentType, originalName, size, metadata }) {
+    ensureEnabled('createUploadUrl');
+    if (!user || !user.user_id) {
+      throw new Error('davepi-plugin-object-storage: createUploadUrl requires { user: { user_id } }');
+    }
+    // Same policy enforcement the REST `POST /upload-url` route runs —
+    // a hook author can't bypass S3_ALLOWED_MIME / S3_MAX_BYTES by
+    // reaching for the programmatic API instead of the HTTP route.
+    validateUploadRequest({ contentType, size, config, errors: state.errors });
+    const userId = String(user.user_id);
+    const key = buildKey({ userId, originalName });
+    const doc = await state.Model.create({
+      userId,
+      accountId:   user.account_id ? String(user.account_id) : undefined,
+      key,
+      bucket:      state.adapter.bucket,
+      contentType,
+      size:        size != null ? size : undefined,
+      status:      'pending',
+      originalName,
+      metadata:    metadata && typeof metadata === 'object' ? metadata : undefined,
+    });
+    const url = await state.adapter.getSignedPutUrl({
+      key,
+      contentType,
+      expires: config.putUrlTtlSeconds,
+    });
+    return { fileId: String(doc._id), key, url, expiresIn: config.putUrlTtlSeconds };
+  }
+
+  async function createDownloadUrl({ user, fileId }) {
+    ensureEnabled('createDownloadUrl');
+    if (!user || !user.user_id) {
+      throw new Error('davepi-plugin-object-storage: createDownloadUrl requires { user: { user_id } }');
+    }
+    const doc = await state.Model.findById(fileId);
+    if (!doc || String(doc.userId) !== String(user.user_id)) {
+      // Same posture as the REST route: don't leak existence of a
+      // foreign-tenant file via a distinct 404-vs-403 response.
+      return null;
+    }
+    if (doc.status !== 'uploaded') return null;
+    const url = await state.adapter.getSignedGetUrl({
+      key:     doc.key,
+      expires: config.getUrlTtlSeconds,
+    });
+    return { fileId: String(doc._id), url, expiresIn: config.getUrlTtlSeconds };
+  }
+
+  async function deleteFile({ user, fileId }) {
+    ensureEnabled('deleteFile');
+    if (!user || !user.user_id) {
+      throw new Error('davepi-plugin-object-storage: deleteFile requires { user: { user_id } }');
+    }
+    const doc = await state.Model.findById(fileId);
+    if (!doc || String(doc.userId) !== String(user.user_id)) return false;
+    try {
+      await state.adapter.deleteObject({ key: doc.key });
+    } catch (err) {
+      if (state.log && typeof state.log.warn === 'function') {
+        state.log.warn(
+          { err, plugin: 'object-storage', key: doc.key },
+          'davepi-plugin-object-storage: deleteFile failed to remove storage object'
+        );
+      }
+      // Don't bail — caller asked to delete the record, so we remove
+      // it from the DB even if storage hiccups. The orphaned blob will
+      // be picked up by a future audit/cleanup; the user-facing API
+      // doesn't need to know.
+    }
+    await state.Model.deleteOne({ _id: doc._id });
+    return true;
+  }
+
+  async function setup({ app, schemaLoader, bus, log, appName }) {
+    state.log = log;
+
+    // The ONLY soft-fail path: an unconfigured `S3_BUCKET` is the
+    // documented dormancy signal so an operator can ship the plugin
+    // in a project before turning S3 on (matches slack / postmark /
+    // audit dormancy semantics for their respective top-level config
+    // env vars). Everything below this point treats real failures as
+    // fail-fast — the pluginLoader contract is explicit that
+    // "Errors during plugin setup propagate — a broken plugin fails
+    // the boot. Silently dropping a plugin would hide
+    // misconfiguration from operators." (utils/pluginLoader.js)
+    if (!config.bucket) {
+      log.warn(
+        { plugin: 'object-storage' },
+        'S3_BUCKET not set; davepi-plugin-object-storage is dormant'
+      );
+      return;
+    }
+    if (!schemaLoader || typeof schemaLoader.loadSchema !== 'function') {
+      throw new Error(
+        'davepi-plugin-object-storage: setup({ schemaLoader }) is required'
+      );
+    }
+    if (!app || typeof app.use !== 'function') {
+      throw new Error(
+        'davepi-plugin-object-storage: setup({ app }) is required'
+      );
+    }
+
+    // Lazy-resolve framework deps so the package's own unit tests
+    // (which don't install `davepi`) can run standalone. A failure
+    // here means the operator's runtime environment is broken — the
+    // peer dep on `davepi` should have made these available, so a
+    // miss is misconfiguration we fail loud on.
+    const mongoose     = injectedMongoose     || requireOrFail('mongoose');
+    const errors       = injectedErrors       || requireOrFail('davepi/utils/errors');
+    const auth         = injectedAuth         || requireOrFail('davepi/middleware/auth');
+    const asyncHandler = injectedAsyncHandler || requireOrFail('davepi/utils/asyncHandler');
+    const expressMod   = injectedExpress      || requireOrFail('express');
+
+    // Capture errors on state BEFORE adapter / schema steps so the
+    // programmatic API can route ValidationError through the same
+    // constructors the REST layer uses even if setup throws partway
+    // through.
+    state.errors = errors;
+
+    // Adapter construction can throw — most commonly when the operator
+    // set `S3_BACKEND=gcs` but didn't install `@google-cloud/storage`
+    // (the optionalDependency wasn't pulled in). That's misconfiguration,
+    // not a soft case: fail-fast so the operator sees it at boot, not
+    // when the first upload request lands.
+    state.adapter = adapterOverride || createAdapter(config, { sdkOverrides });
+
+    // Register the file schema. The afterDelete hook needs the live
+    // adapter, so we pass a thunk rather than the adapter itself —
+    // makes the schema reusable if the adapter is swapped in tests.
+    const schema = buildFileSchema({
+      mongoose,
+      errors,
+      version:       config.fileVersion,
+      path:          config.filePath,
+      cascadeDelete: config.cascadeDelete,
+      getAdapter:    () => state.adapter,
+      log,
+    });
+    await schemaLoader.loadSchema(schema);
+    const entry = schemaLoader.getEntry(`${config.fileVersion}/${config.filePath}`);
+    if (!entry || !entry.model) {
+      throw new Error(
+        'davepi-plugin-object-storage: file schema registered but ' +
+        'schemaLoader.getEntry returned no model — framework contract violation'
+      );
+    }
+    state.Model = entry.model;
+    const router = expressMod.Router();
+    buildRouter({
+      router,
+      auth,
+      asyncHandler,
+      errors,
+      getModel: () => state.Model,
+      adapter:  state.adapter,
+      config,
+    });
+    app.use(config.routePrefix, router);
+    // `app.use` appends to the middleware stack — so the just-mounted
+    // router sits AFTER the framework's terminal `errorHandler`,
+    // meaning a thrown `ValidationError` from our routes would bypass
+    // the centralised response shape. The framework re-asserts the
+    // errorHandler tail after the whole plugin batch completes (see
+    // app.js's `if (app.locals.plugins.length)` block); calling it
+    // here as well keeps the invariant correct for tests + hot-paths
+    // that load the plugin after boot. The operation is idempotent —
+    // it splices any existing errorHandler before re-appending.
+    if (typeof schemaLoader.moveErrorHandlerToEnd === 'function') {
+      schemaLoader.moveErrorHandlerToEnd();
+    }
+
+    state.reaper = createReaper({
+      getModel: () => state.Model,
+      adapter:  state.adapter,
+      config,
+      log,
+    });
+    state.reaper.start();
+
+    state.enabled = true;
+
+    log.info(
+      {
+        plugin:        'object-storage',
+        backend:       config.backend,
+        bucket:        config.bucket,
+        filePath:      `${config.fileVersion}/${config.filePath}`,
+        routePrefix:   config.routePrefix,
+        cascadeDelete: config.cascadeDelete,
+        reapEnabled:   config.reapEnabled,
+      },
+      'davepi-plugin-object-storage ready'
+    );
+
+    // Keep references the contract guarantees we receive even when we
+    // don't use them — same convention slack/audit follow so the
+    // documented setup signature stays exercised.
+    void bus;
+    void appName;
+  }
+
+  return {
+    name: 'object-storage',
+    setup,
+    createUploadUrl,
+    createDownloadUrl,
+    deleteFile,
+    // Adapter escape hatch for advanced consumers — see ticket #112's
+    // "Adapter escape hatch" note.
+    get adapter() {
+      return state.adapter;
+    },
+    // Exposed for tests + integration suites. Not part of the public
+    // API contract.
+    _state: state,
+    _config: config,
+  };
+}
+
+const defaultPlugin = createPlugin();
+module.exports = defaultPlugin;
+module.exports.createPlugin = createPlugin;
+module.exports.buildKey = buildKey;