Capability URLs Best Practice

or: “You won’t believe what happened when this Capability URL was clicked!”

The TAG is seeking feedback on a document that describes common use, best practices for and risks associated with so-called capability URLs. The idea is to publish these as a TAG finding which would hopefully be useful to web application architects and designers seeking to incorporate this pattern into whatever they’re building.

A capability URL is a URL that combines location with access privileges. For example, in web applications this design pattern is often used for password resets, polls or sharing of otherwise private information without the need for additional credentials.

The document is not intended to discourage the use of this pattern. Rather, we’re trying to educate the community about some of the risks associated with capability URLs and encourage adoption of best practices.

Any feedback greatly appreciated.

Just a few thoughts:

I think the thing that is most wrong with this document is its name. Advice is only useful if it’s heeded, and in order to be heeded it first needs to be read. I’ve used these URLs many times, but I’ve never seen them called that. To be fair, I don’t recall seeing them called anything in particular, but “capability URL” certainly doesn’t ring true. If I didn’t know you folks, I’d never have read that. One-Shot URL? Secret URL?

In general I would say that while the content of the document is sensible, this same tendency to write it as if it were by experienced architects for experienced architects seems to pervade throughout. I would think that the primary audience would be the busy hacker who needs to be on top of security issues and good practices but doesn’t have time to understand why in the name of Eris does Second Life (“Wait, that’s still a thing?”) have some weird-arse capability-based API.

This is visible in “4.4 Web Architecture” too. Be careful! “Good practice: Avoiding URI aliases”! But the section concludes saying that in this case it’s actually okay. Maybe that’s a reason to update the discussion in AWWW, but it need not be mentioned here. I don’t think that the group of people this should be written for knows that the AWWW exists.

Likewise, the replaceState() discussion sounds like the hack from hell, and it’s not clear why it’s there.

As a result of being too architectural, I think this document mixes up what are in fact two distinct practices. One is secret URLs (like secret gists) and the other is one-shot URLs (email confirmation, password reset, etc.). Sure enough they look the same, but their uses are IMHO different enough that they warrant being treated separately.

With secret URLs you need to:

• Warn your users about the level of security they are really getting
• Preferably provide a list of “last accesses” so that compromises can be detected
• Make them easy to revoke
• 301 to the public/canonical URL if they stop being secret

With one-shot URLs you need to:

• Revoke them immediately (and expire within days)
• Always 301 to make sure they can never be bookmarked or whatnot

On a final note, I’ve always wondered why no one ever used HTTP URLs’ ability to embed credentials. Those don’t leak through Referer. Unless I’ve missed something, it might be a nice trick.

I love this idea, but I feel like this kind of document is more the kind of thing that https://www.webplatform.org was founded to collect, right? If it’s aimed at site / app developers and doesn’t require any changes to browsers, then it’s out-of-scope for the W3C, I feel.

EDIT: Oh, that’s what the TAG is. I’d never heard of them until right now. Is there a Community Group version of the TAG (something like the WICG)? Can there be? (Again - can this be something that gathers on webplatform.org? Say, we start a new Discourse over there?)