Validação de CPF em Deno com Oak Framework

Deno é um runtime JavaScript e TypeScript criado por Ryan Dahl — o mesmo criador do Node.js — com foco em segurança, simplicidade e compatibilidade com padrões web. Diferente do Node.js, o Deno suporta TypeScript nativamente, possui fetch como API global e utiliza um modelo de permissões granular que impede acesso não autorizado a rede, sistema de arquivos e variáveis de ambiente. Para integrar a API da CPFHub.io em Deno, você não precisa de nenhuma dependência adicional para o cliente HTTP — o fetch nativo e o framework Oak são suficientes para criar um endpoint de validação de CPF seguro e testável.

Consulta de CPF com fetch nativo do Deno

O Deno implementa a Fetch API do navegador como função global, sem necessidade de imports. Veja como consultar a API da CPFHub.io:

// cpfhub_service.ts

interface CPFData {
    cpf: string;
    name: string;
    nameUpper: string;
    gender: string;
    birthDate: string;
    day: number;
    month: number;
    year: number;
}

interface CPFApiResponse {
    success: boolean;
    data?: CPFData;
}

interface ConsultaResultado {
    sucesso: boolean;
    dados?: CPFData;
    erro?: string;
}

const API_URL = "https://api.cpfhub.io/cpf";
const API_KEY = Deno.env.get("CPFHUB_API_KEY") ?? "";
const TIMEOUT_MS = 10000;

export async function consultarCPF(cpf: string): Promise<ConsultaResultado> {
    const cpfLimpo = cpf.replace(/\D/g, "");

    if (cpfLimpo.length !== 11) {
    return { sucesso: false, erro: "CPF deve conter 11 digitos" };
    }

    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);

    try {
    const response = await fetch(`${API_URL}/${cpfLimpo}`, {
    method: "GET",
    headers: {
    "x-api-key": API_KEY,
    "Accept": "application/json",
    },
    signal: controller.signal,
    });

    clearTimeout(timeoutId);

    if (!response.ok) {
    return {
    sucesso: false,
    erro: `API retornou status ${response.status}`,
    };
    }

    const resultado: CPFApiResponse = await response.json();

    if (!resultado.success || !resultado.data) {
    return { sucesso: false, erro: "CPF nao encontrado" };
    }

    return { sucesso: true, dados: resultado.data };
    } catch (error) {
    clearTimeout(timeoutId);

    if (error instanceof DOMException && error.name === "AbortError") {
    return { sucesso: false, erro: "Timeout na consulta de CPF" };
    }

    return {
    sucesso: false,
    erro: `Erro na requisicao: ${(error as Error).message}`,
    };
    }
}

Para executar, o Deno exige permissões explícitas:

deno run --allow-net=api.cpfhub.io --allow-env=CPFHUB_API_KEY cpfhub_service.ts

A flag --allow-net=api.cpfhub.io restringe o acesso de rede exclusivamente ao domínio da API. Isso garante que, mesmo que o código seja comprometido, ele não pode se comunicar com outros servidores.

Criando uma API REST com Oak

Oak é o framework HTTP mais utilizado no Deno, inspirado no Koa do Node.js. Consulte a documentação oficial do Oak para detalhes sobre middlewares e roteamento. Veja como criar um endpoint de validação de CPF:

// server.ts
import { Application, Router, Context } from "https://deno.land/x/oak@v12.6.1/mod.ts";
import { consultarCPF } from "./cpfhub_service.ts";

const router = new Router();

router.get("/api/validar-cpf/:cpf", async (ctx: Context) => {
    const cpf = ctx.params.cpf;

    if (!cpf) {
    ctx.response.status = 400;
    ctx.response.body = { erro: "CPF e obrigatorio" };
    return;
    }

    const resultado = await consultarCPF(cpf);

    if (!resultado.sucesso) {
    ctx.response.status = resultado.erro?.includes("nao encontrado") ? 404 : 500;
    ctx.response.body = { erro: resultado.erro };
    return;
    }

    ctx.response.body = {
    valido: true,
    dados: {
    nome: resultado.dados!.name,
    genero: resultado.dados!.gender,
    dataNascimento: resultado.dados!.birthDate,
    },
    };
});

router.get("/health", (ctx: Context) => {
    ctx.response.body = { status: "ok", timestamp: new Date().toISOString() };
});

const app = new Application();

// Middleware de log
app.use(async (ctx, next) => {
    const inicio = Date.now();
    await next();
    const duracao = Date.now() - inicio;
    console.log(
    `${ctx.request.method} ${ctx.request.url.pathname} - ${ctx.response.status} (${duracao}ms)`
    );
});

// Middleware de tratamento de erros
app.use(async (ctx, next) => {
    try {
    await next();
    } catch (error) {
    console.error("Erro nao tratado:", error);
    ctx.response.status = 500;
    ctx.response.body = { erro: "Erro interno do servidor" };
    }
});

app.use(router.routes());
app.use(router.allowedMethods());

const PORT = parseInt(Deno.env.get("PORT") ?? "8000");
console.log(`Servidor Oak rodando em http://localhost:${PORT}`);
await app.listen({ port: PORT });

Execute com as permissões necessárias:

deno run \
    --allow-net=api.cpfhub.io,0.0.0.0:8000 \
    --allow-env=CPFHUB_API_KEY,PORT \
    server.ts

Middleware de rate limiting com Oak

Para proteger a API contra abusos, implemente um middleware de rate limiting:

// middleware/rate_limiter.ts
import { Context, Next } from "https://deno.land/x/oak@v12.6.1/mod.ts";

interface RateLimitEntry {
    count: number;
    resetAt: number;
}

const limites = new Map<string, RateLimitEntry>();
const MAX_REQUESTS = 10;
const WINDOW_MS = 60000; // 1 minuto

export async function rateLimiter(ctx: Context, next: Next) {
    const ip = ctx.request.ip;
    const agora = Date.now();
    const entry = limites.get(ip);

    if (!entry || entry.resetAt < agora) {
    limites.set(ip, { count: 1, resetAt: agora + WINDOW_MS });
    await next();
    return;
    }

    if (entry.count >= MAX_REQUESTS) {
    ctx.response.status = 429;
    ctx.response.body = {
    erro: "Limite de requisicoes excedido. Tente novamente em 1 minuto.",
    };
    return;
    }

    entry.count++;
    await next();
}

Adicione ao servidor antes das rotas:

app.use(rateLimiter);
app.use(router.routes());

Testes com Deno.test

O Deno inclui um framework de testes nativo. Veja como testar o serviço de CPF:

// cpfhub_service_test.ts
import { assertEquals } from "https://deno.land/std@0.208.0/assert/mod.ts";
import { consultarCPF } from "./cpfhub_service.ts";

Deno.test("CPF com menos de 11 digitos retorna erro", async () => {
    const resultado = await consultarCPF("1234");
    assertEquals(resultado.sucesso, false);
    assertEquals(resultado.erro, "CPF deve conter 11 digitos");
});

Deno.test("CPF formatado e limpo corretamente", async () => {
    const resultado = await consultarCPF("123.456.789-00");
    assertEquals(resultado.sucesso, false);
});

Execute os testes:

deno test --allow-net=api.cpfhub.io --allow-env=CPFHUB_API_KEY

Modelo de permissões do Deno para segurança

O modelo de permissões do Deno é particularmente valioso quando se trabalha com APIs que usam chaves secretas:

Permissão	Flag	Uso na integração
Rede	`--allow-net=api.cpfhub.io`	Restringir acesso ao domínio da API
Variáveis de ambiente	`--allow-env=CPFHUB_API_KEY`	Acesso apenas à chave necessária
Leitura de arquivos	`--allow-read=.env`	Ler arquivo de configuração

Essa granularidade impede que vulnerabilidades no código acessem recursos não autorizados — uma vantagem significativa sobre o Node.js para aplicações que lidam com dados sensíveis como CPF.

Deploy com Deno Deploy

Para colocar a aplicação em produção, o Deno Deploy é a opção mais simples. No Deno Deploy, as variáveis de ambiente são configuradas no dashboard do projeto, mantendo a chave de API segura. A integração com GitHub permite deploy automático a cada push.

Perguntas frequentes

Qual a vantagem de usar o Deno para integrar uma API de CPF?

O Deno elimina a necessidade de configurar bibliotecas de HTTP externas, já que o fetch é uma API global nativa compatível com o padrão web. O modelo de permissões granular impede que o código acesse rede ou variáveis de ambiente além do estritamente declarado, reduzindo a superfície de ataque em integrações que lidam com dados pessoais como CPF.

Como o Deno gerencia o timeout na chamada à API de CPF?

O Deno usa a AbortController nativa do navegador para cancelar requisições. Basta criar um controller, passar o signal para o fetch e acionar controller.abort() após o tempo desejado com setTimeout. A latência típica da API da CPFHub.io é de ~900ms, então um timeout de 10 a 30 segundos é suficiente para cobrir variações de rede sem bloquear a aplicação indefinidamente.

O Oak framework é adequado para produção com validação de CPF?

Sim. O Oak é o framework HTTP mais usado no ecossistema Deno e oferece middleware, roteamento, tratamento de erros e suporte a HTTPS. Para validação de CPF em produção, combine o Oak com rate limiting no middleware para proteger seu endpoint contra abusos, e configure variáveis de ambiente pelo Deno Deploy para manter a chave de API segura fora do código.

O que acontece se o limite de consultas da CPFHub.io for atingido?

A API da CPFHub.io não bloqueia as requisições ao atingir o limite do plano. O serviço continua respondendo normalmente e as consultas excedentes são cobradas a R$0,15 cada. O plano gratuito inclui 50 consultas/mês; o Pro oferece 1.000 por R$149/mês. No Deno, monitore o consumo registrando cada chamada em log estruturado para identificar picos antes que impactem o orçamento.

Conclusão

Deno oferece uma base sólida para integrações com APIs de CPF: fetch nativo, TypeScript sem configuração, modelo de permissões granular e testes integrados. Combinado com o Oak framework, é possível criar APIs REST seguras e performáticas para validação de CPF em poucos arquivos.

A API da CPFHub.io responde em ~900ms com autenticação por header x-api-key. Cadastre-se em cpfhub.io e comece com 50 consultas gratuitas por mês.

CPFHub.io

Pronto para integrar a API?

50 consultas gratuitas para testar agora. Sem cartão de crédito. Acesso imediato à documentação.

Começar grátis Ver documentação

Sobre a redação

Redação CPFHub.io

Time editorial especializado em APIs de CPF, identidade digital e compliance no mercado brasileiro. Produzimos guias técnicos, análises regulatórias e tutoriais sobre LGPD e KYC para desenvolvedores e líderes de produto.

Como integrar validação de CPF em Deno com fetch nativo e Oak framework