@puca/puca-core 14.11.2 → 14.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (29) hide show
  1. package/dist/core/services/install.service.js +25 -0
  2. package/dist/core/services/install.service.js.map +1 -1
  3. package/dist/core/services/report.service.d.ts +8 -0
  4. package/dist/core/services/report.service.js +81 -16
  5. package/dist/core/services/report.service.js.map +1 -1
  6. package/dist/core/services/table-permission.service.js +3 -1
  7. package/dist/core/services/table-permission.service.js.map +1 -1
  8. package/dist/models/crud-controller-especification-environment.d.ts +4 -1
  9. package/dist/models/crud-controller-especification.d.ts +4 -0
  10. package/dist/models/crud-controller-especification.js.map +1 -1
  11. package/dist/models/table-dictionary.d.ts +6 -0
  12. package/dist/orm/services/sql/column-security.helper.d.ts +22 -0
  13. package/dist/orm/services/sql/column-security.helper.js +108 -0
  14. package/dist/orm/services/sql/column-security.helper.js.map +1 -0
  15. package/dist/orm/services/sql/sql-security-layer.service.d.ts +4 -0
  16. package/dist/orm/services/sql/sql-security-layer.service.js +137 -9
  17. package/dist/orm/services/sql/sql-security-layer.service.js.map +1 -1
  18. package/dist/orm/services/sql/table-permission.helper.d.ts +2 -0
  19. package/dist/orm/services/sql/table-permission.helper.js +113 -1
  20. package/dist/orm/services/sql/table-permission.helper.js.map +1 -1
  21. package/dist/tsconfig.tsbuildinfo +1 -1
  22. package/docs/column-level-security/column-level-security-analysis.md +156 -0
  23. package/docs/column-level-security/column-level-security-by-rule-analysis.md +201 -0
  24. package/docs/column-level-security/dictionary-admin-permission-plan.md +164 -0
  25. package/docs/column-level-security/pending-flow-runtime-function-columns.md +39 -0
  26. package/docs/column-level-security/pending-javascript-source-columns.md +19 -0
  27. package/docs/column-level-security/puca-flow-dictionary-admin-exception-plan.md +164 -0
  28. package/package.json +1 -1
  29. package/sqli-pesquisa-consolidada.md +368 -0
@@ -0,0 +1,156 @@
1
+ # Análise e plano: column-level security na SqlSecurityLayer
2
+
3
+ **Status:** análise / plano (não implementado)
4
+ **Data:** 2026-07-27
5
+ **Escopo:** `@puca/puca-core` — ORM / security layer
6
+
7
+ ## Veredito
8
+
9
+ É **viável** limitar acesso a **colunas** reaproveitando a mesma [`SqlSecurityLayerService`](../../src/orm/services/sql/sql-security-layer.service.ts) que hoje limita acesso a **linhas**. O pipeline já percorre toda a árvore do Select (`fields`, `where`, `orderBy`, joins, CTEs); falta um segundo eixo de regras (`denyColumns`) na projeção e nos predicados.
10
+
11
+ Exemplo alvo: tabela `user` com coluna `password` — em listagens o valor não deve vazar (nullify); em filtros/ordenação o uso deve ser rejeitado (throw).
12
+
13
+ ---
14
+
15
+ ## Diagnóstico do que existe hoje
16
+
17
+ ### Row-level (implementado)
18
+
19
+ A security layer:
20
+
21
+ 1. Carrega `table_dictionary.rules` (`PermissionType` → `PermissionConfig`).
22
+ 2. Em `_safeResolveSelect`, injeta `WHERE` + CTEs de permissão (`user_access_*`, `rule_access_by_row_*`, etc.).
23
+ 3. Percorre `fields`, `where`, `orderBy`, `groupBy`, joins e CTEs via `_safeResolveValue` / `_safeResolveWhere`.
24
+ 4. **Não** inspeciona nomes de coluna para negar acesso.
25
+
26
+ Modelo atual em [`src/models/table-dictionary.ts`](../../src/models/table-dictionary.ts):
27
+
28
+ ```ts
29
+ export interface PermissionConfig {
30
+ args?: any;
31
+ where?: Where;
32
+ join?: JoinTable[];
33
+ accessControl?: UserAccessControlMode;
34
+ useAccessControl?: UserAccessControlMode;
35
+ useAccessControlEachRow?: UseAccessControlEachRow;
36
+ }
37
+ ```
38
+
39
+ ### Lacuna de coluna
40
+
41
+ - Qualquer `find`/`select` autenticado que inclua `password` (ou `SELECT *`) pode devolver o hash.
42
+ - Em [`select.service.ts`](../../src/orm/cases/vanilla/sql-builder/select.service.ts), `fields` vazio vira `SELECT *`.
43
+ - O `password` do user já tem tratamento parcial no domínio (`puca-base` user service); column security no ORM seria **defesa em profundidade** para CRUD genérico, reports, PQL, etc.
44
+
45
+ ```mermaid
46
+ flowchart TD
47
+ selectIn[Select PQL] --> ssl[SqlSecurityLayerService]
48
+ ssl --> rowRules["_tableRules: injeta WHERE/CTE"]
49
+ ssl --> colRules["NOVO: denyColumns em fields/where"]
50
+ colRules --> nullify["fields: password -> NULL as password"]
51
+ colRules --> throwStar["fields vazio / *: throw"]
52
+ colRules --> throwFilter["where/orderBy/groupBy: throw"]
53
+ rowRules --> sql[SelectService SQL]
54
+ nullify --> sql
55
+ throwStar --> reject[Reject query]
56
+ throwFilter --> reject
57
+ ```
58
+
59
+ ---
60
+
61
+ ## Estratégia recomendada
62
+
63
+ ### 1. Configuração: `denyColumns` estático em `PermissionConfig`
64
+
65
+ Primeira versão: lista estática por tabela/modo (começando por `select`), no mesmo lugar das rules de linha.
66
+
67
+ ```json
68
+ {
69
+ "select": {
70
+ "denyColumns": ["password"],
71
+ "where": { "...row rules existentes..." }
72
+ }
73
+ }
74
+ ```
75
+
76
+ Por que este modelo (e não role-based / `field_dictionary` nesta 1ª versão):
77
+
78
+ - Encaixa no pipeline que já carrega `td.rules` na layer.
79
+ - Casos como `password` são “sempre sensíveis” para usuários finais (exceto bypass já existente: `puca-user` + `DISABLE_PERMISSION_SYSTEM_FOR_PUCA_USER`, ou `disablePermissionSystem: true`).
80
+ - ACL por role/coluna pode evoluir depois reutilizando o mesmo ponto de interceptação.
81
+
82
+ ### 2. Comportamento híbrido
83
+
84
+ | Contexto | Comportamento |
85
+ | --- | --- |
86
+ | Projection (`select.fields`) | **nullify** — troca a coluna por literal `NULL` com o mesmo `alias` |
87
+ | `where` / `orderBy` / `groupBy` / `distinctOn` / `query` | **throw** — evita exfiltração por filtro/ordenação |
88
+ | `SELECT *` (`fields` vazio) | **throw** — sem expansão de colunas; caller deve declarar `fields` |
89
+
90
+ Não há suporte a `*`: se a tabela tiver `denyColumns` e `fields` estiver vazio, a layer lança exceção.
91
+
92
+ ### 3. Ponto de implementação
93
+
94
+ Dentro de `_safeResolveSelect` / `_safeResolveValue` (mesma árvore PQL já “segura” pela layer), não no front nem só no CrudService.
95
+
96
+ Esboço conceitual:
97
+
98
+ ```ts
99
+ // em PermissionConfig
100
+ denyColumns?: string[];
101
+
102
+ // projection: nullify
103
+ if (isDeniedColumn(fieldName, td?.rules?.select?.denyColumns)) {
104
+ return { field: { field: null, alias: fieldName }, args: {}, tables: [] };
105
+ }
106
+
107
+ // where/orderBy/etc: throw
108
+ // fields vazio com denyColumns: throw
109
+ ```
110
+
111
+ Identificação da coluna:
112
+
113
+ - string `'password'` / `'user.password'` / `{ table, field: 'password' }`
114
+ - join notation (`user__password`) quando o field apontar para a tabela denylisted
115
+ - funções / `conditions` que referenciem a coluna negada → tratar como uso → **throw**
116
+
117
+ ---
118
+
119
+ ## Plano de implementação (1ª entrega)
120
+
121
+ ### Tarefas
122
+
123
+ 1. **Estender modelo** — adicionar `denyColumns?: string[]` em `PermissionConfig` (`src/models/table-dictionary.ts`).
124
+ 2. **Interceptar select** — em `SqlSecurityLayerService`:
125
+ - nullify colunas negadas em `fields`;
126
+ - throw se `fields` vazio (`*`) e a tabela tiver `denyColumns`;
127
+ - throw se coluna negada aparecer em `where` / `orderBy` / `groupBy` / `distinctOn` / `query`.
128
+ 3. **Configurar user** — `rules.select.denyColumns: ['password']` na fonte de rules da tabela `user`.
129
+ 4. **Testes** — em `src/orm/services/sql/sql-security.service.spec.ts`: nullify em fields, throw em where, throw em `SELECT *`.
130
+
131
+ ### Arquivos principais
132
+
133
+ - `src/models/table-dictionary.ts`
134
+ - `src/orm/services/sql/sql-security-layer.service.ts`
135
+ - `src/orm/services/sql/sql-security.service.spec.ts`
136
+ - Configuração/geração de rules da tabela `user` (fora ou via `TablePermissionService` / especificação)
137
+
138
+ ### Fora do escopo imediato
139
+
140
+ - Bloquear `password` em `insert` / `update` (`set` / `values`)
141
+ - ACL por role/coluna dinâmica
142
+ - Flag no `field_dictionary` como fonte alternativa (pode alimentar o mesmo `denyColumns` depois)
143
+
144
+ ---
145
+
146
+ ## Limitações conscientes
147
+
148
+ - Consultas com `disablePermissionSystem: true` ou user `puca-user` (quando o bypass está ligado) **continuam vendo** a coluna — necessário para auth/hash interno.
149
+ - Subselects / `with` já passam por `_safeResolveSelect` recursivo; a regra deve valer em cada nível com `td.rules.select.denyColumns`.
150
+ - Nullify não impede que um serviço de domínio com `disablePermissionSystem` leia e devolva o hash; a proteção é para o caminho “usuário autenticado via ORM com permission system on”.
151
+
152
+ ---
153
+
154
+ ## Conclusão
155
+
156
+ O mecanismo de row-level já visita toda a árvore do Select. Column-level security é um segundo eixo (`denyColumns`) no mesmo ponto de interceptação, com comportamento híbrido: **null na listagem**, **throw em filtro** e **throw em `SELECT *`**. Isso cobre o caso `password` sem exigir expansão de `*` nem redesign do access control por linha.
@@ -0,0 +1,201 @@
1
+ # Análise: column-level security granular por Rule/User
2
+
3
+ **Status:** análise (parte da premissa de que `denyColumns` estático já existe)
4
+ **Data:** 2026-07-27
5
+ **Escopo:** `@puca/puca-core` — ORM / security layer + sistema de permissões (`rule` / `user`)
6
+ **Relacionado:** [column-level-security-analysis.md](./column-level-security-analysis.md)
7
+
8
+ ## Veredito
9
+
10
+ **Sim, é possível** — e encaixa bem no modelo que o sistema já usa para listagem/edição por papel (`UserAccessControlMode.Rule`) e por usuário (`User`).
11
+
12
+ A ideia: cada coluna sensível vira uma **permission boolean** (`{table}-column-{field}`), atribuível a **rules** (ou users), e a security layer decide em SQL (projection) ou rejeita (filtros) com base nessa permission — reutilizando `rulePermissionByName` / `userPermissionByName` e o mesmo `@userRules` / `@currentUser`.
13
+
14
+ ---
15
+
16
+ ## O que o sistema já oferece (base)
17
+
18
+ ### Permissions booleanas por nome
19
+
20
+ O install gera definitions em `puca_base_api_system_user_config_definition`, por exemplo:
21
+
22
+ - `{module}-access`
23
+ - `{table}-list` / `-new` / `-edit` / `-delete`
24
+
25
+ Valores ficam em:
26
+
27
+ - **Rule:** `puca_base_api_rule_config` (liga `rule` ↔ definition)
28
+ - **User:** `puca_base_api_system_user_config` (liga `system_user` ↔ definition)
29
+
30
+ ### Runtime na SqlSecurityLayer
31
+
32
+ Para row-level, a layer já:
33
+
34
+ 1. Cria CTEs via `rulePermissionByName(prefix, '{table}-list')` / `userPermissionByName(...)`.
35
+ 2. Injeta `WHERE EXISTS (SELECT 1 FROM rule_access_...)`.
36
+ 3. Resolve `@userRules` e `@currentUser` na execução do SQL (não no transform síncrono da layer).
37
+
38
+ Ou seja: a decisão “este usuário/papel tem a permission X?” **já é feita em SQL**, sem a `select()` da layer precisar ser async.
39
+
40
+ ### Expressão CASE no PQL
41
+
42
+ O ORM já tem `conditions` / `Case` em `SelectField` (`when` + `then` + `else`) — suficiente para:
43
+
44
+ ```sql
45
+ CASE WHEN EXISTS (SELECT 1 FROM col_access_user_password)
46
+ THEN "user".password
47
+ ELSE NULL
48
+ END AS password
49
+ ```
50
+
51
+ ---
52
+
53
+ ## Estratégia proposta (granular por rule)
54
+
55
+ ### Modelo de configuração
56
+
57
+ Estender o que veio do `denyColumns` estático para um mapa de acesso por coluna:
58
+
59
+ ```ts
60
+ // PermissionConfig (select)
61
+ denyColumns?: string[]; // ainda válido: always-deny (ex.: hash que ninguém vê via ORM)
62
+
63
+ columnAccess?: {
64
+ [columnName: string]: {
65
+ /** Rule | User — mesmo enum do row-level */
66
+ accessControl: UserAccessControlMode;
67
+ /** default: `${tableName}-column-${columnName}` */
68
+ permissionName?: string;
69
+ };
70
+ };
71
+ ```
72
+
73
+ Exemplo conceitual em `rules.select`:
74
+
75
+ ```json
76
+ {
77
+ "denyColumns": [],
78
+ "columnAccess": {
79
+ "password": {
80
+ "accessControl": "Rule",
81
+ "permissionName": "user-column-password"
82
+ },
83
+ "email": {
84
+ "accessControl": "Rule"
85
+ }
86
+ }
87
+ }
88
+ ```
89
+
90
+ Semântica:
91
+
92
+ | Situação | Efeito |
93
+ | --- | --- |
94
+ | Coluna só em `denyColumns` | Sempre nullify / throw em filtro (fase 1) |
95
+ | Coluna em `columnAccess` | Liberada só se EXISTS da permission CTE (rule/user) |
96
+ | Coluna em ambos | Tratar como erro de config, ou `denyColumns` vence |
97
+
98
+ ### Geração de permissions no install
99
+
100
+ Espelhar `-list` / `-edit` em [`install.service.ts`](../../src/core/services/install.service.ts):
101
+
102
+ - Para cada `columnAccess` da especificação/CRUD, criar definition:
103
+ - `name`: `user-column-password` (ou default `${table}-column-${field}`)
104
+ - `type`: boolean
105
+ - `description`: `Acesso à coluna password (User)`
106
+
107
+ Admin atribui essa flag às **rules** (tela de config de papel já existente).
108
+
109
+ ### Runtime na SqlSecurityLayer (projection)
110
+
111
+ Para cada field da projeção que bata em `columnAccess`:
112
+
113
+ 1. Garantir CTE `rule_access_col_{table}_{column}` (ou user) via helper já existente (`rulePermissionByName` / `userPermissionByName`).
114
+ 2. Trocar o field por:
115
+
116
+ ```ts
117
+ {
118
+ conditions: [{
119
+ when: { exists: { from: 'rule_access_col_user_password' } },
120
+ then: 'user.password', // ou field original
121
+ }],
122
+ else: null,
123
+ alias: 'password',
124
+ }
125
+ ```
126
+
127
+ Quem tem a rule com a flag ligada vê o valor; quem não tem recebe `NULL` — **sem throw** na listagem.
128
+
129
+ ### Runtime em where / orderBy / groupBy
130
+
131
+ Aqui está o ponto delicado: a `select()` da layer é **síncrona** e, no transform, `@userRules` ainda é placeholder — não dá para “saber” no JS se o user tem a permission sem:
132
+
133
+ - tornar o pipeline async e pré-consultar, ou
134
+ - adiar a decisão para SQL.
135
+
136
+ Opções práticas:
137
+
138
+ | Opção | Comportamento | Prós | Contras |
139
+ | --- | --- | --- | --- |
140
+ | **A (recomendada p/ sensíveis)** | Se coluna está em `columnAccess`/`denyColumns` e aparece em where/orderBy → **sempre throw** | Simples, sem side-channel, alinhado a `password` | Admin com permissão de *ver* também não filtra por ela |
141
+ | **B** | Pré-check async da permission antes do select | Throw só para quem não tem acesso | Exige mudar contrato sync da layer / executor |
142
+ | **C** | Permitir o predicado só “embrulhado” com `AND EXISTS(cte)` | Pure SQL | UX estranha (0 rows em vez de erro); orderBy ainda problemático |
143
+
144
+ **Recomendação:** opção **A** na 1ª entrega granular (igual à fase estática para filtros). Para `password`/tokens isso costuma ser o desejado. Se no futuro precisar filtrar colunas “semi-sensíveis” (ex.: e-mail) por papel, aí evoluir para **B**.
145
+
146
+ ### `SELECT *`
147
+
148
+ Mantém a regra da fase 1: **throw** se a tabela tiver `denyColumns` ou `columnAccess` e `fields` estiver vazio.
149
+
150
+ ```mermaid
151
+ flowchart TD
152
+ selectIn[Select com user] --> ssl[SqlSecurityLayer]
153
+ ssl --> rowCTE[CTEs row-level existentes]
154
+ ssl --> colCTE["CTEs columnAccess via rulePermissionByName"]
155
+ ssl --> proj{"field em columnAccess?"}
156
+ proj -->|sim| caseExpr["CASE WHEN EXISTS cte THEN col ELSE NULL"]
157
+ proj -->|nao| keep[field original]
158
+ ssl --> filter{"col em where/orderBy?"}
159
+ filter -->|sim| throwAlways[throw]
160
+ filter -->|nao| ok[segue]
161
+ caseExpr --> sql[SQL]
162
+ keep --> sql
163
+ rowCTE --> sql
164
+ colCTE --> sql
165
+ ```
166
+
167
+ ---
168
+
169
+ ## Por que isso é viável (e não um redesign)
170
+
171
+ 1. **Mesmo mecanismo de ACL** já usado em `-list` / `-edit` / module-access.
172
+ 2. **Mesmos helpers** (`rulePermissionByName`, `userPermissionByName`) e args (`@userRules`, `@currentUser`).
173
+ 3. **Mesmo ponto de interceptação** da fase `denyColumns` (projection / predicados).
174
+ 4. **CASE WHEN EXISTS** já expressável no PQL (`conditions`).
175
+ 5. Não exige resolver rules no Node no caminho sync — a decisão de *leitura do valor* fica no SQL.
176
+
177
+ ---
178
+
179
+ ## Limitações e riscos
180
+
181
+ - **Cardinalidade de permissions:** muitas colunas × muitas tabelas = muitas flags na UI de rule. Mitigar: só declarar `columnAccess` em colunas sensíveis; não em todas.
182
+ - **Filtros:** com opção A, ninguém (nem admin com flag) filtra/ordena pela coluna via ORM.
183
+ - **Bypass:** `disablePermissionSystem` / `puca-user` continuam fora do controle (necessário para auth).
184
+ - **Front:** listagens/forms podem precisar esconder inputs quando `NULL`/sem permissão (eval de config já existe para flags booleanas — a nova definition entra no mesmo fluxo).
185
+ - **Performance:** uma CTE extra por coluna sensível usada na query; normalmente poucas (password, token, etc.).
186
+
187
+ ---
188
+
189
+ ## Plano em alto nível (fase 2)
190
+
191
+ 1. Estender `PermissionConfig` com `columnAccess` (manter `denyColumns`).
192
+ 2. Na security layer: gerar CTEs + reescrever fields com `conditions` / CASE; throw em predicados; throw em `*`.
193
+ 3. No install / especificação CRUD: gerar `*-column-*` definitions a partir de `columnAccess`.
194
+ 4. Configurar caso piloto (ex.: `user.password` com `accessControl: Rule`).
195
+ 5. Testes: user **sem** rule → password null; user **com** rule → valor; where com password → throw; `fields` vazio → throw.
196
+
197
+ ---
198
+
199
+ ## Conclusão
200
+
201
+ Controle granular por **rule** (e, pelo mesmo caminho, por **user**) é natural no PUCA: basta tratar “ler coluna X” como mais uma permission booleana no ecossistema `system_user_config_definition` + `rule_config`, e usar `EXISTS` no SELECT (CASE) em vez de deny estático. A fase `denyColumns` continua como always-deny; `columnAccess` é o eixo condicional por papel.
@@ -0,0 +1,164 @@
1
+ # Plano: permissão `dictionary-admin`
2
+
3
+ **Status:** plano (não implementado)
4
+ **Data:** 2026-07-27
5
+ **Escopo:** escrita em `table_dictionary` / `field_dictionary` e APIs do `puca-crud` que as alteram
6
+ **Relacionado:** [puca-flow-dictionary-admin-exception-plan.md](./puca-flow-dictionary-admin-exception-plan.md)
7
+
8
+ ## Veredito
9
+
10
+ Introduzir a permission booleana **`dictionary-admin`** e torná-la o **único** gate de escrita de dicionário para usuários finais. Hoje o caminho oficial usa `puca-base-api-access` (módulo inteiro) e ainda há bypass via CRUD genérico (`user_table_dictionary` / update livre de `rules`).
11
+
12
+ ---
13
+
14
+ ## Problema atual
15
+
16
+ | Caminho | Gate hoje | Lacuna |
17
+ | --- | --- | --- |
18
+ | `POST .../user-table/:t/dictionary/table-headers` | `puca-base-api-access` | Permissão ampla de módulo; não é específica de dicionário |
19
+ | `POST/DELETE field_dictionary` (+ edit) | só `validateDictionary` / naming | Sem check de permission de admin |
20
+ | `connection-entity` (create/update/delete ref) | indireto via `FieldDictionaryService` | Herda a mesma lacuna |
21
+ | `POST user_table_dictionary` | `table_dictionary-edit` (Rule) | Pode gravar **qualquer coluna**, inclusive `rules` / `use_access_control` |
22
+ | `POST view` | CRUD view | Escreve em ambas as tabelas de dicionário |
23
+ | Install / migration / `puca-user` | `disablePermissionSystem` | OK (serviço interno) |
24
+
25
+ UI de configuração: `puca-crud-front/dictionary/:table` (`Dictionary.vue`) — edita `useAccessControl*` e o backend **recalcula** `rules`; não há editor de JSON de `rules`.
26
+
27
+ ---
28
+
29
+ ## Objetivo
30
+
31
+ 1. Criar definition `dictionary-admin` (boolean), atribuível a **rule** e/ou **user** (mesmo ecossistema de `*-access`).
32
+ 2. Só quem tem `dictionary-admin` (ou bypass interno já existente) pode **escrever** em:
33
+ - `field_dictionary`
34
+ - `table_dictionary` (incl. `rules`, `use_access_control*`, `parent_access_control`, layout/headers)
35
+ 3. Fechar bypass de script: body com `rules` / ACL no CRUD genérico deve ser rejeitado sem a permission.
36
+ 4. Leitura de dicionário permanece como está (não exige `dictionary-admin`).
37
+
38
+ ---
39
+
40
+ ## Modelo da permission
41
+
42
+ ### Definition
43
+
44
+ | Campo | Valor sugerido |
45
+ | --- | --- |
46
+ | `name` | `dictionary-admin` |
47
+ | `type` | boolean |
48
+ | `module` | `puca-base-api` (ou `puca-crud-api` — decidir: base é onde vive a UI de estrutura; crud é quem escreve) |
49
+ | `description` | `Administrar dicionário de tabelas e campos (criar/alterar/excluir schema e ACL de tabelas user_*)` |
50
+
51
+ **Recomendação de módulo:** `puca-base-api`, alinhado ao menu “Estrutura de Dados” e ao gate atual (`puca-base-api-access`).
52
+
53
+ ### Avaliação runtime
54
+
55
+ Reutilizar `UserConfigService.eval`:
56
+
57
+ ```ts
58
+ await userConfigService.eval({
59
+ moduleName: 'puca-base-api',
60
+ accessCondition: 'dictionary-admin',
61
+ user,
62
+ })
63
+ ```
64
+
65
+ Mesmo padrão de `puca-base-api-access` / `{table}-edit`.
66
+
67
+ ### Install
68
+
69
+ Em `install.service` / module especification de `puca-base` (ou `puca-crud`):
70
+
71
+ - Incluir `dictionary-admin` na lista de `permissions` booleanas geradas no install (junto com `{module}-access`).
72
+ - **Não** auto-atribuir a todas as rules; atribuir só a papéis admin (manual ou seed explícito).
73
+ - Migração de produto: quem hoje usa `puca-base-api-access` para dicionário precisa receber `dictionary-admin` (doc de rollout / script opcional).
74
+
75
+ ---
76
+
77
+ ## Validações no backend (obrigatórias)
78
+
79
+ Centralizar num helper, ex.: `assertDictionaryAdmin({ user, disablePermissionSystem })`:
80
+
81
+ ```ts
82
+ async function assertDictionaryAdmin(args: {
83
+ user: User;
84
+ disablePermissionSystem?: boolean;
85
+ }): Promise<void> {
86
+ if (args.disablePermissionSystem) return; // só paths internos já autenticados
87
+ if (args.user?.username === 'puca-user') return; // se política atual mantiver
88
+
89
+ const ok = await userConfigService.eval({
90
+ moduleName: 'puca-base-api',
91
+ accessCondition: 'dictionary-admin',
92
+ user: args.user,
93
+ });
94
+ if (!ok) throw new Error('Acesso negado: requer dictionary-admin');
95
+ }
96
+ ```
97
+
98
+ ### Pontos a proteger
99
+
100
+ 1. **`UserTableHeaderService.saveTableDictionary`** (`puca-crud`)
101
+ - Trocar `puca-base-api-access` → `dictionary-admin`.
102
+
103
+ 2. **`FieldDictionaryService`**
104
+ - `updateDictionary`, `dropField`, `editField` (e qualquer add column) → `assertDictionaryAdmin` no início.
105
+
106
+ 3. **`ConnectionEntityService`**
107
+ - create / update / remove reference (quando altera dicionário) → mesmo assert.
108
+
109
+ 4. **`UserTableDictionaryService.update` / `delete`**
110
+ - Assert em create/drop de tabela.
111
+ - Em `super.update`: **omit/reject** campos sensíveis (`rules`, `use_access_control`, `use_access_control_each_row`, `parent_access_control`) se o body tentar setá-los sem passar pelo fluxo de table-headers **ou** exigir `dictionary-admin` e ainda assim preferir regenerar `rules` via `computeTablePermission` (nunca confiar no JSON enviado).
112
+
113
+ 5. **`ViewService.update` / `delete`**
114
+ - Escrita em `table_dictionary` / `field_dictionary` → assert (ou path interno com `puca-user` já usado pelo flow).
115
+
116
+ 6. **`CrudFrontBaseService.updateEditorLayout`**
117
+ - Update de `crud_layout` em `table_dictionary` → assert (ou permission específica; por default incluir em `dictionary-admin`).
118
+
119
+ 7. **Controllers**
120
+ - Garantir que `disablePermissionSystem` continue restrito a `device === 'internal'` (já é o padrão no `CrudBaseController` / `user-table-manager`).
121
+
122
+ ### Política para coluna `rules`
123
+
124
+ - **Nunca** aceitar `rules` cru do client no CRUD.
125
+ - Sempre: client envia `use_access_control*` / `parent_access_control` → server chama `computeTablePermission` → grava `rules`.
126
+ - Isso fecha o bypass identificado na varredura anterior.
127
+
128
+ ---
129
+
130
+ ## Front (mínimo)
131
+
132
+ - `Dictionary.vue` / botão Dicionário: opcionalmente esconder ações de save se `!await puca.user.userConfigEval('puca-base-api', 'dictionary-admin')` (UX; segurança real é backend).
133
+ - Menus de “Estrutura de Dados” podem continuar em `puca-base-api-access` / menu-access; a escrita é que muda.
134
+
135
+ ---
136
+
137
+ ## Test plan
138
+
139
+ - [ ] User **sem** `dictionary-admin`: `POST table-headers` → 403/`Acesso negado`.
140
+ - [ ] User **sem** `dictionary-admin`: `POST field_dictionary` → negado.
141
+ - [ ] User **sem** `dictionary-admin`: `POST user_table_dictionary` com `{ rules: ... }` → negado / campo ignorado.
142
+ - [ ] User **com** `dictionary-admin`: consegue alterar ACL e campos em `user_*` via Dictionary UI.
143
+ - [ ] Chamada interna (`device=internal` + `disablePermissionSystem` ou `puca-user`) continua funcionando (install, flow setup).
144
+ - [ ] Leitura (`GET field_dictionary/search/...`, `GET table_dictionary/...`) **não** exige `dictionary-admin`.
145
+
146
+ ---
147
+
148
+ ## Ordem de implementação sugerida
149
+
150
+ 1. Gerar definition no install + seed/doc de atribuição.
151
+ 2. Helper `assertDictionaryAdmin`.
152
+ 3. Trocar gate em `saveTableDictionary`.
153
+ 4. Blindar `FieldDictionaryService` + `ConnectionEntityService`.
154
+ 5. Sanitizar update de `user_table_dictionary` / view (omit `rules`).
155
+ 6. Front: hide/disable save sem permission.
156
+ 7. Em seguida: exceção do flow ([plano irmão](./puca-flow-dictionary-admin-exception-plan.md)).
157
+
158
+ ---
159
+
160
+ ## Riscos
161
+
162
+ - Quebra quem hoje edita dicionário só com `puca-base-api-access` → precisa rollout da nova flag.
163
+ - Flow admin edita campos via `PucaFormLayoutCustomization` chamando `puca-crud-api` direto → **quebra** sem o plano de exceção do flow.
164
+ - `puca-user` / `disablePermissionSystem` continuam poderosos; manter restritos a device internal.
@@ -0,0 +1,39 @@
1
+ # Pendências: colunas `*_runtime*` / `*_rf` do puca-flow
2
+
3
+ **Status:** pendente
4
+ **Data:** 2026-07-27
5
+ **Escopo:** colunas de `puca_flow_api_step` que armazenam código JavaScript runtime (PucaCodeEditor)
6
+ **Tabela:** `puca_flow_api_step`
7
+
8
+ ---
9
+
10
+ ## Colunas
11
+
12
+ | Coluna |
13
+ | --- |
14
+ | `on_step_change_runtime_function` |
15
+ | `cron_trigger_runtime_function` |
16
+ | `step_requeriments_runtime_function` |
17
+ | `get_ola_runtime_function` |
18
+ | `on_task_update_runtime_function` |
19
+ | `allowed_rules_runtime_function` |
20
+ | `on_subcard_done_runtime_function` |
21
+ | `on_secondary_entity_change_rf` |
22
+
23
+ ---
24
+
25
+ ## Pendências
26
+
27
+ 1. **Adicionar permissão de leitura a estas colunas**
28
+ Declarar `columnAccess` (ou permission equivalente) para que o valor do código só seja retornado em SELECT para quem tiver a permissão de leitura definida.
29
+
30
+ 2. **Refatorar o código para buscar estas informações de um endpoint que valide se o usuário é admin**
31
+ Deixar de expor o source via CRUD/search genérico; criar endpoint dedicado que valide admin (ou papel equivalente) antes de devolver o conteúdo das colunas acima.
32
+
33
+ ---
34
+
35
+ ## Notas
36
+
37
+ - Ignorar colunas de comportamento/enum (ex.: `allowed_rules_runtime_function_behavior`).
38
+ - Ignorar FKs UUID (`*_function`, `*_source`) — não armazenam o código.
39
+ - Ignorar fórmulas/condições (`formula_*`, `cron_trigger_condition`, `external_link`, etc.) — fora do escopo “javascript source”.
@@ -0,0 +1,19 @@
1
+ # Pendências: colunas com código-fonte JavaScript
2
+
3
+ **Status:** pendente
4
+ **Data:** 2026-07-27
5
+ **Escopo:** column-level security apenas em colunas que armazenam source JavaScript (ignorar fórmulas, templates HTML, condições e FKs UUID)
6
+
7
+ ---
8
+
9
+ ## Lista de pendências
10
+
11
+ | # | View | Coluna | Ação pendente |
12
+ | --- | --- | --- | --- |
13
+ | 1 | `puca_indicators_api_data_source` | `script` | Definir e aplicar `columnAccess` no service do puca-indicators |
14
+
15
+ ---
16
+
17
+ ## Relacionado
18
+
19
+ - Runtime JS do flow: [pending-flow-runtime-function-columns.md](./pending-flow-runtime-function-columns.md)