Keytool Storage (#1612)

* keytool signer refactor: made it sync and updated code structure

* KeytoolStorage

* rename feature keytool-signer to keytool

* keytool insert key

* keytool storage implementation

* test keytool storage signing and verification

* KeytoolStorage WASM bindings

* dprint fmt

* add missing license header

* yet another missing license header

* WASM KeytoolStorage JwkStorage & KeyIdStorage impl

* clippy

* fix bindgen toJSON impl

* review comments

* keytool storage example

* fix example by requesting funds for the new address

* TS Keytool storage example

* add missing license header

* remove unneeded code

* fix web build

* Added missing examples to tests, format

* Add inline docs for KeytoolSigner bindings

* link PublicKey docs through URL

Author: UMR1352

bindings/wasm/identity_wasm/Cargo.toml

@@ -81,3 +81,4 @@ unexpected_cfgs = { level = "warn", check-cfg = ['cfg(wasm_bindgen_unstable_test
 [features]
 default = ["dummy-client"]
 dummy-client = ["dep:iota_interaction_ts"]
+keytool = ["dep:iota_interaction_ts", "iota_interaction_ts/keytool", "identity_iota/keytool"]

bindings/wasm/identity_wasm/cypress/app/src/identity.ts

@@ -1,7 +1,7 @@
 import url from "@iota/identity-wasm/web/identity_wasm_bg.wasm?url";
 
 import { init } from "@iota/identity-wasm/web";
-import { main } from "../../../examples/dist/web/main";
+import { main } from "../../../examples/dist/web/web-main";
 
 export const runTest = async (example: string) => {
     try {

bindings/wasm/identity_wasm/examples/src/1_advanced/12_iota_keytool_integration.ts

@@ -0,0 +1,60 @@
+// Copyright 2020-2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+    IdentityClient,
+    IdentityClientReadOnly,
+    IotaDocument,
+    JwkKeytoolStore,
+    JwsAlgorithm,
+    KeyIdKeytoolStore,
+    KeytoolStorage,
+    MethodScope,
+    Storage,
+} from "@iota/identity-wasm/node";
+import { IotaClient } from "@iota/iota-sdk/client";
+import { IOTA_IDENTITY_PKG_ID, NETWORK_URL, requestFunds } from "../util";
+
+export async function iotaKeytoolIntegration() {
+    // For starter we access the local IOTA Keytool executable to create a new keypair.
+    const keytool = new KeytoolStorage();
+    // We generate a new Ed25519 key handled by the keytool, that we will use to interact with the ledger
+    // throughout this example.
+    const [pk, alias] = keytool.generateKey("ed25519");
+    const address = pk.toIotaAddress();
+    console.log(`Created new address ${address} with alias ${alias}!`);
+
+    // Let's request some funds for our new address.
+    await requestFunds(address);
+
+    // Let's use the newly generated key to build the signer that will power our identity client.
+    const iotaClient = new IotaClient({ url: NETWORK_URL });
+    const readOnlyClient = await IdentityClientReadOnly.createWithPkgId(iotaClient, IOTA_IDENTITY_PKG_ID);
+    const signer = keytool.signer(address);
+    // A signer that relies on IOTA Keytool may also be built with:
+    // const signer = new KeytoolSigner(address);
+    const identityClient = await IdentityClient.create(readOnlyClient, signer);
+
+    // Let's create a new DID Document, with a verification method
+    // that has its secret key stored in the Keytool.
+
+    // Firstly, we create a storage instance from our Keytool.
+    const storage = new Storage(new JwkKeytoolStore(keytool), new KeyIdKeytoolStore(keytool));
+    // Then we start building our DID Document.
+    const didDocument = new IotaDocument(identityClient.network());
+    const _vmFragment = await didDocument.generateMethod(
+        storage,
+        "secp256r1",
+        JwsAlgorithm.ES256,
+        null,
+        MethodScope.VerificationMethod(),
+    );
+
+    // Let's publish our new DID Document.
+    let publishedDidDocument = await identityClient
+        .publishDidDocument(didDocument)
+        .execute(identityClient)
+        .then(res => res.output);
+
+    console.log(`Here is our published DID document: ${JSON.stringify(publishedDidDocument, null, 2)}`);
+}

bindings/wasm/identity_wasm/examples/src/main.ts

@@ -10,6 +10,7 @@ import { createVC } from "./0_basic/5_create_vc";
 import { createVP } from "./0_basic/6_create_vp";
 import { revokeVC } from "./0_basic/7_revoke_vc";
 import { sdJwtVc } from "./1_advanced/10_sd_jwt_vc";
+import { iotaKeytoolIntegration } from "./1_advanced/12_iota_keytool_integration";
 import { customResolution } from "./1_advanced/4_custom_resolution";
 import { domainLinkage } from "./1_advanced/5_domain_linkage";
 import { sdJwt } from "./1_advanced/6_sd_jwt";
@@ -55,6 +56,8 @@ export async function main(example?: string) {
             return await zkp_revocation();
         case "10_sd_jwt_vc":
             return await sdJwtVc();
+        case "12_iota_keytool_integration":
+            return await iotaKeytoolIntegration();
         default:
             throw "Unknown example name: '" + argument + "'";
     }

bindings/wasm/identity_wasm/examples/src/tests/10_sd_jwt_vc.ts

@@ -0,0 +1,8 @@
+import { sdJwtVc } from "../1_advanced/10_sd_jwt_vc";
+
+// Only verifies that no uncaught exceptions are thrown, including syntax errors etc.
+describe("Test node examples", function() {
+    it("SD-JWT VC", async () => {
+        await sdJwtVc();
+    });
+});

bindings/wasm/identity_wasm/examples/src/tests/12_iota_keytool_integration.ts

@@ -0,0 +1,8 @@
+import { iotaKeytoolIntegration } from "../1_advanced/12_iota_keytool_integration";
+
+// Only verifies that no uncaught exceptions are thrown, including syntax errors etc.
+describe("Test node examples", function() {
+    it("IOTA Keytool Integration", async () => {
+        await iotaKeytoolIntegration();
+    });
+});

bindings/wasm/identity_wasm/examples/src/util.ts

@@ -43,6 +43,13 @@ export async function createDocumentForNetwork(storage: Storage, network: string
     return [unpublished, verificationMethodFragment];
 }
 
+export async function requestFunds(address: string) {
+    await requestIotaFromFaucetV0({
+        host: getFaucetHost(NETWORK_NAME_FAUCET),
+        recipient: address,
+    });
+}
+
 export async function getFundedClient(storage: Storage): Promise<IdentityClient> {
     if (!IOTA_IDENTITY_PKG_ID) {
         throw new Error(`IOTA_IDENTITY_PKG_ID env variable must be provided to run the examples`);
@@ -68,10 +75,7 @@ export async function getFundedClient(storage: Storage): Promise<IdentityClient>
     let signer = new StorageSigner(storage, keyId, publicKeyJwk);
     const identityClient = await IdentityClient.create(identityClientReadOnly, signer);
 
-    await requestIotaFromFaucetV0({
-        host: getFaucetHost(NETWORK_NAME_FAUCET),
-        recipient: identityClient.senderAddress(),
-    });
+    await requestFunds(identityClient.senderAddress());
 
     const balance = await iotaClient.getBalance({ owner: identityClient.senderAddress() });
     if (balance.totalBalance === "0") {

bindings/wasm/identity_wasm/examples/src/web-main.ts

@@ -0,0 +1,66 @@
+// Copyright 2020-2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import { createIdentity } from "./0_basic/0_create_did";
+import { updateIdentity } from "./0_basic/1_update_did";
+import { resolveIdentity } from "./0_basic/2_resolve_did";
+import { deactivateIdentity } from "./0_basic/3_deactivate_did";
+import { deleteIdentityDID } from "./0_basic/4_delete_did";
+import { createVC } from "./0_basic/5_create_vc";
+import { createVP } from "./0_basic/6_create_vp";
+import { revokeVC } from "./0_basic/7_revoke_vc";
+import { sdJwtVc } from "./1_advanced/10_sd_jwt_vc";
+import { customResolution } from "./1_advanced/4_custom_resolution";
+import { domainLinkage } from "./1_advanced/5_domain_linkage";
+import { sdJwt } from "./1_advanced/6_sd_jwt";
+import { statusList2021 } from "./1_advanced/7_status_list_2021";
+import { zkp } from "./1_advanced/8_zkp";
+import { zkp_revocation } from "./1_advanced/9_zkp_revocation";
+
+export async function main(example?: string) {
+    // Extract example name.
+    const argument = example ?? process.argv?.[2]?.toLowerCase();
+    if (!argument) {
+        throw "Please specify an example name, e.g. '0_create_did'";
+    }
+
+    switch (argument) {
+        case "0_create_did":
+            return await createIdentity();
+        case "1_update_did":
+            return await updateIdentity();
+        case "2_resolve_did":
+            return await resolveIdentity();
+        case "3_deactivate_did":
+            return await deactivateIdentity();
+        case "4_delete_did":
+            return await deleteIdentityDID();
+        case "5_create_vc":
+            return await createVC();
+        case "6_create_vp":
+            return await createVP();
+        case "7_revoke_vc":
+            return await revokeVC();
+        case "4_custom_resolution":
+            return await customResolution();
+        case "5_domain_linkage":
+            return await domainLinkage();
+        case "6_sd_jwt":
+            return await sdJwt();
+        case "7_status_list_2021":
+            return await statusList2021();
+        case "8_zkp":
+            return await zkp();
+        case "9_zkp_revocation":
+            return await zkp_revocation();
+        case "10_sd_jwt_vc":
+            return await sdJwtVc();
+        default:
+            throw "Unknown example name: '" + argument + "'";
+    }
+}
+
+main()
+    .catch((error) => {
+        console.log("Example error:", error);
+    });

bindings/wasm/identity_wasm/package.json

@@ -14,11 +14,12 @@
   },
   "scripts": {
     "build:src": "cargo build --lib --release --target wasm32-unknown-unknown --target-dir ../target",
+    "build:src:nodejs": "cargo build --lib --release --target wasm32-unknown-unknown --target-dir ../target --features keytool",
     "prebundle:nodejs": "rimraf node",
     "bundle:nodejs": "wasm-bindgen ../target/wasm32-unknown-unknown/release/identity_wasm.wasm --typescript --weak-refs --target nodejs --out-dir node && node ../build/node identity_wasm && tsc --project ./lib/tsconfig.json && node ../build/replace_paths ./lib/tsconfig.json node identity_wasm",
     "prebundle:web": "rimraf web",
     "bundle:web": "wasm-bindgen ../target/wasm32-unknown-unknown/release/identity_wasm.wasm --typescript --target web --out-dir web && node ../build/web identity_wasm && tsc --project ./lib/tsconfig.web.json && node ../build/replace_paths ./lib/tsconfig.web.json web identity_wasm",
-    "build:nodejs": "npm run build:src && npm run bundle:nodejs && wasm-opt -O node/identity_wasm_bg.wasm -o node/identity_wasm_bg.wasm",
+    "build:nodejs": "npm run build:src:nodejs && npm run bundle:nodejs && wasm-opt -O node/identity_wasm_bg.wasm -o node/identity_wasm_bg.wasm",
     "build:web": "npm run build:src && npm run bundle:web && wasm-opt -O web/identity_wasm_bg.wasm -o web/identity_wasm_bg.wasm",
     "build:docs": "typedoc && npm run fix_docs",
     "build:examples:web": "tsc --project ./examples/tsconfig.web.json || node ../build/replace_paths ./tsconfig.web.json dist identity_wasm/examples resolve",

bindings/wasm/identity_wasm/src/storage/keytool_storage.rs

@@ -0,0 +1,112 @@
+// Copyright 2020-2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+use identity_iota::storage::JwkStorage;
+use identity_iota::storage::KeyId;
+use identity_iota::storage::KeyIdStorage;
+use identity_iota::storage::KeyType;
+use iota_interaction_ts::bindings::keytool::WasmKeytoolStorage;
+use wasm_bindgen::prelude::wasm_bindgen;
+
+use super::WasmJwkGenOutput;
+use super::WasmMethodDigest;
+use crate::error::Result;
+use crate::error::WasmResult;
+use crate::jose::WasmJwk;
+
+/// Implementation of {@link JwkStorage} for {@link KeytoolStorage}.
+#[wasm_bindgen(js_name = JwkKeytoolStore)]
+pub struct WasmJwkKeytoolStore(pub(crate) WasmKeytoolStorage);
+
+#[wasm_bindgen(js_class = JwkKeytoolStore)]
+impl WasmJwkKeytoolStore {
+  #[wasm_bindgen(constructor)]
+  pub fn new(keytool: &WasmKeytoolStorage) -> Self {
+    Self(keytool.clone())
+  }
+
+  // JwkStorage implementation
+
+  #[wasm_bindgen]
+  pub async fn generate(&self, key_type: &str, algorithm: &str) -> Result<WasmJwkGenOutput> {
+    let key_type = KeyType::new(key_type);
+    let jws_alg = algorithm.parse().wasm_result()?;
+    self
+      .0
+      .as_ref()
+      .generate(key_type, jws_alg)
+      .await
+      .wasm_result()
+      .map(WasmJwkGenOutput)
+  }
+
+  #[wasm_bindgen]
+  pub async fn insert(&self, jwk: WasmJwk) -> Result<String> {
+    self
+      .0
+      .as_ref()
+      .insert(jwk.0.clone())
+      .await
+      .wasm_result()
+      .map(|key_id| key_id.to_string())
+  }
+
+  #[wasm_bindgen]
+  pub async fn sign(&self, key_id: &str, data: &[u8], public_key: &WasmJwk) -> Result<Vec<u8>> {
+    let key_id = KeyId::new(key_id);
+    self.0.as_ref().sign(&key_id, data, &public_key.0).await.wasm_result()
+  }
+
+  #[wasm_bindgen]
+  pub async fn delete(&self, key_id: &str) -> Result<()> {
+    let key_id = KeyId::new(key_id);
+    self.0.as_ref().delete(&key_id).await.wasm_result()
+  }
+
+  #[wasm_bindgen]
+  pub async fn exists(&self, key_id: &str) -> Result<bool> {
+    let key_id = KeyId::new(key_id);
+    self.0.as_ref().exists(&key_id).await.wasm_result()
+  }
+}
+
+/// Implementation of interface {@link KeyIdStorage} for {@link KeytoolStorage}.
+#[wasm_bindgen(js_name = KeyIdKeytoolStore)]
+pub struct WasmKeyIdKeytoolStore(pub(crate) WasmKeytoolStorage);
+
+#[wasm_bindgen(js_class = KeyIdKeytoolStore)]
+impl WasmKeyIdKeytoolStore {
+  #[wasm_bindgen(constructor)]
+  pub fn new(keytool: &WasmKeytoolStorage) -> Self {
+    Self(keytool.clone())
+  }
+
+  // KeyIdStorage implementation
+
+  #[wasm_bindgen(js_name = insertKeyId)]
+  pub async fn insert_key_id(&self, method_digest: WasmMethodDigest, key_id: &str) -> Result<()> {
+    let key_id = KeyId::new(key_id);
+    self
+      .0
+      .as_ref()
+      .insert_key_id(method_digest.0, key_id)
+      .await
+      .wasm_result()
+  }
+
+  #[wasm_bindgen(js_name = getKeyId)]
+  pub async fn get_key_id(&self, method_digest: &WasmMethodDigest) -> Result<String> {
+    self
+      .0
+      .as_ref()
+      .get_key_id(&method_digest.0)
+      .await
+      .wasm_result()
+      .map(|key_id| key_id.to_string())
+  }
+
+  #[wasm_bindgen(js_name = deleteKeyId)]
+  pub async fn delete_key_id(&self, method_digest: &WasmMethodDigest) -> Result<()> {
+    self.0.as_ref().delete_key_id(&method_digest.0).await.wasm_result()
+  }
+}

bindings/wasm/identity_wasm/src/storage/mod.rs

@@ -7,6 +7,8 @@ mod jwk_storage;
 mod jwk_storage_bbs_plus_ext;
 mod jwt_presentation_options;
 mod key_id_storage;
+#[cfg(feature = "keytool")]
+mod keytool_storage;
 mod method_digest;
 mod signature_options;
 mod wasm_storage;
@@ -18,6 +20,8 @@ pub use jwk_gen_output::*;
 pub use jwk_storage::*;
 pub use jwt_presentation_options::*;
 pub use key_id_storage::*;
+#[cfg(feature = "keytool")]
+pub use keytool_storage::*;
 pub use method_digest::*;
 pub use signature_options::*;
 pub use wasm_storage::*;

bindings/wasm/iota_interaction_ts/Cargo.toml

@@ -53,4 +53,5 @@ instant = { version = "0.1", default-features = false, features = ["wasm-bindgen
 empty_docs = "allow"
 
 [features]
-keytool-signer = ["identity_iota_interaction/keytool-signer"]
+default = []
+keytool = ["identity_iota_interaction/keytool"]

bindings/wasm/iota_interaction_ts/package.json

@@ -11,7 +11,7 @@
   },
   "scripts": {
     "build:src": "cargo build --lib --release --target wasm32-unknown-unknown --target-dir ../target",
-    "build:src:node": "cargo build --lib --release --target wasm32-unknown-unknown --features keytool-signer --target-dir ../target",
+    "build:src:node": "cargo build --lib --release --target wasm32-unknown-unknown --features keytool --target-dir ../target",
     "prebundle:nodejs": "rimraf node",
     "bundle:nodejs": "wasm-bindgen ../target/wasm32-unknown-unknown/release/iota_interaction_ts.wasm --typescript --weak-refs --target nodejs --out-dir node && node ../build/node iota_interaction_ts && tsc --project ./lib/tsconfig.json && node ../build/replace_paths ./lib/tsconfig.json node iota_interaction_ts",
     "prebundle:web": "rimraf web",

bindings/wasm/iota_interaction_ts/src/bindings/keytool/mod.rs

@@ -0,0 +1,8 @@
+// Copyright 2020-2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+mod signer;
+mod storage;
+
+pub use signer::*;
+pub use storage::*;