Signet Pdf Laravel Package

Technical Evaluation

Architecture fit. signet-pdf is a library for producing PAdES (ICP-Brasil) signatures over PDFs. The 3.0.0 headline is an architectural change rather than a feature: PreparedSignature::$document becomes a Support\DocumentBuffer, so signing streams the document instead of materialising it twice. For a TPM this matters because memory cost drops from ~2× document size to ~1× (the release cites 310 MB peak for a 300 MB file, down from 602 MB). That converts "large PDF signing" from a hard no into a capacity-planning question, and it removes a whole class of OOM incidents from the design. The second architectural shift is external key custody: a signature can be produced without the private key entering the PHP process, which is the prerequisite for HSM/remote-signer deployments and for any auditor asking "where does the key live?" The ICP-Brasil work (policy declaration, security store, the three PBAD_ entries archival policies need beyond PAdES) is a conformance play, not an API play.

Integration feasibility. Feasible for a Laravel app, with contained but real friction. Two of the three breaking changes are mechanical ($document type, intervention/image 4.x); the third is a semantic change — SignaturePolicy::forProfile(PadesBLT) now returns null because ITI publishes no policy a B-LT signature satisfies. That is the correct decision, but it means any call site that assumed a policy object existed will now fail at runtime, and it must be handled explicitly. The intervention/image 4.x requirement is the one most likely to ripple beyond this package: it is an app-wide Composer constraint, and any other image-handling dependency in the same application has to be compatible or the upgrade stalls.

Technical risk.

• Compliance risk (highest). The release asserts the country's Verificador accepts the output. An assertion in a changelog is not evidence. We need the test corpus, the Verificador version, and ideally a third-party validation report before this carries regulatory weight.
• Memory risk (reduced, not eliminated). The ceiling is now "the size of the document," which is still a hard limit. A 300 MB document needs a worker with >310 MB of headroom plus TSA/certificate overhead. This belongs in background workers, never in a web request.
• Single-maintainer / OSS risk. Release cadence and per-major documentation sites are good signals, but archived 1.x/2.x lines mean security fixes for older majors are not guaranteed. That is a standing supply-chain consideration.
• Behavioural risk. Returning null for B-LT is a silent contract change for callers who do not read UPGRADE.md.

Key questions.

1. What is the actual memory constant (fixed overhead + per-MB cost), and how does it behave at 1 GB?
2. Does DocumentBuffer stream from a disk/S3 path without a full read, or is it an in-memory abstraction with a nicer type?
3. Which profiles are supported by external/HSM signing — all of B-B, B-T, B-LT, B-LTA, or a subset?
4. How is the TSA integrated for B-T/B-LT, and what is the retry/timeout contract?
5. Are the PBAD_ values hard-coded for ICP-Brasil, or extensible for other national profiles?
6. What is the supported PHP/Laravel version matrix, and what does the package require from ext-openssl, ext-gd, and disk?
7. Does 2.x still receive security patches, and for how long?
8. Was the Verificador acceptance tested against the current Verificador release, and is that test reproducible by us?

Integration Approach

Stack fit. Good fit for a Laravel service that already generates documents (invoices, contracts, receipts) and needs to sign them server-side. It slots into the existing service-provider/config-publish pattern, uses the framework's storage disks and queue system, and does not impose a different execution model. The natural placement is a queued job: generate PDF → sign → store → record receipt(). The new receipt() accessor is a small but genuinely useful addition for audit trails and downstream reconciliation.

Migration path. 2.x → 3.0. Follow UPGRADE.md; the order matters:

1. Bump intervention/image to 4.x first, in isolation, and confirm the rest of the application still works. This is the step most likely to surface unrelated breakage and should not be bundled with signing changes.
2. Replace string handling of PreparedSignature::$document with DocumentBuffer. Audit for strlen(), string concatenation, file_put_contents, and any code that hashed or persisted the raw document — those are the real break sites.
3. Add an explicit guard for the PadesBLT null-policy case. Decide the product behaviour now: fall back to B-T, reject the request, or surface a configuration error.
4. Adopt external key signing and ICP-Brasil conformance only after 1–3 are green.

Compatibility. Pin exact versions and verify: PHP version, Laravel version, intervention/image 4.x coexistence with any other imaging package (Spatie Media Library, Glide, etc.), and whether the external-signer path requires a specific crypto extension or client library. If the application serves multiple document profiles, confirm the profile matrix against the external signer before committing.

Sequencing. Spike on a branch against a representative corpus (small, typical, and a genuinely large 100 MB+ file) → measure peak memory and wall time → run the upgrade steps above → obtain Verificador or equivalent validation on our own sample documents → pilot in a staging queue with production-sized payloads → cut over with 2.x pinned as a rollback. Do not cut over on the strength of the changelog claim alone.

Operational Impact

On this line with a 2.x pinned rollback and a validated corpus, the 3.0 cut is a bounded change — the memory profile improves, key custody becomes a deployment decision rather than a code one, and the output becomes defensible against the national verifier. The cost is an intervention/image major bump and a null-policy contract change that will bite silently if the call sites are not audited; both are upgrade work, not steady-state work, and both fit inside a normal release cycle.

Maintenance. Expect majors to move forward and old lines to be archived. Budget a recurring upgrade line item rather than assuming 3.x is terminal. Track the maintainer's release cadence and CHANGELOG as an input to your own patch cadence.

Support. Open-source, community-supported. There is no vendor SLA behind a compliance claim, so the acceptance evidence has to be ours. If signing is revenue- or regulator-facing, designate an internal owner for the conformance story.

Scaling. Throughput is bound by CPU (hashing and signing) and by TSA round-trip latency for B-T and above, not by the package's I/O. Scale queue workers horizontally per signing profile; size each worker's memory_limit to document-size-plus-headroom rather than a flat 512 MB. Very large documents should route to a dedicated queue so they cannot starve ordinary traffic.

Failure modes to instrument.

• Memory exhaustion on documents above the worker ceiling — emit document size on every job.
• TSA unavailability or timeout → B-T/B-LT failures; needs retry with backoff and a dead-letter path.
• External signer timeouts or unavailability; treat the signer as a hard dependency with a circuit breaker.
• null policy for B-LT surfacing as a fatal at the call site if not guarded.
• Certificate chain/expiry problems, and clock skew affecting timestamp validity.
• Archived 2.x line accumulating unpatched issues while you finish migration.

Ramp-up. Moderate. The API surface is small; the domain is not. PAdES policy OIDs, security stores, DSS/VRI structures and archival PBAD_ entries are where the learning cost sits, and getting them wrong is invisible until a verifier rejects the file. Plan one to two sprints: one for the mechanical upgrade and instrumentation, one for conformance validation with someone who owns the ICP-Brasil requirements. Treat the Verificador run as the definition of done.