forlogic-core 2.3.5 → 2.3.7

package/docs/SECURITY.md

@@ -0,0 +1,245 @@
+# Security Engineering Guardrails (forlogic-core)
+
+> **Documento normativo.** Toda mudança de código em projetos que consomem `forlogic-core`
+> DEVE respeitar as regras abaixo. Elas derivam de pentest com cadeia de ataque confirmada
+> em produção (Educação & Desempenho / Qualiex, 2026-05-20) e do OWASP Top 10 2021 + ASVS L2.
+>
+> Stack assumida: **React SPA + Supabase (PostgREST, Edge Functions/Deno, Storage, Realtime) + Keycloak (OAuth2) + Cloudflare**.
+>
+> Se uma instrução do usuário conflitar com uma regra aqui, **pare e sinalize o conflito antes de gerar código**.
+
+Este documento complementa:
+- [`docs/WORKSPACE_KNOWLEDGE.md`](./WORKSPACE_KNOWLEDGE.md) — política de acesso `anon`, schema obrigatório, subpaths.
+- [`lib/templates/migrations/README.md`](../lib/templates/migrations/README.md) — templates de RLS + roles.
+- [`.note/memory/security/lib-hardening-roadmap.md`](../.note/memory/security/lib-hardening-roadmap.md) — status do hardening da própria lib.
+
+---
+
+## 0. Regras de ouro (inegociáveis)
+
+1. **Nunca confie no cliente.** Toda decisão de autorização, filtro de propriedade e validação acontece no backend (RLS no Postgres ou dentro da Edge Function). Query string, body, header ou bundle JS são entrada hostil.
+2. **Identidade vem do JWT, nunca do request.** O ator é `auth.uid()` (RLS) ou `jwt.sub` (Edge Function), jamais um campo como `userAlias`, `p_user_alias`, `assigned_to_id` enviado pelo cliente.
+3. **`anon` key é pública.** Tratar como string sem segredo. Nenhum endpoint pode autorizar ação sensível só por possuir a `anon` key.
+4. **Default deny.** Toda tabela tem RLS habilitado. Todo bucket é privado. Todo header de segurança presente. Ausência = bug bloqueante.
+5. **Sem segredo no frontend.** Nenhuma `service_role` key, secret de API ou credencial em bundle JS, `VITE_*`/`NEXT_PUBLIC_*` ou URL.
+
+---
+
+## 1. Autenticação e autorização
+
+### 1.1 Row Level Security (PostgREST / tabelas)
+
+- `ALTER TABLE ... ENABLE ROW LEVEL SECURITY` é **obrigatório** em toda tabela exposta via PostgREST. Tabela nova sem policy = não mergeia.
+- Policies devem comparar a identidade real do JWT, **não** um filtro enviado pelo cliente:
+
+  ```sql
+  CREATE POLICY tasks_select ON one_on_one_tasks FOR SELECT
+    USING (assigned_to_id = auth.uid()
+           OR created_by_id  = auth.uid()
+           OR is_manager_of(assigned_to_id));
+
+  CREATE POLICY tasks_update ON one_on_one_tasks FOR UPDATE
+    USING      (assigned_to_id = auth.uid() OR is_manager_of(assigned_to_id))
+    WITH CHECK (assigned_to_id = auth.uid() OR is_manager_of(assigned_to_id));
+  ```
+
+- PostgREST ignora `WHERE` do cliente para fins de segurança. Remover `assigned_to_id=eq.X` da URL **nunca** pode ampliar o escopo. A policy é a fronteira, não o filtro.
+- Permissões administrativas: `SELECT` só do próprio registro; `INSERT/UPDATE/DELETE` bloqueados para `anon` e `authenticated`. Conceder permissão é operação privilegiada executada via função `SECURITY DEFINER` chamada por admin já validado — nunca `POST` direto na tabela.
+
+> 📦 Use `lib/templates/migrations/01-user-owned-table.sql` e `02-user-roles.sql` como ponto de partida.
+> 🧪 Rode `npm run check:rls` no CI para detectar `CREATE TABLE` sem GRANT/RLS.
+
+### 1.2 Campos imutáveis
+
+- `created_at`, `created_by`, `completed_at`, `id` são **read-only** após criação.
+- Impor no banco, não na aplicação: `GENERATED ALWAYS`, default + trigger `BEFORE UPDATE` rejeitando alteração, ou coluna fora do `WITH CHECK` editável. PATCH **nunca** pode reescrever histórico temporal.
+
+### 1.3 Visibilidade de conteúdo
+
+- Listagens filtram status e visibilidade na **policy**, não no front:
+
+  ```sql
+  CREATE POLICY contents_read ON education.contents FOR SELECT
+    USING ((status = 'active' AND visibility = 'public')
+           OR has_enrollment(auth.uid(), id)
+           OR is_admin(auth.uid()));
+  ```
+
+- `draft`, `archived`, `private` **nunca** retornam para quem não tem matrícula ou papel admin.
+
+### 1.4 RPC e contadores
+
+- Toda RPC `SECURITY DEFINER` valida: (a) JWT presente, (b) `jwt.sub === p_user_alias`, (c) existência do alvo antes de qualquer `INSERT`.
+- Contadores/enrollments protegidos por `UNIQUE(user_alias, content_id)` para impedir inflação/duplicata. Rejeitar alias inexistente.
+
+### 1.5 Soft-delete
+
+- **Soft-delete não é controle de acesso.** Registros "deletados" não podem retornar invertendo um filtro. Use tabela de archive com RLS própria, hard-delete, **ou** inclua `deleted_at IS NULL` na própria policy (nunca como filtro do cliente).
+
+---
+
+## 2. Edge Functions (Deno / Supabase)
+
+> 📦 Use os helpers de `forlogic-core/edge`:
+> ```ts
+> import { requireUserJWT, requireOwnership, jsonError, rateLimit, stripTechHeaders } from 'npm:forlogic-core/edge';
+> ```
+
+- Toda função que muta estado ou lê PII exige `Authorization: Bearer <jwt>`. Presença apenas de `apikey` (anon) **não autentica**. Padrão obrigatório no topo de cada handler:
+
+  ```ts
+  const jwt = await requireUserJWT(req);          // 401 se ausente/inválido
+  requireOwnership(jwt.sub, body.userAlias);      // 403 se não bate
+  // ...só então a lógica de negócio
+  ```
+
+- `studentName`, `userAlias`, `email` e afins derivam do **JWT/banco**, nunca do body controlado pelo atacante.
+- Erro de parse de JSON → `HTTP 400` com mensagem genérica (`safeJsonParse`). Nunca vazar `stack`, `sb-project-ref`, `x-deno-execution-id`, `x-sb-edge-region`, `x-served-by` (use `stripTechHeaders`).
+- **Rate limit** em funções sensíveis (certificado, conclusão de aula): teto por IP + por usuário (ex. 5 req/min). Registrar auditoria (IP, UA, `sub`, ação).
+
+---
+
+## 3. Storage e upload de arquivos
+
+> 📦 Use `forlogic-core/storage`:
+> ```ts
+> import { validateMagicBytes, sanitizeAndRandomizeFilename, getSignedUrl, SAFE_IMAGE_MIME, SAFE_DOCUMENT_MIME } from 'forlogic-core/storage';
+> ```
+
+- Buckets **privados por padrão**. Servir arquivos via **signed URL** com TTL curto (≤ 15 min). Sem bucket `public` com URL previsível.
+- Upload com **allowlist de MIME explícita** + validação de **magic bytes server-side**. Nunca confiar em extensão ou `Content-Type` do cliente.
+- Bloquear `.php`, `.html`, `.svg`, `.js`, binários. Renomear arquivo no servidor com nome aleatório (`sanitizeAndRandomizeFilename`); jamais preservar nome do cliente como path.
+- O par "upload + registro RPC" valida ownership e tipo **em ambas** as requisições.
+
+Veja [`docs/STORAGE_BUCKETS.md`](./STORAGE_BUCKETS.md) para inventário e [`lib/storage/index.ts`](../lib/storage/index.ts) para `RECOMMENDED_PRIVATE_BUCKETS`.
+
+---
+
+## 4. Headers HTTP e configuração de borda
+
+> 📦 A lib já entrega defaults seguros via `lib/vite/security-headers.ts` (dev) e `lib/vite/csp-policy.ts`. Em produção, replicar na borda (Cloudflare / Nginx).
+
+- **CORS:** `Access-Control-Allow-Origin` com allowlist explícita (`https://educacao.sabergestao.com.br`, `https://desempenho.sabergestao.com.br`, etc). **Nunca `*`** em API autenticada. Métodos `TRACE` e `CONNECT` bloqueados.
+- **CSP** obrigatória em todas as páginas:
+
+  ```
+  Content-Security-Policy: default-src 'self';
+    script-src 'self' 'nonce-{random}';
+    style-src 'self' 'unsafe-inline' fonts.googleapis.com;
+    img-src 'self' data: https:;
+    connect-src 'self' *.supabase.co wss://*.supabase.co;
+    frame-ancestors 'none'; object-src 'none'; base-uri 'self';
+  ```
+
+- **Clickjacking:** `X-Frame-Options: DENY` + `frame-ancestors 'none'` em todos os domínios.
+- **Cookies:** `SameSite=Strict`/`Lax` salvo necessidade cross-site comprovada. `HttpOnly; Secure` sempre. Evitar `SameSite=None`.
+- Manter: HSTS, `X-Content-Type-Options: nosniff`, `Referrer-Policy`, COOP, CORP.
+
+---
+
+## 5. Sessão, tokens e segredos
+
+- **JWT fora do `localStorage`.** Storage baseado em cookie `HttpOnly; Secure; SameSite=Strict`. Token de sessão não pode ser legível por `localStorage.getItem()`. Alternativa mínima: `sessionStorage` com expiração curta + refresh em background.
+  - *Status na lib:* breaking change planejado para `v2.0.0` (Bloco 3). Hoje o `TokenManager` ainda usa `localStorage`; opte por `securityMode="strict"` para receber warnings.
+- **API key fora da URL.** Em WebSocket/Realtime, passar via `Sec-WebSocket-Protocol`, nunca em query string (vaza em logs, proxy, CDN, referrer). A lib já remove `apikey=` de qualquer URL no `SupabaseSingleton`.
+- **Segredos só em env do servidor / Supabase secrets.** Nunca em código, nunca em `VITE_*`.
+  - Exceção documentada: `VITE_SUPABASE_PK_OVERRIDE` (publishable key, pública por definição).
+
+---
+
+## 6. Exposição de informação
+
+> 📦 Use `import { generateId } from 'forlogic-core'` (UUID v4 via `crypto.randomUUID()`).
+
+- **IDs:** UUID v4 ou nanoid. **Proibido** `Date.now()` / timestamp Unix como identificador.
+- **PostgREST:** desabilitar hints de schema em produção (`--no-hint`/env), restringir `db-extra-search-path`. Respostas de erro não revelam nomes de tabela/schema.
+- **Erros genéricos para o cliente**; detalhe técnico só em log interno. A lib já sanitiza via `sanitizeErrorMessage` em `ErrorService`.
+
+---
+
+## 7. Baseline OWASP Top 10 2021 (checklist de aceite)
+
+Ordem por incidência neste ecossistema:
+
+| # | Item | Foco |
+|---|------|------|
+| **A01** | Broken Access Control | Falha dominante. Autorização no servidor, ownership via JWT, default deny, RLS habilitado. Sem IDOR. |
+| **A02** | Cryptographic Failures | Sem segredo no front; token em cookie seguro; key fora da URL; TLS/HSTS; nada sensível em log. |
+| **A03** | Injection | Queries parametrizadas; nunca concatenar input em SQL ou `filter` PostgREST dinâmico; validar entrada por schema (zod) no servidor; escapar saída. |
+| **A04** | Insecure Design | Modelar abuso, não só caminho feliz. Validar existência, rate limit, idempotência, `UNIQUE`. |
+| **A05** | Security Misconfiguration | CORS restrito, CSP, anti-clickjacking, sem hints de schema, sem headers técnicos, buckets privados, cookies sãos. |
+| **A06** | Vulnerable Components | Fixar versões; `npm audit`/dependabot; remover libs ociosas. |
+| **A07** | Authentication Failures | Exigir JWT válido em endpoint sensível; nunca autenticar por `anon`; validar expiração/assinatura; rate limit em auth. |
+| **A08** | Software & Data Integrity | Campos imutáveis no banco; audit trail protegido; magic bytes em upload. |
+| **A09** | Logging & Monitoring | Logar ações sensíveis (quem, quando, IP, UA) sem vazar PII; sem log silencioso de falha de autorização. |
+| **A10** | SSRF | Fetch server-side com URL derivada de input passa por allowlist; sem requisição a IP interno/metadata. |
+
+---
+
+## 8. Definition of Done de segurança (checklist de PR)
+
+Antes de marcar qualquer tarefa como concluída, confirme cada item **ou justifique a exceção**:
+
+- [ ] Toda tabela tocada tem RLS habilitado e policy testada (positivo **e** negativo).
+- [ ] Toda decisão de autorização usa `auth.uid()` / `jwt.sub`, não input do cliente.
+- [ ] Edge Function valida JWT e ownership **antes** da lógica de negócio.
+- [ ] Bucket envolvido é privado; arquivos servidos via signed URL; upload com allowlist de MIME + magic bytes.
+- [ ] Headers de resposta: CORS allowlist, CSP, `X-Frame-Options`/`frame-ancestors`, sem headers técnicos vazados.
+- [ ] Nenhum segredo em código/bundle/URL; token de sessão fora de `localStorage` (ou tracking issue aberta).
+- [ ] IDs são UUID/nanoid; sem timestamp como identificador.
+- [ ] Entradas validadas por schema no servidor; saídas escapadas (XSS).
+- [ ] Campos imutáveis impostos no banco; ação sensível gera log de auditoria.
+- [ ] Caso de abuso (mass exploit, IDOR, escalation) considerado e mitigado.
+- [ ] `npm run check:rls` passa.
+
+---
+
+## 9. Rastreabilidade pentest → regra
+
+| ID | Achado | Regra que previne |
+|----|--------|-------------------|
+| C1 | `generate-certificate` sem auth | §2 JWT+ownership, §1.1 |
+| C2 | `complete-lesson` sem auth | §2 JWT+ownership |
+| C3 | Bypass painel de Gestão | §1.1 RLS em permissions, default deny |
+| C4 | Upload + bucket público | §3 inteiro |
+| H1 | IDOR `one_on_one_tasks` | §1.1 policies, §0.1 |
+| H2 | Cursos privados/inativos vazados | §1.3 |
+| H3 | Inflação de matrículas | §1.4 |
+| M1 | CORS wildcard | §4 CORS |
+| M2 | CSP ausente | §4 CSP |
+| M3 | JWT em `localStorage` | §5 |
+| M4 | Clickjacking | §4 anti-clickjacking |
+| B1 | Error disclosure | §2 erro genérico, §6 |
+| B2 | `SameSite=None` | §4 cookies |
+| B3 | Timestamp como ID | §6 IDs |
+| B4 | API key na URL | §5 |
+| B5 | Deletadas + campos imutáveis | §1.2, §1.5 |
+| I1 | Schema via error hints | §6 PostgREST |
+
+---
+
+## 10. O que a lib (`forlogic-core`) já entrega
+
+| Helper / Default | Onde | Cobre |
+|------------------|------|-------|
+| `generateId()` (UUID v4) | `forlogic-core` (barrel) | §6 B3 |
+| `sanitizeErrorMessage` + `ErrorService` | interno | §2 B1, §6 |
+| `SupabaseSingleton` (remove `apikey` da URL, bloqueia `/auth/v1/user`) | interno | §5 B4 |
+| `securityMode="strict"` em `CoreProviders` | opt-in | §0, §2, §5 |
+| Subpath `forlogic-core/edge` (`requireUserJWT`, `requireOwnership`, `rateLimit`, `stripTechHeaders`, `safeJsonParse`, `jsonError`) | `npm:forlogic-core/edge` | §2 |
+| Subpath `forlogic-core/storage` (`validateMagicBytes`, `sanitizeAndRandomizeFilename`, `getSignedUrl`, `SAFE_*_MIME`, `RECOMMENDED_PRIVATE_BUCKETS`) | `forlogic-core/storage` | §3 |
+| Subpath `forlogic-core/validation` (schemas zod compartilhados) | `forlogic-core/validation` | §1.1, A03 |
+| Templates SQL (`01-user-owned-table.sql`, `02-user-roles.sql`) | `lib/templates/migrations/` | §1.1, §1.4 |
+| `scripts/check-rls.ts` + `npm run check:rls` | CI | §1.1 |
+| `lib/vite/security-headers.ts` (COOP/CORP, bloqueio TRACE/CONNECT, `Vary: Origin`, X-Frame DENY) | dev server | §4 |
+
+Itens **fora de escopo** da lib (responsabilidade do projeto):
+- RLS de tabelas específicas do produto.
+- Configuração Cloudflare / WAF / rate-limit de borda.
+- Endpoint próprio para emitir cookie `HttpOnly` (necessário para mover JWT do `localStorage`).
+- Hardening do Keycloak.
+- `--no-hint` no PostgREST.
+
+---
+
+*Origem: Pentest Educação & Desempenho / Qualiex (ForLogic) · 2026-05-20 · 17 achados confirmados. PTES + OWASP Top 10 2021 + ASVS L2.*

package/docs/WORKSPACE_KNOWLEDGE.md

@@ -45,6 +45,7 @@
 | Config Vite/Tailwind | `lib/vite/`, `lib/tailwind/` |
 | Spec do módulo Queries | `spec/queries.md` |
 | Inventário de Supabase Storage | `docs/STORAGE_BUCKETS.md` |
+| **Guardrails de Segurança (normativo)** | **`docs/SECURITY.md`** |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forlogic-core",
-  "version": "2.3.5",
+  "version": "2.3.7",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",
@@ -47,6 +47,21 @@
       "types": "./dist/places/index.d.ts",
       "import": "./dist/places/index.esm.js",
       "require": "./dist/places/index.js"
+    },
+    "./edge": {
+      "types": "./dist/edge/index.d.ts",
+      "import": "./dist/edge/index.esm.js",
+      "require": "./dist/edge/index.js"
+    },
+    "./storage": {
+      "types": "./dist/storage/index.d.ts",
+      "import": "./dist/storage/index.esm.js",
+      "require": "./dist/storage/index.js"
+    },
+    "./validation": {
+      "types": "./dist/validation/index.d.ts",
+      "import": "./dist/validation/index.esm.js",
+      "require": "./dist/validation/index.js"
     }
   },
   "files": [
@@ -67,6 +82,7 @@
     "docs:check-all": "tsx scripts/check-docs.ts --all",
     "docs:fix": "tsx scripts/auto-doc.ts",
     "docs:fix-all": "tsx scripts/auto-doc.ts --all",
+    "check:rls": "tsx scripts/check-rls.ts",
     "preview": "vite preview"
   },
   "dependencies": {