Merge pull request #2294 from usingtechnology/issue-1652-goal-code

Add Goal and Goal Code to OOB and DIDex Request

Author: dbluhm

Diff for: aries_cloudagent/protocols/didexchange/v1_0/manager.py

@@ -183,6 +183,8 @@ async def create_request_implicit(
         mediation_id: str = None,
         use_public_did: bool = False,
         alias: str = None,
+        goal_code: str = None,
+        goal: str = None,
     ) -> ConnRecord:
         """
         Create and send a request against a public DID only (no explicit invitation).
@@ -193,6 +195,8 @@ async def create_request_implicit(
             my_endpoint: my endpoint
             mediation_id: record id for mediation with routing_keys, service endpoint
             use_public_did: use my public DID for this connection
+            goal_code: Optional self-attested code for sharing intent of connection
+            goal: Optional self-attested string for sharing intent of connection
 
         Returns:
             The new `ConnRecord` instance
@@ -225,6 +229,8 @@ async def create_request_implicit(
             my_label=my_label,
             my_endpoint=my_endpoint,
             mediation_id=mediation_id,
+            goal_code=goal_code,
+            goal=goal,
         )
         conn_rec.request_id = request._id
         conn_rec.state = ConnRecord.State.REQUEST.rfc23
@@ -242,6 +248,8 @@ async def create_request(
         my_label: str = None,
         my_endpoint: str = None,
         mediation_id: str = None,
+        goal_code: str = None,
+        goal: str = None,
     ) -> DIDXRequest:
         """
         Create a new connection request for a previously-received invitation.
@@ -252,7 +260,8 @@ async def create_request(
             my_endpoint: My endpoint
             mediation_id: The record id for mediation that contains routing_keys and
                 service endpoint
-
+            goal_code: Optional self-attested code for sharing intent of connection
+            goal: Optional self-attested string for sharing intent of connection
         Returns:
             A new `DIDXRequest` message to send to the other agent
 
@@ -327,6 +336,8 @@ async def create_request(
             label=my_label,
             did=conn_rec.my_did,
             did_doc_attach=attach,
+            goal_code=goal_code,
+            goal=goal,
         )
         request.assign_thread_id(thid=request._id, pthid=pthid)
 

Diff for: aries_cloudagent/protocols/didexchange/v1_0/messages/request.py

@@ -30,6 +30,8 @@ def __init__(
         label: str = None,
         did: str = None,
         did_doc_attach: AttachDecorator = None,
+        goal_code: str = None,
+        goal: str = None,
         **kwargs,
     ):
         """
@@ -39,11 +41,20 @@ def __init__(
             label: Label for this request
             did: DID for this request
             did_doc_attach: signed DID doc attachment
+            goal_code: (optional) is a self-attested code the receiver may want to
+              display to the user or use in automatically deciding what to do with
+              the request message. The goal code might be used particularly when the
+              request is sent to a resolvable DID without reference to a specfic
+              invitation.
+            goal: (optional) is a self-attested string that the receiver may want to
+              display to the user about the context-specific goal of the request message.
         """
         super().__init__(**kwargs)
         self.label = label
         self.did = did
         self.did_doc_attach = did_doc_attach
+        self.goal_code = goal_code
+        self.goal = goal
 
 
 class DIDXRequestSchema(AgentMessageSchema):
@@ -67,3 +78,15 @@ class Meta:
         description="As signed attachment, DID Doc associated with DID",
         data_key="did_doc~attach",
     )
+    goal_code = fields.Str(
+        required=False,
+        description="A self-attested code the receiver may want to display to the user "
+        "or use in automatically deciding what to do with the out-of-band message",
+        example="issue-vc",
+    )
+    goal = fields.Str(
+        required=False,
+        description="A self-attested string that the receiver may want to display to the "
+        "user about the context-specific goal of the out-of-band message",
+        example="To issue a Faber College Graduate credential",
+    )

Diff for: aries_cloudagent/protocols/didexchange/v1_0/messages/tests/test_request.py

@@ -18,6 +18,8 @@ class TestConfig:
     test_verkey = "3Dn1SJNPaCXcvvJvSbsFWP2xaCjMom3can8CQNhWrTRx"
     test_label = "Label"
     test_endpoint = "http://localhost"
+    goal_code = "pytest"
+    goal = "pass pytest"
 
     def make_did_doc(self):
         doc = DIDDoc(did=self.test_did)
@@ -64,12 +66,16 @@ async def setUp(self):
             label=TestConfig.test_label,
             did=TestConfig.test_did,
             did_doc_attach=did_doc_attach,
+            goal_code=TestConfig.goal_code,
+            goal=TestConfig.goal,
         )
 
     def test_init(self):
         """Test initialization."""
         assert self.request.label == TestConfig.test_label
         assert self.request.did == TestConfig.test_did
+        assert self.request.goal_code == TestConfig.goal_code
+        assert self.request.goal == TestConfig.goal
 
     def test_type(self):
         """Test type."""
@@ -123,6 +129,8 @@ async def setUp(self):
             label=TestConfig.test_label,
             did=TestConfig.test_did,
             did_doc_attach=did_doc_attach,
+            goal_code="pytest",
+            goal="pass pytest",
         )
 
     async def test_make_model(self):

Diff for: aries_cloudagent/protocols/didexchange/v1_0/routes.py

@@ -62,6 +62,18 @@ class DIDXCreateRequestImplicitQueryStringSchema(OpenAPISchema):
         required=False,
         description="Use public DID for this connection",
     )
+    goal_code = fields.Str(
+        required=False,
+        description="A self-attested code the receiver may want to display to the user "
+        "or use in automatically deciding what to do with the out-of-band message",
+        example="issue-vc",
+    )
+    goal = fields.Str(
+        required=False,
+        description="A self-attested string that the receiver may want to display to the "
+        "user about the context-specific goal of the out-of-band message",
+        example="To issue a Faber College Graduate credential",
+    )
 
 
 class DIDXReceiveRequestImplicitQueryStringSchema(OpenAPISchema):
@@ -190,6 +202,8 @@ async def didx_create_request_implicit(request: web.BaseRequest):
     mediation_id = request.query.get("mediation_id") or None
     alias = request.query.get("alias") or None
     use_public_did = json.loads(request.query.get("use_public_did", "null"))
+    goal_code = request.query.get("goal_code") or None
+    goal = request.query.get("goal") or None
 
     profile = context.profile
     didx_mgr = DIDXManager(profile)
@@ -201,6 +215,8 @@ async def didx_create_request_implicit(request: web.BaseRequest):
             mediation_id=mediation_id,
             use_public_did=use_public_did,
             alias=alias,
+            goal_code=goal_code,
+            goal=goal,
         )
     except StorageNotFoundError as err:
         raise web.HTTPNotFound(reason=err.roll_up) from err

Diff for: aries_cloudagent/protocols/out_of_band/v1_0/manager.py

@@ -90,6 +90,8 @@ async def create_invitation(
         mediation_id: str = None,
         service_accept: Optional[Sequence[Text]] = None,
         protocol_version: Optional[Text] = None,
+        goal_code: Optional[Text] = None,
+        goal: Optional[Text] = None,
     ) -> InvitationRecord:
         """
         Generate new connection invitation.
@@ -111,7 +113,8 @@ async def create_invitation(
             service_accept: Optional list of mime types in the order of preference of
             the sender that the receiver can use in responding to the message
             protocol_version: OOB protocol version [1.0, 1.1]
-
+            goal_code: Optional self-attested code for receiver logic
+            goal: Optional self-attested string for receiver logic
         Returns:
             Invitation record
 
@@ -355,6 +358,9 @@ async def create_invitation(
                 )
             ]
             invi_url = invi_msg.to_url()
+            if goal and goal_code:
+                invi_msg.goal_code = goal_code
+                invi_msg.goal = goal
 
             # Update connection record
             if conn_rec:

Diff for: aries_cloudagent/protocols/out_of_band/v1_0/messages/invitation.py

@@ -131,6 +131,8 @@ def __init__(
         accept: Optional[Sequence[Text]] = None,
         version: str = DEFAULT_VERSION,
         msg_type: Optional[Text] = None,
+        goal_code: Optional[Text] = None,
+        goal: Optional[Text] = None,
         **kwargs,
     ):
         """
@@ -150,6 +152,8 @@ def __init__(
         self.requests_attach = list(requests_attach) if requests_attach else []
         self.services = services
         self.accept = accept
+        self.goal_code = goal_code
+        self.goal = goal
 
     @classmethod
     def wrap_message(cls, message: dict) -> AttachDecorator:
@@ -264,6 +268,18 @@ class Meta:
             "did:sov:WgWxqztrNooG92RXvxSTWv",
         ],
     )
+    goal_code = fields.Str(
+        required=False,
+        description="A self-attested code the receiver may want to display to the user "
+        "or use in automatically deciding what to do with the out-of-band message",
+        example="issue-vc",
+    )
+    goal = fields.Str(
+        required=False,
+        description="A self-attested string that the receiver may want to display to the "
+        "user about the context-specific goal of the out-of-band message",
+        example="To issue a Faber College Graduate credential",
+    )
 
     @validates_schema
     def validate_fields(self, data, **kwargs):
@@ -288,6 +304,12 @@ def validate_fields(self, data, **kwargs):
         #     raise ValidationError(
         #         "Model must include non-empty services array"
         #     )
+        goal = data.get("goal")
+        goal_code = data.get("goal_code")
+        if goal and not goal_code:
+            raise ValidationError("Model cannot have goal without goal_code")
+        if goal_code and not goal:
+            raise ValidationError("Model cannot have goal_code without goal")
 
     @post_dump
     def post_dump(self, data, **kwargs):

Diff for: aries_cloudagent/protocols/out_of_band/v1_0/messages/tests/test_invitation.py

@@ -153,3 +153,88 @@ def test_assign_msg_type_version_to_model_inst(self):
         assert "1.0" in test_req._type
         assert "1.2" in test_msg._type
         assert "1.1" in InvitationMessage.Meta.message_type
+
+    def test_goal_and_code_model(self):
+        test_msg = InvitationMessage()
+        assert test_msg.goal is None
+        assert test_msg.goal_code is None
+        test_msg = InvitationMessage(goal="pass test", goal_code="pytest.pass")
+        assert test_msg.goal == "pass test"
+        assert test_msg.goal_code == "pytest.pass"
+
+    def test_mutual_inclusive_goal_and_goal_code(self):
+        msg = {"aries": "message"}
+        deco = InvitationMessage.wrap_message(msg)
+
+        # populate both goal and goal_code - good
+        obj_x = {
+            "label": "label",
+            "requests~attach": [deco.serialize()],
+            "goal_code": "pytest.pass",
+            "goal": "pass test",
+        }
+
+        errs = InvitationMessageSchema().validate(obj_x)
+        assert errs == {}
+
+        # do not include goal and goal_code - good
+        obj_x = {
+            "label": "label",
+            "requests~attach": [deco.serialize()],
+        }
+
+        errs = InvitationMessageSchema().validate(obj_x)
+        assert errs == {}
+
+        # no value for both goal and goal_code - good
+        obj_x = {
+            "label": "label",
+            "requests~attach": [deco.serialize()],
+            "goal_code": "",
+            "goal": "",
+        }
+
+        errs = InvitationMessageSchema().validate(obj_x)
+        assert errs == {}
+
+        errs = InvitationMessageSchema().validate(obj_x)
+        assert errs == {}
+
+        # populate only goal - bad
+        obj_x = {
+            "label": "label",
+            "requests~attach": [deco.serialize()],
+            "goal": "pass test",
+        }
+
+        errs = InvitationMessageSchema().validate(obj_x)
+        assert errs and len(errs)
+        assert errs and errs["_schema"]
+        assert len(errs["_schema"]) == 1
+        assert "goal" in errs["_schema"][0]
+
+        # populate only goal_code - bad
+        obj_x = {
+            "label": "label",
+            "requests~attach": [deco.serialize()],
+            "goal_code": "pytest.pass",
+        }
+
+        errs = InvitationMessageSchema().validate(obj_x)
+        assert errs and len(errs)
+        assert errs and errs["_schema"]
+        assert len(errs["_schema"]) == 1
+        assert "goal_code" in errs["_schema"][0]
+
+        # goal and goal code cannot be set to null/none
+        obj_x = {
+            "label": "label",
+            "requests~attach": [deco.serialize()],
+            "goal_code": None,
+            "goal": None,
+        }
+
+        errs = InvitationMessageSchema().validate(obj_x)
+        assert len(errs) == 2
+        assert errs["goal"]
+        assert errs["goal_code"]

Diff for: aries_cloudagent/protocols/out_of_band/v1_0/routes.py

@@ -116,6 +116,18 @@ class AttachmentDefSchema(OpenAPISchema):
         description="Identifier for active mediation record to be used",
         **UUID4,
     )
+    goal_code = fields.Str(
+        required=False,
+        description="A self-attested code the receiver may want to display to the user "
+        "or use in automatically deciding what to do with the out-of-band message",
+        example="issue-vc",
+    )
+    goal = fields.Str(
+        required=False,
+        description="A self-attested string that the receiver may want to display to the "
+        "user about the context-specific goal of the out-of-band message",
+        example="To issue a Faber College Graduate credential",
+    )
 
 
 class InvitationReceiveQueryStringSchema(OpenAPISchema):
@@ -172,6 +184,8 @@ async def invitation_create(request: web.BaseRequest):
     alias = body.get("alias")
     mediation_id = body.get("mediation_id")
     protocol_version = body.get("protocol_version")
+    goal_code = body.get("goal_code")
+    goal = body.get("goal")
 
     multi_use = json.loads(request.query.get("multi_use", "false"))
     auto_accept = json.loads(request.query.get("auto_accept", "null"))
@@ -193,6 +207,8 @@ async def invitation_create(request: web.BaseRequest):
             mediation_id=mediation_id,
             service_accept=service_accept,
             protocol_version=protocol_version,
+            goal_code=goal_code,
+            goal=goal,
         )
     except (StorageNotFoundError, ValidationError, OutOfBandManagerError) as e:
         raise web.HTTPBadRequest(reason=e.roll_up)

Diff for: aries_cloudagent/protocols/out_of_band/v1_0/tests/test_routes.py

@@ -59,6 +59,8 @@ async def test_invitation_create(self):
                 mediation_id=None,
                 service_accept=None,
                 protocol_version=None,
+                goal_code=None,
+                goal=None,
             )
             mock_json_response.assert_called_once_with({"abc": "123"})
 
@@ -100,6 +102,8 @@ async def test_invitation_create_with_accept(self):
                 mediation_id=None,
                 service_accept=["didcomm/aip1", "didcomm/aip2;env=rfc19"],
                 protocol_version=None,
+                goal_code=None,
+                goal=None,
             )
             mock_json_response.assert_called_once_with({"abc": "123"})