Phase 2: security hardening — token user-binding, credential marker, log caps, domain enforcement (supersedes #67) (#99)

* fix: audit-log failed confirmed-destructive calls; warn on wrapper collisions

- Saddle_Approval::gate now logs a confirmed destructive execution even when
  the executor returns WP_Error — a partial mutation with no audit trail is
  worse than a noisy one. The entry carries a "FAILED after confirmation"
  marker plus the error message.
- Saddle_Integrations::wrap surfaces genuine wrapper-name collisions via
  _doing_it_wrong instead of silently dropping the partner tool; its own
  wrappers are tracked so idempotent re-runs stay silent.

Part of Phase 1 (correctness) of the 2026-07 architecture review
(plugpressco/saddle-pro#39).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0133CZhoFPY6BBChDDGEa22Q

* feat: security hardening — token user-binding, credential marker, split log caps, domain enforcement

- Approval tokens are bound to the previewing user: with several agents on
  one site, agent A's preview can no longer be confirmed by agent B
  (saddle_token_user_mismatch).
- Saddle-issued app passwords are recorded by UUID in user meta
  (saddle_issued_credentials); credential scoping, the XML-RPC block, and
  client revoke/rotate/list key on that immutable marker instead of the
  user-editable display name. Legacy prefix-named keys migrate on sight.
- Saddle_Log GC caps denials (300) and executed mutations (1000) as
  separate filterable buckets, batch raised to 500, so denial noise can
  never evict change history.
- Opt-in domain-drift enforcement (saddle_enforce_tier_domain, default
  off): write/admin abilities refuse on a migrated/cloned domain until the
  owner re-confirms the tier; exposed via GET/POST /settings.

Phase 2 of the 2026-07 architecture review (#63).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0133CZhoFPY6BBChDDGEa22Q

* style: Yoda condition on the token user-binding check

phpcs flagged it after the merge; WPCS wants the call on the left.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GkZr73cqaSesHRDG89Yy8S

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: ifahimreza

includes/admin/class-saddle-rest.php

@@ -512,6 +512,7 @@ public static function get_settings() {
 				'domain'         => array(
 					'current'  => Saddle_Capabilities::current_domain(),
 					'recorded' => Saddle_Capabilities::recorded_tier_domain(),
+					'enforced' => Saddle_Capabilities::is_domain_enforced(),
 				),
 				// The key itself never leaves the server — only whether one is
 				// set, plus a last-4 hint so the owner can recognize it.
@@ -561,6 +562,10 @@ public static function update_settings( WP_REST_Request $request ) {
 			Saddle_Capabilities::set_paused( (bool) $request->get_param( 'paused' ) );
 		}
 
+		if ( array_key_exists( 'domain_enforced', $params ) ) {
+			Saddle_Capabilities::set_domain_enforcement( (bool) $request->get_param( 'domain_enforced' ) );
+		}
+
 		// Key absent from the body ⇒ untouched; '' or null ⇒ cleared;
 		// non-empty ⇒ validated and saved.
 		if ( array_key_exists( 'unsplash_access_key', $params ) ) {
@@ -988,6 +993,10 @@ public static function create_client( WP_REST_Request $request ) {
 		$hints[ $item['uuid'] ] = $hint;
 		update_user_meta( $user->ID, 'saddle_client_hints', $hints );
 
+		// The immutable ownership marker credential scoping keys on — the
+		// display name alone is user-editable and can't be trusted for it.
+		Saddle_Connection::mark_issued( $user->ID, $item['uuid'] );
+
 		return new WP_REST_Response(
 			array(
 				'uuid'       => $item['uuid'],
@@ -1017,13 +1026,15 @@ public static function get_clients() {
 
 			$passwords = WP_Application_Passwords::get_user_application_passwords( $user_id );
 			foreach ( (array) $passwords as $item ) {
-				if ( empty( $item['name'] ) || 0 !== strpos( $item['name'], self::CLIENT_PREFIX ) ) {
+				// Marker first (rename-proof), name prefix for legacy keys.
+				if ( empty( $item['uuid'] ) || ! Saddle_Connection::is_saddle_issued( $user_id, $item['uuid'] ) ) {
 					continue;
 				}
+				$name = isset( $item['name'] ) ? (string) $item['name'] : '';
 				$clients[] = array(
 					'uuid'      => $item['uuid'],
-					'name'      => $item['name'],
-					'label'     => trim( substr( $item['name'], strlen( self::CLIENT_PREFIX ) ) ),
+					'name'      => $name,
+					'label'     => 0 === strpos( $name, self::CLIENT_PREFIX ) ? trim( substr( $name, strlen( self::CLIENT_PREFIX ) ) ) : $name,
 					'created'   => isset( $item['created'] ) ? (int) $item['created'] : 0,
 					'last_used' => isset( $item['last_used'] ) ? $item['last_used'] : null,
 					'last_ip'   => isset( $item['last_ip'] ) ? $item['last_ip'] : null,
@@ -1051,17 +1062,20 @@ public static function revoke_client( WP_REST_Request $request ) {
 			return new WP_Error( 'saddle_app_passwords_unavailable', __( 'Application Passwords are not available on this site.', 'saddle' ), array( 'status' => 500 ) );
 		}
 
-		// Only allow revoking a Saddle-prefixed password, so this endpoint can't
-		// be used to delete unrelated credentials.
+		// Only allow revoking a Saddle-issued password, so this endpoint can't
+		// be used to delete unrelated credentials. Checked via the immutable
+		// marker (with legacy name-prefix fallback), so a renamed key can
+		// still be revoked here.
 		$item = WP_Application_Passwords::get_user_application_password( $user_id, $uuid );
-		if ( ! $item || empty( $item['name'] ) || 0 !== strpos( $item['name'], self::CLIENT_PREFIX ) ) {
+		if ( ! $item || ! Saddle_Connection::is_saddle_issued( $user_id, $uuid ) ) {
 			return new WP_Error( 'saddle_client_not_found', __( 'No Saddle client with that ID.', 'saddle' ), array( 'status' => 404 ) );
 		}
 
 		$result = WP_Application_Passwords::delete_application_password( $user_id, $uuid );
 		if ( is_wp_error( $result ) ) {
 			return $result;
 		}
+		Saddle_Connection::unmark_issued( $user_id, $uuid );
 
 		// Drop the stored last-4 hint along with the credential.
 		$hints = get_user_meta( $user_id, 'saddle_client_hints', true );
@@ -1105,7 +1119,7 @@ public static function rotate_client( WP_REST_Request $request ) {
 
 		// Same guard as revoke_client: only Saddle-issued credentials.
 		$item = WP_Application_Passwords::get_user_application_password( $user->ID, $uuid );
-		if ( ! $item || empty( $item['name'] ) || 0 !== strpos( $item['name'], self::CLIENT_PREFIX ) ) {
+		if ( ! $item || ! Saddle_Connection::is_saddle_issued( $user->ID, $uuid ) ) {
 			return new WP_Error( 'saddle_client_not_found', __( 'No Saddle client with that ID.', 'saddle' ), array( 'status' => 404 ) );
 		}
 
@@ -1132,13 +1146,15 @@ public static function rotate_client( WP_REST_Request $request ) {
 
 		list( $raw_password, $new_item ) = $created;
 
-		// Swap the last-4 hint: old uuid out, new one in.
+		// Swap the last-4 hint and the issued marker: old uuid out, new one in.
 		$hint  = substr( str_replace( ' ', '', $raw_password ), -4 );
 		$hints = get_user_meta( $user->ID, 'saddle_client_hints', true );
 		$hints = is_array( $hints ) ? $hints : array();
 		unset( $hints[ $uuid ] );
 		$hints[ $new_item['uuid'] ] = $hint;
 		update_user_meta( $user->ID, 'saddle_client_hints', $hints );
+		Saddle_Connection::unmark_issued( $user->ID, $uuid );
+		Saddle_Connection::mark_issued( $user->ID, $new_item['uuid'] );
 
 		return new WP_REST_Response(
 			array(

includes/class-saddle-approval.php

@@ -156,7 +156,8 @@ public static function gate( array $args ) {
 	}
 
 	/**
-	 * Create and persist a single-use token bound to an action and target.
+	 * Create and persist a single-use token bound to an action, a target, and
+	 * the previewing user.
 	 *
 	 * @param string $action Action identifier.
 	 * @param string $target Target identifier the token is bound to (e.g. post id).
@@ -197,6 +198,10 @@ private static function issue_token( $action, $target = '', $bind = '' ) {
 		update_post_meta( $post_id, '_saddle_action', $action );
 		update_post_meta( $post_id, '_saddle_target', $target );
 		update_post_meta( $post_id, '_saddle_bind', $bind );
+		// The token belongs to whoever saw the preview: with several agents on
+		// one site (separate app passwords / users), agent A's preview must
+		// not be confirmable by agent B.
+		update_post_meta( $post_id, '_saddle_user', get_current_user_id() );
 		update_post_meta( $post_id, '_saddle_expires', time() + self::TOKEN_TTL );
 
 		return $token;
@@ -218,7 +223,7 @@ private static function hash_token( $token ) {
 	/**
 	 * Validate and consume a token. Single-use: the token record is deleted on
 	 * lookup regardless of outcome, so even a mismatched/expired token cannot be
-	 * retried.
+	 * retried. The consumer must be the same user the preview was issued to.
 	 *
 	 * @param string $token  Candidate token.
 	 * @param string $action Action the token must be bound to.
@@ -257,11 +262,20 @@ public static function consume_token( $token, $action, $target = '', $bind = ''
 		$stored_action = get_post_meta( $post_id, '_saddle_action', true );
 		$stored_target = (string) get_post_meta( $post_id, '_saddle_target', true );
 		$stored_bind   = (string) get_post_meta( $post_id, '_saddle_bind', true );
+		$stored_user   = (int) get_post_meta( $post_id, '_saddle_user', true );
 		$expires       = (int) get_post_meta( $post_id, '_saddle_expires', true );
 
 		// Single-use: burn the token now, before any further branching.
 		wp_delete_post( $post_id, true );
 
+		if ( get_current_user_id() !== $stored_user ) {
+			return new WP_Error(
+				'saddle_token_user_mismatch',
+				__( 'This confirmation token was issued to a different user. Preview the action yourself, then confirm with the token it returns.', 'saddle' ),
+				array( 'status' => 403 )
+			);
+		}
+
 		if ( $stored_action !== $action ) {
 			return new WP_Error(
 				'saddle_token_mismatch',

includes/class-saddle-capabilities.php

@@ -60,6 +60,15 @@ class Saddle_Capabilities {
 	 */
 	const TIER_DOMAIN_OPTION = 'saddle_tier_domain';
 
+	/**
+	 * Option key for opt-in domain-drift enforcement. Off by default (warn
+	 * only). When on, write- and admin-tier abilities are refused while the
+	 * current domain differs from the one the tier was granted on — a cloned
+	 * or migrated database then lands read-only until the owner re-confirms
+	 * the access level (set_tier re-records the domain).
+	 */
+	const ENFORCE_DOMAIN_OPTION = 'saddle_enforce_tier_domain';
+
 	/**
 	 * Tier name => numeric rank. Higher rank = more power.
 	 *
@@ -265,6 +274,11 @@ public static function permission( $level, $cap = 'read', $short_name = null ) {
 				return false;
 			}
 
+			if ( 'read' !== $level && self::is_domain_enforced() && ! self::domain_matches_recorded() ) {
+				self::log_denial( $short_name, 'domain' );
+				return false;
+			}
+
 			if ( ! self::tier_allows( $level ) ) {
 				self::log_denial( $short_name, 'tier' );
 				return false;
@@ -441,6 +455,15 @@ public static function denial_reason( $ability_name ) {
 					),
 				);
 			}
+
+			// Domain enforcement sits between the capability and the tier here,
+			// mirroring the order permission() checks them in.
+			if ( 'read' !== $required && '' !== $required && self::is_domain_enforced() && ! self::domain_matches_recorded() ) {
+				return array(
+					'code'    => 'saddle_domain_drift',
+					'message' => __( 'This site\'s domain changed since write access was granted, and the owner has domain enforcement on — write tools are refused until they re-confirm the access level (Saddle → Permissions). Do not retry; tell the user.', 'saddle' ),
+				);
+			}
 			if ( '' !== $required && ! self::tier_allows( $required ) ) {
 				// The site allows this, but the credential in hand doesn't — the
 				// app was granted a narrower scope when it was authorized. That
@@ -486,7 +509,7 @@ public static function denial_reason( $ability_name ) {
 	 * flood the log, and it never fires for anonymous requests.
 	 *
 	 * @param string|null $short_name Ability id without the 'saddle/' prefix.
-	 * @param string      $reason     'paused' | 'capability' | 'disabled' | 'tier'.
+	 * @param string      $reason     'paused' | 'capability' | 'disabled' | 'domain' | 'tier'.
 	 */
 	private static function log_denial( $short_name, $reason ) {
 		if ( ! class_exists( 'Saddle_Log' ) ) {
@@ -515,6 +538,10 @@ private static function log_denial( $short_name, $reason ) {
 				/* translators: %s: tool name. */
 				$summary = sprintf( __( 'Blocked: the tool "%s" is turned off.', 'saddle' ), $tool );
 				break;
+			case 'domain':
+				/* translators: %s: tool name. */
+				$summary = sprintf( __( 'Blocked: the site domain changed since write access was granted — "%s" is refused until the access level is re-confirmed.', 'saddle' ), $tool );
+				break;
 			case 'tier':
 			default:
 				/* translators: %s: tool name. */
@@ -552,6 +579,25 @@ public static function set_paused( $paused ) {
 		return update_option( self::PAUSED_OPTION, (bool) $paused );
 	}
 
+	/**
+	 * Whether domain-drift enforcement is on (see ENFORCE_DOMAIN_OPTION).
+	 *
+	 * @return bool
+	 */
+	public static function is_domain_enforced() {
+		return (bool) get_option( self::ENFORCE_DOMAIN_OPTION, false );
+	}
+
+	/**
+	 * Turn domain-drift enforcement on or off.
+	 *
+	 * @param bool $enforce Whether write/admin abilities require the recorded domain.
+	 * @return bool
+	 */
+	public static function set_domain_enforcement( $enforce ) {
+		return update_option( self::ENFORCE_DOMAIN_OPTION, (bool) $enforce );
+	}
+
 	/**
 	 * The site's current hostname, for comparison against the recorded one.
 	 *

includes/class-saddle-connection.php

@@ -33,6 +33,15 @@ class Saddle_Connection {
 	 */
 	const HTACCESS_MARKER = 'Saddle Authorization Header';
 
+	/**
+	 * User-meta key recording the UUIDs of app passwords Saddle issued.
+	 *
+	 * The immutable identity credential scoping keys on: the display name
+	 * ("Saddle: …") is user-editable in wp-admin, and scoping that silently
+	 * stops applying after a rename would hand the key full wp/v2 access.
+	 */
+	const ISSUED_META = 'saddle_issued_credentials';
+
 	/**
 	 * Scope Saddle-issued credentials to Saddle's own REST surface.
 	 *
@@ -75,7 +84,7 @@ public static function scope_credentials( $response, $handler, $request ) {
 		$uuid = function_exists( 'rest_get_authenticated_app_password' )
 			? rest_get_authenticated_app_password()
 			: null;
-		if ( ! $uuid || ! self::is_saddle_credential( get_current_user_id(), $uuid ) ) {
+		if ( ! $uuid || ! self::is_saddle_issued( get_current_user_id(), $uuid ) ) {
 			return $response;
 		}
 
@@ -134,8 +143,10 @@ public static function block_xmlrpc_credentials( $error, $user, $item ) {
 		if ( ! apply_filters( 'saddle_scope_credentials', true ) ) {
 			return;
 		}
-		$prefix = class_exists( 'Saddle_REST_Admin' ) ? Saddle_REST_Admin::CLIENT_PREFIX : 'Saddle: ';
-		if ( isset( $item['name'] ) && 0 === strpos( (string) $item['name'], $prefix ) ) {
+		$is_saddle = isset( $item['uuid'] ) && $user instanceof WP_User
+			? self::is_saddle_issued( $user->ID, (string) $item['uuid'] )
+			: ( isset( $item['name'] ) && 0 === strpos( (string) $item['name'], class_exists( 'Saddle_REST_Admin' ) ? Saddle_REST_Admin::CLIENT_PREFIX : 'Saddle: ' ) );
+		if ( $is_saddle ) {
 			$error->add(
 				'saddle_credential_scope',
 				__( 'Saddle sign-in keys cannot be used over XML-RPC.', 'saddle' )
@@ -144,23 +155,73 @@ public static function block_xmlrpc_credentials( $error, $user, $item ) {
 	}
 
 	/**
-	 * Whether the given application password UUID is one Saddle issued
-	 * (identified by the `Saddle: ` name prefix) for this user.
+	 * Record an app-password UUID as Saddle-issued for a user.
+	 *
+	 * @param int    $user_id User the credential belongs to.
+	 * @param string $uuid    Application password UUID.
+	 */
+	public static function mark_issued( $user_id, $uuid ) {
+		$uuids = get_user_meta( (int) $user_id, self::ISSUED_META, true );
+		$uuids = is_array( $uuids ) ? $uuids : array();
+		if ( ! in_array( (string) $uuid, $uuids, true ) ) {
+			$uuids[] = (string) $uuid;
+			update_user_meta( (int) $user_id, self::ISSUED_META, $uuids );
+		}
+	}
+
+	/**
+	 * Forget a revoked credential's UUID.
+	 *
+	 * @param int    $user_id User the credential belonged to.
+	 * @param string $uuid    Application password UUID.
+	 */
+	public static function unmark_issued( $user_id, $uuid ) {
+		$uuids = get_user_meta( (int) $user_id, self::ISSUED_META, true );
+		if ( ! is_array( $uuids ) || ! in_array( (string) $uuid, $uuids, true ) ) {
+			return;
+		}
+		$uuids = array_values( array_diff( $uuids, array( (string) $uuid ) ) );
+		if ( $uuids ) {
+			update_user_meta( (int) $user_id, self::ISSUED_META, $uuids );
+		} else {
+			delete_user_meta( (int) $user_id, self::ISSUED_META );
+		}
+	}
+
+	/**
+	 * Whether the given application password UUID is one Saddle issued for
+	 * this user.
+	 *
+	 * Keyed on the stored UUID marker, which survives a rename in wp-admin →
+	 * Application Passwords. Keys issued before the marker existed are only
+	 * recognizable by their `Saddle: ` name prefix — those migrate into the
+	 * marker on first sight, so a later rename can no longer un-scope them.
 	 *
 	 * @param int    $user_id User the request authenticated as.
 	 * @param string $uuid    Application password UUID.
 	 * @return bool
 	 */
-	private static function is_saddle_credential( $user_id, $uuid ) {
-		if ( ! $user_id || ! class_exists( 'WP_Application_Passwords' ) ) {
+	public static function is_saddle_issued( $user_id, $uuid ) {
+		if ( ! $user_id || '' === (string) $uuid || ! class_exists( 'WP_Application_Passwords' ) ) {
 			return false;
 		}
+
+		$uuids = get_user_meta( (int) $user_id, self::ISSUED_META, true );
+		if ( is_array( $uuids ) && in_array( (string) $uuid, $uuids, true ) ) {
+			return true;
+		}
+
 		$item = WP_Application_Passwords::get_user_application_password( (int) $user_id, (string) $uuid );
 		if ( ! $item || empty( $item['name'] ) ) {
 			return false;
 		}
 		$prefix = class_exists( 'Saddle_REST_Admin' ) ? Saddle_REST_Admin::CLIENT_PREFIX : 'Saddle: ';
-		return 0 === strpos( (string) $item['name'], $prefix );
+		if ( 0 === strpos( (string) $item['name'], $prefix ) ) {
+			self::mark_issued( (int) $user_id, (string) $uuid );
+			return true;
+		}
+
+		return false;
 	}
 
 	/**