.well-known

This article is a stub. You can help the IndieWeb wiki by expanding it.

.well-known is literally the path "/.well-known/" under a domain and used as a standardized (literally a "well-known") location for discovering domain-wide meta-data, and is generally avoided by IndieWeb-related specs, instead preferring follow your nose discovery techniques and methods.

It has been codified by the IETF and IANA in RFC5785 and registry of Well-Known URIs respectively.

Relevant Uses

• Let's Encrypt for proof of domain ownership
• WebFinger for discovery of user data (e.g. used by Mastodon)
• Dat for linking domains to lookup keys on the dat network
• to specify a Do Not Track policy: https://www.eff.org/de/deeplinks/2017/10/do-not-track-implementation-guide-launched
• Thunderbird e-mail client autoconfiguration: [1], [2]
• W3C Editor's Draft: A Well-Known URL for Changing Passwords

Issues

• Some web hosts restrict customer access to .well-known in shared plans, rendering it unusable for vast amounts of websites. Hosts known to not support full customer access to .well-known:
  • hostinger
• Problem: community sites that are user-editable (e.g. via MediaWiki) could allow anyone to create a .well-known resource (like this wiki page!) or a subresource like .well-known/security.txt
• Criticism: bad approach that is counter to the read-write web and adds extra admintax to all server maintainers: https://chat.indieweb.org/meta/2022-05-13/1652432145141300
  • "the point is .well-known is not the only way to do well-known URLs, so just blocking .well-known from being user-editable isn't enough, you have to go list out every possible well-known URL that might cause a problem if it's user-editable and block that too" @aaronpk May 13, 2022
• Criticism: unnecessary domain-level assumption for use-cases that can by handled by resource-level discovery: it's almost always a web architecture error to design something for a domain (also includes root /noun.txt approaches) instead of designing for an arbitrary URL (HTML at some page).
• Criticism: everyone's supposed to register their .well-known URIs with IANA but pretty much nobody does
• Some uses of well-known require the file be served with a specific content-type, e.g. application/json, which means that is no longer just a static file, and might require editing the HTTP server config to set the header as well

How to test Apache/PHP web host support

Pieces of software like Bridgy Fed or Nextcloud usually either make use of Apache RewriteRules to serve content from .well-known. To check that this is possible on your web host, add the following to your root .htaccess file:

<IfModule mod_rewrite.c>
  RewriteRule
  RewriteRule ^\.well-known/test /well-known-test-succeeded [R=302,L]
</IfModule>

Then, visit yourdomain.com/.well-known/test. If you were redirected to yourdomain.com/well-known-test-succeeded, then your host supports .well-known rewrites. If not, it likely doesn’t — please add your host to the list above!

See Also

• well-known
• https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml
• Alternative: instead of forcing/squatting a specific path on web server admins, use link rel for discovery. The W3C Social Web Working Group resolved on this methodology (also known as "follow your nose") years ago for all the approaches being considered, and subsequently all of the W3C Recommendations they produce used link rel discovery, without any need for ".well-known"
• 2023-08-23 Dan Q: .well-known/feeds (archived)
  • Specification on GitHub (archived)
  • via 2023-08-24 Colin Walker: “Dan Q has suggested …” (archived)
• Marketing vs ops: another reason it is bad to depend on .well-known in practice:

  often times the root domain of a website is run by the marketing team at a company and isn't "owned" by the ops team that is providing whatever service is being discovered