SignDocs Brasil

Registro de alterações

1.3.7

WP.org reviewer feedback, round 2 (review ID signdocs-brasil/signdocsbrasil/8May26/T2 15May26/4.0).

• New == External services == section documenting every external endpoint the plugin contacts: the SignDocs API (api.signdocs.com.br / api-hml.signdocs.com.br), the OAuth2 token endpoint at the same base URL, the browser SDK CDN (cdn.signdocs.com.br / cdn-hml.signdocs.com.br), and the signing UI (sign.signdocs.com.br). Each subsection states what data is sent, when, and links to Terms of Use and Privacy Policy.
• Trusted-proxy IP resolver hardened. ClientIp::resolve() previously returned $_SERVER['REMOTE_ADDR'] verbatim when no trusted-proxy chain matched, propagating malformed values into the rate-limit transient key and audit log. Both return paths now gate on filter_var(..., FILTER_VALIDATE_IP); invalid values become empty strings. The anonymous-signing AJAX rate limiter now routes through ClientIp::resolve() instead of reading $_SERVER['REMOTE_ADDR'] directly.
• Allow-list validation on user-supplied policy / locale. Signdocs_Ajax::create_session and Signdocs_WooCommerce::save_product_meta previously accepted any sanitize_text_field-cleaned string for the policy and locale fields, then forwarded it to the API. Both call sites now compare against the canonical lists (Signdocs_Settings::get_policy_options() for policy, ['pt-BR', 'en', 'es'] for locale) and fall back to the configured plugin default when the submitted value isn’t recognized. Avoids 4xx round-trips against the SignDocs API for deprecated profile names.
• is_email() validation on signer email. sanitize_email() strips invalid characters but doesn’t reject a value that fails to parse as an email. Added an is_email() check next to the existing required-field validation in Signdocs_Ajax::create_session.
• wp_unslash() on remaining admin reads. The Verify-page POST handler (VerifyPage::render) now unslashes $_POST['kind'] before comparing, matching the WP coding standard the reviewer’s AI expects.
• esc_html on exception messages reaching the frontend in four call sites: Signdocs_Ajax::create_session (AJAX error response), Signdocs_Settings::ajax_test_connection and ::ajax_register_webhook (settings-page AJAX), and Signdocs_WooCommerce::create_signing_for_order (order note). Exception text from upstream APIs can contain quotes or angle brackets that would break a frontend handler that does innerHTML = response.message.

1.3.6

WP.org reviewer feedback, round 1 (received 2026-05-05, ~9h after submission).

• Description rephrased. The short description previously read “the most complete WordPress plugin for legally-binding electronic signatures in Brazil.” That’s a comparative marketing claim, which the WP.org Plugin Guidelines disallow (Guideline 11). Replaced with “the official WordPress plugin for legally-binding electronic signatures in Brazil” — factual (this is the first-party plugin published by SignDocs Brasil), non-comparative.
• Webhook REST route now uses a proper permission_callback. Previously the route registered with permission_callback => '__return_true' and verified the HMAC signature inside the request handler. While that behaved correctly (signed-out requests were rejected), the WP REST introspection layer reported the endpoint as “publicly accessible,” which the reviewer flagged. New Signdocs_Webhook::authorize() performs HMAC verification at the permission-check phase and returns WP_Error with a precise HTTP status (401 for invalid signatures, 500 for server-side misconfiguration). The handler is now responsible only for body parsing and event dispatch. No change to the wire contract — third-party callers (the SignDocs Brasil API server) see identical request / response behavior.

1.3.5

WP.org submission auto-scanner fix.

• Differentiated Plugin URI from Author URI. Both headers in signdocs-brasil.php were https://signdocs.com.br, which the WP.org submission auto-scanner rejects (the two URIs must be distinct or one omitted; per WP.org policy a Plugin URI is a page about this specific plugin and an Author URI is a page about the author). Plugin URI now points to the canonical GitHub repository (https://github.com/signdocsbrasil/signdocs-brasil-wordpress); Author URI remains the company site (https://signdocs.com.br). Once the plugin is approved on WP.org we may switch Plugin URI to the wordpress.org/plugins/signdocs-brasil/ page.

1.3.4

Plugin Check (PCP) hardening pass for WP.org submission. No runtime behavior changes — every fix in this release is either annotation, defensive cleanup, or removal of a benign-but-noisy header.

• Dropped Domain Path: /languages header — the plugin doesn’t ship .pot / .mo files yet (translations are loaded via WP.org’s automatic language packs once approved), and the empty languages/ folder doesn’t exist in the distribution zip. PCP rightly flagged the header as pointing to a non-existent path.
• wp_unslash() + explicit sanitization on every $_POST / $_SERVER read — added across class-signdocs-ajax.php and class-signdocs-woocommerce.php. The values were already being passed through sanitize_text_field() / absint() / sanitize_email() / esc_url_raw(), but wp_unslash() is the WPCS-canonical pattern and reviewers expect it.
• Documented phpcs:ignore annotations on the custom-table queries. AuditQuery, Logger, webhook controller, and uninstall.php all touch {$wpdb->prefix}signdocs_log (or $wpdb->postmeta for the webhook lookup). PCP’s WordPress.DB.DirectDatabaseQuery.* is unavoidable for plugins with their own tables — every annotation now states the table being touched and why core’s caching/query API doesn’t apply.
• AuditQuery dynamic-prepare pattern documented inline. WordPress.DB.PreparedSQL.InterpolatedNotPrepared and PreparedSQLPlaceholders.* warnings on AuditQuery::count() / select() are PCP false positives — the {$where} fragment is built only from Filters allow-listed columns and the {$orderBy} / {$order} are validated against ALLOWED_ORDER_COLUMNS and validatedOrder(). Annotated explicitly so future readers (and reviewers) don’t have to re-discover this.
• wp_enqueue_script for the CDN-hosted browser SDK now passes a version arg instead of null (includes/class-signdocs-shortcode.php:140). The CDN already serves immutable v1-pinned bundles, but a version argument silences PCP’s EnqueuedResourceParameters.MissingVersion and keeps the dev-tools network panel readable.

Plugin Check status after this release: 0 ERRORs, ~30 WARNINGs (down from 79; remaining warnings are documented false positives — webhook HMAC-vs-nonce, server-side hooks, plugin-specific custom-table queries, and the local-vs-global naming heuristic).

1.3.3

Cleanup pass after the v1.3.2 acceptance run.

• wp signdocs webhook-test actually works. The SDK’s typed WebhookTestResponse model expects {deliveryId, status, statusCode} but the API returns {webhookId, testDelivery: {httpStatus, success, timestamp}}, so the typed call returned all-empty fields. CLI now bypasses the typed wrapper and reads the raw response, printing the real HTTP status + delivery timestamp. SDK fix tracked separately; the CLI unblocks operators today.
• Dispatcher: dropped dead SIGNING_SESSION.* branches. The OpenAPI spec lists these but the server never emits them — the lifecycle is communicated entirely through the corresponding TRANSACTION.* events. Same cleanup applied to the legacy webhook controller in includes/. No behavior change; just removes confusion for anyone reading the dispatch table.
• Audit log writes on success, not just on warnings. A webhook.completed info row now lands in signdocs_log for every TRANSACTION.COMPLETED, capturing transaction ID, evidence ID, and the matched CPT post ID. Brings the table in line with the readme’s “every API call recorded” claim.
• WP-CLI webhook-test and log-tail now register with their dashed names as documented in the class header (previously the _ form silently took precedence).

1.3.2

Two production-acceptance fixes uncovered while running the v1.3.1 release against real HML webhooks and the verify admin UI.

• Webhook dedup keyed off the wrong identifier — X-SignDocs-Webhook-Id carries the subscription ID (wh_*), not a per-delivery ID. The previous dedup transient used that header as the key, so the first delivery for a subscription poisoned the cache for the full 7-day TTL and every subsequent webhook (including TRANSACTION.COMPLETED) returned 200/deduped without ever reaching the dispatcher. CPT records stayed stuck in PENDING. Now keys off the body’s top-level id (the actual delivery ID, del_*).
• Custom capabilities resolved to do_not_allow — the envelope CPT’s 'capabilities' map remapped read_post/edit_post to signdocs_verify/signdocs_send/signdocs_manage, which registered them in WordPress’s $post_type_meta_caps table as meta caps. Core’s map_meta_cap() then short-circuited them to do_not_allow whenever called without a post argument — so even an administrator got HTTP 403 on the Verify admin page. Switched the envelope CPT to a custom capability_type and translate the generated CPT-cap names to the four primitive signdocs_* caps via Capabilities::mapMetaCap.
• Verified end-to-end against HML: full create → sign → TRANSACTION.COMPLETED webhook → CPT updated to COMPLETED with evidenceId → verification->verify($evidenceId) returns the signed evidence record (CPF, policy, completion timestamp).

1.3.1

WP.org submission readiness — Plugin Check (PCP) baseline + canonical English readme + complete CPF/CNPJ collection.

• Plugin Check: 0 ERRORs — fixed 12 PCP error-level findings: 4× missing defined('ABSPATH') guards in src/Admin/{VerifyPage,AuditTable}.php, src/Cpt/EnvelopeCpt.php, src/Webhook/Controller.php; 3× missing translators: comments on __() calls with placeholders in WooCommerce integration; 2× output escape gaps in WooCommerce email body; 1× output escape gap on the CPT status badge (now via wp_kses_post()); strip_tags() → wp_strip_all_tags() in the unit-test fallback path of Filters; documented fopen / fwrite / fclose in AuditExport as a streaming-CSV pattern with file-scoped phpcs:ignore.
• Canonical readme rewritten in English. WP.org policy 2025-07-28 requires the description, short description, and FAQ to be in English. The old Portuguese sections move to the standard i18n flow — pt_BR site visitors will see the localized strings via WordPress.org’s automatic translation pack delivery once the plugin is approved.
• Removed load_plugin_textdomain() — discouraged since WordPress 4.6 for plugins on WP.org. WordPress core auto-loads the right language pack from the plugin slug.
• CPF / CNPJ collection at every entry point — the SignDocs API requires signer.cpf or signer.cnpj at session-create time. Added to: shortcode form (when show_form="true"), AJAX handler validation, frontend JS payload, wp signdocs send --cpf= / --cnpj= flags, WooCommerce integration (reads _billing_cpf / _billing_cnpj from order meta — works with the standard “Brazilian Market on WooCommerce” extension), envelope service per-signer.
• wp signdocs send outputs the full shareable URL — previously printed only the base session URL, which is not directly usable. Now appends ?cs=<clientSecret> (URL-encoded) so the printed link can be opened directly to start signing.
• wp signdocs status now requires --client-secret — documented the embed-token authentication contract. Full implementation deferred to a follow-up release.
• Acceptance test against real HML: WP 6.9.x + MariaDB 11 in podman, plugin installed from the v1.3.1 zip, real HML credentials. Confirmed: signingSessions->create returns a valid sessionId + clientSecret + url; envelopes->create returns a valid envelopeId (PARALLEL, 2 signers); WP-CLI validates CPF/CNPJ inputs correctly; capabilities install on activation; plugin co-active with WooCommerce 10.7.

1.3.0

Alignment with PHP SDK 1.4.0 + complete English readme.

• PHP SDK upgraded to ^1.4 — SDK 1.4.0 fixed a model-shape divergence in CreateSigningSessionRequest / CreateEnvelopeRequest that had existed since 1.0.0: the correct field names accepted by the API are purpose, policy, signer, document, returnUrl, cancelUrl, metadata, locale, expiresInMinutes, appearance. Plugin call sites (CLI + AJAX) were updated.
• CPF / CNPJ collection at every entry point — the API requires signer.cpf or signer.cnpj at session creation. The shortcode form now exposes CPF + CNPJ fields when show_form="true"; the AJAX handler validates them; wp signdocs send accepts --cpf / --cnpj; the WooCommerce integration reads _billing_cpf / _billing_cnpj from the order (Brazilian Market on WooCommerce extension keys); the envelope service propagates per-signer CPF.
• Readme rewritten in English — per WP.org policy from 2025-07-28, the canonical readme description must be in English. Portuguese localization is loaded automatically from the bundled .po / .mo translation files for pt_BR sites.
• Plugin Check (PCP) errors fixed — direct file access guards (defined('ABSPATH')) added to 4 source files; missing translators: comments added to 3 __() calls with placeholders; output escaping tightened in WooCommerce email and CPT badge rendering; strip_tags() swapped for wp_strip_all_tags() in non-test paths.
• “Tested up to” updated to WordPress 6.9 (the version used in the automated pen test).

1.2.3

Security sniff cleanup — zero phpcs:ignore comments in source.

• Consolidated exceptions — the 7 remaining WPCS findings that can’t be fixed through refactor (MySQL doesn’t allow identifier placeholders; custom tables can’t use WP_Query; admin audit logs shouldn’t be cached; list-table pagination doesn’t nonce in WP convention) are now declared as file-scoped exclusions in phpcs.xml.dist with written rationale for each. Zero line-level phpcs:ignore comments remain in src/.
• EventRouter::queryByMeta refactored — dropped the direct $wpdb->postmeta lookup in favor of get_posts(['meta_query' => …, 'fields' => 'ids']). Slightly safer (adds post-type filter), eliminates two DirectDatabaseQuery warnings without suppression.
• Filters::fromRequest signature tightened — no longer falls back to $_REQUEST when called without arguments; callers must pass the request array explicitly. Moves the superglobal read-site up to the admin page, where CSRF/capability context is clear.
• Net result: zero security-category PHPCS findings, zero phpcs:ignore suppressions, and every exception documented in one auditable file.

1.2.2

Security audit + refactor.

• AuditQuery refactor — all raw SQL extracted into src/Admin/AuditQuery.php. New src/Admin/Filters.php value object enforces validation at its constructor, so by the time AuditQuery sees a value it’s already allow-list-checked. AuditTable, AuditExport, and SigndocsCommand::log_tail are now thin consumers with zero raw SQL.
• SQL-injection fuzz test suite — tests/Unit/AuditQueryFuzzTest.php runs 24 SQL-injection payloads across every filter field (level, event_type, from, to, orderby, order) and asserts that every payload is either rejected by the allow-list or survives only via %s placeholders — never into a SQL literal. 47 total unit tests / 552 assertions, all green.
• Black-box pen test — tests/pen_test.sh exercises a running WordPress 6.9.x + MariaDB 11 stack (podman pod). Tests SQLi across audit filters + CSV export, webhook HMAC bypass attempts (no-sig, wrong-sig, stale-ts, garbage-ts, valid-sig, replay-dedup), CSRF on admin-post.php, and subscriber-role authorization against the audit log. All checks passed — runtime behavior matches the phpcs:ignore justifications.

1.2.1

WP.org submission-readiness pass.

• phpcbf auto-fixed ~3,300 cosmetic WPCS findings; remaining ~370 are pure style (snake_case / Yoda) and annotated as advisory in CI.
• Audited and annotated the 26 security-adjacent PHPCS findings (nonce verification, prepared SQL) — all verified as safe with justifying phpcs:ignore comments.
• Added .wordpress-org/ asset bundle: icon-256, icon-128, and auto-generated branded banner-1544×500 / banner-772×250 (designer should replace banners before public launch).
• Added .github/workflows/wp-org-deploy.yml — 10up/action-wordpress-plugin-deploy on tag push, gated by the DEPLOY_TO_WPORG repo variable so it’s a no-op until WP.org approves.
• Added DEPLOY.md runbook for the WP.org submission and release flow.

1.2.0

Enterprise feature parity with the external API.

• Envelopes multi-signatário — new signdocs_envelope CPT (parent of signdocs_signing), EnvelopeService wrapping the SDK’s envelope resource, deterministic idempotency keys on create. Sequential and parallel signing flows.
• Verification admin UI — “Verificar” submenu under SignDocs, accepts an evidence ID or envelope ID and renders signer identities, tenant CNPJ, consolidated downloads (.p7s or combined PDF). Uses SDK 1.3.0’s verifyEnvelope.
• Private Key JWT auth — alternative to client_secret. Store a PEM-encoded ES256 private key + key ID; ClientFactory branches on signdocs_auth_method. Preferred by regulated customers who can’t store shared secrets at rest.
• Audit log UI — WP_List_Table over wp_signdocs_log with filters (level, event type, date range) and CSV export, gated by signdocs_view_logs. CSV streams from php://output with chunked reads — safe for multi-GB exports.
• Rotação do segredo de webhook — SecretResolver accepts both the primary and a previous secret during a 7-day grace window. Daily cron signdocs_expire_prev_secret clears the previous secret once the window expires. Controller’s authorize step tries each configured secret before rejecting.

1.1.0

Hardening release + alignment with SignDocs PHP SDK 1.3.0.

• Shared OAuth token cache — SDK TokenCacheInterface is implemented by WpTransientTokenCache, so a single token is reused across every PHP-FPM worker instead of one token fetch per request.
• Webhook hardening — timestamp drift gate (≤300s), replay de-duplication via X-SignDocs-Webhook-Id transient lock (7-day TTL), proper permission_callback that runs HMAC before any business logic, input-shape guard on session / transaction IDs.
• Full webhook coverage — added TRANSACTION.CREATED, TRANSACTION.FALLBACK, STEP.STARTED/COMPLETED/FAILED, QUOTA.WARNING, API.DEPRECATION_NOTICE, plus the two NT65 INSS-consignado events STEP.PURPOSE_DISCLOSURE_SENT and TRANSACTION.DEADLINE_APPROACHING. Covers the 13 events the server actually emits today.
• Observability — Deprecation / Sunset (RFC 8594) response headers surface as admin notices; RateLimit-* headers are captured in a transient for the dashboard widget; structured log table {prefix}signdocs_log with 30-day retention and a daily cron prune.
• Idempotency — X-Idempotency-Key is now sent on every resource-creating call, derived deterministically from site URL + user + action + resource, so AJAX retries no longer create duplicate sessions.
• Capability model — four new caps (signdocs_manage, signdocs_send, signdocs_verify, signdocs_view_logs) instead of raw manage_options / edit_posts. Granted to administrator / editor / author on activation via Capabilities::install(); map_meta_cap wires them to CPT operations.
• LGPD / GDPR — wp_privacy_personal_data_exporters and wp_privacy_personal_data_erasers are registered. The eraser redacts signer name + email but preserves evidence IDs and completion timestamps for legal retention.
• WP-CLI — wp signdocs health|send|status|webhook-test|log-tail.
• Test suite — PHPUnit (Brain Monkey unit tests), PHPStan level 5 (with phpstan-wordpress), PHPCS (WordPress-Extra + PHPCompatibilityWP), GitHub Actions matrix on PHP 8.1 / 8.2 / 8.3.

1.0.0

• Initial release
• [signdocs] shortcode with 8 configurable attributes
• Gutenberg block with live preview (ServerSideRender)
• signdocs_signing custom post type with status, signer, and policy columns
• REST webhook receiver with HMAC-SHA256 verification
• WooCommerce integration: product tab, automatic email, order notes
• AES-256-CBC encryption for stored credentials
• Popup, redirect, and overlay support
• Rate limiting for anonymous signing
• Trilingual: pt-BR, en, es