mouaif 0.3.0

package/src/oauth-mcp.js

@@ -0,0 +1,216 @@
+'use strict';
+
+// MCP OAuth is independent of AI-provider accounts. Credentials are scoped to
+// the saved server identity and stored only in the OS keychain.
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { Entry } = require('@napi-rs/keyring');
+const CALLBACK_PATH = '/oauth/mcp/callback';
+const PENDING_TTL = 10 * 60 * 1000;
+const error = (code, message) => Object.assign(new Error(message), { code });
+
+function identity({ entry, scope, projectDir }) {
+  let project = scope === 'app' ? 'app' : path.resolve(projectDir);
+  if (scope !== 'app') { try { project = fs.realpathSync(project); } catch { /* not yet created */ } }
+  return crypto.createHash('sha256').update(JSON.stringify([
+    project, entry.id, entry.url, entry.oauth || null
+  ])).digest('hex');
+}
+
+function safeUrl(value) {
+  const url = new URL(value);
+  if (url.username || url.password || !['http:', 'https:'].includes(url.protocol)) {
+    throw error('EBADINPUT', 'OAuth URLs must be HTTP(S) URLs without credentials.');
+  }
+  if (url.protocol !== 'https:' && !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) {
+    throw error('EBADINPUT', 'OAuth requires HTTPS (HTTP is allowed only on loopback).');
+  }
+  return url;
+}
+
+const vault = {
+  read(key) {
+    try {
+      const text = new Entry('mouaif/mcp-oauth', key).getPassword();
+      return text ? JSON.parse(text) : {};
+    } catch (e) {
+      if (/no matching entry|not found|No such file/i.test(e.message || '')) return {};
+      throw error('EKEYRING', 'MCP OAuth needs an available OS keychain.');
+    }
+  },
+  write(key, value) {
+    try { new Entry('mouaif/mcp-oauth', key).setPassword(JSON.stringify(value)); }
+    catch { throw error('EKEYRING', 'Could not save MCP OAuth credentials in the OS keychain.'); }
+  },
+  remove(key) {
+    try { new Entry('mouaif/mcp-oauth', key).deletePassword(); }
+    catch (e) {
+      if (!/no matching entry|not found|No such file/i.test(e.message || '')) {
+        throw error('EKEYRING', 'Could not remove MCP OAuth credentials from the OS keychain.');
+      }
+    }
+  }
+};
+
+// Never follow redirects carrying OAuth credentials. Enforce TLS for discovered
+// endpoints too, not just the configured MCP URL. Bound every network request.
+async function oauthFetch(input, init = {}) {
+  safeUrl(typeof input === 'string' || input instanceof URL ? input : input.url);
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  if (init.signal?.aborted) abort();
+  init.signal?.addEventListener('abort', abort, { once: true });
+  const timer = setTimeout(abort, 30000);
+  try { return await fetch(input, { ...init, redirect: 'error', signal: controller.signal }); }
+  finally { clearTimeout(timer); init.signal?.removeEventListener('abort', abort); }
+}
+
+function createManager({ storage = vault, resolveContext } = {}) {
+  const pending = new Map();
+  const generations = new Map();
+  function prune() {
+    for (const [state, item] of pending) if (item.expiresAt <= Date.now()) pending.delete(state);
+  }
+  function cancel(key) {
+    generations.set(key, (generations.get(key) || 0) + 1);
+    for (const [state, item] of pending) if (item.key === key) pending.delete(state);
+  }
+  function checkContext(context) {
+    if (context.entry.transport !== 'http' || !context.entry.oauth?.enabled) {
+      throw error('EBADINPUT', 'Save this HTTP server with OAuth enabled first.');
+    }
+    safeUrl(context.entry.url);
+  }
+  function provider(context, flow) {
+    checkContext(context);
+    const key = identity(context);
+    const generation = flow ? flow.generation : (generations.get(key) || 0);
+    function active() {
+      const current = resolveContext(context.projectDir, context.entry.id);
+      if (!current || identity(current) !== key || generation !== (generations.get(key) || 0) || (flow && flow.expiresAt <= Date.now())) {
+        throw error('EMCP_AUTH', 'Sign-in was cancelled or expired. Start again.');
+      }
+    }
+    function read() { active(); return storage.read(key) || {}; }
+    function update(patch) { storage.write(key, { ...read(), ...patch }); }
+    const saved = read();
+    const redirectUrl = flow?.redirectUrl || saved.redirectUrl;
+    if (!redirectUrl) throw error('EMCP_AUTH', 'Sign in to this MCP server in Settings first.');
+    const configuredClient = context.entry.oauth.clientId;
+    return {
+      redirectUrl,
+      clientMetadata: {
+        client_name: 'mouaif', redirect_uris: [redirectUrl],
+        grant_types: ['authorization_code', 'refresh_token'], response_types: ['code'],
+        token_endpoint_auth_method: 'none',
+        ...(context.entry.oauth.scope ? { scope: context.entry.oauth.scope } : {})
+      },
+      state() {
+        active();
+        if (!flow) throw error('EMCP_AUTH', 'MCP authorization expired. Sign in again in Settings.');
+        return flow.state;
+      },
+      clientInformation: () => configuredClient ? { client_id: configuredClient } : read().client,
+      saveClientInformation: (client) => update({ client }),
+      tokens: () => read().tokens,
+      saveTokens(tokens) {
+        const previous = read().tokens;
+        update({ tokens: { ...tokens, ...(tokens.refresh_token ? {} : previous?.refresh_token ? { refresh_token: previous.refresh_token } : {}) }, redirectUrl });
+      },
+      saveCodeVerifier(verifier) {
+        active();
+        if (!flow) throw error('EMCP_AUTH', 'Sign in again in Settings.');
+        flow.verifier = verifier;
+      },
+      codeVerifier() {
+        active();
+        if (!flow?.verifier) throw error('EMCP_AUTH', 'Sign-in expired. Start again.');
+        return flow.verifier;
+      },
+      redirectToAuthorization(url) {
+        active();
+        if (!flow) throw error('EMCP_AUTH', 'Sign in again in Settings.');
+        flow.authorizationUrl = safeUrl(url).href;
+      },
+      discoveryState: () => flow?.discovery,
+      saveDiscoveryState: (discovery) => { if (flow) flow.discovery = discovery; },
+      invalidateCredentials(scope) {
+        if (scope === 'all') update({ client: undefined, tokens: undefined });
+        else if (scope === 'client') update({ client: undefined });
+        else if (scope === 'tokens') update({ tokens: undefined });
+        if (flow && (scope === 'all' || scope === 'verifier')) flow.verifier = undefined;
+        if (flow && (scope === 'all' || scope === 'discovery')) flow.discovery = undefined;
+      }
+    };
+  }
+  async function begin(context, origin) {
+    checkContext(context);
+    prune();
+    if (pending.size >= 100) throw error('EMCP_AUTH', 'Too many pending sign-ins. Try again later.');
+    const key = identity(context);
+    cancel(key);
+    const redirectUrl = new URL(CALLBACK_PATH, safeUrl(origin)).href;
+    const saved = storage.read(key) || {};
+    // A dynamically registered client is bound to its original redirect URI.
+    storage.write(key, { ...saved, tokens: undefined, redirectUrl,
+      client: saved.redirectUrl === redirectUrl ? saved.client : undefined });
+    const state = crypto.randomBytes(32).toString('base64url');
+    const flow = { key, state, context, redirectUrl, generation: generations.get(key), expiresAt: Date.now() + PENDING_TTL };
+    pending.set(state, flow);
+    try {
+      const { auth, extractWWWAuthenticateParams } = require('@modelcontextprotocol/sdk/client/auth.js');
+      // Some servers advertise protected-resource metadata only through the
+      // challenge rather than a conventional well-known path. Probe without
+      // tokens or custom headers; GET is safe and a 405 still permits discovery.
+      const probe = await oauthFetch(context.entry.url, { headers: { Accept: 'application/json, text/event-stream' } });
+      const challenge = extractWWWAuthenticateParams(probe);
+      await probe.body?.cancel();
+      const result = await auth(provider(context, flow), {
+        serverUrl: context.entry.url, fetchFn: oauthFetch,
+        resourceMetadataUrl: challenge.resourceMetadataUrl, scope: challenge.scope
+      });
+      if (result !== 'REDIRECT' || !flow.authorizationUrl) throw error('EMCP_AUTH', 'Server did not provide an OAuth sign-in URL.');
+      return { authorizationUrl: flow.authorizationUrl, redirectUrl, expiresAt: flow.expiresAt };
+    } catch (e) {
+      pending.delete(state);
+      if (e.code === 'EKEYRING' || e.code === 'EBADINPUT') throw e;
+      // SDK errors may contain raw upstream response bodies (including secrets).
+      throw error('EMCP_AUTH', 'Could not start OAuth. Check server OAuth support and the client ID/redirect URI.');
+    }
+  }
+  async function finish(state, code, denied) {
+    prune();
+    const flow = typeof state === 'string' && pending.get(state);
+    if (!flow) throw error('EMCP_AUTH', 'Unknown, expired, or already used sign-in. Start again in Settings.');
+    pending.delete(state); // one-shot, including provider denials and failed exchanges
+    if (denied) throw error('EMCP_AUTH', 'Sign-in was declined. You can try again in Settings.');
+    if (typeof code !== 'string' || !code || code.length > 8192) throw error('EBADINPUT', 'Missing or invalid authorization code.');
+    const current = resolveContext(flow.context.projectDir, flow.context.entry.id);
+    if (!current || identity(current) !== flow.key) throw error('EMCP_AUTH', 'Server configuration changed. Start sign-in again.');
+    try {
+      const { auth } = require('@modelcontextprotocol/sdk/client/auth.js');
+      await auth(provider(current, flow), { serverUrl: current.entry.url, authorizationCode: code, fetchFn: oauthFetch });
+      return { ok: true };
+    } catch (e) {
+      if (e.code === 'EKEYRING') throw e;
+      throw error('EMCP_AUTH', 'OAuth exchange failed. Start sign-in again and check the server configuration.');
+    }
+  }
+  function status(context) {
+    checkContext(context);
+    prune();
+    const key = identity(context);
+    const saved = storage.read(key) || {};
+    return { connected: !!saved.tokens?.access_token, pending: [...pending.values()].some(item => item.key === key), redirectUrl: saved.redirectUrl || null };
+  }
+  function clear(context) {
+    const key = identity(context);
+    cancel(key);
+    storage.remove(key);
+  }
+  return { begin, finish, provider, status, clear };
+}
+
+const manager = createManager({ resolveContext: (dir, id) => require('./mcp.js').getOAuthContext(dir, id) });
+module.exports = { ...manager, createManager, identity, safeUrl, oauthFetch, CALLBACK_PATH };

package/src/oauth-openrouter.js

@@ -0,0 +1,285 @@
+'use strict';
+
+// OpenRouter OAuth (PKCE) — the per-provider sign-in flow for the
+// `openrouter` AI client provider.
+//
+// Implements docs/decisions.md section 12 (one provider per commit).
+// This module registers an exchange function with src/auth.js that
+// is invoked from the loopback callback (`/oauth/callback`) after the
+// user authorises the app in their browser.
+//
+// OpenRouter's flow is a pure PKCE exchange — there is no client_id
+// or client_secret to register, no separate app dashboard for a
+// per-install app, and no refresh tokens. The shape mirrors
+// https://openrouter.ai/docs/guides/overview/auth/oauth:
+//
+//   1. The mobile UI opens
+//        https://openrouter.ai/auth?callback_url=<our-loopback>&code_challenge=<sha256(verifier)>&code_challenge_method=S256
+//      in the user's browser. The user signs in to OpenRouter and
+//      grants the requested scope (none — the PKCE flow does not
+//      pass a `scope` parameter; OpenRouter grants "manage your own
+//      API keys" by default).
+//
+//   2. OpenRouter redirects the user's browser back to our loopback
+//      URL with a one-time `code` query parameter.
+//
+//   3. Our server POSTs
+//        https://openrouter.ai/api/v1/auth/keys
+//      with `{ code, code_verifier, code_challenge_method: 'S256' }`
+//      and receives `{ key }` — a user-controlled OpenRouter API
+//      key. The key is what `Authorization: Bearer <key>` expects on
+//      every chat-completions call. The mobile UI then uses that key
+//      exactly the way a manually pasted key is used; from the AI
+//      client's perspective there is no OAuth token, just an OpenRouter
+//      API key whose origin happens to be a sign-in.
+//
+// Storage: the keychain holds the API key as the `accessToken` field
+// of a standard OAuth blob, plus `expiresAt: null` and
+// `refreshToken: null`. The `account` slot is the key's first 16
+// chars (`sk-or-v1-xxxxxxxx...`) so the UI picker can show one row
+// per signed-in key without leaking the full secret.
+//
+// Refresh: OpenRouter does not issue refresh tokens. A leaked or
+// revoked key is irrecoverable — the user signs in again, which
+// issues a new key. The refresher registered with auth.registerRefresher
+// is therefore a no-op (it returns the existing blob verbatim with
+// `expiresAt: null` so the AI client's proactive-refresh code path is
+// a clean no-op rather than a typed error).
+//
+// Public surface:
+//
+//   const oauthOpenRouter = require('mouaif/src/oauth-openrouter.js');
+//
+//   oauthOpenRouter.register();  // call once at server startup
+//   oauthOpenRouter.buildAuthorizeUrl({ callbackUrl, state, verifier });
+//   await oauthOpenRouter.exchangeAuthorizationCode({ code, verifier, callbackUrl });
+//   // Internal — the AI client uses the key as a plain Bearer token;
+//   //   src/ai.js does not need any per-provider helper for OpenRouter.
+
+const crypto = require('crypto');
+const auth = require('./auth.js');
+
+// OpenRouter's PKCE endpoints. Documented at
+// https://openrouter.ai/docs/guides/overview/auth/oauth. Both are
+// public; there is no per-app identity, so no client_id constant
+// exists in this module.
+const AUTHORIZE_URL = 'https://openrouter.ai/auth';
+const KEYS_URL = 'https://openrouter.ai/api/v1/auth/keys';
+
+function randomUrlSafe(n) {
+  return crypto.randomBytes(n).toString('base64url');
+}
+
+function pkceChallengeS256(verifier) {
+  return crypto.createHash('sha256').update(verifier).digest('base64url');
+}
+
+// Public — stable helpers used by the mobile UI and tests.
+function newState() { return randomUrlSafe(32); }
+function newVerifier() { return randomUrlSafe(64); }
+function challengeFor(verifier) { return pkceChallengeS256(verifier); }
+
+// Build the /auth URL the user's browser should open. Pure: takes the
+// loopback URL + state + verifier and returns a fully-formed URL
+// string. The mobile UI uses this; the server's handleOAuthCallback
+// is the one that does the *exchange*.
+//
+// `callbackUrl` is the loopback URL (e.g. http://127.0.0.1:5732/oauth/callback?provider=openrouter).
+// We pass it through as the `callback_url` query param verbatim —
+// OpenRouter echoes it back on the redirect so the resulting `code`
+// arrives at the same handler the Anthropic / GitHub flows use.
+function buildAuthorizeUrl(opts) {
+  const {
+    callbackUrl,
+    state,
+    verifier,
+    codeChallengeMethod = 'S256'
+  } = opts || {};
+
+  if (!callbackUrl) throw new Error('callbackUrl is required');
+  if (!state) throw new Error('state is required');
+  if (!verifier) throw new Error('verifier is required');
+  if (codeChallengeMethod !== 'S256' && codeChallengeMethod !== 'plain') {
+    throw new Error('codeChallengeMethod must be "S256" or "plain"');
+  }
+
+  const u = new URL(AUTHORIZE_URL);
+  u.searchParams.set('callback_url', callbackUrl);
+  u.searchParams.set('code_challenge', pkceChallengeS256(verifier));
+  u.searchParams.set('code_challenge_method', codeChallengeMethod);
+  // `state` is forwarded so the loopback handler can match the
+  // callback to a pending record. OpenRouter echoes it back on the
+  // redirect.
+  u.searchParams.set('state', state);
+  return u.toString();
+}
+
+// POST the authorization_code grant. Per OpenRouter's docs, the
+// exchange endpoint accepts application/json with the `code`,
+// `code_verifier`, and `code_challenge_method` fields. Response is
+// `{ key }` — a user-controlled OpenRouter API key.
+async function exchangeAuthorizationCode(opts) {
+  const {
+    keysUrl = KEYS_URL,
+    code,
+    verifier,
+    codeChallengeMethod = 'S256',
+    fetchImpl = globalThis.fetch
+  } = opts || {};
+
+  if (!code) throw new Error('code is required');
+  if (!verifier) throw new Error('verifier is required');
+  if (typeof fetchImpl !== 'function') throw new Error('global fetch is not available');
+
+  const res = await fetchImpl(keysUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      code,
+      code_verifier: verifier,
+      code_challenge_method: codeChallengeMethod
+    })
+  });
+  return readKeyResponse(res);
+}
+
+async function readKeyResponse(res) {
+  const text = await res.text().catch(() => '');
+  if (!res.ok) {
+    let parsed = null;
+    try { parsed = JSON.parse(text); } catch { /* not JSON */ }
+    if (parsed && parsed.error) {
+      // OpenRouter returns `{ error: { message, code } }` for a
+      // rejected sign-in. Older OAuth-style errors would carry the
+      // standard `error` string + `error_description`; we handle both.
+      const errObj = parsed.error;
+      const errMsg = (errObj && typeof errObj === 'object' && errObj.message)
+        ? errObj.message
+        : (typeof errObj === 'string' ? errObj : JSON.stringify(errObj));
+      const e = new Error('OpenRouter sign-in: ' + errMsg + (parsed.error_description ? ' (' + parsed.error_description + ')' : ''));
+      e.code = 'EOAUTH';
+      e.oauthError = errMsg;
+      e.oauthDescription = parsed.error_description || null;
+      throw e;
+    }
+    const e = new Error('OpenRouter sign-in failed: HTTP ' + res.status + ' ' + res.statusText);
+    e.code = 'EUPSTREAM';
+    e.status = res.status;
+    e.body = text.slice(0, 2000);
+    throw e;
+  }
+  let json;
+  try { json = JSON.parse(text); }
+  catch (err) {
+    const e = new Error('OpenRouter sign-in returned non-JSON: ' + err.message);
+    e.code = 'EPARSE';
+    throw e;
+  }
+  if (!json.key || typeof json.key !== 'string') {
+    const e = new Error('OpenRouter sign-in returned 200 with no `key`');
+    e.code = 'ETOKEN';
+    throw e;
+  }
+  return { key: json.key };
+}
+
+// ---- Account naming ----------------------------------------------------
+
+// The PKCE flow hands back a single string (the API key), not a
+// structured account object. We synthesise a short, recognisable
+// label from the key's prefix so the OAuth account picker can show
+// one row per signed-in key without revealing the full secret. The
+// key starts with "sk-or-v1-" by convention; we keep the first 16
+// chars which is unique enough to be useful but not a leak. Empty
+// / short keys fall through to "default" so the picker always has
+// a value.
+function accountForKey(key) {
+  if (typeof key !== 'string' || !key) return 'default';
+  const trimmed = key.trim();
+  if (!trimmed) return 'default';
+  return trimmed.length <= 16 ? trimmed : trimmed.slice(0, 16);
+}
+
+// ---- Auth subsystem wiring --------------------------------------------
+
+// Exchange function registered with auth.registerExchange. Mirrors
+// the shape src/oauth-anthropic.js and src/oauth-github-copilot.js
+// expect: ({ pending, code }) -> { accessToken, refreshToken?,
+// expiresAt?, scope?, account }. The OpenRouter `key` lands in the
+// `accessToken` field; the AI client treats it as a Bearer credential
+// at chat time (see src/ai.js → ENDPOINTS.openrouter.authHeader).
+async function exchange({ pending, code }) {
+  if (!pending || !pending.codeVerifier) {
+    const e = new Error('openrouter pending record is missing codeVerifier — start a new sign-in');
+    e.code = 'EBADINPUT';
+    throw e;
+  }
+  const out = await exchangeAuthorizationCode({
+    code,
+    verifier: pending.codeVerifier,
+    // OpenRouter does not echo a `state` query param back to the
+    // callback; the loopback handler in src/index.js carries the
+    // `state` through `pending.state`, so it does not need to be
+    // sent to the exchange endpoint.
+  });
+  return {
+    // Map the OpenRouter API key to the standard OAuth blob. The AI
+    // client reads `accessToken`; the model record's `auth: 'oauth'`
+    // makes requireApiKey() take the OAuth branch, which then uses
+    // the same Bearer-header path the apikey branch uses.
+    accessToken: out.key,
+    refreshToken: null, // OpenRouter does not issue refresh tokens
+    expiresAt: null,    // OpenRouter keys do not expire unless revoked
+    scope: 'openrouter',
+    account: accountForKey(out.key)
+  };
+}
+
+// Refresher registered with auth.registerRefresher. OpenRouter keys
+// cannot be refreshed — a revocation requires a fresh sign-in. The
+// AI client calls this just before a request when the stored
+// `expiresAt` is within OAUTH_REFRESH_LEAD_MS, but `expiresAt` is
+// always null for OpenRouter, so this is never called in practice.
+// We register a no-op refresher so the auth subsystem's refresh path
+// is a clean no-op (returns the existing blob verbatim) rather than
+// a typed ENOREFRESHER error.
+async function refresh({ provider, account, scope }) {
+  if (provider !== 'openrouter') {
+    const e = new Error('openrouter refresher called for provider "' + provider + '"');
+    e.code = 'EBADINPUT';
+    throw e;
+  }
+  return {
+    accessToken: '',
+    refreshToken: null,
+    expiresAt: null,
+    scope: scope || 'openrouter',
+    account: account || null
+  };
+}
+
+let _registered = false;
+function register() {
+  if (_registered) return;
+  if (!auth.getExchange('openrouter')) auth.registerExchange('openrouter', exchange);
+  if (!auth.getRefresher('openrouter')) auth.registerRefresher('openrouter', refresh);
+  _registered = true;
+}
+
+module.exports = {
+  // introspection
+  AUTHORIZE_URL,
+  KEYS_URL,
+  // helpers
+  newState,
+  newVerifier,
+  challengeFor,
+  buildAuthorizeUrl,
+  exchangeAuthorizationCode,
+  accountForKey,
+  // registration
+  register,
+  // exposed for tests
+  exchange,
+  refresh
+};

package/src/package-version.js

@@ -0,0 +1,20 @@
+'use strict';
+
+// Tiny helper for src/mcp.js to get the current mouaif version without
+// dragging in the full package.json (which would couple every require
+// of mcp.js to the package layout).
+//
+// The version comes from a build-time stamp; in this repo we read the
+// package.json once at require time. A future revision can swap this
+// for a generated file to avoid the cost.
+
+const fs = require('fs');
+const path = require('path');
+
+let _version = '0.0.0';
+try {
+  const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+  if (pkg && typeof pkg.version === 'string') _version = pkg.version;
+} catch { /* swallow; default version is fine for non-fatal uses */ }
+
+module.exports = _version;