@twin.org/identity-connector-entity-storage 0.0.3-next.9 → 0.9.0

package/docs/examples.md

@@ -1 +1,221 @@
-# @twin.org/identity-connector-entity-storage - Examples
+# Identity Connector Entity Storage Examples
+
+These snippets demonstrate document, profile, and resolution workflows using entity storage connectors and model entities.
+
+## EntityStorageIdentityConnector
+
+```typescript
+import { EntityStorageIdentityConnector } from '@twin.org/identity-connector-entity-storage';
+
+const connector = new EntityStorageIdentityConnector({
+  didDocumentEntityStorageType: 'identity-document',
+  vaultConnectorType: 'vault'
+});
+
+const className = connector.className();
+const createdDocument = await connector.createDocument('controller-1');
+const vaultKey = EntityStorageIdentityConnector.buildVaultKey(createdDocument.id, 'did');
+
+await connector.removeDocument('controller-1', createdDocument.id);
+
+console.log(className); // EntityStorageIdentityConnector
+console.log(vaultKey); // did:entity-storage:.../did
+```
+
+```typescript
+import { EntityStorageIdentityConnector } from '@twin.org/identity-connector-entity-storage';
+import { DidVerificationMethodType, ProofTypes } from '@twin.org/standards-w3c-did';
+
+const connector = new EntityStorageIdentityConnector({
+  didDocumentEntityStorageType: 'identity-document',
+  vaultConnectorType: 'vault'
+});
+
+const identity = 'did:entity-storage:0x1234abcd';
+
+const verificationMethod = await connector.addVerificationMethod(
+  'controller-1',
+  identity,
+  DidVerificationMethodType.VerificationMethod,
+  'signing-key'
+);
+
+await connector.removeVerificationMethod('controller-1', verificationMethod.id);
+
+const service = await connector.addService(
+  'controller-1',
+  identity,
+  'linked-domain',
+  'LinkedDomains',
+  'https://example.org'
+);
+
+await connector.removeService('controller-1', service.id);
+
+const createdCredential = await connector.createVerifiableCredential(
+  'controller-1',
+  `${identity}#signing-key`,
+  'urn:uuid:credential-001',
+  {
+    id: 'did:entity-storage:0x5678efab',
+    role: 'Engineer'
+  },
+  {
+    revocationIndex: 3
+  }
+);
+
+const verifiedCredential = await connector.checkVerifiableCredential(createdCredential.jwt);
+
+await connector.revokeVerifiableCredentials('controller-1', identity, [3]);
+await connector.unrevokeVerifiableCredentials('controller-1', identity, [3]);
+
+const createdPresentation = await connector.createVerifiablePresentation(
+  'controller-1',
+  `${identity}#signing-key`,
+  'urn:uuid:presentation-001',
+  ['https://www.w3.org/2018/credentials/v1'],
+  ['VerifiablePresentation'],
+  [createdCredential.jwt]
+);
+
+const verifiedPresentation = await connector.checkVerifiablePresentation(createdPresentation.jwt);
+
+const proof = await connector.createProof(
+  'controller-1',
+  `${identity}#signing-key`,
+  ProofTypes.DataIntegrityProof,
+  {
+    id: 'urn:example:document-1',
+    status: 'active'
+  }
+);
+
+const proofVerified = await connector.verifyProof(
+  {
+    id: 'urn:example:document-1',
+    status: 'active'
+  },
+  proof
+);
+
+console.log(verifiedCredential.revoked); // false
+console.log(verifiedPresentation.revoked); // false
+console.log(proofVerified); // true
+```
+
+## EntityStorageIdentityProfileConnector
+
+```typescript
+import { EntityStorageIdentityProfileConnector } from '@twin.org/identity-connector-entity-storage';
+
+interface PublicProfile {
+  displayName: string;
+  region: string;
+}
+
+interface PrivateProfile {
+  email: string;
+}
+
+const profileConnector = new EntityStorageIdentityProfileConnector<PublicProfile, PrivateProfile>({
+  profileEntityStorageType: 'identity-profile'
+});
+
+const className = profileConnector.className();
+const identity = 'did:entity-storage:0x1234abcd';
+
+await profileConnector.create(
+  identity,
+  {
+    displayName: 'Alice',
+    region: 'Manchester'
+  },
+  {
+    email: 'alice@example.org'
+  }
+);
+
+const profile = await profileConnector.get(identity, ['displayName'], ['email']);
+
+await profileConnector.update(
+  identity,
+  {
+    displayName: 'Alice Doe',
+    region: 'Manchester'
+  },
+  {
+    email: 'alice.doe@example.org'
+  }
+);
+
+const profileList = await profileConnector.list(
+  [
+    {
+      propertyName: 'displayName',
+      propertyValue: 'Alice Doe'
+    }
+  ],
+  undefined,
+  ['displayName'],
+  ['email'],
+  undefined,
+  10
+);
+
+await profileConnector.remove(identity);
+
+console.log(className); // EntityStorageIdentityProfileConnector
+console.log(profile.publicProfile.displayName); // Alice
+console.log(profileList.items.length); // 1
+```
+
+## EntityStorageIdentityResolverConnector
+
+```typescript
+import { EntityStorageIdentityResolverConnector } from '@twin.org/identity-connector-entity-storage';
+
+const resolverConnector = new EntityStorageIdentityResolverConnector({
+  didDocumentEntityStorageType: 'identity-document',
+  vaultConnectorType: 'vault'
+});
+
+const className = resolverConnector.className();
+const didDocument = await resolverConnector.resolveDocument('did:entity-storage:0x1234abcd');
+
+console.log(className); // EntityStorageIdentityResolverConnector
+console.log(didDocument.id); // did:entity-storage:0x1234abcd
+```
+
+## IdentityDocument
+
+```typescript
+import { IdentityDocument } from '@twin.org/identity-connector-entity-storage';
+
+const identityDocument = new IdentityDocument();
+identityDocument.id = 'did:entity-storage:0x1234abcd';
+identityDocument.document = {
+  id: 'did:entity-storage:0x1234abcd'
+};
+identityDocument.signature = 'MEYCIQCyExampleSignature';
+identityDocument.controller = 'controller-1';
+
+console.log(identityDocument.id); // did:entity-storage:0x1234abcd
+```
+
+## IdentityProfile
+
+```typescript
+import { IdentityProfile } from '@twin.org/identity-connector-entity-storage';
+
+const identityProfile = new IdentityProfile();
+identityProfile.identity = 'did:entity-storage:0x1234abcd';
+identityProfile.publicProfile = {
+  displayName: 'Alice'
+};
+identityProfile.privateProfile = {
+  email: 'alice@example.org'
+};
+
+console.log(identityProfile.identity); // did:entity-storage:0x1234abcd
+```

package/docs/reference/classes/EntityStorageIdentityConnector.md

@@ -28,7 +28,7 @@ The options for the identity connector.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -36,7 +36,7 @@ Runtime name for the class.
 
 ***
 
-### NAMESPACE
+### NAMESPACE {#namespace}
 
 > `readonly` `static` **NAMESPACE**: `string` = `"entity-storage"`
 
@@ -44,7 +44,7 @@ The namespace supported by the identity connector.
 
 ## Methods
 
-### className()
+### className() {#classname}
 
 > **className**(): `string`
 
@@ -62,7 +62,7 @@ The class name of the component.
 
 ***
 
-### createDocument()
+### createDocument() {#createdocument}
 
 > **createDocument**(`controller`): `Promise`\<`IDidDocument`\>
 
@@ -88,7 +88,7 @@ The created document.
 
 ***
 
-### removeDocument()
+### removeDocument() {#removedocument}
 
 > **removeDocument**(`controller`, `documentId`): `Promise`\<`void`\>
 
@@ -112,7 +112,7 @@ The id of the document to remove.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the document has been removed.
 
 #### Implementation of
 
@@ -120,7 +120,7 @@ Nothing.
 
 ***
 
-### addVerificationMethod()
+### addVerificationMethod() {#addverificationmethod}
 
 > **addVerificationMethod**(`controller`, `documentId`, `verificationMethodType`, `verificationMethodId?`): `Promise`\<`IDidDocumentVerificationMethod`\>
 
@@ -172,7 +172,7 @@ NotSupportedError if the platform does not support multiple keys.
 
 ***
 
-### removeVerificationMethod()
+### removeVerificationMethod() {#removeverificationmethod}
 
 > **removeVerificationMethod**(`controller`, `verificationMethodId`): `Promise`\<`void`\>
 
@@ -196,7 +196,7 @@ The id of the verification method.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the verification method has been removed.
 
 #### Throws
 
@@ -212,7 +212,7 @@ NotSupportedError if the platform does not support multiple revocable keys.
 
 ***
 
-### addService()
+### addService() {#addservice}
 
 > **addService**(`controller`, `documentId`, `serviceId`, `serviceType`, `serviceEndpoint`): `Promise`\<`IDidService`\>
 
@@ -240,15 +240,15 @@ The id of the service.
 
 ##### serviceType
 
-The type of the service.
+`string` \| `string`[]
 
-`string` | `string`[]
+The type of the service.
 
 ##### serviceEndpoint
 
-The endpoint for the service.
+`string` \| `string`[]
 
-`string` | `string`[]
+The endpoint for the service.
 
 #### Returns
 
@@ -266,7 +266,7 @@ NotFoundError if the id can not be resolved.
 
 ***
 
-### removeService()
+### removeService() {#removeservice}
 
 > **removeService**(`controller`, `serviceId`): `Promise`\<`void`\>
 
@@ -290,7 +290,7 @@ The id of the service.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the service has been removed.
 
 #### Throws
 
@@ -302,7 +302,101 @@ NotFoundError if the id can not be resolved.
 
 ***
 
-### createVerifiableCredential()
+### addAlsoKnownAs() {#addalsoknownas}
+
+> **addAlsoKnownAs**(`controller`, `documentId`, `alias`): `Promise`\<`void`\>
+
+Add an alias to the alsoKnownAs property on the document.
+If the alias is already present the operation is a no-op.
+
+#### Parameters
+
+##### controller
+
+`string`
+
+The controller of the identity who can make changes.
+
+##### documentId
+
+`string`
+
+The id of the document to update.
+
+##### alias
+
+`string`
+
+The alias to add. Must be a Url or Urn (typically another DID).
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the alias has been added.
+
+#### Throws
+
+GeneralError if the alias is not a Url or Urn.
+
+#### Throws
+
+NotFoundError if the id can not be resolved.
+
+#### Implementation of
+
+`IIdentityConnector.addAlsoKnownAs`
+
+***
+
+### removeAlsoKnownAs() {#removealsoknownas}
+
+> **removeAlsoKnownAs**(`controller`, `documentId`, `alias`): `Promise`\<`void`\>
+
+Remove an alias from the alsoKnownAs property on the document.
+If the alias is not present the operation is a no-op.
+
+#### Parameters
+
+##### controller
+
+`string`
+
+The controller of the identity who can make changes.
+
+##### documentId
+
+`string`
+
+The id of the document to update.
+
+##### alias
+
+`string`
+
+The alias to remove. Must be a Url or Urn.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the alias has been removed.
+
+#### Throws
+
+GeneralError if the alias is not a Url or Urn.
+
+#### Throws
+
+NotFoundError if the id can not be resolved.
+
+#### Implementation of
+
+`IIdentityConnector.removeAlsoKnownAs`
+
+***
+
+### createVerifiableCredential() {#createverifiablecredential}
 
 > **createVerifiableCredential**(`controller`, `verificationMethodId`, `id`, `subject`, `options?`): `Promise`\<\{ `verifiableCredential`: `IDidVerifiableCredentialV1`; `jwt`: `string`; \}\>
 
@@ -324,9 +418,9 @@ The verification method id to use.
 
 ##### id
 
-The id of the credential.
+`string` \| `undefined`
 
-`string` | `undefined`
+The id of the credential.
 
 ##### subject
 
@@ -350,6 +444,18 @@ The bitmap revocation index of the credential, if undefined will not have revoca
 
 The date the verifiable credential is valid until.
 
+###### jwtHeaderFields?
+
+\{\[`id`: `string`\]: `string`; \}
+
+Additional fields to add to the JWT header.
+
+###### jwtPayloadFields?
+
+\{\[`id`: `string`\]: `string`; \}
+
+Additional fields to add to the JWT payload.
+
 #### Returns
 
 `Promise`\<\{ `verifiableCredential`: `IDidVerifiableCredentialV1`; `jwt`: `string`; \}\>
@@ -366,23 +472,23 @@ NotFoundError if the id can not be resolved.
 
 ***
 
-### checkVerifiableCredential()
+### checkVerifiableCredential() {#checkverifiablecredential}
 
-> **checkVerifiableCredential**(`credentialJwt`): `Promise`\<\{ `revoked`: `boolean`; `verifiableCredential?`: `IDidVerifiableCredentialV1`; \}\>
+> **checkVerifiableCredential**(`credential`): `Promise`\<\{ `revoked`: `boolean`; `verifiableCredential?`: `IDidVerifiableCredential`; \}\>
 
 Check a verifiable credential is valid.
 
 #### Parameters
 
-##### credentialJwt
+##### credential
 
-`string`
+`string` \| `IDidVerifiableCredential`
 
 The credential to verify.
 
 #### Returns
 
-`Promise`\<\{ `revoked`: `boolean`; `verifiableCredential?`: `IDidVerifiableCredentialV1`; \}\>
+`Promise`\<\{ `revoked`: `boolean`; `verifiableCredential?`: `IDidVerifiableCredential`; \}\>
 
 The credential stored in the jwt and the revocation status.
 
@@ -392,7 +498,7 @@ The credential stored in the jwt and the revocation status.
 
 ***
 
-### revokeVerifiableCredentials()
+### revokeVerifiableCredentials() {#revokeverifiablecredentials}
 
 > **revokeVerifiableCredentials**(`controller`, `issuerDocumentId`, `credentialIndices`): `Promise`\<`void`\>
 
@@ -422,7 +528,7 @@ The revocation bitmap index or indices to revoke.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the credentials have been revoked.
 
 #### Implementation of
 
@@ -430,7 +536,7 @@ Nothing.
 
 ***
 
-### unrevokeVerifiableCredentials()
+### unrevokeVerifiableCredentials() {#unrevokeverifiablecredentials}
 
 > **unrevokeVerifiableCredentials**(`controller`, `issuerDocumentId`, `credentialIndices`): `Promise`\<`void`\>
 
@@ -460,7 +566,7 @@ The revocation bitmap index or indices to un revoke.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the credentials have been unrevoked.
 
 #### Implementation of
 
@@ -468,9 +574,9 @@ Nothing.
 
 ***
 
-### createVerifiablePresentation()
+### createVerifiablePresentation() {#createverifiablepresentation}
 
-> **createVerifiablePresentation**(`controller`, `verificationMethodId`, `presentationId`, `contexts`, `types`, `verifiableCredentials`, `expiresInMinutes?`): `Promise`\<\{ `verifiablePresentation`: `IDidVerifiablePresentationV1`; `jwt`: `string`; \}\>
+> **createVerifiablePresentation**(`controller`, `verificationMethodId`, `presentationId`, `contexts`, `types`, `verifiableCredentials`, `options?`): `Promise`\<\{ `verifiablePresentation`: `IDidVerifiablePresentationV1`; `jwt`: `string`; \}\>
 
 Create a verifiable presentation from the supplied verifiable credentials.
 
@@ -490,21 +596,21 @@ The method to associate with the presentation.
 
 ##### presentationId
 
-The id of the presentation.
+`string` \| `undefined`
 
-`string` | `undefined`
+The id of the presentation.
 
 ##### contexts
 
-The contexts for the data stored in the verifiable credential.
+`IJsonLdContextDefinitionRoot` \| `undefined`
 
-`IJsonLdContextDefinitionRoot` | `undefined`
+The contexts for the data stored in the verifiable credential.
 
 ##### types
 
-The types for the data stored in the verifiable credential.
+`string` \| `string`[] \| `undefined`
 
-`string` | `string`[] | `undefined`
+The types for the data stored in the verifiable credential.
 
 ##### verifiableCredentials
 
@@ -512,11 +618,27 @@ The types for the data stored in the verifiable credential.
 
 The credentials to use for creating the presentation in jwt format.
 
-##### expiresInMinutes?
+##### options?
 
-`number`
+Additional options for creating the verifiable presentation.
+
+###### expirationDate?
+
+`Date`
+
+The date the verifiable presentation is valid until.
+
+###### jwtHeaderFields?
+
+\{\[`id`: `string`\]: `string`; \}
+
+Additional fields to add to the JWT header.
+
+###### jwtPayloadFields?
+
+\{\[`id`: `string`\]: `string`; \}
 
-The time in minutes for the presentation to expire.
+Additional fields to add to the JWT payload.
 
 #### Returns
 
@@ -534,17 +656,17 @@ NotFoundError if the id can not be resolved.
 
 ***
 
-### checkVerifiablePresentation()
+### checkVerifiablePresentation() {#checkverifiablepresentation}
 
-> **checkVerifiablePresentation**(`presentationJwt`): `Promise`\<\{ `revoked`: `boolean`; `verifiablePresentation?`: `IDidVerifiablePresentationV1`; `issuers?`: `IDidDocument`[]; \}\>
+> **checkVerifiablePresentation**(`presentation`): `Promise`\<\{ `revoked`: `boolean`; `verifiablePresentation?`: `IDidVerifiablePresentationV1`; `issuers?`: `IDidDocument`[]; \}\>
 
 Check a verifiable presentation is valid.
 
 #### Parameters
 
-##### presentationJwt
+##### presentation
 
-`string`
+`string` \| `IDidVerifiablePresentation`
 
 The presentation to verify.
 
@@ -560,11 +682,13 @@ The presentation stored in the jwt and the revocation status.
 
 ***
 
-### createProof()
+### createProof() {#createproof}
 
 > **createProof**(`controller`, `verificationMethodId`, `proofType`, `unsecureDocument`): `Promise`\<`IProof`\>
 
 Create a proof for arbitrary data with the specified verification method.
+This method uses async signing to ensure the private key never leaves the vault,
+with algorithm validation to ensure key type compatibility.
 
 #### Parameters
 
@@ -598,13 +722,21 @@ The unsecure document to create the proof for.
 
 The proof.
 
+#### Throws
+
+NotFoundError if the identity or method is not found.
+
+#### Throws
+
+GeneralError if algorithm doesn't match key type or proof creation fails.
+
 #### Implementation of
 
 `IIdentityConnector.createProof`
 
 ***
 
-### verifyProof()
+### verifyProof() {#verifyproof}
 
 > **verifyProof**(`document`, `proof`): `Promise`\<`boolean`\>