@mybuildex/pkg 0.6.0 → 0.7.0

package/README.md

@@ -51,6 +51,32 @@ createAuthMiddleware({
 createTenantMiddleware({getTenantClient, defaultClient, strictTenant: true});
 ```
 
+## 0.7.0 — ACL por endpoint, auditoria de escrita e permissões
+
+Módulos novos, todos opt-in (API que não os registra não muda nada). Nova dependência: `redis`.
+
+- **Auditoria** — `createMultitenantPrisma({..., audit: {api, tables: "*"}})` aplica uma extensão Prisma que registra toda escrita (create/update/upsert/delete e `*Many`) em `audit_logs` da escola: quem (uid, e-mail, `users.id`, `users.id_people`, `peoples.name`), rota, ação de ACL, antes/depois (no update, só o diff) e status. `createAuditPlugin({api, getTenantClient})` abre o contexto por request e grava num único INSERT por schema no `onSend`, **antes** da resposta (no Cloud Run a CPU é cortada depois). Todo 403 vira linha `acl_denied`/`forbidden` (limite de 30 por usuário+rota por minuto) e cada request gera um log `http_access`. Falha na gravação nunca derruba a escrita (log `audit_write_failed`). Exige a tabela `audit_logs` (migrations `2026_09_29_000173`–`000175` do mybuilder-mysql). SQL cru: `auditRaw()`.
+- **ACL por endpoint** — `createAclPlugin({api, mode})` uma vez no `loadPlugins` + `useModuleAcl(fastify, router, overrides?, {resource?})` no início de cada controller. A regra vem do mapa do front (`ACL_MAP`, gerado de `mybuilder-plataforma-front/src/utils/permissions.js` — o mesmo agregador que o front usa, com a ordem dos spreads — por `npm run acl:generate`; o teste `acl-map.spec.ts` acusa divergência). Ações padrão do CRUD gerado: `ALL→list`, `FIND→find`, `PAGINATE→paginate`, `TRASH→trash` (recurso sem a ação própria cai em `list`), `CREATE/CLONE→add`, `UPDATE→edit`, `REMOVE→remover`, `RESTORE→restore`, `DELETE→delete`. Overrides: `"recurso.acao"`, lista (qualquer uma libera), `{anyOf, allOf}`, `"@authenticated"`, `"@public"`. Modos: `off`, `report` (só loga `acl_would_deny`) e `enforce` (403). `getAclRouteReport(fastify)` lista rotas sem ACL ou com configuração inválida (para teste de cobertura).
+- **Permissões** — `createPermissionsResolver({redis})` como `onTenantResolved` do tenant middleware: preenche `request.permissions`, `is_full`/`is_teacher`/`is_student`/`is_responsible` pela cadeia users → users_profiles → profiles_policies → policies_rules → rules_permissions → permissions. Fail-closed (erro = tudo false + `permissions_error`). Cache Redis versionado por escola; `invalidatePermissionsCache(redis, idSchool)` (INCR, O(1)) depois de escrever em perfis/políticas/regras/permissões.
+- **Redis** — `createRedisClient()` lê o JSON da env `REDIS`; best-effort (sem env, JSON inválido ou falha → `undefined`), timeout de conexão de 3 s.
+- **Serviço interno** — request autenticado pelo `internalAuth` do auth (`request.internal === true`) não passa pela ACL, não consulta permissões e entra na auditoria com `origin = SERVICE`.
+
+```ts
+const mt = createMultitenantPrismaMariaDb<PrismaClient>({..., audit: {api: settings.PREFIX, tables: "*"}});
+
+// loadPlugins — depois do request-scope, antes do autoload dos módulos
+const redis = await createRedisClient();
+await createAuditPlugin({api: settings.PREFIX, getTenantClient})(fastify);
+await createAclPlugin({api: settings.PREFIX, mode: aclMode()})(fastify);   // off | report | enforce
+
+createTenantMiddleware({getTenantClient, defaultClient, strictTenant: true,
+    onTenantResolved: createPermissionsResolver({redis})});
+
+// cada controller
+useModuleAcl(fastify, citiesRouter);
+useModuleAcl(fastify, payRouter, {PUBLIC_HASH: "@public", SETTLE: "pay.settle"});
+```
+
 ## 0.6.0 — segurança e confiabilidade
 
 Correções em módulos existentes. **Três mudam comportamento por padrão** (marcadas com ⚠️) — conferir antes de atualizar uma API.

package/dist/acl/check.d.ts

@@ -0,0 +1,32 @@
+export type AclMap = Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>;
+/** Regra de ACL de uma rota. Entradas no formato `recurso.acao` do mapa do front. */
+export type AclRule = string | string[] | {
+    anyOf?: string[];
+    allOf?: string[];
+}
+/** Qualquer usuário autenticado (a auth já barrou quem não tem token). */
+ | "@authenticated"
+/** Rota pública: a ACL não se aplica. */
+ | "@public";
+export interface ResolvedAclRule {
+    kind: "entries" | "authenticated" | "public";
+    /** Entradas `recurso.acao` que liberam (qualquer uma). */
+    anyOf: string[];
+    /** Entradas `recurso.acao` que precisam liberar TODAS. */
+    allOf: string[];
+    /** União dos identificadores do anyOf (o que o isAclArray recebe). */
+    anyOfIds: string[];
+    /** Identificadores de cada entrada do allOf. */
+    allOfIds: string[][];
+}
+export declare class AclConfigError extends Error {
+    constructor(message: string);
+}
+/** Espelho do isAclArray do front: `required` é a lista `acl` de uma entrada. */
+export declare function checkAcl(userPermissions: readonly string[] | null | undefined, required: readonly string[]): boolean;
+/** Identificadores de uma entrada `recurso.acao` (lança se não existir no mapa). */
+export declare function aclEntryIds(entry: string, map?: AclMap): readonly string[];
+/** Valida a regra contra o mapa e pré-calcula os identificadores. */
+export declare function resolveAclRule(rule: AclRule, map?: AclMap): ResolvedAclRule;
+/** Avalia a regra já resolvida contra as permissões do usuário. */
+export declare function evaluateAclRule(userPermissions: readonly string[] | null | undefined, rule: ResolvedAclRule): boolean;

package/dist/acl/check.js

@@ -0,0 +1,114 @@
+"use strict";
+// Checagem de ACL — espelho EXATO do `isAclArray` do front
+// (src/utils/validations.js + utils/roles.js do front da plataforma):
+//
+//   - libera se o usuário tem QUALQUER identificador da lista (OR);
+//   - papéis aceitam o nome em en ou pt-BR (teacher/professor, student/aluno):
+//     'teacher' na lista libera quem tem 'professor' e vice-versa;
+//   - `full` libera tudo;
+//   - lista só com nomes de UM papel (['teacher'], ['teacher','professor'],
+//     ['aluno']...) nega sempre (regra do front: papel sozinho não libera ação).
+//
+// Como o front aplica a mesma lista para mostrar/esconder botão e rota, a
+// API não pode ser nem mais nem menos permissiva que isso.
+//
+// Uma rota da API pode aceitar MAIS DE UMA entrada do mapa (`recurso.acao`):
+// a mesma chamada é feita por telas diferentes (ex.: o diário do professor
+// grava em classes_dailys pela tela de turmas, liberada por classes.daily).
+//   - lista/`anyOf`: a união dos identificadores das entradas, avaliada de
+//     uma vez (qualquer um libera);
+//   - `allOf`: cada entrada avaliada à parte — todas precisam liberar.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AclConfigError = void 0;
+exports.checkAcl = checkAcl;
+exports.aclEntryIds = aclEntryIds;
+exports.resolveAclRule = resolveAclRule;
+exports.evaluateAclRule = evaluateAclRule;
+const map_generated_1 = require("./map.generated");
+const roles_1 = require("./roles");
+class AclConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AclConfigError";
+    }
+}
+exports.AclConfigError = AclConfigError;
+/** Espelho do isAclArray do front: `required` é a lista `acl` de uma entrada. */
+function checkAcl(userPermissions, required) {
+    const acl = Array.isArray(userPermissions) ? userPermissions.map(String) : [];
+    const names = required.map(n => String(n).trim());
+    let result = false;
+    for (const name of names) {
+        if ((0, roles_1.hasAclName)(acl, name))
+            result = true;
+    }
+    if ((0, roles_1.isSingleRoleList)(names))
+        return false;
+    return result || acl.includes("full");
+}
+/** Identificadores de uma entrada `recurso.acao` (lança se não existir no mapa). */
+function aclEntryIds(entry, map = map_generated_1.ACL_MAP) {
+    const dot = entry.lastIndexOf(".");
+    if (dot <= 0 || dot === entry.length - 1) {
+        throw new AclConfigError(`entrada de ACL inválida: "${entry}" (use recurso.acao, ex.: classes.edit)`);
+    }
+    const resource = entry.slice(0, dot);
+    const action = entry.slice(dot + 1);
+    const ids = map[resource]?.[action];
+    if (!ids)
+        throw new AclConfigError(`entrada de ACL inexistente no mapa do front: "${entry}"`);
+    return ids;
+}
+function union(lists) {
+    const out = [];
+    for (const list of lists)
+        for (const id of list)
+            if (!out.includes(id))
+                out.push(id);
+    return out;
+}
+/** Valida a regra contra o mapa e pré-calcula os identificadores. */
+function resolveAclRule(rule, map = map_generated_1.ACL_MAP) {
+    if (rule === "@authenticated" || rule === "@public") {
+        return { kind: rule === "@public" ? "public" : "authenticated", anyOf: [], allOf: [], anyOfIds: [], allOfIds: [] };
+    }
+    let anyOf;
+    let allOf;
+    if (typeof rule === "string") {
+        anyOf = [rule];
+        allOf = [];
+    }
+    else if (Array.isArray(rule)) {
+        anyOf = [...rule];
+        allOf = [];
+    }
+    else if (rule && typeof rule === "object") {
+        anyOf = [...(rule.anyOf ?? [])];
+        allOf = [...(rule.allOf ?? [])];
+    }
+    else {
+        throw new AclConfigError(`regra de ACL inválida: ${JSON.stringify(rule)}`);
+    }
+    if (anyOf.length === 0 && allOf.length === 0) {
+        throw new AclConfigError("regra de ACL vazia: informe ao menos uma entrada recurso.acao");
+    }
+    return {
+        kind: "entries",
+        anyOf,
+        allOf,
+        anyOfIds: union(anyOf.map(e => aclEntryIds(e, map))),
+        allOfIds: allOf.map(e => [...aclEntryIds(e, map)]),
+    };
+}
+/** Avalia a regra já resolvida contra as permissões do usuário. */
+function evaluateAclRule(userPermissions, rule) {
+    if (rule.kind !== "entries")
+        return true;
+    if (rule.anyOf.length > 0 && !checkAcl(userPermissions, rule.anyOfIds))
+        return false;
+    for (const ids of rule.allOfIds)
+        if (!checkAcl(userPermissions, ids))
+            return false;
+    return true;
+}
+//# sourceMappingURL=check.js.map

package/dist/acl/check.js.map

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

package/dist/acl/map.generated.d.ts

@@ -0,0 +1 @@
+export declare const ACL_MAP: Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>;