DottaandPaperclip
ad55d0a281
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agents use Apps through a gateway that checks identity, company access, and action policies. > - Personal pasted credentials can point to company secrets. Setup can show success while the gateway rejects every call. > - Several OAuth methods also omit the scopes needed for their supported write actions. > - This pull request gives setup, health checks, and invocation the same credential rules. Owners repair existing connections by reconnecting. > - New connections request reviewed permissions for their supported actions. Read-only choices remain available under Advanced. > - Agents can use the connections people give them, while existing consent, identity boundaries, and action restrictions remain enforced. ## Linked Issues or Issue Description Refs #14009 and #14008. This addresses the personal-credential defect. The separate GitHub organization-identity selection defect is outside this change. Related work: #13942 fixed part of new personal-key setup. #14200 independently fixes legacy personal reconnect and protects managed-agent profile credentials during removal. This PR covers that ownership invariant across key and secret-URL setup, reconnect, health, discovery, and invocation, and keeps owner reconnect as the repair path. #14059 tracks requested versus provider-asserted OAuth scopes; it remains separate work. I searched open PRs and issues for Zapier, Airtable scopes, connector writes, and personal credential failures. **What happened?** A Zapier secret URL saved through personal setup can become a company secret referenced by a user grant. Health checks bypass the gateway's ownership check, so the connection appears healthy but calls fail with `grant_credential_invalid`. Custom-header paths can also receive a duplicate `credentials.` prefix. Omitted OAuth scopes make write access depend on provider defaults. **Expected behavior** Personal invocation credentials belong to the selected user. Setup, health, and actual calls enforce the same rule. New connections request documented permissions for supported read and write actions. Existing tokens gain no permissions without provider consent. **Steps to reproduce** 1. Connect Zapier or a generic secret URL with the personal identity. 2. Allow an agent to use the connection and complete setup. 3. Invoke a tool through a run-scoped gateway. The legacy layout fails ownership validation despite successful setup. **Paperclip version or commit** The implementation started from `44736c9c7c67b7b646ead9d51721db10f5b83835` and was rebased onto master at `94e8dec56`. **Deployment mode** Built from source. Regression tests use isolated PostgreSQL fixtures and controlled MCP transports. ## What Changed - Share credential writing, ownership validation, and canonical paths across initial setup, resume, reconnect, rotation, health, discovery, and gateway calls. Keep OAuth client-registration secrets separate from invocation credentials. - Existing personal connections with company-scoped credentials require owner reconnect with a fresh key or secret URL. Reconnect creates a correctly owned value and updates the existing grant and declarations. There is no automatic ownership backfill or new startup hook. - Preserve PostgreSQL timestamp precision when reconnect checks whether a grant changed. Previously, converting the timestamp to a JavaScript Date could reject reconnect with a false concurrent-change error. - Protect credentials used by other grants, connections, bindings, managed-agent profiles, routine triggers, or secret proposals from connection removal. - Review all 117 tool methods, including 84 OAuth methods. Record explicit scopes or documented provider-default exceptions with official evidence. Add Airtable's seven scopes, Hugging Face repository/job scopes, and other documented MCP permissions. - Prefer available write-capable methods. Put explicit read-only choices under Advanced. Explain pasted-key permissions and offer reconnect for missing OAuth consent. Preserve existing grants, policies, Google availability gates, and curated scope allowlists. - Reconnect generic secret URLs and custom headers using their stored credential fields. Refresh the catalog after setup, correct reconnect feedback and error guidance, and let Cancel exit invalid setup while Save & exit retains draft-saving behavior. - Apply ownership checks to the new GitHub repository/skill connection picker. Align the permission audit with the Google scope reductions merged on master. - Add run-scoped gateway, ownership, owner-reconnect, OAuth URL, insufficient-scope, UI, and catalog-wide regression coverage. Update the connector playbook and permission audit. ## Verification Latest commit `97bc0b86e0eae0ec892e4ac44beff1a66164b20e` passes all CI/status gates (55 completed check runs, no failures or pending checks) and has a completed Greptile review at **5/5 with no outstanding findings**. GitHub reports the PR as mergeable/CLEAN. - **Embedded browser:** used the actual server and built UI from this worktree, a fresh isolated database, and local HTTP MCP fixtures. Completed personal bearer-key, secret-URL, and custom-header setup; reproduced the legacy ownership failure; reconnected through the owner’s form; and completed writes afterward. Read-back was verified for bearer-key and secret-URL connections. Public organization-wide setup appeared immediately in Browse without reload. Zapier URL validation/Cancel and Google’s enrollment gate were also exercised. - **Persistence and invocation:** verified user ownership, canonical `credentials.authorization` / `remote.url` / `headers.X-Api-Key` declarations, and unchanged connection/grant identity. The old company secrets retain their ownership. Separate HTTP calls through an actual run-scoped gateway session completed a write and read-back. - **Backend coverage:** the final gateway suite passes all 82 cases, including catalog Zapier and generic inline reconnect. It checks company/user isolation, canonical declarations, same-endpoint URL validation, fresh credentials, retained restrictions, and real gateway read/write execution using fixture transport. A timestamp with PostgreSQL microseconds covers the former false reconnect conflict. - **Local checks:** 368 catalog, gateway, repository, and UI tests passed before the final extra Zapier case; 49 GitHub skill access tests also passed. All three Apps browser regressions pass, including reconnect through the actual form and catalog visibility without reload. Full `pnpm -r typecheck`, `pnpm build`, server typecheck after the final patch, and token gates passed. Full tool-access service runs hit varying 15-second Google fixture timeouts; both affected cases and the updated reconnect assertion pass in isolation (3 tests). The complete test matrix passes in CI on this head. - **Verification limits:** no live provider account was available for Zapier/Airtable/OAuth consent or account-bound write proof. Public metadata and local fixtures do not establish provider consent. The original development database clone failed on a pre-existing missing `tool_connections_transport_check` constraint; browser acceptance used a fresh isolated database created by the normal CLI onboarding flow. ## Risks - Existing broken personal connections stay unusable until their owner reconnects. Health, discovery, and invocation return an actionable ownership error; startup does not rewrite credential ownership. - Scope changes affect new authorization requests. Providers may still require resource selection, account roles, paid plans, or app verification. Existing consent and action restrictions remain unchanged. - Shared credentials are retained rather than reassigned or revoked. Provider-default exceptions and unavailable live checks are documented in `doc/connections/CONNECTOR-PERMISSION-AUDIT.md`. - No new endpoint, database table, lockfile change, or CI workflow change is included. ## Model Used OpenAI Codex, based on GPT-6, with reasoning, code editing, shell execution, web research, and browser tools. The exact deployment model ID and context window were not exposed in this session. ## 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>
13 KiB
Tool connection permission audit — 2026-09-30
This review covers 117 tool methods (84 OAuth methods). The machine-readable source of reviewed defaults lists each method's exact requested scopes, supported actions, restrictions, sources and verification limits. AI runtime authentication and chat/channel setup are separate contracts and were not changed.
Shared credential failure
Zapier's secret URL exposed a shared ownership/resolution problem. The same invariants apply to personal pasted-key and custom-header methods, including Bitly, Cloudflare, Coda, Fireflies, GitHub PATs, Kernel, O'Reilly, PagerDuty, PostHog, Postman, Razorpay, Sanity, Similarweb, Stripe, Supabase and You.com. Generic MCP setup uses this path too, so “Connect your own” was not a reliable workaround. This is a code-path finding, not a claim that every provider was tested with a live account.
Personal invocation secrets now belong to the grant's user. Setup, health, discovery and the run gateway share ownership checks and canonical credential paths. Public unauthenticated URLs need no credential repair. OAuth client registration secrets remain company-owned and separate from invocation tokens. Existing connections with incorrectly owned credentials require the owner to reconnect with a fresh key or secret URL. There is no automatic ownership backfill.
Changes
- Airtable now requests its seven documented record, schema, comment and workspace/base scopes, including writes.
- Explicit scope sets were added for providers that advertise a scoped MCP resource, including Beehiiv, Netlify, Miro, Sentry, Supabase, Todoist and TickTick. Read and write remain subject to provider roles and resource selection.
- Hugging Face adds repository read/contribution and jobs to
read-mcp. Optional tools still need enabling in HF's MCP settings. - Slack's reviewed set now covers the documented message, channel, reaction, canvas, file and list actions. It replaces the obsolete generic search scope with the documented search scopes. The fixed app/approval gate remains.
- Google write/draft methods take priority over managed read-only methods when available. Existing Google profiles, preview verification and availability gates remain. People and Workspace Search stay read-only.
- The hosted Fireflies server also exposes meeting sharing, renaming, moving and soundbite creation. Its identity scopes are retained; meeting ownership and team roles decide which mutations succeed.
- Provider read-only choices stay available under Advanced. Existing OAuth tokens and action restrictions are untouched. Permissions offers reconnect when provider consent needs changing.
Provider-default exceptions
These are deliberate exceptions to supplying scopesHint, not claims that an
old grant can write. Several servers put resource/permission selection in their
own consent screen; Box uses registered app scopes, and managed GitHub uses
installation permissions. An authorization server's general scope catalog is
not a safe substitute for the MCP permission contract.
| Provider / method | Reason and limits |
|---|---|
bitly / mcp-oauth |
The official MCP quickstart uses browser authorization without client-selected scopes; neither protected-resource nor authorization-server metadata advertises a scope list. Bitly account permissions govern link actions. Evidence |
box / mcp-own-oauth |
Box requires scopes (including Manage AI) on the registered Box app in the Admin Console. Its MCP authorization metadata has no request-scope list; consent and the app registration control file operations. Evidence |
egnyte / mcp-oauth |
The hosted authorization server selects the Egnyte tenant/account permissions. Neither MCP nor authorization-server metadata advertises request scopes. Documentation rendered no readable body during this review; tenant-bound write proof remains required. Evidence |
github / managed |
Managed github.code uses a GitHub App installation and selected repositories. Installation permissions, not OAuth scope strings, grant code and pull-request writes; retain the managed profile. Evidence |
make / mcp-oauth |
Make documents selecting scopes and scenarios during its hosted connection flow. Management tools require a paid plan. Do not replace that resource selection with invented MCP client scopes. Evidence |
oauth-generic / oauth |
Operator-defined OAuth endpoints have no provider-specific reviewed scope list. Request only the scopes supplied by the operator; this template is not a curated provider allowlist. Evidence |
planetscale / mcp-oauth |
PlanetScale documents choosing organizations, databases and read/write permission at authorization. Its general authorization server advertises unrelated organization administration too; retain the provider consent selection, and the separate insights-only endpoint. Evidence |
planetscale / mcp-insights-only |
PlanetScale documents choosing organizations, databases and read/write permission at authorization. Its general authorization server advertises unrelated organization administration too; retain the provider consent selection, and the separate insights-only endpoint. Evidence |
posthog / mcp-oauth |
PostHog documents the no-scope MCP setup as read/write, with optional readonly and feature filters. The authorization server advertises account administration unrelated to many tools; retain its MCP consent defaults and the existing explicit filters. Evidence |
postman / mcp-oauth-minimal |
The official remote MCP setup uses browser sign-in and endpoint-selected minimal/code/full tool catalogs. Its protected-resource and authorization-server metadata publish no scope set; account/workspace rights govern writes. Evidence |
postman / mcp-oauth-code |
The official remote MCP setup uses browser sign-in and endpoint-selected minimal/code/full tool catalogs. Its protected-resource and authorization-server metadata publish no scope set; account/workspace rights govern writes. Evidence |
postman / mcp-oauth-full |
The official remote MCP setup uses browser sign-in and endpoint-selected minimal/code/full tool catalogs. Its protected-resource and authorization-server metadata publish no scope set; account/workspace rights govern writes. Evidence |
razorpay / mcp-oauth |
Neither protected-resource nor authorization-server metadata advertises scopes. Keep hosted provider consent; the previous official OAuth documentation URL returned 404 during review. Account-bound writes need live confirmation. Evidence |
ticket-tailor / mcp-oauth |
Hosted authorization controls box-office API-key permissions; do not treat OAuth sign-in as increasing the underlying key permissions. This method requires account-bound proof. Evidence |
webflow / mcp-oauth |
The official MCP setup installs the Bridge App and asks users to authorize sites. Neither protected-resource nor authorization-server metadata publishes a request-scope list; the installed app and site selection govern writes. Evidence |
Read-only and provider-controlled methods
Candid, Context7, O'Reilly, Similarweb and You.com expose retrieval/research capabilities rather than document/account mutation. PlanetScale's insights-only endpoint deliberately excludes query execution. Xero's current published MCP scope set includes invoice/report reads and settings access, without invoice write permission. Do not widen these using unrelated general API scopes.
Scopes such as openid, global, mcp:all or workspace:member do not have to
contain the word “write” to authorize work. The provider's MCP tool contract,
role and consent selection determine their meaning. In particular, Cloudflare,
Vercel, Wix, Kernel and Supermemory retain their provider-side permission gates.
Evidence and verification boundaries
Official docs and unauthenticated protected-resource/authorization metadata were retrieved on 2026-09-30. The review records source URLs per method. Some pages (especially Egnyte and Razorpay's old OAuth URL) were unavailable or unreadable; those entries explicitly retain that limitation. Embat publishes identity metadata but no verified write contract. No account-bound write guarantee is made for these entries.
No provider account was used for live read/write verification in this task. In particular, public scope metadata is not proof that an existing token has those permissions or that an account has the required paid plan, resource ACLs, admin approval, or Google preview enrollment. Use test accounts/resources for that proof before claiming provider-level acceptance.
Backend regressions execute catalog Zapier, generic secret URLs, personal bearer/custom headers, organization credentials and public URLs through the run-scoped gateway using a fixture transport. They assert canonical persisted ownership/declarations and run read and write calls. Reconnect regressions cover replacing legacy company credentials with user-owned values and declarations. OAuth fixtures assert exact authorization scopes and rejection of an unrelated advertised admin scope; they do not contact provider accounts.
The managed worktree has a separate instance configuration and database path.
Local CLI provisioning was attempted with both minimal and full seed modes;
both failed while applying the copied database's migrations because
tool_connections_transport_check was missing. The development instance was
not started from that clone. Clean fixture databases were used for the backend and Apps browser
checks; their success does not establish successful seeding of that local copy.
Embedded-browser acceptance
On 2026-09-30, a hands-on walkthrough used the PR checkout's built UI and actual server, a fresh isolated database created through CLI onboarding, and a local HTTP MCP fixture. Starting from the sidebar's Connectors page, the operator selected “Just me,” entered a bearer key, and created and read back a disposable widget through the Permissions screen's agent test controls.
After seeding the legacy ownership mismatch in that disposable connection,
invocation and catalog refresh rejected it with grant_credential_invalid.
The catalog showed “Needs attention” and offered Reconnect. Replacing the key
through that UI preserved the connection and personal grant, created a fresh
user-owned secret and canonical declaration, and restored writes. The legacy
company secret retained its ownership. Separate HTTP calls through a session
bound to a fixture agent run also completed a write and read-back.
The walkthrough exposed and verified fixes for a false “Still not working” message after successful reconnect, incorrect action-input advice for ownership errors, and Cancel attempting to save an invalid Zapier URL. The browser reconnect regression now performs the replacement through the form and checks that the stale warning disappears.
A second personal connection used a secret URL. After reproducing its legacy ownership failure, the browser could replace the URL and create/read back a widget. Generic reconnect now derives URL/header fields from the stored credential placement instead of assuming a bearer key, and rejects replacement URLs for a different public endpoint. A new public, organization-wide connection also appeared immediately when returning to Browse, without a page reload. The walkthrough fixed setup cache invalidation and a cramped reconnect banner.
Zapier's URL validation and cancellation were exercised, but a live Zapier connection was not completed. Gmail stopped at instance enrollment. Neither journey establishes provider-account consent or live provider read/write proof.
Automated verification
- Run
pnpm -r typecheck,pnpm build, andpnpm check:token-gates. - The affected Apps browser suites passed 10 tests, with one existing restart case skipped. These used clean, isolated fixture databases.
- Run
pnpm test:runfor the full suite. Current-head CI and local results are recorded in the pull request; fixture coverage is distinct from provider proof. - New gateway fixtures execute both read and write calls through real run-scoped gateway sessions. They also verify that invalid ownership requires reconnect and that the owner's fresh credentials restore access without changing identity.