letopis 0.16.0 → 0.18.1

package/dist/acl.js

@@ -1,5 +1,12 @@
 export const ACL_OPS = ['READ', 'WRITE', 'DELETE'];
 // --- матчеры -----------------------------------------------------------------
+// START_CONTRACT: matchCategories
+//   PURPOSE: Проверить шаблон pattern.categories ("{A,B}" | "!{A,B}" | NULL) против категорий аккаунта.
+//   INPUTS: { pattern: object|null - шаблон ресурса ACCOUNT; cats: string[] - категории аккаунта }
+//   OUTPUTS: { boolean - подходит ли субъект }
+//   SIDE_EFFECTS: none
+//   LINKS: M-ACL, V-M-ACL
+// END_CONTRACT: matchCategories
 /** pattern.categories: "{A,B}" | "!{A,B}" | отсутствие/NULL (матч всех). */
 export function matchCategories(pattern, cats) {
     const spec = pattern?.categories;
@@ -16,8 +23,16 @@ export function matchCategories(pattern, cats) {
     const hit = list.some((c) => cats.includes(c));
     return neg ? !hit : hit;
 }
+// START_CONTRACT: maskBody
+//   PURPOSE: Скомпилировать тело маски в regex-фрагмент: '{a,b}' → альтернативы (рекурсивно), '*' → хвост из 1+ сегментов.
+//   INPUTS: { mask: string - маска с '.'-сегментами }
+//   OUTPUTS: { string - regex-исходник без якорей }
+//   SIDE_EFFECTS: none
+//   LINKS: M-ACL, V-M-ACL
+// END_CONTRACT: maskBody
 /** Маска → regex: '{a,b}' — альтернативы (рекурсивно), '*' — хвост из 1+ сегментов. */
 function maskBody(mask) {
+    // START_BLOCK_MASK_COMPILE
     let out = '';
     for (let i = 0; i < mask.length; i++) {
         const ch = mask[i];
@@ -58,9 +73,17 @@ function maskBody(mask) {
             out += ch;
         }
     }
+    // END_BLOCK_MASK_COMPILE
     return out;
 }
 const regexCache = new Map();
+// START_CONTRACT: matchMask
+//   PURPOSE: Сопоставить значение с маской, кэшируя скомпилированный RegExp.
+//   INPUTS: { mask: string; value: string }
+//   OUTPUTS: { boolean }
+//   SIDE_EFFECTS: заполняет regexCache
+//   LINKS: M-ACL, V-M-ACL
+// END_CONTRACT: matchMask
 export function matchMask(mask, value) {
     let re = regexCache.get(mask);
     if (!re) {
@@ -123,8 +146,16 @@ function rowFilter(r, account) {
         return undefined;
     return Object.fromEntries(rest.map(([k, v]) => [k, substitute(v, account)]));
 }
+// START_CONTRACT: decide
+//   PURPOSE: Выбрать РОВНО ОДНО победившее правило: max weight; при равенстве deny бьёт allow, равные allow — по alias ресурса.
+//   INPUTS: { rules: Rule[]; subjects: Set<string> - alias'ы субъекта; objects: Map<string,Resource> - применимые ресурсы }
+//   OUTPUTS: { { winner?: Rule } }
+//   SIDE_EFFECTS: none
+//   LINKS: M-ACL, V-M-ACL
+// END_CONTRACT: decide
 /** Победитель: max weight; равный вес — deny бьёт allow, равные allow — по alias объекта. */
 function decide(rules, subjects, objects) {
+    // START_BLOCK_DECIDE_WINNER
     let winner;
     for (const rule of rules) {
         if (!rule.enabled || !subjects.has(rule.account) || !objects.has(rule.resource))
@@ -141,8 +172,16 @@ function decide(rules, subjects, objects) {
             winner = rule;
         }
     }
+    // END_BLOCK_DECIDE_WINNER
     return { winner };
 }
+// START_CONTRACT: toDecision
+//   PURPOSE: Превратить победителя в AclDecision (allow + остаточный row-фильтр | deny + code/message | deny-by-default).
+//   INPUTS: { winner?: Rule; objects: Map<string,Resource>; account: string }
+//   OUTPUTS: { AclDecision }
+//   SIDE_EFFECTS: none
+//   LINKS: M-ACL, V-M-ACL, type-AclDecision
+// END_CONTRACT: toDecision
 function toDecision(winner, objects, account) {
     if (!winner)
         return { allow: false, message: 'no matching rule (deny by default)' };
@@ -158,6 +197,13 @@ function toDecision(winner, objects, account) {
 const subjectAliases = (resources, cats) => new Set(resources.filter((r) => r.category === 'ACCOUNT' && matchCategories(r.pattern, cats)).map((r) => r.alias));
 const toMap = (rs) => new Map(rs.map((r) => [r.alias, r]));
 const accId = (a) => (typeof a === 'object' ? a.id : a);
+// START_CONTRACT: makeAcl
+//   PURPOSE: Построить рантайм-фасад AclApi (check по эндпоинту / checkData по классу+op / reload) с кэшом Resource/Rule.
+//   INPUTS: { tables: Tables; registry: Registry }
+//   OUTPUTS: { AclApi }
+//   SIDE_EFFECTS: лениво читает resources/rules через tables (кэш до reload())
+//   LINKS: M-ACL, V-M-ACL
+// END_CONTRACT: makeAcl
 export function makeAcl(tables, registry) {
     let cache = null;
     const load = () => (cache ??= (async () => ({
@@ -185,8 +231,16 @@ export function makeAcl(tables, registry) {
     };
 }
 // --- enforce-компилятор (connect({enforceAcl: true})) ----------------------------
+// START_CONTRACT: compileEnforcer
+//   PURPOSE: Скомпилировать синхронный энфорсер (ClassDef, op) → AclDecision с мемоизацией — субъект и правила зафиксированы на connect.
+//   INPUTS: { src: AclSource; account: string; cats: string[]; registry: Registry }
+//   OUTPUTS: { (cls: ClassDef, op: AclOp) => AclDecision }
+//   SIDE_EFFECTS: none (мемо-кэш решений)
+//   LINKS: M-ACL, V-M-ACL, M-SQL, M-WRITE
+// END_CONTRACT: compileEnforcer
 /** Синхронный резолвер для цепочек: категории субъекта и правила зафиксированы на connect. */
 export function compileEnforcer(src, account, cats, registry) {
+    // START_BLOCK_ENFORCER_MEMO
     const subjects = subjectAliases(src.resources, cats);
     const memo = new Map();
     return (cls, op) => {
@@ -202,6 +256,14 @@ export function compileEnforcer(src, account, cats, registry) {
         return d;
     };
 }
+// END_BLOCK_ENFORCER_MEMO
+// START_CONTRACT: aclDenied
+//   PURPOSE: Собрать читаемую Error отказа ACL для цепочек (её бросают вызывающие sql/write).
+//   INPUTS: { op: AclOp; clsId: string; d: AclDecision }
+//   OUTPUTS: { Error }
+//   SIDE_EFFECTS: none (возвращает Error, не бросает)
+//   LINKS: M-ACL, V-M-ACL
+// END_CONTRACT: aclDenied
 /** Читаемая ошибка отказа для цепочек. */
 export function aclDenied(op, clsId, d) {
     return new Error(`letopis: acl denies ${op} on ${clsId}${d.message ? ` — ${d.message}` : ''}`);

package/dist/auth.d.ts

@@ -1,3 +1,10 @@
+/**
+ * db.auth: вход по таблице Credential — на аккаунт много способов:
+ * пароль (логин/почта), api-ключ, ключ-секрет, внешние identity (oauth/sso/telegram).
+ * Пароли — scrypt (node:crypto, без зависимостей); ключи/секреты — в БД только sha256.
+ * Однозначность входа даёт credential_identity_udx: один живой кред на (category, identifier).
+ * OAuth-танец, rate-limit, lockout — на приложении: здесь хранение и проверка.
+ */
 import type { Account, Credential } from './types.js';
 import type { Tables } from './tables.js';
 import { type SessionStore, type Sessions } from './sessions.js';

package/dist/auth.js

@@ -5,6 +5,27 @@
  * Однозначность входа даёт credential_identity_udx: один живой кред на (category, identifier).
  * OAuth-танец, rate-limit, lockout — на приложении: здесь хранение и проверка.
  */
+// 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 { promisify } from 'node:util';
 import { makeSessions } from './sessions.js';
@@ -13,11 +34,26 @@ const scryptAsync = promisify(scrypt);
 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) {
     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) {
     const [algo, N, r, p, saltB64, hashB64] = stored.split('$');
     if (algo !== 'scrypt')
@@ -30,6 +66,7 @@ async function verifyHash(password, stored) {
 }
 /** Выравнивание времени ответа: «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');
@@ -41,6 +78,7 @@ const eqStr = (a, b) => {
     return ba.length === bb.length && timingSafeEqual(ba, bb);
 };
 // --- TOTP (RFC 6238 / HOTP RFC 4226) ---------------------------------------
+// START_BLOCK_TOTP
 const B32 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
 function base32Encode(buf) {
     let bits = 0;
@@ -58,6 +96,13 @@ 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) {
     let bits = 0;
     let value = 0;
@@ -77,6 +122,13 @@ function base32Decode(s) {
 }
 const TOTP_PERIOD = 30; // секунд на шаг (стандарт authenticator-приложений)
 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) {
     const buf = Buffer.alloc(8);
     buf.writeBigUInt64BE(BigInt(counter));
@@ -87,11 +139,25 @@ function hotp(secret, counter) {
 }
 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;
@@ -105,6 +171,13 @@ export function makeAuth(tables) {
         return { account, credential: cred };
     }
     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),
@@ -114,6 +187,13 @@ export function makeAuth(tables) {
                 confirmed: a.confirmed,
             });
         },
+        // 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;
@@ -125,6 +205,14 @@ export function makeAuth(tables) {
                 return null;
             return finalize(cred, a);
         },
+        // 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({
@@ -135,6 +223,13 @@ export function makeAuth(tables) {
             });
             return { key, credential };
         },
+        // 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;
@@ -157,6 +252,14 @@ export function makeAuth(tables) {
                 return null;
             return finalize(cred, opts);
         },
+        // 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));
@@ -174,6 +277,13 @@ export function makeAuth(tables) {
             });
             return { secret, uri, credential };
         },
+        // 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];
@@ -204,6 +314,14 @@ export function makeAuth(tables) {
             const cred = (await tables.credentials.find({ account: accId(account), category: 'TOTP' }))[0];
             return cred?.confirmed === true;
         },
+        // 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');
@@ -220,6 +338,13 @@ export function makeAuth(tables) {
             });
             return { code, credential };
         },
+        // 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)
@@ -245,6 +370,7 @@ export function makeAuth(tables) {
             await tables.credentials.delete(cred.id); // одноразовость: успех сжигает код
             return finalize(cred, {});
         },
+        // END_BLOCK_OTP
         async link(a) {
             return tables.credentials.set({
                 account: accId(a.account),