Skip to content

Review documentation #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
royscheeren merged 11 commits into from
Mar 2, 2023
Merged

Review documentation #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
39d405e
Review Readme.md
jdsika Jan 10, 2023
d49eef5
Update acq docs
jdsika Jan 10, 2023
41ae8b7
Review core readme.md
jdsika Jan 10, 2023
1774cba
Review Discor bot ui readme.md
jdsika Jan 10, 2023
38a7116
Review Discord readme.md
jdsika Jan 10, 2023
44765ab
small update
jdsika Jan 10, 2023
ff514c5
review react readme.md
jdsika Jan 10, 2023
c593701
Review utils readme.md
jdsika Jan 10, 2023
4a5169a
merge branch develop into branch doc/review
royscheeren Mar 2, 2023
3e7fb89
feat(docs.siwt.xyz): update docs with reviewed readme files
royscheeren Mar 2, 2023
2188c8b
fix(docs.siwt.xyz): fix broken link
royscheeren Mar 2, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 6 additions & 26 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,27 @@
# Siwt
# SIWT

Sign In With Tezos (SIWT) is a library that supports the development of your decentralized application (dApp) by:

- proving the users ownership of the private key to the address the user signs in with,
- adding permissions to use your API or Backend using on chain data.
- adding permissions to use your API or backend using on chain data.

## Packages

SIWT is split up in several packages:

### [Core](https://github.com/StakeNow/SIWT/tree/develop/packages/core)

This package handles the JWT tokens. Use this on the servers side to create and verify tokens. This package should only be used server side [NPM](https://www.npmjs.com/package/@siwt/core)
This [package](https://www.npmjs.com/package/@siwt/core) handles the JWT tokens. Use this on the servers side to create and verify tokens. This package should only be used server side.

### [Access Control Query (acq)](https://github.com/StakeNow/SIWT/tree/develop/packages/acq)

Use this package to define the requirements your user needs to obtain access. Currently it supports:

Use this [package](https://www.npmjs.com/package/@siwt/acq) to define the requirements your user needs to fulfil to obtain access. Currently it supports:
- checking if your user has a certain NFT
- checking if a user is (or is not) on a provided allowlist
- checking if a user has a min/max amount of XTZ
- checking if a user has a min/max amount of a fungible token

[NPM](https://www.npmjs.com/package/@siwt/acq)

### [SDK](https://github.com/StakeNow/SIWT/tree/develop/packages/sdk)

This package contains utilities to facilitate the creation of messages and verification of signatures. It can be used on both FE and server.
This [package](https://www.npmjs.com/package/@siwt/sdk) contains utilities to facilitate the creation of messages and verification of signatures. It can be used on both FE and server.

### [Discord](https://github.com/StakeNow/SIWT/tree/develop/packages/discord)

Expand All @@ -38,8 +33,7 @@ SIWT.
A react UI that is part of the Discord bot. It is required so your Discord members can use their Tezos wallets to sign in to your server.

### [React](https://github.com/StakeNow/SIWT/tree/develop/packages/react)

This packages contains react hooks to make implementation of SIWT in your React application easier [NPM](https://www.npmjs.com/package/@siwt/react)
This [package](https://www.npmjs.com/package/@siwt/react) contains react hooks to make implementation of SIWT in your React application easier.

## Getting started with your project

Expand Down Expand Up @@ -480,17 +474,3 @@ app.listen(port, () => {
console.log(`SIWT server app listening on port ${port}`)
})
```

## Contributing

<a href="https://nx.dev" target="_blank" rel="noreferrer"><img src="https://raw.githubusercontent.com/nrwl/nx/master/images/nx-logo.png" width="45"></a>

✨ **This workspace has been generated by [Nx, a Smart, fast and extensible build system.](https://nx.dev)** ✨

## Understand this workspace

Run `nx graph` to see a diagram of the dependencies of the projects.

## Further help

Visit the [Nx Documentation](https://nx.dev) to learn more.
51 changes: 21 additions & 30 deletions packages/acq/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,12 @@
# Access Control Query

The Access Control Query library allows you to easily set the requirements for your users.
The Access Control Query (acq) library allows you to easily set the requirements for your users.

## Installation

```
npm install @siwt/acq
```

Once the package is install you can import it using:
Once the package is installed you can import it using:

```
import { queryAccessControl } from '@siwt/acq'
Expand All @@ -20,9 +18,9 @@ Setting your requirements is done by defining a query in the following format:

```
const result = await queryAccessControl({
network: Network.mainnet, // Choose which network should be checked. Options are Mainnet and Ghostnet. Defaults to Ghostnet
network: Network.mainnet, // Choose which network should be checked. Options are Mainnet and Ghostnet. Defaults to Ghostnet.
parameters: {
pkh: 'WALLET ADDRESS', // Variables that are required for the query. Currently this is limited to the user's wallet address. Required
pkh: 'WALLET ADDRESS', // Variables that are required for the query. Currently this is limited to the user's wallet address. Required.
},
test: {
contractAddress: '', // The smart contract address to check. Required on certain condition types.
Expand All @@ -41,9 +39,9 @@ The result will have the following format:
pkh: 'USER WALLET ADDRESS',
testResults: {
passed: boolean,
ownedTokenIds: [], // When using the NFT condition
balance: 0, // when using XTZ or fungible token balance
error: boolean, // If the test failed because of an error
ownedTokenIds: [], // When using the NFT condition.
balance: 0, // when using XTZ or fungible token balance.
error: boolean, // If the test failed because of an error.
}
```

Expand All @@ -54,35 +52,28 @@ The result will have the following format:
Use this if you want to test if your user has a certain amount of a certain NFT.

#### XTZ Amount
Use this if you need your user to hold a certain amount of tez.

Use this if you need your user to hold a certain amount of XTZ

#### Fungible token Amount

Use this if you need your user to hold a certain amount of a fungible token

#### Allowlist
#### Fungible Token Amount
Use this if you need your user to hold a certain amount of a fungible token.

Use this if you want to provide a specific list of wallet address to allow or deny access
#### Whitelist
Use this if you want to provide a specific list of wallet addresses to allow or deny access to.

#### Tezos tickets (Coming soon)

Use this to check if your user has an issued ticket
#### Tezos Tickets (Coming soon)
Use this to check if your user has an issued ticket.

### The following comparators are available:

eq: Equals
gte: Greater than or equals
lte: Less than or equals
gt: Greater than
lt: Less than
in: In (Allowlist only)
notIn: Not in (Allowlist only)
eq: Equals
gte: Greater than or equals
lte: Less than or equals
gt: Greater than
lt: Less than
in: In (Whitelist only)
notIn: Not in (Whitelist only)

## Running unit tests

Run `nx test acq` to execute the unit tests via [Jest](https://jestjs.io).

## Running lint

Run `nx lint acq` to execute the lint via [ESLint](https://eslint.org/).
34 changes: 12 additions & 22 deletions packages/core/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,8 @@
# core

The core library is the main library to be used in your backend. Use it to create and verify access, refresh and id tokens.
# Core
This is the main library (core) to be used in your backend. Use it to create and verify access, refresh and id tokens.

## Usage

Initiate siwt as follows:
Initiate SIWT as follows:

```
import { siwt } from '@siwt/core'
Expand All @@ -13,23 +11,20 @@ const siwtClient = siwt({
accessTokenSecret: 'YOUR ACCESS TOKEN SECRET',
refreshTokenSecret: 'YOUR REFRESH TOKEN SECRET',
idTokenSecret: 'YOUR ID TOKEN SECRET',
accessTokenExpiration: 900, // Seconds. Optional, Default 15 mins
refreshTokenExpiration: 36000, // Seconds. Optional, Default 1 month
idTokenExpiration: 2592000 // Seconds. Optional, Default 10 hrs
accessTokenExpiration: 900, // Seconds. Optional, Default 15 mins.
refreshTokenExpiration: 36000, // Seconds. Optional, Default 1 month.
idTokenExpiration: 2592000 // Seconds. Optional, Default 10 hrs.
})
```

### Secrets

The secret can be a random string you generate. They are used to encode and decode the tokens and acts as a security layer. Treat them accordingly.
### Secrets
The secret can be a random string you generate. They are used to encode and decode the tokens and acts as a security layer. Treat them accordingly and refer to the [official documentation](https://jwt.io/) regarding their requirements.

### Generating tokens

**Access Token:**

Use the access token for authorization upon each protected API call. Add it as a bearer token in the authorization header of each API call.

Since the access token is being sent with every api call, it's a good idea to keep it as small as possible. The minimum data required is the users pkh, however any extra claims are supported.
Use the access token for authorization upon each protected API call. Add it as a bearer token in the authorization header of each API call. Since the access token is being sent with every api call, it is a good idea to keep it as small as possible. The minimum data required is the users pkh, however any extra claims are supported.

```
const pkh = 'USER WALLET ADDRESS'
Expand All @@ -45,8 +40,7 @@ const accessToken = siwtClient.generateAccessToken({

**Refresh Token:**

If you have implemented a refresh token strategy use this token to obtain a new access token.
Generating a refresh token only requires a pkh
If you have implemented a refresh token strategy use this token to obtain a new access token. Generating a refresh token only requires a pkh:

```
const refreshToken = siwtClient.generateRefreshToken({pkh})
Expand All @@ -56,7 +50,7 @@ const refreshToken = siwtClient.generateRefreshToken({pkh})

The ID token is used to obtain some information about the user that is signed in. Because it is a valid JWT token you can use any jwt decoding library to decode the token and use it's contents.

The ID token can contain optional claims and user info.
The ID token can contain optional claims and user info:

```
const pkh = 'USER WALLET ADDRESS'
Expand All @@ -75,9 +69,7 @@ const accessToken = siwtClient.generateAccessToken({
```

### Verifying tokens

The access and refresh token can be verified by using:

The access and refresh token can be verified by using
```
siwtClient.verifyAccessToken(accessToken)
```
Expand All @@ -91,9 +83,7 @@ siwtClient.verifyRefreshToken(refreshToken)
respectively.

## Running unit tests

Run `nx test core` to execute the unit tests via [Jest](https://jestjs.io).

## Running lint

Run `nx lint core` to execute the lint via [ESLint](https://eslint.org/).
18 changes: 5 additions & 13 deletions packages/discord-bot-ui/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,19 @@
# Discord bot ui
# Discord Bot UI

This application is the ui part of the discord bot. It is where users are being redirected to when verifying on your bot to sign in.
This application is the ui part of the Discord bot. It is where users are being redirected to when verifying on your bot to sign in.

## Requirements

Make sure you run

```
npm install
```

in the root of the project
in the root of the project.

## Usage

The ui is a simple react app that you can decide to use, however you are welcome to implement your own solution.

### Environment

Before building the application make sure you have a `.env` file containing the following:

Before building the application make sure you have a `.env` file containing the following information:
```
NX_API_URL='URL to your discord bot'
NX_APPLICATION_URL='Name and/or url of your discord server'
Expand All @@ -32,9 +26,7 @@ Run
```
npx nx build discord-bot-ui
```

The built project can be found in `dist/pakcages/discord-bot-ui`
The built project can be found in `dist/pakcages/discord-bot-ui`.

### Deployment

After successful built, it can now be deployed as a static app on your server of choice.
46 changes: 18 additions & 28 deletions packages/discord/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,37 +1,31 @@
# Discord

The SIWT Discord bot should be used to allow your Discord members to identitfy themselves using their Tezos wallet. The bot automatically assigns the `Verified` role if your user successfully signs in and passes the requirements you set in the [Access control query](https://github.com/StakeNow/SIWT/tree/develop/packages/acq)
The SIWT Discord bot should be used to allow your Discord members to identitfy themselves using their Tezos wallet. The bot automatically assigns the `Verified` role if your user successfully signs in and passes the requirements you set using the [Access Control Query](https://github.com/StakeNow/SIWT/tree/develop/packages/acq) package.

## Requirements

### Server

A server running Node 16 or higher configured to accept requests on the port you have set to run express on. (default is 3000).
For an example on how to set up a Node server using Ubuntu and Nginx check: https://www.digitalocean.com/community/tutorials/how-to-set-up-a-node-js-application-for-production-on-ubuntu-18-04. Make sure you set the environment variables as explained further down.
A server running Node 16 or higher configured to accept requests on the port you have set to run express on. Default is 3000.
For an example on how to set up a Node server using Ubuntu and Nginx check [this tutorial](https://www.digitalocean.com/community/tutorials/how-to-set-up-a-node-js-application-for-production-on-ubuntu-18-04). Make sure you set the environment variables as explained further down.

### UI

The UI is used to allow users to connect their wallet and validate their address by signing a message. The signature is required to verify that the user meets the requirements you've set on the server. It can be deployed on the same server as the bot, or you may choose to deploy it on a separate service like S3/CloudFront.
The UI is used to allow users to connect their wallet and validate their address by signing a message. The signature is required to verify that the user meets the requirements you have set on the server. It can be deployed on the same server as the bot, or you may choose to deploy it on a separate service like a S3/CloudFront.

## Creating private channels

Create a new text channel, give it a name and set it to Private.
Create a new text channel, give it a name and set it to `Private`.
In the next prompt make sure you select the `Verified` role and click create channel.

## Installing the bot
To install the bot you will need a developer account on Discord:

To install the bot you'll need a developer account on Discord:

- Create one or sign in to your existing one at https://discord.com/developers
- Create a new application and give it a shiny little avatar
- Add a bot and give it an even shinier avatar
- Click the Reset Token button and keep it in a safe place, we'll need it later. Make sure you keep this token secret and reset it if you suspect it might have been compromised.
- Turn on the privileged gateway events
- Save your settings
- Create one or sign in to your existing one at [discord.com/developers](https://discord.com/developers).
- Create a new application and give it a shiny little avatar.
- Add a bot and give it an even shinier avatar.
- Click the Reset Token button and keep it in a safe place, we will need it later. Make sure you keep this token secret and reset it if you suspect it might have been compromised.
- Turn on the privileged gateway events.
- Save your settings.

## Building and deploying

Make sure you've run `npm install` in the root of the project
Make sure you have run `npm install` in the root of the project.

The bot can now be built by using:

Expand All @@ -56,9 +50,7 @@ APP_URL="This is the url of you UI"
```

### Access control query

Use the configuration in `/packages/discord/src/app/config` to set up the access control query.
[More info on the access control query](https://github.com/StakeNow/SIWT/tree/develop/packages/acq)
Use the configuration in `/packages/discord/src/app/config` to set up the access control query. Get [more information](https://github.com/StakeNow/SIWT/tree/develop/packages/acq) on the access control query (acq) package.

After you have set the environment and query it is time to start the server.
On your server in the project folder run:
Expand All @@ -67,8 +59,7 @@ On your server in the project folder run:
node ./main.js
```

of if you use `pm2` as per the tutorial above start the server by running:

If you use `pm2` as per the tutorial above start the server by running:
```
pm2 start ./main.js
```
Expand All @@ -83,15 +74,14 @@ Ready! Logged in as SIWT#9646
## How it works

### On activation

When activating the bot it will create a role called `Verified`, create a channel called verification and send a message to it.
The message contains a button labeled `Verify`.
When activating the bot it will create a role called `Verified`, create a channel called `#verification` and send a message to it.
The message contains a button labeled `Verify`.

### The flow

When a user clicks the button, a verification attempt will be created in the DB.
A new message will be sent to the user with a button labeled `Let's go`.
This button will direct the user to the ui you've deployed earlier together with the ID of the verification attempt.
This button will direct the user to the UI you have deployed earlier together with the ID of the verification attempt.

Once the user arrives at the UI, the user will be requested to connect their wallet and sign a message.
After signing the message, the UI will attempt to contact the bot to verify the signature and to check if this user meets
Expand Down
Loading