Skip to content

fix(auth): human-only MCP tools follow their routes, refusals are audited, the saved-token fork takes a session, and no grant rests on an agent-only check - #4243

Merged
vybe merged 16 commits into
devfrom
AndriiPasternak31/ent719-pr5
Nov 11, 2026
Merged

vybe merged 16 commits into
devfrom
AndriiPasternak31/ent719-pr5

Conversation

@AndriiPasternak31

@AndriiPasternak31 AndriiPasternak31 commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Fixes abilityai/trinity-enterprise#719

The keyword points at another tracker, so merging does not close the issue or move its status. The issue is closed by hand at the release cut, once this PR is on main.

This is the last of five PRs for the issue. The other four are on dev: #4040, #4041, #4042 and #4043.

What changes

1. MCP: a human-only tool is listed only to the key scopes its route admits

Thirteen MCP tools proxy routes that admit only a person (require_person) or only a signed-in session (require_interactive). Each is now listed only to the key scopes its route admits, through one shared predicate, access.ts::humanOnlyToolAccess(rule).

Route rule Listed to Tools
PERSON: a session or the person's own user key user keys rename_agent, initialize_github_sync, set_agent_github_pat, inject_credentials, export_credentials, clear_agent_subscription, toggle_nevermined, revoke_agent_delegation, respond_to_operator_queue, close_room
INTERACTIVE: a signed-in session only no key import_credentials, assign_subscription, configure_nevermined
  • Listing follows the key's scope, never the caller's role. Inside a listed scope the route still decides: a user key that is not the owner's or an admin's is shown the tool and refused by the backend.
  • A key that names a tool it is not shown gets FastMCP's "not found" before any backend request.
  • Each tool's description says which keys are not shown it.
  • get_credential_encryption_key stays listed to user and system keys; its route is admin-only.
  • In keyless dev mode (MCP_REQUIRE_API_KEY=false) every tool is still listed and the backend decides.

2. MCP: human-only refusals read as human_only

  • Credential tools (export_credentials, import_credentials, get_credential_encryption_key): a 403 with detail.code == "person_required", or the exact session-only sentence, maps to human_only: true. Before, these mapped to not_authorized. Other 403s keep their own flag (admin_only / not_authorized), and other statuses are unchanged.
  • A2A tools: fail() / failOutbound() read detail.code instead of matching the words "human-only". No public A2A route sends that code today, so this is hardening.

3. A refused person-only or session-only attempt is recorded in the audit log

This is #719's decision 4 and the one new capability in the PR.

  • The five human-only primitives in dependencies.py raise HumanOnlyRefused, an HTTPException subclass.
  • error_handlers.human_only_refused, registered in main.py, writes one authorization / human_only_refused row. It then answers through the app's own HTTPException handler, so status, body and headers are byte-identical to before.
  • The row is filed against the agent, the system agent, or the key's scope. It carries the path, method, route template, rule, code, the request id and actor_ip. It never carries the body, the query string or other headers, and caller-sized values are cut to 256 characters.
  • At most one row per principal, method and route every 60 seconds, per worker. An audit failure is logged and the caller still gets the same 403.
  • Not recorded: refusals that raise a plain 403 (the Workspace doors, reject_agent_principal / Depends(human_only), the tag guards, the creation arm's 400). These are tracked in abilityai/trinity-enterprise#985.

To revert this part alone:

  • source: the HumanOnlyRefused raise sites in dependencies.py, error_handlers.human_only_refused, its registration in main.py, and the audited mark in services/agent_service/files.py;
  • tests: test_ent719_human_only_refusal_audit.py, _human_only_audit_app.py, and the new cases in test_human_only_principals.py.

Nothing else in the PR imports it.

4. Agent creation: the saved-token fork takes a signed-in session

POST /api/agents with a fork_to_own block and no token in the body forks with the creator's saved token. That token then becomes the agent's own, which is a credential bind, so it now takes a signed-in session (requirements/auth.md §2.8).

  • Every key, a person's own user key included, gets the named 400 FORK_PAT_REQUIRED, as an agent key already did. A token passed in the body still works.
  • Signed-in sessions, creates without a fork, and agent-spawned creation are unchanged.
  • Consequence for MCP: create_agent never carries a token, so a fork through it is now refused for every key. The tool still offers the fork option. See "Open question" below.

5. Closure check: no grant route rests on an agent-only check alone

tests/unit/_grant_guard_scan.py (stdlib, reads source, never imports src/) walks every census route into the code it runs. It fails when:

  • A: a route reaches an agent-only check (reject_agent_principal, an agent_name test, an agent-scope test) without a person/session rule or the admin gate beside it;
  • B: a Workspace write neither refuses a non-person first nor is a listed per-viewer use;
  • C: the room moderator check has an exit that admits without a person.

Reviewed exceptions live in its tables, each with a reason. Every entry fails when it goes stale. test_ent719_no_agent_only_grant_guard.py runs it as the acceptance test, plus the self-tests for the scan's rules.

What it does not prove:

  • that every grant route is human-only, since a route with no machine refusal at all is invisible to it, and the census baseline holds those;
  • anything behind a call through an object attribute or method;
  • that a credited check runs before the effect it guards.

6. The autonomy dial's two owner writes take a person

The two Workspace owner writes added by abilityai/trinity-enterprise#641 could be made by the system key. They now refuse a non-person first. The scan found them.

Who is affected

Caller Change
Agent keys Ten tools are no longer listed: the eight agent-settings tools, respond_to_operator_queue and close_room. Their routes already refused agent keys
The system key The thirteen tools are no longer listed. The trinity-system template and system_agent_service.py docstring now name what it does not list
A person's user key The three INTERACTIVE tools are no longer listed, and a create with fork_to_own and no token gets FORK_PAT_REQUIRED
Signed-in sessions (the web UI) No change
Admins reading the audit log They now see refused human-only attempts by key

No in-repo agent template, agent runtime or scheduler path calls any of the thirteen tools.

Evidence

Validation. All of the following is on head e37a599b0, which contains dev at aa12f15ef:

  • CI: 22 checks passed, 6 skipped, 0 failed. They include the full unit suite with its regression diff against dev, journey-smoke (the real stack booted through start.sh), MCP typecheck + unit, CodeQL and the enterprise-docs guard.
  • Grant-guard scan (python tests/unit/_grant_guard_scan.py):
    • 715 routes walked, 56 agent-only sites;
    • 0 grant routes guarded by an agent-only check alone;
    • 1 deferred (portal_delete_document, see below);
    • 0 table problems.
  • Census: FROZEN_BASELINE_COUNT = 232, equal to the baseline's length. This PR moves no baseline entry.
  • The PR's backend test files plus test_2996_human_only_routes.py: 256 passed in fixed order.

Mutation. On this head:

  • restoring the creation arm's old check: 7 red;
  • dropping the autonomy writes' person check: 2 red;
  • removing the audit handler's registration: 33 red, while the byte-identity tests stay green.

The MCP listing, refusal-mapping and scan-rule mutations were run on an earlier base and not repeated here.

Docs

The lines this change made false are corrected:

  • architecture/{mcp-server,security,backend,agent-lifecycle}.md
  • requirements/auth.md §2.8 (the INTERACTIVE table gains the fork arm; the "Audit" bullet)
  • requirements/{public-access,security,github,core-agent}.md
  • the affected feature flows, including a new "Refused person-only and session-only attempts" section in audit-trail.md
  • the matching user docs
  • feature-flows.md gets the one index row for all five of fix(slack): startup recovery supervisor for transient initial-connect failures (#708) #719's PRs.

Open question

The fork through MCP create_agent. Part 4 makes it refused for every key, which turns off the fork option #4126 added to the tool. Either:

  • a person's own user key is re-admitted on that arm, or
  • the option is removed from the tool's schema and description.

This waits on a product ruling.

Not in this PR

Tracked in abilityai/trinity-enterprise#985:

  • the rest of the human-only baseline (232 entries, mostly reads);
  • the deferred Workspace document revoke for every viewer;
  • storing a token at agent creation;
  • a room's budget at creation;
  • set_skill_gate / clear_skill_gate listing;
  • a machine code for the session-only refusal;
  • recording the refusals listed under part 3.

Also tracked there are #719's decisions that no PR settled:

  • unattended triggers respecting autonomy at dispatch;
  • a route census for the private module;
  • a runtime route fence for agent keys.

Unverified.

  • A live MCP server against a running backend. The listings ran through a real MCP server and transport against a fake backend.
  • The private module's routes were read, not imported. Its use of the human-only primitives is recorded by the same handler but not exercised.
  • The session-only mapping depends on the backend's exact sentence. No test crosses the two packages.
  • Audit cost under a refusal loop, with the hash chain on or with several workers (the 60-second bound is per worker), and row volume on a live instance.
  • MCP clients outside this repo that call the thirteen tools with an agent or system key.

Journey Impact: none: MCP tool listings narrow to the scopes their routes admit and no journey step calls these MCP tools; a refused human-only call answers exactly as before and leaves one audit row; a key-authenticated create with fork_to_own and no token in the body now gets 400 FORK_PAT_REQUIRED, while the journey tier creates agents without a fork and a signed-in session (the UI) is unchanged

…ited, the saved-token fork takes a session, and no grant rests on an agent-only check

- MCP listing: each tool whose route needs a person or a signed-in session is
  listed through one shared predicate, so no key is shown a tool its scope can
  never call; within a listed scope the route still decides. The descriptions
  state each route's rule.
- MCP refusal reasons: a backend 403 whose detail is the person_required
  object, or the signed-in-session sentence, maps to the human-only answer.
- Audit: the human-only primitives raise HumanOnlyRefused, and an app handler
  records one row per refused attempt, bounded per principal and route, with
  no request body; the response is unchanged and an audit failure still
  answers 403.
- Agent creation: the arm that spends the creator's saved token as the new
  agent's is a credential bind and takes a signed-in session.
- A static scan fails any grant route that rests on an agent-only check alone;
  it lists one reviewed deferral. The feature-flows index carries one row for
  the issue.

Part of Abilityai/trinity-enterprise#719
Brings in the four earlier parts of Abilityai/trinity-enterprise#719 and
everything dev landed since 2026-10-27. Conflicts:

- fork_to_own.py: the saved-token refusal keeps this branch's rule (a
  signed-in session only) and name, and takes dev's MCP-aware remedy
  (ent#1007). dev's test_ent1007_mcp_fork_body.py imports the renamed
  function.
- tests/registry.json: dev's file plus this branch's three new entries and
  its test_human_only_principals.py description.
- requirements/auth.md: both §2.8 table rows; dev's census paragraph
  (section §2.13) with this branch's "Not closed here".
- architecture/mcp-server.md, user-docs mcp-server.md and faq: dev's rows
  and counts (apply_system, ask_for_credential, the fork block, 177 tools)
  with this branch's listing sentences; inject_credentials and setting a
  per-agent PAT are PERSON on dev, so the sentences say so.
- feature-flows.md: dev's rows, with the issue's row on top.
- feature-flows/credential-injection.md, audit-trail.md: both sides.
… person's key

On dev, writing a credential the caller supplies into its own agent takes a
person (the ruled exception in requirements/auth.md §2.8):
POST .../credentials/inject and PUT .../github-pat are require_person. The
listing still treated inject as a signed-in-session bind (shown to no key)
and said setting a per-agent PAT needed a session, so a person's own user
key was hidden a tool its route admits. Both now take the person predicate;
the visibility tests follow (3 + 14 + 13 refusals, 10 person/interactive
rows, 10 user-listed tools on a fresh install).

Part of Abilityai/trinity-enterprise#719
The create_agent fork block (ent#1007) relies on the backend spending the
caller's saved GitHub token. That arm makes the token the new agent's own,
a credential bind, so it runs only from a signed-in session, and an MCP
call never is one. The tool description and the docs that said the tool
spends the saved token now say a fork made through it is refused
FORK_PAT_REQUIRED for every key and is created from the web UI.

Part of Abilityai/trinity-enterprise#719
The Workspace door admits the system key for the Workspace's uses, and it
resolves to the admin who owns the install, so the dial's owner check alone
let it release a person's held class and rewrite the guard cap (both 200
before this). Releasing is a grant in the route's own words. Both writes
now refuse a caller that is not a person first, as the readiness,
canvas-pin and seat-decision writes beside them do.

The grant scan found both, and the agent's own seat-decision record: its
two agent-only checks narrow an agent key to its running turn and grant
nothing, so they are listed as reviewed non-grants.

Mutation: with the two person checks removed, four system-key cases in
test_ent719_workspace_autonomy_person_only.py go red and the scan reports
both routes.

Part of Abilityai/trinity-enterprise#719
…eir follow-up

The scan's one deferral and the census baseline's remaining entries are
tracked in trinity-enterprise#985, the follow-up filed for this issue.

Part of Abilityai/trinity-enterprise#719
…es inject and a PAT set

Follows the listing change: inject_credentials and setting a per-agent PAT
take a person on dev, so the lines that said they take a signed-in session,
or that a user key can only clear a PAT, now say a person's own user key
reaches both.

Part of Abilityai/trinity-enterprise#719
AndriiPasternak31 and others added 3 commits November 4, 2026 20:53
CodeQL reads url.startsWith(BACKEND) as an incomplete URL check. In these
stubs it only routes a stubbed fetch, but comparing the origin says the
same thing exactly and clears the alert. 70/70 pass in both files.

Part of Abilityai/trinity-enterprise#719
…e-flows index rows (#4243) — mechanical, per the merge-train note on the PR

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…4243) — train decision at Gate 1, see the PR note

#4232 (trinity-enterprise#341) landed on dev after this PR's last dev merge and
added the send block, services/tool_access_guard.py::assert_tool_allowed, in
front of nine send routes. It is a per-agent tool restriction, never a grant,
so the ent#719 scan lists it under NOT_GRANT_GUARDS with the nine routes.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@vybe

vybe commented Nov 4, 2026

Copy link
Copy Markdown
Contributor

merge-train (2026-11-04, evening): validated READY at 4de6dbaa7 (lane C: /validate-pr + /review + /cso --diff — the latter two clean; 8/8 fix-revert mutations red; every changed path executed by a test, none source-text). Two commits pushed to this branch:

  1. e818c544a — a merge of dev (aa12f15ef) with tests/registry.json rebuilt from the index stages (dev's 713 entries plus this PR's four) and both docs/memory/feature-flows.md index rows kept, newest first. Mechanical, no code change.
  2. e37a599b0 — a train decision, ruled at Gate 1 (2026-11-04): feat(guardrails): tool-access profiles — one choice sets read-only mode and the tools an agent can't use (abilityai/trinity-enterprise#341) #4232 (trinity-enterprise#341) landed on dev after this PR's last dev merge and put services/tool_access_guard.py::assert_tool_allowed in front of nine send routes, which this PR's own scan then reported as grant routes guarded by an agent-only check alone (test_ent719_no_agent_only_grant_guard.py::test_no_grant_route_is_guarded_by_an_agent_only_check_alone, 9 findings on the merged tree). That guard is a per-agent tool restriction, never a grant — a person, the system key and a Workspace visitor are never refused there — so it is now listed in NOT_GRANT_GUARDS with the nine routes and that reason. On the merged tree: the guard file 52 passed, the audit harness and principals suites 144 passed together. @AndriiPasternak31 please read the entry and acknowledge (or amend) it after merge — the wording of the reason is the train's, not yours.

Non-blocking notes from validation: frontend-e2e skipped on this lane C PR (no src/frontend/ change — the train carries the ui label); the two Workspace autonomy writes refuse through a plain HTTPException and are outside the new refusal audit, as the body and auth.md say (ent#985).

@AndriiPasternak31 AndriiPasternak31 self-assigned this Nov 4, 2026
@AndriiPasternak31
AndriiPasternak31 marked this pull request as draft November 4, 2026 23:43
@AndriiPasternak31 AndriiPasternak31 added the status-needs-fix PR has an unaddressed review/validation finding; cleared by the author's next push (#2815) label Nov 4, 2026
…cal, after a sibling landed

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@vybe

vybe commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

merge-train (2026-11-04, evening): pushed c4a3c50d9 — one more merge of dev with tests/registry.json rebuilt, because a sibling on tonight's train landed first. Mechanical, no code change.

@vybe vybe 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.

merge-train: batch validated on train/20261104-2310 (train PR #4254, all Tier 1 + Tier 2 green).

@vybe

vybe commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

merge-train (2026-11-04, evening): not merged — you converted the PR to draft at 23:43 UTC, after the train had validated and pushed to it, so the train stopped here. State at c4a3c50d9: validated READY (lane C), the train PR #4254 was fully green with this member on it (Tier 1 + Tier 2, the one regression diff red was the intermittent control now filed as #4256 and passed on the full re-run), the four required checks are green on this head, and it carries an approving review. When you mark it ready for review it can squash-merge as is, or it rides the next train with no further validation needed unless you push code. If the draft was about the Gate 1 NOT_GRANT_GUARDS entry (e37a599b0), amend the wording freely — the nine routes and the reason are what the scan needs.

@github-actions

github-actions Bot commented Nov 5, 2026

Copy link
Copy Markdown

⚠️ Nightly unit-suite check skipped — merge conflict against dev.

Resolve by running git merge dev locally and pushing the result. The next nightly run will re-test once the conflict is gone.

@github-actions

github-actions Bot commented Nov 5, 2026

Copy link
Copy Markdown

⚠️ Live-instance suite skipped — merge conflict against dev.

Resolve by merging dev locally and pushing the result; the next nightly re-tests.

…19-pr5

# Conflicts:
#	docs/memory/architecture/mcp-server.md
#	docs/memory/feature-flows.md
#	src/mcp-server/src/tools/operator_queue.ts
#	tests/registry.json
…made stale

#4204 (ent#1062) made the seat-decision doors agent-only, so the person path
these entries described is gone and the scan reports them stale.
@github-actions github-actions Bot removed the status-needs-fix PR has an unaddressed review/validation finding; cleared by the author's next push (#2815) label Nov 7, 2026
@AndriiPasternak31
AndriiPasternak31 marked this pull request as ready for review November 7, 2026 19:17
@AndriiPasternak31

Copy link
Copy Markdown
Contributor Author

Back to ready.

What changed since c4a3c50d9:

  • 5c3694923: a merge of dev. It had four conflicts, all additive on both sides: one import line in src/mcp-server/src/tools/operator_queue.ts (both name sets kept), two rows in docs/memory/architecture/mcp-server.md and one in docs/memory/feature-flows.md (both sides' text kept), and tests/registry.json (dev's 751 entries plus this PR's 4).
  • 5469133aa: removes the two routers/seat_decisions.py entries from NOT_GRANT_GUARDS. fix(auth): seat decisions and voice reply serve the turn the agent is in (ent#1062) #4204 made those routes agent-only, so the person path the entries described is gone, and the scan reported them stale on the merged tree.

On the merged tree: this PR's own tests pass (213). The auth guards from dev pass (695 across the #186, #293, #1310, #2996, ent#629, ent#638, ent#641, ent#814, ent#840, ent#1024 and ent#1062 suites). In src/mcp-server, tsc --noEmit is clean and 1380/1380 tests pass. CI is green on 5469133aa.

@vybe on e37a599b0: I've read the NOT_GRANT_GUARDS entry and am keeping it as written. assert_tool_allowed restricts and never grants, so the nine routes belong there with that reason. Your two non-blocking notes stand: the refusal audit for the Workspace autonomy writes is tracked in ent#985.

…19-pr5

# Conflicts:
#	docs/memory/architecture/mcp-server.md
#	tests/registry.json
…T_GRANT_GUARDS

On the merged tree the grant scan reported six routes resting on an
agent-only check alone. None is a grant:

- trinity-enterprise#1135 returns an ended ask to its room on the agent's
  next start, so start, chat, task result and system deploy/restart now reach
  the room wake, and through the engine's reply post, `tagger_for`. That post
  carries no tags (`post_message` asks for a tagger only for a sender's own
  tags), so the check never runs there.
- trinity#4302's Continue reaches `tagger_for` the same way, and calls
  `assert_tool_allowed` for parity with `/messages`. Its person check is
  `_is_room_person` in the service.
@AndriiPasternak31

Copy link
Copy Markdown
Contributor Author

Merged dev again; conflict-free.

What changed since 5469133aa:

  • 9d4c6ab83: a merge of dev (97a86f1dc). Two conflicts, both additive:
    • docs/memory/architecture/mcp-server.md, the operator_queue.ts row: dev's row (the project target from ent#1134 and the named-instance destination from ent#1158), plus this PR's clause that respond_to_operator_queue is listed to user keys only.
    • tests/registry.json: dev's 771 entries plus this PR's 4.
      The PR's diff against dev is unchanged by the merge: the per-file numstat is identical to the diff before the merge (67 files, +5980/−264). The src/backend/enterprise pointer moves only because dev moved it.
  • 254a84662: two NOT_GRANT_GUARDS entries for routes dev added or rewired. On the merged tree the grant scan reported six routes resting on an agent-only check alone:
    • ent#1135 returns an ended ask to its room on the agent's next start. That puts start, chat_with_agent, the internal task result and system deploy/restart on the room wake, and through the engine's reply post they reach tagger_for. That post carries no tags, and post_message asks for a tagger only for a sender's own tags, so the check never runs on those routes. I confirmed this by removing just that one edge (_wake_agent_locked → post_message): the scan then finds no other path from those routes to tagger_for.
    • bug(rooms): a stopped mention chain is a dead end, with no plain explanation and no way to continue #4302's Continue reaches tagger_for the same way. It also calls assert_tool_allowed for parity with /messages, so it joins the nine routes already listed there. Its person check is _is_room_person in the service.

On the merged tree: this PR's own tests pass (213; 2278 across the ent#719 suites). The auth guards from dev pass (695 across the #186, #293, #1310, #2996, ent#629, ent#638, ent#641, ent#814, ent#840, ent#1024 and ent#1062 suites). Dev's tests in the areas this PR touches pass (324: #4302, #4357, ent#1134, ent#1135, ent#1147, ent#1148, ent#1165, ent#1172, ent#1202). In src/mcp-server, tsc --noEmit is clean and 1412/1412 tests pass. CI is green on 254a84662 (22 passed, 6 skipped).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants