operation.py: Refactor `polswitch' a little.

[chopwood] / operation.py

### -*-python-*-
###
### Operations and policy switch
###
### (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/>.

import os as OS

import config as CONF; CFG = CONF.CFG
import util as U

### The objective here is to be able to insert a policy layer between the UI,
### which is where the user makes requests to change a bunch of accounts, and
### the backends, which make requested changes without thinking too much
### about whether they're a good idea.
###
### Here, we convert between (nearly) user-level /requests/, which involve
### doing things to multiple service/user pairs, and /operations/, which
### represent a single change to be made to a particular service.  (This is
### slightly nontrivial in the case of reset requests, since the intended
### semantics may be that the services are all assigned the /same/ random
### password.)

###--------------------------------------------------------------------------
### Some utilities.

OPS = ['set', 'reset', 'clear']
## A list of the available operations.

class polswitch (U.struct):
  """A small structure holding a value for each operation."""
  __slots__ = OPS

###--------------------------------------------------------------------------
### Operation protocol.

## An operation deals with a single service/user pair.  The protocol works
## like this.  The constructor is essentially passive, storing information
## about the operation but not actually performing it.  The `perform' method
## attempts to perform the operation, and stores information about the
## outcome in attributes:
##
## error        Either `None' or an `ExpectedError' instance indicating what
##              went wrong.
##
## result       Either `None' or a string providing additional information
##              about the successful completion of the operation.
##
## svc          The service object on which the operation was attempted.
##
## user         The user name on which the operation was attempted.

class BaseOperation (object):
  """
  Base class for individual operations.

  This is where the basic operation protocol is implemented.  Subclasses
  should store any additional attributes necessary during initialization, and
  implement a method `_perform' which takes no parameters, performs the
  operation, and returns any necessary result.
  """

  def __init__(me, svc, user, *args, **kw):
    """Initialize the operation, storing the SVC and USER in attributes."""
    super(BaseOperation, me).__init__(*args, **kw)
    me.svc = svc
    me.user = user

  def perform(me):
    """Perform the operation, and return whether it was successful."""

    ## Set up the `result' and `error' slots here, rather than earlier, to
    ## catch callers referencing them too early.
    me.result = me.error = None

    ## Perform the operation, and stash the result.
    ok = True
    try:
      try: me.result = me._perform()
      except (IOError, OSError), e: raise U.ExpectedError, (500, str(e))
    except U.ExpectedError, e:
      me.error = e
      ok = False

    ## Done.
    return ok
CONF.export('BaseOperation')

class SetOperation (BaseOperation):
  """Operation to set a given password on an account."""
  def __init__(me, svc, user, passwd, *args, **kw):
    super(SetOperation, me).__init__(svc, user, *args, **kw)
    me.passwd = passwd
  def _perform(me):
    me.svc.setpasswd(me.user, me.passwd)
CONF.export('SetOperation')

class ClearOperation (BaseOperation):
  """Operation to clear a password from an account, preventing logins."""
  def _perform(me):
    me.svc.clearpasswd(me.user)
CONF.export('ClearOperation')

class FailOperation (BaseOperation):
  """A fake operation which just raises an exception."""
  def __init__(me, svc, user, exc):
    me.svc = svc
    me.uesr = user
    me.exc = exc
  def perform(me):
    me.result = None
    me.error = me.exc
    return False
CONF.export('FailOperation')

###--------------------------------------------------------------------------
### Requests.

## A request object represents a single user-level operation targetted at
## multiple services.  The user might be known under a different alias by
## each service, so requests operate on service/user pairs, bundled in an
## `acct' object.
##
## Request methods are as follows.
##
## check()      Verify that the request complies with policy.  Note that
##              checking that any particular user has authority over the
##              necessary accounts has already been done.  One might want to
##              check that the passwords are sufficiently long and
##              complicated (though that rapidly becomes problematic, and I
##              don't really recommend it) or that particular services are or
##              aren't processed at the same time.
##
## perform()    Actually perform the request.  A list of completed operation
##              objects is left in the `ops' attribute.
##
## Performing the operation may leave additional information in attributes.
## The `INFO' class attribute contains a dictionary mapping attribute names
## to human-readable descriptions of this additional information.
##
## Note that the request object has a fairly free hand in choosing how to
## implement the request in terms of operations.  In particular, it might
## process additional services.  Callers must not assume that they can
## predict what the resulting operations list will look like.

class acct (U.struct):
  """A simple pairing of a service SVC and USER name."""
  __slots__ = ['svc', 'user']

class BaseRequest (object):
  """
  Base class for requests, provides basic protocol.  In particular, it
  provides an empty `INFO' map, a trivial `check' method, and the obvious
  `perform' method which assumes that the `ops' list has already been
  constructed.
  """
  INFO = {}
  def check(me):
    """
    Check the request to make sure we actually want to proceed.
    """
    pass
  def makeop(me, optype, svc, user, **kw):
    """
    Hook for making operations.  A policy class can substitute a
    `FailOperation' to partially disallow a request.
    """
    return optype(svc, user, **kw)
  def perform(me):
    """
    Perform the queued-up operations.
    """
    for op in me.ops: op.perform()
    return me.ops
CONF.export('BaseRequest', ExpectedError = U.ExpectedError)

class SetRequest (BaseRequest):
  """
  Request to set the password for the given ACCTS to NEW.

  The new password is kept in the object's `new' attribute for easy
  inspection.  The `check' method ensures that the password is not empty, but
  imposes no other policy restrictions.
  """
  def __init__(me, accts, new):
    me.new = new
    me.ops = [me.makeop(SetOperation, acct.svc, acct.user, passwd = new)
              for acct in accts]
  def check(me):
    if me.new == '':
      raise U.ExpectedError, (400, "Empty password not permitted")
    super(SetRequest, me).check()
CONF.export('SetRequest')

class ResetRequest (BaseRequest):
  """
  Request to set the password for the given ACCTS to something new but
  nonspeific.  The new password is generated based on a number of class
  attributes which subclasses can usefully override.

  ENCODING      Encoding to apply to random data.

  PWBYTES       Number of random bytes to collect.

  Alternatively, subclasses can override the `pwgen' method.
  """

  ## Password generation parameters.
  PWBYTES = 16
  ENCODING = 'base32'

  ## Additional information.
  INFO = dict(new = 'New password')

  def __init__(me, accts):
    me.new = me.pwgen()
    me.ops = [me.makeop(SetOperation, acct.svc, acct.user, passwd = me.new)
              for acct in accts]

  def pwgen(me):
    return U.ENCODINGS[me.ENCODING].encode(OS.urandom(me.PWBYTES)) \
           .rstrip('=')
CONF.export('ResetRequest')

class ClearRequest (BaseRequest):
  """
  Request to clear the password for the given ACCTS.
  """
  def __init__(me, accts):
    me.ops = [me.makeop(ClearOperation, acct.svc, acct.user)
              for acct in accts]
CONF.export('ClearRequest')

###--------------------------------------------------------------------------
### Master policy switch.

CONF.DEFAULTS.update(

  ## Map a request type `set', `reset', or `clear', to the appropriate
  ## request class.
  RQCLASS = polswitch(**dict((i, None) for i in OPS)),

  ## Alternatively, set this to a mixin class to apply common policy to all
  ## the kinds of requests.
  RQMIXIN = None)

@CONF.hook
def set_policy_classes():
  for op, base in [('set', SetRequest),
                   ('reset', ResetRequest),
                   ('clear', ClearRequest)]:
    if getattr(CFG.RQCLASS, op): continue
    if CFG.RQMIXIN:
      cls = type('Custom%sPolicy' % op.title(), (base, CFG.RQMIXIN), {})
    else:
      cls = base
    setattr(CFG.RQCLASS, op, cls)

## Outcomes.

class outcome (U.struct):
  __slots__ = ['rc', 'nwin', 'nlose']
  OK = 0
  PARTIAL = 1
  FAIL = 2
  NOTHING = 3

class info (U.struct):
  __slots__ = ['desc', 'value']

def operate(op, accts, *args, **kw):
  """
  Perform a request through the policy switch.

  The operation may be one of `set', `reset' or `clear'.  An instance of the
  appropriate request class is constructed, and additional arguments are
  passed directly to the request class constructor; the request is checked
  for policy compliance; and then performed.

  The return values are:

    * an `outcome' object holding the general outcome, and a count of the
      winning and losing operations;

    * a list of `info' objects holding additional information from the
      request;

    * the request object itself; and

    * a list of the individual operation objects.
  """
  rq = getattr(CFG.RQCLASS, op)(accts, *args, **kw)
  rq.check()
  ops = rq.perform()
  nwin = nlose = 0
  for o in ops:
    if o.error: nlose += 1
    else: nwin += 1
  if nwin:
    if nlose: rc = outcome.PARTIAL
    else: rc = outcome.OK
  else:
    if nlose: rc = outcome.FAIL
    else: rc = outcome.NOTHING
  ii = [info(v, getattr(rq, k)) for k, v in rq.INFO.iteritems()]
  return outcome(rc, nwin, nlose), ii, rq, ops

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