const path = request.url.split('?')[0];

if (path === '/.pods') return false;

if (path === '/idp' || path.startsWith('/idp/') || path.startsWith('/oauth/')) return false;

if (path.startsWith('/.well-known/')) return false;

if (path === '/types/index' || path === '/types/search') return true;

if (/^\/[^/]+\/types\/(index|search)$/.test(path)) return true;

return TRUST_AWARE_WRITE_METHODS.has(request.method);

return {

max: (request) => (request.webId ? authedMax : anonMax),

timeWindow: '1 minute',

keyGenerator: (request) => (request.webId ? `wid:${request.webId}` : `ip:${request.ip}`),

...extra,

};

// Content negotiation is OFF by default - we're a JSON-LD native server

const connegEnabled = options.conneg ?? false;

// Linked Web Storage surface is OFF by default

const lwsEnabled = options.lws ?? false;

// Deployment operator (governance round 2026-07-22): a URI, possibly on

// another pod deployment — config-only on purpose (ownership travels with

// data, operatorship does not). Surfaced, never persisted into tenant data.

// F-3 (final-review fix): validated as an absolute URI before it's

// surfaced — a malformed --lws-provider/JSS_LWS_PROVIDER value must never

// be fatal (warn loud, drop to null; the rest of boot proceeds).

let lwsProviderUri = options.lwsProvider ?? null;

if (lwsProviderUri && !isAbsoluteUri(lwsProviderUri)) {

console.warn(`[lws-pod] --lws-provider / JSS_LWS_PROVIDER is not an absolute URI: ${JSON.stringify(lwsProviderUri)} — ignoring (schema:provider will be omitted)`);

lwsProviderUri = null;

}

// Type Index/Search services are ON by default whenever --lws is on;

// --no-lws-type-index is a per-deployment safety valve to disable just

// the type-aggregation surface without disabling the rest of --lws.

const typeIndexEnabled = lwsEnabled && (options.lwsTypeIndex ?? true);

// Spec §4b: profileIndex/void service pointers live in ONE pod resource

// (--lws-config), read lazily + mtime-cached rather than from two static

// per-service flags — absence is normal at boot (services off, warn once);

// the next request picks up the resource once the publish pipeline writes

// it, no restart needed. ONE instance shared by the HTTP routes below and

// the MCP surface (src/mcp/index.js), so the two views can't diverge.

const podConfig = makePodConfig(storage, lwsEnabled ? (options.lwsConfig ?? null) : null);

// Multi-tenant round (A3, fixed C2): a per-storage resolver ALONGSIDE the

// single podConfig above. C2 (code review): this used to read

// `options.lwsConfig` too — but that flag drives the LEGACY podConfig

// above as a server-root-relative (often absolute) path, e.g.

// `/alice/profiles/pod-config.jsonld`. Reinterpreting the SAME string as

// relative-per-root (podConfigResolver's contract) meant a deployment

// pointing --lws-config at an absolute path got a per-storage lookup of

// `/alice/alice/profiles/pod-config.jsonld` — nonexistent, so every

// per-storage description silently came back with no VoidService/

// ProfileIndex/uriSpaces. Decoupled: podConfigResolver always resolves at

// this FIXED relative convention under each storage root, independent of

// --lws-config. The legacy `podConfig` above (still driving the origin

// /.well-known/void 303 rail) is untouched — a per-storage

// VoidService (services round, R7) now advertises the SAME per-storage

// voidPath directly, so the two can name different targets in a

// mixed-mode deployment (recorded, not reconciled — spec §5).

const PER_STORAGE_CONFIG_REL = 'profiles/pod-config.jsonld';

const podConfigResolver = lwsEnabled ? makePodConfigResolver(storage, PER_STORAGE_CONFIG_REL) : null;

// Content Negotiation by Profile is ON by default whenever --lws is on;

// --no-lws-profile-conneg is a per-deployment safety valve to disable just

// the capability advertisement without disabling the rest of --lws.

const profileConnegEnabled = lwsEnabled && (options.lwsProfileConneg ?? true);

// WebSocket notifications are OFF by default

const notificationsEnabled = options.notifications ?? false;

// Identity Provider is OFF by default

const idpEnabled = options.idp ?? false;

const idpIssuer = options.idpIssuer;

// Subdomain mode is OFF by default - use path-based pods

const subdomainsEnabled = options.subdomains ?? false;

const baseDomain = options.baseDomain || null;

// --lws is path-mode only for now: urlToStoragePath (src/lws/admission.js)

// maps URLs to storage via bare URL.pathname, which drops the pod-name

// prefix under --subdomains — SHACL shape admission (src/lws/write.js) and

// the conneg authz filter (src/lws/representations.js) would silently

// misresolve. Refuse loudly rather than misresolve (spec 2026-07-10 S6).

if (lwsEnabled && subdomainsEnabled) {

throw new Error('--lws cannot be combined with --subdomains yet: LWS resolves shape/alternate URLs in path mode only. Disable one of the two flags.');

}

// Authorization-server role (2026-07-24 AS round): --lws-as only makes

// sense on a deployment that also speaks the LWS storage surface it

// authorizes into. loadConfig() already enforces this for the CLI/env

// path; re-check here so a direct createServer({ lwsAs: true }) caller

// (tests, embedders) gets the same fail-loud guarantee instead of a

// confusing 404 once the AS routes (later tasks) exist.

const lwsAsEnabled = options.lwsAs ?? false;

if (lwsAsEnabled && !lwsEnabled) {

throw new Error('--lws-as requires --lws (enable the LWS storage surface first, or drop --lws-as / JSS_LWS_AS)');

}

// --lws-as requires --idp (review fix, 2026-07-24): mirrors the loadConfig()

// check (src/config.js) for a direct createServer({ lwsAs: true }) caller —

// the token-exchange grant and the RFC 8414 metadata's advertised

// token_endpoint/jwks_uri both live inside idpPlugin; without idpEnabled

// this would serve a 200 metadata doc pointing at routes that don't exist.

if (lwsAsEnabled && !idpEnabled) {

throw new Error('--lws-as requires --idp (enable the built-in Identity Provider first, or drop --lws-as / JSS_LWS_AS)');

}

const lwsAsTtl = options.lwsAsTtl ?? defaults.lwsAsTtl;

// Effective trusted issuer: an explicit --lws-as-uri (validated the same

// way as --lws-provider — must be an absolute URI or it's dropped) else

// this deployment's own origin, since the fork IS the AS by default

// (Approach A, spec 2026-07-24). Stays null when the AS role is off so

// downstream code has one flag (lwsAsEnabled) to branch on.

let lwsAsUri = null;

if (lwsAsEnabled) {

const explicitAsUri = options.lwsAsUri ?? null;

if (explicitAsUri && isAbsoluteUri(explicitAsUri)) {

lwsAsUri = explicitAsUri;

} else {

if (explicitAsUri) {

console.warn(`[lws-pod] --lws-as-uri / JSS_LWS_AS_URI is not an absolute URI: ${JSON.stringify(explicitAsUri)} — falling back to the deployment origin`);

}

const protocol = options.ssl ? 'https' : 'http';

const host = options.host === '0.0.0.0' ? 'localhost' : (options.host || 'localhost');

const port = options.port || defaults.port;

lwsAsUri = idpIssuer?.replace(/\/$/, '') || `${protocol}://${host}:${port}`;

}

}

// Trusted-local direct bearer (2026-07-24 AS round, task 7 / final-review

// fix): default ON (today's behavior — every legacy IdP-issued bearer

// authenticates directly at the resource boundary), OFF-able for a

// public-rung deployment via --no-trusted-local-bearer / env. Threaded

// onto the request the same way as lwsAs/lwsAsUri above so

// src/auth/token.js can gate on it without importing config machinery.

const trustedLocalBearerEnabled = options.trustedLocalBearer ?? true;

// Mashlib data browser is OFF by default

// mashlibCdn: load from CDN; mashlibModule: URL to ES module entry point

const mashlibModule = options.mashlibModule ?? false;

const mashlibCdn = options.mashlibCdn ?? false;

const mashlibEnabled = mashlibCdn || !!mashlibModule;

const mashlibVersion = options.mashlibVersion ?? '2.0.0';

// Git HTTP backend is OFF by default - enables clone/push via git protocol

const gitEnabled = options.git ?? false;

// CORS proxy (#378) — OFF by default. Numeric settings get the

// sane-default fallback if the env var or config file supplies a

// non-finite/non-positive value (e.g. JSS_CORS_PROXY_MAX_BYTES=banana

// would otherwise leave the cap as the string "banana", making

// `bytesSeen > "banana"` always false and silently disabling the

// safety limit).

const positiveInt = (v, fallback) =>

(typeof v === 'number' && Number.isFinite(v) && v > 0) ? v : fallback;

const corsProxyEnabled = options.corsProxy === true;

const corsProxyMaxBytes = positiveInt(options.corsProxyMaxBytes, 50 * 1024 * 1024);

const corsProxyTimeoutMs = positiveInt(options.corsProxyTimeoutMs, 30_000);

const corsProxyMaxRedirects = positiveInt(options.corsProxyMaxRedirects, 5);

// Nostr relay is OFF by default

const nostrEnabled = options.nostr ?? false;

const nostrPath = options.nostrPath ?? '/relay';

const nostrMaxEvents = options.nostrMaxEvents ?? 1000;

// WebRTC signaling is OFF by default

const webrtcEnabled = options.webrtc ?? false;

const webrtcPath = options.webrtcPath ?? '/.webrtc';

// Terminal (WebSocket shell) is OFF by default

const terminalEnabled = options.terminal ?? false;

// Tunnel proxy is OFF by default

const tunnelEnabled = options.tunnel ?? false;

const tunnelPath = options.tunnelPath ?? '/.tunnel';

// Application mount points (plugin seam, #206): URL prefixes owned by

// registered apps (e.g. a game mounted at /tideholm). Requests below an

// app path skip the WAC hook — the app owns authentication and

// authorization under its prefix, like /storage/ and /db/ already do.

const appPaths = Array.isArray(options.appPaths)

? options.appPaths

.filter((p) => typeof p === 'string')

.map((p) => p.trim().replace(/\/+$/, '')) // '/myapp/' matches like '/myapp'

.filter((p) => p.startsWith('/') && p.length > 1)

: [];

// App plugins (#206): loaded at startup, each entry's prefix joins

// appPaths. The WAC hook reads the array per request, so pushes made

// during plugin activation are honored.

const pluginEntries = Array.isArray(options.plugins) ? options.plugins : [];

// Parameterized reservations from api.reservePath (#602): compiled

// matchers for path shapes like /:user/did.json that literal appPaths

// prefixes cannot express. Same per-request read as appPaths.

const appPathPatterns = [];

// ActivityPub federation is OFF by default

const activitypubEnabled = options.activitypub ?? false;

const apUsername = options.apUsername ?? 'me';

const apDisplayName = options.apDisplayName ?? options.apUsername ?? 'Anonymous';

const apSummary = options.apSummary ?? '';

const apNostrPubkey = options.apNostrPubkey ?? null;

// Invite-only registration is OFF by default - open registration

const inviteOnly = options.inviteOnly ?? false;

// Single-user mode - creates pod on startup, disables registration

const singleUser = options.singleUser ?? false;

// Default null = root pod (#348). Pass an explicit singleUserName

// to mount the pod at /<name>/ instead. Normalize the

// historical `'/'` / `''` forms to null up front so downstream

// code (remoteStoragePlugin, decorators, etc.) doesn't have to

// re-check for the same three shapes.

//

// Pre-#348 installs (default 'me') that upgrade in place will see

// a fresh empty root pod alongside their /me/ data. The fix is to

// pass `--single-user-name me` on restart (or move data/me/* out

// to the data root). At v0.0.x we accept that one-time

// intervention rather than carrying detection magic in the code.

const rawSingleUserName = options.singleUserName ?? null;

const singleUserName =

(rawSingleUserName === '/' || rawSingleUserName === '')

? null

: rawSingleUserName;

const singleUserPassword = options.singleUserPassword ?? null;

// Default storage quota per pod (50MB default, 0 = unlimited)

const defaultQuota = options.defaultQuota ?? 50 * 1024 * 1024;

// Pod-creation rate limit (POST /.pods) — max per IP per day. Defaults to

// 1, the shipped anti-squatting / resource-exhaustion cap. Overridable so

// tests that legitimately create many pods against one loopback IP aren't

// blocked by the (now correctly armed) limit; the default is unchanged, so

// production behavior is identical.

const podCreateRateLimitMax = options.podCreateRateLimitMax ?? 1;

// Authenticated write / type-query cap (per webId per minute). Generous by

// design — a runaway-loop backstop, not a throttle on legitimate bulk agent

// work (real write abuse is bounded by WAC + storage quota). Anonymous

// callers keep the strict 60/min per-IP crawler/flood cap (see the two-tier

// writeRateLimit/typeQueryRateLimit below). Tunable; tests pass a low value

// to reach the backstop. Mirrors podCreateRateLimitMax's options pass-through.

const writeRateLimitMax = options.writeRateLimitMax ?? 600;

// Strict per-IP cap for anonymous callers on the same resource endpoints.

// Overridable (mirrors writeRateLimitMax) so tests reach the cap without

// driving 60+ requests; production default is unchanged.

const anonRateLimitMax = options.anonRateLimitMax ?? 60;

// Optional single override for every idp brute-force cap (see idpPlugin).

// Undefined in production → each idp route keeps its shipped max. Tests that

// hammer an idp endpoint from one loopback IP pass a high value.

const idpRateLimitMax = options.idpRateLimitMax;

// WebID-TLS client certificate authentication is OFF by default

const webidTlsEnabled = options.webidTls ?? false;

// Live reload - injects script to auto-refresh browser on file changes

const liveReloadEnabled = options.liveReload ?? false;

// MongoDB-backed /db/ route is OFF by default

const mongoEnabled = options.mongo ?? false;

// MCP (Model Context Protocol) server — exposes the pod as a tool

// surface for agents (Claude Desktop, Cursor, etc.). OFF by default.

// See docs/mcp.md and #490.

const mcpEnabled = options.mcp ?? false;

// Credential-tier seam for /mcp (task-6). 'trusted-local' (default) is

// today's behavior; 'audience-bound' refuses the replayable RS256 bearer

// and requires an audience-bound credential (LWS-CID or Solid-OIDC DPoP).

// An unrecognized value falls back to the safe default rather than

// silently disabling the seam.

const validMcpCredentialPolicies = ['trusted-local', 'audience-bound'];

const mcpCredentialPolicy = validMcpCredentialPolicies.includes(options.mcpCredentialPolicy)

? options.mcpCredentialPolicy

: 'trusted-local';

// Federation SSRF guard opt-in (dt8, spec §6): the MCP federation arm

// (read_resource's remote branch) blocks loopback/RFC-1918/link-local/

// cloud-metadata hosts by default. --lws-federation-private is the

// deliberate opt-in for the local rig (self-fetch across containers on

// one host). Strict `=== true` mirrors provisionKeysEnabled below — a

// stray truthy non-boolean must not silently open the guard.

const federationPrivate = options.lwsFederationPrivate === true;

// Provision a Schnorr secp256k1 owner key in /private/privkey.jsonld

// when a single-user pod is first created. Phase 1 of #437. Off by

// default: keys-on-disk is a real security tradeoff, opt-in keeps

// the choice visible to the operator.

//

// Refuse the --provision-keys + --public combination at server-create

// time so the operator hits the contradiction immediately rather than

// by reading a leaked key from logs / the public web. See #442 review.

//

// Strict `=== true` (not `?? false`) coerces a misconfigured truthy

// non-boolean (e.g. JSON config / env coercion handing in `'true'`

// as a string) to false at the boundary. Without this, the root-pod

// branch's `if (provisionKeysEnabled)` would activate while the

// named-pod path's strict check downstream would not, leaving the

// two pod shapes behaving differently for the same input.

const provisionKeysEnabled = options.provisionKeys === true;

assertProvisionKeysCompatible({

provisionKeys: provisionKeysEnabled,

isPublic: !!options.public

});

const mongoUrl = options.mongoUrl ?? 'mongodb://localhost:27017';

const mongoDatabase = options.mongoDatabase ?? 'solid';

// HTTP 402 paid /pay/ routes are OFF by default

const payEnabled = options.pay ?? false;

const payCost = options.payCost ?? 1;

const payMempoolUrl = options.payMempoolUrl ?? 'https://mempool.space/testnet4';

const payAddress = options.payAddress ?? null; // Pod's MRC20 address for token deposits

const payToken = options.payToken ?? null; // Token ticker for primary market

const payRate = options.payRate ?? 1; // Sats per token

const payChains = options.payChains ?? null; // Multi-chain IDs (e.g. "tbtc3,tbtc4")

// Set data root via environment variable if provided

if (options.root) {

process.env.DATA_ROOT = options.root;

}

// Fastify options

const loggerEnabled = options.logger ?? true;

// Resolve bodyLimit from options. Numbers (programmatic, or env values

// already coerced by parseEnvValue) pass through unchanged; strings

// ("100MB" from CLI / config files) go through parseSize for

// size-shorthand support. The typeof check matters because parseSize

// calls `.match` on its input and would throw on a raw number. Falls

// back to defaults.bodyLimit (20 MiB, #563) when unset. See #474.

const bodyLimit = options.bodyLimit == null

? defaults.bodyLimit

: (typeof options.bodyLimit === 'number' ? options.bodyLimit : parseSize(options.bodyLimit));

const fastifyOptions = {

logger: loggerEnabled ? { level: options.logLevel || 'info' } : false,

disableRequestLogging: true,

trustProxy: true,

// Force close connections on server.close() (useful for tests with WebSockets)

forceCloseConnections: options.forceCloseConnections ?? false,

// Cap raw body size (see resolution above; configurable via

// --body-limit / JSS_BODY_LIMIT / createServer({ bodyLimit })).

bodyLimit,

// Gracefully handle client TCP errors (ECONNRESET, EPIPE, etc.)

clientErrorHandler: (err, socket) => {

if (err.code === 'ECONNRESET' || err.code === 'EPIPE' || err.code === 'ECONNABORTED') {

socket.destroy();

return;

}

// Default Fastify behavior for other client errors

socket.destroy(err);

},

// Catch Fastify-internal errors that fire BEFORE any user hook

// runs — notably FST_ERR_BAD_URL on malformed percent-encoding

// (`%g1`, truncated `%E0%`, invalid UTF-8). Without this, Fastify

// writes the 400 response directly via `res.writeHead` and the

// browser sees a CORS error (no Access-Control-Allow-*) instead

// of the real status. #376.

frameworkErrors: (err, request, reply) => {

// ALWAYS apply CORS headers — matches the rest of the server's

// behavior (every successful response sets CORS via the global

// onRequest hook). getCorsHeaders defaults Allow-Origin to `*`

// when the request didn't send an Origin header.

const cors = getCorsHeaders(request.headers?.origin);

for (const [k, v] of Object.entries(cors)) reply.header(k, v);

const statusCode = err.statusCode ?? 400;

reply.code(statusCode).type('application/json').send({

// Use the HTTP status text (e.g. "Bad Request" for 400)

// rather than err.name (which for FastifyError is the

// unhelpful string "FastifyError"). Matches Fastify's

// default error-body shape that pre-fix clients were

// parsing.

error: STATUS_CODES[statusCode] || 'Error',

code: err.code,

message: err.message,

statusCode,

});

}

};

// Add HTTPS support if SSL config provided

if (options.ssl && options.ssl.key && options.ssl.cert) {

fastifyOptions.https = {

key: options.ssl.key,

cert: options.ssl.cert,

};

// Enable client certificate request for WebID-TLS

if (webidTlsEnabled) {

fastifyOptions.https.requestCert = true;

// Don't reject unauthorized - we verify via WebID profile, not CA chain

fastifyOptions.https.rejectUnauthorized = false;

}

}

const fastify = Fastify(fastifyOptions);

registerErrorHandler(fastify);

// Add raw body parser for all content types

fastify.addContentTypeParser('*', { parseAs: 'buffer' }, (req, body, done) => {

done(null, body);

});

// Git content types need explicit handling (binary data)

fastify.addContentTypeParser('application/x-git-receive-pack-request', { parseAs: 'buffer' }, (req, body, done) => {

done(null, body);

});

fastify.addContentTypeParser('application/x-git-upload-pack-request', { parseAs: 'buffer' }, (req, body, done) => {

done(null, body);

});

// Override the default application/json parser so the NIP-98 payload-hash

// check (src/auth/nostr.js) can verify against the EXACT bytes the client

// signed, not a re-serialization of the parsed object (#565). The default

// parser discards the raw bytes once it produces an object, so capturing

// req.rawBody here is the only point they still exist. Behaviour otherwise

// mirrors Fastify 4's defaultJsonParser exactly — empty body → 400,

// secure-json-parse (same prototype-pollution protection JSS gets today),

// 400 on malformed — so no other request path changes. (Must

// removeContentTypeParser first: Fastify throws on a duplicate type.)

fastify.removeContentTypeParser('application/json');

fastify.addContentTypeParser('application/json', { parseAs: 'string' }, (req, body, done) => {

req.rawBody = body;

if (body === '' || body == null) {

// Match Fastify's FST_ERR_CTP_EMPTY_JSON_BODY exactly (code +

// message + status), so the error-response shape — which surfaces

// err.code — is identical to the default parser's.

const err = new Error("Body cannot be empty when content-type is set to 'application/json'");

err.code = 'FST_ERR_CTP_EMPTY_JSON_BODY';

err.statusCode = 400;

return done(err, undefined);

}

let json;

try {

// The malformed-JSON path already mirrors Fastify's default: it

// sets statusCode 400 on the raw parser error without adding an FST

// code (the default does the same), so no code is set here.

json = sjson.parse(body);

} catch (err) {

err.statusCode = 400;

return done(err, undefined);

}

done(null, json);

});

// Attach server config to requests

// Raw request body for the application/json parser to stash (#565).

fastify.decorateRequest('rawBody', null);

fastify.decorateRequest('connegEnabled', null);

fastify.decorateRequest('lwsEnabled', null);

fastify.decorateRequest('typeIndexEnabled', null);

fastify.decorateRequest('lwsProfileConneg', null);

fastify.decorateRequest('notificationsEnabled', null);

fastify.decorateRequest('idpEnabled', null);

fastify.decorateRequest('subdomainsEnabled', null);

fastify.decorateRequest('baseDomain', null);

fastify.decorateRequest('podName', null);

fastify.decorateRequest('mashlibEnabled', null);

fastify.decorateRequest('mashlibCdn', null);

fastify.decorateRequest('mashlibVersion', null);

fastify.decorateRequest('mashlibModule', null);

fastify.decorateRequest('defaultQuota', null);

fastify.decorateRequest('provisionKeys', null);

fastify.decorateRequest('config', null);

fastify.decorateRequest('liveReloadEnabled', null);

fastify.decorateRequest('singleUser', null);

fastify.decorateRequest('singleUserName', null);

fastify.decorateRequest('podConfig', null);

fastify.decorateRequest('podConfigFor', null);

// A6 (multi-tenant round): the owning storage's root path for THIS

// request's own target resource ('/alice/' or null for server scope),

// resolved once here (async storageRootFor, cached) since getAllHeaders

// is sync and called ~40x per response. Threaded into every LWS-relevant

// getAllHeaders({...}) call site in src/handlers/resource.js (the only

// file whose getAllHeaders calls pass lwsEnabled today — container.js's

// two calls don't, so they never emit storageDescription regardless) so

// the Link points at the OWNING storage's description, not the origin

// well-known.

fastify.decorateRequest('storageRootPath', null);

// Governance round: the storage's solid:owner URIs, resolved ONLY when the

// request targets the storage root itself (the one response Solid's

// advertising MUST applies to) — every other request pays nothing. Rides

// the A6-resolved root; READ-gating is inherited (the root response only

// exists after the WAC hook passed).

fastify.decorateRequest('storageOwners', null);

// Task 7 (spec 2026-07-15): the navigator root/storage view

// (src/handlers/resource.js) builds its own storage description — it

// needs these two flags on `request` for parity, mirroring

// lwsProfileConneg just below. The multi-tenant /:pod/lws-storage HTTP

// route (below) reads the same flags off its own local closures.

fastify.decorateRequest('mcpEnabled', null);

fastify.decorateRequest('anonRateLimitMax', null);

// AS round (task 1): the AS role flag + its resolved effective trusted

// issuer, for the later challenge/token-validation tasks to read off the

// request the same way every other lws-* flag above does.

fastify.decorateRequest('lwsAs', null);

fastify.decorateRequest('lwsAsUri', null);

// Task 7 / final-review fix: the trusted-local-bearer switch, read by

// src/auth/token.js resolveWebIdFromRequest. Default-permissive (`null`)

// until the onRequest hook below sets the real value — see token.js for

// why a missing/`null` decoration means "treat as ON".

fastify.decorateRequest('trustedLocalBearer', null);

fastify.addHook('onRequest', async (request) => {

request.connegEnabled = connegEnabled;

request.lwsEnabled = lwsEnabled;

request.podConfig = podConfig;

request.podConfigFor = (root) => podConfigResolver ? podConfigResolver.for(root) : { get: async () => ({}) };

request.typeIndexEnabled = typeIndexEnabled;

request.lwsProfileConneg = profileConnegEnabled;

request.notificationsEnabled = notificationsEnabled || liveReloadEnabled;

request.idpEnabled = idpEnabled;

request.subdomainsEnabled = subdomainsEnabled;

request.baseDomain = baseDomain;

request.mashlibEnabled = mashlibEnabled;

request.mashlibCdn = mashlibCdn;

request.mashlibVersion = mashlibVersion;

request.mashlibModule = mashlibModule;

request.defaultQuota = defaultQuota;

request.provisionKeys = provisionKeysEnabled;

request.config = { public: options.public, readOnly: options.readOnly };

request.liveReloadEnabled = liveReloadEnabled;

request.singleUser = singleUser;

request.singleUserName = singleUserName;

request.mcpEnabled = mcpEnabled;

request.anonRateLimitMax = anonRateLimitMax;

request.lwsAs = lwsAsEnabled;

request.lwsAsUri = lwsAsUri;

request.trustedLocalBearer = trustedLocalBearerEnabled;

// A6: urlPath the SAME way getRequestPaths (resource.js/container.js)

// derives it, so the resolved root always matches the resourceUrl those

// handlers build from the same request.url — storageRootFor itself

// returns null for '/', '.well-known/*', or an unmarked first segment

// (server scope), cached positive-only (A2).

request.storageRootPath = lwsEnabled

? await storageRootFor(storage, request.url.split('?')[0])

: null;

// solid:owner is READ-gated by inheritance (spec §4): it may only ride

// a response that itself exists after WAC passed. That argument holds

// for GET/HEAD, which go through authorize()'s normal WAC check — but

// NOT for OPTIONS, which authorize() always allows unconditionally

// (CORS preflight, src/auth/middleware.js) and so never sees WAC at

// all. Method-gate resolution here, at the one place owners are read,

// rather than chasing every call site that threads request.storageOwners

// through (final-review F-1, 2026-07-23): an anonymous OPTIONS on a

// private storage must not leak its owner.

request.storageOwners = null;

if ((request.method === 'GET' || request.method === 'HEAD') && request.storageRootPath && request.url.split('?')[0] === request.storageRootPath) {

request.storageOwners = await readOwners(storage, request.storageRootPath);

}

// Extract pod name from subdomain if enabled

if (subdomainsEnabled && baseDomain) {

const host = request.hostname;

// Check if host is a subdomain of baseDomain

if (host !== baseDomain && host.endsWith('.' + baseDomain)) {

// Extract subdomain (e.g., "alice.example.com" -> "alice")

const subdomain = host.slice(0, -(baseDomain.length + 1));

// Only single-level subdomains (no dots)

if (!subdomain.includes('.')) {

request.podName = subdomain;

}

}

}

});

// Unified access log — one line per request

fastify.addHook('onResponse', async (request, reply) => {

if (!request.log.isLevelEnabled('info')) return;

request.log.info({

method: request.method,

url: request.url,

statusCode: reply.statusCode,

remoteAddress: request.ip || request.headers['x-forwarded-for'] || request.socket?.remoteAddress,

responseTime: Math.round(reply.elapsedTime * 100) / 100,

userAgent: request.headers['user-agent'] || undefined,

referrer: request.headers.referer || undefined,

contentLength: reply.getHeader('content-length') || undefined,

}, `${request.method} ${request.url} ${reply.statusCode} ${Math.round(reply.elapsedTime)}ms`);

});

// Register rate limiting plugin FIRST, before any plugin (idp/ap) or route

// that carries a `config.rateLimit` override. @fastify/rate-limit wires

// per-route limits via an `onRoute` hook added inside the plugin body, and

// that hook only fires for routes registered AFTER this plugin has booted.

// Plugins boot in registration order, so registering rate-limit before the

// idp/ap plugins is what actually arms their brute-force limits. (The

// synchronous write/`.pods`/type routes registered directly on this instance

// still need `fastify.after(...)` — they register before ready() runs any

// plugin body at all; see those registrations below.)

// Protects against brute force attacks and resource exhaustion.

fastify.register(rateLimit, {

global: false, // Don't apply globally, only to specific routes

max: 100, // Default max requests per window

timeWindow: '1 minute',

// Custom error response. @fastify/rate-limit does `throw errorResponseBuilder(...)`

// and Fastify only routes a THROWN value through its error handler (which sets

// the reply status from `.statusCode`) when it is an Error instance — a plain

// object silently serializes as a 200 body, so a tripped counter never yields a

// real 429. Return an Error with `.statusCode` (429) so every armed limit responds

// correctly. `context.after` is a formatted string ("1 minute"); `context.ttl` is

// the numeric ms-remaining used to compute Retry-After seconds.

errorResponseBuilder: (request, context) => {

const retryAfter = Math.ceil(context.ttl / 1000);

const err = new Error(`Rate limit exceeded. Try again in ${retryAfter} seconds.`);

err.statusCode = context.statusCode;

err.error = 'Too Many Requests';

err.retryAfter = retryAfter;

return err;

}

});

// Register WebSocket notifications plugin if enabled (or live reload needs it)

if (notificationsEnabled || liveReloadEnabled) {

fastify.register(notificationsPlugin);

}

// Register Identity Provider plugin if enabled

if (idpEnabled) {

// singleUserName + jssVersion are threaded through for the

// pod-data export endpoint (#353), which uses singleUserName to

// resolve the pod's on-disk path and writes the version into

// the export manifest for forensic / "what server made this"

// purposes. Reading the package.json lazily here keeps the

// export endpoint independent of any seedServerRoot work.

let jssVersion = 'unknown';

try {

// Sync read because createServer isn't async and we need the

// version to thread into idpPlugin registration below. The file

// is tiny + on local disk. There is a second async read of

// package.json in the onReady hook for seedServerRoot — both

// are read-once at startup so drift is bounded to "package.json

// changed between two ~ms-apart reads", which doesn't happen

// in practice. Hoisting both into a memoized module-level

// helper is a worthwhile follow-up but out of scope for #353.

const pkgRaw = readFileSync(join(__dirname, '..', 'package.json'), 'utf8');

jssVersion = JSON.parse(pkgRaw).version;

} catch { /* keep 'unknown' */ }

fastify.register(idpPlugin, {

issuer: idpIssuer, inviteOnly, singleUser, singleUserName, jssVersion,

idpRateLimitMax,

lwsAs: lwsAsEnabled, lwsAsUri, lwsAsTtl,

});

}

// Load app plugins (#206). Deferred into a register scope so the dynamic

// imports and async activation run during fastify's startup; a failing

// plugin fails listen() rather than leaving a half-configured server.

if (pluginEntries.length) {

fastify.register(async (instance) => {

const { loadPlugins } = await import('./plugins.js');

await loadPlugins(instance, pluginEntries, {

appPaths,

appPathPatterns,

root: options.root || process.env.DATA_ROOT || './data',

log: fastify.log,

// api.serverInfo inputs (#601). ?? keeps an explicit port 0 —

// "resolved at listen" — instead of masking it with the default.

origin: {

ssl: !!options.ssl,

host: options.host,

port: options.port ?? defaults.port,

baseUrl: idpIssuer?.replace(/\/$/, '') || null,

},

});

});

}

// Register Nostr relay if enabled

if (nostrEnabled) {

fastify.register(async (instance) => {

await registerNostrRelay(instance, {

path: nostrPath,

maxEvents: nostrMaxEvents

});

});

}

// Register WebRTC signaling if enabled

if (webrtcEnabled) {

fastify.register(webrtcPlugin, { path: webrtcPath });

}

// Register terminal (WebSocket shell) if enabled

if (terminalEnabled) {

fastify.register(terminalPlugin, { path: '/.terminal', public: options.public || false });

}

// Register tunnel proxy if enabled

if (tunnelEnabled) {

fastify.register(tunnelPlugin, { path: tunnelPath });

}

// Register ActivityPub plugin if enabled

if (activitypubEnabled) {

fastify.register(activityPubPlugin, {

username: apUsername,

displayName: apDisplayName,

summary: apSummary,

nostrPubkey: apNostrPubkey

});

}

// Register remoteStorage plugin (always on — no flag needed)

fastify.register(remoteStoragePlugin, {

username: singleUserName || 'me',

ownerWebId: null // single-user: any authenticated user can access

});

// Register MongoDB /db/ route if enabled

if (mongoEnabled) {

fastify.register(dbPlugin, { mongoUrl, mongoDatabase, singleUser });

}

// Register MCP server if enabled (issue #490). POST /mcp carries the same

// trust-aware limiter as writeRateLimit/typeQueryRateLimit (Task 4: the LWS

// read tools make an uncapped type-search-over-MCP walk possible otherwise) —

// anon per-IP cap, authenticated per-webId cap. Unlike the bare

// fastify.post(...) routes below (/.pods, /types/*, writes), mcpPlugin is

// itself registered via fastify.register(), so it boots asynchronously in

// registration order along with every other plugin — since @fastify/rate-limit

// was registered earlier (~:442) and boots first, its onRoute hook already

// exists by the time mcpPlugin's body runs and calls fastify.post('/mcp', ...),

// so no fastify.after() wrapping is needed here (that workaround is only for

// routes registered directly/synchronously on this outer instance).

if (mcpEnabled) {

const mcpRateLimit = { config: { rateLimit: trustAwareRateLimit(writeRateLimitMax, anonRateLimitMax) } };

// podConfigResolver (A3/A7), not the legacy single podConfig — the MCP

// storage-description resource is per-storage now (Task A7), so it needs

// the SAME per-root resolver the HTTP /:pod/lws-storage route uses

// (request.podConfigFor), not one server-wide config instance.

fastify.register(mcpPlugin, { routeOptions: mcpRateLimit, credentialPolicy: mcpCredentialPolicy, podConfigResolver, anonRateLimitMax, federationPrivate, lwsProvider: lwsProviderUri });

}

// (rate-limit plugin registration moved up — see the block before the

// notifications plugin registration; it must boot before the idp/ap plugins

// and the write/`.pods`/type routes so their `config.rateLimit` overrides wire.)

// Global CORS preflight

fastify.addHook('onRequest', async (request, reply) => {

// Add CORS headers to all responses

const corsHeaders = getCorsHeaders(request.headers.origin);

Object.entries(corsHeaders).forEach(([k, v]) => reply.header(k, v));

// Add Updates-Via header for WebSocket notification discovery

if (notificationsEnabled) {

const wsProtocol = request.protocol === 'https' ? 'wss' : 'ws';

reply.header('Updates-Via', `${wsProtocol}://${request.hostname}/.notifications`);

}

// Note: OPTIONS requests are handled by handleOptions to include Accept-* headers

});

// ActivityPub actor endpoint - dedicated route for /profile/card.jsonld with AP Accept header

// Registered before wildcard routes to take priority

if (activitypubEnabled) {

fastify.route({

method: 'GET',

url: '/profile/card.jsonld',

handler: async (request, reply) => {

const accept = request.headers.accept || '';

const wantsAP = accept.includes('activity+json') ||

accept.includes('ld+json; profile="https://www.w3.org/ns/activitystreams"');

const actorHandler = getActorHandler();

if (wantsAP && actorHandler) {

const actor = actorHandler(request);

return reply

.type('application/activity+json')

.send(actor);

}

// Not AP request - serve the HTML profile from disk

// This is handled by importing the resource handler

const { handleGet } = await import('./handlers/resource.js');

return handleGet(request, reply);

}

});

}

// Security: Block access to dotfiles except allowed Solid-specific ones

// This prevents exposure of .git/, .env, .htpasswd, etc.

// Git protocol requests bypass this check when git is enabled

const ALLOWED_DOTFILES = ['.well-known', '.acl', '.meta', '.pods', '.notifications', '.account'];

fastify.addHook('onRequest', async (request, reply) => {

// Allow git protocol requests through when git is enabled

if (gitEnabled && isGitRequest(request.url)) {

return;

}

// Allow pay routes through when pay is enabled (.balance, .deposit)

if (payEnabled && isPayRequest(request.url)) {

return;

}

// Allow WebRTC and tunnel endpoints through when enabled

const urlNoQuery = request.url.split('?')[0];

if (tunnelEnabled && (urlNoQuery === tunnelPath || urlNoQuery.startsWith('/tunnel/'))) {

return;

}

if (webrtcEnabled && urlNoQuery === webrtcPath) {

return;

}

if (terminalEnabled && urlNoQuery === '/.terminal') {

return;

}

// App plugins own their prefix (#206) — a plugin mounted at a dot path

// (e.g. the webrtc plugin at /.webrtc, matching core's historical URL)

// must stay reachable, exactly as the WAC hook already defers to

// appPaths. Read per request: plugin activation pushes entries.

if (appPaths.some(p => urlNoQuery === p || urlNoQuery.startsWith(p + '/'))) {

return;

}