mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-07 07:23:08 +02:00
DottaandPaperclip
7e00f67138
## Thinking Path > - Paperclip is the open source control plane people use to manage AI-agent companies and their governed access to external systems. > - Connected Apps build on the existing Apps and MCP gateway substrate so companies can configure reusable, auditable integrations. > - The current connection record does not yet have a stable public address, explicit ownership/auth method fields, or subject-specific credential grants. > - Without that schema core, later OAuth, per-user authorization, token brokering, triggers, and connector-service phases cannot enforce tenant and subject boundaries consistently. > - This pull request adds the forward-compatible Connections v3 schema core while preserving the existing connection lifecycle and directly migrating the remote MCP transport name. > - The benefit is a company-scoped, least-privilege foundation for one-click integrations without bypassing Paperclip secrets, profiles, rules, or audit controls. ## Linked Issues or Issue Description No matching public issue was found. **Problem** Paperclip's current app connections need a durable identity and authorization substrate before Connected Apps can safely support multiple setup methods, per-user credentials, provider tenants, and managed connector services. The existing schema only models a single connection-level credential set and uses legacy transport terminology. **Proposed solution** Add a stable company-scoped connection UID, explicit ownership/auth/transport fields, a subject-aware `connection_grants` table, and multi-key credential annotations. Backfill existing connections and workspace grants in a reversible migration, then update shared/server/UI contracts to the new `mcp_remote` transport name. **Related work** - Related foundation: #9534 - Roadmap: Connected Apps (one-click integrations) ## What Changed - Added company-scoped connection `uid`, `ownership`, `authKind`, and canonical transport fields across database, shared contracts, validators, services, and UI fixtures. - Added `connection_grants` with workspace/user subject rules, provider tenant metadata, credential secret refs, revocation state, company scoping, and uniqueness constraints. - Added migration `0182_connections_v3_schema_core` to backfill stable UIDs, rename `remote_http` to `mcp_remote`, infer auth kinds, create default workspace grants, and support rollback coverage. - Added multi-key credential annotations and updated gateway/access services without changing the existing lifecycle behavior. - Updated the connection glossary, connector playbook, and security threat model for the new identity, grant, and relay boundaries. - Added explicit test UIDs to direct database fixtures so the new non-null invariant is exercised across affected server suites. ## Verification - `pnpm --filter @paperclipai/shared typecheck` - `pnpm --filter @paperclipai/db typecheck` - `pnpm --filter @paperclipai/server typecheck` - `pnpm --filter @paperclipai/ui typecheck` - `pnpm exec vitest run server/src/__tests__/tool-access-service.test.ts server/src/__tests__/tool-gateway-service.test.ts server/src/__tests__/tool-gateway.test.ts server/src/__tests__/heartbeat-runtime-skills.test.ts server/src/__tests__/tool-oauth-legacy-backfill.test.ts server/src/__tests__/tool-access-policy-service.test.ts server/src/__tests__/heartbeat-runtime-mcp-servers.test.ts packages/db/src/connections-v3-schema-core-migration.test.ts packages/shared/src/validators/tool-access.test.ts --config vitest.config.ts` — 9 files, 218 tests passed. - Latest-head GitHub Actions: build, typecheck, general/serialized suites, backup/worktree restore coverage, both e2e shards, canary, policy, and security scans pass. - Greptile: 5/5 with zero unresolved threads. - `pnpm check:token-gates` remains red only on five pre-existing `#9627` color literals outside this change. ## Risks - **Migration risk:** UID backfill and default-grant creation touch every existing connection. The migration uses company-scoped uniqueness, deterministic legacy UIDs with ID suffixes, and seeded up/rollback coverage. - **Authorization risk:** Grant rows carry credential references. Constraints enforce workspace-vs-user subject shape, company/connection lookup indexes, one default grant per connection, and one user grant per connection/subject. Security review is requested specifically for this design. - **Compatibility risk:** `remote_http` is renamed directly to `mcp_remote`; all repository call sites and fixtures are updated in the same change. - **Future-phase risk:** Subject-bound token issuance, triggers, and connector-service relay verification remain fail-closed requirements documented for later phases; this PR does not expose those capabilities. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used OpenAI Codex CLI coding agent. The runtime did not expose an exact underlying model ID or context-window size; capabilities used include repository inspection, code editing, shell execution, test execution, Git/GitHub CLI operations, and structured reasoning. ## 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>
82 lines
4.6 KiB
Markdown
82 lines
4.6 KiB
Markdown
# Connections Glossary
|
|
|
|
Audience: engineers, designers, and agents writing integration code, plans, or
|
|
product copy on the Apps v2 substrate.
|
|
|
|
Source: the accepted vocabulary table from the [PAP-13211](/PAP/issues/PAP-13211)
|
|
plan. Treat these definitions as product law when translating old Connections
|
|
v1, plugin, skill, MCP, and gateway language onto Apps v2.
|
|
|
|
## Canonical Vocabulary
|
|
|
|
| Term | Definition | It is NOT |
|
|
| --- | --- | --- |
|
|
| App | Catalog entry for an external or first-party system: metadata, supported transports, auth modes, and action catalog. The unit of the store. | A running thing; a plugin. |
|
|
| AppDefinition | Versioned, data-only authoring record for an App: identity, copy, supported methods, ownership options, fields, and setup guidance. | A company connection or executable plugin. |
|
|
| Connection | A configured, credentialed instance of an app for this company, possibly per-user account. Carries status and health. | A plugin install; an MCP server config file. |
|
|
| uid | Stable company-scoped connection address in `{namespace}/{slug}` form. | A database UUID or display name. |
|
|
| Ownership | Who supplies and controls the OAuth client: platform-shared, platform-provisioned, customer, or DCR. | Connection kind or credential ownership. |
|
|
| Subject | The app/workspace or Paperclip user on whose behalf a credential is requested. | The calling agent. |
|
|
| Grant | Credential-bearing authorization for one connection subject and provider tenant. | A profile, rule, or permission bypass. |
|
|
| Trigger | Provider-origin event definition that starts governed Paperclip work. | An unauthenticated webhook handler. |
|
|
| Connector service | Paperclip-operated relay for managed OAuth callbacks, credential custody, and webhook intake at `connect.paperclip.ing`. | Paperclip ID or the per-company broker. |
|
|
| Action / Tool | One invokable capability of a connection, risk-classified and quarantined when new or changed. | A free-form shell command or permission grant. |
|
|
| Profile | Curated allowlist of actions bound to a scope such as company, project, agent, routine, or issue. | A permission system of its own. |
|
|
| Rule | Allow, ask-first, or block per action. Ask-first lands in the Review queue. | A profile or catalog entry. |
|
|
| Gateway | Named inbound MCP endpoint exposing curated connections/tools to external clients under a scoped bearer token. Reuses profiles and rules. | A new permission model. |
|
|
| Plugin | Code extension package: workers, UI, migrations. May declare apps/providers and provision skills. Packaging, not governance. | An integration per se. |
|
|
| Skill | Instructions an agent follows. May use connections; must not own tokens. | A token store. |
|
|
| MCP | A wire protocol; one transport apps may support. | A product category. |
|
|
| Broker | The run-time service that turns a stored credential plus a grant into a short-lived, downscoped, attributed token. | A vault or a permission model. |
|
|
|
|
## Product Copy Defaults
|
|
|
|
Use these words in prosumer surfaces:
|
|
|
|
- app
|
|
- connect
|
|
- connection
|
|
- allowed
|
|
- ask-first
|
|
- review
|
|
|
|
Keep protocol and implementation terms behind Developer or Advanced surfaces:
|
|
|
|
- MCP
|
|
- stdio
|
|
- gateway
|
|
- plugin
|
|
- manifest
|
|
- DCR
|
|
- PKCE
|
|
- schema hash
|
|
- bearer token
|
|
- secret ref
|
|
|
|
## Apps v2 Object Mapping
|
|
|
|
| Vocabulary term | Apps v2 object or surface |
|
|
| --- | --- |
|
|
| App | `tool_applications`, provider gallery cards, app detail metadata. |
|
|
| AppDefinition | Catalog registry source used to author and seed Apps and setup methods. |
|
|
| Connection | `tool_connections`, connection detail status/health, setup/configure flows. |
|
|
| Grant | `connection_grants`, provider tenant and subject-specific credential refs. |
|
|
| Action / Tool | Catalog entries discovered from MCP/OpenAPI/vendor wrappers. |
|
|
| Profile | Access profiles and bindings. |
|
|
| Rule | Policy rules such as allow, ask-first, block, rate limit, and trust rules. |
|
|
| Gateway | Inbound MCP gateway sessions and scoped client tokens. |
|
|
| Plugin | Extension packaging that may declare apps but does not bypass governance. |
|
|
| Skill | Agent instruction package that calls governed connections through Paperclip. |
|
|
| MCP | Transport option for apps and gateways. |
|
|
| Broker | Credential resolver/token broker path over `company_secrets`. |
|
|
|
|
## Translation Rules
|
|
|
|
- MCP is a transport, not the information architecture.
|
|
- A plugin may bundle an app, but governance always flows through the connection,
|
|
profile, rule, broker, and audit model.
|
|
- A skill may use Slack, Google Drive, Ramp, or another vendor, but the durable
|
|
credential belongs in `company_secrets` and is reached through a connection.
|
|
- Inbound clients use scoped Paperclip auth; outbound vendor calls use the Apps
|
|
v2 connection governance stack.
|