## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents need API keys and tokens. People manage them in Settings →
Secrets.
> - The page showed every credential in one table. Tokens that Paperclip
saved for connections, chat channels and model sign-ins sat beside the
few secrets a person added, many with record IDs as names.
> - Each row repeated an always-true status, a version and a key. New
secret opened on two stacked mode switches and two storage pickers.
> - A person could not see which agents use a secret without opening it,
and had to open it again after creation to give an agent access.
> - This pull request redesigns the page, the New secret dialog, the
details panel, the Vaults tab, the import dialog, the Proposals tab and
My secrets. It keeps the existing data and API calls.
> - The benefit is a list that shows what a person manages, a create
flow with two fields, and a secret that an agent can use as soon as it
is saved.
## Linked Issues or Issue Description
**What existing behavior does this improve?**
The Settings → Secrets page, its New secret dialog, the secret details
panel, the Vaults tab, the import-from-vault dialog, the Proposals tab
and the My secrets tab.
**Subsystem affected**
UI: `ui/src/pages/Secrets.tsx` and `ui/src/pages/secrets/*`.
**Current behavior**
- One table lists all secrets. On a busy organization most rows are
credentials that Paperclip saved itself, and many have record IDs as
names.
- Each row shows Active, a version, a chip and the key. The row does not
show which agents use the secret.
- A three-line help banner is always visible.
- New secret starts with two mode switches (Organization / Each user,
Managed value / External reference), then a provider picker and a vault
picker. The Create button is disabled without a reason.
- The details panel has Details, Usage and Access events tabs.
- The Vaults tab has one section per provider, with empty placeholder
boxes and a status picker in the form.
**Proposed behavior**
- The list shows the secrets that the team added. Each row shows who
provides the value (Organization, or Each user with a count) and which
agents use it.
- Credentials that Paperclip saved collapse into "Managed by Paperclip".
They are grouped by origin and have readable names.
- One Filter menu covers provided-by, storage and status. Active filters
show as chips. Archived secrets stay hidden until a person asks for
them.
- New secret has a name, one explicit Organization / Each user choice, a
masked value, an optional list of agents, and "Stored in" only when more
than one storage place exists. Create stays enabled and says what is
missing. A `NAME=value` pasted into Name fills both fields.
- The details panel is one scrolling view: agents, other places the
secret is set, details, and recent activity.
- The Vaults tab is one flat list with health and secret counts. The
connect dialog has two required fields. Paperclip checks a new vault
immediately after it is saved.
**Reason and benefit**
A person can find their own secrets, see if a secret is used, and create
a secret that an agent can use in one step.
**Breaking changes**
None. The API gains one optional query parameter (`order` on the board
proposals list). The default order is unchanged. See Risks for the UI
behaviors that changed.
## What Changed
- **List.** Rewrote the Secrets tab in `Secrets.tsx`. Added
`secret-list-parts.tsx` for the Provided by and Used by cells, the help
popover and the managed groups. The Folders / Flat toggle is removed.
Folders are always on and search covers all folders.
- **Managed grouping.** Added `secret-origin.ts`. It infers the origin
of a secret from the name and key conventions of the server modules that
create secrets (`tool_app.*`, `tool_oauth.*`, `slack_manager.*`,
`chat.*`, `ai_*`, `routine-*`, `agent-observability.*`). It is used for
presentation only.
- **Agent usage.** Added `agent-secret-access.ts`. It holds the grant
and revoke logic that was inside the details panel, and builds one usage
index from the agents list for all rows.
- **New secret.** Rewrote the dialog. Added `buildCreateVaultOptions`
and `parseEnvAssignment`. Agents selected in the dialog get an
environment variable binding after the secret is saved. A failed grant
shows an error and keeps the secret.
- **Details.** Replaced the tabs with sections. "Also set in" lists the
bindings that are not agents. Activity shows agent names and the last
five entries, with "Show all activity".
- **Vaults.** Flat list with a built-in Paperclip row, a Default badge
that follows `getSelectableProviderConfig`, Check again, Enable, and an
Add vault menu. The dialog has Name and AWS region, with naming and tags
in a disclosure. The Status picker is removed.
- **Import, Proposals, My secrets.** Restyled to the same design.
Proposals adds a Recently decided list. The board list endpoint `GET
/api/companies/{companyId}/secret-proposals` takes a new optional
`order=resolved` to sort by decision time.
- **Copy.** "Provider vault" is "vault". "Local encrypted" is
"Paperclip" or "Paperclip-encrypted". Toasts and block reasons use plain
words.
- **Stories.** `secrets.stories.tsx` has new stories for the managed
section, a folder, New secret, the details panel and Vaults. The
Storybook usage fixture now returns the `target` field that the API
returns.
- **Tests.** Updated the page, import, proposals and My secrets tests.
Added `secret-origin.test.ts`. Updated the runner E2E vault-reference
journey and the Storybook visual render-state copy for the new labels.
- **Docs.** `Secrets → Provider vaults` is now `Secrets → Vaults` in
three documents.
`Secrets.tsx` was 4,855 lines and is 4,951 lines. The redesign edits the
page in place to keep its queries, mutations and deep links. Splitting
the file is a separate change.
## Verification
- `cd ui && node ../scripts/run-tsc.mjs -b`: no errors.
- `cd ui && pnpm vitest run src/pages/secrets src/pages/Secrets.test.ts
src/pages/Secrets.render.test.tsx
src/components/AgentSecretAccessEditor.test.tsx
src/components/AgentConfigForm src/components/IssueThreadInteractionCard
storybook/map-tooling.test.ts`: 14 files, 467 tests passed.
- `cd server && pnpm vitest run
src/__tests__/secret-proposals-routes.test.ts -t "decision time"`:
passed.
- `pnpm vitest run --config tests/runner-e2e/vitest.config.ts
chat-catalog-domains/external-vault-reference
chat-catalog-domains/external-personal-secret-menu
chat-catalog-domains/external-personal-secret-entry-dialog
chat-catalog-domains/external-personal-secret.test`: 32 passed, 2
skipped.
- `node scripts/check-token-gates.mjs`, `node scripts/check-maps.mjs`,
`node scripts/check-module-boundaries.mjs`, `node
scripts/storybook-catalog.mjs`: clean.
- `pnpm verify`: exit 2. It asks for broader coverage because a runner
E2E source file changed. Required CI supplies that coverage.
- All 22 Secrets stories render and their play functions pass in
headless Chromium against a local Storybook.
- End to end, on an isolated local instance (`paperclipai worktree init
--empty`, one company, two agents), with a headless Chromium script. 16
of 16 steps passed, with no page errors:
- Empty state. Create explains missing fields.
- Create an organization secret and give an agent access. The agent's
saved config has the `secret_ref` binding.
- Paste `NAME=value`. Create an each-user secret. Add a value in My
secrets. The list shows "1 of 1 added".
- Create a folder, create a secret in it, search across folders.
- In details: add an agent, replace the value, remove the agent. The
agent's saved config changes each time.
- Disable, archive, and the Archived filter.
- Managed secrets leave the team list and show under their groups.
- Add a Paperclip-encrypted vault and an AWS vault. New secret then
shows "Stored in".
- The import dialog explains a denied vault. The Proposals tab shows its
empty state. The list at 390 px width.
- Not run: the paid runner E2E journeys. I updated
`external-vault-reference.ts` for the new labels and could not execute
it. A live AWS import, and a proposal from a real agent run, were not
exercised.
## Risks
- **Origin grouping is a heuristic.** It reads naming conventions that
live in server modules. If a module changes its naming, its secrets show
in the team list again. Nothing is hidden or blocked by it. A recorded
origin on each secret is the durable fix.
- **Removed UI.** The Folders / Flat toggle, the "View references"
dialog, the vault Status picker, and creating draft GCP or HashiCorp
vault entries from the Add vault menu. Existing draft vaults still show
and can be edited. A disabled vault now has an Enable action.
- **Default status filter.** The list now shows active and disabled
secrets. Before, it showed active secrets only.
- **Built-in storage in "Stored in".** A provider's built-in storage is
not offered once that provider has a usable vault. The form already
replaced that choice with the vault before this change.
- **Agent access at creation.** Access is a second request for each
agent after the secret is saved. If one fails, the secret exists without
that access and an error says so.
- **Automation contracts.** Labels that agents and the runner E2E
journeys depend on are kept: the key in each My secrets row, "Set
value", "Set my value", "Update my value", "Save value", and the import
dialog test IDs. The import entry point moved into the "More secret
actions" menu and the journey is updated for it.
- **Value masking** uses `-webkit-text-security`. A browser without it
shows the value as typed.
## Model Used
- Claude Fable 5.2 (`claude-fable-5-2`) through Claude Code, with tool
use, code execution and browser automation. Three delegated agents on
the same model restyled the import dialog, the Proposals tab and My
secrets.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
16 KiB
AWS Secrets Manager Provider
Operational contract for the hosted aws_secrets_manager secret provider used by Paperclip Cloud.
Scope
- Hosted provider for Paperclip-managed company and user-scoped secrets when Paperclip Cloud runs on AWS.
- Source of truth for secret values is AWS Secrets Manager, not Postgres.
- Paperclip stores only metadata needed for ownership, bindings, version selection, audit, and runtime resolution.
- AWS provider bootstrap credentials are deployment/runtime credentials, not Paperclip-managed company secrets.
- Remote import for existing AWS secrets is metadata-only. Preview/import uses AWS inventory metadata and creates Paperclip external references; it does not copy plaintext into Paperclip.
- Per-company AWS provider vaults (named instances of
aws_secrets_managerwith their own region, namespace, prefix, KMS key id, and tags) are managed in the board UI underCompany Settings → Secrets → Vaults. See Provider Vaults for the operator model and Provider Vaults API for the routes. The bootstrap trust model in this document still applies — vault config carries non-sensitive routing metadata only, never AWS credentials.
Bootstrap Trust Model
The AWS provider has a chicken-and-egg boundary: Paperclip cannot use
company_secrets to unlock the AWS provider that stores those secrets. The
initial AWS trust must exist before the Paperclip server starts.
Allowed bootstrap locations:
- Infrastructure IAM or workload identity attached to the Paperclip server runtime.
- Process environment or orchestrator secret store used to start the Paperclip server.
- Local AWS SDK sources such as
AWS_PROFILE, AWS SSO/shared config, web identity, container metadata, or instance metadata. - Short-lived shell credentials for local development only.
Do not ask operators to paste AWS root credentials or long-lived IAM user access
keys into the Paperclip board UI. Do not store those bootstrap keys in
company_secrets.
Paperclip Cloud Bootstrap
Paperclip Cloud must provision the AWS backing resources before any board user can create AWS-backed company secrets:
- Create or select the deployment KMS key.
- Create the Paperclip server runtime role for the deployment.
- Attach a minimum IAM policy scoped to the deployment Secrets Manager prefix and the configured KMS key.
- Configure the server runtime with the non-secret provider environment variables below.
- Run
paperclipai doctoror the provider health endpoint from the deployed runtime and confirm that the provider reports the expected region, prefix, deployment id, KMS setting, and AWS SDK credential source.
Once this is in place, the board UI can create Paperclip-managed AWS secrets and Paperclip will write them under the deployment/company namespace.
Self-Hosted And Local Bootstrap
Self-hosted AWS deployments should use the AWS SDK default credential provider chain. Preferred sources are role-based:
- EC2 instance profile.
- ECS task role.
- EKS IRSA or another OIDC web identity role.
- AWS SSO/shared config via
AWS_PROFILE.
Local development can use:
aws sso login --profile paperclip-dev
AWS_PROFILE=paperclip-dev \
PAPERCLIP_SECRETS_PROVIDER=aws_secrets_manager \
PAPERCLIP_SECRETS_AWS_REGION=us-east-1 \
PAPERCLIP_SECRETS_AWS_DEPLOYMENT_ID=dev-local \
PAPERCLIP_SECRETS_AWS_KMS_KEY_ID=arn:aws:kms:us-east-1:123456789012:key/abcd-... \
pnpm dev
Temporary AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY environment credentials
are acceptable only as a local break-glass or short-lived test source. They
should not be written to Paperclip config, committed to .env files, stored in
company_secrets, or used as the default Paperclip Cloud bootstrap path.
Deployment Config
Required environment variables:
PAPERCLIP_SECRETS_PROVIDER=aws_secrets_manager
PAPERCLIP_SECRETS_AWS_REGION=us-east-1
PAPERCLIP_SECRETS_AWS_DEPLOYMENT_ID=prod-us-1
PAPERCLIP_SECRETS_AWS_KMS_KEY_ID=arn:aws:kms:us-east-1:123456789012:key/abcd-...
Optional environment variables:
PAPERCLIP_SECRETS_AWS_PREFIX=paperclip
PAPERCLIP_SECRETS_AWS_ENVIRONMENT=production
PAPERCLIP_SECRETS_AWS_PROVIDER_OWNER=paperclip
PAPERCLIP_SECRETS_AWS_ENDPOINT=
PAPERCLIP_SECRETS_AWS_DELETE_RECOVERY_DAYS=30
Naming convention for Paperclip-managed secrets:
paperclip/{deploymentId}/{companyId}/{secretKey}
Tag set for Paperclip-managed secrets:
paperclip:managed-by=paperclippaperclip:provider-owner=<owner tag>paperclip:deployment-id=<deployment id>paperclip:company-id=<company id>paperclip:secret-key=<secret key>paperclip:environment=<environment tag>
When the user-secret service creates Paperclip-managed AWS values, keep them under the same deployment/company namespace. The secret-key segment should be non-sensitive and collision-safe for the user-secret value, normally derived from the definition key plus an opaque credential-owner subject. Do not put emails, personal names, OAuth scopes, ticket identifiers, or plaintext credential material in AWS secret names, descriptions, or tags.
For operator-owned external references, prefer a separate approved prefix such as:
paperclip-ext/<environment>/<company-id>/user-secrets/<definition-key>/<opaque-owner-id>
Paperclip stores the external ref and provider version as metadata. Treat those fields as secret-adjacent: they must be redacted from comments, activity logs, run transcripts, issue documents, and broad board views unless a route is explicitly designed to show sanitized provider metadata.
IAM And KMS Assumptions
Launch posture:
- One Paperclip app role per deployment.
- One deployment-scoped KMS key per deployment at launch.
- Future per-company KMS keys remain compatible because Paperclip stores provider refs and version metadata separately from values.
Minimum IAM boundary:
- Allow
secretsmanager:CreateSecret,PutSecretValue,GetSecretValue, andDeleteSecret. - Scope resources to the deployment prefix:
arn:aws:secretsmanager:<region>:<account-id>:secret:paperclip/<deployment-id>/*
- Allow
kms:Encrypt,kms:Decrypt,kms:GenerateDataKey, andkms:DescribeKeyfor the configured deployment CMK. - Deny wildcard access outside the deployment prefix.
- Prefer workload identity / role-based auth. Do not store AWS credentials inline in Paperclip config.
Example minimum policy shape:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "PaperclipDeploymentSecrets",
"Effect": "Allow",
"Action": [
"secretsmanager:CreateSecret",
"secretsmanager:PutSecretValue",
"secretsmanager:GetSecretValue",
"secretsmanager:DeleteSecret"
],
"Resource": "arn:aws:secretsmanager:<region>:<account-id>:secret:paperclip/<deployment-id>/*"
},
{
"Sid": "PaperclipDeploymentKms",
"Effect": "Allow",
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:GenerateDataKey",
"kms:DescribeKey"
],
"Resource": "arn:aws:kms:<region>:<account-id>:key/<key-id>"
}
]
}
Operational expectation:
- Paperclip-managed secrets may be deleted only by Paperclip or an operator with equivalent break-glass access.
- External references may resolve through Paperclip runtime, but Paperclip should not delete the external secret resource.
Remote Import Inventory IAM
Remote import preview needs one additional AWS permission:
{
"Sid": "PaperclipRemoteSecretInventory",
"Effect": "Allow",
"Action": "secretsmanager:ListSecrets",
"Resource": "*"
}
This is intentionally separate from the managed create/rotate/delete policy.
AWS treats ListSecrets as an account/Region inventory action; do not document
secret ARNs, names, tags, or AWS request filters as an IAM boundary for it. Use
Resource: "*" and decide whether inventory exposure is acceptable for the AWS
account and Region behind each provider vault.
Remote import preview/import must not call:
secretsmanager:GetSecretValuesecretsmanager:BatchGetSecretValuekms:Decrypt
Those permissions are only needed later when a bound runtime resolves an imported external reference. For imported refs, scope read permissions to the operator-approved external prefixes that Paperclip is allowed to consume:
{
"Sid": "PaperclipResolveImportedExternalReferences",
"Effect": "Allow",
"Action": "secretsmanager:GetSecretValue",
"Resource": [
"arn:aws:secretsmanager:<region>:<account-id>:secret:<approved-external-prefix>/*"
]
}
If selected external secrets use customer-managed KMS keys, also grant
kms:Decrypt and kms:DescribeKey on those keys. Keep managed write/delete
permissions scoped to paperclip/<deployment-id>/*; do not broaden them for
remote import.
The same rule applies to user-scoped external refs. Paperclip derives the responsible user and credential owner before resolution, but AWS IAM still decides whether the runtime role can read the selected ARN/path. If the runtime role can read a broad external prefix, that access is broader than Paperclip's metadata policy. Use dedicated provider vaults, accounts, Regions, prefixes, KMS keys, or runtime roles when provider-side isolation must match a user-secret boundary.
Safe scoping guidance:
- Prefer one Paperclip runtime role per environment/account.
- Point provider vaults at the intended AWS account and Region instead of a broad central admin role.
- Enable
ListSecretsonly in accounts where inventory exposure is acceptable. - Keep preview/import board-only; agent API keys must not call these routes.
- Treat AWS tag/name filters as search UX only, not permission enforcement.
Paperclip also blocks importing refs under its own managed namespace as
external references. Use the Paperclip-managed flow for
paperclip/{deploymentId}/{companyId}/{secretKey} resources.
Existing AWS Secrets
V1 keeps existing AWS Secrets Manager entries as linked external references, not adopted Paperclip-managed resources.
Use the Paperclip-managed flow when Paperclip should create and rotate the value. The AWS secret name is derived from deployment and company scope:
paperclip/{deploymentId}/{companyId}/{secretKey}
Use the external-reference flow when the secret already exists at an operator-owned path such as:
/paperclip-bench/anthropic_api_key
In that mode Paperclip stores only the path or ARN, resolves it at runtime, and records redacted access events. Operators rotate the actual value in AWS. Update the Paperclip reference only when the AWS path, ARN, or pinned provider version changes.
Paperclip does not currently offer an "adopt existing AWS secret" flow that takes over future
PutSecretValue writes for an arbitrary existing secret. Adding that later requires explicit
confirmation UX, scope validation, expected Paperclip tags, and security/cloud-ops review.
Data Custody
- Paperclip stores
externalRef,providerVersionRef, provider id, fingerprint hash, status, and binding metadata. - Paperclip does not store AWS secret plaintext in
company_secret_versions.material. - Runtime resolution fetches the value from AWS only when a bound consumer needs it.
Rotation Runbook
Manual Paperclip-managed rotation:
- Write the new value through the Paperclip secret rotate flow.
- Paperclip creates a new AWS secret version with
PutSecretValue. - Paperclip records the new
providerVersionRefincompany_secret_versions. - Re-run or restart affected workloads that consume
latest, or pin consumers to a specific Paperclip version before rollout when you need staged release safety.
Guidance:
- Prefer pinned Paperclip secret versions for risky rollouts.
- Treat provider-native automatic rotation as a later enhancement; current V1 flow is explicit create-new-version plus controlled rollout.
Backup And Restore Runbook
What must survive:
- Paperclip database metadata for secret ownership, bindings, status, and provider version refs.
- User-secret definitions, declarations,
company_secrets.scope = 'user'value rows, owner user ids, responsible-user snapshots, access-event metadata, and provider version refs. - AWS Secrets Manager namespace under the configured deployment prefix.
- Any operator-owned external AWS prefixes linked by user-scoped external refs.
- The configured KMS key and its decrypt permissions.
Restore checklist:
- Restore Paperclip database metadata.
- Confirm the same AWS Secrets Manager namespace still exists.
- Confirm any linked user-scoped external prefixes still exist.
- Confirm the Paperclip runtime role can call
GetSecretValueon the restored managed prefix and approved external prefixes. - Confirm the role still has decrypt access to the CMKs referenced by
PAPERCLIP_SECRETS_AWS_KMS_KEY_IDand by any external user-secret values. - Run the live smoke below or a targeted runtime secret resolution test for both a company secret and a user-secret value.
Provider Outage Runbook
Symptoms:
- Secret create/rotate/resolve operations fail with AWS provider errors.
- Agent runs fail before adapter invocation on required secret resolution.
- Remote import preview fails to list AWS inventory.
Immediate actions:
- Confirm AWS regional health and Secrets Manager availability.
- Confirm the runtime role still has
GetSecretValueand KMS decrypt permissions. - Check for accidental prefix, region, deployment id, or KMS key config drift.
- Retry a single resolution after AWS service health is green.
- If outage persists, pause high-risk runs that require secret access rather than churning retries.
Remote import-specific actions:
- Missing list permission: add
secretsmanager:ListSecretswithResource: "*"only when inventory import is approved for that vault's AWS account and Region. - Throttling: narrow the search, wait briefly, and retry with backoff. Avoid full-account enumeration.
- Invalid or stale cursor: refresh the preview and discard the old
NextToken. - Large account: load pages intentionally, keep one in-flight preview request per vault/search, and do not run background full-account crawls.
- Runtime read failure after import: verify
GetSecretValueand KMS decrypt on the selected external secret. Visibility inListSecretsdoes not prove read permission.
Incident Response Runbook
Potential incidents:
- Cross-company access caused by IAM scoping drift.
- KMS policy drift causing decrypt failures or over-broad access.
- Suspected secret exposure in logs, transcripts, or downstream agent output.
Response steps:
- Stop or pause affected Paperclip runs.
- Audit recent Paperclip secret access events for impacted secret ids and consumers.
For user-scoped incidents, include
credentialOwnerUserId,responsibleUserId, anduserSecretDefinitionIdin the review. - Audit AWS CloudTrail for
ListSecrets,GetSecretValue,PutSecretValue, andDeleteSecretcalls on the relevant vault account, Region, deployment prefix, and approved external prefixes. - Rotate impacted secrets in AWS through Paperclip-managed versioning.
- Re-scope IAM and KMS policies before resuming normal traffic.
- If a value may have reached an agent transcript or external system, treat it as exposed and rotate immediately.
Optional Live Smoke
This is safe to skip locally. Run it only against a dedicated AWS test namespace.
Prerequisites:
- AWS credentials or workload identity with the deployment-scoped IAM permissions above.
PAPERCLIP_SECRETS_PROVIDER=aws_secrets_manager- The required
PAPERCLIP_SECRETS_AWS_*environment variables set.
Suggested smoke:
- Create a test secret through the Paperclip board or API under a throwaway company.
- Confirm the resulting AWS secret name matches
paperclip/{deploymentId}/{companyId}/{secretKey}. - Rotate the secret once and confirm a new
providerVersionRefappears in Paperclip metadata. - Resolve the secret through a bound runtime path, not by adding a general-purpose reveal endpoint.
- Delete the throwaway secret and confirm AWS schedules deletion with the configured recovery window.