[daisy] New feature: finegrained/partial read access

[Bruno Dumon]

Hi,

I have been developing a new feature: finegrained (or partial) read
access to documents. People who follow the commit list probably guessed
this from my commits to the branch BRANCH_FINEGRAINED_READ_ACCESS.

I'm still working on it, I plan to merge it into trunk later this week
or early next week (this will not be included in 2.1 of course).

The immediate use case we had for this is that users should be able to
see that documents exist, without being able to read their full content.

What follows is a description of what has been done. Feedback/criticism
welcome.

ACL model
---------
The ACL model has been extended so that so-called "access details" can
be specified when granting the read permission.

The access details can currently specify the following things:

 - can all fields be read (boolean), if not, listing allowed fields
   is possible. The inverse, specifying that everything can be read
   except for certain fields, is currently not supported. The
   allowed fields are simply listed by their name (also internally),
   there are no referential integrity checks to validate the fields
   exist (nothing breaks if they don't exist).

 - same for parts

 - can the fulltext index be read. If not, if this document turns up
   in a query with a fulltext clause, it will be removed. This also
   makes the fulltext context extracts inaccessible.

 - can the document summary be read

 - can non-live versions be read. This property replaces the earlier
   'read live' access permission. So the 'read live' permisson no
   longer exists (see also the compatibility notes further on).

ACL evaluation
---------------
When evaluating the ACL, grant-read rules which appear later overwrite
the earlier result, that is, the access details of the last matching
grant-read rule will be used (there is no merging of the access details
here).

When the user has multiple active roles, the ACL results of these roles
are combined, allowing the most liberal/permissive (this was already the
case). For the read access details, a combined access details will be
created with the most permissive configuration.

In order to have write access to a document, one should have full read
access. Having something like partial write access is not part of this
effort, since this comes with its own set of issues that need to be
addressed.

Queries
-------
If the where-clause of the query contains fields which can't be read for
certain documents in the result set, those documents will be removed
from the result set. This is similar to the behaviour for the
dereference operator. So allthough a query might evaluate to true
regardless of whether those fields can be read (e.g. "true or $field =
'foo'), the document will still be removed from the result set. This is
because the SQL query engine doesn't know about the access rules, and
the filtering is done afterwards in Java code.

As mentioned above, documents for which the fulltext index is not
readable will be removed if a fulltext condition is present in the where
clause.

API behaviour
-------------
Fields and parts to which one has no access basically behave as if they
are not present in the document, e.g. the hasField/Part methods will
return false.

If the summary is not readable, the Document.getSummary() method returns
null.

Document wrapping
-----------------
(this is for people interested in implementation details)

In the repository server, when a document is retrieved, it is wrapped in
a DocumentAccessWrapper which will block/filter certain things based on
the access details. Version objects retrieved from these wrapped
documents are also wrapped, in a VersionAccessWrapper. This wrapping is
especially necessary for document objects retrieved from the cache (for
non-cached document copies we could leave out the data when loading the
documents).

The fields/parts to which one has no read access will not be present in
the document/version's XML representation, so they automatically won't
be visible in the remote API implementation either.

Admin GUI
---------
The administration GUI has been extended to allow editing the access
details. Next to the grant-read flag, there's now a button that opens a
dialog to edit the details. The button is shown greyed-out when there
are no details.

Access information annotations
------------------------------
Query result set rows, the link annotations made by the publisher
(p:linkInfo), and the nodes in navigation trees are now annotated with
information about the access permissions the user has on the linked-to
document. This allows to e.g. render a lock icon next to the links if
the user only has partial read access.

Here are some sample annotations:

- when having full access:
   access="read,fullRead,write,delete,publish"

- only able to read live version:
   access="read,liveOnly"

- no full read access:
   access="read,restrictedRead"

- no full read access and no live:
   access="read,liveOnly,restrictedRead"

So this basically is a comma separated list of permissions. For the read
permission, there is always some extra information. When the access
details are non-empty, "restrictedRead" will be added, otherwise
"fullRead". One exception is if the access details specify that non-live
content cannot be read, in which case "liveOnly" will be added too.

With a case-sensitive 'contains' test, it can be easily checked what
permissions the user has (e.g. in XSLT).

Backwards compatibility
-----------------------
The removal of the 'read-live' permisson brings some backwards
incompatibilities with it:

  - API changes and XML formats: programs explicitely working with the
read-live permission will need to be adjusted

  - automaticall upgrading the database from read-live permissions to
read-with-access-details is difficult/impossible. Currently, rules which
contain "grant read live, deny read" are converted to read with access
details, the rest is left untouched. So situations like this won't be
correctly upgraded:
            Read-live       Read
            grant           grant
            don't change    deny

There was also an incompatible change done in the ACL XML format, which
I'll document in the upgrade notes.

                                 - o -

That's all I think. Thanks for reading/scrolling to the end!

-- 
Bruno Dumon                             http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
bruno at outerthought.org                          bruno at apache.org