mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-14 01:50:39 +09:00
[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>
This commit is contained in:
Dotta
GitHub
parent
c91a062326
commit
38c185fb8b
102 changed files with 6744 additions and 395 deletions
166
packages/plugins/sdk/tests/host-client-factory.test.ts
Normal file
166
packages/plugins/sdk/tests/host-client-factory.test.ts
Normal file
|
|
@ -0,0 +1,166 @@
|
|||
import { describe, expect, it, vi } from "vitest";
|
||||
|
||||
import type { HostServices } from "../src/host-client-factory.js";
|
||||
import {
|
||||
CapabilityDeniedError,
|
||||
createHostClientHandlers,
|
||||
InvocationScopeDeniedError,
|
||||
} from "../src/host-client-factory.js";
|
||||
|
||||
describe("createHostClientHandlers invocation company scope", () => {
|
||||
it("rejects company-scoped host calls outside the current invocation company", async () => {
|
||||
const projectsList = vi.fn(async () => []);
|
||||
const services = {
|
||||
projects: {
|
||||
list: projectsList,
|
||||
},
|
||||
} as unknown as HostServices;
|
||||
|
||||
const handlers = createHostClientHandlers({
|
||||
pluginId: "paperclip.test",
|
||||
capabilities: ["projects.read"],
|
||||
services,
|
||||
});
|
||||
|
||||
await expect(
|
||||
handlers["projects.list"](
|
||||
{ companyId: "company-b" },
|
||||
{ invocationScope: { companyId: "company-a" } },
|
||||
),
|
||||
).rejects.toBeInstanceOf(InvocationScopeDeniedError);
|
||||
expect(projectsList).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("filters companies.list to the current invocation company", async () => {
|
||||
const services = {
|
||||
companies: {
|
||||
list: vi.fn(async () => [
|
||||
{ id: "company-a", name: "Company A" },
|
||||
{ id: "company-b", name: "Company B" },
|
||||
]),
|
||||
},
|
||||
} as unknown as HostServices;
|
||||
|
||||
const handlers = createHostClientHandlers({
|
||||
pluginId: "paperclip.test",
|
||||
capabilities: ["companies.read"],
|
||||
services,
|
||||
});
|
||||
|
||||
await expect(
|
||||
handlers["companies.list"](
|
||||
{},
|
||||
{ invocationScope: { companyId: "company-a" } },
|
||||
),
|
||||
).resolves.toEqual([{ id: "company-a", name: "Company A" }]);
|
||||
});
|
||||
|
||||
it("rejects company-scope store access for a different company", async () => {
|
||||
const stateGet = vi.fn(async () => null);
|
||||
const services = {
|
||||
state: {
|
||||
get: stateGet,
|
||||
},
|
||||
} as unknown as HostServices;
|
||||
|
||||
const handlers = createHostClientHandlers({
|
||||
pluginId: "paperclip.test",
|
||||
capabilities: ["plugin.state.read"],
|
||||
services,
|
||||
});
|
||||
|
||||
await expect(
|
||||
handlers["state.get"](
|
||||
{ scopeKind: "company", scopeId: "company-b", stateKey: "settings" },
|
||||
{ invocationScope: { companyId: "company-a" } },
|
||||
),
|
||||
).rejects.toBeInstanceOf(InvocationScopeDeniedError);
|
||||
expect(stateGet).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it.each([
|
||||
[
|
||||
"access.members.list",
|
||||
"access.members.read",
|
||||
{ companyId: "company-a" },
|
||||
(services: HostServices) => vi.mocked(services.access.listMembers),
|
||||
],
|
||||
[
|
||||
"access.members.update",
|
||||
"access.members.write",
|
||||
{ companyId: "company-a", memberId: "member-a", patch: { status: "active" } },
|
||||
(services: HostServices) => vi.mocked(services.access.updateMember),
|
||||
],
|
||||
[
|
||||
"authorization.grants.set",
|
||||
"authorization.grants.write",
|
||||
{ companyId: "company-a", principalType: "agent", principalId: "agent-a", grants: [] },
|
||||
(services: HostServices) => vi.mocked(services.authorization.setGrants),
|
||||
],
|
||||
[
|
||||
"authorization.policies.update",
|
||||
"authorization.policies.write",
|
||||
{ companyId: "company-a", resourceType: "agent", resourceId: "agent-a", policy: null },
|
||||
(services: HostServices) => vi.mocked(services.authorization.updatePolicy),
|
||||
],
|
||||
[
|
||||
"authorization.audit.search",
|
||||
"authorization.audit.read",
|
||||
{ companyId: "company-a" },
|
||||
(services: HostServices) => vi.mocked(services.authorization.searchAudit),
|
||||
],
|
||||
] as const)(
|
||||
"rejects %s when the plugin lacks %s",
|
||||
async (method, capability, params, getDelegate) => {
|
||||
const services = {
|
||||
access: {
|
||||
listMembers: vi.fn(async () => []),
|
||||
updateMember: vi.fn(async () => ({ id: "member-a" })),
|
||||
},
|
||||
authorization: {
|
||||
setGrants: vi.fn(async () => []),
|
||||
updatePolicy: vi.fn(async () => ({ policy: null })),
|
||||
searchAudit: vi.fn(async () => []),
|
||||
},
|
||||
} as unknown as HostServices;
|
||||
const handlers = createHostClientHandlers({
|
||||
pluginId: "paperclip.test",
|
||||
capabilities: [],
|
||||
services,
|
||||
});
|
||||
|
||||
await expect(
|
||||
(handlers as Record<string, (input: unknown) => Promise<unknown>>)[method](params),
|
||||
).rejects.toMatchObject({
|
||||
name: "CapabilityDeniedError",
|
||||
message: expect.stringContaining(capability),
|
||||
});
|
||||
await expect(
|
||||
(handlers as Record<string, (input: unknown) => Promise<unknown>>)[method](params),
|
||||
).rejects.toBeInstanceOf(CapabilityDeniedError);
|
||||
expect(getDelegate(services)).not.toHaveBeenCalled();
|
||||
},
|
||||
);
|
||||
|
||||
it("checks invocation company scope before exposing authorization data", async () => {
|
||||
const searchAudit = vi.fn(async () => []);
|
||||
const services = {
|
||||
authorization: {
|
||||
searchAudit,
|
||||
},
|
||||
} as unknown as HostServices;
|
||||
const handlers = createHostClientHandlers({
|
||||
pluginId: "paperclip.test",
|
||||
capabilities: ["authorization.audit.read"],
|
||||
services,
|
||||
});
|
||||
|
||||
await expect(
|
||||
handlers["authorization.audit.search"](
|
||||
{ companyId: "company-b" },
|
||||
{ invocationScope: { companyId: "company-a" } },
|
||||
),
|
||||
).rejects.toBeInstanceOf(InvocationScopeDeniedError);
|
||||
expect(searchAudit).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
|
|
@ -1,11 +1,26 @@
|
|||
import fs from "node:fs";
|
||||
import os from "node:os";
|
||||
import path from "node:path";
|
||||
import { createInterface } from "node:readline";
|
||||
import { PassThrough } from "node:stream";
|
||||
import { pathToFileURL } from "node:url";
|
||||
|
||||
import { afterEach, describe, expect, it } from "vitest";
|
||||
|
||||
import { isWorkerEntrypoint } from "../src/worker-rpc-host.js";
|
||||
import { definePlugin } from "../src/define-plugin.js";
|
||||
import {
|
||||
createRequest,
|
||||
createErrorResponse,
|
||||
createSuccessResponse,
|
||||
isJsonRpcRequest,
|
||||
isJsonRpcResponse,
|
||||
parseMessage,
|
||||
PLUGIN_RPC_ERROR_CODES,
|
||||
serializeMessage,
|
||||
type JsonRpcResponse,
|
||||
type PluginInvocationContext,
|
||||
} from "../src/protocol.js";
|
||||
import { isWorkerEntrypoint, startWorkerRpcHost } from "../src/worker-rpc-host.js";
|
||||
|
||||
describe("isWorkerEntrypoint", () => {
|
||||
const tempRoots: string[] = [];
|
||||
|
|
@ -55,3 +70,145 @@ describe("isWorkerEntrypoint", () => {
|
|||
).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("worker invocation scope propagation", () => {
|
||||
it("keeps overlapping company scopes local to each getData invocation", async () => {
|
||||
const hostToWorker = new PassThrough();
|
||||
const workerToHost = new PassThrough();
|
||||
const hostReadline = createInterface({ input: workerToHost });
|
||||
const pending = new Map<string, (response: JsonRpcResponse) => void>();
|
||||
const nestedInvocationIds: string[] = [];
|
||||
const invocationCompanies = new Map([
|
||||
["invocation-a", "company-a"],
|
||||
["invocation-b", "company-b"],
|
||||
]);
|
||||
let releaseCompanyA: (() => void) | null = null;
|
||||
let nextRequestId = 1;
|
||||
|
||||
const plugin = definePlugin({
|
||||
async setup(ctx) {
|
||||
ctx.data.register("probe", async (params) => {
|
||||
if (params.label === "a") {
|
||||
await new Promise<void>((resolve) => {
|
||||
releaseCompanyA = resolve;
|
||||
});
|
||||
}
|
||||
const company = await ctx.companies.get(String(params.requestedCompanyId));
|
||||
return { label: params.label, company };
|
||||
});
|
||||
},
|
||||
});
|
||||
|
||||
const worker = startWorkerRpcHost({
|
||||
plugin,
|
||||
stdin: hostToWorker,
|
||||
stdout: workerToHost,
|
||||
});
|
||||
|
||||
function callWorker(method: string, params: unknown, invocation?: PluginInvocationContext) {
|
||||
const id = `host-${nextRequestId++}`;
|
||||
const request = {
|
||||
...createRequest(method, params, id),
|
||||
...(invocation ? { paperclipInvocation: invocation } : {}),
|
||||
};
|
||||
const result = new Promise<unknown>((resolve, reject) => {
|
||||
pending.set(id, (response) => {
|
||||
if ("error" in response && response.error) {
|
||||
reject(new Error(response.error.message));
|
||||
return;
|
||||
}
|
||||
resolve((response as { result?: unknown }).result);
|
||||
});
|
||||
});
|
||||
hostToWorker.write(serializeMessage(request));
|
||||
return result;
|
||||
}
|
||||
|
||||
hostReadline.on("line", (line) => {
|
||||
const message = parseMessage(line);
|
||||
if (isJsonRpcResponse(message)) {
|
||||
pending.get(String(message.id))?.(message);
|
||||
pending.delete(String(message.id));
|
||||
return;
|
||||
}
|
||||
|
||||
if (!isJsonRpcRequest(message)) return;
|
||||
if (message.method !== "companies.get") return;
|
||||
|
||||
const invocationId = (message as { paperclipInvocationId?: string }).paperclipInvocationId ?? "";
|
||||
const requestedCompanyId = (message.params as { companyId?: string }).companyId;
|
||||
const allowedCompanyId = invocationCompanies.get(invocationId);
|
||||
nestedInvocationIds.push(invocationId);
|
||||
if (requestedCompanyId !== allowedCompanyId) {
|
||||
hostToWorker.write(serializeMessage(createErrorResponse(
|
||||
message.id,
|
||||
PLUGIN_RPC_ERROR_CODES.CAPABILITY_DENIED,
|
||||
`requested company "${requestedCompanyId}" but invocation "${invocationId}" is scoped to "${allowedCompanyId}"`,
|
||||
)));
|
||||
return;
|
||||
}
|
||||
|
||||
hostToWorker.write(serializeMessage(createSuccessResponse(message.id, {
|
||||
id: requestedCompanyId,
|
||||
})));
|
||||
|
||||
if (invocationId === "invocation-b") {
|
||||
releaseCompanyA?.();
|
||||
}
|
||||
});
|
||||
|
||||
try {
|
||||
await callWorker("initialize", {
|
||||
manifest: {
|
||||
id: "paperclip.scope-test",
|
||||
apiVersion: 1,
|
||||
version: "1.0.0",
|
||||
displayName: "Scope test",
|
||||
description: "Scope test",
|
||||
author: "Paperclip",
|
||||
categories: ["automation"],
|
||||
capabilities: ["companies.read"],
|
||||
entrypoints: { worker: "dist/worker.js" },
|
||||
},
|
||||
config: {},
|
||||
instanceInfo: { instanceId: "test", hostVersion: "0.0.0" },
|
||||
apiVersion: 1,
|
||||
});
|
||||
|
||||
const companyARequest = callWorker(
|
||||
"getData",
|
||||
{
|
||||
key: "probe",
|
||||
companyId: "company-a",
|
||||
params: { label: "a", requestedCompanyId: "company-b" },
|
||||
},
|
||||
{ id: "invocation-a", scope: { companyId: "company-a" } },
|
||||
);
|
||||
const companyAExpectation = expect(companyARequest).rejects.toThrow(
|
||||
/requested company "company-b"/,
|
||||
);
|
||||
const companyBRequest = callWorker(
|
||||
"getData",
|
||||
{
|
||||
key: "probe",
|
||||
companyId: "company-b",
|
||||
params: { label: "b", requestedCompanyId: "company-b" },
|
||||
},
|
||||
{ id: "invocation-b", scope: { companyId: "company-b" } },
|
||||
);
|
||||
|
||||
await expect(companyBRequest).resolves.toEqual({
|
||||
label: "b",
|
||||
company: { id: "company-b" },
|
||||
});
|
||||
await companyAExpectation;
|
||||
|
||||
expect(nestedInvocationIds).toEqual(["invocation-b", "invocation-a"]);
|
||||
} finally {
|
||||
worker.stop();
|
||||
hostReadline.close();
|
||||
hostToWorker.destroy();
|
||||
workerToHost.destroy();
|
||||
}
|
||||
});
|
||||
});
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue