Parcel Documentation

# Grants Language Specification

This file contains the reference and examples for the grants domain-specific language (DSL).

# Overview

The grants DSL is used to describe the access context under which a Parcel app or identity may access a document. It is designed with the attribute-based access control (opens new window) (ABAC) paradigm in mind.

A condition in Parcel is a JSON object written using the grants DSL specification. Whenever a data access attempt occurs, Parcel checks if the access context satisfies the condition before releasing keys to the requester.

# Specification

When writing a condition, the grants DSL supports two types of keys: selectors and logical operators. We define a clause as a JSON object with either a selector or logical operator as its single key, along with the associated value.

The associated value must be either a relational operation, set operation, or array operation. Relational operations are used to constrain single-valued access context attributes, while set and array operations are used to constrain set or array-valued access context attributes, respectively.

Both relational operations and array operations are specified as JSON objects with a single key representing the operator and the corresponding value representing the operand. The operand for relational operations will be a standard primitive data type or array. For array operations, the operand will be a relational operation.

For example, in the following clause:

{ 'document.id': { $eq: 'DSgUhs1oiQ8vr5pQH8pgfgs' } }

'document.id' is a selector and { $eq: 'DSgUhs1oiQ8vr5pQH8pgfgs' } is a relational operation with $eq as the operator and 'DSgUhs1oiQ8vr5pQH8pgfgs' as the operand.

Clauses can be nested, and every condition must itself be a clause.

# Relational Operators

The grants DSL supports the following relational operators:

  • $eq - Checks if the specified operand is equal to the corresponding access context attribute. The operand must be a primitive type.
  • $ne - Checks if the specified operand is not equal to the corresponding access context attribute. The operand must be a primitive type.
  • $gte - Checks if the specified operand is greater than or equal to the corresponding access context attribute. The operand must be a primitive type.
  • $gt - Checks if the specified operand is strictly greater than the corresponding access context attribute. The operand must be a primitive type.
  • $lte - Checks if the specified operand is less than or equal to the corresponding access context attribute. The operand must be a primitive type.
  • $lt - Checks if the specified operand is strictly less than the corresponding access context attribute. The operand must be a primitive type.
  • $in - Checks if the corresponding access context attribute is a member of the provided operand. The operand must be an array type.
  • $nin - Checks if the corresponding access context attribute is not a member of the provided operand. The operand must be an array type.

These can be used to construct relational operations such as { $eq: 'oasislabs/acme-derma-demo' } as we saw in the Using Custom Compute Images chapter.

# Array Operators

The grants DSL supports the following array operators:

  • $any - Checks if the specified operand is satisfied by any of the values in the corresponding access context attribute. The operand must be a relational operator.
  • $all - Checks if the specified operand is satisfied by all of the values in the corresponding access context attribute. The operand must be a relational operator.
  • $size - Checks if the specified operand is satisfied by the length of the values in the corresponding access context attribute. The operand must be a relational operator.

# Set Operators

The grants DSL supports the following set operators:

  • $contains - Checks if the set contains the specified primitive element.
  • $intersects - Checks if the intersection of the set and the provided set is nonempty.
  • $superset - Checks if the selected set contains all elements in the provided set.
  • $subset - Checks if the selected set contains only elements in the provided set.
  • $values - Recursively matches using the provided array operator on the set's values.
  • $size - Checks if the specified operand is satisfied by the length of the values in the corresponding access context attribute. The operand must be a relational operator.

These can be used to construct set operations such as { 'contains': 'for-sharing' }.

# Selectors

By now, you should have a good handle on how to specify the value for a clause with relational and array operations. These are sufficient for specifying how to operate on access context attributes when evaluating a condition.

Now let's talk about the key for a clause, which is used for specifying what access context attributes to operate on. Selectors are the basic unit of determining this contextual what.

The grants DSL supports the following selectors, which have been categorized below as per standard ABAC attribute categorization:

# Subject Selectors

  • identity.id - Selects the Parcel ID of the identity requesting access.

# Action Selectors

  • job.spec.image - Selects the job image (and image digest) that a Parcel worker will execute when using the requested input documents.
  • job.spec.inputs - Selects the input document filepaths for the requested job.
  • job.spec.outputs - Selects the output document filepaths for the requested job.
  • accessTime - Selects the ISO 8601 time of document access.

# Object Selectors

  • document.id - Selects the ID of the requested document.
  • document.creator - Selects the identity ID of the document's creator.
  • document.owner - Selects the identity ID of the document's owner.
  • document.title - Selects the (creator-specified) title of the document.
  • document.tags - Selects the (creator-specified) array of metadata tags for the requested document.
  • database.id - Selects the ID of the requested database.
  • database.creator - Selects the identity ID of the database's creator.
  • database.owner - Selects the identity ID of the database's owner.
  • database.name - Selects the (creator-specified) name of the database.

# Environment Selectors

The grants DSL does not yet support any environmental selectors. In the future, support for constraining attributes of Parcel workers permissioned to execute compute jobs will be added here.

# Logical Operators

Logical operators are the second type of key that can be specified when writing a clause, and operate on child clauses.

The grants DSL supports the following logical operators:

  • $and, which takes a JSON array of clauses as its value. All clauses in this array must be satisfied for the $and clause as a whole to be satisfied.
  • $or, which takes a JSON array of clauses as its value. Any clause in this array must be satisfied for the $or clause as a whole to be satisfied.
  • $nor, which takes a JSON array of clauses as its value. All clauses in this array must not be satisfied for the $nor clause as a whole to be satisfied.
  • $not which should take a single clause as its value. This single clause should not be satisfied for the $not clause as a whole to be satisfied.

These of course correspond to their natural boolean expression equivalents.

# Examples

Listed below are some common grant conditions written with the grants DSL.

  • Constrain access to a specific job, for a specific input document.
{
  $and: [
    {
      'document.id': {
        $eq: 'DSgUhs1oiQ8vr5pQH8pgfgs',
      },
    },
    {
      'job.spec.image': {
        $eq: 'bash@sha256:137d3e8797d78ab61c3bc4d599ff34dc7fcfbfca4a031c49ca83efed6792ab15',
      },
    },
  ],
}

where the operand is specified by including both the image name (bash) and the image digest sha256:137d3e8797d78ab61c3bc4d599ff34dc7fcfbfca4a031c49ca83efed6792ab15.

  • Constrain access to one of a few specific titled documents.
{
  'document.title': {
    $in: [ 'document-1', 'document-2', 'document-3' ],
  },
}
  • Constrain access to documents that have been tagged with a specific identifier.
{
  'document.tags': {
    $contains: 'for-sharing',
  },
}
  • Constrain access to documents within a specific time window.
{
  $and: [
    { 'accessTime': { $gte: '2021-01-01' } },
    { 'accessTime': { $lt: '2021-01-05' } },
  ],
}

←