@twin.org/synchronised-storage-service 0.0.1-next.3 → 0.0.1-next.5

package/docs/open-api/spec.json

@@ -21,30 +21,53 @@
 		}
 	],
 	"paths": {
-		"/synchronised-storage": {
-			"get": {
+		"/synchronised-storage/sync-changeset": {
+			"post": {
 				"operationId": "synchronisedStorageSyncChangeSetRequest",
 				"summary": "Request that the node perform a sync request for a changeset.",
 				"tags": [
 					"Synchronised Storage"
 				],
-				"parameters": [
-					{
-						"name": "changeSetStorageId",
-						"description": "The storage id of the changeset.",
-						"in": "query",
-						"required": false,
-						"schema": {
-							"type": "string"
-						},
-						"example": "12345"
-					}
-				],
-				"security": [
-					{
-						"jwtBearerAuthScheme": []
+				"requestBody": {
+					"description": "Request a trusted node to perform a sync request for a changeset.",
+					"required": true,
+					"content": {
+						"application/json": {
+							"schema": {
+								"$ref": "#/components/schemas/SyncChangeSet"
+							},
+							"examples": {
+								"synchronisedStorageSyncChangeSetRequestExample": {
+									"value": {
+										"id": "0909090909090909090909090909090909090909090909090909090909090909",
+										"dateCreated": "2025-05-29T01:00:00.000Z",
+										"dateModified": "2025-05-29T01:00:00.000Z",
+										"nodeIdentity": "did:entity-storage:0xd2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2",
+										"changes": [
+											{
+												"entity": {
+													"dateModified": "2025-01-01T00:00:00.000Z"
+												},
+												"id": "test-id-1",
+												"operation": "set"
+											}
+										],
+										"proof": {
+											"@context": "https://www.w3.org/ns/credentials/v2",
+											"created": "2025-05-29T01:00:00.000Z",
+											"cryptosuite": "eddsa-jcs-2022",
+											"proofPurpose": "assertionMethod",
+											"proofValue": "z5efBErQs3YBLZoH7jgKMQaRc9YjAxA5XSYKmW3FmTBDw9WionT2NS2x1SMvcRyBvw53cSSoaCT1xQH9tkWngGCX3",
+											"type": "DataIntegrityProof",
+											"verificationMethod": "did:entity-storage:0xd0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0#synchronised-storage-assertion"
+										},
+										"storageKey": "test-type"
+									}
+								}
+							}
+						}
 					}
-				],
+				},
 				"responses": {
 					"204": {
 						"description": "The rest request ended in success with no data."
@@ -70,6 +93,100 @@
 							}
 						}
 					},
+					"500": {
+						"description": "The server has encountered a situation it does not know how to handle, see the content for more details.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/Error"
+								},
+								"examples": {
+									"exampleResponse": {
+										"value": {
+											"name": "InternalServerError",
+											"message": "component.error"
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"/synchronised-storage/decryption-key": {
+			"post": {
+				"operationId": "synchronisedStorageGetDecryptionKeyRequest",
+				"summary": "Request the decryption key.",
+				"tags": [
+					"Synchronised Storage"
+				],
+				"requestBody": {
+					"description": "Request a trusted node to perform a sync request for a changeset.",
+					"required": true,
+					"content": {
+						"application/json": {
+							"schema": {
+								"$ref": "#/components/schemas/SyncChangeSet"
+							},
+							"examples": {
+								"synchronisedStorageSyncGetDecryptionKeyRequestExample": {
+									"value": {
+										"nodeIdentity": "did:entity-storage:0xd2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2",
+										"proof": {
+											"@context": "https://www.w3.org/ns/credentials/v2",
+											"created": "2025-05-29T01:00:00.000Z",
+											"cryptosuite": "eddsa-jcs-2022",
+											"proofPurpose": "assertionMethod",
+											"proofValue": "z5efBErQs3YBLZoH7jgKMQaRc9YjAxA5XSYKmW3FmTBDw9WionT2NS2x1SMvcRyBvw53cSSoaCT1xQH9tkWngGCX3",
+											"type": "DataIntegrityProof",
+											"verificationMethod": "did:entity-storage:0xd0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0#synchronised-storage-assertion"
+										}
+									}
+								}
+							}
+						}
+					}
+				},
+				"responses": {
+					"200": {
+						"description": "Response to a request for the decryption key for the synchronised storage.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/SyncDecryptionKeyResponse"
+								},
+								"examples": {
+									"synchronisedStorageSyncGetDecryptionKeyResponseExample": {
+										"value": {
+											"decryptionKey": "z5efBErQs3YBLZoH7jgKMQaRc9YjAxA5XSYKmW3FmTBDw9WionT2NS2x1SMvcRyBvw53cSSoaCT1xQH9tkWngGCX3"
+										}
+									}
+								}
+							}
+						}
+					},
+					"400": {
+						"description": "The server cannot process the request, see the content for more details.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/Error"
+								},
+								"examples": {
+									"exampleResponse": {
+										"value": {
+											"name": "GeneralError",
+											"message": "component.error",
+											"properties": {
+												"foo": "bar"
+											}
+										}
+									}
+								}
+							}
+						}
+					},
 					"401": {
 						"description": "You are not authorized to use the API or no credentials were supplied, see the content for more details.",
 						"content": {
@@ -146,6 +263,117 @@
 				],
 				"additionalProperties": false,
 				"description": "Model to describe serialized error."
+			},
+			"SyncChange<SynchronisedEntity>": {
+				"type": "object",
+				"properties": {
+					"operation": {
+						"$ref": "#/components/schemas/SyncChangeOperation"
+					},
+					"id": {
+						"type": "string",
+						"description": "The item id."
+					},
+					"entity": {
+						"$ref": "#/components/schemas/SynchronisedEntity"
+					}
+				},
+				"required": [
+					"operation",
+					"id"
+				],
+				"additionalProperties": false,
+				"description": "The object definition for a sync change."
+			},
+			"SyncChangeOperation": {
+				"anyOf": [
+					{
+						"type": "string",
+						"const": "set",
+						"description": "An item was set in the storage."
+					},
+					{
+						"type": "string",
+						"const": "delete",
+						"description": "An item was deleted from the storage."
+					}
+				],
+				"description": "The operations for a change.   The operations for a change"
+			},
+			"SyncChangeSet": {
+				"type": "object",
+				"properties": {
+					"id": {
+						"type": "string",
+						"description": "The id of the change set."
+					},
+					"dateCreated": {
+						"type": "string",
+						"description": "The date the change set was created."
+					},
+					"storageKey": {
+						"type": "string",
+						"description": "The storage key of the change set. This is used to identify the entities being synchronised."
+					},
+					"dateModified": {
+						"type": "string",
+						"description": "The date the change set was last modified."
+					},
+					"changes": {
+						"type": "array",
+						"items": false,
+						"description": "The changes to apply after a snapshot.",
+						"prefixItems": [
+							{
+								"$ref": "#/components/schemas/SyncChange<SynchronisedEntity>"
+							}
+						]
+					},
+					"nodeIdentity": {
+						"type": "string",
+						"description": "The identity of the node that created the change set."
+					},
+					"proof": {
+						"$ref": "https://schema.twindev.org/w3c-did/Proof"
+					}
+				},
+				"required": [
+					"id",
+					"dateCreated",
+					"storageKey",
+					"dateModified",
+					"changes",
+					"nodeIdentity"
+				],
+				"additionalProperties": false,
+				"description": "The object definition for a sync change set."
+			},
+			"SyncDecryptionKeyResponse": {
+				"type": "object",
+				"properties": {
+					"decryptionKey": {
+						"type": "string",
+						"description": "The decryption key for the synchronised storage as base64."
+					}
+				},
+				"required": [
+					"decryptionKey"
+				],
+				"additionalProperties": false,
+				"description": "The body of the response."
+			},
+			"SynchronisedEntity": {
+				"type": "object",
+				"properties": {
+					"dateModified": {
+						"type": "string",
+						"description": "The date the entry was modified"
+					}
+				},
+				"required": [
+					"dateModified"
+				],
+				"additionalProperties": false
 			}
 		},
 		"securitySchemes": {

package/docs/reference/classes/SyncSnapshotEntry.md

@@ -28,6 +28,14 @@ The id for the snapshot.
 
 ***
 
+### version
+
+> **version**: `string`
+
+The version for the snapshot.
+
+***
+
 ### storageKey
 
 > **storageKey**: `string`
@@ -44,19 +52,27 @@ The date the snapshot was created.
 
 ***
 
-### dateModified?
+### dateModified
 
-> `optional` **dateModified**: `string`
+> **dateModified**: `string`
 
 The date the snapshot was last modified.
 
 ***
 
-### isLocalSnapshot?
+### isLocal
+
+> **isLocal**: `boolean`
+
+The flag to determine if this is the snapshot is the local one containing changes for this node.
+
+***
+
+### isConsolidated
 
-> `optional` **isLocalSnapshot**: `boolean`
+> **isConsolidated**: `boolean`
 
-The flag to determine if this is the current local snapshot containing changes for this node.
+The flag to determine if this is a consolidated snapshot.
 
 ***
 
@@ -70,6 +86,6 @@ The ids of the storage for the change sets in the snapshot, if this is not a loc
 
 ### changes?
 
-> `optional` **changes**: [`ISyncChange`](../interfaces/ISyncChange.md)\<`T`\>[]
+> `optional` **changes**: `ISyncChange`\<`T`\>[]
 
 The changes that were made in this snapshot, if this is a local snapshot.

package/docs/reference/classes/SynchronisedStorageService.md

@@ -118,19 +118,52 @@ Nothing.
 
 ***
 
-### syncChangeSet()
+### getDecryptionKey()
 
-> **syncChangeSet**(`changeSetStorageId`): `Promise`\<`void`\>
+> **getDecryptionKey**(`nodeIdentity`, `proof`): `Promise`\<`string`\>
 
-Synchronise a complete set of changes, assumes this is a trusted node.
+Get the decryption key for the synchronised storage.
+This is used to decrypt the data stored in the synchronised storage.
 
 #### Parameters
 
-##### changeSetStorageId
+##### nodeIdentity
 
 `string`
 
-The id of the change set to synchronise in blob storage.
+The identity of the node requesting the decryption key.
+
+##### proof
+
+`IProof`
+
+The proof of the request so we know the request is from the specified node.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The decryption key.
+
+#### Implementation of
+
+`ISynchronisedStorageComponent.getDecryptionKey`
+
+***
+
+### syncChangeSet()
+
+> **syncChangeSet**(`syncChangeSet`): `Promise`\<`void`\>
+
+Synchronise a set of changes from an untrusted node, assumes this is a trusted node.
+
+#### Parameters
+
+##### syncChangeSet
+
+`ISyncChangeSet`\<`T`\>
+
+The change set to synchronise.
 
 #### Returns
 

package/docs/reference/functions/synchronisedStorageGetDecryptionKeyRequest.md

@@ -0,0 +1,31 @@
+# Function: synchronisedStorageGetDecryptionKeyRequest()
+
+> **synchronisedStorageGetDecryptionKeyRequest**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`ISyncDecryptionKeyResponse`\>
+
+Request the decryption key.
+
+## Parameters
+
+### httpRequestContext
+
+`IHttpRequestContext`
+
+The request context for the API.
+
+### componentName
+
+`string`
+
+The name of the component to use in the routes.
+
+### request
+
+`ISyncDecryptionKeyRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`ISyncDecryptionKeyResponse`\>
+
+The response object with additional http response properties.

package/docs/reference/index.md

@@ -7,8 +7,6 @@
 
 ## Interfaces
 
-- [ISyncChange](interfaces/ISyncChange.md)
-- [ISyncChangeSet](interfaces/ISyncChangeSet.md)
 - [ISyncPointerStore](interfaces/ISyncPointerStore.md)
 - [ISyncSnapshot](interfaces/ISyncSnapshot.md)
 - [ISyncState](interfaces/ISyncState.md)
@@ -25,3 +23,4 @@
 - [initSchema](functions/initSchema.md)
 - [generateRestRoutesSynchronisedStorage](functions/generateRestRoutesSynchronisedStorage.md)
 - [synchronisedStorageSyncChangeSetRequest](functions/synchronisedStorageSyncChangeSetRequest.md)
+- [synchronisedStorageGetDecryptionKeyRequest](functions/synchronisedStorageGetDecryptionKeyRequest.md)

package/docs/reference/interfaces/ISyncPointerStore.md

@@ -4,6 +4,14 @@ The object definition for the sync pointer store.
 
 ## Properties
 
+### version
+
+> **version**: `string`
+
+The version of the sync pointer store.
+
+***
+
 ### syncPointers
 
 > **syncPointers**: `object`

package/docs/reference/interfaces/ISyncSnapshot.md

@@ -4,6 +4,14 @@ The object definition for a sync snapshot.
 
 ## Properties
 
+### version
+
+> **version**: `string`
+
+The version of the sync state.
+
+***
+
 ### id
 
 > **id**: `string`
@@ -20,14 +28,22 @@ The date the snapshot was created.
 
 ***
 
-### dateModified?
+### dateModified
 
-> `optional` **dateModified**: `string`
+> **dateModified**: `string`
 
 The date the snapshot was last modified.
 
 ***
 
+### isConsolidated
+
+> **isConsolidated**: `boolean`
+
+Is this a consolidated snapshot?
+
+***
+
 ### changeSetStorageIds
 
 > **changeSetStorageIds**: `string`[]

package/docs/reference/interfaces/ISyncState.md

@@ -4,6 +4,22 @@ The object definition for a sync state.
 
 ## Properties
 
+### version
+
+> **version**: `string`
+
+The version of the sync state.
+
+***
+
+### storageKey
+
+> **storageKey**: `string`
+
+The storage type contained in the sync state.
+
+***
+
 ### snapshots
 
 > **snapshots**: [`ISyncSnapshot`](ISyncSnapshot.md)[]

package/docs/reference/interfaces/ISynchronisedStorageServiceConfig.md

@@ -4,20 +4,11 @@ Configuration for the Synchronised Storage Service.
 
 ## Properties
 
-### synchronisedStorageKey
-
-> **synchronisedStorageKey**: `string`
-
-The key to use for the remote synchronised storage, the initial item will have been
-generated by a trusted node.
-
-***
-
 ### synchronisedStorageMethodId?
 
 > `optional` **synchronisedStorageMethodId**: `string`
 
-The id of the identity method to use when signing/verifying changesets.
+The id of the identity method to use when signing/verifying requests and changesets.
 
 #### Default
 
@@ -80,3 +71,46 @@ The number of entities to process in a single consolidation batch.
 ```ts
 1000
 ```
+
+***
+
+### maxConsolidations?
+
+> `optional` **maxConsolidations**: `number`
+
+The maximum number of consolidations to keep in storage.
+
+#### Default
+
+```ts
+5
+```
+
+***
+
+### blobStorageEncryptionKeyId?
+
+> `optional` **blobStorageEncryptionKeyId**: `string`
+
+The encryption key id from the vault to use for blob storage, only required for trusted nodes, untrusted nodes will request the key.
+
+#### Default
+
+```ts
+synchronised-storage-blob-encryption-key
+```
+
+***
+
+### verifiableStorageKeyId
+
+> **verifiableStorageKeyId**: `string`
+
+The verifiable storage key to use, already expected to be created.
+if the key is not found in the keys.json it is considered to be a custom verifiable storage id.
+
+#### Default
+
+```ts
+local
+```

package/docs/reference/interfaces/ISynchronisedStorageServiceConstructorOptions.md

@@ -20,6 +20,14 @@ The event bus component type.
 
 ***
 
+### vaultConnectorType?
+
+> `optional` **vaultConnectorType**: `string`
+
+The vault connector type.
+
+***
+
 ### syncSnapshotStorageConnectorType?
 
 > `optional` **syncSnapshotStorageConnectorType**: `string`
@@ -34,11 +42,11 @@ sync-snapshot-entry
 
 ***
 
-### blobStorageComponentType?
+### blobStorageConnectorType?
 
-> `optional` **blobStorageComponentType**: `string`
+> `optional` **blobStorageConnectorType**: `string`
 
-The blob storage component used for remote sync state.
+The blob storage connector used for remote sync state.
 
 #### Default