Hawk Server Bundle Laravel Package

Technical Evaluation

Architecture fit — poor as stated, because the premise is off. hashnz/hawk-server-bundle is a Symfony bundle, not a Laravel package. Bundles rely on Symfony's HttpKernel, DependencyInjection (Extension + CompilerPass), and config-tree machinery that Laravel never loads. Laravel consumes Symfony components (HttpFoundation, Routing, Console, etc.), not the bundle system, so there is no composer require + register-provider path here. The realistic deliverable is "read the Hawk verifier and port ~200–400 lines into Laravel middleware," not "install a dependency."

What is actually reusable. The server-side Hawk verification logic: parsing the Authorization: Hawk id="…", ts="…", nonce="…", mac="…", ext="…" header, canonicalizing the request string, recomputing HMAC-SHA256, constant-time MAC comparison, timestamp-skew rejection, nonce replay tracking, and optional payload-hash validation. That is genuinely useful as a reference implementation. Everything around it is dead weight in our stack.

Integration feasibility. Low as a dependency, moderate as source material. A fork-and-extract effort is measured in days (spike + security review + adapter + interop tests), not hours. The crypto itself is simple and well-documented; the risk is in the edges (payload hashing behind proxies, nonce storage, key lookup).

Technical risk — high, on several independent axes.

• Abandonment signals: score 0, zero stars, zero dependents, one-line description. No evidence of CI, tests, or review. Security-sensitive crypto code with no visible test suite is a hard stop until we read it.
• Era mismatch: the bundle form factor suggests Symfony 2.x / PHP 5.x lineage. The composer.json constraints will almost certainly conflict with PHP 8.2+ and modern Symfony components that Laravel pulls in. Expect transitive dependency hell if we try to install rather than vendor.
• Spec risk: Hawk was a Mozilla-originated draft that was never standardized and has near-zero ecosystem momentum today. OAuth2 client credentials, mTLS, or plain signed requests have won. Adopting Hawk means adopting a protocol nobody on the team can Google their way out of, and we become the only consumer of this library.
• We own the security review. With no upstream maintainer, "abandoned" means any flaw we find is ours to fix and ours to disclose.

Key questions to resolve before any code is written.

1. What are the exact php and symfony/* constraints in composer.json, and what is the last commit date?
2. Does it validate the payload hash, or MAC-only? Does it handle the ext field correctly (it is part of the MAC, a common implementation bug)?
3. Is the MAC comparison constant-time, or a bare ==? This is the single most common flaw in homegrown Hawk implementations.
4. Is nonce storage pluggable (Redis/cache) or in-process? In-process = no replay protection in a multi-node fleet.
5. Is the skew window configurable, and does it fail closed?
6. Is it server-side only, or does it also ship a client helper we'd need for interop testing?
7. Where does the shared key come from — static config, or a lookup-by-id interface we can bind to our key store?
8. License, and is this an original repo or a stale fork of someone else's work?
9. What is the actual business driver? If it's "a partner already speaks Hawk," that changes the calculus entirely — we're implementing an interop requirement, not choosing an auth scheme.

Integration Approach

Stack fit. Laravel 10/11 on PHP 8.2+, likely with Sanctum or Passport already in place. The correct shape is a HawkServiceProvider registering a HawkAuthenticate middleware, a HawkCredentialRepository contract bound to our key store, and a HawkNonceStore bound to Redis. The bundle's DependencyInjection/ and Resources/config/ directories are discarded entirely; only the verifier is lifted.

Migration path. Do not attempt to register the bundle. Options, in order of preference:

1. Vendor a fork. Add the repo as a Composer VCS dependency pinned to a commit SHA, or copy the verifier into app/Support/Hawk/ with a header comment attributing origin and license. Pinning to a SHA is mandatory — a floating branch on an unmaintained repo is an unpinned supply chain.
2. Reimplement from the spec if the source review turns up problems. Hawk's canonical string is short enough to implement cleanly with a proper test suite, and we'd own it outright.
3. Substitute a standard (Sanctum tokens, Passport client credentials, or an HMAC request-signing middleware) if the driver is internal-only rather than a partner interop requirement. This is the cheapest long-term option and should be argued for explicitly.

Compatibility gotchas that will bite during integration.

• Authorization headers are frequently stripped by nginx/FastCGI. Confirm fastcgi_param HTTP_AUTHORIZATION $http_authorization; or equivalent on every hop.
• Payload-hash verification requires the raw, unmodified request body. Laravel middleware that re-encodes JSON, and any proxy that rewrites bodies, will break it. Read $request->getContent(), not the parsed input.
• Hawk over plain HTTP is a MAC, not encryption — TLS is non-negotiable, and the security model changes if TLS terminates at an LB that inspects or mutates traffic.
• Coexistence with existing Bearer tokens on the same routes needs explicit middleware ordering and a clear precedence rule.

Sequencing. (1) 1–2 day spike: read composer.json, read the verifier, answer the key questions above. (2) Security review sign-off on MAC comparison and nonce handling — no code merged before this. (3) Build-vs-adopt-vs-substitute decision with the business driver stated in writing. (4) Port with an interop test suite validated against an independent Hawk client (the npm or Ruby hawk libraries) — do not test only against our own implementation. (5) Shadow-mode rollout: log accept/reject decisions without enforcing for one release cycle, then enforce.

Operational Impact

Maintenance. We own this permanently. There is no upstream cadence to ride, no CVE feed to monitor, and no one else to file a bug with. Budget a named internal owner and a standing dependency-review entry for the fork. Realistically a few hours per quarter plus the initial hardening.

Support. Zero vendor, zero community, zero Stack Overflow surface. The runbook is ours to write, and it must include the canonical string format, the clock-skew policy, the nonce TTL, and a "how to debug a 401" section — otherwise every auth failure becomes an escalation to whoever wrote the middleware.

Scaling. The stateless part (HMAC verification) scales horizontally with no issue — it is pure CPU and cheaper than a database round-trip. The part that does not scale naively is the nonce replay cache: it requires a shared, low-latency store (Redis) with TTL equal to the skew window, typically 60s. An in-process or per-node nonce cache silently degrades replay protection to per-node scope, which is a security regression that will never show up in a functional test.

Failure modes to design for explicitly.

• Clock skew — hosts without reliable NTP produce mass 401s. This is the #1 operational cause of Hawk incidents.
• Nonce store outage — must be a deliberate, documented choice between fail-closed (outage = total auth outage) and fail-open (outage = replay protection gone). Default should be fail-closed, with an alert.
• Key rotation without an overlap window — instant mass 401. Requires dual-key acceptance during rollover.
• Proxy body rewriting or header stripping — auth fails 100% and looks like a client bug.
• Skew-window misconfiguration — too tight causes intermittent failures under load; too loose widens replay exposure.
• Silent spec drift — if a partner's client implementation differs on canonicalization, you'll debug it from scratch with no community reference.

Ramp-up. Nontrivial. Nobody on a typical Laravel team has encountered Hawk; it is not in anyone's muscle memory. Onboarding requires the runbook, a client-side signing helper for local development, and debug tooling — the ext field, which is MAC'd and free-form, is the one genuinely nice affordance here and should carry a request correlation ID. Expect a day of ramp-up per engineer who touches it, and more for whoever is on call the first time a 401 storm hits.

Bottom line for the roadmap: treat this repo as a specification and reference implementation, not a dependency. Adopt only if a partner interop requirement forces Hawk; otherwise the rational move is to standardize on an auth mechanism the team and the ecosystem already understand.