@finchtech/cli 0.3.9 → 0.4.0

package/README.md

@@ -20,13 +20,21 @@ Intent HTTP failures include `remotePath: "/api/skills/intents"`, `remoteStatus`
 
 The CLI measures the exact final multipart request, including metadata and framing. At or below 4,000,000 bytes it posts that request to the inline upload route. Above it the object goes through the staged transport instead: the CLI asks for a signed URL, writes the bytes straight to storage, and has the server read them back, verify them and pin them, so the platform's 4,500,000-byte request-body limit does not apply. These MB thresholds are decimal. The per-object ceilings are enforced against the final object either way: 30 MiB (31,457,280 bytes) for a package, 5 MiB for a cover, and 3 MiB (3,145,728 bytes) for a manifest. The package ceiling is one shared constant, applied by upload admission, by the retrieval route, by this client before it uploads, and by this client when it downloads, so a package that publishes is a package that reads back. Repacking a compressed source ZIP may increase its size. Passing admission does not certify production upload success or authorize replaying a previously failed publication.
 
-The command groups are `wallet`, `login/status/logout`, `site`, `mcp doctor`, `mcp authorize`, `mcp grant`, `creator`, `credentials`, `intent`, `operation show`, `purchase`, `task`, and `skill`. Run `finch --help` for the exact command list as one JSON value.
+The command groups are `wallet`, `login/status/logout`, `site`, `mcp doctor`, `mcp connect`, `mcp authorize`, `mcp grant`, `creator`, `credentials`, `intent`, `operation show`, `purchase`, `task`, and `skill`. Run `finch --help` for the exact command list as one JSON value.
 
 `finch site open` creates a sixty-second one-use handoff from the active AgentCLI Session and opens the exact configured Finch origin in the local default Browser. `finch site login <REQUEST_URL>` binds a website-created five-minute request once, then opens the same confirmation page. Both commands require the wallet, CLI, and graphical Browser on the user's machine. A launch failure returns `BROWSER_OPEN_FAILED` without printing the secret completion URL. The Browser receives only a normal seven-day Finch Web Session; wallet signing, broadcast, and market confirmation remain local CLI actions.
 
-`finch mcp doctor` is read-only. It returns a `checks` object for endpoint, wallet, local Session, remote Session authority, and MCP discovery. Each check reports `ok`, `missing`, `invalid`, `unavailable`, or `skipped`, with guidance for unhealthy checks. Missing login or wallet state does not prevent independent discovery checks; an invalid endpoint prevents network checks. The command emits one JSON report with exit code 0 when ready, or 2 when any required check is unhealthy. It verifies the endpoint, wallet/key binding, Account, Session identity, environment, audience and expiry, plus the MCP challenge and required OAuth capabilities. Each remote read has a 15-second timeout. Wallet inspection does not migrate legacy files. Client guide availability, client names, guide versions and repository paths do not affect readiness; `compatibilityManifestUrl` is only an informational link. The Agent Harness owns Remote MCP configuration, OAuth credentials, and refresh; the CLI does not configure or launch the Harness and never reads Harness OAuth material. During the Harness's native OAuth flow, the authorization page supplies an exact `finch mcp authorize <REQUEST_TOKEN>` command. The versioned base64url token carries the original OAuth request without shell metacharacters so Windows package-manager and Volta launchers cannot split it; the CLI decodes it before applying the existing origin, callback, state, and scope checks. That command uses only the active local AgentCLI Session and opens the verified callback without returning its one-use code. It never uses a Browser Session, Social account, or extension wallet as Agent authority. Configure `https://www.finchtech.ai/mcp` once through the Harness, then use MCP `identity_actor_get` together with `finch status` to verify exact Account and wallet alignment before custody. The server-reported environment is diagnostic and never selects the CLI endpoint or a transaction chain.
+`finch mcp doctor` is read-only. It returns a `checks` object for endpoint, wallet, local Session, remote Session authority, and MCP discovery. Each check reports `ok`, `missing`, `invalid`, `unavailable`, or `skipped`, with guidance for unhealthy checks. Missing login or wallet state does not prevent independent discovery checks; an invalid endpoint prevents network checks. The command emits one JSON report with exit code 0 when ready, or 2 when any required check is unhealthy. It verifies the endpoint, wallet/key binding, Account, Session identity, environment, audience and expiry, plus the MCP challenge and required OAuth capabilities. Each remote read has a 15-second timeout. Wallet inspection does not migrate legacy files. Client guide availability, client names, guide versions and repository paths do not affect readiness; `compatibilityManifestUrl` is only an informational link. The Agent Harness owns Remote MCP configuration, OAuth credentials, and refresh; the CLI never configures the Harness and never reads Harness OAuth material.
 
-Doctor's `ready: true` is scoped by `readinessScope: "cli_session_and_mcp_discovery"`. Its `harnessOAuth.status` is always `not_checked`: CLI login and valid discovery metadata do not establish that the connected Harness has usable OAuth credentials, a saved issuer, or working refresh. The result includes identity-verification and native reauthorization guidance. If the Harness reports an OAuth failure, complete its native MCP authorization flow and the authorization page's fresh `finch mcp authorize` command, then verify MCP identity again.
+The CLI approves the Harness's native OAuth request with the active local AgentCLI Session through one of three entry points, tried in this order:
+
+1. `finch mcp connect -- <MCP_CLIENT_LOGIN_COMMAND...>` runs the MCP client's own login command, for example `finch mcp connect -- codex mcp login finch --no-browser`. It keeps the command's stdin open while it waits, forwards its output to stderr with the authorization code redacted, takes the first `<origin>/oauth/authorize?` URL it prints (including an OSC 8 hyperlink target), and approves only that one request. It then waits a bounded time for the command to exit and reports `loginCommandExitCode: 0`; a second, different authorization request, a missing URL, or a failed or hanging command is a typed `MCP_AUTHORIZATION_FLOW_FAILED` error whose message names the next step.
+2. `finch mcp authorize --stdin` reads one raw authorization URL that the Agent copied unchanged from the client output, for example `printf '%s' '<URL>' | finch mcp authorize --stdin`. A URL is never accepted as an argument, because Windows package-manager and Volta launchers split it at `&`.
+3. `finch mcp authorize <REQUEST_TOKEN>` runs the exact command shown on the Finch authorization page when the Agent cannot see the URL. The versioned base64url token carries the original request without shell metacharacters.
+
+Each entry point applies the same origin, redirect, state, scope, and RFC 9207 issuer checks. A loopback HTTP callback is delivered directly to the waiting listener on this machine, without a Browser or any Finch credential and without following redirects; `localhost` is tried on each loopback address it resolves to only while no connection exists, and a lost response is reported as uncertain rather than resent. An HTTPS callback, such as a proxied workstation or a web editor, is opened in the local Browser. The one-use code is never returned. Exit code 0 of the login command shows only that it exited successfully; confirm the connection with the Harness's own `identity_actor_get`. The server refuses a CLI older than 0.4.0 with an upgrade instruction before issuing a code. No entry point uses a Browser Session, Social account, or extension wallet as Agent authority. Configure `https://www.finchtech.ai/mcp` once through the Harness, then use MCP `identity_actor_get` together with `finch status` to verify exact Account and wallet alignment before custody. The server-reported environment is diagnostic and never selects the CLI endpoint or a transaction chain.
+
+Doctor's `ready: true` is scoped by `readinessScope: "cli_session_and_mcp_discovery"`. Its `harnessOAuth.status` is always `not_checked`: CLI login and valid discovery metadata do not establish that the connected Harness has usable OAuth credentials, a saved issuer, or working refresh. The result includes identity-verification and native reauthorization guidance. If the Harness reports an OAuth failure, start its native MCP authorization flow again, approve the fresh request through the entry points above, then verify MCP identity again.
 
 Run `finch login --help` to list supported production authentication chain IDs (1, 10, 56, 8453, 42161). For example, `finch login --chain-id 56` selects BNB Smart Chain for authentication only.
 
@@ -55,7 +63,7 @@ Version 0.3.1 fixes Skill search continuation: pass the returned `nextCursor` un
 Older clients receive an upgrade message from the Skill search API.
 
 Version 0.3.0 upgrades Skill publication and encrypted delivery together. Upgrade with
-`pnpm add -g @finchtech/cli@0.3.9` and verify `finch --version` before publishing new Skills
+`pnpm add -g @finchtech/cli@0.4.0` and verify `finch --version` before publishing new Skills
 or downloading encrypted Skills from the upgraded gateway. Older CLI versions cannot use
 the new encrypted delivery, including for historical Skills; 0.3.0 retains historical package support.
 
@@ -134,3 +142,7 @@ CLI 0.3.7 supports authorized external-media manifests and 30 MiB final packages
 ## Diagnostic and interoperability fixes (CLI 0.3.9+)
 
 CLI 0.3.9 removes the `mcp.supportedClients` field from doctor. Its health checks do not fetch client guides or migrate legacy wallet files. Omitted or empty OAuth scope uses the server-resolved registered defaults; explicit requested scopes remain checked. Callback target, original query values and state remain verified, independently of query ordering or authorization-code length. Upgrade the installed CLI to receive these fixes; updating the Skill or website alone does not apply them.
+
+## MCP connection without a Browser (CLI 0.4.0+)
+
+CLI 0.4.0 adds `finch mcp connect` and `finch mcp authorize --stdin`, delivers loopback OAuth callbacks directly instead of opening them in a Browser, and verifies the RFC 9207 `iss` the Finch authorization server now advertises. It identifies its release on authorization, and the server refuses older releases with an upgrade instruction because they cannot accept `iss`. Upgrade the installed CLI; updating the Skill or website alone does not apply this.

package/THIRD_PARTY_LICENSES.txt

@@ -9,8 +9,12 @@ The bundle contains the following third-party packages:
 - @scure/bip32 1.7.0 — Copyright (c) 2022 Patricio Palladino, Paul Miller (paulmillr.com)
 - @scure/bip39 1.6.0 — Copyright (c) 2022 Patricio Palladino, Paul Miller (paulmillr.com)
 - ajv 8.20.0 — Copyright (c) 2015-2021 Evgeny Poberezkin
+- cross-spawn 7.0.6 — Copyright (c) 2018 Made With MOXY Lda <hello@moxy.studio>
 - fast-deep-equal 3.1.3 — Copyright (c) 2017 Evgeny Poberezkin
 - json-schema-traverse 1.0.0 — Copyright (c) 2017 Evgeny Poberezkin
+- path-key 3.1.1 — Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)
+- shebang-command 2.0.0 — Copyright (c) Kevin Mårtensson <kevinmartensson@gmail.com> (github.com/kevva)
+- shebang-regex 3.0.0 — Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)
 - viem 2.55.15 — Copyright (c) 2023-present weth, LLC
 
 Each package above is distributed under the MIT License:
@@ -69,6 +73,25 @@ POSSIBILITY OF SUCH DAMAGE.
 The complete fast-uri contributor list is available at:
 https://github.com/garycourt/uri-js/graphs/contributors
 
+which 2.0.2 and isexe 2.0.0
+---------------------------
+
+The ISC License
+
+Copyright (c) Isaac Z. Schlueter and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
 
 SkillRoot and ZIP import dependencies
 =====================================