fang Fang-

identity verification service

Context (~2025.04.02): This document was originally shared within Tlon on ~2024.07.26 and contains the initial feature & implementation spec for the verifier service. This publicly accessible copy lacks discussion and roadmap sections, but is otherwise unaltered, provided for posterity.

overview

This document describes an identity verification service for Urbit ships. The primary end goal of implementing this service is supporting contact discovery.

The specification below aims to support the following features:

mirage (eauth)

Urbit's identity layer pervades everything on Mars. Unfortunately, despite talking to Mars a lot, Earth is not quite so fortunate. A notable example are requests made to Urbit's HTTP server, Eyre. Presently, when viewing for example a blog post hosted by someone else's urbit, there is no way for a user to leave a comment signed by their own identity right then and there: they need to go through their own urbit instead, maybe even installing a matching blog app.

the open eyre

Some have bemoaned Urbit's absence on the clearnet. Everyone accesses their urbits via HTTP, but few apps use that same affordance to expose themselves to the public at large.

But that's not very strange given the current state of HTTP access. As long as you are authenticated as the host ship, you get first-class access to the ship through Eyre's "channels" system, letting you pretend you are in userspace by

eyre caching

Urbit can function as a webserver, but isn't as fast at that as it could be. It would be good if it could comfortably serve hundreds or even thousands of pageviews a minute. Benchmarks for the status quo are left as an exercise to the reader.

approaches to improving performance

There are two ways in which we can use the scry namespace to make Eyre more performant. Truthfully, there are probably more than two ways, but these specific two have highest relevance in Eyre's recent history.

Publication cache: Eyre can track a publication cache with static, known-ahead-of-time responses bound to specific endpoint paths. Eyre would tell the runtime about these known responses, which the runtime would use to serve up responses to GET requests.
Stateless reads: The runtime, when receiving a GET request, can scry into Eyre to retrieve a response for it. Eyre might scry into agents to further resolve the read. This way, with GET requests handled as pure reads, they could theoretically be

First off, general u3/vere docs are here. They feel pretty opaque, and Paul/~fodwyt, an experienced vere dev, has admitted to reading them every so often and still bringing back new understanding of the doc each time. I suggest to skim it, most of it isn't exactly relevant, but do read the sections on reference counts and reference protocols.

For a quick overview on what goes into adding a jet, see this commit as an example. (Matching Hoon change is here though only the use of ~% and ~/ is of interest.)

Jet registration

To get your jet called whenever the matching Hoon code is called, that code needs to be hinted. Use ~/ and so

	::
	:::: /lib/test/clay/hoon
	::
	// /===/sys/vane/clay
	=+ cloy=(. !>(..zuse))
	::
	\|%
	++ core cloy
	++ work
	\|_ cor/_core

	// ==UserScript==
	// @name Open Youtube links in IINA
	// @namespace https://palfun-foslup.urbit.org/
	// @description Replaces Youtube links with a link to open them in IINA. Set a useful whitelist for yourself.
	// @include youtube.com/
	// @updateURL https://gist.githubusercontent.com/Fang-/7db1ac4e798a7128f006fa535f42cfb0/raw/25b60b08e55be87d2b0d5630d1f580b15ca2870d/iina-youtube.js
	// @downloadURL https://gist.githubusercontent.com/Fang-/7db1ac4e798a7128f006fa535f42cfb0/raw/25b60b08e55be87d2b0d5630d1f580b15ca2870d/iina-youtube.js
	// @run-at document-end
	// @version 1.0
	// ==/UserScript==