lazyclaw 6.3.0 → 6.4.0

package/daemon/routes/providers.mjs

@@ -74,30 +74,50 @@ export async function providersTest(c) {
           const cfg = ctx.readConfig();
           const apiKey = cfg['api-key'] || '';
           const sharedPrompt = url.searchParams.get('prompt') || 'ping';
+          // Per-provider timeout so one unreachable provider (a keyless
+          // claude-cli subprocess that never logs in, a dead network endpoint)
+          // can't hang the whole all-providers probe — without it the route
+          // blocks until every sendMessage settles. Override with ?timeoutMs=;
+          // floor 1000, default 8000.
+          const _tm = parseInt(url.searchParams.get('timeoutMs') || '', 10);
+          const perTimeoutMs = Number.isFinite(_tm) && _tm >= 1000 ? _tm : 8000;
           const tAll = Date.now();
           const results = await Promise.all(
             Object.entries(PROVIDERS).map(async ([pid, provider]) => {
               const meta = PROVIDER_INFO[pid] || {};
               const model = url.searchParams.get('model') || cfg.model || meta.defaultModel || 'unknown';
               const t0 = Date.now();
+              const ac = new AbortController();
+              let timer = null;
               try {
-                let reply = '';
-                const stream = provider.sendMessage([{ role: 'user', content: sharedPrompt }], { apiKey, model });
-                for await (const chunk of stream) {
-                  if (typeof chunk === 'string') reply += chunk;
-                }
+                const consume = (async () => {
+                  let reply = '';
+                  const stream = provider.sendMessage([{ role: 'user', content: sharedPrompt }], { apiKey, model, signal: ac.signal });
+                  for await (const chunk of stream) {
+                    if (typeof chunk === 'string') reply += chunk;
+                  }
+                  return reply;
+                })();
+                const timeout = new Promise((_, reject) => {
+                  timer = setTimeout(() => { try { ac.abort(); } catch { /* best-effort */ } reject(new Error(`timed out after ${perTimeoutMs}ms`)); }, perTimeoutMs);
+                });
+                const reply = await Promise.race([consume, timeout]);
                 return {
                   name: pid, ok: reply.length > 0, model,
                   durationMs: Date.now() - t0,
                   replyLength: reply.length,
                 };
               } catch (err) {
+                try { ac.abort(); } catch { /* best-effort */ }
+                const timedOut = /timed out after/.test(err?.message || '');
                 return {
                   name: pid, ok: false, model,
                   durationMs: Date.now() - t0,
                   error: err?.message || String(err),
-                  code: err?.code || null,
+                  code: timedOut ? 'TIMEOUT' : (err?.code || null),
                 };
+              } finally {
+                if (timer) clearTimeout(timer);
               }
             }),
           );

package/daemon/routes/workflows.mjs

@@ -222,3 +222,33 @@ export async function workflowDelete(c) {
           }
 }
 
+
+// POST /workflows/run — run a DECLARATIVE workflow (data, not code) safely.
+// The definition comes from the body ({workflow:{...}} or the def directly);
+// caps are derived from the daemon config (http SSRF-guarded + the configured
+// llm provider), never from the workflow, so a posted workflow can't spawn a
+// process or reach private hosts. Auth-gated like every non-gateway route.
+export async function workflowRun(c) {
+  const { ctx, req, res } = c;
+  let body;
+  try { body = await readJson(req); }
+  catch (e) { return writeJson(res, 400, { error: `invalid JSON body: ${e.message}` }); }
+  const def = (body && typeof body === 'object' && body.workflow) ? body.workflow : body;
+  const cfg = ctx.readConfig();
+  try {
+    const { runDeclarativeRequest } = await import('../../workflow/run_request.mjs');
+    // A body.sessionId opts into the persisted/resumable engine, keyed under the
+    // daemon's workflow-state dir — re-POSTing the same sessionId resumes.
+    const sessionId = (body && typeof body === 'object' && typeof body.sessionId === 'string' && body.sessionId) ? body.sessionId : undefined;
+    const out = await runDeclarativeRequest(def, cfg, {
+      providerLookup: (name) => PROVIDERS[name] || null,
+      input: body && typeof body === 'object' ? body.input : undefined,
+      ...(sessionId ? { sessionId, dir: ctx.workflowStateDir() } : {}),
+    });
+    return writeJson(res, out.success ? 200 : 500, out);
+  } catch (e) {
+    // WorkflowError (bad definition) → 400; anything else → 500.
+    const code = e?.code && String(e.code).startsWith('WF_') ? 400 : 500;
+    return writeJson(res, code, { error: e?.message || String(e), code: e?.code });
+  }
+}

package/daemon.mjs

@@ -18,6 +18,12 @@ import { createGateway } from './gateway/http_gateway.mjs';
 import { TokenBucketLimiter } from './ratelimit.mjs';
 import { createLogger } from './logger.mjs';
 import * as nudge from './mas/nudge.mjs';
+// MCP: cfg.mcp.servers[] are spawned once per daemon process at boot and
+// stopped on graceful shutdown. Booted here (the single per-process seam,
+// after config is available) — the unattended-safety guard runs earlier in
+// commands/daemon.mjs before startDaemon, so this only spawns once exposure
+// has been cleared. Best-effort: a failing server is logged, never fatal.
+import * as mcpSpawn from './mcp/server_spawn.mjs';
 
 // Route bodies moved to daemon/routes/*; makeHandler now only needs the
 // response/auth helpers used by the pre-switch middleware + dispatch.
@@ -160,8 +166,26 @@ export function makeHandler(ctx) {
     },
     logger,
   });
-  process.on('SIGTERM', () => { _nudgeLoop.stop(); });
-  process.on('SIGINT', () => { _nudgeLoop.stop(); });
+  // Boot any configured MCP servers (cfg.mcp.servers[]). Each registers its
+  // tools as mcp:<server>:<tool> (sensitive=true → approval gate). Fire-and-
+  // forget: startConfigured catches per-server, and we swallow the outer
+  // promise so a slow/failing spawn never blocks or crashes the daemon.
+  (async () => {
+    try {
+      const cfg = typeof ctx.readConfig === 'function' ? ctx.readConfig() : {};
+      const results = await mcpSpawn.startConfigured(cfg);
+      for (const r of results) {
+        if (r?.ok) logger?.info?.('mcp.server_started', { name: r.name, tools: r.tools?.length ?? 0 });
+        else logger?.warn?.('mcp.server_failed', { name: r?.name, err: r?.error });
+      }
+    } catch (err) {
+      logger?.warn?.('mcp.boot_failed', { err: err?.message });
+    }
+  })();
+  // Stop MCP servers on graceful shutdown (unregisters their tools too).
+  const _stopMcp = () => { mcpSpawn.stopAll().catch(() => { /* best-effort */ }); };
+  process.on('SIGTERM', () => { _nudgeLoop.stop(); _stopMcp(); });
+  process.on('SIGINT', () => { _nudgeLoop.stop(); _stopMcp(); });
   return async function handler(req, res) {
     // Capture method+path before any handler logic runs; req.url survives
     // the response but capturing now keeps the log line stable even if a

package/dotenv_min.mjs

@@ -6,9 +6,18 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { writeTextSecure } from './secure_write.mjs';
+import { configPath } from './lib/config.mjs';
+
+// Resolve the .env directory, falling back to the active config dir. Callers
+// that forward an undefined ctx.cfgDir (the /channels test slash path) used to
+// crash here (path.join(undefined,…)) and have the throw swallowed, silently
+// skipping every credential — so default rather than throw.
+function resolveCfgDir(cfgDir) {
+  return cfgDir || path.dirname(configPath());
+}
 
 export function loadDotenvIfAny(cfgDir) {
-  const p = path.join(cfgDir, '.env');
+  const p = path.join(resolveCfgDir(cfgDir), '.env');
   if (!fs.existsSync(p)) return { path: p, loaded: 0 };
   let loaded = 0;
   const raw = fs.readFileSync(p, 'utf8');
@@ -28,11 +37,14 @@ export function loadDotenvIfAny(cfgDir) {
 // (no quoting) — callers pass already-trimmed strings. Returns the path.
 // Mirror of loadDotenvIfAny so .env read + write live together.
 export function writeDotenvMerge(cfgDir, vars) {
-  const p = path.join(cfgDir, '.env');
+  const p = path.join(resolveCfgDir(cfgDir), '.env');
   const lines = [];
   const seen = new Set();
   const existing = fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : '';
-  for (const line of existing.split(/\r?\n/)) {
+  // Splitting '' yields [''] — one empty element that would be pushed ahead of
+  // the vars and surface as a leading blank line in a brand-new .env. Only walk
+  // existing lines when there is actual content to preserve.
+  for (const line of existing ? existing.split(/\r?\n/) : []) {
     const m = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=/);
     if (m && Object.prototype.hasOwnProperty.call(vars, m[1])) {
       seen.add(m[1]);

package/gateway/challenge_registry.mjs

@@ -0,0 +1,90 @@
+// gateway/challenge_registry.mjs — single-use anti-replay challenge ledger.
+//
+// Extracted from device_auth.mjs (which sat at its size ceiling) with ZERO
+// behaviour change. verifyConnect is intentionally pure (it cannot mutate
+// state), so the anti-replay guarantee lives here: every minted challenge can
+// be redeemed AT MOST ONCE and only inside its freshness window. createChallenge
+// + DEFAULT_MAX_SKEW_MS stay in device_auth.mjs (verifyConnect uses them too)
+// and are imported here, so there is one source of truth and no import cycle.
+//
+// Lifecycle per connect:
+//   const c = registry.create();          // hand `c` to the client
+//   ...client signs payload carrying c.nonce...
+//   if (!verifyConnect({ ..., challenge: c, nowMs })) reject;
+//   if (!registry.consume(c.nonce, nowMs)) reject;   // replay / expiry guard
+
+import { createChallenge, DEFAULT_MAX_SKEW_MS } from './device_auth.mjs';
+
+export class ChallengeRegistry {
+  /**
+   * @param {{ maxSkewMs?: number, maxPending?: number, sweepEvery?: number }} [opts]
+   */
+  constructor({ maxSkewMs = DEFAULT_MAX_SKEW_MS, maxPending = 10000, sweepEvery = 256 } = {}) {
+    this.maxSkewMs = maxSkewMs;
+    this.maxPending = maxPending;
+    this.sweepEvery = sweepEvery;
+    this._sinceSweep = 0;
+    /** @type {Map<string, number>} nonce -> mint ts (epoch ms) */
+    this._pending = new Map();
+  }
+
+  /**
+   * Mint and register a fresh challenge. Identical shape to createChallenge().
+   * The ledger is self-healing: stale nonces (older than ±maxSkewMs, which can
+   * never be consumed anyway) are swept opportunistically, and a hard cap
+   * evicts the oldest so an unauthenticated flood of un-redeemed challenges can
+   * never grow memory without bound.
+   * @returns {{ nonce: string, ts: number }}
+   */
+  create() {
+    const challenge = createChallenge();
+    this._pending.set(challenge.nonce, challenge.ts);
+    if (++this._sinceSweep >= this.sweepEvery) {
+      this._sinceSweep = 0;
+      this._sweep(challenge.ts);
+    }
+    // Hard cap — evict oldest (Map preserves insertion order) until within
+    // bound. O(1) amortized per create under a sustained flood.
+    while (this._pending.size > this.maxPending) {
+      const oldest = this._pending.keys().next().value;
+      if (oldest === undefined) break;
+      this._pending.delete(oldest);
+    }
+    return challenge;
+  }
+
+  // Drop entries that can no longer verify (outside ±maxSkewMs of nowMs).
+  _sweep(nowMs) {
+    for (const [nonce, ts] of this._pending) {
+      if (Math.abs(nowMs - ts) > this.maxSkewMs) this._pending.delete(nonce);
+    }
+  }
+
+  /**
+   * Redeem a challenge exactly once. Returns true only when the nonce is known,
+   * has NOT been consumed before, and is still within ±maxSkewMs of `nowMs`.
+   * Any successful or expired redemption removes the nonce so it can never be
+   * replayed.
+   *
+   * @param {string} nonce
+   * @param {number} nowMs
+   * @returns {boolean}
+   */
+  consume(nonce, nowMs) {
+    if (typeof nonce !== 'string' || nonce.length === 0) return false;
+    if (typeof nowMs !== 'number' || !Number.isFinite(nowMs)) return false;
+    const ts = this._pending.get(nonce);
+    if (ts === undefined) {
+      // Unknown OR already consumed — either way, reject as replay.
+      return false;
+    }
+    // Single-use: drop it now, before any further decision, so a concurrent or
+    // repeated call can never redeem the same nonce twice.
+    this._pending.delete(nonce);
+    const skew = Math.abs(nowMs - ts);
+    if (skew > this.maxSkewMs) {
+      return false; // expired (stale or implausibly future)
+    }
+    return true;
+  }
+}

package/gateway/device_auth.mjs

@@ -28,7 +28,7 @@ const DEVICES_FILENAME = 'devices.json';
 const PAYLOAD_VERSION = 'v3';
 const FIELD_SEP = '|';
 
-const DEFAULT_MAX_SKEW_MS = 120_000;
+export const DEFAULT_MAX_SKEW_MS = 120_000;
 
 export function defaultConfigDir() {
   return process.env.LAZYCLAW_CONFIG_DIR || path.join(os.homedir(), '.lazyclaw');
@@ -116,94 +116,10 @@ export function createChallenge() {
   };
 }
 
-/**
- * In-memory single-use challenge ledger. verifyConnect is intentionally pure
- * (it cannot mutate state), so the anti-replay guarantee lives here: every
- * minted challenge can be redeemed AT MOST ONCE and only inside its freshness
- * window.
- *
- * Lifecycle per connect:
- *   const c = registry.create();          // hand `c` to the client
- *   ...client signs payload carrying c.nonce...
- *   if (!verifyConnect({ ..., challenge: c, nowMs })) reject;
- *   if (!registry.consume(c.nonce, nowMs)) reject;   // replay / expiry guard
- *
- * `nowMs` is injected on consume() (never read from the wall-clock) so the
- * skew window is test-drivable and consistent with verifyConnect.
- */
-export class ChallengeRegistry {
-  /**
-   * @param {{ maxSkewMs?: number }} [opts]
-   */
-  constructor({ maxSkewMs = DEFAULT_MAX_SKEW_MS, maxPending = 10000, sweepEvery = 256 } = {}) {
-    this.maxSkewMs = maxSkewMs;
-    this.maxPending = maxPending;
-    this.sweepEvery = sweepEvery;
-    this._sinceSweep = 0;
-    /** @type {Map<string, number>} nonce -> mint ts (epoch ms) */
-    this._pending = new Map();
-  }
-
-  /**
-   * Mint and register a fresh challenge. Identical shape to createChallenge().
-   * The ledger is self-healing: stale nonces (older than ±maxSkewMs, which
-   * can never be consumed anyway) are swept opportunistically, and a hard
-   * cap evicts the oldest so an unauthenticated flood of un-redeemed
-   * challenges can never grow memory without bound.
-   * @returns {{ nonce: string, ts: number }}
-   */
-  create() {
-    const challenge = createChallenge();
-    this._pending.set(challenge.nonce, challenge.ts);
-    if (++this._sinceSweep >= this.sweepEvery) {
-      this._sinceSweep = 0;
-      this._sweep(challenge.ts);
-    }
-    // Hard cap — evict oldest (Map preserves insertion order) until within
-    // bound. O(1) amortized per create under a sustained flood.
-    while (this._pending.size > this.maxPending) {
-      const oldest = this._pending.keys().next().value;
-      if (oldest === undefined) break;
-      this._pending.delete(oldest);
-    }
-    return challenge;
-  }
-
-  // Drop entries that can no longer verify (outside ±maxSkewMs of nowMs).
-  _sweep(nowMs) {
-    for (const [nonce, ts] of this._pending) {
-      if (Math.abs(nowMs - ts) > this.maxSkewMs) this._pending.delete(nonce);
-    }
-  }
-
-  /**
-   * Redeem a challenge exactly once. Returns true only when the nonce is
-   * known, has NOT been consumed before, and is still within ±maxSkewMs of
-   * `nowMs`. Any successful or expired redemption removes the nonce so it can
-   * never be replayed.
-   *
-   * @param {string} nonce
-   * @param {number} nowMs
-   * @returns {boolean}
-   */
-  consume(nonce, nowMs) {
-    if (typeof nonce !== 'string' || nonce.length === 0) return false;
-    if (typeof nowMs !== 'number' || !Number.isFinite(nowMs)) return false;
-    const ts = this._pending.get(nonce);
-    if (ts === undefined) {
-      // Unknown OR already consumed — either way, reject as replay.
-      return false;
-    }
-    // Single-use: drop it now, before any further decision, so a concurrent or
-    // repeated call can never redeem the same nonce twice.
-    this._pending.delete(nonce);
-    const skew = Math.abs(nowMs - ts);
-    if (skew > this.maxSkewMs) {
-      return false; // expired (stale or implausibly future)
-    }
-    return true;
-  }
-}
+// ChallengeRegistry (the single-use anti-replay ledger) lives in its own module
+// now — re-exported here so daemon.mjs and existing importers/tests are
+// unchanged. createChallenge + DEFAULT_MAX_SKEW_MS stay above for verifyConnect.
+export { ChallengeRegistry } from './challenge_registry.mjs';
 
 // Canonicalise scopes to a single deterministic token so two clients that
 // list the same scopes in a different order still produce an identical
@@ -266,7 +182,7 @@ export function buildSignPayload({
 // must stay in lock-step with buildSignPayload's field order. Returns null
 // for a malformed / wrong-version payload so the caller can reject cleanly
 // rather than throwing.
-function parsePayload(payload) {
+export function parsePayload(payload) {
   if (typeof payload !== 'string') return null;
   const parts = payload.split(FIELD_SEP);
   if (parts.length !== 11) return null;
@@ -505,7 +421,7 @@ export class PairingStore {
    * @param {{ deviceId: string, platform?: string, label?: string }} args
    * @returns {{ requestId: string, status: 'pending' }}
    */
-  requestPairing({ deviceId, platform = '', label = '' } = {}) {
+  requestPairing({ deviceId, platform = '', label = '', role = '', scopes = [] } = {}) {
     if (!deviceId || typeof deviceId !== 'string') {
       throw new Error('requestPairing requires a deviceId');
     }
@@ -524,6 +440,10 @@ export class PairingStore {
       deviceId,
       platform: String(platform || ''),
       label: String(label || ''),
+      // Capability metadata from the signed payload (read-only vs approver).
+      // Persisted so approve() can stamp it on the device for authz.
+      role: String(role || ''),
+      scopes: Array.isArray(scopes) ? scopes.map(String) : [],
       status: 'pending',
       createdAt: nowIso(),
     };
@@ -544,7 +464,7 @@ export class PairingStore {
    * @param {string} requestId
    * @returns {{ deviceId: string, token: string }}
    */
-  approve(requestId) {
+  approve(requestId, { ttlMs, nowMs = Date.now() } = {}) {
     const req = this._data.requests[requestId];
     if (!req) {
       throw new Error(`unknown pairing request: ${requestId}`);
@@ -553,17 +473,25 @@ export class PairingStore {
       throw new Error(`request not pending: ${requestId} (status=${req.status})`);
     }
     const token = freshToken();
-    this._data.devices[req.deviceId] = {
+    const dev = {
       deviceId: req.deviceId,
       platform: req.platform || '',
       label: req.label || '',
+      role: req.role || '',
+      scopes: Array.isArray(req.scopes) ? req.scopes : [],
       token,
       approvedAt: nowIso(),
     };
+    // Optional TTL: stamp an absolute expiry only when a positive ttlMs is
+    // given. Omitting it keeps the legacy never-expires record.
+    if (Number.isFinite(ttlMs) && ttlMs > 0 && Number.isFinite(nowMs)) {
+      dev.expiresAt = nowMs + ttlMs;
+    }
+    this._data.devices[req.deviceId] = dev;
     req.status = 'approved';
     req.approvedAt = nowIso();
     this._persist();
-    return { deviceId: req.deviceId, token };
+    return { deviceId: req.deviceId, token, ...(dev.expiresAt ? { expiresAt: dev.expiresAt } : {}) };
   }
 
   /**
@@ -602,14 +530,20 @@ export class PairingStore {
    * @param {string} presentedToken
    * @returns {boolean}
    */
-  verifyToken(deviceId, presentedToken) {
-    const stored = this.tokenFor(deviceId);
+  verifyToken(deviceId, presentedToken, nowMs) {
+    const dev = this._data.devices[deviceId];
+    const stored = dev && typeof dev.token === 'string' && dev.token.length > 0 ? dev.token : null;
     if (typeof stored !== 'string' || stored.length === 0) return false;
     if (typeof presentedToken !== 'string' || presentedToken.length === 0) return false;
     const a = Buffer.from(stored, 'utf8');
     const b = Buffer.from(presentedToken, 'utf8');
     if (a.length !== b.length) return false; // length mismatch — cannot timingSafeEqual
-    return crypto.timingSafeEqual(a, b);
+    // Constant-time compare FIRST, expiry AFTER — so response timing can't leak
+    // "expired" vs "wrong token". TTL is only enforced when both the record has
+    // an expiresAt AND the caller injects a nowMs (legacy callers/records skip).
+    if (!crypto.timingSafeEqual(a, b)) return false;
+    if (typeof dev.expiresAt === 'number' && Number.isFinite(nowMs) && nowMs >= dev.expiresAt) return false;
+    return true;
   }
 
   /**
@@ -624,6 +558,46 @@ export class PairingStore {
     return { deviceId, revoked: existed };
   }
 
+  /**
+   * Re-issue a fresh token for an already-approved device WITHOUT a new pairing
+   * handshake. The old token stops authenticating immediately; non-secret
+   * metadata (platform/label/role/scopes) is preserved. A positive ttlMs stamps
+   * a fresh expiresAt; omitting it clears any prior expiry (never-expires).
+   * Throws when the device is unknown or was never approved.
+   * @returns {{ deviceId: string, token: string, expiresAt?: number }}
+   */
+  rotate(deviceId, { ttlMs, nowMs = Date.now() } = {}) {
+    const dev = this._data.devices[deviceId];
+    if (!dev || typeof dev.token !== 'string' || dev.token.length === 0) {
+      throw new Error(`cannot rotate: no approved device ${deviceId}`);
+    }
+    dev.token = freshToken();
+    dev.rotatedAt = nowIso();
+    if (Number.isFinite(ttlMs) && ttlMs > 0 && Number.isFinite(nowMs)) dev.expiresAt = nowMs + ttlMs;
+    else delete dev.expiresAt;
+    this._persist();
+    return { deviceId, token: dev.token, ...(dev.expiresAt ? { expiresAt: dev.expiresAt } : {}) };
+  }
+
+  /**
+   * Non-secret view of a device record (NEVER includes the token) — for the
+   * gateway authz layer (role/scopes) and the `nodes` CLI. null when unknown.
+   * @returns {{ deviceId, platform, label, role, scopes, expiresAt, approvedAt } | null}
+   */
+  deviceInfo(deviceId) {
+    const dev = this._data.devices[deviceId];
+    if (!dev) return null;
+    return {
+      deviceId: dev.deviceId,
+      platform: dev.platform || '',
+      label: dev.label || '',
+      role: dev.role || '',
+      scopes: Array.isArray(dev.scopes) ? dev.scopes : [],
+      expiresAt: dev.expiresAt,
+      approvedAt: dev.approvedAt,
+    };
+  }
+
   /**
    * All pending pairing requests (awaiting an explicit approve()), newest
    * first. Tokens are never part of a request record, so this is safe to

package/gateway/http_gateway.mjs

@@ -33,6 +33,7 @@ import {
   PairingStore,
   deviceIdFromPublicKey,
   verifyConnect,
+  parsePayload,
 } from './device_auth.mjs';
 import { redactSecrets } from '../mas/redact.mjs';
 
@@ -154,8 +155,12 @@ export function createGateway({ configDir, challengeRegistry, nowFn = Date.now,
     const token = bearerToken(req);
     const deviceId = String(req.headers?.['x-device-id'] || '').trim();
     if (!token || !deviceId) return null;
-    if (!store().verifyToken(deviceId, token)) return null;
-    return { deviceId };
+    const st = store();
+    // Inject nowFn so an EXPIRED token (device TTL) is rejected across every
+    // authenticated route, not just freshly after issue.
+    if (!st.verifyToken(deviceId, token, nowFn())) return null;
+    const info = st.deviceInfo(deviceId);
+    return { deviceId, role: info?.role || '', scopes: Array.isArray(info?.scopes) ? info.scopes : [] };
   }
 
   async function handle(req, res, { readBody }) {
@@ -214,8 +219,22 @@ export function createGateway({ configDir, challengeRegistry, nowFn = Date.now,
       if (existing) {
         receipt = { requestId: existing.requestId };
       } else {
+        // role + scopes come from the SIGNATURE-VERIFIED payload (tamper-
+        // evident), not the unsigned body fields, so a client can't forge its
+        // own capabilities. parsePayload is safe here — verifyConnect passed.
+        let role = '';
+        let scopes = [];
         try {
-          receipt = st.requestPairing({ deviceId, platform, label });
+          const parsed = parsePayload(payload);
+          if (parsed) {
+            role = String(parsed.role || '');
+            scopes = typeof parsed.scopes === 'string' && parsed.scopes
+              ? parsed.scopes.split(',').filter(Boolean)
+              : (Array.isArray(parsed.scopes) ? parsed.scopes : []);
+          }
+        } catch { /* fall back to no capability — default device */ }
+        try {
+          receipt = st.requestPairing({ deviceId, platform, label, role, scopes });
         } catch (err) {
           // Pending-requests ceiling hit — shed load rather than 500.
           if (err && err.code === 'PAIRING_CAP') {
@@ -238,6 +257,13 @@ export function createGateway({ configDir, challengeRegistry, nowFn = Date.now,
     if (m === 'POST' && p === '/gateway/exec/resolve') {
       const ident = authDevice(req);
       if (!ident) return writeJson(res, 401, { ok: false, reason: 'invalid device token' });
+      // Capability gate: a read-only device may observe (whoami/events/pending)
+      // but MUST NOT resolve an exec approval (the one mutating gateway action).
+      // Backward-compatible: only an EXPLICITLY read-only role is denied; legacy
+      // devices (role '') and approvers keep the prior behaviour.
+      if (ident.role === 'read-only') {
+        return writeJson(res, 403, { ok: false, reason: 'insufficient scope: a read-only device cannot resolve exec approvals' });
+      }
       const body = await readJsonBody(req, readBody);
       if (body && body.__tooLarge) return writeJson(res, 413, { ok: false, reason: 'request body too large' });
       if (!body || !body.id) return writeJson(res, 400, { ok: false, reason: 'id and decision are required' });