Project routes ignore agent grants: an approved project_tasks scope grants nothing

[jaylfc]

Found while onboarding the taOSmobile agent on 2026-07-21. Jay approved an invite granting eight scopes including project_tasks, the grants are recorded correctly, and the agent still cannot create tasks.

The gap

create_task in tinyagentos/routes/projects.py:587 authorises via _get_owned_project, which is:

if not user.is_admin and user.user_id != p["user_id"]:
    return JSONResponse({"error": "not found"}, status_code=404)

Owner or admin only. The grants table is never consulted. So an agent holding an active project_tasks grant on that exact project gets a masked 404, identical to what a stranger sees.

Verified on the live instance: GET /api/agents/registry/grants?canonical_id=... returns all eight scopes as active, project-scoped to prj-qlvxdq:

a2a_send, a2a_receive, project_tasks, canvas_read,
canvas_write, files_read, files_write, memory_read   (tier=once, project=prj-qlvxdq)

tier='once' is a misleading label but not the problem: the store docstring defines it as "single-decision, no expiry", so these are permanent.

Why it matters

The consent flow, the invite scopes, the approval prompt and the grant feed all work. The enforcement point does not read any of it, so approving project_tasks for an external agent currently grants nothing. That is worse than refusing the scope, because the UI reports success and the agent is left guessing why every call 404s.

It also means the scope set offered at invite time is partly fictional. Worth auditing which other scopes have a real enforcement point and which are similarly decorative.

Fix

Authorise project routes against owner, admin, or an active grant for the required scope on that project. Roughly:

• Add a helper alongside _get_owned_project, e.g. _get_project_for_scope(pstore, grants, project_id, user, scope).
• Keep the masked 404 for genuine strangers so existence is still hidden.
• Apply it to the task routes first (create_task, claim, release, close, comment), since project_tasks is the scope we actually hand out.
• Add a negative test per route: an agent WITHOUT the grant still gets 404, an agent WITH it succeeds. Without both halves the test proves nothing.

Audit needed

Check every scope offered by the invite dialog against a real enforcement point:
project_tasks, canvas_read, canvas_write, files_read, files_write, memory_read, memory_write, decisions_read, decisions_write, registry_feeds_read, tools_execute, a2a_send, a2a_receive.

a2a_send and a2a_receive are known to be enforced (the bus reads the grant feed). The rest need confirming rather than assuming.

Related: #1920 and PR #1921 (agent requests additional scopes, which is the tier above this and pointless until this is fixed), #133 (per-agent permission model), #552 (multi-user isolation).

[jaylfc]

Widening this: the route check is only half the block.

auth_middleware.py:51-61 defines _AGENT_TASK_ROUTES and deliberately omits POST /api/projects/{pid}/tasks, with a comment at line 45 naming it as one of the "sibling routes that must stay session-only". So an agent JWT never reaches create_task at all, independently of the grant check inside it.

Fixing this therefore needs both layers changed: add the create route to the middleware allowlist, and make the handler authorise against grants rather than _get_owned_project.

Correction to my original text, which was too broad: project_tasks is not a decorative scope. _authorize_task_actor is wired into ten task routes (list, get, ready, context, comments, claim, release, close, reopen) and check_agent_scope_for_project in agent_token_auth.py:192-238 performs real grant-gated enforcement. decisions_write also reaches a live enforcement point at decisions.py:150. Creation specifically is the hole, so an external agent can work an existing card but cannot open a new one.

That narrows the audit I asked for: the scopes to verify are the ones with no obvious enforcement site, not the whole list.

[jaylfc]

Stopping before I change this, because the exclusion is deliberate rather than an oversight.

tests/test_routes_projects_agent_tasks.py:295 states it as a tested invariant:

"Invariant 2 + 5: project_tasks must NOT reach create-task, members, or project-lifecycle routes; the token authenticates nothing off the allowlist."

with test_cannot_create_task asserting 401/403/404. The middleware comment names the same exclusion, and the scope is documented as read plus lifecycle plus comments. So an agent claiming, closing and commenting on existing cards while being unable to author new ones is the designed behaviour, not a gap.

I had a patch ready that routed create_task through _authorize_task_actor and added the POST to the allowlist. I have reverted it. Widening project_tasks silently would break a stated invariant and its test, which is not mine to decide.

Two ways forward:

A. Widen project_tasks to include creation. One-line allowlist change plus reusing the existing authoriser. Simple, but it changes what every already-granted project_tasks holder can do, retroactively and without re-consent. Every agent previously approved for "work the board" silently gains "author cards".

B. Add a separate scope, e.g. project_tasks_create. Preserves the invariant, keeps existing grants meaning exactly what they meant when approved, and makes authoring a distinct thing an owner opts into. Costs a new scope in the whitelist, the invite dialog, and the enforcement path.

I recommend B. Retroactively widening a granted permission is the kind of change that is invisible to whoever approved it, and the whole point of the consent flow is that an approval means a specific thing. B also fits the pooled-agent work in #2096, where assignment should hand out narrow capabilities deliberately.

Either way the audit still stands: the scopes offered by the invite dialog should each be checked against a real enforcement point.

Jay's call.