policy API musings

[thomas-fossati]

Related to #42

Assumptions:

• all policies exist in perpetuity
• each policy is associated with a unique version (*)
• at most one policy per scheme is active at any point in time
• the tenant is obtained via the API authn mechanism (cookie, client cert, token, ...)

(*) a uuid - or other id with sufficient entropy (e.g., commit hash) is probably better than a sequence number

Add new policy

The tenant adds a new policy for the given scheme.

The supported policy type is OPA and the file format is rego.

On success, the new policy object is returned alongside its unique URI.

A new policy is inactive. Uploading a policy and activating it are two separate operations.

Request

POST /policy/v1/<SCHEME> HTTP/1.1
Content-Type: application/vnd.veraison.policy.opa

[ rego-file ]

Response

HTTP/1.1 201 Created
Content-Type: application/vnd.veraison.policy+json
Location: /policy/v1/<SCHEME>/<version>

{
  "type": "opa",
  "value": "URL-encode(rego-file)",
  "version": "<version>",
  "active": false,
  "ctime": "2023-07-04 00:00:00"
}

Retrieve a policy object

Obtain a given policy object by URI.

Request

GET /policy/v1/<SCHEME>/<version> HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.veraison.policy+json

{
  "type": "opa",
  "value": "URL-encode(rego-file)",
  "version": "<version>",
  "active": false,
  "ctime": "2023-07-04 00:00:00"
}

Retrieve all policy objects for a scheme

Obtain all policy objects associated with a scheme.

Request

GET /policy/v1/<SCHEME> HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.veraison.policy+json

[
  {
    "type": "opa",
    "value": "URL-encode(rego-file)",
    "version": 1,
    "active": false,
    "ctime": "2023-07-04 00:00:00"
  },
  {
    "type": "opa",
    "value": "URL-encode(rego-file)",
    "version": 0,
    "active": true,
    "ctime": "2023-07-03 00:00:00"
  }
]

Activate a policy

Set a given policy to become the active one. This operation atomically deactivates any previously active policy.

Request

POST /policy/v1/<SCHEME>/<version>/activate HTTP/1.1

Response

HTTP/1.1 200 OK

Deactivate all policies

Request

POST /policy/v1/<SCHEME>/deactivate HTTP/1.1

Response

HTTP/1.1 200 OK