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.
| Control | Main question | Result |
|---|---|---|
| Identity | Who is making the request? | A board user, agent, plugin, or system actor |
| Company scope | Which company may the actor access? | A tenant boundary for data and actions |
| Permission | Is this actor allowed to perform this kind of action? | A grant, role rule, or policy decision |
| Secret scope | May this consumer receive this credential? | A bound company secret or owner-scoped user secret |
| Trust boundary | How much authority does this run have? | Standard or low-trust access with a concrete scope |
| Tool governance | May this exact tool call run now? | Allow, deny, ask for approval, or defer |
| Audit | Can 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
| Trigger | Consequence | Guard |
|---|---|---|
| Responsible user is missing, inactive, or a viewer | A delegated action is denied | Current membership lookup and responsible-user intersection |
| Authorizing user is not an active member | The agent cannot use the external authority | Server-derived authorizing-user check |
| Board bootstrap company IDs do not match current access | The board can show data outside its granted company set | Filter bootstrap companies by the authenticated access set |
| Resource belongs to another company | The actor cannot learn whether it exists | Company-scoped lookup with normal not-found behavior |
| Authorization read facts outlive the request | A membership or instance-role revocation may not affect a later decision | Short-lived request scope with no cross-request cache |
| Assignment policy is unknown, malformed, protected, or private | Simple assignment is blocked or needs an explicit grant | Policy evaluation fails closed across all target levels |
| Secret has no matching binding, active version, or usable provider | Runtime credential resolution fails | Company, binding, status, version, provider, and path checks |
| Agent secret read is not tied to an active run-bound token | The credential read is rejected | JWT source, heartbeat run, path, authorization, and binding checks |
| Resolved value is not registered for redaction | Later logs or tool results may expose the value | Run redaction registration after successful resolution |
| A successful secret read has no access event | Secret usage and last-used reporting become incomplete | Record a success event for attributed and system reads |
| Owner-scoped mediation receives a binding allowlist | Resolution is rejected | Owner-scoped mode refuses allowlists it cannot enforce |
| Fixed managed-login definition or owner value conflicts with stored state | Login or rotation is rejected without exposing credential state | Fixed definition shape, owner lookup, session idempotency, and compare-and-set version checks |
| Low-trust work lacks an isolated sandbox | The run cannot start | Low-trust preflight requires isolation and a sandbox driver |
| Low-trust output enters higher-trust context without promotion | The content is replaced with a quarantine marker | Source-trust quarantine and promotion rules |
| Destructive tool call has no valid approval | The call is blocked | Risk classification, signed approval, and live snapshot checks |
| Active profile is absent, inactive, or excludes the catalog entry | The agent receives no allowed tool or connection assignment | Company and agent binding precedence plus active-profile filtering |
| Reviewed connector rule does not match the connection identity | New or changed actions can bypass the intended risk review | Source and endpoint matching before policy selection, with quarantine by default |
| Archived connection is summarized as active review work | Operators see false pending or quarantined counts | Review-count query returns zero for archived connections |
| Native run is stopped, reassigned, or replaced | The native call cannot execute | Live run, assignment, issue, and server-bound tool checks |
| Plugin calls an unknown operation | The host bridge denies the call | Install-time and runtime capability checks |
| Provider handle key omits company, environment, account, or lease scope | A cached authenticated handle could run work in the wrong sandbox | Composite non-secret cache key and lease-handle identity check |
| Sandbox workspace root is missing or provider liveness hangs | File transfer or execution may escape its root or stall until a broad RPC timeout | Recorded remote root and per-call liveness bounds |
| Sandbox teardown runs while a command or channel is active | The provider may terminate an in-use lease or retain a live route | Activity and teardown gates plus session and channel cleanup |
| Installed connection is removed but its generated binding remains | Later configuration reads can show access the operator removed | Transactional install removal and source-specific binding cleanup |
| OAuth metadata or configured endpoint points to an unsafe or private destination | Paperclip could send credentials or browser navigation to an unintended host | Safe endpoint validation and public-network checks |
| OAuth callback has expired, reused, actor-mismatched, or issuer-mismatched state | The code is rejected and cannot complete a different sign-in | Single-use state, actor binding, PKCE, and issuer validation |
| OAuth provider returns a broader or unverified scope | The grant must not gain the extra permission | Requested-scope allowlist and per-grant returned-scope checks |
| OAuth client registration changes the requested redirect or auth method | The client is rejected instead of being used with a different contract | Bounded DCR response validation |
| OAuth refresh returns no usable refresh credential or an unverified scope | The grant needs reconnection and its actions stop using stale access | Refresh lease, per-grant scope baseline, and reconnect state |
| Catalog discovery finds a new, changed, removed, or provider-blocked action | The action is quarantined or disabled instead of becoming silently usable | Catalog reconciliation, risk classification, quarantine, and profile review |
| Catalog refresh uses a stale endpoint or cached permission view | The catalog can describe the wrong server or grant | Endpoint-bound negotiation persistence, credential-scoped cache, and live health checks |
| Aggregator sync uses an old credential or stale lease | Old account observations can replace current account state | Credential fingerprint, expiring lease, locked final commit, and current-connection check |
| Aggregator mutation is not confirmed by the provider | Paperclip reports a change that may not have happened | No automatic retry for uncertain writes and post-change verification |
| Saved MCP server is unreachable | An agent may waste retries or search unsafe alternate addresses | Final remediation that requires a person to fix the saved connection |
Key files
| File | Why to read it |
|---|---|
| server/…/auth.ts | Shows how request credentials become board, agent, Cloud, or protocol-specific actors. |
| server/…/auth.ts | Shows the board session and profile boundary, including scoped bootstrap and front-end-only telemetry data. |
| server/…/board-bootstrap.ts | Shows how authenticated company access becomes board bootstrap data. |
| server/…/authorization.ts | Centralizes company access, grants, privacy, delegation, assignment policy, and trust-boundary decisions. |
| server/…/authorization-read-scope.ts | Shows the short-lived request scope that reuses read authorization facts without caching them across requests. |
| server/…/secrets.ts | Defines secret ownership, provider resolution, bindings, user-scoped mediation, managed login claims, access events, and redaction registration. |
| server/…/trust-preset-resolver.ts | Shows how policy from agent, project, issue, and run context becomes one trust decision. |
| server/…/low-trust-runtime-containment.ts | Shows the preflight boundary for isolated low-trust execution. |
| server/…/source-trust.ts | Shows quarantine and promotion rules for content that crosses trust levels. |
| server/…/tool-policy.ts | Selects reviewed connector risk and quarantine policy by provider or exact connection identity. |
| server/…/tool-access-policy.ts | Defines profile matching and tool policy decisions. |
| server/…/resolution.ts | Shows how company and agent bindings become effective profiles, allowed tools, and connection assignments. |
| server/…/service.ts | Shows how profiles select catalog actions, review new actions, and bind access to targets. |
| server/…/installs.ts | Shows how a connection is exposed to a company or agent and how its generated access is removed. |
| server/…/assignment-locks.ts | Shows the transaction boundary that keeps connection, profile, catalog, and agent assignment changes consistent. |
| server/…/descriptors.ts | Shows how discovered actions receive risk levels and provider-specific allow limits. |
| server/…/discovery.ts | Shows how supported connections discover actions and respond to credentials, OAuth, scope, protocol, and remote-server state. |
| server/…/health.ts | Shows how live connection checks become health state, runtime readiness, and audit events. |
| server/…/publication.ts | Shows how discovered actions become active, quarantined, disabled, or removed catalog entries. |
| server/…/aggregator-accounts.ts | Shows how authorized users discover and manage upstream aggregator accounts without widening tool authority. |
| server/…/mcp-protocol-config.ts | Shows how negotiated MCP behavior is saved without overwriting concurrent operator changes or another endpoint’s state. |
| server/…/authorization-constraints.ts | Defines redirect-origin and callback-issuer checks for OAuth. |
| server/…/discovery.ts | Shows how OAuth metadata becomes a safe, issuer-bound endpoint set. |
| server/…/authorization-start.ts | Shows how actor-bound OAuth state, PKCE, scopes, resource audience, and human confirmation are created. |
| server/…/direct-callback.ts | Shows how OAuth callbacks become personal or organization grants and refresh the catalog. |
| server/…/client.ts | Shows dynamic client registration validation and safe token exchange. |
| server/…/client-metadata.ts | Defines the public client metadata document and its single callback contract. |
| server/…/credential-store.ts | Shows how organization and personal OAuth credentials resolve through secret bindings. |
| server/…/grant-refresh.ts | Shows how OAuth grants refresh, retain scope provenance, and enter reconnect state. |
| server/…/review-counts.ts | Shows the company-scoped review summary for pending action requests and quarantined catalog entries. |
| server/…/tool-gateway.ts | Shows the boundary between an authorized tool call and a connected runtime. |
| server/…/paperclip-runner-tool-authority.ts | Shows the native run catalog, live binding checks, review limits, and mutation receipts. |
| server/…/plugin-capability-validator.ts | Defines plugin capability checks at install time and runtime. |
| packages/…/plugin.ts | Shows how a provider lease stays bound to its account, company, environment, workspace, and teardown lifecycle. |
| server/…/access.ts | Shows invite, membership, permission, and administrative governance. |