From 74c94517d8acd59636009c8fe9d60f4dfdf00b4c Mon Sep 17 00:00:00 2001 From: ilbertt Date: Tue, 30 Dec 2025 11:36:25 +0100 Subject: [PATCH] chore: update readme --- README.md | 48 ++++++++++++------------------------------------ 1 file changed, 12 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index b9be71e..e9341ea 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,15 @@ # Auth over HTTP -> ⚠️ **Warning**: This is ONLY a proof of concept. It is NOT ready for production use. DO NOT USE THIS IN PRODUCTION. +> [!WARNING] +> This is ONLY a proof of concept. It is NOT ready for production use. DO NOT USE THIS IN PRODUCTION. -This repo contains a proof of concept for HTTP Authentication for canisters. It showcases how to use [HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421.html) to authenticate requests to a canister. +This repo contains a proof of concept for HTTP Authentication for IC canisters. It showcases how to use the [Binary Representation of HTTP Messages](https://www.ietf.org/rfc/rfc9292.html) to send authenticated HTTP requests to a canister. ## Advantages -Using HTTP Message Signatures instead of the custom authentication mechanism has the following advantages: +Using HTTP Authentication instead of the custom authentication mechanism has the following advantages: -- Uses an IETF standard for authentication that does not require [setting custom fields in the request body](https://internetcomputer.org/docs/references/ic-interface-spec#authentication) +- Uses an IETF standard for encoding HTTP messages that does not require [setting custom fields in the request body](https://internetcomputer.org/docs/references/ic-interface-spec#authentication) - Removes the need of [CBOR](https://internetcomputer.org/docs/references/ic-interface-spec#api-cbor) for encoding messages sent to and received from canisters. As a consequence: - Canisters can expose their API using their preferred standard (e.g. OpenAPI, gRPC, etc.) - Existing and widely adopted API standards (REST, GraphQL, etc.) can be used to interact with canisters, enabling popular tools and libraries to be used @@ -16,7 +17,7 @@ Using HTTP Message Signatures instead of the custom authentication mechanism has ## Try It Out -The todo app example is available on mainnet at https://a5eh2-zqaaa-aaaac-qad2a-cai.icp0.io/ +The todo app example is available on mainnet at https://a7hps-myaaa-aaaau-acuna-cai.icp3.io/, behind an [HTTP Gateway](https://github.com/ilbertt/http-gateway) that follows the new protocol. ### Components @@ -26,9 +27,10 @@ Examples: Packages: -- [ic-http-auth](./packages/ic-http-auth/): The canister side library for verifying HTTP Message Signatures -- [http-auth-js](./packages/http-auth-js/): The client side library for sending signed HTTP requests to a canister +- [ic-http](./packages/ic-http/): The canister side library for encoding and decoding HTTP messages +- [`@icp-sdk/http`](./packages/http-auth-js/): The client side library for sending signed HTTP requests to a canister - [insomnia-plugin-ic-http-auth](./packages/insomnia-plugin-ic-http-auth/): An [Insomnia](https://insomnia.rest/) plugin for sending signed HTTP requests to a canister +- [local-replica](./packages/local-replica/): A binary that runs PocketIC and an HTTP Gateway locally ### Prerequisites @@ -43,50 +45,24 @@ After cloning the repository, install the dependencies: ```shell pnpm i -dfx deps pull ``` Then, start the local network: ```shell -dfx start --background --clean +cargo run -p local-replica ``` Then, deploy the canisters: ```shell -dfx deps deploy dfx deploy ``` In the output, you will see a URL similar to `http://.localhost:4943`. Open this URL in your browser to see the todo app running locally. -## Benchmarks - -At the current state, the proof of concept verifies signatures of requests sent to the canister inside the canisters directly. Verifying canister signatures is - -We use [Canbench](https://github.com/dfinity/canbench) to benchmark the performance of some functions of the [ic-http-auth](./packages/ic-http-auth/) package. - -To run the benchmarks, first install the `canbench` CLI: - -```shell -cargo install canbench -``` - -Then, run the benchmarks: - -```shell -cd packages/ic-http-auth -canbench -``` - -The latest results can be found in the [canbench_results.yml](./packages/ic-http-auth/canbench_results.yml) file. - -> Note: if you want to update the benchmarks results, you can run the benchmarks with the `--persist` flag: -> -> ```shell -> canbench --persist -> ``` +> [!NOTE] +> Currently, the HTTP Gateway running locally does not support the old HTTP Protocol, so the Internet Identity frontend will not work locally. You can either disable authentication locally or use the app deployed on mainnet. ## Contributing