javascript-solid-server 0.0.117 → 0.0.119

package/README.md

@@ -24,6 +24,8 @@ A minimal, fast, JSON-LD native Solid server.
 - **MongoDB Storage** — Optional `/db/` route for JSON-LD at scale
 - **WebRTC Signaling** — Peer-to-peer connections via WebID-authenticated signaling
 - **Tunnel Proxy** — Decentralized ngrok through your pod
+- **Terminal** — WebSocket shell access via `--terminal`
+- **Password CLI** — `jss passwd` for user password management
 - **HTTP 402 Payments** — Monetize endpoints with per-request sat payments
 - **Mashlib / SolidOS UI** — Optional data browser (CDN, local, or ES module)
 - **Storage Quotas** — Per-user limits with CLI management
@@ -79,9 +81,10 @@ jss start [options]    # Start the server
 jss init [options]     # Initialize configuration
 jss invite <cmd>       # Manage invite codes
 jss quota <cmd>        # Manage storage quotas
+jss passwd <username>  # Manage user passwords
 ```
 
-Key options: `--port`, `--idp`, `--conneg`, `--mashlib`, `--git`, `--nostr`, `--activitypub`, `--webrtc`, `--tunnel`, `--mongo`, `--pay`, `--public`, `--single-user`
+Key options: `--port`, `--idp`, `--conneg`, `--mashlib`, `--git`, `--nostr`, `--activitypub`, `--webrtc`, `--tunnel`, `--terminal`, `--mongo`, `--pay`, `--public`, `--single-user`
 
 Full options: [docs/configuration.md](docs/configuration.md)
 
@@ -98,6 +101,7 @@ Full options: [docs/configuration.md](docs/configuration.md)
 | ActivityPub & Mastodon API | [docs/activitypub.md](docs/activitypub.md) |
 | remoteStorage | [docs/remotestorage.md](docs/remotestorage.md) |
 | WebRTC & Tunnel | [docs/webrtc.md](docs/webrtc.md) |
+| Terminal & Password CLI | [docs/terminal.md](docs/terminal.md) |
 | MongoDB `/db/` Route | [docs/mongodb.md](docs/mongodb.md) |
 | HTTP 402 Payments | [docs/payments.md](docs/payments.md) |
 | Storage Quotas | [docs/quotas.md](docs/quotas.md) |

package/bin/jss.js

@@ -6,6 +6,7 @@
  * Usage:
  *   jss start [options]    Start the server
  *   jss init               Initialize configuration
+ *   jss passwd <username>  Change user password
  */
 
 import { Command } from 'commander';
@@ -14,6 +15,7 @@ import { loadConfig, saveConfig, printConfig, defaults } from '../src/config.js'
 import { createInvite, listInvites, revokeInvite } from '../src/idp/invites.js';
 import { setQuotaLimit, getQuotaInfo, reconcileQuota, formatBytes } from '../src/storage/quota.js';
 import { parseSize } from '../src/config.js';
+import crypto from 'crypto';
 import fs from 'fs-extra';
 import path from 'path';
 import { fileURLToPath } from 'url';
@@ -66,6 +68,8 @@ program
   .option('--webrtc', 'Enable WebRTC signaling server')
   .option('--no-webrtc', 'Disable WebRTC signaling server')
   .option('--webrtc-path <path>', 'WebRTC signaling WebSocket path (default: /.webrtc)')
+  .option('--terminal', 'Enable WebSocket terminal (shell access)')
+  .option('--no-terminal', 'Disable WebSocket terminal')
   .option('--tunnel', 'Enable tunnel proxy (decentralized ngrok)')
   .option('--no-tunnel', 'Disable tunnel proxy')
   .option('--tunnel-path <path>', 'Tunnel WebSocket path (default: /.tunnel)')
@@ -147,6 +151,7 @@ program
         nostrMaxEvents: config.nostrMaxEvents,
         webrtc: config.webrtc,
         webrtcPath: config.webrtcPath,
+        terminal: config.terminal,
         tunnel: config.tunnel,
         tunnelPath: config.tunnelPath,
         activitypub: config.activitypub,
@@ -193,6 +198,7 @@ program
         if (config.git) console.log('  Git: enabled (clone/push support)');
         if (config.nostr) console.log(`  Nostr: enabled (${config.nostrPath})`);
         if (config.webrtc) console.log(`  WebRTC: enabled (${config.webrtcPath || '/.webrtc'})`);
+        if (config.terminal) console.log('  Terminal: enabled (/.terminal)');
         if (config.tunnel) console.log(`  Tunnel: enabled (${config.tunnelPath || '/.tunnel'})`);
         if (config.activitypub) console.log(`  ActivityPub: enabled (@${config.apUsername || 'me'})`);
         if (config.singleUser) console.log(`  Single-user: ${config.singleUserName || 'me'} (registration disabled)`);
@@ -616,6 +622,134 @@ tokenCmd
     }
   });
 
+/**
+ * Passwd command - change a user's password
+ */
+program
+  .command('passwd <username>')
+  .description('Change password for a user account')
+  .option('-p, --password <password>', 'New password (non-interactive)')
+  .option('-g, --generate', 'Generate a random password')
+  .option('-r, --root <path>', 'Data directory')
+  .action(async (username, options) => {
+    try {
+      if (options.root) {
+        process.env.DATA_ROOT = path.resolve(options.root);
+      }
+
+      // Load account by username
+      const dataRoot = process.env.DATA_ROOT || './data';
+      const accountsDir = path.join(dataRoot, '.idp', 'accounts');
+      const indexPath = path.join(accountsDir, '_username_index.json');
+
+      let usernameIndex;
+      try {
+        usernameIndex = await fs.readJson(indexPath);
+      } catch (err) {
+        if (err.code === 'ENOENT') {
+          console.error(`Error: No accounts found (missing ${indexPath})`);
+          process.exit(1);
+        }
+        throw err;
+      }
+
+      const normalizedUsername = username.toLowerCase().trim();
+      const accountId = usernameIndex[normalizedUsername];
+      if (!accountId) {
+        console.error(`Error: User not found: ${username}`);
+        process.exit(1);
+      }
+
+      const accountPath = path.join(accountsDir, `${accountId}.json`);
+      const account = await fs.readJson(accountPath);
+
+      // Determine new password
+      let newPassword;
+
+      if (options.generate) {
+        newPassword = crypto.randomBytes(16).toString('base64url');
+      } else if (options.password) {
+        newPassword = options.password;
+      } else {
+        // Interactive prompt
+        newPassword = await promptPassword('New password: ');
+        const confirm = await promptPassword('Confirm password: ');
+        if (newPassword !== confirm) {
+          console.error('Error: Passwords do not match');
+          process.exit(1);
+        }
+      }
+
+      if (!newPassword) {
+        console.error('Error: Password cannot be empty');
+        process.exit(1);
+      }
+
+      // Hash and save
+      const bcrypt = await import('bcryptjs').then(m => m.default);
+      account.passwordHash = await bcrypt.hash(newPassword, 10);
+      account.passwordChangedAt = new Date().toISOString();
+      await fs.writeJson(accountPath, account, { spaces: 2 });
+
+      if (options.generate) {
+        console.log(`\nPassword updated for ${normalizedUsername}`);
+        console.log(`Generated password: ${newPassword}\n`);
+      } else {
+        console.log(`\nPassword updated for ${normalizedUsername}\n`);
+      }
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+  });
+
+/**
+ * Helper: Prompt for a password (hidden input)
+ */
+async function promptPassword(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  return new Promise((resolve) => {
+    // Disable echo for password input
+    if (process.stdin.isTTY) {
+      process.stdout.write(`  ${question}`);
+      const stdin = process.openStdin();
+      process.stdin.setRawMode(true);
+      let password = '';
+      const onData = (ch) => {
+        const c = ch.toString('utf8');
+        if (c === '\n' || c === '\r' || c === '\u0004') {
+          process.stdin.setRawMode(false);
+          process.stdin.removeListener('data', onData);
+          process.stdout.write('\n');
+          rl.close();
+          resolve(password);
+        } else if (c === '\u0003') {
+          // Ctrl+C
+          process.exit(0);
+        } else if (c === '\u007f' || c === '\b') {
+          // Backspace
+          if (password.length > 0) {
+            password = password.slice(0, -1);
+          }
+        } else {
+          password += c;
+        }
+      };
+      process.stdin.on('data', onData);
+    } else {
+      // Non-TTY: read line normally (piped input)
+      rl.question(`  ${question}`, (answer) => {
+        rl.close();
+        resolve(answer.trim());
+      });
+    }
+  });
+}
+
 /**
  * Helper: Prompt for input
  */

package/docs/configuration.md

@@ -177,6 +177,7 @@ Server: pub http://localhost:3000/alice/public/data.json  (on change)
 | `--webrtc-path <path>` | WebRTC signaling WebSocket path | /.webrtc |
 | `--tunnel` | Enable tunnel proxy (decentralized ngrok) | false |
 | `--tunnel-path <path>` | Tunnel WebSocket path | /.tunnel |
+| `--terminal` | Enable WebSocket shell at `/.terminal` | false |
 | `-q, --quiet` | Suppress logs | false |
 
 ### Environment Variables

package/docs/terminal.md

@@ -0,0 +1,75 @@
+# Terminal & Password CLI
+
+## WebSocket Terminal (`--terminal`)
+
+Enable a WebSocket shell endpoint at `/.terminal` for browser-based terminal access.
+
+```bash
+jss start --terminal
+```
+
+### How it works
+
+- Spawns `/bin/sh` per authenticated WebSocket connection
+- Pipes stdin/stdout/stderr between WebSocket and shell
+- Requires authentication (only authenticated users can connect)
+- Disabled by default, opt-in via `--terminal`
+
+### Environment variable
+
+```bash
+JSS_TERMINAL=true jss start
+```
+
+### Browser integration
+
+Connect with [xterm.js](https://xtermjs.org/) or any WebSocket terminal client:
+
+```javascript
+const ws = new WebSocket('wss://your.pod/.terminal')
+ws.onmessage = (e) => terminal.write(e.data)
+terminal.onData((data) => ws.send(data))
+```
+
+### Security
+
+- Authentication required — unauthenticated connections are rejected
+- Experimental — not recommended for production multi-user servers without additional access controls
+- Consider using `--single-user` mode for personal pod servers
+
+## Password Management (`jss passwd`)
+
+Manage IdP user passwords from the command line.
+
+```bash
+# Set password interactively
+jss passwd <username>
+
+# Set password directly
+jss passwd <username> --password <newpassword>
+
+# Generate and print a random password
+jss passwd <username> --generate
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--password <pw>` | Set password non-interactively |
+| `--generate` | Generate random password and print it |
+| `-r, --root <path>` | Data directory (default: `./data`) |
+
+### Examples
+
+```bash
+# Reset a user's password
+jss passwd alice --password newsecretpass
+
+# Generate a random password for a user
+jss passwd bob --generate
+# Output: New password for bob: a7Bx9kQ2mP...
+
+# Interactive (prompts for password)
+jss passwd alice
+```

package/package.json

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

package/src/config.js

@@ -55,6 +55,9 @@ export const defaults = {
   webrtc: false,
   webrtcPath: '/.webrtc',
 
+  // Terminal (WebSocket shell access)
+  terminal: false,
+
   // Tunnel (decentralized ngrok)
   tunnel: false,
   tunnelPath: '/.tunnel',
@@ -140,6 +143,7 @@ const envMap = {
   JSS_NOSTR_MAX_EVENTS: 'nostrMaxEvents',
   JSS_WEBRTC: 'webrtc',
   JSS_WEBRTC_PATH: 'webrtcPath',
+  JSS_TERMINAL: 'terminal',
   JSS_TUNNEL: 'tunnel',
   JSS_TUNNEL_PATH: 'tunnelPath',
   JSS_ACTIVITYPUB: 'activitypub',

package/src/server.js

@@ -20,6 +20,7 @@ import { remoteStoragePlugin } from './remotestorage.js';
 import { dbPlugin } from './db/index.js';
 import { webrtcPlugin } from './webrtc/index.js';
 import { tunnelPlugin } from './tunnel/index.js';
+import { terminalPlugin } from './terminal/index.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -76,6 +77,8 @@ export function createServer(options = {}) {
   // 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';
@@ -248,6 +251,11 @@ export function createServer(options = {}) {
     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 });
@@ -352,6 +360,9 @@ export function createServer(options = {}) {
     if (webrtcEnabled && urlNoQuery === webrtcPath) {
       return;
     }
+    if (terminalEnabled && urlNoQuery === '/.terminal') {
+      return;
+    }
 
     const segments = request.url.split('/').map(s => s.split('?')[0]); // Remove query strings
     const hasForbiddenDotfile = segments.some(seg =>
@@ -427,6 +438,7 @@ export function createServer(options = {}) {
         (payEnabled && isPayRequest(request.url)) ||
         (mongoEnabled && (request.url === '/db' || request.url.startsWith('/db/'))) ||
         (webrtcEnabled && (request.url === webrtcPath || request.url.startsWith(webrtcPath + '?'))) ||
+        (terminalEnabled && (request.url === '/.terminal' || request.url.startsWith('/.terminal?'))) ||
         (tunnelEnabled && (request.url === tunnelPath || request.url.startsWith(tunnelPath + '?') || request.url.startsWith('/tunnel/'))) ||
         mashlibPaths.some(p => request.url === p || request.url.startsWith(p + '.'))) {
       return;

package/src/terminal/index.js

@@ -0,0 +1,128 @@
+/**
+ * Terminal Plugin — WebSocket Shell Access
+ *
+ * Provides a remote shell over WebSocket for authenticated pod owners.
+ * Spawns /bin/sh on connection and pipes stdin/stdout/stderr between
+ * the WebSocket and the shell process.
+ *
+ * SECURITY: Requires authentication. The connecting user's webId must
+ * be present (verified via token). This is a privileged endpoint.
+ *
+ * Usage: jss start --terminal
+ * Endpoint: wss://your.pod/.terminal
+ *
+ * Protocol (binary/text over WebSocket):
+ *   -> (text/binary)  stdin data sent to shell
+ *   <- (text/binary)  stdout/stderr data from shell
+ *   <- JSON { type: "exit", code: <n> }  shell exited
+ *   <- JSON { type: "error", message: "..." }
+ */
+
+import websocket from '@fastify/websocket';
+import { getWebIdFromRequestAsync } from '../auth/token.js';
+import { spawn } from 'child_process';
+
+/**
+ * Register terminal WebSocket route on Fastify instance
+ *
+ * @param {object} fastify - Fastify instance
+ * @param {object} options - Options
+ * @param {string} options.path - WebSocket path (default: '/.terminal')
+ */
+export async function terminalPlugin(fastify, options = {}) {
+  const wsPath = options.path || '/.terminal';
+
+  // Track active shell processes for cleanup
+  const shells = new Set();
+
+  if (!fastify.websocketServer) {
+    await fastify.register(websocket);
+  }
+
+  // Clean up all shells on server close
+  fastify.addHook('onClose', async () => {
+    for (const proc of shells) {
+      try { proc.kill(); } catch { /* already dead */ }
+    }
+    shells.clear();
+  });
+
+  fastify.get(wsPath, { websocket: true }, async (connection, request) => {
+    const socket = connection.socket || connection;
+
+    // Authenticate — query param token support for browser WebSocket
+    const queryToken = request.query?.token;
+    if (queryToken && !request.headers.authorization) {
+      request.headers.authorization = `Bearer ${queryToken}`;
+    }
+    const { webId } = await getWebIdFromRequestAsync(request);
+
+    if (!webId && !options.public) {
+      socket.send(JSON.stringify({ type: 'error', message: 'Authentication required' }));
+      socket.close();
+      return;
+    }
+
+    // Spawn shell
+    const shellCommand = process.env.SHELL || 'bash';
+    const shell = spawn(shellCommand, ['-i'], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, TERM: 'xterm-256color' },
+    });
+
+    shells.add(shell);
+
+    // Pipe shell stdout to WebSocket
+    shell.stdout.on('data', (data) => {
+      if (socket.readyState === 1) {
+        try { socket.send(data.toString().replace(/\r?\n/g, '\r\n')); } catch { /* socket closed */ }
+      }
+    });
+
+    // Pipe shell stderr to WebSocket
+    shell.stderr.on('data', (data) => {
+      if (socket.readyState === 1) {
+        try { socket.send(data.toString().replace(/\r?\n/g, '\r\n')); } catch { /* socket closed */ }
+      }
+    });
+
+    // Shell exited
+    shell.on('close', (code) => {
+      shells.delete(shell);
+      if (socket.readyState === 1) {
+        try {
+          socket.send(JSON.stringify({ type: 'exit', code: code ?? 1 }));
+          socket.close();
+        } catch { /* socket already closed */ }
+      }
+    });
+
+    shell.on('error', (err) => {
+      shells.delete(shell);
+      if (socket.readyState === 1) {
+        try {
+          socket.send(JSON.stringify({ type: 'error', message: err.message }));
+          socket.close();
+        } catch { /* socket already closed */ }
+      }
+    });
+
+    // Pipe WebSocket messages to shell stdin
+    socket.on('message', (data) => {
+      if (shell.stdin.writable) {
+        const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+        try { shell.stdin.write(buf); } catch { /* stdin closed */ }
+      }
+    });
+
+    // WebSocket closed — kill the shell
+    socket.on('close', () => {
+      shells.delete(shell);
+      try { shell.kill(); } catch { /* already dead */ }
+    });
+
+    socket.on('error', () => {});
+  });
+}
+
+export default terminalPlugin;