mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 04:21:24 +01:00
fix(routines): keep webhook secrets out of chat and link the reveal page (#21253)
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - An agent can add a webhook trigger to a routine, and the API
response includes the webhook URL and its secret
> - Paperclip redacts secrets from chat output, so a secret that an
agent writes in a reply reaches the person as `[REDACTED]`
> - An agent pasted the bearer token in chat, the person saw
`Authorization: Bearer [REDACTED]`, and had no way to get the key
> - The person can reveal a key once on the routine's Triggers page, but
the agent did not know that page
> - This pull request tells the agent never to write the secret in chat
and to link the Triggers page instead
> - The benefit is that secrets stay out of chat and the person still
gets a working key
## Linked Issues or Issue Description
**What happened?**
In the paid chat eval `routines.webhook-trigger`, the agent created a
bearer webhook trigger. Its reasoning said the token "is sensitive; but
user needs it. I'll provide it." Output redaction removed the token, so
the reply showed `Authorization: Bearer [REDACTED]` and gave no secure
way to get the key.
**Steps to reproduce**
1. Ask an agent to add a webhook to a routine so a test service can
trigger it.
2. The agent calls `POST /api/routines/{id}/triggers` and reads the
secret in the response.
3. Read the agent's reply.
**Expected behavior**
The agent shares the webhook URL and signing mode, does not write the
secret, and links the routine's Triggers page, where the person reveals
the key once.
## What Changed
- `server/src/routes/openapi.ts`: `POST /api/routines/{id}/triggers` and
`POST /api/routine-triggers/{id}/rotate-secret` now describe the secret
handling. For a signed or bearer trigger, the URL and signing mode can
be shared. With `signingMode: none` the URL alone starts the routine, so
it is treated as a credential too. The secret value, or a header that
contains it, is never written in a chat reply, comment, document or
task. The agent links `/<prefix>/routines/<routineId>/triggers`. For a
trigger still awaiting setup, the link is
`/<prefix>/routines/<routineId>/triggers?triggerSetup=<triggerId>` and
the person chooses Generate new key. Otherwise the person chooses Edit
webhook, then Replace key. These are the same controls the human webhook
setup uses.
- `server/src/__tests__/routine-webhook-secret-guidance.test.ts`: the
agent API search for both operations returns this guidance.
## Verification
- `cd server && npx vitest run
src/__tests__/routine-webhook-secret-guidance.test.ts` passes (2 tests).
The tests fail on master because the operations have no description. The
tests also check the unsigned-URL rule.
## Risks
- Low risk. Only agent-facing route descriptions change. Server-side
redaction is unchanged.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with tool use and code
execution in Claude Code.
## 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
- [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
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
500bc694b5
commit
444dc18d98
2 files changed
+25
No files matched your search
@@ -0,0 +1,16 @@
|
||||
import { expect, it } from "vitest";
|
||||
import { searchRunnerApi } from "../services/native-runtime/runner-api-catalog.js";
|
||||
|
||||
it.each([
|
||||
["routine webhook trigger", "POST /api/routines/{id}/triggers"],
|
||||
["rotate routine trigger secret", "POST /api/routine-triggers/{id}/rotate-secret"],
|
||||
])("search %j tells the agent to keep the webhook secret out of chat and where the person reveals it", (query, operationId) => {
|
||||
const operation = searchRunnerApi({ query, limit: 10 }).results.find(row => row.operationId === operationId);
|
||||
expect(operation, query).toBeDefined();
|
||||
const description = operation!.description;
|
||||
expect(description).toContain("never write its value, or a header containing it, in a chat reply");
|
||||
expect(description).toContain("/<prefix>/routines/<routineId>/triggers, as a Markdown link");
|
||||
expect(description).toContain("/<prefix>/routines/<routineId>/triggers?triggerSetup=<triggerId> and tell them to choose Generate new key");
|
||||
expect(description).toContain("Edit webhook, then Replace key");
|
||||
expect(description).toContain("With signingMode none the URL alone starts the routine, so treat that URL as a credential too");
|
||||
});
|
||||
@@ -5548,11 +5548,19 @@ registry.registerPath({
|
||||
},
|
||||
});
|
||||
|
||||
const ROUTINE_WEBHOOK_SECRET_GUIDANCE = "A webhook response includes secretMaterial.webhookUrl and secretMaterial.webhookSecret. "
|
||||
+ "The webhookSecret is a credential: never write its value, or a header containing it, in a chat reply, comment, document or task. "
|
||||
+ "For a signed or bearer trigger, the URL and signing mode may be shared in chat. With signingMode none the URL alone starts the routine, so treat that URL as a credential too and do not write it in chat. "
|
||||
+ "Instead link the person to the routine's Triggers page, /<prefix>/routines/<routineId>/triggers, as a Markdown link, where Paperclip shows a key once: "
|
||||
+ "for a trigger still awaiting setup, link /<prefix>/routines/<routineId>/triggers?triggerSetup=<triggerId> and tell them to choose Generate new key; "
|
||||
+ "otherwise tell them to choose Edit webhook, then Replace key. Replacing the key invalidates the earlier one.";
|
||||
|
||||
registry.registerPath({
|
||||
method: "post",
|
||||
path: "/api/routines/{id}/triggers",
|
||||
tags: ["routines"],
|
||||
summary: "Create a routine trigger",
|
||||
description: ROUTINE_WEBHOOK_SECRET_GUIDANCE,
|
||||
request: {
|
||||
params: z.object({ id: z.string() }),
|
||||
body: jsonBody(createRoutineTriggerSchema),
|
||||
@@ -5586,6 +5594,7 @@ registry.registerPath({
|
||||
path: "/api/routine-triggers/{id}/rotate-secret",
|
||||
tags: ["routines"],
|
||||
summary: "Rotate a routine trigger secret",
|
||||
description: ROUTINE_WEBHOOK_SECRET_GUIDANCE,
|
||||
request: {
|
||||
params: z.object({ id: z.string() }),
|
||||
body: jsonBody(rotateRoutineTriggerSecretSchema),
|
||||
|
||||
Reference in new issue
Block a user