javascript-solid-server 0.0.160 → 0.0.161

package/package.json

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

package/src/handlers/resource.js

@@ -14,7 +14,7 @@ import {
 } from '../rdf/conneg.js';
 import { emitChange } from '../notifications/events.js';
 import { checkIfMatch, checkIfNoneMatchForGet, checkIfNoneMatchForWrite } from '../utils/conditional.js';
-import { generateDatabrowserHtml, generateModuleDatabrowserHtml, shouldServeMashlib } from '../mashlib/index.js';
+import { generateDatabrowserHtml, generateModuleDatabrowserHtml, shouldServeMashlib, DATA_ISLAND_MAX_BYTES } from '../mashlib/index.js';
 
 /**
  * Live reload script - injected into HTML when --live-reload is enabled
@@ -238,9 +238,21 @@ export async function handleGet(request, reply) {
 
     // Check if we should serve Mashlib data browser for containers
     if (shouldServeMashlib(request, request.mashlibEnabled, 'application/ld+json')) {
+      // Phase 1 of #7: also embed the container's JSON-LD listing as a
+      // data island so consumers that look for `<script
+      // type="application/ld+json">` (search-engine rich-results,
+      // archival crawlers, future mashlib zero-fetch path) get the data
+      // without a second request. Use compact (no-whitespace) form for
+      // the embed so we don't burn bytes against DATA_ISLAND_MAX_BYTES
+      // on indentation that nothing will ever read.
+      const embedJsonLd = JSON.stringify(jsonLd);
       const html = request.mashlibModule
-        ? generateModuleDatabrowserHtml(request.mashlibModule)
-        : generateDatabrowserHtml(resourceUrl, request.mashlibCdn ? request.mashlibVersion : null);
+        ? generateModuleDatabrowserHtml(request.mashlibModule, resourceUrl, { embedJsonLd })
+        : generateDatabrowserHtml(
+          resourceUrl,
+          request.mashlibCdn ? request.mashlibVersion : null,
+          { embedJsonLd }
+        );
       const headers = getAllHeaders({
         isContainer: true,
         etag: stats.etag,
@@ -318,9 +330,31 @@ export async function handleGet(request, reply) {
   // Check if we should serve Mashlib data browser
   // Only for RDF resources when Accept: text/html is requested
   if (shouldServeMashlib(request, request.mashlibEnabled, storedContentType)) {
+    // Phase 1 of #7: embed the resource's JSON-LD bytes as a data
+    // island when it's already JSON-LD (the JSS-native format). Other
+    // formats are out of Phase-1 scope; the wrapper still loads
+    // correctly and mashlib XHR-fetches as before.
+    //
+    // Cap-aware short-circuit: skip the read entirely when the file is
+    // already over the embed cap. The island would be dropped anyway,
+    // and large JSON-LD resources would otherwise load into memory on
+    // every HTML navigation.
+    let embedJsonLd;
+    if (storedContentType === 'application/ld+json' &&
+        stats.size <= DATA_ISLAND_MAX_BYTES) {
+      // dataIsland() in mashlib/index.js coerces Buffer → string itself,
+      // so we hand it the Buffer directly instead of allocating a UTF-8
+      // string copy on every navigation.
+      const buf = await storage.read(storagePath);
+      if (buf) embedJsonLd = buf;
+    }
     const html = request.mashlibModule
-      ? generateModuleDatabrowserHtml(request.mashlibModule)
-      : generateDatabrowserHtml(resourceUrl, request.mashlibCdn ? request.mashlibVersion : null);
+      ? generateModuleDatabrowserHtml(request.mashlibModule, resourceUrl, { embedJsonLd })
+      : generateDatabrowserHtml(
+        resourceUrl,
+        request.mashlibCdn ? request.mashlibVersion : null,
+        { embedJsonLd }
+      );
     const headers = getAllHeaders({
       isContainer: false,
       etag: stats.etag,

package/src/mashlib/index.js

@@ -4,23 +4,97 @@
  * Generates HTML wrapper that loads SolidOS Mashlib from CDN.
  * When a browser requests an RDF resource with Accept: text/html,
  * we return this wrapper which then fetches and renders the data.
+ *
+ * Phase 1 of #7: when the originating resource is reasonably small
+ * RDF, the JSON-LD bytes are embedded in the wrapper as a `<script
+ * type="application/ld+json" id="dataisland" data-uri="…">` block.
+ * Browsers ignore non-JS script bodies, so this is harmless to all
+ * existing clients (mashlib still XHR-fetches today). It immediately
+ * benefits anything that knows to look for `application/ld+json`
+ * islands — search engine rich-results, archival crawlers, scrapers,
+ * static-site exporters — and gives Phase 2 a zero-network fast path.
+ */
+
+/**
+ * Cap on how much JSON-LD we'll inline. A 256 KB resource fits any
+ * realistic profile, type index, or container listing. Above that we
+ * drop the island and let the existing XHR path handle it so we don't
+ * make every navigation re-download a multi-megabyte resource.
+ */
+export const DATA_ISLAND_MAX_BYTES = 256 * 1024;
+
+/**
+ * Escape a JSON-LD body for safe inclusion inside `<script
+ * type="application/ld+json">…</script>`.
+ *
+ * Browsers don't execute the script (wrong MIME), but the HTML parser
+ * still scans the body for an end-of-script tag. The relevant rule:
+ * any `</` followed by `script` (case-insensitive) terminates the
+ * element regardless of what follows — `</script>`, `</script >`,
+ * `</script\n>`, `</SCRIPT>` and friends all close it. Escaping just
+ * the literal `</script>` token is too narrow.
+ *
+ * The robust fix is to replace every literal `<` byte in the body with
+ * the JSON string-escape for U+003C — the six characters
+ * backslash-u-0-0-3-c (the same form the implementation emits below).
+ * JSON-LD is JSON, and a JSON parser decodes that escape back to a
+ * literal `<` natively, so document semantics are preserved. After
+ * this transform the body literally cannot contain a `<` byte — so no
+ * end-tag (or comment, CDATA, etc.) can possibly start.
+ */
+function escapeForScriptBlock(jsonLdString) {
+  return String(jsonLdString).replace(/</g, '\\u003c');
+}
+
+/**
+ * Build the data-island `<script>` block for the given JSON-LD payload.
+ * Returns an empty string if the payload is missing or over the size
+ * cap so callers can unconditionally interpolate `dataIsland(...)`.
+ *
+ * The cap applies to the *escaped* body — i.e. the bytes that will
+ * actually appear in the HTTP response. `escapeForScriptBlock` can
+ * expand input up to 6x (each literal `<` becomes the 6-byte JSON
+ * escape sequence backslash-u-0-0-3-c), so checking the raw input
+ * size alone could let an HTML response balloon past the cap.
+ *
+ * Two-stage check:
+ *   1. Cheap raw-byte pre-check — escape can only grow the body,
+ *      so a raw payload already over the cap is guaranteed to be
+ *      over after escaping; drop without doing the work.
+ *   2. Post-escape check — catches the rare case where input was
+ *      under the cap but expanded above it (`<`-heavy bodies).
  */
+function dataIsland(resourceUrl, jsonLdString) {
+  if (!jsonLdString) return '';
+  const raw = String(jsonLdString);
+  if (Buffer.byteLength(raw, 'utf8') > DATA_ISLAND_MAX_BYTES) return '';
+  const safeBody = escapeForScriptBlock(raw);
+  if (Buffer.byteLength(safeBody, 'utf8') > DATA_ISLAND_MAX_BYTES) return '';
+  const safeUri = escapeHtml(String(resourceUrl));
+  return `<script type="application/ld+json" id="dataisland" data-uri="${safeUri}">${safeBody}</script>`;
+}
 
 /**
  * Generate Mashlib databrowser HTML
  *
- * @param {string} resourceUrl - The URL of the resource being viewed (unused, kept for API compatibility)
+ * @param {string} resourceUrl - The URL of the resource being viewed
  * @param {string} cdnVersion - If provided, load mashlib from unpkg CDN (e.g., "2.0.0")
+ * @param {object} [opts]
+ * @param {string|Buffer} [opts.embedJsonLd] - JSON-LD body to inline
+ *   as a `<script type="application/ld+json">` data island. Accepts a
+ *   UTF-8 string or a Buffer (coerced via `String()`). Honors a 256 KB
+ *   size cap; oversize payloads are silently dropped. Phase 1 of #7.
  * @returns {string} HTML content
  */
-export function generateDatabrowserHtml(resourceUrl, cdnVersion = null) {
+export function generateDatabrowserHtml(resourceUrl, cdnVersion = null, opts = {}) {
+  const island = dataIsland(resourceUrl, opts.embedJsonLd);
   if (cdnVersion) {
     // CDN mode - use script.onload to ensure mashlib is fully loaded before init
     // This avoids race conditions with defer + DOMContentLoaded
     const cdnBase = `https://unpkg.com/mashlib@${cdnVersion}/dist`;
     return `<!doctype html><html><head><meta charset="utf-8"/><title>SolidOS Web App</title>
 <link href="${cdnBase}/mash.css" rel="stylesheet"></head>
-<body id="PageBody"><header id="PageHeader"></header>
+<body id="PageBody">${island}<header id="PageHeader"></header>
 <div class="TabulatorOutline" id="DummyUUID" role="main"><table id="outline"></table><div id="GlobalDashboard"></div></div>
 <footer id="PageFooter"></footer>
 <script>
@@ -37,22 +111,27 @@ export function generateDatabrowserHtml(resourceUrl, cdnVersion = null) {
   // Local mode - use defer (reliable when served locally)
   return `<!doctype html><html><head><meta charset="utf-8"/><title>SolidOS Web App</title><script>document.addEventListener('DOMContentLoaded', function() {
         panes.runDataBrowser()
-      })</script><script defer="defer" src="/mashlib.min.js"></script><link href="/mash.css" rel="stylesheet"></head><body id="PageBody"><header id="PageHeader"></header><div class="TabulatorOutline" id="DummyUUID" role="main"><table id="outline"></table><div id="GlobalDashboard"></div></div><footer id="PageFooter"></footer></body></html>`;
+      })</script><script defer="defer" src="/mashlib.min.js"></script><link href="/mash.css" rel="stylesheet"></head><body id="PageBody">${island}<header id="PageHeader"></header><div class="TabulatorOutline" id="DummyUUID" role="main"><table id="outline"></table><div id="GlobalDashboard"></div></div><footer id="PageFooter"></footer></body></html>`;
 }
 
 /**
  * Generate ES module-based databrowser HTML
  *
  * @param {string} moduleUrl - URL to the ES module entry point
+ * @param {string} resourceUrl - The URL of the resource being viewed
+ * @param {object} [opts]
+ * @param {string|Buffer} [opts.embedJsonLd] - JSON-LD body for the
+ *   data island, same contract as `generateDatabrowserHtml`. Phase 1 of #7.
  * @returns {string} HTML content
  */
-export function generateModuleDatabrowserHtml(moduleUrl) {
+export function generateModuleDatabrowserHtml(moduleUrl, resourceUrl = '', opts = {}) {
   const cssUrl = moduleUrl.replace(/\.js$/, '.css');
+  const island = dataIsland(resourceUrl, opts.embedJsonLd);
   return `<!doctype html><html lang="en"><head><meta charset="utf-8"/>
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Solid Data Browser</title>
 <link rel="stylesheet" href="${cssUrl}"></head>
-<body><div id="mashlib"></div>
+<body>${island}<div id="mashlib"></div>
 <script type="module" src="${moduleUrl}"></script>
 </body></html>`;
 }

package/test/data-island.test.js

@@ -0,0 +1,209 @@
+/**
+ * Phase-1 tests for the JSON-LD data island (#7).
+ *
+ * The mashlib HTML wrapper now carries the resource's JSON-LD bytes
+ * inside a `<script type="application/ld+json" id="dataisland"
+ * data-uri="...">` block. Phase 1 doesn't change mashlib's runtime behaviour — the
+ * island is purely additive — so these tests pin:
+ *   - emission shape (script tag, id, MIME, data-uri)
+ *   - escape: any `</script>` substring inside the body must not
+ *     prematurely close the script tag
+ *   - size cap: oversized payloads silently drop the island so we
+ *     don't make every navigation re-download a multi-megabyte file
+ *   - presence in the live HTTP response (resource and container)
+ *   - safe URI attribute against quote / angle-bracket injection
+ */
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert';
+import {
+  startTestServer,
+  stopTestServer,
+  request,
+  createTestPod,
+  assertStatus,
+  assertHeaderContains
+} from './helpers.js';
+import {
+  generateDatabrowserHtml,
+  generateModuleDatabrowserHtml,
+  DATA_ISLAND_MAX_BYTES
+} from '../src/mashlib/index.js';
+
+describe('mashlib data island — emission (unit, #7)', () => {
+  it('emits <script type="application/ld+json" id="dataisland" data-uri="..."> when payload supplied', () => {
+    const html = generateDatabrowserHtml(
+      'https://test.solid.social/profile/card.jsonld',
+      '2.0.0',
+      { embedJsonLd: '{"@id":"#me","foaf:name":"Alice"}' }
+    );
+    assert.match(html, /<script type="application\/ld\+json" id="dataisland" data-uri="https:\/\/test\.solid\.social\/profile\/card\.jsonld">/);
+    assert.match(html, /"@id":"#me"/);
+    assert.match(html, /<\/script>/);
+  });
+
+  it('omits the data island when no payload is supplied (back-compat)', () => {
+    const html = generateDatabrowserHtml('https://x.test/foo', '2.0.0');
+    assert.doesNotMatch(html, /id="dataisland"/);
+  });
+
+  it('omits the data island for oversized payloads (size cap)', () => {
+    // Construct a JSON-LD body just over the cap.
+    const filler = 'x'.repeat(DATA_ISLAND_MAX_BYTES + 1024);
+    const oversized = `{"content":"${filler}"}`;
+    const html = generateDatabrowserHtml(
+      'https://x.test/big',
+      '2.0.0',
+      { embedJsonLd: oversized }
+    );
+    assert.doesNotMatch(html, /id="dataisland"/,
+      'island must drop silently above DATA_ISLAND_MAX_BYTES');
+  });
+
+  it('cap applies post-escape (defends against `<`-heavy expansion)', () => {
+    // A pathological body that's well under the cap as raw bytes but
+    // explodes 6x after escaping — every literal `<` byte becomes the
+    // 6-byte JSON escape sequence backslash-u-0-0-3-c. Without the
+    // post-escape check, this would emit a multi-megabyte island.
+    const halfCap = Math.floor(DATA_ISLAND_MAX_BYTES / 2);
+    const payload = '<'.repeat(halfCap); // 128 KB raw, ~768 KB escaped
+    const html = generateDatabrowserHtml(
+      'https://x.test/expand',
+      '2.0.0',
+      { embedJsonLd: payload }
+    );
+    assert.doesNotMatch(html, /id="dataisland"/,
+      'island must drop when the escaped body exceeds the cap');
+  });
+
+  // The escape strategy is "encode every `<` byte as the six-character
+  // JSON escape `\\u003c`". Test the wide variety of strings that an
+  // HTML parser would otherwise treat as a closing tag — `</script>`,
+  // `</script >`, `</script\n>`, `</SCRIPT>`, `</scRIPT>` — plus
+  // `<!--`, all of which require a literal `<` to start the dangerous
+  // sequence. After escaping, no literal `<` exists in the body and
+  // every transformed location appears as `\\u003c`.
+  const escapeTrojans = [
+    ['exact </script>',      '{"x":"a</script>b"}'],
+    ['with space </script >', '{"x":"a</script >b"}'],
+    ['with newline </script\\n>', '{"x":"a</script\n>b"}'],
+    ['uppercase </SCRIPT>',  '{"x":"a</SCRIPT>b"}'],
+    ['mixed </ScRiPt>',      '{"x":"a</ScRiPt>b"}'],
+    ['<!-- comment',         '{"x":"<!-- hidden -->"}']
+  ];
+  for (const [label, body] of escapeTrojans) {
+    it(`escape blocks ${label} from prematurely terminating the tag`, () => {
+      const html = generateDatabrowserHtml(
+        'https://x.test/r',
+        '2.0.0',
+        { embedJsonLd: body }
+      );
+      const start = html.indexOf('id="dataisland"');
+      assert.ok(start > 0, 'data island should be present');
+      // Slice from the island's `>` (end of opening tag) forward.
+      const open = html.indexOf('>', start) + 1;
+      const close = html.indexOf('</script>', open);
+      const inner = html.slice(open, close);
+      // After our escape, the body must contain NO literal `<`.
+      assert.doesNotMatch(inner, /</,
+        `script body must not contain a literal "<" — got: ${JSON.stringify(inner)}`);
+      // The escaped form (the six characters backslash-u-0-0-3-c)
+      // should be present.
+      assert.match(inner, /\\u003c/,
+        'escaped form `\\u003c` must appear');
+    });
+  }
+
+  it('accepts a Buffer payload (handler may pass storage.read() result directly)', () => {
+    // The src/handlers/resource.js path used to convert with .toString()
+    // before passing in; tightening that contract risks regressions, so
+    // the helper accepts a Buffer transparently.
+    const buf = Buffer.from('{"@id":"#me","foaf:name":"BufferAlice"}', 'utf8');
+    const html = generateDatabrowserHtml(
+      'https://x.test/r',
+      '2.0.0',
+      { embedJsonLd: buf }
+    );
+    assert.match(html, /id="dataisland"/);
+    assert.match(html, /"foaf:name":"BufferAlice"/);
+  });
+
+  it('the module-mode wrapper also emits the data island', () => {
+    const html = generateModuleDatabrowserHtml(
+      'https://example.test/mashlib.js',
+      'https://test.solid.social/profile/card.jsonld',
+      { embedJsonLd: '{"@id":"#me"}' }
+    );
+    assert.match(html, /<script type="application\/ld\+json" id="dataisland" data-uri="https:\/\/test\.solid\.social\/profile\/card\.jsonld">/);
+    assert.match(html, /"@id":"#me"/);
+  });
+
+  it('escapes the data-uri attribute against quote / angle-bracket injection', () => {
+    const html = generateDatabrowserHtml(
+      'https://x.test/r"><img src=x onerror=alert(1)>',
+      '2.0.0',
+      { embedJsonLd: '{}' }
+    );
+    // The dangerous characters must be HTML-entity encoded inside the
+    // attribute, so the attribute can't be broken open.
+    assert.match(html, /data-uri="https:\/\/x\.test\/r&quot;&gt;&lt;img/);
+    assert.doesNotMatch(html, /data-uri="https:\/\/x\.test\/r"><img/);
+  });
+});
+
+// Integration coverage — the data island must actually appear in the
+// HTTP response when a browser asks for the wrapper.
+describe('mashlib data island — integration (#7)', () => {
+  before(async () => {
+    await startTestServer({ mashlibCdn: true });
+    await createTestPod('islandtest');
+    // Put a small JSON-LD resource we can fetch back as HTML.
+    await request('/islandtest/public/note.jsonld', {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/ld+json' },
+      body: JSON.stringify({
+        '@context': { foaf: 'http://xmlns.com/foaf/0.1/' },
+        '@id': '#note',
+        'foaf:name': 'island test'
+      }),
+      auth: 'islandtest'
+    });
+  });
+
+  after(async () => { await stopTestServer(); });
+
+  it('a browser GET to a JSON-LD resource carries the data island', async () => {
+    const res = await request('/islandtest/public/note.jsonld', {
+      headers: { Accept: 'text/html,application/xhtml+xml,*/*;q=0.8' }
+    });
+    assertStatus(res, 200);
+    assertHeaderContains(res, 'Content-Type', 'text/html');
+    const body = await res.text();
+    assert.match(body, /id="dataisland"/);
+    assert.match(body, /<script type="application\/ld\+json"/);
+    assert.match(body, /"foaf:name":"island test"/);
+  });
+
+  it('a browser GET to a container carries the listing as a data island', async () => {
+    const res = await request('/islandtest/public/', {
+      headers: { Accept: 'text/html,application/xhtml+xml,*/*;q=0.8' }
+    });
+    assertStatus(res, 200);
+    assertHeaderContains(res, 'Content-Type', 'text/html');
+    const body = await res.text();
+    assert.match(body, /id="dataisland"/);
+    assert.match(body, /<script type="application\/ld\+json"/);
+    // Contains an ldp:contains pointing at the resource we just PUT.
+    assert.match(body, /note\.jsonld/);
+  });
+
+  it('non-HTML Accept (mashlib XHR) does NOT trigger the wrapper', async () => {
+    const res = await request('/islandtest/public/note.jsonld', {
+      headers: { Accept: 'application/ld+json' }
+    });
+    assertHeaderContains(res, 'Content-Type', 'application/ld+json');
+    const body = await res.text();
+    assert.doesNotMatch(body, /id="dataisland"/);
+    assert.doesNotMatch(body, /<!doctype html>/i);
+  });
+});