@mmmbuto/nexuscrew 0.8.51 → 0.8.52-rc.1

package/lib/vl-nodes/routes.js

@@ -0,0 +1,195 @@
+'use strict';
+
+const express = require('express');
+const { bearerFrom } = require('../auth/middleware.js');
+const store = require('./store.js');
+const { PROTOCOL, MAX_WAIT_MS } = require('./broker.js');
+
+const OWNER_ID_RE = /^[a-f0-9]{16,64}$/;
+const SIMPLE_COMMANDS = new Set([
+  'status', 'health', 'start', 'stop', 'restart', 'version', 'capabilities', 'unpair',
+]);
+const MAX_CANDIDATE_BYTES = 2_621_440;
+
+function commandOf(body) {
+  if (!body || typeof body.kind !== 'string') return null;
+  if (SIMPLE_COMMANDS.has(body.kind)) {
+    if (body.args !== undefined && (typeof body.args !== 'object' || body.args === null
+      || Array.isArray(body.args) || Object.keys(body.args).length > 0)) return null;
+    return { kind: body.kind, args: {} };
+  }
+  if (body.kind === 'logs') {
+    const limit = body.args && body.args.limit;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) return null;
+    return { kind: 'logs', args: { limit } };
+  }
+  if (body.kind === 'update_candidate') {
+    const args = body.args;
+    if (!args || typeof args !== 'object' || Array.isArray(args)) return null;
+    const keys = Object.keys(args).sort();
+    if (keys.join(',') !== 'sha256,size,url,version') return null;
+    if (typeof args.url !== 'string' || args.url.length > 2048) return null;
+    let parsed;
+    try { parsed = new URL(args.url); } catch (_) { return null; }
+    if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password) return null;
+    if (!/^[a-f0-9]{64}$/.test(String(args.sha256 || ''))) return null;
+    if (!Number.isSafeInteger(args.size) || args.size < 1 || args.size > MAX_CANDIDATE_BYTES) return null;
+    if (typeof args.version !== 'string' || !/^[A-Za-z0-9._+-]{1,64}$/.test(args.version)) return null;
+    return {
+      kind: body.kind,
+      args: { url: parsed.toString(), sha256: args.sha256, size: args.size, version: args.version },
+    };
+  }
+  return null;
+}
+
+function nodeToken(req) {
+  const token = bearerFrom(req);
+  return store.TOKEN_RE.test(String(token || '')) ? token : null;
+}
+
+function jsonBodyError(error, _req, res, _next) {
+  if (error && (error.type === 'entity.too.large' || error.status === 413)) {
+    return res.status(413).json({ error: 'body too large' });
+  }
+  if (error instanceof SyntaxError) return res.status(400).json({ error: 'invalid JSON' });
+  return res.status(400).json({ error: String(error?.message || error) });
+}
+
+function publicRoutes({ storePath, broker, ownerId }) {
+  const r = express.Router();
+  const body = express.json({ limit: '20kb' });
+
+  r.post('/pair', body, (req, res) => {
+    const localOwner = ownerId();
+    if (!OWNER_ID_RE.test(String(localOwner || ''))) return res.status(503).json({ error: 'owner identity unavailable' });
+    if (!req.body || req.body.protocol !== PROTOCOL) return res.status(400).json({ error: 'unsupported protocol' });
+    const invite = req.get('x-vl-invite');
+    const paired = store.pairNode(storePath, {
+      invite,
+      nodeId: req.body.nodeId,
+      label: req.body.label,
+    });
+    if (!paired.ok) {
+      const status = paired.code === 'node-exists' ? 409
+        : paired.code === 'invite-expired-or-used' ? 410 : 400;
+      return res.status(status).json({ error: paired.code });
+    }
+    return res.status(201).json({
+      protocol: PROTOCOL,
+      ownerId: localOwner,
+      nodeId: paired.node.nodeId,
+      label: paired.node.label,
+      token: paired.token,
+      pollMaxMs: MAX_WAIT_MS,
+    });
+  });
+
+  r.post('/poll', body, async (req, res) => {
+    const token = nodeToken(req);
+    const node = token && store.authenticate(storePath, token);
+    if (!node || req.body?.nodeId !== node.nodeId) return res.status(401).json({ error: 'unauthorized-node' });
+    const abort = new AbortController();
+    req.once('aborted', () => abort.abort());
+    const result = await broker.poll(node, req.body, {
+      waitMs: Number(req.get('x-vl-wait-ms')) || MAX_WAIT_MS,
+      signal: abort.signal,
+    });
+    if (res.headersSent || res.destroyed) return undefined;
+    if (result.type === 'command') return res.json({ protocol: PROTOCOL, command: result.command });
+    if (result.type === 'idle' || result.type === 'aborted' || result.type === 'acknowledged') {
+      return res.status(204).end();
+    }
+    if (result.type === 'superseded') return res.status(409).json({ error: 'stale-session', generation: result.generation });
+    if (result.type === 'revoked') return res.status(401).json({ error: 'unpaired' });
+    return res.status(400).json({ error: result.code || 'invalid-heartbeat' });
+  });
+
+  r.post('/unpair', body, (req, res) => {
+    const token = nodeToken(req);
+    const node = token && store.authenticate(storePath, token);
+    if (!node || req.body?.nodeId !== node.nodeId || req.body?.protocol !== PROTOCOL) {
+      return res.status(401).json({ error: 'unauthorized-node' });
+    }
+    store.removeNode(storePath, node.nodeId);
+    broker.forget(node.nodeId);
+    return res.status(204).end();
+  });
+
+  r.use(jsonBodyError);
+
+  return r;
+}
+
+function apiRoutes({ storePath, broker, ownerId, readonly = () => false }) {
+  const r = express.Router();
+
+  r.get('/', (_req, res) => {
+    const localOwner = ownerId();
+    if (!OWNER_ID_RE.test(String(localOwner || ''))) return res.status(503).json({ error: 'owner identity unavailable' });
+    const nodes = broker.list(store.listNodes(storePath)).map((node) => ({
+      ...node,
+      id: `${localOwner}:VL-${node.nodeId}`,
+      instanceId: localOwner,
+      cell: `VL-${node.nodeId.slice(0, 8)}`,
+      canReceive: false,
+      canManage: node.online === true,
+    }));
+    return res.json({ instanceId: localOwner, protocol: PROTOCOL, nodes });
+  });
+
+  r.post('/invite', express.json({ limit: '4kb' }), (req, res) => {
+    if (readonly()) return res.status(403).json({ error: 'READONLY: invite blocked' });
+    const localOwner = ownerId();
+    if (!OWNER_ID_RE.test(String(localOwner || ''))) return res.status(503).json({ error: 'owner identity unavailable' });
+    const ttlSeconds = req.body?.ttlSeconds === undefined ? undefined : Number(req.body.ttlSeconds);
+    if (ttlSeconds !== undefined && (!Number.isSafeInteger(ttlSeconds) || ttlSeconds < 30 || ttlSeconds > 3600)) {
+      return res.status(400).json({ error: 'ttlSeconds must be 30..3600' });
+    }
+    const invite = store.createInvite(storePath, {
+      label: req.body?.label,
+      ...(ttlSeconds === undefined ? {} : { ttlMs: ttlSeconds * 1000 }),
+    });
+    return res.status(201).json({ protocol: PROTOCOL, ownerId: localOwner, ...invite });
+  });
+
+  r.post('/:nodeId/commands', express.json({ limit: '8kb' }), (req, res) => {
+    if (readonly()) return res.status(403).json({ error: 'READONLY: command blocked' });
+    if (!store.NODE_ID_RE.test(String(req.params.nodeId || ''))
+      || !store.listNodes(storePath).some((node) => node.nodeId === req.params.nodeId)) {
+      return res.status(404).json({ error: 'node not paired' });
+    }
+    const command = commandOf(req.body);
+    if (!command) return res.status(400).json({ error: 'invalid bounded command' });
+    const result = broker.dispatch(req.params.nodeId, command);
+    if (!result.ok) {
+      const status = result.code === 'node-offline' || result.code === 'command-in-flight' ? 409 : 400;
+      return res.status(status).json({ error: result.code });
+    }
+    return res.status(202).json({
+      id: result.id,
+      status: result.status,
+      note: 'submitted confirms delivery to a live poll only; completion requires the node ack',
+    });
+  });
+
+  r.delete('/:nodeId', (req, res) => {
+    if (readonly()) return res.status(403).json({ error: 'READONLY: revoke blocked' });
+    if (!store.removeNode(storePath, req.params.nodeId)) return res.status(404).json({ error: 'node not paired' });
+    broker.forget(req.params.nodeId);
+    return res.status(204).end();
+  });
+
+  r.use(jsonBodyError);
+
+  return r;
+}
+
+module.exports = {
+  OWNER_ID_RE,
+  SIMPLE_COMMANDS,
+  MAX_CANDIDATE_BYTES,
+  commandOf,
+  publicRoutes,
+  apiRoutes,
+};

package/lib/vl-nodes/store.js

@@ -0,0 +1,203 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const NODE_ID_RE = /^[a-f0-9]{32}$/;
+const TOKEN_RE = /^[a-f0-9]{64}$/;
+const STORE_VERSION = 1;
+const DEFAULT_INVITE_TTL_MS = 10 * 60 * 1000;
+const MAX_INVITE_TTL_MS = 60 * 60 * 1000;
+const MAX_STORE_BYTES = 256 * 1024;
+
+function emptyStore() {
+  return { version: STORE_VERSION, invites: [], nodes: [] };
+}
+
+function defaultPath(home) {
+  return path.join(home, '.nexuscrew', 'vl-nodes.json');
+}
+
+function cleanLabel(value, fallback = 'VL') {
+  if (typeof value !== 'string') return fallback;
+  const clean = value.normalize('NFC').replace(/[\p{Cc}\p{Cf}]/gu, '').trim();
+  return clean ? clean.slice(0, 48) : fallback;
+}
+
+function validRecord(record) {
+  return record && NODE_ID_RE.test(String(record.nodeId || ''))
+    && TOKEN_RE.test(String(record.tokenHash || ''))
+    && Number.isSafeInteger(record.pairedAt) && record.pairedAt > 0
+    && typeof record.label === 'string' && record.label.length > 0 && record.label.length <= 48;
+}
+
+function normalizeStore(raw, now = Date.now()) {
+  if (!raw || raw.version !== STORE_VERSION) return emptyStore();
+  const invites = Array.isArray(raw.invites) ? raw.invites.filter((invite) => (
+    invite && TOKEN_RE.test(String(invite.tokenHash || ''))
+      && Number.isSafeInteger(invite.expiresAt) && invite.expiresAt > now
+      && typeof invite.label === 'string' && invite.label.length > 0 && invite.label.length <= 48
+  )).slice(-64) : [];
+  const seen = new Set();
+  const nodes = [];
+  for (const record of Array.isArray(raw.nodes) ? raw.nodes : []) {
+    if (!validRecord(record) || seen.has(record.nodeId)) continue;
+    seen.add(record.nodeId);
+    nodes.push({
+      nodeId: record.nodeId,
+      label: cleanLabel(record.label),
+      tokenHash: record.tokenHash,
+      pairedAt: record.pairedAt,
+    });
+  }
+  return { version: STORE_VERSION, invites, nodes };
+}
+
+function ownedByCurrentUser(stat) {
+  return typeof process.getuid !== 'function' || stat.uid === process.getuid();
+}
+
+function assertSafeFile(stat) {
+  if (stat.isSymbolicLink() || !stat.isFile() || !ownedByCurrentUser(stat)
+    || (stat.mode & 0o077) !== 0 || stat.size > MAX_STORE_BYTES) {
+    throw new Error('unsafe VL node store');
+  }
+}
+
+function loadStore(file, now = Date.now()) {
+  let fd;
+  try {
+    fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    assertSafeFile(fs.fstatSync(fd));
+    return normalizeStore(JSON.parse(fs.readFileSync(fd, 'utf8')), now);
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return emptyStore();
+    throw error;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+function atomicWriteStore(file, store, now = Date.now()) {
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const dirStat = fs.lstatSync(dir);
+  if (dirStat.isSymbolicLink() || !dirStat.isDirectory() || !ownedByCurrentUser(dirStat)) {
+    throw new Error('unsafe VL node store directory');
+  }
+  fs.chmodSync(dir, 0o700);
+  try {
+    assertSafeFile(fs.lstatSync(file));
+  } catch (error) {
+    if (!error || error.code !== 'ENOENT') throw error;
+  }
+  const tmp = `${file}.tmp.${process.pid}.${crypto.randomBytes(8).toString('hex')}`;
+  const fd = fs.openSync(tmp, 'wx', 0o600);
+  try {
+    const payload = `${JSON.stringify(normalizeStore(store, now), null, 2)}\n`;
+    fs.writeFileSync(fd, payload, { encoding: 'utf8' });
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  try {
+    fs.renameSync(tmp, file);
+    fs.chmodSync(file, 0o600);
+    try {
+      const dirFd = fs.openSync(dir, 'r');
+      try { fs.fsyncSync(dirFd); } finally { fs.closeSync(dirFd); }
+    } catch (_) {}
+  } catch (error) {
+    try { fs.unlinkSync(tmp); } catch (_) {}
+    throw error;
+  }
+}
+
+function digest(token) {
+  return crypto.createHash('sha256').update(String(token), 'utf8').digest('hex');
+}
+
+function timingSafeHex(left, right) {
+  if (!TOKEN_RE.test(String(left || '')) || !TOKEN_RE.test(String(right || ''))) return false;
+  return crypto.timingSafeEqual(Buffer.from(left, 'hex'), Buffer.from(right, 'hex'));
+}
+
+function randomToken(randomBytes = crypto.randomBytes) {
+  return randomBytes(32).toString('hex');
+}
+
+function createInvite(file, { label = 'VL', ttlMs = DEFAULT_INVITE_TTL_MS } = {}, seams = {}) {
+  const now = typeof seams.now === 'function' ? seams.now() : Date.now();
+  const boundedTtl = Math.max(30_000, Math.min(MAX_INVITE_TTL_MS, Number(ttlMs) || DEFAULT_INVITE_TTL_MS));
+  const token = randomToken(seams.randomBytes);
+  const store = loadStore(file, now);
+  store.invites.push({ tokenHash: digest(token), expiresAt: now + boundedTtl, label: cleanLabel(label) });
+  store.invites = store.invites.filter((invite) => invite.expiresAt > now).slice(-64);
+  atomicWriteStore(file, store, now);
+  return { invite: token, expiresAt: now + boundedTtl, label: cleanLabel(label) };
+}
+
+function pairNode(file, { invite, nodeId, label }, seams = {}) {
+  if (!TOKEN_RE.test(String(invite || ''))) return { ok: false, code: 'invalid-invite' };
+  if (!NODE_ID_RE.test(String(nodeId || ''))) return { ok: false, code: 'invalid-node-id' };
+  const now = typeof seams.now === 'function' ? seams.now() : Date.now();
+  const store = loadStore(file, now);
+  if (store.nodes.some((node) => node.nodeId === nodeId)) return { ok: false, code: 'node-exists' };
+  const inviteHash = digest(invite);
+  const index = store.invites.findIndex((row) => timingSafeHex(row.tokenHash, inviteHash));
+  if (index < 0) return { ok: false, code: 'invite-expired-or-used' };
+  const [accepted] = store.invites.splice(index, 1);
+  const token = randomToken(seams.randomBytes);
+  const record = {
+    nodeId,
+    label: cleanLabel(label, accepted.label),
+    tokenHash: digest(token),
+    pairedAt: now,
+  };
+  store.nodes.push(record);
+  atomicWriteStore(file, store, now);
+  return { ok: true, token, node: { nodeId, label: record.label, pairedAt: now } };
+}
+
+function authenticate(file, token, now = Date.now()) {
+  if (!TOKEN_RE.test(String(token || ''))) return null;
+  const tokenHash = digest(token);
+  const record = loadStore(file, now).nodes.find((node) => timingSafeHex(node.tokenHash, tokenHash));
+  return record ? { nodeId: record.nodeId, label: record.label, pairedAt: record.pairedAt } : null;
+}
+
+function removeNode(file, nodeId, now = Date.now()) {
+  if (!NODE_ID_RE.test(String(nodeId || ''))) return false;
+  const store = loadStore(file, now);
+  const kept = store.nodes.filter((node) => node.nodeId !== nodeId);
+  if (kept.length === store.nodes.length) return false;
+  store.nodes = kept;
+  atomicWriteStore(file, store, now);
+  return true;
+}
+
+function listNodes(file, now = Date.now()) {
+  return loadStore(file, now).nodes.map(({ nodeId, label, pairedAt }) => ({ nodeId, label, pairedAt }));
+}
+
+module.exports = {
+  NODE_ID_RE,
+  TOKEN_RE,
+  STORE_VERSION,
+  DEFAULT_INVITE_TTL_MS,
+  MAX_INVITE_TTL_MS,
+  emptyStore,
+  defaultPath,
+  cleanLabel,
+  normalizeStore,
+  loadStore,
+  atomicWriteStore,
+  digest,
+  timingSafeHex,
+  createInvite,
+  pairNode,
+  authenticate,
+  removeNode,
+  listNodes,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmmbuto/nexuscrew",
-  "version": "0.8.51",
+  "version": "0.8.52-rc.1",
   "description": "Faithful browser tmux client — attach to live sessions over a real PTY, localhost-only, mobile-easy",
   "main": "lib/server.js",
   "bin": {

package/skills/nexuscrew-agent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nexuscrew-agent
-description: Use when an AI agent connected to NexusCrew must notify or ask the human, inspect runtime or deck context, list authorized Fleet cells, message an exact active cell, read its inbox, deliver a file, recover from local tmux messages that remain unsubmitted or garbled, or when a drag in the web terminal does not scroll a full-screen TUI. Prefer nc_notify, nc_ask, nc_status, nc_deck, nc_cells, nc_send_cell, nc_inbox, and nc_send_file; use bundled tmux/file helpers only as a declared compatibility fallback.
+description: Use when an AI agent connected to NexusCrew must notify or ask the human, inspect runtime or deck context, manage exact authorized VL micro-device nodes, list authorized Fleet cells, message an exact active cell, read its inbox, deliver a file, recover from local tmux messages that remain unsubmitted or garbled, or when a drag in the web terminal does not scroll a full-screen TUI. Prefer nc_notify, nc_ask, nc_status, nc_deck, nc_cells, nc_vl_nodes, nc_vl_command, nc_send_cell, nc_inbox, and nc_send_file; use bundled tmux/file helpers only as a declared compatibility fallback.
 ---
 
 # NexusCrew Agent I/O
@@ -19,6 +19,10 @@ When the client exposes the NexusCrew MCP server, use these tools directly:
 | Read the caller's deck name(s) and member cells/tmux sessions | `nc_deck` |
 | List every authorized owner-qualified Fleet cell | `nc_cells` |
 | Submit a bounded message to an exact active Fleet cell | `nc_send_cell` |
+| List authorized VL micro-device owners/nodes | `nc_vl_nodes` |
+| Create a one-time VL pairing invite | `nc_vl_invite` |
+| Deliver a bounded VL command | `nc_vl_command` |
+| Revoke an exact VL pairing | `nc_vl_revoke` |
 | List files received for the current session | `nc_inbox` |
 | Deliver an absolute file path under the user's home | `nc_send_file` |
 
@@ -30,6 +34,7 @@ Apply these rules:
 - Use `nc_status` instead of scraping NexusCrew state files. Use `nc_deck` instead of reading `decks.json`: it returns every local or authorized shared-owner deck containing the caller, preserves visual member order, identifies each deck and member by stable owner ID, includes viewer-valid Hydra routes, and reports `cell: null` when no managed Fleet match is available.
 - Use `nc_cells` immediately before cross-cell delivery. Select its exact owner-qualified `id`; require `canReceive: true`; never guess a duplicate name or stale route.
 - Use `nc_send_cell {target, message}` for actual Fleet-cell delivery. `submitted` confirms bracketed paste plus Enter only, never task acceptance or completion. Inactive targets are not queued.
+- Use `nc_vl_nodes` immediately before VL mutation. Mutation tools require an active local Fleet caller and the full owner-qualified VL ID. `nc_vl_command` `submitted` means live-poll delivery only; require the same ID in `lastAck`. No offline queue exists.
 - Use `nc_inbox` instead of guessing an inbox path when the tool is available.
 - Pass `nc_send_file` an existing absolute regular-file path below the user's home. Let NexusCrew choose and sanitize the outbox name.
 - Do not treat an MCP notification as a substitute for the final response required by the active client.
@@ -128,6 +133,7 @@ work. The setting is also applied to windows created later in that session.
 | Discover this session's deck neighbours | `nc_deck` |
 | Discover authorized cells across nodes | `nc_cells` |
 | Submit to an exact active Fleet cell | `nc_send_cell` |
+| Discover/manage a paired VL micro-device | `nc_vl_nodes`, then `nc_vl_command` |
 | Give the human a file | `nc_send_file` or fallback `nc-deliver <file>...` |
 | Read a file the human sent | `nc_inbox` or fallback to the path in the prompt |
 | Send a prompt/command to a session | `nc-send <session> "text"` |