Specification for auth protocol

[friedger]

Background
What problems do you aim to solve? How does it serve the mission of a user owned internet?

Stacks connect and Hiro Wallet uses the stacks auth protocol to authenticate users in web apps. The documentation of the protocol is small. This proposal is about creating a specification that helps projects like Circle, Wise, Ryder to be interoperable. Web application should not worry about users having different authenticators.

Project Overview
What solution are you providing? Who will it serve?

The specification will be a written document a SIP proposal with at least one visual element. It should help to support custom authenticators (reference required) and to help solve bugs in implementations.

Scope
What are the components or technical specs of the project? What will the final deliverable look like? How will you measure success?

The SIP contains specification of the protocol including used cryptographic methods, transport protocols and message formats.

The proposal includes interaction with @larrysalibra @markmhx @0xAsteria and other interested community members.

Budget and Milestones
What grant amount are you seeking? How long will the project take in hours? If more than 20, please break down the project into milestones, with a clear output (e.g., low-fi mockup, MVP with two features) and include the estimated work hours for each milestone.

Total Grant Request: 2,000$

M1: SIP outline document
1 week

M2: Accepted SIP
3 weeks

Team
Who is building this? What relevant experience do you bring to this project? Are there skills sets you are missing that you are seeking from the community? Please share links to previous work.

Friedger (specified sip-9, pull request to fix auth issue: hirosystems/stacks.js#1117)

Risks
What dependencies or obstacles do you anticipate? What contingency plans do you have in place?

A previous diagram was not integrated in the official documentation due to design differences (stacks-network/docs#446), this can happen again.

Community and Supporting Materials
Do you have previous projects, code commits, or experiences that are relevant to this application? What community feedback or input have you received? How do you plan to share your plan to the community over time and as the final deliverable?

There is a general overview of the authflow here: https://docs.stacks.co/build-apps/guides/authentication

Earlier work from 2018 forum post by @larrysalibra et al.

Specification for OAuth2
Documentation for Unstoppabledomain login

[stx-grant-bot]

Thanks for submitting a grant proposal. Our team will review your submission and get back to you.

[jennymith]

Hi @friedger we generally support documentation and standardization of the Stacks auth protocol but we have some suggestions for reworking this grant. What do you think about the following?:

• Instead of a regular document, write a formalized SIP that describes the auth protocol (this could be M1)
• Ensure that the specification is compatible across major Stacks wallets such as the Hiro wallet, Wise, Xverse, etc. OR ensure that the specification is compatible across 2 different implementations of the auth protocol.
• Get the SIP ratified by community (this could be M2)

[friedger]

@jennymith Is a SIP the right place for a specification? Similar to the gaia protocol, I think the auth protocol should be specified independently of the Stacks Blockchain specifications. I could imagine a SIP that states that Stacks apps should/must/may (???) use this or that auth protocol. The only thing were the auth protocol and the Stacks blockchain are linked is when the authenticator returns the optional username.

I think the auth protocol should be specified in a way that it supports more than just Stacks BNS names. The SIP could then specify that Stacks app must return the optional Stacks BNS name, use the c32 encoding of the public key and use the sec256k1 signature.

[larrysalibra]

I agree with @friedger that a SIP is not the appropriate place for authentication specs. Authentication is an application of the stacks blockchain - it isn't an improvement to the stacks blockchain itself.

[jcnelson]

The authentication protocol is strongly tied to the Stacks blockchain, because any implementation of that protocol necessarily queries state from both a smart contract and the attachments system (and moreover, node operators must know to track this particular smart contract's attachments). The smart contract interface and attachment format must be specified as part of the protocol if the protocol does not depend on BNS (which is standardized). Therefore, I think that at least these two aspects of the authentication protocol deserve a SIP, since they both define a smart contract interface standard and potentially require node operators to track its attachments.

[friedger]

My authenticator works even offline. I would consider the part with usernames an optional part that indeed should be defined in a SIP. This grant proposal is only about the part of the authentication protocol without BNS names.

[jennymith]

@jcnelson @friedger Is there a compromise that we can agree on here?

[larrysalibra]

If we look at BIPs (bitcoin) - many specs that are not bitcoin-specific and that are unrelated to the core blockchain are published as BIPs. One well-known example is BIP-0039, generation of human readable deterministic wallets, a specification that is widely used outside of the core bitcoin blockchain and it ecosystems entirely unconnected to bitcoin.

It's very useful to have the deterministic wallet specification defined in bip-0039 because that makes it easily discoverable, easy for developers to communicate about and indicates at least some level of social consensus which hopefully leads to interoperability.

How useful something is for interoperability in the ecosystem and convenience of developers are some of the main considerations we should use when determining what should be a SIP. We don't want developers to have to re-invent the wheel if we have an existing wheel that can easily use.

Since authentication (and identity) have always played a special role in the Stacks ecosystem and we would like them to be widely used by both developers developing in the ecosystem as well as any other developers that might find the specs useful, on reconsideration, I agree with @jcnelson that a SIP is a good place for the authentication specification to live. In the absence of some obviously better place for it to live, I also think it would even make sense for the portion of the authentication protocol that is entirely independent of Stacks to live in a SIP as well. @friedger do you have an suggestions on where such a document would live if not a SIP?

[friedger]

Not really, identity foundation maybe.

If the SIP repo is also intended for these kind of documentations, I am happy to write it down as a SIP.

For the milestones, I would like to start with a draft as M1, and a SIP as M2. Ratification is probably out of scope and a community effort.

[Zk2u]

I would like to start with a draft as M1, and a SIP as M2. Ratification is probably out of scope and a community effort.

Agreed, this sounds good. Have to agree with @jcnelson that authentication is directly linked to the chain and therefore should be a SIP. SIPs will be easier to normalise, too.

I think this should come out as algorithm-agnostic like how Hiro's Web Wallet implementation is now.

[jennymith]

Not really, identity foundation maybe.

If the SIP repo is also intended for these kind of documentations, I am happy to write it down as a SIP.

For the milestones, I would like to start with a draft as M1, and a SIP as M2. Ratification is probably out of scope and a community effort.

Thanks for all the discussion here, everyone. @friedger Happy to get you started on this grant but want to confirm the amount first. Since you'd rather not include ratification in this proposal, should the amount still be $2,000?

[friedger]

@jennymith Yes.
M1: outline: 1 week - 500$
M2: final version as sip including discussion on sip proposal: 3 weeks - $1500

[jennymith]

Sounds good @friedger. This grant has been approved! I'll get started on disbursing M1. In the meantime, can you please update your grant to show that this will be a SIP? Thanks!

[stx-grant-bot]

Congratulations. Your grant is now approved. Please complete the on-boarding link here: https://stacks-grant.netlify.app/onboard?q=fe10225db91b259bdcc0d809bfed8be0

[friedger]

Updated the description!

[jennymith]

Hey @friedger just checking that you've filled out the onboarding form?

[MarvinJanssen]

Following this and happy to be part of the conversation.

[friedger]

!completes_m1

Here is the start of the SIP: stacksgov/sips#50

This completes M1. Currently, I am involved in the discussions about

• authentication on mobile
• fixing profile lookup
• BNS in general (BNS working group)

[friedger]

!m1_complete

[stx-grant-bot]

The agreement has not signed yet

[friedger]

Could you please check why the status still says "sign contract"?

[jennymith]

@friedger Did you receive and sign an agreement on Docusign yet? Let me know! We can still review your M1 in the meantime though.

[friedger]

@jennymith I submitted a signed contract.

[will-corcoran]

Hi @friedger, thanks for submitting M1. You've gotten off to a good start outlining the various components of this SIP. However, we recommend adding a little more content to make this outline more accessible. Someone who doesn't understand BNS initially should be able to read the outline and at least get a sense of what they would need to do to implement this authentication protocol. Specifically, can you please add more information to the first three sections: "Specification," "Authentication Flow," and "Transport Protocol"?

[friedger]

Thank you for reviewing the outline. I understand that more work is needed. However, your comments do not say that the outline is incomplete. Instead of arguing about the outline I prefer to continue to work on the sip. My goal for M1 was to prove
a) that I have a good understanding of the topic,
b) that we now have a place to discuss aspects of the sip and
c) that I have an understanding of the sip process.

[will-corcoran]

@friedger Sounds good. We agree you should keep moving. Please include completing the three sections noted above in your next milestone review - in addition to continued, overall development of the SIP. Thanks, Will

[friedger]

The SIP document is ready for review: stacksgov/sips#50

It describes mainly the current implementation of the Hiro Wallet/stacks.js

Next steps are improving the protocol/format and getting more feedback.

[friedger]

!m1_complete

[stx-grant-bot]

Thank you for completing M1. The grant committee will review and confirm completion or send feedback within a week

[friedger]

The SIP stacksgov/sips#50 has been updated.

It now specifies that the public profile as a verifiable credential.

The transport protocol section has been moved to a new sip.

I think this completes this grant. It would require a new grant to upgrade Hiro Wallet to this spec.

[friedger]

!m2_complete

[stx-grant-bot]

Sorry, you can only complete a milestone if it is active.

[friedger]

!m2_complete

[stx-grant-bot]

Thank you for completing M2. The grant committee will review and confirm completion or send feedback within a week

[will-corcoran]

Hello and thank you for participating in the Stacks Foundation Grants Program!

We are in the process of migrating from GitHub to the new Grants Dashboard. In order to complete your grant, you will need to submit any remaining Progress Review and/or Final Review requests through the Dashboard in order to receive your remaining payments.

• If you have questions about the Grants Dashboard in general please email [email protected].
• If you have questions regarding payments and/or contracts please email [email protected].

Lastly, please note we are marking this grant 'closed' on GitHub for organizational purposes, but it is still 'open' on the Grants Dashboard.

Thanks and we hope to continue to support your efforts with additional grants!

Best,
Will