Download the PHP package antikirra/token without Composer

Lightweight Cryptographically Signed Tokens for PHP

Secure, lightweight PHP library for creating cryptographically signed tokens with built-in expiration and validation. Supports any PHP hash algorithm for flexible performance and security trade-offs. Perfect for API authentication, session management, temporary access grants, and distributed systems requiring tamper-proof tokens without external dependencies.

Install

Why Choose This Library?

• 🔒 Cryptographically Secure - HMAC-based signatures prevent tampering and forgery
• ⏰ Built-in Expiration - Native timestamp-based expiration with microsecond precision
• 🎯 Type-Safe Design - Strongly typed tokens with customizable type identifiers (1-255)
• 🔧 Algorithm Flexibility - Support for any PHP hash algorithm (xxHash, SHA-3, BLAKE2, etc.)
• 📦 Compact Encoding - Efficient binary packing with URL-safe Base64 encoding
• ✅ Signature Verification - Constant-time hash comparison prevents timing attacks
• 🚀 Production Ready - Battle-tested with comprehensive boundary testing
• 🧪 Fully Tested - Extensive test coverage with Pest test suite
• 🔄 Serialization Support - Built-in PHP serialization with validation
• 🛡️ Clone Protection - Prevents token cloning for enhanced security

Features

• Cryptographic Signatures: HMAC-based signing with customizable salt and hash algorithms
• Expiration Management: Built-in timestamp validation with timezone support
• Type System: 255 distinct token types for multi-purpose authentication systems
• Identity Binding: Supports 64-bit integer identities (up to 18,446,744,073,709,551,615)
• Nonce Generation: Cryptographically secure random nonce (268,435,456 to 4,294,967,295)
• Binary Efficiency: Compact binary packing reduces token size by ~40% vs JSON
• URL-Safe Encoding: Base64url encoding compatible with URLs and HTTP headers
• Tamper Detection: Constant-time signature verification with hash_equals()
• Strict Validation: Comprehensive input validation with clear error messages
• Zero Configuration: Works out of the box, extend and configure as needed
• Memory Efficient: Minimal memory footprint with readonly properties

Perfect for

• API Authentication: Stateless authentication tokens with built-in expiration
• Session Management: Secure session identifiers with tamper protection
• Temporary Access: Time-limited resource access grants and one-time tokens
• OAuth/JWT Alternative: Lightweight alternative for internal authentication systems
• Password Reset Tokens: Secure, expiring tokens for password recovery flows
• Email Verification: Tamper-proof verification tokens with expiration
• Download Links: Time-limited, signed download URLs
• Invitation Systems: Secure invitation tokens with type-based permissions
• Multi-Tenant Systems: Type-based token segregation for different services
• Microservices: Service-to-service authentication without shared state

Requirements

• PHP: 8.1 or higher
• Extensions:
  • ext-mbstring - For byte-safe string operations
• Dependencies:
  • antikirra/base64url - URL-safe Base64 encoding/decoding

Basic usage

Advanced Examples

Multiple Token Types

Error Handling

Testing

This library is thoroughly tested with comprehensive test coverage:

Test Coverage: 100%

• 120 tests with 432 assertions
• All tests passing with zero failures
• Test suite execution time: ~0.19s

Test Suite Breakdown

• TokenTest (13 tests): Core functionality, encoding/decoding, serialization
• AlgorithmBoundaryTest (47 tests): Hash algorithm validation and edge cases
• EdgeCasesTest (19 tests): Edge cases, serialization, boundary conditions
• SaltBoundaryTest (22 tests): Salt size boundaries and validation
• TypeBoundaryTest (19 tests): Token type range validation

Coverage Details

• Boundary Tests: Type (1-255), Identity (1 to 2^64-1), Nonce (268,435,456 to 4,294,967,295)
• Salt Validation: Tests for minimum 32-byte requirement and various salt lengths
• Algorithm Support: Validates all common hash algorithms (MD5, SHA family, SHA-3, xxHash, etc.)
• Encode/Decode: Round-trip testing with signature verification
• Serialization: PHP serialize/unserialize with validation
• Expiration: Timestamp validation and timezone handling
• Error Cases: Invalid inputs, tampered signatures, boundary violations

Running Tests

Security Considerations

• Salt Management: NEVER change the salt after deploying tokens - it will invalidate all existing tokens
• Algorithm Choice: Use modern algorithms like xxh128, sha3-256, or blake2b for best security/performance balance
• Salt Length: Minimum 32 bytes required; recommend 64+ bytes for maximum security
• Token Storage: Never log or expose full tokens; only store hashed versions in databases
• Expiration: Always set reasonable expiration times; avoid long-lived tokens when possible
• HTTPS Only: Always transmit tokens over HTTPS to prevent interception
• Constant-Time Comparison: Built-in hash_equals() prevents timing attacks

Keywords

token, authentication, cryptographic-signature, hmac, secure-tokens, api-authentication, session-management, php-8.1, expiration, tamper-proof, stateless-auth, base64url, binary-packing, pest-testing, type-safe