chore: organize documentation structure for monorepo

- Create /docs structure (microdao, daarion, agents)
- Organize 61 cursor technical docs
- Add README files for each category
- Copy key documents to public categories
- Add GitHub setup instructions and scripts

docs/cursor/26_security_audit.md

@@ -0,0 +1,452 @@
+# 26 — Security Audit Checklist (MicroDAO)
+
+*Безпека інфраструктури, сервісів, вебклієнта, агентів, Embassy, access keys, токенів та даних*
+
+Це документ для регулярного безпекового аудитування платформи **DAARION.city / microDAO / Embassy / Agent Mesh / Wallet / RWA**.
+
+Він структурований так, щоб аудитори, інженери, DevOps та SecOps могли пройтися checklist-пунктами і чітко виявити проблеми в:
+
+- Auth / Identity;
+- Access Keys & Capability System;
+- RBAC/Entitlements;
+- Е2Е шифруванні повідомлень;
+- Низькорівневій безпеці API, web, deployment;
+- Embassy / Webhooks / Oracle-потоках;
+- Wallet / Chain / Payouts;
+- RWA flows;
+- DB Security;
+- Secrets Management;
+- Logging/Audit/Compliance.
+
+Документ повністю відповідає архітектурі, яку ми вже побудували.
+
+---
+
+## 1. Identity & Authentication
+
+### 1.1 Users
+
+- [ ] Email-based auth, OTP / Magic Link використовують одноразові токени.
+- [ ] Термін дії OTP ≤ 10 хв.
+- [ ] Повторне використання OTP заблоковано.
+- [ ] Blocklist для підозрілих IP/UA-фінгерпринтів.
+- [ ] MFA можлива (на roadmap).
+- [ ] Session cookies:
+  - [ ] `HttpOnly`
+  - [ ] `Secure`
+  - [ ] `SameSite=Strict` для prod
+- [ ] Session TTL визначений (24–72 год), auto-refresh без надмірного продовження.
+
+### 1.2 Agents
+
+- [ ] Приватні агенти НЕ використовують user-сесію.
+- [ ] Кожен агент має свій **Agent Access Key** (`ak_*` з `subject_kind='agent'`).
+- [ ] Немає можливості «перевтілюватися» в користувача.
+- [ ] Rate limit для agent keys встановлений.
+
+### 1.3 Integrations / Webhooks
+
+- [ ] Інтеграції без JWT. Тільки API Key + HMAC.
+- [ ] Embassy Webhooks:
+  - [ ] Secret зберігається в KMS.
+  - [ ] Підпис запиту перевіряється (`X-Signature`).
+  - [ ] Replay protection: timestamp + max time drift < 5 хв.
+
+---
+
+## 2. Authorization Layer (RBAC + Entitlements + Capabilities)
+
+### 2.1 RBAC
+
+- [ ] Ролі існують: `Owner`, `Guardian`, `Member`, `Visitor`.
+- [ ] Роль користувача залежить від `team_members.role`.
+- [ ] Немає прямого доступу до таблиць без RBAC-check.
+
+### 2.2 Entitlements
+
+- [ ] `plan.Freemium`, `plan.Casual`, `plan.Premium`, `plan.Platformium`.
+- [ ] Плани визначають квоти на:
+  - agent runs;
+  - router.invoke;
+  - message sends;
+  - wallet.payout.claim;
+- [ ] Стейк RINGK коректно впливає на квоти (множники).
+
+### 2.3 Capability System
+
+- [ ] Access Key має capabilities через:
+  - [ ] bundle.role.*
+  - [ ] bundle.plan.*
+  - [ ] bundle.agent.*
+  - [ ] власні capabilities (`access_key_caps`)
+- [ ] Формула:
+
+  ```text
+  allow = RBAC ∧ Entitlement ∧ Capability ∧ ACL ∧ Mode
+  ```
+
+- [ ] PDP працює централізовано.
+- [ ] PEP на всіх API endpoints.
+
+---
+
+## 3. Access Keys (User, Agent, Integration, Embassy)
+
+### 3.1 Зберігання
+
+- [ ] Secrets у KMS (не в базі).
+- [ ] У таблиці `access_keys` зберігаються тільки metadata.
+- [ ] Секрет видається один раз → не зберігається у plaintext.
+
+### 3.2 Політики
+
+- [ ] TTL для ключів (default 30–90 днів).
+- [ ] Mandatory rotation.
+- [ ] Revoke → негайна інвалідація.
+- [ ] `status` ∈ (`active`, `revoked`, `expired`).
+
+### 3.3 Rate limiting
+
+- [ ] Okta-like limit per key.
+- [ ] DDOS запобігання (global rate limit + per-key).
+
+---
+
+## 4. Confidential Mode (E2EE-Like Messaging)
+
+### 4.1 На рівні каналів/команд
+
+- [ ] Якщо `teams.mode='confidential'`:
+  - [ ] сервер не бачить plaintext у `messages.body` (тільки ciphertext).
+  - [ ] агенти не отримують plaintext — тільки:
+    - embeddings;
+    - summary;
+    - обмежені метадані.
+
+### 4.2 Ключі шифрування
+
+- [ ] Зберігаються виключно на клієнті.
+- [ ] Rotate при:
+  - зміні складу команди;
+  - зміні owner/guardian;
+  - виході учасника.
+
+### 4.3 E2EE Threat Model
+
+- [ ] Сервер не може дешифрувати повідомлення.
+- [ ] Агенти працюють на «вивітрених» даних (privacy-preserving).
+
+---
+
+## 5. API Security
+
+### 5.1 Input validation
+
+- [ ] Валідація payload (Zod/JSON schema).
+- [ ] Неможливо запостити чужий team_id/channel_id/task_id.
+
+### 5.2 Rate limiting
+
+- [ ] per-IP
+- [ ] per-user
+- [ ] per-access-key
+- [ ] per-endpoint (наприклад `/agent/run` має сильний ліміт)
+
+### 5.3 Common
+
+- [ ] CORS: origin whitelist
+- [ ] TLS enforced
+- [ ] Referrer policy: `strict-origin`
+- [ ] Headers:
+  - [ ] `X-Frame-Options: DENY`
+  - [ ] `Content-Security-Policy` мінімум:
+
+    ```text
+    default-src 'self';
+    script-src 'self' 'unsafe-inline';
+    connect-src 'self' https:;
+    img-src 'self' data: https:;
+    frame-ancestors 'none';
+    ```
+
+- [ ] Вимкнуто directory listing у CDN.
+
+---
+
+## 6. Web Client Security
+
+### 6.1 Token handling
+
+- [ ] Немає зберігання секретів у localStorage.
+- [ ] Capability-token не містить чутливих даних.
+- [ ] Cookies: secure, httponly, samesite.
+
+### 6.2 UI-level attack surface
+
+- [ ] XSS захищено (React escaping).
+- [ ] Посилання user-generated content: `rel="noopener noreferrer"`.
+
+### 6.3 Cache
+
+- [ ] Disable caching of sensitive pages.
+
+---
+
+## 7. Database Security
+
+### 7.1 Структура
+
+- [ ] Всі таблиці пройдені аудитом (див. `27_database_schema_migrations.md`).
+- [ ] Поля з критичними даними не мають plaintext секретів.
+
+### 7.2 Обмеження
+
+- [ ] CHECK / ENUM на:
+  - roles
+  - viewer_types
+  - message types
+  - task statuses
+  - wallet statuses
+  - access key statuses
+  - embassy platforms
+- [ ] Foreign keys у всіх критичних зв'язках.
+
+### 7.3 Політика доступу
+
+- [ ] Web/API використовує RLS або server-side filters.
+- [ ] Відсутня можливість запитів напряму «в сусідню команду».
+
+### 7.4 Backup & Restore
+
+- [ ] PITR 7–30 днів для prod.
+- [ ] Snapshot перед кожним релізом.
+- [ ] Процедура restore протестована.
+
+---
+
+## 8. Secrets Management
+
+### 8.1 Джерело
+
+- [ ] Prod/Staging secrets в KMS або Vault.
+- [ ] Немає `.env` у repo.
+- [ ] Локальні `.env` окремо від production.
+
+### 8.2 Sensitive secrets
+
+- Embassy secrets
+- Wallet signer private key
+- JWT secret
+- Session secret
+- RWA oracle secrets
+
+### 8.3 Rotation
+
+- [ ] Rotation policy існує.
+- [ ] Auto-rotate для Embassy secrets мінімум раз на 30–60 днів.
+
+---
+
+## 9. Embassy Module & Webhooks Security
+
+### 9.1 Inbound Webhooks
+
+- [ ] Підпис перевіряється (`X-Signature`).
+- [ ] Timestamp у тілі підпису.
+- [ ] Maximum allowed skew < 5 хв.
+- [ ] Body hashing (HMAC_SHA256).
+
+### 9.2 Outbound Webhooks
+
+- [ ] Retry з експоненційною затримкою.
+- [ ] Dead-letter queue для NATS споживачів.
+
+### 9.3 Oracle Input
+
+- [ ] Oracle events проходять PDP capability-check:
+  - `embassy.energy.update`
+  - `embassy.rwa.claim`
+  - `embassy.intent.read`
+- [ ] Oracle payload має структуру з валідацією (не приймати довільний json).
+
+---
+
+## 10. Wallet & Chain Security
+
+### 10.1 Signer
+
+- [ ] Wallet private key у KMS.
+- [ ] Операції підпису — через офіційну KMS-операцію (не на сервері).
+- [ ] Multi-sig або 4-eyes approval для критичних транзакцій.
+
+### 10.2 Payouts
+
+- [ ] `payout.generated` приходить лише з wallet service.
+- [ ] claim → tx → підтвердження → оновлення БД.
+- [ ] Rate limit на claim.
+
+### 10.3 Chain RPC
+
+- [ ] Використовувати приватні RPC endpoint-и.
+- [ ] Логи RPC запитів не містять приватних ключів.
+
+---
+
+## 11. RWA Security
+
+### 11.1 Data-level
+
+- [ ] RWA inventory має типи:
+  - `energy`, `food`, `water`, `essence`, `generic`.
+- [ ] Кожен update — подія `rwa.inventory.updated`.
+
+### 11.2 Embassy-guarded actions
+
+- [ ] тільки Embassy Keys з capability:
+  - `rwa.inventory.update`
+  - `embassy.rwa.claim`
+  - `embassy.energy.update`
+
+---
+
+## 12. Logging & Audit Trail
+
+### 12.1 Audit Log
+
+- [ ] Всі критичні дії пишуть у `audit_log`:
+  - access key created/revoked,
+  - agent run invoked,
+  - payout claimed,
+  - governance actions,
+  - embassy updates.
+
+### 12.2 Log integrity
+
+- [ ] Логи доступні тільки admin/ops.
+- [ ] Немає plaintext секретів.
+
+### 12.3 SIEM інтеграція
+
+- [ ] Підтримується forwarding у ELK / Loki / Cloud Logging.
+
+---
+
+## 13. Monitoring & Alerting
+
+### 13.1 Метрики
+
+- API latency, error rate
+- DB connections, slow queries
+- NATS lag
+- Agent run failures
+- Embassy webhook failures
+- Wallet TX errors
+
+### 13.2 Алерти
+
+- [ ] high latency
+- [ ] high error rate (>2%)
+- [ ] failed db migration
+- [ ] stuck outbox events
+- [ ] agent-run failure rate > заданого порогу
+- [ ] "Embassy webhook signature mismatch"
+
+---
+
+## 14. Incident Response
+
+### 14.1 Playbooks
+
+- [ ] DB corruption
+- [ ] Chain stuck / RPC unreachable
+- [ ] Embassy compromised key
+- [ ] Access key leak
+- [ ] Agent runaway (infinite loop / high cost)
+- [ ] DDOS attack
+- [ ] RWA incorrect oracle input
+
+### 14.2 Communication
+
+- [ ] Responsible security officer визначено.
+- [ ] Питання ескалації прописані.
+
+---
+
+## 15. Compliance
+
+### 15.1 Privacy
+
+- [ ] PII зберігається encrypted-at-rest.
+- [ ] Резидентські дані обмежені на команди.
+- [ ] E2EE для confidential-каналів гарантує приватність.
+
+### 15.2 Data retention
+
+- [ ] Логи зберігаються до 30–90 днів.
+- [ ] Outbox events → 7 днів.
+
+### 15.3 Legal
+
+- [ ] Webhooks & Embassy: мінімізація PII.
+- [ ] Wallet: відповідність нормам локальних регуляцій.
+
+---
+
+## 16. Summary: Security Audit Status Table
+
+| Категорія     | Статус             | Проблеми | Пріоритет |
+| ------------- | ------------------ | -------- | --------- |
+| Identity/Auth | PASS / WARN / FAIL | …        | High      |
+| Access Keys   | PASS / WARN / FAIL | …        | High      |
+| RBAC          | PASS               | …        | Medium    |
+| Capabilities  | PASS               | …        | High      |
+| E2EE          | …                  | …        | High      |
+| Embassy       | …                  | …        | High      |
+| Wallet        | …                  | …        | Critical  |
+| RWA           | …                  | …        | High      |
+| DB            | …                  | …        | High      |
+| Secrets       | …                  | …        | Critical  |
+| Logs          | …                  | …        | Medium    |
+
+---
+
+## 17. Завдання для Cursor
+
+```text
+You are a senior security engineer. Implement security measures based on:
+- 26_security_audit.md
+- 24_access_keys_capabilities_system.md
+- 25_deployment_infrastructure.md
+- 12_agent_runtime_core.md
+
+Tasks:
+1) Implement rate limiting middleware for API endpoints.
+2) Add input validation (Zod schemas) for all API endpoints.
+3) Implement security headers middleware (CSP, X-Frame-Options, etc.).
+4) Add audit logging for critical actions (access keys, payouts, governance).
+5) Implement secrets rotation policy.
+6) Add security monitoring alerts.
+
+Output:
+- list of modified files
+- diff
+- summary
+```
+
+---
+
+## 18. Результат
+
+Після проходження цього чеклисту:
+
+- виявлені всі критичні вразливості безпеки;
+- впроваджені best practices для всіх компонентів системи;
+- готовність до production deployment з точки зору безпеки;
+- чітка політика incident response та compliance.
+
+---
+
+**Версія:** 1.0 (для MVP → RC → PROD)  
+**Останнє оновлення:** 2024-11-14
+
+