From 6ffe9df842aae16f761fcf4ff688b1bb15c8a377 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Wed, 5 Aug 2026 10:09:17 -0500 Subject: [PATCH] fix(auth): clarify protected-agent assignment blocks (#10893) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Task assignment policies control which agents can receive work. > - Protected-agent policy flags currently stop assignment. > - The existing error says that the assignment requires approval. > - Paperclip has no approval workflow for this policy. > - This pull request models the policy as a hard block and gives the operator an action that exists. > - The benefit is accurate API guidance without weakening the existing fail-closed behavior. ## Linked Issues or Issue Description Refs #6386 **What happened?** A protected-agent assignment denial said that approval was required. No approval record or approval action existed for this policy, so the message sent agents and operators to a dead end. **Expected behavior** The authorization result must state that protected-agent policy blocks assignment. It must tell a company administrator to remove the block before retrying. **Steps to reproduce** 1. Set `authorizationPolicy.protectedAgent.requiresApproval` to `true` on a target agent. 2. Give another agent the `tasks:assign` permission. 3. Preview or attempt assignment to the protected agent. 4. Observe that the old response promises an approval step that does not exist. **Paperclip version or commit** `c54936e2e9` on `master`. **Deployment mode** Built from source. The behavior is in the core authorization service and is not deployment-specific. **Agent adapter(s) involved** Not adapter-specific. ## What Changed - Added canonical `protectedAgent.blockAssignment` and `protectedAgent.blockReason` policy fields. - Kept the legacy approval-named flags as fail-closed compatibility aliases. - Changed denial copy to name the hard block and the administrator action. - Added authorization and plugin-host regression coverage for canonical and legacy policy data. - Updated the V1 implementation contract with the protected-assignment rule. ## Verification - `pnpm exec vitest run server/src/__tests__/authorization-service.test.ts server/src/__tests__/plugin-access-authorization-host-services.test.ts` — 2 files passed, 61 tests passed. - `pnpm --filter @paperclipai/shared typecheck` — passed. - `pnpm --filter @paperclipai/server typecheck` — passed. - `pnpm --filter @paperclipai/shared build` — passed. - `pnpm --filter @paperclipai/server build` — passed. - `pnpm check:token-gates` — all gates clean. - `git diff --check public-gh/master...HEAD` — passed. The repository-wide local wrappers exceeded the execution host resource limit before they printed a final summary. The PR check loop will use GitHub CI as the complete test and build authority. ## Risks - Low: assignment remains fail-closed. The change corrects the policy name and denial guidance. - Low: legacy fields remain supported, so existing plugin-owned policy data does not change behavior. - Low: the new policy schemas allow unknown keys for forward compatibility, as the existing authorization policy schema already does. > 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, exact model ID `gpt-5`, tool-enabled coding agent with reasoning, shell, Git, and GitHub CLI access. The runtime does not expose the 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 --- doc/SPEC-implementation.md | 9 ++++ packages/shared/src/index.ts | 4 ++ packages/shared/src/trust-policy.ts | 18 +++++++ packages/shared/src/types/index.ts | 2 + packages/shared/src/validators/index.ts | 2 + .../src/validators/trust-policy.test.ts | 29 +++++++++++ .../shared/src/validators/trust-policy.ts | 16 ++++++ .../__tests__/authorization-service.test.ts | 51 +++++++++++++++++-- ...access-authorization-host-services.test.ts | 10 ++-- server/src/services/authorization.ts | 18 ++++--- 10 files changed, 144 insertions(+), 15 deletions(-) create mode 100644 packages/shared/src/validators/trust-policy.test.ts diff --git a/doc/SPEC-implementation.md b/doc/SPEC-implementation.md index 8c22d9d776..a27d3dd21e 100644 --- a/doc/SPEC-implementation.md +++ b/doc/SPEC-implementation.md @@ -646,6 +646,15 @@ The approved term set is: When multiple constraint families are present, assignment must satisfy all of them. Denials return `403` with a generic scope explanation and do not disclose details about hidden or unrelated resources. +A protected-agent hard block is represented canonically as +`authorizationPolicy.protectedAgent.blockAssignment: true`. It denies assignment +even when the caller has a broad or scoped assignment grant. A company +administrator must remove the block before assignment can be retried; no pending +approval is created. The legacy fields `protectedAgent.requiresApproval` and +`assignmentPolicy.protectedAgentRequiresApproval` remain fail-closed compatibility +aliases for the same hard block, but API denial copy must describe the block and +administrator remediation rather than promising a nonexistent approval step. + ## 9.9 Task Watchdog Authority Contract A task watchdog is a scoped execution capacity for a configured watchdog agent on one watched issue subtree. It is not a separate principal, does not inherit board auth, and does not expand the selected agent's company boundary. The server must enforce the watchdog contract from persisted watchdog configuration and run context; custom instructions and prompt text can narrow the mandate but cannot expand it. diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts index 9259598469..9715de7c8a 100644 --- a/packages/shared/src/index.ts +++ b/packages/shared/src/index.ts @@ -223,6 +223,8 @@ export { type LowTrustOutputPromotionTarget, type LowTrustBoundary, type LowTrustReviewPresetPolicy, + type AssignmentAuthorizationPolicy, + type ProtectedAgentAuthorizationPolicy, type TrustAuthorizationPolicy, type SourceTrustArtifactKind, type SourceTrustDisposition, @@ -1531,6 +1533,8 @@ export { trustPresetSchema, lowTrustBoundarySchema, lowTrustReviewPresetPolicySchema, + assignmentAuthorizationPolicySchema, + protectedAgentAuthorizationPolicySchema, trustAuthorizationPolicySchema, type PatchInstanceExperimentalSettings, type PatchInstanceSettings, diff --git a/packages/shared/src/trust-policy.ts b/packages/shared/src/trust-policy.ts index e078f11ffb..88001a8d62 100644 --- a/packages/shared/src/trust-policy.ts +++ b/packages/shared/src/trust-policy.ts @@ -38,10 +38,28 @@ export interface LowTrustReviewPresetPolicy { rawOutputDisposition: typeof LOW_TRUST_REVIEW_RAW_OUTPUT_DISPOSITION; } +export interface AssignmentAuthorizationPolicy extends Record { + mode?: "company_default" | "protected"; + /** @deprecated Use `protectedAgent.blockAssignment`. */ + protectedAgentRequiresApproval?: boolean; +} + +export interface ProtectedAgentAuthorizationPolicy extends Record { + /** Hard-block assignment until a company administrator removes the block. */ + blockAssignment?: boolean; + blockReason?: string; + /** @deprecated Legacy hard-block alias. This does not create an approval. */ + requiresApproval?: boolean; + /** @deprecated Legacy metadata retained for compatibility. */ + approvalReason?: string; +} + export interface TrustAuthorizationPolicy extends Record { trustPreset?: TrustPreset; reviewPreset?: LowTrustReviewPresetPolicy; trustBoundary?: LowTrustBoundary; + assignmentPolicy?: AssignmentAuthorizationPolicy; + protectedAgent?: ProtectedAgentAuthorizationPolicy; } export type SourceTrustArtifactKind = "issue" | "comment" | "document" | "work_product"; diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.ts index 7e0c2fcb97..e0822c7164 100644 --- a/packages/shared/src/types/index.ts +++ b/packages/shared/src/types/index.ts @@ -128,6 +128,8 @@ export { type LowTrustOutputPromotionTarget, type LowTrustBoundary, type LowTrustReviewPresetPolicy, + type AssignmentAuthorizationPolicy, + type ProtectedAgentAuthorizationPolicy, type TrustAuthorizationPolicy, } from "../trust-policy.js"; export type { diff --git a/packages/shared/src/validators/index.ts b/packages/shared/src/validators/index.ts index 0e20cbfeb5..4fc51c47ac 100644 --- a/packages/shared/src/validators/index.ts +++ b/packages/shared/src/validators/index.ts @@ -313,6 +313,8 @@ export { trustPresetSchema, lowTrustBoundarySchema, lowTrustReviewPresetPolicySchema, + assignmentAuthorizationPolicySchema, + protectedAgentAuthorizationPolicySchema, trustAuthorizationPolicySchema, sourceTrustArtifactKindSchema, sourceTrustMetadataSchema, diff --git a/packages/shared/src/validators/trust-policy.test.ts b/packages/shared/src/validators/trust-policy.test.ts new file mode 100644 index 0000000000..1fc4818984 --- /dev/null +++ b/packages/shared/src/validators/trust-policy.test.ts @@ -0,0 +1,29 @@ +import { describe, expect, it } from "vitest"; +import { trustAuthorizationPolicySchema } from "./trust-policy.js"; + +describe("trustAuthorizationPolicySchema", () => { + it("accepts an empty legacy protected-agent approval reason", () => { + const result = trustAuthorizationPolicySchema.parse({ + protectedAgent: { + requiresApproval: true, + approvalReason: "", + }, + }); + + expect(result.protectedAgent).toMatchObject({ + requiresApproval: true, + approvalReason: "", + }); + }); + + it("still requires a non-empty canonical assignment block reason", () => { + const result = trustAuthorizationPolicySchema.safeParse({ + protectedAgent: { + blockAssignment: true, + blockReason: "", + }, + }); + + expect(result.success).toBe(false); + }); +}); diff --git a/packages/shared/src/validators/trust-policy.ts b/packages/shared/src/validators/trust-policy.ts index 9252d04f91..39496b5e43 100644 --- a/packages/shared/src/validators/trust-policy.ts +++ b/packages/shared/src/validators/trust-policy.ts @@ -31,10 +31,26 @@ export const lowTrustReviewPresetPolicySchema = z.object({ rawOutputDisposition: z.literal(LOW_TRUST_REVIEW_RAW_OUTPUT_DISPOSITION), }).strict(); +export const assignmentAuthorizationPolicySchema = z.object({ + mode: z.enum(["company_default", "protected"]).optional(), + // Legacy compatibility only. This remains a hard block and never creates an approval. + protectedAgentRequiresApproval: z.boolean().optional(), +}).catchall(z.unknown()); + +export const protectedAgentAuthorizationPolicySchema = z.object({ + blockAssignment: z.boolean().optional(), + blockReason: z.string().trim().min(1).optional(), + // Legacy compatibility only. These fields do not create an approval. + requiresApproval: z.boolean().optional(), + approvalReason: z.string().optional(), +}).catchall(z.unknown()); + export const trustAuthorizationPolicySchema = z.object({ trustPreset: trustPresetSchema.optional(), reviewPreset: lowTrustReviewPresetPolicySchema.optional(), trustBoundary: lowTrustBoundarySchema.optional(), + assignmentPolicy: assignmentAuthorizationPolicySchema.optional(), + protectedAgent: protectedAgentAuthorizationPolicySchema.optional(), }).catchall(z.unknown()); export const sourceTrustArtifactKindSchema = z.enum(["issue", "comment", "document", "work_product"]); diff --git a/server/src/__tests__/authorization-service.test.ts b/server/src/__tests__/authorization-service.test.ts index 3874d5a60d..1894fc33ba 100644 --- a/server/src/__tests__/authorization-service.test.ts +++ b/server/src/__tests__/authorization-service.test.ts @@ -1081,7 +1081,7 @@ describeEmbeddedPostgres("authorization service", () => { })).resolves.toMatchObject({ allowed: false, reason: "deny_low_trust_boundary" }); }); - it("denies simple-mode assignment when the target agent requires protected-assignment approval", async () => { + it("hard-blocks assignment when the target agent blocks protected assignment", async () => { const company = await createCompany(db, "ProtectedAssignment"); const actorAgent = await createAgent(db, company.id, { role: "engineer" }); const targetAgent = await createAgent(db, company.id, { @@ -1090,17 +1090,18 @@ describeEmbeddedPostgres("authorization service", () => { authorizationPolicy: { assignmentPolicy: { mode: "protected", - protectedAgentRequiresApproval: true, }, protectedAgent: { - requiresApproval: true, - approvalReason: "Production deployment authority", + blockAssignment: true, + blockReason: "Production deployment authority", }, managedBy: "permissions-extension", }, }, }); + await grantAgentPermission(db, company.id, actorAgent.id, "tasks:assign"); + const decision = await authorizationService(db).decide({ actor: { type: "agent", agentId: actorAgent.id, companyId: company.id, source: "agent_key" }, action: "tasks:assign", @@ -1112,7 +1113,47 @@ describeEmbeddedPostgres("authorization service", () => { allowed: false, reason: "deny_policy_restricted", }); - expect(decision.explanation).toContain("requires approval"); + expect(decision.explanation).toBe( + "Target agent assignment is blocked by protected-agent policy. " + + "A company administrator can remove the assignment block, then retry.", + ); + expect(decision.explanation).not.toContain("approval"); + }); + + it("keeps legacy protected-assignment approval flags as hard blocks without approval copy", async () => { + const company = await createCompany(db, "LegacyProtectedAssignment"); + const actorAgent = await createAgent(db, company.id, { role: "engineer" }); + const targetAgent = await createAgent(db, company.id, { + role: "engineer", + permissions: { + authorizationPolicy: { + assignmentPolicy: { + mode: "protected", + protectedAgentRequiresApproval: true, + }, + protectedAgent: { + requiresApproval: true, + }, + }, + }, + }); + + await grantAgentPermission(db, company.id, actorAgent.id, "tasks:assign"); + + const decision = await authorizationService(db).decide({ + actor: { type: "agent", agentId: actorAgent.id, companyId: company.id, source: "agent_key" }, + action: "tasks:assign", + resource: { type: "issue", companyId: company.id, assigneeAgentId: targetAgent.id }, + scope: { assigneeAgentId: targetAgent.id }, + }); + + expect(decision).toMatchObject({ + allowed: false, + reason: "deny_policy_restricted", + }); + expect(decision.explanation).toContain("assignment is blocked"); + expect(decision.explanation).toContain("company administrator"); + expect(decision.explanation).not.toContain("approval"); }); it("requires an explicit grant before assigning to a private target agent", async () => { diff --git a/server/src/__tests__/plugin-access-authorization-host-services.test.ts b/server/src/__tests__/plugin-access-authorization-host-services.test.ts index 87737816a3..5b588aa8d2 100644 --- a/server/src/__tests__/plugin-access-authorization-host-services.test.ts +++ b/server/src/__tests__/plugin-access-authorization-host-services.test.ts @@ -209,11 +209,10 @@ describeEmbeddedPostgres("plugin access and authorization host services", () => policy: { assignmentPolicy: { mode: "protected", - protectedAgentRequiresApproval: true, }, protectedAgent: { - requiresApproval: true, - approvalReason: "Needs board approval", + blockAssignment: true, + blockReason: "Protected assignment", }, managedBy: "permissions-extension", }, @@ -235,12 +234,15 @@ describeEmbeddedPostgres("plugin access and authorization host services", () => ]); expect(policy.policy).toMatchObject({ - protectedAgent: { requiresApproval: true }, + protectedAgent: { blockAssignment: true }, }); expect(preview).toMatchObject({ allowed: false, reason: "deny_policy_restricted", }); + expect(preview.explanation).toContain("assignment is blocked"); + expect(preview.explanation).toContain("company administrator"); + expect(preview.explanation).not.toContain("approval"); expect(explanation).toMatchObject(preview); const injectedBoardPreview = await services.authorization.previewAssignment({ diff --git a/server/src/services/authorization.ts b/server/src/services/authorization.ts index b41b3aff2d..8ea80a41fe 100644 --- a/server/src/services/authorization.ts +++ b/server/src/services/authorization.ts @@ -221,7 +221,7 @@ function readBoolean(value: unknown): boolean | null { type AssignmentPolicyEffect = | { kind: "none" } | { kind: "restricted"; explanation: string } - | { kind: "requires_approval"; explanation: string } + | { kind: "blocked"; explanation: string } | { kind: "unknown"; explanation: string }; type AgentHierarchyRow = { id: string; reportsTo: string | null }; @@ -293,13 +293,19 @@ function evaluateAuthorizationPolicyForAssignment( }; } - const requiresApproval = + // `requiresApproval` and `protectedAgentRequiresApproval` are legacy aliases. + // They never had an approval workflow behind them, so preserve their hard-block + // behavior without continuing to promise an approval step that does not exist. + const blockAssignment = + readBoolean(protectedAgent?.blockAssignment) === true || readBoolean(protectedAgent?.requiresApproval) === true || readBoolean(assignmentPolicy?.protectedAgentRequiresApproval) === true; - if (requiresApproval) { + if (blockAssignment) { return { - kind: "requires_approval", - explanation: `${label} requires approval before task assignment.`, + kind: "blocked", + explanation: + `${label} assignment is blocked by protected-agent policy. ` + + "A company administrator can remove the assignment block, then retry.", }; } @@ -1300,7 +1306,7 @@ export function authorizationService(db: Db) { const effects = await Promise.all(checks); return ( effects.find((effect) => effect.kind === "unknown") ?? - effects.find((effect) => effect.kind === "requires_approval") ?? + effects.find((effect) => effect.kind === "blocked") ?? effects.find((effect) => effect.kind === "restricted") ?? { kind: "none" } );