Skip to content

feat(permissions): non-cumulative union mode for --permissions (closes #808) - #811

Merged
taylorwilsdon merged 4 commits into
taylorwilsdon:mainfrom
justadityaraj:feat/non-cumulative-permissions
Oct 20, 2026
Merged

taylorwilsdon merged 4 commits into
taylorwilsdon:mainfrom
justadityaraj:feat/non-cumulative-permissions

Conversation

@justadityaraj

@justadityaraj justadityaraj commented May 24, 2026 •

Copy link
Copy Markdown
Contributor

Description

Fixes #808

Problem

--permissions only supported cumulative levels. Requesting gmail:send therefore also granted labels, modify, and compose scopes, so downstream servers exposing only Gmail read and send tools could not request a matching least-privilege OAuth grant.

Changes

  • Add opt-in + syntax, for example gmail:readonly+send.
  • Resolve union entries from only the additive scopes of the named levels.
  • Keep the existing service:level cumulative behavior unchanged.
  • Support mixed union and cumulative services in one invocation.
  • Preserve per-level denied-action checks for union entries.
  • Document the syntax in --help.

User impact

--permissions gmail:readonly+send now grants exactly gmail.readonly and gmail.send, so OAuth scopes can match a narrow tool allowlist without broad Gmail write access.

Type of Change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update

Verification

  • uv run pytest tests/test_permissions.py tests/test_scopes.py -q — 74 passed.
  • uv run pytest -q — 1,159 passed and 2 skipped; three unrelated Windows-only assertions failed on POSIX mode bits and slash direction.
  • uv run ruff check auth/permissions.py main.py tests/test_permissions.py — passed.
  • uv run ruff format --check auth/permissions.py main.py tests/test_permissions.py — passed.
  • git diff --check upstream/main...HEAD — passed.

Checklist

  • My code follows the style guidelines of this project
  • I have performed a self-review of my own code
  • My changes generate no new warnings
  • I have enabled "Allow edits from maintainers" for this pull request

Additional Notes

Union mode is opt-in. A single cumulative level such as gmail:send behaves exactly as before; callers that want read plus send without intermediate scopes must request gmail:readonly+send.

Summary by CodeRabbit

Release Notes

  • New Features
    • Added union mode for permission specifications using + syntax, such as gmail:readonly+send.
    • Combined permission levels now provide non-cumulative, additive access scopes for more granular authorization control.
    • Added validation for empty or unknown permission levels and services.
    • Permission denial checks now use the highest configured level in a union.
  • Documentation
    • Updated command-line help and examples to explain permission unions.

closes taylorwilsdon#808)

Add `+` separator syntax to --permissions for downstream MCPs that wrap a
narrow tool allowlist and want the OAuth grant to match exactly. Example:

    --permissions gmail:readonly+send

grants {gmail.readonly, gmail.send} only — no labels, modify, or compose
that the cumulative ladder would force in. Existing `service:level` syntax
is unchanged and remains the default.

- parse_permissions_arg now produces frozenset[str] values when `+` is
  present, str otherwise
- new helpers: get_additive_scopes_for_level, get_scopes_for_union
- is_action_denied handles union entries via "most restrictive wins"
- 24 new tests covering parsing, scope assembly, denied-action union
  semantics, and the canonical issue-taylorwilsdon#808 read+send case
@coderabbitai

coderabbitai Bot commented May 24, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 499dd65c-4db4-4c43-99a8-1217d8eb1146
📥 Commits

Reviewing files that changed from the base of the PR and between 371d02d and b870e6a.

📒 Files selected for processing: 3
  • auth/permissions.py
  • main.py
  • tests/test_permissions.py

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 2 remain after this review.

📝 Walkthrough

The PR adds +-joined permission unions. Unions grant only the scopes directly added by the selected levels. Parsing, scope resolution, authorization checks, CLI help, and tests support the new syntax.

Changes: Union-mode permission system

Layer / File(s) Summary
Union parsing and scope resolution
auth/permissions.py
Adds get_scopes_for_union, validates services and union components, returns deduplicated additive scopes, and preserves cumulative behavior for single levels.
Union authorization behavior
auth/permissions.py, tests/test_permissions.py
Uses the highest configured union level for denial checks. Tests cover denying and non-denying unions and unions containing full.
CLI documentation and permission validation tests
main.py, tests/test_permissions.py
Documents gmail:readonly+send. Tests cover parsing, invalid components, exact scopes, and mixed cumulative and union configurations.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant PermissionParser
  participant ScopeResolver
  participant AuthorizationCheck

  CLI->>PermissionParser: Parse gmail:readonly+send
  PermissionParser->>ScopeResolver: Resolve selected levels
  ScopeResolver-->>CLI: Return additive Gmail scopes
  CLI->>AuthorizationCheck: Evaluate action denial
  AuthorizationCheck-->>CLI: Allow or deny action
Loading

Suggested reviewers: taylorwilsdon, mickey-mikey

Merge Risk: ⚪ Minimal · up to b870e

The permission-union behavior has no identified merge-blocking issue; the change is ready for normal merge checks.

Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 71.43% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 21 functions across 3 files. Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Title check Passed The title clearly and concisely describes the main change: adding non-cumulative union mode for --permissions.
Description check Passed The description explains the problem, implementation, user impact, testing, and checklist status. It uses a 'Verification' heading instead of 'Testing' and does not address the code-comment checklist …
Linked Issues check Passed Issue #808 requires a non-cumulative permission mode that can grant only gmail.readonly and gmail.send, while preserving cumulative mode and filtering behavior. parse_permissions_arg accepts `gm…
Out of Scope Changes check Passed The changes are limited to permission parsing and scope resolution, action-denial handling, --help documentation, and automated tests for issue #808. These changes directly support the requested lea…
Full details: Description check

Explanation

The description explains the problem, implementation, user impact, testing, and checklist status. It uses a 'Verification' heading instead of 'Testing' and does not address the code-comment checklist item, but it is otherwise complete and relevant.

Full details: Linked Issues check

Explanation

Issue #808 requires a non-cumulative permission mode that can grant only gmail.readonly and gmail.send, while preserving cumulative mode and filtering behavior. parse_permissions_arg accepts gmail:readonly+send; get_scopes_for_union returns only the additive scopes; and the integration test verifies the exact two-scope set. Existing service:level resolution remains cumulative. Mixed service modes, invalid union entries, denied actions, and help text are covered by the implementation and tests.

Full details: Out of Scope Changes check

Explanation

The changes are limited to permission parsing and scope resolution, action-denial handling, --help documentation, and automated tests for issue #808. These changes directly support the requested least-privilege permission mode. No unrelated product behavior or unrelated files are changed.

  • Fix all pre-merge checks with AI

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.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@auth/permissions.py`:
- Line 273: Replace bare set type annotations with explicit string-set types to
satisfy mypy strict mode: change the variable annotation for combined in the
function/block that declares combined: set = set() to combined: set[str] =
set(), change all_scopes: set = set() to all_scopes: set[str] = set(), and
update the function signature of get_allowed_scopes_set to return
Optional[set[str]] instead of Optional[set]; ensure imports for Optional remain
correct and no other code logic is altered.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8bec6690-30e2-4cda-b9ff-48bf29b20ca9

📥 Commits

Reviewing files that changed from the base of the PR and between 0d1475c and 6b5027d.

📒 Files selected for processing (3)
  • auth/permissions.py
  • main.py
  • tests/test_permissions.py

Comment thread auth/permissions.py Resolved
@justadityaraj

justadityaraj commented Aug 16, 2026 •

Copy link
Copy Markdown
Contributor Author

Hey @taylorwilsdon, happy to rebase, or to rework the approach entirely if non-cumulative union mode isn't the direction you want for --permissions.

@taylorwilsdon taylorwilsdon self-assigned this Oct 20, 2026
@taylorwilsdon taylorwilsdon added the enhancement New feature or request label Oct 20, 2026
@taylorwilsdon

Copy link
Copy Markdown
Owner

Thanks!

@taylorwilsdon
taylorwilsdon merged commit c449ed4 into taylorwilsdon:main Oct 20, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Non-cumulative Gmail permission mode (e.g. --permissions gmail:read,send)

2 participants