feat(installer): Licora v5.1.0 Smart Installer & First-Run Wizard

.gitignore

@@ -3,7 +3,10 @@
 .env.*
 !.env.example
 includes/config.local.php
+includes/config.local.php.installing.*
 includes/.licora-encryption.key
+includes/.licora-installed
+includes/.licora-installed.installing.*
 config.local.php
 
 # Logs, exports, backups, and generated operational data

CHANGELOG.md

@@ -6,7 +6,36 @@ All notable public-release changes are recorded here. Historical project notes r
 
 ### Planned
 
-- Resolve the security and correctness items listed in the forensic audit through separate reviewed pull requests.
+- Continue reviewed Zero Freedom development after the v5.1.0 installer release.
+
+## [5.1.0] - 2026-07-23
+
+### Added
+
+- Added a ten-step first-run installer wizard with server compatibility checks, database validation, administrator setup, application configuration, optional demo data, installation locking, success reporting, and admin-login redirect.
+- Added `/install` as an additive installer alias while preserving `/install.php`.
+- Added pre-boot installation detection for incomplete fresh installations.
+- Added an atomic private configuration and installation-flag workflow.
+- Added an installer SQL parser that executes the existing schema, migrations, indexes, constraints, and triggers without manual import.
+- Added optional DEMO records using existing `api_keys`, `licenses`, and `settings` tables only.
+- Added a CLI demo-data cleanup utility.
+- Added installer architecture, first-run, upgrade, demo-data, release, and implementation documentation.
+- Added installer smoke tests and expanded compatibility regression coverage.
+
+### Changed
+
+- Updated the default application version to `5.1.0`.
+- Added optional database-port, application-key, timezone, locale, and mail-from configuration constants.
+- Updated database connection construction to honor `DB_PORT` while retaining port `3306` as the default.
+- Updated the root landing page to trigger the installation guard before normal output.
+
+### Compatibility
+
+- No database table, column, index, foreign key, trigger, or migration was changed.
+- No license generation, license validation, API response, route, admin page, cron entry point, CSS, or JavaScript behavior was changed.
+- Existing v5.0.1 and v5.0.1.1 installations continue normal boot without reinstalling.
+- Temporary database outages never reopen the installer for configured deployments.
+- Table prefixes remain unsupported because the frozen schema and runtime query contract use fixed table names.
 
 ## [5.0.1.1] - 2026-07-23
 
@@ -79,5 +108,4 @@ All notable public-release changes are recorded here. Historical project notes r
 
 ### Compatibility
 
-- Application feature code was not removed, disabled, or simplified.
-- No PHP class, function, endpoint, admin page, migration, stylesheet, or JavaScript behavior was intentionally changed during repository preparation.
+- Existing runtime routes, API contracts, schema objects, license format, and application behavior were preserved.

PHASE2_INSTALLER_SUMMARY.md

@@ -0,0 +1,127 @@
+# Licora Phase 2 Installer Implementation Summary
+
+## Release identity
+
+- Target version: `v5.1.0`
+- Stable base: `v5.0.1.1`
+- Base commit: `7fafd2c34b3425df6ef310b9f25ffa426588d294`
+- Development mode: Zero Freedom Development
+
+## Implementation summary
+
+Licora v5.1.0 adds a production first-run installer and installation guard without modifying the existing license engine, validation logic, API contracts, database schema, admin panel, cron entry points, CSS, or JavaScript.
+
+The implementation includes:
+
+- Ten-step first-run wizard
+- Server compatibility checks
+- Database host/port/name/user/password validation
+- Blank-only table-prefix compatibility enforcement
+- Strong administrator creation with no retained default credentials
+- Application, encryption, CSRF, and JWT secret generation
+- Existing schema and migration execution with trigger delimiter support
+- Optional existing-schema DEMO records
+- Atomic private configuration activation
+- Non-secret installation flag
+- Installer lock and recovery guidance
+- Admin-login redirect without auto-login
+- Legacy installation flag backfill
+- Database-outage-safe detection
+- Installer smoke and compatibility regression tests
+
+## Files created
+
+- `includes/installation.php`
+- `install/index.php`
+- `scripts/remove-demo-data.php`
+- `tests/installer_smoke.php`
+- `docs/INSTALLER_ARCHITECTURE.md`
+- `docs/FIRST_RUN_GUIDE.md`
+- `docs/UPGRADE_GUIDE.md`
+- `docs/DEMO_DATA.md`
+- `PHASE2_INSTALLER_SUMMARY.md`
+- `RELEASE_NOTES_v5.1.0.md`
+
+## Files modified
+
+- `.gitignore`
+- `CHANGELOG.md`
+- `config.sample.php`
+- `index.php`
+- `install.php`
+- `includes/config.php`
+- `includes/database.php`
+- `docs/INSTALLATION.md`
+- `scripts/validate.sh`
+- `tests/compatibility_regression.php`
+
+## Files intentionally unchanged
+
+- `database.sql`
+- All migration SQL files
+- `includes/functions.php`
+- `includes/security.php`
+- `includes/auth.php`
+- `api/verify.php`
+- `api/check_license.php`
+- All admin routes and pages
+- All cron entry points
+- All CSS and JavaScript
+
+## Database objects created
+
+None.
+
+No new table, column, index, foreign key, trigger, or migration is introduced.
+
+## Demo data summary
+
+Optional demo installation creates:
+
+- One API credential row marked `[DEMO]`
+- One `DEMO PRODUCT` representation through `api_keys.app_name`
+- One existing-format license
+- One `[DEMO CUSTOMER]` notes marker
+- Existing `settings` markers for safe cleanup
+
+The raw generated API credential is never displayed or logged.
+
+## Security verification
+
+- CSRF protection on every installer POST
+- Strong password rules
+- Prepared statements for runtime inserts and cleanup
+- Validated database identifiers and whitelisted charset/collation
+- No shell command execution
+- Escaped HTML output
+- Generic production error messages
+- No credentials or secrets in logs
+- No secrets in the installation flag
+- Atomic temporary configuration and lock files
+- Installer lock after completion
+- Existing configured database outage does not reopen installer
+
+## Upgrade compatibility
+
+- v5.0.1 and v5.0.1.1 private configuration remains supported.
+- Missing `DB_PORT` defaults to 3306.
+- Missing v5.1.0 installation flag is backfilled only after successful legacy validation.
+- Existing encrypted values and API clients are unaffected.
+- Existing installations are never forced through the wizard.
+
+## Regression coverage
+
+Automated coverage includes:
+
+- PHP syntax
+- Phase 1 security smoke tests
+- Existing compatibility regression checks
+- Installer helper validation
+- Strong password rejection
+- Table-prefix rejection
+- SQL delimiter parsing
+- Versioned installer encryption
+- Existing license-format generation
+- Non-secret installation flag
+- Preserved schema/migration/frontend hashes
+- Preserved API and route markers

RELEASE_NOTES_v5.1.0.md

@@ -0,0 +1,173 @@
+# Licora v5.1.0 — Smart Installer & First-Run Wizard
+
+**Release type:** Backward-compatible installer feature release
+**Stable base:** `v5.0.1.1`
+**Database migration:** None
+
+## Summary
+
+Licora v5.1.0 introduces a professional first-run installation experience for the open-source, self-hosted PHP and MySQL/MariaDB license management system.
+
+The release improves fresh installation only. Existing deployments continue normal operation and are not required to reinstall.
+
+## Smart first-run installer
+
+The installer now provides ten guided steps:
+
+1. Welcome and server compatibility checks
+2. Database configuration and connection validation
+3. Administrator setup
+4. Application configuration and secure secret generation
+5. Existing schema initialization review
+6. Optional DEMO data
+7. Installation-lock confirmation
+8. Atomic finalization
+9. Installation success summary
+10. Redirect to admin login without auto-login
+
+Both installer routes are available:
+
+- `/install.php` remains fully supported
+- `/install` is an additive alias
+
+## Installation detection
+
+Before normal web application boot, Licora distinguishes between:
+
+- Fresh unconfigured deployments
+- Incomplete fresh installations
+- Valid existing installations
+- Valid legacy installations without an installation flag
+- Configured installations experiencing a temporary database outage
+
+A database outage never reopens the installer for an existing configured deployment.
+
+## Atomic installation
+
+The installer validates all input before finalization and uses temporary private files before activation.
+
+It executes the existing repository `database.sql`, including current migrations, indexes, constraints, and triggers. A delimiter-aware parser removes the need for manual SQL import.
+
+If installation fails before activation, Licora attempts to remove only installer-created objects. Unrelated pre-existing database objects are not removed.
+
+## Administrator security
+
+Fresh wizard installations require:
+
+- Administrator name
+- Valid email address
+- Unique-format username
+- Password of at least 12 characters
+- Uppercase, lowercase, number, and symbol
+
+The temporary development account from the sanitized manual-import schema is replaced before wizard completion. Licora never auto-logs in the new administrator.
+
+## Application configuration
+
+The wizard generates and stores private values for:
+
+- Application key
+- Encryption key
+- CSRF secret
+- JWT secret
+
+It also configures:
+
+- Application name
+- Base URL
+- Timezone
+- Locale
+- Mail From Name
+- Database port
+
+Generated secrets and credentials are never displayed or logged.
+
+## Installation lock
+
+After successful installation Licora creates:
+
+- `includes/config.local.php`
+- `includes/.licora-installed`
+
+The installation flag contains only product, version, and installation timestamp. Installer files remain on disk but execution is disabled.
+
+## Optional DEMO data
+
+When selected, the installer creates clearly marked DEMO data using existing tables only:
+
+- DEMO API credential
+- DEMO PRODUCT representation
+- DEMO license
+- DEMO CUSTOMER marker
+- Demo cleanup settings
+
+No product, customer, role, or permission table is added.
+
+Demo records can be removed with:
+
+```bash
+php scripts/remove-demo-data.php
+```
+
+## Compatibility guarantees
+
+This release does not change:
+
+- Database tables or columns
+- Indexes, foreign keys, triggers, or migrations
+- License-key format
+- License generation
+- License validation
+- Device registration
+- API URLs
+- API request or response JSON
+- Legacy API behavior
+- Admin routes or page design
+- Cron entry points
+- CSS or JavaScript
+- Existing encrypted data
+
+Table prefixes remain unsupported because fixed table names are part of the frozen schema and runtime-query contract. The installer field must remain blank.
+
+## Upgrade instructions
+
+Existing v5.0.1 and v5.0.1.1 installations:
+
+1. Back up the database.
+2. Back up private configuration and encryption-key material.
+3. Replace application source with v5.1.0.
+4. Preserve `includes/config.local.php` and private key files.
+5. Do not run the first-run installer.
+6. Run `bash scripts/validate.sh`.
+7. Verify admin, API, license, device, dashboard, cron, settings, and encrypted-data compatibility.
+
+No v5.1.0 database migration is required.
+
+## Validation
+
+The repository validation suite covers:
+
+- PHP syntax
+- Security smoke tests
+- Compatibility regression tests
+- Installer smoke tests
+- SQL delimiter parsing
+- Strong password validation
+- Table-prefix rejection
+- Installation-flag redaction
+- Versioned demo encryption
+- Existing license format
+- Immutable database and migration hashes
+- Preserved API and route contracts
+- JavaScript syntax
+- Public-release marker scanning
+- SQL seed-scope validation
+
+## Documentation
+
+- `docs/INSTALLATION.md`
+- `docs/INSTALLER_ARCHITECTURE.md`
+- `docs/FIRST_RUN_GUIDE.md`
+- `docs/UPGRADE_GUIDE.md`
+- `docs/DEMO_DATA.md`
+- `PHASE2_INSTALLER_SUMMARY.md`

config.sample.php

@@ -1,8 +1,16 @@
 <?php
 if (!defined('DB_HOST')) define('DB_HOST', 'localhost');
+if (!defined('DB_PORT')) define('DB_PORT', 3306);
 if (!defined('DB_NAME')) define('DB_NAME', 'license_system');
 if (!defined('DB_USER')) define('DB_USER', 'root');
 if (!defined('DB_PASS')) define('DB_PASS', '');
+if (!defined('APP_NAME')) define('APP_NAME', 'Licora');
+if (!defined('APP_URL')) define('APP_URL', 'http://localhost/licora');
+if (!defined('APP_VERSION')) define('APP_VERSION', '5.1.0');
+if (!defined('APP_TIMEZONE')) define('APP_TIMEZONE', 'Asia/Dhaka');
+if (!defined('APP_LOCALE')) define('APP_LOCALE', 'en');
+if (!defined('MAIL_FROM_NAME')) define('MAIL_FROM_NAME', 'Licora');
+if (!defined('APP_KEY')) define('APP_KEY', 'replace-me-with-a-random-64-character-secret');
 if (!defined('ENCRYPTION_KEY')) define('ENCRYPTION_KEY', 'your-32-byte-encryption-key-here-change-this');
 if (!defined('CSRF_SECRET')) define('CSRF_SECRET', 'your-csrf-secret-key-change-this');
 if (!defined('JWT_SECRET')) define('JWT_SECRET', 'your-jwt-secret-key-change-this');