feature - add bit encoding

[jdgamble555]

Clerk uses bit encoding to make claims smaller with permissions in it:

https://clerk.com/docs/guides/sessions/session-tokens#decode-o-fpm-manually

example:

{
  "azp": "https://clerk.com",
  "discord": null,
  "dubClickId": null,
  "exp": 1780798435,
  "fea": "o:applications,o:billing,o:config,o:email_logs,o:global,o:instances,o:restrictions,o:secrets,o:users",
  "fva": [
    5884,
    -1
  ],
  "o": {
    "fpm": "27,24,24,16,24,11,24,8,4",
    "id": "org_3EbR0uDkUyjgZXgCv9tAd68CIa0",
    "per": "create,delete,imp,manage,read",
    "rol": "owner",
    "slg": "personal-workspace-92653544047a"
  },

  "v": 2
}

J

[point-source]

These is pretty clever, but I'm unclear what problem it is solving. Sure, smaller is a space savings and perhaps performance improvement in some areas but I'm wondering if that has actually been a blocker for anyone. Human-readable is also valuable. I am not opposed to something like this, I just want to better understand what the use-case is / who it's for / why it's helpful.

[jdgamble555]

The size matters for headers and cookie limits:

For a typical web app:

Cookie-based JWT: keep the entire JWT below roughly 4 KB. Browsers commonly limit each cookie to 4,096 bytes,
including cookie metadata. Supabase explicitly warns about this limit.
Authorization header: servers and proxies commonly limit total HTTP headers to around 8–16 KB, but this varies by
infrastructure. Recommended target: keep the encoded JWT under 3 KB, especially with Supabase SSR/cookie authentication.

J

[point-source]

Thanks for the explanation. This package doesn't prescribe specific strings though. Is there something preventing you from using shorter / encoded string as-is via helper functions that wrap package functions with a decode/encode layer? (Just doing more discovery)

[jdgamble555]

No, but eventually, some apps will face a limit that could be increased... just thought it was a good idea.

J

[point-source]

Agreed. Thanks for the suggestion! Will consider for the next feature cycle. Let me know if it becomes blocking for you