javascript-solid-server 0.0.15 → 0.0.16

package/.claude/settings.local.json

@@ -51,7 +51,8 @@
       "Bash(ACCESS_TOKEN=\"eyJhbGciOiJFUzI1NiIsImtpZCI6IjQwY2U0YzIzLWY2OWQtNDU4NS05ODg2LTE4MDQzZWIyZjU2ZCJ9.eyJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjQwMDAvIiwic3ViIjoiYjhlZjY5YWUtODc0ZS00MDg5LThiMDktOGQwY2QyM2VlZWY3IiwiYXVkIjoic29saWQiLCJ3ZWJpZCI6Imh0dHA6Ly9sb2NhbGhvc3Q0MDAwL2FsaWNlLyNtZSIsImlhdCI6MTc2NjgyOTQ5MiwiZXhwIjoxNzY2ODMzMDkyLCJqdGkiOiIwMWY4ODVlZS05ZjY2LTQ3M2MtYmZkNC05MWM4ZGU3NGJhZjYiLCJjbGllbnRfaWQiOiJjcmVkZW50aWFsc19jbGllbnQiLCJzY29wZSI6Im9wZW5pZCB3ZWJpZCJ9.DYTlSRkORyDN28XtXk-zbR7xNLViD97KkPqUKb6chV860BaIgwa1suif4TxHQDnK_ejvbvmZ46_n5WwwRnf_Zw\" curl -sI -X PUT http://localhost:4000/alice/cth-test/ -H \"Content-Type: text/turtle\" -H \"Authorization: Bearer $ACCESS_TOKEN\")",
       "Bash(timeout 60 docker run:*)",
       "Bash(rm:*)",
-      "Bash(mkdir:*)"
+      "Bash(mkdir:*)",
+      "WebFetch(domain:communitysolidserver.github.io)"
     ]
   }
 }

package/README.md

@@ -54,7 +54,7 @@ npm run benchmark
 
 ## Features
 
-### Implemented (v0.0.15)
+### Implemented (v0.0.16)
 
 - **LDP CRUD Operations** - GET, PUT, POST, DELETE, HEAD
 - **N3 Patch** - Solid's native patch format for RDF updates
@@ -64,7 +64,8 @@ npm run benchmark
 - **SSL/TLS** - HTTPS support with certificate configuration
 - **WebSocket Notifications** - Real-time updates via solid-0.1 protocol (SolidOS compatible)
 - **Container Management** - Create, list, and manage containers
-- **Multi-user Pods** - Create pods at `/<username>/`
+- **Multi-user Pods** - Path-based (`/alice/`) or subdomain-based (`alice.example.com`)
+- **Subdomain Mode** - XSS protection via origin isolation
 - **WebID Profiles** - JSON-LD structured data in HTML at pod root
 - **Web Access Control (WAC)** - `.acl` file-based authorization
 - **Solid-OIDC Identity Provider** - Built-in IdP with DPoP, dynamic registration
@@ -135,6 +136,8 @@ jss --help             # Show help
 | `--notifications` | Enable WebSocket | false |
 | `--idp` | Enable built-in IdP | false |
 | `--idp-issuer <url>` | IdP issuer URL | (auto) |
+| `--subdomains` | Enable subdomain-based pods | false |
+| `--base-domain <domain>` | Base domain for subdomains | - |
 | `-q, --quiet` | Suppress logs | false |
 
 ### Environment Variables
@@ -146,6 +149,8 @@ export JSS_PORT=8443
 export JSS_SSL_KEY=/path/to/key.pem
 export JSS_SSL_CERT=/path/to/cert.pem
 export JSS_CONNEG=true
+export JSS_SUBDOMAINS=true
+export JSS_BASE_DOMAIN=example.com
 jss start
 ```
 
@@ -338,13 +343,66 @@ curl -H "Authorization: DPoP ACCESS_TOKEN" \
      http://localhost:3000/alice/private/
 ```
 
+## Subdomain Mode (XSS Protection)
+
+By default, JSS uses **path-based pods** (`/alice/`, `/bob/`). This is simple but has a security limitation: all pods share the same origin, making cross-site scripting (XSS) attacks possible between pods.
+
+**Subdomain mode** provides **origin isolation** - each pod gets its own subdomain (`alice.example.com`, `bob.example.com`), preventing XSS attacks between pods.
+
+### Why Subdomain Mode?
+
+| Mode | URL | Origin | XSS Risk |
+|------|-----|--------|----------|
+| Path-based | `example.com/alice/` | `example.com` | Shared origin - pods can XSS each other |
+| Subdomain | `alice.example.com/` | `alice.example.com` | Isolated - browser's Same-Origin Policy protects |
+
+### Enabling Subdomain Mode
+
+```bash
+jss start --subdomains --base-domain example.com
+```
+
+Or via environment variables:
+
+```bash
+export JSS_SUBDOMAINS=true
+export JSS_BASE_DOMAIN=example.com
+jss start
+```
+
+### DNS Configuration
+
+You need a **wildcard DNS record** pointing to your server:
+
+```
+*.example.com  A  <your-server-ip>
+```
+
+### Pod URLs in Subdomain Mode
+
+| Path Mode | Subdomain Mode |
+|-----------|----------------|
+| `example.com/alice/` | `alice.example.com/` |
+| `example.com/alice/public/file.txt` | `alice.example.com/public/file.txt` |
+| `example.com/alice/#me` | `alice.example.com/#me` |
+
+Pod creation still uses the main domain:
+
+```bash
+curl -X POST https://example.com/.pods \
+  -H "Content-Type: application/json" \
+  -d '{"name": "alice"}'
+```
+
 ## Configuration
 
 ```javascript
 createServer({
   logger: true,        // Enable Fastify logging (default: true)
   conneg: false,       // Enable content negotiation (default: false)
-  notifications: false // Enable WebSocket notifications (default: false)
+  notifications: false, // Enable WebSocket notifications (default: false)
+  subdomains: false,   // Enable subdomain-based pods (default: false)
+  baseDomain: null,    // Base domain for subdomains (e.g., "example.com")
 });
 ```
 

package/bin/jss.js

@@ -47,6 +47,9 @@ program
   .option('--idp', 'Enable built-in Identity Provider')
   .option('--no-idp', 'Disable built-in Identity Provider')
   .option('--idp-issuer <url>', 'IdP issuer URL (defaults to server URL)')
+  .option('--subdomains', 'Enable subdomain-based pods (XSS protection)')
+  .option('--no-subdomains', 'Disable subdomain-based pods')
+  .option('--base-domain <domain>', 'Base domain for subdomain pods (e.g., "example.com")')
   .option('-q, --quiet', 'Suppress log output')
   .option('--print-config', 'Print configuration and exit')
   .action(async (options) => {
@@ -80,6 +83,8 @@ program
           cert: await fs.readFile(config.sslCert),
         } : null,
         root: config.root,
+        subdomains: config.subdomains,
+        baseDomain: config.baseDomain,
       });
 
       await server.listen({ port: config.port, host: config.host });
@@ -92,6 +97,7 @@ program
         if (config.conneg) console.log('  Conneg: enabled');
         if (config.notifications) console.log('  WebSocket: enabled');
         if (config.idp) console.log(`  IdP: ${idpIssuer}`);
+        if (config.subdomains) console.log(`  Subdomains: ${config.baseDomain} (XSS protection enabled)`);
         console.log('\n  Press Ctrl+C to stop\n');
       }
 

package/package.json

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

package/src/auth/middleware.js

@@ -7,6 +7,7 @@
 import { getWebIdFromRequestAsync } from './token.js';
 import { checkAccess, getRequiredMode } from '../wac/checker.js';
 import * as storage from '../storage/filesystem.js';
+import { getEffectiveUrlPath } from '../utils/url.js';
 
 /**
  * Check if request is authorized
@@ -27,27 +28,32 @@ export async function authorize(request, reply) {
   // Get WebID from token (supports both simple and Solid-OIDC tokens)
   const { webId, error: authError } = await getWebIdFromRequestAsync(request);
 
+  // Get effective storage path (includes pod name in subdomain mode)
+  const storagePath = getEffectiveUrlPath(request);
+
   // Get resource info
-  const stats = await storage.stat(urlPath);
+  const stats = await storage.stat(storagePath);
   const resourceExists = stats !== null;
   const isContainer = stats?.isDirectory || urlPath.endsWith('/');
 
-  // Build resource URL
+  // Build resource URL (uses actual request hostname which may be subdomain)
   const resourceUrl = `${request.protocol}://${request.hostname}${urlPath}`;
 
   // Get required access mode for this method
   const requiredMode = getRequiredMode(method);
 
   // For write operations on non-existent resources, check parent container
-  let checkPath = urlPath;
+  let checkPath = storagePath;
   let checkUrl = resourceUrl;
   let checkIsContainer = isContainer;
 
   if (!resourceExists && (method === 'PUT' || method === 'POST' || method === 'PATCH')) {
     // Check write permission on parent container
-    const parentPath = getParentPath(urlPath);
+    const parentPath = getParentPath(storagePath);
     checkPath = parentPath;
-    checkUrl = `${request.protocol}://${request.hostname}${parentPath}`;
+    // For URL, also need to get parent
+    const parentUrlPath = getParentPath(urlPath);
+    checkUrl = `${request.protocol}://${request.hostname}${parentUrlPath}`;
     checkIsContainer = true;
   }
 

package/src/config.js

@@ -33,6 +33,10 @@ export const defaults = {
   idp: false,
   idpIssuer: null,
 
+  // Subdomain mode (XSS protection)
+  subdomains: false,
+  baseDomain: null,
+
   // Logging
   logger: true,
   quiet: false,
@@ -57,6 +61,8 @@ const envMap = {
   JSS_CONFIG_PATH: 'configPath',
   JSS_IDP: 'idp',
   JSS_IDP_ISSUER: 'idpIssuer',
+  JSS_SUBDOMAINS: 'subdomains',
+  JSS_BASE_DOMAIN: 'baseDomain',
 };
 
 /**
@@ -188,5 +194,6 @@ export function printConfig(config) {
   console.log(`  Conneg:        ${config.conneg}`);
   console.log(`  Notifications: ${config.notifications}`);
   console.log(`  IdP:           ${config.idp ? (config.idpIssuer || 'enabled') : 'disabled'}`);
+  console.log(`  Subdomains:    ${config.subdomains ? (config.baseDomain || 'enabled') : 'disabled'}`);
   console.log('─'.repeat(40));
 }

package/src/handlers/container.js

@@ -1,17 +1,30 @@
 import * as storage from '../storage/filesystem.js';
 import { getAllHeaders } from '../ldp/headers.js';
-import { isContainer } from '../utils/url.js';
+import { isContainer, getEffectiveUrlPath } 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 { emitChange } from '../notifications/events.js';
 
+/**
+ * Get the storage path and resource URL for a request
+ * In subdomain mode, storage path includes pod name, URL uses subdomain
+ */
+function getRequestPaths(request) {
+  const urlPath = request.url.split('?')[0];
+  // Storage path - includes pod name in subdomain mode
+  const storagePath = getEffectiveUrlPath(request);
+  // Resource URL - uses the actual request hostname (subdomain in subdomain mode)
+  const resourceUrl = `${request.protocol}://${request.hostname}${urlPath}`;
+  return { urlPath, storagePath, resourceUrl };
+}
+
 /**
  * Handle POST request to container (create new resource)
  */
 export async function handlePost(request, reply) {
-  const urlPath = request.url.split('?')[0];
+  const { urlPath, storagePath } = getRequestPaths(request);
 
   // Ensure target is a container
   if (!isContainer(urlPath)) {
@@ -32,10 +45,10 @@ export async function handlePost(request, reply) {
   }
 
   // Check container exists
-  const stats = await storage.stat(urlPath);
+  const stats = await storage.stat(storagePath);
   if (!stats || !stats.isDirectory) {
     // Create container if it doesn't exist
-    await storage.createContainer(urlPath);
+    await storage.createContainer(storagePath);
   }
 
   // Get slug from header or generate UUID
@@ -46,13 +59,14 @@ export async function handlePost(request, reply) {
   const isCreatingContainer = linkHeader.includes('Container') || linkHeader.includes('BasicContainer');
 
   // Generate unique filename
-  const filename = await storage.generateUniqueFilename(urlPath, slug, isCreatingContainer);
-  const newPath = urlPath + filename + (isCreatingContainer ? '/' : '');
-  const resourceUrl = `${request.protocol}://${request.hostname}${newPath}`;
+  const filename = await storage.generateUniqueFilename(storagePath, slug, isCreatingContainer);
+  const newUrlPath = urlPath + filename + (isCreatingContainer ? '/' : '');
+  const newStoragePath = storagePath + filename + (isCreatingContainer ? '/' : '');
+  const resourceUrl = `${request.protocol}://${request.hostname}${newUrlPath}`;
 
   let success;
   if (isCreatingContainer) {
-    success = await storage.createContainer(newPath);
+    success = await storage.createContainer(newStoragePath);
   } else {
     // Get content from request body
     let content = request.body;
@@ -80,7 +94,7 @@ export async function handlePost(request, reply) {
       }
     }
 
-    success = await storage.write(newPath, content);
+    success = await storage.write(newStoragePath, content);
   }
 
   if (!success) {
@@ -153,10 +167,24 @@ export async function handleCreatePod(request, reply) {
   }
 
   // Build URIs
-  // WebID is at pod root: /alice/#me
-  const baseUri = `${request.protocol}://${request.hostname}`;
-  const podUri = `${baseUri}${podPath}`;
-  const webId = `${podUri}#me`;
+  // WebID is at pod root: /alice/#me (path mode) or alice.example.com/#me (subdomain mode)
+  const subdomainsEnabled = request.subdomainsEnabled;
+  const baseDomain = request.baseDomain;
+
+  let baseUri, podUri, webId;
+  if (subdomainsEnabled && baseDomain) {
+    // Subdomain mode: alice.example.com/
+    const podHost = `${name}.${baseDomain}`;
+    baseUri = `${request.protocol}://${baseDomain}`;
+    podUri = `${request.protocol}://${podHost}/`;
+    webId = `${podUri}#me`;
+  } else {
+    // Path mode: example.com/alice/
+    baseUri = `${request.protocol}://${request.hostname}`;
+    podUri = `${baseUri}${podPath}`;
+    webId = `${podUri}#me`;
+  }
+
   // Issuer needs trailing slash for CTH compatibility
   const issuer = baseUri + '/';
 

package/src/handlers/resource.js

@@ -1,7 +1,7 @@
 import * as storage from '../storage/filesystem.js';
 import { getAllHeaders } from '../ldp/headers.js';
 import { generateContainerJsonLd, serializeJsonLd } from '../ldp/container.js';
-import { isContainer, getContentType, isRdfContentType } from '../utils/url.js';
+import { isContainer, getContentType, isRdfContentType, getEffectiveUrlPath } from '../utils/url.js';
 import { parseN3Patch, applyN3Patch, validatePatch } from '../patch/n3-patch.js';
 import { parseSparqlUpdate, applySparqlUpdate } from '../patch/sparql-update.js';
 import {
@@ -15,12 +15,25 @@ import {
 import { emitChange } from '../notifications/events.js';
 import { checkIfMatch, checkIfNoneMatchForGet, checkIfNoneMatchForWrite } from '../utils/conditional.js';
 
+/**
+ * Get the storage path and resource URL for a request
+ * In subdomain mode, storage path includes pod name, URL uses subdomain
+ */
+function getRequestPaths(request) {
+  const urlPath = request.url.split('?')[0];
+  // Storage path - includes pod name in subdomain mode
+  const storagePath = getEffectiveUrlPath(request);
+  // Resource URL - uses the actual request hostname (subdomain in subdomain mode)
+  const resourceUrl = `${request.protocol}://${request.hostname}${urlPath}`;
+  return { urlPath, storagePath, resourceUrl };
+}
+
 /**
  * Handle GET request
  */
 export async function handleGet(request, reply) {
-  const urlPath = request.url.split('?')[0]; // Remove query string
-  const stats = await storage.stat(urlPath);
+  const { urlPath, storagePath, resourceUrl } = getRequestPaths(request);
+  const stats = await storage.stat(storagePath);
 
   if (!stats) {
     return reply.code(404).send({ error: 'Not Found' });
@@ -36,14 +49,13 @@ export async function handleGet(request, reply) {
   }
 
   const origin = request.headers.origin;
-  const resourceUrl = `${request.protocol}://${request.hostname}${urlPath}`;
 
   // Handle container
   if (stats.isDirectory) {
     const connegEnabled = request.connegEnabled || false;
 
     // Check for index.html (serves as both profile and container representation)
-    const indexPath = urlPath.endsWith('/') ? `${urlPath}index.html` : `${urlPath}/index.html`;
+    const indexPath = storagePath.endsWith('/') ? `${storagePath}index.html` : `${storagePath}/index.html`;
     const indexExists = await storage.exists(indexPath);
 
     if (indexExists) {
@@ -105,7 +117,7 @@ export async function handleGet(request, reply) {
     }
 
     // No index.html, return JSON-LD container listing
-    const entries = await storage.listContainer(urlPath);
+    const entries = await storage.listContainer(storagePath);
     const jsonLd = generateContainerJsonLd(resourceUrl, entries || []);
 
     const headers = getAllHeaders({
@@ -122,12 +134,12 @@ export async function handleGet(request, reply) {
   }
 
   // Handle resource
-  const content = await storage.read(urlPath);
+  const content = await storage.read(storagePath);
   if (content === null) {
     return reply.code(500).send({ error: 'Read error' });
   }
 
-  const storedContentType = getContentType(urlPath);
+  const storedContentType = getContentType(storagePath);
   const connegEnabled = request.connegEnabled || false;
 
   // Content negotiation for RDF resources
@@ -184,16 +196,15 @@ export async function handleGet(request, reply) {
  * Handle HEAD request
  */
 export async function handleHead(request, reply) {
-  const urlPath = request.url.split('?')[0];
-  const stats = await storage.stat(urlPath);
+  const { storagePath, resourceUrl } = getRequestPaths(request);
+  const stats = await storage.stat(storagePath);
 
   if (!stats) {
     return reply.code(404).send();
   }
 
   const origin = request.headers.origin;
-  const resourceUrl = `${request.protocol}://${request.hostname}${urlPath}`;
-  const contentType = stats.isDirectory ? 'application/ld+json' : getContentType(urlPath);
+  const contentType = stats.isDirectory ? 'application/ld+json' : getContentType(storagePath);
 
   const headers = getAllHeaders({
     isContainer: stats.isDirectory,
@@ -215,20 +226,19 @@ export async function handleHead(request, reply) {
  * Handle PUT request
  */
 export async function handlePut(request, reply) {
-  const urlPath = request.url.split('?')[0];
+  const { urlPath, storagePath, resourceUrl } = getRequestPaths(request);
   const connegEnabled = request.connegEnabled || false;
-  const resourceUrl = `${request.protocol}://${request.hostname}${urlPath}`;
 
   // Handle container creation via PUT
   if (isContainer(urlPath)) {
-    const stats = await storage.stat(urlPath);
+    const stats = await storage.stat(storagePath);
     if (stats?.isDirectory) {
       // Container already exists - don't allow PUT to modify
       return reply.code(409).send({ error: 'Cannot PUT to existing container' });
     }
 
     // Create the container (and any intermediate containers)
-    const success = await storage.createContainer(urlPath);
+    const success = await storage.createContainer(storagePath);
     if (!success) {
       return reply.code(500).send({ error: 'Failed to create container' });
     }
@@ -258,7 +268,7 @@ export async function handlePut(request, reply) {
   }
 
   // Check if resource already exists and get current ETag
-  const stats = await storage.stat(urlPath);
+  const stats = await storage.stat(storagePath);
   const existed = stats !== null;
   const currentEtag = stats?.etag || null;
 
@@ -308,7 +318,7 @@ export async function handlePut(request, reply) {
     }
   }
 
-  const success = await storage.write(urlPath, content);
+  const success = await storage.write(storagePath, content);
   if (!success) {
     return reply.code(500).send({ error: 'Write failed' });
   }
@@ -332,10 +342,10 @@ export async function handlePut(request, reply) {
  * Handle DELETE request
  */
 export async function handleDelete(request, reply) {
-  const urlPath = request.url.split('?')[0];
+  const { storagePath, resourceUrl } = getRequestPaths(request);
 
   // Check if resource exists and get current ETag
-  const stats = await storage.stat(urlPath);
+  const stats = await storage.stat(storagePath);
   if (!stats) {
     return reply.code(404).send({ error: 'Not Found' });
   }
@@ -349,13 +359,12 @@ export async function handleDelete(request, reply) {
     }
   }
 
-  const success = await storage.remove(urlPath);
+  const success = await storage.remove(storagePath);
   if (!success) {
     return reply.code(500).send({ error: 'Delete failed' });
   }
 
   const origin = request.headers.origin;
-  const resourceUrl = `${request.protocol}://${request.hostname}${urlPath}`;
   const headers = getAllHeaders({ isContainer: false, origin, resourceUrl });
   Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
 
@@ -371,11 +380,10 @@ export async function handleDelete(request, reply) {
  * Handle OPTIONS request
  */
 export async function handleOptions(request, reply) {
-  const urlPath = request.url.split('?')[0];
-  const stats = await storage.stat(urlPath);
+  const { urlPath, storagePath, resourceUrl } = getRequestPaths(request);
+  const stats = await storage.stat(storagePath);
 
   const origin = request.headers.origin;
-  const resourceUrl = `${request.protocol}://${request.hostname}${urlPath}`;
   const connegEnabled = request.connegEnabled || false;
   const headers = getAllHeaders({
     isContainer: stats?.isDirectory || isContainer(urlPath),
@@ -393,7 +401,7 @@ export async function handleOptions(request, reply) {
  * Supports N3 Patch format (text/n3) and SPARQL Update for updating RDF resources
  */
 export async function handlePatch(request, reply) {
-  const urlPath = request.url.split('?')[0];
+  const { urlPath, storagePath, resourceUrl } = getRequestPaths(request);
 
   // Don't allow PATCH to containers
   if (isContainer(urlPath)) {
@@ -413,7 +421,7 @@ export async function handlePatch(request, reply) {
   }
 
   // Check if resource exists
-  const stats = await storage.stat(urlPath);
+  const stats = await storage.stat(storagePath);
   if (!stats) {
     return reply.code(404).send({ error: 'Not Found' });
   }
@@ -428,7 +436,7 @@ export async function handlePatch(request, reply) {
   }
 
   // Read existing content
-  const existingContent = await storage.read(urlPath);
+  const existingContent = await storage.read(storagePath);
   if (existingContent === null) {
     return reply.code(500).send({ error: 'Read error' });
   }
@@ -449,8 +457,6 @@ export async function handlePatch(request, reply) {
     ? request.body.toString()
     : request.body;
 
-  const resourceUrl = `${request.protocol}://${request.hostname}${urlPath}`;
-
   let updatedDocument;
 
   if (isSparqlUpdate) {
@@ -497,7 +503,7 @@ export async function handlePatch(request, reply) {
 
   // Write updated document
   const updatedContent = JSON.stringify(updatedDocument, null, 2);
-  const success = await storage.write(urlPath, Buffer.from(updatedContent));
+  const success = await storage.write(storagePath, Buffer.from(updatedContent));
 
   if (!success) {
     return reply.code(500).send({ error: 'Write failed' });

package/src/server.js

@@ -16,6 +16,8 @@ import { idpPlugin } from './idp/index.js';
  * @param {string} options.idpIssuer - IdP issuer URL (default: server URL)
  * @param {object} options.ssl - SSL configuration { key, cert } (default null)
  * @param {string} options.root - Data directory path (default from env or ./data)
+ * @param {boolean} options.subdomains - Enable subdomain-based pods for XSS protection (default false)
+ * @param {string} options.baseDomain - Base domain for subdomain pods (e.g., "example.com")
  */
 export function createServer(options = {}) {
   // Content negotiation is OFF by default - we're a JSON-LD native server
@@ -25,6 +27,9 @@ export function createServer(options = {}) {
   // Identity Provider is OFF by default
   const idpEnabled = options.idp ?? false;
   const idpIssuer = options.idpIssuer;
+  // Subdomain mode is OFF by default - use path-based pods
+  const subdomainsEnabled = options.subdomains ?? false;
+  const baseDomain = options.baseDomain || null;
 
   // Set data root via environment variable if provided
   if (options.root) {
@@ -58,10 +63,29 @@ export function createServer(options = {}) {
   fastify.decorateRequest('connegEnabled', null);
   fastify.decorateRequest('notificationsEnabled', null);
   fastify.decorateRequest('idpEnabled', null);
+  fastify.decorateRequest('subdomainsEnabled', null);
+  fastify.decorateRequest('baseDomain', null);
+  fastify.decorateRequest('podName', null);
   fastify.addHook('onRequest', async (request) => {
     request.connegEnabled = connegEnabled;
     request.notificationsEnabled = notificationsEnabled;
     request.idpEnabled = idpEnabled;
+    request.subdomainsEnabled = subdomainsEnabled;
+    request.baseDomain = baseDomain;
+
+    // Extract pod name from subdomain if enabled
+    if (subdomainsEnabled && baseDomain) {
+      const host = request.hostname;
+      // Check if host is a subdomain of baseDomain
+      if (host !== baseDomain && host.endsWith('.' + baseDomain)) {
+        // Extract subdomain (e.g., "alice.example.com" -> "alice")
+        const subdomain = host.slice(0, -(baseDomain.length + 1));
+        // Only single-level subdomains (no dots)
+        if (!subdomain.includes('.')) {
+          request.podName = subdomain;
+        }
+      }
+    }
   });
 
   // Register WebSocket notifications plugin if enabled

package/src/utils/url.js

@@ -19,6 +19,58 @@ export function urlToPath(urlPath) {
   return path.join(DATA_ROOT, normalized);
 }
 
+/**
+ * Convert URL path to filesystem path in subdomain mode
+ * In subdomain mode, the pod is determined by the hostname, not the path
+ * @param {string} urlPath - The URL path (e.g., /public/file.txt)
+ * @param {string} podName - The pod name from subdomain (e.g., "alice")
+ * @returns {string} - Filesystem path (e.g., DATA_ROOT/alice/public/file.txt)
+ */
+export function urlToPathWithPod(urlPath, podName) {
+  // Normalize: remove leading slash, decode URI
+  let normalized = urlPath.startsWith('/') ? urlPath.slice(1) : urlPath;
+  normalized = decodeURIComponent(normalized);
+
+  // Security: prevent path traversal
+  normalized = normalized.replace(/\.\./g, '');
+
+  // Prepend pod name to path
+  return path.join(DATA_ROOT, podName, normalized);
+}
+
+/**
+ * Get the effective path for a request (subdomain-aware)
+ * @param {object} request - Fastify request object
+ * @returns {string} - Filesystem path
+ */
+export function getPathFromRequest(request) {
+  const urlPath = request.url.split('?')[0];
+
+  // In subdomain mode with a recognized pod subdomain
+  if (request.subdomainsEnabled && request.podName) {
+    return urlToPathWithPod(urlPath, request.podName);
+  }
+
+  // Path-based mode (default)
+  return urlToPath(urlPath);
+}
+
+/**
+ * Get the effective URL path for a request (with pod prefix in subdomain mode)
+ * @param {object} request - Fastify request object
+ * @returns {string} - URL path with pod prefix if needed
+ */
+export function getEffectiveUrlPath(request) {
+  const urlPath = request.url.split('?')[0];
+
+  // In subdomain mode with a recognized pod subdomain, prepend pod name
+  if (request.subdomainsEnabled && request.podName) {
+    return '/' + request.podName + urlPath;
+  }
+
+  return urlPath;
+}
+
 /**
  * Check if URL path represents a container (ends with /)
  * @param {string} urlPath

package/test-data-idp-accounts/.idp/accounts/3c1cd503-1d7f-4ba0-a3af-ebedf519594d.json

@@ -0,0 +1,9 @@
+{
+  "id": "3c1cd503-1d7f-4ba0-a3af-ebedf519594d",
+  "email": "credtest@example.com",
+  "passwordHash": "$2b$10$h3cRwsgAo/4wEOyip6ckyOf6J.reHOzJzyZrM.LDfQdIWa3e/MkAu",
+  "webId": "http://localhost:3101/credtest/#me",
+  "podName": "credtest",
+  "createdAt": "2025-12-27T12:48:00.226Z",
+  "lastLogin": "2025-12-27T12:48:00.567Z"
+}

package/test-data-idp-accounts/.idp/accounts/_email_index.json

@@ -1,3 +1,3 @@
 {
-  "credtest@example.com": "292738d6-3363-4f40-9a6b-884bfd17830a"
+  "credtest@example.com": "3c1cd503-1d7f-4ba0-a3af-ebedf519594d"
 }

package/test-data-idp-accounts/.idp/accounts/_webid_index.json

@@ -1,3 +1,3 @@
 {
-  "http://localhost:3101/credtest/#me": "292738d6-3363-4f40-9a6b-884bfd17830a"
+  "http://localhost:3101/credtest/#me": "3c1cd503-1d7f-4ba0-a3af-ebedf519594d"
 }

package/test-data-idp-accounts/.idp/keys/jwks.json

@@ -3,20 +3,20 @@
     "keys": [
       {
         "kty": "EC",
-        "x": "1gMgS0xMseqjfq5fA_aYkkq7CMqr6OOQ5ZS4D3MqG6g",
-        "y": "rtkAdN0tManytaX1QDFRBRE6GXoOlxqj_d3Yt5mpViA",
+        "x": "NzQ-skj7cwbmI4Q_-vlQzoPYoQLWq_u34ln95VMcpnU",
+        "y": "H6gMaardV77boCWD4OTix1DsxdY-clIBw7I5xvvDDe8",
         "crv": "P-256",
-        "d": "GqEv1nO1PRgrKE7n18iDNow-haou-7B6_dlMqo-ftLQ",
-        "kid": "102e3c82-7dda-4a6f-a296-d47d9b2e0b59",
+        "d": "WrlpdJo_JidHFldBjU4Q6Wv_ULhAk1j-DTU6YlHxDAQ",
+        "kid": "4e655460-7c94-479c-9ed8-923aa8bfd77f",
         "use": "sig",
         "alg": "ES256",
-        "iat": 1766838193
+        "iat": 1766839680
       }
     ]
   },
   "cookieKeys": [
-    "PQdsUKa6PcaWNBEUm9G3IZumxoXHnd93rUcyf9VYc0w",
-    "T4X4hUYp3dE9LakGJX9U5fRux5pyldcrpg_t8AA4FYg"
+    "CQXN03oU_rUqugGhwZgoiI7eZMgKJaPE_kyrT9lmTu4",
+    "jsJGLtKzYy-RJPZaAMZDpUcfY4-EtdqNOFS-Uiowk9w"
   ],
-  "createdAt": "2025-12-27T12:23:13.203Z"
+  "createdAt": "2025-12-27T12:48:00.136Z"
 }

package/test-data-idp-accounts/.idp/accounts/292738d6-3363-4f40-9a6b-884bfd17830a.json

@@ -1,9 +0,0 @@
-{
-  "id": "292738d6-3363-4f40-9a6b-884bfd17830a",
-  "email": "credtest@example.com",
-  "passwordHash": "$2b$10$tvcMaMvecS7noqe/T/A5Q.VojfNu1FEPAzWhl/.3v7WXrVIH38iYC",
-  "webId": "http://localhost:3101/credtest/#me",
-  "podName": "credtest",
-  "createdAt": "2025-12-27T12:23:13.338Z",
-  "lastLogin": "2025-12-27T12:23:13.871Z"
-}