Kalkan Laravel Package

Product Decisions This Supports

• Compliance and legal validity for Kazakhstan: The package wraps NCANode for Kalkan EDS signing, CMS verification/extraction, and TSA timestamping — decisions about whether the product can produce legally binding electronic documents under NUC RK requirements hinge on capabilities this package exposes.
• Build vs. buy for e-signature infrastructure: Adopting the package avoids building and maintaining a custom NCANode HTTP client, CMS workflow, and TSA policy handling. The v2.0.0 move to Laravel’s HTTP client makes it a lighter dependency and easier to govern than a bespoke integration.
• Roadmap and platform upgrades: v2.0.0 requires PHP 8.3+ and Laravel 12+, adding Laravel 13 / PHP 8.5 support. This forces a concrete decision: schedule the Laravel 10/11 → 12+ upgrade now, or pin 1.2.* while accepting that Laravel 10/11 are out of security support. That is a product risk decision, not just an engineering one.
• TSA policy change as a compliance review trigger: The default signCms() TSA policy moves from TSA_GOST_POLICY to TSA_GOST2015_POLICY, with older policies deprecated. PMs should confirm with legal/compliance and counterparties that GOST2015 timestamping is accepted before switching defaults.
• Reliability and defect priorities: Fixes for lost document IDs, invalid validate() field-list handling, silent empty request bodies on json_encode() failure, and unchecked file_get_contents() in kalkan:install reduce production incident risk in document workflows — useful when prioritizing reliability work on signing/extraction features.
• Use cases: e-government-adjacent services, contract signing, document exchange, archive timestamping, and any product flow in Kazakhstan requiring EDS verification or CMS extraction.

When to Consider This Package

• Your product operates in Kazakhstan and must integrate with NCANode / Kalkan EDS, including CMS signing, verification, extraction, or TSA timestamping.
• You are on Laravel 12+ and PHP 8.3+ (or planning to be), and want a maintained wrapper rather than a custom client.
• You need Laravel-native integration — the v2.0.0 HTTP client change means no direct Guzzle dependency in your application code.
• You value maintenance signals: weekly CI, Dependabot, PHPStan raised to level 7, and explicit migration notes for 1.x users.
• Look elsewhere if: you are not in the Kazakhstan/NUC RK ecosystem; you need eIDAS, PAdES, or other regional signature standards; you are staying on Laravel 10/11 long-term (pin 1.2.*, but plan the upgrade); your application is not Laravel-based; or you need full document lifecycle/records management — this is a signing/verification integration, not a DMS.
• Treat the breaking changes as a gate: signCms() exception behavior (JsonException), the PendingRequest type change, and the deprecated TSA policies should be validated against your error handling and compliance requirements before adoption.

How to Pitch It (Stakeholders)

To executives: This package is a compliance and time-to-market enabler for Kazakhstan e-signature workflows. v2.0.0 keeps the integration aligned with supported PHP/Laravel versions, adds Laravel 13 / PHP 8.5 readiness, and improves maintenance hygiene (weekly CI, Dependabot, stricter static analysis). The main decision is scheduling the Laravel 10/11 upgrade — those versions are out of security support, so staying on 1.2.* is a temporary risk acceptance, not a long-term plan.

To engineering: v2.0.0 is a contained breaking release: PHP 8.3+/Laravel 12+ baseline, Laravel HTTP client instead of Guzzle (PendingRequest), JsonException on signing/verification/extraction, and a changed default TSA policy. The README includes a 1.x → 2.x migration section. The release also fixes real defects in document ID handling, validation, request encoding, installer error checks, and PHPUnit 13 discovery — worth taking for reliability, not just version support.