Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

Restore secret-drop instructions agents can find (#2403)

Joshua France3feb9931b441
diff --git a/skills-seed/admin/SKILL.md b/skills-seed/admin/SKILL.md
index 0b494c4ac..0bcf79ed8 100644
--- a/skills-seed/admin/SKILL.md
+++ b/skills-seed/admin/SKILL.md
@@ -92,8 +92,8 @@ 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`.
+ key now, mint a one-time link with the `secret-drop` skill (service `composio`, envKey
+ `COMPOSIO_API_KEY`) and share its `url`.
A dropped key enables Composio only for them; teammates need the org credential.
- 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
diff --git a/skills-seed/browse/SKILL.md b/skills-seed/browse/SKILL.md
index 643a3060d..17252c0b9 100644
--- a/skills-seed/browse/SKILL.md
+++ b/skills-seed/browse/SKILL.md
@@ -110,9 +110,8 @@ of them (asks and drops are refused only on trigger-fired turns).
person whose approval you're waiting on. The approved grant's handle then works in
`credentials`.
4. **Not registered anywhere** → the person can supply their own keys on the spot: mint a
- drop link per key (`POST /v1/keychain/drops` with
- `{"service":"<your provider doc's keychain service>","envKey":"<the provider key name>","purpose":"browse"}`)
- and hand the link over — the secret lands in
+ drop link per key with the `secret-drop` skill (service = your provider doc's keychain
+ service, envKey = the provider key name) and hand the link over — the secret lands in
their keychain, never in chat.
**If the profile has no handle in your manifest, do NOT jump to bootstrapping** — a
diff --git a/skills-seed/browse/providers/anchor.md b/skills-seed/browse/providers/anchor.md
index 617e2ec81..be1011bdf 100644
--- a/skills-seed/browse/providers/anchor.md
+++ b/skills-seed/browse/providers/anchor.md
@@ -93,13 +93,8 @@ when the site expires the session. If the person wants re-auth without being pin
time, Anchor's Identities store their login and re-run the auth flow automatically before
each session. Check `GET /v1/keychain/credentials` for an existing login for the domain
first (use it via a grant; NEVER bind a login registered for a different site); otherwise
-mint a one-time secret-drop so the password never transits chat:
-
-```bash
-curl -fsS -X POST "$AGENT_API_URL/v1/keychain/drops" -H "x-agent-capability: $AGENT_API_TOKEN" \
- -H 'content-type: application/json' \
- -d '{"service":"<domain>","fields":[{"key":"EMAIL","secret":false},{"key":"PASSWORD"}],"purpose":"sign in to <domain> in the managed browser"}'
-```
+mint a one-time link with the `secret-drop` skill so the password never transits chat
+(service `<domain>`, fields `EMAIL` with `secret:false` and `PASSWORD`).
Hand over the returned `url` with the consent stated plainly: _filling it stores this login
with Anchor (our managed-browser provider) so it can sign in and re-sign-in for you_ — that
diff --git a/skills-seed/secret-drop/SKILL.md b/skills-seed/secret-drop/SKILL.md
new file mode 100644
index 000000000..8910acb84
--- /dev/null
+++ b/skills-seed/secret-drop/SKILL.md
@@ -0,0 +1,42 @@
+---
+name: secret-drop
+description: Request a credential nobody has saved yet (an API key, a site login) with a one-time, expiring link that saves it to the person's keychain. Use instead of asking for secrets in chat or sending people to the keychain page.
+---
+
+# Secret drop: request a new credential by link
+
+Use this when a task needs a credential nobody has saved yet. Never ask for a secret in chat,
+and never tell the person to add it on the keychain page by hand.
+
+- A teammate's credential that is already saved: use the `request-access` skill instead.
+- A CLI with a device-code or browser login (gh, aws sso, gcloud): use `interactive-login`.
+
+## Mint the link
+
+Only on a turn a person sent. Scheduled and trigger-fired turns are refused.
+
+```sh
+curl -fsS -X POST "$AGENT_API_URL/v1/keychain/drops" \
+ -H "x-agent-capability: $AGENT_API_TOKEN" -H 'content-type: application/json' \
+ -d '{"service":"acme","purpose":"sign in to the Acme dashboard","fields":[{"key":"ACME_EMAIL","label":"Email","secret":false},{"key":"ACME_PASSWORD","label":"Password"}]}'
+```
+
+- `service` names the credential; `purpose` is one plain sentence the person sees on the form.
+- `fields` declares the form inputs (1–8). Keys are env var names; `secret:false` shows the
+ input in clear text (usernames, emails). For a single token, omit `fields` and pass
+ `"envKey":"ACME_API_KEY"` instead.
+- The link belongs to the person whose turn this is. If a different teammate in this
+ conversation will fill it, add `"onBehalfOf":"<their id>"`.
+- Send the header exactly as shown. `Authorization: Bearer` is not accepted.
+
+The response is `{dropId, url}`. Give the person `url` exactly as returned. It carries a
+link-bound token, so a rebuilt URL will not work.
+
+## Then
+
+- Tell them in one line what the link is for. It works once and expires.
+- Stop. Don't poll.
+- When they submit, the value is saved encrypted to their keychain (and, in a channel or group,
+ granted to this conversation) and this conversation wakes with the new credential's handle.
+ Select that handle in `execute.credentials` to get the declared env vars.
+- If the link expires or they used the wrong account, mint a fresh one.
diff --git a/src/api/agent-api-catalog.ts b/src/api/agent-api-catalog.ts
index 00f51ed16..1ee6e6079 100644
--- a/src/api/agent-api-catalog.ts
+++ b/src/api/agent-api-catalog.ts
@@ -659,7 +659,7 @@ const FAMILIES: AgentApiFamily[] = [
method: "POST",
path: "/v1/keychain/drops",
summary:
- 'mint a single-use, expiring link for someone to drop a credential into the keychain via a browser (no secret in chat; hand the returned url over VERBATIM — it carries a link-bound token, so a reconstructed url will not work; declare the form inputs with fields[], e.g. [{key:"X_EMAIL",label:"Email",secret:false},{key:"X_PASSWORD",label:"Password"}] for a login, or omit for a single token; the link binds to the person who will paste the secret — pass onBehalfOf with their id when that is a teammate who spoke in this conversation rather than the person whose turn this is; refused on trigger-fired turns)',
+ "mint a single-use, expiring link for someone to enter a new credential into their keychain — follow the `secret-drop` skill",
},
],
},
diff --git a/src/api/server.ts b/src/api/server.ts
index e8e8799aa..896622d9b 100644
--- a/src/api/server.ts
+++ b/src/api/server.ts
@@ -590,7 +590,10 @@ function buildServer(app: App, deps: ServerOptions, allowUnsignedSourceAuth: boo
Math.abs(Date.now() - timestamp * 1000) > SOURCE_AUTH_REPLAY_WINDOW_MS ||
typeof req.headers["x-signature"] !== "string"
) {
- sendJson(res, 401, { error: "unauthorized", message: "missing, invalid, or stale source-auth headers" });
+ sendJson(res, 401, {
+ error: "unauthorized",
+ message: `missing, invalid, or stale source-auth headers; agent calls must send the capability token as ${CAPABILITY_HEADER}: $AGENT_API_TOKEN`,
+ });
return;
}
}
diff --git a/src/credentials/keychain.ts b/src/credentials/keychain.ts
index 437c7c8cf..e5adb1d9c 100644
--- a/src/credentials/keychain.ts
+++ b/src/credentials/keychain.ts
@@ -1779,7 +1779,7 @@ export function renderKeychainManifest(input: KeychainManifestInput, now: number
lines.push(
"",
"Grants: Use of private credentials outside of a 1:1 DM with that person requires an explicit grant. The exception is the live speaker's isolated owner execution in an Open shared conversation, not continuing room or background access. Otherwise use the `request-access` skill; consider whether one-time, standing or time-bound access fits the request.",
- "Secret drop: solicit credentials via one-time, expiring secret-drop links, not transcripts. Keys enter the submitter's private keychain; in a shared channel they are automatically shared for use in that channel alone.",
+ "Secret drop: for a credential nobody has saved, mint a one-time link with the `secret-drop` skill; never collect secrets in chat or send people to the keychain page. Keys enter the submitter's private keychain; in a shared channel they are shared for use in that channel alone.",
"Device code or CLI logins: read the `interactive-login` skill from the first step. It logs in under a temporary home and saves the result. Never log in against this computer's $HOME; only keychain entries are durable and grantable.",
);
return lines.join("\n");
diff --git a/test/onboarding-slack-contract.test.ts b/test/onboarding-slack-contract.test.ts
index 8f7ea0931..9d66a6a33 100644
--- a/test/onboarding-slack-contract.test.ts
+++ b/test/onboarding-slack-contract.test.ts
@@ -41,6 +41,5 @@ test("admins set up a connector source before voice or work questions", () => {
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/);
});
diff --git a/test/secret-drop.test.ts b/test/secret-drop.test.ts
index ce1def51d..152caa259 100644
--- a/test/secret-drop.test.ts
+++ b/test/secret-drop.test.ts
@@ -2,9 +2,11 @@ import "./support/auto-fake-sprites.ts";
import { describe, it, before, after } from "node:test";
import assert from "node:assert/strict";
-import { mkdtempSync } from "node:fs";
+import { mkdtempSync, readFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
import type { AddressInfo } from "node:net";
import type { Server } from "node:http";
import { buildApp, type BuiltApp } from "../src/wiring.ts";
@@ -28,6 +30,7 @@ import { testConfig } from "./support/test-config.ts";
import { materializeGrant } from "./support/materialize-grant.ts";
const SECRET = "secret-drop-test-secret".repeat(3);
+const execFileAsync = promisify(execFile);
describe("SecretDropStore", () => {
it("mint → peek (non-consuming) → redeem (single-use)", async () => {
@@ -471,6 +474,29 @@ describe("/v1/keychain/drops — mint, form, redeem", async () => {
]);
});
+ it("an agent call without the capability header is told which header to send", async () => {
+ const cap = await capFor("U_A");
+ const res = await fetch(`${base}/v1/keychain/drops`, {
+ method: "POST",
+ headers: { "content-type": "application/json", authorization: `Bearer ${cap}` },
+ body: JSON.stringify({ service: "stripe", purpose: "p" }),
+ });
+ assert.equal(res.status, 401);
+ assert.match(((await res.json()) as { message: string }).message, /x-agent-capability/);
+ const ok = await post("/v1/keychain/drops", { service: "stripe", purpose: "p" }, cap);
+ assert.equal(ok.status, 200, "the same token in x-agent-capability mints");
+ });
+
+ it("the secret-drop skill's mint command works as written", async () => {
+ const skill = readFileSync(new URL("../skills-seed/secret-drop/SKILL.md", import.meta.url), "utf8");
+ const start = skill.indexOf("```sh\n") + "```sh\n".length;
+ const command = skill.slice(start, skill.indexOf("```", start));
+ const { stdout } = await execFileAsync("sh", ["-c", command], {
+ env: { PATH: process.env.PATH, AGENT_API_URL: base, AGENT_API_TOKEN: await capFor("U_A") },
+ });
+ assert.match((JSON.parse(stdout) as { formPath: string }).formPath, /^\/drop\//);
+ });
+
it("rejects a malformed fields[] at mint", async () => {
const bad = await post(
"/v1/keychain/drops",