Token Bundle Laravel Package

Product Decisions This Supports

• Feature Development:

  • Implement secure, typed tokens for password resets, email verification, and shareable links without reinventing the wheel.
  • Enable race-safe token consumption (e.g., multi-use tokens for shared documents) to prevent overconsumption in high-traffic scenarios.
  • Add event-driven token lifecycle hooks (e.g., trigger analytics or notifications when tokens are created/consumed/revoked).
  • Build fine-grained token revocation (e.g., invalidate all password_reset tokens for a user after a security breach).
  • Support custom token resolvers (e.g., extract tokens from JWTs, cookies, or custom headers) for flexible API integrations.

• Roadmap Priorities:

  • Phase 1: Replace ad-hoc token logic (e.g., manual token tables, custom services) with this bundle to reduce tech debt.
  • Phase 2: Extend the bundle’s #[RequiresToken] attribute to support role-based token validation (e.g., only allow admin users to revoke tokens).
  • Phase 3: Integrate with Symfony Messenger to asynchronously process token events (e.g., send verification emails after token creation).

• Build vs. Buy:

  • Buy: Avoid building a custom token system (e.g., managing expiration, revocation, and race conditions from scratch).
  • Customize: Extend the bundle’s TokenManager or TokenResolverInterface for niche use cases (e.g., IP-based token validation).

• Use Cases:

  • Password Resets: Secure, single-use tokens with 1-hour expiration.
  • Email Verification: Typed tokens (email_verify) with payloads (e.g., {"locale": "en"}).
  • Shareable Links: Multi-use tokens for documents/files with custom permissions (e.g., {"permissions": ["view", "edit"]}).
  • API Access: Bearer tokens for rate-limited endpoints (using a custom TokenResolver).
  • Audit Logs: Track token consumption/revocation via TokenConsumedEvent/TokenRevokedEvent.

When to Consider This Package

• Adopt if:

  • You’re using Symfony 7.0+ and need a batteries-included token system (no need to manage token tables, expiration, or concurrency manually).
  • Your tokens require types (e.g., password_reset vs. email_verify) and payloads (e.g., metadata like maxUses or permissions).
  • You need race-safe token consumption (e.g., for shared links with limited uses).
  • Your team prefers event-driven architectures (e.g., trigger actions when tokens are created/consumed).
  • You want to protect routes with minimal boilerplate (e.g., #[RequiresToken] attribute).

• Look elsewhere if:

  • You’re not using Symfony (this is a Symfony bundle; alternatives like Laravel’s built-in token system or custom PHP solutions may fit better).
  • You need short-lived tokens (e.g., <1 minute) and want to avoid database queries (consider in-memory caches or JWTs).
  • Your tokens require complex cryptographic operations (e.g., HMAC signatures) beyond what this bundle provides (e.g., use a dedicated library like spomky-labs/token-refresher).
  • You’re on PHP <8.3 or Symfony <7.0 (compatibility constraints).
  • You need distributed token validation (e.g., across microservices) without a shared database (consider Redis-based solutions like predis/predis).

How to Pitch It (Stakeholders)

For Executives:

"This package lets us standardize how we handle secure, time-limited tokens across the app—like password resets, email verifications, and shareable links—without building and maintaining custom logic. It reduces security risks (e.g., token reuse, expiration leaks) and cuts dev time by 30%+ for features like ‘magic links’ or ‘temporary access.’ The bundle’s event system also lets us hook into token actions for analytics or notifications, adding value without extra work. For example, we can automatically revoke all password reset tokens for a user after a breach, or track how often shareable links are used. It’s a low-risk, high-reward upgrade to our auth flow."

For Engineering:

*"This Symfony bundle replaces our scattered token implementations (e.g., manual Doctrine queries, custom services) with a type-safe, race-condition-proof system. Key wins:

• Single source of truth: One Token entity/table for all token types (password resets, verifications, shares).
• Race-safe consumption: Atomic increments for multi-use tokens prevent overconsumption in high-traffic scenarios.
• Flexible validation: Use #[RequiresToken] to protect routes with minimal boilerplate, or extract tokens from headers/cookies via custom resolvers.
• Events + CLI: Hook into token lifecycle events (e.g., log consumption) or purge expired tokens via php bin/console token:purge.
• Payload support: Attach metadata to tokens (e.g., maxUses, permissions) without schema changes.

Migration path:

1. Replace ad-hoc token logic with the bundle’s TokenManager.
2. Add TokenSubjectInterface to your entities (e.g., User, Document).
3. Use #[RequiresToken] for route protection.
4. Leverage events for side effects (e.g., send emails on TokenCreatedEvent).

Tradeoffs:

• Requires Symfony 7.0+ (PHP 8.3+).
• Tokens are stored in a database (not ideal for ultra-low-latency needs).
• Custom token logic (e.g., cryptography) must be added via extensions.

Next steps:

• Audit current token implementations (e.g., password resets, share links) for migration candidates.
• Prototype #[RequiresToken] for a high-traffic endpoint (e.g., /reset-password).
• Benchmark performance vs. current solution (focus on race conditions and concurrency)."*