apppy-auth 0.1.0__tar.gz

apppy_auth-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+__generated__/
+dist/
+*.egg-info
+.env
+.env.*
+*.env
+!.env.ci
+.file_store/
+*.pid
+.python-version
+*.secrets
+.secrets
+*.tar.gz
+*.test_output/
+.test_output/
+uv.lock
+*.whl
+
+# System files
+__pycache__
+.DS_Store
+
+# Editor files
+*.sublime-project
+*.sublime-workspace
+.vscode/*
+!.vscode/settings.json
+

apppy_auth-0.1.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: apppy-auth
+Version: 0.1.0
+Summary: Authentication definitions for server development
+Project-URL: Homepage, https://github.com/spals/apppy
+Author: Tim Kral
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: apppy-env>=0.1.0
+Requires-Dist: apppy-fastql>=0.1.0
+Requires-Dist: apppy-fs>=0.1.0
+Requires-Dist: apppy-logger>=0.1.0
+Requires-Dist: argon2-cffi==25.1.0
+Requires-Dist: authlib==1.6.0
+Requires-Dist: fastapi-another-jwt-auth==0.1.11
+Requires-Dist: fastapi-lifespan-manager==0.1.4
+Requires-Dist: fastapi==0.115.14
+Requires-Dist: itsdangerous==2.2.0
+Requires-Dist: jwcrypto==1.5.6
+Requires-Dist: pyjwt==2.10.1
+Requires-Dist: python-dateutil==2.9.0

apppy_auth-0.1.0/auth.mk

@@ -0,0 +1,23 @@
+ifndef APPPY_AUTH_MK_INCLUDED
+APPPY_AUTH_MK_INCLUDED := 1
+AUTH_PKG_DIR := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
+
+.PHONY: auth auth-dev auth/build auth/clean auth/install auth/install-dev
+
+auth: auth/clean auth/install
+
+auth-dev: auth/clean auth/install-dev
+
+auth/build:
+	cd $(AUTH_PKG_DIR) && uvx --from build pyproject-build
+
+auth/clean:
+	cd $(AUTH_PKG_DIR) && rm -rf dist/ *.egg-info .venv
+
+auth/install: auth/build
+	cd $(AUTH_PKG_DIR) && uv pip install dist/*.whl
+
+auth/install-dev:
+	cd $(AUTH_PKG_DIR) && uv pip install -e .
+
+endif # APPPY_AUTH_MK_INCLUDED

apppy_auth-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "apppy-auth"
+version = "0.1.0"
+description = "Authentication definitions for server development"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [{ name = "Tim Kral" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+]
+dependencies = [
+    "apppy-env>=0.1.0",
+    "apppy-fastql>=0.1.0",
+    "apppy-fs>=0.1.0",
+    "apppy-logger>=0.1.0",
+    "argon2-cffi==25.1.0",
+    "authlib==1.6.0",
+    "fastapi==0.115.14",
+    "fastapi-lifespan-manager==0.1.4",
+    "fastapi-another-jwt-auth==0.1.11",
+    "itsdangerous==2.2.0",
+    "jwcrypto==1.5.6",
+    "PyJWT==2.10.1",
+    "python-dateutil==2.9.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/spals/apppy"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/apppy"]

apppy_auth-0.1.0/src/apppy/auth/__init__.py

@@ -0,0 +1,19 @@
+from fastapi import Request
+from fastapi_another_jwt_auth import AuthJWT as JWT
+
+
+def convert_token_to_jwt(token: str) -> JWT:
+    # The JWT infrastructure only deals with http requests
+    # and responses so we'll emulate an http request in
+    # order to run the JWT parsing
+    scope = {
+        "type": "http",
+        "headers": [(b"authorization", f"Bearer {token}".encode("latin-1"))],
+    }
+    req = Request(scope=scope)
+    return extract_jwt_from_request(req)
+
+
+def extract_jwt_from_request(request: Request) -> JWT:
+    jwt = JWT(req=request, res=None)  # type: ignore[invalid-argument-type]
+    return jwt

apppy_auth-0.1.0/src/apppy/auth/errors/jwks.py

@@ -0,0 +1,10 @@
+from apppy.fastql.annotation import fastql_type_error
+from apppy.fastql.errors import GraphQLServerError
+
+
+@fastql_type_error
+class IllegalJwksPemFileError(GraphQLServerError):
+    """Error raised when a JWKS PEM file is not well-formed"""
+
+    def __init__(self, code: str) -> None:
+        super().__init__(code)

apppy_auth-0.1.0/src/apppy/auth/errors/oauth.py

@@ -0,0 +1,24 @@
+from apppy.fastql.annotation import fastql_type_error
+from apppy.fastql.errors import GraphQLClientError
+
+
+@fastql_type_error
+class IllegalNativeOAuthProviderError(GraphQLClientError):
+    """Error raised when a non-native OAuth provider is treated as a native one"""
+
+    provider: str
+
+    def __init__(self, provider: str) -> None:
+        super().__init__("illegal_native_oauth_provider")
+        self.provider = provider
+
+
+@fastql_type_error
+class UnknownOAuthProviderError(GraphQLClientError):
+    """Error raised when a client has provided an unknown OAuth client name"""
+
+    provider: str
+
+    def __init__(self, provider: str) -> None:
+        super().__init__("unknown_oauth_provider")
+        self.provider = provider

apppy_auth-0.1.0/src/apppy/auth/errors/service.py

@@ -0,0 +1,34 @@
+from apppy.fastql.annotation import fastql_type_error
+from apppy.fastql.errors import GraphQLClientError, GraphQLServerError
+
+
+@fastql_type_error
+class ServiceAuthenticaionDisabledError(GraphQLServerError):
+    """Error raised when a service trying to authenticate but service authentication is disabled"""
+
+    def __init__(self) -> None:
+        super().__init__("service_authenticaion_disabled")
+
+
+@fastql_type_error
+class ServiceKeyAlgorithmMissingError(GraphQLClientError):
+    """Error raised when a service trying to authenticate does not include an algorithm header"""
+
+    def __init__(self) -> None:
+        super().__init__("service_key_algorithm_missing")
+
+
+@fastql_type_error
+class ServiceKeyMissingError(GraphQLServerError):
+    """Error raised when a service trying to authenticate does not have a registered public key"""
+
+    def __init__(self) -> None:
+        super().__init__("service_key_missing")
+
+
+@fastql_type_error
+class ServiceUnknownError(GraphQLClientError):
+    """Error raised when a service trying to authenticate cannot be found"""
+
+    def __init__(self) -> None:
+        super().__init__("service_unknown")

apppy_auth-0.1.0/src/apppy/auth/errors/user.py

@@ -0,0 +1,69 @@
+from apppy.fastql.annotation import fastql_type_error
+from apppy.fastql.errors import GraphQLClientError, GraphQLServerError
+
+
+@fastql_type_error
+class UserSessionRefreshMissingSessionError(GraphQLClientError):
+    """Error raised when a user session refresh is attempted against a missing session"""
+
+    def __init__(self) -> None:
+        super().__init__("user_session_refresh_missing_session")
+
+
+@fastql_type_error
+class UserSignInInvalidCredentialsError(GraphQLClientError):
+    """Error raised when a user has provided invalid credentials for sign in"""
+
+    def __init__(self) -> None:
+        super().__init__("user_sign_in_invalid_credentials")
+
+
+@fastql_type_error
+class UserSignInServerError(GraphQLServerError):
+    """Error raised when there's a user sign in error on the server side"""
+
+    def __init__(self, code: str) -> None:
+        super().__init__(code)
+
+
+@fastql_type_error
+class UserSignOutInvalidScopeError(GraphQLClientError):
+    """Error raised when a user has provided an invalid scope for sign out"""
+
+    scope: str
+
+    def __init__(self, scope: str) -> None:
+        super().__init__("user_sign_out_invalid_scope")
+        self.scope = scope
+
+
+@fastql_type_error
+class UserSignOutServerError(GraphQLServerError):
+    """Error raised when there's a user sign out error on the server side"""
+
+    def __init__(self, code: str) -> None:
+        super().__init__(code)
+
+
+@fastql_type_error
+class UserSignUpInvalidCredentialsError(GraphQLClientError):
+    """Error raised when a user has provided invalid credentials for sign up"""
+
+    def __init__(self) -> None:
+        super().__init__("user_sign_up_invalid_credentials")
+
+
+@fastql_type_error
+class UserSignUpTooManyRetriesError(GraphQLServerError):
+    """Error raised when there have been too many user sign up attempts"""
+
+    def __init__(self) -> None:
+        super().__init__("user_sign_up_too_many_retries")
+
+
+@fastql_type_error
+class UserSignUpServerError(GraphQLServerError):
+    """Error raised when there's a user sign up error on the server side"""
+
+    def __init__(self, code: str) -> None:
+        super().__init__(code)

apppy_auth-0.1.0/src/apppy/auth/jwks.py

@@ -0,0 +1,255 @@
+import datetime
+import re
+from dataclasses import dataclass
+
+from fastapi_lifespan_manager import LifespanManager
+from jwcrypto.jwk import JWK
+from pydantic import Field
+
+from apppy.auth.errors.jwks import IllegalJwksPemFileError
+from apppy.auth.errors.service import (
+    ServiceAuthenticaionDisabledError,
+    ServiceKeyMissingError,
+    ServiceUnknownError,
+)
+from apppy.env import EnvSettings
+from apppy.fs import FileSystem, FileUrl
+from apppy.logger import WithLogger
+
+
+@dataclass
+class JwkPemFile:
+    file_url: FileUrl
+
+    is_public: bool
+    service_name: str
+    version: int
+    generated_at: datetime.datetime
+
+    @property
+    def file_ext(self) -> str:
+        return "pub.pem" if self.is_public else "key.pem"
+
+    @property
+    def kid(self) -> str:
+        return f"{self.service_name}.v{self.version}"
+
+    @staticmethod
+    def file_name_private(service_name: str, version: int, generated_at: datetime.datetime) -> str:
+        generated_ts = generated_at.strftime("%Y%m%d%H%M%S")
+        return f"{service_name}.v{version}.{generated_ts}.key.pem"
+
+    @staticmethod
+    def file_name_public(service_name: str, version: int, generated_at: datetime.datetime) -> str:
+        generated_ts = generated_at.strftime("%Y%m%d%H%M%S")
+        return f"{service_name}.v{version}.{generated_ts}.pub.pem"
+
+    @staticmethod
+    def from_file_url(file_url: FileUrl) -> "JwkPemFile":
+        if file_url.file_name is None:
+            raise IllegalJwksPemFileError("unavailable_pem_file_name")
+
+        service_name, version, generated_at = JwkPemFile._parse_file_name(file_url.file_name)
+        return JwkPemFile(
+            file_url=file_url,
+            is_public=file_url.file_name.endswith("pub.pem"),
+            service_name=service_name,
+            version=version,
+            generated_at=generated_at,
+        )
+
+    @staticmethod
+    def _parse_file_name(file_name: str) -> tuple[str, int, datetime.datetime]:
+        if not file_name.endswith(".pub.pem") and not file_name.endswith(".key.pem"):
+            raise IllegalJwksPemFileError("unknown_pem_file_extension")
+
+        pattern = (
+            r"^(?P<service>[a-zA-Z0-9_-]+)\.v(?P<version>\d+)\.(?P<ts>\d{14})\.(pub|key)\.pem$"
+        )
+        m = re.match(pattern, file_name)
+        if not m:
+            raise ValueError(f"Invalid filename format: {file_name}")
+
+        service_name = m.group("service")
+        version = int(m.group("version"))
+        ts_str = m.group("ts")
+        generated_at = datetime.datetime.strptime(ts_str, "%Y%m%d%H%M%S")
+
+        return (service_name, version, generated_at)
+
+
+@dataclass
+class JwkInfo:
+    key: dict
+    jwk: JWK
+    pem: JwkPemFile
+
+
+class JwksAuthStorageSettings(EnvSettings):
+    # NOTE: Some of these configuration values are general to all authentication
+    # so those use the APP_AUTH prefix. Configuration values specific to jwks use
+    # the APP_JWKS_AUTH prefix.
+
+    # Control whether JWKS authenication is available.
+    # If not available (the default), JwksAuth will not attempt to read
+    # any files from the FileSystem.
+    # Note that this is useful for integration tests. Some integration tests
+    # run with an encrypted FileSystem and some without. So they cannot share
+    # pem files.
+    jwks_auth_enabled: bool = Field(alias="APP_AUTH_SERVICES_ENABLED", default=False)
+    jwks_auth_fs_partition: str = Field(alias="APP_AUTH_FS_PARTITION", default="auth")
+
+    jwks_auth_root_dir: str = Field(alias="APP_JWKS_AUTH_ROOT_DIR", default=".jwks")
+
+
+class JwksAuthStorage(WithLogger):
+    def __init__(
+        self, settings: JwksAuthStorageSettings, lifespan: LifespanManager, fs: FileSystem
+    ):
+        self._settings = settings
+        self._fs = fs
+
+        self._jwks_root_file_url: FileUrl = self._fs.new_file_url_internal(
+            protocol=self._fs.settings.default_protocol,
+            partition=settings.jwks_auth_fs_partition,
+            directory=settings.jwks_auth_root_dir,
+            file_name=None,
+        )
+        self._jwks_full_cache: dict[str, list[JwkInfo]] = {}
+        self._jwks_version_cache: dict[str, int] = {}
+
+        self._keys: list[dict] = []
+        self._keys_dict = {"keys": self._keys}
+        if self._settings.jwks_auth_enabled is True:
+            lifespan.add(self.rebuild_caches)
+
+    def _clear_cache(self):
+        self._jwks_full_cache.clear()
+        self._jwks_version_cache.clear()
+        self._keys.clear()
+
+    def add_jwk(self, pem_file_url: FileUrl) -> JwkInfo:
+        if not self._fs.exists(self._jwks_root_file_url):
+            self._fs.makedir(self._jwks_root_file_url, create_parents=True)
+
+        pem_file: JwkPemFile = JwkPemFile.from_file_url(pem_file_url)
+        pem_file_bytes: bytes = self._fs.read_bytes(pem_file_url)
+        jwk_: JWK = JWK.from_pem(pem_file_bytes)
+        key = jwk_.export_public(as_dict=True)
+        key["use"] = "sig"
+        key["alg"] = "EdDSA"
+        key["kid"] = pem_file.kid
+
+        if pem_file.service_name not in self._jwks_full_cache:
+            self._jwks_full_cache[pem_file.service_name] = []
+
+        jwk_info = JwkInfo(key=key, jwk=jwk_, pem=pem_file)
+        self._jwks_full_cache[pem_file.service_name].append(jwk_info)
+
+        if (
+            pem_file.service_name not in self._jwks_version_cache
+            or self._jwks_version_cache[pem_file.service_name] < pem_file.version
+        ):
+            self._jwks_version_cache[pem_file.service_name] = pem_file.version
+
+        self._keys.append(key)
+        return jwk_info
+
+    def all_services(self) -> dict[str, list[JwkPemFile]]:
+        if self._settings.jwks_auth_enabled is False:
+            raise ServiceAuthenticaionDisabledError()
+
+        return {s: [j.pem for j in jwk_infos] for s, jwk_infos in self._jwks_full_cache.items()}
+
+    def clear_all_jwks(self) -> None:
+        if self._fs.exists(self._jwks_root_file_url):
+            self._fs.rm(self._jwks_root_file_url, recursive=True)
+
+        self._clear_cache()
+
+    def current_service_version(self, service_name: str) -> int | None:
+        if self._settings.jwks_auth_enabled is False:
+            raise ServiceAuthenticaionDisabledError()
+
+        return self._jwks_version_cache.get(service_name)
+
+    def get_jwk(self, kid: str) -> JwkInfo:
+        if self._settings.jwks_auth_enabled is False:
+            raise ServiceAuthenticaionDisabledError()
+
+        service_name = kid.split(".")[0]
+        if service_name not in self._jwks_full_cache:
+            raise ServiceUnknownError()
+
+        jwk_info = next(
+            filter(
+                lambda e: e.pem.kid == kid,
+                self._jwks_full_cache[service_name],
+            ),
+            None,
+        )
+        if jwk_info is None:
+            raise ServiceKeyMissingError()
+
+        return jwk_info
+
+    @property
+    def is_enabled(self) -> bool:
+        return self._settings.jwks_auth_enabled
+
+    @property
+    def keys_dict(self) -> dict:
+        if self._settings.jwks_auth_enabled is False:
+            raise ServiceAuthenticaionDisabledError()
+
+        return self._keys_dict
+
+    async def rebuild_caches(self):
+        if self._settings.jwks_auth_enabled is False:
+            raise ServiceAuthenticaionDisabledError()
+
+        if not self._fs.exists(self._jwks_root_file_url):
+            self._fs.makedir(self._jwks_root_file_url, create_parents=True)
+
+        self._clear_cache()
+
+        for service_dir in self._fs.ls(self._jwks_root_file_url):
+            service_dir_url = self._fs.parse_file_url(service_dir["url"])
+            if self._fs.isdir(service_dir_url):
+                self._jwks_full_cache[service_dir_url.directory] = []
+                for pem_file in self._fs.ls(service_dir_url):
+                    pem_file_url = self._fs.parse_file_url(pem_file["url"])
+                    if self._fs.isfile(pem_file_url):
+                        self.add_jwk(pem_file_url)
+
+        yield {
+            "jwks_full_cache": self._jwks_full_cache,
+            "jwks_version_cache": self._jwks_version_cache,
+            "keys": self._keys,
+        }
+
+    # IMPORTANT NOTE: Each server instance keeps an in-memory cache of
+    # all jwks records. Thus if you are running multiple instances and
+    # you write a new public key (e.g. due to regular rotation maintenance)
+    # you will need to ensure that all server instances are rebooted.
+    async def write_public_key(self, service_name: str, key_bytes: bytes) -> JwkInfo:
+        if self._settings.jwks_auth_enabled is False:
+            raise ServiceAuthenticaionDisabledError()
+
+        version = (
+            self._jwks_version_cache[service_name] + 1
+            if service_name in self._jwks_version_cache
+            else 0
+        )
+        generated_at = datetime.datetime.now(datetime.UTC)
+
+        pem_file_url: FileUrl = self._jwks_root_file_url.join(
+            directory=service_name,
+            file_name=JwkPemFile.file_name_public(service_name, version, generated_at),
+        )
+        service_dir_url = pem_file_url.parent()
+        if not self._fs.exists(service_dir_url):
+            self._fs.makedir(url=pem_file_url.parent(), create_parents=True)
+
+        pem_file_url, _ = await self._fs.write_bytes(pem_file_url, key_bytes)
+        return self.add_jwk(pem_file_url)

apppy_auth-0.1.0/src/apppy/auth/jwks_unit_test.py

@@ -0,0 +1,21 @@
+import datetime
+
+from apppy.auth.jwks import JwkPemFile
+
+
+def test_jwk_parse_file_name_private():
+    service_name, version, generated_at = JwkPemFile._parse_file_name(
+        "test_jwk_pem_file_public.v0.20250905215639.key.pem"
+    )
+    assert service_name == "test_jwk_pem_file_public"
+    assert version == 0
+    assert generated_at == datetime.datetime(2025, 9, 5, 21, 56, 39, 0)
+
+
+def test_jwk_parse_file_name_public():
+    service_name, version, generated_at = JwkPemFile._parse_file_name(
+        "test_jwk_pem_file_public.v0.20250905215639.pub.pem"
+    )
+    assert service_name == "test_jwk_pem_file_public"
+    assert version == 0
+    assert generated_at == datetime.datetime(2025, 9, 5, 21, 56, 39, 0)

apppy_auth-0.1.0/src/apppy/auth/jwt.py

@@ -0,0 +1,200 @@
+import contextvars
+import datetime
+import logging
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from fastapi import HTTPException, Request
+from fastapi_another_jwt_auth import AuthJWT as JWT
+from pydantic import Field
+
+from apppy.auth import convert_token_to_jwt, extract_jwt_from_request
+from apppy.env import EnvSettings
+from apppy.fastql.errors import GraphQLClientError, GraphQLError, GraphQLServerError
+from apppy.fastql.permissions import GraphQLPermission
+from apppy.logger import WithLogger
+
+JwtAuthSubjectType = Literal["user", "service"]
+
+# Define a context variable per key
+_current_auth_context: contextvars.ContextVar["JwtAuthContext"] = contextvars.ContextVar(
+    "_current_auth_context"
+)
+
+# This breaks the typically logger pattern
+# but logging is needed in static methods
+_logger = logging.getLogger("apppy.auth.jwt.JwtAuthContext")
+
+
+class JwtAuthSettings(EnvSettings):
+    # The names here must match the names found in
+    # fastapi_another_jwt_auth.AuthConfig.load_config
+    authjwt_decode_audience: str = Field(
+        alias="APP_JWT_AUTH_DECODE_AUDIENCE", default="authenticated"
+    )
+
+    authjwt_encode_issuer: str = Field(alias="APP_JWT_AUTH_ENCODE_ISSUER")
+    authjwt_secret_key: str = Field(alias="APP_JWT_AUTH_SECRET_KEY", exclude=True)
+
+
+@dataclass
+class JwtAuthContext(WithLogger):
+    # In some cases we'll encounter an error
+    # while preprocessing a JwtAuthContext. The classic
+    # example of this is attempting a service authentication
+    # when service authentication is disabled. For those cases,
+    # we'll store the preprocessing error code here so that we
+    # can return the appropriate error type to the client.
+    preprocessing_error: GraphQLError | None = None
+
+    has_token: bool = False
+    is_token_well_formed: bool = False
+    expires_at: int = 0
+    issued_at: int = 0
+
+    auth_session_id: str | None = None
+    auth_subject_id: str | None = None  # user_id or service_id
+    auth_subject_type: JwtAuthSubjectType | None = None
+
+    iam_enabled: bool = False
+    iam_revoked_at: datetime.datetime | None = None
+    iam_role: str | None = None
+    iam_scopes: list[str] | None = None
+
+    raw_claims: dict[str, Any] | None = None
+
+    def check_graphql_permissions(self, *permissions: GraphQLPermission) -> "JwtAuthContext":
+        for perm in permissions:
+            if not perm.has_permission(source=None, info=None, auth_ctx=self):  # type: ignore[arg-type]
+                raise perm.graphql_client_error_class(*perm.graphql_client_error_args())  # type: ignore[missing-argument]
+
+        return self
+
+    def check_http_permissions(self, *permissions: GraphQLPermission) -> "JwtAuthContext":
+        # Here we'll get the context for the appropriate GraphQL permissions
+        # but then raise an HTTP exception rather than a typed GraphQL exception
+        for perm in permissions:
+            try:
+                if not perm.has_permission(source=None, info=None, auth_ctx=self):  # type: ignore[arg-type]
+                    raise HTTPException(status_code=401)
+            except GraphQLClientError as e:
+                raise HTTPException(status_code=401) from e
+            except GraphQLServerError as e:
+                raise HTTPException(status_code=500) from e
+
+        return self
+
+    @staticmethod
+    def current_auth_context() -> "JwtAuthContext":
+        return _current_auth_context.get()
+
+    @staticmethod
+    def set_current_auth_context(auth_ctx: "JwtAuthContext") -> None:
+        _current_auth_context.set(auth_ctx)
+
+    @staticmethod
+    def _create_service_context(claims) -> "JwtAuthContext":
+        if claims is None:
+            _logger.warning("No claims found in service JWT")
+            return JwtAuthContext(has_token=False)
+        elif "service_metadata" not in claims:
+            _logger.warning("No service_metadata found in service JWT.")
+            return JwtAuthContext(has_token=True, is_token_well_formed=False)
+
+        service_metadata: dict[str, Any] = claims["service_metadata"]  # type: ignore[invalid-assignment]
+        iam_metadata: dict[str, Any] = service_metadata.get("iam_metadata", {})
+
+        return JwtAuthContext(
+            has_token=True,
+            is_token_well_formed=True,
+            expires_at=claims["exp"],  # type: ignore[invalid-argument-type]
+            issued_at=claims["iat"],  # type: ignore[invalid-argument-type]
+            auth_session_id=None,
+            auth_subject_id=service_metadata.get("service_name"),
+            auth_subject_type="service",
+            iam_enabled=True,
+            iam_revoked_at=None,
+            iam_role=iam_metadata.get("role"),
+            iam_scopes=iam_metadata.get("scopes", []),
+            raw_claims=claims,
+        )
+
+    @staticmethod
+    def _create_user_context(claims) -> "JwtAuthContext":
+        if claims is None:
+            _logger.warning("No claims found in user JWT")
+            return JwtAuthContext(has_token=False)
+        elif "user_metadata" not in claims:
+            _logger.warning("No user_metadata found in user JWT.")
+            return JwtAuthContext(has_token=True, is_token_well_formed=False)
+
+        user_metadata: dict[str, Any] = claims["user_metadata"]  # type: ignore[invalid-assignment]
+        iam_metadata: dict[str, Any] = user_metadata.get("iam_metadata", {})
+        return JwtAuthContext(
+            has_token=True,
+            is_token_well_formed=True,
+            expires_at=claims["exp"],  # type: ignore[invalid-argument-type]
+            issued_at=claims["iat"],  # type: ignore[invalid-argument-type]
+            auth_session_id=claims.get("session_id"),  # type: ignore[invalid-argument-type]
+            auth_subject_id=user_metadata.get("subject_id"),
+            auth_subject_type="user",
+            iam_enabled=iam_metadata.get("enabled", False),
+            iam_revoked_at=iam_metadata.get("revoked_at"),
+            iam_role=iam_metadata.get("role"),
+            iam_scopes=iam_metadata.get("scopes", []),
+            raw_claims=claims,
+        )
+
+    @staticmethod
+    def from_jwt(jwt_: JWT) -> "JwtAuthContext":
+        if not jwt_._token:
+            return JwtAuthContext(has_token=False)
+
+        claims = jwt_.get_raw_jwt()
+        if claims is None:
+            _logger.warning("No claims found in JWT")
+            return JwtAuthContext(has_token=False)
+
+        if "user_metadata" in claims:
+            return JwtAuthContext._create_user_context(claims)
+        elif "service_metadata" in claims:
+            return JwtAuthContext._create_service_context(claims)
+
+        _logger.warning(
+            "No user_metadata nor kid found in JWT. We do not know if this is a user or a service"
+        )
+        return JwtAuthContext(has_token=True, is_token_well_formed=False)
+
+    @staticmethod
+    def from_service_request(
+        request: Request,
+        algorithm: str,
+        public_key: str,
+    ) -> "JwtAuthContext":
+        jwt_ = extract_jwt_from_request(request)
+        jwt_._algorithm = algorithm
+        jwt_._public_key = public_key
+
+        claims = jwt_.get_raw_jwt()
+        return JwtAuthContext._create_service_context(claims)
+
+    @staticmethod
+    def from_user_request(request: Request) -> "JwtAuthContext":
+        jwt_ = extract_jwt_from_request(request)
+
+        claims = jwt_.get_raw_jwt()
+        return JwtAuthContext._create_user_context(claims)
+
+    @staticmethod
+    def from_token(token: str) -> "JwtAuthContext":
+        jwt_: JWT = convert_token_to_jwt(token)
+        return JwtAuthContext.from_jwt(jwt_)
+
+    @staticmethod
+    def peek(request: Request) -> dict | None:
+        jwt_: JWT = extract_jwt_from_request(request)
+        if jwt_._token is None:
+            return None
+
+        headers = jwt_.get_unverified_jwt_headers()
+        return headers

apppy_auth-0.1.0/src/apppy/auth/jwt_unit_test.py

@@ -0,0 +1,160 @@
+import datetime
+
+from apppy.auth.jwt import JwtAuthContext
+
+
+class FakeJWT:
+    """
+    Minimal stub for the JWT class used by JwtAuthContext.
+    - Accepts _token to simulate "has token" vs not.
+    - Returns the provided claims from get_raw_jwt().
+    """
+
+    def __init__(self, *, _token=None, claims=None, **kwargs):
+        self._token = _token
+        self._claims = claims
+
+    def get_raw_jwt(self):
+        return self._claims
+
+
+def _claims_base(exp=1111111111, iat=1111110000, **extra):
+    c = {"exp": exp, "iat": iat}
+    c.update(extra)
+    return c
+
+
+def test_jwt_empty():
+    ctx = JwtAuthContext()
+    assert ctx.has_token is False
+    assert ctx.is_token_well_formed is False
+    assert ctx.expires_at == 0
+    assert ctx.issued_at == 0
+    # sanity: optional fields default to None
+    assert ctx.auth_session_id is None
+    assert ctx.auth_subject_id is None
+    assert ctx.auth_subject_type is None
+    assert ctx.iam_enabled is False
+
+    assert ctx.iam_revoked_at is None
+    assert ctx.iam_role is None
+    assert ctx.iam_scopes is None
+
+    assert ctx.raw_claims is None
+
+
+def test_jwt_is_unauthenticated_when_no_token():
+    jwt = FakeJWT(_token=None, claims=None)
+    ctx = JwtAuthContext.from_jwt(jwt)  # type: ignore[invalid-argument-type]
+    assert ctx.has_token is False
+    assert ctx.is_token_well_formed is False
+    assert ctx.iam_enabled is False
+
+
+def test_jwt_is_unauthenticated_when_no_claims():
+    jwt = FakeJWT(_token="token", claims=None)
+    ctx = JwtAuthContext.from_jwt(jwt)  # type: ignore[invalid-argument-type]
+    assert ctx.has_token is False
+    assert ctx.is_token_well_formed is False
+    assert ctx.iam_enabled is False
+
+
+def test_jwt_is_unauthenticated_when_missing_user_metadata():
+    claims = _claims_base()  # no "user_metadata" key
+    jwt = FakeJWT(_token="token", claims=claims)
+    ctx = JwtAuthContext.from_jwt(jwt)  # type: ignore[invalid-argument-type]
+    assert ctx.has_token is True
+    assert ctx.is_token_well_formed is False
+    assert ctx.iam_enabled is False
+
+
+def test_service_jwt_is_unauthenticated_when_iam_is_disabled():
+    claims = _claims_base(
+        user_metadata={
+            "subject_type": "service",
+            "iam_metadata": {
+                "enabled": False,
+            },
+        }
+    )
+    jwt = FakeJWT(_token="token", claims=claims)
+    ctx = JwtAuthContext.from_jwt(jwt)  # type: ignore[invalid-argument-type]
+    assert ctx.has_token is True
+    assert ctx.is_token_well_formed is True
+    assert ctx.iam_enabled is False
+
+
+def test_service_jwt_is_unauthenticated_when_iam_is_revoked():
+    claims = _claims_base(
+        user_metadata={
+            "subject_type": "service",
+            "iam_metadata": {"enabled": True, "revoked_at": datetime.datetime.now()},
+        }
+    )
+    jwt = FakeJWT(_token="token", claims=claims)
+    ctx = JwtAuthContext.from_jwt(jwt)  # type: ignore[invalid-argument-type]
+    assert ctx.has_token is True
+    assert ctx.is_token_well_formed is True
+    assert ctx.iam_enabled is True
+    assert ctx.iam_revoked_at is not None
+
+
+def test_service_jwt_subject_type():
+    claims = _claims_base(
+        service_metadata={
+            "subject_type": "service",
+            "iam_metadata": {
+                "enabled": True,
+            },
+        }
+    )
+    jwt = FakeJWT(_token="token", claims=claims)
+
+    ctx = JwtAuthContext.from_jwt(jwt)  # type: ignore[invalid-argument-type]
+    assert ctx.auth_subject_type == "service"
+
+
+def test_user_jwt_is_unauthenticated_when_iam_is_disabled():
+    claims = _claims_base(
+        user_metadata={
+            "subject_type": "user",
+            "iam_metadata": {
+                "enabled": False,
+            },
+        }
+    )
+    jwt = FakeJWT(_token="token", claims=claims)
+    ctx = JwtAuthContext.from_jwt(jwt)  # type: ignore[invalid-argument-type]
+    assert ctx.has_token is True
+    assert ctx.is_token_well_formed is True
+    assert ctx.iam_enabled is False
+
+
+def test_user_jwt_is_unauthenticated_when_iam_is_revoked():
+    claims = _claims_base(
+        user_metadata={
+            "subject_type": "user",
+            "iam_metadata": {"enabled": True, "revoked_at": datetime.datetime.now()},
+        }
+    )
+    jwt = FakeJWT(_token="token", claims=claims)
+    ctx = JwtAuthContext.from_jwt(jwt)  # type: ignore[invalid-argument-type]
+    assert ctx.has_token is True
+    assert ctx.is_token_well_formed is True
+    assert ctx.iam_enabled is True
+    assert ctx.iam_revoked_at is not None
+
+
+def test_user_jwt_subject_type():
+    claims = _claims_base(
+        user_metadata={
+            "subject_type": "user",
+            "iam_metadata": {
+                "enabled": True,
+            },
+        }
+    )
+    jwt = FakeJWT(_token="token", claims=claims)
+
+    ctx = JwtAuthContext.from_jwt(jwt)  # type: ignore[invalid-argument-type]
+    assert ctx.auth_subject_type == "user"

apppy_auth-0.1.0/src/apppy/auth/oauth.py

@@ -0,0 +1,31 @@
+from authlib.integrations.starlette_client import OAuth
+
+from apppy.auth.errors.oauth import UnknownOAuthProviderError
+from apppy.env import EnvSettings
+from apppy.logger import WithLogger
+
+
+class OAuthRegistrySettings(EnvSettings):
+    pass
+
+
+class OAuthRegistry(OAuth, WithLogger):
+    """
+    Wrapper about the Starlette OAuth integration to allow for
+    any custom settings or logic to be added.
+    """
+
+    def __init__(self, settings: OAuthRegistrySettings) -> None:
+        super().__init__()
+        self._settings = settings
+
+    def load_client(self, provider: str) -> OAuth:
+        oauth_client = self.create_client(provider)
+        if oauth_client is None:
+            raise UnknownOAuthProviderError(provider)
+
+        return oauth_client
+
+    def register(self, name, overwrite=False, **kwargs):
+        self._logger.info("Registering OAuth provider", extra={"provider": name})
+        super().register(name, overwrite=overwrite, **kwargs)

apppy_auth-0.1.0/src/apppy/auth/permissions.py

@@ -0,0 +1,281 @@
+import datetime
+from collections.abc import Sequence
+from typing import Any
+
+from apppy.auth.jwt import JwtAuthContext
+from apppy.fastql.annotation import fastql_type_error
+from apppy.fastql.errors import GraphQLClientError, GraphQLServerError
+from apppy.fastql.permissions import GraphQLPermission
+from apppy.logger import WithLogger
+
+
+def _check_preprocessing_errors(permission: GraphQLPermission, auth_ctx: JwtAuthContext) -> None:
+    if auth_ctx.preprocessing_error is not None:
+        if isinstance(auth_ctx.preprocessing_error, GraphQLClientError):
+            permission._error_code = auth_ctx.preprocessing_error.code  # type: ignore[attr-defined]
+            raise permission.graphql_client_error_class(*permission.graphql_client_error_args())
+        else:
+            raise permission.graphql_server_error_class(auth_ctx.preprocessing_error.code)
+
+
+def _extract_auth_context(permission: GraphQLPermission, info, **kwargs) -> JwtAuthContext:
+    auth_ctx: JwtAuthContext = kwargs.get("auth_ctx")  # type: ignore[assignment]
+    if auth_ctx is not None:
+        return auth_ctx
+
+    if not info:
+        permission._logger.error(
+            "No context or info provided while attempting to check permission",
+            extra={"permission": type(permission).__name__},
+        )
+        raise permission.graphql_server_error_class("missing_context_and_info")
+
+    return info.context.auth
+
+
+@fastql_type_error
+class AuthenticationServerError(GraphQLServerError):
+    """Error raised when authentication fails due to an error on the server side"""
+
+    def __init__(self, code) -> None:
+        super().__init__(code)
+
+
+@fastql_type_error
+class AuthenticatedServiceOrUserRequiredError(GraphQLClientError):
+    """Error raised when authentication is required but it is missing"""
+
+    def __init__(self, code) -> None:
+        super().__init__(code)
+
+
+class IsServiceOrUser(GraphQLPermission, WithLogger):
+    graphql_client_error_class = AuthenticatedServiceOrUserRequiredError
+    graphql_server_error_class = AuthenticationServerError
+
+    def __init__(self):
+        self._error_code: str | None = None
+
+    def has_permission(self, source, info, **kwargs) -> bool:
+        auth_ctx: JwtAuthContext = _extract_auth_context(self, info, **kwargs)
+        _check_preprocessing_errors(self, auth_ctx)
+
+        is_authenticated, self._error_code = IsServiceOrUser.is_context_authenticated(auth_ctx)
+        return is_authenticated
+
+    @staticmethod
+    def is_context_authenticated(auth_ctx: JwtAuthContext) -> tuple[bool, str | None]:
+        if not auth_ctx.has_token:
+            return (False, "token_is_missing")
+        if not auth_ctx.is_token_well_formed:
+            return (False, "token_is_not_well_formed")
+
+        now = int(datetime.datetime.now().timestamp())
+        if now > auth_ctx.expires_at:
+            return (False, "token_is_expired")
+        if not auth_ctx.iam_enabled:
+            return (False, "iam_is_disabled")
+        if auth_ctx.iam_revoked_at is not None:
+            return (False, "iam_is_revoked")
+
+        return (True, None)
+
+    def graphql_client_error_args(self) -> tuple[Any, ...]:
+        return (self._error_code,)
+
+
+@fastql_type_error
+class AuthenticatedUserRequiredError(GraphQLClientError):
+    """Error raised when a user authentication is required but it is missing"""
+
+    def __init__(self, code: str) -> None:
+        super().__init__(code)
+
+
+class IsUser(GraphQLPermission, WithLogger):
+    graphql_client_error_class = AuthenticatedUserRequiredError
+    graphql_server_error_class = AuthenticationServerError
+
+    def __init__(self):
+        self._error_code: str | None = None
+
+    def has_permission(self, source, info, **kwargs) -> bool:
+        auth_ctx: JwtAuthContext = _extract_auth_context(self, info, **kwargs)
+        _check_preprocessing_errors(self, auth_ctx)
+
+        is_authenticated, self._error_code = IsUser.is_context_user_authenticated(auth_ctx)
+        return is_authenticated
+
+    @staticmethod
+    def is_context_user_authenticated(auth_ctx: JwtAuthContext) -> tuple[bool, str | None]:
+        is_authenticated, error_code = IsServiceOrUser.is_context_authenticated(auth_ctx)
+        if not is_authenticated:
+            return (is_authenticated, error_code)
+
+        if auth_ctx.auth_subject_type != "user":
+            return (False, "not_authenticated_as_user")
+
+        return (True, None)
+
+    def graphql_client_error_args(self) -> tuple[Any, ...]:
+        return (self._error_code,)
+
+
+@fastql_type_error
+class AuthenticatedServiceRequiredError(GraphQLClientError):
+    """Error raised when a service authentication is required but it is missing"""
+
+    def __init__(self, code: str) -> None:
+        super().__init__(code)
+
+
+class IsService(GraphQLPermission):
+    graphql_client_error_class = AuthenticatedServiceRequiredError
+    graphql_server_error_class = AuthenticationServerError
+
+    def __init__(self):
+        self._error_code: str | None = None
+
+    def has_permission(self, source, info, **kwargs) -> bool:
+        auth_ctx: JwtAuthContext = _extract_auth_context(self, info, **kwargs)
+        _check_preprocessing_errors(self, auth_ctx)
+
+        is_authenticated, self._error_code = IsService.is_context_service_authenticated(auth_ctx)
+        return is_authenticated
+
+    @staticmethod
+    def is_context_service_authenticated(auth_ctx: JwtAuthContext) -> tuple[bool, str | None]:
+        is_authenticated, error_code = IsServiceOrUser.is_context_authenticated(auth_ctx)
+        if not is_authenticated:
+            return (is_authenticated, error_code)
+
+        if auth_ctx.auth_subject_type != "service":
+            return (False, "not_authenticated_as_service")
+
+        return (True, None)
+
+    def graphql_client_error_args(self) -> tuple[Any, ...]:
+        return (self._error_code,)
+
+
+@fastql_type_error
+class AuthorizationServerError(GraphQLServerError):
+    """Error raised when authorization fails due to an error on the server side"""
+
+    def __init__(self, code) -> None:
+        super().__init__(code)
+
+
+@fastql_type_error
+class AuthorizedRoleRequiredError(GraphQLClientError):
+    """Error raised when an authorization role is required but it is missing"""
+
+    permitted_role: str
+
+    def __init__(self, permitted_role: str) -> None:
+        super().__init__("authorization_role_required")
+        self.permitted_role = permitted_role
+
+
+class HasRole(GraphQLPermission, WithLogger):
+    graphql_client_error_class = AuthorizedRoleRequiredError
+    graphql_server_error_class = AuthorizationServerError
+
+    def __init__(self, role: str):
+        self._role = role
+
+    def has_permission(self, source, info, **kwargs) -> bool:
+        auth_ctx: JwtAuthContext = _extract_auth_context(self, info, **kwargs)
+        _check_preprocessing_errors(self, auth_ctx)
+
+        return bool(auth_ctx.iam_role and self._role == auth_ctx.iam_role)
+
+    def graphql_client_error_args(self) -> tuple[Any, ...]:
+        return (self._role,)
+
+
+@fastql_type_error
+class AuthorizedScopeRequiredError(GraphQLClientError):
+    """Error raised when an authorization scope is required but it is missing"""
+
+    permitted_scope: str
+
+    def __init__(self, permitted_scope: str) -> None:
+        super().__init__("authorization_scope_required")
+        self.permitted_scope = permitted_scope
+
+
+class HasScope(GraphQLPermission, WithLogger):
+    graphql_client_error_class = AuthorizedScopeRequiredError
+    graphql_server_error_class = AuthorizationServerError
+
+    def __init__(self, scope: str):
+        self._scope = scope
+
+    def has_permission(self, source, info, **kwargs) -> bool:
+        auth_ctx: JwtAuthContext = _extract_auth_context(self, info, **kwargs)
+        _check_preprocessing_errors(self, auth_ctx)
+
+        return self._check_scope(auth_ctx)
+
+    def graphql_client_error_args(self) -> tuple[Any, ...]:
+        return (self._scope,)
+
+    def _check_scope(self, auth_ctx: JwtAuthContext) -> bool:
+        # Allow hierarchical scopes like "users:read" implied by "users:*"
+        if not auth_ctx.iam_scopes:
+            return False
+        if self._scope in auth_ctx.iam_scopes:
+            return True
+
+        prefix = self._scope.split(":")[0] + ":*"
+        return prefix in auth_ctx.iam_scopes
+
+
+@fastql_type_error
+class AuthorizedRoleOrScopeRequiredError(GraphQLClientError):
+    """Error raised when an authorization role is required but it is missing"""
+
+    permitted_roles: list[str]
+    permitted_scopes: list[str]
+
+    def __init__(self, permitted_roles: list[str], permitted_scopes: list[str]) -> None:
+        super().__init__("authorization_role_or_scope_required")
+        self.permitted_roles = permitted_roles
+        self.permitted_scopes = permitted_scopes
+
+
+class HasRoleOrScope(GraphQLPermission, WithLogger):
+    graphql_client_error_class = AuthorizedRoleOrScopeRequiredError
+    graphql_server_error_class = AuthorizationServerError
+
+    def __init__(self, roles: Sequence[str | HasRole] = (), scopes: Sequence[str | HasScope] = ()):
+        self._roles = roles
+        self._role_permissions: list[HasRole] = [
+            role if isinstance(role, HasRole) else HasRole(role) for role in roles
+        ]
+        self._scopes = scopes
+        self._scope_permissions: list[HasScope] = [
+            scope if isinstance(scope, HasScope) else HasScope(scope) for scope in scopes
+        ]
+
+    def has_permission(self, source, info, **kwargs) -> bool:
+        auth_ctx: JwtAuthContext = _extract_auth_context(self, info, **kwargs)
+        _check_preprocessing_errors(self, auth_ctx)
+
+        has_role: bool = any(
+            perm.has_permission(source, info, auth_ctx=auth_ctx) for perm in self._role_permissions
+        )
+        has_scope: bool = False
+        if not has_role:
+            has_scope = any(
+                perm.has_permission(source, info, auth_ctx=auth_ctx)
+                for perm in self._scope_permissions
+            )
+        return bool(has_role or has_scope)
+
+    def graphql_client_error_args(self) -> tuple[Any, ...]:
+        return (
+            self._roles,
+            self._scopes,
+        )