Jose Laravel Package

Getting Started

Install via Composer:

composer require namshi/jose

Start with JWS for token signing — the most common use case (e.g., API authentication). For a minimal working example:

use Namshi\JOSE\JWS;

$jws = new JWS('HS256');
$token = $jws->encode(['sub' => 'user-123'], env('JWT_SECRET'));
$payload = $jws->decodeAndVerify($token, env('JWT_SECRET'));

First step: review tests/ in the repo — they provide clean, minimal examples for signing, verifying, and encrypting tokens with common algorithms.

Implementation Patterns

• Stateless Auth Service: Encapsulate token logic in a dedicated JwtService class (e.g., app/Services/JwtService.php) with methods createToken(), validateToken(), revokeToken() (for refresh tokens). Avoid ad-hoc usage in controllers.
• Laravel Integration: Bind the service in ServiceProvider and inject via constructor. Use config('app.key') only for fallback; prefer config('auth.jwt.secret') for explicit control.
• JWE for Sensitive Data: Encrypt payloads containing PII (e.g., email, role claims) using JWE with RSA-OAEP + AES-GCM. Store private keys securely via Laravel’s Crypt facade or external KMS.
• Claim Injection: Set standard claims (exp, iat, jti) manually in payload — namshi/jose won’t auto-add them. Use Carbon::now()->addMinutes(15)->timestamp for exp.
• Testing Strategy: Mock JWS/JWE in feature tests; use hardcoded secret in phpunit.xml for deterministic token generation.

Gotchas and Tips

• Unmaintained Risk: Last commit was in 2018 — high chance of unpatched vulnerabilities (e.g., algorithm confusion). Always restrict allowed algorithms via JWS::setAllowedAlgorithms(['RS256', 'HS256']).
• No Built-in Clock Skew Tolerance: decodeAndVerify() does not validate time-based claims — add manual checks:

  if ($payload->exp && $payload->exp < time()) { /* reject */ }
  if ($payload->nbf && $payload->nbf > time()) { /* reject */ }
  

• RSA Key Formatting: PEM strings often misaligned (missing line breaks or headers). Use openssl_pkey_get_private() to validate keys before encoding/decoding.
• Decoding ≠ Verification: decode() bypasses signature checks — never use in production. Always pair with decodeAndVerify() or validate signature manually.
• PHP 8+ Compatibility: Works only with hotpatched code. Add to composer.json:

  "replace": {
    "namshi/jose": "self.version"
  },
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/your-fork/namshi-jose"
    }
  ]
  

  Then apply patches for PHP 8+ type deprecations. Prefer modern alternatives like web-token/jwt-library for new apps.