A policy is the TiddlyWeb concept for controlling access to resources on the system. That is: it is the mechanism by which authorization is managed. Policies are both powerful and flexible, and as a result can initially be a bit daunting.

There are policies associated with each bag and each recipe. Each policy has a list of constraints and a list of arguments to the constraint. It also has an owner key and value (string), representing the person who most recently modified the policy.

The policy constraint arguments are either user identification strings (such as a username or OpenID), or roles prepended by R:.

Policies are checked throughout the code, primarily in the web handlers. The current user and their roles (in the form of tiddlyweb.usersign are compared against the constraint being queried. If the constraint is not passed the system raises a permissions error which is usually returned to the user as an HTTP error.

If a policy requires a user, but the current user is GUEST, TiddlyWeb will attempt to call the challenger system to get a user.

Policies are edited by editing the recipe or bag to which they are associated. See the API and twanager.

Processing Model

Policies are engaged in six different scenarios:

1. Listing recipes: /recipes.
2. Listing bags: /bags.
3. Requesting an existing recipe: /recipes/{recipe_name}.
4. Requesting an existing bag: /bags/{bag_name}.
5. Requesting all or one of the tiddlers produced by a recipe: /recipes/{recipe_name}/tiddlers.
6. Requesting all or one of the tiddlers produced by a bag: /bags/{bag_name}/tiddlers.

For a bag or recipe to be included in a list, the current user must pass the read constraint on the entity.

To view or edit an existing bag, the current user must pass the manage constraint.

To view an existing recipe, the current must pass the read constraint. To edit, the manage constraint is checked.

delete, read, write and create are used in the "obvious" fashion when addressing tiddlers in a bag.

When editing a tiddler via a recipe URL, the policy on the bag of its eventual destination is checked for write, create or accept. The policy on the recipe does not control edits of tiddlers.

When reading a tiddler via a recipe URL, the current user must have read on the recipe policy and read in the policy of the bag in which the tiddler is located. In fact the user must have read in the policies of all bags used in the recipes. This is because a recipe must be read to determine which bags are being used in the recipe, and then the bags must be read to find the "right" tiddler.

Conceptually, the policy on a recipe is specifically for controlling reading and managing the recipe itself, whereas the policy on a bag does the job of controlling management of the bag's policy and reading and editing (including deleting) of the tiddlers. For another perspective on this distinction see this google group message.

When creating a recipe or bag, the recipe_create_policy and bag_create_policy config items are checked, respectively.

A policy constraint can contain combinations of three different types of entries:

• A string representing a username or usersign. The term usersign is used because what indicates a user is entirely up to the challenger and credentials extractor system or systems being used.
• A string representing a role. A role is indicated by prepending the role name with R:. By convention roles are uppercased.
• A string representing one of these built in meanings:
  • GUEST: The default unauthenticated user.
  • NONE: No user, whether GUEST or authenticated, may pass this constraint. Web access is completely restricted for this constraint.
  • ANY: Any authenticated (not GUEST) user.

When using ANY or NONE that must be the only value in the list associated with a constraint.