Supporting DID links to sphere content

[gordonbrander]

Recently the team has been discussing the value of supporting a did link form for sphere content. This has many upsides.

DIDs are identifiers (stable and globally unique). Slashlinks are locators (they tell you how to find stuff), but not identifiers. Given that slashlinks dereference to sphere DIDs under the hood, it would be a nice fallback if slashlinks could reference DIDs directly. It would also be nice if that form were a stable identifier.

This choice has cascading effects on the UX of Subconscious, the UX of writing Subtext, the parsing of Subtext, and more. Design is navigating tradeoffs by values. To that end, This note is an attempt to explore and reflect on these interconnected aspects, how they intersect with the design values of Subtext, and to find a balance of tradeoffs that best suit our values.

Values:

• DIDs are an important modular interface.
  • If DIDs are a lego dot, then supporting them means you can click together with many other systems.
• DIDs are not user-friendly, but @petnames are.
  • "If we ever show a DID to a user we have failed."
  • To that end, we want to bias the ecosystem toward @petnames, while supporting dids.
  • Adding more structured syntax to dids exacerbates the problem.
  • Chaining dids is pathological.
• Conformability. E.g. Leaning into valid did syntax makes us conformable to a large number of other systems.
  • Reduces corner cases, sharp edges, surprises.
• Subtext should be simple to write, simple to read, simple to parse.
• The best Subtext syntax is no syntax (e.g. auto-linking http URLs).
  • The second best syntax is what you would write anyway (e.g. > blockquote).
  • The third best syntax is popular syntax from existing systems (e.g. _italic_ or @handles).
  • Subtext is less like Markdown, more like the auto-syntax you get in a social media site. We should not support deep structure or features.
• Things like URLs should just work when you paste them into Subtext...
  • ...Within the limits of keeping parsing simple and unambiguous.
  • E.g. we only auto-link URLs starting with http:// or https:// for this reason.

Previously-resolved tradeoffs:

• URLs are ASCII only. Slashlinks support UTF-8. See Consider how to handle unicode characters in slashlinks #28
  • Resolution: there are specifications for translating between URLs and UTF-8 representations. We should use those. https://en.m.wikipedia.org/wiki/Internationalized_Resource_Identifier
• Did/URL paths and slugs have different syntax.
  • Resolution: slug syntax should always be a simplified subset of paths.
  • They should not get more complicated than ([\w\-]+)(\/[\w\-]+)*

[gordonbrander]

It is worth noting that these are both structurally valid DID URLs:

did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK/foo
did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK@petname/foo

However,

• Other consumers of did:key won't know what to do with the path part.
• Slashlinks allow for UTF-8 characters, so we would have to percent-encode to make slashlinks valid DID URLs.
  • We could ofc just allow UTF-8 directly in Subtext, and percent-encode when parsing.

References:

• did:key https://w3c-ccg.github.io/did-method-key/
• DID URL syntax (which allows a path) https://www.w3.org/TR/did-core/#did-url-syntax
• Path RFC https://www.rfc-editor.org/rfc/rfc3986#section-3.3

[gordonbrander]

One approach we could take is to only allow "absolute" did links, without petnames.

did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK/slug

To traverse from one sphere to another, you would "absolutize" the slashlink, at each step, so there is never a traversal path. This keeps the did path simple. This is in keeping with the idea that the did is an "unknown", so the petnames in their address book do not provide much information security.

This is a valid DID URL, with caveats:

• Other consumers of did:key won't know what to do with the path part.
• Slashlinks allow for UTF-8 characters, so we would have to percent-encode to make slashlinks valid DID URLs.
  • We could ofc just allow UTF-8 directly in Subtext, and percent-encode when parsing.

Regex for whole match (markup would require two regex cases, one for did, one for petname slashlink)

(?:(?<did>did:key:[a-zA-Z0-9_\-%]+)|(?<petname>@[\w\-]+(?:\.[\w\-]+)*))?(?<slug>\/[\w\-]+(?:\/[\w\-]+)*)?

[gordonbrander]

Another approach could be to allow slashlinks after a did, with or without petnames.

did:key:[email protected]/slug

This gets visually complicated quickly. The petnames in the path are not really providing much value.

I believe this is a valid DID URL, with same caveats as above.

[bmann]

This is interesting, but possibly premature? Other systems mostly don't know what to do with DIDs at all, and haven't thought about the interfaces.

Maybe @-syntax is correct? So either @petname (which resolves to a DID) or @did:key (which may get looked up and replaced with a label or a petname).

Also: what about other mentions that themselves resolve to a DID? So, @bmann.ca has an _atproto subdomain / TXT record which contains a DID.

@boris.fission.name contains a _did subdomain / TXT record.

DNS flavoured links that resolve to DIDs at well known locations could be a good start?

[gordonbrander]

Did slashlink syntax

I'm strongly partial to

did:key:abc123/slug

(<did>|<petname>)<slug>

If DID, no petname. If petname, no DID. Rationale:

• Disallowing petnames after DIDs makes did-form slashlinks unambiguous unique identifiers
  • Also <did><petname><slug> is a bit weird, because it's backwards. Did is root, but is at the front, whereas in petnames, the root is at the end.
  • Also <did><petname><slug> satisfies none of the UX goals of petnames
    • A did with petnames is so complicated it may as well be a black box to the user
    • If it's a DID, it's "anonymous" to you, and its address book is not to be trusted anyway
• It’s a valid DID-URL, assuming you percent-encode any Unicode chars on the backend (even if not all clients know what to do with the path part)

I like not having the @ for did-slashlinks, but I can see the other side of it. did:method is enough for us to sniff out supported did methods in the text. However, since we are "hijacking" the path-part of DID-URLs for addressing sphere content, I could imagine the leading @ being useful for disambiguating this use. Another possibility might be a custom DID method. Going to mull on this for a bit.

For now, we have implemented did:key:abc123/slug style slashlinks for database indexing in the app, but are not exposing them on the user-facing markup side until we work this out a bit more. See subconsciousnetwork/subconscious#561

DNS names

Worth noting that @boris.fission.name creates an ambiguity with potential @boris.fission.name petnames. This ambiguity might be worth coping with for the utility of bridging to DNS. It's also possible to bridge to DNS via making com, org, name, etc, spheres with address books to DNS.

I'm not sure if this decision should belong to Subtext, or the app implementing it. Spec'ing this into subtext seems like too much app domain knowledge leaking back into a markup spec. Perhaps if we pursue it, it could belong to an "extension spec".