padosoft/laravel-pii-redactor-admin

Installable Laravel admin console for padosoft/laravel-pii-redactor.

Maintainers

Package info

github.com/padosoft/laravel-pii-redactor-admin

pkg:composer/padosoft/laravel-pii-redactor-admin

Statistics

Installs: 0

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

v1.0.2 2026-05-06 18:22 UTC

Requires

Requires (Dev)

Apache-2.0 8e37c413ceba836ceb7893c946ee95b75e687d31

adminlaravelgdprpiiredaction

This package is auto-updated.

Last update: 2026-05-06 21:38:51 UTC

README

A secure, batteries-included admin console for padosoft/laravel-pii-redactor — built with Laravel 13, React 19, Vite and Tailwind v4.

CI Latest Version Total Downloads License PHP Laravel Node React Tailwind

Dashboard preview

Table Of Contents

Why this package?

GDPR-grade PII redaction is only half the story — operators still need a safe way to:

  • inspect what was redacted,
  • detokenise on demand with a paper trail,
  • tune detectors and custom rules,
  • and share design-time examples with the team.

laravel-pii-redactor-admin ships that admin surface as a drop-in Laravel package: zero config in your host app, disabled by default, and locked down behind explicit Gates. No raw PII ever leaves the database.

Features
Dashboard KPI cards (events, tokens, detokenises, errors) with light & dark themes
Playground Paste text, run a redaction, inspect tokens — without persisting raw input
Token map Browse stored tokens (originals never selected nor serialized)
Detokenise Justification-gated, throttled, audited reverse lookup
Audit logs Read-only timeline of every redact/detokenise event
Detectors View built-in detectors and their patterns
Custom rules Manage host-defined rules from the UI
Disabled by default One env flag turns the whole console on or off
Pre-built assets React/Tailwind compiled in-package; no host Vite config required

Screenshots

Design references live in resources/screenshots.

Page Preview
Dashboard Dashboard
Dashboard (dark) Dark dashboard
Playground Playground
Token map Token map
Audit logs Audit logs
Detokenise Detokenise
Detectors Detectors
Custom rules Custom rules

Requirements

Tool Version
PHP ^8.3
Laravel ^13.0
Composer ^2.7
Node.js >=24 (only needed if you want to rebuild assets)
Database Anything Laravel supports (MySQL, PostgreSQL, SQLite…)

The compiled JS/CSS is shipped inside the package, so a host app does not need Node to run the console — only to develop it.

Quick Start (5 minutes, junior-dev friendly)

Follow these steps top-to-bottom on a Laravel 13 app where padosoft/laravel-pii-redactor is already installed and migrated.

1. Install the package

composer require padosoft/laravel-pii-redactor-admin

Both packages are not on Packagist yet? Jump to Installation Variants and come back here.

2. Publish config & migrations

php artisan vendor:publish --tag=pii-redactor-admin-config
php artisan vendor:publish --tag=pii-redactor-admin-migrations
php artisan migrate

What this does:

  • copies config/pii-redactor-admin.php into your app so you can tweak it,
  • adds the audit table migration that records every detokenise event,
  • runs the migration so the table exists.

3. Enable the admin in .env

The console is disabled by default. Turn it on only in environments where you trust the audience (typically staging / a protected admin host):

PII_REDACTOR_ADMIN_ENABLED=true
PII_REDACTOR_ADMIN_ROUTE_PREFIX=pii-redactor-admin
PII_REDACTOR_ADMIN_API_PREFIX=pii-redactor-admin/api

4. Wire the authorization gates

Add the three Gates somewhere they get registered (e.g. app/Providers/AuthServiceProvider.php boot()):

use Illuminate\Support\Facades\Gate;

Gate::define('viewPiiRedactorAdmin', fn ($user) => $user->can('manage-pii-redactor'));
Gate::define('detokenisePiiRedactor', fn ($user) => $user->can('detokenise-pii'));
Gate::define('viewPiiRedactorRawSamples', fn ($user) => $user->can('view-raw-pii-samples'));

Tweak the inner ->can(...) to match your existing permission system (Spatie, custom roles, hardcoded $user->is_admin, etc.). The package only asks these Gates — it never defines who passes them.

5. Open the console

Visit:

https://your-app.test/pii-redactor-admin

Logged in as a user that satisfies viewPiiRedactorAdmin, you should land on the dashboard. If you get a 403, your Gate returned false. If you get a 404, double-check PII_REDACTOR_ADMIN_ENABLED=true and that the config is cached (php artisan config:clear).

Installation Variants

Both packages on Packagist

composer require padosoft/laravel-pii-redactor-admin

Only this package on Packagist

Add the core package repository in the host app first:

composer config repositories.pii-redactor vcs https://github.com/padosoft/laravel-pii-redactor
composer require padosoft/laravel-pii-redactor-admin

Neither package on Packagist

Add both repositories before requiring the admin package:

composer config repositories.pii-redactor vcs https://github.com/padosoft/laravel-pii-redactor
composer config repositories.pii-redactor-admin vcs https://github.com/padosoft/laravel-pii-redactor-admin
composer require padosoft/laravel-pii-redactor-admin

Local development from a checkout

composer config repositories.pii-redactor vcs https://github.com/padosoft/laravel-pii-redactor
composer config repositories.pii-redactor-admin path /absolute/path/to/laravel-pii-redactor-admin
composer require padosoft/laravel-pii-redactor-admin:@dev
php artisan vendor:publish --tag=pii-redactor-admin-config
php artisan vendor:publish --tag=pii-redactor-admin-migrations
php artisan migrate

Composer ignores repositories declared inside a dependency, so you must declare the core package repository in the host app if it isn't on Packagist.

Configuration

config/pii-redactor-admin.php exposes:

Key Env Default Purpose
enabled PII_REDACTOR_ADMIN_ENABLED false Master switch — when false, no routes are registered.
route_prefix PII_REDACTOR_ADMIN_ROUTE_PREFIX pii-redactor-admin UI mount path.
api_prefix PII_REDACTOR_ADMIN_API_PREFIX pii-redactor-admin/api JSON API mount path used by the React app.
middleware — ['web', 'auth'] Adjust to your auth stack (Sanctum, custom guards, etc.).

Always keep web,auth (or stricter) on both the UI and the API prefix.

Authorization

Ability Required for
viewPiiRedactorAdmin Loading any admin page
detokenisePiiRedactor Submitting the detokenise form
viewPiiRedactorRawSamples Showing raw scan samples in detector output

Detokenise additionally requires:

  • a token-shaped input (validated server-side),
  • a justification of at least 10 characters,
  • UI confirmation,
  • per-user/per-route throttling,
  • an audit row written before the result is returned.

Security Model

  • Token-map listing never selects or serializes token originals.
  • Detokenise requires authorization, justification, token validation, throttling, and an audit row.
  • Raw scan samples require a dedicated ability.
  • Audit rows store metadata, counts, target hashes, status, and justification only — no raw text, redacted output, detokenised output, salts, API keys, or token originals.

Demo Fixtures

Safe demo payloads live in resources/demo/admin-api-fixtures.json and are reused by Playwright. They intentionally omit token originals, raw samples, redacted output, salts, and API keys.

Verification

Frontend development and CI use Node.js 24 or newer.

Every task must keep these gates green locally and in GitHub Actions:

composer validate --strict
vendor/bin/phpunit
npm run typecheck
npm run test
npm run build
npm run e2e

Fresh host install verification can be run from the package root (PowerShell):

./scripts/verify-fresh-laravel-host.ps1

Release readiness notes live in docs/RELEASE.md.

Troubleshooting

404 on /pii-redactor-admin
  • Confirm PII_REDACTOR_ADMIN_ENABLED=true is loaded (php artisan config:clear, then php artisan tinker → config('pii-redactor-admin.enabled')).
  • Confirm the service provider is auto-discovered (it's listed in composer.json extra.laravel.providers). If you have dont-discover in your host composer.json, add it manually.
  • Run php artisan route:list | grep pii-redactor-admin.
403 once logged in
  • The viewPiiRedactorAdmin Gate returned false. Check the closure you wrote in step 4 of the Quick Start.
  • Verify the Gate is actually registered: Gate::abilities() should include the three keys.
Blank page / missing styles
  • Make sure resources/dist is present in the package (it's committed). If you cloned without npm run build, run it once.
  • Confirm your host app isn't overriding the asset routes. The package serves its own JS/CSS via the admin route prefix.
Migration error: table already exists
  • You probably ran the publish command twice. Remove the duplicate file from database/migrations and re-run php artisan migrate.
Detokenise returns 422
  • Justification must be ≥ 10 characters.
  • Token must match the format produced by the core redactor.
  • Check the latest row in the audit table — it records the validation failure reason.

Contributing

Pull requests are welcome! Before opening one:

  1. Read AGENTS.md, docs/LESSON.md, and docs/PROGRESS.md.
  2. Keep PRs small and focused.
  3. Run all gates from the Verification section.
  4. Every PR goes through the Copilot review loop.

Bug reports and feature ideas: open an issue.

Release

Current runtime release: v1.0.1.

v1.0.2 is reserved for the final docs/test-hardening ledger after v1.0.1. See docs/RELEASE.md for the full release procedure.

License

Released under the Apache-2.0 License. © Padosoft.

Credits