@martin4455/matomo-mcp-ro 0.4.1

package/cli.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { MatomoApi, MatomoError } from './api.mjs';
+import { CONFIG_NAME, ConfigError, apiOptions, loadConfig, normalizeBaseUrl, resolveConfigPath, saveConfig, validateConfig, prepareConfiguration, configStatus } from './lib/config.mjs';
+import { ask } from './lib/prompt.mjs';
+import { clientConfiguration } from './lib/client-config.mjs';
+import { VERSION } from './lib/version.mjs';
+
+export { VERSION };
+const help = `Matomo MCP - lokalny adapter Reporting API, tylko do odczytu\n\nUżycie: matomo-mcp [polecenie] [--config /ścieżka/${CONFIG_NAME}]\n\n  configure                    Wpisz dane w terminalu, sprawdź i zapisz w keyringu\n  check                        Sprawdź prawa pliku, keyring i połączenie z Matomo\n  status                       Sprawdź konfigurację i keyring bez HTTP\n  serve                        Uruchom MCP przez stdio (polecenie domyślne)\n  client-config codex          Wypisz wpis TOML z bezpośrednim startem Node.js\n  client-config claude-code    Wypisz wpis MCP JSON dla Claude Code\n  client-config claude-desktop Wypisz wpis MCP JSON dla Claude Desktop\n  --help / --version\n\nBez --config używany jest wyłącznie plik ${CONFIG_NAME} w bieżącym katalogu.\nURL, token i Basic Auth są w systemowym keyringu; plik zawiera tylko odwołanie.\nToken i dane HTTP Auth wpisuj tylko w configure, nigdy w argumentach poleceń.\n`;
+
+export function parseArguments(argv) {
+  let config;
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--config') {
+      if (config !== undefined || !argv[i + 1] || argv[i + 1].startsWith('-')) throw new ConfigError('Po --config podaj ścieżkę do pliku konfiguracji.');
+      config = argv[++i];
+    } else if (['--help', '-h', '--version'].includes(argv[i])) positional.push(argv[i]);
+    else if (argv[i].startsWith('-')) throw new ConfigError('Nieznana opcja. Użyj --help.');
+    else positional.push(argv[i]);
+  }
+  const command = positional[0] ?? 'serve';
+  const client = positional[1];
+  if (!['configure', 'check', 'status', 'serve', 'client-config', '--help', '-h', '--version'].includes(command)
+    || positional.length > (command === 'client-config' ? 2 : 1)
+    || command === 'client-config' && !['codex', 'claude-code', 'claude-desktop'].includes(client)) {
+    throw new ConfigError('Nieprawidłowe polecenie. Użyj --help.');
+  }
+  return { command, client, configPath: resolveConfigPath(config) };
+}
+
+export async function checkConnection(config, fetchImpl) {
+  const api = new MatomoApi({ ...apiOptions(config), ...(fetchImpl ? { fetchImpl } : {}) });
+  const sites = await api.call('SitesManager.getSitesWithAtLeastViewAccess');
+  if (!Array.isArray(sites)) throw new MatomoError('Matomo nie zwróciło oczekiwanej listy witryn.');
+  if (!sites.length) throw new MatomoError('Token jest poprawny, ale nie ma dostępu do żadnej witryny.');
+  return { ok: true, backend: 'reporting-api', siteCount: sites.length };
+}
+
+export async function configure(configPath, { store, askImpl = ask, input = process.stdin, output = process.stdout, fetchImpl } = {}) {
+  if (!input.isTTY || !output.isTTY) throw new ConfigError('Uruchom configure we własnym terminalu. Nie przesyłaj tokenu, loginu ani hasła w rozmowie z AI.');
+  output.write(`Konfiguracja: ${configPath}\nURL, token i Basic Auth będą zapisane w systemowym keyringu. Plik będzie zawierał tylko odwołanie.\nOdpowiedź wpisuj po dwukropku i zatwierdzaj klawiszem Enter. Ctrl+C przerywa konfigurację.\nToken, login i hasło są ukryte: podczas wpisywania nie widać znaków ani gwiazdek.\n\nOdczytuję zapisaną konfigurację...\n`);
+  const expected = await prepareConfiguration(configPath, { store });
+  let previous = expected.previous;
+  if (expected.record && !previous) output.write('Zapisane dane są nieprawidłowe lub niekompletne. Wpisz pełne dane; zostaną zapisane dopiero po udanym teście.\n');
+  const prompt = (question, options) => askImpl(question, { ...options, input, output });
+  const secret = async (label, saved) => {
+    const value = await prompt(`${label}${saved ? ' (Enter = zachowaj)' : ' (wymagane)'}: `, { hidden: true });
+    if (value) output.write('  Przyjęto nową wartość.\n');
+    else if (saved) output.write('  Zachowano zapisaną wartość.\n');
+    return value || saved;
+  };
+  output.write('\n[1/4] Adres Matomo\n');
+  if (previous) output.write(`Zapisany adres: ${previous.baseUrl}\n`);
+  const baseUrl = normalizeBaseUrl((await prompt(`Adres HTTPS Matomo${previous ? ' (Enter = zachowaj)' : ' (wymagane)'}: `)).trim() || previous?.baseUrl);
+  if (previous && previous.baseUrl !== baseUrl) {
+    previous = undefined;
+    output.write('Adres Matomo został zmieniony. Wpisz komplet danych dla nowego adresu.\n');
+  }
+  output.write('\n[2/4] HTTP Basic Auth\nCzy serwer wymaga dodatkowego loginu i hasła HTTP Basic Auth?\n');
+  let answer;
+  while (true) {
+    answer = (await prompt(`Wpisz tak lub nie (Enter = ${previous?.basicAuth ? 'tak' : 'nie'}): `)).trim().toLowerCase();
+    if (['', 't', 'tak', 'y', 'yes', 'n', 'nie', 'no'].includes(answer)) break;
+    output.write('Nie rozpoznano odpowiedzi. Wpisz tak albo nie i naciśnij Enter.\n');
+  }
+  const useBasic = answer ? ['t', 'tak', 'y', 'yes'].includes(answer) : Boolean(previous?.basicAuth);
+  output.write(`HTTP Basic Auth: ${useBasic ? 'włączone' : 'wyłączone'}.\n`);
+  let basicAuth;
+  if (useBasic) {
+    const username = await secret('Login HTTP Basic Auth', previous?.basicAuth?.username);
+    const password = await secret('Hasło HTTP Basic Auth', previous?.basicAuth?.password);
+    basicAuth = { username, password };
+  }
+  output.write('\n[3/4] Token API Matomo\nWklej aktualny token i naciśnij Enter.\n');
+  const token = await secret('Token API Matomo', previous?.token);
+  const config = validateConfig({ schemaVersion: 1, baseUrl, token, ...(basicAuth ? { basicAuth } : {}) });
+  output.write('\n[4/4] Test połączenia i zapis\nSprawdzam dostęp do Matomo...\n');
+  const result = await checkConnection(config, fetchImpl);
+  output.write('Połączenie działa. Zapisuję dane w keyringu...\n');
+  const saved = await saveConfig(configPath, config, { overwrite: Boolean(expected.record), expected, store });
+  if (saved.cleanupPending) output.write('Nowe dane są zapisane; część poprzednich fragmentów mogła pozostać w keyringu.\n');
+  output.write(`OK: zapisano konfigurację w keyringu. Dostępne witryny: ${result.siteCount}.\nUruchom check lub client-config codex / claude-code / claude-desktop. Po zmianie danych uruchom MCP ponownie.\n`);
+}
+
+export async function main(argv = process.argv.slice(2), { store, output = process.stdout, fetchImpl, ...options } = {}) {
+  const { command, client, configPath } = parseArguments(argv);
+  if (command === '--help' || command === '-h') return output.write(help);
+  if (command === '--version') return output.write(VERSION + '\n');
+  if (command === 'client-config') return output.write(clientConfiguration(client, configPath));
+  if (command === 'configure') return configure(configPath, { ...options, store, output, fetchImpl });
+  if (command === 'status' || command === 'check') {
+    const result = command === 'check' ? await checkConnection(await loadConfig(configPath, { store }), fetchImpl) : {};
+    const status = await configStatus(configPath, { store });
+    output.write(JSON.stringify({ ...result, ...status, config: configPath, backend: 'reporting-api', readOnly: true, node: process.version }, null, 2) + '\n');
+    return;
+  }
+  const config = await loadConfig(configPath, { store });
+  const { serve } = await import('./server.mjs');
+  await serve(new MatomoApi(apiOptions(config)));
+}
+
+export function reportError(error) {
+  process.stderr.write((error instanceof ConfigError || error instanceof MatomoError ? error.message : 'Operacja Matomo MCP nie powiodła się. Sprawdź konfigurację poleceniem check.') + '\n');
+  process.exitCode = 1;
+}
+
+function invokedDirectly() {
+  try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); } catch { return false; }
+}
+
+if (process.argv[1] && invokedDirectly()) main().catch(reportError);

package/client.mjs

@@ -0,0 +1,28 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { VERSION } from './lib/version.mjs';
+import { keyringSessionEnvironment } from './lib/session-env.mjs';
+export { protectPath as protectOutputPath } from './lib/permissions.mjs';
+
+/** Generic stdio client for local scripts. It never reads or returns credentials. */
+export async function connectMatomo({ configPath, cwd = process.cwd(), cliPath = fileURLToPath(new URL('./cli.mjs', import.meta.url)) } = {}) {
+  const client = new Client({ name: 'matomo-mcp-ro-client', version: VERSION });
+  const transport = new StdioClientTransport({ command: process.execPath,
+    args: [path.resolve(cliPath), 'serve', ...(configPath ? ['--config', path.resolve(configPath)] : [])], cwd, stderr: 'pipe', env: keyringSessionEnvironment() });
+  transport.stderr?.on('data', () => {});
+  try { await client.connect(transport); }
+  catch { await client.close().catch(() => {}); throw new Error('Nie można uruchomić MCP. Sprawdź instalację, prawa konfiguracji i polecenie check.'); }
+  return {
+    version: client.getServerVersion()?.version,
+    async tools() { return (await client.listTools()).tools.map(t => t.name); },
+    async call(name, args, { signal, timeout = 180000 } = {}) {
+      const result = await client.callTool({ name, arguments: args }, undefined, { signal, timeout });
+      const text = result.content?.find(item => item.type === 'text')?.text;
+      if (result.isError) throw new Error(text ?? 'Błąd narzędzia MCP.');
+      try { return JSON.parse(text); } catch { throw new Error('Nieprawidłowa odpowiedź MCP.'); }
+    },
+    close: () => client.close(),
+  };
+}

package/lib/client-config.mjs

@@ -0,0 +1,14 @@
+import { fileURLToPath } from 'node:url';
+
+export function clientConfiguration(client, configPath) {
+  const command = process.execPath;
+  const args = [fileURLToPath(new URL('../cli.mjs', import.meta.url)), 'serve', '--config', configPath];
+  const name = 'matomo';
+  if (client === 'codex') {
+    return `[mcp_servers.${name}]\ncommand = ${JSON.stringify(command)}\nargs = ${JSON.stringify(args)}\nstartup_timeout_sec = 20\ntool_timeout_sec = 90\n`;
+  }
+  if (client === 'claude-code' || client === 'claude-desktop') {
+    return JSON.stringify({ mcpServers: { [name]: { command, args } } }, null, 2) + '\n';
+  }
+  throw new Error('Unknown client');
+}

package/lib/config-errors.mjs

@@ -0,0 +1,8 @@
+// Messages in this class are application-owned. Never wrap a native error/cause.
+export class ConfigError extends Error {
+  constructor(message, code = 'CONFIG_INVALID') {
+    super(message);
+    this.name = 'ConfigError';
+    this.code = code;
+  }
+}

package/lib/config-file.mjs

@@ -0,0 +1,102 @@
+import fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import { ConfigError } from './config-errors.mjs';
+import { protectPath, inspectPermissions } from './permissions.mjs';
+
+export const CONFIG_NAME = '.matomo-mcp.json';
+const MAX_FILE_BYTES = 65536;
+function checkStat(stat) {
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) throw new ConfigError('Konfiguracja musi być zwykłym plikiem, bez dowiązań.');
+  if (stat.size > MAX_FILE_BYTES) throw new ConfigError('Plik konfiguracji jest zbyt duży.');
+  if (process.platform !== 'win32' && ((stat.mode & 0o777) !== 0o600 || stat.uid !== process.getuid())) {
+    throw new ConfigError('Plik konfiguracji wymaga uprawnień 600 i właściciela zgodnego z bieżącym kontem.');
+  }
+}
+function sameFile(a, b) { return a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs; }
+
+export async function readConfigFile(target, { allowMissing = false } = {}) {
+  if (path.basename(target) !== CONFIG_NAME) throw new ConfigError(`Plik konfiguracji musi mieć nazwę ${CONFIG_NAME}.`);
+  let handle;
+  try {
+    let before;
+    try { before = await fs.lstat(target); }
+    catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      if (allowMissing) return null;
+      throw new ConfigError('Brak lokalnego pliku .matomo-mcp.json. Uruchom configure w katalogu projektu lub podaj --config.', 'CONFIG_MISSING');
+    }
+    checkStat(before);
+    handle = await fs.open(target, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const opened = await handle.stat();
+    checkStat(opened);
+    if (!sameFile(before, opened)) throw new ConfigError('Konfiguracja zmieniła się podczas odczytu.', 'CONFIG_CONFLICT');
+    const permissions = await inspectPermissions(target);
+    if (!permissions.private) throw new ConfigError('Plik konfiguracji ma zbyt szerokie uprawnienia. Wymagane są prywatny ACL Windows lub tryb 600 na Unix.', 'CONFIG_PERMISSIONS');
+    const buffer = Buffer.alloc(MAX_FILE_BYTES + 1);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+    const after = await handle.stat();
+    const atPath = await fs.lstat(target);
+    checkStat(after);
+    checkStat(atPath);
+    if (bytesRead > MAX_FILE_BYTES || bytesRead !== after.size || !sameFile(opened, after) || !sameFile(after, atPath)) {
+      throw new ConfigError('Konfiguracja zmieniła się podczas odczytu.', 'CONFIG_CONFLICT');
+    }
+    return { text: new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, bytesRead)), permissions: permissions.kind };
+  } catch (error) {
+    if (error instanceof ConfigError) throw error;
+    throw new ConfigError('Nie można bezpiecznie odczytać pliku konfiguracji na tym koncie.', 'CONFIG_READ_FAILED');
+  } finally { await handle?.close().catch(() => {}); }
+}
+
+async function ensureIgnored(directory) {
+  for (const name of ['.gitignore', '.ignore']) {
+    const target = path.join(directory, name);
+    let before = '';
+    try {
+      const stat = await fs.lstat(target);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) throw new ConfigError('Plik reguł wykluczania nie może być dowiązaniem.');
+      before = await fs.readFile(target, 'utf8');
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    const missing = [CONFIG_NAME, '.matomo-mcp-tmp-*/'].filter(rule => !before.split(/\r?\n/).includes(rule));
+    if (missing.length) await fs.appendFile(target, `${before && !before.endsWith('\n') ? '\n' : ''}${missing.join('\n')}\n`, 'utf8');
+  }
+}
+
+// Only reference metadata reaches this writer.
+export async function writeConfigFile(target, record, expectedText) {
+  if (record.schemaVersion !== 2 || Object.keys(record).sort().join(',') !== 'credentialId,schemaVersion'
+    || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(record.credentialId)) throw new ConfigError('Nieprawidłowe metadane konfiguracji.');
+  const directory = path.dirname(target);
+  let temporary;
+  let stagingFile;
+  try {
+    await ensureIgnored(directory);
+    temporary = await fs.mkdtemp(path.join(directory, '.matomo-mcp-tmp-'));
+    await protectPath(temporary, true);
+    stagingFile = path.join(temporary, CONFIG_NAME);
+    const handle = await fs.open(stagingFile, 'wx', 0o600);
+    try {
+      await protectPath(stagingFile);
+      if (!(await inspectPermissions(stagingFile)).private) throw new ConfigError('Nie udało się ograniczyć dostępu do pliku konfiguracji.');
+      await handle.writeFile(JSON.stringify(record, null, 2) + '\n', 'utf8');
+      await handle.sync();
+    } finally { await handle.close(); }
+    const actual = await readConfigFile(target, { allowMissing: true });
+    if ((actual?.text ?? null) !== expectedText) throw new ConfigError('Konfiguracja została zmieniona przez inną operację. Ponów configure.', 'CONFIG_CONFLICT');
+    if (expectedText !== null) await fs.rename(stagingFile, target);
+    else await fs.link(stagingFile, target);
+    // After commit, cleanup must not trigger a rollback of the new credential.
+    await fs.unlink(stagingFile).catch(() => {});
+    if (process.platform !== 'win32') {
+      const parent = await fs.open(directory, constants.O_RDONLY).catch(() => null);
+      if (parent) { await parent.sync().catch(() => {}); await parent.close().catch(() => {}); }
+    }
+  } catch (error) {
+    if (error instanceof ConfigError) throw error;
+    throw new ConfigError('Nie można zapisać prywatnego pliku konfiguracji. Sprawdź prawa do katalogu.', 'CONFIG_WRITE_FAILED');
+  } finally {
+    if (stagingFile) await fs.unlink(stagingFile).catch(() => {});
+    if (temporary) await fs.rmdir(temporary).catch(() => {});
+  }
+}

package/lib/config.mjs

@@ -0,0 +1,102 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { ConfigError } from './config-errors.mjs';
+import { CONFIG_NAME, readConfigFile, writeConfigFile } from './config-file.mjs';
+import { SystemCredentialStore, UUID_V4 } from './credential-store.mjs';
+import { withLock } from './locks.mjs';
+
+export { ConfigError, CONFIG_NAME };
+const secret = z.string().min(1).max(8192).refine(value => !/[\x00-\x1f\x7f]/.test(value));
+const connectionSchema = z.object({
+  schemaVersion: z.literal(1), baseUrl: z.string().min(1).max(2048), token: secret,
+  basicAuth: z.object({ username: secret.refine(value => !value.includes(':')), password: secret }).strict().optional(),
+}).strict();
+const referenceSchema = z.object({ schemaVersion: z.literal(2), credentialId: z.string().regex(UUID_V4) }).strict();
+const defaultStore = new SystemCredentialStore(); // No native import/access here.
+
+export function normalizeBaseUrl(value) {
+  let url;
+  try { url = new URL(value); } catch { throw new ConfigError('Podaj poprawny adres HTTPS Matomo.'); }
+  if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash) {
+    throw new ConfigError('Adres Matomo musi używać HTTPS i nie może zawierać loginu, hasła, parametrów ani fragmentu.');
+  }
+  if (url.pathname.endsWith('/index.php')) url.pathname = url.pathname.slice(0, -9);
+  if (!url.pathname.endsWith('/')) url.pathname += '/';
+  if (url.href.length > 2048) throw new ConfigError('Adres Matomo jest zbyt długi po normalizacji.');
+  return url.href;
+}
+export function validateConfig(value) {
+  const parsed = connectionSchema.safeParse(value);
+  if (!parsed.success) throw new ConfigError('Nieprawidłowa konfiguracja Matomo. Wymagane są adres HTTPS i token; opcjonalny Basic Auth wymaga loginu i hasła.');
+  return { ...parsed.data, baseUrl: normalizeBaseUrl(parsed.data.baseUrl) };
+}
+export function resolveConfigPath(explicit, cwd = process.cwd()) { return path.resolve(cwd, explicit ?? CONFIG_NAME); }
+
+export async function readConfigRecord(target, options) {
+  const file = await readConfigFile(target, options);
+  if (!file) return { text: null, record: null };
+  let value;
+  try { value = JSON.parse(file.text); }
+  catch { throw new ConfigError('Nie można odczytać konfiguracji JSON.'); }
+  // Recognize obsolete files only so configure can replace them. Never reuse their values.
+  const parsed = value?.schemaVersion === 1 ? { success: true, data: { schemaVersion: 1 } } : referenceSchema.safeParse(value);
+  if (!parsed.success) throw new ConfigError('Nieprawidłowe odwołanie do keyringu: wymagane są wyłącznie schemaVersion 2 i credentialId UUID v4.');
+  return { ...file, record: parsed.data };
+}
+function connectionFromSecret(text) {
+  if (text === null) throw new ConfigError('Brak wpisu w keyringu tego konta. Uruchom configure i podaj dane połączenia.', 'CREDENTIAL_MISSING');
+  try { return validateConfig(JSON.parse(text)); }
+  catch { throw new ConfigError('Wpis keyringu zawiera nieprawidłowe dane. Uruchom configure i podaj pełne dane.', 'CREDENTIAL_INVALID'); }
+}
+export async function loadConfig(target, { store = defaultStore } = {}) {
+  const { record } = await readConfigRecord(target);
+  if (record.schemaVersion === 1) throw new ConfigError('Zapisane dane mają nieprawidłowy format. Uruchom configure i podaj pełne dane połączenia.', 'CREDENTIAL_INVALID');
+  return connectionFromSecret(await store.get(record.credentialId));
+}
+
+export async function prepareConfiguration(target, { store = defaultStore } = {}) {
+  const snapshot = await readConfigRecord(target, { allowMissing: true });
+  if (!snapshot.record) return snapshot;
+  if (snapshot.record.schemaVersion === 1) return snapshot;
+  const { result } = await store.transaction(snapshot.record.credentialId, async tx => {
+    let previous;
+    try { previous = connectionFromSecret(await tx.get()); }
+    catch (error) { if (!['CREDENTIAL_MISSING', 'CREDENTIAL_INVALID'].includes(error.code)) throw error; }
+    return { previous, credentialRevision: tx.revision };
+  });
+  return { ...snapshot, ...result };
+}
+
+export async function saveConfig(target, input, { overwrite = false, expected, store = defaultStore, writeRecord = writeConfigFile } = {}) {
+  const config = validateConfig(input);
+  const canonical = path.join(await fs.realpath(path.dirname(target)), path.basename(target));
+  const lockKey = process.platform === 'win32' ? canonical.toLowerCase() : canonical;
+  return withLock(`config:${lockKey}`, async () => {
+    const actual = await readConfigRecord(target, { allowMissing: true });
+    if (actual.record && !overwrite) throw new ConfigError('Konfiguracja już istnieje. Użyj configure, aby ją zmienić.');
+    if (expected && expected.text !== actual.text) throw new ConfigError('Plik konfiguracji został zmieniony podczas operacji. Ponów configure.', 'CONFIG_CONFLICT');
+    const record = { schemaVersion: 2, credentialId: actual.record?.schemaVersion === 2 ? actual.record.credentialId : randomUUID() };
+    const { cleanupPending } = await store.transaction(record.credentialId, async tx => {
+      if (expected && Object.hasOwn(expected, 'credentialRevision') && expected.credentialRevision !== tx.revision) {
+        throw new ConfigError('Poświadczenia zmieniły się podczas konfiguracji. Ponów configure.', 'CONFIG_CONFLICT');
+      }
+      await tx.set(JSON.stringify(config));
+      await writeRecord(target, record, actual.text);
+    });
+    return { ...record, cleanupPending };
+  }, store.lockOptions);
+}
+
+export async function configStatus(target, { store = defaultStore } = {}) {
+  const { record, permissions } = await readConfigRecord(target);
+  if (record.schemaVersion === 1) return { schemaVersion: 1, credentials: 'invalid', permissions: `${permissions}: OK` };
+  try { connectionFromSecret(await store.get(record.credentialId)); }
+  catch (error) {
+    if (error.code !== 'CREDENTIAL_INVALID') throw error;
+    return { ...record, credentials: 'invalid', storage: 'system-keyring', permissions: `${permissions}: OK` };
+  }
+  return { ...record, credentials: 'configured', storage: 'system-keyring', permissions: `${permissions}: OK` };
+}
+export function apiOptions(config) { return { baseUrl: config.baseUrl, token: config.token, ...config.basicAuth }; }

package/lib/credential-encryption.mjs

@@ -0,0 +1,67 @@
+import { createCipheriv, createDecipheriv, hkdfSync, randomBytes } from 'node:crypto';
+import { ConfigError } from './config-errors.mjs';
+
+export const SERVICE = 'matomo-mcp-ro';
+export const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+export const MAX_SECRET_BYTES = 128 * 1024;
+// Ciphertext is base64; reserve space for the fixed envelope fields and salt/IV/tag.
+export const MAX_ENVELOPE_BYTES = Math.ceil(MAX_SECRET_BYTES / 3) * 4 + 512;
+const ALGORITHM = 'aes-256-gcm';
+const KDF = 'hkdf-sha256';
+const FIELDS = ['algorithm', 'ciphertext', 'iv', 'kdf', 'salt', 'tag', 'version'].join(',');
+const invalid = () => new ConfigError('Nieprawidłowa zaszyfrowana konfiguracja keyringu. Uruchom configure i podaj pełne dane.', 'CREDENTIAL_INVALID');
+
+function context(id, service) {
+  if (typeof id !== 'string' || !UUID_V4.test(id) || typeof service !== 'string' || !service) throw invalid();
+  return Buffer.from(JSON.stringify([service, 2, ALGORITHM, KDF, id]), 'utf8');
+}
+function deriveKey(id, salt, info) {
+  return Buffer.from(hkdfSync('sha256', Buffer.from(id, 'utf8'), salt, info, 32));
+}
+function decodeBase64(value, size) {
+  if (typeof value !== 'string' || !value) throw invalid();
+  const decoded = Buffer.from(value, 'base64');
+  if (decoded.toString('base64') !== value || size !== undefined && decoded.length !== size) throw invalid();
+  return decoded;
+}
+
+// The UUID is public: this envelope is an additional masking/authentication layer,
+// while the OS keyring remains the access boundary. No separate secret is stored.
+export function encryptCredential(raw, id, service = SERVICE) {
+  const info = context(id, service);
+  if (typeof raw !== 'string' || !raw || Buffer.byteLength(raw, 'utf8') > MAX_SECRET_BYTES) throw invalid();
+  const salt = randomBytes(32), iv = randomBytes(12);
+  const key = deriveKey(id, salt, info);
+  try {
+    const cipher = createCipheriv(ALGORITHM, key, iv, { authTagLength: 16 });
+    cipher.setAAD(info);
+    const ciphertext = Buffer.concat([cipher.update(raw, 'utf8'), cipher.final()]);
+    return JSON.stringify({ version: 2, algorithm: ALGORITHM, kdf: KDF,
+      salt: salt.toString('base64'), iv: iv.toString('base64'), tag: cipher.getAuthTag().toString('base64'),
+      ciphertext: ciphertext.toString('base64') });
+  } catch { throw invalid(); }
+  finally { key.fill(0); }
+}
+
+export function decryptCredential(raw, id, service = SERVICE) {
+  const info = context(id, service);
+  let key;
+  try {
+    if (typeof raw !== 'string' || !raw || Buffer.byteLength(raw, 'utf8') > MAX_ENVELOPE_BYTES) throw invalid();
+    const payload = JSON.parse(raw);
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)
+      || Object.keys(payload).sort().join(',') !== FIELDS
+      || payload.version !== 2 || payload.algorithm !== ALGORITHM || payload.kdf !== KDF) throw invalid();
+    const salt = decodeBase64(payload.salt, 32), iv = decodeBase64(payload.iv, 12);
+    const tag = decodeBase64(payload.tag, 16), ciphertext = decodeBase64(payload.ciphertext);
+    if (ciphertext.length > MAX_SECRET_BYTES) throw invalid();
+    key = deriveKey(id, salt, info);
+    const decipher = createDecipheriv(ALGORITHM, key, iv, { authTagLength: 16 });
+    decipher.setAAD(info);
+    decipher.setAuthTag(tag);
+    // No plaintext is returned until final() has authenticated the entire record.
+    const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return new TextDecoder('utf-8', { fatal: true }).decode(plaintext);
+  } catch { throw invalid(); }
+  finally { key?.fill(0); }
+}

package/lib/credential-store.mjs

@@ -0,0 +1,182 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { ConfigError } from './config-errors.mjs';
+import { withLock } from './locks.mjs';
+import { discoverSessionBus } from './session-env.mjs';
+import { SERVICE, UUID_V4, MAX_SECRET_BYTES, MAX_ENVELOPE_BYTES, encryptCredential, decryptCredential } from './credential-encryption.mjs';
+
+export { SERVICE, UUID_V4, MAX_SECRET_BYTES };
+// Base64 ASCII -> at most 2400 UTF-16LE bytes, below Windows' 2560-byte limit.
+export const CHUNK_CHARACTERS = 1200;
+const MAX_PARTS = Math.ceil(Math.ceil(MAX_ENVELOPE_BYTES / 3) * 4 / CHUNK_CHARACTERS);
+const digest = text => createHash('sha256').update(text).digest('hex');
+const manifestSchema = z.object({
+  storageVersion: z.union([z.literal(1), z.literal(2)]), generation: z.string().regex(UUID_V4),
+  parts: z.number().int().min(1).max(MAX_PARTS),
+  bytes: z.number().int().min(1).max(MAX_ENVELOPE_BYTES),
+  sha256: z.string().regex(/^[0-9a-f]{64}$/),
+}).strict();
+const invalid = () => new ConfigError('Wpis keyringu jest nieprawidłowy lub niekompletny. Uruchom configure, aby podać pełne dane.', 'CREDENTIAL_INVALID');
+function manifest(text) {
+  try {
+    if (typeof text !== 'string' || Buffer.byteLength(text, 'utf16le') > 2560) throw new Error();
+    const result = manifestSchema.parse(JSON.parse(text));
+    if (result.storageVersion === 1 && result.bytes > MAX_SECRET_BYTES) throw new Error();
+    if (result.parts !== Math.ceil(Math.ceil(result.bytes / 3) * 4 / CHUNK_CHARACTERS)) throw new Error();
+    return result;
+  } catch { throw invalid(); }
+}
+const partKey = (id, header, index) => `${id}:${header.generation}:${index}`;
+
+async function nativeEntry(service, account) {
+  await discoverSessionBus();
+  const { AsyncEntry } = await import('@napi-rs/keyring');
+  return new AsyncEntry(service, account, { linux: { store: 'secret-service' } });
+}
+
+export class SystemCredentialStore {
+  constructor({ entryFactory = nativeEntry, service = SERVICE, lockOptions } = {}) {
+    this.entryFactory = entryFactory;
+    this.service = service;
+    this.lockOptions = lockOptions;
+  }
+
+  async #call(account, method, value) {
+    try {
+      const entry = await this.entryFactory(this.service, account);
+      return await entry[method](...(value === undefined ? [] : [value]));
+    } catch {
+      throw new ConfigError('Systemowy keyring jest niedostępny lub odmówił operacji. Sprawdź dostęp i odblokowanie magazynu; na Linux również Secret Service oraz sesję D-Bus.', 'KEYRING_UNAVAILABLE');
+    }
+  }
+  async #read(account) {
+    const value = await this.#call(account, 'getPassword');
+    if (value === undefined || value === null) return null;
+    if (typeof value !== 'string') throw invalid();
+    return value;
+  }
+  async #write(account, value) {
+    if (Buffer.byteLength(value, 'utf16le') > 2560) throw invalid();
+    await this.#call(account, 'setPassword', value);
+  }
+  async #remove(account) { return this.#call(account, 'deleteCredential'); }
+
+  async #readPayload(id, root) {
+    if (root === null) return null;
+    const header = manifest(root);
+    // Old manifests are understood for cleanup only; their credentials are never read.
+    if (header.storageVersion !== 2) throw invalid();
+    const parts = [];
+    for (let index = 0; index < header.parts; index++) {
+      const text = await this.#read(partKey(id, header, index));
+      if (!text || text.length > CHUNK_CHARACTERS || !/^[A-Za-z0-9+/]+={0,2}$/.test(text)
+        || index < header.parts - 1 && text.length !== CHUNK_CHARACTERS) throw invalid();
+      parts.push(text);
+    }
+    const base64 = parts.join('');
+    const bytes = Buffer.from(base64, 'base64');
+    if (bytes.length !== header.bytes || bytes.toString('base64') !== base64 || digest(bytes) !== header.sha256) throw invalid();
+    let text;
+    try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); }
+    catch { throw invalid(); }
+    return decryptCredential(text, id, this.service);
+  }
+
+  async #cleanup(accounts) {
+    let pending = false;
+    for (const account of accounts) {
+      try {
+        await this.#remove(account);
+        if (await this.#read(account) !== null) pending = true;
+      } catch { pending = true; }
+    }
+    return pending;
+  }
+
+  // Keeps old fragments until the callback (including the metadata file commit)
+  // succeeds. Readers share this lock, including references in other projects.
+  async transaction(id, operation) {
+    if (typeof id !== 'string' || !UUID_V4.test(id)) throw new ConfigError('Nieprawidłowy identyfikator wpisu keyringu.');
+    return withLock(`credential:${this.service}:${id}`, async () => {
+      const before = await this.#read(id);
+      let current = before;
+      let changed = false;
+      let attempted = false;
+      const staged = [];
+      let result;
+      const tx = {
+        revision: before === null ? null : digest(before),
+        get: () => this.#readPayload(id, current),
+        set: async text => {
+          if (attempted) throw new ConfigError('Jedna operacja może zmienić wpis tylko raz.');
+          if (typeof text !== 'string' || !text.length || Buffer.byteLength(text, 'utf8') > MAX_SECRET_BYTES) throw invalid();
+          try { JSON.parse(text); } catch { throw invalid(); }
+          attempted = true;
+          const bytes = Buffer.from(encryptCredential(text, id, this.service), 'utf8');
+          const encoded = bytes.toString('base64');
+          const header = { storageVersion: 2, generation: randomUUID(), parts: Math.ceil(encoded.length / CHUNK_CHARACTERS), bytes: bytes.length, sha256: digest(bytes) };
+          const next = JSON.stringify(header);
+          for (let index = 0; index < header.parts; index++) {
+            const account = partKey(id, header, index);
+            const chunk = encoded.slice(index * CHUNK_CHARACTERS, (index + 1) * CHUNK_CHARACTERS);
+            staged.push(account); // Also clean writes that throw after committing.
+            await this.#write(account, chunk);
+            if (await this.#read(account) !== chunk) throw invalid();
+          }
+          if (await this.#readPayload(id, next) !== text) throw invalid();
+          if (await this.#read(id) !== before) throw new ConfigError('Wpis keyringu zmienił się podczas operacji. Ponów konfigurację.', 'CONFIG_CONFLICT');
+          current = next; // Record the attempted commit even if the native call throws.
+          changed = true;
+          await this.#write(id, next);
+          if (await this.#read(id) !== next) throw invalid();
+        },
+        delete: async () => {
+          if (attempted) throw new ConfigError('Jedna operacja może zmienić wpis tylko raz.');
+          attempted = true;
+          if (before === null) return false;
+          if (await this.#read(id) !== before) throw new ConfigError('Wpis keyringu zmienił się podczas operacji.', 'CONFIG_CONFLICT');
+          current = null;
+          changed = true;
+          await this.#remove(id);
+          if (await this.#read(id) !== null) throw invalid();
+          return true;
+        },
+      };
+      try { result = await operation(tx); }
+      catch (error) {
+        let recovered = true;
+        if (changed) {
+          try {
+            const actual = await this.#read(id);
+            if (actual === current) {
+              if (before === null) await this.#remove(id);
+              else await this.#write(id, before);
+            } else if (actual !== before) throw new Error();
+            if (await this.#read(id) !== before) throw new Error();
+          } catch { recovered = false; }
+        }
+        // On uncertain root recovery, retain fragments the root might still need.
+        if (recovered && await this.#cleanup(staged)) recovered = false;
+        if (!recovered) throw new ConfigError('Operacja nie powiodła się; nie udało się potwierdzić pełnego przywrócenia lub usunięcia nowych wpisów keyringu. Sprawdź status przed ponowieniem. Konfiguracja może wymagać naprawy.', 'KEYRING_RECOVERY_FAILED');
+        if (error instanceof ConfigError) throw error;
+        throw new ConfigError('Nie można zatwierdzić konfiguracji; poprzedni wpis keyringu został zachowany.', 'CONFIG_WRITE_FAILED');
+      }
+      let cleanupPending = false;
+      if (changed && before !== null) {
+        let old;
+        try { old = manifest(before); } catch { /* A repaired corrupt root has no trustworthy fragment list. */ }
+        if (old) cleanupPending = await this.#cleanup(Array.from({ length: old.parts }, (_, index) => partKey(id, old, index)));
+        else cleanupPending = true;
+      }
+      return { result, cleanupPending };
+    }, this.lockOptions);
+  }
+
+  async get(id) { return (await this.transaction(id, tx => tx.get())).result; }
+  async set(id, text) { return this.transaction(id, tx => tx.set(text)); }
+  async delete(id) {
+    const { result, cleanupPending } = await this.transaction(id, tx => tx.delete());
+    if (cleanupPending) throw new ConfigError('Wpis główny został usunięty, ale część jego fragmentów mogła pozostać w keyringu.', 'KEYRING_CLEANUP_FAILED');
+    return result;
+  }
+}