@plaudai/dsh-mcp-oauth 0.0.0-stage → 0.1.1

package/lib/browser.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Hand a URL to the user's default browser without blocking the host process.
+ *
+ * Never throws: an environment with no desktop session simply gets the URL
+ * logged by the caller, and the authorization flow can still be completed by
+ * pasting it elsewhere.
+ */
+export declare function openBrowser(url: string): void;

package/lib/browser.js

@@ -0,0 +1,23 @@
+import { spawn } from 'node:child_process';
+/**
+ * Hand a URL to the user's default browser without blocking the host process.
+ *
+ * Never throws: an environment with no desktop session simply gets the URL
+ * logged by the caller, and the authorization flow can still be completed by
+ * pasting it elsewhere.
+ */
+export function openBrowser(url) {
+    const [command, args] = process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '', url]]
+        : process.platform === 'darwin'
+            ? ['open', [url]]
+            : ['xdg-open', [url]];
+    try {
+        const child = spawn(command, args, { detached: true, stdio: 'ignore', windowsHide: true });
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch {
+        // The caller logs the URL; a missing browser is not a fatal condition.
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1,59 @@
+import { type PluginContext } from './tools.js';
+export { DshOAuthProvider, OAuthCallbackListener, ensureAuthorized } from './oauth.js';
+export { TokenStore, dshHome } from './store.js';
+export { buildChildEnv, createTransport } from './transport.js';
+export { publicToolName, syncTools } from './tools.js';
+export type { CallbackResult, ProviderOptions } from './oauth.js';
+export type { PluginContext, PluginLogger } from './tools.js';
+/** Per-service defaults baked into a connector package. */
+export interface McpPluginPreset {
+    /** Namespace for tool names and the credential file. */
+    serverName: string;
+    /** `streamable-http` for remote servers, `stdio` for child processes. */
+    transport: 'streamable-http' | 'stdio';
+    /** How the remote server authenticates. Ignored for stdio. */
+    auth?: 'oauth' | 'bearer' | 'none' | undefined;
+    /** Remote MCP endpoint. */
+    url?: string | undefined;
+    /** Local command for stdio servers. */
+    command?: string | undefined;
+    /** Default argument vector for stdio servers. */
+    args?: string[] | undefined;
+    /** Environment variable that carries a bearer token. */
+    bearerTokenEnv?: string | undefined;
+    /** Default scope request. */
+    scope?: string | undefined;
+}
+/** Resolved plugin configuration after schemastery defaults are applied. */
+export interface ResolvedConfig {
+    serverName: string;
+    transport: string;
+    auth: string;
+    url: string;
+    headers: Record<string, string>;
+    bearerTokenEnv: string;
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+    cwd: string;
+    scope: string;
+    clientId: string;
+    clientSecret: string;
+    authorizationParams: Record<string, string>;
+    tokenEndpointAuthMethod: string;
+    toolCallTimeoutMs: number;
+    authTimeoutMs: number;
+    failOnStartupError: boolean;
+}
+/**
+ * Build a Cordis plugin for one MCP server.
+ *
+ * The returned object carries the four names the harness loader reads, so a
+ * service package only needs to re-export them.
+ */
+export declare function createMcpPlugin(preset: McpPluginPreset): {
+    name: string;
+    inject: string[];
+    Config: unknown;
+    apply(ctx: PluginContext, config: ResolvedConfig): Promise<void>;
+};

package/lib/index.js

@@ -0,0 +1,191 @@
+import z from '@deepseek-ai/schemastery';
+import { Client } from '@modelcontextprotocol/client';
+import { DshOAuthProvider, OAuthCallbackListener, ensureAuthorized } from './oauth.js';
+import { TokenStore } from './store.js';
+import { createTransport } from './transport.js';
+import { syncTools } from './tools.js';
+export { DshOAuthProvider, OAuthCallbackListener, ensureAuthorized } from './oauth.js';
+export { TokenStore, dshHome } from './store.js';
+export { buildChildEnv, createTransport } from './transport.js';
+export { publicToolName, syncTools } from './tools.js';
+/** Valid `serverName`: short, filesystem-safe, unique per server. */
+const SERVER_NAME_PATTERN = /^[A-Za-z0-9_-]{1,32}$/;
+/**
+ * Build a Cordis plugin for one MCP server.
+ *
+ * The returned object carries the four names the harness loader reads, so a
+ * service package only needs to re-export them.
+ */
+export function createMcpPlugin(preset) {
+    const Config = z.object({
+        serverName: z.string().default(preset.serverName).pattern(SERVER_NAME_PATTERN),
+        transport: z.string().default(preset.transport),
+        auth: z.string().default(preset.auth ?? 'none'),
+        url: z.string().default(preset.url ?? ''),
+        headers: z.dict(String).default({}),
+        bearerTokenEnv: z.string().default(preset.bearerTokenEnv ?? ''),
+        command: z.string().default(preset.command ?? ''),
+        args: z.array(String).default(preset.args ?? []),
+        env: z.dict(String).default({}),
+        cwd: z.string().default(''),
+        scope: z.string().default(preset.scope ?? ''),
+        clientId: z.string().default(''),
+        clientSecret: z.string().default(''),
+        authorizationParams: z.dict(String).default({}),
+        tokenEndpointAuthMethod: z.string().default(''),
+        toolCallTimeoutMs: z.number().default(120_000),
+        authTimeoutMs: z.number().default(300_000),
+        failOnStartupError: z.boolean().default(false),
+    });
+    async function apply(ctx, config) {
+        const label = `mcp-oauth(${config.serverName})`;
+        const disposers = new Map();
+        const listener = new OAuthCallbackListener();
+        let client;
+        let tornDown = false;
+        const teardown = () => {
+            if (tornDown)
+                return;
+            tornDown = true;
+            listener.close();
+            for (const dispose of disposers.values())
+                dispose();
+            disposers.clear();
+            const current = client;
+            client = undefined;
+            void current?.close().catch(() => { });
+        };
+        ctx.effect(() => teardown, 'mcp-oauth.connection');
+        try {
+            if (config.transport === 'stdio') {
+                if (config.command.length === 0)
+                    throw new Error(`${label}: "command" is required for the stdio transport`);
+                const connected = newClient();
+                try {
+                    await connected.connect(createTransport({
+                        transport: 'stdio',
+                        command: config.command,
+                        args: config.args,
+                        env: config.env,
+                        cwd: config.cwd,
+                    }));
+                }
+                catch (error) {
+                    await connected.close().catch(() => { });
+                    throw error;
+                }
+                client = connected;
+            }
+            else {
+                if (config.url.length === 0)
+                    throw new Error(`${label}: "url" is required for the streamable-http transport`);
+                const url = new URL(config.url);
+                let provider;
+                if (config.auth === 'oauth') {
+                    const redirectUrl = await listener.start();
+                    provider = new DshOAuthProvider({
+                        serverName: config.serverName,
+                        redirectUrl,
+                        store: new TokenStore(config.serverName),
+                        scope: config.scope.length > 0 ? config.scope : undefined,
+                        clientId: config.clientId.length > 0 ? config.clientId : undefined,
+                        clientSecret: config.clientSecret.length > 0 ? config.clientSecret : undefined,
+                        authorizationParams: config.authorizationParams,
+                        tokenEndpointAuthMethod: config.tokenEndpointAuthMethod.length > 0
+                            ? config.tokenEndpointAuthMethod
+                            : undefined,
+                        log: (message) => ctx.logger.info(message),
+                    });
+                    ctx.logger.info(`${label}: OAuth client ready (redirect ${redirectUrl})`);
+                }
+                const headers = { ...config.headers };
+                if (config.auth === 'bearer') {
+                    const variable = config.bearerTokenEnv;
+                    const token = variable.length > 0 ? process.env[variable] : undefined;
+                    if (token === undefined || token.length === 0) {
+                        throw new Error(`${label}: bearer auth needs ${variable.length > 0 ? variable : 'a token'} in the environment`);
+                    }
+                    headers.Authorization = `Bearer ${token}`;
+                }
+                try {
+                    client = await connectRemote(url, headers, provider);
+                }
+                catch (error) {
+                    const needsAuthorization = provider !== undefined && (isUnauthorized(error) || !(await provider.tokens()));
+                    if (!needsAuthorization)
+                        throw error;
+                    ctx.logger.info(`${label}: no usable token, starting the OAuth flow`);
+                    await ensureAuthorized({
+                        serverUrl: url,
+                        provider: provider,
+                        listener,
+                        timeoutMs: config.authTimeoutMs,
+                        log: (message) => ctx.logger.info(message),
+                    });
+                    client = await connectRemote(url, headers, provider);
+                }
+            }
+            const connectedClient = client;
+            if (connectedClient === undefined)
+                throw new Error(`${label}: connection was not established`);
+            const count = await syncTools(connectedClient, ctx, { serverName: config.serverName, toolCallTimeoutMs: config.toolCallTimeoutMs }, disposers);
+            ctx.logger.info(`${label}: connected, ${count} tool(s) registered`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            ctx.logger.error(`${label}: startup failed: ${message}`);
+            if (config.failOnStartupError)
+                throw error;
+        }
+    }
+    async function connectRemote(url, headers, provider) {
+        const connected = newClient();
+        try {
+            await connected.connect(createTransport({
+                transport: 'streamable-http',
+                url: url.toString(),
+                headers,
+                ...(provider !== undefined ? { authProvider: provider } : {}),
+            }));
+        }
+        catch (error) {
+            await connected.close().catch(() => { });
+            throw error;
+        }
+        return connected;
+    }
+    return {
+        // Per-service identity, so five connectors loaded side by side stay
+        // distinguishable in logs and in the host's plugin tree.
+        name: `mcp-${preset.serverName}`,
+        inject: ['tools'],
+        Config,
+        apply,
+    };
+}
+/**
+ * One MCP client generation.
+ *
+ * A Protocol instance is bound to one transport for life, so every reconnect
+ * builds a fresh client. `versionNegotiation: auto` keeps the bridge usable
+ * across MCP protocol revisions instead of pinning one.
+ */
+function newClient() {
+    const options = {
+        capabilities: {},
+        versionNegotiation: { mode: 'auto' },
+        listChanged: { tools: { autoRefresh: false, debounceMs: 0, onChanged: () => { } } },
+    };
+    return new Client({ name: 'dsh-mcp-oauth', version: '0.1.0' }, options);
+}
+/** Whether a connect failure is the server telling us to authenticate first. */
+function isUnauthorized(error) {
+    if (error === null || typeof error !== 'object')
+        return false;
+    const candidate = error;
+    if (candidate.code === 401 || candidate.status === 401)
+        return true;
+    if (candidate.name === 'UnauthorizedError')
+        return true;
+    return typeof candidate.message === 'string' && candidate.message.includes('401');
+}

package/lib/oauth.d.ts

@@ -0,0 +1,90 @@
+import type { OAuthClientProvider } from '@modelcontextprotocol/client';
+import type { ClientInformation, IssuerContext, TokenStore, Tokens } from './store.js';
+/** Everything the provider needs that the host configuration supplies. */
+export interface ProviderOptions {
+    /** MCP server namespace, used only for diagnostics. */
+    serverName: string;
+    /** Loopback redirect URI the SDK registers and the authorization server calls back. */
+    redirectUrl: string;
+    /** Store that persists the client registration, tokens and issuer keys. */
+    store: TokenStore;
+    /** Space-delimited scopes to request; empty lets the server decide. */
+    scope?: string | undefined;
+    /** Pre-registered client id (Slack and other non-DCR servers). */
+    clientId?: string | undefined;
+    /** Pre-registered client secret (confidential clients only). */
+    clientSecret?: string | undefined;
+    /** How the client authenticates at the token endpoint. */
+    tokenEndpointAuthMethod?: 'none' | 'client_secret_basic' | 'client_secret_post' | undefined;
+    /** Extra query parameters appended to the authorization URL (e.g. Slack `app_id`). */
+    authorizationParams?: Record<string, string> | undefined;
+    /** Diagnostics sink; the host logger. */
+    log?: ((message: string) => void) | undefined;
+}
+/**
+ * OAuth 2.0 client provider backed by the host's credential store.
+ *
+ * The MCP SDK owns discovery, DCR, PKCE, issuer validation and refresh; this
+ * class only answers "what do we know" and "where should the browser go".
+ * That split is what keeps the flow standard rather than per-vendor.
+ */
+export declare class DshOAuthProvider implements OAuthClientProvider {
+    #private;
+    readonly options: ProviderOptions;
+    constructor(options: ProviderOptions);
+    /** Loopback redirect URI, known before the first request so DCR can register it. */
+    get redirectUrl(): string;
+    /** Last authorization URL handed to the browser, for diagnostics and retries. */
+    get authorizationUrl(): URL | undefined;
+    get clientMetadata(): ReturnType<() => OAuthClientProvider['clientMetadata']>;
+    /** CSRF state for the authorization request; constant for one flow. */
+    state(): Promise<string>;
+    /** Pre-registered client wins over anything discovered through DCR. */
+    clientInformation(ctx?: IssuerContext): Promise<ClientInformation | undefined>;
+    /** Persist a DCR result; a pre-registered client is never overwritten. */
+    saveClientInformation(information: ClientInformation, ctx?: IssuerContext): Promise<void>;
+    tokens(ctx?: IssuerContext): Promise<Tokens | undefined>;
+    saveTokens(tokens: Tokens, ctx?: IssuerContext): Promise<void>;
+    saveCodeVerifier(codeVerifier: string): Promise<void>;
+    codeVerifier(): Promise<string>;
+    /** Append vendor-required parameters, then open the browser. */
+    redirectToAuthorization(authorizationUrl: URL): Promise<void>;
+}
+/** One authorization callback captured from the loopback listener. */
+export interface CallbackResult {
+    code: string;
+    iss?: string;
+    state?: string;
+}
+/**
+ * Single-use loopback listener for the OAuth redirect.
+ *
+ * Binds `127.0.0.1` on an ephemeral port so two servers (or two harness
+ * processes) never fight over a fixed callback port. A callback that arrives
+ * before anyone awaits is queued, not dropped.
+ */
+export declare class OAuthCallbackListener {
+    #private;
+    /** Redirect URI; only valid after {@link start}. */
+    get redirectUrl(): string;
+    /** Start listening and return the redirect URI to register. */
+    start(): Promise<string>;
+    /** Resolve with the next callback, or reject on timeout / listener failure. */
+    wait(timeoutMs?: number): Promise<CallbackResult>;
+    /** Stop listening; safe to call more than once. */
+    close(): void;
+}
+/**
+ * Drive the full interactive authorization flow for one server.
+ *
+ * First call runs discovery and either refreshes or redirects; when it
+ * redirected, the callback is awaited and exchanged for tokens. Idempotent:
+ * with a live token set it returns after the refresh check.
+ */
+export declare function ensureAuthorized(options: {
+    serverUrl: URL;
+    provider: DshOAuthProvider;
+    listener: OAuthCallbackListener;
+    timeoutMs?: number | undefined;
+    log?: ((message: string) => void) | undefined;
+}): Promise<void>;

package/lib/oauth.js

@@ -0,0 +1,247 @@
+import { randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import { auth } from '@modelcontextprotocol/client';
+import { openBrowser } from './browser.js';
+/**
+ * OAuth 2.0 client provider backed by the host's credential store.
+ *
+ * The MCP SDK owns discovery, DCR, PKCE, issuer validation and refresh; this
+ * class only answers "what do we know" and "where should the browser go".
+ * That split is what keeps the flow standard rather than per-vendor.
+ */
+export class DshOAuthProvider {
+    #codeVerifier;
+    #state;
+    #authorizationUrl;
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Loopback redirect URI, known before the first request so DCR can register it. */
+    get redirectUrl() {
+        return this.options.redirectUrl;
+    }
+    /** Last authorization URL handed to the browser, for diagnostics and retries. */
+    get authorizationUrl() {
+        return this.#authorizationUrl;
+    }
+    get clientMetadata() {
+        const confidential = Boolean(this.options.clientSecret);
+        const metadata = {
+            client_name: `DeepSeek Harness · ${this.options.serverName}`,
+            redirect_uris: [this.options.redirectUrl],
+            grant_types: ['authorization_code', 'refresh_token'],
+            response_types: ['code'],
+            token_endpoint_auth_method: this.options.tokenEndpointAuthMethod ?? (confidential ? 'client_secret_post' : 'none'),
+            ...(this.options.scope ? { scope: this.options.scope } : {}),
+        };
+        return metadata;
+    }
+    /** CSRF state for the authorization request; constant for one flow. */
+    async state() {
+        this.#state ??= randomBytes(32).toString('base64url');
+        return this.#state;
+    }
+    /** Pre-registered client wins over anything discovered through DCR. */
+    async clientInformation(ctx) {
+        const { clientId, clientSecret } = this.options;
+        if (clientId !== undefined && clientId.length > 0) {
+            const information = {
+                client_id: clientId,
+                token_endpoint_auth_method: this.clientMetadata.token_endpoint_auth_method,
+            };
+            if (clientSecret !== undefined && clientSecret.length > 0)
+                information.client_secret = clientSecret;
+            return information;
+        }
+        return this.options.store.client(ctx);
+    }
+    /** Persist a DCR result; a pre-registered client is never overwritten. */
+    async saveClientInformation(information, ctx) {
+        const { clientId } = this.options;
+        if (clientId !== undefined && clientId.length > 0)
+            return;
+        await this.options.store.putClient(ctx, information);
+    }
+    async tokens(ctx) {
+        return this.options.store.tokens(ctx);
+    }
+    async saveTokens(tokens, ctx) {
+        await this.options.store.putTokens(ctx, tokens);
+    }
+    async saveCodeVerifier(codeVerifier) {
+        this.#codeVerifier = codeVerifier;
+    }
+    async codeVerifier() {
+        if (this.#codeVerifier === undefined) {
+            throw new Error(`mcp-oauth(${this.options.serverName}): no PKCE verifier recorded — restart the authorization flow`);
+        }
+        return this.#codeVerifier;
+    }
+    /** Append vendor-required parameters, then open the browser. */
+    async redirectToAuthorization(authorizationUrl) {
+        const target = new URL(authorizationUrl.toString());
+        for (const [name, value] of Object.entries(this.options.authorizationParams ?? {})) {
+            if (value.length > 0)
+                target.searchParams.set(name, value);
+        }
+        this.#authorizationUrl = target;
+        this.options.log?.(`mcp-oauth(${this.options.serverName}): opening browser for authorization`);
+        openBrowser(target.toString());
+    }
+}
+/**
+ * Single-use loopback listener for the OAuth redirect.
+ *
+ * Binds `127.0.0.1` on an ephemeral port so two servers (or two harness
+ * processes) never fight over a fixed callback port. A callback that arrives
+ * before anyone awaits is queued, not dropped.
+ */
+export class OAuthCallbackListener {
+    #server;
+    #port = 0;
+    #queued;
+    #pending;
+    /** Redirect URI; only valid after {@link start}. */
+    get redirectUrl() {
+        return `http://127.0.0.1:${this.#port}/callback`;
+    }
+    /** Start listening and return the redirect URI to register. */
+    async start() {
+        if (this.#server !== undefined)
+            return this.redirectUrl;
+        const server = createServer((request, response) => {
+            const url = new URL(request.url ?? '/', `http://127.0.0.1:${this.#port}`);
+            if (url.pathname !== '/callback') {
+                respond(response, 404, 'Not found');
+                return;
+            }
+            const error = url.searchParams.get('error');
+            if (error !== null) {
+                const description = url.searchParams.get('error_description') ?? '';
+                respond(response, 400, `Authorization failed: ${error} ${description}`);
+                this.#settle(new Error(`authorization failed: ${error} ${description}`.trim()));
+                return;
+            }
+            const code = url.searchParams.get('code');
+            if (code === null || code.length === 0) {
+                respond(response, 400, 'Missing authorization code');
+                this.#settle(new Error('authorization callback carried no code'));
+                return;
+            }
+            const result = {
+                code,
+                ...(url.searchParams.get('iss') !== null ? { iss: url.searchParams.get('iss') } : {}),
+                ...(url.searchParams.get('state') !== null ? { state: url.searchParams.get('state') } : {}),
+            };
+            respond(response, 200, '授权完成，可以关闭这个页面并回到 DeepSeek Harness。');
+            this.#settle(result);
+        });
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(0, '127.0.0.1', () => {
+                server.off('error', reject);
+                resolve();
+            });
+        });
+        const address = server.address();
+        this.#port = typeof address === 'object' && address !== null ? address.port : 0;
+        if (this.#port === 0) {
+            server.close();
+            throw new Error('mcp-oauth: loopback listener bound to port 0');
+        }
+        this.#server = server;
+        return this.redirectUrl;
+    }
+    /** Resolve with the next callback, or reject on timeout / listener failure. */
+    wait(timeoutMs = 300_000) {
+        if (this.#queued !== undefined) {
+            const queued = this.#queued;
+            this.#queued = undefined;
+            return Promise.resolve(queued);
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#pending = undefined;
+                reject(new Error(`mcp-oauth: authorization callback timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            timer.unref?.();
+            this.#pending = {
+                resolve: (result) => {
+                    clearTimeout(timer);
+                    this.#pending = undefined;
+                    resolve(result);
+                },
+                reject: (error) => {
+                    clearTimeout(timer);
+                    this.#pending = undefined;
+                    reject(error);
+                },
+            };
+        });
+    }
+    /** Stop listening; safe to call more than once. */
+    close() {
+        this.#pending?.reject(new Error('mcp-oauth: authorization listener closed'));
+        this.#pending = undefined;
+        const server = this.#server;
+        this.#server = undefined;
+        server?.close();
+    }
+    #settle(result) {
+        if (this.#pending === undefined) {
+            if (result instanceof Error)
+                return;
+            this.#queued = result;
+            return;
+        }
+        if (result instanceof Error)
+            this.#pending.reject(result);
+        else
+            this.#pending.resolve(result);
+    }
+}
+function respond(response, status, message) {
+    const body = `<!doctype html><meta charset="utf-8"><title>DeepSeek Harness</title><p>${escapeHtml(message)}</p>`;
+    response.writeHead(status, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
+    response.end(body);
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (character) => character === '&' ? '&amp;' : character === '<' ? '&lt;' : character === '>' ? '&gt;' : character === '"' ? '&quot;' : '&#39;');
+}
+/**
+ * Drive the full interactive authorization flow for one server.
+ *
+ * First call runs discovery and either refreshes or redirects; when it
+ * redirected, the callback is awaited and exchanged for tokens. Idempotent:
+ * with a live token set it returns after the refresh check.
+ */
+export async function ensureAuthorized(options) {
+    const { serverUrl, provider, listener } = options;
+    const log = options.log ?? (() => { });
+    log(`mcp-oauth(${provider.options.serverName}): starting authorization for ${serverUrl.toString()}`);
+    await auth(provider, { serverUrl: serverUrl.toString() });
+    if (await provider.tokens()) {
+        log(`mcp-oauth(${provider.options.serverName}): authorization refreshed without user interaction`);
+        return;
+    }
+    const authorizationUrl = provider.authorizationUrl;
+    if (authorizationUrl !== undefined)
+        log(`mcp-oauth(${provider.options.serverName}): authorize at ${authorizationUrl.toString()}`);
+    const callback = await listener.wait(options.timeoutMs);
+    if (callback.state !== undefined) {
+        const expected = await provider.state();
+        if (callback.state !== expected) {
+            throw new Error(`mcp-oauth(${provider.options.serverName}): state mismatch on authorization callback`);
+        }
+    }
+    await auth(provider, {
+        serverUrl: serverUrl.toString(),
+        authorizationCode: callback.code,
+        ...(callback.iss !== undefined ? { iss: callback.iss } : {}),
+    });
+    if (!(await provider.tokens())) {
+        throw new Error(`mcp-oauth(${provider.options.serverName}): authorization finished without tokens`);
+    }
+    log(`mcp-oauth(${provider.options.serverName}): authorized`);
+}

package/lib/store.d.ts

@@ -0,0 +1,43 @@
+import type { OAuthClientProvider } from '@modelcontextprotocol/client';
+/** Token set as the MCP SDK's provider interface describes it. */
+export type Tokens = NonNullable<Awaited<ReturnType<OAuthClientProvider['tokens']>>>;
+/** Registered-client information as the MCP SDK's provider interface describes it. */
+export type ClientInformation = NonNullable<Awaited<ReturnType<OAuthClientProvider['clientInformation']>>>;
+/** Per-authorization-server context the SDK passes to credential callbacks. */
+export type IssuerContext = Parameters<OAuthClientProvider['tokens']>[0];
+/**
+ * Root of the DeepSeek Harness installation that owns this process.
+ *
+ * Matches the host's own convention so a plugin running under the desktop app
+ * and one running under the CLI resolve to the same directory.
+ */
+export declare function dshHome(): string;
+/**
+ * Persistent OAuth credentials for one MCP server.
+ *
+ * One JSON document per server under `$DSH_HOME/mcp-oauth/`, written atomically
+ * and chmod 0600. Entries are keyed by authorization-server issuer so a server
+ * that moves between issuers never replays a token against the wrong one
+ * (RFC 9207 mix-up defense).
+ */
+export declare class TokenStore {
+    #private;
+    /** Absolute path of the backing file; surfaced in logs so users can find it. */
+    readonly file: string;
+    constructor(serverName: string);
+    /** Stored client registration for an issuer, or `undefined` when unregistered. */
+    client(ctx?: IssuerContext): Promise<ClientInformation | undefined>;
+    /** Persist a dynamically registered client and remember it as the latest issuer. */
+    putClient(ctx: IssuerContext | undefined, client: ClientInformation): Promise<void>;
+    /**
+     * Tokens for an issuer, or the most recently saved set when the SDK asks
+     * without context (its per-request bearer-token read).
+     */
+    tokens(ctx?: IssuerContext): Promise<Tokens | undefined>;
+    /** Persist a token set for an issuer. */
+    putTokens(ctx: IssuerContext | undefined, tokens: Tokens): Promise<void>;
+    /** Drop every stored credential for this server (used by the logout path). */
+    clear(): Promise<void>;
+    /** Whether a token set exists, without loading the token values. */
+    hasTokens(): Promise<boolean>;
+}

package/lib/store.js

@@ -0,0 +1,115 @@
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** Key used when the SDK asks for tokens without naming an authorization server. */
+const LAST_ISSUER = '*';
+/**
+ * Root of the DeepSeek Harness installation that owns this process.
+ *
+ * Matches the host's own convention so a plugin running under the desktop app
+ * and one running under the CLI resolve to the same directory.
+ */
+export function dshHome() {
+    const configured = process.env.DSH_HOME?.trim();
+    return configured && configured.length > 0 ? configured : join(homedir(), '.dsh');
+}
+/**
+ * Persistent OAuth credentials for one MCP server.
+ *
+ * One JSON document per server under `$DSH_HOME/mcp-oauth/`, written atomically
+ * and chmod 0600. Entries are keyed by authorization-server issuer so a server
+ * that moves between issuers never replays a token against the wrong one
+ * (RFC 9207 mix-up defense).
+ */
+export class TokenStore {
+    /** Absolute path of the backing file; surfaced in logs so users can find it. */
+    file;
+    #state;
+    constructor(serverName) {
+        this.file = join(dshHome(), 'mcp-oauth', `${serverName}.json`);
+    }
+    async #load() {
+        if (this.#state !== undefined)
+            return this.#state;
+        try {
+            const raw = JSON.parse(await readFile(this.file, 'utf8'));
+            this.#state = {
+                version: 1,
+                ...(typeof raw.lastIssuer === 'string' ? { lastIssuer: raw.lastIssuer } : {}),
+                issuers: raw.issuers ?? {},
+            };
+        }
+        catch {
+            this.#state = { version: 1, issuers: {} };
+        }
+        return this.#state;
+    }
+    #key(ctx) {
+        return ctx?.issuer && ctx.issuer.length > 0 ? ctx.issuer : LAST_ISSUER;
+    }
+    async #flush() {
+        const state = await this.#load();
+        await mkdir(dirname(this.file), { recursive: true });
+        const temporary = `${this.file}.${process.pid}.tmp`;
+        await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, {
+            encoding: 'utf8',
+            mode: 0o600,
+        });
+        await rename(temporary, this.file);
+        if (process.platform !== 'win32')
+            await chmod(this.file, 0o600).catch(() => { });
+    }
+    /** Stored client registration for an issuer, or `undefined` when unregistered. */
+    async client(ctx) {
+        const state = await this.#load();
+        const entry = state.issuers[this.#key(ctx)];
+        return entry?.client;
+    }
+    /** Persist a dynamically registered client and remember it as the latest issuer. */
+    async putClient(ctx, client) {
+        const state = await this.#load();
+        const key = this.#key(ctx);
+        state.issuers[key] = { ...state.issuers[key], client };
+        if (key !== LAST_ISSUER)
+            state.lastIssuer = key;
+        await this.#flush();
+    }
+    /**
+     * Tokens for an issuer, or the most recently saved set when the SDK asks
+     * without context (its per-request bearer-token read).
+     */
+    async tokens(ctx) {
+        const state = await this.#load();
+        const direct = state.issuers[this.#key(ctx)]?.tokens;
+        if (direct !== undefined)
+            return direct;
+        if (ctx?.issuer)
+            return undefined;
+        const latest = state.lastIssuer !== undefined ? state.issuers[state.lastIssuer]?.tokens : undefined;
+        if (latest !== undefined)
+            return latest;
+        for (const entry of Object.values(state.issuers)) {
+            if (entry.tokens !== undefined)
+                return entry.tokens;
+        }
+        return undefined;
+    }
+    /** Persist a token set for an issuer. */
+    async putTokens(ctx, tokens) {
+        const state = await this.#load();
+        const key = this.#key(ctx);
+        state.issuers[key] = { ...state.issuers[key], tokens };
+        if (key !== LAST_ISSUER)
+            state.lastIssuer = key;
+        await this.#flush();
+    }
+    /** Drop every stored credential for this server (used by the logout path). */
+    async clear() {
+        this.#state = { version: 1, issuers: {} };
+        await this.#flush();
+    }
+    /** Whether a token set exists, without loading the token values. */
+    async hasTokens() {
+        return (await this.tokens()) !== undefined;
+    }
+}

package/lib/tools.d.ts

@@ -0,0 +1,60 @@
+/** Logger surface the host exposes to plugins. */
+export interface PluginLogger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+/** The subset of the Cordis plugin context this bridge depends on. */
+export interface PluginContext {
+    tools: {
+        register(definition: unknown): () => void;
+    };
+    logger: PluginLogger;
+    effect(callback: () => (() => void) | void, label?: string): unknown;
+}
+/**
+ * Public tool name for one upstream tool: `mcp__<server>__<tool>`.
+ *
+ * Mirrors the host bridge's naming so permission rules, transcripts and
+ * allowlists written for the built-in client keep working unchanged. Over-long
+ * names collapse to a truncated form plus a stable hash.
+ */
+export declare function publicToolName(serverName: string, rawName: string): string;
+/** The connected MCP client as far as this bridge needs to see it. */
+interface McpClientLike {
+    getServerCapabilities(): {
+        tools?: unknown;
+    } | undefined;
+    listTools(params: undefined, options: {
+        cacheMode: 'refresh';
+    }): Promise<{
+        tools: readonly McpToolLike[];
+    }>;
+    callTool(request: {
+        name: string;
+        arguments: Record<string, unknown>;
+    }, options: Record<string, unknown>): Promise<unknown>;
+}
+interface McpToolLike {
+    name: string;
+    description?: string | undefined;
+    inputSchema: unknown;
+    outputSchema?: unknown;
+    execution?: {
+        taskSupport?: string | undefined;
+    } | undefined;
+}
+export interface SyncOptions {
+    serverName: string;
+    toolCallTimeoutMs: number;
+}
+/**
+ * Publish one MCP server's tool list on `ctx.tools`.
+ *
+ * Fetch first, swap second: a failed discovery leaves the previous generation
+ * registered instead of half-replacing it.
+ *
+ * @returns number of tools registered for this server.
+ */
+export declare function syncTools(client: McpClientLike, ctx: PluginContext, options: SyncOptions, live: Map<string, () => void>): Promise<number>;
+export {};

package/lib/tools.js

@@ -0,0 +1,68 @@
+import { createHash } from 'node:crypto';
+import { createMcpToolDefinition } from '@deepseek-ai/dsh-mcp-client';
+/** Budget for the public tool name, matching the host bridge's convention. */
+const MAX_PUBLIC_NAME_LENGTH = 64;
+const HASH_LENGTH = 8;
+/**
+ * Public tool name for one upstream tool: `mcp__<server>__<tool>`.
+ *
+ * Mirrors the host bridge's naming so permission rules, transcripts and
+ * allowlists written for the built-in client keep working unchanged. Over-long
+ * names collapse to a truncated form plus a stable hash.
+ */
+export function publicToolName(serverName, rawName) {
+    const sanitized = rawName.replace(/[^A-Za-z0-9_-]+/g, '_');
+    const full = `mcp__${serverName}__${sanitized}`;
+    if (full.length <= MAX_PUBLIC_NAME_LENGTH)
+        return full;
+    const digest = createHash('sha256').update(`${serverName}\u0000${rawName}`).digest('hex').slice(0, HASH_LENGTH);
+    return `${full.slice(0, MAX_PUBLIC_NAME_LENGTH - HASH_LENGTH - 1)}_${digest}`;
+}
+/**
+ * Publish one MCP server's tool list on `ctx.tools`.
+ *
+ * Fetch first, swap second: a failed discovery leaves the previous generation
+ * registered instead of half-replacing it.
+ *
+ * @returns number of tools registered for this server.
+ */
+export async function syncTools(client, ctx, options, live) {
+    const capabilities = client.getServerCapabilities();
+    const response = capabilities?.tools === undefined
+        ? { tools: [] }
+        : await client.listTools(undefined, { cacheMode: 'refresh' });
+    const definitions = new Map();
+    for (const tool of response.tools) {
+        const name = publicToolName(options.serverName, tool.name);
+        if (definitions.has(name)) {
+            throw new Error(`mcp-oauth(${options.serverName}): server listed tool "${tool.name}" more than once — invalid tool list`);
+        }
+        definitions.set(name, createMcpToolDefinition(ctx, {
+            name,
+            rawName: tool.name,
+            description: tool.description ?? '',
+            inputSchema: tool.inputSchema,
+            outputSchema: tool.outputSchema,
+            taskRequired: tool.execution?.taskSupport === 'required',
+            call: (args, execution) => client.callTool({ name: tool.name, arguments: args }, { signal: execution.signal, timeout: options.toolCallTimeoutMs, toolDefinition: tool }),
+        }));
+    }
+    for (const dispose of live.values())
+        dispose();
+    live.clear();
+    const registered = new Map();
+    try {
+        for (const [name, definition] of definitions) {
+            registered.set(name, ctx.tools.register(definition));
+        }
+    }
+    catch (error) {
+        for (const dispose of registered.values())
+            dispose();
+        ctx.logger.error(`mcp-oauth(${options.serverName}): tool registration failed, no tools registered: ${String(error)}`);
+        throw error;
+    }
+    for (const [name, dispose] of registered)
+        live.set(name, dispose);
+    return registered.size;
+}

package/lib/transport.d.ts

@@ -0,0 +1,29 @@
+import type { DshOAuthProvider } from './oauth.js';
+/** Remote transport: streamable HTTP, optionally OAuth or static headers. */
+export interface RemoteTransportSpec {
+    transport: 'streamable-http';
+    url: string;
+    headers?: Record<string, string> | undefined;
+    authProvider?: DshOAuthProvider | undefined;
+}
+/** Local transport: an MCP server spawned as a child process. */
+export interface StdioTransportSpec {
+    transport: 'stdio';
+    command: string;
+    args?: string[] | undefined;
+    env?: Record<string, string> | undefined;
+    cwd?: string | undefined;
+}
+export type TransportSpec = RemoteTransportSpec | StdioTransportSpec;
+/**
+ * Child environment for a stdio server: the scrubbed parent environment plus
+ * whatever the plugin configuration passes explicitly.
+ *
+ * Credential-shaped names are dropped deliberately — the host does the same for
+ * its own MCP children, and silently forwarding them would make a plugin a
+ * privilege-escalation path. Pass secrets as command arguments instead, or name
+ * them explicitly in `env`.
+ */
+export declare function buildChildEnv(extra: Record<string, string> | undefined): Record<string, string>;
+/** Build the transport for one configured server. */
+export declare function createTransport(spec: TransportSpec): unknown;

package/lib/transport.js

@@ -0,0 +1,42 @@
+import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+/** Names the host strips from a child environment; mirrored so behaviour matches. */
+const CREDENTIAL_SHAPED = /KEY|PASSWORD|SECRET|TOKEN/i;
+/**
+ * Child environment for a stdio server: the scrubbed parent environment plus
+ * whatever the plugin configuration passes explicitly.
+ *
+ * Credential-shaped names are dropped deliberately — the host does the same for
+ * its own MCP children, and silently forwarding them would make a plugin a
+ * privilege-escalation path. Pass secrets as command arguments instead, or name
+ * them explicitly in `env`.
+ */
+export function buildChildEnv(extra) {
+    const environment = {};
+    for (const [name, value] of Object.entries(process.env)) {
+        if (value === undefined)
+            continue;
+        if (CREDENTIAL_SHAPED.test(name) || name.startsWith('DSH_'))
+            continue;
+        environment[name] = value;
+    }
+    return { ...environment, ...(extra ?? {}) };
+}
+/** Build the transport for one configured server. */
+export function createTransport(spec) {
+    if (spec.transport === 'stdio') {
+        return new StdioClientTransport({
+            command: spec.command,
+            args: spec.args ?? [],
+            env: buildChildEnv(spec.env),
+            ...(spec.cwd !== undefined && spec.cwd.length > 0 ? { cwd: spec.cwd } : {}),
+        });
+    }
+    const options = {};
+    if (spec.authProvider !== undefined)
+        options.authProvider = spec.authProvider;
+    const headers = spec.headers ?? {};
+    if (Object.keys(headers).length > 0)
+        options.requestInit = { headers };
+    return new StreamableHTTPClientTransport(new URL(spec.url), options);
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@plaudai/dsh-mcp-oauth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "MCP bridge for DeepSeek Harness with a built-in OAuth 2.0 client (DCR + PKCE), bearer-header and stdio transports",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-mcp-client": "^0.2.0-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@modelcontextprotocol/client": "^2.0.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "mcp",
+    "oauth"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.