📦 deps(thirdparty): update snapshots

2026-07-18 00:02:59 +00:00
parent 82f7c6e56a
commit 47ce7f78dc
1446 changed files with 141041 additions and 6442 deletions
@@ -0,0 +1,100 @@
+# WP Guard — Security Reference
+
+## Contents
+
+- Escaping: context → function
+- Sanitization: input type → function
+- The unslash-then-sanitize order
+- Nonce + capability lifecycle
+- REST API permissions
+- $wpdb->prepare details
+- File uploads
+- Common AI-generated violations
+
+## Escaping: context → function
+
+Escape at the moment of output, with the function matching the destination context:
+
+| Output context | Function |
+|---|---|
+| HTML body text | `esc_html()` |
+| HTML attribute | `esc_attr()` |
+| URL (href/src/action) | `esc_url()` (display) / `esc_url_raw()` (storage/redirects) |
+| Data for inline JS | `wp_json_encode()` + `wp_add_inline_script()`; `esc_js()` is legacy — single-quoted strings in inline attributes only |
+| Textarea content | `esc_textarea()` |
+| Rich/user HTML | `wp_kses_post()` or `wp_kses()` with an explicit allowlist |
+| Translation + output | `esc_html__()`, `esc_html_e()`, `esc_attr__()` — escape and translate in one call |
+
+Trust nothing at output time — not even your own stored options; another plugin or a compromised import may have written them. "Escaped on save" is not a defense.
+
+## Sanitization: input type → function
+
+| Expected input | Function |
+|---|---|
+| Plain text line | `sanitize_text_field()` |
+| Multiline text | `sanitize_textarea_field()` |
+| Integer / ID | `absint()` or `intval()` |
+| Slug/key | `sanitize_key()` / `sanitize_title()` |
+| Email | `sanitize_email()` + `is_email()` check |
+| URL | `esc_url_raw()` |
+| HTML payload | `wp_kses_post()` / `wp_kses()` |
+| File name | `sanitize_file_name()` |
+| Anything enumerable | strict allowlist comparison (`in_array( $v, $allowed, true )`) |
+
+## The unslash-then-sanitize order
+
+WordPress adds slashes to superglobals. The correct pipeline is always:
+
+```php
+$status = sanitize_key( wp_unslash( $_POST['ncs_status'] ?? '' ) );
+```
+
+`wp_unslash()` first, sanitizer second. Sanitizing slashed data corrupts legitimate input and hides bugs.
+
+## Nonce + capability lifecycle
+
+Both checks, always, for any state change. They answer different questions:
+
+- `current_user_can( 'manage_options' )` — is this user *allowed* to do this? (authorization)
+- `check_admin_referer( 'ncs_save_settings' )` / `check_ajax_referer( 'ncs_action', 'nonce' )` — did this request *intend* this action? (CSRF protection)
+
+A nonce without a capability check lets any logged-in subscriber fire admin actions. A capability check without a nonce leaves CSRF open. AI-generated handlers routinely have one, the other, or neither — verify both exist on every `admin_post_*`, `wp_ajax_*`, and form handler.
+
+Generate nonces with `wp_nonce_field()` (forms) or `wp_create_nonce()` (AJAX/REST payloads). Nonces are per-user and time-limited; do not cache pages containing them.
+
+## REST API permissions
+
+- Every route registers a real `permission_callback`. `__return_true` is acceptable only for genuinely public read-only data — never for writes.
+- Validate and sanitize via the route's `args` schema (`validate_callback`, `sanitize_callback`) instead of manual checks inside the handler.
+- Cookie-authenticated REST requests require the `X-WP-Nonce` header (`wp_rest` nonce); custom auth schemes must fail closed.
+
+## $wpdb->prepare details
+
+```php
+$row = $wpdb->get_row(
+	$wpdb->prepare(
+		"SELECT * FROM {$wpdb->prefix}ncs_log WHERE user_id = %d AND event = %s",
+		$user_id,
+		$event
+	)
+);
+```
+
+- Placeholders: `%s`, `%d`, `%f`; `%i` for table/column identifiers (WP ≥ 6.2).
+- `IN ( … )` lists: build placeholders dynamically — `implode( ',', array_fill( 0, count( $ids ), '%d' ) )` — then prepare with the spread array.
+- LIKE queries: `$wpdb->esc_like()` the term *before* passing it as a `%s` parameter.
+- Never interpolate `$_REQUEST` data anywhere near SQL, even "validated" data.
+- Prefer `WP_Query`, `get_posts()`, meta/term/option APIs when they can express the query — they bring caching for free.
+
+## File uploads
+
+Use `wp_handle_upload()` / media APIs — never move `$_FILES` manually. Validate type with `wp_check_filetype_and_ext()` against an allowlist; never trust the client MIME. Store outside executable paths; WordPress handles this when you use its APIs.
+
+## Common AI-generated violations
+
+1. `echo '<div>' . $title . '</div>';` — unescaped output (Rule 1). Published research: XSS appears in 86% of AI generations tested on XSS-prone tasks (see [sources.md](sources.md)).
+2. `wp_ajax_` handler with neither `check_ajax_referer()` nor `current_user_can()` (Rule 3).
+3. `"SELECT * FROM {$wpdb->posts} WHERE post_title = '$title'"` — interpolated SQL (Rule 4).
+4. `permission_callback => '__return_true'` on a POST route (Rule 3).
+5. `curl_init()` inside a plugin (Rule 5) — breaks proxies, blocks, and filters that `wp_remote_*` honors.
+6. Echoed `<script>` blocks with interpolated PHP — combines Rules 1 and 5; use `wp_enqueue_script()` + `wp_add_inline_script()`/`wp_localize_script()`.