mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-21 08:22:20 +02:00
DottaandPaperclip
d9bcf4dfe8
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - People use experimental settings to opt into product features. > - Cloud stack Admins can manage their company, but cannot save an experiment. > - Requiring an Owner role adds unrelated privileges to this workflow. > - This pull request gives trusted Cloud stack Admins permission to update experiments. > - Other instance administration and platform settings keep their existing checks. ## Linked Issues or Issue Description **What happened?** A person with the Cloud stack Admin role receives “Instance admin access required” when they enable an experimental setting, such as Fast responses. **Expected behavior** Cloud stack Admins can save editable experimental settings. This permission does not grant general instance-admin authority. Members, Support users, and agents cannot change experiments. Cloud-managed and operator-hidden settings remain protected. **Steps to reproduce** 1. Sign into a Cloud staging workspace as a stack Admin. 2. Open Settings → Experimental. 3. Enable Experimental fast responses. 4. Observe the permission error instead of a saved setting. **Additional context** Related: #10343 introduced computed Owner elevation. #15748 added Fast responses and the company Connections settings page. The roadmap and existing PRs were checked. This is a small authorization fix for the existing settings path. ## What Changed - Derive experiment-management authority from the current trusted Cloud stack Admin role on each request. - Apply that authority only to the experimental settings PATCH route. Keep general settings, environment defaults, and task drain restricted to instance admins. - Preserve existing hidden-setting checks, managed feature restrictions, and activity records. - Add role and role-downgrade regressions, allowed and denied route cases, staging coverage, and updated OpenAPI and access documentation. ## Verification - Before the fix, the Admin fast-response request returned 403 and the new role assertions failed. The first sandboxed HTTP run could not bind local sockets; the regression run outside that sandbox reached the expected authorization failures. - Focused Cloud actor, settings route, managed-overlay, and health tests: 149 passed. - `node scripts/check-maps.mjs` and `git diff --check` pass. - `pnpm -r typecheck` and `pnpm build` pass. - Greptile reviewed commit `7c33b90066121f03183579d2fae2650755e025e4` at 5/5. Its one style finding is fixed and resolved. - The full local `pnpm test:run` did not pass. It reported two early collection failures before workspace build outputs were ready and a 15-second timeout in the unchanged AgentMail recovery test. The run was stopped after those failures while the full CI suite continued. No full local-suite pass is claimed. - The first current-head CI attempt failed the unchanged Runner test “preserves a real listening process and its marker when a health RPC times out” with `runner_remote_process_identity_unavailable` / `process_identity_changed`. The test passes in a local isolated run. This recovery does not establish the CI failure's cause. [Failed job](https://github.com/paperclipai/paperclip/actions/runs/39332989655/job/118336142261). The failed shard passed on its single rerun. The failure cause remains unconfirmed. All CI checks on commit `7c33b90066121f03183579d2fae2650755e025e4` are now green. [Final CI run](https://github.com/paperclipai/paperclip/actions/runs/39332989655). - No deployed staging behavior is claimed. Manual acceptance after deployment: as a stack Admin, enable Fast responses, reload, and confirm Connections appears. Confirm Members and Support users still cannot save experiments. ## Risks - This intentionally extends experimental settings write access to Cloud stack Admins. It does not persist an instance-admin role or expand other instance controls. - Production retains its existing managed feature policy. Staging retains its editable experiment allowlist and protected execution and owner-elevation settings. - No database migration or UI change is required. ## Model Used OpenAI Codex, based on GPT-6, with reasoning, repository tools, code execution, and browser inspection. The runtime does not expose an exact model snapshot 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 - [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>
159 lines
6.4 KiB
Markdown
159 lines
6.4 KiB
Markdown
# Installation, configuration, updates, and backups — agent access
|
|
|
|
Product map: [Installation, configuration, updates, and
|
|
backups](../feature-map/instance-operations.md).
|
|
|
|
Review date: 2026-10-12. Source commit: `f981fa3cc10cb8663a87dec60345fbff46d54d0a`.
|
|
|
|
This is a source-reviewed baseline of representative operations and known gaps.
|
|
Each capability needs operation-level review before its entire scope can be
|
|
qualified. No live agent execution is claimed. Follow the [map contract](../README.md)
|
|
for format, permission checks, evidence and maintenance.
|
|
|
|
## `install-update`
|
|
|
|
Review: `baseline`.
|
|
|
|
API: `not-applicable` — No uniform company REST updater API. Treat pre-start
|
|
installation as an operator exception or design an explicit delegated operator API.
|
|
|
|
Agent access: `operator-only` — Existing CLI install/update/rollback commands.
|
|
|
|
Policy: Local machine operator and instance-administrator authority; distinct from
|
|
company-scoped agent keys.
|
|
|
|
Evidence: `source-only` — [implementation](../../cli/src/index.ts#L91) at the reviewed
|
|
commit above.
|
|
|
|
Verification: `not-run` — exercise the listed local workflow in an authorized, owned
|
|
operator environment. Verify its isolation and result; do not count local machine
|
|
authority as company-agent API access.
|
|
|
|
Gaps: No uniform company REST updater API. Treat pre-start installation as an operator
|
|
exception or design an explicit delegated operator API.
|
|
|
|
## `server-service`
|
|
|
|
Review: `baseline`.
|
|
|
|
API: `present` — representative operation IDs:
|
|
|
|
- `GET /api/health`.
|
|
|
|
Agent access: `operator-only` — Existing CLI service/dev controls; health REST; owned
|
|
workspace services have separate agent APIs.
|
|
|
|
Policy: Local machine operator and instance-administrator authority; distinct from
|
|
company-scoped agent keys.
|
|
|
|
Evidence: `source-only` — [implementation](../../cli/src/index.ts#L91) at the reviewed
|
|
commit above.
|
|
|
|
Verification: `not-run` — exercise the listed local workflow in an authorized, owned
|
|
operator environment. Verify its isolation and result; do not count local machine
|
|
authority as company-agent API access.
|
|
|
|
Gaps: Instance start/stop and task workspace start/stop are different capabilities.
|
|
Local service control is not agent company authority.
|
|
|
|
## `configuration`
|
|
|
|
Review: `baseline`.
|
|
|
|
API: `present` — representative operation IDs:
|
|
|
|
- `GET /api/instance/settings`.
|
|
- `PATCH /api/instance/settings`.
|
|
- `GET /api/instance/settings/experimental`.
|
|
- `PATCH /api/instance/settings/experimental`.
|
|
|
|
Agent access: `restricted` — Board/admin instance settings; CLI configure/env; local
|
|
configuration files.
|
|
|
|
Policy: Local machine operator and instance-administrator authority; distinct from
|
|
company-scoped agent keys.
|
|
|
|
Evidence: `source-only` — [implementation](../../cli/src/index.ts#L91) at the reviewed
|
|
commit above.
|
|
|
|
Verification: `not-run` — assert the documented agent denial with an owned test fixture;
|
|
verify any listed agent request/result path separately. A delegated operation needs its
|
|
own policy and access review.
|
|
|
|
Gaps: Settings APIs cover parts of configuration; pre-start database/binding/storage
|
|
configuration is local operator tooling.
|
|
|
|
Cloud stack Admins may update experimental settings through the trusted Cloud
|
|
actor without receiving other instance-admin powers. This uses the current
|
|
stack role on each request; company membership alone does not grant it.
|
|
Members, Support users, agents, and ordinary self-hosted sessions remain denied.
|
|
Cloud staging exposes experimental controls to instance admins and stack Admins.
|
|
It permits saved overrides of Cloud feature defaults. This exception requires a managed instance
|
|
and a provisioner-supplied `*.staging.paperclip.app` primary hostname; request
|
|
headers do not establish staging. Ordinary board members and agents still cannot
|
|
mutate instance settings. Only an explicit feature allowlist is editable on staging. Cloud
|
|
owner-admin elevation and managed-sandbox execution policy remain managed, and
|
|
production policy and other Cloud floors remain.
|
|
Local [route tests](../../server/src/__tests__/instance-settings-routes.test.ts)
|
|
cover stack Admin experiment access and auditing, denial for other instance
|
|
controls and actor sources, hidden-setting restrictions, and a spoofed request hostname;
|
|
the [Cloud actor tests](../../server/src/middleware/cloud-tenant-actor.test.ts)
|
|
cover role changes and preserved instance-admin isolation;
|
|
no live Cloud or agent-credential verification is claimed.
|
|
|
|
## `diagnostics`
|
|
|
|
Review: `baseline`.
|
|
|
|
API: `present` — representative operation IDs:
|
|
|
|
- `GET /api/health`.
|
|
- `GET /api/liveness` and `HEAD /api/liveness` — public process startup status
|
|
and build commit only; no database readiness or workspace identity.
|
|
|
|
Liveness is anonymous and runs before actor/session resolution. Hostname and
|
|
signed-bootstrap endpoint validation still apply. It grants no instance control
|
|
authority. [Liveness tests](../../server/src/__tests__/liveness.test.ts) cover idle
|
|
drain, invalid ambient credentials, unavailable SQL, and startup recovery with
|
|
local Express fixtures; no live provider or agent access is claimed.
|
|
|
|
Agent access: `partial` — REST health plus local CLI doctor.
|
|
|
|
Policy: Local machine operator and instance-administrator authority; distinct from
|
|
company-scoped agent keys.
|
|
|
|
Evidence: `source-only` — [implementation](../../cli/src/index.ts#L91) at the reviewed
|
|
commit above.
|
|
|
|
Verification: `not-run` — exercise a listed permitted operation with actual agent
|
|
credentials/run context; inspect its result and applicable persistence/attribution.
|
|
Assert the relevant denied actor, owner, company or mode from Policy. Review the
|
|
remaining operations before qualifying the whole capability.
|
|
|
|
Gaps: Health is an API; full local doctor/repair inspects host configuration and is not
|
|
equivalent to that response.
|
|
|
|
## `backup`
|
|
|
|
Review: `baseline`.
|
|
|
|
API: `present` — representative operation IDs:
|
|
|
|
- `POST /api/instance/database-backups`.
|
|
|
|
Agent access: `restricted` — Board/admin backup API; local CLI db:backup; restore into
|
|
an authorized separate target.
|
|
|
|
Policy: Local machine operator and instance-administrator authority; distinct from
|
|
company-scoped agent keys.
|
|
|
|
Evidence: `source-only` — [implementation](../../cli/src/index.ts#L91) at the reviewed
|
|
commit above.
|
|
|
|
Verification: `not-run` — assert the documented agent denial with an owned test fixture;
|
|
verify any listed agent request/result path separately. A delegated operation needs its
|
|
own policy and access review.
|
|
|
|
Gaps: API creation exists. Restore/lifecycle are operator workflows rather than ordinary
|
|
company agent capabilities.
|