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.
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.