PaperClipAI/doc/ISSUE-PRIVACY.md

Private tasks and projects

Paperclip work is company-open by default. A task or project can instead be marked private when its title, discussion, documents, attachments, work products, or agent run traces should be limited to named participants.

Who can read private work

A private task is readable by its responsible user, creating user, current user or agent assignee, active task grantees, and members of its private project. Restrictions flow down through children and run-created handoffs. Sharing or assigning a task grants access to that task and its descendants; ancestors and siblings require a separate grant. An assignment grant stays active until it is explicitly revoked. Current assignment, ownership, private-project membership, and inherited access remain independent reasons for access. The sharing panel shows the source; revoking one grant does not remove other reasons. Making a parent private protects existing descendants in the same transaction. Moving a task under a private parent inherits privacy. A child cannot be made public while it inherits a private boundary; making a parent public leaves its existing private children private.

Private projects have a separate access-member list. A task-level grant can expose one task without exposing its containing private project. Direct reads by non-members return 404, and list, count, search, attention, status-card, activity, run-history, and tree-control surfaces apply the same predicate. Visible blocker and mention edges may show a locked identifier-only stub; they never include the private task's title or content.

Audit logs remain company-wide because they are the sanctioned oversight path. They contain entity identifiers rather than private task content. Dashboard and sidebar aggregate counts also remain company-wide: they may include private work in totals, but do not expose titles, descriptions, or identifiers. The issue list/count APIs themselves are viewer-filtered.

Audited break-glass

Company owners and admins do not silently inherit private-task access. A normal task detail request still returns 404. When an owner or admin has a legitimate emergency need, they must deliberately request the task with ?breakGlass=true.

Every successful break-glass read writes both:

• an issue.break_glass_read audit row containing the actor, task id, and time;
• a warning system notice on the private task so its owners can see that access occurred.

The flag does not change the canonical read predicate, create a grant, or make future reads implicit. Non-admin members and agents cannot use it.

Cloud customer-success inspection is a separate operator capability. When an operator enables it, the dedicated Cloud-signed permit can read private task content within its company scope. Ordinary users, agent API keys, and plugins cannot use that permit. Cloud enforces the inspection grant, expiration, revocation, replay protection, and audit trail; this path does not create a task grant or a task break-glass notice. Operators who require task ACLs on every content read must leave PAPERCLIP_CUSTOMER_SUCCESS_INSPECTION_ENABLED disabled. See Cloud customer-success inspection support.

Agent runs and shared-agent residual risk

Issue-bound run detail, events, transcripts, logs, and workspace operations use the task ACL. Run authority is the intersection of the agent and the run's responsible user. Reusing an agent does not transfer a different user's private-task permission. Company run lists retain only timing/status/token/cost metadata for non-members so budget oversight continues without exposing task identity or run content.

Workspace operation records retain their original task and run sources even if those entities are deleted or the operation is relinked. Deletion preserves the audit record; unresolved sources make its details and log inaccessible. A company-scoped run does not override a private task linked to the operation.

Residual risk — trusted agents (trust-agent). Paperclip enforces privacy on reads from the control plane, but an agent that legitimately processes a private task may write learned content into shared persistent memory, its home directory, an external tool, or a later public response. V1 deliberately trusts the agent not to exfiltrate that context. Use isolated execution workspaces and appropriately trusted agents for sensitive work; task ACLs are not a sandbox or data-loss-prevention system.

Plugins and notification/digest surfaces

Plugins (including any Slack notifier or digest plugin) are non-member principals: they hold no company membership, task grant, or private-project access. Rather than an allowlist of individually patched methods, the plugin host centralizes the synthetic non-member check into shared helpers (requirePluginReadableIssue, pluginReadableIssueIdsByIds, pluginRedactRelationSummary) and routes every issue-derived read through them. The complete inventory of issue-derived reads and their disposition:

• Direct issue content — issues.list (SQL predicate), issues.get, issues.listComments, issues.listAttachments, issues.getAttachmentContent, issueDocuments.list, issueDocuments.get: a private task is filtered from list results, returns null/empty on soft reads, and reports "not found" (indistinguishable from missing) on document reads.
• Subtree / orchestration — issues.getSubtree and issues.getOrchestrationSummary: a private root reports "not found"; an open root drops private descendants before any relation, document, run, or assignee is fetched, so no private row or its metadata enters the payload.
• Relationship metadata — issues.getRelations (and the summaries echoed by issues.setBlockedBy / addBlockers / removeBlockers, and the subtree relation maps): blocker/blocks edges pointing at a private task are dropped, recursing into nested terminal blockers, so its title, status, and assignee never surface even on a public task.
• Interactions — issues.listInteractions: a private task yields no interaction payloads.

A synthetic { type: "none" } actor resolves to the same public-only scope as any other non-member. This is why a digest broadcast to a shared channel — whose audience is non-members by definition — cannot carry private issue content. Writes that operate on a task must also satisfy its read predicate; plugin capabilities do not substitute for task access. Returned relationship summaries remain redacted.

There is intentionally no plugin oversight exception: unlike the company-wide audit log, no plugin read path bypasses the predicate. A plugin that must surface private work would need an explicit, separately designed oversight capability; none exists today.

Residual metadata disclosure. A plugin still learns aggregate, content-free signals about private work that mirror the accepted dashboard/count disclosure: issues.getOrchestrationSummary returns company-wide openBudgetIncidents. Its costs/token roll-up is limited to the readable subtree, and unreadable relationship edges are omitted entirely. No private title, body, comment, attachment, identifier, relationship target, or locked-edge signal is exposed.

Rollout modes

PAPERCLIP_ISSUE_PRIVACY_MODE=enforce is the default. shadow records structured would-deny decisions without enforcing them and exists only for rollout diagnosis. off disables the task predicate. Operators should not use shadow or off when private-task confidentiality is required.

The production gate includes positive and negative checks: an authorized reader can read a shared child and its descendants, an unrelated reader cannot, and a warm HTTP or live subscription loses that grant after revocation. Privacy grants are read from the database without a cross-request positive cache.

Migration and current runtime integration

Migration 0313_private_task_access.sql adds the task/project ACL tables and backfills privacy parent edges with indexed keyset batches. Run binding is derived from native task identity, explicit issue identity, or legacy issueId/taskId context. Missing source tasks remain issue-scoped tombstones. Context changes cannot turn those runs into company-wide history. The migration is idempotent for preview installs; existing explicit grants are preserved. Operators upgrading an unreleased preview should inspect root grants created under its former whole-tree sharing semantics.

Migration 0314_private_task_draft_assets.sql accompanies enforcement and binds historical inline images to their first owned task. Unbound drafts remain uploader-only under the new asset-content guard.

Both privacy migrations use the Paperclip migration executor's explicit nontransactional path. Indexes on existing tables build concurrently; invalid builds are repaired on retry. DDL statements commit individually and each 1,000-row keyset batch commits before advancing, releasing schema and row locks. The migration journal is written only after all batches succeed; an interruption leaves the migration pending and its idempotent statements can be replayed. Bootstrap uses the same executor, and other migrations retain a transaction per file. Apply these migrations with pnpm db:migrate, before enabling the new server or private-task UI.

Private output uses the same predicate on native tool searches and task context, linked approvals, training exports, execution workspace APIs, stored run-response assets, and WebSocket delivery. Workspace access requires permission for every linked task. Chat publications recheck recipient identity and task access at the provider boundary: private output is withheld from shared channels and from DMs whose known recipients no longer qualify. This does not revoke Gmail or other connection credentials; connection permissions continue to apply independently.

CI leak-test inventory

The privacy regression gate is part of the normal server Vitest suite. Its surface coverage is intentionally distributed beside the routes and services it protects:

Surface	Non-member regression coverage
Downward sharing, responsible-user intersection, mutation denial, provenance, live revocation	privacy-production-review.test.ts
Task detail, list, count, grants, documents, work products	issue-access-grants-routes.test.ts, company-search-service.test.ts
Search and machine extract	company-search-service.test.ts, company-search-extract-service.test.ts
Attention feed	attention-service.test.ts
Status-card hydrate and dry-run	status-cards.test.ts
Activity stream	activity-service.test.ts, activity-routes.test.ts
Run list, live run, detail, transcript, events, logs, operation history	heartbeat-run-privacy-routes.test.ts
Tree holds and tree control	issue-tree-control-routes.test.ts
Blocker and mention identifier-only stubs	issue-access-grants-routes.test.ts
Attachment content	issue-attachment-routes.test.ts
Private-project list and direct read	projects-list-archived-routes.test.ts
Plugin issue reads (list, get, comments, attachments, orchestration, subtree, relations, interactions, documents)	plugin-orchestration-apis.test.ts

Adding a new task-derived read surface requires a non-member fixture in this gate before the surface can ship.

Project privacy management belongs to its recorded creator (the responsible user for agent-created projects), the personal-project owner, and administrators. Project read membership alone never allows publishing the project or changing its audience. Legacy projects recover ownership from their creation audit event; when that evidence is missing, an administrator manages their privacy.

Task privacy management hints

GET /api/issues/:id/privacy-constraints is available only to a principal who can read and manage that task. It returns the blocked scope kind and whether publishing leaves a personal project. It does not return protected parent or project names, identifiers, owners, or contents. This lets task owners manage their task without requiring access to its surrounding project. Visibility writes still enforce the canonical rules under the privacy-tree lock; these hints do not authorize a write.