javascript-solid-server 0.0.151 → 0.0.153

package/.claude/settings.local.json

@@ -355,7 +355,9 @@
       "Read(//home/melvin/remote/github.com/solid-helper/core/**)",
       "Bash(curl -s https://www.gnu.org/licenses/agpl-3.0.txt)",
       "Bash(cat LICENSE.full)",
-      "Bash(rm LICENSE.full)"
+      "Bash(rm LICENSE.full)",
+      "Bash(awk -F: '{print $1,$2}')",
+      "Bash(awk -F: '{print $1}')"
     ]
   }
 }

package/package.json

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

package/src/handlers/container.js

@@ -5,7 +5,7 @@ import { isContainer, getEffectiveUrlPath, getPodName } from '../utils/url.js';
 import { generateProfile, generatePreferences, generateTypeIndex, serialize } from '../webid/profile.js';
 import { generateOwnerAcl, generatePrivateAcl, generateInboxAcl, generatePublicFolderAcl, serializeAcl } from '../wac/parser.js';
 import { createToken } from '../auth/token.js';
-import { canAcceptInput, toJsonLd, getVaryHeader, RDF_TYPES } from '../rdf/conneg.js';
+import { canAcceptInput, toJsonLd, RDF_TYPES } from '../rdf/conneg.js';
 import { emitChange } from '../notifications/events.js';
 
 /**
@@ -138,10 +138,10 @@ export async function handlePost(request, reply) {
   const headers = getAllHeaders({
     isContainer: isCreatingContainer,
     origin,
-    connegEnabled
+    connegEnabled,
+    mashlibEnabled: request.mashlibEnabled
   });
   headers['Location'] = resourceUrl;
-  headers['Vary'] = getVaryHeader(connegEnabled);
 
   Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
 

package/src/handlers/resource.js

@@ -10,7 +10,6 @@ import {
   canAcceptInput,
   toJsonLd,
   fromJsonLd,
-  getVaryHeader,
   RDF_TYPES
 } from '../rdf/conneg.js';
 import { emitChange } from '../notifications/events.js';
@@ -22,6 +21,12 @@ import { generateDatabrowserHtml, generateModuleDatabrowserHtml, shouldServeMash
  */
 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>`;
 
+// Cache-Control for RDF data responses: let clients keep the body but force
+// revalidation via ETag on every use. This prevents stale bodies from leaking
+// across auth-state changes (WAC) and closes the mashlib render-race window
+// where a cached data variant was served on top-level navigation (#315).
+const RDF_CACHE_CONTROL = 'private, no-cache, must-revalidate';
+
 /**
  * Inject live reload script into HTML content
  */
@@ -181,6 +186,7 @@ export async function handleGet(request, reply) {
                 resourceUrl,
                 connegEnabled
               });
+              headers['Cache-Control'] = RDF_CACHE_CONTROL;
 
               Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
               return reply.send(turtleContent);
@@ -194,6 +200,7 @@ export async function handleGet(request, reply) {
                 resourceUrl,
                 connegEnabled
               });
+              headers['Cache-Control'] = RDF_CACHE_CONTROL;
 
               Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
               return reply.send(JSON.stringify(jsonLd, null, 2));
@@ -239,9 +246,9 @@ export async function handleGet(request, reply) {
         contentType: 'text/html',
         origin,
         resourceUrl,
-        connegEnabled
+        connegEnabled,
+        mashlibEnabled: request.mashlibEnabled
       });
-      headers['Vary'] = 'Accept';
       headers['X-Frame-Options'] = 'DENY';
       headers['Content-Security-Policy'] = "frame-ancestors 'none'";
       headers['Cache-Control'] = 'no-store';
@@ -274,9 +281,10 @@ export async function handleGet(request, reply) {
           contentType: 'text/turtle',
           origin,
           resourceUrl,
-          connegEnabled
+          connegEnabled,
+          mashlibEnabled: request.mashlibEnabled
         });
-        headers['Vary'] = 'Accept';
+        headers['Cache-Control'] = RDF_CACHE_CONTROL;
 
         Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
         return reply.send(turtleContent);
@@ -292,8 +300,10 @@ export async function handleGet(request, reply) {
       contentType: 'application/ld+json',
       origin,
       resourceUrl,
-      connegEnabled
+      connegEnabled,
+      mashlibEnabled: request.mashlibEnabled
     });
+    headers['Cache-Control'] = RDF_CACHE_CONTROL;
 
     Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
     return reply.send(serializeJsonLd(jsonLd));
@@ -315,9 +325,9 @@ export async function handleGet(request, reply) {
       contentType: 'text/html',
       origin,
       resourceUrl,
-      connegEnabled
+      connegEnabled,
+      mashlibEnabled: request.mashlibEnabled
     });
-    headers['Vary'] = 'Accept';
     headers['X-Frame-Options'] = 'DENY';
     headers['Content-Security-Policy'] = "frame-ancestors 'none'";
     // Don't cache the HTML wrapper - always negotiate fresh
@@ -397,9 +407,10 @@ export async function handleGet(request, reply) {
             contentType: 'text/turtle',
             origin,
             resourceUrl,
-            connegEnabled
+            connegEnabled,
+            mashlibEnabled: request.mashlibEnabled
           });
-          headers['Vary'] = getVaryHeader(connegEnabled, request.mashlibEnabled);
+          headers['Cache-Control'] = RDF_CACHE_CONTROL;
 
           Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
           return reply.send(turtleContent);
@@ -427,9 +438,10 @@ export async function handleGet(request, reply) {
           contentType: outputType,
           origin,
           resourceUrl,
-          connegEnabled
+          connegEnabled,
+          mashlibEnabled: request.mashlibEnabled
         });
-        headers['Vary'] = getVaryHeader(connegEnabled, request.mashlibEnabled);
+        headers['Cache-Control'] = RDF_CACHE_CONTROL;
 
         Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
         return reply.send(outputContent);
@@ -455,9 +467,12 @@ export async function handleGet(request, reply) {
     contentType: actualContentType,
     origin,
     resourceUrl,
-    connegEnabled
+    connegEnabled,
+    mashlibEnabled: request.mashlibEnabled
   });
-  headers['Vary'] = getVaryHeader(connegEnabled, request.mashlibEnabled);
+  if (isRdfContentType(actualContentType)) {
+    headers['Cache-Control'] = RDF_CACHE_CONTROL;
+  }
 
   Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
 
@@ -671,9 +686,8 @@ export async function handlePut(request, reply) {
   }
 
   const origin = request.headers.origin;
-  const headers = getAllHeaders({ isContainer: false, origin, resourceUrl, connegEnabled });
+  const headers = getAllHeaders({ isContainer: false, origin, resourceUrl, connegEnabled, mashlibEnabled: request.mashlibEnabled });
   headers['Location'] = resourceUrl;
-  headers['Vary'] = getVaryHeader(connegEnabled, request.mashlibEnabled);
 
   Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
 

package/src/ldp/headers.js

@@ -2,7 +2,7 @@
  * LDP (Linked Data Platform) header utilities
  */
 
-import { getAcceptHeaders } from '../rdf/conneg.js';
+import { getAcceptHeaders, getVaryHeader } from '../rdf/conneg.js';
 
 const LDP = 'http://www.w3.org/ns/ldp#';
 
@@ -49,7 +49,7 @@ export function getAclUrl(resourceUrl, isContainer) {
  * @param {object} options
  * @returns {object}
  */
-export function getResponseHeaders({ isContainer = false, etag = null, contentType = null, resourceUrl = null, wacAllow = null, connegEnabled = false, updatesVia = null }) {
+export function getResponseHeaders({ isContainer = false, etag = null, contentType = null, resourceUrl = null, wacAllow = null, connegEnabled = false, mashlibEnabled = false, updatesVia = null }) {
   // Calculate ACL URL if resource URL provided
   const aclUrl = resourceUrl ? getAclUrl(resourceUrl, isContainer) : null;
 
@@ -58,7 +58,7 @@ export function getResponseHeaders({ isContainer = false, etag = null, contentTy
     'Accept-Patch': 'text/n3, application/sparql-update',
     'Accept-Ranges': isContainer ? 'none' : 'bytes',
     'Allow': 'GET, HEAD, PUT, DELETE, PATCH, OPTIONS' + (isContainer ? ', POST' : ''),
-    'Vary': connegEnabled ? 'Accept, Authorization, Origin' : 'Authorization, Origin'
+    'Vary': getVaryHeader(connegEnabled, mashlibEnabled)
   };
 
   // Only set WAC-Allow if explicitly provided (otherwise the auth hook sets it)
@@ -107,9 +107,9 @@ export function getCorsHeaders(origin) {
  * @param {object} options
  * @returns {object}
  */
-export function getAllHeaders({ isContainer = false, etag = null, contentType = null, origin = null, resourceUrl = null, wacAllow = null, connegEnabled = false, updatesVia = null }) {
+export function getAllHeaders({ isContainer = false, etag = null, contentType = null, origin = null, resourceUrl = null, wacAllow = null, connegEnabled = false, mashlibEnabled = false, updatesVia = null }) {
   return {
-    ...getResponseHeaders({ isContainer, etag, contentType, resourceUrl, wacAllow, connegEnabled, updatesVia }),
+    ...getResponseHeaders({ isContainer, etag, contentType, resourceUrl, wacAllow, connegEnabled, mashlibEnabled, updatesVia }),
     ...getCorsHeaders(origin)
   };
 }
@@ -120,7 +120,7 @@ export function getAllHeaders({ isContainer = false, etag = null, contentType =
  * @param {object} options
  * @returns {object}
  */
-export function getNotFoundHeaders({ resourceUrl = null, origin = null, connegEnabled = false }) {
+export function getNotFoundHeaders({ resourceUrl = null, origin = null, connegEnabled = false, mashlibEnabled = false }) {
   // Determine if this would be a container based on URL ending with /
   const isContainer = resourceUrl?.endsWith('/') || false;
   const aclUrl = resourceUrl ? getAclUrl(resourceUrl, isContainer) : null;
@@ -134,7 +134,7 @@ export function getNotFoundHeaders({ resourceUrl = null, origin = null, connegEn
     'Accept-Patch': 'text/n3, application/sparql-update',
     'Accept-Put': acceptHeaders['Accept-Put'] || 'application/ld+json, */*',
     'Allow': 'GET, HEAD, PUT, PATCH, OPTIONS' + (isContainer ? ', POST' : ''),
-    'Vary': connegEnabled ? 'Accept, Authorization, Origin' : 'Authorization, Origin'
+    'Vary': getVaryHeader(connegEnabled, mashlibEnabled)
   };
 
   if (isContainer && acceptHeaders['Accept-Post']) {

package/src/rdf/conneg.js

@@ -189,10 +189,19 @@ export async function fromJsonLd(jsonLd, targetType, baseUri, connegEnabled = fa
 
 /**
  * Get Vary header value for content negotiation
- * Include Accept when conneg or mashlib is enabled (response varies by Accept header)
+ *
+ * Must be identical across all variants of a given URL — inconsistent Vary
+ * across variants confuses browser caches and can cause the wrong variant
+ * to be served on reload (see #315).
+ *
+ * - `Accept` — response body depends on Accept (conneg or mashlib HTML shell)
+ * - `Authorization` — response body depends on the authenticated user (WAC)
+ * - `Origin` — CORS headers echo the request's Origin
  */
 export function getVaryHeader(connegEnabled, mashlibEnabled = false) {
-  return (connegEnabled || mashlibEnabled) ? 'Accept, Origin' : 'Origin';
+  return (connegEnabled || mashlibEnabled)
+    ? 'Accept, Authorization, Origin'
+    : 'Authorization, Origin';
 }
 
 /**

package/src/server.js

@@ -21,6 +21,7 @@ import { dbPlugin } from './db/index.js';
 import { webrtcPlugin } from './webrtc/index.js';
 import { tunnelPlugin } from './tunnel/index.js';
 import { terminalPlugin } from './terminal/index.js';
+import { registerErrorHandler } from './utils/error-handler.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -154,6 +155,7 @@ export function createServer(options = {}) {
   }
 
   const fastify = Fastify(fastifyOptions);
+  registerErrorHandler(fastify);
 
   // Add raw body parser for all content types
   fastify.addContentTypeParser('*', { parseAs: 'buffer' }, (req, body, done) => {

package/src/utils/error-handler.js

@@ -0,0 +1,24 @@
+/**
+ * Top-level Fastify error handler that logs the full stack for any 5xx.
+ *
+ * Without this, 500 responses carry only Fastify's default 91-byte body and
+ * leave no trace in logs — production debugging has to infer the exception
+ * from the response body alone (see #309 investigation for why that's bad).
+ *
+ * 4xx errors carry their own statusCode and don't need stack logging — they
+ * are expected client errors with self-explanatory messages.
+ */
+export function registerErrorHandler(fastify) {
+  fastify.setErrorHandler(function (err, request, reply) {
+    const statusCode = err.statusCode ?? 500;
+    if (statusCode >= 500) {
+      request.log.error({
+        err,
+        method: request.method,
+        url: request.url,
+        hostname: request.hostname
+      }, 'Unhandled 5xx error');
+    }
+    reply.send(err);
+  });
+}

package/test/error-handler.test.js

@@ -0,0 +1,83 @@
+/**
+ * Tests for the top-level error handler (#312).
+ *
+ * Verifies that:
+ *  1. Unhandled exceptions from route handlers produce a 500 whose body
+ *     matches Fastify's default shape — the existing 91-byte response
+ *     format must not regress (that's the baseline consumers rely on).
+ *  2. The error's stack is actually logged (with method/url/hostname
+ *     context), so production debugging has a real trace.
+ *  3. 4xx errors are NOT stack-logged (they're expected client errors).
+ *
+ * Uses a minimal Fastify instance so the test exercises only the handler,
+ * not the full server's auth/routing stack.
+ */
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert';
+import Fastify from 'fastify';
+import { registerErrorHandler } from '../src/utils/error-handler.js';
+
+class LogCapture {
+  constructor() { this.lines = []; }
+  write(chunk) {
+    try { this.lines.push(JSON.parse(chunk)); } catch { /* non-JSON */ }
+    return true;
+  }
+  errorLines() {
+    return this.lines.filter((l) => l.level >= 50);
+  }
+  clear() { this.lines.length = 0; }
+}
+
+describe('registerErrorHandler (#312)', () => {
+  let app;
+  const capture = new LogCapture();
+
+  before(async () => {
+    app = Fastify({
+      logger: { level: 'error', stream: capture },
+      disableRequestLogging: true
+    });
+    registerErrorHandler(app);
+    app.get('/throw500', async () => { throw new Error('synthetic 5xx for test'); });
+    app.get('/throw400', async () => {
+      const err = new Error('bad client input');
+      err.statusCode = 400;
+      throw err;
+    });
+  });
+
+  after(async () => { await app.close(); });
+
+  it('500 response body matches Fastify default shape (no regression)', async () => {
+    capture.clear();
+    const res = await app.inject({ method: 'GET', url: '/throw500' });
+    assert.strictEqual(res.statusCode, 500);
+    assert.deepStrictEqual(res.json(), {
+      statusCode: 500,
+      error: 'Internal Server Error',
+      message: 'synthetic 5xx for test'
+    });
+  });
+
+  it('500 logs include the stack and request context', async () => {
+    capture.clear();
+    await app.inject({ method: 'GET', url: '/throw500', headers: { host: 'example.test' } });
+    const line = capture.errorLines().find((l) => l.msg === 'Unhandled 5xx error');
+    assert.ok(line, `expected 'Unhandled 5xx error' log line, got: ${JSON.stringify(capture.errorLines())}`);
+    assert.strictEqual(line.method, 'GET');
+    assert.strictEqual(line.url, '/throw500');
+    assert.strictEqual(line.hostname, 'example.test');
+    assert.ok(line.err && line.err.stack, 'expected err.stack in log');
+    assert.ok(line.err.stack.includes('synthetic 5xx'), 'stack should identify the error');
+  });
+
+  it('4xx errors do not trigger the 5xx stack log', async () => {
+    capture.clear();
+    const res = await app.inject({ method: 'GET', url: '/throw400' });
+    assert.strictEqual(res.statusCode, 400);
+    const unhandled = capture.errorLines().filter((l) => l.msg === 'Unhandled 5xx error');
+    assert.strictEqual(unhandled.length, 0, '4xx must not produce a 5xx stack log');
+  });
+});

package/test/vary-cache-headers.test.js

@@ -0,0 +1,114 @@
+/**
+ * Regression tests for #315 — inconsistent Vary / Cache-Control across
+ * conneg variants caused stale-render races on browser reload.
+ *
+ * What we guarantee now:
+ *  - Every variant of the same URL returns an *identical* Vary header.
+ *  - RDF data variants carry Cache-Control that forces revalidation via
+ *    ETag, so a cached body cannot silently serve across auth changes or
+ *    be picked up on a top-level navigation by mistake.
+ *  - The mashlib HTML wrapper keeps `no-store` (it's a bootstrap template).
+ */
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert';
+import {
+  startTestServer,
+  stopTestServer,
+  request,
+  createTestPod
+} from './helpers.js';
+
+describe('Vary / Cache-Control consistency (#315)', () => {
+  before(async () => {
+    await startTestServer({ conneg: true, mashlibCdn: true });
+    await createTestPod('varytest');
+    // Create a JSON-LD resource to exercise all variants.
+    await request('/varytest/public/card.jsonld', {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/ld+json' },
+      body: JSON.stringify({
+        '@context': { foaf: 'http://xmlns.com/foaf/0.1/' },
+        '@id': '#me',
+        'foaf:name': 'Vary Test'
+      }),
+      auth: 'varytest'
+    });
+  });
+
+  after(async () => { await stopTestServer(); });
+
+  it('Vary header is identical across all conneg variants of the same URL', async () => {
+    const accepts = [
+      'text/html,*/*;q=0.8',              // mashlib HTML wrapper
+      'text/turtle',                        // Turtle conversion
+      'application/ld+json'                 // native JSON-LD
+    ];
+    const varyValues = [];
+    for (const accept of accepts) {
+      const res = await request('/varytest/public/card.jsonld', { headers: { Accept: accept } });
+      varyValues.push({ accept, vary: res.headers.get('vary') });
+    }
+    // All three variants must carry the same Vary — inconsistent Vary is
+    // what confused browser caches into serving the wrong variant.
+    const uniqueVaryValues = new Set(varyValues.map((v) => v.vary));
+    assert.strictEqual(uniqueVaryValues.size, 1,
+      `expected identical Vary across variants, got: ${JSON.stringify(varyValues)}`);
+    const vary = [...uniqueVaryValues][0];
+    assert.ok(vary, `expected Vary header across variants, got: ${JSON.stringify(varyValues)}`);
+    assert.match(vary, /Accept/, 'Vary must include Accept (conneg active)');
+    assert.match(vary, /Authorization/, 'Vary must include Authorization (WAC)');
+    assert.match(vary, /Origin/, 'Vary must include Origin (CORS)');
+  });
+
+  it('mashlib HTML wrapper uses Cache-Control: no-store', async () => {
+    const res = await request('/varytest/public/card.jsonld', {
+      headers: { Accept: 'text/html,*/*;q=0.8' }
+    });
+    assert.match(res.headers.get('content-type') || '', /text\/html/);
+    assert.strictEqual(res.headers.get('cache-control'), 'no-store');
+  });
+
+  it('RDF data variants force revalidation (no stale bodies across auth changes)', async () => {
+    // Full expected policy — pinning every directive so a regression that
+    // drops `private` or `must-revalidate` (both needed to prevent auth-state
+    // leakage and force freshness) fails the test.
+    const expected = 'private, no-cache, must-revalidate';
+    for (const accept of ['text/turtle', 'application/ld+json']) {
+      const res = await request('/varytest/public/card.jsonld', { headers: { Accept: accept } });
+      assert.strictEqual(res.headers.get('cache-control'), expected,
+        `Cache-Control mismatch on Accept: ${accept}`);
+      // ETag is preserved so revalidation is cheap (304).
+      assert.ok(res.headers.get('etag'), `expected ETag on ${accept} variant`);
+    }
+  });
+
+  it('container index.html data-island variants also carry revalidating Cache-Control', async () => {
+    // Publish an index.html with a JSON-LD data island; conneg should extract
+    // and serve it as Turtle/JSON-LD. Those variants were missing
+    // Cache-Control pre-#315.
+    const html = [
+      '<!doctype html><html><head>',
+      '<script type="application/ld+json">',
+      JSON.stringify({
+        '@context': { foaf: 'http://xmlns.com/foaf/0.1/' },
+        '@id': '#this',
+        'foaf:name': 'Island'
+      }),
+      '</script></head><body>hi</body></html>'
+    ].join('');
+    await request('/varytest/public/index.html', {
+      method: 'PUT',
+      headers: { 'Content-Type': 'text/html' },
+      body: html,
+      auth: 'varytest'
+    });
+
+    const expected = 'private, no-cache, must-revalidate';
+    for (const accept of ['text/turtle', 'application/ld+json']) {
+      const res = await request('/varytest/public/', { headers: { Accept: accept } });
+      assert.strictEqual(res.headers.get('cache-control'), expected,
+        `Cache-Control mismatch on island variant (Accept: ${accept})`);
+    }
+  });
+});