tascan-mcp 3.16.1 → 3.16.2

package/README.md

@@ -288,6 +288,9 @@ API keys are scoped to your organization and support rate limiting (60 requests/
 
 ## Changelog
 
+### v3.16.2 — 2026-09-28
+- 98 tools.  Rolls up 3.16.0 to 3.16.2: `tascan_get_usage` (GET /usage, per-key daily actions and rate-limit headers, migration 220); the device control plane read/revoke tools (`tascan_list_devices`, `tascan_get_device`, `tascan_revoke_device`; register and rotate stay admin-app only by design); `tascan_delegate_to_agent` (child keys with a TTL of 60 s to 24 h clamped to the parent, non-delegable flags refused, the plaintext returned once) and the per-key action budgets that fail closed (migration 221).  Hosted MCP at https://app.tascan.io/mcp already serves this version; this release brings the stdio package up to it.
+
 ### v3.15.0 — 2026-09-19
 
 - `tascan_create_cycle` gains an optional `reviews[]` array — a multi-lens review panel (design item 14a): 1–8 lenses, each `{lens, brief, provider: openai|anthropic|gemini, model?, blocking? (default true), max_tool_calls? (openai only)}`, forwarded to `POST /coord/cycles`; at least one lens must be blocking.  Omit it for the single OpenAI review.

package/index.js

@@ -53,7 +53,7 @@ async function api(method, path, body, idemKey) {
 api.key = API_KEY;   // raw-fetch tools read the key from here (S99: those functions now require auth)
 
 const server = new Server(
-  { name: 'tascan', version: '3.16.1' },
+  { name: 'tascan', version: '3.16.2' },
   { capabilities: { tools: {} } }
 );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tascan-mcp",
-  "version": "3.16.1",
+  "version": "3.16.2",
   "mcpName": "io.github.snowbikemike/tascan-mcp",
   "description": "TaScan MCP Server — Closed-loop autonomous operations protocol. 70 tools for projects, tasks, workers, QR codes, NFC tags, worker marketplace with consented SMS invites, geofenced zones with rules (work site / hazard + AI-verified PPE checkpoints / containment / restricted, breach alerts, zone compliance audit), AI condition assessment, worker passports, verification-gated gig payments, client invoicing from verified work (overtime / day rate / per diem / expenses), shareable report links (completion, client service report, project, evidence pack), signed Action Receipts (Ed25519 JWS), cross-entity search, duplicate-worker detection, worker identity merge, AI issue analysis, and autonomous remediation dispatch. 15 patents filed (470+ claims). Task. Scan. Done.",
   "type": "module",

package/scopes.cjs

@@ -34,7 +34,13 @@ const DISPATCH_CODE = 'agent:dispatch:code';
 // requires full, and unreachable through OAuth (mcp-oauth.js's consent flow passes no device flag, so clamp()
 // below never grants it to a connector token even though clamp is capable of granting it to an owner).
 const DEVICE_ADMIN = 'device:admin';
-const SCOPE_VALUES = ['read', 'write', 'full', DISPATCH, DISPATCH_CODE, DEVICE_ADMIN];
+// B2 (migration 221): delegate — a FOURTH additive permission, never implied by a tier — owner-only, requires
+// full (like device:admin), and unreachable through OAuth (mcp-oauth.js's consent flow passes no delegate flag,
+// so clamp() below never grants it to a connector token even though clamp is capable of granting it to an owner).
+// A key holding it may mint time-limited, narrower child keys (coord_delegate_key) — read/write only, never a
+// wider or lateral grant (I-6).
+const DELEGATE = 'delegate';
+const SCOPE_VALUES = ['read', 'write', 'full', DISPATCH, DISPATCH_CODE, DEVICE_ADMIN, DELEGATE];
 const ALL_SCOPES = SCOPE_VALUES.slice();
 
 // Seed agent inbox (tools.cjs AGENT_REGISTRY, agent-execute, agent.js, migrations 046/137/151).
@@ -74,23 +80,25 @@ function dispatchKind(titles) {
 //     (P0 / migration 216): a legacy row minted before this permission existed must not silently gain it.
 //   null / undefined / [] → read, no dispatch, no device_admin (FAIL CLOSED)
 function normalize(v) {
-  if (v == null) return { tier: 'read', dispatch: false, code: false, device_admin: false, legacy: false };
+  if (v == null) return { tier: 'read', dispatch: false, code: false, device_admin: false, delegate: false, legacy: false };
   const a = Array.isArray(v) ? v.map(String) : String(v).split(/[\s+,]+/).filter(Boolean);
-  if (a.includes('*')) return { tier: 'full', dispatch: true, code: true, device_admin: true, legacy: true };
-  if (a.includes('all')) return { tier: 'full', dispatch: true, code: true, device_admin: false, legacy: true };
+  if (a.includes('*')) return { tier: 'full', dispatch: true, code: true, device_admin: true, delegate: true, legacy: true };
+  if (a.includes('all')) return { tier: 'full', dispatch: true, code: true, device_admin: false, delegate: false, legacy: true };
   let tier = 'read';
   for (const t of TIERS) if (a.includes(t) && RANK[t] > RANK[tier]) tier = t;
   const dispatch = a.includes(DISPATCH);
   // code without dispatch is not a state the consent page or key UI can produce; treat as dispatch too
   const code = a.includes(DISPATCH_CODE);
   const deviceAdmin = a.includes(DEVICE_ADMIN);
-  return { tier, dispatch: dispatch || code, code, device_admin: deviceAdmin, legacy: false };
+  const delegate = a.includes(DELEGATE);
+  return { tier, dispatch: dispatch || code, code, device_admin: deviceAdmin, delegate, legacy: false };
 }
 function toArray(n) {
   const out = TIERS.slice(0, RANK[n.tier] || 1);
   if (n.dispatch || n.code) out.push(DISPATCH);
   if (n.code) out.push(DISPATCH_CODE);
   if (n.device_admin) out.push(DEVICE_ADMIN);
+  if (n.delegate) out.push(DELEGATE);
   return out;
 }
 function toScopeString(n) { return toArray(n).join(' '); }
@@ -133,7 +141,7 @@ function echoScope(str) {
 // P0 (migration 216): device_admin is accepted here for completeness and unit-tested (a non-owner clamp drops
 // it), but the ONLY real caller — mcp-oauth.js's OAuth consent flow — never passes a device flag in `pick` at
 // all, so a connector token can never hold device:admin regardless of the granting admin's role.
-function clamp({ tier, dispatch, code, device_admin }, role) {
+function clamp({ tier, dispatch, code, device_admin, delegate }, role) {
   const t = TIERS.includes(tier) ? tier : 'read';
   const owner = role === 'owner';
   const clamped = [];
@@ -144,7 +152,11 @@ function clamp({ tier, dispatch, code, device_admin }, role) {
   else if (!!code && !gc) clamped.push(DISPATCH_CODE);   // ticked code without dispatch
   let gda = !!device_admin && owner;
   if (!!device_admin && !gda) clamped.push(DEVICE_ADMIN);
-  return { granted: { tier: gt, dispatch: gd, code: gc, device_admin: gda, legacy: false }, clamped };
+  // B2 (migration 221): delegate is owner-only AND requires the final (already-clamped) tier to be full — the
+  // same "only an owner-held, full-tier key may ever mint a delegation" rule 221's own CHECK enforces in storage.
+  let gdel = !!delegate && owner && gt === 'full';
+  if (!!delegate && !gdel) clamped.push(DELEGATE);
+  return { granted: { tier: gt, dispatch: gd, code: gc, device_admin: gda, delegate: gdel, legacy: false }, clamped };
 }
 
 // POST /api/v1/keys body.scopes → canonical array or null (rejects 'all', '*', junk, empty,
@@ -154,6 +166,7 @@ function validateStored(arr) {
   if (!arr.every(s => typeof s === 'string' && SCOPE_VALUES.includes(s))) return null;
   if (arr.includes(DISPATCH_CODE) && !arr.includes(DISPATCH)) return null;
   if (arr.includes(DEVICE_ADMIN) && !arr.includes('full')) return null;
+  if (arr.includes(DELEGATE) && !arr.includes('full')) return null;
   return toArray(normalize(arr));
 }
 
@@ -171,6 +184,7 @@ function check(granted, need) {
   if (need.human_only) return { code: 'human_session_required', required: 'human_session_required', granted_scope: toScopeString(g) };
   if ((RANK[g.tier] || 0) < (RANK[need.tier] || 99)) return deny(need.tier);
   if (need.device_admin && !g.device_admin) return deny(DEVICE_ADMIN);
+  if (need.delegate && !g.delegate) return deny(DELEGATE);
   if (need.dispatch === 'code' && !g.code) return deny(DISPATCH_CODE);
   if (need.dispatch === true && !g.dispatch) return deny(DISPATCH);
   return null;
@@ -250,7 +264,14 @@ const TOOL_SCOPES = {
   tascan_list_devices: R, tascan_get_device: R,
   tascan_revoke_device: { tier: 'full', device_admin: true },
   // B1 (migration 220): GET /usage wrapped as a tool — read tier, same as every other read-only usage/analytics tool.
-  tascan_get_usage: R
+  tascan_get_usage: R,
+  // B2 (migration 221): per-key budgets + delegated child keys. tascan_get_budget is the caller's own row (read
+  // tier, same idiom as tascan_get_usage). tascan_delegate_to_agent mints (NOT destructiveHint — see tools.cjs);
+  // tascan_revoke_delegation is destructive+idempotent. Both need write + delegate (owner-only to grant, I-6).
+  tascan_get_budget: R,
+  tascan_delegate_to_agent: { tier: 'write', delegate: true },
+  tascan_list_delegations: R,
+  tascan_revoke_delegation: { tier: 'write', delegate: true }
 };
 // Tools classified here that do not yet exist in tools.cjs (other workstreams' patches).  Empty since
 // tascan_get_receipt landed in tools.cjs (S100 phase 2b); harnesses assert TOOL_SCOPES ⊇ tools.cjs.
@@ -352,6 +373,16 @@ const ROUTE_SCOPES = {
   // V9b (204): GET/PUT /evidence/policy/:task_id — read a task's evidence-policy progress / author + pin one.
   evidence_policy:     { GET: R, PUT: W },                              // GET /builds/:build_ref/file?path=&offset=&limit=  ≤ 12,000 chars per call
   keys: 'admin', key: 'admin',
+  // B2 (migration 221): key_budget (PUT/GET /keys/:id/budget) joins the admin-JWT-only idiom (api-v1.js's
+  // DECISION_ASSERTION_ADMIN_HANDLERS-style set) — a tsk_/service bearer is refused 403 human_session_required
+  // before this table is ever consulted (I-3: no key, ever, sets or reads ANOTHER key's budget); the whole entry
+  // is the 'admin' marker, same as keys/key above, since the handler self-gates (owner-only for PUT, any admin
+  // role for GET). budget (GET /budget, no :id) is the CALLING key's own row — an ordinary read-tier key route.
+  // delegations/delegation need write + delegate (owner-only to grant, I-6).
+  key_budget: 'admin',
+  budget:      { GET: R },
+  delegations: { POST: { tier: 'write', delegate: true }, GET: R },
+  delegation:  { DELETE: { tier: 'write', delegate: true } },
   // H1 (migration 215): human decision binding — admin-JWT-only, same gate-skip idiom as keys/key (api-v1.js's
   // DECISION_ASSERTION_ADMIN_HANDLERS uses authenticateAdminSession and refuses a tsk_/service key 403 human_session_required).
   decision_assertion_options: 'admin', decision_assertions: 'admin', decision_assertion: 'admin',
@@ -387,6 +418,7 @@ const SCOPE_LABEL = {
   [DISPATCH]: 'the "agent:dispatch" permission ("Let this app hand tasks to my AI agents")',
   [DISPATCH_CODE]: 'the "agent:dispatch:code" permission ("...including code and shell tasks on my computer")',
   [DEVICE_ADMIN]: 'the "device:admin" permission (register/rotate/revoke devices) — owner-only, requires full, and not reachable through OAuth',
+  [DELEGATE]: 'the "delegate" permission (mint time-limited child API keys) — owner-only, requires full, and not reachable through OAuth',
   unclassified: 'a classification (this tool is not in the scope map)'
 };
 function reconnectHint(required) {
@@ -415,7 +447,7 @@ function restDenialHeaders(d) {
 }
 
 module.exports = {
-  SCOPE_VALUES, ALL_SCOPES, TIERS, RANK, DISPATCH, DISPATCH_CODE, DEVICE_ADMIN, AGENT_INBOX_IDS,
+  SCOPE_VALUES, ALL_SCOPES, TIERS, RANK, DISPATCH, DISPATCH_CODE, DEVICE_ADMIN, DELEGATE, AGENT_INBOX_IDS,
   TASK_TYPES, LOCAL_TASK_TYPES, CLOUD_TASK_TYPES, REVIEWER_TASK_TYPES, LOCAL_ONLY_TASK_TYPES, CODE_TASK_TYPES, taskType, dispatchScopeFor, dispatchKind,
   normalize, toArray, toScopeString, parseRequested, echoScope, SCOPE_PARAM_MAX, clamp, validateStored, check,
   TOOL_SCOPES, PENDING_TOOLS, ROUTE_SCOPES, requiredForTool, requiredForRoute,

package/tools.cjs

@@ -2750,6 +2750,79 @@ const TOOLS = [
       return lines.join('\n');
     }
   },
+  // B2 (migration 221): per-key action budgets (#10, I-3) + delegated, time-limited child keys (#11, I-6, I-10).
+  {
+    name: 'tascan_get_budget',
+    description: 'Read THIS credential\'s own per-key action budget (GET /budget): daily limits (sms, invites, payment-request cents per day and per request, dispatch, human pages) and today\'s spend against them. A NULL limit (or no budget row at all) means unlimited on that counter. A key can only ever see its OWN budget, never another key\'s (I-3, no tool or key ever reads another key\'s row). Read tier.',
+    inputSchema: { type: 'object', properties: {} },
+    annotations: { title: 'Get Budget', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async (args, api) => {
+      const result = await api('GET', '/budget');
+      const d = result.data || {};
+      const b = d.budget || {}, u = d.usage || {};
+      const rows = [
+        ['sms_per_day', 'sms_count', 'sms/day'], ['invites_per_day', 'invites_count', 'invites/day'],
+        ['payment_request_cents_per_day', 'payment_request_cents_count', 'payment request cents/day'],
+        ['payment_request_cents_max', null, 'payment request cents/request (max)'],
+        ['dispatch_per_day', 'dispatch_count', 'dispatch/day'], ['human_pages_per_day', 'human_pages_count', 'human pages/day']
+      ];
+      const lines = ["this key's budget (null = unlimited):"];
+      for (const [limitKey, usageKey, label] of rows) {
+        const limit = b[limitKey] != null ? b[limitKey] : 'unlimited';
+        const used = usageKey ? (u[usageKey] != null ? u[usageKey] : 0) : null;
+        lines.push(`  ${label}: ${used != null ? used + ' / ' : ''}${limit}`);
+      }
+      return lines.join('\n') + '\n\n' + JSON.stringify(d, null, 2);
+    }
+  },
+  {
+    name: 'tascan_delegate_to_agent',
+    description: 'Mint a time-limited, NARROWER child API key (POST /delegations, roadmap #11) — only read/write scopes may be requested; full, agent:dispatch, agent:dispatch:code, device:admin, delegate and webhooks:manage are always refused by name (I-6). TTL defaults to 1 hour (3600s), clamps to [60 seconds, 24 hours], and clamps further to THIS key\'s own expiry if it has one — a delegated key can never outlive its grantor. The child\'s tier is always a SUBSET of this key\'s own effective tier, never wider or lateral. Requires the delegate permission (owner-only to grant, requires full). The returned raw key is shown to you exactly ONCE — it is never stored server-side and cannot be retrieved again (I-10). Revoking this key (or any ancestor) cascades immediately to every key it delegated.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        scopes: { type: 'array', items: { type: 'string', enum: ['read', 'write'] }, description: 'Scopes to request for the child key — read and/or write only.' },
+        ttl_seconds: { type: 'number', description: 'How long the child key lives, in seconds (default 3600 = 1h; clamped to [60, 86400] and to this key\'s own expiry).' },
+        resource_constraints: { type: 'object', description: 'Optional free-form narrowing (e.g. project/list ids) recorded on the child key as metadata.' }
+      },
+      required: ['scopes']
+    },
+    annotations: { title: 'Delegate To Agent', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    handler: async (args, api) => {
+      if (!Array.isArray(args.scopes) || !args.scopes.length) throw new Error('scopes is required (array of "read"/"write")');
+      const result = await api('POST', '/delegations', { scopes: args.scopes, ttl_seconds: args.ttl_seconds, resource_constraints: args.resource_constraints });
+      const d = result.data || {};
+      return `Delegated key ${d.key_id} minted, scopes [${(d.scopes || []).join(', ')}], expires ${d.expires_at}.\nSAVE THIS KEY NOW — it will not be shown again:\n${d.key}`;
+    }
+  },
+  {
+    name: 'tascan_list_delegations',
+    description: 'List delegated child keys (GET /delegations): this key\'s own direct children (id, label, scopes, active/revoked, depth, expires_at) — never the raw credential. An admin session sees every delegated key in the org. Read tier.',
+    inputSchema: { type: 'object', properties: {} },
+    annotations: { title: 'List Delegations', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async (args, api) => {
+      const result = await api('GET', '/delegations');
+      const data = result.data || [];
+      const out = `${data.length} delegated key(s)\n\n${JSON.stringify(data, null, 2)}`;
+      return out.length > 12000 ? out.slice(0, 12000) + '\n…[truncated at 12000 chars]' : out;
+    }
+  },
+  {
+    name: 'tascan_revoke_delegation',
+    description: 'Revoke a delegated child key immediately (DELETE /delegations/:key_id) — self-revoke, revoke by an ancestor key, or by an admin session of the org; any other caller is refused. Revoking cascades to every key IT delegated, in turn (the database trigger, not application code). Idempotent: revoking an already-revoked key reports already_revoked, no error.',
+    inputSchema: {
+      type: 'object',
+      properties: { key_id: { type: 'string', description: 'The delegated key id to revoke (from tascan_list_delegations)' } },
+      required: ['key_id']
+    },
+    annotations: { title: 'Revoke Delegation', readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    handler: async (args, api) => {
+      if (!args.key_id) throw new Error('key_id is required');
+      const result = await api('DELETE', `/delegations/${args.key_id}`);
+      const d = result.data || {};
+      return d.already_revoked ? `Key ${args.key_id} was already revoked.` : `Key ${args.key_id} revoked.`;
+    }
+  },
   // P0 (migration 216): device control plane — split out (194 KB already close to the ~200 KB bundle cap).
   ...require('./tools-devices.cjs')
 ];