Policy backend API spec (#2607)

codegen/configs/policy_client_v1.yaml

@@ -0,0 +1,11 @@
+package: client
+generate:
+  echo-server: false
+  client: true
+  models: true
+  strict-server: true
+output-options:
+  skip-prune: true
+  exclude-schemas:
+  - PresentationDefinition
+  - PresentationSubmission

docs/_static/policy/v1.yaml

@@ -0,0 +1,134 @@
+openapi: 3.1.0
+info:
+  title: Policy backend API specification
+  version: 0.1.0
+servers:
+  - url: "http://localhost:1323"
+paths:
+  /presentation_definition:
+    parameters:
+      - name: authorizer
+        in: query
+        description: URLEncoded DID.
+        required: true
+        example: did:web:example.com:1
+        schema:
+          type: string
+      - name: scope
+        in: query
+        description: |
+          This is the scope used in the OpenID4VP authorization request.
+          It is a space separated list of scopes.
+        required: true
+        schema:
+          type: string
+    get:
+      summary: Returns a presentation definition for the given DID and scope.
+      description: |
+        The DID is used for tenant selection. Not all tenants will probably support the same scopes.
+        The scope is used as selection criteria for the presentation definition.
+        It could be the case that the presentation definition is not found.
+        In that case the response will be 201 with an empty body.
+      operationId: "presentationDefinition"
+      tags:
+        - policy
+      responses:
+        "200":
+          description: |
+            DID has been found and the scope is supported.
+            If the scope is supported but no presentation definition is required, the response will be 200 with a presentation definition without any input descriptors.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PresentationDefinition'
+        "201":
+          description: The DID is known but the presented scope is not supported.
+        "404":
+          description: DID is not known to the policy backend.
+  /authorized:
+    post:
+      summary: Check if a resource request is authorized.
+      description: |
+        When an access token is used to request a resource, the resource server needs to know if the access token grants access to the requested resource.
+        The resource server will send a request to the policy backend to check if the access token grants access to the requested resource.
+        All cryptographic and presentation exchange validations have already been done by the caller.
+      operationId: "checkAuthorized"
+      tags:
+        - policy
+      requestBody:
+        description: Required params for policy backend to make an informed decision.
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AuthorizedRequest'
+      responses:
+        "200":
+          description: A response that indicates if the access token grants access to the requested resource.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AuthorizedResponse'
+        "404":
+          description: DID is not known to the policy backend.
+components:
+  schemas:
+    AuthorizedRequest:
+      description: |
+        The request contains all params involved with the request.
+        It might be the case that the caller mapped credential fields to additional params.
+      type: object
+      required:
+        - audience
+        - client_id
+        - scope
+        - request_url
+        - request_method
+        - presentation_submission
+        - vps
+      properties:
+        audience:
+          description: The audience of the access token. This is the identifier (DID) of the authorizer and issuer of the access token.
+          type: string
+        client_id:
+          description: The client ID of the client that requested the resource (DID).
+          type: string
+        scope:
+          description: The scope used in the authorization request.
+          type: string
+        request_url:
+          description: The URL of the resource request.
+          type: string
+        request_method:
+          description: The method of the resource request.
+          type: string
+        presentation_submission:
+          description: The presentation submission that was used to request the access token.
+          $ref: '#/components/schemas/PresentationSubmission'
+        vps:
+          description: | 
+            The verifiable presentations that were used to request the access token.
+            The verifiable presentations could be in JWT format or in JSON format.
+          type: array
+    AuthorizedResponse:
+      description: |
+        The response indicates if the access token grants access to the requested resource.
+        If the access token grants access, the response will be 200 with a boolean value set to true.
+        If the access token does not grant access, the response will be 200 with a boolean value set to false.
+      type: object
+      required:
+        - authorized
+      properties:
+        authorized:
+          description: Indicates if the access token grants access to the requested resource.
+          type: boolean
+    PresentationDefinition:
+      description: |
+        A presentation definition is a JSON object that describes the desired verifiable credentials and presentation formats.
+        Specified at https://identity.foundation/presentation-exchange/spec/v2.0.0/
+        A JSON schema is available at https://identity.foundation/presentation-exchange/#json-schema
+    PresentationSubmission:
+      description: |
+        A presentation submission is a JSON object that maps requirements from the Presentation Definition to the verifiable presentations that were used to request an access token.
+        Specified at https://identity.foundation/presentation-exchange/spec/v2.0.0/
+        A JSON schema is available at https://identity.foundation/presentation-exchange/#json-schema

makefile

@@ -68,6 +68,7 @@ gen-api:
 	oapi-codegen --config codegen/configs/auth_iam.yaml docs/_static/auth/iam.yaml | gofmt > auth/api/iam/generated.go
 	oapi-codegen --config codegen/configs/didman_v1.yaml docs/_static/didman/v1.yaml | gofmt > didman/api/v1/generated.go
 	oapi-codegen --config codegen/configs/crypto_store_client.yaml https://raw.githubusercontent.com/nuts-foundation/secret-store-api/main/nuts-storage-api-v1.yaml | gofmt > crypto/storage/external/generated.go
+	oapi-codegen --config codegen/configs/policy_client_v1.yaml docs/_static/policy/v1.yaml | gofmt > policy/api/v1/client/generated.go
 
 gen-protobuf:
 	protoc --go_out=paths=source_relative:network -I network network/transport/v2/protocol.proto

policy/api/v1/client/client.go

@@ -0,0 +1,110 @@
+/*
+ * Copyright (C) 2023 Nuts community
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ */
+
+package client
+
+import (
+	"context"
+	"crypto/tls"
+	"fmt"
+	"github.com/nuts-foundation/go-did/did"
+	"net/http"
+	"time"
+
+	"github.com/nuts-foundation/nuts-node/core"
+	"github.com/nuts-foundation/nuts-node/vcr/pe"
+)
+
+// HTTPClient holds the server address and other basic settings for the http client
+type HTTPClient struct {
+	strictMode bool
+	httpClient core.HTTPRequestDoer
+}
+
+// NewHTTPClient creates a new api client.
+func NewHTTPClient(strictMode bool, timeout time.Duration, tlsConfig *tls.Config) HTTPClient {
+	return HTTPClient{
+		strictMode: strictMode,
+		httpClient: core.NewStrictHTTPClient(strictMode, timeout, tlsConfig),
+	}
+}
+
+// PresentationDefinition retrieves the presentation definition from the presentation definition endpoint for the given scope and authorizer.
+func (hb HTTPClient) PresentationDefinition(ctx context.Context, serverAddress string, authorizer did.DID, scopes string) (*pe.PresentationDefinition, error) {
+	_, err := core.ParsePublicURL(serverAddress, hb.strictMode)
+	if err != nil {
+		return nil, err
+	}
+
+	client, err := NewClient(serverAddress, WithHTTPClient(hb.httpClient))
+	if err != nil {
+		return nil, err
+	}
+	params := &PresentationDefinitionParams{
+		Scope:      scopes,
+		Authorizer: authorizer.String(),
+	}
+	response, err := client.PresentationDefinition(ctx, params)
+	if err != nil {
+		return nil, fmt.Errorf("failed to call endpoint: %w", err)
+	}
+	if httpErr := core.TestResponseCode(http.StatusOK, response); httpErr != nil {
+		return nil, httpErr
+	}
+
+	presentationDefinitionResponse, err := ParsePresentationDefinitionResponse(response)
+	if err != nil {
+		return nil, fmt.Errorf("unable to unmarshal response: %w", err)
+	}
+
+	return presentationDefinitionResponse.JSON200, nil
+}
+
+// Authorized checks if the given request is authorized by the policy backend.
+// The AuthorizedRequest contains the information that is needed to check if the request is authorized.
+func (hb HTTPClient) Authorized(ctx context.Context, serverAddress string, request AuthorizedRequest) (bool, error) {
+	_, err := core.ParsePublicURL(serverAddress, hb.strictMode)
+	if err != nil {
+		return false, err
+	}
+
+	client, err := NewClient(serverAddress, WithHTTPClient(hb.httpClient))
+	if err != nil {
+		return false, err
+	}
+
+	response, err := client.CheckAuthorized(ctx, request)
+	if err != nil {
+		return false, fmt.Errorf("failed to call endpoint: %w", err)
+	}
+	if httpErr := core.TestResponseCode(http.StatusOK, response); httpErr != nil {
+		return false, httpErr
+	}
+
+	authorizedResponse, err := ParseCheckAuthorizedResponse(response)
+	if err != nil {
+		return false, fmt.Errorf("unable to unmarshal response: %w", err)
+	}
+
+	// theoretically, the JSON200 field could be nil. The API should always return a response, so we return it as error.
+	if authorizedResponse.JSON200 == nil {
+		return false, fmt.Errorf("response is nil")
+	}
+
+	return authorizedResponse.JSON200.Authorized, nil
+}