auth-guide 0.5.0__py3-none-any.whl

auth_guide/accounts/passwords.py

@@ -0,0 +1,172 @@
+"""Account-password operations behind an owned asynchronous boundary."""
+
+from __future__ import annotations
+
+import asyncio
+import queue
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TypeVar, cast
+
+from argon2 import PasswordHasher, Type, extract_parameters
+from argon2.exceptions import InvalidHashError, VerificationError
+
+__all__ = ["PasswordOperations", "PasswordOperationsClosedError", "PasswordOperationsError"]
+
+ResultT = TypeVar("ResultT")
+
+
+class PasswordOperationsError(RuntimeError):
+    """Base error for the password operations boundary."""
+
+
+class PasswordOperationsClosedError(PasswordOperationsError):
+    """Raised when password work is requested outside the worker lifecycle."""
+
+
+@dataclass(slots=True)
+class _Outcome:
+    value: object | None = None
+    error: BaseException | None = None
+
+
+@dataclass(slots=True)
+class _Call:
+    operation: Callable[[], object]
+    loop: asyncio.AbstractEventLoop
+    completion: asyncio.Future[_Outcome]
+
+
+@dataclass(slots=True)
+class _Stop:
+    loop: asyncio.AbstractEventLoop
+    completion: asyncio.Future[None]
+
+
+class PasswordOperations:
+    """Run Argon2id work through one owned serial worker."""
+
+    def __init__(self) -> None:
+        self._hasher = PasswordHasher(
+            time_cost=3,
+            memory_cost=64 * 1024,
+            parallelism=4,
+            hash_len=32,
+            salt_len=16,
+            type=Type.ID,
+        )
+        self._calls: queue.Queue[_Call | _Stop] = queue.Queue()
+        self._worker: threading.Thread | None = None
+        self._closed = False
+        self._shutdown_completion: asyncio.Future[None] | None = None
+
+    async def __aenter__(self) -> "PasswordOperations":
+        await self.start()
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def start(self) -> None:
+        """Start the password operations worker."""
+        if self._closed:
+            raise PasswordOperationsClosedError("Password operations worker is closed")
+        if self._worker is None:
+            self._worker = threading.Thread(target=self._run, name="auth-guide-passwords", daemon=True)
+            self._worker.start()
+
+    async def verify_unknown(self, password: str) -> None:
+        """Perform an equivalent password verification for an absent account."""
+        await self.verify(
+            "$argon2id$v=19$m=65536,t=3,p=4$MDEyMzQ1Njc4OWFiY2RlZg$PjSoTrIgSEYn0GfJ1m5dwCJmQtOaMjFFTIwHP6GJwrs",
+            password,
+        )
+
+    async def aclose(self) -> None:
+        """Stop through a shared cancellation-safe shutdown operation."""
+        completion = self._shutdown_completion
+        if completion is None:
+            loop = asyncio.get_running_loop()
+            completion = loop.create_future()
+            self._shutdown_completion = completion
+            self._closed = True
+            worker = self._worker
+            if worker is None:
+                completion.set_result(None)
+            elif worker.is_alive():
+                self._calls.put(_Stop(loop, completion))
+            else:
+                completion.set_exception(PasswordOperationsError("Password operations worker stopped unexpectedly"))
+        await asyncio.shield(completion)
+
+    async def hash(self, password: str) -> str:
+        """Create one current-policy Argon2id verifier."""
+        return await self._call(lambda: self._hasher.hash(password))
+
+    async def verify(self, verifier: str, password: str) -> bool:
+        """Verify a password against its fixed-policy Argon2id verifier."""
+
+        def operation() -> bool:
+            try:
+                return self._hasher.verify(verifier, password)
+            except (InvalidHashError, VerificationError):
+                return False
+
+        return await self._call(operation)
+
+    @staticmethod
+    def is_current_verifier(verifier: str) -> bool:
+        """Report whether a verifier uses the provider's fixed Argon2id policy."""
+        try:
+            parameters = extract_parameters(verifier)
+        except InvalidHashError:
+            return False
+        return (
+            parameters.type is Type.ID
+            and parameters.version == 19
+            and parameters.time_cost == 3
+            and parameters.memory_cost == 64 * 1024
+            and parameters.parallelism == 4
+            and parameters.hash_len == 32
+            and parameters.salt_len == 16
+        )
+
+    async def _call(self, operation: Callable[[], ResultT]) -> ResultT:
+        worker = self._worker
+        if self._closed or worker is None or not worker.is_alive():
+            raise PasswordOperationsClosedError("Password operations worker is not running")
+        loop = asyncio.get_running_loop()
+        completion: asyncio.Future[_Outcome] = loop.create_future()
+        self._calls.put(_Call(operation, loop, completion))
+        outcome = await asyncio.shield(completion)
+        if outcome.error is not None:
+            raise outcome.error
+        return cast(ResultT, outcome.value)
+
+    def _run(self) -> None:
+        stop: _Stop | None = None
+        try:
+            while True:
+                item = self._calls.get()
+                if isinstance(item, _Stop):
+                    stop = item
+                    return
+                try:
+                    outcome = _Outcome(value=item.operation())
+                except BaseException as error:
+                    outcome = _Outcome(error=error)
+                item.loop.call_soon_threadsafe(_complete_call, item.completion, outcome)
+        finally:
+            if stop is not None:
+                stop.loop.call_soon_threadsafe(_complete_shutdown, stop.completion)
+
+
+def _complete_call(completion: asyncio.Future[_Outcome], outcome: _Outcome) -> None:
+    if not completion.done():
+        completion.set_result(outcome)
+
+
+def _complete_shutdown(completion: asyncio.Future[None]) -> None:
+    if not completion.done():
+        completion.set_result(None)

auth_guide/accounts/tokens.py

@@ -0,0 +1,41 @@
+"""Opaque account access-token generation and verification."""
+
+import secrets
+from dataclasses import dataclass
+from hashlib import sha256
+
+from auth_guide.accounts.models import AccountTokenRecord
+
+
+@dataclass(frozen=True)
+class NewAccountToken:
+    """A raw token available only while its issuing operation completes."""
+
+    raw_value: str
+    verifier: str
+
+
+async def generate_account_token() -> NewAccountToken:
+    """Generate one opaque 256-bit account token and its stored verifier."""
+    raw_value = f"agt_{secrets.token_urlsafe(32)}"
+    return NewAccountToken(raw_value=raw_value, verifier=hash_account_token(raw_value))
+
+
+async def verify_account_token(raw_value: str, verifier: str) -> bool:
+    """Compare a presented raw token with its persisted verifier."""
+    return secrets.compare_digest(hash_account_token(raw_value), verifier)
+
+
+async def resolve_account_token(raw_value: str) -> AccountTokenRecord | None:
+    """Resolve a presented bearer to its active account token, if any."""
+    if not raw_value.startswith("agt_"):
+        return None
+    token = await AccountTokenRecord.all().select_related("account").get_or_none(verifier=hash_account_token(raw_value))
+    if token is None or not token.account.is_active:
+        return None
+    return token
+
+
+def hash_account_token(raw_value: str) -> str:
+    """Return the SHA-256 verifier for a raw account token."""
+    return sha256(raw_value.encode("utf-8")).hexdigest()

auth_guide/bootstrap.py

@@ -0,0 +1,76 @@
+"""Local first-administrator initialisation for a provider configuration root."""
+
+from __future__ import annotations
+
+import secrets
+from dataclasses import dataclass
+from pathlib import Path
+
+from anyio import Path as AsyncPath
+
+from auth_guide.accounts import (
+    AccountRecord,
+    AccountStore,
+    AccountStoreError,
+    AccountTokenRecord,
+    Grant,
+    generate_account_token,
+)
+from auth_guide.accounts.models import normalise_account_email
+from auth_guide.secrets import PlatformSecretProvider
+
+
+@dataclass(frozen=True, slots=True)
+class InitialProviderCredentials:
+    """The once-only credentials produced by local provider initialisation."""
+
+    password: str
+    token: str
+
+
+async def initialise_provider(
+    config_dir: str | Path | AsyncPath,
+    email: str,
+    remove_orphan_key: bool = False,
+) -> InitialProviderCredentials:
+    """Create the encrypted store and first administrator only through local CLI setup."""
+    try:
+        email_values = await normalise_account_email(email)
+    except ValueError as error:
+        raise AccountStoreError(str(error)) from error
+
+    async with PlatformSecretProvider("auth-guide") as secrets_provider:
+        store = AccountStore(config_dir, secrets_provider)
+        initialised = False
+        try:
+            if remove_orphan_key:
+                await store.remove_orphan_database_key()
+            await store.initialise()
+            initialised = True
+            password = _generate_initial_password()
+            account = AccountRecord(
+                email=email_values["email"],
+                email_comparison=email_values["email_comparison"],
+                grants=[Grant.GUIDE_ADMIN, Grant.ACCOUNTS_READ, Grant.ACCOUNTS_MANAGE, Grant.TOKENS_MANAGE],
+            )
+            await store.create_account(account, password)
+            issued_token = await generate_account_token()
+            await AccountTokenRecord.create(
+                account=account,
+                label="admin",
+                verifier=issued_token.verifier,
+                scopes=[Grant.ACCOUNTS_READ, Grant.ACCOUNTS_MANAGE, Grant.TOKENS_MANAGE],
+            )
+            return InitialProviderCredentials(password=password, token=issued_token.raw_value)
+        except BaseException:
+            if initialised:
+                await store.rollback_initialisation()
+            raise
+        finally:
+            await store.aclose()
+
+
+def _generate_initial_password() -> str:
+    """Generate the fixed 12-character printable-ASCII initial password."""
+    printable_ascii = "".join(chr(value) for value in range(33, 127))
+    return "".join(secrets.choice(printable_ascii) for _ in range(12))

auth_guide/certificate_operations.py

@@ -0,0 +1,129 @@
+"""Owned asynchronous boundary for synchronous certificate operations."""
+
+from __future__ import annotations
+
+import asyncio
+import queue
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TypeVar, cast
+
+__all__ = ["CertificateOperations", "CertificateOperationsClosedError", "CertificateOperationsError"]
+
+ResultT = TypeVar("ResultT")
+
+
+class CertificateOperationsError(RuntimeError):
+    """Base error for the certificate operations boundary."""
+
+
+class CertificateOperationsClosedError(CertificateOperationsError):
+    """Raised when operations are attempted outside the worker lifecycle."""
+
+
+@dataclass(slots=True)
+class _Outcome:
+    value: object | None = None
+    error: BaseException | None = None
+
+
+@dataclass(slots=True)
+class _Call:
+    operation: Callable[[], object]
+    loop: asyncio.AbstractEventLoop
+    completion: asyncio.Future[_Outcome]
+
+
+@dataclass(slots=True)
+class _Stop:
+    loop: asyncio.AbstractEventLoop
+    completion: asyncio.Future[None]
+
+
+class CertificateOperations:
+    """Run synchronous cryptographic work through one owned serial worker."""
+
+    def __init__(self) -> None:
+        self._calls: queue.Queue[_Call | _Stop] = queue.Queue()
+        self._worker: threading.Thread | None = None
+        self._closed = False
+        self._shutdown_completion: asyncio.Future[None] | None = None
+
+    @property
+    def is_running(self) -> bool:
+        """Whether the worker is accepting certificate operations."""
+        return self._worker is not None and self._worker.is_alive() and not self._closed
+
+    async def __aenter__(self) -> "CertificateOperations":
+        await self.start()
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def start(self) -> None:
+        """Start the certificate operations worker."""
+        if self._closed:
+            raise CertificateOperationsClosedError("Certificate operations worker is closed")
+        if self._worker is None:
+            self._worker = threading.Thread(target=self._run, name="auth-guide-certificates", daemon=True)
+            self._worker.start()
+
+    async def aclose(self) -> None:
+        """Stop through a shared cancellation-safe shutdown operation."""
+        completion = self._shutdown_completion
+        if completion is None:
+            loop = asyncio.get_running_loop()
+            completion = loop.create_future()
+            self._shutdown_completion = completion
+            self._closed = True
+            worker = self._worker
+            if worker is None:
+                completion.set_result(None)
+            elif worker.is_alive():
+                self._calls.put(_Stop(loop, completion))
+            else:
+                completion.set_exception(
+                    CertificateOperationsError("Certificate operations worker stopped unexpectedly")
+                )
+        await asyncio.shield(completion)
+
+    async def call(self, operation: Callable[[], ResultT]) -> ResultT:
+        """Run one synchronous certificate operation without blocking the caller."""
+        if not self.is_running:
+            raise CertificateOperationsClosedError("Certificate operations worker is not running")
+        loop = asyncio.get_running_loop()
+        completion: asyncio.Future[_Outcome] = loop.create_future()
+        self._calls.put(_Call(operation, loop, completion))
+        outcome = await asyncio.shield(completion)
+        if outcome.error is not None:
+            raise outcome.error
+        return cast(ResultT, outcome.value)
+
+    def _run(self) -> None:
+        stop: _Stop | None = None
+        try:
+            while True:
+                item = self._calls.get()
+                if isinstance(item, _Stop):
+                    stop = item
+                    return
+                try:
+                    outcome = _Outcome(value=item.operation())
+                except BaseException as error:
+                    outcome = _Outcome(error=error)
+                item.loop.call_soon_threadsafe(_complete_call, item.completion, outcome)
+        finally:
+            if stop is not None:
+                stop.loop.call_soon_threadsafe(_complete_shutdown, stop.completion)
+
+
+def _complete_call(completion: asyncio.Future[_Outcome], outcome: _Outcome) -> None:
+    if not completion.done():
+        completion.set_result(outcome)
+
+
+def _complete_shutdown(completion: asyncio.Future[None]) -> None:
+    if not completion.done():
+        completion.set_result(None)