anope21-contrib

Custom third-party modules for Anope IRC Services 2.1 by Jean "reverse" Chevronnet.

Module	Purpose
`m_apiauth`	Authenticate users against an external HTTP API instead of the internal Anope database, with optional SASL SCRAM-SHA-256/512 support.
`m_nickserv_oauth`	Adds `NickServ IDENTIFYOAUTH` for JWT/OAuth token login (used by web chat clients).
`m_youtube`	BotServ reads YouTube links posted in channels and replies with video details.

These are contrib modules — they are not part of the Anope core and are not supported by the Anope team. Test on a staging network before deploying.

Building & installing

Anope 2.1 builds third-party modules from modules/third/. Drop the .cpp files there (or symlink this repo), then configure and build:

# from your Anope source tree
cp /path/to/anope21-contrib/*.cpp modules/third/
./Config          # regenerate the build
cd build
make -j$(nproc)
make install

Each module declares its own build/link requirements at the top of the source file (parsed by Anope's CMake glue). Install the dependencies below before building, or the affected module will be skipped:

Module	Build dependencies
`m_apiauth`	OpenSSL (`libssl`/`libcrypto`), libcurl, `nlohmann/json`, `jwt-cpp`
`m_nickserv_oauth`	OpenSSL (`libssl`/`libcrypto`), `jwt-cpp`
`m_youtube`	libcurl, OpenSSL, `yyjson`

On Debian/Ubuntu the system packages are roughly:

sudo apt install libssl-dev libcurl4-openssl-dev nlohmann-json3-dev
# jwt-cpp and yyjson are header/lib-only; install from source or your package manager

After installing, load and configure each module in your Anope configuration (typically modules.conf / your services config). Every example below is a module { ... } block — add it and /msg OperServ RELOAD (or restart) to apply.

m_apiauth

Delegates NickServ authentication to an external HTTP API. When a user identifies, Anope POSTs (or GETs) the credentials to your endpoint; a 2xx response authenticates the user. Optionally validates JWTs returned by the API and provides SASL SCRAM-SHA-256 / SCRAM-SHA-512 mechanisms.

module
{
    name = "m_apiauth"

    # ── External auth endpoint ───────────────────────────────
    api_url         = "https://accounts.example.com/api/login_token/"
    api_method      = "POST"          # POST (default) or GET
    api_username_param = "username"   # form field carrying the nick
    api_password_param = "password"   # form field carrying the password
    api_email_field = "email"         # JSON field to read the email back from
    api_key         = "changeme-shared-secret"   # sent to the API; keep secret

    # ── TLS verification for the API call ────────────────────
    verify_ssl = "true"               # "true"/"false"
    #capath    = "/etc/ssl/certs"     # optional CA directory
    #cainfo    = "/etc/ssl/cert.pem"  # optional CA bundle file

    # ── Optional JWT validation of the API response ──────────
    # Leave jwt_secret empty to skip signature verification.
    jwt_secret = "your-hmac-signing-secret"
    jwt_issuer = "accounts.example.com"

    # ── User-facing URLs shown in replies ────────────────────
    profile_url  = "https://accounts.example.com/profile/%s/"  # %s = account
    register_url = "https://accounts.example.com/register/"

    # ── Redirect built-in commands to the web app (optional) ─
    # If set, these NickServ commands are blocked with the given reason.
    disable_reason       = "Please register on the website: https://accounts.example.com/register/"
    disable_email_reason = "Change your email address on the website instead."

    # ── Optional group/role sync endpoint ────────────────────
    #group_api_url = "https://accounts.example.com/api/groups/"

    # ── SASL SCRAM mechanisms (optional) ─────────────────────
    enable_sasl_scram_sha256 = "yes"  # advertise SCRAM-SHA-256 (default yes)
    enable_sasl_scram_sha512 = "no"   # advertise SCRAM-SHA-512 (default no)
    scram_iterations = "4096"         # PBKDF2 iteration count
    scram_saltlen    = "16"           # salt length in bytes
    #scram_debug          = "no"      # verbose SASL logging
    #scram_attr_b64_nopad = "no"      # base64 without padding for SCRAM attrs
}

Notes

api_key and jwt_secret are secrets — do not commit real values.
The API must accept the configured api_method and return 2xx on success.
%s in profile_url is replaced with the account name.
SCRAM verifiers are stored per-account; enabling SCRAM requires the API/flow to provision them.

m_nickserv_oauth

Adds the IDENTIFYOAUTH command to NickServ, letting a user identify with a JWT bearer token instead of a password. Intended to be driven automatically by a web chat client after the user logs into your web app.

module
{
    name = "m_nickserv_oauth"

    # HMAC secret used to verify the JWT signature (HS256).
    # If left empty, signature verification is DISABLED (not recommended).
    jwt_secret = "your-hmac-signing-secret"

    # Expected "iss" claim. Only enforced when both this and the token set it.
    jwt_issuer = "accounts.example.com"
}

Usage

/msg NickServ IDENTIFYOAUTH YourNick eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

The token's sub / name / username claim must match the requested account, and the token must not be expired (exp). Tip: share the same jwt_secret and jwt_issuer here and in m_apiauth so one signing key covers both flows.

m_youtube

A BotServ add-on: when a channel bot sees a YouTube link, it fetches the video details from the YouTube Data API v3 and posts a formatted reply. Includes an anti-spam throttle and a persistent cache.

module
{
    name = "m_youtube"

    # YouTube Data API v3 key (required).
    youtube_api_key = "AIza...your-key..."

    # ── Reply formatting ─────────────────────────────────────
    prefix        = "\x02\x03""01,00You\x03""00,04Tube\x0F\x02"  # colored "YouTube" tag
    duration_text = "Duration: "
    seen_text     = "Seen: "
    times_text    = " times."
    #response_format = ""   # optional custom format string

    # ── Anti-spam (per channel) ──────────────────────────────
    spam_limit       = "3"                  # max links...
    spam_window      = "60"                 # ...per this many seconds
    spam_kick        = "yes"                # kick offenders?
    spam_kick_reason = "YouTube link spam"
    cache_ttl        = "300"                # video-info cache lifetime (seconds)
}

Commands (require the SAY channel privilege or botserv/administration):

Command	Description
`BotServ youtube`	Handle/announce a YouTube link.
`BotServ ytstats`	Show module usage statistics.

Notes

Get an API key from the Google Cloud Console with the YouTube Data API v3 enabled.
The cache is persisted to m_youtube.module.json in the Anope data directory.
Assign the BotServ bot to a channel (/msg BotServ ASSIGN #chan Bot) for link detection to work there.

License

Unless a source file states otherwise, these modules are distributed under the GNU General Public License. See the header of each .cpp file for details.

7.9 KiB Raw Blame History