Tyro Login

Tyro Login is a Laravel authentication infrastructure package designed to provide guards, providers, sessions, tokens, verification, and security for the Tyro ecosystem. It is intended as authentication infrastructure rather than a simple login page generator or starter kit.

Technical Specifications:

• Composer Package: hasinhayder/tyro-login
• Namespace: HasinHayder\\TyroLogin
• PHP Version: ^8.2
• Laravel Version: ^12.0 || ^13.0

When introducing changes to default behaviors in new versions, use versioned configuration keys. This allows existing users to opt-in to new behavior while maintaining their current setup after an upgrade.

Example: Instead of changing a hardcoded redirect, use a config key like tyro-login.redirects.after_login which defaults to an existing behavior (e.g., 'intended').

Use the Cache (not the database) for transient, self-cleaning data such as:

• OTP codes
• Password reset tokens
• Email verification tokens
• Magic link hashes
• Lockout counters

Implementation Rules:

• Prefix all cache keys with tyro-login. to prevent collisions.
• Set the TTL (Time To Live) using values from your configuration.
• Explicitly clear cache keys upon successful completion (e.g., after a password change).

// Cache with TTL - self-cleaning
Cache::put(
    'tyro-login.reset:' . $token,
    ['email' => $email],
    now()->addMinutes(config('tyro-login.password_reset.expire', 60))
);

To ensure testability and extensibility, Tyro Login follows a single-responsibility pattern where each email type has its own dedicated Mailable class. Avoid creating a single generic mailable that uses a $type parameter to switch behavior.

Available Mailables in the package:

• OtpMail
• PasswordResetMail
• VerifyEmailMail
• WelcomeMail
• MagicLinkMail

// Correct: Single-purpose mailable
class OtpMail extends Mailable
{
    use Queueable, SerializesModels;

    public function __construct(
        public string $otp,
        public string $userName,
        public int $expiresInMinutes,
    ) {}

    public function build(): self
    {
        return $this->subject(
            config('tyro-login.emails.otp.subject', 'Your One-Time Password')
        )->view('tyro-login::emails.otp');
    }
}

To ensure security and prevent URL tampering, use a dual validation strategy:

1. Cache-stored token: Stores user data and ensures the token is single-use and expires.
2. Laravel Signed URL: Ensures the reset link has not been modified.

Both the cache entry and the signed URL should share the same expiration time. The cache key pattern is tyro-login:password-reset:{token}.

// Cache token + signed URL
$expiresInMinutes = (int) config('tyro-login.password_reset.expire', 60);
$expiresAt = now()->addMinutes($expiresInMinutes);

Cache::put("tyro-login:password-reset:{$token}", [
    'user_id' => $user->id,
    'email' => $user->email,
], $expiresAt);

$url = URL::temporarySignedRoute(
    'tyro-login.password.reset',
    $expiresAt,
    ['token' => $token]
);

The public API of Tyro Login is a strict contract. Any change to the following elements is considered a breaking change and requires a major version bump:

• Configuration keys (e.g., tyro-login.features.remember_me)
• Route names (e.g., tyro-login.login)
• Method signatures (both public and protected methods in controllers)
• Named parameters
• Blade sections or stacks
• Published view structures
• Static methods
• Command signatures
• Event classes
• Mailables

To avoid breaking changes when renaming routes, use the configuration to provide overrides. For example, if a route name changes, allow users to map the old name to the new one via the routes config key.

To maintain the integrity of the referral system, the following rules must be applied during the referral tracking process:

Self-Referral Prevention

Compare the user_id of the InvitationLink (the referrer) with the $newUserId (the registrant). If they are identical, the attempt is a self-referral.

• Action: Log a warning with the [Tyro-Login] Self-referral attempt detected message and return null silently so registration is not interrupted.

Duplicate Referral Prevention

A user can only be referred once. Before creating a new InvitationReferral record, check if a record already exists for the referred_user_id.

• Action: If an existing record is found, log the event for auditing and return the existing referral instead of creating a duplicate.

Email verification should use two layers of validation:

1. A cache-stored token: Ensures the token is valid, unexpired, and single-use. Use the cache key pattern tyro-login:email-verify:{token}.
2. A Laravel signed URL: Ensures the URL parameters have not been tampered with.

Both the cache entry and the signed URL should share the same expiration time, which is configurable via tyro-login.verification.expire (defaults to 60 minutes).

$expiresInMinutes = (int) config('tyro-login.verification.expire', 60);
$expiresAt = now()->addMinutes($expiresInMinutes);

Cache::put("tyro-login:email-verify:{$token}", [
    'user_id' => $user->id,
    'email' => $user->email,
], $expiresAt);

$url = URL::temporarySignedRoute(
    'tyro-login.verification.verify',
    $expiresAt,
    ['token' => $token]
);

The config/tyro-login.php file is the single source of truth for all package settings.

Never call env() directly inside controllers, commands, mailables, or views. Doing so bypasses the configuration file's defaults, casting, and documentation, and causes the application to ignore any changes a user makes to their published config/tyro-login.php file.

Always use the config() helper to retrieve values.

// Correct: Controller reads from config
public function showLoginForm()
{
    $layout = config('tyro-login.layout', 'centered');
}

// Incorrect: Controller reads env directly (bypasses config)
public function showLoginForm()
{
    $layout = env('TYRO_LOGIN_LAYOUT', 'centered');
}