fix(audit): enforce passed-event logging via code policy

Author: dknauss

CHANGELOG.md

@@ -21,8 +21,8 @@
 
 - **Active sessions: identity context** — sessions panel now shows gravatars, username, role badge, display name, and time remaining for each active session. Responsive layout hides gravatars and names on small screens.
 - **Recent events: client-side filtering** — dropdown filters for Time (1h / 24h / 7d), Event type, and Surface, applied client-side against 50 stored events. Filters laid out horizontally in a single row.
-- **Passthrough logging** — new `log_passthrough` toggle in Settings → Sudo → Session Settings. When enabled, gated actions that pass through an active sudo session are recorded as "Passed" events in the widget via the new `wp_sudo_action_passed` audit hook (fires on admin, REST, and WPGraphQL surfaces).
-- **Widget placement and layout** — widget renders in the side column at high priority, active session cards use CSS Grid (`repeat(auto-fit, minmax(180px, 1fr))`) with scrollable container, usernames link to user-edit.php, Settings link in passthrough notice.
+- **Passed-event audit visibility defaults** — `wp_sudo_action_passed` events (admin, REST, WPGraphQL) are now recorded by default so active-session actions stay visible in the audit timeline. Disabling passed-event logging now requires an explicit code override (constant/filter), and WP Sudo shows a warning notice when that override is active.
+- **Widget placement and layout** — widget renders in the side column at high priority, active session cards use CSS Grid (`repeat(auto-fit, minmax(180px, 1fr))`) with scrollable container, usernames link to user-edit.php, and the empty-state panel now uses a clearer Site Health–style status layout.
 - **Users list "Sudo Active" filter** — the Users → All Users screen gains a "Sudo Active (N)" view link that filters the list to users with an active sudo session via `_wp_sudo_expires` meta query.
 
 ### Accessibility

docs/ROADMAP.md

@@ -461,7 +461,7 @@ Use this default order after the v3.0.0 release unless a real user need override
 
 - **Do next:** Network Dashboard Widget + Super Admin Visibility Controls
 - **Plan next:** Gutenberg Block Editor Integration
-- **Do later if demand exists:** Network Policy Hierarchy for Multisite, Cross-Site Session Revocation
+- **Do later if demand exists:** Network Policy Hierarchy for Multisite, Cross-Site Session Revocation, network-enforced Passed-event logging policy (super admins can require immutable Passed-event audit visibility across subsites)
 - **Keep as design backlog:** client-side modal challenge, per-session sudo isolation, REST sudo grant endpoint, SSO/SAML/OIDC framework
 
 ---

docs/current-metrics.md

@@ -9,8 +9,8 @@ Verification environment: primary local repo checkout at `/Users/danknauss/Devel
 
 | Metric | Value | Verification |
 |---|---:|---|
-| Unit tests | 627 tests | `composer test:unit` |
-| Unit assertions | 1781 assertions | `composer test:unit` |
+| Unit tests | 632 tests | `composer test:unit` |
+| Unit assertions | 1796 assertions | `composer test:unit` |
 | Integration tests in suite | 160 test methods | `rg -c "function test" tests/Integration/*.php | awk -F: '{sum+=$2} END{print sum}'` |
 | Unit test files | 23 | `ls tests/Unit/*.php | wc -l` |
 | Integration test files | 22 | `ls tests/Integration/*.php | wc -l` |
@@ -19,11 +19,11 @@ Verification environment: primary local repo checkout at `/Users/danknauss/Devel
 
 | Metric | Value | Verification |
 |---|---:|---|
-| Production PHP lines (`includes/`, `wp-sudo.php`, `uninstall.php`, `mu-plugin/`, `bridges/`) | 12,003 | `find ./includes ./wp-sudo.php ./uninstall.php ./mu-plugin ./bridges -type f -name "*.php" -print0 | xargs -0 wc -l | tail -1 | awk '{print $1}'` |
-| Tests PHP lines (`tests/`) | 22,147 | `find ./tests -type f -name "*.php" -print0 | xargs -0 wc -l | tail -1 | awk '{print $1}'` |
-| Production + tests PHP lines | 34,150 | sum of the two rows above |
-| Test-to-production ratio | 1.85:1 | `22147 / 12003` |
-| Total repo PHP lines (excluding `vendor/`, `vendor_test/`, `.tmp/`, `.git/`) | 34,413 | `find . -type f -name "*.php" ! -path "*/vendor/*" ! -path "*/vendor_test/*" ! -path "*/.tmp/*" ! -path "*/.git/*" -print0 | xargs -0 wc -l | tail -1 | awk '{print $1}'` |
+| Production PHP lines (`includes/`, `wp-sudo.php`, `uninstall.php`, `mu-plugin/`, `bridges/`) | 12,076 | `find ./includes ./wp-sudo.php ./uninstall.php ./mu-plugin ./bridges -type f -name "*.php" -print0 | xargs -0 wc -l | tail -1 | awk '{print $1}'` |
+| Tests PHP lines (`tests/`) | 22,260 | `find ./tests -type f -name "*.php" -print0 | xargs -0 wc -l | tail -1 | awk '{print $1}'` |
+| Production + tests PHP lines | 34,336 | sum of the two rows above |
+| Test-to-production ratio | 1.84:1 | `22260 / 12076` |
+| Total repo PHP lines (excluding `vendor/`, `vendor_test/`, `.tmp/`, `.git/`) | 34,599 | `find . -type f -name "*.php" ! -path "*/vendor/*" ! -path "*/vendor_test/*" ! -path "*/.tmp/*" ! -path "*/.git/*" -print0 | xargs -0 wc -l | tail -1 | awk '{print $1}'` |
 
 ## Architectural Facts
 
@@ -39,8 +39,8 @@ the count in prose without a verification command.
 | Gated rules (total) | 34 | `grep "'id'" includes/class-action-registry.php \| grep -v "rule\[" \| wc -l` | unreleased |
 | Help tabs | 12 | `grep -c -- "->add_help_tab(" includes/class-admin.php` | unreleased |
 | Audit hooks | 11 | `python3 - <<'PY'\nimport pathlib, re\nhooks = set()\nfor path in pathlib.Path('includes').glob('class-*.php'):\n    hooks.update(re.findall(r\"do_action\\(\\s*'([^']+)'\", path.read_text()))\nhooks.discard('wp_sudo_render_two_factor_fields')\nprint(len(hooks))\nPY` | unreleased (v3.0.0) |
-| Settings fields (base) | 7 | 1 numeric (duration) + 1 toggle (passthrough) + 1 preset chooser + 4 policy dropdowns (REST, CLI, Cron, XML-RPC) | unreleased (v3.0.0) |
-| Settings fields (with WPGraphQL) | 8 | +1 conditional WPGraphQL policy dropdown | unreleased (v3.0.0) |
+| Settings fields (base) | 6 | 1 numeric (duration) + 1 preset chooser + 4 policy dropdowns (REST, CLI, Cron, XML-RPC) | unreleased (v3.0.0) |
+| Settings fields (with WPGraphQL) | 7 | +1 conditional WPGraphQL policy dropdown | unreleased (v3.0.0) |
 | E2E tests | 60 | `npx playwright test --config tests/e2e/playwright.config.ts --list` | unreleased |
 
 ### Files that reference these counts
@@ -66,7 +66,7 @@ Source: `.github/workflows/phpunit.yml`, `.github/workflows/e2e.yml`, `.github/w
 
 ## Verification Notes
 
-- `composer test:unit` passed on 2026-04-20 (`627 tests`, `1781 assertions`).
+- `composer test:unit` passed on 2026-04-20 (`632 tests`, `1796 assertions`).
 - `composer test:integration` passed on 2026-04-20 (`165 tests`, `538 assertions`, `9 skipped`) using the repo wrapper's `wp-env` `tests-cli` fallback against the containerized `wordpress_test` database.
 - `WP_MULTISITE=1 composer test:integration` passed on 2026-04-20 (`165 tests`, `552 assertions`, `2 skipped`) using the same `wp-env` `tests-cli` fallback and database.
 - `composer analyse:phpstan`, `composer analyse:psalm`, and `composer lint` passed on 2026-04-19.

docs/developer-reference.md

@@ -315,6 +315,7 @@ needed. It remains inert when Stream APIs are unavailable.
 | `wp_sudo_requires_two_factor` | Whether a user needs 2FA for sudo (for third-party 2FA plugins). |
 | `wp_sudo_validate_two_factor` | Validate a 2FA code (for third-party 2FA plugins). |
 | `wp_sudo_render_two_factor_fields` | Render 2FA input fields (for third-party 2FA plugins). |
+| `wp_sudo_log_passed_events_enabled` | Toggle recording of `action_passed` dashboard events. Default `true`; intended for explicit code-level overrides only. |
 | `wp_sudo_wpgraphql_classification` | Classify WPGraphQL body as `mutation` or `query` (persisted-query support). |
 | `wp_sudo_wpgraphql_bypass` | Bypass WPGraphQL Limited-mode gating for specific requests. |
 

includes/class-admin.php

@@ -118,6 +118,20 @@ class Admin {
 	 */
 	public const POLICY_PRESET_CUSTOM = 'custom';
 
+	/**
+	 * Constant name for disabling Passed-event logging via code.
+	 *
+	 * @var string
+	 */
+	public const DISABLE_PASSED_EVENT_LOGGING_CONSTANT = 'WP_SUDO_DISABLE_PASSED_EVENT_LOGGING';
+
+	/**
+	 * Filter name for enabling/disabling Passed-event logging via code.
+	 *
+	 * @var string
+	 */
+	public const PASSED_EVENT_LOGGING_FILTER = 'wp_sudo_log_passed_events_enabled';
+
 	/**
 	 * Transient prefix for one-shot preset summary notices.
 	 *
@@ -580,15 +594,6 @@ public function register_sections(): void {
 			array( 'label_for' => 'session_duration' )
 		);
 
-		add_settings_field(
-			'log_passthrough',
-			__( 'Log Session Pass-Throughs', 'wp-sudo' ),
-			array( $this, 'render_field_log_passthrough' ),
-			self::PAGE_SLUG,
-			'wp_sudo_session',
-			array( 'label_for' => 'log_passthrough' )
-		);
-
 		// Entry point policies section.
 		add_settings_section(
 			'wp_sudo_policies',
@@ -832,6 +837,41 @@ public static function reset_cache(): void {
 		self::$cached_settings = null;
 	}
 
+	/**
+	 * Return whether Passed-event logging is enabled.
+	 *
+	 * Passed-event logging is enabled by default and intentionally not
+	 * configurable from the UI. It may only be disabled via a code-level
+	 * override (constant/filter) for exceptional environments.
+	 *
+	 * @since 3.0.0
+	 *
+	 * @return bool
+	 */
+	public static function is_passed_event_logging_enabled(): bool {
+		$enabled = true;
+
+		if ( defined( self::DISABLE_PASSED_EVENT_LOGGING_CONSTANT ) && constant( self::DISABLE_PASSED_EVENT_LOGGING_CONSTANT ) ) {
+			$enabled = false;
+		}
+
+		if ( function_exists( 'apply_filters' ) ) {
+			/**
+			 * Filter whether WP Sudo records action_passed events.
+			 *
+			 * Return false only when a deployment intentionally accepts reduced
+			 * audit visibility for actions performed during active sudo sessions.
+			 *
+			 * @since 3.0.0
+			 *
+			 * @param bool $enabled Default true unless disabled by constant.
+			 */
+			$enabled = (bool) apply_filters( self::PASSED_EVENT_LOGGING_FILTER, $enabled );
+		}
+
+		return $enabled;
+	}
+
 	/**
 	 * Sanitize settings input.
 	 *
@@ -848,9 +888,6 @@ public function sanitize_settings( array $input ): array {
 			$sanitized['session_duration'] = 15;
 		}
 
-		// Log passthrough: boolean toggle.
-		$sanitized['log_passthrough'] = ! empty( $input['log_passthrough'] );
-
 		// Entry point policies: disabled, limited, or unrestricted.
 		$policy_keys = self::policy_setting_keys();
 
@@ -1176,6 +1213,7 @@ public function render_settings_page(): void {
 		<div class="wrap">
 			<h1><?php echo esc_html( get_admin_page_title() ); ?></h1>
 			<?php $this->render_policy_preset_notice(); ?>
+			<?php $this->render_passed_event_logging_override_notice(); ?>
 			<?php if ( $is_network && isset( $_GET['updated'] ) ) : // phpcs:ignore WordPress.Security.NonceVerification.Recommended ?>
 				<div class="notice notice-success is-dismissible wp-sudo-notice">
 					<p><?php esc_html_e( 'Settings saved.', 'wp-sudo' ); ?></p>
@@ -1668,21 +1706,6 @@ public function render_field_session_duration(): void {
 		echo '<p class="description">' . esc_html__( 'How long a sudo session lasts before automatically expiring. Range: 1–15 minutes. Default: 15 minutes.', 'wp-sudo' ) . '</p>';
 	}
 
-	/**
-	 * Render the log_passthrough toggle field.
-	 *
-	 * @return void
-	 */
-	public function render_field_log_passthrough(): void {
-		$value = self::get( 'log_passthrough', false );
-		printf(
-			'<input type="checkbox" id="log_passthrough" name="%s[log_passthrough]" value="1" %s />',
-			esc_attr( self::OPTION_KEY ),
-			checked( $value, true, false )
-		);
-		echo '<p class="description">' . esc_html__( 'Log each gated action that succeeds during an active sudo session. Disable to see only gate friction (challenges, blocks, replays) in the dashboard widget. Enable to see a complete audit trail including actions that passed through due to an active session. Default: off.', 'wp-sudo' ) . '</p>';
-	}
-
 	/**
 	 * Render the policy preset chooser.
 	 *
@@ -2073,6 +2096,33 @@ private function render_policy_preset_notice(): void {
 		);
 	}
 
+	/**
+	 * Render an explicit warning when Passed-event logging is code-disabled.
+	 *
+	 * @return void
+	 */
+	private function render_passed_event_logging_override_notice(): void {
+		if ( self::is_passed_event_logging_enabled() ) {
+			return;
+		}
+
+		$message = __( 'Passed event logging is disabled by code override (constant/filter). Actions performed during active sudo sessions will not appear in dashboard event history.', 'wp-sudo' );
+
+		if ( function_exists( 'wp_get_admin_notice' ) ) {
+			$notice_html = wp_get_admin_notice(
+				$message,
+				array(
+					'type'               => 'warning',
+					'additional_classes' => array( 'wp-sudo-notice' ),
+				)
+			);
+			echo wp_kses_post( $notice_html );
+			return;
+		}
+
+		echo '<div class="notice notice-warning wp-sudo-notice"><p>' . esc_html( $message ) . '</p></div>';
+	}
+
 	/**
 	 * Convert a preset key to a display label.
 	 *

includes/class-dashboard-widget.php

@@ -89,7 +89,6 @@ public static function render(): void {
 	 */
 	private const DEFAULTS = array(
 		'session_duration'         => 15,
-		'log_passthrough'          => false,
 		'rest_app_password_policy' => 'limited',
 		'cli_policy'               => 'limited',
 		'cron_policy'              => 'disabled',
@@ -131,12 +130,15 @@ private static function render_active_sessions(): void {
 
 		if ( 0 === $count ) {
 			echo '<div class="wp-sudo-empty-container">';
-			echo '<div class="wp-sudo-empty-status"><strong>' . esc_html__( 'No active sessions now...', 'wp-sudo' ) . '</strong></div>';
+			echo '<div class="wp-sudo-empty-status">';
+			echo '<span class="wp-sudo-empty-status-icon" aria-hidden="true"><span class="dashicons dashicons-lock"></span></span>';
+			echo '<strong>' . esc_html__( 'No active sessions now...', 'wp-sudo' ) . '</strong>';
+			echo '</div>';
 			echo '<div class="wp-sudo-empty-desc">';
 			echo '<p>' . esc_html__( 'Sudo monitors gated actions to ensure high-privilege operations are authorized. Events are logged here to provide visibility into who is performing sensitive tasks.', 'wp-sudo' ) . '</p>';
 			echo '<p>' . sprintf(
 				/* translators: %1$s: opening link tag, %2$s: closing link tag */
-				esc_html__( 'You can also %1$svisit the Sudo Settings page%2$s to configure session durations and logging.', 'wp-sudo' ),
+				esc_html__( 'You can also %1$svisit the Sudo Settings page%2$s to configure session durations and policies.', 'wp-sudo' ),
 				'<a href="' . esc_url( admin_url( 'options-general.php?page=wp-sudo-settings' ) ) . '">',
 				'</a>'
 			) . '</p>';
@@ -236,31 +238,18 @@ private static function render_active_sessions(): void {
 	 * @return void
 	 */
 	private static function render_recent_events(): void {
-		$settings = get_option( 'wp_sudo_settings', array() );
-		if ( ! is_array( $settings ) ) {
-			$settings = array();
-		}
-		$log_passthrough = ! empty( $settings['log_passthrough'] );
+		$passed_event_logging_enabled = Admin::is_passed_event_logging_enabled();
 
 		// Ensure the events table exists before querying.
 		Event_Store::maybe_create_table();
 		$events = Event_Store::recent_for_dashboard( 50 ); // Get more for client-side filtering.
 
 		echo '<h3>' . esc_html__( 'Recent Events', 'wp-sudo' ) . '</h3>';
 
-		// Pass-through notice.
-		if ( ! $log_passthrough ) {
-			$settings_url = esc_url( admin_url( 'options-general.php?page=wp-sudo-settings#log_passthrough' ) );
+		// Code-override notice.
+		if ( ! $passed_event_logging_enabled ) {
 			echo '<p class="wp-sudo-filter-notice">';
-			echo wp_kses(
-				sprintf(
-					/* translators: %1$s: opening link tag, %2$s: closing link tag */
-					__( 'Enable "Log Passed Sessions" in %1$sSettings%2$s to track Passed events.', 'wp-sudo' ),
-					'<a href="' . $settings_url . '">',
-					'</a>'
-				),
-				array( 'a' => array( 'href' => array() ) )
-			);
+			echo esc_html__( 'Passed events are currently hidden by a code-level policy override.', 'wp-sudo' );
 			echo '</p>';
 		}
 
@@ -281,7 +270,7 @@ private static function render_recent_events(): void {
 		echo '<option value="action_gated">' . esc_html__( 'Gated', 'wp-sudo' ) . '</option>';
 		echo '<option value="action_blocked">' . esc_html__( 'Blocked', 'wp-sudo' ) . '</option>';
 		echo '<option value="action_allowed">' . esc_html__( 'Allowed', 'wp-sudo' ) . '</option>';
-		echo '<option value="action_passed"' . ( $log_passthrough ? '' : ' disabled' ) . '>';
+		echo '<option value="action_passed"' . ( $passed_event_logging_enabled ? '' : ' disabled' ) . '>';
 		echo esc_html__( 'Passed', 'wp-sudo' );
 		echo '</option>';
 		echo '<option value="action_replayed">' . esc_html__( 'Replayed', 'wp-sudo' ) . '</option>';
@@ -562,15 +551,43 @@ private static function render_inline_styles(): void {
 }
 
 #wp_sudo_activity .wp-sudo-empty-container {
-	display: flex;
-	gap: 1.5em;
+	display: grid;
+	grid-template-columns: minmax(140px, 30%) 1fr;
+	gap: 1.25em;
 	align-items: flex-start;
 	margin-bottom: 1em;
 }
 #wp_sudo_activity .wp-sudo-empty-status {
-	font-weight: 600;
-	min-width: 140px;
-	flex-shrink: 0;
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	justify-content: center;
+	gap: 0.4em;
+	padding: 0.75em 0.5em;
+	border: 1px solid #e0e0e0;
+	border-radius: 4px;
+	background: #f8f9fa;
+	min-height: 120px;
+	text-align: center;
+}
+#wp_sudo_activity .wp-sudo-empty-status strong {
+	font-size: 1.05em;
+	line-height: 1.25;
+}
+#wp_sudo_activity .wp-sudo-empty-status-icon {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	width: 32px;
+	height: 32px;
+	border-radius: 999px;
+	background: #f0f6fc;
+	color: #2271b1;
+}
+#wp_sudo_activity .wp-sudo-empty-status-icon .dashicons {
+	width: 18px;
+	height: 18px;
+	font-size: 18px;
 }
 #wp_sudo_activity .wp-sudo-empty-desc {
 	font-size: 0.85em;
@@ -639,6 +656,13 @@ private static function render_inline_styles(): void {
 	#wp_sudo_activity .wp-sudo-event-filters {
 		gap: 3px;
 	}
+	#wp_sudo_activity .wp-sudo-empty-container {
+		grid-template-columns: 1fr;
+		gap: 0.75em;
+	}
+	#wp_sudo_activity .wp-sudo-empty-status {
+		min-height: 0;
+	}
 }
 </style>
 <script>

includes/class-event-recorder.php

@@ -178,7 +178,8 @@ public static function on_action_replayed( int $user_id, string $rule_id ): void
 	 * Handle wp_sudo_action_passed event.
 	 *
 	 * Fired when a gated action passes through due to an active sudo session.
-	 * Only logs when the log_passthrough setting is enabled.
+	 * Logging is enabled by default and may only be disabled by explicit
+	 * code-level override (constant/filter).
 	 *
 	 * @since 3.0.0
 	 *
@@ -188,10 +189,8 @@ public static function on_action_replayed( int $user_id, string $rule_id ): void
 	 * @return void
 	 */
 	public static function on_action_passed( int $user_id, string $rule_id, string $surface ): void {
-		// Check the log_passthrough setting.
-		$log_passthrough = Admin::get( 'log_passthrough', false );
-		if ( ! $log_passthrough ) {
-			return; // User opted out of passthrough logging.
+		if ( ! Admin::is_passed_event_logging_enabled() ) {
+			return;
 		}
 
 		Event_Store::insert(