@semaphore-protocol/identity 4.0.0-beta.1 → 4.0.0-beta.10

package/dist/types/index.d.ts

@@ -1,2 +1,86 @@
-import Identity from "./identity";
-export { Identity };
+import type { Point } from "@zk-kit/baby-jubjub";
+import { Signature } from "@zk-kit/eddsa-poseidon";
+import type { BigNumberish } from "@zk-kit/utils";
+/**
+ * The Semaphore identity is essentially an {@link https://www.rfc-editor.org/rfc/rfc8032 | EdDSA}
+ * public/private key pair. The {@link https://github.com/privacy-scaling-explorations/zk-kit/tree/main/packages/eddsa-poseidon | EdDSA implementation}
+ * in this library uses {@link https://eips.ethereum.org/EIPS/eip-2494 | Baby Jubjub} for public key generation
+ * and {@link https://www.poseidon-hash.info | Poseidon} for signatures.
+ * In addition, the commitment, i.e. the hash of the public key, is used to represent
+ * Semaphore identities in groups, adding an additional layer of privacy and security.
+ * The private key of the identity is stored as a hexadecimal string or text.
+ * The other attributes are stored as stringified bigint.
+ */
+export declare class Identity {
+    private _privateKey;
+    private _secretScalar;
+    private _publicKey;
+    private _commitment;
+    /**
+     * Initializes the class attributes based on a given private key, which must be a hexadecimal string or a text.
+     * Hexadecimal strings must not start with '0x' or '0X'.
+     * If the private key is not passed as a parameter, a random hexadecimal key will be generated.
+     * The EdDSAPoseidon class is used to generate the secret scalar and the public key.
+     * Additionally, the constructor computes a commitment of the public key using a hash function (Poseidon).
+     *
+     * @example
+     * // Generates an identity.
+     * const { privateKey, publicKey, commitment } = new Identity("private-key")
+     * @example
+     * // Generates an identity with a random private key.
+     * const { privateKey, publicKey, commitment } = new Identity()
+     *
+     * @param privateKey The private key used to derive the public key (hexadecimal or string).
+     */
+    constructor(privateKey?: string);
+    /**
+     * Returns the private key.
+     * @returns The private key as a string (hexadecimal or text).
+     */
+    get privateKey(): string;
+    /**
+     * Returns the secret scalar.
+     * @returns The secret scalar as a string.
+     */
+    get secretScalar(): bigint;
+    /**
+     * Returns the public key as a Baby Jubjub {@link https://zkkit.pse.dev/types/_zk_kit_baby_jubjub.Point.html | Point}.
+     * @returns The public key as a point.
+     */
+    get publicKey(): Point<bigint>;
+    /**
+     * Returns the commitment hash of the public key.
+     * @returns The commitment as a string.
+     */
+    get commitment(): bigint;
+    /**
+     * Generates a signature for a given message using the private key.
+     * This method demonstrates how to sign a message and could be used
+     * for authentication or data integrity.
+     *
+     * @example
+     * const identity = new Identity()
+     * const signature = identity.signMessage("message")
+     *
+     * @param message The message to be signed.
+     * @returns A {@link https://zkkit.pse.dev/types/_zk_kit_eddsa_poseidon.Signature.html | Signature} object containing the signature components.
+     */
+    signMessage(message: BigNumberish): Signature<bigint>;
+    /**
+     * Verifies a signature against a given message and public key.
+     * This static method allows for the verification of signatures without needing
+     * an instance of the Identity class. It's useful for cases where you only have
+     * the public key, the message and a signature, and need to verify if they match.
+     *
+     * @example
+     * const identity = new Identity()
+     * const signature = identity.signMessage("message")
+     * Identity.verifySignature("message", signature, identity.publicKey)
+     *
+     * @param message The message that was signed.
+     * @param signature The signature to verify.
+     * @param publicKey The public key to use for verification.
+     * @returns A boolean indicating whether the signature is valid.
+     */
+    static verifySignature(message: BigNumberish, signature: Signature, publicKey: Point): boolean;
+}

package/package.json

@@ -1,21 +1,15 @@
 {
   "name": "@semaphore-protocol/identity",
-  "version": "4.0.0-beta.1",
+  "version": "4.0.0-beta.10",
   "description": "A library to create Semaphore identities.",
   "type": "module",
   "license": "MIT",
-  "main": "dist/index.browser.js",
+  "main": "dist/index.js",
   "types": "dist/types/index.d.ts",
   "exports": {
-    ".": {
-      "types": "./dist/types/index.d.ts",
-      "node": {
-        "require": "./dist/index.node.cjs",
-        "default": "./dist/index.node.js"
-      },
-      "browser": "./dist/index.browser.js",
-      "default": "./dist/index.browser.js"
-    }
+    "types": "./dist/types/index.d.ts",
+    "require": "./dist/index.cjs",
+    "default": "./dist/index.js"
   },
   "files": [
     "dist/",
@@ -29,9 +23,7 @@
     "url": "https://github.com/semaphore-protocol/semaphore.git/issues"
   },
   "scripts": {
-    "build": "rimraf dist && yarn build:browser && yarn build:node",
-    "build:browser": "rollup -c rollup.browser.config.ts --configPlugin typescript",
-    "build:node": "rollup -c rollup.node.config.ts --configPlugin typescript",
+    "build": "rimraf dist && rollup -c rollup.config.ts --configPlugin typescript",
     "prepublishOnly": "yarn build"
   },
   "publishConfig": {
@@ -41,13 +33,15 @@
     "@rollup/plugin-alias": "^5.1.0",
     "@rollup/plugin-commonjs": "^25.0.7",
     "@rollup/plugin-node-resolve": "^15.2.3",
-    "rollup-plugin-cleanup": "^3.2.1",
-    "rollup-plugin-typescript2": "^0.36.0"
+    "@rollup/plugin-typescript": "^11.1.6",
+    "rimraf": "^5.0.5",
+    "rollup": "^4.12.0",
+    "rollup-plugin-cleanup": "^3.2.1"
   },
   "dependencies": {
-    "@zk-kit/baby-jubjub": "0.2.0",
-    "@zk-kit/eddsa-poseidon": "0.6.0",
-    "@zk-kit/utils": "0.3.0",
+    "@zk-kit/baby-jubjub": "1.0.0",
+    "@zk-kit/eddsa-poseidon": "1.0.0",
+    "@zk-kit/utils": "1.0.0-beta.4",
     "poseidon-lite": "0.2.0"
   }
 }

package/src/index.ts

@@ -1,4 +1,141 @@
-import Identity from "./identity"
+import type { Point } from "@zk-kit/baby-jubjub"
+import { EdDSAPoseidon, Signature, signMessage, verifySignature } from "@zk-kit/eddsa-poseidon"
+import type { BigNumberish } from "@zk-kit/utils"
+import { hexadecimalToBuffer } from "@zk-kit/utils/conversions"
+import { requireString } from "@zk-kit/utils/error-handlers"
+import { isHexadecimal } from "@zk-kit/utils/type-checks"
+import { poseidon2 } from "poseidon-lite/poseidon2"
 
-// eslint-disable-next-line import/prefer-default-export
-export { Identity }
+/**
+ * The Semaphore identity is essentially an {@link https://www.rfc-editor.org/rfc/rfc8032 | EdDSA}
+ * public/private key pair. The {@link https://github.com/privacy-scaling-explorations/zk-kit/tree/main/packages/eddsa-poseidon | EdDSA implementation}
+ * in this library uses {@link https://eips.ethereum.org/EIPS/eip-2494 | Baby Jubjub} for public key generation
+ * and {@link https://www.poseidon-hash.info | Poseidon} for signatures.
+ * In addition, the commitment, i.e. the hash of the public key, is used to represent
+ * Semaphore identities in groups, adding an additional layer of privacy and security.
+ * The private key of the identity is stored as a hexadecimal string or text.
+ * The other attributes are stored as stringified bigint.
+ */
+export class Identity {
+    // The EdDSA private key, passed as a parameter or generated randomly.
+    private _privateKey: string
+    // The secret scalar derived from the private key.
+    // It is used in circuits to derive the public key.
+    private _secretScalar: bigint
+    // The EdDSA public key, derived from the private key.
+    private _publicKey: Point<bigint>
+    // The identity commitment used as a public value in Semaphore groups.
+    private _commitment: bigint
+
+    /**
+     * Initializes the class attributes based on a given private key, which must be a hexadecimal string or a text.
+     * Hexadecimal strings must not start with '0x' or '0X'.
+     * If the private key is not passed as a parameter, a random hexadecimal key will be generated.
+     * The EdDSAPoseidon class is used to generate the secret scalar and the public key.
+     * Additionally, the constructor computes a commitment of the public key using a hash function (Poseidon).
+     *
+     * @example
+     * // Generates an identity.
+     * const { privateKey, publicKey, commitment } = new Identity("private-key")
+     * @example
+     * // Generates an identity with a random private key.
+     * const { privateKey, publicKey, commitment } = new Identity()
+     *
+     * @param privateKey The private key used to derive the public key (hexadecimal or string).
+     */
+    constructor(privateKey?: string) {
+        let eddsa: EdDSAPoseidon
+
+        if (privateKey) {
+            requireString(privateKey, "privateKey")
+
+            this._privateKey = privateKey
+
+            if (isHexadecimal(privateKey, false)) {
+                eddsa = new EdDSAPoseidon(hexadecimalToBuffer(privateKey))
+            } else {
+                eddsa = new EdDSAPoseidon(privateKey)
+            }
+        } else {
+            eddsa = new EdDSAPoseidon()
+
+            this._privateKey = eddsa.privateKey as string
+        }
+
+        this._secretScalar = eddsa.secretScalar
+        this._publicKey = eddsa.publicKey
+        this._commitment = poseidon2(this._publicKey)
+    }
+
+    /**
+     * Returns the private key.
+     * @returns The private key as a string (hexadecimal or text).
+     */
+    public get privateKey(): string {
+        return this._privateKey
+    }
+
+    /**
+     * Returns the secret scalar.
+     * @returns The secret scalar as a string.
+     */
+    public get secretScalar(): bigint {
+        return this._secretScalar
+    }
+
+    /**
+     * Returns the public key as a Baby Jubjub {@link https://zkkit.pse.dev/types/_zk_kit_baby_jubjub.Point.html | Point}.
+     * @returns The public key as a point.
+     */
+    public get publicKey(): Point<bigint> {
+        return this._publicKey
+    }
+
+    /**
+     * Returns the commitment hash of the public key.
+     * @returns The commitment as a string.
+     */
+    public get commitment(): bigint {
+        return this._commitment
+    }
+
+    /**
+     * Generates a signature for a given message using the private key.
+     * This method demonstrates how to sign a message and could be used
+     * for authentication or data integrity.
+     *
+     * @example
+     * const identity = new Identity()
+     * const signature = identity.signMessage("message")
+     *
+     * @param message The message to be signed.
+     * @returns A {@link https://zkkit.pse.dev/types/_zk_kit_eddsa_poseidon.Signature.html | Signature} object containing the signature components.
+     */
+    public signMessage(message: BigNumberish): Signature<bigint> {
+        const privateKey = isHexadecimal(this.privateKey, false)
+            ? hexadecimalToBuffer(this.privateKey)
+            : this.privateKey
+
+        return signMessage(privateKey, message)
+    }
+
+    /**
+     * Verifies a signature against a given message and public key.
+     * This static method allows for the verification of signatures without needing
+     * an instance of the Identity class. It's useful for cases where you only have
+     * the public key, the message and a signature, and need to verify if they match.
+     *
+     * @example
+     * const identity = new Identity()
+     * const signature = identity.signMessage("message")
+     * Identity.verifySignature("message", signature, identity.publicKey)
+     *
+     * @param message The message that was signed.
+     * @param signature The signature to verify.
+     * @param publicKey The public key to use for verification.
+     * @returns A boolean indicating whether the signature is valid.
+     */
+    static verifySignature(message: BigNumberish, signature: Signature, publicKey: Point): boolean {
+        return verifySignature(message, signature, publicKey)
+    }
+}