what is a Signed Exchange (SXG)?

Signed Exchange (SXG) is an emerging web standard that allows a website to sign its content and serve it to the browser. The browser can then verify the signature and cache the content for later use. This is useful for offline browsing, as the browser can serve the cached content even when the user is offline.

Read more

Whilst on a trip, left without internet, I found myself in a situation where I needed to look up some documentation.

I want a simple solution where, I build some documentation, sign it and upload it to an end point and the rest is taken care of.

+-----------------+   ❶      +-----------------+
|     CI          |--------->|  PKI ACME Prov  |
| OIDC Token  ❸   |<---------|     Priv Key    |
+-----------------+   ❷      +-----------------+           
        |                  
        |    ❹               
        | 
        |                   
        v
+-----------------+
|                 |
|  docuciti.es    |
|                 |
+-----------------+

1. request a Certificate with the OIDC token
2. get the certificate
3. sign the documentation
4. upload the signed documentation to the endpoint

simples.

but why?

docs.rs, pkg.go.dev already serve this content, now you've added another one. why?

Well not quite. pkg.go.dev actually will pull any go repo from any supported vcs and build documentation for it, which is great but that requires a large infrastructure from google to support. And that infrastructure can actually break more independent source forges.

The proposal with docuciti.es is to have a simple way to assoicate a commit to a signed web package.

The other maybe more important thing is that you can use these signed exchanges as internal caching for external documentation.

For instance if someone in your organization has already accessed the documentation of let's say serde you can simply serve the relevant signed exchange from your own servers without being subject to any analytics or tracking. Which I think is a cool thing.

And it works on planes too ✈️

But I think what is the most exciting bit is documentation preservation.

At least that's the plan.