Add comprehensive inline metadata documentation to all BackTunnel scripts

scripts/backtunnel-authorize

@@ -1,9 +1,45 @@
 #!/usr/bin/env bash
-set -euo pipefail
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (c) 2025 LUXIM d.o.o., Slovenia
+# Author: Matjaž Mozetič
+#
+# Name: backtunnel-authorize
+# Summary: Register a named public key for later use by other tools (e.g., to grant temporary access).
+# Description:
+#   Copies a provided OpenSSH public key file into the per-user BackTunnel authorized store
+#   under a chosen name. Other scripts can later reference this key by --allow-known <name>.
+#
+# Usage:
+#   backtunnel-authorize <name> <pubkey-file>
+#
+# Examples:
+#   backtunnel-authorize alice ~/.ssh/alice_ed25519.pub
+#
+# Dependencies:
+#   - bash
+#   - install (coreutils or compatible)
+#
+# Exit codes:
+#   0  success
+#   1  invalid usage or file not found
+#
+# Notes:
+#   - Keys are stored at: ${XDG_CONFIG_HOME:-$HOME/.config}/backtunnel/authorized/<name>.pub
+#   - Existing file with the same name will be overwritten (install default behavior).
+
+set -euo pipefail  # Fail on error, undefined vars, and pipeline errors
+
+# ---- Parse & validate arguments ----
 name="${1:-}"
 file="${2:-}"
 [[ -n "$name" && -n "$file" && -f "$file" ]] || { echo "Usage: backtunnel-authorize <name> <pubkey-file>"; exit 1; }
+
+# ---- Destination directory (XDG-compliant) ----
 dir="${XDG_CONFIG_HOME:-$HOME/.config}/backtunnel/authorized"
-mkdir -p "$dir"
+mkdir -p "$dir"  # Ensure the store exists
+
+# ---- Install the key with sane permissions (rw-r--r--) ----
 install -m 644 "$file" "$dir/$name.pub"
+
+# ---- Confirmation ----
 echo "Saved: $dir/$name.pub"