Merge pull request #1323 from dfinity/vetkeys-examples

feat: add basic vetkeys examples

Author: andreacerulli

motoko/vetkeys/README.md

@@ -1,12 +1,12 @@
-# vetKeys Examples
+# VetKeys Examples (Motoko)
 
-## Basic Examples
-- **[Password Manager](https://github.com/dfinity/vetkeys/tree/main/examples/password_manager)** - A secure, decentralized password manager using Encrypted Maps for vault-based password storage and sharing.
-- **[Password Manager with Metadata](https://github.com/dfinity/vetkeys/tree/main/examples/password_manager_with_metadata)** - Extends the basic password manager to support unencrypted metadata alongside encrypted passwords.
-- **[Encrypted Notes](https://github.com/dfinity/vetkeys/tree/main/examples/encrypted_notes_dapp_vetkd)** - A secure note-taking application that uses vetKeys for encryption and enables sharing notes between users without device management.
+The VetKeys examples (including Motoko backends) are located in [`rust/vetkeys/`](../../rust/vetkeys/).
 
-## Advanced Examples
+Each example that supports a Motoko backend has a `motoko/` subdirectory alongside its `rust/` backend:
 
-- **[Threshold BLS Signature](https://github.com/dfinity/vetkeys/tree/main/examples/basic_bls_signing)** - Demonstrates how to use vetKeys to create a threshold BLS signing service.
-
-- **[Identity-Basic Encryption (IBE)](https://github.com/dfinity/vetkeys/tree/main/examples/basic_ibe)** - Shows how to implement secure messaging using Identity Based Encryption with Internet Identity Principals as encryption keys.
+- [Basic BLS Signing](../../rust/vetkeys/basic_bls_signing/) — Motoko + Rust
+- [Basic IBE](../../rust/vetkeys/basic_ibe/) — Motoko + Rust
+- [Encrypted Notes](../../rust/vetkeys/encrypted_notes_dapp_vetkd/) — Motoko + Rust
+- [Password Manager](../../rust/vetkeys/password_manager/) — Motoko + Rust
+- [Password Manager with Metadata](../../rust/vetkeys/password_manager_with_metadata/) — Motoko + Rust
+- [Basic Timelock IBE](../../rust/vetkeys/basic_timelock_ibe/) — Rust only

rust/vetkeys/basic_bls_signing/README.md

@@ -0,0 +1,60 @@
+# Threshold BLS Signatures
+
+| Motoko backend | [![](https://icp.ninja/assets/open.svg)](http://icp.ninja/editor?g=https://github.com/dfinity/examples/tree/master/rust/vetkeys/basic_bls_signing/motoko)|
+| --- | --- |
+| Rust backend | [![](https://icp.ninja/assets/open.svg)](http://icp.ninja/editor?g=https://github.com/dfinity/examples/tree/master/rust/vetkeys/basic_bls_signing/rust) |
+
+The **Basic BLS signing** example demonstrates how to use **[vetKeys](https://internetcomputer.org/docs/building-apps/network-features/vetkeys/introduction)** to implement a threshold BLS signing service on the **Internet Computer (IC)**, where every authenticated user can ask the canister (IC smart contract) to produce signatures, where the **Internet Identity Principal** identifies the signer. This canister ensures that users can only produce signature for their own principal and not for someone else's principal. Furthermore, the vetKeys in this dapp can only be produced upon a user request, as specified in the canister code, meaning that the canister cannot produce signatures for arbitrary users or messages.
+
+For confirming that the canister can only produce signatures in the intended way, users need to inspect the code installed in the canister. For this, it is crucial that canisters using VetKeys have their code public.
+
+![UI Screenshot](ui_screenshot.png)
+
+## Features
+
+- **Signer Authorization**: Only authorized users can produce signatures and only for their own identity.
+- **Frontend Signature Verification**: Any user can publish any signature from their principal in the canister storage and the frontend automatically checks the signature validity.
+
+## Setup
+
+### Prerequisites
+
+- [Internet Computer software development kit](https://internetcomputer.org/docs/building-apps/getting-started/install)
+- [npm](https://www.npmjs.com/package/npm)
+
+### (Optionally) Choose a Different Master Key
+
+This example uses `test_key_1` by default. To use a different [available master key](https://internetcomputer.org/docs/building-apps/network-features/vetkeys/api#available-master-keys), change the `"init_arg": "(\"test_key_1\")"` line in `dfx.json` to the desired key before running `dfx deploy` in the next step.
+
+### Deploy the Canisters Locally
+
+If you want to deploy this project locally with a Motoko backend, then run:
+```bash
+dfx start --background && dfx deploy
+```
+from the `motoko` folder.
+
+To use the Rust backend instead of Motoko, run the same command in the `rust` folder.
+
+## Example Components
+
+### Backend
+
+The backend consists of a canister that:
+* Produces signatures upon a user request.
+* Allows users to retrieve the root public key that can be used to check any user's signature for this canister.
+* Allows users to store signatures (real or fake) in a log datastructure.
+
+### Frontend
+
+The frontend is a vanilla typescript application providing a simple interface for signing, showing the signatures stored in the canister, and publishing a signature.
+
+To run the frontend in development mode with hot reloading (after running `dfx deploy`):
+
+```bash
+npm run dev
+```
+
+## Additional Resources
+
+- **[What are VetKeys](https://internetcomputer.org/docs/building-apps/network-features/encryption/vetkeys)** - For more information about VetKeys and VetKD.

rust/vetkeys/basic_bls_signing/frontend/eslint.config.mjs

@@ -0,0 +1,30 @@
+// @ts-check
+
+import eslint from "@eslint/js";
+import tseslint from "typescript-eslint";
+import eslintPluginPrettierRecommended from "eslint-plugin-prettier/recommended";
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  tseslint.configs.recommendedTypeChecked,
+  eslintPluginPrettierRecommended,
+  {
+    languageOptions: {
+      parserOptions: {
+        project: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+  {
+    ignores: [
+      "dist/",
+      "src/declarations",
+      "coverage/",
+      "*.config.js",
+      "*.config.cjs",
+      "*.config.mjs",
+      "*.config.ts",
+    ],
+  }
+);

rust/vetkeys/basic_bls_signing/frontend/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>VetKeys: Basic BLS Signing</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

rust/vetkeys/basic_bls_signing/frontend/package.json

@@ -0,0 +1,31 @@
+{
+    "name": "basic_bls_signing_frontend",
+    "private": true,
+    "version": "0.0.0",
+    "type": "module",
+    "scripts": {
+        "dev": "npm run build:bindings && vite",
+        "build": "npm run build:bindings && tsc && vite build",
+        "build:bindings": "cd scripts && ./gen_bindings.sh",
+        "preview": "vite preview",
+        "lint": "eslint"
+    },
+    "devDependencies": {
+        "@eslint/js": "^9.24.0",
+        "@rollup/plugin-typescript": "^12.1.2",
+        "@types/node": "^24.0.10",
+        "eslint": "^9.24.0",
+        "eslint-config-prettier": "^10.1.5",
+        "eslint-plugin-prettier": "^5.4.0",
+        "tslib": "^2.8.1",
+        "typescript": "~5.7.2",
+        "typescript-eslint": "^8.35.1",
+        "vite": "^6.4.1",
+        "vite-plugin-environment": "^1.1.3"
+    },
+    "dependencies": {
+        "@dfinity/auth-client": "^2.4.1",
+        "@dfinity/principal": "^2.4.1",
+        "@dfinity/vetkeys": "^0.3.0"
+    }
+}

rust/vetkeys/basic_bls_signing/frontend/public/.ic-assets.json5

@@ -0,0 +1,10 @@
+[
+  {
+    match: "**/*",
+    security_policy: "hardened",
+    headers: {
+      "Content-Security-Policy": "default-src 'self';script-src 'self';connect-src 'self' http://localhost:* https://icp0.io https://*.icp0.io https://icp-api.io;img-src 'self';object-src 'none';base-uri 'self';frame-ancestors 'none';form-action 'self';upgrade-insecure-requests;",
+    },
+    allow_raw_access: false
+  },
+]

rust/vetkeys/basic_bls_signing/frontend/scripts/gen_bindings.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+cd ../../backend && make extract-candid
+
+cd .. && dfx generate basic_bls_signing || exit 1
+
+rm -r frontend/src/declarations/basic_bls_signing > /dev/null 2>&1 || true
+
+mkdir -p frontend/src/declarations/basic_bls_signing
+mv src/declarations/basic_bls_signing frontend/src/declarations
+rmdir -p src/declarations > /dev/null 2>&1 || true
+
+# dfx 0.31+ generates @icp-sdk/core imports; rewrite to @dfinity/* to match deps
+find frontend/src/declarations -type f \( -name '*.ts' -o -name '*.js' \) -exec \
+  perl -i -pe 's|\@icp-sdk/core/agent|\@dfinity/agent|g; s|\@icp-sdk/core/principal|\@dfinity/principal|g; s|\@icp-sdk/core/candid|\@dfinity/candid|g' {} +