.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.

Current Uses

Let's Encrypt for proof of domain ownership
Thunderbird e-mail client autoconfiguration: [1], [2]
W3C Working Draft: A Well-Known URL for Changing Passwords

Questionable Uses

These should really be done via rel values instead:

Do Not Track policy: https://www.eff.org/de/deeplinks/2017/10/do-not-track-implementation-guide-launched
WebFinger for discovery of user data (e.g. used by Mastodon)
- there was a session at IWC SD 2023 discussing how to use rel values instead

Past Uses

The following methods or utilizing technologies have been deprecated and/or obsoleted. Listed here for historical purposes only.

Dat for linking domains to lookup keys on the dat network

Criticism

A summary of why most uses of /.well-known/ are a bad mistake.

unnecessary and poor reinvention: many proposed uses of /.well-known/ are already handled by existing rel values, for far more use-cases and web hosting options
more complex to author — typically requires sidefiles
harder to publish — requires site admin root access
likely to become inaccurate — Ruby’s postulate
fragile — site admins frequently break /.well-known/ for individual pages/webapps inside.
security vulnerability for community sites — community sites that are user-editable (e.g. via MediaWiki) could allow anyone to create a /.well-known/ resource

Most of this summary is from part of a longer post https://tantek.com/2024/105/t1/w3c-advisory-committee-meetings.

Some of these expanded:

Bad reinvention

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 broader well-known root file /noun.txt approaches) instead of designing for an arbitrary URL (HTML at some page) and using a rel attribute for discovery

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)

Harder to publish

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
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

Unsuitable for community sites

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
Due to that vulnerability it’s a bad approach that is counter to the read-write web and adds extra admintax to all server maintainers:
- "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 on May 13, 2022

In practice unregistered

Everyone's supposed to register their .well-known URIs with IANA but pretty much nobody does

https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml

Fragile due to corporate realities

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

How to

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!