OAuth Scope Minimizer

What this skill does

Inspects an application's OAuth client config and grep-traces the actual API calls it issues, then proposes the minimum set of scopes that still allows the observed calls. Output includes a delta and a user-consent re-prompt plan.

Inputs

• repo_dir: source root of the app.
• current_scopes: array of currently-requested scopes (e.g., ["user:read", "repo:write", "admin:org"]).
• provider: google, github, slack, microsoft, etc. — drives the scope-to-API mapping.
• Optional usage_logs: API access logs, used to verify the static-scan results.

Steps

1. Build a provider-specific mapping from API endpoints to required scopes (load from a curated JSON shipped with the skill).
2. Scan the codebase for API calls: rg -nN 'fetch\(|axios\.|got\(|apiClient\.' <repo_dir>. Extract the URL paths.
3. Match each URL against the provider's API surface. For each match, record the scope(s) that endpoint requires.
4. Aggregate scopes used; compare with current_scopes. The difference is over-grant.
5. If usage_logs are provided, intersect with logged endpoints to remove false-positives (code paths defined but never exercised).
6. Detect "dangerous" scopes still in the set: write/admin-level scopes (admin:org, repo:delete, mail.send) deserve extra scrutiny — confirm the app actually sends destructive calls.
7. For each scope to drop, list the call sites that gave it support (so reviewers can confirm those features are deprecated).
8. Compose a rollout plan: bump the OAuth client to a new version with the minimized scopes; notify users to re-consent; sunset the old token grant.
9. Emit a markdown report.

Output

oauth-scope-min.md with: current vs proposed scopes, per-removed-scope justification, dangerous-scope discussion, re-consent rollout steps. Stdout prints scope-count delta.

Verification

Implement the new scope set in a staging environment, complete the OAuth flow with a test account, and exercise every feature; any feature failure indicates the scope-to-endpoint map missed a call. After production rollout, monitor 401/403 rates and the OAuth provider's audit log for "scope denied" events. If a scope was removed but a hidden code path still calls the API, the failure rate exposes it.

Edge cases

• Provider-specific aliasing (e.g., user vs user:email on GitHub): respect both forms in the mapping.
• Apps that call the same API for both read and write: ensure both scope tiers are kept.
• Scopes for webhooks vs. user-facing actions: separate them; webhook scopes often require organization admin.
• Provider added a finer-grained scope after app launch: take advantage and split a coarse scope (repo) into the finer ones (repo:status, repo:contents).