nucypher / taco-web

🌮 A TypeScript client for TACo (Threshold Access Control)

taco-web

A TypeScript library for interacting with access control functionality in the browser.

Full documentation can be found here.

Warning

taco-web is under active development:

• We expect breaking changes.

Installation

pnpm add @nucypher/taco

Tutorial

To learn more, follow the tutorial at Threshold Network's docs.

Examples

See taco-web/examples to find out how to integrate taco-web into your favorite web framework.

We also provide demos of TACo applications:

• taco-demo
• taco-nft-demo

These examples showcase integration with web applications utilizing an end-to-end flow of creating encrypted data with associated conditions and enacting access-controlled decryption.

Contributing

If you would like to contribute to the development of taco-web, please see our Contributing Guide. You can also join our Discord and say hello!

taco-web's Issues

Documentation link is broken

@theref the documentation link https://nucypher.github.io/nucypher-ts/ takes you to http://jamescampbell.org.uk/

Alice's public key is unintentionally passed to Enrico's Constructor

This is a two-part issue regarding the definition of the Enrico class and it's usage.

The type annotation for Enrico.verifyingKey is PublicKey but actually needs to be PrivateKey.

https://github.com/nucypher/nucypher-ts/blob/sdk/src/characters/enrico.ts#L13

and the public key is being set as an attribute instead of the private key.

https://github.com/nucypher/nucypher-ts/blob/sdk/src/characters/enrico.ts#L17

The motivation of including an optional private key in enrico's constructor is so that a particular enrico can be recreated to sign-then-encrypt plaintexts. Then, when Bob successfully decrypts a message he can verify that it did indeed come from the correct Enrico. However this functionality is not currently implemented.

The naming convention for verifyingKey has led to name shadowing and unintentionally passing Alice's public key to be used as enrico's private key. Even though it's not currently implemented, I surmise that the public key's bytes are the correct format for usage as a private key. This may lead to leaking enrico's private key which represents a potential security vulnerability to impersonate Enrico.

https://github.com/nucypher/nucypher-ts/blob/sdk/src/sdk/strategy.ts#L98

  constructor(
    policyEncryptingKey: PublicKey,
    verifyingKey?: PublicKey,   // <<<<<< this should be PrivateKey
    conditions?: ConditionSet
  ) {
    this.policyEncryptingKey = policyEncryptingKey;
    this.verifyingKey = verifyingKey ?? SecretKey.random().publicKey();  // <<<< enrico secret key
    this.conditions = conditions;
  }

Some attributes are being serialized to pointers and not an underlying JSON object

Update references to IBEX network in code

There are some references to the deprecated ibex network in nucypher-ts code.

https://github.com/nucypher/nucypher-ts/search?q=ibex

Handle conditions data as input to Enrico actions

Redesign `Web3Provider`

• Web3Provider is a wrapper for web3 providers
• It should provide a provider-agnostic way to getAddress, sign, and access other provider methods (such as transacting, etc.)
• Currently, it's only a thin wrapper for ethers.providers.Web3Provider
• Question:
  • Do we want to support providers other than ethers?
  • Or do we want to remove this abstraction and rely on ethers completely?
• Found an old version of this issue: https://github.com/nucypher/tdec/issues/65

Add ability to override default strategy `startDate` and `endDate`

This may just be for training wheels in the early days, but it would required be able to configure for time frames different than a month in production

https://github.com/nucypher/nucypher-ts/blob/ab2b0bec47ca25aca0d3f0e474f44b65823a7f35/src/sdk/strategy.ts#L73-L74

Retire payment stub from TAC SDK (& decide future of SubscriptionManager)

• Remove dependency on policy creation with SubscriptionManager
• Mandates update of examples & docs
• This is a MAJOR breaking change
• RFC: @KPrasch @arjunhassard

POAP based conditions

https://documentation.poap.tech/docs/popular-flow#2-token-gating-with-poaps

Provide a default character `Config`

• Use a default porterUri based on a selected network
• Add a default community Porter instance for mainnet https://porter.nucypher.community/
• Use Config to override default config

Default Chain ID value in conditions

I found a little bit confusing the default values taken in the Conditions doc:

There is no reference to what network will be taken by default. If you inspect the code, the Göerli testnet will be taken. So I'm wondering myself:

Should we have a default value for this? Or should be mandatory to specify the chain ID when creating the Conditions object? What should be the default value in the former case, Ethereum mainnet or Göerli?

_Originally posted by @manumonti [and discussion] in #179

Revoke blockchain policy

• Currently there is no way for Alice to revoke a blockchain policy once it was granted to Bob
• Implement revocation mechanism

Misuse-resistance audit (nucypher-ts <> nc/nc)

Update PRE objects to use Cohort

Switch to chain_id for conditions instead of using names

Off Chain condition examples using chainlink

If Bob performs local retrieval, Handle conditions parsing for the creation of ReencryptionRequests

Update `SubscriptionManager` contract

• Upgrade sources & related logic according to nucypher/nucypher-contracts#2
  • New size param
  • Policy cost logic moved to the contract

Use web3 provider to facilitate transactions

• Currently, transactions are signed and paid for using Ethereum account derived from secret key of Alice.
• Use browser-provided account instead

Batch Granting Support

Awaits specification from: nucypher/nucypher-contracts#37

Update main README file

The Readme file seems to be outdated with the latest changes in the code.

Some changes that should be done are:

• Supported networks section

• References to the deprecated ibex network

• References to makeTDecEncrypter function

Key Value return value parameter for condition evaluation

Produce `ConditionContext` from `ConditionSet`

• ConditionSet knows how to produce parameters to be contained in ConditionContext
• ConditionSet exposes buildContext method that may be called to request user interaction (for example, signing a message with web3 provider)
• Related issue: #79

Update protocol in accordance with `nucypher-core`

• Include changes from nucypher/nucypher#2809

[Gitbook docs] Lack of information in Get Started about WASM bindings

While I was trying to build a new app, I found a lack of information in Get Started with TAC. This caused that I got stuck in the Step 2: Build a Cohort

IMHO, the use of WASM bindings should be documented here as a kind of "prerequisite" or "step 0". The problem I found trying to build a basic app is:

1. nucypher-ts uses nucypher-core as a dependency. nucypher-core contains WASM bindings.
2. To run nucypher-ts (and hence, WASM from nucypher-core) we need a bundler that understands what WASM is.
3. Depending on what project we're running, two good options could be to use Webpack or Craco, but in any case, we need to tell them how to load WASM.

In any case, we have some examples of how to start building a new dApp here, here, and here, that could be linked in this documentation.

_Originally posted by @manumonti in #179

Remote Ursulas don't recognize arrangement's

• Ursulas verify policy payments by calling PolicyManager::getArrangementInfo. However, they fail to recognize existence of their arrangement and throw Policy.Unknown instead.
• This in turn causes Porter to throw error-out on retrieveAndDecrypt call with error: Ursula ((Ursula)⇀xxxxxxxx↽ (0x0...0)) claims not to not know of the policy HRAC(abcde). Has access been revoked?
• This happens when working with Ibex and Lynx nodes, but not with a local node running on 957250c6d8c8a80c08dbd5211188b297b7db1441

[Gitbook docs] Outdated reference to Rinkeby when deploying a new strategy

In section 4. Build a Strategy, the code shows references to Rinkeby network.

We should use Mumbai network or Polygon network here as those are the "payment networks" currently available in nucypher-ts.

Remove deprecated `duration_periods` field

• Update Porter interface according to KPrasch/nucypher#33

ENS name ownership condition

In EVM condition, validate `functionAbi` against `parameters` and `method`

• EvmCondition builder should extract the method name and method parameters from functionAbiand validate them against user-provided parameters and method

Adapt nucypher-ts to accept Matic (and other L2s) RPC endpoints

@piotr-roslaniec:

• Adding support for EVM-compatible L1s is going to be as easy as adding contract and network configuration for a new network.
• nucypher-ts already works on Mumbai (Polygon testnet) in some limited capacity (policy creation). Further work needs to be done in other areas of the network (Ursulas, Porter) to enable complete user flows such as granting and revocation of policies.
• In order to deploy nucypher-ts on Mumbai we had to rewrite some of the policy validation logic - The logic of SubscriptionManager::createPolicy is somewhat different than PolicyManager::createPolicy
• This issue is blocked by the current incompatibility with nucypher
• Related: #31

Create tests to check the code exposed in documentation

In Threshold Access Control (TAC) documentation we have a tutorial with nucypher-ts code snippets.

Logically, every change in the nucypher-ts API should be reflected in the documentation. But this process can be easily forgotten.

Some automated tests that help in detecting changes in the API that would affect the documentation could be convenient.

In words of Piotr:

    Perhaps we should have a separate test suite in `nucypher-ts`, `test/docs`, where we keep code examples to be used in documentation. Then, we could copy&paste them with confidence instead of doing a QA on them every time we update the API.

Originally posted by @piotr-roslaniec in #142 (comment)

Enable support for ERC1155-based conditions

• Currently blocked by node implementation (status)
• Partial support is available (source). See example below:

 "ERC1155_balance_batch": {
    "contractAddress": "0xaDD9D957170dF6F33982001E4c22eCCdd5539118",
    "standardContractType": "ERC1155",
    "chain": 1,
    "method": "balanceOfBatch",
    "parameters": [
      [":userAddress",":userAddress",":userAddress",":userAddress"],
      [1,2,10003,10004]
    ],
    "returnValueTest": {
      "comparator": ">",
      "value": 0
    }
  },

• Add 'ERC1155' to EvmCondition.STANDARD_CONTRACT_TYPES
• Implement "batch support" variant or wait for "full support" variant
• Add relevant tests
• Test manually on Tapir

Remove Alice's secret key from JSON serializers and DeployedStrategy

In an effort to reduce the exposure of sensitive secret material and prevent Alice's private keys from being accidentally transmitted (PRE-adapted proof-of-concept), Alice's secret key can be removed from Strategy's JSON serializer and from DeployedStrategy completely.

https://github.com/nucypher/nucypher-ts/blob/sdk/src/sdk/strategy.ts#L24
https://github.com/nucypher/nucypher-ts/blob/sdk/src/sdk/strategy.ts#L32

As a result, Strategy will contain private information which is not intended for transport, and DeployedStrategy will contain only public information. Doing so potentially overlaps with the objectives in #99.

A follow-up question: is there any reason why a (PRE-adapted-CBD) policy author will ever need to recover Alice's secret key's after generating KFrags and subsequently publishing the treasure map?

Add revocation to nucypher-ts

Dependent on upstream task nucypher/tdec/issues/17

Add `ConditionContext` to `PostRetrieveCFragsRequest`

• Use context to store certain parameters from ConditionSet that require user interaction.
• ConditonContext is a key-value map, Record<string, string|number>
• Related issue: #77
• Related PR: https://github.com/nucypher/nucypher-ts/pull/77/files#r952763415

Improve error messages for retrieval and decryption

Currently, if during Bob.retrieveAndDecrypt we fail to retrieve a minimal amount of cFrags, we throw the following error:

Not enough cFrags retrieved to open capsule Capsule:xxxxxxxxxxxxxx. Was the policy revoked?

However, there are many different reasons why this could happen:

• Policy was revoked
• Policy was created, but not enacted (see delayed enact flow)
• Ursulas fail to provide Porter with cFrags

How should we address these scenarios?

• Policy was revoked
  • Currently not implemented, remove revocation from the error message.
  • In the future, check with the SubscriptionManager contract.
• Policy was created, but not enacted
  • Check with the SubscriptionManager contract? That would require a web3 provider for Bob.
• Ursulas fail to provide Porter with enough cFrags
  • Detect this issue early and throw a relevant error.

Ordering of these checks will be significant.

Implement versioning of bytes serializable protocol entities

• Implement changes in serialization from nucypher/nucypher#2767 and nucypher/nucypher#2805

Add support for user-defined parameters in `returnValueTest`

• Support changes from nucypher/nucypher#3032
• returnTestValue is expecting the following structure:

{
  "comparator": ">",
  "value": 100,
  "index": 0,
}

Where the index is the index of some element in the array returned by the returnTest that we want to use with the comparator:

returnTest()[index] > 100

Authorized key fragment expiration

• Implement AuthorizedKeyFrag expiration according to nucypher/nucypher#2827
• Delayed until merge of aforementioned issue

Error on creating policy

Description

Getting the following error in the console when clicking "Go" to create policy in react-craco example:

Uncaught (in promise) Error: No contracts found for chainId: 1

Screenshot

Here is a screenshot for the same:

Simplify crypto powers

• Currently, crypto powers are used as an abstraction to perform operations that require a secret key.
• Refactor crypto powers into simpler and more coherent abstraction, perhaps composing it onto Keyring.

Unnecessary provider requirement in `DeployedStrategy.fromJSON`

Any need to provide a Provider in fromJson and fromObj here? Possibly future proofing the api? If not necessary it would be nice to remove it as I think the provider is only needed for deploying a new Strategy

https://github.com/nucypher/nucypher-ts/blob/ab2b0bec47ca25aca0d3f0e474f44b65823a7f35/src/sdk/strategy.ts#L146

Provide a convenience method for making an encrypter in `DeployedStrategy`

• Currently, using multiple Conditions with a single DeployedStrategy is cumbersome. See example code below:

deployedStrategy!.encrypter.conditions = myConditions;
const encryptedMessage = deployedStrategy!.encrypter.encryptMessage(plaintext);

• Introduce a DeployedStrategy.makeEncrypter(condition) method to produce per-condition encryptor
  • Avoid condition re-assigment in DeployedStrategy, i.e. it should be immutable
• See the API sketch below:

const encrypter = deployedStrategy.makeEncrypter(myConditions)
const encryptedMessage =  encrypter.encryptMeessage(message)

// Override previous conditions
encrypter.encrypt_message(message, newConditions)

• RFC: @derekpierre @jMyles @theref
• Discussion on Discord

Improve Cohort functionality to be more collusion resistant

We didn't really delve into the sampling/re-sampling sequence in our tdec discussions, so it's reasonable in the interest of fulfilling Milestone 5 to temporarily define Cohorts as a static list of pre-specified node addresses.

However, in the medium-term, something resembling Porter's include logic is more collusion-resistant, more redundant, economically fairer, and confers greater customizability to the adopter.

The sampling mechanism as a whole may need a rethink in the context of tdec, but a core principle of the work token model is not to unnecessarily disadvantage new stakers (since staker population growth mitigates centralization and supports the token price). Even though fees are currently distributed/rebated purely by stake size, concentrating actual fragment-handling work amongst early stakers (via the problem with defaults mentioned here https://github.com/nucypher/tdec/issues/51#issuecomment-1249947113), still foments a imbalance in power (i.e. if you're not on the dominant cohort lists, you have less political power even with the same size stake) and could even hasten a DAO-driven change to said fee model (to address the discordance between work & remuneration).

Originally posted by @arjunhassard in #86 (comment)

Make easy the WASM artifact load from nucypher-core

Related to #119.

When we try to add as a dependency nucypher-ts into a web app, this loads a WASM artifact from nucypher-core package. This requires having a bundler that understands what WASM is.

The objective of this issue is to make this as easy as possible. How to do it is a matter of research.

One option could be to pack wasm-pack artifacts (nucypher-core WASM) into a multi-platform JS package. This is how we're doing at the moment.

Since its a ts project, consider using Zod instead of joi?

I noticed that you're using joi in condition assertions. Its much more fully developed ground up for typescript. @piotr-roslaniec

[EPIC] nucypher-ts MVP

This is a rough draft of several nucypher/nucypher-ts modules in an attempt to tie together a boilerplate for the rest of the library.

The idea is to reimplement existing nucypher/nucypher flows using Porter as a replacement for all network interactions. I will be using acceptance and integration tests from nucypher as a reference point. The code borrows heavily from nucypher/nucypher codebase, especially abstractions such as policies, crypto powers, keyrings, etc.

The goal is to have at least one "user story" working. A lot of implementations will be stubbed-out initially, especially ones related to Porter or blockchain transactions.

Further down the road, nucypher/NuSnap will be updated to implement nucypher/nucypher-ts.

The design of the user-facing library is not final and will be rewritten heavily. As always, all comments are welcome!

To Do

• Implement a use story - "Alice grants access to Bob through a new blockchain policy"
  • Alice / Enrico encrypts a message
  • Alice creates a blockchain policy
  • Alice publishes blockchain policy to blockchain
  • Bob retrieves treasure map from blockchain policy sidechannel
  • Bob retrieves capsule fragments
  • Bob decrypts the message
• Characters
  • Alice
  • Bob
  • Porter
  • Ursula Currently replaced with Porter proxy
  • Enrico
• Ethereum
  • Web3 client
  • Contracts
• Crypto - Review selection of js libs
  • HKDF with Blake2 (64) Using keccak256 for now
  • Keccak256
  • ECDSA
  • SHA256
• Should nucypher-ts be browser and Node.js compatible? Focus on browser compatibility
• Utilities
  • Compatibility with Serialization (Bytesplitter)
  • Compatibility with NuCypher constants (constant-sorrow)
• Design decisions (user API)
  • Handling transactions, web3 provider
  • Remove Buffer usage
• Cryptopowers:
  • Interface with NuSnap Postponed
  • Instantiate from seed (secret ket), fromSecretKey
  • Instantiate from web3 provider, fromWeb3 Connect a web3 provider instead

Relevant PRs

• #3
• #4
• #5
• #7
• #12
• #16

Create conditions errors in code

I'm not sure if this is a documentation issue or a nucypher-ts bug.

If we check Conditions.RpcCondition docs, we see there are two ways of creating this condition. But both of them return errors if used as described in docs:

1. Using RpcCondition:

const const rpc = new Conditions.RpcCondition({
  chain: 1,
  method: 'eth_getBalance',
  parameters: [
      ":userAddress",
      "latest"
    ],
  returnValueTest: {
    comparator: ">=",
    value: 10000000000000
  }
});

2. Using Condition:

const rpcConfig = {
  contractAddress: '',
  standardContractType: '',
  chain: 1,
  method: 'eth_getBalance',
  parameters: [':userAddress', 'latest'],
  returnValueTest: {
    comparator: '>=',
    value: 10000000000000,
  },
};
const rpc = Conditions.Condition(rpcConfig);

If we use in the code the former one, we get an error:

"returnValueTest.value" must be a string

This error is fixed if we pass the Object key value as string instead of as number:

  returnValueTest: {
    comparator: ">=",
    value: "10000000000000"
  }

However, in the latter option, we can use both, string and number types, for the key value.

Should we homogenize this behavior by allowing only one type (string or number)?

Another issue is that the latter option returns error:

Error: Request failed with status code 500

It only works if we delete the two first keys of the config object:

const rpcConfig = {
  contractAddress: '', // DELETE THIS
  standardContractType: '', // DELETE THIS
  chain: 1,
  method: 'eth_getBalance',
  parameters: [':userAddress', 'latest'],
  returnValueTest: {
    comparator: '>=',
    value: 10000000000000,
  },
};

Also, we have the same problems in Conditions.TimelockCondition.

[Gitbook docs] Add mention to the two different networks: payments and CBD on-chain state

I think we should at least mention in Get started that there are two possible networks. One for CBD/on-chain state (mainnet Ethereum, testnet Görli) and other for "payments" (mainnet Polygon, testnet Polygon Mumbai). It could be confusing to use Mumbai in Build a Strategy without any previous reference about this.

_Originally posted by @manumonti in #179