auth-guide 0.5.0__py3-none-any.whl

auth_guide/__init__.py

@@ -0,0 +1,5 @@
+"""Local account and bearer-token service package.
+
+Runtime interfaces are deliberately deferred until the storage feasibility
+work selects the persistence approach.
+"""

auth_guide/__main__.py

@@ -0,0 +1,6 @@
+"""Module entry point for detached auth-guide server processes."""
+
+from auth_guide.cli import cli
+
+if __name__ == "__main__":
+    cli()

auth_guide/accounts/__init__.py

@@ -0,0 +1,322 @@
+"""Encrypted asynchronous provider account persistence."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import secrets
+from pathlib import Path
+from typing import Any
+
+from anyio import Path as AsyncPath
+from tortoise import Tortoise
+from tortoise.connection import get_connection
+from tortoise.migrations.api import migrate
+from tortoise.migrations.executor import MigrationExecutor
+
+from auth_guide.accounts.models import AccountRecord, AccountTokenRecord, Grant
+from auth_guide.accounts.passwords import PasswordOperations
+from auth_guide.accounts.tokens import (
+    NewAccountToken,
+    generate_account_token,
+    resolve_account_token,
+    verify_account_token,
+)
+from auth_guide.secrets import (
+    MissingSecretError,
+    PlatformSecretProvider,
+    SecretAlreadyExistsError,
+    SecretReference,
+)
+
+DATABASE_KEY_REFERENCE = SecretReference("auth-guide-database-key")
+DATABASE_FILENAME = "auth-guide.sqlite3"
+
+__all__ = [
+    "AccountRecord",
+    "AccountTokenRecord",
+    "AccountStore",
+    "AccountStoreError",
+    "DATABASE_FILENAME",
+    "Grant",
+    "NewAccountToken",
+    "generate_account_token",
+    "resolve_account_token",
+    "verify_account_token",
+]
+
+
+class AccountStoreError(RuntimeError):
+    """Base error for account-store lifecycle and persistence failures."""
+
+
+class AccountStore:
+    """Own the encrypted Tortoise connection and account-password operations."""
+
+    def __init__(self, config_dir: str | Path | AsyncPath, secrets_provider: PlatformSecretProvider) -> None:
+        self._config_dir = AsyncPath(config_dir)
+        self._secrets = secrets_provider
+        self._passwords = PasswordOperations()
+        self._database_key: bytes | None = None
+        self._started = False
+        self._migrated = False
+        self._initialised_here = False
+
+    async def __aenter__(self) -> "AccountStore":
+        await self.start()
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def start(self) -> None:
+        """Configure encrypted storage without applying database migrations."""
+        if self._started:
+            return
+        await self._config_dir.mkdir(parents=True, exist_ok=True)
+        self._database_key = await self._resolve_database_key()
+        await self._passwords.start()
+        try:
+            await Tortoise.init(
+                config=self._tortoise_config(),
+                init_connections=False,
+                _enable_global_fallback=True,
+            )
+            self._started = True
+        except BaseException:
+            await self._passwords.aclose()
+            self._database_key = None
+            raise
+
+    async def initialise(self) -> None:
+        """Explicitly create a new encrypted account database from user migrations."""
+        if self._started:
+            raise AccountStoreError("Account store is already started")
+        await self._config_dir.mkdir(parents=True, exist_ok=True)
+        if await self._database_path.exists():
+            raise AccountStoreError("Account database already exists")
+        if not await self._has_user_migrations():
+            raise AccountStoreError("Account store migration is required")
+        key = secrets.token_bytes(32)
+        try:
+            creation_cancelled = await self._create_database_key(key)
+        except SecretAlreadyExistsError as error:
+            raise AccountStoreError("Account database key already exists") from error
+        try:
+            created_database_key = True
+            if creation_cancelled:
+                raise asyncio.CancelledError
+            self._database_key = key
+            await self._passwords.start()
+            await Tortoise.init(config=self._tortoise_config(), init_connections=False)
+            self._started = True
+            await migrate(config=self._tortoise_config())
+            await Tortoise.init(config=self._tortoise_config(), _enable_global_fallback=True)
+            self._migrated = True
+            self._initialised_here = True
+        except BaseException:
+            await self._cleanup_failed_initialisation(created_database_key)
+            raise
+
+    async def remove_orphan_database_key(self) -> None:
+        """Remove a present database key only when no database exists."""
+        if await self._database_path.exists():
+            raise AccountStoreError("Account database already exists")
+        if self._started:
+            await self.aclose()
+            self._database_key = None
+            self._passwords = PasswordOperations()
+        try:
+            await self._secrets.resolve(DATABASE_KEY_REFERENCE)
+        except MissingSecretError as error:
+            raise AccountStoreError("Account database key does not exist") from error
+        await self._secrets.delete(DATABASE_KEY_REFERENCE)
+
+    async def rollback_initialisation(self) -> None:
+        """Remove only database state created by this store's initialisation."""
+        if not self._initialised_here:
+            raise AccountStoreError("Account store has no initialisation to roll back")
+        await self._cleanup_failed_initialisation(created_database_key=True)
+
+    async def aclose(self) -> None:
+        """Close database connections owned by this store."""
+        if self._started:
+            await Tortoise.close_connections()
+            await self._passwords.aclose()
+            self._started = False
+            self._migrated = False
+
+    async def apply_migrations(self) -> None:
+        """Explicitly apply the deploying user's native Tortoise migrations."""
+        await self._require_started()
+        if not await self._database_path.exists():
+            raise AccountStoreError("Account database is not initialised")
+        if not await self._has_user_migrations():
+            raise AccountStoreError("Account store migration is required")
+        await migrate(config=self._tortoise_config())
+        await Tortoise.init(config=self._tortoise_config())
+        self._migrated = True
+
+    async def migration_required(self) -> bool:
+        """Report whether native migrations are pending without applying them."""
+        await self.pending_migration_plan()
+        return not self._migrated
+
+    async def pending_migration_plan(self) -> tuple[str, ...]:
+        """Return a silent, display-ready plan of unapplied native migrations."""
+        await self._require_started()
+        if not await self._has_user_migrations():
+            self._migrated = False
+            return ()
+        if not await self._database_path.exists():
+            self._migrated = False
+            return ()
+        config = self._tortoise_config()
+        connection = get_connection("default")
+        await connection.create_connection(with_db=True)
+        executor = MigrationExecutor(connection, config["apps"])
+        steps = await executor.plan()
+        migration_plan = tuple(
+            f"{'-' if step.backward else '+'} {step.migration.app_label}.{step.migration.name}" for step in steps
+        )
+        self._migrated = not migration_plan
+        return migration_plan
+
+    async def list_accounts(self, *, include_inactive: bool = False) -> list[AccountRecord]:
+        """Return complete account records, excluding inactive accounts by default."""
+        await self._require_migrated()
+        accounts = AccountRecord.including_inactive() if include_inactive else AccountRecord.all()
+        return await accounts.order_by("email_comparison")
+
+    async def set_password(self, account: AccountRecord, password: str) -> None:
+        """Persist a fixed-policy Argon2id verifier on an account record."""
+        await self._require_migrated()
+        account.password_hash = await self._passwords.hash(password)
+        account.must_change_password = False
+        await account.save(update_fields=["password_hash", "must_change_password"])
+
+    async def create_account(self, account: AccountRecord, password: str) -> None:
+        """Persist a newly provisioned account and its initial password together."""
+        await self._require_migrated()
+        account.password_hash = await self._passwords.hash(password)
+        account.must_change_password = True
+        await account.save()
+
+    async def reset_password(self, account: AccountRecord, password: str) -> None:
+        """Replace a managed account password and require its next change."""
+        await self._require_migrated()
+        account.password_hash = await self._passwords.hash(password)
+        account.must_change_password = True
+        await account.save(update_fields=["password_hash", "must_change_password"])
+
+    async def verify_password(self, account: AccountRecord | None, password: str) -> bool:
+        """Verify an active account password against its fixed Argon2id policy."""
+        await self._require_migrated()
+        if account is None or account.password_hash is None:
+            await self._passwords.verify_unknown(password)
+            return False
+        if not account.is_active:
+            await self._passwords.verify_unknown(password)
+            return False
+        if not await self._passwords.verify(account.password_hash, password):
+            return False
+        current_account = await AccountRecord.get_or_none(id=account.id)
+        return (
+            current_account is not None
+            and current_account.is_active
+            and current_account.password_hash == account.password_hash
+        )
+
+    async def _cleanup_failed_initialisation(self, created_database_key: bool) -> None:
+        """Close partial state and remove a key created by this failed invocation."""
+        try:
+            if self._started:
+                await self.aclose()
+            else:
+                await self._passwords.aclose()
+        finally:
+            self._started = False
+            self._migrated = False
+            self._initialised_here = False
+            self._database_key = None
+            for database_path in self._database_files:
+                if await database_path.exists():
+                    await database_path.unlink()
+            if created_database_key:
+                await self._secrets.delete(DATABASE_KEY_REFERENCE)
+
+    async def _create_database_key(self, key: bytes) -> bool:
+        """Create a key to completion and report whether the caller cancelled."""
+        creation = asyncio.create_task(
+            self._secrets.create(DATABASE_KEY_REFERENCE, base64.b64encode(key).decode("ascii"))
+        )
+        cancelled = False
+        while not creation.done():
+            try:
+                await asyncio.shield(creation)
+            except asyncio.CancelledError:
+                cancelled = True
+        await creation
+        return cancelled
+
+    async def _resolve_database_key(self) -> bytes:
+        encoded_key = await self._secrets.resolve(DATABASE_KEY_REFERENCE)
+        try:
+            key = base64.b64decode(encoded_key, validate=True)
+        except ValueError as error:
+            raise AccountStoreError("Stored database key is invalid") from error
+        if len(key) != 32:
+            raise AccountStoreError("Stored database key is invalid")
+        return key
+
+    async def _require_started(self) -> None:
+        if not self._started:
+            raise AccountStoreError("Account store is not started")
+
+    async def _require_migrated(self) -> None:
+        await self._require_started()
+        if not self._migrated:
+            raise AccountStoreError("Account store migration is required")
+
+    async def _has_user_migrations(self) -> bool:
+        """Report whether the deploying user has supplied a native migration."""
+        migrations_path = AsyncPath(__file__).parent / "migrations"
+        async for path in migrations_path.iterdir():
+            if path.suffix == ".py" and path.name != "__init__.py" and not path.name.startswith("_"):
+                return True
+        return False
+
+    @property
+    def _database_path(self) -> AsyncPath:
+        """Return the configured encrypted database path."""
+        return self._config_dir / DATABASE_FILENAME
+
+    @property
+    def _database_files(self) -> tuple[AsyncPath, AsyncPath, AsyncPath]:
+        """Return the database file and SQLite write-ahead-log sidecars."""
+        database_path = self._database_path
+        return database_path, AsyncPath(f"{database_path}-wal"), AsyncPath(f"{database_path}-shm")
+
+    def _tortoise_config(self) -> dict[str, Any]:
+        key = self._database_key
+        if key is None:
+            raise AccountStoreError("Account store database key is unavailable")
+        return {
+            "use_tz": True,
+            "timezone": "UTC",
+            "connections": {
+                "default": {
+                    "engine": "tortoise_sqlcipher.sqlite_sqlcipher",
+                    "credentials": {
+                        "file_path": str(self._database_path),
+                        "encryption_key": key,
+                    },
+                }
+            },
+            "apps": {
+                "accounts": {
+                    "models": ["auth_guide.accounts.models"],
+                    "migrations": "auth_guide.accounts.migrations",
+                }
+            },
+        }

auth_guide/accounts/migrations/0001_initial.py

@@ -0,0 +1,63 @@
+import functools
+from json import dumps, loads
+from uuid import uuid4
+
+from tortoise import fields, migrations
+from tortoise.fields.base import OnDelete
+from tortoise.migrations import operations as ops
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    operations = [
+        ops.CreateModel(
+            name="AccountRecord",
+            fields=[
+                ("id", fields.UUIDField(primary_key=True, default=uuid4, unique=True, db_index=True)),
+                ("email", fields.CharField(max_length=254)),
+                ("email_comparison", fields.CharField(unique=True, max_length=254)),
+                ("grants", fields.JSONField(encoder=functools.partial(dumps, separators=(",", ":")), decoder=loads)),
+                ("password_hash", fields.TextField(unique=False)),
+                ("created_at", fields.DatetimeField(auto_now=False, auto_now_add=True)),
+                ("expires_at", fields.DatetimeField(null=True, auto_now=False, auto_now_add=False)),
+                ("full_name", fields.TextField(null=True, unique=False)),
+                ("must_change_password", fields.BooleanField(default=False)),
+            ],
+            options={
+                "table": "accounts",
+                "app": "accounts",
+                "pk_attr": "id",
+                "table_description": "The persisted representation of one provider account.",
+            },
+            bases=["Model"],
+        ),
+        ops.CreateModel(
+            name="AccountTokenRecord",
+            fields=[
+                ("id", fields.UUIDField(primary_key=True, default=uuid4, unique=True, db_index=True)),
+                (
+                    "account",
+                    fields.ForeignKeyField(
+                        "accounts.AccountRecord",
+                        source_field="account_id",
+                        db_constraint=True,
+                        to_field="id",
+                        related_name="tokens",
+                        on_delete=OnDelete.CASCADE,
+                    ),
+                ),
+                ("label", fields.TextField(unique=False)),
+                ("verifier", fields.CharField(unique=True, max_length=64)),
+                ("scopes", fields.JSONField(encoder=functools.partial(dumps, separators=(",", ":")), decoder=loads)),
+                ("created_at", fields.DatetimeField(auto_now=False, auto_now_add=True)),
+            ],
+            options={
+                "table": "account_tokens",
+                "app": "accounts",
+                "pk_attr": "id",
+                "table_description": "A revocable account token represented only by its verifier and metadata.",
+            },
+            bases=["Model"],
+        ),
+    ]

auth_guide/accounts/migrations/__init__.py

@@ -0,0 +1 @@
+"""Native Tortoise migrations for account persistence."""

auth_guide/accounts/models.py

@@ -0,0 +1,206 @@
+"""Tortoise models for encrypted account persistence."""
+
+import logging
+from collections.abc import Iterable
+from datetime import datetime, timezone
+from enum import StrEnum
+from typing import Any
+
+from email_validator import EmailNotValidError, validate_email
+from tortoise import fields
+from tortoise.backends.base.client import BaseDBAsyncClient
+from tortoise.expressions import Q
+from tortoise.manager import Manager
+from tortoise.models import Model
+from tortoise.queryset import QuerySet
+
+from auth_guide.accounts.passwords import PasswordOperations
+
+logger = logging.getLogger(__name__)
+
+
+class Grant(StrEnum):
+    """Recognised capability grants persisted for provider accounts."""
+
+    GUIDE_ADMIN = "guide:admin"
+    ACCOUNTS_READ = "accounts:read"
+    ACCOUNTS_MANAGE = "accounts:manage"
+    TOKENS_MANAGE = "tokens:manage"
+
+
+class AccountQuerySet(QuerySet):
+    """Warn when native bulk writes bypass account-model validation."""
+
+    def update(self, **kwargs: object):
+        logger.warning("Bulk account update bypasses AccountRecord.save validation")
+        return super().update(**kwargs)
+
+    def bulk_create(
+        self,
+        objects: Iterable[Any],
+        batch_size: int | None = None,
+        ignore_conflicts: bool = False,
+        update_fields: Iterable[str] | None = None,
+        on_conflict: Iterable[str] | None = None,
+    ) -> Any:
+        logger.warning("Bulk account creation bypasses AccountRecord.save validation")
+        return super().bulk_create(objects, batch_size, ignore_conflicts, update_fields, on_conflict)
+
+    def bulk_update(self, objects: Iterable[Any], fields: Iterable[str], batch_size: int | None = None) -> Any:
+        logger.warning("Bulk account update bypasses AccountRecord.save validation")
+        return super().bulk_update(objects, fields, batch_size)
+
+
+class ActiveAccountManager(Manager):
+    """Provide active accounts through the normal model query interface."""
+
+    def get_queryset(self) -> QuerySet:
+        """Return accounts whose optional expiry permits access now."""
+        if self._model is None:
+            raise RuntimeError("Account manager has no model")
+        return AccountQuerySet(self._model).filter(Q(expires_at=None) | Q(expires_at__gt=datetime.now(timezone.utc)))
+
+
+class AccountRecord(Model):
+    """The persisted representation of one provider account."""
+
+    id = fields.UUIDField(primary_key=True)
+    email = fields.CharField(max_length=254)
+    email_comparison = fields.CharField(max_length=254, unique=True)
+    grants = fields.JSONField()
+    password_hash = fields.TextField()
+    created_at = fields.DatetimeField(auto_now_add=True)
+    expires_at = fields.DatetimeField(null=True)
+    full_name = fields.TextField(null=True)
+    must_change_password = fields.BooleanField(default=False)
+
+    class Meta:  # ty: ignore[invalid-attribute-override]
+        table = "accounts"
+        manager = ActiveAccountManager()
+
+    @classmethod
+    def including_inactive(cls) -> QuerySet:
+        """Return an unfiltered account query for explicit administration work."""
+        return AccountQuerySet(cls)
+
+    @property
+    def is_active(self) -> bool:
+        """Report whether the account's optional expiry permits access."""
+        return self.expires_at is None or self.expires_at > datetime.now(timezone.utc)
+
+    def has_grant(self, requested_grant: Grant) -> bool:
+        """Report whether an active account holds the requested grant."""
+        return self.is_active and requested_grant in self.grants
+
+    async def save(
+        self,
+        using_db: BaseDBAsyncClient | None = None,
+        update_fields: Iterable[str] | None = None,
+        force_create: bool = False,
+        force_update: bool = False,
+    ) -> None:
+        """Validate account identity and lifecycle fields before persistence."""
+        fields_to_update = set(update_fields) if update_fields is not None else None
+        if fields_to_update is None or "email" in fields_to_update:
+            self.update_from_dict(await normalise_account_email(self.email))
+            if fields_to_update is not None:
+                fields_to_update.add("email_comparison")
+        if fields_to_update is None or "expires_at" in fields_to_update:
+            self.update_from_dict({"expires_at": await normalise_account_expiry(self.expires_at)})
+        if fields_to_update is None or "grants" in fields_to_update:
+            self.grants = await normalise_grants(self.grants)
+        if fields_to_update is None or "password_hash" in fields_to_update:
+            if self.password_hash is not None and not PasswordOperations.is_current_verifier(self.password_hash):
+                raise ValueError("Account password verifier is invalid")
+        await super().save(
+            using_db=using_db,
+            update_fields=fields_to_update,
+            force_create=force_create,
+            force_update=force_update,
+        )
+
+
+class AccountTokenRecord(Model):
+    """A revocable account token represented only by its verifier and metadata."""
+
+    id = fields.UUIDField(primary_key=True)
+    account = fields.ForeignKeyField("accounts.AccountRecord", related_name="tokens", on_delete=fields.CASCADE)
+    label = fields.TextField()
+    verifier = fields.CharField(max_length=64, unique=True)
+    scopes = fields.JSONField()
+    created_at = fields.DatetimeField(auto_now_add=True)
+
+    class Meta:  # ty: ignore[invalid-attribute-override]
+        table = "account_tokens"
+
+    async def save(
+        self,
+        using_db: BaseDBAsyncClient | None = None,
+        update_fields: Iterable[str] | None = None,
+        force_create: bool = False,
+        force_update: bool = False,
+    ) -> None:
+        """Validate immutable token properties and its mutable label."""
+        fields_to_update = set(update_fields) if update_fields is not None else None
+        if self._saved_in_db and (fields_to_update is None or fields_to_update - {"label"}):
+            raise ValueError("Only an account token label may be updated")
+        if fields_to_update is None or "label" in fields_to_update:
+            if not self.label:
+                raise ValueError("Account token label is required")
+        if fields_to_update is None or "verifier" in fields_to_update:
+            if len(self.verifier) != 64 or any(character not in "0123456789abcdef" for character in self.verifier):
+                raise ValueError("Account token verifier is invalid")
+        if fields_to_update is None or "scopes" in fields_to_update:
+            self.scopes = await normalise_grants(self.scopes)
+        await super().save(
+            using_db=using_db,
+            update_fields=fields_to_update,
+            force_create=force_create,
+            force_update=force_update,
+        )
+
+
+def validate_account_email(email: str) -> str:
+    """Validate and canonicalise an email identifier without deliverability checks."""
+    try:
+        validated = validate_email(email, check_deliverability=False)
+    except EmailNotValidError as error:
+        raise ValueError("Account email identifier is invalid") from error
+    local_part, _, _ = validated.original.rpartition("@")
+    canonical_email = f"{local_part}@{validated.domain.lower()}"
+    if len(canonical_email.encode("utf-8")) > 254:
+        raise ValueError("Account email identifier is too long")
+    return canonical_email
+
+
+class AccountExpiryTimezoneError(ValueError):
+    """Raised when an account expiry omits its required timezone."""
+
+
+async def normalise_account_email(email: str) -> dict[str, str]:
+    """Validate and normalise an email identifier for asynchronous model use."""
+    canonical_email = validate_account_email(email)
+    return {"email": canonical_email, "email_comparison": canonical_email.casefold()}
+
+
+async def normalise_account_expiry(expires_at: datetime | None) -> datetime | None:
+    """Validate and convert an optional account expiry to UTC."""
+    if expires_at is None:
+        return None
+    if expires_at.tzinfo is None or expires_at.utcoffset() is None:
+        raise AccountExpiryTimezoneError("Account expiry must include a timezone")
+    return expires_at.astimezone(timezone.utc)
+
+
+async def normalise_grants(grants: Iterable[Grant | str]) -> list[str]:
+    """Validate a complete account grant or token scope set."""
+    if isinstance(grants, str):
+        raise ValueError("Grant set must be an array")
+    values = list(grants)
+    try:
+        normalised = [str(Grant(value)) for value in values]
+    except ValueError as error:
+        raise ValueError("Grant set contains an unknown grant") from error
+    if len(set(normalised)) != len(normalised):
+        raise ValueError("Grant set must not contain duplicates")
+    return normalised