Claude/integrate security tools h nyd u

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).*

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.*

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