# Copyright: (c) 2026, TeTeHacko # GNU General Public License v3.0+ (see LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt) DOCUMENTATION = r""" module: meshcore_acl short_description: Admin ACL of a MeshCore repeater, over RF through a companion author: TeTeHacko (@TeTeHacko) description: - Reads the repeater's real ACL with the binary access-list request (the only way to see it remotely; `get acl` prints to the node's USB serial), then sends `setperm 3` for missing admins and, with I(exclusive), `setperm 0` for everything else. Reads the ACL back afterwards and fails on a mismatch. - The companion this runs through must stay admin, otherwise the next run could not log in. It is kept even when not listed in I(admins). options: transport: description: - "Companion to talk through: C({type: tcp, host, port}), C({type: serial, port, baud}) or C({type: ble, address})." - A BLE companion must already be bonded on the host the module runs on (C(bluetoothctl pair)); there is no PIN option, so it never lands in a log. While the module holds the link, the companion is not reachable from a phone. - C(expect_freq) (MHz) refuses to send anything when the companion is on another frequency; C(retries) and C(reply_timeout) tune the RF exchange. type: dict required: true target: description: Full 64-hex pubkey of the repeater. type: str required: true password: description: Admin password. Empty = blank login, works for a companion already in the ACL. type: str default: "" admins: description: Full 64-hex pubkeys that must be admin. type: list elements: str required: true exclusive: description: Remove every ACL entry that is not in I(admins). type: bool default: true """ EXAMPLES = r""" - name: Exactly these admins tth.meshcore.meshcore_acl: transport: {type: tcp, host: 127.0.0.1, port: 5000} target: "{{ mc_target }}" password: "{{ vault_meshcore_admin_password }}" admins: - "{{ managing_companion_pubkey }}" - "{{ my_phone_pubkey }}" """ from ansible.module_utils.basic import AnsibleModule, missing_required_lib from ansible_collections.tth.meshcore.plugins.module_utils.meshcore_link import ( HAS_MESHCORE, HEX64, Link, LinkError, run, ) from ansible_collections.tth.meshcore.plugins.module_utils.meshcore_plan import PERM_ADMIN, plan_acl async def work(module, link): p = module.params await link.open() try: await link.login() before = await link.acl() me = link.self_pubkey() add, remove = plan_acl(before, p["admins"], p["exclusive"], keep=[me]) add_pfx = {a[:12] for a in add} expected = (set(before) - set(remove)) | add_pfx result = { "changed": bool(add or remove), "add": add, "remove": remove, "diff": { "before": "".join(f"{k} {before[k]}\n" for k in sorted(before)), "after": "".join(f"{k} {PERM_ADMIN if k in add_pfx else before[k]}\n" for k in sorted(expected)), }, } if module.check_mode or not result["changed"]: return result for pk in add: await link.cli(f"setperm {pk} {PERM_ADMIN}", r"^(OK|Err)") for pfx in remove: # a prefix that is gone already answers "Err - invalid params": fine await link.cli(f"setperm {pfx} 0", r"^(OK|Err)") after = await link.acl() left_add, left_remove = plan_acl(after, p["admins"], p["exclusive"], keep=[me]) if left_add or left_remove: raise LinkError(f"ACL after apply still differs: missing {left_add}, extra {left_remove}") result["acl"] = after return result finally: await link.close() def main(): module = AnsibleModule( argument_spec={ "transport": {"type": "dict", "required": True}, "target": {"type": "str", "required": True}, "password": {"type": "str", "default": "", "no_log": True}, "admins": {"type": "list", "elements": "str", "required": True}, "exclusive": {"type": "bool", "default": True}, }, supports_check_mode=True, ) if not HAS_MESHCORE: module.fail_json(msg=missing_required_lib("meshcore")) admins = [a.lower() for a in module.params["admins"]] bad = [a for a in admins if not HEX64.match(a)] if bad: module.fail_json(msg=f"admins must be full 64-hex pubkeys: {bad}") module.params["admins"] = admins link = Link(module.params["transport"], module.params["target"], module.params["password"]) try: result = run(work(module, link)) except LinkError as e: module.fail_json(msg=str(e), log=link.log) module.exit_json(log=link.log, **result) if __name__ == "__main__": main()