@kindgi/api 0.1.4 → 0.1.5

package/src/routes/eval-overrides.ts

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * An agent candidate's `overrides`, checked when the comparison starts:
+ * each settings block must be one the version pins, its values satisfying
+ * the schema of the version it pins (model settings, for the
+ * model-settings block); a prompt template must be for the prompt block
+ * the version pins, and pass `checkDraftedTemplate` (it reads and names
+ * only what the agent has). Checked once, here, before any run exists:
+ * the replays use them as given, on resume too.
+ */
+
+import {
+  type AgentId,
+  MODEL_SETTINGS_SCHEMA,
+  checkDraftedTemplate,
+  settingsSchemaIssues,
+} from '@kindgi/agents';
+import type { Semver, TenantId } from '@kindgi/types';
+
+import type { AgentRegistryBinding } from '../agent-binding.js';
+import type { BlockRegistryBinding } from '../block-binding.js';
+import type { EvalOverrides } from '../eval-run-binding.js';
+
+/** Where the check reads the agent version and its blocks. */
+export interface SettingsOverridesCheck {
+  readonly agents: AgentRegistryBinding;
+  readonly blocks: BlockRegistryBinding;
+}
+
+export interface OverridesIssue {
+  readonly path: string;
+  readonly message: string;
+}
+
+/** A JSON Pointer token: `~` and `/` escaped. */
+const token = (id: string): string => id.replaceAll('~', '~0').replaceAll('/', '~1');
+
+export async function checkSettingsOverrides(
+  check: SettingsOverridesCheck,
+  tenantId: TenantId,
+  candidate: { readonly agentId: string; readonly version: string },
+  overrides: EvalOverrides,
+): Promise<OverridesIssue[]> {
+  const settings = overrides.settings ?? {};
+  const label = `${candidate.agentId} ${candidate.version}`;
+  const found = await check.agents.getVersion({
+    tenantId,
+    agentId: candidate.agentId as AgentId,
+    version: candidate.version as Semver,
+  });
+  if (found === null) {
+    return [{ path: '/agentRef/version', message: `agent ${label} isn't registered` }];
+  }
+  if (found.pins === undefined) {
+    return [
+      {
+        path: '/overrides/settings',
+        message: `${label} was published before pins: it has no pinned settings to replace`,
+      },
+    ];
+  }
+  const issues: OverridesIssue[] = [];
+  for (const [id, values] of Object.entries(settings)) {
+    const path = `/overrides/settings/${token(id)}`;
+    const version = found.pins.settings[id];
+    if (version === undefined) {
+      issues.push({ path, message: `${label} doesn't pin settings block "${id}"` });
+      continue;
+    }
+    const block = await check.blocks.getVersion({ tenantId, blockId: id, version });
+    if (block === null || block.kind !== 'settings') {
+      issues.push({ path, message: `settings block "${id}" version ${version} isn't published` });
+      continue;
+    }
+    const schema = found.modelSettings?.id === id ? MODEL_SETTINGS_SCHEMA : block.content.schema;
+    if (schema === undefined) continue;
+    for (const issue of settingsSchemaIssues(values, schema)) {
+      issues.push({ path: `${path}${issue.path}`, message: issue.message });
+    }
+  }
+  for (const [id, { template }] of Object.entries(overrides.prompts ?? {})) {
+    const path = `/overrides/prompts/${token(id)}`;
+    const version = found.pins.prompts[id];
+    if (version === undefined) {
+      issues.push({ path, message: `${label} doesn't pin prompt block "${id}"` });
+      continue;
+    }
+    const block = await check.blocks.getVersion({ tenantId, blockId: id, version });
+    if (block === null || block.kind !== 'prompt') {
+      issues.push({ path, message: `prompt block "${id}" version ${version} isn't published` });
+      continue;
+    }
+    const drafted = checkDraftedTemplate(template, {
+      current: block.content,
+      settingsBlocks: Object.keys(found.pins.settings),
+      knownIds: [
+        candidate.agentId,
+        ...Object.keys(found.pins.tools),
+        ...Object.keys(found.pins.prompts),
+        ...Object.keys(found.pins.settings),
+      ],
+    });
+    for (const issue of drafted) issues.push({ path, message: issue.message });
+  }
+  return issues;
+}

package/src/routes/eval-runs.ts

@@ -2,8 +2,10 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import { Hono } from 'hono';
+import type { Context } from 'hono';
 
 import type { AgentId } from '@kindgi/agents';
+import { type Action, ref } from '@kindgi/authz';
 import type { Cursor, FlowId, ProjectId, RunId, Semver, TenantId, Timestamp } from '@kindgi/types';
 
 import { statusFor, toWireError } from '../errors.js';
@@ -18,8 +20,11 @@ import {
   type FlowRef,
 } from '../eval-run-binding.js';
 import { VERSIONS_NEED_A_FLOW } from '../judged-dispatcher.js';
+import type { Authorizer } from '../middleware/authorize.js';
 import type { AppEnv } from '../types.js';
+import { deniedBy } from './denied.js';
 import { parseComparison } from './eval-comparison.js';
+import { type SettingsOverridesCheck, checkSettingsOverrides } from './eval-overrides.js';
 import { type FlowVersionsCheck, checkFlowVersions } from './eval-versions.js';
 import { clampLimit } from './pagination.js';
 import { parseScopeParams } from './scope-params.js';
@@ -43,6 +48,13 @@ import { formatSseFrame } from './sse.js';
  * The binding chooses its underlying substrate (the in-process
  * reference keeps runs in memory; a durable binding can back them with
  * runs and their journal); this route only sees the surface.
+ *
+ * With an authorizer (T243 A): starting a run needs `write` on the
+ * project it lands in and `execute` on what it evaluates (the agent or
+ * flow), on top of the eval-suites router's own check on the suite. An
+ * eval run is read through its suite: `read` on the suite to list, get or
+ * follow it, `write` to cancel it. A run that isn't there is still the
+ * handler's 404.
  */
 export interface EvalRunsRouters {
   readonly start: Hono<AppEnv>;
@@ -57,10 +69,12 @@ export interface EvalRunsRouters {
 export function evalRunsRouters(
   binding: EvalRunBinding,
   versionsCheck?: FlowVersionsCheck,
+  overridesCheck?: SettingsOverridesCheck,
+  authorizer?: Authorizer,
 ): EvalRunsRouters {
   return {
-    start: startRouter(binding, versionsCheck),
-    readback: readbackRouter(binding),
+    start: startRouter(binding, versionsCheck, overridesCheck, authorizer),
+    readback: readbackRouter(binding, authorizer),
   };
 }
 
@@ -91,7 +105,42 @@ async function versionsRefusal(
   };
 }
 
-function startRouter(binding: EvalRunBinding, versionsCheck?: FlowVersionsCheck): Hono<AppEnv> {
+/** The `validation-failed` error for an agent candidate's settings `overrides` that don't fit it; `undefined` when they do. */
+async function overridesRefusal(
+  check: SettingsOverridesCheck | undefined,
+  tenantId: TenantId,
+  start: ParsedStartBody,
+) {
+  const overrides = start.comparison?.overrides;
+  const agentRef = start.agentRef;
+  if (overrides === undefined || agentRef?.version === undefined) return undefined;
+  if (check === undefined) {
+    return {
+      code: 'validation-failed' as const,
+      message: "This runtime can't check overrides (it serves no agent or block registry).",
+      issues: [],
+    };
+  }
+  const issues = await checkSettingsOverrides(
+    check,
+    tenantId,
+    { agentId: agentRef.agentId as unknown as string, version: agentRef.version },
+    overrides,
+  );
+  if (issues.length === 0) return undefined;
+  return {
+    code: 'validation-failed' as const,
+    message: `The overrides don't fit ${agentRef.agentId as unknown as string} ${agentRef.version} (${issues.length} issue${issues.length === 1 ? '' : 's'})`,
+    issues: issues as unknown as Record<string, unknown>[],
+  };
+}
+
+function startRouter(
+  binding: EvalRunBinding,
+  versionsCheck?: FlowVersionsCheck,
+  overridesCheck?: SettingsOverridesCheck,
+  authorizer?: Authorizer,
+): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
 
   r.post('/:suiteId/runs', async (c) => {
@@ -119,7 +168,21 @@ function startRouter(binding: EvalRunBinding, versionsCheck?: FlowVersionsCheck)
       c.status(statusFor(parsed.error.code) as never);
       return c.json(toWireError(parsed.error, requestId));
     }
-    const refusal = await versionsRefusal(versionsCheck, tenantId, parsed.value);
+    const { projectId, agentRef, flowRef } = parsed.value;
+    const target =
+      agentRef !== undefined
+        ? ref('agent', agentRef.agentId as unknown as string)
+        : ref('flow', flowRef?.flowId as unknown as string);
+    // Running the suite takes `execute` on it (an editor of its project, or
+    // an executor), whichever project the run lands in.
+    const refused =
+      (await deniedBy(authorizer, c, 'execute', ref('eval_suite', suiteId))) ??
+      (await deniedBy(authorizer, c, 'write', ref('project', projectId as unknown as string))) ??
+      (await deniedBy(authorizer, c, 'execute', target));
+    if (refused !== undefined) return refused;
+    const refusal =
+      (await versionsRefusal(versionsCheck, tenantId, parsed.value)) ??
+      (await overridesRefusal(overridesCheck, tenantId, parsed.value));
     if (refusal !== undefined) {
       c.status(statusFor(refusal.code) as never);
       return c.json(toWireError(refusal, requestId));
@@ -206,8 +269,16 @@ function startRouter(binding: EvalRunBinding, versionsCheck?: FlowVersionsCheck)
 
 // ---------- /v1/eval-runs/* (readback + cancel + SSE) ----------
 
-function readbackRouter(binding: EvalRunBinding): Hono<AppEnv> {
+function readbackRouter(binding: EvalRunBinding, authorizer?: Authorizer): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
+  /** The refusal, if any, of `action` on the suite of the run named in the path. */
+  const onRunSuite = async (c: Context<AppEnv>, action: Action): Promise<Response | undefined> => {
+    if (authorizer === undefined) return undefined;
+    const tenantId = c.get('tenantId') as TenantId;
+    const run = await binding.get({ tenantId, runId: c.req.param('runId') as RunId });
+    if (run === null) return undefined;
+    return deniedBy(authorizer, c, action, ref('eval_suite', run.suiteId));
+  };
 
   // ---------- GET / (list) ----------
   r.get('/', async (c) => {
@@ -270,8 +341,14 @@ function readbackRouter(binding: EvalRunBinding): Hono<AppEnv> {
       ...(scopeParsed.scope !== undefined && { scope: scopeParsed.scope }),
       ...(scopeParsed.inherit !== undefined && { inherit: scopeParsed.inherit }),
     });
+    const visible =
+      authorizer === undefined
+        ? page.data
+        : await authorizer.filterByCan(c, 'read', page.data, (run) =>
+            ref('eval_suite', run.suiteId),
+          );
     return c.json({
-      data: page.data.map(serializeEvalRun),
+      data: visible.map(serializeEvalRun),
       hasMore: page.nextCursor !== undefined,
       ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
     });
@@ -279,6 +356,8 @@ function readbackRouter(binding: EvalRunBinding): Hono<AppEnv> {
 
   // ---------- GET /:runId ----------
   r.get('/:runId', async (c) => {
+    const refused = await onRunSuite(c, 'read');
+    if (refused !== undefined) return refused;
     const requestId = c.get('requestId');
     const tenantId = c.get('tenantId') as TenantId;
     const runId = c.req.param('runId') as RunId;
@@ -298,6 +377,8 @@ function readbackRouter(binding: EvalRunBinding): Hono<AppEnv> {
 
   // ---------- POST /:runId/cancel ----------
   r.post('/:runId/cancel', async (c) => {
+    const refused = await onRunSuite(c, 'write');
+    if (refused !== undefined) return refused;
     const requestId = c.get('requestId');
     const tenantId = c.get('tenantId') as TenantId;
     const runId = c.req.param('runId') as RunId;
@@ -340,6 +421,8 @@ function readbackRouter(binding: EvalRunBinding): Hono<AppEnv> {
 
   // ---------- GET /:runId/events (SSE) ----------
   r.get('/:runId/events', async (c) => {
+    const refused = await onRunSuite(c, 'read');
+    if (refused !== undefined) return refused;
     const requestId = c.get('requestId');
     const tenantId = c.get('tenantId') as TenantId;
     const runId = c.req.param('runId') as RunId;

package/src/routes/eval-suites.ts

@@ -2,6 +2,7 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import { Hono } from 'hono';
+import { routePath } from 'hono/route';
 
 import { type Principal, ref, tuplesForCreate } from '@kindgi/authz';
 import type { Cursor, ProjectId, TenantId, UserId } from '@kindgi/types';
@@ -16,6 +17,7 @@ import {
 import type { Authorizer } from '../middleware/authorize.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit } from './pagination.js';
+import { projectMismatch } from './project-mismatch.js';
 import { parseScopeParams } from './scope-params.js';
 
 /**
@@ -75,8 +77,26 @@ export function evalSuitesRouter(
       return mw(c, next);
     });
     r.use('/:suiteId/*', async (c, next) => {
-      const action = c.req.method === 'GET' ? 'read' : 'admin';
       const suiteId = c.req.param('suiteId') ?? '';
+      // Starting a run (`POST /:suiteId/runs`, exactly) doesn't change the
+      // suite, and the start route checks it all itself: `execute` on the
+      // suite, `write` on the project and `execute` on the agent or flow.
+      const under = c.req.path.split('/').slice(routePath(c).split('/').length - 1);
+      if (c.req.method === 'POST' && under.length === 1 && under[0] === 'runs') return next();
+      const action = c.req.method === 'GET' ? 'read' : 'admin';
+      // A test set built from judgments under a suite id never registered
+      // (no head row) has no suite to check yet: the build checks `admin`
+      // on the project it names, the project the new suite belongs to. A
+      // tombstoned suite keeps its head row, so it's checked as an existing
+      // one. Anything else under a suite id, and a build under an existing
+      // suite, checks the suite.
+      if (
+        c.req.method === 'POST' &&
+        c.req.path.endsWith('/versions/from-judgments') &&
+        !(await binding.headExists({ tenantId: c.get('tenantId') as TenantId, suiteId }))
+      ) {
+        return next();
+      }
       const mw = authorizer.authorize(action, () => ref('eval_suite', suiteId));
       return mw(c, next);
     });
@@ -128,8 +148,15 @@ export function evalSuitesRouter(
       ...(scopeParsed.scope !== undefined && { scope: scopeParsed.scope }),
       ...(scopeParsed.inherit !== undefined && { inherit: scopeParsed.inherit }),
     });
+    // Only what the caller may read (T243 A), as `GET …/:id` asks.
+    const visible =
+      authorizer === undefined
+        ? page.data
+        : await authorizer.filterByCan(c, 'read', page.data, (a) =>
+            ref('eval_suite', a.id as unknown as string),
+          );
     return c.json({
-      data: page.data.map(serializeEvalSuite),
+      data: visible.map(serializeEvalSuite),
       hasMore: page.nextCursor !== undefined,
       ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
     });
@@ -318,6 +345,9 @@ export function evalSuitesRouter(
         ),
       );
     }
+    if (outcome.kind === 'project-mismatch') {
+      return projectMismatch(c, 'eval-suite', outcome.suiteId, outcome.projectId);
+    }
     if (outcome.kind === 'project-not-found') {
       // Caller supplied a `projectId` that does not resolve within
       // this tenant. Distinct signal from `already-registered` so the

package/src/routes/event-triggers.ts

@@ -7,6 +7,7 @@ import type { Context } from 'hono';
 import type { Cursor, TenantId, TriggerId } from '@kindgi/types';
 
 import { statusFor, toWireError } from '../errors.js';
+import type { Authorizer } from '../middleware/authorize.js';
 import type {
   EventTriggerRecord,
   RegisterEventTriggerInput,
@@ -15,6 +16,7 @@ import type {
 } from '../trigger-binding.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit } from './pagination.js';
+import { triggerAccess } from './trigger-access.js';
 
 /**
  * Event triggers — fire a flow run when a matching event arrives on
@@ -22,9 +24,16 @@ import { clampLimit } from './pagination.js';
  *
  * Seven routes, mirroring the schedules surface. This surface registers
  * triggers; it does not publish events.
+ *
+ * With an authorizer (T243 A), the trigger's flow decides who may see or
+ * change it (`trigger-access.ts`).
  */
-export function eventTriggersRouter(binding: TriggerRegistryBinding): Hono<AppEnv> {
+export function eventTriggersRouter(
+  binding: TriggerRegistryBinding,
+  authorizer?: Authorizer,
+): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
+  const access = triggerAccess(binding, 'event', authorizer);
 
   // ---------- POST / (register) ----------
   r.post('/', async (c) => {
@@ -37,11 +46,14 @@ export function eventTriggersRouter(binding: TriggerRegistryBinding): Hono<AppEn
 
     const flowId = requireString(body, 'flowId');
     const flowVersion = requireString(body, 'flowVersion');
-    const eventKind = requireString(body.config, 'config.eventKind');
+    const eventKind = requireString(body, 'config.eventKind');
     if (flowId.kind === 'err') return bad(c, requestId, flowId.message);
     if (flowVersion.kind === 'err') return bad(c, requestId, flowVersion.message);
     if (eventKind.kind === 'err') return bad(c, requestId, eventKind.message);
 
+    const refused = await access.onRegister(c, flowId.value);
+    if (refused !== undefined) return refused;
+
     const rawConfig = (body.config ?? {}) as Record<string, unknown>;
     const registerInput: RegisterEventTriggerInput = {
       kind: 'event',
@@ -84,7 +96,9 @@ export function eventTriggersRouter(binding: TriggerRegistryBinding): Hono<AppEn
       ...(statusFilter !== undefined && { status: statusFilter }),
     });
     return c.json({
-      data: page.data.map((row) => serializeEventTrigger(row as EventTriggerRecord)),
+      data: (await access.visible(c, page.data as readonly EventTriggerRecord[])).map(
+        serializeEventTrigger,
+      ),
       hasMore: page.nextCursor !== undefined,
       ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
     });
@@ -95,6 +109,8 @@ export function eventTriggersRouter(binding: TriggerRegistryBinding): Hono<AppEn
     const requestId = c.get('requestId');
     const tenantId = c.get('tenantId') as TenantId;
     const triggerId = c.req.param('triggerId') as TriggerId;
+    const refused = await access.onTrigger(c, triggerId, ['read']);
+    if (refused !== undefined) return refused;
 
     const rec = await binding.get({ tenantId, triggerId });
     if (rec === null || rec.kind !== 'event') return notFound(c, requestId, triggerId);
@@ -106,6 +122,8 @@ export function eventTriggersRouter(binding: TriggerRegistryBinding): Hono<AppEn
     const requestId = c.get('requestId');
     const tenantId = c.get('tenantId') as TenantId;
     const triggerId = c.req.param('triggerId') as TriggerId;
+    const refused = await access.onTrigger(c, triggerId, ['write', 'execute']);
+    if (refused !== undefined) return refused;
 
     const parsed = await parseJsonObject(c, requestId);
     if (parsed.kind === 'err') return parsed.response;
@@ -149,6 +167,8 @@ export function eventTriggersRouter(binding: TriggerRegistryBinding): Hono<AppEn
     const requestId = c.get('requestId');
     const tenantId = c.get('tenantId') as TenantId;
     const triggerId = c.req.param('triggerId') as TriggerId;
+    const refused = await access.onTrigger(c, triggerId, ['write']);
+    if (refused !== undefined) return refused;
     const result = await binding.pause({ tenantId, triggerId });
     if (result.kind === 'err') return lifecycleError(c, requestId, result.error, triggerId);
     return c.json(serializeEventTrigger(result.value as EventTriggerRecord));
@@ -159,6 +179,8 @@ export function eventTriggersRouter(binding: TriggerRegistryBinding): Hono<AppEn
     const requestId = c.get('requestId');
     const tenantId = c.get('tenantId') as TenantId;
     const triggerId = c.req.param('triggerId') as TriggerId;
+    const refused = await access.onTrigger(c, triggerId, ['write']);
+    if (refused !== undefined) return refused;
     const result = await binding.resume({ tenantId, triggerId });
     if (result.kind === 'err') return lifecycleError(c, requestId, result.error, triggerId);
     return c.json(serializeEventTrigger(result.value as EventTriggerRecord));
@@ -168,6 +190,8 @@ export function eventTriggersRouter(binding: TriggerRegistryBinding): Hono<AppEn
   r.post('/:triggerId/unregister', async (c) => {
     const tenantId = c.get('tenantId') as TenantId;
     const triggerId = c.req.param('triggerId') as TriggerId;
+    const refused = await access.onTrigger(c, triggerId, ['write']);
+    if (refused !== undefined) return refused;
     const outcome = await binding.unregister({ tenantId, triggerId });
     return c.json({
       eventTriggerId: triggerId as unknown as string,

package/src/routes/export-signing-keys.ts

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { Hono } from 'hono';
+
+import type { ExportSigningBinding } from '@kindgi/crypto';
+
+import type { AppEnv } from '../types.js';
+
+/**
+ * `GET /v1/export-signing-keys`: the public keys this deployment signs
+ * its exports with, active first. A verifier pins them: an export's own
+ * embedded `publicKey` only proves it wasn't changed, these say who
+ * signed it. Empty when the deployment doesn't sign exports. Any
+ * authenticated caller may read them; they're public keys.
+ */
+export function exportSigningKeysRouter(signer: ExportSigningBinding | undefined): Hono<AppEnv> {
+  const r = new Hono<AppEnv>();
+  r.get('/', (c) =>
+    c.json({
+      data: (signer?.listKeys() ?? []).map((key, index) => ({
+        keyId: key.keyId,
+        algorithm: key.algorithm,
+        publicKeyPem: key.publicKeyPem,
+        fingerprint: key.fingerprint,
+        active: index === 0,
+      })),
+    }),
+  );
+  return r;
+}

package/src/routes/flows.ts

@@ -18,6 +18,7 @@ import { refuseWritesWhenReadOnly } from '../registry-read-only.js';
 import type { ToolRegistryBinding } from '../tool-binding.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit } from './pagination.js';
+import { projectMismatch } from './project-mismatch.js';
 import { parseScopeParams } from './scope-params.js';
 
 /**
@@ -132,8 +133,15 @@ export function flowsRouter(
       ...(scopeParsed.scope !== undefined && { scope: scopeParsed.scope }),
       ...(scopeParsed.inherit !== undefined && { inherit: scopeParsed.inherit }),
     });
+    // Only what the caller may read (T243 A), as `GET …/:id` asks.
+    const visible =
+      authorizer === undefined
+        ? page.data
+        : await authorizer.filterByCan(c, 'read', page.data, (a) =>
+            ref('flow', a.id as unknown as string),
+          );
     return c.json({
-      data: page.data.map(serializeGraph),
+      data: visible.map(serializeGraph),
       hasMore: page.nextCursor !== undefined,
       ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
     });
@@ -334,6 +342,9 @@ export function flowsRouter(
         ),
       );
     }
+    if (outcome.kind === 'project-mismatch') {
+      return projectMismatch(c, 'flow', outcome.flowId as unknown as string, outcome.projectId);
+    }
     if (outcome.kind === 'project-not-found') {
       // Caller supplied a `projectId` that does not resolve within
       // this tenant. Distinct signal from `already-registered` so the

package/src/routes/gate-policies.ts

@@ -4,7 +4,7 @@
 import { type Context, Hono } from 'hono';
 
 import { ref } from '@kindgi/authz';
-import type { Cursor, TenantId } from '@kindgi/types';
+import type { Cursor, LiveScope, TenantId } from '@kindgi/types';
 
 import { statusFor, toWireError } from '../errors.js';
 import type { GatePolicyBinding, GatePolicyError } from '../gate-policy-binding.js';
@@ -30,7 +30,10 @@ const ID_RE = /^[a-z0-9][a-z0-9._-]{0,127}$/;
  *   POST /:policyId/versions/:version/unregister|reinstate
  *
  * Writes need `admin` on the tenant: whoever may promote mustn't be able
- * to loosen the gate on their own promotion.
+ * to loosen the gate on their own promotion. Reads need `read` on the
+ * policy's scope (a segment's: its project), as judge classes do: one the
+ * caller can't read answers 404, as if it weren't there, and the list
+ * shows only those they can.
  */
 export function gatePoliciesRouter(
   binding: GatePolicyBinding,
@@ -46,6 +49,11 @@ export function gatePoliciesRouter(
     });
   }
 
+  /** Whether the caller may read a policy: `read` on its scope. */
+  const canRead = async (c: Ctx, policy: { readonly scope: LiveScope }): Promise<boolean> =>
+    authorizer === undefined ||
+    authorizer.can(c, 'read', scopeRef(c.get('tenantId') as TenantId, policy.scope));
+
   r.get('/', async (c) => {
     const requestId = c.get('requestId');
     const scope = scopeFromQuery((n) => c.req.query(n), c.req.queries('segment') ?? []);
@@ -59,8 +67,14 @@ export function gatePoliciesRouter(
       ...(scope.scope !== undefined && { scope: scope.scope }),
       ...(cursor !== undefined && cursor.length > 0 && { cursor: cursor as Cursor }),
     });
+    const visible =
+      authorizer === undefined
+        ? page.data
+        : await authorizer.filterByCan(c, 'read', page.data, (p) =>
+            scopeRef(c.get('tenantId') as TenantId, p.scope),
+          );
     return c.json({
-      data: page.data.map(serializeGatePolicy),
+      data: visible.map(serializeGatePolicy),
       hasMore: page.nextCursor !== undefined,
       ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
     });
@@ -71,7 +85,7 @@ export function gatePoliciesRouter(
       tenantId: c.get('tenantId') as TenantId,
       id: c.req.param('policyId'),
     });
-    if (found === null) return notFound(c, c.req.param('policyId'));
+    if (found === null || !(await canRead(c, found))) return notFound(c, c.req.param('policyId'));
     return c.json(serializeGatePolicy(found));
   });
 
@@ -80,7 +94,11 @@ export function gatePoliciesRouter(
       tenantId: c.get('tenantId') as TenantId,
       id: c.req.param('policyId'),
     });
-    if (versions.length === 0) return notFound(c, c.req.param('policyId'));
+    // A policy's versions share its scope (`gate-policy-scope-changed`).
+    const first = versions[0];
+    if (first === undefined || !(await canRead(c, first))) {
+      return notFound(c, c.req.param('policyId'));
+    }
     return c.json({ data: versions.map(serializeGatePolicy), hasMore: false });
   });
 
@@ -90,7 +108,7 @@ export function gatePoliciesRouter(
       id: c.req.param('policyId'),
       version: c.req.param('version'),
     });
-    if (found === null) {
+    if (found === null || !(await canRead(c, found))) {
       return notFound(c, c.req.param('policyId'), c.req.param('version'));
     }
     return c.json(serializeGatePolicy(found));
@@ -144,6 +162,19 @@ export function gatePoliciesRouter(
 
 type Ctx = Context<AppEnv>;
 
+/** The resource a gate policy's scope is: what reading it needs `read` on. */
+function scopeRef(tenantId: TenantId, scope: LiveScope) {
+  switch (scope.kind) {
+    case 'tenant':
+      return ref('tenant', tenantId as unknown as string);
+    case 'org':
+      return ref('org', scope.orgId as unknown as string);
+    case 'project':
+    case 'segment':
+      return ref('project', scope.projectId as unknown as string);
+  }
+}
+
 function badInput(c: Ctx, requestId: string, message: string) {
   c.status(statusFor('bad-input') as never);
   return c.json(toWireError({ code: 'bad-input', message }, requestId));