@rsconcept/rstool 1.7.1 → 2.0.0

package/examples/access-control/brief.json

@@ -0,0 +1,310 @@
+{
+  "version": 1,
+  "status": "confirmed",
+  "approach": "project",
+  "object": "Ролевое управление доступом",
+  "task": "Эксплицировать роли, иерархию и эффективные права для проектирования подсистемы доступа и проверок при назначении ролей",
+  "source": "requirements-v1.md, requirements-v2.md",
+  "restrictions": [
+    {
+      "id": "L1",
+      "excludes": "журнал изменений и сроки хранения (п. 6)",
+      "inexpressible": ["кто и когда выдал право", "права на прошлую дату"]
+    },
+    {
+      "id": "L2",
+      "excludes": "аутентификация (п. 7)",
+      "inexpressible": ["способ входа", "учётная запись SSO"]
+    },
+    {
+      "id": "L3",
+      "excludes": "ресурсы как объекты: право — неделимый элемент",
+      "inexpressible": ["права на конкретный документ"]
+    }
+  ],
+  "expressiveness": [
+    {
+      "id": "E1",
+      "concept": "младшие роли (замыкание иерархии)",
+      "ref": "п. 2",
+      "via": "замыкание S3 через R{}",
+      "constituent": "F1"
+    },
+    {
+      "id": "E2",
+      "concept": "прямые роли пользователя",
+      "ref": "п. 3",
+      "via": "постоянные назначения ∪ временные с действующим периодом",
+      "constituent": "F2"
+    },
+    {
+      "id": "E3",
+      "concept": "унаследованные роли пользователя",
+      "ref": "п. 5",
+      "via": "объединение младших ролей прямых ролей минус прямые",
+      "constituent": "F3"
+    },
+    {
+      "id": "E4",
+      "concept": "назначенные права",
+      "ref": "п. 3",
+      "via": "права прямых ролей",
+      "constituent": "F5"
+    },
+    {
+      "id": "E5",
+      "concept": "эффективные права",
+      "ref": "п. 3",
+      "via": "права прямых и унаследованных ролей",
+      "constituent": "F6"
+    },
+    {
+      "id": "E6",
+      "concept": "временные назначения",
+      "ref": "v2 п. 1",
+      "via": "родовая структура (пользователь, роль, с, по)",
+      "constituent": "S5"
+    }
+  ],
+  "distinctions": [
+    {
+      "id": "V1",
+      "between": ["E4", "E5"],
+      "text": "назначенные права ≠ эффективные",
+      "witness": "SC1"
+    },
+    {
+      "id": "V2",
+      "between": ["E2", "E3"],
+      "text": "прямая роль ≠ унаследованная",
+      "witness": "SC1"
+    }
+  ],
+  "invariants": [
+    {
+      "id": "I1",
+      "text": "В иерархии ролей нет циклов",
+      "ref": "п. 2",
+      "constituent": "A1",
+      "positive": "SC1",
+      "negative": "SC2"
+    },
+    {
+      "id": "I2",
+      "text": "Нет пользователя с обеими ролями несовместимой пары, в том числе через иерархию",
+      "ref": "п. 4",
+      "constituent": "A2",
+      "positive": "SC1",
+      "negative": "SC3"
+    },
+    {
+      "id": "I3",
+      "text": "Период временного назначения корректен",
+      "constituent": "A3",
+      "positive": "SC4",
+      "negative": "SC6"
+    }
+  ],
+  "decisions": [
+    {
+      "id": "DC1",
+      "topic": "иерархия ролей",
+      "alternatives": ["плоские роли без иерархии", "дерево: у роли одна старшая", "отношение S3 (старшая, младшая)"],
+      "choice": "отношение S3",
+      "rationale": "п. 2; роль может входить в несколько старших — дерево избыточно ограничивает"
+    },
+    {
+      "id": "DC2",
+      "topic": "права пользователя",
+      "alternatives": ["структура «права пользователя» S#", "вывод через роли"],
+      "choice": "вывод через роли (F5, F6)",
+      "rationale": "права пользователя не задаются отдельно — иначе разойдутся с ролями"
+    },
+    {
+      "id": "DC3",
+      "topic": "разделение обязанностей",
+      "alternatives": ["по прямым ролям", "по эффективным ролям"],
+      "choice": "по эффективным ролям (A2)",
+      "rationale": "п. 4: «в том числе через иерархию»"
+    },
+    {
+      "id": "DC4",
+      "topic": "симметричность несовместимости",
+      "choice": "без аксиомы",
+      "rationale": "A2 запрещает пару в любом порядке; достаточно записать пару один раз"
+    },
+    {
+      "id": "DC5",
+      "topic": "ацикличность иерархии",
+      "choice": "аксиома A1 через замыкание F1",
+      "rationale": "п. 2"
+    },
+    {
+      "id": "DC6",
+      "topic": "прямые роли с временными назначениями",
+      "supersedes": "DC2",
+      "choice": "F2 включает временные роли с действующим периодом",
+      "rationale": "v2 п. 1; без временных назначений совпадает с v1"
+    },
+    {
+      "id": "DC7",
+      "topic": "временное назначение",
+      "alternatives": ["период как компонента S1 (ломает v1)", "отдельная структура S5"],
+      "choice": "S5 (пользователь, роль, первый день, последний день) и текущий день S6",
+      "rationale": "S1 и сценарии v1 не меняются; E6 — родовая структура по DC7"
+    }
+  ],
+  "scenarios": [
+    {
+      "id": "SC1",
+      "title": "Администратор и наблюдатель-аудитор",
+      "values": {
+        "X1": ["ann", "bob"],
+        "X2": ["admin", "editor", "viewer", "auditor"],
+        "X3": ["read", "write", "delete", "audit"],
+        "S1": [
+          ["ann", "admin"],
+          ["bob", "viewer"],
+          ["bob", "auditor"]
+        ],
+        "S2": [
+          ["viewer", "read"],
+          ["editor", "write"],
+          ["admin", "delete"],
+          ["auditor", "audit"]
+        ],
+        "S3": [
+          ["admin", "editor"],
+          ["editor", "viewer"]
+        ],
+        "S4": [["admin", "auditor"]],
+        "S6": 1
+      },
+      "expect": [
+        {
+          "of": "F1",
+          "args": ["admin"],
+          "value": ["editor", "viewer"]
+        },
+        {
+          "of": "F3",
+          "args": ["ann"],
+          "value": ["editor", "viewer"]
+        },
+        {
+          "of": "F3",
+          "args": ["bob"],
+          "value": []
+        },
+        {
+          "of": "F5",
+          "args": ["ann"],
+          "value": ["delete"]
+        },
+        {
+          "of": "F6",
+          "args": ["ann"],
+          "value": ["read", "write", "delete"]
+        },
+        {
+          "of": "F6",
+          "args": ["bob"],
+          "value": ["read", "audit"]
+        }
+      ]
+    },
+    {
+      "id": "SC2",
+      "title": "Цикл в иерархии",
+      "base": "SC1",
+      "values": {
+        "S3": [
+          ["admin", "editor"],
+          ["editor", "viewer"],
+          ["viewer", "admin"]
+        ]
+      },
+      "expect": [
+        {
+          "of": "A1",
+          "holds": false
+        }
+      ]
+    },
+    {
+      "id": "SC3",
+      "title": "Несовместимость через наследование",
+      "base": "SC1",
+      "values": {
+        "S1": [
+          ["ann", "admin"],
+          ["ann", "auditor"]
+        ],
+        "S4": [["editor", "auditor"]]
+      },
+      "expect": [
+        {
+          "of": "A2",
+          "holds": false
+        },
+        {
+          "of": "F2",
+          "args": ["ann"],
+          "value": ["admin", "auditor"]
+        }
+      ]
+    },
+    {
+      "id": "SC4",
+      "title": "Временная роль действует",
+      "base": "SC1",
+      "values": {
+        "S5": [["bob", "editor", 5, 10]],
+        "S6": 7
+      },
+      "expect": [
+        {
+          "of": "F2",
+          "args": ["bob"],
+          "value": ["editor", "viewer", "auditor"]
+        },
+        {
+          "of": "F6",
+          "args": ["bob"],
+          "contains": ["write"]
+        }
+      ]
+    },
+    {
+      "id": "SC5",
+      "title": "Временная роль истекла",
+      "base": "SC4",
+      "values": {
+        "S6": 12
+      },
+      "expect": [
+        {
+          "of": "F6",
+          "args": ["bob"],
+          "excludes": ["write"]
+        }
+      ]
+    },
+    {
+      "id": "SC6",
+      "title": "Период задом наперёд",
+      "base": "SC1",
+      "values": {
+        "S5": [["bob", "editor", 10, 5]]
+      },
+      "expect": [
+        {
+          "of": "A3",
+          "holds": false
+        }
+      ]
+    }
+  ],
+  "assumptions": ["право — неделимый элемент, без привязки к конкретному ресурсу"],
+  "openQuestions": []
+}

package/examples/access-control/build-rsform.ts

@@ -0,0 +1,151 @@
+/**
+ * «Ролевой доступ»: RBAC with role hierarchy and separation of duties (v1), temporary roles (v2); anti-examples.
+ * Run from the package root: `pnpm run example:build-access-control-schema`.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { type AgentConstituentaPatch, RSToolAgent } from '../../src';
+
+import { describeBrief, formatDiagnostics } from '../diagnostics-utils';
+
+const V1_ITEMS: AgentConstituentaPatch[] = [
+  { alias: 'X1', term: 'пользователи', convention: 'Учётные записи пользователей системы.' },
+  { alias: 'X2', term: 'роли', convention: 'Роли доступа (администратор, редактор, …).' },
+  { alias: 'X3', term: 'права', convention: 'Элементарные права: действие над видом ресурса (чтение документов, …).' },
+  {
+    alias: 'S1',
+    term: 'назначения ролей',
+    definitionFormal: 'ℬ(X1×X2)',
+    convention: 'Пара (пользователь, роль): роль назначена пользователю напрямую.'
+  },
+  {
+    alias: 'S2',
+    term: 'права роли',
+    definitionFormal: 'ℬ(X2×X3)',
+    convention: 'Пара (роль, право): право дано роли напрямую.'
+  },
+  {
+    alias: 'S3',
+    term: 'иерархия ролей',
+    definitionFormal: 'ℬ(X2×X2)',
+    convention: 'Пара (старшая, младшая): старшая роль включает права младшей.'
+  },
+  {
+    alias: 'S4',
+    term: 'несовместимые роли',
+    definitionFormal: 'ℬ(X2×X2)',
+    convention: 'Пара ролей, которые нельзя иметь одному пользователю (разделение обязанностей).'
+  },
+  {
+    alias: 'F1',
+    term: 'младшие роли',
+    definitionFormal: '[ρ∈X2] R{σ:=Pr2(Fi1[{ρ}](S3)) | σ∪Pr2(Fi1[σ](S3))}',
+    definitionText: 'Роли, которые данная роль включает напрямую или через цепочку.'
+  },
+  {
+    alias: 'F2',
+    term: 'прямые роли',
+    definitionFormal: '[ξ∈X1] Pr2(Fi1[{ξ}](S1))',
+    definitionText: 'Роли, назначенные пользователю напрямую.'
+  },
+  {
+    alias: 'F3',
+    term: 'унаследованные роли',
+    definitionFormal: '[ξ∈X1] red(I{F1[ρ] | ρ:∈F2[ξ]})\\F2[ξ]',
+    definitionText: 'Роли, которые пользователь получает только через иерархию.'
+  },
+  {
+    alias: 'F4',
+    term: 'эффективные роли',
+    definitionFormal: '[ξ∈X1] F2[ξ]∪F3[ξ]',
+    definitionText: 'Прямые и унаследованные роли пользователя.'
+  },
+  {
+    alias: 'F5',
+    term: 'назначенные права',
+    definitionFormal: '[ξ∈X1] Pr2(Fi1[F2[ξ]](S2))',
+    definitionText: 'Права прямых ролей пользователя.'
+  },
+  {
+    alias: 'F6',
+    term: 'эффективные права',
+    definitionFormal: '[ξ∈X1] Pr2(Fi1[F4[ξ]](S2))',
+    definitionText: 'Права всех ролей пользователя, включая унаследованные.'
+  },
+  {
+    alias: 'A1',
+    term: 'иерархия без циклов',
+    definitionFormal: '∀ρ∈X2 ρ∉F1[ρ]',
+    definitionText: 'Роль не включает саму себя ни напрямую, ни через цепочку.'
+  },
+  {
+    alias: 'A2',
+    term: 'разделение обязанностей',
+    definitionFormal: '∀ξ∈X1 ∀(α,β)∈S4 ¬(α∈F4[ξ] & β∈F4[ξ])',
+    definitionText: 'Ни у одного пользователя нет обеих ролей несовместимой пары, в том числе через иерархию.'
+  }
+];
+
+/** Change request v2: temporary role assignments; F2 is redefined by decision DC6. */
+const V2_ITEMS: AgentConstituentaPatch[] = [
+  {
+    alias: 'S5',
+    term: 'временные назначения',
+    definitionFormal: 'ℬ(X1×X2×Z×Z)',
+    convention: 'Четвёрка (пользователь, роль, первый день, последний день): роль действует в эти дни включительно.'
+  },
+  {
+    alias: 'S6',
+    term: 'текущий день',
+    definitionFormal: 'Z',
+    convention: 'Номер текущего дня в той же нумерации, что и периоды назначений.'
+  },
+  {
+    alias: 'F2',
+    definitionFormal: '[ξ∈X1] Pr2(Fi1[{ξ}](S1)) ∪ I{pr2(τ) | τ:∈Fi1[{ξ}](S5); pr3(τ)≤S6; S6≤pr4(τ)}',
+    definitionText: 'Роли, назначенные пользователю напрямую: постоянно или временно с действующим сегодня периодом.'
+  },
+  {
+    alias: 'A3',
+    term: 'период назначения корректен',
+    definitionFormal: '∀τ∈S5 pr3(τ)≤pr4(τ)',
+    definitionText: 'Первый день периода не позже последнего.'
+  }
+];
+
+const ANTI_EXAMPLES: Record<string, AgentConstituentaPatch[]> = {
+  weakened: V1_ITEMS.map(item =>
+    item.alias === 'A2' ? { ...item, definitionFormal: '∀ξ∈X1 ∀(α,β)∈S4 ¬(α∈F2[ξ] & β∈F2[ξ])' } : item
+  ),
+  collapsed: V1_ITEMS.map(item => (item.alias === 'F6' ? { ...item, definitionFormal: '[ξ∈X1] F5[ξ]' } : item))
+};
+
+function build(title: string, brief: string, ...batches: AgentConstituentaPatch[][]): string {
+  const tool = new RSToolAgent();
+  tool.createSession({ alias: 'RBAC', title, comment: describeBrief(resolve(import.meta.dirname, brief)) });
+  for (const [index, items] of batches.entries()) {
+    const result = tool.applySchemaPatch({ items, commitMessage: `${title}: шаг ${index + 1}` });
+    if (!result.success) {
+      throw new Error(`${title}: ${formatDiagnostics(result.diagnostics)}`);
+    }
+  }
+  const diagnostics = tool.listDiagnostics();
+  if (diagnostics.length > 0) {
+    throw new Error(`${title}: ${formatDiagnostics(diagnostics)}`);
+  }
+  return tool.exportSession() + '\n';
+}
+
+function run() {
+  const root = import.meta.dirname;
+  writeFileSync(resolve(root, 'rsform-session-v1.json'), build('Ролевой доступ', 'brief-v1.json', V1_ITEMS));
+  writeFileSync(resolve(root, 'rsform-session.json'), build('Ролевой доступ', 'brief.json', V1_ITEMS, V2_ITEMS));
+  mkdirSync(resolve(root, 'anti'), { recursive: true });
+  for (const [name, items] of Object.entries(ANTI_EXAMPLES)) {
+    writeFileSync(resolve(root, 'anti', `${name}.json`), build(`Антипример: ${name}`, 'brief-v1.json', items));
+  }
+  console.log(`access-control: v1, v2 + ${Object.keys(ANTI_EXAMPLES).length} anti-examples`);
+}
+
+run();

package/examples/access-control/requirements-v1.md

@@ -0,0 +1,9 @@
+# Требования «Ролевой доступ», v1 (фрагмент)
+
+1. Пользователю назначают роли. Роли дают права.
+2. Роли образуют иерархию: старшая роль включает права младших. Циклов в иерархии быть не может.
+3. Права, назначенные пользователю, — права его прямых ролей. Эффективные права — права всех ролей, прямых и унаследованных по иерархии.
+4. Разделение обязанностей: некоторые пары ролей несовместимы; пользователь не может иметь (в том числе через иерархию) обе роли пары.
+5. Администратор видит, откуда у пользователя право: от прямой или унаследованной роли.
+6. Все изменения прав журналируются; журнал хранится 3 года.
+7. Вход по паролю или через корпоративный SSO.

package/examples/access-control/requirements-v2.md

@@ -0,0 +1,4 @@
+# Запрос на изменение v2
+
+1. Роль можно назначить временно: с дня по день включительно. Вне периода временная роль не действует.
+2. Постоянные назначения и всё остальное из v1 работают как раньше.