fix: gate email abilities on mailbox ownership, not just use_tools

[chubes4]

Fixes #3507

Where auth refs live and how ownership is resolved

email_imap mailbox refs are already a richer model than a flat user_id column — EmailAuth (extending BaseAuthProvider) stores named accounts scoped by site / user / agent ownership (AUTH_SCOPE_SITE|USER|AGENT), plus per-agent operation delegations (grant_agent()/revoke_agent()). EmailAuth::resolve_mailbox() / resolve_mailbox_for_principal() is the single authorization choke point every execute() path already calls: it resolves the ref, checks the caller against the account's owner (or an agent's delegation grant), and returns a WP_Error on denial.

The actual gap #3507 reports isn't a missing owner model — it's that ability permission_callbacks never consulted it. Every email ability's checkPermission() was a flat use_tools/can_manage capability floor. Ownership was enforced only deep inside execute()'s IMAP connection logic, so the Abilities API's permission_callback contract ("can this call proceed") never actually answered the resource-specific question — any use_tools holder passed the gate for any auth_ref.

What changed

Added EmailMailboxPermission (inc/Abilities/Email/EmailMailboxPermission.php), a trait providing authorizeMailboxRef( $input, $operation ):

• Requires the use_tools/can_manage floor first (unchanged baseline).
• When normalized input carries a concrete auth_ref, resolves it through EmailAuth::resolve_mailbox() as a side-effect-free preflight (_skip_audit context flag added to EmailAuth::audit() so the preflight doesn't double-log every real operation).
• Denies only on email_mailbox_forbidden — "this ref exists and you don't own it." Every other resolution failure (auth_ref_unresolved, auth_ref_invalid, email_mailbox_ambiguous) passes the permission gate and is left to execute() to report with its specific error — those are configuration/state problems, not authorization decisions, and collapsing them into a generic 403 would be a UX regression (confirmed against the existing EmailAbilityRestTest::test_rest_visible_email_test_connection_resolves_to_ability contract).
• When no auth_ref is present at all (e.g. a chat-tool availability probe called with no input), the capability floor alone governs — execute() still enforces whatever default/legacy-sender rule applies.

Every ability gated

fetch-email, email-reply, email-delete, email-move, email-flag, email-batch-move, email-batch-flag, email-batch-delete, email-unsubscribe, email-batch-unsubscribe, email-test-connection, send-email, send-email-queued. The EmailAbilities CRUD class's per-operation callbacks (each ability needs its own operation set — reply vs delete vs organize+delete for move, etc.) live in a new EmailAbilitiesPermissions trait rather than inline in EmailAbilities.php, which was already close to the codebase's 1500-line file-size audit threshold (homeboy review audit --profile pr flagged this on the first pass; splitting the trait out resolved it cleanly — verified green on the second pass).

send-email's one special case: when input carries a _mailbox_grant — a shape only SendEmailQueuedAbility's Action Scheduler worker ever produces — checkPermission() defers to execute()'s independent HMAC signature verification against the grant's own issuer identity, instead of re-deriving ownership from PermissionHelper's ambient context. That context is empty during real AS dispatch (no acting user/agent), so re-checking ownership there would incorrectly deny a send that was already authorized at queue time. send-email-queued itself needs no such case — queuing is always synchronous with live ambient context; the deferred send is dispatched directly against the datamachine_send_email_worker hook, never through wp_get_ability('datamachine/send-email-queued')->execute().

Decision on the existing unowned/global ref

email_imap:default (site scope, owner_id 0) stays a deliberately shared operational mailbox, gated by EmailAuth::can_use_default()'s management-capability check (manage_options / datamachine_manage_agents / datamachine_manage_flows / datamachine_manage_settings) — not by a bare use_tools floor.

This is why authorizeMailboxRef() reuses EmailAuth::resolve_mailbox() instead of routing through PermissionHelper::owns_resource() as the issue originally suggested: owns_resource() treats resource_user_id === 0 as "shared, accessible to anyone with the capability" (correct for jobs/agents in single-agent mode), which would have been a regression here — it would open the default mailbox to any use_tools holder, exactly the hole this PR closes. EmailAuth's named-account/delegation model already encodes the correct, narrower policy; reusing it keeps one source of truth instead of introducing a second, weaker mechanism that disagrees with the first.

Tests

New tests/Unit/Abilities/EmailMailboxPermissionTest.php:

• owner acts on their own named (AUTH_SCOPE_USER) mailbox → allowed
• non-owner with use_tools → denied
• admin does not get a standing backdoor into another user's connected mailbox (matches EmailAuth::can_access()'s existing contract — no admin override for user-scoped accounts)
• admin retains access to the shared email_imap:default mailbox
• a use_tools-only (non-management) caller is denied the shared default
• missing auth_ref falls back to the capability floor
• an unconfigured ref is not treated as a permission denial (lets execute() report it)
• send-email denies a direct call against an unowned ref, and defers to the signed grant when _mailbox_grant is present
• send-email-queued gates ownership at queue time with no grant special case

Plus updated require_once wiring in the existing pure-PHP smoke tests (send-email-template-smoke.php, email-reply-sent-copy-smoke.php, send-email-ability-lazy-definitions-smoke.php, abilities-send-email-load-order-smoke.php, lightweight-ability-manifest-smoke.php) that require these ability classes directly without an autoloader.

Verification (real results)

• Pure-PHP smoke tests (no WordPress needed): all 8 relevant files pass locally, including named-mailbox-security-contract-smoke.php, named-mailbox-delegation-smoke.php, legacy-email-upgrade-auth-smoke.php.
• homeboy review audit --changed-since origin/main --profile pr: pass, 0 introduced findings (after splitting EmailAbilitiesPermissions out — first pass flagged a god_file line-count finding on EmailAbilities.php, resolved).
• homeboy review lint --changed-only: phpcs 0 findings, eslint 0 findings, phpstan 69 findings — all pre-existing, confirmed by re-running the identical lint against unmodified main (via git stash) with an isolated failing test: the same 69 findings reproduce with zero relation to this diff. They're IMAP\Connection vs resource type-signature drift from a PHP/phpstan-stub version bump, plus a few right side of && is always true / empty() offset findings — all in pre-existing execute()-path IMAP code untouched by this PR, none in the new permission-callback code. Reporting honestly rather than claiming or hiding this: this is pre-existing debt, not introduced here.
• homeboy review test -- --filter Email (real WordPress test runtime via WP Codebox): 19/20 passed. The 1 failure (EmailAbilityRestTest::test_rest_visible_get_orphaned_posts_round_trip) is unrelated to email — confirmed pre-existing by running the identical filtered test against unmodified main, where it fails identically.

Out of scope (per the issue)

• Mailbox connect/attach UI (issue's step 3) — noted as a follow-up, not attempted here.
• data-machine-socials — the issue explicitly flags this as a sibling with a legitimately different answer (shared brand credentials vs. per-user inboxes) and out of scope for this PR.

🤖 Generated with Claude Code

[chubes4]

Rebased onto origin/main + local gate verification

Rebase: clean — no conflicts. git rebase origin/main applied this branch's single commit (0d5b693a1) on top of v0.176.22 (23 commits, including #3505's fail-closed credential decrypt touching EmailAuth.php, which landed in a non-overlapping region). I verified the PR's integration points survive: EmailAuth::resolve_mailbox( $ref, $operations, $context ) signature, the email_mailbox_forbidden error code, can_use_default(), save_named_account()/save_config(), and the AUTH_SCOPE_* constants are all unchanged on current main.

What CI actually failed on (run 35250825196)

Read the job logs rather than assuming they matched the PR body's claims:

• Candidate Lint / Lint: HOMEBOY_DIFFERENTIAL_GATING: false — the gate is absolute (0 findings in changed files). The 69 phpstan level-7 findings failed it outright. CI's own baseline comparison against base 2163b8e74 showed the base checkout producing 276 findings on the same file set (delta: -207) — but with drift_increased: true because every remaining finding's fingerprint changed. So: not introduced by this branch, but still gate-blocking because the gate is absolute, and CI never skips.
• Candidate Audit / Audit: the audit ran 817s, blew its 300s phase budget at 17:17:45, and exited 1 "without reporting a failure cause" — a timeout/infra failure mode, not a reported finding. No actionable code signal in that job.

Why both gates now pass without code changes

The 69 findings were IMAP\Connection vs resource type-signature drift plus stub artifacts from the phpstan toolchain pinned at the time CI last ran (Sep 17, base = pre-#3525). Main has since moved to the homeboy wordpress extension toolchain (#3525) and five more releases. The rebase alone resolves both failures — no suppression, no baselines, no ignores, and no code changes needed in this branch.

Local verification (post-rebase, homeboy 0.378.0)

Gate	Command	Result
Lint	homeboy review lint --changed-only	✅ pass — "lint phase passed with no findings"
Audit	homeboy review audit --changed-since origin/main --profile pr	✅ verdict: pass, 0 warnings
Smoke (8/8)	php tests/{send-email-template,email-reply-sent-copy,send-email-ability-lazy-definitions,abilities-send-email-load-order,lightweight-ability-manifest,named-mailbox-security-contract,named-mailbox-delegation,legacy-email-upgrade-auth}-smoke.php	✅ all pass (e.g. send-email-template: 121 assertions)
PHPUnit	tests/Unit/Abilities/EmailMailboxPermissionTest.php	⏳ needs the WP test runtime — see below

PHPUnit honesty note: the WP-runtime test suite could not execute on this host — no homeboy Lab runner is configured, the machine sat at load ~8–10 (sibling sessions), the run was deferred (deferred-9cb371be…, "no eligible Lab runner is currently ready"), and the local MariaDB grants don't permit the wptests test database. Rather than suppress or fake it: CI's Test shards were skipped in the failed run only because lint/audit failed upstream — with both gates now passing, the shards will run EmailMailboxPermissionTest in this push's CI. Result tracked in a follow-up comment.

Out of scope (unchanged)

System/anonymous sending stays in #3534 — untouched here.

🤖 Generated with Claude Code