@vellumai/assistant 0.4.32 → 0.4.34

package/src/runtime/auth/__tests__/guard-tests.test.ts

@@ -6,9 +6,7 @@
  *
  * 1. Route policy coverage — every dispatched endpoint has a policy.
  * 2. No X-Actor-Token references in production code.
- * 3. No ~/.vellum/http-token file-path references in production code
- *    (the file itself is still used; the guard prevents new code from
- *    reading it directly instead of using the platform utility).
+ * 3. No legacy gateway-origin proof in production code.
  * 4. Scope profile contract — every profile resolves to the expected scopes.
  */
 

package/src/runtime/auth/credential-service.ts

@@ -132,7 +132,6 @@ function mintAccessToken(guardianPrincipalId: string): {
 // ---------------------------------------------------------------------------
 
 function mintRefreshTokenInternal(params: {
-  assistantId: string;
   guardianPrincipalId: string;
   hashedDeviceId: string;
   platform: string;
@@ -155,7 +154,6 @@ function mintRefreshTokenInternal(params: {
   createRefreshTokenRecord({
     tokenHash: refreshTokenHash,
     familyId,
-    assistantId: params.assistantId,
     guardianPrincipalId: params.guardianPrincipalId,
     hashedDeviceId: params.hashedDeviceId,
     platform: params.platform,
@@ -184,20 +182,14 @@ function mintRefreshTokenInternal(params: {
  * Revokes any existing credentials for the device before minting.
  */
 export function mintCredentialPair(params: {
-  assistantId: string;
   platform: string;
   deviceId: string;
   guardianPrincipalId: string;
   hashedDeviceId: string;
 }): CredentialPairResult {
   // Revoke any existing credentials for this device
-  revokeActorTokensByDevice(
-    params.assistantId,
-    params.guardianPrincipalId,
-    params.hashedDeviceId,
-  );
+  revokeActorTokensByDevice(params.guardianPrincipalId, params.hashedDeviceId);
   revokeRefreshTokensByDevice(
-    params.assistantId,
     params.guardianPrincipalId,
     params.hashedDeviceId,
   );
@@ -207,7 +199,6 @@ export function mintCredentialPair(params: {
 
   createActorTokenRecord({
     tokenHash: access.tokenHash,
-    assistantId: params.assistantId,
     guardianPrincipalId: params.guardianPrincipalId,
     hashedDeviceId: params.hashedDeviceId,
     platform: params.platform,
@@ -217,7 +208,6 @@ export function mintCredentialPair(params: {
 
   // Mint new refresh token
   const refresh = mintRefreshTokenInternal({
-    assistantId: params.assistantId,
     guardianPrincipalId: params.guardianPrincipalId,
     hashedDeviceId: params.hashedDeviceId,
     platform: params.platform,
@@ -270,7 +260,6 @@ export function rotateCredentials(params: {
     );
     revokeFamily(record.familyId);
     revokeActorTokensByDevice(
-      record.assistantId,
       record.guardianPrincipalId,
       record.hashedDeviceId,
     );
@@ -314,7 +303,6 @@ export function rotateCredentials(params: {
 
     // Revoke old access tokens for this device
     revokeActorTokensByDevice(
-      record.assistantId,
       record.guardianPrincipalId,
       record.hashedDeviceId,
     );
@@ -324,7 +312,6 @@ export function rotateCredentials(params: {
 
     createActorTokenRecord({
       tokenHash: access.tokenHash,
-      assistantId: record.assistantId,
       guardianPrincipalId: record.guardianPrincipalId,
       hashedDeviceId: record.hashedDeviceId,
       platform: params.platform,
@@ -336,7 +323,6 @@ export function rotateCredentials(params: {
     // absolute expiry so rotation resets inactivity but never extends
     // the session lifetime.
     const refresh = mintRefreshTokenInternal({
-      assistantId: record.assistantId,
       guardianPrincipalId: record.guardianPrincipalId,
       hashedDeviceId: record.hashedDeviceId,
       platform: params.platform,

package/src/runtime/auth/require-bound-guardian.ts

@@ -22,10 +22,7 @@ export function requireBoundGuardian(
       403,
     );
   }
-  const guardianResult = findGuardianForChannel(
-    "vellum",
-    authContext.assistantId,
-  );
+  const guardianResult = findGuardianForChannel("vellum");
   if (!guardianResult) {
     // No guardian yet — in pre-bootstrap state, allow through
     return null;

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

@@ -318,6 +318,56 @@ export function mintUiPageToken(): string {
   });
 }
 
+// ---------------------------------------------------------------------------
+// CLI edge token
+// ---------------------------------------------------------------------------
+
+/**
+ * Mint a long-lived JWT for the CLI to authenticate with the gateway.
+ *
+ * Written to ~/.vellum/http-token at daemon startup so the CLI can read it
+ * and pass it as a Bearer token. Regenerated on each daemon restart. A 30-day
+ * TTL avoids expiry between restarts while keeping the window bounded.
+ *
+ * Uses aud=vellum-gateway so the gateway's edge-auth middleware accepts it.
+ */
+export function mintCliEdgeToken(): string {
+  return mintToken({
+    aud: "vellum-gateway",
+    sub: "svc:daemon:self",
+    scope_profile: "gateway_service_v1",
+    policy_epoch: CURRENT_POLICY_EPOCH,
+    ttlSeconds: 86400 * 30,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Pairing bearer token
+// ---------------------------------------------------------------------------
+
+/**
+ * Mint a JWT bearer token for the iOS pairing flow.
+ *
+ * Minted once at daemon startup and reused for all pairing approvals
+ * during this daemon's lifetime. The token is stored on approved pairing
+ * entries and returned in HTTP responses as a legacy compatibility field.
+ * (iOS clients also receive proper JWT credentials via mintCredentialPair.)
+ *
+ * The 24-hour TTL covers a typical daemon lifecycle. The daemon re-mints
+ * on each restart since the signing key is stable across restarts.
+ *
+ * aud=vellum-daemon, sub=svc:daemon:pairing, scope_profile=gateway_service_v1
+ */
+export function mintPairingBearerToken(): string {
+  return mintToken({
+    aud: "vellum-daemon",
+    sub: "svc:daemon:pairing",
+    scope_profile: "gateway_service_v1",
+    policy_epoch: CURRENT_POLICY_EPOCH,
+    ttlSeconds: 86400, // 24 hours — covers a typical daemon lifecycle
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Hash
 // ---------------------------------------------------------------------------

package/src/runtime/channel-guardian-service.ts

@@ -111,7 +111,6 @@ function generateNumericSecret(digits: number = 6): string {
  * the user; only the hash is persisted.
  */
 export function createVerificationChallenge(
-  assistantId: string,
   channel: string,
   sessionId?: string,
 ): CreateChallengeResult {
@@ -124,7 +123,6 @@ export function createVerificationChallenge(
 
   createChallenge({
     id: challengeId,
-    assistantId,
     channel,
     challengeHash,
     expiresAt,
@@ -162,7 +160,6 @@ export function createVerificationChallenge(
  * period. On success the counter resets.
  */
 export function validateAndConsumeChallenge(
-  assistantId: string,
   channel: string,
   secret: string,
   actorExternalUserId: string,
@@ -171,12 +168,7 @@ export function validateAndConsumeChallenge(
   _actorDisplayName?: string,
 ): ValidateChallengeResult {
   // ── Rate-limit check ──
-  const existing = getRateLimit(
-    assistantId,
-    channel,
-    actorExternalUserId,
-    actorChatId,
-  );
+  const existing = getRateLimit(channel, actorExternalUserId, actorChatId);
   if (
     existing &&
     existing.lockedUntil != null &&
@@ -195,14 +187,9 @@ export function validateAndConsumeChallenge(
 
   const challengeHash = hashSecret(secret);
 
-  const challenge = findPendingChallengeByHash(
-    assistantId,
-    channel,
-    challengeHash,
-  );
+  const challenge = findPendingChallengeByHash(channel, challengeHash);
   if (!challenge) {
     recordInvalidAttempt(
-      assistantId,
       channel,
       actorExternalUserId,
       actorChatId,
@@ -221,7 +208,6 @@ export function validateAndConsumeChallenge(
 
   if (Date.now() > challenge.expiresAt) {
     recordInvalidAttempt(
-      assistantId,
       channel,
       actorExternalUserId,
       actorChatId,
@@ -295,7 +281,6 @@ export function validateAndConsumeChallenge(
       // Anti-oracle: use the same generic error message to avoid leaking
       // whether the identity is wrong vs. the code is wrong.
       recordInvalidAttempt(
-        assistantId,
         channel,
         actorExternalUserId,
         actorChatId,
@@ -319,7 +304,7 @@ export function validateAndConsumeChallenge(
   consumeChallenge(challenge.id, actorExternalUserId, actorChatId);
 
   // Reset the rate-limit counter on success
-  resetRateLimit(assistantId, channel, actorExternalUserId, actorChatId);
+  resetRateLimit(channel, actorExternalUserId, actorChatId);
 
   // Return the verification type — role-specific side effects are
   // handled by callers: verification-intercept (channel) and
@@ -343,7 +328,7 @@ export function getGuardianBinding(
   assistantId: string,
   channel: string,
 ): GuardianBinding | null {
-  const result = findGuardianForChannel(channel, assistantId);
+  const result = findGuardianForChannel(channel);
   if (result) {
     return {
       id: result.channel.id,
@@ -355,9 +340,7 @@ export function getGuardianBinding(
       status: "active" as const,
       verifiedAt: result.channel.verifiedAt ?? 0,
       verifiedVia: result.channel.verifiedVia ?? "",
-      metadataJson: result.contact.displayName
-        ? JSON.stringify({ displayName: result.contact.displayName })
-        : null,
+      metadataJson: null,
       createdAt: result.channel.createdAt,
       updatedAt: result.channel.updatedAt ?? result.channel.createdAt,
     };
@@ -375,7 +358,7 @@ export function isGuardian(
   channel: string,
   externalUserId: string,
 ): boolean {
-  const result = findGuardianForChannel(channel, assistantId);
+  const result = findGuardianForChannel(channel);
   if (result) {
     return result.channel.externalUserId === externalUserId;
   }
@@ -387,31 +370,27 @@ export function isGuardian(
  * Revoke the active guardian binding for a given assistant and channel.
  */
 export function revokeBinding(assistantId: string, channel: string): boolean {
-  return revokeGuardianBinding(assistantId, channel);
+  return revokeGuardianBinding(channel);
 }
 
 /**
- * Revoke all pending challenges for a given assistant and channel.
+ * Revoke all pending challenges for a given channel.
  * Called when the user cancels verification so that stale challenges
  * don't gate inbound calls.
  */
-export function revokePendingChallenges(
-  assistantId: string,
-  channel: string,
-): void {
-  storeRevokePendingChallenges(assistantId, channel);
+export function revokePendingChallenges(channel: string): void {
+  storeRevokePendingChallenges(channel);
 }
 
 /**
  * Look up a pending (non-expired) verification challenge for a given
- * assistant and channel. Used by relay setup to detect whether an active
+ * channel. Used by relay setup to detect whether an active
  * voice verification session exists.
  */
 export function getPendingChallenge(
-  assistantId: string,
   channel: string,
 ): VerificationChallenge | null {
-  return findPendingChallengeForChannel(assistantId, channel);
+  return findPendingChallengeForChannel(channel);
 }
 
 // ---------------------------------------------------------------------------
@@ -437,7 +416,6 @@ export interface CreateOutboundSessionResult {
  * the TTL window.
  */
 export function createOutboundSession(params: {
-  assistantId: string;
   channel: string;
   expectedExternalUserId?: string;
   expectedChatId?: string;
@@ -462,7 +440,6 @@ export function createOutboundSession(params: {
 
   createVerificationSession({
     id: sessionId,
-    assistantId: params.assistantId,
     channel: params.channel,
     challengeHash,
     expiresAt,
@@ -491,33 +468,24 @@ export function createOutboundSession(params: {
 }
 
 /**
- * Find the most recent active outbound session for a given
- * (assistantId, channel).
+ * Find the most recent active outbound session for a given channel.
  */
 export function findActiveSession(
-  assistantId: string,
   channel: string,
 ): VerificationChallenge | null {
-  return storeFindActiveSession(assistantId, channel);
+  return storeFindActiveSession(channel);
 }
 
 /**
  * Identity-bound session lookup for the consume path.
  */
 export function findSessionByIdentity(
-  assistantId: string,
   channel: string,
   externalUserId?: string,
   chatId?: string,
   phoneE164?: string,
 ): VerificationChallenge | null {
-  return storeFindSessionByIdentity(
-    assistantId,
-    channel,
-    externalUserId,
-    chatId,
-    phoneE164,
-  );
+  return storeFindSessionByIdentity(channel, externalUserId, chatId, phoneE164);
 }
 
 /**
@@ -580,10 +548,9 @@ export function bindSessionIdentity(
  * Hashes the raw token with SHA-256 and looks up the session.
  */
 export function resolveBootstrapToken(
-  assistantId: string,
   channel: string,
   token: string,
 ): VerificationChallenge | null {
   const tokenHash = hashSecret(token);
-  return storeFindSessionByBootstrapTokenHash(assistantId, channel, tokenHash);
+  return storeFindSessionByBootstrapTokenHash(channel, tokenHash);
 }

package/src/runtime/channel-invite-transport.ts

@@ -1,13 +1,15 @@
 /**
- * Channel invite transport abstraction.
+ * Channel invite adapter abstraction.
  *
- * Defines a transport interface for building shareable invite links and
- * extracting inbound invite tokens from channel-specific payloads. Each
- * channel (Telegram, SMS, Slack, etc.) registers an adapter that knows
- * how to construct deep links and parse incoming tokens for that channel.
+ * Defines an adapter interface for building shareable invite links,
+ * extracting inbound invite tokens, and generating guardian instructions
+ * from channel-specific payloads. Each channel (Telegram, voice, etc.)
+ * registers an adapter that knows how to handle invite flows for that
+ * channel.
  *
- * The transport layer is intentionally thin: it handles URL construction
- * and token extraction only. Redemption logic lives in
+ * All methods are optional: a channel that only provides
+ * `buildGuardianInstruction` (e.g. SMS) is a valid adapter. The adapter
+ * layer is intentionally thin — redemption logic lives in
  * `invite-redemption-service.ts`.
  */
 
@@ -17,71 +19,164 @@ import type { ChannelId } from "../channels/types.js";
 // Types
 // ---------------------------------------------------------------------------
 
-export interface InviteSharePayload {
+export interface InviteShareLink {
   /** The full URL the recipient can open to redeem the invite. */
   url: string;
   /** Human-readable text suitable for display alongside the link. */
   displayText: string;
 }
 
-export interface ChannelInviteTransport {
-  /** The channel this transport handles. */
+export interface GuardianInstruction {
+  /** Human-readable instruction text for the guardian. */
+  instruction: string;
+  /** Channel-specific handle to reach the assistant (e.g. "@botName", "+15551234567", "hello@domain.agentmail.to"). */
+  channelHandle?: string;
+}
+
+export interface ChannelInviteAdapter {
+  /** The channel this adapter handles. */
   channel: ChannelId;
 
   /**
-   * Build a shareable invite payload (URL + display text) from a raw token.
-   *
-   * The raw token is the base64url-encoded secret returned by
-   * `invite-store.createInvite`. The transport wraps it in a
-   * channel-specific deep link so the recipient can redeem the invite
-   * by clicking/tapping the link.
+   * Build a channel-specific shareable link (e.g. Telegram deep link).
+   * Optional — not all channels support link-based invites.
    */
-  buildShareableInvite(params: {
+  buildShareLink?(params: {
     rawToken: string;
     sourceChannel: ChannelId;
-  }): InviteSharePayload;
+  }): InviteShareLink;
 
   /**
-   * Extract an invite token from an inbound channel message.
-   *
-   * Returns the raw token string (without the `iv_` prefix) if the
-   * message contains a valid invite token, or `undefined` otherwise.
+   * Extract a channel-specific invite token from an inbound message
+   * (e.g. Telegram `/start iv_<token>`). Optional — only needed for
+   * channels with link-based invites.
    */
-  extractInboundToken(params: {
+  extractInboundToken?(params: {
     commandIntent?: Record<string, unknown>;
     content: string;
     sourceMetadata?: Record<string, unknown>;
   }): string | undefined;
+
+  /**
+   * Build guardian instruction for this channel. Returns structured data
+   * with the instruction text and an optional channel-specific handle.
+   * Optional — falls back to generic instruction if not implemented.
+   */
+  buildGuardianInstruction?(params: {
+    inviteCode: string;
+    contactName?: string;
+  }): GuardianInstruction;
+
+  /**
+   * Resolve the channel-specific handle to reach the assistant (e.g.
+   * "@botName", "+15551234567", "hello@domain.agentmail.to").
+   * Returns `undefined` when the handle cannot be resolved (e.g.
+   * credentials not yet configured).
+   */
+  resolveChannelHandle?(): string | undefined;
 }
 
+// ---------------------------------------------------------------------------
+// Backward-compatible type aliases
+// ---------------------------------------------------------------------------
+
+/** @deprecated Use `ChannelInviteAdapter` instead. */
+export type ChannelInviteTransport = ChannelInviteAdapter;
+
+/** @deprecated Use `InviteShareLink` instead. */
+export type InviteSharePayload = InviteShareLink;
+
 // ---------------------------------------------------------------------------
 // Registry
 // ---------------------------------------------------------------------------
 
-const registry = new Map<ChannelId, ChannelInviteTransport>();
+export class InviteAdapterRegistry {
+  private adapters = new Map<ChannelId, ChannelInviteAdapter>();
+
+  /**
+   * Register a channel invite adapter. Overwrites any previously
+   * registered adapter for the same channel.
+   */
+  register(adapter: ChannelInviteAdapter): void {
+    this.adapters.set(adapter.channel, adapter);
+  }
+
+  /**
+   * Look up the registered adapter for a channel. Returns `undefined`
+   * when no adapter has been registered for the given channel.
+   */
+  get(channel: ChannelId): ChannelInviteAdapter | undefined {
+    return this.adapters.get(channel);
+  }
+
+  /** Return all registered adapters. */
+  getAll(): ChannelInviteAdapter[] {
+    return Array.from(this.adapters.values());
+  }
+
+  /**
+   * Reset the registry. Intended for tests only.
+   * @internal
+   */
+  _reset(): void {
+    this.adapters.clear();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Singleton registry + backward-compatible free functions
+// ---------------------------------------------------------------------------
+
+import { emailInviteAdapter } from "./channel-invite-transports/email.js";
+import { slackInviteAdapter } from "./channel-invite-transports/slack.js";
+import { smsInviteAdapter } from "./channel-invite-transports/sms.js";
+import { telegramInviteAdapter } from "./channel-invite-transports/telegram.js";
+import { voiceInviteAdapter } from "./channel-invite-transports/voice.js";
+
+/** Create a registry instance with built-in adapters registered. */
+export function createInviteAdapterRegistry(): InviteAdapterRegistry {
+  const registry = new InviteAdapterRegistry();
+  registry.register(emailInviteAdapter);
+  registry.register(slackInviteAdapter);
+  registry.register(smsInviteAdapter);
+  registry.register(telegramInviteAdapter);
+  registry.register(voiceInviteAdapter);
+  return registry;
+}
+
+/**
+ * Module-level singleton registry, created eagerly so callers that
+ * import the free functions continue to work without changes.
+ */
+const defaultRegistry = createInviteAdapterRegistry();
+
+/** Return the module-level singleton registry. */
+export function getInviteAdapterRegistry(): InviteAdapterRegistry {
+  return defaultRegistry;
+}
 
 /**
- * Register a channel invite transport. Overwrites any previously registered
- * transport for the same channel.
+ * Register a channel invite adapter on the default registry.
+ * @deprecated Prefer `getInviteAdapterRegistry().register(adapter)`.
  */
-export function registerTransport(transport: ChannelInviteTransport): void {
-  registry.set(transport.channel, transport);
+export function registerTransport(transport: ChannelInviteAdapter): void {
+  defaultRegistry.register(transport);
 }
 
 /**
- * Look up the registered transport for a channel. Returns `undefined` when
- * no transport has been registered for the given channel.
+ * Look up the registered adapter for a channel on the default registry.
+ * @deprecated Prefer `getInviteAdapterRegistry().get(channel)`.
  */
 export function getTransport(
   channel: ChannelId,
-): ChannelInviteTransport | undefined {
-  return registry.get(channel);
+): ChannelInviteAdapter | undefined {
+  return defaultRegistry.get(channel);
 }
 
 /**
- * Reset the registry. Intended for tests only.
+ * Reset the default registry. Intended for tests only.
  * @internal
  */
 export function _resetRegistry(): void {
-  registry.clear();
+  defaultRegistry._reset();
 }

package/src/runtime/channel-invite-transports/email.ts

@@ -0,0 +1,54 @@
+/**
+ * Email channel invite adapter.
+ *
+ * Provides guardian instruction text for email-based invites. Email invites
+ * use the universal 6-digit code path for redemption, so this adapter only
+ * implements `buildGuardianInstruction` — no `buildShareLink` or
+ * `extractInboundToken` needed.
+ */
+
+import type {
+  ChannelInviteAdapter,
+  GuardianInstruction,
+} from "../channel-invite-transport.js";
+
+// ---------------------------------------------------------------------------
+// Email address resolution
+// ---------------------------------------------------------------------------
+
+// TODO: resolve from AgentMail provider (async — needs caching or pre-resolution)
+// The real implementation requires async inbox lookup via
+// `getActiveEmailProvider().health()` which doesn't fit the sync adapter
+// interface.
+function resolveAssistantEmailAddress(): string | undefined {
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Adapter implementation
+// ---------------------------------------------------------------------------
+
+export const emailInviteAdapter: ChannelInviteAdapter = {
+  channel: "email",
+
+  buildGuardianInstruction(params: {
+    inviteCode: string;
+    contactName?: string;
+  }): GuardianInstruction {
+    const address = resolveAssistantEmailAddress();
+    const contactLabel = params.contactName || "the contact";
+    if (!address) {
+      return {
+        instruction: `Tell ${contactLabel} to email the assistant and include the code ${params.inviteCode} in the message.`,
+      };
+    }
+    return {
+      instruction: `Tell ${contactLabel} to email ${address} and include the code ${params.inviteCode} in the message.`,
+      channelHandle: address,
+    };
+  },
+
+  resolveChannelHandle(): string | undefined {
+    return resolveAssistantEmailAddress();
+  },
+};