Merge lp:~cjwatson/lazr.restful/caveats into lp:lazr.restful

[Colin Watson]

Implement caveat checking at the request boundary.

Implement basic support for "caveats": predicates that are enforced at the webservice request boundary, but not inside it. The data structures used here are inspired by Google's "macaroons" (http://research.google.com/pubs/pub41892.html) and will be used to implement support for them, but the support here is more generic; the concrete binding to the macaroon wire format and implementation of specific predicates will be left to the Launchpad webapp code, and some caveats are expected to be stored in the database rather than supplied in macaroons.

Caveats are enforced around marshalling and unmarshalling of objects, and in some cases in advance of turning them into their wire format in order to be able to redact fields; they are also enforced on calls to methods declared as part of the webservice. In order to avoid a large amount of verbiage in macaroons related to reading public objects, caveats can never reduce permissions below those possessed by an unauthenticated user, which requires some extra support in the security policy.

The ICaveatChecker interface is somewhat based on zope.security.interfaces.IChecker, but I didn't think it quite worked out for it to implement it directly.

I have work in progress to implement the corresponding pieces of this in Launchpad. I don't intend to land the lazr.restful side until the Launchpad side is also ready, but I'm sending this for earlier review to make sure that I'm heading in the right direction.

[lp:~cjwatson/lazr.restful/caveats]

215. By Colin Watson on 2016-02-22

Only check caveats if the principal provides IPrincipalWithCaveats.

216. By Colin Watson on 2016-02-22

It's the interaction that supports checkUnauthenticatedPermission, not the security policy.

217. By Colin Watson on 2016-02-22

Fix doctest.

218. By Colin Watson on 2016-02-25

Add IPrincipalCaveat.text.

219. By Colin Watson on 2016-02-29

Rename IPrincipalCaveat to ICaveat.

220. By Colin Watson on 2016-03-01

Add a @check_parameter_permissions decorator.

221. By Colin Watson on 2016-03-01

Fix lazr.restful.caveatchecker.__all__.

222. By Colin Watson on 2016-03-02

Check caveats in accessors, mutators, and collections.

[Colin Watson (cjwatson)]

I'm withdrawing this as it seems unlikely that we're going to proceed with this work.

Unmerged revisions

222. By Colin Watson on 2016-03-02

Check caveats in accessors, mutators, and collections.

221. By Colin Watson on 2016-03-01

Fix lazr.restful.caveatchecker.__all__.

220. By Colin Watson on 2016-03-01

Add a @check_parameter_permissions decorator.

219. By Colin Watson on 2016-02-29

Rename IPrincipalCaveat to ICaveat.

218. By Colin Watson on 2016-02-25

Add IPrincipalCaveat.text.

217. By Colin Watson on 2016-02-22

Fix doctest.

216. By Colin Watson on 2016-02-22

It's the interaction that supports checkUnauthenticatedPermission, not the security policy.

215. By Colin Watson on 2016-02-22

Only check caveats if the principal provides IPrincipalWithCaveats.

214. By Colin Watson on 2016-02-22

Implement caveat checking at the request boundary.

213. By Colin Watson on 2016-02-22

Lift exception handling from ReadWriteResource.__call__ into HTTPResource.__call__.

=== modified file 'setup.py'
--- setup.py	2016-02-17 01:07:21 +0000
+++ setup.py	2016-03-02 13:25:07 +0000
@@ -69,11 +69,13 @@
         'van.testing',
         'wsgiref',
         'zope.app.pagetemplate',
+        'zope.authentication',
         'zope.component [zcml]',
         'zope.configuration',
         'zope.event',
         'zope.interface>=3.6.0',
         'zope.pagetemplate',
+        'zope.principalregistry',
         'zope.processlifetime',
         'zope.proxy',
         'zope.publisher',

=== modified file 'src/lazr/restful/_operation.py'
--- src/lazr/restful/_operation.py	2016-02-17 01:07:21 +0000
+++ src/lazr/restful/_operation.py	2016-03-02 13:25:07 +0000
@@ -16,10 +16,15 @@
 from lazr.lifecycle.event import ObjectModifiedEvent
 from lazr.lifecycle.snapshot import Snapshot
 
-from lazr.restful.fields import CollectionField
 from lazr.restful.interfaces import (
-    ICollection, IFieldMarshaller, IResourceDELETEOperation,
-    IResourceGETOperation, IResourcePOSTOperation, IWebServiceConfiguration)
+    ICaveatChecker,
+    ICollection,
+    IFieldMarshaller,
+    IResourceDELETEOperation,
+    IResourceGETOperation,
+    IResourcePOSTOperation,
+    IWebServiceConfiguration,
+    )
 from lazr.restful.interfaces import ICollectionField, IReference
 from lazr.restful.utils import is_total_size_link_active
 from lazr.restful._resource import (
@@ -46,6 +51,7 @@
     def __init__(self, context, request):
         self.context = context
         self.request = request
+        self.caveat_checker = ICaveatChecker(request)
         self.total_size_only = False
 
     def total_size_link(self, navigator):

=== modified file 'src/lazr/restful/_resource.py'
--- src/lazr/restful/_resource.py	2016-02-17 01:07:21 +0000
+++ src/lazr/restful/_resource.py	2016-03-02 13:25:07 +0000
@@ -89,6 +89,7 @@
 from lazr.lifecycle.event import ObjectModifiedEvent
 from lazr.lifecycle.snapshot import Snapshot
 from lazr.restful.interfaces import (
+    ICaveatChecker,
     ICollection,
     ICollectionField,
     ICollectionResource,
@@ -286,11 +287,41 @@
     def __init__(self, context, request):
         self.context = context
         self.request = request
+        self.caveat_checker = ICaveatChecker(request)
         self.etags_by_media_type = {}
 
     def __call__(self):
         """See `IHTTPResource`."""
-        pass
+        result = ""
+        try:
+            result = self.call()
+        except Exception as e:
+            exception_info = sys.exc_info()
+            view = getMultiAdapter((e, self.request), name="index.html")
+            try:
+                ws_view = IWebServiceExceptionView(view)
+            except TypeError:
+                # There's a view for this exception, but it's not one
+                # we can understand.  It was probably designed for a
+                # web application rather than a web service.  We'll
+                # re-raise the exception, let the publisher look up
+                # the view, and hopefully handle it better.  Note the careful
+                # reraising that ensures the original traceback is preserved.
+                raise exception_info[0], exception_info[1], exception_info[2]
+
+            self.request.response.setStatus(ws_view.status)
+            if ws_view.status / 100 == 4:
+                # This exception corresponds to a client-side error
+                result = ws_view()
+            else:
+                # This exception corresponds to a server-side error
+                # (or some weird attempt to handle redirects or normal
+                # status codes using exceptions).  Let the publisher
+                # handle it.  (No need for carefully reraising here; since
+                # there is only one exception in flight we just use a bare
+                # raise to reraise the original exception.)
+                raise
+        return result
 
     def getRequestMethod(self, request=None):
         """Return the HTTP method of the provided (or current) request.
@@ -667,7 +698,8 @@
         # obtained from a representation cache.
         resources = [EntryResource(entry, request)
                      for entry in navigator.batch
-                     if checkPermission(view_permission, entry)]
+                     if checkPermission(view_permission, entry) and
+                        self.caveat_checker.checkCaveats(entry)]
         entry_strings = [
             resource._representation(HTTPResource.JSON_TYPE)
             for resource in resources]
@@ -784,6 +816,56 @@
         super(FieldUnmarshallerMixin, self).__init__(context, request)
         self._unmarshalled_field_cache = {}
 
+    def _checkPermission(self, context, name, field, check_method):
+        # Can we view/change (as appropriate) the field's value?  We check
+        # the permission directly using the Zope permission checker for
+        # several reasons.  Firstly, doing it indirectly by fetching the
+        # value may have very slow side-effects such as database hits.
+        # Secondly, in the write case we obviously cannot set the value
+        # without side-effects.  Thirdly, if caveats are in operation then
+        # we need to check them only for this field, not for anything
+        # internal to the getter/setter.
+        try:
+            tagged_values = field.getTaggedValue(
+                'lazr.restful.exported')
+            original_name = tagged_values['original_name']
+        except KeyError:
+            # This field has no tagged values, or is missing the
+            # 'original_name' value.  Its entry class was probably created
+            # by hand rather than by tagging an interface.  In that case,
+            # it's the programmer's responsibility to set 'original_name' if
+            # the web service field name differs from the underlying
+            # interface's field name.  Since 'original_name' is not present,
+            # assume the names are the same.
+            original_name = name
+        context = self.entry._orig_interfaces[name](context)
+        try:
+            getChecker(context)
+        except TypeError:
+            if check_method == 'check':
+                # This is more expensive than using a Zope checker, but
+                # there is no checker, so either there is no permission
+                # control on this object, or permission control is
+                # implemented some other way.  Also note that we use
+                # getattr() on self.entry rather than context because some
+                # of the fields in entry.schema will be provided by adapters
+                # rather than directly by context.
+                getattr(self.entry, name)
+            else:
+                # In the write case, we cannot check permissions in advance
+                # if there is no checker.
+                pass
+        else:
+            getattr(self.caveat_checker, check_method)(context, original_name)
+
+    def checkRead(self, context, name, field):
+        """Raise Unauthorized if the current user cannot read this field."""
+        self._checkPermission(context, name, field, 'check_getattr')
+
+    def checkWrite(self, context, name, field):
+        """Raise Unauthorized if the current user cannot write this field."""
+        self._checkPermission(context, name, field, 'check_setattr')
+
     def _unmarshallField(self, field_name, field, detail=NORMAL_DETAIL):
         """See what a field would look like in a generic representation.
 
@@ -803,7 +885,9 @@
                 value = None
                 flag = IUnmarshallingDoesntNeedValue
             else:
+                self.checkRead(self.entry.context, field.__name__, field)
                 value = getattr(self.entry, field.__name__)
+                self.caveat_checker.enforceCaveats(value)
                 flag = None
             if detail is NORMAL_DETAIL:
                 repr_value = marshaller.unmarshall(self.entry, value)
@@ -875,7 +959,7 @@
         # even though there's no other code in __init__.
         super(ReadOnlyResource, self).__init__(context, request)
 
-    def __call__(self):
+    def call(self):
         """Handle a GET or (if implemented) POST request."""
         result = ""
         method = self.getRequestMethod()
@@ -902,60 +986,33 @@
         # even though there's no other code in __init__.
         super(ReadWriteResource, self).__init__(context, request)
 
-    def __call__(self):
+    def call(self):
         """Handle a GET, PUT, or PATCH request."""
         result = ""
         method = self.getRequestMethod()
-        try:
-            if method == "GET":
-                result = self.do_GET()
-            elif method in ["PUT", "PATCH"]:
-                media_type = self.handleConditionalWrite()
-                if media_type is not None:
-                    stream = self.request.bodyStream
-                    representation = stream.getCacheStream().read()
-                    if method == "PUT":
-                        result = self.do_PUT(media_type, representation)
-                    else:
-                        result = self.do_PATCH(media_type, representation)
-            elif method == "POST" and self.implementsPOST():
-                result = self.do_POST()
-            elif method == "DELETE" and self.implementsDELETE():
-                result = self.do_DELETE()
-            else:
-                allow_string = "GET PUT PATCH"
-                if self.implementsPOST():
-                    allow_string += " POST"
-                if self.implementsDELETE():
-                    allow_string += " DELETE"
-                self.request.response.setStatus(405)
-                self.request.response.setHeader("Allow", allow_string)
-        except Exception as e:
-            exception_info = sys.exc_info()
-            view = getMultiAdapter((e, self.request), name="index.html")
-            try:
-                ws_view = IWebServiceExceptionView(view)
-            except TypeError:
-                # There's a view for this exception, but it's not one
-                # we can understand. It was probably designed for a
-                # web application rather than a web service. We'll
-                # re-raise the exception, let the publisher look up
-                # the view, and hopefully handle it better.  Note the careful
-                # reraising that ensures the original trackabck is preserved.
-                raise exception_info[0], exception_info[1], exception_info[2]
-
-            self.request.response.setStatus(ws_view.status)
-            if ws_view.status / 100 == 4:
-                # This exception corresponds to a client-side error
-                result = ws_view()
-            else:
-                # This exception corresponds to a server-side error
-                # (or some weird attempt to handle redirects or normal
-                # status codes using exceptions). Let the publisher
-                # handle it. (No need for carefuly reraising here, since there
-                # is only one exception in flight we just use a bare raise to
-                # reraise the original exception.)
-                raise
+        if method == "GET":
+            result = self.do_GET()
+        elif method in ["PUT", "PATCH"]:
+            media_type = self.handleConditionalWrite()
+            if media_type is not None:
+                stream = self.request.bodyStream
+                representation = stream.getCacheStream().read()
+                if method == "PUT":
+                    result = self.do_PUT(media_type, representation)
+                else:
+                    result = self.do_PATCH(media_type, representation)
+        elif method == "POST" and self.implementsPOST():
+            result = self.do_POST()
+        elif method == "DELETE" and self.implementsDELETE():
+            result = self.do_DELETE()
+        else:
+            allow_string = "GET PUT PATCH"
+            if self.implementsPOST():
+                allow_string += " POST"
+            if self.implementsDELETE():
+                allow_string += " DELETE"
+            self.request.response.setStatus(405)
+            self.request.response.setHeader("Allow", allow_string)
         return result
 
 
@@ -1016,6 +1073,7 @@
         changeset = copy.copy(changeset)
         validated_changeset = []
         errors = []
+        orig_interfaces = self.entry._orig_interfaces
 
         # Some fields aren't part of the schema, so they're handled
         # separately.
@@ -1174,6 +1232,8 @@
                         error = "Validation error"
                     errors.append(u"%s: %s" % (repr_name, error))
                     continue
+                self.checkWrite(self.entry.context, name, field)
+                self.caveat_checker.enforceCaveats(value)
                 validated_changeset.append((field, value))
         # If there are any fields left in the changeset, they're
         # fields that don't correspond to some field in the
@@ -1624,7 +1684,6 @@
         """An EntryAdapterUtility for this resource."""
         return EntryAdapterUtility(self.entry.__class__)
 
-
     @property
     def redacted_fields(self):
         """Names the fields the current user doesn't have permission to see."""
@@ -1632,40 +1691,7 @@
         orig_interfaces = self.entry._orig_interfaces
         for name, field in getFieldsInOrder(self.entry.schema):
             try:
-                # Can we view the field's value? We check the
-                # permission directly using the Zope permission
-                # checker, because doing it indirectly by fetching the
-                # value may have very slow side effects such as
-                # database hits.
-                try:
-                    tagged_values = field.getTaggedValue(
-                        'lazr.restful.exported')
-                    original_name = tagged_values['original_name']
-                except KeyError:
-                    # This field has no tagged values, or is missing
-                    # the 'original_name' value. Its entry class was
-                    # probably created by hand rather than by tagging
-                    # an interface. In that case, it's the
-                    # programmer's responsibility to set
-                    # 'original_name' if the web service field name
-                    # differs from the underlying interface's field
-                    # name. Since 'original_name' is not present, assume the
-                    # names are the same.
-                    original_name = name
-                context = orig_interfaces[name](self.context)
-                try:
-                    checker = getChecker(context)
-                except TypeError:
-                    # This is more expensive than using a Zope checker, but
-                    # there is no checker, so either there is no permission
-                    # control on this object, or permission control is
-                    # implemented some other way. Also note that we use
-                    # getattr() on self.entry rather than self.context because
-                    # some of the fields in entry.schema will be provided by
-                    # adapters rather than directly by self.context.
-                    getattr(self.entry, name)
-                else:
-                    checker.check(context, original_name)
+                self.checkRead(self.context, name, field)
             except Unauthorized:
                 # This is an expensive operation that will make this
                 # request more expensive still, but it happens
@@ -1699,6 +1725,8 @@
         if media_type in [self.WADL_TYPE, self.DEPRECATED_WADL_TYPE]:
             return self.toWADL().encode("utf-8")
         elif media_type in (self.JSON_TYPE, self.JSON_PLUS_XHTML_TYPE):
+            self.caveat_checker.enforceCaveats(self.context)
+
             cache = self._representation_cache
             if cache is None:
                 representation = None

=== added file 'src/lazr/restful/caveatchecker.py'
--- src/lazr/restful/caveatchecker.py	1970-01-01 00:00:00 +0000
+++ src/lazr/restful/caveatchecker.py	2016-03-02 13:25:07 +0000
@@ -0,0 +1,121 @@
+# Copyright 2016 Canonical Ltd.  All rights reserved.
+#
+# This file is part of lazr.restful.
+#
+# lazr.restful is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, version 3 of the License.
+#
+# lazr.restful 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 Lesser General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with lazr.restful.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Caveat checking."""
+
+__metaclass__ = type
+__all__ = [
+    'CaveatChecker',
+    ]
+
+from zope.component import (
+    adapter,
+    getUtility,
+    )
+from zope.interface import implementer
+from zope.publisher.interfaces import IApplicationRequest
+from zope.security.interfaces import Unauthorized
+from zope.security.management import queryInteraction
+from zope.security.proxy import getChecker
+
+from lazr.restful.interfaces import (
+    ICaveatChecker,
+    IInteractionWithUnauthenticatedCheck,
+    IPrincipalWithCaveats,
+    IWebServiceConfiguration,
+    )
+
+
+@implementer(ICaveatChecker)
+@adapter(IApplicationRequest)
+class CaveatChecker:
+    """A class that checks whether objects satisfy caveats in a request."""
+
+    def __init__(self, request):
+        self.request = request
+        self.view_permission = (
+            getUtility(IWebServiceConfiguration).view_permission)
+
+    def checkCaveats(self, object, permission=None, attribute=None):
+        """See `ICaveatChecker`."""
+        if not IPrincipalWithCaveats.providedBy(self.request.principal):
+            return True
+        if permission is None:
+            permission = self.view_permission
+        satisfied = all(
+            caveat.verify(permission, object, attribute=attribute)
+            for caveat in self.request.principal.caveats)
+        if not satisfied:
+            # Caveats are not satisfied, but we'll ignore that if an
+            # unauthenticated principal could perform this operation: that
+            # is, caveats never reduce permissions below those possessed by
+            # an anonymous user.
+            interaction = queryInteraction()
+            if (IInteractionWithUnauthenticatedCheck.providedBy(
+                    interaction) and
+                interaction.checkUnauthenticatedPermission(
+                    permission, object)):
+                return True
+        return satisfied
+
+    def enforceCaveats(self, object, permission=None, attribute=None):
+        """See `ICaveatChecker`."""
+        if permission is None:
+            permission = self.view_permission
+        if not self.checkCaveats(
+                object, permission=permission, attribute=attribute):
+            if attribute is None:
+                raise Unauthorized(object, permission)
+            else:
+                raise Unauthorized(object, attribute, permission)
+        return object
+
+    def check_setattr(self, object, attribute):
+        """See `ICaveatChecker`."""
+        try:
+            base_checker = getChecker(object)
+        except TypeError:
+            # We cannot check permissions in advance if there is no checker.
+            return
+        if base_checker.set_permissions:
+            permission = base_checker.set_permissions.get(attribute)
+        else:
+            permission = None
+        if permission is not None:
+            self.enforceCaveats(object, permission, attribute)
+        base_checker.check_setattr(object, attribute)
+
+    def check_getattr(self, object, attribute):
+        """See `ICaveatChecker`."""
+        try:
+            base_checker = getChecker(object)
+        except TypeError:
+            # We cannot check permissions in advance if there is no checker.
+            return
+        permission = base_checker.get_permissions.get(attribute)
+        if permission is not None:
+            self.enforceCaveats(object, permission, attribute)
+        base_checker.check_getattr(object, attribute)
+
+    def setattr(self, object, attribute, value):
+        """See `ICaveatChecker`."""
+        self.check_setattr(object, attribute)
+        setattr(object, attribute, value)
+
+    def getattr(self, object, attribute):
+        """See `ICaveatChecker`."""
+        self.check_getattr(object, attribute)
+        return getattr(object, attribute)

=== modified file 'src/lazr/restful/configure.zcml'
--- src/lazr/restful/configure.zcml	2012-03-13 02:03:47 +0000
+++ src/lazr/restful/configure.zcml	2016-03-02 13:25:07 +0000
@@ -40,6 +40,8 @@
 
     <adapter factory="lazr.restful.jsoncache.JSONRequestCache" />
 
+    <adapter factory="lazr.restful.caveatchecker.CaveatChecker" />
+
     <!-- TALES namespace for web service functions available through the
          website. -->
     <adapter

=== modified file 'src/lazr/restful/declarations.py'
--- src/lazr/restful/declarations.py	2015-04-08 20:11:29 +0000
+++ src/lazr/restful/declarations.py	2016-03-02 13:25:07 +0000
@@ -15,6 +15,7 @@
     'accessor_for',
     'cache_for',
     'call_with',
+    'check_parameter_permissions',
     'collection_default_content',
     'error_status',
     'exported',
@@ -55,6 +56,8 @@
     IText,
     )
 from zope.security.checker import CheckerPublic
+from zope.security.interfaces import Unauthorized
+from zope.security.management import checkPermission
 from zope.traversing.browser import absoluteURL
 
 from lazr.delegates import Passthrough
@@ -65,6 +68,7 @@
     )
 from lazr.restful.interface import copy_field
 from lazr.restful.interfaces import (
+    ICaveatChecker,
     ICollection,
     IEntry,
     IReference,
@@ -562,10 +566,12 @@
             if 'as' not in annotations:
                 annotations['as'] = method.__name__
 
-            # It's possible that call_with, operation_parameters, and/or
-            # operation_returns_* weren't used.
+            # It's possible that call_with, operation_parameters,
+            # check_parameter_permissions, and/or operation_returns_*
+            # weren't used.
             annotations.setdefault('call_with', {})
             annotations.setdefault('params', {})
+            annotations.setdefault('param_permissions', {})
             annotations.setdefault('return_type', None)
 
             # Make sure that all parameters exist and that we miss none.
@@ -574,6 +580,7 @@
             defined_params.update(info['required'])
             exported_params = set(annotations['params'])
             exported_params.update(annotations['call_with'])
+            exported_params.update(annotations['param_permissions'])
             undefined_params = exported_params.difference(defined_params)
             if undefined_params and info['kwargs'] is None:
                 raise TypeError(
@@ -632,6 +639,20 @@
         annotations['call_with'] = self.params
 
 
+class check_parameter_permissions(_method_annotator):
+    """Decorator indicating that calling a method requires specified
+    permissions on parameters.
+    """
+    def __init__(self, **params):
+        _check_called_from_interface_def('%s()' % self.__class__.__name__)
+        self.params = params
+
+    def annotate_method(self, method, annotations):
+        """See `_method_annotator`."""
+        annotations.setdefault('param_permissions', [])
+        annotations['param_permissions'] = self.params
+
+
 class mutator_for(_method_annotator):
     """Decorator indicating that an exported method mutates a field.
 
@@ -1225,6 +1246,15 @@
     return params
 
 
+def get_caveat_checker(instance):
+    """Get a caveat checker appropriate for an instance."""
+    if instance is None or instance.request is None:
+        request = get_current_web_service_request()
+    else:
+        request = instance.request
+    return ICaveatChecker(request)
+
+
 class _AccessorWrapper:
     """A wrapper class for properties with accessors.
 
@@ -1242,7 +1272,8 @@
         # Error checking code in accessor_for() guarantees that there
         # is one and only one non-fixed parameter for the accessor
         # method.
-        return getattr(context, self.accessor)(**params)
+        caveat_checker = get_caveat_checker(obj)
+        return caveat_checker.getattr(context, self.accessor)(**params)
 
 
 class _MutatorWrapper:
@@ -1262,7 +1293,8 @@
         # Error checking code in mutator_for() guarantees that there
         # is one and only one non-fixed parameter for the mutator
         # method.
-        getattr(context, self.mutator)(new_value, **params)
+        caveat_checker = get_caveat_checker(obj)
+        caveat_checker.getattr(context, self.mutator)(new_value, **params)
 
 
 class PropertyWithAccessor(_AccessorWrapper, Passthrough):
@@ -1336,7 +1368,8 @@
 
     def find(self):
         """See `ICollection`."""
-        method = getattr(self.context, self.method_name)
+        caveat_checker = get_caveat_checker(self)
+        method = caveat_checker.getattr(self.context, self.method_name)
         params = params_with_dereferenced_user(self.params)
         return method(**params)
 
@@ -1371,7 +1404,8 @@
     """Base class for generated operation adapters."""
 
     def _getMethod(self):
-        return getattr(self._orig_iface(self.context), self._method_name)
+        return self.caveat_checker.getattr(
+            self._orig_iface(self.context), self._method_name)
 
     def _getMethodParameters(self, kwargs):
         """Return the method parameters.
@@ -1394,6 +1428,15 @@
         # Handle fixed parameters.
         params.update(params_with_dereferenced_user(
                 self._export_info['call_with']))
+
+        # Handle any requested parameter permission checks.
+        for name, permission in self._export_info['param_permissions'].items():
+            param = params.get(name)
+            if param is not None:
+                if not checkPermission(permission, param):
+                    raise Unauthorized(param, permission)
+                self.caveat_checker.enforceCaveats(param, permission)
+
         return params
 
     def call(self, **kwargs):
@@ -1409,6 +1452,7 @@
                 % self._export_info['cache_for'])
 
         result = self._getMethod()(**params)
+        self.caveat_checker.enforceCaveats(result)
         return self.encodeResult(result)
 
 
@@ -1423,6 +1467,7 @@
         """
         params = self._getMethodParameters(kwargs)
         result = self._getMethod()(**params)
+        self.caveat_checker.enforceCaveats(result)
         response = self.request.response
         response.setStatus(201)
         response.setHeader('Location', absoluteURL(result, self.request))

=== modified file 'src/lazr/restful/docs/webservice-declarations.txt'
--- src/lazr/restful/docs/webservice-declarations.txt	2016-02-17 01:07:21 +0000
+++ src/lazr/restful/docs/webservice-declarations.txt	2016-03-02 13:25:07 +0000
@@ -427,6 +427,7 @@
     as: 'create_book'
     call_with: {}
     creates: <...IBook...>
+    param_permissions: {}
     params: {'author': <...TextLine...>,
         'base_price': <...Float...>,
         'title': <...TextLine...>}
@@ -439,6 +440,7 @@
     >>> print_export_tag(IBookSetOnSteroids['searchBookTitles'])
     as: 'searchBookTitles'
     call_with: {}
+    param_permissions: {}
     params: {'text': <...TextLine...>}
     return_type: <lazr.restful.fields.CollectionField object...>
     type: 'read_operation'
@@ -448,6 +450,7 @@
     >>> print_export_tag(IBookSetOnSteroids['bestMatch'])
     as: 'bestMatch'
     call_with: {}
+    param_permissions: {}
     params: {'text': <...TextLine...>}
     return_type: <lazr.restful.fields.Reference object...>
     type: 'read_operation'
@@ -457,6 +460,7 @@
     >>> print_export_tag(IBookOnSteroids['checkout'])
     as: 'checkout'
     call_with: {'kind': 'normal', 'who': <class '...REQUEST_USER'>}
+    param_permissions: {}
     params: {}
     return_type: None
     type: 'write_operation'
@@ -486,6 +490,7 @@
     as: 'create_book'
     call_with: {}
     creates: <...IBook...>
+    param_permissions: {}
     params: {'author': <...TextLine...>,
         'collection': <...TextLine...>,
         'title': <...TextLine...>}
@@ -804,12 +809,14 @@
     == rename ==
     as: 'rename'
     call_with: {}
+    param_permissions: {}
     params: {'new_name': <...TextLine...>}
     return_type: None
     type: 'write_operation'
     == talk_to ==
     as: 'talk_to'
     call_with: {}
+    param_permissions: {}
     params: {'msg': <...TextLine...>,
         'to': <...Object...>}
     return_type: None
@@ -897,6 +904,9 @@
     ...                      (ITestServiceRequest30, '3.0')]:
     ...     sm.registerUtility(marker, IWebServiceVersion, name=name)
 
+    >>> from lazr.restful.caveatchecker import CaveatChecker
+    >>> sm.registerAdapter(CaveatChecker)
+
     >>> from lazr.restful.testing.webservice import FakeRequest
     >>> request = FakeRequest(version='beta')
 
@@ -2591,6 +2601,79 @@
     zope.security._proxy._Proxy (using zope.security.checker.Checker)
         public: __call__, send_modification_event
 
+Additional permission checking
+------------------------------
+
+The @check_parameter_permissions decorator allows stating that additional
+permissions are required on some parameters.
+
+    >>> from zope.security.management import (
+    ...     queryInteraction,
+    ...     setSecurityPolicy,
+    ...     )
+    >>> from zope.security.permission import Permission
+    >>> from zope.security.simplepolicies import PermissiveSecurityPolicy
+    >>> from lazr.restful.caveatchecker import CaveatChecker
+    >>> from lazr.restful.declarations import check_parameter_permissions
+    >>> from lazr.restful.security import protect_schema
+
+    >>> class CachedOnlySecurityPolicy(PermissiveSecurityPolicy):
+    ...     def __init__(self, *participations):
+    ...         super(CachedOnlySecurityPolicy, self).__init__(
+    ...             *participations)
+    ...         self.cache = {}
+    ...
+    ...     def checkPermission(self, permission, object):
+    ...         return self.cache.get(object, {}).get(permission, False)
+
+    >>> class IParameterPermissions(Interface):
+    ...     export_as_webservice_entry()
+    ...
+    ...     @check_parameter_permissions(foo='lazr.Edit', bar='lazr.Edit')
+    ...     @operation_parameters(
+    ...         foo=Reference(schema=Interface),
+    ...         bar=Reference(schema=Interface, required=False))
+    ...     @export_write_operation()
+    ...     def test_function(foo, bar=None):
+    ...         pass
+
+    >>> @implementer(IParameterPermissions)
+    ... class ParameterPermissions(object):
+    ...     def test_function(self, foo, bar=None):
+    ...         return foo, bar
+
+    >>> sm.registerAdapter(CaveatChecker)
+    >>> sm.registerUtility(Permission('lazr.Edit'), name='lazr.Edit')
+    >>> protect_schema(HasText, IHasText, write_permission='lazr.Edit')
+
+    >>> pp_test_function_adapter_factory = generate_operation_adapter(
+    ...     IParameterPermissions['test_function'])
+    >>> setSecurityPolicy(CachedOnlySecurityPolicy)
+    <class ...>
+    >>> endInteraction()
+    >>> newInteraction()
+    >>> interaction = queryInteraction()
+    >>> pp_object = ParameterPermissions()
+    >>> foo = HasText()
+    >>> bar = HasText()
+    >>> pp_test_function_adapter = pp_test_function_adapter_factory(
+    ...     pp_object, request)
+
+    >>> pp_test_function_adapter.call(foo=foo)
+    Traceback (most recent call last):
+    ...
+    Unauthorized: (<HasText object...>, 'lazr.Edit')
+    >>> interaction.cache.setdefault(foo, {})['lazr.Edit'] = True
+    >>> pp_test_function_adapter.call(foo=foo)
+    (<HasText object...>, None)
+    >>> pp_test_function_adapter.call(foo=foo, bar=bar)
+    Traceback (most recent call last):
+    ...
+    Unauthorized: (<HasText object...>, 'lazr.Edit')
+    >>> interaction.cache.setdefault(bar, {})['lazr.Edit'] = True
+    >>> pp_test_function_adapter.call(foo=foo, bar=bar)
+    (<HasText object...>, <HasText object...>)
+
 ZCML Registration
 =================
 

=== modified file 'src/lazr/restful/docs/webservice-marshallers.txt'
--- src/lazr/restful/docs/webservice-marshallers.txt	2016-02-16 13:32:24 +0000
+++ src/lazr/restful/docs/webservice-marshallers.txt	2016-03-02 13:25:07 +0000
@@ -8,10 +8,19 @@
 To test the various marshallers we create a dummy request and
 application root.
 
+    >>> from zope.component import (
+    ...     provideAdapter,
+    ...     provideUtility,
+    ...     )
+    >>> from lazr.restful.caveatchecker import CaveatChecker
+    >>> from lazr.restful.interfaces import IWebServiceConfiguration
+    >>> from lazr.restful.testing.helpers import TestWebServiceConfiguration
     >>> from lazr.restful.testing.webservice import WebServiceTestPublication
     >>> from lazr.restful.simple import Request
     >>> from lazr.restful.example.base.root import (
     ...     CookbookServiceRootResource)
+    >>> provideUtility(TestWebServiceConfiguration(), IWebServiceConfiguration)
+    >>> provideAdapter(CaveatChecker)
     >>> request = Request("", {'HTTP_HOST': 'cookbooks.dev'})
     >>> request.annotations[request.VERSION_ANNOTATION] = '1.0'
     >>> application = CookbookServiceRootResource()

=== modified file 'src/lazr/restful/docs/webservice.txt'
--- src/lazr/restful/docs/webservice.txt	2016-02-17 01:07:21 +0000
+++ src/lazr/restful/docs/webservice.txt	2016-03-02 13:25:07 +0000
@@ -50,6 +50,9 @@
     ...     cuisine = TextLine(title=u"Cuisine", required=False, default=None)
     ...     recipes = Attribute("List of recipes published in this cookbook.")
     ...     cover = Bytes(0, 5000, title=u"An image of the cookbook's cover.")
+    ...     auth_required = Bool(
+    ...         title=u"Whether viewing this requires authentication.",
+    ...         default=False)
     ...     def removeRecipe(recipe):
     ...         """Remove a recipe from this cookbook."""
 
@@ -65,8 +68,11 @@
     ...     cookbook = Reference(schema=ICookbook)
     ...     instructions = Text(title=u"How to prepare the recipe.",
     ...         required=True)
-    ...     private = Bool(title=u"Whether the public can see this recipe.",
-    ...                    default=False)
+    ...     private = Bool(
+    ...         title=u"Whether this recipe is private.", default=False)
+    ...     auth_required = Bool(
+    ...         title=u"Whether viewing this recipe requires authentication.",
+    ...         default=False)
     ...     def delete():
     ...         """Delete this recipe."""
 
@@ -87,6 +93,9 @@
     ...         "Retrieve a single author by name."
 
     >>> class ICookbookSet(ITestDataSet):
+    ...     def newCookbook(self, author_name, title, cuisine):
+    ...         """Create a new cookbook."""
+    ...
     ...     def getAll(self):
     ...         "Get all cookbooks."
     ...
@@ -190,6 +199,7 @@
     ...         self.comments = []
     ...         self.cuisine = cuisine
     ...         self.cover = None
+    ...         self.auth_required = True
     ...
     ...     @property
     ...     def path(self):
@@ -251,7 +261,7 @@
     ... class Recipe:
     ...     path = ''
     ...     def __init__(self, id, cookbook, dish, instructions,
-    ...                  private=False):
+    ...                  private=False, auth_required=False):
     ...         self.id = id
     ...         self.cookbook = cookbook
     ...         self.cookbook.recipes.append(self)
@@ -260,6 +270,7 @@
     ...         self.instructions = instructions
     ...         self.comments = []
     ...         self.private = private
+    ...         self.auth_required = auth_required
     ...     def delete(self):
     ...         self.cookbook.removeRecipe(self)
     ...         self.dish.removeRecipe(self)
@@ -324,11 +335,18 @@
     >>> C3_D1 = Recipe(3, C3, D1, u"A perfectly roasted chicken is...")
 
     >>> D2 = Dish("Baked beans")
-    >>> C2_D2 = Recipe(4, C2, D2, "Preheat oven to...")
-    >>> C3_D2 = Recipe(5, C3, D2, "Without doubt the most famous...", True)
+    >>> C1_D2 = Recipe(4, C1, D2, "57 varieties...", auth_required=True)
+    >>> C2_D2 = Recipe(5, C2, D2, "Preheat oven to...")
+    >>> C3_D2 = Recipe(
+    ...     6, C3, D2, "Without doubt the most famous...",
+    ...     private=True, auth_required=True)
 
     >>> D3 = Dish("Foies de voilaille en aspic")
-    >>> C1_D3 = Recipe(6, C1, D3, "Chicken livers sauteed in butter...")
+    >>> C1_D3 = Recipe(
+    ...     7, C1, D3, "Chicken livers sauteed in butter...",
+    ...     auth_required=True)
+    >>> C2_D3 = Recipe(
+    ...     8, C2, D3, "More chicken livers...", auth_required=True)
 
     >>> COM1 = Comment(C2_D1, "Clear and concise.")
     >>> COM2 = Comment(C2, "A kitchen staple.")
@@ -379,7 +397,9 @@
     ...             raise ValueError("No matches for %s" % name)
     ...         return matches
 
+    >>> from zope.security.protectclass import protectName
     >>> protect_schema(CookbookSet, ICookbookSet)
+    >>> protectName(CookbookSet, 'newCookbook', 'zope.Edit')
     >>> sm.registerUtility(CookbookSet(), ICookbookSet)
 
 Here's a simple AuthorSet with predefined authors.
@@ -460,15 +480,24 @@
     >>> from zope.security.management import setSecurityPolicy
     >>> from zope.security.simplepolicies import PermissiveSecurityPolicy
     >>> from zope.security.proxy import removeSecurityProxy
+    >>> from lazr.restful.interfaces import (
+    ...     IInteractionWithUnauthenticatedCheck,
+    ...     )
 
     >>> sm.registerUtility(Permission('zope.View'), name='zope.View')
 
-    >>> class SimpleSecurityPolicy(PermissiveSecurityPolicy):
+    >>> @implementer(IInteractionWithUnauthenticatedCheck)
+    ... class SimpleSecurityPolicy(PermissiveSecurityPolicy):
     ...     def checkPermission(self, permission, object):
     ...         if IRecipe.providedBy(object):
     ...             return not removeSecurityProxy(object).private
     ...         else:
     ...             return True
+    ...     def checkUnauthenticatedPermission(self, permission, object):
+    ...         if IRecipe.providedBy(object) or ICookbook.providedBy(object):
+    ...             return not removeSecurityProxy(object).auth_required
+    ...         else:
+    ...             return permission == 'zope.View'
 
     >>> setSecurityPolicy(SimpleSecurityPolicy)
     <class ...>
@@ -980,8 +1009,10 @@
     ...     return_type = Reference(schema=IRecipe)
     ...
     ...     def call(self, author_name, title, cuisine):
-    ...         cookbook = CookbookSet().newCookbook(
-    ...             author_name, title, cuisine)
+    ...         method = self.caveat_checker.getattr(
+    ...             self.context, 'newCookbook')
+    ...         cookbook = method(author_name, title, cuisine)
+    ...         self.caveat_checker.enforceCaveats(cookbook)
     ...         self.request.response.setStatus(201)
     ...         self.request.response.setHeader(
     ...             "Location", absoluteURL(cookbook, self.request))
@@ -1829,6 +1860,153 @@
     >>> print put_request.response.getStatus()
     401
 
+Caveats
+=======
+
+Resource visibility may also be restricted by caveats attached to a
+principal.  We define an example caveat which is only satisfied by
+non-recipes or by recipes for a particular set of dishes.
+
+    >>> from lazr.restful.testing.webservice import (
+    ...     FakeCaveat,
+    ...     FakePrincipal,
+    ...     )
+
+    >>> class DishCaveat(FakeCaveat):
+    ...     def __init__(self, argument):
+    ...         super(DishCaveat, self).__init__("dish", argument)
+    ...     def verify(self, permission, object, attribute=None):
+    ...         if not IRecipe.providedBy(object):
+    ...             return True
+    ...         return object.dish.name in self.argument
+
+A request without caveats (which our simple security policy will normally
+pretend is authenticated) can see recipes regardless of whether they require
+authentication.
+
+    >>> public_recipe_url = quote(
+    ...     "/beta/cookbooks/Mastering the Art of French Cooking/recipes/"
+    ...     "Roast chicken")
+    >>> auth_required_recipe_urls = [
+    ...     quote(
+    ...         "/beta/cookbooks/Mastering the Art of French Cooking/recipes/"
+    ...         "Baked beans"),
+    ...     quote(
+    ...         "/beta/cookbooks/The Joy of Cooking/recipes/"
+    ...         "Foies de voilaille en aspic"),
+    ...     ]
+    >>> for url in [public_recipe_url] + auth_required_recipe_urls:
+    ...     get_request = create_web_service_request(public_recipe_url)
+    ...     recipe_resource = get_request.traverse(app)
+
+A request with a caveat restricting it to a particular dish can still see
+the public recipe and the one that requires authentication and satisfies the
+caveat, but not the one that requires authentication and does not satisfy
+the caveat.
+
+    >>> principal = FakePrincipal()
+    >>> principal.caveats.append(DishCaveat(["Baked beans"]))
+    >>> for url in [public_recipe_url, auth_required_recipe_urls[0]]:
+    ...     get_request = create_web_service_request(url, principal=principal)
+    ...     recipe_resource = get_request.traverse(app)
+    >>> get_request = create_web_service_request(
+    ...     auth_required_recipe_urls[1], principal=principal)
+    >>> recipe_resource = get_request.traverse(app)
+    >>> print recipe_resource()
+    (<Recipe object...>, u'zope.View')
+
+Links are redacted if they fail to satisfy caveats.
+
+    >>> child_url = quote('/beta/authors/Julia Child')
+    >>> get_request = create_web_service_request(
+    ...     child_url, principal=principal)
+    >>> author_resource = get_request.traverse(app)
+    >>> author = load_json(author_resource())
+    >>> author['name']
+    u'Julia Child'
+    >>> author['favorite_recipe_link']
+    u'.../The%20Joy%20of%20Cooking/recipes/Baked%20beans'
+
+    >>> A1.favorite_recipe = C1_D3
+    >>> get_request = create_web_service_request(
+    ...     child_url, principal=principal)
+    >>> author_resource = get_request.traverse(app)
+    >>> author = load_json(author_resource())
+    >>> author['name']
+    u'Julia Child'
+    >>> author['favorite_recipe_link']
+    u'tag:launchpad.net:2008:redacted'
+
+When setting an attribute value, the new value must satisfy caveats.
+
+    >>> A1.favorite_recipe = C1_D1
+    >>> get_request = create_web_service_request(
+    ...     child_url, principal=principal)
+    >>> author_resource = get_request.traverse(app)
+    >>> author = load_json(author_resource())
+    >>> author['favorite_recipe_link'] = (
+    ...     'http://api.cookbooks.dev' + auth_required_recipe_urls[0])
+    >>> body = simplejson.dumps(author)
+    >>> put_request = create_web_service_request(
+    ...     child_url, body=body, environ=headers, method='PUT',
+    ...     principal=principal)
+    >>> put_request.traverse(app)()
+    '{..."favorite_recipe_link": ".../Baked%20beans"...}'
+    >>> put_request.response.getStatus()
+    209
+
+    >>> get_request = create_web_service_request(
+    ...     child_url, principal=principal)
+    >>> author_resource = get_request.traverse(app)
+    >>> author = load_json(author_resource())
+    >>> author['favorite_recipe_link'] = (
+    ...     'http://api.cookbooks.dev' + auth_required_recipe_urls[1])
+    >>> body = simplejson.dumps(author)
+    >>> put_request = create_web_service_request(
+    ...     child_url, body=body, environ=headers, method='PUT',
+    ...     principal=principal)
+    >>> print put_request.traverse(app)()
+    (<Recipe object...>, u'zope.View')
+    >>> print put_request.response.getStatus()
+    401
+
+Caveats can restrict named POST operations.
+
+    >>> class CookbookCaveat(FakeCaveat):
+    ...     def __init__(self, argument):
+    ...         super(CookbookCaveat, self).__init__("cookbook", argument)
+    ...     def verify(self, permission, object, attribute=None):
+    ...         if not ICookbook.providedBy(object):
+    ...             return True
+    ...         return object.name in self.argument
+
+    >>> principal.caveats = [CookbookCaveat(['Good name'])]
+
+    >>> body = ("ws.op=create_cookbook&title=Good%20name&"
+    ...         "author_name=James%20Beard")
+    >>> request = create_web_service_request(
+    ...     '/beta/cookbooks', 'POST', body,
+    ...     {'CONTENT_TYPE' : 'application/x-www-form-urlencoded'},
+    ...     principal=principal)
+    >>> operation_resource = request.traverse(app)
+    >>> result = operation_resource()
+    >>> request.response.getStatus()
+    201
+    >>> request.response.getHeader('Location')
+    'http://api.cookbooks.dev/beta/cookbooks/Good%20name'
+
+    >>> body = ("ws.op=create_cookbook&title=Bad%20name&"
+    ...         "author_name=James%20Beard")
+    >>> request = create_web_service_request(
+    ...     '/beta/cookbooks', 'POST', body,
+    ...     {'CONTENT_TYPE' : 'application/x-www-form-urlencoded'},
+    ...     principal=principal)
+    >>> operation_resource = request.traverse(app)
+    >>> print operation_resource()
+    (<Cookbook object...>, u'zope.View')
+    >>> request.response.getStatus()
+    401
+
 Stored file resources
 =====================
 

=== modified file 'src/lazr/restful/interfaces/_rest.py'
--- src/lazr/restful/interfaces/_rest.py	2011-03-31 01:13:59 +0000
+++ src/lazr/restful/interfaces/_rest.py	2016-03-02 13:25:07 +0000
@@ -22,6 +22,8 @@
 __all__ = [
     'IByteStorage',
     'IByteStorageResource',
+    'ICaveat',
+    'ICaveatChecker',
     'ICollection',
     'ICollectionResource',
     'IEntry',
@@ -32,9 +34,11 @@
     'IFieldMarshaller',
     'IFileLibrarian',
     'IHTTPResource',
+    'IInteractionWithUnauthenticatedCheck',
     'INotificationsProvider',
     'IJSONPublishable',
     'IJSONRequestCache',
+    'IPrincipalWithCaveats',
     'IRepresentationCache',
     'IResourceOperation',
     'IResourceGETOperation',
@@ -57,6 +61,7 @@
     ]
 
 from textwrap import dedent
+from zope.authentication.interfaces import IPrincipal
 from zope.schema import (
     Bool,
     Dict,
@@ -78,6 +83,7 @@
     IBrowserRequest,
     IDefaultBrowserLayer,
     )
+from zope.security.interfaces import IInteraction
 from lazr.batchnavigator.interfaces import InvalidBatchSizeError
 
 # Constants for periods of time
@@ -329,6 +335,126 @@
     """
     pass
 
+
+class ICaveat(Interface):
+    """A caveat that restricts the scope of a principal.
+
+    Caveats extend standard Zope security checks with finer-grained
+    restrictions, but they are typically only applied at the request
+    boundary.
+
+    For example, a webservice method call checks that caveats permit read or
+    write access (depending on its declaration) to the method on the context
+    object and read access to all method parameters; while setting an
+    attribute checks that caveats permit write access to the attribute on
+    the context object and read access to the new value.  In either case,
+    caveats are not checked for any internal operations performed by the
+    method call or the attribute setter.
+    """
+
+    condition = TextLine(
+        title=u"Condition", description=u"The condition part of this caveat.")
+    argument = TextLine(
+        title=u"Argument", description=u"The argument part of this caveat.")
+
+    text = TextLine(title=u"A serialised form of this caveat.")
+
+    def verify(permission, object, attribute=None):
+        """Return whether a caveat is satisfied for permission on object.
+
+        :param permission: A permission name.
+        :param object: The object being accessed according to the permission.
+        :param attribute: The attribute of the object being accessed, if
+            any.  Since caveats may specify particular method and attribute
+            names that may be accessed, a full caveat check may require this
+            information in addition to the permission name (which is
+            sufficient for other kinds of permission checks on an object).
+            Callers that are merely checking a principal's authorization to
+            view an object rather than to call a method or view/change an
+            attribute on it do not need to pass an attribute name.
+        """
+
+
+class IPrincipalWithCaveats(IPrincipal):
+    """A principal that may have some `ICaveat`s attached to it."""
+
+    caveats = Attribute(
+        "List of `ICaveat`s restricting the scope of this principal.")
+
+
+class ICaveatChecker(Interface):
+    """A class that checks whether objects satisfy caveats in a request."""
+
+    def checkCaveats(object, permission=None, attribute=None):
+        """Check whether `object` satisfies caveats.
+
+        :param object: The object to check.
+        :param permission: The Zope permission indicating the kind of
+            operation being performed.  If None, check for view permission
+            according to the webservice configuration.
+        :param attribute: If not None, check caveats that apply to
+            reading/writing this attribute on `object`; if None, only check
+            caveats on `object` itself.
+        """
+
+    def enforceCaveats(object, permission=None, attribute=None):
+        """Raise `Unauthorized` if `object` does not satisfy caveats.
+
+        :param object: The object to check.
+        :param permission: The Zope permission indicating the kind of
+            operation being performed.  If None, check for view permission
+            according to the webservice configuration.
+        :param attribute: If not None, check caveats that apply to
+            reading/writing this attribute on `object`; if None, only check
+            caveats on `object` itself.
+        """
+
+    def check_setattr(object, attribute):
+        """Check whether setting an object's attribute is allowed.
+
+        This checks both basic Zope security and caveats.
+
+        :param object: The object to check.
+        :param attribute: The attribute name to check.
+        """
+
+    def check_getattr(object, attribute):
+        """Check whether getting an object's attribute is allowed.
+
+        This checks both basic Zope security and caveats.
+
+        :param object: The object to check.
+        :param attribute: The attribute name to check.
+        """
+
+    def setattr(object, attribute, value):
+        """Set an object's attribute after checking that it is allowed.
+
+        :param object: The object whose attribute is to be set.
+        :param attribute: The attribute name to set.
+        :param value: The new attribute value.
+        """
+
+    def getattr(object, attribute):
+        """Get an object's attribute after checking that it is allowed.
+
+        :param object: The object whose attribute is to be got.
+        :param attribute: The attribute name to get.
+        """
+
+
+class IInteractionWithUnauthenticatedCheck(IInteraction):
+    """An interaction that can do a separate unauthenticated check."""
+
+    def checkUnauthenticatedPermission(permission, object):
+        """Return whether an unauthenticated user has permission on object.
+
+        :param permission: A permission name.
+        :param object: The object being accessed according to the
+            permission.
+        """
+
+
 class IJSONRequestCache(Interface):
     """A cache of objects exposed as URLs or JSON representations."""
 

=== modified file 'src/lazr/restful/marshallers.py'
--- src/lazr/restful/marshallers.py	2016-02-17 01:07:21 +0000
+++ src/lazr/restful/marshallers.py	2016-03-02 13:25:07 +0000
@@ -49,6 +49,7 @@
     )
 
 from lazr.restful.interfaces import (
+    ICaveatChecker,
     IFieldMarshaller,
     IUnmarshallingDoesntNeedValue,
     IServiceRootResource,
@@ -117,7 +118,7 @@
         request = config.createRequest(StringIO(), {'PATH_INFO': path})
         request.setTraversalStack(path_parts)
         root = request.publication.getApplication(self.request)
-        return request.traverse(root)
+        return self.caveat_checker.enforceCaveats(request.traverse(root))
 
 
 @implementer(IFieldMarshaller)
@@ -133,6 +134,7 @@
     def __init__(self, field, request):
         self.field = field
         self.request = request
+        self.caveat_checker = ICaveatChecker(request)
 
     def marshall_from_json_data(self, value):
         """See `IFieldMarshaller`.
@@ -142,7 +144,8 @@
         """
         if value is None:
             return None
-        return self._marshall_from_json_data(value)
+        return self.caveat_checker.enforceCaveats(
+            self._marshall_from_json_data(value))
 
     def marshall_from_request(self, value):
         """See `IFieldMarshaller`.
@@ -170,7 +173,8 @@
                 value = v[0]
         if value is None:
             return None
-        return self._marshall_from_request(value)
+        return self.caveat_checker.enforceCaveats(
+            self._marshall_from_request(value))
 
     def _marshall_from_request(self, value):
         """Hook method to marshall a non-null JSON value.
@@ -264,6 +268,7 @@
 
         Marshall as a link to the byte storage resource.
         """
+        self.caveat_checker.enforceCaveats(entry.context)
         return "%s/%s" % (absoluteURL(entry.context, self.request),
                           self.field.__name__)
 
@@ -560,6 +565,7 @@
 
         This returns a link to the scoped collection.
         """
+        self.caveat_checker.enforceCaveats(entry.context)
         return "%s/%s" % (absoluteURL(entry.context, self.request),
                           self.field.__name__)
 
@@ -628,6 +634,7 @@
         """
         repr_value = None
         if value is not None:
+            self.caveat_checker.enforceCaveats(value)
             repr_value = absoluteURL(value, self.request)
         return repr_value
 

=== modified file 'src/lazr/restful/testing/webservice.py'
--- src/lazr/restful/testing/webservice.py	2016-02-17 01:07:21 +0000
+++ src/lazr/restful/testing/webservice.py	2016-03-02 13:25:07 +0000
@@ -7,6 +7,8 @@
     'create_web_service_request',
     'DummyAbsoluteURL',
     'DummyRootResourceURL',
+    'FakeCaveat',
+    'FakePrincipal',
     'FakeRequest',
     'FakeResponse',
     'IGenericEntry',
@@ -32,21 +34,29 @@
     adapter, getGlobalSiteManager, getUtility)
 from zope.configuration import xmlconfig
 from zope.interface import alsoProvides, implementer, Interface
+from zope.principalregistry.principalregistry import PrincipalBase
+from zope.proxy import ProxyBase
 from zope.publisher.interfaces.http import IHTTPApplicationRequest
 from zope.publisher.paste import Application
-from zope.proxy import ProxyBase
 from zope.schema import TextLine
 from zope.security.checker import ProxyFactory
 from zope.testing.cleanup import CleanUp
 from zope.traversing.browser.interfaces import IAbsoluteURL
 
+from lazr.restful.caveatchecker import CaveatChecker
 from lazr.restful.declarations import (
     collection_default_content, exported,
     export_as_webservice_collection, export_as_webservice_entry,
     export_read_operation, operation_parameters)
 from lazr.restful.interfaces import (
-    IServiceRootResource, IWebServiceClientRequest,
-    IWebServiceConfiguration, IWebServiceLayer, IWebServiceVersion)
+    ICaveat,
+    IPrincipalWithCaveats,
+    IServiceRootResource,
+    IWebServiceClientRequest,
+    IWebServiceConfiguration,
+    IWebServiceLayer,
+    IWebServiceVersion,
+    )
 from lazr.restful.simple import (
     BaseWebServiceConfiguration, Publication, Request,
     RootResourceAbsoluteURL, ServiceRootResource)
@@ -54,7 +64,7 @@
 
 
 def create_web_service_request(path_info, method='GET', body=None,
-                               environ=None, hostname=None):
+                               environ=None, hostname=None, principal=None):
     """Create a web service request object with the given parameters.
 
     :param path_info: The path portion of the requested URL.
@@ -81,6 +91,8 @@
         test_environ['CONTENT_LENGTH'] = len(body)
         body_instream = StringIO(body)
     request = config.createRequest(body_instream, test_environ)
+    if principal is not None:
+        request.setPrincipal(principal)
 
     request.processInputs()
     # This sets the request as the current interaction.
@@ -168,6 +180,28 @@
         return default
 
 
+@implementer(ICaveat)
+class FakeCaveat:
+    """Simple caveat object for testing."""
+
+    def __init__(self, condition, argument):
+        self.condition = condition
+        self.argument = argument
+
+    def verify(self, permission, object, attribute=None):
+        return getattr(object, self.condition) in self.argument
+
+
+@implementer(IPrincipalWithCaveats)
+class FakePrincipal(PrincipalBase):
+    """Simple principal object for testing."""
+
+    def __init__(self):
+        super(FakePrincipal, self).__init__(
+            1, "fake-principal", "Fake principal")
+        self.caveats = []
+
+
 def pprint_entry(json_body):
     """Pretty-print a webservice entry JSON representation.
 
@@ -451,6 +485,7 @@
         webservice_configuration = WebServiceTestConfiguration()
         sm = getGlobalSiteManager()
         sm.registerUtility(webservice_configuration)
+        sm.registerAdapter(CaveatChecker)
 
         # Register IWebServiceVersions for the
         # '1.0' and '2.0' web service versions.

=== modified file 'src/lazr/restful/tests/test_etag.py'
--- src/lazr/restful/tests/test_etag.py	2016-02-17 00:49:58 +0000
+++ src/lazr/restful/tests/test_etag.py	2016-03-02 13:25:07 +0000
@@ -5,11 +5,18 @@
 
 import unittest
 
-from zope.component import provideUtility
+from zope.component import (
+    provideAdapter,
+    provideUtility,
+    )
 
+from lazr.restful.caveatchecker import CaveatChecker
 from lazr.restful.interfaces import IWebServiceConfiguration
 from lazr.restful.testing.helpers import TestWebServiceConfiguration
-from lazr.restful.testing.webservice import create_web_service_request
+from lazr.restful.testing.webservice import (
+    create_web_service_request,
+    FakeRequest,
+    )
 from lazr.restful._resource import (
     EntryFieldResource,
     HTTPResource,
@@ -81,11 +88,17 @@
 
 class TestHTTPResourceETags(unittest.TestCase):
 
+    def setUp(self):
+        self.config = TestWebServiceConfiguration()
+        provideUtility(self.config, IWebServiceConfiguration)
+        provideAdapter(CaveatChecker)
+
     def test_getETag_is_a_noop(self):
         # The HTTPResource class implements a do-nothing _getETagCores in order to
         # be conservative (because it's not aware of the nature of all possible
         # subclasses).
-        self.assertEquals(HTTPResource(None, None)._getETagCores(), None)
+        self.assertEqual(
+            None, HTTPResource(None, FakeRequest())._getETagCores())
 
 
 class FauxEntryField:
@@ -105,7 +118,8 @@
     def setUp(self):
         self.config = TestWebServiceConfiguration()
         provideUtility(self.config, IWebServiceConfiguration)
-        self.resource = EntryFieldResource(FauxEntryField(), None)
+        provideAdapter(CaveatChecker)
+        self.resource = EntryFieldResource(FauxEntryField(), FakeRequest())
 
     def set_field_value(self, value):
         """Set the value of the fake field the EntryFieldResource references.
@@ -162,6 +176,7 @@
     def setUp(self):
         self.config = TestWebServiceConfiguration()
         provideUtility(self.config, IWebServiceConfiguration)
+        provideAdapter(CaveatChecker)
         self.resource = ServiceRootResource()
 
     def test_cores_change_with_revno(self):
@@ -195,6 +210,7 @@
     def setUp(self):
         self.config = TestWebServiceConfiguration()
         provideUtility(self.config, IWebServiceConfiguration)
+        provideAdapter(CaveatChecker)
         self.request = create_web_service_request('/1.0')
         self.resource = TestableHTTPResource(None, self.request)
 
@@ -222,6 +238,7 @@
     def setUp(self):
         self.config = TestWebServiceConfiguration()
         provideUtility(self.config, IWebServiceConfiguration)
+        provideAdapter(CaveatChecker)
         self.request = create_web_service_request('/1.0')
         self.resource = TestableHTTPResource(None, self.request)
 

=== modified file 'src/lazr/restful/tests/test_webservice.py'
--- src/lazr/restful/tests/test_webservice.py	2016-02-17 01:07:21 +0000
+++ src/lazr/restful/tests/test_webservice.py	2016-03-02 13:25:07 +0000
@@ -60,9 +60,11 @@
 from lazr.restful.testing.webservice import (
     create_web_service_request,
     DummyAbsoluteURL,
+    FakeRequest,
     IGenericCollection,
     IGenericEntry,
     simple_renderer,
+    TestCaseWithWebServiceFixtures,
     WebServiceTestCase,
     )
 from lazr.restful.testing.tales import test_tales
@@ -111,7 +113,7 @@
         return "wibble"
 
 
-class ResourceOperationTestCase(unittest.TestCase):
+class ResourceOperationTestCase(TestCaseWithWebServiceFixtures):
     """A test case for resource operations."""
 
     def test_object_with_getitem_should_not_batch(self):
@@ -124,7 +126,7 @@
         return_type = Reference(IHas_getitem)
         result = Has_getitem()
 
-        operation = ResourceGETOperation("fake context", "fake request")
+        operation = ResourceGETOperation("fake context", FakeRequest())
         operation.return_type = return_type
 
         self.assertFalse(