letopis 0.20.3 → 1.0.0

package/dist/admin.js

@@ -0,0 +1,170 @@
+import { LetopisError } from './errors.js';
+import { runTx } from './tx.js';
+import { CHAIN_METHODS, DB_METHODS } from './types.js';
+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;
+}
+/** Ключ advisory-блокировки обслуживания: форма с двумя int4, своё пространство (19541). */
+const MAINTAIN_LOCK = (schema) => [19541, schema];
+/**
+ * Обслуживание: истёкшие сессии и коды, прореживание журнала пачками (каждая — своя транзакция,
+ * долгих блокировок нет), заполнение очереди сигналов. Из нескольких процессов работает один: пачка
+ * первым делом берёт транзакционную advisory-блокировку (pg_try_advisory_xact_lock), и та снимается
+ * с фиксацией пачки. Сеансовая блокировка за пулом в режиме транзакций (PgBouncer) оставалась бы на
+ * серверном соединении, которое пул отдаёт другим клиентам, — и обслуживание молча вставало бы
+ * (skipped у всех). Блокировку держит другой процесс: до первой пачки — skipped; между пачками —
+ * вызов останавливается (продолжит тот процесс), отчёт — о сделанном, more: true.
+ */
+export async function maintain(a, opts = {}) {
+    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 [k1, k2] = MAINTAIN_LOCK(a.schema);
+    const max = opts.batches ?? 100;
+    for (let i = 0; i < max; i++) {
+        // блокировка и пачка — одним оператором: case вычисляет maintain() только при взятой блокировке
+        const [{ r }] = await runTx(a.txc, (q) => q.unsafe(`select case when pg_try_advisory_xact_lock($1::int, hashtext($2::text))
+        then ${a.S}.maintain($3::text::timestamptz, $4::int) end as r`, [k1, k2, now, opts.limit ?? 10_000]));
+        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;
+    }
+    const warn = queueWarning(report.queue);
+    if (warn)
+        console.warn(warn);
+    return report;
+}
+/** Предупреждение о заполненной очереди сигналов (§2.12): больше половины — зависший слушатель. */
+export function queueWarning(queue) {
+    return queue > 0.5 ? `letopis: очередь сигналов PostgreSQL заполнена на ${(queue * 100).toFixed(0)} % — проверьте зависших слушателей` : null;
+}
+/** Интервал расписания: число мс или '30s', '15m', '1h', '1d'. */
+export function parseInterval(v) {
+    if (typeof v === 'number')
+        return v;
+    const m = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$/.exec(v.trim());
+    if (!m)
+        throw new LetopisError('invalid_data', `интервал ${v}: число мс или '30s', '15m', '1h', '1d'`);
+    const n = Number(m[1]);
+    return n * { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]];
+}
+/** Запуск maintain() по расписанию (connect({ maintain: '1h' })): ошибки — предупреждением. */
+export function scheduleMaintain(run, every) {
+    const ms = parseInterval(every);
+    let busy = false;
+    const timer = setInterval(() => {
+        if (busy)
+            return;
+        busy = true;
+        run().catch((e) => console.warn(`letopis: maintain по расписанию: ${e.message}`)).finally(() => (busy = false));
+    }, ms);
+    timer.unref?.();
+    return () => clearInterval(timer);
+}
+/**
+ * Сброс (этап 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;
+}
+/** Машинное описание модели арендатора вместе с метаданными классов (этап 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 ?? []),
+        ends: c.ends,
+        key: c.key,
+        history: c.history,
+        ownerDefault: c.ownerDefault,
+        ...(c.cache ? { cache: c.cache } : {}),
+        meta: c.meta,
+    })).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 } };
+}
+/** Описание модели текстом для языковых моделей (llms.txt). */
+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(', ')}`);
+        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(', ')}`);
+        out.push('');
+    }
+    return out.join('\n');
+}

package/dist/auth.d.ts

@@ -1,123 +1,170 @@
-/**
- * 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';
-/** Код authenticator-а для секрета на момент времени (хелпер для тестов/сервисов). */
+import type { Executor } from './tx.js';
+/** Хэш пароля scrypt: `scrypt$N$r$p$соль$хэш` (формат 0.21). */
+export declare function hashPassword(password: string): Promise<string>;
+/** Проверка пароля по хэшу scrypt; другие форматы не проверяются. */
+export declare function verifyHash(password: string, stored: string): Promise<boolean>;
+export declare function base32Encode(buf: Uint8Array): string;
+export declare function base32Decode(s: string): Buffer;
+/** Код приложения-аутентификатора для секрета на момент времени (RFC 6238; помощник для тестов и сервисов). */
 export declare function totpCode(secretBase32: string, atMs?: number): string;
-/** Успешный вход: чей кред и какой именно. */
-export interface AuthResult {
-    account: Account;
-    credential: Credential;
+type AccountRef = string | {
+    id: string;
+};
+/** Успешный вход: аккаунт и токен новой сессии. */
+export interface LoginResult {
+    account: string;
+    token: string;
 }
-interface VerifyOpts {
-    /** false — пускать и неподтверждённые креды (default: подтверждённые). */
-    requireConfirmed?: boolean;
+/** Кред без секретного материала. */
+export interface Credential {
+    id: string;
+    kind: string;
+    /** Идентификатор (у TOTP — нет). */
+    ident: string | null;
+    confirmed: boolean;
+    enabled: boolean;
+    meta: Record<string, unknown>;
+    created_at: string;
+    expires_at: string | null;
 }
 export interface AuthApi {
-    /** Пароль (upsert): логин/пароль и почта/пароль — одна механика, различает category. */
+    /** Пароль (и любой «логин/пароль»: kind — PASSWORD, EMAIL, …): создать или заменить. Смена гасит остальные сессии аккаунта. */
     setPassword(a: {
-        account: string | {
-            id: string;
-        };
+        account: AccountRef;
         identifier: string;
         password: string;
-        category?: string;
+        kind?: string;
         confirmed?: boolean;
-    }): Promise<Credential>;
+        keepCurrent?: boolean;
+    }): Promise<string>;
+    /**
+     * Вход по паролю — для сервиса с правом auth.password и auth.session. Неудача — null. С `totp` после
+     * верного пароля база проверяет код TOTP аккаунта (право auth.totp; счётчик неудач и блокировка — общие
+     * с verifyTotp): верный — сессия со способами [kind, 'TOTP'], неверный или повторный — null.
+     */
     verifyPassword(a: {
         identifier: string;
         password: string;
-        category?: string;
-    } & VerifyOpts): Promise<AuthResult | null>;
-    /** Новый api-ключ `lts_<48hex>`: отдаётся ОДИН раз, в БД — только sha256. */
+        kind?: string;
+        requireConfirmed?: boolean;
+        ttl?: number;
+        totp?: string;
+    }): Promise<LoginResult | null>;
+    /** Ключ API `lts_…`: отдаётся один раз. Себе сервис выпускает ключ сам по сессии своего ключа. */
     issueApiKey(a: {
-        account: string | {
-            id: string;
-        };
+        account: AccountRef;
         name?: string;
+        ttl?: number;
     }): Promise<{
         key: string;
-        credential: Credential;
+        id: string;
     }>;
-    verifyApiKey(key: string, opts?: VerifyOpts): Promise<AuthResult | null>;
-    /** Пара key(открытый id)+secret: secret отдаётся один раз, в БД — sha256. */
+    verifyApiKey(key: string): Promise<LoginResult | null>;
+    /** Пара ключ + секрет: секрет отдаётся один раз. Себе сервис выпускает пару сам по сессии своего ключа. */
     issueKeySecret(a: {
-        account: string | {
-            id: string;
-        };
+        account: AccountRef;
         name?: string;
     }): Promise<{
         key: string;
         secret: string;
-        credential: Credential;
+        id: string;
     }>;
-    verifyKeySecret(key: string, secret: string, opts?: VerifyOpts): Promise<AuthResult | null>;
-    /** TOTP (authenticator): секрет + otpauth-URI для QR; активен после первой успешной проверки. */
+    verifyKeySecret(key: string, secret: string): Promise<LoginResult | null>;
+    /** TOTP: секрет в base32 и ссылка otpauth:// для QR; фактор включает первая успешная проверка. */
     enrollTotp(a: {
-        account: string | {
-            id: string;
-        };
+        account: AccountRef;
         issuer?: string;
         label?: string;
     }): Promise<{
         secret: string;
         uri: string;
-        credential: Credential;
     }>;
-    /** Проверка 6-значного кода: окно ±window шагов (default 1), replay того же шага отбит. */
     verifyTotp(a: {
-        account: string | {
-            id: string;
-        };
+        account: AccountRef;
         code: string;
         window?: number;
     }): Promise<boolean>;
-    /** true — TOTP-фактор включён (enroll подтверждён хотя бы одной проверкой). */
-    totpEnabled(account: string | {
-        id: string;
-    }): Promise<boolean>;
-    /** Одноразовый код (email/SMS/reset — доставка на приложении): в БД sha256 + TTL + лимит попыток. */
+    totpEnabled(account: AccountRef): Promise<boolean>;
+    /** Одноразовый код для доставки сервисом (право auth.otp). */
     issueOtp(a: {
-        account: string | {
-            id: string;
-        };
+        account: AccountRef;
         identifier: string;
-        category?: string;
-        ttlSec?: number;
+        kind?: string;
+        ttl?: number;
         digits?: number;
+        maxAttempts?: number;
     }): Promise<{
         code: string;
-        credential: Credential;
     }>;
-    /** Успех сжигает код (одноразовость); maxAttempts (default 5) неудач тоже сжигают. */
+    /** Вход по одноразовому коду: успех и перебор (лимит задал выпуск, 1–10, по умолчанию 5) сжигают код. */
     verifyOtp(a: {
         identifier: string;
         code: string;
-        category?: string;
-        maxAttempts?: number;
-    }): Promise<AuthResult | null>;
-    /** Внешняя identity (TELEGRAM / GOOGLE / SSO-провайдер…): токен проверяет приложение, тут — связка. */
+        kind?: string;
+    }): Promise<LoginResult | null>;
+    /** Внешняя identity (TELEGRAM, GOOGLE, SSO): токен проверяет сервис, здесь — связка. */
     link(a: {
-        account: string | {
-            id: string;
-        };
-        category: string;
+        account: AccountRef;
+        kind: string;
         identifier: string;
         meta?: Record<string, unknown>;
         confirmed?: boolean;
-    }): Promise<Credential>;
+    }): Promise<string>;
+    /** Вход по identity — для сервиса с правами auth.identity и auth.session; `totp` — как у verifyPassword. */
     lookup(a: {
-        category: string;
+        kind: string;
         identifier: string;
-    } & VerifyOpts): Promise<AuthResult | null>;
-    /** Сессии во внешнем KV (Redis): store инжектирует приложение. */
-    sessions(store: SessionStore): Sessions;
+        requireConfirmed?: boolean;
+        ttl?: number;
+        totp?: string;
+    }): Promise<LoginResult | null>;
+    /** Креды аккаунта без секретов. */
+    credentials(account: AccountRef): Promise<Credential[]>;
+    /**
+     * Удалить кред. Ключ API и пара ключ + секрет гасят только свои сессии, прочие креды — остальные сессии
+     * аккаунта; текущая гаснет, если keepCurrent: false. Свои ключи сервис отзывает сам; последний
+     * действующий ключ сервиса не отзывается (acl_denied).
+     */
+    revokeCredential(id: string, opts?: {
+        keepCurrent?: boolean;
+    }): Promise<boolean>;
+    /** Признаки креда confirmed и enabled (право auth.credential). */
+    setFlags(id: string, flags: {
+        confirmed?: boolean;
+        enabled?: boolean;
+    }): Promise<boolean>;
+    /** Короткая сессия пользователя для другого процесса (право auth.session). */
+    sessionFor(account: AccountRef, opts?: {
+        ttl?: number;
+    }): Promise<string>;
+    /** Продлить текущую сессию; новый срок — от сейчас. */
+    refresh(opts?: {
+        ttl?: number;
+    }): Promise<string>;
+    /** Выход: погасить текущую сессию. */
+    revoke(): Promise<boolean>;
+    /** Выход везде: все сессии аккаунта (чужого — с правом auth.session). */
+    revokeAll(account?: AccountRef): Promise<number>;
+    /** Переключить арендатора сессии: собственный или по членству. */
+    switch(tenant: string): Promise<void>;
+    /** Арендаторы, доступные аккаунту сессии: собственный (owner) и по членству. */
+    tenants(): Promise<{
+        tenant: string;
+        roles: string[];
+    }[]>;
+    /**
+     * Удалить аккаунт (этап 6; accounts.purge 0.21): системный администратор или владелец его
+     * арендатора; себя и последнего владельца арендатора — нельзя. Данные арендатора стираются,
+     * владение строками в чужих арендаторах переходит им, сессии гаснут, креды удаляются.
+     */
+    purgeAccount(account: AccountRef): Promise<{
+        account: string;
+        rows: number;
+        versions: number;
+        memberships: number;
+        owned: number;
+    }>;
 }
-export declare function makeAuth(tables: Tables): AuthApi;
+/** Фасад db.auth. onSwitch — подключение перечитывает арендатора, реестр и пропуска прав. */
+export declare function makeAuth(S: string, exec: Executor, onSwitch: () => Promise<void>, canSwitch: boolean): AuthApi;
 export {};