@vellumai/assistant 0.3.18 → 0.3.19

package/src/runtime/routes/guardian-approval-interception.ts

@@ -11,7 +11,9 @@ import {
   type GuardianApprovalRequest,
   updateApprovalDecision,
 } from '../../memory/channel-guardian-store.js';
+import { createScopedApprovalGrant } from '../../memory/scoped-approval-grants.js';
 import { emitNotificationSignal } from '../../notifications/emit-signal.js';
+import { computeToolApprovalDigest } from '../../security/tool-approval-digest.js';
 import { getLogger } from '../../util/logger.js';
 import { runApprovalConversationTurn } from '../approval-conversation-turn.js';
 import { composeApprovalMessageGenerative } from '../approval-message-composer.js';
@@ -23,6 +25,7 @@ import {
   getApprovalInfoByConversation,
   getChannelApprovalPrompt,
   handleChannelDecision,
+  type PendingApprovalInfo,
 } from '../channel-approvals.js';
 import { deliverChannelReply } from '../gateway-client.js';
 import type {
@@ -46,6 +49,68 @@ import {
 
 const log = getLogger('runtime-http');
 
+/** TTL for scoped approval grants minted on guardian approve_once decisions. */
+export const GRANT_TTL_MS = 5 * 60 * 1000;
+
+// ---------------------------------------------------------------------------
+// Scoped grant minting on guardian tool-approval decisions
+// ---------------------------------------------------------------------------
+
+/**
+ * Mint a `tool_signature` scoped grant when a guardian approves a tool-approval
+ * request.  Only mints when the approval info contains a tool invocation with
+ * input (so we can compute the input digest).  Informational ASK_GUARDIAN
+ * requests that lack tool input are skipped.
+ *
+ * Fails silently on error — grant minting is best-effort and must never block
+ * the approval flow.
+ */
+function tryMintToolApprovalGrant(params: {
+  approvalInfo: PendingApprovalInfo;
+  approval: GuardianApprovalRequest;
+  decisionChannel: ChannelId;
+  guardianExternalUserId: string;
+}): void {
+  const { approvalInfo, approval, decisionChannel, guardianExternalUserId } = params;
+
+  // Only mint for requests that carry a tool name — the presence of toolName
+  // distinguishes tool-approval requests from informational ones.
+  // computeToolApprovalDigest can deterministically hash {} so zero-argument
+  // tool invocations must still receive a grant.
+  if (!approvalInfo.toolName) {
+    return;
+  }
+
+  try {
+    const inputDigest = computeToolApprovalDigest(approvalInfo.toolName, approvalInfo.input);
+
+    createScopedApprovalGrant({
+      assistantId: approval.assistantId,
+      scopeMode: 'tool_signature',
+      toolName: approvalInfo.toolName,
+      inputDigest,
+      requestChannel: approval.channel,
+      decisionChannel,
+      executionChannel: null,
+      conversationId: approval.conversationId,
+      callSessionId: null,
+      guardianExternalUserId,
+      requesterExternalUserId: approval.requesterExternalUserId,
+      expiresAt: new Date(Date.now() + GRANT_TTL_MS).toISOString(),
+    });
+
+    log.info(
+      { toolName: approvalInfo.toolName, conversationId: approval.conversationId },
+      'Minted scoped approval grant for guardian tool-approval decision',
+    );
+  } catch (err) {
+    log.error(
+      { err, toolName: approvalInfo.toolName, conversationId: approval.conversationId },
+      'Failed to mint scoped approval grant (non-fatal)',
+    );
+  }
+}
+
 export interface ApprovalInterceptionParams {
   conversationId: string;
   callbackData?: string;
@@ -207,6 +272,13 @@ export async function handleApprovalInterception(
           return accessResult;
         }
 
+        // Capture pending approval info before handleChannelDecision resolves
+        // (and removes) the pending interaction. Needed for grant minting.
+        const cbApprovalInfo = getApprovalInfoByConversation(guardianApproval.conversationId);
+        const cbMatchedInfo = callbackDecision.requestId
+          ? cbApprovalInfo.find(a => a.requestId === callbackDecision!.requestId)
+          : cbApprovalInfo[0];
+
         // Apply the decision to the underlying session using the requester's
         // conversation context
         const result = handleChannelDecision(
@@ -224,6 +296,16 @@ export async function handleApprovalInterception(
             decidedByExternalUserId: senderExternalUserId,
           });
 
+          // Mint a scoped grant when a guardian approves a tool-approval request
+          if (callbackDecision.action !== 'reject' && cbMatchedInfo) {
+            tryMintToolApprovalGrant({
+              approvalInfo: cbMatchedInfo,
+              approval: guardianApproval,
+              decisionChannel: sourceChannel,
+              guardianExternalUserId: senderExternalUserId,
+            });
+          }
+
           // Notify the requester's chat about the outcome with the tool name
           const outcomeText = await composeApprovalMessageGenerative({
             scenario: 'guardian_decision_outcome',
@@ -346,6 +428,13 @@ export async function handleApprovalInterception(
           ...(engineResult.targetRequestId ? { requestId: engineResult.targetRequestId } : {}),
         };
 
+        // Capture pending approval info before handleChannelDecision resolves
+        // (and removes) the pending interaction. Needed for grant minting.
+        const engineApprovalInfo = getApprovalInfoByConversation(targetApproval.conversationId);
+        const engineMatchedInfo = engineDecision.requestId
+          ? engineApprovalInfo.find(a => a.requestId === engineDecision.requestId)
+          : engineApprovalInfo[0];
+
         const result = handleChannelDecision(
           targetApproval.conversationId,
           engineDecision,
@@ -361,6 +450,16 @@ export async function handleApprovalInterception(
             decidedByExternalUserId: senderExternalUserId,
           });
 
+          // Mint a scoped grant when a guardian approves a tool-approval request
+          if (decisionAction !== 'reject' && engineMatchedInfo) {
+            tryMintToolApprovalGrant({
+              approvalInfo: engineMatchedInfo,
+              approval: targetApproval,
+              decisionChannel: sourceChannel,
+              guardianExternalUserId: senderExternalUserId,
+            });
+          }
+
           // Notify the requester's chat about the outcome
           const outcomeText = await composeApprovalMessageGenerative({
             scenario: 'guardian_decision_outcome',
@@ -492,6 +591,13 @@ export async function handleApprovalInterception(
             return accessResult;
           }
 
+          // Capture pending approval info before handleChannelDecision resolves
+          // (and removes) the pending interaction. Needed for grant minting.
+          const legacyApprovalInfo = getApprovalInfoByConversation(targetLegacyApproval.conversationId);
+          const legacyMatchedInfo = legacyGuardianDecision.requestId
+            ? legacyApprovalInfo.find(a => a.requestId === legacyGuardianDecision.requestId)
+            : legacyApprovalInfo[0];
+
           const result = handleChannelDecision(
             targetLegacyApproval.conversationId,
             legacyGuardianDecision,
@@ -504,6 +610,16 @@ export async function handleApprovalInterception(
               decidedByExternalUserId: senderExternalUserId,
             });
 
+            // Mint a scoped grant when a guardian approves a tool-approval request
+            if (legacyGuardianDecision.action !== 'reject' && legacyMatchedInfo) {
+              tryMintToolApprovalGrant({
+                approvalInfo: legacyMatchedInfo,
+                approval: targetLegacyApproval,
+                decisionChannel: sourceChannel,
+                guardianExternalUserId: senderExternalUserId,
+              });
+            }
+
             // Notify the requester's chat about the outcome
             const outcomeText = await composeApprovalMessageGenerative({
               scenario: 'guardian_decision_outcome',

package/src/runtime/routes/inbound-message-handler.ts

@@ -78,6 +78,7 @@ import {
 } from './channel-route-shared.js';
 import { handleApprovalInterception } from './guardian-approval-interception.js';
 import { deliverGeneratedApprovalPrompt } from './guardian-approval-prompt.js';
+import { tryMintGuardianActionGrant } from '../guardian-action-grant-minter.js';
 
 const log = getLogger('runtime-http');
 
@@ -254,23 +255,13 @@ export async function handleChannelInbound(
 
       if (denyNonMember) {
         log.info({ sourceChannel, externalUserId: body.senderExternalUserId }, 'Ingress ACL: no member record, denying');
-        if (body.replyCallbackUrl) {
-          try {
-            await deliverChannelReply(body.replyCallbackUrl, {
-              chatId: externalChatId,
-              text: "Sorry, you haven't been approved to message this assistant. You can ask its Guardian for an invite.",
-              assistantId,
-            }, bearerToken);
-          } catch (err) {
-            log.error({ err, externalChatId }, 'Failed to deliver ACL rejection reply');
-          }
-        }
 
         // Notify the guardian about the access request so they can approve/deny.
         // Only fires when a guardian binding exists and no duplicate pending
         // request already exists for this requester.
+        let guardianNotified = false;
         try {
-          notifyGuardianOfAccessRequest({
+          guardianNotified = notifyGuardianOfAccessRequest({
             canonicalAssistantId,
             sourceChannel,
             externalChatId,
@@ -282,25 +273,89 @@ export async function handleChannelInbound(
           log.error({ err, sourceChannel, externalChatId }, 'Failed to notify guardian of access request');
         }
 
-        return Response.json({ accepted: true, denied: true, reason: 'not_a_member' });
-      }
-    }
-
-    if (resolvedMember) {
-      if (resolvedMember.status !== 'active') {
-        log.info({ sourceChannel, memberId: resolvedMember.id, status: resolvedMember.status }, 'Ingress ACL: member not active, denying');
         if (body.replyCallbackUrl) {
+          const replyText = guardianNotified
+            ? "I've let my guardian know you'd like access. They'll send you a verification code if they approve your request."
+            : "Sorry, you haven't been approved to message this assistant.";
           try {
             await deliverChannelReply(body.replyCallbackUrl, {
               chatId: externalChatId,
-              text: "Sorry, you haven't been approved to message this assistant. You can ask its Guardian for an invite.",
+              text: replyText,
               assistantId,
             }, bearerToken);
           } catch (err) {
             log.error({ err, externalChatId }, 'Failed to deliver ACL rejection reply');
           }
         }
-        return Response.json({ accepted: true, denied: true, reason: `member_${resolvedMember.status}` });
+
+        return Response.json({ accepted: true, denied: true, reason: 'not_a_member' });
+      }
+    }
+
+    if (resolvedMember) {
+      if (resolvedMember.status !== 'active') {
+        // Same bypass logic as the no-member branch: verification codes and
+        // bootstrap commands must pass through even when the member record is
+        // revoked/blocked — otherwise the user can never re-verify.
+        let denyInactiveMember = true;
+        if (isGuardianVerifyCode) {
+          const hasPendingChallenge = !!getPendingChallenge(canonicalAssistantId, sourceChannel);
+          const hasActiveOutboundSession = !!findActiveSession(canonicalAssistantId, sourceChannel);
+          if (hasPendingChallenge || hasActiveOutboundSession) {
+            denyInactiveMember = false;
+          } else {
+            log.info({ sourceChannel, memberId: resolvedMember.id, hasPendingChallenge, hasActiveOutboundSession }, 'Ingress ACL: inactive member verification bypass denied');
+          }
+        }
+        if (isBootstrapCommand) {
+          const bootstrapPayload = (rawCommandIntentForAcl as Record<string, unknown>).payload as string;
+          const bootstrapTokenForAcl = bootstrapPayload.slice(3);
+          const bootstrapSessionForAcl = resolveBootstrapToken(canonicalAssistantId, sourceChannel, bootstrapTokenForAcl);
+          if (bootstrapSessionForAcl && bootstrapSessionForAcl.status === 'pending_bootstrap') {
+            denyInactiveMember = false;
+          } else {
+            log.info({ sourceChannel, memberId: resolvedMember.id, hasValidBootstrapSession: false }, 'Ingress ACL: inactive member bootstrap bypass denied');
+          }
+        }
+
+        if (denyInactiveMember) {
+          log.info({ sourceChannel, memberId: resolvedMember.id, status: resolvedMember.status }, 'Ingress ACL: member not active, denying');
+
+          // For revoked/pending members, notify the guardian so they can
+          // re-approve. Blocked members are intentionally excluded — the
+          // guardian already made an explicit decision to block them.
+          let guardianNotified = false;
+          if (resolvedMember.status !== 'blocked') {
+            try {
+              guardianNotified = notifyGuardianOfAccessRequest({
+                canonicalAssistantId,
+                sourceChannel,
+                externalChatId,
+                senderExternalUserId: body.senderExternalUserId,
+                senderName: body.senderName,
+                senderUsername: body.senderUsername,
+              });
+            } catch (err) {
+              log.error({ err, sourceChannel, externalChatId }, 'Failed to notify guardian of access request');
+            }
+          }
+
+          if (body.replyCallbackUrl) {
+            const replyText = guardianNotified
+              ? "I've let my guardian know you'd like access. They'll send you a verification code if they approve your request."
+              : "Sorry, you haven't been approved to message this assistant.";
+            try {
+              await deliverChannelReply(body.replyCallbackUrl, {
+                chatId: externalChatId,
+                text: replyText,
+                assistantId,
+              }, bearerToken);
+            } catch (err) {
+              log.error({ err, externalChatId }, 'Failed to deliver ACL rejection reply');
+            }
+          }
+          return Response.json({ accepted: true, denied: true, reason: `member_${resolvedMember.status}` });
+        }
       }
 
       if (resolvedMember.policy === 'deny') {
@@ -309,7 +364,7 @@ export async function handleChannelInbound(
           try {
             await deliverChannelReply(body.replyCallbackUrl, {
               chatId: externalChatId,
-              text: "Sorry, you haven't been approved to message this assistant. You can ask its Guardian for an invite.",
+              text: "Sorry, you haven't been approved to message this assistant.",
               assistantId,
             }, bearerToken);
           } catch (err) {
@@ -855,6 +910,15 @@ export async function handleChannelInbound(
             );
 
             if (resolved) {
+              // Mint a scoped grant so the voice call can consume it
+              // for subsequent tool confirmations.
+              tryMintGuardianActionGrant({
+                resolvedRequest: resolved,
+                answerText,
+                decisionChannel: sourceChannel,
+                guardianExternalUserId: body.senderExternalUserId,
+              });
+
               return Response.json({
                 accepted: true,
                 duplicate: false,
@@ -1408,7 +1472,7 @@ function notifyGuardianOfAccessRequest(params: {
   senderExternalUserId?: string;
   senderName?: string;
   senderUsername?: string;
-}): void {
+}): boolean {
   const {
     canonicalAssistantId,
     sourceChannel,
@@ -1418,16 +1482,17 @@ function notifyGuardianOfAccessRequest(params: {
     senderUsername,
   } = params;
 
-  if (!senderExternalUserId) return;
+  if (!senderExternalUserId) return false;
 
   const binding = getGuardianBinding(canonicalAssistantId, sourceChannel);
   if (!binding) {
     log.debug({ sourceChannel, canonicalAssistantId }, 'No guardian binding for access request notification');
-    return;
+    return false;
   }
 
   // Deduplicate: skip if there is already a pending approval request for
-  // the same requester on this channel.
+  // the same requester on this channel.  Still return true — the guardian
+  // was already notified for this request.
   const existing = findPendingAccessRequestForRequester(
     canonicalAssistantId,
     sourceChannel,
@@ -1439,7 +1504,7 @@ function notifyGuardianOfAccessRequest(params: {
       { sourceChannel, senderExternalUserId, existingId: existing.id },
       'Skipping duplicate access request notification',
     );
-    return;
+    return true;
   }
 
   const senderIdentifier = senderName || senderUsername || senderExternalUserId;
@@ -1491,6 +1556,8 @@ function notifyGuardianOfAccessRequest(params: {
     { sourceChannel, senderExternalUserId, senderIdentifier },
     'Guardian notified of non-member access request',
   );
+
+  return true;
 }
 
 // ---------------------------------------------------------------------------

package/src/security/tool-approval-digest.ts

@@ -0,0 +1,67 @@
+/**
+ * Canonical JSON serialization and deterministic SHA-256 hash for tool
+ * approval signatures.
+ *
+ * Producers (grant creators) and consumers (grant matchers) must use the
+ * same serialization to ensure digest equality.  The algorithm:
+ *   1. Sort object keys recursively (depth-first).
+ *   2. Convert to a canonical JSON string with no whitespace.
+ *   3. SHA-256 hash the UTF-8 bytes and return a lowercase hex digest.
+ */
+
+import { createHash } from 'node:crypto';
+
+// ---------------------------------------------------------------------------
+// Canonical JSON serialization
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively sort all object keys and return a deterministic JSON string.
+ *
+ * Handles nested objects, arrays (element order preserved), and primitive
+ * values.  `undefined` values inside objects are omitted (matching
+ * JSON.stringify semantics).  `null` is preserved.
+ */
+export function canonicalJsonSerialize(value: unknown): string {
+  return JSON.stringify(sortKeysDeep(value));
+}
+
+function sortKeysDeep(value: unknown): unknown {
+  if (value === null || value === undefined) return value;
+
+  if (Array.isArray(value)) {
+    return value.map(sortKeysDeep);
+  }
+
+  if (typeof value === 'object') {
+    const sorted: Record<string, unknown> = {};
+    const keys = Object.keys(value as Record<string, unknown>).sort();
+    for (const key of keys) {
+      sorted[key] = sortKeysDeep((value as Record<string, unknown>)[key]);
+    }
+    return sorted;
+  }
+
+  // Primitive — number, string, boolean
+  return value;
+}
+
+// ---------------------------------------------------------------------------
+// Digest computation
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute a deterministic SHA-256 hex digest over the canonical
+ * serialization of a tool invocation's name and input.
+ *
+ * The digest covers `{ toolName, input }` so that two invocations of the
+ * same tool with identical (deeply-equal) inputs always produce the same
+ * hash, regardless of key ordering in the original input object.
+ */
+export function computeToolApprovalDigest(
+  toolName: string,
+  input: Record<string, unknown>,
+): string {
+  const payload = canonicalJsonSerialize({ input, toolName });
+  return createHash('sha256').update(payload, 'utf8').digest('hex');
+}

package/src/skills/remote-skill-policy.ts

@@ -0,0 +1,131 @@
+export type RemoteSkillProvider = 'clawhub' | 'skillssh';
+
+export type SkillsShRisk = 'safe' | 'low' | 'medium' | 'high' | 'critical' | 'unknown';
+export type SkillsShRiskThreshold = Exclude<SkillsShRisk, 'unknown'>;
+
+export interface RemoteSkillPolicy {
+  /**
+   * When true, suspicious skills are excluded from installable lists
+   * and blocked from installation.
+   */
+  blockSuspicious: boolean;
+  /**
+   * When true, malware-blocked skills are excluded from installable lists
+   * and blocked from installation.
+   */
+  blockMalware: boolean;
+  /**
+   * Maximum allowed Skills.sh audit risk. Anything above this threshold is blocked.
+   */
+  maxSkillsShRisk: SkillsShRiskThreshold;
+}
+
+export interface ClawhubModerationState {
+  isSuspicious?: boolean;
+  isMalwareBlocked?: boolean;
+}
+
+export interface SkillsShAuditState {
+  risk?: SkillsShRisk | null;
+}
+
+interface RemoteSkillCandidateBase {
+  provider: RemoteSkillProvider;
+  slug: string;
+}
+
+export interface ClawhubRemoteSkillCandidate extends RemoteSkillCandidateBase {
+  provider: 'clawhub';
+  moderation?: ClawhubModerationState | null;
+}
+
+export interface SkillsShRemoteSkillCandidate extends RemoteSkillCandidateBase {
+  provider: 'skillssh';
+  audit?: SkillsShAuditState | null;
+}
+
+export type RemoteSkillCandidate =
+  | ClawhubRemoteSkillCandidate
+  | SkillsShRemoteSkillCandidate;
+
+export type RemoteSkillDenyReason =
+  | 'clawhub_suspicious'
+  | 'clawhub_malware_blocked'
+  | 'clawhub_moderation_missing'
+  | 'skillssh_risk_exceeds_threshold';
+
+export type RemoteSkillInstallDecision =
+  | { ok: true }
+  | { ok: false; reason: RemoteSkillDenyReason };
+
+export const DEFAULT_REMOTE_SKILL_POLICY: Readonly<RemoteSkillPolicy> = Object.freeze({
+  blockSuspicious: true,
+  blockMalware: true,
+  maxSkillsShRisk: 'medium',
+});
+
+const SKILLS_SH_RISK_RANK: Record<SkillsShRisk, number> = {
+  safe: 0,
+  low: 1,
+  medium: 2,
+  high: 3,
+  critical: 4,
+  // Fail closed when risk is unknown.
+  unknown: 5,
+};
+
+function normalizeSkillsShRisk(audit: SkillsShAuditState | null | undefined): SkillsShRisk {
+  const risk = audit?.risk;
+  if (risk == null) return 'unknown';
+  // Coerce unrecognized risk labels to 'unknown' so we fail closed.
+  if (!Object.hasOwn(SKILLS_SH_RISK_RANK, risk)) return 'unknown';
+  return risk;
+}
+
+function exceedsSkillsShRiskThreshold(
+  audit: SkillsShAuditState | null | undefined,
+  threshold: SkillsShRiskThreshold,
+): boolean {
+  const actualRisk = normalizeSkillsShRisk(audit);
+  return SKILLS_SH_RISK_RANK[actualRisk] > SKILLS_SH_RISK_RANK[threshold];
+}
+
+export function evaluateRemoteSkillInstall(
+  candidate: RemoteSkillCandidate,
+  policy: RemoteSkillPolicy = DEFAULT_REMOTE_SKILL_POLICY,
+): RemoteSkillInstallDecision {
+  if (candidate.provider === 'clawhub') {
+    // Fail closed: block Clawhub skills when moderation data is missing.
+    if (candidate.moderation == null) {
+      return { ok: false, reason: 'clawhub_moderation_missing' };
+    }
+
+    if (policy.blockMalware && candidate.moderation.isMalwareBlocked === true) {
+      return { ok: false, reason: 'clawhub_malware_blocked' };
+    }
+    if (policy.blockSuspicious && candidate.moderation.isSuspicious === true) {
+      return { ok: false, reason: 'clawhub_suspicious' };
+    }
+    return { ok: true };
+  }
+
+  if (exceedsSkillsShRiskThreshold(candidate.audit, policy.maxSkillsShRisk)) {
+    return { ok: false, reason: 'skillssh_risk_exceeds_threshold' };
+  }
+
+  return { ok: true };
+}
+
+export function isRemoteSkillInstallable(
+  candidate: RemoteSkillCandidate,
+  policy: RemoteSkillPolicy = DEFAULT_REMOTE_SKILL_POLICY,
+): boolean {
+  return evaluateRemoteSkillInstall(candidate, policy).ok;
+}
+
+export function filterInstallableRemoteSkills<T extends RemoteSkillCandidate>(
+  skills: T[],
+  policy: RemoteSkillPolicy = DEFAULT_REMOTE_SKILL_POLICY,
+): T[] {
+  return skills.filter((skill) => isRemoteSkillInstallable(skill, policy));
+}