Harden inbox apply safety

Author: silvermanjared-web

README.md

@@ -36,7 +36,8 @@ These are the active scripts this repo exposes today.
 
 | Script | Command | What it does | Safety posture |
 |---|---|---|---|
-| Gmail Inbox Accelerator | `python -m src.inbox.accelerator --dry` | Loads configurable Gmail rules, searches matching messages, and previews label/archive actions | Use `--dry` before any write run |
+| Gmail Inbox Accelerator preview | `python -m src.inbox.accelerator` | Loads configurable Gmail rules, searches matching messages, and previews label/archive actions | Dry run by default; no Gmail or local state changes are saved |
+| Gmail Inbox Accelerator apply | `python -m src.inbox.accelerator --apply` | Applies reviewed rules to Gmail labels, archive state, and read state if configured | Write-capable; run only after preview review |
 | Inbox status check | `python -m src.inbox.accelerator --status` | Prints current state, rule index, labeled count, archived count, errors, runs, and last run | Read-only |
 | Inbox state reset | `python -m src.inbox.accelerator --reset` | Removes local processing state so the next run starts from rule 0 | Local state only |
 | Google Ads Campaign Health Audit | `python -m src.audit.campaign_health --days 30` | Pulls Google Ads campaign data and checks budget pacing, conversion health, impression share, naming, auto-tagging, and status anomalies | Read-only API workflow |
@@ -52,7 +53,7 @@ Rule-based email processing using the Gmail API. Categorizes, labels, archives,
 - **Rule engine** — configurable pattern matching by sender, subject, and keywords
 - **Batch processing** — labels and archives messages efficiently through API calls
 - **State persistence** — tracks progress across runs and resumes where it left off
-- **Dry-run mode** — previews changes before applying them
+- **Dry-run mode** — previews changes without modifying Gmail or local state
 
 ### Platform audit (`src/audit/`)
 
@@ -84,12 +85,12 @@ Structured reporting examples show how script output can be translated into oper
 Start in dry-run or read-only mode before applying changes.
 
 ```bash
-python -m src.inbox.accelerator --dry
+python -m src.inbox.accelerator
 python -m src.inbox.accelerator --status
 python -m src.audit.campaign_health --days 30
 ```
 
-Use write-capable inbox workflows only after reviewing the dry-run output and confirming the rule configuration.
+Use `python -m src.inbox.accelerator --apply` only after reviewing the dry-run output and confirming the rule configuration. Avoid broad catch-all inbox rules, and treat `mark_read` as an explicit opt-in for narrow, low-risk message classes.
 
 ## Example output
 

config/README.md

@@ -6,11 +6,13 @@
 2. Create a project (or select existing)
 3. Enable the **Gmail API**
 4. Create OAuth 2.0 credentials (Desktop application)
-5. Download the credentials JSON and save as `credentials.json` in the project root
-6. On first run, a browser window will open for authorization — the resulting token is saved as `token.json`
+5. Download the credentials JSON and save it as an ignored local file named `credentials.json`
+6. On first authorization, the resulting token is saved as an ignored local file named `token.json`
 
 Reference: [Gmail API Python Quickstart](https://developers.google.com/gmail/api/quickstart/python)
 
+Do not commit OAuth credentials or tokens. The repository `.gitignore` excludes the default local filenames, but you should still treat them as private machine-local files.
+
 ### Gmail Rules
 
 ```bash
@@ -23,7 +25,9 @@ Edit `gmail_rules.json` to add your own sender patterns, subject filters, and la
 - `query` — Gmail search query (same syntax as the Gmail search bar)
 - `label` — target label (created automatically if it doesn't exist)
 - `archive` — whether to remove from inbox
-- `mark_read` — whether to mark as read
+- `mark_read` — whether to mark as read; keep this `false` unless the rule is narrow and intentionally low-risk
+
+Run the inbox accelerator without flags first. It defaults to a dry run and does not modify Gmail or local processing state. Use `--apply` only after reviewing the matched rules.
 
 ## Google Ads API Setup
 
@@ -45,6 +49,8 @@ Fill in your credentials:
 
 Reference: [Google Ads API Authentication](https://developers.google.com/google-ads/api/docs/oauth/overview)
 
+Do not commit `config/google-ads.yaml` or any copied output from live accounts. Public examples should use synthetic account names, IDs, and performance data only.
+
 ### Accounts Config
 
 ```bash

config/gmail_rules.example.json

@@ -18,27 +18,20 @@
     "query": "subject:(\"has shipped\" OR \"out for delivery\" OR \"package delivered\" OR \"tracking number\") in:inbox",
     "label": "INBOX/RECEIPTS",
     "archive": true,
-    "mark_read": true
+    "mark_read": false
   },
   {
     "name": "Notifications - calendar and system",
     "query": "from:(calendar-notification@google.com OR noreply@alerts.example.com OR notifications@system.example.com) in:inbox",
     "label": "INBOX/NOTIFICATIONS",
     "archive": true,
-    "mark_read": true
+    "mark_read": false
   },
   {
     "name": "Promotions - known marketing senders",
     "query": "from:(deals@retailer.example.com OR offers@brand.example.com OR promo@store.example.com) in:inbox",
     "label": "INBOX/PROMOTIONS",
     "archive": true,
-    "mark_read": true
-  },
-  {
-    "name": "Promotions - alias catch-all",
-    "query": "to:alias@example.com in:inbox",
-    "label": "INBOX/PROMOTIONS",
-    "archive": true,
-    "mark_read": true
+    "mark_read": false
   }
 ]

examples/example-run.md

@@ -8,39 +8,41 @@ The purpose of this file is to make the repo easier to inspect. It shows what an
 
 | Workflow | Command | Writes to external system? |
 |---|---|---|
-| Inbox dry run | `python -m src.inbox.accelerator --dry` | No |
+| Inbox dry run | `python -m src.inbox.accelerator` | No |
 | Inbox status | `python -m src.inbox.accelerator --status` | No |
 | Inbox reset | `python -m src.inbox.accelerator --reset` | No external write; resets local state |
-| Inbox apply | `python -m src.inbox.accelerator` | Yes, after OAuth and rule review |
+| Inbox apply | `python -m src.inbox.accelerator --apply` | Yes, after OAuth and rule review |
 | Campaign health audit | `python -m src.audit.campaign_health --days 30` | No; reads Google Ads data |
 
 ## Inbox automation dry run
 
 ### Command
 
 ```bash
-python -m src.inbox.accelerator --dry
+python -m src.inbox.accelerator
 ```
 
 ### Sample console output
 
 ```text
-Loaded 8 rules
-Run #3 | phase=processing | rule=2/7 | labeled=284 | archived=196
-[DRY RUN] Rule 2 (Platform alerts): would process 91 messages
-[DRY RUN] Rule 3 (Vendor reporting): would process 142 messages
-[DRY RUN] Rule 4 (Low-priority newsletters): would process 178 messages
-Rule 5 (Recruiter and priority contacts): no matches, advancing.
-Run #3 complete | 14s | labeled=284 | archived=196 | errors=0 | next_rule=6
+Loaded 5 rules
+Dry-run mode. Add --apply only after reviewing the rule output.
+Preview #3 | phase=processing | rule=0/4 | labeled=284 | archived=196
+[DRY RUN] Rule 0 (Intel - industry newsletters): would label 91 messages, archive
+[DRY RUN] Rule 1 (Receipts - transactional emails): would label 142 messages, archive
+[DRY RUN] Rule 2 (Receipts - shipping notifications): would label 178 messages, archive
+Rule 3 (Notifications - calendar and system): no matches, advancing.
+Preview #3 complete | 14s | labeled=284 | archived=196 | errors=0 | next_rule=5
+Dry run only. No Gmail changes or local state changes were saved.
 ```
 
 ### Operator readout
 
 | Review area | Signal | Suggested action |
 |---|---|---|
 | Rule volume | Three rules would touch 411 messages | Confirm rules are scoped correctly before write run |
-| Priority safety | Priority-contact rule had no matches | Confirm this is expected before archiving lower-priority mail |
-| State behavior | Next run resumes from rule 6 | Use `--status` before applying changes |
+| Notification safety | Notification rule had no matches | Confirm this is expected before applying lower-priority mail handling |
+| State behavior | Preview does not save local state | Use `--apply` only after reviewing the preview |
 
 ## Inbox status check
 
@@ -127,5 +129,5 @@ The toolkit is designed to make recurring marketing operations work easier to in
 
 - This example uses mock data.
 - Do not commit live exports, private campaign data, account IDs, credentials, or tokens.
-- Dry-run mode should be used before applying inbox changes.
+- Dry-run mode is the default and should be used before applying inbox changes.
 - Google Ads audit output should be treated as a diagnostic prompt for human review, not as an automated budget decision.

scripts/validate_repo.py

@@ -20,7 +20,7 @@
     re.compile(r"BEGIN (RSA|OPENSSH|PRIVATE) KEY"),
 ]
 SENSITIVE_NAME = re.compile(
-    r"(^|/)(\.env(\..*)?|\.env\.keys|client_secret.*\.json|credentials.*\.json|token.*\.json|tokens.*\.json|google[-_]ads\.ya?ml)$",
+    r"(^|/)(\.env(\..*)?|\.env\.keys|client_secret.*\.json|credentials.*\.json|token.*\.json|tokens.*\.json|google[-_]ads\.ya?ml|state\.json)$",
     re.IGNORECASE,
 )
 ALLOW_TRACKED = {
@@ -29,6 +29,16 @@
 }
 SKIP_DIRS = {".git", "node_modules", "venv", ".venv", "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache"}
 TEXT_SUFFIXES = {".py", ".md", ".txt", ".json", ".yaml", ".yml", ".toml", ".sh", ".css", ".js", ".ts", ".html"}
+UNSAFE_SAMPLE_PATTERNS = {
+    "config/gmail_rules.example.json": [
+        (re.compile(r'"mark_read"\s*:\s*true', re.IGNORECASE), "Sample Gmail rules should not mark messages read by default"),
+        (re.compile(r'"query"\s*:\s*"to:[^"]+@[^"]+in:inbox"', re.IGNORECASE), "Sample Gmail rules should not use broad alias catch-all queries"),
+    ],
+    "src/inbox/rules.py": [
+        (re.compile(r"mark_read\s*=\s*True"), "Built-in Gmail rules should not mark messages read by default"),
+        (re.compile(r"query\s*=\s*[\"']to:[^\"']+@[^\"']+in:inbox[\"']", re.IGNORECASE), "Built-in Gmail rules should not use broad alias catch-all queries"),
+    ],
+}
 
 def git(args: list[str]) -> subprocess.CompletedProcess[str]:
     return subprocess.run(["git", *args], cwd=ROOT, text=True, capture_output=True, check=False)
@@ -74,6 +84,11 @@ def main() -> int:
                 failures.append(f"Secret-like pattern in {rel}: {pattern.pattern}")
                 break
 
+        for pattern, message in UNSAFE_SAMPLE_PATTERNS.get(rel, []):
+            if pattern.search(text):
+                failures.append(f"{message}: {rel}")
+                break
+
     status = git(["status", "--short"]).stdout.strip()
     if status:
         failures.append("Working tree is not clean")

src/inbox/accelerator.py

@@ -6,8 +6,9 @@
 batchModify. Maintains state across runs so it can resume where it left off.
 
 Usage:
-    python -m src.inbox.accelerator              # Process inbox
-    python -m src.inbox.accelerator --dry        # Preview changes (no writes)
+    python -m src.inbox.accelerator              # Preview changes (no writes)
+    python -m src.inbox.accelerator --apply      # Apply approved rules
+    python -m src.inbox.accelerator --dry        # Explicit preview mode
     python -m src.inbox.accelerator --status     # Print current state
     python -m src.inbox.accelerator --reset      # Reset state to start over
     python -m src.inbox.accelerator --config config/gmail_rules.json
@@ -176,27 +177,35 @@ def run_accelerator(rules: list[Rule], dry_run: bool = False) -> None:
         - For each rule, searches for matching messages and applies actions
         - If a rule matches messages, re-runs it until exhausted (handles
           inboxes with >1,000 matching messages per rule)
-        - Saves state after each batch so processing resumes on next run
+        - Saves state after each applied batch so processing resumes on next run
         - Stops after MAX_RUNTIME_SEC to stay within scheduler limits
+
+    Dry-run mode is intentionally non-mutating: it does not apply Gmail
+    changes and does not advance or save local processing state.
     """
     service = get_gmail_service()
     state = load_state()
+    if dry_run:
+        state = dict(state)
     start_time = time.time()
 
-    state["runs"] += 1
-    run_num = state["runs"]
+    run_num = state["runs"] + 1
 
     print(
-        f"Run #{run_num} | phase={state['phase']} | "
+        f"{'Preview' if dry_run else 'Run'} #{run_num} | phase={state['phase']} | "
         f"rule={state['rule_index']}/{len(rules) - 1} | "
         f"labeled={state['labeled']} | archived={state['archived']}"
     )
 
     if state["phase"] == "done":
         print("All rules processed. Nothing to do. Use --reset to start over.")
-        save_state(state)
+        if not dry_run:
+            save_state(state)
         return
 
+    if not dry_run:
+        state["runs"] = run_num
+
     label_id_cache: dict[str, str] = {}
     consecutive_errors = 0
 
@@ -228,18 +237,20 @@ def run_accelerator(rules: list[Rule], dry_run: bool = False) -> None:
             print(f"Rule {idx} ({rule.name}): no matches, advancing.")
             state["rule_index"] += 1
             consecutive_errors = 0
-            save_state(state)
+            if not dry_run:
+                save_state(state)
             continue
 
         # Dry run — report what would happen
         if dry_run:
             print(
                 f"[DRY RUN] Rule {idx} ({rule.name}): "
-                f"would process {len(message_ids)} messages"
+                f"would label {len(message_ids)} messages"
+                f"{', archive' if rule.archive else ''}"
+                f"{', mark read' if rule.mark_read else ''}"
             )
             state["rule_index"] += 1
             consecutive_errors = 0
-            save_state(state)
             continue
 
         # Apply the rule
@@ -270,18 +281,22 @@ def run_accelerator(rules: list[Rule], dry_run: bool = False) -> None:
                 break
             time.sleep(2)
 
-        save_state(state)
+        if not dry_run:
+            save_state(state)
 
     # Finalize
-    state["last_run"] = datetime.now(timezone.utc).isoformat()
-    save_state(state)
+    if not dry_run:
+        state["last_run"] = datetime.now(timezone.utc).isoformat()
+        save_state(state)
 
     elapsed = round(time.time() - start_time)
     print(
-        f"Run #{run_num} complete | {elapsed}s | "
+        f"{'Preview' if dry_run else 'Run'} #{run_num} complete | {elapsed}s | "
         f"labeled={state['labeled']} | archived={state['archived']} | "
         f"errors={state['errors']} | next_rule={state['rule_index']}"
     )
+    if dry_run:
+        print("Dry run only. No Gmail changes or local state changes were saved.")
 
 
 # ── CLI ──────────────────────────────────────────────────────────────────────
@@ -312,7 +327,11 @@ def main() -> None:
     )
     parser.add_argument(
         "--dry", action="store_true",
-        help="Dry run — preview what would change without modifying anything",
+        help="Explicit dry run — preview without Gmail or local state changes",
+    )
+    parser.add_argument(
+        "--apply", action="store_true",
+        help="Apply approved rules to Gmail. Without this flag, the command is a dry run.",
     )
     parser.add_argument(
         "--status", action="store_true",
@@ -328,6 +347,9 @@ def main() -> None:
     )
     args = parser.parse_args()
 
+    if args.dry and args.apply:
+        parser.error("Use either --dry or --apply, not both.")
+
     if args.status:
         print_status()
         sys.exit(0)
@@ -338,7 +360,9 @@ def main() -> None:
 
     rules = get_rules(args.config)
     print(f"Loaded {len(rules)} rules")
-    run_accelerator(rules, dry_run=args.dry)
+    if not args.apply:
+        print("Dry-run mode. Add --apply only after reviewing the rule output.")
+    run_accelerator(rules, dry_run=not args.apply)
 
 
 if __name__ == "__main__":

src/inbox/rules.py

@@ -122,7 +122,7 @@ def _validate_rule_entry(entry: dict, index: int) -> None:
         ),
         label="INBOX/RECEIPTS",
         archive=True,
-        mark_read=True,
+        mark_read=False,
     ),
     Rule(
         name="Notifications - calendar and system",
@@ -133,7 +133,7 @@ def _validate_rule_entry(entry: dict, index: int) -> None:
         ),
         label="INBOX/NOTIFICATIONS",
         archive=True,
-        mark_read=True,
+        mark_read=False,
     ),
     Rule(
         name="Promotions - known marketing senders",
@@ -144,14 +144,7 @@ def _validate_rule_entry(entry: dict, index: int) -> None:
         ),
         label="INBOX/PROMOTIONS",
         archive=True,
-        mark_read=True,
-    ),
-    Rule(
-        name="Promotions - alias catch-all",
-        query="to:alias@example.com in:inbox",
-        label="INBOX/PROMOTIONS",
-        archive=True,
-        mark_read=True,
+        mark_read=False,
     ),
 ]