--- epic_id: EPIC-01-auth-app-shell epic_name: Auth & App Shell priority: P0 estimated_waves: 12 estimated_total_points: 38 depends_on: [EPIC-00-foundation] exposes_contracts: - "hook.useAuth" - "hook.useUser" - "hook.useActiveOrg" - "hook.usePermission" - "middleware.ts" - "route./login" - "route./login/mfa" - "route./login/recovery" - "ui." - "ui." - "ui." - "ui." - "ui." - "layout.app-authenticated" - "cookie.sb-deskcomm-auth" status: completed created_at: 2026-04-28 owner: Rafael Melgaço --- # EPIC-01 — Auth & App Shell > **Para o epic-executor**: leia este arquivo inteiro antes de qualquer wave. Stories estão em ordem de dependência. Cada story = 1 wave. `Deps:` é lei. Toda wave passa por build → QA → fix → regression → checkpoint antes da próxima começar. ## 1. Objetivo Entregar autenticação completa (email+senha + MFA TOTP + recovery codes) com middleware de proteção de rotas, hooks canônicos de identidade (`useAuth`, `useUser`, `useActiveOrg`, `usePermission`), e o layout autenticado padrão (sidebar fixa 240px + topbar com tenant switcher, busca global Cmd+K e user menu) — base que TODOS os epics seguintes consomem. ## 2. Resultado esperado (Definition of Done do Epic) - [ ] Usuário não autenticado em `/app/*` ou `/admin/*` é redirecionado pra `/login?next=` pelo middleware - [ ] Usuário consegue logar em `/login` com email+senha e cair em `/app/inbox` (ou `next` query) - [ ] Admin/platform_admin com MFA cadastrado faz challenge TOTP em `/login/mfa` antes de logar - [ ] Admin/platform_admin sem MFA cadastrado é forçado a enrollar via modal blocker no primeiro login (com display once de 10 recovery codes + copy-to-clipboard) - [ ] Recovery code válido em `/login/recovery` reseta MFA do user (usado UMA vez, marcado `used_at`) - [ ] Logout limpa cookie `sb-deskcomm-auth` + redireciona pra `/login` - [ ] Layout `app/(app)/layout.tsx` renderiza com `` (Inbox, Kanban, Contacts, Settings, com Phosphor icons + collapse persistido em cookie) + `` (``, trigger Cmd+K, `` com avatar/logout/profile/theme) - [ ] Hooks `useAuth`, `useUser`, `useActiveOrg`, `usePermission(action)` disponíveis em `lib/auth/` e cobertos por unit test - [ ] Auto-refresh de sessão a cada 40min (`useAuth`) — JWT não expira em sessão longa - [ ] Audit actions emitidas: `auth.login_success`, `auth.login_failed`, `auth.mfa_enrolled`, `auth.mfa_failed`, `auth.logout`, `auth.recovery_code_used` - [ ] 100% das rotas protegidas falham fechado (redirect, nunca render parcial) - [ ] Regression suite cumulativa verde ## 3. Pré-requisitos - EPIC-00-foundation completo (Phosphor, sonner, TanStack Query, theme provider, test runners) - Migrations 0001-0007 do Supabase aplicadas (inclui `user_organizations`, `platform_admins`, `user_recovery_codes`, `api_audit_log`, helpers `fn_user_org_ids`, `fn_is_platform_admin`) - Variáveis env: `NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY`, `NEXT_PUBLIC_APP_URL` - Dev server rodando em `localhost:3001` - Playwright MCP conectado pra QA - Pelo menos 1 user seed: 1 admin com email/senha conhecida + 1 agent (Spec 01 §9.3 trigger T-06 já cobre) ## 4. Architecture Contracts ### 4.1 Contracts consumidos (de epics anteriores) | Contract ID | Tipo | Origem | Como usar | |---|---|---|---| | `infra.tanstack-query` | provider | EPIC-00 | `QueryClientProvider` no root layout | | `lib.toast` | lib | EPIC-00 | `toast.error(...)` em error handler | | `lib.phosphor` | lib | EPIC-00 | `import { House, ChatCircle, ... } from '@phosphor-icons/react'` | | `hook.useTheme` | react_hook | EPIC-00 | `` consome | | `hook.useApiClient` | react_hook | EPIC-00 | Server Actions usam server-side equivalent | | `db.user_organizations` | db_table | migration 0001 | Carrega orgs via RLS | | `db.platform_admins` | db_table | migration 0001 | Bypass de tenant pra super-admin | | `db.user_recovery_codes` | db_table | migration 0001 | Persiste hashes de recovery codes | | `db.api_audit_log` | db_table | migration 0001 | Insert append-only de audit actions | | `fn.fn_user_org_ids` | sql_fn | migration 0001 | RLS de tenant | | `fn.fn_is_platform_admin` | sql_fn | migration 0001 | Gating de `/admin/*` | ### 4.2 Contracts expostos (consumíveis por epics futuros) | Contract ID | Tipo | Wave que expõe | Descrição pra consumidores | |---|---|---|---| | `middleware.ts` | next_middleware | S-01.01 | Protege `/app/*` e `/admin/*`; injeta `x-request-id`; refresh JWT < 60s | | `route./login` | next_route | S-01.02 | Form email+senha; redirect pra `next` ou `/app/inbox` | | `action.signInWithPassword` | server_action | S-01.03 | `(input) => Promise<{ ok } \| { error: 'mfa_required' \| 'mfa_enrollment_required' \| 'invalid_credentials' \| 'rate_limited' }>` | | `route./login/mfa` | next_route | S-01.04 | TOTP 6 dígitos challenge | | `action.verifyMfa` | server_action | S-01.04 | `(code) => Promise<{ ok } \| { error }>` | | `route./login/recovery` | next_route | S-01.05 | Recovery code 8 chars; reset MFA | | `action.useRecoveryCode` | server_action | S-01.05 | `(email, code) => Promise<{ ok, reset_mfa: true }>` | | `hook.useAuth` | react_hook | S-01.06 | `() => { user, signOut, refreshing, isAuthenticated }` (auto-refresh 40min) | | `hook.useUser` | react_hook | S-01.06 | `() => User` (throws se ausente — usar dentro de `(app)` layout) | | `hook.useActiveOrg` | react_hook | S-01.06 | `() => { orgId, name, role }` | | `hook.usePermission` | react_hook | S-01.06 | `(action: string) => boolean` derivado da matriz RBAC Spec 01 §5 | | `action.signOut` | server_action | S-01.07 | `() => Promise` (limpa cookie + redirect) | | `layout.app-authenticated` | next_layout | S-01.08 | `app/(app)/layout.tsx` — sidebar 240px + topbar 56px | | `ui.` | react_component | S-01.09 | Phosphor icons; collapse via cookie `sidebar_collapsed` | | `ui.` | react_component | S-01.10 | Slots: tenant switcher, busca Cmd+K, user menu | | `ui.` | react_component | S-01.10 | Lista orgs do user; chama Server Action `setActiveOrg` | | `ui.` | react_component | S-01.10 | Avatar + dropdown logout/profile/theme | | `ui.` | react_component | S-01.10 | Wrapper sobre `useTheme` | | `ui.` | react_component | S-01.11 | Blocker; QR + TOTP input + display once recovery codes | | `ui.` | react_component | S-01.12 | Lista 10 codes com copy-all e download .txt | | `cookie.sb-deskcomm-auth` | cookie | S-01.01 | Nome canônico do cookie de sessão Supabase em todos os ambientes | | `cookie.active_org` | cookie | S-01.10 | `httpOnly`, `sameSite=strict` | | `cookie.sidebar_collapsed` | cookie | S-01.09 | Boolean `'1' \| '0'` | | `event.audit.auth.*` | domain_event | S-01.03/04/05/07 | Inseridos em `api_audit_log` (Spec 01 §6.1) | ## 5. Stories (em ordem de dependência) > Cada story abaixo vira UMA wave do epic-executor. Wave 1 = primeira story; wave 12 = última. Deps internos respeitados pela ordem. --- ### S-01.01 — Middleware de proteção de rotas **Points**: 3 | **Priority**: P0 | **Deps**: (none) | **FR refs**: Spec 09 §3.2, Spec 01 §4.1, Sitemap §1 #### Contexto Primeira pedra do shell autenticado. Sem middleware nada funciona — qualquer rota `/app/*` ou `/admin/*` precisa falhar fechado pra usuário sem cookie. Decisão lockada: **cookie name canônico = `sb-deskcomm-auth`** em todos os ambientes (dev/staging/prod). Lista pública (`PUBLIC_PATHS`) inclui `/`, `/login`, `/login/mfa`, `/login/recovery`, `/api/v1/webhooks/*`, `/api/v1/health`. `/admin/*` exige `fn_is_platform_admin()` true além de auth. #### Files to create - `middleware.ts` — proteção de rotas, refresh < 60s, inject `x-request-id` - `lib/auth/public-paths.ts` — array de regex compartilhado - `tests/middleware.spec.ts` — Playwright e2e #### Files to modify - `next.config.ts` — garantir `output: 'standalone'` ainda válido (não tocar se já ok) #### Implementation steps (sequential) 1. Criar `lib/auth/public-paths.ts` com `PUBLIC_PATHS` regex array 2. Criar `middleware.ts` espelhando Spec 09 §3.2 (createServerClient ssr, getUser, redirect com `next` query) 3. Adicionar gating de `/admin/*` via `supabase.rpc('fn_is_platform_admin')` → redirect `/403` se false 4. Configurar `matcher` excluindo assets estáticos 5. Forçar nome de cookie: `cookieOptions: { name: 'sb-deskcomm-auth', sameSite: 'strict', httpOnly: true, secure: true }` (dev pode `secure: false` via env) 6. Escrever Playwright spec #### Acceptance Criteria ```gherkin Given um usuário não autenticado When ele faz GET /app/inbox Then ele recebe 307 redirect pra /login?next=%2Fapp%2Finbox And nenhum HTML do shell é renderizado ``` ```gherkin Given um usuário autenticado como agent (sem platform_admin) When ele faz GET /admin/inbox Then ele recebe 307 redirect pra /403 ``` ```gherkin Given uma rota pública /api/v1/health When ela é acessada sem cookie Then retorna 200 sem redirect ``` ```gherkin Given um cookie com JWT que expira em <60s When middleware processa o request Then JWT é refreshado e Set-Cookie sai com novo token ``` #### QA test cases | ID | Tipo | Descrição | Como testar | |---|---|---|---| | t1 | e2e | Redirect anônimo | Playwright: `goto('/app/inbox')` → expect URL `/login?next=...` | | t2 | e2e | Redirect admin sem permissão | Login como agent, `goto('/admin')` → expect `/403` | | t3 | api | Health pública | `curl /api/v1/health` sem cookie → 200 | | t4 | api | Header injection | Inspect response headers em qualquer rota → `x-request-id` presente | | t5 | rls | Cookie name canônico | Inspect Set-Cookie em login → `sb-deskcomm-auth=...` | #### Architecture contracts emitted ```yaml exposes: - type: next_middleware id: "middleware.ts" behavior: "redirect_to_login_with_next + admin_gating + jwt_refresh" - type: cookie id: "sb-deskcomm-auth" options: "{ httpOnly, sameSite: strict, secure: true (prod), path: / }" ``` #### Decisões a registrar - **D-01.01**: Cookie de sessão chama-se `sb-deskcomm-auth` em todos os ambientes (locked) - **D-01.02**: `/admin/*` faz RPC `fn_is_platform_admin` no middleware (1 round-trip extra aceito por security) #### Definition of Done - [ ] Todos os ACs passam em Playwright - [ ] `pnpm typecheck` zero erros novos - [ ] `pnpm lint` zero erros novos - [ ] Sem warnings no console em dev - [ ] Commit `feat(EPIC-01): middleware [wave 1]` - [ ] Contracts registrados no state file - [ ] Sem regressão em waves anteriores (none — primeira wave) --- ### S-01.02 — Página `/login` com form email+senha **Points**: 3 | **Priority**: P0 | **Deps**: S-01.01 | **FR refs**: Sitemap §2 (`/login`), Journeys J1 step 1, ADR-08 #### Contexto Tela pública, server component que renderiza um `` client. Form via `react-hook-form` + Zod resolver (ADR-08). Não chama Server Action ainda — apenas valida e exibe states (loading/error). A action vem na próxima story. #### Files to create - `app/(public)/login/page.tsx` — server component (metadata, layout) - `app/(public)/layout.tsx` — layout público minimal (logo centralizada, sem sidebar) - `components/auth/LoginForm.tsx` — client component com RHF - `lib/auth/schemas.ts` — `loginSchema = z.object({ email, password })` #### Files to modify - (none) #### Implementation steps 1. Criar `(public)/layout.tsx` com container centralizado max-w-sm 2. Criar `loginSchema` em `lib/auth/schemas.ts` 3. Criar `` com fields email/password, useForm + zodResolver 4. Renderizar erros inline (``) e estado disabled durante submit 5. Wire submit handler com placeholder `console.log` (action vem em S-01.03) 6. Garantir aria-labels + autoComplete corretos (`email`, `current-password`) #### Acceptance Criteria ```gherkin Given anônimo em /login When ele submete email inválido Then erro "Email inválido" aparece inline sem navegar ``` ```gherkin Given /login carregada When usuário tab pelo form Then ordem é email → password → submit (a11y) ``` ```gherkin Given /login carregada via mobile (375px) When inspeciono layout Then card cabe sem scroll horizontal ``` #### QA test cases | ID | Tipo | Descrição | Como testar | |---|---|---|---| | t1 | ui | Form renderiza | Playwright: `getByLabel('Email')`, `getByLabel('Senha')`, `getByRole('button', { name: /Entrar/ })` | | t2 | ui | Validação Zod inline | Submit com email vazio → `getByText('Email obrigatório')` | | t3 | a11y | Tab order | Playwright: tab × 3 → submit focused | | t4 | ui | Mobile layout | Resize 375 → screenshot diff vs baseline | #### Architecture contracts emitted ```yaml exposes: - type: next_route id: "/login" component: "app/(public)/login/page.tsx" - type: react_component id: "" file: "components/auth/LoginForm.tsx" - type: zod_schema id: "loginSchema" file: "lib/auth/schemas.ts" ``` #### Decisões a registrar - **D-01.03**: Schemas de form moram em `lib/auth/schemas.ts`, compartilhados entre client e Server Action #### Definition of Done - [ ] ACs passam - [ ] Typecheck/lint limpos - [ ] Commit `feat(EPIC-01): /login page + form [wave 2]` - [ ] Regression: middleware ainda redireciona --- ### S-01.03 — Server Action `signInWithPassword` **Points**: 4 | **Priority**: P0 | **Deps**: S-01.02 | **FR refs**: Spec 01 §4.1, Spec 09 §11, ADR-02 #### Contexto Lógica server-side do login. Reuso do pseudo-código da Spec 01 §4.1 — Server Action (não API route) porque é form simples com revalidação. Trata 4 outcomes: ok / `invalid_credentials` / `mfa_required` / `mfa_enrollment_required` / `rate_limited`. Em `mfa_required` retorna sucesso parcial e redireciona pra `/login/mfa` (cookie `mfa_pending` curto). Em `mfa_enrollment_required` redireciona pra `/login/mfa` em modo enrollment (S-01.11 trata). #### Files to create - `app/actions/auth/signInWithPassword.ts` — Server Action - `lib/auth/server.ts` — `requireAuth()`, `loadUserOrgs()`, `checkPlatformAdmin()`, `isMfaEnrolled()` - `lib/audit/index.ts` — wrapper `audit({ action, actorUserId?, metadata?, requestId? })` - `lib/audit/actions.ts` — union type `AuditAction` (subset auth.* desta wave) #### Files to modify - `components/auth/LoginForm.tsx` — wire `useFormStatus` + invocação da action; redirect baseado em retorno #### Implementation steps 1. Criar `lib/audit/actions.ts` com union de `auth.*` (Spec 01 §6.1) 2. Criar `lib/audit/index.ts` com função `audit()` que insere em `api_audit_log` via service role 3. Criar helpers em `lib/auth/server.ts` 4. Criar Server Action `signInWithPassword` espelhando Spec 01 §4.1 pseudocódigo 5. Mapear erros pra discriminated union de retorno (sem throws) 6. No client: ao receber `mfa_required` → set cookie `mfa_pending` (1min) e `redirect('/login/mfa')` 7. Audit `auth.login_success` e `auth.login_failed` 8. Rate limit (Spec 01 §7.4) — 5 tentativas / 15min por IP+email_hash; em fallback degrada open #### Acceptance Criteria ```gherkin Given user agent com email/senha válidos sem MFA When submete /login Then cookie sb-deskcomm-auth é setado And redirect pra /app/inbox (ou next query) And api_audit_log tem row auth.login_success ``` ```gherkin Given email/senha errados When submete /login Then mensagem "Email ou senha incorretos" aparece And api_audit_log tem row auth.login_failed com email_hash ``` ```gherkin Given admin com MFA cadastrado When submete /login com creds válidas Then redirect pra /login/mfa And cookie mfa_pending=1 TTL 60s ``` ```gherkin Given mesmo IP+email faz 6 tentativas em <15min When submete a 6ª Then resposta { error: 'rate_limited' } e UI mostra cooldown ``` #### QA test cases | ID | Tipo | Descrição | Como testar | |---|---|---|---| | t1 | e2e | Login agent ok | Playwright: form submit → URL `/app/inbox` | | t2 | e2e | Login admin → mfa | Playwright: form submit admin → URL `/login/mfa` | | t3 | api | Audit row inserida | Supabase query `SELECT * FROM api_audit_log WHERE action='auth.login_success' ORDER BY created_at DESC LIMIT 1` | | t4 | e2e | Erro inválido | Submit com password errada → toast/inline "incorretos" | | t5 | rls | Rate limit | Loop 6 attempts → 6º bloqueado | | t6 | e2e | Next param respeitado | `/login?next=/app/contacts` → após login URL = `/app/contacts` | #### Architecture contracts emitted ```yaml exposes: - type: server_action id: "signInWithPassword" file: "app/actions/auth/signInWithPassword.ts" signature: "(input: { email, password }) => Promise<{ ok: true } | { ok: false; error: 'invalid_credentials' | 'mfa_required' | 'mfa_enrollment_required' | 'rate_limited'; details? }>" - type: lib id: "lib/audit" api: "audit({ action, actorUserId?, metadata?, requestId? })" - type: domain_event id: "audit.auth.login_success" payload: "{ user_id, is_platform_admin, orgs_count }" - type: domain_event id: "audit.auth.login_failed" payload: "{ email_hash, reason }" ``` #### Decisões a registrar - **D-01.04**: Login é Server Action (não `/api/v1/auth/login` route) — pra UI humana. Bearer/server-to-server sai por API route (vem em EPIC-10/11) - **D-01.05**: MFA pending state via cookie `mfa_pending` httpOnly TTL 60s #### Definition of Done - [ ] ACs passam (incluindo audit query) - [ ] Typecheck/lint limpos - [ ] Commit `feat(EPIC-01): signInWithPassword action [wave 3]` - [ ] Regression: anônimo ainda redirecionado; /login ainda renderiza --- ### S-01.04 — Página `/login/mfa` + verify **Points**: 3 | **Priority**: P0 | **Deps**: S-01.03 | **FR refs**: Spec 01 §4.1/§4.2, Journeys J1 step 2 #### Contexto Recebe usuário com cookie `mfa_pending=1`. Mostra `` (6 dígitos, auto-submit ao 6º char). Server Action `verifyMfa` chama `supabase.auth.mfa.challenge` + `verify`. Em sucesso: limpa `mfa_pending`, audit `auth.mfa_success` (alias de `login_success` com flag), redirect `next || /app/inbox`. Em falha: audit `auth.mfa_failed`, mensagem "Código inválido". 3 falhas → bloqueia 5min. #### Files to create - `app/(public)/login/mfa/page.tsx` - `components/auth/MfaForm.tsx` — `` (6 boxes com auto-advance) - `app/actions/auth/verifyMfa.ts` #### Files to modify - `lib/audit/actions.ts` — adicionar `auth.mfa_failed`, `auth.mfa_enrolled` ao union #### Implementation steps 1. Criar `` com 6 inputs `inputMode="numeric"` + auto-focus next 2. Criar page server component que verifica cookie `mfa_pending` ou redirect `/login` 3. Criar `verifyMfa` action espelhando Spec 01 §4.2 (challenge + verify) 4. Mapear erros: `mfa_invalid`, `mfa_expired`, `mfa_locked` (após 3 fails) 5. Audit em ambos os outcomes #### Acceptance Criteria ```gherkin Given user pós-login com mfa_pending=1 When digita TOTP correto Then sb-deskcomm-auth elevated, redirect /app/inbox And audit auth.mfa_success existe ``` ```gherkin Given mesmo user When erra TOTP 3x Then UI bloqueia por 5min com countdown And audit auth.mfa_failed × 3 existe ``` ```gherkin Given user sem mfa_pending tenta /login/mfa direto When abre URL Then redirect pra /login ``` #### QA test cases | ID | Tipo | Descrição | Como testar | |---|---|---|---| | t1 | e2e | Auto-advance TOTP | Playwright: type "1" no box 1 → focus box 2 | | t2 | e2e | Auto-submit ao 6º char | type 6 dígitos → form submitted sem clicar | | t3 | e2e | TOTP correto | gerar TOTP via lib (test fixture) → submit → /app/inbox | | t4 | api | Audit failed | submit "000000" → audit row mfa_failed | | t5 | e2e | Sem cookie → redirect | `goto('/login/mfa')` sem mfa_pending → /login | #### Architecture contracts emitted ```yaml exposes: - type: next_route id: "/login/mfa" - type: server_action id: "verifyMfa" signature: "(code: string) => Promise<{ ok } | { error: 'mfa_invalid' | 'mfa_expired' | 'mfa_locked' }>" - type: react_component id: "" ``` #### Definition of Done - [ ] ACs passam - [ ] Typecheck/lint limpos - [ ] Commit `feat(EPIC-01): mfa challenge [wave 4]` - [ ] Regression: agent sem MFA ainda loga direto --- ### S-01.05 — Página `/login/recovery` + reset MFA **Points**: 3 | **Priority**: P1 | **Deps**: S-01.04 | **FR refs**: Spec 01 §4.5, Journeys J4 step 2, Sitemap §2 #### Contexto Saída de emergência quando user perde TOTP. Form pede email + recovery code (8 chars). Server Action verifica hash em `user_recovery_codes` (single-use), marca `used_at`, força regeneração de TOTP no próximo login, emite `auth.recovery_code_used`. Após sucesso → redireciona pra `/login/mfa?enrollment=1` (S-01.11 recobre). #### Files to create - `app/(public)/login/recovery/page.tsx` - `components/auth/RecoveryForm.tsx` - `app/actions/auth/useRecoveryCode.ts` #### Files to modify - `lib/audit/actions.ts` — adicionar `auth.recovery_code_used` #### Implementation steps 1. Form `email + recovery_code` (RHF + Zod, code regex `[A-Z0-9]{8}`) 2. Action: `select id, code_hash, used_at from user_recovery_codes where user_id=(...) and code_hash=sha256($code) and used_at is null` 3. Se válido: `update used_at=now(), used_ip=...`; resetar TOTP via `supabase.auth.admin.mfa.deleteFactor` (todos factors) 4. Audit `auth.recovery_code_used` com `metadata: { masked_code }` 5. Redirect pra `/login/mfa?enrollment=1` #### Acceptance Criteria ```gherkin Given user admin com recovery code válido não-usado When submete email + code corretos Then used_at é setado em user_recovery_codes And audit auth.recovery_code_used existe And redirect pra /login/mfa?enrollment=1 ``` ```gherkin Given recovery code já usado (used_at != null) When submete Then erro "Código inválido ou já utilizado" And nenhuma mutation feita ``` ```gherkin Given recovery code não cadastrado When submete Then mesma mensagem genérica (sem leak de existência) ``` #### QA test cases | ID | Tipo | Descrição | Como testar | |---|---|---|---| | t1 | e2e | Recovery flow ok | Seed code → submit → URL `/login/mfa?enrollment=1` | | t2 | db | Single-use enforced | Tentar mesmo code 2× → 2ª falha | | t3 | api | Audit row | Query `auth.recovery_code_used` | | t4 | e2e | Mensagem genérica | Code inválido vs já-usado → mesma mensagem | #### Definition of Done - [ ] ACs passam - [ ] Commit `feat(EPIC-01): recovery code flow [wave 5]` - [ ] Regression: login normal + MFA ainda funcionam --- ### S-01.06 — Hooks `useAuth`, `useUser`, `useActiveOrg`, `usePermission` **Points**: 4 | **Priority**: P0 | **Deps**: S-01.05 | **FR refs**: Spec 09 §13 Tier 1, Spec 01 §5 RBAC #### Contexto Coração do shell. Hooks ficam em `lib/auth/hooks/` (NÃO em `hooks/` direto — convenção pra auth domain). `useAuth` faz auto-refresh com `setInterval(40min)` chamando `supabase.auth.refreshSession()` (Spec 09 §3.6). `usePermission` lê role do `useActiveOrg` e cruza com matriz RBAC declarada em `lib/auth/rbac.ts` (Spec 01 §5). #### Files to create - `lib/auth/hooks/useAuth.ts` - `lib/auth/hooks/useUser.ts` - `lib/auth/hooks/useActiveOrg.ts` - `lib/auth/hooks/usePermission.ts` - `lib/auth/rbac.ts` — matriz `Role × Action → boolean` - `lib/auth/AuthProvider.tsx` — context + initial bootstrap from server - `tests/auth/hooks.spec.ts` — Vitest unit #### Files to modify - `app/(app)/layout.tsx` — wrap em `` (placeholder; layout completo em S-01.08) #### Implementation steps 1. Criar matriz RBAC em `lib/auth/rbac.ts` cobrindo todas as actions da Spec 01 §5 2. Criar `` que recebe `initialUser`, `initialOrgs`, `initialActiveOrg` do server e popula context + TanStack Query cache (`['auth']`, `['orgs']`, `['active-org']`) 3. `useAuth`: retorna `{ user, isAuthenticated, signOut, refreshing }` + `useEffect` com `setInterval(40 * 60_000)` chamando `refreshSession` 4. `useUser`: throws se ausente (uso só dentro de `(app)`) 5. `useActiveOrg`: lê de query cache + cookie `active_org` 6. `usePermission(action)`: cruza role de `useActiveOrg` com `rbac[role][action]`; super-admin sempre true 7. Unit tests pra rbac matrix + hooks (renderHook) #### Acceptance Criteria ```gherkin Given useAuth montado em /app/inbox When 40min passam Then refreshSession é chamada e novo JWT cookie é setado ``` ```gherkin Given user agent com active org X When chama usePermission('leads.delete') Then retorna false ``` ```gherkin Given user admin When chama usePermission('leads.delete') Then retorna true ``` ```gherkin Given platform_admin When chama usePermission(qualquer action sensata) Then retorna true ``` #### QA test cases | ID | Tipo | Descrição | Como testar | |---|---|---|---| | t1 | unit | RBAC matrix | Vitest: `rbac.agent['leads.delete']` === false | | t2 | unit | usePermission | renderHook com mock active org agent → permission false | | t3 | e2e | Auto-refresh | Spy em `refreshSession`, fast-forward timer 40min → spy called | | t4 | unit | useUser throws | render fora de provider → throws | #### Architecture contracts emitted ```yaml exposes: - type: react_hook id: "useAuth" file: "lib/auth/hooks/useAuth.ts" signature: "() => { user, isAuthenticated, signOut, refreshing }" - type: react_hook id: "useUser" signature: "() => User" # throws - type: react_hook id: "useActiveOrg" signature: "() => { orgId, name, role: 'viewer'|'agent'|'manager'|'admin' }" - type: react_hook id: "usePermission" signature: "(action: string) => boolean" - type: lib id: "lib/auth/rbac" description: "Matriz declarativa Role × Action conforme Spec 01 §5" ``` #### Decisões a registrar - **D-01.06**: Hooks de auth ficam em `lib/auth/hooks/`, não em `hooks/` (separação de domínio crítico) - **D-01.07**: Auto-refresh JWT a cada 40min via `setInterval` no `useAuth` — JWT TTL Supabase default 1h #### Definition of Done - [ ] Unit tests passam (Vitest) - [ ] Commit `feat(EPIC-01): auth hooks + RBAC matrix [wave 6]` - [ ] Regression: login flows ainda OK --- ### S-01.07 — Logout **Points**: 2 | **Priority**: P0 | **Deps**: S-01.06 | **FR refs**: Spec 01 §6.1 `auth.logout` #### Contexto Server Action `signOut` que chama `supabase.auth.signOut()` server-side, deleta cookies (`sb-deskcomm-auth`, `active_org`, `mfa_pending` se existir, `sidebar_collapsed`), audit `auth.logout`, `redirect('/login')`. Botão dispara via `` (componente vem em S-01.10, mas action precisa estar pronta). #### Files to create - `app/actions/auth/signOut.ts` #### Files to modify - `lib/auth/hooks/useAuth.ts` — wire `signOut` no retorno #### Implementation steps 1. Server Action `signOut` com `requireAuth()` no topo 2. `supabase.auth.signOut({ scope: 'local' })` (não desloga outros devices) 3. Limpar cookies via `cookies().delete(...)` 4. Audit `auth.logout` 5. `redirect('/login')` #### Acceptance Criteria ```gherkin Given user autenticado When chama signOut Then cookie sb-deskcomm-auth removido And redirect pra /login And audit auth.logout existe ``` ```gherkin Given após logout When tenta /app/inbox Then redirecionado pra /login (middleware) ``` #### QA test cases | ID | Tipo | Descrição | Como testar | |---|---|---|---| | t1 | e2e | Logout limpa cookie | Login → invocar action → cookie ausente | | t2 | e2e | Pós-logout protected | goto /app/inbox → /login | | t3 | api | Audit row | query `auth.logout` | #### Definition of Done - [ ] ACs passam - [ ] Commit `feat(EPIC-01): signOut action [wave 7]` --- ### S-01.08 — Layout `app/(app)/layout.tsx` **Points**: 3 | **Priority**: P0 | **Deps**: S-01.07 | **FR refs**: Sitemap §3 (Layout pai `/app`), Components §00-overview #### Contexto Shell autenticado base. Grid: sidebar fixa 240px (collapsable pra 64px) + topbar fixa 56px + main area com ``. Server component que faz `requireAuth()`, carrega user/orgs/active-org e injeta no ``. Reserva slots pros componentes que vêm nas próximas waves (Sidebar S-01.09, TopBar S-01.10). #### Files to create - `app/(app)/layout.tsx` — server component - `app/(app)/_components/AppShell.tsx` — client wrapper que usa cookie `sidebar_collapsed` - `app/(app)/page.tsx` — redirect pra `/app/inbox` (placeholder até EPIC-03) #### Files to modify - (none) #### Implementation steps 1. Layout server component: `requireAuth()` + `loadUserOrgs()` + read cookie `active_org` 2. Pass initial state pro `` (S-01.06) 3. `` client com grid 240px / 1fr e topbar absoluta 4. Slots placeholder pra Sidebar e TopBar (renderiza `