@hcu-lab.me/mcp-device 1.0.10 → 1.0.12

package/control-plane/scripts/GATEWAY-LICENSE.txt

@@ -0,0 +1,7 @@
+MIT License
+
+Copyright (c) 2026 Ren Zimeng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the software, subject to including this copyright notice and permission notice in all copies or substantial portions of the software.
+
+THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/control-plane/scripts/account-http.mjs

@@ -0,0 +1,220 @@
+import crypto from 'node:crypto';
+
+const ACCOUNT_COOKIE = 'hcu_account_session';
+const SESSION_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+function escapeHtml(value) {
+  return String(value ?? '')
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}
+
+function parseCookies(header = '') {
+  return String(header)
+    .split(';')
+    .map(part => part.trim())
+    .filter(Boolean)
+    .reduce((result, part) => {
+      const index = part.indexOf('=');
+      if (index <= 0) return result;
+      try { result[part.slice(0, index)] = decodeURIComponent(part.slice(index + 1)); } catch {}
+      return result;
+    }, {});
+}
+
+function safeReturnTo(value) {
+  const target = String(value || '').trim();
+  if (!target || target.length > 2048 || !target.startsWith('/') || target.startsWith('//') || target.includes('\\')) return '/dashboard';
+  return target;
+}
+
+function secureRequest(req) {
+  const forwarded = String(req.headers?.['x-forwarded-proto'] || '').split(',')[0].trim().toLowerCase();
+  return Boolean(req.secure || forwarded === 'https');
+}
+
+function sourceKey(req) {
+  return String(req.headers?.['cf-connecting-ip'] || req.ip || req.socket?.remoteAddress || 'unknown').trim().slice(0, 128);
+}
+
+function identityDigest(value) {
+  return crypto.createHash('sha256').update(String(value || '').trim().toLowerCase(), 'utf8').digest('hex').slice(0, 24);
+}
+
+export function createLoginRateLimiter({ now = () => Date.now() } = {}) {
+  const states = new Map();
+  const resetAfterMs = 15 * 60_000;
+
+  function key(identity, source) {
+    return `${String(source || 'unknown').slice(0, 128)}\n${identityDigest(identity)}`;
+  }
+
+  function canAttempt({ identity, source }) {
+    const state = states.get(key(identity, source));
+    return !state || Number(state.blockedUntil || 0) <= Number(now());
+  }
+
+  function recordFailure({ identity, source }) {
+    const id = key(identity, source);
+    const time = Number(now());
+    const previous = states.get(id);
+    const state = !previous || time - previous.lastFailure > resetAfterMs
+      ? { failures: 0, lastFailure: time, blockedUntil: 0 }
+      : previous;
+    state.failures += 1;
+    state.lastFailure = time;
+    if (state.failures >= 5) state.blockedUntil = time + 60 * 60_000;
+    else if (state.failures === 4) state.blockedUntil = time + 5 * 60_000;
+    else if (state.failures === 3) state.blockedUntil = time + 60_000;
+    states.set(id, state);
+    return { ...state };
+  }
+
+  function recordSuccess({ identity, source }) {
+    states.delete(key(identity, source));
+  }
+
+  return { canAttempt, recordFailure, recordSuccess };
+}
+
+export function publicGatePage(body, { failed = false } = {}) {
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title></title>
+<style>
+:root{color-scheme:dark}*{box-sizing:border-box}body{margin:0;min-height:100vh;display:grid;place-items:center;background:#050505;color:#eee;font:15px ui-monospace,SFMono-Regular,Consolas,monospace}.gate{width:min(92vw,440px);display:grid;gap:10px}.row{display:flex;gap:10px}.row>*{min-width:0}form{margin:0}.go-form{display:flex;gap:10px;flex:1}.signup-form{display:grid;gap:10px;flex:1}.gate-error{color:#b96a62;font-size:12px;letter-spacing:.08em}input{min-width:0;flex:1;background:#0b0b0b;color:#f4f4f4;border:1px solid ${failed ? '#733' : '#292929'};padding:13px 14px;outline:none}input::placeholder{color:#666}input:focus{border-color:#666}button,a{border:0;padding:13px 16px;background:#222;color:#eee;text-decoration:none;font:inherit;cursor:pointer}.go{background:#176b45;color:#f2f2f2}.out{background:#8f342c;color:#f2f2f2}
+</style></head><body><main class="gate">${body}</main></body></html>`;
+}
+
+function loginIdentityPage(returnTo = '/dashboard') {
+  const target = safeReturnTo(returnTo);
+  return publicGatePage(`<div class="row"><form class="go-form" method="post" action="/login/email"><input name="identity" type="email" autocomplete="username" aria-label="Email" placeholder="email" autofocus required><input type="hidden" name="return_to" value="${escapeHtml(target)}"><button class="go" type="submit">GO</button></form><a class="out" href="/signup?return_to=${encodeURIComponent(target)}">OUT</a></div>`);
+}
+
+function loginPasswordPage(identity, returnTo = '/dashboard', failed = false) {
+  const target = safeReturnTo(returnTo);
+  return publicGatePage(`<div class="row"><form class="go-form" method="post" action="/login"><input name="password" type="password" autocomplete="current-password" aria-label="Password" placeholder="password" aria-invalid="${failed ? 'true' : 'false'}" autofocus required><input type="hidden" name="identity" value="${escapeHtml(identity)}"><input type="hidden" name="return_to" value="${escapeHtml(target)}"><button class="go" type="submit">GO</button></form><a class="out" href="/signup?return_to=${encodeURIComponent(target)}">OUT</a></div>`, { failed });
+}
+
+function signupPage(returnTo = '/dashboard', failed = false, needInvite = true, inviteInvalid = false) {
+  const target = safeReturnTo(returnTo);
+  const inviteInput = inviteInvalid
+    ? '<input name="invite" autocomplete="one-time-code" aria-label="Invite code" aria-invalid="true" placeholder="invalid invite code" maxlength="8" autofocus required>'
+    : '<input name="invite" autocomplete="one-time-code" aria-label="Invite code" placeholder="invite code" maxlength="8" required>';
+  return publicGatePage(`<div class="row"><form id="signup-form" class="signup-form" method="post" action="/signup"><input name="identity" type="email" autocomplete="username" aria-label="Email" placeholder="email" aria-invalid="${failed ? 'true' : 'false'}" required><input name="password" type="password" autocomplete="new-password" aria-label="Password" placeholder="password" required>${needInvite ? inviteInput : ''}${inviteInvalid ? '<div class="gate-error" role="alert">INVALID INVITE</div>' : ''}<input type="hidden" name="return_to" value="${escapeHtml(target)}"><a href="/login?return_to=${encodeURIComponent(target)}" class="out">OUT</a></form><button class="go" type="submit" form="signup-form">GO</button></div>`, { failed });
+}
+
+export function installAccountRoutes(app, {
+  accountStore,
+  needInvite = true,
+  allowAdminLogin = false,
+  now = () => Date.now(),
+  loginLimiter = createLoginRateLimiter({ now }),
+  sessionTtlMs = SESSION_TTL_MS
+} = {}) {
+  if (!app || !accountStore) throw new Error('app and accountStore are required.');
+  const requiresInvite = () => typeof needInvite === 'function' ? Boolean(needInvite()) : Boolean(needInvite);
+
+  function sessionAccountFromRequest(req) {
+    const sessionId = parseCookies(req?.headers?.cookie || '')[ACCOUNT_COOKIE];
+    return sessionId ? accountStore.getSessionAccount(sessionId) : null;
+  }
+
+  function accountFromRequest(req) {
+    const account = sessionAccountFromRequest(req);
+    return account?.role === 'user' ? account : null;
+  }
+
+  function setSession(req, res, accountId) {
+    const session = accountStore.createSession(accountId, { ttlMs: sessionTtlMs });
+    res.cookie(ACCOUNT_COOKIE, session.sessionId, {
+      httpOnly: true,
+      sameSite: 'lax',
+      secure: secureRequest(req),
+      maxAge: sessionTtlMs,
+      path: '/'
+    });
+    return session;
+  }
+
+  function clearSession(req, res) {
+    const sessionId = parseCookies(req.headers?.cookie || '')[ACCOUNT_COOKIE];
+    if (sessionId) accountStore.revokeSession(sessionId);
+    res.clearCookie(ACCOUNT_COOKIE, { path: '/' });
+  }
+
+  function sessionBindingFromRequest(req) {
+    const sessionId = parseCookies(req?.headers?.cookie || '')[ACCOUNT_COOKIE];
+    if (!sessionId || !accountStore.getSessionAccount(sessionId)) return null;
+    return crypto.createHash('sha256').update(sessionId, 'utf8').digest('hex');
+  }
+
+  function loginLocation(returnTo) {
+    const target = safeReturnTo(returnTo);
+    return target === '/dashboard' ? '/login' : `/login?return_to=${encodeURIComponent(target)}`;
+  }
+
+  app.get('/', (req, res) => {
+    res.redirect(302, accountFromRequest(req) ? '/dashboard' : '/login');
+  });
+
+  app.get('/login', (req, res) => {
+    res.status(200).type('html').send(loginIdentityPage(req.query?.return_to));
+  });
+
+  app.post('/login/email', (req, res) => {
+    res.status(200).type('html').send(loginPasswordPage(String(req.body?.identity || '').trim(), req.body?.return_to, false));
+  });
+
+  app.post('/login', (req, res) => {
+    const identity = String(req.body?.identity || '').trim();
+    const returnTo = safeReturnTo(req.body?.return_to);
+    const source = sourceKey(req);
+    const limiterKey = { identity, source };
+    if (!loginLimiter.canAttempt(limiterKey)) {
+      res.status(200).type('html').send(loginPasswordPage(identity, returnTo, true));
+      return;
+    }
+
+    const account = accountStore.verifyPassword(identity, req.body?.password);
+    if (!account || (account.role !== 'user' && !(allowAdminLogin && account.role === 'admin'))) {
+      loginLimiter.recordFailure(limiterKey);
+      res.status(200).type('html').send(loginPasswordPage(identity, returnTo, true));
+      return;
+    }
+
+    loginLimiter.recordSuccess(limiterKey);
+    setSession(req, res, account.accountId);
+    res.redirect(302, account.role === 'admin' && returnTo === '/dashboard' ? '/operator' : returnTo);
+  });
+
+  app.get('/signup', (req, res) => {
+    res.status(200).type('html').send(signupPage(req.query?.return_to, false, requiresInvite()));
+  });
+
+  app.post('/signup', (req, res) => {
+    const returnTo = safeReturnTo(req.body?.return_to);
+    try {
+      const account = accountStore.createAccount({
+        email: req.body?.identity,
+        password: req.body?.password,
+        inviteCode: req.body?.invite,
+        requireInvite: requiresInvite()
+      });
+      setSession(req, res, account.accountId);
+      res.redirect(302, returnTo);
+    } catch (error) {
+      const inviteInvalid = error?.code === 'INVITE_REQUIRED' || error?.code === 'INVITE_INVALID';
+      res.status(200).type('html').send(signupPage(returnTo, true, requiresInvite(), inviteInvalid));
+    }
+  });
+
+  app.post('/logout', (req, res) => {
+    clearSession(req, res);
+    res.redirect(302, '/login');
+  });
+
+  return { accountFromRequest, sessionAccountFromRequest, cookieName: ACCOUNT_COOKIE, clearSession, loginLocation, sessionBindingFromRequest };
+}

package/control-plane/scripts/account-store.mjs

@@ -0,0 +1,368 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { DatabaseSync } from 'node:sqlite';
+
+const INVITE_ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+const INVITE_LENGTH = 8;
+const SCRYPT_N = 16384;
+const SCRYPT_R = 8;
+const SCRYPT_P = 1;
+const SCRYPT_KEYLEN = 32;
+
+function accountError(code, message) {
+  const error = new Error(`${code}: ${message}`);
+  error.code = code;
+  return error;
+}
+
+export function normalizeAccountEmail(value) {
+  const email = String(value || '').trim().toLowerCase();
+  if (!email || email.length > 320 || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+    throw accountError('INVALID_EMAIL', 'A valid email is required.');
+  }
+  return email;
+}
+
+function normalizePassword(value) {
+  const password = String(value || '');
+  if (password.length < 8 || password.length > 1024) {
+    throw accountError('INVALID_PASSWORD', 'Password must be between 8 and 1024 characters.');
+  }
+  return password;
+}
+
+function hashPassword(password) {
+  const salt = crypto.randomBytes(16);
+  const digest = crypto.scryptSync(normalizePassword(password), salt, SCRYPT_KEYLEN, {
+    N: SCRYPT_N,
+    r: SCRYPT_R,
+    p: SCRYPT_P,
+    maxmem: 64 * 1024 * 1024
+  });
+  return `scrypt$${SCRYPT_N}$${SCRYPT_R}$${SCRYPT_P}$${salt.toString('base64url')}$${digest.toString('base64url')}`;
+}
+
+function verifyPasswordHash(password, encoded) {
+  try {
+    const [kind, nText, rText, pText, saltText, digestText] = String(encoded || '').split('$');
+    if (kind !== 'scrypt') return false;
+    const N = Number(nText);
+    const r = Number(rText);
+    const p = Number(pText);
+    if (!Number.isInteger(N) || !Number.isInteger(r) || !Number.isInteger(p)) return false;
+    const salt = Buffer.from(saltText, 'base64url');
+    const expected = Buffer.from(digestText, 'base64url');
+    const actual = crypto.scryptSync(String(password || ''), salt, expected.length, {
+      N,
+      r,
+      p,
+      maxmem: 64 * 1024 * 1024
+    });
+    return expected.length === actual.length && crypto.timingSafeEqual(expected, actual);
+  } catch {
+    return false;
+  }
+}
+
+const DUMMY_PASSWORD_HASH = hashPassword('hcu-dummy-password-not-an-account');
+
+function sha256Hex(value) {
+  return crypto.createHash('sha256').update(String(value || ''), 'utf8').digest('hex');
+}
+
+function inviteHash(code) {
+  return sha256Hex(String(code || '').trim().toUpperCase());
+}
+
+function sessionHash(sessionId) {
+  return sha256Hex(String(sessionId || '').trim());
+}
+
+function generateInviteCode() {
+  const bytes = crypto.randomBytes(INVITE_LENGTH);
+  let value = '';
+  for (let index = 0; index < INVITE_LENGTH; index += 1) {
+    value += INVITE_ALPHABET[bytes[index] % INVITE_ALPHABET.length];
+  }
+  return value;
+}
+
+function rowToAccount(row) {
+  if (!row) return null;
+  return {
+    accountId: row.account_id,
+    email: row.email_normalized,
+    role: row.role,
+    createdAt: Number(row.created_at),
+    revokedAt: row.revoked_at === null ? null : Number(row.revoked_at)
+  };
+}
+
+function rowToInvite(row) {
+  if (!row) return null;
+  return {
+    inviteHash: row.invite_hash,
+    createdAt: Number(row.created_at),
+    usedAt: row.used_at === null ? null : Number(row.used_at),
+    revokedAt: row.revoked_at === null ? null : Number(row.revoked_at)
+  };
+}
+
+export function createAccountStore({ dbPath, now = () => Date.now() } = {}) {
+  if (!dbPath) throw new Error('dbPath is required for account store.');
+  const resolved = path.resolve(dbPath);
+  fs.mkdirSync(path.dirname(resolved), { recursive: true });
+  const db = new DatabaseSync(resolved);
+  db.exec(`
+    PRAGMA journal_mode = WAL;
+    PRAGMA synchronous = NORMAL;
+    PRAGMA busy_timeout = 5000;
+    CREATE TABLE IF NOT EXISTS accounts (
+      account_id TEXT PRIMARY KEY,
+      email_normalized TEXT NOT NULL UNIQUE,
+      password_hash TEXT NOT NULL,
+      role TEXT NOT NULL CHECK (role IN ('user', 'admin')),
+      created_at INTEGER NOT NULL,
+      revoked_at INTEGER
+    );
+    CREATE TABLE IF NOT EXISTS invites (
+      invite_hash TEXT PRIMARY KEY,
+      created_at INTEGER NOT NULL,
+      used_at INTEGER,
+      revoked_at INTEGER
+    );
+    CREATE TABLE IF NOT EXISTS account_sessions (
+      session_hash TEXT PRIMARY KEY,
+      account_id TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      expires_at INTEGER NOT NULL,
+      revoked_at INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS accounts_email_idx ON accounts(email_normalized);
+    CREATE INDEX IF NOT EXISTS account_sessions_account_idx ON account_sessions(account_id);
+  `);
+
+  const getByIdStatement = db.prepare(`
+    SELECT account_id, email_normalized, password_hash, role, created_at, revoked_at
+    FROM accounts WHERE account_id = ?
+  `);
+  const getByEmailStatement = db.prepare(`
+    SELECT account_id, email_normalized, password_hash, role, created_at, revoked_at
+    FROM accounts WHERE email_normalized = ?
+  `);
+  const listAccountsStatement = db.prepare(`
+    SELECT account_id, email_normalized, password_hash, role, created_at, revoked_at
+    FROM accounts ORDER BY created_at, account_id
+  `);
+  const insertAccountStatement = db.prepare(`
+    INSERT INTO accounts (account_id, email_normalized, password_hash, role, created_at, revoked_at)
+    VALUES (?, ?, ?, ?, ?, NULL)
+  `);
+  const revokeAccountStatement = db.prepare(`
+    UPDATE accounts SET revoked_at = ? WHERE account_id = ? AND revoked_at IS NULL
+  `);
+  const deleteAccountStatement = db.prepare('DELETE FROM accounts WHERE account_id = ?');
+  const insertSessionStatement = db.prepare(`
+    INSERT INTO account_sessions (session_hash, account_id, created_at, expires_at, revoked_at)
+    VALUES (?, ?, ?, ?, NULL)
+  `);
+  const getSessionAccountStatement = db.prepare(`
+    SELECT a.account_id, a.email_normalized, a.password_hash, a.role, a.created_at, a.revoked_at
+    FROM account_sessions s
+    JOIN accounts a ON a.account_id = s.account_id
+    WHERE s.session_hash = ? AND s.revoked_at IS NULL AND s.expires_at >= ? AND a.revoked_at IS NULL
+  `);
+  const revokeSessionStatement = db.prepare('UPDATE account_sessions SET revoked_at = ? WHERE session_hash = ? AND revoked_at IS NULL');
+  const revokeAccountSessionsStatement = db.prepare('UPDATE account_sessions SET revoked_at = ? WHERE account_id = ? AND revoked_at IS NULL');
+  const deleteAccountSessionsStatement = db.prepare('DELETE FROM account_sessions WHERE account_id = ?');
+
+  const getInviteStatement = db.prepare('SELECT invite_hash, created_at, used_at, revoked_at FROM invites WHERE invite_hash = ?');
+  const listInvitesStatement = db.prepare('SELECT invite_hash, created_at, used_at, revoked_at FROM invites ORDER BY created_at, invite_hash');
+  const insertInviteStatement = db.prepare('INSERT INTO invites (invite_hash, created_at, used_at, revoked_at) VALUES (?, ?, NULL, NULL)');
+  const consumeInviteStatement = db.prepare('UPDATE invites SET used_at = ? WHERE invite_hash = ? AND used_at IS NULL AND revoked_at IS NULL');
+  const revokeInviteStatement = db.prepare('UPDATE invites SET revoked_at = ? WHERE invite_hash = ? AND used_at IS NULL AND revoked_at IS NULL');
+
+  function getAccount(accountId) {
+    return rowToAccount(getByIdStatement.get(String(accountId || '').trim()));
+  }
+
+  function getAccountByEmail(email) {
+    return rowToAccount(getByEmailStatement.get(normalizeAccountEmail(email)));
+  }
+
+  function listAccounts() {
+    return listAccountsStatement.all().map(rowToAccount);
+  }
+
+  function createAccountInternal({ email, password, role, inviteCode, requireInvite }) {
+    const normalizedEmail = normalizeAccountEmail(email);
+    const passwordHash = hashPassword(password);
+    const createdAt = Number(now());
+    const accountId = crypto.randomUUID();
+    const invite = String(inviteCode || '').trim().toUpperCase();
+    const hash = invite ? inviteHash(invite) : null;
+    let began = false;
+    try {
+      db.exec('BEGIN IMMEDIATE');
+      began = true;
+      if (requireInvite) {
+        if (!invite) throw accountError('INVITE_REQUIRED', 'A valid invite code is required.');
+        const row = getInviteStatement.get(hash);
+        if (!row || row.used_at !== null || row.revoked_at !== null) {
+          throw accountError('INVITE_INVALID', 'Invite code is invalid, used, or revoked.');
+        }
+      }
+      try {
+        insertAccountStatement.run(accountId, normalizedEmail, passwordHash, role, createdAt);
+      } catch (error) {
+        if (String(error?.message || '').toLowerCase().includes('unique')) {
+          throw accountError('ACCOUNT_EXISTS', 'Account already exists.');
+        }
+        throw error;
+      }
+      if (requireInvite) {
+        const changed = consumeInviteStatement.run(createdAt, hash);
+        if (Number(changed.changes) !== 1) throw accountError('INVITE_INVALID', 'Invite code is invalid, used, or revoked.');
+      }
+      db.exec('COMMIT');
+      began = false;
+      return getAccount(accountId);
+    } catch (error) {
+      if (began) { try { db.exec('ROLLBACK'); } catch {} }
+      throw error;
+    }
+  }
+
+  function createAccount({ email, password, inviteCode, requireInvite = false }) {
+    return createAccountInternal({ email, password, role: 'user', inviteCode, requireInvite: Boolean(requireInvite) });
+  }
+
+  function createAdmin({ email, password }) {
+    return createAccountInternal({ email, password, role: 'admin', requireInvite: false });
+  }
+
+  function verifyPassword(email, password) {
+    let normalizedEmail;
+    try { normalizedEmail = normalizeAccountEmail(email); } catch { normalizedEmail = null; }
+    const row = normalizedEmail ? getByEmailStatement.get(normalizedEmail) : null;
+    const matches = verifyPasswordHash(password, row?.password_hash || DUMMY_PASSWORD_HASH);
+    if (!row || row.revoked_at !== null || !matches) return null;
+    return rowToAccount(row);
+  }
+
+  function createSession(accountId, { ttlMs = 7 * 24 * 60 * 60 * 1000 } = {}) {
+    const id = String(accountId || '').trim();
+    const account = getAccount(id);
+    if (!account || account.revokedAt !== null) throw accountError('ACCOUNT_NOT_FOUND', 'Unknown or revoked account.');
+    if (!Number.isInteger(ttlMs) || ttlMs < 60_000 || ttlMs > 30 * 24 * 60 * 60 * 1000) {
+      throw accountError('INVALID_SESSION_TTL', 'Session ttlMs must be between 60000 and 2592000000.');
+    }
+    const sessionId = crypto.randomBytes(32).toString('base64url');
+    const createdAt = Number(now());
+    const expiresAt = createdAt + ttlMs;
+    insertSessionStatement.run(sessionHash(sessionId), id, createdAt, expiresAt);
+    return { sessionId, accountId: id, createdAt, expiresAt };
+  }
+
+  function getSessionAccount(sessionId) {
+    const id = String(sessionId || '').trim();
+    if (!id) return null;
+    return rowToAccount(getSessionAccountStatement.get(sessionHash(id), Number(now())));
+  }
+
+  function revokeSession(sessionId) {
+    const id = String(sessionId || '').trim();
+    if (!id) return false;
+    return Number(revokeSessionStatement.run(Number(now()), sessionHash(id)).changes) === 1;
+  }
+
+  function revokeAccount(accountId) {
+    const id = String(accountId || '').trim();
+    const existing = getAccount(id);
+    if (!existing) throw accountError('ACCOUNT_NOT_FOUND', 'Unknown account.');
+    if (existing.revokedAt !== null) return existing;
+    const revokedAt = Number(now());
+    let began = false;
+    try {
+      db.exec('BEGIN IMMEDIATE');
+      began = true;
+      revokeAccountStatement.run(revokedAt, id);
+      revokeAccountSessionsStatement.run(revokedAt, id);
+      db.exec('COMMIT');
+      began = false;
+      return getAccount(id);
+    } catch (error) {
+      if (began) { try { db.exec('ROLLBACK'); } catch {} }
+      throw error;
+    }
+  }
+
+  function deleteAccount(accountId) {
+    const id = String(accountId || '').trim();
+    let began = false;
+    try {
+      db.exec('BEGIN IMMEDIATE');
+      began = true;
+      deleteAccountSessionsStatement.run(id);
+      const deleted = Number(deleteAccountStatement.run(id).changes) === 1;
+      db.exec('COMMIT');
+      began = false;
+      return deleted;
+    } catch (error) {
+      if (began) { try { db.exec('ROLLBACK'); } catch {} }
+      throw error;
+    }
+  }
+
+  function createInvite() {
+    const createdAt = Number(now());
+    for (let attempt = 0; attempt < 16; attempt += 1) {
+      const code = generateInviteCode();
+      try {
+        insertInviteStatement.run(inviteHash(code), createdAt);
+        return { code, createdAt };
+      } catch (error) {
+        if (!String(error?.message || '').toLowerCase().includes('unique')) throw error;
+      }
+    }
+    throw new Error('Unable to allocate a unique invite code.');
+  }
+
+  function listInvites() {
+    return listInvitesStatement.all().map(rowToInvite);
+  }
+
+  function revokeInvite(code) {
+    const normalized = String(code || '').trim().toUpperCase();
+    if (!normalized) throw accountError('INVITE_INVALID', 'Invite code is required.');
+    const hash = inviteHash(normalized);
+    const existing = getInviteStatement.get(hash);
+    if (!existing) throw accountError('INVITE_INVALID', 'Invite code is invalid.');
+    if (existing.used_at !== null) throw accountError('INVITE_INVALID', 'Invite code is already used.');
+    if (existing.revoked_at === null) revokeInviteStatement.run(Number(now()), hash);
+    return rowToInvite(getInviteStatement.get(hash));
+  }
+
+  function close() {
+    db.close();
+  }
+
+  return {
+    getAccount,
+    getAccountByEmail,
+    listAccounts,
+    createAccount,
+    createAdmin,
+    verifyPassword,
+    createSession,
+    getSessionAccount,
+    revokeSession,
+    revokeAccount,
+    deleteAccount,
+    createInvite,
+    listInvites,
+    revokeInvite,
+    close
+  };
+}

package/control-plane/scripts/admin.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { createAccountStore } from './account-store.mjs';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const runtimeDirectory = path.resolve(process.env.MCP_RUNTIME_DIR || path.join(packageRoot, '.runtime'));
+const dbPath = path.resolve(process.env.MCP_GATEWAY_DB_PATH || path.join(runtimeDirectory, 'gateway.sqlite'));
+const [area, action, ...args] = process.argv.slice(2);
+
+function usage() {
+  console.error([
+    'Usage:',
+    '  node scripts/admin.mjs account create-admin <email>   # password from HCU_ADMIN_PASSWORD',
+    '  node scripts/admin.mjs account list',
+    '  node scripts/admin.mjs account revoke <account_id|email>',
+    '  node scripts/admin.mjs account delete <account_id|email>',
+    '  node scripts/admin.mjs invite create [count]',
+    '  node scripts/admin.mjs invite list',
+    '  node scripts/admin.mjs invite revoke <code>'
+  ].join('\n'));
+}
+
+function print(value) {
+  process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+
+function resolveAccount(store, value) {
+  const key = String(value || '').trim();
+  if (!key) throw new Error('account_id or email is required.');
+  return key.includes('@') ? store.getAccountByEmail(key) : store.getAccount(key);
+}
+
+const store = createAccountStore({ dbPath });
+try {
+  if (area === 'account' && action === 'create-admin') {
+    const email = args[0];
+    const password = process.env.HCU_ADMIN_PASSWORD;
+    if (!email || !password) throw new Error('create-admin requires <email> and HCU_ADMIN_PASSWORD in the local environment.');
+    print({ ok: true, account: store.createAdmin({ email, password }) });
+  } else if (area === 'account' && action === 'list') {
+    print({ ok: true, accounts: store.listAccounts() });
+  } else if (area === 'account' && ['revoke', 'delete'].includes(action)) {
+    const account = resolveAccount(store, args[0]);
+    if (!account) throw new Error('Unknown account.');
+    if (action === 'revoke') print({ ok: true, account: store.revokeAccount(account.accountId) });
+    else print({ ok: true, account_id: account.accountId, deleted: store.deleteAccount(account.accountId) });
+  } else if (area === 'invite' && action === 'create') {
+    const count = args[0] === undefined ? 1 : Number(args[0]);
+    if (!Number.isInteger(count) || count < 1 || count > 100) throw new Error('invite create count must be an integer from 1 to 100.');
+    const codes = Array.from({ length: count }, () => store.createInvite().code);
+    print({ ok: true, codes });
+  } else if (area === 'invite' && action === 'list') {
+    print({ ok: true, invites: store.listInvites() });
+  } else if (area === 'invite' && action === 'revoke') {
+    print({ ok: true, invite: store.revokeInvite(args[0]) });
+  } else {
+    usage();
+    process.exitCode = 2;
+  }
+} catch (error) {
+  console.error(JSON.stringify({ ok: false, code: error?.code || 'ADMIN_COMMAND_FAILED', error: error?.message || String(error) }));
+  process.exitCode = 1;
+} finally {
+  store.close();
+}