Skip to content

Claude/integrate security tools k zla e #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hyperpolymath merged 4 commits into from
Dec 27, 2025
Merged

Claude/integrate security tools k zla e #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a21d942
Add integration feedback documentation and roadmap
claude Dec 27, 2025
ae90570
Add critical adoption feedback: Composer wrapper, PHP 7.4 compat
claude Dec 27, 2025
1a21fb0
Add Zotpress integration findings: GHC blocker, WP overlap
claude Dec 27, 2025
9fc7a77
Merge branch 'main' into claude/integrate-security-tools-KZlaE
hyperpolymath Dec 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 21 additions & 4 deletions docs/IMPLEMENTATION-TRACKER.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
70 changes: 66 additions & 4 deletions docs/PHP-AEGIS-HANDOVER.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

---

Expand All @@ -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+
Expand Down
35 changes: 28 additions & 7 deletions docs/ROADMAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,32 +2,53 @@

## 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 |
| Missing WP integration docs | Medium | Users don't know how to integrate |

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

---

Expand Down
Loading
Loading