@kindgi/api 0.1.4 → 0.1.5-rc.0

package/src/routes/tokens.ts

@@ -4,31 +4,44 @@
 import type { Context, MiddlewareHandler } from 'hono';
 import { Hono } from 'hono';
 
-import { ref } from '@kindgi/authz';
 import type { ApiTokenId, ProjectId, TenantId } from '@kindgi/types';
 
+import { callerPrincipal, callerRef, isTenantAdmin, principalToWire } from '../caller.js';
+
 import { statusFor, toWireError } from '../errors.js';
 import type { Authorizer } from '../middleware/authorize.js';
+import { withholdFromReplay } from '../middleware/idempotency.js';
 import {
   API_TOKEN_ROLES,
   type ApiTokenRecord,
   type ApiTokenRole,
   type TokenAdmin,
+  type TokenPrincipal,
 } from '../token-admin.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit, decodeCursor, encodeCursor } from './pagination.js';
 
 /**
- * API keys: mint, list, read, revoke. Every route is tenant-admin only:
- * `admin` on the tenant when authorization is on, otherwise the
- * `tenant-admin` scope on the caller's token.
+ * API keys: mint, list, read, revoke. A key acts for one principal (a
+ * person or a service account) with that principal's grants; its role is
+ * a ceiling under them and its project a narrowing.
  *
- * A caller can only give a new key what it holds itself: every
- * capability it grants must be one of its own.
+ * - **Your own keys:** a person, or a service account's key, may mint,
+ *   list, read and revoke the keys that act for them.
+ * - **Someone else's:** only a tenant admin (`admin` on the tenant when
+ *   authorization is on, otherwise the `tenant-admin` scope) mints keys
+ *   for another principal, and sees and revokes every key. A tenant admin
+ *   whose token names no principal mints, as before principals, keys
+ *   that are their own service account.
+ * - **What a new key may hold:** an `admin` key needs a tenant admin
+ *   minting it (and, for someone else, a principal that is one: the store
+ *   refuses `role-exceeds-principal`). Every capability granted must be
+ *   one the minter holds. A minter narrowed to a project mints only keys
+ *   narrowed to the same project.
  */
 export function tokensRouter(admin: TokenAdmin, authorizer?: Authorizer): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
-  r.use('/*', requireTenantAdmin(authorizer));
+  r.use('/*', requireOwnerOrAdmin(authorizer));
 
   // ---------- POST / (mint) ----------
   r.post('/', async (c) => {
@@ -40,22 +53,15 @@ export function tokensRouter(admin: TokenAdmin, authorizer?: Authorizer): Hono<A
     const parsed = parseMintBody(body.value);
     if (parsed.kind === 'err') return fail(c, parsed.error, requestId);
 
-    const held = new Set(c.get('capabilities') ?? []);
-    const notHeld = parsed.value.capabilities.filter((cap) => !held.has(cap));
-    if (notHeld.length > 0) {
-      return fail(
-        c,
-        {
-          code: 'permission-denied',
-          message: `A key can only be given capabilities its minter holds; you don't hold: ${notHeld.join(', ')}`,
-        },
-        requestId,
-      );
-    }
+    const owner = keyOwner(c);
+    const principal = parsed.value.for ?? owner;
+    const refused = await mintRefusal(c, authorizer, owner, principal, parsed.value);
+    if (refused !== undefined) return fail(c, refused, requestId);
 
     const createdBy = callerRef(c);
     const minted = await admin.mint({
       tenantId,
+      ...(principal !== undefined && { principal }),
       role: parsed.value.role,
       capabilities: parsed.value.capabilities,
       ...(parsed.value.label !== undefined && { label: parsed.value.label }),
@@ -63,6 +69,11 @@ export function tokensRouter(admin: TokenAdmin, authorizer?: Authorizer): Hono<A
       ...(parsed.value.projectId !== undefined && { projectId: parsed.value.projectId }),
       ...(createdBy !== undefined && { createdBy }),
     });
+    if (!('token' in minted)) {
+      return fail(c, { code: minted.kind, message: minted.message }, requestId);
+    }
+    // The key's secret is shown once: an Idempotency-Key repeat doesn't get it.
+    withholdFromReplay(c);
     c.status(201);
     return c.json({ ...toWire(minted.record), token: minted.token });
   });
@@ -81,7 +92,16 @@ export function tokensRouter(admin: TokenAdmin, authorizer?: Authorizer): Hono<A
       }
       after = { createdAt: new Date(decoded.createdAt), tokenId: decoded.id as ApiTokenId };
     }
-    const records = await admin.list({ tenantId, limit: limit + 1, ...(after && { after }) });
+    const filter = parsePrincipalQuery(c.req.query('principal'));
+    if (filter.kind === 'err') return fail(c, filter.error, requestId);
+    // An admin sees every key (or one principal's); anyone else, their own.
+    const principal = (await isTenantAdmin(c, authorizer)) ? filter.value : keyOwner(c);
+    const records = await admin.list({
+      tenantId,
+      limit: limit + 1,
+      ...(principal !== undefined && { principal }),
+      ...(after && { after }),
+    });
     const hasMore = records.length > limit;
     const page = hasMore ? records.slice(0, limit) : records;
     const last = page[page.length - 1];
@@ -101,9 +121,8 @@ export function tokensRouter(admin: TokenAdmin, authorizer?: Authorizer): Hono<A
   // ---------- GET /:tokenId ----------
   r.get('/:tokenId', async (c) => {
     const requestId = c.get('requestId');
-    const tenantId = c.get('tenantId') as TenantId;
     const tokenId = c.req.param('tokenId') as ApiTokenId;
-    const record = await admin.get({ tenantId, tokenId });
+    const record = await visibleKey(c, admin, authorizer, tokenId);
     if (record === undefined) return notFound(c, tokenId, requestId);
     return c.json(toWire(record));
   });
@@ -113,8 +132,16 @@ export function tokensRouter(admin: TokenAdmin, authorizer?: Authorizer): Hono<A
     const requestId = c.get('requestId');
     const tenantId = c.get('tenantId') as TenantId;
     const tokenId = c.req.param('tokenId') as ApiTokenId;
-
-    const outcome = await admin.revoke({ tenantId, tokenId });
+    // Someone else's key reads as missing, as it does for `get`.
+    if ((await visibleKey(c, admin, authorizer, tokenId)) === undefined) {
+      return notFound(c, tokenId, requestId);
+    }
+    const revokedBy = callerRef(c);
+    const outcome = await admin.revoke({
+      tenantId,
+      tokenId,
+      ...(revokedBy !== undefined && { revokedBy }),
+    });
     if (outcome.kind === 'not-found') return notFound(c, tokenId, requestId);
     return c.json({ tokenId: tokenId as unknown as string, revoked: true });
   });
@@ -122,18 +149,10 @@ export function tokensRouter(admin: TokenAdmin, authorizer?: Authorizer): Hono<A
   return r;
 }
 
-function requireTenantAdmin(authorizer: Authorizer | undefined): MiddlewareHandler<AppEnv> {
-  if (authorizer !== undefined) {
-    return async (c, next) => {
-      const tenantId = c.get('tenantId') as TenantId;
-      const mw = authorizer.authorize('admin', async () =>
-        ref('tenant', tenantId as unknown as string),
-      );
-      return mw(c, next);
-    };
-  }
+/** A caller with keys of their own, or a tenant admin. */
+function requireOwnerOrAdmin(authorizer: Authorizer | undefined): MiddlewareHandler<AppEnv> {
   return async (c, next) => {
-    if (!(c.get('scopes') ?? []).includes('tenant-admin')) {
+    if (keyOwner(c) === undefined && !(await isTenantAdmin(c, authorizer))) {
       return fail(
         c,
         { code: 'permission-denied', message: 'Managing API keys needs a tenant admin' },
@@ -145,18 +164,80 @@ function requireTenantAdmin(authorizer: Authorizer | undefined): MiddlewareHandl
   };
 }
 
-/** The caller as a principal reference: `user:<id>` or `service_account:<tokenId>`. */
-function callerRef(c: Context<AppEnv>): string | undefined {
-  const userId = c.get('userId');
-  if (userId !== undefined) return `user:${userId as unknown as string}`;
-  const tokenId = c.get('tokenId');
-  if (tokenId !== undefined) return `service_account:${tokenId as unknown as string}`;
+/**
+ * Whom the caller's own keys act for: the person, or the service account
+ * the caller's key acts for. A token naming neither (a key from before
+ * principals, a static token) has no keys of its own.
+ */
+function keyOwner(c: Context<AppEnv>): TokenPrincipal | undefined {
+  const caller = callerPrincipal(c);
+  if (caller?.kind === 'service-account' && c.get('serviceAccountId') === undefined) {
+    return undefined;
+  }
+  return caller;
+}
+
+function samePrincipal(a: TokenPrincipal, b: TokenPrincipal | undefined): boolean {
+  if (b === undefined) return false;
+  if (a.kind === 'user') return b.kind === 'user' && b.userId === a.userId;
+  return b.kind === 'service-account' && b.serviceAccountId === a.serviceAccountId;
+}
+
+/** Why the route refuses this mint before the store sees it, if it does. */
+async function mintRefusal(
+  c: Context<AppEnv>,
+  authorizer: Authorizer | undefined,
+  owner: TokenPrincipal | undefined,
+  principal: TokenPrincipal | undefined,
+  body: ParsedMintBody,
+): Promise<WireError | undefined> {
+  const forSomeoneElse = principal !== undefined && !samePrincipal(principal, owner);
+  if ((forSomeoneElse || body.role === 'admin') && !(await isTenantAdmin(c, authorizer))) {
+    return {
+      code: 'permission-denied',
+      message: forSomeoneElse
+        ? 'Only a tenant admin mints keys for someone else'
+        : 'Only a tenant admin mints an admin key',
+    };
+  }
+  const held = new Set(c.get('capabilities') ?? []);
+  const notHeld = body.capabilities.filter((cap) => !held.has(cap));
+  if (notHeld.length > 0) {
+    return {
+      code: 'permission-denied',
+      message: `A key can only be given capabilities its minter holds; you don't hold: ${notHeld.join(', ')}`,
+    };
+  }
+  const narrowedTo = c.get('tokenProjectId');
+  if (narrowedTo !== undefined && body.projectId !== (narrowedTo as unknown as ProjectId)) {
+    return {
+      code: 'key-project-mismatch',
+      message: `Your key is limited to project ${narrowedTo}: a key it mints must be limited to it too`,
+    };
+  }
   return undefined;
 }
 
+/** A key the caller may see: any, for a tenant admin; otherwise only their own. */
+async function visibleKey(
+  c: Context<AppEnv>,
+  admin: TokenAdmin,
+  authorizer: Authorizer | undefined,
+  tokenId: ApiTokenId,
+): Promise<ApiTokenRecord | undefined> {
+  const tenantId = c.get('tenantId') as TenantId;
+  const record = await admin.get({ tenantId, tokenId });
+  if (record === undefined) return undefined;
+  if (await isTenantAdmin(c, authorizer)) return record;
+  return record.principal !== undefined && samePrincipal(record.principal, keyOwner(c))
+    ? record
+    : undefined;
+}
+
 function toWire(record: ApiTokenRecord): Record<string, unknown> {
   return {
     tokenId: record.tokenId as unknown as string,
+    ...(record.principal !== undefined && { principal: principalToWire(record.principal) }),
     role: record.role,
     capabilities: record.capabilities,
     ...(record.label !== undefined && { label: record.label }),
@@ -207,6 +288,7 @@ async function readJsonBody(
 }
 
 type ParsedMintBody = {
+  readonly for?: TokenPrincipal;
   readonly role: ApiTokenRole;
   readonly capabilities: readonly string[];
   readonly label?: string;
@@ -232,23 +314,29 @@ function parseMintBody(body: unknown): Parsed<ParsedMintBody> {
   if (role.kind === 'err') return role;
   const capabilities = parseCapabilities(b.capabilities);
   if (capabilities.kind === 'err') return capabilities;
+  const principal = parseFor(b.for);
+  if (principal.kind === 'err') return principal;
   const out: {
+    for?: TokenPrincipal;
     role: ApiTokenRole;
     capabilities: readonly string[];
     label?: string;
     expiresAt?: Date;
     projectId?: ProjectId;
-  } = { role: role.value, capabilities: capabilities.value };
+  } = {
+    ...(principal.value !== undefined && { for: principal.value }),
+    role: role.value,
+    capabilities: capabilities.value,
+  };
 
   if (b.label !== undefined) {
     if (typeof b.label !== 'string') return badInput('`label` must be a string');
     out.label = b.label;
   }
   if (b.expiresAt !== undefined) {
-    if (typeof b.expiresAt !== 'string') return badInput('`expiresAt` must be an ISO date string');
-    const parsed = new Date(b.expiresAt);
-    if (Number.isNaN(parsed.getTime())) return badInput('`expiresAt` is not a valid ISO date');
-    out.expiresAt = parsed;
+    const expiresAt = parseExpiresAt(b.expiresAt);
+    if (expiresAt.kind === 'err') return expiresAt;
+    out.expiresAt = expiresAt.value;
   }
   if (b.projectId !== undefined) {
     if (typeof b.projectId !== 'string') {
@@ -259,6 +347,14 @@ function parseMintBody(body: unknown): Parsed<ParsedMintBody> {
   return { kind: 'ok', value: out };
 }
 
+/** `expiresAt`: an ISO date string. */
+function parseExpiresAt(raw: unknown): Parsed<Date> {
+  if (typeof raw !== 'string') return badInput('`expiresAt` must be an ISO date string');
+  const parsed = new Date(raw);
+  if (Number.isNaN(parsed.getTime())) return badInput('`expiresAt` is not a valid ISO date');
+  return { kind: 'ok', value: parsed };
+}
+
 /** `role`: `admin` | `member`; `member` when absent (least privilege). */
 function parseRole(raw: unknown): Parsed<ApiTokenRole> {
   if (raw === undefined) return { kind: 'ok', value: 'member' };
@@ -283,3 +379,33 @@ function parseCapabilities(raw: unknown): Parsed<readonly string[]> {
   }
   return { kind: 'ok', value: out };
 }
+
+/** `for`, when present: whom the key acts for. */
+function parseFor(raw: unknown): Parsed<TokenPrincipal | undefined> {
+  return raw === undefined ? { kind: 'ok', value: undefined } : parsePrincipalBody(raw);
+}
+
+/** `for`: `{kind: 'user' | 'service-account', id}`. */
+function parsePrincipalBody(raw: unknown): Parsed<TokenPrincipal> {
+  const b = (raw ?? {}) as { kind?: unknown; id?: unknown };
+  if (typeof b.id !== 'string' || b.id.length === 0) {
+    return badInput('`for.id` must be the id of a person or a service account');
+  }
+  if (b.kind === 'user') return { kind: 'ok', value: { kind: 'user', userId: b.id } };
+  if (b.kind === 'service-account') {
+    return { kind: 'ok', value: { kind: 'service-account', serviceAccountId: b.id } };
+  }
+  return badInput("`for.kind` must be 'user' or 'service-account'");
+}
+
+/** `?principal=user:<id>` or `?principal=service-account:<id>`: one principal's keys (admins). */
+function parsePrincipalQuery(raw: string | undefined): Parsed<TokenPrincipal | undefined> {
+  if (raw === undefined || raw === '') return { kind: 'ok', value: undefined };
+  const colon = raw.indexOf(':');
+  const kind = raw.slice(0, colon);
+  const id = raw.slice(colon + 1);
+  if (colon <= 0 || id === '') {
+    return badInput('`principal` is `user:<id>` or `service-account:<id>`');
+  }
+  return parsePrincipalBody({ kind, id });
+}

package/src/routes/tools.ts

@@ -13,6 +13,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';
 
 /**
@@ -127,8 +128,15 @@ export function toolsRouter(
       ...(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('tool', a.id as unknown as string),
+          );
     return c.json({
-      data: page.data.map(serializeTool),
+      data: visible.map(serializeTool),
       hasMore: page.nextCursor !== undefined,
       ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
     });
@@ -329,6 +337,9 @@ export function toolsRouter(
         ),
       );
     }
+    if (outcome.kind === 'project-mismatch') {
+      return projectMismatch(c, 'tool', outcome.toolId 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/trigger-access.ts

@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Context } from 'hono';
+
+import { type Action, ref } from '@kindgi/authz';
+import type { TenantId, TriggerId } from '@kindgi/types';
+
+import type { Authorizer } from '../middleware/authorize.js';
+import type { TriggerRecord, TriggerRegistryBinding } from '../trigger-binding.js';
+import type { AppEnv } from '../types.js';
+import { deniedBy } from './denied.js';
+
+/**
+ * Who may manage an event or webhook trigger (T243 A): the flow it fires.
+ * A trigger has no parent tuple of its own, so every check names its
+ * flow: `read` to see it; `write` to pause, resume or unregister it; and
+ * `write` plus `execute` to register it or change what it runs, since it
+ * starts runs of the flow as its registrant would. With no authorizer,
+ * nothing is checked.
+ */
+export interface TriggerAccess {
+  /** Registering a trigger for `flowId`: the refusal, if any. */
+  onRegister(c: Context<AppEnv>, flowId: string): Promise<Response | undefined>;
+  /**
+   * A route on one trigger: the refusal, if any. A trigger that isn't
+   * there, or is of another kind, passes on to the handler's 404.
+   */
+  onTrigger(
+    c: Context<AppEnv>,
+    triggerId: TriggerId,
+    actions: readonly Action[],
+  ): Promise<Response | undefined>;
+  /** The rows of a list whose flow the caller may read. */
+  visible<T extends { readonly flowId: string }>(
+    c: Context<AppEnv>,
+    rows: readonly T[],
+  ): Promise<readonly T[]>;
+}
+
+export function triggerAccess(
+  binding: TriggerRegistryBinding,
+  kind: Exclude<TriggerRecord['kind'], 'cron'>,
+  authorizer: Authorizer | undefined,
+): TriggerAccess {
+  const onFlow = async (
+    c: Context<AppEnv>,
+    flowId: string,
+    actions: readonly Action[],
+  ): Promise<Response | undefined> => {
+    for (const action of actions) {
+      const refused = await deniedBy(authorizer, c, action, ref('flow', flowId));
+      if (refused !== undefined) return refused;
+    }
+    return undefined;
+  };
+  return {
+    onRegister: (c, flowId) => onFlow(c, flowId, ['write', 'execute']),
+    async onTrigger(c, triggerId, actions) {
+      if (authorizer === undefined) return undefined;
+      const tenantId = c.get('tenantId') as TenantId;
+      const rec = await binding.get({ tenantId, triggerId });
+      // A schedule's access is the schedules router's own (it may run an agent).
+      if (rec === null || rec.kind === 'cron' || rec.kind !== kind) return undefined;
+      return onFlow(c, rec.flowId, actions);
+    },
+    async visible(c, rows) {
+      if (authorizer === undefined) return rows;
+      return authorizer.filterByCan(c, 'read', rows, (row) => ref('flow', row.flowId));
+    },
+  };
+}

package/src/routes/webhook-endpoints.ts

@@ -14,6 +14,8 @@ import type {
 } from '@kindgi/types';
 
 import { statusFor, toWireError } from '../errors.js';
+import type { Authorizer } from '../middleware/authorize.js';
+import { withholdFromReplay } from '../middleware/idempotency.js';
 import type { AppEnv } from '../types.js';
 import {
   WEBHOOK_DELIVERY_STATUSES,
@@ -30,6 +32,7 @@ import {
 } from '../webhook-endpoint-binding.js';
 import { clampLimit } from './pagination.js';
 import { parseSecretRef } from './secret-ref.js';
+import { tenantAdminAccess } from './tenant-access.js';
 
 const MAX_URL_LENGTH = 2048;
 const MAX_DESCRIPTION_LENGTH = 500;
@@ -41,8 +44,13 @@ const MAX_FLOW_ID_LENGTH = 200;
  * the platform sends signed events to, read their delivery log, redeliver
  * and send a test event. See `WebhookEndpointBinding`.
  */
-export function webhookEndpointsRouter(binding: WebhookEndpointBinding): Hono<AppEnv> {
+export function webhookEndpointsRouter(
+  binding: WebhookEndpointBinding,
+  authorizer?: Authorizer,
+): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
+  // Deliveries carry every project's runs: all of it is an admin's.
+  r.use('*', tenantAdminAccess(authorizer));
 
   // ---------- POST / (create) ----------
   r.post('/', async (c) => {
@@ -71,8 +79,12 @@ export function webhookEndpointsRouter(binding: WebhookEndpointBinding): Hono<Ap
   });
 
   // ---------- POST /generate-secret ----------
-  // A strong signing secret to store before registering; nothing is kept.
-  r.post('/generate-secret', (c) => c.json({ secret: generateWebhookSecret() }));
+  // A strong signing secret to store before registering; nothing is kept,
+  // and an Idempotency-Key repeat doesn't get it.
+  r.post('/generate-secret', (c) => {
+    withholdFromReplay(c);
+    return c.json({ secret: generateWebhookSecret() });
+  });
 
   // ---------- GET / (list) ----------
   r.get('/', async (c) => {

package/src/routes/webhooks.ts

@@ -9,6 +9,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 {
   RegisterWebhookTriggerInput,
   TriggerRegistryBinding,
@@ -17,6 +18,7 @@ import type {
 } from '../trigger-binding.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit } from './pagination.js';
+import { triggerAccess } from './trigger-access.js';
 
 /**
  * Webhook triggers — fire a flow run when an HMAC-signed request
@@ -33,9 +35,16 @@ import { clampLimit } from './pagination.js';
  * carries `hmacSecretName`, a handle into the tenant secrets store the
  * caller wrote to first via `POST /v1/secrets`. Rotation flows through
  * `POST /v1/secrets/:name/rotate` — trigger row untouched.
+ *
+ * With an authorizer (T243 A), the trigger's flow decides who may see or
+ * change it (`trigger-access.ts`).
  */
-export function webhooksRouter(binding: TriggerRegistryBinding): Hono<AppEnv> {
+export function webhooksRouter(
+  binding: TriggerRegistryBinding,
+  authorizer?: Authorizer,
+): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
+  const access = triggerAccess(binding, 'webhook', authorizer);
 
   // ---------- POST / (register) ----------
   r.post('/', async (c) => {
@@ -53,6 +62,9 @@ export function webhooksRouter(binding: TriggerRegistryBinding): Hono<AppEnv> {
     if (flowVersion.kind === 'err') return bad(c, requestId, flowVersion.message);
     if (hmacSecretName.kind === 'err') return bad(c, requestId, hmacSecretName.message);
 
+    const refused = await access.onRegister(c, flowId.value);
+    if (refused !== undefined) return refused;
+
     const rawConfig = (body.config ?? {}) as Record<string, unknown>;
     // Route mints the webhookId — a random UUID, returned so the caller
     // learns the receiver URL from the response.
@@ -100,7 +112,9 @@ export function webhooksRouter(binding: TriggerRegistryBinding): Hono<AppEnv> {
       ...(statusFilter !== undefined && { status: statusFilter }),
     });
     return c.json({
-      data: page.data.map((row) => serializeWebhook(row as WebhookTriggerRecord)),
+      data: (await access.visible(c, page.data as readonly WebhookTriggerRecord[])).map(
+        serializeWebhook,
+      ),
       hasMore: page.nextCursor !== undefined,
       ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
     });
@@ -111,6 +125,8 @@ export function webhooksRouter(binding: TriggerRegistryBinding): Hono<AppEnv> {
     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 !== 'webhook') return notFound(c, requestId, triggerId);
@@ -122,6 +138,8 @@ export function webhooksRouter(binding: TriggerRegistryBinding): Hono<AppEnv> {
     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;
@@ -162,6 +180,8 @@ export function webhooksRouter(binding: TriggerRegistryBinding): Hono<AppEnv> {
     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(serializeWebhook(result.value as WebhookTriggerRecord));
@@ -172,6 +192,8 @@ export function webhooksRouter(binding: TriggerRegistryBinding): Hono<AppEnv> {
     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(serializeWebhook(result.value as WebhookTriggerRecord));
@@ -181,6 +203,8 @@ export function webhooksRouter(binding: TriggerRegistryBinding): Hono<AppEnv> {
   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({
       triggerId: triggerId as unknown as string,

package/src/run-failure.ts

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { parseFailureMessage } from '@kindgi/agents';
+
+/** Why a run failed, on the wire (`Run.failure`). */
+export interface RunFailure {
+  /** The error's own code (`budget-exceeded`, `capability-routing-failed`, …), or `run-failed`. */
+  readonly code: string;
+  readonly message: string;
+  /** What the error came from, when it says (e.g. the router's reasons, by provider). */
+  readonly cause?: unknown;
+}
+
+/**
+ * A failed run's error, so a caller needn't parse `failureMessage`. An
+ * agent turn's failure reads back as its typed error, the way
+ * `invokeAgent` reads a run (`parseFailureMessage`; with several joined,
+ * the first). Any other is `run-failed`, in the run's own words.
+ * Absent unless the run is `failed`.
+ */
+export function runFailure(row: {
+  readonly runId: unknown;
+  readonly status: string;
+  readonly failureMessage?: string | null;
+}): RunFailure | undefined {
+  if (row.status !== 'failed') return undefined;
+  const raw = row.failureMessage ?? undefined;
+  const error = parseFailureMessage(raw);
+  if (error !== undefined) {
+    const cause = (error as { readonly cause?: unknown }).cause;
+    return {
+      code: error.code,
+      message: error.message,
+      ...(cause !== undefined && cause !== null && { cause }),
+    };
+  }
+  return {
+    code: 'run-failed',
+    message: raw !== undefined && raw !== '' ? raw : `Run ${String(row.runId)} failed`,
+  };
+}