@vellumai/assistant 0.8.6 → 0.8.7

package/src/runtime/routes/acp-routes.test.ts

@@ -5,9 +5,8 @@
  *  - POST /v1/acp/spawn — the three failure paths produced by
  *    `resolveAcpAgent` (acp_disabled, unknown_agent, binary_not_found).
  *  - POST /v1/acp/spawn (env injection) — CLAUDE_CODE_OAUTH_TOKEN is read
- *    from the secure store under the canonical
- *    `credential/acp/claude_oauth_token` key (built by `credentialKey()`)
- *    and merged into `agentConfig.env` ONLY for the `claude` agent.
+ *    from the credential broker (policy-gated + audited) and merged into
+ *    `agentConfig.env` ONLY for the `claude` agent.
  *  - DELETE /v1/acp/sessions?status=completed — the bulk-clear route that
  *    wipes terminal-state rows (completed/failed/cancelled) from
  *    `acp_session_history` while leaving running/initializing rows intact.
@@ -84,12 +83,83 @@ mock.module("../../acp/index.js", () => ({
   }),
 }));
 
-// Stub secure-keys so env-injection tests can plant a known token (or
-// absence). Driven via `secureKeyStore` per test in beforeEach.
-const secureKeyStore = new Map<string, string>();
+// Stub credential broker + metadata store so env-injection tests can plant
+// a known token (or absence) without touching the real credential store.
+// The broker mock mirrors the real serverUse policy: metadata must exist
+// and allowedTools must include the requesting tool.
+const vaultStore = new Map<string, string>();
+const metadataStore = new Map<
+  string,
+  { allowedTools: string[]; usageDescription?: string }
+>();
+
+mock.module("../../tools/credentials/metadata-store.js", () => ({
+  getCredentialMetadata: (service: string, field: string) => {
+    const key = `${service}/${field}`;
+    const entry = metadataStore.get(key);
+    if (!entry) return undefined;
+    return {
+      credentialId: `cred-${key}`,
+      service,
+      field,
+      allowedTools: entry.allowedTools,
+      allowedDomains: [],
+      usageDescription: entry.usageDescription,
+      createdAt: 0,
+      updatedAt: 0,
+    };
+  },
+  upsertCredentialMetadata: (
+    service: string,
+    field: string,
+    policy?: { allowedTools?: string[]; usageDescription?: string },
+  ) => {
+    const key = `${service}/${field}`;
+    const existing = metadataStore.get(key);
+    metadataStore.set(key, {
+      allowedTools: policy?.allowedTools ?? existing?.allowedTools ?? [],
+      usageDescription:
+        policy?.usageDescription ?? existing?.usageDescription,
+    });
+    return {
+      credentialId: `cred-${key}`,
+      service,
+      field,
+      allowedTools: metadataStore.get(key)!.allowedTools,
+      allowedDomains: [],
+      createdAt: 0,
+      updatedAt: 0,
+    };
+  },
+}));
 
-mock.module("../../security/secure-keys.js", () => ({
-  getSecureKeyAsync: async (key: string) => secureKeyStore.get(key),
+mock.module("../../tools/credentials/broker.js", () => ({
+  credentialBroker: {
+    serverUse: async <T>(request: {
+      service: string;
+      field: string;
+      toolName: string;
+      execute: (value: string) => Promise<T>;
+    }) => {
+      const key = `${request.service}/${request.field}`;
+      const meta = metadataStore.get(key);
+      if (!meta) {
+        return { success: false, reason: `No credential found for ${key}` };
+      }
+      if (!meta.allowedTools.includes(request.toolName)) {
+        return {
+          success: false,
+          reason: `Tool "${request.toolName}" not allowed`,
+        };
+      }
+      const value = vaultStore.get(key);
+      if (!value) {
+        return { success: false, reason: `No stored value for ${key}` };
+      }
+      const result = await request.execute(value);
+      return { success: true, result };
+    },
+  },
 }));
 
 import { eq } from "drizzle-orm";
@@ -113,7 +183,8 @@ beforeEach(() => {
   config.setConfig({});
   which.setWhich((cmd) => `/usr/local/bin/${cmd}`);
   capturedSpawns.length = 0;
-  secureKeyStore.clear();
+  vaultStore.clear();
+  metadataStore.clear();
 });
 
 // ---------------------------------------------------------------------------
@@ -186,29 +257,27 @@ describe("POST /v1/acp/spawn", () => {
 //
 // claude-agent-acp authenticates via CLAUDE_CODE_OAUTH_TOKEN. The route
 // accepts the token from two provisioning routes:
-//   1. Secure store under the canonical `credential/acp/claude_oauth_token`
-//      key (built by `credentialKey()`), populated by
-//      `assistant credentials set --service acp --field claude_oauth_token`.
+//   1. Credential broker (policy-gated + audited) reading from the secure
+//      store — provisioned via `assistant credentials set --service acp
+//      --field claude_oauth_token`.
 //   2. `acp.agents.claude.env.CLAUDE_CODE_OAUTH_TOKEN` in the user's
 //      config.json, surfaced on `resolved.agent.env` by the resolver.
-// After merging the secure-store value into `agentConfig.env`, the route
-// preflights for the token and throws `FailedDependencyError` if it is
-// still absent. The "fail-fast" behavior is symmetric with the existing
-// `binary_not_found` preflight and avoids the zombie-subprocess footgun
-// where claude-agent-acp launches, crashes on auth, and leaves the
-// caller with no useful signal.
+// After broker-mediated resolution, the route preflights for the token
+// and throws `FailedDependencyError` if it is still absent.
 //
 // These tests pin both the happy paths and the throw path so a future
 // drift in the key path, the env-override route, or the preflight check
 // fails the suite loudly.
 // ---------------------------------------------------------------------------
 
+/** Seed a vault entry to simulate `assistant credentials set`. */
+function seedVaultToken(token: string): void {
+  vaultStore.set("acp/claude_oauth_token", token);
+}
+
 describe("POST /v1/acp/spawn — CLAUDE_CODE_OAUTH_TOKEN injection", () => {
-  test("injects CLAUDE_CODE_OAUTH_TOKEN from credential/acp/claude_oauth_token for the claude agent", async () => {
-    secureKeyStore.set(
-      "credential/acp/claude_oauth_token",
-      "test-token-abc123",
-    );
+  test("injects CLAUDE_CODE_OAUTH_TOKEN from the vault via the broker for the claude agent", async () => {
+    seedVaultToken("test-token-abc123");
 
     const handler = getSpawnHandler();
     await handler({
@@ -226,11 +295,7 @@ describe("POST /v1/acp/spawn — CLAUDE_CODE_OAUTH_TOKEN injection", () => {
     );
   });
 
-  test("accepts CLAUDE_CODE_OAUTH_TOKEN from acp.agents.claude.env (config.json override) without a secure-store entry", async () => {
-    // The user-supplied config.json env override is the first-priority
-    // provisioning route. resolveAcpAgent returns it on `resolved.agent.env`,
-    // which the route then preserves on `agentConfig.env`. The preflight
-    // should accept this path with no secure-store entry needed.
+  test("accepts CLAUDE_CODE_OAUTH_TOKEN from acp.agents.claude.env (config.json override) without a vault entry", async () => {
     config.setConfig({
       agents: {
         claude: {
@@ -256,12 +321,8 @@ describe("POST /v1/acp/spawn — CLAUDE_CODE_OAUTH_TOKEN injection", () => {
     );
   });
 
-  test("config.json env override wins over a secure-store token (precedence pin)", async () => {
-    // Codex review feedback (PR #31901 / P2): when a user explicitly sets
-    // CLAUDE_CODE_OAUTH_TOKEN under `acp.agents.<id>.env` (per-workspace,
-    // rotated, scoped credential, etc.), the secure-store value must NOT
-    // silently overwrite it. Vault is fallback, not override.
-    secureKeyStore.set("credential/acp/claude_oauth_token", "vault-token-AAA");
+  test("config.json env override wins over a vault token (precedence pin)", async () => {
+    seedVaultToken("vault-token-AAA");
     config.setConfig({
       agents: {
         claude: {
@@ -288,11 +349,7 @@ describe("POST /v1/acp/spawn — CLAUDE_CODE_OAUTH_TOKEN injection", () => {
   });
 
   test("injects via command match for a user-defined agent id aliased to claude-agent-acp", async () => {
-    // Codex review feedback (PR #31901 / P2): gating is keyed off the
-    // resolved command (basename), not the agent id. A custom agent id
-    // pointing at claude-agent-acp still needs CLAUDE_CODE_OAUTH_TOKEN,
-    // so injection + preflight must fire regardless of the id string.
-    secureKeyStore.set("credential/acp/claude_oauth_token", "vault-token-zzz");
+    seedVaultToken("vault-token-zzz");
     config.setConfig({
       agents: {
         "my-claude": {
@@ -319,12 +376,6 @@ describe("POST /v1/acp/spawn — CLAUDE_CODE_OAUTH_TOKEN injection", () => {
   });
 
   test("throws FailedDependencyError when no CLAUDE_CODE_OAUTH_TOKEN is available from any source", async () => {
-    // secureKeyStore intentionally empty AND no agentConfig.env override —
-    // simulates a fresh install where the user hasn't provisioned a token
-    // via either route. Fail-fast preflight surfaces this immediately
-    // instead of letting claude-agent-acp launch, crash on auth, and leave
-    // a zombie subprocess behind.
-
     const handler = getSpawnHandler();
     await expect(
       handler({
@@ -339,14 +390,7 @@ describe("POST /v1/acp/spawn — CLAUDE_CODE_OAUTH_TOKEN injection", () => {
   });
 
   test("does NOT inject CLAUDE_CODE_OAUTH_TOKEN for agents whose command is not claude-agent-acp", async () => {
-    // Token-injection AND preflight are scoped to claude-agent-acp by
-    // command basename. A codex-acp spawn with the secure-store key set
-    // must still launch without that env var — and must not be blocked
-    // by claude's preflight.
-    secureKeyStore.set(
-      "credential/acp/claude_oauth_token",
-      "test-token-abc123",
-    );
+    seedVaultToken("test-token-abc123");
 
     const handler = getSpawnHandler();
     await handler({
@@ -363,28 +407,6 @@ describe("POST /v1/acp/spawn — CLAUDE_CODE_OAUTH_TOKEN injection", () => {
       capturedSpawns[0]?.agentConfig.env?.CLAUDE_CODE_OAUTH_TOKEN,
     ).toBeUndefined();
   });
-
-  test("does NOT pick up a token planted at the legacy non-`credential/` key path", async () => {
-    // Regression guard: the original implementation used the raw key
-    // "acp/claude/oauth_token". The fix routes through `credentialKey()`
-    // so the CLI (`assistant credentials set --service acp --field
-    // claude_oauth_token`) is the canonical provisioning path. Pin this
-    // by planting the token ONLY under the legacy key — the preflight
-    // should fail-fast because the canonical path is empty.
-    secureKeyStore.set("acp/claude/oauth_token", "legacy-token-should-miss");
-
-    const handler = getSpawnHandler();
-    await expect(
-      handler({
-        body: {
-          agent: "claude",
-          task: "do a thing",
-          conversationId: "conv-1",
-        },
-      }),
-    ).rejects.toThrow(/CLAUDE_CODE_OAUTH_TOKEN/);
-    expect(capturedSpawns).toHaveLength(0);
-  });
 });
 
 // ---------------------------------------------------------------------------

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

@@ -16,6 +16,7 @@ import { rawChanges } from "../../memory/raw-query.js";
 import { acpSessionHistory } from "../../memory/schema.js";
 import { broadcastMessage } from "../../runtime/assistant-event-hub.js";
 import { getLogger } from "../../util/logger.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import {
   BadRequestError,
   ConflictError,
@@ -202,7 +203,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "acp_spawn",
     endpoint: "acp/spawn",
     method: "POST",
-    policyKey: "acp/spawn",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: spawnSession,
     summary: "Spawn ACP session",
     description: "Start a new Agent Communication Protocol session.",
@@ -223,7 +227,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "acp_steer",
     endpoint: "acp/:id/steer",
     method: "POST",
-    policyKey: "acp/steer",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: steerSession,
     summary: "Steer ACP session",
     description: "Send a steering instruction to an active ACP session.",
@@ -240,7 +247,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "acp_cancel",
     endpoint: "acp/:id/cancel",
     method: "POST",
-    policyKey: "acp/cancel",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: cancelSession,
     summary: "Cancel ACP session",
     description: "Cancel an active ACP session.",
@@ -254,7 +264,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "acp_close",
     endpoint: "acp/:id/close",
     method: "POST",
-    policyKey: "acp/close",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: closeSession,
     summary: "Close ACP session",
     description: "Close a completed ACP session.",
@@ -268,7 +281,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "acp_list_sessions",
     endpoint: "acp/sessions",
     method: "GET",
-    policyKey: "acp",
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: listSessions,
     summary: "List ACP sessions",
     description:
@@ -300,6 +316,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "acp_bulk_delete_sessions",
     endpoint: "acp/sessions",
     method: "DELETE",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: bulkDeleteSessions,
     summary: "Bulk-clear terminal ACP sessions",
     description:
@@ -322,7 +342,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "acp_delete_session",
     endpoint: "acp/sessions/:id",
     method: "DELETE",
-    policyKey: "acp/sessions/delete",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: deleteSession,
     summary: "Delete ACP session from history",
     description:

package/src/runtime/routes/app-management-routes.ts

@@ -49,6 +49,8 @@ import {
 import { createSharedAppLink } from "../../memory/shared-app-links-store.js";
 import { computeContentId } from "../../util/content-id.js";
 import { getLogger } from "../../util/logger.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
+import { publishAppsChanged } from "../sync/resource-sync-events.js";
 import {
   BadRequestError,
   NotFoundError,
@@ -62,6 +64,12 @@ const log = getLogger("app-management-routes");
 // Helpers
 // ---------------------------------------------------------------------------
 
+function getOriginClientId(
+  headers: RouteHandlerArgs["headers"],
+): string | undefined {
+  return headers?.["x-vellum-client-id"]?.trim() || undefined;
+}
+
 function getSharedAppsDir(): string {
   return join(
     homedir(),
@@ -565,14 +573,16 @@ async function handleImportBundle({ rawBody, headers }: RouteHandlerArgs) {
       "Request body is required — upload a .vbundle file",
     );
   }
-  return importBundle(rawBody, headers ?? {});
+  const result = await importBundle(rawBody, headers ?? {});
+  publishAppsChanged(getOriginClientId(headers));
+  return result;
 }
 
 function handleListSharedApps() {
   return { apps: listSharedApps() };
 }
 
-function handleForkSharedApp({ body }: RouteHandlerArgs) {
+function handleForkSharedApp({ body, headers }: RouteHandlerArgs) {
   if (!body?.uuid) {
     throw new BadRequestError("uuid is required");
   }
@@ -580,10 +590,11 @@ function handleForkSharedApp({ body }: RouteHandlerArgs) {
   if (!result.success) {
     throw new BadRequestError(result.error);
   }
+  publishAppsChanged(getOriginClientId(headers));
   return result;
 }
 
-async function handleInstallGalleryApp({ body }: RouteHandlerArgs) {
+async function handleInstallGalleryApp({ body, headers }: RouteHandlerArgs) {
   if (!body?.galleryAppId) {
     throw new BadRequestError("galleryAppId is required");
   }
@@ -591,6 +602,7 @@ async function handleInstallGalleryApp({ body }: RouteHandlerArgs) {
   if (!result.success) {
     throw new BadRequestError(result.error);
   }
+  publishAppsChanged(getOriginClientId(headers));
   return result;
 }
 
@@ -694,8 +706,9 @@ async function handleOpenApp({ pathParams }: RouteHandlerArgs) {
   return { appId: app.id, dirName, name: app.name, html };
 }
 
-function handleDeleteApp({ pathParams }: RouteHandlerArgs) {
+function handleDeleteApp({ pathParams, headers }: RouteHandlerArgs) {
   deleteApp(pathParams?.id as string);
+  publishAppsChanged(getOriginClientId(headers));
   return { success: true };
 }
 
@@ -773,7 +786,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "apps_list",
     endpoint: "apps",
     method: "GET",
-    policyKey: "apps",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleListApps,
     summary: "List apps",
     description: "Return all locally installed apps.",
@@ -803,7 +819,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "apps_open_bundle",
     endpoint: "apps/open-bundle",
     method: "POST",
-    policyKey: "apps/open-bundle",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleOpenBundle,
     summary: "Open a .vbundle file",
     description:
@@ -832,7 +851,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "apps_shared_list",
     endpoint: "apps/shared",
     method: "GET",
-    policyKey: "apps/shared-list",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleListSharedApps,
     summary: "List shared apps",
     description: "Return all apps available via cloud share links.",
@@ -861,7 +883,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "apps_fork",
     endpoint: "apps/fork",
     method: "POST",
-    policyKey: "apps/fork",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleForkSharedApp,
     summary: "Fork a shared app",
     description: "Create a local copy of a shared app by its UUID.",
@@ -879,7 +904,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "apps_gallery_install",
     endpoint: "apps/gallery/install",
     method: "POST",
-    policyKey: "apps/gallery/install",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleInstallGalleryApp,
     summary: "Install a gallery app",
     description: "Install an app from the built-in gallery by its ID.",
@@ -895,7 +923,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "apps_gallery_list",
     endpoint: "apps/gallery",
     method: "GET",
-    policyKey: "apps/gallery",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleListGallery,
     summary: "List gallery apps",
     description: "Return the built-in app gallery catalog.",
@@ -929,7 +960,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "apps_import_bundle",
     endpoint: "apps/import-bundle",
     method: "POST",
-    policyKey: "apps/import-bundle",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleImportBundle,
     summary: "Import a .vbundle file",
     description:
@@ -957,7 +991,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "apps_sign_bundle",
     endpoint: "apps/sign-bundle",
     method: "POST",
-    policyKey: "apps/sign-bundle",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleSignBundle,
     summary: "Sign an app bundle",
     description:
@@ -980,7 +1017,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "apps_signing_identity",
     endpoint: "apps/signing-identity",
     method: "GET",
-    policyKey: "apps/signing-identity",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleSigningIdentity,
     summary: "Get signing identity",
     description:
@@ -995,7 +1035,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "apps_data_query",
     endpoint: "apps/:id/data",
     method: "GET",
-    policyKey: "apps/data",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleQueryAppData,
     summary: "Query app data",
     description: "Read records from an app's local data store.",
@@ -1015,7 +1058,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "apps_data_mutate",
     endpoint: "apps/:id/data",
     method: "POST",
-    policyKey: "apps/data",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleMutateAppData,
     summary: "Mutate app data",
     description:
@@ -1035,7 +1081,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "apps_open",
     endpoint: "apps/:id/open",
     method: "POST",
-    policyKey: "apps/open",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleOpenApp,
     summary: "Open an app",
     description: "Compile (if needed) and return the app's HTML for rendering.",
@@ -1051,7 +1100,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "apps_delete",
     endpoint: "apps/:id/delete",
     method: "POST",
-    policyKey: "apps/delete",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleDeleteApp,
     summary: "Delete an app",
     description: "Permanently remove an app and its data.",
@@ -1062,7 +1114,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "apps_preview_get",
     endpoint: "apps/:id/preview",
     method: "GET",
-    policyKey: "apps/preview",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleGetPreview,
     summary: "Get app preview",
     description: "Return the preview image or HTML for an app.",
@@ -1076,7 +1131,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "apps_preview_update",
     endpoint: "apps/:id/preview",
     method: "PUT",
-    policyKey: "apps/preview",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleUpdatePreview,
     summary: "Update app preview",
     description: "Set a new preview image or HTML for an app.",
@@ -1093,7 +1151,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "apps_history",
     endpoint: "apps/:id/history",
     method: "GET",
-    policyKey: "apps/history",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleGetHistory,
     summary: "Get app version history",
     description: "Return the git commit history of an app.",
@@ -1114,7 +1175,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "apps_diff",
     endpoint: "apps/:id/diff",
     method: "GET",
-    policyKey: "apps/diff",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleGetDiff,
     summary: "Get app diff",
     description: "Return a git diff between two commits for an app.",
@@ -1132,7 +1196,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "apps_restore",
     endpoint: "apps/:id/restore",
     method: "POST",
-    policyKey: "apps/restore",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleRestore,
     summary: "Restore app version",
     description: "Restore an app to a previous git commit.",
@@ -1144,7 +1211,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "apps_bundle",
     endpoint: "apps/:id/bundle",
     method: "POST",
-    policyKey: "apps/bundle",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleBundle,
     summary: "Bundle an app",
     description: "Package an app into a distributable .vbundle archive.",
@@ -1160,7 +1230,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "apps_share_cloud",
     endpoint: "apps/:id/share-cloud",
     method: "POST",
-    policyKey: "apps/share-cloud",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleShareCloud,
     summary: "Share app to cloud",
     description: "Package and upload an app to the cloud share service.",