fix: Spec Agent Runtime

specs/en/SPEC-018-Security-and-Identity-Model.md

@@ -0,0 +1,152 @@
+# SPEC-018 — Security and Identity Model
+
+## Agent Platform OCI
+
+Version: 1.0.0
+
+
+---
+
+## Reading guide
+
+each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
+
+The document structure is:
+
+1. Concept.
+2. Problem addressed.
+3. When to use.
+4. When not to use.
+5. Architecture.
+6. Implementation.
+7. Examples.
+8. Common errors.
+9. Acceptance criteria.
+
+---
+
+
+# 1. Concept
+
+Security and Identity Model Defines como workloads autenticam, como Components autorizam actions, como segredos are protegidos and como Data sensíveis are tratados.
+
+# 2. Modelos of Authentication
+
+| Modo | Uso |
+| --- | --- |
+| config_file | Development local with ~/.oci/config. |
+| instance_principal | Execution em OCI Compute. |
+| workload_identity | Execution em OKE/Kubernetes. |
+| resource_principal | Recursos OCI gerenciados. |
+| api_key | Endpoints compatíveis with OpenAI when aplicável. |
+
+
+# 3. Workload Identity
+
+Flow:
+
+```mermaid
+flowchart LR
+    Pod[Pod Kubernetes] --> SA[ServiceAccount]
+    SA --> WI[Workload Identity]
+    WI --> IAM[OCI IAM Policy]
+    IAM --> Resource[OCI Resource]
+```
+
+# 4. Authorization
+
+Escopos:
+
+- Agent can chamar tool?
+- tenant can use provider?
+- canal can chamar agent_id?
+- User can executar ação?
+- tool mutável exige confirmação?
+
+# 5. Secrets
+
+Secrets No ficam no código.
+
+sources:
+
+- OCI Vault;
+- Kubernetes Secrets;
+- secret manager corporativo.
+
+Examples:
+
+```text
+LANGFUSE_SECRET_KEY
+OCI_GENAI_API_KEY
+ADB_PASSWORD
+MCP_BACKEND_TOKEN
+```
+
+# 6. Proteção of Data
+
+apply:
+
+- máscara of PII;
+- minimização of metadata;
+- sanitização of payload;
+- No logar secrets;
+- retenção controlada;
+- classificação of Data.
+
+# 7. Security em MCP
+
+MCP tools must ter:
+
+- Authorization por Agent;
+- allowlist;
+- timeout;
+- retry;
+- idempotência declarada;
+- confirmação for operações mutáveis.
+
+# 8. Security em canais
+
+Channel Gateway must:
+
+- validate assinatura;
+- validate origem;
+- deduplicar;
+- rate limit;
+- remover tokens;
+- normalizar payload;
+- rejeitar anexos inválidos.
+
+# 9. Auditoria
+
+Registrar:
+
+- User/canal;
+- agent_id;
+- tenant_id;
+- tool Call;
+- Model Used;
+- Decision of guardrail;
+- judge score;
+- Error;
+- trace_id.
+
+# 10. Common errors
+
+| Error | Impact | Correction |
+| --- | --- | --- |
+| Secret em .env versionado | Vazamento. | use Vault/Secrets. |
+| Tool without Authorization | Acesso indevido. | Allowed agents por tool. |
+| Payload bruto em logs | Exposição of Data. | Mascarar/minimizar. |
+| Instance main local | Timeout/Authentication invalid. | use config_file local. |
+
+
+# 11. Acceptance criteria
+
+- [ ] Modo of Authentication definido por ambiente.
+- [ ] Secrets external ao código.
+- [ ] MCP tools autorizadas por Agent.
+- [ ] Channel Gateway valida origem.
+- [ ] PII mascarada em logs.
+- [ ] Events auditáveis emitidos.
+- [ ] Workload Identity definido for OKE.
+- [ ] Security review executado before Production.