@fyresmith/hive-server 3.1.0 → 4.0.1

package/README.md

@@ -92,6 +92,19 @@ hive env check
 hive env print
 ```
 
+Managed mode requires `OWNER_DISCORD_ID` in the env file. This Discord user is the only account allowed to initialize managed state and issue invites.
+
+Managed operations:
+
+```bash
+hive managed status
+hive managed invite create
+hive managed invite list
+hive managed invite revoke <code>
+hive managed member list
+hive managed member remove <discordId>
+```
+
 ## Tunnel Operations
 
 ```bash

package/cli/commands/managed.js

@@ -0,0 +1,142 @@
+import { CliError } from '../errors.js';
+import { EXIT } from '../constants.js';
+import { loadValidatedEnv, resolveContext } from '../core/context.js';
+import {
+  createInvite,
+  describeManagedStatus,
+  listInvites,
+  loadManagedState,
+  removeMember,
+  revokeInvite,
+} from '../../lib/managedState.js';
+import { section, success } from '../output.js';
+
+async function resolveManagedInputs(options) {
+  const { envFile } = await resolveContext(options);
+  const { env, issues } = await loadValidatedEnv(envFile, { requireFile: true });
+  if (issues.length > 0) {
+    throw new CliError(`Env validation failed: ${issues.join(', ')}`, EXIT.FAIL);
+  }
+  return {
+    vaultPath: env.VAULT_PATH,
+    ownerDiscordId: env.OWNER_DISCORD_ID,
+    envFile,
+  };
+}
+
+function assertInitialized(state) {
+  if (!state) {
+    throw new CliError('Managed vault is not initialized. Run pair/init flow first.', EXIT.FAIL);
+  }
+}
+
+export function registerManagedCommands(program) {
+  const managed = program.command('managed').description('Manage Hive managed-vault state');
+
+  managed
+    .command('status')
+    .description('Show managed vault status')
+    .option('--env-file <path>', 'env file path')
+    .action(async (options) => {
+      const { vaultPath, ownerDiscordId, envFile } = await resolveManagedInputs(options);
+      const state = await loadManagedState(vaultPath);
+      section('Managed Status');
+      console.log(`Env: ${envFile}`);
+      if (!state) {
+        console.log('Initialized: no');
+        console.log(`Configured owner: ${ownerDiscordId}`);
+        return;
+      }
+      const status = describeManagedStatus(state, ownerDiscordId);
+      console.log('Initialized: yes');
+      console.log(`Vault ID: ${status.vaultId}`);
+      console.log(`Owner: ${state.ownerDiscordId}`);
+      console.log(`Configured owner: ${ownerDiscordId}`);
+      console.log(`Owner matches env: ${state.ownerDiscordId === ownerDiscordId ? 'yes' : 'no'}`);
+      console.log(`Members: ${status.memberCount}`);
+      console.log(`Invites: ${Object.keys(state.invites ?? {}).length}`);
+    });
+
+  const invite = managed.command('invite').description('Manage invite codes');
+
+  invite
+    .command('create')
+    .description('Create a single-use invite code')
+    .option('--env-file <path>', 'env file path')
+    .action(async (options) => {
+      const { vaultPath, ownerDiscordId } = await resolveManagedInputs(options);
+      const created = await createInvite({
+        vaultPath,
+        ownerDiscordId,
+        createdBy: ownerDiscordId,
+      });
+      success(`Invite created: ${created.code}`);
+    });
+
+  invite
+    .command('list')
+    .description('List invite codes')
+    .option('--env-file <path>', 'env file path')
+    .action(async (options) => {
+      const { vaultPath } = await resolveManagedInputs(options);
+      const invites = await listInvites(vaultPath);
+      section('Invites');
+      if (invites.length === 0) {
+        console.log('(none)');
+        return;
+      }
+      for (const inviteRow of invites) {
+        const status = inviteRow.revokedAt
+          ? 'revoked'
+          : inviteRow.usedAt
+            ? `used by ${inviteRow.usedBy}`
+            : 'active';
+        console.log(`${inviteRow.code}  ${status}  created ${inviteRow.createdAt}`);
+      }
+    });
+
+  invite
+    .command('revoke <code>')
+    .description('Revoke an unused invite code')
+    .option('--env-file <path>', 'env file path')
+    .action(async (code, options) => {
+      const { vaultPath } = await resolveManagedInputs(options);
+      const revoked = await revokeInvite({ vaultPath, code });
+      success(`Invite revoked: ${revoked.code}`);
+    });
+
+  const member = managed.command('member').description('Manage members');
+
+  member
+    .command('list')
+    .description('List paired members')
+    .option('--env-file <path>', 'env file path')
+    .action(async (options) => {
+      const { vaultPath } = await resolveManagedInputs(options);
+      const state = await loadManagedState(vaultPath);
+      assertInitialized(state);
+      section('Members');
+      const members = Object.values(state.members ?? {});
+      if (members.length === 0) {
+        console.log('(none)');
+        return;
+      }
+      for (const row of members) {
+        const ownerMark = row.id === state.ownerDiscordId ? ' (owner)' : '';
+        console.log(`${row.id}${ownerMark}  @${row.username}  added ${row.addedAt}`);
+      }
+    });
+
+  member
+    .command('remove <discordId>')
+    .description('Remove a paired member')
+    .option('--env-file <path>', 'env file path')
+    .action(async (discordId, options) => {
+      const { vaultPath } = await resolveManagedInputs(options);
+      const result = await removeMember({ vaultPath, discordId });
+      if (!result.removed) {
+        throw new CliError(`Member not found: ${discordId}`, EXIT.FAIL);
+      }
+      success(`Removed member: ${discordId}`);
+    });
+}

package/cli/constants.js

@@ -18,16 +18,14 @@ export const REQUIRED_ENV_KEYS = [
   'DISCORD_CLIENT_ID',
   'DISCORD_CLIENT_SECRET',
   'DISCORD_REDIRECT_URI',
-  'DISCORD_GUILD_ID',
+  'OWNER_DISCORD_ID',
   'JWT_SECRET',
   'VAULT_PATH',
   'PORT',
-  'YJS_PORT',
 ];
 
 export const DEFAULT_ENV_VALUES = {
   PORT: '3000',
-  YJS_PORT: '3001',
 };
 
 export const DEFAULT_CONFIG = {

package/cli/core/app.js

@@ -3,6 +3,7 @@ import { Command, CommanderError } from 'commander';
 import { EXIT } from '../constants.js';
 import { CliError } from '../errors.js';
 import { registerEnvCommands } from '../commands/env.js';
+import { registerManagedCommands } from '../commands/managed.js';
 import { registerRootCommands } from '../commands/root.js';
 import { registerServiceCommands } from '../commands/service.js';
 import { registerTunnelCommands } from '../commands/tunnel.js';
@@ -23,6 +24,7 @@ export class HiveCliApp {
 
     registerRootCommands(program);
     registerEnvCommands(program);
+    registerManagedCommands(program);
     registerTunnelCommands(program);
     registerServiceCommands(program);
 

package/cli/env-file.js

@@ -76,9 +76,7 @@ export function validateEnvValues(values) {
   }
 
   const port = parseInt(values.PORT ?? '', 10);
-  const yjsPort = parseInt(values.YJS_PORT ?? '', 10);
   if (!Number.isInteger(port) || port <= 0) issues.push('PORT must be a positive integer');
-  if (!Number.isInteger(yjsPort) || yjsPort <= 0) issues.push('YJS_PORT must be a positive integer');
 
   try {
     const uri = new URL(values.DISCORD_REDIRECT_URI ?? '');
@@ -113,11 +111,10 @@ export async function promptForEnv({ envFile, existing, yes = false, preset = {}
   const questions = [
     { name: 'DISCORD_CLIENT_ID', message: 'Discord Client ID' },
     { name: 'DISCORD_CLIENT_SECRET', message: 'Discord Client Secret', secret: true },
-    { name: 'DISCORD_GUILD_ID', message: 'Discord Guild ID' },
+    { name: 'OWNER_DISCORD_ID', message: 'Managed vault owner Discord ID' },
     { name: 'JWT_SECRET', message: 'JWT secret', secret: true },
     { name: 'VAULT_PATH', message: 'Vault absolute path' },
     { name: 'PORT', message: 'HTTP port' },
-    { name: 'YJS_PORT', message: 'Yjs WS port' },
     { name: 'DISCORD_REDIRECT_URI', message: 'Discord redirect URI' },
   ];
 

package/cli/flows/doctor.js

@@ -8,6 +8,7 @@ import { run } from '../exec.js';
 import { getCloudflaredPath } from '../tunnel.js';
 import { fail, info, section, success, warn } from '../output.js';
 import { loadValidatedEnv } from '../core/context.js';
+import { loadManagedState } from '../../lib/managedState.js';
 
 export async function runDoctorChecks({ envFile, includeCloudflared = true }) {
   section('Hive Doctor');
@@ -63,6 +64,25 @@ export async function runDoctorChecks({ envFile, includeCloudflared = true }) {
       }
     }
 
+    if (env.VAULT_PATH && env.OWNER_DISCORD_ID) {
+      try {
+        const managedState = await loadManagedState(env.VAULT_PATH);
+        if (!managedState) {
+          info('Managed state not initialized yet');
+        } else if (managedState.ownerDiscordId !== env.OWNER_DISCORD_ID) {
+          fail(
+            `Managed owner mismatch: state=${managedState.ownerDiscordId} env=${env.OWNER_DISCORD_ID}`,
+          );
+          failures += 1;
+        } else {
+          success(`Managed state OK (vaultId ${managedState.vaultId})`);
+        }
+      } catch (err) {
+        fail(`Managed state error: ${err instanceof Error ? err.message : String(err)}`);
+        failures += 1;
+      }
+    }
+
     const port = parseInt(env.PORT, 10);
     const yjsPort = parseInt(env.YJS_PORT, 10);
     if (Number.isInteger(port) && port > 0) {

package/cli/flows/setup.js

@@ -95,7 +95,6 @@ export async function runSetupWizard(options) {
   const shouldSetupTunnel = await promptConfirm('Configure Cloudflare Tunnel now?', yes, true);
   if (shouldSetupTunnel) {
     const port = parseInteger(envValues.PORT, 'PORT');
-    const yjsPort = parseInteger(envValues.YJS_PORT, 'YJS_PORT');
     const tunnelName = requiredOrFallback(options.tunnelName, nextConfig.tunnelName || DEFAULT_TUNNEL_NAME);
     const cloudflaredConfigFile = requiredOrFallback(
       options.cloudflaredConfigFile,
@@ -109,7 +108,6 @@ export async function runSetupWizard(options) {
       configFile: cloudflaredConfigFile,
       certPath: DEFAULT_CLOUDFLARED_CERT,
       port,
-      yjsPort,
       yes,
       installService: tunnelService,
     });

package/cli/tunnel.js

@@ -138,10 +138,9 @@ export async function writeCloudflaredConfig({
   credentialsFile,
   domain,
   port,
-  yjsPort,
 }) {
   await mkdir(dirname(configFile), { recursive: true });
-  const yaml = `tunnel: ${tunnelId}\ncredentials-file: ${credentialsFile}\n\ningress:\n  - hostname: ${domain}\n    path: /yjs/*\n    service: http://localhost:${yjsPort}\n\n  - hostname: ${domain}\n    service: http://localhost:${port}\n\n  - service: http_status:404\n`;
+  const yaml = `tunnel: ${tunnelId}\ncredentials-file: ${credentialsFile}\n\ningress:\n  - hostname: ${domain}\n    service: http://localhost:${port}\n\n  - service: http_status:404\n`;
   await writeFile(configFile, yaml, 'utf-8');
   return yaml;
 }
@@ -358,7 +357,6 @@ export async function setupTunnel({
   configFile,
   certPath,
   port,
-  yjsPort,
   yes = false,
   installService = false,
 }) {
@@ -379,7 +377,6 @@ export async function setupTunnel({
     credentialsFile,
     domain,
     port,
-    yjsPort,
   });
 
   info(`Ensuring DNS route for ${domain}`);

package/index.js

@@ -4,9 +4,11 @@ import { fileURLToPath } from 'url';
 import express from 'express';
 import { Server } from 'socket.io';
 import authRoutes from './routes/auth.js';
+import managedRoutes from './routes/managed.js';
 import * as vault from './lib/vaultManager.js';
 import { attachHandlers } from './lib/socketHandler.js';
 import { startYjsServer, getActiveRooms, forceCloseRoom, getRoomStatus } from './lib/yjsServer.js';
+import { assertOwnerConsistency } from './lib/managedState.js';
 
 const REQUIRED = [
   'VAULT_PATH',
@@ -14,7 +16,7 @@ const REQUIRED = [
   'DISCORD_CLIENT_ID',
   'DISCORD_CLIENT_SECRET',
   'DISCORD_REDIRECT_URI',
-  'DISCORD_GUILD_ID',
+  'OWNER_DISCORD_ID',
 ];
 
 function validateEnv() {
@@ -25,13 +27,9 @@ function validateEnv() {
   }
 
   const port = parseInt(process.env.PORT ?? '3000', 10);
-  const yjsPort = parseInt(process.env.YJS_PORT ?? '3001', 10);
   if (!Number.isInteger(port) || port <= 0) {
     throw new Error('[startup] PORT must be a positive integer');
   }
-  if (!Number.isInteger(yjsPort) || yjsPort <= 0) {
-    throw new Error('[startup] YJS_PORT must be a positive integer');
-  }
 
   return { port };
 }
@@ -51,6 +49,7 @@ export async function startHiveServer(options = {}) {
   );
 
   const { port } = validateEnv();
+  await assertOwnerConsistency(process.env.VAULT_PATH, process.env.OWNER_DISCORD_ID);
 
   const app = express();
   const httpServer = createServer(app);
@@ -64,8 +63,21 @@ export async function startHiveServer(options = {}) {
 
   app.use(express.json());
 
+  // Allow desktop plugin fetch calls (Authorization header triggers preflight).
+  app.use((req, res, next) => {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET,POST,PUT,PATCH,DELETE,OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Authorization,Content-Type');
+    if (req.method === 'OPTIONS') {
+      res.sendStatus(204);
+      return;
+    }
+    next();
+  });
+
   // Auth routes
   app.use('/auth', authRoutes);
+  app.use('/managed', managedRoutes);
 
   // Health check
   app.get('/health', (req, res) => res.json({ ok: true, ts: Date.now() }));
@@ -80,7 +92,17 @@ export async function startHiveServer(options = {}) {
   }
 
   attachHandlers(io, getActiveRooms, broadcastFileUpdated, forceCloseRoom);
-  startYjsServer(broadcastFileUpdated);
+  const yjsWss = startYjsServer(httpServer, broadcastFileUpdated);
+
+  httpServer.on('upgrade', (req, socket, head) => {
+    const { pathname } = new URL(req.url, 'http://localhost');
+    if (pathname.startsWith('/yjs')) {
+      yjsWss.handleUpgrade(req, socket, head, (ws) => {
+        yjsWss.emit('connection', ws, req);
+      });
+    }
+    // Socket.IO handles /socket.io upgrades automatically via its own listener
+  });
 
   // Chokidar watch for external (non-plugin) changes
   vault.initWatcher((relPath, event) => {

package/lib/auth.js

@@ -1,4 +1,5 @@
 import jwt from 'jsonwebtoken';
+import { describeManagedStatus, isMember, loadManagedState } from './managedState.js';
 
 /**
  * Verify a JWT and return the decoded payload.
@@ -10,6 +11,30 @@ export function verifyToken(token) {
   return jwt.verify(token, process.env.JWT_SECRET);
 }
 
+function getVaultPath() {
+  const value = String(process.env.VAULT_PATH ?? '').trim();
+  if (!value) throw new Error('VAULT_PATH env var is required');
+  return value;
+}
+
+export async function getManagedContextForUser(user, vaultId) {
+  const state = await loadManagedState(getVaultPath());
+  if (!state) {
+    throw new Error('Managed vault is not initialized');
+  }
+  if (!vaultId || vaultId !== state.vaultId) {
+    throw new Error('Invalid vault ID');
+  }
+  if (!isMember(state, user.id)) {
+    throw new Error('User is not paired with this managed vault');
+  }
+
+  return {
+    state,
+    status: describeManagedStatus(state, user.id),
+  };
+}
+
 /**
  * Express middleware — reads Authorization: Bearer <token> header.
  */
@@ -31,13 +56,31 @@ export function expressMiddleware(req, res, next) {
  */
 export function socketMiddleware(socket, next) {
   const token = socket.handshake.auth?.token;
+  const vaultId = socket.handshake.auth?.vaultId;
   if (!token) return next(new Error('No token'));
-  try {
-    socket.user = verifyToken(token);
-    next();
-  } catch (err) {
-    next(new Error('Invalid token'));
-  }
+  (async () => {
+    try {
+      socket.user = verifyToken(token);
+      socket.managed = await getManagedContextForUser(socket.user, vaultId);
+      next();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Invalid token';
+      next(new Error(message));
+    }
+  })();
+}
+
+/**
+ * Verify a JWT for the y-websocket WS handshake + managed vault membership.
+ * @param {string} token
+ * @param {string} vaultId
+ * @returns {Promise<object>} decoded payload
+ */
+export async function verifyManagedWsAccess(token, vaultId) {
+  if (!token) throw new Error('No token');
+  const user = verifyToken(token);
+  await getManagedContextForUser(user, vaultId);
+  return user;
 }
 
 /**
@@ -46,5 +89,10 @@ export function socketMiddleware(socket, next) {
  * @returns {object} decoded payload
  */
 export function verifyWsToken(token) {
-  return verifyToken(token);
+  if (!token) throw new Error('No token');
+  try {
+    return verifyToken(token);
+  } catch (err) {
+    throw new Error('Invalid token');
+  }
 }

package/lib/managedState.js

@@ -0,0 +1,226 @@
+import { randomBytes } from 'crypto';
+import { existsSync } from 'fs';
+import { mkdir, readFile, writeFile } from 'fs/promises';
+import { dirname, resolve, join } from 'path';
+
+const STATE_VERSION = 1;
+const STATE_REL_PATH = join('.hive', 'managed-state.json');
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function normalizeOwnerId(value) {
+  return String(value ?? '').trim();
+}
+
+export function getManagedStatePath(vaultPath) {
+  const root = resolve(vaultPath);
+  return join(root, STATE_REL_PATH);
+}
+
+function normalizeState(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const ownerDiscordId = normalizeOwnerId(raw.ownerDiscordId);
+  const vaultId = String(raw.vaultId ?? '').trim();
+  const initializedAt = String(raw.initializedAt ?? '').trim();
+  if (!ownerDiscordId || !vaultId || !initializedAt) return null;
+
+  const members = raw.members && typeof raw.members === 'object' ? raw.members : {};
+  const invites = raw.invites && typeof raw.invites === 'object' ? raw.invites : {};
+
+  return {
+    version: STATE_VERSION,
+    managed: true,
+    ownerDiscordId,
+    vaultId,
+    initializedAt,
+    members,
+    invites,
+  };
+}
+
+export async function loadManagedState(vaultPath) {
+  const filePath = getManagedStatePath(vaultPath);
+  if (!existsSync(filePath)) return null;
+  const raw = await readFile(filePath, 'utf-8');
+  const parsed = JSON.parse(raw);
+  return normalizeState(parsed);
+}
+
+export async function saveManagedState(vaultPath, state) {
+  const filePath = getManagedStatePath(vaultPath);
+  const normalized = normalizeState(state);
+  if (!normalized) {
+    throw new Error('Invalid managed state payload');
+  }
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(normalized, null, 2)}\n`, 'utf-8');
+  return normalized;
+}
+
+export function getRole(state, userId) {
+  if (!state) return 'none';
+  if (userId === state.ownerDiscordId) return 'owner';
+  if (state.members?.[userId]) return 'member';
+  return 'none';
+}
+
+export function isMember(state, userId) {
+  return getRole(state, userId) !== 'none';
+}
+
+export async function assertOwnerConsistency(vaultPath, ownerDiscordId) {
+  const state = await loadManagedState(vaultPath);
+  if (!state) return null;
+  const configuredOwner = normalizeOwnerId(ownerDiscordId);
+  if (!configuredOwner) {
+    throw new Error('OWNER_DISCORD_ID is required');
+  }
+  if (state.ownerDiscordId !== configuredOwner) {
+    throw new Error(
+      `[managed] owner mismatch: state=${state.ownerDiscordId} env=${configuredOwner}. Update OWNER_DISCORD_ID or reset managed state.`,
+    );
+  }
+  return state;
+}
+
+function nextInviteCode() {
+  return randomBytes(6).toString('hex');
+}
+
+export async function initManagedState({ vaultPath, ownerDiscordId, ownerUser }) {
+  const existing = await loadManagedState(vaultPath);
+  if (existing) return existing;
+
+  const ownerId = normalizeOwnerId(ownerDiscordId);
+  if (!ownerId) throw new Error('OWNER_DISCORD_ID is required');
+
+  const state = {
+    version: STATE_VERSION,
+    managed: true,
+    ownerDiscordId: ownerId,
+    vaultId: randomBytes(16).toString('hex'),
+    initializedAt: nowIso(),
+    members: {},
+    invites: {},
+  };
+
+  state.members[ownerId] = {
+    id: ownerId,
+    username: ownerUser?.username || ownerId,
+    addedAt: nowIso(),
+    addedBy: ownerId,
+  };
+
+  return saveManagedState(vaultPath, state);
+}
+
+export async function createInvite({ vaultPath, ownerDiscordId, createdBy }) {
+  const state = await loadManagedState(vaultPath);
+  if (!state) throw new Error('Managed vault is not initialized');
+  if (state.ownerDiscordId !== normalizeOwnerId(ownerDiscordId)) {
+    throw new Error('Owner mismatch');
+  }
+
+  let code = nextInviteCode();
+  while (state.invites[code]) {
+    code = nextInviteCode();
+  }
+
+  state.invites[code] = {
+    code,
+    createdAt: nowIso(),
+    createdBy,
+    usedAt: null,
+    usedBy: null,
+    revokedAt: null,
+  };
+  await saveManagedState(vaultPath, state);
+  return state.invites[code];
+}
+
+export async function listInvites(vaultPath) {
+  const state = await loadManagedState(vaultPath);
+  if (!state) throw new Error('Managed vault is not initialized');
+  return Object.values(state.invites).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+
+export async function revokeInvite({ vaultPath, code }) {
+  const state = await loadManagedState(vaultPath);
+  if (!state) throw new Error('Managed vault is not initialized');
+  const invite = state.invites[code];
+  if (!invite) throw new Error('Invite not found');
+  if (invite.usedAt) throw new Error('Invite already used');
+  if (invite.revokedAt) return invite;
+  invite.revokedAt = nowIso();
+  await saveManagedState(vaultPath, state);
+  return invite;
+}
+
+export async function pairMember({ vaultPath, code, user }) {
+  const state = await loadManagedState(vaultPath);
+  if (!state) throw new Error('Managed vault is not initialized');
+
+  if (isMember(state, user.id)) {
+    return { state, paired: false, reason: 'already-member' };
+  }
+
+  const invite = state.invites[code];
+  if (!invite) throw new Error('Invite not found');
+  if (invite.revokedAt) throw new Error('Invite revoked');
+  if (invite.usedAt) throw new Error('Invite already used');
+
+  invite.usedAt = nowIso();
+  invite.usedBy = user.id;
+
+  state.members[user.id] = {
+    id: user.id,
+    username: user.username,
+    addedAt: nowIso(),
+    addedBy: invite.createdBy || state.ownerDiscordId,
+  };
+
+  await saveManagedState(vaultPath, state);
+  return { state, paired: true, reason: 'paired' };
+}
+
+export async function removeMember({ vaultPath, discordId }) {
+  const state = await loadManagedState(vaultPath);
+  if (!state) throw new Error('Managed vault is not initialized');
+  if (discordId === state.ownerDiscordId) {
+    throw new Error('Cannot remove owner');
+  }
+  const existing = state.members?.[discordId];
+  if (!existing) {
+    return { removed: false, state };
+  }
+  delete state.members[discordId];
+  await saveManagedState(vaultPath, state);
+  return { removed: true, state, member: existing };
+}
+
+export function describeManagedStatus(state, userId) {
+  if (!state) {
+    return {
+      managedInitialized: false,
+      vaultId: null,
+      role: 'none',
+      isOwner: false,
+      isMember: false,
+      memberCount: 0,
+    };
+  }
+
+  const role = getRole(state, userId);
+  return {
+    managedInitialized: true,
+    vaultId: state.vaultId,
+    role,
+    isOwner: role === 'owner',
+    isMember: role === 'owner' || role === 'member',
+    ownerDiscordId: state.ownerDiscordId,
+    memberCount: Object.keys(state.members ?? {}).length,
+    initializedAt: state.initializedAt,
+  };
+}

package/lib/vaultManager.js

@@ -8,7 +8,7 @@ import chokidar from 'chokidar';
 // Deny / allow lists
 // ---------------------------------------------------------------------------
 
-const DENY_PREFIXES = ['.obsidian', 'Attachments', '.git'];
+const DENY_PREFIXES = ['.obsidian', 'Attachments', '.git', '.hive', '.hive-quarantine'];
 const DENY_FILES = ['.DS_Store', 'Thumbs.db'];
 // Keep synced content text-based to ensure hash/read/write semantics stay safe.
 const ALLOW_EXTS = new Set(['.md', '.canvas']);

package/lib/yjsServer.js

@@ -204,12 +204,11 @@ export async function forceCloseRoom(relPath) {
   await closeRoom(docName, { closeClients: true, reason: 'forced' });
 }
 
-export function startYjsServer(broadcastFileUpdated) {
+export function startYjsServer(httpServer, broadcastFileUpdated) {
   broadcastRef = broadcastFileUpdated;
-  const port = parseInt(process.env.YJS_PORT ?? '3001', 10);
-  const wss = new WebSocketServer({ port });
+  const wss = new WebSocketServer({ noServer: true });
 
-  wss.on('connection', (conn, req) => {
+  wss.on('connection', async (conn, req) => {
     const url = new URL(req.url, 'http://localhost');
 
     // Strip /yjs/ prefix added by Cloudflare Tunnel routing
@@ -223,10 +222,12 @@ export function startYjsServer(broadcastFileUpdated) {
     }
 
     const token = url.searchParams.get('token');
+    const vaultId = url.searchParams.get('vaultId');
     try {
-      auth.verifyWsToken(token);
-    } catch {
-      conn.close(4001, 'Unauthorized');
+      await auth.verifyManagedWsAccess(token, vaultId);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Unauthorized';
+      conn.close(4001, message);
       return;
     }
 
@@ -272,6 +273,5 @@ export function startYjsServer(broadcastFileUpdated) {
     }
   });
 
-  console.log(`[yjs] WebSocket server listening on port ${port}`);
   return wss;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fyresmith/hive-server",
-  "version": "3.1.0",
+  "version": "4.0.1",
   "type": "module",
   "description": "Collaborative Obsidian vault server",
   "main": "index.js",

package/routes/auth.js

@@ -29,9 +29,10 @@ router.get('/login', (req, res) => {
   const state = randomBytes(16).toString('hex');
   stateMap.set(state, { ts: Date.now() });
 
+  const scope = process.env.DISCORD_GUILD_ID ? ['identify', 'guilds'] : ['identify'];
   const url = oauth.generateAuthUrl({
     clientId: process.env.DISCORD_CLIENT_ID,
-    scope: ['identify', 'guilds'],
+    scope,
     redirectUri: process.env.DISCORD_REDIRECT_URI,
     state,
   });
@@ -56,22 +57,25 @@ router.get('/callback', async (req, res) => {
 
   try {
     // Exchange code for access token
+    const scope = process.env.DISCORD_GUILD_ID ? ['identify', 'guilds'] : ['identify'];
     const tokenData = await oauth.tokenRequest({
       clientId: process.env.DISCORD_CLIENT_ID,
       clientSecret: process.env.DISCORD_CLIENT_SECRET,
       redirectUri: process.env.DISCORD_REDIRECT_URI,
       code,
-      scope: ['identify', 'guilds'],
+      scope,
       grantType: 'authorization_code',
     });
 
     const accessToken = tokenData.access_token;
 
-    // Verify guild membership
-    const guilds = await oauth.getUserGuilds(accessToken);
-    const isMember = guilds.some((g) => g.id === process.env.DISCORD_GUILD_ID);
-    if (!isMember) {
-      return res.status(403).send('Access denied: you are not a member of the required Discord server.');
+    // Verify guild membership (only when DISCORD_GUILD_ID is configured)
+    if (process.env.DISCORD_GUILD_ID) {
+      const guilds = await oauth.getUserGuilds(accessToken);
+      const isMember = guilds.some((g) => g.id === process.env.DISCORD_GUILD_ID);
+      if (!isMember) {
+        return res.status(403).send('Access denied: you are not a member of the required Discord server.');
+      }
     }
 
     // Fetch user profile

package/routes/managed.js

@@ -0,0 +1,174 @@
+import { Router } from 'express';
+import { expressMiddleware } from '../lib/auth.js';
+import {
+  createInvite,
+  describeManagedStatus,
+  initManagedState,
+  listInvites,
+  loadManagedState,
+  pairMember,
+  removeMember,
+  revokeInvite,
+} from '../lib/managedState.js';
+
+const router = Router();
+
+router.use((req, res, next) => {
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'GET,POST,PUT,PATCH,DELETE,OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Authorization,Content-Type');
+  if (req.method === 'OPTIONS') {
+    res.sendStatus(204);
+    return;
+  }
+  next();
+});
+
+function getVaultPath() {
+  const value = String(process.env.VAULT_PATH ?? '').trim();
+  if (!value) throw new Error('VAULT_PATH env var is required');
+  return value;
+}
+
+function getOwnerDiscordId() {
+  return String(process.env.OWNER_DISCORD_ID ?? '').trim();
+}
+
+function assertOwner(req, res) {
+  const ownerId = getOwnerDiscordId();
+  if (!ownerId) {
+    res.status(500).json({ ok: false, error: 'OWNER_DISCORD_ID is not configured' });
+    return false;
+  }
+  if (req.user?.id !== ownerId) {
+    res.status(403).json({ ok: false, error: 'Owner access required' });
+    return false;
+  }
+  return true;
+}
+
+router.get('/status', expressMiddleware, async (req, res) => {
+  try {
+    const state = await loadManagedState(getVaultPath());
+    let status = describeManagedStatus(state, req.user.id);
+    if (!state) {
+      const isOwner = req.user.id === getOwnerDiscordId();
+      status = {
+        ...status,
+        role: isOwner ? 'owner' : 'none',
+        isOwner,
+      };
+    }
+    res.json({
+      ok: true,
+      ...status,
+      user: { id: req.user.id, username: req.user.username },
+    });
+  } catch (err) {
+    res.status(500).json({ ok: false, error: err instanceof Error ? err.message : String(err) });
+  }
+});
+
+router.post('/init', expressMiddleware, async (req, res) => {
+  if (!assertOwner(req, res)) return;
+  try {
+    const state = await initManagedState({
+      vaultPath: getVaultPath(),
+      ownerDiscordId: getOwnerDiscordId(),
+      ownerUser: req.user,
+    });
+    res.json({
+      ok: true,
+      managedInitialized: true,
+      vaultId: state.vaultId,
+      ownerDiscordId: state.ownerDiscordId,
+      memberCount: Object.keys(state.members ?? {}).length,
+    });
+  } catch (err) {
+    res.status(400).json({ ok: false, error: err instanceof Error ? err.message : String(err) });
+  }
+});
+
+router.post('/pair', expressMiddleware, async (req, res) => {
+  const code = String(req.body?.code ?? '').trim();
+  if (!code) {
+    return res.status(400).json({ ok: false, error: 'Invite code is required' });
+  }
+
+  try {
+    const result = await pairMember({
+      vaultPath: getVaultPath(),
+      code,
+      user: req.user,
+    });
+
+    res.json({
+      ok: true,
+      paired: result.paired,
+      reason: result.reason,
+      vaultId: result.state.vaultId,
+      memberCount: Object.keys(result.state.members ?? {}).length,
+    });
+  } catch (err) {
+    res.status(400).json({ ok: false, error: err instanceof Error ? err.message : String(err) });
+  }
+});
+
+router.post('/unpair', expressMiddleware, async (req, res) => {
+  if (!assertOwner(req, res)) return;
+  const discordId = String(req.body?.discordId ?? '').trim();
+  if (!discordId) {
+    return res.status(400).json({ ok: false, error: 'discordId is required' });
+  }
+  try {
+    const result = await removeMember({ vaultPath: getVaultPath(), discordId });
+    res.json({
+      ok: true,
+      removed: result.removed,
+      discordId,
+      memberCount: Object.keys(result.state.members ?? {}).length,
+    });
+  } catch (err) {
+    res.status(400).json({ ok: false, error: err instanceof Error ? err.message : String(err) });
+  }
+});
+
+router.post('/invite/create', expressMiddleware, async (req, res) => {
+  if (!assertOwner(req, res)) return;
+  try {
+    const invite = await createInvite({
+      vaultPath: getVaultPath(),
+      ownerDiscordId: getOwnerDiscordId(),
+      createdBy: req.user.id,
+    });
+    res.json({ ok: true, invite });
+  } catch (err) {
+    res.status(400).json({ ok: false, error: err instanceof Error ? err.message : String(err) });
+  }
+});
+
+router.get('/invite/list', expressMiddleware, async (req, res) => {
+  if (!assertOwner(req, res)) return;
+  try {
+    const invites = await listInvites(getVaultPath());
+    res.json({ ok: true, invites });
+  } catch (err) {
+    res.status(400).json({ ok: false, error: err instanceof Error ? err.message : String(err) });
+  }
+});
+
+router.post('/invite/revoke', expressMiddleware, async (req, res) => {
+  if (!assertOwner(req, res)) return;
+  const code = String(req.body?.code ?? '').trim();
+  if (!code) {
+    return res.status(400).json({ ok: false, error: 'code is required' });
+  }
+  try {
+    const invite = await revokeInvite({ vaultPath: getVaultPath(), code });
+    res.json({ ok: true, invite });
+  } catch (err) {
+    res.status(400).json({ ok: false, error: err instanceof Error ? err.message : String(err) });
+  }
+});
+
+export default router;