Disclaimer best practicies Oracle for Security

specs/Disclaimer Auth and Security_PT.md

@@ -0,0 +1,40 @@
+### Recomendações de segurança, autenticação e autorização
+
+Os componentes e templates deste framework podem ser adaptados a diferentes arquiteturas e requisitos de segurança. Para ambientes produtivos, recomenda-se que a solução seja avaliada de acordo com as políticas corporativas, os requisitos regulatórios aplicáveis e as melhores práticas de segurança da Oracle Cloud Infrastructure.
+
+Como orientação geral, recomenda-se considerar autenticação e autorização em todas as interfaces acessíveis por usuários, canais, sistemas externos ou outros serviços. Na OCI, uma opção é utilizar o OCI API Gateway, ou uma camada equivalente, em conjunto com OAuth 2.0/OpenID Connect, validação de tokens e políticas de autorização por rota, scope, papel e tenant.
+
+Métodos como HTTP Basic e API keys podem ser adequados para determinados cenários de integração, especialmente ambientes controlados ou sistemas legados. Nesses casos, recomenda-se utilizá-los sobre TLS, manter as credenciais em um serviço seguro de gerenciamento de segredos e adotar mecanismos de expiração e rotação.
+
+A avaliação de segurança deve considerar, conforme os componentes utilizados pela solução:
+
+- Agent Gateway, Channel Gateway e MCP Gateway;
+- backends de agentes e comunicação entre gateways e backends;
+- aplicações frontend e APIs consumidas pelo navegador;
+- callbacks e webhooks provenientes de canais externos;
+- conexões SSE, WebSocket ou outros mecanismos de streaming;
+- histórico, memória, checkpoints e dados de sessão;
+- endpoints administrativos, de debug, documentação, health e métricas;
+- integrações com LLMs, bancos de dados, caches, mensageria e plataformas de observabilidade.
+
+Recomenda-se tratar identificadores recebidos em payloads ou headers — como `tenant_id`, `agent_id`, `user_id`, `customer_id` e `session_id` — como informações de contexto, e não como evidência suficiente da identidade do solicitante. Quando aplicável, esses identificadores podem ser derivados de claims validadas ou relacionados à identidade autenticada antes da execução da operação.
+
+Além da autenticação, recomenda-se avaliar a autorização sobre cada recurso acessado. Essa verificação pode considerar se o usuário ou serviço autenticado possui permissão para acessar o tenant, agente, sessão, histórico, checkpoint, backend ou ferramenta MCP solicitado.
+
+Para comunicação entre serviços, podem ser consideradas identidades específicas por workload e mecanismos como OAuth 2.0 client credentials, OCI IAM, OKE Workload Identity, Instance Principals, Resource Principals ou mTLS. A escolha deve considerar a plataforma de execução e o modelo de confiança definido para a solução.
+
+Para callbacks e webhooks, recomenda-se avaliar os mecanismos disponibilizados pelo provedor do canal, como assinatura digital ou HMAC, JWT, timestamp, identificador de mensagem, proteção contra replay e idempotência.
+
+Em relação aos endpoints operacionais, é recomendável avaliar separadamente:
+
+- endpoints de liveness, com resposta mínima sobre o estado do processo;
+- endpoints de readiness, preferencialmente acessíveis apenas pela infraestrutura;
+- endpoints de métricas, destinados aos coletores autorizados;
+- endpoints de debug e teste, normalmente restritos a ambientes não produtivos;
+- documentação OpenAPI, que pode ser desabilitada ou protegida em produção.
+
+Também é recomendável utilizar TLS nas comunicações, restringir a exposição de serviços por meio de redes privadas, sub-redes, NSGs e allowlists, e considerar rate limiting, auditoria, rastreabilidade e monitoramento de acessos negados.
+
+Segredos, tokens, senhas, certificados e chaves podem ser mantidos no OCI Secret Management ou em solução corporativa equivalente, evitando seu armazenamento em código-fonte ou arquivos de configuração versionados. Recomenda-se estabelecer políticas de acesso de menor privilégio, expiração e rotação compatíveis com a criticidade de cada credencial.
+
+Estas recomendações representam uma referência inicial de melhores práticas. A definição final dos mecanismos de autenticação, autorização, proteção de rede e gestão de segredos permanece sob responsabilidade da equipe responsável pela arquitetura e pelo deployment, considerando o contexto, os riscos e os requisitos específicos de cada implementação.

specs/Disclaimer_Auth_and_Security_EN.md

@@ -0,0 +1,40 @@
+### Security, Authentication, and Authorization Recommendations
+
+The components and templates in this framework can be adapted to different architectures and security requirements. For production environments, it is recommended that the solution be assessed in accordance with corporate policies, applicable regulatory requirements, and Oracle Cloud Infrastructure security best practices.
+
+As general guidance, authentication and authorization should be considered for all interfaces accessible by users, channels, external systems, or other services. In OCI, one option is to use OCI API Gateway, or an equivalent layer, together with OAuth 2.0/OpenID Connect, token validation, and authorization policies based on route, scope, role, and tenant.
+
+Methods such as HTTP Basic authentication and API keys may be suitable for certain integration scenarios, particularly in controlled environments or with legacy systems. In such cases, it is recommended that they be used over TLS, that credentials be stored in a secure secrets management service, and that expiration and rotation mechanisms be adopted.
+
+The security assessment should consider, according to the components used by the solution:
+
+- Agent Gateway, Channel Gateway, and MCP Gateway;
+- agent backends and communication between gateways and backends;
+- frontend applications and APIs consumed by the browser;
+- callbacks and webhooks originating from external channels;
+- SSE, WebSocket, or other streaming connections;
+- history, memory, checkpoints, and session data;
+- administrative, debug, documentation, health, and metrics endpoints;
+- integrations with LLMs, databases, caches, messaging systems, and observability platforms.
+
+Identifiers received in payloads or headers—such as `tenant_id`, `agent_id`, `user_id`, `customer_id`, and `session_id`—should be treated as contextual information rather than sufficient proof of the requester's identity. When applicable, these identifiers may be derived from validated claims or associated with the authenticated identity before the operation is executed.
+
+In addition to authentication, authorization should be evaluated for each accessed resource. This verification may consider whether the authenticated user or service has permission to access the requested tenant, agent, session, history, checkpoint, backend, or MCP tool.
+
+For service-to-service communication, dedicated workload identities and mechanisms such as OAuth 2.0 client credentials, OCI IAM, OKE Workload Identity, Instance Principals, Resource Principals, or mTLS may be considered. The choice should take into account the execution platform and the trust model defined for the solution.
+
+For callbacks and webhooks, the mechanisms provided by the channel provider should be evaluated, such as digital signatures or HMAC, JWT, timestamps, message identifiers, replay protection, and idempotency.
+
+Operational endpoints should also be evaluated separately:
+
+- liveness endpoints, with a minimal response regarding the process status;
+- readiness endpoints, preferably accessible only by the infrastructure;
+- metrics endpoints, intended for authorized collectors;
+- debug and test endpoints, typically restricted to non-production environments;
+- OpenAPI documentation, which may be disabled or protected in production.
+
+It is also recommended to use TLS for communications, restrict service exposure through private networks, subnets, NSGs, and allowlists, and consider rate limiting, auditing, traceability, and monitoring of denied access attempts.
+
+Secrets, tokens, passwords, certificates, and keys may be stored in OCI Secret Management or an equivalent corporate solution, avoiding storage in source code or version-controlled configuration files. Least-privilege access policies, expiration, and rotation practices appropriate to the criticality of each credential should be established.
+
+These recommendations provide an initial reference for best practices. The final definition of authentication, authorization, network protection, and secrets management mechanisms remains the responsibility of the team accountable for the architecture and deployment, taking into consideration the context, risks, and specific requirements of each implementation.