Download the PHP package devinci-it/shadow-auth without Composer

Devinci Shadow Auth

A lightweight, file-based PHP authentication library with optional TOTP 2FA, CSRF protection, and simple processor/form helpers for classic server-rendered apps.

Table of Contents

• Requirements
• Installation
• Quick Start
• Architecture
• Configuration
• Auth Flows
• Facade API
• Publishing Demo, Endpoints, and Wiki
• Serve Demo Locally
• Class Wiki
• Security Notes
• Release and Tagging
• License

Requirements

• PHP >=8.1
• Composer (for package install and autoload)

Installation

Install through Composer:

If you are developing this package locally in another app, use a Composer path repository:

Then update dependencies:

Quick Start

1. Bootstrap

2. Register

3. Login

4. Route Guard

Architecture

Namespace root: DevinciIT\ShadowAuth\

Main components:

• Core: business logic managers and config.
• Facade: static API for app code.
• Providers: persistence layer (FileUserProvider).
• Processors: request handlers for login/register/reset/TOTP forms.
• Services: reusable services (TwoFactorService).
• Utils: utility helpers (CSRF).
• View: form builders with CSRF injection.
• Publisher: file publishing utilities for demo/endpoints/wiki.
• Shadow\Facade\Auth: compatibility alias facade.

Configuration

Configure with DevinciIT\ShadowAuth\Core\Config::set([...]).

Supported keys:

• storage_path (string, required): path to PHP array storage file.
• session_key (string, optional): auth session key. Default: shadow_auth_user.
• totp_enabled (bool, optional): global TOTP toggle. Default: true.
• registration_constraints (array, optional): unique/case-insensitive field rules.

Example:

Auth Flows

Username/password only

1. Auth::beginLogin($username, $password)
2. Returns authenticated and session is established.

Username/password + TOTP

1. Auth::beginLogin(...)
2. Returns totp_required and writes pending state in session.
3. Auth::verifyPendingTotp($code) finalizes login.

Password reset

1. Auth::requestPasswordResetToken($identifier) returns token (demo mode usage).
2. Validate before submit with Auth::hasValidPasswordResetToken($token).
3. Complete with Auth::resetPasswordWithToken($token, $newPassword).

Facade API

Available methods in DevinciIT\ShadowAuth\Facade\Auth:

• boot(): void
• register(string $username, string $password): bool
• registerWithData(string $username, string $password, array $attributes): bool
• registrationError(): ?string
• attempt(string $username, string $password, ?string $totp = null): bool
• beginLogin(string $username, string $password): string
• verifyPendingTotp(string $code): bool
• isTotpPending(): bool
• pendingUsername(): ?string
• check(): bool
• requireAuth(string $redirectTo = '/views/login.php'): void
• user(): ?array
• logout(): void
• setupTotpSecret(string $username): ?string
• confirmTotp(string $username, string $code): bool
• disableTotp(string $username): bool
• enableTotp(): void
• disableTotpGlobally(): void
• requestPasswordResetToken(string $identifier): ?string
• hasValidPasswordResetToken(string $token): bool
• resetPasswordWithToken(string $token, string $newPassword): bool

Publishing Demo, Endpoints, and Wiki

This package includes bin/shadow-auth-publish-demo with multiple modes.

Composer script aliases:

Serve Demo Locally

Use the dedicated helper to create an isolated demo in /tmp, generate a proper composer.json, install dependencies, and run PHP's local server.

Default behavior:

• Creates target directory under /tmp/shadow-auth-demo-*
• Copies bootstrap.php, src/, public/, and views/
• Writes composer.json from the demo template with local PSR-4 autoload
• Runs composer install (no devinci-it/shadow-auth self-dependency required)
• Serves http://127.0.0.1:8500 with php -S 127.0.0.1:8500 -t public

Useful flags:

Composer alias:

Class Wiki

Detailed per-class documentation is under docs/wiki/.

• Wiki index: docs/wiki/README.md
• Class pages: docs/wiki/classes/

Security Notes

• Keep storage files outside the public web root where possible.
• Apply restrictive permissions (0700 for directory, 0600 for file).
• Always use HTTPS in production.
• Regenerate session IDs after successful authentication.
• Validate CSRF tokens on all state-changing requests.
• Treat demo password reset tokens as sensitive and short-lived.

Release and Tagging

Create an annotated tag with helper script:

Composer aliases:

License

MIT