javascript-solid-server 0.0.55 → 0.0.56

package/.claude/settings.local.json

@@ -202,7 +202,12 @@
       "Bash(webledgers show:*)",
       "Bash(webledgers set-balance:*)",
       "Bash(ssh melvincarvalho.com \"pm2 list | grep jss\")",
-      "Bash(ssh melvincarvalho.com \"cd /home/ubuntu/jss && git pull && pm2 restart jss\")"
+      "Bash(ssh melvincarvalho.com \"cd /home/ubuntu/jss && git pull && pm2 restart jss\")",
+      "WebFetch(domain:registry.npmjs.org)",
+      "WebFetch(domain:solid-chat.com)",
+      "WebFetch(domain:developer.chrome.com)",
+      "WebFetch(domain:css-tricks.com)",
+      "Bash(node bin/jss.js:*)"
     ]
   }
 }

package/README.md

@@ -6,7 +6,7 @@ A minimal, fast, JSON-LD native Solid server.
 
 ## Features
 
-### Implemented (v0.0.42)
+### Implemented (v0.0.56)
 
 - **LDP CRUD Operations** - GET, PUT, POST, DELETE, HEAD
 - **N3 Patch** - Solid's native patch format for RDF updates
@@ -29,6 +29,7 @@ A minimal, fast, JSON-LD native Solid server.
 - **Content Negotiation** - Turtle <-> JSON-LD conversion, including HTML data islands
 - **CORS Support** - Full cross-origin resource sharing
 - **Git HTTP Backend** - Clone and push to containers via `git` protocol
+- **Invite-Only Registration** - CLI-managed invite codes for controlled signups
 - **Security** - Blocks access to dotfiles (`.git/`, `.env`, etc.) except Solid-specific ones
 
 ### HTTP Methods
@@ -76,6 +77,7 @@ jss start --port 8443 --ssl-key ./key.pem --ssl-cert ./cert.pem
 ```bash
 jss start [options]    # Start the server
 jss init [options]     # Initialize configuration
+jss invite <cmd>       # Manage invite codes (create, list, revoke)
 jss --help             # Show help
 ```
 
@@ -99,6 +101,7 @@ jss --help             # Show help
 | `--mashlib-cdn` | Enable Mashlib (CDN mode) | false |
 | `--mashlib-version <ver>` | Mashlib CDN version | 2.0.0 |
 | `--git` | Enable Git HTTP backend | false |
+| `--invite-only` | Require invite code for registration | false |
 | `-q, --quiet` | Suppress logs | false |
 
 ### Environment Variables
@@ -113,6 +116,7 @@ export JSS_CONNEG=true
 export JSS_SUBDOMAINS=true
 export JSS_BASE_DOMAIN=example.com
 export JSS_MASHLIB=true
+export JSS_INVITE_ONLY=true
 jss start
 ```
 
@@ -379,6 +383,50 @@ git add .acl && git commit -m "Add ACL"
 
 See [git-credential-nostr](https://github.com/JavaScriptSolidServer/git-credential-nostr) for more details.
 
+## Invite-Only Registration
+
+Control who can create accounts by requiring invite codes:
+
+```bash
+jss start --idp --invite-only
+```
+
+### Managing Invite Codes
+
+```bash
+# 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
+
+| Mode | Registration | Pod Creation |
+|------|--------------|--------------|
+| Open (default) | Anyone can register | Anyone can create pods |
+| Invite-only | Requires valid invite code | Via registration only |
+
+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 invite's remaining uses
+- Depleted invites are automatically removed
+
+Invite codes are stored in `.server/invites.json` in your data directory.
+
 ## Authentication
 
 ### Simple Tokens (Development)
@@ -668,7 +716,8 @@ src/
 │   ├── accounts.js       # User account management
 │   ├── keys.js           # JWKS key management
 │   ├── interactions.js   # Login/consent handlers
-│   └── views.js          # HTML templates
+│   ├── views.js          # HTML templates
+│   └── invites.js        # Invite code management
 ├── rdf/
 │   ├── turtle.js         # Turtle <-> JSON-LD
 │   └── conneg.js         # Content negotiation

package/bin/jss.js

@@ -11,6 +11,7 @@
 import { Command } from 'commander';
 import { createServer } from '../src/server.js';
 import { loadConfig, saveConfig, printConfig, defaults } from '../src/config.js';
+import { createInvite, listInvites, revokeInvite } from '../src/idp/invites.js';
 import fs from 'fs-extra';
 import path from 'path';
 import { fileURLToPath } from 'url';
@@ -56,6 +57,8 @@ program
   .option('--mashlib-version <version>', 'Mashlib version for CDN mode (default: 2.0.0)')
   .option('--git', 'Enable Git HTTP backend (clone/push support)')
   .option('--no-git', 'Disable Git HTTP backend')
+  .option('--invite-only', 'Require invite code for registration')
+  .option('--no-invite-only', 'Allow open registration')
   .option('-q, --quiet', 'Suppress log output')
   .option('--print-config', 'Print configuration and exit')
   .action(async (options) => {
@@ -98,6 +101,7 @@ program
         mashlibCdn: config.mashlibCdn,
         mashlibVersion: config.mashlibVersion,
         git: config.git,
+        inviteOnly: config.inviteOnly,
       });
 
       await server.listen({ port: config.port, host: config.host });
@@ -117,6 +121,7 @@ program
           console.log(`  Mashlib: local (data browser enabled)`);
         }
         if (config.git) console.log('  Git: enabled (clone/push support)');
+        if (config.inviteOnly) console.log('  Registration: invite-only');
         console.log('\n  Press Ctrl+C to stop\n');
       }
 
@@ -204,6 +209,104 @@ program
     console.log('\nRun `jss start` to start the server.\n');
   });
 
+/**
+ * Invite command - manage invite codes
+ */
+const inviteCmd = program
+  .command('invite')
+  .description('Manage invite codes for registration');
+
+inviteCmd
+  .command('create')
+  .description('Create a new invite code')
+  .option('-u, --uses <number>', 'Maximum uses (default: 1)', parseInt, 1)
+  .option('-n, --note <text>', 'Optional note/description')
+  .option('-r, --root <path>', 'Data directory')
+  .action(async (options) => {
+    try {
+      // Set DATA_ROOT if provided
+      if (options.root) {
+        process.env.DATA_ROOT = path.resolve(options.root);
+      }
+
+      const { code, invite } = await createInvite({
+        maxUses: options.uses,
+        note: options.note || ''
+      });
+
+      console.log(`\nCreated invite code: ${code}`);
+      if (invite.maxUses > 1) {
+        console.log(`Uses: 0/${invite.maxUses}`);
+      }
+      if (invite.note) {
+        console.log(`Note: ${invite.note}`);
+      }
+      console.log('');
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+  });
+
+inviteCmd
+  .command('list')
+  .description('List all invite codes')
+  .option('-r, --root <path>', 'Data directory')
+  .action(async (options) => {
+    try {
+      // Set DATA_ROOT if provided
+      if (options.root) {
+        process.env.DATA_ROOT = path.resolve(options.root);
+      }
+
+      const invites = await listInvites();
+
+      if (invites.length === 0) {
+        console.log('\nNo invite codes found.\n');
+        return;
+      }
+
+      console.log('\n  CODE        USES     CREATED      NOTE');
+      console.log('  ' + '-'.repeat(55));
+
+      for (const invite of invites) {
+        const uses = `${invite.uses}/${invite.maxUses}`.padEnd(8);
+        const created = invite.created.split('T')[0];
+        const note = invite.note || '';
+        console.log(`  ${invite.code}    ${uses} ${created}   ${note}`);
+      }
+      console.log('');
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+  });
+
+inviteCmd
+  .command('revoke <code>')
+  .description('Revoke an invite code')
+  .option('-r, --root <path>', 'Data directory')
+  .action(async (code, options) => {
+    try {
+      // Set DATA_ROOT if provided
+      if (options.root) {
+        process.env.DATA_ROOT = path.resolve(options.root);
+      }
+
+      const success = await revokeInvite(code);
+
+      if (success) {
+        console.log(`\nRevoked invite code: ${code.toUpperCase()}\n`);
+      } else {
+        console.log(`\nInvite code not found: ${code.toUpperCase()}\n`);
+        process.exit(1);
+      }
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+  });
+
 /**
  * Helper: Prompt for input
  */

package/package.json

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

package/src/config.js

@@ -42,6 +42,12 @@ export const defaults = {
   mashlibCdn: false,
   mashlibVersion: '2.0.0',
 
+  // Git HTTP backend
+  git: false,
+
+  // Invite-only registration
+  inviteOnly: false,
+
   // Logging
   logger: true,
   quiet: false,
@@ -71,6 +77,8 @@ const envMap = {
   JSS_MASHLIB: 'mashlib',
   JSS_MASHLIB_CDN: 'mashlibCdn',
   JSS_MASHLIB_VERSION: 'mashlibVersion',
+  JSS_GIT: 'git',
+  JSS_INVITE_ONLY: 'inviteOnly',
 };
 
 /**

package/src/idp/index.js

@@ -27,7 +27,7 @@ import { addTrustedIssuer } from '../auth/solid-oidc.js';
  * @param {string} options.issuer - The issuer URL
  */
 export async function idpPlugin(fastify, options) {
-  const { issuer } = options;
+  const { issuer, inviteOnly = false } = options;
 
   if (!issuer) {
     throw new Error('IdP requires issuer URL');
@@ -274,7 +274,7 @@ export async function idpPlugin(fastify, options) {
 
   // Registration routes
   fastify.get('/idp/register', async (request, reply) => {
-    return handleRegisterGet(request, reply);
+    return handleRegisterGet(request, reply, inviteOnly);
   });
 
   // Registration - rate limited to prevent spam accounts
@@ -287,7 +287,7 @@ export async function idpPlugin(fastify, options) {
       }
     }
   }, async (request, reply) => {
-    return handleRegisterPost(request, reply, issuer);
+    return handleRegisterPost(request, reply, issuer, inviteOnly);
   });
 
   fastify.log.info(`IdP initialized with issuer: ${issuer}`);

package/src/idp/interactions.js

@@ -7,6 +7,7 @@ import { authenticate, findById, createAccount } from './accounts.js';
 import { loginPage, consentPage, errorPage, registerPage } from './views.js';
 import * as storage from '../storage/filesystem.js';
 import { createPodStructure } from '../handlers/container.js';
+import { validateInvite } from './invites.js';
 
 // Security: Maximum body size for IdP form submissions (1MB)
 const MAX_BODY_SIZE = 1024 * 1024;
@@ -309,16 +310,16 @@ export async function handleAbort(request, reply, provider) {
  * Handle GET /idp/register
  * Shows registration page
  */
-export async function handleRegisterGet(request, reply) {
+export async function handleRegisterGet(request, reply, inviteOnly = false) {
   const uid = request.query.uid || null;
-  return reply.type('text/html').send(registerPage(uid));
+  return reply.type('text/html').send(registerPage(uid, null, null, inviteOnly));
 }
 
 /**
  * Handle POST /idp/register
  * Creates account and pod
  */
-export async function handleRegisterPost(request, reply, issuer) {
+export async function handleRegisterPost(request, reply, issuer, inviteOnly = false) {
   const uid = request.query.uid || null;
 
   // Parse body
@@ -328,7 +329,7 @@ export async function handleRegisterPost(request, reply, issuer) {
   if (Buffer.isBuffer(parsedBody)) {
     // Security: check body size
     if (parsedBody.length > MAX_BODY_SIZE) {
-      return reply.code(413).type('text/html').send(registerPage(null, 'Request body exceeds maximum size.'));
+      return reply.code(413).type('text/html').send(registerPage(null, 'Request body exceeds maximum size.', null, inviteOnly));
     }
     const bodyStr = parsedBody.toString();
     if (contentType.includes('application/json')) {
@@ -344,32 +345,39 @@ export async function handleRegisterPost(request, reply, issuer) {
   } else if (typeof parsedBody === 'string') {
     // Security: check body size
     if (parsedBody.length > MAX_BODY_SIZE) {
-      return reply.code(413).type('text/html').send(registerPage(null, 'Request body exceeds maximum size.'));
+      return reply.code(413).type('text/html').send(registerPage(null, 'Request body exceeds maximum size.', null, inviteOnly));
     }
     const params = new URLSearchParams(parsedBody);
     parsedBody = Object.fromEntries(params.entries());
   }
 
-  const { username, password, confirmPassword } = parsedBody;
+  const { username, password, confirmPassword, invite } = parsedBody;
+
+  // Validate invite code if invite-only mode is enabled
+  if (inviteOnly) {
+    const inviteResult = await validateInvite(invite);
+    if (!inviteResult.valid) {
+      return reply.code(403).type('text/html').send(registerPage(uid, inviteResult.error, null, inviteOnly));
+    }
+  }
 
   // Validate input
   if (!username || !password) {
-    return reply.type('text/html').send(registerPage(uid, 'Username and password are required'));
+    return reply.type('text/html').send(registerPage(uid, 'Username and password are required', null, inviteOnly));
   }
 
   // Validate username format
   const usernameRegex = /^[a-z0-9]+$/;
   if (!usernameRegex.test(username)) {
-    return reply.type('text/html').send(registerPage(uid, 'Username must contain only lowercase letters and numbers'));
+    return reply.type('text/html').send(registerPage(uid, 'Username must contain only lowercase letters and numbers', null, inviteOnly));
   }
 
   if (username.length < 3) {
-    return reply.type('text/html').send(registerPage(uid, 'Username must be at least 3 characters'));
+    return reply.type('text/html').send(registerPage(uid, 'Username must be at least 3 characters', null, inviteOnly));
   }
 
-
   if (password !== confirmPassword) {
-    return reply.type('text/html').send(registerPage(uid, 'Passwords do not match'));
+    return reply.type('text/html').send(registerPage(uid, 'Passwords do not match', null, inviteOnly));
   }
 
   try {
@@ -393,7 +401,7 @@ export async function handleRegisterPost(request, reply, issuer) {
     const podPath = `${username}/`;
     const podExists = await storage.exists(podPath);
     if (podExists) {
-      return reply.type('text/html').send(registerPage(uid, 'Username is already taken'));
+      return reply.type('text/html').send(registerPage(uid, 'Username is already taken', null, inviteOnly));
     }
 
     // Create pod structure
@@ -413,10 +421,10 @@ export async function handleRegisterPost(request, reply, issuer) {
     if (uid) {
       return reply.redirect(`/idp/interaction/${uid}`);
     } else {
-      return reply.type('text/html').send(registerPage(null, null, `Account created! You can now sign in as "${username}".`));
+      return reply.type('text/html').send(registerPage(null, null, `Account created! You can now sign in as "${username}".`, inviteOnly));
     }
   } catch (err) {
     request.log.error(err, 'Registration error');
-    return reply.type('text/html').send(registerPage(uid, err.message));
+    return reply.type('text/html').send(registerPage(uid, err.message, null, inviteOnly));
   }
 }

package/src/idp/invites.js

@@ -0,0 +1,181 @@
+/**
+ * Invite code management for invite-only registration
+ * Stores codes in /data/.server/invites.json
+ */
+
+import { promises as fs } from 'fs';
+import { join } from 'path';
+import crypto from 'crypto';
+import { getDataRoot } from '../utils/url.js';
+
+const INVITES_DIR = '.server';
+const INVITES_FILE = 'invites.json';
+
+/**
+ * Get path to invites file
+ */
+function getInvitesPath() {
+  return join(getDataRoot(), INVITES_DIR, INVITES_FILE);
+}
+
+/**
+ * Ensure .server directory exists
+ */
+async function ensureServerDir() {
+  const dirPath = join(getDataRoot(), INVITES_DIR);
+  try {
+    await fs.mkdir(dirPath, { recursive: true });
+  } catch (err) {
+    if (err.code !== 'EEXIST') throw err;
+  }
+}
+
+/**
+ * Load all invites from storage
+ * @returns {Promise<object>} Map of code -> invite data
+ */
+export async function loadInvites() {
+  try {
+    const data = await fs.readFile(getInvitesPath(), 'utf-8');
+    return JSON.parse(data);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return {};
+    }
+    throw err;
+  }
+}
+
+/**
+ * Save invites to storage
+ * @param {object} invites - Map of code -> invite data
+ */
+async function saveInvites(invites) {
+  await ensureServerDir();
+  await fs.writeFile(getInvitesPath(), JSON.stringify(invites, null, 2));
+}
+
+/**
+ * Generate a random invite code
+ * @returns {string} 8-character uppercase alphanumeric code
+ */
+function generateCode() {
+  const bytes = crypto.randomBytes(6);
+  // Base64 encode and take first 8 chars, uppercase, remove ambiguous chars
+  return bytes.toString('base64')
+    .replace(/[+/=]/g, '')
+    .substring(0, 8)
+    .toUpperCase()
+    .replace(/O/g, '0')
+    .replace(/I/g, '1')
+    .replace(/L/g, '1');
+}
+
+/**
+ * Create a new invite code
+ * @param {object} options
+ * @param {number} options.maxUses - Maximum number of uses (default 1)
+ * @param {string} options.note - Optional note/description
+ * @returns {Promise<{code: string, invite: object}>}
+ */
+export async function createInvite({ maxUses = 1, note = '' } = {}) {
+  const invites = await loadInvites();
+
+  // Generate unique code
+  let code;
+  do {
+    code = generateCode();
+  } while (invites[code]);
+
+  const invite = {
+    created: new Date().toISOString(),
+    maxUses,
+    uses: 0,
+    note
+  };
+
+  invites[code] = invite;
+  await saveInvites(invites);
+
+  return { code, invite };
+}
+
+/**
+ * List all invite codes
+ * @returns {Promise<Array<{code: string, ...invite}>>}
+ */
+export async function listInvites() {
+  const invites = await loadInvites();
+  return Object.entries(invites).map(([code, invite]) => ({
+    code,
+    ...invite
+  }));
+}
+
+/**
+ * Revoke (delete) an invite code
+ * @param {string} code - The invite code to revoke
+ * @returns {Promise<boolean>} True if code existed and was deleted
+ */
+export async function revokeInvite(code) {
+  const invites = await loadInvites();
+  const upperCode = code.toUpperCase();
+
+  if (!invites[upperCode]) {
+    return false;
+  }
+
+  delete invites[upperCode];
+  await saveInvites(invites);
+  return true;
+}
+
+/**
+ * Validate and consume an invite code
+ * @param {string} code - The invite code to validate
+ * @returns {Promise<{valid: boolean, error?: string}>}
+ */
+export async function validateInvite(code) {
+  if (!code || typeof code !== 'string') {
+    return { valid: false, error: 'Invite code required' };
+  }
+
+  const invites = await loadInvites();
+  const upperCode = code.toUpperCase().trim();
+  const invite = invites[upperCode];
+
+  if (!invite) {
+    return { valid: false, error: 'Invalid invite code' };
+  }
+
+  if (invite.uses >= invite.maxUses) {
+    return { valid: false, error: 'Invite code has been fully used' };
+  }
+
+  // Consume one use
+  invite.uses += 1;
+  await saveInvites(invites);
+
+  return { valid: true };
+}
+
+/**
+ * Check if an invite code is valid without consuming it
+ * @param {string} code - The invite code to check
+ * @returns {Promise<boolean>}
+ */
+export async function isValidInvite(code) {
+  if (!code || typeof code !== 'string') {
+    return false;
+  }
+
+  const invites = await loadInvites();
+  const upperCode = code.toUpperCase().trim();
+  const invite = invites[upperCode];
+
+  if (!invite) {
+    return false;
+  }
+
+  return invite.uses < invite.maxUses;
+}

package/src/idp/views.js

@@ -296,7 +296,13 @@ export function errorPage(title, message) {
 /**
  * Registration page HTML
  */
-export function registerPage(uid = null, error = null, success = null) {
+export function registerPage(uid = null, error = null, success = null, inviteOnly = false) {
+  const inviteField = inviteOnly ? `
+      <label for="invite">Invite Code</label>
+      <input type="text" id="invite" name="invite" required
+             placeholder="Enter your invite code" style="text-transform: uppercase;">
+  ` : '';
+
   return `
 <!DOCTYPE html>
 <html lang="en">
@@ -310,14 +316,16 @@ export function registerPage(uid = null, error = null, success = null) {
   <div class="container">
     <div class="logo">${solidLogo}</div>
     <h1>Create Account</h1>
-    <p class="subtitle">Register for a new Solid Pod</p>
+    <p class="subtitle">Register for a new Solid Pod${inviteOnly ? ' (invite required)' : ''}</p>
 
     ${error ? `<div class="error">${escapeHtml(error)}</div>` : ''}
     ${success ? `<div class="error" style="background: #efe; border-color: #cfc; color: #060;">${escapeHtml(success)}</div>` : ''}
 
     <form method="POST" action="/idp/register${uid ? `?uid=${uid}` : ''}">
+      ${inviteField}
+
       <label for="username">Username</label>
-      <input type="text" id="username" name="username" required autofocus
+      <input type="text" id="username" name="username" required ${!inviteOnly ? 'autofocus' : ''}
              placeholder="Choose a username" pattern="[a-z0-9]+"
              title="Lowercase letters and numbers only">
 

package/src/server.js

@@ -46,6 +46,8 @@ export function createServer(options = {}) {
   const mashlibVersion = options.mashlibVersion ?? '2.0.0';
   // Git HTTP backend is OFF by default - enables clone/push via git protocol
   const gitEnabled = options.git ?? false;
+  // Invite-only registration is OFF by default - open registration
+  const inviteOnly = options.inviteOnly ?? false;
 
   // Set data root via environment variable if provided
   if (options.root) {
@@ -125,7 +127,7 @@ export function createServer(options = {}) {
 
   // Register Identity Provider plugin if enabled
   if (idpEnabled) {
-    fastify.register(idpPlugin, { issuer: idpIssuer });
+    fastify.register(idpPlugin, { issuer: idpIssuer, inviteOnly });
   }
 
   // Register rate limiting plugin