Xmlseclibs Laravel Package

Product Decisions This Supports

• Build vs. buy for XML trust boundaries. Any feature that must prove "this XML really came from that partner" — SAML assertions, WS-Security/SOAP payloads, signed invoices/EDI (e-invoicing, AS4/PEPPOL-style flows), signed configuration or license documents, encrypted payload exchange — has a make-or-buy fork. Hand-rolling DOM + openssl_verify in application code is where signature-wrapping, KeyInfo trust, and canonicalization bugs live. This package is the "buy" option for the cryptographic core, and it is the same core already under SimpleSAMLphp, OneLogin php-saml, and LightSAML, so choosing it is choosing the ecosystem default rather than a novel dependency.
• Security posture as a feature, not a backlog item. The 4.0 line ships safe-by-default verification: pinned keys, algorithm allowlists, DOCTYPE rejection (the CVE-2025-23369 class of Id-resolution bypass), XPath-transform rejection, RSA-1.5 denial on decrypt, uniform decrypt errors, SSRF-hardened certificate fetching. A PM can treat these as pre-built compliance and threat-model answers — you are inheriting mitigations for attack classes most teams would never scope a ticket for.
• Roadmap gating for interoperability. The package makes "which peers do we support, and at what security cost?" an explicit, reviewable product decision. Legacy peers are enabled one knob at a time (enableLegacyMode(), allowRSA15KeyTransport, allowXPathTransforms), which means each interop concession can be tracked as a named, owned, expiring roadmap item rather than an invisible weakening of the whole system.
• Scope containment on integrations. Because the library deliberately does not derive keys from the document, does not fetch trust material implicitly, and does not implement XAdES/e-signature profiles, it draws a clean line: this is the crypto primitive layer, and your product still owns key management, certificate rotation, tenant-to-cert mapping, and profile-level signature requirements. That is a scoping decision a PM can defend in a design review.
• Framework fit for a Laravel shop. It is framework-agnostic PHP 8.0+ with no service provider, config file, or facade. For a Laravel product this means the PM should plan an explicit thin adapter (bindings, config for pinned certs, queued jobs for any certificate fetch, feature-flagged legacy knobs) rather than assuming "composer require and done." If you only need SAML SSO at the app layer, you likely consume it transitively through php-saml and should scope accordingly; if you need direct signing/encryption of partner XML, you are building the adapter.
• Dependency and lifecycle planning. BSD-3-Clause, actively maintained master, but a single primary author and a 4.0 line still in beta with documented breaking defaults (3.1 → 4.0). That shapes version-pinning policy, upgrade budgeting, and the risk register entry.

When to Consider This Package

Adopt when most of these hold:

• You must verify XML signatures or decrypt XML from an external party, and you can pin the trusted key/certificate out-of-band (config, secret store, per-tenant record). verifyDocument() expects exactly this.
• You are on PHP 8.0+ and can accept phpseclib/phpseclib ~3.0 (with OpenSSL optional — useful in locked-down images without ext-openssl).
• Your peer set uses mainstream algorithms: RSA-SHA256/384/512, RSA-PSS, AES-GCM, RSA-OAEP. If a peer forces SHA-1, RSA-1.5, CBC, or XPath transforms, adopt only with a documented, time-boxed interop exception.
• You need strict primitives for a custom workflow (custom signing templates, selective references, wsu:Id-style attribute namespaces) rather than a batteries-included SAML stack.
• You are willing to own the adapter and key management. The library will not manage certificates, rotation, or tenant routing for you.

Look elsewhere when:

• You need only JWT/OAuth/API auth — use a JWT or Passport/Sanctum path; XMLDSig is irrelevant weight.
• You want SAML at the application layer — use php-saml or SimpleSAMLphp and let it pin xmlseclibs; do not build SAML semantics on top of raw primitives unless that is genuinely your product.
• You need advanced e-signature profiles: XAdES/EPES baseline levels, signature timestamps, long-term validation, eIDAS-qualified signatures. This library is the primitive, not the profile; those are a specialist build or a commercial API purchase.
• You need schema validation, SOAP/WSDL stacks, or full WS-Security policy handling — different concerns, different libraries.
• You are still on PHP 7.x — you would be on the 3.1 branch and outside the hardened-defaults story, which is the main reason to pick this package at all.
• You cannot accept single-maintainer concentration risk on a security-critical path without a mitigation plan (see pitch below).

How to Pitch It (Stakeholders)

For executives: This is a small, permissively licensed dependency that replaces a class of security work we would otherwise have to design, build, and audit ourselves — XML signature verification and XML encryption for partner integrations. It absorbs attack classes we would not have scoped (signature wrapping, entity-reference resolution bypass, padding-oracle decryption, SSRF via certificate URLs) as defaults, not optional hardening. It is already the cryptographic foundation under the major PHP SAML implementations, so we are standardizing on the ecosystem's shared core instead of a bespoke one. Cost is essentially integration effort, not licensing; the real investment is our own key management and a thin Laravel adapter, both of which we would need anyway.

For engineering: Treat verifyDocument() with a pinned key as the only sanctioned verification path; operate solely on the returned validated nodes and never re-select assertions by Id from the full document. Low-level primitives are allowed for signing and for workflows that genuinely need them, with the rule that verify() results are compared === 1 and decrypt failures are never branched on by message. Pin the algorithm allowlists explicitly, keep legacy mode behind a config flag with an owner and an expiry date, and instrument it — every use of legacy mode, RSA-1.5, or CBC is a metric we watch and a migration ticket. Certificate fetching is blocking network I/O: queue it, never inline in a request. Version-pin in Composer; 4.0 is still beta with intentional breaking defaults, so plan a dedicated upgrade window rather than a floating constraint.

Risks to state out loud, once: single primary maintainer on a security-critical path (mitigate with pinned versions, an internal review of the verification path, and a tested fallback plan); a metric showing zero dependents that contradicts documented real-world usage, so verify transitive adoption yourself before treating it as a signal; and known breaking changes between 3.1 and 4.0 — decide now whether you ship on 3.1 hardened defaults or commit to the 4.0 line, and put the migration on the roadmap rather than discovering it.