Claude/integrate security tools k zla e

docs/IMPLEMENTATION-TRACKER.md

@@ -6,30 +6,67 @@
 |------|--------|-------------|
 | php-aegis Handover | ✅ Complete | Send to php-aegis team |
 | sanctify-php Roadmap | ✅ Complete | Begin Phase 1 |
-| Binary Releases | 🔲 Not Started | Create CI workflow |
+| Standalone Requirements | ✅ Complete | See STANDALONE.md |
+| Binary Releases | 🔲 Not Started | **CRITICAL** - Create CI workflow |
+| Composer Plugin | 🔲 Not Started | **CRITICAL** - Enable `composer require` |
+| 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 Path: Adoption Blockers
+
+> **Key Insight**: The biggest barrier to adoption is the Haskell dependency.
+> PHP developers expect `composer require` installation with no external runtime.
+
+### sanctify-php Critical Items
+
+| Item | Priority | Blocks |
+|------|----------|--------|
+| Pre-built binaries | **CRITICAL** | Everything else |
+| Composer plugin wrapper | **CRITICAL** | PHP dev adoption |
+| GitHub Action | High | CI/CD adoption |
+| Incremental analysis | Medium | Performance at scale |
+
+### php-aegis Critical Items
+
+| Item | Priority | Blocks |
+|------|----------|--------|
+| php-aegis-compat (PHP 7.4+) | **CRITICAL** | WordPress adoption |
+| WordPress adapter (snake_case) | High | WP dev experience |
+| Extended validators | Medium | Common use cases |
+
+---
+
 ## Immediate Actions
 
 ### For php-aegis Team
 
 1. **Review handover document**: `docs/PHP-AEGIS-HANDOVER.md`
-2. **Priority implementation**:
-   - `Aegis\Semantic\Turtle::escapeString()`
-   - `Aegis\Semantic\Turtle::escapeIRI()`
-   - SPDX headers on all files
+2. **Critical implementation** (adoption blockers):
+   - [ ] Create `php-aegis-compat` package for PHP 7.4+
+   - [ ] Add WordPress adapter with snake_case functions
+   - [ ] Extend `Validate` class: `int()`, `ip()`, `domain()`
+3. **Priority implementation** (unique value):
+   - [ ] `Aegis\Semantic\Turtle::escapeString()`
+   - [ ] `Aegis\Semantic\Turtle::escapeIRI()`
+   - [ ] SPDX headers on all files
 
 ### For sanctify-php Team
 
-1. **Phase 1 Priority**: Make tool accessible without Haskell
-   - [ ] GitHub Actions for binary releases
+1. **Phase 1 CRITICAL**: Enable `composer require` installation
+   - [ ] GitHub Actions for binary releases (linux, darwin x86_64/arm64)
+   - [ ] Composer plugin that auto-downloads binary on install
+   - [ ] GitHub Action for CI/CD integration
    - [ ] Dockerfile for container distribution
-   - [ ] Update README with installation options
 
-2. **Phase 2 Priority**: Semantic web support
+2. **Phase 1 HIGH**: Performance
+   - [ ] Incremental analysis with file hash cache
+   - [ ] Only rescan changed files
+
+3. **Phase 2 Priority**: Semantic web support
    - [ ] Create `Sanctify.Analysis.Semantic` module
    - [ ] Extend taint sinks for Turtle/JSON-LD contexts
    - [ ] Add WordPress semantic theme detection

docs/PHP-AEGIS-HANDOVER.md

@@ -15,16 +15,244 @@ This document provides integration feedback from the wp-sinople-theme WordPress
 
 | Issue | Severity | Impact |
 |-------|----------|--------|
+| 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() |
 | Missing SPDX license headers | Low | Compliance concern for FOSS projects |
-| No PHP 8.1+ features | Medium | Missing enums, union types, readonly properties |
 
 ---
 
 ## Detailed Recommendations
 
-### 1. Differentiate from WordPress Core Functions
+### 0. 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+
+- Many shared hosts still run PHP 7.4 or 8.0
+- Plugin/theme developers must support the WordPress minimum
+
+**Solution**: Split into two packages:
+
+```
+php-aegis (PHP 8.1+)           ← Modern API with enums, union types
+    │
+    └── php-aegis-compat (PHP 7.4+)  ← Polyfill package for WordPress
+```
+
+**php-aegis-compat Implementation**:
+
+```php
+<?php
+// SPDX-License-Identifier: MIT
+// php-aegis-compat/src/Escape.php
+
+namespace Aegis;
+
+/**
+ * PHP 7.4+ compatible escape functions.
+ * Mirrors php-aegis API without 8.1+ features.
+ */
+final class Escape
+{
+    /**
+     * @param string $value
+     * @param string $context One of: html, attr, url, js, css, turtle, jsonld
+     * @return string
+     */
+    public static function context(string $value, string $context): string
+    {
+        switch ($context) {
+            case 'html':
+                return htmlspecialchars($value, ENT_QUOTES | ENT_HTML5, 'UTF-8');
+            case 'attr':
+                return htmlspecialchars($value, ENT_QUOTES | ENT_HTML5, 'UTF-8');
+            case 'url':
+                return filter_var($value, FILTER_SANITIZE_URL) ?: '';
+            case 'turtle':
+                return Semantic\Turtle::escapeString($value);
+            default:
+                throw new \InvalidArgumentException("Unknown context: {$context}");
+        }
+    }
+}
+```
+
+**Composer Setup**:
+```json
+{
+    "name": "hyperpolymath/php-aegis-compat",
+    "description": "PHP 7.4+ compatibility layer for php-aegis",
+    "require": {
+        "php": ">=7.4"
+    },
+    "conflict": {
+        "hyperpolymath/php-aegis": "*"
+    },
+    "autoload": {
+        "psr-4": { "Aegis\\": "src/" }
+    }
+}
+```
+
+**Usage in WordPress plugins**:
+```php
+// In plugin bootstrap
+if (PHP_VERSION_ID >= 80100) {
+    require_once __DIR__ . '/vendor/hyperpolymath/php-aegis/autoload.php';
+} else {
+    require_once __DIR__ . '/vendor/hyperpolymath/php-aegis-compat/autoload.php';
+}
+```
+
+### 1. WordPress Adapter (snake_case API)
+
+**Problem**: WordPress uses `snake_case` functions, php-aegis uses `CamelCase` methods.
+
+**Solution**: Provide WordPress adapter functions:
+
+```php
+<?php
+// SPDX-License-Identifier: MIT
+// php-aegis/src/WordPress/functions.php
+
+namespace Aegis\WordPress;
+
+use Aegis\Escape;
+use Aegis\Validate;
+use Aegis\Semantic\Turtle;
+
+/**
+ * WordPress-style function wrappers.
+ * Use in themes/plugins for familiar API.
+ */
+
+function aegis_escape_html(string $value): string {
+    return Escape::html($value);
+}
+
+function aegis_escape_attr(string $value): string {
+    return Escape::attr($value);
+}
+
+function aegis_escape_turtle(string $value): string {
+    return Turtle::escapeString($value);
+}
+
+function aegis_escape_turtle_iri(string $iri): string {
+    return Turtle::escapeIRI($iri);
+}
+
+function aegis_validate_int($value): ?int {
+    return Validate::int($value);
+}
+
+function aegis_validate_ip(string $value): ?string {
+    return Validate::ip($value);
+}
+
+function aegis_validate_domain(string $value): ?string {
+    return Validate::domain($value);
+}
+```
+
+**Registration via WordPress hooks**:
+```php
+<?php
+// php-aegis/src/WordPress/Loader.php
+
+namespace Aegis\WordPress;
+
+final class Loader
+{
+    public static function init(): void
+    {
+        // Load function wrappers
+        require_once __DIR__ . '/functions.php';
+
+        // Register with WordPress security hooks
+        add_filter('sanitize_text_field', [self::class, 'enhanceSanitize'], 10, 1);
+    }
+
+    public static function enhanceSanitize(string $value): string
+    {
+        // Aegis-enhanced sanitization
+        return \Aegis\Sanitize::text($value);
+    }
+}
+
+// Auto-init when WordPress is detected
+if (defined('ABSPATH')) {
+    add_action('plugins_loaded', [Loader::class, 'init']);
+}
+```
+
+### 2. Extended Validators
+
+**Problem**: Only `email()` and `url()` validators exist. Real-world needs:
+
+**Add these validators**:
+
+```php
+<?php
+// SPDX-License-Identifier: MIT
+
+namespace Aegis;
+
+final class Validate
+{
+    public static function email(string $value): ?string { /* existing */ }
+    public static function url(string $value): ?string { /* existing */ }
+
+    // NEW validators:
+
+    public static function int(mixed $value): ?int
+    {
+        if (is_int($value)) return $value;
+        if (is_string($value) && ctype_digit(ltrim($value, '-'))) {
+            return (int)$value;
+        }
+        return null;
+    }
+
+    public static function ip(string $value, int $flags = FILTER_FLAG_IPV4 | FILTER_FLAG_IPV6): ?string
+    {
+        $result = filter_var($value, FILTER_VALIDATE_IP, $flags);
+        return $result !== false ? $result : null;
+    }
+
+    public static function domain(string $value): ?string
+    {
+        // Remove protocol if present
+        $domain = preg_replace('#^https?://#', '', $value);
+        $domain = explode('/', $domain)[0];
+
+        if (filter_var($domain, FILTER_VALIDATE_DOMAIN, FILTER_FLAG_HOSTNAME)) {
+            return $domain;
+        }
+        return null;
+    }
+
+    public static function uuid(string $value): ?string
+    {
+        if (preg_match('/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i', $value)) {
+            return strtolower($value);
+        }
+        return null;
+    }
+
+    public static function slug(string $value): ?string
+    {
+        if (preg_match('/^[a-z0-9]+(?:-[a-z0-9]+)*$/', $value)) {
+            return $value;
+        }
+        return null;
+    }
+}
+```
+
+### 3. Differentiate from WordPress Core Functions
 
 **Problem**: WordPress already provides `esc_html()`, `esc_attr()`, `sanitize_text_field()`, etc.
 
@@ -282,20 +510,26 @@ We will add support in sanctify-php to:
 
 ## Action Items for php-aegis Team
 
-### Priority 1 (High)
+### Priority 0 (Critical) — Adoption Blockers
+- [ ] Create `php-aegis-compat` package for PHP 7.4+
+- [ ] Add WordPress adapter with snake_case functions
+- [ ] Extend `Validate` class: `int()`, `ip()`, `domain()`, `uuid()`, `slug()`
+
+### Priority 1 (High) — Unique Value
 - [ ] Add `Aegis\Semantic\Turtle` namespace with W3C-compliant escaping
 - [ ] Add `Aegis\IndieWeb\Micropub` for content sanitization
 - [ ] Add SPDX headers to all files
 
-### Priority 2 (Medium)
-- [ ] Refactor to use PHP 8.1+ enums for contexts
+### Priority 2 (Medium) — Polish
+- [ ] Use PHP 8.1+ enums for contexts (in main package only)
 - [ ] Add union types throughout API
 - [ ] Document differentiation from WordPress core functions
+- [ ] Auto-detect WordPress and register hooks
 
-### Priority 3 (Low)
+### Priority 3 (Low) — Extended Features
 - [ ] Add ActivityPub sanitization support
 - [ ] Add JSON-LD validation
-- [ ] Create WordPress integration hooks
+- [ ] Laravel adapter (in addition to WordPress)
 
 ---