javascript-solid-server 0.0.191 → 0.0.193

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "javascript-solid-server",
3
- "version": "0.0.191",
3
+ "version": "0.0.193",
4
4
  "description": "A minimal, fast Solid server",
5
5
  "main": "src/index.js",
6
6
  "type": "module",
@@ -24,11 +24,11 @@
24
24
  "benchmark": "node benchmark.js"
25
25
  },
26
26
  "dependencies": {
27
- "@noble/curves": "^1.2.0",
28
- "@noble/hashes": "^1.3.2",
29
27
  "@fastify/middie": "^8.3.3",
30
28
  "@fastify/rate-limit": "^9.1.0",
31
29
  "@fastify/websocket": "^8.3.1",
30
+ "@noble/curves": "^1.2.0",
31
+ "@noble/hashes": "^1.3.2",
32
32
  "@simplewebauthn/server": "^13.2.2",
33
33
  "bcryptjs": "^3.0.3",
34
34
  "commander": "^14.0.2",
@@ -38,7 +38,8 @@
38
38
  "microfed": "^0.0.14",
39
39
  "n3": "^1.26.0",
40
40
  "oidc-provider": "^9.6.0",
41
- "sql.js": "^1.13.0"
41
+ "sql.js": "^1.13.0",
42
+ "tar-stream": "^3.2.0"
42
43
  },
43
44
  "engines": {
44
45
  "node": ">=18.0.0"
@@ -0,0 +1,49 @@
1
+ /**
2
+ * Shared cookie helpers for the IdP module.
3
+ *
4
+ * JSS doesn't register @fastify/cookie, so we emit Set-Cookie headers
5
+ * directly. oidc-provider sets four session cookies (_session,
6
+ * _session.sig, _session.legacy, _session.legacy.sig); all four must
7
+ * be expired together to fully clear the browser's session state.
8
+ */
9
+
10
+ const SESSION_COOKIE_NAMES = [
11
+ '_session',
12
+ '_session.sig',
13
+ '_session.legacy',
14
+ '_session.legacy.sig',
15
+ ];
16
+
17
+ function buildExpiredHeaders(secure) {
18
+ const attrs = 'Path=/; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; HttpOnly; SameSite=Lax'
19
+ + (secure ? '; Secure' : '');
20
+ return SESSION_COOKIE_NAMES.map((name) => `${name}=; ${attrs}`);
21
+ }
22
+
23
+ /**
24
+ * Expire oidc-provider session cookies on a Fastify reply.
25
+ *
26
+ * Used by account deletion (credentials.js) and account switching
27
+ * (interactions.js) to prevent stale session references from crashing
28
+ * oidc-provider's consent check (#452).
29
+ *
30
+ * @param {object} reply - Fastify reply object
31
+ * @param {object} [request] - Fastify request (used to detect HTTPS)
32
+ */
33
+ export function expireSessionCookies(reply, request) {
34
+ const secure = request?.protocol === 'https' || process.env.NODE_ENV === 'production';
35
+ reply.header('Set-Cookie', buildExpiredHeaders(secure));
36
+ }
37
+
38
+ /**
39
+ * Expire oidc-provider session cookies on a Koa context.
40
+ *
41
+ * Used by renderError in provider.js for stale-session recovery,
42
+ * where the response object is a Koa ctx, not a Fastify reply.
43
+ *
44
+ * @param {object} ctx - Koa context object
45
+ */
46
+ export function expireSessionCookiesKoa(ctx) {
47
+ const secure = ctx.secure || process.env.NODE_ENV === 'production';
48
+ ctx.set('Set-Cookie', buildExpiredHeaders(secure));
49
+ }
@@ -11,6 +11,7 @@ import { authenticate, findByUsername, findByWebId, updatePassword, verifyPasswo
11
11
  import { getJwks } from './keys.js';
12
12
  import { getWebIdFromRequestAsync } from '../auth/token.js';
13
13
  import { accountDeletePage } from './views.js';
14
+ import { expireSessionCookies } from './cookies.js';
14
15
 
15
16
  /**
16
17
  * Handle POST /idp/credentials
@@ -364,6 +365,10 @@ export async function handleDeleteAccount(request, reply, options = {}) {
364
365
  // and rationale (#391 pass 2 / pass 3).
365
366
  const { purged } = await deleteAccountAndOptionallyPurge(request, account, purgeData);
366
367
 
368
+ // Expire OIDC session cookies so the browser doesn't send stale
369
+ // references on the next login attempt (#452).
370
+ expireSessionCookies(reply, request);
371
+
367
372
  reply.header('Cache-Control', 'no-store');
368
373
  reply.header('Pragma', 'no-cache');
369
374
  return {
@@ -547,6 +552,10 @@ export async function handleAccountDeleteForm(request, reply, options = {}) {
547
552
 
548
553
  const { purged } = await deleteAccountAndOptionallyPurge(request, account, purgeData);
549
554
 
555
+ // Expire OIDC session cookies so the browser doesn't send stale
556
+ // references on the next login attempt (#452).
557
+ expireSessionCookies(reply, request);
558
+
550
559
  // If the user asked for a purge but it didn't run (fs.remove threw,
551
560
  // path-relative check rejected, etc.), surface that on the success
552
561
  // page. Account deletion succeeded — don't roll that back — but the
@@ -0,0 +1,547 @@
1
+ /**
2
+ * GET /idp/account/export — self-service pod data download (#353).
3
+ *
4
+ * The export side of the user-rights trio (#351 password change,
5
+ * #352 account delete, this). Authenticated owner downloads a
6
+ * streamed tar.gz of their pod tree + a manifest. End users walk
7
+ * away with what they own without operator help and without
8
+ * shell access.
9
+ *
10
+ * Per the Credible Exit framing (#448), the archive intentionally
11
+ * INCLUDES `/private/privkey.jsonld` when the pod was provisioned
12
+ * with `--provision-keys`. The user's secret IS theirs and must
13
+ * leave with them — refusing would make L4+ identity migration
14
+ * impossible. The endpoint is owner-authenticated; the secret
15
+ * never leaves the WAC perimeter to anyone but the owner.
16
+ *
17
+ * Streaming pipeline: tar.pack → zlib.createGzip → reply. Memory
18
+ * stays constant regardless of pod size; a multi-GB pod doesn't
19
+ * OOM the server.
20
+ *
21
+ * Failure modes:
22
+ * 401 — unauthenticated
23
+ * 403 — caller's WebID has no matching local account record;
24
+ * applies to multi-user (no account for the WebID) and
25
+ * single-user (authenticated WebID is not the seeded owner —
26
+ * e.g. an external Solid-OIDC / LWS-CID identity)
27
+ * 404 — pod directory unexpectedly missing (shouldn't happen for
28
+ * an account with a valid WebID, but caught defensively)
29
+ * 500 — defense-in-depth: podDir resolved to a server-internal
30
+ * name (`.idp` / `.private` / etc.) in non-root-pod mode,
31
+ * meaning account-creation validation has regressed and
32
+ * allowed a reserved username through
33
+ *
34
+ * Cross-account access is structurally impossible: the endpoint
35
+ * takes no target parameter and always scopes to the caller's
36
+ * authenticated WebID. There's no `403 cross-account` failure mode
37
+ * because there's no path to attempt the access in the first place.
38
+ *
39
+ * Out of scope: re-import, cross-server pod migration, periodic
40
+ * scheduled backups, partial / per-resource selection. See #353.
41
+ */
42
+
43
+ import path from 'path';
44
+ import { promises as fsp, constants as fsConstants } from 'fs';
45
+ import crypto from 'crypto';
46
+ import zlib from 'zlib';
47
+ import tar from 'tar-stream';
48
+ import { getWebIdFromRequestAsync } from '../auth/token.js';
49
+ import { findByWebId } from './accounts.js';
50
+
51
+ /**
52
+ * Entries at the data root that are server-internal, not pod data.
53
+ * In single-user *root* pod mode, podDir IS dataRoot — packing it
54
+ * naively would ship server-managed material to the caller. Skip:
55
+ *
56
+ * .idp/ — IDP accounts (passwordHash for every user!) +
57
+ * signing keys (mint tokens for any user) +
58
+ * OIDC adapter state (sessions, refresh tokens)
59
+ * .private/ — pay/Bitcoin keypair + UTXO state (drainable)
60
+ *
61
+ * The pod's *own* /private/ folder (no leading dot) lives at
62
+ * <dataRoot>/private/ in root-pod mode and IS pod data — operator
63
+ * key, etc. — and is INCLUDED.
64
+ *
65
+ * Public namespaces under .well-known/ (webledgers, openid-config,
66
+ * etc.) are reachable by any HTTP client by spec, so they're
67
+ * "pod data" in the sense that they're part of the pod's public
68
+ * surface — included.
69
+ *
70
+ * Named-pod single-user (podDir = <dataRoot>/<name>/) and multi-user
71
+ * (podDir = <dataRoot>/<podName>/) don't hit this code path — the
72
+ * pod tree is already isolated by the path layout.
73
+ *
74
+ * !!! SECURITY-CRITICAL — DO NOT ADD A NEW SERVER-INTERNAL TOP-LEVEL
75
+ * DIRECTORY WITHOUT ALSO ADDING IT HERE AND ADDING A REGRESSION TEST.
76
+ *
77
+ * We use a denylist (not an allowlist of pod-data subdirs) because
78
+ * pod content is open-ended — operators and apps create arbitrary
79
+ * top-level containers, and an allowlist would break Credible Exit
80
+ * by silently dropping legitimate user data. The trade-off: any new
81
+ * server-managed dotfile dir landing at the data root must be added
82
+ * here in the same PR that introduces it. The denylist test in
83
+ * test/idp-export.test.js asserts on the property "no IdP secrets
84
+ * appear in the archive" against on-disk seeded files, so it will
85
+ * regress loudly if a future feature drops a secret-bearing dir at
86
+ * the data root and forgets to update this set.
87
+ */
88
+ const ROOT_POD_EXCLUDE = new Set(['.idp', '.private']);
89
+
90
+ /**
91
+ * Allowlist of account record fields that are safe to include in
92
+ * `account.json`. Defensive: a denylist that strips only
93
+ * `passwordHash` would silently leak any future secret-bearing
94
+ * field added to the account schema (passkey credential records,
95
+ * OIDC client secrets, recovery tokens, etc.).
96
+ *
97
+ * Adding a new field here requires a security review. Passkey
98
+ * credentials are intentionally NOT included — they're device-
99
+ * bound and not portable to a fresh server.
100
+ *
101
+ * !!! TOP-LEVEL ONLY. The allowlist gates only at the first level
102
+ * of the account record. If a future field is itself an
103
+ * object/array (e.g. `oidcClientConfig: { secret: ... }`,
104
+ * `metadata: { recoveryAnswers: [...] }`, etc.), allowlisting the
105
+ * top-level key alone exports the entire nested structure
106
+ * including any secrets. Nested structures need their own scrubbing
107
+ * before being added here, OR they should be projected into a flat
108
+ * shape that excludes the secret-bearing fields.
109
+ */
110
+ const ACCOUNT_EXPORT_FIELDS = [
111
+ 'id', 'webId', 'username', 'email', 'podName', 'createdAt', 'updatedAt',
112
+ 'passwordChangedAt', 'lastLoginAt',
113
+ ];
114
+
115
+ /**
116
+ * Error vocabulary note: 401 uses the OAuth-Bearer-defined
117
+ * `invalid_token` (RFC 6750), while 403/404 use plain HTTP-semantic
118
+ * tokens (`forbidden`, `not_found`). This mixed convention is
119
+ * deliberate and consistent with the rest of `src/idp/` (see
120
+ * credentials.js: 401→`invalid_token`/`invalid_grant`, 403→
121
+ * `forbidden`, 400→`invalid_request`). Aligning to a single
122
+ * vocabulary across the whole IdP surface is its own refactor.
123
+ *
124
+ * @param {object} request - Fastify request
125
+ * @param {object} reply - Fastify reply
126
+ * @param {object} options
127
+ * @param {boolean} [options.singleUser]
128
+ * @param {string|null} [options.singleUserName] - null for root pod,
129
+ * string for /<name>/ pod
130
+ * @param {string} [options.jssVersion] - written into the manifest
131
+ * for forensic / "what server made this" purposes
132
+ */
133
+ export async function handleExportAccount(request, reply, options = {}) {
134
+ // 1. Authenticate caller. Same path as DELETE /idp/account etc.;
135
+ // works with bearer tokens, LWS-CID JWTs, etc. — anything
136
+ // getWebIdFromRequestAsync resolves to a WebID.
137
+ const { webId, error: authError } = await getWebIdFromRequestAsync(request);
138
+ if (!webId) {
139
+ return reply.code(401).send({
140
+ error: 'invalid_token',
141
+ error_description: authError || 'Authentication required',
142
+ });
143
+ }
144
+
145
+ // 2. Resolve the pod tree on disk + the manifest data.
146
+ const dataRoot = process.env.DATA_ROOT || './data';
147
+ let podDir;
148
+ let accountRecord = null;
149
+ let manifest;
150
+ let isRootPod = false;
151
+
152
+ if (options.singleUser) {
153
+ // Single-user: pod is at `/` (root pod) or `/<name>/` based on
154
+ // singleUserName. The seeded IDP account (per
155
+ // seedSingleUserIdpAccount in src/server.js) is the sole owner —
156
+ // an authenticated WebID without a matching local account is
157
+ // some third-party identity (external Solid-OIDC, LWS-CID JWT,
158
+ // etc.), NOT the pod owner, and must not get the operator's
159
+ // /private/privkey.jsonld. The route is only mounted when
160
+ // idpEnabled, so a missing account record means "caller is not
161
+ // the seeded owner" — refuse with the same 403 shape as
162
+ // multi-user.
163
+ //
164
+ // Refuse empty-string / non-string singleUserName explicitly.
165
+ // The previous `!singleUserName` falsy-check silently mapped
166
+ // both '' and null to root-pod, but '' is almost certainly a
167
+ // misconfiguration — an operator who meant root-pod omits the
168
+ // option entirely, and an operator who meant a named pod
169
+ // wouldn't use empty string. WORSE, with `!''`=true the old
170
+ // code took the root-pod branch and applied ROOT_POD_EXCLUDE;
171
+ // a strict null check WITHOUT this refusal would take the
172
+ // named-pod branch with podDir = path.join(dataRoot, '') =
173
+ // dataRoot AND excludeAtRoot = null, silently exporting
174
+ // server-internal `.idp/` and `.private/`. So we explicitly
175
+ // reject the empty-string / non-string case before deciding
176
+ // isRootPod.
177
+ if (
178
+ options.singleUserName !== null &&
179
+ options.singleUserName !== undefined &&
180
+ (typeof options.singleUserName !== 'string' || options.singleUserName.length === 0)
181
+ ) {
182
+ request.log.error(
183
+ { singleUserName: options.singleUserName },
184
+ 'pod export refused — singleUserName must be null/undefined or a non-empty string',
185
+ );
186
+ return reply.code(500).send({
187
+ error: 'server_error',
188
+ error_description: 'Invalid singleUserName configuration',
189
+ });
190
+ }
191
+ isRootPod = options.singleUserName == null;
192
+ podDir = isRootPod
193
+ ? dataRoot
194
+ : path.join(dataRoot, options.singleUserName);
195
+
196
+ accountRecord = await findByWebId(webId);
197
+ if (!accountRecord) {
198
+ return reply.code(403).send({
199
+ error: 'forbidden',
200
+ error_description:
201
+ 'Authenticated WebID does not match the single-user account',
202
+ });
203
+ }
204
+ // Defense-in-depth: in named-pod single-user mode, the seeded
205
+ // accountRecord.podName MUST equal options.singleUserName (the
206
+ // CLI option that derives podDir). If seedSingleUserIdpAccount
207
+ // ever drifted, manifest.podName (read from accountRecord) would
208
+ // advertise X while the pod tree is read from <dataRoot>/Y.
209
+ // Refuse with 500 so a seeding regression fails loudly rather
210
+ // than producing a silently mismatched archive.
211
+ //
212
+ // Skipped in root-pod mode where podDir is dataRoot regardless
213
+ // of the seeded podName (which is intentionally 'me' for OIDC
214
+ // identity, not a path component).
215
+ if (!isRootPod && accountRecord.podName !== options.singleUserName) {
216
+ request.log.error(
217
+ {
218
+ seededPodName: accountRecord.podName,
219
+ cliSingleUserName: options.singleUserName,
220
+ },
221
+ 'pod export refused — accountRecord.podName disagrees with ' +
222
+ 'singleUserName; seedSingleUserIdpAccount regression?',
223
+ );
224
+ return reply.code(500).send({
225
+ error: 'server_error',
226
+ error_description: 'Pod identity inconsistent with on-disk layout',
227
+ });
228
+ }
229
+ // manifest.podName mirrors the IDP account's podName (the OIDC
230
+ // short name) for parity with the multi-user branch — both
231
+ // branches now read podName from accountRecord, so a downstream
232
+ // importer keying on manifest.podName or account.json.podName
233
+ // gets the same answer regardless of server mode. Filesystem
234
+ // layout (root-pod vs /<name>/ pod) is conveyed by `mode` +
235
+ // the seeded podName ('me' for root-pod, singleUserName otherwise).
236
+ manifest = {
237
+ webId: accountRecord.webId,
238
+ username: accountRecord.username,
239
+ email: accountRecord.email,
240
+ podName: accountRecord.podName,
241
+ mode: 'single-user',
242
+ createdAt: accountRecord.createdAt,
243
+ exportedAt: new Date().toISOString(),
244
+ jssVersion: options.jssVersion ?? 'unknown',
245
+ };
246
+ } else {
247
+ // Multi-user: caller's WebID must resolve to an account record
248
+ // on this server. Same 403 shape as DELETE /idp/account uses
249
+ // when an authenticated WebID has no local account.
250
+ accountRecord = await findByWebId(webId);
251
+ if (!accountRecord) {
252
+ return reply.code(403).send({
253
+ error: 'forbidden',
254
+ error_description: 'No account found for authenticated WebID',
255
+ });
256
+ }
257
+ const podName = accountRecord.podName || accountRecord.username;
258
+ podDir = path.join(dataRoot, podName);
259
+ manifest = {
260
+ webId: accountRecord.webId,
261
+ username: accountRecord.username,
262
+ email: accountRecord.email,
263
+ podName,
264
+ mode: 'multi-user',
265
+ createdAt: accountRecord.createdAt,
266
+ exportedAt: new Date().toISOString(),
267
+ jssVersion: options.jssVersion ?? 'unknown',
268
+ };
269
+ }
270
+
271
+ // Defense-in-depth: in multi-user mode `excludeAtRoot` is null
272
+ // because the pod is at <dataRoot>/<podName>/ (already isolated
273
+ // from server-internal dotfiles by the path layout). But if
274
+ // account-creation validation ever regressed and allowed a
275
+ // username matching `.idp` / `.private`, podDir would resolve to
276
+ // the server-internal directory and the export would happily
277
+ // walk it. Refuse here — account creation rejecting these names
278
+ // is the primary defense; this is the second line.
279
+ if (
280
+ !(options.singleUser && isRootPod) &&
281
+ ROOT_POD_EXCLUDE.has(path.basename(podDir))
282
+ ) {
283
+ request.log.error(
284
+ { podDir, basename: path.basename(podDir) },
285
+ 'export refused — podDir resolved to a server-internal name; ' +
286
+ 'account-creation validation regression?',
287
+ );
288
+ return reply.code(500).send({
289
+ error: 'server_error',
290
+ error_description: 'Pod resolution conflicts with server-internal layout',
291
+ });
292
+ }
293
+
294
+ // Pre-flight the pod directory BEFORE flushing response headers.
295
+ // We do both checks (stat for existence/type, readdir for
296
+ // readability) up front so a first-byte EACCES on the top-level
297
+ // readdir doesn't surface inside the streaming pipeline AFTER
298
+ // reply.send(gzip) has already flushed headers — that would leave
299
+ // the client with a 200 + truncated/empty body instead of a clean
300
+ // 5xx JSON error.
301
+ //
302
+ // 404 vs 500 split:
303
+ // ENOENT/ENOTDIR → 404 (auth was fine, just no pod on disk)
304
+ // anything else (EACCES, EIO, etc.) → 500 (server-side problem)
305
+ //
306
+ // Generic error_descriptions on the wire — echoing the resolved
307
+ // podDir back would leak the operator's filesystem layout. Path
308
+ // stays in the server log via request.log.{warn,error} for
309
+ // operator debugging.
310
+ try {
311
+ const st = await fsp.stat(podDir);
312
+ if (!st.isDirectory()) {
313
+ const err = new Error('not a directory');
314
+ err.code = 'ENOTDIR';
315
+ throw err;
316
+ }
317
+ // Pre-flight readability with `fsp.access(R_OK | X_OK)` rather
318
+ // than a discarded readdir — same effect (catches EACCES on the
319
+ // pod directory) without scanning the whole top-level entry
320
+ // list twice. R_OK gates listing, X_OK gates traversal into
321
+ // subdirectories, both required by the recursive walk.
322
+ await fsp.access(podDir, fsConstants.R_OK | fsConstants.X_OK);
323
+ } catch (err) {
324
+ if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) {
325
+ request.log.warn({ podDir }, 'pod export: podDir missing or not a directory');
326
+ return reply.code(404).send({
327
+ error: 'not_found',
328
+ error_description: 'Pod data not found',
329
+ });
330
+ }
331
+ request.log.error({ err, podDir }, 'pod export: pre-flight failed');
332
+ return reply.code(500).send({
333
+ error: 'server_error',
334
+ error_description: 'Pod data is unreadable',
335
+ });
336
+ }
337
+
338
+ // 3. Set headers and start streaming.
339
+ const slug = sanitizeSlug(webId);
340
+ const isoDate = manifest.exportedAt.replace(/[:.]/g, '-');
341
+ // Short random suffix avoids collisions when a client batches
342
+ // exports — ISO timestamps have only millisecond resolution and
343
+ // two consecutive calls in the same ms would otherwise produce
344
+ // identical filenames that overwrite each other on the client.
345
+ const rand = crypto.randomBytes(3).toString('hex'); // 6 hex chars
346
+ const filename = `jss-export-${slug}-${isoDate}-${rand}.tar.gz`;
347
+
348
+ // sanitizeSlug() restricts the slug to [A-Za-z0-9._-] and isoDate
349
+ // is ISO-8601 with `:`/`.` replaced — both are strict-ASCII safe
350
+ // for the legacy `filename=` form. Also emit `filename*=UTF-8''…`
351
+ // (RFC 5987) so any future non-ASCII slip-through degrades to
352
+ // valid UTF-8 percent-encoding rather than a malformed header.
353
+ const cdValue =
354
+ `attachment; filename="${filename}"; ` +
355
+ `filename*=UTF-8''${encodeURIComponent(filename)}`;
356
+ reply
357
+ .type('application/x-tar+gzip')
358
+ .header('Content-Disposition', cdValue)
359
+ .header('Cache-Control', 'no-store');
360
+
361
+ const pack = tar.pack();
362
+ const gzip = zlib.createGzip();
363
+ pack.pipe(gzip);
364
+
365
+ // Surface stream-level errors. Once response headers are out an
366
+ // EACCES / mid-pack failure can otherwise present as a silently
367
+ // truncated download — the client gets 200 + partial gzip + no
368
+ // error signal. We log on the server side and destroy the
369
+ // pipeline so the client at least sees an aborted transfer rather
370
+ // than a corrupt but seemingly-complete archive.
371
+ // Idempotent: invoked from pack.error, gzip.error, AND the
372
+ // .catch(onStreamError) chained on packExport(...) below.
373
+ // Destroying a stream re-emits 'error', which would re-enter this
374
+ // handler and produce duplicate log lines for one underlying
375
+ // failure. The destroyed-flag short-circuits all subsequent calls
376
+ // so a single failure logs once.
377
+ const onStreamError = (err) => {
378
+ if (gzip.destroyed || pack.destroyed) return;
379
+ request.log.error({ err }, 'pod export stream error');
380
+ pack.destroy(err);
381
+ gzip.destroy(err);
382
+ };
383
+ pack.on('error', onStreamError);
384
+ gzip.on('error', onStreamError);
385
+
386
+ // Client disconnect handler. Without this, walkAndPack keeps
387
+ // reading every file in the pod, opening file descriptors, and
388
+ // pushing into a gzip whose downstream socket is gone. For a
389
+ // multi-GB pod that's wasted IO + fds until the walk finishes.
390
+ // Destroying both ends short-circuits the walk via stream error
391
+ // propagation; the request.log captures the abort for diagnostics.
392
+ //
393
+ // `responseFinished` closes a race window. We can't gate on
394
+ // `packExport`'s resolution: that fires when `pack.finalize()`
395
+ // returns, which is "we're done WRITING into the pipeline" — not
396
+ // "the client has received the bytes". For a multi-GB gzipped
397
+ // response over a slow link, the gap between those two events
398
+ // can be substantial, and a real client disconnect during the
399
+ // final flush would be silently swallowed (close handler
400
+ // short-circuits on a flag set too early). Gate instead on
401
+ // `reply.raw.on('finish')` — Node emits 'finish' when the last
402
+ // byte has been flushed to the OS socket buffer, AFTER which a
403
+ // 'close' event means "client disconnected after we were done"
404
+ // and is correctly ignored. Before 'finish', a 'close' is a
405
+ // genuine mid-stream disconnect and gets logged + cleans up.
406
+ let responseFinished = false;
407
+ reply.raw.on('finish', () => { responseFinished = true; });
408
+ reply.raw.on('close', () => {
409
+ if (responseFinished || reply.raw.writableEnded) return;
410
+ request.log.warn('pod export client disconnected mid-stream');
411
+ pack.destroy(new Error('client disconnected'));
412
+ gzip.destroy(new Error('client disconnected'));
413
+ });
414
+
415
+ // Pump in the background; entries are added asynchronously below.
416
+ // The root-pod denylist is wired in so single-user-root-pod mode
417
+ // doesn't ship .idp/ (accounts + signing keys + OIDC state).
418
+ // `.catch(onStreamError)` attaches a rejection handler so there's
419
+ // no unhandled-rejection risk; the pipeline runs detached.
420
+ packExport({
421
+ pack,
422
+ podDir,
423
+ manifest,
424
+ accountRecord,
425
+ excludeAtRoot: (options.singleUser && isRootPod) ? ROOT_POD_EXCLUDE : null,
426
+ }).catch(onStreamError);
427
+
428
+ return reply.send(gzip);
429
+ }
430
+
431
+ async function packExport({ pack, podDir, manifest, accountRecord, excludeAtRoot }) {
432
+ // Manifest first so consumers can read the shape before deciding
433
+ // whether to keep streaming the (potentially large) pod tree.
434
+ await addEntry(pack, 'jss-export/manifest.json',
435
+ Buffer.from(JSON.stringify(manifest, null, 2), 'utf8'));
436
+
437
+ // Account record — allowlisted fields only. Both branches in
438
+ // handleExportAccount now refuse with 403 when accountRecord is
439
+ // null, so by the time we get here the record is always defined
440
+ // and account.json is always emitted.
441
+ const safeAccount = {};
442
+ for (const key of ACCOUNT_EXPORT_FIELDS) {
443
+ if (accountRecord[key] !== undefined) safeAccount[key] = accountRecord[key];
444
+ }
445
+ await addEntry(pack, 'jss-export/account.json',
446
+ Buffer.from(JSON.stringify(safeAccount, null, 2), 'utf8'));
447
+
448
+ // Pod tree. The first-level filter (`excludeAtRoot`) is what
449
+ // prevents single-user-root-pod mode from leaking .idp/.
450
+ await walkAndPack(pack, podDir, 'jss-export/pod', excludeAtRoot);
451
+
452
+ pack.finalize();
453
+ }
454
+
455
+ /**
456
+ * Recursively pack `dir` into `pack` under the tar prefix `tarBase`.
457
+ *
458
+ * @param {Set<string>|null} excludeAtRoot - first-level names to skip
459
+ * (applied only at the top of the walk; deeper entries pass freely).
460
+ * Set to `ROOT_POD_EXCLUDE` in single-user-root-pod mode where
461
+ * podDir is the data root and server-internal dotfiles live next
462
+ * to pod data.
463
+ */
464
+ async function walkAndPack(pack, dir, tarBase, excludeAtRoot = null) {
465
+ const entries = await fsp.readdir(dir, { withFileTypes: true });
466
+ for (const dirent of entries) {
467
+ if (excludeAtRoot && excludeAtRoot.has(dirent.name)) {
468
+ // Top-level server-internal dir — never appears in any export.
469
+ continue;
470
+ }
471
+ const fullPath = path.join(dir, dirent.name);
472
+ const tarPath = `${tarBase}/${dirent.name}`;
473
+ if (dirent.isDirectory()) {
474
+ // Emit an explicit directory entry so empty LDP containers
475
+ // (a container the operator provisioned but hasn't populated)
476
+ // survive a round-trip — preserves the pod's LDP shape on
477
+ // restore. tar requires the trailing slash on directory names.
478
+ await addDirEntry(pack, `${tarPath}/`);
479
+ // No `excludeAtRoot` on recursion — the denylist is first-level only.
480
+ await walkAndPack(pack, fullPath, tarPath, null);
481
+ } else if (dirent.isFile()) {
482
+ // Stream the file into the entry from an *open fd* — opens
483
+ // and stats off the same fd, so a concurrent truncate/grow
484
+ // can't desync `size` from the bytes actually piped. Without
485
+ // this, a stat-then-open dance would TOCTOU on a live pod
486
+ // and produce a corrupt tar that fails extraction.
487
+ const fh = await fsp.open(fullPath, 'r');
488
+ try {
489
+ const st = await fh.stat();
490
+ await new Promise((resolve, reject) => {
491
+ const entry = pack.entry(
492
+ { name: tarPath, size: st.size, mode: st.mode & 0o777 },
493
+ (err) => err ? reject(err) : resolve(),
494
+ );
495
+ const rs = fh.createReadStream({ autoClose: false });
496
+ rs.on('error', reject);
497
+ entry.on('error', reject);
498
+ rs.pipe(entry);
499
+ });
500
+ } finally {
501
+ await fh.close();
502
+ }
503
+ }
504
+ // Symlinks, sockets, FIFOs, etc. are intentionally skipped —
505
+ // `dirent.isFile()` is false for those, even when the symlink
506
+ // points at a regular file. Out of scope for "downloadable pod
507
+ // data" and would complicate restore semantics.
508
+ }
509
+ }
510
+
511
+ /**
512
+ * Add a tar directory entry. `tar-stream` distinguishes by name
513
+ * suffix (`/`) and explicit `type: 'directory'`.
514
+ */
515
+ function addDirEntry(pack, name) {
516
+ return new Promise((resolve, reject) => {
517
+ pack.entry({ name, type: 'directory', size: 0 }, (err) => {
518
+ if (err) reject(err);
519
+ else resolve();
520
+ });
521
+ });
522
+ }
523
+
524
+ /**
525
+ * Add a single in-memory entry to the tar pack. Promisified wrapper
526
+ * around `pack.entry({...}, callback)` so the caller can await.
527
+ */
528
+ function addEntry(pack, name, content) {
529
+ return new Promise((resolve, reject) => {
530
+ pack.entry({ name, size: content.length }, content, (err) => {
531
+ if (err) reject(err);
532
+ else resolve();
533
+ });
534
+ });
535
+ }
536
+
537
+ /**
538
+ * Squash a WebID into something safe for a download filename.
539
+ * Just enough to be useful as a hint; doesn't need to round-trip.
540
+ */
541
+ function sanitizeSlug(webId) {
542
+ return webId
543
+ .replace(/^https?:\/\//, '')
544
+ .replace(/[#?].*$/, '')
545
+ .replace(/[^A-Za-z0-9._-]+/g, '_')
546
+ .slice(0, 80) || 'pod';
547
+ }