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

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

@@ -70,6 +70,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,9 +28,9 @@ The date the snapshot was created.
 
 ***
 
-### dateModified?
+### dateModified
 
-> `optional` **dateModified**: `string`
+> **dateModified**: `string`
 
 The date the snapshot was last modified.
 

package/docs/reference/interfaces/ISyncState.md

@@ -4,6 +4,14 @@ The object definition for a sync state.
 
 ## Properties
 
+### version
+
+> **version**: `string`
+
+The version of 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,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
 

package/locales/en.json

@@ -4,18 +4,22 @@
 			"changeSetApplyingChange": "Applying remote sync change with operation id \"{operation}\" for item with id \"{id}\"",
 			"changeSetStoring": "Storing remote sync change set with id \"{id}\"",
 			"verifyChangeSetProofMissing": "Verifying change set with id \"{id}\" failed, missing proof",
-			"verifyChangeSetProofInvalid": "Verifying change set with id \"{id}\" failed, invalid proof",
+			"verifyChangeSetProofInvalid": "Verifying change set with id \"{id}\" failed, missing proof",
+			"verifyChangeSetProofNodeIdentityMismatch": "Verifying change set with id \"{id}\" failed, the node identity does not match the proof",
 			"verifyChangeSetProofValid": "Verifying change set with id \"{id}\" succeeded",
-			"createdChangeSetProof": "Created change proof for change set with id \"{id}\", proof value is \"{proofValue}\""
+			"createdChangeSetProof": "Created change proof for change set with id \"{id}\", proof value is \"{proofValue}\"",
+			"getChangeSet": "Retrieving change set with id \"{changeSetStorageId}\"",
+			"getChangeSetEmpty": "No change set found with id \"{changeSetStorageId}\"",
+			"copyChangeSet": "Copying change set with id \"{changeSetStorageId}\""
 		},
 		"localSyncStateHelper": {
 			"getLocalChangeSnapshot": "Retrieving local change snapshot for storage key \"{storageKey}\"",
 			"localChangeSnapshotExists": "Found existing local change snapshot for storage key \"{storageKey}\"",
 			"localChangeSnapshotDoesNotExist": "No local change snapshot found for storage key \"{storageKey}\", creating new one",
-			"remoteSyncSynchronisation": "Syncing from remote state with \"{snapshotCount}\" snapshots",
-			"remoteSyncSnapshotProcessing": "Processing remote sync snapshot with id \"{snapshotId}\" created on \"{dateCreated}\"",
-			"remoteSyncSnapshotModified": "Processing modified sync snapshot with id \"{snapshotId}\", remote modified on \"{remoteModified}\", local modified on \"{localModified}\"",
-			"remoteSyncSnapshotNew": "Processing new sync snapshot with id \"{snapshotId}\", created on \"{dateCreated}\"",
+			"applySyncState": "Syncing from remote state with \"{snapshotCount}\" snapshots",
+			"applySnapshot": "Processing sync snapshot with id \"{snapshotId}\" created on \"{dateCreated}\"",
+			"processModifiedSnapshot": "Processing modified sync snapshot with id \"{snapshotId}\", remote modified on \"{remoteModified}\", local modified on \"{localModified}\"",
+			"processNewSnapshot": "Processing new sync snapshot with id \"{snapshotId}\", created on \"{dateCreated}\"",
 			"removeLocalChangeSnapshot": "Removing local change snapshot with id \"{snapshotId}\"",
 			"addLocalChange": "Adding local change with id \"{id}\" to local change snapshot for storage key \"{storageKey}\", operation \"{operation}\"",
 			"setLocalChangeSnapshot": "Storing local change snapshot for storage key \"{storageKey}\""
@@ -32,20 +36,29 @@
 			"consolidationStarting": "Starting consolidation of remote sync state",
 			"consolidationCompleted": "Consolidation of remote sync state completed",
 			"addChangeSetToSyncState": "Adding change set with id \"{changeSetStorageId}\" to remote sync state for storage key \"{storageKey}\"",
-			"createAndStoreChangeSet": "Creating and storing change set for storage key \"{storageKey}\" with \"{changeCount}\" changes",
+			"buildingChangeSet": "Building change set for storage key \"{storageKey}\" with \"{changeCount}\" changes",
 			"finalisingSyncChanges": "Finalising sync changes for storage key \"{storageKey}\""
 		},
 		"synchronisedStorageService": {
-			"registerType": "Registering synchronised storage type \"{storageKey}\"",
-			"activateType": "Activating synchronised storage type \"{storageKey}\"",
-			"startEntitySync": "Starting synchronised entity storage for type \"{storageKey}\"",
-			"updateFromRemoteSyncState": "Updating synchronised entity storage from remote sync state for type \"{storageKey}\"",
-			"updateFromLocalSyncState": "Updating synchronised entity storage from local sync state for type \"{storageKey}\"",
-			"updateFromLocalSyncStateNoChanges": "No changes found in local sync state for type \"{storageKey}\", skipping update",
-			"createdStorageChangeSet": "Created storage change set for type \"{storageKey}\" with id \"{changeSetStorageId}\"",
-			"createdStorageChangeSetNone": "No changes found for type \"{storageKey}\", no storage change set created",
-			"createChangeSetRequestingItem": "Creating change set for type \"{storageKey}\", requesting item with id \"{id}\"",
-			"createChangeSetRespondingItem": "Responding to change set request for type \"{storageKey}\", item with id \"{id}\""
+			"registerStorageKey": "Registering synchronised storage key \"{storageKey}\"",
+			"activateStorageKey": "Activating synchronised storage key \"{storageKey}\"",
+			"startEntitySync": "Starting synchronised entity storage for key \"{storageKey}\"",
+			"updateFromRemoteSyncState": "Updating synchronised entity storage from remote sync state for key \"{storageKey}\"",
+			"updateFromLocalSyncState": "Updating synchronised entity storage from local sync state for key \"{storageKey}\"",
+			"updateFromLocalSyncStateNoChanges": "No changes found in local sync state for key \"{storageKey}\", skipping update",
+			"builtStorageChangeSet": "Built storage change set for key \"{storageKey}\" with id \"{changeSetStorageId}\"",
+			"builtStorageChangeSetNone": "No changes found for key \"{storageKey}\", no storage change set created",
+			"createChangeSetRequestingItem": "Creating change set for key \"{storageKey}\", requesting item with id \"{id}\"",
+			"createChangeSetRespondingItem": "Responding to change set request for key \"{storageKey}\", item with id \"{id}\"",
+			"sendingChangeSetToTrustedNode": "Sending change set with id \"{changeSetStorageId}\" to trusted node for key \"{storageKey}\"",
+			"syncChangeSetForRemoteNode": "Synchronising change set with id \"{changeSetStorageId}\" for remote node for type \"{storageKey}\""
+		},
+		"blobStorageHelper": {
+			"loadBlob": "Loading blob with id \"{blobId}\"",
+			"loadedBlob": "Loaded blob with id \"{blobId}\"",
+			"loadBlobEmpty": "No blob found with id \"{blobId}\"",
+			"saveBlob": "Saving blob",
+			"savedBlob": "Saved blob with id \"{blobId}\""
 		}
 	},
 	"error": {
@@ -56,10 +69,25 @@
 		"synchronisedStorageService": {
 			"notTrustedNode": "This method can only be called on a trusted node",
 			"entitySyncFailed": "Failed to sync synchronised entity storage connector",
-			"consolidationSyncFailed": "Failed to consolidate synchronised entity storage connector"
+			"consolidationSyncFailed": "Failed to consolidate synchronised entity storage connector",
+			"invalidProof": "Invalid proof provided for synchronised entity storage connector",
+			"decryptionKeyNotFound": "Decryption key not found, ensure the synchronised storage component is initialised and the decryption key is set"
 		},
 		"remoteSyncStateHelper": {
 			"finalisingSyncChangesFailed": "Failed to finalise sync changes for storage key \"{storageKey}\""
+		},
+		"blobStorageHelper": {
+			"loadBlobFailed": "Failed to load blob with id \"{blobId}\"",
+			"saveBlobFailed": "Failed to save blob",
+			"notTrustedNode": "Cannot save blob, this is not a trusted node"
+		}
+	},
+	"warn": {
+		"changeSetHelper": {
+			"getChangeSetError": "Failed to retrieve change set with id \"{changeSetStorageId}\""
+		},
+		"remoteSyncStateHelper": {
+			"getSyncStateError": "Failed to retrieve sync state for syncPointerId \"{syncPointerId}\""
 		}
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/synchronised-storage-service",
-	"version": "0.0.1-next.3",
+	"version": "0.0.1-next.4",
 	"description": "Synchronised storage contract implementation and REST endpoint definitions",
 	"repository": {
 		"type": "git",
@@ -18,6 +18,7 @@
 		"@twin.org/background-task-models": "next",
 		"@twin.org/blob-storage-models": "next",
 		"@twin.org/core": "next",
+		"@twin.org/crypto": "next",
 		"@twin.org/entity": "next",
 		"@twin.org/entity-storage-models": "next",
 		"@twin.org/event-bus-models": "next",
@@ -25,7 +26,7 @@
 		"@twin.org/logging-models": "next",
 		"@twin.org/nameof": "next",
 		"@twin.org/standards-w3c-did": "next",
-		"@twin.org/synchronised-storage-models": "0.0.1-next.3",
+		"@twin.org/synchronised-storage-models": "0.0.1-next.4",
 		"@twin.org/verifiable-storage-models": "next",
 		"@twin.org/web": "next"
 	},