Skip to content

Commit 121ba67

Browse files
claudeclaude
committed
docs: Add positioning strategy and Report 3 findings
Based on Zotpress integration feedback: New Documentation: - POSITIONING.md: Clear target audience guidance - Best for: APIs, CLI tools, microservices, semantic web - Not needed for: WordPress (use core functions), Laravel/Symfony (use framework helpers) - Unique value: RDF/Turtle escaping, security headers, extended validators HANDOVER_SANCTIFY.md Updates: - Report 3: GHC barrier confirmed (critical) - WordPress security API overlap documented - WordPress-specific detection rules for sanctify-php - Target audience clarification recommendations README/Roadmap Updates: - Added "Best For" / "Not Needed For" sections - Strategic positioning in roadmap intro - Focus on unique capabilities WordPress lacks
1 parent 7a04a35 commit 121ba67

4 files changed

Lines changed: 378 additions & 10 deletions

File tree

‎HANDOVER_SANCTIFY.md‎

Lines changed: 108 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -380,13 +380,119 @@ safeSinks = [
380380

381381
---
382382

383+
## Additional Findings (Report 3: Zotpress Plugin)
384+
385+
### 10. GHC Barrier Confirmed (Critical)
386+
387+
**Problem**: sanctify-php could not run on the Zotpress integration due to missing Haskell toolchain.
388+
389+
**Impact**: This is now confirmed across multiple integration attempts. The Haskell build requirement is the #1 adoption barrier.
390+
391+
**Immediate Recommendations**:
392+
1. Provide pre-built binaries for:
393+
- Linux x86_64 (static binary)
394+
- Linux aarch64 (for ARM servers)
395+
- macOS Intel
396+
- macOS Apple Silicon
397+
- Windows x64
398+
2. Publish Docker image: `ghcr.io/hyperpolymath/sanctify-php:latest`
399+
3. Create GitHub Action that uses the Docker image internally
400+
401+
**Workaround Used**: Manual analysis using sanctify-php's documented detection patterns.
402+
403+
### 11. WordPress Security API Overlap
404+
405+
**Finding**: When analyzing mature WordPress plugins (like Zotpress), they already follow WordPress security best practices using core functions.
406+
407+
**WordPress provides equivalent security functions**:
408+
409+
| php-aegis | WordPress Equivalent | Notes |
410+
|-----------|---------------------|-------|
411+
| `Validator::email()` | `is_email()` | WP version is more permissive |
412+
| `Validator::url()` | `wp_http_validate_url()` | WP has SSL enforcement |
413+
| `Sanitizer::html()` | `esc_html()` | Identical functionality |
414+
| `Sanitizer::attr()` | `esc_attr()` | Identical functionality |
415+
| `Sanitizer::js()` | `esc_js()` | WP version is context-aware |
416+
| `Sanitizer::url()` | `esc_url()` | WP handles protocols |
417+
| `Sanitizer::stripTags()` | `wp_strip_all_tags()` | WP handles more edge cases |
418+
419+
**What sanctify-php should detect**:
420+
- Direct use of raw PHP functions instead of WordPress equivalents
421+
- `echo $var` instead of `echo esc_html($var)`
422+
- `header('Location: ...')` instead of `wp_redirect()`
423+
- Missing `exit;` after redirect
424+
425+
**sanctify-php rule suggestions**:
426+
```haskell
427+
-- WordPress-specific rules
428+
wpRules = [
429+
("use_wp_redirect", "header\\s*\\(\\s*['\"]Location", "Use wp_redirect() instead of header()"),
430+
("missing_exit_redirect", "wp_redirect\\([^;]+\\);(?!\\s*exit)", "Add exit; after wp_redirect()"),
431+
("raw_echo", "echo\\s+\\$(?!esc_)", "Escape output with esc_html()/esc_attr()"),
432+
("direct_superglobal", "\\$_(GET|POST|REQUEST)\\[", "Sanitize superglobals before use")
433+
]
434+
```
435+
436+
### 12. Target Audience Clarification Needed
437+
438+
**Finding**: php-aegis value proposition is unclear for WordPress users.
439+
440+
**Recommended positioning for sanctify-php**:
441+
442+
When sanctify-php detects issues in WordPress code, suggest:
443+
1. **First choice**: WordPress native function (if available)
444+
2. **Second choice**: php-aegis function (for gaps WordPress doesn't cover)
445+
446+
```
447+
VULNERABILITY: Unescaped output
448+
FILE: plugin.php:42
449+
CODE: echo $user_input;
450+
451+
RECOMMENDATION:
452+
WordPress: echo esc_html($user_input);
453+
Or php-aegis: echo \PhpAegis\Sanitizer::html($user_input);
454+
```
455+
456+
### 13. WordPress-Unique Security Patterns
457+
458+
**What sanctify-php should understand about WordPress**:
459+
460+
```php
461+
// WordPress-specific security patterns
462+
463+
// 1. ABSPATH protection (must be at top of every PHP file)
464+
if (!defined('ABSPATH')) exit;
465+
466+
// 2. Nonce verification for forms
467+
check_admin_referer('action_name');
468+
wp_verify_nonce($_POST['nonce'], 'action_name');
469+
470+
// 3. Capability checks for privileged actions
471+
if (!current_user_can('manage_options')) return;
472+
473+
// 4. Prepared statements for database
474+
$wpdb->prepare("SELECT * FROM table WHERE id = %d", $id);
475+
476+
// 5. Safe redirect
477+
wp_safe_redirect($url);
478+
exit;
479+
```
480+
481+
**Detection rules needed**:
482+
- Missing ABSPATH check at file start
483+
- Form handlers without nonce verification
484+
- AJAX handlers without capability checks
485+
- Missing `exit;` after redirects
486+
487+
---
488+
383489
## Contact
384490

385491
For questions about this integration or to coordinate between repos:
386492
- php-aegis: https://github.com/hyperpolymath/php-aegis
387493
- sanctify-php: https://github.com/hyperpolymath/sanctify-php
388-
- Integration tested in: wp-sinople-theme
494+
- Integration tested in: wp-sinople-theme, Zotpress
389495

390496
---
391497

392-
*Generated from real-world WordPress semantic theme integration experience (Reports 1 & 2).*
498+
*Generated from real-world WordPress integration experience (Reports 1, 2 & 3).*

‎POSITIONING.md‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
# php-aegis Positioning & Target Audience
2+
3+
## The Problem We Discovered
4+
5+
After integrating php-aegis with multiple WordPress projects (themes and plugins), we found:
6+
7+
> **WordPress already has comprehensive security APIs** (`esc_html()`, `esc_attr()`, `wp_kses()`, etc.) that are deeply integrated with the WordPress ecosystem.
8+
9+
This means php-aegis **should not compete** with WordPress core functions. Instead, it should:
10+
11+
1. **Target non-WordPress PHP applications** where no security API exists
12+
2. **Provide unique capabilities** that WordPress (and other frameworks) lack
13+
14+
---
15+
16+
## Target Audience Matrix
17+
18+
| Audience | php-aegis Value | Recommendation |
19+
|----------|-----------------|----------------|
20+
| **WordPress plugins/themes** | Low | Use WordPress core functions |
21+
| **Laravel applications** | Medium | Use Laravel's helpers, aegis for gaps |
22+
| **Symfony applications** | Medium | Use Twig's escaping, aegis for gaps |
23+
| **Vanilla PHP applications** | **High** | php-aegis is the primary security layer |
24+
| **API-only services** | **High** | No view layer = no framework escaping |
25+
| **CLI tools** | **High** | No framework = aegis fills the gap |
26+
| **Microservices** | **High** | Lightweight, zero-dependency |
27+
| **Semantic Web apps** | **Very High** | TurtleEscaper is unique |
28+
29+
---
30+
31+
## What WordPress Has (Don't Duplicate)
32+
33+
| WordPress Function | Purpose | php-aegis Equivalent |
34+
|--------------------|---------|---------------------|
35+
| `esc_html()` | HTML content escaping | `Sanitizer::html()` |
36+
| `esc_attr()` | HTML attribute escaping | `Sanitizer::attr()` |
37+
| `esc_url()` | URL escaping with protocol check | `Sanitizer::url()` |
38+
| `esc_js()` | JavaScript escaping | `Sanitizer::js()` |
39+
| `wp_kses()` | HTML filtering with allowlist | ❌ Not implemented |
40+
| `wp_kses_post()` | HTML filtering for posts | ❌ Not implemented |
41+
| `sanitize_text_field()` | Text sanitization | `Sanitizer::stripTags()` |
42+
| `is_email()` | Email validation | `Validator::email()` |
43+
| `wp_http_validate_url()` | URL validation + SSL | `Validator::url()` |
44+
| `absint()` | Positive integer | `Validator::int(..., min: 0)` |
45+
46+
**For WordPress projects**: Use WordPress functions. They're more battle-tested, ecosystem-integrated, and maintained by Automattic.
47+
48+
---
49+
50+
## What php-aegis Provides (Unique Value)
51+
52+
These capabilities are **not available** in WordPress, Laravel, or Symfony:
53+
54+
### 1. RDF/Turtle Escaping (Unique)
55+
56+
No other PHP library provides W3C-compliant Turtle escaping.
57+
58+
```php
59+
use PhpAegis\TurtleEscaper;
60+
61+
// Safe for semantic web applications
62+
TurtleEscaper::string($userLabel);
63+
TurtleEscaper::iri($userProvidedUri);
64+
TurtleEscaper::triple($subject, $predicate, $object, 'en');
65+
```
66+
67+
**Use cases**:
68+
- Linked Data platforms
69+
- Knowledge graphs
70+
- Semantic WordPress themes (like wp-sinople-theme)
71+
- SPARQL endpoint integrations
72+
73+
### 2. Security Headers Helper
74+
75+
WordPress doesn't provide header helpers. Frameworks have partial support.
76+
77+
```php
78+
use PhpAegis\Headers;
79+
80+
// One-line security hardening
81+
Headers::secure();
82+
83+
// Or fine-grained control
84+
Headers::contentSecurityPolicy([...]);
85+
Headers::strictTransportSecurity(maxAge: 31536000, preload: true);
86+
Headers::permissionsPolicy([...]);
87+
```
88+
89+
### 3. Extended Validators Not in WordPress
90+
91+
| php-aegis | WordPress Equivalent | Notes |
92+
|-----------|---------------------|-------|
93+
| `Validator::uuid()` | ❌ None | RFC 4122 UUID validation |
94+
| `Validator::ip()` | ❌ None | IPv4/IPv6 validation |
95+
| `Validator::ipv4()` | ❌ None | IPv4 only |
96+
| `Validator::ipv6()` | ❌ None | IPv6 only |
97+
| `Validator::domain()` | ❌ None | RFC 1035 domain validation |
98+
| `Validator::hostname()` | ❌ None | Domain or IP |
99+
| `Validator::slug()` | `sanitize_title()` | WP sanitizes, aegis validates |
100+
| `Validator::semver()` | ❌ None | Semantic versioning |
101+
| `Validator::iso8601()` | ❌ None | ISO 8601 datetime |
102+
| `Validator::hexColor()` | `sanitize_hex_color()` | WP sanitizes, aegis validates |
103+
| `Validator::safeFilename()` | `sanitize_file_name()` | WP sanitizes, aegis validates |
104+
| `Validator::json()` | ❌ None | JSON structure validation |
105+
| `Validator::int(min, max)` | ❌ None | Integer with range |
106+
| `Validator::printable()` | ❌ None | ASCII printable only |
107+
| `Validator::noNullBytes()` | ❌ None | Path traversal prevention |
108+
| `Validator::httpsUrl()` | `wp_http_validate_url()` | WP has `$ssl` param |
109+
110+
### 4. Zero Dependencies
111+
112+
- WordPress functions require WordPress
113+
- Laravel helpers require Laravel
114+
- Symfony components require Symfony
115+
116+
php-aegis works in any PHP 8.1+ environment with no dependencies.
117+
118+
---
119+
120+
## Recommended Usage Patterns
121+
122+
### For WordPress Projects
123+
124+
```php
125+
// DON'T: Use php-aegis for basic escaping
126+
echo \PhpAegis\Sanitizer::html($content); // ❌ Redundant
127+
128+
// DO: Use WordPress functions
129+
echo esc_html($content); // ✅ Preferred
130+
131+
// DO: Use php-aegis for unique capabilities
132+
$headers = new \PhpAegis\Headers();
133+
$headers::secure(); // ✅ WordPress lacks this
134+
135+
// DO: Use php-aegis for semantic web features
136+
echo \PhpAegis\TurtleEscaper::string($label); // ✅ WordPress lacks this
137+
138+
// DO: Use php-aegis for validation gaps
139+
if (!\PhpAegis\Validator::uuid($_GET['id'])) { // ✅ WordPress lacks this
140+
wp_die('Invalid ID');
141+
}
142+
```
143+
144+
### For Laravel Projects
145+
146+
```php
147+
// DON'T: Use php-aegis for Blade escaping
148+
{{ $content }} // Blade auto-escapes, don't use aegis
149+
150+
// DO: Use php-aegis in non-Blade contexts
151+
$uuid = $request->input('resource_id');
152+
if (!Validator::uuid($uuid)) {
153+
abort(400, 'Invalid resource ID');
154+
}
155+
156+
// DO: Use for security headers (Laravel's is less comprehensive)
157+
Headers::secure();
158+
```
159+
160+
### For Vanilla PHP / APIs
161+
162+
```php
163+
// DO: Use php-aegis as your primary security layer
164+
use PhpAegis\{Validator, Sanitizer, Headers};
165+
166+
// Apply security headers
167+
Headers::secure();
168+
169+
// Validate input
170+
if (!Validator::email($_POST['email'])) {
171+
http_response_code(400);
172+
exit(json_encode(['error' => 'Invalid email']));
173+
}
174+
175+
// Sanitize output
176+
echo Sanitizer::html($userContent);
177+
```
178+
179+
---
180+
181+
## Marketing Positioning
182+
183+
### Tagline Options
184+
185+
1. **"Security for the rest of PHP"** - Emphasizes non-framework use
186+
2. **"Where frameworks fear to tread"** - Emphasizes unique capabilities
187+
3. **"Semantic web security, done right"** - Emphasizes Turtle escaping niche
188+
189+
### README Messaging
190+
191+
```
192+
php-aegis is a zero-dependency PHP security toolkit for:
193+
- API services without view layers
194+
- CLI tools and microservices
195+
- Semantic web applications (RDF/Turtle)
196+
- Any PHP app without a framework
197+
198+
For WordPress, use WordPress core functions.
199+
For Laravel/Symfony, use framework helpers + aegis for gaps.
200+
```
201+
202+
---
203+
204+
## Roadmap Implications
205+
206+
Based on this positioning, prioritize:
207+
208+
1. **RDF/Turtle escaping** - Already done, unique differentiator
209+
2. **Security headers** - Already done, fills framework gaps
210+
3. **Extended validators** - Focus on what WordPress lacks (UUID, IP, semver, etc.)
211+
4. **IndieWeb security** - Micropub, IndieAuth, Webmention (unique niche)
212+
5. **Rate limiting** - File-based, no Redis required
213+
214+
De-prioritize:
215+
- HTML/attribute escaping improvements (frameworks do this well)
216+
- WordPress adapter (WordPress users should use WordPress functions)
217+
218+
---
219+
220+
## Success Metrics
221+
222+
| Metric | Target Audience Indicator |
223+
|--------|--------------------------|
224+
| Downloads from API/microservice projects | Primary audience |
225+
| Usage in semantic web tools | Niche but high-value |
226+
| Issues asking about WordPress | Signals need for better docs |
227+
| PRs adding framework adapters | Community wants integration |
228+
229+
---
230+
231+
*This positioning reflects insights from WordPress theme (wp-sinople-theme) and plugin (Zotpress) integration attempts.*

‎README.adoc‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,22 @@ image:https://img.shields.io/badge/RSR-Compliant-gold.svg[RSR Compliant]
1414

1515
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.
1616

17+
=== Best For
18+
19+
* **API services** without view layers
20+
* **CLI tools** and microservices
21+
* **Semantic web applications** (RDF/Turtle escaping - unique to php-aegis)
22+
* **Vanilla PHP** applications without frameworks
23+
* **Framework gaps** - validation/features that WordPress/Laravel/Symfony lack
24+
25+
=== Not Needed For
26+
27+
* **WordPress plugins/themes** - Use WordPress core functions (`esc_html()`, `esc_attr()`, etc.)
28+
* **Laravel views** - Use Blade's auto-escaping
29+
* **Symfony/Twig** - Use Twig's escaping
30+
31+
See link:POSITIONING.md[POSITIONING.md] for detailed guidance.
32+
1733
=== Key Features
1834

1935
* **Input Validation** - Strict validation for emails, URLs, IPs, UUIDs, and more

0 commit comments

Comments
 (0)