javascript-solid-server 0.0.110 → 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.110",
+  "version": "0.0.111",
   "description": "A minimal, fast Solid server",
   "main": "src/index.js",
   "type": "module",