@vellumai/assistant 0.3.0

package/src/runtime/channel-approvals.ts

@@ -0,0 +1,206 @@
+/**
+ * Channel-agnostic approval orchestration module.
+ *
+ * Bridges the gap between external channel adapters (Telegram, SMS, etc.)
+ * and the internal run orchestrator / permission system:
+ *
+ *   1. Detect pending confirmations for a conversation
+ *   2. Build human-readable approval prompts with action buttons
+ *   3. Consume user decisions and apply them to the underlying run
+ *   4. Build reminder prompts when non-decision messages arrive
+ */
+
+import { getPendingConfirmationsByConversation, getRun } from '../memory/runs-store.js';
+import type { PendingRunInfo } from '../memory/runs-store.js';
+import { addRule } from '../permissions/trust-store.js';
+import type { RunOrchestrator } from './run-orchestrator.js';
+import { DEFAULT_APPROVAL_ACTIONS } from './channel-approval-types.js';
+import type {
+  ChannelApprovalPrompt,
+  ApprovalUIMetadata,
+  ApprovalDecisionResult,
+} from './channel-approval-types.js';
+
+// ---------------------------------------------------------------------------
+// 1. Detect pending confirmations and build prompt
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a conversation has a pending tool-use confirmation and,
+ * if so, build a human-readable approval prompt.
+ *
+ * Returns `null` when there is nothing waiting for approval.
+ */
+export function getChannelApprovalPrompt(
+  conversationId: string,
+): ChannelApprovalPrompt | null {
+  const pending = getPendingConfirmationsByConversation(conversationId);
+  if (pending.length === 0) return null;
+
+  // Use the first pending run — channel UIs show one prompt at a time.
+  const info = pending[0];
+  return buildPromptFromRunInfo(info);
+}
+
+/**
+ * Internal helper: turn a PendingRunInfo into a ChannelApprovalPrompt.
+ */
+function buildPromptFromRunInfo(info: PendingRunInfo): ChannelApprovalPrompt {
+  const promptText = `The assistant wants to use the tool "${info.toolName}". Do you want to allow this?`;
+
+  // Hide "approve always" when persistent trust rules are disallowed for this invocation.
+  const actions = info.persistentDecisionsAllowed === false
+    ? DEFAULT_APPROVAL_ACTIONS.filter((a) => a.id !== 'approve_always')
+    : [...DEFAULT_APPROVAL_ACTIONS];
+
+  const plainTextFallback = info.persistentDecisionsAllowed === false
+    ? `${promptText}\n\nReply "yes" to approve or "no" to reject.`
+    : `${promptText}\n\nReply "yes" to approve once, "always" to approve always, or "no" to reject.`;
+
+  return { promptText, actions, plainTextFallback };
+}
+
+// ---------------------------------------------------------------------------
+// 2. Build gateway-facing UI metadata
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a prompt + run info into the `ApprovalUIMetadata` payload that
+ * gateway adapters use to render buttons and route decisions back.
+ */
+export function buildApprovalUIMetadata(
+  prompt: ChannelApprovalPrompt,
+  runInfo: PendingRunInfo,
+): ApprovalUIMetadata {
+  return {
+    runId: runInfo.runId,
+    requestId: runInfo.requestId,
+    actions: prompt.actions,
+    plainTextFallback: prompt.plainTextFallback,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 3. Consume a user decision and apply it to the run
+// ---------------------------------------------------------------------------
+
+export interface HandleDecisionResult {
+  applied: boolean;
+  runId?: string;
+}
+
+/**
+ * Find the pending run for a conversation, map the user's decision to the
+ * permission system's vocabulary, and apply it.
+ *
+ * For `approve_always`, a trust rule is persisted using the first allowlist
+ * option and first scope option from the pending confirmation (narrow
+ * default). The current invocation is also approved.
+ */
+export function handleChannelDecision(
+  conversationId: string,
+  decision: ApprovalDecisionResult,
+  orchestrator: RunOrchestrator,
+): HandleDecisionResult {
+  const pending = getPendingConfirmationsByConversation(conversationId);
+  if (pending.length === 0) return { applied: false };
+
+  const info = pending[0];
+
+  if (decision.action === 'approve_always') {
+    // Only persist a trust rule when the confirmation explicitly allows persistence
+    // AND provides explicit allowlist/scope options. Without explicit options we
+    // would create a blanket "**"/"everywhere" rule, which is a security risk.
+    const run = getRun(info.runId);
+    const confirmation = run?.pendingConfirmation;
+    if (
+      confirmation &&
+      confirmation.persistentDecisionsAllowed !== false &&
+      confirmation.allowlistOptions?.length &&
+      confirmation.scopeOptions?.length
+    ) {
+      const pattern = confirmation.allowlistOptions[0].pattern;
+      const scope = confirmation.scopeOptions[0].scope;
+      addRule(confirmation.toolName, pattern, scope, 'allow', 100, {
+        executionTarget: confirmation.executionTarget,
+      });
+    }
+    // When persistence is not allowed or options are missing, the decision
+    // still proceeds as a one-time approval (falls through to submitDecision).
+  }
+
+  // Map channel-level action to the permission system's UserDecision type.
+  const userDecision = decision.action === 'reject' ? 'deny' as const : 'allow' as const;
+  const result = orchestrator.submitDecision(info.runId, userDecision);
+
+  return {
+    applied: result === 'applied',
+    runId: info.runId,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 4. Guardian-aware approval prompt
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an approval prompt that includes context about which non-guardian
+ * user is requesting the action. Sent to the guardian's chat so they
+ * can approve or deny on behalf of the requester.
+ */
+export function buildGuardianApprovalPrompt(
+  info: PendingRunInfo,
+  requesterIdentifier: string,
+): ChannelApprovalPrompt {
+  const promptText =
+    `User ${requesterIdentifier} is requesting to run "${info.toolName}". Approve or deny?`;
+
+  // Guardian approvals are always one-time decisions — "approve always"
+  // doesn't make sense when the guardian is approving on behalf of someone else.
+  const actions = DEFAULT_APPROVAL_ACTIONS.filter((a) => a.id !== 'approve_always');
+
+  const plainTextFallback = `${promptText}\n\nReply "yes" to approve or "no" to reject.`;
+
+  return { promptText, actions, plainTextFallback };
+}
+
+// ---------------------------------------------------------------------------
+// 5. Channel UI capability check
+// ---------------------------------------------------------------------------
+
+/**
+ * Channels known to support rich inline approval UI (e.g. inline keyboards).
+ * All other channels fall back to plain-text instructions embedded in the
+ * message body.
+ */
+const RICH_APPROVAL_CHANNELS: ReadonlySet<string> = new Set(['telegram']);
+
+/**
+ * Returns true when the given channel supports rich approval UI such as
+ * inline buttons / keyboards. For channels that return false, the
+ * plainTextFallback instructions should be appended to the message body
+ * so the user sees how to approve or reject via text.
+ */
+export function channelSupportsRichApprovalUI(channel: string): boolean {
+  return RICH_APPROVAL_CHANNELS.has(channel);
+}
+
+// ---------------------------------------------------------------------------
+// 6. Reminder prompt for non-decision messages
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a reminder prompt when the user sends a non-decision message while
+ * an approval is pending. Reuses the original actions and fallback text
+ * but prefixes the prompt text with a reminder.
+ */
+export function buildReminderPrompt(
+  pendingPrompt: ChannelApprovalPrompt,
+): ChannelApprovalPrompt {
+  const reminderPrefix = "I'm still waiting for your decision on the previous request.";
+  return {
+    promptText: `${reminderPrefix}\n\n${pendingPrompt.promptText}`,
+    actions: pendingPrompt.actions,
+    plainTextFallback: `${reminderPrefix}\n\n${pendingPrompt.plainTextFallback}`,
+  };
+}

package/src/runtime/channel-guardian-service.ts

@@ -0,0 +1,212 @@
+/**
+ * Channel guardian verification service.
+ *
+ * Encapsulates the business logic for the guardian verification challenge
+ * lifecycle: creating challenges with cryptographic secrets, validating
+ * and consuming them, and managing guardian bindings.
+ */
+
+import { randomBytes, createHash } from 'crypto';
+import { v4 as uuid } from 'uuid';
+import {
+  createBinding,
+  getActiveBinding,
+  revokeBinding as storeRevokeBinding,
+  createChallenge,
+  findPendingChallengeByHash,
+  consumeChallenge,
+  getRateLimit,
+  recordInvalidAttempt,
+  resetRateLimit,
+} from '../memory/channel-guardian-store.js';
+import type { GuardianBinding } from '../memory/channel-guardian-store.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Challenge TTL in milliseconds (10 minutes). */
+const CHALLENGE_TTL_MS = 10 * 60 * 1000;
+
+/** Maximum invalid verification attempts within the throttling window before lockout. */
+const RATE_LIMIT_MAX_ATTEMPTS = 5;
+
+/** Throttling window in milliseconds (15 minutes). */
+const RATE_LIMIT_WINDOW_MS = 15 * 60 * 1000;
+
+/** Lockout duration in milliseconds (30 minutes). */
+const RATE_LIMIT_LOCKOUT_MS = 30 * 60 * 1000;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface CreateChallengeResult {
+  challengeId: string;
+  secret: string;
+  instruction: string;
+}
+
+export type ValidateChallengeResult =
+  | { success: true; bindingId: string }
+  | { success: false; reason: string };
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function hashSecret(secret: string): string {
+  return createHash('sha256').update(secret).digest('hex');
+}
+
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a human-readable channel label for use in guardian challenge
+ * instructions. Avoids hardcoding "Telegram" so SMS and future
+ * channels get appropriate wording.
+ */
+function channelLabel(channel: string): string {
+  switch (channel) {
+    case 'telegram': return 'Telegram';
+    case 'sms': return 'SMS';
+    default: return channel;
+  }
+}
+
+/**
+ * Create a new verification challenge for a guardian candidate.
+ *
+ * Generates a random secret, hashes it (SHA-256), and stores the
+ * challenge record with a 10-minute TTL. The raw secret is returned
+ * so it can be displayed to the user; only the hash is persisted.
+ */
+export function createVerificationChallenge(
+  assistantId: string,
+  channel: string,
+  sessionId?: string,
+): CreateChallengeResult {
+  const secret = randomBytes(32).toString('hex');
+  const challengeHash = hashSecret(secret);
+  const challengeId = uuid();
+  const expiresAt = Date.now() + CHALLENGE_TTL_MS;
+
+  createChallenge({
+    id: challengeId,
+    assistantId,
+    channel,
+    challengeHash,
+    expiresAt,
+    createdBySessionId: sessionId,
+  });
+
+  const label = channelLabel(channel);
+
+  return {
+    challengeId,
+    secret,
+    instruction: `Send \`/guardian_verify ${secret}\` to your bot via ${label} within 10 minutes.`,
+  };
+}
+
+/**
+ * Validate and consume a verification challenge.
+ *
+ * Checks per-actor/per-channel rate limits before attempting validation.
+ * Hashes the provided secret, looks up a matching pending challenge,
+ * validates it has not expired, consumes it, revokes any existing
+ * active binding, and creates a new guardian binding.
+ *
+ * On failure the invalid-attempt counter is incremented; after
+ * exceeding the threshold the actor is locked out for a cooldown
+ * period. On success the counter resets.
+ */
+export function validateAndConsumeChallenge(
+  assistantId: string,
+  channel: string,
+  secret: string,
+  actorExternalUserId: string,
+  actorChatId: string,
+): ValidateChallengeResult {
+  // ── Rate-limit check ──
+  const existing = getRateLimit(assistantId, channel, actorExternalUserId, actorChatId);
+  if (existing && existing.lockedUntil !== null && Date.now() < existing.lockedUntil) {
+    // Use the same generic failure message to avoid leaking whether the
+    // actor is rate-limited vs. the code is genuinely wrong.
+    return { success: false, reason: 'Verification failed. Please try again later.' };
+  }
+
+  const challengeHash = hashSecret(secret);
+
+  const challenge = findPendingChallengeByHash(assistantId, channel, challengeHash);
+  if (!challenge) {
+    recordInvalidAttempt(
+      assistantId, channel, actorExternalUserId, actorChatId,
+      RATE_LIMIT_WINDOW_MS, RATE_LIMIT_MAX_ATTEMPTS, RATE_LIMIT_LOCKOUT_MS,
+    );
+    return { success: false, reason: 'Verification failed. Please try again later.' };
+  }
+
+  if (Date.now() > challenge.expiresAt) {
+    recordInvalidAttempt(
+      assistantId, channel, actorExternalUserId, actorChatId,
+      RATE_LIMIT_WINDOW_MS, RATE_LIMIT_MAX_ATTEMPTS, RATE_LIMIT_LOCKOUT_MS,
+    );
+    return { success: false, reason: 'Verification failed. Please try again later.' };
+  }
+
+  // Consume the challenge so it cannot be reused
+  consumeChallenge(challenge.id, actorExternalUserId, actorChatId);
+
+  // Reset the rate-limit counter on success
+  resetRateLimit(assistantId, channel, actorExternalUserId, actorChatId);
+
+  // Revoke any existing active binding before creating a new one
+  storeRevokeBinding(assistantId, channel);
+
+  // Create the new guardian binding
+  const binding = createBinding({
+    assistantId,
+    channel,
+    guardianExternalUserId: actorExternalUserId,
+    guardianDeliveryChatId: actorChatId,
+    verifiedVia: 'challenge',
+  });
+
+  return { success: true, bindingId: binding.id };
+}
+
+/**
+ * Look up the active guardian binding for a given assistant and channel.
+ */
+export function getGuardianBinding(
+  assistantId: string,
+  channel: string,
+): GuardianBinding | null {
+  return getActiveBinding(assistantId, channel);
+}
+
+/**
+ * Check whether the given external user is the active guardian for
+ * the specified assistant and channel.
+ */
+export function isGuardian(
+  assistantId: string,
+  channel: string,
+  externalUserId: string,
+): boolean {
+  const binding = getActiveBinding(assistantId, channel);
+  return binding !== null && binding.guardianExternalUserId === externalUserId;
+}
+
+/**
+ * Revoke the active guardian binding for a given assistant and channel.
+ */
+export function revokeBinding(
+  assistantId: string,
+  channel: string,
+): boolean {
+  return storeRevokeBinding(assistantId, channel);
+}

package/src/runtime/gateway-client.ts

@@ -0,0 +1,58 @@
+import { getLogger } from '../util/logger.js';
+import type { RuntimeAttachmentMetadata } from './http-types.js';
+import type { ApprovalUIMetadata } from './channel-approval-types.js';
+
+const log = getLogger('gateway-client');
+
+const DELIVERY_TIMEOUT_MS = 30_000;
+
+export interface ChannelReplyPayload {
+  chatId: string;
+  text?: string;
+  assistantId?: string;
+  attachments?: RuntimeAttachmentMetadata[];
+  approval?: ApprovalUIMetadata;
+}
+
+export async function deliverChannelReply(
+  callbackUrl: string,
+  payload: ChannelReplyPayload,
+  bearerToken?: string,
+): Promise<void> {
+  const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+  if (bearerToken) {
+    headers['Authorization'] = `Bearer ${bearerToken}`;
+  }
+
+  const response = await fetch(callbackUrl, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(payload),
+    signal: AbortSignal.timeout(DELIVERY_TIMEOUT_MS),
+  });
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => '<unreadable>');
+    log.error(
+      { status: response.status, body, callbackUrl, chatId: payload.chatId },
+      'Channel reply delivery failed',
+    );
+    throw new Error(`Channel reply delivery failed (${response.status}): ${body}`);
+  }
+
+  log.info({ chatId: payload.chatId, callbackUrl }, 'Channel reply delivered');
+}
+
+/**
+ * Deliver an approval prompt (text + inline keyboard metadata) to the
+ * gateway so it can render the approval UI in the channel.
+ */
+export async function deliverApprovalPrompt(
+  callbackUrl: string,
+  chatId: string,
+  text: string,
+  approval: ApprovalUIMetadata,
+  bearerToken?: string,
+): Promise<void> {
+  await deliverChannelReply(callbackUrl, { chatId, text, approval }, bearerToken);
+}