The Web Auth Page is the front end of the Web Auth framework and must be used with Web Auth Server. Web Auth Page provides a lite wallet easy to embeded in various Dapps using Nuxt framework. After logging in through OAuth, users will be able to perform simple keypair management, transaction construction, signature, etc.
First you need to set up Nodejs service in your server, go to official documentation for how to install: https://nodejs.org/en/download/package-manager . Then you need to set up Web Auth Server service.
You can configure environment variables in any familiar way, such as CI and PM2 both have their own way for configure environment variables, except that you can use dotenv. Copy and rename the .env.example in the project directory to .env and configure it as needed.
npm install --only=prod
npm run startWeb Auth Page is expected to run in an iframe of Dapp, so we have created a Dapp example in Web Auth SDK that shows how it works, so that you can get a more intuitive view of the whole system.
We recommend calling the API via Web Auth SDK because it has encapsulated the API in easy-to-use asynchronous methods, and you don't need to care about the details of communication. **Only if you need to expand or make something compatible with these APIs you should read the following API specification carefully. **
This service provides several APIs for the Web Auth SDK based on window.postMessage, which can be invoked via iframe.contentWindow.postMessage once Web Auth Page is embeded in your Dapp through iframe. In order to implement a full-duplex communication approach similar to persistent connection, we defined a customized specification inspired by JSON RPC 2.0 . Next we define Web Auth Page as the server side and Web Auth SDK as the client side, and introduce the protocol starting with a few basic data structures.
After each Request sent, both side will waiting for a Response with the same ID , default timeout limit is 5 minutes.
interface IRequestMessage {
channel: string, // Only with the same channel client and server can communicate with each other, and each side can listen to multiple channels simultaneously.
id: string, // Identity, corresponding to Response with the same ID.
method: string, // Methods described in next section
params: any, // Params of methods.
}All implemented methods
No matter which side in receipt of a Request, a Response with the same ID must be sent.
interface IResponseMessage {
channel: string, // Same as Request.
error?: IError, // If an error occurs, this field must be used to store the error object.
id: string, // Must correspond to the ID of the Request.
result?: any, // If it works out, this field must be used to store the return value.
}
interface IError {
code: number, // error code
data: any | null, // data of error, could be null
message: string, // error description for developers
}If an method never returns, then the message invoke that method must be sent as Notify, the only difference from Request is that there is no ID.
interface INotifyMessage {
channel: string,
method: string,
params: any,
}Based on the above specification, the following methods are currently implemented. For variables, values are expressed as data types.
This method is for checking if Dapp can communicate with Web Auth Page in the iframe properly, if the method does not return then there must be an unresolved issue.
// Request
{
channel: string,
id: string,
method: 'ping',
params: null,
}
// Response
{
channel: string,
id: string,
result: 'pong',
}Ask the user to OAuth login and authorizes the use of the CKB address and user information.
// Request
{
channel: string,
id: string,
method: 'signIn',
params: null,
}
// Response
{
channel: string,
id: string,
result: {
address: string, // address of CKB
nickname: string, // user's nickname on SNS
profile: any, // user's original profile on SNS
},
}Ask user to construct a signed transaction, useful for simple transfer scenario, the miner fee can be determined by user themselves.
// Request
{
channel: string,
id: string,
method: 'buildTransaction',
params: {
tos: [
{ address: string, value: string }, // address is CKB address, value is amount in shannon
{ address: string, value: string },
]
},
}
// Response
{
channel: string,
id: string,
result: {
signedTransaction: RPC.RawTransaction, // JSON object available for RPC API https://docs.nervos.org/api/rpc.html#send_transaction
},
}Ask user to sign an existing unsigned transaction, useful for complex trading scenario, the user only need to confirm the transaction.
// Request
{
channel: string,
id: string,
method: 'signTransaction',
params: {
unspents: IUTXOUnspent[],
rawTransaction: RPC.RawTransaction // unsigned
},
}
// Response
{
channel: string,
id: string,
result: {
signedTransaction: RPC.RawTransaction, // JSON object available for RPC API https://docs.nervos.org/api/rpc.html#send_transaction.
},
}Constructing unsigned transactions and obtaining
IUTXOUnspent[]requires the use of One Chain CKB, which you can learn about in this example.
Push signed transaction through RPC node without user consent.
// Request
{
channel: string,
id: string,
method: 'pushTransaction',
params: {
rawTransaction: RPC.RawTransaction, // JSON object available for RPC API https://docs.nervos.org/api/rpc.html#send_transaction.
},
}
// Response
{
channel: string,
id: string,
result: {
txId: string, // Transaction ID
},
}First you need to set up and start the Web Auth Server service, and then you need to run the example of Web Auth SDK.
We used dotenv to manage the environment variables, and a common improvement has
been made. There is a .production.env file in the project root directory which contains all available environment
variables. When you need to customize some of these variables, you can create a new .env file and redefine the variables
exists in .production.env. Eventually the variables in .env will override the variables in .production.env.
- Note that
DAPP_URLmust be configured as the URL of the Dapp you are using with the Web Auth SDK. - Note that
BACKEND_URLmust be configured as the URL of the Web Auth Server service you are runing.
npm install
npm run devWe use a little tweaked version of standardjs: https://github.com/BlockABC/eslint-config-blockabc
Please feel free to submit your questions at Issues.