DottaandPaperclip
6e781e0ab2
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Connections give agents access to external tools through access
profiles.
> - Operators can remove a broad app profile and keep a limited profile.
> - Saving a connection's agent list restored the broad profile to
existing installation targets.
> - Those restored grants could permit write tools that the limited
profile omitted.
> - This pull request grants the app profile only to new installation
targets.
> - The benefit is stable permission choices when an operator edits an
installation list.
## Linked Issues or Issue Description
**What happened?**
`PUT /api/tool-connections/{connectionId}/installs` attached the app
profile to every target in the submitted list. An existing target
received the profile again if an operator had removed it. Adding an
agent, removing another agent, or saving the same list could therefore
restore broad tool permissions. The activity log recorded each restored
binding as `tool_connection.install_access_extended`.
**Expected behavior**
Targets that remain installed keep their saved profile assignments. A
removed app-profile assignment stays removed. New installation targets
receive the current app-profile defaults. Removing an installation still
removes its install-derived binding.
**Steps to reproduce**
1. Install a connection with read and write tools on two agents.
2. Give one agent a read-only profile and remove its broad app-profile
assignment.
3. Save the installation list, add an agent, or remove the other agent.
4. Check the first agent's permission to use the write tool.
Before this change, the write tool becomes allowed again. After this
change, it stays denied.
Related: #17422 adds an agent-edit permission check to direct profile
bind and unbind operations. This PR preserves removed assignments during
installation-list updates. The duplicate search found no open PR for
this defect.
## What Changed
- Attach app-profile bindings only for new installation targets.
- Preserve removed grants for existing agent and company installations.
- Keep legacy connection-wide include cleanup on every non-empty
installation save, including saves with no added targets.
- Add six PostgreSQL regressions. All six use the real install HTTP
route with a local operator fixture.
- Check effective read/write decisions, saved assignments, new-agent
defaults, uninstall cleanup, legacy-rule cleanup, and access-extension
audit records.
- Document the behavior in the connector runbook and both access maps.
## Verification
- Red: all four new regressions fail before the fix. The policy returns
`allow_profile` where the tests require `deny_default`.
- Review regression: the two legacy-rule cases fail before the review
correction. The original four cases still pass.
- Green after review: all six regressions and five existing
profile-precedence tests pass after the correction.
- Command: `pnpm exec vitest run
server/src/__tests__/tool-connection-installs.test.ts
server/src/services/tool-profile-binding-precedence.test.ts`.
- The local regression used `PAPERCLIP_TOOL_ACCESS_TEST_DATABASE_URL`
with a separate, fully migrated PostgreSQL 17 test database. Embedded
PostgreSQL could not start because the host had reached its semaphore
limit. Skipped tests were not counted as a regression pass.
- `pnpm -r typecheck` and `pnpm build` passed for the initial fix.
Server `tsc --noEmit` also passes after the review correction.
- `node scripts/check-maps.mjs`, `node
scripts/check-module-boundaries.mjs`, and `git diff --check` pass.
- `pnpm test:run` was started, then stopped after 16 tests in the
native-session suite failed during embedded PostgreSQL startup. A
focused rerun of its `collect` case confirmed the database startup
error. Direct `initdb` output reported `could not create semaphores: No
space left on device`. The full local suite is incomplete. All six new
regressions executed against the separate test database and passed.
- [Initial-fix
CI](https://github.com/paperclipai/paperclip/actions/runs/40541191695)
passed at `23253ee332b90f142e48df3f553aeaaa7f6fa298`. Greptile gave that
commit 5/5. Ponytail found the legacy cleanup gap; this revision
restores that cleanup and adds both regression cases.
- [Current-commit
CI](https://github.com/paperclipai/paperclip/actions/runs/40547366181)
passes for `729c487cf2ffaae261a820de0cf9a033a0365fd4`, including type
checks, build, test shards, and both `ci / verify` and `ci / e2e`
aggregate checks.
- The first CI attempt hit a 30-second module-import timeout in the
unchanged `issue-agent-mutation-ownership-routes.test.ts` suite. All 179
tests passed locally. One [job
retry](https://github.com/paperclipai/paperclip/actions/runs/40547366181/job/122349226221)
passed without a code change. The cause of the import slowdown was not
established. The failed attempt remains recorded in CI history.
- Greptile and Ponytail both give the current commit 5/5 with no
actionable findings. Ponytail confirms the legacy cleanup finding is
fixed. The review thread is resolved, and the PR has no merge conflicts.
Ponytail's advisory check has a neutral conclusion with a 5/5
assessment.
## Risks
- New installations retain the current app-profile defaults. Removing
and then reinstalling a target is a new installation.
- A repeated installation save no longer restores a missing profile
assignment. Operators must use an explicit profile assignment when they
want to restore that grant.
- Existing unwanted grants still require a separate access review and
repair. This PR does not change stored grants, reconnect identity
behavior, or the default access model.
- No database migration or API schema change is required.
## Model Used
- OpenAI GPT-6 in Codex, with reasoning, repository tools, and code
execution. The session does not expose the exact routed model ID or
context-window size.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
9.0 KiB
navigation
| navigation | ||||||
|---|---|---|---|---|---|---|
|
App access and action permissions
After connecting an app, an operator or authorized agent decides which agents may use it and whether each action is off, requires approval, or is allowed. Activity and action tests help verify the resulting access.
Feature ID: app-permissions.
Implementation: app detail, permissions, activity.
Agent access: companion.
Sub-features
agent-access:app-permissions/agent-access— grant the connection to all or selected eligible agents.action-policy:app-permissions/action-policy— set off/ask/allowed independently for available actions.catalog-change:app-permissions/catalog-change— review newly discovered/quarantined actions before enabling them.test-action:app-permissions/test-action— choose an actor and inputs and inspect a real action result.account-maintenance:app-permissions/account-maintenance— inspect accounts, reconnect/revoke, and review connection activity.
Changing the connection's agent list preserves profile assignments for agents that remain installed. Saving the list must not restore a removed app-profile assignment. New installations retain the current app-profile defaults. Non-empty saves also remove legacy connection-wide include rules, including unchanged lists and removals with no new targets.
How to get to it (user POV)
permissions
Open an app at /apps/:connectionId/permissions; this is the default connected-app view.
test-and-maintain
Use the action test control in Permissions, then the connection’s Activity and available account/advanced controls.
delegated-permissions
Ask an agent to change access or action policy for a named connection through the existing APIs. The responsible person's current authority, the agent's management grants, resource scope and all affected targets bound the request. An explicitly requested, authorized policy change may target that same agent.
Driving it
Preconditions: follow the baseline. Prepare a connection to a fixture or test provider, two agents, and a harmless action. Record provider and credential ownership.
permissions
Automated: app detail covers agent/action controls, quarantined actions, and navigation using mocked requests.
Installation permission regressions exercise the real install API with a local operator and PostgreSQL. They check that adding, removing, or retaining agents preserves removed app-profile grants and denies write tools for agents with read-only profiles. They also check company installations, new-agent defaults, legacy connection-wide include cleanup, and access-extension audit records. These fixtures do not qualify an agent-authenticated request or a live provider.
Runtime assignment tests
use PostgreSQL to verify committed assignment notifications, bounded snapshots,
rollback, and concurrent AI adoption. The owning lifecycle plugin can read
standing assignments through ctx.agents.getRuntime; this does not grant tool
execution access or replace task-specific authorization.
Tool-definition runtime tests cover catalog invalidation, scoped policy/profile-entry recipients, ignored bookkeeping, profile-entry edits concurrent with setup finalization, and profile replacement concurrent with application deletion using PostgreSQL. They do not qualify live provider access.
Connector access runtime tests cover grants, delegation, membership cleanup, referenced vault changes, and agent-scoped secret bindings. OAuth and Railway tests exercise the corresponding credential lock order. Slack search and membership cleanup tests cover lock contention and complete transaction retries. Provider calls use fixtures; no live credentials are qualified by this coverage.
Manual: Grant one agent access, leave another excluded, and exercise off, ask, and allowed states for a harmless action. Reload between changes. Verify actual denied calls stay denied and ask-first creates a decision rather than executing early.
For Braintrust, distinguish reviewed action risk from effective policy: S4 methods retain the shared Allowed defaults. Explicit Off and Ask-first choices must survive refresh and reconnect. Exercise the read, write, and destructive classifications with a fixture, including billable tests classified as writes and dataset row edits/automation activation classified as destructive. After initial discovery, newly added or changed tools remain quarantined until reviewed. Use synthetic data for provider calls; see Braintrust. Live US OAuth proof covers bounded reads, a synthetic dataset insert/readback through actual process-agent gateway calls, and denial after local removal. Off, Ask-first, and changed-tool denial use fixture evidence; the other three methods still need live account qualification.
test-and-maintain
Automated: app detail tests cover test-dialog/UI contracts. Real provider execution and revocation require the selected provider’s live check.
Manual: Run a read-only action with explicit inputs and inspect returned data and activity. Refresh discovery and review new actions. Revoke or disconnect only the disposable credential, then verify subsequent use fails with an actionable reconnect state.
For Daytona, opening an older saved catalog discovers the current native contract. Removed diagnostic actions disappear from Permissions and agent discovery; new or changed actions require review. Existing Off/Allowed choices remain in place. Daytona regressions cover shared/personal catalog upgrades, failed refresh, permission preservation, run-bound file transfers, and revocation with fixture provider responses.
Unikraft actions follow the same review rules: deletion, stop/suspend/detach and sandbox command execution are destructive, and catalog updates quarantine new or changed actions. Unikraft regressions cover classification, Off policies, revocation and stale contracts with fixture provider responses.
delegated-permissions
Automated: production-authenticated integration covers actual key/JWT policy edits, retained targets, caller/target test policies, human approval, scope and revocation using PostgreSQL and provider fixtures.
Manual: Request a bounded access or policy change through an actual agent, reload Permissions, and verify the saved audience, action choice and agent audit actor. Include an explicitly requested self-targeted policy edit. Repeat with missing management grants, an excluded target/resource, and Ask or Plan mode; writes must be denied. A denied tool call must not cause an unsolicited policy relaxation. An Ask-first action still requires the authorized human's decision; the agent cannot approve its own governed action or edit its own principal permissions. Verify caller and target policies both apply when testing as another agent.
Gotchas
- Connected does not imply an agent has access or an action is allowed.
- Credential-only connections may replace tool-action controls with account-specific controls.
- See connection setup for auth and questions and approvals for pending action review.
Storybook verification
catalog-change
Capability ID: app-permissions/catalog-change.
Scope: ui Storybook: Mount PermissionsPanel/AppDetail with quarantined actions, selection/review, refresh pending, empty and failed discovery states. Existing auto-allowed NewToolsAllowed examples are not quarantine review. Production: Exercise catalog refresh and new-tool review with permitted/denied actors; unreviewed actions stay quarantined, prior Off/Ask choices survive refresh, and approved review persists. Sources: Source: PermissionsPanel.tsx, AppDetail.tsx, tool-access.ts. Tests: AppDetail.test.tsx, tool-access-service.test.ts, tool-access-policy-service.test.ts
delegated-configuration
See the canonical delegated configuration guidance and acceptance evidence.