mirror of https://github.com/lukechilds/docs.git
Browse Source
- Add Stacks.js references to "Build app" nav - Move BNS and Gaia to new protocols section in same nav - Remove Stacks Connect page, merging contents into authentication guidefeat/build-apps
Mark Hendrickson
4 years ago
6 changed files with 227 additions and 305 deletions
|
Before Width: | Height: | Size: 25 KiB |
@ -1,285 +0,0 @@ |
|||||
--- |
|
||||
title: Stacks Connect |
|
||||
description: Open protocol for connecting apps built with Stacks |
|
||||
images: |
|
||||
large: /images/pages/authentication.svg |
|
||||
sm: /images/pages/authentication-sm.svg |
|
||||
--- |
|
||||
|
|
||||
Stacks Connect is an open protocol for connecting apps built with the Stacks blockchain, such as consumer apps with authenticators and wallets. |
|
||||
|
|
||||
## Authentication flow |
|
||||
|
|
||||
For an application developer, the application flow is similar to the typical client-server flow used by centralized sign in services (for example, OAuth). However, with Stacks Connect, the authentication flow happens entirely client-side. |
|
||||
|
|
||||
An app and authenticator, such as [the Stacks Wallet](https://blockstack.org/wallet), communicate during the authentication flow by passing back and forth two tokens. The requesting application sends the authenticator an `authRequest` token. Once a user approves a sign-in, the authenticator responds to the application with an `authResponse` token. These tokens are <a href="https://jwt.io/" target="\_blank">JSON Web Tokens</a>, and they are passed via URL query strings. |
|
||||
|
|
||||
 |
|
||||
|
|
||||
When a user chooses to authenticate a decentralized application, it calls the `doOpenAuth()` method which sends an `authRequest` to the authenticator. Stacks auth passes the token in via a URL query string in the `authRequest` parameter: |
|
||||
|
|
||||
`https://app.blockstack.org/#/sign-up?authRequest=j902120cn829n1jnvoa...` |
|
||||
|
|
||||
When the authenticator receives the request, it generates an (`authResponse`) token to the application using an _ephemeral transit key_ . The ephemeral transit key is just used for the particular instance of the application, in this case, to sign the `authRequest`. The application stores the ephemeral transit key during the request generation. The public portion of the transit key is passed in the `authRequest` token. The authenticator uses the public portion of the key to encrypt an _app-private key_ which is returned via the `authResponse`. |
|
||||
|
|
||||
During sign in, the authenticator generates the app-private key from the user's _identity-address private_ key and the application's `appDomain`. The app private key serves three functions: |
|
||||
|
|
||||
- It is used to create the credentials that give an app access to the Gaia storage bucket for that specific app. |
|
||||
- It is used in the end-to-end encryption of files stored for the app in the user's Gaia storage. |
|
||||
- It serves as a cryptographic secret that apps can use to perform other cryptographic functions. |
|
||||
|
|
||||
Finally, the app private key is deterministic, meaning that for a given user ID and domain name, the same private key is generated each time. |
|
||||
|
|
||||
## Scopes |
|
||||
|
|
||||
Scopes define the permissions requested by an app for granting during authentication. |
|
||||
|
|
||||
Apps may request any of the following scopes: |
|
||||
|
|
||||
| Scope | Definition | |
|
||||
| -------------- | ------------------------------------------------------------------------------------ | |
|
||||
| `store_write` | Read and write data to the user's Gaia hub in an app-specific storage bucket. | |
|
||||
| `publish_data` | Publish data so that other users of the app can discover and interact with the user. | |
|
||||
|
|
||||
The permissions scope should be specified through the [`AppConfig`](https://blockstack.github.io/stacks.js/classes/appconfig.html) |
|
||||
object. If no `scopes` array is provided to the `redirectToSignIn` or `makeAuthRequest` functions, the default is to request `['store_write']`. |
|
||||
|
|
||||
## Manifest file |
|
||||
|
|
||||
Decentralized apps have a manifest file. This file is based on the [W3C web app manifest specification](https://w3c.github.io/manifest/). |
|
||||
The following is an example manifest file. |
|
||||
|
|
||||
```json |
|
||||
{ |
|
||||
"name": "Todo App", |
|
||||
"start_url": "http://todos.blockstack.org", |
|
||||
"description": "A simple todo app build on Stacks", |
|
||||
"icons": [ |
|
||||
{ |
|
||||
"src": "http://todos.blockstack.org/logo.png", |
|
||||
"sizes": "400x400", |
|
||||
"type": "image/png" |
|
||||
} |
|
||||
] |
|
||||
} |
|
||||
``` |
|
||||
|
|
||||
The Stacks Wallet retrieves the manifest file from the app during the authentication process and displays the |
|
||||
information in it such as the app `name` and to the user during sign in. The location of the app manifest file is specific |
|
||||
in the authentication request token and **must** be on the same origin as the app requesting authentication. |
|
||||
|
|
||||
The manifest file **must** have [Cross-origin resource sharing (CORS) headers](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) |
|
||||
that allow the manifest file to be fetched from any arbitrary source. This usually means returning a header like this: |
|
||||
|
|
||||
``` |
|
||||
Access-Control-Allow-Origin: * |
|
||||
``` |
|
||||
|
|
||||
How you implement CORS depends in part on which platform/service you use to serve your application. For example, Netlify |
|
||||
and Firebase have two different ways of configuring CORS. Consult your vendor documentation for more information. |
|
||||
|
|
||||
## Key pairs |
|
||||
|
|
||||
Stacks Auth makes extensive use of public key cryptography. Blockstack uses ECDSA with the `secp256k1` curve. The |
|
||||
following sections describe the three public-private key pairs used in the authentication process: |
|
||||
|
|
||||
- how they're generated |
|
||||
- where they're used |
|
||||
- to whom the private key is disclosed |
|
||||
|
|
||||
### Transit private key |
|
||||
|
|
||||
The transit private is an ephemeral key that is used to encrypt secrets that |
|
||||
need to be passed from the authenticator to the decentralized app during the |
|
||||
authentication process. It is randomly generated by the app at the beginning of |
|
||||
the authentication response. |
|
||||
|
|
||||
The public key that corresponds to the transit private key is stored in a single |
|
||||
element array in the `public_keys` key of the authentication request token. The |
|
||||
authenticator encrypts secret data such as the app private key using this |
|
||||
public key and sends it back to the app when the user signs in to the app. The |
|
||||
transit private key signs the app authentication request. |
|
||||
|
|
||||
### Identity address private key |
|
||||
|
|
||||
The identity address private key is derived from the user's keychain phrase and |
|
||||
is the private key of the Stacks username that the user chooses to use to sign in |
|
||||
to the app. It is a secret owned by the user and never leaves the user's |
|
||||
instance of the authenticator. |
|
||||
|
|
||||
This private key signs the authentication response token for an app to indicate that the user approves sign in to that app. |
|
||||
|
|
||||
### App private key |
|
||||
|
|
||||
The app private key is an app-specific private key that is generated from the |
|
||||
user's identity address private key using the `domain_name` as input. It is |
|
||||
deterministic in that for a given Stacks username and `domain_name`, the same |
|
||||
private key is generated each time. |
|
||||
|
|
||||
The app private key is securely shared with the app on each authentication, encrypted by the authenticator with the transit public key. |
|
||||
|
|
||||
## JSON Web Token signatures |
|
||||
|
|
||||
Both the `authRequest` and the `authResponse` tokens are [JSON Web Tokens](https://jwt.io/), and they are passed via URL query strings. |
|
||||
|
|
||||
Stacks authentication tokens are based on the [RFC 7519 OAuth JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) |
|
||||
with additional support for the `secp256k1` curve used by Bitcoin and many other |
|
||||
cryptocurrencies. |
|
||||
|
|
||||
This signature algorithm is indicated by specifying `ES256K` in the token's |
|
||||
`alg` key, specifying that the JWT signature uses ECDSA with the secp256k1 |
|
||||
curve. Stacks auth provide both [JavaScript](https://github.com/blockstack/jsontokens-js) |
|
||||
and |
|
||||
[Ruby](https://github.com/blockstack/ruby-jwt-blockstack/tree/ruby-jwt-blockstack) |
|
||||
JWT libraries with support for this signing algorithm. |
|
||||
|
|
||||
-> The Stacks JWT implementation is different from other implementations because of the underlying cryptography we employ. There are libraries in [JavaScript](https://github.com/blockstack/jsontokens-js) and [Ruby](https://github.com/blockstack/ruby-jwt-blockstack) available on the Blockstack Github to allow you to work with these tokens. |
|
||||
|
|
||||
### Example: authRequest payload schema |
|
||||
|
|
||||
```jsx |
|
||||
const requestPayload = { |
|
||||
jti, // UUID |
|
||||
iat, // JWT creation time in seconds |
|
||||
exp, // JWT expiration time in seconds |
|
||||
iss, // legacy decentralized identifier generated from transit key |
|
||||
public_keys, // single entry array with public key of transit key |
|
||||
domain_name, // app origin |
|
||||
manifest_uri, // url to manifest file - must be hosted on app origin |
|
||||
redirect_uri, // url to which the authenticator redirects user on auth approval - must be hosted on app origin |
|
||||
version, // version tuple |
|
||||
do_not_include_profile, // a boolean flag asking authenticator to send profile url instead of profile object |
|
||||
supports_hub_url, // a boolean flag indicating gaia hub support |
|
||||
scopes, // an array of string values indicating scopes requested by the app |
|
||||
}; |
|
||||
``` |
|
||||
|
|
||||
### Example: authResponse payload schema |
|
||||
|
|
||||
```jsx |
|
||||
const responsePayload = { |
|
||||
jti, // UUID |
|
||||
iat, // JWT creation time in seconds |
|
||||
exp, // JWT expiration time in seconds |
|
||||
iss, // legacy decentralized identifier (string prefix + identity address) - this uniquely identifies the user |
|
||||
private_key, // encrypted private key payload |
|
||||
public_keys, // single entry array with public key |
|
||||
profile, // profile object or null if passed by profile_url |
|
||||
username, // Stacks username (if any) |
|
||||
core_token, // encrypted core token payload |
|
||||
email, // email if email scope is requested & email available |
|
||||
profile_url, // url to signed profile token |
|
||||
hubUrl, // url pointing to user's gaia hub |
|
||||
version, // version tuple |
|
||||
}; |
|
||||
``` |
|
||||
|
|
||||
## Decode authRequest |
|
||||
|
|
||||
To decode the token and see what information it holds: |
|
||||
|
|
||||
1. Copy the `authRequest` string from the URL. |
|
||||
|
|
||||
<img src="/images/copy-authRequest.png" alt="" /> |
|
||||
|
|
||||
2. Navigate to [jwt.io](https://jwt.io/). |
|
||||
3. Paste the full token there. |
|
||||
|
|
||||
The output should look similar to below: |
|
||||
|
|
||||
```json |
|
||||
{ |
|
||||
"jti": "f65f02db-9f42-4523-bfa9-8034d8edf459", |
|
||||
"iat": 1555641911, |
|
||||
"exp": 1555645511, |
|
||||
"iss": "did:btc-addr:1ANL7TNdT7TTcjVnrvauP7Mq3tjcb8TsUX", |
|
||||
"public_keys": ["02f08d5541bf611ded745cc15db08f4447bfa55a55a2dd555648a1de9759aea5f9"], |
|
||||
"domain_name": "http://localhost:8080", |
|
||||
"manifest_uri": "http://localhost:8080/manifest.json", |
|
||||
"redirect_uri": "http://localhost:8080", |
|
||||
"version": "1.3.1", |
|
||||
"do_not_include_profile": true, |
|
||||
"supports_hub_url": true, |
|
||||
"scopes": ["store_write", "publish_data"] |
|
||||
} |
|
||||
``` |
|
||||
|
|
||||
The `iss` property is a decentralized identifier or `did`. This identifies the user and the user name to the application. The specific `did` is a `btc-addr`. |
|
||||
|
|
||||
## User profiles |
|
||||
|
|
||||
Profile data is stored using Gaia on the user's selected storage provider. An example of a `profile.json` file URL using |
|
||||
default provided storage: |
|
||||
|
|
||||
``` |
|
||||
https://gaia.blockstack.org/hub/1EeZtGNdFrVB2AgLFsZbyBCF7UTZcEWhHk/profile.json |
|
||||
``` |
|
||||
|
|
||||
Follow these steps to create and register a profile for a BNS username (`identifier`): |
|
||||
|
|
||||
1. Create a JSON profile object |
|
||||
2. Split up the profile into tokens, sign the tokens, and put them in a token file |
|
||||
3. Create a zone file that points to the web location of the profile token file |
|
||||
|
|
||||
```jsx |
|
||||
"account": [ |
|
||||
{ |
|
||||
"@type": "Account", |
|
||||
"service": "twitter", |
|
||||
"identifier": "naval", |
|
||||
"proofType": "http", |
|
||||
"proofUrl": "https://twitter.com/naval/status/12345678901234567890" |
|
||||
} |
|
||||
] |
|
||||
``` |
|
||||
|
|
||||
## Create a profile |
|
||||
|
|
||||
```jsx |
|
||||
const profileOfNaval = { |
|
||||
'@context': 'http://schema.org/', |
|
||||
'@type': 'Person', |
|
||||
name: 'Naval Ravikant', |
|
||||
description: 'Co-founder of AngelList', |
|
||||
}; |
|
||||
``` |
|
||||
|
|
||||
## Sign a profile as a single token |
|
||||
|
|
||||
```jsx |
|
||||
import { wrapProfileToken, Person } from '@stacks/profiles'; |
|
||||
|
|
||||
const privateKey = 'e546ba96ee34220287d0c177418011addf8d71b32fb81ae8e33a1d7510fa5d0d01'; |
|
||||
|
|
||||
const person = new Person(profileOfNaval); |
|
||||
const token = person.toToken(privateKey); |
|
||||
const tokenFile = [wrapProfileToken(token)]; |
|
||||
``` |
|
||||
|
|
||||
## Verify an individual token |
|
||||
|
|
||||
```jsx |
|
||||
import { verifyProfileToken } from '@stacks/profiles'; |
|
||||
|
|
||||
try { |
|
||||
const decodedToken = verifyProfileToken(tokenFile[0].token, publicKey); |
|
||||
} catch (e) { |
|
||||
console.log(e); |
|
||||
} |
|
||||
``` |
|
||||
|
|
||||
## Recover a profile from a token file |
|
||||
|
|
||||
```jsx |
|
||||
const recoveredProfile = Person.fromToken(tokenFile, publicKey); |
|
||||
``` |
|
||||
|
|
||||
## Validate profile schema |
|
||||
|
|
||||
```jsx |
|
||||
const validationResults = Person.validateSchema(recoveredProfile); |
|
||||
``` |
|
||||
|
|
||||
### Transaction signing |
|
||||
|
|
||||
TBD: info on transaction signing protocol |
|
||||
Loading…
Reference in new issue