@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.
148 lines • 6.09 kB
TypeScript
/**
* Element Policies
*
* Handles element-based access control for the Gatekeeper.
* Allows ANY DollhouseMCP element to define policies in its metadata
* that override or restrict the default operation policies.
*
* Policy Resolution Order:
* 1. Active element deny list (highest priority - blocks operation)
* 2. Active element confirm list (requires confirmation)
* 3. Active element allow list (auto-approves)
* 4. Operation default permission (fallback)
*/
import { PermissionLevel, type ElementGatekeeperPolicy, type GatekeeperDecision } from '../GatekeeperTypes.js';
/**
* Metadata structure for elements with Gatekeeper policies.
* The 'gatekeeper' field is optional and contains policy definitions.
*/
export interface ElementMetadataWithPolicy {
name: string;
description?: string;
gatekeeper?: ElementGatekeeperPolicy;
[key: string]: unknown;
}
/**
* Active element for policy evaluation.
* Represents an element currently active in the session.
*/
export interface ActiveElement {
type: string;
name: string;
metadata: ElementMetadataWithPolicy;
}
export interface GatekeeperPolicyDiagnostics {
valid: false;
enforceable: false;
message: string;
}
/**
* Result of element policy resolution.
* Contains the effective permission level and policy source.
*/
export interface ElementPolicyResult {
/** Effective permission level after element policy application */
permissionLevel: PermissionLevel;
/** Which element's policy determined this result */
sourceElement?: string;
/** The specific policy field that matched (allow/confirm/deny) */
matchedPolicy?: 'allow' | 'confirm' | 'deny' | 'scope_restriction';
/** Whether the operation was blocked by scope restrictions */
scopeBlocked?: boolean;
/**
* Elements that wanted to auto-approve this operation but were overridden
* by a higher-priority confirm or deny policy from another element.
* Issue #674: allow cannot override confirm.
*/
conflictingElements?: Array<{
name: string;
wantedLevel: PermissionLevel;
}>;
}
/**
* Resolve the effective permission level for an operation
* considering all active elements and their policies.
*
* @param operation - The operation to check
* @param activeElements - Currently active elements with their metadata
* @param targetElementType - Optional element type being operated on
* @returns The resolved policy result
*/
export declare function resolveElementPolicy(operation: string, activeElements: ActiveElement[], targetElementType?: string): ElementPolicyResult;
/**
* Create a Gatekeeper decision from element policy resolution.
*
* @param operation - The operation that was checked
* @param result - The element policy resolution result
* @param targetElementType - Optional element type being operated on
* @returns A GatekeeperDecision object
*/
export declare function createDecisionFromPolicy(operation: string, result: ElementPolicyResult, targetElementType?: string): GatekeeperDecision;
/**
* Parse and validate a Gatekeeper policy from element metadata.
*
* @param metadata - The element metadata to parse
* @returns The parsed policy, or undefined if no policy is defined
* @throws Error if the policy is malformed
*/
export declare function parseElementPolicy(metadata: unknown): ElementGatekeeperPolicy | undefined;
/**
* Validate authored gatekeeper input before save.
*
* Authoring-time validation is stricter than load-time sanitization: it should
* reject misplaced policy blocks instead of silently saving an element that
* later appears active but has non-enforceable external restrictions.
*/
export declare function getGatekeeperAuthoringErrors(record: Record<string, unknown> | undefined): string[];
/**
* Analyze externalRestrictions patterns for common mistakes and suspicious syntax.
*
* Returns non-fatal warnings to help LLMs and users write effective patterns.
* Does NOT throw — validation errors are handled by {@link validatePatternStrings}.
*
* Checks performed (Issue #1664):
* - Missing tool prefix (pattern doesn't start with ToolName:)
* - Overly broad patterns (bare `*` or `ToolName:*`)
* - Regex syntax that won't work in glob matching
* - Leading/trailing whitespace
*
* @param patterns - Array of pattern strings to analyze
* @param fieldName - Field name for warning messages
* @returns Array of warning messages (empty if no issues found)
*/
export declare function analyzePatternSyntax(patterns: string[], fieldName: string): string[];
/**
* Check if an operation is a gatekeeper infrastructure operation that should
* skip element policy evaluation in the primary enforcement path.
* Exported for use by MCPAQLHandler. Issue #758.
*/
export declare function isGatekeeperInfraOperation(operation: string): boolean;
/**
* Check if any active elements deny confirm_operation (nuclear sandbox).
* Returns the denying element name if found, undefined otherwise.
*/
export declare function findConfirmDenyingElement(activeElements: Array<{
name: string;
type: string;
metadata: Record<string, unknown>;
}>): {
name: string;
type: string;
} | undefined;
/**
* Check if any active elements have confirm_operation in their confirm list (advisory).
* Returns the element names that request additional scrutiny.
*/
export declare function findConfirmAdvisoryElements(activeElements: Array<{
name: string;
type: string;
metadata: Record<string, unknown>;
}>): Array<{
name: string;
type: string;
}>;
export declare function sanitizeGatekeeperPolicy(rawPolicy: unknown, elementName: string, elementType: string, diagnosticsTarget?: Record<string, unknown>): ElementGatekeeperPolicy | undefined;
export declare function attachGatekeeperDiagnostics(target: unknown, message: string): void;
export declare function clearGatekeeperDiagnostics(target: unknown): void;
export declare function getGatekeeperDiagnostics(target: unknown): GatekeeperPolicyDiagnostics | undefined;
//# sourceMappingURL=ElementPolicies.d.ts.map