@vellumai/assistant 0.4.2 → 0.4.4

package/src/runtime/local-actor-identity.ts

@@ -0,0 +1,76 @@
+/**
+ * Deterministic local actor identity for IPC connections.
+ *
+ * IPC (Unix domain socket) connections come from the local macOS native app.
+ * No actor token is sent over the socket; instead, the daemon assigns a
+ * deterministic local actor identity server-side by looking up the vellum
+ * channel guardian binding.
+ *
+ * This routes IPC connections through the same `resolveGuardianContext`
+ * pathway used by HTTP channel ingress, producing equivalent
+ * guardian-context behavior for the vellum channel.
+ */
+
+import type { ChannelId } from '../channels/types.js';
+import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.js';
+import { getActiveBinding } from '../memory/guardian-bindings.js';
+import { getLogger } from '../util/logger.js';
+import { DAEMON_INTERNAL_ASSISTANT_ID } from './assistant-scope.js';
+import {
+  resolveGuardianContext,
+  toGuardianRuntimeContext,
+} from './guardian-context-resolver.js';
+
+const log = getLogger('local-actor-identity');
+
+/**
+ * Resolve the guardian runtime context for a local IPC connection.
+ *
+ * Looks up the vellum guardian binding to obtain the `guardianPrincipalId`,
+ * then passes it as the sender identity through `resolveGuardianContext` --
+ * the same pathway HTTP channel routes use. This ensures IPC and HTTP
+ * produce equivalent trust classification for the vellum channel.
+ *
+ * When no vellum guardian binding exists (e.g. fresh install before
+ * bootstrap), falls back to a minimal guardian context so the local
+ * user is not incorrectly denied.
+ */
+export function resolveLocalIpcGuardianContext(
+  sourceChannel: ChannelId = 'vellum',
+): GuardianRuntimeContext {
+  const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
+  const binding = getActiveBinding(assistantId, 'vellum');
+
+  if (!binding) {
+    // No vellum binding yet (pre-bootstrap). The local user is
+    // inherently the guardian of their own machine, so produce a
+    // guardian context without a binding match. The trust resolver
+    // would classify this as 'unknown' due to no_binding, but for
+    // the local IPC case that is incorrect -- the local macOS user
+    // is always the guardian.
+    log.debug('No vellum guardian binding found; using fallback guardian context for IPC');
+    return {
+      sourceChannel,
+      trustClass: 'guardian',
+    };
+  }
+
+  const guardianPrincipalId = binding.guardianExternalUserId;
+
+  // Route through the shared trust resolution pipeline using 'vellum'
+  // as the channel for binding lookup. The guardianPrincipalId comes
+  // from the vellum binding, so the binding lookup must also target
+  // 'vellum' — otherwise resolveActorTrust would look up a different
+  // channel's binding (e.g. telegram/sms) and the IDs wouldn't match,
+  // causing a 'unknown' trust classification.
+  const guardianCtx = resolveGuardianContext({
+    assistantId,
+    sourceChannel: 'vellum',
+    externalChatId: 'local',
+    senderExternalUserId: guardianPrincipalId,
+  });
+
+  // Overlay the caller's actual sourceChannel onto the resolved context
+  // so downstream consumers see the correct channel provenance.
+  return toGuardianRuntimeContext(sourceChannel, guardianCtx);
+}

package/src/runtime/middleware/actor-token.ts

@@ -0,0 +1,271 @@
+/**
+ * Actor-token verification middleware for HTTP routes.
+ *
+ * Extracts the X-Actor-Token header, verifies the HMAC signature,
+ * checks that the token is active in the store, and returns the
+ * verified claims and resolved guardian runtime context.
+ *
+ * Used by vellum-channel HTTP routes (POST /v1/messages, POST /v1/confirm,
+ * POST /v1/guardian-actions/decision, etc.) to enforce identity-based
+ * authentication.
+ *
+ * For backward compatibility with bearer-authenticated local clients (CLI),
+ * provides fallback functions that resolve identity through the local IPC
+ * guardian context pathway when no actor token is present.
+ */
+
+import type { ChannelId } from '../../channels/types.js';
+import type { GuardianRuntimeContext } from '../../daemon/session-runtime-assembly.js';
+import { getActiveBinding } from '../../memory/guardian-bindings.js';
+import { getLogger } from '../../util/logger.js';
+import { type ActorTokenClaims, hashToken, verifyActorToken } from '../actor-token-service.js';
+import { findActiveByTokenHash } from '../actor-token-store.js';
+import { DAEMON_INTERNAL_ASSISTANT_ID } from '../assistant-scope.js';
+import {
+  resolveGuardianContext,
+  toGuardianRuntimeContext,
+} from '../guardian-context-resolver.js';
+import { resolveLocalIpcGuardianContext } from '../local-actor-identity.js';
+
+const log = getLogger('actor-token-middleware');
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ActorTokenResult {
+  ok: true;
+  claims: ActorTokenClaims;
+  guardianContext: GuardianRuntimeContext;
+}
+
+export interface ActorTokenError {
+  ok: false;
+  status: number;
+  message: string;
+}
+
+export type ActorTokenVerification = ActorTokenResult | ActorTokenError;
+
+// ---------------------------------------------------------------------------
+// Header extraction
+// ---------------------------------------------------------------------------
+
+const ACTOR_TOKEN_HEADER = 'x-actor-token';
+
+export function extractActorToken(req: Request): string | null {
+  return req.headers.get(ACTOR_TOKEN_HEADER) || null;
+}
+
+// ---------------------------------------------------------------------------
+// Full verification pipeline
+// ---------------------------------------------------------------------------
+
+/**
+ * Verify the X-Actor-Token header and resolve a guardian runtime context.
+ *
+ * Steps:
+ * 1. Extract the header value.
+ * 2. Verify HMAC signature and expiration.
+ * 3. Check the token hash is active in the actor-token store.
+ * 4. Resolve a guardian context through the standard trust pipeline using
+ *    the claims' guardianPrincipalId as the sender identity.
+ *
+ * Returns an ok result with claims and guardianContext, or an error with
+ * the HTTP status code and message to return.
+ */
+export function verifyHttpActorToken(req: Request): ActorTokenVerification {
+  const rawToken = extractActorToken(req);
+  if (!rawToken) {
+    return {
+      ok: false,
+      status: 401,
+      message: 'Missing X-Actor-Token header. Vellum HTTP requests require actor identity.',
+    };
+  }
+
+  // Structural + signature verification
+  const verifyResult = verifyActorToken(rawToken);
+  if (!verifyResult.ok) {
+    log.warn({ reason: verifyResult.reason }, 'Actor token verification failed');
+    return {
+      ok: false,
+      status: 401,
+      message: `Invalid actor token: ${verifyResult.reason}`,
+    };
+  }
+
+  // Check the token is active in the store (not revoked)
+  const tokenHash = hashToken(rawToken);
+  const record = findActiveByTokenHash(tokenHash);
+  if (!record) {
+    log.warn('Actor token not found in active store (possibly revoked)');
+    return {
+      ok: false,
+      status: 401,
+      message: 'Actor token is no longer active',
+    };
+  }
+
+  const { claims } = verifyResult;
+
+  // Resolve guardian context through the shared trust pipeline.
+  // The guardianPrincipalId from the token is used as the sender identity,
+  // and 'vellum' is used as the channel for binding lookup.
+  const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
+  const guardianCtx = resolveGuardianContext({
+    assistantId,
+    sourceChannel: 'vellum',
+    externalChatId: 'local',
+    senderExternalUserId: claims.guardianPrincipalId,
+  });
+
+  const guardianContext = toGuardianRuntimeContext('vellum' as ChannelId, guardianCtx);
+
+  return {
+    ok: true,
+    claims,
+    guardianContext,
+  };
+}
+
+/**
+ * Verify that the actor identity from a verified token matches the bound
+ * guardian for the vellum channel. Used for guardian-decision endpoints
+ * where only the guardian should be able to approve/reject.
+ *
+ * Returns true if the actor is the bound guardian, false otherwise.
+ */
+export function isActorBoundGuardian(claims: ActorTokenClaims): boolean {
+  const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
+  const binding = getActiveBinding(assistantId, 'vellum');
+  if (!binding) return false;
+  return binding.guardianExternalUserId === claims.guardianPrincipalId;
+}
+
+// ---------------------------------------------------------------------------
+// Bearer-auth fallback variants
+// ---------------------------------------------------------------------------
+
+/** Loopback addresses — used to gate the local identity fallback. */
+const LOOPBACK_ADDRESSES = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+
+/** Bun server shape needed for requestIP — avoids importing the full Bun type. */
+export type ServerWithRequestIP = {
+  requestIP(req: Request): { address: string; family: string; port: number } | null;
+};
+
+/**
+ * Result for the fallback verification path where the actor token is absent
+ * but the request is bearer-authenticated (local trusted client like CLI).
+ */
+export interface ActorTokenLocalFallbackResult {
+  ok: true;
+  claims: null;
+  guardianContext: GuardianRuntimeContext;
+  localFallback: true;
+}
+
+export type ActorTokenVerificationWithFallback =
+  | ActorTokenResult
+  | ActorTokenLocalFallbackResult
+  | ActorTokenError;
+
+/**
+ * Verify the actor token with fallback to local IPC identity resolution.
+ *
+ * When an actor token is present, the full verification pipeline runs.
+ * When absent AND the request originates from a loopback address, the
+ * request is treated as a trusted local client (e.g. CLI) and we fall
+ * back to `resolveLocalIpcGuardianContext()` which produces the same
+ * guardian context as the IPC pathway.
+ *
+ * Two conditions must BOTH be met for the local fallback:
+ * 1. No X-Forwarded-For header (rules out gateway-proxied requests).
+ * 2. The peer remote address is a loopback address (rules out LAN/container
+ *    connections when the runtime binds to 0.0.0.0).
+ *
+ * The peer address is checked via `server.requestIP(req)`.
+ *
+ * --- CLI compatibility note ---
+ *
+ * The local fallback is an intentional CLI compatibility path, not a
+ * security gap. The CLI currently sends only `Authorization: Bearer <token>`
+ * without `X-Actor-Token`. This fallback allows the CLI to function until
+ * it is migrated to actor tokens in a future milestone.
+ *
+ * The fallback is gated by three conditions that together ensure only
+ * genuinely local connections receive guardian identity:
+ *   (1) Absence of X-Forwarded-For header — the gateway always injects
+ *       this header when proxying, so its presence indicates a remote client.
+ *   (2) Loopback origin check — verifies the peer IP is 127.0.0.1/::1,
+ *       preventing LAN or container peers.
+ *   (3) Valid bearer authentication — already enforced upstream by the
+ *       HTTP server's auth gate before this function is called.
+ *
+ * Once the CLI adopts actor tokens, this fallback can be removed.
+ */
+export function verifyHttpActorTokenWithLocalFallback(
+  req: Request,
+  server: ServerWithRequestIP,
+): ActorTokenVerificationWithFallback {
+  const rawToken = extractActorToken(req);
+
+  // If an actor token is present, use the strict verification pipeline.
+  if (rawToken) {
+    return verifyHttpActorToken(req);
+  }
+
+  // Gate the local fallback on provably-local origin. The gateway runtime
+  // proxy always injects X-Forwarded-For with the real client IP when
+  // forwarding requests. Direct local connections (CLI, macOS app) never
+  // set this header. If X-Forwarded-For is present, the request was
+  // proxied through the gateway on behalf of a potentially remote client
+  // and must not receive local guardian identity.
+  if (req.headers.get('x-forwarded-for')) {
+    log.warn('Rejecting local identity fallback: request has X-Forwarded-For (proxied through gateway)');
+    return {
+      ok: false,
+      status: 401,
+      message: 'Missing X-Actor-Token header. Proxied requests require actor identity.',
+    };
+  }
+
+  // Verify the peer address is actually loopback. This prevents LAN or
+  // container peers from receiving local guardian identity when the
+  // runtime binds to 0.0.0.0.
+  const peerIp = server.requestIP(req)?.address;
+  if (!peerIp || !LOOPBACK_ADDRESSES.has(peerIp)) {
+    log.warn({ peerIp }, 'Rejecting local identity fallback: peer is not loopback');
+    return {
+      ok: false,
+      status: 401,
+      message: 'Missing X-Actor-Token header. Non-loopback requests require actor identity.',
+    };
+  }
+
+  // No actor token, no forwarding header, and the peer is on loopback
+  // — this is a direct local connection that passed bearer auth at the
+  // HTTP server layer. Resolve identity the same way as IPC.
+  log.debug('No actor token present on direct local request; using local IPC identity fallback');
+  const guardianContext = resolveLocalIpcGuardianContext('vellum');
+  return {
+    ok: true,
+    claims: null,
+    guardianContext,
+    localFallback: true,
+  };
+}
+
+/**
+ * Check whether the local fallback identity is the bound guardian.
+ *
+ * When no actor token is present (local fallback), the local user is
+ * treated as the guardian of their own machine — equivalent to IPC.
+ * This returns true when either the resolved trust class is 'guardian'
+ * or no vellum binding exists yet (pre-bootstrap).
+ */
+export function isLocalFallbackBoundGuardian(): boolean {
+  const guardianContext = resolveLocalIpcGuardianContext('vellum');
+  return guardianContext.trustClass === 'guardian';
+}

package/src/runtime/middleware/twilio-validation.ts

@@ -12,12 +12,10 @@ import { httpError } from '../http-errors.js';
 const log = getLogger('runtime-http');
 
 /**
- * Regex to extract the Twilio webhook subpath from both top-level and
- * assistant-scoped route shapes:
+ * Regex to extract the Twilio webhook subpath:
  *   /v1/calls/twilio/<subpath>
- *   /v1/assistants/<id>/calls/twilio/<subpath>
  */
-export const TWILIO_WEBHOOK_RE = /^\/v1\/(?:assistants\/[^/]+\/)?calls\/twilio\/(.+)$/;
+export const TWILIO_WEBHOOK_RE = /^\/v1\/calls\/twilio\/(.+)$/;
 
 /**
  * Gateway-compatible Twilio webhook paths:

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

@@ -3,20 +3,77 @@
  *
  * These endpoints resolve pending confirmations, secrets, and trust rules
  * by requestId — orthogonal to message sending.
+ *
+ * All approval endpoints require a valid actor token via the X-Actor-Token
+ * header (with local CLI fallback). Guardian decisions additionally verify
+ * that the actor is the bound guardian.
  */
 import { getConversationByKey } from '../../memory/conversation-key-store.js';
 import { addRule } from '../../permissions/trust-store.js';
 import { getTool } from '../../tools/registry.js';
 import { getLogger } from '../../util/logger.js';
 import { httpError } from '../http-errors.js';
+import {
+  isActorBoundGuardian,
+  isLocalFallbackBoundGuardian,
+  type ServerWithRequestIP,
+  verifyHttpActorTokenWithLocalFallback,
+} from '../middleware/actor-token.js';
 import * as pendingInteractions from '../pending-interactions.js';
 
 const log = getLogger('approval-routes');
 
+/**
+ * Verify the actor token from the request with local fallback.
+ * Returns an error Response if verification fails, or null if
+ * the actor is authenticated (via actor token or local identity).
+ */
+function requireActorToken(req: Request, server: ServerWithRequestIP): Response | null {
+  const result = verifyHttpActorTokenWithLocalFallback(req, server);
+  if (!result.ok) {
+    return httpError(
+      result.status === 401 ? 'UNAUTHORIZED' : 'FORBIDDEN',
+      result.message,
+      result.status,
+    );
+  }
+  return null;
+}
+
+/**
+ * Verify the actor token and confirm the actor is the bound guardian.
+ * When no actor token is present (bearer-authenticated local client),
+ * falls back to local IPC identity resolution and checks the local
+ * identity is the bound guardian.
+ */
+function requireBoundGuardian(req: Request, server: ServerWithRequestIP): Response | null {
+  const result = verifyHttpActorTokenWithLocalFallback(req, server);
+  if (!result.ok) {
+    return httpError(
+      result.status === 401 ? 'UNAUTHORIZED' : 'FORBIDDEN',
+      result.message,
+      result.status,
+    );
+  }
+  // For actor-token-authenticated requests, check the token's identity.
+  // For local fallback (bearer-auth only), check the local identity.
+  const isBoundGuardian = result.claims
+    ? isActorBoundGuardian(result.claims)
+    : isLocalFallbackBoundGuardian();
+  if (!isBoundGuardian) {
+    return httpError('FORBIDDEN', 'Actor is not the bound guardian for this channel', 403);
+  }
+  return null;
+}
+
 /**
  * POST /v1/confirm — resolve a pending confirmation by requestId.
+ * Requires a valid actor token (guardian-bound).
  */
-export async function handleConfirm(req: Request): Promise<Response> {
+export async function handleConfirm(req: Request, server: ServerWithRequestIP): Promise<Response> {
+  const authError = requireBoundGuardian(req, server);
+  if (authError) return authError;
+
   const body = await req.json() as {
     requestId?: string;
     decision?: string;
@@ -37,14 +94,20 @@ export async function handleConfirm(req: Request): Promise<Response> {
     return httpError('NOT_FOUND', 'No pending interaction found for this requestId', 404);
   }
 
-  interaction.session.handleConfirmationResponse(requestId, decision);
+  interaction.session.handleConfirmationResponse(requestId, decision, undefined, undefined, undefined, {
+    source: 'button',
+  });
   return Response.json({ accepted: true });
 }
 
 /**
  * POST /v1/secret — resolve a pending secret request by requestId.
+ * Requires a valid actor token (guardian-bound).
  */
-export async function handleSecret(req: Request): Promise<Response> {
+export async function handleSecret(req: Request, server: ServerWithRequestIP): Promise<Response> {
+  const authError = requireBoundGuardian(req, server);
+  if (authError) return authError;
+
   const body = await req.json() as {
     requestId?: string;
     value?: string;
@@ -76,13 +139,17 @@ export async function handleSecret(req: Request): Promise<Response> {
 
 /**
  * POST /v1/trust-rules — add a trust rule for a pending confirmation.
+ * Requires a valid actor token (guardian-bound).
  *
  * 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): Promise<Response> {
+export async function handleTrustRule(req: Request, server: ServerWithRequestIP): Promise<Response> {
+  const authError = requireBoundGuardian(req, server);
+  if (authError) return authError;
+
   const body = await req.json() as {
     requestId?: string;
     pattern?: string;
@@ -130,9 +197,14 @@ export async function handleTrustRule(req: Request): Promise<Response> {
     return httpError('FORBIDDEN', 'pattern does not match any server-provided allowlist option', 403);
   }
 
-  // Validate scope against server-provided scope options
+  // 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.includes(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);
   }
 
@@ -155,12 +227,15 @@ export async function handleTrustRule(req: Request): Promise<Response> {
 
 /**
  * GET /v1/pending-interactions?conversationKey=...
+ * Requires a valid actor token.
  *
  * 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): Response {
+export function handleListPendingInteractions(url: URL, req: Request, server: ServerWithRequestIP): Response {
+  const authError = requireActorToken(req, server);
+  if (authError) return authError;
   const conversationKey = url.searchParams.get('conversationKey');
   const conversationId = url.searchParams.get('conversationId');