[codex] Add agent permissions and controls plan (#6386)

## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies by keeping task ownership, approvals, and operator control inside one control plane. > - Agent permissions and plugin-hosted company settings sit on the boundary between autonomy and governance. > - V1 needs scoped task assignment rules, plugin extension points, and clearer company access surfaces without weakening company boundaries. > - The branch builds the core authorization service, plugin SDK/host APIs, and UI simplifications needed to support those controls. > - Paperclip EE plugin surfaces were intentionally moved out of this core PR per review direction, so this PR now carries only the public core/plugin infrastructure work. > - The latest updates preserve the PAP-9937 branch changes that belong in this PR, remove the `design/` artifacts, and exclude the experimental `plugin-briefs` package. > - Greptile feedback was applied through the authorization/audit paths and the final cleanup commit was re-reviewed at 5/5 with no unresolved Greptile threads. > - The benefit is safer assignment control with extension hooks for richer permission products while preserving simple defaults for normal operators. ## What Changed - Added scoped task-assignment authorization decisions and routed issue/agent assignment mutations through the authorization service. - Added plugin SDK and host APIs for company settings slots, authorization policy/grant management, assignment previews, and bridge invocation scope propagation. - Simplified core company access UI and moved advanced controls behind plugin-provided settings surfaces. - Added retry-now affordances for blocked issue next-step notices. - Added protected-assignment enforcement for persisted agent/project/issue policies, including explicit-grant fallback behavior. - Added incremental principal-access compatibility backfill for active agent memberships and role-default human permission grants. - Added the Markdown code block wrap action fix from the latest branch changes. - Removed `design/` artifacts from the PR and removed `packages/plugins/plugin-briefs` from the final diff. - Addressed Greptile feedback for plugin actor sanitization, legacy membership handling, audit pagination, unknown grant-scope metadata, and startup test mocks. ## Verification - `pnpm exec vitest run server/src/__tests__/access-service.test.ts server/src/__tests__/company-portability.test.ts` -> 2 files passed, 54 tests passed. - `pnpm exec vitest run server/src/__tests__/server-startup-feedback-export.test.ts server/src/__tests__/access-service.test.ts server/src/__tests__/company-portability.test.ts` -> 3 files passed, 62 tests passed. - `pnpm exec vitest run server/src/__tests__/authorization-service.test.ts server/src/__tests__/plugin-access-authorization-host-services.test.ts server/src/__tests__/server-startup-feedback-export.test.ts` -> 3 files passed, 28 tests passed. - `pnpm --filter @paperclipai/server typecheck` -> passed. - `git diff --check` -> passed. - `node ./scripts/check-docker-deps-stage.mjs` -> passed. - `CI=true pnpm install --frozen-lockfile --ignore-scripts` -> passed with no lockfile update. - `pnpm exec vitest run ui/src/components/MarkdownBody.interaction.test.tsx` -> 1 test passed. - `git ls-files design packages/plugins/plugin-briefs | wc -l` -> 0. - GitHub CI on `40cd83b53` -> all checks passed, merge state `CLEAN`. - Greptile on `40cd83b53` -> 5/5, 102 files reviewed, 0 comments/annotations added, 0 unresolved review threads. - Confirmed the PR diff contains no `design/`, `packages/plugins/plugin-briefs`, `pnpm-lock.yaml`, or `.github/workflows` changes. ## Risks - Medium: task assignment authorization paths are behaviorally stricter for protected/private policy data, so existing plugin-authored policies may block assignment until explicit grants or approval flows are configured. - Medium: plugin-host authorization APIs expand the surface area available to trusted plugins and need careful review for company scoping. - Low: startup now performs a principal-access compatibility backfill, but the migration and runtime backfill use conflict-tolerant inserts. > 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, GPT-5 coding agent, tool-enabled workflow with shell, git, and GitHub CLI access. ## 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 run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-05-22 08:12:52 -05:00
parent c91a062326
commit 38c185fb8b
102 changed files with 6744 additions and 395 deletions
@@ -0,0 +1,322 @@
+import { randomUUID } from "node:crypto";
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import {
+  activityLog,
+  agents,
+  companies,
+  companyMemberships,
+  createDb,
+  invites,
+  principalPermissionGrants,
+} from "@paperclipai/db";
+import { buildHostServices } from "../services/plugin-host-services.js";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+const pluginId = "plugin-record-id";
+
+function createEventBusStub() {
+  return {
+    forPlugin() {
+      return {
+        emit: vi.fn(),
+        subscribe: vi.fn(),
+        clear: vi.fn(),
+      };
+    },
+  } as any;
+}
+
+async function createCompany(db: ReturnType<typeof createDb>, prefix: string) {
+  return db
+    .insert(companies)
+    .values({
+      name: `${prefix} ${randomUUID()}`,
+      issuePrefix: `${prefix}${randomUUID().slice(0, 6).toUpperCase()}`,
+    })
+    .returning()
+    .then((rows) => rows[0]!);
+}
+
+describeEmbeddedPostgres("plugin access and authorization host services", () => {
+  let db!: ReturnType<typeof createDb>;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+
+  beforeAll(async () => {
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-plugin-access-authz-");
+    db = createDb(tempDb.connectionString);
+  }, 20_000);
+
+  afterEach(async () => {
+    await db.delete(activityLog);
+    await db.delete(principalPermissionGrants);
+    await db.delete(invites);
+    await db.delete(agents);
+    await db.delete(companyMemberships);
+    await db.delete(companies);
+  });
+
+  afterAll(async () => {
+    await tempDb?.cleanup();
+  });
+
+  it("rejects grant writes for principals outside the requested company", async () => {
+    const targetCompany = await createCompany(db, "PAX");
+    const otherCompany = await createCompany(db, "PAY");
+    const otherAgent = await db
+      .insert(agents)
+      .values({
+        companyId: otherCompany.id,
+        name: "Other agent",
+        role: "engineer",
+        adapterType: "process",
+        adapterConfig: {},
+        permissions: {},
+      })
+      .returning()
+      .then((rows) => rows[0]!);
+    const services = buildHostServices(db, pluginId, "permissions-extension", createEventBusStub());
+
+    await expect(
+      services.authorization.setGrants({
+        companyId: targetCompany.id,
+        principalType: "agent",
+        principalId: otherAgent.id,
+        grants: [{ permissionKey: "tasks:assign" }],
+      }),
+    ).rejects.toThrow("Agent not found");
+
+    const rows = await db.select().from(principalPermissionGrants);
+    expect(rows).toEqual([]);
+    services.dispose();
+  });
+
+  it("redacts invite token hashes and sensitive defaults from plugin invite reads", async () => {
+    const company = await createCompany(db, "PAZ");
+    const services = buildHostServices(db, pluginId, "permissions-extension", createEventBusStub());
+
+    const created = await services.access.createInvite({
+      companyId: company.id,
+      allowedJoinTypes: "human",
+      defaultsPayload: {
+        human: { role: "operator", apiKey: "secret-value" },
+        secret: "top-secret",
+      },
+    });
+
+    expect(created.token).toMatch(/^pcp_invite_/);
+    expect("tokenHash" in created).toBe(false);
+    expect(created.defaultsPayload).toMatchObject({
+      human: { role: "operator", apiKey: "***REDACTED***" },
+      secret: "***REDACTED***",
+    });
+
+    const listed = await services.access.listInvites({ companyId: company.id });
+    expect(listed.invites).toHaveLength(1);
+    expect("token" in listed.invites[0]!).toBe(false);
+    expect("tokenHash" in listed.invites[0]!).toBe(false);
+    services.dispose();
+  });
+
+  it("filters authorization audit entries by allow or deny decision details", async () => {
+    const company = await createCompany(db, "PAU");
+    const services = buildHostServices(db, pluginId, "permissions-extension", createEventBusStub());
+    await db.insert(activityLog).values([
+      {
+        companyId: company.id,
+        actorType: "agent",
+        actorId: "agent-1",
+        action: "authorization.assignment_preview",
+        entityType: "issue",
+        entityId: "issue-1",
+        details: { decision: "allow", secret: "do-not-leak" },
+        createdAt: new Date("2026-01-02T00:00:00Z"),
+      },
+      {
+        companyId: company.id,
+        actorType: "agent",
+        actorId: "agent-1",
+        action: "authorization.assignment_preview",
+        entityType: "issue",
+        entityId: "issue-2",
+        details: { reason: "deny_scope" },
+        createdAt: new Date("2026-01-03T00:00:00Z"),
+      },
+    ]);
+
+    const [allowed, denied] = await Promise.all([
+      services.authorization.searchAudit({
+        companyId: company.id,
+        action: "authorization.assignment_preview",
+        decision: "allow",
+        limit: 1,
+      }),
+      services.authorization.searchAudit({
+        companyId: company.id,
+        action: "authorization.assignment_preview",
+        decision: "deny",
+      }),
+    ]);
+
+    expect(allowed).toHaveLength(1);
+    expect(allowed[0]!.entityId).toBe("issue-1");
+    expect(allowed[0]!.details).toMatchObject({ decision: "allow", secret: "***REDACTED***" });
+    expect(denied).toHaveLength(1);
+    expect(denied[0]!.entityId).toBe("issue-2");
+    services.dispose();
+  });
+
+  it("uses persisted agent policy for plugin assignment preview and explanation", async () => {
+    const company = await createCompany(db, "PAP");
+    const [actorAgent, targetAgent] = await db
+      .insert(agents)
+      .values([
+        {
+          companyId: company.id,
+          name: "Actor agent",
+          role: "engineer",
+          adapterType: "process",
+          adapterConfig: {},
+          permissions: {},
+        },
+        {
+          companyId: company.id,
+          name: "Protected target",
+          role: "engineer",
+          adapterType: "process",
+          adapterConfig: {},
+          permissions: {},
+        },
+      ])
+      .returning();
+    await db.insert(companyMemberships).values({
+      companyId: company.id,
+      principalType: "agent",
+      principalId: actorAgent!.id,
+      status: "active",
+      membershipRole: "member",
+    });
+
+    const services = buildHostServices(db, pluginId, "permissions-extension", createEventBusStub());
+    const updatedPolicy = await services.authorization.updatePolicy({
+      companyId: company.id,
+      resourceType: "agent",
+      resourceId: targetAgent!.id,
+      policy: {
+        assignmentPolicy: {
+          mode: "protected",
+          protectedAgentRequiresApproval: true,
+        },
+        protectedAgent: {
+          requiresApproval: true,
+          approvalReason: "Needs board approval",
+        },
+        managedBy: "permissions-extension",
+      },
+    });
+    const input = {
+      companyId: company.id,
+      actor: {
+        type: "agent" as const,
+        agentId: actorAgent!.id,
+        companyId: company.id,
+        source: "agent_key" as const,
+      },
+      target: { assigneeAgentId: targetAgent!.id },
+    };
+    const [policy, preview, explanation] = await Promise.all([
+      Promise.resolve(updatedPolicy),
+      services.authorization.previewAssignment(input),
+      services.authorization.explainAssignment(input),
+    ]);
+
+    expect(policy.policy).toMatchObject({
+      protectedAgent: { requiresApproval: true },
+    });
+    expect(preview).toMatchObject({
+      allowed: false,
+      reason: "deny_policy_restricted",
+    });
+    expect(explanation).toMatchObject(preview);
+
+    const injectedBoardPreview = await services.authorization.previewAssignment({
+      companyId: company.id,
+      actor: {
+        type: "board",
+        userId: "operator",
+        companyIds: [company.id],
+        source: "local_implicit",
+        isInstanceAdmin: true,
+      } as any,
+      target: { assigneeAgentId: targetAgent!.id },
+    });
+    expect(injectedBoardPreview).toMatchObject({
+      allowed: false,
+      reason: "deny_policy_restricted",
+    });
+    services.dispose();
+  });
+
+  it("sanitizes plugin authorization policy updates and records audit activity", async () => {
+    const company = await createCompany(db, "PAS");
+    const targetAgent = await db
+      .insert(agents)
+      .values({
+        companyId: company.id,
+        name: "Policy target",
+        role: "engineer",
+        adapterType: "process",
+        adapterConfig: {},
+        permissions: {},
+      })
+      .returning()
+      .then((rows) => rows[0]!);
+    const services = buildHostServices(db, pluginId, "permissions-extension", createEventBusStub());
+
+    const updatedPolicy = await services.authorization.updatePolicy({
+      companyId: company.id,
+      resourceType: "agent",
+      resourceId: targetAgent.id,
+      policy: {
+        assignmentPolicy: { mode: "protected" },
+        apiKey: "sk-test-secret",
+        nested: {
+          authorization: "Bearer should-not-persist",
+          safeLabel: "kept",
+        },
+      },
+    });
+
+    expect(updatedPolicy.policy).toMatchObject({
+      assignmentPolicy: { mode: "protected" },
+      apiKey: "***REDACTED***",
+      nested: {
+        authorization: "***REDACTED***",
+        safeLabel: "kept",
+      },
+    });
+
+    const rows = await db.select().from(activityLog);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({
+      companyId: company.id,
+      actorType: "plugin",
+      actorId: pluginId,
+      action: "authorization.policy_updated_by_plugin",
+      entityType: "agent",
+      entityId: targetAgent.id,
+    });
+    expect(rows[0]!.details).toMatchObject({
+      hasPolicy: true,
+      sourcePluginId: pluginId,
+      sourcePluginKey: "permissions-extension",
+    });
+    expect(JSON.stringify(rows[0]!.details)).not.toContain("sk-test-secret");
+    expect(JSON.stringify(rows[0]!.details)).not.toContain("should-not-persist");
+    services.dispose();
+  });
+});