diff --git a/HANDOVER_SANCTIFY.md b/HANDOVER_SANCTIFY.md index 46f5e85..70d1574 100644 --- a/HANDOVER_SANCTIFY.md +++ b/HANDOVER_SANCTIFY.md @@ -380,13 +380,119 @@ safeSinks = [ --- +## Additional Findings (Report 3: Zotpress Plugin) + +### 10. GHC Barrier Confirmed (Critical) + +**Problem**: sanctify-php could not run on the Zotpress integration due to missing Haskell toolchain. + +**Impact**: This is now confirmed across multiple integration attempts. The Haskell build requirement is the #1 adoption barrier. + +**Immediate Recommendations**: +1. Provide pre-built binaries for: + - Linux x86_64 (static binary) + - Linux aarch64 (for ARM servers) + - macOS Intel + - macOS Apple Silicon + - Windows x64 +2. Publish Docker image: `ghcr.io/hyperpolymath/sanctify-php:latest` +3. Create GitHub Action that uses the Docker image internally + +**Workaround Used**: Manual analysis using sanctify-php's documented detection patterns. + +### 11. WordPress Security API Overlap + +**Finding**: When analyzing mature WordPress plugins (like Zotpress), they already follow WordPress security best practices using core functions. + +**WordPress provides equivalent security functions**: + +| php-aegis | WordPress Equivalent | Notes | +|-----------|---------------------|-------| +| `Validator::email()` | `is_email()` | WP version is more permissive | +| `Validator::url()` | `wp_http_validate_url()` | WP has SSL enforcement | +| `Sanitizer::html()` | `esc_html()` | Identical functionality | +| `Sanitizer::attr()` | `esc_attr()` | Identical functionality | +| `Sanitizer::js()` | `esc_js()` | WP version is context-aware | +| `Sanitizer::url()` | `esc_url()` | WP handles protocols | +| `Sanitizer::stripTags()` | `wp_strip_all_tags()` | WP handles more edge cases | + +**What sanctify-php should detect**: +- Direct use of raw PHP functions instead of WordPress equivalents +- `echo $var` instead of `echo esc_html($var)` +- `header('Location: ...')` instead of `wp_redirect()` +- Missing `exit;` after redirect + +**sanctify-php rule suggestions**: +```haskell +-- WordPress-specific rules +wpRules = [ + ("use_wp_redirect", "header\\s*\\(\\s*['\"]Location", "Use wp_redirect() instead of header()"), + ("missing_exit_redirect", "wp_redirect\\([^;]+\\);(?!\\s*exit)", "Add exit; after wp_redirect()"), + ("raw_echo", "echo\\s+\\$(?!esc_)", "Escape output with esc_html()/esc_attr()"), + ("direct_superglobal", "\\$_(GET|POST|REQUEST)\\[", "Sanitize superglobals before use") +] +``` + +### 12. Target Audience Clarification Needed + +**Finding**: php-aegis value proposition is unclear for WordPress users. + +**Recommended positioning for sanctify-php**: + +When sanctify-php detects issues in WordPress code, suggest: +1. **First choice**: WordPress native function (if available) +2. **Second choice**: php-aegis function (for gaps WordPress doesn't cover) + +``` +VULNERABILITY: Unescaped output +FILE: plugin.php:42 +CODE: echo $user_input; + +RECOMMENDATION: + WordPress: echo esc_html($user_input); + Or php-aegis: echo \PhpAegis\Sanitizer::html($user_input); +``` + +### 13. WordPress-Unique Security Patterns + +**What sanctify-php should understand about WordPress**: + +```php +// WordPress-specific security patterns + +// 1. ABSPATH protection (must be at top of every PHP file) +if (!defined('ABSPATH')) exit; + +// 2. Nonce verification for forms +check_admin_referer('action_name'); +wp_verify_nonce($_POST['nonce'], 'action_name'); + +// 3. Capability checks for privileged actions +if (!current_user_can('manage_options')) return; + +// 4. Prepared statements for database +$wpdb->prepare("SELECT * FROM table WHERE id = %d", $id); + +// 5. Safe redirect +wp_safe_redirect($url); +exit; +``` + +**Detection rules needed**: +- Missing ABSPATH check at file start +- Form handlers without nonce verification +- AJAX handlers without capability checks +- Missing `exit;` after redirects + +--- + ## Contact For questions about this integration or to coordinate between repos: - php-aegis: https://github.com/hyperpolymath/php-aegis - sanctify-php: https://github.com/hyperpolymath/sanctify-php -- Integration tested in: wp-sinople-theme +- Integration tested in: wp-sinople-theme, Zotpress --- -*Generated from real-world WordPress semantic theme integration experience (Reports 1 & 2).* +*Generated from real-world WordPress integration experience (Reports 1, 2 & 3).* diff --git a/POSITIONING.md b/POSITIONING.md new file mode 100644 index 0000000..4a35c85 --- /dev/null +++ b/POSITIONING.md @@ -0,0 +1,231 @@ +# php-aegis Positioning & Target Audience + +## The Problem We Discovered + +After integrating php-aegis with multiple WordPress projects (themes and plugins), we found: + +> **WordPress already has comprehensive security APIs** (`esc_html()`, `esc_attr()`, `wp_kses()`, etc.) that are deeply integrated with the WordPress ecosystem. + +This means php-aegis **should not compete** with WordPress core functions. Instead, it should: + +1. **Target non-WordPress PHP applications** where no security API exists +2. **Provide unique capabilities** that WordPress (and other frameworks) lack + +--- + +## Target Audience Matrix + +| Audience | php-aegis Value | Recommendation | +|----------|-----------------|----------------| +| **WordPress plugins/themes** | Low | Use WordPress core functions | +| **Laravel applications** | Medium | Use Laravel's helpers, aegis for gaps | +| **Symfony applications** | Medium | Use Twig's escaping, aegis for gaps | +| **Vanilla PHP applications** | **High** | php-aegis is the primary security layer | +| **API-only services** | **High** | No view layer = no framework escaping | +| **CLI tools** | **High** | No framework = aegis fills the gap | +| **Microservices** | **High** | Lightweight, zero-dependency | +| **Semantic Web apps** | **Very High** | TurtleEscaper is unique | + +--- + +## What WordPress Has (Don't Duplicate) + +| WordPress Function | Purpose | php-aegis Equivalent | +|--------------------|---------|---------------------| +| `esc_html()` | HTML content escaping | `Sanitizer::html()` | +| `esc_attr()` | HTML attribute escaping | `Sanitizer::attr()` | +| `esc_url()` | URL escaping with protocol check | `Sanitizer::url()` | +| `esc_js()` | JavaScript escaping | `Sanitizer::js()` | +| `wp_kses()` | HTML filtering with allowlist | ❌ Not implemented | +| `wp_kses_post()` | HTML filtering for posts | ❌ Not implemented | +| `sanitize_text_field()` | Text sanitization | `Sanitizer::stripTags()` | +| `is_email()` | Email validation | `Validator::email()` | +| `wp_http_validate_url()` | URL validation + SSL | `Validator::url()` | +| `absint()` | Positive integer | `Validator::int(..., min: 0)` | + +**For WordPress projects**: Use WordPress functions. They're more battle-tested, ecosystem-integrated, and maintained by Automattic. + +--- + +## What php-aegis Provides (Unique Value) + +These capabilities are **not available** in WordPress, Laravel, or Symfony: + +### 1. RDF/Turtle Escaping (Unique) + +No other PHP library provides W3C-compliant Turtle escaping. + +```php +use PhpAegis\TurtleEscaper; + +// Safe for semantic web applications +TurtleEscaper::string($userLabel); +TurtleEscaper::iri($userProvidedUri); +TurtleEscaper::triple($subject, $predicate, $object, 'en'); +``` + +**Use cases**: +- Linked Data platforms +- Knowledge graphs +- Semantic WordPress themes (like wp-sinople-theme) +- SPARQL endpoint integrations + +### 2. Security Headers Helper + +WordPress doesn't provide header helpers. Frameworks have partial support. + +```php +use PhpAegis\Headers; + +// One-line security hardening +Headers::secure(); + +// Or fine-grained control +Headers::contentSecurityPolicy([...]); +Headers::strictTransportSecurity(maxAge: 31536000, preload: true); +Headers::permissionsPolicy([...]); +``` + +### 3. Extended Validators Not in WordPress + +| php-aegis | WordPress Equivalent | Notes | +|-----------|---------------------|-------| +| `Validator::uuid()` | ❌ None | RFC 4122 UUID validation | +| `Validator::ip()` | ❌ None | IPv4/IPv6 validation | +| `Validator::ipv4()` | ❌ None | IPv4 only | +| `Validator::ipv6()` | ❌ None | IPv6 only | +| `Validator::domain()` | ❌ None | RFC 1035 domain validation | +| `Validator::hostname()` | ❌ None | Domain or IP | +| `Validator::slug()` | `sanitize_title()` | WP sanitizes, aegis validates | +| `Validator::semver()` | ❌ None | Semantic versioning | +| `Validator::iso8601()` | ❌ None | ISO 8601 datetime | +| `Validator::hexColor()` | `sanitize_hex_color()` | WP sanitizes, aegis validates | +| `Validator::safeFilename()` | `sanitize_file_name()` | WP sanitizes, aegis validates | +| `Validator::json()` | ❌ None | JSON structure validation | +| `Validator::int(min, max)` | ❌ None | Integer with range | +| `Validator::printable()` | ❌ None | ASCII printable only | +| `Validator::noNullBytes()` | ❌ None | Path traversal prevention | +| `Validator::httpsUrl()` | `wp_http_validate_url()` | WP has `$ssl` param | + +### 4. Zero Dependencies + +- WordPress functions require WordPress +- Laravel helpers require Laravel +- Symfony components require Symfony + +php-aegis works in any PHP 8.1+ environment with no dependencies. + +--- + +## Recommended Usage Patterns + +### For WordPress Projects + +```php +// DON'T: Use php-aegis for basic escaping +echo \PhpAegis\Sanitizer::html($content); // ❌ Redundant + +// DO: Use WordPress functions +echo esc_html($content); // ✅ Preferred + +// DO: Use php-aegis for unique capabilities +$headers = new \PhpAegis\Headers(); +$headers::secure(); // ✅ WordPress lacks this + +// DO: Use php-aegis for semantic web features +echo \PhpAegis\TurtleEscaper::string($label); // ✅ WordPress lacks this + +// DO: Use php-aegis for validation gaps +if (!\PhpAegis\Validator::uuid($_GET['id'])) { // ✅ WordPress lacks this + wp_die('Invalid ID'); +} +``` + +### For Laravel Projects + +```php +// DON'T: Use php-aegis for Blade escaping +{{ $content }} // Blade auto-escapes, don't use aegis + +// DO: Use php-aegis in non-Blade contexts +$uuid = $request->input('resource_id'); +if (!Validator::uuid($uuid)) { + abort(400, 'Invalid resource ID'); +} + +// DO: Use for security headers (Laravel's is less comprehensive) +Headers::secure(); +``` + +### For Vanilla PHP / APIs + +```php +// DO: Use php-aegis as your primary security layer +use PhpAegis\{Validator, Sanitizer, Headers}; + +// Apply security headers +Headers::secure(); + +// Validate input +if (!Validator::email($_POST['email'])) { + http_response_code(400); + exit(json_encode(['error' => 'Invalid email'])); +} + +// Sanitize output +echo Sanitizer::html($userContent); +``` + +--- + +## Marketing Positioning + +### Tagline Options + +1. **"Security for the rest of PHP"** - Emphasizes non-framework use +2. **"Where frameworks fear to tread"** - Emphasizes unique capabilities +3. **"Semantic web security, done right"** - Emphasizes Turtle escaping niche + +### README Messaging + +``` +php-aegis is a zero-dependency PHP security toolkit for: +- API services without view layers +- CLI tools and microservices +- Semantic web applications (RDF/Turtle) +- Any PHP app without a framework + +For WordPress, use WordPress core functions. +For Laravel/Symfony, use framework helpers + aegis for gaps. +``` + +--- + +## Roadmap Implications + +Based on this positioning, prioritize: + +1. **RDF/Turtle escaping** - Already done, unique differentiator +2. **Security headers** - Already done, fills framework gaps +3. **Extended validators** - Focus on what WordPress lacks (UUID, IP, semver, etc.) +4. **IndieWeb security** - Micropub, IndieAuth, Webmention (unique niche) +5. **Rate limiting** - File-based, no Redis required + +De-prioritize: +- HTML/attribute escaping improvements (frameworks do this well) +- WordPress adapter (WordPress users should use WordPress functions) + +--- + +## Success Metrics + +| Metric | Target Audience Indicator | +|--------|--------------------------| +| Downloads from API/microservice projects | Primary audience | +| Usage in semantic web tools | Niche but high-value | +| Issues asking about WordPress | Signals need for better docs | +| PRs adding framework adapters | Community wants integration | + +--- + +*This positioning reflects insights from WordPress theme (wp-sinople-theme) and plugin (Zotpress) integration attempts.* diff --git a/README.adoc b/README.adoc index 354fc63..4154233 100644 --- a/README.adoc +++ b/README.adoc @@ -14,6 +14,22 @@ image:https://img.shields.io/badge/RSR-Compliant-gold.svg[RSR Compliant] php-aegis provides a collection of security-focused utilities for PHP applications. Named after the mythological shield of Zeus, it aims to protect your applications from common web vulnerabilities. +=== Best For + +* **API services** without view layers +* **CLI tools** and microservices +* **Semantic web applications** (RDF/Turtle escaping - unique to php-aegis) +* **Vanilla PHP** applications without frameworks +* **Framework gaps** - validation/features that WordPress/Laravel/Symfony lack + +=== Not Needed For + +* **WordPress plugins/themes** - Use WordPress core functions (`esc_html()`, `esc_attr()`, etc.) +* **Laravel views** - Use Blade's auto-escaping +* **Symfony/Twig** - Use Twig's escaping + +See link:POSITIONING.md[POSITIONING.md] for detailed guidance. + === Key Features * **Input Validation** - Strict validation for emails, URLs, IPs, UUIDs, and more diff --git a/ROADMAP_PRIORITY.md b/ROADMAP_PRIORITY.md index 8cf6c43..c1838e2 100644 --- a/ROADMAP_PRIORITY.md +++ b/ROADMAP_PRIORITY.md @@ -1,17 +1,32 @@ # php-aegis Roadmap (Integration-Informed Priority) -This roadmap is prioritized based on real-world integration experience with WordPress semantic themes and the feedback received during the wp-sinople-theme security integration. +This roadmap is prioritized based on real-world integration experience with WordPress themes and plugins, reflecting lessons from wp-sinople-theme and Zotpress integrations. -## Context: Why This Matters +## Strategic Positioning -During integration testing, the following gaps were identified: +See [POSITIONING.md](POSITIONING.md) for full positioning strategy. -1. **Feature set too minimal** - WordPress has `esc_html()`, `esc_attr()`, etc. already -2. **No RDF/Turtle support** - Semantic themes need specialized escaping -3. **Missing SPDX headers** - Compliance requirement not met -4. **Not leveraging PHP 8.1+** - Enums, union types, readonly properties unused +**Key insight**: WordPress (and Laravel, Symfony) already have comprehensive security APIs. php-aegis should: -This roadmap addresses these gaps in priority order. +1. **Target non-framework PHP** - APIs, CLI tools, microservices +2. **Provide unique capabilities** - RDF/Turtle, security headers, extended validators +3. **Fill framework gaps** - What WordPress/Laravel/Symfony don't provide + +**Do NOT prioritize**: Duplicating `esc_html()`, `esc_attr()` equivalents that frameworks already do well. + +## Context: Integration Findings + +| Integration | Finding | +|-------------|---------| +| wp-sinople-theme | RDF/Turtle escaping is unique value; basic sanitization duplicates WordPress | +| Zotpress plugin | Mature WP plugins already use core functions; php-aegis not needed for basic security | + +**Prioritize features WordPress lacks**: +- RDF/Turtle escaping ✅ +- Security headers ✅ +- Extended validators (UUID, IP, semver, etc.) ✅ +- IndieWeb security (Micropub, IndieAuth) +- Rate limiting without external dependencies ---