@verdeect/kit 0.0.0-stage → 1.0.0-rc.2

package/dist/observability/metrics.js

@@ -0,0 +1,53 @@
+// kitMetrics и alertRulesTemplate (prd.md §3.2, AC-2.8, AC-2.11). Эталон — O metrics-server.ts (реестр на экземпляр) и
+// O orch-metrics.ts (метрики на реестре экземпляра). По PRD v1.12: @prometheus-io/client, как у O; метка service по
+// умолчанию, метрики процесса Node, имена verdeect_*. Глобального реестра нет: два приложения в процессе не смешиваются.
+// AC-9.5 (E4): метрика очистки verdeect_cleanup_runs_total.
+import { fileURLToPath } from 'node:url';
+import { collectDefaultMetrics, Counter, Gauge, Registry } from '@prometheus-io/client';
+import { assertServiceName } from '../internal/service-name.js';
+/** Создаёт реестр экземпляра с меткой `service`, метриками процесса Node и метриками пакета (§3.2, AC-2.8). */
+export function kitMetrics(options) {
+    assertServiceName(options.service, 'kitMetrics');
+    const registry = new Registry();
+    registry.setDefaultLabels({ service: options.service });
+    collectDefaultMetrics({ register: registry });
+    const registers = [registry];
+    return {
+        registry,
+        outboxPending: new Gauge({
+            name: 'verdeect_outbox_pending',
+            help: 'Неотправленные строки outbox',
+            registers,
+        }),
+        outboxLagSeconds: new Gauge({
+            name: 'verdeect_outbox_lag_seconds',
+            help: 'Возраст самой старой неотправленной строки outbox, с',
+            registers,
+        }),
+        eventsConsumed: new Counter({
+            name: 'verdeect_events_consumed_total',
+            help: 'Принятые события по типу и результату (handled, duplicate, retry, dlq)',
+            labelNames: ['type', 'result'],
+            registers,
+        }),
+        dbPoolWaitTimeouts: new Counter({
+            name: 'verdeect_db_pool_wait_timeouts_total',
+            help: 'Истёк срок ожидания клиента пула БД',
+            labelNames: ['pool'],
+            registers,
+        }),
+        rateLimitUnavailable: new Counter({
+            name: 'verdeect_rate_limit_unavailable_total',
+            help: 'Проверки лимита без Redis (запрос пропущен)',
+            registers,
+        }),
+        cleanupRuns: new Counter({
+            name: 'verdeect_cleanup_runs_total',
+            help: 'Проходы фоновой очистки по таблице и итогу (ok, partial, interrupted, error)',
+            labelNames: ['table', 'result'],
+            registers,
+        }),
+    };
+}
+/** Абсолютный путь к шаблону правил vmalert `alerts/verdeect-kit.rules.yml` внутри установленного пакета (§3.2). */
+export const alertRulesTemplate = fileURLToPath(new URL('../../alerts/verdeect-kit.rules.yml', import.meta.url));

package/dist/observability/redaction.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Базовый список чувствительных имён (§3.2): заголовки, секреты и токены, ПДн, `body.code` и `body.state`.
+ * Каждое имя скрывается на уровнях 0–2 в логах и по имени — в событиях GlitchTip. `err.code` не скрывается.
+ */
+export declare const SENSITIVE_KEYS: readonly string[];
+/**
+ * Правила редактирования сервиса — один объект на сервис (константа `src/redaction.ts`). Передаётся и в
+ * `createLoggerOptions`, и в `initSentry`: имена и маска пути для логов и GlitchTip совпадают по построению.
+ * `src/redaction.ts` сервиса загружается в `instrument.ts` до Sentry, поэтому импортирует только типы из
+ * `@verdeect/kit/observability` (GAP-9).
+ */
+export interface KitRedaction {
+    /** Имена, добавляемые к `SENSITIVE_KEYS` (объединение без дублей); пустой массив базовый список не отключает. */
+    readonly sensitiveKeys?: readonly string[];
+    /** Маска пути для лога доступа и `request.url` события GlitchTip; по умолчанию путь не меняется. */
+    readonly maskPath?: (path: string) => string;
+}
+/** `SENSITIVE_KEYS` ∪ `redaction.sensitiveKeys` без дублей; базовый список присутствует всегда. */
+export declare function sensitiveNames(redaction?: KitRedaction): readonly string[];
+/** Пути `redact` pino: каждое имя на уровнях 0–2 (`k`, `*.k`, `*.*.k`). */
+export declare function redactPaths(redaction?: KitRedaction): string[];
+/** Маска пути сервиса; по умолчанию — тождество. */
+export declare function maskPathOf(redaction?: KitRedaction): (path: string) => string;

package/dist/observability/redaction.js

@@ -0,0 +1,65 @@
+// Список чувствительных имён и KitRedaction (prd.md §3.2, O1, O3, GAP-6, GAP-8; NFR-4). Эталон — REDACT_PATHS O
+// observability.module.ts; имена — по PRD, ключи сервисов (O ORCHESTRATOR_KEYS, I csrfToken/stepToken) — в KitRedaction
+// сервиса.
+/**
+ * Базовый список чувствительных имён (§3.2): заголовки, секреты и токены, ПДн, `body.code` и `body.state`.
+ * Каждое имя скрывается на уровнях 0–2 в логах и по имени — в событиях GlitchTip. `err.code` не скрывается.
+ */
+export const SENSITIVE_KEYS = Object.freeze([
+    'authorization',
+    'cookie',
+    'set-cookie',
+    'idempotency-key',
+    'password',
+    'newPassword',
+    'currentPassword',
+    'secret',
+    'clientSecret',
+    'token',
+    'access_token',
+    'refresh_token',
+    'id_token',
+    'logout_token',
+    'accessToken',
+    'code_verifier',
+    'nonce',
+    'email',
+    'givenName',
+    'familyName',
+    'middleName',
+    'body.code',
+    'body.state',
+]);
+/** Сегмент пути pino: имя из `[A-Za-z0-9_]` — через точку, прочее — в скобках `["…"]`. */
+const PLAIN_SEGMENT = /^[A-Za-z0-9_]+$/;
+/** `SENSITIVE_KEYS` ∪ `redaction.sensitiveKeys` без дублей; базовый список присутствует всегда. */
+export function sensitiveNames(redaction) {
+    return [...new Set([...SENSITIVE_KEYS, ...(redaction?.sensitiveKeys ?? [])])];
+}
+/** Путь имени без префикса: `body.code` → `body.code`, `set-cookie` → `["set-cookie"]`. */
+function namePath(name) {
+    return name
+        .split('.')
+        .map((segment, index) => {
+        if (!PLAIN_SEGMENT.test(segment)) {
+            return `[${JSON.stringify(segment)}]`;
+        }
+        return index === 0 ? segment : `.${segment}`;
+    })
+        .join('');
+}
+/** Присоединяет путь имени к префиксу `*`/`*.*`: скобка идёт без точки. */
+function withPrefix(prefix, path) {
+    return path.startsWith('[') ? `${prefix}${path}` : `${prefix}.${path}`;
+}
+/** Пути `redact` pino: каждое имя на уровнях 0–2 (`k`, `*.k`, `*.*.k`). */
+export function redactPaths(redaction) {
+    return sensitiveNames(redaction).flatMap((name) => {
+        const path = namePath(name);
+        return [path, withPrefix('*', path), withPrefix('*.*', path)];
+    });
+}
+/** Маска пути сервиса; по умолчанию — тождество. */
+export function maskPathOf(redaction) {
+    return redaction?.maskPath ?? ((path) => path);
+}

package/dist/observability/sanitize-error.d.ts

@@ -0,0 +1,47 @@
+/** Предел обхода цепочки `cause` (§3.2). */
+export declare const MAX_CAUSE_DEPTH = 10;
+/** Ошибка БД без SQL, параметров и значений: только метаданные pg. */
+export declare class SanitizedDbError extends Error {
+    readonly name = "SanitizedDbError";
+    /** SQLSTATE. */
+    readonly code?: string;
+    /** Имя ограничения. */
+    readonly constraint?: string;
+    /** Имя таблицы. */
+    readonly table?: string;
+    /** Имя столбца. */
+    readonly column?: string;
+    /** Уровень pg (`ERROR`, `FATAL`). */
+    readonly severity?: string;
+}
+/** Ошибка ioredis без аргументов команды: имя, код и имя команды. */
+export declare class SanitizedRedisError extends Error {
+    readonly name = "SanitizedRedisError";
+    /** Код ошибки ioredis. */
+    code?: string;
+    /** Имя команды Redis без аргументов. */
+    command?: string;
+}
+/**
+ * Регистрирует ветку очистки сервиса (§3.2), например SMTP Identity. Глобально на процесс; повторная
+ * регистрация того же `match` игнорируется. `match` проверяется на каждом звене цепочки `cause`, `sanitize`
+ * получает совпавшее звено.
+ */
+export declare function registerErrorSanitizer(match: (error: unknown) => boolean, sanitize: (error: unknown) => Error): void;
+/**
+ * Ошибка без SQL, параметров и значений (§3.2, AC-2.3). Ветки по форме объекта на любом звене цепочки `cause`
+ * (до 10): PostgreSQL/Drizzle → `code`, `constraint`, `table`, `column`, `severity` и «Failed query (<code>)»;
+ * ioredis → `name`, `code`, имя команды; затем ветки `registerErrorSanitizer`. Срабатывает первая. Ветки нет —
+ * исходная ошибка; цепочка глубже 10 или с циклом — копия с обрезанной цепочкой. Уже очищенная — как есть.
+ */
+export declare function sanitizeError(error: unknown): unknown;
+/**
+ * formatters.log для pino: ключ `err` и любые Error верхнего уровня (error, cause, …) — через sanitizeError.
+ * Вызывается до сериализаторов с исходным объектом: поля pg из cause ещё доступны.
+ */
+export declare function sanitizeLogObject(object: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Сериализатор `err` для pino: любой logger.error({err}) проходит через sanitizeError. Получает и Error (pino), и
+ * сериализованный объект (pino-http оборачивает через wrapErrorSerializer).
+ */
+export declare function serializeError(error: unknown): unknown;

package/dist/observability/sanitize-error.js

@@ -0,0 +1,194 @@
+// sanitizeError и registerErrorSanitizer (prd.md §3.2, AC-2.3, NFR-4). Эталон — O sanitize-error.ts (SanitizedDbError,
+// проверка pg по форме, «Failed query (<code>)», стек без первой строки, sanitizeLogObject, serializeError); ветка
+// ioredis — B sanitize-error.ts (SanitizedRedisError). По PRD: Drizzle распознаётся по форме, без импорта drizzle-orm;
+// цепочка cause — не глубже 10 звеньев и без зацикливания; ветки сервисов — через registerErrorSanitizer (SMTP Identity).
+import { stdSerializers } from 'pino';
+/** Предел обхода цепочки `cause` (§3.2). */
+export const MAX_CAUSE_DEPTH = 10;
+const PG_FIELDS = ['code', 'constraint', 'table', 'column', 'severity'];
+const SQLSTATE = /^[\dA-Z]{5}$/;
+const DRIZZLE_QUERY_ERROR = 'DrizzleQueryError';
+/** Ошибка БД без SQL, параметров и значений: только метаданные pg. */
+export class SanitizedDbError extends Error {
+    name = 'SanitizedDbError';
+    /** SQLSTATE. */
+    code;
+    /** Имя ограничения. */
+    constraint;
+    /** Имя таблицы. */
+    table;
+    /** Имя столбца. */
+    column;
+    /** Уровень pg (`ERROR`, `FATAL`). */
+    severity;
+}
+/** Ошибка ioredis без аргументов команды: имя, код и имя команды. */
+export class SanitizedRedisError extends Error {
+    name = 'SanitizedRedisError';
+    /** Код ошибки ioredis. */
+    code;
+    /** Имя команды Redis без аргументов. */
+    command;
+}
+/** Ветки сервисов — глобально на процесс, в порядке регистрации. */
+const registered = [];
+/** Результаты sanitizeError: повторно не обрабатываются. */
+const sanitizedResults = new WeakSet();
+/**
+ * Регистрирует ветку очистки сервиса (§3.2), например SMTP Identity. Глобально на процесс; повторная
+ * регистрация того же `match` игнорируется. `match` проверяется на каждом звене цепочки `cause`, `sanitize`
+ * получает совпавшее звено.
+ */
+export function registerErrorSanitizer(match, sanitize) {
+    if (registered.some((item) => item.match === match)) {
+        return;
+    }
+    registered.push({ match, sanitize });
+}
+/** Цепочка error → cause → … не длиннее MAX_CAUSE_DEPTH, без повторов; truncated — дальше есть звенья. */
+function causeChain(error) {
+    const chain = [];
+    const seen = new Set();
+    let current = error;
+    while (typeof current === 'object' && current !== null) {
+        if (seen.has(current) || chain.length >= MAX_CAUSE_DEPTH) {
+            return { chain, truncated: true };
+        }
+        seen.add(current);
+        chain.push(current);
+        current = current.cause;
+    }
+    return { chain, truncated: false };
+}
+/** Ошибка драйвера pg (DatabaseError): SQLSTATE в code и строковый severity — без импорта pg. */
+function isPgError(value) {
+    const { code, severity } = value;
+    return typeof code === 'string' && SQLSTATE.test(code) && typeof severity === 'string';
+}
+/**
+ * DrizzleQueryError по форме: `name` экземпляра или `type` сериализованной формы (pino-http сначала
+ * применяет stdSerializers.err). Без импорта drizzle-orm (§3.2).
+ */
+function isDrizzleQueryError(value) {
+    const { name, type } = value;
+    return name === DRIZZLE_QUERY_ERROR || type === DRIZZLE_QUERY_ERROR;
+}
+/** Ошибка ioredis: поле command `{name, args}` — без импорта ioredis. */
+function isRedisCommandError(value) {
+    const command = value.command;
+    return typeof command === 'object' && command !== null && 'args' in command;
+}
+/** Строки стека без первой (в ней message исходной ошибки). */
+function framesOnly(stack) {
+    if (typeof stack !== 'string') {
+        return '';
+    }
+    const start = stack.indexOf('\n    at ');
+    return start === -1 ? '' : stack.slice(start);
+}
+/** Ошибка БД → SanitizedDbError: поля pg из первого pg-звена, сообщение «Failed query» (+ code). */
+function sanitizeDbError(error, chain) {
+    const fields = {};
+    const pg = chain.find(isPgError);
+    for (const field of PG_FIELDS) {
+        const value = pg?.[field];
+        if (typeof value === 'string') {
+            fields[field] = value;
+        }
+    }
+    const sanitized = new SanitizedDbError(fields.code === undefined ? 'Failed query' : `Failed query (${fields.code})`);
+    Object.assign(sanitized, fields);
+    sanitized.stack = `${sanitized.name}: ${sanitized.message}${framesOnly(error.stack)}`;
+    return sanitized;
+}
+/** Ошибка ioredis → SanitizedRedisError: code и имя команды, без args. */
+function sanitizeRedisError(error, redis) {
+    const { code, command } = redis;
+    const commandName = typeof command.name === 'string' ? command.name : undefined;
+    const sanitized = new SanitizedRedisError(commandName === undefined
+        ? 'Redis command failed'
+        : `Redis command failed (${commandName})`);
+    if (typeof code === 'string') {
+        sanitized.code = code;
+    }
+    if (commandName !== undefined) {
+        sanitized.command = commandName;
+    }
+    sanitized.stack = `${sanitized.name}: ${sanitized.message}${framesOnly(error.stack)}`;
+    return sanitized;
+}
+/** Копия звеньев chain (прототип и собственные свойства), последняя — без cause. */
+function truncatedCopy(chain) {
+    const copies = chain.map((link) => Object.create(Object.getPrototypeOf(link), Object.getOwnPropertyDescriptors(link)));
+    copies.forEach((copy, index) => {
+        const next = copies[index + 1];
+        if (next === undefined) {
+            delete copy.cause;
+            return;
+        }
+        Object.defineProperty(copy, 'cause', {
+            value: next,
+            writable: true,
+            configurable: true,
+            enumerable: Object.getOwnPropertyDescriptor(copy, 'cause')?.enumerable ?? false,
+        });
+    });
+    return copies[0] ?? {};
+}
+/** Применяет ветку и помечает результат очищенным. */
+function mark(result) {
+    sanitizedResults.add(result);
+    return result;
+}
+/**
+ * Ошибка без SQL, параметров и значений (§3.2, AC-2.3). Ветки по форме объекта на любом звене цепочки `cause`
+ * (до 10): PostgreSQL/Drizzle → `code`, `constraint`, `table`, `column`, `severity` и «Failed query (<code>)»;
+ * ioredis → `name`, `code`, имя команды; затем ветки `registerErrorSanitizer`. Срабатывает первая. Ветки нет —
+ * исходная ошибка; цепочка глубже 10 или с циклом — копия с обрезанной цепочкой. Уже очищенная — как есть.
+ */
+export function sanitizeError(error) {
+    if (typeof error !== 'object' || error === null || sanitizedResults.has(error)) {
+        return error;
+    }
+    const { chain, truncated } = causeChain(error);
+    if (chain.some((link) => isDrizzleQueryError(link) || isPgError(link))) {
+        return mark(sanitizeDbError(error, chain));
+    }
+    const redis = chain.find(isRedisCommandError);
+    if (redis !== undefined) {
+        return mark(sanitizeRedisError(error, redis));
+    }
+    for (const branch of registered) {
+        const link = chain.find((item) => branch.match(item));
+        if (link !== undefined) {
+            return mark(branch.sanitize(link));
+        }
+    }
+    return truncated ? mark(truncatedCopy(chain)) : error;
+}
+/**
+ * formatters.log для pino: ключ `err` и любые Error верхнего уровня (error, cause, …) — через sanitizeError.
+ * Вызывается до сериализаторов с исходным объектом: поля pg из cause ещё доступны.
+ */
+export function sanitizeLogObject(object) {
+    let result = object;
+    for (const [key, value] of Object.entries(object)) {
+        if (key !== 'err' && !(value instanceof Error)) {
+            continue;
+        }
+        const sanitized = sanitizeError(value);
+        if (sanitized !== value) {
+            result = result === object ? { ...object } : result;
+            result[key] = sanitized;
+        }
+    }
+    return result;
+}
+/**
+ * Сериализатор `err` для pino: любой logger.error({err}) проходит через sanitizeError. Получает и Error (pino), и
+ * сериализованный объект (pino-http оборачивает через wrapErrorSerializer).
+ */
+export function serializeError(error) {
+    const safe = sanitizeError(error);
+    return safe instanceof Error ? stdSerializers.err(safe) : safe;
+}

package/dist/observability/sentry.d.ts

@@ -0,0 +1,64 @@
+import type { Breadcrumb, Event } from '@sentry/nestjs';
+import { type KitRedaction } from './redaction.js';
+/** Опции `initSentry` (§3.2). */
+export interface KitSentryOptions {
+    /** Имя сервиса — тег `service` каждого события. */
+    readonly service: string;
+    /** Правила редактирования сервиса (общие с `createLoggerOptions`). */
+    readonly redaction?: KitRedaction;
+}
+/** Sentry 11: вместо sendDefaultPii — ничего из ПДн, заголовков, тел, query и данных БД не собирается. */
+export declare const NO_PERSONAL_DATA: {
+    userInfo: false;
+    cookies: false;
+    httpHeaders: false;
+    httpBodies: never[];
+    urlQueryParams: false;
+    databaseQueryData: false;
+    queues: false;
+    stackFrameVariables: false;
+    genAI: {
+        inputs: false;
+        outputs: false;
+    };
+};
+/** Хлебная крошка без чувствительных данных; адрес — без query и через maskPath. Внутренняя функция. */
+export declare function scrubBreadcrumb(crumb: Breadcrumb, redaction?: KitRedaction): Breadcrumb;
+/**
+ * Событие без query, `request.data`, cookie, ПДн пользователя (кроме `id`) и значений чувствительных имён в
+ * extra, contexts, tags и breadcrumbs (§3.2, AC-2.5). Внутренняя функция. При исключении отбрасываются
+ * request, extra, breadcrumbs и exception.
+ */
+export declare function scrubEvent<T extends Event>(event: T, originalException: unknown, redaction?: KitRedaction): T;
+/**
+ * DSN в форме, которую принимает SDK: иначе он сам печатает значение в console.error (NFR-4). Внутренняя функция: её же
+ * использует bootstrapService для SENTRY_NOT_PRELOADED.
+ */
+export declare function isValidDsn(dsn: string): boolean;
+/**
+ * Включает GlitchTip (§3.2): вызывается в `instrument.ts` сервиса, подключённом через `node --import` до загрузки
+ * приложения. Включается только при непустом и верном `SENTRY_DSN` и `NODE_ENV = production` (не задан — production);
+ * неверное окружение — Sentry выключен, без исключения и лога. `dataCollection: NO_PERSONAL_DATA`,
+ * `tracesSampleRate: 0`, тег `service`. Возвращает, включён ли SDK.
+ */
+export declare function initSentry(options: KitSentryOptions): boolean;
+/** Контекст события `captureError`. */
+interface CaptureContext {
+    /** Теги события. */
+    readonly tags?: Readonly<Record<string, string>>;
+    /** Дополнительные данные (проходят скраббер). */
+    readonly extra?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Отправляет ошибку в GlitchTip через `sanitizeError` — ровно одно событие на ошибку (§3.2): объект ошибки
+ * помечается отправленным, повторный вызов ничего не шлёт.
+ */
+export declare function captureError(error: unknown, context?: CaptureContext): void;
+/**
+ * Одно событие за окно `windowMs` (умолч. 60 000) на ключ в процессе (§3.2, AC-2.6). Уже отправленная ошибка
+ * (например, границей через `captureError`) повторно не шлётся. Возвращает, отправлено ли событие.
+ */
+export declare function captureThrottled(key: string, error: unknown, options?: {
+    readonly windowMs?: number;
+}): boolean;
+export {};