From 4282c536c55bef73de0f0f8db06e9f354bc8412b Mon Sep 17 00:00:00 2001 From: ldraney Date: Wed, 28 Jan 2026 12:11:04 -0700 Subject: [PATCH] docs: add security section and keychain prompt explanation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add macOS Keychain prompt explanation to guide (the "node wants to use your confidential information" dialog) - Add dedicated Security section covering keychain storage, OAuth flow, server-side client secret, and no open ports - Update auth steps to reflect actual browser redirect flow - Fix architecture.html: keytar → @napi-rs/keyring Refs #69 Co-Authored-By: Claude Opus 4.5 --- docs/architecture.html | 6 +++--- docs/guide.html | 39 +++++++++++++++++++++++++++++++++++---- 2 files changed, 38 insertions(+), 7 deletions(-) diff --git a/docs/architecture.html b/docs/architecture.html index eee5d62..995a784 100644 --- a/docs/architecture.html +++ b/docs/architecture.html @@ -261,9 +261,9 @@

Decision: Tool Naming Convention

Decision: Token Storage

-

Choice: OS Keychain via keytar

-

Alternatives considered: File-based (~/.github-mcp), environment variables only

-

Rationale: Native security, no plaintext files, cross-platform

+

Choice: OS Keychain via @napi-rs/keyring

+

Alternatives considered: File-based (~/.github-mcp), environment variables only, keytar (replaced — required libsecret on Linux)

+

Rationale: Native security, no plaintext files, cross-platform, prebuilt binaries with no system dependencies

diff --git a/docs/guide.html b/docs/guide.html index aa034e8..eaaf050 100644 --- a/docs/guide.html +++ b/docs/guide.html @@ -384,14 +384,45 @@

Ask for Help

Authentication

On first use, you'll authenticate via GitHub OAuth:

    -
  1. A code appears in your terminal/Claude
    2. -
  2. Visit github.com/login/device
    3. -
  3. Enter the code
    4. +
  4. Your browser opens to GitHub's authorization page
  5. Authorize the app
    6. -
  6. Token is stored securely in your OS keychain
    7. +
  7. GitHub redirects back and your token is stored securely in your OS keychain

You only need to do this once. To re-authenticate: npx @ldraney/github-mcp auth login

+
+

macOS Keychain Prompt

+

On macOS, you'll see a system dialog:

+

"node wants to use your confidential information stored in 'github-mcp' in your keychain."

+

This is expected and is a good sign — it means your GitHub token is stored in the macOS Keychain, the same encrypted vault that Safari, Mail, and other system apps use for credentials. Enter your login keychain password (your Mac login password) to allow access.

+

You can click Always Allow to avoid the prompt on future launches.

+
+ +

Security

+

GitHub MCP is designed so your credentials never touch the filesystem as plaintext.

+ +
+
+

OS Keychain Storage

+

Your GitHub token is stored in your operating system's native credential manager — macOS Keychain, Windows Credential Manager, or Linux secret-service. These are encrypted, OS-protected stores. Your token is never written to a config file, environment file, or disk.

+
+ +
+

OAuth — No PATs to Manage

+

Authentication uses GitHub's OAuth flow. You authorize in your browser and the token is issued directly — you never create, copy, or paste a Personal Access Token. Tokens can be revoked from your GitHub settings at any time.

+
+ +
+

Client Secret Stays Server-Side

+

The OAuth client secret is held on our backend server, never shipped in the npm package or .mcpb bundle. Your machine only ever handles the short-lived authorization code and the resulting token.

+
+ +
+

No Open Ports

+

The OAuth callback uses a temporary local HTTP server on a random port that only listens for a single redirect, then shuts down. Webhook delivery uses smee.io (outbound SSE), so no inbound ports are ever exposed.

+
+
+

Links