@twin.org/identity-connector-entity-storage 0.0.3-next.3 → 0.0.3-next.30

package/README.md

@@ -1,6 +1,6 @@
-# TWIN Identity Connector Entity Storage
+# TWIN Identity
 
-Identity connector implementation using entity storage.
+The identity-connector-entity-storage package provides an entity storage backed connector for identity workflows, enabling reliable persistence and retrieval of identity records. It supports implementations that need consistent storage semantics while staying aligned with shared contracts across the ecosystem.
 
 ## Installation
 

package/dist/es/entityStorageIdentityConnector.js

@@ -1,10 +1,10 @@
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
-import { BaseError, BitString, Coerce, Compression, CompressionType, Converter, GeneralError, Guards, Is, JsonHelper, NotFoundError, ObjectHelper, RandomHelper } from "@twin.org/core";
-import { JsonLdProcessor } from "@twin.org/data-json-ld";
+import { ArrayHelper, BaseError, BitString, Coerce, Compression, CompressionType, Converter, GeneralError, Guards, Is, JsonHelper, NotFoundError, ObjectHelper, RandomHelper, Url, Urn } from "@twin.org/core";
+import { JsonLdHelper, JsonLdProcessor } from "@twin.org/data-json-ld";
 import { EntityStorageConnectorFactory } from "@twin.org/entity-storage-models";
 import { DocumentHelper } from "@twin.org/identity-models";
-import { DidContexts, DidTypes, DidVerificationMethodType, ProofHelper, ProofTypes } from "@twin.org/standards-w3c-did";
+import { DidContexts, DidTypes, DidVerificationMethodType, JwsAlgorithms, ProofHelper, ProofTypes } from "@twin.org/standards-w3c-did";
 import { VaultConnectorFactory, VaultConnectorHelper, VaultKeyType } from "@twin.org/vault-models";
 import { Jwk, Jwt } from "@twin.org/web";
 /**
@@ -147,9 +147,8 @@ export class EntityStorageIdentityConnector {
             if (Is.stringValue(verificationMethodId)) {
                 // If there is a verification method id, we will try to get the key from the vault.
                 try {
-                    const defaultMethodId = `${controller}/${verificationMethodId}`;
                     // If there is an existing key, we will use it.
-                    const existingKey = await this._vaultConnector.getKey(defaultMethodId);
+                    const existingKey = await this._vaultConnector.getKey(EntityStorageIdentityConnector.buildVaultKey(didDocument.id, verificationMethodId));
                     methodKeyPublic = existingKey.publicKey;
                 }
                 catch { }
@@ -352,6 +351,81 @@ export class EntityStorageIdentityConnector {
             throw new GeneralError(EntityStorageIdentityConnector.CLASS_NAME, "removeServiceFailed", undefined, error);
         }
     }
+    /**
+     * Add an alias to the alsoKnownAs property on the document.
+     * If the alias is already present the operation is a no-op.
+     * @param controller The controller of the identity who can make changes.
+     * @param documentId The id of the document to update.
+     * @param alias The alias to add. Must be a Url or Urn (typically another DID).
+     * @returns Nothing.
+     * @throws GeneralError if the alias is not a Url or Urn.
+     * @throws NotFoundError if the id can not be resolved.
+     */
+    async addAlsoKnownAs(controller, documentId, alias) {
+        Guards.stringValue(EntityStorageIdentityConnector.CLASS_NAME, "controller", controller);
+        Guards.stringValue(EntityStorageIdentityConnector.CLASS_NAME, "documentId", documentId);
+        Guards.stringValue(EntityStorageIdentityConnector.CLASS_NAME, "alias", alias);
+        if (!Url.tryParseExact(alias) && !Urn.tryParseExact(alias)) {
+            throw new GeneralError(EntityStorageIdentityConnector.CLASS_NAME, "invalidAlias", { alias });
+        }
+        try {
+            const didIdentityDocument = await this._didDocumentEntityStorage.get(documentId);
+            if (Is.undefined(didIdentityDocument)) {
+                throw new NotFoundError(EntityStorageIdentityConnector.CLASS_NAME, "documentNotFound", documentId);
+            }
+            await EntityStorageIdentityConnector.verifyDocument(didIdentityDocument, this._vaultConnector);
+            const didDocument = didIdentityDocument.document;
+            const existing = Is.array(didDocument.alsoKnownAs) ? didDocument.alsoKnownAs : [];
+            if (existing.includes(alias)) {
+                return;
+            }
+            didDocument.alsoKnownAs = [...existing, alias];
+            await this.updateDocument(controller, didDocument);
+        }
+        catch (error) {
+            throw new GeneralError(EntityStorageIdentityConnector.CLASS_NAME, "addAlsoKnownAsFailed", undefined, error);
+        }
+    }
+    /**
+     * Remove an alias from the alsoKnownAs property on the document.
+     * If the alias is not present the operation is a no-op.
+     * @param controller The controller of the identity who can make changes.
+     * @param documentId The id of the document to update.
+     * @param alias The alias to remove. Must be a Url or Urn.
+     * @returns Nothing.
+     * @throws GeneralError if the alias is not a Url or Urn.
+     * @throws NotFoundError if the id can not be resolved.
+     */
+    async removeAlsoKnownAs(controller, documentId, alias) {
+        Guards.stringValue(EntityStorageIdentityConnector.CLASS_NAME, "controller", controller);
+        Guards.stringValue(EntityStorageIdentityConnector.CLASS_NAME, "documentId", documentId);
+        Guards.stringValue(EntityStorageIdentityConnector.CLASS_NAME, "alias", alias);
+        if (!Url.tryParseExact(alias) && !Urn.tryParseExact(alias)) {
+            throw new GeneralError(EntityStorageIdentityConnector.CLASS_NAME, "invalidAlias", { alias });
+        }
+        try {
+            const didIdentityDocument = await this._didDocumentEntityStorage.get(documentId);
+            if (Is.undefined(didIdentityDocument)) {
+                throw new NotFoundError(EntityStorageIdentityConnector.CLASS_NAME, "documentNotFound", documentId);
+            }
+            await EntityStorageIdentityConnector.verifyDocument(didIdentityDocument, this._vaultConnector);
+            const didDocument = didIdentityDocument.document;
+            if (!Is.array(didDocument.alsoKnownAs) || !didDocument.alsoKnownAs.includes(alias)) {
+                return;
+            }
+            const filtered = didDocument.alsoKnownAs.filter(a => a !== alias);
+            if (filtered.length === 0) {
+                delete didDocument.alsoKnownAs;
+            }
+            else {
+                didDocument.alsoKnownAs = filtered;
+            }
+            await this.updateDocument(controller, didDocument);
+        }
+        catch (error) {
+            throw new GeneralError(EntityStorageIdentityConnector.CLASS_NAME, "removeAlsoKnownAsFailed", undefined, error);
+        }
+    }
     /**
      * Create a verifiable credential for a verification method.
      * @param controller The controller of the identity who can make changes.
@@ -361,6 +435,8 @@ export class EntityStorageIdentityConnector {
      * @param options Additional options for creating the verifiable credential.
      * @param options.revocationIndex The bitmap revocation index of the credential, if undefined will not have revocation status.
      * @param options.expirationDate The date the verifiable credential is valid until.
+     * @param options.jwtHeaderFields Additional fields to add to the JWT header.
+     * @param options.jwtPayloadFields Additional fields to add to the JWT payload.
      * @returns The created verifiable credential and its token.
      * @throws NotFoundError if the id can not be resolved.
      */
@@ -371,6 +447,9 @@ export class EntityStorageIdentityConnector {
         if (!Is.undefined(options?.revocationIndex)) {
             Guards.number(EntityStorageIdentityConnector.CLASS_NAME, "options.revocationIndex", options.revocationIndex);
         }
+        if (!Is.undefined(options?.expirationDate)) {
+            Guards.date(EntityStorageIdentityConnector.CLASS_NAME, "options.expirationDate", options.expirationDate);
+        }
         try {
             const idParts = DocumentHelper.parseId(verificationMethodId);
             if (Is.empty(idParts.fragment)) {
@@ -412,7 +491,8 @@ export class EntityStorageIdentityConnector {
                 finalTypes.push(credType);
             }
             const verifiableCredential = {
-                "@context": JsonLdProcessor.combineContexts(DidContexts.ContextVCv1, credContext),
+                "@context": (JsonLdProcessor.combineContexts(DidContexts.ContextVCv1, credContext) ??
+                    DidContexts.ContextVCv1),
                 id,
                 type: finalTypes,
                 credentialSubject: subjectClone,
@@ -432,9 +512,10 @@ export class EntityStorageIdentityConnector {
                     : undefined
             };
             const jwtHeader = {
+                ...options?.jwtHeaderFields,
                 kid: verificationDidMethod.id,
                 typ: "JWT",
-                alg: "EdDSA"
+                alg: JwsAlgorithms.EdDSA
             };
             const jwtVc = ObjectHelper.pick(ObjectHelper.clone(verifiableCredential), [
                 "@context",
@@ -442,6 +523,15 @@ export class EntityStorageIdentityConnector {
                 "credentialSubject",
                 "credentialStatus"
             ]);
+            // Add the proof to the VC after extracting the jwt data
+            // as the jwt does not include the proof
+            verifiableCredential.proof = await this.createProof(controller, verificationMethodId, ProofTypes.DataIntegrityProof, JsonLdHelper.toNodeObject(verifiableCredential));
+            // As we are adding the receipt to the data we update the JSON-LD context
+            const proofContext = verifiableCredential.proof["@context"];
+            if (!Is.empty(proofContext)) {
+                verifiableCredential["@context"] = (JsonLdProcessor.combineContexts(verifiableCredential["@context"], proofContext) ?? verifiableCredential["@context"]);
+                delete verifiableCredential.proof["@context"];
+            }
             if (Is.array(jwtVc.credentialSubject)) {
                 jwtVc.credentialSubject = jwtVc.credentialSubject.map(c => {
                     ObjectHelper.propertyDelete(c, "id");
@@ -452,12 +542,16 @@ export class EntityStorageIdentityConnector {
                 ObjectHelper.propertyDelete(jwtVc.credentialSubject, "id");
             }
             const jwtPayload = {
+                ...options?.jwtPayloadFields,
                 iss: idParts.id,
                 nbf: Math.floor(Date.now() / 1000),
                 jti: verifiableCredential.id,
                 sub: credId,
                 vc: jwtVc
             };
+            if (Is.date(options?.expirationDate)) {
+                jwtPayload.exp = Math.floor(options.expirationDate.getTime() / 1000);
+            }
             const signature = await Jwt.encodeWithSigner(jwtHeader, jwtPayload, async (header, payload) => VaultConnectorHelper.jwtSigner(this._vaultConnector, EntityStorageIdentityConnector.buildVaultKey(idParts.id, idParts.fragment ?? ""), header, payload));
             return {
                 verifiableCredential,
@@ -470,13 +564,23 @@ export class EntityStorageIdentityConnector {
     }
     /**
      * Check a verifiable credential is valid.
-     * @param credentialJwt The credential to verify.
+     * @param credential The credential to verify.
      * @returns The credential stored in the jwt and the revocation status.
      */
-    async checkVerifiableCredential(credentialJwt) {
-        Guards.stringValue(EntityStorageIdentityConnector.CLASS_NAME, "credentialJwt", credentialJwt);
+    async checkVerifiableCredential(credential) {
+        if (Is.object(credential)) {
+            Guards.objectValue(EntityStorageIdentityConnector.CLASS_NAME, "credential", credential);
+            Guards.objectValue(EntityStorageIdentityConnector.CLASS_NAME, "credential.proof", credential.proof);
+            const { proof, ...doc } = credential;
+            await this.verifyProof(JsonLdHelper.toNodeObject(doc), ArrayHelper.fromObjectOrArray(proof)[0]);
+            return {
+                revoked: false,
+                verifiableCredential: doc
+            };
+        }
+        Guards.stringValue(EntityStorageIdentityConnector.CLASS_NAME, "credential", credential);
         try {
-            const jwtDecoded = await Jwt.decode(credentialJwt);
+            const jwtDecoded = await Jwt.decode(credential);
             const jwtHeader = jwtDecoded.header;
             const jwtPayload = jwtDecoded.payload;
             const jwtSignature = jwtDecoded.signature;
@@ -511,7 +615,7 @@ export class EntityStorageIdentityConnector {
                     method: jwtHeader.kid
                 });
             }
-            await Jwt.verifySignature(credentialJwt, await Jwk.toCryptoKey(didMethod.publicKeyJwk));
+            await Jwt.verifySignature(credential, await Jwk.toCryptoKey(didMethod.publicKeyJwk));
             const verifiableCredential = jwtPayload.vc;
             if (Is.object(verifiableCredential)) {
                 if (Is.string(jwtPayload.jti)) {
@@ -641,11 +745,14 @@ export class EntityStorageIdentityConnector {
      * @param contexts The contexts for the data stored in the verifiable credential.
      * @param types The types for the data stored in the verifiable credential.
      * @param verifiableCredentials The credentials to use for creating the presentation in jwt format.
-     * @param expiresInMinutes The time in minutes for the presentation to expire.
+     * @param options Additional options for creating the verifiable presentation.
+     * @param options.expirationDate The date the verifiable presentation is valid until.
+     * @param options.jwtHeaderFields Additional fields to add to the JWT header.
+     * @param options.jwtPayloadFields Additional fields to add to the JWT payload.
      * @returns The created verifiable presentation and its token.
      * @throws NotFoundError if the id can not be resolved.
      */
-    async createVerifiablePresentation(controller, verificationMethodId, presentationId, contexts, types, verifiableCredentials, expiresInMinutes) {
+    async createVerifiablePresentation(controller, verificationMethodId, presentationId, contexts, types, verifiableCredentials, options) {
         Guards.stringValue(EntityStorageIdentityConnector.CLASS_NAME, "controller", controller);
         Guards.stringValue(EntityStorageIdentityConnector.CLASS_NAME, "verificationMethodId", verificationMethodId);
         if (Is.array(types)) {
@@ -655,8 +762,8 @@ export class EntityStorageIdentityConnector {
             Guards.stringValue(EntityStorageIdentityConnector.CLASS_NAME, "types", types);
         }
         Guards.arrayValue(EntityStorageIdentityConnector.CLASS_NAME, "verifiableCredentials", verifiableCredentials);
-        if (!Is.undefined(expiresInMinutes)) {
-            Guards.integer(EntityStorageIdentityConnector.CLASS_NAME, "expiresInMinutes", expiresInMinutes);
+        if (!Is.undefined(options?.expirationDate)) {
+            Guards.date(EntityStorageIdentityConnector.CLASS_NAME, "options.expirationDate", options.expirationDate);
         }
         try {
             const idParts = DocumentHelper.parseId(verificationMethodId);
@@ -694,31 +801,37 @@ export class EntityStorageIdentityConnector {
             else if (Is.stringValue(types)) {
                 finalTypes.push(types);
             }
+            const combinedContext = JsonLdProcessor.combineContexts(DidContexts.ContextVCv1, contexts) ??
+                DidContexts.ContextVCv1;
             const verifiablePresentation = {
-                "@context": JsonLdProcessor.combineContexts(DidContexts.ContextVCv1, contexts),
+                "@context": combinedContext,
                 id: presentationId,
                 type: finalTypes,
                 verifiableCredential: verifiableCredentials,
                 holder: idParts.id
             };
             const jwtHeader = {
+                ...options?.jwtHeaderFields,
                 kid: didMethod.id,
                 typ: "JWT",
-                alg: "EdDSA"
+                alg: JwsAlgorithms.EdDSA
             };
             const jwtVp = ObjectHelper.pick(ObjectHelper.clone(verifiablePresentation), [
                 "@context",
                 "type",
                 "verifiableCredential"
             ]);
+            // Add the proof to the VP after extracting the jwt data
+            // as the jwt does not include the proof
+            verifiablePresentation.proof = await this.createProof(controller, verificationMethodId, ProofTypes.DataIntegrityProof, JsonLdHelper.toNodeObject(verifiablePresentation));
             const jwtPayload = {
-                iss: idParts.id,
+                ...options?.jwtPayloadFields,
+                iss: verifiablePresentation.holder,
                 nbf: Math.floor(Date.now() / 1000),
                 vp: jwtVp
             };
-            if (Is.integer(expiresInMinutes)) {
-                const expiresInSeconds = expiresInMinutes * 60;
-                jwtPayload.exp = Math.floor(Date.now() / 1000) + expiresInSeconds;
+            if (Is.date(options?.expirationDate)) {
+                jwtPayload.exp = Math.floor(options.expirationDate.getTime() / 1000);
             }
             const signature = await Jwt.encodeWithSigner(jwtHeader, jwtPayload, async (header, payload) => VaultConnectorHelper.jwtSigner(this._vaultConnector, EntityStorageIdentityConnector.buildVaultKey(idParts.id, idParts.fragment ?? ""), header, payload));
             return {
@@ -732,11 +845,19 @@ export class EntityStorageIdentityConnector {
     }
     /**
      * Check a verifiable presentation is valid.
-     * @param presentationJwt The presentation to verify.
+     * @param presentation The presentation to verify.
      * @returns The presentation stored in the jwt and the revocation status.
      */
-    async checkVerifiablePresentation(presentationJwt) {
-        Guards.stringValue(EntityStorageIdentityConnector.CLASS_NAME, "presentationJwt", presentationJwt);
+    async checkVerifiablePresentation(presentation) {
+        if (Is.object(presentation)) {
+            const { proof, ...doc } = presentation;
+            const proofEntry = ArrayHelper.fromObjectOrArray(proof)[0];
+            Guards.objectValue(EntityStorageIdentityConnector.CLASS_NAME, "proofEntry", proofEntry);
+            await this.verifyProof(JsonLdHelper.toNodeObject(doc), proofEntry);
+            return { revoked: false, verifiablePresentation: doc };
+        }
+        Guards.stringValue(EntityStorageIdentityConnector.CLASS_NAME, "presentation", presentation);
+        const presentationJwt = presentation;
         try {
             const jwtDecoded = await Jwt.decode(presentationJwt);
             const jwtHeader = jwtDecoded.header;
@@ -821,11 +942,15 @@ export class EntityStorageIdentityConnector {
     }
     /**
      * 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.
      * @param controller The controller of the identity who can make changes.
      * @param verificationMethodId The verification method id to use.
      * @param proofType The type of proof to create.
      * @param unsecureDocument The unsecure document to create the proof for.
      * @returns 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.
      */
     async createProof(controller, verificationMethodId, proofType, unsecureDocument) {
         Guards.stringValue(EntityStorageIdentityConnector.CLASS_NAME, "controller", controller);
@@ -862,8 +987,14 @@ export class EntityStorageIdentityConnector {
                 });
             }
             const vaultKey = EntityStorageIdentityConnector.buildVaultKey(didDocument.id, idParts.fragment ?? "");
-            const key = await this._vaultConnector.getKey(vaultKey);
-            const signedProof = await ProofHelper.createProof(proofType, unsecureDocument, ProofHelper.createUnsignedProof(proofType, verificationMethodId), await Jwk.fromEd25519Private(key.privateKey));
+            const keyType = await this._vaultConnector.getKeyType(vaultKey);
+            if (Is.undefined(keyType)) {
+                throw new GeneralError(EntityStorageIdentityConnector.CLASS_NAME, "privateKeyMissing", {
+                    keyId: vaultKey
+                });
+            }
+            const unsignedProof = ProofHelper.createUnsignedProof(proofType, verificationMethodId);
+            const signedProof = await ProofHelper.createProofWithSigner(proofType, unsecureDocument, unsignedProof, async (data, algorithm) => this.signWithVault(vaultKey, keyType, data, algorithm));
             return signedProof;
         }
         catch (error) {
@@ -916,6 +1047,27 @@ export class EntityStorageIdentityConnector {
             throw new GeneralError(EntityStorageIdentityConnector.CLASS_NAME, "verifyProofFailed", undefined, error);
         }
     }
+    /**
+     * Signs data using the vault connector with algorithm validation.
+     * @param vaultKey The vault key identifier.
+     * @param keyType The type of the key.
+     * @param data The data to sign.
+     * @param algorithm The signing algorithm.
+     * @returns The signature bytes.
+     * @throws GeneralError if algorithm doesn't match key type.
+     * @internal
+     */
+    async signWithVault(vaultKey, keyType, data, algorithm) {
+        if (algorithm === JwsAlgorithms.EdDSA && keyType !== VaultKeyType.Ed25519) {
+            throw new GeneralError(EntityStorageIdentityConnector.CLASS_NAME, "algorithmKeyTypeMismatch", {
+                algorithm,
+                expectedKeyType: VaultKeyType.Ed25519,
+                actualKeyType: keyType,
+                keyId: vaultKey
+            });
+        }
+        return this._vaultConnector.sign(vaultKey, data);
+    }
     /**
      * Get all the methods from a document.
      * @param document The document to get the methods from.