javascript-solid-server 0.0.7 → 0.0.9

package/.claude/settings.local.json

@@ -13,7 +13,9 @@
       "Bash(pkill:*)",
       "Bash(curl:*)",
       "Bash(npm test:*)",
-      "Bash(git add:*)"
+      "Bash(git add:*)",
+      "WebFetch(domain:solid.github.io)",
+      "Bash(node:*)"
     ]
   }
 }

package/README.md

@@ -1,209 +1,230 @@
-# Vision
+# JavaScript Solid Server
 
-The goal of this project is to create a hyper-modern, performant, and minimalist JavaScript Solid server. While drawing inspiration from Node Solid Server (NSS), this new implementation will address its shortcomings and prioritize scalability, modularity, and developer usability.
+A minimal, fast, JSON-LD native Solid server.
 
-## Key Objectives
+## Philosophy: JSON-LD First
 
-- **Performance First:** Capable of handling enterprise-scale loads, targeting thousands to millions of users.
-- **Minimalist Design:** Remove unused and experimental features; focus on what matters most.
-- **Modularity:** Clear separation of identity, authentication, storage, and onboarding.
-- **Developer Friendly:** Clean, well-documented, and extensible codebase that adheres to the Solid specification.
-- **Modern Tooling:** Leverage async/await, native modules, fast HTTP servers like Fastify, and cutting-edge JavaScript runtimes.
-- **HTTP Simplicity:** Prioritize simple HTTP/1.1 compatibility for maximum interoperability.
-- **Frontend Agnostic:** Work with any frontend or application layer via standardized APIs.
-- **Testable and CI Ready:** Fully integrated with Solid test suites and modern CI/CD pipelines.
+This is a **JSON-LD native implementation**. Unlike traditional Solid servers that treat Turtle as the primary format and convert to/from it, this server:
 
----
+- **Stores everything as JSON-LD** - No RDF parsing overhead for standard operations
+- **Serves JSON-LD by default** - Modern web applications can consume responses directly
+- **Content negotiation is optional** - Enable Turtle support with `{ conneg: true }` when needed
+- **Fast by design** - Skip the RDF parsing tax when you don't need it
 
-# ARCHITECTURE
+### Why JSON-LD First?
 
-## Overview
+1. **Performance**: JSON parsing is native to JavaScript - no external RDF libraries needed for basic operations
+2. **Simplicity**: JSON-LD is valid JSON - works with any JSON tooling
+3. **Web-native**: Browsers and web apps understand JSON natively
+4. **Semantic web ready**: JSON-LD is a W3C standard RDF serialization
 
-The architecture is inspired by NSS but modernized and streamlined. Each subsystem is designed to operate independently and follow the single-responsibility principle.
+### When to Enable Content Negotiation
 
-### Components
+Enable `conneg: true` when:
+- Interoperating with Turtle-based Solid apps
+- Serving data to legacy Solid clients
+- Running conformance tests that require Turtle support
 
-- **HTTP Layer**
+```javascript
+import { createServer } from './src/server.js';
 
-  - Fastify server
-  - Routing and middleware based on HTTP verbs and Solid operations
-  - Blazingly fast, with benchmarks from the start
+// Default: JSON-LD only (fast)
+const server = createServer();
 
-- **Identity Provider (IDP)**
-
-  - Handles Pod based WebIDs
-  - Handles external WebIDs
-  - Minimal by default, extendable via plugins
-
-- **Authenticaion Module (AUthn)**
-
-  - Handles WebID-based authentication, including WebID-TLS
-  - OIDC-compliant with modular Authentication
-  - Single sign-on including WebID-TLS
-
-- **Authorization Module (Authz)**
-
-  - Supports Web Access Control (WAC)
-  - Token-based permissions model
-  - Modular Authorization system
-
-- **Storage Engine**
-
-  - Modular backend adapters (e.g. file system, S3, memory)
-  - POD-level quota management (optional)
-  - Interoperable with existing Cloud
-
-- **Account and Onboarding**
-  - API-first registration
-  - Public, private, invite modes
-  - Extensible account templates
-
-### Deployment Model
-
-- Works as a single binary or serverless function
-- Container-friendly (Docker, Deno, etc.)
-- CLI for local dev setup and testing
-
-### Separation of Concerns
-
-- Each subsystem lives in its own module/package
-- Clear boundaries between IDP and storage
-- Frontend-independent API endpoints
-
-### Compatibility
-
-- Solid-compliant, LWS Compliant
-- API parity with NSS where applicable
-- API parity with CSS where applicable
-
----
-
-# MVP Implementation
+// With Turtle support (for interoperability)
+const serverWithConneg = createServer({ conneg: true });
+```
 
-This is a minimal viable product (MVP) implementation of the JavaScriptSolid server. It includes the core components needed to demonstrate the concept while omitting some of the more complex features for simplicity.
+## Features
+
+### Implemented (v0.0.8)
+
+- **LDP CRUD Operations** - GET, PUT, POST, DELETE, HEAD
+- **N3 Patch** - Solid's native patch format for RDF updates
+- **Container Management** - Create, list, and manage containers
+- **Multi-user Pods** - Create pods at `/<username>/`
+- **WebID Profiles** - JSON-LD structured data in HTML at pod root
+- **Web Access Control (WAC)** - `.acl` file-based authorization
+- **Solid-OIDC Resource Server** - Accept DPoP-bound access tokens from external IdPs
+- **Simple Auth Tokens** - Built-in token authentication for development
+- **Content Negotiation** - Optional Turtle <-> JSON-LD conversion
+- **CORS Support** - Full cross-origin resource sharing
+
+### HTTP Methods
+
+| Method | Support |
+|--------|---------|
+| GET | Full - Resources and containers |
+| HEAD | Full |
+| PUT | Full - Create/update resources |
+| POST | Full - Create in containers |
+| DELETE | Full |
+| PATCH | N3 Patch format |
+| OPTIONS | Full with CORS |
 
 ## Getting Started
 
 ### Prerequisites
 
-- Node.js 18 or higher
+- Node.js 18+
 
 ### Installation
 
 ```bash
-# Clone the repository
-git clone https://github.com/yourusername/javascript-solid-server.git
-cd javascript-solid-server
-
-# Install dependencies
 npm install
 ```
 
-### Running the Server
+### Running
 
 ```bash
-# Start the server
+# Start server (default port 3000)
 npm start
-```
 
-The server will be available at http://localhost:3000 by default.
+# Development mode with watch
+npm dev
+```
 
-## Features Included in MVP
+### Creating a Pod
 
-- **HTTP Server**: Based on Fastify for high performance
-- **Basic Identity Provider**: Simple user registration and login with JWT tokens
-- **Simple Authorization**: Basic implementation of WAC (Web Access Control)
-- **File-based Storage**: Local filesystem storage for Solid resources
-- **Basic Solid Protocol Support**: GET, PUT, DELETE, PATCH, and HEAD operations
+```bash
+curl -X POST http://localhost:3000/.pods \
+  -H "Content-Type: application/json" \
+  -d '{"name": "alice"}'
+```
 
-## Features Omitted in MVP (to be added later)
+Response:
+```json
+{
+  "name": "alice",
+  "webId": "http://localhost:3000/alice/#me",
+  "podUri": "http://localhost:3000/alice/",
+  "token": "eyJ..."
+}
+```
 
-1. WebID-TLS Authentication
-2. Full OIDC implementation
-3. Advanced WAC features and ACL file parsing
-4. Quotas and resource limits
-5. Advanced container management
-6. SPARQL and N3 Patch support
-7. Notification systems
+### Using the Pod
 
-## API Usage Examples
+```bash
+# Read public profile
+curl http://localhost:3000/alice/
 
-### User Registration
+# Write to pod (with token)
+curl -X PUT http://localhost:3000/alice/public/data.json \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/ld+json" \
+  -d '{"@id": "#data", "http://example.org/value": 42}'
 
-```bash
-curl -X POST http://localhost:3000/register \
-  -H "Content-Type: application/json" \
-  -d '{"username": "alice", "password": "secret", "email": "alice@example.com"}'
+# Read back
+curl http://localhost:3000/alice/public/data.json
 ```
 
-### Login
+### PATCH with N3
 
 ```bash
-curl -X POST http://localhost:3000/login \
-  -H "Content-Type: application/json" \
-  -d '{"username": "alice", "password": "secret"}'
+curl -X PATCH http://localhost:3000/alice/public/data.json \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: text/n3" \
+  -d '@prefix solid: <http://www.w3.org/ns/solid/terms#>.
+      _:patch a solid:InsertDeletePatch;
+        solid:inserts { <#data> <http://example.org/name> "Updated" }.'
 ```
 
-### Accessing Resources
+## Pod Structure
 
-```bash
-# Get a resource
-curl -X GET http://localhost:3000/alice/profile \
-  -H "Authorization: Bearer YOUR_TOKEN_HERE"
-
-# Create or update a resource
-curl -X PUT http://localhost:3000/alice/profile \
-  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
-  -H "Content-Type: text/turtle" \
-  -d '@prefix foaf: <http://xmlns.com/foaf/0.1/>. <#me> a foaf:Person; foaf:name "Alice".'
+```
+/alice/
+├── index.html          # WebID profile (HTML with JSON-LD)
+├── .acl                 # Root ACL (owner + public read)
+├── inbox/              # Notifications (public append)
+│   └── .acl
+├── public/             # Public files
+├── private/            # Private files (owner only)
+│   └── .acl
+└── settings/           # User preferences (owner only)
+    ├── .acl
+    ├── prefs
+    ├── publicTypeIndex
+    └── privateTypeIndex
 ```
 
-## Performance Benchmarking
+## Authentication
 
-This project includes a comprehensive benchmarking tool to measure server performance under various loads.
+### Simple Tokens (Development)
 
-### Running the Benchmark
+Use the token returned from pod creation:
 
 ```bash
-# Make sure the server is running in a separate terminal
-npm start
-
-# In another terminal, run the benchmark
-npm run benchmark
+curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:3000/alice/private/
 ```
 
-The benchmark will:
+### Solid-OIDC (Production)
+
+The server accepts DPoP-bound access tokens from external Solid identity providers:
+
+```bash
+curl -H "Authorization: DPoP ACCESS_TOKEN" \
+     -H "DPoP: DPOP_PROOF" \
+     http://localhost:3000/alice/private/
+```
 
-1. Create multiple test users
-2. Execute various operations (register, login, read, write, delete)
-3. Measure response times for each operation type
-4. Test different concurrency levels (1, 5, 10, 50, 100 users)
-5. Calculate throughput (operations per second)
+## Configuration
 
-### Visualizing Results
+```javascript
+createServer({
+  logger: true,     // Enable Fastify logging (default: true)
+  conneg: false     // Enable content negotiation (default: false)
+});
+```
 
-After running the benchmark, you can generate a visual report:
+## Running Tests
 
 ```bash
-# Generate an HTML report with charts
-npm run visualize benchmark-report-[timestamp].json
+npm test
 ```
 
-Open the generated HTML file in a browser to see:
+Currently passing: **105 tests**
+
+## Project Structure
 
-- Average response times for each operation type
-- Throughput metrics at different concurrency levels
-- Visual charts for easy performance analysis
+```
+src/
+├── index.js              # Entry point
+├── server.js             # Fastify setup
+├── handlers/
+│   ├── resource.js       # GET, PUT, DELETE, HEAD, PATCH
+│   └── container.js      # POST, pod creation
+├── storage/
+│   └── filesystem.js     # File operations
+├── auth/
+│   ├── middleware.js     # Auth hook
+│   ├── token.js          # Simple token auth
+│   └── solid-oidc.js     # DPoP verification
+├── wac/
+│   ├── parser.js         # ACL parsing
+│   └── checker.js        # Permission checking
+├── ldp/
+│   ├── headers.js        # LDP Link headers
+│   └── container.js      # Container JSON-LD
+├── webid/
+│   └── profile.js        # WebID generation
+├── patch/
+│   └── n3-patch.js       # N3 Patch support
+├── rdf/
+│   ├── turtle.js         # Turtle <-> JSON-LD
+│   └── conneg.js         # Content negotiation
+└── utils/
+    └── url.js            # URL utilities
+```
 
-### Customizing Benchmarks
+## Dependencies
 
-You can customize the benchmark parameters in `benchmark.js`:
+Minimal dependencies for a fast, secure server:
 
-- Concurrent users levels
-- Operations per user
-- Test duration
-- Test user credentials
+- **fastify** - High-performance HTTP server
+- **fs-extra** - Enhanced file operations
+- **jose** - JWT/JWK handling for Solid-OIDC
+- **n3** - Turtle parsing (only used when conneg enabled)
 
-## Contributing
+## License
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "javascript-solid-server",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "A minimal, fast Solid server",
   "main": "src/index.js",
   "type": "module",
@@ -10,9 +10,11 @@
     "test": "node --test --test-concurrency=1"
   },
   "dependencies": {
+    "@fastify/websocket": "^8.3.1",
     "fastify": "^4.25.2",
     "fs-extra": "^11.2.0",
-    "jose": "^6.1.3"
+    "jose": "^6.1.3",
+    "n3": "^1.26.0"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/handlers/container.js

@@ -4,6 +4,8 @@ import { isContainer } from '../utils/url.js';
 import { generateProfile, generatePreferences, generateTypeIndex, serialize } from '../webid/profile.js';
 import { generateOwnerAcl, generatePrivateAcl, generateInboxAcl, 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';
 
 /**
  * Handle POST request to container (create new resource)
@@ -16,6 +18,19 @@ export async function handlePost(request, reply) {
     return reply.code(405).send({ error: 'POST only allowed on containers' });
   }
 
+  const connegEnabled = request.connegEnabled || false;
+  const contentType = request.headers['content-type'] || '';
+
+  // Check if we can accept this input type
+  if (!canAcceptInput(contentType, connegEnabled)) {
+    return reply.code(415).send({
+      error: 'Unsupported Media Type',
+      message: connegEnabled
+        ? 'Supported types: application/ld+json, text/turtle, text/n3'
+        : 'Supported type: application/ld+json (enable conneg for Turtle support)'
+    });
+  }
+
   // Check container exists
   const stats = await storage.stat(urlPath);
   if (!stats || !stats.isDirectory) {
@@ -33,6 +48,7 @@ export async function handlePost(request, reply) {
   // Generate unique filename
   const filename = await storage.generateUniqueFilename(urlPath, slug, isCreatingContainer);
   const newPath = urlPath + filename + (isCreatingContainer ? '/' : '');
+  const resourceUrl = `${request.protocol}://${request.hostname}${newPath}`;
 
   let success;
   if (isCreatingContainer) {
@@ -49,6 +65,21 @@ export async function handlePost(request, reply) {
     } else {
       content = Buffer.from('');
     }
+
+    // Convert Turtle/N3 to JSON-LD if conneg enabled
+    const inputType = contentType.split(';')[0].trim().toLowerCase();
+    if (connegEnabled && (inputType === RDF_TYPES.TURTLE || inputType === RDF_TYPES.N3)) {
+      try {
+        const jsonLd = await toJsonLd(content, contentType, resourceUrl, connegEnabled);
+        content = Buffer.from(JSON.stringify(jsonLd, null, 2));
+      } catch (e) {
+        return reply.code(400).send({
+          error: 'Bad Request',
+          message: 'Invalid Turtle/N3 format: ' + e.message
+        });
+      }
+    }
+
     success = await storage.write(newPath, content);
   }
 
@@ -56,16 +87,23 @@ export async function handlePost(request, reply) {
     return reply.code(500).send({ error: 'Create failed' });
   }
 
-  const location = `${request.protocol}://${request.hostname}${newPath}`;
   const origin = request.headers.origin;
 
   const headers = getAllHeaders({
     isContainer: isCreatingContainer,
-    origin
+    origin,
+    connegEnabled
   });
-  headers['Location'] = location;
+  headers['Location'] = resourceUrl;
+  headers['Vary'] = getVaryHeader(connegEnabled);
 
   Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+
+  // Emit change notification for WebSocket subscribers
+  if (request.notificationsEnabled) {
+    emitChange(resourceUrl);
+  }
+
   return reply.code(201).send();
 }
 

package/src/handlers/resource.js

@@ -3,6 +3,15 @@ import { getAllHeaders } from '../ldp/headers.js';
 import { generateContainerJsonLd, serializeJsonLd } from '../ldp/container.js';
 import { isContainer, getContentType, isRdfContentType } from '../utils/url.js';
 import { parseN3Patch, applyN3Patch, validatePatch } from '../patch/n3-patch.js';
+import {
+  selectContentType,
+  canAcceptInput,
+  toJsonLd,
+  fromJsonLd,
+  getVaryHeader,
+  RDF_TYPES
+} from '../rdf/conneg.js';
+import { emitChange } from '../notifications/events.js';
 
 /**
  * Handle GET request
@@ -20,6 +29,8 @@ export async function handleGet(request, reply) {
 
   // 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 indexExists = await storage.exists(indexPath);
@@ -34,7 +45,8 @@ export async function handleGet(request, reply) {
         etag: indexStats?.etag || stats.etag,
         contentType: 'text/html',
         origin,
-        resourceUrl
+        resourceUrl,
+        connegEnabled
       });
 
       Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
@@ -50,7 +62,8 @@ export async function handleGet(request, reply) {
       etag: stats.etag,
       contentType: 'application/ld+json',
       origin,
-      resourceUrl
+      resourceUrl,
+      connegEnabled
     });
 
     Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
@@ -63,14 +76,54 @@ export async function handleGet(request, reply) {
     return reply.code(500).send({ error: 'Read error' });
   }
 
-  const contentType = getContentType(urlPath);
+  const storedContentType = getContentType(urlPath);
+  const connegEnabled = request.connegEnabled || false;
+
+  // Content negotiation for RDF resources
+  if (connegEnabled && isRdfContentType(storedContentType)) {
+    try {
+      // Parse stored content as JSON-LD
+      const jsonLd = JSON.parse(content.toString());
+
+      // Select output format based on Accept header
+      const acceptHeader = request.headers.accept;
+      const targetType = selectContentType(acceptHeader, connegEnabled);
+
+      // Convert to requested format
+      const { content: outputContent, contentType: outputType } = await fromJsonLd(
+        jsonLd,
+        targetType,
+        resourceUrl,
+        connegEnabled
+      );
+
+      const headers = getAllHeaders({
+        isContainer: false,
+        etag: stats.etag,
+        contentType: outputType,
+        origin,
+        resourceUrl,
+        connegEnabled
+      });
+      headers['Vary'] = getVaryHeader(connegEnabled);
+
+      Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+      return reply.send(outputContent);
+    } catch (e) {
+      // If not valid JSON-LD, serve as-is
+    }
+  }
+
+  // Serve content as-is (no conneg or non-RDF resource)
   const headers = getAllHeaders({
     isContainer: false,
     etag: stats.etag,
-    contentType,
+    contentType: storedContentType,
     origin,
-    resourceUrl
+    resourceUrl,
+    connegEnabled
   });
+  headers['Vary'] = getVaryHeader(connegEnabled);
 
   Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
   return reply.send(content);
@@ -118,6 +171,20 @@ export async function handlePut(request, reply) {
     return reply.code(409).send({ error: 'Cannot PUT to container. Use POST instead.' });
   }
 
+  const connegEnabled = request.connegEnabled || false;
+  const contentType = request.headers['content-type'] || '';
+  const resourceUrl = `${request.protocol}://${request.hostname}${urlPath}`;
+
+  // Check if we can accept this input type
+  if (!canAcceptInput(contentType, connegEnabled)) {
+    return reply.code(415).send({
+      error: 'Unsupported Media Type',
+      message: connegEnabled
+        ? 'Supported types: application/ld+json, text/turtle, text/n3'
+        : 'Supported type: application/ld+json (enable conneg for Turtle support)'
+    });
+  }
+
   // Check if resource already exists
   const existed = await storage.exists(urlPath);
 
@@ -135,17 +202,37 @@ export async function handlePut(request, reply) {
     content = Buffer.from('');
   }
 
+  // Convert Turtle/N3 to JSON-LD if conneg enabled
+  const inputType = contentType.split(';')[0].trim().toLowerCase();
+  if (connegEnabled && (inputType === RDF_TYPES.TURTLE || inputType === RDF_TYPES.N3)) {
+    try {
+      const jsonLd = await toJsonLd(content, contentType, resourceUrl, connegEnabled);
+      content = Buffer.from(JSON.stringify(jsonLd, null, 2));
+    } catch (e) {
+      return reply.code(400).send({
+        error: 'Bad Request',
+        message: 'Invalid Turtle/N3 format: ' + e.message
+      });
+    }
+  }
+
   const success = await storage.write(urlPath, content);
   if (!success) {
     return reply.code(500).send({ error: 'Write failed' });
   }
 
   const origin = request.headers.origin;
-  const resourceUrl = `${request.protocol}://${request.hostname}${urlPath}`;
-  const headers = getAllHeaders({ isContainer: false, origin, resourceUrl });
+  const headers = getAllHeaders({ isContainer: false, origin, resourceUrl, connegEnabled });
   headers['Location'] = resourceUrl;
+  headers['Vary'] = getVaryHeader(connegEnabled);
 
   Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+
+  // Emit change notification for WebSocket subscribers
+  if (request.notificationsEnabled) {
+    emitChange(resourceUrl);
+  }
+
   return reply.code(existed ? 204 : 201).send();
 }
 
@@ -170,6 +257,11 @@ export async function handleDelete(request, reply) {
   const headers = getAllHeaders({ isContainer: false, origin, resourceUrl });
   Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
 
+  // Emit change notification for WebSocket subscribers
+  if (request.notificationsEnabled) {
+    emitChange(resourceUrl);
+  }
+
   return reply.code(204).send();
 }
 
@@ -285,5 +377,10 @@ export async function handlePatch(request, reply) {
   const headers = getAllHeaders({ isContainer: false, origin, resourceUrl });
   Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
 
+  // Emit change notification for WebSocket subscribers
+  if (request.notificationsEnabled) {
+    emitChange(resourceUrl);
+  }
+
   return reply.code(204).send();
 }