service.py: Fix commentary, and default remote command.

[chopwood] / service.py

### -*-python-*-
###
### Services
###
### (c) 2013 Mark Wooding
###

###----- Licensing notice ---------------------------------------------------
###
### This file is part of Chopwood: a password-changing service.
###
### Chopwood is free software; you can redistribute it and/or modify
### it under the terms of the GNU Affero General Public License as
### published by the Free Software Foundation; either version 3 of the
### License, or (at your option) any later version.
###
### Chopwood is distributed in the hope that it will be useful,
### but WITHOUT ANY WARRANTY; without even the implied warranty of
### MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
### GNU Affero General Public License for more details.
###
### You should have received a copy of the GNU Affero General Public
### License along with Chopwood; if not, see
### <http://www.gnu.org/licenses/>.

from __future__ import with_statement

import os as OS
import re as RX
import subprocess as SUB

from auto import HOME
import backend as B
import cgi as CGI
import config as CONF; CFG = CONF.CFG
import hash as H
import util as U

###--------------------------------------------------------------------------
### Protocol.
###
### A service is a thing for which a user might have an account, with a login
### name and password.  The service protocol is fairly straightforward: there
### are methods corresponding to the various low-level operations which can
### be performed on services.  Services also present `friendly' names, used
### by the user interface.
###
### A service may be local or remote.  Local services are implemented in
### terms of a backend and hashing scheme.  Information about a particular
### user of a service is maintained in an `account' object which keeps track
### of the backend record and hashing scheme; the service protocol operations
### are handed off to the account.  Accounts provide additional protocol for
### clients which are willing to restrict themselves to the use of local
### services.
###
### A remote service doesn't have local knowledge of the password database:
### instead, it simply sends commands corresponding to the service protocol
### operations to some external service which is expected to act on them.
### The implementation here uses SSH, and the remote end is expected to be
### provided by another instance of `chpwd', but that needn't be the case:
### the protocol is very simple.

UnknownUser = B.UnknownUser

class IncorrectPassword (Exception):
  """
  A failed password check is reported via an exception.

  This is /not/ an `ExpectedError', since we anticipate that whoever called
  `check' will have made their own arrangements to deal with the failure in
  some more useful way.
  """
  pass

class BasicService (object):
  """
  A simple base class for services.

  The `manage_pwent_p' flag indicates whether administration commands should
  attempt to add or remove password entries in the corresponding database
  when users are added or removed.
  """

  def __init__(me, friendly, name = None, manage_pwent_p = True,
               *args, **kw):
    super(BasicService, me).__init__(*args)
    me.name = name
    me.friendly = friendly
    me.manage_pwent_p = manage_pwent_p
    me.meta = kw

###--------------------------------------------------------------------------
### Local services.

class Account (object):
  """
  An account represents information about a user of a particular service.

  From here, we can implement the service protocol operations, and also check
  passwords.

  Users are expected to acquire account objects via the `lookup' method of a
  `LocalService' or similar.
  """

  def __init__(me, svc, rec):
    """
    Create a new account, for the service SVC, holding the user record REC.
    """
    me._svc = svc
    me._rec = rec
    me._hash = svc.hash

  def check(me, passwd):
    """
    Check the password PASSWD against the information we have.  If the
    password is correct, return normally; otherwise, raise
    `IncorrectPassword'.
    """
    if not me._hash.check(me._rec, me._rec.passwd, passwd):
      raise IncorrectPassword

  def clearpasswd(me):
    """Service protocol: clear the user's password."""
    if me._hash.NULL is None:
      raise U.ExpectedError, (400, "Can't clear this password")
    me._rec.passwd = me._hash.NULL
    me._rec.write()

  def setpasswd(me, passwd):
    """Service protocol: set the user's password to PASSWD."""
    passwd = me._hash.hash(me._rec, passwd)
    me._rec.passwd = passwd
    me._rec.write()

  def remove(me):
    """Service protocol: remove the user's password entry."""
    me._rec.remove()

class LocalService (BasicService):
  """
  A local service has immediate knowledge of a hashing scheme and a password
  storage backend.  (Knowing connection details for a remote database server
  is enough to qualify for being a `local' service.  The important bit is
  that the hashed passwords are exposed to us.)

  The service protocol is implemented via an `Account', acquired through the
  `find' method.  Mainly for the benefit of the `Account' class, the
  service's hashing scheme is exposed in the `hash' attribute.
  """

  def __init__(me, backend, hash, *args, **kw):
    """
    Create a new local service with a FRIENDLY name, using the given BACKEND
    and HASH scheme.
    """
    super(LocalService, me).__init__(*args, **kw)
    me._be = backend
    me.hash = hash

  def find(me, user):
    """Find the named USER, returning an `Account' object."""
    rec = me._be.lookup(user)
    return Account(me, rec)

  def setpasswd(me, user, passwd):
    """Service protcol: set USER's password to PASSWD."""
    me.find(user).setpasswd(passwd)

  def clearpasswd(me, user):
    """Service protocol: clear USER's password, preventing logins."""
    me.find(user).clearpasswd()

  def mkpwent(me, user, passwd, fields):
    """Service protocol: create a record for USER."""
    if me.hash.NULL is not None: passwd = me.hash.NULL
    me._be.create(user, passwd, fields)

  def rmpwent(me, user):
    """Service protocol: delete the record for USER."""
    me.find(user).remove()

CONF.export('LocalService')

###--------------------------------------------------------------------------
### Remote services.

class BasicRemoteService (BasicService):
  """
  A remote service transmits the simple service protocol operations to some
  remote system, which presumably is better able to implement them than we
  are.  This is useful if, for example, the password file isn't available to
  us, or we don't have (or can't be allowed to have) access to the database
  tables containing password hashes, or must synchronize updates with some
  remote process.  It can also be useful to integrate with services which
  don't present a conventional password file.

  This class provides common machinery for communicating with various kinds
  of remote service.  Specific subclasses are provided for transporting
  requests through SSH and GNU Userv; others can be added easily in local
  configuration.
  """

  def _run(me, cmd, input = None, state = None):
    """
    This is the core of the remote service machinery.  It issues a command
    and parses the response.  It will generate strings of informational
    output from the command; error responses cause appropriate exceptions to
    be raised.

    The command is determined by passing the CMD and STATE arguments to the
    `_mkcmd' method, which a subclass must implement; it should return a list
    of command-line arguments suitable for `subprocess.Popen'.  The INPUT is
    a string to make available on the command's stdin; if None, then no input
    is provided to the command.  The `_describe' method must provide a
    description of the remote service for use in timeout messages.

    We expect output on stdout in a simple line-based format.  The first
    whitespace-separated token on each line is a type code: `OK' means the
    command completed successfully; `INFO' means the rest of the line is some
    useful (and expected) information; and `ERR' means an error occurred: the
    next token is an HTTP integer status code, and the remainder is a
    human-readable message.
    """

    ## Run the command and collect its output and status.
    with U.timeout(30, "waiting for remote service %s" % me._describe()):
      proc = SUB.Popen(me._mkcmd(cmd, state),
                       stdin = input is not None and SUB.PIPE or None,
                       stdout = SUB.PIPE, stderr = SUB.PIPE)
      out, err = proc.communicate(input)
      st = proc.wait()

    ## If the program failed then report this: it obviously didn't work
    ## properly.
    if st or err:
      raise U.ExpectedError, (
        500, 'Remote service error: %r (rc = %d)' % (err, st))

    ## Split a word off the front of a string; return the word and the
    ## remaining string.
    def nextword(line):
      ww = line.split(None, 1)
      n = len(ww)
      if not n: return None
      elif n == 1: return ww[0], ''
      else: return ww

    ## Work through the lines, parsing them.
    win = False
    for line in out.splitlines():
      type, rest = nextword(line)
      if type == 'ERR':
        code, msg = nextword(rest)
        raise U.ExpectedError, (int(code), msg)
      elif type == 'INFO':
        yield rest
      elif type == 'OK':
        win = True
      else:
        raise U.ExpectedError, \
              (500, 'Incomprehensible reply from remote service: %r' % line)

    ## If we didn't get any kind of verdict then something weird has
    ## happened.
    if not win:
      raise U.ExpectedError, (500, 'No reply from remote service')

  def _run_noout(me, cmd, input = None, state = None):
    """Like `_run', but expect no output."""
    for _ in me._run(cmd, input, state):
      raise U.ExpectedError, (500, 'Unexpected output from remote service')

class SSHRemoteService (BasicRemoteService):
  """
  A remote service transported over SSH.

  The remote service is given commands of the form

  `set SERVICE USER'
        Set USER's password for SERVICE to the password provided on the next
        line of standard input.

  `clear SERVICE USER'
        Clear the USER's password for SERVICE.

  `mkpwent USER SERVICE [FIELDS ...]'
        Install a record for USER in the SERVICE, supplying any other
        necessary FIELDS in the appropriate format.  The user's password is
        provided on the next line of standard input.

  `rmpwent USER SERVICE'
        Remove USER's password record for SERVICE.

  Arguments are form-url-encoded, since SSH doesn't preserve token boundaries
  in its argument list.

  It is expected that the remote user has an `.ssh/authorized_keys' file
  entry for us specifying a program to be run; the above commands will be
  left available to this program in the environment variable
  `SSH_ORIGINAL_COMMAND'.
  """

  def __init__(me, remote, name, *args, **kw):
    """
    Initialize an SSH remote service, contacting the SSH user REMOTE
    (probably of the form `LOGIN@HOSTNAME') and referring to the service
    NAME.
    """
    super(SSHRemoteService, me).__init__(name = name, *args, **kw)
    me._remote = remote

  def _describe(me):
    """Description of the remote service."""
    return "`%s' via SSH to `%s'" % (me.name, me._remote),

  def _mkcmd(me, cmd, state):
    """Format a command for SSH.  Mainly escaping arguments."""
    return ['ssh', me._remote, ' '.join(map(CGI.urlencode, cmd))]

  def setpasswd(me, user, passwd):
    """Service protocol: set the USER's password to PASSWD."""
    me._run_noout(['set', me.name, user], passwd + '\n')

  def clearpasswd(me, user):
    """Service protocol: clear the USER's password."""
    me._run_noout(['clear', me.name, user])

  def mkpwent(me, user, passwd, fields):
    """Service protocol: create a record for USER."""
    me._run_noout(['mkpwent', user, me.name] + fields, passwd + '\n')

  def rmpwent(me, user):
    """Service protocol: delete the record for USER."""
    me._run_noout(['rmpwent', user, me.name])

CONF.export('SSHRemoteService')

class CommandRemoteService (BasicRemoteService):
  """
  A remote service transported over a standard Unix command.

  This is left rather generic.  Two strategies are available (and can be
  combined using appropriate configuration).  A DEFAULT command list can be
  specified, and will be invoked as `DEFAULT OP ARGS...', where OP ARGS form
  a Chopwood remote command.  Additionally, an OPMAP dictionary can be
  provided, mapping OP names (remote command names) to command lists
  containing `%' placeholders, as follows:

  `%u'          the user's name
  `%%'          a single `%' character

  On success, the commands should print a line `OK' to standard output, and
  on any kind of anticipated failure, they should print `ERR' followed by an
  HTTP status code and a message; in either case, the program should exit
  with status zero.  In disastrous cases, it's acceptable to print an error
  message to stderr and/or exit with a nonzero status.

  Configuration hint: if you can only handle some subset of the available
  commands, then your easy approach is to set commands for the operations you
  can handle in the OPMAP, and set the DEFAULT to something like

        ['echo', 'ERR', '500', 'unsupported command:']

  to reject other commands.
  """

  R_PAT = RX.compile('%(.)')

  def __init__(me,
               default = ['echo', 'ERR', '500', 'unimplemented command:'],
               opmap = {}, *args, **kw):
    """Initialize the command remote service."""
    super(CommandRemoteService, me).__init__(*args, **kw)
    me._default = default
    me._opmap = opmap

  def _describe(me):
    """Description of the remote service."""
    return "`%s' command service (%s)" % (me.name, ' '.join(me._default))

  def _subst(me, c, map):
    """Return the substitution for the placeholder `%C'."""
    return map.get(c, c)

  def _mkcmd(me, cmd, map):
    """Construct the command to be executed, by substituting placeholders."""
    if map is None: return cmd
    return [me.R_PAT.sub(lambda m: me._subst(m.group(1), map), arg)
            for arg in cmd]

  def _dispatch(me, func, op, args, input = None):
    """
    Work out how to invoke a particular command.

    Invoke FUNC, which works like `_run', with appropriate arguments.  The OP
    is a remote command name; ARGS is a sequence of (C, ARG) pairs, where C
    is a placeholder character and ARG is a string value; INPUT is the text
    to provide to the command on standard input.
    """
    try:
      cmd = me._opmap[op]
    except KeyError:
      cmd = me._default + [op] + [v for k, v in args]
      map = None
    else:
      map = dict(args)
    return func(cmd, input = input, state = map)

  def setpasswd(me, user, passwd):
    """Service protocol: set the USER's password to PASSWD."""
    me._dispatch(me._run_noout, 'set', [('u', user)], passwd + '\n')

  def clearpasswd(me, user):
    """Service protocol: clear the USER's password."""
    me._dispatch(me._run_noout, 'clear', [('u', user)])

  def mkpwent(me, user, passwd, fields):
    """Service protocol: create a record for USER."""
    me._dispatch(me._run_noout, 'mkpwent', [('u', user)])

  def rmpwent(me, user):
    """Service protocol: delete the record for USER."""
    me._dispatch(me._run_noout, 'rmpwent', [('u', user)])

CONF.export('CommandRemoteService')

###--------------------------------------------------------------------------
### Services registry.

## The registry of services.
SERVICES = {}
CONF.export('SERVICES')

## Set some default configuration.
CONF.DEFAULTS.update(

  ## The master database, as a pair (MODNAME, MODARGS).
  DB = ('sqlite3', [OS.path.join(HOME, 'chpwd.db')]),

  ## The hash to use for our master password database.
  HASH = H.CryptHash('md5'))

## Post-configuration hook: add the master service.
@CONF.hook
def add_master_service():
  dbmod, dbargs = CFG.DB
  SERVICES['master'] = \
    LocalService(B.DatabaseBackend(dbmod, dbargs,
                                   'users', 'user', 'passwd'),
                 CFG.HASH,
                 friendly = 'Password changing service')
  for name, svc in SERVICES.iteritems():
    if svc.name is None: svc.name = name

###----- That's all, folks --------------------------------------------------