javascript-solid-server 0.0.212 → 0.0.213

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.
@@ -350,6 +350,40 @@ When `--invite-only` is enabled:
350
350
 
351
351
  Invite codes are stored in `.server/invites.json` in your data directory.
352
352
 
353
+ ## Application Mount Points (appPaths)
354
+
355
+ Programmatic compositions can mount whole applications beside the pod
356
+ (the plugin-zero pattern from
357
+ [#206](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/206)):
358
+
359
+ ```js
360
+ import { createServer } from 'javascript-solid-server/src/server.js';
361
+
362
+ const fastify = createServer({ appPaths: ['/myapp'] });
363
+ // Register both forms: fastify wildcards don't match the bare prefix.
364
+ fastify.all('/myapp', myAppHandler);
365
+ fastify.all('/myapp/*', myAppHandler); // the app owns auth below its prefix
366
+ await fastify.listen({ port: 4443 });
367
+ ```
368
+
369
+ Requests at or below an app path skip the WAC authorization hook — the
370
+ application authenticates and authorizes its own traffic, exactly like the
371
+ built-in `/storage/` and `/db/` routes. Everything outside the declared
372
+ prefixes keeps full WAC enforcement. Entries must start with `/` and be
373
+ longer than `/`; anything else is ignored.
374
+
375
+ Because the WAC hook is also what populates `request.webId`, requests under
376
+ an app path never carry it — don't rely on `request.webId` in app handlers.
377
+ Resolve identity yourself, e.g. with `getWebIdFromRequestAsync(request)`
378
+ from `src/auth/token.js` (a stable public accessor is tracked in
379
+ [#584](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/584)).
380
+
381
+ See [#582](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/582)
382
+ for the design discussion and
383
+ [melvincarvalho/tideholm](https://github.com/melvincarvalho/tideholm/tree/gh-pages/jss-plugin)
384
+ for a complete example (a multiplayer game where pod WebIDs are the player
385
+ accounts).
386
+
353
387
  ## Storage Quotas
354
388
 
355
389
  Limit storage per pod to prevent abuse and manage resources:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "javascript-solid-server",
3
- "version": "0.0.212",
3
+ "version": "0.0.213",
4
4
  "description": "A minimal, fast Solid server",
5
5
  "main": "src/index.js",
6
6
  "type": "module",
package/src/server.js CHANGED
@@ -107,6 +107,16 @@ export function createServer(options = {}) {
107
107
  // Tunnel proxy is OFF by default
108
108
  const tunnelEnabled = options.tunnel ?? false;
109
109
  const tunnelPath = options.tunnelPath ?? '/.tunnel';
110
+ // Application mount points (plugin seam, #206): URL prefixes owned by
111
+ // registered apps (e.g. a game mounted at /tideholm). Requests below an
112
+ // app path skip the WAC hook — the app owns authentication and
113
+ // authorization under its prefix, like /storage/ and /db/ already do.
114
+ const appPaths = Array.isArray(options.appPaths)
115
+ ? options.appPaths
116
+ .filter((p) => typeof p === 'string')
117
+ .map((p) => p.trim().replace(/\/+$/, '')) // '/myapp/' matches like '/myapp'
118
+ .filter((p) => p.startsWith('/') && p.length > 1)
119
+ : [];
110
120
  // ActivityPub federation is OFF by default
111
121
  const activitypubEnabled = options.activitypub ?? false;
112
122
  const apUsername = options.apUsername ?? 'me';
@@ -719,6 +729,7 @@ export function createServer(options = {}) {
719
729
  (webrtcEnabled && (request.url === webrtcPath || request.url.startsWith(webrtcPath + '?'))) ||
720
730
  (terminalEnabled && (request.url === '/.terminal' || request.url.startsWith('/.terminal?'))) ||
721
731
  (tunnelEnabled && (request.url === tunnelPath || request.url.startsWith(tunnelPath + '?') || request.url.startsWith('/tunnel/'))) ||
732
+ appPaths.some(p => request.url === p || request.url.startsWith(p + '/') || request.url.startsWith(p + '?')) ||
722
733
  mashlibPaths.some(p => request.url === p || request.url.startsWith(p + '.'))) {
723
734
  return;
724
735
  }
@@ -0,0 +1,151 @@
1
+ /**
2
+ * appPaths — WAC-exempt application mount points (#582).
3
+ *
4
+ * The global WAC preHandler authorizes every URL against pod ACLs and
5
+ * rejects before routes run; the only escapes are its hardcoded prefix
6
+ * list (/storage/, /db, /mcp, …). That means a third-party app plugin
7
+ * registering routes on the returned fastify instance (#206's plugin-zero
8
+ * pattern, e.g. a game mounted at /tideholm) has its POSTs swallowed by
9
+ * WAC with no way to opt out.
10
+ *
11
+ * createServer({ appPaths: ['/myapp'] }) declares URL prefixes owned by
12
+ * registered applications: requests at or below an app path skip the WAC
13
+ * hook, and the app owns authentication and authorization under its
14
+ * prefix — exactly the deal the bundled pseudo-plugins already have.
15
+ *
16
+ * Tests verify the seam end-to-end: an app route mounted on the returned
17
+ * instance receives unauthenticated requests (WAC stays out), sibling LDP
18
+ * paths keep full WAC enforcement, and malformed appPaths entries are
19
+ * dropped rather than becoming accidental holes.
20
+ */
21
+
22
+ import { describe, it, before, after, afterEach } from 'node:test';
23
+ import assert from 'node:assert';
24
+ import { createServer } from '../src/server.js';
25
+ import fs from 'fs-extra';
26
+
27
+ const TEST_DATA_DIR = './test-data-app-paths';
28
+
29
+ let server;
30
+ let baseUrl;
31
+ let originalDataRoot;
32
+
33
+ async function startWith(appPaths) {
34
+ await fs.emptyDir(TEST_DATA_DIR);
35
+ server = createServer({
36
+ logger: false,
37
+ forceCloseConnections: true,
38
+ root: TEST_DATA_DIR,
39
+ appPaths,
40
+ });
41
+ // An app in the #206 plugin-zero shape: routes registered on the returned
42
+ // instance, answering with its own status codes (its own "auth").
43
+ server.all('/myapp', echo);
44
+ server.all('/myapp/*', echo);
45
+ async function echo(request, reply) {
46
+ reply.code(200).send({
47
+ app: true,
48
+ method: request.method,
49
+ url: request.url,
50
+ webId: request.webId ?? null, // hook skipped -> never set
51
+ });
52
+ }
53
+ await server.listen({ port: 0, host: '127.0.0.1' });
54
+ const address = server.server.address();
55
+ baseUrl = `http://127.0.0.1:${address.port}`;
56
+ }
57
+
58
+ describe('appPaths application mount points (#582)', () => {
59
+ before(() => {
60
+ // createServer({ root }) mutates process.env.DATA_ROOT; snapshot so the
61
+ // test dir doesn't leak into later suites.
62
+ originalDataRoot = process.env.DATA_ROOT;
63
+ });
64
+
65
+ afterEach(async () => {
66
+ if (server) {
67
+ await server.close();
68
+ server = null;
69
+ }
70
+ await fs.remove(TEST_DATA_DIR);
71
+ });
72
+
73
+ after(() => {
74
+ if (originalDataRoot === undefined) delete process.env.DATA_ROOT;
75
+ else process.env.DATA_ROOT = originalDataRoot;
76
+ });
77
+
78
+ it('unauthenticated POST below an app path reaches the app handler', async () => {
79
+ await startWith(['/myapp']);
80
+ const res = await fetch(`${baseUrl}/myapp/api/action`, {
81
+ method: 'POST',
82
+ headers: { 'Content-Type': 'application/json' },
83
+ body: JSON.stringify({ hello: 'world' }),
84
+ });
85
+ assert.strictEqual(res.status, 200);
86
+ const body = await res.json();
87
+ assert.strictEqual(body.app, true);
88
+ assert.strictEqual(body.method, 'POST');
89
+ });
90
+
91
+ it('the bare app path and query-string forms are exempt too', async () => {
92
+ await startWith(['/myapp']);
93
+ for (const path of ['/myapp', '/myapp?tab=map']) {
94
+ const res = await fetch(`${baseUrl}${path}`, { method: 'POST' });
95
+ assert.strictEqual(res.status, 200, `${path} should reach the app`);
96
+ }
97
+ });
98
+
99
+ it('the WAC hook never sets request.webId on app-path requests', async () => {
100
+ await startWith(['/myapp']);
101
+ const res = await fetch(`${baseUrl}/myapp/whoami`);
102
+ const body = await res.json();
103
+ assert.strictEqual(body.webId, null);
104
+ });
105
+
106
+ it('sibling LDP paths keep full WAC enforcement', async () => {
107
+ await startWith(['/myapp']);
108
+ // Writing outside the app prefix without auth must still be rejected.
109
+ const res = await fetch(`${baseUrl}/notes.jsonld`, {
110
+ method: 'PUT',
111
+ headers: { 'Content-Type': 'application/ld+json' },
112
+ body: JSON.stringify({ '@id': '', name: 'x' }),
113
+ });
114
+ assert.ok(res.status === 401 || res.status === 403,
115
+ `expected WAC rejection, got ${res.status}`);
116
+ });
117
+
118
+ it('a prefix match is a path-segment match, not a string prefix', async () => {
119
+ await startWith(['/myapp']);
120
+ // /myapplication must NOT be exempt just because it shares characters.
121
+ const res = await fetch(`${baseUrl}/myapplication.jsonld`, {
122
+ method: 'PUT',
123
+ headers: { 'Content-Type': 'application/ld+json' },
124
+ body: JSON.stringify({ '@id': '', name: 'x' }),
125
+ });
126
+ assert.ok(res.status === 401 || res.status === 403,
127
+ `expected WAC rejection, got ${res.status}`);
128
+ });
129
+
130
+ it('trailing-slash entries are normalized, children still exempt', async () => {
131
+ await startWith(['/myapp/']);
132
+ const res = await fetch(`${baseUrl}/myapp/api/action`, { method: 'POST' });
133
+ assert.strictEqual(res.status, 200);
134
+ });
135
+
136
+ it('malformed appPaths entries are dropped, not accidental holes', async () => {
137
+ // No leading slash and bare '/' are both invalid; with them filtered out
138
+ // the route registrations still exist but WAC fires first.
139
+ await startWith(['myapp', '/', '///', ' ']);
140
+ const res = await fetch(`${baseUrl}/myapp/api/action`, { method: 'POST' });
141
+ assert.ok(res.status === 401 || res.status === 403,
142
+ `expected WAC rejection (invalid entries dropped), got ${res.status}`);
143
+ });
144
+
145
+ it('omitting appPaths changes nothing (default off)', async () => {
146
+ await startWith(undefined);
147
+ const res = await fetch(`${baseUrl}/myapp/api/action`, { method: 'POST' });
148
+ assert.ok(res.status === 401 || res.status === 403,
149
+ `expected WAC rejection with no appPaths, got ${res.status}`);
150
+ });
151
+ });