Laravel Auth Signature Laravel Package

Product Decisions This Supports

• Build vs buy on service-to-service authentication. This package gives you HMAC request signing (sign → transmit → validate) inside Laravel without writing and owning a bespoke canonicalization/signature implementation. v3.2.0 is the release that turns it from a server-side validator into a two-sided toolkit, which is the point at which "buy" becomes defensible for both ends of the call.
• Roadmap: standardizing internal service-to-service calls. The new Http::withSignature($clientId, $authVersion, $secret) macro signs at send time over the final method, path, query string and JSON/form body, reusing the same SignatureGenerator the validator verifies against. One shared primitive for both signing and verifying removes the most common class of integration bug (client and server canonicalizing differently) and makes "adopt signed service calls" a shippable roadmap item rather than a research spike.
• Reducing partner/customer integration cost. php artisan auth-signature:sign --curl emits a ready-to-run curl command for a given request; --debug/-v prints the exact canonical string being signed, with secrets never printed. This converts partner onboarding from "read the spec and guess" into "run one command and paste it." Budget impact: lower support load per integration and shorter time-to-first-successful-call — a measurable onboarding KPI.
• Multi-credential and key-rotation features. SignatureGenerator::generate() now accepts an optional $secret override, so one process can sign on behalf of multiple clients/tenants without reconfiguring the singleton. This is the enabling primitive for per-partner credentials, staged secret rotation (sign with new secret while old is still accepted during overlap), and delegated/on-behalf-of signing. Decide now whether rotation is in scope for the next quarter — the package now supports it, but the acceptance-window and secret-storage work is yours.
• Launch-readiness gate: correct error semantics. The README now states plainly that signature failures currently render as HTTP 500, and documents a bootstrap/app.php snippet to map them to their proper 4xx codes. Treat this as a pre-GA checklist item, not documentation trivia: unmapped failures pollute 5xx SLOs and alerting, inflate error budgets, and can trigger incident pages for what is actually a client bug. If signature validation is on a customer-facing or revenue path, "4xx mapping configured and verified in staging" should be an explicit exit criterion.
• Security posture / risk acceptance. Replay protection is only the ±300 s timestamp window — there is no nonce store or seen-signature cache. That is a legitimate design choice for low-value, idempotent, short-lived calls, but it explicitly bounds what the package defends against. This is a decision to escalate to security, not to assume.
• Observability and debugging as a product capability. RequestSigner (PSR-7) plus stringToSign() mean support engineers can reproduce a failing signature deterministically instead of instrumenting production. Lower MTTR on integration incidents, and a cheaper path to a "why did this request fail?" admin/diagnostic view if you ever want one.
• Dependency and release hygiene. Runtime dependencies on illuminate/http, illuminate/routing, illuminate/console and guzzlehttp/guzzle are now declared explicitly (less chance of transitive-version surprises), and the published archive no longer ships tests, CI config or dev tooling — smaller vendor footprint in your build artifacts. CI now actually installs the Laravel version each job claims, and end-to-end route tests were added: modest but real evidence that the compatibility matrix means something.

When to Consider This Package

Adopt when most of the following hold:

• Your signer and verifier are both PHP/Laravel (or your counterpart can implement HMAC per your spec), and you want one library rather than two implementations.
• You need request integrity and caller authenticity for internal service-to-service calls, webhooks you emit, or partner APIs — not full user identity/OAuth flows.
• Your endpoints are idempotent or low-value enough that a 300-second replay window is an acceptable residual risk, or you can layer your own nonce/idempotency key on top.
• You want the operational ergonomics: artisan signing command, curl output, canonical-string debugging, PSR-7 signer for non-HTTP-client code paths.
• You're prepared to (a) map signature failures to 4xx at the framework exception layer, (b) own secret storage and rotation, and (c) verify the signature scheme end-to-end against a real counterpart before committing.

Look elsewhere — or plan significant additional build — when:

• You need OAuth2 / OIDC / JWT / mTLS, delegated user consent, or token introspection. This package signs requests; it does not authenticate users or issue tokens.
• You need strong replay protection (nonce store, one-time signatures, strict ordered delivery) or you operate in a regulated/high-value domain (money movement, PHI, destructive admin operations) where a 300 s window alone won't pass security review.
• You have non-PHP clients at scale (mobile, Go, third-party SaaS) that can't reuse the library — you'd be maintaining a cross-language spec plus conformance tests anyway, so evaluate whether a standard (mTLS, OAuth2 client credentials, cloud IAM signing) buys you more than a custom HMAC scheme.
• You need managed key infrastructure — KMS/HSM-backed signing, automatic rotation with audit trails, per-key policy. The secret override helps you implement rotation; it does not provide key management.
• You're highly sensitive to vendor concentration / maintenance risk: this is a niche, effectively single-purpose package. Check release cadence, maintainer responsiveness and open-issue handling, and confirm the pinned PHPUnit ^11 || ^12 and Laravel version matrix match your CI before betting a critical path on it.
• Your signing needs are trivially small — one internal endpoint with a shared secret may not justify a dependency; but if you're already writing canonicalization logic by hand, that's exactly the bespoke code this replaces.

How to Pitch It (Stakeholders)

For executives (one paragraph): We're evaluating a small Laravel package that lets our services and partners cryptographically sign API requests and verify them on the other side. The new release is the meaningful one: previously it only checked signatures, so every caller had to hand-roll the signing logic; now the same library signs outgoing calls, provides a one-line CLI that generates a ready-to-run curl command for partners, and can sign on behalf of multiple clients with different secrets. Practically, that shortens partner onboarding, removes a recurring class of "signature mismatch" support tickets, and makes a standard for internal service-to-service calls achievable this quarter instead of as a bespoke build. Two caveats we should own rather than inherit: signature failures currently surface as HTTP 500 and need a small config change to return proper 4xx (otherwise they distort our error rates and on-call alerts), and replay protection is limited to a 5-minute timestamp window, which security needs to sign off on for anything high-value. Recommendation: pilot on one internal integration with the 4xx mapping in place, then decide on broader adoption.

For engineering (the ask):

• Adopt the Http::withSignature() macro and RequestSigner as the only signing path; do not hand-roll canonicalization anywhere. That's what keeps client and server verifiably in sync via stringToSign().
• Add the documented bootstrap/app.php exception mapping in the same PR as adoption — signature failures must be 4xx, and we want a test asserting that.
• Verify behavior under retries and queued jobs (signing happens at send time, so each attempt gets a fresh timestamp — confirm this with a test rather than assuming).
• Keep secrets out of logs and out of the CLI output; the package already avoids printing them, so don't undermine that in our wrappers.
• Write one end-to-end conformance test against a real counterpart before we call it done — the package's own route tests prove it works with itself, not with our partners.
• Confirm secret storage/rotation ownership explicitly; the override exists, the process does not.