Secrets and credentials
Paperclip gives each company one controlled way to store confidential values, link values held by an external provider, and deliver only approved values to agents and other workloads. It keeps read views and audit data free of plaintext while recording the context of each resolution. Server-side Git can use a managed GitHub connection or a company secret without placing the credential in command arguments or remote URLs. Read identity and access control for actor and company boundaries, and runtime and tool governance for controls on consumers that receive a value.
Secret custody model
Secret custody is the path from a value entering Paperclip to the point where a consuming process receives it. Paperclip stores or links the value, checks its binding and version at resolution time, and treats the receiving agent, sandbox, plugin, remote host, Git process, or request as the final trust boundary.
This diagram shows how administration produces a bound value while the value stays out of metadata views and access records.
flowchart LR
A[Board or approved service action] --> B[Encrypted or external provider storage]
B --> C[Binding, scope, and version checks]
C --> D[Server-side resolution]
D --> E[Agent, sandbox, plugin, Git, or request]
C --> F[Value-free access audit]
D --> G[Run and response redaction]
Secret providers
Secret providers define where secret material lives and how Paperclip creates, rotates, links, resolves, and removes it. A company can use local encrypted storage or select a company provider vault for a supported external service.
| Provider | Value custody | Runtime state |
|---|---|---|
local_encrypted | Paperclip stores encrypted material protected by the deployment master key. | Ready for normal use. |
aws_secrets_manager | AWS stores the value. Paperclip stores the provider handle and version metadata. | Ready when the vault and server credential path work. |
gcp_secret_manager | Paperclip can hold draft provider metadata. | Runtime use is locked. |
vault | Paperclip can hold draft provider metadata. | Runtime use is locked. |
A provider vault is a company-scoped routing record for one provider family. A company can have several vaults in one family and can select a default for new create and rotate actions. An explicit vault wins; without one, the deployment-level provider setup is used. Vault configuration contains routing data such as a region, namespace, prefix, KMS key, project, or Vault address. It does not contain bootstrap credentials. The server uses its deployment identity or the provider's normal credential chain.
References: server/…/provider-registry.ts• L11-33 server/…/secrets.ts• L835-837 server/…/secrets.ts• L1240-1297 server/…/secrets.ts• L1301-1359
Encrypted and external storage
Paperclip-managed secrets accept a value and create a provider version. Local values are encrypted before storage. External managed values are written to the selected provider. External-reference secrets keep a pointer and provider version reference for a value that already exists elsewhere; Paperclip does not copy that provider plaintext into its own storage.
The storage modes define ownership:
- Paperclip-managed: Paperclip owns the provider create and rotation operation.
- External reference: The provider owns the value. Paperclip resolves it and writes a new value only when that provider supports the operation and the request allows it.
Create and rotate use a reserve, provider write, and database commit flow. If a later local write fails, Paperclip attempts provider cleanup or archive and reports when cleanup also fails. Version changes use a parent-secret-first transaction lock and an optional expected-version check. A guarded rotation that loses a race returns one stale-version conflict instead of making its version current. A latest binding follows the new version; a pinned binding remains on its selected version.
Paperclip also supports instance-scoped secrets owned by one agent or project and one plugin. These values are resolved only inside that owner boundary. Instance storage supports plugin workers without making the value a company-wide secret.
References: server/…/secrets.ts• L1361-1469 server/…/secrets.ts• L2211-2427 server/…/secrets.ts• L2433-2649 server/…/secrets.ts• L3530-3563 server/…/secrets.ts• L4664-4735
Provider health and recovery
Health checks show whether a provider or vault can serve its role without returning credentials or values. They return safe status, operator guidance, and missing non-secret setup data.
For local encrypted storage, the database and deployment master key form one recovery pair. For AWS storage, recovery needs Paperclip metadata plus the same provider namespace and the permissions required by the AWS identity. A vault marked coming_soon or disabled cannot create, rotate, or resolve values.
References: server/…/secrets.ts• L1301-1359 server/…/local-encrypted-provider.ts• L48-80 server/…/local-encrypted-provider.ts• L109-193
Secret bindings and delivery
A secret binding connects a stored secret to a target and a configuration path. The binding is the permission to deliver the value. Creating a secret does not place it in an agent or workload environment.
Company secret bindings
Company secrets can be bound to agents, projects, environments, routines, issues, runs, or other supported targets. A binding selects latest or a fixed version and names the path where the target receives it.
The main delivery paths are:
env.<KEY>injects the resolved value as an environment variable.access.<ALIAS>gives an agent on-demand API access without environment injection.
Runtime resolution checks the company boundary, secret status, version status, provider status, and binding path. Agent reads also require an authorized run-bound agent token and a verified running heartbeat. The active run can limit access to binding IDs recorded in its secret manifest. Resolution records a manifest entry and a value-free access result before the value reaches the consumer.
Paperclip can inspect a draft environment without writing tenant audit events. A durable sandbox cleanup can resolve the exact connection recorded by its cleanup lease even when the environment binding was removed. These are narrow system paths, not general agent access paths, and each uses a distinct audit consumer.
References: server/…/secrets.ts• L1140-1217 server/…/secrets.ts• L1361-1469 server/…/secrets.ts• L1492-1591 server/…/secrets.ts• L1619-1783 server/…/secrets.ts• L1785-1889
Plugin task credential handoffs
Plugin-backed AI tasks can keep using a managed credential while a warm task, task move, or recovery outlives the process that started it. Paperclip records durable handoff authority on the active task lease. The record identifies the account and the approved secret binding, but it does not store credential bytes or a controller-local temporary path.
The handoff supports two related paths:
- Live credential updates resolve the current binding again before writing back a provider credential. A revocation or binding change therefore wins over an old task snapshot.
- Completion and cleanup settle a pending handoff only after task termination is confirmed. A stopped task can read its credential only when the saved handoff matches the account and the task is marked stopped.
This lets warm tasks and restart cleanup finish safely without granting a task a new secret authority. The writeback records an outcome such as rotation, no change, binding change, unavailable credentials, or a task that was never dispatched.
References: server/…/plugin-task-credential-writeback.ts• L16-48 server/…/plugin-task-credential-writeback.ts• L51-81 server/…/plugin-task-credential-writeback.ts• L84-118 server/…/managed-ai-credential-writeback.ts• L20-90 server/…/environment-task-runtime.ts• L88-93 server/…/environment-task-runtime.ts• L457-463
User-specific secret bindings
User-specific secrets separate a shared credential slot from each person's value. A user secret definition names the slot, such as github_api_token; a user secret value belongs to one company member. An adapter refers to the definition key, not to a person's secret ID.
The responsible user supplies the value at resolution time. Required bindings fail closed when the user, definition, declaration, or active value is missing. Optional bindings omit the environment variable. They never use an empty value or another user's value. Configuration sync writes both company binding rows and user-secret declaration rows so the saved adapter or environment config matches the runtime authorization record.
Paperclip also owns a fixed user-secret definition for Claude Code OAuth. The login flow creates or reuses only that definition, records a non-secret session identifier for idempotency, and uses an owner-bound first write or confirmed rotation. A valid stored-session claim is required when the fixed binding is introduced. A non-empty higher-priority ANTHROPIC_API_KEY conflicts with the OAuth binding. A copied binding must match the parent's current version, so concurrent parent rotation cannot create stale inheritance.
References: server/…/secrets.ts• L1056-1103 server/…/secrets.ts• L3021-3192 server/…/secrets.ts• L3194-3404 server/…/secrets.ts• L5107-5228
Binding synchronization
Configuration is the source of intended delivery paths. Paperclip normalizes secret references when it saves adapter or environment configuration, then synchronizes the corresponding binding and user-secret declaration rows. It validates references before replacing a target's bindings so an invalid reference does not leave a target half-bound.
The same model supports instance targets shared across companies. Instance bindings are written under the company that owns each referenced secret, while environment-variable bindings remain company-scoped. This lets an instance show honest metadata for references that the current company's picker cannot list without exposing values.
References: server/…/secrets.ts• L1922-2064 server/…/secrets.ts• L4819-5026 server/…/secrets.ts• L5037-5085
Agent proposals and approval
Agents can request a new secret or ask for an existing secret to be bound at a new path without receiving permission to make that change. A proposal is a pending human-reviewable request tied to an authorized run and, when present, its issue origin.
Proposal types
| Proposal | Purpose | Human decision |
|---|---|---|
| Secret | Ask Paperclip to create a company secret from an agent-supplied value. | Approve and create, or reject. |
| Binding | Ask Paperclip to attach an existing, inherited, or proposed secret to an agent path. | Approve and create the binding, or reject. |
Proposal creation requires the run-bound agent permission for secret proposals. A binding request names exactly one source and uses an env.<KEY> or access.<ALIAS> path. The source can be an existing company secret, a path already bound to the proposing agent, or a pending secret proposal. Policy limits pending proposals and creation rate. A manager can target a report only when the policy permits it.
References: server/…/secret-proposals.ts• L23-29 server/…/secret-proposals.ts• L105-150 server/…/secret-proposals.ts• L360-480 server/…/secrets.ts• L129-157 server/…/secrets.ts• L194-253
Review lifecycle
The board reviews proposals in the Secrets page and through the company proposal API. Review data includes proposer, target, path, expiry, and justification. A secret proposal shows a fingerprint and length instead of its value. Agent-facing views omit those value-derived fields. The justification is an agent claim and is untrusted input.
When a binding proposal comes from an issue run, Paperclip creates one human-only Confirm secret binding interaction. Choosing Create binding accepts the interaction and starts a separately authorized write. Acceptance does not prove that the write succeeded; the caller must check the execution result and list the agent's secret metadata again.
Approval can cascade from a binding proposal to its still-pending secret prerequisite. Paperclip creates the secret first and then applies the binding. If the binding fails, the secret remains approved but the binding does not exist. Rejection, withdrawal, expiry, or failed execution does not create access. Terminal proposal changes scrub stored proposal ciphertext, and dependent binding proposals close when their prerequisite closes.
References: server/…/secret-proposals.ts• L173-314 server/…/secret-proposals.ts• L482-519 server/…/secret-proposals.ts• L552-887 server/…/issues.ts• L2406-2454 ui/…/proposal-review.tsx• L243-313
Redaction and audit
Redaction prevents secret material from entering Paperclip logs, activity payloads, issue data, or human-facing responses. Audit records preserve enough metadata to explain an access decision without recording the value.
Value redaction
Paperclip does not return decrypted values to board views, provider-vault views, secret lists, proposal lists, or health responses. Sensitive event fields and HTTP log fields use a redaction marker. Secret-bearing URLs lose user information and query or fragment data. Provider references remain visible because they are pointers, not plaintext values.
Values delivered to a run are registered for that run. Later responses and issue data can be scanned and replaced when a registered value appears. This protects values copied into Paperclip output after resolution, but it cannot control what an agent sends to an outside system after it receives the value.
References: server/…/run-secret-redaction.ts• L35-123 server/…/redaction.ts• L3-16 server/…/redaction.ts• L99-149 server/…/redact-sensitive.ts• L1-14
Access audit
Successful and failed resolutions create value-free access events. Events identify the company, scope, selected version, provider, actor, consumer, binding path, run or issue, responsible user, credential owner when relevant, and safe error code. Secret changes and provider-vault changes also create metadata-only activity entries.
The custody guarantee ends at injection or delivery. An agent process, sandbox, plugin worker, remote host, or downstream tool can read, log, or forward the value. Bind only what each consumer needs and rotate a value after suspected exposure.
References: server/…/secrets.ts• L1180-1217 server/…/secrets.ts• L1417-1466 server/…/secrets.ts• L1734-1781 server/…/run-secret-redaction.ts• L77-81
Credential access visibility
When a run cannot use a selected credential because it is not shared with the responsible user, Paperclip can show the selected connection name only to that responsible user or to a human covered by the connection's user or organization grant. Other viewers receive no connection name and no grant details. This helps the affected user repair access without turning activity and run views into a credential directory.
References: server/…/credential-access-visibility.ts• L4-28 server/…/activity.ts• L88-107 server/…/run-secret-redaction.ts• L77-81
Git credentials
Server-side Git operations use a company or managed connection credential source for private GitHub remotes. This path is separate from agent environment bindings, so managed checkouts and workspace refreshes can use a credential without injecting it into every agent run.
Credential source selection
For each run, Paperclip first checks for one eligible managed GitHub identity within the company's installed connections and the run's agent or responsible user. A dedicated agent identity takes priority over a personal identity. Paperclip rejects ambiguous or unavailable managed identities instead of silently falling through to an older source.
When no managed identity applies, Paperclip checks company secrets in this order: GITHUB_TOKEN, GH_TOKEN, then PAPERCLIP_GITHUB_TOKEN. If no company secret resolves, self-hosted operation can use GITHUB_TOKEN or GH_TOKEN from the server process environment. A credential lookup is reused for Git operations in one run, and its secret reads use the system consumer context workspace-git-credential.
References: server/…/git-credentials.ts• L17-32 server/…/git-credentials.ts• L202-263 server/…/git-credentials.ts• L296-429 server/…/git-credentials.ts• L464-579
Git invocation boundary
The credential path accepts supported GitHub remotes and can translate supported SSH forms to HTTPS. It rejects unrelated hosts, inline URL credentials, and unsupported remote forms. Paperclip clears ambient Git helpers and passes the token through a URL-scoped helper and the process environment. Git prompts are disabled. The token does not enter command arguments, remote URLs, or files.
Credential-bearing URL user information and complete query strings are scrubbed from warnings and errors. Git authentication failures identify the credential source without exposing the token, while unrelated network or file errors are not blamed on the credential.
References: server/…/git-credentials.ts• L34-113 server/…/git-credentials.ts• L115-189
Administration interfaces
The Secrets page is the main board interface for confidential configuration. It combines company secrets, user-secret definitions and values, provider vaults, usage data, and pending proposals while keeping value fields out of read views.
Board UI
Administrators use Company Settings → Secrets to manage:
- Company secret names, status, deletion, rotation, storage mode, and provider vault.
- External-reference imports and metadata-only usage and access history.
- User-secret definitions and metadata-only coverage.
- The current user's own user-secret values.
- Provider vault defaults, status, configuration, and health checks.
- Secret and binding proposal review.
Slash-separated secret names have folder-like display views. This only organizes the page; it does not change custody or binding rules.
References: ui/…/Secrets.tsx• L649-783 ui/…/Secrets.tsx• L901-981 ui/…/user-secret-presentation.tsx• L15-79
APIs
The server separates company administration routes from run-scoped agent routes. The UI groups these calls in secretsApi.
| Area | API surface |
|---|---|
| Company secrets | /api/companies/{companyId}/secrets and /api/secrets/{id} |
| Provider discovery and vaults | /api/companies/{companyId}/secret-providers, /api/companies/{companyId}/secret-provider-configs, and /api/secret-provider-configs/{id} |
| User-secret definitions | /api/companies/{companyId}/user-secret-definitions |
| Current user's values | /api/companies/{companyId}/me/user-secrets |
| Usage and access history | /api/secrets/{id}/usage and /api/secrets/{id}/access-events |
| Agent catalog and run access | /api/companies/{companyId}/secrets/catalog, /api/agents/me/secrets, and /api/agents/me/secrets/{key}/value |
| Secret proposals | /api/agents/me/secret-proposals and /api/companies/{companyId}/secret-proposals |
Board routes require board authentication and company access. User-secret definitions require company administrator access. Agent value reads require a current run-bound agent identity. Proposal routes require a verified run-bound token with the relevant action permission. Binding approval also checks the target agent's configuration-change permission.
References: ui/…/secrets.ts• L150-255 server/…/secrets.ts• L68-89 server/…/secrets.ts• L119-157 server/…/secrets.ts• L240-359
Change checklist
When these files or sections are changed, remember to consider these:
- Keep provider selection, vault status, health results, and runtime provider checks aligned so a vault cannot appear usable while create, rotate, or resolve is locked.
- Keep provider error mapping and rollback paths free of plaintext, credentials, raw provider errors, and sensitive URL parts.
- Keep secret scope checks aligned with instance owner checks, binding checks, and the narrow system cleanup and inspection paths.
- Keep binding rows, user-secret declarations, runtime manifests, and configuration normalization synchronized so a saved reference cannot lose its authorization record.
- Keep
latestand pinned version behavior aligned with guarded rotation, parent-first lock order, provider cleanup, and stale conflict handling. - Keep plugin task handoff authority, task identity checks, termination confirmation, live writeback, and restart cleanup aligned so a warm or moved task cannot use stale authority.
- Keep class-3 static lease projection checks aligned with the approved target and configuration-path allowlist.
- Keep Claude fixed-definition, stored-session claim, owner-bound compare-and-set, precedence conflict, and parent-version inheritance rules together across all configuration write paths.
- Keep proposal quotas, source references, target policy checks, approval cascade, execution results, and terminal ciphertext cleanup consistent.
- Keep agent list and value-read checks aligned with running heartbeats, run manifests, binding IDs, and per-run redaction registration.
- Keep GitHub managed-identity selection, same-account retry rules, company-secret order, host checks, and helper scope aligned.
- Keep provider recovery guidance paired with the local database and master key or the external provider namespace and permissions.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Local encrypted master key is missing, invalid, or does not match the database. | Local secret resolution fails and a database-only restore cannot recover values. | Back up the database and the same master key. Use provider health checks. |
| An external vault lacks non-secret configuration or server runtime credentials. | Create, rotate, import, or resolve calls fail. | Run the vault health check and provide credentials through the provider's server-side credential chain. |
| A secret is inactive, deleted, out of scope, or points to an inactive version. | Resolution fails closed and no value is delivered. | Restore the secret and version state or update the binding. |
| A guarded rotation uses an old expected version. | The rotation returns a stale conflict and does not become current. | Reload the secret and confirm the rotation against the current version. |
| An instance secret is resolved for a different agent, project, or plugin owner. | Resolution is rejected by the owner boundary. | Resolve through the exact instance owner scope. |
| A required user-secret definition, declaration, responsible user, or value is missing. | Adapter or run setup is blocked. | Create the definition, sync the declaration, identify the responsible user, and set that user's value. |
| A plugin task handoff is changed, points to a different task, or is read before task stop is confirmed. | Writeback or credential read fails instead of using an unverified snapshot. | Preserve the lease authority and task identity. Confirm stop before cleanup or recovery reads. |
| A plugin task's managed binding is revoked or changed during writeback. | The old credential is not rotated back into the managed secret. | Re-check the grant, secret version, session epoch, and connection before writeback. |
| An agent read lacks a verified running heartbeat, allowed binding, or run-manifest entry. | The value is not returned to the agent. | Use the active run-bound token and keep the manifest and binding records synchronized. |
| A proposal source, target policy, path, quota, or expiry check fails. | No pending request or binding access is created. | Use one valid source, stay within proposal limits, and review before expiry. |
| An issue interaction is accepted but binding execution fails. | The issue shows acceptance while the agent has no new access. | Read the execution result and re-list the agent's secret metadata. |
| A managed GitHub identity is ambiguous, unavailable, or unauthorized. | Private clone or fetch fails without falling through to a less specific credential. | Repair or narrow the managed identity and verify its repository access. |
| A GitHub token is requested for an unrelated host or a remote contains inline credentials. | Paperclip withholds the token and prevents cross-host credential leakage. | Use a supported GitHub remote and keep credentials out of the remote URL. |
| A value reaches an agent, plugin, sandbox, remote host, or downstream tool. | The receiving process can log or forward it outside Paperclip's custody. | Use narrow bindings and rotate after suspected exposure. |
Key files
| File | Why to read it |
|---|---|
| server/…/secrets.ts | Central secret lifecycle, provider selection, scoped resolution, bindings, user secrets, runtime manifests, version safety, and access events. |
| server/…/secrets.ts | Company, agent, proposal, provider-vault, user-secret, catalog, and audit API boundaries. |
| server/…/provider-registry.ts | Provider discovery and provider health entry points. |
| server/…/local-encrypted-provider.ts | Local value custody and master-key health behavior. |
| server/…/aws-secrets-manager-provider.ts | AWS managed values, external references, discovery, and provider credential boundaries. |
| server/…/agent-secret-bindings.ts | Translation from agent configuration to company bindings and user-secret declarations. |
| server/…/plugin-task-credential-writeback.ts | Durable credential handoff authority for warm, moved, and recovering plugin tasks. |
| server/…/managed-ai-credential-writeback.ts | Revalidation and safe writeback of managed AI credentials after a task provides a new snapshot. |
| server/…/secret-proposals.ts | Proposal policy, approval, cascade behavior, interaction results, and ciphertext cleanup. |
| server/…/run-secret-redaction.ts | Run registration, value redaction, and viewer-scoped credential projection. |
| server/…/credential-access-visibility.ts | Visibility rules for selected connection names. |
| server/…/redaction.ts | General payload and text redaction rules. |
| server/…/git-credentials.ts | Managed GitHub selection, company-secret fallback, and safe Git invocation. |
| packages/…/secrets.ts | Shared vocabulary for providers, versions, bindings, scopes, proposals, and access events. |
| packages/…/secret.ts | Input rules for managed values, external references, and provider configuration. |
| ui/…/Secrets.tsx | Main board administration flow for secrets, user secrets, vaults, imports, usage, and status. |
| ui/…/ProposalsTab.tsx and ui/…/proposal-review.tsx | Human review and approval flow for secret and binding proposals. |
| ui/…/secrets.ts | UI-to-server API contract for confidential configuration. |