Jannik/PaperClipAI
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip.git synced 2026-11-01 23:43:16 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
d6dfbb495db44b60faa37416675e8ffbb9cc10d0
PaperClipAI/doc/connections/README.md
T
DottaandPaperclip 4d90634f74 feat(connections): add 1Password service-account connector (#17249) 
## Thinking Path

> - Paperclip lets people manage AI agents and govern their access to
outside services.
> - Apps connections keep provider credentials in the instance vault and
mediate every action through grants, policies, and audit.
> - Agents currently have no Apps connection for reading or managing
1Password items with an operator-supplied service-account token.
> - 1Password supports this through its official SDK; its documentation
MCP server does not expose vault operations.
> - This pull request adds a one-field service-account connection and
registers eight reviewed SDK actions through the existing
native-provider catalog.
> - Operators can select vault permissions in 1Password and agent/action
access in Paperclip without installing a CLI or handing durable
credentials to agents.

## Linked Issues or Issue Description

Related: #16144 adds 1Password as Paperclip's secret-storage backend.
This PR adds the separate Apps/tool-access flow with a per-connection
credential; it does not change secret providers or use a server-wide
ambient token.

**Subsystem affected**
Apps catalog, native tool-provider registry, and shared connection
setup.

**Problem or motivation**
People need to paste their own `OP_SERVICE_ACCOUNT_TOKEN`, find official
service-account setup instructions, and authorize agents to use the
selected vaults through ordinary Paperclip governance.

**Proposed solution**
Add `1password/service-account`, with a password field labeled **Paste
your 1Password Service Account token** and a link to [1Password's
creation
instructions](https://www.1password.dev/service-accounts/get-started#create-a-service-account).
Use the pinned official `@1password/sdk` 0.5.0 for vault/item listing,
item and secret-reference reads, and item create/update/archive/delete.

**Alternatives considered**
A remote MCP card would not provide vault access. A local CLI or a
third-party MCP package adds installation and credential surfaces that
the official SDK avoids.

## What Changed

- Added the source and generated catalog definition, permission review,
official light/dark artwork, documentation, and capability-map
references.
- Added a provider-owned SDK bridge with strict schemas, account-domain
validation, contract hashes, fixed errors, bounded output, and
disposable workers with cancellation/deadlines.
- Registered the provider through master's native-provider catalog;
existing setup, health, discovery, gateway, policy, and audit owners
remain in place.
- Labeled the single password field **Paste your 1Password Service
Account token**. The shared formatter preserves explicit credential
prompts; ordinary key labels retain their existing presentation.
- Added credential-ownership, gateway read/write, policy/revocation,
worker, setup UI, and interactive Storybook coverage.

## Verification

- Final review follow-up: added two deterministic worker-entry tests for
nested exact-token redaction and oversized-output rejection. Removing
each guard caused exactly its regression test to fail. The focused
provider suite passed **15 tests**, and the official server typecheck
passed after rebuilding stale workspace SDK artifacts. Current head
`569cb7f9bd57db791fb13a6034ce69bf50878cb1` passed the full [CI
run](https://github.com/paperclipai/paperclip/actions/runs/40016166260),
including typecheck, build, unit/integration tests, and all eight
browser shards. The required `ci / verify` and `ci / e2e` gates passed.
[Greptile](https://github.com/paperclipai/paperclip/pull/17249#issuecomment-6353731805)
and [Paperclip
Review](https://github.com/paperclipai/paperclip/pull/17249#issuecomment-6372165895)
each rated this exact head **5/5**, with no open findings. Paperclip
Review completed with a neutral check because its scoped reviewer could
not inspect CI; the full CI result was verified separately. Other
neutral checks and intentionally skipped Storybook jobs contain no
actionable findings.
- CI recovery on the same commit: the first attempt lost six jobs. Five
logged simultaneous runner shutdowns at 18:49 UTC on 2026-10-23; the
sixth stopped logging before a test result and its root cause was not
established. No assertion failure appeared in the retrieved logs. All
six jobs and the aggregate gates passed one failed-job retry. [CI
run](https://github.com/paperclipai/paperclip/actions/runs/40005754936).
- Copy follow-up: the catalog, provider, and setup UI suites passed
**275 tests**. The governed gateway lifecycle passed **3 tests** (one
live-only test skipped), including create, update, archive, and delete.
UI token gates and map checks passed. The branch was rebased onto
`9c442cf48e` to resolve additive catalog conflicts while retaining the
Vercel and Supabase entries. The existing live write proof below remains
applicable; this follow-up changes presentation only.
- Five affected suites, including the existing Daytona consumer, passed
**290 tests** (one opt-in live test skipped in fixture mode). Full `pnpm
-r typecheck` and `pnpm build` passed. The local broad-suite attempt
could not complete because PostgreSQL semaphore exhaustion prevented a
competing integration suite from starting; the complete affected-file
retry passed after disposable-process cleanup. The prior commit
`f208a8aff6dc28859cc3f343497e18d85f124579` passed the complete CI
matrix. All CI build, typecheck, test, and browser gates also passed on
the earlier commit `9e2f3d3140368a08da43b004b2e8d3a0f4c0fa4d`. The
separate Paperclip Review reported a worker-result regression-test gap
on that head; the follow-up above addresses it. Its review thread is
resolved, and both fresh current-head reviews are clean as recorded
above.
- Token gates, module boundaries, brand validation, map checks, and
Storybook catalog checks passed.
- Direct SDK create/archive/delete and rejected-call coverage passed (13
provider tests); the Storybook Permissions/Test play completed
successfully in Chromium. Server and UI typechecks passed after those
fixes. Greptile passed prior commit
`9e2f3d3140368a08da43b004b2e8d3a0f4c0fa4d` at **5/5**. Both reviewers
also passed the worker-test follow-up at **5/5** as recorded above.
- Live 1Password proof on 2026-10-22: connect, eight-action discovery,
vault listing through an actual run-scoped gateway, refresh, reconnect
preserving identity, another read, removal, and denial through the
retained session passed. Credential absence was asserted in
responses/audit; an exact-token scan of inspected logs and changed files
passed.
- Real browser: Connectors → 1Password → token entry → personal access
limited to one disposable agent → completion → Permissions → Test
`onepassword_list_vaults` succeeded. The disposable connection was
removed afterward.
- Compiled-worker smoke initially exposed inherited Node launch flags.
Workers now use explicit empty `execArgv`; the compiled worker then
authenticated successfully and listed one vault.
- Live write proof on **2026-10-23**: the replacement Keychain token
passed all eight actions through the actual run-scoped gateway for both
personal and shared credentials. The test created, listed, read,
updated, resolved a secret from, archived, and deleted two synthetic
items. Both were absent from subsequent item lists. Refresh/reconnect,
identity preservation, removal, retained-session denial, and credential
absence passed. The live suite passed **3 tests** (one fixture-only test
skipped) in 116.65 seconds. The expanded fixture suite passed **3
tests** (one live-only test skipped); the 13 provider tests and server
typecheck passed. An exact-token scan passed over 64 source/log files.
- Failure history: the original token denied creation on 2026-10-22 and
created no item. The first 2026-10-23 attempt stopped before provider
calls because host PostgreSQL semaphore limits prevented test-database
startup. A temporary ten-connection test profile allowed the complete
retry to pass without changing shared services or host limits. A new
delete-result assertion also exposed an outdated fixture response
(`success` instead of `deleted`); the fixture was corrected and the
complete fixture suite passed.

Official contract sources: [service
accounts](https://www.1password.dev/service-accounts/get-started),
[SDKs](https://www.1password.dev/sdks), [item
management](https://www.1password.dev/sdks/manage-items), [official
JavaScript SDK](https://github.com/1Password/onepassword-sdk-js).

## Risks

- Authorized item/secret reads intentionally return secret values to the
agent and ordinary tool-result history. Select trusted agents and use
restricted service-account vaults; the connection token itself is
redacted.
- New connections retain existing Paperclip action defaults, including
Allowed writes/destructive actions for selected agents. 1Password still
enforces the token's permissions.
- Service-account access cannot be changed in place. Create a
replacement account and reconnect to change vault permissions; read-only
keys can connect but cannot write.
- SDK authentication happens per action in a disposable worker. Calls
have a 30-second maximum; cancellation stops local work, while a
mutation already accepted by 1Password can still finish. Writes are
never automatically retried.
- Additive dependency and catalog change; no database migration.
Disable/remove the connection to withdraw access, or remove the provider
from catalog visibility for rollback.

## Model Used

OpenAI Codex, based on GPT-6, with code editing, shell/browser tools,
and live provider verification. A more specific runtime model ID and
context-window limit 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>
2026-10-23 13:27:33 -07:00

213 lines
11 KiB
Markdown
Raw Blame History

# Apps, Connections, and Integrations
Audience: internal engineers and product contributors working on integrations.
Start here when adding a provider:
[Connection authoring runbook](./CONNECTOR-PLAYBOOK.md). It is the canonical
agent tutorial from provider research and protocol classification through
manifest generation, branding, secrets, deterministic tests, real-account
proof, and PR submission.
Runtime authentication: [AI Connections](./AI-CONNECTIONS.md).
Long-term memory: [Experimental memory connectors](./MEMORY.md).
Provider notes: [Google Workspace](./GOOGLE-WORKSPACE.md),
[Gmail](./GMAIL.md), [Asana](./ASANA.md), [Sentry](./SENTRY.md), [PostHog](./POSTHOG.md), [Braintrust](./BRAINTRUST.md), [Neon](./NEON.md), [Superagent](./SUPERAGENT.md), [Gauge](./GAUGE.md), [Ditto](./DITTO.md),
[1Password](./1PASSWORD.md), [Unikraft](./UNIKRAFT.md), [AgentMail](./AGENTMAIL.md), [Telem.AI](./TELEM.md), [iMessage Photon](./IMESSAGE-PHOTON.md),
[Enterpret](./ENTERPRET.md), [Supabase](./SUPABASE.md), and
[Vercel](./vercel.md). Optional credential custody:
[Vercel Connect](./VERCEL-CONNECT.md).
Post-read action: classify a new integration request, pick the right Paperclip
layer to change, and avoid creating a parallel connection framework.
## Decision Record
Board decisions from [PAP-13211](/PAP/issues/PAP-13211) make the Apps v2
substrate on the PAP-10341 branch canonical:
- **D1: Apps v2 is the substrate.** The active model is
`tool_applications`, `tool_connections`, catalog entries, profiles, policy
rules, action requests, gateway sessions, audit events, and runtime slots.
Connections v1 is retired as an implementation path.
- **D2: one credential authority per connection, brokered projections.** The
default is the Paperclip instance vault: durable third-party credentials live
in `company_secrets` as secret refs. A reviewed remote MCP method may instead
opt in to [Vercel Connect](./VERCEL-CONNECT.md), in which case Vercel is the
durable credential authority and Paperclip stores only the connector reference
and redacted grant metadata. A connection must never mix those two sources.
Adapter config, plugin config, harness credential files, and run environments
may receive only brokered or projected credentials.
- **D3: the vocabulary and three-door IA are product law.** The default product
doors are Apps, Connections, and Review. Protocol and operator-depth concepts
live behind Developer or Advanced surfaces.
- **D4: unification lands on PAP-10341.** Pages, CircleBack-style harness MCP
OAuth, provider gallery work, and plugin-provided integrations converge on
this branch instead of spawning new integration substrates.
- **D5: inbound stays thin.** External clients that call Paperclip use scoped
Paperclip tokens and existing profiles/rules. They do not get a separate
permission model.
## Canonical Object Model
Use **connection** as the unifying noun. A connection is four things:
1. A stored credential reference.
2. A capability catalog.
3. A governance layer.
4. An audit trail.
Everything else is an axis on that object:
| Axis | Values | It answers |
| --- | --- | --- |
| Direction | outbound, inbound | Who is the client? |
| Transport | MCP, native REST/OpenAPI, OAuth app install, webhook | How do bytes move? |
| Auth mode | OAuth, API key/PAT, app installation, none | What does the secret represent? |
| Credential owner | company, user, run | Whose identity acts? |
| Packaging | catalog entry, plugin, skill | How does it ship? |
MCP is a transport, not a product category. "Install the Discord app",
"connect Google Drive", and "add an MCP endpoint" all produce governed
connections with different transport/auth values.
## Layer Stack
When you are unsure where a change belongs, place it on the narrowest layer that
solves the problem:
| Layer | Owns | Examples |
| --- | --- | --- |
| Surface | user-facing Apps, Connections, Review, Developer/Advanced screens | gallery cards, setup wizard, review queue |
| Governance | profiles, bindings, allow/ask-first/block rules, quarantine, audit | read-only profile, ask-first write policy |
| Capability | action catalogs, schemas, risk classes, changed-tool review | `search_issues`, `create_comment`, schema hash |
| Credential | `company_secrets`, OAuth broker, credential resolver, token broker | Slack bot token ref, Google OAuth refresh token ref |
| Identity | actor attribution and token exchange | board user, agent run, first-party service identity |
| Transport | how the external system is reached | remote HTTP MCP, local stdio, REST/OpenAPI, webhook |
The agent should not hold a durable provider credential. It should hold a
Paperclip run/session token; the server or broker resolves the connection,
checks governance, invokes the provider, and writes audit.
## Identity vs. connections
Signing a user *in* and connecting a *resource* are different planes with
different owners, different token profiles, and different homes. Do not merge
them. This section is the public, connections-side statement of the identity
model so connector implementers inherit the rule without depending on private
identity-service documentation or re-deriving it.
| Plane | Question | Lives where | Token profile |
| --- | --- | --- | --- |
| **P1. Sign-in methods** | *Who are you?* | `paperclip-id` (id.paperclip.ing → Account) | Minimal-scope provider tokens (`openid email profile`), used once to authenticate, encrypted at rest, never exported |
| **P2. Connections (Apps)** | *What may your agents touch?* | Paperclip App instances (`tool_connections`), acquired via the **connect broker** for hosted + self-hosted | Rich-scope, long-lived resource tokens in the **instance's** encrypted vault; per-agent grants; risk-tier policy defaults |
| **P3. Login with Paperclip** | *Who may authenticate against us?* | `paperclip-id` OIDC provider + DB-backed client registry | Our ES256 ID/access tokens issued *by* us to registered RPs (instances, the broker, future third parties) |
Everything in `doc/connections/` — the [First-30 matrix](./FIRST-30-MATRIX.md),
the [connection authoring runbook](./CONNECTOR-PLAYBOOK.md), and the connect-broker work —
lives on **plane P2**. It never acquires, stores, or brokers a P1 sign-in token.
### The standing rule (D7)
Adopted as a standing rule (decision D7) with the identity-model plan. State it
verbatim in any P2 design so the app-store work cannot drift into merging the
planes:
> Sign-in tokens are never reused as resource tokens; id.paperclip.ing never
> stores resource tokens; no connections hub on the ID service.
P2 tokens flow broker → instance vault as pass-through only; the id.paperclip.ing
Account page therefore must **not** grow a "Connections" hub. The reasons to
hold the planes apart (from the plan §3):
- **Scope discipline.** Sign-in wants the narrowest grant; connections want
deliberately broad ones. One button that does both is how you grant repo
access just to log in.
- **Blast radius.** id.paperclip.ing holding every customer's Vercel/Slack/GitHub
resource tokens would make it the single juiciest target in the fleet; the
broker is intentionally pass-through.
- **Self-hosted symmetry.** Instances own their vaults, so self-hosters don't
depend on our uptime to *use* their own connections.
- **Legibility.** Sign-in and connections answer different user questions, and
every product we benchmarked (Vercel, Railway, GitHub, Google) keeps them on
separate pages with separate names.
The explicit Vercel Connect exception does not change D7 or merge P1 and P2.
The operator chooses Vercel as the P2 credential authority for an individual
connection. `id.paperclip.ing` is not involved, and neither sign-in tokens nor
provider tokens pass through it. The deployment's Vercel access token or
workload OIDC identity is bootstrap authority for that external vault, not a
provider resource credential.
### Naming alignment
Use the surface-correct name for each plane; they intentionally differ:
| Surface | Plane | Name to use |
| --- | --- | --- |
| Paperclip App instances | P2 | **"Connections"** |
| id.paperclip.ing Account | P1 | **"Ways to sign in"** |
| id.paperclip.ing admin | P3 | **"OIDC clients"** (until the app store productizes it) |
## Packaging Rule
Default to a **catalog entry** when an integration can be described as metadata:
manifest, auth config, action catalog, resource filters, and policy defaults.
Use a **plugin** only when the integration needs product code such as custom UI
pages, its own tables, workers, migrations, routines, or specialized ingestion.
A plugin may bundle catalog entries, but it must not bypass the connection,
profile, policy, credential, and audit model.
Use a **skill** for agent instructions. Skills may use connections; they must
not own durable tokens.
## Canonical Docs
- [Glossary](./GLOSSARY.md) defines product and internal terms.
- [Identity vs. connections](#identity-vs-connections) is the public statement
of the P1/P2/P3 boundary and the D7 standing rule for connections work.
- [Security threat model](./SECURITY-THREAT-MODEL.md) harvests the keeper from
[PAP-2359](/PAP/issues/PAP-2359) and maps it onto Apps v2.
- [First-30 matrix](./FIRST-30-MATRIX.md) harvests the keeper from
[PAP-2432](/PAP/issues/PAP-2432) and is the source matrix for connector
playbook work.
- [Connecting any remote MCP server](./GENERIC-REMOTE-MCP.md) is the baseline:
how an operator connects a standards-compliant remote MCP endpoint with no
Paperclip code change, and how sign-in resolves a client.
- [Connection authoring runbook](./CONNECTOR-PLAYBOOK.md) is the one
end-to-end, agent-executable guide for adding a vendor as a catalog entry on
Apps v2: research, connection-type selection, OAuth/API-key/generated-URL
setup, encrypted credential handling, branding, implementation, browser and
live-provider testing, verification, and PR submission.
- [Vercel Connect operator guide](./VERCEL-CONNECT.md) documents the optional
external credential source, deployment flags, runtime resolution, recovery,
and smoke requirements.
- [MCP access governance](../MCP-ACCESS-GOVERNANCE.md) remains the operator
runbook for the current gateway, profile, policy, approval, runtime, and audit
APIs.
## Migration Notes
Connections v1 contributed useful policy, UX, and rollout thinking, but its
implementation branch is no longer the target. When you see old tickets or code
using `connections`, `connection_grants`, or a provider-directory mental model,
translate the intent into Apps v2:
| Connections v1 intent | Apps v2 home |
| --- | --- |
| Provider directory | Apps gallery / `tool_applications` |
| Configured provider instance | Connection / `tool_connections` |
| Grant allowlist | Profiles, profile bindings, policies |
| Resource filters | Policy/profile conditions plus provider config |
| Tool broker | Tool gateway and runtime supervisor |
| Connection UX tail | Apps, Connections, Review, Developer/Advanced IA |
Do not add new work to the retired v1 branch. If an old ticket still describes a
valid product gap, retarget it to an active Apps v2 issue or close it as
superseded with a link to the replacement.
For Slack chat bot creation, installation, recovery, and live qualification, see
[Automatic Slack app setup](SLACK-AUTOMATIC-SETUP.md).
Reference in new issue View Git Blame Copy Permalink