@atlassian-dc-mcp/common 0.16.0 → 0.17.0

package/src/config/sources/home-file.ts

@@ -0,0 +1,121 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import type { ConfigKey, ProductDefinition, SourceId, WritableSource } from '../source.js';
+import { getNonEmptyValue } from '../source.js';
+import {
+  DotenvFileCache,
+  DotenvFileNotFoundError,
+  type ParsedEnvironment,
+} from './dotenv-file-cache.js';
+
+const HOME_DIR_NAME = '.atlassian-dc-mcp';
+
+function getHomeFilePath(product: ProductDefinition | string): string {
+  const id = typeof product === 'string' ? product : product.id;
+  return path.join(os.homedir(), HOME_DIR_NAME, `${id}.env`);
+}
+
+function needsQuoting(value: string): boolean {
+  return /[\s#'"]/.test(value);
+}
+
+function serializeValue(value: string): string {
+  if (!needsQuoting(value)) {
+    return value;
+  }
+  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+function serialize(values: ParsedEnvironment): string {
+  const lines: string[] = [];
+  for (const [key, raw] of Object.entries(values)) {
+    lines.push(`${key}=${serializeValue(raw)}`);
+  }
+  return lines.length > 0 ? `${lines.join('\n')}\n` : '';
+}
+
+export class HomeFileSource implements WritableSource {
+  readonly id: SourceId = 'home-file';
+  readonly priority = 60;
+
+  private cache = new DotenvFileCache();
+
+  isAvailable(): boolean {
+    return true;
+  }
+
+  read(product: ProductDefinition, key: ConfigKey): string | undefined {
+    const values = this.loadFile(product);
+    return getNonEmptyValue(values[product.envVars[key]]);
+  }
+
+  describe(): string {
+    return `home-file (~/${HOME_DIR_NAME}/<product>.env)`;
+  }
+
+  describeForProduct(product: ProductDefinition): string {
+    return `home-file (${getHomeFilePath(product)})`;
+  }
+
+  write(product: ProductDefinition, key: ConfigKey, value: string): void {
+    const envVar = product.envVars[key];
+    const existing = this.readFileIgnoringErrors(product);
+    existing[envVar] = value;
+    this.persist(product, existing);
+  }
+
+  clear(product: ProductDefinition, key: ConfigKey): void {
+    const envVar = product.envVars[key];
+    const existing = this.readFileIgnoringErrors(product);
+    if (!(envVar in existing)) {
+      return;
+    }
+    delete existing[envVar];
+    this.persist(product, existing);
+  }
+
+  private loadFile(product: ProductDefinition): ParsedEnvironment {
+    const filePath = getHomeFilePath(product);
+    try {
+      return this.cache.load(filePath);
+    } catch (error) {
+      if (error instanceof DotenvFileNotFoundError) {
+        return {};
+      }
+      throw error;
+    }
+  }
+
+  private readFileIgnoringErrors(product: ProductDefinition): ParsedEnvironment {
+    try {
+      return { ...this.loadFile(product) };
+    } catch {
+      return {};
+    }
+  }
+
+  private persist(product: ProductDefinition, values: ParsedEnvironment): void {
+    const filePath = getHomeFilePath(product);
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+    const tmpPath = `${filePath}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+    try {
+      fs.writeFileSync(tmpPath, serialize(values), { mode: 0o600 });
+      fs.renameSync(tmpPath, filePath);
+    } catch (error) {
+      try {
+        fs.unlinkSync(tmpPath);
+      } catch {
+        // best-effort cleanup
+      }
+      throw error;
+    }
+
+    this.cache.invalidate();
+  }
+}
+
+export { getHomeFilePath, HOME_DIR_NAME };

package/src/config/sources/macos-keychain.ts

@@ -0,0 +1,117 @@
+import { execFileSync as nodeExecFileSync } from 'node:child_process';
+import { existsSync as nodeExistsSync } from 'node:fs';
+import type { ConfigKey, ProductDefinition, SourceId, WritableSource } from '../source.js';
+
+// We pass the token via `-w <value>` on write. `security add-generic-password`
+// has no stdin-password mode, so the token is visible in argv to same-user
+// processes. A same-user attacker already has keychain access via `security`
+// itself; this does not widen the attack surface.
+
+export const SECURITY_BINARY = '/usr/bin/security';
+export const KEYCHAIN_SERVICE = 'atlassian-dc-mcp';
+const KEYCHAIN_TIMEOUT_MS = 5000;
+export const NOT_FOUND_STATUS = 44;
+
+export type KeychainDeps = {
+  execFileSync: typeof nodeExecFileSync;
+  existsSync: typeof nodeExistsSync;
+  getPlatform: () => NodeJS.Platform;
+};
+
+function accountFor(product: ProductDefinition): string {
+  return `${product.id}-token`;
+}
+
+const DEFAULT_DEPS: KeychainDeps = {
+  execFileSync: nodeExecFileSync,
+  existsSync: nodeExistsSync,
+  getPlatform: () => process.platform,
+};
+
+export class MacosKeychainSource implements WritableSource {
+  readonly id: SourceId = 'macos-keychain';
+  readonly priority = 40;
+
+  private cache = new Map<string, string | undefined>();
+  private cacheWarmed = new Set<string>();
+  private readonly deps: KeychainDeps;
+
+  constructor(deps: Partial<KeychainDeps> = {}) {
+    this.deps = { ...DEFAULT_DEPS, ...deps };
+  }
+
+  isAvailable(): boolean {
+    return this.deps.getPlatform() === 'darwin' && this.deps.existsSync(SECURITY_BINARY);
+  }
+
+  read(product: ProductDefinition, key: ConfigKey): string | undefined {
+    if (key !== 'token' || !this.isAvailable()) {
+      return undefined;
+    }
+    if (this.cacheWarmed.has(product.id)) {
+      return this.cache.get(product.id);
+    }
+    const value = this.findPassword(product);
+    this.cache.set(product.id, value);
+    this.cacheWarmed.add(product.id);
+    return value;
+  }
+
+  describe(): string {
+    return 'macOS Keychain';
+  }
+
+  write(product: ProductDefinition, key: ConfigKey, value: string): void {
+    if (key !== 'token') {
+      throw new Error('macOS Keychain only stores the token key');
+    }
+    if (!this.isAvailable()) {
+      throw new Error('macOS Keychain is not available on this platform');
+    }
+    this.deps.execFileSync(
+      SECURITY_BINARY,
+      [
+        'add-generic-password',
+        '-U',
+        '-s', KEYCHAIN_SERVICE,
+        '-a', accountFor(product),
+        '-w', value,
+      ],
+      { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8', timeout: KEYCHAIN_TIMEOUT_MS },
+    );
+    this.cache.set(product.id, value);
+    this.cacheWarmed.add(product.id);
+  }
+
+  clear(product: ProductDefinition, key: ConfigKey): void {
+    if (key !== 'token' || !this.isAvailable()) {
+      return;
+    }
+    try {
+      this.deps.execFileSync(
+        SECURITY_BINARY,
+        ['delete-generic-password', '-s', KEYCHAIN_SERVICE, '-a', accountFor(product)],
+        { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8', timeout: KEYCHAIN_TIMEOUT_MS },
+      );
+    } catch {
+      // absent / already cleared — non-fatal
+    }
+    this.cache.set(product.id, undefined);
+    this.cacheWarmed.add(product.id);
+  }
+
+  private findPassword(product: ProductDefinition): string | undefined {
+    try {
+      const stdout = this.deps.execFileSync(
+        SECURITY_BINARY,
+        ['find-generic-password', '-s', KEYCHAIN_SERVICE, '-a', accountFor(product), '-w'],
+        { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8', timeout: KEYCHAIN_TIMEOUT_MS },
+      );
+      return String(stdout).replace(/\n$/, '');
+    } catch {
+      // exit 44 = not found; any other failure (locked keychain, etc.) is
+      // treated as absent so the resolver continues down the chain.
+      return undefined;
+    }
+  }
+}

package/src/config/sources/process-env.ts

@@ -0,0 +1,15 @@
+import type { ConfigKey, ProductDefinition, ReadableSource, SourceId } from '../source.js';
+import { getNonEmptyValue } from '../source.js';
+
+export class ProcessEnvSource implements ReadableSource {
+  readonly id: SourceId = 'process-env';
+  readonly priority = 100;
+
+  read(product: ProductDefinition, key: ConfigKey): string | undefined {
+    return getNonEmptyValue(process.env[product.envVars[key]]);
+  }
+
+  describe(): string {
+    return 'process env';
+  }
+}

package/src/index.ts

@@ -2,7 +2,8 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 export * from './api-error-handler.js'
-export * from './runtime-config.js';
+export * from './config/index.js';
+export { runSetup } from './setup-cli.js';
 
 // Helper function to format tool responses
 export const formatToolResponse = (result: unknown) => ({

package/src/setup-cli.ts

@@ -0,0 +1,308 @@
+import { confirm as inquirerConfirm, input as inquirerInput, password as inquirerPassword } from '@inquirer/prompts';
+import { buildDefaultRegistry, type ConfigRegistry } from './config/registry.js';
+import { getProductRuntimeConfig } from './config/runtime-config.js';
+import type {
+  ConfigKey,
+  ProductDefinition,
+  WritableSource,
+} from './config/source.js';
+import { HomeFileSource, getHomeFilePath } from './config/sources/home-file.js';
+import { MacosKeychainSource } from './config/sources/macos-keychain.js';
+
+const FALLBACK_PAGE_SIZE = 25;
+
+type PromptResult = {
+  host: string;
+  apiBasePath: string;
+  defaultPageSize: string;
+  token: string | undefined;
+};
+
+export type SetupPrompts = {
+  input: (opts: { message: string; default?: string; validate?: (raw: string) => true | string }) => Promise<string>;
+  password: (opts: { message: string; mask?: string }) => Promise<string>;
+  confirm: (opts: { message: string; default?: boolean }) => Promise<boolean>;
+};
+
+export type SetupDeps = {
+  registry?: ConfigRegistry;
+  log?: (message: string) => void;
+  exit?: (code: number) => void;
+  prompts?: SetupPrompts;
+};
+
+const DEFAULT_PROMPTS: SetupPrompts = {
+  input: (opts) => inquirerInput(opts as any),
+  password: (opts) => inquirerPassword(opts as any),
+  confirm: (opts) => inquirerConfirm(opts as any),
+};
+
+export async function runSetup(product: ProductDefinition, deps: SetupDeps = {}): Promise<void> {
+  const registry = deps.registry ?? buildDefaultRegistry();
+  const log = deps.log ?? ((message: string) => process.stdout.write(`${message}\n`));
+  const exit = deps.exit ?? ((code: number) => { process.exit(code); });
+  const prompts = deps.prompts ?? DEFAULT_PROMPTS;
+
+  registry.initialize();
+
+  log(`Atlassian DC MCP setup — ${product.id}`);
+  log('');
+
+  const current = getProductRuntimeConfig(product);
+  printCurrent(log, registry, product, current);
+
+  let answers: PromptResult;
+  try {
+    answers = await promptForValues(prompts, product, current);
+  } catch (error) {
+    if (isUserCancel(error)) {
+      exit(130);
+      return;
+    }
+    throw error;
+  }
+
+  const homeFile = requireHomeFile(registry);
+  writeNonSecretFields(registry, product, answers, homeFile, log);
+  const tokenWriter = await writeToken(registry, product, answers.token, homeFile, log, prompts);
+  printSummary(log, product, answers, tokenWriter);
+}
+
+function requireHomeFile(registry: ConfigRegistry): HomeFileSource {
+  const homeFile = registry.getWritableSource(
+    (s): s is HomeFileSource => s instanceof HomeFileSource,
+  );
+  if (!homeFile) {
+    throw new Error('No writable source available for non-secret fields');
+  }
+  return homeFile;
+}
+
+function printCurrent(
+  log: (message: string) => void,
+  registry: ConfigRegistry,
+  product: ProductDefinition,
+  current: ReturnType<typeof getProductRuntimeConfig>,
+): void {
+  const keys: ConfigKey[] = ['host', 'apiBasePath', 'token', 'defaultPageSize'];
+  for (const key of keys) {
+    const primary = registry.locate(product, key)[0];
+    const label = displayLabel(key);
+    const displayValue = key === 'token' ? maskToken(current.token) : readable(current[key]);
+    const origin = primary ? `from ${primary.detail ?? primary.sourceId}` : 'not set';
+    log(`Current ${label}: ${displayValue} (${origin})`);
+  }
+  log('');
+}
+
+async function promptForValues(
+  prompts: SetupPrompts,
+  product: ProductDefinition,
+  current: ReturnType<typeof getProductRuntimeConfig>,
+): Promise<PromptResult> {
+  const host = await prompts.input({
+    message: 'Host (e.g. jira.example.com):',
+    default: current.host ?? '',
+  });
+  const apiBasePath = await prompts.input({
+    message: 'API base path:',
+    default: current.apiBasePath ?? product.defaultApiBasePath ?? '',
+  });
+  const defaultPageSize = await prompts.input({
+    message: 'Default page size:',
+    default: String(current.defaultPageSize ?? FALLBACK_PAGE_SIZE),
+    validate: (raw) =>
+      /^\d+$/.test(raw.trim()) && Number.parseInt(raw.trim(), 10) > 0
+        ? true
+        : 'Enter a positive integer',
+  });
+  const token = await promptForToken(prompts, current.token);
+  return { host: host.trim(), apiBasePath: apiBasePath.trim(), defaultPageSize: defaultPageSize.trim(), token };
+}
+
+async function promptForToken(
+  prompts: SetupPrompts,
+  existing: string | undefined,
+): Promise<string | undefined> {
+  const entered = await prompts.password({ message: 'API token:', mask: '*' });
+  const trimmed = entered.trim();
+  if (trimmed.length > 0) {
+    return trimmed;
+  }
+  if (!existing) {
+    return undefined;
+  }
+  await prompts.confirm({ message: 'Keep existing token?', default: true });
+  return undefined;
+}
+
+function writeNonSecretFields(
+  registry: ConfigRegistry,
+  product: ProductDefinition,
+  answers: PromptResult,
+  homeFile: HomeFileSource,
+  log: (message: string) => void,
+): void {
+  for (const key of ['host', 'apiBasePath', 'defaultPageSize'] as const) {
+    warnIfShadowed(registry, product, key, homeFile, log);
+    const value = answers[key];
+    if (value.length > 0) {
+      homeFile.write(product, key, value);
+    }
+  }
+}
+
+async function writeToken(
+  registry: ConfigRegistry,
+  product: ProductDefinition,
+  token: string | undefined,
+  homeFile: HomeFileSource,
+  log: (message: string) => void,
+  prompts: SetupPrompts,
+): Promise<WritableSource | undefined> {
+  if (!token) {
+    return undefined;
+  }
+
+  const keychain = registry.getWritableSource(
+    (s): s is MacosKeychainSource => s instanceof MacosKeychainSource,
+  );
+  const candidates: WritableSource[] = [];
+  if (keychain?.isAvailable()) {
+    candidates.push(keychain);
+  }
+  candidates.push(homeFile);
+
+  warnIfShadowed(registry, product, 'token', candidates[0], log);
+
+  for (const writer of candidates) {
+    const written = await tryWrite(writer, product, token, log, prompts);
+    if (written) {
+      if (writer instanceof MacosKeychainSource) {
+        homeFile.clear(product, 'token');
+      }
+      return writer;
+    }
+  }
+  throw new Error('No writable source succeeded for token');
+}
+
+async function tryWrite(
+  writer: WritableSource,
+  product: ProductDefinition,
+  token: string,
+  log: (message: string) => void,
+  prompts: SetupPrompts,
+): Promise<boolean> {
+  try {
+    writer.write(product, 'token', token);
+    return true;
+  } catch (error) {
+    const stderr = (error as { stderr?: string | Buffer }).stderr?.toString() ?? '';
+    log(`Failed to write token to ${writer.describe()}: ${(error as Error).message}`);
+    if (stderr) {
+      log(stderr.trim());
+    }
+    if (writer instanceof MacosKeychainSource) {
+      const fallback = await prompts.confirm({
+        message: 'Fall back to plaintext home file with mode 0600?',
+        default: false,
+      });
+      return !fallback;
+    }
+    return false;
+  }
+}
+
+function warnIfShadowed(
+  registry: ConfigRegistry,
+  product: ProductDefinition,
+  key: ConfigKey,
+  target: WritableSource,
+  log: (message: string) => void,
+): void {
+  const shadowing = registry
+    .locate(product, key)
+    .filter((loc) => priorityOf(registry, loc.sourceId) > target.priority);
+  if (shadowing.length === 0) {
+    return;
+  }
+  const envVar = product.envVars[key];
+  for (const loc of shadowing) {
+    if (loc.sourceId === 'process-env') {
+      log(`Warning: process.env[${envVar}] is set — runtime will prefer it over the value you're saving to ${target.describe()}. Unset it to use the new value.`);
+    } else {
+      log(`Warning: ${loc.detail ?? loc.sourceId} provides ${envVar} — runtime will prefer it over the value you're saving to ${target.describe()}.`);
+    }
+  }
+}
+
+function priorityOf(registry: ConfigRegistry, sourceId: string): number {
+  const match = registry.sources.find((s) => s.id === sourceId);
+  return match?.priority ?? 0;
+}
+
+function printSummary(
+  log: (message: string) => void,
+  product: ProductDefinition,
+  answers: PromptResult,
+  tokenWriter: WritableSource | undefined,
+): void {
+  log('');
+  log('Saved configuration:');
+  log(`  host: ${answers.host || '(unchanged)'}`);
+  log(`  apiBasePath: ${answers.apiBasePath || '(unchanged)'}`);
+  log(`  defaultPageSize: ${answers.defaultPageSize || '(unchanged)'}`);
+  if (tokenWriter) {
+    log(`  token: ${maskToken(answers.token)} (stored in ${describeWriter(tokenWriter, product)})`);
+  } else {
+    log('  token: (unchanged)');
+  }
+  log(`Home file: ${getHomeFilePath(product)}`);
+}
+
+function describeWriter(writer: WritableSource, product: ProductDefinition): string {
+  if (writer instanceof MacosKeychainSource) {
+    return `macOS Keychain (service atlassian-dc-mcp, account ${product.id}-token)`;
+  }
+  if (writer instanceof HomeFileSource) {
+    return writer.describeForProduct(product);
+  }
+  return writer.describe();
+}
+
+function displayLabel(key: ConfigKey): string {
+  switch (key) {
+    case 'host':
+      return 'host';
+    case 'apiBasePath':
+      return 'API base path';
+    case 'token':
+      return 'token';
+    case 'defaultPageSize':
+      return 'page size';
+  }
+}
+
+function readable(value: string | number | undefined): string {
+  if (value === undefined || value === '') {
+    return '(not set)';
+  }
+  return String(value);
+}
+
+function maskToken(token: string | undefined): string {
+  if (!token) {
+    return '(not set)';
+  }
+  const last4 = token.slice(-4);
+  return `••••${last4}`;
+}
+
+function isUserCancel(error: unknown): boolean {
+  if (!error || typeof error !== 'object') {
+    return false;
+  }
+  const err = error as { name?: string; message?: string };
+  return err.name === 'ExitPromptError' || /force closed/i.test(err.message ?? '');
+}