mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-30 13:20:54 +01:00
Devin FoleyandPaperclip
fd98075a22
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Operators inspect agent configuration to understand which credentials an agent can use. > - Agent environment bindings can contain inline values, company secret references, and user secret references. > - The Secrets page did not mount the environment editor. Inline credentials were absent, and its empty message said no secrets were bound. > - The existing environment editor already handles these binding types and redacted values. > - This PR mounts that editor on the Secrets page in both UI layouts and clarifies the empty reference message. > - Operators can inspect and edit the configured bindings. Values remain masked, and the Runtime editor remains available. ## Linked Issues or Issue Description **What happened?** An agent can receive an inline credential through its environment while its Secrets page shows no matching entry. That page only rendered the secret-reference overview and API access controls. **Expected behavior** The agent Secrets page shows existing environment bindings as well as secret references. Saved inline values stay redacted. Saving another binding preserves existing credentials. **Steps to reproduce** 1. Save an agent with an inline environment credential. 2. Open the agent Secrets page. 3. The credential row is missing, although the runtime configuration contains it. **Paperclip version or commit** Reproduced on master `27270e9bf8b7a294cf03f8b84f4857f1b1ff05c7` before the fix. Related: [#12517](https://github.com/paperclipai/paperclip/pull/12517) proposes changes to secret assignment controls. This PR covers display of existing inline environment bindings through the current editor. ## What Changed - Show the environment editor on agent Secrets pages in both UI layouts. Keep the Runtime editor available. - Change the empty overview message to describe missing company secret references. Personal references remain visible in the environment editor. - Add native and legacy agent regressions through the actual page components. - Add a browser check for masked values, secret references, save/reload, and exact credential preservation through an opaque configuration revision. - Update the feature and agent access maps for the existing UI entry point. ## Verification - Red before the fix: the native and legacy page regressions could not find the saved environment credential row. - The focused UI suites pass: 207 tests, including all four layout/adapter page cases. - The server redaction and configuration revision suites pass: 42 tests. Native Runner environment assembly suites pass: 40 tests. - An isolated Chromium flow passes against the real local API and database. It checks a masked inline value, a company secret reference, and save/reload of an added variable. It then removes the new variable and checks that the opaque server revision matches its original value. This proves that the hidden credentials survive both saves without reading them. The initial browser attempt exposed a fixture ordering assumption; the test now compares variable-name sets because PostgreSQL JSONB does not retain insertion order. - `pnpm -r typecheck`, `pnpm build`, `pnpm check:token-gates`, and `node scripts/check-maps.mjs` pass. - The full local `pnpm test:run` attempt found three failures in unchanged server fixtures. The chat-recovery case passes in isolation and in its 22-test group. The two workspace cases inherit `init.defaultBranch=main`; all 179 workspace tests pass when the child process uses `init.defaultBranch=master`, as the fixtures expect. The long local invocation was then stopped. Later local groups were not reached. All corresponding CI test shards pass. - [CI passes on the final commit](https://github.com/paperclipai/paperclip/actions/runs/40809064907). The first canary dry run found an npm version collision. Its single retry passed without a source change. - Apex passes at 5/5 on the current commit with no unresolved findings. ## Risks Low risk. The change reuses the existing editor and save path. No API, secret delivery, permission, or database contract changes. The tests cover masked values and existing references during save/reload. ## Model Used OpenAI GPT-6 through Codex, with tool use and code execution. The session does not expose a more specific model ID or context-window size. ## 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 — scoped checks pass; the full local command limits are recorded above - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
91 lines
7.1 KiB
Markdown
91 lines
7.1 KiB
Markdown
---
|
||
navigation: {"section":"Apps, channels, and extensions","sectionOrder":50,"order":50}
|
||
---
|
||
|
||
# Secrets and proposals
|
||
|
||
Operators manage company secret references, users supply their own credentials where required, and reviewers decide proposed secret changes without exposing secret values in ordinary UI evidence.
|
||
|
||
Feature ID: `secrets`.
|
||
|
||
Implementation: [secrets page](../../ui/src/pages/Secrets.tsx), [personal secrets](../../ui/src/pages/secrets/MyUserSecretsTab.tsx), [proposals](../../ui/src/pages/secrets/ProposalsTab.tsx).
|
||
|
||
Agent access: [companion](../agent-access-map/secrets.md).
|
||
|
||
## Sub-features
|
||
|
||
- `company-secrets`: `secrets/company-secrets` — create/update secret references and control their bindings.
|
||
- `user-secrets`: `secrets/user-secrets` — define required user credentials and set a value for the current user.
|
||
- `proposals`: `secrets/proposals` — review proposed changes with the appropriate authority.
|
||
- `vault-import`: `secrets/vault-import` — import eligible external-vault references through the offered flow.
|
||
- `runtime-delivery`: `secrets/runtime-delivery` — deliver only the secret references authorized for the run/actor. Agent-owned instance secrets stay in the trusted server runtime and are never delivered to an agent.
|
||
|
||
## How to get to it (user POV)
|
||
|
||
### `secret-management`
|
||
|
||
Open company Settings → Secrets and the company/personal secret views.
|
||
|
||
An agent's **Secrets** page also shows its environment variables, including
|
||
masked inline values, company secret references, and user secret references.
|
||
Environment bindings remain available from **Harness / Runtime** as well.
|
||
Save an added variable and reload to confirm that the existing masked bindings
|
||
and their secret references remain present.
|
||
|
||
### `proposal-import`
|
||
|
||
Use the Proposals tab or Import from vault where available.
|
||
|
||
## Driving it with Playwright and the Paperclip CLI
|
||
|
||
Preconditions: follow the [baseline](./README.md#before-driving-a-journey). Use dummy credentials in an isolated company, two user identities, and a test agent. Never print actual secret values in evidence.
|
||
|
||
**Operation checkpoints**
|
||
|
||
Use these checks alongside the entry-point recipes below and the operation records in the [access companion](../agent-access-map/secrets.md). Record the actual actor, surface, saved result and denial separately. Source review and linked tests do not establish a live pass.
|
||
|
||
| Capability ID | Action and persisted result | Denial, race and retry checks |
|
||
| --- | --- | --- |
|
||
| `secrets/company-secrets` | Create a dummy company reference; inspect metadata, usage and access history; update, rotate, bind, and remove separate disposable references. | Reload each change and test read versus manage authority, foreign IDs, stale bindings and in-use deletion. Metadata, errors and audit must omit values. Rotation and metadata edits have different effects. |
|
||
| `secrets/user-secrets` | Manage a credential definition and inspect coverage as an authorized operator; create, update, rotate and remove the current person’s dummy value. | Use two signed-in people. Definition/coverage authority does not grant another person’s value. Check missing values, wrong definitions, cross-company references and owner-scoped persistence. |
|
||
| `secrets/proposals` | Use an actual permitted run to propose a new secret or binding; inspect its redacted preview, withdraw one, reject one, and approve a fresh one. | Check target/value authority before applying. Test expiry, duplicate/conflicting decisions, revoked context and malformed run attribution. Inspect created reference/binding and audit once, without displaying the dummy value. |
|
||
| `secrets/vault-import` | Manage a disposable provider configuration, default and health check; preview eligible AWS references and import only selected test entries. | Check provider/admin authority, unsupported vaults, failed discovery/health, duplicate imports and foreign IDs. Imported references still need permitted value resolution; provider registration does not prove a working vault. |
|
||
| `secrets/runtime-delivery` | Bind a dummy reference to a permitted environment/config path and use the actual run to check delivery without printing the value. Inspect the agent’s permitted metadata catalog separately. | Deny ordinary agent-key value reads, user/instance-scope reads through the agent value API, and missing/wrong run or binding. Check Stop/revocation, redacted logs/errors and isolation of another person’s value. |
|
||
|
||
### `secret-management`
|
||
|
||
Automated: [secrets service](../../server/src/__tests__/secrets-service.test.ts) and [user ownership](../../server/src/__tests__/secrets-service-user-secret-owner-scoped.test.ts) cover storage/access contracts. [Instance-secret tests](../../server/src/__tests__/agent-instance-secrets.test.ts) cover local encrypted storage, owner isolation, and exclusion from ordinary bindings.
|
||
|
||
Manual: Create a dummy secret reference, bind it through a supported field, and verify its use in a harmless run without logging the value. Update it and reload. Switch users and confirm personal values remain owner-scoped and missing credentials produce an actionable state.
|
||
|
||
### `proposal-import`
|
||
|
||
Automated: [proposal routes](../../server/src/__tests__/secret-proposals-routes.test.ts) and [vault import dialog](../../ui/src/pages/secrets/ImportFromVaultDialog.test.tsx) cover route/UI layers; a real vault integration needs live validation.
|
||
|
||
Manual: Review a dummy proposal, reject one and accept another, then inspect the resulting reference state and history. Preview a vault import, select only disposable entries, and verify imported references and denied-access errors after reload.
|
||
|
||
## Gotchas
|
||
|
||
- Vault import currently targets eligible AWS Secrets Manager providers.
|
||
Organization-secret checks in local-trusted mode do not establish two-user
|
||
personal-secret ownership or actual external-vault import.
|
||
|
||
- A displayed reference name is not proof that the actor can resolve its value at runtime.
|
||
- Company secrets and user-specific values have different ownership.
|
||
- Redaction needs verification in errors, activity, and run logs as well as the form.
|
||
|
||
### Storybook verification
|
||
|
||
#### `proposals`
|
||
|
||
Capability ID: `secrets/proposals`.
|
||
|
||
Scope: ui
|
||
Storybook: Mount ProposalsTab pending secret/binding proposals, blocked authority, expired/resolved proposal, approval/rejection pending/error, and redacted metadata.
|
||
Production: GET /companies/{id}/secret-proposals and POST approve/reject must enforce company/admin/target authority, durable resolution and redaction; verified run-bound agent proposal creation is separate.
|
||
Sources: Source: [ProposalsTab.tsx](../../ui/src/pages/secrets/ProposalsTab.tsx), [secrets.ts](../../server/src/routes/secrets.ts), [secret-proposal-authorization.ts](../../server/src/services/secret-proposal-authorization.ts). Tests: [ProposalsTab.render.test.tsx](../../ui/src/pages/secrets/ProposalsTab.render.test.tsx), [secret-proposals-routes.test.ts](../../server/src/__tests__/secret-proposals-routes.test.ts)
|
||
|
||
### Documentation scope: Secrets and secret proposals
|
||
|
||
Company/user/proposal/vault and runtime-binding paths are mapped; every secret provider, rotation scenario, and delivery context needs separate validation.
|