From 0c96c0b8bbf2a3e01bd8d344119e418708346c61 Mon Sep 17 00:00:00 2001 From: Mark Krasner Date: Thu, 17 Oct 2024 11:48:18 -0400 Subject: [PATCH 1/6] Initial save for TACo with composedb example --- .../examples/taco-access-control.mdx | 116 ++++++++++++++++++ sidebars.ts | 5 + 2 files changed, 121 insertions(+) create mode 100644 docs/composedb/examples/taco-access-control.mdx diff --git a/docs/composedb/examples/taco-access-control.mdx b/docs/composedb/examples/taco-access-control.mdx new file mode 100644 index 00000000..312a13cc --- /dev/null +++ b/docs/composedb/examples/taco-access-control.mdx @@ -0,0 +1,116 @@ +# TACo with ComposeDB + +*Store sensitive data on ComposeDB, using decentralized access control to enforce fine-grained decryption rights.* + +This guide explains how to integrate [TACo](https://docs.threshold.network/applications/threshold-access-control) into ComposeDB, which enables the storing and sharing of non-public data on Ceramic. A more detailed version of this tutorial is available [here](https://docs.threshold.network/app-development/threshold-access-control-tac/integration-guides/ceramic-+-taco). + +## TACo Overview + +TACo is a programmable encrypt/decrypt API for applications that handle sensitive user data, without compromising on privacy, security or decentralization. TACo offers a distinct alternative to centralized, permissioned, and TEE-dependent access control services. + +TACo is the first and only end-to-end encrypted data sharing layer in which access to data payloads is always collectively enforced by a distributed group. Today, over 120 service-providers permissionlessly run TACo clients. They independently validate whether a given data request satisfies pre-specified conditions, only then provisioning decryption material fragments for client-side assembly, decryption, and plaintext access. + +TACo offers a flexible access control framework and language, in which access conditions can be configured individually or combined logically. This approach enables developers to chain conditions together and facilitates dynamic access flows. For example, predicting the input to one access condition on the output of a previous access condition can also be programmatically combined with on-chain (and off-chain) authentication methods. + +TACo’s encrypt/decrypt API – [taco-web](https://github.com/nucypher/taco-web) – is straightforward to integrate into any web app and usable in parallel with core Web3 infrastructure like Ceramic. + +### Use Cases + +- **Social networks & Knowledge Bases:** Leverage Ceramic's verifiable credentials and TACo's credential-based decryption to ensure that private user-generated content is only viewable by those who are supposed to see it, and nobody else. + +- **IoT event streams:** Let sensitive data flow from sensors to legitimate recipients, without trusting an intermediary server to handle the routing and harvest metadata. For example, a medical professional can be issued a temporary access token if a patient's wearable output data rises above a certain threshold. + +- **LLM chatbots:** Messages to and from a chatbot should be 100% private, not mined by a UX-providing intermediary. Harness Ceramic's web-scale transaction processing and TACo's per-message encryption granularity to provide a smooth and private experience for users of LLM interfaces. + +## Example Application & Repo + +The "TACo with ComposeDB Message Board [Application](https://github.com/nucypher/taco-composedb/tree/main)" is provided as an example and reference for developers – illustrating how TACo and ComposeDB can be combined in a browser-based messaging app. Once installed, a simple UI shows how messages can be encrypted by data producers with access conditions embedded, and how data consumers can view messages *only* if they satisfy those conditions. Launching the demo also involves running a local Ceramic node, to which TACo-encrypted messages are saved and immediately queryable by data requestors. + +The following sections explain the core components of TACo’s access control system – access conditions, encryption, and decryption. + +### Specifying access conditions & authentication methods + +There are two ways in which a recipient, or data consumer, must prove their right to access the private data – (1) authentication and (2) condition fulfillment. The data producer must specify the authentication methods and condition(s) before encrypting the private data, as this configuration is embedded alongside the encrypted payload. + +In the example snippet below, we are using RPC conditions. The function will check the *data consumer’s* Ethereum wallet balance, which they prove ownership of via the chosen authentication method – in this case via a EIP4361 (Sign-In with Ethereum) message. Note that this message has already been solicited and utilized by the application, analogous to single-sign-on functionality. This setup is the same as in the demo code above and can be viewed directly in the [repo](https://github.com/nucypher/taco-composedb/blob/main/src/fragments/chatinputbox.tsx#L26-L34). + +```TypeScript +import { conditions } from "@nucypher/taco"; + +const rpcCondition = new conditions.base.rpc.RpcCondition({ + chain: 80002, + method: 'eth_getBalance', + parameters: [':userAddressExternalEIP4361'], + returnValueTest: { + comparator: '>', + value: 0, + }, +}); +``` + +### Encrypting & saving the data + +To complete the encryption step, the following are added as arguments: +a. `domain` – testnet or mainnet +b. `ritualId` – the ID of the cohort of TACo nodes who will collectively manage access to the data +c. a standard web3 provider + +The output of this function is a payload containing both the encrypted data and embedded metadata necessary for a qualifying data consumer to access the plaintext message. + +```TypeScript +import { initialize, encrypt, conditions, domains, toHexString } from '@nucypher/taco'; +import { ethers } from "ethers"; + +await initialize(); + +const web3Provider = new ethers.providers.Web3Provider(window.ethereum); +const ritualId = 0 +const message = "I cannot trust a centralized access control layer with this message."; +const messageKit = await encrypt( + web3Provider, + domains.TESTNET, + Message, + rpcCondition, + ritualId, + web3Provider.getSigner() +); +const encryptedMessageHex = toHexString(messageKit.toBytes()); +``` + +### Querying & decrypting the data + +Data consumers interact with the TACo API via the `decrypt` function. They include the following arguments: + +a. Provider +b. Domain +c. EncryptedMessage +d. ConditionContext + +The conditionContext is a way for developers to programmatically provide required data consumer authentication methods mapped to specific access conditions – all at decryption time. + +```TypeScript +import {conditions, decrypt, Domain, encrypt, ThresholdMessageKit} from '@nucypher/taco'; +import {ethers} from "ethers"; + +export async function decryptWithTACo( + encryptedMessage: ThresholdMessageKit, + domain: Domain, + conditionContext?: conditions.context.ConditionContext +): Promise { + const provider = new ethers.providers.Web3Provider(window.ethereum); + return await decrypt( + provider, + domain, + encryptedMessage, + conditionContext, + ) +} +``` + +Note that the EIP4361 authentication data required to validate the user address (within the condition) is supplied via the `conditionContext` object. To understand this component better, check out the demo [repo](https://github.com/nucypher/taco-composedb/blob/main/src/fragments/chatcontent.tsx#L47). + +### Using ComposeDB & TACo in production + +For Ceramic, connect to Mainnet (`domains.MAINNET`). + +For TACo, a funded Mainnet ritualID is required – this connects the encrypt/decrypt API to a cohort of independently operated nodes and corresponds to a DKG public key generated by independent parties. A dedicated ritualID for Ceramic + TACo projects will be sponsored soon. Watch for updates here. diff --git a/sidebars.ts b/sidebars.ts index fa299d2a..3f6abdc5 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -241,6 +241,11 @@ const sidebars: SidebarsConfig = { type: "doc", id: "composedb/examples/verifiable-credentials", label: "Verifiable Credentials" + }, + { + type: "doc", + id: "composedb/examples/taco-access-control", + label: "TACo with ComposeDB" } ] }, From 54500ac44db79a86d4c1a74ce5a68c14dbdbc889 Mon Sep 17 00:00:00 2001 From: Mark Krasner <70119343+mzkrasner@users.noreply.github.com> Date: Mon, 21 Oct 2024 12:16:51 -0400 Subject: [PATCH 2/6] TACo introduction summary edits Co-authored-by: Arjun Hassard --- docs/composedb/examples/taco-access-control.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/composedb/examples/taco-access-control.mdx b/docs/composedb/examples/taco-access-control.mdx index 312a13cc..9ca7fac8 100644 --- a/docs/composedb/examples/taco-access-control.mdx +++ b/docs/composedb/examples/taco-access-control.mdx @@ -10,7 +10,8 @@ TACo is a programmable encrypt/decrypt API for applications that handle sensitiv TACo is the first and only end-to-end encrypted data sharing layer in which access to data payloads is always collectively enforced by a distributed group. Today, over 120 service-providers permissionlessly run TACo clients. They independently validate whether a given data request satisfies pre-specified conditions, only then provisioning decryption material fragments for client-side assembly, decryption, and plaintext access. -TACo offers a flexible access control framework and language, in which access conditions can be configured individually or combined logically. This approach enables developers to chain conditions together and facilitates dynamic access flows. For example, predicting the input to one access condition on the output of a previous access condition can also be programmatically combined with on-chain (and off-chain) authentication methods. +TACo offers a flexible access control framework and language, in which access conditions can be configured individually and combined logically. Developers can compose dynamic access workflows for their users – for example, using +the sequential conditions feature to predicate the input to a given access condition on the output of a previous condition or call. Conditions may also be programmatically combined with both on-chain and off-chain authentication methods. TACo’s encrypt/decrypt API – [taco-web](https://github.com/nucypher/taco-web) – is straightforward to integrate into any web app and usable in parallel with core Web3 infrastructure like Ceramic. From 2b0ffe6bfc5a2753fc244a1f75f611b7cb7c414a Mon Sep 17 00:00:00 2001 From: Mark Krasner <70119343+mzkrasner@users.noreply.github.com> Date: Mon, 21 Oct 2024 12:17:35 -0400 Subject: [PATCH 3/6] Better specificity edits around conditionContext Co-authored-by: Arjun Hassard --- docs/composedb/examples/taco-access-control.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/composedb/examples/taco-access-control.mdx b/docs/composedb/examples/taco-access-control.mdx index 9ca7fac8..49cc69de 100644 --- a/docs/composedb/examples/taco-access-control.mdx +++ b/docs/composedb/examples/taco-access-control.mdx @@ -87,7 +87,7 @@ b. Domain c. EncryptedMessage d. ConditionContext -The conditionContext is a way for developers to programmatically provide required data consumer authentication methods mapped to specific access conditions – all at decryption time. +`conditionContext` is a way for developers to programmatically map methods for authenticating a data consumer to specific access conditions – all executable at decryption time. For example, if the condition involves proving ownership of a social account, authenticate via OAuth. ```TypeScript import {conditions, decrypt, Domain, encrypt, ThresholdMessageKit} from '@nucypher/taco'; From d0846f899ae10c253f34e1948624bc624e764fde Mon Sep 17 00:00:00 2001 From: Mark Krasner <70119343+mzkrasner@users.noreply.github.com> Date: Mon, 21 Oct 2024 12:18:23 -0400 Subject: [PATCH 4/6] Better IoT use case summary Co-authored-by: Arjun Hassard --- docs/composedb/examples/taco-access-control.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/composedb/examples/taco-access-control.mdx b/docs/composedb/examples/taco-access-control.mdx index 49cc69de..1f0fd536 100644 --- a/docs/composedb/examples/taco-access-control.mdx +++ b/docs/composedb/examples/taco-access-control.mdx @@ -19,7 +19,7 @@ TACo’s encrypt/decrypt API – [taco-web](https://github.com/nucypher/taco-web - **Social networks & Knowledge Bases:** Leverage Ceramic's verifiable credentials and TACo's credential-based decryption to ensure that private user-generated content is only viewable by those who are supposed to see it, and nobody else. -- **IoT event streams:** Let sensitive data flow from sensors to legitimate recipients, without trusting an intermediary server to handle the routing and harvest metadata. For example, a medical professional can be issued a temporary access token if a patient's wearable output data rises above a certain threshold. +- **IoT event streams:** Let data flow from sensors to legitimate recipients, without trusting an intermediary server to handle the routing and harvest sensitive (meta)data. For example, a medical professional can be issued a temporary access token if the output data from a patient's wearable device rises above a certain threshold. - **LLM chatbots:** Messages to and from a chatbot should be 100% private, not mined by a UX-providing intermediary. Harness Ceramic's web-scale transaction processing and TACo's per-message encryption granularity to provide a smooth and private experience for users of LLM interfaces. From d65dda49939ee7fb80c10ede1c0e26e4267f7615 Mon Sep 17 00:00:00 2001 From: Mark Krasner <70119343+mzkrasner@users.noreply.github.com> Date: Mon, 21 Oct 2024 12:19:08 -0400 Subject: [PATCH 5/6] Verbiage clarity edits for LLM chatbots use case Co-authored-by: Arjun Hassard --- docs/composedb/examples/taco-access-control.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/composedb/examples/taco-access-control.mdx b/docs/composedb/examples/taco-access-control.mdx index 1f0fd536..c551149a 100644 --- a/docs/composedb/examples/taco-access-control.mdx +++ b/docs/composedb/examples/taco-access-control.mdx @@ -21,7 +21,7 @@ TACo’s encrypt/decrypt API – [taco-web](https://github.com/nucypher/taco-web - **IoT event streams:** Let data flow from sensors to legitimate recipients, without trusting an intermediary server to handle the routing and harvest sensitive (meta)data. For example, a medical professional can be issued a temporary access token if the output data from a patient's wearable device rises above a certain threshold. -- **LLM chatbots:** Messages to and from a chatbot should be 100% private, not mined by a UX-providing intermediary. Harness Ceramic's web-scale transaction processing and TACo's per-message encryption granularity to provide a smooth and private experience for users of LLM interfaces. +- **LLM chatbots:** Messages to and from a chatbot should be 100% private, not mined by a UX-providing intermediary. Harness Ceramic's web-scale transaction processing and TACo's per-message encryption/condition granularity to provide a smooth and safe experience for users of LLM interfaces. ## Example Application & Repo From 617752afda1b89b69d76af4b48ae700baea51a0d Mon Sep 17 00:00:00 2001 From: Mark Krasner <70119343+mzkrasner@users.noreply.github.com> Date: Mon, 21 Oct 2024 12:19:48 -0400 Subject: [PATCH 6/6] Slight formatting modifications for method arguments Co-authored-by: Arjun Hassard --- docs/composedb/examples/taco-access-control.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/composedb/examples/taco-access-control.mdx b/docs/composedb/examples/taco-access-control.mdx index c551149a..3504533f 100644 --- a/docs/composedb/examples/taco-access-control.mdx +++ b/docs/composedb/examples/taco-access-control.mdx @@ -82,10 +82,10 @@ const encryptedMessageHex = toHexString(messageKit.toBytes()); Data consumers interact with the TACo API via the `decrypt` function. They include the following arguments: -a. Provider -b. Domain -c. EncryptedMessage -d. ConditionContext +a. `provider` +b. `domain` +c. `encryptedMessage` +d. `conditionContext` `conditionContext` is a way for developers to programmatically map methods for authenticating a data consumer to specific access conditions – all executable at decryption time. For example, if the condition involves proving ownership of a social account, authenticate via OAuth.