javascript-solid-server 0.0.200 → 0.0.202

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.
package/MAINTAINERS.md ADDED
@@ -0,0 +1,29 @@
1
+ # Maintainers
2
+
3
+ JSS is maintained by a small group with commit access, working in the open.
4
+ Decisions are recorded in issues and PRs.
5
+
6
+ ## Current maintainers
7
+
8
+ | Maintainer | GitHub | Focus |
9
+ |---|---|---|
10
+ | Melvin Carvalho | [@melvincarvalho](https://github.com/melvincarvalho) | Project lead; substrate, releases |
11
+ | John O'Hare | [@jjohare](https://github.com/jjohare) | (onboarding) |
12
+
13
+ See [.github/CODEOWNERS](.github/CODEOWNERS) for path-level review routing.
14
+
15
+ ## Process
16
+
17
+ Workflow, code style, and AI-assistance disclosure are covered in
18
+ [CONTRIBUTING.md](CONTRIBUTING.md). Maintainers follow the same workflow
19
+ as other contributors (issue → branch → PR → review → merge).
20
+
21
+ ## Becoming a maintainer
22
+
23
+ By invitation of an existing maintainer, after demonstrated substantive
24
+ contribution. No formal vote; existing maintainers make the call and
25
+ update this file.
26
+
27
+ ## Security
28
+
29
+ Security disclosures: use [GitHub private security advisories](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/security/advisories/new).
package/README.md CHANGED
@@ -145,6 +145,10 @@ Full options: [docs/configuration.md](docs/configuration.md)
145
145
  npm test
146
146
  ```
147
147
 
148
+ ## Maintainers
149
+
150
+ JSS is maintained by [@melvincarvalho](https://github.com/melvincarvalho) and [@jjohare](https://github.com/jjohare). See [MAINTAINERS.md](MAINTAINERS.md).
151
+
148
152
  ## License
149
153
 
150
154
  Licensed under [AGPL-3.0](./LICENSE).
package/bin/jss.js CHANGED
@@ -87,8 +87,8 @@ program
87
87
  .option('-c, --config <file>', 'Config file path')
88
88
  .option('--ssl-key <path>', 'Path to SSL private key (PEM)')
89
89
  .option('--ssl-cert <path>', 'Path to SSL certificate (PEM)')
90
- .option('--multiuser', 'Enable multi-user mode')
91
- .option('--no-multiuser', 'Disable multi-user mode')
90
+ .option('--multi-user', 'Enable multi-user mode')
91
+ .option('--no-multi-user', 'Disable multi-user mode')
92
92
  .option('--conneg', 'Enable content negotiation (Turtle support)')
93
93
  .option('--no-conneg', 'Disable content negotiation')
94
94
  .option('--notifications', 'Enable WebSocket notifications')
@@ -159,6 +159,12 @@ program
159
159
  .option('--print-config', 'Print configuration and exit')
160
160
  .action(async (options) => {
161
161
  try {
162
+ // Normalize --multi-user (Commander camelCase: multiUser) to internal key
163
+ if (options.multiUser !== undefined) {
164
+ options.multiuser = options.multiUser;
165
+ delete options.multiUser;
166
+ }
167
+
162
168
  const config = await loadConfig(options, options.config);
163
169
 
164
170
  // Set DATA_ROOT env var so all modules use the same data directory
package/docs/mcp.md CHANGED
@@ -82,6 +82,79 @@ Both `SKILL.md` (Anthropic markdown format) and `SKILL.jsonld` (typed JSON-LD de
82
82
 
83
83
  Pod-resident docs (`/docs/`, `/public/apps/<name>/docs/`) are reachable via the regular CRUD tools — no separate surface.
84
84
 
85
+ ### ACL editing (#496)
86
+
87
+ The most common owner operation is delegating an agent access to a resource. The MCP server exposes ACL editing as first-class tools so bots don't need to hand-roll JSON-LD.
88
+
89
+ | Tool | Effect | WAC check |
90
+ |---|---|---|
91
+ | `read_acl` | Return the ACL for a resource as a structured list (agents, agentClasses, modes, isDefault) | Control on resource |
92
+ | `write_acl` | Persist a structured ACL to the resource's `.acl` file | Control on resource |
93
+
94
+ ```json
95
+ // write_acl arguments
96
+ {
97
+ "path": "/private/notes/",
98
+ "authorizations": [
99
+ {
100
+ "agents": ["did:nostr:abc...", "https://alice.example.com/profile#me"],
101
+ "modes": ["Read", "Append"],
102
+ "isDefault": true
103
+ },
104
+ {
105
+ "agentClasses": ["acl:AuthenticatedAgent"],
106
+ "modes": ["Read"]
107
+ }
108
+ ]
109
+ }
110
+ ```
111
+
112
+ The structured form abstracts away JSON-LD shape (`acl:agent` vs `acl:agentClass`, mode URI prefixes, `acl:default` propagation). New WAC vocabulary additions extend the structure without breaking existing bots.
113
+
114
+ ### Subscribe — live change notifications (#494)
115
+
116
+ `subscribe` is a streaming tool. The response switches to SSE (`text/event-stream`) and emits MCP notifications as resources change. WAC-filtered per event so subscribers only see resources they have Read access to.
117
+
118
+ | Tool | Effect |
119
+ |---|---|
120
+ | `subscribe` | Stream resource_changed events for a container subtree or specific path |
121
+
122
+ ```bash
123
+ curl -N http://localhost:4443/mcp \
124
+ -H "Content-Type: application/json" \
125
+ -H "Authorization: Bearer $TOKEN" \
126
+ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"subscribe","arguments":{"path":"/forum/channels/general/"}}}'
127
+ ```
128
+
129
+ Events arrive as:
130
+ ```
131
+ event: notification
132
+ data: {"jsonrpc":"2.0","method":"notifications/tool_event","params":{"tool":"subscribe","event":{"type":"resource_changed","path":"/forum/channels/general/abc.jsonld"}}}
133
+ ```
134
+
135
+ For chat-style bots, replace polling with `subscribe` and react to events as they land.
136
+
137
+ ### Federation — bot-to-bot (#495)
138
+
139
+ `call_remote_pod` lets a bot on this pod invoke MCP tools on another pod. WAC-gated on both ends; depth-capped at 3 hops.
140
+
141
+ | Tool | Effect | Gating |
142
+ |---|---|---|
143
+ | `call_remote_pod` | Forward an MCP `tools/call` to another pod | Caller needs acl:Write on `<their-pod>/private/federation/` on this pod |
144
+
145
+ ```json
146
+ {
147
+ "pod_url": "https://alice.example.com",
148
+ "tool": "read_resource",
149
+ "arguments": { "path": "/public/notes/shared.md" },
150
+ "auth": { "type": "bearer", "token": "..." }
151
+ }
152
+ ```
153
+
154
+ To delegate outbound federation to a specific agent, grant them `acl:Write` on your `/private/federation/` container. Owners control which agents can initiate calls; remote pods control what they expose.
155
+
156
+ Foreign WebIDs (identities hosted on other pods) cannot initiate federation from this pod — there's no local path for the gate to live at. Multi-pod federation chains compose by hopping between pods, each gated locally.
157
+
85
158
  ### Introspection
86
159
 
87
160
  | Tool | Returns |
@@ -98,13 +171,47 @@ http://localhost:4443/mcp
98
171
 
99
172
  For authenticated access, configure the client to send `Authorization: Bearer <token>`. Tokens come from `POST /idp/credentials` (username/password) or from any compatible OIDC/DPoP flow.
100
173
 
174
+ ## Footguns
175
+
176
+ A short list of real gotchas to know about, learned from live-fire use:
177
+
178
+ ### Use absolute WebIDs in `write_acl` agents
179
+
180
+ The `agents` array in a `write_acl` authorization is interpreted as a list of URIs. Relative paths (e.g. `../profile/card.jsonld#me`) resolve against the **.acl file's URL**, not the pod root — and the .acl URL changes depending on which resource the ACL applies to. Two pitfalls:
181
+
182
+ ```json
183
+ // Pod owner WebID: http://example.com/profile/card.jsonld#me
184
+ // Writing this ACL to /public/forum/.acl:
185
+ {
186
+ "agents": ["../profile/card.jsonld#me"], // wrong — resolves to /public/profile/card.jsonld#me
187
+ "agents": ["./profile/card.jsonld#me"], // wrong — resolves to /public/forum/profile/card.jsonld#me
188
+ "agents": ["/profile/card.jsonld#me"], // right — absolute path, resolves to /profile/card.jsonld#me
189
+ "agents": ["http://example.com/profile/card.jsonld#me"] // right — absolute URL, host-portable
190
+ }
191
+ ```
192
+
193
+ **Always use absolute WebID URLs unless you know exactly what relative-URL resolution will give you.** Absolute URLs also make the ACL portable across hostnames.
194
+
195
+ ### `write_acl` will refuse if you'd lock yourself out
196
+
197
+ If the proposed ACL doesn't grant `Control` to the caller (typically a relative-URL mistake), `write_acl` refuses with an explanatory error. This is a safety, not a permission check — it's stopping you from breaking your own access.
198
+
199
+ If you really want to transfer ownership (remove your own access), do it in two steps:
200
+
201
+ 1. First `write_acl` granting Control to the new owner *in addition to* yourself
202
+ 2. Then the new owner calls `write_acl` removing you
203
+
204
+ ### Subscribe over long-running connections needs a keep-alive client
205
+
206
+ The `subscribe` tool keeps an HTTP+SSE connection open indefinitely. Some HTTP clients, proxies, or load balancers will time out idle streams. If you're subscribing for hours, ensure your client handles SSE reconnect (most do; raw `curl` does not).
207
+
101
208
  ## What's not included (yet)
102
209
 
103
- The first cut ships CRUD, ACL-as-resource (you can read/write `.acl` files via the regular tools), skills, docs, and introspection. Deferred:
210
+ The current cut ships CRUD, structured ACL editing, subscribe, federation, skills, docs, and introspection. Deferred:
104
211
 
105
212
  - **`update_resource` (PATCH)** — SPARQL Update / N3 patches. Read-modify-write through the CRUD tools is the workaround.
106
- - **`subscribe`** — wrap JSS's WebSocket notifications as MCP events over SSE. Today, agents can `read_resource` + poll.
107
- - **`call_remote_pod`** — federation primitive for bot-to-bot. Today, an agent can talk to two pods by registering both as MCP servers in its client.
213
+ - **Discovery layer** — no DNS SRV / Solid Type Index entry for "this pod offers MCP". Owners share URLs explicitly today.
214
+ - **Pod-resident federation credentials** — every `call_remote_pod` carries its own auth. A vault for storing remote-pod credentials is a separate security surface worth its own design pass.
108
215
 
109
216
  These are tracked as follow-ups on issue #490.
110
217
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "javascript-solid-server",
3
- "version": "0.0.200",
3
+ "version": "0.0.202",
4
4
  "description": "A minimal, fast Solid server",
5
5
  "main": "src/index.js",
6
6
  "type": "module",
package/src/mcp/index.js CHANGED
@@ -23,7 +23,7 @@ import {
23
23
  rpcResult,
24
24
  rpcError
25
25
  } from './protocol.js';
26
- import { listToolsForRpc, callTool } from './tools.js';
26
+ import { listToolsForRpc, callTool, TOOLS } from './tools.js';
27
27
  import { getWebIdFromRequestAsync } from '../auth/token.js';
28
28
 
29
29
  const ALLOWED_METHODS = new Set([
@@ -84,6 +84,75 @@ async function dispatch(msg, ctx) {
84
84
  return rpcError(id, RPC_ERRORS.METHOD_NOT_FOUND, `unhandled method: ${method}`);
85
85
  }
86
86
 
87
+ function isStreamingToolCall(body) {
88
+ return body
89
+ && body.method === 'tools/call'
90
+ && body.params?.name
91
+ && TOOLS[body.params.name]
92
+ // Sniff: invoke the handler synchronously so we can detect the
93
+ // `{ stream: true, init, run }` shape. Streaming tools must be
94
+ // pure-synchronous in their shape-decision (no awaits before
95
+ // returning the stream descriptor).
96
+ && (() => {
97
+ try {
98
+ // We can't safely call the handler without a ctx, so we just
99
+ // rely on the tool name being in our streaming-tools set.
100
+ return STREAMING_TOOLS.has(body.params.name);
101
+ } catch { return false; }
102
+ })();
103
+ }
104
+
105
+ const STREAMING_TOOLS = new Set(['subscribe']);
106
+
107
+ async function handleStreamingTool(request, reply, body, ctx) {
108
+ const tool = TOOLS[body.params.name];
109
+ let descriptor;
110
+ try {
111
+ descriptor = tool.handler(body.params.arguments || {}, ctx);
112
+ } catch (e) {
113
+ reply.code(500);
114
+ reply.header('Content-Type', 'application/json');
115
+ return rpcError(body.id, RPC_ERRORS.INTERNAL_ERROR, e.message);
116
+ }
117
+ if (!descriptor || descriptor.stream !== true) {
118
+ // Tool decided not to stream after all — emit single-shot response
119
+ reply.header('Content-Type', 'application/json');
120
+ return rpcResult(body.id, descriptor);
121
+ }
122
+
123
+ // Switch to SSE
124
+ reply.raw.writeHead(200, {
125
+ 'Content-Type': 'text/event-stream',
126
+ 'Cache-Control': 'no-cache, no-transform',
127
+ 'Connection': 'keep-alive',
128
+ 'X-Accel-Buffering': 'no'
129
+ });
130
+
131
+ const controller = new AbortController();
132
+ request.raw.on('close', () => controller.abort());
133
+
134
+ const sendEvent = (payload) => {
135
+ if (controller.signal.aborted) return;
136
+ const note = {
137
+ jsonrpc: '2.0',
138
+ method: 'notifications/tool_event',
139
+ params: { tool: body.params.name, event: payload }
140
+ };
141
+ reply.raw.write(`event: notification\ndata: ${JSON.stringify(note)}\n\n`);
142
+ };
143
+
144
+ try {
145
+ const initial = await descriptor.init();
146
+ if (initial) sendEvent(initial);
147
+ await descriptor.run(sendEvent, controller.signal);
148
+ } catch (e) {
149
+ sendEvent({ type: 'error', message: e.message });
150
+ } finally {
151
+ if (!controller.signal.aborted) reply.raw.end();
152
+ }
153
+ return reply;
154
+ }
155
+
87
156
  /**
88
157
  * Register the MCP plugin with Fastify.
89
158
  */
@@ -99,11 +168,21 @@ export async function mcpPlugin(fastify, _options) {
99
168
  // null webId means "anonymous"; WAC will treat it accordingly.
100
169
  const { webId } = await getWebIdFromRequestAsync(request).catch(() => ({ webId: null }));
101
170
 
171
+ // Federation depth (used by call_remote_pod to enforce the cap)
172
+ const depthHdr = request.headers['mcp-federation-depth'];
173
+ const federationDepth = depthHdr ? parseInt(depthHdr, 10) || 0 : 0;
174
+
102
175
  const ctx = {
103
176
  webId: webId || null,
104
- origin: originOf(request)
177
+ origin: originOf(request),
178
+ federationDepth
105
179
  };
106
180
 
181
+ // Streaming tool? Hand off to SSE handler.
182
+ if (!Array.isArray(body) && isStreamingToolCall(body)) {
183
+ return handleStreamingTool(request, reply, body, ctx);
184
+ }
185
+
107
186
  // Batch support (array of requests)
108
187
  if (Array.isArray(body)) {
109
188
  const out = [];