Download the PHP package padosoft/laravel-rebel-step-up without Composer

Laravel Rebel — Step-Up

Ask for a strong re-confirmation only when it truly matters. The user is already logged in, but is about to perform a sensitive action (change their email, download an invoice, confirm a credit order): Rebel Step-Up asks them for a targeted second factor (email OTP, passkey, TOTP…), with the AAL/AMR security level chosen for that action and — for payments — PSD2/SCA dynamic linking (the confirmation is bound to amount+payee). It is part of the padosoft/laravel-rebel-* suite.

Table of contents

• What it is (and what it is NOT)
• Quick glossary (read it, it takes 1 minute)
• Why Rebel Step-Up — the moats
• Rebel Step-Up vs the "do-it-yourself"
• How it works (the flow, step by step)
• Installation (junior-proof)
• Configuration (every option)
• Usage examples
  • 1. Protect a route with the middleware
  • 2. Manual control (without middleware)
  • 3. Payment with PSD2/SCA dynamic linking
  • 4. Start and confirm a challenge (API/mobile)
  • 5. Choose the driver (passkey-first, OTP fallback)
  • 6. Bind the confirmation to the device
• Validating the config in CI
• .env.example
• Security (what it guarantees you)
• Testing & License

What it is (and what it is NOT)

It is the "control plane" that decides when an already-authenticated user must re-prove who they are before a sensitive action, with what strength (assurance), and binding that confirmation to the specific action (for payments: to amount and payee). You declare a policy for each purpose (action) and Rebel enforces the rule — via middleware or via API.

It is NOT:

• a login system (to sign in there is laravel-rebel-email-otp, or Fortify via laravel-rebel-bridge-fortify); step-up assumes a user already logged in;
• a standalone OTP generator: for email OTP it uses the engine of laravel-rebel-email-otp; for passkey/TOTP it uses the drivers of laravel-rebel-bridge-fortify. Step-Up orchestrates them, it does not reimplement them.

It depends on padosoft/laravel-rebel-core (assurance, contracts, keyed hashing) and on padosoft/laravel-rebel-email-otp (default OTP driver). For the big picture of the ecosystem, start from the core README.

Quick glossary (read it, it takes 1 minute)

Why Rebel Step-Up — the moats

Rebel Step-Up vs the "do-it-yourself"

Legend: ✅ built-in · ➖ partial / hosted-only / not exposed to you · ❌ not available. Note on Shopify: it is a hosted, closed commerce platform you can neither self-host nor extend — it exposes none of these step-up primitives to your own Laravel app, so it's a black box you don't control.

How it works (the flow, step by step)

What happens if…

• the user gets the code wrong too many times → the challenge goes to failed (max attempts configurable);
• the amount changes between start and confirm → binding_mismatch, you start over (the SCA mandates it);
• you raise the policy from aal1 to aal2 after a confirmation → the old aal1 confirmation no longer counts;
• the factor provider goes down during start → the challenge is cancelled (no orphan "pending" entries).

Installation (junior-proof)

Prerequisites: Laravel 12 or 13, PHP 8.3+, with padosoft/laravel-rebel-core and padosoft/laravel-rebel-email-otp already installed (they are pulled in as dependencies).

1) Require the package

2) Publish config and migration

3) Configure the pepper (if you haven't already done so for the core)

Step-up uses the core's keyed hashing for the SCA binding. In your .env:

4) Define your protected actions in config/rebel-step-up.php (see below) and protect a route:

Done: the route now requires a step-up for the change-email purpose.

Configuration (every option)

File config/rebel-step-up.php. Global keys:

Each purposes entry accepts:

Example:

⚠️ If a purpose requires aal2 + require_phishing_resistant but lists only email_otp (which is aal1, not phishing-resistant), the config is insecure: rebel:validate-config fails in CI before deploy (see below).

Usage examples

1. Protect a route with the middleware

• JSON / API request without a valid confirmation → 423 Locked:

• Web request without a confirmation → redirect to redirect_route (if set) or abort(423).

2. Manual control (without middleware)

When you want to handle the flow yourself in a controller:

3. Payment with PSD2/SCA dynamic linking

The confirmation is bound to amount+currency+payee+order. If the user confirms €100 and then someone tries to push the order through at €999, the confirmation does not count.

4. Start and confirm a challenge (API/mobile)

A two-endpoint pattern, perfect for mobile apps (Sanctum tokens):

5. Choose the driver (passkey-first, OTP fallback)

The policy lists the drivers in order of preference; you can also force one:

6. Bind the confirmation to the device

Pass a deviceId (e.g. derived from the Sanctum token or from hash(ip|user-agent)): the confirmation will count only for that device.

A confirmation made on device A does not unlock the action on device B.

Validating the config in CI

Step-up extends the core's command:

It exits with a code ≠ 0 if a purpose is configured insecurely, for example:

• it requires an assurance that none of the listed drivers can reach;
• it demands phishing_resistant but lists only non-phishing-resistant drivers;
• it points to an unregistered driver.

Put it in your CI pipeline so you don't ship rules to production that can't be satisfied:

.env.example

The package commits an .env.example with all the variables used. The essential ones:

Security (what it guarantees you)

• Atomic & single-use verification: confirm runs in a transaction with lockForUpdate; two concurrent confirmations don't both pass.
• Assurance enforcement against the CURRENT policy: a successful confirmation saves the achieved assurance; if the policy is raised, the "old", weaker confirmation lapses.
• PSD2/SCA dynamic linking: keyed HMAC binding (with key_version for rotation) over amount+currency+payee+order; anti-injection JSON canonicalization (no collisions from separators in the fields).
• Symmetric device binding: a context without a device ⇒ only deviceless confirmations; with a device ⇒ only that device. No cross reuse.
• Tenant isolation: every query is scoped per tenant (null-safe).
• Fail-closed: missing/corrupted assurance data ⇒ the confirmation is not valid; an invalid amount (NaN/∞/negative) ⇒ an immediate exception.
• Audit: StepUpRequired, StepUpVerified, StepUpFailed recorded via the core's AuditLogger.

🔋 Vibe coding with batteries included

This package ships AI batteries — so you (and your AI agent) can extend it correctly on the first try:

• CLAUDE.md — a concise AI working guide (purpose, conventions, architecture, how to extend, Definition of Done). Plain Markdown, so Claude Code, Cursor, Copilot and Codex all read it.
• AGENTS.md — the agent/workflow contract (branch → PR → CI → tag/release, the gates).
• .claude/skills/ — invocable skills (at least rebel-package-dev) encoding the suite's TDD loop, the PHPStan-level-max recipes, the security/telemetry rules, and the release discipline.

Open the repo in your AI editor and just start — the rules, guardrails and extension recipes come with it. PRs that follow the shipped CLAUDE.md pass CI (PHPStan max + Pest + Pint) and review the first time around.

Testing & License

The suite covers: start/confirm, wrong code + max attempts, no eligible driver, dynamic linking (amount change, separator collision), TTL expiry, policy raising, device binding, cancellation on driver crash, middleware 423→OK, config validation, and the real integration with the email_otp driver.

License: MIT — see padosoft/laravel-rebel suite.