modelcontextprotocol/inspector
Watch
1
0
Fork
You've already forked inspector
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

fix: load @napi-rs/keyring lazily so an unsupported platform degrades instead of crashing (#1905) (#1948)

Browse source 
* fix: load @napi-rs/keyring lazily so an unsupported platform degrades

`@napi-rs/keyring` ships one prebuilt binary per platform triple and
throws on import where it has none. On Android / Termux there is no
`@napi-rs/keyring-android-arm64`, so the static top-level import in
`core/auth/node/secret-store.ts` threw during module evaluation and the
Inspector exited at startup with "Cannot find native binding" — before
any of the keychain-unavailable handling in that same file could run.

Replaces the static import with a cached dynamic one. The outcome is
cached, not just the module, so a box without a binary doesn't
re-attempt (and re-throw) resolution on every secret operation —
`expectedSecretFields` means that would otherwise be once per server per
`GET /api/servers` — and so `set` can name the underlying cause in its
`KeychainUnavailableError`.

An unloadable package now folds into the same degradation contract as an
unreachable keychain: `get` returns null, `delete` and
`deleteAllForServer` no-op, and `set` throws `KeychainUnavailableError`
(not double-wrapped — the load failure is already typed by the time the
catch sees it). The class doc comment now enumerates all three ways
"unavailable" can arrive, since each escaped the contract at some point.

The shared `vi.mock` stub can't express this — it models a keyring that
loads — so the new tests build on `vi.resetModules()` + `vi.doMock` with
a throwing factory and re-import the module, covering the load failure,
each method under it, and the load-once caching.

Verified the dynamic import survives bundling in all three clients
(cli, tui, and the web runner) rather than being inlined back to a
static one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XAR2Nr9kXbrywFNUVoTe9F

* fix: steer a missing native binding to a reinstall hint

`KeychainUnavailableError` gave the Linux libsecret / gnome-keyring
advice for every cause, including the one where the keychain is fine and
the @napi-rs/keyring platform package is what's missing — an unsupported
triple (#1905) or npm's optional-deps bug dropping it on a supported one
(npm/cli#4828, the Windows report on #1852). Detect the loader's "Cannot
find native binding" phrasing and point those users at a reinstall /
npx-cache clear instead.

Ported from the superseded #1943, which fixed this alongside the same
lazy-load change.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HDdo1rNRVQnVRRdsqSrvG3

* fix: name a bad keyring namespace instead of "is not a constructor"

The lazy import accepted whatever the resolution produced. The named
exports arrive through CJS interop, so a resolution that stopped
yielding them — a default-only export upstream, a bundler changing
interop, a platform where named-export detection fails — would hand us
`undefined`, and `new mod.AsyncEntry(...)` would throw a TypeError
inside the very try that implements graceful degradation.

Shape-check the resolved module and treat a bad shape as unavailable.

Scope, because it is narrower than it first appears: this does NOT
prevent a bad shape from emptying the secret list. `get` returns null
either way — that is its read-tolerance contract, and the TypeError
lands in the same catch a dead keychain does. What changes is the
diagnosis. Without the check the only signal is `set` reporting
"keyring.mod.AsyncEntry is not a constructor", which reads like an
Inspector bug; with it, `set` names the real problem once, at the load
boundary, in the same actionable 503 as every other unavailability.
Catching the silent-empty-list case itself would need a round-trip
against the unmocked package, which nothing in the suite does today.

The member access sits inside the try because reading a missing export
is not always a harmless undefined — a Proxy-backed namespace can throw,
as vitest's module mocks do — and letting that escape would reject the
cached promise, which is otherwise guaranteed to always resolve.

Of the four new tests only the cause-message one fails without the
guard; the rest pin the surrounding contract.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HDdo1rNRVQnVRRdsqSrvG3

* docs: correct the test header's count of unavailability entry points

The shape check added a fourth way "unavailable" can arrive, and the
enumeration in secret-store.ts was updated to match, but the test file's
header still said three — so it read as an exhaustive list that silently
omitted the case a whole describe below it covers.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HDdo1rNRVQnVRRdsqSrvG3

* fix: give the wrong-shape cause its own remediation hint

The shape check added a cause that fell through to the libsecret
advice — so a packaging mismatch told the user to install a keyring
daemon, which cannot help, and on Windows or macOS points somewhere that
does not exist. That is the same wrong-advice bug the native-binding
branch was added to fix, reintroduced by the guard itself.

Hint selection moves into `hintFor`, where libsecret is the explicit
fallback rather than the default, and the shape failure becomes a
distinct `KeyringModuleShapeError` matched by type — it is our own error,
so there is no reason to re-parse text we wrote (the native-binding
branch matches a string only because that message comes from napi-rs).

Also retitles the wrong-shape test: it claimed the guard avoids
"returning null secrets", but `get` returns null either way by the
read-tolerance contract. The title now says what actually differs —
`set` hard-fails — matching the correction already made in the comments.

Both raised by Copilot review.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HDdo1rNRVQnVRRdsqSrvG3

* fix: give both shape-check failure paths the packaging hint

The shape check can fail two ways — the members are absent, or reading
them throws — and only the first carried KeyringModuleShapeError. The
catch path returned the raw error, so a Proxy-backed namespace throwing
on access fell through to the libsecret advice: the same wrong-remedy
bug as the previous two commits, one branch further along.

Both paths now carry the type. KeyringModuleShapeError takes a detail
string plus a standard `cause`, so the throwing path reads "its exports
could not be read: <original>" and keeps the underlying failure legible
while still earning the packaging hint.

Three instances of one mistake in a row (a new cause added without
deciding which remediation it inherits) says the shape was wrong, not
just the branch: making libsecret an explicit fallback in `hintFor` did
not stop me adding a second exit that skipped it. The tests now pin the
invariant directly — one asserts both construction paths produce the
same hint — so the next cause that forgets is a failing test rather than
a reviewer's catch.

Raised by Copilot review.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HDdo1rNRVQnVRRdsqSrvG3

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Cliff Hall 2026-08-08 21:15:20 -04:00 • committed by GitHub
commit a09f2dcf1d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 525 additions and 30 deletions
Download patch file Download diff file Expand all files Collapse all files

4
clients/web/server/vite-base-config.ts
View file

@ -28,7 +28,9 @@ const NODE_ONLY_OPTIMIZE_DEPS_EXCLUDE = [
"which",
// `@napi-rs/keyring` is loaded only inside
// `core/auth/node/secret-store.ts` from the Hono `/api/servers`
// handlers. It's a native-binding package (no browser code path) so
// handlers — and lazily even there, via a cached dynamic import, so
// an unsupported platform degrades instead of crashing at startup
// (#1905). It's a native-binding package (no browser code path) so
// excluding it keeps Vite's dep scanner from chasing into the
// platform-specific binaries during dev startup.
"@napi-rs/keyring",

315
clients/web/src/test/integration/auth/node/secret-store.test.ts
View file

@ -7,8 +7,16 @@
* so the suite stubs the native side and asserts the tolerance contract
* (`get` returns null on failure, destructive ops no-op, `set` is the
* one operation that hard-fails with `KeychainUnavailableError`).
*
* The contract has four entry points for "unavailable" and the suite
* covers all four: the operation throwing, `AsyncEntry`'s constructor
* throwing (#1848), the package failing to load at all (#1905), and the
* package loading but exposing the wrong shape. The last two can't use
* the shared stub — one needs the *import* to reject, the other needs it
* to resolve to a namespace the stub can't express — so each lives in
* its own describe built on `vi.resetModules()`.
*/
import { describe, it, expect, beforeEach, vi } from "vitest";
import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
// The mock must be hoisted above the `await import` of secret-store
// inside the `KeyringSecretStore` describe block. Use `vi.hoisted` so
@ -81,6 +89,7 @@ import {
InMemorySecretStore,
KeyringSecretStore,
KeychainUnavailableError,
KeyringModuleShapeError,
SECRET_FIELD_OAUTH_CLIENT_SECRET,
envSecretField,
parseAccount,
@ -330,6 +339,59 @@ describe("KeyringSecretStore (mocked native bindings)", () => {
expect(err.message).toMatch(/libsecret/);
});
// The two hint branches are asserted by direct construction rather than
// through the store: the unloadable-package path can only be reached via
// a throwing `vi.doMock` factory, and vitest substitutes its own "error
// when mocking a module" message for whatever that factory throws — so
// the real loader text never reaches the constructor from there. These
// two cases pin the wording against the message the napi-rs loader
// actually produces.
it("KeychainUnavailableError steers a missing native binding to a reinstall", () => {
const err = new KeychainUnavailableError(
new Error(
"Cannot find native binding. npm has a bug related to optional dependencies…",
),
);
expect(err.message).toMatch(/reinstall the Inspector/);
expect(err.message).toMatch(/npx cache/);
// The Linux keyring-daemon advice is irrelevant to this cause.
expect(err.message).not.toMatch(/libsecret/);
expect(err.message).toMatch(/Cannot find native binding/);
});
it("KeychainUnavailableError points a wrong-shape module at a reinstall, not at libsecret", () => {
// A packaging/version mismatch is not a missing keyring daemon, so
// the libsecret line would send the user somewhere that cannot help.
const err = new KeychainUnavailableError(
new KeyringModuleShapeError("did not expose AsyncEntry"),
);
expect(err.message).toMatch(/does not expose the API this build expects/);
expect(err.message).not.toMatch(/libsecret/);
});
it("KeychainUnavailableError gives the same hint however the shape check failed", () => {
// The shape check fails two ways — members absent, or reading them
// throws. Both are the same underlying problem, so both must earn the
// packaging hint; only one of them carrying it was the original bug.
const err = new KeychainUnavailableError(
new KeyringModuleShapeError("its exports could not be read: boom", {
cause: new Error("boom"),
}),
);
expect(err.message).toMatch(/does not expose the API this build expects/);
expect(err.message).not.toMatch(/libsecret/);
// The original failure is still legible in the message.
expect(err.message).toMatch(/boom/);
});
it("KeychainUnavailableError keeps the libsecret advice for other causes", () => {
const err = new KeychainUnavailableError(
new Error("failed to unlock the default collection"),
);
expect(err.message).toMatch(/libsecret/);
expect(err.message).not.toMatch(/reinstall the Inspector/);
});
it("KeychainUnavailableError carries the underlying error message", async () => {
keyringMocks.failures.setThrows = true;
try {
@ -386,3 +448,254 @@ describe("KeyringSecretStore (mocked native bindings)", () => {
});
});
});
describe("@napi-rs/keyring unloadable on this platform (#1905)", () => {
// `@napi-rs/keyring` ships one prebuilt binary per platform triple and
// throws on import where it has none — Android / Termux is the reported
// case. A static top-level import made that a startup crash: the module
// never evaluated, so none of the tolerance handling could run.
//
// The shared stub above can't express this: it models a keyring that
// loads. Here the *import itself* rejects, which needs a fresh module
// registry — hence `vi.resetModules()` + `vi.doMock` and a re-import
// rather than a flag. The re-imported module is a distinct instance, so
// its `KeychainUnavailableError` is a distinct class identity too; the
// assertions below use the freshly imported one.
// The real-world message on Termux. Documentary here — see the cause
// assertion below for why vitest doesn't let it through verbatim.
const LOAD_ERROR = "Cannot find module '@napi-rs/keyring-android-arm64'";
/** Fresh secret-store module whose `@napi-rs/keyring` import rejects. */
const importWithUnloadableKeyring = async (
onLoadAttempt: () => void = () => {},
) => {
vi.resetModules();
vi.doMock("@napi-rs/keyring", () => {
onLoadAttempt();
throw new Error(LOAD_ERROR);
});
return await import("@inspector/core/auth/node/secret-store.js");
};
afterEach(() => {
vi.doUnmock("@napi-rs/keyring");
vi.resetModules();
});
it("the module still evaluates — importing it must not throw", async () => {
// The regression itself: with a static top-level import this rejects,
// and the Inspector exits before reaching any fallback.
await expect(importWithUnloadableKeyring()).resolves.toHaveProperty(
"KeyringSecretStore",
);
});
it("get returns null", async () => {
const mod = await importWithUnloadableKeyring();
const store = new mod.KeyringSecretStore();
expect(await store.get("alpha", "oauth-client-secret")).toBe(null);
});
it("set throws KeychainUnavailableError carrying the load failure as its cause", async () => {
const mod = await importWithUnloadableKeyring();
const store = new mod.KeyringSecretStore();
await expect(
store.set("alpha", "oauth-client-secret", "v"),
).rejects.toBeInstanceOf(mod.KeychainUnavailableError);
// Asserted by shape, not by the literal text: vitest substitutes its
// own "error when mocking a module" message for a throwing `doMock`
// factory, so `LOAD_ERROR` never reaches the store here. What matters
// — and what is testable — is that the load failure is appended as
// the cause rather than swallowed. In production the real
// "Cannot find native binding" text lands in that slot.
await expect(
store.set("alpha", "oauth-client-secret", "v"),
).rejects.toThrow(/Underlying error: .+/);
});
it("set does not double-wrap the typed error", async () => {
// The load failure is already a `KeychainUnavailableError` by the time
// the catch sees it; re-wrapping would bury the cause a level deeper.
const mod = await importWithUnloadableKeyring();
const store = new mod.KeyringSecretStore();
try {
await store.set("alpha", "oauth-client-secret", "v");
throw new Error("expected throw");
} catch (err) {
expect(err).toBeInstanceOf(mod.KeychainUnavailableError);
// One "OS keychain is not available" prefix, not two nested.
expect(
(err as Error).message.match(/OS keychain is not available/g),
).toHaveLength(1);
}
});
it("delete and deleteAllForServer silently no-op", async () => {
const mod = await importWithUnloadableKeyring();
const store = new mod.KeyringSecretStore();
await expect(
store.delete("alpha", "oauth-client-secret"),
).resolves.toBeUndefined();
await expect(store.deleteAllForServer("alpha")).resolves.toBeUndefined();
});
it("attempts the load once and caches the failure", async () => {
// Without the cache every secret operation re-attempts (and re-throws)
// the resolution — `expectedSecretFields` means that is once per
// server per `GET /api/servers`.
const onLoadAttempt = vi.fn();
const mod = await importWithUnloadableKeyring(onLoadAttempt);
const store = new mod.KeyringSecretStore();
await store.get("alpha", "oauth-client-secret");
await store.get("beta", "oauth-client-secret");
await store.delete("alpha", "oauth-client-secret");
expect(onLoadAttempt).toHaveBeenCalledTimes(1);
});
});
describe("@napi-rs/keyring loads but exposes the wrong shape", () => {
// The package is CJS, so `AsyncEntry` / `findCredentialsAsync` reach us
// through named-export interop. That holds today — verified against the
// real package — but if it ever stopped (a default-only export upstream,
// a bundler changing interop, a platform where named-export detection
// fails), the members would be `undefined` and `new undefined(...)` would
// throw a TypeError *inside* the try that implements degradation.
//
// What the shape check fixes is the *diagnosis*, not the data loss: `get`
// returns null with or without it (read-tolerance is its contract), so
// the empty secret list looks the same either way. The difference is that
// `set` names the shape problem at the load boundary instead of reporting
// "keyring.mod.AsyncEntry is not a constructor". Only the cause-message
// test below actually fails without the guard — the others pin the
// surrounding contract and would pass either way.
const importWithKeyringShape = async (shape: Record<string, unknown>) => {
vi.resetModules();
vi.doMock("@napi-rs/keyring", () => shape);
return await import("@inspector/core/auth/node/secret-store.js");
};
afterEach(() => {
vi.doUnmock("@napi-rs/keyring");
vi.resetModules();
});
// The members are declared but not callable, rather than absent. That is
// the shape a default-only export would leave behind, and it keeps these
// cases on the `typeof !== "function"` branch deterministically: vitest's
// module mock *throws* on reading a key the factory never returned, which
// is a different path (covered by its own case at the end).
const ENTRY_NOT_A_FUNCTION = {
AsyncEntry: undefined,
findCredentialsAsync: async () => [],
};
it("hard-fails set for a namespace without a callable AsyncEntry (get still returns null by contract)", async () => {
const mod = await importWithKeyringShape(ENTRY_NOT_A_FUNCTION);
const store = new mod.KeyringSecretStore();
// `get` returning null is the read-tolerance contract, not something
// the shape check changes — it reads the same as "no secret stored",
// which is exactly why `set` has to be the operation that hard-fails.
expect(await store.get("alpha", "oauth-client-secret")).toBe(null);
await expect(
store.set("alpha", "oauth-client-secret", "v"),
).rejects.toBeInstanceOf(mod.KeychainUnavailableError);
});
it("names the shape problem as the cause, not a bare unavailability", async () => {
const mod = await importWithKeyringShape(ENTRY_NOT_A_FUNCTION);
const store = new mod.KeyringSecretStore();
try {
await store.set("alpha", "oauth-client-secret", "v");
throw new Error("expected throw");
} catch (err) {
expect((err as Error).message).toMatch(
/did not expose AsyncEntry \/ findCredentialsAsync/,
);
// Not double-wrapped: the load failure is already typed by the time
// `set`'s catch sees it.
expect(
(err as Error).message.match(/OS keychain is not available/g),
).toHaveLength(1);
}
});
it("treats a namespace without a callable findCredentialsAsync as unavailable too", async () => {
// `deleteAllForServer` is the only caller of it, so a shape check on
// `AsyncEntry` alone would let this one through to a TypeError.
class StubEntry {
async getPassword(): Promise<string | undefined> {
return undefined;
}
}
const mod = await importWithKeyringShape({
AsyncEntry: StubEntry,
findCredentialsAsync: undefined,
});
const store = new mod.KeyringSecretStore();
await expect(
store.set("alpha", "oauth-client-secret", "v"),
).rejects.toBeInstanceOf(mod.KeychainUnavailableError);
await expect(store.deleteAllForServer("alpha")).resolves.toBeUndefined();
});
it("treats a namespace that throws on member access as unavailable", async () => {
// Reading a missing export is not always a harmless `undefined` — a
// Proxy-backed namespace can throw, and vitest's module mock does. If
// that throw escaped the shape check it would reject the *cached*
// promise, so the check has to absorb it and report unavailable.
const mod = await importWithKeyringShape({});
const store = new mod.KeyringSecretStore();
expect(await store.get("alpha", "oauth-client-secret")).toBe(null);
await expect(
store.set("alpha", "oauth-client-secret", "v"),
).rejects.toBeInstanceOf(mod.KeychainUnavailableError);
// …and it reaches the user as a packaging problem, not as "install
// libsecret". Returning the raw access error here would have been
// typed correctly but hinted wrongly.
await expect(
store.set("alpha", "oauth-client-secret", "v"),
).rejects.toThrow(/does not expose the API this build expects/);
await expect(
store.set("alpha", "oauth-client-secret", "v"),
).rejects.not.toThrow(/libsecret/);
// Absorbed, not escaped: a rejected cached promise would surface here
// as the raw access error instead of the typed one.
await expect(store.deleteAllForServer("alpha")).resolves.toBeUndefined();
});
it("accepts a well-formed namespace", async () => {
// The guard must not reject the shape the package actually ships —
// otherwise it would turn a working keychain into a permanent 503.
const stored = new Map<string, string>();
class StubEntry {
// Declared explicitly rather than as a constructor parameter
// property: those are disallowed under `erasableSyntaxOnly`.
private readonly account: string;
constructor(_service: string, account: string) {
this.account = account;
}
async getPassword(): Promise<string | undefined> {
return stored.get(this.account);
}
async setPassword(value: string): Promise<void> {
stored.set(this.account, value);
}
async deleteCredential(): Promise<boolean> {
return stored.delete(this.account);
}
}
const mod = await importWithKeyringShape({
AsyncEntry: StubEntry,
findCredentialsAsync: async () => [],
});
const store = new mod.KeyringSecretStore();
await store.set("alpha", "oauth-client-secret", "shh");
expect(await store.get("alpha", "oauth-client-secret")).toBe("shh");
});
});

236
core/auth/node/secret-store.ts
View file

@ -13,10 +13,124 @@
* browser side never imports this; it gets values rehydrated into the
* `/api/servers` response by the Hono handler.
*/
import { AsyncEntry, findCredentialsAsync } from "@napi-rs/keyring";
const SERVICE_NAME = "mcp-inspector";
/**
* `@napi-rs/keyring` ships one prebuilt binary per platform triple, and
* loading the package *throws* on a platform it has no binary for —
* Android / Termux is the reported case (#1905), where the import fails
* with "Cannot find native binding" / "Cannot find module
* '@napi-rs/keyring-android-arm64'".
*
* A static top-level import made that a startup crash: the module never
* evaluated, so the Inspector exited before any of the
* keychain-unavailable handling below could run. Loading it lazily, and
* caching the *outcome* rather than only the module, folds an
* unsupported platform into the same degradation contract as an
* unreachable keychain (see `KeyringSecretStore`) — the store is simply
* unavailable, and callers see it through the documented behavior
* instead of a crash.
*
* The failure is cached alongside the success so a box without a binary
* doesn't re-attempt (and re-throw) the resolution on every secret
* operation, and so `set` can name the underlying cause in its
* `KeychainUnavailableError`.
*
* The cache is process-lifetime by design — there is no reset seam, since
* a platform does not grow a native binary mid-run. Tests reach the
* unloadable path through `vi.resetModules()` + `vi.doMock`, which gives
* them a fresh module (and so a fresh cache) instead.
*
* A resolved import is also **shape-checked** before being accepted. The
* package is CJS, so the named exports we rely on come from interop, and
* a resolution that stopped yielding them (a default-only export in a
* future version, a bundler changing interop, a platform where the
* named-export detection fails) would land as `undefined`, making
* `new mod.AsyncEntry(...)` throw `TypeError: not a constructor` from
* inside the very `try` that implements graceful degradation.
*
* Be precise about what this buys, because it is narrower than it looks:
* it does **not** stop a bad shape from emptying the secret list. `get`
* returns `null` either way — that is its read-tolerance contract, and
* the `TypeError` lands in the same `catch` that a dead keychain does.
* What the check changes is *diagnosis*. Without it the only signal is
* `set` reporting "keyring.mod.AsyncEntry is not a constructor", an
* internal-looking message that reads like an Inspector bug; with it,
* `set` names the actual problem once, at the load boundary, in the same
* actionable 503 as every other flavor of unavailability. Detecting the
* silent-empty-list case itself would take a real round-trip against the
* unmocked package, which nothing in the suite does today.
*/
type KeyringModule = typeof import("@napi-rs/keyring");
type KeyringLoad =
| { ok: true; mod: KeyringModule }
| { ok: false; err: unknown };
let keyringLoad: Promise<KeyringLoad> | undefined;
/**
* Accept a resolved import only if it carries the two members we call.
*
* The member *access* is inside the `try` because reading a missing
* export is not always the harmless `undefined` a plain ESM namespace
* gives: a Proxy-based namespace can throw on an unknown key (vitest's
* module mocks do exactly that). Either way the answer is the same —
* unavailable — and returning it rather than throwing is what keeps the
* cached promise from ever rejecting.
*/
/**
* Marks the shape-check failure so `KeychainUnavailableError` can give
* advice that fits it. A distinct type rather than a string match on the
* message: this is our own error, so there is no reason to re-parse text
* we just wrote (the native-binding branch matches on a string only
* because that message comes from someone else's loader).
*/
export class KeyringModuleShapeError extends Error {
constructor(detail: string, options?: { cause?: unknown }) {
super(`@napi-rs/keyring loaded but ${detail}`, options);
this.name = "KeyringModuleShapeError";
}
}
const checkKeyringShape = (mod: KeyringModule): KeyringLoad => {
try {
if (
typeof mod.AsyncEntry === "function" &&
typeof mod.findCredentialsAsync === "function"
) {
return { ok: true, mod };
}
return {
ok: false,
err: new KeyringModuleShapeError(
"did not expose AsyncEntry / findCredentialsAsync",
),
};
} catch (err) {
// Both ways of failing the shape check are the same problem — the
// module is not the API we expect — so both carry the type that
// earns the packaging hint. Returning the raw error here instead
// would drop it back to the libsecret advice, which is what this
// whole branch exists to avoid.
return {
ok: false,
err: new KeyringModuleShapeError(
`its exports could not be read: ${err instanceof Error ? err.message : String(err)}`,
{ cause: err },
),
};
}
};
const loadKeyring = (): Promise<KeyringLoad> => {
keyringLoad ??= import("@napi-rs/keyring").then(
checkKeyringShape,
(err: unknown): KeyringLoad => ({ ok: false, err }),
);
return keyringLoad;
};
export {
SECRET_FIELD_OAUTH_CLIENT_SECRET,
SECRET_FIELD_IDP_CLIENT_SECRET,
@ -39,22 +153,50 @@ const buildAccount = (serverId: string, field: string): string =>
`${serverId}:${field}`;
/**
* Thrown when the OS keychain is unavailable — typically Linux without
* libsecret / gnome-keyring installed. Surfaced as a 503 by the API
* handlers so the UI can show an actionable error rather than a generic
* 500. macOS and Windows always have a working keychain, so this only
* realistically fires on minimal Linux installs.
* Thrown when the OS keychain is unavailable. Surfaced as a 503 by the
* API handlers so the UI can show an actionable error rather than a
* generic 500 — and "actionable" is the point: the causes need
* *different* fixes, so the message carries a hint chosen per cause
* (see `hintFor`). Three realistic ones:
*
* - **The keychain itself is missing** — Linux without libsecret /
* gnome-keyring. Install it.
* - **`@napi-rs/keyring` won't load** — no platform binary for this
* triple (Android/Termux, #1905) or npm's optional-deps bug dropping
* it on a supported one (npm/cli#4828). Reinstall / clear the npx
* cache; installing a keyring daemon would not help.
* - **It loads but exposes the wrong API** — a version or packaging
* mismatch (`KeyringModuleShapeError`). Also not a daemon problem.
*/
export class KeychainUnavailableError extends Error {
constructor(cause: unknown) {
const message = cause instanceof Error ? cause.message : String(cause);
super(
`OS keychain is not available. On Linux, install libsecret / gnome-keyring. ` +
`Underlying error: ${cause instanceof Error ? cause.message : String(cause)}`,
`OS keychain is not available. ${hintFor(cause, message)} Underlying error: ${message}`,
);
this.name = "KeychainUnavailableError";
}
}
/**
* The remediation that fits the cause. Wrong advice is worse than none —
* telling someone on Windows to install libsecret sends them down a path
* that cannot work — so every cause that has its own fix gets its own
* branch, and the libsecret line is the fallback rather than the default.
*/
const hintFor = (cause: unknown, message: string): string => {
// Our own error, so match on the type rather than re-parsing text we wrote.
if (cause instanceof KeyringModuleShapeError) {
return `The @napi-rs/keyring package loaded but does not expose the API this build expects — most likely a version or packaging mismatch; reinstall the Inspector, and report this if it persists.`;
}
// This phrasing comes from the napi-rs loader, not from us: it is what
// the package throws when the platform binary is missing.
if (message.includes("Cannot find native binding")) {
return `The @napi-rs/keyring platform package for this OS is missing or unavailable — reinstall the Inspector (for npx, clear the npx cache under your npm cache directory first).`;
}
return `On Linux, install libsecret / gnome-keyring.`;
};
/**
* Storage interface for the per-server secrets we lift off
* `~/.mcp-inspector/mcp.json`. Implemented by `KeyringSecretStore` (the
@ -79,28 +221,48 @@ export interface SecretStore {
* can use `=== null` rather than truthiness (an empty-string secret is
* a real value and must round-trip).
*
* **Availability behavior.** When the keychain is unavailable (the
* typical case is Linux without libsecret / gnome-keyring, or a
* container with no D-Bus session), `set` is the only operation that
* throws `KeychainUnavailableError` — that's the moment where data
* would actually be lost. `get` returns `null` (as if no entry
* existed) and the destructive operations silently no-op (there's
* nothing to delete anyway). This keeps non-secret flows working on a
* stock CI runner / minimal Linux box; the user only hits a hard error
* when they actually try to save a secret.
* **Availability behavior.** When the keychain is unavailable, `set` is
* the only operation that throws `KeychainUnavailableError` — that's
* the moment where data would actually be lost. `get` returns `null`
* (as if no entry existed) and the destructive operations silently
* no-op (there's nothing to delete anyway). This keeps non-secret flows
* working on a stock CI runner / minimal Linux box / unsupported
* platform; the user only hits a hard error when they actually try to
* save a secret.
*
* The `AsyncEntry` construction is deliberately **inside** each
* method's `try`: `AsyncEntry::new` performs the platform-store setup
* (on Linux, the Secret Service connect with a keyutils fallback) and
* throws when no backend is reachable. Constructing it outside the
* `try` let that raw error escape, 500ing every `GET /api/servers`
* before any secret was involved — the contract above only holds if
* construction failures are funneled through the same handlers (#1848).
* "Unavailable" covers four distinct failures, all funneled into that
* one contract — the contract is only as good as its narrowest funnel,
* and each of these escaped it at some point:
*
* 1. **The package won't load at all** — no prebuilt binary for this
* platform (Android / Termux). A static top-level import made this a
* startup crash before any handling ran (#1905); `loadKeyring()`
* above defers and caches it instead.
* 2. **The package loads but exposes the wrong shape** — the named
* exports arrive via CJS interop, so a resolution that stopped
* yielding them would hand us `undefined` and fail as a `TypeError`
* swallowed by the degradation path. `loadKeyring()` shape-checks up
* front so `set` can name that cause instead of surfacing an
* "is not a constructor" message (see the note there — the check
* improves the diagnosis, it does not change what `get` returns).
* 3. **`AsyncEntry::new` throws** — it performs the platform-store setup
* (on Linux, the Secret Service connect with a keyutils fallback) and
* throws when no backend is reachable. Construction is therefore
* deliberately **inside** each method's `try`; outside it, the raw
* error escaped and 500'd every `GET /api/servers` before any secret
* was involved (#1848).
* 4. **The operation itself throws** — the original case, and the only
* one the first version of this contract actually handled.
*/
export class KeyringSecretStore implements SecretStore {
async get(serverId: string, field: string): Promise<string | null> {
try {
const entry = new AsyncEntry(SERVICE_NAME, buildAccount(serverId, field));
const keyring = await loadKeyring();
if (!keyring.ok) return null;
const entry = new keyring.mod.AsyncEntry(
SERVICE_NAME,
buildAccount(serverId, field),
);
const v = await entry.getPassword();
return v ?? null;
} catch {
@ -114,9 +276,20 @@ export class KeyringSecretStore implements SecretStore {
async set(serverId: string, field: string, value: string): Promise<void> {
try {
const entry = new AsyncEntry(SERVICE_NAME, buildAccount(serverId, field));
const keyring = await loadKeyring();
// An unloadable package is as fatal to a write as an unreachable
// keychain, and for the same reason — the value would vanish.
if (!keyring.ok) throw new KeychainUnavailableError(keyring.err);
const entry = new keyring.mod.AsyncEntry(
SERVICE_NAME,
buildAccount(serverId, field),
);
await entry.setPassword(value);
} catch (err) {
// Already the typed error when the module failed to load — don't
// double-wrap it (that would bury the underlying cause one level
// deeper in the message).
if (err instanceof KeychainUnavailableError) throw err;
// The only operation that hard-fails — if we can't persist the
// secret, the user needs to know now rather than discover later
// that their value disappeared. Routes translate this to a 503.
@ -126,7 +299,12 @@ export class KeyringSecretStore implements SecretStore {
async delete(serverId: string, field: string): Promise<void> {
try {
const entry = new AsyncEntry(SERVICE_NAME, buildAccount(serverId, field));
const keyring = await loadKeyring();
if (!keyring.ok) return;
const entry = new keyring.mod.AsyncEntry(
SERVICE_NAME,
buildAccount(serverId, field),
);
await entry.deleteCredential();
} catch {
// Every reason for a throw collapses to the same desired outcome
@ -142,7 +320,9 @@ export class KeyringSecretStore implements SecretStore {
async deleteAllForServer(serverId: string): Promise<void> {
let creds: Array<{ account: string; password: string }>;
try {
creds = await findCredentialsAsync(SERVICE_NAME);
const keyring = await loadKeyring();
if (!keyring.ok) return;
creds = await keyring.mod.findCredentialsAsync(SERVICE_NAME);
} catch {
// Same reasoning as `delete`: nothing was written, nothing to sweep.
return;