@twin.org/synchronised-storage-service 0.0.1-next.2 → 0.0.1-next.4

package/docs/changelog.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [0.0.1-next.4](https://github.com/twinfoundation/synchronised-storage/compare/synchronised-storage-service-v0.0.1-next.3...synchronised-storage-service-v0.0.1-next.4) (2025-08-08)
+
+
+### Features
+
+* add payload versioning ([3bbbce0](https://github.com/twinfoundation/synchronised-storage/commit/3bbbce0bdf24bbe67c1a265704538d505d7feb91))
+* blob storage connector instead of component ([#7](https://github.com/twinfoundation/synchronised-storage/issues/7)) ([ea27241](https://github.com/twinfoundation/synchronised-storage/commit/ea27241cf0810b52ab7a6be7346809d127b7109a))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/synchronised-storage-models bumped from 0.0.1-next.3 to 0.0.1-next.4
+
+## [0.0.1-next.3](https://github.com/twinfoundation/synchronised-storage/compare/synchronised-storage-service-v0.0.1-next.2...synchronised-storage-service-v0.0.1-next.3) (2025-07-25)
+
+
+### Features
+
+* sync testing ([#5](https://github.com/twinfoundation/synchronised-storage/issues/5)) ([f78d5ac](https://github.com/twinfoundation/synchronised-storage/commit/f78d5ac661b891f9912e0a81d028453f909a64b4))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/synchronised-storage-models bumped from 0.0.1-next.2 to 0.0.1-next.3
+
 ## [0.0.1-next.2](https://github.com/twinfoundation/synchronised-storage/compare/synchronised-storage-service-v0.0.1-next.1...synchronised-storage-service-v0.0.1-next.2) (2025-07-22)
 
 

package/docs/open-api/spec.json

@@ -21,30 +21,52 @@
 		}
 	],
 	"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",
+										"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 +92,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 +262,116 @@
 				],
 				"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",
+					"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,11 +28,11 @@ The id for the snapshot.
 
 ***
 
-### schemaType
+### storageKey
 
-> **schemaType**: `string`
+> **storageKey**: `string`
 
-The schema type for the snapshot i.e. which entity is being synchronized.
+The storage key for the snapshot i.e. which entity is being synchronized.
 
 ***
 
@@ -68,8 +68,8 @@ The ids of the storage for the change sets in the snapshot, if this is not a loc
 
 ***
 
-### localChanges?
+### changes?
 
-> `optional` **localChanges**: [`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,7 +7,9 @@
 
 ## Interfaces
 
-- [ISyncChange](interfaces/ISyncChange.md)
+- [ISyncPointerStore](interfaces/ISyncPointerStore.md)
+- [ISyncSnapshot](interfaces/ISyncSnapshot.md)
+- [ISyncState](interfaces/ISyncState.md)
 - [ISynchronisedStorageServiceConfig](interfaces/ISynchronisedStorageServiceConfig.md)
 - [ISynchronisedStorageServiceConstructorOptions](interfaces/ISynchronisedStorageServiceConstructorOptions.md)
 
@@ -21,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

@@ -0,0 +1,23 @@
+# Interface: ISyncPointerStore
+
+The object definition for the sync pointer store.
+
+## Properties
+
+### version
+
+> **version**: `string`
+
+The version of the sync pointer store.
+
+***
+
+### syncPointers
+
+> **syncPointers**: `object`
+
+The mapping from storage keys to sync pointers.
+
+#### Index Signature
+
+\[`key`: `string`\]: `string`

package/docs/reference/interfaces/ISyncSnapshot.md

@@ -0,0 +1,43 @@
+# Interface: ISyncSnapshot
+
+The object definition for a sync snapshot.
+
+## Properties
+
+### version
+
+> **version**: `string`
+
+The version of the sync state.
+
+***
+
+### id
+
+> **id**: `string`
+
+The id of the snapshot.
+
+***
+
+### dateCreated
+
+> **dateCreated**: `string`
+
+The date the snapshot was created.
+
+***
+
+### dateModified
+
+> **dateModified**: `string`
+
+The date the snapshot was last modified.
+
+***
+
+### changeSetStorageIds
+
+> **changeSetStorageIds**: `string`[]
+
+The ids of the storage for the change sets in the snapshot.

package/docs/reference/interfaces/ISyncState.md

@@ -0,0 +1,19 @@
+# Interface: ISyncState
+
+The object definition for a sync state.
+
+## Properties
+
+### version
+
+> **version**: `string`
+
+The version of the sync state.
+
+***
+
+### snapshots
+
+> **snapshots**: [`ISyncSnapshot`](ISyncSnapshot.md)[]
+
+The snapshots.

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
 
@@ -27,16 +18,16 @@ synchronised-storage-assertion
 
 ***
 
-### entityUpdateIntervalMs?
+### entityUpdateIntervalMinutes?
 
-> `optional` **entityUpdateIntervalMs**: `number`
+> `optional` **entityUpdateIntervalMinutes**: `number`
 
-How often to check for entity updates in milliseconds.
+How often to check for entity updates in minutes.
 
 #### Default
 
 ```ts
-300000 (5 minutes)
+5
 ```
 
 ***
@@ -55,16 +46,16 @@ false
 
 ***
 
-### consolidationIntervalMs?
+### consolidationIntervalMinutes?
 
-> `optional` **consolidationIntervalMs**: `number`
+> `optional` **consolidationIntervalMinutes**: `number`
 
 Interval to perform consolidation of changesets, only used if isTrustedNode is set.
 
 #### Default
 
 ```ts
-300000 (5 minutes)
+60
 ```
 
 ***
@@ -80,3 +71,32 @@ The number of entities to process in a single consolidation batch.
 ```ts
 1000
 ```
+
+***
+
+### 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
 
@@ -76,6 +84,20 @@ identity
 
 ***
 
+### taskSchedulerComponentType?
+
+> `optional` **taskSchedulerComponentType**: `string`
+
+The task scheduler component.
+
+#### Default
+
+```ts
+task-scheduler
+```
+
+***
+
 ### trustedSynchronisedStorageComponentType?
 
 > `optional` **trustedSynchronisedStorageComponentType**: `string`