@@ -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
  */

@@ -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',

@@ -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' });
-  if (terminalEnabled) {
-    fastify.register(terminalPlugin, { path: '/.terminal' });
+  const terminalPath = '/.terminal';
+  if (terminalEnabled) {
+    fastify.register(terminalPlugin, { path: terminalPath });
-  if (terminalEnabled) {
-    fastify.register(terminalPlugin, { path: '/.terminal' });
+  const terminalPath = '/.terminal';
+  if (terminalEnabled) {
+    fastify.register(terminalPlugin, { path: terminalPath });
+  }
+
   // 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;

@@ -0,0 +1,127 @@
+/**
+ * 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;
+
+    // Authenticate — query param token support for browser WebSocket
+    const queryToken = request.query?.token;
+    if (queryToken && !request.headers.authorization) {
+      request.headers.authorization = `Bearer ${queryToken}`;
-    // Authenticate — query param token support for browser WebSocket
-    const queryToken = request.query?.token;
-    if (queryToken && !request.headers.authorization) {
-      request.headers.authorization = `Bearer ${queryToken}`;
+    // Authenticate — require Authorization header; query-string tokens are not supported
+    if (request.query?.token) {
+      socket.send(JSON.stringify({
+        type: 'error',
+        message: 'Query-string token authentication is not supported; use the Authorization header.',
+      }));
+      socket.close();
+      return;
-    // Authenticate — query param token support for browser WebSocket
-    const queryToken = request.query?.token;
-    if (queryToken && !request.headers.authorization) {
-      request.headers.authorization = `Bearer ${queryToken}`;
+    // Authenticate — require Authorization header; query-string tokens are not supported
+    if (request.query?.token) {
+      socket.send(JSON.stringify({
+        type: 'error',
+        message: 'Query-string token authentication is not supported; use the Authorization header.',
+      }));
+      socket.close();
+      return;
+    }
+    const { webId } = await getWebIdFromRequestAsync(request);
+
+    if (!webId) {
+      socket.send(JSON.stringify({ type: 'error', message: 'Authentication required' }));
+      socket.close();
+      return;
+    }
+
-
+
+    // Authorization — only pod owner (or single-user mode) may open a shell
+    let isOwner = false;
+
+    // Explicit single-user mode: any authenticated user is treated as the owner
+    if (options.singleUser === true) {
+      isOwner = true;
+    } else if (typeof options.isOwner === 'function') {
+      try {
+        // Allow async/sync ownership check similar to other plugins (e.g. /db/*)
+        const result = options.isOwner(request, webId);
+        isOwner = result instanceof Promise ? await result : result;
+      } catch {
+        isOwner = false;
+      }
+    } else if (typeof options.ownerWebId === 'string') {
+      isOwner = webId === options.ownerWebId;
+    }
+
+    if (!isOwner) {
+      // Forbidden: authenticated but not the pod owner
+      socket.send(JSON.stringify({ type: 'error', code: 403, message: 'Forbidden' }));
+      try { socket.close(); } catch { /* already closed */ }
+      return;
+    }
-
+
+    // Authorization — only pod owner (or single-user mode) may open a shell
+    let isOwner = false;
+
+    // Explicit single-user mode: any authenticated user is treated as the owner
+    if (options.singleUser === true) {
+      isOwner = true;
+    } else if (typeof options.isOwner === 'function') {
+      try {
+        // Allow async/sync ownership check similar to other plugins (e.g. /db/*)
+        const result = options.isOwner(request, webId);
+        isOwner = result instanceof Promise ? await result : result;
+      } catch {
+        isOwner = false;
+      }
+    } else if (typeof options.ownerWebId === 'string') {
+      isOwner = webId === options.ownerWebId;
+    }
+
+    if (!isOwner) {
+      // Forbidden: authenticated but not the pod owner
+      socket.send(JSON.stringify({ type: 'error', code: 403, message: 'Forbidden' }));
+      try { socket.close(); } catch { /* already closed */ }
+      return;
+    }
+    // Spawn shell
+    const shell = spawn('/bin/sh', [], {
+      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); } catch { /* socket closed */ }
+      }
+    });
+
+    // Pipe shell stderr to WebSocket
+    shell.stderr.on('data', (data) => {
+      if (socket.readyState === 1) {
+        try { socket.send(data); } 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;