workbite 0.1.19 → 0.1.20

package/lib/mcp-task-context.js

@@ -0,0 +1,188 @@
+'use strict';
+// An inherited hint is discovery data, never Task write authority or a provider grant.
+const fs = require('node:fs/promises');
+const { constants } = require('node:fs');
+const path = require('node:path');
+const { execFile } = require('node:child_process');
+const { promisify } = require('node:util');
+const { createHash } = require('node:crypto');
+const { UUID } = require('./common');
+const execute = promisify(execFile);
+const SCHEMA = 'stackbite.workstack-task-context.v1';
+const MAX_CONTEXT = 1024 * 1024, MAX_SNAPSHOT = 32768;
+const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const identifier = value => typeof value === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(value);
+const refuse = reason => { throw Object.assign(new Error(reason), { code: 'task_context_unavailable', reason }); };
+function absolute(value) {
+  if (typeof value !== 'string' || !path.isAbsolute(value) || /[\x00-\x1f]/.test(value)
+      || /^(?:\\\\|\/\/)/.test(value)
+      || (process.platform === 'win32' && /^[\\/](?![\\/])/.test(value))) refuse('unsafe_context_path');
+  return path.resolve(value);
+}
+function samePath(a, b) {
+  return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+async function regularDirectory(directory) {
+  const parent = path.dirname(directory);
+  if (parent !== directory) await regularDirectory(parent);
+  const info = await fs.lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink()) refuse('linked_context_path');
+}
+async function readRegular(filename, limit) {
+  const target = absolute(filename);
+  await regularDirectory(path.dirname(target));
+  const before = await fs.lstat(target);
+  if (!before.isFile() || before.isSymbolicLink() || before.size > limit) refuse('unsafe_or_oversized_context_file');
+  const handle = await fs.open(target, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+  try {
+    const info = await handle.stat();
+    if (!info.isFile() || info.size > limit || info.dev !== before.dev || info.ino !== before.ino) refuse('context_file_changed');
+    const buffer = Buffer.alloc(limit + 1);
+    let size = 0;
+    while (size < buffer.length) {
+      const next = await handle.read(buffer, size, buffer.length - size, null);
+      if (!next.bytesRead) break;
+      size += next.bytesRead;
+    }
+    if (size > limit) refuse('unsafe_or_oversized_context_file');
+    return buffer.subarray(0, size);
+  } finally { await handle.close(); }
+}
+// JSON.parse accepts duplicate keys. Walk the bounded document first so an identity
+// cannot mean different things to the producer and this consumer. Depth is bounded too.
+function strictJson(bytes) {
+  const source = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  let pos = 0;
+  const white = () => { while (/[ \t\r\n]/.test(source[pos] || '\u0000')) pos++; };
+  function string() {
+    const start = pos++;
+    while (pos < source.length) {
+      if (source[pos] === '\\') { pos += 2; continue; }
+      if (source[pos++] === '"') return JSON.parse(source.slice(start, pos));
+    }
+    refuse('invalid_context_json');
+  }
+  function value(depth) {
+    if (depth > 64) refuse('invalid_context_json');
+    white();
+    if (source[pos] === '"') { string(); return; }
+    if (source[pos] === '{' || source[pos] === '[') {
+      const object = source[pos++] === '{', end = object ? '}' : ']', keys = new Set();
+      white();
+      if (source[pos] === end) { pos++; return; }
+      for (;;) {
+        white();
+        if (object) {
+          if (source[pos] !== '"') refuse('invalid_context_json');
+          const key = string();
+          if (keys.has(key)) refuse('duplicate_context_key');
+          keys.add(key); white();
+          if (source[pos++] !== ':') refuse('invalid_context_json');
+        }
+        value(depth + 1); white();
+        const next = source[pos++];
+        if (next === end) return;
+        if (next !== ',') refuse('invalid_context_json');
+      }
+    }
+    const match = /^(?:null|true|false|-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?)/.exec(source.slice(pos));
+    if (!match) refuse('invalid_context_json');
+    pos += match[0].length;
+  }
+  value(0); white();
+  if (pos !== source.length) refuse('invalid_context_json');
+  return JSON.parse(source);
+}
+function matchesTask(envelope, binding, fresh = false) {
+  const task = envelope?.data?.task;
+  return plain(envelope) && envelope.contract === 'workstack.cli.v1' && !Object.hasOwn(envelope, 'error')
+    && envelope.meta?.command === 'agent.context' && envelope.meta?.workspace_uid === binding.workspace_uid
+    && envelope.data?.workspace_uid === binding.workspace_uid && plain(task)
+    && task.id === binding.task_id && task.uid === binding.task_uid
+    && Number.isSafeInteger(task.revision)
+    && (fresh ? task.revision >= binding.task_revision : task.revision === binding.task_revision);
+}
+function generationOf(environment) {
+  const generation = environment.STACKBITE_SESSION_GENERATION;
+  if (!identifier(generation) || (environment.STACKBITE_SEAT_GENERATION !== undefined
+      && environment.STACKBITE_SEAT_GENERATION !== generation)) refuse('seat_generation_mismatch');
+  return generation;
+}
+function identity(hint, environment) {
+  if (!identifier(environment.STACKBITE_ROOM_ID) || !identifier(environment.STACKBITE_SEAT_KEY)
+      || hint.room_id !== environment.STACKBITE_ROOM_ID || hint.seat_key !== environment.STACKBITE_SEAT_KEY)
+    refuse('seat_identity_mismatch');
+  const generation = generationOf(environment);
+  if (hint.generation !== null && hint.generation !== generation) refuse('seat_generation_mismatch');
+}
+async function loadHint(environment) {
+  if (!environment.STACKBITE_CONTEXT_FILE) return null;
+  try {
+    const document = strictJson(await readRegular(environment.STACKBITE_CONTEXT_FILE, MAX_CONTEXT));
+    if (!plain(document)) refuse('invalid_launch_context');
+    if (!Object.hasOwn(document, 'workstack_task_context')) return null; // old / standalone Seat
+    const hint = document.workstack_task_context;
+    if (!plain(hint) || hint.schema !== SCHEMA || hint.status !== 'bound') refuse('task_context_unverified');
+    identity(hint, environment);
+    if (document.room_id !== hint.room_id || (document.seat_key ?? document.seat_id) !== hint.seat_key)
+      refuse('seat_identity_mismatch');
+    const b = hint.task_binding, s = hint.context_snapshot;
+    if (!plain(b) || b.schema !== 'workstack.task-binding.v1' || Object.keys(b).length !== 5
+        || !UUID.test(b.workspace_uid) || typeof b.task_uid !== 'string' || !b.task_uid || b.task_uid.length > 128
+        || /[\x00-\x1f\x7f-\x9f]/.test(b.task_uid) || !/^T-[0-9]{4,}$/.test(b.task_id)
+        || b.task_id.length > 64 || !Number.isSafeInteger(b.task_revision) || b.task_revision < 0
+        || !plain(s) || s.contract !== 'workstack.cli.v1' || !/^[0-9a-f]{64}$/.test(s.sha256)
+        || !UUID.test(hint.request_id) || typeof hint.backend_id !== 'string'
+        || !/^[A-Za-z0-9_-]{1,128}$/.test(hint.backend_id)) refuse('invalid_task_handoff');
+    const state = absolute(environment.STACKBITE_STATE_DIR);
+    if (!samePath(absolute(environment.STACKBITE_CONTEXT_FILE), path.join(state, 'agent-context', hint.room_id, hint.seat_key + '.json'))
+        || !samePath(absolute(s.path), path.join(state, 'task-workspaces', hint.request_id, 'context.json')))
+      refuse('context_path_mismatch');
+    const bytes = await readRegular(s.path, MAX_SNAPSHOT);
+    if (createHash('sha256').update(bytes).digest('hex') !== s.sha256) refuse('snapshot_digest_mismatch');
+    if (!matchesTask(strictJson(bytes), b)) refuse('snapshot_task_mismatch');
+    return hint;
+  } catch (error) {
+    if (error.code === 'task_context_unavailable') throw error;
+    refuse('context_file_unreadable');
+  }
+}
+function commandArgv(environment) {
+  let argv;
+  try { argv = JSON.parse(environment.STACKBITE_AGENT_COMMAND); } catch { refuse('seat_cli_unavailable'); }
+  if (!Array.isArray(argv) || !argv.every(arg => typeof arg === 'string' && arg.length < 4096 && !/[\x00-\x1f]/.test(arg)))
+    refuse('seat_cli_unavailable');
+  const executable = argv[0];
+  if (!executable || !path.isAbsolute(executable)) refuse('seat_cli_unavailable');
+  const base = path.basename(executable).toLowerCase();
+  const frozen = argv.length === 2 && /^(?:stackbite|workbite-execution)(?:\.exe)?$/.test(base) && argv[1] === 'agent';
+  const python = argv.length === 3 && /^python(?:3(?:\.[0-9]+)?)?(?:\.exe)?$/.test(base)
+    && path.isAbsolute(argv[1]) && path.basename(argv[1]) === 'stackbite.py' && argv[2] === 'agent';
+  if (!frozen && !python) refuse('seat_cli_unavailable');
+  return argv;
+}
+async function readSeat(environment) {
+  const argv = commandArgv(environment);
+  try {
+    const result = await execute(argv[0], [...argv.slice(1), 'context', '--format', 'full'], {
+      env: environment, shell: false, windowsHide: true, timeout: 10000, maxBuffer: MAX_CONTEXT, encoding: 'buffer' });
+    return strictJson(result.stdout);
+  } catch { refuse('live_seat_unavailable'); }
+}
+async function verifySeat(hint, environment, reader = readSeat) {
+  identity(hint, environment);
+  const live = await reader(environment), seat = live?.seat;
+  if (live?.room?.room_id !== hint.room_id || seat?.seat_key !== hint.seat_key
+      || seat.generation !== generationOf(environment) || seat.is_alive !== true) refuse('live_seat_mismatch');
+  const current = live.onboarding?.workstack_task_context;
+  if (!plain(current) || current.schema !== SCHEMA || current.status !== 'bound'
+      || current.room_id !== hint.room_id || current.seat_key !== hint.seat_key
+      || current.backend_id !== hint.backend_id || current.request_id !== hint.request_id
+      || !plain(current.task_binding) || Object.keys(current.task_binding).length !== 5
+      || Object.keys(hint.task_binding).some(key => current.task_binding[key] !== hint.task_binding[key])
+      || current.context_snapshot?.sha256 !== hint.context_snapshot.sha256
+      || current.context_snapshot?.path !== hint.context_snapshot.path
+      || current.context_snapshot?.contract !== hint.context_snapshot.contract
+      || (current.generation !== null && current.generation !== generationOf(environment))) refuse('live_assignment_changed');
+}
+module.exports = { loadHint, verifySeat, matchesTask, readRegular, strictJson, commandArgv };