fecadm — CLI + dashboard de administração

cactus-agents/fecadm é a ferramenta interna de administração de infraestrutura: gerencia Workers do Cloudflare, acesso de desenvolvedores (tokens e Zero Trust service tokens), disparo de CI/CD e monitoramento, nas contas CactusGaming e Bluetec.

É relevante para várias tarefas que a documentação de deploy descreve como "trabalho manual no dashboard CF": operações em lote de secrets nos front-web-*, rotação de chaves, criação/revogação de tokens de dev e de service tokens do Zero Trust.

:::info Local-only O fecadm não é deployado em lugar nenhum. Não há wrangler.*, Dockerfile nem script de deploy no repo. O dashboard web faz bind em 127.0.0.1 por design. O único CI é ci.yml (lint + typecheck + build) e delete-merged-branch.yml. :::

Não é clonado pelo setup default:

feca clone --tag admin

Estrutura

Monorepo pnpm com três packages:

Package	O que é
`@fecadm/core`	Biblioteca compartilhada: cliente da API CF, auth, banco, lógica de acesso. Build via `tsup`
`@fecadm/cli`	CLI com TUI em Ink. Declara `"bin": { "fecadm": "./build/index.js" }`
`@fecadm/web`	Servidor Hono + SPA React 19 (Vite, React Router 7, TanStack Query, Tailwind)

Superfície de capacidades exportada por @fecadm/core: cliente CF (CfClient, CfApiError), CfWorkersService, CfZeroTrustService, serviços por conta (createAccountServices, getAccountServices, listAllWorkers), acesso (createAccess, revokeAccess, listAccess, rotateServiceTokenAccess), tokens (generateToken, computeChecksum, normalizeUserId, userTokenSecretName), banco (getPool, query), e auth/auditoria (createSession, validateSession, verifyOtp, writeAuditLog, listAuditLogs, canWrite, isSuperAdmin).

CLI

Há um dispatcher bash em bin/fecadm que builda automaticamente se o build do CLI não existir, e roteia web para o servidor e o resto para o CLI.

Sem argumentos, abre a TUI interativa. Com argumento, executa direto:

fecadm                                   # TUI interativa
fecadm workers [--account <key>]         # lista workers
fecadm workers detail <worker-name>      # detalhe de um worker
fecadm access list [--account <key>]
fecadm access create <user-id> [--with-service-token] [--duration <days>]
fecadm access revoke <user-id>
fecadm config check                      # valida a configuração
fecadm web                               # sobe o dashboard

fecadm projects existe mas hoje só imprime Project status: coming soon.

:::info fecadm access create é o provisionamento do dev-proxy É este comando que cria a secret USER_TOKEN_UUID_<USERID> no front-service-api-dev-proxy, e é por isso que a lista de credenciais daquele worker não está em nenhum arquivo do repo dele. Ver Serviços de infraestrutura. :::

Dashboard web

pnpm build
node packages/web/build/server/index.js --port=4201
# http://127.0.0.1:4201

Em desenvolvimento, pnpm dev sobe Vite + Hono em paralelo. Portas usadas: 4200 (Vite HMR), 4201 (API Hono), 5439 (Postgres via docker-compose, que só levanta o postgres:17-alpine).

:::caution Passe --port explicitamente Sem --port=, o servidor cai no default 4200 — que é a porta do Vite HMR. O guia de start do repo instrui --port=4201. :::

Páginas

Rota	O que faz
`/`	Dashboard agregado, quick stats
`/localhost`	Controles do dev server local (feca dev/stop/sync/kill), git status dos repos
`/front-ssr`	Workers `front-web-` com health check, operações de secret em lote* e rotação de chaves
`/workers`	Todos os workers CF das contas, filtrável
`/workers/:account/:name`	Deployments, versions, analytics, secrets (carregados por card)
`/sites`	CI/CD do GitHub: runs de workflow, branches, dispatch
`/devops`	Load balancers, target groups, bancos, health checks, links de observabilidade
`/access`	Tokens de desenvolvedor e service tokens do Zero Trust
`/audit`	Todas as operações de escrita, com usuário, ação, target e metadata
`/settings`	Validação de config, status das contas
`/cache`	Existe no código (rota `cache`), não listada no README

:::caution README desatualizado A tabela de páginas do README.md do fecadm lista 10 rotas; o roteador do client registra 11 — a /cache está ausente do README (embora o .env.example e o guia de start a mencionem, incluindo que ela precisa de GITHUB_TOKEN e, opcionalmente, do escopo Zone: Cache Purge:Purge no token CF). Há também uma página de login que o README não conta. :::

RBAC e auditoria

Três roles:

Role	Permissões
`superadmin`	Tudo
`admin`	Leitura + escrita
`reader`	Somente leitura — bloqueado em escrita

A checagem é canWrite(role) (true para superadmin e admin) e isSuperAdmin(role).

Toda escrita é auditada. Um middleware intercepta requests /api/* com método POST, PUT, PATCH ou DELETE: se o role não pode escrever, responde 403 Read-only access. Write operations not allowed.; se pode, grava um registro em audit_logs (Postgres) com user_id, user_email, ação (<método>:<path>), target, metadata e IP. /api/auth/login e /api/auth/me são exceção (o login é logado separadamente como auth.login / auth.login_failed).

O metadata é filtrado contra uma lista de chaves sensíveis (password, token, secret, client_secret, otp_secret, checksum, …), substituídas por [REDACTED].

Autenticação: email + senha (bcrypt) + TOTP opcional; sessão como Authorization: Bearer <token>, com TTL de 24h no Postgres. O schema tem três tabelas: users, sessions, audit_logs.

Credenciais necessárias

Nomes de variáveis (do .env.example) — nunca valores:

Variável	Obrigatória	Para quê
`CF_API_TOKEN_CACTUS`	ao menos uma das duas	Conta Cactus
`CF_API_TOKEN_BLUETEC`	ao menos uma das duas	Conta Bluetec
`MAIN_TOKEN_CACTUS` / `MAIN_TOKEN_BLUETEC`	só para `access create`	Base do checksum dos tokens de dev
`DATABASE_URL`	opcional	Postgres; cai num default local
`GITHUB_TOKEN`	para as páginas Sites e Cache	Escopos `repo` + `workflow`

Escopos exigidos do token CF: Workers Scripts Read+Edit, Access: Service Tokens Read+Edit, Account Settings Read. Opcional: Zone: Cache Purge:Purge.

Metadados não-secretos das contas vivem em config/accounts.yaml.

Por que isso importa para o deploy

Dois pontos concretos onde o fecadm é o caminho, e não o dashboard CF:

Service tokens do Zero Trust. Os envs stage-* ficam atrás do Cloudflare Access, o que hoje força skip_post_deploy_purge e skip_asset_verify no deploy.yml. Cabear um Access service token no pipeline é o desbloqueio, e é o fecadm que gerencia esses tokens. Ver Adicionar conta CF.
Setup de vars/secrets em lote nos Workers. A Parte 3.2 do guia de environment descreve configurar variáveis worker por worker no dashboard; /front-ssr faz isso em lote, com auditoria.

Estrutura​

CLI​

Dashboard web​

Páginas​

RBAC e auditoria​

Credenciais necessárias​

Por que isso importa para o deploy​