Repository Discovery via WebFinger

A repository refers to a version control managed source code which may be browsed over HTTP or downloaded with specific tooling.

Repository URI

A repository URI identifies a code repository and optionally the host that is resides on. This value is similar to RFC7565. The slug and hostname part MUST match the URI path specification as defined in RFC3986-3.3 while the hostname, if specified, must match RFC3986-3.2.2

repository-uri = prefix slug hostname

prefix      = "repository:"
slug        = rfc3986-path
hostname    = [@ rfc3986-hostname]

Slug

The Slug represents a unique string that identifies a repository at a particular code forge. Repository refers to a VCS managed codebase of some kind, e.g. a Git repository.

Hostname

If the hostname part is missing then the address of the server receiving the query is assumed. For example the following two queries are equivalent:

https://example.org/.well-known/webfinger?resource=repository:spartacus/game
https://example.org/.well-known/webfinger?resource=repository:spartacus/game@example.org

TODO: Make this an actual spec, for now, some Python:

from urllib.parse import urlparse, quote_plus

def from_string(text):
    url = urlparse(text)
    if not url.path:
        return (None, None)
    split = url.path.split("@", 1)
    if len(split) == 2:
        return (split[0], split[1])
    return (split[0], None)

def to_string(slug, domain=None):
    if domain:
        return quote_plus(f"repository:{slug}@{domain}")
    else:
        return quote_plus(f"repository:{slug}")

Properties

http://feed-forge.org/ns/vcs-type

Identifies VCS types, valid strings are:

bzr (GNU Bazaar) bazaar.canonical.com
darcs (Darcs) darcs.net
fossil (Fossil) fossil-scm.org
git (Git) git-scm.com
hg (Mercurial) mercurial-scm.org
pijul (Pijul) pijul.org
svn (Apache Subversion) subversion.apache.org

http://feed-forge.org/ns/spdx-identifier

Refers to a valid SPDX identifier, see license-list

Link Extension Types

Avatar

Forges that allow users to configure a logo can expose this information as an avatar for use in other applications.

{
  "rel": "http://webfinger.net/rel/avatar",
  "href": "https://example.org/stylized-logo.png"
}

Homepage

Link to an HTTP representation of the repository.

{
  "rel": "http://feed-forge.org/rel/homepage",
  "href": "https://example.org/spartacus/game"
}

Description

A short text representation of the repository.

{
  "rel": "http://example.org/rel/description",
  "titles": {
    "en-us": "A Text Adventure Written in FORTRAN 77",
    "es": "Una Aventura de Texto Escrita en FORTRAN 77"
  }
}

License

A license SPDX identifier and link to the license's full text.

{
  "rel": "http://feed-forge.org/rel/license",
  "href": "https://example.com/example/spartacus/tree/LICENSE",
  "properties": {
    "http://feed-forge.org/ns/spdx-identifier": "GPL-2.0-or-later"
  }
}

Clone Links

Clone links define how one can download a copy of the remote software onto their own server.

{
    "rel": "http://feed-forge.org/rel/clone",
    "href": "https://example.org/example/spartacus",
    "properties": {
        "http://feed-forge.org/ns/vcs-type": "git"
    }
}

WebFinger Query

A WebFinger query may be used to identify detailed information about a public repository at a particular forge. Here is an example response about a fictitious repository:

GET https://example.org/.well-known/webfinger?resource=repository:spartacus/game

{
  "subject": "repository:spartacus/game",
  "aliases": [
    "https://example.org/spartacus/game"
  ],
  "links": [
    {
      "rel": "http://webfinger.net/rel/avatar",
      "href": "https://example.org/stylized-logo.png"
    },
    {
      "rel": "http://forge-feed.org/rel/description",
      "titles": {
        "en-us": "A Text Adventure Written in FORTRAN 77",
        "es": "Una Aventura de Texto Escrita en FORTRAN 77"
      }
    },
    {
      "rel": "http://feed-forge.org/rel/clone",
      "href": "https://example.org/spartacus/game",
      "properties": {
        "http://feed-forge.org/ns/vcs-type": "git"
      }
    },
    {
      "rel": "http://forge-feed.org/rel/license",
      "href": "https://example.com/spartacus/game/tree/LICENSE",
      "properties": {
        "spdx-identifier": "GPL-2.0-or-later"
      }
    },
    {
      "rel": "http://forge-feed.org/rel/label",
      "properties": {
        "http://feed-forge.org/ns/label": "fortran"
      }
    },
    {
      "rel": "http://forge-feed.org/rel/label",
      "properties": {
        "http://feed-forge.org/ns/label": "text-adventure"
      }
    }
  ]
}

Security

Repositories which are not publicly available should not be identifiable by making webfinger queries at all. A repository which is private MUST return the same response as a repository which does not exist when making a webfinger request.

GET https://example.org/.well-known/webfinger?resource=repository:spartacus/game
200
GET https://example.org/.well-known/webfinger?resource=repository:example/private-repository
404
GET https://example.org/.well-known/webfinger?resource=repository:example/non-existent-repository
404