letopis 1.4.2 → 3.0.0

package/api-contract.json

@@ -0,0 +1,381 @@
+{
+  "$comment": "СГЕНЕРИРОВАНО lib/scripts/gen-api-contract.mjs из исходников — не редактировать руками. Регенерация: cd lib && npm run api:contract. CI сверяет через npm run check:docs.",
+  "package": {
+    "name": "letopis",
+    "type": "module",
+    "engines": {
+      "node": ">=22"
+    },
+    "exports": [
+      ".",
+      "./model",
+      "./mcp"
+    ]
+  },
+  "exports": {
+    ".": {
+      "values": [
+        "CHAIN_METHODS",
+        "DB_METHODS",
+        "DDL_REVISION",
+        "LOG_EVENTS",
+        "LetopisError",
+        "RESERVED_CLASS_NAMES",
+        "Registry",
+        "ValidationError",
+        "applyDefaults",
+        "between",
+        "compileValidator",
+        "connect",
+        "createTenant",
+        "cursorOf",
+        "ends",
+        "exists",
+        "fromDbError",
+        "generateTypes",
+        "gt",
+        "gte",
+        "has",
+        "hasAll",
+        "hasAny",
+        "hashPassword",
+        "idOf",
+        "ilike",
+        "inList",
+        "inc",
+        "isInc",
+        "isNull",
+        "isOp",
+        "like",
+        "loose",
+        "lt",
+        "lte",
+        "ne",
+        "not",
+        "or",
+        "schemaToTs",
+        "starts",
+        "syncModels",
+        "totpCode",
+        "up",
+        "uuidv5",
+        "v5Id",
+        "v5Name",
+        "verifyHash"
+      ],
+      "types": [
+        "AclApi",
+        "AclDataDecision",
+        "AclDecision",
+        "AclOp",
+        "AclRule",
+        "AclRuleSpec",
+        "AclTarget",
+        "AnyModelLike",
+        "AuthApi",
+        "Batch",
+        "BatchEntry",
+        "CacheOptions",
+        "CacheStats",
+        "Chain",
+        "ChainCore",
+        "ChainMods",
+        "ChainRef",
+        "ClassInfo",
+        "ConnectOptions",
+        "Credential",
+        "Cursor",
+        "Db",
+        "DbCore",
+        "DbTx",
+        "DeleteOptions",
+        "EndInfo",
+        "Expected",
+        "FieldFilter",
+        "FieldFilterOf",
+        "Filter",
+        "FilterOf",
+        "IncMarker",
+        "Issue",
+        "KeyedClass",
+        "LeafType",
+        "LoadInput",
+        "LoadIssue",
+        "LoadOptions",
+        "LoadReport",
+        "LogEvent",
+        "LogEventName",
+        "LogFn",
+        "LogLevel",
+        "LogObject",
+        "LogOptions",
+        "Logger",
+        "LoginOptions",
+        "LoginResult",
+        "MaintainReport",
+        "ModelLike",
+        "Op",
+        "OrOp",
+        "PatchOf",
+        "Path",
+        "QueryEvent",
+        "RestoreOptions",
+        "Row",
+        "RowOf",
+        "Scalar",
+        "SessionInfo",
+        "SignalMode",
+        "StepFn",
+        "StepsOf",
+        "Subscription",
+        "SyncResult",
+        "SystemModels",
+        "TenantOptions",
+        "TenantResult",
+        "TypedChain",
+        "TypedDb",
+        "UpOptions",
+        "UpResult",
+        "Validator",
+        "WatchEvent",
+        "WatchOptions",
+        "WriteRow"
+      ]
+    },
+    "./model": {
+      "values": [
+        "End",
+        "hub",
+        "link",
+        "many",
+        "normalizeSchema",
+        "one",
+        "translatePattern"
+      ],
+      "types": [
+        "AnyModel",
+        "ClassDef",
+        "ClassDescription",
+        "ClassMeta",
+        "Infer",
+        "InferLinks",
+        "JsonSchema",
+        "LostRule",
+        "Model",
+        "OnDelete"
+      ]
+    },
+    "./mcp": {
+      "values": [
+        "createMcpServer"
+      ],
+      "types": [
+        "McpOptions"
+      ]
+    }
+  },
+  "chain": [
+    "add",
+    "after",
+    "alias",
+    "asOf",
+    "avg",
+    "cache",
+    "count",
+    "countBy",
+    "create",
+    "deep",
+    "delete",
+    "entity",
+    "exact",
+    "first",
+    "forUpdate",
+    "ids",
+    "limit",
+    "max",
+    "min",
+    "offset",
+    "owner",
+    "paths",
+    "remove",
+    "restore",
+    "rows",
+    "set",
+    "sort",
+    "sum",
+    "tags",
+    "then",
+    "unset",
+    "update",
+    "upsert",
+    "versions",
+    "withDeleted"
+  ],
+  "db": [
+    "acl",
+    "as",
+    "auth",
+    "batch",
+    "begin",
+    "cache",
+    "close",
+    "commit",
+    "flushSignals",
+    "idOf",
+    "load",
+    "lock",
+    "maintain",
+    "refresh",
+    "registry",
+    "rollback",
+    "schema",
+    "sql",
+    "tenant",
+    "token",
+    "transaction",
+    "watch"
+  ],
+  "batch": [
+    "discard",
+    "run",
+    "size"
+  ],
+  "codes": [
+    "acl_denied",
+    "admin_required",
+    "bypass_rls",
+    "class_not_loadable",
+    "commit_unknown",
+    "confirmation_required",
+    "conflict",
+    "delete_restricted",
+    "deleted",
+    "duplicate",
+    "exists",
+    "id_from_db",
+    "id_mismatch",
+    "immutable_key",
+    "internal",
+    "invalid_class",
+    "invalid_data",
+    "invalid_query",
+    "isolation_level",
+    "lock_unsupported",
+    "no_key",
+    "no_path",
+    "no_session",
+    "not_deleted",
+    "not_empty",
+    "recreated_in_statement",
+    "rev_ambiguous",
+    "target_not_found",
+    "tenant_denied",
+    "tightening_conflict",
+    "tx_required",
+    "tx_rolled_back",
+    "undeclared_end",
+    "user_session_required"
+  ],
+  "errors": [
+    {
+      "module": "15-errors",
+      "message": "letopis: acl_denied: отказ по правилам доступа"
+    },
+    {
+      "module": "15-errors",
+      "message": "letopis: delete_restricted: удалению мешают ссылающиеся строки"
+    },
+    {
+      "module": "15-errors",
+      "message": "letopis: id_from_db: id класса без ключа выдаёт база"
+    },
+    {
+      "module": "15-errors",
+      "message": "letopis: id_mismatch: id не равен v5 от ключа"
+    },
+    {
+      "module": "15-errors",
+      "message": "letopis: immutable_key: ключевое поле менять нельзя"
+    },
+    {
+      "module": "15-errors",
+      "message": "letopis: invalid_class: описание класса отклонено"
+    },
+    {
+      "module": "15-errors",
+      "message": "letopis: invalid_data: данные не проходят описание класса"
+    },
+    {
+      "module": "15-errors",
+      "message": "letopis: isolation_level: операция разрешена только в read committed"
+    },
+    {
+      "module": "15-errors",
+      "message": "letopis: no_session: нет действующей сессии"
+    },
+    {
+      "module": "15-errors",
+      "message": "letopis: not_deleted: объект не удалён — restore только для удалённых"
+    },
+    {
+      "module": "15-errors",
+      "message": "letopis: recreated_in_statement: id удалён и создан заново одним оператором"
+    },
+    {
+      "module": "15-errors",
+      "message": "letopis: target_not_found: цель не найдена"
+    },
+    {
+      "module": "15-errors",
+      "message": "letopis: tenant_denied: чужой арендатор"
+    },
+    {
+      "module": "15-errors",
+      "message": "letopis: tightening_conflict: ужесточению описания мешают строки"
+    },
+    {
+      "module": "15-errors",
+      "message": "letopis: undeclared_end: конец не объявлен в классе"
+    },
+    {
+      "module": "60-write",
+      "message": "letopis: invalid_data: "
+    },
+    {
+      "module": "errors",
+      "message": "letopis: <…>"
+    },
+    {
+      "module": "errors",
+      "message": "letopis: <…>: <…>"
+    },
+    {
+      "module": "errors",
+      "message": "letopis: invalid_data: <…><…>"
+    },
+    {
+      "module": "messages/index",
+      "message": "letopis: ключ каталога <…> повторяется"
+    },
+    {
+      "module": "messages/index",
+      "message": "letopis: ключ каталога <…> — не из раздела <…>"
+    },
+    {
+      "module": "up",
+      "message": "letopis.up: ${own ? seed : "
+    },
+    {
+      "module": "up",
+      "message": "letopis.up: <…>"
+    },
+    {
+      "module": "up",
+      "message": "letopis.up: <…>: <…>"
+    },
+    {
+      "module": "up",
+      "message": "letopis.up: migrate/<…>: <…>"
+    }
+  ]
+}

package/dist/acl.d.ts

@@ -1,4 +1,5 @@
 import type { Executor } from './tx.js';
+import type { CallSpec } from './log.js';
 export type AclOp = 'READ' | 'WRITE' | 'DELETE';
 /** Решение по ресурсу приложения (эндпоинту): можно ли к нему обратиться. */
 export interface AclDecision {
@@ -20,6 +21,52 @@ export interface AclDataDecision {
     allow: boolean;
     filter?: Record<string, unknown>;
 }
+/**
+ * Цель правила на строки: имя класса (правило действует и на потомков), `'*'` — все классы, или класс с условием на
+ * строки — шаблоном колонок `owner`, `tenant`, `tags`, `data`, `links`, `id` (`'$actor'` — тот, от чьего имени запрос,
+ * `'$tenant'` — рабочий арендатор): `{ class: 'Ticket', owner: '$actor' }`.
+ */
+export type AclTarget = string | ({
+    class: string;
+} & {
+    [column: string]: unknown;
+});
+/**
+ * Что разрешить, запретить или снять: кому — ровно одно из `role` и `everyone` (иначе `invalid_data`), операции — с
+ * классами, ресурсами приложения или с теми и другими.
+ */
+export interface AclRuleSpec {
+    /** Роль членства в текущем арендаторе (как в `member.roles`). */
+    role?: string;
+    /** Все аккаунты арендатора, кроме анонимных и теневых, — группа правил «можно всё» от createTenant. */
+    everyone?: true;
+    read?: AclTarget | readonly AclTarget[];
+    write?: AclTarget | readonly AclTarget[];
+    delete?: AclTarget | readonly AclTarget[];
+    /** Ресурсы приложения — маски эндпоинтов, как у `check()`: `'reports.*'` — `reports.daily`, но не `reports`. */
+    api?: string | readonly string[];
+    /** Вес правила, целое от 1 до 999; по умолчанию 50 — сильнее правила «можно всё» (вес 10) от createTenant. */
+    weight?: number;
+}
+/** Правило арендатора в виде обёртки. */
+export interface AclRule {
+    id: string;
+    /** Роль группы `role:<роль>:ACCOUNT`; null — группа не одной роли (все аккаунты или своя группа). */
+    role: string | null;
+    /** Группа всех аккаунтов арендатора: `authenticated:ACCOUNT` от createTenant или `everyone:ACCOUNT` обёртки. */
+    everyone: boolean;
+    /** Alias группы. */
+    group: string;
+    op: AclOp | 'API';
+    /** Класс (`'*'` — все классы) или маска эндпоинта. */
+    target: string;
+    /** Условие на строки — шаблон колонок. */
+    condition?: Record<string, unknown>;
+    permission: 'allow' | 'deny';
+    weight: number;
+    /** Действует ли правило: `false` — выключено полем `enabled` строки `rule`, база его не применяет. */
+    enabled: boolean;
+}
 export interface AclApi {
     /**
      * Можно ли тому, от чьего имени идёт запрос, обратиться к ресурсу приложения (эндпоинту). Решают правила доступа
@@ -31,5 +78,38 @@ export interface AclApi {
      * что подходят под условие `filter` в ответе.
      */
     checkData(className: string, op: AclOp): Promise<AclDataDecision>;
+    /**
+     * Разрешить роли (`role`) или всем аккаунтам арендатора (`everyone: true`) операции с классами и ресурсы приложения —
+     * по правилу на каждую операцию и цель, с весом `weight` (по умолчанию 50). Повтор ничего не меняет; запрет той же
+     * группы и цели заменяется разрешением. Внутри `db.begin()` — в её транзакции, иначе — своей.
+     */
+    grant(spec: AclRuleSpec): Promise<AclRule[]>;
+    /** Запретить — те же правила с запретом: при равном весе запрет сильнее разрешения. */
+    deny(spec: AclRuleSpec): Promise<AclRule[]>;
+    /**
+     * Снять правила роли или всех аккаунтов — разрешения и запреты — для этих операций и целей; число снятых.
+     * `revoke({ everyone: true, read: '*', write: '*', delete: '*' })` снимает «можно всё» от createTenant: дальше права —
+     * только по ролям.
+     */
+    revoke(spec: Omit<AclRuleSpec, 'weight'>): Promise<number>;
+    /**
+     * Роли аккаунта в текущем арендаторе (строка `member`); null — не член. Со списком ролей — заменить их (членство
+     * заводится, если его нет), с null — снять членство. Сам арендатор (вход под его аккаунтом) — владелец без строки
+     * `member`: для него ответ null.
+     */
+    roles(account: string | {
+        id: string;
+    }, roles?: readonly string[] | null): Promise<string[] | null>;
+    /**
+     * Правила текущего арендатора — свои и «можно всё» от createTenant. На подключении без RLS (`allowBypassRls`) — тоже
+     * только правила арендатора сессии, без правил других арендаторов и System.
+     */
+    list(): Promise<AclRule[]>;
 }
-export declare function makeAcl(S: string, exec: Executor): AclApi;
+/**
+ * db.acl фасада. db — сам фасад (корень, db.as(), db.begin()): запись правил идёт его цепочками, внутри db.begin() — в её
+ * транзакции.
+ */
+export declare function makeAcl(S: string, exec: Executor, db?: () => unknown): AclApi;
+/** Что пишет в лог каждый метод db.acl: правка прав — acl.change, проверки и список — acl.check. */
+export declare const ACL_LOG: Readonly<Record<string, CallSpec>>;