javascript-solid-server 0.0.83 → 0.0.85

package/.claude/settings.local.json

@@ -320,7 +320,10 @@
       "WebFetch(domain:remotestorage.io)",
       "Bash(gh issue create --title \"Feature: --public flag to skip WAC and allow open access\" --body \"$\\(cat << ''ENDOFFILE''\n## Summary\n\nAdd a `--public` flag that disables WAC \\(Web Access Control\\) checks, allowing unauthenticated read/write access to all resources. This enables JSS to be used as a simple file server similar to `npx serve`, but with REST write capabilities.\n\n**Difficulty**: 15/100  \n**Estimated Effort**: 2-4 hours  \n**Dependencies**: None\n\n---\n\n## Motivation\n\nCurrently, JSS requires either:\n1. ACL files to grant access, or\n2. Authentication via Solid-OIDC\n\nThis makes it impossible to use JSS as a simple \"just serve this folder\" tool like `npx serve`. The `--public` flag would enable:\n\n1. **Quick local development** - No auth setup needed\n2. **Simple file sharing** - LAN file server with write support\n3. **jsserve wrapper** - Foundation for `npx jsserve` \\(see future issue\\)\n4. **WebDAV alternative** - Simple REST-based file server\n5. **Testing/demos** - Quick Solid server without auth complexity\n\n---\n\n## Proposed Implementation\n\n### CLI Flag\n\n```bash\njss start --public              # Open read/write, no auth\njss start --public --read-only  # Open read, no writes \\(like npx serve\\)\n```\n\n### Environment Variable\n\n```bash\nJSS_PUBLIC=true jss start\n```\n\n### Config File\n\n```json\n{\n  \"public\": true\n}\n```\n\n---\n\n## Implementation Details\n\n### 1. Add flag to CLI \\(`bin/jss.js`\\)\n\n```javascript\n.option\\(''--public'', ''Allow unauthenticated access to all resources \\(disables WAC\\)''\\)\n.option\\(''--read-only'', ''Disable PUT/DELETE methods \\(read-only mode\\)''\\)\n```\n\n### 2. Add to config \\(`src/config.js`\\)\n\n```javascript\nconst DEFAULTS = {\n  // ... existing ...\n  public: false,\n  readOnly: false,\n};\n\n// Environment variable mapping\nif \\(process.env.JSS_PUBLIC\\) {\n  config.public = process.env.JSS_PUBLIC === ''true'';\n}\nif \\(process.env.JSS_READ_ONLY\\) {\n  config.readOnly = process.env.JSS_READ_ONLY === ''true'';\n}\n```\n\n### 3. Skip WAC when public \\(`src/auth/middleware.js`\\)\n\n```javascript\nexport async function authorize\\(request, reply\\) {\n  // Public mode - skip all auth/WAC checks\n  if \\(request.config?.public\\) {\n    return; // Allow request to proceed\n  }\n  \n  // ... existing WAC logic ...\n}\n```\n\n### 4. Block writes when read-only \\(`src/handlers/resource.js`, `src/handlers/container.js`\\)\n\n```javascript\n// At start of PUT/DELETE handlers\nif \\(request.config?.readOnly\\) {\n  return reply.code\\(405\\).send\\({ \n    error: ''Method Not Allowed'',\n    message: ''Server is in read-only mode''\n  }\\);\n}\n```\n\n---\n\n## Behavior Matrix\n\n| Flag Combination | GET | PUT/DELETE | Auth Required |\n|------------------|-----|------------|---------------|\n| \\(default\\) | ACL | ACL | Yes \\(if ACL requires\\) |\n| `--public` | ✅ Allow | ✅ Allow | No |\n| `--public --read-only` | ✅ Allow | ❌ Block | No |\n| `--read-only` \\(no public\\) | ACL | ❌ Block | Yes |\n\n---\n\n## Security Considerations\n\n### Warning on Startup\n\nWhen `--public` is enabled, show a clear warning:\n\n```\n⚠️  WARNING: Server running in PUBLIC mode\n   All files are readable and writable without authentication.\n   Do not use in production or expose to the internet.\n```\n\n### Binding to localhost by default?\n\nConsider: When `--public` is set, should the default host be `localhost` instead of `0.0.0.0`?\n\n```javascript\nif \\(config.public && !explicitHostSet\\) {\n  config.host = ''localhost''; // Safer default for public mode\n}\n```\n\nUser can override with `--public --host 0.0.0.0` if they explicitly want network access.\n\n---\n\n## Examples\n\n### Local Development\n```bash\n# Quick Solid-compatible file server for development\njss start --public --port 3000 --root ./test-data\n```\n\n### Read-Only File Sharing\n```bash\n# Share files on LAN, no writes allowed\njss start --public --read-only --host 0.0.0.0 --root ~/shared\n```\n\n### Testing Solid Apps\n```bash\n# Test app without auth complexity\njss start --public --root ./fixtures\nnpm test\n```\n\n---\n\n## Files to Modify\n\n| File | Changes |\n|------|---------|\n| `bin/jss.js` | Add `--public` and `--read-only` options \\(~5 LOC\\) |\n| `src/config.js` | Add defaults and env var mapping \\(~10 LOC\\) |\n| `src/auth/middleware.js` | Skip WAC when public \\(~5 LOC\\) |\n| `src/handlers/resource.js` | Block writes when read-only \\(~5 LOC\\) |\n| `src/handlers/container.js` | Block writes when read-only \\(~5 LOC\\) |\n| **Total** | **~30 LOC** |\n\n---\n\n## Testing\n\n```javascript\ndescribe\\(''--public flag'', \\(\\) => {\n  it\\(''should allow unauthenticated GET'', async \\(\\) => {\n    const server = await createServer\\({ public: true, root: tmpDir }\\);\n    const res = await request\\(server\\).get\\(''/file.txt''\\);\n    expect\\(res.status\\).toBe\\(200\\);\n  }\\);\n\n  it\\(''should allow unauthenticated PUT'', async \\(\\) => {\n    const server = await createServer\\({ public: true, root: tmpDir }\\);\n    const res = await request\\(server\\)\n      .put\\(''/new-file.txt''\\)\n      .send\\(''content''\\);\n    expect\\(res.status\\).toBe\\(201\\);\n  }\\);\n\n  it\\(''should block PUT when read-only'', async \\(\\) => {\n    const server = await createServer\\({ public: true, readOnly: true, root: tmpDir }\\);\n    const res = await request\\(server\\)\n      .put\\(''/new-file.txt''\\)\n      .send\\(''content''\\);\n    expect\\(res.status\\).toBe\\(405\\);\n  }\\);\n}\\);\n```\n\n---\n\n## Related Issues\n\n- Future: `jsserve` package \\(thin wrapper using this flag\\)\n- #100 - Production Readiness \\(this is a dev/convenience feature\\)\n\n---\n\n## Open Questions\n\n1. Should `--public` default to `localhost` binding for safety?\n2. Should there be a `--public-read` \\(read-only public\\) shorthand?\n3. Should `--public` disable IdP/login UI entirely, or just make it optional?\nENDOFFILE\n\\)\")",
       "Bash(npx serve --help:*)",
-      "Bash(npm exec serve:*)"
+      "Bash(npm exec serve:*)",
+      "Bash(npm link)",
+      "Bash(npm link:*)",
+      "Bash(git push)"
     ]
   }
 }

package/bin/jss.js

@@ -78,6 +78,7 @@ program
   .option('--no-webid-tls', 'Disable WebID-TLS authentication')
   .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('-q, --quiet', 'Suppress log output')
   .option('--print-config', 'Print configuration and exit')
   .action(async (options) => {
@@ -135,6 +136,7 @@ program
         singleUserName: config.singleUserName,
         public: config.public,
         readOnly: config.readOnly,
+        liveReload: config.liveReload,
       });
 
       await server.listen({ port: config.port, host: config.host });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "javascript-solid-server",
-  "version": "0.0.83",
+  "version": "0.0.85",
   "description": "A minimal, fast Solid server",
   "main": "src/index.js",
   "type": "module",

package/src/config.js

@@ -79,6 +79,9 @@ export const defaults = {
   // Read-only mode - disable PUT/DELETE/PATCH
   readOnly: false,
 
+  // Live reload - inject script to auto-refresh browser on file changes
+  liveReload: false,
+
   // Logging
   logger: true,
   quiet: false,
@@ -125,6 +128,7 @@ const envMap = {
   JSS_DEFAULT_QUOTA: 'defaultQuota',
   JSS_PUBLIC: 'public',
   JSS_READ_ONLY: 'readOnly',
+  JSS_LIVE_RELOAD: 'liveReload',
 };
 
 /**

package/src/handlers/resource.js

@@ -17,6 +17,23 @@ import { emitChange } from '../notifications/events.js';
 import { checkIfMatch, checkIfNoneMatchForGet, checkIfNoneMatchForWrite } from '../utils/conditional.js';
 import { generateDatabrowserHtml, generateSolidosUiHtml, shouldServeMashlib } from '../mashlib/index.js';
 
+/**
+ * Live reload script - injected into HTML when --live-reload is enabled
+ */
+const LIVE_RELOAD_SCRIPT = `<script>(function(){var ws=new WebSocket((location.protocol==='https:'?'wss:':'ws:')+'//' +location.host+'/.notifications');ws.onopen=function(){ws.send('sub '+location.href)};ws.onmessage=function(e){if(e.data.startsWith('pub '))location.reload()};ws.onclose=function(){setTimeout(function(){location.reload()},1000)}})();</script>`;
+
+/**
+ * Inject live reload script into HTML content
+ */
+function injectLiveReload(content) {
+  const html = content.toString();
+  // Inject before </body> or at end
+  if (html.includes('</body>')) {
+    return Buffer.from(html.replace('</body>', LIVE_RELOAD_SCRIPT + '</body>'));
+  }
+  return Buffer.from(html + LIVE_RELOAD_SCRIPT);
+}
+
 /**
  * Get the storage path and resource URL for a request
  * In subdomain mode, storage path includes pod name, URL uses subdomain
@@ -198,6 +215,12 @@ export async function handleGet(request, reply) {
       });
 
       Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+      // Inject live reload script for index.html
+      if (request.liveReloadEnabled) {
+        reply.header('Cache-Control', 'no-store');
+        reply.removeHeader('ETag');
+        return reply.send(injectLiveReload(content));
+      }
       return reply.send(content);
     }
 
@@ -439,6 +462,13 @@ export async function handleGet(request, reply) {
   headers['Vary'] = getVaryHeader(connegEnabled, request.mashlibEnabled);
 
   Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+
+  // Inject live reload script into HTML (disable caching since content is modified)
+  if (actualContentType === 'text/html' && request.liveReloadEnabled) {
+    reply.header('Cache-Control', 'no-store');
+    reply.removeHeader('ETag');
+    return reply.send(injectLiveReload(content));
+  }
   return reply.send(content);
 }
 

package/src/notifications/events.js

@@ -6,6 +6,8 @@
  */
 
 import { EventEmitter } from 'events';
+import { watch } from 'fs';
+import { join, relative } from 'path';
 
 // Singleton event emitter for resource changes
 export const resourceEvents = new EventEmitter();
@@ -20,3 +22,56 @@ resourceEvents.setMaxListeners(1000);
 export function emitChange(resourceUrl) {
   resourceEvents.emit('change', resourceUrl);
 }
+
+/**
+ * Start watching filesystem for changes and emit notifications
+ * @param {string} rootDir - Directory to watch
+ * @param {string} baseUrl - Base URL for constructing resource URLs (e.g., http://localhost:3000)
+ */
+export function startFileWatcher(rootDir, baseUrl) {
+  // Debounce map to avoid duplicate events (editors often save multiple times)
+  const debounceMap = new Map();
+  const DEBOUNCE_MS = 100;
+
+  try {
+    const watcher = watch(rootDir, { recursive: true }, (eventType, filename) => {
+      if (!filename) return;
+
+      // Skip hidden files and common temp files
+      if (filename.startsWith('.') || filename.endsWith('~') || filename.endsWith('.swp')) {
+        return;
+      }
+
+      // Debounce: skip if we just emitted for this file
+      const now = Date.now();
+      const lastEmit = debounceMap.get(filename);
+      if (lastEmit && now - lastEmit < DEBOUNCE_MS) {
+        return;
+      }
+      debounceMap.set(filename, now);
+
+      // Clean up old debounce entries periodically
+      if (debounceMap.size > 1000) {
+        for (const [key, time] of debounceMap) {
+          if (now - time > 5000) debounceMap.delete(key);
+        }
+      }
+
+      // Construct resource URL
+      const resourcePath = '/' + filename.replace(/\\/g, '/');
+      const resourceUrl = baseUrl.replace(/\/$/, '') + resourcePath;
+
+      emitChange(resourceUrl);
+    });
+
+    // Handle watcher errors gracefully
+    watcher.on('error', (err) => {
+      console.error('File watcher error:', err.message);
+    });
+
+    return watcher;
+  } catch (err) {
+    console.error('Failed to start file watcher:', err.message);
+    return null;
+  }
+}

package/src/server.js

@@ -9,6 +9,7 @@ import * as storage from './storage/filesystem.js';
 import { getCorsHeaders } from './ldp/headers.js';
 import { authorize, handleUnauthorized } from './auth/middleware.js';
 import { notificationsPlugin } from './notifications/index.js';
+import { startFileWatcher } from './notifications/events.js';
 import { idpPlugin } from './idp/index.js';
 import { isGitRequest, isGitWriteOperation, handleGit } from './handlers/git.js';
 import { AccessMode } from './wac/parser.js';
@@ -79,6 +80,8 @@ export function createServer(options = {}) {
   const defaultQuota = options.defaultQuota ?? 50 * 1024 * 1024;
   // WebID-TLS client certificate authentication is OFF by default
   const webidTlsEnabled = options.webidTls ?? false;
+  // Live reload - injects script to auto-refresh browser on file changes
+  const liveReloadEnabled = options.liveReload ?? false;
 
   // Set data root via environment variable if provided
   if (options.root) {
@@ -136,9 +139,10 @@ export function createServer(options = {}) {
   fastify.decorateRequest('solidosUiEnabled', null);
   fastify.decorateRequest('defaultQuota', null);
   fastify.decorateRequest('config', null);
+  fastify.decorateRequest('liveReloadEnabled', null);
   fastify.addHook('onRequest', async (request) => {
     request.connegEnabled = connegEnabled;
-    request.notificationsEnabled = notificationsEnabled;
+    request.notificationsEnabled = notificationsEnabled || liveReloadEnabled;
     request.idpEnabled = idpEnabled;
     request.subdomainsEnabled = subdomainsEnabled;
     request.baseDomain = baseDomain;
@@ -148,6 +152,7 @@ export function createServer(options = {}) {
     request.solidosUiEnabled = solidosUiEnabled;
     request.defaultQuota = defaultQuota;
     request.config = { public: options.public, readOnly: options.readOnly };
+    request.liveReloadEnabled = liveReloadEnabled;
 
     // Extract pod name from subdomain if enabled
     if (subdomainsEnabled && baseDomain) {
@@ -164,8 +169,8 @@ export function createServer(options = {}) {
     }
   });
 
-  // Register WebSocket notifications plugin if enabled
-  if (notificationsEnabled) {
+  // Register WebSocket notifications plugin if enabled (or live reload needs it)
+  if (notificationsEnabled || liveReloadEnabled) {
     fastify.register(notificationsPlugin);
   }
 
@@ -538,6 +543,16 @@ export function createServer(options = {}) {
     // Note: Quota not initialized for root-level pods (no user directory)
   }
 
+  // Start file watcher for live reload (watches filesystem for external changes)
+  if (liveReloadEnabled) {
+    const dataRoot = options.root || process.env.DATA_ROOT || './data';
+    const protocol = options.ssl ? 'https' : 'http';
+    // Use configured port, or default; actual URL will be localhost
+    const port = options.port || 3000;
+    const baseUrl = `${protocol}://localhost:${port}`;
+    startFileWatcher(dataRoot, baseUrl);
+  }
+
   return fastify;
 }