# Access Evaluations semantics proposal

First draft: Dec 17 2024

## Motivation

In the latest [AuthZEN draft](https://openid.github.io/authzen/authorization-api-1_0_02.html), we have defined a payload format for sending multiple evaluation requests to an AuthZEN PDP using the `evaluations` API.

The implied semantics are "execute all of the requests and return all of the results". This is perhaps the most common use-case, but there are at least three use-cases:

1. *Execute all of the requests (potentially in parallel), return all of the results.* Any failure can be denoted by `decision: false` and provide a reason code in the context.
2. *Deny on first denial (or failure).* This semantic could be desired if a PEP wants to issue a few requests in a particular order, with any denial (error, or `decision: false`) "short-circuiting" the evaluations call and returning on the first denial. This essentially works like the `&&` operator.
3. *Permit on first permit.* This is the converse "short-circuiting" semantic, working like the `||` operator.

## Proposal

Add a flag in the `context` field that denotes what semantics the caller (PEP) is asking for:

`evaluations_semantic`: one of the following values:
* `execute_all`
* `deny_on_first_deny`
* `permit_on_first_permit`

`execute_all` is the default semantic, so an existing `evaluations` request (without the `context.evaluations_semantic` flag) can be submitted which honors this semantic.

## Example: Evaluate `read` action for three documents

### Execute all

#### Request

{
  "subject": {
    "type": "user",
    "id": "[e-mail]"
  },
  "action": {
    "name": "read"
  },
  // this could be omitted altogether since the default semantic is "execute_all"
  "options": {
    "evaluations_semantic": "execute_all"
  },
  "evaluations": [
    {
      "resource": {
        "type": "document",
        "id": "1"
      }
    },
    {
      "resource": {
        "type": "document",
        "id": "2"
      }
    },
    {
      "resource": {
        "type": "document",
        "id": "3"
      }
    }
  ]
}

#### Response

{
  "evaluations": [
    {
      decision: true
    },
    {
      decision: false
    },
    {
      decision: true
    }
  ]
}

### Deny on first deny

#### Request

{
  "subject": {
    "type": "user",
    "id": "[e-mail]"
  },
  "action": {
    "name": "read"
  },
  "options": {
    "evaluations_semantic": "deny_on_first_deny"
  },
  "evaluations": [
    {
      "resource": {
        "type": "document",
        "id": "1"
      }
    },
    {
      "resource": {
        "type": "document",
        "id": "2"
      }
    },
    {
      "resource": {
        "type": "document",
        "id": "3"
      }
    }
  ]
}

#### Response

{
  "evaluations": [
    {
      decision: true
    },
    {
      decision: false,
      // below is optional?
      context: {
        "id": "200",
        "reason": "deny_on_first_deny"
      }
    }
  ]
}

### Permit on first permit

#### Request

{
  "subject": {
    "type": "user",
    "id": "[e-mail]"
  },
  "action": {
    "name": "read"
  },
  "options": {
    "evaluations_semantic": "permit_on_first_permit"
  },
  "context": {
  }
  "evaluations": [
    {
      "resource": {
        "type": "document",
        "id": "1"
      },
      "context": {
      }
    },
    {
      "resource": {
        "type": "document",
        "id": "2"
      }
    },
    {
      "resource": {
        "type": "document",
        "id": "3"
      }
    }
  ]
}

#### Response

{
  "evaluations": [
    {
      decision: true
      // below is optional?
      context: {
        "id": "200",
        "reason": "permit_on_first_permit"
      }
    }
  ]
}