javascript-solid-server 0.0.135 → 0.0.137

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/.claude/settings.local.json +8 -1
  2. package/README.md +6 -0
  3. package/docs/payments.md +35 -13
  4. package/jss-architecture.svg +182 -0
  5. package/jsserve/LICENSE +21 -0
  6. package/jsserve/README.md +194 -0
  7. package/jsserve/bin/jsserve.js +329 -0
  8. package/jsserve/package-lock.json +1832 -0
  9. package/jsserve/package.json +45 -0
  10. package/package.json +1 -1
  11. package/src/notifications/websocket.js +11 -4
  12. package/src/server.js +4 -0
  13. package/src/utils/url.js +31 -8
  14. package/test/url.test.js +75 -0
package/.claude/settings.local.json CHANGED
@@ -343,7 +343,14 @@
343
343
  "Bash(sed -i 's/\"currency\":\"sats\"/\"currency\":\"tbtc4\"/g' /home/melvin/articles/solid-402.html /home/melvin/articles/solid-pay.html /home/melvin/articles/solid-balance.html)",
344
344
  "WebFetch(domain:lists.w3.org)",
345
345
  "Bash(git:*)",
346
- "Bash(npm publish:*)"
346
+ "Bash(npm publish:*)",
347
+ "WebFetch(domain:git-mark.com)",
348
+ "WebFetch(domain:w3id.org)",
349
+ "WebFetch(domain:webledgers.github.io)",
350
+ "Bash(\\\\\"git config:*)",
351
+ "Read(//usr/local/lib/node_modules/gitmark-test/**)",
352
+ "WebFetch(domain:nip98.com)",
353
+ "WebFetch(domain:htmlpreview.github.io)"
347
354
  ]
348
355
  }
349
356
  }
package/README.md CHANGED
@@ -6,6 +6,12 @@ A minimal, fast, JSON-LD native Solid server.
6
6
 
7
7
  **[Documentation](https://javascriptsolidserver.github.io/docs/)** | **[GitHub](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer)**
8
8
 
9
+ ## Architecture
10
+
11
+ <p align="center">
12
+ <img src="jss-architecture.svg" alt="JSS Architecture Diagram" width="960">
13
+ </p>
14
+
9
15
  ## Features
10
16
 
11
17
  - **LDP CRUD** — GET, PUT, POST, DELETE, HEAD, PATCH (N3 + SPARQL Update)
package/docs/payments.md CHANGED
@@ -73,8 +73,10 @@ jss start --pay --pay-cost 10 --pay-address your-address --pay-token PODS --pay-
73
73
  | Method | Path | Description |
74
74
  |--------|------|-------------|
75
75
  | GET | `/pay/.info` | Public: cost, token info, chains, pool |
76
- | GET | `/pay/.balance` | Check your balance (NIP-98 auth) |
77
- | POST | `/pay/.deposit` | Deposit sats via TXO URI or MRC20 state proof |
76
+ | GET | `/pay/.address` | Public: pod's taproot deposit address (optional `?user=did:nostr:...` for per-user address) |
77
+ | GET | `/pay/.balance` | Check your balance (NIP-98 auth) — also auto-detects new deposits |
78
+ | POST | `/pay/.deposit` | Deposit sats via TXO URI, claim `{txid, vout, chain}`, or MRC20 state proof |
79
+ | POST | `/pay/.withdraw-sats` | Withdraw sats as a TXO voucher URI |
78
80
  | POST | `/pay/.buy` | Buy tokens with sat balance (requires `--pay-token`) |
79
81
  | POST | `/pay/.withdraw` | Withdraw balance as portable tokens (requires `--pay-token`) |
80
82
  | GET | `/pay/.offers` | List open sell orders (secondary market) |
@@ -86,41 +88,61 @@ jss start --pay --pay-cost 10 --pay-address your-address --pay-token PODS --pay-
86
88
 
87
89
  ### How It Works
88
90
 
89
- 1. Authenticate with NIP-98 (Nostr HTTP Auth)
90
- 2. Check balance at `/pay/.balance`
91
- 3. Deposit sats by POSTing a TXO URI to `/pay/.deposit`
91
+ 1. Get your deposit address: `GET /pay/.address?user=did:nostr:YOUR_PUBKEY`
92
+ 2. Send sats to that address from any Bitcoin wallet
93
+ 3. Check balance at `/pay/.balance` — deposits are auto-detected
92
94
  4. Access paid resources — each request deducts the configured cost
93
- 5. Optionally buy tokens (`/pay/.buy`) or withdraw as portable tokens (`/pay/.withdraw`)
94
- 6. Balance tracked in a [Web Ledger](https://webledgers.org/) at `/.well-known/webledgers/webledgers.json`
95
+ 5. Withdraw sats as a portable voucher: `POST /pay/.withdraw-sats`
96
+ 6. Optionally buy tokens (`/pay/.buy`) or withdraw as portable tokens (`/pay/.withdraw`)
97
+ 7. Balance tracked in a [Web Ledger](https://webledgers.org/) at `/.well-known/webledgers/webledgers.json`
98
+
99
+ Each user gets a unique taproot deposit address derived from the pod's master key + their identity. The pod auto-detects deposits by scanning the mempool API when you check your balance.
95
100
 
96
101
  ### Example
97
102
 
98
103
  ```bash
99
- # Check balance
104
+ # Get your deposit address
105
+ curl http://localhost:4443/pay/.address?chain=tbtc4&user=did:nostr:YOUR_PUBKEY
106
+ # → {"address": "tb1p...", "chain": "tbtc4", "pubkey": "02..."}
107
+
108
+ # Send sats to that address, then check balance (auto-detects deposits)
100
109
  curl -H "Authorization: Nostr <base64-event>" http://localhost:4443/pay/.balance
101
110
 
102
- # Deposit (post a confirmed transaction output)
111
+ # Or deposit manually with a TXO voucher URI
103
112
  curl -X POST -H "Authorization: Nostr <base64-event>" \
104
113
  http://localhost:4443/pay/.deposit \
105
- -d "txid:vout"
114
+ -d "txo:tbtc4:txid:vout?amount=X&key=Y"
115
+
116
+ # Or claim a deposit to the pod's address
117
+ curl -X POST -H "Authorization: Nostr <base64-event>" \
118
+ -H "Content-Type: application/json" \
119
+ http://localhost:4443/pay/.deposit \
120
+ -d '{"txid": "abc...", "vout": 0, "chain": "tbtc4"}'
106
121
 
107
122
  # Access paid resource
108
123
  curl -H "Authorization: Nostr <base64-event>" http://localhost:4443/pay/my-resource
109
124
 
125
+ # Withdraw sats as a portable TXO voucher
126
+ curl -X POST -H "Authorization: Nostr <base64-event>" \
127
+ -H "Content-Type: application/json" \
128
+ http://localhost:4443/pay/.withdraw-sats \
129
+ -d '{"amount": 10000, "chain": "tbtc4"}'
130
+ # → {"voucher": "txo:tbtc4:txid:0?amount=10000&key=...", ...}
131
+
110
132
  # Buy tokens with sat balance
111
133
  curl -X POST -H "Authorization: Nostr <base64-event>" \
112
134
  -H "Content-Type: application/json" \
113
135
  http://localhost:4443/pay/.buy \
114
- -d '{"amount": 100}'
136
+ -d '{"amount": 100, "currency": "tbtc4"}'
115
137
 
116
138
  # Withdraw entire balance as portable tokens
117
139
  curl -X POST -H "Authorization: Nostr <base64-event>" \
118
140
  -H "Content-Type: application/json" \
119
141
  http://localhost:4443/pay/.withdraw \
120
- -d '{"all": true}'
142
+ -d '{"all": true, "currency": "tbtc4"}'
121
143
  ```
122
144
 
123
- 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.
145
+ Three deposit methods: (1) send to your per-user address and check balance (auto-detected), (2) TXO voucher URI with private key, (3) claim a txid after sending to the pod's address. The `X-Balance`, `X-Cost`, and `X-Pay-Currency` headers are returned on successful paid requests. Buy and withdraw return portable MRC20 proofs with Bitcoin anchor data for independent verification.
124
146
 
125
147
  ### Secondary Market
126
148
 
package/jss-architecture.svg ADDED
@@ -0,0 +1,182 @@
1
+ <?xml version="1.0" encoding="UTF-8"?>
2
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 840" width="960" height="840">
3
+ <defs>
4
+ <marker id="aBlue" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
5
+ <path d="M 0 1 L 10 5 L 0 9 z" fill="#2563eb"/>
6
+ </marker>
7
+ <marker id="aPurp" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
8
+ <path d="M 0 1 L 10 5 L 0 9 z" fill="#7c3aed"/>
9
+ </marker>
10
+ <marker id="aGreen" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
11
+ <path d="M 0 1 L 10 5 L 0 9 z" fill="#059669"/>
12
+ </marker>
13
+ <marker id="aOrange" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
14
+ <path d="M 0 1 L 10 5 L 0 9 z" fill="#ea580c"/>
15
+ </marker>
16
+ <marker id="aTeal" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
17
+ <path d="M 0 1 L 10 5 L 0 9 z" fill="#0d9488"/>
18
+ </marker>
19
+ <marker id="aGray" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
20
+ <path d="M 0 1 L 10 5 L 0 9 z" fill="#6b7280"/>
21
+ </marker>
22
+ <marker id="aGold" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
23
+ <path d="M 0 1 L 10 5 L 0 9 z" fill="#b45309"/>
24
+ </marker>
25
+ <marker id="aRed" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
26
+ <path d="M 0 1 L 10 5 L 0 9 z" fill="#dc2626"/>
27
+ </marker>
28
+ <filter id="shadow" x="-2%" y="-2%" width="104%" height="108%">
29
+ <feDropShadow dx="0" dy="1" stdDeviation="2" flood-color="#000" flood-opacity="0.08"/>
30
+ </filter>
31
+ </defs>
32
+ <rect width="960" height="840" fill="#ffffff"/>
33
+ <text x="480" y="34" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="22" font-weight="700" fill="#111827">JavaScript Solid Server (JSS)</text>
34
+ <text x="480" y="52" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="#6b7280">Lightweight high-performance Solid pod server · ~1 MB · 5,400+ req/s · Node.js</text>
35
+ <!-- Layer 1: Clients -->
36
+ <rect x="80" y="72" width="800" height="64" rx="8" fill="#eff6ff" stroke="none"/>
37
+ <text x="96" y="88" font-family="system-ui, sans-serif" font-size="10" font-weight="700" fill="#2563eb" letter-spacing="0.5">CLIENTS</text>
38
+ <rect x="96" y="94" width="104" height="32" rx="8" fill="#ffffff" stroke="#2563eb" stroke-width="1.5" filter="url(#shadow)"/>
39
+ <text x="148" y="114" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" font-weight="600" fill="#111827">Solid Apps</text>
40
+ <rect x="228" y="94" width="104" height="32" rx="8" fill="#ffffff" stroke="#059669" stroke-width="1.5" filter="url(#shadow)"/>
41
+ <text x="280" y="114" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" font-weight="600" fill="#111827">Browsers</text>
42
+ <rect x="360" y="94" width="104" height="32" rx="8" fill="#ffffff" stroke="#7c3aed" stroke-width="1.5" filter="url(#shadow)"/>
43
+ <text x="412" y="114" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" font-weight="600" fill="#111827">Nostr Clients</text>
44
+ <rect x="492" y="94" width="104" height="32" rx="8" fill="#ffffff" stroke="#ea580c" stroke-width="1.5" filter="url(#shadow)"/>
45
+ <text x="544" y="114" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" font-weight="600" fill="#111827">Fediverse</text>
46
+ <rect x="624" y="94" width="104" height="32" rx="8" fill="#ffffff" stroke="#b45309" stroke-width="1.5" filter="url(#shadow)"/>
47
+ <text x="676" y="114" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" font-weight="600" fill="#111827">Git</text>
48
+ <rect x="756" y="94" width="104" height="32" rx="8" fill="#ffffff" stroke="#6b7280" stroke-width="1.5" filter="url(#shadow)"/>
49
+ <text x="808" y="114" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" font-weight="600" fill="#111827">CLI / API</text>
50
+ <!-- Layer 2: Authentication -->
51
+ <rect x="80" y="160" width="800" height="72" rx="8" fill="#f0fdfa" stroke="none"/>
52
+ <text x="96" y="176" font-family="system-ui, sans-serif" font-size="10" font-weight="700" fill="#0d9488" letter-spacing="0.5">AUTHENTICATION LAYER</text>
53
+ <rect x="112" y="182" width="112" height="40" rx="8" fill="#ffffff" stroke="#0d9488" stroke-width="1.5" filter="url(#shadow)"/>
54
+ <text x="168" y="200" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" font-weight="600" fill="#111827">Solid-OIDC</text>
55
+ <text x="168" y="214" text-anchor="middle" font-family="system-ui, sans-serif" font-size="8.5" fill="#6b7280">DPoP tokens</text>
56
+ <rect x="264" y="182" width="112" height="40" rx="8" fill="#ffffff" stroke="#059669" stroke-width="1.5" filter="url(#shadow)"/>
57
+ <text x="320" y="200" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" font-weight="600" fill="#111827">Passkeys</text>
58
+ <text x="320" y="214" text-anchor="middle" font-family="system-ui, sans-serif" font-size="8.5" fill="#6b7280">Schnorr SSO</text>
59
+ <rect x="416" y="182" width="112" height="40" rx="8" fill="#ffffff" stroke="#7c3aed" stroke-width="1.5" filter="url(#shadow)"/>
60
+ <text x="472" y="200" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" font-weight="600" fill="#111827">Nostr NIP-98</text>
61
+ <text x="472" y="214" text-anchor="middle" font-family="system-ui, sans-serif" font-size="8.5" fill="#6b7280">Signatures</text>
62
+ <rect x="568" y="182" width="112" height="40" rx="8" fill="#ffffff" stroke="#b45309" stroke-width="1.5" filter="url(#shadow)"/>
63
+ <text x="624" y="200" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" font-weight="600" fill="#111827">Invites</text>
64
+ <text x="624" y="214" text-anchor="middle" font-family="system-ui, sans-serif" font-size="8.5" fill="#6b7280">Controlled signup</text>
65
+ <rect x="720" y="182" width="112" height="40" rx="8" fill="#ffffff" stroke="#2563eb" stroke-width="1.5" filter="url(#shadow)"/>
66
+ <text x="776" y="200" text-anchor="middle" font-family="system-ui, sans-serif" font-size="10" font-weight="600" fill="#111827">WebID</text>
67
+ <text x="776" y="214" text-anchor="middle" font-family="system-ui, sans-serif" font-size="8.5" fill="#6b7280">Identity</text>
68
+ <!-- Layer 3: Core Server -->
69
+ <rect x="80" y="256" width="800" height="168" rx="8" fill="#f0fdf4" stroke="none"/>
70
+ <text x="96" y="272" font-family="system-ui, sans-serif" font-size="10" font-weight="700" fill="#059669" letter-spacing="0.5">CORE SERVER ENGINE</text>
71
+ <rect x="100" y="280" width="200" height="56" rx="8" fill="#ffffff" stroke="#059669" stroke-width="1.5" filter="url(#shadow)"/>
72
+ <text x="200.0" y="300" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-weight="600" fill="#111827">LDP CRUD</text>
73
+ <text x="200.0" y="326" text-anchor="middle" font-family="system-ui, sans-serif" font-size="8.5" fill="#6b7280">GET PUT POST DELETE PATCH HEAD</text>
74
+ <text x="200" y="310" text-anchor="middle" font-family="monospace" font-size="9" fill="#059669">5,400+ req/s</text>
75
+ <rect x="320" y="280" width="160" height="56" rx="8" fill="#ffffff" stroke="#2563eb" stroke-width="1.5" filter="url(#shadow)"/>
76
+ <text x="400.0" y="300" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-weight="600" fill="#111827">Content Negotiation</text>
77
+ <text x="400.0" y="326" text-anchor="middle" font-family="system-ui, sans-serif" font-size="8.5" fill="#6b7280">JSON-LD + Turtle + N3</text>
78
+ <rect x="500" y="280" width="160" height="56" rx="8" fill="#ffffff" stroke="#7c3aed" stroke-width="1.5" filter="url(#shadow)"/>
79
+ <text x="580.0" y="300" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-weight="600" fill="#111827">WebSocket</text>
80
+ <text x="580.0" y="326" text-anchor="middle" font-family="system-ui, sans-serif" font-size="8.5" fill="#6b7280">Live update notifications</text>
81
+ <rect x="680" y="280" width="168" height="56" rx="8" fill="#ffffff" stroke="#b45309" stroke-width="1.5" filter="url(#shadow)"/>
82
+ <text x="764.0" y="300" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-weight="600" fill="#111827">SPARQL Update</text>
83
+ <text x="764.0" y="326" text-anchor="middle" font-family="system-ui, sans-serif" font-size="8.5" fill="#6b7280">N3 PATCH operations</text>
84
+ <rect x="100" y="352" width="268" height="56" rx="6" fill="#ffffff" stroke="#d1d5db" stroke-width="1"/>
85
+ <text x="112" y="372" font-family="system-ui, sans-serif" font-size="10" font-weight="600" fill="#374151">Multi-Pod Architecture</text>
86
+ <text x="112" y="394" font-family="monospace" font-size="9" fill="#6b7280">path: /alice/ | subdomain: alice.pod.me</text>
87
+ <rect x="388" y="352" width="132" height="56" rx="6" fill="#ffffff" stroke="#d1d5db" stroke-width="1"/>
88
+ <text x="400" y="372" font-family="system-ui, sans-serif" font-size="10" font-weight="600" fill="#374151">HTTP 402 Pay</text>
89
+ <text x="400" y="394" font-family="monospace" font-size="9" fill="#6b7280">satoshi per request</text>
90
+ <rect x="540" y="352" width="132" height="56" rx="6" fill="#ffffff" stroke="#d1d5db" stroke-width="1"/>
91
+ <text x="552" y="372" font-family="system-ui, sans-serif" font-size="10" font-weight="600" fill="#374151">Storage Quotas</text>
92
+ <text x="552" y="394" font-family="monospace" font-size="9" fill="#6b7280">per-user limits</text>
93
+ <rect x="692" y="352" width="156" height="56" rx="6" fill="#ffffff" stroke="#d1d5db" stroke-width="1"/>
94
+ <text x="704" y="372" font-family="system-ui, sans-serif" font-size="10" font-weight="600" fill="#374151">Terminal</text>
95
+ <text x="704" y="394" font-family="monospace" font-size="9" fill="#6b7280">WebSocket shell</text>
96
+ <!-- Layer 4: Protocol Integrations -->
97
+ <rect x="80" y="448" width="800" height="80" rx="8" fill="#faf5ff" stroke="none"/>
98
+ <text x="96" y="464" font-family="system-ui, sans-serif" font-size="10" font-weight="700" fill="#7c3aed" letter-spacing="0.5">PROTOCOL INTEGRATIONS</text>
99
+ <rect x="100" y="470" width="112" height="48" rx="8" fill="#ffffff" stroke="#7c3aed" stroke-width="1.5" filter="url(#shadow)"/>
100
+ <text x="156.0" y="490" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-weight="600" fill="#111827">Nostr Relay</text>
101
+ <text x="156.0" y="508" text-anchor="middle" font-family="system-ui, sans-serif" font-size="8.5" fill="#6b7280">NIP-01 wss://</text>
102
+ <rect x="224" y="470" width="112" height="48" rx="8" fill="#ffffff" stroke="#ea580c" stroke-width="1.5" filter="url(#shadow)"/>
103
+ <text x="280.0" y="490" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-weight="600" fill="#111827">ActivityPub</text>
104
+ <text x="280.0" y="508" text-anchor="middle" font-family="system-ui, sans-serif" font-size="8.5" fill="#6b7280">Fediverse</text>
105
+ <rect x="348" y="470" width="112" height="48" rx="8" fill="#ffffff" stroke="#b45309" stroke-width="1.5" filter="url(#shadow)"/>
106
+ <text x="404.0" y="490" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-weight="600" fill="#111827">Git HTTP</text>
107
+ <text x="404.0" y="508" text-anchor="middle" font-family="system-ui, sans-serif" font-size="8.5" fill="#6b7280">Clone + Push</text>
108
+ <rect x="472" y="470" width="112" height="48" rx="8" fill="#ffffff" stroke="#2563eb" stroke-width="1.5" filter="url(#shadow)"/>
109
+ <text x="528.0" y="490" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-weight="600" fill="#111827">remoteStorage</text>
110
+ <text x="528.0" y="508" text-anchor="middle" font-family="system-ui, sans-serif" font-size="8.5" fill="#6b7280">File sync</text>
111
+ <rect x="596" y="470" width="112" height="48" rx="8" fill="#ffffff" stroke="#059669" stroke-width="1.5" filter="url(#shadow)"/>
112
+ <text x="652.0" y="490" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-weight="600" fill="#111827">WebRTC</text>
113
+ <text x="652.0" y="508" text-anchor="middle" font-family="system-ui, sans-serif" font-size="8.5" fill="#6b7280">P2P signaling</text>
114
+ <rect x="720" y="470" width="112" height="48" rx="8" fill="#ffffff" stroke="#6b7280" stroke-width="1.5" filter="url(#shadow)"/>
115
+ <text x="776.0" y="490" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" font-weight="600" fill="#111827">Tunnel</text>
116
+ <text x="776.0" y="508" text-anchor="middle" font-family="system-ui, sans-serif" font-size="8.5" fill="#6b7280">Reverse proxy</text>
117
+ <!-- Layer 5: Access Control -->
118
+ <rect x="80" y="552" width="800" height="72" rx="8" fill="#fef2f2" stroke="none"/>
119
+ <text x="96" y="568" font-family="system-ui, sans-serif" font-size="10" font-weight="700" fill="#ea580c" letter-spacing="0.5">WEB ACCESS CONTROL (WAC)</text>
120
+ <rect x="108" y="574" width="340" height="40" rx="6" fill="#ffffff" stroke="#d1d5db" stroke-width="1"/>
121
+ <text x="124" y="590" font-family="monospace" font-size="10" fill="#ea580c">resource.acl</text>
122
+ <text x="228" y="590" font-family="system-ui, sans-serif" font-size="9.5" fill="#6b7280">→ agent + mode + accessTo</text>
123
+ <text x="124" y="606" font-family="system-ui, sans-serif" font-size="8.5" fill="#6b7280">Inheritance: acl:default cascades to children</text>
124
+ <rect x="466" y="580" width="60" height="24" rx="6" fill="#ffffff" stroke="#059669" stroke-width="1.2" filter="url(#shadow)"/>
125
+ <text x="496.0" y="596" text-anchor="middle" font-family="system-ui, sans-serif" font-size="9.5" font-weight="500" fill="#111827">Read</text>
126
+ <rect x="534" y="580" width="60" height="24" rx="6" fill="#ffffff" stroke="#ea580c" stroke-width="1.2" filter="url(#shadow)"/>
127
+ <text x="564.0" y="596" text-anchor="middle" font-family="system-ui, sans-serif" font-size="9.5" font-weight="500" fill="#111827">Write</text>
128
+ <rect x="602" y="580" width="60" height="24" rx="6" fill="#ffffff" stroke="#2563eb" stroke-width="1.2" filter="url(#shadow)"/>
129
+ <text x="632.0" y="596" text-anchor="middle" font-family="system-ui, sans-serif" font-size="9.5" font-weight="500" fill="#111827">Append</text>
130
+ <rect x="674" y="580" width="60" height="24" rx="6" fill="#ffffff" stroke="#dc2626" stroke-width="1.2" filter="url(#shadow)"/>
131
+ <text x="704.0" y="596" text-anchor="middle" font-family="system-ui, sans-serif" font-size="9.5" font-weight="500" fill="#111827">Control</text>
132
+ <rect x="750" y="580" width="60" height="24" rx="6" fill="#ffffff" stroke="#b45309" stroke-width="1.2" filter="url(#shadow)"/>
133
+ <text x="780.0" y="596" text-anchor="middle" font-family="system-ui, sans-serif" font-size="9.5" font-weight="500" fill="#111827">Origin</text>
134
+ <!-- Layer 6: Storage -->
135
+ <rect x="80" y="648" width="800" height="80" rx="8" fill="#fefce8" stroke="none"/>
136
+ <text x="96" y="664" font-family="system-ui, sans-serif" font-size="10" font-weight="700" fill="#b45309" letter-spacing="0.5">STORAGE LAYER</text>
137
+ <rect x="120" y="672" width="320" height="40" rx="8" fill="#ffffff" stroke="#059669" stroke-width="2" filter="url(#shadow)"/>
138
+ <text x="280" y="690" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" font-weight="700" fill="#111827">Filesystem (default)</text>
139
+ <text x="280" y="706" text-anchor="middle" font-family="monospace" font-size="8.5" fill="#059669">JSON-LD files + .acl resources</text>
140
+ <rect x="480" y="672" width="200" height="40" rx="8" fill="#ffffff" stroke="#059669" stroke-width="1.2" filter="url(#shadow)"/>
141
+ <text x="580" y="690" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" font-weight="600" fill="#111827">MongoDB</text>
142
+ <text x="580" y="706" text-anchor="middle" font-family="monospace" font-size="8.5" fill="#6b7280">optional /db/ routes</text>
143
+ <rect x="720" y="672" width="140" height="40" rx="8" fill="#ffffff" stroke="#d1d5db" stroke-width="1"/>
144
+ <text x="790" y="690" text-anchor="middle" font-family="monospace" font-size="10" fill="#111827">/alice/</text>
145
+ <text x="790" y="706" text-anchor="middle" font-family="monospace" font-size="10" fill="#6b7280">/bob/</text>
146
+ <!-- Performance Stats -->
147
+ <rect x="80" y="748" width="380" height="72" rx="8" fill="#f0fdf4" stroke="#059669" stroke-width="1.2"/>
148
+ <text x="100" y="766" font-family="system-ui, sans-serif" font-size="10" font-weight="700" fill="#059669">PERFORMANCE</text>
149
+ <text x="108" y="786" font-family="monospace" font-size="9" font-weight="700" fill="#111827">GET</text>
150
+ <text x="108" y="800" font-family="monospace" font-size="10" font-weight="600" fill="#059669">5,400+</text>
151
+ <text x="108" y="812" font-family="monospace" font-size="8" fill="#6b7280">1.2ms</text>
152
+ <text x="196" y="786" font-family="monospace" font-size="9" font-weight="700" fill="#111827">PUT</text>
153
+ <text x="196" y="800" font-family="monospace" font-size="10" font-weight="600" fill="#059669">5,700+</text>
154
+ <text x="196" y="812" font-family="monospace" font-size="8" fill="#6b7280">1.1ms</text>
155
+ <text x="284" y="786" font-family="monospace" font-size="9" font-weight="700" fill="#111827">POST</text>
156
+ <text x="284" y="800" font-family="monospace" font-size="10" font-weight="600" fill="#059669">5,200+</text>
157
+ <text x="284" y="812" font-family="monospace" font-size="8" fill="#6b7280">1.3ms</text>
158
+ <text x="372" y="786" font-family="monospace" font-size="9" font-weight="700" fill="#111827">OPTIONS</text>
159
+ <text x="372" y="800" font-family="monospace" font-size="10" font-weight="600" fill="#059669">10,000+</text>
160
+ <text x="372" y="812" font-family="monospace" font-size="8" fill="#6b7280">0.4ms</text>
161
+ <rect x="500" y="748" width="380" height="72" rx="8" fill="#fffbeb" stroke="#b45309" stroke-width="1.2"/>
162
+ <text x="520" y="766" font-family="system-ui, sans-serif" font-size="10" font-weight="700" fill="#b45309">QUICK START</text>
163
+ <text x="520" y="784" font-family="monospace" font-size="9" fill="#111827">npm install -g javascript-solid-server</text>
164
+ <text x="520" y="800" font-family="monospace" font-size="9" fill="#059669">jss start --port 8443 --idp --nostr</text>
165
+ <text x="520" y="814" font-family="monospace" font-size="8.5" fill="#6b7280">~1 MB package · AGPL-3.0</text>
166
+ <!-- Arrows -->
167
+ <path d="M480 136 L480 160" fill="none" stroke="#0d9488" stroke-width="1.5" marker-end="url(#aTeal)"/>
168
+ <rect x="436.0" y="139" width="88.0" height="18" rx="4" fill="#ffffff" stroke="#0d9488" stroke-width="0.8"/>
169
+ <text x="480" y="151" text-anchor="middle" font-family="system-ui, sans-serif" font-size="9" font-weight="500" fill="#0d9488">authenticate</text>
170
+ <path d="M480 232 L480 256" fill="none" stroke="#059669" stroke-width="1.5" marker-end="url(#aGreen)"/>
171
+ <rect x="452.25" y="235" width="55.5" height="18" rx="4" fill="#ffffff" stroke="#059669" stroke-width="0.8"/>
172
+ <text x="480" y="247" text-anchor="middle" font-family="system-ui, sans-serif" font-size="9" font-weight="500" fill="#059669">request</text>
173
+ <path d="M480 424 L480 448" fill="none" stroke="#7c3aed" stroke-width="1.5" marker-end="url(#aPurp)"/>
174
+ <rect x="445.75" y="427" width="68.5" height="18" rx="4" fill="#ffffff" stroke="#7c3aed" stroke-width="0.8"/>
175
+ <text x="480" y="439" text-anchor="middle" font-family="system-ui, sans-serif" font-size="9" font-weight="500" fill="#7c3aed">protocols</text>
176
+ <path d="M480 528 L480 552" fill="none" stroke="#ea580c" stroke-width="1.5" marker-end="url(#aOrange)"/>
177
+ <rect x="445.75" y="531" width="68.5" height="18" rx="4" fill="#ffffff" stroke="#ea580c" stroke-width="0.8"/>
178
+ <text x="480" y="543" text-anchor="middle" font-family="system-ui, sans-serif" font-size="9" font-weight="500" fill="#ea580c">authorize</text>
179
+ <path d="M480 624 L480 648" fill="none" stroke="#b45309" stroke-width="1.5" marker-end="url(#aGold)"/>
180
+ <rect x="452.25" y="627" width="55.5" height="18" rx="4" fill="#ffffff" stroke="#b45309" stroke-width="0.8"/>
181
+ <text x="480" y="639" text-anchor="middle" font-family="system-ui, sans-serif" font-size="9" font-weight="500" fill="#b45309">persist</text>
182
+ </svg>
package/jsserve/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 JavaScriptSolidServer Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/jsserve/README.md ADDED
@@ -0,0 +1,194 @@
1
+ # servejss
2
+
3
+ > Static file server with REST write support. A drop-in `npx serve` alternative.
4
+
5
+ [![npm version](https://img.shields.io/npm/v/servejss.svg)](https://www.npmjs.com/package/servejss)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
7
+
8
+ ## Why?
9
+
10
+ `npx serve` is great for quickly serving static files, but it's **read-only**. Sometimes you need to:
11
+
12
+ - Upload files during development
13
+ - Test REST APIs locally
14
+ - Sync files between devices on your LAN
15
+ - Have a simple WebDAV-like server
16
+
17
+ **servejss** is `serve` with superpowers: same simple interface, but you can write too.
18
+
19
+ ## Install
20
+
21
+ ```bash
22
+ npm install -g servejss
23
+ ```
24
+
25
+ Or use directly with npx:
26
+
27
+ ```bash
28
+ npx servejss
29
+ ```
30
+
31
+ ## Usage
32
+
33
+ ```bash
34
+ # Serve current directory (read + write enabled)
35
+ servejss
36
+
37
+ # Serve specific directory
38
+ servejss ./public
39
+
40
+ # Custom port
41
+ servejss -p 8080
42
+
43
+ # Specify port and directory
44
+ servejss -l 3000 ./dist
45
+
46
+ # Read-only mode (exactly like npx serve)
47
+ servejss --read-only
48
+ ```
49
+
50
+ ## Output
51
+
52
+ ```
53
+ servejss
54
+
55
+ Directory: /home/user/project
56
+
57
+ Local: http://localhost:3000
58
+ Network: http://192.168.1.5:3000
59
+
60
+ Mode: GET/PUT/DELETE enabled
61
+
62
+ Press Ctrl+C to stop
63
+ ```
64
+
65
+ ## REST API
66
+
67
+ ```bash
68
+ # Read a file
69
+ curl http://localhost:3000/file.txt
70
+
71
+ # Create or update a file
72
+ curl -X PUT -d "Hello, World!" http://localhost:3000/file.txt
73
+
74
+ # Delete a file
75
+ curl -X DELETE http://localhost:3000/file.txt
76
+
77
+ # Conditional update (only if ETag matches)
78
+ curl -X PUT -H 'If-Match: "abc123"' -d "Updated" http://localhost:3000/file.txt
79
+
80
+ # Create only if doesn't exist
81
+ curl -X PUT -H 'If-None-Match: *' -d "New file" http://localhost:3000/new.txt
82
+ ```
83
+
84
+ ## Options
85
+
86
+ ```
87
+ Usage: servejss [options] [directory]
88
+
89
+ Options:
90
+ -v, --version Output version number
91
+ -l, --listen <uri> Specify a URI endpoint on which to listen
92
+ -p, --port <port> Specify custom port (default: 3000)
93
+ -H, --host <host> Host to bind to (default: 0.0.0.0)
94
+ -s, --single Rewrite all not-found requests to index.html (SPA mode)
95
+ -d, --debug Show debugging information
96
+ -C, --cors Enable CORS (enabled by default)
97
+ -L, --no-request-logging Do not log any request information
98
+ --no-etag Disable ETag generation
99
+ -S, --symlinks Resolve symlinks instead of showing 404
100
+ --ssl-cert <path> Path to SSL certificate
101
+ --ssl-key <path> Path to SSL private key
102
+ --no-port-switching Do not open a different port if specified one is taken
103
+ -r, --read-only Disable PUT/DELETE methods (like npx serve)
104
+ --auth <credentials> Enable basic auth (user:pass)
105
+ --solid Enable full Solid protocol features
106
+ -q, --quiet Suppress all output
107
+ -h, --help Display help
108
+ ```
109
+
110
+ ## Comparison with serve
111
+
112
+ | Feature | serve | servejss |
113
+ |---------|-------|---------|
114
+ | Static file serving | ✅ | ✅ |
115
+ | Directory listings | ✅ | ✅ |
116
+ | CORS | ✅ | ✅ |
117
+ | SPA mode | ✅ | ✅ |
118
+ | Custom port | ✅ | ✅ |
119
+ | Auto port switching | ✅ | ✅ |
120
+ | SSL/TLS | ✅ | ✅ |
121
+ | **PUT (create/update)** | ❌ | ✅ |
122
+ | **DELETE** | ❌ | ✅ |
123
+ | **ETags** | ❌ | ✅ |
124
+ | **Conditional requests** | ❌ | ✅ |
125
+ | **Upgrade to Solid** | ❌ | ✅ |
126
+
127
+ ## Advanced Features
128
+
129
+ ### Conditional Requests
130
+
131
+ servejss supports ETags for efficient caching and safe concurrent updates:
132
+
133
+ ```bash
134
+ # Get a file with its ETag
135
+ curl -i http://localhost:3000/file.txt
136
+ # Returns: ETag: "a1b2c3"
137
+
138
+ # Only fetch if changed
139
+ curl -H 'If-None-Match: "a1b2c3"' http://localhost:3000/file.txt
140
+ # Returns: 304 Not Modified (if unchanged)
141
+
142
+ # Safe update (fails if file changed since you read it)
143
+ curl -X PUT -H 'If-Match: "a1b2c3"' -d "new content" http://localhost:3000/file.txt
144
+ ```
145
+
146
+ ### Upgrade to Solid
147
+
148
+ servejss is powered by [JSS (JavaScript Solid Server)](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer). Enable full Solid protocol support:
149
+
150
+ ```bash
151
+ servejss --solid
152
+ ```
153
+
154
+ This enables:
155
+ - Solid-OIDC authentication
156
+ - Web Access Control (WAC)
157
+ - Linked Data support (Turtle, JSON-LD)
158
+ - WebID profiles
159
+
160
+ ## Use Cases
161
+
162
+ ### Local Development Server
163
+ ```bash
164
+ # Serve your project with write support for uploads
165
+ cd my-project
166
+ servejss
167
+ ```
168
+
169
+ ### Quick File Sharing on LAN
170
+ ```bash
171
+ # Share files with devices on your network
172
+ servejss --read-only ~/shared-files
173
+ ```
174
+
175
+ ### REST API Testing
176
+ ```bash
177
+ # Mock a simple REST backend
178
+ servejss ./mock-data
179
+ ```
180
+
181
+ ### WebDAV Alternative
182
+ ```bash
183
+ # Lightweight file sync server
184
+ servejss --auth user:pass ~/sync
185
+ ```
186
+
187
+ ## License
188
+
189
+ MIT
190
+
191
+ ## Related Projects
192
+
193
+ - [JSS](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer) - Full Solid server
194
+ - [serve](https://github.com/vercel/serve) - Static file serving (read-only)