aar

Room for All Your Overdue Potential 📚

1. The Beginning

In 2025, I was on a mission to add as many library cards as possible to Libby to accelerate my audiobook addiction. When I added my 39th library card, Libby started failing my requests. After a tortuous few days/weeks of debugging, I determined that the JWT token which Libby uses to store data was now too big for their nginx server to handle. 💥

I wrote some tools. I determined that the few thousand tags I had been painstakingly applying to books was lost, at least to me – I was unable to re-authenticate with Libby using my now compromised JWT. I could never get the full list. I mourned my loss, wrote a blog post in November, reset my account, re-added some (not all) library cards, decided to stop using tags if they were going to be a fragile mechanism and moved on with my life.

At some point this year, Libby either increased the header limitations of their nginx deployment AND/OR updated their JWT format. Probably both! Suddenly, I was able to re-authenticate with the broken JWT and export all my tags! I finished the tools I had started, used them to export and then re-import those tags into the account I was currently using and considered myself lucky!

Then I saw the post about the partner libraries… If Libby was adding partner libraries for everyone…

OH NO!

So back in I went. Will the addition of potentially dozens of partner libraries I had been avoiding once again throw me over the limit?!? Enquiring minds (me) wanted to know!

TL;DR: NOTHING TO WORRY ABOUT.

Libby changed the shape of the data they store in their JWT!

2. Prior JWT — the original issue…

The original JWT embedded every linked card in a verbose chip.accounts[] structure. Each card was represented as a named account object, approximately like this:

{
  "ag": 123,
  "id": "account-id",
  "typ": "library",
  "cards": [
    {
      "id": "card-id",
      "name": "My card name",
      "lib": {
        "id": "website-id",
        "key": "library-slug"
      }
    }
  ]
}

• The JWT travelled in every Authorization: Bearer … request.
• Each added card enlarged the token.
• The structure repeated JSON field names and included the human-readable card name (this is where many bytes were wasted).
• Base64url encoding expands the JSON payload by about one-third before it becomes part of the JWT.
• With an 8 KiB nginx header boundary, a large enough token would be rejected before Libby could process it.
• That was the failure mode I encountered: adding cards could eventually make the authentication header too large.
• Eventually, I realized you could rename the cards to be single letters to reduce the size of the token, shrinking back under the size limit.

3. What the new JWT contains

The refreshed identity JWT still includes a grant for every linked card, but uses chip.cards[]: a compact positional tuple.

[
  "account-id",
  "card-id",
  "ils-id",
  false,
  "website-id",
  "library-slug"
]

• Tuple positions:
  • 0: Account ID
  • 1: Card ID
  • 2: ILS ID
  • 3: Visiting-card flag
  • 4: Library website ID
  • 5: Library/Advantage key
• Keeps the card-grant information required by the service.
• Removes repeated JSON property names and per-card wrapper objects.
• The card name is no longer present and therefore does not consume JWT space (making my original single-character-card-name-fix moot).

4. Measurements from my tokens

I measured 89 real compact card grants across two refreshed Libby identities (46 cards and 43 cards).

• New compact JWT card size, measured from 89 cards:
  • Minimum: 54 raw JSON bytes; 72 JWT on-wire bytes per card
  • Median: 63 raw JSON bytes; 84 JWT on-wire bytes per card
  • Mean/average: 63.7 raw JSON bytes; 85 JWT on-wire bytes per card
  • Maximum: 83 raw JSON bytes; 111 JWT on-wire bytes per card

The JWT has a fixed non-card envelope of about 610 bytes: its signed header, signature, and claims such as issuer, expiry, and chip identifiers. A useful approximation is:

JWT size ≈ 610 bytes + (number of cards × bytes per card)

For comparison, the observed legacy card representation was:

• Legacy versus New:
  • Original chip.accounts[]: 118–139 raw JSON bytes; 157–185 JWT on-wire bytes per card
  • New chip.cards[]: 54–83 raw JSON bytes; 72–111 JWT on-wire bytes per card

5. Capacity: legacy format and legacy limit vs. new format and current limit

The legacy-format “typical” figure uses its observed approximate cost of 167 bytes/card. The new figures use the measured distribution above.

• Approximate card capacity:
  • Old format, 8 KiB limit:
    • Best case, 157 bytes/card: 48 cards
    • Typical, ~167 bytes/card: 45 cards
    • Worst case, 185 bytes/card: 40 cards
  • New format, ~32 KiB limit:
    • Best case, 72 bytes/card: 446 cards
    • Median, 84 bytes/card: 382 cards
    • Mean/average, 85 bytes/card: 378 cards
    • Worst case, 111 bytes/card: 289 cards

A typical account has roughly eight times the theoretical card headroom: about 45 cards in the former 8 KiB/legacy-format world, versus about 382 cards using the current compact JWT under the current Libby-core header limit.

6. The limit test

The relevant request carries its JWT like this:

curl -sS -D- "https://sentry.libbyapp.com/chip/sync" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <YOUR_JWT>"

A malformed-but-small bearer reaches the application and is rejected as unauthenticated:

curl -sS -D- "https://sentry.libbyapp.com/chip/sync" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer not-a-valid-jwt"

# HTTP/1.1 403 Forbidden
# {"result":"missing_chip"}

The request-header boundary was tested by increasing an invalid bearer value. The behavior changes sharply:

Authorization line length: 32,766 bytes → 403 Authorization line length: 32,767 bytes → 400

The difference matters:

• 403 means the request reached Libby’s application layer, which rejected the invalid bearer.
• 400 means nginx rejected the header first because it was too large (And was the original clue I witnessed all those months ago).
• A real oversized JWT would hit that proxy rejection before its signature or card grants could be evaluated.

7. What this means for people adding cards

• My original advice to avoid long card names is no longer relevant to the compact JWT format: card display names are not embedded in its card tuple.
• Adding a card still increases the JWT size, because each linked card still needs a grant.
• The practical ceiling is now far higher for Libby’s core services—hundreds of normally sized cards rather than dozens.
• The precise count varies with card and library identifier lengths.
• Refreshing the identity is the migration path: it reissues the token in chip.cards[] form.
• This improves the risk substantially, but it is not the same as an unlimited-card guarantee.
• Export tags periodically anyway. Better token headroom is not a substitute for a backup.

8. Closing

My original failure was real, but the conditions behind it have materially improved. Libby still carries linked-card grants inside its identity token; the change is that those grants are now encoded more efficiently, and Libby accepts a substantially larger authorization header. For ordinary multi-library users, the practical danger zone has moved from “a few dozen cards may be risky” to “hundreds of normally sized cards.”