@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.
244 lines • 9.16 kB
TypeScript
/**
* Gatekeeper Type Definitions
*
* Type definitions for the Gatekeeper Policy Engine.
* These types define the permission system, policy structures,
* and enforcement results for MCP-AQL access control.
*/
import type { CRUDEndpoint } from './OperationRouter.js';
/**
* Permission levels for operation access control.
* These define how operations are approved or denied.
*/
export declare enum PermissionLevel {
/** Always allowed, no confirmation needed */
AUTO_APPROVE = "AUTO_APPROVE",
/** Confirm THIS instance only, ask again next time */
CONFIRM_SINGLE_USE = "CONFIRM_SINGLE_USE",
/** Confirm once, auto-approve for rest of session */
CONFIRM_SESSION = "CONFIRM_SESSION",
/** Never allowed (blocked by policy) */
DENY = "DENY"
}
/**
* Verification strictness levels.
* Define how aggressively the Gatekeeper challenges operations.
*/
export declare enum VerificationStrictness {
/** Only DANGER_ZONE operations require verification */
MINIMAL = "MINIMAL",
/** DANGER_ZONE + policy violations (default) */
STANDARD = "STANDARD",
/** Above + DELETE operations */
ELEVATED = "ELEVATED",
/** All mutations require verification */
MAXIMUM = "MAXIMUM"
}
/**
* Gatekeeper error codes for rich LLM error responses.
* Each code maps to a specific failure scenario with actionable guidance.
*/
export declare enum GatekeeperErrorCode {
/** Operation not found in the routing table */
UNKNOWN_OPERATION = "UNKNOWN_OPERATION",
/** Operation called via wrong CRUD endpoint */
ENDPOINT_MISMATCH = "ENDPOINT_MISMATCH",
/** Active element's policy blocks this operation */
ELEMENT_POLICY_VIOLATION = "ELEMENT_POLICY_VIOLATION",
/** Operation not allowed for this element type */
SCOPE_RESTRICTION = "SCOPE_RESTRICTION",
/** Denied by default operation policy */
PERMISSION_DENIED = "PERMISSION_DENIED",
/** User confirmation required before proceeding */
CONFIRMATION_REQUIRED = "CONFIRMATION_REQUIRED",
/** High-risk operation requires verification code */
VERIFICATION_REQUIRED = "VERIFICATION_REQUIRED",
/** Wrong verification code entered */
VERIFICATION_FAILED = "VERIFICATION_FAILED",
/** User did not respond to verification prompt */
VERIFICATION_TIMEOUT = "VERIFICATION_TIMEOUT",
/** Destructive pattern detected, operation blocked */
DANGER_ZONE_BLOCKED = "DANGER_ZONE_BLOCKED",
/** Session is invalid or expired */
SESSION_INVALID = "SESSION_INVALID"
}
/**
* Result of a Gatekeeper policy check.
* Indicates whether an operation is allowed and what actions are needed.
*/
export interface GatekeeperDecision {
/** Whether the operation is allowed to proceed */
allowed: boolean;
/** Permission level determined for this operation */
permissionLevel: PermissionLevel;
/** Error code if the operation is denied */
errorCode?: GatekeeperErrorCode;
/** Human-readable reason for the decision */
reason: string;
/** Actionable suggestion for the LLM on what to do next */
suggestion?: string;
/** Whether a confirmation is pending from the user */
confirmationPending?: boolean;
/** The policy source that determined this decision */
policySource?: 'operation_default' | 'element_policy' | 'safety_tier' | 'session_confirmation';
}
/**
* Confirmation record for session-scoped approvals.
* Tracks which operations have been confirmed for this session.
*/
export interface ConfirmationRecord {
/** The operation that was confirmed */
operation: string;
/** When the confirmation was granted */
confirmedAt: string;
/** The permission level that was confirmed */
permissionLevel: PermissionLevel.CONFIRM_SESSION | PermissionLevel.CONFIRM_SINGLE_USE;
/** Number of times this confirmation has been used */
useCount: number;
/** Optional element type scope for the confirmation */
elementType?: string;
}
/**
* Element-level Gatekeeper policy.
* Allows ANY DollhouseMCP element to define access control policies.
* These are stored in the element's metadata YAML front matter.
*/
export interface ElementGatekeeperPolicy {
/** Operations auto-approved when this element is active */
allow?: string[];
/** Operations requiring confirmation when this element is active */
confirm?: string[];
/** Operations blocked when this element is active */
deny?: string[];
/** Restrict operations to specific element types */
scopeRestrictions?: {
/** Allow operations only on these element types */
allowedTypes?: string[];
/** Block operations on these element types */
blockedTypes?: string[];
};
/** Advisory restrictions for external tools (CLI permission delegation) */
externalRestrictions?: {
/** Description of external restrictions */
description: string;
/** Patterns to deny for external tool operations */
denyPatterns?: string[];
/** Patterns requiring human approval before execution (Issue #1660).
* Evaluated after denyPatterns, before allowPatterns.
* Deny always takes precedence over confirm. */
confirmPatterns?: string[];
/** When defined, only tools matching at least one pattern are permitted (allowlist mode).
* Deny always takes precedence over allow. Across elements, allows are unioned. */
allowPatterns?: string[];
/** Approval policy for CLI tool operations (Issue #625 Phase 3) */
approvalPolicy?: CliApprovalPolicy;
};
}
/**
* Scope for CLI approval records.
* - 'single': consumed after one use
* - 'tool_session': all uses of that tool for the session
*/
export type CliApprovalScope = 'single' | 'tool_session';
/**
* Approval policy for CLI tool operations.
* Configures which risk levels need human approval.
*/
export interface CliApprovalPolicy {
/** Risk levels that require human approval before proceeding */
requireApproval?: ('moderate' | 'dangerous')[];
/** Default scope for approvals (default: 'single') */
defaultScope?: CliApprovalScope;
/** Time-to-live for pending approvals in seconds (30-3600, default: 300) */
ttlSeconds?: number;
}
/**
* Record of a CLI tool approval request.
* Created when permission_prompt encounters a tool that requires approval.
*/
export interface CliApprovalRecord {
/** Unique request identifier (format: cli-<UUIDv4>) */
requestId: string;
/** The tool that was requested */
toolName: string;
/** The tool input parameters */
toolInput: Record<string, unknown>;
/** Risk level from classification */
riskLevel: string;
/** Numeric risk score (0-100) */
riskScore: number;
/** Whether the operation is irreversible */
irreversible: boolean;
/** When the request was created */
requestedAt: string;
/** When the request was approved (undefined if pending) */
approvedAt?: string;
/** Whether this approval has been consumed */
consumed: boolean;
/** Approval scope */
scope: CliApprovalScope;
/** Reason the tool was denied (pending approval) */
denyReason: string;
/** Which policy source triggered the approval requirement */
policySource?: string;
/** Per-record TTL in milliseconds (overrides default 300s) */
ttlMs?: number;
}
/**
* Risk assessment for a CLI tool call.
* Provides a numeric score and irreversibility indicator.
*/
export interface RiskAssessment {
/** Numeric risk score (0-100) */
score: number;
/** Whether the operation is irreversible */
irreversible: boolean;
/** Factors that contributed to the risk score */
factors: string[];
}
/**
* Endpoint permissions for CRUD endpoints.
* Defines the security characteristics of each endpoint.
*/
export interface EndpointPermissions {
/** Whether the endpoint only reads data */
readOnly: boolean;
/** Whether the endpoint can perform destructive operations */
destructive: boolean;
}
/**
* Audit log entry for Gatekeeper decisions.
* Logged to SecurityMonitor for security analysis.
*/
export interface GatekeeperAuditEntry {
/** Timestamp of the decision */
timestamp: string;
/** Session ID that made the request */
sessionId: string;
/** Operation that was checked */
operation: string;
/** CRUD endpoint used */
endpoint: CRUDEndpoint;
/** Element type if applicable */
elementType?: string;
/** The decision made */
decision: GatekeeperDecision;
/** Client information if available */
clientInfo?: {
name: string;
version: string;
};
}
/**
* Operation policy mapping entry.
* Defines the default permission level for an operation.
*/
export interface OperationPolicy {
/** Default permission level for this operation */
defaultLevel: PermissionLevel;
/** Human-readable description of why this level is assigned */
rationale: string;
/** Whether this operation can be elevated by active elements */
canBeElevated?: boolean;
}
//# sourceMappingURL=GatekeeperTypes.d.ts.map