DottaandPaperclip
b8f6d9b23f
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The feature and agent access maps describe user journeys and their permission boundaries. > - PRs #17737 and #17739 added delegated connection setup across several existing areas. > - The maps include those operations, but some recipes and board-only statements are stale. > - This PR adds usable setup recipes and corrects the access descriptions. > - The benefit is a clearer verification path that preserves human and agent authority boundaries. ## Linked Issues or Issue Description Refs: #17737, #17739. Related: #17862 changes connection setup advice and catalog choices. This PR only clarifies the existing maps. **Issue type** Outdated and missing documentation. **Where is the issue?** The paired connection setup, app permissions, chat channels, model accounts, and gateway maps under `maps/`. **What's wrong?** Delegated setup guidance sits under Gotchas without a matching driving recipe. Some model-account text still groups supported account sign-in with board-only host controls. A few callback, privacy, and native admission descriptions omit important limits. **Suggested fix** Add the missing recipes. State the current route and service boundaries. Keep existing capability IDs and distinguish source review, fixture tests, and live provider proof. ## What Changed - Add paired entry points and driving recipes for delegated setup, permission changes, and managed AI sign-in. - Describe Google consent restoration, GitHub requested credential fields and saved rotation, and Vercel personal credential attribution. - Correct the Vercel callback state checks and chat conversation/test-status privacy scope. Name the separate GitHub registration handoff endpoint. - Replace blanket board-only AI login wording with the specific managed-account and host/session boundaries. - Link the five access maps to shared native admission and work-mode limits. State the permitted self-targeted policy administration boundary. ## Verification - `node scripts/check-maps.mjs` passed: 35 paired areas and 192 stable capability IDs. This checks structure and references. - `node scripts/storybook-catalog.mjs` passed. Generated output remains ignored. - `git diff --check` passed. - Eleven selected cases in `server/src/__tests__/connection-management.integration.test.ts` passed on source `db70c5acd9`, the unchanged base of this documentation commit. They use a fresh PostgreSQL database, actual agent keys/run JWTs, human sessions, and deterministic provider fixtures. The other 61 cases were not selected. - The selected cases cover connection/profile creation, Google saved choices, native API entry points, Slack caller/target policy, GitHub import and identity confirmation, durable gateway authority, AI accounts/pools, saved human handoffs, revocation, scope, trust, and Ask/Plan denial. - Read-only source reviews checked all five areas. The disposable database was removed after the run. - Full workspace typecheck, build, and test sweep were not rerun for this Markdown-only change. Live provider login and browser journeys were not run. Per-operation source-only/not-run labels remain unchanged. ## Risks Low risk. Incorrect documentation could misstate a permission boundary or imply broader verification. The changes cite the owning routes and services and retain fixture and live-provider limits. No runtime, schema, lockfile, or workflow files change. ## Model Used OpenAI Codex, GPT-6 family, with reasoning, repository tools, code execution, and read-only source-review agents. The session does not expose a more specific deployment 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 — existing fixtures verify this documentation-only change - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green — CI is running and Paperclip Review is queued on the current head - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups — exact head `4d16f101968d6908f90f72b6ff6ecbb79037f168` - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
8.1 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.
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.
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.