@vellumai/assistant 0.4.3 → 0.4.4

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

@@ -25,6 +25,7 @@ import type { Provider } from '../../providers/types.js';
 import { getLogger } from '../../util/logger.js';
 import { buildAssistantEvent } from '../assistant-event.js';
 import { DAEMON_INTERNAL_ASSISTANT_ID } from '../assistant-scope.js';
+import { bridgeConfirmationRequestToGuardian } from '../confirmation-request-guardian-bridge.js';
 import { routeGuardianReply } from '../guardian-reply-router.js';
 import { httpError } from '../http-errors.js';
 import type {
@@ -35,48 +36,41 @@ import type {
   RuntimeMessagePayload,
   SendMessageDeps,
 } from '../http-types.js';
+import { resolveLocalIpcGuardianContext } from '../local-actor-identity.js';
+import { type ServerWithRequestIP, verifyHttpActorTokenWithLocalFallback } from '../middleware/actor-token.js';
 import * as pendingInteractions from '../pending-interactions.js';
 
 const log = getLogger('conversation-routes');
 
 const SUGGESTION_CACHE_MAX = 100;
 
-function collectLivePendingConfirmationRequestIds(
+function collectCanonicalGuardianRequestHintIds(
   conversationId: string,
   sourceChannel: string,
   session: import('../../daemon/session.js').Session,
 ): string[] {
-  const pendingInteractionRequestIds = pendingInteractions
-    .getByConversation(conversationId)
-    .filter(
-      (interaction) =>
-        interaction.kind === 'confirmation'
-        && interaction.session === session
-        && session.hasPendingConfirmation(interaction.requestId),
-    )
-    .map((interaction) => interaction.requestId);
-
-  // Query both by destination conversation (via deliveries table) and by
-  // source conversation (direct field). For desktop/HTTP sessions these
-  // often overlap, but the Set dedup below handles that.
-  const pendingCanonicalRequestIds = [
+  const requests = [
     ...listPendingCanonicalGuardianRequestsByDestinationConversation(conversationId, sourceChannel)
-      .filter((request) => request.kind === 'tool_approval')
-      .map((request) => request.id),
+      .map((request) => ({ id: request.id, kind: request.kind })),
     ...listCanonicalGuardianRequests({
       status: 'pending',
       conversationId,
-      kind: 'tool_approval',
-    }).map((request) => request.id),
-  ].filter((requestId) => session.hasPendingConfirmation(requestId));
-
-  return Array.from(new Set([
-    ...pendingInteractionRequestIds,
-    ...pendingCanonicalRequestIds,
-  ]));
+    }).map((request) => ({ id: request.id, kind: request.kind })),
+  ];
+
+  const deduped = new Map<string, string>();
+  for (const request of requests) {
+    if (!deduped.has(request.id)) {
+      deduped.set(request.id, request.kind ?? '');
+    }
+  }
+
+  return Array.from(deduped.entries())
+    .filter(([requestId, kind]) => kind !== 'tool_approval' || session.hasPendingConfirmation(requestId))
+    .map(([requestId]) => requestId);
 }
 
-async function tryConsumeInlineApprovalReply(params: {
+async function tryConsumeCanonicalGuardianReply(params: {
   conversationId: string;
   sourceChannel: string;
   sourceInterface: string;
@@ -90,6 +84,8 @@ async function tryConsumeInlineApprovalReply(params: {
   session: import('../../daemon/session.js').Session;
   onEvent: (msg: ServerMessage) => void;
   approvalConversationGenerator?: ApprovalConversationGenerator;
+  /** Verified actor identity from actor-token middleware. */
+  verifiedActorExternalUserId?: string;
 }): Promise<{ consumed: boolean; messageId?: string }> {
   const {
     conversationId,
@@ -100,42 +96,57 @@ async function tryConsumeInlineApprovalReply(params: {
     session,
     onEvent,
     approvalConversationGenerator,
+    verifiedActorExternalUserId,
   } = params;
   const trimmedContent = content.trim();
 
-  // Try inline approval interception whenever a pending confirmation exists.
-  // We intentionally do not block on queue depth: after an auto-deny, users
-  // often retry with "approve"/"yes" while the queue is still draining, and
-  // requiring an empty queue can create a deny/retry cascade.
-  if (
-    !session.hasAnyPendingConfirmation()
-    || trimmedContent.length === 0
-  ) {
+  if (trimmedContent.length === 0) {
     return { consumed: false };
   }
 
-  const pendingRequestIds = collectLivePendingConfirmationRequestIds(conversationId, sourceChannel, session);
-  if (pendingRequestIds.length === 0) {
-    return { consumed: false };
-  }
+  const pendingRequestHintIds = collectCanonicalGuardianRequestHintIds(conversationId, sourceChannel, session);
+  const pendingRequestIds = pendingRequestHintIds.length > 0 ? pendingRequestHintIds : undefined;
 
   const routerResult = await routeGuardianReply({
     messageText: trimmedContent,
     channel: sourceChannel,
     actor: {
-      externalUserId: undefined,
+      externalUserId: verifiedActorExternalUserId,
       channel: sourceChannel,
-      isTrusted: true,
+      // When a verified identity is available, disable the trusted bypass so
+      // that the identity-match checks in applyCanonicalGuardianDecision
+      // actually run. Only fall back to isTrusted when no verified identity
+      // was resolved (defensive — shouldn't happen for vellum since
+      // verification runs upstream).
+      isTrusted: !verifiedActorExternalUserId,
     },
     conversationId,
     pendingRequestIds,
     approvalConversationGenerator,
+    emissionContext: {
+      source: 'inline_nl',
+      decisionText: trimmedContent,
+    },
   });
 
   if (!routerResult.consumed || routerResult.type === 'nl_keep_pending') {
     return { consumed: false };
   }
 
+  // Success-path emissions (approved/denied) are handled centrally
+  // by handleConfirmationResponse (called via the resolver chain).
+  // However, stale/failed paths never reach handleConfirmationResponse,
+  // so we emit resolved_stale here for those cases.
+  if (routerResult.requestId && !routerResult.decisionApplied) {
+    session.emitConfirmationStateChanged({
+      sessionId: conversationId,
+      requestId: routerResult.requestId,
+      state: 'resolved_stale',
+      source: 'inline_nl',
+      decisionText: trimmedContent,
+    });
+  }
+
   // Decision has been applied — transcript persistence is best-effort.
   // If DB writes fail, we still return consumed: true so the approval text
   // is not re-processed as a new user turn.
@@ -336,7 +347,7 @@ function makeHubPublisher(
       // via applyCanonicalGuardianDecision.
       const guardianContext = session.guardianContext;
       const sourceChannel = guardianContext?.sourceChannel ?? 'vellum';
-      createCanonicalGuardianRequest({
+      const canonicalRequest = createCanonicalGuardianRequest({
         id: msg.requestId,
         kind: 'tool_approval',
         sourceType: resolveCanonicalRequestSourceType(sourceChannel),
@@ -350,6 +361,18 @@ function makeHubPublisher(
         requestCode: generateCanonicalRequestCode(),
         expiresAt: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
       });
+
+      // For trusted-contact sessions, bridge to guardian.question so the
+      // guardian gets notified and can approve via callback/request-code.
+      if (guardianContext) {
+        bridgeConfirmationRequestToGuardian({
+          canonicalRequest,
+          guardianContext,
+          conversationId,
+          toolName: msg.toolName,
+          assistantId: session.assistantId ?? DAEMON_INTERNAL_ASSISTANT_ID,
+        });
+      }
     } else if (msg.type === 'secret_request') {
       pendingInteractions.register(msg.requestId, {
         session,
@@ -384,6 +407,7 @@ export async function handleSendMessage(
     sendMessageDeps?: SendMessageDeps;
     approvalConversationGenerator?: ApprovalConversationGenerator;
   },
+  server: ServerWithRequestIP,
 ): Promise<Response> {
   const body = await req.json() as {
     conversationKey?: string;
@@ -441,31 +465,68 @@ export async function handleSendMessage(
 
   // ── Queue-if-busy path (preferred when sendMessageDeps is wired) ────
   if (deps.sendMessageDeps) {
+    // Vellum HTTP requests prefer actor-token identity. When absent (e.g. CLI
+    // bearer-auth only), fall back to local IPC identity resolution so
+    // bearer-authenticated local clients are not rejected.
+    const actorVerification = sourceChannel === 'vellum' ? verifyHttpActorTokenWithLocalFallback(req, server) : null;
+    if (actorVerification && !actorVerification.ok) {
+      return httpError(
+        actorVerification.status === 401 ? 'UNAUTHORIZED' : 'FORBIDDEN',
+        actorVerification.message,
+        actorVerification.status,
+      );
+    }
+
     const smDeps = deps.sendMessageDeps;
     const session = await smDeps.getOrCreateSession(mapping.conversationId);
-    // HTTP API is a trusted local ingress (same as IPC) — set guardian context
-    // so that memory extraction is not silently disabled by unverified provenance.
-    session.setGuardianContext({ trustClass: 'guardian', sourceChannel: sourceChannel ?? 'http' });
+    // Resolve actor identity from the verified actor token. The token's
+    // guardianPrincipalId is matched against the vellum guardian binding
+    // through the standard trust pipeline.
+    if (actorVerification?.ok) {
+      session.setGuardianContext(actorVerification.guardianContext);
+    } else {
+      // Non-vellum channels through the HTTP API are still local
+      // authenticated requests. Resolve guardian context via the local
+      // identity pathway (vellum binding lookup) to preserve guardian
+      // trust. Falls back to a minimal guardian context if no binding
+      // exists (pre-bootstrap).
+      session.setGuardianContext(
+        resolveLocalIpcGuardianContext(sourceChannel) ?? { trustClass: 'guardian', sourceChannel },
+      );
+    }
     const onEvent = makeHubPublisher(smDeps, mapping.conversationId, session);
+    // Route server-authoritative state signals (confirmation_state_changed,
+    // assistant_activity_state) to the SSE hub. Without this, these signals
+    // only travel through session.sendToClient, which is a no-op for
+    // socketless HTTP sessions.
+    session.setStateSignalListener(onEvent);
 
     const attachments = hasAttachments
       ? smDeps.resolveAttachments(attachmentIds)
       : [];
 
-    // Try to consume the message as an inline approval/rejection reply.
+    // Resolve the verified actor's external user ID for inline approval
+    // routing. Uses the guardianExternalUserId from the verified context
+    // (actor-token or local-fallback) rather than hardcoding undefined.
+    const verifiedActorExternalUserId = actorVerification?.ok
+      ? actorVerification.guardianContext.guardianExternalUserId
+      : undefined;
+
+    // Try to consume the message as a canonical guardian approval/rejection reply.
     // On failure, degrade to the existing queue/auto-deny path rather than
     // surfacing a 500 — mirrors the IPC handler's catch-and-fallback.
     try {
-      const inlineReplyResult = await tryConsumeInlineApprovalReply({
+      const inlineReplyResult = await tryConsumeCanonicalGuardianReply({
         conversationId: mapping.conversationId,
         sourceChannel,
         sourceInterface,
         content: content ?? '',
-      attachments,
-      session,
-      onEvent,
-      approvalConversationGenerator: deps.approvalConversationGenerator,
-    });
+        attachments,
+        session,
+        onEvent,
+        approvalConversationGenerator: deps.approvalConversationGenerator,
+        verifiedActorExternalUserId,
+      });
       if (inlineReplyResult.consumed) {
         return Response.json(
           { accepted: true, ...(inlineReplyResult.messageId ? { messageId: inlineReplyResult.messageId } : {}) },
@@ -480,6 +541,18 @@ export async function handleSendMessage(
       // If a tool confirmation is pending, auto-deny it so the agent
       // can finish the current turn and process this queued message.
       if (session.hasAnyPendingConfirmation()) {
+        // Emit authoritative denial state for each pending request.
+        // The onStateSignal listener routes these to the SSE hub automatically.
+        for (const interaction of pendingInteractions.getByConversation(mapping.conversationId)) {
+          if (interaction.session === session && interaction.kind === 'confirmation') {
+            session.emitConfirmationStateChanged({
+              sessionId: mapping.conversationId,
+              requestId: interaction.requestId,
+              state: 'denied' as const,
+              source: 'auto_deny' as const,
+            });
+          }
+        }
         session.denyAllPendingConfirmations();
         pendingInteractions.removeBySession(session);
       }
@@ -534,12 +607,27 @@ export async function handleSendMessage(
     return httpError('SERVICE_UNAVAILABLE', 'Message processing not configured', 503);
   }
 
+  // Require actor token for vellum channel requests on the legacy path too,
+  // with local IPC fallback for bearer-authenticated CLI clients.
+  const legacyActorVerification = sourceChannel === 'vellum' ? verifyHttpActorTokenWithLocalFallback(req, server) : null;
+  if (legacyActorVerification && !legacyActorVerification.ok) {
+    return httpError(
+      legacyActorVerification.status === 401 ? 'UNAUTHORIZED' : 'FORBIDDEN',
+      legacyActorVerification.message,
+      legacyActorVerification.status,
+    );
+  }
+
+  const guardianContext = legacyActorVerification?.ok
+    ? legacyActorVerification.guardianContext
+    : resolveLocalIpcGuardianContext(sourceChannel) ?? { trustClass: 'guardian' as const, sourceChannel };
+
   try {
     const result = await processor(
       mapping.conversationId,
       content ?? '',
       hasAttachments ? attachmentIds : undefined,
-      { guardianContext: { trustClass: 'guardian', sourceChannel } },
+      { guardianContext },
       sourceChannel,
       sourceInterface,
     );

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

@@ -3,7 +3,9 @@
  *
  * GET /v1/events?conversationKey=...
  *
- * Auth is enforced by RuntimeHttpServer before this handler is called.
+ * Bearer auth is enforced by RuntimeHttpServer before this handler is called.
+ * Actor-token identity verification (with local CLI fallback) is performed
+ * within this handler to bind the SSE stream to a verified actor identity.
  * Subscribers receive all assistant events scoped to the given conversation.
  */
 
@@ -13,6 +15,7 @@ import type { AssistantEventSubscription } from '../assistant-event-hub.js';
 import { AssistantEventHub,assistantEventHub } from '../assistant-event-hub.js';
 import { DAEMON_INTERNAL_ASSISTANT_ID } from '../assistant-scope.js';
 import { httpError } from '../http-errors.js';
+import { type ServerWithRequestIP, verifyHttpActorTokenWithLocalFallback } from '../middleware/actor-token.js';
 
 /** Keep-alive comment sent to idle clients every 30 s by default. */
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
@@ -30,11 +33,23 @@ const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
 export function handleSubscribeAssistantEvents(
   req: Request,
   url: URL,
-  options?: {
-    hub?: AssistantEventHub;
-    heartbeatIntervalMs?: number;
-  },
+  options?:
+    | { hub?: AssistantEventHub; heartbeatIntervalMs?: number; skipActorVerification?: false; server: ServerWithRequestIP }
+    | { hub?: AssistantEventHub; heartbeatIntervalMs?: number; skipActorVerification: true },
 ): Response {
+  // Verify actor-token identity for vellum channel requests, with local
+  // CLI fallback for bearer-authenticated clients without X-Actor-Token.
+  if (options && !options.skipActorVerification) {
+    const actorVerification = verifyHttpActorTokenWithLocalFallback(req, options.server);
+    if (!actorVerification.ok) {
+      return httpError(
+        actorVerification.status === 401 ? 'UNAUTHORIZED' : 'FORBIDDEN',
+        actorVerification.message,
+        actorVerification.status,
+      );
+    }
+  }
+
   const conversationKey = url.searchParams.get('conversationKey');
   if (!conversationKey) {
     return httpError('BAD_REQUEST', 'conversationKey is required', 400);

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

@@ -3,6 +3,10 @@
  *
  * These endpoints let desktop clients fetch pending guardian prompts and
  * submit button decisions without relying on text parsing.
+ *
+ * All guardian action endpoints require a valid actor token via the
+ * X-Actor-Token header (with local CLI fallback). Guardian decisions
+ * additionally verify the actor is the bound guardian.
  */
 import {
   applyCanonicalGuardianDecision,
@@ -16,6 +20,12 @@ import type { ApprovalAction } from '../channel-approval-types.js';
 import type { GuardianDecisionPrompt } from '../guardian-decision-types.js';
 import { buildDecisionActions } from '../guardian-decision-types.js';
 import { httpError } from '../http-errors.js';
+import {
+  isActorBoundGuardian,
+  isLocalFallbackBoundGuardian,
+  type ServerWithRequestIP,
+  verifyHttpActorTokenWithLocalFallback,
+} from '../middleware/actor-token.js';
 
 // ---------------------------------------------------------------------------
 // GET /v1/guardian-actions/pending?conversationId=...
@@ -23,12 +33,22 @@ import { httpError } from '../http-errors.js';
 
 /**
  * List pending guardian decision prompts for a conversation.
+ * Requires a valid actor token.
  *
  * Returns guardian approval requests (from the channel guardian store) that
  * are still pending, mapped to the GuardianDecisionPrompt shape so clients
  * can render structured button UIs.
  */
-export function handleGuardianActionsPending(req: Request): Response {
+export function handleGuardianActionsPending(req: Request, server: ServerWithRequestIP): Response {
+  const tokenResult = verifyHttpActorTokenWithLocalFallback(req, server);
+  if (!tokenResult.ok) {
+    return httpError(
+      tokenResult.status === 401 ? 'UNAUTHORIZED' : 'FORBIDDEN',
+      tokenResult.message,
+      tokenResult.status,
+    );
+  }
+
   const url = new URL(req.url);
   const conversationId = url.searchParams.get('conversationId');
 
@@ -46,12 +66,28 @@ export function handleGuardianActionsPending(req: Request): Response {
 
 /**
  * Submit a guardian action decision.
+ * Requires a valid actor token for a bound guardian.
  *
  * Routes all decisions through the unified canonical guardian decision
  * primitive which handles CAS resolution, resolver dispatch, and grant
  * minting.
  */
-export async function handleGuardianActionDecision(req: Request): Promise<Response> {
+export async function handleGuardianActionDecision(req: Request, server: ServerWithRequestIP): Promise<Response> {
+  const tokenResult = verifyHttpActorTokenWithLocalFallback(req, server);
+  if (!tokenResult.ok) {
+    return httpError(
+      tokenResult.status === 401 ? 'UNAUTHORIZED' : 'FORBIDDEN',
+      tokenResult.message,
+      tokenResult.status,
+    );
+  }
+  const isBoundGuardian = tokenResult.claims
+    ? isActorBoundGuardian(tokenResult.claims)
+    : isLocalFallbackBoundGuardian();
+  if (!isBoundGuardian) {
+    return httpError('FORBIDDEN', 'Actor is not the bound guardian for this channel', 403);
+  }
+
   const body = await req.json() as {
     requestId?: string;
     action?: string;
@@ -82,11 +118,17 @@ export async function handleGuardianActionDecision(req: Request): Promise<Respon
     }
   }
 
+  // Resolve the actor's external user ID: from the token claims if present,
+  // otherwise from the vellum guardian binding (local fallback).
+  const actorExternalUserId = tokenResult.claims
+    ? tokenResult.claims.guardianPrincipalId
+    : tokenResult.guardianContext.guardianExternalUserId;
+
   const canonicalResult = await applyCanonicalGuardianDecision({
     requestId,
     action: action as ApprovalAction,
     actorContext: {
-      externalUserId: undefined,
+      externalUserId: actorExternalUserId,
       channel: 'vellum',
       isTrusted: true,
     },

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

@@ -741,6 +741,35 @@ export async function handleApprovalInterception(
         }
         return { handled: true, type: 'decision_applied' };
       }
+
+      // Guard: non-guardian actors with a guardian binding must not self-approve
+      // even when no guardian approval row exists yet. The guardian approval
+      // row is created asynchronously when the approval prompt is delivered
+      // to the guardian. In the window between the pending confirmation being
+      // created (isInteractive=true) and the guardian approval row being
+      // persisted, any non-guardian actor could otherwise fall through to the
+      // standard conversational engine / legacy parser and resolve their own
+      // pending request via handleChannelDecision.
+      if (guardianCtx.trustClass !== 'guardian' && guardianCtx.guardianExternalUserId) {
+        log.info(
+          { conversationId, externalChatId, guardianExternalUserId: guardianCtx.guardianExternalUserId },
+          'Blocking non-guardian self-approval: pending confirmation exists but guardian approval row not yet created',
+        );
+        try {
+          const pendingText = await composeApprovalMessageGenerative({
+            scenario: 'request_pending_guardian',
+            channel: sourceChannel,
+          }, {}, approvalCopyGenerator);
+          await deliverChannelReply(replyCallbackUrl, {
+            chatId: externalChatId,
+            text: pendingText,
+            assistantId,
+          }, bearerToken);
+        } catch (err) {
+          log.error({ err, conversationId }, 'Failed to deliver guardian-pending notice to non-guardian actor (pre-row guard)');
+        }
+        return { handled: true, type: 'assistant_turn' };
+      }
     }
   }
 

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

@@ -0,0 +1,145 @@
+/**
+ * POST /v1/integrations/guardian/vellum/bootstrap
+ *
+ * Idempotent bootstrap endpoint for the vellum guardian channel.
+ * Creates or confirms a guardianPrincipalId and channel='vellum'
+ * guardian binding, then mints and returns an actor token bound
+ * to (assistantId, guardianPrincipalId, deviceId).
+ *
+ * Only the hashed token is persisted.
+ */
+
+import { createHash } from 'node:crypto';
+
+import { v4 as uuid } from 'uuid';
+
+import {
+  createBinding,
+  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 { DAEMON_INTERNAL_ASSISTANT_ID } from '../assistant-scope.js';
+import { httpError } from '../http-errors.js';
+import type { ServerWithRequestIP } from '../middleware/actor-token.js';
+
+const log = getLogger('guardian-bootstrap');
+
+/** Hash a device ID for storage (same pattern as approved-devices-store). */
+function hashDeviceId(deviceId: string): string {
+  return createHash('sha256').update(deviceId).digest('hex');
+}
+
+/**
+ * Ensure a guardianPrincipalId exists for the vellum channel.
+ * If a binding already exists, returns the existing guardianExternalUserId
+ * as the principal. Otherwise creates a new binding with a fresh principal.
+ */
+function ensureGuardianPrincipal(assistantId: string): {
+  guardianPrincipalId: string;
+  isNew: boolean;
+} {
+  const existing = getActiveBinding(assistantId, 'vellum');
+  if (existing) {
+    return { guardianPrincipalId: existing.guardianExternalUserId, isNew: false };
+  }
+
+  // Mint a new principal ID for the vellum channel
+  const guardianPrincipalId = `vellum-principal-${uuid()}`;
+
+  createBinding({
+    assistantId,
+    channel: 'vellum',
+    guardianExternalUserId: guardianPrincipalId,
+    guardianDeliveryChatId: 'local',
+    verifiedVia: 'bootstrap',
+    metadataJson: JSON.stringify({ bootstrappedAt: Date.now() }),
+  });
+
+  log.info({ assistantId, guardianPrincipalId }, 'Created vellum guardian principal via bootstrap');
+  return { guardianPrincipalId, isNew: true };
+}
+
+/** Loopback addresses — used to gate the bootstrap endpoint to local-only. */
+const LOOPBACK_ADDRESSES = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+
+/**
+ * Handle POST /v1/integrations/guardian/vellum/bootstrap
+ *
+ * Body: { platform: 'macos', deviceId: string }
+ * Returns: { guardianPrincipalId, actorToken, isNew }
+ *
+ * This endpoint is loopback-only (macOS local use only). iOS devices
+ * obtain actor tokens exclusively through the QR pairing flow.
+ */
+export async function handleGuardianBootstrap(req: Request, server: ServerWithRequestIP): Promise<Response> {
+  // Reject proxied requests — bootstrap is local-only
+  if (req.headers.get('x-forwarded-for')) {
+    return httpError('FORBIDDEN', 'Bootstrap endpoint is local-only', 403);
+  }
+
+  // Reject non-loopback peers
+  const peerIp = server.requestIP(req)?.address;
+  if (!peerIp || !LOOPBACK_ADDRESSES.has(peerIp)) {
+    return httpError('FORBIDDEN', 'Bootstrap endpoint is local-only', 403);
+  }
+
+  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() : '';
+
+    if (!platform || !deviceId) {
+      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);
+    }
+
+    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({
+      assistantId,
+      platform,
+      deviceId,
+      guardianPrincipalId,
+    });
+
+    // Store only the hash
+    createActorTokenRecord({
+      tokenHash,
+      assistantId,
+      guardianPrincipalId,
+      hashedDeviceId,
+      platform,
+      issuedAt: claims.iat,
+      expiresAt: claims.exp,
+    });
+
+    log.info(
+      { assistantId, platform, guardianPrincipalId, isNew },
+      'Guardian bootstrap completed',
+    );
+
+    return Response.json({
+      guardianPrincipalId,
+      actorToken: token,
+      isNew,
+    });
+  } catch (err) {
+    log.error({ err }, 'Guardian bootstrap failed');
+    return httpError('INTERNAL_ERROR', 'Internal server error', 500);
+  }
+}