Skip to content

Commit 2d55fa9

Browse files
fix(wordpress): centralize findings confirmation and hold invariants
1 parent 8d3243b commit 2d55fa9

7 files changed

Lines changed: 544 additions & 56 deletions

File tree

‎integrations/wordpress/ct-scan.php‎

Lines changed: 115 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -134,7 +134,11 @@ function ct_scan_config() {
134134
* grandfathered. A version that cannot be parsed is NOT legacy.
135135
*/
136136
function ct_scan_is_legacy_version( $version ) {
137-
if ( ! is_string( $version ) || ! preg_match( '/\A(\d{4}-\d{2}-\d{2})-r(\d{1,3})\z/', $version, $m ) ) {
137+
if ( ! is_string( $version ) || ! preg_match( '/\A(\d{4}-\d{2}-\d{2})-r([1-9]\d{0,2})\z/', $version, $m ) ) {
138+
return false;
139+
}
140+
$date = explode( '-', $m[1] );
141+
if ( ! checkdate( (int) $date[1], (int) $date[2], (int) $date[0] ) ) {
138142
return false;
139143
}
140144
return $m[1] < '2026-10-21' || ( '2026-10-21' === $m[1] && (int) $m[2] <= 2 );
@@ -1134,6 +1138,58 @@ function ct_scan_closure_metadata_trusted( $row ) {
11341138
return false;
11351139
}
11361140

1141+
/**
1142+
* Findings presence is a SQL NULL question, never PHP truthiness: '0' and '' are stored values.
1143+
* Missing columns or unexpected non-string data mean unknown and must preserve the complete row.
1144+
* Returns true (present), false (both explicit SQL NULL), or null (unknown schema/value).
1145+
*/
1146+
function ct_scan_findings_presence( $row ) {
1147+
if ( ! is_object( $row ) ) {
1148+
return null;
1149+
}
1150+
foreach ( array( 'result_json', 'manual_remainder_notes' ) as $field ) {
1151+
if ( ! property_exists( $row, $field ) || ( null !== $row->$field && ! is_string( $row->$field ) ) ) {
1152+
return null;
1153+
}
1154+
}
1155+
return null !== $row->result_json || null !== $row->manual_remainder_notes;
1156+
}
1157+
1158+
/** Shared prerequisites for ordinary and restored-row deletion; legacy policy never excuses backwards dates. */
1159+
function ct_scan_retention_dates_trusted( $row ) {
1160+
if ( ! is_object( $row ) ) {
1161+
return false;
1162+
}
1163+
foreach ( array( 'created_at', 'terms_accepted_at', 'closed_at', 'retain_until' ) as $field ) {
1164+
if ( ! property_exists( $row, $field ) || ! ct_scan_valid_datetime( $row->$field ) ) {
1165+
return false;
1166+
}
1167+
}
1168+
return $row->closed_at >= $row->created_at && $row->closed_at >= $row->terms_accepted_at;
1169+
}
1170+
1171+
/**
1172+
* Canonical mailbox confirmation is proof only within its original acceptance/creation window.
1173+
* A prepared report may be retrieved after traffic authorization expires: the confirmation itself,
1174+
* not the current retrieval time, must have occurred by that frozen authorization deadline.
1175+
*/
1176+
function ct_scan_confirmation_metadata_trusted( $row, $now = null ) {
1177+
if ( ! is_object( $row ) ) {
1178+
return false;
1179+
}
1180+
$now = null === $now ? ct_scan_utc_now() : $now;
1181+
if ( ! ct_scan_valid_datetime( $now ) ) {
1182+
return false;
1183+
}
1184+
foreach ( array( 'confirmed_at', 'created_at', 'terms_accepted_at', 'authorization_expires_at' ) as $field ) {
1185+
if ( ! property_exists( $row, $field ) || ! ct_scan_valid_datetime( $row->$field ) ) {
1186+
return false;
1187+
}
1188+
}
1189+
return $row->confirmed_at >= $row->created_at && $row->confirmed_at >= $row->terms_accepted_at
1190+
&& $row->confirmed_at <= $now && $row->confirmed_at <= $row->authorization_expires_at;
1191+
}
1192+
11371193
/** Findings and any served report remain until their trusted delivery or final-close timestamp plus 366 days. */
11381194
function ct_scan_findings_retain_until( $row ) {
11391195
if ( ! ct_scan_closure_metadata_trusted( $row ) ) {
@@ -1209,23 +1265,44 @@ function ct_scan_hold_grace_days() {
12091265
return 3;
12101266
}
12111267

1212-
/**
1213-
* Is this job under a preservation hold? An unexpired hold preserves, and so does one that expired
1214-
* less than the grace period ago; a hold with a purpose but no expiry (not creatable through the admin
1215-
* action) also preserves, so a damaged hold never causes a deletion.
1216-
*/
1268+
/** The complete nullable hold tuple; all destructive paths validate and compare the same state. */
1269+
function ct_scan_hold_fields() {
1270+
return array( 'hold_reason', 'hold_until', 'hold_set_by', 'hold_set_at', 'hold_released_by', 'hold_released_at' );
1271+
}
1272+
1273+
/** A database actor id is positive and canonical; NULL/zero/coercible non-ids are not evidence. */
1274+
function ct_scan_positive_actor_id( $value ) {
1275+
return ( is_int( $value ) && $value > 0 )
1276+
|| ( is_string( $value ) && 1 === preg_match( '/\A[1-9]\d*\z/', $value ) && (string) (int) $value === $value && (int) $value > 0 );
1277+
}
1278+
1279+
/** Only a complete absent tuple or a trustworthy elapsed/released hold can permit cleanup. */
12171280
function ct_scan_job_on_hold( $row, $now ) {
1218-
if ( ! is_object( $row ) || ! property_exists( $row, 'hold_reason' ) || ! property_exists( $row, 'hold_until' ) ) {
1281+
if ( ! is_object( $row ) || ! ct_scan_valid_datetime( $now ) ) {
12191282
return true;
12201283
}
1221-
if ( null === $row->hold_reason ) {
1284+
$all_null = true;
1285+
foreach ( ct_scan_hold_fields() as $field ) {
1286+
if ( ! property_exists( $row, $field ) ) {
1287+
return true;
1288+
}
1289+
$all_null = $all_null && null === $row->$field;
1290+
}
1291+
if ( $all_null ) {
12221292
return false;
12231293
}
1224-
// SQL NULL is the only unambiguous absence. A damaged empty/'0' purpose or expiry
1225-
// must not release a hold in PHP while SQL and the administrative UI still see a record.
1294+
// Any partial or contradictory tuple is a damaged hold, never an absent hold.
12261295
if ( ! is_string( $row->hold_reason ) || '' === $row->hold_reason || '0' === $row->hold_reason
12271296
|| trim( $row->hold_reason ) !== $row->hold_reason || preg_match( '/[\x00-\x1f\x7f]/', $row->hold_reason )
1228-
|| ! ct_scan_valid_datetime( $row->hold_until ) ) {
1297+
|| ! ct_scan_valid_datetime( $row->hold_until ) || ! ct_scan_valid_datetime( $row->hold_set_at )
1298+
|| ! ct_scan_positive_actor_id( $row->hold_set_by )
1299+
|| $row->hold_set_at > $row->hold_until || $row->hold_set_at > $now ) {
1300+
return true;
1301+
}
1302+
$release_absent = null === $row->hold_released_by && null === $row->hold_released_at;
1303+
if ( ! $release_absent && ( ! ct_scan_positive_actor_id( $row->hold_released_by )
1304+
|| ! ct_scan_valid_datetime( $row->hold_released_at ) || $row->hold_released_at < $row->hold_set_at
1305+
|| $row->hold_released_at > $now || $row->hold_until > $row->hold_released_at ) ) {
12291306
return true;
12301307
}
12311308
$grace_end = ( new DateTimeImmutable( $row->hold_until, new DateTimeZone( 'UTC' ) ) )->modify( '+' . ct_scan_hold_grace_days() . ' days' )->format( 'Y-m-d H:i:s' );
@@ -1274,12 +1351,7 @@ function ct_scan_deletion_decision( $row, $now ) {
12741351
if ( ! isset( $row->identity ) || ! is_string( $row->identity ) || '' === $row->identity ) {
12751352
return array( 'keep', null );
12761353
}
1277-
foreach ( array( $row->created_at, $row->closed_at, $row->retain_until ) as $date ) {
1278-
if ( ! ct_scan_valid_datetime( $date ) ) {
1279-
return array( 'keep', null );
1280-
}
1281-
}
1282-
if ( $row->closed_at < $row->created_at ) {
1354+
if ( ! ct_scan_retention_dates_trusted( $row ) ) {
12831355
return array( 'keep', null );
12841356
}
12851357
if ( ct_scan_is_legacy_version( $row->terms_version ) ) {
@@ -1293,7 +1365,10 @@ function ct_scan_deletion_decision( $row, $now ) {
12931365
if ( false === $required ) {
12941366
return array( 'keep', null );
12951367
}
1296-
$has_findings = ! empty( $row->result_json ) || ! empty( $row->manual_remainder_notes );
1368+
$has_findings = ct_scan_findings_presence( $row );
1369+
if ( null === $has_findings ) {
1370+
return array( 'keep', null );
1371+
}
12971372
if ( $has_findings ) {
12981373
$findings_until = ct_scan_findings_retain_until( $row );
12991374
if ( false === $findings_until || $findings_until > $now ) {
@@ -1324,17 +1399,7 @@ function ct_scan_deletion_allowed( $row, $now ) {
13241399
* deadline for a restored or damaged copy.
13251400
*/
13261401
function ct_scan_tombstone_deadline_passed( $row, $now ) {
1327-
// A tombstone does not excuse invalid dates in a restored legacy row. Apply the same
1328-
// closure/deadline prerequisites as ordinary retention before deriving its legacy period.
1329-
if ( ! is_object( $row ) ) {
1330-
return false;
1331-
}
1332-
foreach ( array( 'created_at', 'closed_at', 'retain_until' ) as $field ) {
1333-
if ( ! property_exists( $row, $field ) || ! ct_scan_valid_datetime( $row->$field ) ) {
1334-
return false;
1335-
}
1336-
}
1337-
if ( $row->closed_at < $row->created_at ) {
1402+
if ( ct_scan_job_on_hold( $row, $now ) || ! ct_scan_retention_dates_trusted( $row ) ) {
13381403
return false;
13391404
}
13401405
$required = ct_scan_required_retain_until( $row );
@@ -1348,7 +1413,11 @@ function ct_scan_tombstone_deadline_passed( $row, $now ) {
13481413
if ( $deadline > $now ) {
13491414
return false;
13501415
}
1351-
if ( ! empty( $row->result_json ) || ! empty( $row->manual_remainder_notes ) ) {
1416+
$has_findings = ct_scan_findings_presence( $row );
1417+
if ( null === $has_findings ) {
1418+
return false;
1419+
}
1420+
if ( $has_findings ) {
13521421
$findings_until = ct_scan_findings_retain_until( $row );
13531422
if ( false === $findings_until || $findings_until > $now ) {
13541423
return false;
@@ -1593,15 +1662,15 @@ function ct_scan_purge_findings_if_due( $job_id, $now ) {
15931662
if ( ! is_object( $row ) || ! isset( $row->job_id ) || (int) $row->job_id < 1 || (int) $row->job_id !== (int) $job_id ) {
15941663
return 'kept';
15951664
}
1596-
$fields = array( 'status', 'created_at', 'terms_accepted_at', 'closed_at', 'closure_source', 'closed_by', 'closure_reason', 'report_delivered_at', 'report_access_used_at', 'hold_reason', 'hold_until', 'result_json', 'manual_remainder_notes' );
1665+
$fields = array_merge( array( 'status', 'created_at', 'terms_accepted_at', 'closed_at', 'closure_source', 'closed_by', 'closure_reason', 'report_delivered_at', 'report_access_used_at', 'result_json', 'manual_remainder_notes' ), ct_scan_hold_fields() );
15971666
foreach ( $fields as $field ) {
15981667
if ( ! property_exists( $row, $field ) ) {
15991668
return 'kept';
16001669
}
16011670
}
16021671
$until = ct_scan_findings_retain_until( $row );
16031672
if ( false === $until || $until > $now || ct_scan_job_on_hold( $row, $now )
1604-
|| ( null === $row->result_json && null === $row->manual_remainder_notes ) ) {
1673+
|| true !== ct_scan_findings_presence( $row ) ) {
16051674
return 'kept';
16061675
}
16071676
// The advisory lock serializes supported writers. Binary predicates additionally refuse an
@@ -2174,7 +2243,7 @@ function ct_scan_send_accepted_copy( $job_id ) {
21742243
try {
21752244
$row = ct_scan_row( $job_id );
21762245
// Same recipient rule as the report path: confirmed, and still the address the signer authorized.
2177-
if ( ! $row || empty( $row->confirmed_at ) || ! is_email( $row->contact_email )
2246+
if ( ! $row || ! ct_scan_confirmation_metadata_trusted( $row ) || ! is_email( $row->contact_email )
21782247
|| ct_scan_meta_string( (int) $row->request_id, '_ct_scan_email' ) !== $row->contact_email
21792248
|| ct_scan_meta_string( (int) $row->request_id, '_ct_terms_version' ) !== $row->terms_version
21802249
|| strtolower( ct_scan_meta_string( (int) $row->request_id, '_ct_terms_sha256' ) ) !== $row->terms_hash ) {
@@ -2189,9 +2258,9 @@ function ct_scan_send_accepted_copy( $job_id ) {
21892258
$claimed = $wpdb->update(
21902259
$table,
21912260
array( 'accepted_copy_status' => 'unknown', 'accepted_copy_at' => ct_scan_utc_now() ),
2192-
array( 'job_id' => (int) $row->job_id, 'accepted_copy_status' => 'not_sent' ),
2261+
array( 'job_id' => (int) $row->job_id, 'accepted_copy_status' => 'not_sent', 'confirmed_at' => $row->confirmed_at, 'created_at' => $row->created_at, 'terms_accepted_at' => $row->terms_accepted_at, 'authorization_expires_at' => $row->authorization_expires_at ),
21932262
array( '%s', '%s' ),
2194-
array( '%d', '%s' )
2263+
array( '%d', '%s', '%s', '%s', '%s', '%s' )
21952264
);
21962265
if ( 1 !== $claimed ) {
21972266
return 'already_handled';
@@ -2782,7 +2851,7 @@ function ct_scan_admit_locked( $data, $now_ms ) {
27822851
|| ! hash_equals( $row->scope_hash, $data['scope_hash'] ) || strtotime( $row->lease_until . ' UTC' ) <= time() ) {
27832852
return $refuse( 410, 'lease_invalid_or_expired' );
27842853
}
2785-
if ( empty( $row->confirmed_at ) ) {
2854+
if ( ! ct_scan_confirmation_metadata_trusted( $row ) ) {
27862855
return $refuse( 410, 'recipient_unconfirmed' );
27872856
}
27882857
if ( ! ct_scan_authorization_is_live( $row ) ) {
@@ -3093,7 +3162,7 @@ function ct_scan_admit_control_locked( $data, $now_ms ) {
30933162
|| ! hash_equals( $row->scope_hash, $data['scope_hash'] ) || strtotime( $row->control_lease_until . ' UTC' ) <= time() ) {
30943163
return $refuse( 410, 'lease_invalid_or_expired' );
30953164
}
3096-
if ( empty( $row->confirmed_at ) ) {
3165+
if ( ! ct_scan_confirmation_metadata_trusted( $row ) ) {
30973166
return $refuse( 410, 'recipient_unconfirmed' );
30983167
}
30993168
if ( ! ct_scan_authorization_is_live( $row ) ) {
@@ -3169,7 +3238,7 @@ function ct_scan_control_claim( WP_REST_Request $request ) {
31693238
if ( ! $row ) {
31703239
return ct_scan_rest_response( 200, array( 'task' => null ) );
31713240
}
3172-
if ( ! ct_scan_authorization_is_live( $row ) || empty( $row->confirmed_at ) || ! in_array( $row->control_requested_method, array( 'dns_txt', 'https_file' ), true ) ) {
3241+
if ( ! ct_scan_authorization_is_live( $row ) || ! ct_scan_confirmation_metadata_trusted( $row ) || ! in_array( $row->control_requested_method, array( 'dns_txt', 'https_file' ), true ) ) {
31733242
$wpdb->update( $table, array( 'status' => 'cancelled', 'error_code' => 'authorization_changed', 'finished_at' => ct_scan_utc_now(), 'control_token_hash' => null, 'control_page_hash' => null, 'control_state' => 'none' ), array( 'job_id' => (int) $row->job_id ), null, array( '%d' ) );
31743243
ct_scan_mark_request_status( (int) $row->request_id, 'cancelled', 'authorization_changed' );
31753244
return ct_scan_rest_response( 200, array( 'task' => null ) );
@@ -3527,7 +3596,7 @@ function ct_scan_validate_report_job( $row, $token = '', $require_capability = f
35273596
if ( ! ct_scan_terminal_status( $row->status ) || 'complete' !== $row->manual_remainder_status || '' === trim( (string) $row->manual_remainder_notes ) ) {
35283597
return new WP_Error( 'report_not_ready', 'The reviewed report is not ready.' );
35293598
}
3530-
if ( empty( $row->confirmed_at ) ) {
3599+
if ( ! ct_scan_confirmation_metadata_trusted( $row ) ) {
35313600
return new WP_Error( 'report_recipient_unconfirmed', 'The report recipient did not confirm the request.' );
35323601
}
35333602
clean_post_cache( (int) $row->request_id );
@@ -3665,6 +3734,7 @@ function ct_scan_report_access_response( $method, $job_id, $token ) {
36653734
'authorization_expires_at' => $row->authorization_expires_at,
36663735
'status' => $row->status,
36673736
'confirmed_at' => $row->confirmed_at,
3737+
'created_at' => $row->created_at,
36683738
'control_required' => ct_scan_control_required( $row ) ? 1 : 0,
36693739
'control_method' => $row->control_method ?? null,
36703740
'control_verified_at' => $row->control_verified_at ?? null,
@@ -3894,13 +3964,17 @@ function ct_scan_admin_send_report( $job_id ) {
38943964
'job_id' => (int) $row->job_id,
38953965
'request_id' => (int) $row->request_id,
38963966
'status' => $row->status,
3967+
'confirmed_at' => $row->confirmed_at,
3968+
'created_at' => $row->created_at,
3969+
'terms_accepted_at' => $row->terms_accepted_at,
3970+
'authorization_expires_at' => $row->authorization_expires_at,
38973971
'report_notification_status' => $row->report_notification_status,
38983972
'report_delivered_at' => null,
38993973
'revoked_at' => null,
39003974
'report_access_used_at' => null,
39013975
),
39023976
array( '%s', '%s', '%s', '%s', '%s' ),
3903-
array( '%d', '%d', '%s', '%s', '%s', '%s', '%s' )
3977+
array( '%d', '%d', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s' )
39043978
);
39053979
if ( 1 !== $updated ) {
39063980
return new WP_Error( 'report_state_write_failed', 'The one-time send state could not be durably recorded. No email was sent.' );
@@ -4131,7 +4205,7 @@ function ct_scan_admin_page() {
41314205
echo '<tr><td><a href="' . esc_url( $request_url ) . '">Job #' . (int) $row->job_id . ' / request #' . (int) $row->request_id . '</a><br>Created ' . esc_html( (string) $row->created_at ) . ' UTC</td>';
41324206
echo '<td><code>' . esc_html( (string) $row->target_origin ) . '</code><br>Terms ' . esc_html( (string) $row->terms_version ) . '<br>Accepted ' . esc_html( (string) $row->terms_accepted_at ) . ' UTC<br>Expires ' . esc_html( (string) $row->authorization_expires_at ) . ' UTC<br>Scope hash <code>' . esc_html( substr( (string) $row->scope_hash, 0, 16 ) ) . '…</code></td>';
41334207
echo '<td><pre>' . esc_html( $exec ) . '</pre>' . ct_scan_admin_result_details( $row ) . '</td><td><pre>' . esc_html( $mail ) . '</pre></td><td>';
4134-
if ( ! empty( $row->manual_remainder_notes ) ) {
4208+
if ( is_string( $row->manual_remainder_notes ) && '' !== $row->manual_remainder_notes ) {
41354209
echo '<details><summary>Manual remainder (' . esc_html( sanitize_key( (string) $row->manual_remainder_status ) ) . ')</summary><pre>' . esc_html( (string) $row->manual_remainder_notes ) . '</pre></details>';
41364210
}
41374211
$closure_pending = null === $row->closure_source && null === $row->closed_by && null === $row->closure_reason && null === $row->report_delivered_at && null === $row->report_access_used_at;

0 commit comments

Comments
 (0)