Skip to content

Instantly share code, notes, and snippets.

@diracdeltas

diracdeltas/verification-spec.md

Last active June 14, 2017 20:48
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save diracdeltas/7c1792a7484ca98ab016710467d1e729 to your computer and use it in GitHub Desktop.
Save diracdeltas/7c1792a7484ca98ab016710467d1e729 to your computer and use it in GitHub Desktop.
Download ZIP
protocol for domain ownership verification in Brave Payments
Raw
verification-spec.md

Intro

The Brave browser now includes a way for users to allocate ~monthly anonymized micropayments for online publishers. These payments are held in an escrow wallet managed by Brave Inc., which must then provide a way for publishers to claim their total allocated funds (minus processing fees).

Note that for 1.0, we only support allocating payments at the domain-name level. Hence, nytimes.tumblr.com and forbes.tumblr.com would count as separately payable publishers, but any funds calculated based on pageviews for myspace.com/forbes and myspace.com/nytimes would simply go to myspace.com. Note that currently Brave includes an exception list that prevents us from paying platforms with user-generated content, like youtube.com.

Verification steps

  1. foo.example.com is eligible to claim payments if its total contributed amount is at least $10. Once this happens, Brave sends verification initiation emails from payments@brave.com to {webmaster, hostmaster}@foo.example.com (per RFC 2142) containing a random hex-encoded token T with at least 128 bits of entropy. (TODO: Maybe also send email to the WHOIS contact?)
  2. Upon receiving T, the domain owner constructs the value V = sha256(T || W), where W is the Base58-encoded address of the Bitcoin wallet where the domain owner wishes to receive funds.
  3. The domain owner does one of the following:
    • Put the hex-encoded value of V in a DNS TXT record for foo.example.com
    • Put the hex-encoded value of V in a text file located at https://foo.example.com/.well-known/brave-payment-info.txt. This option is only available for domains that support HTTPS with a valid certificate.
  4. The domain owner sends a verification request email to payments@brave.com from <any_account_name>@foo.example.com with either Verify DNS or Verify HTTPS (depending on which verification method was selected in Step 3) in the email subject line and W in the email body. If Brave does not receive a verification request email from the domain owner within 1 week of sending a verification initiation email, Brave resends the email in Step 1.
  5. Upon receiving the email from Step 4, Brave checks for a valid DKIM signature over both the subject header and the body. If none is found, verification returns false and the next step is skipped.
  6. Brave calculates V and verifies that it is equal to either the DNS TXT record value or the body of the text file at https://foo.example.com/.well-known/brave-payment-info.txt, depending on which method the domain owner selected. To mitigate DNS hijacking in the former case, Brave should use multi-path probing techniques.
  7. payments@brave.com replies to the email from the domain owner in Step 4 notifying them that verification succeeded or failed.
  8. If verification fails, the domain owner may repeat Steps 3-4 up to 5 times per payment period (30 days?). After the 6th attempt, Brave will ignore verification request emails from the domain owner.
  9. If verification does not succeed within the payments period, Brave will retry Step 1 with a new token during the next payments period if foo.example.com is still eligible. Previous tokens are invalid as soon as a new token is sent.

Other considerations

Unclaimed funds

Publisher funds that are unclaimed after some to-be-determined time period due to verification failure will be redistributed in some to-be-determined manner, probably among the set of publishers who have verified themselves. TODO: What about publisher funds that are unclaimed because the total amount for the publisher was less than $10? Do these rollover into the next pay period for the publisher?

Publisher wallet address changes

Publishers may wish to rotate wallets, ex: due to loss of private key. To initiate this process, they must send an email from <any_account_name>@foo.example.com to payments@brave.com with the subject line Change Brave wallet address. Upon receiving this email, Steps 1-9 are repeated. Publishers can only request wallet address changes at most once per pay period.

Verifying publishers who don't control .well-known or DNS records for their site

We will probably have to set up partnerships with the bigger publisher sites like Tumblr, Youtube, Medium, etc. Some of this might already be doable through OAuth, etc.

@diracdeltas
Copy link
Author

Note that this requires us to set up DKIM/SPF/DMARC for the brave.com accounts sending payments emails

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment