Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

Determine connector sources from existing signals (#2359)

Joshua Francea7b43df9cba3
diff --git a/plugins/onboarding/skills/onboarding/SKILL.md b/plugins/onboarding/skills/onboarding/SKILL.md
index 6658feafe..7af98fa53 100644
--- a/plugins/onboarding/skills/onboarding/SKILL.md
+++ b/plugins/onboarding/skills/onboarding/SKILL.md
@@ -45,17 +45,18 @@ them without seeing their password and can be revoked.
### Connector source first for admins
For a system-identified org admin on a human-started turn, check connector sources before
-anything else. Read the admin skill's **Check connector sources** section and silently
-call `GET /v1/admin/connector-sources`. It returns whether Composio is configured, which
-OAuth apps are configured, and the admin setup links. It never returns secrets.
-
-- `composio.configured` or a non-empty `oauth.configured`: skip silently and continue to
- the Slack bot and personal connections.
-- A failed or unavailable read is unknown, not absent. Continue onboarding without
- offering source setup.
-- Neither configured: setting one up is the admin's first task. In one short message,
- offer both options and recommend Composio, using only the returned `setup` links as
- the admin skill describes.
+anything else. Do it silently, using the signals in the admin skill's **Check connector
+sources** section:
+
+- Composio: `GET /v1/composio/toolkits` succeeds, or the org scope's `serviceCredentials`
+ has an enabled `COMPOSIO_API_KEY` env credential with a secret.
+- Own OAuth apps: the live Connected apps block lists providers.
+
+If either exists, skip silently and continue to the Slack bot and personal connections.
+If a signal is missing or a read fails, treat it as unknown, not absent, and do not offer
+setup. Only when both are confirmed absent is setting one up the admin's first task: in
+one short message, offer Composio (recommended) or the org's own OAuth apps, with the
+links the admin skill describes.
Never ask for the key or client secrets in chat, and never invent admin URLs. When they
say it is done, re-check and continue to the Slack bot and personal connections. If they
diff --git a/skills-seed/admin/SKILL.md b/skills-seed/admin/SKILL.md
index 02db68e36..0b494c4ac 100644
--- a/skills-seed/admin/SKILL.md
+++ b/skills-seed/admin/SKILL.md
@@ -67,29 +67,43 @@ GET /v1/admin/whoami → {"isAdmin":true,"role":"org_admin","scopeId":"or
## Check connector sources
During admin onboarding, check this silently before offering Slack bot setup or personal
-connections. On a human-started admin turn, read `GET /v1/admin/connector-sources` (admin
-tool action `connector_sources`). It returns metadata only, never secrets:
-
-- `composio.configured`: an enabled org service credential delivers `COMPOSIO_API_KEY`.
-- `oauth.configured`: OAuth providers with client credentials.
-- `setup`: `composioCredentialUrl`, `composioVerifierUrl`, `oauthAppsUrl`, and
- `oauthCallbackUrls` (one per provider). Any link the deployment cannot build is absent.
-
-If either source is configured, skip silently. A failed read means unknown, not absent;
-do not offer setup. Only when both are unconfigured, send one short message:
-
-- Composio (recommended): one project key covers most apps. Link `setup.composioCredentialUrl`
- to add it as an org service credential with env key `COMPOSIO_API_KEY`. If
- `setup.composioVerifierUrl` is present, give it as Composio's callback verification URL
- and point to `docs/composio.md`. If that link is absent, or they would rather paste the
+connections. A source is either Composio or the org's own OAuth apps. Never inspect
+deployment secrets.
+
+**Composio.** It is available when `GET /v1/composio/toolkits` succeeds. A
+`composio_unavailable` error only means it is not available to this person; the org may
+still have a key they are not granted. To check the org, read
+`GET /v1/admin/scopes/<org scope>?view=credentials`: a `serviceCredentials` entry with
+`enabled: true`, `hasSecret: true`, `delivery: "env"` and `envKey: "COMPOSIO_API_KEY"`
+means Composio is configured.
+
+**Own OAuth apps.** The live Connected apps block reflects the providers configured with
+client credentials, from Admin → Connectors or deployment secrets. The line "No direct
+OAuth app connections are configured" means none are, even if MCP apps appear under
+"Connected". Without that line, at least one provider is configured.
+`GET /v1/admin/scopes/<org scope>?view=connectors` shows only apps added in Admin →
+Connectors, not ones set by deployment secrets, so it cannot prove absence.
+
+Composio is absent only when the toolkits read fails and the org check finds no such
+credential. If either source exists, skip silently. If the block is missing or a read
+fails, treat it as unknown, not absent, and do not offer setup. Only when both are
+confirmed absent, send one short message:
+
+- Composio (recommended): one project key covers most apps. Add it in Admin → Credentials
+ as an org service credential with env key `COMPOSIO_API_KEY`, and set up callback
+ verification as described in QM's `docs/composio.md`. If they would rather paste the
key now, mint a one-time drop with `POST /v1/keychain/drops`
(`{"service":"composio","envKey":"COMPOSIO_API_KEY","purpose":"…"}`) and share its `url`.
A dropped key enables Composio only for them; teammates need the org credential.
-- Own OAuth apps: link `setup.oauthAppsUrl` and give the matching entry from
- `setup.oauthCallbackUrls` for each provider they want to register.
-
-Use only returned links; never invent URLs. Never ask for keys or client secrets in chat.
-Never ask regular users to configure a source.
+- Own OAuth apps: add each provider in Admin → Connectors. Each one needs the callback URL
+ `<web origin>/v1/connectors/oauth/<provider>/callback`, which the Connectors page also
+ shows.
+
+Links: the web origin is the origin of the Connection page URL in the Connected apps
+block (`<web origin>/keychain`). Link `<web origin>/admin/credentials` and
+`<web origin>/admin/connectors`. If that line is absent, name the pages without links and
+offer the drop link. Never invent URLs or ask for keys or client secrets in chat. Never
+ask regular users to configure a source.
## Guide Slack installation
diff --git a/src/api/routes/admin.ts b/src/api/routes/admin.ts
index 0dfc38cd6..efca6c9ac 100644
--- a/src/api/routes/admin.ts
+++ b/src/api/routes/admin.ts
@@ -51,7 +51,6 @@ import {
startSlackInstallation,
managedSlackRequest,
} from "./admin/slack-installation.ts";
-import { getConnectorSources } from "./admin/connector-sources.ts";
import { deleteModelProvider, getModelProviders, putModelProvider } from "./admin/model-providers.ts";
import { deleteCustomProvider, getCustomProviders, putCustomProvider } from "./admin/custom-providers.ts";
import { deleteMcpServer, getMcpServers, putMcpServer } from "./admin/mcp-servers.ts";
@@ -83,7 +82,6 @@ const routes: ReadonlyArray<Route<ApiCtx>> = [
{ method: "POST", path: "/v1/slack/managed/events", auth: "public", handle: managedSlackRequest },
{ method: "GET", path: "/v1/admin/slack-installation", auth: "either", handle: getSlackInstallation },
{ method: "GET", path: "/v1/admin/slack-emoji", auth: "either", handle: getSlackEmojiList },
- { method: "GET", path: "/v1/admin/connector-sources", auth: "either", handle: getConnectorSources },
{ method: "PUT", path: "/v1/admin/slack-installation", auth: "either", handle: putSlackInstallation },
{ method: "DELETE", path: "/v1/admin/slack-installation", auth: "either", handle: deleteSlackInstallation },
{ method: "GET", path: "/v1/admin/model-providers", auth: "either", handle: getModelProviders },
diff --git a/src/api/routes/admin/connector-sources.ts b/src/api/routes/admin/connector-sources.ts
deleted file mode 100644
index facf47767..000000000
--- a/src/api/routes/admin/connector-sources.ts
+++ /dev/null
@@ -1,49 +0,0 @@
-import { sendJson } from "../../http.ts";
-import { audit, authorizeAdmin, orgScope } from "../shared.ts";
-import type { ApiCtx } from "../route.ts";
-import { PROVIDERS } from "../../../connectors/oauth.ts";
-import { isComposioServiceCredential } from "../composio.ts";
-import { configuredOAuthProviders } from "../connectors.ts";
-
-function origin(url: string | undefined): string | undefined {
- return url ? url.replace(/\/+$/, "") : undefined;
-}
-
-export async function getConnectorSources(ctx: ApiCtx): Promise<void> {
- const scope = orgScope(ctx.deps);
- const actor = await authorizeAdmin(ctx, scope);
- if (!actor) return;
- audit(ctx.deps, {
- principalId: actor.id,
- action: "connector-sources.read",
- resource: "connector-sources",
- scopeLabel: scope,
- });
- const [credentials, oauth] = await Promise.all([
- ctx.deps.serviceCreds?.listServiceCredentials(scope) ?? [],
- configuredOAuthProviders(ctx.deps),
- ]);
- const web = origin(ctx.deps.portalUrl);
- const admin = web ?? origin(ctx.deps.publicUrl);
- const api = origin(ctx.deps.publicUrl);
- return sendJson(ctx.res, 200, {
- composio: { configured: credentials.some(isComposioServiceCredential) },
- oauth: { configured: oauth },
- setup: {
- ...(admin
- ? { composioCredentialUrl: `${admin}/admin/credentials`, oauthAppsUrl: `${admin}/admin/connectors` }
- : {}),
- ...(web ? { composioVerifierUrl: `${web}/api/composio/callback` } : {}),
- ...(api
- ? {
- oauthCallbackUrls: Object.fromEntries(
- Object.keys(PROVIDERS).map((provider) => [
- provider,
- `${api}/v1/connectors/oauth/${encodeURIComponent(provider)}/callback`,
- ]),
- ),
- }
- : {}),
- },
- });
-}
diff --git a/src/api/routes/composio.ts b/src/api/routes/composio.ts
index e8f123ed6..897ff85cf 100644
--- a/src/api/routes/composio.ts
+++ b/src/api/routes/composio.ts
@@ -1,4 +1,4 @@
-import { isBackendCredential, type PublicServiceCredential } from "../../credentials/keychain.ts";
+import { isBackendCredential } from "../../credentials/keychain.ts";
import { livePersonCapability } from "../artifact-share.ts";
import { mintSignedPayload, verifySignedPayload } from "../../auth/signed-token.ts";
import { canonicalPerson, personIds, samePerson } from "../../directory/person.ts";
@@ -15,10 +15,6 @@ import { errMessage, httpFailure, reportFailure } from "../../util/errors.ts";
import { activePrincipal, audit } from "./shared.ts";
import type { ApiCtx, Route } from "./route.ts";
-export function isComposioServiceCredential(c: PublicServiceCredential): boolean {
- return c.enabled && c.hasSecret && c.delivery === "env" && c.envKey === "COMPOSIO_API_KEY";
-}
-
export function composioUserId(org: string, principal: string): string {
return `qm_${createHash("sha256")
.update(JSON.stringify([org, principal]))
@@ -117,7 +113,7 @@ async function credential(ctx: ApiCtx): Promise<{ key: string; principal: string
)) ?? [];
const allowed = new Set(grants.map((g) => parseRef(g.ref).id));
const records = ((await ctx.deps.serviceCreds?.listServiceCredentials(org)) ?? []).filter(
- (c) => isComposioServiceCredential(c) && allowed.has(c.slug),
+ (c) => c.enabled && c.hasSecret && c.delivery === "env" && c.envKey === "COMPOSIO_API_KEY" && allowed.has(c.slug),
);
if (records.length !== 1) {
sendJson(ctx.res, records.length ? 409 : 403, {
diff --git a/src/api/routes/connectors.ts b/src/api/routes/connectors.ts
index 609fab4b5..8d48eaf47 100644
--- a/src/api/routes/connectors.ts
+++ b/src/api/routes/connectors.ts
@@ -53,20 +53,6 @@ export function resolverFor(deps: ServerDeps): OAuthClientResolver {
);
}
-export async function configuredOAuthProviders(deps: ServerDeps): Promise<string[]> {
- const resolve = resolverFor(deps);
- const names = Object.keys(PROVIDERS);
- const configured = await Promise.all(
- names.map((name) =>
- resolve(name, {}).then(
- (client) => !!client.id && !!client.secret,
- () => false,
- ),
- ),
- );
- return names.filter((_, i) => configured[i]);
-}
-
function parseAccountType(v: string | null | undefined): AccountType {
return v === "personal" || v === "company" ? v : "default";
}
diff --git a/src/core/environment-facts.ts b/src/core/environment-facts.ts
index ac40085ad..4bbc0333f 100644
--- a/src/core/environment-facts.ts
+++ b/src/core/environment-facts.ts
@@ -56,6 +56,7 @@ export function renderConnectedAppsBlock(
"## Connected apps",
"This list covers direct OAuth only; it does not describe app access through separately authorized credentials. Use the matching access skill for those, respecting explicit app restrictions and account permissions.",
];
+ if (connectionsUrl) lines.push(`Connection page: ${connectionsUrl}`);
if (!availableProviders.length) {
lines.push("No direct OAuth app connections are configured. Do not offer direct OAuth consent links.");
if (!connected.length && !reconnect.length) return lines.join("\n");
@@ -70,7 +71,6 @@ export function renderConnectedAppsBlock(
lines.push("Only offer direct OAuth consent links for the admin-configured list below.");
}
}
- if (connectionsUrl) lines.push(`Connection page: ${connectionsUrl}`);
if (connected.length) {
lines.push(`Connected: ${connected.join(", ")}. Use them directly; their auth is wired.`);
}
diff --git a/src/tools/admin.ts b/src/tools/admin.ts
index a62de4a9f..3351704a8 100644
--- a/src/tools/admin.ts
+++ b/src/tools/admin.ts
@@ -194,11 +194,6 @@ export const adminOperations = {
),
}),
slack_emoji: operation("List Slack emoji.", "GET", "/slack-emoji"),
- connector_sources: operation(
- "Check whether Composio or OAuth apps are configured, with admin setup links. Never returns secrets.",
- "GET",
- "/connector-sources",
- ),
model_providers: operation("Read model-provider metadata.", "GET", "/model-providers"),
custom_providers: operation("Read custom model-provider metadata.", "GET", "/custom-providers"),
mcp_servers: operation("Read MCP-server metadata.", "GET", "/mcp-servers"),
diff --git a/test/admin-connector-sources.test.ts b/test/admin-connector-sources.test.ts
deleted file mode 100644
index 202a1dd8c..000000000
--- a/test/admin-connector-sources.test.ts
+++ /dev/null
@@ -1,135 +0,0 @@
-import "./support/auto-fake-sprites.ts";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtempSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import type { AddressInfo } from "node:net";
-import { createInsecureTestServer } from "../src/api/server.ts";
-import { buildApp, type BuiltApp } from "../src/wiring.ts";
-import { testConfig } from "./support/test-config.ts";
-
-const ADMIN = { "content-type": "application/json", "x-admin-actor": "admin-alice@default-org" };
-const ORG = "org:default-org";
-
-interface Sources {
- composio: { configured: boolean };
- oauth: { configured: string[] };
- setup: {
- composioCredentialUrl?: string;
- composioVerifierUrl?: string;
- oauthAppsUrl?: string;
- oauthCallbackUrls?: Record<string, string>;
- };
-}
-
-function start(urls: { publicUrl?: string; portalUrl?: string } = {}): {
- base: string;
- built: BuiltApp;
- close: () => Promise<void>;
-} {
- const built = buildApp(testConfig({ dataDir: mkdtempSync(join(tmpdir(), "connector-sources-")) }));
- const server = createInsecureTestServer(built.app, {
- resolveClient: built.resolveClient,
- serviceCreds: built.serviceCreds,
- config: built.config,
- admin: built.admin,
- auditLog: built.auditLog,
- ...urls,
- });
- server.listen(0);
- const base = `http://localhost:${(server.address() as AddressInfo).port}`;
- return { base, built, close: () => new Promise<void>((r) => server.close(() => r())) };
-}
-
-const read = (base: string, headers: Record<string, string> = ADMIN) =>
- fetch(`${base}/v1/admin/connector-sources`, { headers });
-
-test("connector sources report nothing configured with admin setup links", async () => {
- const srv = start({ publicUrl: "https://api.example/", portalUrl: "https://qm.example" });
- try {
- const res = await read(srv.base);
- assert.equal(res.status, 200);
- const body = (await res.json()) as Sources;
- assert.deepEqual(body.composio, { configured: false });
- assert.deepEqual(body.oauth, { configured: [] });
- assert.equal(body.setup.composioCredentialUrl, "https://qm.example/admin/credentials");
- assert.equal(body.setup.composioVerifierUrl, "https://qm.example/api/composio/callback");
- assert.equal(body.setup.oauthAppsUrl, "https://qm.example/admin/connectors");
- assert.equal(body.setup.oauthCallbackUrls?.google, "https://api.example/v1/connectors/oauth/google/callback");
- assert.ok((await srv.built.auditLog.events()).some((event) => event.action === "connector-sources.read"));
- } finally {
- await srv.close();
- }
-});
-
-test("connector sources detect Composio and OAuth apps without returning secrets", async () => {
- const srv = start({ publicUrl: "https://api.example" });
- try {
- await srv.built.serviceCreds.setServiceCredential(ORG, {
- slug: "composio",
- name: "Composio",
- delivery: "env",
- envKey: "COMPOSIO_API_KEY",
- secret: "COMPOSIO_SECRET_SENTINEL",
- host: "",
- });
- const put = await fetch(`${srv.base}/v1/admin/scopes/${ORG}/connectors`, {
- method: "PUT",
- headers: ADMIN,
- body: JSON.stringify({ provider: "google", clientId: "cid", clientSecret: "OAUTH_SECRET_SENTINEL" }),
- });
- assert.equal(put.status, 200);
- const res = await read(srv.base);
- assert.equal(res.status, 200);
- const text = await res.text();
- assert.doesNotMatch(text, /SECRET_SENTINEL/);
- const body = JSON.parse(text) as Sources;
- assert.deepEqual(body.composio, { configured: true });
- assert.deepEqual(body.oauth, { configured: ["google"] });
- assert.equal(body.setup.oauthAppsUrl, "https://api.example/admin/connectors");
- assert.equal(body.setup.composioVerifierUrl, undefined);
- } finally {
- await srv.close();
- }
-});
-
-test("disabled Composio credentials and disabled OAuth apps do not count as sources", async () => {
- const srv = start();
- try {
- await srv.built.serviceCreds.setServiceCredential(ORG, {
- slug: "composio",
- name: "Composio",
- delivery: "env",
- envKey: "COMPOSIO_API_KEY",
- secret: "k",
- host: "",
- enabled: false,
- });
- for (const enabled of [true, false]) {
- await fetch(`${srv.base}/v1/admin/scopes/${ORG}/connectors`, {
- method: "PUT",
- headers: ADMIN,
- body: JSON.stringify({ provider: "google", clientId: "cid", clientSecret: "s", enabled }),
- });
- }
- const [google] = await srv.built.config.listConnectorClients(ORG);
- assert.equal(google?.enabled, false);
- const body = (await (await read(srv.base)).json()) as Sources;
- assert.deepEqual(body.composio, { configured: false });
- assert.deepEqual(body.oauth, { configured: [] });
- assert.deepEqual(body.setup, {});
- } finally {
- await srv.close();
- }
-});
-
-test("connector sources are admin-only", async () => {
- const srv = start();
- try {
- assert.equal((await read(srv.base, { "x-admin-actor": "nobody@default-org" })).status, 403);
- } finally {
- await srv.close();
- }
-});
diff --git a/test/environment-facts.test.ts b/test/environment-facts.test.ts
index 33bd4df80..ae74f8f32 100644
--- a/test/environment-facts.test.ts
+++ b/test/environment-facts.test.ts
@@ -57,6 +57,7 @@ test("connected-apps block: lists only admin-configured providers and the exact
const unavailable = renderConnectedAppsBlock(null, [], url);
assert.match(unavailable, /No direct OAuth app connections are configured/);
assert.match(unavailable, /does not describe app access through separately authorized credentials/);
+ assert.match(unavailable, /Connection page: https:\/\/qm\.example\/keychain/);
const none: ConnectorStatusRecord = { principalId: "U1", checkedAt: 1, providers: { google: { connected: false } } };
const available = renderConnectedAppsBlock(none, ["google"], url);
diff --git a/test/onboarding-slack-contract.test.ts b/test/onboarding-slack-contract.test.ts
index c1eb2f666..8f7ea0931 100644
--- a/test/onboarding-slack-contract.test.ts
+++ b/test/onboarding-slack-contract.test.ts
@@ -34,9 +34,13 @@ test("admins set up a connector source before voice or work questions", () => {
assert.match(PROACTIVE_OPENER_PROMPT, /first step is connecting their tools/);
assert.ok(onboarding.indexOf("Connector source first for admins") < onboarding.indexOf("Slack bot first for admins"));
assert.match(onboarding, /Never ask for the key or client\s+secrets in chat/);
- assert.match(onboarding, /GET \/v1\/admin\/connector-sources/);
+ assert.match(onboarding, /GET \/v1\/composio\/toolkits/);
+ assert.match(onboarding, /Connected apps block/);
assert.match(onboarding, /unknown, not absent/);
- assert.doesNotMatch(onboarding, /\]\(\/admin\//);
- assert.match(admin, /setup\.composioCredentialUrl[\s\S]*\/v1\/keychain\/drops[\s\S]*setup\.oauthAppsUrl/);
- assert.match(admin, /Never ask regular users to configure a source/);
+ assert.doesNotMatch(onboarding, /connector-sources/);
+ assert.match(admin, /view=credentials[\s\S]*COMPOSIO_API_KEY/);
+ assert.match(admin, /<web origin>\/admin\/credentials[\s\S]*<web origin>\/admin\/connectors/);
+ assert.match(admin, /<web origin>\/v1\/connectors\/oauth\/<provider>\/callback/);
+ assert.match(admin, /\/v1\/keychain\/drops/);
+ assert.match(admin, /Never\s+ask\s+regular\s+users\s+to\s+configure\s+a\s+source/);
});