@wootsup/mcp 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,91 +1,156 @@
 # Changelog
 
-All notable changes to `@wootsup/mcp` will be documented here.
+All notable changes to this project are documented in this file.
 
-The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
-this project uses [Semantic Versioning](https://semver.org/).
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project follows [Semantic Versioning](https://semver.org/).
 
-## [0.1.0-rc.1] - 2026-05-18 (unreleased)
+## [0.3.0] `Latest` - 2026-06-08
 
-First public release candidate. Ships the full 74-tool MCP surface
-plus a complete setup story (`npx setup` wizard + Claude Desktop DXT
-bundle). Built across Phases 0–10 of the
-`apimapper-mcp-implementation-plan` (vault).
+### Added
+
+- **Library-first workflow: creating a custom connection for an API a curated library template already covers now returns a 409 that steers you to activate the template instead. Override with acknowledge_no_library:true for genuinely uncovered endpoints.**
+- **New tool apimapper_yootheme_binding_for_flow — inspect the exact YOOtheme binding a published flow exposes.**
+- **New tool apimapper_connection_recover — repair stuck or corrupted connections.**
+- **JMESPath date primitives (date_weekday, date_iso_to_time, date_iso_to_date, time_in_window) plus a depth-overflow guard for deeply nested expressions.**
+- **Connection reads now explain why they returned 0 items instead of failing silently.**
+- **MCP keys can be minted from a permission level (read / write / admin) with additive scopes.**
+- **Multi-site routing: target a specific site via a sites file.**
+- **uninstall CLI command (reverse of setup).**
+
+### Changed
+
+- **library_activate is resource-aware: it never silently mutates a healthy existing connection — reuse, heal, or fork is explicit (force_new + reused/mutated/healed semantics).**
+- **Recompile/publish auto-fix is on by default.**
+
+### Fixed
+
+- **connection_update accepts the extra_fields alias so template fields are no longer dropped.**
+- **Source item-shape falls back to the template-merged shape instead of rendering empty.**
+- **The API response cache is dropped on connection update/delete/re-auth, so stale data no longer lingers.**
+- **getFlow reports compile state and node types so YOOtheme bindings don't go stale.**
+- **Full WordPress ↔ Joomla parity across library, license, connection and cache paths.**
+- **OAuth refresh-token storage and re-consent hardening.**
+
+### Security
+
+- **Bearer-scope gate on all destructive MCP tasks (delete*, revokeMcpKey, deactivateLibraryConnection): a read- or write-scoped token can no longer delete connections or revoke keys.**
+
+## [0.1.0] - 2026-05-28
 
 ### Added
 
-- **Stripe-style HMAC-SHA256 auth.** `amk_live_…` / `amk_test_…`
-  token format, server-side signing key, identity-probe handshake
-  with site-title confirmation in the setup wizard.
-- **WordPress plugin foundation.** REST routes under
-  `/wp-json/api-mapper/v1/mcp/*`, key generation UI under
-  *API Mapper → Connections → MCP Access*, key list + rotate +
-  revoke endpoints.
-- **Joomla plugin foundation.** Mirror surface via `com_ajax`
-  envelope; same key lifecycle as WordPress. Joomla envelope unwrap
-  is handled by the client layer transparently.
-- **5 admin UI components** for MCP key management: KeyList,
-  CreateKey, KeyDetail, RotateKey, RevokeKey — shared between
-  WordPress and Joomla via the platform abstraction.
-- **Platform abstraction.** Each MCP tool routes through a single
-  platform-router that detects WordPress vs. Joomla from the site
-  URL + `APIMAPPER_PLATFORM` env, then dispatches to the correct
-  REST shape.
-- **Keychain + Profiles.** OS keychain integration via
-  `@napi-rs/keyring` (macOS Keychain, Windows Credential Manager,
-  Linux libsecret) with named profile support (`APIMAPPER_PROFILE`)
-  and a `0600` file fallback when no keychain is available.
-- **Setup CLI (`apimapper-mcp` binary).** Interactive
-  `@clack/prompts` wizard with subcommands: `setup` (default),
-  `install-skill`, `help`. Auto-detects Claude Desktop, Claude Code,
-  Cursor, VS Code, Cline, Codex. Idempotent config writers; rollback
-  on probe failure.
-- **Skills bundling.** `skills/apimapper/SKILL.md` plus four reference
-  docs (`oauth.md`, `joomla.md`, `yootheme.md`, `troubleshooting.md`)
-  shipped with every install. Resources surfaced via
-  `apimapper_get_skill` tool.
-- **Composite tools.** `apimapper_flow_setup_with_sources` (create
-  flow + add sources + compile + publish), `apimapper_diagnose`
-  (pre-flight: health + license + platform parity + connection probe
-  + recent flow status). Reduces multi-turn back-and-forth for the
-  most common workflows.
-- **Multi-transport.** stdio transport (default, local install) plus
-  HTTP transport with OAuth 2.0 (PKCE-required, S256) for remote
-  consumption. Bearer tokens are site-bound (rejected on origin
-  mismatch).
-- **DXT bundle.** `apimapper-mcp.dxt` packaged via `build-dxt.js`
-  for one-click Claude Desktop install. User-config keys
-  (`APIMAPPER_TOKEN`, `APIMAPPER_SITE_URL`, `APIMAPPER_PLATFORM`)
-  bridged into the runtime via env shimming. Build verified with a
-  grep-gate that ensures every declared user-config key has a
-  runtime consumer.
-- **74 MCP tools** spanning: connections, credentials, flows, graph
-  preview/validate, local sources, schema profile, library catalog,
-  cache, settings, license, releases, brandfetch, feedback,
-  workflows, plus health / onboarding / diagnose / inspect-token /
-  use-profile.
-
-### Engineering
-
-- **Test suite.** 243 tests across 27 files
-  (vitest + `tsx watch` dev). Includes a stdio-transport spawn
-  smoke-test, HTTP+Bearer transport tests, build-dxt manifest
-  invariants, and unit coverage of every register file.
-- **CI matrix.** ubuntu-latest, macos-latest, windows-latest × Node
-  22.x, gated by path filter and concurrency-cancel per ref
-  (`.github/workflows/apimapper-mcp-ci.yml`).
-- **Publish workflow.** Tag-triggered (`apimapper-mcp-v*`),
-  verifies tag-version vs. `package.json#version` before publishing,
-  publishes with `--provenance`, uploads DXT bundle to GitHub
-  Release (`.github/workflows/apimapper-mcp-publish.yml`).
-
-### Known issues
-
-- `@getimo/mcp-toolkit@1.0.0` declares a `workspace:*` peer-dep on
-  `@pipeline-studio/screenshot-capture` that is unresolvable outside
-  the source monorepo. Install with `npm install --legacy-peer-deps`
-  (or `npm ci --legacy-peer-deps` in CI). Tracked upstream; will be
-  fixed in `@getimo/mcp-toolkit@1.1.0`. Does not affect runtime —
-  `npx @wootsup/mcp` and the DXT bundle work without intervention.
-
-[0.1.0-rc.1]: https://github.com/wootsup/api-mapper/releases/tag/apimapper-mcp-v0.1.0-rc.1
+- **First public stable release. CLI installer (`npx -y @wootsup/mcp setup`), 17 MCP tools via the apimapper_advanced gateway (77 capabilities behind it), Stripe-style HMAC-SHA256 auth, Claude Desktop DXT bundle, multi-AI-client wizard (Claude Desktop, Claude Code, Cursor, VS Code, Cline, Codex CLI), bundled skills with topic-scoped reference docs.** `npm`
+
+## [0.1.0-rc.13-w3.1] - 2026-05-20
+
+### Fixed
+
+- **Pre-release iteration during initial public testing. Wave-3 hotfix on top of rc.13.** `npm`
+
+## [0.1.0-rc.13-w3.0] - 2026-05-20
+
+### Fixed
+
+- **Pre-release iteration during initial public testing. Wave-3 baseline iteration on rc.13.** `npm`
+
+## [0.1.0-rc.12] - 2026-05-19
+
+### Fixed
+
+- **Pre-release iteration during initial public testing.** `npm`
+
+## [0.1.0-rc.11] - 2026-05-19
+
+### Fixed
+
+- **Pre-release iteration during initial public testing.** `npm`
+
+## [0.1.0-rc.10] - 2026-05-19
+
+### Fixed
+
+- **Pre-release iteration during initial public testing.** `npm`
+
+## [0.1.0-rc.9] - 2026-05-19
+
+### Fixed
+
+- **Pre-release iteration during initial public testing.** `npm`
+
+## [0.1.0-rc.8] - 2026-05-19
+
+### Fixed
+
+- **Pre-release iteration during initial public testing.** `npm`
+
+## [0.1.0-rc.7] - 2026-05-19
+
+### Fixed
+
+- **Pre-release iteration during initial public testing.** `npm`
+
+## [0.1.0-rc.6] - 2026-05-19
+
+### Fixed
+
+- **Pre-release iteration during initial public testing.** `npm`
+
+## [0.1.0-rc.5] - 2026-05-18
+
+### Fixed
+
+- **Pre-release iteration during initial public testing.** `npm`
+
+## [0.1.0-rc.4] - 2026-05-18
+
+### Fixed
+
+- **Pre-release iteration during initial public testing.** `npm`
+
+## [0.1.0-rc.3] - 2026-05-18
+
+### Fixed
+
+- **Pre-release iteration during initial public testing.** `npm`
+
+## [0.1.0-rc.2] - 2026-05-18
+
+### Fixed
+
+- **Pre-release iteration during initial public testing.** `npm`
+
+## [0.1.0-rc.1] - 2026-05-18
+
+### Added
+
+- **First public release candidate. Ships the full 74-tool MCP surface plus a complete setup story (npx setup wizard plus Claude Desktop DXT bundle). Stripe-style HMAC-SHA256 auth, WordPress and Joomla plugin foundations, OS keychain integration via @napi-rs/keyring, multi-AI-client wizard (Claude Desktop, Claude Code, Cursor, VS Code, Cline, Codex), bundled skills, stdio plus HTTP+OAuth2 (PKCE) transports.** `npm`
+
+---
+
+## Version Types
+
+- **Added** - New features
+- **Changed** - Changes to existing features
+- **Deprecated** - Features to be removed in future versions
+- **Removed** - Removed features
+- **Fixed** - Bug fixes
+- **Security** - Security updates
+
+[0.3.0]: https://github.com/wootsup/api-mapper/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/wootsup/api-mapper/compare/v0.1.0-rc.13-w3.1...v0.1.0
+[0.1.0-rc.13-w3.1]: https://github.com/wootsup/api-mapper/compare/v0.1.0-rc.13-w3.0...v0.1.0-rc.13-w3.1
+[0.1.0-rc.13-w3.0]: https://github.com/wootsup/api-mapper/compare/v0.1.0-rc.12...v0.1.0-rc.13-w3.0
+[0.1.0-rc.12]: https://github.com/wootsup/api-mapper/compare/v0.1.0-rc.11...v0.1.0-rc.12
+[0.1.0-rc.11]: https://github.com/wootsup/api-mapper/compare/v0.1.0-rc.10...v0.1.0-rc.11
+[0.1.0-rc.10]: https://github.com/wootsup/api-mapper/compare/v0.1.0-rc.9...v0.1.0-rc.10
+[0.1.0-rc.9]: https://github.com/wootsup/api-mapper/compare/v0.1.0-rc.8...v0.1.0-rc.9
+[0.1.0-rc.8]: https://github.com/wootsup/api-mapper/compare/v0.1.0-rc.7...v0.1.0-rc.8
+[0.1.0-rc.7]: https://github.com/wootsup/api-mapper/compare/v0.1.0-rc.6...v0.1.0-rc.7
+[0.1.0-rc.6]: https://github.com/wootsup/api-mapper/compare/v0.1.0-rc.5...v0.1.0-rc.6
+[0.1.0-rc.5]: https://github.com/wootsup/api-mapper/compare/v0.1.0-rc.4...v0.1.0-rc.5
+[0.1.0-rc.4]: https://github.com/wootsup/api-mapper/compare/v0.1.0-rc.3...v0.1.0-rc.4
+[0.1.0-rc.3]: https://github.com/wootsup/api-mapper/compare/v0.1.0-rc.2...v0.1.0-rc.3
+[0.1.0-rc.2]: https://github.com/wootsup/api-mapper/compare/v0.1.0-rc.1...v0.1.0-rc.2
+[0.1.0-rc.1]: https://github.com/wootsup/api-mapper/releases/tag/v0.1.0-rc.1
+

package/README.md

@@ -7,7 +7,6 @@ flows, manage OAuth credentials, and publish sources without leaving the
 chat.
 
 [![npm version](https://img.shields.io/npm/v/@wootsup/mcp.svg)](https://www.npmjs.com/package/@wootsup/mcp)
-[![CI](https://github.com/wootsup/api-mapper/actions/workflows/apimapper-mcp-ci.yml/badge.svg)](https://github.com/wootsup/api-mapper/actions/workflows/apimapper-mcp-ci.yml)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
 ---
@@ -36,8 +35,8 @@ subcommands.
 
 ### Option B — Claude Desktop (DXT bundle)
 
-1. Download `apimapper-mcp.dxt` from the latest
-   [GitHub Release](https://github.com/wootsup/api-mapper/releases?q=apimapper-mcp).
+1. Download `apimapper-mcp.dxt` — see the
+   [installation guide](https://wootsup.com/docs/mcp/api-mapper/installation).
 2. Drag it onto the Claude Desktop window (or **Settings → Developer →
    Install from file**).
 3. Enter your site URL, MCP key, and platform when prompted.
@@ -65,13 +64,16 @@ Verify in your AI client:
 
 ```text
 You:  apimapper_health
-LLM:  ✅ status: ok, platform: wordpress, version: 2.0.7
+LLM:  ✅ status: ok, platform: wordpress, version: 2.0.13
 ```
 
 ## Common tools
 
-A small set of high-leverage tools — the full 74-tool surface is
-[documented in detail in the bundled skill](https://github.com/wootsup/api-mapper/blob/main/packages/apimapper-mcp/skills/apimapper/SKILL.md).
+A small set of high-leverage tools. The full surface is 79 tools: 19 are
+first-class in `tools/list`, and the other 60 route through the
+`apimapper_advanced` gateway (so the listed surface stays under each client's
+tool cap). Everything is
+[documented in detail in the tools reference](https://wootsup.com/docs/mcp/api-mapper/tools).
 
 | Tool | What it does |
 |------|--------------|
@@ -84,10 +86,16 @@ A small set of high-leverage tools — the full 74-tool surface is
 | `apimapper_graph_preview` | Preview a flow's output without saving. |
 | `apimapper_library_catalog` | Browse pre-built connection templates. |
 | `apimapper_get_skill` | Fetch the bundled skill text on demand. |
+| `apimapper_advanced` | Gateway to the 60 advanced tools. Call `{ tool }` for a target's schema, or `{ tool, arguments }` to run it. |
 
-See [`skills/apimapper/SKILL.md`](https://github.com/wootsup/api-mapper/blob/main/packages/apimapper-mcp/skills/apimapper/SKILL.md) for the
-canonical workflow guide, and
-[`skills/apimapper/reference/`](https://github.com/wootsup/api-mapper/tree/main/packages/apimapper-mcp/skills/apimapper/reference) for OAuth,
+The 60 advanced tools (the full connection / credential / flow / library /
+license / schema surface) are not listed individually in `tools/list` — they
+route through `apimapper_advanced` so the first-class surface stays under each
+client's tool cap.
+
+See the [tools reference](https://wootsup.com/docs/mcp/api-mapper/tools) for the
+canonical workflow guide, and the
+[API Mapper MCP docs](https://wootsup.com/docs/mcp/api-mapper/) for OAuth,
 Joomla, YOOtheme, and troubleshooting deep-dives.
 
 ## Multi-platform: WordPress and Joomla
@@ -107,15 +115,15 @@ Supported AI clients (auto-detected by the setup wizard):
 - **Cursor** — `~/.cursor/mcp.json` (or project-local `.cursor/mcp.json`)
 - **VS Code** — workspace `.vscode/settings.json` `mcp.servers`
 - **Cline** — VS Code extension settings
-- **Codex** — `~/.config/codex/mcp.json`
+- **Codex** — `~/.codex/config.toml`
 - **ChatGPT Desktop** — when MCP support ships
 
-Both transports are supported: **stdio** (default, local install) and
-**HTTP + OAuth 2.0** (remote use, see [`docs/architecture.md`](https://github.com/wootsup/api-mapper/blob/main/packages/apimapper-mcp/docs/architecture.md)).
+The server ships **stdio-only** (local install via npx or the Claude
+Desktop DXT bundle).
 
 ## Troubleshooting
 
-See [`skills/apimapper/reference/troubleshooting.md`](https://github.com/wootsup/api-mapper/blob/main/packages/apimapper-mcp/skills/apimapper/reference/troubleshooting.md).
+See the [troubleshooting guide](https://wootsup.com/docs/mcp/api-mapper/troubleshooting).
 Common cases:
 
 - `403 invalid_token` → token expired or wrong site URL. Re-run setup.
@@ -123,14 +131,10 @@ Common cases:
 - Joomla `0` envelope → SEF/htaccess intercepting `com_ajax`; check
   the reference doc.
 
-## Contributing
+## Feedback and support
 
-PRs welcome. Source lives at
-[github.com/wootsup/api-mapper](https://github.com/wootsup/api-mapper)
-in `packages/apimapper-mcp/`. Run `npm test --workspace=@wootsup/mcp`
-before opening a PR; the cross-platform CI matrix
-([`apimapper-mcp-ci.yml`](../../.github/workflows/apimapper-mcp-ci.yml))
-re-runs on ubuntu, macOS, and windows.
+Found a bug or have a feature request? Reach us at
+[wootsup.com/contact](https://wootsup.com/contact/).
 
 For the security disclosure process, see [`SECURITY.md`](./SECURITY.md).
 
@@ -141,10 +145,10 @@ For the security disclosure process, see [`SECURITY.md`](./SECURITY.md).
 ## Links
 
 - **Homepage:** <https://wootsup.com>
-- **Plugin (WordPress + Joomla):** <https://wootsup.com> · download from `/downloads`
-- **Docs:** <https://wootsup.com/docs/mcp/>
-- **Issues:** <https://github.com/wootsup/api-mapper/issues>
-- **Architecture:** [`docs/architecture.md`](https://github.com/wootsup/api-mapper/blob/main/packages/apimapper-mcp/docs/architecture.md)
-- **Security model:** [`docs/security.md`](https://github.com/wootsup/api-mapper/blob/main/packages/apimapper-mcp/docs/security.md)
-- **Tools reference:** [`docs/tools.md`](https://github.com/wootsup/api-mapper/blob/main/packages/apimapper-mcp/docs/tools.md)
-- **Changelog:** [`CHANGELOG.md`](https://github.com/wootsup/api-mapper/blob/main/packages/apimapper-mcp/CHANGELOG.md)
+- **Plugin (WordPress + Joomla):** download from <https://wootsup.com/downloads>
+- **Docs:** <https://wootsup.com/docs/mcp/api-mapper/>
+- **Installation:** <https://wootsup.com/docs/mcp/api-mapper/installation>
+- **Tools reference:** <https://wootsup.com/docs/mcp/api-mapper/tools>
+- **Troubleshooting:** <https://wootsup.com/docs/mcp/api-mapper/troubleshooting>
+- **Support:** <https://wootsup.com/contact/>
+- **Changelog:** [`CHANGELOG.md`](./CHANGELOG.md)

package/SECURITY.md

@@ -91,12 +91,16 @@ tool-list (eliminates one class of confused-deputy risk).
 | `GET /mcp/keys` (list) | ❌ key IDs + scopes + last-used only. **Never** the token string. |
 | `POST /mcp/keys` (create) | ✅ **Only on creation.** Subsequent reads cannot retrieve it. |
 | `apimapper_credential_*` | ❌ Stored OAuth/Bearer creds are returned with values redacted (`***`). |
+| `apimapper_connection_get` / `apimapper_connection_data` | ❌ Read through the sanitizer (`sanitize:true`). Inline `Authorization` / `X-API-Key` values stored in a connection's `headers`/`params` (`{name,value}` pairs) are redacted. |
 | `apimapper_inspect_token` | Returns the **decoded payload** (key_id, scopes, env) but **not** the signature. |
 | `apimapper_settings_get` | Always strips `signing_key`, OAuth client secrets, and Brandfetch keys. |
 
 Server-side, the `CredentialSanitizer` runs on every response that
 could possibly contain a credential value — see
 [`src/modules/apimapper/credential-sanitizer.ts`](./src/modules/apimapper/credential-sanitizer.ts).
+The TS sanitizer redacts both secret-named keys (`auth_data`, `api_key`, …)
+and the `value` of a `{name,value}` header/param pair whose `name` is a known
+auth header (`Authorization`, `X-API-Key`, `Cookie`, vendor variants, …).
 Unit tests pin the redaction surface.
 
 ### Token rotation
@@ -127,13 +131,15 @@ file is plain JSON containing the token string — readable by the user
 account only. If you operate in a hostile multi-user environment,
 **use the OS keychain path** (the default on macOS and Windows).
 
-### OAuth 2.0 (HTTP transport)
+### Transport: stdio only
 
-When `@wootsup/mcp` runs in HTTP mode (`server-http.ts`), it acts as
-both an MCP server and an OAuth 2.0 authorization server with **PKCE
-required** (RFC 7636 S256). No implicit flow, no `code` grant without
-PKCE. Bearer tokens are bound to the issuing site URL and rejected if
-the `Origin` header differs.
+`@wootsup/mcp` ships **stdio-only**. The published npm package and the DXT
+bundle both run over **stdio** (`index.ts` → `transports/stdio.ts`) — the
+MCP server is spawned by the AI client and speaks JSON-RPC over
+stdin/stdout. There is **no HTTP, SSE, or remote transport**, and the
+server does not open a network listener. All of the authentication
+guarantees described above (HMAC tokens, identity probe, scope filtering,
+no-secret-leak) apply to that stdio path.
 
 ## Threat model summary
 
@@ -146,6 +152,9 @@ the `Origin` header differs.
 | Phishing setup link | Identity probe + site-title confirmation in wizard. |
 | Confused-deputy / over-privileged LLM | Scope filter excludes destructive tools from token-restricted lists. |
 | Local-fs token theft (no keychain) | `0600` perms on profile file; keychain default on macOS/Windows. |
+| Network exposure of the server | None — the server is stdio-only and opens no network listener. |
+
+> The MCP server ships stdio-only; there is no HTTP/remote transport.
 
 See [`docs/security.md`](./docs/security.md) for the long-form threat
 model.

package/dist/auth/keychain.d.ts

@@ -10,13 +10,32 @@ export declare class SystemKeychain implements Keychain {
     get(ref: string): Promise<string | null>;
     delete(ref: string): Promise<void>;
 }
+/** True when the value is a production API Mapper token (`amk_live_…`). */
+export declare function isLiveToken(value: string): boolean;
+/**
+ * Thrown when a live (`amk_live_…`) token would be written to the encrypted-file
+ * fallback without the explicit opt-in. The message names the safer path.
+ */
+export declare class LiveTokenFileFallbackError extends Error {
+    constructor();
+}
+export interface EncryptedFileKeychainOptions {
+    /**
+     * When true, allow persisting a production (`amk_live_…`) token to the file
+     * fallback. Default false — live tokens are refused (see
+     * LiveTokenFileFallbackError). Set this only on hosts where the OS keychain is
+     * unavailable AND you accept the weaker at-rest protection.
+     */
+    allowLiveTokens?: boolean;
+}
 export declare class EncryptedFileKeychain implements Keychain {
     private readonly dir;
     private readonly vaultPath;
     private readonly saltPath;
+    private readonly allowLiveTokens;
     private cachedKey?;
     private writeChain;
-    constructor(configDir: string);
+    constructor(configDir: string, opts?: EncryptedFileKeychainOptions);
     private deriveKey;
     private readVault;
     private writeVault;
@@ -43,5 +62,12 @@ export interface CreateKeychainOptions {
      * clean.
      */
     silent?: boolean;
+    /**
+     * S-MED-2: propagated to the EncryptedFileKeychain fallback. When false
+     * (default) the file fallback refuses production (`amk_live_…`) tokens. Set
+     * true only on hosts without an OS keychain where the weaker at-rest
+     * protection is accepted.
+     */
+    allowLiveTokensInFileFallback?: boolean;
 }
 export declare function createKeychain(opts: CreateKeychainOptions): Promise<Keychain>;

package/dist/auth/keychain.js

@@ -19,6 +19,14 @@
 // through casual file inspection, and (b) is no worse than the alternative
 // (raw plaintext) for environments that already failed the system-keychain
 // probe.
+//
+// S-MED-2 (Wave-B 2026-06-03): because the file fallback's key is derivable
+// from repo-public material + a co-located salt, the EncryptedFileKeychain
+// REFUSES to persist a production (`amk_live_…`) token by default (throws
+// LiveTokenFileFallbackError). Live secrets belong in the OS keychain; dev/test
+// tokens may still use the fallback. Pass { allowLiveTokens: true } (or
+// createKeychain({ allowLiveTokensInFileFallback: true })) to override on a host
+// with no OS keychain.
 import { randomBytes, pbkdf2Sync, createCipheriv, createDecipheriv, } from "node:crypto";
 import { mkdirSync, existsSync, readFileSync, writeFileSync, } from "node:fs";
 import { createRequire } from "node:module";
@@ -115,18 +123,48 @@ const PBKDF2_DIGEST = "sha256";
 // derived key is unique to this product even if two unrelated tools share the
 // same salt file path by accident.
 const KDF_PHRASE = "apimapper-mcp/v1/keychain";
+// S-MED-2 (Wave-B 2026-06-03): the file fallback's AES key is derived from a
+// repo-public KDF phrase + a `.salt` co-located with the vault. An attacker with
+// read access to both files can recompute the key and decrypt offline — this is
+// obfuscation, not encryption, against a local attacker. We therefore REFUSE to
+// persist a production (`amk_live_…`) token to the file fallback by default: live
+// secrets must live in the OS keychain. Dev/test tokens (`amk_test_…`, app
+// passwords) may still use the fallback. Callers that genuinely need the file
+// fallback for a live token (locked-down host with no OS keychain) must opt in
+// explicitly via { allowLiveTokens: true }.
+const LIVE_TOKEN_PREFIX = "amk_live_";
+/** True when the value is a production API Mapper token (`amk_live_…`). */
+export function isLiveToken(value) {
+    return value.startsWith(LIVE_TOKEN_PREFIX);
+}
+/**
+ * Thrown when a live (`amk_live_…`) token would be written to the encrypted-file
+ * fallback without the explicit opt-in. The message names the safer path.
+ */
+export class LiveTokenFileFallbackError extends Error {
+    constructor() {
+        super("Refusing to persist a production (amk_live_…) token to the encrypted-file " +
+            "keychain fallback: its AES key is derivable from repo-public material + a " +
+            "co-located salt. Use the OS keychain for live tokens, or pass " +
+            "{ allowLiveTokens: true } to override on a host where no OS keychain is " +
+            "available.");
+        this.name = "LiveTokenFileFallbackError";
+    }
+}
 export class EncryptedFileKeychain {
     dir;
     vaultPath;
     saltPath;
+    allowLiveTokens;
     cachedKey;
     // In-memory mutex to serialise writes — vitest hits concurrent set() in the
     // "concurrent writes" test and we don't want a torn JSON file.
     writeChain = Promise.resolve();
-    constructor(configDir) {
+    constructor(configDir, opts = {}) {
         this.dir = configDir;
         this.vaultPath = join(configDir, "keychain.enc.json");
         this.saltPath = join(configDir, ".salt");
+        this.allowLiveTokens = opts.allowLiveTokens ?? false;
         if (!existsSync(this.dir)) {
             mkdirSync(this.dir, { recursive: true });
         }
@@ -210,6 +248,12 @@ export class EncryptedFileKeychain {
         }
     }
     set(ref, value) {
+        // S-MED-2: refuse production tokens unless explicitly opted in. Reject
+        // BEFORE touching the write chain so nothing is persisted and the salt/vault
+        // files are not created as a side effect.
+        if (!this.allowLiveTokens && isLiveToken(value)) {
+            return Promise.reject(new LiveTokenFileFallbackError());
+        }
         // Serialise on the per-instance write chain to avoid torn JSON. Callers
         // can still hit us concurrently — each set() waits for the prior one.
         const next = this.writeChain.then(() => {
@@ -256,7 +300,9 @@ export async function createKeychain(opts) {
             console.warn(`[apimapper-mcp] System keychain unavailable (${msg}); ` +
                 `falling back to AES-GCM-encrypted file at ${opts.configDir}/keychain.enc.json`);
         }
-        return new EncryptedFileKeychain(opts.configDir);
+        return new EncryptedFileKeychain(opts.configDir, {
+            allowLiveTokens: opts.allowLiveTokensInFileFallback ?? false,
+        });
     }
 }
 //# sourceMappingURL=keychain.js.map

package/dist/auth/keychain.js.map

@@ -1 +1 @@
-{"version":3,"file":"keychain.js","sourceRoot":"","sources":["../../src/auth/keychain.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"keychain.js","sourceRoot":"","sources":["../../src/auth/keychain.ts"],"names":[],"mappings":"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"}

package/dist/cli-hint.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Decide whether the bare/unknown-invocation interactive hint should be shown.
+ *
+ * Returns true ONLY when the invocation is interactive (a TTY on stdin) AND
+ * the given subcommand is not a recognised CLI subcommand (either absent —
+ * bare `npx @wootsup/mcp` — or an unknown typo).
+ *
+ * When stdin is NOT a TTY (piped, i.e. a real MCP client) this ALWAYS returns
+ * false so the server-boot path is never disturbed.
+ *
+ * @param subcommand The first positional CLI arg (`process.argv[2]`), or undefined.
+ * @param knownSubcommands The set of recognised CLI subcommands.
+ * @param isTTY Whether stdin is an interactive terminal (`process.stdin.isTTY`).
+ */
+export declare function shouldShowInteractiveHint(subcommand: string | undefined, knownSubcommands: ReadonlySet<string>, isTTY: boolean): boolean;
+/**
+ * Build the human-facing hint message printed to stderr in interactive mode.
+ *
+ * When `subcommand` is a non-empty unknown token, the message is prefixed with
+ * an "unknown command" line so a typo is called out explicitly.
+ */
+export declare function buildInteractiveHint(subcommand: string | undefined): string;