diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 40d96fa..691cfda 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -14,7 +14,7 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - node: [ 20, 18 ] + node: [ 22, 20 ] crypto_arg_required: [ true, false ] steps: - name: Checking out diff --git a/README.md b/README.md index 79ba175..5faf2c1 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![NPM](https://nodei.co/npm/@cloudflare/voprf-ts.png)](https://www.npmjs.com/package/@cloudflare/voprf-ts) -# voprf-ts: A TypeScript Library for Oblivious Pseudorandom Functions (OPRF). +# voprf-ts: A TypeScript Library for Oblivious Pseudorandom Functions (OPRF) An **Oblivious Pseudorandom Function (OPRF)** is a two-party protocol between a client and server for computing the output of a Pseudorandom Function (PRF). @@ -13,26 +13,37 @@ A **verifiable OPRF (VOPRF)** ensures clients can verify that the server used a A **partially-oblivious (POPRF)** extends a VOPRF allowing the client and server to provide public shared input to the PRF computation. +|Specification: [RFC 9497](https://doi.org/10.17487/RFC9497)| +|--| + This library supports all three modes: + ```js Oprf.Mode.OPRF Oprf.Mode.VOPRF Oprf.Mode.POPRF ``` -and supports three suites corresponding to the underlying group and hash used: + +and supports the following suites corresponding to the underlying group and hash used: + ```js Oprf.Suite.P256_SHA256 Oprf.Suite.P384_SHA384 Oprf.Suite.P521_SHA512 ``` -**Specification:** Compliant with IETF [draft-irtf-cfrg-voprf](https://datatracker.ietf.org/doc/draft-irtf-cfrg-voprf/) and tests vectors match with [v21](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-voprf-21). +Additional suites are also supported when using the [@noble/curves](https://www.npmjs.com/package/@noble/curves) library as the `CryptoProvider`. See [examples/facade/index.ts](examples/facade/index.ts) to setup this `CryptoProvider`. + +```js +Oprf.Suite.RISTRETTO255_SHA512 +Oprf.Suite.DECAF448_SHAKE256 +``` -### Usage +## Usage -#### Step 1 +### Step 1 -First set up a client and a server. In this case, we use the VOPRF mode with suite P384-SHA384. +First set up a client and a server. In this example, we use the VOPRF mode with suite P384-SHA384. ```js import { @@ -47,17 +58,17 @@ const server = new VOPRFServer(suite, privateKey); const client = new VOPRFClient(suite, publicKey); ``` -#### Step 2 +### Step 2 -The client prepares arbitrary input[s] that will be batch evaluated by the server. The blinding method produces an evaluation request, and some finalization data to be used later. Then, the client sends the evaluation request to the server. +The client prepares arbitrary input(s) that will be batch evaluated by the server. The blinding method produces an evaluation request, and some finalization data to be used later. Then, the client sends the evaluation request to the server. ```js -const input = new TextEncoder().encode("This is the client's input"); +const input = new TextEncoder().encode('This is the client's input'); const batch = [input] const [finData, evalReq] = await client.blind(batch); ``` -#### Step 3 +### Step 3 Once the server received the evaluation request, it responds to the client with an evaluation. @@ -65,19 +76,15 @@ Once the server received the evaluation request, it responds to the client with const evaluation = await server.blindEvaluate(evalReq); ``` -#### Step 4 +### Step 4 -Finally, the client can produce the output[s] of the OPRF protocol using the server's evaluation and the finalization data from the second step. If the mode is verifiable, this step allows the client to check the proof that the server used the expected private key for the evaluation. +Finally, the client can produce the output(s) of the OPRF protocol using the server's evaluation and the finalization data from the second step. If the mode is verifiable, this step also checks the proof that the server used the expected private key for the evaluation. ```js // Get output matching first input of batch const [output] = await client.finalize(finData, evaluation); ``` -### Facade API - -See [examples](examples/facade/index.ts) - ### Development | Task | NPM scripts | @@ -90,14 +97,18 @@ See [examples](examples/facade/index.ts) | Code Linting | `$ npm run lint` | | Code Formatting | `$ npm run format` | +## Security Disclaimer -**Dependencies** +🚨 This library is offered as-is, and without a guarantee. Therefore, it is expected that changes in the code, repository, and API occur in the future. We recommend to take caution before using this library in a production application since part of its content is experimental. All security issues must be reported, please notify us immediately following the instructions given in our [Security Policy](https://github.com/cloudflare/voprf-ts/security/policy). -This project uses the Stanford Javascript Crypto Library [sjcl](https://github.com/bitwiseshiftleft/sjcl). Support for elliptic curves must be enabled by this compilation step, which produces the necessary files inside the [src/sjcl](./src/sjcl) folder. +### Cryptography Providers -```sh - $ make -f sjcl.Makefile -``` +Although this library relies on the standard [Web Cryptography API](https://www.w3.org/TR/WebCryptoAPI/) for high-level operations, prime field and elliptic curve operations are not covered by the standard API. For this reason, this library can be configured to use one of the following providers: + +* The Stanford JavaScript Crypto Library [sjcl](https://github.com/bitwiseshiftleft/sjcl). +* The [@noble/curves](https://www.npmjs.com/package/@noble/curves) library. + +⚠️ **Note:** Running operations in constant time is a basic requirement to prevent against timing attacks. However in JavaScript, constant-time execution is not guaranteed. These providers have made different choices towards addressing this goal. ### License diff --git a/mockCrypto/tsconfig.cjs.json b/mockCrypto/tsconfig.cjs.json index 7d4f5b9..30ce327 100644 --- a/mockCrypto/tsconfig.cjs.json +++ b/mockCrypto/tsconfig.cjs.json @@ -1,6 +1,4 @@ { "extends": "../tsconfig.cjs.json", - "include": [ - "." - ] + "include": ["."] } diff --git a/mockCrypto/tsconfig.json b/mockCrypto/tsconfig.json index 6d0b962..3ae2a24 100644 --- a/mockCrypto/tsconfig.json +++ b/mockCrypto/tsconfig.json @@ -1,6 +1,4 @@ { "extends": "../tsconfig.json", - "include": [ - "." - ] -} \ No newline at end of file + "include": ["."] +} diff --git a/package-lock.json b/package-lock.json index 115f4a7..03ddf06 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,16 +1,16 @@ { "name": "@cloudflare/voprf-ts", - "version": "0.21.2", + "version": "1.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@cloudflare/voprf-ts", - "version": "0.21.2", + "version": "1.0.0", "license": "BSD-3-Clause", "devDependencies": { - "@eslint/js": "9.6.0", - "@noble/curves": "1.4.2", + "@eslint/js": "9.8.0", + "@noble/curves": "1.5.0", "@noble/hashes": "1.4.0", "@types/benchmark": "2.1.5", "@types/eslint__js": "8.42.3", @@ -18,21 +18,21 @@ "benchmark": "2.1.4", "eslint": "8.57.0", "eslint-config-prettier": "9.1.0", - "eslint-plugin-jest": "28.6.0", + "eslint-plugin-jest": "28.8.0", "eslint-plugin-jest-formatting": "3.1.0", - "eslint-plugin-prettier": "5.1.3", + "eslint-plugin-prettier": "5.2.1", "eslint-plugin-security": "3.0.1", "jest": "29.7.0", - "prettier": "3.3.2", + "prettier": "3.3.3", "sjcl": "1.0.8", - "typescript": "5.5.3", + "typescript": "5.5.4", "typescript-eslint": "7.15.0" }, "engines": { - "node": ">=18" + "node": ">=20" }, "optionalDependencies": { - "@noble/curves": "1.4.2", + "@noble/curves": "1.5.0", "@noble/hashes": "1.4.0" } }, @@ -731,9 +731,9 @@ } }, "node_modules/@eslint/js": { - "version": "9.6.0", - "resolved": "https://registry.npmjs.org/@eslint/js/-/js-9.6.0.tgz", - "integrity": "sha512-D9B0/3vNg44ZeWbYMpBoXqNP4j6eQD5vNwIlGAuFRRzK/WtT/jvDQW3Bi9kkf3PMDMlM7Yi+73VLUsn5bJcl8A==", + "version": "9.8.0", + "resolved": "https://registry.npmjs.org/@eslint/js/-/js-9.8.0.tgz", + "integrity": "sha512-MfluB7EUfxXtv3i/++oh89uzAr4PDI4nn201hsp+qaXqsjAWzinlZEHEfPgAX4doIlKvPG/i0A9dpKxOLII8yA==", "dev": true, "license": "MIT", "engines": { @@ -1241,9 +1241,9 @@ } }, "node_modules/@noble/curves": { - "version": "1.4.2", - "resolved": "https://registry.npmjs.org/@noble/curves/-/curves-1.4.2.tgz", - "integrity": "sha512-TavHr8qycMChk8UwMld0ZDRvatedkzWfH8IiaeGCfymOP5i0hSCozz9vHOL0nkwk7HRMlFnAiKpS2jrUmSybcw==", + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/@noble/curves/-/curves-1.5.0.tgz", + "integrity": "sha512-J5EKamIHnKPyClwVrzmaf5wSdQXgdHcPZIZLu3bwnbeCx8/7NPK5q2ZBWF+5FvYGByjiQQsJYX6jfgB2wDPn3A==", "dev": true, "license": "MIT", "dependencies": { @@ -2501,19 +2501,19 @@ } }, "node_modules/eslint-plugin-jest": { - "version": "28.6.0", - "resolved": "https://registry.npmjs.org/eslint-plugin-jest/-/eslint-plugin-jest-28.6.0.tgz", - "integrity": "sha512-YG28E1/MIKwnz+e2H7VwYPzHUYU4aMa19w0yGcwXnnmJH6EfgHahTJ2un3IyraUxNfnz/KUhJAFXNNwWPo12tg==", + "version": "28.8.0", + "resolved": "https://registry.npmjs.org/eslint-plugin-jest/-/eslint-plugin-jest-28.8.0.tgz", + "integrity": "sha512-Tubj1hooFxCl52G4qQu0edzV/+EZzPUeN8p2NnW5uu4fbDs+Yo7+qDVDc4/oG3FbCqEBmu/OC3LSsyiU22oghw==", "dev": true, "license": "MIT", "dependencies": { - "@typescript-eslint/utils": "^6.0.0 || ^7.0.0" + "@typescript-eslint/utils": "^6.0.0 || ^7.0.0 || ^8.0.0" }, "engines": { "node": "^16.10.0 || ^18.12.0 || >=20.0.0" }, "peerDependencies": { - "@typescript-eslint/eslint-plugin": "^6.0.0 || ^7.0.0", + "@typescript-eslint/eslint-plugin": "^6.0.0 || ^7.0.0 || ^8.0.0", "eslint": "^7.0.0 || ^8.0.0 || ^9.0.0", "jest": "*" }, @@ -2540,14 +2540,14 @@ } }, "node_modules/eslint-plugin-prettier": { - "version": "5.1.3", - "resolved": "https://registry.npmjs.org/eslint-plugin-prettier/-/eslint-plugin-prettier-5.1.3.tgz", - "integrity": "sha512-C9GCVAs4Eq7ZC/XFQHITLiHJxQngdtraXaM+LoUFoFp/lHNl2Zn8f3WQbe9HvTBBQ9YnKFB0/2Ajdqwo5D1EAw==", + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/eslint-plugin-prettier/-/eslint-plugin-prettier-5.2.1.tgz", + "integrity": "sha512-gH3iR3g4JfF+yYPaJYkN7jEl9QbweL/YfkoRlNnuIEHEz1vHVlCmWOS+eGGiRuzHQXdJFCOTxRgvju9b8VUmrw==", "dev": true, "license": "MIT", "dependencies": { "prettier-linter-helpers": "^1.0.0", - "synckit": "^0.8.6" + "synckit": "^0.9.1" }, "engines": { "node": "^14.18.0 || >=16.0.0" @@ -4512,9 +4512,9 @@ } }, "node_modules/prettier": { - "version": "3.3.2", - "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.3.2.tgz", - "integrity": "sha512-rAVeHYMcv8ATV5d508CFdn+8/pHPpXeIid1DdrPwXnaAdH7cqjVbpJaT5eq4yRAFU/lsbwYwSF/n5iNrdJHPQA==", + "version": "3.3.3", + "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.3.3.tgz", + "integrity": "sha512-i2tDNA0O5IrMO757lfrdQZCc2jPNDVntV0m/+4whiDfWaTKfMNgR7Qz0NAeGz/nRqF4m5/6CLzbP4/liHt12Ew==", "dev": true, "license": "MIT", "bin": { @@ -5003,9 +5003,9 @@ } }, "node_modules/synckit": { - "version": "0.8.8", - "resolved": "https://registry.npmjs.org/synckit/-/synckit-0.8.8.tgz", - "integrity": "sha512-HwOKAP7Wc5aRGYdKH+dw0PRRpbO841v2DENBtjnR5HFWoiNByAl7vrx3p0G/rCyYXQsrxqtX48TImFtPcIHSpQ==", + "version": "0.9.1", + "resolved": "https://registry.npmjs.org/synckit/-/synckit-0.9.1.tgz", + "integrity": "sha512-7gr8p9TQP6RAHusBOSLs46F4564ZrjV8xFmw5zCmgmhGUcw2hxsShhJ6CEiHQMgPDwAQ1fWHPM0ypc4RMAig4A==", "dev": true, "license": "MIT", "dependencies": { @@ -5128,9 +5128,9 @@ } }, "node_modules/typescript": { - "version": "5.5.3", - "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.5.3.tgz", - "integrity": "sha512-/hreyEujaB0w76zKo6717l3L0o/qEUtRgdvUBvlkhoWeOVMjMuHNHk0BRBzikzuGDqNmPQbg5ifMEqsHLiIUcQ==", + "version": "5.5.4", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.5.4.tgz", + "integrity": "sha512-Mtq29sKDAEYP7aljRgtPOpTvOfbwRWlS6dPRzwjdE+C0R4brX/GUyhHSecbHMFLNBLcJIPt9nl9yG5TZ1weH+Q==", "dev": true, "license": "Apache-2.0", "bin": { diff --git a/package.json b/package.json index f4da3f8..206eb51 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@cloudflare/voprf-ts", - "version": "0.21.2", + "version": "1.0.0", "description": "voprf-ts: A TypeScript Library for Oblivious Pseudorandom Functions (OPRF)", "author": "Armando Faz ", "maintainers": [ @@ -45,11 +45,11 @@ "homepage": "https://github.com/cloudflare/voprf-ts#readme", "repository": "github:cloudflare/voprf-ts", "engines": { - "node": ">=18" + "node": ">=20" }, "devDependencies": { - "@eslint/js": "9.6.0", - "@noble/curves": "1.4.2", + "@eslint/js": "9.8.0", + "@noble/curves": "1.5.0", "@noble/hashes": "1.4.0", "@types/benchmark": "2.1.5", "@types/eslint__js": "8.42.3", @@ -57,14 +57,14 @@ "benchmark": "2.1.4", "eslint": "8.57.0", "eslint-config-prettier": "9.1.0", - "eslint-plugin-jest": "28.6.0", + "eslint-plugin-jest": "28.8.0", "eslint-plugin-jest-formatting": "3.1.0", - "eslint-plugin-prettier": "5.1.3", + "eslint-plugin-prettier": "5.2.1", "eslint-plugin-security": "3.0.1", "jest": "29.7.0", - "prettier": "3.3.2", + "prettier": "3.3.3", "sjcl": "1.0.8", - "typescript": "5.5.3", + "typescript": "5.5.4", "typescript-eslint": "7.15.0" }, "scripts": { @@ -85,7 +85,7 @@ "format:json": "prettier './**/*.json' '!./node_modules/**' '!./package-lock.json' '!./test/testdata/allVectors_v20.json' --write" }, "optionalDependencies": { - "@noble/curves": "1.4.2", + "@noble/curves": "1.5.0", "@noble/hashes": "1.4.0" } } diff --git a/src/sjcl/tsconfig.json b/src/sjcl/tsconfig.json index cf9be0b..61602a1 100644 --- a/src/sjcl/tsconfig.json +++ b/src/sjcl/tsconfig.json @@ -1,6 +1,4 @@ { "extends": ["../../tsconfig.json", "./tsconfig.compilerOptions.json"], - "files": [ - "index.js" - ] + "files": ["index.js"] } diff --git a/src/tsconfig.cjs.json b/src/tsconfig.cjs.json index 5406650..30ce327 100644 --- a/src/tsconfig.cjs.json +++ b/src/tsconfig.cjs.json @@ -1,7 +1,4 @@ { "extends": "../tsconfig.cjs.json", - "include": [ - "." - ] - + "include": ["."] } diff --git a/src/tsconfig.json b/src/tsconfig.json index c708062..3ae2a24 100644 --- a/src/tsconfig.json +++ b/src/tsconfig.json @@ -1,6 +1,4 @@ { "extends": "../tsconfig.json", - "include": [ - "." - ] + "include": ["."] } diff --git a/test/tsconfig.cjs.json b/test/tsconfig.cjs.json index 80a52a1..8de2829 100644 --- a/test/tsconfig.cjs.json +++ b/test/tsconfig.cjs.json @@ -1,9 +1,6 @@ { "extends": "../tsconfig.cjs.json", - "include": [ - ".", - "testdata/*.json" - ], + "include": [".", "testdata/*.json"], "compilerOptions": { "resolveJsonModule": true }, diff --git a/test/tsconfig.json b/test/tsconfig.json index 36e4630..8f9c62f 100644 --- a/test/tsconfig.json +++ b/test/tsconfig.json @@ -1,9 +1,6 @@ { "extends": "../tsconfig.json", - "include": [ - ".", - "testdata/*.json" - ], + "include": [".", "testdata/*.json"], "compilerOptions": { "resolveJsonModule": true }, diff --git a/tsconfig.json b/tsconfig.json index aaccd49..64aca30 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -2,10 +2,7 @@ "compilerOptions": { "target": "ES2020", "module": "ES2020", - "lib": [ - "ES2020", - "dom" - ], + "lib": ["ES2020", "dom"], "composite": true, "declarationMap": true, "sourceMap": true,