foldrun 10.3.1 → 10.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/bin/foldrun.mjs CHANGED
@@ -170,6 +170,8 @@ const HELP = `foldrun — agents are just folders
170
170
  foldrun inbox what waits on you: approvals, questions, issues, proposed fixes, your failed runs (--team, --all, --kind, --unread, --dismissed)
171
171
  foldrun inbox read|unread|dismiss|restore <id>… mark items in your own view (dismiss sets aside; it still waits where it lives)
172
172
  foldrun mcp this account as MCP tools for an AI app, over stdio, with this machine's sign-in: \`claude mcp add foldrun -- foldrun mcp\` (--read-only: only the tools that read)
173
+ foldrun mcp connections the AI apps connected over OAuth (claude.ai and the like): which app, whose, what access, last used — everyone's for an admin, else yours (--all adds the disconnected, --json)
174
+ foldrun mcp disconnect <id> end one: every token it holds stops working (asks; --yes)
173
175
  foldrun issues what went wrong, grouped, open until resolved (--to <workspace>, --all, --status, --json)
174
176
  foldrun issues show|ack|snooze|resolve|reopen <id> one issue — snooze --for 1d or --times 5, --note "…"
175
177
  foldrun issues doctor <id> the run doctor on the issue's newest run, in its workspace: why, and the fix as diffs, saved on yes (--yes, --dry-run, --json)
@@ -351,7 +353,7 @@ Options
351
353
  --value "<text>" secrets set: skip the prompt (careful with shell history)
352
354
  --site <domain> secrets set, secrets sites: a site the secret is bound to — the egress proxy fills it for those alone (repeatable, or a,b)
353
355
  --clear secrets sites: unbind it; flow compute: no cap of its own
354
- --all secrets workspaces: every workspace may use the account secret again
356
+ --all secrets workspaces: every workspace may use the account secret again; mcp connections: the disconnected ones too
355
357
  --none secrets workspaces, secrets set: no workspace may use the account secret
356
358
  --workspaces <a,b> secrets set: store an account secret limited to those workspaces, in the same write (with --account)
357
359
  --add <site> agent network: add a site to its network: list (repeatable)
package/docs/api.md CHANGED
@@ -17,7 +17,7 @@ proof instead of a key: a token or signature (`/s/<token>`, `/api/hooks`,
17
17
  `/api/inbox`, `/api/events`, `/api/approve`, `/api/unsubscribe`, `/api/billing/stripe`,
18
18
  `/api/billing/confirm`), the sign-in and recovery steps (`/api/auth/signup`,
19
19
  `login`, `forgot`, `reset`, `verify`, `mfa/verify`, `session`, `/api/cli/login`,
20
- `/api/cli/login/<id>`, `/api/cli/authorize` GET, `/api/oauth/callback`), `/api/healthz`, `/api/status`, `/api/status/history`, `/api/version` and `/api/openapi.json`.
20
+ `/api/cli/login/<id>`, `/api/cli/authorize` GET, `/api/oauth/callback`), `/api/healthz`, `/api/status`, `/api/status/history`, `/api/version` and `/api/openapi.json` — and an AI app's OAuth sign-in to `/api/mcp`: `/api/mcp/oauth/register` (open, as the protocol needs) and `/api/mcp/oauth/token` (its code and PKCE verifier, or its refresh token, are the proof).
21
21
 
22
22
  ```
23
23
  Authorization: Bearer <api-key> # machines. Settings → API keys
@@ -490,7 +490,7 @@ signed-in person, never by a key — mints an ordinary API key at their role.
490
490
 
491
491
  | Route | Methods | |
492
492
  |---|---|---|
493
- | `/api/oauth/clients` | GET, POST, DELETE | saved OAuth apps (`name`, `client`, `config`). `config`: `authorize_url`, `token_url`, `client_id`, `client_secret` (empty for a public app), `scopes`, optional `authorize_extra` (`{ name: value }` added to the authorize URL — the flow's own parameters are refused), `pkce` (false to turn it off), `issuer` |
493
+ | `/api/oauth/clients` | GET, POST, DELETE | saved OAuth apps (`name`, `client`, `config`). `config`: `authorize_url`, `token_url`, `client_id`, `client_secret` (empty for a public app), `scopes`, optional `authorize_extra` (`{ name: value }` added to the authorize URL — the flow's own parameters are refused), `pkce` (false to turn it off), `issuer`, `token_auth` (`client_secret_post`, the default: the secret in the form body; `client_secret_basic`: HTTP Basic, which Notion, Spotify, Reddit and Zoom require; `none`: a public app) |
494
494
  | `/api/oauth/start` | POST | begin a connection (`client`, `secret`, `workspace`, optional `scopes`). `secret` is checked as `PUT /api/secrets` checks a name — the account's `RESEND_API_KEY`/`EMAIL_FROM` are the owner's alone (403), and so is accepting a hand-off for them. From a signed-in browser: `{ url }` is the provider's consent, bound to that browser by a cookie the callback checks, with PKCE. With an API key: `{ url, handoff: true }` is a dashboard page where a signed-in person accepts first (`foldrun connect --client` opens it). `scopes` (space-separated, as the provider spells them) is what this connection asks for instead of the client's default, and the connection keeps it for its reconnects — one saved app serves any number of connections at different scopes |
495
495
  | `/api/oauth/callback` | GET | where the provider returns — refuses a consent that comes back to another browser, and an `iss` that is not the app's issuer |
496
496
  | `/api/identity?workspace=` | GET | keyless cloud identity: `{ enabled, issuer, subject, tokenSeconds }` — the issuer a cloud must trust and the subject pattern each agent's tokens carry (`account:<a>:workspace:<w>:agent:<agent>`). Open (no key), outside `/api`: `/.well-known/openid-configuration` and `/.well-known/jwks.json`, 404 when the install does not issue tokens |
@@ -528,12 +528,12 @@ published, is `404` like one that does not exist.
528
528
 
529
529
  ## MCP — AI apps connecting with a key
530
530
 
531
- The platform as an [MCP server](mcp) for Claude Code, Claude Desktop,
532
- Cursor, Codex and any other MCP client. An **API key** opens it
533
- (`Authorization: Bearer mda_…`) — never a session cookie, never an A2A key —
534
- and every tool is a call to one of the routes above, made with that key, so
535
- it answers what the route would: the key's role, its workspaces and every
536
- refusal hold. MCP's Streamable HTTP transport, stateless: one JSON-RPC 2.0
531
+ The platform as an [MCP server](mcp) for claude.ai, Claude Code, Claude
532
+ Desktop, Cursor, Codex and any other MCP client. An **API key**
533
+ (`Authorization: Bearer mda_…`) or an AI app's **OAuth access token** (below)
534
+ opens it — never a session cookie, never an A2A key — and every tool is a call
535
+ to one of the routes above, made with that credential, so it answers what the
536
+ route would: its role, its workspaces and every refusal hold. MCP's Streamable HTTP transport, stateless: one JSON-RPC 2.0
537
537
  message per request, answered as JSON — no SSE stream, no session id, no
538
538
  batches. Errors before a message is read (no key, a refused key, a foreign
539
539
  `Origin`, an `MCP-Protocol-Version` it does not speak) are JSON-RPC error
@@ -543,3 +543,22 @@ with `HTTP <status>: <the route's error>`.
543
543
  | Route | Methods | |
544
544
  |---|---|---|
545
545
  | `/api/mcp` | POST | one JSON-RPC message: `initialize` (revisions `2025-11-25`, `2025-06-18`, `2025-03-26`; an unknown one is answered with the newest), `ping`, `tools/list`, `tools/call`; a notification is `202` with no body. `?readonly=1` offers only the tools that read and refuses the rest (`-32602`). The tools: `whoami`, `list_workspaces`, `inbox`, `list_approvals`, `list_flows`, `list_runs`, `get_run`, `read_file`, `run_flow`, `decide_approval`, `answer_question`, `message_run`, `stop_run` — see [MCP](mcp#the-tools). `foldrun mcp` serves the same over stdio |
546
+ | `/api/mcp/oauth/register` | POST | an AI app registers itself (RFC 7591), before anyone signs it in. Open, as the protocol needs — no key. `{ redirect_uris, client_name?, token_endpoint_auth_method?, grant_types?, response_types?, client_uri? }`: one to ten redirect URIs, each `https` or `http` to localhost, no fragment; `token_endpoint_auth_method` `none` (PKCE alone), `client_secret_post` or `client_secret_basic` (the default). Answers `201 { client_id, client_id_issued_at, client_name, redirect_uris, grant_types, response_types, token_endpoint_auth_method, client_secret?, client_secret_expires_at? }` — the secret only for the two secret methods, shown once. Errors are OAuth's `{ error, error_description }` (`invalid_redirect_uri`, `invalid_client_metadata`); `503` past 5,000 apps on the install |
547
+ | `/api/mcp/oauth/authorize` | GET, POST | the person's half of the sign-in, for the page at `/mcp/authorize` — a signed-in person only, never a key or a support view. GET `?request=<the app's query>` checks it and answers `{ client: { name, id, kind, uri }, redirectHost, loopback, scopes, account, person: { email, role }, workspaces, allWorkspaces }`; POST `{ request, decision: approve\|deny, access?: read\|write, workspaces?: [names] \| null }` answers `{ ok, redirect }` — the app's redirect URI with a one-time `code` (ten minutes), `state` and `iss`, or with `error=access_denied`. A request that names an unknown app or a redirect URI it did not register is `400` and never redirected; the rest of its faults (no PKCE `S256` challenge, a `resource` that is not this `/api/mcp`, an unknown scope) come back as `{ redirect }` with OAuth's error. `access: write` needs the app to have asked for `mcp:write`; `workspaces` must be ones the person may open (`403` otherwise) |
548
+ | `/api/mcp/oauth/token` | POST | OAuth 2.1's token endpoint, form-encoded (JSON is read too), no key: `grant_type=authorization_code` with `code`, `redirect_uri`, `code_verifier` (PKCE S256) and `client_id` — or the app's secret, Basic or in the form —, or `grant_type=refresh_token` with `refresh_token`. `resource`, when sent, must be this `/api/mcp`. Answers `{ access_token, token_type: "Bearer", expires_in: 3600, refresh_token, scope }` with `Cache-Control: no-store`. A code is good once, right or wrong. A refresh token is rotated on use; one used twice revokes the whole connection. Errors: `400 invalid_grant` / `invalid_target` / `unsupported_grant_type`, `401 invalid_client` |
549
+ | `/api/mcp/connections` | GET | the AI apps connected over OAuth: `{ connections: [{ id, client, clientId, redirectHost, person, role, workspaces, access: read\|write, createdAt, lastUsedAt, revokedAt }], everyone }` — every one for `keys:manage` (`everyone: true`), else your own. `?all=1` adds the revoked |
550
+ | `/api/mcp/connections/<id>` | DELETE | disconnect one: the grant is revoked and every token it issued stops at once. Your own, or anyone's with `keys:manage` (`403` otherwise); `404` when there is none or it is already revoked. Audited as `mcp.revoked` |
551
+
552
+ **OAuth for AI apps.** claude.ai — and any MCP client that signs in rather
553
+ than taking a pasted key — finds this from the `401` of `/api/mcp`:
554
+ `WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/api/mcp"`
555
+ (RFC 9728), which names this install as the authorization server, whose
556
+ `/.well-known/oauth-authorization-server` (RFC 8414) lists the endpoints above,
557
+ `code_challenge_methods_supported: ["S256"]` and
558
+ `client_id_metadata_document_supported: true` (an app may name itself by an
559
+ `https` URL to its metadata document, fetched through the SSRF guard). Scopes
560
+ are `mcp:read` and `mcp:write`. The access token (`fmcp_at_…`, an hour) opens
561
+ `POST /api/mcp` and nothing else — sent to any other route it is `403` — and
562
+ acts as the person who approved it, at the lower of the role they chose then
563
+ and the one they hold now, in the workspaces both allow; a read-only
564
+ connection is refused every write.
package/docs/cli.md CHANGED
@@ -96,6 +96,8 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
96
96
  | `foldrun inbox` | what waits on you across your workspaces ([your inbox](runs#your-inbox)): gates, questions agents ask, open issues, proposed fixes, your runs that went wrong this week — assigned to you and started by you by default; `--team`, `--started`, `--mine`, `--all`, `--dismissed`, `--kind approval\|question\|issue\|proposal\|run`, `--unread`, `--json`. Each item shows its id; exits 1 when something assigned to you is unread |
97
97
  | `foldrun inbox read\|unread\|dismiss\|restore <id>…` | mark items in your own view: `dismiss` sets one aside (it still waits where it lives), `restore` puts it back |
98
98
  | `foldrun mcp` | this account as an [MCP server](mcp) on stdin/stdout, for an AI app to start: `claude mcp add foldrun -- foldrun mcp`, `codex mcp add foldrun -- foldrun mcp`. Each line is one JSON-RPC message, forwarded to the platform's `POST /api/mcp` with this machine's sign-in (`--profile`, `--url`, `--token` as for any platform command); stdout carries nothing but protocol. `--read-only` offers only the tools that read. Typed into a terminal it prints how to connect and exits 2 |
99
+ | `foldrun mcp connections` | the AI apps connected to the account over OAuth (claude.ai and the like): the app, where its answers go, whose approval, read only or read and act, which workspaces, connected and last used. Everyone's for an admin (`keys:manage`), else your own; `--all` adds the disconnected, `--json` the raw list |
100
+ | `foldrun mcp disconnect <id>` | end one connection: every token it holds stops at once. Your own, or anyone's as an admin. Asks first; `--yes` when there is no terminal |
99
101
  | `foldrun issues` | the account's [issues](runs#issues): what went wrong, grouped, open until someone resolves it — kind, desk and flow (or the platform cause and every desk it hit), how many times since when, the newest reason and what to do. `--to <workspace>` narrows it, `--all` adds resolved ones (`--status open\|acknowledged\|snoozed\|resolved\|all`), `--json` |
100
102
  | `foldrun issues show\|ack\|snooze\|resolve\|reopen <id>` | one issue: `show` adds its runs and history; `ack` says you have seen it, `snooze --for 30m\|4h\|1d\|1w` (or `--until <ISO>`, or `--times <n>`: until it happens n more times) hides it for a while, `resolve` closes it until it happens again, `reopen` undoes that. `--note "…"` is kept in its history |
101
103
  | `foldrun issues doctor <id>` | the run doctor on an issue's newest run, in that run's workspace — the issue card's **Doctor** button: why (platform, check, work or outside), and the fix as diffs, saved on yes (`--yes`, `--dry-run`, `--json`). A missed schedule has no run and is refused |
@@ -107,9 +109,9 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
107
109
  | `foldrun message <run-id> "…"` | say something to a running agent. It reaches the model after its next tool call, as context — it changes none of the step's tools. `--step <n>` picks one when a parallel group has several running. Platform only |
108
110
  | `foldrun secrets set NAME` | store a secret — also `ls`, `rm`, and `status` (OAuth grant health). `--site <domain>` (repeatable, or `a,b`) binds it as it is stored |
109
111
  | `foldrun secrets sites NAME [site…]` | bind a secret to the sites it is for: the egress proxy fills it in requests to those sites alone, and it never enters a sandbox ([bound to sites](secrets#bound-to-sites)). No sites prints what it is bound to; `--clear` unbinds. On the platform, or this machine's vault with `--local` |
110
- | `foldrun secrets set NAME --kind <k>` | the other shapes the Connections form stores: `file` (`--file <path>`), `ssh` (`--host`, `--user`, `--port`, `--key-file <path>` or a prompted password), `api` (`--base-url`, `--header "Name: value"` repeatable, or `--basic-user <u>` with the password prompted or `--basic-password`), `service-account` (`--file <key.json>`, `--scopes`, `--subject <user>` to act as a user where the provider allows it), `client-cert` (`--cert-file`, `--key-file`, `--passphrase`, `--export` to put it in the sandbox as files too; bind it with `secrets sites`), `identity` (`--audience`: keyless cloud access — nothing secret is stored), `m2m` (a client-credentials app: `--token-url`, `--client-id`, `--scopes`, the secret prompted). On the platform, or this machine's vault with `--local` |
111
- | `foldrun secrets clients` | the OAuth clients saved on the platform — what a consent runs from without typing the client again; the client secret is never shown. `clients add <name> --authorize-url … --token-url … --client-id … --scopes …` saves one (secret prompted), with `--authorize-param name=value` for anything else the provider's authorize URL takes, `clients rm <name>` removes it |
112
- | `foldrun connect NAME` | OAuth sign-in from the terminal, stored as an auto-refreshing secret — `--authorize-url` and `--token-url` from the provider's OAuth docs, `--authorize-param name=value` for its extras; PKCE is on (`--no-pkce` only for an app with a secret whose provider refuses it), and an app with no client secret is a public app; reconnecting a secret whose client is saved asks for nothing (`--new-client` to enter one) |
112
+ | `foldrun secrets set NAME --kind <k>` | the other shapes the Connections form stores: `file` (`--file <path>`), `ssh` (`--host`, `--user`, `--port`, `--key-file <path>` or a prompted password), `api` (`--base-url`, `--header "Name: value"` repeatable, or `--basic-user <u>` with the password prompted or `--basic-password`), `service-account` (`--file <key.json>`, `--scopes`, `--subject <user>` to act as a user where the provider allows it), `client-cert` (`--cert-file`, `--key-file`, `--passphrase`, `--export` to put it in the sandbox as files too; bind it with `secrets sites`), `identity` (`--audience`: keyless cloud access — nothing secret is stored), `m2m` (a client-credentials app: `--token-url`, `--client-id`, `--scopes`, the secret prompted, `--token-auth basic` for a provider that takes the secret only as HTTP Basic). On the platform, or this machine's vault with `--local` |
113
+ | `foldrun secrets clients` | the OAuth clients saved on the platform — what a consent runs from without typing the client again; the client secret is never shown. `clients add <name> --authorize-url … --token-url … --client-id … --scopes …` saves one (secret prompted), with `--authorize-param name=value` for anything else the provider's authorize URL takes and `--token-auth basic` for a provider that takes the secret only as HTTP Basic, `clients rm <name>` removes it |
114
+ | `foldrun connect NAME` | OAuth sign-in from the terminal, stored as an auto-refreshing secret — `--authorize-url` and `--token-url` from the provider's OAuth docs, `--authorize-param name=value` for its extras; PKCE is on (`--no-pkce` only for an app with a secret whose provider refuses it), and an app with no client secret is a public app; `--token-auth basic` sends the secret as HTTP Basic, for providers that refuse it in the form body; reconnecting a secret whose client is saved asks for nothing (`--new-client` to enter one) |
113
115
  | `foldrun connect NAME --client <saved>` | the Connections page's **Connect**: a consent from a client saved on the platform (`--scopes "<a b>"` asks for this connection's own scopes instead of the client's default; the connection keeps them). It opens a page in the dashboard where you, signed in, accept the connection before the provider is asked, returning to the platform's own callback, which stores the grant as NAME (`--to <workspace>` for a workspace's). Opens the browser (`--no-browser` prints the address) and waits for it to land |
114
116
  | `foldrun deploy [dir]` | push this account into an installation — every workspace and the shared library. `foldrun deploy <workspace>` pushes one. Never removes a workspace the platform has and the folder does not. It first prints where it is going and as whom (`deploying to <url> as <profile> (<email>)`); a deploy that would delete files the folder no longer has lists them and asks — what runs wrote (`storage/`, `state/`, the trigger log) is never deleted, so never listed. The confirmed list goes with the deploy; if the platform would now remove anything else it refuses and the CLI asks again. With no terminal (a script, a CI job, a coding agent) it refuses unless `--yes`. A deploy that only adds or changes files asks nothing |
115
117
  | `foldrun help <command>` | that command's usage and options. `foldrun <command> --help` and `-h` print the same and never run the command |
@@ -231,7 +233,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
231
233
  | `--payload <json\|text\|@file>` | `approve`: release a step waiting on `wait: event` with this body (`POST …/approve` `{ payload }`). JSON is sent as JSON, anything else as text; `@file` reads a file |
232
234
  | `--note "<text>"` | `approve`: guidance the approved step reads in its prompt — "approve, but skip the Sydney batch". `reject`: the reason, recorded on the trace |
233
235
  | `--read-only` | `mcp`: offer the AI app only the tools that read — no `run_flow`, `decide_approval`, `answer_question`, `message_run` or `stop_run` |
234
- | `--yes` | skip the confirmation, deliberately: `approve`, `stop`, `deploy` (when it would delete files), and a bulk `stop` or `rerun`, `flow rotate-hook`, `flow draft`, `assistant`, `a2a cancel`, `history restore`, `restore`, `billing plan`, `repo deploy`/`merge`, `workspace set name`, and every delete — `runs rm`, `storage rm`, `storage unshare`, `source rm`, `secrets rm`, `keys revoke`, `workspaces rm`. Required when there is no terminal to ask; without it nothing is deleted |
236
+ | `--yes` | skip the confirmation, deliberately: `approve`, `stop`, `deploy` (when it would delete files), and a bulk `stop` or `rerun`, `flow rotate-hook`, `flow draft`, `assistant`, `mcp disconnect`, `a2a cancel`, `history restore`, `restore`, `billing plan`, `repo deploy`/`merge`, `workspace set name`, and every delete — `runs rm`, `storage rm`, `storage unshare`, `source rm`, `secrets rm`, `keys revoke`, `workspaces rm`. Required when there is no terminal to ask; without it nothing is deleted |
235
237
  | `--json` | `report`: the raw run record instead of the report. `observe`, `usage`, `workspaces`, `workspaces show`, `agent ls`, `flow ls`, `agent import --list`, `assistant`, `backups requests`, `status --platform --history`, `team`: the raw document |
236
238
  | `--events <a,b>` | `account set notify`: which events are notified on — `failed`, `awaiting-approval`, `completed` |
237
239
  | `--watch` | `invoke`: follow the run's trace here as it happens; the exit code is the run's |
@@ -249,6 +251,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
249
251
  | `--scopes "<a b c>"` | `connect`: space-separated, as OAuth defines it |
250
252
  | `--client-id` / `--client-secret` | `connect`: the OAuth app; prompted when omitted, the secret never echoed |
251
253
  | `--port <n>` | `connect`: the loopback port (default 8642) |
254
+ | `--token-auth <how>` | `connect`, `secrets clients add`, `secrets set --kind m2m`, `secrets set --oauth2`: how the app proves itself at the token URL — `post` (the form body, the default), `basic` (HTTP Basic: Notion, Spotify, Reddit, Zoom) or `none` (a public app with no secret) |
252
255
  | `--role <r>` | `keys create`: `viewer`, `editor` (default) or `admin` |
253
256
  | `--expires <span>` | `keys create`: when it stops working — `30d`, `90d`, `365d` or `never` (default) |
254
257
  | `--grace <span>` | `keys rotate`: keep the old key working for `1h` or `24h` (default `0`: revoked now) |
package/docs/mcp.md CHANGED
@@ -9,16 +9,41 @@ the decisions — approve, answer, message, start, stop.
9
9
  Ask it "what is waiting on me in foldrun?", "why did last night's run of
10
10
  `weekly` fail?" or "approve the draft in run r-…, and say why".
11
11
 
12
- There are two ways in, and they serve the same tools:
12
+ There are three ways in, and they serve the same tools:
13
13
 
14
14
  | | needs | for |
15
15
  |---|---|---|
16
+ | OAuth | nothing: you approve the app in foldrun | claude.ai (web and phone), and any app that signs in by itself |
16
17
  | `foldrun mcp` | the CLI, signed in (`foldrun login`) | an app on the same machine — nothing to paste |
17
- | `POST /api/mcp` | an API key | an app that connects over HTTP, or a machine without the CLI |
18
+ | `POST /api/mcp` with a key | an API key | an app that takes a header, or a machine without the CLI |
18
19
 
19
20
  ## Connecting
20
21
 
21
- With the CLI, on a machine that is signed in:
22
+ ### claude.ai, and apps that sign in
23
+
24
+ In claude.ai: **Settings → Connectors → Add custom connector**, name it
25
+ foldrun, and give it your platform's MCP address:
26
+
27
+ ```
28
+ https://<your platform>/api/mcp
29
+ ```
30
+
31
+ Leave the OAuth client ID and secret empty — claude.ai registers itself. When
32
+ you click **Connect**, it sends you to foldrun: sign in if you are not, and a
33
+ page says which app is asking, where the answer goes (`claude.ai`), and lets
34
+ you choose:
35
+
36
+ - **what it may do** — read only (inbox, runs, flows, files), or read and act
37
+ (also start and stop runs, approve gates, answer and message agents);
38
+ - **which workspaces** — every one you may open, or the ones you tick.
39
+
40
+ **Connect** sends you back to claude.ai, connected; **Deny** sends it a no.
41
+ It is the same in the Claude apps on a phone, which share claude.ai's
42
+ connectors, and in any MCP client that follows the MCP authorization spec.
43
+
44
+ ### With the CLI
45
+
46
+ On a machine that is signed in:
22
47
 
23
48
  ```sh
24
49
  claude mcp add foldrun -- foldrun mcp # Claude Code
@@ -34,9 +59,13 @@ Claude Desktop, Cursor and other apps that take a JSON config:
34
59
  `foldrun mcp` forwards each message to the platform the CLI is signed in to,
35
60
  as the account `foldrun whoami` names — `--profile <name>` picks another
36
61
  signed-in account, `--url` and `--token` (or `FOLDRUN_URL`, `FOLDRUN_TOKEN`)
37
- another platform or key. It renews this machine's sign-in once when it starts,
38
- the way every platform command does. Typed into a terminal it prints how to
39
- connect and exits: it is for an app to start.
62
+ another platform or key. The account is pinned when it starts — `foldrun use`
63
+ in another terminal never moves a running session — and the key is read again
64
+ for every message, so a sign-in another command renews is picked up; the
65
+ renewal itself is checked again twice a day. Typed into a terminal it prints
66
+ how to connect and exits: it is for an app to start.
67
+
68
+ ### With a key
40
69
 
41
70
  Over HTTP, with a key from Settings → API keys:
42
71
 
@@ -46,8 +75,30 @@ claude mcp add --transport http foldrun https://<your platform>/api/mcp \
46
75
  ```
47
76
 
48
77
  Settings → API keys → **Connecting an AI app (MCP)** shows this install's
49
- address and the same lines. claude.ai's connectors sign in with OAuth, which
50
- this endpoint does not offer; connect through Claude Desktop or Claude Code.
78
+ address and the same lines.
79
+
80
+ ## Connected apps
81
+
82
+ Every app connected over OAuth is listed in Settings → API keys → **Connected
83
+ AI apps**: the app, where its answers went, whose approval, what access and
84
+ which workspaces, when it was connected and last used. **Disconnect** ends it —
85
+ every token it holds stops at once — and the person can connect it again. You
86
+ see your own; an admin sees everyone's and may disconnect any.
87
+
88
+ ```sh
89
+ foldrun mcp connections # yours, or everyone's for an admin (--all adds the disconnected)
90
+ foldrun mcp disconnect <id> # asks first; --yes on a pipe
91
+ ```
92
+
93
+ What a connection may do is decided at every call, not only when it was
94
+ approved: it acts as the person who approved it, at the lower of the role
95
+ they chose then and the role they hold now, in the workspaces both allow. A
96
+ person who leaves the account, or is made a viewer, takes their apps with
97
+ them. The access token lasts an hour and opens `/api/mcp` only — sent to any
98
+ other route it is refused. Refresh tokens rotate on every use, and one used
99
+ twice disconnects the app: someone else has a copy. Approving, disconnecting
100
+ and that automatic disconnect are in the audit log (`mcp.connected`,
101
+ `mcp.revoked`).
51
102
 
52
103
  ## The tools
53
104
 
@@ -115,11 +166,22 @@ answered `202` with no body. It sits under `/api`, so the proxy holds the same
115
166
  raw-path check, body limit and rate limit as for every other route.
116
167
 
117
168
  Refused before a message is read, as a JSON-RPC error with a real status: no
118
- key (`401`, with `WWW-Authenticate: Bearer`) — a session cookie never opens
119
- it —, a refused key (`401`/`403`), an `Origin` header that is not the
120
- platform's own (`403`; MCP clients send none), an `MCP-Protocol-Version` it
121
- does not speak (`400`). The route and request shape are in [the API
122
- reference](api#mcp--ai-apps-connecting-with-a-key).
169
+ credential (`401`, with `WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/api/mcp"`,
170
+ which is where an app that signs in starts) — a session cookie never opens
171
+ it —, a refused key or an expired or revoked token (`401`, `error="invalid_token"`),
172
+ an `Origin` header that is not the platform's own (`403`; MCP clients send
173
+ none), an `MCP-Protocol-Version` it does not speak (`400`). The route and
174
+ request shape are in [the API reference](api#mcp--ai-apps-connecting-with-a-key).
175
+
176
+ The sign-in follows the MCP authorization spec on OAuth 2.1:
177
+ `/.well-known/oauth-protected-resource` (RFC 9728) names this install as the
178
+ authorization server; `/.well-known/oauth-authorization-server` (RFC 8414)
179
+ lists the endpoints, PKCE `S256` only, and `mcp:read` / `mcp:write`; an app
180
+ registers itself (RFC 7591) or names itself by an `https` URL to its own
181
+ metadata document, which foldrun fetches through its SSRF guard; every token is
182
+ bound to this `/api/mcp` (RFC 8707). Redirect URIs are `https`, or `http` to
183
+ localhost for a desktop app — and for those the approval page warns that the
184
+ app is on this computer.
123
185
 
124
186
  `foldrun mcp` reads one message per line on stdin and writes one per line on
125
187
  stdout, and nothing else there: every note goes to stderr. Calls run side by
package/docs/secrets.md CHANGED
@@ -290,6 +290,28 @@ How a connection is kept safe, whatever the provider:
290
290
  - A provider that **rotates refresh tokens** sends a new one with each
291
291
  refresh; it replaces the old one in the vault, where that secret is kept.
292
292
 
293
+ ### How the app signs in at the token URL
294
+
295
+ The client secret goes to the provider's token URL every time a code is
296
+ traded or a token refreshed. Providers take it one of two ways, and the form's
297
+ **Client authentication at the token URL** (CLI: `--token-auth`) says which:
298
+
299
+ | Setting | What is sent | Who wants it |
300
+ |---|---|---|
301
+ | in the form body (default) | `client_id` and `client_secret` as form fields | most providers: Google, Microsoft, GitHub, LinkedIn, Slack |
302
+ | HTTP Basic | an `Authorization: Basic` header (RFC 6749 §2.3.1) | Notion, Spotify, Reddit, Zoom, and any provider whose docs say Basic |
303
+ | none | `client_id` only | a public app, which has no secret (PKCE protects it) |
304
+
305
+ If the provider answers `invalid_client` when you connect, try the other
306
+ setting. The choice stays with the saved app and the secret, so refreshes
307
+ and **Reconnect** sign in the same way. Secrets stored before 1 Nov 2026 keep
308
+ sending the form body.
309
+
310
+ Whatever the token URL sends back is read as providers actually write it: JSON
311
+ or form-encoded, `expires_in` as a number or a string, and Slack's user token
312
+ nested under `authed_user`. Plain fields that come back beside the token,
313
+ such as Salesforce's `instance_url`, are kept with the secret.
314
+
293
315
  ## Keyless cloud identity
294
316
 
295
317
  The safest credential is none at all. A cloud that supports workload
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldrun",
3
- "version": "10.3.1",
3
+ "version": "10.5.0",
4
4
  "description": "Agents are just folders. Write them, check them, run them — on your machine.",
5
5
  "license": "FSL-1.1-ALv2",
6
6
  "type": "module",
@@ -11,7 +11,7 @@
11
11
  "node": ">=22"
12
12
  },
13
13
  "dependencies": {
14
- "@foldrun/core": "^9.2.1"
14
+ "@foldrun/core": "^9.3.0"
15
15
  },
16
16
  "files": [
17
17
  "bin",
package/src/commands.mjs CHANGED
@@ -3478,7 +3478,8 @@ async function secretsCmd(positional, flags, layout) {
3478
3478
  const client_id = await promptVisible(" client_id: ");
3479
3479
  const client_secret = await promptHidden(" client_secret: ");
3480
3480
  const refresh_token = await promptHidden(" refresh_token: ");
3481
- const config = { token_url, client_id, client_secret, refresh_token };
3481
+ const token_auth = await tokenAuthFlag(flags);
3482
+ const config = { token_url, client_id, client_secret, refresh_token, ...(token_auth ? { token_auth } : {}) };
3482
3483
  if (url) {
3483
3484
  await remoteCall(url, flags, "/api/secrets", {
3484
3485
  method: "PUT",
@@ -3824,9 +3825,19 @@ function warnProviderDeprecated(flags) {
3824
3825
  }
3825
3826
  }
3826
3827
 
3828
+ /** `--token-auth basic|post|none` (or the RFC names) — how the app proves
3829
+ * itself at the token URL; absent when the flag is. */
3830
+ async function tokenAuthFlag(flags) {
3831
+ if (flags["token-auth"] === undefined) return undefined;
3832
+ const { parseTokenAuth } = await core();
3833
+ const auth = typeof flags["token-auth"] === "string" ? parseTokenAuth(flags["token-auth"]) : null;
3834
+ if (!auth) throw new Error("--token-auth is basic (HTTP Basic: Notion, Spotify, Reddit, Zoom), post (the form body, the default) or none (a public app)");
3835
+ return auth;
3836
+ }
3837
+
3827
3838
  async function connect(positional, flags) {
3828
3839
  const name = positional[0];
3829
- if (!name) throw new Error("usage: foldrun connect NAME --authorize-url <url> --token-url <url> [--authorize-param name=value …] [--scopes …] [--workspace <name>] [--new-client]");
3840
+ if (!name) throw new Error("usage: foldrun connect NAME --authorize-url <url> --token-url <url> [--authorize-param name=value …] [--scopes …] [--token-auth basic|post|none] [--workspace <name>] [--new-client]");
3830
3841
  if (!/^[A-Z][A-Z0-9_]*$/.test(name)) throw new Error(`secret name "${name}" must be UPPER_SNAKE_CASE`);
3831
3842
  const { OAUTH_PRESETS } = await core();
3832
3843
 
@@ -3898,6 +3909,12 @@ async function connect(positional, flags) {
3898
3909
  if (!clientId) throw new Error("client_id is required");
3899
3910
  // No secret is a public app, which PKCE alone protects (RFC 9700 §2.1.1).
3900
3911
  if (!clientSecret && !pkce) throw new Error("an app with no client_secret needs PKCE — drop --no-pkce");
3912
+ const tokenAuth = await tokenAuthFlag(flags);
3913
+ const { oauthTokenRequest, readTokenResponse, tokenAuthProblem } = await core();
3914
+ // Before the browser opens: a consent is never spent on a client that
3915
+ // cannot then authenticate (Basic with no secret, none with one).
3916
+ const authProblem = tokenAuthProblem({ client_secret: clientSecret, token_auth: tokenAuth });
3917
+ if (authProblem) throw new Error(authProblem);
3901
3918
  const scopes = flags.scopes ?? preset?.scopes_example ?? "";
3902
3919
 
3903
3920
  // One fixed loopback address, the same on every developer's machine, so an
@@ -3960,16 +3977,15 @@ async function connect(positional, flags) {
3960
3977
  });
3961
3978
  if (!code) throw new Error("the redirect carried no code");
3962
3979
 
3963
- const exchange = await fetch(tokenUrl, {
3964
- method: "POST",
3965
- headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
3966
- body: new URLSearchParams({
3967
- grant_type: "authorization_code", code, redirect_uri: redirectUri, client_id: clientId,
3968
- ...(clientSecret ? { client_secret: clientSecret } : {}),
3969
- ...(verifier ? { code_verifier: verifier } : {}),
3970
- }).toString(),
3971
- });
3972
- const payload = /** @type {any} */ (await exchange.json().catch(() => ({})));
3980
+ // Core's one token-request builder: the secret in the body or a Basic
3981
+ // header, as --token-auth says; the answer read however the provider
3982
+ // wrote it (form-encoded, Slack's nested user token, a string expiry).
3983
+ const request = oauthTokenRequest(
3984
+ { client_id: clientId, ...(clientSecret ? { client_secret: clientSecret } : {}), ...(tokenAuth ? { token_auth: tokenAuth } : {}) },
3985
+ { grant_type: "authorization_code", code, redirect_uri: redirectUri, ...(verifier ? { code_verifier: verifier } : {}) },
3986
+ );
3987
+ const exchange = await fetch(tokenUrl, { method: "POST", headers: request.headers, body: request.body, redirect: "error" });
3988
+ const payload = readTokenResponse(await exchange.text().catch(() => ""), exchange.headers.get("content-type") ?? "");
3973
3989
  if (!exchange.ok || (!payload.refresh_token && !payload.access_token)) {
3974
3990
  throw new Error(`token exchange failed (${exchange.status}): ${payload.error_description ?? payload.error ?? "no token in the reply"}`);
3975
3991
  }
@@ -3977,7 +3993,7 @@ async function connect(positional, flags) {
3977
3993
  // Store: the refresh recipe when there is one, the bare token otherwise.
3978
3994
  /** @type {any} */
3979
3995
  const body = payload.refresh_token
3980
- ? { name, oauth2: { token_url: tokenUrl, client_id: clientId, ...(clientSecret ? { client_secret: clientSecret } : {}), refresh_token: payload.refresh_token }, workspace: workspaceName, scopes, ...(payload.refresh_token_expires_in ? { refresh_token_expires_in: payload.refresh_token_expires_in } : {}) }
3996
+ ? { name, oauth2: { token_url: tokenUrl, client_id: clientId, ...(clientSecret ? { client_secret: clientSecret } : {}), refresh_token: payload.refresh_token, ...(tokenAuth ? { token_auth: tokenAuth } : {}), ...(Object.keys(payload.fields).length ? { fields: payload.fields } : {}) }, workspace: workspaceName, scopes, ...(payload.refresh_token_expires_in ? { refresh_token_expires_in: payload.refresh_token_expires_in } : {}) }
3981
3997
  : { name, value: payload.access_token, workspace: workspaceName };
3982
3998
  if (url) {
3983
3999
  // The same PUT `secrets set` makes. A store that fails here has spent the
@@ -6632,7 +6648,17 @@ function issueDoctor(issue) {
6632
6648
  * @param {string[]} positional @param {Record<string, any>} flags
6633
6649
  */
6634
6650
  async function mcpCmd(positional, flags) {
6635
- if (positional.length) throw new Error("`foldrun mcp` takes no arguments — an AI app starts it: `claude mcp add foldrun -- foldrun mcp` (--read-only for the tools that read)");
6651
+ const [verb, arg, ...extra] = positional;
6652
+ if (verb === "connections" || verb === "ls") return mcpConnectionsCmd(flags);
6653
+ if (verb === "disconnect" || verb === "revoke") {
6654
+ if (!arg || extra.length) throw new Error("which connection? `foldrun mcp disconnect <id>` — ids are in `foldrun mcp connections`");
6655
+ const url = platformFor(flags, "mcp disconnect");
6656
+ if (!(await sureToDelete(flags, "mcp disconnect", `the AI app connection ${arg} on ${url} (every token it holds stops working)`))) return 1;
6657
+ await remoteCall(url, flags, `/api/mcp/connections/${encodeURIComponent(arg)}`, { method: "DELETE" });
6658
+ console.log(`\n ${c.green("✓")} disconnected ${arg}\n`);
6659
+ return 0;
6660
+ }
6661
+ if (positional.length) throw new Error("`foldrun mcp` serves the tools to an AI app (`claude mcp add foldrun -- foldrun mcp`); its verbs are connections and disconnect <id> — not " + verb);
6636
6662
  if (process.stdin.isTTY && flags.yes !== true) {
6637
6663
  console.error(`\n ${c.bold("foldrun mcp")} is an MCP server on stdin/stdout, for an AI app to start — not to type into.\n\n claude mcp add foldrun -- foldrun mcp${flags["read-only"] === true ? " --read-only" : ""}\n codex mcp add foldrun -- foldrun mcp\n\n ${c.dim("Claude Desktop, Cursor: { \"mcpServers\": { \"foldrun\": { \"command\": \"foldrun\", \"args\": [\"mcp\"] } } } — `foldrun docs mcp`")}\n`);
6638
6664
  return 2;
@@ -6737,6 +6763,28 @@ async function mcpCmd(positional, flags) {
6737
6763
  return 0;
6738
6764
  }
6739
6765
 
6766
+ /** `foldrun mcp connections` — the AI apps connected to the account over OAuth
6767
+ * (claude.ai and the like): which app, whose approval, what access. Every
6768
+ * one for an admin; your own otherwise. */
6769
+ async function mcpConnectionsCmd(flags) {
6770
+ const url = platformFor(flags, "mcp connections");
6771
+ const view = await remoteCall(url, flags, `/api/mcp/connections${flags.all === true ? "?all=1" : ""}`);
6772
+ if (flags.json) {
6773
+ console.log(JSON.stringify(view, null, 2));
6774
+ return 0;
6775
+ }
6776
+ const rows = view.connections ?? [];
6777
+ console.log(`\n ${c.bold("AI apps connected over OAuth")} ${c.dim(view.everyone ? "· everyone's" : "· yours")}`);
6778
+ if (!rows.length) console.log(`\n ${c.dim("none — claude.ai connects itself when you add this platform's /api/mcp as a custom connector")}`);
6779
+ for (const r of rows) {
6780
+ const used = r.lastUsedAt ? `last used ${String(r.lastUsedAt).slice(0, 16).replace("T", " ")}` : "not used yet";
6781
+ console.log(`\n ${c.bold(r.client)} ${c.dim(`· ${r.redirectHost} · ${r.access === "read" ? "read only" : "read and act"} · ${r.workspaces ? r.workspaces.join(", ") : "all workspaces"}`)}${r.revokedAt ? c.red(" · disconnected") : ""}`);
6782
+ console.log(` ${c.dim(`${r.id} · ${r.person} · connected ${String(r.createdAt).slice(0, 16).replace("T", " ")} · ${used}`)}`);
6783
+ }
6784
+ console.log("");
6785
+ return 0;
6786
+ }
6787
+
6740
6788
  async function inboxCmd(positional, flags) {
6741
6789
  const url = platformFor(flags, "inbox");
6742
6790
  const [verb, ...ids] = positional;
@@ -11630,7 +11678,7 @@ async function oauthClientsCmd(positional, flags) {
11630
11678
  return 0;
11631
11679
  }
11632
11680
  if (verb === "add") {
11633
- if (!name || !/^[a-z0-9][a-z0-9-]*$/.test(name)) throw new Error("`foldrun secrets clients add <name> --authorize-url … --token-url … --client-id … [--authorize-param name=value …] [--scopes …]` — the name in kebab-case");
11681
+ if (!name || !/^[a-z0-9][a-z0-9-]*$/.test(name)) throw new Error("`foldrun secrets clients add <name> --authorize-url … --token-url … --client-id … [--authorize-param name=value …] [--scopes …] [--token-auth basic|post|none]` — the name in kebab-case");
11634
11682
  warnProviderDeprecated(flags);
11635
11683
  const { OAUTH_PRESETS } = await core();
11636
11684
  const preset = flags.provider ? OAUTH_PRESETS[flags.provider] : undefined;
@@ -11645,11 +11693,13 @@ async function oauthClientsCmd(positional, flags) {
11645
11693
  if (!client_id) throw new Error("client_id is required");
11646
11694
  if (!client_secret && !pkce) throw new Error("an app with no client_secret needs PKCE — drop --no-pkce");
11647
11695
  if (flags.issuer !== undefined && (typeof flags.issuer !== "string" || !/^https:\/\/[^?#]+$/.test(flags.issuer))) throw new Error("--issuer is the provider's https issuer URL, no query or fragment");
11696
+ const token_auth = await tokenAuthFlag(flags);
11648
11697
  const config = {
11649
11698
  authorize_url, token_url, client_id, client_secret: client_secret ?? "", scopes: flags.scopes ?? preset?.scopes_example ?? "",
11650
11699
  ...(Object.keys(authorize_extra).length ? { authorize_extra } : {}),
11651
11700
  ...(pkce ? {} : { pkce: false }),
11652
11701
  ...(typeof flags.issuer === "string" ? { issuer: flags.issuer } : {}),
11702
+ ...(token_auth ? { token_auth } : {}),
11653
11703
  };
11654
11704
  await remoteCall(url, flags, "/api/oauth/clients", { method: "POST", body: JSON.stringify({ name, config }) });
11655
11705
  console.log(`\n ${c.green("✓")} saved ${name} ${c.dim(`— \`foldrun connect NAME --client ${name}\` runs a consent from it`)}\n`);
@@ -11758,7 +11808,8 @@ async function secretOfKind(kind, flags) {
11758
11808
  if (typeof flags["token-url"] !== "string") throw new Error("--kind m2m needs --token-url, --client-id (and the client secret, prompted or --client-secret)");
11759
11809
  const client_id = flags["client-id"] ?? (await promptVisible(" client_id: "));
11760
11810
  const client_secret = flags["client-secret"] ?? (await promptHidden(" client_secret: "));
11761
- const oauth2 = { token_url: flags["token-url"], client_id, client_secret, grant_type: "client_credentials", ...(flags.scopes ? { extra: { scope: flags.scopes } } : {}) };
11811
+ const token_auth = await tokenAuthFlag(flags);
11812
+ const oauth2 = { token_url: flags["token-url"], client_id, client_secret, grant_type: "client_credentials", ...(flags.scopes ? { extra: { scope: flags.scopes } } : {}), ...(token_auth ? { token_auth } : {}) };
11762
11813
  return { body: { oauth2 }, local: (k, n, b, s, l) => k.setOAuth2Secret("default", n, b.oauth2, s, l) };
11763
11814
  }
11764
11815
  default: