Bearer URIs RFC

[Pierre Thierry]

Hi everyone,

I've been thinking about bearer URIs for a long time, especially since the question of selecting credentials to use comes up quite often when discussing REST/HATEOAS…

My core idea was the same as Neil Madden, I discovered (putting the token in the authority), and I started to put together an RFC for the IETF. I realized that the question of relative URIs might be a tricky part, as the hierarchical nature of URIs basically presumes ambient authority… The current version is very preliminary, and every section needs a lot of work, but I'd like to get feedback very early.

https://kephas.github.io/bearer-uri/

I think Neil Madden's idea of the UserOnly parameter might be a good idea, and the part of his article on protection in the browser might make an interesting annex if he agrees.

What do you think, and do you know if there's anything implementing something like those URIs out there? In my last team where we deployed a capability-based API, we basically used objects in the JSON payload with a url and cap fields, so we side-stepped the URI question, I wonder if others did differently...

I also wondered if it would be useful to mention WebKeys in an annex...

Curiously,
Pierre Thierry
--

pie...@nothos.net
0xD9D50D8A

[Alan Karp]

I only did a quick scan of your spec, so forgive me if I missed something significant.

Your scheme is an improvement over waterken (you should cite it), which puts the bearer token in the URL fragment.  Unfortunately, secrets in the authorization header do leak.  The problem is significant enough that a follow-on spec, AAuth, uses signed JWTs as tokens.  I'm on a task force on AI agent safety, and we've ruled out bearer tokens, including Macaroons and Biscuits, because of the leakage problem.

I saw that revocation is a TODO.  You also need a section on attenuated delegation.  A non-normative section on responsibility tracking would help developers.

--------------
Alan Karp

--
You received this message because you are subscribed to the Google Groups "friam" group.
To unsubscribe from this group and stop receiving emails from it, send an email to friam+un...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/friam/1d65f1fd-1c69-414a-a9d1-90d9810fc83c%40nothos.net.

[Tristan Slominski]

Not sure if you find this useful, but I've used this bearer URI spec for a few years https://github.com/capabilityio/capability-uri 

[Pierre Thierry]

Le lundi 3 août 2026 à 19:37:13 UTC+2, alan...@gmail.com a écrit :

Your scheme is an improvement over waterken (you should cite it), which puts the bearer token in the URL fragment.

Yes, I wondered if it should go in an appendix but maybe it would be better simply as the prior art in the first section.

 

  Unfortunately, secrets in the authorization header do leak.  The problem is significant enough that a follow-on spec, AAuth, uses signed JWTs as tokens.  I'm on a task force on AI agent safety, and we've ruled out bearer tokens, including Macaroons and Biscuits, because of the leakage problem.

I'm curious, wasn't it possible to include the notion of binding a capabilty to a session key in Biscuits? 

 

I saw that revocation is a TODO.  You also need a section on attenuated delegation.  A non-normative section on responsibility tracking would help developers.

Are there existing texts on the latter I could draw inspiration from? (or pillage with the author's consent)

--

Pierre Thierry

[Pierre Thierry]

Le mardi 4 août 2026 à 06:16:13 UTC+2, tristan....@gmail.com a écrit :

Not sure if you find this useful, but I've used this bearer URI spec for a few years https://github.com/capabilityio/capability-uri 

Ha, thanks! I started naming my scheme cap: then I discovered the two existing proposals using bearer in the naming and I didn't look for things named "capability URI"...

I decided not to put the token in the fragment because I'd like to retain the ability to embed a full URI with path, query and fragment. 

--

Pierre Thierry

[Alan Karp]

On Tue, Aug 4, 2026 at 4:13 PM Pierre Thierry <pie...@nothos.net> wrote:

I'm curious, wasn't it possible to include the notion of binding a capabilty to a session key in Biscuits? 

I don't know.

 

I saw that revocation is a TODO.  You also need a section on attenuated delegation.  A non-normative section on responsibility tracking would help developers.

Are there existing texts on the latter I could draw inspiration from? (or pillage with the author's consent)

The only writeup I know is the Horton paper, which is all about responsibility tracking in an object reference as capabilities system.  You have other options in a system with opaque bearer tokens.  For example, you hold your delegate responsible and it holds its delegate responsible and it holds ...  In this approach it's up to the delegator to keep track of the necessary information.  Alternatively, if you do attenuated delegation via token exchange, the authorization server can keep the responsibility info.

--------------
Alan Karp

[William ML Leslie]

Really enjoying both Pierre's spec and Tristan's repos (why did I not know about these sooner?!)

The only thing preventing everyone from putting the secret into the userinfo iirc was that the browser refuses to preserve that field.  if you're outside of the browser, you can put the secret anywhere you like.  Does it eat userinfo on custom schemes?

Was there ever documentation on the httpsy scheme?  I downloaded waterken a few months ago to learn more and I couldn't even find the implementation.  Assuming this was not just a dream, I think the userinfo held the fingerprint of the signature to use for establishing an httpsy session, which would normally live in the host section of a regular webkey.  I sometimes wonder if there was a protocol built in for key rotation.

On delegation, it would be nice to loudly normalise that whenever someone creates a link to share that we store and display the delegations that have been made, and track them with the time they were created and probably an additional field to record why you shared the link, or who you shared it with.  Allow you to delete or put an expiration time on them.  Marc can finally stop letting Alan drive his car (it always comes back with fresh scratches).

--

William ML Leslie

Get MarkM to do it, he always gets the finest assigned numbers.

[William ML Leslie]

On Thu, 6 Aug 2026 at 23:52, William ML Leslie <william.l...@gmail.com> wrote:

[on the httpsy scheme]  I sometimes wonder if there was a protocol built in for key rotation.

I say this because I think it's wonderful that a server implementing webkeys doesn't need to stop supporting old keys, it's entirely within the client's control whether to continue using an old key or to upgrade.

--

William ML Leslie

BRB installing firefox version 20 so I can talk to iLO.

[Alan Karp]

On Thu, Aug 6, 2026 at 6:52 AM William ML Leslie <william.l...@gmail.com> wrote:

The only thing preventing everyone from putting the secret into the userinfo iirc was that the browser refuses to preserve that field.  if you're outside of the browser, you can put the secret anywhere you like.  Does it eat userinfo on custom schemes?

The real problem is the secret leaking.  There are just too many systems out there that log information they're explicitly told not to log.

 

Was there ever documentation on the httpsy scheme?  I downloaded waterken a few months ago to learn more and I couldn't even find the implementation.  Assuming this was not just a dream, I think the userinfo held the fingerprint of the signature to use for establishing an httpsy session, which would normally live in the host section of a regular webkey.  I sometimes wonder if there was a protocol built in for key rotation.

The Java version of Waterken was on a Subversion server, probably in Anguilla where Tyler kept the YURL server.  I used waterken for a couple of projects but never came across anything related to key rotation.

On delegation, it would be nice to loudly normalise that whenever someone creates a link to share that we store and display the delegations that have been made, and track them with the time they were created and probably an additional field to record why you shared the link, or who you shared it with.  Allow you to delete or put an expiration time on them.  Marc can finally stop letting Alan drive his car (it always comes back with fresh scratches).

Storing all that information is a privacy nightmare.  It's less intrusive if each delegator keeps track of its own delegations.

All certificate capability systems I've seen lately have explicit expiration times.

--------------
Alan Karp

[William ML Leslie]

On Fri, 7 Aug 2026 at 07:08, Alan Karp <alan...@gmail.com> wrote:

On Thu, Aug 6, 2026 at 6:52 AM William ML Leslie <william.l...@gmail.com> wrote:

The only thing preventing everyone from putting the secret into the userinfo iirc was that the browser refuses to preserve that field.  if you're outside of the browser, you can put the secret anywhere you like.  Does it eat userinfo on custom schemes?

The real problem is the secret leaking.  There are just too many systems out there that log information they're explicitly told not to log.

Having made extensive use of application load balancers in the cloud, I'm familiar with the problem, but the big plus of having your own scheme is that nothing existing implements it, so you are completely in control over everything server side.

You do still have to worry about sanitisers in email clients and other office and communication software, such as microsoft's safelinks.

 

 

On delegation, it would be nice to loudly normalise that whenever someone creates a link to share that we store and display the delegations that have been made, and track them with the time they were created and probably an additional field to record why you shared the link, or who you shared it with.  Allow you to delete or put an expiration time on them.  Marc can finally stop letting Alan drive his car (it always comes back with fresh scratches).

Storing all that information is a privacy nightmare.  It's less intrusive if each delegator keeps track of its own delegations.

The real privacy nightmare is that if I delete a file from google drive, I don't even get told about any URLs I've shared to the file.  They silently continue to work.  _That_ is a privacy nightmare.  Making it clear what shares I have created not only gives me visibility into the status of the document, but allows me to explicitly delete specific delegations.  I'm not sure how my ability to label them rises to a noteworthy level of worry.

All certificate capability systems I've seen lately have explicit expiration times.

The reason I say I'd like to normalise it is because I think we should start expecting this in UI.  You create a delegation in response to a user request?  Make it easy for them to catalogue and revoke it.

--

William ML Leslie

A machine for replacing the CA mechanism?

[Tyler Close]

You've temporarily raised the dead. ;) Some answers inline below.

On Thu, Aug 6, 2026 at 2:08 PM Alan Karp <alan...@gmail.com> wrote:
>
> On Thu, Aug 6, 2026 at 6:52 AM William ML Leslie <william.l...@gmail.com> wrote:
>>
>>
>> The only thing preventing everyone from putting the secret into the userinfo iirc was that the browser refuses to preserve that field. if you're outside of the browser, you can put the secret anywhere you like. Does it eat userinfo on custom schemes?
>>
> The real problem is the secret leaking. There are just too many systems out there that log information they're explicitly told not to log.
>
>>
>> Was there ever documentation on the httpsy scheme? I downloaded waterken a few months ago to learn more and I couldn't even find the implementation. Assuming this was not just a dream, I think the userinfo held the fingerprint of the signature to use for establishing an httpsy session, which would normally live in the host section of a regular webkey. I sometimes wonder if there was a
protocol built in for key rotation.

There was a specification for the httpsy scheme, but I can't find a
link to it at the moment. I haven't maintained the project in over a
decade, so the page might not be online anymore. The httpsy scheme did
not get much deployment due to the difficulty of adding new URL
schemes to browsers at the time. Instead, we deployed within the
normal https scheme and tucked the needed information into there. The
httpsy scheme had the advantage that it included a list of ip
addresses for nameservers to contact to get the current location of
the server hosting the service identified by the public key hash in
the URL.

Both schemes included support for key rotation. The hash in the URL
was the hash of the certificate authority to trust to sign the
certificate deployed on the running service. This used the normal
X.509 certificate chains. The idea was to keep the keypair matching
the hash in the URL offline, and only use it to sign the certificate
deployed on the running server. The software that Alan used
implemented this feature, though we never did rotate keys.

--Tyler

[๏̯͡๏ Jasvir Nagra]

Welcome back to the world (even if it's briefly) Tyler!  This was the best archived version of httpsy spec I could find: https://web.archive.org/web/20081206135155/http://waterken.com/dev/YURL/httpsy/

-- 

Jasvir Nagra

--
You received this message because you are subscribed to the Google Groups "friam" group.
To unsubscribe from this group and stop receiving emails from it, send an email to friam+un...@googlegroups.com.

To view this discussion visit https://groups.google.com/d/msgid/friam/CAKvcKK%3DvgRndXORsxPaR4Bm7M%2B%3DAR%3DbhQ4GmJTAgCb7%3DO4WwhQ%40mail.gmail.com.

[William ML Leslie]

On Fri, 7 Aug 2026 at 10:17, Tyler Close <tyler...@gmail.com> wrote:

You've temporarily raised the dead. ;) Some answers inline below.

Thank you muchly.

 

The httpsy scheme did
not get much deployment due to the difficulty of adding new URL
schemes to browsers at the time.

No doubt.  As an engineering challenge alone, getting a new scheme supported across the browsers people use would be involved is one thing, getting the UA to keep a secret is a much bigger one.

 

Instead, we deployed within the
normal https scheme and tucked the needed information into there. The
httpsy scheme had the advantage that it included a list of ip
addresses for nameservers to contact to get the current location of
the server hosting the service identified by the public key hash in
the URL.

Both schemes included support for key rotation. The hash in the URL
was the hash of the certificate authority to trust to sign the
certificate deployed on the running service. This used the normal
X.509 certificate chains. The idea was to keep the keypair matching
the hash in the URL offline, and only use it to sign the certificate
deployed on the running server. The software that Alan used
implemented this feature, though we never did rotate keys.

Oh nice - so you can replace the certificate used for key exchange without invalidating existing capabilities.

--

William ML Leslie

Never interrupt the browser vendor when they are implementing httpsy.

[William ML Leslie]

On Fri, 7 Aug 2026 at 10:34, ๏̯͡๏ Jasvir Nagra <j...@nagras.com> wrote:

Welcome back to the world (even if it's briefly) Tyler!  This was the best archived version of httpsy spec I could find: https://web.archive.org/web/20081206135155/http://waterken.com/dev/YURL/httpsy/

Potential updates:

- a modern handshake rather than TLS upgrade,

- base64?

- Daira

Outside of the browser - if you were doing a server and a client specifically for your own use - it would be interesting to see how deep in the guts of OpenSSL you would end up in order to get the certificates verified.  Something to try in the quiet hours, I guess.

Maybe that is more complexity than Pierre is after rn.

--

William ML Leslie

ACK.

[Pierre Thierry]

Reading the Waterken YURL documents, I wonder how useful it would be to make it possible to include the Y property, even if only later…

One obvious solution would be to make the userinfo component of the URI use sub-schemes, so we could have a URI

• with just a bearer token: bearer-https:tok;FyHBk5nl53GZayms8SluFw@example.com/foo?bar#baz
• with a token and a root certificate public key: bearer-https:yurl;sha-256;x7KyHQqCiondlRxA74-1zg;FyHBk5nl53GZayms8SluFw@example.com/foo?bar#baz

From my own experience with TLS issues, the Y property is useful on so many levels (both to avoid spoofing and to simplify deployments), so reading again about it, I feel like making it possible would be great, but this smells of YAGNI…

Doubtfully,
Pierre Thierry

--

pie...@nothos.net
0xD9D50D8A