Status List Helper

Small Python utility for inspecting an IETF OAuth Token Status List endpoint.

The script fetches an application/statuslist+jwt response, decodes the JWT payload, decompresses the status_list.lst bytes, and prints the actual status values as compact index ranges.

What It Does

• Fetches a JWT from a configured status list endpoint
• Reads the status_list.bits and status_list.lst claims
• Supports lst values encoded as either hex text or base64url text
• Decompresses the packed status bytes
• Reads statuses using the spec's LSB-first bit packing
• Prints contiguous ranges in a readable table

Example output:

Fetching status list from http://status-list:9288/lists/1 ...

  bits_per_status : 2
  compressed size : 271 bytes
  decompressed    : 250000 bytes
  total entries   : 1000000

Status ranges
=======================
Index range   | Status
--------------+--------
0-477369      | VALID
477370        | INVALID
477371-999999 | VALID

Requirements

• Python 3.9+
• Dependencies listed in requirements.txt

Install the dependency with:

pip install -r requirements.txt

Usage

1. Run the script with an explicit endpoint URL:

python3 sl_test.py http://your-endpoint/lists/1

2. If no URL is provided, the script falls back to ENDPOINT_URL in sl_test.py.

python3 sl_test.py

Status Encoding Notes

The script follows the token status list draft's packed bit layout:

• bits must be 1, 2, 4, or 8
• status values are packed LSB-first within each byte
• index lookup uses:

$$ \mathrm{byte\ index} = i \div (8 / \mathrm{bits}) $$

$$ \mathrm{bit\ offset} = (i \bmod (8 / \mathrm{bits})) \times \mathrm{bits} $$

For currently supported labels:

• 1 bit: 0 = VALID, 1 = INVALID
• 2 bits: 0 = VALID, 1 = INVALID, 2 = SUSPENDED, 3 = APPLICATION_SPECIFIC

Notes About This Endpoint

During verification for this repo, the live endpoint returned status_list.lst as a hex string containing zlib-compressed bytes. The script handles that form as well as base64url input before decompression.

Files

• sl_test.py: main inspection script
• .github/copilot-instructions.md: repository-specific guidance for Copilot