Bootstrap5 upgrade part1

.github/workflows/docker.yml

@@ -25,7 +25,45 @@ on:
     types: [ published ]
 
 jobs:
+  quality-gates:
+    runs-on: ubuntu-22.04
+    steps:
+    - name: Check out repository
+      uses: actions/checkout@v6
+
+    - name: Setup PHP
+      uses: shivammathur/setup-php@v2
+      with:
+        php-version: '8.2'
+        extensions: ldap, mbstring, mysqli, pcntl, ssh2
+        coverage: none
+
+    - name: Install dependencies
+      run: composer install --no-interaction --prefer-dist
+
+    - name: Composer validate
+      run: composer validate --strict
+
+    - name: Composer audit
+      run: composer audit
+
+    - name: Composer platform requirements
+      run: composer check-platform-reqs
+
+    - name: Docker compose config validation
+      run: docker compose config -q
+
+    - name: PHP lint
+      run: composer run lint
+
+    - name: PHP static analysis
+      run: composer run stan
+
+    - name: Smoke harness dry-run
+      run: composer run smoke:dry-run
+
   build-matrix:
+    needs: quality-gates
     if: github.event_name != 'pull_request'
     outputs:
       safe_ref: ${{ steps.ref.outputs.safe_ref }}

.gitignore

@@ -6,3 +6,6 @@ extensions/*.php
 docker-compose*
 docker/
 /vendor/
+var/
+scripts/smoke/fixtures/sync/*.txt
+testenvs.env

.php-cs-fixer.dist.php

@@ -0,0 +1,17 @@
+<?php
+
+$finder = PhpCsFixer\Finder::create()
+    ->in([
+        __DIR__ . '/model',
+        __DIR__ . '/scripts',
+        __DIR__ . '/services',
+    ])
+    ->name('*.php');
+
+return (new PhpCsFixer\Config())
+    ->setRiskyAllowed(false)
+    ->setRules([
+        '@PSR12' => true,
+        'line_ending' => true,
+    ])
+    ->setFinder($finder);

AGENTS.md

@@ -2,6 +2,14 @@
 
 This document gives AI agents enough context to work safely in this repo.
 
+## Current status (Phase 10 complete)
+- Modernization phases 0-10 are implemented on the Bootstrap 5 modernization branch (`bootstrap5-upgrade*` lineage).
+- Runtime state container is in use (`services/runtime_state.php`) with compatibility fallback paths still present.
+- Request/auth/CSRF/security-header flow is service-based in `requesthandler.php`.
+- Bootstrap, jQuery, and the Bootstrap 5 compatibility runtime are no longer loaded in the browser.
+- Frontend shell/layout behavior is now repo-local in `public_html/style.css` and `public_html/extra.js`.
+- Smoke harness and quality gates are available and expected in agent workflow.
+
 ## What this project is
 - SKA is a PHP web app that centralizes SSH public key management.
 - It integrates with LDAP/AD for users and groups.
@@ -15,29 +23,42 @@ This document gives AI agents enough context to work safely in this repo.
 - Views/controllers: `views/`
 - Templates: `templates/`
 - Models: `model/`
-- Services: `services/` (auth, init scripts)
+- Services: `services/`
 - CLI scripts: `scripts/` (sync + cron jobs)
+- Documentation: `docs/`
 
 ## Configuration and secrets
 - Main config template: `config/config.ini.example`
 - Real config: `config/config.ini` (not in repo)
 - Sync SSH keys expected at:
   - `config/keys-sync` (private key)
   - `config/keys-sync.pub` (public key)
-- Do not commit any real secrets or keys.
+- Never commit real secrets, keys, or production credentials.
+
+## Critical compatibility contract
+Do not break these unless explicitly approved and documented:
+- LDAP login/auth flow.
+- Public key add/remove lifecycle.
+- Access rule add/remove lifecycle.
+- Sync behavior and output compatibility.
+- Audit/event logging semantics.
+- Sync key paths:
+  - `config/keys-sync`
+  - `config/keys-sync.pub`
+
+Reference: `docs/compatibility-contract.md`
 
 ## Core workflows (high level)
-- Login: LDAP auth via `services/auth.php` and `ldap.php`, session in `requesthandler.php`.
-- Key upload: stored in `model/publickey.php` and related directories.
-- Access rules: `model/access.php` and related access option classes.
-- Key distribution: `scripts/sync.php` over SSH to write files under `/var/local/keys-sync/`.
-- Periodic tasks:
-  - `scripts/ldap_update.php` (LDAP sync)
-  - `scripts/supervise_external_keys.php` (detect external keys)
-  - `scripts/syncd.php` (daemon for key sync)
+- Login/auth: `services/auth.php`, `services/login_flow.php`, `ldap.php`
+- Request policy/auth/csrf: `services/request_policy_guard.php`, `services/request_auth_guard.php`, `services/request_csrf_guard.php`
+- Key lifecycle: `services/key_lifecycle_service.php`, `model/publickey.php`
+- Access lifecycle: `services/access_rule_service.php`, `model/access.php`, `model/accessoption.php`
+- Sync distribution: `scripts/sync.php`, `scripts/sync-common.php`, `scripts/syncd.php`
+- External key supervision: `scripts/supervise_external_keys.php`
+- LDAP sync: `scripts/ldap_update.php`
 
 ## Data model (key tables)
-See `migrations/00x.php` for schema.
+See migrations (`migrations/00x.php`) for schema details.
 - Users: `user`, `entity`
 - Groups: `group`, `group_member`
 - Servers: `server`, `server_account`
@@ -46,29 +67,54 @@ See `migrations/00x.php` for schema.
 - Events/audit: `entity_event`, `server_event`
 - Sync: `sync_request`, `external_key`
 
-## Development and runtime notes
-- PHP 8.2+, MySQL/MariaDB, LDAP.
-- Docker is the preferred deployment method (`Dockerfile`, `docker-compose.yml`).
-- Cron and supervisor configs live under `etc/`.
-- Web assets in `public_html/` (Bootstrap + jQuery).
+## Validation workflow for agents
+Run these before handoff:
+
+```bash
+source testenvs.env
+make ci-check
+make smoke-dry-run
+make smoke
+```
+
+Security note:
+- Do not use `COMPOSER_ALLOW_SUPERUSER=1` for local/dev workflows.
+- If a CI runner must execute Composer as root, follow the guidance in [docs/operations-runbook.md](/var/www/ska/docs/operations-runbook.md) and keep that exception scoped to the CI environment.
+
+If `testenvs.env` is not present in the environment, coordinate with the user for smoke variables.
+
+## Smoke workflow expectations
+Smoke harness validates:
+- login page + LDAP auth
+- key add/remove for authenticated user
+- access rule add/remove for target account
+- sync preview output against fixture
+
+References:
+- `docs/smoke-tests.md`
+- `docs/operations-runbook.md`
 
 ## Where to look for changes
-- UI changes: `templates/` and `views/`
-- Access logic: `model/access.php` and `model/accessoption.php`
-- LDAP behavior: `ldap.php` and `services/auth.php`
-- Sync behavior: `scripts/sync.php` and `scripts/sync-common.php`
+- UI and UX: `templates/`, `views/`, compatibility assets in `public_html/`
+- Access logic: `model/access.php`, `model/accessoption.php`, `services/access_rule_service.php`
+- LDAP behavior: `ldap.php`, `services/auth.php`
+- Sync behavior: `scripts/sync.php`, `scripts/sync-common.php`, `scripts/syncd.php`
+- Request/auth/security headers: `requesthandler.php`, `services/request_*`, `services/response_security_headers.php`
 
 ## Safety checks for edits
-- Validate any change that touches SSH key generation or distribution.
-- Do not change key file paths without updating docs and server config.
-- Avoid modifying LDAP queries without checking group/user assumptions.
-- Keep audit/event logging intact when altering access flows.
-
-## Testing guidance
-- No automated tests in repo.
-- For changes, prefer targeted manual verification:
-  - Login and LDAP auth flow
-  - Add/Remove public keys
-  - Create/Remove access rules
-  - Trigger a sync (CLI) and verify output files
+- Validate any change touching SSH sync, key generation, or host verification paths.
+- Avoid changing LDAP query behavior unless assumptions and migration notes are explicit.
+- Keep audit/event logging intact when changing key/access/admin flows.
+- Keep schema-compatible migrations unless a breaking change is explicitly approved.
 
+## Modernization docs map
+- Plan: `docs/modernization-plan.md`
+- Risks: `docs/modernization-risks.md`
+- Roadmap: `docs/modernization-roadmap.md`
+- Checkpoints:
+  - `docs/phase-5-checkpoint.md`
+  - `docs/phase-6-checkpoint.md`
+  - `docs/phase-7-checkpoint.md`
+  - `docs/phase-8-checkpoint.md`
+  - `docs/phase-9-checkpoint.md`
+  - `docs/phase-10-checkpoint.md`

Makefile

@@ -0,0 +1,45 @@
+.PHONY: lint stan qa format format-check composer-validate composer-audit platform-check docker-config-check ci-check smoke smoke-dry-run smoke-web smoke-sync smoke-sync-record
+
+lint:
+	composer run lint
+
+stan:
+	composer run stan
+
+qa:
+	composer run qa
+
+format:
+	composer run format
+
+format-check:
+	composer run format:check
+
+composer-validate:
+	composer validate --strict
+
+composer-audit:
+	composer audit
+
+platform-check:
+	composer check-platform-reqs
+
+docker-config-check:
+	docker compose config -q
+
+ci-check: composer-validate composer-audit platform-check docker-config-check qa
+
+smoke:
+	bash scripts/smoke/run.sh
+
+smoke-dry-run:
+	bash scripts/smoke/run.sh --dry-run
+
+smoke-web:
+	bash scripts/smoke/run.sh --web-only
+
+smoke-sync:
+	bash scripts/smoke/run.sh --sync-only
+
+smoke-sync-record:
+	bash scripts/smoke/run.sh --sync-only --record-sync

README.md

@@ -77,7 +77,7 @@ Installation
         CREATE DATABASE `ska-db` DEFAULT CHARACTER SET utf8mb4;
         GRANT ALL ON `ska-db`.* to 'ska-user'@'localhost';
 
-5.  Copy the file `config/config-sample.ini` to `config/config.ini` and edit the settings as required.
+5.  Copy the file `config/config.ini.example` to `config/config.ini` and edit the settings as required.
 
 6.  Set up authnz_ldap for your virtual host (or any other authentication module that will pass on an Auth-user
     variable to the application).
@@ -108,6 +108,49 @@ Usage
 
 Anyone in the LDAP group defined under `admin_group_cn` in `config/config.ini` will be able to manage accounts and servers.
 
+Development checks
+------------------
+
+Install development dependencies:
+
+    composer install
+
+Run quality checks:
+
+    make ci-check
+
+Run smoke harness dry-run:
+
+    make smoke-dry-run
+
+Run smoke workflows (requires environment variables, see docs):
+
+    make smoke
+
+Run individual checks:
+
+    make lint
+    make stan
+    make composer-validate
+    make composer-audit
+    make platform-check
+    make docker-config-check
+
+Inspect sync runtime timeout diagnostics:
+
+    php scripts/sync.php --diagnostics
+
+Smoke test documentation: `docs/smoke-tests.md`
+Operations runbook: `docs/operations-runbook.md`
+Modernization checkpoints and roadmap:
+- `docs/modernization-roadmap.md`
+- `docs/phase-5-checkpoint.md`
+- `docs/phase-6-checkpoint.md`
+- `docs/phase-7-checkpoint.md`
+- `docs/phase-8-checkpoint.md`
+- `docs/phase-9-checkpoint.md`
+- `docs/phase-10-checkpoint.md`
+
 Key distribution
 ----------------
 

composer.json

@@ -11,5 +11,21 @@
         "ext-ssh2": "*",
         "phpseclib/phpseclib": "^3.0"
     },
+    "require-dev": {
+        "friendsofphp/php-cs-fixer": "^3.90",
+        "php-parallel-lint/php-parallel-lint": "^1.4",
+        "phpstan/phpstan": "^1.12"
+    },
+    "scripts": {
+        "lint": "parallel-lint --exclude vendor --exclude .git --exclude docs .",
+        "stan": "phpstan analyse --configuration=phpstan.neon.dist --memory-limit=1G",
+        "format": "php-cs-fixer fix --config=.php-cs-fixer.dist.php",
+        "format:check": "php-cs-fixer fix --config=.php-cs-fixer.dist.php --dry-run --diff",
+        "smoke:dry-run": "bash scripts/smoke/run.sh --dry-run",
+        "qa": [
+            "@lint",
+            "@stan"
+        ]
+    },
     "license": "Apache-2.0"
 }