@vellumai/assistant 0.3.18 → 0.3.19

package/ARCHITECTURE.md

@@ -22,6 +22,10 @@ This document owns assistant-runtime architecture details. The repo-level archit
 - Voice calls mirror the same prompt contract: `CallController` receives guardian context on setup and refreshes it immediately after successful voice challenge verification, so the first post-verification turn is grounded as `actor_role: guardian`.
 - Voice-specific behavior (DTMF/speech verification flow, relay state machine) remains voice-local; only actor-role resolution is shared.
 
+### Channel-Agnostic Scoped Approval Grants
+
+Scoped approval grants allow a guardian's approval decision on one channel (e.g., Telegram) to authorize a tool execution on a different channel (e.g., voice). Two scope modes exist: `request_id` (bound to a specific pending request) and `tool_signature` (bound to `toolName` + canonical `inputDigest`). Grants are one-time-use, exact-match, fail-closed, and TTL-bound. Full architecture details (lifecycle flow, security invariants, key files) live in [`docs/architecture/security.md`](docs/architecture/security.md#channel-agnostic-scoped-approval-grants).
+
 ### Outbound Guardian Verification (HTTP Endpoints)
 
 Guardian verification can be initiated through the runtime HTTP API as an alternative to the legacy IPC-only flow. This enables chat-first verification where the assistant guides the user through guardian setup via normal conversation.

package/docs/architecture/security.md

@@ -315,3 +315,83 @@ The `allowOneTimeSend` config gate (default: `false`) enables a secondary "Send
 
 ---
 
+## Channel-Agnostic Scoped Approval Grants
+
+Scoped approval grants are a channel-agnostic primitive that allows a guardian's approval decision on one channel (e.g., Telegram) to authorize a tool execution on a different channel (e.g., voice). Each grant authorizes exactly one tool execution and is consumed atomically.
+
+### Scope Modes
+
+Two scope modes exist:
+
+| Mode | Key fields | Use case |
+|------|-----------|----------|
+| `request_id` | `requestId` | Grant is bound to a specific pending confirmation request. Consumed by matching the request ID. |
+| `tool_signature` | `toolName` + `inputDigest` | Grant is bound to a specific tool invocation identified by tool name and a canonical SHA-256 digest of the input. Consumed by matching both fields plus optional context constraints. |
+
+### Lifecycle Flow
+
+```mermaid
+sequenceDiagram
+    participant Caller as Non-Guardian Caller (Voice)
+    participant Session as Session / Agent Loop
+    participant Bridge as Voice Session Bridge
+    participant Guardian as Guardian (Telegram)
+    participant Interception as Approval Interception
+    participant GrantStore as Scoped Grant Store (SQLite)
+
+    Caller->>Session: Tool invocation triggers confirmation_request
+    Session->>Bridge: confirmation_request event
+    Note over Bridge: Non-guardian voice call cannot prompt interactively
+
+    Bridge->>Session: ASK_GUARDIAN_APPROVAL marker in agent response
+    Session->>Guardian: "Approve [tool] with [args]?" (Telegram)
+
+    Guardian->>Interception: "yes" / approve_once callback
+    Interception->>Session: handleChannelDecision(approve_once)
+    Interception->>GrantStore: createScopedApprovalGrant(tool_signature)
+    Note over GrantStore: Grant minted with 5-min TTL
+
+    Note over Bridge: On next confirmation_request for same tool+input...
+    Bridge->>GrantStore: consumeScopedApprovalGrantByToolSignature()
+    GrantStore-->>Bridge: { ok: true, grant }
+    Bridge->>Session: handleConfirmationResponse(allow)
+    Note over GrantStore: Grant status: active -> consumed (CAS)
+```
+
+### Security Invariants
+
+1. **One-time use** -- Each grant can be consumed at most once. The consume operation uses compare-and-swap (CAS) on the `status` column (`active` -> `consumed`) so concurrent consumers race safely. At most one wins.
+
+2. **Exact-match** -- All non-null scope fields on the grant must match the consumption context exactly. The `inputDigest` is a SHA-256 of the canonical JSON serialization of `{ toolName, input }`, ensuring key-order-independent matching.
+
+3. **Fail-closed** -- When no matching active grant exists, consumption returns `{ ok: false }` and the voice bridge auto-denies. There is no fallback to "allow without a grant."
+
+4. **TTL-bound** -- Grants expire after a configurable TTL (default: 5 minutes). An expiry sweep transitions active past-TTL grants to `expired` status. Expired grants cannot be consumed.
+
+5. **Context-constrained** -- Optional scope fields (`executionChannel`, `conversationId`, `callSessionId`, `requesterExternalUserId`) narrow the grant's applicability. When set on the grant, they must match the consumer's context. When null on the grant, they act as wildcards.
+
+6. **Identity-bound** -- The guardian identity is verified at the approval interception level before a grant is minted. A sender whose `externalUserId` does not match the expected guardian cannot mint a grant.
+
+7. **Persistent storage** -- Grants are stored in the SQLite `scoped_approval_grants` table, which survives daemon restarts. This ensures fail-closed behavior across restarts: consumed grants remain consumed, and no implicit "reset to allowed" occurs.
+
+### Key Source Files
+
+| File | Role |
+|------|------|
+| `assistant/src/memory/scoped-approval-grants.ts` | CRUD, atomic CAS consume, expiry sweep, context-based revocation |
+| `assistant/src/memory/migrations/033-scoped-approval-grants.ts` | SQLite schema migration for the `scoped_approval_grants` table |
+| `assistant/src/security/tool-approval-digest.ts` | Canonical JSON serialization + SHA-256 digest for tool signatures |
+| `assistant/src/runtime/routes/guardian-approval-interception.ts` | Grant minting on guardian approve_once decisions (`tryMintToolApprovalGrant`) |
+| `assistant/src/calls/voice-session-bridge.ts` | Voice consumer: checks and consumes grants before auto-denying |
+
+### Test Coverage
+
+| Test file | Scenarios covered |
+|-----------|-------------------|
+| `assistant/src/__tests__/scoped-approval-grants.test.ts` | Store CRUD, request_id consume, tool_signature consume, expiry, revocation, digest stability |
+| `assistant/src/__tests__/voice-scoped-grant-consumer.test.ts` | Voice bridge integration: grant-allowed, no-grant-denied, tool-mismatch, guardian-bypass, one-time-use, revocation on call end |
+| `assistant/src/__tests__/guardian-grant-minting.test.ts` | Grant minting: callback/engine/legacy paths, informational-skip, reject-skip, identity-mismatch, stale-skip, TTL verification |
+| `assistant/src/__tests__/scoped-grant-security-matrix.test.ts` | Security matrix: requester identity mismatch, concurrent CAS, persistence across restart, fail-closed default, cross-scope invariants |
+
+---
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.3.18",
+  "version": "0.3.19",
   "type": "module",
   "bin": {
     "vellum": "./src/index.ts"

package/src/__tests__/__snapshots__/ipc-snapshot.test.ts.snap

@@ -1748,6 +1748,10 @@ exports[`IPC message snapshots ServerMessage types skills_list_response serializ
       "emoji": "🔧",
       "id": "my-skill",
       "name": "My Skill",
+      "provenance": {
+        "kind": "first-party",
+        "provider": "Vellum",
+      },
       "source": "bundled",
       "state": "enabled",
       "updateAvailable": false,

package/src/__tests__/call-controller.test.ts

@@ -1195,4 +1195,174 @@ describe('call-controller', () => {
 
     controller.destroy();
   });
+
+  // ── Structured tool-approval ASK_GUARDIAN_APPROVAL ──────────────────
+
+  test('ASK_GUARDIAN_APPROVAL: persists toolName and inputDigest on guardian action request', async () => {
+    const approvalPayload = JSON.stringify({
+      question: 'Allow send_email to bob@example.com?',
+      toolName: 'send_email',
+      input: { to: 'bob@example.com', subject: 'Hello' },
+    });
+    mockStartVoiceTurn.mockImplementation(createMockVoiceTurn(
+      [`Let me check with your guardian. [ASK_GUARDIAN_APPROVAL: ${approvalPayload}]`],
+    ));
+    const { session, relay, controller } = setupController('Send an email');
+
+    await controller.handleCallerUtterance('Send an email to Bob');
+
+    // Give the async dispatchGuardianQuestion a tick to create the request
+    await new Promise((r) => setTimeout(r, 50));
+
+    // Verify controller entered waiting_on_user
+    expect(controller.getState()).toBe('waiting_on_user');
+
+    // Verify a pending question was created with the correct text
+    const question = getPendingQuestion(session.id);
+    expect(question).not.toBeNull();
+    expect(question!.questionText).toBe('Allow send_email to bob@example.com?');
+
+    // Verify the guardian action request has tool metadata
+    const pendingRequest = getPendingRequestByCallSessionId(session.id);
+    expect(pendingRequest).not.toBeNull();
+    expect(pendingRequest!.toolName).toBe('send_email');
+    expect(pendingRequest!.inputDigest).not.toBeNull();
+    expect(pendingRequest!.inputDigest!.length).toBe(64); // SHA-256 hex = 64 chars
+
+    // The ASK_GUARDIAN_APPROVAL marker should NOT appear in the relay tokens
+    const allText = relay.sentTokens.map((t) => t.token).join('');
+    expect(allText).not.toContain('[ASK_GUARDIAN_APPROVAL:');
+    expect(allText).not.toContain('send_email');
+
+    controller.destroy();
+  });
+
+  test('ASK_GUARDIAN_APPROVAL: computes deterministic digest for same tool+input', async () => {
+    const approvalPayload = JSON.stringify({
+      question: 'Allow send_email?',
+      toolName: 'send_email',
+      input: { subject: 'Hello', to: 'bob@example.com' },
+    });
+    mockStartVoiceTurn.mockImplementation(createMockVoiceTurn(
+      [`Checking. [ASK_GUARDIAN_APPROVAL: ${approvalPayload}]`],
+    ));
+    const { session, controller } = setupController('Send email');
+
+    await controller.handleCallerUtterance('Send it');
+    await new Promise((r) => setTimeout(r, 50));
+
+    const request1 = getPendingRequestByCallSessionId(session.id);
+    expect(request1).not.toBeNull();
+
+    // Compute expected digest independently using the same utility
+    const { computeToolApprovalDigest } = await import('../security/tool-approval-digest.js');
+    const expectedDigest = computeToolApprovalDigest('send_email', { subject: 'Hello', to: 'bob@example.com' });
+    expect(request1!.inputDigest).toBe(expectedDigest);
+
+    controller.destroy();
+  });
+
+  test('informational ASK_GUARDIAN: does NOT persist tool metadata (null toolName/inputDigest)', async () => {
+    mockStartVoiceTurn.mockImplementation(createMockVoiceTurn(
+      ['Let me check. [ASK_GUARDIAN: What date works best?]'],
+    ));
+    const { session, controller } = setupController('Book appointment');
+
+    await controller.handleCallerUtterance('I need to schedule something');
+    await new Promise((r) => setTimeout(r, 50));
+
+    // Verify the guardian action request has NO tool metadata
+    const pendingRequest = getPendingRequestByCallSessionId(session.id);
+    expect(pendingRequest).not.toBeNull();
+    expect(pendingRequest!.toolName).toBeNull();
+    expect(pendingRequest!.inputDigest).toBeNull();
+    expect(pendingRequest!.questionText).toBe('What date works best?');
+
+    controller.destroy();
+  });
+
+  test('ASK_GUARDIAN_APPROVAL: strips marker from TTS output', async () => {
+    const approvalPayload = JSON.stringify({
+      question: 'Allow calendar_create?',
+      toolName: 'calendar_create',
+      input: { date: '2026-03-01', title: 'Meeting' },
+    });
+    mockStartVoiceTurn.mockImplementation(createMockVoiceTurn([
+      'Let me get approval for that. ',
+      `[ASK_GUARDIAN_APPROVAL: ${approvalPayload}]`,
+      ' Thank you.',
+    ]));
+    const { relay, controller } = setupController('Create event');
+
+    await controller.handleCallerUtterance('Create a meeting');
+
+    const allText = relay.sentTokens.map((t) => t.token).join('');
+    expect(allText).toContain('Let me get approval');
+    expect(allText).not.toContain('[ASK_GUARDIAN_APPROVAL:');
+    expect(allText).not.toContain('calendar_create');
+    expect(allText).not.toContain('inputDigest');
+
+    controller.destroy();
+  });
+
+  test('ASK_GUARDIAN_APPROVAL: handles JSON payloads containing }] in string values', async () => {
+    // The `}]` sequence inside a JSON string value previously caused the
+    // non-greedy regex to terminate early, truncating the JSON and leaking
+    // partial data into TTS output.
+    const approvalPayload = JSON.stringify({
+      question: 'Allow send_message?',
+      toolName: 'send_message',
+      input: { msg: 'test}]more', nested: { key: 'value with }] braces' } },
+    });
+    mockStartVoiceTurn.mockImplementation(createMockVoiceTurn(
+      [`Let me check. [ASK_GUARDIAN_APPROVAL: ${approvalPayload}]`],
+    ));
+    const { session, relay, controller } = setupController('Send a message');
+
+    await controller.handleCallerUtterance('Send it');
+    await new Promise((r) => setTimeout(r, 50));
+
+    // Verify controller entered waiting_on_user with the correct question
+    expect(controller.getState()).toBe('waiting_on_user');
+    const question = getPendingQuestion(session.id);
+    expect(question).not.toBeNull();
+    expect(question!.questionText).toBe('Allow send_message?');
+
+    // Verify tool metadata was parsed correctly
+    const pendingRequest = getPendingRequestByCallSessionId(session.id);
+    expect(pendingRequest).not.toBeNull();
+    expect(pendingRequest!.toolName).toBe('send_message');
+    expect(pendingRequest!.inputDigest).not.toBeNull();
+
+    // No partial JSON or marker text should leak into TTS output
+    const allText = relay.sentTokens.map((t) => t.token).join('');
+    expect(allText).not.toContain('[ASK_GUARDIAN_APPROVAL:');
+    expect(allText).not.toContain('send_message');
+    expect(allText).not.toContain('}]');
+    expect(allText).not.toContain('test}]more');
+    expect(allText).toContain('Let me check.');
+
+    controller.destroy();
+  });
+
+  test('ASK_GUARDIAN_APPROVAL with malformed JSON: falls through to informational ASK_GUARDIAN', async () => {
+    // Malformed JSON in the approval marker — should be ignored, and if there's
+    // also an informational ASK_GUARDIAN marker, it should be used instead
+    mockStartVoiceTurn.mockImplementation(createMockVoiceTurn(
+      ['Checking. [ASK_GUARDIAN_APPROVAL: {invalid json}] [ASK_GUARDIAN: Fallback question?]'],
+    ));
+    const { session, controller } = setupController('Test fallback');
+
+    await controller.handleCallerUtterance('Do something');
+    await new Promise((r) => setTimeout(r, 50));
+
+    const pendingRequest = getPendingRequestByCallSessionId(session.id);
+    expect(pendingRequest).not.toBeNull();
+    expect(pendingRequest!.questionText).toBe('Fallback question?');
+    // Tool metadata should be null since the approval marker was malformed
+    expect(pendingRequest!.toolName).toBeNull();
+    expect(pendingRequest!.inputDigest).toBeNull();
+
+    controller.destroy();
+  });
 });

package/src/__tests__/checker.test.ts

@@ -354,6 +354,66 @@ describe('Permission Checker', () => {
       test('env injection is high risk', async () => {
         expect(await classifyRisk('bash', { command: 'LD_PRELOAD=evil.so cmd' })).toBe(RiskLevel.High);
       });
+
+      test('wrapped rm via env is high risk', async () => {
+        expect(await classifyRisk('bash', { command: 'env rm -rf /tmp/x' })).toBe(RiskLevel.High);
+      });
+
+      test('wrapped rm via time is high risk', async () => {
+        expect(await classifyRisk('bash', { command: 'time rm file.txt' })).toBe(RiskLevel.High);
+      });
+
+      test('wrapped kill via env is high risk', async () => {
+        expect(await classifyRisk('bash', { command: 'env kill -9 1234' })).toBe(RiskLevel.High);
+      });
+
+      test('wrapped sudo via env is high risk', async () => {
+        expect(await classifyRisk('bash', { command: 'env sudo apt-get install foo' })).toBe(RiskLevel.High);
+      });
+
+      test('wrapped reboot via nice is high risk', async () => {
+        expect(await classifyRisk('bash', { command: 'nice reboot' })).toBe(RiskLevel.High);
+      });
+
+      test('wrapped pkill via nohup is high risk', async () => {
+        expect(await classifyRisk('bash', { command: 'nohup pkill node' })).toBe(RiskLevel.High);
+      });
+
+      test('command -v is low risk (read-only lookup)', async () => {
+        expect(await classifyRisk('bash', { command: 'command -v rm' })).toBe(RiskLevel.Low);
+      });
+
+      test('command -V is low risk (read-only lookup)', async () => {
+        expect(await classifyRisk('bash', { command: 'command -V sudo' })).toBe(RiskLevel.Low);
+      });
+
+      test('command without -v/-V flag escalates wrapped program', async () => {
+        expect(await classifyRisk('bash', { command: 'command rm file.txt' })).toBe(RiskLevel.High);
+      });
+
+      test('rm BOOTSTRAP.md (bare safe file) is medium risk', async () => {
+        expect(await classifyRisk('bash', { command: 'rm BOOTSTRAP.md' })).toBe(RiskLevel.Medium);
+      });
+
+      test('rm UPDATES.md (bare safe file) is medium risk', async () => {
+        expect(await classifyRisk('bash', { command: 'rm UPDATES.md' })).toBe(RiskLevel.Medium);
+      });
+
+      test('rm -rf BOOTSTRAP.md is still high risk (flags present)', async () => {
+        expect(await classifyRisk('bash', { command: 'rm -rf BOOTSTRAP.md' })).toBe(RiskLevel.High);
+      });
+
+      test('rm /path/to/BOOTSTRAP.md is still high risk (path separator)', async () => {
+        expect(await classifyRisk('bash', { command: 'rm /path/to/BOOTSTRAP.md' })).toBe(RiskLevel.High);
+      });
+
+      test('rm BOOTSTRAP.md other.txt is still high risk (multiple targets)', async () => {
+        expect(await classifyRisk('bash', { command: 'rm BOOTSTRAP.md other.txt' })).toBe(RiskLevel.High);
+      });
+
+      test('rm somefile.md is still high risk (not a known safe file)', async () => {
+        expect(await classifyRisk('bash', { command: 'rm somefile.md' })).toBe(RiskLevel.High);
+      });
     });
 
     // unknown tool