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" } );