@vellumai/assistant 0.4.2 → 0.4.4

package/src/runtime/access-request-helper.ts

@@ -15,17 +15,29 @@
 
 import type { ChannelId } from '../channels/types.js';
 import {
+  createCanonicalGuardianDelivery,
   createCanonicalGuardianRequest,
   listCanonicalGuardianRequests,
+  updateCanonicalGuardianDelivery,
 } from '../memory/canonical-guardian-store.js';
 import { listActiveBindingsByAssistant } from '../memory/channel-guardian-store.js';
+import type { MemberStatus } from '../memory/ingress-member-store.js';
 import { emitNotificationSignal } from '../notifications/emit-signal.js';
+import type { NotificationDeliveryResult } from '../notifications/types.js';
 import { getLogger } from '../util/logger.js';
 import { getGuardianBinding } from './channel-guardian-service.js';
 import { GUARDIAN_APPROVAL_TTL_MS } from './routes/channel-route-shared.js';
 
 const log = getLogger('access-request-helper');
 
+function applyDeliveryStatus(deliveryId: string, result: NotificationDeliveryResult): void {
+  if (result.status === 'sent') {
+    updateCanonicalGuardianDelivery(deliveryId, { status: 'sent' });
+    return;
+  }
+  updateCanonicalGuardianDelivery(deliveryId, { status: 'failed' });
+}
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -37,6 +49,7 @@ export interface AccessRequestParams {
   senderExternalUserId?: string;
   senderName?: string;
   senderUsername?: string;
+  previousMemberStatus?: MemberStatus;
 }
 
 export type AccessRequestResult =
@@ -71,6 +84,7 @@ export function notifyGuardianOfAccessRequest(
     senderExternalUserId,
     senderName,
     senderUsername,
+    previousMemberStatus,
   } = params;
 
   if (!senderExternalUserId) {
@@ -105,14 +119,22 @@ export function notifyGuardianOfAccessRequest(
     }
   }
 
+  // The conversationId is assistant-scoped so the dedupe query below only
+  // matches requests for the same assistant. Without this, a pending request
+  // from assistant A could be returned for assistant B, allowing the caller
+  // to piggyback on A's guardian approval.
+  const conversationId = `access-req-${canonicalAssistantId}-${sourceChannel}-${senderExternalUserId}`;
+
   // Deduplicate: skip creation if there is already a pending canonical request
-  // for the same requester on this channel. Still return notified: true with
-  // the existing request ID so callers know the guardian was already notified.
+  // for the same requester on this channel *and* assistant. Still return
+  // notified: true with the existing request ID so callers know the guardian
+  // was already notified.
   const existingCanonical = listCanonicalGuardianRequests({
     status: 'pending',
     requesterExternalUserId: senderExternalUserId,
     sourceChannel,
     kind: 'access_request',
+    conversationId,
   });
   if (existingCanonical.length > 0) {
     log.debug(
@@ -130,7 +152,7 @@ export function notifyGuardianOfAccessRequest(
     kind: 'access_request',
     sourceType: 'channel',
     sourceChannel,
-    conversationId: `access-req-${sourceChannel}-${senderExternalUserId}`,
+    conversationId,
     requesterExternalUserId: senderExternalUserId,
     requesterChatId: externalChatId,
     guardianExternalUserId: guardianExternalUserId ?? undefined,
@@ -139,6 +161,7 @@ export function notifyGuardianOfAccessRequest(
     expiresAt: new Date(Date.now() + GUARDIAN_APPROVAL_TTL_MS).toISOString(),
   });
 
+  let vellumDeliveryId: string | null = null;
   void emitNotificationSignal({
     sourceEventName: 'ingress.access_request',
     sourceChannel,
@@ -160,9 +183,64 @@ export function notifyGuardianOfAccessRequest(
       senderUsername: senderUsername ?? null,
       senderIdentifier,
       guardianBindingChannel,
+      previousMemberStatus: previousMemberStatus ?? null,
     },
     dedupeKey: `access-request:${canonicalRequest.id}`,
-  });
+    onThreadCreated: (info) => {
+      if (info.sourceEventName !== 'ingress.access_request' || vellumDeliveryId) return;
+      const delivery = createCanonicalGuardianDelivery({
+        requestId: canonicalRequest.id,
+        destinationChannel: 'vellum',
+        destinationConversationId: info.conversationId,
+      });
+      vellumDeliveryId = delivery.id;
+    },
+  })
+    .then((signalResult) => {
+      for (const result of signalResult.deliveryResults) {
+        if (result.channel === 'vellum') {
+          if (!vellumDeliveryId) {
+            const delivery = createCanonicalGuardianDelivery({
+              requestId: canonicalRequest.id,
+              destinationChannel: 'vellum',
+              destinationConversationId: result.conversationId,
+            });
+            vellumDeliveryId = delivery.id;
+          }
+          applyDeliveryStatus(vellumDeliveryId, result);
+          continue;
+        }
+
+        if (result.channel !== 'telegram' && result.channel !== 'sms') {
+          continue;
+        }
+
+        const delivery = createCanonicalGuardianDelivery({
+          requestId: canonicalRequest.id,
+          destinationChannel: result.channel,
+          destinationChatId: result.destination.length > 0 ? result.destination : undefined,
+        });
+        applyDeliveryStatus(delivery.id, result);
+      }
+
+      if (!vellumDeliveryId) {
+        const fallback = createCanonicalGuardianDelivery({
+          requestId: canonicalRequest.id,
+          destinationChannel: 'vellum',
+        });
+        updateCanonicalGuardianDelivery(fallback.id, { status: 'failed' });
+        log.warn(
+          { requestId: canonicalRequest.id, reason: signalResult.reason },
+          'Notification pipeline did not produce a vellum delivery result for access request',
+        );
+      }
+    })
+    .catch((err) => {
+      log.error(
+        { err, requestId: canonicalRequest.id, sourceChannel, senderExternalUserId },
+        'Failed to persist access request delivery rows from notification pipeline',
+      );
+    });
 
   log.info(
     { sourceChannel, senderExternalUserId, senderIdentifier, guardianBindingChannel },

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

@@ -0,0 +1,234 @@
+/**
+ * Actor-token mint/verify service.
+ *
+ * Mints HMAC-signed actor tokens bound to (assistantId, guardianPrincipalId,
+ * deviceId, platform). Only the SHA-256 hash of the token is persisted —
+ * the raw plaintext is returned to the caller once and never stored.
+ *
+ * Token format: base64url(JSON claims) + '.' + base64url(HMAC-SHA256 signature)
+ */
+
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { getLogger } from '../util/logger.js';
+import { getRootDir } from '../util/platform.js';
+
+const log = getLogger('actor-token-service');
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ActorTokenClaims {
+  /** The assistant this token is scoped to. */
+  assistantId: string;
+  /** Platform: 'macos' | 'ios' */
+  platform: string;
+  /** Opaque device identifier (hashed for storage). */
+  deviceId: string;
+  /** The guardian principal this token is bound to. */
+  guardianPrincipalId: string;
+  /** Token issuance timestamp (epoch ms). */
+  iat: number;
+  /** Token expiration timestamp (epoch ms). Null means non-expiring. */
+  exp: number | null;
+  /** Random jti (JWT ID) for uniqueness. */
+  jti: string;
+}
+
+export interface MintResult {
+  /** The raw actor token string — returned once, never persisted. */
+  token: string;
+  /** SHA-256 hex hash of the token (for storage/lookup). */
+  tokenHash: string;
+  /** The decoded claims. */
+  claims: ActorTokenClaims;
+}
+
+export type VerifyResult =
+  | { ok: true; claims: ActorTokenClaims }
+  | { ok: false; reason: string };
+
+// ---------------------------------------------------------------------------
+// Signing key management
+// ---------------------------------------------------------------------------
+
+let signingKey: Buffer | null = null;
+
+/**
+ * Path to the persisted signing key file.
+ * Stored in the protected directory alongside other sensitive material.
+ */
+function getSigningKeyPath(): string {
+  return join(getRootDir(), 'protected', 'actor-token-signing-key');
+}
+
+/**
+ * Load a signing key from disk or generate and persist a new one.
+ * Uses the same atomic-write + chmod 0o600 pattern as approved-devices-store.ts.
+ */
+export function loadOrCreateSigningKey(): Buffer {
+  const keyPath = getSigningKeyPath();
+
+  // Try to load existing key
+  if (existsSync(keyPath)) {
+    try {
+      const raw = readFileSync(keyPath);
+      if (raw.length === 32) {
+        log.info('Actor-token signing key loaded from disk');
+        return raw;
+      }
+      log.warn('Signing key file has unexpected length, regenerating');
+    } catch (err) {
+      log.warn({ err }, 'Failed to read signing key file, regenerating');
+    }
+  }
+
+  // Generate and persist a new key
+  const newKey = randomBytes(32);
+  const dir = dirname(keyPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  const tmpPath = keyPath + '.tmp.' + process.pid;
+  writeFileSync(tmpPath, newKey, { mode: 0o600 });
+  renameSync(tmpPath, keyPath);
+  chmodSync(keyPath, 0o600);
+
+  log.info('Actor-token signing key generated and persisted');
+  return newKey;
+}
+
+/**
+ * Initialize (or reinitialize) the signing key. Called at daemon startup
+ * with a key loaded from disk via loadOrCreateSigningKey(), or by tests
+ * with a deterministic key.
+ */
+export function initSigningKey(key: Buffer): void {
+  signingKey = key;
+}
+
+function getSigningKey(): Buffer {
+  if (!signingKey) {
+    throw new Error('Actor-token signing key not initialized — call initSigningKey() during startup');
+  }
+  return signingKey;
+}
+
+// ---------------------------------------------------------------------------
+// Base64url helpers
+// ---------------------------------------------------------------------------
+
+function base64urlEncode(data: Buffer | string): string {
+  const buf = typeof data === 'string' ? Buffer.from(data, 'utf-8') : data;
+  return buf.toString('base64url');
+}
+
+function base64urlDecode(str: string): Buffer {
+  return Buffer.from(str, 'base64url');
+}
+
+// ---------------------------------------------------------------------------
+// Hashing
+// ---------------------------------------------------------------------------
+
+/** SHA-256 hex digest of a raw token string. */
+export function hashToken(token: string): string {
+  return createHash('sha256').update(token).digest('hex');
+}
+
+// ---------------------------------------------------------------------------
+// Mint
+// ---------------------------------------------------------------------------
+
+/** Default TTL for actor tokens: 90 days in milliseconds. */
+const DEFAULT_TOKEN_TTL_MS = 90 * 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.
+ *               Pass `null` explicitly for a non-expiring token.
+ * @returns The raw token, its hash, and the embedded claims.
+ */
+export function mintActorToken(params: {
+  assistantId: string;
+  platform: string;
+  deviceId: string;
+  guardianPrincipalId: string;
+  ttlMs?: number | null;
+}): MintResult {
+  const now = Date.now();
+  const effectiveTtl = params.ttlMs === undefined ? DEFAULT_TOKEN_TTL_MS : params.ttlMs;
+  const claims: ActorTokenClaims = {
+    assistantId: params.assistantId,
+    platform: params.platform,
+    deviceId: params.deviceId,
+    guardianPrincipalId: params.guardianPrincipalId,
+    iat: now,
+    exp: effectiveTtl != null ? now + effectiveTtl : null,
+    jti: randomBytes(16).toString('hex'),
+  };
+
+  const payload = base64urlEncode(JSON.stringify(claims));
+  const sig = createHmac('sha256', getSigningKey())
+    .update(payload)
+    .digest();
+  const token = payload + '.' + base64urlEncode(sig);
+  const tokenHash = hashToken(token);
+
+  return { token, tokenHash, claims };
+}
+
+// ---------------------------------------------------------------------------
+// Verify
+// ---------------------------------------------------------------------------
+
+/**
+ * Verify an actor token's structural integrity and signature.
+ *
+ * Does NOT check revocation — callers must additionally verify the
+ * token hash exists in the actor-token store with status='active'.
+ */
+export function verifyActorToken(token: string): VerifyResult {
+  const dotIndex = token.indexOf('.');
+  if (dotIndex < 0) {
+    return { ok: false, reason: 'malformed_token' };
+  }
+
+  const payload = token.slice(0, dotIndex);
+  const sigPart = token.slice(dotIndex + 1);
+
+  // Recompute HMAC
+  const expectedSig = createHmac('sha256', getSigningKey())
+    .update(payload)
+    .digest();
+  const actualSig = base64urlDecode(sigPart);
+
+  if (expectedSig.length !== actualSig.length) {
+    return { ok: false, reason: 'invalid_signature' };
+  }
+
+  // Constant-time comparison
+  if (!timingSafeEqual(expectedSig, actualSig)) {
+    return { ok: false, reason: 'invalid_signature' };
+  }
+
+  let claims: ActorTokenClaims;
+  try {
+    const decoded = base64urlDecode(payload).toString('utf-8');
+    claims = JSON.parse(decoded) as ActorTokenClaims;
+  } catch {
+    return { ok: false, reason: 'malformed_claims' };
+  }
+
+  // Expiration check
+  if (claims.exp != null && Date.now() > claims.exp) {
+    return { ok: false, reason: 'token_expired' };
+  }
+
+  return { ok: true, claims };
+}

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

@@ -0,0 +1,236 @@
+/**
+ * Hash-only actor token persistence.
+ *
+ * Stores only the SHA-256 hash of each actor token alongside metadata
+ * (assistantId, guardianPrincipalId, deviceId hash, platform, status).
+ * The raw token plaintext is never stored.
+ *
+ * Uses the assistant SQLite database via drizzle-orm.
+ */
+
+import { and, eq } from 'drizzle-orm';
+import { v4 as uuid } from 'uuid';
+
+import { getDb } from '../memory/db.js';
+import { actorTokenRecords } from '../memory/schema.js';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('actor-token-store');
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ActorTokenStatus = 'active' | 'revoked';
+
+export interface ActorTokenRecord {
+  id: string;
+  tokenHash: string;
+  assistantId: string;
+  guardianPrincipalId: string;
+  hashedDeviceId: string;
+  platform: string;
+  status: ActorTokenStatus;
+  issuedAt: number;
+  expiresAt: number | null;
+  createdAt: number;
+  updatedAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// Operations
+// ---------------------------------------------------------------------------
+
+/**
+ * Store a new actor token record (hash-only).
+ */
+export function createActorTokenRecord(params: {
+  tokenHash: string;
+  assistantId: string;
+  guardianPrincipalId: string;
+  hashedDeviceId: string;
+  platform: string;
+  issuedAt: number;
+  expiresAt?: number | null;
+}): ActorTokenRecord {
+  const db = getDb();
+  const now = Date.now();
+  const id = uuid();
+
+  const row = {
+    id,
+    tokenHash: params.tokenHash,
+    assistantId: params.assistantId,
+    guardianPrincipalId: params.guardianPrincipalId,
+    hashedDeviceId: params.hashedDeviceId,
+    platform: params.platform,
+    status: 'active' as const,
+    issuedAt: params.issuedAt,
+    expiresAt: params.expiresAt ?? null,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  db.insert(actorTokenRecords).values(row).run();
+  log.info({ id, assistantId: params.assistantId, platform: params.platform }, 'Actor token record created');
+
+  return row;
+}
+
+/**
+ * Look up an active actor token record by its hash.
+ */
+export function findActiveByTokenHash(tokenHash: string): ActorTokenRecord | null {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(actorTokenRecords)
+    .where(
+      and(
+        eq(actorTokenRecords.tokenHash, tokenHash),
+        eq(actorTokenRecords.status, 'active'),
+      ),
+    )
+    .get();
+
+  return row ? rowToRecord(row) : null;
+}
+
+/**
+ * Find an active token for a specific (assistantId, guardianPrincipalId, deviceId).
+ * Used for idempotent bootstrap — if an active token already exists for this
+ * device binding, we can revoke-and-remint or return the existing record.
+ */
+export function findActiveByDeviceBinding(
+  assistantId: string,
+  guardianPrincipalId: string,
+  hashedDeviceId: string,
+): ActorTokenRecord | null {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(actorTokenRecords)
+    .where(
+      and(
+        eq(actorTokenRecords.assistantId, assistantId),
+        eq(actorTokenRecords.guardianPrincipalId, guardianPrincipalId),
+        eq(actorTokenRecords.hashedDeviceId, hashedDeviceId),
+        eq(actorTokenRecords.status, 'active'),
+      ),
+    )
+    .get();
+
+  return row ? rowToRecord(row) : null;
+}
+
+/**
+ * Revoke all active tokens for a given device binding.
+ * Called before minting a new token to ensure one-active-per-device.
+ */
+export function revokeByDeviceBinding(
+  assistantId: string,
+  guardianPrincipalId: string,
+  hashedDeviceId: string,
+): number {
+  const db = getDb();
+  const now = Date.now();
+
+  const condition = and(
+    eq(actorTokenRecords.assistantId, assistantId),
+    eq(actorTokenRecords.guardianPrincipalId, guardianPrincipalId),
+    eq(actorTokenRecords.hashedDeviceId, hashedDeviceId),
+    eq(actorTokenRecords.status, 'active'),
+  );
+
+  // Count matching rows before the update since drizzle's bun-sqlite
+  // .run() does not expose the underlying changes count in its types.
+  const matching = db
+    .select({ id: actorTokenRecords.id })
+    .from(actorTokenRecords)
+    .where(condition)
+    .all();
+
+  if (matching.length === 0) return 0;
+
+  db.update(actorTokenRecords)
+    .set({ status: 'revoked', updatedAt: now })
+    .where(condition)
+    .run();
+
+  return matching.length;
+}
+
+/**
+ * Find all active actor token records for a given (assistantId, guardianPrincipalId).
+ * Used for multi-device guardian fanout — returns all bound devices (macOS, iOS, etc.)
+ * so notification targeting can reach every device for the same guardian identity.
+ */
+export function findActiveByGuardianPrincipalId(
+  assistantId: string,
+  guardianPrincipalId: string,
+): ActorTokenRecord[] {
+  const db = getDb();
+  const rows = db
+    .select()
+    .from(actorTokenRecords)
+    .where(
+      and(
+        eq(actorTokenRecords.assistantId, assistantId),
+        eq(actorTokenRecords.guardianPrincipalId, guardianPrincipalId),
+        eq(actorTokenRecords.status, 'active'),
+      ),
+    )
+    .all();
+
+  return rows.map(rowToRecord);
+}
+
+/**
+ * Revoke a single token by its hash.
+ */
+export function revokeByTokenHash(tokenHash: string): boolean {
+  const db = getDb();
+  const now = Date.now();
+
+  const condition = and(
+    eq(actorTokenRecords.tokenHash, tokenHash),
+    eq(actorTokenRecords.status, 'active'),
+  );
+
+  // Check existence before update since drizzle's bun-sqlite .run()
+  // does not expose the underlying changes count in its types.
+  const existing = db
+    .select({ id: actorTokenRecords.id })
+    .from(actorTokenRecords)
+    .where(condition)
+    .get();
+
+  if (!existing) return false;
+
+  db.update(actorTokenRecords)
+    .set({ status: 'revoked', updatedAt: now })
+    .where(condition)
+    .run();
+
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function rowToRecord(row: typeof actorTokenRecords.$inferSelect): ActorTokenRecord {
+  return {
+    id: row.id,
+    tokenHash: row.tokenHash,
+    assistantId: row.assistantId,
+    guardianPrincipalId: row.guardianPrincipalId,
+    hashedDeviceId: row.hashedDeviceId,
+    platform: row.platform,
+    status: row.status as ActorTokenStatus,
+    issuedAt: row.issuedAt,
+    expiresAt: row.expiresAt,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}

package/src/runtime/actor-trust-resolver.ts

@@ -17,7 +17,7 @@ import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.
 import type { IngressMember } from '../memory/ingress-member-store.js';
 import { findMember } from '../memory/ingress-member-store.js';
 import { canonicalizeInboundIdentity } from '../util/canonicalize-identity.js';
-import { normalizeAssistantId } from '../util/platform.js';
+import { DAEMON_INTERNAL_ASSISTANT_ID } from './assistant-scope.js';
 import { getGuardianBinding } from './channel-guardian-service.js';
 
 // ---------------------------------------------------------------------------
@@ -76,7 +76,7 @@ export interface ResolveActorTrustInput {
  * 5. Classify: guardian > trusted_contact (active member) > unknown.
  */
 export function resolveActorTrust(input: ResolveActorTrustInput): ActorTrustContext {
-  const assistantId = normalizeAssistantId(input.assistantId);
+  const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
 
   const rawUserId = typeof input.senderExternalUserId === 'string' && input.senderExternalUserId.trim().length > 0
     ? input.senderExternalUserId.trim()

package/src/runtime/assistant-scope.ts

@@ -0,0 +1,10 @@
+/**
+ * Canonical internal scope ID for all daemon-side assistant-scoped storage.
+ *
+ * The daemon uses a single fixed identity (`'self'`) for its own assistant
+ * scope. Public/external assistant IDs are an edge concern owned by the
+ * gateway and platform layers (hatch, invite links, etc.). Daemon code
+ * should never derive scoping decisions from externally-provided assistant
+ * IDs — use this constant instead.
+ */
+export const DAEMON_INTERNAL_ASSISTANT_ID = 'self' as const;

package/src/runtime/channel-approvals.ts

@@ -151,11 +151,13 @@ export function handleChannelDecision(
     if (
       details &&
       details.persistentDecisionsAllowed !== false &&
-      details.allowlistOptions?.length &&
-      details.scopeOptions?.length
+      details.allowlistOptions?.length
     ) {
       const pattern = details.allowlistOptions[0].pattern;
-      const scope = details.scopeOptions[0].scope;
+      // Non-scoped tools (web_fetch, network_request, etc.) have empty
+      // scopeOptions — default to 'everywhere' so approve_always still
+      // persists a trust rule instead of silently degrading to one-time.
+      const scope = details.scopeOptions?.length ? details.scopeOptions[0].scope : 'everywhere';
       // Only persist executionTarget for skill-origin tools — core tools don't
       // set it in their PolicyContext, so a persisted value would prevent the
       // rule from ever matching on subsequent permission checks.