server/http/openapi/management-routes/agent-governance.ts

Rama main · réplica de lectura del repositorio original.

import {
  agentAuthorizedResourceServersResponseSchema,
  agentPermissionSchema,
  agentPermissionsResponseSchema,
  agentSchema,
  auditEventsResponseSchema,
  createAgentPermissionSchema,
  createAgentSchema,
  createdAgentPermissionsResponseSchema,
  dpopNonceErrorResponseSchema,
  listAgentAuditEventsQuerySchema,
  listAgentAuthorizedResourceServersQuerySchema,
  listAgentPermissionsQuerySchema,
  listAgentsQuerySchema,
  managementAgentInstallationsResponseSchema,
  managementAgentResponseSchema,
  managementAgentsResponseSchema,
  targetCredentialProofSchema,
  targetTokenSchema,
} from '@shared/api/agent-api'
import { managementErrorResponseSchema } from '@shared/api/management'
import { paginationQuerySchema } from '@shared/api/pagination'
import {
  idempotencyKeyHeader,
  idempotencyReplayResponseHeader,
  jsonBody,
  type ManagementRouteConfig,
  z,
} from './helpers'

export const agentGovernanceRoutes: ManagementRouteConfig[] = [
  {
    method: 'post',
    path: '/agents',
    operationId: 'createAgent',
    summary: 'Create a User-owned Agent and its initial installation',
    security: [{ oauth2: ['agents:write'] }],
    request: {
      headers: idempotencyKeyHeader,
      body: jsonBody(createAgentSchema),
    },
    response: agentSchema,
    responseHeaders: {
      Location: { description: 'Canonical URI of the created Agent.', schema: { type: 'string' } },
      ...idempotencyReplayResponseHeader,
    },
    status: 201,
    errors: {
      400: 'The Agent representation, public key, or Idempotency-Key is invalid.',
      403: 'The Application is not acting as a User or lacks agents:write authority.',
      409: 'The username is unavailable or the Idempotency-Key was reused with different Agent data.',
    },
  },
  {
    method: 'get',
    path: '/agents',
    operationId: 'listAgents',
    summary: 'List stable Agents',
    request: { query: listAgentsQuerySchema },
    response: managementAgentsResponseSchema,
    paginated: true,
  },
  {
    method: 'get',
    path: '/agents/{agentId}',
    operationId: 'getAgent',
    summary: 'Get a stable Agent',
    request: { params: z.object({ agentId: z.string() }) },
    response: managementAgentResponseSchema,
  },
  {
    method: 'get',
    path: '/agents/{agentId}/installations',
    operationId: 'listAgentInstallations',
    summary: 'List installations authorized for a stable Agent',
    request: { params: z.object({ agentId: z.string() }), query: paginationQuerySchema },
    response: managementAgentInstallationsResponseSchema,
    paginated: true,
    errors: { 400: 'The pagination query is invalid.', 404: 'The Agent was not found.' },
  },
  {
    method: 'get',
    path: '/agents/{agentId}/authorized-resource-servers',
    operationId: 'listAgentAuthorizedResourceServers',
    summary: 'List Resource Servers authorized for an Agent',
    security: [{ oauth2: ['permissions:read'] }, { sessionCookie: ['permissions:read'] }],
    request: { params: z.object({ agentId: z.string() }), query: listAgentAuthorizedResourceServersQuerySchema },
    response: agentAuthorizedResourceServersResponseSchema,
    paginated: true,
    errors: { 400: 'The collection query is invalid.', 404: 'The Agent was not found.' },
  },
  {
    method: 'post',
    path: '/agents/{agentId}/permissions',
    operationId: 'createAgentPermission',
    summary: 'Grant scopes using internally resolved controller resource Contexts',
    security: [{ oauth2: ['agents:write'] }, { sessionCookie: ['agents:write'] }],
    request: { params: z.object({ agentId: z.string() }), body: jsonBody(createAgentPermissionSchema) },
    response: createdAgentPermissionsResponseSchema,
    status: 201,
    errors: {
      400: 'The permission or external account is invalid.',
      403: 'The User lacks controller or resource authority.',
      404: 'The Agent or Resource Server was not found.',
    },
  },
  {
    method: 'get',
    path: '/agents/{agentId}/permissions',
    operationId: 'listAgentPermissions',
    summary: 'List an Agent’s Permissions',
    security: [{ oauth2: ['permissions:read'] }, { sessionCookie: ['permissions:read'] }],
    request: { params: z.object({ agentId: z.string() }), query: listAgentPermissionsQuerySchema },
    response: agentPermissionsResponseSchema,
    paginated: true,
    errors: { 400: 'The collection query is invalid.' },
  },
  {
    method: 'get',
    path: '/agents/{agentId}/permissions/{permissionId}',
    operationId: 'getAgentPermission',
    summary: 'Get an Agent Permission',
    security: [{ oauth2: ['permissions:read'] }, { sessionCookie: ['permissions:read'] }],
    request: { params: z.object({ agentId: z.string(), permissionId: z.string() }) },
    response: agentPermissionSchema,
    errors: { 404: 'The Agent Permission was not found.' },
  },
  {
    method: 'delete',
    path: '/agents/{agentId}/permissions/{permissionId}',
    operationId: 'deleteAgentPermission',
    summary: 'Revoke an Agent Permission',
    security: [{ oauth2: ['permissions:write'] }, { sessionCookie: ['permissions:write'] }],
    request: { params: z.object({ agentId: z.string(), permissionId: z.string() }) },
    noBody: true,
    errors: { 404: 'The Agent Permission was not found.' },
  },
  {
    method: 'post',
    path: '/agent/access-requests/{requestId}/credentials',
    operationId: 'createAgentAccessRequestCredential',
    summary: 'Create a temporary credential for an approved Agent access request',
    security: [{ oauth2: ['access-requests:write'] }],
    request: {
      params: z.object({ requestId: z.string() }),
      body: jsonBody(targetCredentialProofSchema),
    },
    response: targetTokenSchema,
    status: 201,
    responseHeaders: {
      'DPoP-Nonce': {
        description: 'Opaque authorization-server nonce to include in the next credential DPoP proof.',
        schema: { type: 'string' },
      },
    },
    errors: {
      400: {
        description: 'The request is invalid or the authorization server requires a nonce in a fresh DPoP proof.',
        schema: z.union([managementErrorResponseSchema, dpopNonceErrorResponseSchema]),
        headers: {
          'DPoP-Nonce': {
            description: 'Opaque authorization-server nonce required in the retry proof.',
            schema: { type: 'string' },
          },
        },
      },
    },
  },
  {
    method: 'get',
    path: '/agents/{agentId}/activation',
    operationId: 'getAgentActivation',
    summary: 'Get an Agent activation',
    request: { params: z.object({ agentId: z.string() }) },
    response: z.object({ agentId: z.string(), active: z.boolean() }),
  },
  {
    method: 'put',
    path: '/agents/{agentId}/activation',
    operationId: 'replaceAgentActivation',
    summary: 'Create or replace an Agent activation',
    request: { params: z.object({ agentId: z.string() }) },
    noBody: true,
  },
  {
    method: 'delete',
    path: '/agents/{agentId}/activation',
    operationId: 'deleteAgentActivation',
    summary: 'Delete an Agent activation',
    request: { params: z.object({ agentId: z.string() }) },
    noBody: true,
  },
  {
    method: 'delete',
    path: '/agents/{agentId}',
    operationId: 'deleteAgent',
    summary: 'Delete an Agent',
    request: { params: z.object({ agentId: z.string() }) },
    noBody: true,
  },
  {
    method: 'get',
    path: '/realm/audit-events',
    operationId: 'listAgentAuditEvents',
    summary: 'List Agent audit events',
    request: { query: listAgentAuditEventsQuerySchema },
    response: auditEventsResponseSchema,
    paginated: true,
  },
]