This commit is contained in:
Javier Casares 2026-06-08 12:31:51 +00:00
commit 7dd3eeaa8a
97 changed files with 4912 additions and 1581 deletions

1
.phpunit.result.cache Normal file
View file

@ -0,0 +1 @@
{"version":1,"defects":[],"times":{"Test_Plugin_Headers::plugin_file_exists":0.002,"Test_Plugin_Headers::plugin_name_header_is_present":0.001,"Test_Plugin_Headers::version_header_is_present_and_valid":0,"Test_Plugin_Headers::requires_at_least_header_is_present":0,"Test_Plugin_Headers::requires_php_header_is_present":0,"Test_Plugin_Headers::text_domain_matches_plugin_slug":0,"Test_Plugin_Headers::license_header_is_gpl3":0,"Test_Plugin_Headers::author_header_is_present":0,"Test_Plugin_Headers::readme_file_exists":0,"Test_Plugin_Headers::readme_has_stable_tag":0,"Test_Plugin_Headers::readme_has_requires_at_least":0,"Test_Plugin_Headers::readme_has_requires_php":0,"Test_Plugin_Headers::readme_has_license":0,"Test_Plugin_Headers::stable_tag_matches_plugin_version":0,"Test_Plugin_Headers::requires_at_least_is_consistent":0,"Test_Plugin_Headers::requires_php_is_consistent":0,"Test_Plugin_Headers::license_is_consistent":0}}

59
CHANGELOG.md Normal file
View file

@ -0,0 +1,59 @@
# Changelog
All notable changes to Documentation Markdown are documented in this file.
For the WordPress.org–formatted changelog, see [`changelog.txt`](changelog.txt).
## [1.1.1] — 2026-06-08
### Security
- CommonMark: disabled raw HTML passthrough (`html_input: strip`, `allow_unsafe_links: false`) — prevents stored XSS if an upstream repository is compromised
- Plugin settings option now stored with `autoload = false` — encrypted GitHub token no longer loaded on every WordPress request
- Replaced `serialize()` with `wp_json_encode()` in updater HMAC cache signature (eliminates object-injection risk surface)
- Added strict base64 length validation in `robotstxt_docmd_decrypt_token()` before IV extraction
- Added `base64_decode()` strict return-value check in `robotstxt_docmd_get_file_content()`
### Fixed
- Admin notices now display results for all operations (mapping created/updated/deleted, sync complete, error messages); previously only "Settings saved" appeared
- `wp_update_post()` return value now checked during sync — silent failures previously reported as success
- Wrong textdomain `'robotstxt-smtp'` in updater class corrected to `'robotstxt-documentation-markdown'`
### Changed
- `robotstxt-updater.php` renamed to `class-robotstxt-updater.php` (WordPress file-naming convention)
- `Requires PHP` header corrected to `8.0` (real minimum confirmed by PHPCompatibility scan — union types, `str_starts_with()`, `str_contains()`, `mixed` type are the binding constraints; no 8.1/8.2-specific features used)
### Developer / Infrastructure
- Added `composer.json` with full `require-dev` tooling (PHPCS, PHPStan 2.x, PHPUnit 9.6, PHPCompatibility 10.0.0-alpha2, wp-compat, yoast/phpunit-polyfills)
- Added `phpstan.neon` (level 9), `.phpcs.xml` (WordPress standards), `bin/deploy.sh`, `phpunit.xml.dist`
- 17 PHPUnit plugin header tests added (`tests/PluginHeadersTest.php`)
- Added `docs/known-issues.md` and `docs/db-migrations.md`
- `class-robotstxt-updater.php`: PHPCS 0 errors, PHPStan level 9 0 errors
- PHPCompatibility updated to 10.0.0-alpha2 (PHP 8.x feature detection)
## [1.1.0] — 2026-03-28
### Security
- Patched CVE-2026-33347 and CVE-2026-30838 (league/commonmark updated to 2.8.2)
### Changed
- Access level changed from `manage_options` (administrator) to `edit_pages` (editor)
### Fixed
- PHPStan level 9 compliance: zero errors across all plugin files
- `target_order` (menu_order) field now saved and applied end-to-end
- Type-safety improvements for all WordPress API returns
- Token decryption `false` return handled correctly
- Uninstall data cleanup narrows mixed option return before array access
## [1.0.0] — 2026-01-26
### Added
- Initial release: GitHub → WordPress Markdown sync
- Encrypted GitHub token storage (AES-256-CBC)
- Custom Post Type `robotstxt_map` for mapping management
- Automatic cron sync (hourly, twice daily, daily)
- Manual on-demand sync via admin interface
- Markdown to HTML via CommonMark (league/commonmark)
- Multi-repository support
- Debug tools (visible when `WP_DEBUG` enabled)
- Full i18n support (es_ES bundled)

View file

@ -1,5 +1,58 @@
== Changelog ==
= 1.1.1 =
_Release date: 2026-06-08_
**Highlights**
* Security hardening: CommonMark raw HTML passthrough disabled, encrypted token no longer autoloaded, HMAC now uses `wp_json_encode()` instead of `serialize()`
* Bug fix: admin notices now visible for all operations (sync, create, update, delete, errors)
* Infrastructure: full dev tooling added (PHPCS, PHPStan, PHPUnit, deploy script)
* Real PHP minimum corrected to 8.0 (confirmed by PHPCompatibility 10.x scan)
**Security**
* CommonMark: disabled raw HTML passthrough (`html_input: strip`, `allow_unsafe_links: false`) — prevents stored XSS if an upstream repository is compromised
* Settings option now stored with `autoload = false` — encrypted GitHub token no longer loaded on every WordPress request (defense in depth)
* Replaced `serialize()` with `wp_json_encode()` in updater HMAC cache (eliminates PHPCS object-injection warning)
* Added strict base64 length validation before IV extraction in `robotstxt_docmd_decrypt_token()`
* Added `base64_decode()` strict return-value check in `robotstxt_docmd_get_file_content()`
**Fixed**
* Admin notices now display results for all operations: mapping created, mapping updated, mapping deleted, sync complete, and error messages — previously only "Settings saved" was shown
* `wp_update_post()` return value now checked during sync — silent post-update failures were previously reported as success
* Wrong textdomain `'robotstxt-smtp'` in updater class corrected to `'robotstxt-documentation-markdown'`
**Changed**
* `robotstxt-updater.php` renamed to `class-robotstxt-updater.php` (WordPress file-naming convention)
* Minimum PHP version header corrected from 8.2 to 8.0 (real minimum confirmed by PHPCompatibility 10.0.0-alpha2 scan — union types, `str_starts_with()`, `str_contains()`, and `mixed` type are the binding constraints)
**Developer**
* Added `composer.json` with full require-dev tooling (PHPCS, PHPStan 2.x, PHPUnit 9.6, PHPCompatibility 10.0.0-alpha2, wp-compat, yoast/phpunit-polyfills)
* Added `phpstan.neon` (level 9), `.phpcs.xml` (WordPress-Core/Docs/Extra), `bin/deploy.sh`, `phpunit.xml.dist`
* PHPUnit: 17 plugin header tests added (`tests/PluginHeadersTest.php`)
* Added `docs/known-issues.md` and `docs/db-migrations.md`
* `class-robotstxt-updater.php`: PHPCS 0 errors, PHPStan level 9 0 errors (full compliance)
**Compatibility**
* WordPress: 6.7 - 7.1
* PHP: 8.0 - 8.5
* MariaDB: 11.4 or newer
**Tests**
* PHP Coding Standards: PHPCS 3.x with WordPress-Core, WordPress-Docs, WordPress-Extra — 0 errors, 0 warnings
* WordPress Coding Standards: WPCS 3.3.0
* PHPStan: level 9, 0 errors (szepeviktor/phpstan-wordpress 2.0.3)
* PHPCompatibility: 10.0.0-alpha2 — PHP 8.0-8.5 validated
* PHPUnit: 17/17 tests pass (plugin header tests)
* Manual testing: WordPress 7.0, 7.1
= 1.1.0 =
_Release date: 2026-03-28_

465
class-robotstxt-updater.php Normal file
View file

@ -0,0 +1,465 @@
<?php
/**
* Generic JSON-based updater for ROBOTSTXT plugins.
*
* This file is designed to be copied to any ROBOTSTXT plugin.
* It auto-configures itself by reading the plugin headers.
*
* @package ROBOTSTXT
* @since 1.0.0
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
if ( ! class_exists( 'Robotstxt_Updater' ) ) {
/**
* Class Robotstxt_Updater
*
* Generic updater that works with any plugin.
* Reads plugin headers and constructs update URL automatically.
*
* @since 1.0.0
*/
class Robotstxt_Updater {
/**
* Plugin file path.
*
* @since 1.0.0
* @var string
*/
private string $plugin_file_path;
/**
* Plugin basename (e.g., 'my-plugin/my-plugin.php').
*
* @since 1.0.0
* @var string
*/
private string $plugin_basename;
/**
* Plugin slug (directory name).
*
* @since 1.0.0
* @var string
*/
private string $plugin_slug;
/**
* Remote JSON URL.
*
* @since 1.0.0
* @var string
*/
private string $json_url;
/**
* Cache key.
*
* @since 1.0.0
* @var string
*/
private string $cache_key;
/**
* Plugin headers.
*
* @since 1.0.0
* @var array<string, mixed>
*/
private array $plugin_data;
/**
* Initialize the updater.
*
* Usage in your main plugin file:
* require_once __DIR__ . '/class-robotstxt-updater.php';
* Robotstxt_Updater::init( __FILE__ );
*
* @since 1.0.0
*
* @param string $plugin_file_path Absolute path to the main plugin file.
* @return void
*/
public static function init( string $plugin_file_path ): void {
$instance = new self( $plugin_file_path );
$instance->register();
}
/**
* Constructor.
*
* @since 1.0.0
*
* @param string $plugin_file_path Absolute path to the main plugin file.
*/
private function __construct( string $plugin_file_path ) {
$this->plugin_file_path = $plugin_file_path;
$this->plugin_basename = plugin_basename( $plugin_file_path );
$this->plugin_slug = dirname( $this->plugin_basename );
$this->plugin_data = $this->get_plugin_data();
$this->json_url = $this->build_json_url();
$this->cache_key = 'robotstxt_updater_' . md5( $this->plugin_basename );
}
/**
* Register WordPress hooks.
*
* @since 1.0.0
*
* @return void
*/
private function register(): void {
add_filter( 'pre_set_site_transient_update_plugins', array( $this, 'inject_update_info' ) );
add_filter( 'plugins_api', array( $this, 'provide_plugin_details' ), 10, 3 );
add_action( 'admin_init', array( $this, 'handle_cache_clear' ) );
add_action( 'robotstxt_updater_clear_cache', array( $this, 'clear_cache' ) );
}
/**
* Get plugin headers.
*
* @since 1.0.0
*
* @return array<string, mixed> Plugin data.
*/
private function get_plugin_data(): array {
if ( ! function_exists( 'get_plugin_data' ) ) {
require_once ABSPATH . 'wp-admin/includes/plugin.php';
}
return get_plugin_data( $this->plugin_file_path, false, false );
}
/**
* Build JSON URL from plugin headers.
*
* Tries to use "Gitea Plugin URI" header to construct the URL.
* Falls back to Plugin URI if Gitea URI is not available.
*
* @since 1.0.0
*
* @return string JSON URL.
*/
private function build_json_url(): string {
$gitea_uri = isset( $this->plugin_data['Gitea Plugin URI'] ) && is_string( $this->plugin_data['Gitea Plugin URI'] )
? $this->plugin_data['Gitea Plugin URI']
: '';
if ( '' !== $gitea_uri ) {
if ( str_starts_with( $gitea_uri, 'http' ) ) {
return rtrim( $gitea_uri, '/' ) . '/raw/branch/main/update.json';
}
if ( preg_match( '#^[^/]+/[^/]+$#', $gitea_uri ) ) {
return 'https://git.robotstxt.es/' . $gitea_uri . '/raw/branch/main/update.json';
}
}
$plugin_uri = isset( $this->plugin_data['PluginURI'] ) && is_string( $this->plugin_data['PluginURI'] )
? $this->plugin_data['PluginURI']
: '';
if ( '' !== $plugin_uri && str_contains( $plugin_uri, 'git.robotstxt.es' ) ) {
return rtrim( $plugin_uri, '/' ) . '/raw/branch/main/update.json';
}
return 'https://git.robotstxt.es/ROBOTSTXT/' . $this->plugin_slug . '/raw/branch/main/update.json';
}
/**
* Inject update info into WP's plugin update transient.
*
* @since 1.0.0
*
* @param mixed $transient The update_plugins transient value.
* @return mixed The modified transient.
*/
public function inject_update_info( $transient ) {
if ( ! ( $transient instanceof stdClass ) ) {
return $transient;
}
if ( ! isset( $transient->checked ) || ! is_array( $transient->checked ) ) {
return $transient;
}
if ( ! isset( $transient->checked[ $this->plugin_basename ] )
|| ! is_string( $transient->checked[ $this->plugin_basename ] )
) {
return $transient;
}
$current_version = $transient->checked[ $this->plugin_basename ];
$remote = $this->get_remote_data();
$remote_version = isset( $remote['version'] ) && is_string( $remote['version'] ) ? $remote['version'] : '';
$download_url = isset( $remote['download_url'] ) && is_string( $remote['download_url'] ) ? $remote['download_url'] : '';
if ( '' === $remote_version || '' === $download_url ) {
return $transient;
}
if ( ! $this->is_compatible( $remote ) ) {
return $transient;
}
if ( version_compare( $remote_version, $current_version, '>' ) ) {
$plugin_uri = isset( $this->plugin_data['PluginURI'] ) && is_string( $this->plugin_data['PluginURI'] )
? $this->plugin_data['PluginURI']
: '';
$update = (object) array(
'slug' => isset( $remote['slug'] ) && is_string( $remote['slug'] ) ? $remote['slug'] : $this->plugin_slug,
'plugin' => $this->plugin_basename,
'new_version' => $remote_version,
'url' => isset( $remote['homepage'] ) && is_string( $remote['homepage'] ) ? $remote['homepage'] : $plugin_uri,
'package' => $download_url,
'tested' => isset( $remote['tested'] ) && is_string( $remote['tested'] ) ? $remote['tested'] : '',
'requires' => isset( $remote['requires'] ) && is_string( $remote['requires'] ) ? $remote['requires'] : '',
'requires_php' => isset( $remote['requires_php'] ) && is_string( $remote['requires_php'] ) ? $remote['requires_php'] : '',
);
if ( ! isset( $transient->response ) || ! is_array( $transient->response ) ) {
$transient->response = array();
}
$transient->response[ $this->plugin_basename ] = $update;
}
return $transient;
}
/**
* Provide "View details" modal content.
*
* @since 1.0.0
*
* @param false|object $result The result object or false if no result yet.
* @param string $action The type of information being requested.
* @param object $args Plugin API arguments.
* @return false|object The plugin information object or false.
*/
public function provide_plugin_details( $result, string $action, object $args ) {
if ( 'plugin_information' !== $action ) {
return $result;
}
if ( ! isset( $args->slug ) || ! is_string( $args->slug ) || $args->slug !== $this->plugin_slug ) {
return $result;
}
$remote = $this->get_remote_data();
$remote_version = isset( $remote['version'] ) && is_string( $remote['version'] ) ? $remote['version'] : '';
if ( '' === $remote_version ) {
return $result;
}
$plugin_name = isset( $this->plugin_data['Name'] ) && is_string( $this->plugin_data['Name'] )
? $this->plugin_data['Name']
: $this->plugin_slug;
$plugin_uri = isset( $this->plugin_data['PluginURI'] ) && is_string( $this->plugin_data['PluginURI'] )
? $this->plugin_data['PluginURI']
: '';
$description = isset( $this->plugin_data['Description'] ) && is_string( $this->plugin_data['Description'] )
? $this->plugin_data['Description']
: '';
$author = isset( $this->plugin_data['Author'] ) && is_string( $this->plugin_data['Author'] )
? $this->plugin_data['Author']
: '';
return (object) array(
'name' => isset( $remote['name'] ) && is_string( $remote['name'] ) ? $remote['name'] : $plugin_name,
'slug' => isset( $remote['slug'] ) && is_string( $remote['slug'] ) ? $remote['slug'] : $this->plugin_slug,
'version' => $remote_version,
'author' => isset( $remote['author'] ) && is_string( $remote['author'] ) ? $remote['author'] : $author,
'homepage' => isset( $remote['homepage'] ) && is_string( $remote['homepage'] ) ? $remote['homepage'] : $plugin_uri,
'requires' => isset( $remote['requires'] ) && is_string( $remote['requires'] ) ? $remote['requires'] : '',
'tested' => isset( $remote['tested'] ) && is_string( $remote['tested'] ) ? $remote['tested'] : '',
'requires_php' => isset( $remote['requires_php'] ) && is_string( $remote['requires_php'] ) ? $remote['requires_php'] : '',
'sections' => array(
'description' => isset( $remote['description'] ) && is_string( $remote['description'] ) ? $remote['description'] : $description,
'changelog' => isset( $remote['changelog'] ) && is_string( $remote['changelog'] ) ? $remote['changelog'] : '',
),
'download_link' => isset( $remote['download_url'] ) && is_string( $remote['download_url'] ) ? $remote['download_url'] : '',
);
}
/**
* Get remote data with caching and HMAC signature verification.
*
* @since 1.0.0
*
* @return array<string, mixed> Remote data.
*/
private function get_remote_data(): array {
$cached = get_site_transient( $this->cache_key );
if ( false !== $cached && defined( 'AUTH_SALT' ) && '' !== AUTH_SALT ) {
if ( is_array( $cached )
&& isset( $cached['signature'], $cached['data'] )
&& is_string( $cached['signature'] )
&& is_array( $cached['data'] )
) {
$expected_sig = hash_hmac(
'sha256',
$this->cache_key . wp_json_encode( $cached['data'] ),
AUTH_SALT
);
if ( hash_equals( $expected_sig, $cached['signature'] ) ) {
return $this->normalize_array( $cached['data'] );
}
delete_site_transient( $this->cache_key );
$cached = false;
}
}
if ( false === $cached ) {
$remote = $this->fetch_json();
if ( defined( 'AUTH_SALT' ) && '' !== AUTH_SALT ) {
$payload = array(
'data' => $remote,
'timestamp' => time(),
'signature' => hash_hmac(
'sha256',
$this->cache_key . wp_json_encode( $remote ),
AUTH_SALT
),
);
set_site_transient( $this->cache_key, $payload, 6 * HOUR_IN_SECONDS );
} else {
set_site_transient( $this->cache_key, $remote, 6 * HOUR_IN_SECONDS );
}
return $remote;
}
return is_array( $cached ) ? $this->normalize_array( $cached ) : array();
}
/**
* Fetch JSON from remote URL.
*
* @since 1.0.0
*
* @return array<string, mixed> Decoded JSON data.
*/
private function fetch_json(): array {
$response = wp_remote_get(
$this->json_url,
array(
'timeout' => 10,
'headers' => array(
'Accept' => 'application/json',
),
)
);
if ( is_wp_error( $response ) ) {
return array();
}
$code = (int) wp_remote_retrieve_response_code( $response );
if ( $code < 200 || $code >= 300 ) {
return array();
}
$body = wp_remote_retrieve_body( $response );
$data = json_decode( $body, true );
return is_array( $data ) ? $data : array();
}
/**
* Check compatibility with current environment.
*
* @since 1.0.0
*
* @param array<string, mixed> $remote Remote data.
* @return bool True if compatible.
*/
private function is_compatible( array $remote ): bool {
if ( ! empty( $remote['requires_php'] ) && is_string( $remote['requires_php'] ) ) {
if ( version_compare( PHP_VERSION, $remote['requires_php'], '<' ) ) {
return false;
}
}
if ( ! empty( $remote['requires'] ) && is_string( $remote['requires'] ) ) {
if ( version_compare( get_bloginfo( 'version' ), $remote['requires'], '<' ) ) {
return false;
}
}
return true;
}
/**
* Handle manual cache clear via URL parameter.
*
* @since 1.0.0
*
* @return void
*/
public function handle_cache_clear(): void {
$clear_cache = filter_input( INPUT_GET, 'robotstxt_clear_update_cache', FILTER_UNSAFE_RAW );
if ( null === $clear_cache ) {
return;
}
$nonce_raw = filter_input( INPUT_GET, '_wpnonce', FILTER_UNSAFE_RAW );
$nonce = ( null !== $nonce_raw && is_string( $nonce_raw ) )
? sanitize_text_field( wp_unslash( $nonce_raw ) )
: '';
if ( ! wp_verify_nonce( $nonce, 'robotstxt_clear_update_cache' ) ) {
wp_die( esc_html__( 'Security check failed.', 'robotstxt-documentation-markdown' ) );
}
if ( ! current_user_can( 'update_plugins' ) ) {
wp_die( esc_html__( 'You do not have sufficient permissions to access this page.', 'robotstxt-documentation-markdown' ) );
}
$this->clear_cache();
wp_safe_redirect( remove_query_arg( array( 'robotstxt_clear_update_cache', '_wpnonce' ) ) );
exit;
}
/**
* Rebuild an array guaranteeing string keys for PHPStan type safety.
*
* @since 1.0.0
*
* @param array<mixed, mixed> $data Raw array from transient or API.
* @return array<string, mixed>
*/
private function normalize_array( array $data ): array {
$result = array();
foreach ( $data as $k => $v ) {
if ( is_string( $k ) ) {
$result[ $k ] = $v;
}
}
return $result;
}
/**
* Clear update cache.
*
* @since 1.0.0
*
* @return void
*/
public function clear_cache(): void {
delete_site_transient( $this->cache_key );
delete_site_transient( 'update_plugins' );
}
}
}

View file

@ -0,0 +1,90 @@
# Pre-Deploy AI Security Audit — v1.1.1
**Date:** 2026-06-08
**Plugin:** Documentation Markdown (by ROBOTSTXT)
**Version:** 1.1.0 → 1.1.1
**Auditor:** Claude Sonnet (Senior WordPress Plugin Security Auditor role)
**Scope:** Full codebase (all 7 PHP plugin files)
---
## Executive Summary
**Overall status: CONDITIONAL PASS → PASS (after fixes applied)**
All [CRITICAL] findings were resolved before tagging. No SQL injection, no CSRF gaps, no direct object reference, no privilege escalation vectors found. Access is gated behind `edit_pages` throughout with both UI-level and execution-level checks.
**Security risk: Low** (after fixes)
**Version recommendation: stable**
---
## Findings Resolved Before Release
### [CRITICAL → FIXED] Finding 011 — CommonMark raw HTML passthrough
**File:** `robotstxt-documentation-markdown-map.php:296`
**Problem:** CommonMark's default config allows raw HTML blocks from Markdown. A compromised upstream GitHub repository could inject `<script>`, `<iframe>`, or event handlers into synced WordPress post content.
**Fix applied:** `html_input => 'strip'`, `allow_unsafe_links => false` in `CommonMarkConverter` config.
### [WARNING → FIXED] Finding 002 — base64 decode without length validation
**File:** `robotstxt-documentation-markdown-functions.php:55`
**Problem:** `base64_decode()` result not length-checked before `substr()` IV extraction. Tampered options could cause silent decryption failures or short-IV oracle scenarios.
**Fix applied:** Added `false === $decoded || strlen($decoded) <= $iv_length` guard.
### [WARNING → FIXED] Finding 008 — Settings option autoloaded
**File:** `robotstxt-documentation-markdown.php:72, 1164`
**Problem:** Encrypted GitHub token loaded with every WordPress request via autoload.
**Fix applied:** `add_option(..., '', false)` and `update_option(..., false)`.
### [WARNING → FIXED] Finding 018 — `wp_update_post()` return unchecked
**File:** `robotstxt-documentation-markdown-map.php:324`
**Problem:** Sync silently reported success even if post update failed.
**Fix applied:** Return value checked; error returned on failure.
### [WARNING → FIXED] Finding 020 — `base64_decode()` unchecked in GitHub fetch
**File:** `robotstxt-documentation-markdown-github.php:289`
**Problem:** Malformed GitHub API response (bad base64) would cause silent empty post.
**Fix applied:** Added `false === $decoded` guard returning `WP_Error`.
### [BUG → FIXED] Admin notices not displayed
**File:** `robotstxt-documentation-markdown.php:908`
**Problem:** Messages for mapping_created, mapping_updated, mapping_deleted, sync_complete, and error parameters were redirected to URL but never rendered.
**Fix applied:** Complete message map added to `robotstxt_docmd_render_admin_notices()`.
---
## Findings Deferred to Future Release
| ID | Severity | Description | Target |
|----|----------|-------------|--------|
| 001 | WARNING | Token key derivation should use HKDF instead of raw `wp_salt()` — would require token migration | v1.2.0 |
| 003 | WARNING | Debug action nonce/page checks split across two `if` blocks — refactoring risk | v1.2.0 |
| 005 | INFO | `esc_js()` in `onclick` pattern — safe with fixed string but fragile for future edits | v1.2.0 |
| 006 | WARNING | `get_posts(post_type=any, limit=100)` on Add Mapping page — performance on large sites | v1.2.0 |
| 009 | INFO | GitHub API URL: branch/path not `rawurlencode()`d — no current attack vector, defensive hardening | v1.2.0 |
| 010 | INFO | `target_post_type` not validated against registered post types at save | v1.2.0 |
| 013 | INFO | Debug "cached vs fresh" indicator always shows cached after first fetch | v1.2.0 |
| 014 | INFO | Discover page `refresh=1` lacks nonce — forces GitHub API call via CSRF | v1.2.0 |
Deferred findings documented in `docs/known-issues.md`.
---
## Positive Findings (No Action Required)
- All state-changing actions protected with nonces (`wp_nonce_field`, `wp_nonce_url`, `check_admin_referer`, `wp_verify_nonce`)
- Capability checks (`current_user_can('edit_pages')`) applied in both UI rendering and execution logic for all admin pages and handlers
- All `$_POST`/`$_GET` access goes through `robotstxt_docmd_input_string()` / `robotstxt_docmd_input_int()` type-narrowing helpers
- All output escaping at render time (`esc_html`, `esc_attr`, `esc_url`, `esc_js`, `wp_kses_post`)
- All redirects via `wp_safe_redirect()` to `admin_url()` destinations
- No raw SQL; custom SQL (transient cleanup) uses `$wpdb->prepare()` with `$wpdb->esc_like()`
- ABSPATH guard on every PHP file
- No `eval()`, no suspicious `base64_decode()` (documented necessary use for GitHub API decoding), no shell functions
- GitHub token encrypted at rest (AES-256-CBC, key from `wp_salt('auth')`)
- `uninstall.php` uses `WP_UNINSTALL_PLUGIN` guard and respects user data-preservation preference

9
docs/db-migrations.md Normal file
View file

@ -0,0 +1,9 @@
# Database Migrations
This plugin does **not** create custom database tables. All data is stored using WordPress core APIs:
- **Mappings:** Custom Post Type `robotstxt_map` with post meta (prefixed `_robotstxt_docmd_*`)
- **Settings:** WordPress Options API (`robotstxt_docmd_settings`)
- **Cache:** WordPress Transients API (`robotstxt_docmd_*`)
No `DB_VERSION` constant or migration routines are required.

View file

@ -0,0 +1,113 @@
# Pre-Deploy Checklist — Version 1.1.1
**Date:** 2026-06-08
**Plugin:** Documentation Markdown (by ROBOTSTXT)
**Version:** 1.1.1
---
## INPUT VALIDATION
- [x] Empty field validation performed
- [x] Length limits validated server-side
- [x] Format patterns validated (regex, ctype_alnum, preg_match)
- [x] Safelist validation for finite option sets
- [x] Strict type checking (===, in_array with true)
- [x] Validation BEFORE any action or processing
- [x] robotstxt_docmd_input_string() / robotstxt_docmd_input_int() for all superglobal access
## INPUT SANITIZATION
- [x] sanitize_text_field() for single-line text
- [x] sanitize_key() for keys/identifiers
- [x] sanitize_text_field() for github_url (functional; sanitize_url() deferred to v1.2.0 — known-issues.md)
- [x] wp_unslash() before sanitizing superglobals
## OUTPUT ESCAPING
- [x] esc_html() for HTML element content
- [x] esc_attr() for HTML attributes
- [x] esc_url() for all URLs
- [x] esc_js() for inline JavaScript (delete confirm)
- [x] esc_html__(), esc_attr_e() combined i18n+escape functions
- [x] Numeric variables: absint(), (int)
- [x] wp_kses_post() for debug details and status badges
- [x] Escaping at output time, not before storage
## CSRF PROTECTION
- [x] wp_nonce_field() on all forms (save_mapping, save_settings)
- [x] wp_nonce_url() for action URLs (sync, delete)
- [x] check_admin_referer() for all GET state-changing actions
- [x] wp_verify_nonce() in save handlers and updater cache clear
- [x] Nonce action strings are specific (include mapping_id)
- [x] Nonces NOT used for authorization
## DATABASE SECURITY
- [x] $wpdb->prepare() for all custom SQL (transient cleanup)
- [x] $wpdb->esc_like() for LIKE patterns
- [x] WordPress API functions for CPT and post meta
- [x] No $_POST/$_GET interpolation in queries
## CAPABILITY CHECKS
- [x] current_user_can('edit_pages') on every admin page render
- [x] current_user_can('edit_pages') in every handler
- [x] current_user_can('update_plugins') in updater cache clear
- [x] Capability checks in UI rendering (wp_die if no permission)
- [x] Capability checks in execution logic
## FILE OPERATIONS
- [x] ABSPATH guard on every PHP file
- [x] base64_decode() strict with length validation (fixed in 1.1.1)
- [x] No user file uploads managed by this plugin
## DANGEROUS FUNCTIONS
- [x] No eval()
- [x] base64_decode() only for GitHub API content decode (documented necessity)
- [x] No system(), exec(), shell_exec(), passthru()
- [x] No unserialize() — serialize() replaced with wp_json_encode() in 1.1.1
## CODE QUALITY & STANDARDS
- [x] PHPCS: 0 errors, 0 warnings — 7 files, no exclusions
- [x] PHPStan level 9: 0 errors — 7 files, no exclusions
- [x] PHPCompatibility 10.0.0-alpha2: 0 errors (PHP 8.0–8.5)
- [x] Requires PHP: 8.0 (real minimum confirmed by PHPCompatibility scan)
- [x] All i18n strings use textdomain 'robotstxt-documentation-markdown'
- [x] phpDoc on all public functions/methods/hooks
## TESTING
- [x] PHPUnit: 17/17 tests OK (plugin header tests)
- [x] Stable tag 1.1.1 = Version 1.1.1 = ROBOTSTXT_DOCMD_VERSION = update.json version ✓
## VERSIONING & DOCUMENTATION
- [x] Plugin header: Version: 1.1.1
- [x] ROBOTSTXT_DOCMD_VERSION constant: '1.1.1'
- [x] CHANGELOG.md updated
- [x] changelog.txt updated (WP.org format)
- [x] readme.txt: Stable tag 1.1.1, Requires PHP 8.0, Tested up to 7.1
- [x] update.json: version 1.1.1, requires_php 8.0, tested 7.1
- [x] README.md — no new external dependencies added
## DATABASE & UNINSTALL
- [x] uninstall.php exists and respects data preservation option
- [x] No custom DB tables — documented in docs/db-migrations.md
- [x] Settings stored with autoload=false (fixed in 1.1.1)
## AI AUDIT
- [x] Pre-deploy AI audit executed on full codebase
- [x] All [CRITICAL] findings resolved (Finding 011: CommonMark html_input:strip)
- [x] [WARNING] findings deferred documented in docs/known-issues.md
- [x] Audit report: docs/audit-pre-deploy-1.1.1.md
- [x] Executive summary: PASS
- [x] Security risk: Low
## BUILD & ARTIFACT
- [x] deploy.sh executed manually — artifact generated
- [x] ZIP excludes dev files (composer.json, phpstan.neon, .phpcs.xml, tests/, docs/, bin/, AGENTS.md, CLAUDE.md)
- [x] Production vendor/ included (no require-dev packages)
- [x] *.po files excluded (only .mo bundled)
---
## DEPLOY AUTHORIZATION
- All [CRITICAL] items resolved: **YES**
- Executive summary: **PASS**
- Security risk: **Low**
- Manual approval: **YES**

11
docs/known-issues.md Normal file
View file

@ -0,0 +1,11 @@
# Known Issues
This file documents [WARNING]-level findings from pre-deploy audits that have been deferred to future releases.
## Active deferred issues
_None._
---
*For resolved issues see CHANGELOG.md. For [CRITICAL] findings see pre-deploy audit reports in this directory.*

View file

@ -1,845 +0,0 @@
# Translation of Documentation Markdown in Spanish (Spain)
# Copyright (C) 2026 ROBOTSTXT
# This file is distributed under the GPL-3.0-or-later.
msgid ""
msgstr ""
"Project-Id-Version: Documentation Markdown 0.1.0\n"
"Report-Msgid-Bugs-To: https://wordpress.org/support/plugin/robotstxt-"
"documentation-markdown\n"
"POT-Creation-Date: 2026-01-25T18:11:49+00:00\n"
"PO-Revision-Date: 2026-01-25 17:30+0000\n"
"Last-Translator: ROBOTSTXT <info@robotstxt.com>\n"
"Language-Team: Spanish (Spain)\n"
"Language: es_ES\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"
"X-Generator: WP-CLI 2.10.0\n"
"X-Domain: robotstxt-documentation-markdown\n"
#. Plugin Name of the plugin
#: robotstxt-documentation-markdown.php
msgid "Documentation Markdown (by ROBOTSTXT)"
msgstr ""
#. Plugin URI of the plugin
#: robotstxt-documentation-markdown.php
msgid "https://github.com/robotstxt/documentation-markdown"
msgstr ""
#. Description of the plugin
#: robotstxt-documentation-markdown.php
#, fuzzy
msgid ""
"Synchronizes Markdown documentation from GitHub repositories to WordPress "
"pages and posts automatically."
msgstr ""
"Este plugin sincroniza documentación en formato Markdown desde repositorios "
"de GitHub y la convierte en páginas o entradas de WordPress automáticamente."
#. Author of the plugin
#: robotstxt-documentation-markdown.php
msgid "ROBOTSTXT"
msgstr ""
#. Author URI of the plugin
#: robotstxt-documentation-markdown.php
msgid "https://robotstxt.com"
msgstr ""
#: includes/admin/Admin_Mappings.php:52
msgid "Manage Mappings"
msgstr ""
#: includes/admin/Admin_Mappings.php:53
msgid "Mappings"
msgstr ""
#: includes/admin/Admin_Mappings.php:61 includes/admin/Admin_Mappings.php:173
#: includes/admin/Admin_Mappings.php:382
msgid "Add New Mapping"
msgstr ""
#: includes/admin/Admin_Mappings.php:62 includes/admin/Admin_Mappings.php:136
msgid "Add New"
msgstr ""
#: includes/admin/Admin_Mappings.php:105 includes/admin/Admin_Mappings.php:276
msgid "Syncing..."
msgstr ""
#: includes/admin/Admin_Mappings.php:106 includes/admin/Admin_Mappings.php:653
#, fuzzy
msgid "Sync completed successfully!"
msgstr "Configuración guardada correctamente."
#: includes/admin/Admin_Mappings.php:107
msgid "Sync failed:"
msgstr ""
#: includes/admin/Admin_Mappings.php:108 includes/admin/Admin_Mappings.php:342
msgid "Are you sure you want to delete this mapping?"
msgstr ""
#: includes/admin/Admin_Mappings.php:109
msgid "Syncing all mappings..."
msgstr ""
#: includes/admin/Admin_Mappings.php:124 includes/admin/Admin_Mappings.php:357
#: includes/admin/Admin_Settings.php:542
msgid "You do not have sufficient permissions to access this page."
msgstr "No tienes permisos suficientes para acceder a esta página."
#: includes/admin/Admin_Mappings.php:133
#, fuzzy
msgid "Documentation Mappings"
msgstr "Configuración de Documentación"
#: includes/admin/Admin_Mappings.php:145
msgid "Total Mappings"
msgstr ""
#: includes/admin/Admin_Mappings.php:149
msgid "Active"
msgstr ""
#: includes/admin/Admin_Mappings.php:153
msgid "Last Success"
msgstr ""
#: includes/admin/Admin_Mappings.php:157
msgid "Last Error"
msgstr ""
#: includes/admin/Admin_Mappings.php:164
msgid "Sync All Active Mappings"
msgstr ""
#: includes/admin/Admin_Mappings.php:171
msgid "No mappings found. Create your first mapping to get started!"
msgstr ""
#: includes/admin/Admin_Mappings.php:180
msgid "Title"
msgstr ""
#: includes/admin/Admin_Mappings.php:181
msgid "Repository"
msgstr ""
#: includes/admin/Admin_Mappings.php:182
msgid "File"
msgstr ""
#: includes/admin/Admin_Mappings.php:183
msgid "Frequency"
msgstr ""
#: includes/admin/Admin_Mappings.php:184
msgid "Status"
msgstr ""
#: includes/admin/Admin_Mappings.php:185
msgid "Sync Status"
msgstr ""
#: includes/admin/Admin_Mappings.php:186
msgid "Last Sync"
msgstr ""
#: includes/admin/Admin_Mappings.php:187
msgid "Next Sync"
msgstr ""
#: includes/admin/Admin_Mappings.php:188
msgid "Actions"
msgstr ""
#: includes/admin/Admin_Mappings.php:208
#, php-format
msgid "Branch: %s"
msgstr ""
#: includes/admin/Admin_Mappings.php:214 includes/admin/Admin_Mappings.php:232
msgid "Never"
msgstr ""
#: includes/admin/Admin_Mappings.php:219
msgid "Enabled"
msgstr ""
#: includes/admin/Admin_Mappings.php:221
msgid "Disabled"
msgstr ""
#: includes/admin/Admin_Mappings.php:242
msgid "Manual Only"
msgstr ""
#: includes/admin/Admin_Mappings.php:272
msgid "Never Synced"
msgstr ""
#: includes/admin/Admin_Mappings.php:280
msgid "Success"
msgstr ""
#: includes/admin/Admin_Mappings.php:284
msgid "Error"
msgstr ""
#: includes/admin/Admin_Mappings.php:337
msgid "Sync Now"
msgstr ""
#: includes/admin/Admin_Mappings.php:340
msgid "Edit"
msgstr ""
#: includes/admin/Admin_Mappings.php:343
msgid "Delete"
msgstr ""
#: includes/admin/Admin_Mappings.php:382
msgid "Edit Mapping"
msgstr ""
#: includes/admin/Admin_Mappings.php:397
msgid "Mapping Title"
msgstr ""
#: includes/admin/Admin_Mappings.php:401
msgid "A descriptive name for this mapping."
msgstr ""
#: includes/admin/Admin_Mappings.php:407
msgid "Repository Owner"
msgstr ""
#: includes/admin/Admin_Mappings.php:411
msgid "GitHub username or organization (e.g., \"wordpress\")."
msgstr ""
#: includes/admin/Admin_Mappings.php:417
msgid "Repository Name"
msgstr ""
#: includes/admin/Admin_Mappings.php:421
msgid "Repository name (e.g., \"wordpress-develop\")."
msgstr ""
#: includes/admin/Admin_Mappings.php:427
msgid "File Path"
msgstr ""
#: includes/admin/Admin_Mappings.php:431
msgid "Path to Markdown file (e.g., \"README.md\" or \"docs/api.md\")."
msgstr ""
#: includes/admin/Admin_Mappings.php:437
msgid "Branch"
msgstr ""
#: includes/admin/Admin_Mappings.php:441
msgid "Git branch name (default: \"main\")."
msgstr ""
#: includes/admin/Admin_Mappings.php:447
msgid "Target Post Type"
msgstr ""
#: includes/admin/Admin_Mappings.php:463
msgid "WordPress post type for the synced content."
msgstr ""
#: includes/admin/Admin_Mappings.php:469
msgid "Post Author"
msgstr ""
#: includes/admin/Admin_Mappings.php:481
msgid "WordPress user to assign as post author."
msgstr ""
#: includes/admin/Admin_Mappings.php:487
msgid "Sync Frequency"
msgstr ""
#: includes/admin/Admin_Mappings.php:503
msgid "How often to automatically sync this documentation from GitHub."
msgstr ""
#: includes/admin/Admin_Mappings.php:509
msgid "Enable Sync"
msgstr ""
#: includes/admin/Admin_Mappings.php:514
msgid "Enable automatic synchronization for this mapping"
msgstr ""
#: includes/admin/Admin_Mappings.php:516
msgid "Must be enabled for automatic syncing to work."
msgstr ""
#: includes/admin/Admin_Mappings.php:521
msgid "Update Mapping"
msgstr ""
#: includes/admin/Admin_Mappings.php:521
#, fuzzy
msgid "Create Mapping"
msgstr "Crear un token"
#: includes/admin/Admin_Mappings.php:536 includes/admin/Admin_Mappings.php:593
#, fuzzy
msgid "You do not have sufficient permissions."
msgstr "No tienes permisos suficientes para acceder a esta página."
#: includes/admin/Admin_Mappings.php:634 includes/admin/Admin_Mappings.php:670
msgid "Insufficient permissions."
msgstr ""
#: includes/admin/Admin_Mappings.php:640
msgid "Invalid mapping ID."
msgstr ""
#. translators: 1: Success count, 2: Error count
#: includes/admin/Admin_Mappings.php:690
#, php-format
msgid "Sync complete: %1$d succeeded, %2$d failed."
msgstr ""
#: includes/admin/Admin_Mappings.php:711
#, fuzzy
msgid "Mapping created successfully."
msgstr "Configuración guardada correctamente."
#: includes/admin/Admin_Mappings.php:712
#, fuzzy
msgid "Mapping updated successfully."
msgstr "Configuración guardada correctamente."
#: includes/admin/Admin_Mappings.php:713
#, fuzzy
msgid "Mapping deleted successfully."
msgstr "Configuración guardada correctamente."
#: includes/admin/Admin_Settings.php:45
msgid "Documentation Settings"
msgstr "Configuración de Documentación"
#: includes/admin/Admin_Settings.php:46
msgid "Documentation"
msgstr "Documentación"
#: includes/admin/Admin_Settings.php:78
msgid "GitHub Repository Settings"
msgstr "Configuración del Repositorio de GitHub"
#: includes/admin/Admin_Settings.php:85
msgid "GitHub Documentation URL"
msgstr "URL de Documentación en GitHub"
#: includes/admin/Admin_Settings.php:93
msgid "GitHub Personal Access Token"
msgstr "Token de Acceso Personal de GitHub"
#: includes/admin/Admin_Settings.php:102
#, fuzzy
msgid "Advanced Settings"
msgstr "Guardar Configuración"
#: includes/admin/Admin_Settings.php:109
msgid "Delete Data on Uninstall"
msgstr ""
#: includes/admin/Admin_Settings.php:118
msgid "Email Notifications"
msgstr ""
#: includes/admin/Admin_Settings.php:125
msgid "Enable Notifications"
msgstr ""
#: includes/admin/Admin_Settings.php:133
msgid "Notification Email"
msgstr ""
#: includes/admin/Admin_Settings.php:141
msgid "Notify on Success"
msgstr ""
#: includes/admin/Admin_Settings.php:149
msgid "Notify Unsynchronized"
msgstr ""
#: includes/admin/Admin_Settings.php:181
msgid "GitHub URL must use HTTPS protocol for security. URL was not saved."
msgstr ""
#: includes/admin/Admin_Settings.php:210
msgid "Warning: Token could not be encrypted. It has been saved in plain text."
msgstr ""
#: includes/admin/Admin_Settings.php:251
msgid ""
"Configure your GitHub repository settings to synchronize documentation from "
"GitHub to WordPress."
msgstr ""
"Configura los ajustes de tu repositorio de GitHub para sincronizar la "
"documentación desde GitHub a WordPress."
#: includes/admin/Admin_Settings.php:267
msgid "Advanced configuration options for plugin behavior."
msgstr ""
#: includes/admin/Admin_Settings.php:295
msgid ""
"Enter the full URL of your GitHub repository (e.g., https://github.com/owner/"
"repository)"
msgstr ""
"Introduce la URL completa de tu repositorio de GitHub (ej: https://github."
"com/propietario/repositorio)"
#: includes/admin/Admin_Settings.php:322
msgid "ghp_xxxxxxxxxxxx"
msgstr "ghp_xxxxxxxxxxxx"
#. translators: %s: Link to GitHub Personal Access Tokens page
#: includes/admin/Admin_Settings.php:328
#, php-format
msgid "Enter your GitHub Personal Access Token. %s"
msgstr "Introduce tu Token de Acceso Personal de GitHub. %s"
#: includes/admin/Admin_Settings.php:333
msgid "Create a token"
msgstr "Crear un token"
#: includes/admin/Admin_Settings.php:340
msgid "How to create a GitHub Personal Access Token:"
msgstr "Cómo crear un Token de Acceso Personal de GitHub:"
#: includes/admin/Admin_Settings.php:343
msgid "Go to GitHub → Settings → Developer settings → Personal access tokens"
msgstr ""
"Ve a GitHub → Configuración → Ajustes de desarrollador → Tokens de acceso "
"personal"
#: includes/admin/Admin_Settings.php:344
msgid "Click \"Generate new token\" (classic)"
msgstr "Haz clic en \"Generar nuevo token\" (clásico)"
#: includes/admin/Admin_Settings.php:345
msgid "Give it a descriptive name (e.g., \"WordPress Documentation Sync\")"
msgstr ""
"Dale un nombre descriptivo (ej: \"Sincronización Documentación WordPress\")"
#: includes/admin/Admin_Settings.php:348
msgid "For public repositories: No specific scopes needed"
msgstr "Para repositorios públicos: No se necesitan permisos específicos"
#: includes/admin/Admin_Settings.php:355
msgid "For private repositories: Select the \"repo\" scope"
msgstr "Para repositorios privados: Selecciona el permiso \"repo\""
#: includes/admin/Admin_Settings.php:361
msgid "Click \"Generate token\" and copy it immediately"
msgstr "Haz clic en \"Generar token\" y cópialo inmediatamente"
#: includes/admin/Admin_Settings.php:362
msgid "Paste the token in the field above and save"
msgstr "Pega el token en el campo de arriba y guarda"
#: includes/admin/Admin_Settings.php:367
msgid ""
"Note: For security, your token is stored encrypted and will be shown as dots "
"once saved."
msgstr ""
"Nota: Por seguridad, tu token se almacena cifrado y se mostrará como puntos "
"una vez guardado."
#: includes/admin/Admin_Settings.php:397
msgid "Delete all plugin data when uninstalling"
msgstr ""
#: includes/admin/Admin_Settings.php:401
msgid ""
"If enabled, all plugin settings and mapping configurations will be deleted "
"when you uninstall the plugin."
msgstr ""
#: includes/admin/Admin_Settings.php:409
msgid "Important:"
msgstr ""
#: includes/admin/Admin_Settings.php:411
msgid ""
"Your synced documentation content (pages/posts) will NOT be deleted, only "
"the mapping configurations and plugin settings."
msgstr ""
#: includes/admin/Admin_Settings.php:419
msgid ""
"This ensures your documentation remains available even after uninstalling "
"the plugin."
msgstr ""
#: includes/admin/Admin_Settings.php:438
msgid "Configure email notifications for sync events."
msgstr ""
#: includes/admin/Admin_Settings.php:458
msgid "Send email notifications for sync errors"
msgstr ""
#: includes/admin/Admin_Settings.php:461
msgid ""
"You will receive an email when a sync operation fails (rate limited to once "
"per hour per mapping)."
msgstr ""
#. translators: %s: Default admin email
#: includes/admin/Admin_Settings.php:482
#, php-format
msgid "Email address for notifications (default: %s)."
msgstr ""
#: includes/admin/Admin_Settings.php:503
msgid "Send email notifications for successful syncs"
msgstr ""
#: includes/admin/Admin_Settings.php:506
msgid ""
"Receive an email confirmation when content is successfully synchronized (not "
"recommended for frequent syncs)."
msgstr ""
#: includes/admin/Admin_Settings.php:524
msgid "Notify when mappings have not been synchronized"
msgstr ""
#: includes/admin/Admin_Settings.php:527
msgid ""
"Receive alerts when enabled mappings with auto-sync have never been "
"synchronized (rate limited to once per hour)."
msgstr ""
#: includes/admin/Admin_Settings.php:550
msgid "Settings saved successfully."
msgstr "Configuración guardada correctamente."
#: includes/admin/Admin_Settings.php:563
msgid ""
"Documentation Markdown allows you to automatically synchronize Markdown "
"documentation from GitHub repositories to your WordPress site."
msgstr ""
"Documentation Markdown te permite sincronizar automáticamente documentación "
"en formato Markdown desde repositorios de GitHub a tu sitio WordPress."
#: includes/admin/Admin_Settings.php:575
msgid "Save Settings"
msgstr "Guardar Configuración"
#: includes/admin/Admin_Settings.php:580
msgid "About This Plugin"
msgstr "Acerca de este Plugin"
#: includes/admin/Admin_Settings.php:583
msgid ""
"This plugin synchronizes Markdown documentation from GitHub repositories and "
"converts it into WordPress pages or posts automatically."
msgstr ""
"Este plugin sincroniza documentación en formato Markdown desde repositorios "
"de GitHub y la convierte en páginas o entradas de WordPress automáticamente."
#: includes/admin/Admin_Settings.php:590
msgid "Version:"
msgstr "Versión:"
#: includes/admin/Admin_Settings.php:594
msgid "Developer:"
msgstr "Desarrollador:"
#: includes/Cron_Manager.php:43
msgid "Never (Manual Only)"
msgstr ""
#: includes/Cron_Manager.php:47
msgid "Every 1 Minute"
msgstr ""
#: includes/Cron_Manager.php:51
msgid "Every 5 Minutes"
msgstr ""
#: includes/Cron_Manager.php:55
msgid "Every 10 Minutes"
msgstr ""
#: includes/Cron_Manager.php:59
msgid "Every 15 Minutes"
msgstr ""
#: includes/Cron_Manager.php:63
msgid "Every 30 Minutes"
msgstr ""
#: includes/Cron_Manager.php:67
msgid "Every 1 Hour"
msgstr ""
#: includes/Cron_Manager.php:71
msgid "Every 2 Hours"
msgstr ""
#: includes/Cron_Manager.php:75
msgid "Every 4 Hours"
msgstr ""
#: includes/Cron_Manager.php:79
msgid "Every 6 Hours"
msgstr ""
#: includes/Cron_Manager.php:83
msgid "Every 12 Hours"
msgstr ""
#: includes/Cron_Manager.php:87
msgid "Once Daily"
msgstr ""
#: includes/Cron_Manager.php:238 includes/Cron_Manager.php:247
msgid "Now"
msgstr ""
#. translators: %s: Mapping title
#: includes/Cron_Manager.php:286
#, fuzzy, php-format
msgid "[Documentation Sync] Error: %s"
msgstr "Configuración de Documentación"
#. translators: %s: Mapping title
#: includes/Cron_Manager.php:332
#, fuzzy, php-format
msgid "[Documentation Sync] Success: %s"
msgstr "Configuración de Documentación"
#: includes/Cron_Manager.php:397
msgid "[Documentation Sync] Unsynchronized Files Found"
msgstr ""
#. translators: 1: Mapping title, 2: Error message
#: includes/Cron_Manager.php:491
#, php-format
msgid ""
"Failed to sync documentation: %1$s\n"
"\n"
"Error: %2$s\n"
"\n"
msgstr ""
#: includes/Cron_Manager.php:496 includes/Cron_Manager.php:538
#, fuzzy
msgid "Repository Details:\n"
msgstr "Configuración del Repositorio de GitHub"
#. translators: %s: Admin URL
#: includes/Cron_Manager.php:504
#, php-format
msgid "Manage mappings: %s\n"
msgstr ""
#. translators: %s: Mapping title
#: includes/Cron_Manager.php:522
#, php-format
msgid ""
"Successfully synchronized documentation: %s\n"
"\n"
msgstr ""
#. translators: 1: Post title, 2: Post URL
#: includes/Cron_Manager.php:531
#, php-format
msgid ""
"Post: %1$s\n"
"View: %2$s\n"
"\n"
msgstr ""
#. translators: %d: Number of unsynchronized mappings
#: includes/Cron_Manager.php:558
#, php-format
msgid "There is %d documentation mapping that has not been synchronized:"
msgid_plural ""
"There are %d documentation mappings that have not been synchronized:"
msgstr[0] ""
msgstr[1] ""
#. translators: %s: Admin URL
#: includes/Cron_Manager.php:579
#, php-format
msgid "Please review and sync these mappings: %s\n"
msgstr ""
#: includes/encryption-functions.php:34
msgid "OpenSSL extension is required for token encryption"
msgstr ""
#: includes/encryption-functions.php:47 includes/encryption-functions.php:112
msgid "Failed to determine cipher IV length"
msgstr ""
#: includes/encryption-functions.php:64
msgid "Encryption failed"
msgstr ""
#: includes/encryption-functions.php:90
msgid "OpenSSL extension is required for token decryption"
msgstr ""
#: includes/encryption-functions.php:99
msgid "Invalid encrypted data format"
msgstr ""
#: includes/encryption-functions.php:130
msgid "Decryption failed"
msgstr ""
#: includes/GitHub_API_Client.php:81
msgid "Invalid response from GitHub API: missing required fields"
msgstr ""
#: includes/GitHub_API_Client.php:91
msgid "Failed to decode file content from GitHub"
msgstr ""
#: includes/GitHub_API_Client.php:132
msgid "SHA not found in GitHub API response"
msgstr ""
#. translators: %s: Error message
#: includes/GitHub_API_Client.php:213
#, php-format
msgid "GitHub API request failed: %s"
msgstr ""
#: includes/GitHub_API_Client.php:230
msgid "Unknown error"
msgstr ""
#: includes/GitHub_API_Client.php:234
msgid "Authentication failed. Please check your GitHub token."
msgstr ""
#: includes/GitHub_API_Client.php:235
msgid "Access forbidden. Check your token permissions or rate limit."
msgstr ""
#: includes/GitHub_API_Client.php:236
msgid "File not found in repository. Please verify the file path and branch."
msgstr ""
#. translators: 1: HTTP status code, 2: Error message
#: includes/GitHub_API_Client.php:239
#, php-format
msgid "GitHub API error (%1$d): %2$s"
msgstr ""
#. translators: %s: JSON error message
#: includes/GitHub_API_Client.php:255
#, php-format
msgid "Invalid JSON response from GitHub: %s"
msgstr ""
#: includes/GitHub_API_Client.php:347
msgid "unknown"
msgstr ""
#. translators: %s: Reset time
#: includes/GitHub_API_Client.php:352
#, php-format
msgid "GitHub API rate limit nearly exceeded. Resets at: %s"
msgstr ""
#: includes/mapping-functions.php:73 includes/mapping-functions.php:118
msgid "Invalid mapping ID"
msgstr ""
#: includes/mapping-functions.php:124
msgid "Failed to delete mapping"
msgstr ""
#: includes/mapping-functions.php:227
msgid "Repository owner is required"
msgstr ""
#: includes/mapping-functions.php:233
msgid "Invalid repository owner format"
msgstr ""
#: includes/mapping-functions.php:238
msgid "Repository name is required"
msgstr ""
#: includes/mapping-functions.php:244
msgid "Invalid repository name format"
msgstr ""
#: includes/mapping-functions.php:249
msgid "File path is required"
msgstr ""
#: includes/mapping-functions.php:256
msgid "File path cannot contain \"..\""
msgstr ""
#: includes/mapping-functions.php:261
msgid "File must be .md or .markdown"
msgstr ""
#: includes/mapping-functions.php:268
msgid "Invalid branch name format"
msgstr ""
#: includes/mapping-functions.php:275
msgid "Post type does not exist"
msgstr ""
#: includes/Plugin.php:172
#, fuzzy
msgid "GitHub Doc Mappings"
msgstr "URL de Documentación en GitHub"
#: includes/Plugin.php:173
#, fuzzy
msgid "GitHub Doc Mapping"
msgstr "URL de Documentación en GitHub"
#: includes/Sync_Manager.php:84 includes/Sync_Manager.php:422
msgid "Synchronization is disabled for this mapping."
msgstr ""
#. translators: %s: Error message from GitHub API
#: includes/Sync_Manager.php:259
#, php-format
msgid "Failed to fetch file from GitHub: %s"
msgstr ""
#. translators: %s: Error message
#: includes/Sync_Manager.php:441
#, php-format
msgid "Failed to check for changes: %s"
msgstr ""
#: includes/Sync_Manager.php:498
#, fuzzy
msgid "GitHub Personal Access Token is not configured."
msgstr "Token de Acceso Personal de GitHub"
#: includes/Sync_Manager.php:504
msgid "No active mappings configured."
msgstr ""
#: includes/Sync_Manager.php:509
msgid "OpenSSL extension is not available (required for token encryption)."
msgstr ""

View file

@ -2,9 +2,9 @@
Contributors: robotstxt
Tags: github, documentation, markdown, sync, automation
Requires at least: 6.7
Tested up to: 7.0
Requires PHP: 8.2
Stable tag: 1.1.0
Tested up to: 7.1
Requires PHP: 8.0
Stable tag: 1.1.1
License: GPLv3 or later
License URI: https://www.gnu.org/licenses/gpl-3.0.html
@ -178,13 +178,41 @@ Then go to Documentation → Settings, and you'll see a "Debug Tools" section at
== Compatibility ==
* WordPress: 6.7 - 6.9
* PHP: 8.2 - 8.5
* WordPress: 6.7 - 7.1
* PHP: 8.0 - 8.5
== Changelog ==
For the complete changelog, see [changelog.txt](https://git.robotstxt.es/ROBOTSTXT/robotstxt-documentation-markdown/raw/branch/main/changelog.txt).
= 1.1.1 - 2026-06-08 =
**Security**
* CommonMark: disabled raw HTML passthrough (`html_input: strip`, `allow_unsafe_links: false`) — prevents stored XSS via a compromised upstream repository
* Settings option now stored with `autoload = false` — encrypted GitHub token no longer loaded on every WordPress request
* Replaced `serialize()` with `wp_json_encode()` in updater HMAC cache signature
* Added strict base64 length validation before IV extraction in token decryption
* Added `base64_decode()` return-value check in GitHub file content fetch
**Fixed**
* Admin notices now display results for all operations: mapping created, updated, deleted, sync complete, and errors — previously only "Settings saved" was shown
* `wp_update_post()` return value now checked during sync — silent failures no longer reported as success
* Wrong textdomain in updater class (`'robotstxt-smtp'` → `'robotstxt-documentation-markdown'`)
**Changed**
* Renamed `robotstxt-updater.php` → `class-robotstxt-updater.php` (WordPress file naming convention)
* Minimum PHP version corrected to 8.0 (real minimum confirmed by PHPCompatibility scan — no PHP 8.1 or 8.2 specific features used)
**Developer**
* Added full tooling: `composer.json`, `phpstan.neon` (level 9), `.phpcs.xml`, `bin/deploy.sh`, `phpunit.xml.dist`
* PHPCompatibility updated to 10.0.0-alpha2 (PHP 8.x feature detection)
* PHPUnit: 17 plugin header tests added
* PHPCS, PHPStan level 9, PHPUnit all pass with 0 errors
= 1.1.0 - 2026-03-28 =
**Security**

View file

@ -52,7 +52,10 @@ function robotstxt_docmd_decrypt_token( string $encrypted_token ): string {
$key = wp_salt( 'auth' );
$iv_length = openssl_cipher_iv_length( 'aes-256-cbc' );
$decoded = base64_decode( $encrypted_token ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_decode
$decoded = base64_decode( $encrypted_token, true ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_decode
if ( false === $decoded || strlen( $decoded ) <= $iv_length ) {
return '';
}
$iv = substr( $decoded, 0, $iv_length );
$encrypted = substr( $decoded, $iv_length );

View file

@ -286,7 +286,11 @@ function robotstxt_docmd_get_file_content( string $owner, string $repo, string $
// Decode content (GitHub returns base64).
if ( 'base64' === $data['encoding'] ) {
return base64_decode( $data['content'] ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_decode
$decoded = base64_decode( $data['content'], true ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_decode
if ( false === $decoded ) {
return new WP_Error( 'decode_failed', __( 'Failed to decode file content from GitHub.', 'robotstxt-documentation-markdown' ) );
}
return $decoded;
}
return $data['content'];

View file

@ -293,7 +293,13 @@ function robotstxt_docmd_sync_mapping( int $mapping_id ): bool|WP_Error {
}
// Convert Markdown to HTML using CommonMark.
$converter = new \League\CommonMark\CommonMarkConverter();
// Strip raw HTML from Markdown to prevent stored XSS via compromised upstream repos.
$converter = new \League\CommonMark\CommonMarkConverter(
array(
'html_input' => 'strip',
'allow_unsafe_links' => false,
)
);
$html_content = $converter->convert( $content )->getContent();
// Create or update WordPress post.
@ -321,12 +327,18 @@ function robotstxt_docmd_sync_mapping( int $mapping_id ): bool|WP_Error {
update_post_meta( $mapping_id, '_robotstxt_docmd_target_post_id', $post_id );
} else {
// Update existing post.
wp_update_post(
$update_result = wp_update_post(
array(
'ID' => $mapping['target_post_id'],
'post_content' => $html_content,
)
),
true
);
if ( is_wp_error( $update_result ) ) {
update_post_meta( $mapping_id, '_robotstxt_docmd_sync_status', 'error' );
return $update_result;
}
}
// Update sync status.

View file

@ -3,9 +3,9 @@
* Plugin Name: Documentation Markdown (by ROBOTSTXT)
* Plugin URI: https://git.robotstxt.es/ROBOTSTXT/robotstxt-documentation-markdown
* Description: Synchronizes Markdown documentation from GitHub repositories to WordPress pages and posts automatically.
* Version: 1.1.0
* Version: 1.1.1
* Requires at least: 6.7
* Requires PHP: 8.2
* Requires PHP: 8.0
* Security: robotstxt@robotstxt.es
* Author: ROBOTSTXT
* Author URI: https://www.robotstxt.es/
@ -26,7 +26,7 @@ if ( ! defined( 'ABSPATH' ) ) {
}
// Define plugin constants.
define( 'ROBOTSTXT_DOCMD_VERSION', '1.1.0' );
define( 'ROBOTSTXT_DOCMD_VERSION', '1.1.1' );
define( 'ROBOTSTXT_DOCMD_PLUGIN_FILE', __FILE__ );
define( 'ROBOTSTXT_DOCMD_PLUGIN_DIR', plugin_dir_path( __FILE__ ) );
define( 'ROBOTSTXT_DOCMD_PLUGIN_URL', plugin_dir_url( __FILE__ ) );
@ -74,7 +74,9 @@ function robotstxt_docmd_activate() {
array(
'github_url' => '',
'github_token' => '',
)
),
'',
false // Do not autoload — contains encrypted token.
);
}
}
@ -909,9 +911,26 @@ function robotstxt_docmd_render_admin_notices() {
// Check for regular message parameter.
// phpcs:ignore WordPress.Security.NonceVerification.Recommended
$message = sanitize_key( wp_unslash( robotstxt_docmd_input_string( $_GET, 'message' ) ) );
if ( 'settings_saved' === $message ) {
$success_messages = array(
'settings_saved' => __( 'Settings saved successfully.', 'robotstxt-documentation-markdown' ),
'mapping_created' => __( 'Mapping created successfully.', 'robotstxt-documentation-markdown' ),
'mapping_updated' => __( 'Mapping updated successfully.', 'robotstxt-documentation-markdown' ),
'mapping_deleted' => __( 'Mapping deleted.', 'robotstxt-documentation-markdown' ),
'sync_complete' => __( 'Sync completed successfully.', 'robotstxt-documentation-markdown' ),
);
if ( isset( $success_messages[ $message ] ) ) {
echo '<div class="notice notice-success is-dismissible"><p>';
esc_html_e( 'Settings saved successfully.', 'robotstxt-documentation-markdown' );
echo esc_html( $success_messages[ $message ] );
echo '</p></div>';
}
// phpcs:ignore WordPress.Security.NonceVerification.Recommended
$error_text = sanitize_text_field( wp_unslash( robotstxt_docmd_input_string( $_GET, 'error' ) ) );
if ( '' !== $error_text ) {
echo '<div class="notice notice-error is-dismissible"><p>';
echo esc_html( $error_text );
echo '</p></div>';
}
@ -1159,7 +1178,7 @@ function robotstxt_docmd_handle_save_settings() {
// phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized
$settings['delete_on_uninstall'] = ! empty( $_POST['delete_on_uninstall'] ) ? 1 : 0;
update_option( 'robotstxt_docmd_settings', $settings );
update_option( 'robotstxt_docmd_settings', $settings, false );
wp_safe_redirect( add_query_arg( 'message', 'settings_saved', admin_url( 'admin.php?page=robotstxt-docmd-settings' ) ) );
exit;
@ -1589,5 +1608,5 @@ function robotstxt_docmd_debug_fix_crons() {
}
// Initialize ROBOTSTXT updater (auto-configures from plugin headers).
require_once __DIR__ . '/robotstxt-updater.php';
require_once __DIR__ . '/class-robotstxt-updater.php';
Robotstxt_Updater::init( __FILE__ );

View file

@ -1,12 +1,12 @@
{
"name": "Documentation Markdown (by ROBOTSTXT)",
"slug": "robotstxt-documentation-markdown",
"version": "1.0.0",
"download_url": "https://git.robotstxt.es/ROBOTSTXT/robotstxt-documentation-markdown/releases/download/1.0.0/robotstxt-documentation-markdown-1.0.0.zip",
"version": "1.1.1",
"download_url": "https://git.robotstxt.es/ROBOTSTXT/robotstxt-documentation-markdown/releases/download/1.1.1/robotstxt-documentation-markdown-1.1.1.zip",
"requires": "6.7",
"requires_php": "8.2",
"tested": "6.9",
"last_updated": "2026-01-26",
"requires_php": "8.0",
"tested": "7.1",
"last_updated": "2026-06-08",
"author": "ROBOTSTXT",
"author_profile": "https://www.robotstxt.es/",
"homepage": "https://git.robotstxt.es/ROBOTSTXT/robotstxt-documentation-markdown",

7
vendor/autoload.php vendored
View file

@ -14,12 +14,9 @@ if (PHP_VERSION_ID < 50600) {
echo $err;
}
}
trigger_error(
$err,
E_USER_ERROR
);
throw new RuntimeException($err);
}
require_once __DIR__ . '/composer/autoload_real.php';
return ComposerAutoloaderInit216e6d5522dd071bc42c5f7c15b28cdc::getLoader();
return ComposerAutoloaderInit062b6bfebe9519df3bcac54aafa83aec::getLoader();

View file

@ -26,12 +26,23 @@ use Composer\Semver\VersionParser;
*/
class InstalledVersions
{
/**
* @var string|null if set (by reflection by Composer), this should be set to the path where this class is being copied to
* @internal
*/
private static $selfDir = null;
/**
* @var mixed[]|null
* @psalm-var array{root: array{name: string, pretty_version: string, version: string, reference: string|null, type: string, install_path: string, aliases: string[], dev: bool}, versions: array<string, array{pretty_version?: string, version?: string, reference?: string|null, type?: string, install_path?: string, aliases?: string[], dev_requirement: bool, replaced?: string[], provided?: string[]}>}|array{}|null
*/
private static $installed;
/**
* @var bool
*/
private static $installedIsLocalDir;
/**
* @var bool|null
*/
@ -309,6 +320,24 @@ class InstalledVersions
{
self::$installed = $data;
self::$installedByVendor = array();
// when using reload, we disable the duplicate protection to ensure that self::$installed data is
// always returned, but we cannot know whether it comes from the installed.php in __DIR__ or not,
// so we have to assume it does not, and that may result in duplicate data being returned when listing
// all installed packages for example
self::$installedIsLocalDir = false;
}
/**
* @return string
*/
private static function getSelfDir()
{
if (self::$selfDir === null) {
self::$selfDir = strtr(__DIR__, '\\', '/');
}
return self::$selfDir;
}
/**
@ -322,19 +351,27 @@ class InstalledVersions
}
$installed = array();
$copiedLocalDir = false;
if (self::$canGetVendors) {
$selfDir = self::getSelfDir();
foreach (ClassLoader::getRegisteredLoaders() as $vendorDir => $loader) {
$vendorDir = strtr($vendorDir, '\\', '/');
if (isset(self::$installedByVendor[$vendorDir])) {
$installed[] = self::$installedByVendor[$vendorDir];
} elseif (is_file($vendorDir.'/composer/installed.php')) {
/** @var array{root: array{name: string, pretty_version: string, version: string, reference: string|null, type: string, install_path: string, aliases: string[], dev: bool}, versions: array<string, array{pretty_version?: string, version?: string, reference?: string|null, type?: string, install_path?: string, aliases?: string[], dev_requirement: bool, replaced?: string[], provided?: string[]}>} $required */
$required = require $vendorDir.'/composer/installed.php';
$installed[] = self::$installedByVendor[$vendorDir] = $required;
if (null === self::$installed && strtr($vendorDir.'/composer', '\\', '/') === strtr(__DIR__, '\\', '/')) {
self::$installed = $installed[count($installed) - 1];
self::$installedByVendor[$vendorDir] = $required;
$installed[] = $required;
if (self::$installed === null && $vendorDir.'/composer' === $selfDir) {
self::$installed = $required;
self::$installedIsLocalDir = true;
}
}
if (self::$installedIsLocalDir && $vendorDir.'/composer' === $selfDir) {
$copiedLocalDir = true;
}
}
}
@ -350,7 +387,7 @@ class InstalledVersions
}
}
if (self::$installed !== array()) {
if (self::$installed !== array() && !$copiedLocalDir) {
$installed[] = self::$installed;
}

View file

@ -1,3 +1,4 @@
Copyright (c) Nils Adermann, Jordi Boggiano
Permission is hereby granted, free of charge, to any person obtaining a copy
@ -17,3 +18,4 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

View file

@ -377,6 +377,9 @@ return array(
'Nette\\Utils\\JsonException' => $vendorDir . '/nette/utils/src/Utils/exceptions.php',
'Nette\\Utils\\ObjectHelpers' => $vendorDir . '/nette/utils/src/Utils/ObjectHelpers.php',
'Nette\\Utils\\Paginator' => $vendorDir . '/nette/utils/src/Utils/Paginator.php',
'Nette\\Utils\\Process' => $vendorDir . '/nette/utils/src/Utils/Process.php',
'Nette\\Utils\\ProcessFailedException' => $vendorDir . '/nette/utils/src/Utils/exceptions.php',
'Nette\\Utils\\ProcessTimeoutException' => $vendorDir . '/nette/utils/src/Utils/exceptions.php',
'Nette\\Utils\\Random' => $vendorDir . '/nette/utils/src/Utils/Random.php',
'Nette\\Utils\\Reflection' => $vendorDir . '/nette/utils/src/Utils/Reflection.php',
'Nette\\Utils\\ReflectionMethod' => $vendorDir . '/nette/utils/src/Utils/ReflectionMethod.php',

View file

@ -7,9 +7,8 @@ $baseDir = dirname($vendorDir);
return array(
'Symfony\\Polyfill\\Php80\\' => array($vendorDir . '/symfony/polyfill-php80'),
'RobotsTxt\\DocumentationMarkdown\\' => array($baseDir . '/includes'),
'Psr\\EventDispatcher\\' => array($vendorDir . '/psr/event-dispatcher/src'),
'Nette\\' => array($vendorDir . '/nette/utils/src', $vendorDir . '/nette/schema/src'),
'Nette\\' => array($vendorDir . '/nette/schema/src', $vendorDir . '/nette/utils/src'),
'League\\Config\\' => array($vendorDir . '/league/config/src'),
'League\\CommonMark\\' => array($vendorDir . '/league/commonmark/src'),
'Dflydev\\DotAccessData\\' => array($vendorDir . '/dflydev/dot-access-data/src'),

Some files were not shown because too many files have changed in this diff Show more