Configuração segura, certificado A1 e CSC

Configuration é imutável. A configuração padrão já é homologação (ambiente: 2); nos exemplos, o valor fica explícito. O construtor valida formato e domínio de valores, sem comprovar cadastro, dígitos verificadores, vínculo fiscal ou habilitação na SEFAZ.

use Acbr\Configuration;

$config = new Configuration(
    cnpj: '11222333000181', // identificador sintético da fixture
    uf: 'CE',
    modelo: 55,
    ambiente: 2,
);

Parâmetro	Contrato
cnpj	String com exatamente 14 dígitos
uf	Sigla maiúscula de uma UF brasileira aceita
modelo	Inteiro 55 ou 65; padrão 55
ambiente	Inteiro 1 ou 2; padrão 2; exemplos somente 2
certificado	?CertificateA1, opcional para gerar/validar; exigido nas outras seis operações
csc	?Csc, necessário ao fluxo NFC-e conforme o motor

A1 por fonte segura

CertificateA1::fromFile(string $path, string $password) lê uma vez um arquivo regular local de até 2 MiB. Não aceita URL ou stream wrapper. fromData(string $pfx, string $password) recebe bytes em memória com o mesmo limite. A senha deve ser UTF-8 e é preservada sem trim; a validade criptográfica do PFX é verificada pelo motor, não pelo construtor PHP.

O trecho abaixo é para ambiente de desenvolvimento com certificado sintético e descartável. As variáveis são fornecidas ao processo por um gerenciador seguro ou mecanismo local equivalente; não coloque uma senha literal em linha de comando ou no histórico do shell.

use Acbr\CertificateA1;
use Acbr\Configuration;

$pfxPath = getenv('ACBR_A1_PATH');
$password = getenv('ACBR_A1_PASSWORD');
if ($pfxPath === false || $pfxPath === '' || $password === false) {
    throw new RuntimeException('Configure o caminho e a senha do A1 sintético.');
}

$config = new Configuration(
    cnpj: '11222333000181',
    uf: 'CE',
    modelo: 55,
    ambiente: 2,
    certificado: CertificateA1::fromFile($pfxPath, $password),
);

Uma aplicação autorizada a operar fiscalmente deve obter seus próprios dados e A1 por um processo seguro; nenhum certificado, senha, XML fiscal ou contato real acompanha esta documentação. O exemplo assinar-offline.php exige declaração explícita de certificado sintético e não executa operação de rede.

NFC-e e CSC

Para modelo 65, configure um CSC de homologação obtido pela aplicação para esse ambiente. Csc aceita ID como string de 1 a 6 dígitos e token UTF-8 de 1 a 256 bytes, sem espaços removidos automaticamente. Um caractere multibyte consome mais de um byte.

use Acbr\Csc;

$id = getenv('ACBR_CSC_ID');
$valor = getenv('ACBR_CSC_TOKEN');
if ($id === false || $valor === false) {
    throw new RuntimeException('CSC de homologação não configurado.');
}
$csc = new Csc($id, $valor);

Passe modelo: 65, ambiente: 2, certificado: $a1, csc: $csc ao construtor. O modelo do documento e o ambiente precisam ser coerentes com a configuração. O help informa o enum taHomologacao do documento; não confunda esse enum com o inteiro 2 da configuração.

Privacidade e ciclo de vida

PFX, senha e CSC seguem pelo stdin do worker; não entram nos argumentos do processo. json_encode() e debug das classes de segredo retornam apenas indicadores; serialize() é recusado. Configuration::toWire(), CertificateA1::toWire() e Csc::toWire() são métodos internos que contêm segredos: não os use para log, cache ou HTTP.

Mantenha PFX e arquivos de aplicação fora do diretório público, com acesso restrito ao processo autorizado. Evite capturar configuração ou XML em callbacks, dumps, traces e ferramentas de observabilidade. Redação do SDK não protege logs que a própria aplicação montar. Memória PHP, variáveis de ambiente, dumps do sistema e cópias por fork() não têm promessa de apagamento físico garantido.

Finalize o emissor em finally. A construção de objetos e a instalação do runtime não contactam a SEFAZ; uma chamada de operação de rede representa uma decisão explícita da aplicação.