@vellumai/assistant 0.3.14 → 0.3.16

package/src/runtime/ingress-service.ts

@@ -0,0 +1,237 @@
+/**
+ * Shared business logic for ingress member and invite management.
+ *
+ * Extracted from the IPC handlers in daemon/handlers/config-inbox.ts so that
+ * both the HTTP routes and the IPC handlers call the same logic.
+ */
+
+import {
+  createInvite,
+  type IngressInvite,
+  type InviteStatus,
+  listInvites,
+  redeemInvite,
+  revokeInvite,
+} from '../memory/ingress-invite-store.js';
+import {
+  blockMember,
+  type IngressMember,
+  listMembers,
+  type MemberPolicy,
+  type MemberStatus,
+  revokeMember,
+  upsertMember,
+} from '../memory/ingress-member-store.js';
+
+// ---------------------------------------------------------------------------
+// Response shapes — used by both HTTP routes and IPC handlers
+// ---------------------------------------------------------------------------
+
+export interface InviteResponseData {
+  id: string;
+  sourceChannel: string;
+  token?: string;
+  tokenHash: string;
+  maxUses: number;
+  useCount: number;
+  expiresAt: number | null;
+  status: string;
+  note?: string;
+  createdAt: number;
+}
+
+export interface MemberResponseData {
+  id: string;
+  sourceChannel: string;
+  externalUserId?: string;
+  externalChatId?: string;
+  displayName?: string;
+  username?: string;
+  status: string;
+  policy: string;
+  lastSeenAt?: number;
+  createdAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// Mappers
+// ---------------------------------------------------------------------------
+
+function inviteToResponse(inv: IngressInvite, rawToken?: string): InviteResponseData {
+  return {
+    id: inv.id,
+    sourceChannel: inv.sourceChannel,
+    ...(rawToken ? { token: rawToken } : {}),
+    tokenHash: inv.tokenHash,
+    maxUses: inv.maxUses,
+    useCount: inv.useCount,
+    expiresAt: inv.expiresAt,
+    status: inv.status,
+    note: inv.note ?? undefined,
+    createdAt: inv.createdAt,
+  };
+}
+
+export function memberToResponse(m: IngressMember): MemberResponseData {
+  return {
+    id: m.id,
+    sourceChannel: m.sourceChannel,
+    externalUserId: m.externalUserId ?? undefined,
+    externalChatId: m.externalChatId ?? undefined,
+    displayName: m.displayName ?? undefined,
+    username: m.username ?? undefined,
+    status: m.status,
+    policy: m.policy,
+    lastSeenAt: m.lastSeenAt ?? undefined,
+    createdAt: m.createdAt,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Result types
+// ---------------------------------------------------------------------------
+
+export type IngressResult<T> =
+  | { ok: true; data: T }
+  | { ok: false; error: string };
+
+// ---------------------------------------------------------------------------
+// Invite operations
+// ---------------------------------------------------------------------------
+
+export function createIngressInvite(params: {
+  sourceChannel?: string;
+  note?: string;
+  maxUses?: number;
+  expiresInMs?: number;
+}): IngressResult<InviteResponseData> {
+  if (!params.sourceChannel) {
+    return { ok: false, error: 'sourceChannel is required for create' };
+  }
+  const { invite, rawToken } = createInvite({
+    sourceChannel: params.sourceChannel,
+    note: params.note,
+    maxUses: params.maxUses,
+    expiresInMs: params.expiresInMs,
+  });
+  return { ok: true, data: inviteToResponse(invite, rawToken) };
+}
+
+export function listIngressInvites(params: {
+  sourceChannel?: string;
+  status?: string;
+}): IngressResult<InviteResponseData[]> {
+  const invites = listInvites({
+    sourceChannel: params.sourceChannel,
+    status: params.status as InviteStatus | undefined,
+  });
+  return {
+    ok: true,
+    data: invites.map((inv) => inviteToResponse(inv)),
+  };
+}
+
+export function revokeIngressInvite(inviteId?: string): IngressResult<InviteResponseData> {
+  if (!inviteId) {
+    return { ok: false, error: 'inviteId is required for revoke' };
+  }
+  const revoked = revokeInvite(inviteId);
+  if (!revoked) {
+    return { ok: false, error: 'Invite not found or already revoked' };
+  }
+  return { ok: true, data: inviteToResponse(revoked) };
+}
+
+export function redeemIngressInvite(params: {
+  token?: string;
+  externalUserId?: string;
+  externalChatId?: string;
+  sourceChannel?: string;
+}): IngressResult<InviteResponseData> {
+  if (!params.token) {
+    return { ok: false, error: 'token is required for redeem' };
+  }
+  const result = redeemInvite({
+    rawToken: params.token,
+    externalUserId: params.externalUserId,
+    externalChatId: params.externalChatId,
+    sourceChannel: params.sourceChannel,
+  });
+  if ('error' in result) {
+    return { ok: false, error: result.error };
+  }
+  return { ok: true, data: inviteToResponse(result.invite) };
+}
+
+// ---------------------------------------------------------------------------
+// Member operations
+// ---------------------------------------------------------------------------
+
+export function listIngressMembers(params: {
+  assistantId?: string;
+  sourceChannel?: string;
+  status?: string;
+  policy?: string;
+}): IngressResult<MemberResponseData[]> {
+  const members = listMembers({
+    assistantId: params.assistantId,
+    sourceChannel: params.sourceChannel,
+    status: params.status as MemberStatus | undefined,
+    policy: params.policy as MemberPolicy | undefined,
+  });
+  return {
+    ok: true,
+    data: members.map(memberToResponse),
+  };
+}
+
+export function upsertIngressMember(params: {
+  sourceChannel?: string;
+  externalUserId?: string;
+  externalChatId?: string;
+  displayName?: string;
+  username?: string;
+  policy?: string;
+  status?: string;
+  assistantId?: string;
+}): IngressResult<MemberResponseData> {
+  if (!params.sourceChannel) {
+    return { ok: false, error: 'sourceChannel is required for upsert' };
+  }
+  if (!params.externalUserId && !params.externalChatId) {
+    return { ok: false, error: 'At least one of externalUserId or externalChatId is required for upsert' };
+  }
+  const member = upsertMember({
+    assistantId: params.assistantId,
+    sourceChannel: params.sourceChannel,
+    externalUserId: params.externalUserId,
+    externalChatId: params.externalChatId,
+    displayName: params.displayName,
+    username: params.username,
+    policy: params.policy as MemberPolicy | undefined,
+    status: params.status as MemberStatus | undefined,
+  });
+  return { ok: true, data: memberToResponse(member) };
+}
+
+export function revokeIngressMember(memberId?: string, reason?: string): IngressResult<MemberResponseData> {
+  if (!memberId) {
+    return { ok: false, error: 'memberId is required for revoke' };
+  }
+  const revoked = revokeMember(memberId, reason);
+  if (!revoked) {
+    return { ok: false, error: 'Member not found or cannot be revoked' };
+  }
+  return { ok: true, data: memberToResponse(revoked) };
+}
+
+export function blockIngressMember(memberId?: string, reason?: string): IngressResult<MemberResponseData> {
+  if (!memberId) {
+    return { ok: false, error: 'memberId is required for block' };
+  }
+  const blocked = blockMember(memberId, reason);
+  if (!blocked) {
+    return { ok: false, error: 'Member not found or already blocked' };
+  }
+  return { ok: true, data: memberToResponse(blocked) };
+}

package/src/runtime/middleware/error-handler.ts

@@ -4,6 +4,7 @@
 
 import { ConfigError, IngressBlockedError } from '../../util/errors.js';
 import { getLogger } from '../../util/logger.js';
+import { httpError } from '../http-errors.js';
 
 const log = getLogger('runtime-http');
 
@@ -20,14 +21,14 @@ export async function withErrorHandling(
   } catch (err) {
     if (err instanceof IngressBlockedError) {
       log.warn({ endpoint, detectedTypes: err.detectedTypes }, 'Blocked HTTP request containing secrets');
-      return Response.json({ error: err.message, code: err.code }, { status: 422 });
+      return httpError('UNPROCESSABLE_ENTITY', err.message, 422);
     }
     if (err instanceof ConfigError) {
       log.warn({ err, endpoint }, 'Runtime HTTP config error');
-      return Response.json({ error: err.message, code: err.code }, { status: 422 });
+      return httpError('UNPROCESSABLE_ENTITY', err.message, 422);
     }
     log.error({ err, endpoint }, 'Runtime HTTP handler error');
     const message = err instanceof Error ? err.message : 'Internal server error';
-    return Response.json({ error: message }, { status: 500 });
+    return httpError('INTERNAL_ERROR', message, 500);
   }
 }

package/src/runtime/middleware/rate-limiter.ts

@@ -0,0 +1,160 @@
+// Per-client-IP sliding-window rate limiter for /v1/* API endpoints.
+// Tracks request counts per key and returns 429 when the limit is exceeded.
+// Follows the same sliding-window pattern as gateway/src/auth-rate-limiter.ts.
+
+import type { HttpErrorResponse } from '../http-errors.js';
+import { isPrivateAddress } from './auth.js';
+
+const DEFAULT_MAX_REQUESTS = 60;
+const DEFAULT_WINDOW_MS = 60_000; // 60 seconds
+const MAX_TRACKED_TOKENS = 10_000;
+
+// Lower limit for unauthenticated (IP-based) requests to reduce abuse surface.
+const DEFAULT_IP_MAX_REQUESTS = 20;
+const DEFAULT_IP_WINDOW_MS = 60_000;
+const MAX_TRACKED_IPS = 50_000;
+
+export class TokenRateLimiter {
+  private requests = new Map<string, number[]>();
+  private readonly maxRequests: number;
+  private readonly windowMs: number;
+  private readonly maxTrackedKeys: number;
+
+  constructor(
+    maxRequests = DEFAULT_MAX_REQUESTS,
+    windowMs = DEFAULT_WINDOW_MS,
+    maxTrackedKeys = MAX_TRACKED_TOKENS,
+  ) {
+    this.maxRequests = maxRequests;
+    this.windowMs = windowMs;
+    this.maxTrackedKeys = maxTrackedKeys;
+  }
+
+  /**
+   * Check whether the request should be allowed and record it.
+   * Returns rate limit metadata for response headers.
+   */
+  check(key: string): RateLimitResult {
+    const now = Date.now();
+    let timestamps = this.requests.get(key);
+
+    if (!timestamps) {
+      if (this.requests.size >= this.maxTrackedKeys) {
+        this.evictStale(now);
+        if (this.requests.size >= this.maxTrackedKeys) {
+          const oldest = this.requests.keys().next().value;
+          if (oldest !== undefined) this.requests.delete(oldest);
+        }
+      }
+      timestamps = [];
+      this.requests.set(key, timestamps);
+    }
+
+    const cutoff = now - this.windowMs;
+
+    // Remove expired timestamps from the front
+    while (timestamps.length > 0 && timestamps[0] <= cutoff) {
+      timestamps.shift();
+    }
+
+    const remaining = Math.max(0, this.maxRequests - timestamps.length);
+    const resetAt = timestamps.length > 0
+      ? Math.ceil((timestamps[0] + this.windowMs) / 1000)
+      : Math.ceil((now + this.windowMs) / 1000);
+
+    if (timestamps.length >= this.maxRequests) {
+      return {
+        allowed: false,
+        limit: this.maxRequests,
+        remaining: 0,
+        resetAt,
+      };
+    }
+
+    timestamps.push(now);
+
+    return {
+      allowed: true,
+      limit: this.maxRequests,
+      remaining: remaining - 1,
+      resetAt,
+    };
+  }
+
+  private evictStale(now: number): void {
+    const cutoff = now - this.windowMs;
+    for (const [key, timestamps] of this.requests) {
+      while (timestamps.length > 0 && timestamps[0] <= cutoff) {
+        timestamps.shift();
+      }
+      if (timestamps.length === 0) {
+        this.requests.delete(key);
+      }
+    }
+  }
+}
+
+export interface RateLimitResult {
+  allowed: boolean;
+  limit: number;
+  remaining: number;
+  /** Unix timestamp (seconds) when the window resets. */
+  resetAt: number;
+}
+
+/** Build standard rate limit headers from a check result. */
+export function rateLimitHeaders(result: RateLimitResult): Record<string, string> {
+  return {
+    'X-RateLimit-Limit': String(result.limit),
+    'X-RateLimit-Remaining': String(result.remaining),
+    'X-RateLimit-Reset': String(result.resetAt),
+  };
+}
+
+/** Return a 429 response with rate limit headers and a Retry-After hint. */
+export function rateLimitResponse(result: RateLimitResult): Response {
+  const retryAfter = Math.max(1, result.resetAt - Math.ceil(Date.now() / 1000));
+  const body: HttpErrorResponse = {
+    error: { code: 'RATE_LIMITED', message: 'Too Many Requests' },
+  };
+  return Response.json(body, {
+    status: 429,
+    headers: {
+      ...rateLimitHeaders(result),
+      'Retry-After': String(retryAfter),
+    },
+  });
+}
+
+/** Singleton rate limiter for authenticated /v1/* requests (per-client-IP). */
+export const apiRateLimiter = new TokenRateLimiter();
+
+/** Singleton rate limiter for unauthenticated requests (per-IP, lower limits). */
+export const ipRateLimiter = new TokenRateLimiter(DEFAULT_IP_MAX_REQUESTS, DEFAULT_IP_WINDOW_MS, MAX_TRACKED_IPS);
+
+/**
+ * Extract the client IP from a request. Only trusts proxy headers
+ * (X-Forwarded-For, X-Real-IP) when the peer IP is loopback or private,
+ * meaning the request arrived via the gateway. Direct connections from
+ * external clients use the peer IP, preventing header spoofing.
+ */
+export function extractClientIp(
+  req: Request,
+  server: { requestIP(req: Request): { address: string } | null },
+): string {
+  const peerIp = server.requestIP(req)?.address ?? '0.0.0.0';
+
+  if (isPrivateAddress(peerIp)) {
+    const forwarded = req.headers.get('x-forwarded-for');
+    if (forwarded) {
+      const first = forwarded.split(',')[0].trim();
+      if (first) return first;
+    }
+
+    const realIp = req.headers.get('x-real-ip');
+    if (realIp) return realIp.trim();
+  }
+
+  return peerIp;
+}
+

package/src/runtime/middleware/request-logger.ts

@@ -0,0 +1,71 @@
+/**
+ * HTTP request/response logging middleware.
+ *
+ * Logs method, path, status, and latency for every request to aid
+ * debugging client issues. Uses structured Pino logging.
+ */
+
+import { getLogger } from '../../util/logger.js';
+
+const log = getLogger('http-request');
+
+/**
+ * Wrap a request handler to log request metadata and response timing.
+ *
+ * The handler may return `undefined` for WebSocket upgrades (Bun consumes
+ * the request and there is no HTTP response to send).
+ */
+export async function withRequestLogging(
+  req: Request,
+  handler: () => Promise<Response>,
+): Promise<Response> {
+  const start = performance.now();
+  const url = new URL(req.url);
+  const method = req.method;
+  const path = url.pathname;
+
+  let response: Response;
+  try {
+    response = await handler();
+  } catch (err) {
+    const latencyMs = Math.round(performance.now() - start);
+    log.error(
+      { method, path, latencyMs, err },
+      `${method} ${path} -> error (${latencyMs}ms)`,
+    );
+    throw err;
+  }
+
+  const latencyMs = Math.round(performance.now() - start);
+
+  // WebSocket upgrades return undefined — log and pass through without
+  // dereferencing response properties.
+  if (!response) {
+    log.info(
+      { method, path, latencyMs },
+      `${method} ${path} -> ws-upgrade (${latencyMs}ms)`,
+    );
+    return response;
+  }
+
+  const status = response.status;
+
+  const logData = {
+    method,
+    path,
+    status,
+    latencyMs,
+    contentType: req.headers.get('content-type') ?? undefined,
+    userAgent: req.headers.get('user-agent') ?? undefined,
+  };
+
+  if (status >= 500) {
+    log.error(logData, `${method} ${path} -> ${status} (${latencyMs}ms)`);
+  } else if (status >= 400) {
+    log.warn(logData, `${method} ${path} -> ${status} (${latencyMs}ms)`);
+  } else {
+    log.info(logData, `${method} ${path} -> ${status} (${latencyMs}ms)`);
+  }
+
+  return response;
+}

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

@@ -7,6 +7,7 @@ import { isTwilioWebhookValidationDisabled } from '../../config/env.js';
 import { loadConfig } from '../../config/loader.js';
 import { getPublicBaseUrl } from '../../inbound/public-ingress-urls.js';
 import { getLogger } from '../../util/logger.js';
+import { httpError } from '../http-errors.js';
 
 const log = getLogger('runtime-http');
 
@@ -68,13 +69,13 @@ export async function validateTwilioWebhook(
   // Fail-closed: reject if no auth token is configured
   if (!authToken) {
     log.error('Twilio auth token not configured — rejecting webhook request (fail-closed)');
-    return Response.json({ error: 'Forbidden' }, { status: 403 });
+    return httpError('FORBIDDEN', 'Forbidden', 403);
   }
 
   const signature = req.headers.get('x-twilio-signature');
   if (!signature) {
     log.warn('Twilio webhook request missing X-Twilio-Signature header');
-    return Response.json({ error: 'Forbidden' }, { status: 403 });
+    return httpError('FORBIDDEN', 'Forbidden', 403);
   }
 
   // Parse form-urlencoded body into key-value params for signature computation
@@ -85,9 +86,9 @@ export async function validateTwilioWebhook(
   }
 
   // Reconstruct the public-facing URL that Twilio signed against.
-  // Behind proxies/gateways, req.url is the local server URL (e.g.
-  // http://127.0.0.1:7821/...) which differs from the public URL Twilio
-  // used to compute the HMAC-SHA1 signature.
+  // Behind proxies/gateways, req.url is the local runtime URL which
+  // differs from the public URL Twilio used to compute the HMAC-SHA1
+  // signature.
   let publicBaseUrl: string | undefined;
   try {
     publicBaseUrl = getPublicBaseUrl(loadConfig());
@@ -108,7 +109,7 @@ export async function validateTwilioWebhook(
 
   if (!isValid) {
     log.warn('Twilio webhook signature validation failed');
-    return Response.json({ error: 'Forbidden' }, { status: 403 });
+    return httpError('FORBIDDEN', 'Forbidden', 403);
   }
 
   return { body: rawBody };

package/src/runtime/pending-interactions.ts

@@ -67,6 +67,18 @@ export function getByConversation(conversationId: string): Array<{ requestId: st
   return results;
 }
 
+/**
+ * Remove all pending interactions for a given session.
+ * Used when auto-denying all pending confirmations (e.g. new user message).
+ */
+export function removeBySession(session: Session): void {
+  for (const [requestId, interaction] of pending) {
+    if (interaction.session === session) {
+      pending.delete(requestId);
+    }
+  }
+}
+
 /** Clear all pending interactions. Useful for testing. */
 export function clear(): void {
   pending.clear();