Skip to content

CONCEPT Cited by 1 source

Attenuation (offline)

Attenuation is the operation of narrowing a Macaroon's privileges by appending additional caveats — restrictions — to the token. Offline attenuation means this is done without contacting the token authority, in user space, using only local state + the existing token's bytes.

The cryptographic enabler is the chained-HMAC construction: the next HMAC step uses the current tag as its key, so the bearer can extend the chain without knowing the root key.

Fly.io's framing

Two one-liners from the 2025-03-27 post:

"You can minimize your token before every API operation so that you're only ever transmitting the least amount of privilege needed for what you're actually doing, even if the token you were issued was an admin token." (Source: sources/2025-03-27-flyio-operationalizing-macaroons.)

"The most complicated possible Macaroon still chains up to a single root key … and everything that complicates that Macaroon happens 'offline'. We take advantage of 'attenuation' far more than our users do." (Source: sources/2025-03-27-flyio-operationalizing-macaroons.)

Two load-bearing consequences at Fly.io

  1. Database stays small. "There's actually not much for us to store!" — tkdb holds root keys and revocations only; every added caveat happens off-box. DB size is "a couple dozen megs" at Internet-largest-user scale.
  2. Attenuate-on-use is cheap. Adding a caveat is one HMAC with no network round-trip; every API call can transmit a just-barely-sufficient scope of the caller's token. See patterns/attenuate-on-use.

Typical caveat classes

From Fly.io's usage described across the 2025-03-27 post and the earlier Macaroons Escalated Quickly post:

  • Time-bound: valid until T.
  • Scope-bound: valid for org X / app Y / specific resource ID.
  • Host-bound: valid only when running on a specific flyd instance or Fly Machine (this is what Fly uses to make exfiltrated service tokens useless — patterns/third-party-caveat-strip-for-service-token).
  • Third-party: dischargeable only by proving something to another authority (this is how authentication is bolted onto an authorization token).

Contrast with online restriction

Compare to issuer-side restriction (issue a new token with narrower scope): requires round-trip to issuer, new record on issuer's side, coordination for revocation. Offline attenuation avoids all of that — the same lineage covers a broad token and all its narrowed descendants, and revoking the root nonce kills every descendant in one stroke.

Seen in

Last updated · 200 distilled / 1,178 read