mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-07 16:11:46 +02:00
DottaandPaperclip
9dd6526b47
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The server controls secrets, host files, outbound requests, and workspace commands > - A red-team review found cases where restricted callers could cross these trust boundaries > - These cases could expose credentials or let untrusted input reach privileged resources > - This pull request applies least-privilege checks at each affected server boundary > - The benefit is safer agent execution without changing the private-instance bootstrap contract ## Linked Issues or Issue Description **What happened?** Several server paths used authorization, redaction, or content-delivery rules that were too broad. Restricted agent keys could obtain company-level operational data. Some adapter and instruction paths could reach server-owned network or file resources without the required owner approval. **Expected behavior** Paperclip must redact credential values, enforce restricted-key scopes, guard outbound network access, prevent same-origin script execution, and reserve host-level file and command controls for authorized operators. **Steps to reproduce** 1. Configure an authenticated development instance at the parent commit. 2. Exercise the affected APIs with a restricted agent key or a non-instance-admin company user. 3. Observe that the parent commit returns privileged data or accepts a privileged operation. 4. Repeat on this branch and observe a redacted response, a safe download, or an HTTP 403 response. **Paperclip version or commit** The findings reproduce from commit `39898ab22` and are fixed by this pull request. **Deployment mode** Authenticated self-hosted server and local development modes. **Installation method** Built from source with pnpm. ## What Changed - Redact generic secret `value` and `token` fields recursively in structured logs. - Classify exact and separator-suffixed `KEY` environment names as secrets in company exports. - Limit restricted self-identity responses and protect company run, log, and secret catalog APIs. - Route HTTP adapter requests through DNS-pinned SSRF protection with exact private-origin allowlisting. - Download HTML, SVG, and other script-capable assets with `nosniff` and a sandbox CSP. - Require instance-admin access for external instruction roots and exports that read them. - Block agent-authenticated host command persistence across supported workspace runtime shapes. - Apply the central runtime-management decision before workspace command controls. - Keep the documented first-user instance-admin claim contract unchanged. - Add regression tests and server-owner configuration documentation. ## Verification - `pnpm -r typecheck` passes. - The Node 24 remediation suite passes with 365 tests. It skips 25 environment-gated tests. - `pnpm build` passes under Node 24. - `git diff --check` passes. - The full local runner reaches known macOS-only general-server harness failures before the serialized route lane. The Linux PR matrix is the authoritative full-suite gate. ## Risks - Restricted agent keys now receive HTTP 403 responses from company-wide run, log, and secret catalog endpoints. - Script-capable assets now download instead of rendering inline. - External instruction roots now require instance-admin access. - Private HTTP adapter endpoints now require an exact origin in `PAPERCLIP_HTTP_ADAPTER_PRIVATE_ENDPOINT_ALLOWLIST`. - Public HTTP adapter endpoints remain enabled. Redirects and metadata or link-local targets remain blocked. - No database migration is required. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used OpenAI Codex, GPT-5. The exact serving snapshot and context-window size are not exposed. The model used tool-enabled reasoning, repository access, code execution, and test execution. ## 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 --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
204 lines
8.0 KiB
Markdown
204 lines
8.0 KiB
Markdown
# Deployment Modes
|
|
|
|
Status: Canonical deployment and auth mode model
|
|
Date: 2026-02-23
|
|
|
|
## 1. Purpose
|
|
|
|
Paperclip supports two runtime modes:
|
|
|
|
1. `local_trusted`
|
|
2. `authenticated`
|
|
|
|
`authenticated` supports two exposure policies:
|
|
|
|
1. `private`
|
|
2. `public`
|
|
|
|
This keeps one authenticated auth stack while still separating low-friction private-network defaults from internet-facing hardening requirements.
|
|
|
|
Paperclip now treats **bind** as a separate concern from auth:
|
|
|
|
- auth model: `local_trusted` vs `authenticated`, plus `private/public`
|
|
- reachability model: `server.bind = loopback | lan | tailnet | custom`
|
|
|
|
## 2. Canonical Model
|
|
|
|
| Runtime Mode | Exposure | Human auth | Primary use |
|
|
|---|---|---|---|
|
|
| `local_trusted` | n/a | No login required | Single-operator local machine workflow |
|
|
| `authenticated` | `private` | Login required | Private-network access (for example Tailscale/VPN/LAN) |
|
|
| `authenticated` | `public` | Login required | Internet-facing/cloud deployment |
|
|
|
|
## Reachability Model
|
|
|
|
| Bind | Meaning | Typical use |
|
|
|---|---|---|
|
|
| `loopback` | Listen on localhost only | default local usage, reverse-proxy deployments |
|
|
| `lan` | Listen on all interfaces (`0.0.0.0`) | LAN/VPN/private-network access |
|
|
| `tailnet` | Listen on a detected Tailscale IP | Tailscale-only access |
|
|
| `custom` | Listen on an explicit host/IP | advanced interface-specific setups |
|
|
|
|
## 3. Security Policy
|
|
|
|
## `local_trusted`
|
|
|
|
- loopback-only host binding
|
|
- no human login flow
|
|
- optimized for fastest local startup
|
|
|
|
## `authenticated + private`
|
|
|
|
- login required
|
|
- low-friction URL handling (`auto` base URL mode)
|
|
- private-host trust policy required
|
|
- Better Auth request rate limiting is off by default for private mode to keep local/LAN repair loops from locking out the operator; set `PAPERCLIP_AUTH_RATE_LIMIT_ENABLED=true` to opt in
|
|
- bind can be `loopback`, `lan`, `tailnet`, or `custom`
|
|
|
|
## `authenticated + public`
|
|
|
|
- login required
|
|
- explicit public URL required
|
|
- stricter deployment checks and failures in doctor
|
|
- Better Auth request rate limiting is on by default; set `PAPERCLIP_AUTH_RATE_LIMIT_ENABLED=false` only when an explicit front-door limiter covers the deployment
|
|
- recommended bind is `loopback` behind a reverse proxy; direct `lan/custom` is advanced
|
|
- local stdio MCP runtime slots fail closed by default; set `PAPERCLIP_TRUSTED_MCP_RUNTIME_HOST` only when a trusted worker/runtime host is configured to supervise those processes. Remote HTTP MCP remains the preferred public-hosted path.
|
|
|
|
### Paperclip Cloud warm-pool identity
|
|
|
|
A Cloud-managed warm-pool process initially boots under a `pool-*` origin. It
|
|
receives only Cloud's public verification set in
|
|
`PAPERCLIP_CLOUD_RUNTIME_IDENTITY_JWKS`. Before Cloud activates a claimed stack,
|
|
the existing server-to-server health request carries a short-lived Ed25519 JWS
|
|
that binds the immutable `PAPERCLIP_CLOUD_STACK_ID`, pool claim, previous
|
|
origin, canonical HTTPS origin, and slug. Paperclip verifies and persists that
|
|
one-time assertion, updates its live public/API URL provider, and acknowledges
|
|
the exact origin in `/api/health` before the first user request is admitted.
|
|
|
|
The Harness signing private key is never present in Paperclip, browsers, or
|
|
other tenant stacks. A different claim or destination cannot replace the
|
|
persisted identity. On restart, the durable identity is loaded before auth,
|
|
routes, and child-runtime configuration, even when provider variables are
|
|
temporarily stale. Self-hosted deployments continue to use their configured
|
|
`PAPERCLIP_PUBLIC_URL` and do not participate in this protocol.
|
|
|
|
## 4. Onboarding UX Contract
|
|
|
|
Default onboarding remains interactive and flagless:
|
|
|
|
```sh
|
|
pnpm paperclipai onboard
|
|
```
|
|
|
|
Server prompt behavior:
|
|
|
|
1. quickstart `--yes` defaults to `server.bind=loopback` and therefore `local_trusted/private`
|
|
2. advanced server setup asks reachability first:
|
|
- `Trusted local` → `bind=loopback`, `local_trusted/private`
|
|
- `Private network` → `bind=lan`, `authenticated/private`
|
|
- `Tailnet` → `bind=tailnet`, `authenticated/private`
|
|
- `Custom` → manual mode/exposure/host entry
|
|
3. raw host entry is only required for the `Custom` path
|
|
4. explicit public URL is only required for `authenticated + public`
|
|
|
|
Examples:
|
|
|
|
```sh
|
|
pnpm paperclipai onboard --yes
|
|
npx paperclipai onboard --yes --bind lan
|
|
npx paperclipai run --bind tailnet
|
|
```
|
|
|
|
`configure --section server` follows the same interactive behavior.
|
|
|
|
## 5. Doctor UX Contract
|
|
|
|
Default doctor remains flagless:
|
|
|
|
```sh
|
|
pnpm paperclipai doctor
|
|
```
|
|
|
|
Doctor reads configured mode/exposure and applies mode-aware checks. Optional override flags are secondary.
|
|
|
|
## 6. Board/User Integration Contract
|
|
|
|
Board identity must be represented by a real DB user principal for user-based features to work consistently.
|
|
|
|
Required integration points:
|
|
|
|
- real user row in `authUsers` for Board identity
|
|
- `instance_user_roles` entry for Board admin authority
|
|
- `company_memberships` integration for user-level task assignment and access
|
|
|
|
This is required because user assignment paths validate active membership for `assigneeUserId`.
|
|
|
|
## 7. Local Trusted -> Authenticated Claim Flow
|
|
|
|
When running `authenticated` mode, if the only instance admin is `local-board`, Paperclip emits a startup warning with a one-time high-entropy claim URL.
|
|
|
|
- URL format: `/board-claim/<token>?code=<code>`
|
|
- intended use: signed-in human claims board ownership
|
|
- claim action:
|
|
- promotes current signed-in user to `instance_admin`
|
|
- demotes `local-board` admin role
|
|
- ensures active owner membership for the claiming user across existing companies
|
|
|
|
This prevents lockout when a user migrates from long-running local trusted usage to authenticated mode.
|
|
|
|
## 8. First Admin Setup For Fresh Authenticated Installs
|
|
|
|
Fresh authenticated installs start in `bootstrap_pending` until the first
|
|
`instance_admin` exists.
|
|
|
|
For `authenticated/private`, Paperclip supports a browser-first setup path:
|
|
|
|
1. open the Paperclip URL from the private network or appliance UI
|
|
2. sign in or create a Paperclip account
|
|
3. choose `Claim this instance` on the setup screen
|
|
|
|
That browser claim promotes the signed-in session user to the first instance
|
|
admin and then falls through to normal onboarding. The endpoint is available
|
|
only to real browser session actors in `authenticated/private`; unauthenticated
|
|
requests, agent keys, board API keys, and local implicit board actors are
|
|
rejected.
|
|
|
|
This is intentionally a first-claim bootstrap contract: before an instance
|
|
admin exists, the first authenticated browser session that completes the claim
|
|
wins. Operators must keep a `bootstrap_pending` private deployment on a trusted
|
|
network and complete setup before admitting untrusted users. This behavior is
|
|
not an account-recovery or public-deployment mechanism.
|
|
|
|
The CLI fallback remains supported in all authenticated setup states:
|
|
|
|
```sh
|
|
pnpm paperclipai auth bootstrap-ceo
|
|
```
|
|
|
|
That command prints a one-time first-admin invite URL. Browser claim and
|
|
bootstrap invite acceptance share the same first-admin transaction, so whichever
|
|
path wins first makes later attempts return a conflict.
|
|
|
|
For `authenticated/public`, browser first-admin claim is intentionally disabled.
|
|
Public deployments must use the high-entropy bootstrap invite path unless a
|
|
future public-hosted setup design explicitly changes this policy.
|
|
|
|
## 9. Current Code Reality (As Of 2026-02-23)
|
|
|
|
- runtime values are `local_trusted | authenticated`
|
|
- `authenticated` uses Better Auth sessions and bootstrap invite flow
|
|
- `local_trusted` ensures a real local Board user principal in `authUsers` with `instance_user_roles` admin access
|
|
- company creation ensures creator membership in `company_memberships` so user assignment/access flows remain consistent
|
|
|
|
## 10. Naming and Compatibility Policy
|
|
|
|
- canonical naming is `local_trusted` and `authenticated` with `private/public` exposure
|
|
- no long-term compatibility alias layer for discarded naming variants
|
|
|
|
## 11. Relationship to Other Docs
|
|
|
|
- implementation plan: `doc/plans/2026-02-23-deployment-auth-mode-consolidation.md`
|
|
- V1 contract: `doc/SPEC-implementation.md`
|
|
- operator workflows: `doc/DEVELOPING.md` and `doc/CLI.md`
|
|
- invite/join state map: `doc/spec/invite-flow.md`
|