@cosmicdrift/kumiko-bundled-features 0.243.1 → 0.243.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.243.1",
+  "version": "0.243.3",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -130,12 +130,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.243.1",
-    "@cosmicdrift/kumiko-framework": "0.243.1",
-    "@cosmicdrift/kumiko-headless": "0.243.1",
-    "@cosmicdrift/kumiko-renderer": "0.243.1",
-    "@cosmicdrift/kumiko-renderer-web": "0.243.1",
-    "@cosmicdrift/kumiko-types": "0.243.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.243.3",
+    "@cosmicdrift/kumiko-framework": "0.243.3",
+    "@cosmicdrift/kumiko-headless": "0.243.3",
+    "@cosmicdrift/kumiko-renderer": "0.243.3",
+    "@cosmicdrift/kumiko-renderer-web": "0.243.3",
+    "@cosmicdrift/kumiko-types": "0.243.3",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -164,7 +164,7 @@
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
     "@types/qrcode": "^1.5.5",
-    "@cosmicdrift/kumiko-locale-de": "0.243.1",
-    "@cosmicdrift/kumiko-locale-es": "0.243.1"
+    "@cosmicdrift/kumiko-locale-de": "0.243.3",
+    "@cosmicdrift/kumiko-locale-es": "0.243.3"
   }
 }

package/src/agent-tools/__tests__/agent-optout.test.ts

@@ -0,0 +1,252 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createEntity,
+  createRegistry,
+  createTextField,
+  defineEntityDetailHandler,
+  defineEntityListHandler,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { authFoundationFeature } from "../../auth-foundation";
+import { AuthMfaHandlers, AuthMfaQueries, createAuthMfaFeature } from "../../auth-mfa";
+import { createConfigFeature } from "../../config";
+import { createCryptoShreddingFeature } from "../../crypto-shredding";
+import { createPersonalAccessTokensFeature, PatHandlers } from "../../personal-access-tokens";
+import { createSecretsFeature } from "../../secrets";
+import { createTenantFeature } from "../../tenant";
+import { createUserFeature } from "../../user/feature";
+import { buildAgentManifest } from "../agent-manifest";
+import { buildToolCatalog, toolNameForQn } from "../tool-catalog";
+
+// #2700/#2702 — bundled handlers that carry secrets/irreversible-erase risk are now
+// opted out of the agent tool catalog via `agent: { expose: false }`, and the app-side
+// `denyQns` cut removes a handler the catalog would otherwise expose (including the
+// entity-CRUD tools, which bypass the manifest entirely).
+
+const SECRETS_HANDLING_FEATURE_QNS = [
+  AuthMfaHandlers.enableStart,
+  AuthMfaHandlers.enableStartPreauth,
+  AuthMfaHandlers.regenerateRecovery,
+  PatHandlers.create,
+  "crypto-shredding:write:forget-subject",
+  "secrets:write:set",
+] as const;
+
+// enable-start-preauth is gated to the literal role "all" (login-flow guest caller,
+// see auth-mfa/handlers/enable-start-preauth.write.ts) — none of the three roles
+// exercised below carry that role, so hasAccess alone would already exclude it and
+// this one QN's absence doesn't prove agent.expose:false is doing the work. The other
+// five QNs are openToAll or role-reachable by at least one of ["User"], ["TenantAdmin"],
+// ["SystemAdmin"], so their absence does.
+function buildSecretHandlingFeatures() {
+  return [
+    createConfigFeature(),
+    createUserFeature(),
+    createTenantFeature(),
+    authFoundationFeature,
+    createAuthMfaFeature({
+      setupTokenSecret: "test-mfa-setup-secret-at-least-32-bytes!!",
+      issuer: "Kumiko Test",
+      challengeTokenSecret: "test-mfa-challenge-secret-at-least-32-bytes!!",
+    }),
+    createPersonalAccessTokensFeature({ scopes: {} }),
+    createCryptoShreddingFeature(),
+    createSecretsFeature(),
+  ];
+}
+
+describe("bundled secret-bearing handlers are not in the catalog", () => {
+  const roleCases: ReadonlyArray<readonly string[]> = [["User"], ["TenantAdmin"], ["SystemAdmin"]];
+
+  for (const roles of roleCases) {
+    test(`roles ${JSON.stringify(roles)}: none of the opted-out handlers reach the catalog or manifest`, () => {
+      const registry = createRegistry(buildSecretHandlingFeatures());
+      const manifest = buildAgentManifest(registry, { locale: "en", roles });
+      const catalog = buildToolCatalog(registry, manifest, { mode: "edit" });
+      const toolNames = catalog.tools.map((t) => t.name);
+      const manifestQns = manifest.handlers.map((h) => h.qn);
+
+      for (const qn of SECRETS_HANDLING_FEATURE_QNS) {
+        const toolName = toolNameForQn(qn);
+        expect(toolNames).not.toContain(toolName);
+        expect(catalog.dispatchTable.has(toolName)).toBe(false);
+        expect(manifestQns).not.toContain(qn);
+      }
+
+      // Positive control: a still-exposed bundled handler ("is MFA enabled for me?")
+      // must survive — without this, the six assertions above would also pass for a
+      // registry that mounted no features at all.
+      const statusToolName = toolNameForQn(AuthMfaQueries.status);
+      expect(toolNames).toContain(statusToolName);
+      expect(catalog.dispatchTable.has(statusToolName)).toBe(true);
+      expect(manifestQns).toContain(AuthMfaQueries.status);
+    });
+  }
+});
+
+function buildDenyTestFeature() {
+  return defineFeature("deny-test", (r) => {
+    r.queryHandler("alpha", z.object({}), async () => ({ ok: true }), {
+      access: { roles: ["Admin"] },
+      description: "Alpha query handler.",
+    });
+    r.queryHandler("beta", z.object({}), async () => ({ ok: true }), {
+      access: { roles: ["Admin"] },
+      description: "Beta query handler.",
+    });
+  });
+}
+
+const DENY_TEST_QN_A = "deny-test:query:alpha";
+const DENY_TEST_QN_B = "deny-test:query:beta";
+
+describe("denyQns removes a tool", () => {
+  function buildDenyCatalog(denyQns?: readonly string[]) {
+    const registry = createRegistry([buildDenyTestFeature()]);
+    const manifest = buildAgentManifest(registry, { locale: "en", roles: ["Admin"], denyQns });
+    const catalog = buildToolCatalog(registry, manifest, { mode: "edit", denyQns });
+    return { manifest, catalog };
+  }
+
+  test("without denyQns both handler-derived tools are present", () => {
+    const { catalog } = buildDenyCatalog();
+    const names = catalog.tools.map((t) => t.name);
+    expect(names).toContain(toolNameForQn(DENY_TEST_QN_A));
+    expect(names).toContain(toolNameForQn(DENY_TEST_QN_B));
+  });
+
+  test("denyQns on both buildAgentManifest and buildToolCatalog removes only the denied tool", () => {
+    const { manifest, catalog } = buildDenyCatalog([DENY_TEST_QN_A]);
+    const nameA = toolNameForQn(DENY_TEST_QN_A);
+    const nameB = toolNameForQn(DENY_TEST_QN_B);
+
+    expect(catalog.tools.map((t) => t.name)).not.toContain(nameA);
+    expect(catalog.dispatchTable.has(nameA)).toBe(false);
+    expect(manifest.handlers.map((h) => h.qn)).not.toContain(DENY_TEST_QN_A);
+
+    expect(catalog.tools.map((t) => t.name)).toContain(nameB);
+    expect(catalog.dispatchTable.has(nameB)).toBe(true);
+    expect(manifest.handlers.map((h) => h.qn)).toContain(DENY_TEST_QN_B);
+  });
+
+  test("denyQns passed only to buildToolCatalog still removes the tool, even though the manifest still lists the handler", () => {
+    const registry = createRegistry([buildDenyTestFeature()]);
+    const manifest = buildAgentManifest(registry, { locale: "en", roles: ["Admin"] });
+    expect(manifest.handlers.map((h) => h.qn)).toContain(DENY_TEST_QN_A);
+
+    const catalog = buildToolCatalog(registry, manifest, {
+      mode: "edit",
+      denyQns: [DENY_TEST_QN_A],
+    });
+    const nameA = toolNameForQn(DENY_TEST_QN_A);
+    expect(catalog.tools.map((t) => t.name)).not.toContain(nameA);
+    expect(catalog.dispatchTable.has(nameA)).toBe(false);
+  });
+});
+
+const gadgetEntity = createEntity({
+  fields: {
+    name: createTextField({ searchable: true, filterable: true }),
+  },
+});
+
+function buildGadgetCrudFeature() {
+  return defineFeature("gadget-crud-test", (r) => {
+    r.crud("gadget", gadgetEntity, {
+      read: { access: { roles: ["Admin"] } },
+      write: { access: { roles: ["Admin"] } },
+    });
+  });
+}
+
+const GADGET_LIST_QN = "gadget-crud-test:query:gadget:list";
+const GADGET_DETAIL_QN = "gadget-crud-test:query:gadget:detail";
+
+describe("denyQns reaches the entity CRUD tools", () => {
+  function buildGadgetCatalog(denyQns?: readonly string[]) {
+    const registry = createRegistry([buildGadgetCrudFeature()]);
+    const manifest = buildAgentManifest(registry, { locale: "en", roles: ["Admin"], denyQns });
+    return buildToolCatalog(registry, manifest, { mode: "edit", denyQns });
+  }
+
+  test("without denyQns the full entity CRUD tool set is present", () => {
+    const names = buildGadgetCatalog().tools.map((t) => t.name);
+    expect(names).toContain("get_gadget");
+    expect(names).toContain("list_gadget");
+    expect(names).toContain("search_gadget");
+    expect(names).toContain("find_gadget_by_name");
+  });
+
+  test("denying the :list QN removes list/search/find-by but keeps get", () => {
+    const names = buildGadgetCatalog([GADGET_LIST_QN]).tools.map((t) => t.name);
+    expect(names).not.toContain("list_gadget");
+    expect(names).not.toContain("search_gadget");
+    expect(names).not.toContain("find_gadget_by_name");
+    expect(names).toContain("get_gadget");
+  });
+
+  test("denying the :detail QN removes get_gadget", () => {
+    const names = buildGadgetCatalog([GADGET_DETAIL_QN]).tools.map((t) => t.name);
+    expect(names).not.toContain("get_gadget");
+  });
+});
+
+const plainItemEntity = createEntity({
+  fields: { label: createTextField({ searchable: true, filterable: true }) },
+});
+const cloakedItemEntity = createEntity({
+  fields: { label: createTextField({ searchable: true, filterable: true }) },
+});
+
+// Both entities mounted in the same feature so the "default stays exposed"
+// assertion and the "explicit opt-out hides it" assertion run against one
+// shared registry/catalog build and prove each other's premise.
+function buildExposureTestFeature() {
+  return defineFeature("expose-test", (r) => {
+    r.crud("plain-item", plainItemEntity, {
+      read: { access: { roles: ["Admin"] } },
+      write: { access: { roles: ["Admin"] } },
+    });
+
+    r.entity("cloaked-item", cloakedItemEntity);
+    r.queryHandler(
+      defineEntityListHandler("cloaked-item", cloakedItemEntity, {
+        access: { roles: ["Admin"] },
+        agent: { expose: false },
+      }),
+    );
+    r.queryHandler(
+      defineEntityDetailHandler("cloaked-item", cloakedItemEntity, {
+        access: { roles: ["Admin"] },
+      }),
+    );
+  });
+}
+
+describe("#2700 — explicit agent.expose:false on an entity handler, both directions", () => {
+  function buildExposureCatalog() {
+    const registry = createRegistry([buildExposureTestFeature()]);
+    const manifest = buildAgentManifest(registry, { locale: "en", roles: ["Admin"] });
+    return buildToolCatalog(registry, manifest, { mode: "edit" });
+  }
+
+  test("a CRUD entity without any agent hint keeps its default entity tools — resolveAgentExposure never runs on it", () => {
+    const names = buildExposureCatalog().tools.map((t) => t.name);
+    // CRUD-generated list/detail handlers carry no `description`, and
+    // resolveAgentExposure is fail-closed on a missing description — applying it here
+    // would delete every entity tool in every app, not just an opted-out one.
+    expect(names).toContain("get_plain-item");
+    expect(names).toContain("list_plain-item");
+    expect(names).toContain("search_plain-item");
+    expect(names).toContain("find_plain-item_by_label");
+  });
+
+  test("an entity's list handler with an explicit agent.expose:false loses list/search/find-by but keeps get", () => {
+    const names = buildExposureCatalog().tools.map((t) => t.name);
+    expect(names).not.toContain("list_cloaked-item");
+    expect(names).not.toContain("search_cloaked-item");
+    expect(names).not.toContain("find_cloaked-item_by_label");
+    expect(names).toContain("get_cloaked-item");
+  });
+});

package/src/agent-tools/agent-manifest.ts

@@ -155,7 +155,9 @@ function buildHandlerEntry(
   def: QueryHandlerDef | WriteHandlerDef,
   roles: readonly string[],
   getHandlerEntity: (qualifiedHandler: string) => string | undefined,
+  denyQns: ReadonlySet<string>,
 ): AgentManifestHandler | undefined {
+  if (denyQns.has(qn)) return undefined;
   const exposure = resolveAgentExposure(def, kind);
   if (!exposure.expose) return undefined;
   if (!hasAccess({ roles }, def.access)) return undefined;
@@ -190,14 +192,15 @@ function buildHandlers(
   writeHandlers: ReadonlyMap<string, WriteHandlerDef>,
   roles: readonly string[],
   getHandlerEntity: (qualifiedHandler: string) => string | undefined,
+  denyQns: ReadonlySet<string>,
 ): readonly AgentManifestHandler[] {
   const result: AgentManifestHandler[] = [];
   for (const [qn, def] of queryHandlers) {
-    const entry = buildHandlerEntry(qn, "query", def, roles, getHandlerEntity);
+    const entry = buildHandlerEntry(qn, "query", def, roles, getHandlerEntity, denyQns);
     if (entry) result.push(entry);
   }
   for (const [qn, def] of writeHandlers) {
-    const entry = buildHandlerEntry(qn, "write", def, roles, getHandlerEntity);
+    const entry = buildHandlerEntry(qn, "write", def, roles, getHandlerEntity, denyQns);
     if (entry) result.push(entry);
   }
   return result;
@@ -323,6 +326,7 @@ export function buildAgentManifest(
     registry.getAllWriteHandlers(),
     roles,
     (qn) => registry.getHandlerEntity(qn),
+    new Set(options.denyQns ?? []),
   );
   const screenMap = registry.getAllScreens();
   const navs = buildNavs(navMap, workspaceMap, translations, roles, screenMap);

package/src/agent-tools/tool-catalog.ts

@@ -1,4 +1,8 @@
-import type { EntityDefinition, FieldDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import type {
+  EntityDefinition,
+  FieldDefinition,
+  QueryHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { hasAccess } from "@cosmicdrift/kumiko-framework/engine";
 import type {
   AgentManifest,
@@ -94,6 +98,14 @@ function isDetailHandlerQn(qn: string, entityName: string): boolean {
   return qn.endsWith(`:${entityName}:detail`);
 }
 
+/** #2700: the entity CRUD tools are enumerated off the registry, not off the manifest, so
+ *  `resolveAgentExposure` never runs for them. Only an EXPLICIT opt-out may hide one here —
+ *  the resolver's own default is fail-closed on a missing `description`, and CRUD-generated
+ *  handlers never carry one, so reusing it would delete every entity tool in every app. */
+function isExplicitlyAgentHidden(def: QueryHandlerDef): boolean {
+  return def.agent?.expose === false;
+}
+
 function addToolsForListHandler(
   registry: RegistrySearchView,
   qn: string,
@@ -375,11 +387,13 @@ function addTool(
 function addRegistrySearchTools(
   registry: RegistrySearchView,
   roleFilter: { roles: readonly string[] },
+  denyQns: ReadonlySet<string>,
   sink: CatalogSink,
 ): void {
   for (const [qn, def] of registry.getAllQueryHandlers()) {
     const entityName = registry.getHandlerEntity(qn);
     if (!entityName || !isListHandlerQn(qn, entityName)) continue;
+    if (denyQns.has(qn) || isExplicitlyAgentHidden(def)) continue;
     if (!hasAccess(roleFilter, def.access)) continue;
 
     const entity = registry.getEntity(entityName);
@@ -398,6 +412,7 @@ type EntityHandlerQns = {
 function collectEntityHandlerQns(
   registry: RegistrySearchView,
   roleFilter: { roles: readonly string[] },
+  denyQns: ReadonlySet<string>,
 ): EntityHandlerQns {
   const detailQnByEntity = new Map<string, string>();
   const listQnByEntity = new Map<string, string>();
@@ -413,6 +428,7 @@ function collectEntityHandlerQns(
   for (const [qn, def] of registry.getAllQueryHandlers()) {
     const entityName = registry.getHandlerEntity(qn);
     if (!entityName || !hasAccess(roleFilter, def.access)) continue;
+    if (denyQns.has(qn) || isExplicitlyAgentHidden(def)) continue;
     if (isDetailHandlerQn(qn, entityName)) detailQnByEntity.set(entityName, qn);
     if (isListHandlerQn(qn, entityName)) listQnByEntity.set(entityName, qn);
   }
@@ -459,10 +475,12 @@ function addListTools(
 function addQueryHandlerTools(
   manifest: AgentManifest,
   entityListDetailQns: ReadonlySet<string>,
+  denyQns: ReadonlySet<string>,
   sink: CatalogSink,
 ): void {
   for (const handler of manifest.handlers) {
     if (handler.kind !== "query") continue;
+    if (denyQns.has(handler.qn)) continue;
     if (entityListDetailQns.has(handler.qn)) continue;
     const name = toolNameForQn(handler.qn);
 
@@ -483,10 +501,12 @@ function addQueryHandlerTools(
 function addWriteHandlerTools(
   manifest: AgentManifest,
   detailQnByEntity: ReadonlyMap<string, string>,
+  denyQns: ReadonlySet<string>,
   sink: CatalogSink,
 ): void {
   for (const handler of manifest.handlers) {
     if (handler.kind !== "write") continue;
+    if (denyQns.has(handler.qn)) continue;
     const name = toolNameForQn(handler.qn);
 
     const detailQn =
@@ -544,7 +564,14 @@ function addClientTools(manifest: AgentManifest, mode: AgentToolMode, sink: Cata
  *  tool (custom query/write handlers, navigate/open_form/ask_user) is manifest-derived, since
  *  the manifest already carries the role-filtered handler/screen shape needed for those. Roles
  *  and locale both come from the manifest (`manifest.builtForRoles` / `manifest.tenantSettings.locale`)
- *  so the registry-derived and manifest-derived halves share one source and cannot disagree. */
+ *  so the registry-derived and manifest-derived halves share one source and cannot disagree.
+ *
+ *  `options.denyQns` is the app-side cut, applied to both halves: it is the only way to keep a
+ *  handler out of the catalog that the app does not own (a bundled feature's), and the only way
+ *  to drop an entity CRUD tool, which no `agent.expose` on the manifest side can reach. It is
+ *  NOT read off the manifest on purpose — the manifest is prompt payload, and a list of the
+ *  handlers the model may not call has no business travelling to the provider. Pass the same
+ *  list to `buildAgentManifest` so the manifest stops describing what the catalog withholds. */
 export function buildToolCatalog(
   registry: RegistrySearchView,
   manifest: AgentManifest,
@@ -554,16 +581,20 @@ export function buildToolCatalog(
   const roleFilter = { roles: manifest.builtForRoles };
   const locale = manifest.tenantSettings.locale;
   const entityByName = new Map(manifest.entities.map((entity) => [entity.name, entity]));
+  const denyQns = new Set(options.denyQns ?? []);
 
-  addRegistrySearchTools(registry, roleFilter, sink);
+  addRegistrySearchTools(registry, roleFilter, denyQns, sink);
   const { detailQnByEntity, listQnByEntity, entityListDetailQns } = collectEntityHandlerQns(
     registry,
     roleFilter,
+    denyQns,
   );
   addGetTools(detailQnByEntity, entityByName, locale, sink);
   addListTools(registry, listQnByEntity, entityByName, locale, sink);
-  addQueryHandlerTools(manifest, entityListDetailQns, sink);
-  if (options.mode !== "read-only") addWriteHandlerTools(manifest, detailQnByEntity, sink);
+  addQueryHandlerTools(manifest, entityListDetailQns, denyQns, sink);
+  if (options.mode !== "read-only") {
+    addWriteHandlerTools(manifest, detailQnByEntity, denyQns, sink);
+  }
   addClientTools(manifest, options.mode, sink);
 
   return { tools: sink.tools, dispatchTable: sink.dispatchTable };

package/src/agent-tools/types.ts

@@ -14,6 +14,13 @@ export type AgentToolMode = "read-only" | "approval" | "edit";
 
 export type ToolCatalogOptions = {
   readonly mode: AgentToolMode;
+  /** Handler QNs the mounting app refuses to expose, whatever the handler's own
+   *  `agent.expose` says. Applies to every tool shape, including the entity
+   *  CRUD tools (`get_`/`list_`/`search_`/`find_*_by_*`) that are enumerated off
+   *  the registry rather than off the manifest. Pass the same list to
+   *  `buildAgentManifest`, or the manifest will still describe what the catalog
+   *  no longer offers. */
+  readonly denyQns?: readonly string[];
 };
 
 /** Mirrors `ToolDefinition` in `@cosmicdriftgamestudio/kumiko-ai-foundation` (providers/types.ts)
@@ -104,6 +111,12 @@ export type ToolCatalog = {
 export type AgentManifestOptions = {
   readonly locale: string;
   readonly roles: readonly string[];
+  /** Handler QNs the mounting app refuses to expose, whatever the handler's own
+   *  `agent.expose` says. Denied handlers are left out of `manifest.handlers`
+   *  entirely — the manifest is prompt payload, so a denied handler must not
+   *  reach the model as a description either. Pass the same list to
+   *  `buildToolCatalog`. */
+  readonly denyQns?: readonly string[];
   /** Tenant currency — the registry knows nothing about tenants, so the
    *  caller passes it through into the manifest's tenant-settings block. */
   readonly currency?: string;

package/src/auth-mfa/handlers/enable-confirm-preauth.write.ts

@@ -66,6 +66,8 @@ export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOpti
     access: { roles: ["all"] },
     description:
       "Completes the enrollment that unblocks a sign-in forced into two-factor setup: verifies the code against the pre-auth setup token, stores the factor and derives the session the blocked login never got.",
+    // Changes the caller's authentication state and mints a session.
+    agent: { risk: "high" },
     handler: async (event, ctx) => {
       const verify = verifyMfaSetupToken(event.payload.setupToken, opts.setupTokenSecret);
       if (!verify.ok) return invalidSetupToken();

package/src/auth-mfa/handlers/enable-confirm.write.ts

@@ -40,6 +40,8 @@ export function createEnableConfirmHandler(opts: EnableConfirmOptions) {
     access: { openToAll: true },
     description:
       "Completes TOTP enrollment for the signed-in user by checking a code against the secret carried in the setup token from enable-start, then storing the factor and signing every other session and access token out.",
+    // Changes the caller's authentication state and signs their other sessions out.
+    agent: { risk: "high" },
     handler: async (event, ctx) => {
       const verify = verifyMfaSetupToken(event.payload.setupToken, opts.setupTokenSecret);
       if (!verify.ok) return invalidSetupToken();

package/src/auth-mfa/handlers/enable-start-preauth.write.ts

@@ -37,6 +37,8 @@ export function createEnableStartPreauthHandler(opts: EnableStartPreauthOptions)
     access: { roles: ["all"] },
     description:
       "Begins TOTP enrollment for a user whose sign-in was blocked because the tenant requires two-factor authentication, taking identity from the pre-auth token login issued instead of from a session.",
+    // Same secret-bearing result as enable-start.
+    agent: { expose: false },
     handler: async (event, ctx) => {
       const verified = verifyMfaPreauthSetupToken(
         event.payload.preauthSetupToken,

package/src/auth-mfa/handlers/enable-start.write.ts

@@ -32,6 +32,9 @@ export function createEnableStartHandler(opts: EnableStartOptions) {
     access: { openToAll: true },
     description:
       "Begins TOTP enrollment for the signed-in user by generating a secret plus recovery codes and returning them as a short-lived setup token, an otpauth:// URI and the one-time plaintext recovery codes; nothing is persisted until enable-confirm.",
+    // The result is the TOTP secret, the otpauth:// URI and the plaintext
+    // recovery codes — an agent turn would put all three in the LLM transcript.
+    agent: { expose: false },
     handler: async (event, ctx) => {
       const existing = await findUserMfaRow(ctx.db, event.user);
       if (existing) return mfaAlreadyEnabled();

package/src/auth-mfa/handlers/regenerate-recovery.write.ts

@@ -29,7 +29,9 @@ export function createRegenerateRecoveryHandler(opts: RegenerateRecoveryOptions)
     access: { openToAll: true },
     description:
       "Destroys every existing recovery code of the caller, including unused ones, and returns a fresh set once in plaintext; use it when recovery codes may have leaked but TOTP itself should stay enrolled.",
-    agent: { risk: "high" },
+    // Returns a fresh set of plaintext recovery codes — same transcript leak as
+    // enable-start.
+    agent: { expose: false },
     handler: async (event, ctx) => {
       const row = await findUserMfaRow(ctx.db, event.user);
       if (!row) return mfaNotEnabled();

package/src/crypto-shredding/handlers/forget-subject.write.ts

@@ -189,7 +189,9 @@ export const forgetSubjectWrite = defineWriteHandler({
   access: { roles: [ROLES.DataProtectionOfficer, ROLES.SystemAdmin] },
   description:
     "Irreversibly crypto-shreds one user or tenant subject by erasing its encryption key, nulling its blind indexes, purging its search documents and closing the user's login, for supervisory-authority requests and operator recovery outside the automated Art. 17 cleanup pipeline.",
-  agent: { risk: "high" },
+  // Erasing the subject key is irreversible: there is no undo, so an agent must
+  // not be able to reach it at all.
+  agent: { expose: false },
   handler: async (event, ctx) => {
     const kms = configuredPiiSubjectKms();
     if (!kms) {

package/src/personal-access-tokens/handlers/create.write.ts

@@ -60,6 +60,9 @@ export function createPatCreateHandler(opts: CreatePatOptions = {}) {
     access: { openToAll: true },
     description:
       "Mints a personal access token for the calling user after re-verifying their password (and MFA code when enrolled) and returns the plaintext token exactly once; use it when a user needs a long-lived API credential.",
+    // Returns the plaintext token once; an agent turn would archive it in the
+    // LLM transcript, where it stays valid until revoked.
+    agent: { expose: false },
     handler: async (event, ctx) => {
       const systemUser = createSystemUser(event.user.tenantId);
       const me = (await ctx.queryAs(systemUser, UserQueries.findForAuth, {

package/src/secrets/handlers/set.write.ts

@@ -8,6 +8,9 @@ export function createSetHandler(access: AccessRule = DEFAULT_SECRETS_ACCESS) {
     name: "set",
     description:
       "Stores or replaces one encrypted secret for the caller's tenant under the given key, together with a redacted preview and optional hint; use it to enter or rotate a credential.",
+    // `value` is the plaintext credential: as a tool call it would travel to
+    // the model provider before it is ever encrypted at rest.
+    agent: { expose: false },
     schema: z.object({
       key: z.string().min(1).max(100),
       value: z.string(),

package/src/sessions/handlers/detail.query.ts

@@ -22,6 +22,8 @@ export const detailQuery = defineQueryHandler({
   access: { roles: access.admin },
   description:
     "Loads one session of the active tenant by its id with owner, timestamps and decrypted IP/user-agent; use it when an admin investigates a specific session found through the session list.",
+  // Decrypted IP and user-agent.
+  agent: { risk: "high" },
   outputSchema: sessionRowSchema.nullable(),
   handler: async (query, ctx) => {
     const row = await fetchOne<{

package/src/tenant/handlers/invitations.query.ts

@@ -25,6 +25,8 @@ export const invitationsQuery = defineQueryHandler({
   access: { roles: access.admin },
   description:
     "Lists the still-pending invitations of the caller's own tenant with their email and inviter decrypted; accepted, cancelled and expired ones are left out.",
+  // Decrypted invitee and inviter email.
+  agent: { risk: "high" },
   handler: async (query, ctx) => {
     if (!ctx.systemDb) {
       throw new InternalError({

package/src/tenant/handlers/members.query.ts

@@ -26,6 +26,8 @@ export const membersQuery = defineQueryHandler({
   access: { roles: access.admin },
   description:
     "Lists the memberships of the caller's own tenant with each member's decrypted email, display name and roles, optionally narrowed to a single user id.",
+  // Decrypted email + display name: legitimate for an agent, never unattended.
+  agent: { risk: "high" },
   handler: async (query, ctx) => {
     if (!ctx.systemDb) {
       throw new InternalError({

package/src/user-data-rights/handlers/list-download-attempts.query.ts

@@ -25,6 +25,8 @@ export const listDownloadAttemptsQuery = defineQueryHandler({
   access: { roles: ["Admin", "SystemAdmin"] },
   description:
     "Lists invalid export-download attempts inside the caller's own tenant, filterable by failure result, source IP and time range, for a data protection officer triaging brute-force probing of download links.",
+  // Source IPs of the probing attempts.
+  agent: { risk: "high" },
   handler: async (query, ctx) => {
     const p = query.payload;
     const where: WhereObject = { tenantId: query.user.tenantId };

package/src/user-data-rights/handlers/request-deletion-by-email.write.ts

@@ -62,6 +62,8 @@ export function createRequestDeletionByEmailHandler(opts: RequestDeletionByEmail
     access: { roles: ["anonymous", "Member", "User", "TenantAdmin", "SystemAdmin"] },
     description:
       "Mails an account-deletion verification link to the given address, for a user who wants to be erased but can no longer log in; it answers identically whether or not the address belongs to an active account and never returns the link.",
+    // Mails a deletion link to any address the caller names.
+    agent: { risk: "high" },
     // Defense-in-depth gegen Email-Probing auf dem anonymen Endpoint.
     rateLimit: { per: "ip", limit: 10, windowSeconds: 60 },
     handler: async (event, ctx) => {