@vellumai/assistant 0.6.5 → 0.7.0

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

@@ -4,87 +4,43 @@
  * These endpoints resolve pending confirmations, secrets, and trust rules
  * by requestId — orthogonal to message sending.
  *
- * All approval endpoints require a valid JWT via the Authorization: Bearer
- * header. Guardian decisions additionally verify that the actor is the
- * bound guardian.
+ * Auth is enforced at the transport layer (HTTP policy middleware, IPC
+ * socket trust) — handlers contain only business logic.
  */
 import { z } from "zod";
 
+import { emitFeedEvent } from "../../home/emit-feed-event.js";
 import { getConversationByKey } from "../../memory/conversation-key-store.js";
-import { addRule } from "../../permissions/trust-store.js";
 import type { UserDecision } from "../../permissions/types.js";
-import {
-  isConversationHostAccessDecision,
-  isConversationHostAccessEnablePrompt,
-  isPermissionControlsV2Enabled,
-} from "../../permissions/v2-consent-policy.js";
-import { getTool } from "../../tools/registry.js";
 import { getLogger } from "../../util/logger.js";
-import { requireBoundGuardian } from "../auth/require-bound-guardian.js";
-import type { AuthContext } from "../auth/types.js";
-import { httpError } from "../http-errors.js";
-import type { RouteDefinition } from "../http-router.js";
 import * as pendingInteractions from "../pending-interactions.js";
+import { BadRequestError, NotFoundError } from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 const log = getLogger("approval-routes");
 
-function canonicalizeV2ConfirmDecision(params: {
+function canonicalizeConfirmDecision(params: {
   decision: string;
   interaction: NonNullable<ReturnType<typeof pendingInteractions.get>>;
 }): UserDecision | null {
-  const { decision, interaction } = params;
+  const { decision } = params;
   if (decision === "allow" || decision === "deny") {
     return decision;
   }
-
-  const details = interaction.confirmationDetails;
-  if (!details || isConversationHostAccessEnablePrompt(details)) {
-    return null;
-  }
-
-  if (
-    (decision === "allow_10m" || decision === "allow_conversation") &&
-    details.temporaryOptionsAvailable?.includes(decision)
-  ) {
-    return "allow";
-  }
-
-  if (
-    (decision === "always_allow" || decision === "always_deny") &&
-    details.persistentDecisionsAllowed
-  ) {
-    return decision === "always_deny" ? "deny" : "allow";
-  }
-
   return null;
 }
 
 /**
  * POST /v1/confirm — resolve a pending confirmation by requestId.
- * Requires AuthContext with guardian-bound actor.
  */
-export async function handleConfirm(
-  req: Request,
-  authContext: AuthContext,
-): Promise<Response> {
-  const authError = requireBoundGuardian(authContext);
-  if (authError) return authError;
-
-  const body = (await req.json()) as {
-    requestId?: string;
-    decision?: string;
-    selectedPattern?: string;
-    selectedScope?: string;
-  };
-
-  const { requestId, selectedPattern, selectedScope } = body;
-  // Normalize legacy decision: older clients may still send
-  // "always_allow_high_risk" for high-risk prompts.
-  const decision =
-    body.decision === "always_allow_high_risk" ? "always_allow" : body.decision;
+function handleConfirm({ body }: RouteHandlerArgs) {
+  const requestId = body?.requestId as string | undefined;
+  const decision = body?.decision as string | undefined;
+  const selectedPattern = body?.selectedPattern as string | undefined;
+  const selectedScope = body?.selectedScope as string | undefined;
 
   if (!requestId || typeof requestId !== "string") {
-    return httpError("BAD_REQUEST", "requestId is required", 400);
+    throw new BadRequestError("requestId is required");
   }
 
   const peeked = pendingInteractions.get(requestId);
@@ -93,108 +49,16 @@ export async function handleConfirm(
       { requestId, decision },
       "Confirmation POST for unknown requestId (already consumed or never registered)",
     );
-    return httpError(
-      "NOT_FOUND",
-      "No pending interaction found for this requestId",
-      404,
-    );
-  }
-
-  const v2Enabled = isPermissionControlsV2Enabled();
-  const effectiveDecision = v2Enabled
-    ? typeof decision === "string"
-      ? canonicalizeV2ConfirmDecision({ decision, interaction: peeked })
-      : null
-    : decision;
-  const validConfirmDecisions = [
-    "allow",
-    "allow_10m",
-    "allow_conversation",
-    "deny",
-    "always_allow",
-    "always_deny",
-  ];
-  if (
-    (v2Enabled && effectiveDecision == null) ||
-    (!v2Enabled &&
-      (typeof decision !== "string" ||
-        !validConfirmDecisions.includes(decision)))
-  ) {
-    return httpError(
-      "BAD_REQUEST",
-      v2Enabled
-        ? "decision must resolve to allow or deny under permission-controls-v2"
-        : `decision must be one of: ${validConfirmDecisions.join(", ")}`,
-      400,
-    );
-  }
-
-  if (
-    peeked.confirmationDetails &&
-    isConversationHostAccessEnablePrompt(peeked.confirmationDetails) &&
-    !isConversationHostAccessDecision(effectiveDecision as UserDecision)
-  ) {
-    return httpError(
-      "FORBIDDEN",
-      "Conversation host-access prompts only accept allow or deny",
-      403,
-    );
-  }
-
-  if (v2Enabled && (selectedPattern || selectedScope)) {
-    return httpError(
-      "FORBIDDEN",
-      "Scoped or persistent approval selections are not supported under permission-controls-v2",
-      403,
-    );
+    throw new NotFoundError("No pending interaction found for this requestId");
   }
 
-  // For decisions that persist trust rules, validate that selectedPattern
-  // and selectedScope are among the options the server actually offered.
-  // This prevents a crafted request from injecting overly-broad rules.
-  const persistsRule =
-    decision === "always_allow" || decision === "always_deny";
-  if (persistsRule && (selectedPattern || selectedScope)) {
-    const confirmation = peeked.confirmationDetails;
-    if (!confirmation) {
-      return httpError(
-        "CONFLICT",
-        "No confirmation details available for this request",
-        409,
-      );
-    }
-
-    if (selectedPattern) {
-      const validPatterns = (confirmation.allowlistOptions ?? []).map(
-        (o) => o.pattern,
-      );
-      if (!validPatterns.includes(selectedPattern)) {
-        return httpError(
-          "FORBIDDEN",
-          "selectedPattern does not match any server-provided allowlist option",
-          403,
-        );
-      }
-    }
+  const effectiveDecision =
+    typeof decision === "string"
+      ? canonicalizeConfirmDecision({ decision, interaction: peeked })
+      : null;
 
-    if (selectedScope) {
-      const validScopes = (confirmation.scopeOptions ?? []).map((o) => o.scope);
-      if (validScopes.length === 0) {
-        if (selectedScope !== "everywhere") {
-          return httpError(
-            "FORBIDDEN",
-            'non-scoped tools only accept scope "everywhere"',
-            403,
-          );
-        }
-      } else if (!validScopes.includes(selectedScope)) {
-        return httpError(
-          "FORBIDDEN",
-          "selectedScope does not match any server-provided scope option",
-          403,
-        );
-      }
-    }
+  if (effectiveDecision == null) {
+    throw new BadRequestError("decision must resolve to allow or deny");
   }
 
   // Validation passed — consume the pending interaction.
@@ -207,13 +71,30 @@ export async function handleConfirm(
       toolName: interaction.confirmationDetails?.toolName,
       conversationId: interaction.conversationId,
     },
-    "Confirmation resolved via HTTP",
+    "Confirmation resolved",
   );
 
+  const approved = effectiveDecision === "allow";
+  const toolName = interaction.confirmationDetails?.toolName ?? "unknown tool";
+  void emitFeedEvent({
+    source: "assistant",
+    title: `${approved ? "Approved" : "Denied"} use of ${toolName}.`,
+    summary: `${approved ? "Approved" : "Denied"} use of ${toolName}.`,
+    dedupKey: `tool-approval:${requestId}`,
+    urgency: approved ? undefined : "medium",
+    conversationId: interaction.conversationId,
+    detailPanel: { kind: "toolPermission" },
+  }).catch((err) => {
+    log.warn(
+      { err, requestId },
+      "Failed to emit tool approval resolution feed event",
+    );
+  });
+
   // ACP permissions: resolve directly without a Conversation object.
   if (interaction.directResolve) {
     interaction.directResolve(effectiveDecision as UserDecision);
-    return Response.json({ accepted: true });
+    return { accepted: true };
   }
 
   interaction.conversation!.handleConfirmationResponse(
@@ -227,30 +108,19 @@ export async function handleConfirm(
     },
   );
 
-  return Response.json({ accepted: true });
+  return { accepted: true };
 }
 
 /**
  * POST /v1/secret — resolve a pending secret request by requestId.
- * Requires AuthContext with guardian-bound actor.
  */
-export async function handleSecret(
-  req: Request,
-  authContext: AuthContext,
-): Promise<Response> {
-  const authError = requireBoundGuardian(authContext);
-  if (authError) return authError;
-
-  const body = (await req.json()) as {
-    requestId?: string;
-    value?: string;
-    delivery?: string;
-  };
-
-  const { requestId, value, delivery } = body;
+function handleSecret({ body }: RouteHandlerArgs) {
+  const requestId = body?.requestId as string | undefined;
+  const value = body?.value as string | undefined;
+  const delivery = body?.delivery as string | undefined;
 
   if (!requestId || typeof requestId !== "string") {
-    return httpError("BAD_REQUEST", "requestId is required", 400);
+    throw new BadRequestError("requestId is required");
   }
 
   if (
@@ -258,20 +128,12 @@ export async function handleSecret(
     delivery !== "store" &&
     delivery !== "transient_send"
   ) {
-    return httpError(
-      "BAD_REQUEST",
-      'delivery must be "store" or "transient_send"',
-      400,
-    );
+    throw new BadRequestError('delivery must be "store" or "transient_send"');
   }
 
   const interaction = pendingInteractions.resolve(requestId);
   if (!interaction) {
-    return httpError(
-      "NOT_FOUND",
-      "No pending interaction found for this requestId",
-      404,
-    );
+    throw new NotFoundError("No pending interaction found for this requestId");
   }
 
   interaction.conversation!.handleSecretResponse(
@@ -279,154 +141,19 @@ export async function handleSecret(
     value,
     delivery as "store" | "transient_send" | undefined,
   );
-  return Response.json({ accepted: true });
-}
-
-/**
- * POST /v1/trust-rules — add a trust rule for a pending confirmation.
- * Requires AuthContext with guardian-bound actor.
- *
- * Does NOT resolve the confirmation itself (the client still needs to
- * POST /v1/confirm to approve/deny). Validates the pattern and scope
- * against the server-provided allowlist options from the original
- * confirmation_request.
- */
-export async function handleTrustRule(
-  req: Request,
-  authContext: AuthContext,
-): Promise<Response> {
-  const authError = requireBoundGuardian(authContext);
-  if (authError) return authError;
-
-  if (isPermissionControlsV2Enabled()) {
-    return httpError(
-      "FORBIDDEN",
-      "Persistent trust rules are not supported under permission-controls-v2",
-      403,
-    );
-  }
-
-  const body = (await req.json()) as {
-    requestId?: string;
-    pattern?: string;
-    scope?: string;
-    decision?: string;
-  };
-
-  const { requestId, pattern, scope, decision } = body;
-
-  if (!requestId || typeof requestId !== "string") {
-    return httpError("BAD_REQUEST", "requestId is required", 400);
-  }
-
-  if (!pattern || typeof pattern !== "string") {
-    return httpError("BAD_REQUEST", "pattern is required", 400);
-  }
-
-  if (!scope || typeof scope !== "string") {
-    return httpError("BAD_REQUEST", "scope is required", 400);
-  }
-
-  if (decision !== "allow" && decision !== "deny") {
-    return httpError("BAD_REQUEST", 'decision must be "allow" or "deny"', 400);
-  }
-
-  // Look up without removing — trust rule doesn't resolve the confirmation
-  const interaction = pendingInteractions.get(requestId);
-  if (!interaction) {
-    return httpError(
-      "NOT_FOUND",
-      "No pending interaction found for this requestId",
-      404,
-    );
-  }
-
-  if (!interaction.confirmationDetails) {
-    return httpError(
-      "CONFLICT",
-      "No confirmation details available for this request",
-      409,
-    );
-  }
-
-  const confirmation = interaction.confirmationDetails;
-
-  if (confirmation.persistentDecisionsAllowed === false) {
-    return httpError(
-      "FORBIDDEN",
-      "Persistent trust rules are not allowed for this tool invocation",
-      403,
-    );
-  }
-
-  // Validate pattern against server-provided allowlist options
-  const validPatterns = (confirmation.allowlistOptions ?? []).map(
-    (o) => o.pattern,
-  );
-  if (!validPatterns.includes(pattern)) {
-    return httpError(
-      "FORBIDDEN",
-      "pattern does not match any server-provided allowlist option",
-      403,
-    );
-  }
-
-  // Validate scope against server-provided scope options.
-  // Non-scoped tools have empty scopeOptions — only "everywhere" is valid for them.
-  const validScopes = (confirmation.scopeOptions ?? []).map((o) => o.scope);
-  if (validScopes.length === 0) {
-    if (scope !== "everywhere") {
-      return httpError(
-        "FORBIDDEN",
-        'non-scoped tools only accept scope "everywhere"',
-        403,
-      );
-    }
-  } else if (!validScopes.includes(scope)) {
-    return httpError(
-      "FORBIDDEN",
-      "scope does not match any server-provided scope option",
-      403,
-    );
-  }
-
-  try {
-    const tool = getTool(confirmation.toolName);
-    const executionTarget =
-      tool?.origin === "skill" ? confirmation.executionTarget : undefined;
-
-    // Canonicalization is handled inside addRule — no need to pre-parse here.
-    addRule(confirmation.toolName, pattern, scope, decision, undefined, {
-      ...(executionTarget != null ? { executionTarget } : {}),
-    });
-    log.info(
-      { tool: confirmation.toolName, pattern, scope, decision, requestId },
-      "Trust rule added via HTTP (bound to pending confirmation)",
-    );
-    return Response.json({ accepted: true });
-  } catch (err) {
-    log.error({ err }, "Failed to add trust rule");
-    return httpError("INTERNAL_ERROR", "Failed to add trust rule", 500);
-  }
+  return { accepted: true };
 }
 
 /**
- * GET /v1/pending-interactions?conversationKey=...
- * Requires AuthContext (already verified upstream by JWT middleware).
+ * GET /v1/pending-interactions?conversationKey=...&conversationId=...
  *
  * Returns pending confirmations and secrets for a conversation, allowing
  * polling-based clients (like the CLI) to discover approval requests
  * without SSE.
  */
-export function handleListPendingInteractions(
-  url: URL,
-  _authContext: AuthContext,
-): Response {
-  // Auth is already verified by JWT middleware upstream — no additional
-  // verification needed here. The _authContext parameter is accepted for
-  // type consistency and potential future use.
-  const conversationKey = url.searchParams.get("conversationKey");
-  const conversationId = url.searchParams.get("conversationId");
+function handleListPendingInteractions({ queryParams }: RouteHandlerArgs) {
+  const conversationKey = queryParams?.conversationKey;
+  const conversationId = queryParams?.conversationId;
 
   let resolvedConversationId: string | undefined;
   if (conversationId) {
@@ -435,15 +162,13 @@ export function handleListPendingInteractions(
     const mapping = getConversationByKey(conversationKey);
     resolvedConversationId = mapping?.conversationId;
   } else {
-    return httpError(
-      "BAD_REQUEST",
+    throw new BadRequestError(
       "conversationKey or conversationId query parameter is required",
-      400,
     );
   }
 
   if (!resolvedConversationId) {
-    return Response.json({ pendingConfirmation: null, pendingSecret: null });
+    return { pendingConfirmation: null, pendingSecret: null };
   }
 
   const interactions = pendingInteractions.getByConversation(
@@ -455,7 +180,7 @@ export function handleListPendingInteractions(
   );
   const secret = interactions.find((i) => i.kind === "secret");
 
-  return Response.json({
+  return {
     pendingConfirmation: confirmation
       ? {
           requestId: confirmation.requestId,
@@ -472,8 +197,6 @@ export function handleListPendingInteractions(
           scopeOptions: confirmation.confirmationDetails?.scopeOptions,
           persistentDecisionsAllowed:
             confirmation.confirmationDetails?.persistentDecisionsAllowed,
-          temporaryOptionsAvailable:
-            confirmation.confirmationDetails?.temporaryOptionsAvailable,
           acpToolKind: confirmation.confirmationDetails?.acpToolKind,
           acpOptions: confirmation.confirmationDetails?.acpOptions,
         }
@@ -483,111 +206,87 @@ export function handleListPendingInteractions(
           requestId: secret.requestId,
         }
       : null,
-  });
+  };
 }
 
 // ---------------------------------------------------------------------------
 // Route definitions
 // ---------------------------------------------------------------------------
 
-export function approvalRouteDefinitions(): RouteDefinition[] {
-  return [
-    {
-      endpoint: "confirm",
-      method: "POST",
-      summary: "Resolve a pending confirmation",
-      description: "Approve or deny a pending tool confirmation by requestId.",
-      tags: ["approvals"],
-      requestBody: z.object({
-        requestId: z.string().describe("Pending interaction request ID"),
-        decision: z
-          .string()
-          .describe(
-            "One of: allow, allow_10m, allow_conversation, deny, always_allow, always_deny",
-          ),
-        selectedPattern: z
-          .string()
-          .describe("Allowlist pattern for persistent decisions")
-          .optional(),
-        selectedScope: z
-          .string()
-          .describe("Scope for persistent decisions")
-          .optional(),
-      }),
-      responseBody: z.object({
-        accepted: z.boolean(),
-      }),
-      handler: async ({ req, authContext }) => handleConfirm(req, authContext),
-    },
-    {
-      endpoint: "secret",
-      method: "POST",
-      summary: "Resolve a pending secret request",
-      description: "Provide a secret value for a pending secret request.",
-      tags: ["approvals"],
-      requestBody: z.object({
-        requestId: z.string().describe("Pending interaction request ID"),
-        value: z.string().describe("Secret value").optional(),
-        delivery: z
-          .string()
-          .describe("Delivery mode: store or transient_send")
-          .optional(),
-      }),
-      responseBody: z.object({
-        accepted: z.boolean(),
-      }),
-      handler: async ({ req, authContext }) => handleSecret(req, authContext),
-    },
-    {
-      endpoint: "trust-rules",
-      method: "POST",
-      summary: "Add a trust rule for a pending confirmation",
-      description:
-        "Add a trust rule bound to a pending confirmation without resolving it.",
-      tags: ["approvals"],
-      requestBody: z.object({
-        requestId: z.string().describe("Pending confirmation request ID"),
-        pattern: z.string().describe("Allowlist pattern"),
-        scope: z.string().describe("Scope for the rule"),
-        decision: z.string().describe("allow or deny"),
-      }),
-      responseBody: z.object({
-        accepted: z.boolean(),
-      }),
-      handler: async ({ req, authContext }) =>
-        handleTrustRule(req, authContext),
-    },
-    {
-      endpoint: "pending-interactions",
-      method: "GET",
-      summary: "List pending interactions",
-      description:
-        "Return pending confirmations and secrets for a conversation.",
-      tags: ["approvals"],
-      queryParams: [
-        {
-          name: "conversationKey",
-          schema: { type: "string" },
-          description: "Conversation key",
-        },
-        {
-          name: "conversationId",
-          schema: { type: "string" },
-          description: "Conversation ID",
-        },
-      ],
-      responseBody: z.object({
-        pendingConfirmation: z
-          .object({})
-          .passthrough()
-          .describe("Pending confirmation details or null"),
-        pendingSecret: z
-          .object({})
-          .passthrough()
-          .describe("Pending secret request or null"),
-      }),
-      handler: ({ url, authContext }) =>
-        handleListPendingInteractions(url, authContext),
-    },
-  ];
-}
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "confirm",
+    endpoint: "confirm",
+    method: "POST",
+    handler: handleConfirm,
+    requireGuardian: true,
+    summary: "Resolve a pending confirmation",
+    description: "Approve or deny a pending tool confirmation by requestId.",
+    tags: ["approvals"],
+    requestBody: z.object({
+      requestId: z.string().describe("Pending interaction request ID"),
+      decision: z.string().describe("One of: allow, deny"),
+      selectedPattern: z
+        .string()
+        .describe("Allowlist pattern for persistent decisions")
+        .optional(),
+      selectedScope: z
+        .string()
+        .describe("Scope for persistent decisions")
+        .optional(),
+    }),
+    responseBody: z.object({
+      accepted: z.boolean(),
+    }),
+  },
+  {
+    operationId: "secret",
+    endpoint: "secret",
+    method: "POST",
+    handler: handleSecret,
+    requireGuardian: true,
+    summary: "Resolve a pending secret request",
+    description: "Provide a secret value for a pending secret request.",
+    tags: ["approvals"],
+    requestBody: z.object({
+      requestId: z.string().describe("Pending interaction request ID"),
+      value: z.string().describe("Secret value").optional(),
+      delivery: z
+        .string()
+        .describe("Delivery mode: store or transient_send")
+        .optional(),
+    }),
+    responseBody: z.object({
+      accepted: z.boolean(),
+    }),
+  },
+  {
+    operationId: "pending_interactions",
+    endpoint: "pending-interactions",
+    method: "GET",
+    handler: handleListPendingInteractions,
+    summary: "List pending interactions",
+    description: "Return pending confirmations and secrets for a conversation.",
+    tags: ["approvals"],
+    queryParams: [
+      {
+        name: "conversationKey",
+        description: "Conversation key",
+      },
+      {
+        name: "conversationId",
+        description: "Conversation ID",
+      },
+    ],
+    responseBody: z.object({
+      pendingConfirmation: z
+        .object({})
+        .passthrough()
+        .describe("Pending confirmation details or null"),
+      pendingSecret: z
+        .object({})
+        .passthrough()
+        .describe("Pending secret request or null"),
+    }),
+  },
+];