@fyresmith/hive-server 3.0.0 → 4.0.0

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

@@ -19,6 +19,7 @@ export const REQUIRED_ENV_KEYS = [
   'DISCORD_CLIENT_SECRET',
   'DISCORD_REDIRECT_URI',
   'DISCORD_GUILD_ID',
+  'OWNER_DISCORD_ID',
   'JWT_SECRET',
   'VAULT_PATH',
   'PORT',

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

@@ -114,6 +114,7 @@ export async function promptForEnv({ envFile, existing, yes = false, preset = {}
     { 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' },

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/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',
@@ -15,6 +17,7 @@ const REQUIRED = [
   'DISCORD_CLIENT_SECRET',
   'DISCORD_REDIRECT_URI',
   'DISCORD_GUILD_ID',
+  'OWNER_DISCORD_ID',
 ];
 
 function validateEnv() {
@@ -51,6 +54,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);
@@ -66,6 +70,7 @@ export async function startHiveServer(options = {}) {
 
   // Auth routes
   app.use('/auth', authRoutes);
+  app.use('/managed', managedRoutes);
 
   // Health check
   app.get('/health', (req, res) => res.json({ ok: true, ts: Date.now() }));

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/socketHandler.js

@@ -19,6 +19,12 @@ const socketToFiles = new Map();
  */
 const userBySocket = new Map();
 
+/**
+ * claimedFiles: file path → { socketId, userId, username, color }
+ * @type {Map<string, object>}
+ */
+const claimedFiles = new Map();
+
 function respond(cb, payload) {
   if (typeof cb === 'function') cb(payload);
 }
@@ -184,6 +190,38 @@ export function attachHandlers(io, getActiveRooms, broadcastFileUpdated, forceCl
       }
     });
 
+    // -----------------------------------------------------------------------
+    // file-claim
+    // -----------------------------------------------------------------------
+    socket.on('file-claim', ({ relPath } = {}, cb) => {
+      if (!isAllowedPath(relPath)) return respond(cb, { ok: false, error: 'Not allowed' });
+      const claimUser = userBySocket.get(socket.id);
+      if (!claimUser) return;
+      claimedFiles.set(relPath, { socketId: socket.id, ...claimUser });
+      io.emit('file-claimed', { relPath, user: claimUser });
+      respond(cb, { ok: true });
+    });
+
+    // -----------------------------------------------------------------------
+    // file-unclaim
+    // -----------------------------------------------------------------------
+    socket.on('file-unclaim', ({ relPath } = {}, cb) => {
+      const claim = claimedFiles.get(relPath);
+      if (claim?.socketId !== socket.id) return respond(cb, { ok: false, error: 'Not your claim' });
+      claimedFiles.delete(relPath);
+      io.emit('file-unclaimed', { relPath, userId: userBySocket.get(socket.id)?.id });
+      respond(cb, { ok: true });
+    });
+
+    // -----------------------------------------------------------------------
+    // user-status-changed
+    // -----------------------------------------------------------------------
+    socket.on('user-status-changed', ({ status } = {}) => {
+      const statusUser = userBySocket.get(socket.id);
+      if (!statusUser) return;
+      socket.broadcast.emit('user-status-changed', { userId: statusUser.id, status });
+    });
+
     // -----------------------------------------------------------------------
     // presence-file-opened
     // -----------------------------------------------------------------------
@@ -219,6 +257,15 @@ export function attachHandlers(io, getActiveRooms, broadcastFileUpdated, forceCl
         socket.broadcast.emit('presence-file-closed', { relPath, user });
       }
       socketToFiles.delete(socket.id);
+
+      // Release all file claims held by this socket
+      for (const [relPath, claim] of claimedFiles) {
+        if (claim.socketId === socket.id) {
+          claimedFiles.delete(relPath);
+          io.emit('file-unclaimed', { relPath, userId: claim.id });
+        }
+      }
+
       userBySocket.delete(socket.id);
       socket.broadcast.emit('user-left', { user });
     });

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

@@ -209,7 +209,7 @@ export function startYjsServer(broadcastFileUpdated) {
   const port = parseInt(process.env.YJS_PORT ?? '3001', 10);
   const wss = new WebSocketServer({ port });
 
-  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 +223,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;
     }
 

package/package.json

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

package/routes/managed.js

@@ -0,0 +1,163 @@
+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();
+
+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;