@twin.org/identity-models 0.0.3-next.2 → 0.0.3-next.21

package/docs/examples.md

@@ -1 +1,157 @@
-# @twin.org/identity-service-models - Examples
+# Identity Models Examples
+
+These examples focus on building and validating DID identifiers, extracting data from DID documents, and verifying signed materials.
+
+## DocumentHelper
+
+```typescript
+import { DocumentHelper } from '@twin.org/identity-models';
+
+const parsed = DocumentHelper.parseId('did:iota:tst:0x1234abcd#key-1');
+
+console.log(parsed.id); // did:iota:tst:0x1234abcd
+console.log(parsed.fragment); // key-1
+```
+
+```typescript
+import { DocumentHelper } from '@twin.org/identity-models';
+import { DidVerificationMethodType, type IDidDocument } from '@twin.org/standards-w3c-did';
+
+const didDocument: IDidDocument = {
+  id: 'did:iota:tst:0x1234abcd',
+  verificationMethod: [
+    {
+      id: 'did:iota:tst:0x1234abcd#key-1',
+      controller: 'did:iota:tst:0x1234abcd',
+      type: 'JsonWebKey',
+      publicKeyJwk: {
+        kty: 'OKP',
+        crv: 'Ed25519',
+        x: 'S4e4WQ9Hj1et0eS2e0_ExampleBase64Url'
+      }
+    }
+  ]
+};
+
+const fullVerificationMethodId = DocumentHelper.joinId(didDocument.id, 'key-1');
+const verificationMethod = DocumentHelper.getVerificationMethod(
+  didDocument,
+  fullVerificationMethodId,
+  DidVerificationMethodType.VerificationMethod
+);
+const publicJwk = DocumentHelper.getJwk(
+  didDocument,
+  fullVerificationMethodId,
+  DidVerificationMethodType.VerificationMethod
+);
+
+console.log(verificationMethod.id); // did:iota:tst:0x1234abcd#key-1
+console.log(publicJwk.crv); // Ed25519
+```
+
+## DidContextIdHandler
+
+```typescript
+import { DidContextIdHandler } from '@twin.org/identity-models';
+
+const contextIdHandler = new DidContextIdHandler();
+
+const className = contextIdHandler.className();
+const shortened = contextIdHandler.short('did:iota:tst:0x8f2f0d7a5c4b3a2f1e0d9c8b7a6f5e4d');
+contextIdHandler.guard('did:iota:tst:0x8f2f0d7a5c4b3a2f1e0d9c8b7a6f5e4d');
+
+console.log(className); // DidContextIdHandler
+console.log(shortened); // jy8NelxLOi8eDZyLem9eTQ
+```
+
+## Did
+
+```typescript
+import { Did } from '@twin.org/identity-models';
+
+const parsedDid = Did.parse('did:iota:tst:0x1234abcd');
+Did.guard('ExampleWorkflow', 'issuerDid', 'did:iota:tst:0x1234abcd');
+
+console.log(parsedDid.method); // iota
+console.log(parsedDid.network); // tst
+console.log(parsedDid.id); // 0x1234abcd
+```
+
+## VerificationHelper
+
+```typescript
+import { VerificationHelper, type IIdentityResolverComponent } from '@twin.org/identity-models';
+
+const resolver: IIdentityResolverComponent = {
+  className: () => 'IdentityResolverService',
+  identityResolve: async (identity: string) => ({
+    id: identity,
+    verificationMethod: [
+      {
+        id: `${identity}#signing-key`,
+        controller: identity,
+        type: 'JsonWebKey',
+        publicKeyJwk: {
+          kty: 'OKP',
+          crv: 'Ed25519',
+          x: 'S4e4WQ9Hj1et0eS2e0_ExampleBase64Url'
+        }
+      }
+    ]
+  })
+};
+
+const jwt =
+  'eyJraWQiOiJkaWQ6aW90YTp0c3Q6MHgxMjM0YWJjZCNzaWduaW5nLWtleSIsImlzcyI6ImRpZDppb3RhOnRzdDoweDEyMzRhYmNkIiwiYWxnIjoiRWREU0EiLCJ0eXAiOiJKV1QifQ.eyJzdWIiOiJhbGljZSJ9.Q2hhbmdlTWVXaXRoUmVhbFNpZ25hdHVyZQ';
+
+const jwtVerification = await VerificationHelper.verifyJwt(resolver, jwt);
+
+console.log(typeof jwtVerification.payload.sub); // string
+```
+
+```typescript
+import { VerificationHelper, type IIdentityResolverComponent } from '@twin.org/identity-models';
+import type { IJsonLdNodeObject } from '@twin.org/data-json-ld';
+
+const resolver: IIdentityResolverComponent = {
+  className: () => 'IdentityResolverService',
+  identityResolve: async (identity: string) => ({
+    id: identity,
+    verificationMethod: [
+      {
+        id: `${identity}#signing-key`,
+        controller: identity,
+        type: 'JsonWebKey',
+        publicKeyJwk: {
+          kty: 'OKP',
+          crv: 'Ed25519',
+          x: 'S4e4WQ9Hj1et0eS2e0_ExampleBase64Url'
+        }
+      }
+    ]
+  })
+};
+
+const verifiableCredential: IJsonLdNodeObject = {
+  '@context': ['https://www.w3.org/2018/credentials/v1'],
+  type: ['VerifiableCredential'],
+  issuer: 'did:iota:tst:0x1234abcd',
+  issuanceDate: '2026-03-10T00:00:00.000Z',
+  credentialSubject: {
+    id: 'did:iota:tst:0x5678efab',
+    role: 'Developer'
+  },
+  proof: {
+    type: 'DataIntegrityProof',
+    verificationMethod: 'did:iota:tst:0x1234abcd#signing-key',
+    cryptosuite: 'eddsa-jcs-2022',
+    created: '2026-03-10T00:00:00.000Z',
+    proofPurpose: 'assertionMethod',
+    proofValue: 'z4ExampleProofValue'
+  }
+};
+
+const verified = await VerificationHelper.verifyProof(resolver, verifiableCredential);
+
+console.log(verified); // true
+```

package/docs/reference/classes/Did.md

@@ -14,7 +14,7 @@ Helper methods for Ids.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -22,7 +22,7 @@ Runtime name for the class.
 
 ## Methods
 
-### parse()
+### parse() {#parse}
 
 > `static` **parse**(`id`): `object`
 
@@ -48,7 +48,7 @@ The parsed id.
 
 ##### network?
 
-> `optional` **network**: `string`
+> `optional` **network?**: `string`
 
 ##### id
 
@@ -60,7 +60,7 @@ GeneralError if the id is not valid.
 
 ***
 
-### guard()
+### guard() {#guard}
 
 > `static` **guard**(`source`, `property`, `value`): `asserts value is string`
 

package/docs/reference/classes/DidContextIdHandler.md

@@ -18,7 +18,7 @@ Context Id handler for testing as a DID.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -26,7 +26,25 @@ Runtime name for the class.
 
 ## Methods
 
-### short()
+### className() {#classname}
+
+> **className**(): `string`
+
+The class name of the component.
+
+#### Returns
+
+`string`
+
+The class name.
+
+#### Implementation of
+
+`IContextIdHandler.className`
+
+***
+
+### short() {#short}
 
 > **short**(`value`): `string`
 
@@ -52,7 +70,7 @@ Short form string.
 
 ***
 
-### guard()
+### guard() {#guard}
 
 > **guard**(`value`): `void`
 

package/docs/reference/classes/DocumentHelper.md

@@ -14,7 +14,7 @@ Helper methods for documents.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -22,7 +22,7 @@ Runtime name for the class.
 
 ## Methods
 
-### parseId()
+### parseId() {#parseid}
 
 > `static` **parseId**(`documentId`): `object`
 
@@ -52,7 +52,7 @@ The parsed document id.
 
 ***
 
-### joinId()
+### joinId() {#joinid}
 
 > `static` **joinId**(`documentId`, `fragment?`): `string`
 
@@ -80,7 +80,7 @@ The full id.
 
 ***
 
-### getVerificationMethod()
+### getVerificationMethod() {#getverificationmethod}
 
 > `static` **getVerificationMethod**(`didDocument`, `methodName`, `methodType?`): `IDidDocumentVerificationMethod`
 
@@ -118,7 +118,7 @@ Error if the method is not found.
 
 ***
 
-### getJwk()
+### getJwk() {#getjwk}
 
 > `static` **getJwk**(`didDocument`, `methodName`, `methodType?`): `JWK`
 

package/docs/reference/classes/VerificationHelper.md

@@ -14,7 +14,7 @@ Helper methods for verification.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -22,7 +22,7 @@ Runtime name for the class.
 
 ## Methods
 
-### verifyJwt()
+### verifyJwt() {#verifyjwt}
 
 > `static` **verifyJwt**\<`T`, `U`\>(`resolver`, `jwt`): `Promise`\<\{ `header`: `T`; `payload`: `U`; \}\>
 
@@ -60,7 +60,7 @@ The decoded payload.
 
 ***
 
-### verifyProof()
+### verifyProof() {#verifyproof}
 
 > `static` **verifyProof**(`resolver`, `secureDocument`): `Promise`\<`boolean`\>
 

package/docs/reference/index.md

@@ -15,6 +15,8 @@
 - [IIdentityProfileConnector](interfaces/IIdentityProfileConnector.md)
 - [IIdentityResolverComponent](interfaces/IIdentityResolverComponent.md)
 - [IIdentityResolverConnector](interfaces/IIdentityResolverConnector.md)
+- [IIdentityAlsoKnownAsCreateRequest](interfaces/IIdentityAlsoKnownAsCreateRequest.md)
+- [IIdentityAlsoKnownAsRemoveRequest](interfaces/IIdentityAlsoKnownAsRemoveRequest.md)
 - [IIdentityCreateRequest](interfaces/IIdentityCreateRequest.md)
 - [IIdentityCreateResponse](interfaces/IIdentityCreateResponse.md)
 - [IIdentityProofCreateRequest](interfaces/IIdentityProofCreateRequest.md)
@@ -29,10 +31,12 @@
 - [IIdentityVerifiableCredentialCreateResponse](interfaces/IIdentityVerifiableCredentialCreateResponse.md)
 - [IIdentityVerifiableCredentialRevokeRequest](interfaces/IIdentityVerifiableCredentialRevokeRequest.md)
 - [IIdentityVerifiableCredentialUnrevokeRequest](interfaces/IIdentityVerifiableCredentialUnrevokeRequest.md)
+- [IIdentityVerifiableCredentialVerifyDocumentRequest](interfaces/IIdentityVerifiableCredentialVerifyDocumentRequest.md)
 - [IIdentityVerifiableCredentialVerifyRequest](interfaces/IIdentityVerifiableCredentialVerifyRequest.md)
 - [IIdentityVerifiableCredentialVerifyResponse](interfaces/IIdentityVerifiableCredentialVerifyResponse.md)
 - [IIdentityVerifiablePresentationCreateRequest](interfaces/IIdentityVerifiablePresentationCreateRequest.md)
 - [IIdentityVerifiablePresentationCreateResponse](interfaces/IIdentityVerifiablePresentationCreateResponse.md)
+- [IIdentityVerifiablePresentationVerifyDocumentRequest](interfaces/IIdentityVerifiablePresentationVerifyDocumentRequest.md)
 - [IIdentityVerifiablePresentationVerifyRequest](interfaces/IIdentityVerifiablePresentationVerifyRequest.md)
 - [IIdentityVerifiablePresentationVerifyResponse](interfaces/IIdentityVerifiablePresentationVerifyResponse.md)
 - [IIdentityVerificationMethodCreateRequest](interfaces/IIdentityVerificationMethodCreateRequest.md)

package/docs/reference/interfaces/IIdentityAlsoKnownAsCreateRequest.md

@@ -0,0 +1,31 @@
+# Interface: IIdentityAlsoKnownAsCreateRequest
+
+Request to create an alias for an identity.
+
+## Properties
+
+### pathParams {#pathparams}
+
+> **pathParams**: `object`
+
+The path parameters.
+
+#### identity
+
+> **identity**: `string`
+
+The identity to create the alias for.
+
+***
+
+### body {#body}
+
+> **body**: `object`
+
+The data for the request.
+
+#### alias
+
+> **alias**: `string`
+
+The alias to create for the identity.

package/docs/reference/interfaces/IIdentityAlsoKnownAsRemoveRequest.md

@@ -0,0 +1,23 @@
+# Interface: IIdentityAlsoKnownAsRemoveRequest
+
+Request to remove an alias from an identity.
+
+## Properties
+
+### pathParams {#pathparams}
+
+> **pathParams**: `object`
+
+The path parameters.
+
+#### identity
+
+> **identity**: `string`
+
+The identity to remove the alias from.
+
+#### alias
+
+> **alias**: `string`
+
+The alias to remove.

package/docs/reference/interfaces/IIdentityComponent.md

@@ -8,7 +8,7 @@ Interface describing a contract which provides identity operations.
 
 ## Methods
 
-### identityCreate()
+### identityCreate() {#identitycreate}
 
 > **identityCreate**(`namespace?`, `controller?`): `Promise`\<`IDidDocument`\>
 
@@ -36,7 +36,7 @@ The created identity document.
 
 ***
 
-### identityRemove()
+### identityRemove() {#identityremove}
 
 > **identityRemove**(`identity`, `controller?`): `Promise`\<`void`\>
 
@@ -64,7 +64,7 @@ Nothing.
 
 ***
 
-### verificationMethodCreate()
+### verificationMethodCreate() {#verificationmethodcreate}
 
 > **verificationMethodCreate**(`identity`, `verificationMethodType`, `verificationMethodId?`, `controller?`): `Promise`\<`IDidDocumentVerificationMethod`\>
 
@@ -112,7 +112,7 @@ NotSupportedError if the platform does not support multiple keys.
 
 ***
 
-### verificationMethodRemove()
+### verificationMethodRemove() {#verificationmethodremove}
 
 > **verificationMethodRemove**(`verificationMethodId`, `controller?`): `Promise`\<`void`\>
 
@@ -148,7 +148,7 @@ NotSupportedError if the platform does not support multiple revocable keys.
 
 ***
 
-### serviceCreate()
+### serviceCreate() {#servicecreate}
 
 > **serviceCreate**(`identity`, `serviceId`, `serviceType`, `serviceEndpoint`, `controller?`): `Promise`\<`IDidService`\>
 
@@ -170,15 +170,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.
 
 ##### controller?
 
@@ -198,7 +198,7 @@ NotFoundError if the id can not be resolved.
 
 ***
 
-### serviceRemove()
+### serviceRemove() {#serviceremove}
 
 > **serviceRemove**(`serviceId`, `controller?`): `Promise`\<`void`\>
 
@@ -230,7 +230,93 @@ NotFoundError if the id can not be resolved.
 
 ***
 
-### verifiableCredentialCreate()
+### alsoKnownAsAdd() {#alsoknownasadd}
+
+> **alsoKnownAsAdd**(`documentId`, `alias`, `controller?`): `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
+
+##### documentId
+
+`string`
+
+The id of the document to update.
+
+##### alias
+
+`string`
+
+The alias to add. Must be a Url or Urn (typically another DID).
+
+##### controller?
+
+`string`
+
+The controller of the identity who can make changes.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Throws
+
+GeneralError if the alias is not a Url or Urn.
+
+#### Throws
+
+NotFoundError if the id can not be resolved.
+
+***
+
+### alsoKnownAsRemove() {#alsoknownasremove}
+
+> **alsoKnownAsRemove**(`documentId`, `alias`, `controller?`): `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
+
+##### documentId
+
+`string`
+
+The id of the document to update.
+
+##### alias
+
+`string`
+
+The alias to remove. Must be a Url or Urn.
+
+##### controller?
+
+`string`
+
+The controller of the identity who can make changes.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Throws
+
+GeneralError if the alias is not a Url or Urn.
+
+#### Throws
+
+NotFoundError if the id can not be resolved.
+
+***
+
+### verifiableCredentialCreate() {#verifiablecredentialcreate}
 
 > **verifiableCredentialCreate**(`verificationMethodId`, `id`, `subject`, `options?`, `controller?`): `Promise`\<\{ `verifiableCredential`: `IDidVerifiableCredential`; `jwt`: `string`; \}\>
 
@@ -246,9 +332,9 @@ The verification method id to use.
 
 ##### id
 
-The id of the credential.
+`string` \| `undefined`
 
-`string` | `undefined`
+The id of the credential.
 
 ##### subject
 
@@ -290,17 +376,17 @@ NotFoundError if the id can not be resolved.
 
 ***
 
-### verifiableCredentialVerify()
+### verifiableCredentialVerify() {#verifiablecredentialverify}
 
-> **verifiableCredentialVerify**(`credentialJwt`): `Promise`\<\{ `revoked`: `boolean`; `verifiableCredential?`: `IDidVerifiableCredential`; \}\>
+> **verifiableCredentialVerify**(`credential`): `Promise`\<\{ `revoked`: `boolean`; `verifiableCredential?`: `IDidVerifiableCredential`; \}\>
 
 Verify a verifiable credential is valid.
 
 #### Parameters
 
-##### credentialJwt
+##### credential
 
-`string`
+`string` \| `IDidVerifiableCredential`
 
 The credential to verify.
 
@@ -312,7 +398,7 @@ The credential stored in the jwt and the revocation status.
 
 ***
 
-### verifiableCredentialRevoke()
+### verifiableCredentialRevoke() {#verifiablecredentialrevoke}
 
 > **verifiableCredentialRevoke**(`issuerId`, `credentialIndex`, `controller?`): `Promise`\<`void`\>
 
@@ -346,7 +432,7 @@ Nothing.
 
 ***
 
-### verifiableCredentialUnrevoke()
+### verifiableCredentialUnrevoke() {#verifiablecredentialunrevoke}
 
 > **verifiableCredentialUnrevoke**(`issuerId`, `credentialIndex`, `controller?`): `Promise`\<`void`\>
 
@@ -380,9 +466,9 @@ Nothing.
 
 ***
 
-### verifiablePresentationCreate()
+### verifiablePresentationCreate() {#verifiablepresentationcreate}
 
-> **verifiablePresentationCreate**(`verificationMethodId`, `presentationId`, `contexts`, `types`, `verifiableCredentials`, `expiresInMinutes?`, `controller?`): `Promise`\<\{ `verifiablePresentation`: `IDidVerifiablePresentation`; `jwt`: `string`; \}\>
+> **verifiablePresentationCreate**(`verificationMethodId`, `presentationId`, `contexts`, `types`, `verifiableCredentials`, `options?`, `controller?`): `Promise`\<\{ `verifiablePresentation`: `IDidVerifiablePresentation`; `jwt`: `string`; \}\>
 
 Create a verifiable presentation from the supplied verifiable credentials.
 
@@ -396,21 +482,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
 
@@ -418,11 +504,15 @@ 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.
 
-The time in minutes for the presentation to expire.
+###### expirationDate?
+
+`Date`
+
+The date the verifiable presentation is valid until.
 
 ##### controller?
 
@@ -442,17 +532,17 @@ NotFoundError if the id can not be resolved.
 
 ***
 
-### verifiablePresentationVerify()
+### verifiablePresentationVerify() {#verifiablepresentationverify}
 
-> **verifiablePresentationVerify**(`presentationJwt`): `Promise`\<\{ `revoked`: `boolean`; `verifiablePresentation?`: `IDidVerifiablePresentation`; `issuers?`: `IDidDocument`[]; \}\>
+> **verifiablePresentationVerify**(`presentation`): `Promise`\<\{ `revoked`: `boolean`; `verifiablePresentation?`: `IDidVerifiablePresentation`; `issuers?`: `IDidDocument`[]; \}\>
 
 Verify a verifiable presentation is valid.
 
 #### Parameters
 
-##### presentationJwt
+##### presentation
 
-`string`
+`string` \| `IDidVerifiablePresentation`
 
 The presentation to verify.
 
@@ -464,7 +554,7 @@ The presentation stored in the jwt and the revocation status.
 
 ***
 
-### proofCreate()
+### proofCreate() {#proofcreate}
 
 > **proofCreate**(`verificationMethodId`, `proofType`, `unsecureDocument`, `controller?`): `Promise`\<`IProof`\>
 
@@ -504,7 +594,7 @@ The proof.
 
 ***
 
-### proofVerify()
+### proofVerify() {#proofverify}
 
 > **proofVerify**(`document`, `proof`): `Promise`\<`boolean`\>