@dollhousemcp/mcp-server
Version:
DollhouseMCP - A Model Context Protocol (MCP) server that enables dynamic AI persona management from markdown files, allowing Claude and other compatible AI assistants to activate and switch between different behavioral personas.
180 lines • 7.58 kB
TypeScript
/**
* Gatekeeper Policy Engine
*
* Centralized access control enforcement for MCP-AQL operations.
* Implements a multi-layer defense-in-depth model:
*
* Layer 1: Route Validation (existing - validates endpoint/operation matching)
* Layer 2: Safety Tier Check (integrates @dollhousemcp/safety)
* Layer 3: Element Policy Check (active element restrictions)
* Layer 4: Permission Level Enforcement (AUTO_APPROVE, CONFIRM, DENY)
*
* Design Principles:
* - "LLM instructions are suggestions. Adapter policies are enforcement."
* - Session-scoped confirmations (no cross-session leakage)
* - Security-first (crash = fresh session)
* - Audit logging for all decisions
*/
import { CRUDEndpoint } from './OperationRouter.js';
import { GatekeeperSession, type ClientInfo } from './GatekeeperSession.js';
import { type GatekeeperConfigOptions } from './GatekeeperConfig.js';
import { PermissionLevel, type GatekeeperDecision, type EndpointPermissions, type CliApprovalRecord, type CliApprovalScope } from './GatekeeperTypes.js';
import { type ActiveElement } from './policies/index.js';
/**
* Input for Gatekeeper enforcement.
* Contains all context needed to make an access control decision.
*/
export interface EnforceInput {
/** The operation being requested */
operation: string;
/** The CRUD endpoint being called */
endpoint: CRUDEndpoint;
/** Element type being operated on (if applicable) */
elementType?: string;
/** Currently active elements for policy evaluation */
activeElements?: ActiveElement[];
/**
* Skip Layer 2 (element policy resolution) — use route-level defaults only.
* Used for gatekeeper infrastructure operations (confirm_operation, verify_challenge)
* to prevent cascading confirmation loops. Issue #758.
*/
skipElementPolicies?: boolean;
}
/**
* Gatekeeper Policy Engine.
*
* Central enforcement point for MCP-AQL access control.
* Validates that operations are called correctly and enforces
* permission policies based on operation type and active elements.
*/
export declare class Gatekeeper {
private readonly session;
private readonly config;
/**
* Permission flags for each CRUDE endpoint.
* These define the security characteristics of each endpoint.
*/
private static readonly ENDPOINT_PERMISSIONS;
constructor(clientInfo?: ClientInfo, configOptions?: GatekeeperConfigOptions);
/**
* Get the session ID for this Gatekeeper instance.
*/
get sessionId(): string;
/**
* Get a summary of the current session.
*/
getSessionSummary(): ReturnType<GatekeeperSession['getSummary']>;
/**
* Whether permission_prompt has been invoked this session (Issue #625 Phase 4).
*/
get isPermissionPromptActive(): boolean;
/**
* Mark that permission_prompt has been invoked (Issue #625 Phase 4).
*/
markPermissionPromptActive(): void;
/**
* Validates that an operation is being called via the correct endpoint.
* Throws an error if the operation doesn't exist or is called via wrong endpoint.
*
* This is Layer 1: Route Validation (existing PermissionGuard behavior).
*
* @param operation - The operation being called (e.g., 'create_element')
* @param calledEndpoint - The endpoint it was called through (e.g., 'CREATE')
* @throws Error if operation unknown or endpoint mismatch
*/
validateRoute(operation: string, calledEndpoint: CRUDEndpoint): void;
/**
* Enforce access control for an operation.
* This is the main entry point for policy enforcement.
*
* Checks:
* 1. Route validation (operation exists and matches endpoint)
* 2. Element policies (active elements' allow/confirm/deny lists)
* 3. Session confirmations (cached approvals)
* 4. Default operation policies (permission levels)
*
* @param input - The enforcement input containing operation context
* @returns A GatekeeperDecision indicating whether the operation is allowed
*/
enforce(input: EnforceInput): GatekeeperDecision;
/**
* Record a confirmation for an operation.
* Called when the user approves an operation that requires confirmation.
*
* @param operation - The operation being confirmed
* @param level - The permission level (CONFIRM_SESSION or CONFIRM_SINGLE_USE)
* @param elementType - Optional element type scope
*/
recordConfirmation(operation: string, level: PermissionLevel.CONFIRM_SESSION | PermissionLevel.CONFIRM_SINGLE_USE, elementType?: string): void;
/**
* Revoke a confirmation for an operation.
*
* @param operation - The operation to revoke
* @param elementType - Optional element type scope
* @returns true if a confirmation was revoked
*/
revokeConfirmation(operation: string, elementType?: string): boolean;
/**
* Revoke all confirmations for this session.
* Useful when security-sensitive changes occur.
*/
revokeAllConfirmations(): void;
/**
* Create a CLI approval request.
* Delegates to session and logs the event.
*/
createCliApprovalRequest(toolName: string, toolInput: Record<string, unknown>, riskLevel: string, riskScore: number, irreversible: boolean, denyReason: string, policySource?: string, ttlMs?: number): string;
/**
* Approve a pending CLI approval request.
*/
approveCliRequest(requestId: string, scope?: CliApprovalScope): CliApprovalRecord | undefined;
/**
* Check if a CLI tool call has a valid approval.
*/
checkCliApproval(toolName: string, toolInput: Record<string, unknown>): CliApprovalRecord | undefined;
/**
* Get all pending CLI approval requests.
*/
getPendingCliApprovals(): CliApprovalRecord[];
/**
* Gets the permission flags for an endpoint.
*
* @param endpoint - The CRUD endpoint to get permissions for
* @returns The permission flags for the endpoint
*/
static getPermissions(endpoint: CRUDEndpoint): EndpointPermissions;
/**
* Static validation method for backward compatibility with PermissionGuard.
* Validates that an operation is being called via the correct endpoint.
*
* @param operation - The operation being called
* @param calledEndpoint - The endpoint it was called through
* @throws Error if operation unknown or endpoint mismatch
*
* @deprecated Use instance method validateRoute() or enforce() instead
*/
static validate(operation: string, calledEndpoint: CRUDEndpoint): void;
/**
* Get the default permission level for an operation.
*
* @param operation - The operation name
* @returns The default permission level
*/
getDefaultPermissionLevel(operation: string): PermissionLevel;
/**
* Returns a human-readable reason for the permission classification.
*/
private getPermissionReason;
/**
* Static version of getPermissionReason for backward compatibility.
*/
private static getPermissionReasonStatic;
/**
* Log an audit event for a Gatekeeper decision.
*/
private logAuditEvent;
}
export { PermissionLevel, GatekeeperErrorCode } from './GatekeeperTypes.js';
export type { GatekeeperDecision, EndpointPermissions, ElementGatekeeperPolicy, ConfirmationRecord, CliApprovalRecord, CliApprovalScope, CliApprovalPolicy, RiskAssessment, } from './GatekeeperTypes.js';
export type { ClientInfo } from './GatekeeperSession.js';
//# sourceMappingURL=Gatekeeper.d.ts.map