microdao-daarion/docs/cursor/DOCX_UPDATE_INSTRUCTIONS.md

Інструкції для оновлення .docx документів

Цей документ містить інструкції для механічного оновлення Word документів (.docx), які не можна редагувати автоматично.

---

1. microdao — Data Model & Event Catalog.docx

Крок 1: Додати новий розділ для таблиць access keys

Де: Після Heading 3 "3.9 Integrations / Webhooks / Audit"

Що додати:

Heading 3: 3.10 Access Keys & Capability Bundles

SQL схема:

create table access_keys (
  id text primary key,        -- ak_...
  subject_kind text not null, -- 'user' | 'agent' | 'integration' | 'embassy'
  subject_id text not null,   -- u_/ag_/...
  team_id text null,          -- t_..., якщо scoped до команди
  name text not null,
  status text not null check (status in ('active','revoked','expired')),
  created_at timestamptz not null default now(),
  expires_at timestamptz null,
  last_used_at timestamptz null
);

create table capabilities (
  id text primary key,        -- cap_...
  code text not null unique,  -- chat.message.send, wallet.stake.ringk, ...
  description text not null
);

create table access_key_caps (
  key_id text references access_keys(id) on delete cascade,
  cap_id text references capabilities(id) on delete cascade,
  primary key (key_id, cap_id)
);

create table bundles (
  id text primary key,        -- bundle_...
  name text not null unique,  -- role.Member / plan.Premium / agent.default
  created_at timestamptz not null default now()
);

create table bundle_caps (
  bundle_id text references bundles(id) on delete cascade,
  cap_id text references capabilities(id) on delete cascade,
  primary key (bundle_id, cap_id)
);

---

Крок 2: Додати події в Event Catalog

Де: У розділі 6.3 Події (JSON, скорочено)

1. У список topic додати:

• access_key.created
• access_key.revoked
• access_key.used

2. Нижче, де йдуть payload-схеми, додати JSON-схеми:

access_key.created:

// envelope.topic = "access_key.created"
"access_key_created": {
  "type": "object",
  "properties": {
    "key_id": { "type": "string" },
    "subject_kind": { "type": "string" },
    "subject_id": { "type": "string" },
    "team_id": { "type": ["string","null"] }
  },
  "required": ["key_id","subject_kind","subject_id"]
}

access_key.revoked:

// envelope.topic = "access_key.revoked"
"access_key_revoked": {
  "type": "object",
  "properties": {
    "key_id": { "type": "string" },
    "revoked_by": { "type": "string" },
    "revoked_at": { "type": "string", "format": "date-time" }
  },
  "required": ["key_id","revoked_by","revoked_at"]
}

access_key.used:

// envelope.topic = "access_key.used"
"access_key_used": {
  "type": "object",
  "properties": {
    "key_id": { "type": "string" },
    "subject_id": { "type": "string" },
    "action": { "type": "string" },
    "resource_kind": { "type": "string" },
    "ts": { "type": "string", "format": "date-time" }
  },
  "required": ["key_id","subject_id","action","resource_kind","ts"]
}

---

2. microdao — RBAC і Entitlements (MVP).docx

Крок 1: Оновити формулу доступу

Де: У розділі 2) Модель доступу

Знайти: Нинішню формулу allow = ...

Замінити на:

allow =
  RBAC(role, action, resource)
  ∧ Entitlement(plan, RINGK_staked)
  ∧ Capability(key, action, resource)
  ∧ ACL(resource)
  ∧ Mode(public|confidential)

Додати після формули:

Capability(key, …) береться з bundles bundle.role.* + bundle.plan.* (детальніше див. 24_access_keys_capabilities_system.md).

---

Крок 2: Додати мапінг Entitlements → bundles

Де: У розділі 6) Entitlements від RINGK (стейк), в кінці розділу

Додати:

Мапінг Entitlements → capability-bundles

• плани Freemium/Casual/Premium/Platformium відповідають bundle.plan.*;
• множники від стейку RINGK впливають на квоти для capabilities (chat.message.send, agent.run.invoke, router.invoke, wallet.payout.claim).

---

3. microdao — Security Architecture & Threat Model (MVP).docx

Крок 1: Додати підрозділ про Access Keys & Policy Service

Де: У розділі 5. Авторизація, після першого підрозділу (5.1/5.2)

Додати:

Heading 3: 5.x Access Keys & Policy Service (PDP/PEP)

Текст:

• Access keys перевіряються через PDP (Policy Decision Point / Policy Service)
• PEP (Policy Enforcement Point) живе в API Gateway та сервісах
• Використовується capability-token (JWT/opaque), який несе:
  • sub (user/agent/integration ID)
  • team_id
  • стиснений список caps (capabilities)

---

Крок 2: Додати підрозділ про зберігання access keys

Де: У розділі 8. Зберігання та доступ

Додати:

Heading 3: 8.x Зберігання access keys

Текст:

• Метадані зберігаються в таблиці access_keys (див. Data Model)
• Секрети (secret) зашифровані через KMS/HSM
• One-time reveal: після створення ключ не показується повторно
• Ротація: обов'язковий expires_at, періодична ротація ключів

---

Крок 3: Додати абзац про агентний шар

Де: У розділі 11. Агентний шар

Додати:

Всі приватні агенти працюють виключно через Agent Access Keys з мінімальними capabilities. Для mode='confidential' агенти не отримують plaintext-повідомлень, тільки summary/embeddings (узгоджено з E2EE моделлю).

---

Крок 4: Додати абзац про Wallet/Staking

Де: У розділі 12. Wallet/Staking/Токени

Додати:

Всі операції гаманця (wallet.balance.view, wallet.stake.ringk, wallet.payout.claim) завжди проходять через capability-check для ключа (user/agent). Перевірка виконується через PDP перед виконанням операції.

---

4. Перевірка

Після оновлення всіх .docx файлів перевір:

• ✅ У Data Model додано розділ 3.10 з таблицями access keys
• ✅ У Event Catalog додано 3 нові topics та їх JSON-схеми
• ✅ У RBAC оновлено формулу доступу та додано мапінг Entitlements → bundles
• ✅ У Security Architecture додано 4 нові розділи/абзаци про Access Keys

---

5. Посилання на Markdown документи

Всі деталі вже є в Markdown документах:

• 24_access_keys_capabilities_system.md — повна специфікація
• DAARION_city_platforms_catalog.md — мапінг платформ
• 28_flows_wallet_embassy_energy_union.md — sequence-діаграми

---

Версія: 1.0
Останнє оновлення: 2024-11-14