javascript-solid-server 0.0.110 → 0.0.111

package/docs/activitypub.md

@@ -0,0 +1,109 @@
+## ActivityPub Federation
+
+Enable ActivityPub to federate with Mastodon, Pleroma, Misskey, and other Fediverse servers:
+
+```bash
+jss start --activitypub --ap-username alice --ap-display-name "Alice" --ap-summary "Hello from JSS!"
+```
+
+### Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `/.well-known/webfinger` | Actor discovery (Mastodon searches here) |
+| `/.well-known/nodeinfo` | NodeInfo discovery |
+| `/profile/card` | Actor (returns JSON-LD when `Accept: application/activity+json`) |
+| `/inbox` | Shared inbox for receiving activities |
+| `/profile/card/inbox` | Personal inbox |
+| `/profile/card/outbox` | User's activities |
+| `/profile/card/followers` | Followers collection |
+| `/profile/card/following` | Following collection |
+
+### How It Works
+
+1. **Discovery**: Mastodon looks up `@alice@your.server` via WebFinger
+2. **Actor**: Returns ActivityPub Actor JSON-LD with public key
+3. **Follow**: Remote servers POST Follow activities to inbox
+4. **Accept**: JSS auto-accepts follows and sends Accept back
+5. **Delivery**: Posts are signed with HTTP Signatures and delivered to follower inboxes
+
+### Identity Linking
+
+Your WebID (`/profile/card#me`) becomes your ActivityPub Actor. Link to Nostr identity:
+
+```bash
+jss start --activitypub --ap-nostr-pubkey <64-char-hex-pubkey>
+```
+
+This adds `alsoKnownAs: ["did:nostr:<pubkey>"]` to your Actor profile, creating a verifiable link between your Solid, ActivityPub, and Nostr identities (the SAND stack).
+
+### Programmatic Usage
+
+```javascript
+import { createServer } from 'javascript-solid-server';
+
+const server = createServer({
+  activitypub: true,
+  apUsername: 'alice',
+  apDisplayName: 'Alice',
+  apSummary: 'Building the decentralized web!',
+  apNostrPubkey: 'abc123...'  // Optional: links to did:nostr
+});
+```
+
+### Testing Federation
+
+```bash
+# Check WebFinger
+curl "http://localhost:3000/.well-known/webfinger?resource=acct:alice@localhost:3000"
+
+# Get Actor (AP format)
+curl -H "Accept: application/activity+json" http://localhost:3000/profile/card
+
+# Check NodeInfo
+curl http://localhost:3000/.well-known/nodeinfo/2.1
+```
+
+## Mastodon-compatible API
+
+JSS exposes Mastodon API endpoints so that Mastodon clients (Elk, Phanpy, Ice Cubes) can connect:
+
+```bash
+jss start --activitypub --idp
+```
+
+### Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `POST /api/v1/apps` | Dynamic client registration |
+| `GET /api/v1/accounts/verify_credentials` | Current user profile |
+| `GET /api/v1/instance` | Instance metadata |
+| `GET /oauth/authorize` | OAuth authorize page |
+| `POST /oauth/authorize` | Process login |
+| `POST /oauth/token` | Exchange code for Bearer token |
+
+### OAuth 2.0 Flow
+
+The OAuth layer is shared between Mastodon clients, remoteStorage apps, and third-party Solid panes:
+
+1. Client registers via `POST /api/v1/apps` (gets `client_id` + `client_secret`)
+2. Client redirects user to `GET /oauth/authorize?client_id=...&redirect_uri=...&response_type=code`
+3. User logs in, JSS redirects back with `?code=...`
+4. Client exchanges code for Bearer token via `POST /oauth/token`
+5. Bearer token works with all JSS endpoints (Solid, ActivityPub, remoteStorage)
+
+Supports out-of-band (OOB) redirect for CLI/desktop clients.
+
+### Testing
+
+```bash
+# Register a client
+curl -X POST http://localhost:3000/api/v1/apps \
+  -H "Content-Type: application/json" \
+  -d '{"client_name": "Test App", "redirect_uris": "urn:ietf:wg:oauth:2.0:oob"}'
+
+# Check instance info
+curl http://localhost:3000/api/v1/instance
+```
+

package/docs/architecture.md

@@ -0,0 +1,165 @@
+## Pod Structure
+
+```
+/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
+```
+
+## Project Structure
+
+```
+src/
+├── index.js              # Entry point
+├── server.js             # Fastify setup
+├── handlers/
+│   ├── resource.js       # GET, PUT, DELETE, HEAD, PATCH
+│   ├── container.js      # POST, pod creation
+│   ├── git.js            # Git HTTP backend
+│   └── pay.js            # HTTP 402 paid access
+├── storage/
+│   ├── filesystem.js     # File operations
+│   └── quota.js          # Storage quota management
+├── auth/
+│   ├── middleware.js      # Auth hook
+│   ├── token.js           # Simple token auth
+│   ├── solid-oidc.js      # DPoP verification
+│   ├── nostr.js           # NIP-98 Nostr authentication
+│   ├── did-nostr.js       # did:nostr → WebID resolution
+│   └── webid-tls.js       # WebID-TLS client certificate auth
+├── 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
+│   └── sparql-update.js  # SPARQL Update support
+├── notifications/
+│   ├── index.js          # WebSocket plugin
+│   ├── events.js         # Event emitter
+│   └── websocket.js      # solid-0.1 protocol
+├── idp/
+│   ├── index.js           # Identity Provider plugin
+│   ├── provider.js        # oidc-provider config
+│   ├── adapter.js         # Filesystem adapter
+│   ├── accounts.js        # User account management
+│   ├── credentials.js     # Credentials endpoint
+│   ├── keys.js            # JWKS key management
+│   ├── interactions.js    # Login/consent handlers
+│   ├── passkey.js         # WebAuthn/FIDO2 passkey support
+│   ├── views.js           # HTML templates
+│   └── invites.js         # Invite code management
+├── ap/
+│   ├── index.js          # ActivityPub plugin
+│   ├── keys.js           # RSA keypair management
+│   ├── store.js          # SQLite storage (followers, activities)
+│   └── routes/
+│       ├── actor.js      # Actor JSON-LD
+│       ├── inbox.js      # Receive activities
+│       ├── outbox.js     # User's activities
+│       ├── collections.js # Followers/following
+│       ├── mastodon.js  # Mastodon API (apps, instance, verify_credentials)
+│       └── oauth.js     # OAuth 2.0 authorize/token flow
+├── webledger.js          # Web Ledger balance tracking (webledgers.org)
+├── mrc20.js              # State chain verification
+├── remotestorage.js      # remoteStorage protocol (draft-dejong-remotestorage-22)
+├── rdf/
+│   ├── turtle.js         # Turtle <-> JSON-LD
+│   └── conneg.js         # Content negotiation
+├── mashlib/
+│   └── index.js           # Mashlib data browser plugin
+└── utils/
+    ├── url.js             # URL utilities
+    ├── conditional.js     # If-Match/If-None-Match
+    └── ssrf.js            # SSRF protection
+```
+
+## Dependencies
+
+14 direct dependencies for a fast, secure server:
+
+- **fastify** - High-performance HTTP server
+- **@fastify/middie** - Express/Connect middleware bridge (for IdP)
+- **@fastify/rate-limit** - Rate limiting for API endpoints
+- **@fastify/websocket** - WebSocket support for notifications
+- **@simplewebauthn/server** - Passkey/WebAuthn authentication
+- **bcryptjs** - Password hashing (pure JS, works on Termux/Android)
+- **commander** - CLI command parsing
+- **fs-extra** - Enhanced file operations
+- **jose** - JWT/JWK handling for Solid-OIDC
+- **microfed** - ActivityPub primitives (only when activitypub enabled)
+- **n3** - Turtle parsing (only used when conneg enabled)
+- **nostr-tools** - Nostr protocol and Schnorr signature verification
+- **oidc-provider** - OpenID Connect Identity Provider (only when IdP enabled)
+- **sql.js** - SQLite storage for federation data (WASM, cross-platform)
+
+## Performance
+
+This server is designed for speed. Benchmark results on a typical development machine:
+
+| Operation | Requests/sec | Avg Latency | p99 Latency |
+|-----------|-------------|-------------|-------------|
+| GET resource | 5,400+ | 1.2ms | 3ms |
+| GET container | 4,700+ | 1.6ms | 3ms |
+| PUT (write) | 5,700+ | 1.1ms | 2ms |
+| POST (create) | 5,200+ | 1.3ms | 3ms |
+| OPTIONS | 10,000+ | 0.4ms | 1ms |
+
+Run benchmarks yourself:
+```bash
+npm run benchmark
+```
+
+## Running Tests
+
+```bash
+npm test
+```
+
+Currently passing: **289 tests** (including 27 conformance tests)
+
+### Conformance Test Harness (CTH)
+
+This server passes the Solid Conformance Test Harness authentication tests:
+
+```bash
+# Start server with IdP and content negotiation
+JSS_PORT=4000 JSS_CONNEG=true JSS_IDP=true jss start
+
+# Create test users
+curl -X POST http://localhost:4000/.pods \
+  -H "Content-Type: application/json" \
+  -d '{"name": "alice", "email": "alice@example.com", "password": "alicepassword123"}'
+
+curl -X POST http://localhost:4000/.pods \
+  -H "Content-Type: application/json" \
+  -d '{"name": "bob", "email": "bob@example.com", "password": "bobpassword123"}'
+
+# Run CTH authentication tests
+docker run --rm --network=host \
+  -e SOLID_IDENTITY_PROVIDER="http://localhost:4000/" \
+  -e USERS_ALICE_WEBID="http://localhost:4000/alice/#me" \
+  -e USERS_ALICE_PASSWORD="alicepassword123" \
+  -e USERS_BOB_WEBID="http://localhost:4000/bob/#me" \
+  -e USERS_BOB_PASSWORD="bobpassword123" \
+  solidproject/conformance-test-harness:latest \
+  --filter="authentication"
+```
+
+**CTH Status (v0.0.15):**
+- Authentication tests: 6/6 passing
+

package/docs/authentication.md

@@ -0,0 +1,157 @@
+# Authentication
+
+### Simple Tokens (Development)
+
+Use the token returned from pod creation:
+
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:3000/alice/private/
+```
+
+### Built-in Identity Provider (v0.0.12+)
+
+Enable the built-in Solid-OIDC Identity Provider:
+
+```bash
+jss start --idp
+```
+
+With IdP enabled, pod creation requires email and password:
+
+```bash
+curl -X POST http://localhost:3000/.pods \
+  -H "Content-Type: application/json" \
+  -d '{"name": "alice", "email": "alice@example.com", "password": "secret123"}'
+```
+
+Response:
+```json
+{
+  "name": "alice",
+  "webId": "http://localhost:3000/alice/#me",
+  "podUri": "http://localhost:3000/alice/",
+  "idpIssuer": "http://localhost:3000",
+  "loginUrl": "http://localhost:3000/idp/auth"
+}
+```
+
+OIDC Discovery: `/.well-known/openid-configuration`
+
+### Programmatic Login (CTH Compatible)
+
+For automated testing and scripts, use the credentials endpoint:
+
+```bash
+curl -X POST http://localhost:3000/idp/credentials \
+  -H "Content-Type: application/json" \
+  -d '{"email": "alice@example.com", "password": "secret123"}'
+```
+
+Response:
+```json
+{
+  "access_token": "...",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "webid": "http://localhost:3000/alice/#me"
+}
+```
+
+For DPoP-bound tokens (Solid-OIDC compliant), include a DPoP proof header.
+
+### Passkey Authentication (v0.0.77+)
+
+Enable passwordless login with WebAuthn/FIDO2:
+
+```bash
+jss start --idp
+```
+
+**How it works:**
+1. User logs in with username/password
+2. Prompted to add a passkey (Touch ID, Face ID, security key)
+3. Future logins: tap "Sign in with Passkey" → biometric → done!
+
+**Benefits:**
+- Phishing-resistant (bound to domain)
+- No passwords to remember or leak
+- Works on mobile and desktop
+
+Passkeys are stored per-account and work across devices via platform sync (iCloud Keychain, Google Password Manager, etc.).
+
+### Schnorr SSO (v0.0.79+)
+
+Sign in with your Nostr key using NIP-07 browser extensions:
+
+```bash
+jss start --idp
+```
+
+**How it works:**
+1. User clicks "Sign in with Schnorr" on the login page
+2. NIP-07 extension (Podkey, nos2x, Alby) signs a NIP-98 auth event
+3. Server verifies BIP-340 Schnorr signature
+4. User authenticated via linked did:nostr identity
+
+**Requirements:**
+- Account must have a `did:nostr:<pubkey>` WebID linked
+- User needs a NIP-07 compatible browser extension
+
+**Benefits:**
+- No passwords - cryptographic authentication
+- Works with existing Nostr identity
+- Single sign-on across Solid and Nostr ecosystems
+
+### Solid-OIDC (External IdP)
+
+The server also 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/
+```
+
+### WebID-TLS (Client Certificates)
+
+For backend services, CLI tools, and automated agents that need non-interactive authentication:
+
+```bash
+jss start --ssl-key key.pem --ssl-cert cert.pem --webid-tls
+```
+
+**How it works:**
+1. Client presents X.509 certificate during TLS handshake
+2. Certificate's `SubjectAlternativeName` contains a WebID URI
+3. Server fetches the WebID profile
+4. Server verifies the certificate's public key matches one in the profile
+
+**Testing with curl:**
+
+```bash
+# Generate self-signed cert with WebID in SAN
+openssl req -x509 -newkey rsa:2048 -keyout client-key.pem -out client-cert.pem -days 365 \
+  -subj "/CN=Test" -addext "subjectAltName=URI:https://example.com/alice/#me" -nodes
+
+# Make authenticated request
+curl --cert client-cert.pem --key client-key.pem https://localhost:8443/alice/private/
+```
+
+**Profile requirement:** Your WebID profile must contain the certificate's public key:
+
+```turtle
+@prefix cert: <http://www.w3.org/ns/auth/cert#> .
+
+<#me> cert:key [
+    a cert:RSAPublicKey;
+    cert:modulus "abc123..."^^xsd:hexBinary;
+    cert:exponent 65537
+] .
+```
+
+**Use cases:**
+- Enterprise backend services with existing PKI
+- Server-to-server communication
+- CLI tools and scripts
+- IoT devices with embedded certificates
+