Vault
Our customers need to sign transactions with a cryptographic key. We do not want to be in possession of this key. But our customers can not easily be trained to manage keys themselves. We need the keys to be managed for them, without us holding the keys.
To accomplish this, we will give each user a vault that will hold their keys and sign their transactions. The user will authorize an API access token for each transaction, that will temporarily allow us to request that the vault sign the transaction with the key. The token will be scoped to the specific transaction to be signed.
- PRVD CLI
- The CLI is a convenience layer for developers to interact with the services.
- Code – https://github.com/provideplatform/provide-cli
- Docs – https://docs.provide.services/api/quickstart/cli-quickstart
- PRVD Ident service
- The Ident service will manage our identity and our customers’ identities.
- API – https://ident.provide.services/api/v1/
- Code – https://github.com/provideplatform/ident
- Docs – https://docs.provide.services/api/rest-api-v1/ident
- PRVD Vault service
- The Vault service will manage vaults, keys and signing.
- API – https://vault.provide.services/api/v1/
- Code – https://github.com/provideplatform/vault
- Docs – https://docs.provide.services/api/rest-api-v1/vault
- PRVD JS
- This library is an
npmpackage for interacting with the services in JavaScript. - Code – https://github.com/provideplatform/provide-js
Before we start helping others with identities and vaults, we need our own. We’ll need a user, an organization, and an application. We can do this through the Ident API, but it is more convenient to use the CLI. Follow the CLI instructions in Prerequisites and Installing from Source before continuing. You can run
prvd --help to verify the CLI is installed and to see what all it can do.$ prvd users init
The CLI conveniently prompts for the required input: First Name, Last Name, Email, Password.
After filing these in, the CLI returns the new User ID.
created user: 92e9804f-0639-4d61-9ffa-c1d0434089b1
$ prvd organizations init
The CLI conveniently prompts for the required input: Organization Name.
Organization Name: Philip's Org
After filing that in, the CLI returns the new Organization ID.
initialized organization: Philip's Org aa79cc1c-300b-4814-aa4f-be9ce918c9ce
$ prvd applications init --name 'My App' --network 024ff1ef-7369-4dee-969c-1918c6edb5d4 --without-wallet
The CLI returns the application ID, name, account, and address.
63b9faad-2269-4298-90e6-9281e6437a54 My App
Account adc02bbb-98ac-4011-8bdf-b12ab5150b22 0x69C147D1C8B84f87002438b71B8A681624d3E620
You can create your application on any network.prvd networks listwill show your private networks andprvd networks list --publicwill show available public networks.
$ prvd api_tokens init --application '63b9faad-2269-4298-90e6-9281e6437a54' --offline-access
The CLI returns an access token and refresh token.
Access token authorized for application: 63b9faad-2269-4298-90e6-9281e6447a54 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Refresh token authorized for application: 63b9faad-2269-4298-90e6-9281e6447a54 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Now that we have our own identity, we can create identities for our customers. We have a lot of customers, so we will do this in an automated way using scripts. PRVD has helper libraries for many programming languages to more conveniently use the API. JavaScript is a popular language and can be used in either a front end proof of concept, or a back end NodeJS server.
import { identClientFactory, vaultClientFactory } from 'provide-js';
const accountId = 'adc02bbb-98ac-4011-8bdf-b12ab5150b22';
const appId = '63b9faad-2269-4298-90e6-9281e6437a54';
const appAccessToken = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
const ident = identClientFactory(appAccessToken);
const virtualUser = await ident.createUser({
application_id: appId,
email: `joe.user.${new Date().getTime()}@example.com`,
first_name: 'Joe',
last_name: 'User',
})
console.log(virtualUser.id);
The user ID should be persisted and associated with your record of your user.
const userAccessToken = (await ident.createToken({
application_id: appId,
user_id: virtualUser.id,
scope: 'offline_access',
})).accessToken;
The refresh token is also returned. It should be persisted and used to create future access tokens.
const org = await ident.createOrganization({
name: 'Acme Inc.',
});
console.log(org.id);
The organization ID should be persisted and associated with your record of your user.
const orgAccessToken = (await ident.createToken({
organization_id: org.id,
scope: 'offline_access',
})).accessToken;
The refresh token is also returned. It should be persisted and used to create future access tokens.
const vault = vaultClientFactory(orgAccessToken);
const orgVault = await vault.createVault({
name: `${org.name} Vault`,
description: `${org.name} vault instance`,
});
console.log(orgVault.id);
The vault ID should be persisted and associated with your record of your user.
const key = await vault.createVaultKey(orgVault.id, {
type: 'asymmetric',
usage: 'sign/verify',
spec: 'secp256k1',
name: `${org.name} ETH keypair`,
description: `${org.name} ETH keypair`,
});
console.log(key.id);
The key ID should be persisted and associated with your record of your user.
Use your preferred library of choice to construct a raw Ethereum transaction. To sign it, Vault will need its transaction hash.
If the transaction hash starts with "0x" we need to trim that off.
const hash = (transactionHash.substring(0, 2) === '0x')
? transaction.hash.substring(2)
: transaction.hash;
const signedMessage = await vault.signMessage(orgVault.id, key.id, hash);
console.log(signedMessage.signature);
As you can see, we have the user ID, organization ID, vault ID, key ID, and an access token, but we do not have the actual key. It is stored securely in the vault. Vault signs the message in a custodial or non-custodial manner, depending on if you (i) are relying on the commercially-supported managed Provide vault (custodial) or (ii) deployed Vault to your own infrastructure (non-custodial).
Last modified 7mo ago