# pkolano/mesh architecture

> Architecture diagram of the GitHub repository pkolano/mesh, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pkolano/mesh
- Repository: https://github.com/pkolano/mesh

## Overview

##### Main Components

- Client (User):
– Represents the user’s SSH client initiating connections.

- Mesh Proxy (MP):
– Acts as the gateway for remote commands.
– Implements the Mesh Authorization Shell (Mash), which is found in the Perl/ directory (e.g., perl/Mash and its associated scripts like mash.pl and various mesh-* utilities). Mash parses and authorizes incoming commands based on site policies.

- Mesh Interposition Agent (MIA):
– Installed on Mesh-accessible resources.
– Incorporated via dynamic library preloading (the “bypass_src” directory contains lib and src components such as bypass_agent, bypass_shadow, etc.). The MIA intercepts the SSH server’s authentication process to retrieve an authorized_keys file from a Mesh Authentication Point (MAP).

- Mesh Authentication Point (MAP):
– Works as the key retrieval source for authorized keys during authentication.
– While specific directories for MAP are not clearly labeled in the file tree, the configuration files (e.g., those in the “etc” directory) and the design described in the README imply its existence. MAP may be implemented as part of the intercommunication between the MIA and the proxy.

- Mesh Exec Security Shell (Mess):
– Responsible for securely executing commands once they are authorized.
– Its role is mentioned in the README, and although its implementation details are less visible from the file structure, it logically completes the workflow by applying execution constraints (integrated with the bypass components).

##### File Structure to Components

- “bypass” and “bypass_src”:
– These directories contain build scripts, configuration files, and the source code (in lib/ and src/). They are likely responsible for building the MIA and potentially parts of the single sign-on execution environment.

- “perl” folder:
– Contains Mash’s modules (including command mediation, policies, and rules). Files like Mash/Command.pm, Mash/Policy.pm, Mash/Proxy.pm, and their derivatives illustrate how the command parsing and mediation functions are implemented.

- Configuration and Documentation:
– The “etc” and “doc” directories provide the configuration maps and user/deployment instructions. They indicate how the system should be integrated on client and server hosts.

- Build Scripts and Makefiles:
– Present at multiple levels (the root, bypass, and bypass_src) to support compilation and installation, emphasizing that distinct build steps are needed for different components.

##### Relationships and Data Flow

- The SSH session first interfaces with the Mesh Proxy (MP) where Mash examines and possibly rewrites the command:
- Once authorized, the Mesh Proxy directs the remote command to the appropriate Mesh-accessible resource.
- On the remote server, Mesh Interposition Agent (MIA) is preloaded into the SSH daemon:
– This agent intercepts the authentication call, retrieves the authorized_keys file from the MAP (with propagation to the user’s home VO if needed), and enforces the security policies.
- After successful authentication, the Mesh Exec Security Shell (Mess) takes over to execute the command with controlled privileges.
– Use directional flows indicating this process from MIA to Mess and then command execution.

##### Architectural Patterns and Design Principles

- Modularity: The project splits responsibilities clearly into discrete components (Mash, MIA, Mess) which can be deployed independently as noted in the README.
- Interposition: The MIA uses system call interposition (via library preloading) to modify SSH behavior during authentication.
- Single Sign-On: The cross-communication between different hosts (MP, MAP) and the propagation of keys highlight a distributed architecture.
- Customizability: Using Perl for Mash facilitates a highly flexible authorization process, evident from the modular Perl modules for different rules and command mediation logic.

##### Instructing the Principal Software Engineer

- That each component (Client, Mesh Proxy [Mash], Mesh Interposition Agent, Mesh Authentication Point, Mesh Exec Security Shell) is clearly drawn and labeled.
- Notes that indicate the architectural patterns observed:
– Modularity for potential independent deployment.
– Dynamic behavior modification by the MIA via system interposition.
– Single sign-on implementation which propagates authentication requests.
- With relevant technologies noted in the project:
– Languages used (C for low-level agents in bypass_src, Perl for Mash in the perl directory).
– Tools such as Makefiles and configuration scripts that indicate build and deployment flows.
- Provide clear, detailed labels and annotations that capture each piece’s role, data flow, and interaction with the SSH stack.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client"
        A["Client (User SSH)"]:::clientStyle
    end

    subgraph "Mesh Gateway"
        B["Mesh Proxy (Mash)"]:::mpStyle
    end

    subgraph "Remote Resource"
        C["Mesh Interposition Agent (MIA)"]:::miaStyle
        D["Mesh Authentication Point (MAP)"]:::mapStyle
        E["Mesh Exec Security Shell (Mess)"]:::messStyle
    end

    A -->|"SSH_connection"| B
    B -->|"Forwards_command"| C
    C -->|"Fetches_keys"| D
    D -->|"Returns_keys"| C
    C -->|"Executes_command"| E

    click B "https://github.com/pkolano/mesh/blob/master/perl/mash.pl"
    click C "https://github.com/pkolano/mesh/tree/master/bypass_src/lib"
    click D "https://github.com/pkolano/mesh/tree/master/etc"
    click E "https://github.com/pkolano/mesh/tree/master/perl/mess"

    classDef clientStyle fill:#f4e1ff,stroke:#333,stroke-width:2px;
    classDef mpStyle fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef miaStyle fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef mapStyle fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef messStyle fill:#ffcc99,stroke:#333,stroke-width:2px;
```
