Files

Apple c552199eed 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

2025-11-15 04:08:35 -08:00

12 KiB

Raw Blame History

32 — Policy Service PDP Design (MicroDAO)

Архітектура Policy Decision Point (PDP), кешування, резолюція прав, квоти, інтеграція з API Gateway / Agents / Embassy

1. Purpose & Scope

PDP — це центральний компонент авторизації платформи DAARION.city / microDAO / Embassy / Agents / Wallet.

Він відповідає за:

розв'язання прав доступу на основі:
- RBAC,
- Capability Bundles,
- Entitlements (плани),
- Stake (RINGK),
- ACL,
- Mode (public/confidential),
- Quotas,
кешування конфігів доступів,
видачу дозволу або заборони на кожну дію,
роботу у high-load середовищах,
інтеграцію з API Gateway (PEP),
безпечну роботу з Agent Mesh, Embassy, Wallet, RWA.

Це ключовий документ для розробників API, агентного шару та бекенду.

2. PDP Formula

PDP приймає рішення за єдиною формулою:

allow =
  RBAC(role, action, resource)                   AND
  Entitlement(plan, stake_RINGK)                 AND
  Capability(key, action, resource)              AND
  ACL(resource, subject)                         AND
  Mode(resource_mode, subject_type)              AND
  Quota(subject, action)                         AND
  SecurityContext(subject, key_status)

Кожен блок працює незалежно.

3. PDP Inputs

PDP приймає запит такого вигляду:

{
  "subject": {
    "id": "u_123",
    "type": "user"             // user | agent | integration | embassy
  },
  "team_id": "t_456",
  "action": "task.create",
  "resource": {
    "id": "p_001",
    "team_id": "t_456",
    "mode": "public"           // або confidential
  },
  "key_id": "ak_789",
  "context": {
    "ip": "1.2.3.4",
    "ua": "Mozilla/5.0",
    "timestamp": 1700000000
  }
}

PDP повинен дати відповідь:

{ "allow": true, "reason": "ok" }

або:

{ "allow": false, "reason": "quota_exceeded" }

4. PDP Architecture Overview

                    ┌─────────────────────────┐
                    │     Policy Registry      │
                    │ (bundles, caps, plans)  │
                    └───────────┬────────────┘
                                │
                     ┌──────────┴───────────┐
                     │        PDP Core       │
                     │  (decision engine)    │
                     └──────────┬───────────┘
                                │
         ┌──────────────────────┼─────────────────────────┐
         │                      │                         │
     API Gateway (PEP)       Agent Mesh                Embassy

5. Internal Modules

5.1 Module: Role Resolver

Визначає роль користувача в команді:
- Owner
- Guardian
- Member
- Visitor

Запит у БД (кешований):

SELECT role, viewer_type FROM team_members WHERE ...

5.2 Module: Capability Resolver

Для key_id PDP збирає:

capabilities з access_key_caps
capabilities з bundle.role.*
capabilities з bundle.plan.*
capabilities з bundle.agent.*
capabilities з bundle.platform.* (для платформи)

Фінальний набір — унія всіх capability-джерел.

5.3 Module: Entitlements

План (Freemium, Casual, Premium, Platformium) → базові квоти:

LLM-токени
Agent runs
Router invokes
Embassy events
Storage
Wallet claims

Далі застосовується stake-множник:

effective_quota = base_quota × f(RINGK_staked)

5.4 Module: Quota Manager

Робить такі перевірки:

usage < effective_quota
якщо usage близько до межі → warning-флаг
якщо перевищено → deny

5.5 Module: ACL Resolver

ACL ресурсу (якщо встановлено):

список дозволених user_id/team_id,
список заборонених user_id/team_id.

5.6 Module: Confidential Mode Resolver

Важливо для каналів/чату:

if resource.mode == confidential:
    if subject.type == 'agent':
        deny reading plaintext

Agents не бачать plaintext у confidential-режимі.

5.7 Module: Key Status Checker

Перевіряє:

чи активний ключ,
чи не expired,
чи не revoked,
чи не over-rate-limit.

6. PDP Data Sources

PDP отримує дані з:

6.1 Capability Registry

Таблиці:

capabilities
bundles
bundle_caps
access_keys
access_key_caps

6.2 Role/Team Registry

team_members
teams

6.3 Usage Metrics (Per Team/User)

usage_agent_runs
usage_llm_tokens
usage_embassy_events
usage_storage
usage_router_invokes
usage_wallet_tx

(Можуть бути або materialized views, або окремі таблиці.)

6.4 Resource Metadata

channels
projects
tasks
rwa_inventory

7. PDP Cache Design

PDP має бути дуже швидким, тому більшість даних кешуються.

7.1 Static Cache (Long-term)

Завантажується при старті PDP:

capabilities list,
bundles,
bundle_caps.

Оновлюється:

при події "governance.policy.updated".

7.2 Dynamic Cache (Short-term)

Кешуються на 10–60 секунд:

role for (user_id, team_id)
caps for (key_id)
quotas for (team_id)
stake multipliers

7.3 Usage Cache

Usage counter зберігається:

у Redis або Memcache,
синхронізується з БД регулярно.

8. PDP Decision Algorithm (Pseudocode)

def pdp_decide(request):
    # 1) Key status
    if key_is_invalid(request.key_id):
        return deny("key_invalid")

    # 2) Role
    role = get_role(request.subject, request.team_id)
    if not role:
        return deny("no_role")

    # 3) Capability
    if not has_capability(request.key_id, request.action):
        return deny("capability_missing")

    # 4) RBAC matrix
    if not rbac_allows(role, request.action):
        return deny("rbac_denied")

    # 5) ACL
    if acl_blocks(request.resource, request.subject):
        return deny("acl_block")

    # 6) Confidential mode
    if is_confidential(request.resource) and is_agent(request.subject):
        if request.action in ["chat.message.read"]:
            return deny("confidential_mode_restriction")

    # 7) Quotas
    if exceeds_quota(request.subject, request.action):
        return deny("quota_exceeded")

    return allow()

9. PDP Integration with API Gateway (PEP)

API Gateway виконує:

Аутентифікацію
Витяг ключа (user session / access key)
Виклик PDP:

POST /pdp/decide
{
  subject: {...},
  team_id: "...",
  action: "...",
  resource: {...}
}

Отримує відповідь allow/deny
Продовжує або блокує запит
Збирає usage (LLM tokens, bytes, etc.)

10. PDP Integration with Agents

10.1 Agent run

Перед кожним agent.run.invoke:

PDP перевіряє capability → agent.run.invoke
PDP перевіряє квоти → agent_runs_per_day

10.2 Tools

Кожен tool має окремий action:

tool.browser
tool.code
tool.search

Plugins:

tool.<plugin_name>.invoke

10.3 Confidential-mode

Агенти отримують summary замість plaintext.

11. PDP Integration with Embassy

Embassy keys використовують capabilities:

embassy.rwa.claim
embassy.energy.update
embassy.intent.read

При події:

POST /embassy/rwa

API Gateway викликає PDP:

authorize(embassy_key, action=embassy.rwa.claim)

PDP перевіряє:

ключ дійсний,
capability збігається,
quota embassy events не перевищена,
ACL платформи.

12. PDP Integration with Wallet

Перед кожним:

wallet.balance.view
wallet.stake.ringk
wallet.payout.claim

PDP:

перевіряє capability для користувача,
перевіряє стейк (stake multipliers),
перевіряє квоту на wallet tx,
перевіряє ACL команди.

13. PDP Integration with Governance

Після прийняття governance policy:

governance.policy.updated

PDP:

скидає кеш bundles,
оновлює entitlement-конфіги,
застосовує stake multipliers,
ідентифікає можливі конфлікти.

14. PDP Logging & Audit

Кожне рішення PDP опціонально логують:

action,
subject,
team,
result,
latency,
quotas status.

Для chathistory-sensitive дій → minimal metadata.

15. PDP Performance Targets

p95 latency < 3 ms (кешований)
p99 latency < 8 ms
5k–20k rps у проді
1–3 GB RAM кешу достатньо

16. PDP Failure Modes & Recovery

16.1 Cache Corruption

→ Reload from Policy Registry → Governance Agent перевіряє consistency

16.2 DB Unavailable

→ PDP переходить у fail-safe режим (deny critical ops, allow read-only)

16.3 Overloaded PDP

→ Horizontal autoscaling → Rate limit API upstream

16.4 Governance Hotfix

→ Manual override policies → Emergency shutdown of dangerous capabilities

17. Security Considerations

PDP не довіряє API Gateway
PDP не довіряє клієнту
Кеш capabilities підписано
Governance updates підписані
Embassy events мають HMAC-підписи
Confidential mode ніколи не віддає plaintext агенту

18. Завдання для Cursor

You are a senior backend engineer. Implement Policy Decision Point (PDP) using:
- 32_policy_service_PDP_design.md
- 24_access_keys_capabilities_system.md
- 31_governance_policies_for_capabilities_and_quotas.md

Tasks:
1) Create PDP service with decision engine.
2) Implement internal modules (Role Resolver, Capability Resolver, Entitlements, Quota Manager, ACL Resolver, Confidential Mode Resolver, Key Status Checker).
3) Implement caching layer (static cache, dynamic cache, usage cache).
4) Create PDP decision algorithm.
5) Integrate with API Gateway (PEP).
6) Add PDP logging and audit.
7) Implement failure modes and recovery.

Output:
- list of modified files
- diff
- summary

19. Summary

PDP — основа безпеки та економічної стійкості міста:

централізує право доступу,
інтегрується з governance,
застосовує квоти,
керує usage,
забезпечує ізоляцію агентів,
гарантує E2EE-приватність,
контролює Embassy/RWA/Wallet потоки,
підтримує масштабованість і HA.

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

12 KiB Raw Blame History Unescape Escape