javascript-solid-server 0.0.110 → 0.0.111

package/docs/configuration.md

@@ -0,0 +1,471 @@
+## Philosophy: JSON-LD First
+
+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
+
+### Why JSON-LD First?
+
+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
+
+### When to Enable Content Negotiation
+
+Enable `conneg: true` when:
+- Interoperating with Turtle-based Solid apps
+- Serving data to legacy Solid clients
+- Running conformance tests that require Turtle support
+
+```javascript
+import { createServer } from './src/server.js';
+
+// Default: JSON-LD only (fast)
+const server = createServer();
+
+// With Turtle support (for interoperability)
+const serverWithConneg = createServer({ conneg: true });
+```
+
+
+## Configuration
+
+```javascript
+createServer({
+  logger: true,        // Enable Fastify logging (default: true)
+  conneg: false,       // Enable content negotiation (default: false)
+  notifications: false, // Enable WebSocket notifications (default: false)
+  subdomains: false,   // Enable subdomain-based pods (default: false)
+  baseDomain: null,    // Base domain for subdomains (e.g., "example.com")
+  mashlib: false,      // Enable Mashlib data browser - local mode (default: false)
+  mashlibCdn: false,   // Enable Mashlib data browser - CDN mode (default: false)
+  mashlibVersion: '2.0.0', // Mashlib version for CDN mode
+});
+```
+
+### Mashlib Data Browser
+
+Enable the [SolidOS Mashlib](https://github.com/SolidOS/mashlib) data browser for RDF resources. Two modes are available:
+
+**CDN Mode** (recommended for getting started):
+```bash
+jss start --mashlib-cdn --conneg
+```
+Loads mashlib from unpkg.com CDN. Zero footprint - no local files needed.
+
+**Local Mode** (for production/offline):
+```bash
+jss start --mashlib --conneg
+```
+Serves mashlib from `src/mashlib-local/dist/`. Requires building mashlib locally:
+```bash
+cd src/mashlib-local
+npm install && npm run build
+```
+
+**ES Module Mode** (for custom or next-gen mashlib builds):
+```bash
+jss start --mashlib-module https://example.com/mashlib.js
+```
+Loads an ES module-based data browser from any URL. Uses `<script type="module">` and `<div id="mashlib">` (self-initializing). CSS is auto-derived by replacing `.js` with `.css`. Content negotiation is auto-enabled.
+
+**How it works:**
+1. Browser requests `/alice/public/data.ttl` with `Accept: text/html`
+2. Server returns Mashlib HTML wrapper
+3. Mashlib fetches the actual data via content negotiation
+4. Mashlib renders an interactive, editable view
+
+**Note:** Mashlib works best with `--conneg` enabled for Turtle support.
+
+**Modern UI (SolidOS UI):**
+```bash
+jss start --mashlib --solidos-ui --conneg
+```
+Serves a modern Nextcloud-style UI shell while reusing mashlib's data layer. The `--solidos-ui` flag swaps the classic databrowser interface for a cleaner, mobile-friendly design with:
+- Modern file browser with breadcrumb navigation
+- Profile, Contacts, Sharing, and Settings views
+- Path-based URLs (browser URL reflects current resource)
+- Responsive design for mobile devices
+
+Requires solidos-ui dist files in `src/mashlib-local/dist/solidos-ui/`. See [solidos-ui](https://github.com/solidos/solidos/tree/main/workspaces/solidos-ui) for details.
+
+### Profile Pages
+
+Pod profiles (`/alice/`) use HTML with embedded JSON-LD data islands and are rendered using:
+- [mashlib-jss](https://github.com/JavaScriptSolidServer/mashlib-jss) - A fork of mashlib with `getPod()` fix for path-based pods
+- [solidos-lite](https://github.com/SolidOS/solidos-lite) - Parses JSON-LD data islands into the RDF store
+
+This allows profiles to work without server-side content negotiation while still providing full SolidOS editing capabilities.
+
+### WebSocket Notifications
+
+Enable real-time notifications for resource changes:
+
+```javascript
+const server = createServer({ notifications: true });
+```
+
+Clients discover the WebSocket URL via the `Updates-Via` header:
+
+```bash
+curl -I http://localhost:3000/alice/public/
+# Updates-Via: ws://localhost:3000/.notifications
+```
+
+Protocol (solid-0.1, compatible with SolidOS):
+```
+Server: protocol solid-0.1
+Client: sub http://localhost:3000/alice/public/data.json
+Server: ack http://localhost:3000/alice/public/data.json
+Server: pub http://localhost:3000/alice/public/data.json  (on change)
+```
+
+
+## CLI Start Options
+
+### Start Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-p, --port <n>` | Port to listen on | 3000 |
+| `-h, --host <addr>` | Host to bind to | 0.0.0.0 |
+| `-r, --root <path>` | Data directory | ./data |
+| `-c, --config <file>` | Config file path | - |
+| `--ssl-key <path>` | SSL private key (PEM) | - |
+| `--ssl-cert <path>` | SSL certificate (PEM) | - |
+| `--conneg` | Enable Turtle support | false |
+| `--notifications` | Enable WebSocket | false |
+| `--idp` | Enable built-in IdP | false |
+| `--idp-issuer <url>` | IdP issuer URL | (auto) |
+| `--subdomains` | Enable subdomain-based pods | false |
+| `--base-domain <domain>` | Base domain for subdomains | - |
+| `--mashlib` | Enable Mashlib (local mode) | false |
+| `--mashlib-cdn` | Enable Mashlib (CDN mode) | false |
+| `--mashlib-module <url>` | Enable ES module data browser from a URL | - |
+| `--mashlib-version <ver>` | Mashlib CDN version | 2.0.0 |
+| `--solidos-ui` | Enable modern SolidOS UI (requires --mashlib) | false |
+| `--git` | Enable Git HTTP backend | false |
+| `--nostr` | Enable Nostr relay | false |
+| `--nostr-path <path>` | Nostr relay WebSocket path | /relay |
+| `--nostr-max-events <n>` | Max events in relay memory | 1000 |
+| `--invite-only` | Require invite code for registration | false |
+| `--webid-tls` | Enable WebID-TLS client certificate auth | false |
+| `--default-quota <size>` | Default storage quota per pod (e.g., 50MB) | 50MB |
+| `--activitypub` | Enable ActivityPub federation | false |
+| `--ap-username <name>` | ActivityPub username | me |
+| `--ap-display-name <name>` | ActivityPub display name | (username) |
+| `--ap-summary <text>` | ActivityPub bio/summary | - |
+| `--ap-nostr-pubkey <hex>` | Nostr pubkey for identity linking | - |
+| `--public` | Allow unauthenticated access (skip WAC) | false |
+| `--read-only` | Disable PUT/DELETE/PATCH methods | false |
+| `--live-reload` | Auto-refresh browser on file changes | false |
+| `--pay` | Enable HTTP 402 paid access for /pay/* | false |
+| `--pay-cost <n>` | Cost per request in satoshis | 1 |
+| `--pay-mempool-url <url>` | Mempool API URL for deposit verification | (testnet4) |
+| `--pay-address <addr>` | Address for receiving deposits | - |
+| `--pay-token <ticker>` | Token to sell (enables primary market + withdrawal) | - |
+| `--pay-rate <n>` | Sats per token for buy/withdraw | 1 |
+| `--pay-chains <ids>` | Multi-chain deposits + AMM (e.g. "tbtc3,tbtc4") | - |
+| `--mongo` | Enable MongoDB-backed /db/ route | false |
+| `--mongo-url <url>` | MongoDB connection URL | mongodb://localhost:27017 |
+| `--mongo-database <name>` | MongoDB database name | solid |
+| `--webrtc` | Enable WebRTC signaling server | false |
+| `--webrtc-path <path>` | WebRTC signaling WebSocket path | /.webrtc |
+| `--tunnel` | Enable tunnel proxy (decentralized ngrok) | false |
+| `--tunnel-path <path>` | Tunnel WebSocket path | /.tunnel |
+| `-q, --quiet` | Suppress logs | false |
+
+### Environment Variables
+
+All options can be set via environment variables with `JSS_` prefix:
+
+```bash
+export JSS_PORT=8443
+export JSS_SSL_KEY=/path/to/key.pem
+export JSS_SSL_CERT=/path/to/cert.pem
+export JSS_CONNEG=true
+export JSS_SUBDOMAINS=true
+export JSS_BASE_DOMAIN=example.com
+export JSS_MASHLIB=true
+export JSS_MASHLIB_MODULE=https://example.com/mashlib.js
+export JSS_NOSTR=true
+export JSS_INVITE_ONLY=true
+export JSS_WEBID_TLS=true
+export JSS_DEFAULT_QUOTA=100MB
+export JSS_ACTIVITYPUB=true
+export JSS_AP_USERNAME=alice
+export JSS_PUBLIC=true
+export JSS_READ_ONLY=true
+export JSS_LIVE_RELOAD=true
+export JSS_SOLIDOS_UI=true
+export JSS_PAY=true
+export JSS_PAY_COST=10
+export JSS_PAY_ADDRESS=your-address
+export JSS_PAY_TOKEN=PODS
+export JSS_PAY_RATE=10
+export JSS_MONGO=true
+export JSS_MONGO_URL=mongodb://localhost:27017
+export JSS_MONGO_DATABASE=solid
+export JSS_WEBRTC=true
+jss start
+```
+
+### Config File
+
+Create `config.json`:
+
+```json
+{
+  "port": 8443,
+  "root": "./data",
+  "sslKey": "./ssl/key.pem",
+  "sslCert": "./ssl/cert.pem",
+  "conneg": true,
+  "notifications": true
+}
+```
+
+Then: `jss start --config config.json`
+
+### Creating a Pod
+
+```bash
+curl -X POST http://localhost:3000/.pods \
+  -H "Content-Type: application/json" \
+  -d '{"name": "alice"}'
+```
+
+Response:
+```json
+{
+  "name": "alice",
+  "webId": "http://localhost:3000/alice/#me",
+  "podUri": "http://localhost:3000/alice/",
+  "token": "eyJ..."
+}
+```
+
+### Single-User Mode
+
+For personal pod servers where only one user needs access:
+
+```bash
+# Basic single-user mode (creates pod at /me/)
+jss start --single-user --idp
+
+# Custom username
+jss start --single-user --single-user-name alice --idp
+
+# Root-level pod (pod at /, WebID at /profile/card#me)
+jss start --single-user --single-user-name '' --idp
+
+# Via environment
+JSS_SINGLE_USER=true jss start --idp
+```
+
+**Features:**
+- Pod auto-created on first startup with full structure (inbox, public, private, profile)
+- Registration endpoint disabled (returns 403)
+- Login still works for the single user
+- Proper ACLs generated automatically
+
+
+## Invite-Only Registration
+
+Control who can create accounts by requiring invite codes:
+
+```bash
+jss start --idp --invite-only
+```
+
+### Managing Invite Codes
+
+```bash
+# Create a single-use invite
+jss invite create
+# Created invite code: ABCD1234
+
+# Create multi-use invite with note
+jss invite create -u 5 -n "For team members"
+
+# List all active invites
+jss invite list
+#   CODE        USES     CREATED      NOTE
+#   -------------------------------------------------------
+#   ABCD1234    0/1      2026-01-03
+#   EFGH5678    2/5      2026-01-03   For team members
+
+# Revoke an invite
+jss invite revoke ABCD1234
+```
+
+### How It Works
+
+| Mode | Registration | Pod Creation |
+|------|--------------|--------------|
+| Open (default) | Anyone can register | Anyone can create pods |
+| Invite-only | Requires valid invite code | Via registration only |
+
+When `--invite-only` is enabled:
+- The registration page shows an "Invite Code" field
+- Invalid or expired codes are rejected with an error
+- Each use decrements the invite's remaining uses
+- Depleted invites are automatically removed
+
+Invite codes are stored in `.server/invites.json` in your data directory.
+
+## Storage Quotas
+
+Limit storage per pod to prevent abuse and manage resources:
+
+```bash
+jss start --default-quota 50MB
+```
+
+### Managing Quotas
+
+```bash
+# Set quota for a user (overrides default)
+jss quota set alice 100MB
+
+# Show quota info
+jss quota show alice
+#   alice:
+#     Used:  12.5 MB
+#     Limit: 100 MB
+#     Free:  87.5 MB
+#     Usage: 12%
+
+# Recalculate from actual disk usage
+jss quota reconcile alice
+```
+
+### How It Works
+
+- Quotas are tracked incrementally on PUT, POST, and DELETE operations
+- When quota is exceeded, the server returns HTTP 507 Insufficient Storage
+- Each pod stores its quota in `/{pod}/.quota.json`
+- Use `reconcile` to fix quota drift from manual file changes
+
+### Size Formats
+
+Supported formats: `50MB`, `1GB`, `500KB`, `1TB`
+
+## Storage Quotas
+
+Limit storage per pod to prevent abuse and manage resources:
+
+```bash
+jss start --default-quota 50MB
+```
+
+### Managing Quotas
+
+```bash
+# Set quota for a user (overrides default)
+jss quota set alice 100MB
+
+# Show quota info
+jss quota show alice
+#   alice:
+#     Used:  12.5 MB
+#     Limit: 100 MB
+#     Free:  87.5 MB
+#     Usage: 12%
+
+# Recalculate from actual disk usage
+jss quota reconcile alice
+```
+
+### How It Works
+
+- Quotas are tracked incrementally on PUT, POST, and DELETE operations
+- When quota is exceeded, the server returns HTTP 507 Insufficient Storage
+- Each pod stores its quota in `/{pod}/.quota.json`
+- Use `reconcile` to fix quota drift from manual file changes
+
+### Size Formats
+
+Supported formats: `50MB`, `1GB`, `500KB`, `1TB`
+
+### Mashlib Data Browser
+
+Enable the [SolidOS Mashlib](https://github.com/SolidOS/mashlib) data browser for RDF resources. Two modes are available:
+
+**CDN Mode** (recommended for getting started):
+```bash
+jss start --mashlib-cdn --conneg
+```
+Loads mashlib from unpkg.com CDN. Zero footprint - no local files needed.
+
+**Local Mode** (for production/offline):
+```bash
+jss start --mashlib --conneg
+```
+Serves mashlib from `src/mashlib-local/dist/`. Requires building mashlib locally:
+```bash
+cd src/mashlib-local
+npm install && npm run build
+```
+
+**ES Module Mode** (for custom or next-gen mashlib builds):
+```bash
+jss start --mashlib-module https://example.com/mashlib.js
+```
+Loads an ES module-based data browser from any URL. Uses `<script type="module">` and `<div id="mashlib">` (self-initializing). CSS is auto-derived by replacing `.js` with `.css`. Content negotiation is auto-enabled.
+
+**How it works:**
+1. Browser requests `/alice/public/data.ttl` with `Accept: text/html`
+2. Server returns Mashlib HTML wrapper
+3. Mashlib fetches the actual data via content negotiation
+4. Mashlib renders an interactive, editable view
+
+**Note:** Mashlib works best with `--conneg` enabled for Turtle support.
+
+**Modern UI (SolidOS UI):**
+```bash
+jss start --mashlib --solidos-ui --conneg
+```
+Serves a modern Nextcloud-style UI shell while reusing mashlib's data layer. The `--solidos-ui` flag swaps the classic databrowser interface for a cleaner, mobile-friendly design with:
+- Modern file browser with breadcrumb navigation
+- Profile, Contacts, Sharing, and Settings views
+- Path-based URLs (browser URL reflects current resource)
+- Responsive design for mobile devices
+
+Requires solidos-ui dist files in `src/mashlib-local/dist/solidos-ui/`. See [solidos-ui](https://github.com/solidos/solidos/tree/main/workspaces/solidos-ui) for details.
+
+### Profile Pages
+
+Pod profiles (`/alice/`) use HTML with embedded JSON-LD data islands and are rendered using:
+- [mashlib-jss](https://github.com/JavaScriptSolidServer/mashlib-jss) - A fork of mashlib with `getPod()` fix for path-based pods
+- [solidos-lite](https://github.com/SolidOS/solidos-lite) - Parses JSON-LD data islands into the RDF store
+
+This allows profiles to work without server-side content negotiation while still providing full SolidOS editing capabilities.
+
+### WebSocket Notifications
+
+Enable real-time notifications for resource changes:
+
+```javascript
+const server = createServer({ notifications: true });
+```
+
+Clients discover the WebSocket URL via the `Updates-Via` header:
+
+```bash
+curl -I http://localhost:3000/alice/public/
+# Updates-Via: ws://localhost:3000/.notifications
+```
+
+Protocol (solid-0.1, compatible with SolidOS):
+```
+Server: protocol solid-0.1
+Client: sub http://localhost:3000/alice/public/data.json
+Server: ack http://localhost:3000/alice/public/data.json
+Server: pub http://localhost:3000/alice/public/data.json  (on change)
+```
+

package/docs/mongodb.md

@@ -0,0 +1,42 @@
+## MongoDB Storage (`/db/` Route)
+
+Optional MongoDB-backed route for JSON-LD documents that need scale (social feeds, posts, follows). All other routes continue using the filesystem unchanged.
+
+```bash
+# Install the optional MongoDB driver
+npm install mongodb
+
+# Start with MongoDB enabled
+jss start --mongo --mongo-url mongodb://localhost:27017 --mongo-database solid
+```
+
+### Operations
+
+```bash
+# Store a document
+curl -X PUT http://localhost:3000/db/alice/notes/1 \
+  -H "Content-Type: application/ld+json" \
+  -H "Authorization: Bearer <token>" \
+  -d '{"@context": "https://schema.org/", "@type": "Note", "text": "Hello"}'
+
+# Read it back
+curl http://localhost:3000/db/alice/notes/1
+
+# List container (derived from URI prefixes)
+curl http://localhost:3000/db/alice/
+
+# Delete
+curl -X DELETE http://localhost:3000/db/alice/notes/1 \
+  -H "Authorization: Bearer <token>"
+```
+
+### How It Works
+
+- `GET /db/:path` — retrieve a document by URI, or list a virtual container
+- `PUT /db/:path` — create or update (upsert) a JSON-LD document
+- `DELETE /db/:path` — remove a document
+- Returns standard LDP headers (Link, ETag, WAC-Allow, CORS)
+- Supports conditional requests (If-Match, If-None-Match)
+- Container listings are computed from URI prefix queries — no directory management needed
+- Auth: pod owner can write (`/db/{podName}/...`), reads are public
+- MongoDB is an optional dependency — the server runs without it

package/docs/payments.md

@@ -0,0 +1,94 @@
+## HTTP 402 Paid Access
+
+Monetize API endpoints with per-request satoshi payments. Resources under `/pay/*` require NIP-98 authentication and a positive balance.
+
+```bash
+jss start --pay --pay-cost 10 --pay-address your-address --pay-token PODS --pay-rate 10
+```
+
+### Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/pay/.info` | Public: cost, token info, chains, pool |
+| GET | `/pay/.balance` | Check your balance (NIP-98 auth) |
+| POST | `/pay/.deposit` | Deposit sats via TXO URI or MRC20 state proof |
+| POST | `/pay/.buy` | Buy tokens with sat balance (requires `--pay-token`) |
+| POST | `/pay/.withdraw` | Withdraw balance as portable tokens (requires `--pay-token`) |
+| GET | `/pay/.offers` | List open sell orders (secondary market) |
+| POST | `/pay/.sell` | Create a sell order (requires `--pay-token`) |
+| POST | `/pay/.swap` | Execute a swap against a sell order |
+| GET | `/pay/.pool` | AMM pool state (requires `--pay-chains`) |
+| POST | `/pay/.pool` | AMM swap, add/remove liquidity |
+| GET | `/pay/*` | Paid resource access (deducts balance) |
+
+### How It Works
+
+1. Authenticate with NIP-98 (Nostr HTTP Auth)
+2. Check balance at `/pay/.balance`
+3. Deposit sats by POSTing a TXO URI to `/pay/.deposit`
+4. Access paid resources — each request deducts the configured cost
+5. Optionally buy tokens (`/pay/.buy`) or withdraw as portable tokens (`/pay/.withdraw`)
+6. Balance tracked in a [Web Ledger](https://webledgers.org/) at `/.well-known/webledgers/webledgers.json`
+
+### Example
+
+```bash
+# Check balance
+curl -H "Authorization: Nostr <base64-event>" http://localhost:3000/pay/.balance
+
+# Deposit (post a confirmed transaction output)
+curl -X POST -H "Authorization: Nostr <base64-event>" \
+  http://localhost:3000/pay/.deposit \
+  -d "txid:vout"
+
+# Access paid resource
+curl -H "Authorization: Nostr <base64-event>" http://localhost:3000/pay/my-resource
+
+# Buy tokens with sat balance
+curl -X POST -H "Authorization: Nostr <base64-event>" \
+  -H "Content-Type: application/json" \
+  http://localhost:3000/pay/.buy \
+  -d '{"amount": 100}'
+
+# Withdraw entire balance as portable tokens
+curl -X POST -H "Authorization: Nostr <base64-event>" \
+  -H "Content-Type: application/json" \
+  http://localhost:3000/pay/.withdraw \
+  -d '{"all": true}'
+```
+
+Deposit verification uses the mempool API (default: testnet4). The `X-Balance` and `X-Cost` headers are returned on successful paid requests. Buy and withdraw return portable MRC20 proofs with Bitcoin anchor data for independent verification.
+
+### Secondary Market
+
+Users can trade tokens peer-to-peer through the pod. Sell orders are created via `/pay/.sell` and filled via `/pay/.swap`. The pod acts as escrow — transferring tokens on the Bitcoin-anchored MRC20 trail and settling sats in the webledger.
+
+### Multi-Chain AMM
+
+Enable multi-chain deposits and an automated market maker:
+
+```bash
+jss start --pay --pay-chains "tbtc3,tbtc4"
+```
+
+Deposits detect the chain from the TXO URI prefix (`txo:tbtc3:txid:vout`). Each chain's balance is tracked separately. The AMM uses a constant-product formula (x × y = k) with a 0.3% fee.
+
+```bash
+# Add liquidity
+curl -X POST -H "Authorization: Nostr <token>" \
+  -H "Content-Type: application/json" \
+  http://localhost:3000/pay/.pool \
+  -d '{"action": "add-liquidity", "tbtc3": 1000, "tbtc4": 5000}'
+
+# Swap
+curl -X POST -H "Authorization: Nostr <token>" \
+  -H "Content-Type: application/json" \
+  http://localhost:3000/pay/.pool \
+  -d '{"action": "swap", "sell": "tbtc3", "amount": 100}'
+
+# Check pool state
+curl http://localhost:3000/pay/.pool
+```
+
+Supported chains: `btc`, `tbtc3`, `tbtc4`, `ltc`, `signet`.

package/docs/remotestorage.md

@@ -0,0 +1,86 @@
+## remoteStorage
+
+JSS implements the [remoteStorage protocol](https://remotestorage.io/spec/draft-dejong-remotestorage-22). The storage routes are always available, but WebFinger discovery and OAuth require `--activitypub` (which provides the WebFinger and OAuth endpoints). Any remoteStorage-compatible app can store and sync data on your pod.
+
+```bash
+jss start --activitypub --idp
+```
+
+### Discovery
+
+remoteStorage clients discover the storage endpoint via WebFinger:
+
+```bash
+curl "http://localhost:3000/.well-known/webfinger?resource=acct:me@localhost:3000"
+```
+
+The response includes a `remotestorage` link relation pointing to `/storage/me/`.
+
+### Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/storage/:user/*` | Read file or list folder (JSON-LD) |
+| `HEAD` | `/storage/:user/*` | Get metadata (ETag, Content-Type, size) |
+| `PUT` | `/storage/:user/*` | Write file (creates parent folders) |
+| `DELETE` | `/storage/:user/*` | Delete file |
+
+### How It Works
+
+- **Auth**: Bearer token via OAuth 2.0 (same flow as Mastodon clients)
+- **Public folder**: `/storage/me/public/*` is readable without auth
+- **Conditional requests**: If-Match, If-None-Match (uses shared ETag utilities)
+- **Dotfile protection**: `.acl`, `.meta`, and other dotfiles are blocked
+- **Read-only mode**: Respects `--read-only` flag
+- **Streaming**: Large files are streamed, not buffered
+
+### Testing
+
+```bash
+# Write a file (needs Bearer token from OAuth flow)
+curl -X PUT http://localhost:3000/storage/me/documents/hello.txt \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: text/plain" \
+  -d "Hello, remoteStorage!"
+
+# Read it back
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  http://localhost:3000/storage/me/documents/hello.txt
+
+# List a folder
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  http://localhost:3000/storage/me/documents/
+
+# Read from public folder (no auth needed)
+curl http://localhost:3000/storage/me/public/readme.txt
+```
+
+### Linking Nostr to WebID (did:nostr)
+
+Bridge your Nostr identity to a Solid WebID for seamless authentication:
+
+**Step 1:** Add your WebID to your Nostr profile (kind 0 event):
+```json
+{
+  "name": "alice",
+  "alsoKnownAs": ["https://solid.social/alice/profile/card#me"]
+}
+```
+
+**Step 2:** Add the did:nostr link to your WebID profile:
+```json
+{
+  "@id": "#me",
+  "owl:sameAs": "did:nostr:<your-64-char-hex-pubkey>"
+}
+```
+
+**How it works:**
+1. NIP-98 signature is verified (existing flow)
+2. DID document is fetched from `nostr.social/.well-known/did/nostr/<pubkey>.json`
+3. `alsoKnownAs` is checked for a WebID URL
+4. WebID profile is fetched and `owl:sameAs` verified
+5. If bidirectional link exists → authenticated as WebID
+
+This enables Nostr users to access their Solid pods using existing NIP-07 browser extensions.
+