@vellumai/assistant 0.8.6 → 0.8.7-dev.202606052118.34cd356

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

@@ -1,31 +1,39 @@
-import {
-  copyFileSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  unlinkSync,
-} from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
 
 import { z } from "zod";
 
 import { renderCharacterAscii } from "../../avatar/ascii-renderer.js";
+import {
+  type AvatarState,
+  deriveStateFromLegacyFiles,
+  readManifest,
+  writeManifest,
+} from "../../avatar/avatar-manifest.js";
+import {
+  clearAvatar,
+  setCharacter,
+  setImage,
+} from "../../avatar/avatar-store.js";
 import { getCharacterComponents } from "../../avatar/character-components.js";
 import { updateIdentityAvatarSection } from "../../avatar/identity-avatar.js";
 import {
   type CharacterTraits,
+  TRAITS_FILENAME,
   writeTraitsAndRenderAvatar,
 } from "../../avatar/traits-png-sync.js";
 import { setPlatformBaseUrl } from "../../config/env.js";
 import { credentialKey } from "../../security/credential-key.js";
 import { getSecureKeyAsync } from "../../security/secure-keys.js";
-import { generateAndSaveAvatar } from "../../tools/system/avatar-generator.js";
+import { detectMediaType } from "../../tools/shared/filesystem/image-read.js";
+import { generateAvatarImage } from "../../tools/system/avatar-generator.js";
 import { getLogger } from "../../util/logger.js";
 import {
   getAvatarDir,
   getAvatarImagePath,
   getWorkspaceDir,
 } from "../../util/platform.js";
+import { ACTOR_PRINCIPALS, LOCAL_PRINCIPALS } from "../auth/route-policy.js";
 import { publishAvatarChanged } from "../sync/resource-sync-events.js";
 import {
   BadRequestError,
@@ -40,6 +48,50 @@ function handleGetCharacterComponents() {
   return getCharacterComponents();
 }
 
+/**
+ * Reads the manifest, self-healing once if it is absent.
+ *
+ * The migration (092) seeds `avatar.json` for every workspace, so the manifest
+ * is normally present. If it is somehow missing (e.g. a workspace that predates
+ * the manifest and skipped the migration), we derive state from the legacy
+ * sidecar files. A *real* avatar (character/image) is persisted once so
+ * subsequent reads hit the manifest directly; an empty (`none`) result is NOT
+ * persisted, so an avatar-less workspace stays manifest-less and a later legacy
+ * sidecar write is still picked up by the next self-heal (backward compat).
+ */
+function readManifestSelfHealing(): AvatarState {
+  const manifest = readManifest();
+  if (manifest) {
+    return manifest;
+  }
+  const derived = deriveStateFromLegacyFiles();
+  // Only persist a real avatar. Persisting `none` would shadow a later legacy
+  // sidecar write behind a stale manifest (see migration 094 + clearAvatar).
+  // Persist is best-effort: on a read-only / permission-restricted workspace the
+  // write can throw. Swallow it so a GET still returns the derived state instead
+  // of turning into a 500 — the next read simply self-heals again.
+  if (derived.kind !== "none") {
+    try {
+      writeManifest(derived);
+    } catch (err) {
+      log.warn({ err }, "Failed to persist self-healed avatar manifest");
+    }
+  }
+  return derived;
+}
+
+/**
+ * Return the authoritative avatar render state.
+ *
+ * Reads the manifest (`avatar.json`). When the manifest is absent it is
+ * self-healed once from the legacy sidecar files and persisted. Never 404s —
+ * an empty workspace yields `{ kind: "none", traits: null, source: null,
+ * image: null }`.
+ */
+function handleGetAvatarState() {
+  return readManifestSelfHealing();
+}
+
 function handleRenderFromTraits({ body, headers }: RouteHandlerArgs) {
   const traits = body as CharacterTraits | undefined;
 
@@ -55,7 +107,7 @@ function handleRenderFromTraits({ body, headers }: RouteHandlerArgs) {
     );
   }
 
-  const result = writeTraitsAndRenderAvatar(traits);
+  const result = setCharacter(traits);
 
   if (!result.ok) {
     switch (result.reason) {
@@ -92,27 +144,69 @@ async function handleGenerateAvatar({ body, headers }: RouteHandlerArgs) {
     // Non-fatal
   }
 
-  const result = await generateAndSaveAvatar(description);
-  if (result.isError) {
+  const result = await generateAvatarImage(description);
+  if (result.isError || !result.pngBuffer) {
     throw new ServiceUnavailableError(result.content);
   }
 
-  // Remove native character files since AI-generated image takes precedence
-  const avatarDir = getAvatarDir();
-  const traitsPath = join(avatarDir, "character-traits.json");
-  const asciiPath = join(avatarDir, "character-ascii.txt");
-  try {
-    if (existsSync(traitsPath)) unlinkSync(traitsPath);
-    if (existsSync(asciiPath)) unlinkSync(asciiPath);
-  } catch {
-    // Best-effort
-  }
+  // Route through the store: atomically writes the PNG, removes the now-stale
+  // character sidecars (traits + ASCII), and records an AI-sourced manifest.
+  setImage(result.pngBuffer, "ai");
 
   updateIdentityAvatarSection(null, log);
   publishAvatarChanged(headers?.["x-vellum-client-id"]?.trim() || undefined);
   return { ok: true, message: result.content };
 }
 
+/**
+ * Accept a base64-encoded image and set it as the avatar. Replaces the web
+ * client's prior two-call `workspace/write` + `workspace/delete` dance with a
+ * single server-authoritative endpoint: the store atomically writes the PNG,
+ * clears the character sidecars, and records an `image` manifest.
+ */
+function handleUploadAvatarImage({ body, headers }: RouteHandlerArgs) {
+  const payload = body as Record<string, unknown> | undefined;
+  const content = payload?.content;
+  const encoding = payload?.encoding;
+
+  if (typeof content !== "string" || content.length === 0) {
+    throw new BadRequestError("content (base64 string) is required");
+  }
+  if (encoding !== undefined && encoding !== "base64") {
+    throw new BadRequestError('encoding must be "base64"');
+  }
+
+  // Strictly validate the base64 BEFORE decoding. `Buffer.from(.., "base64")`
+  // silently drops characters outside the alphabet, so a valid image prefix
+  // followed by garbage would decode to a truncated/corrupt buffer that still
+  // passes the magic-byte sniff below — accepting a corrupt avatar. Same strict
+  // pattern used by stt-routes / live-voice (tolerating surrounding whitespace).
+  const normalized = content.replace(/\s+/g, "");
+  if (
+    normalized.length === 0 ||
+    !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(
+      normalized,
+    )
+  ) {
+    throw new BadRequestError("content is not valid base64-encoded image data");
+  }
+
+  const buffer = Buffer.from(normalized, "base64");
+  if (detectMediaType(buffer) === null) {
+    throw new BadRequestError(
+      "content must be a PNG, JPEG, GIF, or WEBP image",
+    );
+  }
+
+  // Route through the store: atomically writes the PNG, removes the now-stale
+  // character sidecars (traits + ASCII), and records an uploaded-image manifest.
+  setImage(buffer, "upload");
+
+  updateIdentityAvatarSection(null, log);
+  publishAvatarChanged(headers?.["x-vellum-client-id"]?.trim() || undefined);
+  return { ok: true };
+}
+
 function handleSetAvatar({ body, headers }: RouteHandlerArgs) {
   const imagePath = (body as Record<string, unknown>)?.imagePath as
     | string
@@ -137,9 +231,9 @@ function handleSetAvatar({ body, headers }: RouteHandlerArgs) {
     throw new BadRequestError(`Image file not found: ${normalized}`);
   }
 
-  const avatarPath = getAvatarImagePath();
-  mkdirSync(dirname(avatarPath), { recursive: true });
-  copyFileSync(normalized, avatarPath);
+  // Route through the store so traits sidecars are cleared and the manifest is
+  // recorded as an uploaded image atomically (no more stale both-files state).
+  setImage(readFileSync(normalized), "upload");
 
   updateIdentityAvatarSection(null, log);
   publishAvatarChanged(headers?.["x-vellum-client-id"]?.trim() || undefined);
@@ -147,33 +241,26 @@ function handleSetAvatar({ body, headers }: RouteHandlerArgs) {
 }
 
 function handleRemoveAvatar({ headers }: RouteHandlerArgs) {
-  const avatarPath = getAvatarImagePath();
-
-  if (!existsSync(avatarPath)) {
-    return { ok: true, hadAvatar: false };
-  }
-
-  unlinkSync(avatarPath);
-
-  // Regenerate character PNG from traits if available
-  const traitsPath = join(getAvatarDir(), "character-traits.json");
-  if (existsSync(traitsPath)) {
-    try {
-      const traits = JSON.parse(
-        readFileSync(traitsPath, "utf-8"),
-      ) as CharacterTraits;
-      writeTraitsAndRenderAvatar(traits);
-    } catch {
-      // Best-effort
-    }
-  }
+  // `hadAvatar` must reflect whether *any* avatar was configured before the
+  // clear — not just a rendered PNG. A character-only workspace (traits present,
+  // no PNG) is still an avatar, and clearAvatar() deletes its traits/ascii too.
+  // Derive from the manifest (self-healing on a manifest-miss) and treat any
+  // non-"none" kind as hadAvatar.
+  const hadAvatar = readManifestSelfHealing().kind !== "none";
+
+  // Clear everything to a manifest-consistent kind:"none". Semantic change
+  // (intentional): traits no longer persist alongside an image, so there is
+  // nothing to revert to — the legacy "re-render character from traits" branch
+  // has been removed. avatar/remove is now a plain clear, reachable only via
+  // CLI/host.
+  clearAvatar();
 
   updateIdentityAvatarSection(
     "Default character avatar (no custom image set)",
     log,
   );
   publishAvatarChanged(headers?.["x-vellum-client-id"]?.trim() || undefined);
-  return { ok: true, hadAvatar: true };
+  return { ok: true, hadAvatar };
 }
 
 function handleGetAvatar({ queryParams, body }: RouteHandlerArgs) {
@@ -187,19 +274,27 @@ function handleGetAvatar({ queryParams, body }: RouteHandlerArgs) {
     );
   }
 
+  // Resolve precedence from the manifest so this raster accessor (CLI / dock /
+  // notifications) agrees with macOS/web rather than picking image-first off
+  // file existence. For both `character` and `image` the derived raster is the
+  // same on-disk PNG; only the precedence is manifest-driven. Self-heals once
+  // on manifest-miss so we never re-infer from legacy files per request.
+  const state = readManifestSelfHealing();
+
+  if (state.kind === "none") {
+    return { exists: false };
+  }
+
   const avatarPath = getAvatarImagePath();
 
-  if (!existsSync(avatarPath)) {
-    const traitsPath = join(getAvatarDir(), "character-traits.json");
-    if (existsSync(traitsPath)) {
-      try {
-        const traits = JSON.parse(
-          readFileSync(traitsPath, "utf-8"),
-        ) as CharacterTraits;
-        writeTraitsAndRenderAvatar(traits);
-      } catch {
-        // Best-effort
-      }
+  // For a character, the rendered PNG normally already exists on disk. Keep the
+  // existing safety net: if it's missing, re-render it from the persisted traits
+  // so the accessor still returns a raster.
+  if (state.kind === "character" && !existsSync(avatarPath) && state.traits) {
+    try {
+      writeTraitsAndRenderAvatar(state.traits);
+    } catch {
+      // Best-effort
     }
   }
 
@@ -231,7 +326,7 @@ function handleCharacterAscii({ queryParams, body }: RouteHandlerArgs) {
     );
   }
 
-  const traitsPath = join(getAvatarDir(), "character-traits.json");
+  const traitsPath = join(getAvatarDir(), TRAITS_FILENAME);
   if (!existsSync(traitsPath)) {
     throw new BadRequestError(
       "No native character set. Use 'assistant avatar character update' first.",
@@ -260,15 +355,80 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "avatar_character_components",
     endpoint: "avatar/character-components",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleGetCharacterComponents,
     summary: "Get character components",
     description: "Return available avatar character components.",
     tags: ["avatar"],
+    responseBody: z.object({
+      bodyShapes: z.array(
+        z.object({
+          id: z.string(),
+          viewBox: z.object({ width: z.number(), height: z.number() }),
+          faceCenter: z.object({ x: z.number(), y: z.number() }),
+          svgPath: z.string(),
+        }),
+      ),
+      eyeStyles: z.array(
+        z.object({
+          id: z.string(),
+          sourceViewBox: z.object({ width: z.number(), height: z.number() }),
+          eyeCenter: z.object({ x: z.number(), y: z.number() }),
+          paths: z.array(z.object({ svgPath: z.string(), color: z.string() })),
+        }),
+      ),
+      colors: z.array(z.object({ id: z.string(), hex: z.string() })),
+      faceCenterOverrides: z.array(
+        z.object({
+          bodyShape: z.string(),
+          eyeStyle: z.string(),
+          faceCenter: z.object({ x: z.number(), y: z.number() }),
+        }),
+      ),
+    }),
+  },
+  {
+    operationId: "avatar_get_state",
+    endpoint: "avatar/state",
+    method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    handler: handleGetAvatarState,
+    summary: "Get avatar state",
+    description:
+      "Return the authoritative avatar render mode (character, image, or none).",
+    tags: ["avatar"],
+    responseBody: z.object({
+      kind: z.enum(["character", "image", "none"]),
+      traits: z
+        .object({
+          bodyShape: z.string(),
+          eyeStyle: z.string(),
+          color: z.string(),
+        })
+        .nullable(),
+      source: z.enum(["builder", "upload", "ai"]).nullable(),
+      image: z
+        .object({
+          updatedAt: z.string(),
+          etag: z.string(),
+        })
+        .nullable(),
+    }),
   },
   {
     operationId: "avatar_render_from_traits",
     endpoint: "avatar/render-from-traits",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleRenderFromTraits,
     summary: "Render avatar from traits",
     description: "Write character traits and render an avatar PNG.",
@@ -286,8 +446,14 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "notify_avatar_updated",
     endpoint: "avatar/notify-updated",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: ({ headers }: RouteHandlerArgs) => {
-      publishAvatarChanged(headers?.["x-vellum-client-id"]?.trim() || undefined);
+      publishAvatarChanged(
+        headers?.["x-vellum-client-id"]?.trim() || undefined,
+      );
       return { ok: true };
     },
     summary: "Notify avatar updated",
@@ -301,6 +467,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "avatar_generate",
     endpoint: "avatar/generate",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleGenerateAvatar,
     summary: "Generate AI avatar",
     description: "Generate an AI avatar from a text description and save it.",
@@ -312,6 +482,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "avatar_set",
     endpoint: "avatar/set",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleSetAvatar,
     summary: "Set avatar from image file",
     description: "Copy an image file to the avatar location.",
@@ -319,10 +493,33 @@ export const ROUTES: RouteDefinition[] = [
     requestBody: z.object({ imagePath: z.string() }),
     responseBody: z.object({ ok: z.boolean() }),
   },
+  {
+    operationId: "avatar_upload_image",
+    endpoint: "avatar/image",
+    method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    handler: handleUploadAvatarImage,
+    summary: "Upload avatar image",
+    description:
+      "Upload a base64-encoded image as the avatar; writes the PNG and clears character traits atomically.",
+    tags: ["avatar"],
+    requestBody: z.object({
+      content: z.string(),
+      encoding: z.literal("base64").optional(),
+    }),
+    responseBody: z.object({ ok: z.boolean() }),
+  },
   {
     operationId: "avatar_remove",
     endpoint: "avatar/remove",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleRemoveAvatar,
     summary: "Remove custom avatar",
     description:
@@ -334,6 +531,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "avatar_get",
     endpoint: "avatar/get",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleGetAvatar,
     summary: "Get current avatar",
     description: "Retrieve the current avatar as a file path or base64 string.",
@@ -350,6 +551,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "avatar_character_ascii",
     endpoint: "avatar/character/ascii",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleCharacterAscii,
     summary: "Render character as ASCII art",
     description: "Render the current native character as ASCII art.",

package/src/runtime/routes/background-tool-routes.ts

@@ -12,6 +12,7 @@ import {
   cancelBackgroundTool,
   listBackgroundTools,
 } from "../../tools/background-tool-registry.js";
+import { LOCAL_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -59,6 +60,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "background_tool_list",
     endpoint: "background-tools",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleBackgroundToolList,
     summary: "List active background tools",
     description:
@@ -80,6 +85,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "background_tool_cancel",
     endpoint: "background-tools/cancel",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleBackgroundToolCancel,
     summary: "Cancel a background tool",
     description: "Cancel an active background tool execution by ID.",

package/src/runtime/routes/background-wake-routes.ts

@@ -7,6 +7,7 @@ import {
 import type { BackgroundWakeRuntime } from "../../background-wake/runtime-registry.js";
 import { getBackgroundWakeRuntime } from "../../background-wake/runtime-registry.js";
 import { getLogger } from "../../util/logger.js";
+import { GATEWAY_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError, ServiceUnavailableError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -309,7 +310,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "getBackgroundWakeIntent",
     endpoint: "background-wake/intent",
     method: "GET",
-    policyKey: "background-wake",
+    policy: {
+      requiredScopes: ["internal.write"],
+      allowedPrincipalTypes: GATEWAY_PRINCIPALS,
+    },
     summary: "Get background wake intent",
     description: "Return the current computed background wake intent.",
     tags: ["background-wake"],
@@ -322,7 +326,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "prepareBackgroundWakeSleep",
     endpoint: "background-wake/prepare-sleep",
     method: "POST",
-    policyKey: "background-wake",
+    policy: {
+      requiredScopes: ["internal.write"],
+      allowedPrincipalTypes: GATEWAY_PRINCIPALS,
+    },
     summary: "Prepare for assistant sleep",
     description:
       "Return the current background wake intent and whether sleep should be deferred.",
@@ -337,7 +344,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "drainDueBackgroundWake",
     endpoint: "background-wake/drain-due",
     method: "POST",
-    policyKey: "background-wake",
+    policy: {
+      requiredScopes: ["internal.write"],
+      allowedPrincipalTypes: GATEWAY_PRINCIPALS,
+    },
     summary: "Drain due background wake work",
     description:
       "Run due heartbeat and scheduler work for a background wake lease.",

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

@@ -46,6 +46,7 @@ import type { BackupConfig, BackupDestination } from "../../config/schema.js";
 import { getMemoryCheckpoint } from "../../memory/checkpoints.js";
 import { getLogger } from "../../util/logger.js";
 import { getWorkspaceDir, getWorkspaceHooksDir } from "../../util/platform.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { DefaultPathResolver } from "../migrations/vbundle-import-analyzer.js";
 import { BadRequestError, RouteError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
@@ -493,6 +494,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "backups_list",
     endpoint: "backups",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleBackupList,
     summary: "List backup snapshots",
     description:
@@ -515,6 +520,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "backups_create",
     endpoint: "backups/create",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleBackupCreate,
     summary: "Create a backup snapshot immediately",
     description:
@@ -530,6 +539,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "backups_restore",
     endpoint: "backups/restore",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleBackupRestore,
     summary: "Restore from a backup snapshot",
     description:
@@ -549,6 +562,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "backups_verify",
     endpoint: "backups/verify",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleBackupVerify,
     summary: "Verify a backup snapshot",
     description:
@@ -567,6 +584,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "backup_enable",
     endpoint: "backup/enable",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleBackupEnable,
     summary: "Enable automated backups",
     description:
@@ -583,6 +604,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "backup_disable",
     endpoint: "backup/disable",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleBackupDisable,
     summary: "Disable automated backups",
     description:
@@ -596,6 +621,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "backup_destinations_list",
     endpoint: "backup/destinations",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleBackupDestinationsList,
     summary: "List configured offsite backup destinations",
     description:
@@ -614,6 +643,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "backup_destinations_add",
     endpoint: "backup/destinations/add",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleBackupDestinationsAdd,
     summary: "Add an offsite backup destination",
     description:
@@ -642,6 +675,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "backup_destinations_remove",
     endpoint: "backup/destinations/remove",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleBackupDestinationsRemove,
     summary: "Remove an offsite backup destination",
     description:
@@ -666,6 +703,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "backup_destinations_set_encrypt",
     endpoint: "backup/destinations/set-encrypt",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleBackupDestinationsSetEncrypt,
     summary: "Toggle encryption for an existing destination",
     description:
@@ -691,6 +732,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "backup_status",
     endpoint: "backup/status",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleBackupStatus,
     summary: "Show backup status and next-run timing",
     description: