init.lua

--- === AutoAllowScreenCapture ===
---
--- Automatically approves macOS's window picker screen/audio capture alert for a configurable list of trusted applications.
---
--- Match strategy: checks that the window is a genuine OS-presented
--- system dialog -- role AXWindow, subrole AXSystemDialog, owned by
--- com.apple.UserNotificationCenter -- then looks at its direct children
--- for an AXStaticText whose value exactly matches the expected sentence
--- for one of the configured app names.
---
--- Config file (OUTSIDE this Spoon, in your Hammerspoon config dir):
---
---     <hs.configdir>/Prefs/auto-allow-apps.json
---
---
--- Format:
---     { "appnames": ["Thaw", "RustDesk"], "loglevel": "info" }
---
--- appnames: array of app name strings (may be empty -- watcher just
---   won't install).
--- loglevel: 'nothing', 'error', 'warning', 'info', 'debug', or
---   'verbose', or the corresponding number 0-5, per hs.logger's own
---   documented levels. Defaults to "info" if the file itself is
---   missing; but if the file EXISTS and loglevel is present but not
---   one of these, that's a hard validation failure (see below).
---
--- Validation / failure behavior: a malformed JSON file, a missing or
--- wrong-shaped "appnames", or an invalid "loglevel" all log a specific
--- error at error level and leave the Spoon inert -- no window watcher
--- gets installed. There is no live file-watching: change appnames or
--- loglevel, then call reloadApps() (or hs.reload()) to pick it up.
---
--- Debugging: logs through hs.logger under "AutoAllowSC" (dot syntax
--- required -- see hs.logger docs). Starts at "info" until a valid
--- config is loaded, which then applies the configured level.
---
---     spoon.AutoAllowScreenCapture.logger.setLogLevel("debug")
---
--- Test the label-matching logic against a plain string:
---
---     spoon.AutoAllowScreenCapture:testLabelMatch('"Thaw" is requesting to bypass the system private window picker and directly access your screen and audio.')
---
--- Test the full gate against a captured window object:
---
---     spoon.AutoAllowScreenCapture:testWindow(x[14])

local obj = {}
obj.__index = obj

obj.name = "AutoAllowScreenCapture"
obj.version = "1.1.0"
obj.author = "Darrin Tisdale"
obj.license = "MIT"
obj.homepage = "https://github.com/mdarrint/AutoAllowScreenCapture.spoon"
obj.logTag = "AllowSCapt"

obj.logger = hs.logger.new(obj.logTag, "info")

obj.configfilename = "auto-allow-apps.json"

-- The loaded app names, reachable from anywhere (after hs.loadSpoon) as
-- spoon.AutoAllowScreenCapture.apps.
obj.apps = {}

-- internal
obj._filter = nil
obj._matchStrings = {}

-- Delay (seconds) between moving the matched dialog off-screen and
-- actually pressing its Allow button. Gives other window watchers (e.g.
-- LuaSkin-based ones) a chance to observe the window before it's
-- dismissed -- dismissing it too quickly causes LuaSkin errors when a
-- later call tries to operate on a window that's already gone.
obj.dismissDelay = 0.25

-- local variables and functions
local EXPECTED_ROLE = "AXWindow"
local EXPECTED_SUBROLE = "AXSystemDialog"
local EXPECTED_BUNDLE_ID = "com.apple.UserNotificationCenter"

-- Valid log level names, per hs.logger's own documented list.
local VALID_LOG_LEVELS = {
    ["nothing"] = true,
    ["error"] = true,
    ["warning"] = true,
    ["info"] = true,
    ["debug"] = true,
    ["verbose"] = true,
}

local function expectedLabelFor(appName)
    return "“" ..
        appName ..
        "” is requesting to bypass the system private window picker and directly access your screen and audio."
end

-- Validates a decoded loglevel value against hs.logger's documented
-- accepted forms. Returns the value to hand to setLogLevel() (a
-- canonicalized lowercase string, or the original number), or nil plus
-- an error string on failure.
local function validateLogLevel(value)
    if type(value) == "string" then
        local lowered = value:lower()
        if VALID_LOG_LEVELS[lowered] then
            return lowered, nil
        end
        return nil, "loglevel \"" .. value .. "\" is not one of: nothing, error, warning, info, debug, verbose"
    elseif type(value) == "number" then
        if value == math.floor(value) and value >= 0 and value <= 5 then
            return value, nil
        end
        return nil, "loglevel " .. tostring(value) .. " is not an integer between 0 and 5"
    else
        return nil, "loglevel is missing or not a string/number (got " .. type(value) .. ")"
    end
end

-- object private functions

-- Read + validate the JSON config file. On success returns
-- { apps = {...}, loglevel = <validated value> }. On ANY failure --
-- missing file, empty file, malformed JSON, wrong shape, invalid
-- loglevel -- logs a specific error and returns nil. Never throws.
function obj:_loadConfigFromDisk()
    local path = self:configPath()
    self.logger.i("reading config from " .. path)

    local file = io.open(path, "r")
    if not file then
        self.logger.w("no config file at " .. path .. " -- watcher will be disabled")
        return nil
    end

    local contents = file:read("*a")
    file:close()
    self.logger.d("read " .. tostring(contents and #contents or 0) .. " bytes from " .. path)

    if not contents or contents:match("^%s*$") then
        self.logger.w(path .. " is empty -- watcher will be disabled")
        return nil
    end

    local ok, decoded = pcall(hs.json.decode, contents)
    if not ok then
        self.logger.e("failed to parse " .. path .. " as JSON: " .. tostring(decoded))
        return nil
    end
    if type(decoded) ~= "table" then
        self.logger.e(path .. " did not decode to a JSON object -- watcher will be disabled")
        return nil
    end

    if type(decoded.appnames) ~= "table" then
        self.logger.e(path .. " is missing an \"appnames\" array (or it isn't an array) -- watcher will be disabled")
        return nil
    end

    local validatedLevel, levelErr = validateLogLevel(decoded.loglevel)
    if not validatedLevel then
        self.logger.e(path .. ": " .. levelErr .. " -- watcher will be disabled")
        return nil
    end

    local names = {}
    for _, entry in ipairs(decoded.appnames) do
        if type(entry) == "string" and entry:match("%S") then
            table.insert(names, entry)
        else
            self.logger.w("ignoring invalid entry in " .. path .. " appnames: " .. tostring(entry))
        end
    end

    self.logger.i("loaded " .. #names .. " app name(s): " .. table.concat(names, ", "))
    return { apps = names, loglevel = validatedLevel }
end

function obj:_isCandidateSystemDialog(win)
    local role = win:role()
    if role ~= EXPECTED_ROLE then
        self.logger.d("_isCandidateSystemDialog(): role=" .. tostring(role) .. " (want " .. EXPECTED_ROLE .. ") -- skip")
        return false
    end

    local subrole = win:subrole()
    if subrole ~= EXPECTED_SUBROLE then
        self.logger.d("_isCandidateSystemDialog(): subrole=" ..
            tostring(subrole) .. " (want " .. EXPECTED_SUBROLE .. ") -- skip")
        return false
    end

    local app = win:application()
    if not app then
        self.logger.d("_isCandidateSystemDialog(): no owning application -- skip")
        return false
    end

    local bundleID = app:bundleID()
    self.logger.d("_isCandidateSystemDialog(): observed bundleID=" .. tostring(bundleID))
    if bundleID ~= EXPECTED_BUNDLE_ID then
        self.logger.d("_isCandidateSystemDialog(): bundleID=" ..
            tostring(bundleID) .. " (want " .. EXPECTED_BUNDLE_ID .. ") -- skip")
        return false
    end

    return true
end

function obj:_findMatchingLabel(win)
    local axWin = hs.axuielement.windowElement(win)
    if not axWin then
        self.logger.e("_findMatchingLabel(): could not get an AX element for the window")
        return nil
    end

    for _, child in ipairs(axWin:attributeValue("AXChildren") or {}) do
        if child:attributeValue("AXRole") == "AXStaticText" then
            local value = child:attributeValue("AXValue")
            self.logger.d("_findMatchingLabel(): label value -> " .. tostring(value))
            for i, expected in ipairs(self._matchStrings) do
                if value == expected then
                    return self.apps[i]
                end
            end
        end
    end

    return nil
end

function obj:_pressAllow(win)
    local axWin = hs.axuielement.windowElement(win)
    if not axWin then
        self.logger.e("_pressAllow(): could not get an AX element for the window")
        return false
    end

    local children = axWin:attributeValue("AXChildren") or {}
    self.logger.d("_pressAllow(): inspecting " .. #children .. " child element(s)")

    for _, child in ipairs(children) do
        local role = child:attributeValue("AXRole")
        local title = child:attributeValue("AXTitle")
        self.logger.d("_pressAllow(): child role=" .. tostring(role) .. " title=" .. tostring(title))

        if role == "AXButton" and title == "Allow" then
            child:performAction("AXPress")
            self.logger.i("_pressAllow(): pressed Allow")
            return true
        end
    end

    self.logger.e("_pressAllow(): no \"Allow\" button found -- dialog left untouched")
    return false
end

-- testing functions
function obj:testLabelMatch(value)
    self.logger.i("testLabelMatch(): checking value -> " .. tostring(value))
    for i, expected in ipairs(self._matchStrings) do
        if value == expected then
            self.logger.i("testLabelMatch(): MATCH -- app \"" .. self.apps[i] .. "\"")
            return self.apps[i]
        end
    end
    self.logger.i("testLabelMatch(): no match")
    return nil
end

function obj:testWindow(win)
    if not win then
        self.logger.w("testWindow(): no window given")
        return nil
    end
    if not self:_isCandidateSystemDialog(win) then
        self.logger.i("testWindow(): not a candidate system dialog")
        return nil
    end
    local matchedApp = self:_findMatchingLabel(win)
    if matchedApp then
        self.logger.i("testWindow(): MATCH -- app \"" .. matchedApp .. "\"")
    else
        self.logger.i("testWindow(): candidate dialog, but no configured app's label matched")
    end
    return matchedApp
end

--- AutoAllowScreenCapture:init()
--- Method
--- Initializes the Spoon. Called automatically by hs.loadSpoon().
---
--- Parameters:
---  * None
---
--- Returns:
---  * The AutoAllowScreenCapture object
function obj:init()
    self.logger.i("init() starting")

    local config = self:_loadConfigFromDisk()

    if not config then
        self.logger.e(
            "configuration failed to load -- see error above; Spoon will not watch for anything until reloadApps() is called with a valid config")
        self.apps = {}
        self._matchStrings = {}
        return self
    end

    self.logger.setLogLevel(config.loglevel)
    self.logger.i("log level set to " .. tostring(config.loglevel))

    self.apps = config.apps
    self._matchStrings = {}
    for _, appName in ipairs(self.apps) do
        local expected = expectedLabelFor(appName)
        table.insert(self._matchStrings, expected)
        self.logger.d("expecting label: " .. expected)
    end

    self.logger.i("init() complete -- " .. #self._matchStrings .. " app(s) ready")
    return self
end

--- AutoAllowScreenCapture:configPath()
--- Method
--- Provides the string for the configuration path
---
--- Parameters:
---  * None
---
--- Returns:
---  * a string for the path to the configuration file
function obj:configPath()
    return hs.configdir .. "/Prefs/" .. self.configfilename
end

--- AutoAllowScreenCapture:start()
--- Method
--- Verifies the preferences were read, then starts hooking window creation to circumvent
--- the indicated notifications
---
--- Parameters:
---  * None
---
--- Returns:
---  * The AutoAllowScreenCapture object
function obj:start()
    if #self._matchStrings == 0 then
        self.logger.w("no configured apps -- not installing a window watcher")
        return self
    end

    self._filter = hs.window.filter.new(true)

    self._filter:subscribe(hs.window.filter.windowCreated, function(win)
        if not win then return end

        self.logger.d("windowCreated: title=\"" .. (win:title() or "") ..
            "\" role=" .. tostring(win:role()) .. " subrole=" .. tostring(win:subrole()))

        if not self:_isCandidateSystemDialog(win) then
            return
        end

        local matchedApp = self:_findMatchingLabel(win)
        if matchedApp then
            self.logger.i("matched app \"" .. matchedApp .. "\" -- moving off-screen and scheduling Allow press")

            local moveOk, moveErr = pcall(function() win:setTopLeft({ x = -10000, y = -10000 }) end)
            if not moveOk then
                self.logger.w("failed to move window off-screen: " .. tostring(moveErr))
            end

            hs.timer.doAfter(self.dismissDelay, function() self:_pressAllow(win) end)
        else
            self.logger.d("candidate system dialog seen, but no configured app's label matched")
        end
    end)

    self.logger.i("watcher started -- watching for: " .. table.concat(self.apps, ", "))
    return self
end

--- AutoAllowScreenCapture:stop()
--- Method
--- Stops notification window monitoring
---
--- Parameters:
---  * None
---
--- Returns:
---  * The AutoAllowScreenCapture object
function obj:stop()
    if self._filter then
        self._filter:unsubscribeAll()
        self._filter = nil
        self.logger.i("watcher stopped")
    end
    return self
end

--- AutoAllowScreenCapture:reloadApps()
--- Method
--- Re-reads and re-validates the config file and restarts the watcher.
--- Required after any appnames or loglevel change -- there is no
--- automatic file watching.
---
--- Parameters:
---  * None
---
--- Returns:
---  * The AutoAllowScreenCapture object
function obj:reloadApps()
    self.logger.i("reloadApps() -- reloading config and restarting watcher")
    self:stop()
    self:init()
    self:start()
    return self
end

return obj