Introducing a new way to review your PRs.

Read the announcement

paperclipai / paperclip

The open-source app everyone uses to manage agents at work

View on GitHub

30 documents · Updated Nov 20, 2026

docs / security-and-governance

Security and governance

Security and governance provide the control layer for Paperclip work. The system identifies users, agents, plugins, and delegated runs, then limits each action to its company, role, secret scope, tool policy, and execution trust boundary. It works with agent work management, organization work management, automation and control, the extensibility platform, and application platform operations.

Security model

Paperclip applies several checks before work can change data or reach an external system. These checks form one chain rather than separate security features.

ControlMain questionResult
IdentityWho is making the request?A board user, agent, plugin, or system actor
Company scopeWhich company may the actor access?A tenant boundary for data and actions
PermissionIs this actor allowed to perform this kind of action?A grant, role rule, or policy decision
Secret scopeMay this consumer receive this credential?A bound company secret or owner-scoped user secret
Trust boundaryHow much authority does this run have?Standard or low-trust access with a concrete scope
Tool governanceMay this exact tool call run now?Allow, deny, ask for approval, or defer
AuditCan an operator explain the decision later?Activity, access, and tool audit records

The company is the main boundary. Identity and permissions become company-scoped decisions before resource access, secret delivery, or tool execution continues.

Identity and authorization

Identity answers who is calling. Authorization answers what that identity may do in a company and on a specific resource. The request actor carries both the credential source and the context needed for later checks.

Request identity

The request layer recognizes board sessions, board API keys, agent API keys, agent JWTs, trusted local access, and trusted Cloud tenant headers. Public webhook and MCP gateway paths use their own signature or run-scoped credential checks instead of generic actor handling. Agent credentials can also carry company, run, and responsible-user context.

Board sessions use Better Auth. Agent JWTs bind a run to an agent and company. Agent API keys use stored hashes and revoked keys do not authenticate. Terminated or pending agents cannot authenticate. Cloud tenant elevation is derived from trusted request context and fails closed when its setting cannot be read.

The board session response exposes the signed-in user's profile and accessible company bootstrap data. It also exposes only the front-end Sentry data needed by the browser. It does not expose the backend DSN. Profile updates require the same board identity as profile reads.

References: server/…/auth.ts• L220-274 server/…/auth.ts• L260-435 server/…/auth.ts• L599-776 server/…/auth.ts• L16-116 server/…/board-bootstrap.ts• L6-25 server/…/better-auth.ts• L185-255 server/…/agent-auth-jwt.ts• L122-255

Company and resource access

Company access is the first resource gate after authentication. Board actors need active membership or instance authority. Agent actors stay pinned to the company in their credential. Write actions also require a non-viewer membership unless a trusted local or instance-admin path applies.

Resource lookup uses the same company check as the write path. A cross-company lookup returns the normal not-found result so resource IDs do not reveal data across companies. Private projects and issues add a narrower read boundary through implicit principals, explicit grants, and project membership. The same privacy rule applies to lists and linked resources.

Privacy checks can run in enforcement, shadow, or off mode. Shadow mode lets operators measure denials before they block access.

Read authorization can reuse the same instance-admin and membership facts during one short-lived GET or HEAD request. The scope ends with the response or after its age limit, so membership changes take effect on the next request and are not cached across requests.

References: server/…/authz.ts• L26-121 server/…/access.ts• L41-92 server/…/authorization.ts• L626-764 server/…/authorization.ts• L934-958 server/…/authorization-read-scope.ts• L4-57 server/…/access.ts• L1290-1337

Permission grants

Permission grants add action-level control inside a company. A grant belongs to a user or agent and may cover a project, agent, user, connection, or managed subtree. The authorization service checks active membership, the requested action, and the grant scope before it allows the action.

Roles provide default grants, but a role does not replace the company boundary. Assignment policy is checked across the target agent, project, issue, and parent issue. Unknown or malformed policy data fails closed for assignment. A protected change needs a direct grant, while a suggest grant needs accepted consent before it can apply the change.

Connection management is also an authorization decision. An agent cannot manage a connection without a current responsible user, and a user who supplies external authority is checked from current company membership rather than from an agent-selected identity.

References: server/…/authorization.ts• L306-447 server/…/authorization.ts• L1034-1122 server/…/authorization.ts• L1966-1985 server/…/authorization.ts• L2117-2251 server/…/authorization.ts• L2810-2929

Delegated agent actions

An agent may act for a responsible user, but delegation does not create more authority than that user has. For most agent actions, the final decision intersects the agent decision with the responsible user’s current active, non-viewer company authority. A missing user or membership fails closed.

Some actions carry a separate authorizing user. This user is checked from current company membership rather than from an agent-selected principal. Skill changes can use the agent’s explicit skill grant after the responsible user passes the active membership check. Connection management always requires an authenticated responsible user.

The responsible-user check can run in shadow mode while operators measure denials. Enforced mode blocks the action when the intersection fails. More detail is in Identity and access control.

References: server/…/authorization.ts• L2809-2907 server/…/authorization.ts• L2910-2965 server/…/authorization.ts• L2312-2370

Secrets and credentials

Secrets are managed values that may come from Paperclip or an external provider. The secret system separates ownership from use: a company secret is bound to approved consumers, while a user secret belongs to one user and is resolved through a declared or owner-scoped use.

Secret ownership and provider lifecycle

Company administrators manage secret definitions, values, versions, provider vaults, and rotations. User secret definitions describe a credential type for a company, while each user stores only their own value for that definition. A value can be stored locally or linked to a supported remote provider.

A provider supplies the value lifecycle for create, link, resolve, rotate, archive, and health checks. Provider configuration stays company-scoped. Disabled or unavailable providers cannot resolve runtime values, and a provider vault must match both the company and the secret provider.

Secret resolution records a successful access event without changing the secret row. The secrets list derives its last-used value from that event history, which keeps credential reads from changing shared secret state during concurrent work admission.

Managed login flows use fixed secret definitions and stored-session claims. They do not let a caller choose the definition shape. The Claude Code OAuth flow binds the value to its user and uses the login session as an idempotency key. Conflicting higher-priority credentials and stale rotations return fixed, non-secret errors. Successful completion is idempotent for the same login session.

References: server/…/secrets.ts• L91-125 server/…/secrets.ts• L1194-1231 server/…/secrets.ts• L1373-1472 server/…/secrets.ts• L3233-3421 server/…/secrets.ts• L3896-3924 server/…/secrets.ts• L68-117

Secret bindings and delivery

A secret reference does not grant access by itself. A binding connects a company secret to a target such as an agent, environment, plugin, or tool connection at a named configuration path. Runtime resolution checks the company, secret status, version status, binding path, target, provider, and any active trust-boundary allowlist.

Static lease bindings use a fixed target and path allowlist. A class-3 static lease fails when its allowlist key or approved path is missing. Prospective owner-scoped configuration is separate from low-trust binding enforcement and rejects an allowlist it cannot enforce.

An agent read requires a run-bound agent token, a verified active heartbeat run, a permitted path, company authorization, and a valid binding when one is expected. Each read records its consumer, actor, run, issue, provider, version, and outcome. Resolved values are registered for run-level redaction before later tool arguments, results, logs, or audit summaries can expose them.

References: server/…/secrets.ts• L805-833 server/…/secrets.ts• L1113-1192 server/…/secrets.ts• L1390-1505 server/…/secrets.ts• L1656-1819 server/…/run-secret-redaction.ts• L42-123

User-scoped credentials

User-scoped credentials resolve through a company definition and a responsible user. A persisted consumer must have a matching declaration at its configuration path. The declaration can also be limited by the active low-trust boundary.

Prospective configuration can use owner-scoped mediation when no saved declaration exists. That path does not accept allowedBindingIds, because it has no declaration check with which to enforce the list. Required definitions, active owner values, and active versions remain necessary in both modes.

The detailed credential model and flows are in Secrets and credentials.

References: server/…/secrets.ts• L4220-4309 server/…/secrets.ts• L5606-5625 server/…/secrets.ts• L5718-5882

Connection credentials

Tool connections keep organization credentials and personal credentials under separate authorization grants. The system resolves the credential for the active actor, records it as a secret access, and keeps its binding view aligned with the connection and its grants.

OAuth refresh replaces expiring values only after it has confirmed the grant, its refresh lease, and the returned permission scope. If the provider cannot prove the required scope or the refresh credential is no longer usable, the grant moves to a reconnect state instead of silently widening or keeping stale access.

References: server/…/credential-store.ts• L22-35 server/…/credential-store.ts• L58-131 server/…/grant-refresh.ts• L40-129 server/…/grant-refresh.ts• L258-365 server/…/grant-refresh.ts• L446-547

Execution trust boundaries

Execution trust describes how much authority a run receives from its source and context. The effective trust decision combines agent, project, issue, and run policy. A low-trust result stays separate from higher-trust context until a trusted actor promotes it.

Trust policy resolution

The trust resolver reads policy from the agent, project, issue, and run. A low-trust preset or boundary at any level can lower the effective trust. Boundaries intersect, so later policy cannot expand an earlier scope. Cross-company, conflicting, invalid, or unscoped boundaries produce a denial.

An explicit root-issue boundary includes that issue and its descendants. A project boundary or exact issue scope does not authorize an unrelated child only because its parent is in an allowed project. The resolved decision must contain a concrete project, root issue, or issue set before low-trust execution can proceed.

References: server/…/trust-preset-resolver.ts• L16-65 server/…/trust-preset-resolver.ts• L223-337 server/…/authorization.ts• L1185-1259 server/…/authorization.ts• L1261-1304

Low-trust execution

Low-trust work must run in an isolated workspace with a sandbox environment. The issue must remain inside the active boundary. Company-wide and privileged APIs such as secret access, runtime management, connection management, and agent configuration are denied by default.

Low-trust task creation keeps the trust policy and source-trust record that caused the restriction. Persistent instruction changes require a direct message in the authorized user’s chat with that agent. Work from tasks, subtasks, connectors, plugins, or peer agents does not inherit that authority.

References: server/…/low-trust-runtime-containment.ts• L11-105 server/…/authorization.ts• L1290-1369 server/…/authorization.ts• L2555-2583 server/…/authorization.ts• L2641-2652

Quarantined output

Output from a low-trust run is marked as quarantined source material. Higher-trust context receives a fixed placeholder instead of the body, presentation, or metadata. A trusted reviewer can inspect and promote a sanitized artifact, which records the source and promoting actor.

This boundary applies as content moves between trust levels. A low-trust comment or document does not become trusted only because it is attached to a visible issue.

References: server/…/source-trust.ts• L12-94 server/…/source-trust.ts• L97-173

More detail on runtime isolation, tool authority, and plugin limits is in Runtime and tool governance.

Tool access governance

Tools connect agents to Paperclip functions and external systems. The tool path combines connection state, profiles, policies, approvals, runtime controls, and audit records before it sends a call.

Tool profiles and calls

A tool profile describes the catalog entries that a company, agent, project, routine, issue, or gateway may use. Narrower bindings take precedence over wider bindings. The effective profile resolver checks the company and agent, keeps only active profiles, and turns matching catalog entries into the tools and connections available to that agent. A profile can allow selected tools or allow all tools except explicit exclusions.

Connection installs decide where a connection is exposed. They do not grant every action on that connection. Profile entries select the catalog actions, and new or changed actions can remain pending until an authorized reviewer allows them. Assignment changes use the same company and agent checks as other tool access changes.

Reviewed connector policy supplies a shared risk classification and new-entry quarantine rule for known providers. It selects the policy by source and, where needed, by the exact connection endpoint. A connector definition can carry the same reviewed policy even when its provider code comes from a plugin. This keeps risk review consistent wherever the connector is installed without granting the connector a new execution path.

Tool policies can match the actor, work context, connection, tool, risk, credential scope, trust boundary, argument fields, time window, or rate bucket. Destructive calls require formal approval. Write calls may also pause under an ask-first policy. The approval records a signed view of the tool name, canonical arguments, and relevant policy state before live checks permit execution.

Connection review data gives an authorized reader a narrow view of pending signed action requests and quarantined catalog entries. Archived connections report zero for both counts. The route keeps company admission separate from the aggregate query, so a hidden or foreign connection is not summarized.

The gateway flow is:

flowchart LR
    A[Authenticated actor] --> B[Run and company context]
    B --> C[Gateway session or token]
    C --> D[Catalog and connection checks]
    D --> E[Profile and policy decision]
    E -->|deny| F[Blocked and audited]
    E -->|ask first| G[Human approval]
    E -->|allow| H[Runtime execution]
    G -->|approved| H
    H --> I[Redacted result and audit]

References: server/…/tool-policy.ts• L26-89 server/…/tool-access-policy.ts• L328-529 server/…/tool-access.ts• L1069-1497 server/…/resolution.ts• L66-188 server/…/resolution.ts• L190-260 server/…/installs.ts• L105-143 server/…/service.ts• L104-243 server/…/review-counts.ts• L5-32 server/…/tool-access.ts• L1924-1930 server/…/tool-gateway.ts• L149-230 server/…/tool-gateway.ts• L1463-1556

OAuth authorization

OAuth authorization gives a connection a provider credential without making the provider or its metadata a trusted source. Discovery accepts only safe endpoint addresses and keeps the authorization server issuer bound to the connection. The resulting token carries the MCP resource audience when the provider supports it.

The sign-in flow uses a short-lived, actor-bound state and PKCE. Redirects must use HTTPS or a loopback HTTP origin. Dynamic client registration accepts only bounded metadata that keeps the requested redirect, grant, and response types. Client ID metadata documents expose one legal callback for the Paperclip deployment.

The callback consumes state before it handles success or denial. It checks the callback issuer, redirect rules, code verifier, actor binding, company membership, and requested scope before it stores a personal or organization grant. A provider response cannot widen a curated scope set, and a failed refresh sends the grant to reconnect instead of preserving uncertain access.

When an agent starts authorization for a person, Paperclip creates a human-only confirmation request. The agent receives a handoff rather than provider credentials, so the person remains the actor who consents to the external access.

References: server/…/authorization-constraints.ts• L8-79 server/…/authorization-start.ts• L442-555 server/…/authorization-start.ts• L557-728 server/…/direct-callback.ts• L57-167 server/…/discovery.ts• L66-214 server/…/client.ts• L147-296 server/…/client-metadata.ts• L9-93

Catalog discovery and health

The tool catalog is the governed view of actions that a connection can currently support. Discovery checks the connection method, credentials, permission scope, protocol, and remote response. Health checks turn that result into a connection state and an audit record.

Discovery uses the active actor’s credential grant. A narrower personal or service grant cannot be combined with another grant to create broader authority. Google Workspace services are filtered by the current grant, and a service outage leaves other verified services available rather than publishing actions from a stale permission snapshot.

Remote MCP discovery negotiates the protocol and session mode, follows bounded pagination, and caches only within the server’s stated freshness and privacy scope. The negotiated mode is saved only if the connection still points to the same endpoint. Health checks bypass the tool-list cache so a connection state reflects a live probe.

Catalog refresh reconciles discovered actions with the existing catalog. Removed actions become unavailable. New or changed actions can stay quarantined for review before a profile can expose them. Provider-specific limits and OAuth scope changes can also disable an action without granting a broader replacement.

Failures distinguish operator repair from an upstream outage. Agents receive a final remediation message for an unreachable saved server instead of permission to search other hosts or network addresses. Scheduled health checks keep connection state current without treating a temporary service failure as permission to expand access.

References: server/…/tool-policy.ts• L28-89 server/…/descriptors.ts• L18-58 server/…/descriptors.ts• L99-212 server/…/discovery.ts• L115-161 server/…/discovery.ts• L186-306 server/…/discovery.ts• L445-484 server/…/health.ts• L80-231 server/…/publication.ts• L125-175 server/…/publication.ts• L205-353 server/…/mcp-protocol-config.ts• L5-41

Aggregator account discovery

Aggregator account discovery shows which upstream app accounts are available through a governed gateway. It is a management action for an authorized responsible user, not a new source of tool authority.

The gateway must be active and expose the reviewed management action before discovery can run. Account checks use the caller’s credential identity and a credential fingerprint. A lease prevents overlapping or stale syncs from replacing newer observations. A complete inventory is committed as one observation, while failed or expired checks remain stale and never become current authorization.

Mutating upstream account actions are not retried automatically when the provider response is uncertain. The system checks the account before removal or rename and checks the provider’s later state before it reports success. Arcade discovery keeps its extra project credential separate from gateway invocation credentials and tool grants.

References: server/…/aggregator-accounts.ts• L26-75 server/…/aggregator-accounts.ts• L96-172 server/…/aggregator-accounts.ts• L238-415 server/…/aggregator-accounts.ts• L418-506

Native and plugin boundaries

Native runs receive a server-bound tool authority. It limits the visible catalog and checks the live company, agent, issue, run, assignment, responsible user, and trust context before a call can create an effect. Review runs receive only assigned-task reads and their review action. Mutations use durable receipts and recheck authorization before replay.

Plugins use a separate capability boundary. A plugin declares its required capabilities, install-time checks compare those declarations with its features, and runtime bridge calls check the named operation again. Unknown operations fail by default.

The Daytona sandbox provider keeps execution tied to a company, environment, driver, provider lease, and provider account without placing the API key in the in-memory handle key. It confines file sync to the recorded workspace directory, requires a matching provider lease, and rejects mismatched handles. It also bounds provider liveness calls and closes sessions and channels during teardown so a stale or dead bridge cannot retain execution access.

More detail on runtime isolation, tool authority, and plugin limits is in Runtime and tool governance.

References: server/…/paperclip-runner-tool-authority.ts• L186-345 server/…/paperclip-runner-tool-authority.ts• L941-1100 server/…/plugin-capability-validator.ts• L44-150 server/…/plugin-runtime-sandbox.ts• L56-175 packages/…/plugin.ts• L971-980 packages/…/plugin.ts• L1147-1216 packages/…/plugin.ts• L3387-3475 packages/…/plugin.ts• L3542-3623 packages/…/plugin.ts• L3787-3805

Organizational policy enforcement

Company policy turns local security choices into repeatable rules for all agents and runs. The policy layer covers membership, skills, issue review, execution stages, workspace selection, and tool use. Policy edits require company authority and produce activity records.

Membership and invite policy

Company access routes manage invitations, join approval, member roles, permission grants, and member archival. Invite tokens are high-entropy values stored only as hashes. They expire after a short period and the raw value is returned only when the invite is created.

Member changes use company-scoped role checks. The system blocks self-removal and removal of protected instance or company administrators through ordinary membership controls. Instance-level administration remains separate from company access.

References: server/…/access.ts• L62-75 server/…/access.ts• L110-145 server/…/access.ts• L3017-3202 server/…/access.ts• L4481-4667

Skill, review, and workspace policy

Skill policy controls which agents may use or change skills and which sources are acceptable. Explicit rules take priority over the default effect, and revision checks prevent a stale editor from overwriting a newer policy.

Issue review policy controls who may approve or reject a review. Execution stages can require a decision comment, request changes, or escalate to the responsible human after repeated agent review rounds. Workspace policy selects the execution environment and can require a managed sandbox instead of local fallback.

References: server/…/company-skill-policy.ts• L24-39 server/…/company-skill-policy.ts• L45-87 server/…/issue-review-policy.ts• L23-147 server/…/issue-execution-policy.ts• L446-462 server/…/execution-workspace-policy.ts• L107-165 server/…/execution-workspace-policy.ts• L330-401

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep actor sources, credential claims, run context, responsible-user context, and authorizing-user context aligned. A new authentication source must preserve company, run, delegation, and audit identity fields.
  • Keep board session bootstrap scope aligned with the company IDs already granted to the actor. Profile and session routes must not expose another company’s directory or backend telemetry credential.
  • Keep company access checks and resource not-found behavior aligned. A new resource route must not turn a cross-company lookup into a distinguishable authorization error.
  • Keep request-local authorization reads bounded by the request and response lifetime. Do not move instance-role or membership facts into a cross-request cache that could hide a revocation.
  • Keep responsible-user and external-authorizer intersections aligned between API decisions, connection-token minting, gateway sessions, native tool calls, and connection management.
  • Keep assignment policy parsing and precedence aligned across agent, project, parent-issue, and issue targets. Unknown or malformed data must not become an allow path.
  • Keep private project and issue predicates aligned across direct reads, list filters, linked resources, and external publication.
  • Keep secret configuration paths synchronized with binding records, user-secret declarations, projection allowlists, and runtime manifests.
  • Keep run-bound secret authorization, access events, and redaction registration aligned when adding a credential delivery path.
  • Keep successful secret access events aligned with last-used reporting. A credential read must not update shared secret state in a way that can interfere with concurrent work admission.
  • Keep owner-scoped user-secret mediation separate from low-trust declaration allowlists. A caller must not select a mode that skips a check it claims to enforce.
  • Keep fixed managed-login definitions, stored-session claims, credential precedence, idempotency, and stale-version checks aligned.
  • Keep trust boundaries intersected across agent, project, issue, and run policy. A new policy source must not widen an existing boundary.
  • Keep reviewed connector source and endpoint matching aligned with risk classification and catalog quarantine. A custom connection must not inherit a reviewed policy unless its identity matches the reviewed rule.
  • Keep native tool catalogs, server-built bindings, active-profile resolution, connection review counts, live run checks, review-run limits, and durable mutation receipts aligned.
  • Keep connection grants, OAuth actor state, profiles, gateway credentials, and removal cleanup aligned so reconnects rebuild access from a fresh identity decision.
  • Keep OAuth endpoint discovery, redirect constraints, issuer binding, resource audience, PKCE state, client registration, callback consumption, and token transport checks aligned. A new OAuth endpoint producer must use the same endpoint gate.
  • Keep curated OAuth scopes separate from provider-advertised scopes. A provider response must not widen the scopes stored for a connection or grant.
  • Keep plugin declarations, operation mappings, and sandbox host bindings aligned. An undeclared operation must remain denied by default.
  • Keep sandbox lease cache keys, provider account identity, workspace roots, lease checks, liveness bounds, and teardown eviction aligned. A cached provider handle must never cross company, environment, account, or lease scope.
  • Keep connection installs, profile bindings, catalog entries, and uninstall cleanup aligned. Removing an install must not leave a stale binding that changes configuration or review results.
  • Keep OAuth grant-held credentials, secret bindings, refresh leases, per-grant scope baselines, and reconnect state aligned. A personal grant must not fall back to organization credentials.
  • Keep catalog discovery, protocol negotiation, cache scope, health status, quarantine state, provider-specific action limits, and default profile synchronization aligned. A failed or narrower discovery must not re-enable an action.
  • Keep aggregator account leases, credential fingerprints, actor ownership, complete inventory commits, and provider-confirmation checks aligned. An old sync must not replace observations made with a newer credential.

Important failure modes

TriggerConsequenceGuard
Responsible user is missing, inactive, or a viewerA delegated action is deniedCurrent membership lookup and responsible-user intersection
Authorizing user is not an active memberThe agent cannot use the external authorityServer-derived authorizing-user check
Board bootstrap company IDs do not match current accessThe board can show data outside its granted company setFilter bootstrap companies by the authenticated access set
Resource belongs to another companyThe actor cannot learn whether it existsCompany-scoped lookup with normal not-found behavior
Authorization read facts outlive the requestA membership or instance-role revocation may not affect a later decisionShort-lived request scope with no cross-request cache
Assignment policy is unknown, malformed, protected, or privateSimple assignment is blocked or needs an explicit grantPolicy evaluation fails closed across all target levels
Secret has no matching binding, active version, or usable providerRuntime credential resolution failsCompany, binding, status, version, provider, and path checks
Agent secret read is not tied to an active run-bound tokenThe credential read is rejectedJWT source, heartbeat run, path, authorization, and binding checks
Resolved value is not registered for redactionLater logs or tool results may expose the valueRun redaction registration after successful resolution
A successful secret read has no access eventSecret usage and last-used reporting become incompleteRecord a success event for attributed and system reads
Owner-scoped mediation receives a binding allowlistResolution is rejectedOwner-scoped mode refuses allowlists it cannot enforce
Fixed managed-login definition or owner value conflicts with stored stateLogin or rotation is rejected without exposing credential stateFixed definition shape, owner lookup, session idempotency, and compare-and-set version checks
Low-trust work lacks an isolated sandboxThe run cannot startLow-trust preflight requires isolation and a sandbox driver
Low-trust output enters higher-trust context without promotionThe content is replaced with a quarantine markerSource-trust quarantine and promotion rules
Destructive tool call has no valid approvalThe call is blockedRisk classification, signed approval, and live snapshot checks
Active profile is absent, inactive, or excludes the catalog entryThe agent receives no allowed tool or connection assignmentCompany and agent binding precedence plus active-profile filtering
Reviewed connector rule does not match the connection identityNew or changed actions can bypass the intended risk reviewSource and endpoint matching before policy selection, with quarantine by default
Archived connection is summarized as active review workOperators see false pending or quarantined countsReview-count query returns zero for archived connections
Native run is stopped, reassigned, or replacedThe native call cannot executeLive run, assignment, issue, and server-bound tool checks
Plugin calls an unknown operationThe host bridge denies the callInstall-time and runtime capability checks
Provider handle key omits company, environment, account, or lease scopeA cached authenticated handle could run work in the wrong sandboxComposite non-secret cache key and lease-handle identity check
Sandbox workspace root is missing or provider liveness hangsFile transfer or execution may escape its root or stall until a broad RPC timeoutRecorded remote root and per-call liveness bounds
Sandbox teardown runs while a command or channel is activeThe provider may terminate an in-use lease or retain a live routeActivity and teardown gates plus session and channel cleanup
Installed connection is removed but its generated binding remainsLater configuration reads can show access the operator removedTransactional install removal and source-specific binding cleanup
OAuth metadata or configured endpoint points to an unsafe or private destinationPaperclip could send credentials or browser navigation to an unintended hostSafe endpoint validation and public-network checks
OAuth callback has expired, reused, actor-mismatched, or issuer-mismatched stateThe code is rejected and cannot complete a different sign-inSingle-use state, actor binding, PKCE, and issuer validation
OAuth provider returns a broader or unverified scopeThe grant must not gain the extra permissionRequested-scope allowlist and per-grant returned-scope checks
OAuth client registration changes the requested redirect or auth methodThe client is rejected instead of being used with a different contractBounded DCR response validation
OAuth refresh returns no usable refresh credential or an unverified scopeThe grant needs reconnection and its actions stop using stale accessRefresh lease, per-grant scope baseline, and reconnect state
Catalog discovery finds a new, changed, removed, or provider-blocked actionThe action is quarantined or disabled instead of becoming silently usableCatalog reconciliation, risk classification, quarantine, and profile review
Catalog refresh uses a stale endpoint or cached permission viewThe catalog can describe the wrong server or grantEndpoint-bound negotiation persistence, credential-scoped cache, and live health checks
Aggregator sync uses an old credential or stale leaseOld account observations can replace current account stateCredential fingerprint, expiring lease, locked final commit, and current-connection check
Aggregator mutation is not confirmed by the providerPaperclip reports a change that may not have happenedNo automatic retry for uncertain writes and post-change verification
Saved MCP server is unreachableAn agent may waste retries or search unsafe alternate addressesFinal remediation that requires a person to fix the saved connection

Key files

FileWhy to read it
server/…/auth.tsShows how request credentials become board, agent, Cloud, or protocol-specific actors.
server/…/auth.tsShows the board session and profile boundary, including scoped bootstrap and front-end-only telemetry data.
server/…/board-bootstrap.tsShows how authenticated company access becomes board bootstrap data.
server/…/authorization.tsCentralizes company access, grants, privacy, delegation, assignment policy, and trust-boundary decisions.
server/…/authorization-read-scope.tsShows the short-lived request scope that reuses read authorization facts without caching them across requests.
server/…/secrets.tsDefines secret ownership, provider resolution, bindings, user-scoped mediation, managed login claims, access events, and redaction registration.
server/…/trust-preset-resolver.tsShows how policy from agent, project, issue, and run context becomes one trust decision.
server/…/low-trust-runtime-containment.tsShows the preflight boundary for isolated low-trust execution.
server/…/source-trust.tsShows quarantine and promotion rules for content that crosses trust levels.
server/…/tool-policy.tsSelects reviewed connector risk and quarantine policy by provider or exact connection identity.
server/…/tool-access-policy.tsDefines profile matching and tool policy decisions.
server/…/resolution.tsShows how company and agent bindings become effective profiles, allowed tools, and connection assignments.
server/…/service.tsShows how profiles select catalog actions, review new actions, and bind access to targets.
server/…/installs.tsShows how a connection is exposed to a company or agent and how its generated access is removed.
server/…/assignment-locks.tsShows the transaction boundary that keeps connection, profile, catalog, and agent assignment changes consistent.
server/…/descriptors.tsShows how discovered actions receive risk levels and provider-specific allow limits.
server/…/discovery.tsShows how supported connections discover actions and respond to credentials, OAuth, scope, protocol, and remote-server state.
server/…/health.tsShows how live connection checks become health state, runtime readiness, and audit events.
server/…/publication.tsShows how discovered actions become active, quarantined, disabled, or removed catalog entries.
server/…/aggregator-accounts.tsShows how authorized users discover and manage upstream aggregator accounts without widening tool authority.
server/…/mcp-protocol-config.tsShows how negotiated MCP behavior is saved without overwriting concurrent operator changes or another endpoint’s state.
server/…/authorization-constraints.tsDefines redirect-origin and callback-issuer checks for OAuth.
server/…/discovery.tsShows how OAuth metadata becomes a safe, issuer-bound endpoint set.
server/…/authorization-start.tsShows how actor-bound OAuth state, PKCE, scopes, resource audience, and human confirmation are created.
server/…/direct-callback.tsShows how OAuth callbacks become personal or organization grants and refresh the catalog.
server/…/client.tsShows dynamic client registration validation and safe token exchange.
server/…/client-metadata.tsDefines the public client metadata document and its single callback contract.
server/…/credential-store.tsShows how organization and personal OAuth credentials resolve through secret bindings.
server/…/grant-refresh.tsShows how OAuth grants refresh, retain scope provenance, and enter reconnect state.
server/…/review-counts.tsShows the company-scoped review summary for pending action requests and quarantined catalog entries.
server/…/tool-gateway.tsShows the boundary between an authorized tool call and a connected runtime.
server/…/paperclip-runner-tool-authority.tsShows the native run catalog, live binding checks, review limits, and mutation receipts.
server/…/plugin-capability-validator.tsDefines plugin capability checks at install time and runtime.
packages/…/plugin.tsShows how a provider lease stays bound to its account, company, environment, workspace, and teardown lifecycle.
server/…/access.tsShows invite, membership, permission, and administrative governance.