diff --git a/docs/IMPLEMENTATION-TRACKER.md b/docs/IMPLEMENTATION-TRACKER.md index f0b4b62..463dfe4 100644 --- a/docs/IMPLEMENTATION-TRACKER.md +++ b/docs/IMPLEMENTATION-TRACKER.md @@ -7,19 +7,36 @@ | php-aegis Handover | ✅ Complete | Send to php-aegis team | | sanctify-php Roadmap | ✅ Complete | Begin Phase 1 | | Standalone Requirements | ✅ Complete | See STANDALONE.md | -| Binary Releases | 🔲 Not Started | **CRITICAL** - Create CI workflow | +| Target Audience | ✅ Complete | See TARGET-AUDIENCE.md | +| Binary Releases | 🔲 Not Started | **BLOCKER** - Tool cannot run without this | | Composer Plugin | 🔲 Not Started | **CRITICAL** - Enable `composer require` | +| Docker Container | 🔲 Not Started | **HIGH** - Fallback for binary issues | | GitHub Action | 🔲 Not Started | High priority | -| Docker Container | 🔲 Not Started | Create Dockerfile | | Incremental Analysis | 🔲 Not Started | Cache for performance | | Semantic Support | 🔲 Not Started | Design AST extensions | --- +## Critical Finding: GHC Requirement is a BLOCKER + +### Integration Evidence + +| Project | Could run sanctify-php? | Result | +|---------|------------------------|--------| +| wp-sinople-theme | ⚠️ With difficulty | Needed Haskell setup | +| Zotpress | ❌ **NO** | GHC not available, couldn't run at all | + +> **Zotpress integration failed completely** — sanctify-php could not be executed. +> Manual analysis was performed instead using documented patterns. +> This is not an inconvenience — it's a **total adoption blocker**. + +--- + ## Critical Path: Adoption Blockers -> **Key Insight**: The biggest barrier to adoption is the Haskell dependency. -> PHP developers expect `composer require` installation with no external runtime. +> **Key Insight**: The Haskell dependency is a BLOCKER, not just an inconvenience. +> In real-world integrations, the tool literally could not be used. +> PHP developers cannot and will not install GHC. ### sanctify-php Critical Items diff --git a/docs/PHP-AEGIS-HANDOVER.md b/docs/PHP-AEGIS-HANDOVER.md index edf6c9b..a3bf208 100644 --- a/docs/PHP-AEGIS-HANDOVER.md +++ b/docs/PHP-AEGIS-HANDOVER.md @@ -2,10 +2,43 @@ ## Context -This document provides integration feedback from the wp-sinople-theme WordPress theme project, which attempted to use both `sanctify-php` (static analysis) and `php-aegis` (runtime security library) together. +This document provides integration feedback from multiple WordPress projects: +1. **wp-sinople-theme** - Semantic theme with IndieWeb/Micropub support +2. **Zotpress** - Mature WordPress plugin (already well-secured) **Integration Report Date**: 2025-12-27 -**Integration Target**: WordPress semantic theme with IndieWeb/Micropub support + +--- + +## Executive Summary + +### The Core Problem + +**php-aegis duplicates WordPress core functionality** without providing additional value for WordPress projects. + +| php-aegis | WordPress Equivalent | Winner | +|-----------|---------------------|--------| +| `Validator::email()` | `is_email()` | WordPress (more edge cases) | +| `Validator::url()` | `wp_http_validate_url()` | WordPress (protocol-aware) | +| `Sanitizer::html()` | `esc_html()` | WordPress (context-aware) | +| `Sanitizer::stripTags()` | `wp_strip_all_tags()` | WordPress (more thorough) | +| Generic escaping | `esc_html()`, `esc_attr()`, `esc_url()`, `esc_js()` | **WordPress (context-specific)** | + +### Strategic Decision Required + +php-aegis must choose a positioning: + +**Option A: Non-WordPress PHP Library** +- Document that php-aegis is for Laravel, Symfony, vanilla PHP +- Don't compete with WordPress's mature security APIs +- Focus on frameworks that lack built-in security + +**Option B: WordPress Superset Library** +- Provide capabilities WordPress lacks (semantic web, IndieWeb, ActivityPub) +- Integrate with (not replace) WordPress functions +- Be additive, not duplicative + +**Recommendation: Option B** — Provide unique value WordPress lacks. --- @@ -15,18 +48,47 @@ This document provides integration feedback from the wp-sinople-theme WordPress | Issue | Severity | Impact | |-------|----------|--------| +| Duplicates WordPress core | **Critical** | No value add for WP projects | +| Lacks context-aware escaping | **Critical** | WP has html/attr/url/js contexts, Aegis has generic | | PHP 8.1+ blocks WordPress adoption | **Critical** | WordPress 6.4 supports PHP 7.4+, most hosts still on 7.4/8.0 | | No WordPress adapter | High | camelCase API vs snake_case WordPress conventions | | Feature set too minimal | Medium | WordPress has equivalent functions already | | No RDF/Turtle escaping | High | Semantic themes require W3C-compliant escaping | -| Limited validators | Medium | Only email/url - missing int(), ip(), domain() | +| Limited validators | Medium | Only email/url - missing int(), ip(), domain(), uuid(), credit_card() | | Missing SPDX license headers | Low | Compliance concern for FOSS projects | +### What Mature WordPress Projects Already Have + +The Zotpress integration revealed that well-maintained WordPress plugins already: +- ✅ Have ABSPATH protection on all files +- ✅ Use prepared statements for all database queries +- ✅ Verify nonces on AJAX handlers +- ✅ Sanitize input and escape output throughout +- ✅ Follow WordPress coding standards + +**Conclusion**: php-aegis provides no value for these projects unless it offers something WordPress doesn't. + --- ## Detailed Recommendations -### 0. CRITICAL: PHP 7.4+ Compatibility Layer +### 0. CRITICAL: Define Target Audience + +Before any implementation, php-aegis must answer: + +> **Who is this library for?** + +| Audience | Should php-aegis target? | Why | +|----------|-------------------------|-----| +| WordPress plugins/themes | Only if offering unique value | WP core already handles standard security | +| Laravel applications | Yes | Laravel has security but less comprehensive | +| Symfony applications | Yes | Similar to Laravel | +| Vanilla PHP | Yes | No built-in security | +| Semantic web apps | **Yes - unique opportunity** | No existing library handles RDF/Turtle | +| IndieWeb apps | **Yes - unique opportunity** | Micropub/Webmention security not solved | +| ActivityPub/Fediverse | **Yes - unique opportunity** | Complex content policies needed | + +### 1. CRITICAL: PHP 7.4+ Compatibility Layer **Problem**: php-aegis requires PHP 8.1+, but WordPress ecosystem reality: - WordPress 6.4+ officially supports PHP 7.4+ diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 3f580a5..10f1a22 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -2,22 +2,42 @@ ## Context -This roadmap addresses integration feedback from real-world deployment in the wp-sinople-theme WordPress project, which uses semantic web (RDF/Turtle) output and IndieWeb protocols. +This roadmap addresses integration feedback from real-world deployment: +1. **wp-sinople-theme** - Semantic theme with IndieWeb/Micropub support +2. **Zotpress** - Mature WordPress plugin (couldn't run sanctify-php at all) **Feedback Date**: 2025-12-27 **Current Version**: 0.1.0.0 --- +## Critical Finding: Tool Unusable Without Binaries + +### Zotpress Integration Failure + +> **sanctify-php could not be run at all** because GHC (Haskell compiler) was not available. +> Manual analysis was performed instead using documented patterns. + +This confirms the #1 adoption blocker: **the Haskell build requirement prevents any usage**. + +### Evidence from Integration Attempts + +| Project | Could run sanctify-php? | Outcome | +|---------|------------------------|---------| +| wp-sinople-theme | ⚠️ With difficulty | Required Haskell setup | +| Zotpress | ❌ **No** | GHC not available, manual analysis only | + +--- + ## Issues Identified | Issue | Severity | User Impact | |-------|----------|-------------| -| Requires Haskell toolchain | **Critical** | Most PHP devs can't build/run sanctify-php | +| Requires Haskell toolchain | **BLOCKER** | Tool literally cannot run | | No `composer require` install | **Critical** | PHP devs expect Composer installation | +| No pre-built binaries | **Critical** | No workaround for GHC requirement | +| No Docker container | High | Alternative deployment path missing | | No GitHub Action | High | No easy CI/CD integration | -| No pre-built binaries | High | Installation friction prevents adoption | -| No Docker container | Medium | Alternative deployment path missing | | No incremental analysis | Medium | Full rescan on every change is slow | | No RDF/Turtle awareness | High | Semantic themes get false negatives | | Limited PHP 8.x syntax | Medium | May miss some modern PHP patterns | @@ -25,9 +45,10 @@ This roadmap addresses integration feedback from real-world deployment in the wp ### Key Insight -> **The biggest barrier to sanctify-php adoption is the Haskell dependency.** -> PHP developers expect `composer require` installation with no external runtime. -> The solution is a Composer plugin that downloads pre-built binaries. +> **The Haskell dependency is a BLOCKER, not just an inconvenience.** +> In the Zotpress integration, the tool could not be used at all. +> PHP developers cannot and will not install GHC. +> **Pre-built binaries are not optional — they are required for any adoption.** --- diff --git a/docs/TARGET-AUDIENCE.md b/docs/TARGET-AUDIENCE.md new file mode 100644 index 0000000..dc1e7ff --- /dev/null +++ b/docs/TARGET-AUDIENCE.md @@ -0,0 +1,231 @@ +# Target Audience & Use Cases + +This document clarifies when to use sanctify-php and php-aegis based on real-world integration feedback. + +--- + +## Quick Decision Matrix + +### Should I use sanctify-php? + +| Your Situation | Use sanctify-php? | Why | +|----------------|------------------|-----| +| New PHP project | ✅ Yes | Catch issues early | +| Legacy codebase audit | ✅ Yes | Find security debt | +| WordPress plugin/theme | ⚠️ Maybe | WP already has security APIs | +| CI/CD security gate | ✅ Yes (when binaries exist) | Automated scanning | +| **GHC not installed** | ❌ **No** | Tool cannot run | + +### Should I use php-aegis? + +| Your Situation | Use php-aegis? | Why | +|----------------|---------------|-----| +| WordPress plugin/theme | ⚠️ **Only for unique features** | WP core has equivalent security | +| Laravel/Symfony app | ✅ Yes | Complements framework security | +| Vanilla PHP app | ✅ Yes | Provides missing security layer | +| Semantic web (RDF/Turtle) | ✅ **Yes - unique value** | No other library handles this | +| IndieWeb (Micropub, etc.) | ✅ **Yes - unique value** | Protocol-specific security | +| ActivityPub/Fediverse | ✅ **Yes - unique value** | Content policy enforcement | + +--- + +## sanctify-php: When to Use + +### Ideal Use Cases + +1. **Security Audits** + - Scanning legacy codebases for vulnerabilities + - Pre-deployment security checks + - Compliance requirements (PCI, SOC2) + +2. **CI/CD Integration** + - Block PRs with security issues + - Generate SARIF reports for GitHub Security + - Track security debt over time + +3. **Code Transformation** + - Auto-add `declare(strict_types=1)` + - Insert missing escaping functions + - Enforce WordPress coding standards + +### When NOT to Use + +1. **GHC Not Available** (BLOCKER) + - sanctify-php requires Haskell compiler + - Until pre-built binaries exist, many environments can't use it + - Workaround: Docker container (when available) + +2. **Already Well-Secured WordPress Plugins** + - Mature plugins like Zotpress already follow WP security best practices + - sanctify-php adds limited value if codebase is already clean + - May still be useful for regression detection + +3. **Quick One-Off Scripts** + - Overhead not worth it for disposable code + - Use php-aegis runtime protection instead + +--- + +## php-aegis: When to Use + +### Ideal Use Cases + +1. **Non-WordPress PHP Applications** + ```php + // Laravel, Symfony, vanilla PHP + use Aegis\Escape; + echo Escape::html($userInput); + ``` + +2. **Semantic Web Applications** (UNIQUE VALUE) + ```php + // RDF/Turtle output - WordPress can't do this + use Aegis\Semantic\Turtle; + echo '"' . Turtle::escapeString($label) . '"'; + ``` + +3. **IndieWeb Applications** (UNIQUE VALUE) + ```php + // Micropub content sanitization + use Aegis\IndieWeb\Micropub; + $safe = Micropub::sanitizeContent($content, ['allow_html' => true]); + ``` + +4. **ActivityPub/Fediverse** (UNIQUE VALUE) + ```php + // Federated content policies + use Aegis\ActivityPub\Content; + $safe = Content::sanitize($post, ContentPolicy::STRICT); + ``` + +### When NOT to Use + +1. **WordPress Plugins/Themes (for standard security)** + + WordPress already provides: + | Need | WordPress Function | php-aegis Adds Nothing | + |------|-------------------|----------------------| + | HTML escape | `esc_html()` | ❌ | + | Attribute escape | `esc_attr()` | ❌ | + | URL escape | `esc_url()` | ❌ | + | JS escape | `esc_js()` | ❌ | + | Email validation | `is_email()` | ❌ | + | Sanitize text | `sanitize_text_field()` | ❌ | + + **Exception**: Use php-aegis for Turtle/RDF/IndieWeb in WordPress themes. + +2. **PHP 7.4 Environments (until compat package exists)** + - php-aegis requires PHP 8.1+ + - WordPress supports PHP 7.4+ + - Need `php-aegis-compat` package first + +--- + +## Combined Use: When Both Tools Add Value + +The tools complement each other best when: + +### Scenario: Semantic WordPress Theme + +``` +┌─────────────────────────────────────────────────────────────┐ +│ WordPress theme with RDF/Turtle output (IndieWeb/Semantic) │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ sanctify-php: │ +│ • Detects Turtle output context │ +│ • Warns: "esc_html() wrong for Turtle, use Aegis" │ +│ • Auto-inserts: Aegis\Semantic\Turtle::escapeString() │ +│ │ +│ php-aegis: │ +│ • Provides runtime Turtle escaping │ +│ • W3C-compliant string/IRI handling │ +│ • WordPress doesn't have this capability │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Scenario: Laravel API with Security Requirements + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Laravel API with strict security requirements │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ sanctify-php (CI/CD): │ +│ • SARIF reports in GitHub Security │ +│ • Block PRs with SQL injection │ +│ • Enforce type hints on all functions │ +│ │ +│ php-aegis (runtime): │ +│ • Defense in depth for validation │ +│ • Consistent escaping API │ +│ • Additional validators (IP, UUID, credit card) │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Scenario: Standard WordPress Plugin + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Standard WordPress plugin (no semantic web) │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ sanctify-php: ⚠️ Limited value │ +│ • May catch issues WP doesn't │ +│ • Useful for security audit │ +│ • But WP security is already comprehensive │ +│ │ +│ php-aegis: ❌ No value │ +│ • WordPress already has esc_html(), etc. │ +│ • Adding Aegis duplicates existing functions │ +│ • Exception: Use for unique validators WP lacks │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## Summary: Unique Value Propositions + +### sanctify-php Unique Value + +| Capability | Competition | sanctify-php Advantage | +|------------|-------------|----------------------| +| PHP static analysis | PHPStan, Psalm | Security-focused, not just types | +| WordPress awareness | PHPCS-WPCS | Deeper taint tracking | +| Auto-fix transforms | None | Automatic code hardening | +| SARIF output | Few tools | GitHub Security integration | +| Semantic context | None | Detects Turtle/JSON-LD contexts | + +### php-aegis Unique Value + +| Capability | Competition | php-aegis Advantage | +|------------|-------------|---------------------| +| Turtle/RDF escaping | **None** | Only library for semantic web | +| Micropub sanitization | **None** | IndieWeb protocol security | +| ActivityPub content | **None** | Fediverse content policies | +| Context-aware escaping | Laravel, WP | Unified API across frameworks | +| UUID/IP/credit card | Various | Consolidated validation library | + +--- + +## Recommendations + +### For php-aegis Team + +1. **Don't compete with WordPress core** — document that php-aegis is for non-WP apps or unique WP needs +2. **Focus on unique value** — Turtle, IndieWeb, ActivityPub are unserved markets +3. **Create framework adapters** — Laravel, Symfony, WordPress (for unique features only) + +### For sanctify-php Team + +1. **Pre-built binaries are MANDATORY** — tool literally cannot be used without them +2. **Docker image as fallback** — for environments that can't install binaries +3. **Document when NOT to use** — mature WP plugins may not benefit + +--- + +*SPDX-License-Identifier: MIT OR AGPL-3.0-or-later* +*SPDX-FileCopyrightText: 2024-2025 hyperpolymath*