From 14eb7d978486b77de1186fa3fa776266807b0a35 Mon Sep 17 00:00:00 2001 From: James Campbell Date: Thu, 18 Jul 2024 10:40:38 +0200 Subject: [PATCH 1/8] docs: Add simple structure to `CONTRIBUTING.md` --- CONTRIBUTING.md | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 540ac6640..ac64a4788 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,15 @@ # Contribution Guide +- [Quick Start](#quick-start) + - [Setup](#setup) + - [Development](#development) + - [Documentation](#documentation) + - [Publishing](#publishing) +- [External Api](#external-api) +- [Design and Architecture](#design-and-architecture) +# Quick Start + +### Setup Download, install, build, and test with: ```bash @@ -8,7 +18,7 @@ cd taco-web pnpm install ``` -## Development +### Basic Development Commands Execute common tasks with: @@ -19,7 +29,7 @@ pnpm lint pnpm fix ``` -## Documentation +### Documentation Build and publish documentation with: @@ -28,6 +38,11 @@ pnpm doc pnpm doc:publish ``` -## Publishing +### Deployment TODO: Update after implementing automated publishing. + +# External Api +This is the api that we expose to developers. + +# Design and Architecture \ No newline at end of file From 930f0b46c347adde8e108054e69204c09cbccb51 Mon Sep 17 00:00:00 2001 From: James Campbell Date: Thu, 18 Jul 2024 11:19:40 +0200 Subject: [PATCH 2/8] docs: Fix broken links and update docs command --- CONTRIBUTING.md | 5 +++-- packages/taco/README.md | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ac64a4788..65a4ee63f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,8 +34,8 @@ pnpm fix Build and publish documentation with: ```bash -pnpm doc -pnpm doc:publish +pnpm typedoc +pnpm typedoc:publish ``` ### Deployment @@ -44,5 +44,6 @@ TODO: Update after implementing automated publishing. # External Api This is the api that we expose to developers. +It is defined in [`packages/taco/src/taco.ts`](https://github.com/nucypher/taco-web/blob/main/packages/taco/src/taco.ts) # Design and Architecture \ No newline at end of file diff --git a/packages/taco/README.md b/packages/taco/README.md index bd94816f4..9f54511ce 100644 --- a/packages/taco/README.md +++ b/packages/taco/README.md @@ -1,6 +1,6 @@ # `@nucypher/taco` -### [`nucypher/taco-web`](../../README.md) +### [`nucypher/taco-web`](https://github.com/nucypher/taco-web/blob/main/README.md) ## Supported `taco` versions From 3b31f0cd84626d4ff6f81a80b22b5c72c4a9c9fc Mon Sep 17 00:00:00 2001 From: James Campbell Date: Thu, 18 Jul 2024 12:49:15 +0200 Subject: [PATCH 3/8] docs: Add authentication section --- CONTRIBUTING.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 65a4ee63f..79397a6b9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -46,4 +46,12 @@ TODO: Update after implementing automated publishing. This is the api that we expose to developers. It is defined in [`packages/taco/src/taco.ts`](https://github.com/nucypher/taco-web/blob/main/packages/taco/src/taco.ts) -# Design and Architecture \ No newline at end of file +# Design and Architecture + +## User Authentication +[SIWE](https://docs.login.xyz/) (Sign In With Ethereum, [EIP-4361](https://eips.ethereum.org/EIPS/eip-4361)) is the default authentication method. +EIP-712 has previously been supported but is now deprecated. + +The below test demonstrates how a SIWE message can be reused for TACo authentication. +This ensures that users don't have to sign multiple messages when loggin into apps and decrypting TACo messages. +https://github.com/nucypher/taco-web/blob/b689493a37bec0b168f80f43347818095c3dd5ce/packages/taco/test/conditions/context.test.ts#L382C1-L429C6 \ No newline at end of file From b3122bccece9d32aabb9a9d86caa8a29a27bed13 Mon Sep 17 00:00:00 2001 From: James Campbell Date: Thu, 18 Jul 2024 13:02:08 +0200 Subject: [PATCH 4/8] docs: Add test code and background info for authentication providers --- CONTRIBUTING.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 68 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 79397a6b9..d58ccb05d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -49,9 +49,73 @@ It is defined in [`packages/taco/src/taco.ts`](https://github.com/nucypher/taco- # Design and Architecture ## User Authentication -[SIWE](https://docs.login.xyz/) (Sign In With Ethereum, [EIP-4361](https://eips.ethereum.org/EIPS/eip-4361)) is the default authentication method. +User authentication is handled by an `AuthProvider` defined in `packages/taco-auth/src`. +Using authentication providers has several benefits: +1. Abstraction: + + They abstract away the specific details of authentication, providing a unified interface for different authentication methods. + +2. Flexibility: + + The system can accommodate various types of authentication providers, making it extensible and adaptable to different authentication needs. + +3. User Context Management: + + They help manage user context, including handling authentication tokens and ensuring that users are authenticated only once for multiple actions. + +Currently, [SIWE](https://docs.login.xyz/) (Sign In With Ethereum, [EIP-4361](https://eips.ethereum.org/EIPS/eip-4361)) is the only authentication method implemented. EIP-712 has previously been supported but is now deprecated. -The below test demonstrates how a SIWE message can be reused for TACo authentication. -This ensures that users don't have to sign multiple messages when loggin into apps and decrypting TACo messages. -https://github.com/nucypher/taco-web/blob/b689493a37bec0b168f80f43347818095c3dd5ce/packages/taco/test/conditions/context.test.ts#L382C1-L429C6 \ No newline at end of file +[The below test](https://github.com/nucypher/taco-web/blob/b689493a37bec0b168f80f43347818095c3dd5ce/packages/taco/test/conditions/context.test.ts#L382C1-L429C6) demonstrates how a SIWE message can be reused for TACo authentication. +This ensures that users don't have to sign multiple messages when logging into apps and decrypting TACo messages. + +```typescript + it('supports reusing external eip4361', async () => { + // Because we are reusing an existing SIWE auth message, we have to pass it as a custom parameter + const authMessage = await makeAuthSignature(USER_ADDRESS_PARAM_DEFAULT); + const customParams: Record = { + [USER_ADDRESS_PARAM_EXTERNAL_EIP4361]: authMessage as CustomContextParam, + }; + + // Spying on the EIP4361 provider to make sure it's not called + const eip4361Spy = vi.spyOn( + EIP4361AuthProvider.prototype, + 'getOrCreateAuthSignature', + ); + + // Now, creating the condition context to run the actual test + const conditionObj = { + ...testContractConditionObj, + returnValueTest: { + ...testReturnValueTest, + value: USER_ADDRESS_PARAM_EXTERNAL_EIP4361, + }, + }; + const condition = new ContractCondition(conditionObj); + const conditionExpr = new ConditionExpression(condition); + + // Make sure we remove the EIP4361 auth method from the auth providers first + delete authProviders[EIP4361_AUTH_METHOD]; + // Should throw an error if we don't pass the custom parameter + expect( + () => conditionExpr.buildContext( {}, authProviders) + ).toThrow( + `No custom parameter for requested context parameter: ${USER_ADDRESS_PARAM_EXTERNAL_EIP4361}`, + ); + + // Remembering to pass in customParams here: + const builtContext = conditionExpr.buildContext( + customParams, + authProviders, + ); + const contextVars = await builtContext.toContextParameters(); + expect(eip4361Spy).not.toHaveBeenCalled(); + + // Now, we expect that the auth signature will be available in the context variables + const authSignature = contextVars[ + USER_ADDRESS_PARAM_EXTERNAL_EIP4361 + ] as AuthSignature; + expect(authSignature).toBeDefined(); + await testEIP4361AuthSignature(authSignature); + }); +``` \ No newline at end of file From 810c6e81036f31bc5001bfb79e449a9259a8afb9 Mon Sep 17 00:00:00 2001 From: James Campbell Date: Thu, 18 Jul 2024 13:27:54 +0200 Subject: [PATCH 5/8] docs: Add section for context parameters --- CONTRIBUTING.md | 48 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 44 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d58ccb05d..dbf912858 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,10 +7,12 @@ - [Publishing](#publishing) - [External Api](#external-api) - [Design and Architecture](#design-and-architecture) + - [Context Parameters](#context-parameters) + - [Authentication Providers](#authentication-providers) # Quick Start ### Setup -Download, install, build, and test with: +Download and install with: ```bash git clone https://github.com/nucypher/taco-web @@ -38,7 +40,7 @@ pnpm typedoc pnpm typedoc:publish ``` -### Deployment +### Publishing TODO: Update after implementing automated publishing. @@ -48,7 +50,45 @@ It is defined in [`packages/taco/src/taco.ts`](https://github.com/nucypher/taco- # Design and Architecture -## User Authentication +## Context Parameters +When defining conditions for decryption, context parameters are specified to indicate what information is required. +These parameters are placeholders that will be filled with actual data during the decryption process. + +The built in `:userAddress` parameter is defined in `packages/taco-auth/src/auth-provider.ts`. +Custom context parameters can also be defined and they must always begin with `:`. + +[This test](https://github.com/nucypher/taco-web/blob/b689493a37bec0b168f80f43347818095c3dd5ce/packages/taco/test/taco.test.ts#L102) demonstrates the functionality: +```typescript + it('exposes requested parameters', async () => { + const mockedDkg = fakeDkgFlow(FerveoVariant.precomputed, 0, 4, 4); + const mockedDkgRitual = fakeDkgRitual(mockedDkg); + const provider = fakeProvider(aliceSecretKeyBytes); + const signer = fakeSigner(aliceSecretKeyBytes); + const getFinalizedRitualSpy = mockGetActiveRitual(mockedDkgRitual); + + const customParamKey = ':nftId'; + const ownsNFTWithCustomParams = new conditions.predefined.erc721.ERC721Ownership({ + contractAddress: '0x1e988ba4692e52Bc50b375bcC8585b95c48AaD77', + parameters: [customParamKey], + chain: TEST_CHAIN_ID, + }); + + const messageKit = await taco.encrypt( + provider, + domains.DEVNET, + message, + ownsNFTWithCustomParams, + mockedDkg.ritualId, + signer, + ); + expect(getFinalizedRitualSpy).toHaveBeenCalled(); + + const requestedParameters = taco.conditions.context.ConditionContext.requestedContextParameters(messageKit); + expect(requestedParameters).toEqual(new Set([customParamKey, USER_ADDRESS_PARAM_DEFAULT])); + }); +``` + +## Authentication Providers User authentication is handled by an `AuthProvider` defined in `packages/taco-auth/src`. Using authentication providers has several benefits: 1. Abstraction: @@ -61,7 +101,7 @@ Using authentication providers has several benefits: 3. User Context Management: - They help manage user context, including handling authentication tokens and ensuring that users are authenticated only once for multiple actions. + They help manage user context, specifically the `:userAddress` parameter. This includes handling authentication tokens and ensuring that users are authenticated only once for multiple actions. Currently, [SIWE](https://docs.login.xyz/) (Sign In With Ethereum, [EIP-4361](https://eips.ethereum.org/EIPS/eip-4361)) is the only authentication method implemented. EIP-712 has previously been supported but is now deprecated. From ca8cdb8155d759f9ae3b3f0cffaf58f5feea4dec Mon Sep 17 00:00:00 2001 From: James Campbell Date: Thu, 25 Jul 2024 11:55:52 +0200 Subject: [PATCH 6/8] docs: Fix broken link and some wording suggestions Co-authored-by: Manuel Montenegro --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dbf912858..6b44ac035 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ - [Quick Start](#quick-start) - [Setup](#setup) - - [Development](#development) + - [Basic Development Commands](#basic-development-commands) - [Documentation](#documentation) - [Publishing](#publishing) - [External Api](#external-api) @@ -44,7 +44,7 @@ pnpm typedoc:publish TODO: Update after implementing automated publishing. -# External Api +# External API This is the api that we expose to developers. It is defined in [`packages/taco/src/taco.ts`](https://github.com/nucypher/taco-web/blob/main/packages/taco/src/taco.ts) @@ -103,7 +103,7 @@ Using authentication providers has several benefits: They help manage user context, specifically the `:userAddress` parameter. This includes handling authentication tokens and ensuring that users are authenticated only once for multiple actions. -Currently, [SIWE](https://docs.login.xyz/) (Sign In With Ethereum, [EIP-4361](https://eips.ethereum.org/EIPS/eip-4361)) is the only authentication method implemented. +Currently, [SIWE](https://docs.login.xyz/) (Sign-In With Ethereum, [EIP-4361](https://eips.ethereum.org/EIPS/eip-4361)) is the only authentication method implemented. EIP-712 has previously been supported but is now deprecated. [The below test](https://github.com/nucypher/taco-web/blob/b689493a37bec0b168f80f43347818095c3dd5ce/packages/taco/test/conditions/context.test.ts#L382C1-L429C6) demonstrates how a SIWE message can be reused for TACo authentication. From 05a99338fbc149b31dabd8f8117a16e3eb75a741 Mon Sep 17 00:00:00 2001 From: James Campbell Date: Thu, 25 Jul 2024 13:20:27 +0200 Subject: [PATCH 7/8] docs: Improve Publishing section --- CONTRIBUTING.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6b44ac035..bd2a120ad 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,7 +42,25 @@ pnpm typedoc:publish ### Publishing -TODO: Update after implementing automated publishing. +This package follows semantic versioning: + + 1. Major Releases: Introduce significant changes, including breaking changes. + 2. Minor Releases: Add new features in a backwards-compatible manner. + 3. Patch Releases: Include backwards-compatible bug fixes. + +There are multiple inputs that go into deciding when to publish a release, usually driven by external factors like shipping something on the server side and wanting to test it. + +Currently, versions are manually updated in the `package.json` file of each package. +This process involves determining the appropriate version number based on the changes being introduced (e.g., major, minor, patch). + +When the package is published to [npm](https://www.npmjs.com/package/@nucypher/taco), tags are used to indicate the environment or network compatibility. +We use `devnet`, `testnet`, and `mainnet` help users understand which network the release is intended for. + +```bash +npm dist-tag add @nucypher/taco@0.3.0 devnet +``` + +Ideally, this would all be automated using Github actions, workflows, releases, and tags. # External API This is the api that we expose to developers. From b6379ff8e5a6a8491f8da3d28c67cc2abbfa7c1f Mon Sep 17 00:00:00 2001 From: James Campbell Date: Mon, 29 Jul 2024 13:31:44 +0200 Subject: [PATCH 8/8] docs: Add note about convential commits --- CONTRIBUTING.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bd2a120ad..b36a70245 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -62,6 +62,10 @@ npm dist-tag add @nucypher/taco@0.3.0 devnet Ideally, this would all be automated using Github actions, workflows, releases, and tags. +### Version Control +We use git and github to manage our version control. +Where possible, please follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification. + # External API This is the api that we expose to developers. It is defined in [`packages/taco/src/taco.ts`](https://github.com/nucypher/taco-web/blob/main/packages/taco/src/taco.ts)