Vigil

Brought to you by Ilyes Makdoud and Thierry Janaudy.

This project also relies on:

• Vigil Auth: A WebAuthN implementation for the authentication of actors via web
• Vigil HSM: A HashiCorp Vault Transit Secrets Engine

Statistics

• TypeScript Files: 7,714
• Total Lines of Code: 38,091

Generic Entitlement Layer

Vigil is a generic entitlement layer designed to abstract crypto-providers and custodians. It functions as a unified control plane for managing digital asset operations, policies, and entitlements across disparate underlying providers (e.g., DFNS, Swiss / Zodia, Fireblocks, Ripple Custody, Ledger Enterprise).

Vigil enforces a strict "intent-based" architecture where every operation is treated as a Wish that must pass through a rigorous lifecycle of policy evaluation and control before execution. This ensures that organizational governance is consistently applied regardless of the underlying execution layer.

High-Level Architecture

The Flow of CUD Wishes

Vigil manages the lifecycle of a "Wish"—an immutable intent to change the system state.

The lifecycle of a Wish proceeds as follows:

1. Submission: An Actor submits a Wish (e.g., "Create Wallet", "Transfer Assets"). The Wish is a JSON payload containing the intent and metadata.

2. Verification: The Wish must be digitally signed by the Actor. Vigil validates this signature against the Actor's registered Ed25519 public key to ensure authenticity and non-repudiation.

3. Policy Engine: Once verified and persisted (initial status PE_WISH_PENDING), the Policy Engine evaluates the Wish against the Organization's policy hierarchy. It identifies all policies applicable to the specific Actor, Organization, and Wish type.

   • Output: Policies are marked as PE_SELECTED, PE_REJECTED, or PE_REJECTED_BY_EXPRESSION.

   Policy Selection Logic: The Policy Engine determines the effective policy through a rigorous hierarchical process:

   1. Hierarchy Reconstruction: It reconstructs the full organizational path from the Root Org down to the Target Org.
   2. Top-Down Traversal: It traverses this path from Root to Target. At each level (each Org), it gathers all defined policies.
   3. Filtering: Policies are filtered out if:
      • They are not applicable to Sub-Orgs (if the current node is not the Target Org).
      • The Policy WishKind does not match the Wish's kind.
      • The Policy is expired (validFor window passed).
   4. Sorting: Remaining policies are sorted by:
      • Dynamic vs Static: Dynamic policies (with CEL rules) take precedence.
      • Priority: Higher priority values come first.
      • Creation Date: Newer policies take precedence (LIFO for ties).
   5. Selection: The engine evaluates the rules of the first matching policy in the sorted list.
      • If the policy's rules evaluate to TRUE, that policy is SELECTED for that Org level.
      • If the rules evaluate to FALSE (or rules fail), the policy is skipped, and the next one in the list is tried.
   6. Composite Decision: A Wish is only SELECTED if at least one policy is selected during the traversal. (Note: Current implementation selects one policy per level, but requires at least one match in the path).

4. Control Engine: If a policy requires specific controls (e.g., M-of-N approvals, time-locks, or external validations), the Control Engine manages these workflows. The initial status is CE_PENDING. It blocks execution until all conditions are satisfied.

   • Output: Status transitions from CE_PENDING to CE_APPROVED or CE_FAILED (or CE_REJECTED).

5. Execution Engine: Only fully approved Wishes are picked up by the Execution Engine. This engine interfaces with the specific crypto-provider (the "Vault") to execute the operation on-chain or via the provider's API.

   • Output: Status becomes EE_EXECUTED or EE_FAILED.

The Flow of R Wishes

Read-Only (R) Wishes allow Actors to securely query the system state. Unlike CUD (Create/Update/Delete) wishes, R-Wishes are:

1. Transient: They are not persisted on the immutable ledger.
2. Policy-Gated: Every read request is evaluated by the Policy Engine in real-time. Access is granted or denied based on the Actor's organization and assigned permissions.

Supported R-Wish kinds include VIEW_ORGS, VIEW_ACTORS, VIEW_VAULTS, VIEW_WISHES (history), and VIEW_LOCKS.

Wish Submission & Security

Interaction with Vigil is cryptographically secured.

• Actors & Keys: Every Actor in the system is identified by a public key (currently Ed25519).
• Signed Wishes: Actors do not simply "call an API"; they construct a SignedWish object. This object contains the clear-text Wish payload and a cryptographic signature of that payload.
• Immutable Ledger: Once a Wish is submitted and verified, it is persisted effectively as an immutable record. The system functions as a deterministic state machine, moving the Wish through its lifecycle stages based on the defined rules and controls.

Control Engine

The Vigil Neo Control Engine is responsible for managing the approval workflows that gate execution of specific Wishes. When the Policy Engine evaluates a defined Policy as SELECTED, and that Policy dictates that constraints must be met, the Control Engine orchestrates the collection of necessary authorizations before yielding control to the Execution Engine.

Operational Logic (Control-Flow Traversal)

The Neo Control Engine utilizes a Control-Flow JSON structure that represents approval workflows as hierarchical trees. The execution model follows a rigorous depth-first, left-to-right traversal algorithm:

1. Tree Structure: Workflows consist of ROOT nodes (representing sequential containers) and ACTOR_GROUP nodes (representing leaf nodes that map to real identities).
2. Sequential Steps: Each ACTOR_GROUP encountered during traversal constitutes a discrete execution "step". The engine mandates that a step is definitively resolved before it evaluates the next step.
3. Parallel Notifications: To maximize efficiency, all identified actors within an active step receive notifications simultaneously.
4. Threshold Evaluation: The engine dynamically evaluates approvals against a predefined threshold. A step is approved as soon as the threshold of unique actor approvals is met. Conversely, the exact moment the number of rejections mathematically prevents the threshold from being met, the entire request is securely halted as CE_REJECTED.

Core Characteristics of Programmable Policies

The architecture of the Neo Control Engine actively enforces the core pillars of programmable policies:

• Contextual Intelligence (Dynamic JSON Context): Workflows are not hardcoded. The engine builds situational awareness by processing a strictly structured, dynamic JSON workflow representation (vigil.ControlsFlow). This provides unparalleled contextual intelligence, adapting seamlessly to complex logic trees tailored to the specific context of the request, the affected organization, and the impacted actors.
• Logic-Based Evaluation (Rules Designer): The hierarchical grouping of constraints enables the expression of complex conditional logic. By treating the workflow as a deterministic graph, the engine acts as an automated rules evaluator. It mathematically tracks quorum responses, allows for zero-threshold auto-bypassing, and instantly identifies mathematically impassable states, ensuring airtight policy enforcement.
• Separation of Concerns: The platform maintains strict modular boundaries. The Policy Engine evaluates whether a request is permitted. The Control Engine isolates the state-machine logic determining how and from whom necessary signatures are collected. Actual delivery of requests to humans is handed off to a distinct Notification system. This decoupled architecture ensures the Control Engine acts solely as a pure, mathematically-sound ledger of state.

UI

MCP Integration (Claude Code / AI Agents)

Vigil exposes its full API surface via the Model Context Protocol for integration with Claude Code and other MCP-compatible AI clients. The MCP server runs exclusively in Docker.

Prerequisites

1. Backend stack running:

cd containers-4-vigil
docker compose -f docker-compose.full.yml up -d --build

2. MCP image built:

docker build -f containers-4-vigil/Dockerfile.mcp -t vigil-mcp .

Claude Code Integration

The project includes a .mcp.json that automatically connects Claude Code to Vigil's MCP server:

claude   # .mcp.json is auto-detected

Full Stack with MCP (HTTP mode)

Run all services including MCP on port 5004:

cd containers-4-vigil
docker compose -f docker-compose.full-with-mcp.yml up -d --build

Available MCP Tools (16)

Category	Tools
Read (11)	vigil_view_orgs, vigil_view_actors, vigil_view_actor_groups, vigil_view_vaults, vigil_view_vault_groups, vigil_view_policies, vigil_view_policy_groups, vigil_view_rules, vigil_view_controls, vigil_view_wishes, vigil_view_locks
Wish Lifecycle (3)	vigil_build_wish, vigil_validate_wish, vigil_submit_wish
Reference (2)	vigil_get_wish_kinds, vigil_get_reference_data