DEV Community: Hossein Hezami

oving Beyond TOTP: Why the PulseProof Sentinel (PPS) Protocol is the Future of Offline Authentication

Hossein Hezami — Wed, 29 Jul 2026 08:38:21 +0000

Time-based One-Time Passwords (TOTP)—the technology behind Google Authenticator and Microsoft Authenticator—have kept us safe for over a decade. But as cyber threats evolve and systems increasingly move to isolated, semi-offline, or edge environments, the foundational vulnerabilities of TOTP are starting to show.

Enter the PulseProof Sentinel Protocol (PPS), an innovative Internet-Draft registered with the IETF by researcher Hossein Hezami. PPS introduces an elegant shift in cryptographic paradigms: replacing shared-secret symmetric authentication with time-bound asymmetric proofs.

In this article, we’ll dive deep into why PPS is a game-changer, how it operates in 100% offline environments, and how it handles physical coercion with absolute stealth.

The Fatal Flaws of Traditional TOTP

To appreciate PulseProof Sentinel, we must first look at what makes traditional 2FA vulnerable:

The Shared Secret Trap: TOTP relies on a shared symmetric key stored on both your device and the server. If a hacker breaches the server’s database, they steal the raw seeds for every single user.
Lack of Forward Secrecy: If someone compromises your 2FA secret key today, they can often generate future codes or intercept past sessions.

3. No Safety Valve for Physical Coercion: If an attacker physically forces you to open your account under duress, traditional 2FA leaves you with zero options to signal for help safely.

What is PulseProof Sentinel (PPS)?

PulseProof Sentinel (PPS) is an experimental authentication protocol designed specifically for constraint-heavy, offline, or high-risk environments (like IoT networks, remote hardware, or air-gapped point-of-sale terminals).

Instead of generating a random 6-digit number based on a shared secret, PPS generates a cryptographically signed message known as a "Pulse."

1. Zero Server-Side Secrets (Asymmetric Architecture)PPS leverages asymmetric cryptography (Ed25519). The server stores only your Public Key. If the server's database is completely leaked, the attacker gains absolutely nothing that could help them spoof a pulse. Your Private Key remains strictly isolated within your device's Secure Enclave.

2. Time-Counter Hybrid RatchetingTo prevent replay attacks and ensure robust security, PPS uses an asymmetric ratchet mechanism based on SHA-256 and HKDF. Every time a pulse is generated, the private key evolves and the old key is discarded forever. This guarantees strict Forward Secrecy.

How It Works in 100% Offline Environments

One of the biggest engineering achievements of PPS is its ability to validate credentials without requiring any internet connection on the client side.

Imagine an air-gapped smart door lock or an offline POS machine in a remote area:

[ Offline Client Device ]
│ (Generates Compact CBOR Pulse via Ed25519)
▼
[ QR Code / NFC / BLE ]
│
▼
[ Air-Gapped Verifier Terminal ] ───► (Validates Signature via Local Public Key)

The Compact Pulse: The client packs the protocol version, timestamp, unique nonce, counter, and a signature into a highly compressed CBOR (Concise Binary Object Representation) payload.
Passive Data Transfer: This tiny payload is translated into a dynamic QR Code, an NFC burst, or a Bluetooth Low Energy (BLE) packet.
The Dynamic Acceptance Window: What happens if the offline device's internal clock drifts? PPS introduces a Sliding Validation Window. When the verifier receives a pulse, it checks a range of future/past time slots. Once validated, the verifier automatically calculates the exact time drift, saves it to the user's profile, and seamlessly self-corrects for future validations—all without internet sync!

The Coolest Feature: The "Honey-Pulse" (Duress Signaling)

In high-security deployments, physical threats are a real attack vector. PPS addresses this with a brilliant psychological and cryptographic mechanism called Honey-Pulse.

When configuring your device, PPS initiates twin, parallel key-rotation tracks:

Normal Track: For everyday, risk-free authentications.
Honey Track: Triggered only under duress (via an alternative PIN, a specific gesture, or a hidden panic button).

If an attacker forces you to log in, you trigger the Honey Track. The device outputs a pulse that looks mathematically flawless to any onlooker. The attacker sees a successful login animation on the device screen.

However, when the pulse hits the online backend server, it instantly flags the hidden "Honey" indicator. The server subtly sandboxes the session, caps transactional limits to zero, and quietly triggers silent alarms or relays location coordinates to security personnel—all while keeping the attacker completely oblivious.

Current Status and Developer Ecosystem

Because security standards require rigorous peer reviews, PPS is currently classified as an Experimental Internet-Draft within the IETF. It is undergoing active evaluation to ensure it stands up to side-channel attacks and edge-case vulnerabilities.

However, the ecosystem is growing fast. If you are a developer looking to experiment with this cutting-edge protocol, open-source packages are already available:

Core PHP Implementation: pps-php
Laravel Framework Integration: laravel-pps

Conclusion: Is This the Future?

While mass-market web apps are currently pivoting toward Passkeys (WebAuthn/FIDO2), PulseProof Sentinel bridges the critical gaps where FIDO2 cannot easily reach—specifically in completely air-gapped, zero-connectivity environments, and scenarios requiring native, cryptographically hidden duress handling.

It is a masterful piece of security architecture that proves we don't need to invent new math to solve complex problems; we just need to orchestrate the math we have more intelligently.

What are your thoughts on asymmetric offline 2FA? Do you think the Honey-Pulse mechanism should become a standard feature in all modern authentication apps? Let's discuss in the comments below! 👇

Beyond Passkeys and OTP: Why I Built a Protocol for the Authentication Gaps We Keep Ignoring

Hossein Hezami — Thu, 23 Jul 2026 20:09:09 +0000

Passkeys are winning the browser login race.

And they should.

WebAuthn and FIDO2 solved a huge part of the authentication problem: phishing-resistant, browser-native, public-key authentication.

But the more I worked on real systems, the more I noticed a gap.

Not every authentication problem happens inside a browser.

Some happen on a point-of-sale terminal.

Some happen offline.

Some happen inside a legacy OTP form that cannot be rewritten overnight.

Some happen during a high-value transaction where the user must visually confirm an amount.

Some happen under coercion.

And some require approval from more than one device.

That is the gap that led me to PulseProof Sentinel Protocol, or PPS.

PPS is an experimental open authentication protocol that replaces shared-secret TOTP-style codes with signed, time-bound, asymmetric proofs called Pulses.

You can explore the project here:

https://pps-protocol.github.io

The Problem With TOTP

TOTP is everywhere.

It is simple, widely supported, and easy to deploy.

But it has a structural weakness:

code = HMAC(shared_secret, time)

The server knows the secret.

If the server database is breached, the attacker can generate valid codes.

That is not ideal.

Public-key authentication solves this. The server should not need to know the secret that proves identity.

That is the core idea behind PPS:

Pulse = Sign(private_key, time + rp + nonce + counter + context + policy)

The user’s device holds the private key.

The server stores only the public key.

The proof is signed, time-bound, replay-protected, and bound to the relying party.

PPS Is Not a WebAuthn Replacement

This is important.

PPS is not trying to replace WebAuthn.

If you are building browser-based passwordless login, WebAuthn is usually the right answer.

PPS is designed to complement WebAuthn.

It targets the operational gaps where WebAuthn is unavailable, impractical, or insufficient:

offline authentication
legacy OTP input forms
QR-code and deep-link authentication
constrained hardware terminals
point-of-sale and IoT devices
human-visible transaction confirmation
silent duress signaling
offline multi-device threshold approval

In other words:

WebAuthn is for passkeys.

PPS is for the authentication flows that still live outside the passkey world.

What Is a Pulse?

A Pulse is a signed authentication statement.

It can be bound to several things:

a relying-party identifier
a time epoch
a server nonce
a monotonic counter
an expiration window
a security policy
a transaction hash
environmental context

This makes PPS flexible.

A Pulse can be used for simple login.

It can also be used for transaction signing, offline terminal authentication, or multi-device approval.

The protocol uses deterministic CBOR encoding and Ed25519 signatures.

The mandatory profile is:

PPS-ED25519-CBOR30

You can read the full specification here:

https://pps-protocol.github.io/pulseproof-sentinel/SPEC.html

The documentation is available here:

https://pps-protocol.github.io/pulseproof-sentinel/docs/

The protocol is also submitted as an IETF Internet-Draft:

https://datatracker.ietf.org/doc/draft-hezami-pulseproof-sentinel/

The Developer Story: PHP and Laravel

A protocol is only useful if people can implement it.

That is why the first sample implementation is available in PHP.

The core package is framework-agnostic:

https://github.com/pps-protocol/pps-php

You can install it with Composer:

composer require pps-protocol/pps-php

Package website:

https://pps-protocol.github.io/pps-php/

Documentation:

https://pps-protocol.github.io/pps-php/docs/

Packagist:

https://packagist.org/packages/pps-protocol/pps-php

For Laravel applications, there is a dedicated integration package:

https://github.com/pps-protocol/laravel-pps

Install it with:

composer require pps-protocol/laravel-pps

Then run:

php artisan pps:install

The Laravel package provides:

service provider
publishable configuration
API routes
HTTP controller
facade
Artisan commands
storage backend integration
transaction challenge endpoints
silent duress handling support

Laravel package website:

https://pps-protocol.github.io/laravel-pps/

Packagist:

https://packagist.org/packages/pps-protocol/laravel-pps

A Small Example

At the protocol level, the idea is simple.

The client signs a Pulse:

use Pps\Client\AuthenticatorClient;

$client = new AuthenticatorClient($clientState);

$pulse = $client
    ->rpId('example.com')
    ->nonce($nonceFromServer)
    ->createPulse();

The server verifies it using the stored public key.

No shared OTP secret is required.

In Laravel, the package exposes endpoints such as:

GET  /pps/health
GET  /pps/challenge
POST /pps/register
POST /pps/verify
POST /pps/transaction/challenge
POST /pps/transaction/verify

This makes it easy to integrate PPS into an existing authentication or transaction-signing flow.

Transaction Signing Is Where PPS Becomes Interesting

One of my favorite PPS features is transaction signing.

Imagine a withdrawal:

Amount: 2,500,067 IRR
Trust Code: 49371867

The last two digits of the Trust Code come from the transaction amount.

This creates a human-visible connection between the cryptographic proof and the transaction being approved.

The user can confirm:

Yes, the code I see matches the amount I requested.

This is especially useful for:

banking
fintech
crypto withdrawals
admin approvals
high-value payments
corporate treasury flows

PPS can bind the transaction hash, amount, session, and policy into the signed Pulse.

That is much stronger than sending a generic OTP code.

Silent Duress: Authentication Under Coercion

Another important area is duress.

What happens if someone is forced to authenticate?

Traditional OTP systems do not have a good answer.

PPS introduces an optional duress mechanism.

The user can authenticate with a hidden duress key.

The resulting Pulse is cryptographically valid, but the server recognizes it as a Honey-Pulse.

The server can return a normal-looking success response while internally:

restricting account capabilities
blocking high-value operations
delaying settlement
triggering a silent alert
preserving audit logs

This is sensitive territory, and implementation matters a lot.

But for high-risk accounts, it is a powerful concept.

Offline and Multi-Device Flows

PPS also supports offline authentication.

Because a Pulse is signed and time-bound, it can be generated without a live network round-trip.

Offline mode requires stricter rate limiting and careful operational design, but it is useful for:

terminals
IoT devices
field equipment
unstable networks
emergency access

PPS also supports offline multi-device threshold approval.

For example:

2-of-2: phone + watch
2-of-3: phone + laptop + hardware key

This is useful when a single device should not be enough to approve a sensitive action.

The Ecosystem

The PPS project is organized under a GitHub organization:

https://github.com/pps-protocol

The main repositories are:

PulseProof Sentinel Protocol

The specification repository.

https://github.com/pps-protocol/pulseproof-sentinel

Website:

https://pps-protocol.github.io/pulseproof-sentinel/

Specification:

https://pps-protocol.github.io/pulseproof-sentinel/SPEC.html

Documentation:

https://pps-protocol.github.io/pulseproof-sentinel/docs/

pps-php

The core PHP implementation.

https://github.com/pps-protocol/pps-php

Website:

https://pps-protocol.github.io/pps-php/

Documentation:

https://pps-protocol.github.io/pps-php/docs/

Packagist:

https://packagist.org/packages/pps-protocol/pps-php

laravel-pps

The Laravel integration package.

https://github.com/pps-protocol/laravel-pps

Website:

https://pps-protocol.github.io/laravel-pps/

Packagist:

https://packagist.org/packages/pps-protocol/laravel-pps

Why Explore PPS?

PPS is experimental.

It has not been independently audited.

It is not ready to replace your production authentication system tomorrow.

But if you care about authentication design, it is worth exploring.

It is especially interesting if you are working on:

fintech authentication
crypto exchange security
offline device login
POS terminals
IoT authentication
transaction signing
high-value approval workflows
duress-aware accounts
multi-device authorization
legacy OTP migration

PPS asks a simple question:

Why should the server ever store a shared OTP secret when it can verify a signature instead?

Start Here

The best place to start is the project website:

https://pps-protocol.github.io

Then read the specification:

https://pps-protocol.github.io/pulseproof-sentinel/SPEC.html

If you are a PHP developer, try the core package:

composer require pps-protocol/pps-php

If you are using Laravel, install the Laravel integration:

composer require pps-protocol/laravel-pps

And if you are interested in protocol design, review the IETF Internet-Draft:

https://datatracker.ietf.org/doc/draft-hezami-pulseproof-sentinel/

PPS is early, experimental, and open for feedback.

If you believe authentication should move beyond shared secrets, give it a look.

TOTP Secrets Are a Liability: Meet PPS, an Asymmetric Authentication Protocol for PHP and Laravel

Hossein Hezami — Thu, 23 Jul 2026 20:01:37 +0000

Most two-factor authentication systems still rely on a dangerous assumption:

If the server is breached, authentication secrets can be protected.

TOTP breaks that assumption.

With TOTP, the server stores a shared secret. If your database leaks, attackers can generate valid OTP codes.

That is exactly the problem PulseProof Sentinel Protocol, or PPS, tries to solve.

PPS is an experimental open authentication protocol that replaces shared-secret TOTP codes with signed, time-bound, asymmetric proofs called Pulses.

Instead of this:

TOTP:
  code = HMAC(shared_secret, time)

PPS uses this:

PPS:
  Pulse = Sign(private_key, time + rp + nonce + counter + context + policy)

The server never stores a shared OTP secret.

It stores only public keys.

What Is PPS?

PulseProof Sentinel Protocol is an asymmetric authentication protocol designed for scenarios where traditional OTP, push authentication, and even WebAuthn are not enough.

It is especially useful for:

offline authentication
legacy OTP input forms
QR-code and deep-link login
constrained hardware terminals
point-of-sale and IoT devices
transaction signing with human-visible confirmation
silent duress signaling
offline multi-device threshold approval

PPS is not trying to replace WebAuthn/FIDO2.

WebAuthn remains the preferred standard for browser-based passkey authentication.

PPS is designed to complement WebAuthn by covering operational gaps where WebAuthn is unavailable or impractical.

You can explore the protocol here:

Project website: https://pps-protocol.github.io
Specification: https://pps-protocol.github.io/pulseproof-sentinel/SPEC.html
Documentation: https://pps-protocol.github.io/pulseproof-sentinel/docs/
IETF Internet-Draft: https://datatracker.ietf.org/doc/draft-hezami-pulseproof-sentinel/
GitHub organization: https://github.com/pps-protocol

Why Not Just Use WebAuthn?

WebAuthn is excellent.

If you are building browser-based passwordless authentication, use WebAuthn.

But many real systems still need:

- OTP-style input fields
- offline verification
- hardware terminals without browser support
- transaction amount confirmation
- silent duress codes
- multi-device approval
- QR/deep-link authentication flows

That is where PPS fits.

Think of it like this:

Scenario	Recommended
Browser passkey login	WebAuthn/FIDO2
Legacy OTP form	PPS
Offline terminal authentication	PPS
High-value transaction signing	PPS
Silent duress authentication	PPS
Multi-device approval	PPS
IoT or constrained device authentication	PPS

Core Features

PPS includes a small core protocol plus optional advanced modules.

Core

Ed25519 signatures
deterministic CBOR encoding
time-bound Pulses
nonce binding
monotonic counter replay protection
relying-party binding
expiration enforcement

Optional Advanced Modules

forward-secure key ratcheting
silent duress / Honey-Pulse signaling
offline n-of-m threshold approval
transaction AmountMark verification
dynamic policy binding
environmental context binding

The protocol specification is available here:

https://pps-protocol.github.io/pulseproof-sentinel/SPEC.html

The PHP Implementation: `pps-php`

The core PHP implementation is available as a framework-agnostic package:

pps-protocol/pps-php

Links:

GitHub: https://github.com/pps-protocol/pps-php
Website: https://pps-protocol.github.io/pps-php/
Documentation: https://pps-protocol.github.io/pps-php/docs/
Packagist: https://packagist.org/packages/pps-protocol/pps-php

Install it with Composer:

composer require pps-protocol/pps-php

It supports:

Pulse creation
Pulse verification
registration flows
Trust Code generation
AmountMark transaction codes
duress keys
threshold signatures
offline mode
memory, file, PDO, and Redis storage backends

Quick Example: Creating a Pulse

Here is a simplified client-side example:

use Pps\Client\AuthenticatorClient;

$client = new AuthenticatorClient($clientState);

$pulse = $client
    ->rpId('example.com')
    ->nonce($nonceFromServer)
    ->createPulse();

echo $pulse['token'];
echo $pulse['trust_code'];

The server verifies the Pulse using only the stored public key.

No shared secret is required.

Laravel Integration: `laravel-pps`

If you are using Laravel, there is a dedicated integration package:

pps-protocol/laravel-pps

Links:

GitHub: https://github.com/pps-protocol/laravel-pps
Website: https://pps-protocol.github.io/laravel-pps/
Packagist: https://packagist.org/packages/pps-protocol/laravel-pps

Install it:

composer require pps-protocol/laravel-pps

Then run:

php artisan pps:install

This publishes the PPS config and migrations.

The package provides:

service provider
publishable configuration
API routes
HTTP controller
facade
Artisan commands
storage backend integration
transaction challenge endpoints
silent duress handling support

Default routes:

Method	Endpoint	Description
GET	`/pps/health`	Health check
GET	`/pps/challenge`	Create authentication challenge
POST	`/pps/register`	Register a device
POST	`/pps/verify`	Verify a Pulse Token
POST	`/pps/transaction/challenge`	Create transaction challenge
POST	`/pps/transaction/verify`	Verify transaction-bound Pulse

Test the health endpoint:

curl http://localhost:8000/pps/health

Example response:

{
    "status": "ok",
    "protocol": "PulseProof Sentinel Protocol",
    "version": 1,
    "algorithm": "PPS-ED25519-CBOR30",
    "epoch_seconds": 30,
    "rp_id": "localhost"
}

Transaction Signing With AmountMark

One of the most useful PPS features is transaction signing.

Imagine a withdrawal:

Amount: 2,500,067 IRR
Trust Code: 49371867

The last two digits, 67, are derived from the transaction amount.

This allows the user to visually confirm that the signed transaction matches the displayed amount.

The client binds the transaction hash and amount to the Pulse:

use Pps\Crypto\Base64Url;
use Pps\Payload\ContextObject;

$context = new ContextObject();
$context->sessionId = Base64Url::decode($sessionId);
$context->txHash = Base64Url::decode($txHash);

$pulse = $client
    ->rpId('example.com')
    ->nonce($nonce)
    ->context($context)
    ->amountMinor(2500067)
    ->createPulse();

The server verifies:

signature
nonce
counter
transaction hash
amount mark
Trust Code

This is much stronger than sending a plain OTP for transaction confirmation.

Silent Duress Authentication

PPS also supports silent duress signaling.

If a user is forced to authenticate, the client can sign with a hidden duress key.

The server detects this internally but returns a normal-looking success response.

if ($result->honey) {
    // Return normal response.
    // Internally restrict account, alert security, delay settlement, etc.
}

This is useful for fintech, banking, crypto exchanges, and high-risk accounts.

The outward response should remain indistinguishable from a normal login.

How PPS Compares to TOTP

Feature	TOTP	PPS
Shared secret on server	Yes	No
Asymmetric proof	No	Yes
Offline capable	Yes	Yes
Legacy OTP form support	Yes	Yes
Transaction binding	Weak	Strong
Amount confirmation	No	Yes
Silent duress	No	Optional
Threshold approval	No	Optional
Policy binding	No	Optional
Context binding	No	Optional

Important Links

Here are the most important links if you want to explore PPS:

Project website: https://pps-protocol.github.io
Protocol repository: https://github.com/pps-protocol/pulseproof-sentinel
Specification: https://pps-protocol.github.io/pulseproof-sentinel/SPEC.html
Documentation: https://pps-protocol.github.io/pulseproof-sentinel/docs/
IETF Internet-Draft: https://datatracker.ietf.org/doc/draft-hezami-pulseproof-sentinel/
PHP core package: https://github.com/pps-protocol/pps-php
PHP package docs: https://pps-protocol.github.io/pps-php/docs/
Laravel package: https://github.com/pps-protocol/laravel-pps
Laravel package website: https://pps-protocol.github.io/laravel-pps/
Packagist core package: https://packagist.org/packages/pps-protocol/pps-php
Packagist Laravel package: https://packagist.org/packages/pps-protocol/laravel-pps

Try It

If you are building:

fintech authentication
crypto withdrawal confirmation
offline device authentication
POS or IoT login
high-security admin approval
duress-aware accounts
multi-device authorization

PPS may be worth exploring.

Start with the website:

https://pps-protocol.github.io

Then read the specification:

https://pps-protocol.github.io/pulseproof-sentinel/SPEC.html

If you use PHP or Laravel, install the packages:

composer require pps-protocol/pps-php
composer require pps-protocol/laravel-pps

PPS is experimental, so it is not recommended for production without security review. But if you are interested in authentication protocols, asymmetric OTP alternatives, or transaction signing, it is definitely worth a look.

If you find the idea useful, star the repositories, test the packages, and share feedback.

GitHub organization:

https://github.com/pps-protocol

Master Role-Based Access Control with Laravel Permission Manager

Hossein Hezami — Wed, 24 Sep 2025 14:33:20 +0000

Building a secure, scalable Laravel application often requires a robust permission management system. Enter Laravel Permission Manager, a powerful package designed to streamline role-based access control (RBAC) with a flexible, feature-rich API. Whether you're securing routes, managing roles, or integrating permissions into your Blade templates, this package has you covered. In this post, I'll walk you through its installation, configuration, and usage to help you implement a bulletproof RBAC system in your Laravel app.

Why Laravel Permission Manager?

The Laravel Permission Manager package, developed by Hossein Hezami, offers a comprehensive solution for managing roles and permissions in Laravel applications. Here’s what makes it stand out:

Role-Based Access Control (RBAC): Assign multiple roles to users and permissions to roles.
Wildcard Permissions: Support for flexible route matching (e.g., admin.*, *admin*).
Blade Directives: Easily check roles and permissions in templates with @hasRole and @hasPermission.
Artisan Commands: Manage roles and permissions from the command line.
Facade Methods: Programmatically handle roles and permissions with a fluent API.
Middleware Support: Protect routes with role or permission checks.
Caching: Boost performance with permission caching.
Multi-Guard Support: Works seamlessly with Laravel’s authentication guards.
Export/Import: Save and restore roles/permissions as JSON.

Ready to get started? Let’s dive into the setup and usage.

Installation

Installing Laravel Permission Manager is straightforward with Composer. Follow these steps to integrate it into your Laravel project:

Install the Package Run the following command to install the package:

   composer require hosseinhezami/laravel-permission-manager

Register the Service Provider (Optional) If Laravel’s package auto-discovery is disabled, add the service provider and facade to config/app.php:

   'providers' => [
       // ...
       HosseinHezami\PermissionManager\PermissionManagerServiceProvider::class,
   ],
   'aliases' => [
       // ...
       'PermissionManager' => HosseinHezami\PermissionManager\Facades\PermissionManager::class,
   ],

Publish Configuration and Migrations Publish the configuration file and migrations to set up the package:

   php artisan vendor:publish --provider="HosseinHezami\PermissionManager\PermissionManagerServiceProvider" --tag="config"
   php artisan vendor:publish --provider="HosseinHezami\PermissionManager\PermissionManagerServiceProvider" --tag="migrations"

Run Migrations Create the necessary database tables for roles and permissions:

   php artisan migrate

Add the Permission Trait Add the PermissionTrait to your User model:

   namespace App\Models;

   use HosseinHezami\PermissionManager\Traits\PermissionTrait;
   use Illuminate\Foundation\Auth\User as Authenticatable;

   class User extends Authenticatable
   {
       use PermissionTrait;
   }

Run the Install Command For a streamlined setup, use the Artisan install command. Here are some variations:

   # Basic installation
   php artisan permission-manager:install

   # Install and run migrations
   php artisan permission-manager:install --migrate

   # Install, run migrations, and overwrite existing files
   php artisan permission-manager:install --migrate --force

   # Install with a custom User model path
   php artisan permission-manager:install --user-model=/path/to/User.php

Configuration

After publishing the configuration, you can customize the package in config/permission-manager.php. Here’s a sample configuration:

return [
    'models' => [
        'role' => \HosseinHezami\PermissionManager\Models\Role::class,
        'permission' => \HosseinHezami\PermissionManager\Models\Permission::class,
        'user' => \App\Models\User::class,
    ],
    'tables' => [
        'roles' => 'roles',
        'permissions' => 'permissions',
        'role_permissions' => 'role_permissions',
        'user_roles' => 'user_roles',
    ],
    'cache_duration' => 60, // Cache permissions for 60 minutes
    'log_denials' => false, // Log permission/role denials
    'wildcards' => true, // Enable wildcard support
];

This file lets you tweak model classes, table names, caching duration, and wildcard support to suit your application’s needs.

Database Migrations

The package creates four tables to manage roles and permissions:

roles: Stores role details (name, slug, description).
permissions: Stores permission routes (e.g., users.edit).
role_permissions: Links roles to permissions.
user_roles: Links users to roles.

The migrations are automatically published when you run the vendor:publish command for the migrations tag.

Usage

Let’s explore how to leverage Laravel Permission Manager in your application.

1. Blade Directives

Control access in your Blade templates with intuitive directives:

@hasRole('admin')
    <p>Welcome, Admin!</p>
@endhasRole

@hasPermission('users.edit')
    <a href="/users/edit">Edit User</a>
@endhasPermission

These directives make it easy to show or hide content based on roles or permissions.

2. Middleware

Protect routes with middleware for roles or permissions:

Route::get('/admin', [AdminController::class, 'index'])
    ->middleware('pm:role:admin|manager');

Route::get('/posts', [PostController::class, 'create'])
    ->middleware('pm:permission:posts|post.create');

The pm middleware ensures only users with the specified roles or permissions can access the route.

3. Artisan Commands

Manage roles and permissions directly from the terminal:

# List roles and permissions
php artisan roles:list
php artisan permissions:list

# Create a role
php artisan role:create admin "Administrator" "Has full system access"

# Update a role
php artisan role:update admin --name="Super Admin" --description="Updated description"

# Delete a role
php artisan role:delete admin

# Create permissions
php artisan permission:create "users.*"
php artisan permission:create "users.create,users.edit"

# Sync routes with permissions
php artisan permission:sync-routes

# Assign/revoke permissions to a role
php artisan role:assign-permission admin "users.*"
php artisan role:revoke-permission admin "users.edit"

# Assign/revoke roles to a user
php artisan user:assign-role 1 admin
php artisan user:revoke-role 1 admin

# Export/import roles
php artisan role:export roles.json
php artisan role:import roles.json

These commands make it easy to manage your RBAC system without writing code.

4. Facade Methods

For programmatic control, use the PermissionManager facade:

use HosseinHezami\PermissionManager\Facades\PermissionManager;

// Create a role
PermissionManager::roles()->create([
    'slug' => 'admin',
    'name' => 'Administrator',
    'description' => 'Has full system access'
]);

// Assign permissions to a role
PermissionManager::role('admin')->assignPermission('users.edit');

// Assign a role to a user
PermissionManager::user(1)->assignRole('admin');

// Check permissions
$hasPermission = PermissionManager::user(1)->hasPermission('users.edit');

5. Wildcard Permissions

Wildcard permissions add flexibility to route matching:

// Match all routes starting with 'admin'
PermissionManager::permissions()->create('admin.*');

// Match all routes containing 'admin'
PermissionManager::permissions()->create('*admin*');

6. Trait Methods

The PermissionTrait adds convenient methods to your User model:

$user = User::find(1);

// Assign a role
$user->assignRole('admin');

// Check permissions
if ($user->hasPermission('users.edit')) {
    // Allow edit action
}

Best Practices

Use Descriptive Slugs: Choose clear, meaningful slugs for roles and permissions (e.g., users.edit instead of edit).
Leverage Wildcards: Group related routes with wildcards (e.g., users.* for all user-related actions).
Sync Routes Regularly: Run php artisan permission:sync-routes to keep permissions aligned with your routes.
Enable Caching: Set a reasonable cache_duration in production to improve performance.
Handle Exceptions: Use the package’s custom exceptions (e.g., UnauthorizedException) for robust error handling.

Conclusion

The Laravel Permission Manager package is a game-changer for developers building secure Laravel applications. Its intuitive API, comprehensive Artisan commands, and flexible features like wildcard permissions and Blade directives make it a must-have for implementing RBAC. Whether you’re managing a small app or a large-scale system, this package simplifies access control without compromising on power.

Check out the official documentation for more details, and feel free to contribute via the GitHub repository. Got questions? Reach out to the maintainer at hossein.hezami@gmail.com.

What’s your favorite way to manage permissions in Laravel? Share your thoughts in the comments!

Build Laravel AI Features in Minutes: A Guide to the Gemini Package

Hossein Hezami — Fri, 12 Sep 2025 23:40:51 +0000

Tired of reading docs and just want to see the code? Let's dive straight into how you can use the hosseinhezami/laravel-gemini package to add powerful AI features to your Laravel application. The API is clean, fluent, and incredibly powerful.

Installation & Setup

First, get the package.

composer require hosseinhezami/laravel-gemini

Publish the config file and set your API key.

php artisan vendor:publish --tag=gemini-config

# .env
GEMINI_API_KEY=your_gemini_api_key_here

Code Examples: See It in Action

1. Basic Text Generation & Chat

The TextBuilder makes generating text or creating a chat interface simple.

use HosseinHezami\LaravelGemini\Facades\Gemini;

// Simple prompt
$response = Gemini::text()
    ->prompt('Write a tagline for a developer blog.')
    ->generate();

echo $response->content();

// Chat with history
$history = [
    ['role' => 'user', 'parts' => [['text' => 'Hello!']]],
    ['role' => 'model', 'parts' => [['text' => 'Hi there! How can I help?']]]
];

$response = Gemini::text()
    ->prompt('What’s the weather like?')
    ->history($history)
    ->temperature(0.7)
    ->generate();

echo $response->content();

2. Structured Data Extraction

Need consistent JSON output from a messy prompt? Use structuredSchema.

$response = Gemini::text()
    ->structuredSchema([
        'type' => 'object',
        'properties' => [
            'sentiment' => [
                'type' => 'string',
                'enum' => ['positive', 'negative', 'neutral']
            ],
            'confidence' => ['type' => 'number'],
            'key_points' => {
                'type' => 'array',
                'items' => {'type' => 'string'}
            }
        ],
        'required' => ['sentiment']
    ])
    ->prompt('The product is amazing but the delivery was late. I love the features though.')
    ->generate();

$analysis = json_decode($response->content());
// $analysis->sentiment, $analysis->key_points, etc.

3. Image Generation

Generate images from a text description.

$response = Gemini::image()
    ->prompt('A minimalist logo for a tech startup called "Nexus", using blue and green')
    ->generate();

// Save the generated image directly
$response->save(storage_path('app/logo.png'));

4. Document Understanding

Upload a file (PDF, DOC, image) and ask questions about it.

// First, upload the file to Gemini's servers
$fileUri = Gemini::files()->upload('document', $pathToInvoicePdf);

// Then, use it in a prompt
$response = Gemini::text()
    ->upload('document', $pathToInvoicePdf) // or use the $fileUri
    ->prompt('What is the total amount due on this invoice?')
    ->generate();

echo $response->content();

5. Text-to-Speech (Audio)

Generate spoken audio from text.

$response = Gemini::audio()
    ->prompt('Welcome to our application. We are thrilled to have you on board.')
    ->voiceName('Kore') // Check docs for available voices
    ->generate();

// The package smartly handles the binary response,
// allowing you to save it directly.
$response->save(public_path('audio/welcome.mp3'));

6. Real-Time Streaming

Crucial for building chat interfaces that feel fast and responsive.

// In your controller (e.g., app/Http/Controllers/ChatController.php)
public function stream(Request $request)
{
    return response()->stream(function () use ($request) {
        Gemini::text()
            ->model('gemini-2.5-flash-lite') // Use a fast model for streaming
            ->prompt($request->query('message'))
            ->stream(function ($chunk) {
                $text = $chunk['text'] ?? '';
                if (connection_aborted()) return;
                echo "data: " . json_encode(['text' => $text]) . "\n\n";
                ob_flush();
                flush();
            });
    }, 200, [
        'Content-Type' => 'text/event-stream',
        'Cache-Control' => 'no-cache',
        'Connection' => 'keep-alive',
        'X-Accel-Buffering' => 'no',
    ]);
}

Ready to Build?

This is just the surface. The package also handles video generation, embeddings, and full file management.

For complete documentation, check out the official docs:
https://hosseinhezami.github.io/laravel-gemini/

Source:

What will you build first? Let me know in the comments! 👇

TOTP Authenticator: A Lightweight PHP Library for Secure Two-Factor Authentication

Hossein Hezami — Fri, 05 Sep 2025 11:08:13 +0000

Two-Factor Authentication (2FA) has become an essential layer of security for web applications, helping protect user accounts even if passwords are compromised. Among the most widely used 2FA methods is TOTP (Time-based One-Time Password), supported by popular apps like Google Authenticator, Authy, and Microsoft Authenticator.

For PHP developers looking to add TOTP-based authentication to their projects, TOTP Authenticator provides a simple, lightweight, and secure solution.

Key Features

🔐 Secure Secret Generation: Generates cryptographically secure secrets with configurable lengths.

⏱ Time-based OTP Generation: Produces 6-digit one-time passwords compliant with RFC 6238.

✅ Code Verification: Validates user input with support for slight time drift to accommodate clock differences.

📱 QR Code Generation: Creates URLs compatible with Google Authenticator and similar 2FA apps.

🔒 Timing-Safe Comparison: Protects against timing attacks during code verification.

💡 Zero Dependencies: Pure PHP library (requires PHP 7.4 or higher).

Installation
Install the library easily using Composer:

composer require hosseinhezami/totp-authenticator

Getting Started
Here's a quick example demonstrating the core functionality of the library:

use HosseinHezami\TotpAuthenticator\Authenticator;

// Generate a secure secret
$secret = Authenticator::createSecret(16);

// Generate a TOTP code
$code = Authenticator::generateCode($secret);

// Verify the code
$isValid = Authenticator::verifyCode($secret, $code);
echo $isValid ? "Valid code" : "Invalid code";

// Generate a QR code URL for Google Authenticator
$qrCodeUrl = Authenticator::generateQrCodeUrl("user@example.com", $secret, "MyApp");
echo $qrCodeUrl;

The QR code URL can be scanned directly in any TOTP-compatible authenticator app.
Verification uses timing-safe comparison to ensure maximum security.

Laravel Integration Example
Integrating this library into a Laravel project is straightforward. For example, a route can be defined to test all the functionalities:

use HosseinHezami\TotpAuthenticator\Authenticator;
Route::get('/totp-test', function () {
    $secret = Authenticator::createSecret(16);
    $code = Authenticator::generateCode($secret);
    $isValid = Authenticator::verifyCode($code, $secret);
    $qrCodeUrl = Authenticator::generateQrCodeUrl('testuser@example.com', $secret, 'MyApp');

    return response()->json([
        'secret' => $secret,
        'generated_code' => $code,
        'verify_code' => $isValid,
        'qr_code_url' => $qrCodeUrl
    ]);
});

This provides a ready-to-use JSON response for testing secret generation, code verification, and QR code creation.

Why Use TOTP Authenticator?

Lightweight & Minimal Setup: Easy to integrate without heavy dependencies.
Secure & Standards-Compliant: Follows RFC 6238 and implements cryptographically secure operations.
Flexible: Works in both plain PHP and frameworks like Laravel.
Developer-Friendly: Provides all the core TOTP functionality without complexity.

Resources
GitHub: https://github.com/hosseinhezami/totp-authenticator
Packagist: https://packagist.org/packages/hosseinhezami/totp-authenticator

DEV Community: Hossein Hezami

oving Beyond TOTP: Why the PulseProof Sentinel (PPS) Protocol is the Future of Offline Authentication

In this article, we’ll dive deep into why PPS is a game-changer, how it operates in 100% offline environments, and how it handles physical coercion with absolute stealth.

The Fatal Flaws of Traditional TOTP

3. No Safety Valve for Physical Coercion: If an attacker physically forces you to open your account under duress, traditional 2FA leaves you with zero options to signal for help safely.

What is PulseProof Sentinel (PPS)?

2. Time-Counter Hybrid RatchetingTo prevent replay attacks and ensure robust security, PPS uses an asymmetric ratchet mechanism based on SHA-256 and HKDF. Every time a pulse is generated, the private key evolves and the old key is discarded forever. This guarantees strict Forward Secrecy.

How It Works in 100% Offline Environments

The Coolest Feature: The "Honey-Pulse" (Duress Signaling)

Current Status and Developer Ecosystem

Conclusion: Is This the Future?

Beyond Passkeys and OTP: Why I Built a Protocol for the Authentication Gaps We Keep Ignoring

The Problem With TOTP

PPS Is Not a WebAuthn Replacement

What Is a Pulse?

The Developer Story: PHP and Laravel

A Small Example

Transaction Signing Is Where PPS Becomes Interesting

Silent Duress: Authentication Under Coercion

Offline and Multi-Device Flows

The Ecosystem

PulseProof Sentinel Protocol

pps-php

laravel-pps

Why Explore PPS?

Start Here

TOTP Secrets Are a Liability: Meet PPS, an Asymmetric Authentication Protocol for PHP and Laravel

What Is PPS?

Why Not Just Use WebAuthn?

Core Features

Core

Optional Advanced Modules

The PHP Implementation: pps-php

Quick Example: Creating a Pulse

Laravel Integration: laravel-pps

Transaction Signing With AmountMark

Silent Duress Authentication

How PPS Compares to TOTP

Important Links

Try It

Master Role-Based Access Control with Laravel Permission Manager

Why Laravel Permission Manager?

Installation

Configuration

Database Migrations

Usage

1. Blade Directives

2. Middleware

3. Artisan Commands

4. Facade Methods

5. Wildcard Permissions

6. Trait Methods

Best Practices

Conclusion

Build Laravel AI Features in Minutes: A Guide to the Gemini Package

Installation & Setup

Code Examples: See It in Action

1. Basic Text Generation & Chat

2. Structured Data Extraction

3. Image Generation

4. Document Understanding

5. Text-to-Speech (Audio)

6. Real-Time Streaming

Ready to Build?

TOTP Authenticator: A Lightweight PHP Library for Secure Two-Factor Authentication

The PHP Implementation: `pps-php`

Laravel Integration: `laravel-pps`