pyfastauth 0.1.0__py3-none-any.whl

fastauth/__init__.py

@@ -0,0 +1,29 @@
+"""fastauth -- authentication and authorization for FastAPI.
+
+Add working authentication to an existing application in three lines::
+
+    from fastapi import FastAPI
+    from fastauth import FastAuth
+
+    app = FastAPI()
+    auth = FastAuth(config="auth.yaml")
+    auth.install(app)
+
+The public surface is deliberately small: the four names below, plus
+``fastauth.ownership`` for per-user data isolation. Everything else is an
+implementation detail and may change without a major version bump.
+"""
+
+from fastauth.config.models import AuthConfig
+from fastauth.core import FastAuth
+from fastauth.types import AuthContext, AuthUser
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AuthConfig",
+    "AuthContext",
+    "AuthUser",
+    "FastAuth",
+    "__version__",
+]

fastauth/authorization/__init__.py

@@ -0,0 +1,31 @@
+"""Authorization: scope matching and role resolution (spec section 15).
+
+Everything in this package is pure. It takes declared roles and held scopes and
+answers questions about them; it never reads configuration files, touches the
+database, or logs. That is what makes the matching rules exhaustively testable,
+which spec 15.2 explicitly requires.
+"""
+
+from __future__ import annotations
+
+from fastauth.authorization.roles import RoleRegistry
+from fastauth.authorization.scopes import (
+    GLOBAL_WILDCARD,
+    SCOPE_PATTERN,
+    has_scope,
+    is_valid_scope,
+    matches,
+    missing_scopes,
+    scope_matches,
+)
+
+__all__ = [
+    "GLOBAL_WILDCARD",
+    "SCOPE_PATTERN",
+    "RoleRegistry",
+    "has_scope",
+    "is_valid_scope",
+    "matches",
+    "missing_scopes",
+    "scope_matches",
+]

fastauth/authorization/roles.py

@@ -0,0 +1,210 @@
+"""Role inheritance resolution (spec section 15.3).
+
+Roles are declared in ``auth.yaml``; user-role assignments live in the database
+(spec 15.1). This module owns the step between the two: turning declared roles
+into the flat scope sets that authorization checks actually use.
+
+The whole resolution happens once, at configuration load time, and produces an
+immutable :class:`RoleRegistry`. Nothing resolves inheritance per request --
+that would make the cost of a deep hierarchy a per-request cost, and would move
+cycle detection into the request path where it can only be reported as a 500.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+
+from fastauth.exceptions import RoleCycleError, UnknownRoleError
+from fastauth.types import RoleDefinition, RoleName, Scope
+
+
+@dataclass(frozen=True, slots=True)
+class RoleRegistry:
+    """The resolved role graph: declared roles plus their inherited scopes.
+
+    Immutable and self-contained, so it can be built once at startup and shared
+    by every request without locking. Construct it with
+    :meth:`from_definitions`; the constructor takes already-resolved data and
+    performs no validation of its own.
+    """
+
+    definitions: Mapping[RoleName, RoleDefinition]
+    """The declarations exactly as they appeared in ``auth.yaml``."""
+
+    resolved_scopes: Mapping[RoleName, frozenset[Scope]]
+    """Per role: its own scopes unioned with every ancestor's, deduplicated."""
+
+    ancestry: Mapping[RoleName, tuple[RoleName, ...]]
+    """Per role: itself plus every role it inherits from, transitively, sorted."""
+
+    inheritance_enabled: bool = True
+    """Mirrors ``authorization.role_inheritance_enabled``. When ``False`` the
+    ``inherits`` lists were validated but deliberately not applied."""
+
+    @classmethod
+    def from_definitions(
+        cls,
+        definitions: Mapping[RoleName, RoleDefinition],
+        *,
+        inheritance_enabled: bool = True,
+    ) -> RoleRegistry:
+        """Resolve inheritance and build a registry.
+
+        Parents are validated even when ``inheritance_enabled`` is ``False``: a
+        dangling parent or a cycle is a mistake in the file regardless of
+        whether the feature that reads it is switched on, and it would become a
+        surprise failure the day someone enables inheritance.
+
+        Args:
+            definitions: Declared roles, keyed by name.
+            inheritance_enabled: When ``False``, each role resolves to exactly
+                its own scopes.
+
+        Returns:
+            An immutable registry.
+
+        Raises:
+            UnknownRoleError: A role inherits from a name that is not declared.
+            RoleCycleError: Inheritance contains a cycle; the error carries the
+                actual cycle path, e.g. ``a -> b -> a``.
+        """
+        _reject_unknown_parents(definitions)
+        order = _topological_order(definitions)
+
+        resolved: dict[RoleName, frozenset[Scope]] = {}
+        ancestry: dict[RoleName, tuple[RoleName, ...]] = {}
+        for name in order:
+            definition = definitions[name]
+            scopes = set(definition.scopes)
+            lineage = {name}
+            if inheritance_enabled:
+                for parent in definition.inherits:
+                    # Parents precede children in `order`, so their resolution
+                    # is already final -- one pass, no fixed-point iteration.
+                    scopes |= resolved[parent]
+                    lineage |= set(ancestry[parent])
+            resolved[name] = frozenset(scopes)
+            ancestry[name] = tuple(sorted(lineage))
+
+        return cls(
+            definitions=dict(definitions),
+            resolved_scopes=resolved,
+            ancestry=ancestry,
+            inheritance_enabled=inheritance_enabled,
+        )
+
+    def known(self, role: str) -> bool:
+        """Report whether ``role`` is declared in the configuration.
+
+        Args:
+            role: A role name, typically one read from the database.
+
+        Returns:
+            ``True`` if the role exists in ``auth.yaml``.
+        """
+        return RoleName(role) in self.definitions
+
+    def scopes_for(self, roles: Iterable[str]) -> frozenset[Scope]:
+        """Union the resolved scopes of every named role.
+
+        Roles that are not declared are ignored rather than raising. A role row
+        can outlive its YAML declaration -- someone deletes ``reviewer`` from
+        the file while users still carry it -- and the safe reading of an
+        undeclared role is "grants nothing", not "crash every request that
+        user makes".
+
+        Args:
+            roles: Role names, typically from the user's database rows.
+
+        Returns:
+            Every scope those roles grant, deduplicated.
+        """
+        scopes: set[Scope] = set()
+        for role in roles:
+            scopes |= self.resolved_scopes.get(RoleName(role), frozenset())
+        return frozenset(scopes)
+
+    def effective_roles(self, roles: Iterable[str]) -> tuple[RoleName, ...]:
+        """Expand role names to include everything they inherit.
+
+        Sorted and deduplicated so that the ``roles`` claim of an access token
+        is stable: two tokens issued for the same user must not differ only in
+        list order, or byte-comparing them becomes meaningless in tests and
+        logs. Undeclared roles are dropped, for the reason given on
+        :meth:`scopes_for`.
+
+        Args:
+            roles: Directly assigned role names.
+
+        Returns:
+            The assigned roles plus their ancestors, sorted.
+        """
+        effective: set[RoleName] = set()
+        for role in roles:
+            effective |= set(self.ancestry.get(RoleName(role), ()))
+        return tuple(sorted(effective))
+
+    @property
+    def role_names(self) -> tuple[RoleName, ...]:
+        """Every declared role name, sorted."""
+        return tuple(sorted(self.definitions))
+
+
+def _reject_unknown_parents(definitions: Mapping[RoleName, RoleDefinition]) -> None:
+    """Fail startup when a role inherits from something undeclared (spec 15.3)."""
+    for name, definition in definitions.items():
+        for parent in definition.inherits:
+            if parent not in definitions:
+                raise UnknownRoleError(
+                    f"role {name!r} inherits from undeclared role {parent!r}",
+                    yaml_path=f"roles.{name}.inherits",
+                )
+
+
+def _topological_order(
+    definitions: Mapping[RoleName, RoleDefinition],
+) -> tuple[RoleName, ...]:
+    """Order roles so every parent precedes its children.
+
+    Iterative depth-first search rather than recursion: the path stack is what
+    lets the cycle error name the actual cycle instead of merely reporting that
+    one exists.
+
+    Raises:
+        RoleCycleError: with the offending chain, e.g. ``["a", "b", "a"]``.
+    """
+    order: list[RoleName] = []
+    finished: set[RoleName] = set()
+    path: list[RoleName] = []
+    on_path: set[RoleName] = set()
+
+    # Roots are visited in sorted order so that the resulting order -- and
+    # therefore any error message derived from it -- is reproducible.
+    for root in sorted(definitions):
+        if root in finished:
+            continue
+        # Each frame is (role, index of the next parent to descend into).
+        stack: list[tuple[RoleName, int]] = [(root, 0)]
+        while stack:
+            name, cursor = stack[-1]
+            if cursor == 0:
+                if name in finished:
+                    stack.pop()
+                    continue
+                if name in on_path:
+                    raise RoleCycleError([*path[path.index(name) :], name])
+                path.append(name)
+                on_path.add(name)
+            parents = definitions[name].inherits
+            if cursor < len(parents):
+                stack[-1] = (name, cursor + 1)
+                stack.append((parents[cursor], 0))
+                continue
+            order.append(name)
+            finished.add(name)
+            on_path.discard(name)
+            path.pop()
+            stack.pop()
+
+    return tuple(order)

fastauth/authorization/scopes.py

@@ -0,0 +1,165 @@
+"""Scope matching (spec sections 15.2 and 6.6).
+
+The spec names three shapes -- exact (``contracts:read``), resource wildcard
+(``contracts:*``) and global (``*``) -- and requires matching to be
+"deterministic and unit tested". It does not define the algorithm, so this
+module does, once, for the whole package:
+
+1.  A scope is a ``:``-separated sequence of segments.
+2.  Granted and required segments are compared pairwise, left to right.
+3.  A granted ``*`` in a non-final position matches exactly one segment
+    (``*:read`` grants read on any resource).
+4.  A granted ``*`` in the *final* position matches one or more remaining
+    segments, so ``contracts:*`` grants ``contracts:read`` and also
+    ``contracts:findings:read``.
+5.  The bare global ``*`` grants everything.
+6.  A *required* wildcard demands wildcard-or-broader authority: ``admin:*`` is
+    satisfied by ``*`` or ``admin:*``, but never by ``admin:read``. Requiring
+    ``admin:*`` (spec 6.6) means "full authority over admin", and a holder of
+    one narrow admin scope does not have that.
+
+Consequence of rules 3 and 4: ``contracts:*`` does not match the bare scope
+``contracts``. The wildcard stands for segments that exist; a route requiring
+``contracts`` is asking for a different, coarser permission.
+
+Every function here is pure: no configuration, no I/O, no logging. Mid-string
+wildcards such as ``con*racts`` are rejected at configuration load time by
+:func:`is_valid_scope`, so matching never has to consider them.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from typing import Final
+
+from fastauth.types import Scope, ScopeMatch
+
+SEGMENT_SEPARATOR: Final = ":"
+WILDCARD: Final = "*"
+GLOBAL_WILDCARD: Final[Scope] = Scope("*")
+
+SCOPE_PATTERN: Final[re.Pattern[str]] = re.compile(r"\A[A-Za-z0-9_:*-]+\Z")
+"""Approved characters for a scope string (spec section 7.2)."""
+
+
+def is_valid_scope(scope: str) -> bool:
+    """Report whether ``scope`` is well formed.
+
+    Two rules beyond the character set: no empty segments (``a::b`` and a
+    leading or trailing ``:``), and a ``*`` may only appear as a whole segment.
+    ``con*racts`` is rejected here rather than being given a meaning, because a
+    partial-match wildcard in an authorization grant is far more likely to be a
+    typo than an intention.
+
+    Args:
+        scope: The candidate scope string, exactly as written in ``auth.yaml``.
+
+    Returns:
+        ``True`` if the scope is usable by :func:`scope_matches`.
+    """
+    if not scope or not SCOPE_PATTERN.match(scope):
+        return False
+    return all(
+        segment and (WILDCARD not in segment or segment == WILDCARD)
+        for segment in scope.split(SEGMENT_SEPARATOR)
+    )
+
+
+def scope_matches(granted: str, required: str) -> bool:
+    """Report whether one granted scope satisfies one required scope.
+
+    Args:
+        granted: A scope the user holds, e.g. ``"contracts:*"``.
+        required: A scope the route demands, e.g. ``"contracts:read"``.
+
+    Returns:
+        ``True`` when ``granted`` covers ``required`` under the rules in the
+        module docstring.
+    """
+    if granted == GLOBAL_WILDCARD:
+        return True
+
+    granted_segments = granted.split(SEGMENT_SEPARATOR)
+    required_segments = required.split(SEGMENT_SEPARATOR)
+    last = len(granted_segments) - 1
+
+    for position, segment in enumerate(granted_segments):
+        if position >= len(required_segments):
+            # The grant is more specific than the requirement, e.g. granted
+            # "contracts:read:own" against required "contracts:read".
+            return False
+        if segment == WILDCARD:
+            if position == last:
+                return True  # trailing wildcard absorbs every remaining segment
+            continue  # segment wildcard consumes exactly one segment
+        if segment != required_segments[position]:
+            # Also the branch that rejects a literal grant against a required
+            # wildcard: "read" != "*".
+            return False
+
+    return len(granted_segments) == len(required_segments)
+
+
+def has_scope(granted: Iterable[str], required: str) -> bool:
+    """Report whether any held scope satisfies ``required``.
+
+    Args:
+        granted: Every scope the user holds, in any order.
+        required: The scope the route demands.
+
+    Returns:
+        ``True`` if at least one granted scope matches.
+    """
+    return any(scope_matches(held, required) for held in granted)
+
+
+def missing_scopes(
+    granted: Iterable[str],
+    required: Iterable[str],
+) -> tuple[Scope, ...]:
+    """List the required scopes that ``granted`` does not satisfy.
+
+    Returned in the order the route declared them, so the structured
+    authorization-denied log (spec 15.5) reads the same way the route does. The
+    public 403 body stays generic; only internal logs receive this detail.
+
+    Args:
+        granted: Every scope the user holds.
+        required: The scopes the route demands.
+
+    Returns:
+        The unsatisfied scopes, possibly empty.
+    """
+    held = tuple(granted)
+    return tuple(Scope(scope) for scope in required if not has_scope(held, scope))
+
+
+def matches(
+    granted: Iterable[str],
+    required: Iterable[str],
+    match: ScopeMatch = "all",
+) -> bool:
+    """Evaluate a route's scope requirement against a user's scopes.
+
+    An empty requirement means "authenticated is enough" and returns ``True``
+    under either mode -- including ``match="any"``, where a strict reading of
+    "any" would return ``False``. Routes declare zero scopes to mean
+    authentication-only, and answering ``False`` there would lock out every such
+    route.
+
+    Args:
+        granted: Every scope the user holds.
+        required: The scopes the route demands.
+        match: ``"all"`` (default) requires every scope; ``"any"`` requires one.
+
+    Returns:
+        ``True`` when the requirement is satisfied.
+    """
+    required_scopes = tuple(required)
+    if not required_scopes:
+        return True
+    held = tuple(granted)
+    if match == "any":
+        return any(has_scope(held, scope) for scope in required_scopes)
+    return all(has_scope(held, scope) for scope in required_scopes)

fastauth/cli/__init__.py

@@ -0,0 +1,30 @@
+"""The ``fastauth`` command-line interface (spec section 17).
+
+The package is deliberately thin. Every command is a translation layer: it
+resolves ``--config``, calls one already-tested API in the layers below, and
+renders the result. No authentication, authorization or persistence logic lives
+here, which is why ``fastauth.cli`` sits at the very top of the import-linter
+layer contract and may import anything beneath it.
+
+One module per command group, each exposing ``register(app)``:
+
+============================  =========================================
+:mod:`fastauth.cli.init`      ``fastauth init``
+:mod:`fastauth.cli.config_cmd`  ``fastauth config validate``
+:mod:`fastauth.cli.secret`    ``fastauth secret generate``
+:mod:`fastauth.cli.doctor`    ``fastauth doctor``
+:mod:`fastauth.cli.database`  ``fastauth db ...``
+:mod:`fastauth.cli.users`     ``fastauth users ...``
+:mod:`fastauth.cli.sessions`  ``fastauth sessions ...``
+:mod:`fastauth.cli.routes`    ``fastauth routes``
+============================  =========================================
+
+Registration rather than a central command table is what let this be built
+without a single file that every command group has to edit.
+"""
+
+from __future__ import annotations
+
+from fastauth.cli.app import app, main
+
+__all__ = ["app", "main"]