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
8.0 KiB
App access, action permissions, and testing — agent access
Product map: App access, action permissions, and testing.
Feature ID: app-permissions.
Review date: 2026-10-12. Source commit: f981fa3cc10cb8663a87dec60345fbff46d54d0a.
This is a source-reviewed baseline of representative operations and known gaps. Each capability needs operation-level review before its entire scope can be qualified. No live agent execution is claimed. Follow the map contract for format, permission checks, evidence and maintenance.
agent-access
Capability ID: app-permissions/agent-access.
Review: baseline.
API: present — representative operation IDs:
PUT /api/tool-connections/{connectionId}/installs.
Agent access: restricted — Board management API; agents use their resulting assigned
app tools.
Policy: Connection/profile/policy management routes require a board user; tool use separately evaluates agent grants and action policies.
Evidence: source-only — implementation
at the reviewed commit above.
Verification: not-run — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: Granting access is distinct from using access. No equivalent agent management path exists in these routes.
The owning lifecycle plugin can read bounded standing connection and active
profile assignments with ctx.agents.getRuntime. It requires the existing
agents.lifecycle.manage capability and agent ownership checks. Committed
assignment changes use the opt-in agent_runtime stream. These inputs contain
no grant credentials and do not authorize a task's tool calls. See the
runtime contract.
action-policy
Capability ID: app-permissions/action-policy.
Review: baseline.
API: present — representative operation IDs:
POST /api/tool-profiles/{profileId}/entries.
Agent access: restricted — Board management API; agent execution follows
off/ask/allowed.
Policy: Connection/profile/policy management routes require a board user; tool use separately evaluates agent grants and action policies.
Evidence: source-only — implementation
at the reviewed commit above.
Verification: not-run — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: An agent cannot authorize itself by editing the policy. Decide whether any explicitly delegated administration should be supported.
Braintrust's reviewed classifier treats retrieval as read, dataset row edits and
automation-status changes as destructive, and other mutations, billable
execution, and unknown tools as write. Provider hints cannot lower a reviewed
mutation's risk. The classifier grants no authority: shared Allowed defaults
and explicit Off/Ask-first policies still govern each agent's actual run-bound
call. See Braintrust.
Live US OAuth bounded reads and a synthetic dataset insert/readback passed
through actual process-agent runs and run-scoped gateway sessions; local removal
then denied further use. This does not establish live Off/Ask-first policy
behavior, which is covered with provider fixtures. US API-key and both EU
methods remain not-run against real accounts; board Test calls do not
establish agent execution evidence.
catalog-change
Capability ID: app-permissions/catalog-change.
Review: baseline.
API: present — representative operation IDs:
POST /api/tool-profiles/{profileId}/new-tools/review.
Agent access: restricted — Board catalog-review API; agents can discover authorized
tools.
Policy: Connection/profile/policy management routes require a board user; tool use separately evaluates agent grants and action policies.
Evidence: source-only — implementation
at the reviewed commit above.
Verification: not-run — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: Catalog refresh/review and quarantined-action enablement are management operations.
Braintrust enables changed-tool quarantine after initial discovery and preserves it through reconnect and refresh. Agents cannot approve newly quarantined tools or bypass a changed schema by reusing its old name. Verify the quarantined call denial through a real run-scoped gateway separately from board catalog review; the provider qualification record records live US OAuth catalog refresh and reconnect preserving the regional method and quarantine setting. Live changed-tool denial remains outstanding; fixtures cover that denial and policy preservation across refresh/reconnect. US API-key and both EU methods have no account-bound qualification. Live token expiry/refresh, remote OAuth revocation, and native CLI automatic capability delivery also remain unqualified.
Daytona also checks its deployed native contract on the board's
GET /api/tool-connections/{connectionId}/catalog. A changed saved catalog
refreshes under the viewing human's credential context. Retired tools are
hidden even if refresh fails. Agent discovery and dispatch reject retired names
and stale same-name contracts before refresh; new/changed tools stay quarantined until reviewed. The
database-backed Daytona fixtures
exercise this boundary through real run-bound gateway sessions with fixture
provider responses. They do not qualify a live Daytona account or agent model.
Unikraft uses the same native-catalog contract: stale same-name saved entries are rejected before refresh and new or changed actions stay quarantined. Its database-backed fixtures cover this through real run-bound gateway sessions with fixture provider responses, not a live Unikraft account.
test-action
Capability ID: app-permissions/test-action.
Review: baseline.
API: present — representative operation IDs:
POST /api/tool-connections/{connectionId}/test-calls.
Agent access: restricted — Board test-as-agent API; agent executes its own assigned
tools normally.
Policy: Connection/profile/policy management routes require a board user; tool use separately evaluates agent grants and action policies.
Evidence: source-only — implementation
at the reviewed commit above.
Verification: not-run — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: A board test performed as an agent is not proof the agent can manage or invoke the testing endpoint.
account-maintenance
Capability ID: app-permissions/account-maintenance.
Review: baseline.
API: present — representative operation IDs:
POST /api/tool-connections/{connectionId}/reconnect.GET /api/tool-connections/{connectionId}/activity.
Agent access: restricted — Board account management; native
connections_search/connection_request can request human setup.
Policy: Connection/profile/policy management routes require a board user; tool use separately evaluates agent grants and action policies.
Evidence: source-only — implementation
at the reviewed commit above.
Verification: not-run — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: Agent requests and continued tool use exist; reconnect/revoke/audit management are human paths.