Download the PHP package alvinfadli/access-lock without Composer

access-lock

A lightweight Laravel package that password-protects your application (or specific routes) using a middleware, a JavaScript prompt(), and Laravel session storage.

Not intended for production-grade authentication. Use this as a simple access gate — e.g. for staging environments, internal tools, or early-access previews.

Requirements

Installation

1. Install via Composer

The service provider is auto-discovered; no manual registration is needed.

2. Set a Password

Run the Artisan command to set the access password:

You will be prompted to enter and confirm a password. The bcrypt hash is automatically written to your .env file as:

If you cache your configuration, clear it afterwards:

Usage

Web (Monolith / Blade)

Important: always add this middleware inside the web group, never in the global middleware stack. The global stack runs before StartSession, so $request->session() would not be available yet and you would get a "Session store not set on request" error.

Laravel 10 — app/Http/Kernel.php

Add it to the web group (after StartSession):

Laravel 11 / 12 / 13 — bootstrap/app.php

Use appendToGroup('web', ...) — not append():

API (Decoupled / SPA / Mobile)

For decoupled setups (e.g. Angular, React, Vue, or mobile apps talking to a Laravel API), use the access.lock.api middleware instead. It is token-based and returns JSON responses rather than redirecting to a Blade view.

1. Protect your API routes

2. Obtain a token

POST the staging password to the built-in unlock endpoint. No authentication is required for this endpoint — it is the entry point.

Success (200):

Wrong password (401):

3. Use the token on subsequent requests

Include the token on every protected API request using one of two headers:

or

The middleware verifies the token against the configured bcrypt hash on every request — no session or cache storage is needed.

How it works

1. The client POSTs the password to /api/access-lock/unlock.
2. The package verifies it using access_lock_verify().
3. On success, the plain-text password is returned as a token.
4. The client stores the token (e.g. localStorage) and sends it with every subsequent request.
5. AccessLockApiMiddleware calls access_lock_verify(token) on each request — if it matches the configured hash, the request passes through; otherwise it returns 403.

Protect a Route Group (web)

Protect a Single Route (web)

Protect a Route Group (api)

Protect a Single Route (api)

How It Works (Web)

1. A visitor hits a protected route.
2. AccessLockMiddleware checks the Laravel session for access_lock_unlocked = true.
3. If not unlocked, the visitor is redirected to /access-lock.
4. The unlock page loads and a window.prompt() dialog appears automatically.
5. The visitor enters the password and it is submitted via POST.
6. If correct, the session flag is set and the visitor is redirected back to the original URL.
7. If incorrect, the unlock page reloads with an error message.

How It Works (API)

1. A client (SPA, mobile app, etc.) hits a protected API route.
2. AccessLockApiMiddleware checks for a valid token in the Authorization: Bearer or X-Access-Lock-Token header.
3. If no valid token is found, the request is rejected with a 401 or 403 response.
4. The client obtains a token by POSTing the password to the /api/access-lock/unlock endpoint.
5. On success, the server returns the plain-text password as a token (for convenience in decoupled setups).
6. The client stores the token and includes it on every subsequent request.
7. AccessLockApiMiddleware calls access_lock_verify(token) on each request — if it matches the configured hash, the request passes through; otherwise it returns 403.

Publishing Assets

Publish Config

This copies config/access-lock.php to your application's config/ directory so you can customise it.

Publish Views

This copies the unlock Blade view to resources/views/vendor/access-lock/ for customisation.

Publish Everything

Configuration

After publishing, edit config/access-lock.php:

Bypass Conditions

You can configure query string parameters or request headers that automatically and permanently unlock the session for a visitor — no password prompt is shown.

This is useful for automated tools, CI checks, SSO redirects, or any trusted caller that should never see the lock screen.

Setup

Publish the config and list the query keys / header names you want to act as bypass signals:

Helper Functions

The package provides three global helpers:

Setting Password Programmatically

Middleware Reference

License

MIT — see LICENSE.