letopis 1.4.2 → 3.0.0

package/dist/admin.js

@@ -1,68 +1,35 @@
-import { LetopisError, fromDbError } from './errors.js';
+/**
+ * Эксплуатация (план, этап 6, п. 7, 8): maintain и его запуск по расписанию. Всё проверяет база: функция владельца
+ * 90-time.sql сама сверяет права (letopis.maintain — системный администратор или администраторское подключение).
+ */
+import { lerr, lmsg, lwarn, warnText } from './errors.js';
+import { safeErrorText } from './log.js';
 import { runTx } from './tx.js';
-import { CHAIN_METHODS, DB_METHODS } from './types.js';
-/** Внутренняя опция maintain(): остановка запуска по расписанию — текущая пачка доделывается, следующая не начинается. */
-export const MAINTAIN_STOP = Symbol('letopis.maintain.stop');
-const SYSTEM_CLASSES = new Set(['Class', 'Account', 'member', 'Resource', 'rule']);
-const one = async (a, text, params = []) => a.exec.run(async (q) => (await q.unsafe(text, params))[0]);
-export async function verify(a, opts = {}) {
-    const r = await one(a, `select ${a.S}.verify($1::boolean) as v`, [opts.data === true]);
-    return r.v;
-}
 /**
- * Обслуживание: истёкшие сессии и коды, прореживание журнала пачками (каждая — своя транзакция,
- * долгих блокировок нет), заполнение очереди сигналов. Из нескольких процессов работает один: пачка
- * первым делом берёт строку-замок обслуживания (lock_try в maintain() базы: for update skip locked строки
- * secret, которую посторонняя роль не займёт), и та снимается с фиксацией пачки. Сеансовая блокировка
- * за пулом в режиме транзакций (PgBouncer) оставалась бы на
- * серверном соединении, которое пул отдаёт другим клиентам, — и обслуживание молча вставало бы
- * (skipped у всех). Блокировку держит другой процесс: до первой пачки — skipped; между пачками —
- * вызов останавливается (продолжит тот процесс), отчёт — о сделанном, more: true.
+ * Обслуживание: истёкшие и погашенные сессии, одноразовые коды, строки-замки удалённых семейств и заполнение очереди
+ * сигналов — одной транзакцией. Из нескольких процессов работает один: maintain() базы первым делом берёт строку-замок
+ * обслуживания (lock_try: for update skip locked строки secret, которую посторонняя роль не займёт), и та снимается с
+ * фиксацией. Сеансовая блокировка за пулом в режиме транзакций (PgBouncer) оставалась бы на серверном соединении,
+ * которое пул отдаёт другим клиентам, — и обслуживание молча вставало бы (skipped у всех). Строку-замок держит другой
+ * процесс — skipped.
  */
-export async function maintain(a, opts = {}) {
+export async function maintain(a) {
     if (a.exec.explicit)
-        throw new LetopisError('invalid_query', 'maintain() — пачками в своих транзакциях, не внутри db.begin()');
-    const now = opts.now === undefined ? null : opts.now instanceof Date ? opts.now.toISOString() : opts.now;
-    const report = { skipped: false, sessions: 0, codes: 0, thinned: 0, batches: 0, more: false, queue: 0 };
-    const max = opts.batches ?? 100;
-    for (let i = 0; i < max; i++) {
-        // запуск по расписанию остановлен (close()): следующая пачка не начинается, отчёт — с more: true
-        if (i > 0 && opts[MAINTAIN_STOP]?.())
-            break;
-        // блокировку берёт сама maintain() базы — строку-замок, которую посторонняя роль не займёт; занята — null.
-        // Истёкшие сессии и коды — только в первой пачке (план 2.0, 7.3 №4); схема, функции которой ещё не обновил up()
-        // (нет третьего аргумента, 42883), — прежний вызов: он чистит в каждой пачке
-        const call = (cleanup) => runTx(a.txc, (q) => q.unsafe(cleanup === null
-            ? `select ${a.S}.maintain($1::text::timestamptz, $2::int) as r`
-            : `select ${a.S}.maintain($1::text::timestamptz, $2::int, $3::boolean) as r`, (cleanup === null ? [now, opts.limit ?? 10_000] : [now, opts.limit ?? 10_000, cleanup])));
-        const [{ r }] = await call(i === 0).catch((e) => {
-            if (e.code === '42883')
-                return call(null);
-            throw e;
-        });
-        if (r === null) {
-            if (i === 0)
-                return { ...report, skipped: true };
-            break;
-        }
-        const b = r;
-        report.sessions += b.sessions;
-        report.codes += b.codes;
-        report.thinned += b.thinned;
-        report.queue = Number(b.queue);
-        report.more = b.more;
-        report.batches++;
-        if (!b.more)
-            break;
-    }
+        throw lerr('time.maintain_in_tx');
+    const [{ r }] = await runTx(a.txc, (q) => q.unsafe(`select ${a.S}.maintain() as r`));
+    if (r === null)
+        return { skipped: true, sessions: 0, codes: 0, queue: 0 };
+    const b = r;
+    const report = { skipped: false, sessions: b.sessions, codes: b.codes, queue: Number(b.queue) };
     const warn = queueWarning(report.queue);
+    // логгер задан — событие warning (time.signal_queue), иначе console.warn, как прежде
     if (warn)
-        console.warn(warn);
+        warnText(warn, 'time.signal_queue', a.txc.log, { queue: report.queue });
     return report;
 }
 /** Предупреждение о заполненной очереди сигналов (§2.12): больше половины — зависший слушатель. */
 export function queueWarning(queue) {
-    return queue > 0.5 ? `letopis: очередь сигналов PostgreSQL заполнена на ${(queue * 100).toFixed(0)} % — проверьте зависших слушателей` : null;
+    return queue > 0.5 ? `letopis: ${lmsg('time.signal_queue', { pct: (queue * 100).toFixed(0) })}` : null;
 }
 /** Самый длинный интервал таймера Node.js — 2³¹−1 мс (около 24,8 суток): дольше таймер не ждёт и срабатывает сразу. */
 const MAX_TIMER_MS = 2 ** 31 - 1;
@@ -82,23 +49,23 @@ export function parseInterval(v) {
     }
     if (!Number.isFinite(ms) || ms < 1 || ms > MAX_TIMER_MS) {
         const shown = typeof v === 'string' ? `'${v}'` : typeof v === 'number' || typeof v === 'boolean' || v == null ? String(v) : typeof v;
-        throw new LetopisError('invalid_data', `интервал ${shown}: число мс или строка '30s', '15m', '1h', '1d' — от 1 мс до 2³¹−1 мс (около 24 суток)`);
+        throw lerr('time.bad_interval', { value: shown });
     }
     return ms;
 }
 /**
  * Запуск maintain() по расписанию (connect({ maintain: '1h' }); ms — уже проверенный интервал): ошибки — предупреждением,
- * следующий запуск не начинается, пока идёт прежний. Возвращает остановку: она снимает таймер, просит идущий запуск не
- * начинать новых пачек и ждёт его конца — close() закрывает пул после неё, а не посреди пачки.
+ * следующий запуск не начинается, пока идёт прежний. Возвращает остановку: она снимает таймер и ждёт конца идущего
+ * запуска — close() закрывает пул после него, а не посреди транзакции.
  */
-export function scheduleMaintain(run, ms) {
+export function scheduleMaintain(run, ms, log) {
     let stopped = false;
     let current = null;
     const timer = setInterval(() => {
         if (current || stopped)
             return;
-        current = run(() => stopped)
-            .then(() => { }, (e) => console.warn(`letopis: maintain по расписанию: ${e.message}`))
+        current = run()
+            .then(() => { }, (e) => lwarn('time.maintain_failed', { message: safeErrorText(e) }, { log }))
             .finally(() => (current = null));
     }, ms);
     timer.unref?.();
@@ -108,128 +75,3 @@ export function scheduleMaintain(run, ms) {
         await current;
     };
 }
-/**
- * Сброс (этап 6, п. 6). Предохранители — в базе: флаг allowReset установки, право letopis.reset,
- * подтверждение именем схемы. tenant — пачками (длинная операция не держит горизонт подписок).
- */
-export async function reset(a, opts) {
-    if (opts.level === 'tenant') {
-        if (a.exec.explicit)
-            throw new LetopisError('invalid_query', "reset({ level: 'tenant' }) — пачками в своих транзакциях, не внутри db.begin()");
-        let rows = 0;
-        let versions = 0;
-        for (;;) {
-            const [{ r }] = await runTx(a.txc, (q) => q.unsafe(`select ${a.S}.reset($1, $2, $3::uuid, 10000) as r`, [opts.level, opts.confirm, opts.tenant ?? null]));
-            const b = r;
-            rows += b.rows;
-            versions += b.versions;
-            if (b.done)
-                return { level: opts.level, tenant: b.tenant, rows, versions };
-        }
-    }
-    const r = await one(a, `select ${a.S}.reset($1, $2, $3::uuid) as r`, [opts.level, opts.confirm, opts.tenant ?? null]);
-    return r.r;
-}
-/**
- * Обрезка истории (этап 6, п. 3): версии строже момента before удаляются, текущая — никогда; на место
- * версии 1 встаёт запись trim. target — имя класса (с потомками), id или список id, строка ответа.
- */
-export async function trimHistory(a, target, before) {
-    const at = before instanceof Date ? before.toISOString() : before;
-    let ids = null;
-    let classes = null;
-    if (typeof target === 'string' && a.registry().has(target)) {
-        classes = a.registry().family(target).map((c) => c.name);
-    }
-    else {
-        const list = Array.isArray(target) ? target : [target];
-        ids = list.map((x) => (typeof x === 'string' ? x : x.id));
-    }
-    const r = await one(a, `select ${a.S}.trim_history($1::uuid[], $2::text[], $3::text::timestamptz) as n`, [ids, classes, at]);
-    return r.n;
-}
-/** Новый ключ класса (этап 6, п. 7): строки семейства переносятся на новые id. Возвращает их число. */
-export async function rekeyClass(a, cls, key) {
-    const name = a.registry().resolve(cls).name;
-    const r = await one(a, `select ${a.S}.rekey_class($1, $2::jsonb) as n`, [name, key]);
-    return r.n;
-}
-/**
- * Ремонт агрегатов (план 1.1, §2.4): поля класса и его потомков во всех арендаторах — заново из живых источников,
- * под исключительными блокировками семейств целей и источников (запись в них ждёт). Версия пишется только там, где
- * значение изменилось; возвращает число исправленных строк. Функция владельца — от его роли (set local role), как
- * загрузчик; подключение проверил вызывающий (admin_required).
- */
-export async function rebuildAggregates(env, cls) {
-    if (typeof cls !== 'string' || !cls)
-        throw new LetopisError('invalid_data', 'rebuildAggregates(класс): имя класса');
-    const role = `"${env.ownerRole.replace(/"/g, '""')}"`;
-    return env.sql.begin(async (q) => {
-        await q.unsafe(`set local role ${role}`);
-        await q.unsafe(`select set_config('letopis.reason', 'rebuildAggregates', true)`);
-        const [{ n }] = await q.unsafe(`select ${env.S}.rebuild_aggregates($1) as n`, [cls]);
-        return n;
-    }).catch((e) => {
-        throw fromDbError(e);
-    });
-}
-/** Машинное описание модели арендатора вместе с метаданными классов (этап 6, п. 12). */
-export function describe(a) {
-    const classes = a.registry().all().map((c) => ({
-        name: c.name,
-        kind: c.kind,
-        ...(c.alias ? { alias: c.alias } : {}),
-        abstract: c.abstract,
-        ...(c.ancestors[1] ? { parent: c.ancestors[1] } : {}),
-        ancestors: c.ancestors,
-        system: SYSTEM_CLASSES.has(c.name),
-        fields: (c.schema.properties ?? {}),
-        required: (c.schema.required ?? []),
-        ...(Array.isArray(c.schema.anyOf) ? { anyOf: c.schema.anyOf } : {}),
-        ...(Array.isArray(c.schema.oneOf) ? { oneOf: c.schema.oneOf } : {}),
-        ends: c.ends,
-        key: c.key,
-        history: c.history,
-        ownerDefault: c.ownerDefault,
-        ...(c.cache ? { cache: c.cache } : {}),
-        meta: c.meta,
-        ...(c.derivedBy ? { derivedBy: c.derivedBy } : {}),
-        ...(c.aggregate ? { aggregate: c.aggregate } : {}),
-    })).sort((x, y) => Number(x.system) - Number(y.system) || x.name.localeCompare(y.name));
-    return { schema: a.schema, tenant: a.tenant(), classes, methods: { chain: CHAIN_METHODS, db: DB_METHODS } };
-}
-/** Описание модели текстом для языковых моделей. */
-export function describeText(d) {
-    const out = [`# letopis: модель схемы ${d.schema}`, '',
-        'Цепочка: db.Класс(фильтр).Связь().Класс().rows(); запись — create, update, upsert, delete; история — versions(), asOf(), withDeleted().', ''];
-    for (const c of d.classes) {
-        const title = typeof c.meta.title === 'string' ? ` — ${c.meta.title}` : '';
-        out.push(`## ${c.name}${c.alias ? ` (${c.alias})` : ''}${title}`);
-        out.push(`- вид: ${c.kind === 'hub' ? 'хаб (объект)' : 'связь'}${c.abstract ? ', абстрактный' : ''}${c.parent ? `, предок ${c.parent}` : ''}${c.system ? ', системный' : ''}`);
-        out.push(`- ключ: ${c.key.length ? c.key.join(', ') : 'нет (id выдаёт база)'}`);
-        const fields = Object.entries(c.fields).map(([k, v]) => {
-            const t = v.type;
-            return `${k}${c.required.includes(k) ? '*' : ''}: ${Array.isArray(t) ? t.join('|') : t ?? 'any'}`;
-        });
-        if (fields.length)
-            out.push(`- поля: ${fields.join(', ')}`);
-        if (c.anyOf)
-            out.push(`- условия anyOf (хотя бы одно): ${JSON.stringify(c.anyOf)}`);
-        if (c.oneOf)
-            out.push(`- условия oneOf (ровно одно): ${JSON.stringify(c.oneOf)}`);
-        const ends = Object.entries(c.ends).map(([k, v]) => {
-            const e = v;
-            return `${k}${e.required ? '*' : ''} → ${Array.isArray(e.class) ? e.class.join('|') : e.class}${e.many ? '[]' : ''}`;
-        });
-        if (ends.length)
-            out.push(`- концы: ${ends.join(', ')}`);
-        if (c.derivedBy)
-            out.push(`- производный: строки пишет проектор ${c.derivedBy}, приложение только читает`);
-        for (const [field, a] of Object.entries(c.aggregate ?? {})) {
-            const what = a.sum !== undefined ? `сумма ${a.sum}` : 'число';
-            out.push(`- агрегат ${field} = ${what} строк ${a.of} по концу ${a.via}${a.where ? `, условие ${JSON.stringify(a.where)}` : ''}; поле считает база, приложение его не пишет`);
-        }
-        out.push('');
-    }
-    return out.join('\n');
-}

package/dist/auth.d.ts

@@ -1,5 +1,6 @@
 import type { Executor } from './tx.js';
-/** Хэш пароля scrypt: `scrypt$N$r$p$соль$хэш` (формат 0.21). */
+import type { CallSpec } from './log.js';
+/** Хэш пароля scrypt: `scrypt$N$r$p$соль$хэш`. */
 export declare function hashPassword(password: string): Promise<string>;
 /** Проверка пароля по хэшу scrypt; другие форматы не проверяются. */
 export declare function verifyHash(password: string, stored: string): Promise<boolean>;
@@ -184,19 +185,31 @@ export interface AuthApi {
     refresh(opts?: {
         ttl?: number;
     }): Promise<string>;
-    /** Выход: погасить текущую сессию. */
-    revoke(): Promise<boolean>;
+    /**
+     * Выход. Без аргумента — погасить сессию этого подключения. С токеном — погасить сессию пользователя по её токену
+     * (например, из cookie веб-сервиса): так сервис выводит пользователя, не подключаясь по его токену; нужно право
+     * `auth.session`, как у `session(token)`.
+     * @returns true — сессия погашена; false — токен неверный, сессия уже погашена или истекла (причина не различается).
+     * @throws LetopisError `acl_denied` — с токеном, а у вызывающего нет права `auth.session`; `no_session` — у подключения
+     * нет действующей сессии.
+     */
+    revoke(token?: string): Promise<boolean>;
     /** Выход везде: все сессии аккаунта (чужого — с правом `auth.session`). */
     revokeAll(account?: AccountRef): Promise<number>;
     /** Переключить арендатора сессии: собственный или по членству. */
     switch(tenant: string): Promise<void>;
-    /** Арендаторы, доступные аккаунту сессии: собственный (`owner`) и по членству. */
+    /**
+     * Арендаторы, доступные аккаунту сессии: собственный (`roles: ['owner']`, `personal: true`) и по членству. `name` — имя
+     * аккаунта арендатора (`createTenant({ name })`, у личного — имя пользователя).
+     */
     tenants(): Promise<{
         tenant: string;
         roles: string[];
+        name: string | null;
+        personal: boolean;
     }[]>;
     /**
-     * Удалить аккаунт (этап 6; accounts.purge 0.21): системный администратор или владелец его
+     * Удалить аккаунт: системный администратор или владелец его
      * арендатора; себя и последнего владельца арендатора — нельзя. Данные арендатора стираются,
      * владение строками в чужих арендаторах переходит им, сессии гаснут, креды удаляются. Владелец стирает
      * и арендатора, в котором работает: его сессия возвращается в личный арендатор.
@@ -211,4 +224,6 @@ export interface AuthApi {
 }
 /** Фасад db.auth. onSwitch — подключение перечитывает арендатора, реестр и пропуска прав. */
 export declare function makeAuth(S: string, exec: Executor, onSwitch: () => Promise<void>, canSwitch: boolean): AuthApi;
+/** Что пишет в лог каждый метод db.auth. */
+export declare const AUTH_LOG: Readonly<Record<string, CallSpec>>;
 export {};

package/dist/auth.js

@@ -11,11 +11,11 @@
  */
 import { createHmac, randomBytes, scrypt, timingSafeEqual } from 'node:crypto';
 import { promisify } from 'node:util';
-import { LetopisError, removed } from './errors.js';
+import { lerr } from './errors.js';
 const scryptAsync = promisify(scrypt);
 const SCRYPT = { N: 32768, r: 8, p: 1, maxmem: 64 * 1024 * 1024 };
 const KEYLEN = 32;
-/** Хэш пароля scrypt: `scrypt$N$r$p$соль$хэш` (формат 0.21). */
+/** Хэш пароля scrypt: `scrypt$N$r$p$соль$хэш`. */
 export async function hashPassword(password) {
     const salt = randomBytes(16);
     const hash = await scryptAsync(password, salt, KEYLEN, SCRYPT);
@@ -31,7 +31,7 @@ export async function verifyHash(password, stored) {
     // которому нужно больше, или с недопустимыми параметрами scrypt Node.js отвергает — это понятная ошибка, а не «неверный
     // пароль» (false). Текст Node.js в сообщение не идёт: он зависит от сборки OpenSSL
     const got = await scryptAsync(password, Buffer.from(saltB64, 'base64'), want.length, { N: Number(N), r: Number(r), p: Number(p), maxmem: SCRYPT.maxmem }).catch(() => {
-        throw new LetopisError('invalid_data', `хэш пароля: параметры scrypt N=${N}, r=${r}, p=${p} недопустимы или требуют больше 64 МБ памяти`);
+        throw lerr('access.bad_scrypt_params', { N, r, p });
     });
     return got.length === want.length && timingSafeEqual(got, want);
 }
@@ -61,7 +61,7 @@ export function base32Decode(s) {
     for (const ch of s.replace(/=+$/, '').toUpperCase()) {
         const idx = B32.indexOf(ch);
         if (idx < 0)
-            throw new LetopisError('invalid_data', 'секрет TOTP — не base32');
+            throw lerr('access.bad_totp_secret');
         value = (value << 5) | idx;
         bits += 5;
         if (bits >= 8) {
@@ -83,19 +83,11 @@ export function totpCode(secretBase32, atMs = Date.now()) {
     return String(code).padStart(TOTP_DIGITS, '0');
 }
 const accId = (a) => (typeof a === 'object' ? a.id : a);
+/** Логин без крайних пробелов (план 2.1, A12): « anna » и «anna» — один логин; не строка — как есть (отказ даст база). */
+const trimLogin = (v) => (typeof v === 'string' ? v.trim() : v);
 const ttlOf = (sec) => (sec === undefined ? null : `${Math.round(sec)} seconds`);
 /** Фасад db.auth. onSwitch — подключение перечитывает арендатора, реестр и пропуска прав. */
 export function makeAuth(S, exec, onSwitch, canSwitch) {
-    const api = makeAuthCore(S, exec, onSwitch, canSwitch);
-    return new Proxy(api, {
-        get(t, p, r) {
-            if (p === 'sessions')
-                throw removed('db.auth.sessions(store)', 'сессии хранятся в базе: sessionFor, refresh, revoke, revokeAll');
-            return Reflect.get(t, p, r);
-        },
-    });
-}
-function makeAuthCore(S, exec, onSwitch, canSwitch) {
     const one = async (text, params = []) => {
         const rows = await exec.run((q) => q.unsafe(text, params));
         return rows[0];
@@ -118,12 +110,14 @@ function makeAuthCore(S, exec, onSwitch, canSwitch) {
     return {
         async setPassword(a) {
             const hash = await hashPassword(a.password);
-            const r = await one(`select ${S}.auth_set_password($1::uuid, $2, $3, $4, $5, $6) as id`, [accId(a.account), a.identifier, hash, a.kind ?? 'PASSWORD', a.confirmed ?? null, a.keepCurrent ?? true]);
+            const r = await one(`select ${S}.auth_set_password($1::uuid, $2, $3, $4, $5, $6) as id`, [accId(a.account), trimLogin(a.identifier), hash, a.kind ?? 'PASSWORD', a.confirmed ?? null, a.keepCurrent ?? true]);
             return r.id;
         },
         async verifyPassword(a) {
-            const rows = await exec.run((q) => q.unsafe(`select account, hash, confirmed from ${S}.auth_password_get($1, $2)`, [a.identifier, a.kind ?? 'PASSWORD']));
-            const cred = rows[0];
+            const get = async (ident) => (await exec.run((q) => q.unsafe(`select account, hash, confirmed from ${S}.auth_password_get($1, $2)`, [ident, a.kind ?? 'PASSWORD'])))[0];
+            // логин без крайних пробелов (план 2.1, A12); кред, записанный до 2.1 с пробелами, находится по логину как есть
+            const ident = trimLogin(a.identifier);
+            const cred = (await get(ident)) ?? (ident !== a.identifier ? await get(a.identifier) : undefined);
             if (!cred)
                 return dummyVerify(a.password).then(() => null);
             if (!(await verifyHash(a.password, cred.hash)))
@@ -191,7 +185,10 @@ function makeAuthCore(S, exec, onSwitch, canSwitch) {
         async refresh(opts) {
             return (await one(`select ${S}.auth_refresh(coalesce($1::interval, interval '7 days')) as e`, [ttlOf(opts?.ttl)])).e;
         },
-        async revoke() {
+        async revoke(token) {
+            // с токеном — выход пользователя по токену (план 2.1, A3): право auth.session, как у session(token)
+            if (token !== undefined)
+                return (await one(`select ${S}.auth_logout_token($1) as ok`, [token])).ok;
             return (await one(`select ${S}.auth_logout() as ok`)).ok;
         },
         async revokeAll(account) {
@@ -199,13 +196,14 @@ function makeAuthCore(S, exec, onSwitch, canSwitch) {
         },
         async switch(tenant) {
             if (!canSwitch)
-                throw new LetopisError('invalid_query', 'auth.switch() — от корня подключения: при имперсонации арендатора задаёт db.as(…, { tenant })');
+                throw lerr('access.switch_not_root');
             await one(`select ${S}.auth_switch($1::uuid)`, [tenant]);
             await onSwitch();
         },
         async tenants() {
-            const rows = await exec.run((q) => q.unsafe(`select tenant, roles from ${S}.auth_tenants()`));
-            return rows.map((r) => ({ tenant: r.tenant, roles: r.roles }));
+            // name и personal — с ревизии 9 (план 2.1, A5): personal — собственный арендатор аккаунта сессии (tenant = account)
+            const rows = await exec.run((q) => q.unsafe(`select tenant, roles, name, personal from ${S}.auth_tenants()`));
+            return rows.map((r) => ({ tenant: r.tenant, roles: r.roles, name: r.name ?? null, personal: r.personal === true }));
         },
         async purgeAccount(account) {
             const r = (await one(`select ${S}.account_purge($1::uuid) as r`, [accId(account)])).r;
@@ -216,3 +214,64 @@ function makeAuthCore(S, exec, onSwitch, canSwitch) {
         },
     };
 }
+const argOf = (args, i = 0) => (args[i] !== null && typeof args[i] === 'object' ? args[i] : {});
+/** Аккаунт аргумента: id или { id }. */
+const accOf = (a) => (typeof a === 'string' ? a : a !== null && typeof a === 'object' && typeof a.id === 'string' ? a.id : undefined);
+const loginOf = (v) => (typeof v === 'string' ? { login: v.trim() } : {});
+/** Вход: успех — auth.login (account — вошедший), отказ — auth.fail. */
+function loginEvent(r, method, extra = {}) {
+    const res = r;
+    const detail = { method, ...extra };
+    return res && typeof res === 'object' ? { event: 'auth.login', account: res.account, detail } : { event: 'auth.fail', detail };
+}
+const credential = (action, detail) => ({ event: 'auth.credential', detail: { action, ...detail } });
+const call = (method, detail = {}) => ({ event: 'auth.call', detail: { method, ...detail } });
+/** Что пишет в лог каждый метод db.auth. */
+export const AUTH_LOG = {
+    setPassword: (args, id) => {
+        const a = argOf(args);
+        return credential('setPassword', { account: accOf(a.account), kind: a.kind ?? 'PASSWORD', ...loginOf(a.identifier), id });
+    },
+    verifyPassword: (args, r) => {
+        const a = argOf(args);
+        return loginEvent(r, String(a.kind ?? 'PASSWORD'), { ...loginOf(a.identifier), ...(a.totp != null ? { totp: true } : {}) });
+    },
+    issueApiKey: (args, r) => credential('issueApiKey', { account: accOf(argOf(args).account), name: argOf(args).name, id: r?.id }),
+    verifyApiKey: (_args, r) => loginEvent(r, 'APIKEY'),
+    issueKeySecret: (args, r) => credential('issueKeySecret', { account: accOf(argOf(args).account), name: argOf(args).name, id: r?.id }),
+    verifyKeySecret: (_args, r) => loginEvent(r, 'KEYSECRET'),
+    enrollTotp: (args) => credential('enrollTotp', { account: accOf(argOf(args).account) }),
+    verifyTotp: (args, ok) => (ok === true
+        ? call('verifyTotp', { account: accOf(argOf(args).account), ok: true })
+        : { event: 'auth.fail', detail: { method: 'TOTP', account: accOf(argOf(args).account) } }),
+    totpEnabled: (args, r) => call('totpEnabled', { account: accOf(args[0]), enabled: r }),
+    issueOtp: (args) => {
+        const a = argOf(args);
+        return credential('issueOtp', { account: accOf(a.account), kind: a.kind ?? 'OTP', ...loginOf(a.identifier) });
+    },
+    verifyOtp: (args, r) => {
+        const a = argOf(args);
+        return loginEvent(r, String(a.kind ?? 'OTP'), loginOf(a.identifier));
+    },
+    link: (args, id) => {
+        const a = argOf(args);
+        return credential('link', { account: accOf(a.account), kind: a.kind, ...loginOf(a.identifier), id });
+    },
+    lookup: (args, r) => {
+        const a = argOf(args);
+        return loginEvent(r, String(a.kind), { ...loginOf(a.identifier), ...(a.totp != null ? { totp: true } : {}) });
+    },
+    credentials: (args, r) => ({ ...call('credentials', { account: accOf(args[0]) }), rows: Array.isArray(r) ? r.length : undefined }),
+    revokeCredential: (args, ok) => ({ event: 'auth.revoke', detail: { target: 'credential', id: args[0], ok } }),
+    setFlags: (args, ok) => credential('setFlags', { id: args[0], ...argOf(args, 1), ok }),
+    sessionFor: (args) => ({ event: 'auth.session', detail: { account: accOf(args[0]), method: 'SERVICE' } }),
+    session: (_args, r) => call('session', { found: r !== null }),
+    refresh: () => call('refresh'),
+    revoke: (args, ok) => (args[0] !== undefined
+        ? { event: 'auth.revoke', detail: { target: 'token', ok } }
+        : { event: 'auth.logout', detail: { ok } }),
+    revokeAll: (args, n) => ({ event: 'auth.revoke', detail: { target: 'all', account: accOf(args[0]), n } }),
+    switch: (args, _r, before) => ({ event: 'auth.switch', tenant: String(args[0]), detail: { from: before } }),
+    tenants: (_args, r) => ({ ...call('tenants'), rows: Array.isArray(r) ? r.length : undefined }),
+    purgeAccount: (args, r) => ({ event: 'account.purge', detail: { account: accOf(args[0]), ...r } }),
+};

package/dist/cache.d.ts

@@ -68,6 +68,13 @@ export declare class ResultCache {
     }): string;
     /** Снимок счётчиков классов, пар с арендатором запроса (id) и сессии — до запроса. */
     token(classes: readonly string[], session: string, tenantId?: string | null): CacheToken;
+    /**
+     * Счётчик сессии заводит снимок запроса (token), а сигнал о гашении меняет только заведённые: снимок в полёте бывает
+     * лишь у сессии, которая читала через этот кэш. Гасят же в основном чужие сессии — вход и выход пользователей
+     * сервиса, — и счётчик на каждый тег копил бы карту до предела EPOCH_MAX (долгий прогон: вход и выход раз в секунду —
+     * 0,7–0,9 МБ/ч на подключение). Заведённый счётчик не удаляется: иначе снимок, взятый до гашения, сошёлся бы с нулём.
+     */
+    private watchSession;
     private pairCount;
     get(key: string): unknown[] | undefined;
     /** Положить ответ, если с момента снимка не было сигналов о его классах и сессии. */
@@ -76,7 +83,7 @@ export declare class ResultCache {
     invalidate(classes: Iterable<string>): void;
     /** Сбросить ответы класса в арендаторе (токен) и ответы без арендатора; null — во всех. */
     private invalidateIn;
-    /** Сбросить ответы сессии (тег — начало sha256 токена). */
+    /** Сбросить ответы сессии (тег — начало sha256 токена); счётчик — только у заведённой снимком (watchSession). */
     invalidateSession(tag: string): void;
     /**
      * Счётчик сигналов по ключу (класс, пара «класс, арендатор», сессия). Ключи приходят в нагрузке сигнала, а её

package/dist/cache.js

@@ -5,13 +5,14 @@
  * Ключ — текст запроса, параметры и тот, кто спрашивает (токен, актор, арендатор): под RLS один
  * запрос разным пользователям отдаёт разные строки. Сброс:
  *   - свои записи — сразу после фиксации, по классам из letopis.changed (туда попадают и классы
- *     каскада, unset, смены класса и ключа); запись через db.sql — весь кэш;
+ *     каскада и unset); запись через db.sql — весь кэш;
  *   - чужие записи — по сигналу базы (нагрузка по режиму установки, signals.ts): класс в арендаторе
  *     сигнала (ответ помнит токен арендатора запроса; сигнал System и процесс без ключа — во всех), в режиме
- *     opaque без ключа — весь кэш; классы прав и схемы (rule, Resource, member, Account, Class) и «*» —
- *     весь кэш; `session:<16 hex>` — ответы погашенной сессии, `session:*` — все;
+ *     opaque без ключа — весь кэш; классы прав и схемы (rule, Resource, member, Account, Class) — весь кэш;
+ *     `session:<16 hex>` — ответы погашенной сессии;
  *   - гонка запроса и сигнала: счётчики сигналов по классам, парам «класс, арендатор» и сессиям
- *     снимаются до запроса, ответ кладётся, только если они не изменились;
+ *     снимаются до запроса, ответ кладётся, только если они не изменились; счётчик сессии заводит сам
+ *     снимок — гашение сессии, которая через кэш не читала, следа в картах не оставляет;
  *   - (пере)подключение слушателя сигналов — весь кэш: сигналы за время обрыва потеряны; без слушателя
  *     кэш выключен (с ttlOnly — работает только по сроку);
  *   - срок (по умолчанию 60 с) — предохранитель; ответы истёкшей сессии не используются.
@@ -63,13 +64,32 @@ export class ResultCache {
     /** Снимок счётчиков классов, пар с арендатором запроса (id) и сессии — до запроса. */
     token(classes, session, tenantId) {
         const tenant = this.allTenants ? null : this.sig.tenantToken(tenantId);
+        // счётчик сессии — до снимка epoch: переполнение карты сдвигает epoch
+        const sessionCount = this.watchSession(session);
         return {
             epoch: this.epoch,
             classes: classes.map((c) => [c, this.classEpoch.get(c) ?? 0, this.pairCount(c, tenant)]),
-            session: this.sessionEpoch.get(session) ?? 0,
+            session: sessionCount,
             tenant,
         };
     }
+    /**
+     * Счётчик сессии заводит снимок запроса (token), а сигнал о гашении меняет только заведённые: снимок в полёте бывает
+     * лишь у сессии, которая читала через этот кэш. Гасят же в основном чужие сессии — вход и выход пользователей
+     * сервиса, — и счётчик на каждый тег копил бы карту до предела EPOCH_MAX (долгий прогон: вход и выход раз в секунду —
+     * 0,7–0,9 МБ/ч на подключение). Заведённый счётчик не удаляется: иначе снимок, взятый до гашения, сошёлся бы с нулём.
+     */
+    watchSession(tag) {
+        const n = this.sessionEpoch.get(tag);
+        if (n !== undefined)
+            return n;
+        if (this.sessionEpoch.size >= EPOCH_MAX) {
+            this.sessionEpoch.clear();
+            this.epoch++;
+        }
+        this.sessionEpoch.set(tag, 0);
+        return 0;
+    }
     pairCount(cls, tenant) {
         return (tenant === null ? this.anyEpoch.get(cls) : this.pairEpoch.get(`${cls}@${tenant}`)) ?? 0;
     }
@@ -126,9 +146,11 @@ export class ResultCache {
             if ((e.tenant === null || e.tenant === tenant) && e.classes.includes(cls))
                 this.map.delete(key);
     }
-    /** Сбросить ответы сессии (тег — начало sha256 токена). */
+    /** Сбросить ответы сессии (тег — начало sha256 токена); счётчик — только у заведённой снимком (watchSession). */
     invalidateSession(tag) {
-        this.bump(this.sessionEpoch, tag);
+        const n = this.sessionEpoch.get(tag);
+        if (n !== undefined)
+            this.sessionEpoch.set(tag, n + 1);
         for (const [k, e] of this.map)
             if (e.session === tag)
                 this.map.delete(k);
@@ -161,7 +183,7 @@ export class ResultCache {
                 // класса нет в реестрах процесса — и ответов с ним нет
                 return;
             default:
-                // *, session:*, opaque без ключа, нагрузка не по режиму
+                // переподключение слушателя, opaque без ключа, нагрузка не по режиму
                 return this.clear();
         }
     }