@kindgi/api 0.1.4-rc.5 → 0.1.5-rc.0

package/src/routes/blocks.ts

@@ -3,17 +3,12 @@
 
 import { type Context, Hono } from 'hono';
 
-import {
-  BLOCK_KINDS,
-  type BlockDefinition,
-  type BlockKind,
-  settingsSchemaIssues,
-  validateBlock,
-} from '@kindgi/agents';
+import { BLOCK_KINDS, type BlockKind, validateBlock } from '@kindgi/agents';
 import { ref } from '@kindgi/authz';
 import type { Cursor, ProjectId, TenantId } from '@kindgi/types';
 
 import type { BlockPublishOutcome, BlockRecord, BlockRegistryBinding } from '../block-binding.js';
+import { continuityIssues, withCarriedSchema } from '../block-publish.js';
 import { statusFor, toWireError } from '../errors.js';
 import type { Authorizer } from '../middleware/authorize.js';
 import type { AppEnv } from '../types.js';
@@ -249,52 +244,6 @@ function isBlockKind(value: string): value is BlockKind {
   return (BLOCK_KINDS as readonly string[]).includes(value);
 }
 
-/**
- * A new version against the block's latest: the same kind, and a
- * settings version without a schema of its own satisfies the schema it
- * keeps (`carriedSchema`).
- */
-function continuityIssues(
-  latest: BlockRecord | null,
-  block: BlockDefinition,
-): { path: string; message: string }[] {
-  if (latest === null) return [];
-  if (latest.kind !== block.kind) {
-    return [
-      {
-        path: '/kind',
-        message: `block "${block.id}" is a ${latest.kind} block; a version can't change its kind`,
-      },
-    ];
-  }
-  const carried = carriedSchema(latest, block);
-  if (block.kind !== 'settings' || carried === undefined) return [];
-  return settingsSchemaIssues(block.content.values, carried).map((i) => ({
-    ...i,
-    message: `${i.message} (the schema of version ${latest.version})`,
-  }));
-}
-
-/**
- * The schema a settings version that gives none keeps: the latest
- * version's. A version that gives a schema replaces it (`{}` drops the
- * check on purpose).
- */
-function carriedSchema(
-  latest: BlockRecord | null,
-  block: BlockDefinition,
-): Readonly<Record<string, unknown>> | undefined {
-  if (latest?.kind !== 'settings' || block.kind !== 'settings') return undefined;
-  return block.content.schema === undefined ? latest.content.schema : undefined;
-}
-
-/** The version as stored: with the schema it keeps, if any. */
-function withCarriedSchema(latest: BlockRecord | null, block: BlockDefinition): BlockDefinition {
-  const schema = carriedSchema(latest, block);
-  if (schema === undefined || block.kind !== 'settings') return block;
-  return { ...block, content: { ...block.content, schema } };
-}
-
 /** The response to a publish outcome. */
 function published(c: Context<AppEnv>, outcome: BlockPublishOutcome) {
   const requestId = c.get('requestId');

package/src/routes/capabilities.ts

@@ -7,8 +7,10 @@ import type { Cursor, TenantId } from '@kindgi/types';
 
 import type { CapabilityDescriptor, CapabilityRegistryBinding } from '../capability-binding.js';
 import { statusFor, toWireError } from '../errors.js';
+import type { Authorizer } from '../middleware/authorize.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit } from './pagination.js';
+import { tenantResourceAccess } from './tenant-access.js';
 
 /**
  * Capabilities resource routes — part of the admin control plane.
@@ -19,8 +21,12 @@ import { clampLimit } from './pagination.js';
  * the HTTP surface — that would fork the closed-enum feature set the
  * router depends on.
  */
-export function capabilitiesRouter(binding: CapabilityRegistryBinding): Hono<AppEnv> {
+export function capabilitiesRouter(
+  binding: CapabilityRegistryBinding,
+  authorizer?: Authorizer,
+): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
+  r.use('*', tenantResourceAccess(authorizer));
 
   // ---------- GET / (list, cursor-paginated) ----------
   r.get('/', async (c) => {
@@ -75,5 +81,8 @@ function serializeCapability(d: CapabilityDescriptor): Record<string, unknown> {
     description: d.description,
     ...(d.kind !== undefined && { kind: d.kind }),
     ...(d.paramsSchema !== undefined && { paramsSchema: d.paramsSchema }),
+    ...(d.providers !== undefined && {
+      providers: d.providers.map((p) => ({ providerId: p.providerId, models: [...p.models] })),
+    }),
   };
 }

package/src/routes/compliance.ts

@@ -4,27 +4,31 @@
 import { Hono } from 'hono';
 
 import type { AuditEvent, AuditEventBinding, AuditEventFilter } from '@kindgi/audit-events';
-import type {
-  ComplianceEvidence,
-  ComplianceEvidenceGenerator,
-  EvidenceFilter,
-  LoadedClassifier,
-} from '@kindgi/compliance';
-import { auditEventToEvidence } from '@kindgi/compliance';
-import type { SigningKeyBinding } from '@kindgi/crypto';
+import type { ComplianceEvidence, EvidenceFilter, LoadedClassifier } from '@kindgi/compliance';
+import { auditEventToEvidence, collectEvidence } from '@kindgi/compliance';
+import type { ExportSigningBinding } from '@kindgi/crypto';
 import type {
   AgentId,
   ComplianceEvidenceId,
   FlowId,
   RunId,
-  SigningKeyId,
   TenantId,
   Timestamp,
 } from '@kindgi/types';
 
 import { statusFor, toWireError } from '../errors.js';
+import type { Authorizer } from '../middleware/authorize.js';
+import {
+  exportActor,
+  parseSigningKeyId,
+  readExportBody,
+  signExport,
+  signExportFailure,
+  signingNotConfigured,
+} from '../signed-export.js';
 import type { AppEnv } from '../types.js';
 import { clampLimit } from './pagination.js';
+import { tenantAdminAccess } from './tenant-access.js';
 
 /**
  * Compliance-evidence readback + signed-export routes over the unified
@@ -44,20 +48,26 @@ import { clampLimit } from './pagination.js';
 export interface ComplianceRouterOptions {
   readonly auditEvents: AuditEventBinding;
   readonly classifier: LoadedClassifier;
-  readonly signingKey?: SigningKeyBinding;
   /**
-   * Caller-plugged evidence generator. Supplied at app-composition
-   * time by the host (the Kindgi runtime provides one). Kept
-   * required — signed export routes cannot run without it, and the
-   * route mount guards (auditEvents + classifier) already imply
-   * signed-export capability.
+   * Signs evidence exports. Absent: `POST /evidence/export` answers
+   * `404 signing-not-configured`. The route collects the evidence from
+   * `auditEvents` itself (`collectEvidence`), signs it, and records the
+   * export there (`export-signed`).
    */
-  readonly complianceGenerator: ComplianceEvidenceGenerator;
+  readonly exportSigning?: ExportSigningBinding;
 }
 
-export function complianceRouter(options: ComplianceRouterOptions): Hono<AppEnv> {
+/** The evidence bundle body's version. Unchanged: the body is the one the runtime's generator signed. */
+const BUNDLE_SCHEMA_VERSION = '1.0.0';
+
+export function complianceRouter(
+  options: ComplianceRouterOptions,
+  authorizer?: Authorizer,
+): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
-  const { auditEvents, classifier, signingKey, complianceGenerator } = options;
+  // Evidence across the tenant, as the audit routes: an admin's.
+  r.use('*', tenantAdminAccess(authorizer));
+  const { auditEvents, classifier, exportSigning } = options;
 
   const isExportable = (kind: string): boolean => classifier.resolve(kind).exportable;
   const exportableKinds = (): readonly string[] =>
@@ -165,36 +175,10 @@ export function complianceRouter(options: ComplianceRouterOptions): Hono<AppEnv>
     const requestId = c.get('requestId');
     const tenantId = c.get('tenantId') as TenantId;
 
-    if (signingKey === undefined) {
-      c.status(statusFor('signing-not-configured') as never);
-      return c.json(
-        toWireError(
-          {
-            code: 'signing-not-configured',
-            message:
-              'This deployment does not have a `signingKey` binding mounted; signed compliance exports are unavailable.',
-          },
-          requestId,
-        ),
-      );
-    }
+    if (exportSigning === undefined) return signingNotConfigured(c, 'signed compliance exports');
 
-    let body: unknown;
-    try {
-      body = await c.req.json();
-    } catch {
-      c.status(statusFor('bad-input') as never);
-      return c.json(
-        toWireError({ code: 'bad-input', message: 'Request body must be valid JSON' }, requestId),
-      );
-    }
-    if (body === null || typeof body !== 'object' || Array.isArray(body)) {
-      c.status(statusFor('bad-input') as never);
-      return c.json(
-        toWireError({ code: 'bad-input', message: 'Request body must be an object' }, requestId),
-      );
-    }
-    const parsed = parseExportBody(body as Record<string, unknown>);
+    const read = await readExportBody(c);
+    const parsed = read.kind === 'ok' ? parseExportBody(read.value) : read;
     if (parsed.kind === 'err') {
       c.status(statusFor('bad-input') as never);
       return c.json(toWireError({ code: 'bad-input', message: parsed.message }, requestId));
@@ -223,52 +207,34 @@ export function complianceRouter(options: ComplianceRouterOptions): Hono<AppEnv>
       );
     }
 
-    const generator = complianceGenerator;
-    const bundle = await generator.exportSigned(tenantId, filter, signingKeyId);
-    if (bundle.kind === 'err') {
-      const err = bundle.error;
-      if (err.code === 'signing-key-missing') {
-        c.status(statusFor('signing-key-not-found') as never);
-        return c.json(
-          toWireError(
-            {
-              code: 'signing-key-not-found',
-              message: err.message,
-              signingKeyId: err.signingKeyId as unknown as string,
-            },
-            requestId,
-          ),
-        );
-      }
-      if (err.code === 'signing-failure') {
-        c.status(statusFor('compliance-export-failed') as never);
-        return c.json(
-          toWireError(
-            {
-              code: 'compliance-export-failed',
-              message: err.message,
-              signingKeyId: err.signingKeyId as unknown as string,
-            },
-            requestId,
-          ),
-        );
-      }
-      if (err.code === 'persistence-error') {
-        c.status(statusFor('persistence-error') as never);
-        return c.json(toWireError({ code: 'persistence-error', message: err.message }, requestId));
-      }
-      c.status(statusFor('compliance-export-failed') as never);
+    const records = await collectEvidence(auditEvents, tenantId, filter);
+    if (records.kind === 'err') {
+      c.status(statusFor('persistence-error') as never);
       return c.json(
-        toWireError(
-          {
-            code: 'compliance-export-failed',
-            message: `Signed export failed: ${(err as { readonly message: string }).message}`,
-          },
-          requestId,
-        ),
+        toWireError({ code: 'persistence-error', message: records.error.message }, requestId),
       );
     }
-    return c.json(bundle.value);
+    const signed = await signExport({
+      signer: exportSigning,
+      kind: 'compliance',
+      bundleSchemaVersion: BUNDLE_SCHEMA_VERSION,
+      ...(signingKeyId !== undefined && { signingKeyId }),
+      body: {
+        tenantId: tenantId as unknown as string,
+        filter,
+        records: records.value,
+        recordCount: records.value.length,
+      },
+      record: {
+        auditEvents,
+        tenantId,
+        actor: exportActor(c),
+        subject: { filter },
+      },
+    });
+    if (signed.kind === 'err')
+      return signExportFailure(c, signed.error, 'compliance-export-failed');
+    return c.json({ tenantId: tenantId as unknown as string, ...signed.value });
   });
 
   return r;
@@ -352,15 +318,13 @@ function buildAuditFilter(
 }
 
 interface ValidatedExportBody {
-  readonly signingKeyId: SigningKeyId;
+  readonly signingKeyId: string | undefined;
   readonly filter: EvidenceFilter;
 }
 
 function parseExportBody(body: Record<string, unknown>): ParseResult<ValidatedExportBody> {
-  const rawKey = body.signingKeyId;
-  if (typeof rawKey !== 'string' || rawKey.length === 0) {
-    return { kind: 'err', message: 'Field `signingKeyId` must be a non-empty string' };
-  }
+  const signingKeyId = parseSigningKeyId(body);
+  if (signingKeyId.kind === 'err') return signingKeyId;
   const filterRaw = body.filter;
   if (
     filterRaw !== undefined &&
@@ -372,10 +336,7 @@ function parseExportBody(body: Record<string, unknown>): ParseResult<ValidatedEx
   if (parsedFilter.kind === 'err') return parsedFilter;
   return {
     kind: 'ok',
-    value: {
-      signingKeyId: rawKey as SigningKeyId,
-      filter: parsedFilter.value ?? {},
-    },
+    value: { signingKeyId: signingKeyId.value, filter: parsedFilter.value ?? {} },
   };
 }
 

package/src/routes/conversations.ts

@@ -10,13 +10,16 @@ import type {
   ConversationMessage,
   ConversationPageCursor,
 } from '@kindgi/agents';
+import { type ResourceRef, ref } from '@kindgi/authz';
 import type { ProjectBinding } from '@kindgi/platform';
 import type { RunBinding } from '@kindgi/runtime';
 import type { AgentId, ProjectId, Semver, TenantId } from '@kindgi/types';
 
 import { statusFor, toWireError } from '../errors.js';
+import type { Authorizer } from '../middleware/authorize.js';
 import type { AppEnv } from '../types.js';
-import { clampLimit, decodeCursor, encodeCursor } from './pagination.js';
+import { deniedBy } from './denied.js';
+import { clampLimit, decodeCursor, encodeCursor, isCursorTime } from './pagination.js';
 import { parseListScope } from './scope-params.js';
 import { refuseMalformedUuidParam } from './uuid-param.js';
 
@@ -46,6 +49,12 @@ export function conversationsRouter(
    * tenant's projects, and an omitted one is the tenant's Default project.
    */
   projectBinding?: ProjectBinding,
+  /**
+   * With one (T243 A): reading a conversation or its messages needs `read`
+   * on its project (its agent, for one from before projects); opening or
+   * closing one needs `execute` on its agent, as starting a run does.
+   */
+  authorizer?: Authorizer,
 ): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
 
@@ -101,7 +110,7 @@ export function conversationsRouter(
     const rawCursor = c.req.query('cursor');
     if (rawCursor !== undefined && rawCursor.length > 0) {
       const decoded = decodeCursor(rawCursor);
-      if (decoded === null) {
+      if (decoded === null || !isCursorTime(decoded.createdAt)) {
         c.status(statusFor('bad-input') as never);
         return c.json(
           toWireError({ code: 'bad-input', message: '`cursor` is malformed' }, requestId),
@@ -123,17 +132,25 @@ export function conversationsRouter(
       c.status(statusFor(listResult.error.code) as never);
       return c.json(toWireError(listResult.error as never, requestId));
     }
-    const { data, hasMore } = listResult.value;
+    const { data, hasMore, next } = listResult.value;
     const last = data[data.length - 1];
+    // The binding's exact position when it gives one (`openedAt` to the
+    // microsecond); else the last row's, as a binding before it answers.
+    const position =
+      next ?? (last !== undefined ? { openedAt: last.openedAt, id: last.id } : undefined);
     const nextCursor =
-      hasMore && last !== undefined
+      hasMore && position !== undefined
         ? encodeCursor({
-            createdAt: last.openedAt as unknown as string,
-            id: last.id as unknown as string,
+            createdAt: position.openedAt as unknown as string,
+            id: position.id as unknown as string,
           })
         : undefined;
+    const visible =
+      authorizer === undefined
+        ? data
+        : await authorizer.filterByCan(c, 'read', data, conversationRef);
     return c.json({
-      data: data.map(serializeConversation),
+      data: visible.map(serializeConversation),
       hasMore,
       ...(nextCursor !== undefined && { nextCursor }),
     });
@@ -150,6 +167,8 @@ export function conversationsRouter(
       c.status(statusFor(got.error.code) as never);
       return c.json(toWireError(got.error as never, requestId));
     }
+    const refused = await deniedBy(authorizer, c, 'read', conversationRef(got.value));
+    if (refused !== undefined) return refused;
     return c.json(serializeConversation(got.value));
   });
 
@@ -192,6 +211,13 @@ export function conversationsRouter(
     // Omitted: the tenant's Default project, as for a run. No Default (or
     // no project binding): no project, never a refusal.
     const projectId = supplied ?? (await projectBinding?.getDefault(tenantId))?.id;
+    const refused = await deniedBy(
+      authorizer,
+      c,
+      'execute',
+      ref('agent', parsed.value.agentId as unknown as string),
+    );
+    if (refused !== undefined) return refused;
 
     const opened = await conversationBinding.openConversation({
       tenantId,
@@ -224,6 +250,13 @@ export function conversationsRouter(
       c.status(statusFor(existing.error.code) as never);
       return c.json(toWireError(existing.error as never, requestId));
     }
+    const refused = await deniedBy(
+      authorizer,
+      c,
+      'execute',
+      ref('agent', existing.value.agentId as unknown as string),
+    );
+    if (refused !== undefined) return refused;
     // Close is idempotent — closing an already-closed conversation
     // returns 200 with the current row, no error and no timestamp bump.
     if (existing.value.closedAt !== undefined) {
@@ -241,6 +274,44 @@ export function conversationsRouter(
     return c.json(serializeConversation(closed.value));
   });
 
+  // ---------- POST /:conversationId/unregister ----------
+  // A tombstone: from now on no read, list or recall returns the
+  // conversation, and no message can be added; the retention sweep
+  // removes it after the tenant's grace. Unregistered already, or never: 404.
+  // It needs `write` on the conversation's project (its agent, for one from
+  // before projects): an editor or above. Reading it isn't enough, nor is
+  // `execute`, which opening and closing one take.
+  r.post('/:conversationId/unregister', refuseMalformedConversationId, async (c) => {
+    const requestId = c.get('requestId');
+    const tenantId = c.get('tenantId') as TenantId;
+    const conversationId = c.req.param('conversationId') as ConversationId;
+    if (conversationBinding.unregisterConversation === undefined) {
+      c.status(statusFor('conversation-unregister-unsupported') as never);
+      return c.json(
+        toWireError(
+          {
+            code: 'conversation-unregister-unsupported',
+            message: "This runtime can't unregister conversations.",
+          },
+          requestId,
+        ),
+      );
+    }
+    const existing = await conversationBinding.getConversation(tenantId, conversationId);
+    if (existing.kind === 'err') {
+      c.status(statusFor(existing.error.code) as never);
+      return c.json(toWireError(existing.error as never, requestId));
+    }
+    const refused = await deniedBy(authorizer, c, 'write', conversationRef(existing.value));
+    if (refused !== undefined) return refused;
+    const unregistered = await conversationBinding.unregisterConversation(tenantId, conversationId);
+    if (unregistered.kind === 'err') {
+      c.status(statusFor(unregistered.error.code) as never);
+      return c.json(toWireError(unregistered.error as never, requestId));
+    }
+    return c.json(serializeConversation(unregistered.value));
+  });
+
   // ---------- GET /:conversationId/messages (cursor-paginated, sequence asc) ----------
   r.get('/:conversationId/messages', refuseMalformedConversationId, async (c) => {
     const requestId = c.get('requestId');
@@ -263,6 +334,15 @@ export function conversationsRouter(
       sinceSequence = decoded + 1;
     }
 
+    if (authorizer !== undefined) {
+      const got = await conversationBinding.getConversation(tenantId, conversationId);
+      if (got.kind === 'err') {
+        c.status(statusFor(got.error.code) as never);
+        return c.json(toWireError(got.error as never, requestId));
+      }
+      const refused = await deniedBy(authorizer, c, 'read', conversationRef(got.value));
+      if (refused !== undefined) return refused;
+    }
     const result = await conversationBinding.readMessages({
       tenantId,
       conversationId,
@@ -289,6 +369,17 @@ export function conversationsRouter(
   return r;
 }
 
+/**
+ * What a conversation is checked on: its project, or its agent for one
+ * opened before conversations recorded a project. (A `conversation`
+ * object has no parent tuple, so a check on it would refuse everyone.)
+ */
+function conversationRef(conv: Conversation): ResourceRef {
+  return conv.projectId !== undefined
+    ? ref('project', conv.projectId as unknown as string)
+    : ref('agent', conv.agentId as unknown as string);
+}
+
 // ============ serializers ============
 
 function serializeConversation(c: Conversation): Record<string, unknown> {
@@ -304,6 +395,9 @@ function serializeConversation(c: Conversation): Record<string, unknown> {
     status: (c.closedAt === undefined ? 'open' : 'closed') as 'open' | 'closed',
     openedAt: c.openedAt as unknown as string,
     ...(c.closedAt !== undefined && { closedAt: c.closedAt as unknown as string }),
+    ...(c.unregisteredAt !== undefined && {
+      unregisteredAt: c.unregisteredAt as unknown as string,
+    }),
     turnCount: c.turnCount,
     ...(c.lastMessageAt !== undefined && { lastMessageAt: c.lastMessageAt as unknown as string }),
     ...(c.metadata !== undefined && { metadata: c.metadata }),

package/src/routes/cost.ts

@@ -5,6 +5,7 @@ import { Hono } from 'hono';
 
 import type { Cursor, TenantId, Timestamp } from '@kindgi/types';
 
+import { type ResourceRef, ref } from '@kindgi/authz';
 import {
   COST_AGGREGATE_DEFAULT_LIMIT,
   COST_AGGREGATE_MAX_LIMIT,
@@ -16,10 +17,13 @@ import {
   type CostRecordFilter,
   type CostTokenTotals,
 } from '../cost-binding.js';
+
 import { statusFor, toWireError } from '../errors.js';
+import type { Authorizer } from '../middleware/authorize.js';
 import type { AppEnv } from '../types.js';
+import { deniedBy } from './denied.js';
 import { clampLimit } from './pagination.js';
-import { parseScopeParams } from './scope-params.js';
+import { parseScopeParams, scopeResourceRef } from './scope-params.js';
 
 /**
  * Cost readback routes — part of the admin control plane. Three
@@ -38,8 +42,19 @@ import { parseScopeParams } from './scope-params.js';
  *
  * Budgets are not part of this surface.
  */
-export function costRouter(binding: CostBinding): Hono<AppEnv> {
+export function costRouter(
+  binding: CostBinding,
+  /**
+   * With one (T243 A): a record needs `read` on its project (the tenant,
+   * for one with no project); an aggregate, on the scope it's asked for.
+   */
+  authorizer?: Authorizer,
+): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
+  const recordRef = (tenantId: TenantId, rec: { readonly projectId?: unknown }): ResourceRef =>
+    rec.projectId !== undefined && rec.projectId !== null
+      ? ref('project', rec.projectId as string)
+      : ref('tenant', tenantId as unknown as string);
 
   const DEFAULT_AGGREGATE_WINDOW_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
 
@@ -81,8 +96,12 @@ export function costRouter(binding: CostBinding): Hono<AppEnv> {
       ...(scopeParsed.inherit !== undefined && { inherit: scopeParsed.inherit }),
       ...(include.rawUsage && { includeRawUsage: true }),
     });
+    const visible =
+      authorizer === undefined
+        ? page.data
+        : await authorizer.filterByCan(c, 'read', page.data, (rec) => recordRef(tenantId, rec));
     return c.json({
-      data: page.data.map(serializeRecord),
+      data: visible.map(serializeRecord),
       hasMore: page.nextCursor !== undefined,
       ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
     });
@@ -117,6 +136,8 @@ export function costRouter(binding: CostBinding): Hono<AppEnv> {
         ),
       );
     }
+    const refused = await deniedBy(authorizer, c, 'read', recordRef(tenantId, record));
+    if (refused !== undefined) return refused;
     return c.json(serializeRecord(record));
   });
 
@@ -249,6 +270,14 @@ export function costRouter(binding: CostBinding): Hono<AppEnv> {
       );
     }
 
+    const refused = await deniedBy(
+      authorizer,
+      c,
+      'read',
+      scopeResourceRef(scopeParsed.scope, tenantId),
+    );
+    if (refused !== undefined) return refused;
+
     const result = await binding.aggregate({
       tenantId,
       groupBy,

package/src/routes/denied.ts

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Context } from 'hono';
+
+import type { Action, ResourceRef } from '@kindgi/authz';
+
+import type { Authorizer } from '../middleware/authorize.js';
+import type { AppEnv } from '../types.js';
+
+/**
+ * An in-handler check, for a resource known only once the request is
+ * read: nothing when the caller may take `action` on `resource` (or there
+ * is no authorizer), else the authorizer's own 403, to return as is.
+ */
+export async function deniedBy(
+  authorizer: Authorizer | undefined,
+  c: Context<AppEnv>,
+  action: Action,
+  resource: ResourceRef,
+): Promise<Response | undefined> {
+  if (authorizer === undefined) return undefined;
+  let allowed = false;
+  const answer = await authorizer.authorize(action, () => resource)(c, async () => {
+    allowed = true;
+  });
+  return allowed ? undefined : (answer as Response);
+}