laravel-rebel-bridge-laragear-2fa

GitHub repository · Composer: padosoft/laravel-rebel-bridge-laragear-2fa · MIT

Authenticator-app 2FA, graded and audited. Bring laragear/two-factor’s TOTP and recovery codes into Rebel as a proper AAL2 step-up factor — no secret ever touches the audit log.

What it is

A bridge that registers laragear/two-factor as a Rebel step-up driver (LaragearTotpStepUpDriver). It validates a time-based one-time code (or a recovery code) through the TwoFactorValidator contract — backed by LaragearTwoFactorValidator — and reports an AAL2 / AMR otp outcome into Rebel’s assurance model and audit trail. laragear keeps owning the TOTP secrets and QR provisioning.

The problem it solves

Authenticator apps are a solid second factor, but laragear/two-factor on its own treats verification as a boolean and keeps its own state. Your app can’t ask “was this user TOTP-verified strongly enough, and when?”, and the outcome never reaches a shared audit trail. The bridge maps each verification to an AAL2 grade, folds in recovery codes, and records every result once in rebel_auth_events — without ever logging the code.

What you get

When to use it

• You already use laragear/two-factor and want its TOTP graded and audited inside Rebel.
• You want authenticator-app 2FA as a step-up factor for sensitive actions, without SMS costs.
• You need recovery codes handled in the same audited step-up flow.
• You’re consolidating mixed factors onto one assurance scale and one audit trail.

When not to use it

TOTP is AAL2, not phishing-resistant — a user can be tricked into entering a code on a fake page. For the highest assurance, pair it with laravel-rebel-bridge-passkeys (AAL3).

Worked example

composer require padosoft/laravel-rebel-bridge-laragear-2fa
php artisan vendor:publish

The bridge auto-registers LaragearTotpStepUpDriver; config/rebel-bridge-laragear-2fa.php exposes its options. Bind your own TwoFactorValidator to customize verification, or use FakeTwoFactorValidator in tests.

How it fits

This package wraps laragear/two-factor (the upstream TOTP implementation) and registers it with laravel-rebel-step-up (the step-up consumer). It maps each verification onto the AAL/AMR model and audit contract from laravel-rebel-core, placing it at AAL2 — above email/SMS OTP equivalents in audit reasoning, below the phishing-resistant passkey bridge.

A standalone 2FA package verifies a code; this one grades it AAL2 and audits it alongside every other factor. See Why Rebel.

Reference

Runtime files

• src\Contracts\TwoFactorValidator.php
• src\Drivers\LaragearTotpStepUpDriver.php
• src\Support\LaragearBridge.php
• src\Support\LaragearTwoFactorValidator.php
• src\Testing\FakeTwoFactorValidator.php
• src\RebelLaragear2faBridgeServiceProvider.php

Service providers

• src\RebelLaragear2faBridgeServiceProvider.php

Services and managers

• src\RebelLaragear2faBridgeServiceProvider.php

Contracts

• src\Contracts\TwoFactorValidator.php

Controllers

None detected in the package tree.

Middleware

None detected in the package tree.

Models

None detected in the package tree.

Config

• config\rebel-bridge-laragear-2fa.php

Migrations

None detected in the package tree.

Routes

None detected in the package tree.

Commands

None detected in the package tree.

Composer requirements

Development requirements

ADR

Problem: keep laravel-rebel-bridge-laragear-2fa replaceable

Decision: document its public responsibility and use Rebel core contracts at integration boundaries.

Consequences: applications can adopt the package without coupling every other Rebel module to its internals.

Problem: package-specific behavior must remain auditable

Decision: all security-significant outcomes should emit or feed audit events through the core vocabulary.

Consequences: admin API, admin UI and AI guard can reason across packages without bespoke parsers for every provider.

Test and verification surface

• tests\Feature\FakeTwoFactorValidatorTest.php
• tests\Feature\LaragearTotpDriverTest.php
• tests\Feature\ServiceProviderTest.php
• tests\Fixtures\User.php
• tests\Pest.php
• tests\TestCase.php