@vellumai/assistant 0.4.30 → 0.4.31

package/src/runtime/http-server.ts

@@ -140,6 +140,7 @@ import {
   handleMergeContacts,
   handleUpdateContactChannel,
   handleUpsertContact,
+  handleVerifyContactChannel,
 } from "./routes/contact-routes.js";
 import { handleListConversationAttention } from "./routes/conversation-attention-routes.js";
 // Route handlers — grouped by domain
@@ -1128,6 +1129,17 @@ export class RuntimeHttpServer {
         handler: async ({ req, params, authContext }) =>
           handleUpdateContactChannel(req, params.id, authContext.assistantId),
       },
+      {
+        endpoint: "contacts/:contactId/channels/:channelId/verify",
+        method: "POST",
+        policyKey: "contacts/channels",
+        handler: async ({ params, authContext }) =>
+          handleVerifyContactChannel(
+            params.contactId,
+            params.channelId,
+            authContext.assistantId,
+          ),
+      },
 
       // ------------------------------------------------------------------
       // Contacts invites — must precede contacts/:id to avoid shadowing

package/src/runtime/routes/approval-strategies/guardian-callback-strategy.ts

@@ -297,7 +297,8 @@ async function handleCallbackDecision(params: {
   const result = applyGuardianDecision({
     approval: guardianApproval,
     decision: callbackDecision,
-    actorExternalUserId: actorExternalId,
+    actorPrincipalId: undefined, // Callback path — principal not available at this layer
+    actorExternalUserId: actorExternalId, // Channel-native ID (Telegram user ID, phone, etc.)
     actorChannel: sourceChannel,
   });
 
@@ -491,7 +492,8 @@ async function handleConversationalDecision(params: {
   const result = applyGuardianDecision({
     approval: targetApproval,
     decision: engineDecision,
-    actorExternalUserId: actorExternalId,
+    actorPrincipalId: undefined, // Callback path — principal not available at this layer
+    actorExternalUserId: actorExternalId, // Channel-native ID (Telegram user ID, phone, etc.)
     actorChannel: sourceChannel,
   });
 
@@ -675,7 +677,8 @@ async function handleLegacyDecision(params: {
     const result = applyGuardianDecision({
       approval: targetLegacyApproval,
       decision: legacyGuardianDecision,
-      actorExternalUserId: actorExternalId,
+      actorPrincipalId: undefined, // Callback path — principal not available at this layer
+      actorExternalUserId: actorExternalId, // Channel-native ID (Telegram user ID, phone, etc.)
       actorChannel: sourceChannel,
     });
 

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

@@ -6,8 +6,12 @@
  * GET   /v1/contacts/:id          — get a contact by ID
  * POST  /v1/contacts/merge        — merge two contacts
  * PATCH /v1/contacts/channels/:id — update a contact channel's status/policy
+ * POST  /v1/contacts/:contactId/channels/:channelId/verify — initiate trusted contact verification
  */
 
+import { createHash, randomBytes } from "node:crypto";
+
+import type { ChannelId } from "../../channels/types.js";
 import {
   getAssistantContactMetadata,
   getChannelById,
@@ -20,6 +24,7 @@ import {
   upsertContact,
   validateSpeciesMetadata,
 } from "../../contacts/contact-store.js";
+import type { ContactChannel } from "../../contacts/types.js";
 import type {
   AssistantSpecies,
   ChannelPolicy,
@@ -27,6 +32,27 @@ import type {
   ContactRole,
   ContactType,
 } from "../../contacts/types.js";
+import { getCredentialMetadata } from "../../tools/credentials/metadata-store.js";
+import { normalizePhoneNumber } from "../../util/phone.js";
+import {
+  countRecentSendsToDestination,
+  createOutboundSession,
+  updateSessionDelivery,
+} from "../channel-guardian-service.js";
+import {
+  deliverVerificationSlack,
+  deliverVerificationSms,
+  deliverVerificationTelegram,
+  DESTINATION_RATE_WINDOW_MS,
+  MAX_SENDS_PER_DESTINATION_WINDOW,
+  normalizeTelegramDestination,
+} from "../guardian-outbound-actions.js";
+import {
+  composeVerificationSlack,
+  composeVerificationSms,
+  composeVerificationTelegram,
+  GUARDIAN_VERIFY_TEMPLATE_KEYS,
+} from "../guardian-verification-templates.js";
 import { httpError } from "../http-errors.js";
 
 const VALID_CONTACT_TYPES: readonly ContactType[] = ["human", "assistant"];
@@ -38,7 +64,7 @@ const VALID_ASSISTANT_SPECIES: readonly AssistantSpecies[] = [
 /**
  * GET /v1/contacts?limit=50&role=guardian&contactType=human
  *
- * Also supports search query params: query, channelAddress, channelType, relationship.
+ * Also supports search query params: query, channelAddress, channelType.
  * When any search param is provided, delegates to searchContacts() instead of listContacts().
  */
 export function handleListContacts(url: URL, assistantId: string): Response {
@@ -48,8 +74,6 @@ export function handleListContacts(url: URL, assistantId: string): Response {
   const query = url.searchParams.get("query");
   const channelAddress = url.searchParams.get("channelAddress");
   const channelType = url.searchParams.get("channelType");
-  const relationship = url.searchParams.get("relationship");
-
   if (contactTypeParam && !isContactType(contactTypeParam)) {
     return httpError(
       "BAD_REQUEST",
@@ -58,8 +82,7 @@ export function handleListContacts(url: URL, assistantId: string): Response {
     );
   }
 
-  const hasSearchParams =
-    query || channelAddress || channelType || relationship;
+  const hasSearchParams = query || channelAddress || channelType;
 
   const contactType = contactTypeParam
     ? (contactTypeParam as ContactType)
@@ -71,7 +94,6 @@ export function handleListContacts(url: URL, assistantId: string): Response {
       query: query ?? undefined,
       channelAddress: channelAddress ?? undefined,
       channelType: channelType ?? undefined,
-      relationship: relationship ?? undefined,
       role: role ?? undefined,
       contactType,
       limit,
@@ -162,7 +184,7 @@ function isChannelPolicy(value: string): value is ChannelPolicy {
 }
 
 /**
- * POST /v1/contacts { displayName, id?, relationship?, importance?, contactType?, assistantMetadata?, ... }
+ * POST /v1/contacts { displayName, id?, notes?, contactType?, assistantMetadata?, ... }
  */
 export async function handleUpsertContact(
   req: Request,
@@ -171,10 +193,7 @@ export async function handleUpsertContact(
   const body = (await req.json()) as {
     id?: string;
     displayName?: string;
-    relationship?: string;
-    importance?: number;
-    responseExpectation?: string;
-    preferredTone?: string;
+    notes?: string;
     role?: string;
     contactType?: string;
     assistantMetadata?: {
@@ -204,20 +223,6 @@ export async function handleUpsertContact(
     );
   }
 
-  if (
-    body.importance !== undefined &&
-    (typeof body.importance !== "number" ||
-      Number.isNaN(body.importance) ||
-      body.importance < 0 ||
-      body.importance > 1)
-  ) {
-    return httpError(
-      "BAD_REQUEST",
-      "importance must be a number between 0 and 1",
-      400,
-    );
-  }
-
   if (body.contactType !== undefined && !isContactType(body.contactType)) {
     return httpError(
       "BAD_REQUEST",
@@ -297,10 +302,7 @@ export async function handleUpsertContact(
     const contact = upsertContact({
       id: body.id,
       displayName: body.displayName.trim(),
-      relationship: body.relationship,
-      importance: body.importance,
-      responseExpectation: body.responseExpectation,
-      preferredTone: body.preferredTone,
+      notes: body.notes,
       role: body.role as ContactRole | undefined,
       contactType: body.contactType as ContactType | undefined,
       assistantId,
@@ -404,3 +406,280 @@ export async function handleUpdateContactChannel(
   const parentContact = getContact(updated.contactId, assistantId);
   return Response.json({ ok: true, contact: parentContact ?? undefined });
 }
+
+// ---------------------------------------------------------------------------
+// Channel verification
+// ---------------------------------------------------------------------------
+
+/** Session TTL in seconds (matches challenge TTL of 10 minutes). */
+const SESSION_TTL_SECONDS = 600;
+
+/**
+ * Map a contact channel type to the verification ChannelId used by the
+ * guardian service. Returns null for unsupported channel types.
+ */
+function toVerificationChannel(channelType: string): ChannelId | null {
+  switch (channelType) {
+    case "phone":
+      return "sms";
+    case "telegram":
+      return "telegram";
+    case "slack":
+      return "slack";
+    default:
+      return null;
+  }
+}
+
+/**
+ * Get the Telegram bot username from credential metadata.
+ * Falls back to process.env.TELEGRAM_BOT_USERNAME.
+ */
+function getTelegramBotUsername(): string | undefined {
+  const meta = getCredentialMetadata("telegram", "bot_token");
+  if (
+    meta?.accountInfo &&
+    typeof meta.accountInfo === "string" &&
+    meta.accountInfo.trim().length > 0
+  ) {
+    return meta.accountInfo.trim();
+  }
+  return process.env.TELEGRAM_BOT_USERNAME || undefined;
+}
+
+/**
+ * POST /v1/contacts/:contactId/channels/:channelId/verify
+ *
+ * Initiate trusted contact verification for a specific channel. Sends a
+ * verification code via SMS, Telegram, Slack, or voice and returns session
+ * info so the client can track the verification flow.
+ */
+export async function handleVerifyContactChannel(
+  contactId: string,
+  channelId: string,
+  assistantId: string,
+): Promise<Response> {
+  const contact = getContact(contactId, assistantId);
+  if (!contact) {
+    return httpError("NOT_FOUND", `Contact "${contactId}" not found`, 404);
+  }
+
+  const channel: ContactChannel | undefined = contact.channels.find(
+    (ch) => ch.id === channelId,
+  );
+  if (!channel) {
+    return httpError("NOT_FOUND", `Channel "${channelId}" not found`, 404);
+  }
+
+  // Already verified — no need to re-verify
+  if (channel.status === "active" && channel.verifiedAt != null) {
+    return httpError("CONFLICT", "Channel is already verified", 409);
+  }
+
+  const verificationChannel = toVerificationChannel(channel.type);
+  if (!verificationChannel) {
+    return httpError(
+      "BAD_REQUEST",
+      `Verification is not supported for channel type "${channel.type}"`,
+      400,
+    );
+  }
+
+  const destination = channel.address;
+  if (!destination) {
+    return httpError(
+      "BAD_REQUEST",
+      "Channel has no address to send verification to",
+      400,
+    );
+  }
+
+  // Normalize Telegram destinations so rate-limit lookups are consistent with
+  // guardian-outbound-actions (strips leading '@', lowercases handles).
+  const effectiveDestination =
+    verificationChannel === "telegram"
+      ? normalizeTelegramDestination(destination)
+      : destination;
+
+  // Rate limit check
+  const recentSendCount = countRecentSendsToDestination(
+    verificationChannel,
+    effectiveDestination,
+    DESTINATION_RATE_WINDOW_MS,
+  );
+  if (recentSendCount >= MAX_SENDS_PER_DESTINATION_WINDOW) {
+    return httpError(
+      "RATE_LIMITED",
+      "Too many verification attempts to this destination. Please try again later.",
+      429,
+    );
+  }
+
+  // --- SMS verification ---
+  if (verificationChannel === "sms") {
+    const phoneE164 = normalizePhoneNumber(destination);
+    if (!phoneE164) {
+      return httpError(
+        "BAD_REQUEST",
+        "Channel address is not a valid phone number",
+        400,
+      );
+    }
+
+    const sessionResult = createOutboundSession({
+      assistantId,
+      channel: verificationChannel,
+      expectedPhoneE164: phoneE164,
+      expectedExternalUserId: channel.externalUserId ?? undefined,
+      destinationAddress: phoneE164,
+      verificationPurpose: "trusted_contact",
+    });
+
+    const smsBody = composeVerificationSms(
+      GUARDIAN_VERIFY_TEMPLATE_KEYS.CHALLENGE_REQUEST,
+      {
+        code: sessionResult.secret,
+        expiresInMinutes: Math.floor(SESSION_TTL_SECONDS / 60),
+      },
+    );
+
+    const now = Date.now();
+    const sendCount = 1;
+    updateSessionDelivery(sessionResult.sessionId, now, sendCount, null);
+    deliverVerificationSms(phoneE164, smsBody, assistantId);
+
+    return Response.json({
+      ok: true,
+      verificationSessionId: sessionResult.sessionId,
+      expiresAt: sessionResult.expiresAt,
+      sendCount,
+    });
+  }
+
+  // --- Telegram verification ---
+  if (verificationChannel === "telegram") {
+    // Telegram with known chat ID: identity is already bound
+    if (channel.externalChatId) {
+      const sessionResult = createOutboundSession({
+        assistantId,
+        channel: verificationChannel,
+        expectedChatId: channel.externalChatId,
+        expectedExternalUserId: channel.externalUserId ?? undefined,
+        identityBindingStatus: "bound",
+        destinationAddress: effectiveDestination,
+        verificationPurpose: "trusted_contact",
+      });
+
+      const telegramBody = composeVerificationTelegram(
+        GUARDIAN_VERIFY_TEMPLATE_KEYS.TELEGRAM_CHALLENGE_REQUEST,
+        {
+          code: sessionResult.secret,
+          expiresInMinutes: Math.floor(SESSION_TTL_SECONDS / 60),
+        },
+      );
+
+      const now = Date.now();
+      const sendCount = 1;
+      updateSessionDelivery(sessionResult.sessionId, now, sendCount, null);
+      deliverVerificationTelegram(
+        channel.externalChatId,
+        telegramBody,
+        assistantId,
+      );
+
+      return Response.json({
+        ok: true,
+        verificationSessionId: sessionResult.sessionId,
+        expiresAt: sessionResult.expiresAt,
+        sendCount,
+      });
+    }
+
+    // Telegram handle only (no chat ID): bootstrap flow
+    const botUsername = getTelegramBotUsername();
+    if (!botUsername) {
+      return httpError(
+        "BAD_REQUEST",
+        "Telegram bot username is not configured. Set up the Telegram integration first.",
+        400,
+      );
+    }
+
+    const bootstrapToken = randomBytes(16).toString("hex");
+    const bootstrapTokenHash = createHash("sha256")
+      .update(bootstrapToken)
+      .digest("hex");
+
+    const sessionResult = createOutboundSession({
+      assistantId,
+      channel: verificationChannel,
+      identityBindingStatus: "pending_bootstrap",
+      destinationAddress: effectiveDestination,
+      bootstrapTokenHash,
+      verificationPurpose: "trusted_contact",
+    });
+
+    const telegramBootstrapUrl = `https://t.me/${botUsername}?start=gv_${bootstrapToken}`;
+
+    return Response.json({
+      ok: true,
+      verificationSessionId: sessionResult.sessionId,
+      expiresAt: sessionResult.expiresAt,
+      sendCount: 0,
+      telegramBootstrapUrl,
+    });
+  }
+
+  // --- Slack verification ---
+  if (verificationChannel === "slack") {
+    const slackUserId = channel.externalUserId ?? destination;
+
+    // Only claim identity is bound when we have at least one platform identifier
+    const hasIdentityBinding = Boolean(
+      channel.externalUserId || channel.externalChatId,
+    );
+    if (!hasIdentityBinding) {
+      return httpError(
+        "BAD_REQUEST",
+        "Slack verification requires an externalUserId or externalChatId for identity binding",
+        400,
+      );
+    }
+
+    const sessionResult = createOutboundSession({
+      assistantId,
+      channel: verificationChannel,
+      expectedExternalUserId: channel.externalUserId ?? undefined,
+      expectedChatId: channel.externalChatId ?? undefined,
+      identityBindingStatus: "bound",
+      destinationAddress: slackUserId,
+      verificationPurpose: "trusted_contact",
+    });
+
+    const slackBody = composeVerificationSlack(
+      GUARDIAN_VERIFY_TEMPLATE_KEYS.SLACK_CHALLENGE_REQUEST,
+      {
+        code: sessionResult.secret,
+        expiresInMinutes: Math.floor(SESSION_TTL_SECONDS / 60),
+      },
+    );
+
+    const now = Date.now();
+    const sendCount = 1;
+    updateSessionDelivery(sessionResult.sessionId, now, sendCount, null);
+    deliverVerificationSlack(slackUserId, slackBody, assistantId);
+
+    return Response.json({
+      ok: true,
+      verificationSessionId: sessionResult.sessionId,
+      expiresAt: sessionResult.expiresAt,
+      sendCount,
+    });
+  }
+
+  return httpError(
+    "BAD_REQUEST",
+    `Verification is not supported for channel type "${channel.type}"`,
+    400,
+  );
+}

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

@@ -124,7 +124,8 @@ async function tryConsumeCanonicalGuardianReply(params: {
     messageText: trimmedContent,
     channel: sourceChannel,
     actor: {
-      externalUserId: verifiedActorExternalUserId,
+      actorPrincipalId: verifiedActorPrincipalId,
+      actorExternalUserId: verifiedActorExternalUserId,
       channel: sourceChannel,
       guardianPrincipalId: verifiedActorPrincipalId,
     },

package/src/runtime/routes/global-search-routes.ts

@@ -58,7 +58,7 @@ interface GlobalSearchSchedule {
 interface GlobalSearchContact {
   id: string;
   displayName: string;
-  relationship: string | null;
+  notes: string | null;
   lastInteraction: number | null;
 }
 
@@ -256,7 +256,7 @@ export async function handleGlobalSearch(url: URL): Promise<Response> {
     results.contacts = contactResults.map((c) => ({
       id: c.id,
       displayName: c.displayName,
-      relationship: c.relationship,
+      notes: c.notes,
       lastInteraction: c.lastInteraction,
     }));
   }

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

@@ -96,7 +96,7 @@ export async function handleGuardianActionDecision(
     conversationId,
     channel: "vellum",
     actorContext: {
-      externalUserId: authContext.actorPrincipalId ?? undefined,
+      actorPrincipalId: authContext.actorPrincipalId ?? undefined,
       guardianPrincipalId: authContext.actorPrincipalId ?? undefined,
     },
   });

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

@@ -232,7 +232,8 @@ export async function handleApprovalInterception(
             const cancelApplyResult = applyGuardianDecision({
               approval: guardianApprovalForRequest,
               decision: rejectDecision,
-              actorExternalUserId: actorExternalId,
+              actorPrincipalId: undefined, // Interception path — principal not available
+              actorExternalUserId: actorExternalId, // Channel-native ID
               actorChannel: sourceChannel,
             });
             if (cancelApplyResult.applied) {

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

@@ -13,6 +13,7 @@ import { createHash } from "node:crypto";
 
 import { v4 as uuid } from "uuid";
 
+import { resolveUserReference } from "../../config/user-reference.js";
 import { findGuardianForChannel } from "../../contacts/contact-store.js";
 import { createGuardianBinding } from "../../contacts/contacts-write.js";
 import { getLogger } from "../../util/logger.js";
@@ -54,6 +55,7 @@ function ensureGuardianPrincipal(assistantId: string): {
 
   // Mint a new principal ID for the vellum channel
   const guardianPrincipalId = `vellum-principal-${uuid()}`;
+  const guardianDisplayName = resolveUserReference();
 
   createGuardianBinding({
     assistantId,
@@ -62,7 +64,10 @@ function ensureGuardianPrincipal(assistantId: string): {
     guardianDeliveryChatId: "local",
     guardianPrincipalId,
     verifiedVia: "bootstrap",
-    metadataJson: JSON.stringify({ bootstrappedAt: Date.now() }),
+    metadataJson: JSON.stringify({
+      bootstrappedAt: Date.now(),
+      displayName: guardianDisplayName,
+    }),
   });
 
   log.info(

package/src/runtime/routes/inbound-stages/acl-enforcement.ts

@@ -8,7 +8,10 @@
  */
 import type { ChannelId } from "../../../channels/types.js";
 import { findContactChannel } from "../../../contacts/contact-store.js";
-import { touchChannelLastSeen } from "../../../contacts/contacts-write.js";
+import {
+  touchChannelLastSeen,
+  touchContactInteraction,
+} from "../../../contacts/contacts-write.js";
 import type {
   ChannelStatus,
   ContactChannel,
@@ -634,6 +637,7 @@ export async function enforceIngressAcl(
 
       // 'allow' or 'escalate' — update last seen and continue
       touchChannelLastSeen(resolvedMember.channel.id);
+      touchContactInteraction(resolvedMember.contact.id);
     }
   }
 

package/src/runtime/routes/inbound-stages/guardian-reply-intercept.ts

@@ -129,7 +129,8 @@ export async function handleGuardianReplyIntercept(
     messageText: trimmedContent,
     channel: sourceChannel,
     actor: {
-      externalUserId: canonicalSenderId ?? rawSenderId!,
+      actorPrincipalId: guardianPrincipalId ?? undefined,
+      actorExternalUserId: canonicalSenderId ?? rawSenderId!,
       channel: sourceChannel,
       guardianPrincipalId: guardianPrincipalId ?? undefined,
     },