davepi-plugin-object-storage 0.1.0

package/lib/routes.js

@@ -0,0 +1,209 @@
+'use strict';
+
+/**
+ * The three plugin-owned REST routes that drive the presigned-URL
+ * upload pipeline. Mounted by the plugin's setup() onto the same
+ * Express app the schema layer uses, so requests go through the
+ * framework's terminal `errorHandler` for response shape consistency.
+ *
+ * All three require `auth(true)` so a JWT is present; `userId` comes
+ * off `req.user.user_id` exactly like the framework's auto-generated
+ * REST handlers.
+ *
+ * Routes:
+ *
+ *   POST   /api/files/upload-url      — issue a presigned PUT URL +
+ *                                       create a `pending` file record
+ *   POST   /api/files/:fileId/complete — verify the upload landed,
+ *                                       flip status to `uploaded`
+ *   GET    /api/files/:fileId/download-url — issue a short-lived
+ *                                            presigned GET URL
+ *
+ * Tenant scope is enforced at the route layer (`userId` filter on
+ * every Mongo query). The schema's write-locked fields are a second
+ * line of defence at the framework's generic CRUD surface, but for
+ * these custom routes the plugin is the only writer and validates
+ * directly.
+ */
+
+const { buildKey } = require('./keys');
+const { validateUploadRequest } = require('./config');
+
+function buildRouter({
+  router,
+  auth,
+  asyncHandler,
+  errors,
+  getModel,
+  adapter,
+  config,
+}) {
+  const { NotFoundError, ValidationError, ForbiddenError } = errors;
+
+  function ownerOnly(record, userId) {
+    if (!record) throw new NotFoundError('file');
+    if (String(record.userId) !== String(userId)) {
+      // 404, not 403 — never leak that a foreign-tenant file exists.
+      throw new NotFoundError('file');
+    }
+  }
+
+  router.post(
+    '/upload-url',
+    auth(true),
+    asyncHandler(async (req, res) => {
+      const userId = req.user && req.user.user_id;
+      if (!userId) throw new ForbiddenError('auth required');
+
+      const { contentType, originalName, size, metadata } = req.body || {};
+      // Single source of truth for upload-policy validation — shared
+      // with the programmatic `createUploadUrl` API so a hook author
+      // can't bypass MIME / size checks by reaching for the JS surface.
+      validateUploadRequest({ contentType, size, config, errors });
+
+      const key = buildKey({ userId, originalName });
+      const Model = getModel();
+      const doc = await Model.create({
+        userId:        String(userId),
+        accountId:     req.user.account_id ? String(req.user.account_id) : undefined,
+        key,
+        bucket:        adapter.bucket,
+        contentType,
+        size:          size != null ? size : undefined,
+        status:        'pending',
+        originalName:  originalName || undefined,
+        metadata:      metadata && typeof metadata === 'object' ? metadata : undefined,
+      });
+
+      const url = await adapter.getSignedPutUrl({
+        key,
+        contentType,
+        expires: config.putUrlTtlSeconds,
+      });
+
+      res.status(201).json({
+        fileId:      String(doc._id),
+        key,
+        url,
+        expiresIn:   config.putUrlTtlSeconds,
+        contentType,
+      });
+    })
+  );
+
+  router.post(
+    '/:fileId/complete',
+    auth(true),
+    asyncHandler(async (req, res) => {
+      const userId = req.user && req.user.user_id;
+      if (!userId) throw new ForbiddenError('auth required');
+
+      const Model = getModel();
+      const doc = await Model.findById(req.params.fileId);
+      ownerOnly(doc, userId);
+
+      if (doc.status === 'uploaded') {
+        // Idempotent — the client may legitimately retry /complete if
+        // the PUT response was ambiguous (network blip, mobile network
+        // killing the connection mid-200). Return the existing state.
+        return res.status(200).json(serialize(doc));
+      }
+
+      if (config.verifyOnComplete) {
+        const head = await adapter.headObject({ key: doc.key });
+        if (!head.exists) {
+          throw new ValidationError(
+            'upload not found in storage; client must PUT to the presigned URL before calling /complete'
+          );
+        }
+        // If the client provided a size at upload-url time, validate
+        // the storage layer reports the same value. A mismatch usually
+        // means the client lied at presign time to bypass the maxBytes
+        // gate, then PUT a bigger file.
+        if (
+          typeof doc.size === 'number' &&
+          typeof head.contentLength === 'number' &&
+          doc.size !== head.contentLength
+        ) {
+          throw new ValidationError(
+            `uploaded size ${head.contentLength} does not match declared size ${doc.size}`
+          );
+        }
+        if (
+          typeof head.contentLength === 'number' &&
+          head.contentLength > config.maxBytes
+        ) {
+          // Even if the client didn't declare a size up-front, refuse
+          // to flip to `uploaded` if the actual blob is over the limit.
+          // The blob stays in the bucket — the reaper / cascade-delete
+          // path will eventually clean it up.
+          throw new ValidationError(
+            `uploaded size ${head.contentLength} exceeds S3_MAX_BYTES (${config.maxBytes})`
+          );
+        }
+        if (head.contentLength != null) doc.size = head.contentLength;
+        if (head.etag) doc.etag = head.etag;
+      }
+
+      doc.status = 'uploaded';
+      doc.uploadedAt = new Date();
+      await doc.save();
+
+      res.status(200).json(serialize(doc));
+    })
+  );
+
+  router.get(
+    '/:fileId/download-url',
+    auth(true),
+    asyncHandler(async (req, res) => {
+      const userId = req.user && req.user.user_id;
+      if (!userId) throw new ForbiddenError('auth required');
+
+      const Model = getModel();
+      const doc = await Model.findById(req.params.fileId);
+      ownerOnly(doc, userId);
+
+      if (doc.status !== 'uploaded') {
+        throw new ValidationError(
+          `file ${req.params.fileId} is in status "${doc.status}"; only uploaded files can be downloaded`
+        );
+      }
+
+      const url = await adapter.getSignedGetUrl({
+        key:     doc.key,
+        expires: config.getUrlTtlSeconds,
+      });
+
+      res.status(200).json({
+        fileId:     String(doc._id),
+        url,
+        expiresIn:  config.getUrlTtlSeconds,
+      });
+    })
+  );
+
+  return router;
+}
+
+function serialize(doc) {
+  const o = typeof doc.toObject === 'function' ? doc.toObject() : doc;
+  return {
+    fileId:       String(o._id),
+    userId:       o.userId,
+    accountId:    o.accountId || null,
+    key:          o.key,
+    bucket:       o.bucket || null,
+    contentType:  o.contentType,
+    size:         o.size != null ? o.size : null,
+    status:       o.status,
+    originalName: o.originalName || null,
+    metadata:     o.metadata || null,
+    uploadedAt:   o.uploadedAt || null,
+    etag:         o.etag || null,
+    createdAt:    o.createdAt || null,
+    updatedAt:    o.updatedAt || null,
+  };
+}
+
+module.exports = { buildRouter, serialize };

package/lib/schema.js

@@ -0,0 +1,124 @@
+'use strict';
+
+const { userIdOfKey } = require('./keys');
+
+/**
+ * Build the `file` schema the plugin registers with the framework's
+ * schemaLoader. Once registered, the file collection is queryable
+ * through every standard surface (REST list / read, GraphQL, MCP,
+ * Swagger, the admin SPA) like any other dAvePi resource — but the
+ * fields that describe where the bytes live are write-locked so
+ * clients can't lie about them.
+ *
+ * Write-locked fields: `key`, `bucket`, `status`, `size`, `contentType`.
+ * Anyone trying to POST or PUT these via the standard CRUD routes has
+ * them filtered out by `filterWritable` (the sentinel ACL role no real
+ * user holds — same trick `davepi-plugin-audit` uses on its `audit`
+ * collection). The plugin's own upload-url / complete endpoints write
+ * these directly via the Mongoose model, bypassing the API surface.
+ *
+ * `originalName` and `metadata` stay writable so a client can rename a
+ * file or attach app-specific labels through the regular PUT route.
+ *
+ * The schema declares an `afterDelete` hook that talks to the storage
+ * adapter when `S3_CASCADE_DELETE=true`. The hook is best-effort —
+ * `after*` hooks already swallow throws per the framework contract, so
+ * a transient bucket error logs but doesn't surface as a 5xx.
+ */
+
+function buildFileSchema({
+  mongoose,
+  errors,
+  version,
+  path,
+  cascadeDelete,
+  getAdapter,
+  log,
+}) {
+  const Mixed = mongoose.Schema.Types.Mixed;
+  const NO_ONE = ['__davepi_plugin_object_storage_only__'];
+  const withWriteLock = (field) => ({
+    ...field,
+    acl: { ...(field.acl || {}), create: NO_ONE, update: NO_ONE },
+  });
+
+  const afterDelete = async ({ record }) => {
+    if (!cascadeDelete) return;
+    if (!record || !record.key) return;
+    // Defence-in-depth: the `key` field is API-write-locked via the
+    // sentinel ACL above, so a client can't directly stamp a foreign
+    // tenant's key onto a file record. But framework bugs, corrupted
+    // documents, or a misconfigured admin tool that wrote directly
+    // through Mongoose could leave a row whose key disagrees with its
+    // userId. `userIdOfKey` parses the leading segment of the key
+    // (which buildKey always stamps as `<userId>/...`) — if it doesn't
+    // match record.userId, refuse to delete the blob rather than
+    // potentially wiping another tenant's bytes.
+    const keyUserId = userIdOfKey(record.key);
+    if (!keyUserId || String(keyUserId) !== String(record.userId)) {
+      if (log && typeof log.warn === 'function') {
+        log.warn(
+          { plugin: 'object-storage', key: record.key, recordUserId: record.userId },
+          'davepi-plugin-object-storage: cascade-delete refused — key does not belong to record owner'
+        );
+      }
+      return;
+    }
+    try {
+      const adapter = getAdapter();
+      if (!adapter) return;
+      await adapter.deleteObject({ key: record.key });
+    } catch (err) {
+      // Best-effort: storage failure must not back-propagate into the
+      // delete response. Same posture as audit's bus write — log via
+      // the framework's pino instance and move on.
+      if (log && typeof log.error === 'function') {
+        log.error(
+          { err, plugin: 'object-storage', key: record.key },
+          'davepi-plugin-object-storage: cascade-delete of storage object failed'
+        );
+      }
+    }
+  };
+
+  return {
+    path,
+    collection: path,
+    version,
+    // Soft-delete leaves the record around but the blob's still in the
+    // bucket. Cascade-delete only runs on hard-delete (the framework's
+    // afterDelete hook fires once per delete path; the soft-delete path
+    // fires it with the tombstoned record, which we ignore unless the
+    // hard-delete path runs). To keep semantics clean — and because file
+    // records track an external mutable resource — `softDelete: false`
+    // means the API always hard-deletes. Consumers who want a "trash"
+    // workflow can layer their own status (`archived` etc.) on top.
+    softDelete: false,
+    fields: [
+      withWriteLock({ name: 'userId',       type: String, required: true }),
+      withWriteLock({ name: 'accountId',    type: String }),
+      withWriteLock({ name: 'key',          type: String, required: true }),
+      withWriteLock({ name: 'bucket',       type: String }),
+      withWriteLock({ name: 'contentType',  type: String, required: true }),
+      withWriteLock({ name: 'size',         type: Number }),
+      withWriteLock({
+        name:    'status',
+        type:    String,
+        enum:    ['pending', 'uploaded', 'deleted'],
+        default: 'pending',
+        required: true,
+      }),
+      { name: 'originalName', type: String },
+      { name: 'metadata',     type: Mixed },
+      withWriteLock({ name: 'uploadedAt',   type: Date }),
+      withWriteLock({ name: 'etag',         type: String }),
+    ],
+    hooks: { afterDelete },
+    // No `acl.list` bypass — files are tenant-scoped like every other
+    // resource. Admins who need cross-tenant visibility can add a
+    // schema override in their consumer project; the plugin's default
+    // is the strict invariant.
+  };
+}
+
+module.exports = { buildFileSchema };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "davepi-plugin-object-storage",
+  "version": "0.1.0",
+  "description": "Presigned-URL object-storage uploads for 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. Pluggable backend supports AWS S3, Cloudflare R2, MinIO, and Google Cloud Storage.",
+  "license": "ISC",
+  "homepage": "https://docs.davepi.dev/features/plugins/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/projik/davepi.git",
+    "directory": "packages/davepi-plugin-object-storage"
+  },
+  "keywords": [
+    "davepi",
+    "davepi-plugin",
+    "object-storage",
+    "s3",
+    "r2",
+    "minio",
+    "gcs",
+    "uploads",
+    "presigned-url"
+  ],
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.583.0",
+    "@aws-sdk/s3-request-presigner": "^3.583.0"
+  },
+  "optionalDependencies": {
+    "@google-cloud/storage": "^7.11.0"
+  },
+  "peerDependencies": {
+    "davepi": ">=1.0.5"
+  },
+  "peerDependenciesMeta": {
+    "davepi": {
+      "optional": false
+    }
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  }
+}