<?php
/**
 * Consent declaration — AnswerRails (#259).
 *
 * Design: docs/design/CMP_COEXISTENCE_DESIGN.md (D1, D2). Input: #257.
 *
 * WHAT THIS IS. AnswerRails declares itself to the WordPress ecosystem's
 * consent standard (the WP Consent API) and to Complianz, so a consent
 * manager can classify our browser storage instead of bucketing it as an
 * "Unknown Service" and so its script blocker steps aside.
 *
 * ⚠ WHAT THIS IS NOT. It is a DECLARATION, not a fix for the 2026-08-21
 * observation on answerrails.com. That failure has never been reproduced and
 * the design's §1.6 records four things standing against its stated cause.
 * Nothing here may be described as fixing it.
 *
 * 📌 A BLOCKLIST ASSEMBLED FROM RECOGNISED PLUGINS CANNOT BLOCK AN
 * UNRECOGNISED ONE. Complianz blocks what it KNOWS: its blocked-script list is
 * assembled from the 106 per-plugin integration files it ships, each gated on
 * a detection entry. With no integration of ours in that registry its wizard
 * reports "We found 0 active plugin integrations" — so the remedy is to
 * become recognised, not to hide.
 *
 * 🔴 THE WP CONSENT API IS A PLUGIN, NOT CORE. It lives in the WordPress
 * GitHub organisation and describes itself as "Planned for adoption to
 * WordPress Core", but it is absent from the Roadmap to 7.1. Every call into
 * it sits behind function_exists(). A hard dependency here would recreate the
 * exact failure mode this issue exists to end, and no copy may call it a
 * WordPress core API.
 *
 * 🔴 WE DESCRIBE, WE DO NOT CLAIM TO OBEY — amendment A1, 2026-08-26 (design
 * §"Amendment A1"). AnswerRails deliberately does NOT answer the API's
 * per-plugin registration filter, `wp_consent_api_registered_{basename}`.
 * Answering it true is, in that API's model, a claim that we check consent
 * before we act — and we call wp_has_consent() nowhere, so the claim had
 * nothing behind it. It is withdrawn. What stays is the half that was always
 * accurate: wp_add_cookie_info() describing our seven storage entries.
 * 📌 A DECLARATION YOU CANNOT HONOUR IS NOT A DECLARATION, IT IS A CLAIM.
 * ⚠ Do not re-add the registration to "complete" this class. Honouring a
 * consent decision is #273, and it needs its own design.
 *
 * ⚠ THE COMPLIANZ REGISTRATION BELOW IS A DIFFERENT MECHANISM AND STAYS.
 * cmplz_integrations declares our IDENTITY to Complianz's registry so we stop
 * being an unrecognised plugin; it makes no claim about honouring consent.
 * Verified in the field 2026-08-26 — Complianz's wizard moved from "We found
 * 0 active plugin integrations" to "We found 1 … → AnswerRails".
 *
 * @package AnswerRails
 */

// Prevent direct access
if (!defined('ABSPATH')) {
    exit;
}

class AnswerRails_Consent_Declaration {

    /**
     * Consent categories, as the WP Consent API names them.
     *
     * Our storage is functional and preferences — see storage_keys().
     *
     * 🔴 CORRECTION TO THE DESIGN, read from the shipped API rather than
     * inferred. The design's §1.5 and D1 state that `wp_has_consent()` "returns
     * true for `functional` regardless of consent state". **It does not.**
     * `inc/api-functions.php:176` special-cases no category: it returns true
     * only when there is no consent management at all, or the consent type is
     * opt-out with no cookie set, or the category's cookie reads `allow`. On an
     * opt-in (GDPR) site before the visitor answers the banner, it returns
     * FALSE for `functional` exactly as it does for `preferences`.
     *
     * ⚠ Consequence, and only HALF of it is closed. We call `wp_has_consent()`
     * nowhere, so the two `preferences` entries are still written after a
     * refusal. That gap is open and is **#273**, which needs its own design:
     * consent state has to reach JS, refusal needs defined behaviour, and it
     * interacts with our own consent gate.
     *
     * What amendment A1 (2026-08-26) closed is the other half — the CLAIM. We
     * no longer answer `wp_consent_api_registered_{basename}` true, so we are
     * no longer asserting that we honour consent while #273 is open. 📌 A
     * DECLARATION YOU CANNOT HONOUR IS NOT A DECLARATION, IT IS A CLAIM.
     * ⚠ Reclassifying these two keys to `functional` would NOT close #273 —
     * `wp_has_consent('functional')` is also false pre-banner on an opt-in
     * site, so it changes the label and nothing else. (Codex P1, PR #269;
     * ruled 2026-08-26.)
     */
    const CATEGORY_FUNCTIONAL  = 'functional';
    const CATEGORY_PREFERENCES = 'preferences';

    /**
     * The service name every declared item is attributed to. This is the
     * string a CMP prints in the site's cookie policy in place of "Unknown
     * Service" (#257's finding), so it is the product name, not the slug.
     */
    const SERVICE_NAME = 'AnswerRails';

    /**
     * The WP Consent API's storage TYPE for everything we declare.
     *
     * 🔴 THIS IS THE FIELD THAT SAYS "NOT A COOKIE", AND IT IS STRUCTURAL.
     * `wp_add_cookie_info()`'s `$type` accepts exactly `'HTTP'`, `'LOCALSTORAGE'`
     * or `'API'` (`class-wp-consent-api-cookie-info.php:82`) — **and it defaults
     * to `'HTTP'`.** Omitting it therefore declares our seven browser-storage
     * entries to every CMP as HTTP cookies, which is the precise error #257
     * exists to correct, reintroduced inside the remedy for it. Prose in a
     * description field does not fix that; this argument does. (Codex P1, PR
     * #269.)
     *
     * `LOCALSTORAGE` is the API's single browser-storage bucket and covers our
     * `sessionStorage` entries too — the three-value enum has no finer grade,
     * and the per-mode lifetime is carried in each entry's `expires`.
     */
    const STORAGE_TYPE = 'LOCALSTORAGE';

    /**
     * Our slug in Complianz's integration registry.
     */
    const COMPLIANZ_INTEGRATION_SLUG = 'answerrails';

    /**
     * Our frontend script handles — BOTH bundles.
     *
     * The design named only the widget; the second bundle
     * (`answerrails-privacy-controls`, enqueued alongside it in
     * AnswerRails_Core::enqueue_frontend_assets()) is equally ours and equally
     * in need of the attribute. A blocker that skips one and neutralises the
     * other leaves the storage-policy enforcer dead while the widget runs,
     * which is the worse half to lose.
     */
    const FRONTEND_HANDLES = array(
        'answerrails-chat-widget',
        'answerrails-privacy-controls',
    );

    /**
     * The browser storage AnswerRails writes, as declared to the WP Consent API.
     *
     * ⚠ SEVEN KEYS, NOT EIGHT — and none of them are cookies. #257 enumerated
     * eight and named `answerrails-chat-minimized` as the eighth, citing
     * chat-widget.js:512. That line, at the very tree #257 read (v0.1.3), is
     *
     *     this.elements.widget.addClass('is-open').removeClass('answerrails-chat-minimized');
     *
     * — a CSS class on the widget element, not a storage write. The minimised
     * state has never been persisted. A full enumeration of every
     * localStorage/sessionStorage/storeGet/storeSet/storeRemove call across
     * this plugin's scripts, those of AnswerRails Pro, and admin returns
     * the seven below and nothing
     * else. Declaring a key we do not write would be a false statement in a
     * compliance artefact, which is the one own goal a compliance product
     * cannot afford. #257's body carries the correction.
     *
     * The first five are conversation data, governed by the `privacy_mode`
     * setting: `local` puts them in localStorage, `session` in sessionStorage,
     * and `none` means nothing is persisted at all. The last two are interface
     * preferences, deliberately exempt from those modes (widget geometry is
     * interface state, not conversation data — `UI_PREFERENCE_KEYS` in
     * assets/js/privacy-controls.js) and always localStorage.
     *
     * All seven are first-party, same-origin, and never leave the browser.
     *
     * @return array
     */
    public static function storage_keys() {
        // ⚠ LIFETIMES ARE STATED AS THEY ACTUALLY BEHAVE, INCLUDING ON THE
        // DEFAULT CONFIGURATION. An earlier cut said every conversation entry
        // was "cleared when the privacy mode retention window elapses", which
        // promised a deletion that does not happen: `answerrails_privacy_ttl`
        // defaults to 0, `checkAndCleanExpiredData()` returns immediately when
        // it is <= 0, and even with a timer set that sweep removes ONLY the
        // `answerrails-conversation-*` transcript — not the other four. A
        // consent policy that promises deletion nobody performs is the same
        // class of false statement as calling these cookies. (Codex P2, PR
        // #269.) 📌 COMPLIANCE COPY IS NOT CUSTOMER COPY.
        $mode_lifetime = __('Under the default "session" privacy mode, until the browser session ends; under "local", until the visitor clears site data; under "none", never stored at all.', 'answerrails');

        $conversation_expires = $mode_lifetime . ' ' . __('The owner\'s auto-clear timer is off by default and does not remove this entry.', 'answerrails');
        $transcript_expires   = $mode_lifetime . ' ' . __('If the site owner enables the auto-clear timer (off by default), also removed after that period of inactivity.', 'answerrails');
        $preference_expires   = __('Stored in localStorage regardless of privacy mode, and kept until the visitor clears site data.', 'answerrails');

        // ⚠ The API's `$collected_personal_data` slot. Ours is genuinely empty
        // for six of the seven — a random identifier is not personal data — and
        // the seventh is honest about the one case where it is not, because the
        // visitor decides what they type into a chat.
        $collected_none = __('None. This entry holds no personal data.', 'answerrails');

        return array(
            'answerrails-session-id' => array(
                'category'  => self::CATEGORY_FUNCTIONAL,
                'expires'   => $conversation_expires,
                'function'  => __('Identifies this visitor\'s chat session so their conversation stays their own. Cryptographically random; not an account identifier and not a tracking identifier.', 'answerrails'),
                'collected' => $collected_none,
            ),
            'answerrails-session-token' => array(
                'category'  => self::CATEGORY_FUNCTIONAL,
                'expires'   => $conversation_expires,
                'function'  => __('Authorises this visitor to add to their own conversation, and nobody else to. Presented on chat and consent requests.', 'answerrails'),
                'collected' => $collected_none,
            ),
            'answerrails-conversation-<sessionId>' => array(
                'category'  => self::CATEGORY_FUNCTIONAL,
                'expires'   => $transcript_expires,
                'function'  => __('Keeps this visitor\'s copy of the conversation so the thread survives a page reload. One entry per session identifier.', 'answerrails'),
                'collected' => __('Whatever the visitor chooses to type into the chat, which may include personal data. Held in their own browser and never read from it by this plugin.', 'answerrails'),
            ),
            'answerrails-consent' => array(
                'category'  => self::CATEGORY_FUNCTIONAL,
                'expires'   => $conversation_expires,
                'function'  => __('Remembers that this visitor accepted the chat disclaimer, so they are not asked again. The authoritative record is the server-side consent receipt.', 'answerrails'),
                'collected' => $collected_none,
            ),
            'answerrails-last-activity' => array(
                'category'  => self::CATEGORY_FUNCTIONAL,
                'expires'   => $conversation_expires,
                'function'  => __('Records when this visitor was last active in the chat, so the owner\'s auto-clear timer knows when the conversation went idle.', 'answerrails'),
                'collected' => $collected_none,
            ),
            'answerrails-window-size' => array(
                'category'  => self::CATEGORY_PREFERENCES,
                'expires'   => $preference_expires,
                'function'  => __('Remembers the size this visitor resized the chat window to, so it opens the same way next time.', 'answerrails'),
                'collected' => $collected_none,
            ),
            'answerrails-window-position' => array(
                'category'  => self::CATEGORY_PREFERENCES,
                'expires'   => $preference_expires,
                'function'  => __('Remembers where this visitor dragged the chat window to, so it opens where they left it.', 'answerrails'),
                'collected' => $collected_none,
            ),
        );
    }

    /**
     * Wire the declaration up.
     *
     * The storage declaration rides `wp_loaded` because the WP Consent API is
     * not there to receive it any earlier. It is guarded, so the hook being
     * present with the API absent costs one no-op call and nothing else.
     *
     * ⚠ There is deliberately no `plugins_loaded` hook here. It existed only to
     * answer the API's registration filter, which amendment A1 withdrew — see
     * the class docblock.
     */
    public function __construct() {
        add_filter('script_loader_tag', array(__CLASS__, 'add_consent_category_attribute'), 10, 3);

        add_action('wp_loaded', array(__CLASS__, 'declare_storage'));

        add_filter('cmplz_integrations', array(__CLASS__, 'register_complianz_integration'));
        add_filter('cmplz_integration_path', array(__CLASS__, 'complianz_integration_path'), 10, 2);
    }

    /**
     * D1b — describe what we store, once, for every CMP that reads the API.
     *
     * 🔴 The guard is the point. wp_add_cookie_info() ships with the WP Consent
     * API PLUGIN. With that plugin absent — which is the overwhelmingly common
     * case, and the case every existing install is in — this method returns
     * having done nothing, and AnswerRails behaves byte-identically to the way
     * it did before #259. Removing this guard turns an optional integration
     * into a fatal error on every page load. ConsentDeclarationTest pins that
     * property in a subprocess with the function genuinely undefined.
     */
    public static function declare_storage() {
        if (!function_exists('wp_add_cookie_info')) {
            return;
        }

        foreach (self::storage_keys() as $key => $info) {
            // The signature, read from the shipped API and not from memory
            // (`inc/api-functions.php:392`, v2.0.1):
            //
            //   wp_add_cookie_info( $name, $plugin_or_service, $category,
            //       $expires, $cookie_function, $collected_personal_data = '',
            //       $member_cookie = false, $administrator_cookie = false,
            //       $type = 'HTTP', $domain = '' )
            //
            // 🔴 THERE IS NO $description PARAMETER. An earlier cut passed our
            // description as the sixth argument, where it landed in
            // `collectedPersonalData` — so every entry told the CMP it collected
            // whatever that sentence said, and the `$type` default of `'HTTP'`
            // declared all seven as HTTP cookies. Both are the #257 error
            // reintroduced inside its own remedy. (Codex P1, PR #269.)
            //
            // $domain is omitted deliberately: the API defaults it to
            // site_url(), which is exactly right — every entry is first-party.
            wp_add_cookie_info(
                $key,
                self::SERVICE_NAME,
                $info['category'],
                $info['expires'],
                $info['function'],
                $info['collected'],
                false,
                false,
                self::STORAGE_TYPE
            );
        }
    }

    /**
     * D2a — put `data-category="functional"` on our own frontend script tags.
     *
     * Complianz's cookie blocker skips a tag carrying this attribute before it
     * reaches any pattern matching at all (class-cookie-blocker.php:726), which
     * makes it the cheapest and most direct of the four mechanisms in the
     * design's §1.2 table — and the only one that needs no cooperation from
     * anybody.
     *
     * ⚠ The attribute is emitted through WordPress's script loader, never by
     * string concatenation at the enqueue site. Handles not ours are returned
     * untouched: a filter that decorated other plugins' tags would be making a
     * consent claim on their behalf.
     *
     * @param string $tag    The full script tag WordPress is about to print.
     * @param string $handle The registered handle.
     * @param string $src    The script source (unused; part of core's signature).
     * @return string
     */
    public static function add_consent_category_attribute($tag, $handle, $src = '') {
        unset($src);

        if (!is_string($tag) || !in_array($handle, self::FRONTEND_HANDLES, true)) {
            return $tag;
        }

        if (strpos($tag, 'data-category=') !== false) {
            return $tag;
        }

        return preg_replace(
            '/<script(?=[\s>])/',
            '<script data-category="' . self::CATEGORY_FUNCTIONAL . '"',
            $tag,
            1
        );
    }

    /**
     * D2b — register AnswerRails in Complianz's integration registry.
     *
     * The registry is a filter, so we ship our own entry from inside
     * AnswerRails and Complianz never has to accept a pull request. The
     * detection entry names a constant of ours, exactly as Complianz's own 106
     * shipped integrations do.
     *
     * @param array $integrations Complianz's registry, keyed by slug.
     * @return array
     */
    public static function register_complianz_integration($integrations) {
        if (!is_array($integrations)) {
            return $integrations;
        }

        $integrations[self::COMPLIANZ_INTEGRATION_SLUG] = array(
            'constant_or_function' => 'ANSWERRAILS_VERSION',
            'label'                => self::SERVICE_NAME,
        );

        return $integrations;
    }

    /**
     * D2c — tell Complianz where our integration file lives.
     *
     * ⚠ FAIL CLOSED TO A NO-OP, NEVER INTO BREAKING THE CMP. If this filter's
     * real signature does not carry the plugin slug, $plugin arrives empty, the
     * guard below declines, and Complianz keeps whatever path it had. The cost
     * of that is our integration file not loading — a live leg catches it. The
     * cost of the other posture, returning our path unconditionally, would be
     * redirecting every OTHER integration's load to our file, i.e. breaking the
     * consent manager on behalf of the site. One of those failures is ours to
     * absorb; the other is not.
     *
     * @param string $path   The path Complianz resolved.
     * @param string $plugin The integration slug being loaded.
     * @return string
     */
    public static function complianz_integration_path($path, $plugin = '') {
        if (self::COMPLIANZ_INTEGRATION_SLUG !== $plugin) {
            return $path;
        }

        return ANSWERRAILS_PLUGIN_DIR . 'includes/integrations/complianz-answerrails.php';
    }
}