1 files changed, 124 insertions, 0 deletions
diff --git a/proposals/0000-dns.md b/proposals/0000-dns.md
new file mode 100644
index 0000000..d9d2eae
--- /dev/null
+++ b/proposals/0000-dns.md
@@ -0,0 +1,124 @@
+
+Title: **DEP-0000: DNS**
+
+Short Name: `0000-dns`
+
+Type: Informative
+
+Status: Draft (as of 2018-04-27)
+
+Github PR: (add HTTPS link here after PR is opened)
+
+Authors: Paul Frazee
+
+
+# Summary
+[summary]: #summary
+
+Dat's data structures (HyperCore, HyperDB, and HyperDrive) are addressed using
+cryptographic keys. In the context of Web browsers, a URL scheme is used which
+is structured as `'dat://' {key} '/' {path...}`.
+
+This DEP describes an additional protocol Dats using DNS short names.
+
+
+# Motivation
+[motivation]: #motivation
+
+The cryptographic keys which address Dats are secure and global, but not human-readable. This creates a usability problem.
+
+The goal of this DEP is to leverage DNS to provide human-readable shortnames which map to Dat's cryptographic addresses. The solution...
+
+ - Must provide a single canonical Dat URL for the domain. It should not be possible for a name to have multiple valid mappings. (No conflict.)
+ - Must not be controllable by non-owners of the domain. It should not be possible for third parties to modify the mapping. (Secure.)
+ - Should be accessible to as many users as possible. (Convenient.)
+
+An initial proposal (the [".well-known solution"](https://web.archive.org/web/20171013151452/https://github.com/beakerbrowser/beaker/wiki/Authenticated-Dat-URLs-and-HTTPS-to-Dat-Discovery)) has had prior usage in the Beaker Browser and Dat CLI. A followup proposal (the ["DNS TXT solution"](https://web.archive.org/web/20180427202745/https://github.com/beakerbrowser/beaker/wiki/Dat-DNS-TXT-records-with-optional-DNS-over-HTTPS)) was made recently, but has not yet been deployed. This DEP intends to unify these proposals formally.
+
+
+# Usage Documentation
+[usage-documentation]: #usage-documentation
+
+Users may provide a Dat URL to clients with the following structure: `'dat://' {name} '/'`. 
+
+If the `name` is a 64-character hex string, it should be considered a "key" and no DNS-resolution should occur. If `name` matches the following RegExp, it is considered a "key":
+
+```
+^[0-9a-f]{64}$
+```
+
+If the `name` does not match this RegExp, it is a "domain name" and requires resolution. A Dat client should follow the [resolution process](#resolution-process) to do this.
+
+```
+domain: dat://beakerbrowser.com/
+key:    dat://87ed2e3b160f261a032af03921a3bd09227d0a4cde73466c17114816cae43336/
+```
+
+Users have multiple options for creating a domain-name mapping.
+
+The first option is to set a DNS TXT record at the domain which maps to a "key"-addressed Dat URL. The client will lookup this TXT record first and load the resulting Dat.
+
+The second option is to run an HTTPS server at the domain name which includes a `/.well-known/dat` resource. That resource should provide a text file with the following schema:
+
+```
+dat://{key}
+TTL={time in seconds}
+```
+
+`TTL` is optional and will default to `3600` (one hour). If set to `0`, the entry is not cached.
+
+
+# Resolution process
+[resolution-process]: #resolution-process
+
+Resolution of a Dat at `dat://{name}` should follow this process:
+
+ - Client checks its names cache. If a non-expired entry is found, return with the entry.
+ - Client issues a DNS TXT request for `name`. This request should be issued via a secure transport (see ["DNS-over-HTTPS"](#dns-over-https)).
+ - Client iterates all TXT records given (skip if none). If a record's value matches the RegExp `^dat:\/\/[0-9a-f]{64}\/?$`:
+   - If the record includes a non-zero TTL, store the entry in the names cache.
+   - Return the entry.
+ - Client issues an HTTPS GET request to `https://{name}/.well-known/dat`.
+   - If the server responds with a `404 Not Found` status, client stores a `null` entry in the names cache with a TTL of 3600 and returns a failed lookup.
+   - If the server responds with anything other than a `200 OK` status, return a failed lookup.
+   - If the server responds with a malformed file (see below), return a failed lookup.
+   - If the server responds with a well-formed file, store the entry in the names cache (default TTL to `3600` if not provided) and return the entry.
+
+The `/.well-known/dat` file must match this schema:
+
+```
+'dat://' [0-9a-f]{64} '/'?
+( 'TTL=' [0-9]* )?
+```
+
+# DNS-over-HTTPS
+[dns-over-https]: #dns-over-https
+
+Until PKI can authenticate the DNS lookups (ie via SSL certificates or equivalent) there is a risk that the DNS lookup will be intercepted by an adversary. To protect against this, the client should use DNS-over-HTTPS to lookup the DNS TXT records.
+
+Current providers:
+
+ - [Google](https://developers.google.com/speed/public-dns/docs/dns-over-https)
+ - [Cloudflare](https://developers.cloudflare.com/1.1.1.1/dns-over-https/json-format/)
+
+
+# Drawbacks
+[drawbacks]: #drawbacks
+
+ - The use of the `.well-known/dat` resource over HTTPS creates a dependency on a service.
+ - DNS-over-HTTPS exposes all lookups to the provider and relies on the provider to be honest. However, because this method offsets the risk of MITM attacks, this is a worthwhile trade. Future DEPs should find alternative ways to authenticate domain-name records.
+
+
+# Rationale and alternatives
+[alternatives]: #alternatives
+
+- User-defined names registries could be used instead of DNS, but they would likely suffer from name conflicts without a top-down control.
+- A blockchain (such as Namecoin) could be used instead of DNS, but blockchains currently have poor throughput and require users to sync large amounts of data.
+- DNSSEC could be used instead of DNS-over-HTTPS, but it does not have the same level of support among gTLDs that DNS-over-HTTPS has.
+
+
+# Changelog
+[changelog]: #changelog
+
+- 2018-04-27: First complete draft submitted for review
+