TODO: this document is relative to version 1 and will be updated soon for changes introduced in version 2

Despite significant architectural differences, the following points are still a good approximation of the internals.

Espanso has always been designed with a strong focus on security. In the following section, there is an overview of the critical security components.

If you have any doubt, don't hesitate to contact me.

In its most basic form, a text expander is composed of two parts:

• A global key detector that intercepts the keys pressed by the user, in order to determine if a trigger was typed.

• A key injection mechanism that injects the final text into the current application, a process known as expansion.

At this point, some of you may think that espanso is acting as a keylogger, due to the global key detector we mentioned before. The good news is, it's not!

While espanso detects key presses as a keylogger would do, it doesn't log anything. Moreover, to further reduce risks, espanso only stores in memory the last 3 chars by default (you can change this amount by setting the backspace_limit parameter in the config) and this is needed to allow the user to correct wrongly typed triggers by pressing backspace, up to 3 characters.

The matching part is implemented with an efficient data structure that keeps track of the compatible matches in a "rolling" basis. So that in the worst case scenario, the longest sequence of chars kept in memory would be equal to the longest trigger.

And of course, if you don't trust me you can examine all the code! That's the wonderful thing about open source :)

The global key detector is implemented on top of various OS-dependent APIs, in particular:

• On Windows, it uses the RawInput API.
• On macOS, it uses addGlobalMonitorForEvents.
• On Linux, it uses the X Record Extension.

To report a security issue, please email me at federicoterzi96[at]gmail.com