Octawire Auth Service Php Client Bundle Laravel Package

Technical Evaluation

Scope of this assessment: initial baseline established at v0.9.4. No prior assessment exists, so this document sets the reference point against which future releases will be diffed.

Architecture fit

• The package is a client-side adapter for an "Auth Service" speaking Auth Service Protocol v1.0 (camelCase JSON) and conforming to the JATP_METHODS_1.0.json spec. It supplies DTOs/mappers (OctowireUser, IssueTokenResponse, ValidateTokenRequest, HealthCheckResponse) plus an authenticator (OctowireTokenAuthenticator) and validator (TokenValidator).
• Architecturally this is an anti-corruption layer between our application and an external identity provider. That is the right shape — it means protocol churn (v1.0 field renames) is absorbed at the boundary rather than leaking into domain code, provided our code depends on our own interface, not on OctowireUser directly.
• The v0.9.4 dual-read behaviour (userId with fallback to user_id, projectId with fallback to project_id, customClaims/custom_claims) is a transitional compatibility shim. Good for cutover, bad as a permanent state: it doubles the field surface and hides server-version mismatches that should fail loudly.
• Framing risk: the brief describes this as a Laravel/PHP package, but the stated dependencies are Symfony 6.4+/7.0+ with no mention of a Laravel service provider, config publishing, facade, or container bindings. It may be a framework-agnostic library consumed via Symfony components. This materially changes integration effort and must be resolved before sizing.

Integration feasibility

• PHP 8.1+ is the floor. Symfony component constraints (6.4+/7.0+) interact with the Laravel version we run: Laravel 10 sits on Symfony 6.2–6.4 components; Laravel 11 moves to Symfony 7.x and requires PHP 8.2. Adopting this package likely pins us to Laravel 11 / PHP 8.2+, or forces a Composer conflict-resolution exercise. This is the single biggest feasibility gate.
• Transitive dependency kabiroman/octawire-auth-service-php-client: ^0.9.4 is itself pre-1.0. Two pre-1.0 packages stacked means caret ranges give weak guarantees; ^0.9.4 allows 0.9.x only, which is acceptable, but any 0.10.0 bump is a breaking-range exit.
• Documented artifacts lower ramp-up meaningfully: migration guide in README, examples/integration-tests/, TLS and non-TLS example configs, TESTING.md. That is unusually complete for a 0.9.x.
• The release fixes Argument #2 ($projectId) not passed in token validation and now passes required projectId into ValidateTokenRequest. Prior versions therefore had a defect on the core validation path. For a multi-tenant deployment, projectId is the tenant-scoping input — a missing or defaulted value is a cross-tenant trust boundary issue, not just a crash. Verify the fix, and verify behaviour when projectId is absent.

Technical risk

• Pre-1.0 churn (high): v0.9.x with a protocol rename wave already in flight. Semver permits breaking changes at 0.10.0. expiresIn on IssueTokenResponse already changed signature within this line.
• Protocol migration incompleteness (medium): camelCase rollout is presented as complete, but the fallback implies servers may still emit snake_case. Silent-null risk: if a field is absent under both names, does the mapper throw or return null? A null userId or projectId propagating into authorization decisions is the worst-case failure.
• Breaking change in HealthCheckResponse (medium): healthy (bool) → status (string). Any existing probe, readiness gate, or alerting rule keyed on the old shape breaks silently. Anything treating a non-empty string as truthy inherits a subtle bug.
• Verification depth (medium): 88 unit tests plus "integration tests with real Auth Service verified" — but no CI matrix over PHP 8.1/8.2/8.3 or Symfony 6.4/7.0 is stated, and integration tests appear to be example-grade rather than gated.
• No published support policy (medium): no LTS statement, no deprecation window, no security disclosure process documented in the notes.

Key questions

1. Is this a Laravel-native package (service provider, publishable config, container bindings) or a Symfony-component library used inside Laravel? Which Laravel versions are actually supported?
2. What is the support matrix — PHP 8.1/8.2/8.3 × Laravel 10/11/12 × Symfony 6.4/7.0 — and is it tested in CI or asserted in docs?
3. Is snake_case fallback permanent or deprecated? If deprecated, what is the removal version and date?
4. What is the intended 1.0 timeline and stability commitment? Should we plan to pin exactly and re-review at every minor?
5. What happens on missing/unknown fields — throw, null, or default? Specifically for userId, projectId, customClaims.
6. How is projectId sourced and validated in our deployment — static config, per-tenant lookup, or request-derived? Can it ever be empty and still validate?
7. Is the upstream Auth Service itself versioned independently, and does it support both field casings simultaneously?
8. Who maintains both packages, and what is the issue-response expectation?
9. Does HealthCheckResponse.status have a defined enum of values, and which value indicates ready?
10. Is token validation cached, or does it round-trip to the Auth Service on every request?

Integration Approach

Stack fit

• Best fit is a PHP 8.2+ / Laravel 11 application already using Symfony 7 components. Applications on PHP 8.1 or Laravel 10 should not adopt until the matrix is confirmed — treat as a blocked path, not a stretch goal.
• Where the package is framework-agnostic, wrap it: define our own TokenVerifier interface and AuthenticatedPrincipal value object, and let the Octowire adapter implement it. This contains the pre-1.0 blast radius to one directory.

Migration path

• There is no prior assessment, so "migration" here means onboarding a greenfield integration, not upgrading. That is an advantage: we can adopt directly at v1.0-shaped semantics and skip the snake_case path in our own code.
• Pin 0.9.4 exactly in composer.json — not ^0.9.4 — for the first integration cycle. Loosen only after we have a passing CI matrix of our own.
• Run the Auth Service in a dev/staging environment that emits both casings if possible. This forces the fallback logic to be exercised in the direction we expect (camelCase wins) and proves it does not mask a broken payload.

Compatibility

• Two independent version axes must be tracked: our Laravel/PHP line and the Auth Service Protocol version. Record both explicitly in the dependency register. Protocol v1.0 is the only supported target in this release.
• The projectId requirement makes this package inherently multi-tenant. Confirm at onboarding whether a single deployment serves one or many projects; the answer changes the config model and the test strategy.

Sequencing

1. Spike (1 week): install in a throwaway Laravel 11 skeleton, stand up the non-TLS example config, exercise the examples/integration-tests/ suite end to end. Deliverable: confirmed support matrix and a yes/no on framework fit.
2. Interface design: define our own abstraction (verifier, principal, error taxonomy) before writing any product code. No OctowireUser outside the adapter.
3. TLS hardening: move to the TLS example config, validate certificate handling, secret rotation, and failure behaviour when the Auth Service is unreachable.
4. Negative-path testing: missing projectId, unknown field casing, expired expiresIn, malformed health status. Explicitly test cross-tenant rejection.
5. Health/readiness wiring: map HealthCheckResponse.status to our probe contract in the same step as the feature, not later — it is already a breaking field and should not be retrofitted.
6. Pilot: one low-traffic service in production behind a feature flag, with the legacy auth path retained for rollback.
7. Expansion: remaining services, one at a time, each with the same flag and rollback story.

Operational Impact

Maintenance

• Expect to re-review this dependency at every minor release. A 0.9.x dependency with an in-flight protocol migration is not a "set and forget" library; budget a recurring slice of platform capacity for version review, and treat 0.10.0 as a scheduled breaking change.
• Two pre-1.0 packages in the dependency chain (octawire-auth-service-php-client and this package) means two upgrade cadences to reconcile. Track both on one watchlist.
• Cleanup debt is already visible: the snake_case fallback will eventually need removal from our adapter and from test fixtures.

Support

• Documentation quality is above average for the version number — migration guide, INSTALLATION.md, TESTING.md, runnable examples. That materially lowers day-2 support load.
• No SLA, support tier, or security disclosure process is stated. Budget for self-support: vendor the source, keep a fork point identified, and ensure someone on the team can read the token validation path.
• Escalation path is unclear for a bug on the auth critical path. Record it before go-live, not during an incident.

Scaling

• Token validation is on the request hot path. If ValidateTokenRequest round-trips to the Auth Service per call, latency and availability of the Auth Service become our latency and availability. Confirm whether local verification (signature + claims) is supported; if so, use it and reserve remote validation for cache misses.
• Introduce a validation cache keyed on token with TTL bounded by expiresIn, plus a circuit breaker around the Auth Service. Neither is provided by the package as far as the notes indicate — assume we build both.
• projectId scoping should not require a per-request lookup. Load it once per tenant at boot.

Failure modes

• Auth Service unavailable: default must be fail-closed. Any proposal to fail-open on validation error needs explicit security sign-off.
• Field-casing mismatch: server emits unexpected casing or omits a field; fallback returns null; null principal reaches an authorization check. Mitigate with strict non-null assertions at the adapter boundary.
• Missing projectId: the exact defect fixed here. If it can recur, validation either errors (safe) or silently scopes to a default tenant (severe). Test it explicitly on every upgrade.
• Health check regression: healthy: true → status: "...". Probes that coerce strings to booleans will report healthy incorrectly. Rename the check and add an assertion on the allowed values.
• Clock skew: expiresIn is a duration, not an absolute time; skew accumulates if we convert carelessly. Compute expiry once, server-side-relative, and log the delta.
• TLS misconfiguration: the non-TLS example config is convenient and dangerous. Gate it behind an environment check that cannot be enabled in production.

Ramp-up

• Estimated 2–3 engineer-days to productive: the examples and TESTING.md compress the learning curve considerably.
• The non-obvious parts are not in the code — they are our tenant model, our caching decision, and our fail-closed posture. Allocate design time there rather than to API familiarisation.
• Pair the first integration with a security review. The projectId defect in this release's changelog is a reminder that the failure mode of this package is a tenant-isolation failure, and that class of bug is cheap to review and expensive to discover.