@mybuildex/pkg 0.6.1 → 0.8.0

package/dist/acl/roles.js

@@ -0,0 +1,71 @@
+"use strict";
+// Papéis aceitos em inglês e português — espelho de
+// src/utils/roles.js do front da plataforma. O array de
+// permissões pode trazer o nome em inglês ('teacher'/'student') ou em pt-BR,
+// igual ao profiles.identifier do banco ('professor'/'aluno'). Basta um deles.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FUNCTION_ROLE_ALIASES = exports.FUNCTION_ROLES = exports.FUNCTION_ROLE_PAIRS = exports.ROLE_ALIASES = exports.RESPONSIBLE_ACLS = exports.STUDENT_ACLS = exports.TEACHER_ACLS = void 0;
+exports.isRoleName = isRoleName;
+exports.isSingleRoleList = isSingleRoleList;
+exports.isFunctionRoleName = isFunctionRoleName;
+exports.hasAclName = hasAclName;
+exports.hasAnyOf = hasAnyOf;
+exports.TEACHER_ACLS = ["teacher", "professor"];
+exports.STUDENT_ACLS = ["student", "aluno"];
+/** Responsável (front: store/active-child.js). Não entra na regra de ACL; só no resolver. */
+exports.RESPONSIBLE_ACLS = ["responsible", "responsavel"];
+/** nome (en ou pt) → todos os nomes equivalentes do mesmo papel */
+exports.ROLE_ALIASES = {
+    teacher: exports.TEACHER_ACLS,
+    professor: exports.TEACHER_ACLS,
+    student: exports.STUDENT_ACLS,
+    aluno: exports.STUDENT_ACLS,
+};
+function isRoleName(name) {
+    return Object.prototype.hasOwnProperty.call(exports.ROLE_ALIASES, name);
+}
+/** true quando a lista só tem nomes de UM papel (ex.: ['teacher'] ou ['teacher', 'professor']). */
+function isSingleRoleList(names) {
+    if (!names.length || !names.every(isRoleName))
+        return false;
+    return new Set(names.map(n => exports.ROLE_ALIASES[n][0])).size === 1;
+}
+/**
+ * Papéis de função da escola, en ↔ pt-BR — espelho de
+ * FUNCTION_ROLE_PAIRS do front (utils/roles.js). Diferente de professor/aluno,
+ * NÃO entram na regra "lista só com papel nega". O mapeamento papel → telas
+ * vive nas listas `acl` do mapa do front (ACL_MAP), com o nome em inglês.
+ */
+exports.FUNCTION_ROLE_PAIRS = [
+    ["director", "diretor"],
+    ["deputy_director", "diretor_auxiliar"],
+    ["coordinator", "coordenador"],
+    ["pedagogical", "pedagogico"],
+    ["secretary", "secretaria"],
+    ["assistant_secretary", "secretaria_auxiliar"],
+    ["financial", "financeiro"],
+    ["cashier", "financeiro_caixa"],
+    ["doorman", "porteiro"],
+    ["counselor", "orientador"],
+    ["teaching_assistant", "monitor"],
+    ["admissions", "comercial"],
+    ["reception", "recepcao"],
+];
+exports.FUNCTION_ROLES = exports.FUNCTION_ROLE_PAIRS.map(([en]) => en);
+exports.FUNCTION_ROLE_ALIASES = Object.freeze(Object.fromEntries(exports.FUNCTION_ROLE_PAIRS.flatMap(pair => pair.map(name => [name, pair]))));
+function isFunctionRoleName(name) {
+    return Object.prototype.hasOwnProperty.call(exports.FUNCTION_ROLE_ALIASES, name);
+}
+/** As permissões do usuário têm `name` (papéis aceitam o nome en ou pt). */
+function hasAclName(acl, name) {
+    if (isRoleName(name))
+        return exports.ROLE_ALIASES[name].some(alias => acl.includes(alias));
+    if (isFunctionRoleName(name))
+        return exports.FUNCTION_ROLE_ALIASES[name].some(alias => acl.includes(alias));
+    return acl.includes(name);
+}
+/** Alguma das permissões do usuário é um dos nomes. */
+function hasAnyOf(acl, names) {
+    return names.some(n => acl.includes(n));
+}
+//# sourceMappingURL=roles.js.map

package/dist/acl/roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.js","sourceRoot":"","sources":["../../src/acl/roles.ts"],"names":[],"mappings":"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"}

package/dist/audit/audit.d.ts

@@ -0,0 +1,165 @@
+import { SerializeOptions } from "./serialize";
+export declare const AUDIT_WRITE_OPERATIONS: readonly ["create", "createMany", "createManyAndReturn", "update", "updateMany", "updateManyAndReturn", "upsert", "delete", "deleteMany"];
+export type AuditOrigin = "USER" | "ANONYMOUS" | "SERVICE" | "CRON" | "WEBHOOK" | "SYSTEM";
+export interface AuditOptions extends SerializeOptions {
+    /** Nome da API (ex.: v1_pedagogico). */
+    api: string;
+    /** Tabelas (models do Prisma) auditadas. "*" = TODAS: tabela nova
+     *  entra sozinha, sem manter lista. Vazio = nada auditado. */
+    tables: string[] | "*";
+    /** Com tables "*": models que NÃO são auditados. */
+    exclude?: string[];
+    /** Tabela de destino (default audit_logs). */
+    table?: string;
+    /** Máximo de linhas lidas como "antes" num updateMany/deleteMany (default 200). */
+    maxManyRows?: number;
+    /** Log estruturado (default console.error/warn em JSON). */
+    logger?: (event: string, data: Record<string, unknown>) => void;
+    /** Resolve o usuário (users.id), a pessoa (users.id_people) e o nome
+     *  (peoples.name) do autor pelo uid do token. Default true. */
+    actorLookup?: boolean;
+    /** TTL do cache do autor por escola+uid, ms (default 10 min). */
+    actorCacheTtlMs?: number;
+}
+/** Cliente base (sem extensão) usado para ler o "antes" e gravar o log. */
+export interface AuditBaseClient {
+    $schema: string;
+    $executeRawUnsafe(sql: string, ...params: unknown[]): Promise<unknown>;
+    $queryRawUnsafe?(sql: string, ...params: unknown[]): Promise<unknown>;
+    [model: string]: any;
+}
+export interface AuditEntry {
+    api: string;
+    schema: string;
+    auditTable: string;
+    client: AuditBaseClient;
+    createdAt: Date;
+    tableName: string;
+    recordId: string | null;
+    operation: string;
+    before: unknown;
+    after: unknown;
+    changed: string[] | null;
+    affectedRows: number | null;
+    serialize: SerializeOptions;
+    log: (event: string, data: Record<string, unknown>) => void;
+    /** Resolver o autor (users/peoples) na gravação. */
+    actorLookup?: boolean;
+    actorCacheTtlMs?: number;
+}
+interface AuditContext {
+    request: any;
+    requestId: string;
+    entries: AuditEntry[];
+    flushed: boolean;
+    startedAt?: number;
+}
+/** Contexto de auditoria da request corrente (undefined fora de request). */
+export declare function getAuditContext(): AuditContext | undefined;
+/** Abre um contexto fora do Fastify (testes, jobs que queiram agrupar escritas). */
+export declare function runInAuditContext<T>(request: any, fn: () => T): T;
+/**
+ * Handler `$allOperations` da extensão (exportado para teste). `base` é o
+ * client SEM extensão do mesmo schema: lê o "antes" e grava o log.
+ */
+export declare function createAuditQueryHandler(base: AuditBaseClient, options: AuditOptions): ({ model, operation, args, query }: {
+    model?: string;
+    operation: string;
+    args: any;
+    query: (args: any) => Promise<any>;
+}) => Promise<any>;
+/** Extensão pronta para `client.$extends(...)`. */
+export declare function createAuditExtension(base: AuditBaseClient, options: AuditOptions): {
+    name: string;
+    query: {
+        $allModels: {
+            $allOperations: ({ model, operation, args, query }: {
+                model?: string;
+                operation: string;
+                args: any;
+                query: (args: any) => Promise<any>;
+            }) => Promise<any>;
+        };
+    };
+};
+/** A auditoria está ligada? ("*" ou lista não vazia) */
+export declare function auditEnabled(options: AuditOptions | undefined | null): boolean;
+/** Aplica a extensão preservando o `$schema` do client base. */
+export declare function withAudit<T extends AuditBaseClient>(base: T, options: AuditOptions): T;
+/**
+ * Registra uma escrita feita por SQL cru (não passa pela extensão). Sem
+ * antes/depois: guarda o SQL e os parâmetros.
+ */
+export declare function auditRaw(prisma: AuditBaseClient, input: {
+    api: string;
+    table: string;
+    operation: string;
+    sql: string;
+    params?: unknown[];
+    recordId?: string | number | null;
+    affectedRows?: number | null;
+    auditTable?: string;
+}, options?: SerializeOptions & {
+    logger?: AuditOptions["logger"];
+}): Promise<void>;
+export declare const AUDIT_COLUMNS: readonly ["created_at", "request_id", "api", "module", "action", "acl_entry", "http_method", "route", "url", "table_name", "record_id", "operation", "origin", "actor_uid", "actor_email", "actor_name", "actor_id_user", "actor_id_people", "actor_people_name", "ip", "user_agent", "data_before", "data_after", "changed_fields", "affected_rows", "status_code", "request_failed"];
+/** DATETIME(3) em UTC — o mesmo relógio que o Prisma usa nas colunas de data. */
+export declare function auditDate(d: Date): string;
+export interface AuditRequestInfo {
+    requestId: string | null;
+    statusCode: number | null;
+    origin: AuditOrigin;
+}
+export interface AuditActor {
+    idUser: string | null;
+    idPeople: string | null;
+    peopleName: string | null;
+}
+/** Limpa o cache do autor (testes). */
+export declare function clearAuditActorCache(): void;
+/** Autor pelo uid, na base da escola. null quando não acha ou falha (nunca lança). */
+export declare function resolveAuditActor(client: AuditBaseClient, schema: string, uid: string, options?: {
+    ttlMs?: number;
+    log?: (event: string, data: Record<string, unknown>) => void;
+    api?: string;
+}): Promise<AuditActor | null>;
+/** Linha (na ordem de AUDIT_COLUMNS) de uma entrada. Exportado para teste. */
+export declare function auditRow(entry: AuditEntry, request: any, info: AuditRequestInfo, actor?: AuditActor | null): unknown[];
+/** Grava as entradas: um INSERT por (schema, tabela de destino). Nunca lança. */
+export declare function writeEntries(entries: AuditEntry[], ctx?: AuditContext, statusCode?: number | null): Promise<void>;
+export interface AuditPluginOptions {
+    /** Origem da escrita a partir do request (ex.: conta de serviço => SERVICE). */
+    resolveOrigin?: (request: any) => AuditOrigin | undefined;
+    /** Nome da API nas linhas de 403 e no log de acesso (ex.: v1_pedagogico). */
+    api?: string;
+    /** Client da escola para gravar o 403 quando o request ainda não tem
+     *  req.prisma (ex.: 403 do vínculo token↔escola, no onRequest). */
+    getTenantClient?: (idSchool: string) => any;
+    /** Tabela de destino (default audit_logs). */
+    table?: string;
+    /** Grava todo 403 em audit_logs (default true). */
+    auditForbidden?: boolean;
+    /** Máximo de linhas de 403 por usuário+rota por minuto (default 30). Acima
+     *  disso: uma linha-resumo e o resto só no log. */
+    forbiddenLimitPerMinute?: number;
+    /** Uma linha estruturada por request no log da function (default true). */
+    accessLog?: boolean;
+    /** Log estruturado (default console em JSON). */
+    logger?: (event: string, data: Record<string, unknown>) => void;
+    /** Relógio (teste). */
+    now?: () => number;
+}
+/**
+ * Plugin (função aplicada direto na instância, como os demais do pkg): abre o
+ * contexto no onRequest e grava no onSend. Idempotente.
+ */
+export declare function createAuditPlugin(options?: AuditPluginOptions): (fastify: any) => Promise<void>;
+export interface ForbiddenThrottle {
+    /** "record" grava normal; "summary" grava a linha-resumo; "skip" só loga. */
+    hit(key: string): {
+        decision: "record" | "summary" | "skip";
+        suppressedBefore: number;
+    };
+}
+export declare function createForbiddenThrottle(limit: number, now?: () => number): ForbiddenThrottle;
+export {};