diff --git a/doc/source/handlers.rst b/doc/source/handlers.rst
index 45955e0..67fb2c7 100644
--- a/doc/source/handlers.rst
+++ b/doc/source/handlers.rst
@@ -298,13 +298,18 @@ In analogy to C handlers, the prototype for a Lua handler is
 
 ::
 
+        --- Lua Handler.
+        --
+        --- @param  image  img_type  Lua equivalent of `struct img_type`
+        --- @return number           # 0 on success, 1 on error
         function lua_handler(image)
             ...
         end
 
 where ``image`` is a Lua table (with attributes according to
 :ref:`sw-description's attribute reference <sw-description-attribute-reference>`)
-that describes a single artifact to be processed by the handler.
+that describes a single artifact to be processed by the handler
+(also see the Lua Handler Interface Specification in ``handlers/swupdate.lua``).
 
 Note that dashes in the attributes' names are replaced with
 underscores for the Lua domain to make them idiomatic, e.g.,
@@ -315,6 +320,11 @@ For a script handler written in Lua, the prototype is
 
 ::
 
+        --- Lua Handler.
+        --
+        --- @param  image     img_type  Lua equivalent of `struct img_type`
+        --- @param  scriptfn  string    Type, one of `preinst` or `postinst` 
+        --- @return number              # 0 on success, 1 on error
         function lua_handler(image, scriptfn)
             ...
         end
@@ -343,6 +353,10 @@ a simple handler chain-calling the ``rawfile`` C handler:
 
 ::
 
+        --- Lua Handler.
+        --
+        --- @param  image  img_type  Lua equivalent of `struct img_type`
+        --- @return number           # 0 on success, 1 on error
         function lua_handler(image)
             if not swupdate.handler["rawfile"] then
                 swupdate.error("rawfile handler not available")
@@ -381,6 +395,10 @@ a simple handler calling ``image:copy2file()``:
 
 ::
 
+        --- Lua Handler.
+        --
+        --- @param  image  img_type  Lua equivalent of `struct img_type`
+        --- @return number           # 0 on success, 1 on error
         function lua_handler(image)
             local err, msg = image:copy2file("/tmp/destination.path")
             if err ~= 0 then
@@ -401,6 +419,10 @@ of a simple handler printing the artifact's content:
 
 ::
 
+        --- Lua Handler.
+        --
+        --- @param  image  img_type  Lua equivalent of `struct img_type`
+        --- @return number           # 0 on success, 1 on error
         function lua_handler(image)
             err, msg = image:read(function(data) print(data) end)
             if err ~= 0 then
@@ -422,6 +444,13 @@ returns. Chaining handlers, calling ``image:copy2file()``, or using
 ``image:read()`` satisfies this requirement.
 
 
+The ``swupdate`` Lua module interface specification that details what
+functionality is made available to Lua handlers by SWUpdate's
+``corelib/lua_interface.c`` is found in ``handlers/swupdate.lua``.
+It serves as reference, for mocking purposes, and type checking thanks
+to the EmmyLua-inspired annotations.
+
+
 Note that although the dynamic nature of Lua handlers would
 technically allow one to embed them into a to be processed ``.swu``
 image, this is not implemented as it carries some security
diff --git a/handlers/swupdate.lua b/handlers/swupdate.lua
new file mode 100644
index 0000000..b5ae92b
--- /dev/null
+++ b/handlers/swupdate.lua
@@ -0,0 +1,315 @@
+--[[
+
+    SWUpdate Lua Handler Interface.
+
+    Interface specification for the Lua module
+    provided by SWUpdate to Lua Handlers.
+    See: corelib/lua_interface.c
+
+    Copyright (C) 2022, Siemens AG
+    Author: Christian Storm <christian.storm@siemens.com>
+
+    SPDX-License-Identifier: GPL-2.0-or-later
+
+--]]
+
+---@diagnostic disable: unused-local
+-- luacheck: no unused args
+
+
+--- SWUpdate Lua Handler Module.
+--- @class swupdate
+local swupdate = {}
+
+
+--- @class swupdate.RECOVERY_STATUS
+--- Lua equivalent of `RECOVERY_STATUS` as in `include/swupdate_status.h`.
+--- @type table<string, number>
+swupdate.RECOVERY_STATUS = {
+    IDLE       = 0,
+    START      = 1,
+    RUN        = 2,
+    SUCCESS    = 3,
+    FAILURE    = 4,
+    DOWNLOAD   = 5,
+    DONE       = 6,
+    SUBPROCESS = 7,
+    PROGRESS   = 8
+}
+
+--- Lua equivalent of `ERROR(format, ...)`.
+--- @param format  string  Format string
+--- @param ...     any     Varargs as referenced in format string
+swupdate.error = function(format, ...) end
+
+--- Lua equivalent of `TRACE(format, ...)`.
+--- @param format  string  Format string
+--- @param ...     any     Varargs as referenced in format string
+swupdate.trace = function(format, ...) end
+
+--- Lua equivalent of `INFO(format, ...)`.
+--- @param format  string  Format string
+--- @param ...     any     Varargs as referenced in format string
+swupdate.info  = function(format, ...) end
+
+--- Lua equivalent of `WARN(format, ...)`.
+--- @param format  string  Format string
+--- @param ...     any     Varargs as referenced in format string
+swupdate.warn  = function(format, ...) end
+
+--- Lua equivalent of `DEBUG(format, ...)`.
+--- @param format  string  Format string
+--- @param ...     any     Varargs as referenced in format string
+swupdate.debug = function(format, ...) end
+
+--- Lua equivalent of `notify(PROGRESS, ..., msg)`.
+--- @param msg  string  Message to send to progress interface
+swupdate.progress = function(msg) end
+
+--- Lua equivalent of `notify(status, error, INFOLEVEL, msg)`.
+--- @param status  number  Current status, one of `swupdate.RECOVERY_STATUS`'s values
+--- @param error   number  Error code
+--- @param msg     string  Message
+swupdate.notify = function(status, error, msg) end
+
+
+--- Update progress.
+--
+--- @param percent  number  Progress percent to set
+swupdate.progress_update = function(percent) end
+
+
+--- Mount a filesystem to a temporary mountpoint.
+--
+--- @param  device      string  Device to mount
+--- @param  filesystem  string  Device's filesystem
+--- @return string              # Mountpoint for use with `swupdate.umount(target)`
+swupdate.mount = function(device, filesystem) end
+
+--- Unmount a mountpoint.
+--
+--- @param  target  string  Mountpoint to unmount
+--- @return boolean         # true if successful, nil on error
+swupdate.umount = function(target) end
+
+
+--- @class swupdate.ROOT_DEVICE
+--- Lua equivalent of `root_dev_type` as in `include/lua_util.h`.
+--- @type  table<string, number>
+swupdate.ROOT_DEVICE = {
+    PATH      = 0,
+    UUID      = 1,
+    PARTUUID  = 2,
+    PARTLABEL = 3
+}
+
+
+--- Current root device information.
+--- @class rootdev
+--- @field type   number  Root device type, one of `swupdate.ROOT_DEVICE`'s values
+--- @field value  string  Root device path
+--- @field path   string  Full root device path, if identified, else nil
+
+--- Get current root device.
+--
+--- @return rootdev  # Table containing type, and (full) path to root device
+swupdate.getroot = function() end
+
+
+--- Get SWUpdate's TMPDIRSCRIPT directory.
+--
+--- @return string  # TMPDIRSCRIPT directory
+swupdate.tmpdirscripts = function() end
+
+--- Get SWUpdate's TMPDIR directory.
+--
+--- @return string  # TMPDIR directory
+swupdate.tmpdir = function() end
+
+
+--- SWUpdate version information.
+--- @class swupdate_version
+--- @field [1]         number  SWUpdate's version
+--- @field [2]         number  SWUpdate's patch level
+--- @field version     number  SWUpdate's version
+--- @field patchlevel  number  SWUpdate's patch level
+
+--- Get SWUpdate version.
+--
+--- @return swupdate_version  # Table with 'version' and 'patchlevel' fields
+swupdate.getversion = function() end
+
+
+--- Get software Selection and Mode.
+--
+--- @return string  # Selection
+--- @return string  # Mode
+swupdate.get_selection = function() end
+
+
+--- Set Bootloader environment key=value.
+--
+--- @param key    string  Bootloader environment key to set
+--- @param value  string  Value to set `key` to in bootloader environment
+swupdate.set_bootenv = function(key, value) end
+
+--- Get Bootloader environment key's value.
+--
+--- @param  key  string  Bootloader environment's key to get value from
+--- @return string       # Bootloader environment key's value, empty if key absent
+swupdate.get_bootenv = function(key) end
+
+
+--- @class swupdate.HANDLER_MASK
+--- Lua equivalent of `HANDLER_MASK` as in `include/handler.h`.
+--- @type  table<string, number>
+swupdate.HANDLER_MASK = {
+    IMAGE_HANDLER      = 1,
+    FILE_HANDLER       = 2,
+    SCRIPT_HANDLER     = 4,
+    BOOTLOADER_HANDLER = 8,
+    PARTITION_HANDLER  = 16,
+    NO_DATA_HANDLER    = 32,
+    ANY_HANDLER        = 1 + 2 + 4 + 8 + 16 + 32
+}
+
+--- Register a Lua function as Handler implementation.
+--
+-- The signature of the function to be registered as Handler implementation is:
+--
+-- --- @param  image img_type Lua equivalent of `struct img_type`
+-- --- @param  fn?   string   `preinst` or `postinst` for `SCRIPT_HANDLER`s, else nil
+-- --- @return number         # 0 on success, 1 on error
+-- function lua_handler(image, fn)
+--     ...
+-- end
+--
+--- @param name     string    Registered Handler's name
+--- @param funcptr  function  Function to register as Handler implementation
+--- @param mask     number    Type(s) for which to register the Handler, one or more ORed values of `swupdate.HANDLER_MASK`
+swupdate.register_handler = function(name, funcptr, mask) end
+
+
+--- Lua equivalent of `struct img_type {...}` as in `include/swupdate.h` plus `read()` and `copy2file()` functions.
+--- @class img_type
+--- @field name                  string    `sw-component` name to check with `sw-versions`
+--- @field version               string    `sw-component` version to check with `sw-versions`
+--- @field filename              string    File name in CPIO archive
+--- @field volume                string    If handler is "ubivol", the UBI volume name
+--- @field type                  string    The Handler name
+--- @field device                string    Device node to operate on for mounting, flashing, ...
+--- @field path                  string    For FILE_HANDLERs: the relative destination path
+--- @field mtdname               string    MTD device where image must be installed
+--- @field data                  string    Handler-specific arbitrary data
+--- @field filesystem            string    For FILE_HANDLERs: the filesystem to mount
+--- @field ivt                   string    IVT of an encrypted artifact
+--- @field installed_directly    boolean   Whether to stream image to `device` w/o temporary copy
+--- @field install_if_different  boolean   Whether to compare `name` and `version` accordingly
+--- @field install_if_higher     boolean   Whether to compare `name` and `version` accordingly
+--- @field encrypted             boolean   Whether the artifact is encrypted
+--- @field partition             boolean   Whether the artifact is a partitioner
+--- @field script                boolean   Whether the artifact is a script
+--- @field preserve_attributes   boolean   Whether to preserve attributes in archives
+--- @field offset                number    Offset to seek to in artifact
+--- @field size                  number    Artifact size
+--- @field checksum              number    Computed checksum
+--- @field skip                  number    `skip_t` enum number as in `include/swupdate.h`
+--- @field compressed            string    `zlib` or `zstd` (boolean value is deprecated)
+--- @field properties            table     Properties Table equivalent as specified in `sw-description`
+--- @field sha256                string    sha256 hash of the image, file, or script
+local img_type = {
+    --- Store the current image artifact to disk.
+    --
+    --- @param  self  img_type  This `img_type` instance
+    --- @param  path  string    Path to store the current image artifact to
+    --- @return number          # 0 on success, -1 on error
+    --- @return string | nil    # nil on success, error message on failure
+    ['copy2file'] = function(self, path) end,
+
+    --- Process the current image artifact in Lua.
+    --
+    -- The `callback = function(chunk) ... end` is repeatedly called with
+    -- chunked artifact data of type `string` in its `chunk` parameter as
+    -- long as there is data available.
+    -- The callback function must completely consume the artifact data so
+    -- that SWUpdate can continue with the stream's next artifact after
+    -- the Lua Handler returns.
+    --
+    --- @param  self      img_type  This `img_type` instance
+    --- @param  callback  function  Callback `function(chunk) ... end` that is fed the current image artifact in chunks.
+    --- @return number              # 0 on success, -1 on error
+    --- @return string | nil        # nil on success, error message on failure
+    ['read'] = function(self, callback) end,
+}
+
+
+--- @class swupdate.handler
+--- Chain-callable SWUpdate Handlers (Non-exhaustive).
+--
+-- Note: This list of built-in Handlers is non-exhaustive and
+-- purely illustrative. At run-time, SWUpdate populates this
+-- Table with the actually available Handlers according to its
+-- compile-time configuration and Lua Handlers loaded.
+--
+--- @type table<string, number>
+swupdate.handler = {
+    --- Archive Handler (See: `handlers/archive_handler.c`).
+    ["archive"]        = 1,
+    --- `tar` Archive Handler (See: `handlers/archive_handler.c`).
+    ["tar"]            = 1,
+    --- Bootloader Handler (See: `handlers/boot_handler.c`).
+    ["bootloader"]     = 1,
+    --- "dummy" Handler (See: `handlers/dummy_handler.c`).
+    ["dummy"]          = 1,
+    --- Delta Handler (See: `handlers/delta_handler.c`).
+    ["delta"]          = 1,
+    --- Disk Format Handler (See: `handlers/diskformat_handler.c`).
+    ["diskformat"]     = 1,
+    --- Disk Partition Handler (See: `handlers/diskpart_handler.c`).
+    ["diskpart"]       = 1,
+    --- Toggle Boot Flag Handler (See: `handlers/diskpart_handler.c`).
+    ["toggleboot"]     = 1,
+    --- Flash Hamming1 Handler (See: `handlers/flash_hamming1_handler.c`).
+    ["flash-hamming1"] = 1,
+    --- Flash Handler (See: `handlers/flash_handler.c`).
+    ["flash"]          = 1,
+    --- Raw Image Handler (See: `handlers/raw_handler.c`).
+    ["raw"]            = 1,
+    --- Raw File Handler (See: `handlers/raw_handler.c`).
+    ["rawfile"]        = 1,
+    --- Raw Copy Handler (See: `handlers/raw_handler.c`).
+    ["rawcopy"]        = 1,
+    --- rdiff Image Handler (See: `handlers/rdiff_handler.c`).
+    ["rdiff_image"]    = 1,
+    --- rdiff File Handler (See: `handlers/rdiff_handler.c`).
+    ["rdiff_file"]     = 1,
+    --- Readback Handler (See: `handlers/readback_handler.c`).
+    ["readback"]       = 1,
+    --- Remote Handler (See: `handlers/remote_handler.c`).
+    ["remote"]         = 1,
+    --- SSBL Handler (See: `handlers/ssbl_handler.c`).
+    ["ssblswitch"]     = 1,
+    --- SWU Forward Handler (See: `handlers/swuforward_handler.c`).
+    ["swuforward"]     = 1,
+    --- UBI Volume Handler (See: `handlers/ubivol_handler.c`).
+    ["ubivol"]         = 1,
+    --- UBI Partition Handler (See: `handlers/ubivol_handler.c`).
+    ["ubipartition"]   = 1,
+    --- UBI Swap Handler (See: `handlers/ubivol_handler.c`).
+    ["ubiswap"]        = 1,
+    --- ucfw Handler (See: `handlers/ucfw_handler.c`).
+    ["ucfw"]           = 1,
+    --- Unique UUID Handler (See: `handlers/uniqueuuid_handler.c`).
+    ["uniqueuuid"]     = 1,
+}
+
+--- Chain-call another Handler.
+--
+--- @param  handler  string    Chain-called Handler's name
+--- @param  image    img_type  Lua equivalent of `struct img_type` as in `include/swupdate.h`
+--- @return number             # 0 on success, 1 on failure
+--- @return string | nil       # nil on success, error message on failure
+swupdate.call_handler = function(handler, image) end
+
+
+return swupdate
