SIP for Authentication Protocol

[friedger]

This SIP defines a authentication protocol used by Stacks apps.

The current version has (hopefully) all the required information about the protocol as it is currently used.

I changed three properties of the auth response: hubUrl -> hub_url and associationToken -> association_token. profile.stxAddress-> stx_address.

I added state to the auth messages as defined in OAuth 2.0.

It is recommended to use did:stacks:v2 instead of did:btc-addr

For the public profile, this spec uses the Verifiable Credential model. The VC spec was chosen because it now has W3C Recommendation status.

[friedger]

After the description of the current protocol 1.3.1, I have updated the spec to 2.0.0 in 7b35de6 using verifiable credentials and better definition of the issuers.

[aulneau]

@friedger, thank you so much for doing this. I added a few comments, curious what you think :)

[aulneau]

Suggested change

	1. Application creates app transit private key, signs an auth request with that key and sends the request to the Authenticator.
	2. In the Authenticator, User authorizes sharing of public key, Authenticator derives app private key from request and updates the user's public profile if required.
	3. Authenticator creates response with authorized data and sends response to the Application.
	4. Application verifies signature against the app transit private key.
	**Client (app):**
	1. Client generates ephemeral private/public key pair: `transitPrivateKey`
	2. Client creates an auth request payload (`authRequestPayload`) with details about the application, eg:
	```ts
	export interface AuthRequestPayload {
	scopes: AuthScope[];
	redirect_uri: string;
	public_keys: string[];
	domain_name: string;
	appDetails: AppDetails;
	}
	```
	3. Client signs the auth request payload (a JWT) with the `transitPrivateKey`, with signature format `ES256k`
	4. Client sends the JWT to an authenticator (eg: Hiro Web Wallet)
	**Authenticator (wallet):**
	1. Authenticator validates the signature against the included public key(s)
	2. Authenticator generates an account index by creating a SHA256 hash of the domain of the application that generated the `authRequestPayload`, and the wallet's salt
	3. Authenticator then uses that index to derive a hardened child private key (`appPrivateKey`) from the root seed phrase (BIP32).
	4. Authenticator generates an `authResponse` which includes the `appPrivateKey`
	5. Authenticator encrypts the JWT with the public key provided in the `authRequestPayload`
	**Client (app):**
	1. Client receives the encrypted `authResponse` and decrypts it with the `transitPrivateKey`
	2. Client is now authenticated

[friedger]

I wanted to give a high level overview first. Ideally with a better diagram than the current one. I like the separation between the two entities, but I think it is too much detail. Maybe we should have this in pseudo code as an appendix? @aulneau

The auth response is not encrypted, only the appPrivateKey (and core_token). Messages are always normal JWTs.

[aulneau]

This is highly prone to collisions, and generally a bad implementation. Unfortunately, it has been used for years. I have created what I think is a better alternative here in micro-stacks.

  // Rather than using the `hashCode` function to derive an index for the child
  // which makes it so there's a unreasonable high probability that someone can
  // log into a new app (website) and it accidentally shares data with another one
  //
  // we want to use the `appDomain` + `salt` to generate a sha256 hash that is
  // then used as the chaincode for the new app keychain
  const chainCode = hashSha256(utf8ToBytes(`${appDomain}${account.salt}`));
  const rootNode = HDKeychain.fromBase58(account.appsKey);
  const appKeychain = await HDKeychain.fromPrivateKey(rootNode.privateKey, chainCode).deriveChild(
    0,
    true
  );

With the formalization of this standard in a SIP, would it make sense to explore this (or another) alternative?

[aulneau]

cc @zone117x @kantai for any thoughts you might have on this

[friedger]

Interesting. We should fix that!

[janniks]

We're currently in the process of removing the username from the authentication flow completely. hirosystems/stacks.js#1230 Keeping the username adds a bunch of complications. Additionally, the username should be verified by the application anyway, so it makes sense for the application to fetch the username in the first place.

I bumped the token version to 1.4.0 for this, in case anybody is validating very strictly.

some discussions/comments here:

• fix: remove username matching hirosystems/stacks.js#1230
• fix: update to stacks.js 4.0.0 (removes username checking) leather-io/extension#2333

[zone117x]

+1 this seems like a good separation of concerns

[aulneau]

I'm in the process of building a new library that implements this SIP in micro-stacks and I have a few questions:

In the auth request area:

manifest_uri: is this required anymore? I don't think we need it. Can you describe use cases for this?
redirect_uri: this is also not used anymore in the context of extension/native based wallets. this seems to be a hold over from early blockstack days.

In the auth response section:

core_token: is this needed? I don't think anything uses this, nor generates a token for it.
email wouldn't this be better in some profile? nothing uses this to date