Suggested clarification on "Biscuit is a bearer token"

[sourcefrog]

https://www.biscuitsec.org/docs/getting-started/introduction/ says "Biscuit is a bearer token" which might be taken to mean it has some of the shortcomings of bearer tokens: in particular that anyone that sees the token can reuse it.

It seems like that weakness can be quite significantly mitigated by attenuating the token so that it's valid for only a single request to whichever API, as you discuss in Per request attenuation.

The concrete suggestion is basically to mention this in the introduction.

Two additional thoughts for what it's worth:

1. Maybe the docs could compare it to AWS Sigv4:

• Sigv4 seems to need a shared secret, whereas Biscuit works on an asymmetric key
• Sigv4 signs the whole HTTP request whereas Biscuit defaults open and can be (and must be) constrained by the user?
• Sigv4 embeds some AWS-specific concepts so can't directly be used as-is
• Sigv4 has no concept of offline attenuation

2. I wonder if there is or could be a pattern documented about how to make sure all request fields and the content actually are included as facts?

[tarcieri]

Macaroons provide ample precedent for taming unrestricted bearer credentials, both via attenuation (ideally to least authority as proposed above), but also through contextual caveats.

It might be interesting to standardize one or more contextual caveats for Biscuits. It could potentially leverage the RFC8471 token binding protocol, or something a bit more minimalist (IIRC Chrome dropped support for token binding due to complexity, but Microsoft still uses it apparently)

[divarvel]

One cool application of third-party blocks will be to require an extra signature for the token to be valid. This way, the token itself is valid, and has to be signed (by adding a third-party block) just before it's sent on the wire.

Agreed on standardizing caveats (we would rather standardize ambient facts, i think), in addition to time(…) which is somehow standardized by being supported in the CLI. The current default symbol table reflects that goal, by carrying several names that are intended to be used this way (things ilke client_ip for instance)