Antenna Bundle Laravel Package

Technical Evaluation

Evidence basis: this assessment is derived solely from the 1.1.0 release note (time_to_live option added to UsernamePasswordAuthenticator); no source, changelog history, or usage data was supplied. Findings should be treated as provisional until code review.

Architecture fit

• The package occupies a narrow but well-understood slot in a Laravel codebase: a named authenticator that validates a username/password credential pair and issues a bearer-style access token. It sits behind Laravel's service container and is typically bound into a guard or a controller-level login flow.
• Adding time_to_live moves the package from "issue a token that lives indefinitely or until manually revoked" to "issue a token with a bounded, configurable validity window." That is an architectural improvement, not a structural change: it aligns the authenticator with how modern token-based auth is expected to behave (short-lived access tokens plus a refresh or re-login path).
• It remains a stateless-by-default design. TTL governs expiry, not revocation — a token remains valid for its full lifetime once issued. Architectures that require immediate revocation (logout-everywhere, compromised-credential response) still need a denylist, a token-version/jti store, or a session-bound design.

Integration feasibility

• Low integration cost. A TTL option is almost always additive: a new constructor argument, config key, or fluent setter, with a default that preserves 1.0.x behaviour. Expect a single configuration change plus, at most, a small code touch in the login path or the guard binding.
• Semver classification is correct at a minor bump. No deprecation is signalled, and no removal is signalled.
• The main integration decision is where the value is set — a single global config value, per-guard, or per-call. Per-guard/per-call is materially more useful (short TTL for public API clients, longer for trusted internal services) and should be confirmed before we design around it.

Technical risk

• Overall: low. Additive option, small surface, no schema change implied.
• Behavioural-default risk: if the default TTL is null/unbounded, behaviour is unchanged and safe. If the default is a finite value (e.g. 60 minutes), existing integrations will start expiring tokens silently — the highest-impact failure mode in this release. Must be verified in code, not assumed from the note.
• Enforcement risk: TTL is only meaningful if it is validated server-side. A TTL encoded as a claim but not checked on the guard path is a decorative control and would be a security-relevant defect.
• Clock handling: expiry checks are clock-sensitive. Skew between app servers, and between the issuing and validating process, needs a leeway/grace setting. Not indicated in the note.
• Operational coupling: short TTLs push retry/re-auth traffic to clients. Without a refresh flow, a TTL that is "secure by default" can become a UX and load problem.

Key questions

1. What is the default value when time_to_live is unset — unbounded (backward compatible) or a finite default?
2. Is TTL enforced on every token validation, or only embedded as a claim?
3. Granularity: global config only, per-guard/authenticator instance, or per-login call?
4. Unit and format (seconds, DateInterval, Carbon), and is a null value explicitly supported and documented?
5. Is there a clock-skew/leeway setting, and is it configurable?
6. Does the package ship a refresh-token or silent re-issue mechanism, or is re-login the only recovery path?
7. Is revocation (denylist, jti, token version) available or planned? TTL is not a substitute.
8. Is this release covered by tests asserting expiry behaviour (token invalid after TTL, valid before)?
9. Laravel/PHP version support matrix, and whether 1.1.0 changes any transitive dependency constraints.

Integration Approach

Stack fit

• Conforms to standard Laravel package conventions: Composer-installed, config-published, container-resolved, compatible with guard/middleware composition. No framework-level workarounds implied.
• Fits cleanly whether the package is used standalone for an API login endpoint or as one authenticator among several behind a shared auth manager.

Migration path

• composer require bump from 1.0.x to 1.1.0; no data migration, no schema migration, no breaking API change indicated.
• Recommended: pin ^1.1 on one non-critical service first, confirm the unset-TTL default empirically (issue a token, wait past any implied default, re-validate), then roll forward.
• If we are replacing an incumbent (Sanctum, Passport, hand-rolled JWT), do not treat this release as a trigger for that decision. It raises the package's maturity but does not close gaps those alternatives cover — refresh tokens, scopes, revocation, first-party cookie/Session handling.

Compatibility

• Greenfield: set TTL deliberately from day one, matched to client re-auth capability.
• Brownfield: treat as a no-op change unless we explicitly adopt TTL. Adoption is the actual decision; the version bump is not.
• Client-side compatibility is the real constraint: any consumer that caches a bearer token must handle a 401 and re-authenticate. Mobile and long-running batch jobs are the usual breakage points.

Sequencing

1. Code review of the release to answer the default-value and enforcement questions.
2. Upgrade on a canary service; verify no behavioural change with TTL unset.
3. Define a TTL policy per client class (interactive user, service-to-service, batch).
4. Enable TTL on the canary; instrument 401 rate and re-login volume.
5. Confirm client retry/re-auth logic, including skew tolerance, before broader rollout.
6. Roll out by service tier; document the chosen defaults in the platform auth standard.
7. Separately (not blocking): scope a revocation/denylist story if immediate invalidation is a requirement.

Operational Impact

Maintenance

• Small, single-maintainer-style packages carry concentration risk. Review commit cadence, issue responsiveness, test coverage, and whether the release includes tests for the new path before depending on it in a revenue path.
• The TTL surface is small and stable; expect low ongoing maintenance burden for the feature itself. Budget for periodic review of security advisories on the package and its JWT/Carbon dependencies.

Support

• The support burden shifts to policy, not code: "why did my token stop working," "what should the TTL be," "how do I get a longer token." Publish a short internal standard (default TTL, per-client overrides, re-auth expectations) at rollout time.
• Client teams need a documented error contract: 401 + token_expired semantics, and whether retry-with-same-credentials is safe.

Scaling

• Stateless validation scales well — no per-request store lookup implied, so auth throughput tracks the rest of the request path.
• Shorter TTLs increase login/refresh request volume roughly proportionally to 1/TTL. Model this: a 15-minute TTL on a high-traffic mobile client is 96 potential re-auth events per user per day if refresh is absent. Password-hashing cost on the login endpoint is the scaling bottleneck to watch — this is the single most likely operational surprise from this release.
• If token persistence exists for revocation or audit, TTL enables a pruning/retention job with a clear expiry horizon — an improvement over unbounded rows.

Failure modes

• Silent mass expiry: a finite default we did not notice; every integration breaks at once at a shared wall-clock moment. Highest-severity, lowest-likelihood; the canary step is the mitigation.
• No refresh path: TTL set aggressively, clients fall back to credential storage or frequent logins; users notice degraded experience.
• Clock skew: a node ahead of or behind peers rejects valid tokens or accepts expired ones; intermittent, hard-to-reproduce 401s that look like load-balancer issues.
• False security assumption: team believes TTL equals revocation; a leaked token stays usable until expiry. Document explicitly that TTL bounds blast radius but does not eliminate it.
• Missing enforcement: TTL set but not validated on the guard path; control appears in config and does nothing. Caught only by an expiry test.

Ramp-up

• Low for any Laravel-fluent engineer: one config key, one concept. Half a day including verification.
• The non-obvious learning is conceptual, not syntactic: the distinction between expiry and revocation, and the client-side contract for re-authentication. Newer engineers reliably conflate the two; cover it in the platform auth doc.
• Reviewers should require an expiry test and a documented default before this is considered production-ready in our environment.