OCapN locators / introduction by serialized reference

[tsyesika]

When it comes to sharing a sturdyref or having a machine address, we need a way to express this in a standard way. There are several things to consider here:

• What format of the URI to use?
• Do we need to support hints?
• What kinds of URIs do we support? (probably at minimum: URIs to a machine & sturdyrefs, but what about certificates for example?)

To kick the ball rolling on this Goblins uses this format for machines:

ocapn://<transport-address>.<transport>

and for a sturdyref is:

ocapn://<transport-address>.<transport>/s/<swiss-num>

[jar398]

I want to question the need for these things to be URIs. I used to advocate for a URI form for sparse capabilities but after pushback from independent sources that I found credible I'm not so sure any more. The argument is basically that, regardless of how wrong it is, it is human nature to put URIs (those found in log files, bookmark lists, and so on) onto insecure data paths (or rather: for the data paths that URIs find themselves on to be made insecure). The concern is mainly server-side leaks when using generic web toolkits, rather than browsers, which usually have some notion of respecting privacy.

Rather than argue about principles (e.g. "just don't put them on insecure channels" which is what I kept saying), first I would like to know the intended use cases that require them to be URIs.

The alternative is just to make them some kind of string that we don't call a URI. That would force them onto different data paths from URIs. It's no guarantee of privacy on its own but it should help.

[dckc]

ocapn://<transport-address>.<transport>

Seems to me that should be <transport>://<transport-address> or perhaps ocapn-<transport>://<transport-address> or <transport>+ocapn://....

in particular, onion://... instead of ocapn://...onion

[zarutian]

I rather lean towards ocapn:<transport>:<machineOrVatLocatorForThatTransport>/ as the common prefix. Then after the first / we get choices such as s/<swissNum> for swissNum (read “password capability” if you are looking into the old literature) based sturdyrefs and many others for all kinds of cerificates based sturdyrefs.

ocapn-uri := “ocapn:” transport-scheme-identifier “:” vatLocator “/“ ocapn-uri-payload
transport-scheme-identifier := “tor” | “tls” | “websocket” | “webrtc” | <others>
vatLocator := <depends on the transport but must be self authenticating>
ocapn-uri-payload := swissNumPayload | macaroonPayload | ActiveCapCertPayload | UcanPayload | BisquitPayload | <others>
swissNumPayload := “s/“ swissNum
macaroonPayload := “mr/“ macaroon
ActiveCapCertPayload := “acc/“ ActiveCapCert
UcanPayload := “ucan/“ ucan
BisquitPayload := “bq/“ bisquit

and probably others in that wane/vein/waine.

[ocdtrekkie]

@zarutian So with your example, a connection to my Sandstorm server (which in non-OCapN format, is using HTTPS URLs) might look like:

ocapn:tls:ocdhost.sandcats.io/s/mQ3Dn17biDW3FcplNVfEynE2fto__QfGz2RUSoDTc-r

compared to our normal sharing URL, which would look more like

https://ocdhost.sandcats.io/shared/mQ3Dn17biDW3FcplNVfEynE2fto__QfGz2RUSoDTc-r

[ocdtrekkie]

I think I agree with @dckc that it's probably ideal to move the transport type up to the front of the URI/string. Arguably .onion addresses are actually just fake TLDs for DNS names, not a real statement of a transport type.

Especially if @zarutian expects websocket and webrtc transport types to be specified potentially, treating all of them as TLDs is weird (and would clash with the actual DNS address of the servers in question, I presume).

There's probably some value in it not looking like a URL if we don't want people to assume they can enter it into a browser. All things that look like URLs will get entered into browsers, if there isn't a law for that defined somewhere, there should be.

[zenhack]

I still think we should punt this off until we have a clear idea of what the content of a sturdyref is going to be, independent of syntax. In particular, I could see a sturdyref format that provides multiple possible transports to connect to the relevant machine. Considerations like that might conflict with whatever syntax folks like here, and it seems cumbersome to interleave those two discussions.

[dckc]

I still think we should punt this off until we have a clear idea of what the content of a sturdyref is going to be, independent of syntax. ...

I have some sympathy for that (concur with @jar398: "I would like to know the intended use cases that require them to be URIs." or IOW: please tell me a story, ideally including some examples...), but meanwhile,

1. we have a stated goal/obligation to start with the 2 Spritely implementations
2. those implementations have a concrete URI syntax

and

3. I think it should at least change, if not go away.

Also,

4. The chair-ish people have pointed to this in agenda discussions, which represents some obligation to speak-now-or-forever-hold-your-peace

[zenhack]

In any case, if we are tackling this now then: I'll add myself to the list of folks that don't think these should be URIs, and also want to step back and identify use cases for these; I assume we expect users to see these somehow, otherwise we should just keep things as structured data. So how do they get used?

[zenhack]

Note that with the default config on modern browsers, if you paste something in the address bar that looks URI-ish but starts with ocapn:, which the browser does not actually recognize as a URI, it doesn't just error, it ends up in a search engine. Not what we want to have happen to a sturdyref. I agree that's an argument against URI signifiers.

[ocdtrekkie]

I mean, browsers will do that for any string that doesn't explicitly start with http:// or https:// at this point. Even Firefox tends to be aggressive about searching for, say, intranet URLs that lack a protocol.

[zenhack]

Another idea I want to put in the mix is, we may want to specify multiple possible ways to form a connection to a peer (per Agoric/documentation#18 I'm going to start using "peer" instead of "vat" when we're talking about network peers instead of units of concurrency). This suggests that a simple <transport-address>.<transport. may be insufficient to find a peer. I'm going to lay down some capnp schema to describe a possible format for the structured data version of what this might look like; we can debate possible URI syntax after, and obv. we wouldn't necessarily use capnp for this, but it's a good way to notate a data format, so to get the ideas down:

struct SturdyRef {
  swissNum @0 :Data;
  peer @1 :PeerLocator;
}

struct PeerLocator {
  publicKey @0 :Data; # Serves as unique id for the peer
  connectionOptions @1 :List(ConnectionOption);
}

struct ConnectionOption {
  union {
    tor @0 :Text; # onion address
    websocket @1 :Text; # websocket URL
    tcp :group {
      # A tcp host & port to connect to directly
      port @2 :UInt16;
      host :union {
        byName @3 :Text;
        byIp @4 :Data;
      }
    }
    # Maybe some other options
  }
}

To connect to a peer given a PeerLocator you would walk down the list of connection options until you found a suitable one and use that.

If we want ConnectionOption to be more easily extensible without coordination, we could do something like:

struct ConnectionOption {
  typeId @0 :UInt64;
  info @1 :AnyPointer; # value of the specified type; peers that don't recognize typeId can just skip this option.
}

...but the former is a bit clearer for discussion purposes.

[cwebber]

What if instead of talking about URIs we talked about:

• "string representations of OCapN addresses" (which may or may not use the URI format) which are an encoding of a very specific structure
• Encouraging people to use structured representations and NOT the string representations, wherever possible
• Encouraging encapsulation of structured representations (display in the GUI should not, in most cases, expose a URI from which a user can unpack a sturdyref)

Whether or not we choose to use URIs as a string structure, we can at least agree on the rest.

[cwebber]

But actually, I'm probably all for not having these be URIs. And in fact, we originally did have a format like ocapn:<transport>:<machineOrVatLocatorForThatTransport>/ but we threw it out in favor of the ocapn:// stuff to make it actually map the URI spec more "properly". Maybe avoiding calling these or working like URIs at all is a feature?

But note that the did: and urn: folks also call these URIs, even though they don't map very well to the URI spec ;)