Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

fix: allow verified human thread replies to use admin routes (#1134)

Joshua Francef10782add987
diff --git a/src/api/agent-api-catalog.ts b/src/api/agent-api-catalog.ts
index f872ef4bc..120472a4f 100644
--- a/src/api/agent-api-catalog.ts
+++ b/src/api/agent-api-catalog.ts
@@ -1,4 +1,5 @@
import type { CapabilityClaims } from "../auth/capability-token.ts";
+import { livePersonCapability } from "./artifact-share.ts";
interface AgentApiRoute {
method: string;
@@ -718,7 +719,7 @@ const FAMILIES: AgentApiFamily[] = [
},
{
match: (_m, p) => p.startsWith("/v1/admin/"),
- when: (v) => v.isAdmin && v.claims.liveActor === true,
+ when: (v) => v.isAdmin && livePersonCapability(v.claims),
guidance:
"Admin plane: you act AS this org admin — live-authorized per call, audited under their name; confirm before any mutation (bodies/params in the admin skill). Enforced limits: content reads work only from a DM with the admin; bulk config imports also require a DM; other mutations work anywhere; admin grant changes are portal-only and refuse agent tokens.",
routes: [
@@ -805,7 +806,7 @@ const FAMILIES: AgentApiFamily[] = [
},
{
match: () => false,
- when: (v) => v.claims.liveActor !== true && v.claims.grants?.includes("admin.sessions.read") === true,
+ when: (v) => !livePersonCapability(v.claims) && v.claims.grants?.includes("admin.sessions.read") === true,
guidance:
"This cron has a specific read-only admin grant. Use only these listed routes; flag any other admin action to a human.",
routes: [
@@ -818,28 +819,28 @@ const FAMILIES: AgentApiFamily[] = [
},
{
match: () => false,
- when: (v) => v.claims.liveActor !== true && v.claims.grants?.includes("admin.audit.read") === true,
+ when: (v) => !livePersonCapability(v.claims) && v.claims.grants?.includes("admin.audit.read") === true,
guidance:
"This cron has a specific read-only admin grant. Use only these listed routes; flag any other admin action to a human.",
routes: [{ method: "GET", path: "/v1/admin/audit", summary: "read security audit events" }],
},
{
match: () => false,
- when: (v) => v.claims.liveActor !== true && v.claims.grants?.includes("admin.metrics.read") === true,
+ when: (v) => !livePersonCapability(v.claims) && v.claims.grants?.includes("admin.metrics.read") === true,
guidance:
"This cron has a specific read-only admin grant. Use only these listed routes; flag any other admin action to a human.",
routes: [{ method: "GET", path: "/v1/admin/metrics", summary: "read usage and performance metrics" }],
},
{
match: () => false,
- when: (v) => v.claims.liveActor !== true && v.claims.grants?.includes("admin.egress.read") === true,
+ when: (v) => !livePersonCapability(v.claims) && v.claims.grants?.includes("admin.egress.read") === true,
guidance:
"This cron has a specific read-only admin grant. Use only these listed routes; flag any other admin action to a human.",
routes: [{ method: "GET", path: "/v1/admin/egress", summary: "read scope-labelled egress decisions" }],
},
{
match: () => false,
- when: (v) => v.claims.liveActor !== true && v.claims.grants?.includes("admin.files.read") === true,
+ when: (v) => !livePersonCapability(v.claims) && v.claims.grants?.includes("admin.files.read") === true,
guidance:
"This cron has a specific read-only admin grant. Use only these listed routes; flag any other admin action to a human.",
routes: [
@@ -852,7 +853,7 @@ const FAMILIES: AgentApiFamily[] = [
const WHOAMI_FOR_ALL: AgentApiFamily = {
match: () => false,
- when: (v) => !(v.isAdmin && v.claims.liveActor === true),
+ when: (v) => !(v.isAdmin && livePersonCapability(v.claims)),
routes: [
{ method: "GET", path: "/v1/admin/whoami", summary: "this user's org capabilities: {permissions, isAdmin, role?}" },
],
diff --git a/src/api/server.ts b/src/api/server.ts
index 5ca5ad465..9d2118d1b 100644
--- a/src/api/server.ts
+++ b/src/api/server.ts
@@ -33,6 +33,7 @@ import { dispatch, findRoute, run, type ApiCtx, type BaseCtx, type Route, type R
import { apiRoutes, rawRoutes } from "./routes/index.ts";
import { proxyDeploymentSubdomain } from "./routes/deployments.ts";
import { CAPABILITY_HEADER } from "./contract.ts";
+import { livePersonCapability } from "./artifact-share.ts";
const safeDecode = (s: string): string => {
try {
@@ -45,7 +46,7 @@ const safeDecode = (s: string): string => {
function capabilityAdminDenied(method: string, pathname: string, url: URL, claims: CapabilityClaims): string | null {
if (method === "GET" && pathname === "/v1/admin/whoami") return null;
if (claims.aud !== CONTROL_PLANE_AUD) return "admin routes require the per-turn agent token";
- if (claims.liveActor !== true && !unattendedAdminReadAllowed(method, pathname, claims)) {
+ if (!livePersonCapability(claims) && !unattendedAdminReadAllowed(method, pathname, claims)) {
return "admin actions through the agent require a turn the admin started themselves — autonomous turns (crons, webhooks) cannot act as an admin";
}
if (pathname.startsWith("/v1/admin/grants")) {
diff --git a/src/core/orchestrator.ts b/src/core/orchestrator.ts
index 328304dec..683579cfa 100644
--- a/src/core/orchestrator.ts
+++ b/src/core/orchestrator.ts
@@ -1387,13 +1387,14 @@ export function createOrchestrator(deps: OrchestratorDeps): Orchestrator {
if (!strictReadOnly && deps.signingSecret && deps.apiBaseUrl) {
const destination = defaultDestination;
connectorEnv.AGENT_API_URL = deps.apiBaseUrl;
- if (deps.admin && liveTurn) {
+ if (deps.admin && liveAuthorTurn) {
const status = await deps.admin
.adminStatusOf(actor)
.catch(swallowAs("orchestrator: admin status for turn", { isAdmin: false }));
actorIsOrgAdmin = status.isAdmin;
if (
actorIsOrgAdmin &&
+ liveTurn &&
useMemory &&
memoryPolicy.capture !== "off" &&
resolution.orgScopeId !== memoryScopeId
diff --git a/test/admin-agent-capability.test.ts b/test/admin-agent-capability.test.ts
index a7335a37b..59497f924 100644
--- a/test/admin-agent-capability.test.ts
+++ b/test/admin-agent-capability.test.ts
@@ -11,7 +11,7 @@ import { buildApp } from "../src/wiring.ts";
import { createKeychain } from "../src/credentials/keychain.ts";
import { deriveConnectorKey } from "../src/connectors/connector-client-store.ts";
import { createMemoryMap } from "../src/persistence/durable-map.ts";
-import { scopeId } from "../src/types.ts";
+import { scopeId, type TurnRequest } from "../src/types.ts";
import {
mintCapabilityToken,
CAPABILITY_TTL_MS,
@@ -28,6 +28,8 @@ function start() {
testConfig({
dataDir: mkdtempSync(join(tmpdir(), "admin-agent-cap-")),
signingSecret: SECRET,
+ capabilitySecret: SECRET,
+ apiBaseUrl: "http://core.example.test",
}),
);
void built.directory.replaceChannels(
@@ -49,6 +51,7 @@ function start() {
runs: built.runs,
errors: built.errors,
keychain,
+ capabilitySecret: SECRET,
signingSecret: SECRET,
});
server.listen(0);
@@ -58,7 +61,7 @@ function start() {
const capFor = async (
actorId: string,
- opts: { aud?: string | null; live?: boolean; scope?: string; grants?: string[] } = {},
+ opts: { aud?: string | null; live?: boolean; liveAuthor?: boolean; scope?: string; grants?: string[] } = {},
) => {
const aud = opts.aud === undefined ? CONTROL_PLANE_AUD : opts.aud;
return await mintCapabilityToken(
@@ -67,6 +70,7 @@ const capFor = async (
scopeId: opts.scope ?? scopeId("personal", actorId),
...(aud === null ? {} : { aud }),
...(opts.live === false ? {} : { liveActor: true }),
+ ...(opts.liveAuthor ? { liveAuthor: true } : {}),
...(opts.grants ? { grants: opts.grants } : {}),
exp: Date.now() + CAPABILITY_TTL_MS,
},
@@ -457,3 +461,105 @@ test("revoking the admin grant cuts off an already-minted token immediately", as
await s.close();
}
});
+
+for (const liveAuthor of [false, true]) {
+ test(`thread author admin access (${liveAuthor}) preserves all other authorization gates`, async () => {
+ const s = start();
+ try {
+ const cap = await capFor("admin-alice", { live: false, liveAuthor, scope: "channel:C1" });
+ const headers = { "x-agent-capability": cap, "content-type": "application/json" };
+ const path = `/v1/admin/scopes/${ORG}/security-posture`;
+ const write = await fetch(`${s.base}${path}`, {
+ method: "PUT",
+ headers,
+ body: JSON.stringify({ posture: "auto" }),
+ });
+ assert.equal(write.status, liveAuthor ? 200 : 403);
+ if (!liveAuthor) return;
+ const read = await fetch(`${s.base}/v1/admin/scopes/${ORG}`, { headers });
+ assert.equal(read.status, 200);
+ assert.equal(((await read.json()) as { securityPosture: string }).securityPosture, "auto");
+ for (const restricted of ["/v1/admin/sessions", "/v1/admin/keychain"]) {
+ assert.equal((await fetch(`${s.base}${restricted}`, { headers })).status, 403);
+ }
+ assert.equal(
+ (
+ await fetch(`${s.base}/v1/admin/grants`, {
+ method: "POST",
+ headers,
+ body: JSON.stringify({ principalId: "U9", role: "org_admin", scopeId: ORG }),
+ })
+ ).status,
+ 403,
+ );
+ const memberCap = await capFor("U1", { live: false, liveAuthor: true });
+ assert.equal(
+ (
+ await fetch(`${s.base}${path}`, {
+ method: "PUT",
+ headers: { ...headers, "x-agent-capability": memberCap },
+ body: JSON.stringify({ posture: "strict" }),
+ })
+ ).status,
+ 403,
+ );
+ await s.built.admin.revokeGrant({ id: "admin-bob", type: "internal" }, "admin-alice", ORG, "org_admin");
+ assert.equal(
+ (
+ await fetch(`${s.base}${path}`, {
+ method: "PUT",
+ headers,
+ body: JSON.stringify({ posture: "strict" }),
+ })
+ ).status,
+ 403,
+ );
+ } finally {
+ await s.close();
+ }
+ });
+}
+
+for (const [name, input, expected] of [
+ ["human thread reply", { unprompted: true, liveActor: true }, 200],
+ ["synthetic ambient wake", { unprompted: true }, 403],
+ ["bot thread reply", { unprompted: true, botActor: true }, 403],
+ ["cron", { triggered: true, surface: "cron", liveActor: true }, 403],
+ ["webhook", { triggered: true, surface: "webhook", liveActor: true }, 403],
+] satisfies Array<[string, Partial<TurnRequest>, number]>) {
+ test(`orchestrator-issued ${name} token reaches the HTTP admin gate with the right authority`, async () => {
+ const s = start();
+ try {
+ let cap: string | undefined;
+ const provision = s.built.sandbox.provision.bind(s.built.sandbox);
+ s.built.sandbox.provision = (layers, opts) => {
+ cap = opts?.env?.AGENT_API_TOKEN;
+ return provision(layers, opts);
+ };
+ const admin = { externalId: "admin-alice" };
+ const result = await s.built.app.turn({
+ surface: "test",
+ actor: admin,
+ conversation: {
+ kind: "channel",
+ threadRef: "ch:C1:reply",
+ channelRef: "C1",
+ audience: [admin],
+ publishMembers: [admin],
+ },
+ text: "!run echo ok",
+ ...input,
+ });
+ assert.equal(result.status, "ok");
+ assert.ok(cap);
+ const res = await fetch(`${s.base}/v1/admin/scopes/${ORG}/security-posture`, {
+ method: "PUT",
+ headers: { "x-agent-capability": cap, "content-type": "application/json" },
+ body: JSON.stringify({ posture: "auto" }),
+ });
+ assert.equal(res.status, expected);
+ } finally {
+ await s.close();
+ }
+ });
+}
diff --git a/test/agent-api-discovery.test.ts b/test/agent-api-discovery.test.ts
index 306a7b643..869991599 100644
--- a/test/agent-api-discovery.test.ts
+++ b/test/agent-api-discovery.test.ts
@@ -39,6 +39,7 @@ const capFor = (
opts: {
memory?: { write?: ScopeId; orgWrite?: ScopeId; read: ScopeId[] };
liveActor?: boolean;
+ liveAuthor?: boolean;
grants?: string[];
} = {},
) =>
@@ -49,6 +50,7 @@ const capFor = (
exp: Date.now() + CAPABILITY_TTL_MS,
...(opts.memory ? { memory: opts.memory } : {}),
...(opts.liveActor ? { liveActor: true } : {}),
+ ...(opts.liveAuthor ? { liveAuthor: true } : {}),
...(opts.grants ? { grants: opts.grants } : {}),
},
SECRET,
@@ -216,3 +218,26 @@ test("the catalog IS the gate: discovery rows with real paths are admitted, unli
assert.equal(agentApiMatches("GET", "/v1/sessions/abc"), false);
assert.equal(agentApiMatches("DELETE", "/v1/webhooks"), false);
});
+
+test("discovery includes admin routes for a verified human thread reply", async () => {
+ const s = await start();
+ try {
+ const { body } = await listApis(
+ s.base,
+ await capFor("admin-alice", {
+ liveAuthor: true,
+ grants: ["admin.sessions.read"],
+ }),
+ );
+ const p = paths(body);
+ assert.ok(p.includes("/v1/admin/scopes/:scopeId/:resource"));
+ assert.equal(p.filter((path) => path === "/v1/admin/whoami").length, 1);
+ assert.equal(p.filter((path) => path === "/v1/admin/scopes").length, 1);
+ assert.ok(body.guidance.some((g: string) => g.includes("confirm before any mutation")));
+ assert.ok(!body.guidance.some((g: string) => g.includes("This cron")));
+ const member = await listApis(s.base, await capFor("U1", { liveAuthor: true }));
+ assert.ok(!paths(member.body).includes("/v1/admin/scopes"));
+ } finally {
+ await s.close();
+ }
+});
diff --git a/test/orchestrator.test.ts b/test/orchestrator.test.ts
index 823733f48..ef2833742 100644
--- a/test/orchestrator.test.ts
+++ b/test/orchestrator.test.ts
@@ -1134,7 +1134,27 @@ test("admin reach rides only live, all-internal turns — autonomous and guest-a
);
claims = await verifyCapabilityToken(captured!.env!.AGENT_API_TOKEN!, TEST_CAPABILITY_SECRET);
assert.equal(claims!.liveAuthor, true, "an author-live detection turn attests authorship");
- assert.equal(claims!.liveActor, undefined, "a detection turn must never open the admin plane");
+ const threadPrompt = await app.turn({
+ surface: "test",
+ actor: admin,
+ conversation: {
+ kind: "group",
+ threadRef: "grp:G1:det",
+ channelRef: "G1",
+ audience: [admin],
+ publishMembers: [admin, { externalId: "bob" }],
+ },
+ text: "!sysprompt",
+ liveActor: true,
+ unprompted: true,
+ });
+ assert.match(threadPrompt.reply ?? "", /## Acting for an org admin/);
+
+ assert.equal(
+ claims!.liveActor,
+ undefined,
+ "a thread reply attests authorship without pretending to be an explicit mention",
+ );
assert.equal(claims!.memory?.orgWrite, undefined);
captured = undefined;
@@ -1232,6 +1252,7 @@ test("admin reach rides only live, all-internal turns — autonomous and guest-a
);
claims = await verifyCapabilityToken(captured!.env!.AGENT_API_TOKEN!, TEST_CAPABILITY_SECRET);
assert.equal(claims!.liveActor, undefined, "guest-audience turns must not attest liveness");
+ assert.equal(claims!.liveAuthor, undefined);
assert.equal(claims!.memory?.orgWrite, undefined);
for (const publishMembers of [undefined, [] as { externalId: string; orgId: string }[]]) {