javascript-solid-server 0.0.35 → 0.0.37

package/.claude/settings.local.json

@@ -97,7 +97,26 @@
       "Bash(done)",
       "Bash(for domain in jss.dev jss.sh jss.io jss.app solidserver.dev)",
       "Bash(host:*)",
-      "WebFetch(domain:nostr-components.github.io)"
+      "WebFetch(domain:nostr-components.github.io)",
+      "Bash(ssh melvincarvalho.com \"pm2 list && echo ''---HAPROXY---'' && cat /etc/haproxy/haproxy.cfg 2>/dev/null | grep -A5 ''melvin\\|backend\\|frontend\\|acl host''\")",
+      "Bash(ssh:*)",
+      "Bash(time curl -s --connect-timeout 10 https://melvin.solid.live/credit/count.ttl)",
+      "Bash(time curl -s --connect-timeout 10 https://melvin.solid.live/)",
+      "Bash(time curl:*)",
+      "Bash(time curl -s 'https://melvin.solid.live/credit/count.ttl')",
+      "Bash(grep:*)",
+      "Bash(scp:*)",
+      "Bash(for i in 1 2 3)",
+      "Bash(do echo \"Attempt $i:\")",
+      "Bash(for i in 1 2 3 4 5)",
+      "Bash(do curl -so /dev/null -w \"%{http_code} \" https://melvincarvalho.com/js/handlemutation.js)",
+      "Bash(for i in 1 2 3 4 5 6 7 8 9 10)",
+      "Bash(if [ ! -d \"jose\" ])",
+      "Bash(then git clone --depth 1 --branch v0.7.0 https://github.com/solid/jose.git)",
+      "Bash(fi)",
+      "Bash(timeout 45 node:*)",
+      "Bash(gh issue list:*)",
+      "Bash(DATA_ROOT=/tmp/jss-git-test JSS_PORT=4444 timeout 3 node:*)"
     ]
   }
 }

package/AGENTS.md

@@ -0,0 +1,152 @@
+# AGENTS.md - AI Assistant Context for JSS
+
+This document provides context for AI assistants working on JavaScript Solid Server (JSS).
+
+## What is JSS?
+
+A lightweight Solid server implementation focused on simplicity and modern JavaScript. Alternative to Node Solid Server (NSS) and Community Solid Server (CSS).
+
+**Key differences from other Solid servers:**
+- Single-file JSON-LD storage (no quad stores)
+- Content negotiation converts JSON-LD ↔ Turtle on the fly
+- Built on Fastify (not Express)
+- Uses oidc-provider for identity
+- Supports Nostr NIP-98 authentication (unique to JSS)
+
+## Architecture
+
+```
+src/
+├── server.js          # Fastify setup, route registration
+├── handlers/          # LDP operations (GET, PUT, POST, PATCH, DELETE)
+│   ├── resource.js    # File operations
+│   └── container.js   # Directory operations, pod creation
+├── auth/              # Authentication
+│   ├── middleware.js  # WAC authorization hook
+│   ├── solid-oidc.js  # DPoP token verification
+│   ├── nostr.js       # NIP-98 Schnorr signatures
+│   └── token.js       # Simple Bearer tokens
+├── idp/               # Identity Provider (oidc-provider)
+│   ├── provider.js    # OIDC configuration
+│   ├── interactions.js # Login/consent UI handlers
+│   └── accounts.js    # User account storage
+├── wac/               # Web Access Control
+│   ├── checker.js     # Permission checking
+│   └── parser.js      # ACL file parsing/generation
+├── rdf/               # RDF handling
+│   ├── conneg.js      # Content negotiation
+│   └── turtle.js      # Turtle ↔ JSON-LD conversion
+├── notifications/     # WebSocket real-time updates
+│   ├── websocket.js   # solid-0.1 protocol handler
+│   └── events.js      # Event emitter for changes
+├── ldp/               # Linked Data Platform
+│   ├── headers.js     # LDP response headers
+│   └── container.js   # Container JSON-LD generation
+└── storage/           # File system operations
+    └── filesystem.js  # Read/write/stat/list
+```
+
+## Key Design Decisions
+
+### JSON-LD as canonical storage
+All RDF is stored as JSON-LD. When clients request Turtle, we convert on the fly. This simplifies storage and allows non-RDF tools to read the data.
+
+### HTML profiles with JSON-LD data islands
+WebID profiles are HTML documents with embedded `<script type="application/ld+json">`. This allows:
+- Human-readable profiles in browsers
+- Machine-readable RDF via content negotiation
+- Mashlib renders the profile using the embedded data
+
+### Subdomain mode for XSS isolation
+When `subdomains: true`, each pod gets its own subdomain (alice.example.com). This provides browser security isolation. Storage path includes pod name, but URLs use subdomains.
+
+### Settings folder conventions
+Mashlib expects `Settings/` (capital S) with:
+- `Settings/Preferences.ttl`
+- `Settings/publicTypeIndex.ttl`
+- `Settings/privateTypeIndex.ttl`
+
+Earlier versions used lowercase `settings/prefs` which broke mashlib.
+
+## Common Gotchas
+
+### Content negotiation
+- Files stored as JSON-LD regardless of upload format
+- `.ttl` extension triggers Turtle response regardless of Accept header
+- Container listings need conneg too (fixed in v0.0.33)
+
+### Authentication paths that skip auth
+These paths bypass the auth middleware:
+- `/.pods` - Pod creation
+- `/.notifications` - WebSocket endpoint
+- `/idp/*` - Identity provider routes
+- `/.well-known/*` - Discovery endpoints
+- OPTIONS requests
+
+### WebSocket notifications
+Uses legacy `solid-0.1` protocol (not Solid Notifications Protocol):
+```
+Server: protocol solid-0.1
+Client: sub https://example.org/resource
+Server: ack https://example.org/resource
+Server: pub https://example.org/resource  (on change)
+```
+Discovered via `Updates-Via` header.
+
+### DPoP token verification
+Solid-OIDC uses DPoP-bound tokens. The DPoP proof must match:
+- HTTP method (htm)
+- Request URL (htu)
+- Be recent (iat within 5 minutes)
+- Key thumbprint matches token binding (cnf.jkt)
+
+### ACL inheritance
+WAC ACLs use `acl:default` for inheritance. When checking permissions:
+1. Look for resource-specific ACL (resource.acl or .acl for containers)
+2. Walk up to parent containers checking for `acl:default` rules
+3. Stop at pod root
+
+## Testing
+
+```bash
+npm test                    # Run all tests
+npm run test:cth           # Conformance Test Harness (requires setup)
+```
+
+Tests use in-memory server instances. See `test/helpers.js` for test utilities.
+
+## Deployment
+
+### Production setup
+```bash
+npm install -g javascript-solid-server
+jss --port 443 --ssl-key key.pem --ssl-cert cert.pem --idp --multiuser
+```
+
+### With HAProxy (recommended)
+HAProxy handles SSL termination, JSS runs on localhost:8443. Wildcard cert needed for subdomain mode.
+
+### PM2 process management
+```bash
+pm2 start "jss --config config.json" --name solid
+pm2 logs solid
+pm2 restart solid
+```
+
+## External Dependencies
+
+- **oidc-provider**: OpenID Connect implementation (complex, many warnings are normal)
+- **n3**: Turtle/N3 parsing and serialization
+- **jose**: JWT/JWK handling for Solid-OIDC
+- **@fastify/websocket**: WebSocket support
+
+## Related Specs
+
+- [Solid Protocol](https://solidproject.org/TR/protocol)
+- [Solid-OIDC](https://solidproject.org/TR/oidc)
+- [Web Access Control](https://solidproject.org/TR/wac)
+- [Linked Data Platform](https://www.w3.org/TR/ldp/)
+
+## Contact
+
+Issues: https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues

package/bin/jss.js

@@ -54,6 +54,8 @@ 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('--git', 'Enable Git HTTP backend (clone/push support)')
+  .option('--no-git', 'Disable Git HTTP backend')
   .option('-q, --quiet', 'Suppress log output')
   .option('--print-config', 'Print configuration and exit')
   .action(async (options) => {
@@ -95,6 +97,7 @@ program
         mashlib: config.mashlib || config.mashlibCdn,
         mashlibCdn: config.mashlibCdn,
         mashlibVersion: config.mashlibVersion,
+        git: config.git,
       });
 
       await server.listen({ port: config.port, host: config.host });
@@ -113,6 +116,7 @@ program
         } else if (config.mashlib) {
           console.log(`  Mashlib: local (data browser enabled)`);
         }
+        if (config.git) console.log('  Git: enabled (clone/push support)');
         console.log('\n  Press Ctrl+C to stop\n');
       }
 

package/docs/design/nostr-relay-integration.md

@@ -0,0 +1,353 @@
+# Design: JSS as Nostr Relay++
+
+## Overview
+
+Replace the Solid Notifications Protocol with Nostr relay functionality. JSS becomes a Nostr relay that also serves LDP resources, unifying identity, storage, and real-time notifications.
+
+## Motivation
+
+**Solid Notifications Protocol problems:**
+- Complex discovery mechanism
+- JSON-LD channel descriptions
+- No federation
+- No existing ecosystem
+- Reinvents pub/sub poorly
+
+**Nostr advantages:**
+- Simple WebSocket protocol (NIP-01)
+- Cryptographic identity built-in
+- Federation via relay gossip
+- Millions of existing users
+- Mobile push infrastructure exists
+- Battle-tested
+
+**JSS already has:**
+- NIP-98 HTTP authentication
+- WebSocket infrastructure (solid-0.1)
+- JSON-LD storage
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         JSS Server                          │
+├──────────────────────┬──────────────────────────────────────┤
+│     LDP Layer        │         Nostr Relay Layer            │
+│                      │                                      │
+│  GET/PUT/POST/PATCH  │    EVENT/REQ/CLOSE/EOSE              │
+│  DELETE/OPTIONS      │                                      │
+│                      │                                      │
+│  ┌────────────────┐  │  ┌─────────────────────────────────┐ │
+│  │  Resources     │◄─┼─►│  Events (kind:30078)            │ │
+│  │  /alice/doc.ttl│  │  │  Addressable by d-tag = URI     │ │
+│  └────────────────┘  │  └─────────────────────────────────┘ │
+│                      │                                      │
+│  Auth: Solid-OIDC    │    Auth: NIP-98 / NIP-42             │
+│        NIP-98        │                                      │
+└──────────────────────┴──────────────────────────────────────┘
+                              │
+                              ▼
+                    ┌─────────────────┐
+                    │  Other Relays   │
+                    │  (Federation)   │
+                    └─────────────────┘
+```
+
+## Protocol Mapping
+
+### Resource ↔ Event Mapping
+
+LDP resources map to Nostr replaceable events:
+
+```
+Resource URL: https://alice.solid.social/notes/idea.json
+     ↓
+Nostr Event:
+{
+  "kind": 30078,                    // Arbitrary JSON (NIP-78)
+  "pubkey": "<alice-pubkey>",
+  "created_at": 1703888888,
+  "tags": [
+    ["d", "https://alice.solid.social/notes/idea.json"],
+    ["solid:type", "ldp:Resource"],
+    ["solid:contentType", "application/ld+json"]
+  ],
+  "content": "{\"@context\": ..., \"title\": \"My Idea\"}",
+  "sig": "<signature>"
+}
+```
+
+### Kind Assignments
+
+| Kind | Purpose | NIP |
+|------|---------|-----|
+| 30078 | LDP Resource (JSON content) | NIP-78 |
+| 30079 | LDP Container listing | Custom |
+| 30080 | ACL document | Custom |
+| 10078 | Resource deletion marker | Custom |
+| 1 | Social posts (optional integration) | NIP-01 |
+
+Using 30xxx range for addressable replaceable events (d-tag = resource URI).
+
+### Subscription Filters
+
+Subscribe to resource changes:
+
+```json
+// Subscribe to single resource
+["REQ", "sub1", {
+  "kinds": [30078],
+  "#d": ["https://alice.solid.social/notes/idea.json"]
+}]
+
+// Subscribe to container (all resources under path)
+["REQ", "sub2", {
+  "kinds": [30078, 30079],
+  "#d": ["https://alice.solid.social/notes/"]
+}]
+
+// Subscribe to all changes by user
+["REQ", "sub3", {
+  "kinds": [30078],
+  "authors": ["<alice-pubkey>"]
+}]
+```
+
+## Implementation
+
+### Phase 1: Basic Relay
+
+Add NIP-01 relay functionality to existing WebSocket endpoint:
+
+```javascript
+// src/notifications/nostr-relay.js
+
+export function handleNostrMessage(socket, message) {
+  const [type, ...params] = JSON.parse(message);
+
+  switch (type) {
+    case 'EVENT':
+      return handleEvent(socket, params[0]);
+    case 'REQ':
+      return handleSubscription(socket, params[0], params.slice(1));
+    case 'CLOSE':
+      return handleClose(socket, params[0]);
+  }
+}
+```
+
+### Phase 2: LDP-Event Bridge
+
+When LDP resources change, emit Nostr events:
+
+```javascript
+// src/handlers/resource.js (modified)
+
+export async function handlePut(request, reply) {
+  // ... existing LDP logic ...
+
+  // After successful write, emit Nostr event
+  if (request.nostrPubkey) {
+    await emitResourceEvent({
+      pubkey: request.nostrPubkey,
+      resourceUrl,
+      content,
+      contentType
+    });
+  }
+}
+```
+
+### Phase 3: Federation
+
+Connect to other relays for event propagation:
+
+```javascript
+// src/notifications/federation.js
+
+const FEDERATION_RELAYS = [
+  'wss://relay.damus.io',
+  'wss://nos.lol',
+  'wss://relay.nostr.band'
+];
+
+export async function federateEvent(event) {
+  // Only federate public resources
+  if (await isPublicResource(event.tags.find(t => t[0] === 'd')[1])) {
+    for (const relay of FEDERATION_RELAYS) {
+      publishToRelay(relay, event);
+    }
+  }
+}
+```
+
+### Phase 4: Identity Unification
+
+WebID document includes Nostr pubkey:
+
+```json
+{
+  "@context": {...},
+  "@id": "https://alice.solid.social/profile/card#me",
+  "foaf:name": "Alice",
+  "nostr:pubkey": "npub1abc...",
+  "nostr:relays": ["wss://alice.solid.social"]
+}
+```
+
+Nostr profile (kind:0) links to WebID:
+
+```json
+{
+  "kind": 0,
+  "content": "{\"name\":\"Alice\",\"webid\":\"https://alice.solid.social/profile/card#me\"}"
+}
+```
+
+## WebSocket Endpoint
+
+Single endpoint handles both protocols:
+
+```
+wss://alice.solid.social/.notifications
+
+Protocol detection:
+- If first message is JSON array starting with "EVENT"/"REQ" → Nostr
+- If first message is "sub <uri>" → Legacy solid-0.1
+```
+
+```javascript
+// src/notifications/websocket.js (modified)
+
+export function handleWebSocket(socket, request) {
+  socket.on('message', (message) => {
+    const msg = message.toString().trim();
+
+    // Detect protocol
+    if (msg.startsWith('[')) {
+      // Nostr protocol
+      handleNostrMessage(socket, msg);
+    } else if (msg.startsWith('sub ') || msg.startsWith('unsub ')) {
+      // Legacy solid-0.1
+      handleSolidMessage(socket, msg);
+    }
+  });
+}
+```
+
+## Access Control
+
+### Public Resources
+- Events federate to other relays
+- Anyone can subscribe
+
+### Private Resources
+- Events stay local (no federation)
+- NIP-42 AUTH required to subscribe
+- Subscription filter must match authorized pubkeys
+
+```javascript
+// NIP-42 AUTH flow
+["AUTH", "<signed-event>"]
+
+// Server validates and restricts subscriptions
+// to resources the pubkey has access to
+```
+
+### ACL Mapping
+
+```
+acl:Read   → Can subscribe to events
+acl:Write  → Can publish events (create/update)
+acl:Control → Can modify ACL events
+```
+
+## Storage
+
+Two options:
+
+### Option A: Dual Storage (Recommended for Phase 1)
+- LDP resources in filesystem (existing)
+- Nostr events in SQLite/memory (relay state)
+- Bridge syncs between them
+
+### Option B: Event-Native Storage (Future)
+- All resources stored as Nostr events
+- LDP is a view over event history
+- Full audit trail built-in
+- Replaces filesystem storage
+
+## Configuration
+
+```json
+{
+  "nostr": {
+    "enabled": true,
+    "relay": {
+      "nip01": true,
+      "nip42": true,
+      "nip78": true
+    },
+    "federation": {
+      "enabled": false,
+      "relays": [],
+      "publicOnly": true
+    },
+    "kinds": {
+      "resource": 30078,
+      "container": 30079,
+      "acl": 30080
+    }
+  }
+}
+```
+
+## Migration Path
+
+1. **Phase 1**: Add relay alongside existing WebSocket
+   - Both protocols on same endpoint
+   - No breaking changes
+
+2. **Phase 2**: LDP-Event bridge
+   - Changes emit events
+   - Subscriptions work via Nostr
+
+3. **Phase 3**: Federation (optional)
+   - Public resources propagate
+   - Discovery via relay network
+
+4. **Phase 4**: Deprecate solid-0.1
+   - Nostr becomes primary notification protocol
+   - Mashlib adapter if needed
+
+## Benefits
+
+| Feature | Solid Notifications | Nostr Relay++ |
+|---------|--------------------|--------------|
+| Protocol complexity | High | Low |
+| Existing clients | ~0 | Millions |
+| Federation | No | Yes |
+| Mobile push | Build it yourself | Existing infrastructure |
+| Identity | Separate (WebID) | Integrated (npub) |
+| Signatures | Optional | Every event |
+| Ecosystem | Academic | Active |
+
+## Open Questions
+
+1. **Kind numbers**: Apply for official NIP allocation or use 30078-30080 range?
+
+2. **Content encoding**: Store JSON-LD directly in content, or reference by hash?
+
+3. **Large resources**: Nostr events have size limits. Use NIP-94/NIP-96 for large files?
+
+4. **Container semantics**: How to represent ldp:contains in events?
+
+5. **Conflict resolution**: Last-write-wins via created_at, or something smarter?
+
+## References
+
+- [NIP-01: Basic Protocol](https://github.com/nostr-protocol/nips/blob/master/01.md)
+- [NIP-42: Authentication](https://github.com/nostr-protocol/nips/blob/master/42.md)
+- [NIP-78: Arbitrary Custom App Data](https://github.com/nostr-protocol/nips/blob/master/78.md)
+- [NIP-98: HTTP Auth](https://github.com/nostr-protocol/nips/blob/master/98.md)
+- [Solid Protocol](https://solidproject.org/TR/protocol)