javascript-solid-server 0.0.94 → 0.0.95

package/.claude/settings.local.json

@@ -141,7 +141,6 @@
       "Bash(DATA_ROOT=/tmp/jss-git-test/data node:*)",
       "Bash(git remote set-url:*)",
       "Bash(for:*)",
-      "Bash(^/**\" | head -1 | sed ''''s/.*\\* //'''')\")",
       "Bash(if [ ! -d \"node-solid-server\" ])",
       "Bash(then git clone --depth 1 https://github.com/nodeSolidServer/node-solid-server.git)",
       "Bash(node test-local-nss2.js:*)",
@@ -325,7 +324,10 @@
       "Bash(npm link:*)",
       "Bash(git push)",
       "Bash(ulimit:*)",
-      "Bash(gh label:*)"
+      "Bash(gh label:*)",
+      "Bash(mongosh --eval \"db.runCommand\\({ ping: 1 }\\)\" 2>&1 | head -5)",
+      "Bash(which jss && jss --version 2>&1)",
+      "Bash(jss start --help 2>&1 | grep -i mongo)"
     ]
   }
 }

package/README.md

@@ -148,6 +148,9 @@ jss --help             # Show help
 | `--public` | Allow unauthenticated access (skip WAC) | false |
 | `--read-only` | Disable PUT/DELETE/PATCH methods | false |
 | `--live-reload` | Auto-refresh browser on file changes | false |
+| `--mongo` | Enable MongoDB-backed /db/ route | false |
+| `--mongo-url <url>` | MongoDB connection URL | mongodb://localhost:27017 |
+| `--mongo-database <name>` | MongoDB database name | solid |
 | `-q, --quiet` | Suppress logs | false |
 
 ### Environment Variables
@@ -173,6 +176,9 @@ export JSS_PUBLIC=true
 export JSS_READ_ONLY=true
 export JSS_LIVE_RELOAD=true
 export JSS_SOLIDOS_UI=true
+export JSS_MONGO=true
+export JSS_MONGO_URL=mongodb://localhost:27017
+export JSS_MONGO_DATABASE=solid
 jss start
 ```
 
@@ -647,6 +653,49 @@ jss quota show alice
 jss quota reconcile alice
 ```
 
+## MongoDB Storage (`/db/` Route)
+
+Optional MongoDB-backed route for JSON-LD documents that need scale (social feeds, posts, follows). All other routes continue using the filesystem unchanged.
+
+```bash
+# Install the optional MongoDB driver
+npm install mongodb
+
+# Start with MongoDB enabled
+jss start --mongo --mongo-url mongodb://localhost:27017 --mongo-database solid
+```
+
+### Operations
+
+```bash
+# Store a document
+curl -X PUT http://localhost:3000/db/alice/notes/1 \
+  -H "Content-Type: application/ld+json" \
+  -H "Authorization: Bearer <token>" \
+  -d '{"@context": "https://schema.org/", "@type": "Note", "text": "Hello"}'
+
+# Read it back
+curl http://localhost:3000/db/alice/notes/1
+
+# List container (derived from URI prefixes)
+curl http://localhost:3000/db/alice/
+
+# Delete
+curl -X DELETE http://localhost:3000/db/alice/notes/1 \
+  -H "Authorization: Bearer <token>"
+```
+
+### How It Works
+
+- `GET /db/:path` — retrieve a document by URI, or list a virtual container
+- `PUT /db/:path` — create or update (upsert) a JSON-LD document
+- `DELETE /db/:path` — remove a document
+- Returns standard LDP headers (Link, ETag, WAC-Allow, CORS)
+- Supports conditional requests (If-Match, If-None-Match)
+- Container listings are computed from URI prefix queries — no directory management needed
+- Auth: pod owner can write (`/db/{podName}/...`), reads are public
+- MongoDB is an optional dependency — the server runs without it
+
 ### How It Works
 
 - Quotas are tracked incrementally on PUT, POST, and DELETE operations

package/bin/jss.js

@@ -80,6 +80,10 @@ program
   .option('--public', 'Allow unauthenticated access (skip WAC, open read/write)')
   .option('--read-only', 'Disable PUT/DELETE/PATCH methods (read-only mode)')
   .option('--live-reload', 'Inject live reload script into HTML (auto-refresh on changes)')
+  .option('--mongo', 'Enable MongoDB-backed /db/ route')
+  .option('--no-mongo', 'Disable MongoDB-backed /db/ route')
+  .option('--mongo-url <url>', 'MongoDB connection URL (default: mongodb://localhost:27017)')
+  .option('--mongo-database <name>', 'MongoDB database name (default: solid)')
   .option('-q, --quiet', 'Suppress log output')
   .option('--log-level <level>', 'Log level: error, warn, info, debug (default: info)')
   .option('--print-config', 'Print configuration and exit')
@@ -142,6 +146,9 @@ program
         public: config.public,
         readOnly: config.readOnly,
         liveReload: config.liveReload,
+        mongo: config.mongo,
+        mongoUrl: config.mongoUrl,
+        mongoDatabase: config.mongoDatabase,
       });
 
       await server.listen({ port: config.port, host: config.host });
@@ -177,6 +184,7 @@ program
           }
           console.log('     Do not expose to the internet!');
         }
+        if (config.mongo) console.log(`  MongoDB: ${config.mongoUrl} (${config.mongoDatabase})`);
         if (config.readOnly) console.log('  Read-only: enabled (PUT/DELETE/PATCH disabled)');
         console.log('\n  Press Ctrl+C to stop\n');
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "javascript-solid-server",
-  "version": "0.0.94",
+  "version": "0.0.95",
   "description": "A minimal, fast Solid server",
   "main": "src/index.js",
   "type": "module",
@@ -51,6 +51,9 @@
     "nostr"
   ],
   "license": "AGPL-3.0-only",
+  "optionalDependencies": {
+    "mongodb": "^6.21.0"
+  },
   "devDependencies": {
     "autocannon": "^8.0.0"
   }

package/src/config.js

@@ -83,6 +83,11 @@ export const defaults = {
   // Live reload - inject script to auto-refresh browser on file changes
   liveReload: false,
 
+  // MongoDB-backed /db/ route
+  mongo: false,
+  mongoUrl: 'mongodb://localhost:27017',
+  mongoDatabase: 'solid',
+
   // Logging
   logger: true,
   quiet: false,
@@ -133,6 +138,9 @@ const envMap = {
   JSS_PUBLIC: 'public',
   JSS_READ_ONLY: 'readOnly',
   JSS_LIVE_RELOAD: 'liveReload',
+  JSS_MONGO: 'mongo',
+  JSS_MONGO_URL: 'mongoUrl',
+  JSS_MONGO_DATABASE: 'mongoDatabase',
 };
 
 /**
@@ -297,5 +305,6 @@ export function printConfig(config) {
   console.log(`  Subdomains:    ${config.subdomains ? (config.baseDomain || 'enabled') : 'disabled'}`);
   console.log(`  Mashlib:       ${config.mashlibModule ? `module (${config.mashlibModule})` : config.mashlibCdn ? `CDN v${config.mashlibVersion}` : config.mashlib ? 'local' : 'disabled'}`);
   console.log(`  SolidOS UI:    ${config.solidosUi ? 'enabled' : 'disabled'}`);
+  if (config.mongo) console.log(`  MongoDB:       ${config.mongoUrl} (${config.mongoDatabase})`);
   console.log('─'.repeat(40));
 }

package/src/db/index.js

@@ -0,0 +1,303 @@
+/**
+ * MongoDB Database Route Plugin for JSS
+ *
+ * Adds /db/* routes backed by MongoDB.
+ * Documents are stored as JSON-LD and keyed by URI.
+ */
+
+import { connect, disconnect, findOne, upsertOne, deleteOne, listByPrefix } from './store.js';
+import { getAllHeaders, getNotFoundHeaders } from '../ldp/headers.js';
+import { generateContainerJsonLd, serializeJsonLd } from '../ldp/container.js';
+import { checkIfMatch, checkIfNoneMatchForGet, checkIfNoneMatchForWrite } from '../utils/conditional.js';
+import { emitChange } from '../notifications/events.js';
+import { getWebIdFromRequestAsync } from '../auth/token.js';
+
+/**
+ * Database route Fastify plugin
+ * @param {FastifyInstance} fastify
+ * @param {object} options
+ */
+export async function dbPlugin(fastify, options) {
+  await connect({
+    url: options.mongoUrl,
+    database: options.mongoDatabase || 'solid'
+  });
+
+  fastify.addHook('onClose', async () => {
+    await disconnect();
+  });
+
+  // Auth hook for /db/* routes
+  // WAC doesn't apply here — uses WebID-based ownership
+  fastify.addHook('preHandler', async (request, reply) => {
+    if (request.method === 'OPTIONS') return;
+
+    // Public mode — skip auth
+    if (request.config?.public) {
+      request.webId = null;
+      return;
+    }
+
+    const { webId } = await getWebIdFromRequestAsync(request);
+    request.webId = webId;
+
+    // Read is public
+    if (request.method === 'GET' || request.method === 'HEAD') return;
+
+    // Write requires authentication
+    if (!webId) {
+      return reply.code(401).send({ error: 'Unauthorized', message: 'Authentication required' });
+    }
+
+    // Ownership check: only pod owner can write to /db/{podName}/...
+    const urlPath = request.url.split('?')[0];
+    const relative = urlPath.replace(/^\/db\//, '');
+    const podName = relative.split('/')[0];
+    if (podName) {
+      // Build expected WebID for both path and subdomain modes
+      const expectedWebId = request.subdomainsEnabled && request.baseDomain
+        ? `${request.protocol}://${podName}.${request.baseDomain}/profile/card#me`
+        : `${request.protocol}://${request.hostname}/${podName}/profile/card#me`;
+      if (webId !== expectedWebId) {
+        return reply.code(403).send({ error: 'Forbidden', message: 'You can only write to your own /db/ space' });
+      }
+    }
+  });
+
+  // Routes
+  fastify.get('/db', handleDbGet);
+  fastify.get('/db/*', handleDbGet);
+  fastify.head('/db', handleDbHead);
+  fastify.head('/db/*', handleDbHead);
+  fastify.put('/db/*', handleDbPut);
+  fastify.delete('/db/*', handleDbDelete);
+  fastify.options('/db', handleDbOptions);
+  fastify.options('/db/*', handleDbOptions);
+}
+
+/**
+ * Build the full resource URL for a /db/ request
+ */
+function getResourceUrl(request) {
+  const urlPath = request.url.split('?')[0];
+  return `${request.protocol}://${request.hostname}${urlPath}`;
+}
+
+/**
+ * GET /db/* — read resource or container listing
+ */
+async function handleDbGet(request, reply) {
+  const urlPath = request.url.split('?')[0];
+  const resourceUrl = getResourceUrl(request);
+  const origin = request.headers.origin;
+  const connegEnabled = request.connegEnabled || false;
+
+  // Container request (treat /db as root container)
+  if (urlPath === '/db' || urlPath.endsWith('/')) {
+    const entries = await listByPrefix(resourceUrl);
+    const jsonLd = generateContainerJsonLd(resourceUrl, entries);
+    const content = serializeJsonLd(jsonLd);
+
+    const etag = `"container-${entries.length}"`;
+
+    const ifNoneMatch = request.headers['if-none-match'];
+    if (ifNoneMatch) {
+      const check = checkIfNoneMatchForGet(ifNoneMatch, etag);
+      if (!check.ok && check.notModified) {
+        return reply.code(304).send();
+      }
+    }
+
+    const headers = getAllHeaders({
+      isContainer: true, etag,
+      contentType: 'application/ld+json',
+      origin, resourceUrl, connegEnabled
+    });
+    Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+    return reply.send(content);
+  }
+
+  // Resource request
+  const doc = await findOne(resourceUrl);
+  if (!doc) {
+    const headers = getNotFoundHeaders({ resourceUrl, origin, connegEnabled });
+    Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+    return reply.code(404).send({ error: 'Not Found' });
+  }
+
+  const ifNoneMatch = request.headers['if-none-match'];
+  if (ifNoneMatch) {
+    const check = checkIfNoneMatchForGet(ifNoneMatch, doc.etag);
+    if (!check.ok && check.notModified) {
+      return reply.code(304).send();
+    }
+  }
+
+  const headers = getAllHeaders({
+    isContainer: false, etag: doc.etag,
+    contentType: doc.contentType,
+    origin, resourceUrl, connegEnabled
+  });
+  Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+  return reply.send(JSON.stringify(doc.data, null, 2));
+}
+
+/**
+ * HEAD /db/* — same as GET but no body
+ */
+async function handleDbHead(request, reply) {
+  const urlPath = request.url.split('?')[0];
+  const resourceUrl = getResourceUrl(request);
+  const origin = request.headers.origin;
+  const connegEnabled = request.connegEnabled || false;
+
+  if (urlPath === '/db' || urlPath.endsWith('/')) {
+    const entries = await listByPrefix(resourceUrl);
+    const etag = `"container-${entries.length}"`;
+    const headers = getAllHeaders({
+      isContainer: true, etag,
+      contentType: 'application/ld+json',
+      origin, resourceUrl, connegEnabled
+    });
+    Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+    return reply.code(200).send();
+  }
+
+  const doc = await findOne(resourceUrl);
+  if (!doc) {
+    const headers = getNotFoundHeaders({ resourceUrl, origin, connegEnabled });
+    Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+    return reply.code(404).send();
+  }
+
+  const headers = getAllHeaders({
+    isContainer: false, etag: doc.etag,
+    contentType: doc.contentType,
+    origin, resourceUrl, connegEnabled
+  });
+  Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+  return reply.code(200).send();
+}
+
+/**
+ * PUT /db/* — create or update resource
+ */
+async function handleDbPut(request, reply) {
+  if (request.config?.readOnly) {
+    return reply.code(405).send({ error: 'Method Not Allowed', message: 'Server is in read-only mode' });
+  }
+
+  const urlPath = request.url.split('?')[0];
+  const resourceUrl = getResourceUrl(request);
+
+  if (urlPath.endsWith('/')) {
+    return reply.code(409).send({ error: 'Conflict', message: 'Cannot PUT to a container' });
+  }
+
+  // Only accept JSON content types — stored as JSON-LD
+  const incomingType = (request.headers['content-type'] || '').split(';')[0].trim().toLowerCase();
+  if (incomingType && incomingType !== 'application/ld+json' && incomingType !== 'application/json') {
+    return reply.code(415).send({ error: 'Unsupported Media Type', message: 'Only application/ld+json and application/json are accepted' });
+  }
+
+  // Parse body
+  let data;
+  let body = request.body;
+  if (Buffer.isBuffer(body)) body = body.toString();
+  if (typeof body === 'string') {
+    try { data = JSON.parse(body); }
+    catch { return reply.code(400).send({ error: 'Bad Request', message: 'Invalid JSON' }); }
+  } else if (typeof body === 'object' && body !== null) {
+    data = body;
+  } else {
+    return reply.code(400).send({ error: 'Bad Request', message: 'Request body required' });
+  }
+
+  // Conditional headers
+  const existing = await findOne(resourceUrl);
+  const currentEtag = existing?.etag || null;
+
+  const ifMatch = request.headers['if-match'];
+  if (ifMatch) {
+    const check = checkIfMatch(ifMatch, currentEtag);
+    if (!check.ok) return reply.code(check.status).send({ error: check.error });
+  }
+
+  const ifNoneMatch = request.headers['if-none-match'];
+  if (ifNoneMatch) {
+    const check = checkIfNoneMatchForWrite(ifNoneMatch, currentEtag);
+    if (!check.ok) return reply.code(check.status).send({ error: check.error });
+  }
+
+  const { created, etag } = await upsertOne(resourceUrl, data, 'application/ld+json');
+
+  const origin = request.headers.origin;
+  const headers = getAllHeaders({
+    isContainer: false, etag,
+    origin, resourceUrl,
+    connegEnabled: request.connegEnabled || false
+  });
+  headers['Location'] = resourceUrl;
+  Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+
+  if (request.notificationsEnabled) {
+    emitChange(resourceUrl);
+  }
+
+  return reply.code(created ? 201 : 204).send();
+}
+
+/**
+ * DELETE /db/* — delete resource
+ */
+async function handleDbDelete(request, reply) {
+  if (request.config?.readOnly) {
+    return reply.code(405).send({ error: 'Method Not Allowed', message: 'Server is in read-only mode' });
+  }
+
+  const resourceUrl = getResourceUrl(request);
+  const origin = request.headers.origin;
+
+  const existing = await findOne(resourceUrl);
+  if (!existing) {
+    const headers = getNotFoundHeaders({ resourceUrl, origin, connegEnabled: request.connegEnabled || false });
+    Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+    return reply.code(404).send({ error: 'Not Found' });
+  }
+
+  const ifMatch = request.headers['if-match'];
+  if (ifMatch) {
+    const check = checkIfMatch(ifMatch, existing.etag);
+    if (!check.ok) return reply.code(check.status).send({ error: check.error });
+  }
+
+  await deleteOne(resourceUrl);
+
+  const headers = getAllHeaders({
+    isContainer: false, origin, resourceUrl
+  });
+  Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+
+  if (request.notificationsEnabled) {
+    emitChange(resourceUrl);
+  }
+
+  return reply.code(204).send();
+}
+
+/**
+ * OPTIONS /db/* — return allowed methods
+ */
+async function handleDbOptions(request, reply) {
+  const resourceUrl = getResourceUrl(request);
+  const origin = request.headers.origin;
+  const headers = getAllHeaders({
+    isContainer: request.url.split('?')[0] === '/db' || request.url.split('?')[0].endsWith('/'),
+    origin, resourceUrl,
+    connegEnabled: request.connegEnabled || false
+  });
+  Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+  return reply.code(204).send();
+}
+
+export default dbPlugin;

package/src/db/store.js

@@ -0,0 +1,154 @@
+/**
+ * MongoDB Storage Layer for /db/ route
+ *
+ * Optional dependency — dynamically imports 'mongodb'.
+ * Provides document-level CRUD keyed by URI.
+ */
+
+import crypto from 'crypto';
+
+let client = null;
+let db = null;
+let col = null;
+
+/**
+ * Connect to MongoDB
+ * @param {object} options
+ * @param {string} options.url - MongoDB connection URL
+ * @param {string} options.database - Database name
+ * @returns {Promise<void>}
+ */
+export async function connect({ url, database }) {
+  let MongoClient;
+  try {
+    ({ MongoClient } = await import('mongodb'));
+  } catch {
+    throw new Error(
+      'MongoDB driver not installed. Install it with: npm install mongodb\n' +
+      'The mongodb package is optional and only needed when using --mongo.'
+    );
+  }
+
+  client = new MongoClient(url);
+  await client.connect();
+  db = client.db(database);
+  col = db.collection('resources');
+
+  // Create unique index on URI for fast lookups
+  await col.createIndex({ uri: 1 }, { unique: true });
+}
+
+/**
+ * Disconnect from MongoDB
+ * @returns {Promise<void>}
+ */
+export async function disconnect() {
+  if (client) {
+    await client.close();
+    client = null;
+    db = null;
+    col = null;
+  }
+}
+
+/**
+ * Generate ETag from data
+ */
+function generateEtag(data) {
+  const hash = crypto.createHash('md5').update(JSON.stringify(data)).digest('hex');
+  return `"${hash}"`;
+}
+
+/**
+ * Find a single document by URI
+ * @param {string} uri - The resource URI
+ * @returns {Promise<{data: object, contentType: string, etag: string, modified: Date} | null>}
+ */
+export async function findOne(uri) {
+  const doc = await col.findOne({ uri });
+  if (!doc) return null;
+  return {
+    data: doc.data,
+    contentType: doc.contentType,
+    etag: doc.etag,
+    modified: doc.modified
+  };
+}
+
+/**
+ * Upsert a document by URI
+ * @param {string} uri - The resource URI
+ * @param {object} data - The document data (JSON-LD)
+ * @param {string} contentType - The content type
+ * @returns {Promise<{created: boolean, etag: string}>}
+ */
+export async function upsertOne(uri, data, contentType) {
+  const etag = generateEtag(data);
+  const now = new Date();
+
+  const result = await col.updateOne(
+    { uri },
+    {
+      $set: { data, contentType, etag, modified: now },
+      $setOnInsert: { created: now }
+    },
+    { upsert: true }
+  );
+
+  return {
+    created: result.upsertedCount > 0,
+    etag
+  };
+}
+
+/**
+ * Delete a document by URI
+ * @param {string} uri - The resource URI
+ * @returns {Promise<boolean>} - true if deleted, false if not found
+ */
+export async function deleteOne(uri) {
+  const result = await col.deleteOne({ uri });
+  return result.deletedCount > 0;
+}
+
+/**
+ * Escape special regex characters in a string
+ */
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * List immediate children whose URI starts with a prefix (for container listings)
+ * @param {string} prefix - URI prefix (must end with '/')
+ * @returns {Promise<Array<{name: string, isDirectory: boolean}>>}
+ */
+export async function listByPrefix(prefix) {
+  const regex = new RegExp('^' + escapeRegex(prefix));
+  const docs = await col.find({ uri: regex }, { projection: { uri: 1 } }).toArray();
+
+  const children = new Map();
+  for (const doc of docs) {
+    const remainder = doc.uri.slice(prefix.length);
+    if (!remainder) continue;
+    const slashIndex = remainder.indexOf('/');
+    if (slashIndex === -1) {
+      // Direct child resource
+      children.set(remainder, false);
+    } else {
+      // Nested under a sub-container
+      const containerName = remainder.slice(0, slashIndex);
+      children.set(containerName, true);
+    }
+  }
+
+  return Array.from(children.entries()).map(([name, isDirectory]) => ({ name, isDirectory }));
+}
+
+/**
+ * Check if MongoDB is connected
+ * @returns {boolean}
+ */
+export function isConnected() {
+  return client !== null;
+}

package/src/server.js

@@ -15,6 +15,7 @@ import { isGitRequest, isGitWriteOperation, handleGit } from './handlers/git.js'
 import { AccessMode } from './wac/parser.js';
 import { registerNostrRelay } from './nostr/relay.js';
 import { activityPubPlugin, getActorHandler } from './ap/index.js';
+import { dbPlugin } from './db/index.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -84,6 +85,10 @@ export function createServer(options = {}) {
   const webidTlsEnabled = options.webidTls ?? false;
   // Live reload - injects script to auto-refresh browser on file changes
   const liveReloadEnabled = options.liveReload ?? false;
+  // MongoDB-backed /db/ route is OFF by default
+  const mongoEnabled = options.mongo ?? false;
+  const mongoUrl = options.mongoUrl ?? 'mongodb://localhost:27017';
+  const mongoDatabase = options.mongoDatabase ?? 'solid';
 
   // Set data root via environment variable if provided
   if (options.root) {
@@ -229,6 +234,11 @@ export function createServer(options = {}) {
     });
   }
 
+  // Register MongoDB /db/ route if enabled
+  if (mongoEnabled) {
+    fastify.register(dbPlugin, { mongoUrl, mongoDatabase });
+  }
+
   // Register rate limiting plugin
   // Protects against brute force attacks and resource exhaustion
   fastify.register(rateLimit, {
@@ -358,6 +368,7 @@ export function createServer(options = {}) {
         (gitEnabled && isGitRequest(request.url)) ||
         (activitypubEnabled && apPaths.some(p => request.url === p || request.url.startsWith(p + '?'))) ||
         isProfileAP ||
+        (mongoEnabled && (request.url === '/db' || request.url.startsWith('/db/'))) ||
         mashlibPaths.some(p => request.url === p || request.url.startsWith(p + '.'))) {
       return;
     }