@gohcltech/bitbucket-mcp/dist/auth-capabilities.js

Bitbucket integration for Claude via Model Context Protocol

/**
 * @fileoverview Authentication capabilities and scope management for Bitbucket MCP server.
 *
 * This module defines the capability scopes available for different authentication methods
 * and maps them to tool categories. It allows the server to dynamically determine which
 * tools should be available based on the authenticated user's capabilities.
 *
 * ## Authentication Methods and Capabilities
 *
 * **API Token (username + token)**
 * - User-account level access
 * - Can access all workspaces and repositories the user has permission to
 * - Full scope support for all tool categories
 *
 * **Repository Token (bearer token)**
 * - Single repository access only
 * - Limited to the specific repository it was created for
 * - Cannot access workspace management or issues
 *
 * ## Scope Definitions
 *
 * Capabilities are organized by Bitbucket API scope:
 * - `workspace:read` - Read workspace data (list workspaces, get workspace info)
 * - `workspace:admin` - Manage workspace (create, update, delete workspaces)
 * - `repository:read` - Read repository data
 * - `repository:write` - Write to repositories (create, update)
 * - `repository:admin` - Administer repositories (delete, settings)
 * - `pullrequest:read` - Read pull request data
 * - `pullrequest:write` - Create and manage pull requests
 * - `issue:read` - Read issues and issue tracking data
 * - `issue:write` - Create and manage issues
 * - `issue:admin` - Administer issue tracking
 */
import { AuthMethod } from './types.js';
/**
 * Individual capability scope names that map to Bitbucket API permissions.
 */
export var Capability;
(function (Capability) {
    Capability["WORKSPACE_READ"] = "workspace:read";
    Capability["WORKSPACE_ADMIN"] = "workspace:admin";
    Capability["REPOSITORY_READ"] = "repository:read";
    Capability["REPOSITORY_WRITE"] = "repository:write";
    Capability["REPOSITORY_ADMIN"] = "repository:admin";
    Capability["PULLREQUEST_READ"] = "pullrequest:read";
    Capability["PULLREQUEST_WRITE"] = "pullrequest:write";
    Capability["ISSUE_READ"] = "issue:read";
    Capability["ISSUE_WRITE"] = "issue:write";
    Capability["ISSUE_ADMIN"] = "issue:admin";
})(Capability || (Capability = {}));
/**
 * Tool categories that require specific capabilities to function.
 */
export var ToolCategory;
(function (ToolCategory) {
    ToolCategory["WORKSPACE"] = "workspace";
    ToolCategory["REPOSITORY"] = "repository";
    ToolCategory["BRANCH"] = "branch";
    ToolCategory["PULL_REQUEST"] = "pull_request";
    ToolCategory["COMMIT"] = "commit";
    ToolCategory["ISSUE"] = "issue";
})(ToolCategory || (ToolCategory = {}));
/**
 * Maps tool categories to their required capabilities.
 * If a capability is missing, the tool category will be filtered out.
 */
const TOOL_CAPABILITY_REQUIREMENTS = {
    [ToolCategory.WORKSPACE]: [Capability.WORKSPACE_READ],
    [ToolCategory.REPOSITORY]: [Capability.REPOSITORY_READ],
    [ToolCategory.BRANCH]: [Capability.REPOSITORY_READ],
    [ToolCategory.PULL_REQUEST]: [Capability.PULLREQUEST_READ],
    [ToolCategory.COMMIT]: [Capability.REPOSITORY_READ],
    [ToolCategory.ISSUE]: [Capability.ISSUE_READ],
};
/**
 * Capability sets for different authentication methods.
 * Defines what capabilities are available for each auth method.
 */
const AUTH_METHOD_CAPABILITIES = {
    [AuthMethod.API_TOKEN]: [
        // API Tokens have full access to workspaces and repositories
        Capability.WORKSPACE_READ,
        Capability.WORKSPACE_ADMIN,
        Capability.REPOSITORY_READ,
        Capability.REPOSITORY_WRITE,
        Capability.REPOSITORY_ADMIN,
        Capability.PULLREQUEST_READ,
        Capability.PULLREQUEST_WRITE,
        Capability.ISSUE_READ,
        Capability.ISSUE_WRITE,
        Capability.ISSUE_ADMIN,
    ],
    [AuthMethod.REPOSITORY_TOKEN]: [
        // Repository tokens are limited to single repository, no workspace or issue access
        Capability.REPOSITORY_READ,
        Capability.REPOSITORY_WRITE,
        Capability.PULLREQUEST_READ,
        Capability.PULLREQUEST_WRITE,
        // Notably missing:
        // - WORKSPACE_READ / WORKSPACE_ADMIN (cannot access workspace management)
        // - ISSUE_READ / ISSUE_WRITE / ISSUE_ADMIN (cannot access issue tracking)
    ],
};
/**
 * Represents the set of capabilities available to the current authentication.
 */
export class AuthCapabilities {
    capabilities;
    authMethod;
    /**
     * Creates a new AuthCapabilities instance from authentication config.
     *
     * @param authConfig - The authentication configuration
     */
    constructor(authConfig) {
        this.authMethod = authConfig.method;
        const caps = AUTH_METHOD_CAPABILITIES[authConfig.method] || [];
        this.capabilities = new Set(caps);
    }
    /**
     * Gets the authentication method used.
     *
     * @returns The authentication method
     */
    getAuthMethod() {
        return this.authMethod;
    }
    /**
     * Checks if a specific capability is available.
     *
     * @param capability - The capability to check
     * @returns True if the capability is available
     */
    hasCapability(capability) {
        return this.capabilities.has(capability);
    }
    /**
     * Checks if all required capabilities are available.
     *
     * @param capabilities - Array of capabilities to check
     * @returns True if all capabilities are available
     */
    hasAllCapabilities(capabilities) {
        return capabilities.every(cap => this.capabilities.has(cap));
    }
    /**
     * Gets all available capabilities.
     *
     * @returns Array of available capabilities
     */
    getAvailableCapabilities() {
        return Array.from(this.capabilities);
    }
    /**
     * Checks if a tool category is available based on current capabilities.
     *
     * @param category - The tool category to check
     * @returns True if the tool category's requirements are met
     */
    isToolCategoryAvailable(category) {
        const requirements = TOOL_CAPABILITY_REQUIREMENTS[category];
        if (!requirements) {
            // Unknown category, allow it
            return true;
        }
        return this.hasAllCapabilities(requirements);
    }
    /**
     * Gets all available tool categories.
     *
     * @returns Array of available tool categories
     */
    getAvailableToolCategories() {
        return Object.values(ToolCategory).filter(category => this.isToolCategoryAvailable(category));
    }
    /**
     * Gets tool categories that are NOT available (filtered out).
     *
     * @returns Array of unavailable tool categories
     */
    getUnavailableToolCategories() {
        return Object.values(ToolCategory).filter(category => !this.isToolCategoryAvailable(category));
    }
    /**
     * Gets a detailed description of why a tool category is unavailable.
     *
     * @param category - The tool category to check
     * @returns String describing missing capabilities, or empty string if available
     */
    getUnavailabilityReason(category) {
        if (this.isToolCategoryAvailable(category)) {
            return '';
        }
        const requirements = TOOL_CAPABILITY_REQUIREMENTS[category];
        if (!requirements) {
            return '';
        }
        const missing = requirements.filter(req => !this.capabilities.has(req));
        return `Missing capabilities: ${missing.join(', ')}`;
    }
}
/**
 * Creates an AuthCapabilities instance from authentication config.
 *
 * @param authConfig - The authentication configuration
 * @returns AuthCapabilities instance
 */
export function createAuthCapabilities(authConfig) {
    return new AuthCapabilities(authConfig);
}
//# sourceMappingURL=auth-capabilities.js.map