From 1994384e1bf939ffcbda9a4e224f20b49f65776c Mon Sep 17 00:00:00 2001 From: Magnus Kuhn <127854942+Magnus-Kuhn@users.noreply.github.com> Date: Fri, 15 Nov 2024 12:37:04 +0100 Subject: [PATCH] Personalization of Tokens and RelationshipTemplates (#283) * feat: add personalization * refactor: review comments * refactor: dotting --------- Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com> --- _docs_integrate/data-model-overview.md | 22 +++++++------- _docs_integrate/establish-relationships.md | 16 ++++++++++ ...ansport-create-own-relationshiptemplate.md | 5 ++-- .../use-case-transport-create-own-token.md | 3 +- ...se-case-transport-create-token-for-file.md | 1 + ...eate-token-for-own-relationshiptemplate.md | 7 +++-- ...transport-create-token-qr-code-for-file.md | 3 +- ...en-qr-code-for-own-relationshiptemplate.md | 30 ++++++++++++++++--- ...-relationshiptemplate-created-by-others.md | 3 +- ...-transport-load-token-created-by-others.md | 1 + 10 files changed, 69 insertions(+), 22 deletions(-) diff --git a/_docs_integrate/data-model-overview.md b/_docs_integrate/data-model-overview.md index 025c26623..7f94036c8 100644 --- a/_docs_integrate/data-model-overview.md +++ b/_docs_integrate/data-model-overview.md @@ -51,16 +51,17 @@ Tokens can be used to save arbitrary structured data on the Backbone, which is e A Token has the following properties: -| Name | Type | Description | Remarks | -| ------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | -| id | `string` | {% include descr_id class="Token" prefix="TOK" %} | -| createdBy | `string` | {% include descr_createdBy class="Token" %} | | -| createdByDevice | `string` | {% include descr_createdByDevice class="Token" %} | | -| content | `unknown` | The content of the Token. You can add whatever you want here. | will be encrypted before sent to the Backbone | -| createdAt | `string` | {% include descr_createdAt class="Token" %} | | -| expiresAt | `string` | {% include descr_expiresAt class="Token" %} | | -| truncatedReference | `string` | {% include descr_truncatedReference class="Token" %} | saved only locally | -| isEphemeral | `boolean` | If set to `true` the Token will not be cached in the database and only displayed once. You will not be able to fetch this Token unless you remember its truncatedReference. | +| Name | Type | Description | Remarks | +| ------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | +| id | `string` | {% include descr_id class="Token" prefix="TOK" %} | +| createdBy | `string` | {% include descr_createdBy class="Token" %} | | +| createdByDevice | `string` | {% include descr_createdByDevice class="Token" %} | | +| content | `unknown` | The content of the Token. You can add whatever you want here. | will be encrypted before sent to the Backbone | +| createdAt | `string` | {% include descr_createdAt class="Token" %} | | +| expiresAt | `string` | {% include descr_expiresAt class="Token" %} | | +| forIdentity | `string` | Can be set to an enmeshed address. If set, then only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can retrieve the Token from the Backbone. | +| truncatedReference | `string` | {% include descr_truncatedReference class="Token" %} | saved only locally | +| isEphemeral | `boolean` | If set to `true` the Token will not be cached in the database and only displayed once. You will not be able to fetch this Token unless you remember its truncatedReference. | ## RelationshipTemplate @@ -79,6 +80,7 @@ A RelationshipTemplate serves two purposes: | content | [`RelationshipTemplateContent`](#relationshiptemplatecontent) \| [`ArbitraryRelationshipTemplateContent`](#arbitraryrelationshiptemplatecontent) | The content of the RelationshipTemplate. If it is intended for a User of the enmeshed App, `RelationshipTemplateContent` has to be used. Otherwise, an `ArbitraryRelationshipTemplateContent` can also be used, which can be filled with anything and serves as a fallback if the `RelationshipTemplateContent` is not sufficient. | | | expiresAt | `string` | {% include descr_expiresAt class="RelationshipTemplate" %} | will be encrypted before sent to the Backbone | | maxNumberOfAllocations | `number` \| `undefined` | Can be set to limit the number of allocations of this RelationshipTemplate. A RelationshipTemplate is allocated by another Identity when it is first retrieved by it from the Backbone. After this value is reached, the Backbone rejects each request of any new Identity that wants to retrieve it. Identities that already allocated it will still be able to retrieve it. | | +| forIdentity | `string` | Can be set to an enmeshed address. If set, then only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can retrieve the RelationshipTemplate from the Backbone. | | | truncatedReference | `string` | {% include descr_truncatedReference class="RelationshipTemplate" %} | saved only locally | ## Relationship diff --git a/_docs_integrate/establish-relationships.md b/_docs_integrate/establish-relationships.md index 09172bd28..5f1718b46 100644 --- a/_docs_integrate/establish-relationships.md +++ b/_docs_integrate/establish-relationships.md @@ -75,6 +75,22 @@ How to send a Request via a RelationshipTemplate is explained in detail in the [ If the RelationshipTemplate is intended to establish a Relationship between the templator and another Connector, an [ArbitraryRelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshiptemplatecontent) can be used instead of a RelationshipTemplateContent as the value of the [RelationshipTemplate's]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) `content`. An ArbitraryRelationshipTemplateContent has a single `value` property with no type restriction and is appropriate if the standard way is insufficient. +### Personalize the RelationshipTemplate + +If the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) is only for creating a Relationship with a single known [Identity]({% link _docs_integrate/data-model-overview.md %}#identity), you can set that Identity's `address` in the RelationshipTemplate: + +```jsonc +{ + // ... + "content": { + // ... + }, + "forIdentity": "
" +} +``` + +Only that Identity will be able to continue with establishing a Relationship. This also protects sensitive data of that Identity contained in the RelationshipTemplate from outside access. + ### Successfully Created RelationshipTemplate If you have successfully created the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) on the templator, you will receive a success response from which you can read its `id`. As the templator is the creator of the RelationshipTemplate, the `createdBy` property contains the Address of the templator. For this reason, the value of the `isOwn` property is set to `true` in this context. diff --git a/_docs_use-cases/use-case-transport-create-own-relationshiptemplate.md b/_docs_use-cases/use-case-transport-create-own-relationshiptemplate.md index 12d2011db..c9efd4481 100644 --- a/_docs_use-cases/use-case-transport-create-own-relationshiptemplate.md +++ b/_docs_use-cases/use-case-transport-create-own-relationshiptemplate.md @@ -42,7 +42,7 @@ api_route_regex: ^POST /api/v2/RelationshipTemplates/Own$ {% include properties_list.html %} -Creates a RelationshipTemplate with the given parameters and submits it to the Backbone for other Identites to use. +Creates a RelationshipTemplate with the given parameters and submits it to the Backbone for other [Identities]({% link _docs_integrate/data-model-overview.md %}#identity) to use. A [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) can be used by any party to either initiate a Relationship with the current Identity or retrieve a Request from an existing Relationship by a side-channel. @@ -51,6 +51,7 @@ A [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relat - `expiresAt` is the ISODateTime the RelationshipTemplate expires at. This should be set as small as possible and cannot be in the past. - `content` describes the structure of the RelationshipTemplate. If an enmeshed App user shall receive this RelationshipTemplate, a [RelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplatecontent) is required as structure, otherwise an [ArbitraryRelationshipTemplateContent]({% link _docs_integrate/data-model-overview.md %}#arbitraryrelationshiptemplatecontent) containing any data can be used. - `maxNumberOfAllocations` is the number of times the RelationshipTemplate can be accessed by different Identities to initiate a Relationship. The Backbone returns an error, if one accesses a RelationshipTemplate with no allocations left. Accessing the same RelationshipTemplate with the same Identity multiple times doesn't affect the number of allocations. The allocation counts, even if the Identity does not accept the RelationshipTemplate by discarding it. +- `forIdentity` can be set to an enmeshed address. If set, only the Identity with that `address` can access the RelationshipTemplate. ## On Success @@ -59,4 +60,4 @@ A [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relat ## On Failure - The `content` is malformed. -- `expiresAt` lies in the past +- `expiresAt` lies in the past. diff --git a/_docs_use-cases/use-case-transport-create-own-token.md b/_docs_use-cases/use-case-transport-create-own-token.md index 9fc5d4c47..1975da7f8 100644 --- a/_docs_use-cases/use-case-transport-create-own-token.md +++ b/_docs_use-cases/use-case-transport-create-own-token.md @@ -49,6 +49,7 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) that - `content` an arbitrary JSON structure of the data to share via the Token. - `expiresAt` is the ISODateTime the Token expires at. - `ephemeral` indicates if the Token should be ephemeral and thus not be stored and cached on the local database. This is especially useful for Tokens which are created regularly, e.g. for RelationshipTemplates and doesn't need to be stored. +- `forIdentity` can be set to an enmeshed address. If set, only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can load the Token from the Backbone. ## On Success @@ -57,4 +58,4 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) that ## On Failure - The `content` is malformed. -- `expiresAt` lies in the past +- `expiresAt` lies in the past. diff --git a/_docs_use-cases/use-case-transport-create-token-for-file.md b/_docs_use-cases/use-case-transport-create-token-for-file.md index 1303381f8..27a2a3d99 100644 --- a/_docs_use-cases/use-case-transport-create-token-for-file.md +++ b/_docs_use-cases/use-case-transport-create-token-for-file.md @@ -49,6 +49,7 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) for a - `fileId` is the `id` of the File the Token should be created for. - Optionally, `expiresAt` can be specified, which describes the ISODateTime the Token expires at. - Optionally, `ephemeral` can be specified, which indicates if the Token should be ephemeral and thus not be stored and cached on the local database. This is especially useful for Tokens which are created regularly, e.g. for [RelationshipTemplates]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) and don't need to be stored. +- Optionally, `forIdentity` can be specified, which names the `address` of the only [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) that will be able to load the Token from the Backbone. ## On Success diff --git a/_docs_use-cases/use-case-transport-create-token-for-own-relationshiptemplate.md b/_docs_use-cases/use-case-transport-create-token-for-own-relationshiptemplate.md index 34bf24287..8093f1c9a 100644 --- a/_docs_use-cases/use-case-transport-create-token-for-own-relationshiptemplate.md +++ b/_docs_use-cases/use-case-transport-create-token-for-own-relationshiptemplate.md @@ -44,13 +44,14 @@ api_route_regex: ^POST /api/v2/RelationshipTemplates/Own/{id}/Token$ {% include properties_list.html %} -Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) for a given [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) +Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) for a given [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate). ## Parameters -- `fileId` is the id of the File the Token should be created for. +- `templateId` is the `id` of the RelationshipTemplate the Token should be created for. - `expiresAt` is the ISODateTime the Token expires at. - `ephemeral` indicates if the Token should be ephemeral and thus not be stored and cached on the local database. This is especially useful for Tokens which are created regularly, e.g. for RelationshipTemplates and doesn't need to be stored. +- `forIdentity` can be set to an enmeshed address. If set, only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can load the Token from the Backbone. ## On Success @@ -59,4 +60,4 @@ Creates a [Token]({% link _docs_integrate/data-model-overview.md %}#token) for a ## On Failure - `templateId` does not resolve to a RelationshipTemplate. -- `expiresAt` lies in the past +- `expiresAt` lies in the past. diff --git a/_docs_use-cases/use-case-transport-create-token-qr-code-for-file.md b/_docs_use-cases/use-case-transport-create-token-qr-code-for-file.md index c1f74041a..081fd3923 100644 --- a/_docs_use-cases/use-case-transport-create-token-qr-code-for-file.md +++ b/_docs_use-cases/use-case-transport-create-token-qr-code-for-file.md @@ -48,10 +48,11 @@ Creates a QR code for a [Token]({% link _docs_integrate/data-model-overview.md % - `fileId` is the `id` of the File the Token and its QR code should be created for. - Optionally, `expiresAt` can be specified, which describes the ISODateTime the Token expires at. +- Optionally, `forIdentity` can be specified, which names the `address` of the only [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) that will be able to load the Token from the Backbone. ## On Success -- Returns the created QR code encoded as Base64. +- Returns the created QR code, whose content is Base64-encoded. ## On Failure diff --git a/_docs_use-cases/use-case-transport-create-token-qr-code-for-own-relationshiptemplate.md b/_docs_use-cases/use-case-transport-create-token-qr-code-for-own-relationshiptemplate.md index 20fa78a91..253968394 100644 --- a/_docs_use-cases/use-case-transport-create-token-qr-code-for-own-relationshiptemplate.md +++ b/_docs_use-cases/use-case-transport-create-token-qr-code-for-own-relationshiptemplate.md @@ -1,7 +1,7 @@ --- # Start automatic generation permalink: use-case-transport-create-token-qr-code-for-own-relationshiptemplate -published: false +published: true title: "Create Token QR code for own RelationshipTemplate" type: use-case toc: true @@ -18,8 +18,8 @@ properties: - feature category: Consent required before any data is shared - tech category: RelationshipTemplates - status: DONE - - documentation status: - - comments: + - documentation status: DONE + - comments: "Accept: image/png" - actor: Identity - trigger: - precondition: @@ -29,10 +29,32 @@ properties: - size: n/a - created_at: - changed_at: - - api_route_regex: + - api_route_regex: POST /api/v2/RelationshipTemplates/Own/{id}/Token - published: default - link: use-case-transport-create-token-qr-code-for-own-relationshiptemplate require: required_by: +api_route_regex: ^POST /api/v2/RelationshipTemplates/Own/{id}/Token$ # End automatic generation --- + +{{properties.description}} + +{% include properties_list.html %} + +Creates a QR code for a [Token]({% link _docs_integrate/data-model-overview.md %}#token) of a given [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate). + +## Parameters + +- `templateId` is the `id` of the RelationshipTemplate the Token and its QR code should be created for. +- `expiresAt` is the ISODateTime the Token expires at. +- `forIdentity` can be set to an enmeshed address. If set, only the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) with that `address` can load the Token from the Backbone. + +## On Success + +- Returns the created QR code, whose content is Base64-encoded. + +## On Failure + +- `templateId` does not resolve to a RelationshipTemplate. +- `expiresAt` lies in the past. diff --git a/_docs_use-cases/use-case-transport-load-relationshiptemplate-created-by-others.md b/_docs_use-cases/use-case-transport-load-relationshiptemplate-created-by-others.md index 25ae87bee..5f660db40 100644 --- a/_docs_use-cases/use-case-transport-load-relationshiptemplate-created-by-others.md +++ b/_docs_use-cases/use-case-transport-load-relationshiptemplate-created-by-others.md @@ -44,7 +44,7 @@ api_route_regex: ^POST /api/v2/RelationshipTemplates/Peer$ {% include properties_list.html %} -This use case loads a peer's [RelatonshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) from the Backbone by a given reference to the RelationshipTemplate. +This use case loads a peer's [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) from the Backbone by a given reference to the RelationshipTemplate. ## Parameters @@ -65,3 +65,4 @@ There are two different options to use this use case, depending on the actual in - The RelationshipTemplate does not exist. - The RelationshipTemplate is expired. - The `maxNumberOfAllocations` of the RelationshipTemplate are depleted. +- The RelationshipTemplate is personalized to a different [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) via the property `forIdentity` of the RelationshipTemplate. diff --git a/_docs_use-cases/use-case-transport-load-token-created-by-others.md b/_docs_use-cases/use-case-transport-load-token-created-by-others.md index da2924a3c..ae802aaab 100644 --- a/_docs_use-cases/use-case-transport-load-token-created-by-others.md +++ b/_docs_use-cases/use-case-transport-load-token-created-by-others.md @@ -60,3 +60,4 @@ You can execute this use case if you know the `truncatedReference` of the peer's - The parameters are malformed. - The Token does not exist. - The Token is expired. +- The Token is personalized to a different [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) via the property `forIdentity` of the Token.