@viberqc/mcp-server 0.1.0

package/dist/repository/git-files.js

@@ -0,0 +1,77 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { DEFAULT_REPOSITORY_SCOPE, } from '../contracts/repository.js';
+const execFileAsync = promisify(execFile);
+export class RepositoryGitError extends Error {
+    code = 'GIT_FILE_LIST_FAILED';
+    constructor() {
+        super('Git could not provide a safe repository file list.');
+        this.name = 'RepositoryGitError';
+    }
+}
+async function runGitNullList(root, args) {
+    let result;
+    try {
+        result = await execFileAsync('git', ['-C', root.absolutePath, ...args], {
+            encoding: 'buffer',
+            maxBuffer: 20 * 1024 * 1024,
+        });
+    }
+    catch {
+        throw new RepositoryGitError();
+    }
+    return result.stdout
+        .toString('utf8')
+        .split('\0')
+        .filter((entry) => entry.length > 0);
+}
+function addStates(files, paths, state) {
+    for (const relativePath of paths) {
+        const states = files.get(relativePath) ?? new Set();
+        states.add(state);
+        files.set(relativePath, states);
+    }
+}
+const STATE_ORDER = [
+    'tracked',
+    'staged',
+    'unstaged',
+    'untracked',
+];
+export async function listRepositoryCandidates(root, scope = DEFAULT_REPOSITORY_SCOPE) {
+    const [tracked, staged, unstaged, untracked] = await Promise.all([
+        runGitNullList(root, ['ls-files', '-z', '--cached']),
+        runGitNullList(root, [
+            'diff',
+            '--cached',
+            '--name-only',
+            '--diff-filter=ACMRTUXB',
+            '-z',
+        ]),
+        runGitNullList(root, [
+            'diff',
+            '--name-only',
+            '--diff-filter=ACMRTUXB',
+            '-z',
+        ]),
+        runGitNullList(root, [
+            'ls-files',
+            '-z',
+            '--others',
+            '--exclude-standard',
+        ]),
+    ]);
+    const files = new Map();
+    if (scope === 'full') {
+        addStates(files, tracked, 'tracked');
+    }
+    addStates(files, staged, 'staged');
+    addStates(files, unstaged, 'unstaged');
+    addStates(files, untracked, 'untracked');
+    return [...files.entries()]
+        .map(([relativePath, states]) => ({
+        relativePath,
+        states: STATE_ORDER.filter((state) => states.has(state)),
+    }))
+        .sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}

package/dist/repository/identity.js

@@ -0,0 +1,72 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export class RepositoryIdentityError extends Error {
+    code;
+    constructor(code) {
+        super(code === 'REPOSITORY_NOT_AUTHORIZED'
+            ? 'The repository does not match the Project Token.'
+            : 'A safe repository identity could not be established.');
+        this.name = 'RepositoryIdentityError';
+        this.code = code;
+    }
+}
+function normalizedHostPath(host, repositoryPath) {
+    const cleanPath = repositoryPath
+        .replace(/^\/+/, '')
+        .replace(/\/+$/, '')
+        .replace(/\.git$/i, '');
+    if (!host || !cleanPath || cleanPath.includes('..')) {
+        throw new RepositoryIdentityError('REMOTE_INVALID');
+    }
+    return `${host.toLowerCase()}/${cleanPath.toLowerCase()}`;
+}
+export function normalizeGitRemote(remote) {
+    const candidate = remote.trim();
+    const scpStyle = candidate.match(/^(?:[^@/\s]+@)?([^:/\s]+):(.+)$/);
+    if (scpStyle && !candidate.includes('://')) {
+        return normalizedHostPath(scpStyle[1], scpStyle[2]);
+    }
+    let parsed;
+    try {
+        parsed = new URL(candidate);
+    }
+    catch {
+        throw new RepositoryIdentityError('REMOTE_INVALID');
+    }
+    if (!['git:', 'http:', 'https:', 'ssh:'].includes(parsed.protocol)) {
+        throw new RepositoryIdentityError('REMOTE_INVALID');
+    }
+    return normalizedHostPath(parsed.host, parsed.pathname);
+}
+async function readPrimaryRemote(root) {
+    try {
+        const result = await execFileAsync('git', ['-C', root.absolutePath, 'config', '--get', 'remote.origin.url'], { encoding: 'utf8' });
+        const remote = result.stdout.trim();
+        return remote.length > 0 ? remote : null;
+    }
+    catch (error) {
+        if (typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            error.code === 1) {
+            return null;
+        }
+        throw new RepositoryIdentityError('REMOTE_INVALID');
+    }
+}
+export async function resolveRepositoryIdentity(root, localRepositoryId) {
+    const remote = await readPrimaryRemote(root);
+    if (remote) {
+        return { kind: 'remote', value: normalizeGitRemote(remote) };
+    }
+    if (!localRepositoryId || !/^vqc_local_[A-Za-z0-9_-]{16,}$/.test(localRepositoryId)) {
+        throw new RepositoryIdentityError('LOCAL_ID_REQUIRED');
+    }
+    return { kind: 'local', value: localRepositoryId };
+}
+export function assertRepositoryAuthorized(actual, allowed) {
+    if (actual.kind !== allowed.kind || actual.value !== allowed.value) {
+        throw new RepositoryIdentityError('REPOSITORY_NOT_AUTHORIZED');
+    }
+}

package/dist/repository/inventory.js

@@ -0,0 +1,91 @@
+import { DEFAULT_REPOSITORY_SCOPE, } from '../contracts/repository.js';
+import { classifyPathByCentralPolicy, fileLooksBinary, } from '../security/content-policy.js';
+import { RepositoryBoundaryError, validateRepositoryFile, } from '../security/path-policy.js';
+import { assertExternalPayloadSafe } from '../security/redaction.js';
+import { listRepositoryCandidates } from './git-files.js';
+import { isViberQcIgnored, loadViberQcIgnoreRules, } from './viberqc-ignore.js';
+function boundaryErrorToSkipReason(error) {
+    if (error.code === 'PATH_SYMLINK') {
+        return 'symlink';
+    }
+    if (error.code === 'PATH_MISSING') {
+        return 'missing';
+    }
+    if (error.code === 'PATH_NOT_FILE') {
+        return 'not-file';
+    }
+    return 'central-policy';
+}
+function countSkipReason(counts, reason) {
+    counts[reason] = (counts[reason] ?? 0) + 1;
+}
+export async function buildRepositoryInventory(root, options = {}) {
+    const scope = options.scope ?? DEFAULT_REPOSITORY_SCOPE;
+    const [candidates, ignoreRules] = await Promise.all([
+        listRepositoryCandidates(root, scope),
+        loadViberQcIgnoreRules(root),
+    ]);
+    const files = [];
+    const skipped = [];
+    const skipReasons = {};
+    for (const candidate of candidates) {
+        let reason = classifyPathByCentralPolicy(candidate.relativePath);
+        if (!reason && options.organizationPolicy) {
+            try {
+                if (options.organizationPolicy(candidate.relativePath)) {
+                    reason = 'organization-policy';
+                }
+            }
+            catch {
+                reason = 'organization-policy';
+            }
+        }
+        if (!reason && isViberQcIgnored(candidate.relativePath, ignoreRules)) {
+            reason = 'viberqcignore';
+        }
+        if (reason) {
+            skipped.push({ relativePath: candidate.relativePath, reason });
+            countSkipReason(skipReasons, reason);
+            continue;
+        }
+        try {
+            const file = await validateRepositoryFile(root, candidate.relativePath);
+            if (await fileLooksBinary(file.absolutePath)) {
+                reason = 'binary';
+            }
+        }
+        catch (error) {
+            reason =
+                error instanceof RepositoryBoundaryError
+                    ? boundaryErrorToSkipReason(error)
+                    : 'central-policy';
+        }
+        if (reason) {
+            skipped.push({ relativePath: candidate.relativePath, reason });
+            countSkipReason(skipReasons, reason);
+            continue;
+        }
+        files.push(candidate);
+    }
+    return {
+        scope,
+        files,
+        skipped,
+        totals: {
+            candidates: candidates.length,
+            included: files.length,
+            skipped: skipped.length,
+        },
+        skipReasons,
+    };
+}
+export function buildExternalRepositorySummary(inventory) {
+    const summary = {
+        scope: inventory.scope,
+        fileCount: inventory.totals.included,
+        skippedCount: inventory.totals.skipped,
+        skipReasons: { ...inventory.skipReasons },
+    };
+    assertExternalPayloadSafe(summary);
+    return summary;
+}

package/dist/repository/viberqc-ignore.js

@@ -0,0 +1,94 @@
+import { lstat, readFile } from 'node:fs/promises';
+import path from 'node:path';
+const MAX_IGNORE_BYTES = 64 * 1024;
+const MAX_IGNORE_RULES = 1_024;
+const MAX_PATTERN_LENGTH = 512;
+export class ViberQcIgnoreError extends Error {
+    code = 'VIBERQC_IGNORE_UNAVAILABLE';
+    constructor() {
+        super('The repository ignore policy could not be applied safely.');
+        this.name = 'ViberQcIgnoreError';
+    }
+}
+function escapeRegexCharacter(character) {
+    return /[\\^$.*+?()[\]{}|]/.test(character)
+        ? `\\${character}`
+        : character;
+}
+function globToRegex(pattern) {
+    let source = '';
+    for (let index = 0; index < pattern.length; index += 1) {
+        const character = pattern[index];
+        const next = pattern[index + 1];
+        if (character === '*' && next === '*') {
+            source += '.*';
+            index += 1;
+        }
+        else if (character === '*') {
+            source += '[^/]*';
+        }
+        else if (character === '?') {
+            source += '[^/]';
+        }
+        else {
+            source += escapeRegexCharacter(character);
+        }
+    }
+    return new RegExp(`^${source}$`);
+}
+export async function loadViberQcIgnoreRules(root) {
+    const ignorePath = path.join(root.absolutePath, '.viberqcignore');
+    try {
+        const info = await lstat(ignorePath);
+        if (!info.isFile() || info.isSymbolicLink() || info.size > MAX_IGNORE_BYTES) {
+            throw new ViberQcIgnoreError();
+        }
+        const contents = await readFile(ignorePath, 'utf8');
+        return contents
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0 &&
+            line.length <= MAX_PATTERN_LENGTH &&
+            !line.startsWith('#') &&
+            !line.startsWith('!'))
+            .slice(0, MAX_IGNORE_RULES)
+            .map((line) => {
+            const directory = line.endsWith('/');
+            const withoutDirectoryMarker = directory ? line.slice(0, -1) : line;
+            const normalized = withoutDirectoryMarker.replace(/^\/+/, '');
+            return {
+                directory,
+                hasSlash: normalized.includes('/'),
+                regex: globToRegex(normalized),
+            };
+        });
+    }
+    catch (error) {
+        if (typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            error.code === 'ENOENT') {
+            return [];
+        }
+        if (error instanceof ViberQcIgnoreError) {
+            throw error;
+        }
+        throw new ViberQcIgnoreError();
+    }
+}
+export function isViberQcIgnored(relativePath, rules) {
+    const portable = relativePath.replaceAll('\\', '/');
+    const segments = portable.split('/');
+    return rules.some((rule) => {
+        if (rule.hasSlash) {
+            if (rule.regex.test(portable)) {
+                return true;
+            }
+            if (rule.directory) {
+                return segments.some((_, index) => rule.regex.test(segments.slice(0, index + 1).join('/')));
+            }
+            return false;
+        }
+        return segments.some((segment) => rule.regex.test(segment));
+    });
+}

package/dist/security/content-policy.js

@@ -0,0 +1,147 @@
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import path from 'node:path';
+const BLOCKED_DIRECTORIES = new Map([
+    ['.aws', 'secret'],
+    ['.azure', 'secret'],
+    ['.gcloud', 'secret'],
+    ['.git', 'git-metadata'],
+    ['.kube', 'secret'],
+    ['.next', 'build-output'],
+    ['.nuxt', 'build-output'],
+    ['.output', 'build-output'],
+    ['.parcel-cache', 'build-output'],
+    ['.ssh', 'secret'],
+    ['.turbo', 'build-output'],
+    ['build', 'build-output'],
+    ['coverage', 'build-output'],
+    ['dist', 'build-output'],
+    ['node_modules', 'dependency'],
+    ['out', 'build-output'],
+    ['target', 'build-output'],
+]);
+const BINARY_EXTENSIONS = new Set([
+    '.7z',
+    '.a',
+    '.avi',
+    '.bin',
+    '.bmp',
+    '.class',
+    '.dmg',
+    '.doc',
+    '.docx',
+    '.eot',
+    '.exe',
+    '.gif',
+    '.gz',
+    '.ico',
+    '.jar',
+    '.jpeg',
+    '.jpg',
+    '.mov',
+    '.mp3',
+    '.mp4',
+    '.o',
+    '.otf',
+    '.pdf',
+    '.png',
+    '.ppt',
+    '.pptx',
+    '.pyc',
+    '.so',
+    '.tar',
+    '.tiff',
+    '.ttf',
+    '.wasm',
+    '.webm',
+    '.webp',
+    '.woff',
+    '.woff2',
+    '.xls',
+    '.xlsx',
+    '.zip',
+]);
+const SECRET_EXTENSIONS = new Set([
+    '.der',
+    '.jks',
+    '.key',
+    '.p12',
+    '.pfx',
+    '.pkcs12',
+    '.ppk',
+]);
+const SECRET_FILE_NAMES = new Set([
+    '.dockerconfigjson',
+    '.git-credentials',
+    '.netrc',
+    '.npmrc',
+    '.pypirc',
+    'credentials',
+    'credentials.json',
+    'id_dsa',
+    'id_ed25519',
+    'id_ecdsa',
+    'id_rsa',
+    'kubeconfig',
+    'service-account.json',
+]);
+export function classifyPathByCentralPolicy(relativePath) {
+    const portable = relativePath.replaceAll('\\', '/');
+    const segments = portable.split('/');
+    const lowerSegments = segments.map((segment) => segment.toLowerCase());
+    for (const segment of lowerSegments.slice(0, -1)) {
+        const blocked = BLOCKED_DIRECTORIES.get(segment);
+        if (blocked) {
+            return blocked;
+        }
+    }
+    const fileName = lowerSegments.at(-1) ?? '';
+    if (fileName === '.viberqcignore') {
+        return 'central-policy';
+    }
+    if (fileName === '.env' || fileName.startsWith('.env.')) {
+        return 'secret';
+    }
+    const extension = path.posix.extname(fileName);
+    if (SECRET_EXTENSIONS.has(extension) ||
+        SECRET_FILE_NAMES.has(fileName) ||
+        fileName.endsWith('.credentials.json') ||
+        /^service-account(?:[._-].+)?\.json$/.test(fileName)) {
+        return 'secret';
+    }
+    if (extension === '.pem' || fileName.endsWith('.private-key')) {
+        return 'secret';
+    }
+    if (BINARY_EXTENSIONS.has(extension)) {
+        return 'binary';
+    }
+    return null;
+}
+export function bufferLooksBinary(buffer) {
+    if (buffer.length === 0) {
+        return false;
+    }
+    let suspiciousBytes = 0;
+    for (const byte of buffer) {
+        if (byte === 0) {
+            return true;
+        }
+        if (byte < 7 ||
+            (byte > 13 && byte < 32) ||
+            byte === 127) {
+            suspiciousBytes += 1;
+        }
+    }
+    return suspiciousBytes / buffer.length > 0.3;
+}
+export async function fileLooksBinary(absolutePath, maxBytes = 8_192) {
+    const handle = await open(absolutePath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const buffer = Buffer.alloc(maxBytes);
+        const { bytesRead } = await handle.read(buffer, 0, maxBytes, 0);
+        return bufferLooksBinary(buffer.subarray(0, bytesRead));
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/security/path-policy.js

@@ -0,0 +1,167 @@
+import { execFile } from 'node:child_process';
+import { lstat, realpath, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+const SAFE_MESSAGES = {
+    PATH_ABSOLUTE: 'Absolute candidate paths are not allowed.',
+    PATH_MISSING: 'The candidate file is unavailable.',
+    PATH_NOT_FILE: 'The candidate is not a regular file.',
+    PATH_OUTSIDE_ROOT: 'The candidate is outside the authorized repository.',
+    PATH_SYMLINK: 'Symbolic links are not followed.',
+    PATH_TRAVERSAL: 'Parent path traversal is not allowed.',
+    REPO_ROOT_AMBIGUOUS: 'More than one trusted repository root was supplied.',
+    REPO_ROOT_FORBIDDEN: 'This directory cannot be used as a repository root.',
+    REPO_ROOT_MISSING: 'No trusted repository root was supplied.',
+    REPO_ROOT_NOT_DIRECTORY: 'The repository root is not a directory.',
+    REPO_ROOT_NOT_GIT: 'The repository root is not a Git work tree.',
+    REPO_ROOT_NOT_TOPLEVEL: 'The repository root must be the Git top-level directory.',
+};
+export class RepositoryBoundaryError extends Error {
+    code;
+    constructor(code) {
+        super(SAFE_MESSAGES[code]);
+        this.name = 'RepositoryBoundaryError';
+        this.code = code;
+    }
+}
+function chooseTrustedRoot(sources) {
+    const mcpRoots = (sources.mcpRoots ?? []).filter((candidate) => candidate.trim().length > 0);
+    if (mcpRoots.length > 1) {
+        throw new RepositoryBoundaryError('REPO_ROOT_AMBIGUOUS');
+    }
+    const selected = mcpRoots[0] ?? sources.configuredRoot?.trim();
+    if (!selected) {
+        throw new RepositoryBoundaryError('REPO_ROOT_MISSING');
+    }
+    return selected;
+}
+function isInsideRoot(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return (relative.length > 0 &&
+        relative !== '..' &&
+        !relative.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(relative));
+}
+function normalizeCandidatePath(candidate) {
+    const portable = candidate.replaceAll('\\', '/');
+    if (path.posix.isAbsolute(portable) ||
+        path.win32.isAbsolute(candidate) ||
+        /^[A-Za-z]:/.test(candidate) ||
+        portable.split('/').includes('..')) {
+        throw new RepositoryBoundaryError(path.posix.isAbsolute(portable) ||
+            path.win32.isAbsolute(candidate) ||
+            /^[A-Za-z]:/.test(candidate)
+            ? 'PATH_ABSOLUTE'
+            : 'PATH_TRAVERSAL');
+    }
+    const normalized = path.posix.normalize(portable);
+    if (normalized.length === 0 ||
+        normalized === '.' ||
+        normalized === '..' ||
+        normalized.startsWith('../')) {
+        throw new RepositoryBoundaryError('PATH_TRAVERSAL');
+    }
+    return normalized;
+}
+async function assertNoSymlinkSegments(root, relativePath) {
+    let current = root;
+    for (const segment of relativePath.split('/')) {
+        current = path.join(current, segment);
+        try {
+            const info = await lstat(current);
+            if (info.isSymbolicLink()) {
+                throw new RepositoryBoundaryError('PATH_SYMLINK');
+            }
+        }
+        catch (error) {
+            if (error instanceof RepositoryBoundaryError) {
+                throw error;
+            }
+            throw new RepositoryBoundaryError('PATH_MISSING');
+        }
+    }
+}
+export async function validateRepositoryRoot(sources) {
+    const selected = chooseTrustedRoot(sources);
+    let canonicalRoot;
+    try {
+        canonicalRoot = await realpath(selected);
+    }
+    catch {
+        throw new RepositoryBoundaryError('REPO_ROOT_MISSING');
+    }
+    let rootInfo;
+    try {
+        rootInfo = await stat(canonicalRoot);
+    }
+    catch {
+        throw new RepositoryBoundaryError('REPO_ROOT_MISSING');
+    }
+    if (!rootInfo.isDirectory()) {
+        throw new RepositoryBoundaryError('REPO_ROOT_NOT_DIRECTORY');
+    }
+    let canonicalHome = homedir();
+    try {
+        canonicalHome = await realpath(canonicalHome);
+    }
+    catch {
+        // Comparing against the unresolved home path is safer than allowing it.
+    }
+    if (canonicalRoot === path.parse(canonicalRoot).root ||
+        canonicalRoot === canonicalHome) {
+        throw new RepositoryBoundaryError('REPO_ROOT_FORBIDDEN');
+    }
+    let gitTopLevel;
+    try {
+        const result = await execFileAsync('git', ['-C', canonicalRoot, 'rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+        gitTopLevel = result.stdout.trim();
+    }
+    catch {
+        throw new RepositoryBoundaryError('REPO_ROOT_NOT_GIT');
+    }
+    let canonicalGitTopLevel;
+    try {
+        canonicalGitTopLevel = await realpath(gitTopLevel);
+    }
+    catch {
+        throw new RepositoryBoundaryError('REPO_ROOT_NOT_GIT');
+    }
+    if (canonicalGitTopLevel !== canonicalRoot) {
+        throw new RepositoryBoundaryError('REPO_ROOT_NOT_TOPLEVEL');
+    }
+    return Object.freeze({ absolutePath: canonicalRoot });
+}
+export async function validateRepositoryFile(root, candidate) {
+    const relativePath = normalizeCandidatePath(candidate);
+    await assertNoSymlinkSegments(root.absolutePath, relativePath);
+    const lexicalPath = path.resolve(root.absolutePath, ...relativePath.split('/'));
+    if (!isInsideRoot(root.absolutePath, lexicalPath)) {
+        throw new RepositoryBoundaryError('PATH_OUTSIDE_ROOT');
+    }
+    let canonicalPath;
+    try {
+        canonicalPath = await realpath(lexicalPath);
+    }
+    catch {
+        throw new RepositoryBoundaryError('PATH_MISSING');
+    }
+    if (!isInsideRoot(root.absolutePath, canonicalPath)) {
+        throw new RepositoryBoundaryError('PATH_OUTSIDE_ROOT');
+    }
+    let fileInfo;
+    try {
+        fileInfo = await stat(canonicalPath);
+    }
+    catch {
+        throw new RepositoryBoundaryError('PATH_MISSING');
+    }
+    if (!fileInfo.isFile()) {
+        throw new RepositoryBoundaryError('PATH_NOT_FILE');
+    }
+    return Object.freeze({
+        absolutePath: canonicalPath,
+        relativePath,
+    });
+}