Segurança e operações — NextPDF no CodeIgniter 4

Visão geral

Esta página descreve as ameaças às quais esta integração precisa resistir, os controles verificados no código-fonte do pacote e as regras operacionais que você deve seguir para uma implantação segura.

Modelo de ameaças

Você precisa considerar três superfícies que um atacante pode influenciar.

Payload do job da fila. Uma fila armazena os dados do job. Um atacante com acesso ao broker pode alterar esses dados. Trate-os como entrada desserializada e não confiável.
Nome do arquivo da resposta. Um usuário pode fornecer o nome do arquivo de download. Um nome malicioso pode injetar conteúdo no cabeçalho.
Caminhos de configuração. O caminho das fontes e os caminhos de assinatura vêm da configuração. Um caminho malicioso pode ler ou gravar no local errado.

Controle 1 — Lista de permissão do payload da fila

O job da fila trata o payload como dados desserializados não confiáveis. O Open Worldwide Application Security Project (OWASP) Application Security Verification Standard (ASVS) exige tratamento seguro de entrada para dados desserializados não confiáveis (ASVS V1.5.2).

Controles verificados em GeneratePdfJob:

O builder precisa ser uma string não vazia. O job rejeita qualquer outro tipo.
O builder precisa corresponder ao padrão App\PdfBuilders\<Class>::<method>. O job rejeita qualquer outro namespace, funções simples e payloads com prefixo ou sufixo.
O builder precisa ser callable. O job rejeita uma string que corresponde ao padrão, mas não resolve.

Em conjunto, essas regras bloqueiam a execução arbitrária de código por meio de um payload de fila adulterado. Os testes do pacote cobrem cada caso de rejeição.

Controle 2 — Confinamento do caminho de saída da fila

O job grava um arquivo em disco. O OWASP ASVS exige tratamento seguro de caminhos quando uma aplicação cria caminhos de arquivo para operações de arquivo (ASVS V5.3.2).

Controles verificados em GeneratePdfJob:

O caminho de saída precisa ser uma string não vazia.
O job normaliza o caminho antes de qualquer verificação. Ele resolve os segmentos . e .. e converte os separadores.
O caminho normalizado precisa permanecer dentro de WRITEPATH/pdfs/. O job rejeita um diretório irmão que compartilhe um prefixo de nome (pdfs-evil/).
O caminho precisa terminar com .pdf (sem distinção entre maiúsculas e minúsculas).

Essas regras bloqueiam gravações arbitrárias de arquivo por meio de um payload adulterado.

Controle 3 — Reforço dos cabeçalhos da resposta

PdfResponse anexa um conjunto fixo e reforçado de cabeçalhos a toda resposta no formato Portable Document Format (PDF):

Cabeçalho	Valor
`X-Content-Type-Options`	`nosniff`
`X-Frame-Options`	`DENY`
`Content-Security-Policy`	`default-src 'none'`
`X-Robots-Tag`	`noindex, nofollow`
`Referrer-Policy`	`no-referrer`
`Cache-Control`	`private, max-age=0, must-revalidate`

O pacote sanitiza o nome do arquivo antes que ele chegue ao cabeçalho. Ele remove separadores de caminho, bytes nulos e carriage return/line feed (CR/LF). Ele faz escape de aspas duplas para a forma entre aspas. Ele adiciona um parâmetro filename*=UTF-8''… da Request for Comments (RFC) 5987 para nomes não ASCII. Um nome vazio se torna document.pdf.

Controle 4 — Validação dos caminhos de configuração

O registro de fontes rejeita um valor de fontsPath que contenha um stream wrapper (://) ou um byte nulo. Ele lança um erro em tempo de execução. Isso bloqueia caminhos encapsulados como php:// ou phar://.

Controle 5 — Superfície mínima do service locator

O CodeIgniter 4 não fornece um container PHP Standards Recommendation 11 (PSR-11). Ele usa um locator de Services. A PSR-11 §1.3 trata o padrão service locator como desencorajado (modal SHOULD NOT). O pacote mantém a superfície do locator pequena: cada serviço tem um método de fábrica nomeado. Resolva os serviços no limite do controller. Passe objetos concretos adiante. Não passe a classe Services para o código de domínio.

Operações de assinatura e TSA (NextPDF Pro / Enterprise)

O serviço de assinatura permanece inativo por padrão. Ele só é ativado quando signature.enabled é true e signature.certificate não está vazio. O nível de assinatura padrão do pacote é B-B. O NextPDF Pro fornece a assinatura baseline B-B. A validação de longo prazo é um recurso Enterprise separado, documentado na referência Premium, e não aqui.

Regras operacionais:

Mantenha os arquivos de certificado e chave fora do controle de versão. Forneça-os por meio do .env ou de um gerenciador de segredos.
Mantenha tsa.allow_insecure_http definido como false em produção. Um canal de Time Stamping Authority (TSA) em texto claro não é aceitável.
Defina tsa.pinned_public_keys quando a TSA publicar uma chave estável. Mantenha tsa.warn_on_key_rotation definido como true.
Restrinja o acesso de leitura ao arquivo de chave apenas ao usuário da aplicação.

Checklist de operações

Fixe todas as versões resolvidas no composer.lock.
Exija codeigniter4/queue na aplicação que executa os workers.
Execute o worker da fila como um usuário de baixo privilégio. Conceda a ele acesso de gravação somente a WRITEPATH/pdfs/.
Dê ao worker as mesmas extensões do NextPDF que a camada web. Um PDF assinado precisa do NextPDF Pro ou Enterprise no ambiente do worker.
Confirme que as extensões mbstring e zlib estão disponíveis em todo runtime que constrói um PDF.
Confirme que os cabeçalhos da resposta sobrevivem ao proxy reverso.
Registre a geração de PDF com contexto. Não registre material de certificado nem senhas de chave.

Conformidade

O tratamento do payload da fila está alinhado ao OWASP ASVS V1.5.2.
O tratamento do caminho de saída da fila está alinhado ao OWASP ASVS V5.3.2.
O design do locator segue a orientação da PSR-11 §1.3.

Contexto comercial

O core do NextPDF é licenciado sob Apache-2.0. As âncoras de confiança de assinatura e o reforço de TSA se aplicam quando o NextPDF Pro ou Enterprise está instalado. O pacote do CodeIgniter expõe os métodos de serviço correspondentes, que retornam null até que o pacote Premium correspondente seja instalado. Consulte </get-license/?intent=codeigniter-signing>.

Veja também

/integrations/codeigniter/production-usage/ — registro e despacho corretos da fila.
/integrations/codeigniter/configuration/ — chaves de assinatura, TSA e de caminho.
/integrations/codeigniter/troubleshooting/ — mensagens de rejeição verificadas.
/integrations/codeigniter/overview/ — superfície completa da API.