initial commit

native/wordpress/maple-icons-wp/SECURITY.md

@@ -0,0 +1,621 @@
+# SECURITY.md — Maple Local Fonts Security Requirements
+
+## Overview
+
+This document covers all security requirements for the Maple Local Fonts plugin. Reference this when writing ANY PHP code.
+
+---
+
+## ABSPATH Check (Every PHP File)
+
+Every PHP file MUST start with this check. No exceptions.
+
+```php
+<?php
+if (!defined('ABSPATH')) {
+    exit;
+}
+```
+
+---
+
+## Silence is Golden Files
+
+Create `index.php` in EVERY directory:
+
+```php
+<?php
+// Silence is golden.
+if (!defined('ABSPATH')) {
+    exit;
+}
+```
+
+**Required locations:**
+- `/maple-local-fonts/index.php`
+- `/maple-local-fonts/includes/index.php`
+- `/maple-local-fonts/assets/index.php`
+- `/maple-local-fonts/languages/index.php`
+
+---
+
+## OWASP Compliance
+
+### A1 - Injection Prevention
+
+**SQL Injection:**
+```php
+// NEVER do this
+$wpdb->query("SELECT * FROM table WHERE id = " . $_POST['id']);
+
+// ALWAYS do this
+$wpdb->get_results($wpdb->prepare(
+    "SELECT * FROM %i WHERE id = %d",
+    $table_name,
+    absint($_POST['id'])
+));
+```
+
+**Note:** This plugin should rarely need direct SQL. Use WordPress APIs (`get_posts`, `wp_insert_post`, etc.) which handle escaping internally.
+
+### A2 - Authentication
+
+All admin actions require capability check:
+
+```php
+if (!current_user_can('edit_theme_options')) {
+    wp_die('Unauthorized', 'Error', ['response' => 403]);
+}
+```
+
+### A3 - Sensitive Data
+
+- No API keys (Google Fonts CSS2 API is public)
+- No user credentials stored
+- No PII collected
+
+### A5 - Broken Access Control
+
+**Order of checks for ALL AJAX handlers:**
+
+```php
+public function handle_ajax_action() {
+    // 1. Nonce verification FIRST
+    if (!check_ajax_referer('mlf_action_name', 'nonce', false)) {
+        wp_send_json_error(['message' => 'Security check failed'], 403);
+    }
+
+    // 2. Capability check SECOND
+    if (!current_user_can('edit_theme_options')) {
+        wp_send_json_error(['message' => 'Unauthorized'], 403);
+    }
+
+    // 3. Input validation THIRD
+    // ... validate all inputs ...
+
+    // 4. Process request
+    // ... actual logic ...
+}
+```
+
+### A7 - Cross-Site Scripting (XSS)
+
+**Escape ALL output:**
+
+```php
+// HTML content
+echo esc_html($font_name);
+
+// HTML attributes
+echo '<input value="' . esc_attr($font_name) . '">';
+
+// URLs
+echo '<a href="' . esc_url($url) . '">';
+
+// JavaScript data
+wp_localize_script('mlf-admin', 'mlfData', [
+    'fontName' => esc_js($font_name),  // Or let wp_localize_script handle it
+]);
+
+// Translatable strings with variables
+printf(
+    esc_html__('Installed: %s', 'maple-local-fonts'),
+    esc_html($font_name)
+);
+```
+
+**Never trust input for output:**
+```php
+// WRONG - XSS vulnerability
+echo '<div>' . $_POST['font_name'] . '</div>';
+
+// RIGHT - sanitize input, escape output
+$font_name = sanitize_text_field($_POST['font_name']);
+echo '<div>' . esc_html($font_name) . '</div>';
+```
+
+### A8 - Insecure Deserialization
+
+```php
+// NEVER use unserialize() on external data
+$data = unserialize($_POST['data']); // DANGEROUS
+
+// Use JSON instead
+$data = json_decode(sanitize_text_field($_POST['data']), true);
+if (json_last_error() !== JSON_ERROR_NONE) {
+    wp_send_json_error(['message' => 'Invalid data format']);
+}
+```
+
+### A9 - Vulnerable Components
+
+- No external PHP libraries
+- Use only WordPress core functions
+- Keep dependencies to zero
+
+---
+
+## Nonce Implementation
+
+### Creating Nonces
+
+**In admin page form:**
+```php
+wp_nonce_field('mlf_download_font', 'mlf_nonce');
+```
+
+**For AJAX (via wp_localize_script):**
+```php
+wp_localize_script('mlf-admin', 'mlfData', [
+    'ajaxUrl' => admin_url('admin-ajax.php'),
+    'nonce'   => wp_create_nonce('mlf_download_font'),
+]);
+```
+
+### Verifying Nonces
+
+**AJAX handler:**
+```php
+// Returns false on failure, doesn't die (we handle response ourselves)
+if (!check_ajax_referer('mlf_download_font', 'nonce', false)) {
+    wp_send_json_error(['message' => 'Security check failed'], 403);
+}
+```
+
+**Form submission:**
+```php
+if (!wp_verify_nonce($_POST['mlf_nonce'], 'mlf_download_font')) {
+    wp_die('Security check failed');
+}
+```
+
+### Nonce Names
+
+Use consistent, descriptive nonce action names:
+
+| Action | Nonce Name |
+|--------|------------|
+| Download font | `mlf_download_font` |
+| Delete font | `mlf_delete_font` |
+| Update settings | `mlf_update_settings` |
+
+---
+
+## Input Validation
+
+### Font Name Validation
+
+```php
+$font_name = isset($_POST['font_name']) ? sanitize_text_field($_POST['font_name']) : '';
+
+// Strict allowlist pattern - alphanumeric, spaces, hyphens only
+if (!preg_match('/^[a-zA-Z0-9\s\-]+$/', $font_name)) {
+    wp_send_json_error(['message' => 'Invalid font name: only letters, numbers, spaces, and hyphens allowed']);
+}
+
+// Length limit
+if (strlen($font_name) > 100) {
+    wp_send_json_error(['message' => 'Font name too long']);
+}
+
+// Not empty
+if (empty($font_name)) {
+    wp_send_json_error(['message' => 'Font name required']);
+}
+```
+
+### Weight Validation
+
+```php
+$weights = isset($_POST['weights']) ? (array) $_POST['weights'] : [];
+
+// Convert to integers
+$weights = array_map('absint', $weights);
+
+// Strict allowlist
+$allowed_weights = [100, 200, 300, 400, 500, 600, 700, 800, 900];
+$weights = array_intersect($weights, $allowed_weights);
+
+// Must have at least one
+if (empty($weights)) {
+    wp_send_json_error(['message' => 'At least one weight required']);
+}
+```
+
+### Style Validation
+
+```php
+$styles = isset($_POST['styles']) ? (array) $_POST['styles'] : [];
+
+// Strict allowlist - only these two values ever
+$allowed_styles = ['normal', 'italic'];
+$styles = array_filter($styles, function($style) use ($allowed_styles) {
+    return in_array($style, $allowed_styles, true);
+});
+
+// Must have at least one
+if (empty($styles)) {
+    wp_send_json_error(['message' => 'At least one style required']);
+}
+```
+
+### Font Family ID Validation (for delete)
+
+```php
+$font_id = isset($_POST['font_id']) ? absint($_POST['font_id']) : 0;
+
+if ($font_id < 1) {
+    wp_send_json_error(['message' => 'Invalid font ID']);
+}
+
+// Verify it exists and is a font family
+$font = get_post($font_id);
+if (!$font || $font->post_type !== 'wp_font_family') {
+    wp_send_json_error(['message' => 'Font not found']);
+}
+
+// Verify it's one we imported (not a theme font)
+if (get_post_meta($font_id, '_mlf_imported', true) !== '1') {
+    wp_send_json_error(['message' => 'Cannot delete theme fonts']);
+}
+```
+
+---
+
+## File Operation Security
+
+### Path Traversal Prevention
+
+```php
+/**
+ * Validate that a path is within the WordPress fonts directory.
+ * Prevents path traversal attacks.
+ *
+ * @param string $path Full path to validate
+ * @return bool True if path is safe, false otherwise
+ */
+function mlf_validate_font_path($path) {
+    $font_dir = wp_get_font_dir();
+    $fonts_path = wp_normalize_path(trailingslashit($font_dir['path']));
+    
+    // Resolve to real path (handles ../ etc)
+    $real_path = realpath($path);
+    
+    // If realpath fails, file doesn't exist yet - validate the directory
+    if ($real_path === false) {
+        $dir = dirname($path);
+        $real_dir = realpath($dir);
+        if ($real_dir === false) {
+            return false;
+        }
+        $real_path = wp_normalize_path($real_dir . '/' . basename($path));
+    } else {
+        $real_path = wp_normalize_path($real_path);
+    }
+    
+    // Must be within fonts directory
+    return strpos($real_path, $fonts_path) === 0;
+}
+```
+
+### Filename Sanitization
+
+```php
+/**
+ * Sanitize and validate a font filename.
+ *
+ * @param string $filename The filename to validate
+ * @return string|false Sanitized filename or false if invalid
+ */
+function mlf_sanitize_font_filename($filename) {
+    // WordPress sanitization first
+    $filename = sanitize_file_name($filename);
+    
+    // Must have .woff2 extension
+    if (pathinfo($filename, PATHINFO_EXTENSION) !== 'woff2') {
+        return false;
+    }
+    
+    // No path components
+    if ($filename !== basename($filename)) {
+        return false;
+    }
+    
+    // Reasonable length
+    if (strlen($filename) > 200) {
+        return false;
+    }
+    
+    return $filename;
+}
+```
+
+### Safe File Writing
+
+```php
+/**
+ * Safely write a font file to the fonts directory.
+ *
+ * @param string $filename Sanitized filename
+ * @param string $content File content
+ * @return string|WP_Error File path on success, WP_Error on failure
+ */
+function mlf_write_font_file($filename, $content) {
+    // Validate filename
+    $safe_filename = mlf_sanitize_font_filename($filename);
+    if ($safe_filename === false) {
+        return new WP_Error('invalid_filename', 'Invalid filename');
+    }
+    
+    // Get fonts directory
+    $font_dir = wp_get_font_dir();
+    $destination = trailingslashit($font_dir['path']) . $safe_filename;
+    
+    // Validate path
+    if (!mlf_validate_font_path($destination)) {
+        return new WP_Error('invalid_path', 'Invalid file path');
+    }
+    
+    // Ensure directory exists
+    if (!wp_mkdir_p($font_dir['path'])) {
+        return new WP_Error('mkdir_failed', 'Could not create fonts directory');
+    }
+    
+    // Write file
+    global $wp_filesystem;
+    if (empty($wp_filesystem)) {
+        require_once ABSPATH . 'wp-admin/includes/file.php';
+        WP_Filesystem();
+    }
+    
+    if (!$wp_filesystem->put_contents($destination, $content, FS_CHMOD_FILE)) {
+        return new WP_Error('write_failed', 'Could not write font file');
+    }
+    
+    return $destination;
+}
+```
+
+### Safe File Deletion
+
+```php
+/**
+ * Safely delete a font file.
+ *
+ * @param string $path Full path to the file
+ * @return bool True on success, false on failure
+ */
+function mlf_delete_font_file($path) {
+    // Validate path is within fonts directory
+    if (!mlf_validate_font_path($path)) {
+        return false;
+    }
+    
+    // Must be a .woff2 file
+    if (pathinfo($path, PATHINFO_EXTENSION) !== 'woff2') {
+        return false;
+    }
+    
+    // File must exist
+    if (!file_exists($path)) {
+        return true; // Already gone, that's fine
+    }
+    
+    return wp_delete_file($path);
+}
+```
+
+---
+
+## HTTP Request Security
+
+### Outbound Requests (Google Fonts)
+
+```php
+$response = wp_remote_get($url, [
+    'timeout'    => 15,
+    'sslverify'  => true,  // Always verify SSL
+    'user-agent' => 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
+]);
+
+// Check for errors
+if (is_wp_error($response)) {
+    // Log error, return gracefully
+    error_log('MLF: Google Fonts request failed - ' . $response->get_error_message());
+    return new WP_Error('request_failed', 'Could not connect to Google Fonts');
+}
+
+// Check HTTP status
+$status = wp_remote_retrieve_response_code($response);
+if ($status !== 200) {
+    return new WP_Error('http_error', 'Google Fonts returned status ' . $status);
+}
+
+// Get body
+$body = wp_remote_retrieve_body($response);
+if (empty($body)) {
+    return new WP_Error('empty_response', 'Empty response from Google Fonts');
+}
+```
+
+### URL Validation (Google Fonts only)
+
+```php
+/**
+ * Validate that a URL is a legitimate Google Fonts URL.
+ *
+ * @param string $url URL to validate
+ * @return bool True if valid Google Fonts URL
+ */
+function mlf_is_valid_google_fonts_url($url) {
+    $parsed = wp_parse_url($url);
+    
+    if (!$parsed || !isset($parsed['host'])) {
+        return false;
+    }
+    
+    // Only allow Google Fonts domains
+    $allowed_hosts = [
+        'fonts.googleapis.com',
+        'fonts.gstatic.com',
+    ];
+    
+    return in_array($parsed['host'], $allowed_hosts, true);
+}
+```
+
+---
+
+## AJAX Handler Complete Template
+
+```php
+<?php
+if (!defined('ABSPATH')) {
+    exit;
+}
+
+class MLF_Ajax_Handler {
+
+    public function __construct() {
+        add_action('wp_ajax_mlf_download_font', [$this, 'handle_download']);
+        add_action('wp_ajax_mlf_delete_font', [$this, 'handle_delete']);
+        // NEVER add wp_ajax_nopriv_ - admin only functionality
+    }
+
+    /**
+     * Handle font download AJAX request.
+     */
+    public function handle_download() {
+        // 1. NONCE CHECK
+        if (!check_ajax_referer('mlf_download_font', 'nonce', false)) {
+            wp_send_json_error(['message' => 'Security check failed'], 403);
+        }
+
+        // 2. CAPABILITY CHECK
+        if (!current_user_can('edit_theme_options')) {
+            wp_send_json_error(['message' => 'Unauthorized'], 403);
+        }
+
+        // 3. INPUT VALIDATION
+        $font_name = isset($_POST['font_name']) ? sanitize_text_field($_POST['font_name']) : '';
+        if (empty($font_name) || !preg_match('/^[a-zA-Z0-9\s\-]+$/', $font_name) || strlen($font_name) > 100) {
+            wp_send_json_error(['message' => 'Invalid font name']);
+        }
+
+        $weights = isset($_POST['weights']) ? array_map('absint', (array) $_POST['weights']) : [];
+        $weights = array_intersect($weights, [100, 200, 300, 400, 500, 600, 700, 800, 900]);
+        if (empty($weights)) {
+            wp_send_json_error(['message' => 'At least one weight required']);
+        }
+
+        $styles = isset($_POST['styles']) ? (array) $_POST['styles'] : [];
+        $styles = array_intersect($styles, ['normal', 'italic']);
+        if (empty($styles)) {
+            wp_send_json_error(['message' => 'At least one style required']);
+        }
+
+        // 4. PROCESS REQUEST
+        try {
+            $downloader = new MLF_Font_Downloader();
+            $result = $downloader->download($font_name, $weights, $styles);
+            
+            if (is_wp_error($result)) {
+                wp_send_json_error(['message' => $result->get_error_message()]);
+            }
+            
+            wp_send_json_success([
+                'message' => sprintf('Successfully installed %s', esc_html($font_name)),
+                'font_id' => $result,
+            ]);
+        } catch (Exception $e) {
+            error_log('MLF Download Error: ' . $e->getMessage());
+            wp_send_json_error(['message' => 'An unexpected error occurred']);
+        }
+    }
+
+    /**
+     * Handle font deletion AJAX request.
+     */
+    public function handle_delete() {
+        // 1. NONCE CHECK
+        if (!check_ajax_referer('mlf_delete_font', 'nonce', false)) {
+            wp_send_json_error(['message' => 'Security check failed'], 403);
+        }
+
+        // 2. CAPABILITY CHECK
+        if (!current_user_can('edit_theme_options')) {
+            wp_send_json_error(['message' => 'Unauthorized'], 403);
+        }
+
+        // 3. INPUT VALIDATION
+        $font_id = isset($_POST['font_id']) ? absint($_POST['font_id']) : 0;
+        if ($font_id < 1) {
+            wp_send_json_error(['message' => 'Invalid font ID']);
+        }
+
+        // Verify font exists and is ours
+        $font = get_post($font_id);
+        if (!$font || $font->post_type !== 'wp_font_family') {
+            wp_send_json_error(['message' => 'Font not found']);
+        }
+        if (get_post_meta($font_id, '_mlf_imported', true) !== '1') {
+            wp_send_json_error(['message' => 'Cannot delete theme fonts']);
+        }
+
+        // 4. PROCESS REQUEST
+        try {
+            $registry = new MLF_Font_Registry();
+            $result = $registry->delete_font($font_id);
+            
+            if (is_wp_error($result)) {
+                wp_send_json_error(['message' => $result->get_error_message()]);
+            }
+            
+            wp_send_json_success(['message' => 'Font deleted successfully']);
+        } catch (Exception $e) {
+            error_log('MLF Delete Error: ' . $e->getMessage());
+            wp_send_json_error(['message' => 'An unexpected error occurred']);
+        }
+    }
+}
+```
+
+---
+
+## Security Checklist
+
+Before committing any code:
+
+- [ ] ABSPATH check at top of every PHP file
+- [ ] index.php exists in every directory
+- [ ] All AJAX handlers verify nonce first
+- [ ] All AJAX handlers check capability second
+- [ ] All user input sanitized with appropriate function
+- [ ] All user input validated against allowlists where applicable
+- [ ] All output escaped with appropriate function
+- [ ] File paths validated to prevent traversal
+- [ ] No direct SQL queries (use WordPress APIs)
+- [ ] No `unserialize()` on user input
+- [ ] No `eval()` or similar dynamic execution
+- [ ] External URLs validated before use
+- [ ] Error messages don't expose sensitive info