Devin Foley
059ae49cab
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Apps connections give agents governed access to external services through vault credentials, grants, action policies, the tool gateway, and audit. > - Unikraft Cloud runs unikernel micro-VMs, services, and volumes across regional metros, and it offers a sandbox plugin for commands and files. > - Unikraft is not in the catalog. It has no hosted MCP server, so the generic "Connect your own MCP server" flow cannot reach it. > - Daytona (#16483) added a native REST pattern for this case: a catalog generated from the provider's published OpenAPI specifications and executed through the gateway. > - This pull request adds Unikraft on that pattern and moves the shared native-provider code into one registry, so the shared connection code does not name each provider. > - The benefit is governed agent access to all published Unikraft actions, with the token kept in the vault and sent only to published Unikraft hosts. ## Linked Issues or Issue Description Refs #16483 **Problem or motivation** Teams that run workloads on Unikraft Cloud want their agents to list instances, read logs, deploy and scale services, and run commands in sandboxes. Unikraft is not in the Apps catalog. Unikraft has no hosted MCP server, so operators cannot connect it through the remote MCP flow. **Proposed solution** Add a native Unikraft connection. Generate its actions from Unikraft's official OpenAPI specifications for the platform API and the sandbox plugin. Pin the specifications to a reviewed commit. The operator connects an API token. The token stays in the vault and goes only to the five published metro hosts. Every action takes an optional metro. Actions without a metro use the connection's default metro, which the operator can change under Advanced. **Alternatives considered** A catalog-only AppDefinition was not possible because no hosted MCP endpoint exists. Wrapping the `unikraft` CLI was rejected because it would expose host filesystem behavior and CLI login state. A second copy of the Daytona bridge was rejected; the shared transport and catalog contract are now one module with a provider registry. **Roadmap alignment** This extends the existing Apps and Connections provider coverage. It uses the existing credential, grant, policy, gateway, and audit model. It does not overlap planned core work. ## What Changed - Added `scripts/generate-unikraft-tools.mjs` and its tests. The generator reads the platform and sandbox plugin specifications at commit `5dd107ea1cd8716b83cb86a83ed2a6ee46f99b5b`, resolves shared parameters, records source SHA-256 hashes, and writes `server/src/services/unikraft/operations.generated.json`. - The catalog has 105 actions: 89 platform operations and 16 sandbox plugin operations. The server-sent audit event stream is recorded in the inventory and is not advertised as an action. - Classification: GET operations and sandbox reads and waits are reads. Delete, stop, suspend, detach, unpin, and sandbox command execution, signals, and stdin are destructive. All other operations are writes. - Added `server/src/services/connectors/unikraft/client.ts` and its generated catalog. It validates arguments against the generated schemas, accepts only published metros, rejects path traversal, sends JSON bodies on GET and DELETE as the specification requires, and verifies the token with `GET /v1/users/quotas`. A sandbox wait that times out (documented HTTP 408) returns a still-running result instead of a failure. - Moved the bounded, credential-redacting HTTP sender and the catalog contract helpers from `daytona.ts` to `native-rest-client.ts`. Added `native-provider-catalogs.ts`. `tool-access.ts`, the `tool-access/catalog` and `token-broker` modules, `connectors/tool-policy.ts`, and `tool-gateway.ts` now use this registry instead of Daytona-specific checks. Daytona behavior does not change. - Added the Unikraft definition source, the generated definition, the brand mark and manifest entry, and the permission review (`liveProof: not-run`). - Added `doc/connections/UNIKRAFT.md` with a sequence diagram, endpoints, setup, actions, and limits. Updated the connections README, the permission audit, and both capability maps. - Tests: definition shape, database-backed gateway reads, writes, deletes, and sandbox commands for personal and shared grants, default and per-call metros, rejection of unpublished metros and traversal, Off policies, revocation, stale-contract blocking, credential export denial, schema validation for all actions, pinned-transport tests for GET and DELETE bodies, and a browser setup check. ## Verification - `pnpm exec vitest run packages/shared/src server/src/__tests__/unikraft-connection.test.ts server/src/__tests__/unikraft-http-boundary.test.ts server/src/__tests__/daytona-connection.test.ts server/src/__tests__/daytona-http-boundary.test.ts server/src/__tests__/tool-access-service.test.ts server/src/__tests__/tool-gateway-service.test.ts server/src/__tests__/tool-gateway.test.ts ui/src/pages/apps/AppsConnect.test.tsx ui/src/pages/apps/Browse.test.tsx ui/src/lib/app-brand-assets.test.ts` plus `connector-tool-policy` and `tool-catalog-publication`: all passed after the rebase onto the split tool-access modules. - `node --test scripts/generate-unikraft-tools.test.mjs scripts/generate-daytona-tools.test.mjs scripts/app-brand-validation.test.mjs`: 20 passed. - `node scripts/check-app-brand-assets.mjs`, `node scripts/check-maps.mjs`, and `git diff --check`: passed. - `pnpm --filter @paperclipai/shared typecheck`, `pnpm --filter @paperclipai/server typecheck`, and `pnpm --filter @paperclipai/ui typecheck`: clean. - `npx playwright test --config tests/e2e/playwright.config.ts tests/e2e/unikraft-connector.spec.ts tests/e2e/daytona-connector.spec.ts`: 2 passed. - `node scripts/generate-unikraft-tools.mjs` regenerates the committed catalog with the recorded hashes. - Manual: on a local instance, open Connectors, search for Unikraft, and select **Add key**. Confirm the icon, the password field, the key guidance, and the default metro select under **Change**. - Not verified: a real Unikraft account. Live provider read and write proof is pending. ## Risks - A Unikraft token acts for the whole organization in every metro. Unikraft offers no narrower token permissions. Assign only trusted agents and review action permissions. - Sandbox actions run arbitrary commands inside the selected instance. They are classified as destructive. - A timed-out write can still complete at the provider. The bridge does not retry writes automatically. - New metros fail closed until the specification is regenerated and reviewed. Legacy `*.kraft.cloud` hosts are not reachable. - The Daytona refactor moves code without behavior changes. All Daytona tests pass without edits. - The generated JSON snapshot is large because it holds the provider input contracts. No migration or lockfile change is required. ## Model Used - Claude Opus 5.5 (Anthropic), model ID `claude-opus-5-5`, 1M context window, used through Claude Code with tool use (shell, file editing, web research, browser tests). ## 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 - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge
14 KiB
Tool connection permission audit — 2026-09-30
This review covers 119 tool methods (85 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.
Methods reviewed after this audit carry their own reviewedAt date in the same
ledger; the counts above are not restated. Later additions: Neon
(mcp-oauth, mcp-api-key; 2026-10-02), Superagent
(mcp-api-key; 2026-10-06), Gauge
(mcp-oauth, mcp-api-key; 2026-10-08), Ditto
(mcp-oauth, mcp-api-key; 2026-10-10), Unikraft
(api-token; 2026-10-15).
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.