Provide keychain-backed MCP OAuth and web/headless sign-in on Pi 1.0.2

[piclaw-bot]

Current integration target — Pi 1.0.2

Rui authorised retargeting to released Pi 1.0.2 on 5 October 2026, upstream commit cd32f7725fdbddbaecdff5b1e68491563394e0ca. This work integrates Pi with the standard MCP wrapper already shipped by Piclaw. Wrapper replacement, Native MCP parity and adapter removal are future work, not prerequisites for this integration. Keep one wrapper owner; reject unsupported Native selection without fallback. This scope decision does not weaken the shipped wrapper's credential, policy or cleanup requirements.

Preserve 0.99.1, 1.0.0 and 1.0.1 receipts as historical evidence. New 1.0.2 qualification is separate. Unreleased upstream OAuth cancellation changes after the 1.0.2 tag are excluded. Source updates, isolated tests, review and verified merges are authorised; installation, restart and real-account/provider tests still need separate approval. Pi-durable remains out of scope.

Integration checklist and completed slices

• Keep the shipped wrapper/keychain authentication path; no Native credential-store replacement is required for this integration.
• Fresh retained-wrapper keychain/generation isolation and 144 synthetic auth/callback/refresh/logout tests pass. Test-only adapter PR11 corrects dual-stack port-conflict fixtures; runtime pin unchanged and overlay explicit in checkpoint PR Record released Pi 1.0.2 retained-wrapper acceptance and remaining gates #1552. Original failures retained.
• Unsupported Native auth remains unavailable without fallback; live credential/server operations require separate permission and are not executed by this source qualification.

Previous target criteria and receipts — preserved historical record

Active target — Pi 1.0.1 (3 October 2026)

Rui authorised retargeting and implementation to exact Pi 1.0.1, upstream git head a7229ddc21810d6245105978033b7df645ecc2f7. This supersedes the earlier 1.0.0 execution target below. Preserve all 0.99.1 and 1.0.0 receipts as historical evidence; they are not 1.0.1 qualification.

Source migration, exact-package admission and isolated Bun-only synthetic qualification are authorised. Keep Adapter/Auto as the default, reject unsupported native combinations, retain failed-teardown/Apply security gates, and exclude pi-durable. Live accounts, deployment, production installation, restart and canary remain separately authorised. Do not waive unresolved native, provider or Delegate acceptance gates.

Earlier target and requirements (retained)

Checkpoint: 958ac185255840ee4f800becc5f7e3111ef9acda on feat/mcp-settings-host; stable 0.99.1 source baseline, not 1.0.0 admission.

Shared target and MCP policy

Selected target: Pi 1.0.0, gitHead a13d35a742c6ef8462812a28fbe1d8c8b7431c32. Rui explicitly authorised retargeting all remaining work on 1 October 2026: stabilise and commit current work → update relevant issues/dependencies → resume the 1.0.0 upgrade on that checkpoint. Source changes, isolated dependency installs and offline qualification are authorised; runtime admission remains an acceptance gate, not an assumed result. All new execution is Bun-only. Live accounts/MCP/provider calls, production installation, deployment/restart and experimental pi-durable activation still require separate approval. Preserve completed 0.99.1 receipts and closed issue states as historical evidence; do not relabel them as 1.0.0 results.

• Preserve the approved consolidated instance MCP settings: adapter/native selector, adapter default, exactly one active owner, codemode Auto/On/Off default Auto.
• Engine switching aborts active turns and reloads all extensions through supported public APIs, retaining chats/history; no service restart. Unsupported combinations reject with explicit reasons; no silent fallback or dropped settings.
• Ten native public-API gap diagnostics persist in the 1.0.0 assessment. Target selection is not a capability/security waiver.
• Old Harness/Pico3 exports are removed. Design the pi-durable 1.0.0 Harness successor and HC/PC crosswalk #1493 owns the pi-durable semantic/authority design and Qualify pi-durable 1.0.0 storage and Harness semantics on Bun without activation #1494 its isolated qualification. Do not add pi-durable to production merely to repair imports.

Summary

Preserve secure OAuth and headless authentication without relying on upstream plaintext auth files or non-public classes.

Parent: #1442

MCP contract: #1444

Dependencies

• Blocked by Admit exact Pi 1.0.0 and migrate current-loop removed import boundaries #1492
• Blocked by Qualify Pi 1.0.2 provider, MCP and Delegate integration deltas #1495

Acceptance Criteria

• Qualify 1.0.0 name+URL credential keys and first-claimant legacy migration with disposable secrets: same-URL servers, rename, refresh/logout isolation, issuer/state and granted scopes.

• Keep native authentication unavailable where a public keychain/headless control contract is missing; adapter functionality remains subject to the same security policy.

• Obtain a public credential-store contract usable with Piclaw keychain and cross-process refresh locks; no private import/type cast or mcp-auth.json token persistence.

• Implement user/chat/server-bound auth-start/complete with expiring single-use state, PKCE, validated callback URL, cancellation and replay protection.

• Preserve token refresh/rotation, logout/revocation and concurrent-process isolation; remove credentials only for the authorised principal/server.

• No browser launch or sign-in flow begins from a model call without user action; explicit bearer failures cannot fall back to OAuth.

• Preserve headless/web UX despite upstream login rejecting ctx.hasUI=false; openUrl alone is not a solution.

• Secrets never enter messages/logs/config/cache/argv; every unsupported flow is a blocking diagnostic, not fallback.

Implementation Notes

createMcpExtension.credentials names non-root-exported McpOAuthCredentialStore with private members; the default persists mcp-auth.json. Plan a public upstream seam. Do not run authentication against live servers during implementation fixtures without separate approval.

Estimate: M · Risk: high · Source file: runtime/src/secure/mcp-keychain.ts

Source anchors: Piclaw baseline, upstream release, MCP guide, public extension options.

Test Plan

• MCP-03/10 fake OAuth server: bad state, replay, expiry, cancellation, wrong chat/server, loopback validation and refresh contention.
• Secret sentinel scan and logout/session replacement tests.

Definition of Done

• Acceptance criteria satisfied with exact-version evidence
• Required tests/typechecks pass (documentation-only changes use structural/link review)
• Docs and migration guidance updated
• Operational impact and rollback assessed
• Update history and parent/dependency status reflect evidence

Pre-retarget issue body — historical record, not current target authority

Summary

Preserve secure OAuth and headless authentication without relying on upstream plaintext auth files or non-public classes.

Planning record only. This issue does not authorise package installation, live credentials/MCP/provider calls, production activation, deployment or restart. Target exactly Earendil 0.99.1 (gitHead d86654abb8862e201933517d6f1fce9f88dd117f), starting from 0.87.1 / Delegate 0.2.13. A later upstream fix needs an explicit target decision and its own receipt. Preserve completed 0.87.1 history.

Parent: #1442

MCP contract: #1444

Dependencies

• Blocked by Resolve public-API blockers for the 0.99.1 upstream MCP contract #1444
• Blocked by Translate MCP config and credentials without weakening quarantine #1446

Acceptance Criteria

• Obtain a public credential-store contract usable with Piclaw keychain and cross-process refresh locks; no private import/type cast or mcp-auth.json token persistence.
• Implement user/chat/server-bound auth-start/complete with expiring single-use state, PKCE, validated callback URL, cancellation and replay protection.
• Preserve token refresh/rotation, logout/revocation and concurrent-process isolation; remove credentials only for the authorised principal/server.
• No browser launch or sign-in flow begins from a model call without user action; explicit bearer failures cannot fall back to OAuth.
• Preserve headless/web UX despite upstream login rejecting ctx.hasUI=false; openUrl alone is not a solution.
• Secrets never enter messages/logs/config/cache/argv; every unsupported flow is a blocking diagnostic, not fallback.

Implementation Notes

createMcpExtension.credentials names non-root-exported McpOAuthCredentialStore with private members; the default persists mcp-auth.json. Plan a public upstream seam. Do not run authentication against live servers during implementation fixtures without separate approval.

Estimate: M · Risk: high · Source file: runtime/src/secure/mcp-keychain.ts

Source anchors: Piclaw baseline, upstream release, MCP guide, public extension options.

Test Plan

• MCP-03/10 fake OAuth server: bad state, replay, expiry, cancellation, wrong chat/server, loopback validation and refresh contention.
• Secret sentinel scan and logout/session replacement tests.

Definition of Done

• Acceptance criteria satisfied with exact-version evidence
• Required tests/typechecks pass (documentation-only changes use structural/link review)
• Docs and migration guidance updated
• Operational impact and rollback assessed
• Update history and parent/dependency status reflect evidence

[piclaw-bot]

Exact installed public surface audit: native McpExtensionOptions.credentials is nominal McpOAuthCredentialStore with private members, not root-exported; default persists mcp-auth.json. Retained adapter41f10ee exports ./oauth token get/inspect/update helpers; AuthStorageOptions exposes only legacy baseDir, and AuthSecretStore is module-private. Neither offers Piclaw host keychain + cross-process refresh-store injection. No private import/cast, global monkeypatch or second client will be introduced. Native OAuth cutover remains blocked pending explicit target/scope decision or admitted public API. No live credentials read or auth calls made.