javascript-solid-server 0.0.109 → 0.0.111

package/docs/security.md

@@ -0,0 +1,96 @@
+## Security
+
+### Root ACL Required
+
+JSS uses **restrictive mode** by default: if no ACL file exists for a resource, access is denied. This prevents unauthorized writes to unprotected containers.
+
+**You must create a root `.acl` file** in your data directory. Example (JSON-LD format):
+
+```json
+{
+  "@context": {
+    "acl": "http://www.w3.org/ns/auth/acl#",
+    "foaf": "http://xmlns.com/foaf/0.1/"
+  },
+  "@graph": [
+    {
+      "@id": "#owner",
+      "@type": "acl:Authorization",
+      "acl:agent": { "@id": "https://your-domain.com/profile/card#me" },
+      "acl:accessTo": { "@id": "https://your-domain.com/" },
+      "acl:default": { "@id": "https://your-domain.com/" },
+      "acl:mode": [
+        { "@id": "acl:Read" },
+        { "@id": "acl:Write" },
+        { "@id": "acl:Control" }
+      ]
+    },
+    {
+      "@id": "#public",
+      "@type": "acl:Authorization",
+      "acl:agentClass": { "@id": "foaf:Agent" },
+      "acl:accessTo": { "@id": "https://your-domain.com/" },
+      "acl:default": { "@id": "https://your-domain.com/" },
+      "acl:mode": [
+        { "@id": "acl:Read" }
+      ]
+    }
+  ]
+}
+```
+
+Save this as `data/.acl` (replacing `your-domain.com` with your actual domain).
+
+See [Issue #32](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/32) for background.
+
+## 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"}'
+```
+

package/docs/webrtc.md

@@ -0,0 +1,66 @@
+## WebRTC Signaling
+
+Peer-to-peer communication via WebRTC, using JSS as the signaling server. Once peers are connected, all media and data flows directly between them.
+
+```bash
+jss start --webrtc
+```
+
+### How It Works
+
+1. Both peers connect to `wss://your.pod/.webrtc` (WebID auth required)
+2. Caller sends an SDP offer targeting the callee's WebID
+3. JSS relays the offer/answer and ICE candidates between peers
+4. Once a direct path is found, the peer-to-peer connection is established
+5. JSS steps out — video, audio, files, and data flow directly between peers
+
+### Protocol
+
+Messages are JSON over WebSocket:
+
+```js
+// Send an offer to another user
+{ "type": "offer", "to": "https://bob.example/profile/card#me", "sdp": "..." }
+
+// Receive an offer from another user
+{ "type": "offer", "from": "https://alice.example/profile/card#me", "sdp": "..." }
+
+// ICE candidate exchange
+{ "type": "candidate", "to": "https://bob.example/profile/card#me", "candidate": {...} }
+
+// Hang up
+{ "type": "hangup", "to": "https://bob.example/profile/card#me" }
+```
+
+On connect, peers receive a list of online users and get notified when others join or leave.
+
+## Tunnel Proxy (Decentralized ngrok)
+
+Expose a local dev server to the internet through your JSS pod. A tunnel client connects via WebSocket, registers a name, and receives proxied HTTP requests.
+
+```bash
+jss start --tunnel
+```
+
+### How It Works
+
+1. Tunnel client connects to `wss://your.pod/.tunnel` (WebID auth required)
+2. Client registers a name: `{ "type": "register", "name": "myapp" }`
+3. Public URL becomes available at `https://your.pod/tunnel/myapp/`
+4. HTTP requests to that URL are serialized and sent to the tunnel client over WebSocket
+5. Tunnel client forwards to localhost, returns the response
+
+### Tunnel Client Protocol
+
+```js
+// 1. Register a tunnel
+→ { "type": "register", "name": "myapp" }
+← { "type": "registered", "name": "myapp", "url": "/tunnel/myapp/" }
+
+// 2. Receive proxied HTTP requests
+← { "type": "request", "id": "uuid", "method": "GET", "path": "/api/hello", "headers": {...} }
+
+// 3. Return the response
+→ { "type": "response", "id": "uuid", "status": 200, "headers": {...}, "body": "..." }
+```
+

package/package.json

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

package/src/patch/n3-patch.js

@@ -57,6 +57,7 @@ export function parseN3Patch(patchText, baseUri) {
 
 /**
  * Parse triples from N3 block content
+ * Handles Turtle semicolon shorthand (same subject, different predicate-object)
  */
 function parseTriples(content, prefixes, baseUri) {
   const triples = [];
@@ -68,11 +69,37 @@ function parseTriples(content, prefixes, baseUri) {
   // Split by '.' but be careful with strings containing '.'
   const statements = splitStatements(content);
 
+  let lastSubject = null;
   for (const stmt of statements) {
-    const triple = parseStatement(stmt.trim(), prefixes, baseUri);
-    if (triple) {
-      triples.push(triple);
+    const trimmed = stmt.trim();
+    if (!trimmed) continue;
+
+    const tokens = tokenize(trimmed);
+    if (tokens.length < 2) continue;
+
+    let subject, predicate, object;
+
+    if (tokens.length >= 3) {
+      // Full triple: subject predicate object
+      subject = resolveValue(tokens[0], prefixes, baseUri);
+      predicate = resolveValue(tokens[1], prefixes, baseUri);
+      object = resolveValue(tokens.slice(2).join(' '), prefixes, baseUri);
+      lastSubject = subject;
+    } else if (tokens.length === 2 && lastSubject) {
+      // Semicolon continuation: predicate object (reuse last subject)
+      subject = lastSubject;
+      predicate = resolveValue(tokens[0], prefixes, baseUri);
+      object = resolveValue(tokens[1], prefixes, baseUri);
+    } else {
+      continue;
+    }
+
+    // Handle 'a' as rdf:type
+    if (predicate === 'a') {
+      predicate = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type';
     }
+
+    triples.push({ subject, predicate, object });
   }
 
   return triples;
@@ -86,11 +113,18 @@ function splitStatements(content) {
   let current = '';
   let inString = false;
   let stringChar = null;
+  let inIri = false;
 
   for (let i = 0; i < content.length; i++) {
     const char = content[i];
 
-    if (!inString && (char === '"' || char === "'")) {
+    if (!inString && !inIri && char === '<') {
+      inIri = true;
+      current += char;
+    } else if (inIri && char === '>') {
+      inIri = false;
+      current += char;
+    } else if (!inIri && !inString && (char === '"' || char === "'")) {
       inString = true;
       stringChar = char;
       current += char;
@@ -98,12 +132,12 @@ function splitStatements(content) {
       inString = false;
       stringChar = null;
       current += char;
-    } else if (!inString && char === '.') {
+    } else if (!inString && !inIri && char === '.') {
       if (current.trim()) {
         statements.push(current);
       }
       current = '';
-    } else if (!inString && char === ';') {
+    } else if (!inString && !inIri && char === ';') {
       // Turtle shorthand - same subject, different predicate
       if (current.trim()) {
         statements.push(current);
@@ -121,23 +155,6 @@ function splitStatements(content) {
   return statements;
 }
 
-/**
- * Parse a single N3 statement into a triple
- */
-function parseStatement(stmt, prefixes, baseUri) {
-  if (!stmt) return null;
-
-  // Tokenize - split by whitespace but respect quotes
-  const tokens = tokenize(stmt);
-  if (tokens.length < 3) return null;
-
-  const subject = resolveValue(tokens[0], prefixes, baseUri);
-  const predicate = resolveValue(tokens[1], prefixes, baseUri);
-  const object = resolveValue(tokens.slice(2).join(' '), prefixes, baseUri);
-
-  return { subject, predicate, object };
-}
-
 /**
  * Tokenize a statement respecting quoted strings
  */

package/test/patch.test.js

@@ -185,6 +185,67 @@ describe('PATCH Operations', () => {
       assert.ok(data['@graph'], 'Should have @graph');
       assert.strictEqual(data['@graph'].length, 2, 'Should have 2 nodes');
     });
+
+    it('should handle semicolon shorthand and rdf:type "a" keyword', async () => {
+      // Create initial resource with @graph
+      const initial = {
+        '@context': { 'solid': 'http://www.w3.org/ns/solid/terms#' },
+        '@graph': []
+      };
+
+      await request('/patchtest/public/patch-semicolon.json', {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/ld+json' },
+        body: JSON.stringify(initial),
+        auth: 'patchtest'
+      });
+
+      // Use semicolons and 'a' keyword (Turtle shorthand)
+      const patch = `
+        @prefix solid: <http://www.w3.org/ns/solid/terms#>.
+        @prefix wf: <http://www.w3.org/2005/01/wf/flow#>.
+        _:patch a solid:InsertDeletePatch;
+          solid:inserts {
+            <#reg1> a solid:TypeRegistration;
+              solid:forClass wf:Tracker;
+              solid:instance <https://example.com/todo/data.jsonld#this>.
+          }.
+      `;
+
+      const res = await request('/patchtest/public/patch-semicolon.json', {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'text/n3' },
+        body: patch,
+        auth: 'patchtest'
+      });
+
+      assertStatus(res, 204);
+
+      // Verify all three triples were inserted
+      const verify = await request('/patchtest/public/patch-semicolon.json');
+      const data = await verify.json();
+      const node = data['@graph'].find(n => n['@id'] && n['@id'].includes('#reg1'));
+      assert.ok(node, 'Should have the reg1 node');
+
+      // Check rdf:type value (from 'a' keyword)
+      const rdfType = node['rdf:type'] || node['http://www.w3.org/1999/02/22-rdf-syntax-ns#type'];
+      assert.ok(rdfType, 'Should have rdf:type (from "a" keyword)');
+      const typeId = rdfType['@id'] || rdfType;
+      assert.ok(String(typeId).includes('TypeRegistration'), `rdf:type should be TypeRegistration, got ${typeId}`);
+
+      // Check solid:forClass value
+      const forClass = node['solid:forClass'];
+      assert.ok(forClass, 'Should have solid:forClass');
+      const forClassId = forClass['@id'] || forClass;
+      assert.ok(String(forClassId).includes('Tracker'), `solid:forClass should be Tracker, got ${forClassId}`);
+
+      // Check solid:instance value (contains a dot in the IRI - tests IRI splitting)
+      const instance = node['solid:instance'];
+      assert.ok(instance, 'Should have solid:instance');
+      const instanceId = instance['@id'] || instance;
+      assert.strictEqual(instanceId, 'https://example.com/todo/data.jsonld#this',
+        'solid:instance should have full IRI preserved');
+    });
   });
 
   describe('PATCH Error Handling', () => {