feat: implement Extensions with real FreeSWITCH directory integration
- extensions table (tenant-scoped, RLS): number, sip_password_enc
(AES-256-GCM via packages/shared/src/crypto.ts), caller_id, context,
sofia_profile, codecs, max_registrations
- apps/api/src/extensions: CRUD (POST/GET/GET:id/DELETE), protected by a
new generic PermissionGuard (@RequirePermission decorator), tenant
resolved only from the JWT (never trusted from the client)
- SIP password is returned in plaintext only once, in the create response;
toPublicExtension() explicitly destructures the encrypted field out
(not a spread) so it can't leak by accident
- b2bcall-fs-config now resolves real directory data: Tenant.telephonyDomain
-> Extension.number, decrypts the password, builds proper directory XML
including a dial-string param (missing it caused originate to fail with
MANDATORY_IE_MISSING instead of the expected USER_NOT_REGISTERED)
- pinned FreeSWITCH's 357737{domain} to a stable value (b2bcall.local) via a
vars.xml patch in the Dockerfile -- it previously used the container's
dynamic IP, which could never match a stored telephony_domain
- added HTTP Basic auth between FreeSWITCH and fs-config
(gateway-credentials, timingSafeEqual comparison) now that the service
returns real secret data, closing the gap flagged as pending in the XML
Curl phase instead of leaving it open
- found and fixed: PermissionGuard's constructor-injected Reflector came
back undefined at runtime under tsx/esbuild (unreliable cross-file
decorator metadata emission) -- fixed with an explicit @Inject(Reflector);
worth watching for in future guards/services run via tsx
- verified end-to-end: create extension -> originate user/<ext> reports
USER_NOT_REGISTERED (found, not registered) -> delete -> back to
SUBSCRIBER_ABSENT (not found); password never reappears in any GET;
unauthenticated fs-config requests get 401
- docs/EXTENSIONS.md
This commit is contained in:
115
docs/EXTENSIONS.md
Normal file
115
docs/EXTENSIONS.md
Normal file
@@ -0,0 +1,115 @@
|
||||
# Extensions (Ramais)
|
||||
|
||||
Primeira fase que dá dado real de negócio ao FreeSWITCH via `mod_xml_curl`
|
||||
(agente.md secao 39-40, 178).
|
||||
|
||||
## Modelo
|
||||
|
||||
`extensions` (tenant-scoped, RLS — mesmo padrão de `tenant_memberships`):
|
||||
`number`, `name`, `domain`, `sip_password_enc`, `caller_id_name/number`,
|
||||
`context`, `sofia_profile`, `codecs`, `max_registrations`, `enabled`.
|
||||
`UNIQUE(tenant_id, number)` — números só precisam ser únicos dentro do
|
||||
tenant (secao 34).
|
||||
|
||||
## Senha SIP (secao 178)
|
||||
|
||||
- Gerada com `generateStrongPassword()` (24 caracteres alfanuméricos,
|
||||
`crypto.randomBytes`).
|
||||
- Cifrada em repouso com AES-256-GCM (`packages/shared/src/crypto.ts`),
|
||||
chave em `ENCRYPTION_KEY` (.env, 32 bytes hex) — nunca no PostgreSQL.
|
||||
- **Só aparece em texto puro na resposta do `POST /extensions`, uma única
|
||||
vez.** `GET`/`list` nunca devolvem `sipPasswordEnc` nem a senha — a função
|
||||
`toPublicExtension()` faz destructuring explícito do campo (não spread) pra
|
||||
garantir isso é removido de fato, não só "esquecido" no tipo TypeScript.
|
||||
|
||||
## API (`apps/api/src/extensions`)
|
||||
|
||||
```
|
||||
POST /extensions extensions.manage cria (gera+cifra senha, devolve 1x)
|
||||
GET /extensions extensions.view lista (sem senha)
|
||||
GET /extensions/:id extensions.view detalhe (sem senha)
|
||||
DELETE /extensions/:id extensions.manage soft delete (deletedAt + enabled=false)
|
||||
```
|
||||
|
||||
Novo `PermissionGuard` genérico (`@RequirePermission('extensions.manage')`)
|
||||
— roda depois do `JwtAuthGuard`, exige tenant selecionado no JWT (nunca
|
||||
aceita tenant_id do client) e chama `userHasPermission()` de `packages/auth`.
|
||||
|
||||
**Achado real durante os testes**: o `PermissionGuard` injeta `Reflector` via
|
||||
construtor — padrão documentado do NestJS. Rodando via `tsx` (esbuild), o
|
||||
`reflector` chegava `undefined` em runtime (`TypeError: Cannot read
|
||||
properties of undefined`), porque esbuild não faz emissão de
|
||||
`design:paramtypes` com checagem de tipos completa entre arquivos (limitação
|
||||
conhecida do esbuild, diferente do `tsc`). Resolvido com `@Inject(Reflector)`
|
||||
explícito no construtor. Isso é um risco real pra qualquer guard/serviço
|
||||
futuro que dependa de injeção implícita de tipo — **usar `@Inject()`
|
||||
explícito sempre que o dev/runtime for via `tsx`**, ou considerar migrar
|
||||
`apps/api` pra build real (`tsc`) mais adiante.
|
||||
|
||||
## `b2bcall-fs-config` agora responde directory de verdade
|
||||
|
||||
Fluxo `section === "directory"`:
|
||||
|
||||
1. `Tenant.findFirst({ telephonyDomain: domain, status: "ACTIVE" })` — tenants
|
||||
não são RLS-protected (é o registro da plataforma).
|
||||
2. `withTenantContext(tenant.id) → Extension.findFirst({ number: user, enabled: true })`.
|
||||
3. `buildDirectoryUserXml()` (`packages/telephony`) monta o XML, incluindo
|
||||
`b2bcall_tenant_id`/`b2bcall_extension_id` como channel variables (secao 81
|
||||
— assim qualquer chamada desse ramal já carrega a origem).
|
||||
|
||||
**Achado real**: a primeira versão do XML não incluía o bloco
|
||||
`<domain><params><param name="dial-string".../></params></domain>` que a
|
||||
config vanilla tem em `directory/default.xml`. Sem isso, `originate
|
||||
user/1500 &park()` falhava com `MANDATORY_IE_MISSING` em vez do
|
||||
`USER_NOT_REGISTERED` esperado — o FreeSWITCH não sabia montar o dialstring
|
||||
pro endpoint `user/`. Corrigido copiando o mesmo template de `dial-string` da
|
||||
config vanilla.
|
||||
|
||||
## `$${domain}` fixo
|
||||
|
||||
`Tenant.telephonyDomain` precisa bater com o que o FreeSWITCH manda como
|
||||
`domain` no POST do xml_curl. Por padrão, a config vanilla usa
|
||||
`domain=$${local_ip_v4}` — o IP do container, que muda a cada restart e
|
||||
nunca seria estável o suficiente pra configurar em um tenant. Corrigido no
|
||||
`Dockerfile` do FreeSWITCH com um `sed` fixando `$${domain}` pra
|
||||
`b2bcall.local` (configurável via `ARG DEFAULT_SIP_DOMAIN`). Multi-domínio
|
||||
real por tenant (múltiplos domínios simultâneos, um por tenant) ainda não
|
||||
está resolvido — hoje só suporta um domínio fixo pra todos; isso é uma
|
||||
limitação genuína a resolver quando existir gestão de domínio por tenant de
|
||||
verdade (fora do escopo desta fase).
|
||||
|
||||
## Verificado ponta a ponta
|
||||
|
||||
```bash
|
||||
POST /extensions {"number":"1500","name":"Ramal de Teste"} # 201, senha aparece 1x
|
||||
GET /extensions/:id # confirma senha nunca reaparece
|
||||
|
||||
# fs-config resolve com a senha certa (decifrada corretamente):
|
||||
curl -d "section=directory&user=1500&domain=b2bcall.local" http://fs-config:8080/
|
||||
|
||||
# FreeSWITCH:
|
||||
originate user/1500 &park() # USER_NOT_REGISTERED (achou o ramal, sem telefone registrado)
|
||||
originate user/1501 &park() # SUBSCRIBER_ABSENT (nao existe)
|
||||
|
||||
DELETE /extensions/:id
|
||||
originate user/1500 &park() # volta a SUBSCRIBER_ABSENT
|
||||
```
|
||||
|
||||
## Autenticação HTTP `fs-config` ↔ FreeSWITCH
|
||||
|
||||
Adicionada nesta mesma fase (assim que o serviço passou a devolver dados
|
||||
reais, deixou de ser opcional): HTTP Basic, credenciais em `FS_CONFIG_USER`/
|
||||
`FS_CONFIG_PASSWORD` (.env, geradas com `openssl rand`). FreeSWITCH manda via
|
||||
`gateway-credentials` em `xml_curl.conf.xml` (substituído em runtime pelo
|
||||
`entrypoint.sh`, mesmo padrão do `ESL_PASSWORD` — nunca fica na imagem).
|
||||
`fs-config` compara com `timingSafeEqual` (evita timing attack), libera só
|
||||
`/health` sem auth (usado pelo healthcheck do Docker). Verificado: requisição
|
||||
sem credenciais recebe 401; o FreeSWITCH (com `gateway-credentials`
|
||||
configurado) continua funcionando normalmente.
|
||||
|
||||
## O que falta
|
||||
|
||||
- Quota de ramais (`max_extensions` do plano, secao 57) — depende da fase
|
||||
Plans/Entitlements, que ainda não existe.
|
||||
- Tela "Telefonia → Ramais" (frontend) — fase Frontend, bem mais adiante.
|
||||
- Multi-domínio real por tenant (ver acima).
|
||||
Reference in New Issue
Block a user