Add a verifier for token status list, as well as issuer and verifier for bitstring status list.

[Athan13]

Create a verifier for token status list, both JWT and CWT formats. Implement the bitstring status list spec, creating both an issuer and verifier equivalent to those in token status list.

[dbluhm]

This is great! I have a few recommendations that I think will help polish the implementation and more clearly define the expected usage of our classes here. Nice work and thanks for reviewing the feedback below!

[dbluhm]

I have a number of recommendations for this method:

• I think retrieve_list would be a better name; establish_connection could be interpreted a number of ways and implies just initial connection and not necessarily a transfer of data.
• I think we should use either aiohttp or httpx.AsyncClient for this instead of requests. That would mean the method will have to be declared async.
• I propose we make this method a @classmethod that returns a new instance of the verifier. In that model, the headers, protected_headers, payload, and _bit_array attributes would be immutable which I think would help prevent a category of bugs that could arise from having attributes designed to be reset by certain events. It also makes it so the types of these attributes are cleaner; instead of, for example, encoding being Literal["CWT", "JWT"] | None = None, it could just be Literal["CWT", "JWT"]. This makes it easier to work with these attributes since we don't have to worry about the None case. It also makes it easier to constrain the usage in appropriate ways; for example, just by looking at the init method of this class, it's unclear whether the user should provide none or all of the attributes passed in -- or something in between.
• I propose we add another classmethod for creating a verifier from a jwt/cwt that the caller might have obtained through some other means. The retrieve_list class method would reuse this classmethod.
• assert statements should be reserved for catch errors rising from us, the programmers, violating our own assumptions we've encoded into our program. We should raise a "normal" exception in the event that we get a status code outside of the expected range.

Here is an example of what this might look like:

    def __init__(
        self,
        encoding: Literal["JWT", "CWT"],
        protected_headers: dict,
        unprotected_headers: dict,
        payload: dict,
        bit_array: BitArray,
    ):
        self.encoding = encoding
        self.headers = protected_headers
        self.protected_headers = protected_headers
        self.unprotected_headers = unprotected_headers

        self.payload = payload

        self._bit_array = bit_array

    @classmethod
    async def retrieve_list(
        cls, 
        status_list_uri: str,
        encoding: Literal["JWT", "CWT"] = "JWT",
        headers: dict | None = None,
    ) -> "TokenStatusListVerifier":
        """ Establish connection. Returns base64 encoded response. """
        headers = headers or {}
        headers.update({"Accept": f"application/statuslist+{encoding.lower()}"})

        async with ClientSession() as session:
            async with session.get(status_list_uri, headers=headers) as resp:
                # Quick method to raise exception on status outside of 200 range
                # TODO: consider using a more semantically rich exception
                resp.raise_for_status()
                token = await resp.read()

        if encoding == "JWT":
            return cls.from_jwt(token)
        if encoding == "CWT":
            return cls.from_cwt(token)
        
    @classmethod
    def from_jwt(cls, token: str | bytes) -> "TokenStatusListVerifier":
        if isinstance(token, str):
            token = token.encode()

        if not token.startswith(b"ey"):
            raise ValueError("JWT requested but token is not a JWT")

        # INSERT DATA EXTRACTION HERE
        protected = None
        unprotected = None
        payload = None
        bit_array = None
        return cls("JWT", protected, unprotected, payload, bit_array)

    @classmethod
    def from_cwt(cls, token: bytes) -> "TokenStatusListVerifier":
        # TODO: Is there a consistent byte at the beginning of statuslist+cwt?
        if token.startswith(b"ey"):
            raise ValueError("CWT request but got JWT")

        # INSERT DATA EXTRACTION HERE
        protected = None
        unprotected = None
        payload = None
        bit_array = None
        return cls("CWT", protected, unprotected, payload, bit_array)

[dbluhm]

There should be a single verify method that detects the encoding of the current status list and then calls an encoding specific verify; e.g.:

def verify(self, verifier: TokenVerifier):
    assert self.encoding in ("JWT", "CWT"), f"Invalid value for encoding: {self.encoding}"
    if self.encoding == "JWT":
        return self.jwt_verify(verifier)
    if self.encoding == "CWT":
        return self.cwt_verify(verifier)

[dbluhm]

To encode the expected usage of our verifier class, I wonder if we should have a StatusReporter that gets returned by the verify function. The StatusReporter would be the one with this method. So the expected usage (combined with my previous comments) might look something like this:

verifier = await TokenStatusListVerifier.retrieve_list("JWT", "https://status.example.com/0")
reporter = verifier.verify(token_verifier)
reporter.get_status(0)

The first line is responsible for retrieval and basic parsing of the token. The second is responsible for evaluating the cryptographic integrity and origin of the token. The third uses the returned status reporter and is basically just a simple wrapper around BitArray.

This forces the user to correctly use our classes; this should make it harder for them to use a value that is private to the class in a way that compromises the integrity of the status list (i.e. by somehow skipping signature verification or altering a critical value after signature verification and polluting the results).

[dbluhm]

This (and other imports) should look like from token_status_list.bit_array import .... The package is token_status_list; pdm will install the package into the local scope when you run pdm install. If you have any issues with this, let me know.

Also, it is generally discouraged to do from x import *; imports should be precise, importing only what is actually used in the code of the current module.

[dbluhm]

See my comments above about the TokenStatusListVerifier; many of the same recommendations apply here.