[aterga]

Summary

Stage 2 of the local-deployment design (docs merged in #148, Stage 1 merged in #77): ship imcp2-local, the single-user binary an AI tool (Claude Desktop/Code, Codex, Cursor, …) spawns and talks to over stdio. It serves the same tool surface as the hosted server against the same mainnet and production Internet Identity, and carries none of the hosted server's OAuth machinery — signing in is a built-in browser handshake behind an in-band authenticate tool. No behavior change to the hosted server.

Related issues

Implements Implementation Stages → Stage 2 of the design docs merged in #148 (components 3–7).

Changes

• crates/imcp2-local (new bin crate, publish = false — distributed as release binaries per the design's Stage 3):
  • Login driver (login.rs): authenticate mints a fresh session id + registration key, binds a transient loopback listener on 127.0.0.1:0, and returns the id.ai connect link in-band (plus best-effort open::that), never blocking on the callback. Exactly three routes — the pinned callback page (shared with hosted, same CSP + hardening headers), the slim redeem, and the #4091 allow-list (CORS-readable, no-store) — Host-validated against the listener's own authority (anti-DNS-rebinding, per the design's loopback hardening), torn down on redeem, on the 10-minute handshake timeout (hosted's CONNECT_TTL), or when a fresh flow replaces it. The redeem mirrors the hosted order (validate state → parse before claiming → single-flight claim → one mcp_register_v2 call) minus the OAuth tail: success answers {"done": true}; a registration mutex serializes register+commit across flows so the local slot always names the session II actually honors.
  • Wrapper handler (server.rs): the two local-only login tools live on LocalServer's own #[tool_router]; tools/list is the merged surface (26 core + 2), tools/call dispatches to the login router first and forwards everything else (calls, resources, get_tool) to the inner IcTools handler verbatim. Both tools declare object-rooted outputSchemas and attach matching structuredContent. get_info identifies as imcp2-local and appends sign-in guidance to core's instructions.
  • main.rs: mainnet agent (IMCP2_IC_URL override; IMCP2_FETCH_ROOT_KEY honoured only for loopback endpoints — the local-replica test configuration), production II (II_URL_PROD/II_CANISTER_ID_PROD), management identity derived at the hosted origin by default (IMCP2_MANAGEMENT_ORIGIN) so the same anchor keeps the same controller principal across deployments, IMCP2_NO_OPEN; all logging to stderr (stdout is the JSON-RPC channel).
• imcp2-core (the seams Stage 1 left for the login driver, refined per review):
  • Authentication stays in the embedding binary: IcTools takes an injected SessionResolver that only reports the already-validated session for a call. The hosted crate's require_token middleware validates the bearer and its resolver reads the stashed AuthedSession back (both defined in imcp2's auth.rs); the local binary's login flow fills its SessionSlot (defined in imcp2-local's login.rs) and injects a slot-reading resolver. Core drops its http dependency along the way.
  • The pinned callback page's script gains the {"done": true} success arm ("Signed in — you can close this tab", .done terminal state in connect.css); hosted keeps answering redirect.
  • Regression guard: the core router must never carry the login tools (it is the hosted tools/list).
• Workspace: imcp2-local added to members; axum/anyhow/uuid/tracing-subscriber pins lifted to [workspace.dependencies].

Testing

• cargo build --workspace --all-targets / cargo test --workspace --all-targets — all suites green (hosted 52+10+9 unchanged; core 142; imcp2-local 12, including forged-Host rejection via raw sockets and the MCP round-trip with structured-content assertions)
• Real MCP round-trip over an in-process duplex pipe: initialize → merged tools/list (28) → login lifecycle through tools/call (signed out → link → pending) → forwarded core tool
• Listener driven like the browser (reqwest): pinned page + strict CSP + hardening headers; allow-list matches the link's callback verbatim with Access-Control-Allow-Origin: * and no-store; redeem refusal paths (unknown state, malformed delegation, garbage signatures) all offline and all leave the flow retryable
• The built binary answers initialize/tools/list over real stdio (28 tools, identifies as imcp2-local)
• The full local login passes end to end against a live II canister in PocketIC (the e2e ships in the Stage 3 PR and was run against this branch's code)
• cargo check --features e2e --all-targets (hosted PocketIC harness intact); cargo fmt --check clean on the new crate; cargo clippy: no warnings in imcp2-local
• cargo publish --dry-run -p imcp2-core still rehearses; cargo package -p imcp2 is blocked on imcp2-core's first (manual) crates.io release — pre-existing, reproduced identically on the Stage 1 base commit

Checklist

• I have read the Contributing guidelines.
• Docs: the design docs merged in Design docs: IMCP2 local deployment (minimal stdio binary, no OAuth) #148 describe this stage; env vars are documented in the crate-level rustdoc.
• No secrets, credentials, or internal-only information are included.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01AqNkpMQiQHzYxC2djTfvBK

[Copilot]

Pull request overview

Adds the imcp2-local stdio binary with browser-based Internet Identity authentication while preserving hosted-server behavior.

Changes:

• Adds local login, session handling, and merged MCP tool routing.
• Makes singleton sessions replaceable and supports local callback completion.
• Registers the new crate and shared dependencies.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
crates/imcp2-local/src/server.rs	Wraps core tools with local authentication tools.
crates/imcp2-local/src/main.rs	Configures and launches the stdio server.
crates/imcp2-local/src/login.rs	Implements the loopback browser-login flow.
crates/imcp2-local/Cargo.toml	Defines the local binary crate.
crates/imcp2-core/src/tools.rs	Adds replaceable singleton sessions.
crates/imcp2-core/src/lib.rs	Exports SessionSlot.
crates/imcp2-core/src/iiconnect.rs	Handles local callback completion.
crates/imcp2-core/src/assets/connect.css	Styles the completed-login state.
Cargo.toml	Registers the crate and shared dependencies.
Cargo.lock	Locks new dependencies.

Suppressed comments (2)

crates/imcp2-local/src/login.rs:493

• The unconditional last-writer-wins commit allows an expired/replaced redeem to become current. For example, a redeem claimed just before the 10-minute deadline can remain in mcp_register_v2 while the watchdog removes it and a new flow starts; when the old call returns, it overwrites the new flow's session slot. Revalidate that this session is still the active, unexpired pending flow under the lock before committing it.

            // Fill the shared slot LAST-WRITER-WINS: II bound the grant to this
            // session's key, so even if a newer flow replaced the pending entry
            // mid-call, this successful login is real and becomes current.
            driver.inner.slot.set(body.state.clone());

crates/imcp2-local/src/server.rs:123

• auth_status is also advertised without an object-rooted outputSchema or matching structuredContent, contrary to the all-tools contract enforced in crates/imcp2-core/src/tools.rs:2521-2537. Define a structured status output and return it alongside the human-readable text so the merged local surface preserves the same MCP contract as the core tools.

    #[tool(
        description = "Report the Internet Identity sign-in state of this local server: signed in (with the session principal, access level, and time to expiry), sign-in pending (with the link to finish it), expired, or signed out.",

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 1 comment.

Suppressed comments (3)

crates/imcp2-local/src/login.rs:296

• A refresh flow can coexist with the still-live previous grant, but this grant-first ordering hides that flow: after authenticate(refresh=true), auth_status immediately reports the old account as signed in instead of reporting the pending link. An agent can therefore treat an account switch/access upgrade as complete before the browser handshake finishes. Check a non-expired pending flow before the existing grant (while still falling back to the grant when the pending flow has expired).

        if let Some(g) = &state.grant {
            if !g.expired() {
                return LoginStatus::SignedIn(g.clone());
            }
        }

crates/imcp2-local/src/server.rs:85

• authenticate omits output_schema and returns only text, so the merged tool surface breaks the repository's established MCP contract that every tool exposes an object-rooted output schema and matching structured content (crates/imcp2-core/src/tools.rs:2521-2538; all core tool attributes follow this pattern). Add a small serializable output type, declare it with output_schema, and populate structuredContent alongside the human-readable message.

    #[tool(
        description = "Sign in with Internet Identity. Returns an id.ai sign-in link for the USER to open in their browser (the server also tries to open it for them), and returns immediately — it never waits for the browser. After the user finishes, auth_status (or simply retrying the tool that needed a session) confirms the session. Call this when a tool answers that it needs an authenticated session. Repeat calls while a sign-in is pending return the same link.",
        annotations(
            title = "Sign in with Internet Identity",
            read_only_hint = false,
            destructive_hint = false,
            open_world_hint = true
        )

crates/imcp2-local/src/server.rs:129

• auth_status also lacks the object-rooted output_schema and structured result required by the established tool convention (crates/imcp2-core/src/tools.rs:2521-2538). Returning a structured state (for example, state plus optional URL/grant details) is especially important here so clients do not have to parse changing prose to determine whether login is pending or complete.

    #[tool(
        description = "Report the Internet Identity sign-in state of this local server: signed in (with the session principal, access level, and time to expiry), sign-in pending (with the link to finish it), expired, or signed out.",
        annotations(
            title = "Check sign-in status",
            read_only_hint = true,
            destructive_hint = false,
            open_world_hint = false
        )

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated no new comments.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

crates/imcp2-local/src/login.rs:207

• A grant is considered active solely from its recorded expiration. If II has already returned Unauthorized because the grant was revoked or replaced, identities.rs only returns RECONNECT_MSG and does not invalidate this Grant. Consequently, a normal authenticate call reports AlreadySignedIn (and auth_status reports signed_in) until the original expiry, instead of starting the fresh-session flow required after Unauthorized. Propagate that definitive invalidation to the local login state/slot, or otherwise make begin distinguish a revoked session so reauthentication works without requiring callers to discover refresh=true through an extra failed call.

        if !refresh {
            if let Some(g) = &state.grant {
                if !g.expired() {
                    return Ok(BeginOutcome::AlreadySignedIn(g.clone()));

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated no new comments.

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

crates/imcp2-local/src/server.rs:176

• This advertised tool description always claims that the server tries to open the browser, even when IMCP2_NO_OPEN disables that behavior. Since clients use this description to explain the flow, qualify the claim so it remains accurate in both configurations.

This issue also appears on line 203 of the same file.

        description = "Sign in with Internet Identity. Returns an id.ai sign-in link for the USER to open in their browser (the server also tries to open it for them), and returns immediately — it never waits for the browser. After the user finishes, auth_status (or simply retrying the tool that needed a session) confirms the session. Call this when a tool answers that it needs an authenticated session. Repeat calls while a sign-in is pending return the same link.",

crates/imcp2-local/src/server.rs:207

• On a repeated authenticate call, fresh is false and LoginDriver::begin does not invoke open::that, but this message still says the system was asked to open the browser whenever auto-open is enabled. Gate this text on fresh as well so the tool result accurately describes what happened.

                let opener = if self.auto_open {
                    "I also asked the system to open it in your browser. "
                } else {
                    ""
                };

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated no new comments.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

crates/imcp2-local/src/login.rs:420

• The Stage 2 acceptance criteria in docs/scoping-local-deployment.md:621-624 require an automated Chromium/Firefox run plus Safari/enterprise-policy validation before this loopback callback flow is declared working. This PR explicitly leaves that gate unchecked and the reqwest test cannot exercise browser mixed-content/PNA policy, fragment handling, or the page script. Complete the required browser compatibility gate (or align the stated stage/scope) before shipping Stage 2.

/// GET /callback — the pinned fragment-reading page (shared with the hosted
/// server), pointed at this listener's `/redeem`, with the same non-CSP
/// hardening headers the hosted server adds.
async fn callback_page() -> Response {

[Copilot]

Pull request overview

Copilot reviewed 17 out of 18 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 19 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 19 changed files in this pull request and generated no new comments.