NAME

Bot::Cobalt::Plugin::Auth -- User management and auth plugin

DESCRIPTION

This plugin provides the standard authorization and access control functionality for Bot::Cobalt.

CONFIGURATION

plugins.conf

A basic plugins.conf entry for this plugin:

  Auth:
    Module: Bot::Cobalt::Plugin::Auth
    Config: auth.conf

auth.conf

auth.conf is the central configuration file for this plugin, including statically-configured superuser auth entries.

SuperUsers

The SuperUsers directive specifies statically configured superusers, who receive access level 9999 by default and typically have access to the totality of the bot's functionality.

Users are specified per-context. Multiple masks can be specified as a list:

  SuperUsers:
    Main:
      'avenj':
        Mask:
          - '*avenj@*.oppresses.us'
          - '*avenj@*.cobaltirc.org'
        Password: '$2a$08$W19087w4d(. . . .)'

Password should be a hashed password. You can create them from the command line via bmkpasswd from App::bmkpasswd, which this distribution depends on.

Opts

Opts defines a small set of password and database related options:

  Opts:
    Method: 'bcrypt'
    Bcrypt_Cost: '08'
    AuthDB: 'db/authdb.yml'

Method

Method is a string describing the preferred password hashing method for new passwords. Hashes are created via App::bmkpasswd -- bcrypt is the recommended method and guaranteed to be available.

sha256 and sha512 methods may be available, although you might need Crypt::Passwd::XS on certain platforms. Consult the App::bmkpasswd documentation for details.

Bcrypt_Cost

If using bcrypt (see "Method"), the 'work cost factor' is configurable. Must be a two digit power of 2. Lower is faster (less secure), higher is slower (more secure).

The default work cost factor is '08' -- you can probably leave this alone.

AuthDB

Path (relative to the bot's var/ directory) used to store user information (except for superusers).

Defaults to 'db/authdb.yml'

RequiredPrivs

Required base access levels for specific operations.

  RequiredPrivs:
    AddingUsers: 2
    DeletingUsers: 2

IRC USAGE

Logging in

  /msg cobalt login <username> <password>

You must share at least one channel with the bot in order to log in.

Changing your password

You can change your own password at any time:

  /msg cobalt chpass <oldpasswd> <newpasswd>

User administration

user add

  /msg cobalt user add <username> <level> <mask> <passwd>

New users can be added by anyone with at least AddingUsers level (see "RequiredPrivs"). Users can only be added at levels below your own.

user del

  /msg cobalt user del <username>

Users can only be removed below your own access level (and you must have at least DeletingUsers permissions -- see "RequiredPrivs")

user chflags

  /msg cobalt user chflags <username> +FLAG -FLAG [...]

Alter a user's marked flags; flags must be prefixed with + or - to indicate an addition or removal.

(As of this writing, flags are under-utilized in the Cobalt core distribution)

user chpass

  /msg cobalt user chpass <username> <passwd>

Alter a user's password manually. Only usable by superusers.

user chmask

  /msg cobalt user chmask <username> +*!*some@*.mask.example.org
  /msg cobalt user chmask <username> -*!*some@*.mask.example.org

Add or remove authorized masks for a particular user.

You can add or remove masks for yourself at any time, so long as you have at least DeletingUsers level (see "RequiredPrivs"). Altering masks for other users requires a higher access level than theirs.

Only one mask can be added or deleted at a time.

user whois

  /msg cobalt user whois <nickname>

Find out if a nickname is currently logged in to the bot (and under what username / access level)

user info

  /msg cobalt user info <username>

Display user record information for a username.

user list

  /msg cobalt user list

Display the current user list.

user search

FIXME

EMITTED EVENTS

Bot_auth_user_login

Broadcast when a login is successful.

Arguments are:

  $context, $nickname, $username, $hostname, $authorized_level

Bot_auth_failed_login

Broadcast when a login fails.

Arguments are:

  $context, $nickname, $username, $hostname, "ERR_STR"

Where 'ERR_STR' is one of the following strings:

  "NO_SUCH_USER"
  "NO_SHARED_CHANS"
  "BAD_HOST"
  "BAD_PASS"

Bot_auth_user_logout

Broadcast when a user is logged out, either manually or because the user was "lost" (no longer visible by the bot).

Arguments are:

  $context, $nickname, $hostname, $username, $authorized_level

AUTHOR

Jon Portnoy <avenj@cobaltirc.org>

cpanm Bot::Cobalt

perl -MCPAN -e shell
install Bot::Cobalt