feat(agent-bff): serve the agent schema contract on GET /agent/v1/context

packages/agent-bff/src/cli-core.ts

@@ -16,6 +16,7 @@ import createApiKeyMiddleware from './api-key/api-key-middleware';
 import createResolveCache from './api-key/resolve-cache';
 import createAuthModeMiddleware from './auth/auth-mode-middleware';
 import { parseConfig } from './config/env-config';
+import createContextRoutesMiddleware from './context/context-routes-middleware';
 import createCorsMiddleware from './cors/cors-middleware';
 import createPerKeyOriginMiddleware from './cors/per-key-origin';
 import createDataRoutesMiddleware from './data/data-routes-middleware';
@@ -90,13 +91,18 @@ function resolveOAuthConfig(config: BFFConfig): ResolvedOAuthConfig | undefined
   return undefined;
 }
 
-async function buildOAuthMiddlewares(config: BFFConfig, logger: Logger): Promise<Middleware[]> {
+interface OAuthEdge {
+  middlewares: Middleware[];
+  environmentId?: number;
+}
+
+async function buildOAuthMiddlewares(config: BFFConfig, logger: Logger): Promise<OAuthEdge> {
   const oauthConfig = resolveOAuthConfig(config);
 
   if (!oauthConfig) {
     logger('Warn', 'OAuth routes disabled: required configuration is missing');
 
-    return [];
+    return { middlewares: [] };
   }
 
   const { forestServerUrl, forestEnvSecret, forestAppUrl, forestAuthSecret, tokenEncryptionKey } =
@@ -120,7 +126,7 @@ async function buildOAuthMiddlewares(config: BFFConfig, logger: Logger): Promise
     logger,
   });
 
-  return [oauthRoutes];
+  return { middlewares: [oauthRoutes], environmentId };
 }
 
 interface ResolvedApiKeyConfig {
@@ -265,7 +271,11 @@ function buildAgentRouteMiddlewares(
   ];
 }
 
-function buildAgentMiddlewares(config: BFFConfig, logger: Logger): Middleware[] {
+function buildAgentMiddlewares(
+  config: BFFConfig,
+  logger: Logger,
+  environmentId?: number,
+): Middleware[] {
   const { forestAuthSecret, defaultTimezone } = config;
 
   if (!forestAuthSecret) {
@@ -285,6 +295,7 @@ function buildAgentMiddlewares(config: BFFConfig, logger: Logger): Middleware[]
     apiKeyStep,
     createPerKeyOriginMiddleware(),
     createOpenApiRoutes({ version, enabled: config.openapiEnabled, source }),
+    ...(bundle ? [createContextRoutesMiddleware({ store: bundle.store, environmentId })] : []),
     createTimezoneMiddleware({ defaultTimezone }),
     ...buildAgentRouteMiddlewares(bundle, config, logger),
   ];
@@ -304,15 +315,15 @@ export default async function runCli(
     });
   }
 
-  const oauthMiddlewares = await buildOAuthMiddlewares(config, logger);
-  const agentMiddlewares = buildAgentMiddlewares(config, logger);
+  const oauth = await buildOAuthMiddlewares(config, logger);
+  const agentMiddlewares = buildAgentMiddlewares(config, logger, oauth.environmentId);
   const agentErrorMiddleware =
     agentMiddlewares.length > 0 ? [agentScoped(createErrorMiddleware({ logger }))] : [];
   const middlewares = [
     createCorsMiddleware({ allowedOrigins: config.allowedOrigins }),
     ...agentErrorMiddleware,
     bodyParser({ jsonLimit: BODY_LIMIT }),
-    ...oauthMiddlewares,
+    ...oauth.middlewares,
     ...agentMiddlewares,
   ];
   const server = new BFFHttpServer({

packages/agent-bff/src/context/build-context.ts

@@ -0,0 +1,153 @@
+import type { FieldType } from '../read-model/capabilities-cache';
+import type ReadModel from '../read-model/read-model';
+import type { RelationshipType } from '../read-model/read-model';
+import type {
+  ForestSchemaAction,
+  ForestSchemaCollection,
+  ForestSchemaField,
+} from '@forestadmin/forestadmin-client';
+
+export interface ContextActionField {
+  field: string;
+  type: FieldType;
+  isRequired?: boolean;
+  defaultValue?: unknown;
+  enums?: string[];
+}
+
+export interface ContextAction {
+  id: string;
+  name: string;
+  type: ForestSchemaAction['type'];
+  fields: ContextActionField[];
+}
+
+export interface ContextValidation {
+  type: string;
+  value?: unknown;
+}
+
+export interface ContextField {
+  field: string;
+  type: FieldType;
+  relationship?: RelationshipType;
+  reference?: string;
+  inverseOf?: string;
+  polymorphicTargets?: string[];
+  isPrimaryKey?: boolean;
+  isRequired?: boolean;
+  isReadOnly?: boolean;
+  enums?: string[];
+  validations?: ContextValidation[];
+}
+
+export interface ContextCollection {
+  name: string;
+  fields: ContextField[];
+  actions: ContextAction[];
+}
+
+export interface ContextMeta {
+  schemaRevision: number;
+  environmentId?: number;
+}
+
+export interface AgentContext {
+  collections: ContextCollection[];
+  meta: ContextMeta;
+}
+
+function toArray<T>(value: T[] | null | undefined): T[] {
+  return Array.isArray(value) ? value : [];
+}
+
+type FieldWithWireEnums = ForestSchemaField & { enums?: string[] };
+
+function toContextValidations(validations: unknown[] | null | undefined): ContextValidation[] {
+  return toArray(validations)
+    .filter(
+      (entry): entry is { type: string; value?: unknown } =>
+        typeof entry === 'object' &&
+        entry !== null &&
+        typeof (entry as { type?: unknown }).type === 'string',
+    )
+    .map(entry =>
+      'value' in entry ? { type: entry.type, value: entry.value } : { type: entry.type },
+    );
+}
+
+function toContextField(field: FieldWithWireEnums): ContextField {
+  const serialized: ContextField = { field: field.field, type: field.type };
+
+  if (field.relationship) serialized.relationship = field.relationship;
+  if (field.reference) serialized.reference = field.reference;
+  if (field.inverseOf) serialized.inverseOf = field.inverseOf;
+
+  const polymorphicTargets = toArray(field.polymorphicReferencedModels);
+  if (polymorphicTargets.length > 0) serialized.polymorphicTargets = [...polymorphicTargets];
+
+  if (field.isPrimaryKey) serialized.isPrimaryKey = true;
+  if (field.isRequired) serialized.isRequired = true;
+  if (field.isReadOnly) serialized.isReadOnly = true;
+
+  const enums = toArray(field.enums);
+  if (enums.length > 0) serialized.enums = [...enums];
+
+  const validations = toContextValidations(field.validations);
+  if (validations.length > 0) serialized.validations = validations;
+
+  return serialized;
+}
+
+function toContextActionField(field: ForestSchemaAction['fields'][number]): ContextActionField {
+  const serialized: ContextActionField = { field: field.field, type: field.type };
+
+  if (field.isRequired !== undefined) serialized.isRequired = field.isRequired;
+  if (field.defaultValue !== undefined) serialized.defaultValue = field.defaultValue;
+  if (Array.isArray(field.enums)) serialized.enums = [...field.enums];
+
+  return serialized;
+}
+
+function toContextAction(action: ForestSchemaAction): ContextAction {
+  return {
+    id: action.id,
+    name: action.name,
+    type: action.type,
+    fields: toArray(action.fields)
+      .filter(field => typeof field === 'object' && field !== null)
+      .map(toContextActionField),
+  };
+}
+
+function toContextCollection(
+  collection: ForestSchemaCollection,
+  readModel: ReadModel,
+): ContextCollection {
+  return {
+    name: collection.name,
+    fields: toArray(collection.fields).map(toContextField),
+    actions: toArray(collection.actions)
+      .filter(action => readModel.isActionAllowed(collection.name, action.name))
+      .map(toContextAction),
+  };
+}
+
+function toContextMeta({ schemaRevision, environmentId }: ContextMeta): ContextMeta {
+  const meta: ContextMeta = { schemaRevision };
+
+  if (environmentId !== undefined) meta.environmentId = environmentId;
+
+  return meta;
+}
+
+export default function buildContext(
+  collections: ForestSchemaCollection[],
+  readModel: ReadModel,
+  meta: ContextMeta,
+): AgentContext {
+  return {
+    collections: collections.map(collection => toContextCollection(collection, readModel)),
+    meta: toContextMeta(meta),
+  };
+}

packages/agent-bff/src/context/context-routes-middleware.ts

@@ -0,0 +1,30 @@
+import type ReadModelStore from '../read-model/read-model-store';
+import type { Middleware } from 'koa';
+
+import buildContext from './build-context';
+import { resolveSchemaSnapshot } from '../http/agent-route-helpers';
+
+const CONTEXT_ROUTE = '/agent/v1/context';
+
+export interface ContextRoutesMiddlewareOptions {
+  store: ReadModelStore;
+  environmentId?: number;
+}
+
+export default function createContextRoutesMiddleware({
+  store,
+  environmentId,
+}: ContextRoutesMiddlewareOptions): Middleware {
+  return async function contextRoutesMiddleware(ctx, next) {
+    if (ctx.path !== CONTEXT_ROUTE || ctx.method !== 'GET') {
+      await next();
+
+      return;
+    }
+
+    const { collections, readModel, revision } = await resolveSchemaSnapshot(store);
+
+    ctx.status = 200;
+    ctx.body = buildContext(collections, readModel, { schemaRevision: revision, environmentId });
+  };
+}

packages/agent-bff/src/http/agent-route-helpers.ts

@@ -1,6 +1,7 @@
 import type { Logger } from '../ports/logger-port';
 import type ReadModel from '../read-model/read-model';
 import type ReadModelStore from '../read-model/read-model-store';
+import type { SchemaSnapshot } from '../read-model/read-model-store';
 import type { Context } from 'koa';
 
 import { mapAgentError } from './agent-error-mapper';
@@ -16,15 +17,23 @@ export function decodeSegment(raw: string, label: string): string {
   }
 }
 
-export async function resolveReadModel(store: ReadModelStore): Promise<ReadModel> {
+async function mapSchemaFailure<T>(read: () => Promise<T>): Promise<T> {
   try {
-    return await store.getReadModel();
+    return await read();
   } catch (error) {
     if (error instanceof SchemaUnavailableError) throw schemaUnavailable();
     throw error;
   }
 }
 
+export async function resolveSchemaSnapshot(store: ReadModelStore): Promise<SchemaSnapshot> {
+  return mapSchemaFailure(() => store.getSchemaSnapshot());
+}
+
+export async function resolveReadModel(store: ReadModelStore): Promise<ReadModel> {
+  return mapSchemaFailure(() => store.getReadModel());
+}
+
 export function requireAgentToken(ctx: Context): string {
   const token = ctx.state.agentToken as string | undefined;
   if (!token) throw unauthorized('No agent credentials for this request');

packages/agent-bff/src/openapi/openapi-document.ts

@@ -6,6 +6,7 @@ import { OpenAPIRegistry, OpenApiGeneratorV31 } from '@asteasolutions/zod-to-ope
 import ComponentPool from './component-pool';
 import {
   ActionRequestSchema,
+  ContextResponseSchema,
   CountRequestSchema,
   CountResponseSchema,
   ErrorResponseSchema,
@@ -36,7 +37,7 @@ const ERROR_STATUSES: Record<string, string> = {
   415: 'The request declares a character set the server cannot decode. Other content types are NOT rejected: a form-urlencoded body is parsed and validated like JSON (its values arrive as strings, so typed fields such as page.limit fail with 400), while any other non-JSON content type is read as an absent body, silently dropping filters and pagination',
   422: 'A field is unknown, not filterable, or is a nested relation path',
   429: 'The agent rate-limited the request',
-  500: 'The agent payload could not be mapped to the BFF contract',
+  500: 'The agent payload could not be mapped to the BFF contract, or the BFF hit an unexpected error',
   501: 'The BFF is running without an agent configured, so the proxy is not implemented',
   502: 'The agent could not be reached',
   503: 'The agent schema is unavailable, the agent returned a 5xx, or the API key could not be resolved',
@@ -277,9 +278,8 @@ export function generateOpenApiDocument(version: string, unfolding?: Unfolding):
     type: 'http',
     scheme: 'bearer',
     description:
-      'Mode 1: the BFF session token issued after the OAuth login. It authenticates the caller ' +
-      'but the data and action routes reject it until the BFF mints an agent token from the ' +
-      'OAuth principal, so no operation lists it yet. Use the API key today.',
+      'Mode 1: the BFF session token issued after the OAuth login. Accepted on the context ' +
+      'contract; the data and action routes advertise the API key only.',
   });
   registry.registerComponent('securitySchemes', API_KEY_SCHEME, {
     type: 'apiKey',
@@ -288,6 +288,27 @@ export function generateOpenApiDocument(version: string, unfolding?: Unfolding):
     description: 'Mode 2: a BFF API key. Never send both this and an Authorization header.',
   });
 
+  registry.registerPath({
+    method: 'get',
+    path: `${ROUTE_PREFIX}/context`,
+    operationId: 'getContext',
+    summary: 'Read the exposed schema contract',
+    security: [{ [SESSION_SCHEME]: [] }, { [API_KEY_SCHEME]: [] }],
+    request: {},
+    responses: {
+      200: {
+        description: 'The exposed schema: collections, typed fields, relations and actions',
+        content: { 'application/json': { schema: ContextResponseSchema } },
+      },
+      400: errorRefs.byStatus['400'],
+      401: errorRefs.byStatus['401'],
+      403: errorRefs.byStatus['403'],
+      500: errorRefs.byStatus['500'],
+      501: errorRefs.byStatus['501'],
+      503: errorRefs.byStatus['503'],
+    },
+  });
+
   if (unfolding) {
     registerUnfoldedPaths(
       {