[Feature Request] Introduce a Typesafe API

[winstxnhdw]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the Missil documentation, with the integrated search.
• I already searched in Google "How to X in Missil" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to Missil but to FastAPI.
• I already checked if it is not related to Missil but to Python-Jose.

Commit to Help

• I commit to help with one of those options 👆

Example Code

import missil

from fastapi import FastAPI
from fastapi import Response

from datetime import datetime
from datetime import timezone
from datetime import timedelta

app = FastAPI()

TOKEN_KEY = "Authorization"
SECRET_KEY = "2ef9451be5d149ceaf5be306b5aa03b41a0331218926e12329c5eeba60ed5cf0"

bearer = missil.FlexibleTokenBearer(TOKEN_KEY, SECRET_KEY)
rules = missil.make_rules(bearer, "finances", "it", "other")

@app.get("/", dependencies=[rules[{"finances", missil.READ}])
def read_root():
    return {"Hello": "World"}


@app.get("/set-cookies")
def set_cookies(response: Response) -> None:
    """Just for example purposes."""
    sample_user_privileges = {
        "finances": missil.READ,
        "it": missil.WRITE,
    }

    token_expiration = datetime.now(timezone.utc) + timedelta(hours=8)
    token = missil.encode_jwt_token(sample_user_privileges, SECRET_KEY, token_expiration)

    response.set_cookie(
        key=TOKEN_KEY,
        value=f"Bearer {token}",
        httponly=True,
        max_age=1800,
        expires=1800,
    )

Description

As mentioned on LinkedIn, it would be great if we can make the API completely typesafe. This can probably be done if we let make_rules accept a Mapping or TypedDict generic. I am writing this through my phone so this might not be entirely correct.

class PrivilegeEnum(enum.Enum):  # your enum implementation
   READ
   WRITE
   ...

T = TypeVar("T", bound=Mapping[str, PrivilegeEnum])  # I think this should be a tuple of PrivilegeEnum instead for multi-privilege setups?

class SomeProtocolWrapper(Protocol[T]):
    # I am not sure what object make_rule is returning, but from the API, it looks like you are using dunder `call`
    def __call__(self, rule: T): 
         ...

def make_rules(token: FlexibleTokenBearer, scopes: T) -> SomeProtocolWrapper[T]:
    ...

make_rules(bearer, {
    "finance": missil.READ,
    "it": missil.WRITE,
    "other": missil.READ
})

Operating System

Linux

Operating System Details

No response

Missil Version

0.1.4b

Python Version

3.12

Additional Context

No response