Download the PHP package sokkian/simpleauth without Composer

SimpleAuth

A lightweight, secure PHP library for passwordless authentication using magic links (one-time login tokens).

Project Status

⚠️ Learning/educational project - not actively maintained. Feel free to fork and adapt it for your needs.

Features

• Passwordless authentication: Secure login via email magic links
• Replay protection: One-time use tokens with nonce validation
• Clock skew tolerance: Configurable grace period for time synchronization
• Immutable result objects: Type-safe error handling without exceptions
• Internationalization: Built-in support for multiple languages
• Zero dependencies: Pure PHP with no external libraries required
• PSR-4 compatible: Easy integration via autoloading

Requirements

• PHP 7.4 or higher
• PDO extension with MySQL support
• MySQL 5.7+ or MariaDB 10.2+

Installation

Via Composer (Recommended)

Manual Installation

1. Download or clone this repository

2. Copy the src/ directory to your project:

3. Create an autoloader file in your project root:

autoload.php:

Database Setup

Run the SQL schema to create required tables:

Or manually create tables:

Quick Start

1. Generate a Magic Link

2. Verify the Token

Complete Testing Example

Here's a minimal working example to test the installation:

test-login.php (Request magic link)

test-verify.php (Verify token)

test-logout.php (Clear session)

Testing steps:

1. Insert a test user: INSERT INTO users (email, name) VALUES ('[email protected]', 'Test User');
2. Open test-login.php in your browser
3. Enter [email protected]
4. Click the magic link displayed
5. Verify you're logged in

API Reference

Token Class

__construct(PDO $db)

Create a new token generator.

Parameters:

• $db - PDO database connection

generate(int $user_id, int $ttlSeconds = 900): string

Generate a new magic link token.

Parameters:

• $user_id - User ID from users table
• $ttlSeconds - Time to live in seconds (default: 900 = 15 minutes)

Returns: string - The generated token

Example:

cleanup(int $retentionWeeks = 4): array

Delete expired tokens and nonces.

Parameters:

• $retentionWeeks - Keep records for this many weeks after expiration

Returns: array with keys:

• tokens_deleted - Number of tokens deleted
• nonces_deleted - Number of nonces deleted

Example:

Verifier Class

__construct(PDO $db, int $clockSkewSeconds = 120)

Create a new token verifier.

Parameters:

• $db - PDO database connection
• $clockSkewSeconds - Clock skew tolerance in seconds (default: 120)

verify(string $token): Result

Verify a magic link token.

Parameters:

• $token - The token to verify

Returns: Result object

Example:

verifyFromUrl(string $url, string $paramName = 't'): Result

Extract and verify token from URL.

Parameters:

• $url - Complete URL with token parameter
• $paramName - Query parameter name (default: 't')

Returns: Result object

Result Class

Constants (Error Codes)

Methods

isOk(): bool
Returns true if verification succeeded.

isFailed(): bool
Returns true if verification failed.

getReason(): ?string
Returns error code (null if success).

getData(): ?array
Returns success data array (null if failed).

getUserId(): ?int
Returns authenticated user ID (null if failed).

Internationalization

SimpleAuth includes translations for error messages in multiple languages.

Supported locales:

• en_US - English (United States)
• es_ES - Spanish (Spain)
• it_IT - Italian (Italy)

Customizing messages:

Messages are stored in src/locales/{locale}.php. To override messages in your application:

1. Create directory: src/App/locales/simpleauth/
2. Create locale file: src/App/locales/simpleauth/es_ES.php
3. Override specific messages:

See src/locales/README.md for available message IDs.

Security Best Practices

1. Always use HTTPS for magic link URLs
2. Short TTL: Keep token lifetime short (5-15 minutes recommended)
3. Rate limiting: Limit magic link requests per email/IP
4. Email validation: Verify email ownership before generating tokens
5. Cleanup regularly: Run cleanup() daily via cron job
6. Monitor nonces: Alert on unusual replay attack attempts
7. Secure sessions: Use secure session configuration after authentication

Maintenance

Cleanup Cron Job

Add to your crontab to run daily cleanup:

cleanup.php:

Troubleshooting

Problem: Token always shows as "not found"
Solution: Check that the token is being passed correctly in the URL parameter

Problem: Token shows as "expired" immediately
Solution: Check server time synchronization. Increase clockSkewSeconds if needed.

Problem: "Token already used" on first attempt
Solution: Check for duplicate requests. Ensure the token isn't being consumed multiple times.

Problem: Database errors
Solution: Verify all tables are created and foreign keys are properly set up.

Problem: Autoloader not working (manual installation)
Solution: Verify autoload.php is in the project root and the src/ path is correct.

License

MIT License - see LICENSE file for details.

Forking and Using This Project

This project is a learning exercise and not actively maintained. You are encouraged to:

• Fork this repository and adapt it for your own projects
• Modify the code to fit your specific requirements
• Use it as a reference for understanding passwordless authentication
• Build upon it and create your own improved versions

If you create something interesting based on this work, feel free to share it (but not required).

Support

For questions, review the documentation above or fork the project to experiment. Limited support available at [email protected].

Changelog

1.0.0 (2025-01-15)

• Initial release
• Magic link token generation
• Token verification with replay protection
• Multi-language support (en_US, es_ES, it_IT)
• Clock skew tolerance
• PSR-4 autoloading