DottaandPaperclip
a9a20fb5c6
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agents need a persistent identity and a verified active run for governed access. > - Customer-success inspection needs broad reads without tenant writes or secret access. > - Ordinary board login and database credentials give more authority than this task needs. > - This pull request adds a dedicated inspection API and strict managed-run authority. > - Cloud owns short grants, human approval, replay protection, and audit records. > - The benefit is inspectable access that an operator can disable immediately. ## Linked Issues or Issue Description Refs: #15352. This change reuses the persistent Ed25519 identity from that PR. **Subsystem affected** Server authentication, pure resource readers, and the shared wire contract. **Problem or motivation** One internal Paperclip agent must inspect customer onboarding work. It must not receive owner login or database credentials. Reads must not create customer sessions, memberships, activity, or read receipts. **Proposed solution** Add disabled-by-default run authority and versioned tenant inspection endpoints. Require strict instance-bound managed-run JWTs on the home instance. Require exact-operation, single-use Cloud permits on tenants. Execute a reviewed company-scoped catalog in read-only transactions. Cloud applies seven-day stack-age eligibility and human exceptions. **Roadmap alignment** This is access support for Cloud deployments and governed agent identities. Bot creation, scheduling, scoring, and reports are separate work. The maintainer requested this implementation. ## What Changed - Reuse existing public identity reads and managed private-key injection. Reject unprovisioned keys, paused agents, ended runs, legacy signatures, and wrong instances. - Mount `/api/customer-success/v1` before actor/session synchronization. Verify Cloud permits and consume them centrally before reading. - Add explicit company-scoped database readers and bounded instruction, skill snapshot, run log, workspace, and asset reads. Preserve existing redactions and file protections. - Add protocol, security, database immutability, and managed-agent qualification tests. Add deployment and rollback documentation. ## Verification - Full `pnpm -r typecheck` and `pnpm build` passed. Server typecheck passed after review fixes. - The broad local `pnpm test:run` recorded 14,277 passes and four failures in unchanged suites: two timeouts and two PR-metadata mock assertions. All three affected suites passed on isolated reruns (36 tests). The complete CI matrix passes at the final head, including every test lane, typecheck, build, runner checks, canary dry run, and the security scan. - Focused inspection, JWT, and existing identity tests pass. The catalog test compares every public database table before and after reads. - Inspection and route-contract tests: 22 passed. The coordinated test runs a real managed process agent against separate home/customer PostgreSQL databases and a PostgreSQL broker over HTTP. It proves wake through the existing controller, bounded binary file reads, single challenge consumption across replicas, concurrent grants with a two-connection pool, scoped SQL audits, append-only runtime auditing, one-year retention, and unchanged tenant data/files. - Run the coordinated test with `PAPERCLIP_INSPECTION_CLOUD_DIST` pointing at the sibling Cloud build. Normal unit runs skip that optional private integration. - Final-head Greptile is 5/5 with no unresolved findings. - No production deployment or customer inspection occurred. ## Risks - This adds an authentication boundary. Keep both feature flags disabled until coordinated staging and canary qualification. - Cloud support must deploy after this API. Unsupported tenants fail closed. There is no owner-login or database fallback. - Existing redactions remain the content boundary. Arbitrary pasted secrets in readable prose or files may remain. - Remote files and suppressed provider traces remain unavailable. Wake can cause normal startup/background writes; test those separately. - Disable Cloud policy first during rollback. Preserve existing identity material and Cloud audit history. ## Model Used OpenAI GPT-6 (Codex), with reasoning, code execution, and browser testing. The session does not expose a more specific deployment 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 (focused checks and isolated reruns; broad-run flakes are documented 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>
5.1 KiB
Cloud customer-success inspection support
Paperclip exposes /api/customer-success/v1/run-authority and /read for the
coordinated Cloud inspection broker. This foundation supports one registered
Paperclip agent; bot creation, scheduling, scoring and reporting are separate.
The authority endpoint is disabled unless
PAPERCLIP_CUSTOMER_SUCCESS_AUTHORITY_ENABLED=true. It accepts only a strict,
current instance/company-derived managed-run JWT. It requires the authenticated
agent's existing provisioned Ed25519 identity and an active running heartbeat;
paused, cancelled/stopped, finished and unsupported-runtime agents are rejected.
No identity GET provisions keys. Normal API JWT compatibility remains unchanged;
legacy signatures are rejected specifically at this authority boundary.
Tenant reads are disabled unless
PAPERCLIP_CUSTOMER_SUCCESS_INSPECTION_ENABLED=true. Configure the public-only
PAPERCLIP_CUSTOMER_SUCCESS_INSPECTION_JWKS and the stable HTTPS
PAPERCLIP_CUSTOMER_SUCCESS_CLOUD_ORIGIN. Cloud provision/roll delivers the trust
configuration. The persisted runtime stack identity is authoritative; an explicit
PAPERCLIP_CLOUD_STACK_ID is usable on operator-configured qualification stacks.
Cloud's dedicated inspection key is distinct from the inspecting agent's key.
The tenant verifies a maximum-sixty-second, audience/type-bound Ed25519 permit with exact stack, query, grant, registered key/agent/run, request and binding version. It calls Cloud's permit-consumption endpoint before reading, so replay fencing and every inspection record live in Cloud. Cloud remains responsible for stack eligibility, seven days from creation/pooled claim, human older-stack approval, active source-run checks, limits, revocation and audits. The source run bearer is never forwarded to tenants.
The namespace terminates before actor middleware. It never creates users, memberships, sessions, run-identity snapshots, activity records or read receipts. All database readers run inside repeatable-read, read-only transactions. An explicit catalog avoids existing GET side effects such as skill reconciliation, instruction recovery/adoption and provider-trace cleanup. There is no arbitrary GET proxy, write operation or credential-resolution operation.
The catalog in services/customer-success-inspection.ts covers companies,
directory/membership/permission metadata, agents/config/instruction revisions and
public identity, tasks/comments/documents/interactions, approvals/decisions,
routines/schedules, projects/workspaces/stored repository assignments, skill
sources/versions, execution events/trace metadata, activity/costs, work products/
assets/attachments, and existing readable connections/installs/grants/catalogs.
packages/shared/src/customer-success.ts is the versioned wire contract and is
mirrored byte-for-byte in the private Cloud broker; update both together.
list/get readers enforce company scope and bounded pagination. Special
operations read instruction files without repair, installed skill snapshots,
existing run logs, workspace files through the current file-resource service,
and company-scoped storage assets. Workspace context uses an owning task and
existing project/workspace checks. Binary envelopes and inclusive byte ranges
pass through Cloud; ranges cap at 1 MiB, JSON at 2 MiB, and lists at 100 rows.
Remote or unsnapshotted resources report unavailable; large content requires
pagination or download ranges. No storage credentials or bypass URLs are issued.
Existing config/event/run redactions and path/symlink/secret-file/size restrictions remain in use. Authentication account/session, secret, private-key/encrypted-key and raw provider-trace tables/readers are excluded. Identity-enabled trace suppression stays intact. No new prose/file scanner is added; arbitrary pasted secrets in otherwise readable content may be present.
Deploy this support first, then Cloud's migration/broker/admin UI. Keep both inspection and Cloud policy disabled until staging and internal canary checks pass. Wake only idle sleeps through Cloud's existing controller; normal startup and background writes after wake are separate from the inspection read. Existing human login/Slack alerts are unchanged.
Focused verification:
pnpm exec vitest run server/src/__tests__/customer-success.test.ts \
server/src/__tests__/agent-auth-jwt.test.ts server/src/__tests__/agent-identity.test.ts
# Coordinated qualification, with the sibling Cloud build:
PAPERCLIP_INSPECTION_CLOUD_DIST=/absolute/path/paperclip-cloud/dist \
pnpm exec vitest run server/src/__tests__/customer-success-cloud.test.ts
The coordinated test uses two disposable local PostgreSQL databases, a real managed process with the existing identity/env injection, a PostgreSQL-backed Cloud broker, HTTP permit consumption, the existing wake controller with a local provider, and bounded binary file reads. It tests durable replay fencing and never touches a customer. Cloud's operations document covers enrollment, capability grants, exclusions, approval/expiry/revocation, audit retention and rollback. During rollback, disable Cloud policy first, disable tenant inspection, and preserve identity material and Cloud audit history.