javascript-solid-server 0.0.75 → 0.0.76

package/.claude/settings.local.json

@@ -234,7 +234,29 @@
       "Bash(timeout 90 bash -c:*)",
       "Bash(git commit -m \"$\\(cat <<''EOF''\nsecurity: add ACL check on WebSocket subscription requests\n\nCheck WAC read permission before allowing subscription to prevent\ninformation leakage via notifications. Unauthorized subscriptions\nnow receive ''err <url> forbidden'' response.\n\nSecurity improvements:\n- Check ACL read access before allowing subscription\n- Validate URLs are on this server \\(prevents SSRF-like probing\\)\n- Add subscription limit and URL length validation\n\nFixes #62\nEOF\n\\)\")",
       "Bash(gh repo fork:*)",
-      "Bash(timeout 180 npm test:*)"
+      "Bash(timeout 180 npm test:*)",
+      "Bash(git show:*)",
+      "Bash(git -C /home/melvin/remote/github.com/nodeSolidServer/node-solid-server log --oneline -30 -- \"test/integration/acl-tls-test.mjs\" \"test-esm/integration/acl-tls-test.js\")",
+      "Bash(git -C /home/melvin/remote/github.com/nodeSolidServer/node-solid-server log --oneline --follow -30 -- \"test/integration/acl-tls-test.mjs\")",
+      "Bash(git -C /home/melvin/remote/github.com/nodeSolidServer/node-solid-server show 778095ad --stat)",
+      "Bash(git -C /home/melvin/remote/github.com/nodeSolidServer/node-solid-server show 778095ad)",
+      "Bash(git -C /home/melvin/remote/github.com/nodeSolidServer/node-solid-server show b183c7a0)",
+      "Bash(git -C /home/melvin/remote/github.com/nodeSolidServer/node-solid-server log --oneline --before=\"2019-10-29\" --after=\"2019-10-01\" -20)",
+      "Bash(git -C /home/melvin/remote/github.com/nodeSolidServer/node-solid-server show 1a92a912 --stat)",
+      "Bash(git -C /home/melvin/remote/github.com/nodeSolidServer/node-solid-server log --oneline --all --grep=jaxoncreed)",
+      "Bash(git -C /home/melvin/remote/github.com/nodeSolidServer/node-solid-server log --oneline --author=\"jaxoncreed\" -30)",
+      "Bash(git -C /home/melvin/remote/github.com/nodeSolidServer/node-solid-server log --oneline --author=\"[Dd]mitri\" -20)",
+      "Bash(git -C /home/melvin/remote/github.com/nodeSolidServer/node-solid-server log --oneline --all --grep=\"oidc\" -20)",
+      "Bash(npm install)",
+      "Bash(timeout 60 npx mocha:*)",
+      "Bash(timeout 120 npx mocha:*)",
+      "Bash(timeout 30 npx mocha:*)",
+      "Bash(openssl x509:*)",
+      "Bash(gh pr checks:*)",
+      "Bash(gh run view:*)",
+      "Bash(gh pr edit:*)",
+      "WebFetch(domain:patch-diff.githubusercontent.com)",
+      "Bash(git rebase:*)"
     ]
   }
 }

package/README.md

@@ -122,6 +122,7 @@ jss --help             # Show help
 | `--mashlib` | Enable Mashlib (local mode) | false |
 | `--mashlib-cdn` | Enable Mashlib (CDN mode) | false |
 | `--mashlib-version <ver>` | Mashlib CDN version | 2.0.0 |
+| `--solidos-ui` | Enable modern SolidOS UI (requires --mashlib) | false |
 | `--git` | Enable Git HTTP backend | false |
 | `--nostr` | Enable Nostr relay | false |
 | `--nostr-path <path>` | Nostr relay WebSocket path | /relay |
@@ -333,6 +334,18 @@ npm install && npm run build
 
 **Note:** Mashlib works best with `--conneg` enabled for Turtle support.
 
+**Modern UI (SolidOS UI):**
+```bash
+jss start --mashlib --solidos-ui --conneg
+```
+Serves a modern Nextcloud-style UI shell while reusing mashlib's data layer. The `--solidos-ui` flag swaps the classic databrowser interface for a cleaner, mobile-friendly design with:
+- Modern file browser with breadcrumb navigation
+- Profile, Contacts, Sharing, and Settings views
+- Path-based URLs (browser URL reflects current resource)
+- Responsive design for mobile devices
+
+Requires solidos-ui dist files in `src/mashlib-local/dist/solidos-ui/`. See [solidos-ui](https://github.com/solidos/solidos/tree/main/workspaces/solidos-ui) for details.
+
 ### Profile Pages
 
 Pod profiles (`/alice/`) use HTML with embedded JSON-LD data islands and are rendered using:

package/bin/jss.js

@@ -57,6 +57,7 @@ program
   .option('--mashlib-cdn', 'Enable Mashlib data browser (CDN mode, no local files needed)')
   .option('--no-mashlib', 'Disable Mashlib data browser')
   .option('--mashlib-version <version>', 'Mashlib version for CDN mode (default: 2.0.0)')
+  .option('--solidos-ui', 'Enable modern Nextcloud-style UI (requires --mashlib)')
   .option('--git', 'Enable Git HTTP backend (clone/push support)')
   .option('--no-git', 'Disable Git HTTP backend')
   .option('--nostr', 'Enable Nostr relay')
@@ -114,6 +115,7 @@ program
         mashlib: config.mashlib || config.mashlibCdn,
         mashlibCdn: config.mashlibCdn,
         mashlibVersion: config.mashlibVersion,
+        solidosUi: config.solidosUi,
         git: config.git,
         nostr: config.nostr,
         nostrPath: config.nostrPath,
@@ -143,6 +145,7 @@ program
         } else if (config.mashlib) {
           console.log(`  Mashlib: local (data browser enabled)`);
         }
+        if (config.solidosUi) console.log('  SolidOS UI: enabled (modern interface)');
         if (config.git) console.log('  Git: enabled (clone/push support)');
         if (config.nostr) console.log(`  Nostr: enabled (${config.nostrPath})`);
         if (config.activitypub) console.log(`  ActivityPub: enabled (@${config.apUsername || 'me'})`);

package/package.json

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

package/src/auth/middleware.js

@@ -9,7 +9,7 @@ import { checkAccess, getRequiredMode } from '../wac/checker.js';
 import { AccessMode } from '../wac/parser.js';
 import * as storage from '../storage/filesystem.js';
 import { getEffectiveUrlPath } from '../utils/url.js';
-import { generateDatabrowserHtml } from '../mashlib/index.js';
+import { generateDatabrowserHtml, generateSolidosUiHtml } from '../mashlib/index.js';
 
 /**
  * Check if request is authorized
@@ -117,8 +117,11 @@ export function handleUnauthorized(request, reply, isAuthenticated, wacAllow, au
     // If mashlib is enabled, serve mashlib instead of static error page
     // Mashlib has built-in login functionality via panes.runDataBrowser()
     if (request.mashlibEnabled) {
-      const cdnVersion = request.mashlibCdn ? request.mashlibVersion : null;
-      return reply.code(statusCode).type('text/html').send(generateDatabrowserHtml(request.url, cdnVersion));
+      // Use SolidOS UI if enabled, otherwise fallback to classic mashlib
+      const html = request.solidosUiEnabled
+        ? generateSolidosUiHtml()
+        : generateDatabrowserHtml(request.url, request.mashlibCdn ? request.mashlibVersion : null);
+      return reply.code(statusCode).type('text/html').send(html);
     }
     return reply.code(statusCode).type('text/html').send(getErrorPage(statusCode, isAuthenticated, request));
   }

package/src/config.js

@@ -42,6 +42,9 @@ export const defaults = {
   mashlibCdn: false,
   mashlibVersion: '2.0.0',
 
+  // SolidOS UI (modern Nextcloud-style interface)
+  solidosUi: false,
+
   // Git HTTP backend
   git: false,
 
@@ -95,6 +98,7 @@ const envMap = {
   JSS_MASHLIB: 'mashlib',
   JSS_MASHLIB_CDN: 'mashlibCdn',
   JSS_MASHLIB_VERSION: 'mashlibVersion',
+  JSS_SOLIDOS_UI: 'solidosUi',
   JSS_GIT: 'git',
   JSS_NOSTR: 'nostr',
   JSS_NOSTR_PATH: 'nostrPath',
@@ -258,5 +262,6 @@ export function printConfig(config) {
   console.log(`  IdP:           ${config.idp ? (config.idpIssuer || 'enabled') : 'disabled'}`);
   console.log(`  Subdomains:    ${config.subdomains ? (config.baseDomain || 'enabled') : 'disabled'}`);
   console.log(`  Mashlib:       ${config.mashlibCdn ? `CDN v${config.mashlibVersion}` : config.mashlib ? 'local' : 'disabled'}`);
+  console.log(`  SolidOS UI:    ${config.solidosUi ? 'enabled' : 'disabled'}`);
   console.log('─'.repeat(40));
 }

package/src/handlers/resource.js

@@ -15,7 +15,7 @@ import {
 } from '../rdf/conneg.js';
 import { emitChange } from '../notifications/events.js';
 import { checkIfMatch, checkIfNoneMatchForGet, checkIfNoneMatchForWrite } from '../utils/conditional.js';
-import { generateDatabrowserHtml, shouldServeMashlib } from '../mashlib/index.js';
+import { generateDatabrowserHtml, generateSolidosUiHtml, shouldServeMashlib } from '../mashlib/index.js';
 
 /**
  * Get the storage path and resource URL for a request
@@ -30,6 +30,64 @@ function getRequestPaths(request) {
   return { urlPath, storagePath, resourceUrl };
 }
 
+/**
+ * Parse HTTP Range header
+ * @param {string} rangeHeader - The Range header value (e.g., "bytes=0-1023")
+ * @param {number} fileSize - Total file size in bytes
+ * @returns {{ start: number, end: number } | null}
+ */
+function parseRangeHeader(rangeHeader, fileSize) {
+  if (!rangeHeader || !rangeHeader.startsWith('bytes=')) {
+    return null;
+  }
+
+  const range = rangeHeader.slice(6); // Remove 'bytes='
+
+  // Multi-range requests (e.g., "0-100,200-300") are not supported
+  // Per RFC 7233, ignore Range header and serve full content instead of 416
+  if (range.includes(',')) {
+    return null;
+  }
+
+  const parts = range.split('-');
+
+  if (parts.length !== 2) {
+    return null;
+  }
+
+  let start, end;
+
+  if (parts[0] === '') {
+    // Suffix range: bytes=-500 (last 500 bytes)
+    const suffix = parseInt(parts[1], 10);
+    if (isNaN(suffix) || suffix <= 0) return null;
+    start = Math.max(0, fileSize - suffix);
+    end = fileSize - 1;
+  } else if (parts[1] === '') {
+    // Open-ended range: bytes=1024- (from 1024 to end)
+    start = parseInt(parts[0], 10);
+    if (isNaN(start) || start < 0) return null;
+    end = fileSize - 1;
+  } else {
+    // Normal range: bytes=0-1023
+    start = parseInt(parts[0], 10);
+    end = parseInt(parts[1], 10);
+    if (isNaN(start) || isNaN(end) || start < 0 || end < start) return null;
+  }
+
+  // Clamp end to file size
+  if (end >= fileSize) {
+    end = fileSize - 1;
+  }
+
+  // Check if range is satisfiable
+  if (start > end || start >= fileSize) {
+    return null;
+  }
+
+  return { start, end };
+}
+
 /**
  * Handle GET request
  */
@@ -149,8 +207,10 @@ export async function handleGet(request, reply) {
 
     // Check if we should serve Mashlib data browser for containers
     if (shouldServeMashlib(request, request.mashlibEnabled, 'application/ld+json')) {
-      const cdnVersion = request.mashlibCdn ? request.mashlibVersion : null;
-      const html = generateDatabrowserHtml(resourceUrl, cdnVersion);
+      // Use SolidOS UI if enabled, otherwise fallback to classic mashlib
+      const html = request.solidosUiEnabled
+        ? generateSolidosUiHtml()
+        : generateDatabrowserHtml(resourceUrl, request.mashlibCdn ? request.mashlibVersion : null);
       const headers = getAllHeaders({
         isContainer: true,
         etag: stats.etag,
@@ -224,9 +284,10 @@ 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)) {
-    // Pass CDN version if using CDN mode, null for local mode
-    const cdnVersion = request.mashlibCdn ? request.mashlibVersion : null;
-    const html = generateDatabrowserHtml(resourceUrl, cdnVersion);
+    // Use SolidOS UI if enabled, otherwise fallback to classic mashlib
+    const html = request.solidosUiEnabled
+      ? generateSolidosUiHtml()
+      : generateDatabrowserHtml(resourceUrl, request.mashlibCdn ? request.mashlibVersion : null);
     const headers = getAllHeaders({
       isContainer: false,
       etag: stats.etag,
@@ -245,6 +306,43 @@ export async function handleGet(request, reply) {
     return reply.type('text/html').send(html);
   }
 
+  // Handle Range requests for media files (video, audio, etc.)
+  const rangeHeader = request.headers.range;
+  if (rangeHeader && !isRdfContentType(storedContentType)) {
+    const range = parseRangeHeader(rangeHeader, stats.size);
+
+    if (range) {
+      const { start, end } = range;
+      const chunkSize = end - start + 1;
+
+      const headers = getAllHeaders({
+        isContainer: false,
+        etag: stats.etag,
+        contentType: storedContentType,
+        origin,
+        resourceUrl,
+        connegEnabled
+      });
+      headers['Content-Range'] = `bytes ${start}-${end}/${stats.size}`;
+      headers['Content-Length'] = chunkSize;
+
+      Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+
+      const streamResult = storage.createReadStream(storagePath, { start, end });
+      if (!streamResult) {
+        return reply.code(500).send({ error: 'Stream error' });
+      }
+
+      // Handle stream errors that occur during response
+      streamResult.stream.on('error', (err) => {
+        console.error('Stream error during range response:', err.message);
+      });
+
+      return reply.code(206).send(streamResult.stream);
+    }
+    // If range is null (unsupported format or multi-range), fall through to serve full content
+  }
+
   const content = await storage.read(storagePath);
   if (content === null) {
     return reply.code(500).send({ error: 'Read error' });

package/src/ldp/headers.js

@@ -56,6 +56,7 @@ export function getResponseHeaders({ isContainer = false, etag = null, contentTy
   const headers = {
     'Link': getLinkHeader(isContainer, aclUrl),
     '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'
   };
@@ -94,8 +95,8 @@ export function getCorsHeaders(origin) {
   return {
     'Access-Control-Allow-Origin': origin || '*',
     'Access-Control-Allow-Methods': 'GET, HEAD, POST, PUT, DELETE, PATCH, OPTIONS',
-    'Access-Control-Allow-Headers': 'Accept, Authorization, Content-Type, DPoP, If-Match, If-None-Match, Link, Slug, Origin',
-    'Access-Control-Expose-Headers': 'Accept-Patch, Accept-Post, Allow, Content-Type, ETag, Link, Location, Updates-Via, WAC-Allow',
+    'Access-Control-Allow-Headers': 'Accept, Authorization, Content-Type, DPoP, If-Match, If-None-Match, Link, Range, Slug, Origin',
+    'Access-Control-Expose-Headers': 'Accept-Patch, Accept-Post, Accept-Ranges, Allow, Content-Length, Content-Range, Content-Type, ETag, Link, Location, Updates-Via, WAC-Allow',
     'Access-Control-Allow-Credentials': 'true',
     'Access-Control-Max-Age': '86400'
   };

package/src/mashlib/index.js

@@ -94,6 +94,113 @@ export function shouldServeMashlib(request, mashlibEnabled, contentType) {
   return rdfTypes.includes(baseType);
 }
 
+/**
+ * Generate SolidOS UI HTML (modern Nextcloud-style interface)
+ * Uses mashlib for data layer but solidos-ui for the UI shell
+ *
+ * @returns {string} HTML content
+ */
+export function generateSolidosUiHtml() {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>SolidOS - Modern UI</title>
+  <!-- SolidOS UI Styles -->
+  <link rel="stylesheet" href="/solidos-ui/styles/variables.css">
+  <link rel="stylesheet" href="/solidos-ui/styles/shell.css">
+  <link rel="stylesheet" href="/solidos-ui/styles/components.css">
+  <link rel="stylesheet" href="/solidos-ui/styles/responsive.css">
+  <!-- View-specific styles -->
+  <link rel="stylesheet" href="/solidos-ui/views/profile/profile.css">
+  <link rel="stylesheet" href="/solidos-ui/views/contacts/contacts.css">
+  <link rel="stylesheet" href="/solidos-ui/views/sharing/sharing.css">
+  <link rel="stylesheet" href="/solidos-ui/views/settings/settings.css">
+  <!-- Bundled styles (contains all component styles) -->
+  <link rel="stylesheet" href="/solidos-ui/style.css">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    html, body { height: 100%; }
+    #app { height: 100%; }
+  </style>
+</head>
+<body>
+  <div id="app"></div>
+
+  <script>
+    // Load mashlib first, then solidos-ui
+    (function() {
+      var mashScript = document.createElement('script');
+      mashScript.src = '/mashlib.min.js';
+      mashScript.onload = function() {
+        // Now load solidos-ui
+        import('/solidos-ui/solidos-ui.js').then(function(module) {
+          var initSolidOSSkin = module.initSolidOSSkin;
+          var SolidLogic = window.SolidLogic;
+          var panes = window.panes;
+          var store = SolidLogic.store;
+
+          initSolidOSSkin('#app', {
+            store: store,
+            fetcher: store.fetcher,
+            paneRegistry: panes,
+            authn: SolidLogic.authn,
+            logic: SolidLogic.solidLogicSingleton,
+          }, {
+            onNavigate: function(uri) {
+              if (uri) {
+                // Use path-based navigation - update URL to match resource
+                try {
+                  var url = new URL(uri);
+                  // Always use the path from the URI, regardless of origin
+                  // (URIs may use internal hostname like jss:4000 vs localhost:4000)
+                  var newPath = url.pathname;
+                  if (newPath !== window.location.pathname) {
+                    window.history.pushState({ uri: uri }, '', newPath);
+                  }
+                } catch (e) {
+                  console.warn('Invalid URI for navigation:', uri);
+                }
+              }
+            },
+            onLogout: function() {
+              window.location.reload();
+            },
+          }).then(function(skin) {
+            // Handle browser back/forward
+            window.addEventListener('popstate', function(event) {
+              // Use the current URL as the resource (not hash-based)
+              var resourceUrl = window.location.origin + window.location.pathname;
+              skin.goto(resourceUrl);
+            });
+
+            // Navigate to the current URL's resource
+            // The URL path IS the resource in JSS (not hash-based routing)
+            var currentPath = window.location.pathname;
+            if (currentPath && currentPath !== '/') {
+              var resourceUrl = window.location.origin + currentPath;
+              skin.goto(resourceUrl);
+            }
+
+            // Expose for debugging
+            window.solidosSkin = skin;
+          });
+        }).catch(function(err) {
+          console.error('Failed to load solidos-ui:', err);
+          document.body.innerHTML = '<p>Failed to load SolidOS UI</p>';
+        });
+      };
+      mashScript.onerror = function() {
+        document.body.innerHTML = '<p>Failed to load Mashlib</p>';
+      };
+      document.head.appendChild(mashScript);
+    })();
+  </script>
+</body>
+</html>`;
+}
+
 /**
  * Escape HTML special characters
  */

package/src/server.js

@@ -55,6 +55,8 @@ export function createServer(options = {}) {
   const mashlibEnabled = options.mashlib ?? false;
   const mashlibCdn = options.mashlibCdn ?? false;
   const mashlibVersion = options.mashlibVersion ?? '2.0.0';
+  // SolidOS UI (modern Nextcloud-style interface) - requires mashlib
+  const solidosUiEnabled = options.solidosUi ?? false;
   // Git HTTP backend is OFF by default - enables clone/push via git protocol
   const gitEnabled = options.git ?? false;
   // Nostr relay is OFF by default
@@ -127,6 +129,7 @@ export function createServer(options = {}) {
   fastify.decorateRequest('mashlibEnabled', null);
   fastify.decorateRequest('mashlibCdn', null);
   fastify.decorateRequest('mashlibVersion', null);
+  fastify.decorateRequest('solidosUiEnabled', null);
   fastify.decorateRequest('defaultQuota', null);
   fastify.addHook('onRequest', async (request) => {
     request.connegEnabled = connegEnabled;
@@ -137,6 +140,7 @@ export function createServer(options = {}) {
     request.mashlibEnabled = mashlibEnabled;
     request.mashlibCdn = mashlibCdn;
     request.mashlibVersion = mashlibVersion;
+    request.solidosUiEnabled = solidosUiEnabled;
     request.defaultQuota = defaultQuota;
 
     // Extract pod name from subdomain if enabled
@@ -296,7 +300,7 @@ export function createServer(options = {}) {
   // Authorization hook - check WAC permissions
   // Skip for pod creation endpoint (needs special handling)
   fastify.addHook('preHandler', async (request, reply) => {
-    // Skip auth for pod creation, OPTIONS, IdP routes, mashlib, well-known, notifications, nostr, git, and AP
+    // Skip auth for pod creation, OPTIONS, IdP routes, mashlib, solidos-ui, well-known, notifications, nostr, git, and AP
     const mashlibPaths = ['/mashlib.min.js', '/mash.css', '/841.mashlib.min.js'];
     const apPaths = ['/inbox', '/profile/card/inbox', '/profile/card/outbox', '/profile/card/followers', '/profile/card/following'];
     // Check if request wants ActivityPub content for profile
@@ -308,6 +312,7 @@ export function createServer(options = {}) {
         request.method === 'OPTIONS' ||
         request.url.startsWith('/idp/') ||
         request.url.startsWith('/.well-known/') ||
+        request.url.startsWith('/solidos-ui/') ||
         (nostrEnabled && request.url.startsWith(nostrPath)) ||
         (gitEnabled && isGitRequest(request.url)) ||
         (activitypubEnabled && apPaths.some(p => request.url === p || request.url.startsWith(p + '?'))) ||
@@ -381,6 +386,37 @@ export function createServer(options = {}) {
     }
   }
 
+  // SolidOS UI static files (modern Nextcloud-style interface)
+  // Serves from /solidos-ui/* - requires mashlib to be enabled as well
+  if (solidosUiEnabled && mashlibEnabled) {
+    const solidosUiDir = join(__dirname, 'mashlib-local', 'dist', 'solidos-ui');
+
+    // Serve all files under /solidos-ui/* path
+    fastify.get('/solidos-ui/*', async (request, reply) => {
+      try {
+        // Get the path after /solidos-ui/
+        const filePath = request.url.replace('/solidos-ui/', '').split('?')[0];
+        const fullPath = join(solidosUiDir, filePath);
+
+        // Determine content type based on extension
+        const ext = filePath.split('.').pop()?.toLowerCase();
+        const contentTypes = {
+          'js': 'application/javascript',
+          'css': 'text/css',
+          'map': 'application/json',
+          'html': 'text/html'
+        };
+        const contentType = contentTypes[ext] || 'application/octet-stream';
+
+        const content = await readFile(fullPath);
+        return reply.type(contentType).send(content);
+      } catch (err) {
+        request.log.error(err, 'Failed to serve solidos-ui file');
+        return reply.code(404).send({ error: 'Not Found' });
+      }
+    });
+  }
+
   // Rate limit configuration for write operations
   // Protects against resource exhaustion and abuse
   const writeRateLimit = {

package/src/storage/filesystem.js

@@ -51,6 +51,28 @@ export async function read(urlPath) {
   }
 }
 
+/**
+ * Create a readable stream for a resource (supports range requests)
+ * @param {string} urlPath
+ * @param {object} options - { start, end } byte range options
+ * @returns {{ stream: ReadStream, filePath: string } | null}
+ */
+export function createReadStream(urlPath, options = {}) {
+  const filePath = urlToPath(urlPath);
+
+  // Check file exists before creating stream (createReadStream doesn't throw sync)
+  if (!fs.pathExistsSync(filePath)) {
+    return null;
+  }
+
+  try {
+    const stream = fs.createReadStream(filePath, options);
+    return { stream, filePath };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Write resource content
  * @param {string} urlPath

package/test/range.test.js

@@ -0,0 +1,145 @@
+/**
+ * Range Request Tests
+ *
+ * Tests HTTP Range header support for partial content delivery.
+ */
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert';
+import {
+  startTestServer,
+  stopTestServer,
+  request,
+  createTestPod,
+  assertStatus
+} from './helpers.js';
+
+describe('Range Requests', () => {
+  const testContent = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'; // 36 bytes
+
+  before(async () => {
+    await startTestServer();
+    await createTestPod('rangetest');
+
+    // Create a test file with known content
+    await request('/rangetest/public/test.txt', {
+      method: 'PUT',
+      headers: { 'Content-Type': 'text/plain' },
+      body: testContent,
+      auth: 'rangetest'
+    });
+  });
+
+  after(async () => {
+    await stopTestServer();
+  });
+
+  describe('Accept-Ranges header', () => {
+    it('should include Accept-Ranges: bytes for files', async () => {
+      const res = await request('/rangetest/public/test.txt');
+      assertStatus(res, 200);
+      assert.strictEqual(res.headers.get('Accept-Ranges'), 'bytes');
+    });
+
+    it('should include Accept-Ranges: none for containers', async () => {
+      const res = await request('/rangetest/public/');
+      assertStatus(res, 200);
+      assert.strictEqual(res.headers.get('Accept-Ranges'), 'none');
+    });
+  });
+
+  describe('Range header parsing', () => {
+    it('should return 206 for valid range bytes=0-9', async () => {
+      const res = await request('/rangetest/public/test.txt', {
+        headers: { 'Range': 'bytes=0-9' }
+      });
+      assertStatus(res, 206);
+
+      const body = await res.text();
+      assert.strictEqual(body, 'ABCDEFGHIJ');
+      assert.strictEqual(res.headers.get('Content-Range'), 'bytes 0-9/36');
+      assert.strictEqual(res.headers.get('Content-Length'), '10');
+    });
+
+    it('should return 206 for open-ended range bytes=30-', async () => {
+      const res = await request('/rangetest/public/test.txt', {
+        headers: { 'Range': 'bytes=30-' }
+      });
+      assertStatus(res, 206);
+
+      const body = await res.text();
+      assert.strictEqual(body, '456789');
+      assert.strictEqual(res.headers.get('Content-Range'), 'bytes 30-35/36');
+    });
+
+    it('should return 206 for suffix range bytes=-6', async () => {
+      const res = await request('/rangetest/public/test.txt', {
+        headers: { 'Range': 'bytes=-6' }
+      });
+      assertStatus(res, 206);
+
+      const body = await res.text();
+      assert.strictEqual(body, '456789');
+      assert.strictEqual(res.headers.get('Content-Range'), 'bytes 30-35/36');
+    });
+
+    it('should clamp end to file size for range exceeding file', async () => {
+      const res = await request('/rangetest/public/test.txt', {
+        headers: { 'Range': 'bytes=30-1000' }
+      });
+      assertStatus(res, 206);
+
+      const body = await res.text();
+      assert.strictEqual(body, '456789');
+      assert.strictEqual(res.headers.get('Content-Range'), 'bytes 30-35/36');
+    });
+  });
+
+  describe('Multi-range requests', () => {
+    it('should ignore multi-range and return 200 with full content', async () => {
+      const res = await request('/rangetest/public/test.txt', {
+        headers: { 'Range': 'bytes=0-5,10-15' }
+      });
+      // Multi-range is not supported, should fall back to 200
+      assertStatus(res, 200);
+
+      const body = await res.text();
+      assert.strictEqual(body, testContent);
+    });
+  });
+
+  describe('Invalid ranges', () => {
+    it('should return 200 for invalid range format', async () => {
+      const res = await request('/rangetest/public/test.txt', {
+        headers: { 'Range': 'invalid' }
+      });
+      // Invalid format, ignore Range header
+      assertStatus(res, 200);
+    });
+
+    it('should return 200 for non-bytes range unit', async () => {
+      const res = await request('/rangetest/public/test.txt', {
+        headers: { 'Range': 'chars=0-10' }
+      });
+      assertStatus(res, 200);
+    });
+  });
+
+  describe('RDF resources', () => {
+    it('should ignore Range header for RDF resources', async () => {
+      // Create an RDF resource
+      await request('/rangetest/public/data.jsonld', {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/ld+json' },
+        body: JSON.stringify({ '@id': '#test', 'http://example.org/name': 'Test' }),
+        auth: 'rangetest'
+      });
+
+      const res = await request('/rangetest/public/data.jsonld', {
+        headers: { 'Range': 'bytes=0-10' }
+      });
+      // RDF resources don't support range requests
+      assertStatus(res, 200);
+    });
+  });
+});