Skip to content

Commit 4da58a1

Browse files
Merge origin/main into feat/target-control
Brings in the #10 and #11 review fixes (probe busy/inconclusive handling, bound-evidence pair comparisons, duplicate evidence refusal, accepted-copy live check). Resolutions: - admission.py probe(): keep main's bounded queue_busy retry and use this branch's per-kind route ("probe" for http, "control_probe" for control). Test added for the control route. - ct_scan_send_accepted_copy(): main's live-job check allowed only queued/leased/running, but confirmation now leaves control-required jobs in awaiting_control and sends the copy then, so the default path would never send it. awaiting_control is accepted as live; every other check (authorization live, recipient, terms hash, compare-and-set) is kept. evidence-strict.php covers confirmation into awaiting_control; docs updated. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2 parents 1f61646 + 3379944 commit 4da58a1

6 files changed

Lines changed: 206 additions & 24 deletions

File tree

‎docs/WORDPRESS.md‎

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -119,8 +119,9 @@ Enforcement in the supervisor and scanner:
119119
- The grant's one-second lifetime and ten-second request bound are measured
120120
from just before the call WordPress granted, not from delivery to the
121121
scanner. A grant that took more than 0.6 s to come back is discarded and
122-
asked for again (the discarded slot stays spent), at most twice; after that
123-
the admission is refused (`admission_expired`). No admission is requested
122+
asked for again (the discarded slot stays spent), at most twice and never
123+
after the admission's four-second retry deadline; after that the admission is
124+
refused (`admission_expired`). No admission is requested
124125
after the scan's own deadline, and a shutdown interrupts a slow guard call.
125126
- One grant is outstanding at a time. A second request, an out-of-sequence or
126127
unexpected message or an oversized message ends the scan
@@ -134,9 +135,13 @@ Enforcement in the supervisor and scanner:
134135
that the job is cancelled, expired or revoked, or that the integration is
135136
disabled (the operator kill switch). Cancellation therefore aborts the one
136137
admitted request within about two seconds plus the probe's own latency, and
137-
never later than the ten-second bound. A probe that cannot reach WordPress
138-
does not abort a request already admitted, and the next admission fails closed
139-
(`admission_guard_unavailable`). Expired authorization is refused locally
138+
never later than the ten-second bound. A probe that finds the queue lock held
139+
elsewhere (often by the supervisor's own concurrent admission) retries briefly
140+
within one call budget. An inconclusive probe (WordPress unreachable or slow,
141+
a malformed answer, a still-busy lock or an internal `admission_error`) does
142+
not abort a request already admitted or end the scan, and the next admission
143+
fails closed on the same condition (for example
144+
`admission_guard_unavailable`). Expired authorization is refused locally
140145
without a call.
141146
- `SubprocessRunner.run` refuses to start without a gate.
142147

@@ -278,7 +283,10 @@ the request closes). The form, the site recorder and this plugin render
278283
byte-identical text from that one function, so the limits the signer saw are the
279284
limits the job runs under. Any missing, oversized, mismatched, stale,
280285
non-canonical or partial piece refuses the job (`ct_scan_binding_mismatch` /
281-
`ct_scan_binding_required`), and the job row stores the summary digest, so a
286+
`ct_scan_binding_required`). Every recorded digest is compared, even when the
287+
terms and the Summary are byte-identical. An evidence key (the marker, the
288+
snapshot, the Summary or any of their digests) that holds more than one meta row
289+
is ambiguous and refuses the job (`ct_scan_evidence_duplicate`). The job row stores the summary digest, so a
282290
later edit of the retained evidence makes the authorization no longer live and
283291
cancels a queued or running job. A change of the profile's limits changes the
284292
text and therefore requires a new acceptance.
@@ -301,12 +309,15 @@ confirmation sends the verified contact their copy: the Target Summary, the
301309
hashes, the filled-in copy and, for a bound acceptance, the exact terms bytes
302310
as an attachment (written to a private temporary directory and attached only if
303311
it reproduces the recorded hash). The recipient must still be the confirmed,
304-
authorized address. It is sent at most once (the status is claimed by
312+
authorized address, and the job must still be live (awaiting target control,
313+
queued, leased or running, not revoked, and its retained evidence unchanged), re-checked under the queue
314+
lock immediately before the send is claimed. It is sent at most once (the status is claimed by
305315
compare-and-set before mail is handed off), only to the verified address, and
306316
never to a referrer. An uncertain or failed hand-off is recorded as `unknown`
307317
and never resent automatically; `accepted` means transport acceptance, not
308318
receipt. A failure cannot cancel, delay or repeat a scan. The wording of that
309319
message has not been reviewed by the owner.
320+
310321
## Egress (activation requirement)
311322

312323
The admission guard, the unprivileged UID and the resource limits are
@@ -458,7 +469,8 @@ API stays refused, and the upgrade is not retried for five minutes (so a broken
458469
table cannot make every public request re-run it).
459470
Schema 3 adds `profile_id`, `http_admitted` and `last_admit_ms` to the jobs
460471
table (existing rows default to `r2-header-v1` with empty counters); schema 4
461-
adds `summary_sha256`, `accepted_copy_status` and `accepted_copy_at`. Upgrades
472+
adds `summary_sha256`, `bound_required` (the job's frozen evidence requirement;
473+
existing rows default to `0`), `accepted_copy_status` and `accepted_copy_at`. Upgrades
462474
run on `init` and the worker API refuses requests until they complete.
463475

464476
The healthcheck requires a successful authenticated exchange in the last ten

‎integrations/wordpress/ct-scan.php‎

Lines changed: 24 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -400,6 +400,13 @@ function ct_scan_meta_string( $post_id, $key ) {
400400
* unless the operator grandfathered an r2-or-earlier version as `legacy` in config `terms_policy`.
401401
*/
402402
function ct_scan_check_bound_evidence( $request_id, $terms_hash, $identity, $required, $profile ) {
403+
// get_post_meta( ..., true ) silently returns the first of several rows, so an evidence key that
404+
// holds more than one value is ambiguous: refuse rather than pick one.
405+
foreach ( array( '_ct_terms_binding', '_ct_terms_snapshot', '_ct_terms_sha256', '_ct_terms_shown_digest', '_ct_summary_text', '_ct_summary_sha256', '_ct_summary_shown_digest' ) as $key ) {
406+
if ( count( (array) get_post_meta( $request_id, $key, false ) ) > 1 ) {
407+
return new WP_Error( 'ct_scan_evidence_duplicate', 'The saved acceptance holds more than one value for a piece of evidence.' );
408+
}
409+
}
403410
$marker = ct_scan_meta_string( $request_id, '_ct_terms_binding' );
404411
$partial = false;
405412
foreach ( array( '_ct_terms_snapshot', '_ct_terms_shown_digest', '_ct_summary_text', '_ct_summary_sha256', '_ct_summary_shown_digest' ) as $key ) {
@@ -420,15 +427,18 @@ function ct_scan_check_bound_evidence( $request_id, $terms_hash, $identity, $req
420427
}
421428
$snapshot_hash = hash( 'sha256', $snapshot );
422429
$summary_hash = hash( 'sha256', $summary );
430+
// A list of [computed, recorded] pairs, never keyed by the computed hash: byte-identical terms and
431+
// Summary would share a key and silently drop the terms comparison.
423432
$checks = array(
424-
$snapshot_hash => array( $terms_hash, strtolower( ct_scan_meta_string( $request_id, '_ct_terms_shown_digest' ) ) ),
425-
$summary_hash => array( strtolower( ct_scan_meta_string( $request_id, '_ct_summary_sha256' ) ), strtolower( ct_scan_meta_string( $request_id, '_ct_summary_shown_digest' ) ) ),
433+
array( $snapshot_hash, $terms_hash ),
434+
array( $snapshot_hash, strtolower( ct_scan_meta_string( $request_id, '_ct_terms_shown_digest' ) ) ),
435+
array( $summary_hash, strtolower( ct_scan_meta_string( $request_id, '_ct_summary_sha256' ) ) ),
436+
array( $summary_hash, strtolower( ct_scan_meta_string( $request_id, '_ct_summary_shown_digest' ) ) ),
426437
);
427-
foreach ( $checks as $computed => $recorded ) {
428-
foreach ( $recorded as $value ) {
429-
if ( ! is_string( $value ) || ! preg_match( '/\A[a-f0-9]{64}\z/', $value ) || ! hash_equals( $computed, $value ) ) {
430-
return new WP_Error( 'ct_scan_binding_mismatch', 'The retained evidence does not match the digest the signer was shown.' );
431-
}
438+
foreach ( $checks as $check ) {
439+
list( $computed, $value ) = $check;
440+
if ( ! is_string( $value ) || ! preg_match( '/\A[a-f0-9]{64}\z/', $value ) || ! hash_equals( $computed, $value ) ) {
441+
return new WP_Error( 'ct_scan_binding_mismatch', 'The retained evidence does not match the digest the signer was shown.' );
432442
}
433443
}
434444
// The Target Summary must be exactly the canonical text of the authorized request (website, client,
@@ -1001,9 +1011,15 @@ function ct_scan_send_accepted_copy( $job_id ) {
10011011
if ( ! $row || empty( $row->confirmed_at ) || ! is_email( $row->contact_email )
10021012
|| ct_scan_meta_string( (int) $row->request_id, '_ct_scan_email' ) !== $row->contact_email
10031013
|| ct_scan_meta_string( (int) $row->request_id, '_ct_terms_version' ) !== $row->terms_version
1004-
|| ct_scan_meta_string( (int) $row->request_id, '_ct_terms_sha256' ) !== $row->terms_hash ) {
1014+
|| strtolower( ct_scan_meta_string( (int) $row->request_id, '_ct_terms_sha256' ) ) !== $row->terms_hash ) {
10051015
return new WP_Error( 'accepted_copy_unavailable', 'The accepted copy requires the confirmed, authorized recipient.' );
10061016
}
1017+
// Re-checked under the queue lock right before the claim: a job that was cancelled, stopped,
1018+
// expired or whose evidence changed since confirmation gets no copy. A confirmed job waiting for
1019+
// proof of target control is live (confirmation sends the copy then); control gates the scan, not the copy.
1020+
if ( ! in_array( $row->status, array( 'awaiting_control', 'queued', 'leased', 'running' ), true ) || ! ct_scan_authorization_is_live( $row ) ) {
1021+
return new WP_Error( 'accepted_copy_unavailable', 'The accepted copy requires a live authorization.' );
1022+
}
10071023
$claimed = $wpdb->update(
10081024
$table,
10091025
array( 'accepted_copy_status' => 'unknown', 'accepted_copy_at' => ct_scan_utc_now() ),

‎integrations/wordpress/tests/evidence-strict.php‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,47 @@
7171
ct_test_assert( 'already_handled' === ct_scan_send_accepted_copy( $fevent['job_id'] ) && count( $mail ) === $count, 'An uncertain accepted copy was resent automatically.' );
7272
}
7373

74+
// The recorded terms hash is compared case-insensitively at send time (the job stores it lowercased).
75+
list( $upper_id, $upper_fields ) = ct_test_request( 'strict-upper.example.net' );
76+
$request_ids[] = $upper_id;
77+
$upper_meta = ct_test_bind( $upper_id, $upper_fields );
78+
update_post_meta( $upper_id, '_ct_terms_sha256', strtoupper( $upper_meta['_ct_terms_sha256'] ) );
79+
$upper_event = ct_scan_on_request_ready( $upper_id, $upper_fields );
80+
ct_test_assert( is_array( $upper_event ), 'A bound acceptance with an upper-case terms hash was refused.' );
81+
ct_test_queue_job( $upper_event['job_id'] );
82+
$count = count( $mail );
83+
ct_test_assert( 'sent' === ct_scan_send_accepted_copy( $upper_event['job_id'] ) && count( $mail ) === $count + 1, 'An upper-case recorded terms hash blocked the accepted copy.' );
84+
85+
// The strict policy requires target control: confirmation leaves the job awaiting control and still sends the copy.
86+
list( $ctl_id, $ctl_fields ) = ct_test_request( 'strict-awaiting-control.example.net', 'control.customer@example.com' );
87+
$request_ids[] = $ctl_id;
88+
ct_test_bind( $ctl_id, $ctl_fields );
89+
$count = count( $mail );
90+
$ctl_event = ct_scan_on_request_ready( $ctl_id, $ctl_fields );
91+
ct_test_assert( is_array( $ctl_event ) && 1 === (int) ct_scan_row( $ctl_event['job_id'] )->control_required && 1 === preg_match( '/token=([a-f0-9]{64})/', $mail[ $count ]['message'], $ctl_m ), 'The control-required fixture job or its confirmation mail is missing.' );
92+
list( , $ctl_status ) = ct_scan_confirm_job( $ctl_event['job_id'], $ctl_m[1] );
93+
$ctl_row = ct_scan_row( $ctl_event['job_id'] );
94+
ct_test_assert( 200 === $ctl_status && 'awaiting_control' === $ctl_row->status && 'sent' === $ctl_row->accepted_copy_status && array( 'control.customer@example.com' ) === array_values( (array) $mail[ count( $mail ) - 1 ]['to'] ), 'Confirming a job that awaits target control did not send the accepted copy.' );
95+
96+
// A job that is no longer live when the copy would be sent gets none, and its copy state is untouched.
97+
foreach ( array( 'cancelled', 'revoked', 'evidence_changed' ) as $how ) {
98+
list( $dead_id, $dead_fields ) = ct_test_request( 'strict-dead-' . str_replace( '_', '-', $how ) . '.example.net' );
99+
$request_ids[] = $dead_id;
100+
ct_test_bind( $dead_id, $dead_fields );
101+
$dead_event = ct_scan_on_request_ready( $dead_id, $dead_fields );
102+
ct_test_queue_job( $dead_event['job_id'] );
103+
if ( 'cancelled' === $how ) {
104+
$wpdb->update( $jobs, array( 'status' => 'cancelled', 'error_code' => 'customer_stop' ), array( 'job_id' => $dead_event['job_id'] ) );
105+
} elseif ( 'revoked' === $how ) {
106+
$wpdb->update( $jobs, array( 'revoked_at' => ct_scan_utc_now() ), array( 'job_id' => $dead_event['job_id'] ) );
107+
} else {
108+
update_post_meta( $dead_id, '_ct_summary_text', wp_slash( ct_test_summary( $dead_fields ) . "Note: edited afterwards\n" ) );
109+
}
110+
$count = count( $mail );
111+
$dead = ct_scan_send_accepted_copy( $dead_event['job_id'] );
112+
ct_test_assert( is_wp_error( $dead ) && count( $mail ) === $count && 'not_sent' === ct_scan_row( $dead_event['job_id'] )->accepted_copy_status, "An accepted copy was sent for a job that is no longer live ($how)." );
113+
}
114+
74115
// The requirement is frozen into each job. A job created before the version was listed as requiring
75116
// bound evidence keeps working when the configuration later requires it, and one created bound keeps
76117
// needing it: configuration can neither cancel nor relax an authorization already given.

‎integrations/wordpress/tests/evidence.php‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,9 @@ function ct_test_refused_with( $request_id, $fields, $code, $message ) {
6464
'summary without the limits line' => array( array( 'summary_drop' => 'Limits' ), 'binding_mismatch' ),
6565
'summary with other limits' => array( array( 'summary' => ct_test_summary( array( 'target' => 'https://evidence-case.example.net/', 'name' => 'Fixture Reviewer', 'email' => 'fixture@example.com' ), array( 'Limits' => 'this website only; at most 2000 requests' ) ) ), 'binding_mismatch' ),
6666
'summary without the period line' => array( array( 'summary_drop' => 'Authorization' ), 'binding_mismatch' ),
67+
// Byte-identical terms and Summary share one computed hash; every recorded digest must still be compared.
68+
'snapshot equals summary, terms hash differs' => array( array( 'snapshot_is_summary' => true, 'meta' => array( '_ct_terms_sha256' => str_repeat( 'b', 64 ) ) ), 'binding_mismatch' ),
69+
'snapshot equals summary, stale terms digest' => array( array( 'snapshot_is_summary' => true, 'meta' => array( '_ct_terms_shown_digest' => str_repeat( 'a', 64 ) ) ), 'binding_mismatch' ),
6770
'bound pieces without the marker' => array( array( 'meta' => array( '_ct_terms_binding' => null ) ), 'binding_required' ),
6871
'marker with another value' => array( array( 'meta' => array( '_ct_terms_binding' => 'yes' ) ), 'binding_required' ),
6972
);
@@ -76,6 +79,9 @@ function ct_test_refused_with( $request_id, $fields, $code, $message ) {
7679
if ( isset( $mutations['summary_drop'] ) ) {
7780
$mutations = array( 'summary' => implode( "\n", array_filter( explode( "\n", ct_test_summary( $case_fields ) ), static function ( $line ) use ( $mutations ) { return '' !== $line && 0 !== strpos( $line, $mutations['summary_drop'] . ':' ); } ) ) . "\n" );
7881
}
82+
if ( ! empty( $mutations['snapshot_is_summary'] ) ) {
83+
$mutations['snapshot'] = ct_test_summary( $case_fields );
84+
}
7985
// Summaries built for "evidence-case" must name this request's website for the other checks to be the only fault.
8086
if ( isset( $mutations['summary'] ) ) {
8187
$mutations['summary'] = str_replace( 'https://evidence-case.example.net/', $case_fields['target'], $mutations['summary'] );
@@ -84,6 +90,29 @@ function ct_test_refused_with( $request_id, $fields, $code, $message ) {
8490
ct_test_refused_with( $case_id, $case_fields, $case[1], 'Case "' . $label . '"' );
8591
}
8692

93+
// Control: byte-identical terms and Summary with every digest consistent is accepted (the cases above fail only on the digest).
94+
list( $same_id, $same_fields ) = ct_test_request( 'evidence-same-bytes.example.net' );
95+
$request_ids[] = $same_id;
96+
ct_test_bind( $same_id, $same_fields, array( 'snapshot' => ct_test_summary( $same_fields ) ) );
97+
ct_test_assert( is_array( ct_scan_on_request_ready( $same_id, $same_fields ) ), 'Byte-identical but consistent terms and Summary were refused.' );
98+
99+
// An evidence key holding more than one row is ambiguous (get_post_meta( ..., true ) would pick the first): refused,
100+
// even when the extra row repeats the same value.
101+
foreach ( array( '_ct_terms_binding', '_ct_terms_snapshot', '_ct_terms_sha256', '_ct_terms_shown_digest', '_ct_summary_text', '_ct_summary_sha256', '_ct_summary_shown_digest' ) as $i => $key ) {
102+
list( $dup_id, $dup_fields ) = ct_test_request( 'evidence-duplicate-' . $i . '.example.net' );
103+
$request_ids[] = $dup_id;
104+
$dup_meta = ct_test_bind( $dup_id, $dup_fields );
105+
add_post_meta( $dup_id, $key, wp_slash( 0 === $i % 2 ? $dup_meta[ $key ] : $dup_meta[ $key ] . 'x' ) );
106+
ct_test_refused_with( $dup_id, $dup_fields, 'evidence_duplicate', 'Duplicate ' . $key );
107+
}
108+
// ...and a duplicate row added after the job exists ends the authorization.
109+
$dup_running = ct_test_running_job_for_bound( 'evidence-duplicate-running.example.net' );
110+
$request_ids[] = $dup_running['request_id'];
111+
ct_test_assert( 200 === ct_test_admit( $dup_running )->get_status(), 'A bound running job was not admitted (duplicate case).' );
112+
add_post_meta( $dup_running['request_id'], '_ct_summary_text', wp_slash( ct_scan_meta_string( $dup_running['request_id'], '_ct_summary_text' ) ) );
113+
ct_test_age_admission( $dup_running['job_id'] );
114+
$dup_admit = ct_test_admit( $dup_running );
115+
ct_test_assert( 410 === $dup_admit->get_status() && 'cancelled' === ct_scan_row( $dup_running['job_id'] )->status, 'A duplicate evidence row added after acceptance did not end the authorization.' );
87116

88117
// ---- Defaults: strict unless an r2-or-earlier version is explicitly grandfathered -------------------------------
89118
function ct_test_gate_env( $env ) {

0 commit comments

Comments
 (0)