javascript-solid-server 0.0.137 → 0.0.139

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "javascript-solid-server",
-  "version": "0.0.137",
+  "version": "0.0.139",
   "description": "A minimal, fast Solid server",
   "main": "src/index.js",
   "type": "module",

package/src/ap/index.js

@@ -68,7 +68,7 @@ export async function activityPubPlugin(fastify, options = {}) {
   const getActorId = (request) => {
     const protocol = getProtocol(request)
     const host = request.headers['x-forwarded-host'] || request.hostname
-    return `${protocol}://${host}/profile/card#me`
+    return `${protocol}://${host}/profile/card.jsonld#me`
   }
 
   // Helper to get base URL
@@ -96,11 +96,11 @@ export async function activityPubPlugin(fastify, options = {}) {
       return reply.code(404).send({ error: 'Not found' })
     }
 
-    // For now, accept any username and map to /profile/card#me
+    // For now, accept any username and map to /profile/card.jsonld#me
     // In multi-user mode, we'd look up the user
     const baseUrl = getBaseUrl(request)
-    const actorUrl = `${baseUrl}/profile/card#me`
-    const profileUrl = `${baseUrl}/profile/card`
+    const actorUrl = `${baseUrl}/profile/card.jsonld#me`
+    const profileUrl = `${baseUrl}/profile/card.jsonld`
 
     const response = webfinger.createResponse(
       `${parsed.username}@${parsed.domain}`,
@@ -174,18 +174,18 @@ export async function activityPubPlugin(fastify, options = {}) {
   // Inbox endpoint
   const inboxHandler = createInboxHandler(config, keypair)
   fastify.post('/inbox', inboxHandler)
-  fastify.post('/profile/card/inbox', inboxHandler)
+  fastify.post('/profile/card.jsonld/inbox', inboxHandler)
 
   // Outbox endpoint
   const outboxHandler = createOutboxHandler(config, keypair)
   const outboxPostHandler = createOutboxPostHandler(config, keypair)
-  fastify.get('/profile/card/outbox', outboxHandler)
-  fastify.post('/profile/card/outbox', outboxPostHandler)
+  fastify.get('/profile/card.jsonld/outbox', outboxHandler)
+  fastify.post('/profile/card.jsonld/outbox', outboxPostHandler)
 
   // Followers/Following collections
   const collectionsHandler = createCollectionsHandler(config)
-  fastify.get('/profile/card/followers', (req, reply) => collectionsHandler(req, reply, 'followers'))
-  fastify.get('/profile/card/following', (req, reply) => collectionsHandler(req, reply, 'following'))
+  fastify.get('/profile/card.jsonld/followers', (req, reply) => collectionsHandler(req, reply, 'followers'))
+  fastify.get('/profile/card.jsonld/following', (req, reply) => collectionsHandler(req, reply, 'following'))
 
   // Mastodon-compatible API endpoints
   fastify.post('/api/v1/apps', createAppsHandler())

package/src/ap/keys.js

@@ -52,8 +52,8 @@ export function loadOrCreateKeypair(path = DEFAULT_KEY_PATH) {
 
 /**
  * Get key ID for HTTP Signatures
- * @param {string} actorId - Actor URL (e.g., https://example.com/profile/card#me)
- * @returns {string} Key ID (e.g., https://example.com/profile/card#main-key)
+ * @param {string} actorId - Actor URL (e.g., https://example.com/profile/card.jsonld#me)
+ * @returns {string} Key ID (e.g., https://example.com/profile/card.jsonld#main-key)
  */
 export function getKeyId(actorId) {
   // Strip fragment and add #main-key

package/src/ap/routes/actor.js

@@ -30,7 +30,7 @@ export function createActorHandler(config, keypair) {
     }
     protocol = protocol || request.protocol
     const baseUrl = `${protocol}://${host}`
-    const profileUrl = `${baseUrl}/profile/card`
+    const profileUrl = `${baseUrl}/profile/card.jsonld`
     const actorId = `${profileUrl}#me`
 
     const actor = {

package/src/ap/routes/collections.js

@@ -15,7 +15,7 @@ export function createCollectionsHandler(config) {
     const protocol = request.headers['x-forwarded-proto'] || request.protocol
     const host = request.headers['x-forwarded-host'] || request.hostname
     const baseUrl = `${protocol}://${host}`
-    const profileUrl = `${baseUrl}/profile/card`
+    const profileUrl = `${baseUrl}/profile/card.jsonld`
 
     let items, totalItems
 

package/src/ap/routes/inbox.js

@@ -150,7 +150,7 @@ export function createInboxHandler(config, keypair) {
     const protocol = request.headers['x-forwarded-proto'] || request.protocol
     const host = request.headers['x-forwarded-host'] || request.hostname
     const baseUrl = `${protocol}://${host}`
-    const profileUrl = `${baseUrl}/profile/card`
+    const profileUrl = `${baseUrl}/profile/card.jsonld`
     const actorId = `${profileUrl}#me`
 
     request.log.info(`Received ${activity.type} from ${activity.actor}`)

package/src/ap/routes/mastodon.js

@@ -78,8 +78,8 @@ export function createVerifyCredentialsHandler (config) {
       acct: config.username,
       display_name: config.displayName,
       note: config.summary ? `<p>${escapeHtml(config.summary)}</p>` : '',
-      url: `${baseUrl}/profile/card`,
-      uri: `${baseUrl}/profile/card#me`,
+      url: `${baseUrl}/profile/card.jsonld`,
+      uri: `${baseUrl}/profile/card.jsonld#me`,
       avatar: `${baseUrl}/profile/avatar.png`,
       header: '',
       locked: false,

package/src/ap/routes/outbox.js

@@ -19,7 +19,7 @@ export function createOutboxHandler(config, keypair) {
     const protocol = request.headers['x-forwarded-proto'] || request.protocol
     const host = request.headers['x-forwarded-host'] || request.hostname
     const baseUrl = `${protocol}://${host}`
-    const profileUrl = `${baseUrl}/profile/card`
+    const profileUrl = `${baseUrl}/profile/card.jsonld`
     const actorId = `${profileUrl}#me`
 
     const posts = getPosts(20)
@@ -63,7 +63,7 @@ export function createOutboxPostHandler(config, keypair) {
     const protocol = request.headers['x-forwarded-proto'] || request.protocol
     const host = request.headers['x-forwarded-host'] || request.hostname
     const baseUrl = `${protocol}://${host}`
-    const profileUrl = `${baseUrl}/profile/card`
+    const profileUrl = `${baseUrl}/profile/card.jsonld`
     const actorId = `${profileUrl}#me`
 
     // Parse body

package/src/auth/token-secret.js

@@ -0,0 +1,122 @@
+/**
+ * TOKEN_SECRET resolution.
+ *
+ * Extracted from token.js so it can be unit-tested without pulling in the
+ * full auth graph (solid-oidc, nostr, webid-tls), which does module-level
+ * work that keeps the node:test event loop busy.
+ */
+
+import crypto from 'crypto';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+export const DEFAULT_SECRET_PATH = path.join(os.homedir(), '.jss', 'token.secret');
+
+// Tighten permissions on POSIX, best-effort. No-op on Windows (ACLs) and
+// on read-only filesystems — we never want perm-tightening to block using
+// an otherwise-valid secret.
+function chmodBestEffort(target, mode) {
+  try {
+    fs.chmodSync(target, mode);
+  } catch {
+    // Intentionally swallow — perms are defensive hardening, not required.
+  }
+}
+
+/**
+ * Read a persisted secret from `filePath`, or generate one and write it
+ * (with dir mode 0700 and file mode 0600) if the file is missing.
+ *
+ * Read-first: if the file already exists and is non-empty we return it
+ * without trying to mkdir or tighten the containing directory. Deployments
+ * with a pre-provisioned secret on a read-only filesystem boot cleanly.
+ *
+ * Concurrent-startup safe: new secrets are written to a per-process temp
+ * file in the same directory and `renameSync`'d into place, so another
+ * process reading the target never sees a half-written file. If a peer
+ * process won the rename we fall back to reading their value.
+ *
+ * Anything other than ENOENT on the initial read (permission denied,
+ * corrupt FS, …) propagates.
+ */
+export function readOrWritePersistedSecret(filePath = DEFAULT_SECRET_PATH) {
+  const dir = path.dirname(filePath);
+
+  // Fast path: pre-existing non-empty file. We do not mkdir the parent
+  // dir here, and perm-tightening is best-effort (chmodBestEffort swallows
+  // all errors), so a pre-provisioned secret on a read-only filesystem
+  // still boots cleanly.
+  try {
+    const existing = fs.readFileSync(filePath, 'utf8').trim();
+    if (existing) {
+      chmodBestEffort(dir, 0o700);
+      chmodBestEffort(filePath, 0o600);
+      return existing;
+    }
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+
+  // Slow path: create it. Only touch the FS with writes from here on.
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodBestEffort(dir, 0o700);
+
+  const generated = crypto.randomBytes(32).toString('hex');
+  // Atomic write: fully write a temp file, then rename into place. On
+  // POSIX the rename is atomic, so concurrent readers see either the old
+  // content or the new complete content — never a half-written file.
+  const tmpPath = `${filePath}.${crypto.randomBytes(8).toString('hex')}.tmp`;
+  try {
+    fs.writeFileSync(tmpPath, generated, { mode: 0o600 });
+    fs.renameSync(tmpPath, filePath);
+  } catch (e) {
+    try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
+    throw e;
+  }
+  chmodBestEffort(filePath, 0o600);
+
+  // Multiple processes racing each produce a different secret; only the
+  // last renamer's value sticks on disk. Re-read so every process ends up
+  // using the winning secret and token verification stays consistent.
+  const persisted = fs.readFileSync(filePath, 'utf8').trim();
+  return persisted || generated;
+}
+
+/**
+ * Resolve the token secret.
+ *
+ *   1. TOKEN_SECRET env → use it.
+ *   2. Else read/create ~/.jss/token.secret.
+ *   3. On file-write failure: hard-exit in production, ephemeral secret otherwise.
+ *
+ * Console I/O is injected so tests can assert log behaviour without spamming
+ * the real console; defaults to the real console.
+ */
+export function resolveTokenSecret({
+  env = process.env,
+  secretPath = DEFAULT_SECRET_PATH,
+  log = console,
+  exit = (code) => process.exit(code),
+} = {}) {
+  if (env.TOKEN_SECRET) return env.TOKEN_SECRET;
+
+  try {
+    const s = readOrWritePersistedSecret(secretPath);
+    log.warn(`Using persisted TOKEN_SECRET at ${secretPath} (set TOKEN_SECRET env var to override).`);
+    return s;
+  } catch (e) {
+    if (env.NODE_ENV === 'production') {
+      const code = e?.code ? ` [${e.code}]` : '';
+      log.error(`SECURITY ERROR: TOKEN_SECRET not set and ${secretPath} could not be read or created${code} (${e.message}).`);
+      log.error(`Set TOKEN_SECRET explicitly, or grant the necessary access to ${path.dirname(secretPath)}.`);
+      exit(1);
+      // `exit` is injectable; if a caller stubs it out we must not silently
+      // return undefined and let downstream code use an invalid secret.
+      throw new Error(`Failed to resolve TOKEN_SECRET in production: ${e.message}`);
+    }
+    const ephemeral = crypto.randomBytes(32).toString('hex');
+    log.warn(`WARNING: Could not persist TOKEN_SECRET (${e.message}). Using ephemeral secret; tokens will not survive restarts.`);
+    return ephemeral;
+  }
+}

package/src/auth/token.js

@@ -11,30 +11,11 @@ import crypto from 'crypto';
 import { verifySolidOidc, hasSolidOidcAuth } from './solid-oidc.js';
 import { verifyNostrAuth, hasNostrAuth } from './nostr.js';
 import { webIdTlsAuth, hasClientCertificate } from './webid-tls.js';
+import { resolveTokenSecret } from './token-secret.js';
 
-// Secret for signing tokens
-// SECURITY: In production, TOKEN_SECRET must be set via environment variable
-const getSecret = () => {
-  if (process.env.TOKEN_SECRET) {
-    return process.env.TOKEN_SECRET;
-  }
-
-  // In production (NODE_ENV=production), require explicit secret
-  if (process.env.NODE_ENV === 'production') {
-    console.error('SECURITY ERROR: TOKEN_SECRET environment variable must be set in production');
-    console.error('Generate one with: node -e "console.log(require(\'crypto\').randomBytes(32).toString(\'hex\'))"');
-    process.exit(1);
-  }
-
-  // In development, generate a random secret per process (tokens won't survive restarts)
-  const devSecret = crypto.randomBytes(32).toString('hex');
-  console.warn('WARNING: No TOKEN_SECRET set. Using random secret (tokens will not survive restarts).');
-  console.warn('Set TOKEN_SECRET environment variable for persistent tokens.');
-  return devSecret;
-};
-
-// Initialize secret once at module load
-const SECRET = getSecret();
+// Initialize secret once at module load. See token-secret.js for the
+// resolution order (env → ~/.jss/token.secret → exit-or-ephemeral).
+const SECRET = resolveTokenSecret();
 
 /**
  * Create a simple token for a WebID

package/src/db/index.js

@@ -59,8 +59,8 @@ export async function dbPlugin(fastify, options) {
     if (podName) {
       // Build expected WebID for both path and subdomain modes
       const expectedWebId = request.subdomainsEnabled && request.baseDomain
-        ? `${request.protocol}://${podName}.${request.baseDomain}/profile/card#me`
-        : `${request.protocol}://${request.hostname}/${podName}/profile/card#me`;
+        ? `${request.protocol}://${podName}.${request.baseDomain}/profile/card.jsonld#me`
+        : `${request.protocol}://${request.hostname}/${podName}/profile/card.jsonld#me`;
       if (webId !== expectedWebId) {
         return reply.code(403).send({ error: 'Forbidden', message: 'You can only write to your own /db/ space' });
       }

package/src/handlers/container.js

@@ -173,20 +173,20 @@ export async function createPodStructure(name, webId, podUri, issuer, defaultQuo
   await storage.createContainer(`${podPath}settings/`);
   await storage.createContainer(`${podPath}profile/`);
 
-  // Generate and write WebID profile at /profile/card (standard Solid location)
-  const profileHtml = generateProfile({ webId, name, podUri, issuer });
-  await storage.write(`${podPath}profile/card`, profileHtml);
+  // Generate and write WebID profile at /profile/card.jsonld
+  const profile = generateProfile({ webId, name, podUri, issuer });
+  await storage.write(`${podPath}profile/card.jsonld`, serialize(profile));
 
-  // Generate and write preferences (mashlib-compatible paths)
+  // Generate and write preferences
   const prefs = generatePreferences({ webId, podUri });
-  await storage.write(`${podPath}settings/Preferences.ttl`, serialize(prefs));
+  await storage.write(`${podPath}settings/prefs.jsonld`, serialize(prefs));
 
-  // Generate and write type indexes with .ttl extension for mashlib
-  const publicTypeIndex = generateTypeIndex(`${podUri}settings/publicTypeIndex.ttl`);
-  await storage.write(`${podPath}settings/publicTypeIndex.ttl`, serialize(publicTypeIndex));
+  // Generate and write type indexes
+  const publicTypeIndex = generateTypeIndex(`${podUri}settings/publicTypeIndex.jsonld`);
+  await storage.write(`${podPath}settings/publicTypeIndex.jsonld`, serialize(publicTypeIndex));
 
-  const privateTypeIndex = generateTypeIndex(`${podUri}settings/privateTypeIndex.ttl`);
-  await storage.write(`${podPath}settings/privateTypeIndex.ttl`, serialize(privateTypeIndex));
+  const privateTypeIndex = generateTypeIndex(`${podUri}settings/privateTypeIndex.jsonld`);
+  await storage.write(`${podPath}settings/privateTypeIndex.jsonld`, serialize(privateTypeIndex));
 
   // Create default ACL files
   // Pod root: owner full control, public read
@@ -229,13 +229,13 @@ export async function createPodStructure(name, webId, podUri, issuer, defaultQuo
  *
  * Creates the following structure:
  *   /{name}/
- *   /{name}/profile/card     - WebID profile
- *   /{name}/inbox/           - Notifications
- *   /{name}/public/          - Public files
- *   /{name}/private/         - Private files
- *   /{name}/settings/prefs   - Preferences
- *   /{name}/settings/publicTypeIndex
- *   /{name}/settings/privateTypeIndex
+ *   /{name}/profile/card.jsonld          - WebID profile
+ *   /{name}/inbox/                       - Notifications
+ *   /{name}/public/                      - Public files
+ *   /{name}/private/                     - Private files
+ *   /{name}/settings/prefs.jsonld        - Preferences
+ *   /{name}/settings/publicTypeIndex.jsonld
+ *   /{name}/settings/privateTypeIndex.jsonld
  */
 export async function handleCreatePod(request, reply) {
   // Read-only mode - block pod creation
@@ -272,23 +272,22 @@ export async function handleCreatePod(request, reply) {
     return reply.code(409).send({ error: 'Pod already exists' });
   }
 
-  // Build URIs
-  // WebID follows standard Solid convention: /alice/profile/card#me
+  // Build URIs. WebID is the JSON-LD profile with an #me fragment.
   const subdomainsEnabled = request.subdomainsEnabled;
   const baseDomain = request.baseDomain;
 
   let baseUri, podUri, webId;
   if (subdomainsEnabled && baseDomain) {
-    // Subdomain mode: alice.example.com/profile/card#me
+    // Subdomain mode: alice.example.com/profile/card.jsonld#me
     const podHost = `${name}.${baseDomain}`;
     baseUri = `${request.protocol}://${baseDomain}`;
     podUri = `${request.protocol}://${podHost}/`;
-    webId = `${podUri}profile/card#me`;
+    webId = `${podUri}profile/card.jsonld#me`;
   } else {
-    // Path mode: example.com/alice/profile/card#me
+    // Path mode: example.com/alice/profile/card.jsonld#me
     baseUri = `${request.protocol}://${request.hostname}`;
     podUri = `${baseUri}${podPath}`;
-    webId = `${podUri}profile/card#me`;
+    webId = `${podUri}profile/card.jsonld#me`;
   }
 
   // Issuer needs trailing slash for CTH compatibility

package/src/idp/interactions.js

@@ -405,20 +405,20 @@ export async function handleRegisterPost(request, reply, issuer, inviteOnly = fa
   }
 
   try {
-    // Build URLs - WebID follows standard Solid convention: /profile/card#me
+    // Build URLs. WebID is the JSON-LD profile with an #me fragment.
     const subdomainsEnabled = request.subdomainsEnabled;
     const baseDomain = request.baseDomain;
     const baseUrl = issuer.endsWith('/') ? issuer.slice(0, -1) : issuer;
 
     let podUri, webId;
     if (subdomainsEnabled && baseDomain) {
-      // Subdomain mode: alice.example.com/profile/card#me
+      // Subdomain mode: alice.example.com/profile/card.jsonld#me
       podUri = `${request.protocol}://${username}.${baseDomain}/`;
-      webId = `${podUri}profile/card#me`;
+      webId = `${podUri}profile/card.jsonld#me`;
     } else {
-      // Path mode: example.com/alice/profile/card#me
+      // Path mode: example.com/alice/profile/card.jsonld#me
       podUri = `${baseUrl}/${username}/`;
-      webId = `${podUri}profile/card#me`;
+      webId = `${podUri}profile/card.jsonld#me`;
     }
 
     // Check if pod already exists

package/src/server.js

@@ -314,12 +314,12 @@ export function createServer(options = {}) {
     // Note: OPTIONS requests are handled by handleOptions to include Accept-* headers
   });
 
-  // ActivityPub actor endpoint - dedicated route for /profile/card with AP Accept header
+  // 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',
+      url: '/profile/card.jsonld',
       handler: async (request, reply) => {
         const accept = request.headers.accept || '';
         const wantsAP = accept.includes('activity+json') ||
@@ -426,13 +426,13 @@ export function createServer(options = {}) {
   fastify.addHook('preHandler', async (request, reply) => {
     // Skip auth for pod creation, OPTIONS, IdP routes, mashlib, well-known, notifications, nostr, git, and AP
     const mashlibPaths = ['/mashlib.min.js', '/mash.css', '/841.mashlib.min.js'];
-    const apPaths = ['/inbox', '/profile/card/inbox', '/profile/card/outbox', '/profile/card/followers', '/profile/card/following',
+    const apPaths = ['/inbox', '/profile/card.jsonld/inbox', '/profile/card.jsonld/outbox', '/profile/card.jsonld/followers', '/profile/card.jsonld/following',
       '/api/v1/apps', '/api/v1/instance', '/api/v1/accounts/verify_credentials',
       '/oauth/authorize', '/oauth/token'];
     // Check if request wants ActivityPub content for profile
     const accept = request.headers.accept || '';
     const wantsAP = accept.includes('activity+json') || accept.includes('ld+json; profile="https://www.w3.org/ns/activitystreams"');
-    const isProfileAP = activitypubEnabled && wantsAP && (request.url === '/profile/card' || request.url.startsWith('/profile/card?'));
+    const isProfileAP = activitypubEnabled && wantsAP && (request.url === '/profile/card.jsonld' || request.url.startsWith('/profile/card.jsonld?'));
     if (request.url === '/.pods' ||
         request.url === '/.notifications' ||
         request.method === 'OPTIONS' ||
@@ -557,11 +557,15 @@ export function createServer(options = {}) {
       const isRootPod = !singleUserName || singleUserName === '/';
       const podPath = isRootPod ? '/' : `/${singleUserName}/`;
       const podUri = isRootPod ? `${baseUrl}/` : `${baseUrl}/${singleUserName}/`;
-      const webId = `${podUri}profile/card#me`;
+      const webId = `${podUri}profile/card.jsonld#me`;
       const displayName = isRootPod ? 'me' : singleUserName;
 
-      // Check if pod already exists (profile/card is the indicator)
-      const profileExists = await storage.exists(`${podPath}profile/card`);
+      // Check if pod already exists. Accept either the new `card.jsonld`
+      // or legacy extensionless `card` layout so we don't re-seed a pod
+      // that was created by an older JSS version.
+      const profileExists =
+        await storage.exists(`${podPath}profile/card.jsonld`) ||
+        await storage.exists(`${podPath}profile/card`);
 
       if (!profileExists) {
         fastify.log.info(`Creating single-user pod at ${podUri}...`);
@@ -593,18 +597,18 @@ export function createServer(options = {}) {
     await storage.createContainer('/profile/');
 
     // Generate profile
-    const profileHtml = generateProfile({ webId, name: displayName, podUri, issuer });
-    await storage.write('/profile/card', profileHtml);
+    const profile = generateProfile({ webId, name: displayName, podUri, issuer });
+    await storage.write('/profile/card.jsonld', serialize(profile));
 
     // Preferences and type indexes
     const prefs = generatePreferences({ webId, podUri });
-    await storage.write('/settings/Preferences.ttl', serialize(prefs));
+    await storage.write('/settings/prefs.jsonld', serialize(prefs));
 
-    const publicTypeIndex = generateTypeIndex(`${podUri}settings/publicTypeIndex.ttl`);
-    await storage.write('/settings/publicTypeIndex.ttl', serialize(publicTypeIndex));
+    const publicTypeIndex = generateTypeIndex(`${podUri}settings/publicTypeIndex.jsonld`);
+    await storage.write('/settings/publicTypeIndex.jsonld', serialize(publicTypeIndex));
 
-    const privateTypeIndex = generateTypeIndex(`${podUri}settings/privateTypeIndex.ttl`);
-    await storage.write('/settings/privateTypeIndex.ttl', serialize(privateTypeIndex));
+    const privateTypeIndex = generateTypeIndex(`${podUri}settings/privateTypeIndex.jsonld`);
+    await storage.write('/settings/privateTypeIndex.jsonld', serialize(privateTypeIndex));
 
     // ACL files
     const rootAcl = generateOwnerAcl(podUri, webId, true);

package/src/webid/profile.js

@@ -1,7 +1,10 @@
 /**
  * WebID Profile generation
- * Creates profile documents following Solid conventions
- * Profile is HTML with embedded JSON-LD structured data
+ *
+ * Creates profile documents following Solid conventions. Default profile
+ * shape is now plain JSON-LD at `profile/card.jsonld` — operators who
+ * want a human-readable HTML shell can serve their own `index.html` with
+ * an embedded `<script type="application/ld+json">` data island.
  */
 
 const FOAF = 'http://xmlns.com/foaf/0.1/';
@@ -45,95 +48,33 @@ export function generateProfileJsonLd({ webId, name, podUri, issuer }) {
     'inbox': `${pod}inbox/`,
     'storage': pod,
     'oidcIssuer': issuer,
-    'preferencesFile': `${pod}settings/Preferences.ttl`,
-    'publicTypeIndex': `${pod}settings/publicTypeIndex.ttl`,
-    'privateTypeIndex': `${pod}settings/privateTypeIndex.ttl`
+    'preferencesFile': `${pod}settings/prefs.jsonld`,
+    'publicTypeIndex': `${pod}settings/publicTypeIndex.jsonld`,
+    'privateTypeIndex': `${pod}settings/privateTypeIndex.jsonld`
   };
 }
 
 /**
- * Generate HTML profile with embedded JSON-LD data island
- * The page uses mashlib + solidos-lite to render the profile from the data island
+ * Generate the profile document as a plain JSON-LD object.
+ *
+ * Previously returned an HTML shell with an embedded data island; that
+ * shell still exists for hand-curated personal sites, but server-default
+ * profiles are now plain JSON-LD for predictability and easier
+ * post-processing by clients.
+ *
  * @param {object} options
  * @param {string} options.webId - Full WebID URI
  * @param {string} options.name - Display name
  * @param {string} options.podUri - Pod root URI
  * @param {string} options.issuer - OIDC issuer URI
- * @returns {string} HTML document with JSON-LD data island
+ * @returns {object} JSON-LD profile document
  */
 export function generateProfile({ webId, name, podUri, issuer }) {
-  const jsonLd = generateProfileJsonLd({ webId, name, podUri, issuer });
-
-  return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>${escapeHtml(name)}'s Profile</title>
-  <link rel="stylesheet" href="https://javascriptsolidserver.github.io/mashlib-jss/dist/mash.css">
-  <script type="application/ld+json">
-${JSON.stringify(jsonLd, null, 2)}
-  </script>
-  <style>
-    body { margin: 0; font-family: system-ui, sans-serif; }
-    .loading { padding: 2rem; text-align: center; color: #666; }
-  </style>
-</head>
-<body>
-  <div class="TabulatorOutline" id="DummyUUID" role="main">
-    <table id="outline"></table>
-    <div id="GlobalDashboard"></div>
-  </div>
-  <div class="loading" id="loading">Loading profile...</div>
-
-  <script src="https://javascriptsolidserver.github.io/mashlib-jss/dist/mashlib.min.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/solidos-lite/solidos-lite.js"></script>
-  <script>
-  document.addEventListener('DOMContentLoaded', function() {
-    const loadingEl = document.getElementById('loading');
-
-    // Initialize solidos-lite to handle data islands
-    const success = SolidOSLite.init({ verbose: false });
-    if (!success) {
-      loadingEl.textContent = 'Failed to initialize. Please try refreshing.';
-      return;
-    }
-
-    // Parse data islands into the RDF store
-    SolidOSLite.parseAllIslands();
-
-    // Mark this document as already fetched
-    const pageBase = window.location.href.split('?')[0].split('#')[0];
-    const fetcher = SolidLogic.store.fetcher;
-    fetcher.requested[pageBase] = 'done';
-    fetcher.requested[pageBase.replace(/\\/$/, '')] = 'done';
-
-    // Navigate to #me
-    const subject = $rdf.sym(pageBase + '#me');
-    const outliner = panes.getOutliner(document);
-    outliner.GotoSubject(subject, true, undefined, true, undefined);
-
-    loadingEl.style.display = 'none';
-  });
-  </script>
-</body>
-</html>`;
-}
-
-/**
- * Escape HTML entities
- */
-function escapeHtml(str) {
-  return str
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;');
+  return generateProfileJsonLd({ webId, name, podUri, issuer });
 }
 
 /**
- * Generate preferences file as JSON-LD
- * Uses mashlib-compatible paths (settings/Preferences.ttl)
+ * Generate preferences file as JSON-LD.
  * @param {object} options
  * @param {string} options.webId - Full WebID URI
  * @param {string} options.podUri - Pod root URI
@@ -149,9 +90,9 @@ export function generatePreferences({ webId, podUri }) {
       'publicTypeIndex': { '@id': 'solid:publicTypeIndex', '@type': '@id' },
       'privateTypeIndex': { '@id': 'solid:privateTypeIndex', '@type': '@id' }
     },
-    '@id': `${pod}settings/Preferences.ttl`,
-    'publicTypeIndex': `${pod}settings/publicTypeIndex.ttl`,
-    'privateTypeIndex': `${pod}settings/privateTypeIndex.ttl`
+    '@id': `${pod}settings/prefs.jsonld`,
+    'publicTypeIndex': `${pod}settings/publicTypeIndex.jsonld`,
+    'privateTypeIndex': `${pod}settings/privateTypeIndex.jsonld`
   };
 }
 

package/test/auth.test.js

@@ -173,7 +173,7 @@ describe('Authentication', () => {
           {
             '@id': '#owner',
             '@type': 'acl:Authorization',
-            'acl:agent': { '@id': `${baseUrl}/authuser1/profile/card#me` },
+            'acl:agent': { '@id': `${baseUrl}/authuser1/profile/card.jsonld#me` },
             'acl:accessTo': { '@id': `${baseUrl}/authuser1/authenticated-only/` },
             'acl:default': { '@id': `${baseUrl}/authuser1/authenticated-only/` },
             'acl:mode': [

package/test/pod.test.js

@@ -36,7 +36,7 @@ describe('Pod Lifecycle', () => {
 
       const data = await res.json();
       assert.strictEqual(data.name, 'alice');
-      assert.ok(data.webId.endsWith('/alice/profile/card#me'));
+      assert.ok(data.webId.endsWith('/alice/profile/card.jsonld#me'));
       assert.ok(data.podUri.endsWith('/alice/'));
     });
 
@@ -103,16 +103,16 @@ describe('Pod Lifecycle', () => {
     it('should create settings files', async () => {
       await createTestPod('dan');
 
-      // Check Preferences.ttl (needs auth - Settings is private)
-      const prefs = await request('/dan/settings/Preferences.ttl', { auth: 'dan' });
+      // Check prefs.jsonld (needs auth - settings is private)
+      const prefs = await request('/dan/settings/prefs.jsonld', { auth: 'dan' });
       assertStatus(prefs, 200);
 
       // Check public type index (needs auth)
-      const pubIndex = await request('/dan/settings/publicTypeIndex.ttl', { auth: 'dan' });
+      const pubIndex = await request('/dan/settings/publicTypeIndex.jsonld', { auth: 'dan' });
       assertStatus(pubIndex, 200);
 
       // Check private type index (needs auth)
-      const privIndex = await request('/dan/settings/privateTypeIndex.ttl', { auth: 'dan' });
+      const privIndex = await request('/dan/settings/privateTypeIndex.jsonld', { auth: 'dan' });
       assertStatus(privIndex, 200);
     });
   });

package/test/token-secret.test.js

@@ -0,0 +1,209 @@
+/**
+ * Unit tests for TOKEN_SECRET resolution (src/auth/token-secret.js).
+ *
+ * Covers #280: TOKEN_SECRET auto-persists on first run rather than hard-exiting.
+ */
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import {
+  readOrWritePersistedSecret,
+  resolveTokenSecret,
+  DEFAULT_SECRET_PATH,
+} from '../src/auth/token-secret.js';
+
+describe('readOrWritePersistedSecret', () => {
+  let tmpDir;
+  let secretPath;
+
+  before(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jss-token-secret-'));
+    secretPath = path.join(tmpDir, '.jss', 'token.secret');
+  });
+
+  after(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('generates + persists a secret when the file is missing', () => {
+    const s = readOrWritePersistedSecret(secretPath);
+    assert.strictEqual(typeof s, 'string');
+    assert.strictEqual(s.length, 64); // 32 bytes, hex-encoded
+    assert.strictEqual(fs.readFileSync(secretPath, 'utf8').trim(), s);
+  });
+
+  it('returns the same secret on subsequent calls', () => {
+    const first  = readOrWritePersistedSecret(secretPath);
+    const second = readOrWritePersistedSecret(secretPath);
+    assert.strictEqual(first, second);
+  });
+
+  it('enforces tight permissions on POSIX (skipped on Windows)', { skip: process.platform === 'win32' }, () => {
+    const stat = fs.statSync(secretPath);
+    assert.strictEqual(stat.mode & 0o777, 0o600, 'secret file should be mode 0600');
+    const dirStat = fs.statSync(path.dirname(secretPath));
+    assert.strictEqual(dirStat.mode & 0o777, 0o700, 'secret dir should be mode 0700');
+  });
+
+  it('propagates errors other than ENOENT', () => {
+    // Use a regular file as the would-be parent directory — mkdirSync then
+    // fails with ENOTDIR synchronously. Portable across OSes.
+    const blockerFile = path.join(tmpDir, 'blocker-file');
+    fs.writeFileSync(blockerFile, 'not a dir');
+    const unwritable = path.join(blockerFile, '.jss', 'token.secret');
+    assert.throws(() => readOrWritePersistedSecret(unwritable));
+  });
+
+  it('recovers when the secret file already exists but is empty', () => {
+    // Simulates a concurrent or interrupted persistence case: the file
+    // is present (so the fast path falls through the trim-empty check)
+    // but carries no usable secret yet. tmp-file + renameSync repairs
+    // it by overwriting atomically.
+    const p = path.join(tmpDir, 'empty', '.jss', 'token.secret');
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, '');
+    const s = readOrWritePersistedSecret(p);
+    assert.strictEqual(s.length, 64);
+    assert.strictEqual(fs.readFileSync(p, 'utf8').trim(), s);
+  });
+
+  it('tightens permissions when the file already exists with loose mode', { skip: process.platform === 'win32' }, () => {
+    const p = path.join(tmpDir, 'loose', '.jss', 'token.secret');
+    fs.mkdirSync(path.dirname(p), { recursive: true, mode: 0o755 });
+    fs.writeFileSync(p, 'a'.repeat(64), { mode: 0o644 });
+    readOrWritePersistedSecret(p);
+    assert.strictEqual(fs.statSync(p).mode & 0o777, 0o600);
+    assert.strictEqual(fs.statSync(path.dirname(p)).mode & 0o777, 0o700);
+  });
+
+  it('reads a pre-existing secret even when the parent dir is not writable', { skip: process.platform === 'win32' || process.getuid?.() === 0 }, () => {
+    // Simulates a read-only deployment: secret provisioned ahead of time,
+    // parent dir not writable for the current user. Must not block startup.
+    const p = path.join(tmpDir, 'readonly-parent', '.jss', 'token.secret');
+    fs.mkdirSync(path.dirname(p), { recursive: true, mode: 0o700 });
+    const expected = 'b'.repeat(64);
+    fs.writeFileSync(p, expected);
+    fs.chmodSync(path.dirname(p), 0o500); // r-x, no write
+    try {
+      const s = readOrWritePersistedSecret(p);
+      assert.strictEqual(s, expected);
+    } finally {
+      fs.chmodSync(path.dirname(p), 0o700);  // let after()'s rmSync clean up
+    }
+  });
+});
+
+describe('resolveTokenSecret', () => {
+  let tmpDir;
+
+  before(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jss-resolve-secret-'));
+  });
+
+  after(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  const silentLog = { warn: () => {}, error: () => {} };
+
+  it('prefers TOKEN_SECRET env var', () => {
+    const s = resolveTokenSecret({
+      env: { TOKEN_SECRET: 'from-env' },
+      secretPath: path.join(tmpDir, 'unused', 'token.secret'),
+      log: silentLog,
+    });
+    assert.strictEqual(s, 'from-env');
+  });
+
+  it('persists a generated secret when env is unset', () => {
+    const p = path.join(tmpDir, 'persist', 'token.secret');
+    const s = resolveTokenSecret({ env: {}, secretPath: p, log: silentLog });
+    assert.strictEqual(s.length, 64);
+    assert.strictEqual(fs.readFileSync(p, 'utf8').trim(), s);
+  });
+
+  it('returns the same persisted secret on the next call', () => {
+    const p = path.join(tmpDir, 'persist-twice', 'token.secret');
+    const first  = resolveTokenSecret({ env: {}, secretPath: p, log: silentLog });
+    const second = resolveTokenSecret({ env: {}, secretPath: p, log: silentLog });
+    assert.strictEqual(first, second);
+  });
+
+  // Build an unwritable path by planting a regular file where the helper
+  // would try to mkdir a directory. mkdirSync then fails synchronously.
+  function buildUnwritable(name) {
+    const blocker = path.join(tmpDir, name, 'blocker-file');
+    fs.mkdirSync(path.dirname(blocker), { recursive: true });
+    fs.writeFileSync(blocker, 'not a dir');
+    return path.join(blocker, '.jss', 'token.secret');
+  }
+
+  it('hard-exits in production when persistence fails', () => {
+    let exitCode;
+    assert.throws(() => {
+      resolveTokenSecret({
+        env: { NODE_ENV: 'production' },
+        secretPath: buildUnwritable('prod'),
+        log: silentLog,
+        exit: (code) => { exitCode = code; },  // stubbed — doesn't actually terminate
+      });
+    });
+    // exit(1) must still have been invoked even though we throw afterwards,
+    // so a non-stubbed production process actually terminates.
+    assert.strictEqual(exitCode, 1);
+  });
+
+  it('throws after exit so a stubbed exit() cannot leak undefined downstream', () => {
+    // Regression: earlier versions returned undefined "for tests" after
+    // calling exit(), which could let callers continue with an invalid
+    // secret when exit is stubbed.
+    assert.throws(
+      () => resolveTokenSecret({
+        env: { NODE_ENV: 'production' },
+        secretPath: buildUnwritable('no-leak'),
+        log: silentLog,
+        exit: () => {},
+      }),
+      /TOKEN_SECRET/
+    );
+  });
+
+  it('production error message references the actual secret directory', () => {
+    const secretPath = buildUnwritable('custom-path');
+    const errors = [];
+    assert.throws(() => {
+      resolveTokenSecret({
+        env: { NODE_ENV: 'production' },
+        secretPath,
+        log: { warn: () => {}, error: (msg) => errors.push(msg) },
+        exit: () => {},
+      });
+    });
+    assert.ok(
+      errors.some(m => m.includes(path.dirname(secretPath))),
+      `expected an error to mention ${path.dirname(secretPath)}, got: ${errors.join(' | ')}`
+    );
+  });
+
+  it('falls back to an ephemeral secret outside production when persistence fails', () => {
+    const s = resolveTokenSecret({
+      env: {},
+      secretPath: buildUnwritable('dev'),
+      log: silentLog,
+      exit: () => { throw new Error('exit should not be called in dev') },
+    });
+    assert.strictEqual(typeof s, 'string');
+    assert.strictEqual(s.length, 64);
+  });
+});
+
+describe('DEFAULT_SECRET_PATH', () => {
+  it('is absolute and platform-native', () => {
+    assert.ok(path.isAbsolute(DEFAULT_SECRET_PATH));
+    assert.ok(DEFAULT_SECRET_PATH.includes('.jss'));
+    assert.ok(DEFAULT_SECRET_PATH.includes('token.secret'));
+  });
+});

package/test/webid.test.js

@@ -12,7 +12,6 @@ import {
   assertStatus,
   assertHeader,
   assertHeaderContains,
-  extractJsonLdFromHtml
 } from './helpers.js';
 
 describe('WebID Profile', () => {
@@ -30,87 +29,80 @@ describe('WebID Profile', () => {
   });
 
   describe('Profile Document', () => {
-    // Profile is at /pod/profile/card following Solid convention
-    const profilePath = '/webidtest/profile/card';
+    // Profile is now a plain JSON-LD doc at /pod/profile/card.jsonld.
+    const profilePath = '/webidtest/profile/card.jsonld';
 
-    it('should serve profile as HTML', async () => {
+    it('should serve profile as JSON-LD', async () => {
       const res = await request(profilePath);
 
       assertStatus(res, 200);
-      assertHeaderContains(res, 'Content-Type', 'text/html');
+      assertHeaderContains(res, 'Content-Type', 'application/ld+json');
     });
 
-    it('should contain JSON-LD structured data', async () => {
+    it('should be valid JSON-LD with @context and @id', async () => {
       const res = await request(profilePath);
-      const html = await res.text();
+      const jsonLd = await res.json();
 
-      const jsonLd = extractJsonLdFromHtml(html);
       assert.ok(jsonLd['@context'], 'Should have @context');
-      // Profile uses flat structure, not @graph
       assert.ok(jsonLd['@id'], 'Should have @id');
     });
 
     it('should have correct WebID URI', async () => {
       const res = await request(profilePath);
-      const html = await res.text();
-      const jsonLd = extractJsonLdFromHtml(html);
+      const jsonLd = await res.json();
 
-      // Profile is a flat structure with the person as the main entity
-      assert.ok(jsonLd['@id'].endsWith('/webidtest/profile/card#me'), 'WebID should end with /profile/card#me');
+      assert.ok(jsonLd['@id'].endsWith('/webidtest/profile/card.jsonld#me'),
+        `WebID should end with /profile/card.jsonld#me, got ${jsonLd['@id']}`);
     });
 
     it('should have foaf:name', async () => {
       const res = await request(profilePath);
-      const html = await res.text();
-      const jsonLd = extractJsonLdFromHtml(html);
+      const jsonLd = await res.json();
 
       assert.strictEqual(jsonLd['foaf:name'], 'webidtest');
     });
 
     it('should have solid:oidcIssuer', async () => {
       const res = await request(profilePath);
-      const html = await res.text();
-      const jsonLd = extractJsonLdFromHtml(html);
+      const jsonLd = await res.json();
 
       assert.ok(jsonLd['oidcIssuer'], 'Should have oidcIssuer');
     });
 
     it('should have pim:storage pointing to pod', async () => {
       const res = await request(profilePath);
-      const html = await res.text();
-      const jsonLd = extractJsonLdFromHtml(html);
+      const jsonLd = await res.json();
 
       assert.ok(jsonLd['storage'].endsWith('/webidtest/'), 'Storage should point to pod');
     });
 
     it('should have ldp:inbox', async () => {
       const res = await request(profilePath);
-      const html = await res.text();
-      const jsonLd = extractJsonLdFromHtml(html);
+      const jsonLd = await res.json();
 
       assert.ok(jsonLd['inbox'].endsWith('/webidtest/inbox/'), 'Should have inbox');
     });
 
     it('should have mainEntityOfPage', async () => {
       const res = await request(profilePath);
-      const html = await res.text();
-      const jsonLd = extractJsonLdFromHtml(html);
+      const jsonLd = await res.json();
 
-      // Check for mainEntityOfPage which links to the profile document
       assert.ok(jsonLd['mainEntityOfPage'], 'Should have mainEntityOfPage');
     });
   });
 
   describe('WebID Resolution', () => {
+    const profilePath = '/webidtest/profile/card.jsonld';
+
     it('should return LDP headers', async () => {
-      const res = await request('/webidtest/profile/card');
+      const res = await request(profilePath);
 
       assertHeaderContains(res, 'Link', 'ldp#Resource');
       assertHeader(res, 'WAC-Allow');
     });
 
     it('should return CORS headers', async () => {
-      const res = await request('/webidtest/profile/card', {
+      const res = await request(profilePath, {
         headers: { 'Origin': 'https://example.com' }
       });