letopis 0.21.0 → 1.0.1

package/dist/auth.js

@@ -1,86 +1,39 @@
 /**
- * db.auth: вход по таблице Credential — на аккаунт много способов:
- * пароль (логин/почта), api-ключ, ключ-секрет, внешние identity (oauth/sso/telegram).
- * Пароли — scrypt (node:crypto, без зависимостей); ключи/секреты — в БД только sha256.
- * Однозначность входа даёт credential_identity_udx: один живой кред на (category, identifier).
- * OAuth-танец, rate-limit, lockout — на приложении: здесь хранение и проверка.
+ * db.auth — креды, вход и сессии (план, §2.9, этап 5, п. 1–4). Всё хранится в таблице secret, к
+ * которой у приложения нет доступа: библиотека вызывает функции базы (80-auth.sql), а они проверяют
+ * права (auth.* — по правилам System: сервис, системный администратор; свои креды аккаунт привязывает
+ * сам после недавнего входа).
+ *
+ * Пароли — scrypt в Node (как в 0.21): база хранит готовый хэш и отдаёт его только сервису с правом
+ * auth.password; проверку для несуществующего идентификатора выравнивает по времени холостой scrypt.
+ * Ключи API, пары ключ + секрет, одноразовые коды и TOTP проверяет база. Успешный вход — новая
+ * сессия: { account, token }.
  */
-// FILE: lib/src/auth.ts
-// VERSION: 1.0.0
-// START_MODULE_CONTRACT
-//   PURPOSE: Жизненный цикл и проверка кредов аккаунта — пароли (scrypt), api-ключи, ключ+секрет, TOTP, OTP, внешние identity — плюс выдача сессий.
-//   SCOPE: makeAuth (AuthApi) + totpCode + локальные крипто-хелперы (hashPassword/verifyHash/base32Encode/base32Decode/hotp)
-//   DEPENDS: M-TYPES, M-TABLES, M-SESSIONS
-//   LINKS: M-AUTH, V-M-AUTH
-//   ROLE: RUNTIME
-//   MAP_MODE: EXPORTS
-// END_MODULE_CONTRACT
-//
-// START_MODULE_MAP
-//   totpCode - TOTP-код authenticator-а для base32-секрета на момент времени (хелпер для тестов/сервисов)
-//   AuthResult - успешный вход: аккаунт + конкретный кред
-//   AuthApi - контракт всех способов входа (пароль/api-ключ/ключ-секрет/TOTP/OTP/identity) + выдача сессий
-//   makeAuth - фабрика AuthApi поверх Tables
-// END_MODULE_MAP
-//
-// START_CHANGE_SUMMARY
-//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
-// END_CHANGE_SUMMARY
-import { createHash, createHmac, randomBytes, randomInt, scrypt, timingSafeEqual } from 'node:crypto';
+import { createHmac, randomBytes, scrypt, timingSafeEqual } from 'node:crypto';
 import { promisify } from 'node:util';
-import { makeSessions } from './sessions.js';
+import { LetopisError, removed } from './errors.js';
 const scryptAsync = promisify(scrypt);
-// OWASP-порядок стойкости; maxmem с запасом (128*N*r байт впритык к дефолтным 32MiB)
 const SCRYPT = { N: 32768, r: 8, p: 1, maxmem: 64 * 1024 * 1024 };
 const KEYLEN = 32;
-const sha256 = (s) => createHash('sha256').update(s).digest('hex');
-// START_BLOCK_SCRYPT_HASH
-// START_CONTRACT: hashPassword
-//   PURPOSE: Захэшировать пароль scrypt-ом со случайной солью в самодостаточную строку.
-//   INPUTS: { password: string - открытый пароль }
-//   OUTPUTS: { Promise<string> - строка `scrypt$N$r$p$saltB64$hashB64` }
-//   SIDE_EFFECTS: none (CSPRNG-соль, scrypt-KDF)
-//   LINKS: M-AUTH, V-M-AUTH
-// END_CONTRACT: hashPassword
-async function hashPassword(password) {
+/** Хэш пароля scrypt: `scrypt$N$r$p$соль$хэш` (формат 0.21). */
+export async function hashPassword(password) {
     const salt = randomBytes(16);
     const hash = await scryptAsync(password, salt, KEYLEN, SCRYPT);
     return `scrypt$${SCRYPT.N}$${SCRYPT.r}$${SCRYPT.p}$${salt.toString('base64')}$${hash.toString('base64')}`;
 }
-// START_CONTRACT: verifyHash
-//   PURPOSE: Проверить пароль против сохранённого scrypt-хэша в постоянное время.
-//   INPUTS: { password: string - открытый пароль; stored: string - строка формата scrypt$… }
-//   OUTPUTS: { Promise<boolean> - true при совпадении; false для не-scrypt (legacy) форматов }
-//   SIDE_EFFECTS: none (timingSafeEqual — сравнение в постоянное время)
-//   LINKS: M-AUTH, V-M-AUTH
-// END_CONTRACT: verifyHash
-async function verifyHash(password, stored) {
+/** Проверка пароля по хэшу scrypt; другие форматы не проверяются. */
+export async function verifyHash(password, stored) {
     const [algo, N, r, p, saltB64, hashB64] = stored.split('$');
-    if (algo !== 'scrypt')
-        return false; // legacy-форматы (bcrypt из дампа) не верифицируем
+    if (algo !== 'scrypt' || !hashB64)
+        return false;
     const want = Buffer.from(hashB64, 'base64');
-    const got = await scryptAsync(password, Buffer.from(saltB64, 'base64'), want.length, {
-        N: Number(N), r: Number(r), p: Number(p), maxmem: SCRYPT.maxmem,
-    });
-    return timingSafeEqual(got, want);
+    const got = await scryptAsync(password, Buffer.from(saltB64, 'base64'), want.length, { N: Number(N), r: Number(r), p: Number(p), maxmem: SCRYPT.maxmem });
+    return got.length === want.length && timingSafeEqual(got, want);
 }
-/** Выравнивание времени ответа: «identifier не существует» не быстрее «пароль неверен». */
+/** Холостая проверка: «идентификатора нет» отвечает не быстрее, чем «пароль неверен». */
 const dummyVerify = (password) => scryptAsync(password, Buffer.alloc(16), KEYLEN, SCRYPT).then(() => false);
-// END_BLOCK_SCRYPT_HASH
-const eqHex = (a, b) => {
-    const ba = Buffer.from(a, 'hex');
-    const bb = Buffer.from(b, 'hex');
-    return ba.length === bb.length && timingSafeEqual(ba, bb);
-};
-const eqStr = (a, b) => {
-    const ba = Buffer.from(a);
-    const bb = Buffer.from(b);
-    return ba.length === bb.length && timingSafeEqual(ba, bb);
-};
-// --- TOTP (RFC 6238 / HOTP RFC 4226) ---------------------------------------
-// START_BLOCK_TOTP
 const B32 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
-function base32Encode(buf) {
+export function base32Encode(buf) {
     let bits = 0;
     let value = 0;
     let out = '';
@@ -96,21 +49,14 @@ function base32Encode(buf) {
         out += B32[(value << (5 - bits)) & 31];
     return out;
 }
-// START_CONTRACT: base32Decode
-//   PURPOSE: Декодировать base32 (RFC 4648, алфавит A-Z2-7) в байты.
-//   INPUTS: { s: string - base32-строка (хвостовой padding и регистр допустимы) }
-//   OUTPUTS: { Buffer - декодированные байты }
-//   SIDE_EFFECTS: бросает Error 'letopis: invalid base32 TOTP secret' на недопустимый символ
-//   LINKS: M-AUTH, V-M-AUTH
-// END_CONTRACT: base32Decode
-function base32Decode(s) {
+export function base32Decode(s) {
     let bits = 0;
     let value = 0;
     const out = [];
     for (const ch of s.replace(/=+$/, '').toUpperCase()) {
         const idx = B32.indexOf(ch);
         if (idx < 0)
-            throw new Error('letopis: invalid base32 TOTP secret');
+            throw new LetopisError('invalid_data', 'секрет TOTP — не base32');
         value = (value << 5) | idx;
         bits += 5;
         if (bits >= 8) {
@@ -120,270 +66,139 @@ function base32Decode(s) {
     }
     return Buffer.from(out);
 }
-const TOTP_PERIOD = 30; // секунд на шаг (стандарт authenticator-приложений)
+const TOTP_PERIOD = 30;
 const TOTP_DIGITS = 6;
-// START_CONTRACT: hotp
-//   PURPOSE: HOTP (RFC 4226) — HMAC-SHA1 счётчика + dynamic truncation в цифровой код.
-//   INPUTS: { secret: Buffer - общий секрет; counter: number - шаг/счётчик }
-//   OUTPUTS: { string - код из TOTP_DIGITS (6) цифр с ведущими нулями }
-//   SIDE_EFFECTS: none
-//   LINKS: M-AUTH, V-M-AUTH
-// END_CONTRACT: hotp
-function hotp(secret, counter) {
+/** Код приложения-аутентификатора для секрета на момент времени (RFC 6238; помощник для тестов и сервисов). */
+export function totpCode(secretBase32, atMs = Date.now()) {
     const buf = Buffer.alloc(8);
-    buf.writeBigUInt64BE(BigInt(counter));
-    const h = createHmac('sha1', secret).update(buf).digest();
+    buf.writeBigUInt64BE(BigInt(Math.floor(atMs / 1000 / TOTP_PERIOD)));
+    const h = createHmac('sha1', base32Decode(secretBase32)).update(buf).digest();
     const off = h[h.length - 1] & 0xf;
     const code = (((h[off] & 0x7f) << 24) | (h[off + 1] << 16) | (h[off + 2] << 8) | h[off + 3]) % 10 ** TOTP_DIGITS;
     return String(code).padStart(TOTP_DIGITS, '0');
 }
-const totpStep = (atMs) => Math.floor(atMs / 1000 / TOTP_PERIOD);
-/** Код authenticator-а для секрета на момент времени (хелпер для тестов/сервисов). */
-// START_CONTRACT: totpCode
-//   PURPOSE: TOTP-код authenticator-а для base32-секрета на заданный момент времени.
-//   INPUTS: { secretBase32: string - секрет в base32; atMs?: number - момент в мс (default Date.now()) }
-//   OUTPUTS: { string - 6-значный код текущего 30-секундного шага }
-//   SIDE_EFFECTS: none (при отсутствии atMs читает Date.now())
-//   LINKS: M-AUTH, V-M-AUTH
-// END_CONTRACT: totpCode
-export function totpCode(secretBase32, atMs = Date.now()) {
-    return hotp(base32Decode(secretBase32), totpStep(atMs));
-}
-// ---------------------------------------------------------------------------
 const accId = (a) => (typeof a === 'object' ? a.id : a);
-// START_CONTRACT: makeAuth
-//   PURPOSE: Собрать AuthApi поверх Tables — все способы входа + выдача сессий.
-//   INPUTS: { tables: Tables - доступ к таблицам Credential/Account }
-//   OUTPUTS: { AuthApi - методы setPassword/verify*/issue*/enrollTotp/link/lookup/sessions }
-//   SIDE_EFFECTS: none при сборке; методы читают/пишут строки Credential и читают Account через Tables
-//   LINKS: M-AUTH, V-M-AUTH, M-TABLES, M-SESSIONS
-// END_CONTRACT: makeAuth
-export function makeAuth(tables) {
-    /** Живой кред по глобально-уникальной паре (category, identifier). */
-    const findLive = async (category, identifier) => (await tables.credentials.find({ category, identifier }))[0] ?? null;
-    /** Общие ворота: confirmed-кред + enabled-аккаунт. */
-    async function finalize(cred, opts) {
-        if (!cred.confirmed && opts.requireConfirmed !== false)
-            return null;
-        const account = await tables.accounts.get(cred.account);
-        if (!account?.enabled)
+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];
+    };
+    // Вход после первой проверки. Код TOTP проверяет база той же функцией, что verifyTotp (право auth.totp,
+    // окно ±1 шаг, повтор шага, счётчик неудач и блокировка), секрет из базы не выходит; способ TOTP
+    // сессия получает только после удачи. Без кода — сессия без отметки TOTP, как раньше.
+    const login = async (account, ttl, methods, totp) => {
+        if (!account)
             return null;
-        return { account, credential: cred };
-    }
+        if (totp != null) {
+            const v = await one(`select ${S}.auth_verify_totp($1::uuid, $2::text, 1) as ok`, [account, String(totp)]);
+            if (!v.ok)
+                return null;
+            methods = [...methods, 'TOTP'];
+        }
+        const r = await one(`select ${S}.issue_session($1::uuid, coalesce($2::interval, interval '7 days'), $3::text[]) as t`, [account, ttlOf(ttl), methods]);
+        return { account, token: r.t };
+    };
     return {
-        // START_CONTRACT: setPassword
-        //   PURPOSE: Upsert пароля (scrypt) для (account, category, identifier).
-        //   INPUTS: { a: { account: string|{id}, identifier: string, password: string, category?='PASSWORD', confirmed?: boolean } }
-        //   OUTPUTS: { Promise<Credential> - записанный кред }
-        //   SIDE_EFFECTS: пишет строку Credential (meta.password = scrypt-хэш) через Tables
-        //   LINKS: M-AUTH, V-M-AUTH, M-TABLES
-        // END_CONTRACT: setPassword
         async setPassword(a) {
-            return tables.credentials.set({
-                account: accId(a.account),
-                category: a.category ?? 'PASSWORD',
-                identifier: a.identifier,
-                meta: { password: await hashPassword(a.password) },
-                confirmed: a.confirmed,
-            });
+            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]);
+            return r.id;
         },
-        // START_CONTRACT: verifyPassword
-        //   PURPOSE: Проверить identifier+пароль; на miss — dummy-verify для выравнивания времени ответа.
-        //   INPUTS: { a: { identifier: string, password: string, category?='PASSWORD', requireConfirmed?: boolean } }
-        //   OUTPUTS: { Promise<AuthResult|null> - аккаунт+кред при успехе, иначе null }
-        //   SIDE_EFFECTS: читает Credential/Account; при отсутствии креда выполняет dummyVerify (scrypt) для timing-выравнивания
-        //   LINKS: M-AUTH, V-M-AUTH, M-TABLES
-        // END_CONTRACT: verifyPassword
         async verifyPassword(a) {
-            const cred = await findLive(a.category ?? 'PASSWORD', a.identifier);
-            const stored = cred?.meta.password;
-            if (!cred || typeof stored !== 'string') {
-                await dummyVerify(a.password);
+            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];
+            if (!cred)
+                return dummyVerify(a.password).then(() => null);
+            if (!(await verifyHash(a.password, cred.hash)))
                 return null;
-            }
-            if (!(await verifyHash(a.password, stored)))
+            if (!cred.confirmed && a.requireConfirmed !== false)
                 return null;
-            return finalize(cred, a);
+            return login(cred.account, a.ttl, [a.kind ?? 'PASSWORD'], a.totp);
         },
-        // START_BLOCK_APIKEY
-        // START_CONTRACT: issueApiKey
-        //   PURPOSE: Выдать api-ключ `lts_<48hex>` (в БД — только sha256 + префикс).
-        //   INPUTS: { a: { account: string|{id}, name?: string } }
-        //   OUTPUTS: { Promise<{ key: string, credential: Credential }> - ключ отдаётся ОДИН раз }
-        //   SIDE_EFFECTS: пишет Credential (category='APIKEY', identifier=sha256(key), meta.prefix)
-        //   LINKS: M-AUTH, V-M-AUTH, M-TABLES
-        // END_CONTRACT: issueApiKey
         async issueApiKey(a) {
-            const key = `lts_${randomBytes(24).toString('hex')}`;
-            const credential = await tables.credentials.set({
-                account: accId(a.account),
-                category: 'APIKEY',
-                identifier: sha256(key),
-                meta: { name: a.name ?? null, prefix: key.slice(0, 12) },
-            });
-            return { key, credential };
+            return one(`select key, id from ${S}.auth_issue_apikey($1::uuid, $2, $3::interval)`, [accId(a.account), a.name ?? null, ttlOf(a.ttl)]);
         },
-        // START_CONTRACT: verifyApiKey
-        //   PURPOSE: Проверить api-ключ по sha256(key).
-        //   INPUTS: { key: string - api-ключ; opts?: { requireConfirmed?: boolean } }
-        //   OUTPUTS: { Promise<AuthResult|null> }
-        //   SIDE_EFFECTS: читает Credential/Account
-        //   LINKS: M-AUTH, V-M-AUTH, M-TABLES
-        // END_CONTRACT: verifyApiKey
-        async verifyApiKey(key, opts = {}) {
-            const cred = await findLive('APIKEY', sha256(key));
-            return cred ? finalize(cred, opts) : null;
+        async verifyApiKey(key) {
+            return (await one(`select ${S}.auth_login_apikey($1) as r`, [key])).r;
         },
         async issueKeySecret(a) {
-            const key = randomBytes(8).toString('hex');
-            const secret = randomBytes(24).toString('hex');
-            const credential = await tables.credentials.set({
-                account: accId(a.account),
-                category: 'KEYSECRET',
-                identifier: key,
-                meta: { name: a.name ?? null, secret: sha256(secret) },
-            });
-            return { key, secret, credential };
+            return one(`select key, secret, id from ${S}.auth_issue_keysecret($1::uuid, $2)`, [accId(a.account), a.name ?? null]);
         },
-        async verifyKeySecret(key, secret, opts = {}) {
-            const cred = await findLive('KEYSECRET', key);
-            const stored = cred?.meta.secret;
-            if (!cred || typeof stored !== 'string' || !eqHex(sha256(secret), stored))
-                return null;
-            return finalize(cred, opts);
+        async verifyKeySecret(key, secret) {
+            return (await one(`select ${S}.login_keysecret($1, $2) as r`, [key, secret])).r;
         },
-        // END_BLOCK_APIKEY
-        // START_CONTRACT: enrollTotp
-        //   PURPOSE: Завести TOTP-фактор: случайный секрет + otpauth-URI для QR (неподтверждён до первой проверки).
-        //   INPUTS: { a: { account: string|{id}, issuer?: string, label?: string } }
-        //   OUTPUTS: { Promise<{ secret: string, uri: string, credential: Credential }> }
-        //   SIDE_EFFECTS: пишет/перезаписывает Credential (category='TOTP', identifier=id, confirmed=false, meta.secret/lastStep)
-        //   LINKS: M-AUTH, V-M-AUTH, M-TABLES
-        // END_CONTRACT: enrollTotp
         async enrollTotp(a) {
-            const id = accId(a.account);
-            const secret = base32Encode(randomBytes(20));
-            const label = encodeURIComponent(a.label ?? id);
+            const r = await one(`select ${S}.auth_enroll_totp($1::uuid) as s`, [accId(a.account)]);
+            const secret = base32Encode(r.s);
+            const label = encodeURIComponent(a.label ?? accId(a.account));
             const issuer = a.issuer ? `&issuer=${encodeURIComponent(a.issuer)}` : '';
-            const uri = `otpauth://totp/${label}?secret=${secret}${issuer}` +
-                `&algorithm=SHA1&digits=${TOTP_DIGITS}&period=${TOTP_PERIOD}`;
-            // re-enroll перезаписывает секрет и сбрасывает подтверждение
-            const credential = await tables.credentials.set({
-                account: id,
-                category: 'TOTP',
-                identifier: id, // один TOTP-фактор на аккаунт
-                meta: { secret, lastStep: 0 },
-                confirmed: false,
-            });
-            return { secret, uri, credential };
+            return { secret, uri: `otpauth://totp/${label}?secret=${secret}${issuer}&algorithm=SHA1&digits=${TOTP_DIGITS}&period=${TOTP_PERIOD}` };
         },
-        // START_CONTRACT: verifyTotp
-        //   PURPOSE: Проверить 6-значный код в окне ±window; replay использованного шага отбит; первая удача активирует фактор.
-        //   INPUTS: { a: { account: string|{id}, code: string, window?: number=1 } }
-        //   OUTPUTS: { Promise<boolean> - true при валидном коде }
-        //   SIDE_EFFECTS: при успехе пишет Credential (meta.lastStep=s, confirmed=true)
-        //   LINKS: M-AUTH, V-M-AUTH, M-TABLES
-        // END_CONTRACT: verifyTotp
         async verifyTotp(a) {
-            const id = accId(a.account);
-            const cred = (await tables.credentials.find({ account: id, category: 'TOTP' }))[0];
-            const secretB32 = cred?.meta.secret;
-            if (!cred || typeof secretB32 !== 'string')
-                return false;
-            const secret = base32Decode(secretB32);
-            const lastStep = typeof cred.meta.lastStep === 'number' ? cred.meta.lastStep : 0;
-            const now = totpStep(Date.now());
-            const window = a.window ?? 1;
-            for (let s = now - window; s <= now + window; s++) {
-                if (s <= lastStep)
-                    continue; // replay: шаг уже использован
-                if (!eqStr(a.code, hotp(secret, s)))
-                    continue;
-                await tables.credentials.set({
-                    account: id,
-                    category: 'TOTP',
-                    identifier: cred.identifier,
-                    meta: { ...cred.meta, lastStep: s },
-                    confirmed: true, // первая успешная проверка активирует фактор
-                });
-                return true;
-            }
-            return false;
+            return (await one(`select ${S}.auth_verify_totp($1::uuid, $2, $3) as ok`, [accId(a.account), a.code, a.window ?? 1])).ok;
         },
         async totpEnabled(account) {
-            const cred = (await tables.credentials.find({ account: accId(account), category: 'TOTP' }))[0];
-            return cred?.confirmed === true;
+            return (await one(`select ${S}.auth_totp_enabled($1::uuid) as ok`, [accId(account)])).ok;
         },
-        // START_BLOCK_OTP
-        // START_CONTRACT: issueOtp
-        //   PURPOSE: Выдать одноразовый код (в БД sha256 + TTL + счётчик попыток); доставка — на приложении.
-        //   INPUTS: { a: { account: string|{id}, identifier: string, category?='OTP', ttlSec?=600, digits?=6 } }
-        //   OUTPUTS: { Promise<{ code: string, credential: Credential }> - код отдаётся один раз }
-        //   SIDE_EFFECTS: пишет/перезаписывает Credential (meta.code=sha256, expires, attempts=0)
-        //   LINKS: M-AUTH, V-M-AUTH, M-TABLES
-        // END_CONTRACT: issueOtp
         async issueOtp(a) {
-            const digits = a.digits ?? 6;
-            const code = String(randomInt(0, 10 ** digits)).padStart(digits, '0');
-            // повторный issue на тот же identifier перезаписывает код (валиден только последний)
-            const credential = await tables.credentials.set({
-                account: accId(a.account),
-                category: a.category ?? 'OTP',
-                identifier: a.identifier,
-                meta: {
-                    code: sha256(code),
-                    expires: new Date(Date.now() + (a.ttlSec ?? 600) * 1000).toISOString(),
-                    attempts: 0,
-                },
-            });
-            return { code, credential };
+            const r = await one(`select ${S}.auth_issue_otp($1::uuid, $2, $3, coalesce($4::interval, interval '10 minutes'), $5, $6) as c`, [accId(a.account), a.identifier, a.kind ?? 'OTP', ttlOf(a.ttl), a.digits ?? 6, a.maxAttempts ?? 5]);
+            return { code: r.c };
         },
-        // START_CONTRACT: verifyOtp
-        //   PURPOSE: Проверить одноразовый код; успех и перебор попыток (maxAttempts) сжигают код.
-        //   INPUTS: { a: { identifier: string, code: string, category?='OTP', maxAttempts?=5 } }
-        //   OUTPUTS: { Promise<AuthResult|null> }
-        //   SIDE_EFFECTS: читает Credential; удаляет кред при успехе/просрочке/переборе, иначе инкрементит meta.attempts
-        //   LINKS: M-AUTH, V-M-AUTH, M-TABLES
-        // END_CONTRACT: verifyOtp
         async verifyOtp(a) {
-            const cred = await findLive(a.category ?? 'OTP', a.identifier);
-            if (!cred)
-                return null;
-            const { code, expires, attempts } = cred.meta;
-            if (typeof code !== 'string' || !expires || Date.parse(expires) < Date.now()) {
-                await tables.credentials.delete(cred.id);
-                return null;
-            }
-            if (!eqHex(sha256(a.code), code)) {
-                const n = (attempts ?? 0) + 1;
-                if (n >= (a.maxAttempts ?? 5))
-                    await tables.credentials.delete(cred.id); // перебор — код сожжён
-                else
-                    await tables.credentials.set({
-                        account: cred.account,
-                        category: cred.category,
-                        identifier: cred.identifier,
-                        meta: { ...cred.meta, attempts: n },
-                    });
-                return null;
-            }
-            await tables.credentials.delete(cred.id); // одноразовость: успех сжигает код
-            return finalize(cred, {});
+            return (await one(`select ${S}.login_otp($1, $2, $3) as r`, [a.identifier, a.code, a.kind ?? 'OTP'])).r;
         },
-        // END_BLOCK_OTP
         async link(a) {
-            return tables.credentials.set({
-                account: accId(a.account),
-                category: a.category,
-                identifier: a.identifier,
-                meta: a.meta ?? {},
-                confirmed: a.confirmed,
-            });
+            return (await one(`select ${S}.auth_link($1::uuid, $2, $3, $4::jsonb, $5) as id`, [accId(a.account), a.kind, a.identifier, (a.meta ?? {}), a.confirmed ?? false])).id;
         },
         async lookup(a) {
-            const cred = await findLive(a.category, a.identifier);
-            return cred ? finalize(cred, a) : null;
+            const r = await one(`select ${S}.auth_lookup($1, $2, $3) as a`, [a.kind, a.identifier, a.requireConfirmed ?? true]);
+            return login(r.a, a.ttl, [a.kind], a.totp);
+        },
+        async credentials(account) {
+            return exec.run((q) => q.unsafe(`select * from ${S}.auth_credentials($1::uuid)`, [accId(account)]));
+        },
+        async revokeCredential(id, opts) {
+            return (await one(`select ${S}.auth_revoke_credential($1::uuid, $2) as ok`, [id, opts?.keepCurrent ?? true])).ok;
+        },
+        async setFlags(id, flags) {
+            return (await one(`select ${S}.auth_set_flags($1::uuid, $2, $3) as ok`, [id, flags.confirmed ?? null, flags.enabled ?? null])).ok;
+        },
+        async sessionFor(account, opts) {
+            return (await login(accId(account), opts?.ttl, ['SERVICE'])).token;
+        },
+        async refresh(opts) {
+            return (await one(`select ${S}.auth_refresh(coalesce($1::interval, interval '7 days')) as e`, [ttlOf(opts?.ttl)])).e;
+        },
+        async revoke() {
+            return (await one(`select ${S}.auth_logout() as ok`)).ok;
+        },
+        async revokeAll(account) {
+            return (await one(`select ${S}.auth_logout_all($1::uuid) as n`, [account === undefined ? null : accId(account)])).n;
+        },
+        async switch(tenant) {
+            if (!canSwitch)
+                throw new LetopisError('invalid_query', 'auth.switch() — от корня подключения: при имперсонации арендатора задаёт db.as(…, { tenant })');
+            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 }));
+        },
+        async purgeAccount(account) {
+            return (await one(`select ${S}.account_purge($1::uuid) as r`, [accId(account)])).r;
         },
-        sessions: makeSessions,
     };
 }

package/dist/cache.d.ts

@@ -0,0 +1,73 @@
+/** Классы, строки которых меняют права и схему: их сигнал сбрасывает весь кэш. */
+export declare const ACL_CLASSES: ReadonlySet<string>;
+export interface CacheOptions {
+    /** Срок ответа по умолчанию, секунды (60). */
+    ttl?: number;
+    /** Работать без слушателя сигналов — только по сроку (пул в режиме транзакций, §2.12). */
+    ttlOnly?: boolean;
+    /** Не больше ответов в памяти (10 000): старые вытесняются. */
+    max?: number;
+}
+export interface CacheStats {
+    size: number;
+    hits: number;
+    misses: number;
+    stores: number;
+    /** Ответ не положен: за время запроса пришёл сигнал о его классах или сессии. */
+    raced: number;
+    /** Получено сигналов. */
+    signals: number;
+    /** (Пере)подключений слушателя. */
+    listens: number;
+    /** Кэш работает: слушатель сигналов на месте (или ttlOnly). */
+    enabled: boolean;
+}
+/** Снимок счётчиков до запроса: ответ кладётся, только если они не изменились. */
+export interface CacheToken {
+    epoch: number;
+    classes: [string, number][];
+    session: number;
+}
+/** Начало sha256 токена — так база называет сессию в сигнале session:<16 hex>. */
+export declare const sessionTag: (token: string | null) => string;
+export declare class ResultCache {
+    private map;
+    private classEpoch;
+    private sessionEpoch;
+    private epoch;
+    private listening;
+    private st;
+    readonly ttlMs: number;
+    readonly ttlOnly: boolean;
+    private max;
+    constructor(opts?: CacheOptions);
+    /** Кэш работает: слушатель на месте или режим только по сроку. */
+    get enabled(): boolean;
+    /** Ключ ответа: запрос, параметры и тот, кто спрашивает. */
+    key(text: string, params: unknown[], who: {
+        token: string | null;
+        account?: string;
+        tenant?: string | null;
+    }): string;
+    /** Снимок счётчиков классов и сессии — до запроса. */
+    token(classes: readonly string[], session: string): CacheToken;
+    get(key: string): unknown[] | undefined;
+    /** Положить ответ, если с момента снимка не было сигналов о его классах и сессии. */
+    set(key: string, value: unknown[], classes: readonly string[], session: string, tok: CacheToken, ttlMs: number, sessionExpires: number | null): boolean;
+    /** Сбросить ответы, читавшие эти классы. */
+    invalidate(classes: Iterable<string>): void;
+    /** Сбросить ответы сессии (тег — начало sha256 токена). */
+    invalidateSession(tag: string): void;
+    /** Весь кэш. */
+    clear(): void;
+    /**
+     * Имена из сигнала или из letopis.changed своей транзакции: классы, `*`, `session:<тег>`,
+     * `session:*`. raw — запись через db.sql: весь кэш.
+     */
+    changed(names: Iterable<string>, raw?: boolean): void;
+    /** Сигнал от базы. */
+    signal(name: string): void;
+    /** Слушатель (пере)подключился: сигналы за время обрыва потеряны — весь кэш. */
+    listen(): void;
+    stats(): CacheStats;
+}