cyberia 3.0.3 → 3.2.5

package/src/api/ipfs/ipfs.model.js

@@ -1,6 +1,22 @@
 /**
- * Mongoose model for IPFS API – a general-purpose pin record that relates
- * a user to a CID.
+ * Mongoose model for the IPFS CID Registry.
+ *
+ * Purpose: tracks every CID that the Engine has pinned to IPFS so that:
+ *   1. Deletions can cleanly unpin the right CID from the IPFS node/cluster.
+ *   2. Admins can run a health-check that verifies every DB-registered CID is
+ *      still actually pinned (GET /ipfs/verify).
+ *   3. Garbage-collection jobs can discover orphaned CIDs (pinned on the node
+ *      but not referenced by any DB document).
+ *
+ * Fields:
+ *   cid          - IPFS Content Identifier (CIDv0 or CIDv1).
+ *   resourceType - What kind of asset this CID belongs to:
+ *                    'object-layer-data'  - JSON payload of an ObjectLayer document.
+ *                    'atlas-sprite-sheet' - PNG sprite-sheet of an ObjectLayer.
+ *                    'atlas-metadata'     - JSON metadata of an AtlasSpriteSheet.
+ *   mfsPath      - MFS (Mutable File System) path used when the CID was added,
+ *                  e.g. /object-layer/sword/sword_data.json.
+ *                  Enables targeted removal via files/rm without knowing the CID.
  *
  * @module src/api/ipfs/ipfs.model.js
  * @namespace IpfsModel
@@ -8,14 +24,6 @@
 
 import { Schema, model } from 'mongoose';
 
-/**
- * @typedef {Object} Ipfs
- * @property {string}         cid       – IPFS Content Identifier (CIDv0 or CIDv1).
- * @property {Types.ObjectId} userId    – Reference to the User who owns / requested the pin.
- * @property {Date}           createdAt – Auto-managed by Mongoose.
- * @property {Date}           updatedAt – Auto-managed by Mongoose.
- * @memberof IpfsModel
- */
 const IpfsSchema = new Schema(
   {
     cid: {
@@ -23,10 +31,19 @@ const IpfsSchema = new Schema(
       required: true,
       trim: true,
     },
-    userId: {
-      type: Schema.Types.ObjectId,
-      ref: 'User',
+    // Asset category - determines which service owns this CID.
+    resourceType: {
+      type: String,
       required: true,
+      trim: true,
+      enum: ['object-layer-data', 'atlas-sprite-sheet', 'atlas-metadata'],
+    },
+    // MFS path used when the content was added to IPFS.
+    // Empty string when the content was added without an MFS copy.
+    mfsPath: {
+      type: String,
+      default: '',
+      trim: true,
     },
   },
   {
@@ -34,14 +51,14 @@ const IpfsSchema = new Schema(
   },
 );
 
-// Compound index: one pin record per user + CID pair.
-IpfsSchema.index({ cid: 1, userId: 1 }, { unique: true });
+// One DB record per (CID, resourceType) pair.
+IpfsSchema.index({ cid: 1, resourceType: 1 }, { unique: true });
 
-// Fast look-ups by user.
-IpfsSchema.index({ userId: 1 });
+// Fast look-ups for health-check and garbage-collection by type.
+IpfsSchema.index({ resourceType: 1 });
 
-// Fast look-ups by CID.
-IpfsSchema.index({ cid: 1 });
+// Fast look-ups for targeted MFS cleanup.
+IpfsSchema.index({ mfsPath: 1 });
 
 const IpfsModel = model('Ipfs', IpfsSchema);
 
@@ -49,21 +66,13 @@ const ProviderSchema = IpfsSchema;
 
 const IpfsDto = {
   select: {
-    get: () => {
-      return {
-        _id: 1,
-        cid: 1,
-        userId: 1,
-        createdAt: 1,
-        updatedAt: 1,
-      };
-    },
-  },
-  populate: {
-    user: () => ({
-      path: 'userId',
-      model: 'User',
-      select: '_id username email role',
+    get: () => ({
+      _id: 1,
+      cid: 1,
+      resourceType: 1,
+      mfsPath: 1,
+      createdAt: 1,
+      updatedAt: 1,
     }),
   },
 };

package/src/api/ipfs/ipfs.router.js

@@ -8,19 +8,14 @@ const logger = loggerFactory(import.meta);
 const IpfsRouter = (options) => {
   const router = express.Router();
   const authMiddleware = options.authMiddleware;
-  router.post(`/pin`, authMiddleware, adminGuard, async (req, res) => await IpfsController.pin(req, res, options));
-  router.delete(
-    `/pin/:cid`,
-    authMiddleware,
-    adminGuard,
-    async (req, res) => await IpfsController.unpin(req, res, options),
-  );
-  router.post(`/:id`, authMiddleware, async (req, res) => await IpfsController.post(req, res, options));
-  router.post(`/`, authMiddleware, async (req, res) => await IpfsController.post(req, res, options));
-  router.get(`/:id`, authMiddleware, async (req, res) => await IpfsController.get(req, res, options));
-  router.get(`/`, authMiddleware, async (req, res) => await IpfsController.get(req, res, options));
-  router.put(`/:id`, authMiddleware, async (req, res) => await IpfsController.put(req, res, options));
-  router.put(`/`, authMiddleware, async (req, res) => await IpfsController.put(req, res, options));
+  // Health / audit — must come before /:id to avoid matching conflicts.
+  router.get(`/verify`, authMiddleware, adminGuard, async (req, res) => await IpfsController.verify(req, res, options));
+  router.post(`/:id`, authMiddleware, adminGuard, async (req, res) => await IpfsController.post(req, res, options));
+  router.post(`/`, authMiddleware, adminGuard, async (req, res) => await IpfsController.post(req, res, options));
+  router.get(`/:id`, authMiddleware, adminGuard, async (req, res) => await IpfsController.get(req, res, options));
+  router.get(`/`, authMiddleware, adminGuard, async (req, res) => await IpfsController.get(req, res, options));
+  router.put(`/:id`, authMiddleware, adminGuard, async (req, res) => await IpfsController.put(req, res, options));
+  router.put(`/`, authMiddleware, adminGuard, async (req, res) => await IpfsController.put(req, res, options));
   router.delete(`/:id`, authMiddleware, adminGuard, async (req, res) => await IpfsController.delete(req, res, options));
   router.delete(`/`, authMiddleware, adminGuard, async (req, res) => await IpfsController.delete(req, res, options));
   return router;

package/src/api/ipfs/ipfs.service.js

@@ -7,47 +7,40 @@ import { IpfsDto } from './ipfs.model.js';
 const logger = loggerFactory(import.meta);
 
 /**
- * Create (or upsert) an IPFS pin record for a given user + CID pair.
- * This is a helper consumed by other services (ObjectLayer, AtlasSpriteSheet, …)
- * so they don't need to know about the Ipfs model directly.
+ * Upsert a CID registry entry.
+ * Called by asset services (ObjectLayer, AtlasSpriteSheet) after a successful
+ * IPFS pin so the registry always reflects what is actually pinned.
  *
- * @param {object}  opts
- * @param {string}  opts.cid      – IPFS Content Identifier.
- * @param {string}  opts.userId   – Mongoose ObjectId string of the owning user.
- * @param {object}  opts.options  – Router options ({ host, path }) for DB lookup.
+ * @param {object} opts
+ * @param {string} opts.cid          - IPFS Content Identifier.
+ * @param {string} opts.resourceType - Asset category ('object-layer-data' | 'atlas-sprite-sheet' | 'atlas-metadata').
+ * @param {string} [opts.mfsPath]    - MFS path used when adding the content.
+ * @param {object} opts.options      - Router options ({ host, path }) for DB lookup.
  * @returns {Promise<import('mongoose').Document>}
  */
-const createPinRecord = async ({ cid, userId, options }) => {
+const createPinRecord = async ({ cid, resourceType, mfsPath = '', options }) => {
   const Ipfs = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Ipfs;
-
-  // Upsert: if a record for this user + CID already exists, just touch it.
   const record = await Ipfs.findOneAndUpdate(
-    { cid, userId },
-    { cid, userId },
-    { upsert: true, new: true, setDefaultsOnInsert: true },
+    { cid, resourceType },
+    { cid, resourceType, mfsPath },
+    { upsert: true, returnDocument: 'after', setDefaultsOnInsert: true },
   );
-
-  logger.info(`IPFS pin record upserted – CID: ${cid}, userId: ${userId}`);
+  logger.info(`IPFS registry upserted – CID: ${cid}, type: ${resourceType}, mfsPath: ${mfsPath}`);
   return record;
 };
 
 /**
- * Remove all DB pin records for a CID, then best-effort unpin from IPFS node/cluster.
- * Always deletes the DB records first so that even if the IPFS node is unreachable
- * the database stays clean.
+ * Remove all DB registry entries for a CID, then best-effort unpin from the IPFS node.
+ * Always deletes DB records first so the registry stays clean even if the node is down.
  *
- * @param {string} cid     – IPFS Content Identifier to clean up.
- * @param {object} options – Router options ({ host, path }) for DB lookup.
+ * @param {string} cid     - IPFS Content Identifier to remove.
+ * @param {object} options - Router options ({ host, path }) for DB lookup.
  * @returns {Promise<void>}
  */
 const removePinRecordsAndUnpin = async (cid, options) => {
   const Ipfs = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Ipfs;
-
-  // 1. Remove all DB pin records for this CID first
   await Ipfs.deleteMany({ cid });
-  logger.info(`Removed all IPFS pin records for CID: ${cid}`);
-
-  // 2. Best-effort unpin from IPFS node/cluster (ignore "not pinned" errors)
+  logger.info(`Removed IPFS registry entries for CID: ${cid}`);
   try {
     await IpfsClient.unpinCid(cid);
   } catch (err) {
@@ -65,128 +58,87 @@ const IpfsService = {
   // ──────────────────────────────────────────────
 
   post: async (req, res, options) => {
-    /** @type {import('./ipfs.model.js').IpfsModel} */
     const Ipfs = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Ipfs;
-
-    // Accept { cid, userId? } in body.
-    // If userId is omitted, fall back to the authenticated user.
-    const body = { ...req.body };
-    if (!body.userId && req.auth && req.auth.user) {
-      body.userId = req.auth.user._id;
-    }
-    // Strip pinType if sent by legacy clients
-    delete body.pinType;
-
-    return await new Ipfs(body).save();
+    return await new Ipfs(req.body).save();
   },
 
   get: async (req, res, options) => {
-    /** @type {import('./ipfs.model.js').IpfsModel} */
     const Ipfs = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Ipfs;
-
     if (req.params.id) {
-      return await Ipfs.findById(req.params.id).select(IpfsDto.select.get()).populate(IpfsDto.populate.user());
+      return await Ipfs.findById(req.params.id).select(IpfsDto.select.get());
     }
-
     const { query, sort, skip, limit, page } = DataQuery.parse(req.query);
-
     const [data, total] = await Promise.all([
-      Ipfs.find(query)
-        .select(IpfsDto.select.get())
-        .sort(sort)
-        .limit(limit)
-        .skip(skip)
-        .populate(IpfsDto.populate.user()),
+      Ipfs.find(query).select(IpfsDto.select.get()).sort(sort).limit(limit).skip(skip),
       Ipfs.countDocuments(query),
     ]);
-
     const totalPages = Math.ceil(total / limit);
     return { data, total, page, totalPages };
   },
 
   put: async (req, res, options) => {
-    /** @type {import('./ipfs.model.js').IpfsModel} */
     const Ipfs = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Ipfs;
-    return await Ipfs.findByIdAndUpdate(req.params.id, req.body, { new: true });
+    return await Ipfs.findByIdAndUpdate(req.params.id, req.body, { returnDocument: 'after' });
   },
 
   delete: async (req, res, options) => {
-    /** @type {import('./ipfs.model.js').IpfsModel} */
     const Ipfs = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Ipfs;
-
     if (req.params.id) {
       const record = await Ipfs.findById(req.params.id);
       if (record) {
-        // Remove DB record first, then best-effort unpin
         await Ipfs.findByIdAndDelete(req.params.id);
-        try {
-          // Only unpin from IPFS if no other records reference this CID
-          const remaining = await Ipfs.countDocuments({ cid: record.cid });
-          if (remaining === 0) {
+        // Only unpin from the node when no other registry entries reference this CID.
+        const remaining = await Ipfs.countDocuments({ cid: record.cid });
+        if (remaining === 0) {
+          try {
             await IpfsClient.unpinCid(record.cid);
+          } catch (err) {
+            logger.warn(`Failed to unpin CID ${record.cid}: ${err.message}`);
           }
-        } catch (err) {
-          logger.warn(`Failed to unpin CID ${record.cid} from IPFS node: ${err.message}`);
         }
         return record;
       }
       return null;
     }
-
     return await Ipfs.deleteMany();
   },
 
   // ──────────────────────────────────────────────
-  //  Pin / Unpin helpers (called via controller)
+  //  Health / audit
   // ──────────────────────────────────────────────
 
   /**
-   * POST /ipfs/pin  – add content to IPFS, pin it, and create a DB record.
-   * Body: { data: <string|object>, userId? }
+   * GET /ipfs/verify
+   *
+   * Iterates every CID in the registry and checks whether it is actually pinned
+   * on the connected IPFS node. Returns a summary suitable for admin dashboards
+   * and automated alerting.
+   *
+   * Response shape:
+   *   { total, pinned, unpinned, errors, entries: [{ cid, resourceType, mfsPath, pinned, error? }] }
    */
-  pin: async (req, res, options) => {
-    const userId = req.body.userId || (req.auth && req.auth.user ? req.auth.user._id : undefined);
-    if (!userId) throw new Error('userId is required to create a pin record');
-
-    const content = typeof req.body.data === 'string' ? req.body.data : JSON.stringify(req.body.data);
-    const result = await IpfsClient.addToIpfs(Buffer.from(content, 'utf-8'), req.body.filename || 'data');
-
-    if (!result) throw new Error('IPFS node is unreachable – content was not pinned');
-
-    const record = await createPinRecord({
-      cid: result.cid,
-      userId,
-      options,
-    });
-
-    return { cid: result.cid, size: result.size, record };
-  },
-
-  /**
-   * DELETE /ipfs/pin/:cid  – unpin a CID and remove the DB record for the current user.
-   */
-  unpin: async (req, res, options) => {
+  verify: async (req, res, options) => {
     const Ipfs = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Ipfs;
-    const userId = req.auth && req.auth.user ? req.auth.user._id : undefined;
-    const cid = req.params.cid || req.params.id;
+    const records = await Ipfs.find({}).select(IpfsDto.select.get()).lean();
 
-    const record = await Ipfs.findOne({ cid, ...(userId ? { userId } : {}) });
-    if (!record) throw new Error(`No pin record found for CID ${cid}`);
-
-    // Remove DB record first
-    await Ipfs.findByIdAndDelete(record._id);
-
-    // Only unpin from the IPFS node when nobody else has a record for this CID
-    const remaining = await Ipfs.countDocuments({ cid });
-    if (remaining === 0) {
-      try {
-        await IpfsClient.unpinCid(cid);
-      } catch (err) {
-        logger.warn(`Best-effort IPFS unpin failed for CID ${cid}: ${err.message}`);
-      }
-    }
+    let pinned = 0;
+    let unpinned = 0;
+    let errors = 0;
+    const entries = await Promise.all(
+      records.map(async (r) => {
+        try {
+          const isPinned = await IpfsClient.isCidPinned(r.cid);
+          if (isPinned) pinned++;
+          else unpinned++;
+          return { cid: r.cid, resourceType: r.resourceType, mfsPath: r.mfsPath, pinned: isPinned };
+        } catch (err) {
+          errors++;
+          return { cid: r.cid, resourceType: r.resourceType, mfsPath: r.mfsPath, pinned: false, error: err.message };
+        }
+      }),
+    );
 
-    return { success: true, cid };
+    return { total: records.length, pinned, unpinned, errors, entries };
   },
 };