Skip to content

# Інструкції для оновлення .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