Skip to content

Commit

Permalink
Personalization of Tokens and RelationshipTemplates (#283)
Browse files Browse the repository at this point in the history 
* feat: add personalization

* refactor: review comments

* refactor: dotting

---------

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
  • Loading branch information
@Magnus-Kuhn @mergify
Magnus-Kuhn and mergify[bot] authored Nov 15, 2024
1 parent 8d12167 commit 1994384
Show file tree
Hide file tree
Showing 10 changed files with 69 additions and 22 deletions.
22 changes: 12 additions & 10 deletions _docs_integrate/data-model-overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down
16 changes: 16 additions & 0 deletions _docs_integrate/establish-relationships.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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": "<address that the RelationshipTemplate is intended for>"
}
```

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.
Expand Down
5 changes: 3 additions & 2 deletions _docs_use-cases/use-case-transport-create-own-relationshiptemplate.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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

Expand All @@ -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.
3 changes: 2 additions & 1 deletion _docs_use-cases/use-case-transport-create-own-token.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.
1 change: 1 addition & 0 deletions _docs_use-cases/use-case-transport-create-token-for-file.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
7 changes: 4 additions & 3 deletions _docs_use-cases/use-case-transport-create-token-for-own-relationshiptemplate.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.
3 changes: 2 additions & 1 deletion _docs_use-cases/use-case-transport-create-token-qr-code-for-file.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
30 changes: 26 additions & 4 deletions ...e-cases/use-case-transport-create-token-qr-code-for-own-relationshiptemplate.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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:
Expand All @@ -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.
3 changes: 2 additions & 1 deletion _docs_use-cases/use-case-transport-load-relationshiptemplate-created-by-others.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.
1 change: 1 addition & 0 deletions _docs_use-cases/use-case-transport-load-token-created-by-others.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

0 comments on commit 1994384

Please sign in to comment.