authmate 0.1.0__py3-none-any.whl

authmate/__init__.py

@@ -0,0 +1,58 @@
+"""AuthMate's phase 0.1 contract-preview API."""
+
+from .errors import (
+    AuthMateClosedError,
+    AuthMateConfigurationError,
+    AuthMateError,
+    AuthMateUnavailableError,
+    AuthorizationDeniedError,
+    InvalidAuthorizationRequestError,
+    ProviderContractError,
+    ProviderUnavailableError,
+    SecretClosedError,
+)
+from .models import (
+    AccessContext,
+    AuditEvent,
+    AuditOutcome,
+    AuthorizationDecision,
+    CredentialRef,
+    DecisionReason,
+    PrincipalKind,
+    PrincipalRecord,
+    PrincipalRef,
+    ResourceRef,
+    SecretReference,
+    validate_action,
+)
+from .secrets import SecretValue
+from .service import AuthMate
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AccessContext",
+    "AuthMate",
+    "AuthMateClosedError",
+    "AuthMateConfigurationError",
+    "AuthMateError",
+    "AuthMateUnavailableError",
+    "AuditEvent",
+    "AuditOutcome",
+    "AuthorizationDecision",
+    "AuthorizationDeniedError",
+    "CredentialRef",
+    "DecisionReason",
+    "InvalidAuthorizationRequestError",
+    "PrincipalKind",
+    "PrincipalRecord",
+    "PrincipalRef",
+    "ProviderContractError",
+    "ProviderUnavailableError",
+    "ResourceRef",
+    "SecretClosedError",
+    "SecretReference",
+    "SecretValue",
+    "validate_action",
+    "__version__",
+]

authmate/errors.py

@@ -0,0 +1,75 @@
+"""Sanitized AuthMate exception types."""
+
+from __future__ import annotations
+
+from .models import AuthorizationDecision
+
+
+class AuthMateError(Exception):
+    """Base exception with a stable code and constant safe message."""
+
+    code = "authmate_error"
+    safe_message = "AuthMate error"
+
+    def __init__(self, *, decision: AuthorizationDecision | None = None) -> None:
+        super().__init__(self.safe_message)
+        self.decision = decision
+
+    def __str__(self) -> str:
+        return self.safe_message
+
+
+class InvalidAuthorizationRequestError(AuthMateError):
+    code = "invalid_authorization_request"
+    safe_message = "invalid authorization request"
+
+
+class AuthorizationDeniedError(AuthMateError):
+    code = "authorization_denied"
+    safe_message = "authorization denied"
+
+    def __init__(self, decision: AuthorizationDecision) -> None:
+        super().__init__(decision=decision)
+
+
+class AuthMateUnavailableError(AuthMateError):
+    code = "authmate_unavailable"
+    safe_message = "authorization service unavailable"
+
+
+class ProviderUnavailableError(AuthMateUnavailableError):
+    code = "provider_unavailable"
+    safe_message = "provider unavailable"
+
+
+class ProviderContractError(AuthMateUnavailableError):
+    code = "provider_contract_violation"
+    safe_message = "provider contract violation"
+
+
+class AuthMateConfigurationError(AuthMateError):
+    code = "authmate_configuration_error"
+    safe_message = "invalid AuthMate integration configuration"
+
+
+class AuthMateClosedError(AuthMateError):
+    code = "authmate_closed"
+    safe_message = "AuthMate is closed"
+
+
+class SecretClosedError(AuthMateError):
+    code = "secret_closed"
+    safe_message = "secret value is closed"
+
+
+__all__ = [
+    "AuthMateClosedError",
+    "AuthMateConfigurationError",
+    "AuthMateError",
+    "AuthMateUnavailableError",
+    "AuthorizationDeniedError",
+    "InvalidAuthorizationRequestError",
+    "ProviderContractError",
+    "ProviderUnavailableError",
+    "SecretClosedError",
+]

authmate/fastapi.py

@@ -0,0 +1,110 @@
+"""FastAPI dependency adaptation without owning authentication."""
+
+from collections.abc import Awaitable, Callable
+from typing import Annotated, Any
+
+from fastapi import Depends, HTTPException
+
+from .errors import (
+    AuthMateConfigurationError,
+    AuthMateUnavailableError,
+    AuthorizationDeniedError,
+)
+from .models import AccessContext, AuthorizationDecision, ResourceRef, validate_action
+from .service import AuthMate
+
+ContextDependency = Callable[..., AccessContext | Awaitable[AccessContext]]
+ResourceDependency = Callable[..., ResourceRef | Awaitable[ResourceRef]]
+
+
+class AuthMateSecurity:
+    """Create FastAPI dependencies backed by an existing AuthMate facade."""
+
+    def __init__(self, authmate: AuthMate, *, context_dependency: ContextDependency) -> None:
+        if not isinstance(authmate, AuthMate) or not callable(context_dependency):
+            raise AuthMateConfigurationError()
+        self._authmate = authmate
+        self._context_dependency = context_dependency
+
+    def require(
+        self,
+        action: str,
+        *,
+        resource_dependency: ResourceDependency | None = None,
+    ) -> Callable[..., Awaitable[AuthorizationDecision]]:
+        """Build a dependency that delegates to AuthMate.require exactly once."""
+
+        try:
+            validated_action = validate_action(action)
+        except (TypeError, ValueError) as exc:
+            raise AuthMateConfigurationError() from exc
+
+        if resource_dependency is not None and not callable(resource_dependency):
+            raise AuthMateConfigurationError()
+
+        if resource_dependency is None:
+
+            async def dependency(
+                context: Annotated[AccessContext, Depends(self._context_dependency)],
+            ) -> AuthorizationDecision:
+                verified_context = self._require_context(context)
+                return await self._enforce(
+                    context=verified_context,
+                    action=validated_action,
+                    resource=None,
+                )
+
+            return dependency
+
+        async def dependency_with_resource(
+            context: Annotated[AccessContext, Depends(self._context_dependency)],
+            resource: Annotated[ResourceRef, Depends(resource_dependency)],
+        ) -> AuthorizationDecision:
+            verified_context = self._require_context(context)
+            verified_resource = self._require_resource(resource)
+            return await self._enforce(
+                context=verified_context,
+                action=validated_action,
+                resource=verified_resource,
+            )
+
+        return dependency_with_resource
+
+    @staticmethod
+    def _require_context(value: Any) -> AccessContext:
+        if not isinstance(value, AccessContext):
+            raise AuthMateConfigurationError()
+        return value
+
+    @staticmethod
+    def _require_resource(value: Any) -> ResourceRef:
+        if not isinstance(value, ResourceRef):
+            raise AuthMateConfigurationError()
+        return value
+
+    async def _enforce(
+        self,
+        *,
+        context: AccessContext,
+        action: str,
+        resource: ResourceRef | None,
+    ) -> AuthorizationDecision:
+        try:
+            return await self._authmate.require(
+                context=context,
+                action=action,
+                resource=resource,
+            )
+        except AuthorizationDeniedError:
+            raise HTTPException(
+                status_code=403,
+                detail={"code": "authorization_denied"},
+            ) from None
+        except AuthMateUnavailableError:
+            raise HTTPException(
+                status_code=503,
+                detail={"code": "authmate_unavailable"},
+            ) from None
+
+
+__all__ = ["AuthMateSecurity", "ContextDependency", "ResourceDependency"]

authmate/models.py

@@ -0,0 +1,336 @@
+"""Immutable, validated values shared by AuthMate consumers and providers."""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import Annotated, Any
+from uuid import UUID
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    StrictBool,
+    StrictInt,
+    StrictStr,
+    StringConstraints,
+    TypeAdapter,
+    field_validator,
+    model_validator,
+)
+
+_DOTTED_NAME_PATTERN = r"^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+$"
+_REASON_PATTERN = r"^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)*$"
+_CORRELATION_PATTERN = r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+_PROVIDER_PATTERN = r"^[a-z][a-z0-9_-]{0,62}$"
+
+ActionName = Annotated[
+    StrictStr,
+    StringConstraints(pattern=_DOTTED_NAME_PATTERN, min_length=3, max_length=200),
+]
+ResourceType = Annotated[
+    StrictStr,
+    StringConstraints(pattern=_DOTTED_NAME_PATTERN, min_length=3, max_length=100),
+]
+EventType = Annotated[
+    StrictStr,
+    StringConstraints(pattern=_DOTTED_NAME_PATTERN, min_length=3, max_length=200),
+]
+ProviderAlias = Annotated[
+    StrictStr,
+    StringConstraints(pattern=_PROVIDER_PATTERN, min_length=1, max_length=63),
+]
+CorrelationId = Annotated[
+    StrictStr,
+    StringConstraints(pattern=_CORRELATION_PATTERN, min_length=1, max_length=128),
+]
+
+ACTION_ADAPTER = TypeAdapter(ActionName)
+
+
+class AuthMateModel(BaseModel):
+    """Base configuration for public immutable contract values."""
+
+    model_config = ConfigDict(
+        extra="forbid",
+        frozen=True,
+        str_strip_whitespace=False,
+        validate_assignment=True,
+    )
+
+
+def _reject_control_or_outer_whitespace(value: str, *, field_name: str) -> str:
+    if value != value.strip() or any(ord(char) < 32 or ord(char) == 127 for char in value):
+        raise ValueError(f"{field_name} contains invalid whitespace or control characters")
+    return value
+
+
+def _require_non_nil(value: UUID, *, field_name: str) -> UUID:
+    if value.int == 0:
+        raise ValueError(f"{field_name} must not be nil")
+    return value
+
+
+def _reject_non_json_uuid(value: object, *, field_name: str) -> object:
+    if not isinstance(value, (UUID, str)):
+        raise ValueError(f"{field_name} must be a UUID or string")
+    return value
+
+
+def _reject_non_json_enum(value: object, *, field_name: str) -> object:
+    if not isinstance(value, (str, StrEnum)):
+        raise ValueError(f"{field_name} must be a string")
+    return value
+
+
+def _reject_non_json_datetime(value: object, *, field_name: str) -> object:
+    if not isinstance(value, (datetime, str)):
+        raise ValueError(f"{field_name} must be a datetime or string")
+    return value
+
+
+def _as_utc(value: datetime, *, field_name: str) -> datetime:
+    if value.tzinfo is None or value.utcoffset() is None:
+        raise ValueError(f"{field_name} must be timezone-aware")
+    return value.astimezone(UTC)
+
+
+class PrincipalKind(StrEnum):
+    """Kinds of principals known by the contract preview."""
+
+    USER = "user"
+    SERVICE_ACCOUNT = "service_account"
+
+
+class PrincipalRef(AuthMateModel):
+    """An immutable principal identifier; it is not authentication proof."""
+
+    id: UUID
+    kind: PrincipalKind
+
+    @field_validator("id", mode="before")
+    @classmethod
+    def reject_coercive_id(cls, value: object) -> object:
+        return _reject_non_json_uuid(value, field_name="id")
+
+    @field_validator("id")
+    @classmethod
+    def validate_id(cls, value: UUID) -> UUID:
+        return _require_non_nil(value, field_name="id")
+
+    @field_validator("kind", mode="before")
+    @classmethod
+    def reject_coercive_kind(cls, value: object) -> object:
+        return _reject_non_json_enum(value, field_name="kind")
+
+
+class PrincipalRecord(AuthMateModel):
+    """Current provider-owned principal state used for an authorization check."""
+
+    ref: PrincipalRef
+    display_name: StrictStr = Field(min_length=1, max_length=200)
+    enabled: StrictBool
+    expires_at: datetime | None = None
+    version: StrictInt = Field(default=0, ge=0)
+
+    @field_validator("display_name")
+    @classmethod
+    def validate_display_name(cls, value: str) -> str:
+        return _reject_control_or_outer_whitespace(value, field_name="display_name")
+
+    @field_validator("expires_at")
+    @classmethod
+    def normalize_expiry(cls, value: datetime | None) -> datetime | None:
+        return None if value is None else _as_utc(value, field_name="expires_at")
+
+    @field_validator("expires_at", mode="before")
+    @classmethod
+    def reject_coercive_expiry(cls, value: object) -> object:
+        if value is None:
+            return None
+        return _reject_non_json_datetime(value, field_name="expires_at")
+
+
+class ResourceRef(AuthMateModel):
+    """Exact consumer resource identity supplied by a trusted consumer lookup."""
+
+    type: ResourceType
+    id: StrictStr = Field(min_length=1, max_length=255)
+
+    @field_validator("id")
+    @classmethod
+    def validate_id(cls, value: str) -> str:
+        return _reject_control_or_outer_whitespace(value, field_name="resource id")
+
+
+class AccessContext(AuthMateModel):
+    """Verified actor context supplied by a trusted host integration."""
+
+    actor: PrincipalRef
+    effective: PrincipalRef | None = None
+    correlation_id: CorrelationId | None = None
+
+    @model_validator(mode="after")
+    def validate_distinct_effective(self) -> AccessContext:
+        if self.effective is not None and self.effective == self.actor:
+            raise ValueError("effective must be omitted for a direct actor")
+        return self
+
+
+class DecisionReason(StrEnum):
+    """Stable reasons attached to authorization decisions."""
+
+    ALLOWED = "allowed"
+    DENIED = "denied"
+    PRINCIPAL_NOT_FOUND = "principal_not_found"
+    PRINCIPAL_DISABLED = "principal_disabled"
+    PRINCIPAL_EXPIRED = "principal_expired"
+    DELEGATION_NOT_SUPPORTED = "delegation_not_supported"
+    PROVIDER_UNAVAILABLE = "provider_unavailable"
+    PROVIDER_CONTRACT_VIOLATION = "provider_contract_violation"
+
+
+class AuthorizationDecision(AuthMateModel):
+    """A single authorization evaluation; never a reusable capability."""
+
+    allowed: StrictBool
+    reason: DecisionReason
+    action: ActionName
+    resource: ResourceRef | None = None
+    policy_revision: StrictStr | None = Field(default=None, min_length=1, max_length=128)
+
+    @field_validator("reason", mode="before")
+    @classmethod
+    def reject_coercive_reason(cls, value: object) -> object:
+        return _reject_non_json_enum(value, field_name="reason")
+
+    @field_validator("policy_revision")
+    @classmethod
+    def validate_policy_revision(cls, value: str | None) -> str | None:
+        return (
+            None
+            if value is None
+            else _reject_control_or_outer_whitespace(value, field_name="policy_revision")
+        )
+
+    @model_validator(mode="after")
+    def validate_allowed_reason(self) -> AuthorizationDecision:
+        if self.allowed and self.reason is not DecisionReason.ALLOWED:
+            raise ValueError("allowed decisions must use reason 'allowed'")
+        if not self.allowed and self.reason is DecisionReason.ALLOWED:
+            raise ValueError("denied decisions cannot use reason 'allowed'")
+        return self
+
+
+class CredentialRef(AuthMateModel):
+    """Opaque credential identifier reserved for later resolver integration."""
+
+    id: UUID
+
+    @field_validator("id", mode="before")
+    @classmethod
+    def reject_coercive_id(cls, value: object) -> object:
+        return _reject_non_json_uuid(value, field_name="id")
+
+    @field_validator("id")
+    @classmethod
+    def validate_id(cls, value: UUID) -> UUID:
+        return _require_non_nil(value, field_name="id")
+
+
+class SecretReference(AuthMateModel):
+    """Provider alias and opaque key; it is never resolved in phase 0.1."""
+
+    provider: ProviderAlias
+    key: StrictStr = Field(min_length=1, max_length=255)
+
+    @field_validator("key")
+    @classmethod
+    def validate_key(cls, value: str) -> str:
+        return _reject_control_or_outer_whitespace(value, field_name="secret key")
+
+
+class AuditOutcome(StrEnum):
+    """Outcome vocabulary for the preview audit protocol."""
+
+    SUCCEEDED = "succeeded"
+    DENIED = "denied"
+    FAILED = "failed"
+
+
+class AuditEvent(AuthMateModel):
+    """Bounded event value for the unwired phase 0.1 audit protocol."""
+
+    id: UUID
+    event_type: EventType
+    occurred_at: datetime
+    outcome: AuditOutcome
+    actor: PrincipalRef | None = None
+    effective: PrincipalRef | None = None
+    action: ActionName | None = None
+    resource: ResourceRef | None = None
+    reason_code: StrictStr | None = Field(default=None, min_length=1, max_length=100)
+    correlation_id: CorrelationId | None = None
+
+    @field_validator("id", mode="before")
+    @classmethod
+    def reject_coercive_id(cls, value: object) -> object:
+        return _reject_non_json_uuid(value, field_name="id")
+
+    @field_validator("id")
+    @classmethod
+    def validate_id(cls, value: UUID) -> UUID:
+        return _require_non_nil(value, field_name="id")
+
+    @field_validator("outcome", mode="before")
+    @classmethod
+    def reject_coercive_outcome(cls, value: object) -> object:
+        return _reject_non_json_enum(value, field_name="outcome")
+
+    @field_validator("occurred_at", mode="before")
+    @classmethod
+    def reject_coercive_occurred_at(cls, value: object) -> object:
+        return _reject_non_json_datetime(value, field_name="occurred_at")
+
+    @field_validator("occurred_at")
+    @classmethod
+    def normalize_occurred_at(cls, value: datetime) -> datetime:
+        return _as_utc(value, field_name="occurred_at")
+
+    @field_validator("reason_code")
+    @classmethod
+    def validate_reason_code(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        _reject_control_or_outer_whitespace(value, field_name="reason_code")
+        if not re.fullmatch(_REASON_PATTERN, value):
+            raise ValueError("reason_code has an invalid format")
+        return value
+
+
+def validate_action(value: Any) -> str:
+    """Validate an action at a service/dependency boundary."""
+
+    return ACTION_ADAPTER.validate_python(value)
+
+
+__all__ = [
+    "AccessContext",
+    "ActionName",
+    "AuditEvent",
+    "AuditOutcome",
+    "AuthorizationDecision",
+    "CredentialRef",
+    "DecisionReason",
+    "EventType",
+    "PrincipalKind",
+    "PrincipalRecord",
+    "PrincipalRef",
+    "ProviderAlias",
+    "ResourceRef",
+    "ResourceType",
+    "SecretReference",
+    "validate_action",
+]

authmate/protocols.py

@@ -0,0 +1,78 @@
+"""Provider-neutral extension protocols for AuthMate."""
+
+from __future__ import annotations
+
+from contextlib import AbstractAsyncContextManager as AsyncContextManager
+from typing import Any, Protocol
+
+from .models import (
+    AccessContext,
+    AuditEvent,
+    AuthorizationDecision,
+    CredentialRef,
+    PrincipalRecord,
+    PrincipalRef,
+    ResourceRef,
+    SecretReference,
+)
+from .secrets import SecretValue
+
+
+class PrincipalProvider(Protocol):
+    """Load current principal state from a host-owned source."""
+
+    async def get_principal(self, ref: PrincipalRef) -> PrincipalRecord | None: ...
+
+    async def aclose(self) -> None: ...
+
+
+class AuthorizationProvider(Protocol):
+    """Evaluate one authorization request for a current principal."""
+
+    async def authorize(
+        self,
+        *,
+        principal: PrincipalRecord,
+        action: str,
+        resource: ResourceRef | None,
+    ) -> AuthorizationDecision: ...
+
+    async def aclose(self) -> None: ...
+
+
+class CredentialResolver(Protocol):
+    """Future credential-to-secret boundary; unwired in phase 0.1."""
+
+    def resolve(
+        self,
+        *,
+        context: AccessContext,
+        credential: CredentialRef,
+    ) -> AsyncContextManager[SecretValue[Any]]: ...
+
+    async def aclose(self) -> None: ...
+
+
+class SecretProvider(Protocol):
+    """Future provider-specific secret boundary; unwired in phase 0.1."""
+
+    def resolve(self, reference: SecretReference) -> AsyncContextManager[SecretValue[Any]]: ...
+
+    async def aclose(self) -> None: ...
+
+
+class AuditSink(Protocol):
+    """Future audit delivery boundary; unwired in phase 0.1."""
+
+    async def record(self, event: AuditEvent) -> None: ...
+
+    async def aclose(self) -> None: ...
+
+
+__all__ = [
+    "AuditSink",
+    "AuthorizationProvider",
+    "CredentialResolver",
+    "PrincipalProvider",
+    "SecretProvider",
+]

authmate/secrets.py

@@ -0,0 +1,57 @@
+"""Redacted, explicitly closable secret values for protocol testing."""
+
+from __future__ import annotations
+
+from typing import Any, Generic, NoReturn, TypeVar, cast
+
+from .errors import SecretClosedError
+
+T = TypeVar("T")
+
+
+class SecretValue(Generic[T]):
+    """A non-serializable wrapper with deterministic redaction and cleanup."""
+
+    __slots__ = ("_closed", "_value")
+    _REDACTED = "SecretValue(<redacted>)"
+
+    def __init__(self, value: T) -> None:
+        self._value: T | None = value
+        self._closed = False
+
+    def reveal(self) -> T:
+        """Return the wrapped value until the lease is closed."""
+
+        if self._closed:
+            raise SecretClosedError()
+        return cast(T, self._value)
+
+    def close(self) -> None:
+        """Drop AuthMate's reference; repeated closes are harmless."""
+
+        self._value = None
+        self._closed = True
+
+    def __enter__(self) -> SecretValue[T]:
+        return self
+
+    def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> None:
+        self.close()
+
+    async def __aenter__(self) -> SecretValue[T]:
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return self._REDACTED
+
+    def __str__(self) -> str:
+        return self._REDACTED
+
+    def __reduce__(self) -> NoReturn:
+        raise TypeError("SecretValue cannot be serialized")
+
+
+__all__ = ["SecretValue"]

authmate/service.py

@@ -0,0 +1,256 @@
+"""The phase 0.1 authorization service facade."""
+
+from __future__ import annotations
+
+import asyncio
+import math
+from collections.abc import Awaitable, Callable
+from datetime import UTC, datetime
+from typing import TypeVar
+
+from pydantic import ValidationError
+
+from .errors import (
+    AuthMateClosedError,
+    AuthMateUnavailableError,
+    AuthorizationDeniedError,
+    InvalidAuthorizationRequestError,
+)
+from .models import (
+    AccessContext,
+    AuthorizationDecision,
+    DecisionReason,
+    PrincipalRecord,
+    ResourceRef,
+    validate_action,
+)
+from .protocols import AuthorizationProvider, PrincipalProvider
+
+T = TypeVar("T")
+
+
+class AuthMate:
+    """Authorize direct, non-HTTP calls through one provider-neutral service path."""
+
+    def __init__(
+        self,
+        *,
+        principal_provider: PrincipalProvider,
+        authorization_provider: AuthorizationProvider,
+        provider_timeout_seconds: float = 5.0,
+    ) -> None:
+        if isinstance(provider_timeout_seconds, bool) or not isinstance(
+            provider_timeout_seconds, (int, float)
+        ):
+            raise ValueError("provider timeout must be a finite number")
+        if not math.isfinite(float(provider_timeout_seconds)) or not (
+            0.01 <= float(provider_timeout_seconds) <= 60.0
+        ):
+            raise ValueError("provider timeout must be between 0.01 and 60 seconds")
+        self._principal_provider = principal_provider
+        self._authorization_provider = authorization_provider
+        self._timeout = float(provider_timeout_seconds)
+        self._condition = asyncio.Condition()
+        self._state = "open"
+        self._in_flight = 0
+        self._shutdown_task: asyncio.Task[None] | None = None
+
+    async def authorize(
+        self,
+        *,
+        context: AccessContext,
+        action: str,
+        resource: ResourceRef | None = None,
+    ) -> AuthorizationDecision:
+        """Return a single authorization decision and never turn failure into allow."""
+
+        await self._enter_operation()
+        try:
+            return await self._authorize_inner(context=context, action=action, resource=resource)
+        finally:
+            await self._exit_operation()
+
+    async def can(
+        self,
+        *,
+        context: AccessContext,
+        action: str,
+        resource: ResourceRef | None = None,
+    ) -> bool:
+        """Return only whether the current request is allowed."""
+
+        decision = await self.authorize(context=context, action=action, resource=resource)
+        return decision.allowed
+
+    async def require(
+        self,
+        *,
+        context: AccessContext,
+        action: str,
+        resource: ResourceRef | None = None,
+    ) -> AuthorizationDecision:
+        """Return an allow decision or raise a sanitized domain error."""
+
+        decision = await self.authorize(context=context, action=action, resource=resource)
+        if decision.allowed:
+            return decision
+        if decision.reason in {
+            DecisionReason.PROVIDER_UNAVAILABLE,
+            DecisionReason.PROVIDER_CONTRACT_VIOLATION,
+        }:
+            raise AuthMateUnavailableError(decision=decision)
+        raise AuthorizationDeniedError(decision)
+
+    async def aclose(self) -> None:
+        """Drain entered calls and close owned providers once in reverse order."""
+
+        async with self._condition:
+            if self._shutdown_task is None:
+                self._state = "closing"
+                self._shutdown_task = asyncio.create_task(self._shutdown())
+            task = self._shutdown_task
+        await asyncio.shield(task)
+
+    async def _authorize_inner(
+        self,
+        *,
+        context: AccessContext,
+        action: str,
+        resource: ResourceRef | None,
+    ) -> AuthorizationDecision:
+        if not isinstance(context, AccessContext):
+            raise InvalidAuthorizationRequestError()
+        if resource is not None and not isinstance(resource, ResourceRef):
+            raise InvalidAuthorizationRequestError()
+        try:
+            valid_action = validate_action(action)
+        except (ValidationError, TypeError, ValueError) as exc:
+            raise InvalidAuthorizationRequestError() from exc
+
+        if context.effective is not None:
+            return self._deny(valid_action, resource, DecisionReason.DELEGATION_NOT_SUPPORTED)
+
+        try:
+            record = await self._call_provider(
+                lambda: self._principal_provider.get_principal(context.actor),
+            )
+        except _ProviderUnavailable:
+            return self._deny(valid_action, resource, DecisionReason.PROVIDER_UNAVAILABLE)
+
+        if record is None:
+            return self._deny(valid_action, resource, DecisionReason.PRINCIPAL_NOT_FOUND)
+        if not isinstance(record, PrincipalRecord):
+            return self._deny(
+                valid_action,
+                resource,
+                DecisionReason.PROVIDER_CONTRACT_VIOLATION,
+            )
+        try:
+            record = PrincipalRecord.model_validate(record.model_dump(mode="python"))
+        except Exception as exc:
+            del exc
+            return self._deny(valid_action, resource, DecisionReason.PROVIDER_CONTRACT_VIOLATION)
+        if record.ref != context.actor:
+            return self._deny(
+                valid_action,
+                resource,
+                DecisionReason.PROVIDER_CONTRACT_VIOLATION,
+            )
+        now = datetime.now(UTC)
+        if not record.enabled:
+            return self._deny(valid_action, resource, DecisionReason.PRINCIPAL_DISABLED)
+        if record.expires_at is not None and record.expires_at <= now:
+            return self._deny(valid_action, resource, DecisionReason.PRINCIPAL_EXPIRED)
+
+        try:
+            decision = await self._call_provider(
+                lambda: self._authorization_provider.authorize(
+                    principal=record, action=valid_action, resource=resource
+                ),
+            )
+        except _ProviderUnavailable:
+            return self._deny(valid_action, resource, DecisionReason.PROVIDER_UNAVAILABLE)
+
+        if not isinstance(decision, AuthorizationDecision):
+            return self._deny(
+                valid_action,
+                resource,
+                DecisionReason.PROVIDER_CONTRACT_VIOLATION,
+            )
+        try:
+            decision = AuthorizationDecision.model_validate(decision.model_dump(mode="python"))
+        except Exception as exc:
+            del exc
+            return self._deny(valid_action, resource, DecisionReason.PROVIDER_CONTRACT_VIOLATION)
+        if decision.action != valid_action or decision.resource != resource:
+            return self._deny(
+                valid_action,
+                resource,
+                DecisionReason.PROVIDER_CONTRACT_VIOLATION,
+            )
+        return decision
+
+    async def _call_provider(self, operation: Callable[[], Awaitable[T]]) -> T:
+        try:
+            awaitable = operation()
+            async with asyncio.timeout(self._timeout):
+                return await awaitable
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            raise _ProviderUnavailable() from exc
+
+    @staticmethod
+    def _deny(
+        action: str,
+        resource: ResourceRef | None,
+        reason: DecisionReason,
+    ) -> AuthorizationDecision:
+        return AuthorizationDecision(
+            allowed=False,
+            reason=reason,
+            action=action,
+            resource=resource,
+        )
+
+    async def _enter_operation(self) -> None:
+        async with self._condition:
+            if self._state != "open":
+                raise AuthMateClosedError()
+            self._in_flight += 1
+
+    async def _exit_operation(self) -> None:
+        async with self._condition:
+            self._in_flight -= 1
+            if self._state == "closing" and self._in_flight == 0:
+                self._condition.notify_all()
+
+    async def _shutdown(self) -> None:
+        async with self._condition:
+            while self._in_flight:
+                await self._condition.wait()
+
+        errors: list[Exception] = []
+        seen: set[int] = set()
+        for provider in (self._authorization_provider, self._principal_provider):
+            provider_id = id(provider)
+            if provider_id in seen:
+                continue
+            seen.add(provider_id)
+            try:
+                await provider.aclose()
+            except Exception as exc:
+                errors.append(exc)
+
+        async with self._condition:
+            self._state = "closed"
+            self._condition.notify_all()
+        if errors:
+            raise ExceptionGroup("AuthMate provider cleanup failed", errors)
+
+
+class _ProviderUnavailable(Exception):
+    """Private sentinel that prevents provider text from reaching public errors."""
+
+
+__all__ = ["AuthMate"]

authmate-0.1.0.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: authmate
+Version: 0.1.0
+Summary: FastAPI-native identity and authorization contracts
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.11
+Requires-Dist: fastapi<1,>=0.140
+Requires-Dist: pydantic<3,>=2.12
+Description-Content-Type: text/markdown
+
+# AuthMate
+
+AuthMate is a provider-neutral authorization boundary for Python services. Version
+0.1.0 is a stateless contract preview: it validates shared values, coordinates
+principal and authorization providers, and supplies a small FastAPI adapter. It
+does not authenticate requests, persist data, implement RBAC, manage credentials,
+or provide a production-readiness guarantee.
+
+> Independent by default, composable by contract.
+
+## Status
+
+The phase 0.1 runtime is implemented under `src/authmate`. Read the
+[quickstart](docs/quickstart.md) and [planning index](docs/plans/README.md) for the
+public contract and release boundary.
+
+## Supported runtime
+
+Python 3.11 through 3.14. Install this checkout with `uv sync --group dev`.
+AuthMate is distributed under the [MIT License](LICENSE).
+
+## Quick start
+
+Providers are host-owned and implement the protocols in `authmate.protocols`.
+The service calls the principal provider first, then the authorization provider
+only for an enabled, non-expired principal.
+
+```python
+from uuid import uuid4
+from authmate import (
+    AccessContext,
+    AuthMate,
+    AuthorizationDecision,
+    PrincipalKind,
+    PrincipalRecord,
+    PrincipalRef,
+)
+
+actor = PrincipalRef(id=uuid4(), kind=PrincipalKind.USER)
+
+
+class Principals:
+    async def get_principal(self, ref):
+        return PrincipalRecord(ref=ref, display_name="Ada", enabled=True)
+
+    async def aclose(self):
+        pass
+
+
+class Policy:
+    async def authorize(self, *, principal, action, resource):
+        return AuthorizationDecision(
+            allowed=True, reason="allowed", action=action, resource=resource
+        )
+
+    async def aclose(self):
+        pass
+
+
+async def check_request():
+    service = AuthMate(principal_provider=Principals(), authorization_provider=Policy())
+    try:
+        return await service.require(context=AccessContext(actor=actor), action="report.read")
+    finally:
+        await service.aclose()
+```
+
+See [the phase 0.1 quickstart](docs/quickstart.md) for FastAPI integration,
+provider contracts, lifecycle behavior, and deliberate non-goals.
+
+## Development
+
+```sh
+uv sync --frozen --group dev
+uv run ruff format --check .
+uv run ruff check .
+uv run mypy --strict src/authmate tests
+uv run pytest --cov=authmate --cov-branch --cov-fail-under=95
+uv build
+uv run twine check dist/*
+```
+
+## Planned MVP
+
+- Users, operator provisioning, opaque SQL-backed browser sessions, and revocation.
+- Service accounts, revocable API tokens, and generic delegated identity.
+- Exact RBAC scopes, FastAPI dependencies, and Python service APIs.
+- Credential metadata, exact secret-use grants, and approved environment references.
+- Durable SQL audit, rate limiting, CSRF protection, and explicit recovery procedures.
+- Typed public contracts, controlled model/provider extensions, and reviewed migrations.
+
+PostgreSQL is the production reference; SQLite supports local development. No Redis,
+broker, external identity service, or external secret manager is required. Encrypted
+SQL secret storage, federation, tenancy, and richer extensions have later release gates.
+
+## Architecture principles
+
+- AuthMate owns its security semantics and public contracts; consumers adapt to them.
+- Mandatory service checks remain authoritative with custom providers.
+- Pydantic public contracts are separate from SQLModel/SQLAlchemy persistence.
+- FastAPI composition uses explicit DI, lifespan, security, and OpenAPI integration.
+- Core requires SQL-backed state, not process-local caches or additional services.
+
+Hedron, ShuETL, and other applications may build optional adapters against AuthMate.
+Core contains no consumer workflow records, callbacks, domain imports, or release
+dependencies. Consumer-owned compatibility tests establish supported combinations.
+See [Consumer Contracts](docs/plans/CONSUMER_CONTRACTS.md) and
+[MVP gates](docs/plans/MVP.md).

authmate-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+authmate/__init__.py,sha256=zL-5PT8tEkKr_V7AgQ0Qk54NaG2kIVyTvG4BdZdTpHE,1275
+authmate/errors.py,sha256=kc1rQxYHBLiNlqLMe2mkZt2w-Wqdxpf1AcA76qqXuUY,1993
+authmate/fastapi.py,sha256=2zO8vt8311EC-oc8__TWDGDTfHyKAnEiKVnzFLh_k4s,3817
+authmate/models.py,sha256=ZV9vEH-xmgvVDedB7ER3ureCBZJqpUUElBNo7j-B9Y0,10497
+authmate/protocols.py,sha256=ky4iv9rgnaCaw-ZqDhKIiwibDcjoTo7zTBfppqnHZ9Q,1865
+authmate/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+authmate/secrets.py,sha256=of_SyPj9DQeKEtD3BNFfUqxwhee4Ew0NGwgXqGDyAhk,1471
+authmate/service.py,sha256=RP1EklWWlauMOo-q_WYocXEBdgpmIHCyb5NuyaglxC4,8863
+authmate-0.1.0.dist-info/METADATA,sha256=AtVJ_hkOAe3Y9mcXvjcTJ3Lv8epcikytrbM4QG8Vv2E,4567
+authmate-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+authmate-0.1.0.dist-info/licenses/LICENSE,sha256=p5xydNm1apImfFfPitmKIURubF492JXU5y13fRbq7rE,1078
+authmate-0.1.0.dist-info/RECORD,,

authmate-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

authmate-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AuthMate contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.