Skip to content

feat: add secure Gmail mailbox cleanup - #5

Merged
404Dealer merged 3 commits into
masterfrom
feat/secure-imap-cleanup
Jul 10, 2026
Merged

404Dealer merged 3 commits into
masterfrom
feat/secure-imap-cleanup

Conversation

@404Dealer

@404Dealer 404Dealer commented Jul 10, 2026 •

Copy link
Copy Markdown
Owner

Summary

Adds a fixed-scope, human-gated Gmail IMAP cleanup helper stacked on the secure SMTP/App Password feature.

The helper:

  • runs only through a root-owned interactive wrapper;
  • drops privileges to isolated agentgate with a clean environment;
  • reads the existing App Password only through the installer-pinned absolute pass executable;
  • connects only to imap.gmail.com:993 with verified TLS and bounded resources/timeouts;
  • discovers only server-declared \\Junk and \\Trash special-use mailboxes;
  • snapshots unread UIDs and UIDVALIDITY before confirmation;
  • requires exact MARK READ confirmation;
  • adds only \\Seen to the approved UID snapshot;
  • never deletes, moves, archives, empties, fetches/displays message content, prints credentials, or grants Hermes mailbox access;
  • reports post-confirmation folder failure as a redacted partial outcome so rerunning is safe;
  • appends counts-only no-symlink JSONL audit events without turning post-action audit failure into a false mailbox failure.

Stacked PR

Base: feat/smtp-app-password-provider / PR #4.

This keeps the production-verified SMTP PR frozen. Retarget this PR to master after PR #4 merges. GitHub Actions intentionally does not attach while the base is a feature branch; the same CI matrix was executed locally below.

Verification at bfe9a5d

  • full suite: 104/104 passing
  • Node 20.20.2: 104/104 + TypeScript build
  • Node 22.23.1: 104/104 + TypeScript build
  • current runtime Node 24: 104/104 + TypeScript build
  • installed npm tarball binary smoke: passing
  • tarball contents: cleanup CLI/modules/operator doc present
  • npm audit --omit=dev: 0 vulnerabilities
  • production dependency licenses: MIT/ISC/BSD-compatible set
  • Bash syntax checks: clean
  • git diff --check: clean
  • static unsafe-operation scan: no delete/move/expunge/fetch APIs
  • static credential scan: no live mailbox address, key name, commit marker, or credential (test fixtures only)

Remaining before ready

  • independent latest-head security/correctness/deployment review
  • production installer upgrade
  • human-approved live Gmail cleanup and audit verification

Summary by CodeRabbit

  • New Features

    • Added a human-gated Gmail cleanup tool that previews unread Spam and Trash messages and marks them as read only after the exact MARK READ confirmation.
    • Reports no-op, cancelled, completed, and partial outcomes with audit logging that excludes message contents and credentials.
    • Added the agent-gate-mailbox-cleanup command and production installation support.
  • Documentation

    • Added operator guidance, prerequisites, safety boundaries, troubleshooting, and deployment instructions for the cleanup workflow.

@cursor

cursor Bot commented Jul 10, 2026

Copy link
Copy Markdown

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

@coderabbitai

coderabbitai Bot commented Jul 10, 2026 •

Copy link
Copy Markdown
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title is concise and accurately summarizes the main change: a secure Gmail mailbox cleanup helper.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/secure-imap-cleanup

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@404Dealer
404Dealer marked this pull request as ready for review July 10, 2026 05:44
Copilot AI review requested due to automatic review settings July 10, 2026 05:44

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@404Dealer
404Dealer changed the base branch from feat/smtp-app-password-provider to master July 10, 2026 15:54
@404Dealer
404Dealer merged commit ab263a6 into master Jul 10, 2026
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.

2 participants