@vellumai/assistant 0.4.6 → 0.4.7

package/src/runtime/actor-refresh-token-store.ts

@@ -0,0 +1,157 @@
+/**
+ * Hash-only refresh token persistence.
+ *
+ * Stores SHA-256 hash of each refresh token with family tracking,
+ * device binding, and dual expiry (absolute + inactivity).
+ */
+
+import { and, eq } from 'drizzle-orm';
+import { v4 as uuid } from 'uuid';
+
+import { getDb } from '../memory/db.js';
+import { rawChanges } from '../memory/raw-query.js';
+import { actorRefreshTokenRecords } from '../memory/schema.js';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('actor-refresh-token-store');
+
+export type RefreshTokenStatus = 'active' | 'rotated' | 'revoked';
+
+export interface RefreshTokenRecord {
+  id: string;
+  tokenHash: string;
+  familyId: string;
+  assistantId: string;
+  guardianPrincipalId: string;
+  hashedDeviceId: string;
+  platform: string;
+  status: RefreshTokenStatus;
+  issuedAt: number;
+  absoluteExpiresAt: number;
+  inactivityExpiresAt: number;
+  lastUsedAt: number | null;
+  createdAt: number;
+  updatedAt: number;
+}
+
+/** Create a new refresh token record (hash-only). */
+export function createRefreshTokenRecord(params: {
+  tokenHash: string;
+  familyId: string;
+  assistantId: string;
+  guardianPrincipalId: string;
+  hashedDeviceId: string;
+  platform: string;
+  issuedAt: number;
+  absoluteExpiresAt: number;
+  inactivityExpiresAt: number;
+}): RefreshTokenRecord {
+  const db = getDb();
+  const now = Date.now();
+  const id = uuid();
+
+  const row = {
+    id,
+    tokenHash: params.tokenHash,
+    familyId: params.familyId,
+    assistantId: params.assistantId,
+    guardianPrincipalId: params.guardianPrincipalId,
+    hashedDeviceId: params.hashedDeviceId,
+    platform: params.platform,
+    status: 'active' as const,
+    issuedAt: params.issuedAt,
+    absoluteExpiresAt: params.absoluteExpiresAt,
+    inactivityExpiresAt: params.inactivityExpiresAt,
+    lastUsedAt: null,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  db.insert(actorRefreshTokenRecords).values(row).run();
+  log.info({ id, familyId: params.familyId, platform: params.platform }, 'Refresh token record created');
+  return row;
+}
+
+/** Look up a refresh token record by hash (ANY status - needed for replay detection). */
+export function findByTokenHash(tokenHash: string): RefreshTokenRecord | null {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(actorRefreshTokenRecords)
+    .where(eq(actorRefreshTokenRecords.tokenHash, tokenHash))
+    .get();
+  return row ? rowToRecord(row) : null;
+}
+
+/**
+ * Atomically mark a refresh token as rotated (used successfully, replaced by a new one).
+ * Uses a single conditional UPDATE and checks the affected row count to ensure
+ * exactly one row transitioned from 'active' to 'rotated'. This prevents
+ * concurrent refresh requests from both succeeding (CAS semantics).
+ */
+export function markRotated(tokenHash: string): boolean {
+  const db = getDb();
+  const now = Date.now();
+  db.update(actorRefreshTokenRecords)
+    .set({ status: 'rotated', lastUsedAt: now, updatedAt: now })
+    .where(
+      and(
+        eq(actorRefreshTokenRecords.tokenHash, tokenHash),
+        eq(actorRefreshTokenRecords.status, 'active'),
+      ),
+    )
+    .run();
+  return rawChanges() > 0;
+}
+
+/** Revoke all tokens in a family (replay detection response). */
+export function revokeFamily(familyId: string): number {
+  const db = getDb();
+  const now = Date.now();
+  db.update(actorRefreshTokenRecords)
+    .set({ status: 'revoked', updatedAt: now })
+    .where(eq(actorRefreshTokenRecords.familyId, familyId))
+    .run();
+  return rawChanges();
+}
+
+/** Revoke all active refresh tokens for a device binding. */
+export function revokeByDeviceBinding(
+  assistantId: string,
+  guardianPrincipalId: string,
+  hashedDeviceId: string,
+): number {
+  const db = getDb();
+  const now = Date.now();
+  db.update(actorRefreshTokenRecords)
+    .set({ status: 'revoked', updatedAt: now })
+    .where(
+      and(
+        eq(actorRefreshTokenRecords.assistantId, assistantId),
+        eq(actorRefreshTokenRecords.guardianPrincipalId, guardianPrincipalId),
+        eq(actorRefreshTokenRecords.hashedDeviceId, hashedDeviceId),
+        eq(actorRefreshTokenRecords.status, 'active'),
+      ),
+    )
+    .run();
+  return rawChanges();
+}
+
+function rowToRecord(row: typeof actorRefreshTokenRecords.$inferSelect): RefreshTokenRecord {
+  return {
+    id: row.id,
+    tokenHash: row.tokenHash,
+    familyId: row.familyId,
+    assistantId: row.assistantId,
+    guardianPrincipalId: row.guardianPrincipalId,
+    hashedDeviceId: row.hashedDeviceId,
+    platform: row.platform,
+    status: row.status as RefreshTokenStatus,
+    issuedAt: row.issuedAt,
+    absoluteExpiresAt: row.absoluteExpiresAt,
+    inactivityExpiresAt: row.inactivityExpiresAt,
+    lastUsedAt: row.lastUsedAt,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}

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

@@ -143,14 +143,14 @@ export function hashToken(token: string): string {
 // Mint
 // ---------------------------------------------------------------------------
 
-/** Default TTL for actor tokens: 90 days in milliseconds. */
-const DEFAULT_TOKEN_TTL_MS = 90 * 24 * 60 * 60 * 1000;
+/** Default TTL for actor tokens: 30 days in milliseconds. */
+const DEFAULT_TOKEN_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 
 /**
  * Mint a new actor token.
  *
  * @param params Token claims (assistantId, platform, deviceId, guardianPrincipalId).
- * @param ttlMs  Optional TTL in milliseconds. Defaults to 90 days.
+ * @param ttlMs  Optional TTL in milliseconds. Defaults to 30 days.
  *               Pass `null` explicitly for a non-expiring token.
  * @returns The raw token, its hash, and the embedded claims.
  */

package/src/runtime/gateway-client.ts

@@ -1,3 +1,5 @@
+import { createHash } from 'node:crypto';
+
 import { getLogger } from '../util/logger.js';
 import type { ApprovalUIMetadata } from './channel-approval-types.js';
 import type { RuntimeAttachmentMetadata } from './http-types.js';
@@ -5,6 +7,13 @@ import type { RuntimeAttachmentMetadata } from './http-types.js';
 const log = getLogger('gateway-client');
 
 const DELIVERY_TIMEOUT_MS = 30_000;
+const MANAGED_OUTBOUND_SEND_PATH = '/v1/internal/managed-gateway/outbound-send/';
+const MANAGED_CALLBACK_TOKEN_HEADER = 'X-Managed-Gateway-Callback-Token';
+const MANAGED_IDEMPOTENCY_HEADER = 'X-Idempotency-Key';
+const MANAGED_OUTBOUND_MAX_ATTEMPTS = 3;
+const MANAGED_OUTBOUND_RETRY_BASE_MS = 150;
+const SMS_ATTACHMENTS_FALLBACK_TEXT =
+  'I have a media attachment to share, but SMS currently supports text only.';
 
 export interface ChannelReplyPayload {
   chatId: string;
@@ -15,11 +24,26 @@ export interface ChannelReplyPayload {
   chatAction?: 'typing';
 }
 
+interface ManagedOutboundCallbackContext {
+  requestUrl: string;
+  routeId: string;
+  assistantId: string;
+  sourceChannel: 'sms' | 'voice';
+  sourceUpdateId?: string;
+  callbackToken?: string;
+}
+
 export async function deliverChannelReply(
   callbackUrl: string,
   payload: ChannelReplyPayload,
   bearerToken?: string,
 ): Promise<void> {
+  const managedCallback = parseManagedOutboundCallback(callbackUrl);
+  if (managedCallback) {
+    await deliverManagedOutboundReply(managedCallback, payload, bearerToken);
+    return;
+  }
+
   const headers: Record<string, string> = { 'Content-Type': 'application/json' };
   if (bearerToken) {
     headers['Authorization'] = `Bearer ${bearerToken}`;
@@ -51,6 +75,221 @@ export async function deliverChannelReply(
   }
 }
 
+function parseManagedOutboundCallback(
+  callbackUrl: string,
+): ManagedOutboundCallbackContext | null {
+  let parsed: URL;
+  try {
+    parsed = new URL(callbackUrl);
+  } catch {
+    return null;
+  }
+
+  const normalizedPath = parsed.pathname.endsWith('/')
+    ? parsed.pathname
+    : `${parsed.pathname}/`;
+  if (normalizedPath !== MANAGED_OUTBOUND_SEND_PATH) {
+    return null;
+  }
+
+  const routeId = parsed.searchParams.get('route_id')?.trim();
+  const assistantId = parsed.searchParams.get('assistant_id')?.trim();
+  const sourceChannel = parsed.searchParams.get('source_channel')?.trim();
+
+  if (!routeId || !assistantId || (sourceChannel !== 'sms' && sourceChannel !== 'voice')) {
+    throw new Error(
+      'Managed outbound callback URL is missing required route_id, assistant_id, or source_channel.',
+    );
+  }
+
+  const sourceUpdateId = parsed.searchParams.get('source_update_id')?.trim();
+  const callbackToken = parsed.searchParams.get('callback_token')?.trim();
+
+  parsed.searchParams.delete('route_id');
+  parsed.searchParams.delete('assistant_id');
+  parsed.searchParams.delete('source_channel');
+  parsed.searchParams.delete('source_update_id');
+  parsed.searchParams.delete('callback_token');
+
+  return {
+    requestUrl: parsed.toString(),
+    routeId,
+    assistantId,
+    sourceChannel,
+    sourceUpdateId,
+    callbackToken,
+  };
+}
+
+async function deliverManagedOutboundReply(
+  callback: ManagedOutboundCallbackContext,
+  payload: ChannelReplyPayload,
+  bearerToken?: string,
+): Promise<void> {
+  const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+  if (callback.callbackToken) {
+    headers[MANAGED_CALLBACK_TOKEN_HEADER] = callback.callbackToken;
+  } else if (bearerToken) {
+    headers.Authorization = `Bearer ${bearerToken}`;
+  }
+
+  const hasAttachments = Array.isArray(payload.attachments) && payload.attachments.length > 0;
+  const text = payload.approval?.plainTextFallback ?? payload.text;
+  const normalizedText =
+    typeof text === 'string' && text.trim().length > 0
+      ? text
+      : hasAttachments
+        ? SMS_ATTACHMENTS_FALLBACK_TEXT
+        : '';
+  if (!normalizedText) {
+    throw new Error('Managed outbound delivery requires text or plainTextFallback.');
+  }
+
+  const requestId = buildManagedOutboundRequestId(callback, payload, normalizedText);
+  headers[MANAGED_IDEMPOTENCY_HEADER] = requestId;
+
+  const requestBody = JSON.stringify({
+    route_id: callback.routeId,
+    assistant_id: callback.assistantId,
+    normalized_send: {
+      version: 'v1',
+      sourceChannel: callback.sourceChannel,
+      message: {
+        to: payload.chatId,
+        content: normalizedText,
+        externalMessageId: requestId,
+      },
+      source: {
+        requestId: requestId,
+      },
+      raw: {
+        chatId: payload.chatId,
+        text: payload.text ?? null,
+        assistantId: payload.assistantId ?? null,
+        chatAction: payload.chatAction ?? null,
+        hasAttachments,
+        sourceUpdateId: callback.sourceUpdateId ?? null,
+      },
+    },
+  });
+
+  for (let attempt = 1; attempt <= MANAGED_OUTBOUND_MAX_ATTEMPTS; attempt++) {
+    let response: Response;
+    try {
+      response = await fetch(callback.requestUrl, {
+        method: 'POST',
+        headers,
+        body: requestBody,
+        signal: AbortSignal.timeout(DELIVERY_TIMEOUT_MS),
+      });
+    } catch (error) {
+      if (attempt < MANAGED_OUTBOUND_MAX_ATTEMPTS) {
+        const retryDelayMs = MANAGED_OUTBOUND_RETRY_BASE_MS * attempt;
+        log.warn(
+          {
+            callbackUrl: callback.requestUrl,
+            routeId: callback.routeId,
+            requestId,
+            chatId: payload.chatId,
+            attempt,
+            retryDelayMs,
+            error,
+          },
+          'Managed outbound delivery attempt failed before response; retrying',
+        );
+        await sleep(retryDelayMs);
+        continue;
+      }
+      throw error;
+    }
+
+    if (response.ok) {
+      log.info(
+        {
+          routeId: callback.routeId,
+          assistantId: callback.assistantId,
+          sourceChannel: callback.sourceChannel,
+          requestId,
+          chatId: payload.chatId,
+          attempt,
+        },
+        'Managed outbound delivery accepted',
+      );
+      return;
+    }
+
+    const responseBody = await response.text().catch(() => '<unreadable>');
+    if (response.status >= 500 && response.status < 600 && attempt < MANAGED_OUTBOUND_MAX_ATTEMPTS) {
+      const retryDelayMs = MANAGED_OUTBOUND_RETRY_BASE_MS * attempt;
+      log.warn(
+        {
+          callbackUrl: callback.requestUrl,
+          routeId: callback.routeId,
+          requestId,
+          chatId: payload.chatId,
+          attempt,
+          status: response.status,
+          responseBody,
+          retryDelayMs,
+        },
+        'Managed outbound delivery got retriable upstream response; retrying',
+      );
+      await sleep(retryDelayMs);
+      continue;
+    }
+
+    log.error(
+      {
+        status: response.status,
+        body: responseBody,
+        callbackUrl: callback.requestUrl,
+        routeId: callback.routeId,
+        requestId,
+        chatId: payload.chatId,
+        attempt,
+      },
+      'Managed outbound delivery failed',
+    );
+    throw new Error(`Managed outbound delivery failed (${response.status}): ${responseBody}`);
+  }
+}
+
+function buildManagedOutboundRequestId(
+  callback: ManagedOutboundCallbackContext,
+  payload: ChannelReplyPayload,
+  normalizedText: string,
+): string {
+  const bodyMaterial = JSON.stringify({
+    callback: {
+      routeId: callback.routeId,
+      assistantId: callback.assistantId,
+      sourceChannel: callback.sourceChannel,
+      sourceUpdateId: callback.sourceUpdateId ?? null,
+    },
+    payload: {
+      chatId: payload.chatId,
+      text: normalizedText,
+      assistantId: payload.assistantId ?? null,
+      chatAction: payload.chatAction ?? null,
+      hasAttachments: Array.isArray(payload.attachments) && payload.attachments.length > 0,
+      approvalRequestId: payload.approval?.requestId ?? null,
+      approvalActions: payload.approval?.actions.map(action => action.id) ?? null,
+    },
+  });
+
+  const digest = createHash('sha256')
+    .update(bodyMaterial)
+    .digest('hex')
+    .slice(0, 40);
+  return `mgw-send-${digest}`;
+}
+
+async function sleep(ms: number): Promise<void> {
+  await new Promise(resolve => {
+    setTimeout(resolve, ms);
+  });
+}
+
 /**
  * Deliver an approval prompt (text + inline keyboard metadata) to the
  * gateway so it can render the approval UI in the channel.

package/src/runtime/http-server.ts

@@ -132,6 +132,7 @@ import {
   handleGuardianActionsPending,
 } from './routes/guardian-action-routes.js';
 import { handleGuardianBootstrap } from './routes/guardian-bootstrap-routes.js';
+import { handleGuardianRefresh } from './routes/guardian-refresh-routes.js';
 import { handleGetIdentity,handleHealth } from './routes/identity-routes.js';
 import {
   handleBlockMember,
@@ -783,6 +784,7 @@ export class RuntimeHttpServer {
 
       // Guardian vellum channel bootstrap
       if (endpoint === 'integrations/guardian/vellum/bootstrap' && req.method === 'POST') return await handleGuardianBootstrap(req, server);
+      if (endpoint === 'integrations/guardian/vellum/refresh' && req.method === 'POST') return await handleGuardianRefresh(req);
 
       // Integrations — Twilio config
       if (endpoint === 'integrations/twilio/config' && req.method === 'GET') return handleGetTwilioConfig();

package/src/runtime/routes/guardian-bootstrap-routes.ts

@@ -18,11 +18,7 @@ import {
   getActiveBinding,
 } from '../../memory/guardian-bindings.js';
 import { getLogger } from '../../util/logger.js';
-import { mintActorToken } from '../actor-token-service.js';
-import {
-  createActorTokenRecord,
-  revokeByDeviceBinding,
-} from '../actor-token-store.js';
+import { mintCredentialPair } from '../actor-refresh-token-service.js';
 import { DAEMON_INTERNAL_ASSISTANT_ID } from '../assistant-scope.js';
 import { httpError } from '../http-errors.js';
 import type { ServerWithRequestIP } from '../middleware/actor-token.js';
@@ -98,35 +94,21 @@ export async function handleGuardianBootstrap(req: Request, server: ServerWithRe
       return httpError('BAD_REQUEST', 'Missing required fields: platform, deviceId', 400);
     }
 
-    if (platform !== 'macos') {
-      return httpError('BAD_REQUEST', 'Invalid platform. Bootstrap is macOS-only; iOS uses QR pairing.', 400);
+    if (platform !== 'macos' && platform !== 'cli') {
+      return httpError('BAD_REQUEST', 'Invalid platform. Bootstrap is macOS/CLI-only; iOS uses QR pairing.', 400);
     }
 
     const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
     const { guardianPrincipalId, isNew } = ensureGuardianPrincipal(assistantId);
     const hashedDeviceId = hashDeviceId(deviceId);
 
-    // Revoke any existing active tokens for this device binding
-    // so we maintain one-active-token-per-device
-    revokeByDeviceBinding(assistantId, guardianPrincipalId, hashedDeviceId);
-
-    // Mint a new actor token
-    const { token, tokenHash, claims } = mintActorToken({
+    // Mint credential pair (access token + refresh token)
+    const credentials = mintCredentialPair({
       assistantId,
       platform,
       deviceId,
       guardianPrincipalId,
-    });
-
-    // Store only the hash
-    createActorTokenRecord({
-      tokenHash,
-      assistantId,
-      guardianPrincipalId,
       hashedDeviceId,
-      platform,
-      issuedAt: claims.iat,
-      expiresAt: claims.exp,
     });
 
     log.info(
@@ -136,7 +118,11 @@ export async function handleGuardianBootstrap(req: Request, server: ServerWithRe
 
     return Response.json({
       guardianPrincipalId,
-      actorToken: token,
+      actorToken: credentials.actorToken,
+      actorTokenExpiresAt: credentials.actorTokenExpiresAt,
+      refreshToken: credentials.refreshToken,
+      refreshTokenExpiresAt: credentials.refreshTokenExpiresAt,
+      refreshAfter: credentials.refreshAfter,
       isNew,
     });
   } catch (err) {

package/src/runtime/routes/guardian-refresh-routes.ts

@@ -0,0 +1,53 @@
+/**
+ * POST /v1/integrations/guardian/vellum/refresh
+ *
+ * Rotates the refresh token and mints a new access token + refresh token pair.
+ * This endpoint is the runtime handler proxied through the gateway.
+ */
+
+import { getLogger } from '../../util/logger.js';
+import { rotateCredentials } from '../actor-refresh-token-service.js';
+import { httpError } from '../http-errors.js';
+
+const log = getLogger('guardian-refresh');
+
+/**
+ * Handle POST /v1/integrations/guardian/vellum/refresh
+ *
+ * Body: { platform: 'ios' | 'macos', deviceId: string, refreshToken: string }
+ * Returns: { guardianPrincipalId, actorToken, actorTokenExpiresAt, refreshToken, refreshTokenExpiresAt, refreshAfter }
+ */
+export async function handleGuardianRefresh(req: Request): Promise<Response> {
+  try {
+    const body = await req.json() as Record<string, unknown>;
+    const platform = typeof body.platform === 'string' ? body.platform.trim() : '';
+    const deviceId = typeof body.deviceId === 'string' ? body.deviceId.trim() : '';
+    const refreshToken = typeof body.refreshToken === 'string' ? body.refreshToken : '';
+
+    if (!platform || !deviceId || !refreshToken) {
+      return httpError('BAD_REQUEST', 'Missing required fields: platform, deviceId, refreshToken', 400);
+    }
+
+    if (platform !== 'ios' && platform !== 'macos') {
+      return httpError('BAD_REQUEST', 'Invalid platform. Must be "ios" or "macos".', 400);
+    }
+
+    const result = rotateCredentials({ refreshToken, platform, deviceId });
+
+    if (!result.ok) {
+      const statusCode = result.error === 'refresh_reuse_detected' ? 403
+        : result.error === 'device_binding_mismatch' ? 403
+        : result.error === 'revoked' ? 403
+        : 401;
+
+      log.warn({ error: result.error, platform }, 'Refresh token rotation failed');
+      return Response.json({ error: result.error }, { status: statusCode });
+    }
+
+    log.info({ platform, guardianPrincipalId: result.result.guardianPrincipalId }, 'Refresh token rotation succeeded');
+    return Response.json(result.result);
+  } catch (err) {
+    log.error({ err }, 'Guardian refresh failed');
+    return httpError('INTERNAL_ERROR', 'Internal server error', 500);
+  }
+}