JavaScriptSolidServer

Philosophy: JSON-LD First

This is a JSON-LD native implementation. Unlike traditional Solid servers that treat Turtle as the primary format and convert to/from it, this server:

• Stores everything as JSON-LD - No RDF parsing overhead for standard operations
• Serves JSON-LD by default - Modern web applications can consume responses directly
• Content negotiation is optional - Enable Turtle support with { conneg: true } when needed
• Fast by design - Skip the RDF parsing tax when you dont need it

Why JSON-LD First?

1. Performance: JSON parsing is native to JavaScript - no external RDF libraries needed for basic operations
2. Simplicity: JSON-LD is valid JSON - works with any JSON tooling
3. Web-native: Browsers and web apps understand JSON natively
4. Semantic web ready: JSON-LD is a W3C standard RDF serialization

When to Enable Content Negotiation

Enable conneg: true when:

• Interoperating with Turtle-based Solid apps
• Serving data to legacy Solid clients
• Running conformance tests that require Turtle support

import { createServer } from './src/server.js';

// Default: JSON-LD only (fast)
const server = createServer();

// With Turtle support (for interoperability)
const serverWithConneg = createServer({ conneg: true });

Configuration

createServer({
  logger: true,        // Enable Fastify logging (default: true)
  conneg: false,       // Enable content negotiation (default: false)
  notifications: false, // Enable WebSocket notifications (default: false)
  subdomains: false,   // Enable subdomain-based pods (default: false)
  baseDomain: null,    // Base domain for subdomains (e.g., "example.com")
  mashlib: false,      // Enable Mashlib data browser - local mode (default: false)
  mashlibCdn: false,   // Enable Mashlib data browser - CDN mode (default: false)
  mashlibVersion: '2.0.0', // Mashlib version for CDN mode
});

Mashlib Data Browser

Enable the SolidOS Mashlib data browser for RDF resources. Two modes are available:

CDN Mode (recommended for getting started):

jss start --mashlib-cdn --conneg

Loads mashlib from unpkg.com CDN. Zero footprint - no local files needed.

Local Mode (for production/offline):

jss start --mashlib --conneg

Serves mashlib from src/mashlib-local/dist/. Requires building mashlib locally:

cd src/mashlib-local
npm install && npm run build

ES Module Mode (for custom or next-gen mashlib builds):

jss start --mashlib-module https://example.com/mashlib.js

Loads an ES module-based data browser from any URL. Uses <script type="module"> and <div id="mashlib"> (self-initializing). CSS is auto-derived by replacing .js with .css. Content negotiation is auto-enabled.

How it works:

1. Browser requests /alice/public/data.ttl with Accept: text/html
2. Server returns Mashlib HTML wrapper
3. Mashlib fetches the actual data via content negotiation
4. Mashlib renders an interactive, editable view

Note: Mashlib works best with --conneg enabled for Turtle support.

Modern UI (SolidOS UI):

jss start --mashlib --solidos-ui --conneg

Serves a modern Nextcloud-style UI shell while reusing mashlibs data layer. The --solidos-ui flag swaps the classic databrowser interface for a cleaner, mobile-friendly design with:

• Modern file browser with breadcrumb navigation
• Profile, Contacts, Sharing, and Settings views
• Path-based URLs (browser URL reflects current resource)
• Responsive design for mobile devices

Requires solidos-ui dist files in src/mashlib-local/dist/solidos-ui/. See solidos-ui for details.

Profile Pages

Pod profiles (/alice/) use HTML with embedded JSON-LD data islands and are rendered using:

• mashlib-jss - A fork of mashlib with getPod() fix for path-based pods
• solidos-lite - Parses JSON-LD data islands into the RDF store

This allows profiles to work without server-side content negotiation while still providing full SolidOS editing capabilities.

WebSocket Notifications

Enable real-time notifications for resource changes:

const server = createServer({ notifications: true });

Clients discover the WebSocket URL via the Updates-Via header:

curl -I http://localhost:4443/alice/public/
# Updates-Via: ws://localhost:4443/.notifications

Protocol (solid-0.1, compatible with SolidOS):

Server: protocol solid-0.1
Client: sub http://localhost:4443/alice/public/data.json
Server: ack http://localhost:4443/alice/public/data.json
Server: pub http://localhost:4443/alice/public/data.json  (on change)

CLI Start Options

Start Options

Environment Variables

All options can be set via environment variables with JSS_ prefix:

export JSS_PORT=8443
export JSS_SSL_KEY=/path/to/key.pem
export JSS_SSL_CERT=/path/to/cert.pem
export JSS_CONNEG=true
export JSS_SUBDOMAINS=true
export JSS_BASE_DOMAIN=example.com
export JSS_MASHLIB=true
export JSS_MASHLIB_MODULE=https://example.com/mashlib.js
export JSS_NOSTR=true
export JSS_INVITE_ONLY=true
export JSS_WEBID_TLS=true
export JSS_DEFAULT_QUOTA=100MB
export JSS_ACTIVITYPUB=true
export JSS_AP_USERNAME=alice
export JSS_PUBLIC=true
export JSS_READ_ONLY=true
export JSS_SINGLE_USER=true
export JSS_SINGLE_USER_NAME=me
export JSS_SINGLE_USER_PASSWORD=choose-a-good-one  # seeds IDP account on first start
export JSS_LIVE_RELOAD=true
export JSS_SOLIDOS_UI=true
export JSS_PAY=true
export JSS_PAY_COST=10
export JSS_PAY_ADDRESS=your-address
export JSS_PAY_TOKEN=PODS
export JSS_PAY_RATE=10
export JSS_MONGO=true
export JSS_MONGO_URL=mongodb://localhost:27017
export JSS_MONGO_DATABASE=solid
export JSS_WEBRTC=true
jss start

Config File

Create config.json:

{
  "port": 8443,
  "root": "./data",
  "sslKey": "./ssl/key.pem",
  "sslCert": "./ssl/cert.pem",
  "conneg": true,
  "notifications": true
}

Then: jss start --config config.json

Creating a Pod

curl -X POST http://localhost:4443/.pods \
  -H "Content-Type: application/json" \
  -d '{"name": "alice"}'

Response:

{
  "name": "alice",
  "webId": "http://localhost:4443/alice/#me",
  "podUri": "http://localhost:4443/alice/",
  "token": "eyJ..."
}

Single-User Mode

For personal pod servers where only one user needs access:

# Default: pod served at server root (#348). WebID is
# /profile/card.jsonld#me; the IDP login username is "me". On first
# run JSS will prompt for an initial password (TTY only).
jss start --single-user --idp

# Provide the initial IDP password non-interactively (systemd, containers, CI):
jss start --single-user --idp --single-user-password 'choose-a-good-one'
JSS_SINGLE_USER_PASSWORD='choose-a-good-one' jss start --single-user --idp

# Mount the pod at a named path instead of the origin. WebID becomes
# /alice/profile/card.jsonld#me; login as "alice".
jss start --single-user --single-user-name alice --idp

# Legacy /me/ pod  same as the old default before #348.
jss start --single-user --single-user-name me --idp

# Via environment
JSS_SINGLE_USER=true jss start --idp

Features:

• Pod auto-created on first startup with full structure (inbox, public, private, profile)
• IDP account auto-seeded so the operator can log in immediately
• Registration endpoint disabled (returns 403)
• Login works for the single user via password (POST /idp/credentials) or any other configured method
• Proper ACLs generated automatically

Upgrading from a pre-#348 install: if your existing pod was created with the old default (data lives under <root>/me/), JSS no longer auto-detects it restarting plain jss start --single-user will start seeding a fresh empty root pod alongside your legacy /me/ data, and your existing IDP account will keep authenticating against /me/. Pick one path on the next restart:

• Keep the legacy layout: add --single-user-name me to your launch command. No data movement needed.

• Migrate to root pod: move the entire contents of <root>/me/ (including dotfiles like .acl, .meta, .quota.json a plain mv <root>/me/* <root>/ skips them) to <root>/, delete the IDP account for me (so the new root pods me account can be seeded), then restart without the name flag. Use one of:

  # Option A: rsync handles dotfiles correctly with the trailing slash.
  rsync -a <root>/me/ <root>/ && rm -rf <root>/me
  
  # Option B: bash with dotglob enabled so * matches dotfiles too.
  shopt -s dotglob && mv <root>/me/* <root>/ && rmdir <root>/me
  

Initial password sources, in priority order:

1. --single-user-password <pw> CLI flag
2. JSS_SINGLE_USER_PASSWORD env var
3. Interactive no-echo prompt (TTY only)
4. None the server starts and warns; the pod is created but isnt loggable until you restart with --single-user-password <pw>, set JSS_SINGLE_USER_PASSWORD, or run on a TTY to be prompted. (jss passwd <user> does not work here it returns User not found until an account exists.)

The password is only consulted on the first start once an account exists, subsequent restarts skip the seed step and never overwrite it. The password is never written to the saved config file (.jss/config).

Invite-Only Registration

Control who can create accounts by requiring invite codes:

jss start --idp --invite-only

Managing Invite Codes

# Create a single-use invite
jss invite create
# Created invite code: ABCD1234

# Create multi-use invite with note
jss invite create -u 5 -n "For team members"

# List all active invites
jss invite list
#   CODE        USES     CREATED      NOTE
#   -------------------------------------------------------
#   ABCD1234    0/1      2026-01-03
#   EFGH5678    2/5      2026-01-03   For team members

# Revoke an invite
jss invite revoke ABCD1234

How It Works

When --invite-only is enabled:

• The registration page shows an Invite Code field
• Invalid or expired codes are rejected with an error
• Each use decrements the invites remaining uses
• Depleted invites are automatically removed

Invite codes are stored in .server/invites.json in your data directory.

Application Mount Points (appPaths)

Programmatic compositions can mount whole applications beside the pod (the plugin-zero pattern from #206):

import { createServer } from 'javascript-solid-server/src/server.js';

const fastify = createServer({ appPaths: ['/myapp'] });
// Register both forms: fastify wildcards don't match the bare prefix.
fastify.all('/myapp', myAppHandler);
fastify.all('/myapp/*', myAppHandler); // the app owns auth below its prefix
await fastify.listen({ port: 4443 });

Requests at or below an app path skip the WAC authorization hook the application authenticates and authorizes its own traffic, exactly like the built-in /storage/ and /db/ routes. Everything outside the declared prefixes keeps full WAC enforcement. Entries must start with / and be longer than /; anything else is ignored.

Because the WAC hook is also what populates request.webId, requests under an app path never carry it dont rely on request.webId in app handlers. Resolve identity with the public accessor (#584):

import { getAgent } from 'javascript-solid-server/auth.js';

const agent = await getAgent(request); // WebID or did:nostr DID, null if anonymous

See #582 for the design discussion and melvincarvalho/tideholm for a complete example (a multiplayer game where pod WebIDs are the player accounts).

App Plugins (plugins)

The plugin loader (#206) does the appPaths wiring for you: declare the apps in config and the server imports, mounts, and tears them down itself.

const fastify = createServer({
  root: './data',
  idp: true,
  plugins: [
    { module: 'tideholm/jss-plugin/tideholm-jss.js', prefix: '/tideholm',
      config: { bots: 8 } },
    { module: './my-app/plugin.js', prefix: '/myapp' },
  ],
});

Each entry:

• module import specifier: a package path (resolved from JSSs module graph) or a file path (./ or absolute, resolved from the process cwd). The module exports activate(api), called during startup.
• prefix the apps mount point. Added to appPaths automatically, so the app owns authentication below it (see the section above). Must start with /; invalid prefixes fail startup.
• config passed to the plugin verbatim as api.config.
• id optional stable identifier that names the plugins private data dir. Defaults to a name derived from module: the files basename, or for a generic basename like plugin.js/index.js its parent directory (relay/plugin.js relay), so the conventional <name>/plugin.js layout yields distinct ids with none set. Set it explicitly only if two specifiers still reduce to the same name.

activate(api) receives: api.fastify (register routes here), api.prefix, api.config, api.log, api.auth.getAgent(request) (identity, as above), api.storage.pluginDir() (a private server-side directory under the data root, never served over HTTP), api.serverInfo() { baseUrl, protocol, host, port, listening } (the servers own origin, for minting absolute URLs and loopback calls call it lazily, e.g. per request: with port: 0 the real port exists only once the server is listening, and an explicit idpIssuer wins as baseUrl), api.plugins [{ id, prefix, module }] for every loaded entry (a read-only, frozen boot-time snapshot, so a plugin can enumerate its co-loaded siblings instead of being handed a copy of the operators plugins array it includes the plugin itself, so consumers filter), and api.ws.route(path, (socket, request) => {}) for WebSocket endpoints routed through the same upgrade path as the built-in realtime features, so plugins never attach their own 'upgrade' listener. Return { deactivate } to run teardown (state saves, timers) on server close.

A plugin whose protocol pins absolute paths outside its prefix can claim them with api.reservePath(path):

api.reservePath('/xrpc', { methods: ['GET', 'POST'] });  // fixed root  subtree, methods opted in
api.reservePath('/:user/did.json');                      // pinned document  exact shape, read-only

Both kinds are read-only by default (GET/HEAD/OPTIONS; widen with { methods: [...] }) a reserved path is WAC-exempt and the LDP write wildcards sit beneath it, so exempting a write method the plugin hasnt implemented would let that write fall through to storage unauthenticated. Literal reservations claim their whole subtree; parameterized reservations (:name matches one segment) match only the exact path shape, since they exist for pinned documents inside the pods WAC-governed namespace. Claims are cross-plugin: a second plugin reserving the same path fails the boot naming both claimants. Registering routes on the reserved paths remains the plugins job via api.fastify.

To mount an existing node-style app a (req, res) handler, a reverse proxy, or a framework adapter use api.mountApp(handler, { prefix }):

export async function activate(api) {
  const app = createMyNodeApp();
  await api.mountApp((req, res) => app.handle(req, res));
}

mountApp bundles the four things a wrapped-app plugin needs and would otherwise rediscover: the appPaths WAC exemption, a scoped pass-through content parser (so the wrapped app receives an unconsumed body stream instead of one Fastify already drained the failure that hangs any body-reading app), reply.hijack() so Fastify releases the response, and registration on both the bare prefix and its subtree. It defaults to the entrys prefix; pass { prefix } to mount a second app elsewhere (that prefix is WAC-exempted too).

A plugin that fails to import or activate fails listen() loudly rather than booting a server silently missing an app.

The simple module + prefix case also works straight from the CLI, no config file needed (#594):

jss start --root ./data --public \
  --plugin './chat/plugin.js@/chat' \
  --plugin '@scope/pkg/plugin.js@/app'

--plugin is repeatable; the prefix separator is the last @ followed by /, so scoped package names parse unambiguously. CLI entries append to any plugins array from the config file (they dont replace it). Per-plugin config objects and explicit ids remain config-file-only.

Storage Quotas

Limit storage per pod to prevent abuse and manage resources:

jss start --default-quota 50MB

Managing Quotas

# Set quota for a user (overrides default)
jss quota set alice 100MB

# Show quota info
jss quota show alice
#   alice:
#     Used:  12.5 MB
#     Limit: 100 MB
#     Free:  87.5 MB
#     Usage: 12%

# Recalculate from actual disk usage
jss quota reconcile alice

How It Works

• Quotas are tracked incrementally on PUT, POST, and DELETE operations
• When quota is exceeded, the server returns HTTP 507 Insufficient Storage
• Each pod stores its quota in /{pod}/.quota.json
• Use reconcile to fix quota drift from manual file changes

Size Formats

Supported formats: 50MB, 1GB, 500KB, 1TB

Mashlib Data Browser

Enable the SolidOS Mashlib data browser for RDF resources. Two modes are available:

CDN Mode (recommended for getting started):

jss start --mashlib-cdn --conneg

Loads mashlib from unpkg.com CDN. Zero footprint - no local files needed.

Local Mode (for production/offline):

jss start --mashlib --conneg

Serves mashlib from src/mashlib-local/dist/. Requires building mashlib locally:

cd src/mashlib-local
npm install && npm run build

ES Module Mode (for custom or next-gen mashlib builds):

jss start --mashlib-module https://example.com/mashlib.js

Loads an ES module-based data browser from any URL. Uses <script type="module"> and <div id="mashlib"> (self-initializing). CSS is auto-derived by replacing .js with .css. Content negotiation is auto-enabled.

How it works:

1. Browser requests /alice/public/data.ttl with Accept: text/html
2. Server returns Mashlib HTML wrapper
3. Mashlib fetches the actual data via content negotiation
4. Mashlib renders an interactive, editable view

Note: Mashlib works best with --conneg enabled for Turtle support.

Modern UI (SolidOS UI):

jss start --mashlib --solidos-ui --conneg

Serves a modern Nextcloud-style UI shell while reusing mashlibs data layer. The --solidos-ui flag swaps the classic databrowser interface for a cleaner, mobile-friendly design with:

• Modern file browser with breadcrumb navigation
• Profile, Contacts, Sharing, and Settings views
• Path-based URLs (browser URL reflects current resource)
• Responsive design for mobile devices

Requires solidos-ui dist files in src/mashlib-local/dist/solidos-ui/. See solidos-ui for details.

Profile Pages

Pod profiles (/alice/) use HTML with embedded JSON-LD data islands and are rendered using:

• mashlib-jss - A fork of mashlib with getPod() fix for path-based pods
• solidos-lite - Parses JSON-LD data islands into the RDF store

This allows profiles to work without server-side content negotiation while still providing full SolidOS editing capabilities.

WebSocket Notifications

Enable real-time notifications for resource changes:

const server = createServer({ notifications: true });

Clients discover the WebSocket URL via the Updates-Via header:

curl -I http://localhost:4443/alice/public/
# Updates-Via: ws://localhost:4443/.notifications

Protocol (solid-0.1, compatible with SolidOS):

Server: protocol solid-0.1
Client: sub http://localhost:4443/alice/public/data.json
Server: ack http://localhost:4443/alice/public/data.json
Server: pub http://localhost:4443/alice/public/data.json  (on change)