diff --git a/class-two-factor-core.php b/class-two-factor-core.php index a9dfbaa9..7c9df193 100644 --- a/class-two-factor-core.php +++ b/class-two-factor-core.php @@ -157,6 +157,8 @@ public static function add_hooks( $compat ) { add_action( 'login_enqueue_scripts', array( __CLASS__, 'login_enqueue_scripts' ), 5 ); add_action( 'admin_init', array( __CLASS__, 'trigger_user_settings_action' ) ); add_action( 'admin_init', array( __CLASS__, 'add_privacy_policy_content' ) ); + add_filter( 'wp_privacy_personal_data_exporters', array( __CLASS__, 'register_privacy_exporter' ) ); + add_filter( 'wp_privacy_personal_data_erasers', array( __CLASS__, 'register_privacy_eraser' ) ); add_filter( 'two_factor_providers', array( __CLASS__, 'enable_dummy_method_for_debug' ) ); // Add Settings link to plugin action links. @@ -2966,4 +2968,215 @@ public static function add_privacy_policy_content() { wp_kses_post( wpautop( $content, false ) ) ); } + + /** + * Register the personal data exporter. + * + * @since 0.17.0 + * + * @param array $exporters Registered exporters. + * + * @return array + */ + public static function register_privacy_exporter( $exporters ) { + $exporters['two-factor'] = array( + 'exporter_friendly_name' => __( 'Two-Factor Authentication', 'two-factor' ), + 'callback' => array( __CLASS__, 'privacy_export' ), + ); + + return $exporters; + } + + /** + * Register the personal data eraser. + * + * @since 0.17.0 + * + * @param array $erasers Registered erasers. + * + * @return array + */ + public static function register_privacy_eraser( $erasers ) { + $erasers['two-factor'] = array( + 'eraser_friendly_name' => __( 'Two-Factor Authentication', 'two-factor' ), + 'callback' => array( __CLASS__, 'privacy_erase' ), + ); + + return $erasers; + } + + /** + * Export a user's two-factor data for a personal data request. + * + * Credentials are described, never disclosed: the TOTP secret is reported as + * configured and backup codes as a remaining count. Nothing here is enough to + * pass a second factor if the export is intercepted. + * + * @since 0.17.0 + * + * @param string $email_address Email address of the data subject. + * @param int $page Page of results, 1-indexed. + * + * @return array + */ + public static function privacy_export( $email_address, $page = 1 ) { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed -- Exporter signature includes the page number, but all data fits in a single page. + $user = get_user_by( 'email', $email_address ); + + if ( ! $user ) { + return array( + 'data' => array(), + 'done' => true, + ); + } + + $data = array(); + + $enabled_providers = self::get_enabled_providers_for_user( $user ); + if ( ! empty( $enabled_providers ) ) { + $data[] = array( + 'name' => __( 'Enabled two-factor methods', 'two-factor' ), + 'value' => implode( ', ', $enabled_providers ), + ); + } + + $primary_provider = get_user_meta( $user->ID, self::PROVIDER_USER_META_KEY, true ); + if ( $primary_provider ) { + $data[] = array( + 'name' => __( 'Primary two-factor method', 'two-factor' ), + 'value' => $primary_provider, + ); + } + + $failed_attempts = get_user_meta( $user->ID, self::USER_FAILED_LOGIN_ATTEMPTS_KEY, true ); + if ( $failed_attempts ) { + $data[] = array( + 'name' => __( 'Failed two-factor attempts', 'two-factor' ), + 'value' => (string) (int) $failed_attempts, + ); + } + + $last_failure = get_user_meta( $user->ID, self::USER_RATE_LIMIT_KEY, true ); + if ( $last_failure ) { + $data[] = array( + 'name' => __( 'Last failed two-factor attempt', 'two-factor' ), + 'value' => self::format_privacy_timestamp( $last_failure ), + ); + } + + foreach ( self::get_providers() as $provider ) { + if ( ! method_exists( $provider, 'privacy_export_data' ) ) { + continue; + } + + $data = array_merge( $data, $provider->privacy_export_data( $user ) ); + } + + if ( empty( $data ) ) { + return array( + 'data' => array(), + 'done' => true, + ); + } + + return array( + 'data' => array( + array( + 'group_id' => 'two-factor', + 'group_label' => __( 'Two-Factor Authentication', 'two-factor' ), + 'item_id' => 'two-factor-' . $user->ID, + 'data' => $data, + ), + ), + 'done' => true, + ); + } + + /** + * Format a stored Unix timestamp for inclusion in a personal data export. + * + * @since 0.17.0 + * + * @param int|string $timestamp Unix timestamp. + * + * @return string + */ + public static function format_privacy_timestamp( $timestamp ) { + return wp_date( get_option( 'date_format' ) . ' ' . get_option( 'time_format' ), (int) $timestamp ); + } + + /** + * Erase a user's incidental two-factor records for a personal data request. + * + * Login nonces, failed-attempt counters, rate-limit timestamps and pending + * tokens are removed. Credentials — enabled methods, the TOTP secret, backup + * codes — are retained and reported as such, because erasing them would turn + * off the second factor on a live account without the account holder asking + * for that. They are removed when the account is deleted. + * + * @since 0.17.0 + * + * @param string $email_address Email address of the data subject. + * @param int $page Page of results, 1-indexed. + * + * @return array + */ + public static function privacy_erase( $email_address, $page = 1 ) { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed -- Eraser signature includes the page number, but all erasure happens in a single page. + $response = array( + 'items_removed' => false, + 'items_retained' => false, + 'messages' => array(), + 'done' => true, + ); + + $user = get_user_by( 'email', $email_address ); + + if ( ! $user ) { + return $response; + } + + $meta_keys = array( + self::USER_META_NONCE_KEY, + self::USER_RATE_LIMIT_KEY, + self::USER_FAILED_LOGIN_ATTEMPTS_KEY, + self::USER_PASSWORD_WAS_RESET_KEY, + ); + + foreach ( self::get_providers() as $provider ) { + if ( ! method_exists( $provider, 'privacy_eraser_user_meta_keys' ) ) { + continue; + } + + $meta_keys = array_merge( $meta_keys, $provider->privacy_eraser_user_meta_keys() ); + } + + foreach ( array_unique( $meta_keys ) as $meta_key ) { + if ( metadata_exists( 'user', $user->ID, $meta_key ) && delete_user_meta( $user->ID, $meta_key ) ) { + $response['items_removed'] = true; + } + } + + // Provider settings and credential meta remain in place. Check stored + // meta rather than enabled providers, since a configured provider may be + // disabled while its credential is still retained. + $retained_meta_keys = array( + self::PROVIDER_USER_META_KEY, + self::ENABLED_PROVIDERS_USER_META_KEY, + ); + + foreach ( self::get_providers() as $provider ) { + $provider_meta_keys = $provider::uninstall_user_meta_keys(); + $erased_meta_keys = $provider::privacy_eraser_user_meta_keys(); + $retained_meta_keys = array_merge( $retained_meta_keys, array_diff( $provider_meta_keys, $erased_meta_keys ) ); + } + + foreach ( array_unique( $retained_meta_keys ) as $meta_key ) { + if ( metadata_exists( 'user', $user->ID, $meta_key ) ) { + $response['items_retained'] = true; + $response['messages'][] = __( "Two-factor authentication credentials or settings were retained to avoid changing this account's authentication as part of a personal data erasure request. They are removed when the account is deleted.", 'two-factor' ); + break; + } + } + + return $response; + } } diff --git a/providers/class-two-factor-backup-codes.php b/providers/class-two-factor-backup-codes.php index bde9e7e1..ee7606c6 100644 --- a/providers/class-two-factor-backup-codes.php +++ b/providers/class-two-factor-backup-codes.php @@ -533,4 +533,28 @@ public static function uninstall_user_meta_keys() { self::BACKUP_CODES_META_KEY, ); } + + /** + * Report how many backup codes are left, never the codes or their hashes. + * + * @since 0.17.0 + * + * @param WP_User $user The user whose data is being exported. + * + * @return array + */ + public function privacy_export_data( $user ) { + $remaining = self::codes_remaining_for_user( $user ); + + if ( ! $remaining ) { + return array(); + } + + return array( + array( + 'name' => __( 'Backup codes remaining', 'two-factor' ), + 'value' => (string) $remaining, + ), + ); + } } diff --git a/providers/class-two-factor-email.php b/providers/class-two-factor-email.php index d93ec30b..65fa58a1 100644 --- a/providers/class-two-factor-email.php +++ b/providers/class-two-factor-email.php @@ -472,4 +472,48 @@ public static function uninstall_user_meta_keys() { self::TOKEN_META_KEY_TIMESTAMP, ); } + + /** + * Report a pending login code by the time it was issued, never by its value. + * + * Only a hash of the code is stored, and even that is withheld — a hash of a + * short numeric code is trivially reversible. + * + * @since 0.17.0 + * + * @param WP_User $user The user whose data is being exported. + * + * @return array + */ + public function privacy_export_data( $user ) { + if ( ! $this->user_has_token( $user->ID ) ) { + return array(); + } + + $issued = get_user_meta( $user->ID, self::TOKEN_META_KEY_TIMESTAMP, true ); + + return array( + array( + 'name' => __( 'Email login code', 'two-factor' ), + 'value' => $issued + /* translators: %s: date and time the login code was sent. */ + ? sprintf( __( 'A one-time login code was sent on %s. The code itself is not stored.', 'two-factor' ), Two_Factor_Core::format_privacy_timestamp( $issued ) ) + : __( 'A one-time login code is pending. The code itself is not stored.', 'two-factor' ), + ), + ); + } + + /** + * A pending login token is short-lived and incidental, so it is erased. + * + * @since 0.17.0 + * + * @return array + */ + public static function privacy_eraser_user_meta_keys() { + return array( + self::TOKEN_META_KEY, + self::TOKEN_META_KEY_TIMESTAMP, + ); + } } diff --git a/providers/class-two-factor-provider.php b/providers/class-two-factor-provider.php index 5659309b..38d00538 100644 --- a/providers/class-two-factor-provider.php +++ b/providers/class-two-factor-provider.php @@ -211,4 +211,38 @@ public static function uninstall_user_meta_keys() { public static function uninstall_options() { return array(); } + + /** + * Return this provider's contribution to a personal data export. + * + * Describe what is stored, never the credential itself: report a secret as + * configured rather than disclosing it, and a set of codes as a count. + * + * @since 0.17.0 + * + * @param WP_User $user The user whose data is being exported. + * + * @return array List of `array( 'name' => string, 'value' => string )` pairs. + */ + public function privacy_export_data( $user ) { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.Found -- Base implementation keeps the provider interface signature but has no data to export. + return array(); + } + + /** + * Return the user meta keys to delete on a personal data erasure request. + * + * This covers incidental login records only — pending tokens, counters and + * timestamps. Credential material is deliberately excluded, because erasing + * it would silently disable the second factor on a live account. It is + * removed with the account itself, and on plugin uninstall. + * + * @since 0.17.0 + * + * Note: this method doesn't have access to the instantiated provider object. + * + * @return array + */ + public static function privacy_eraser_user_meta_keys() { + return array(); + } } diff --git a/providers/class-two-factor-totp.php b/providers/class-two-factor-totp.php index 6160dbae..22377314 100644 --- a/providers/class-two-factor-totp.php +++ b/providers/class-two-factor-totp.php @@ -902,4 +902,39 @@ public static function uninstall_user_meta_keys() { self::LAST_SUCCESSFUL_LOGIN_META_KEY, ); } + + /** + * Report whether an authenticator app is configured, without disclosing the secret. + * + * @since 0.17.0 + * + * @param WP_User $user The user whose data is being exported. + * + * @return array + */ + public function privacy_export_data( $user ) { + if ( ! $this->get_user_totp_key( $user->ID ) ) { + return array(); + } + + return array( + array( + 'name' => __( 'Authenticator app (TOTP)', 'two-factor' ), + 'value' => __( 'Configured. The secret key itself is not included in this export.', 'two-factor' ), + ), + ); + } + + /** + * The replay-protection timestamp is incidental; the secret key is retained. + * + * @since 0.17.0 + * + * @return array + */ + public static function privacy_eraser_user_meta_keys() { + return array( + self::LAST_SUCCESSFUL_LOGIN_META_KEY, + ); + } } diff --git a/tests/class-two-factor-privacy.php b/tests/class-two-factor-privacy.php new file mode 100644 index 00000000..55049676 --- /dev/null +++ b/tests/class-two-factor-privacy.php @@ -0,0 +1,285 @@ +user = self::factory()->user->create_and_get( array( 'user_email' => 'privacy-subject@example.com' ) ); + } + + /** + * Flatten an exporter response into a name => value map. + * + * @param array $response Exporter response. + * @return array + */ + private function flatten_export( $response ) { + $flat = array(); + + foreach ( $response['data'] as $group ) { + foreach ( $group['data'] as $field ) { + $flat[ $field['name'] ] = $field['value']; + } + } + + return $flat; + } + + /** + * Run the registered exporter for the test user. + * + * @return array + */ + private function export() { + $exporters = apply_filters( 'wp_privacy_personal_data_exporters', array() ); + + return call_user_func( $exporters['two-factor']['callback'], $this->user->user_email, 1 ); + } + + /** + * Run the registered eraser for the test user. + * + * @return array + */ + private function erase() { + $erasers = apply_filters( 'wp_privacy_personal_data_erasers', array() ); + + return call_user_func( $erasers['two-factor']['callback'], $this->user->user_email, 1 ); + } + + /** + * The plugin registers an exporter with WordPress. + */ + public function test_registers_a_personal_data_exporter() { + $exporters = apply_filters( 'wp_privacy_personal_data_exporters', array() ); + + $this->assertArrayHasKey( 'two-factor', $exporters ); + $this->assertTrue( is_callable( $exporters['two-factor']['callback'] ) ); + } + + /** + * The plugin registers an eraser with WordPress. + */ + public function test_registers_a_personal_data_eraser() { + $erasers = apply_filters( 'wp_privacy_personal_data_erasers', array() ); + + $this->assertArrayHasKey( 'two-factor', $erasers ); + $this->assertTrue( is_callable( $erasers['two-factor']['callback'] ) ); + } + + /** + * An address with no matching user exports nothing. + */ + public function test_export_returns_no_data_for_an_unknown_email_address() { + $exporters = apply_filters( 'wp_privacy_personal_data_exporters', array() ); + $response = call_user_func( $exporters['two-factor']['callback'], 'nobody@example.com', 1 ); + + $this->assertSame( array(), $response['data'] ); + $this->assertTrue( $response['done'] ); + } + + /** + * A user with no two-factor data exports nothing. + */ + public function test_export_returns_no_data_for_a_user_without_two_factor_data() { + $response = $this->export(); + + $this->assertSame( array(), $response['data'] ); + $this->assertTrue( $response['done'] ); + } + + /** + * Enabled providers and the primary provider are exported. + */ + public function test_export_includes_enabled_and_primary_providers() { + Two_Factor_Core::enable_provider_for_user( $this->user->ID, 'Two_Factor_Email' ); + update_user_meta( $this->user->ID, Two_Factor_Core::PROVIDER_USER_META_KEY, 'Two_Factor_Email' ); + + $flat = $this->flatten_export( $this->export() ); + + $this->assertStringContainsString( 'Two_Factor_Email', $flat['Enabled two-factor methods'] ); + $this->assertStringContainsString( 'Two_Factor_Email', $flat['Primary two-factor method'] ); + } + + /** + * The TOTP secret is reported as configured, never disclosed. + */ + public function test_export_reports_totp_as_configured_without_disclosing_the_secret() { + $totp = Two_Factor_Totp::get_instance(); + $secret = Two_Factor_Totp::generate_key(); + $totp->set_user_totp_key( $this->user->ID, $secret ); + + $response = $this->export(); + $flat = $this->flatten_export( $response ); + + $this->assertArrayHasKey( 'Authenticator app (TOTP)', $flat ); + $this->assertStringNotContainsString( $secret, wp_json_encode( $response ) ); + } + + /** + * Backup codes are reported as a remaining count, never as codes or hashes. + */ + public function test_export_reports_backup_codes_as_a_count_only() { + $backup_codes = Two_Factor_Backup_Codes::get_instance(); + $codes = $backup_codes->generate_codes( $this->user ); + + $response = $this->export(); + $flat = $this->flatten_export( $response ); + + $this->assertSame( (string) count( $codes ), (string) $flat['Backup codes remaining'] ); + + foreach ( $codes as $code ) { + $this->assertStringNotContainsString( $code, wp_json_encode( $response ) ); + } + } + + /** + * Failed login records are personal data and are exported. + */ + public function test_export_includes_failed_login_records() { + $failure_time = time() - 60; + update_user_meta( $this->user->ID, Two_Factor_Core::USER_FAILED_LOGIN_ATTEMPTS_KEY, 3 ); + update_user_meta( $this->user->ID, Two_Factor_Core::USER_RATE_LIMIT_KEY, $failure_time ); + + $flat = $this->flatten_export( $this->export() ); + + $this->assertSame( '3', (string) $flat['Failed two-factor attempts'] ); + $this->assertArrayHasKey( 'Last failed two-factor attempt', $flat ); + } + + /** + * A pending email token is reported by time, never by value. + */ + public function test_export_reports_a_pending_email_token_without_its_value() { + $email = Two_Factor_Email::get_instance(); + $email->generate_token( $this->user->ID ); + + $response = $this->export(); + $flat = $this->flatten_export( $response ); + $stored = get_user_meta( $this->user->ID, Two_Factor_Email::TOKEN_META_KEY, true ); + + $this->assertArrayHasKey( 'Email login code', $flat ); + $this->assertStringNotContainsString( $stored, wp_json_encode( $response ) ); + } + + /** + * An address with no matching user erases nothing. + */ + public function test_erase_removes_nothing_for_an_unknown_email_address() { + $erasers = apply_filters( 'wp_privacy_personal_data_erasers', array() ); + $response = call_user_func( $erasers['two-factor']['callback'], 'nobody@example.com', 1 ); + + $this->assertFalse( $response['items_removed'] ); + $this->assertFalse( $response['items_retained'] ); + $this->assertTrue( $response['done'] ); + } + + /** + * Incidental login records are erased. + */ + public function test_erase_removes_incidental_login_records() { + update_user_meta( $this->user->ID, Two_Factor_Core::USER_META_NONCE_KEY, array( 'key' => 'value' ) ); + update_user_meta( $this->user->ID, Two_Factor_Core::USER_RATE_LIMIT_KEY, time() ); + update_user_meta( $this->user->ID, Two_Factor_Core::USER_FAILED_LOGIN_ATTEMPTS_KEY, 4 ); + update_user_meta( $this->user->ID, Two_Factor_Core::USER_PASSWORD_WAS_RESET_KEY, true ); + + $response = $this->erase(); + + $this->assertTrue( $response['items_removed'] ); + $this->assertSame( '', get_user_meta( $this->user->ID, Two_Factor_Core::USER_META_NONCE_KEY, true ) ); + $this->assertSame( '', get_user_meta( $this->user->ID, Two_Factor_Core::USER_RATE_LIMIT_KEY, true ) ); + $this->assertSame( '', get_user_meta( $this->user->ID, Two_Factor_Core::USER_FAILED_LOGIN_ATTEMPTS_KEY, true ) ); + $this->assertSame( '', get_user_meta( $this->user->ID, Two_Factor_Core::USER_PASSWORD_WAS_RESET_KEY, true ) ); + } + + /** + * A pending email login token is erased. + */ + public function test_erase_removes_a_pending_email_login_token() { + $email = Two_Factor_Email::get_instance(); + $email->generate_token( $this->user->ID ); + + $this->erase(); + + $this->assertFalse( $email->user_has_token( $this->user->ID ) ); + } + + /** + * The TOTP replay-protection timestamp is erased. + */ + public function test_erase_removes_the_totp_replay_timestamp() { + update_user_meta( $this->user->ID, Two_Factor_Totp::LAST_SUCCESSFUL_LOGIN_META_KEY, time() ); + + $response = $this->erase(); + + $this->assertTrue( $response['items_removed'] ); + $this->assertSame( '', get_user_meta( $this->user->ID, Two_Factor_Totp::LAST_SUCCESSFUL_LOGIN_META_KEY, true ) ); + } + + /** + * Nothing is retained when the user has no second factor configured. + */ + public function test_erase_retains_nothing_when_no_provider_is_enabled() { + update_user_meta( $this->user->ID, Two_Factor_Core::USER_FAILED_LOGIN_ATTEMPTS_KEY, 2 ); + + $response = $this->erase(); + + $this->assertTrue( $response['items_removed'] ); + $this->assertFalse( $response['items_retained'] ); + $this->assertSame( array(), $response['messages'] ); + } + + /** + * Erasure must not silently disable a live account's second factor. + */ + public function test_erase_retains_credentials_so_two_factor_stays_enabled() { + $totp = Two_Factor_Totp::get_instance(); + $secret = Two_Factor_Totp::generate_key(); + $totp->set_user_totp_key( $this->user->ID, $secret ); + Two_Factor_Core::enable_provider_for_user( $this->user->ID, 'Two_Factor_Totp' ); + + $response = $this->erase(); + + $this->assertTrue( $response['items_retained'] ); + $this->assertNotEmpty( $response['messages'] ); + $this->assertSame( $secret, $totp->get_user_totp_key( $this->user->ID ) ); + $this->assertContains( 'Two_Factor_Totp', Two_Factor_Core::get_enabled_providers_for_user( $this->user ) ); + } + + /** + * Erasure reports credentials retained even when their provider is disabled. + */ + public function test_erase_reports_retained_credentials_for_a_disabled_provider() { + $totp = Two_Factor_Totp::get_instance(); + $secret = Two_Factor_Totp::generate_key(); + $totp->set_user_totp_key( $this->user->ID, $secret ); + + $response = $this->erase(); + + $this->assertTrue( $response['items_retained'] ); + $this->assertNotEmpty( $response['messages'] ); + $this->assertSame( $secret, $totp->get_user_totp_key( $this->user->ID ) ); + } +}