Skip to content

chore: user-mailbox track backlog cleanup (rename MailboxCrud* wire types, drop dead require_root, soften MCP verb)#196

Merged
uzyn merged 1 commit into
mainfrom
chore/user-mailbox-backlog-cleanup
May 3, 2026
Merged

chore: user-mailbox track backlog cleanup (rename MailboxCrud* wire types, drop dead require_root, soften MCP verb)#196
uzyn merged 1 commit into
mainfrom
chore/user-mailbox-backlog-cleanup

Conversation

@uzyn

@uzyn uzyn commented May 3, 2026

Copy link
Copy Markdown
Owner

Summary

Bundles the four open items in the Non-blocking Review Backlog of docs/user-mailbox-sprint.md (lines 332-335) into a single mechanical cleanup PR. The user-mailbox initiative shipped in three sprints (PRs #193, #194, #195); these are the deferred-but-tracked nits.

Requirements

  • R1 — Add a one-line comment in install_tester_resolver_with_current_user (src/mailbox_handler.rs) explaining that the per-call lookup_username/getpwuid is intentional and cheap — preempts a future "let me memoize this" PR that would break test isolation.

  • R2 — Delete dead require_root / enforce_root from src/uds_authz.rs along with their three direct unit tests (require_root_rejects_non_root, require_root_accepts_root, enforce_root_logs_reject). Sprint 2 settled with no new root-only UDS verb adopting them. Caller, peer_username, and the rest of uds_authz.rs are untouched.

  • R3 — Rename pre-existing wire-protocol type names off the MailboxCrud prefix:

    • MailboxCrudRequest -> MailboxLifecycleRequest
    • Request::MailboxCrud(...) -> Request::MailboxLifecycle(...)
    • MailboxCrudFallback -> MailboxLifecycleFallback

    Mechanical refactor, ~71 occurrences across 5 files (src/send_protocol.rs, src/mailbox.rs, src/mailbox_handler.rs, src/mcp.rs, src/serve.rs). Wire-protocol verb strings (MAILBOX-CREATE, MAILBOX-DELETE) and other on-the-wire identifiers are unchanged.

  • R4 — Derive the format_auth_error rendering verb from the auth::Action variant in mcp::authorize_mailbox instead of hardcoding verb: Some("create"). MailboxCreate { .. } -> Some("create"), MailboxDelete { .. } -> Some("delete"), anything else -> None (renders as the generic "perform"). Keeps the rendering correct if a future predicate ever produces OwnerMismatch from a non-create action.

  • R5 — Mark the four bullets in the Non-blocking Review Backlog Improvements subsection as [x] (with an inline note pointing at this PR). The docs/ tree is gitignored in this repo, so the file is updated locally but does not appear in the PR diff.

Out of scope

  • Renaming any Action::Mailbox* authz variants — those landed correctly in Sprint 1.
  • Standardising the user-visible wording across the three format_auth_error call sites — Sprint 3 deliberately preserved each surface's existing strings; changing wording is a separate UX decision, not a cleanup.
  • Any other backlog items added later — only the four listed at lines 332-335 of docs/user-mailbox-sprint.md are in scope.

Technical approach

  • R1: single comment edit in the test scaffolding. No semantic change.
  • R2: pre-flight grep -rn "require_root\|enforce_root" src/ services/ | grep -v src/uds_authz.rs returned nothing — confirmed zero production callers. Deleted both pub fn definitions and the three direct unit tests. Other tests in uds_authz.rs::tests that consume Caller / AuthzDecision are untouched.
  • R3: per-file Edit with replace_all: true for each name, file by file. cargo build after each renamed-definition change caught any remaining call sites; the final post-rename grep -rn "MailboxCrud" src/ services/ returned nothing.
  • R4: five-line let verb = match &action { ... } block computed before the existing authorize(...) call (which moves action); the closure passes verb instead of Some("create"). Per the plan, no test scaffold added — the verb-derivation logic is one match arm and mcp.rs has no existing tests module that covers authorize_mailbox directly.

Test plan

  • cargo fmt -- --check (root + verifier) — clean
  • cargo clippy --all-targets -- -D warnings (root + verifier) — clean
  • cargo test (root crate, default lane) — 1124 tests pass, 0 failures (1026 unit + 97 integration + 1 uds_authz default; 8/5/21 ignored slots remain)
  • cargo test (verifier crate) — 43 pass, 0 failures
  • sudo -E env "PATH=$PATH" AIMX_INTEGRATION_SUDO=1 cargo test --test uds_authz -- --ignored --test-threads=121/21 pass (the canonical privilege-boundary regression guard; the rename touches handler entry points so this matters)
  • Strict spot-check: grep -rn "MailboxCrud" src/ services/ returns nothing — closes S3-6 strictly
  • Production callers gone: grep -rn "require_root\|enforce_root" src/ services/ returns nothing

Bundles the four open items from the user-mailbox sprint's
Non-blocking Review Backlog into a single mechanical cleanup PR:

- R1: comment in install_tester_resolver_with_current_user explaining
  the per-call lookup_username/getpwuid is intentional (preempts a
  future memoize-this PR that would break test isolation).
- R2: delete dead require_root / enforce_root from src/uds_authz.rs
  plus their three direct unit tests. Sprint 2 settled with no new
  root-only UDS verb adopting them.
- R3: rename pre-existing wire-protocol type names off the MailboxCrud
  prefix (MailboxCrudRequest -> MailboxLifecycleRequest, the enum
  variant Request::MailboxCrud -> Request::MailboxLifecycle, and
  MailboxCrudFallback -> MailboxLifecycleFallback). Closes the S3-6
  spot-check grep strictly. Wire verb strings (MAILBOX-CREATE /
  MAILBOX-DELETE) are unchanged.
- R4: derive the format_auth_error verb from the action variant in
  mcp::authorize_mailbox instead of hardcoding "create" — keeps the
  rendering correct if a future predicate ever produces OwnerMismatch
  from MailboxDelete (or anything else).

@uzyn uzyn left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes Overview

Bundles four mechanical cleanup items from the user-mailbox track's Non-blocking Review Backlog into a single PR: (R1) a 4-line comment explaining intentional non-memoization in a test resolver, (R2) deletes dead require_root / enforce_root + their three direct unit tests from src/uds_authz.rs, (R3) renames the wire-protocol type names MailboxCrudRequest -> MailboxLifecycleRequest, Request::MailboxCrud -> Request::MailboxLifecycle, and MailboxCrudFallback -> MailboxLifecycleFallback across 5 files, and (R4) derives the format_auth_error rendering verb in mcp::authorize_mailbox from the auth::Action variant (MailboxCreate -> "create", MailboxDelete -> "delete", else None) instead of hardcoding Some("create"). Strict net diff: +88 / -173.

Scope Alignment

All four in-tree items match the PR description exactly. R5 (marking the four backlog bullets [x] in docs/user-mailbox-sprint.md) does not appear in the diff because docs/ is a symlink to a path outside the repo — this is structural and called out in the PR description, not a gap.

No scope creep observed: wire-protocol verb strings (MAILBOX-CREATE / MAILBOX-DELETE / MAILBOX-LIST), auth::Action::Mailbox* variants, and format_auth_error itself are all untouched. Test scaffolds in mailbox_handler.rs::tests were updated to the new struct name with no semantic changes.

Independent Verification

  • git grep "MailboxCrud" 052db5db -- src/ services/ -> nothing. Closes the S3-6 spot-check strictly. (PR's claim verified.)
  • git grep "require_root\|enforce_root" 052db5db -- src/ services/ -> nothing. R2 deletion is safe; no production caller remains.
  • The remaining consumers of uds_authz are Caller, peer_username, log_decision, enforce_mailbox_owner_or_root — none touch the deleted helpers.
  • R4 verb-derivation match is exhaustive enough: explicit arms for MailboxCreate { .. } / MailboxDelete { .. }, fallback _ => None. format_auth_error defaults verb to "perform" when None, so OwnerMismatch from a hypothetical future non-create predicate will render as "cannot perform a mailbox owned by another user" — sensible. No panic! fallback.
  • No existing test asserts on the previous "create" wording from the MCP surface. auth.rs::tests exercises format_auth_error directly with explicit verb values and is unaffected.
  • Doc-comment housekeeping is consistent: the MCP comment correctly drops the stale "/ verb" mention now that verb is passed; MailboxLifecycleRequest's doc-comment block correctly updated; write_mailbox_crud_request's doc paragraph now references the new struct type.
  • On the PR head SHA 052db5db: cargo fmt -- --check clean; cargo clippy --all-targets -- -D warnings clean; cargo test --bin aimx 1026/1026; cargo test --test integration 97/97; cargo test --tests (uds_authz default lane) 1/1; verifier cargo test 43/43. All matches the PR's claimed numbers.

Potential Bugs

None.

Security Issues

None. R2 deletion does not weaken the authz surface — the deleted helpers had zero callers; mailbox-CRUD authorization runs through enforce_mailbox_owner_or_root and the auth::authorize predicate, both untouched.

Test Coverage

Adequate. The three deleted unit tests (require_root_rejects_non_root, require_root_accepts_root, enforce_root_logs_reject) exercised only the deleted helpers — removing them with the helpers is correct, not a regression. R4 has no new test scaffold (the PR description acknowledges this; mcp.rs has no tests module covering authorize_mailbox directly today and the verb derivation is one match arm). All other changes are mechanical type renames covered by the existing test suite that uses the renamed types.

Code Quality

One minor observation, non-blocker, out of scope per the literal R3 wording:

The R3 rename only touched CamelCase type identifiers. The underlying snake_case function names still carry the old mailbox_crud prefix:

  • submit_mailbox_crud_via_daemon (src/mcp.rs)
  • submit_mailbox_crud_request (src/mcp.rs)
  • handle_mailbox_crud (src/mailbox_handler.rs)
  • parse_mailbox_crud_headers (src/send_protocol.rs)
  • write_mailbox_crud_request (src/send_protocol.rs)
  • the mailbox_crud_create_then_mark_works_on_same_mailbox test name

This is consistent with the PR's stated scope ("rename pre-existing wire-protocol type names") and the strict spot-check (grep "MailboxCrud" — CamelCase) passes. But it leaves a stylistic mismatch between the type names and the function names that handle them. Worth tracking as a follow-up if the operator wants full nomenclature consistency, but absolutely not blocking.

Summary and Recommended Actions

  • Overall verdict: Ready to merge
  • Blockers: none
  • Non-blockers: none
  • Nice-to-haves: optional follow-up to rename the snake_case mailbox_crud function names to mailbox_lifecycle for full nomenclature consistency

Recommended merge commit message

chore: user-mailbox track backlog cleanup

Bundles the four Non-blocking Review Backlog items from the user-mailbox
track:

- Comment in `install_tester_resolver_with_current_user` documenting why
  per-call `lookup_username` is intentional (test isolation requirement).
- Delete dead `require_root` / `enforce_root` from `src/uds_authz.rs`
  and their three direct unit tests; no production callers remained
  after Sprint 1 retired the root-only mailbox-CRUD path.
- Rename wire-protocol type names off the `MailboxCrud` prefix:
  `MailboxCrudRequest` -> `MailboxLifecycleRequest`,
  `Request::MailboxCrud` -> `Request::MailboxLifecycle`,
  `MailboxCrudFallback` -> `MailboxLifecycleFallback`. Wire-protocol
  verb strings (`MAILBOX-CREATE` / `MAILBOX-DELETE`) unchanged.
- Derive `format_auth_error` rendering verb from the `auth::Action`
  variant in `mcp::authorize_mailbox` instead of hardcoding
  `Some("create")`, so a future predicate that emits `OwnerMismatch`
  from a non-create action renders correctly.

Net: +88 / -173. fmt + clippy clean; 1124 default-lane tests pass;
21/21 ignored uds_authz integration tests pass under sudo.

@uzyn uzyn merged commit 08e6121 into main May 3, 2026
8 checks passed
@uzyn uzyn deleted the chore/user-mailbox-backlog-cleanup branch May 3, 2026 03:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant