Skip to content

Commit

Permalink
Add description for password protection of RelationshipTemplates and …
Browse files Browse the repository at this point in the history 
…Tokens (#287)

* fix: forIdentity property of RelationshipTemplate and Token is optional

* feat: add passwordProtection property to RelationshipTemplate

* feat: add paragraph within establish Relationships scenario

* feat: use more appropriate links

* refactor: change order of sentences

* feat: add passwordProtection property to Token

* feat: add link to "Load Token" use case

* feat: add runtime errors regarding password protection and personalization

* feat: add passwordProtection and password parameters to use cases

* feat: add personalization failure to load File use case

* feat: add noPasswordProvided error

* feat: add passwordProtection to create (get) device onboarding token use case

* feat: add forIdentity and passwordProtection to getters of RelationshipTemplates and Tokens

* feat: incorporate review comments

* feat: incorporate PasswordProtectionDTO

* refactor: rephrase sentence

---------

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
  • Loading branch information
@britsta @mergify
britsta and mergify[bot] authored Dec 19, 2024
1 parent 9f4682a commit a0d6873
Show file tree
Hide file tree
Showing 16 changed files with 105 additions and 28 deletions.
38 changes: 26 additions & 12 deletions _docs_integrate/data-model-overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,17 +51,30 @@ 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" %} | |
| 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. |
| 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` \| `undefined` | 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. |
| passwordProtection | [`PasswordProtection`](#passwordprotection) \| `undefined` | Information about whether or not the Token is protected by a password or pin. | |
| 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. |

### PasswordProtection

A [Token](#token) or [RelationshipTemplate can be protected by a password]({% link _docs_integrate/establish-relationships.md %}#password-protection-of-a-relationshiptemplate) to ensure that it is protected from unauthorized access.
In order for a peer to [establish a Relationship]({% link _docs_integrate/establish-relationships.md %}) to the creator of a password protected [RelationshipTemplate](#relationshiptemplate), it must enter the correct password when [loading the RelationshipTemplate]({% link _docs_use-cases/use-case-transport-load-relationshiptemplate-created-by-others.md %}).
Similarly, in order for an Identity to [load a Token]({% link _docs_use-cases/use-case-transport-load-token-created-by-others.md %}) that is password protected, it must enter the correct password.
Information about the password protection of a Token or a RelationshipTemplate is recorded within its optional `passwordProtection` property.

| Name | Type | Description | Remarks |
| ------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| password | `string` | The password of the Token or the RelationshipTemplate. | |
| passwordIsPin | `true` \| `undefined` | If the password consists of 4 to 16 digits, the value of the `passwordIsPin` property can be set to `true`. In this case, the password is interpreted as a pin and a corresponding input field is displayed in the UI of the App when the pin needs to be entered. However, if the value is `undefined`, a regular input field for entering the password is displayed regardless of whether the password could also be interpreted as a pin. | |

## RelationshipTemplate

Expand All @@ -80,7 +93,8 @@ 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. | |
| forIdentity | `string` \| `undefined` | 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. | |
| passwordProtection | [`PasswordProtection`](#passwordprotection) \| `undefined` | Information about whether or not the RelationshipTemplate is protected by a password or pin. | |
| truncatedReference | `string` | {% include descr_truncatedReference class="RelationshipTemplate" %} | saved only locally |

## Relationship
Expand Down
Loading

0 comments on commit a0d6873

Please sign in to comment.