RomanNum3ral
/
paperclip
mirror of https://github.com/paperclipai/paperclip.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
paperclip/packages/plugins/examples/plugin-file-browser-example
History
Nicky Leach fdb9a4880d
fix(security): route paperclipai CLI guidance through safe npx form (CWE-78) (#11400) 
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Paperclip provides CLI commands and guidance for operators and
agents
> - The `pnpm paperclipai` script can pass argument values through a
shell
> - Shell re-parsing can execute command substitutions inside quoted
values
> - This pull request routes guidance through inert-argv `npx
paperclipai` commands and adds regression coverage
> - The benefit is safer operator guidance across documentation and
runtime hints

## Linked Issues or Issue Description

This pull request fixes a command-injection-class defect in Paperclip
CLI guidance.

**What happened?**

The `pnpm paperclipai <sub> --flag "$VALUE"` form can re-parse argument
values through a shell. A command substitution inside a quoted value can
execute on the host.

**Expected behavior**

Paperclip guidance must pass CLI values as inert argument values.
Host-derived values must not appear in copyable commands.

**Steps to reproduce**

1. Run a Paperclip guidance command that uses the `pnpm paperclipai`
script.
2. Provide a quoted value that contains a command substitution.
3. Observe that the shell can evaluate the substitution before the CLI
starts.
4. Compare the result with the `npx paperclipai` form.

**Paperclip version or commit**

`5670984b75d109950c968542a0111ebb6967f4da`

**Deployment mode**

All deployment modes that show or use the affected CLI guidance.

**Installation method**

Built from source and installed CLI guidance.

**Agent adapter(s) involved**

Not adapter-specific (core bug).

**Database mode**

Not database-related.

**Access context**

Both.

**Additional context**

The earlier merged PR
[#11343](https://github.com/paperclipai/paperclip/pull/11343) used the
unsafe `pnpm exec paperclipai` form. This fresh PR replaces that
guidance with the safe `npx paperclipai` form.

## What Changed

- Standardize documentation and runtime hints on `npx paperclipai`.
- Remove the broken `pnpm exec paperclipai` guidance.
- Use a static `<host>` placeholder in private-hostname guidance.
- Add regression tests for unsafe forms, continued lines, static hosts,
and offline guidance.

## Verification

- `git diff --check
origin/master...origin/fix/paperclipai-cli-npx-safe-invocation` passes.
- The branch adds `server/src/__tests__/cli-invocation-safety.test.ts`
and updates private-hostname tests.
- CI must run the new tests, typecheck, lint, and build checks.
- Local Vitest execution was not available because this worktree has no
installed Vitest binary.

## Risks

- The change affects operator and agent documentation text.
- The runtime hints now show `<host>` instead of a request-derived host
value.
- No database schema or migration changes exist.
- CI will detect any missed unsafe invocation or type error.

## Model Used

OpenAI GPT-5, exact model ID `gpt-5`, with tool use and code-review
assistance. The model used repository inspection, Git operations, and PR
preparation.

## 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] CI ran the test suites and they pass; local test execution was
unavailable in this worktree
- [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 addressed all Greptile and reviewer comments before requesting
merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
 		2026-08-14 22:11:16 -07:00
..
scripts Add plugin framework and settings UI 2026-03-13 16:22:34 -05:00
src feat(mcp) [split 2/8]: add governed access contracts (#9557) 2026-07-14 12:57:20 -05:00
README.md fix(security): route paperclipai CLI guidance through safe npx form (CWE-78) (#11400) 2026-08-14 22:11:16 -07:00
package.json build(deps): bump @codemirror/view from 6.43.1 to 6.43.8 (#11321) 2026-08-13 10:06:17 -07:00
tsconfig.json Add plugin framework and settings UI 2026-03-13 16:22:34 -05:00

README.md

File Browser Example Plugin

Example Paperclip plugin that demonstrates:

  • projectSidebarItem — An optional "Files" link under each project in the sidebar that opens the project detail with this plugin’s tab selected. This is controlled by plugin settings and defaults to off.
  • detailTab (entityType project) — A project detail tab with a workspace-path selector, a desktop two-column layout (file tree left, editor right), and a mobile one-panel flow with a back button from editor to file tree, including save support.

This is a repo-local example plugin for development. It should not be assumed to ship in a generic production build unless it is explicitly included.

Slots

Slot Type Description
Files (sidebar) projectSidebarItem Optional link under each project → project detail + tab.
Files (tab) detailTab Responsive tree/editor layout with save support.

Settings

  • Show Files in Sidebar — toggles the project sidebar link on or off. Defaults to off.
  • Comment File Links — controls whether comment annotations and the comment context-menu action are shown.

Capabilities

  • ui.sidebar.register — project sidebar item
  • ui.detailTab.register — project detail tab
  • projects.read — resolve project
  • project.workspaces.read — list workspaces and read paths for file access

Worker

  • getData workspaces — ctx.projects.listWorkspaces(projectId, companyId) (ordered, primary first).
  • getData fileList — { projectId, workspaceId, directoryPath? } → list directory entries for the workspace root or a subdirectory (Node fs).
  • getData fileContent — { projectId, workspaceId, filePath } → read file content using workspace-relative paths (Node fs).
  • performAction writeFile — { projectId, workspaceId, filePath, content } → write the current editor buffer back to disk.

Local Install (Dev)

From the repo root, build the plugin and install it by local path:

pnpm --filter @paperclipai/plugin-file-browser-example build
npx paperclipai plugin install ./packages/plugins/examples/plugin-file-browser-example

To uninstall:

npx paperclipai plugin uninstall paperclip-file-browser-example --force

Local development notes:

  • Build first. The host resolves the worker from the manifest entrypoints.worker (e.g. ./dist/worker.js). Run pnpm build in the plugin directory before installing so the worker file exists.
  • Dev-only install path. This local-path install flow assumes this monorepo checkout is present on disk. For deployed installs, publish an npm package instead of depending on packages/plugins/examples/... existing on the host.
  • Reinstall after pulling. If you installed a plugin by local path before the server stored package_path, the plugin may show status error (worker not found). Uninstall and install again so the server persists the path and can activate the plugin.
  • Optional: use paperclip-plugin-dev-server for UI hot-reload with devUiUrl in plugin config.

Structure

  • src/manifest.ts — manifest with projectSidebarItem and detailTab (entityTypes ["project"]).
  • src/worker.ts — data handlers for workspaces, file list, file content.
  • src/ui/index.tsx — FilesLink (sidebar) and FilesTab (workspace path selector + two-panel file tree/editor).