PR Custody

PRPR Custody

fix(clockify): normalize no-scope action gates

@surajmarkupchecks n/achecks…fix/clockify-scope-qa-mismatches → master8 files · +8 −8updated 1mo ago

GitHub

▸Description

Summary

audited the VERIFIED Clockify workbook rows against real Clockify action code and the official Clockify OpenAPI spec embedded in https://docs.developer.clockify.me/
normalized the two Clockify actions that shipped legacy [] scope lists to empty CNF ({"all_of": []})
removed six non-canonical Clockify scope gates (TIME_ENTRY_READ, TASK_READ, USER_WRITE, and the invented sentinel No OAuth scopes) from actions whose official docs publish auth schemes only (ApiKeyAuth / AddonKeyAuth) with no operation scope strings

Official source of truth used for this pass:

action code under apps/clockify/actions/*
Clockify API docs auth section: X-Api-Key / X-Addon-Token
per-operation OpenAPI security blocks in the same docs page

Per-action coverage matrix

Action	File	Actual HTTP call in code	Old `_scopes`	New `_scopes`	Official doc evidence
`CLOCKIFY_GENERATE_DETAILED_REPORT`	`apps/clockify/actions/generate_detailed_report.py`	`POST https://reports.api.clockify.me/v1/workspaces/{workspaceId}/reports/detailed`	`[]`	`{"all_of": []}`	`Generate a detailed report` lists `security: [{"ApiKeyAuth": []}, {"AddonKeyAuth": []}]` — no operation scopes.
`CLOCKIFY_GENERATE_WEEKLY_REPORT`	`apps/clockify/actions/generate_weekly_report.py`	`POST https://reports.api.clockify.me/v1/workspaces/{workspaceId}/reports/weekly`	`[]`	`{"all_of": []}`	`Generate a weekly report` lists `security: [{"ApiKeyAuth": []}, {"AddonKeyAuth": []}]` — no operation scopes.
`CLOCKIFY_GET_IN_PROGRESS_TIME_ENTRIES`	`apps/clockify/actions/get_in_progress_time_entries.py`	`GET {base_url}/workspaces/{workspaceId}/time-entries/status/in-progress`	`{"all_of": [{"any_of": ["TIME_ENTRY_READ"]}]}`	`{"all_of": []}`	`Get all in progress time entries on a workspace` lists only `ApiKeyAuth` / `AddonKeyAuth`. `TIME_ENTRY_READ` is not a documented Clockify API scope for this endpoint.
`CLOCKIFY_GET_PROJECT`	`apps/clockify/actions/get_project.py`	`GET {base_url}/workspaces/{workspaceId}/projects/{projectId}`	`{"all_of": [{"any_of": ["No OAuth scopes"]}]}`	`{"all_of": []}`	`Find a project by ID` lists only `ApiKeyAuth` / `AddonKeyAuth`. `No OAuth scopes` was an invented sentinel, not a real scope.
`CLOCKIFY_GET_TASKS`	`apps/clockify/actions/get_tasks.py`	`GET {base_url}/workspaces/{workspaceId}/projects/{projectId}/tasks`	`{"all_of": [{"any_of": ["TASK_READ"]}]}`	`{"all_of": []}`	`Find tasks on a project` lists only `ApiKeyAuth` / `AddonKeyAuth`. `TASK_READ` is not published in the official endpoint spec.
`CLOCKIFY_GET_TEMPLATE_BY_ID_ON_WORKSPACE`	`apps/clockify/actions/get_template_by_id_on_workspace.py`	`GET {base_url}/workspaces/{workspaceId}/templates/{templateId}`	`{"all_of": [{"any_of": ["No OAuth scopes"]}]}`	`{"all_of": []}`	`Get template by ID on a workspace` lists only `ApiKeyAuth` / `AddonKeyAuth`.
`CLOCKIFY_UPDATE_TASK`	`apps/clockify/actions/update_task.py`	`PUT {base_url}/workspaces/{workspaceId}/projects/{projectId}/tasks/{taskId}`	`{"all_of": [{"any_of": ["No OAuth scopes"]}]}`	`{"all_of": []}`	`Update a task on a project` lists only `ApiKeyAuth` / `AddonKeyAuth`.
`CLOCKIFY_UPDATE_USER_HOURLY_RATE`	`apps/clockify/actions/update_user_hourly_rate.py`	`PUT {base_url}/workspaces/{workspaceId}/users/{userId}/hourly-rate`	`{"all_of": [{"any_of": ["USER_WRITE"]}]}`	`{"all_of": []}`	`Update a user's hourly rate` lists only `ApiKeyAuth` / `AddonKeyAuth`. `USER_WRITE` is not published in the official endpoint spec.

Reviewed but not changed

67 workbook rows were marked ⚠ MISSING SCOPE, but I left them alone because the real action code already had no explicit _scopes gate, and the official Clockify OpenAPI spec likewise exposes only auth schemes with empty arrays for those operations.
In other words: for the remaining Clockify actions, “missing _scopes” is not a product bug — it matches the vendor spec's no-operation-scope model.
Representative unchanged actions reviewed during this pass: create_client, create_new_project, create_task, create_time_entry, get_time_entry, update_project, delete_time_entry, get_workspace_info, create_webhook, stop_user_timer.

Validation

uv run --with ruff ruff format apps/clockify/actions/{generate_detailed_report.py,generate_weekly_report.py,get_in_progress_time_entries.py,get_project.py,get_tasks.py,get_template_by_id_on_workspace.py,update_task.py,update_user_hourly_rate.py}
uv run --with ruff ruff check apps/clockify/actions/{generate_detailed_report.py,generate_weekly_report.py,get_in_progress_time_entries.py,get_project.py,get_tasks.py,get_template_by_id_on_workspace.py,update_task.py,update_user_hourly_rate.py}
uv run python AST + ActionBuilder.validate_scopes verification for all 8 edited actions

QA note

The VERIFIED Clockify workbook mixes two incompatible models:

the official Clockify OpenAPI docs, which publish auth schemes (ApiKeyAuth / AddonKeyAuth) but no per-operation scope strings
secondary addon-manifest references that mention labels like TIME_ENTRY_READ, TASK_READ, and USER_WRITE

Per the audit rules, I treated the action code + canonical Clockify docs as authoritative and did not add scope gates to the other 67 rows just because the workbook's helper heuristics wanted addon-manifest-style names.

Bugbot pass

gh pr checks 23460 shows Cursor Bugbot = pass
fetched gh api repos/ComposioHQ/mercury/pulls/23460/comments
fetched gh api repos/ComposioHQ/mercury/pulls/23460/reviews
both API responses were [] at check time, so there were no bugbot/review comments to address

loading diff…