Assinar PDFs no seu sistema

 Navegador (JS + extensão)         Seu servidor                    API ShieldSign PKI
 ─────────────────────────         ────────────                    ──────────────────
 1  envia o(s) PDF(s) ───────────▶ POST /assinar/iniciar ────────▶ POST /v1/pades-signatures/multipart
                       ◀────────── { assinaturaId, documentos }  ◀─ { token, documents }
 2  lê o certificado (DER)
    ──────────────────────────────▶ POST /assinar/preparar ──────▶ POST .../{token}/prepare
                       ◀────────── { digests }                   ◀─ { digests, certificate }
 3  assina com a extensão: uma aprovação, um PIN, a chave nunca sai do token
 4  envia as assinaturas ────────▶ POST /assinar/concluir ───────▶ POST .../{token}/complete
                                    baixa os PDFs ◀──────────────── GET .../documents/{i}  (ou .zip)
                       ◀────────── { documentos }                   DELETE .../{token}

use ShieldSign\Client;
use ShieldSign\ApiException;

function cliente(): Client {
    return new Client(getenv('SHIELDSIGN_URL'), getenv('SHIELDSIGN_KEY'), timeoutSeconds: 300);
}

// $arquivos: lista de ['path' => caminho do PDF no disco, 'name' => nome do arquivo]
$r = cliente()->startMultipart($arquivos, 'pades-icpbrasil-ad-rb', 'icp-brasil', callbackArgument: "usuario:$uid");

$id = bin2hex(random_bytes(16));            // identificador opaco que o navegador vai conhecer
guardarAssinatura($id, [
    'token' => $r['token'],                  // o token da API fica SÓ AQUI
    'documentos' => $r['documents'],         // transactionId e sha256 de cada PDF recebido
    'documentoEsperado' => $cpfOuCnpjDoSignatario,  // do seu cadastro: veja "Recusar antes do PIN"
]);
// devolva ao navegador: { assinaturaId: $id, documentos: [...] }

$a = lerAssinatura($in['assinaturaId']);
$p = cliente()->prepare($a['token'], $in['certificado']);   // certificado DER em base64, enviado pelo navegador

// A API já validou cadeia, validade e uso da chave. Agora confira QUEM é:
$c  = $p['certificate'];
$pk = $c['pkiBrazil'];                                       // cpf, cnpj, responsibleCpf, companyName...
if ($a['documentoEsperado'] && !in_array($a['documentoEsperado'], [$pk['cpf'], $pk['cnpj'], $pk['responsibleCpf']], true)) {
    cliente()->discard($a['token']);                         // recusa ANTES do PIN: nada foi assinado nem cobrado
    responder(422, ['erro' => 'certificado_de_outra_pessoa']);
}

$a['idempotencyKey'] = bin2hex(random_bytes(16));            // veja "Sessões, prazos e repetição segura"
guardarAssinatura($in['assinaturaId'], $a);

// devolva SÓ o necessário ao navegador: os dados a assinar, um por documento, na mesma ordem do envio
responder(200, ['digests' => $p['digests'], 'warnings' => $p['warnings'] ?? []]);

$c = cliente()->complete($a['token'], $in['assinaturas'], 'link', $a['idempotencyKey']);

foreach ($c['documents'] as $d) {
    $destino = "$dir/assinado-{$d['index']}.pdf";
    cliente()->downloadDocument($a['token'], $d['index'], $destino);
    // confira o que recebeu: o hash do arquivo baixado deve ser o que a API informou
    if (!hash_equals($d['signedSha256'], hash_file('sha256', $destino))) {
        throw new RuntimeException('arquivo assinado corrompido no download');
    }
    // guarde: $d['transactionId'], $d['signedSha256'], $c['certificate']['pkiBrazil'] e o requestId
}
cliente()->discard($a['token']);   // libera a sessão e apaga os arquivos do servidor da API

import { ExtensionSigner, A3Signer, ExtensionError } from "/assets/shieldsign-sdk.browser.mjs";

const b64 = (bytes) => btoa(String.fromCharCode(...bytes));          // para arquivos grandes, converta em pedaços
const unb64 = (s) => Uint8Array.from(atob(s), (c) => c.charCodeAt(0));

async function post(caminho, corpo) {
  const res = await fetch(caminho, {
    method: "POST", credentials: "include",
    ...(corpo instanceof FormData ? { body: corpo } : { headers: { "content-type": "application/json" }, body: JSON.stringify(corpo) }),
  });
  const json = await res.json().catch(() => ({}));
  if (!res.ok) throw Object.assign(new Error(json.mensagem ?? `HTTP ${res.status}`), { codigo: json.erro, requestId: json.requestId });
  return json;
}

export async function assinar(arquivos, signer) {
  // 1) iniciar: envia os PDFs
  const form = new FormData();
  arquivos.forEach((f) => form.append("pdf[]", f, f.name));
  const ini = await post("/assinar/iniciar", form);

  // 2) preparar: envia o certificado; a API o valida ANTES de o usuário digitar o PIN
  const prep = await post("/assinar/preparar", { assinaturaId: ini.assinaturaId, certificado: b64(await signer.certificate()) });

  // 3) assinar: UMA aprovação e UM PIN para todos os documentos
  const algoritmo = prep.digests[0].digestAlgorithm;
  const dados = prep.digests.map((d) => unb64(d.toSignData));
  const assinaturas = await signer.signMany(dados, algoritmo);

  // 4) concluir
  return post("/assinar/concluir", { assinaturaId: ini.assinaturaId, assinaturas: assinaturas.map(b64) });
}

// uso
if (await ExtensionSigner.isAvailable()) {
  const [cert] = await ExtensionSigner.listCertificates();      // normalmente você mostra a lista e o usuário escolhe
  const resultado = await assinar([...inputArquivos.files], new A3Signer(cert.thumbprint));
}