foldrun 10.4.0 → 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/docs/api.md +1 -1
- package/docs/cli.md +4 -3
- package/docs/secrets.md +22 -0
- package/package.json +2 -2
- package/src/commands.mjs +34 -15
package/docs/api.md
CHANGED
|
@@ -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 |
|
package/docs/cli.md
CHANGED
|
@@ -109,9 +109,9 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
109
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 |
|
|
110
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 |
|
|
111
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` |
|
|
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). 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, `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; 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) |
|
|
115
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 |
|
|
116
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 |
|
|
117
117
|
| `foldrun help <command>` | that command's usage and options. `foldrun <command> --help` and `-h` print the same and never run the command |
|
|
@@ -251,6 +251,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
251
251
|
| `--scopes "<a b c>"` | `connect`: space-separated, as OAuth defines it |
|
|
252
252
|
| `--client-id` / `--client-secret` | `connect`: the OAuth app; prompted when omitted, the secret never echoed |
|
|
253
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) |
|
|
254
255
|
| `--role <r>` | `keys create`: `viewer`, `editor` (default) or `admin` |
|
|
255
256
|
| `--expires <span>` | `keys create`: when it stops working — `30d`, `90d`, `365d` or `never` (default) |
|
|
256
257
|
| `--grace <span>` | `keys rotate`: keep the old key working for `1h` or `24h` (default `0`: revoked now) |
|
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
|
+
"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.
|
|
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
|
|
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
|
-
|
|
3964
|
-
|
|
3965
|
-
|
|
3966
|
-
|
|
3967
|
-
|
|
3968
|
-
|
|
3969
|
-
|
|
3970
|
-
|
|
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
|
|
@@ -11662,7 +11678,7 @@ async function oauthClientsCmd(positional, flags) {
|
|
|
11662
11678
|
return 0;
|
|
11663
11679
|
}
|
|
11664
11680
|
if (verb === "add") {
|
|
11665
|
-
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");
|
|
11666
11682
|
warnProviderDeprecated(flags);
|
|
11667
11683
|
const { OAUTH_PRESETS } = await core();
|
|
11668
11684
|
const preset = flags.provider ? OAUTH_PRESETS[flags.provider] : undefined;
|
|
@@ -11677,11 +11693,13 @@ async function oauthClientsCmd(positional, flags) {
|
|
|
11677
11693
|
if (!client_id) throw new Error("client_id is required");
|
|
11678
11694
|
if (!client_secret && !pkce) throw new Error("an app with no client_secret needs PKCE — drop --no-pkce");
|
|
11679
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);
|
|
11680
11697
|
const config = {
|
|
11681
11698
|
authorize_url, token_url, client_id, client_secret: client_secret ?? "", scopes: flags.scopes ?? preset?.scopes_example ?? "",
|
|
11682
11699
|
...(Object.keys(authorize_extra).length ? { authorize_extra } : {}),
|
|
11683
11700
|
...(pkce ? {} : { pkce: false }),
|
|
11684
11701
|
...(typeof flags.issuer === "string" ? { issuer: flags.issuer } : {}),
|
|
11702
|
+
...(token_auth ? { token_auth } : {}),
|
|
11685
11703
|
};
|
|
11686
11704
|
await remoteCall(url, flags, "/api/oauth/clients", { method: "POST", body: JSON.stringify({ name, config }) });
|
|
11687
11705
|
console.log(`\n ${c.green("✓")} saved ${name} ${c.dim(`— \`foldrun connect NAME --client ${name}\` runs a consent from it`)}\n`);
|
|
@@ -11790,7 +11808,8 @@ async function secretOfKind(kind, flags) {
|
|
|
11790
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)");
|
|
11791
11809
|
const client_id = flags["client-id"] ?? (await promptVisible(" client_id: "));
|
|
11792
11810
|
const client_secret = flags["client-secret"] ?? (await promptHidden(" client_secret: "));
|
|
11793
|
-
const
|
|
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 } : {}) };
|
|
11794
11813
|
return { body: { oauth2 }, local: (k, n, b, s, l) => k.setOAuth2Secret("default", n, b.oauth2, s, l) };
|
|
11795
11814
|
}
|
|
11796
11815
|
default:
|