[WIP] feat: json-schema and OAS for authzen 1.0

api/oas/authzen-1.0-openapi.json

@@ -0,0 +1,166 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Authzen HTTP-json",
+    "description": "Authzen HTTP-json specs: https://openid.net/specs/authorization-api-1_0-05.html#name-https-json-binding",
+    "version": "1.0.0"
+  },
+  "servers": [
+  ],
+  "paths": {
+    "/access/v1/evaluation": {
+      "post": {
+        "summary": "Access Evaluation",
+        "description": "The Access Evaluation API defines the message exchange pattern between a PEP and a PDP for executing a single access evaluation. see: https://openid.net/specs/authorization-api-1_0-05.html#name-access-evaluation-api",
+        "operationId": "accessEvaluationEndpoint",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "../schemas/access-evaluation-request.json"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "PDP has successfully generated the decision",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "../schemas/access-evaluation-response.json"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/access/v1/evaluations": {
+      "post": {
+        "summary": "Access Evaluations",
+        "description": "The Access Evaluation API defines the message exchange pattern between a PEP and a PDP for executing a single access evaluation. see: https://openid.net/specs/authorization-api-1_0-05.html#name-access-evaluations-api",
+        "operationId": "accessEvaluationsEndpoint",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "oneOf": [
+                  {
+                    "$ref": "../schemas/access-evaluation-request.json"
+                  },
+                  {
+                    "$ref": "../schemas/access-evaluations-request.json"
+                  }
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "PDP has successfully generated the decision",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "oneOf": [
+                    {
+                      "$ref": "../schemas/access-evaluation-response.json"
+                    },
+                    {
+                      "$ref": "../schemas/access-evaluations-response.json"
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/access/v1/search/subject": {
+      "post": {
+        "summary": "Subject Search",
+        "description": "The Subject Search API returns all subjects of a given type that are permitted according to the provided Action, Resource and Context. see: https://openid.net/specs/authorization-api-1_0-05.html#name-subject-search-api",
+        "operationId": "searchSubjectEndpoint",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "../schemas/search-subject-request.json"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "PDP has successfully process the subject search",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "../schemas/search-subject-response.json"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/access/v1/search/resource": {
+      "post": {
+        "summary": "Resource Search",
+        "description": "The Resource Search API returns all resources of a given type that are permitted according to the provided Action, Subject and Context. see: https://openid.net/specs/authorization-api-1_0-05.html#name-resource-search-api",
+        "operationId": "searchResourceEndpoint",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "../schemas/search-resource-request.json"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "PDP has successfully process the resource search",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "../schemas/search-resource-response.json"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/access/v1/search/action": {
+      "post": {
+        "summary": "Action Search",
+        "description": "The Action Search API returns all actions that are permitted according to the provided Subject, Resource and Context. see: https://openid.net/specs/authorization-api-1_0-05.html#name-action-search-api",
+        "operationId": "searchActionEndpoint",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "../schemas/search-action-request.json"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "PDP has successfully process the action search",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "../schemas/search-action-response.json"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

api/schemas/access-evaluation-request.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "authzen-evaluation-api-request",
+  "title": "Access Evaluation API - Request",
+  "$comment": "https://openid.net/specs/authorization-api-1_0-05.html#section-6.1",
+  "type": "object",
+  "required": [
+    "subject",
+    "resource",
+    "action"
+  ],
+  "properties": {
+    "subject": {
+      "$ref": "./subject-base.json"
+    },
+    "resource": {
+      "description": "The resource of type Resource.",
+      "$ref": "./resource-base.json"
+    },
+    "action": {
+      "description": "The action (or verb) of type Action.",
+      "$ref": "./action-base.json"
+    },
+    "context": {
+      "description": "The context (or environment) of type Context.",
+      "$comment": "https://openid.net/specs/authorization-api-1_0-05.html#name-context",
+      "type": "object",
+      "examples": [
+        {
+          "time": "1985-10-26T01:22-07:00"
+        }
+      ]
+    }
+  },
+  "additionalProperties": false
+}

api/schemas/access-evaluation-response.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "authzen-evaluation-api-response",
+  "title": "Access Evaluation API - Response",
+  "$comment": "https://openid.net/specs/authorization-api-1_0-05.html#name-the-access-evaluation-api-re",
+  "$ref": "./decision-base.json",
+  "additionalProperties": false
+}

api/schemas/access-evaluations-request.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "authzen-evaluations-api-request",
+  "title": "Access Evaluations API - Request",
+  "$comment": "https://openid.net/specs/authorization-api-1_0-05.html#name-the-access-evaluations-api-",
+  "type": "object",
+  "required": [
+    "evaluations"
+  ],
+  "properties": {
+    "subject": {
+      "description": "The subject (or principal) of type Subject to override in `evaluations`.",
+      "$ref": "./subject-base.json",
+      "required": []
+    },
+    "resource": {
+      "description": "The resource of type Resource to override in `evaluations`.",
+      "$ref": "./resource-base.json",
+      "required": []
+    },
+    "action": {
+      "description": "The action (or verb) of type Action to override in `evaluations`.",
+      "$ref": "./action-base.json",
+      "required": []
+    },
+    "evaluations": {
+      "description": "Array which contains a list of objects, each typed as the object as defined in the Access Evaluation Request",
+      "type": "array",
+      "$comment": "how to make sub each not required, maybe keep base schema requirement agnostic and put requirement at each request/response",
+      "items": {
+        "$ref": "./access-evaluation-request.json",
+        "required": []
+      }
+    },
+    "options": {
+      "description": "This provides a general-purpose mechanism for providing PEP-supplied metadata on how the request is to be executed.",
+      "type": "object",
+      "properties": {
+        "evaluations_semantic": {
+          "description": "(`execute_all`|`deny_on_first_deny`|`permit_on_first_permit`)",
+          "type": "string",
+          "$comment": "https://openid.net/specs/authorization-api-1_0-05.html#name-evaluations-semantics"
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": false
+}

api/schemas/access-evaluations-response.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "authzen-evaluations-api-response",
+  "title": "Access Evaluations API - Response",
+  "$comment": "https://openid.net/specs/authorization-api-1_0-05.html#name-the-access-evaluations-api-r",
+  "type": "object",
+  "properties": {
+    "evaluations": {
+      "type": "array",
+      "items": {
+        "$ref": "./decision-base.json"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "examples": [
+    {
+      "evaluations": [
+        {
+          "decision": true
+        }
+      ]
+    },
+    {
+      "evaluations": [
+        {
+          "decision": true
+        },
+        {
+          "decision": false,
+          "context": {
+            "code": "200",
+            "reason": "deny_on_first_deny"
+          }
+        }
+      ]
+    },
+    {
+      "evaluations": [
+        {
+          "decision": true
+        },
+        {
+          "decision": false,
+          "context": {
+            "reason": "resource not found"
+          }
+        },
+        {
+          "decision": false,
+          "context": {
+            "reason": "Subject is a viewer of the resource"
+          }
+        }
+      ]
+    },
+    {
+      "evaluations": [
+        {
+          "decision": true
+        },
+        {
+          "decision": false,
+          "context": {
+            "error": {
+              "status": 404,
+              "message": "Resource not found"
+            }
+          }
+        },
+        {
+          "decision": false,
+          "context": {
+            "reason": "Subject is a viewer of the resource"
+          }
+        }
+      ]
+    }
+  ]
+}

api/schemas/action-base.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "authzen-action-base",
+  "title": "Base model for Authzen action",
+  "$comment": "https://openid.net/specs/authorization-api-1_0-05.html#name-action",
+  "type": "object",
+  "required": [
+    "name"
+  ],
+  "properties": {
+    "name": {
+      "description": "A string value containing the name of the Action.",
+      "type": "string"
+    },
+    "properties": {
+      "description": "An object which can be used to express additional attributes of an Action.",
+      "type": "object",
+      "examples": [
+        {
+          "period": "2W"
+        }
+      ]
+    }
+  }
+}