Skip to content
CAI
Software that uses CAICheck a score

tymondesigns/jwt-auth

54.7

Adequate · 13 November 2026

5.3k

lines of production code

PHP

primary language

7

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

What this system is

This system is a JWT authentication library for Laravel and Lumen that manages the full lifecycle of JSON Web Tokens, including generation, validation, and refresh. It provides core capabilities for issuing tokens, handling blacklisting, and parsing tokens from various HTTP sources like headers, cookies, and query strings. The library integrates with Laravel's existing authentication guards and cache storage while supporting both symmetric and asymmetric signing algorithms.

How it got here

2014 — Initial project scaffolding and core implementation

10 changes.

This period established the foundational structure of the jwt-auth library, including configuration, documentation, and a comprehensive test suite. It introduced the core JWT authentication components, such as token generation, validation, blacklisting, and Laravel integration, along with a structured exception and claims hierarchy.

2015 — Provider abstraction and contract interfaces

14 changes.

This period focused on establishing a robust abstraction layer for the JWT authentication package by introducing contract interfaces for authentication, JWT handling, storage, and HTTP parsing. It involved implementing specific providers for Laravel and Lumen, including support for asymmetric signing algorithms and cookie-based token parsing. Comprehensive test coverage was added to validate these new components and ensure correct behavior across various token sources and claim types.

2016 — JWT authentication refactoring

4 changes.

This period focused on restructuring the JWT authentication system by introducing a modular parser chain for token extraction and a shared base middleware class for handling authentication logic. It also added a new console command for managing JWT secrets and expanded the test suite with fixtures for ECDSA and RSA keys.

Features

Add HTTP Parser contract interface

Introduces the \Tymon\\JWTAuth\\Contracts\\Http\\Parser\ interface, defining a contract for components responsible for parsing HTTP requests to extract token data. This interface specifies a \parse\ method that accepts an \Illuminate\\Http\\Request\ object and returns a string token or null, providing a standardized way to decouple request parsing logic within the JWT authentication system.

src/Contracts/Http · high confidence

Add Illuminate authentication provider implementation

Introduces a new \Illuminate\ class in the \Tymon\\JWTAuth\\Providers\\Auth\ namespace that implements the \Auth\ contract. This provider delegates authentication checks and user retrieval to the underlying Laravel \Guard\ contract, enabling JWT authentication to work seamlessly with Laravel's existing authentication guards.

src/Providers/Auth · high confidence

Add Laravel/Illuminate storage provider

Introduces a new \Illuminate\ storage provider that implements the \Storage\ contract using Laravel's cache repository. This provider handles JWT token storage and retrieval, automatically converting time inputs from minutes to seconds to ensure compatibility across different Laravel versions, and includes logic to detect and support cache tagging where available.

src/Providers/Storage · high confidence

Added contract interfaces for Auth, JWT, and Storage providers

This change introduces three new interface contracts in the \Tymon\\JWTAuth\\Contracts\\Providers\ namespace: \Auth\, \JWT\, and \Storage\. The \Auth\ interface defines methods for user authentication by credentials, by ID, and retrieving the current user. The \JWT\ interface specifies encoding and decoding operations for JSON Web Tokens. The \Storage\ interface outlines methods for managing token storage, including adding, retrieving, destroying, and flushing entries, as well as setting values indefinitely. These interfaces provide the abstraction layer for provider implementations within the JWT authentication package.

src/Contracts/Providers · high confidence

Added facades for JWT authentication, payload factory, and JWT provider

This change introduces three new Laravel facades in the \src/Facades\ directory to provide static access to core JWT services. Users can now use \JWTAuth\ to access the authentication service (\tymon.jwt.auth\), \JWTFactory\ to access the payload factory (\tymon.jwt.payload.factory\), and \JWTProvider\ to access the JWT provider (\tymon.jwt.provider.jwt\). These facades simplify interaction with the underlying JWT components by allowing static method calls instead of resolving instances from the service container.

src/Facades · high confidence

Initial project scaffolding and configuration

This change establishes the foundational structure for the jwt-auth library by adding essential configuration and documentation files. It introduces .editorconfig and .gitattributes to standardize coding styles and repository exports, sets up .styleci.yml with the Laravel preset for automated code style enforcement, and configures phpunit.xml.dist for test execution and code coverage reporting. Additionally, it provides the MIT LICENSE, mkdocs.yml for documentation site generation, and a comprehensive README.md featuring build status badges, security contact information, and links to the official documentation.

(repo-wide) · high confidence

Initial release of JWT authentication core components

This change introduces the foundational classes for the JWT authentication system, including the \Blacklist\ class for managing token invalidation (with support for grace periods and indefinite blacklisting), the \Factory\ class for building payload claims, the \JWT\ and \JWTAuth\ classes for token generation and validation, the \JWTGuard\ for Laravel integration, the \Manager\ for coordinating encoding/decoding and refresh flows, and the \Payload\ and \Token\ value objects. This establishes the core behavioral capability for issuing, validating, refreshing, and blacklisting JWTs.

src · high confidence

Introduce dedicated Payload and Token validators with configurable refresh TTL

The validation logic is now split into specific classes: PayloadValidator checks that JWT payloads contain required claims (iss, iat, exp, nbf, sub, jti) and validates timestamps, while TokenValidator ensures tokens have the correct three-segment structure. A new configurable refresh TTL (defaulting to 20160 minutes) allows users to control how long a token remains valid for refresh operations, and the base Validator class now supports a refresh flow context to apply these specific validations.

src/Validators · high confidence

JWT configuration defaults and options for asymmetric signing and refresh behavior

The configuration file introduces support for asymmetric signing algorithms (RSA and ECDSA) via new \keys\ settings for public/private keys and passphrases, alongside symmetric HMAC options. It allows users to set an infinite refresh TTL by setting \refresh\_ttl\ to null, and provides a \persistent\_claims\ array to control which claims are retained when refreshing tokens. The default token time-to-live (\ttl\) is set to 60 minutes, and the default hashing algorithm is HS256.

config · high confidence

New Lcobucci JWT provider with asymmetric algorithm support

The library now includes a new \Lcobucci\ JWT provider implementation (\src/Providers/JWT/Lcobucci.php\) that replaces or supplements the previous provider. This new provider supports asymmetric signing algorithms (RSA and ECDSA) in addition to HMAC, allowing users to sign tokens with public/private key pairs. It integrates with the \lcobucci/jwt\ library (v5 compatible) and handles token encoding/decoding using the Lcobucci configuration, including validation constraints and claim mapping. The base \Provider\ class has been updated to support these new algorithm constants and key management methods.

src/Providers/JWT · high confidence

New contract interfaces for JWT claims, subjects, and validation

Added three new interfaces to the contracts namespace: Claim, JWTSubject, and Validator. The Claim interface defines methods for setting and getting claim values and names, as well as validating claim creation. The JWTSubject interface specifies how entities should provide their JWT identifier and any custom claims to be included in the token. The Validator interface provides methods for checking values and determining validity. These contracts establish the foundational abstractions for claim handling, subject identification, and validation within the JWT authentication system.

src/Contracts · high confidence

New jwt:secret command for generating and managing JWT keys

A new console command, \jwt:secret\, has been added to generate a 64-character random secret key for JWT authentication. The command supports several options: \--show\ to display the key without saving it, \--force\ to skip the confirmation prompt when overwriting an existing key, and \--always-no\ to skip generation entirely if a key already exists. It intelligently handles the \.env\ file by appending a new \JWT\_SECRET\ entry if the file exists but lacks the key, or updating the existing entry if one is present, while ensuring compatibility with Laravel versions prior to 5.4.17.

src/Console · high confidence

New support traits and utility helpers for JWT handling

This change introduces three new components in the src/Support directory to aid JWT token management. The CustomClaims trait provides methods to set, alias, and retrieve custom claims on token builders. The RefreshFlow trait adds a flag to manage token refresh states. Additionally, a new Utils class offers static helpers for time handling, including methods to get the current UTC time, convert timestamps, and check if a timestamp is in the past or future with optional leeway.

src/Support · high confidence

Behavioural changes

Introduction of specific JWT exception classes

The library now provides a hierarchy of specific exception classes under the Tymon\\JWTAuth\\Exceptions namespace, extending the new base JWTException. Users can now catch distinct exceptions such as InvalidClaimException, PayloadException, TokenBlacklistedException, TokenExpiredException, TokenInvalidException, and UserNotDefinedException, rather than relying on a single generic error type. The InvalidClaimException constructor specifically accepts a Claim object to provide context about which claim had an invalid value.

src/Exceptions · high confidence

Refactored HTTP token parsing into a modular, extensible chain

The HTTP token parsing logic has been restructured from a monolithic implementation into a chain of dedicated parser classes (AuthHeaders, Cookies, InputSource, QueryString, RouteParams, and LumenRouteParams) that can be added, removed, or reordered. This change introduces a new Parser class to manage the chain, allowing users to customize which sources are checked for tokens and in what order. Specific parsers now handle distinct extraction points: AuthHeaders correctly strips trailing hyphens and handles comma-separated tokens in the Authorization header; Cookies optionally decrypts tokens using Laravel's Crypt facade; and InputSource/QueryString/RouteParams provide clear separation for form inputs, query strings, and route parameters. The AuthHeaders parser also supports configurable header names and prefixes via setHeaderName and setHeaderPrefix methods.

src/Http/Parser · high confidence

Refactored JWT authentication middleware into a shared base class

The authentication middleware logic has been restructured to use a new \BaseMiddleware\ class, which centralizes token checking, authentication, and header setting. This change introduces specific middleware behaviors: \Authenticate\ now strictly validates the token and user existence, throwing an \UnauthorizedHttpException\ if the user is not found; \RefreshToken\ handles token renewal and returns the new token in the response header; and \AuthenticateAndRenew\ combines both actions, ensuring a refreshed token is sent back to the client after processing the request. Existing middleware like \Check\ and \Authenticate\ are marked as deprecated in favor of this new structure.

src/Http/Middleware · high confidence

Refactored JWT claims into a structured class hierarchy

The claims system has been restructured from a monolithic implementation into a modular class hierarchy. A new abstract Claim base class now handles core value management, serialization (Arrayable, Jsonable, JsonSerializable), and validation interfaces, while specific claims like Audience, Expiration, IssuedAt, and NotBefore extend it with standard JWT logic. A DatetimeTrait centralizes timestamp handling for DateInterval and DateTimeInterface inputs, and a Claim Collection manages validation contexts. The Claims Factory now uses an extensible class map to instantiate these specific claim types, allowing users to override or extend claim behavior via the new extend() method.

src/Claims · high confidence

The service provider logic has been split into a new AbstractServiceProvider base class with specific implementations for Laravel and Lumen. This refactoring introduces a cookie parser to the default token parsing chain in the Laravel provider, allowing JWT tokens to be read from cookies when the decrypt\_cookies config option is enabled. The Lumen provider now uses a dedicated route params parser and configures middleware via routeMiddleware. Additionally, the storage provider registration in the Laravel service provider now passes the Laravel version to the storage instance if the method exists, ensuring compatibility with version-specific storage behaviors.

src/Providers · high confidence

Test coverage

Added test coverage for Payload and Token validators; Added test fixtures for ECDSA and RSA keys; Added test stubs for JWT authentication scenarios; Added tests for HTTP token parsing chain; Added tests for the Illuminate storage provider; Added unit tests for JWT authentication middleware; Added unit tests for JWT claims and claim factory; Added unit tests for JWT providers; Initial test suite for JWT-Auth core components.

Dependencies

Update dependencies for Laravel 13 and PHP 8.0+ support

The composer.json manifest has been updated to require PHP 8.0 or higher and to support Laravel versions 9 through 13 (via illuminate packages). Additionally, the library now supports lcobucci/jwt versions 4.0 and 5.0, and nesbot/carbon versions 2.69 and 3.0, ensuring compatibility with recent major releases of these core dependencies.

(dependencies) · high confidence

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

How this codebase got here

Score

  • CAI 54 → 55 (+1.0)
  • Rubric changed (rubric-2026.10.5 → rubric-2026.11.4) — scores are not directly comparable.

Lenses

  • Code Health 71 → 71 (-0.1)
  • Architecture 93 → 93 (-0.0)
  • Maturity 43 → 45 (+2.7)
  • Readiness 54 → 53 (-0.9)
  • Security 69 → 69 (+0.0)

Resolved (6)

  • Ambiguous distinction between 'get' and 'getInternal'. Without documentation, it is unclear why a separate method is needed for internal claims versus standard claims, suggesting a potential leakage of implementation details or a confusing API contract.
  • Duplicate method names for the same operation. Both methods accept an array of custom claims and likely perform the same assignment or storage logic.
  • Inconsistent error handling strategy. checkOrFail implies throwing an exception on failure, while check likely returns a boolean or nullable result. While distinct, the naming convention check vs checkOrFail is common but check returning a boolean is often less intuitive than isValid or tryCheck in modern APIs.
  • Inconsistent naming for retrieving the current user. JWTAuth uses user(), while JWTGuard provides both user() and getUser(). This creates confusion about which method to use in different contexts (Facade vs Guard instance).
  • Off-boarding risk: anonymized user #1
  • Redundant method for strict matching. matchesStrict appears to be a convenience wrapper for matches with strict=true, adding no distinct functional value while increasing API surface.

New (2)

  • Edited copy of a member (13 corresponding lines) (src/Providers/JWT/Lcobucci.php)
  • Off-boarding risk: anonymized user #1

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

Survey your own repository

tymondesigns/jwt-auth was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.

About this page

  • The score is its most recent published measurement, taken on 13 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
  • Measured at commit 99e8f24cf96bfb6d847597c6a80713879a0a19c1 — the exact code this score is about.
  • Scored under rubric-2026.11.4 — the same rubric and the same method as every other entry in this index.
  • Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.64+preprod-569132d3dfbe.