paskia 0.7.1__py3-none-any.whl

paskia/authsession.py

@@ -0,0 +1,112 @@
+"""
+Core session management for WebAuthn authentication.
+
+This module provides generic session management functionality that is
+independent of any web framework:
+- Session creation and validation
+- Token handling and refresh
+- Credential management
+"""
+
+from datetime import datetime, timezone
+from uuid import UUID
+
+from paskia.config import SESSION_LIFETIME
+from paskia.db import ResetToken, Session
+from paskia.globals import db, passkey
+from paskia.util import hostutil
+from paskia.util.tokens import create_token, reset_key, session_key
+
+EXPIRES = SESSION_LIFETIME
+
+
+def expires() -> datetime:
+    return datetime.now(timezone.utc) + EXPIRES
+
+
+def reset_expires() -> datetime:
+    from .config import RESET_LIFETIME
+
+    return datetime.now(timezone.utc) + RESET_LIFETIME
+
+
+def session_expiry(session: Session) -> datetime:
+    """Calculate the expiration timestamp for a session (UTC aware)."""
+    # After migration all renewed timestamps are timezone-aware UTC
+    return session.renewed + EXPIRES
+
+
+async def create_session(
+    user_uuid: UUID,
+    credential_uuid: UUID,
+    *,
+    host: str,
+    ip: str,
+    user_agent: str,
+) -> str:
+    """Create a new session and return a session token."""
+    normalized_host = hostutil.normalize_host(host)
+    if not normalized_host:
+        raise ValueError("Host required for session creation")
+    hostname = normalized_host.split(":")[0]  # Domain names only, IPs aren't supported
+    rp_id = passkey.instance.rp_id
+    if not (hostname == rp_id or hostname.endswith(f".{rp_id}")):
+        raise ValueError(f"Host must be the same as or a subdomain of {rp_id}")
+    token = create_token()
+    now = datetime.now(timezone.utc)
+    await db.instance.create_session(
+        user_uuid=user_uuid,
+        credential_uuid=credential_uuid,
+        key=session_key(token),
+        host=normalized_host,
+        ip=ip,
+        user_agent=user_agent,
+        renewed=now,
+    )
+    return token
+
+
+async def get_reset(token: str) -> ResetToken:
+    """Validate a credential reset token. Returns None if the token is not well formed (i.e. it is another type of token)."""
+    record = await db.instance.get_reset_token(reset_key(token))
+    if record and record.expiry >= datetime.now(timezone.utc):
+        return record
+    raise ValueError("This authentication link is no longer valid.")
+
+
+async def get_session(token: str, host: str | None = None) -> Session:
+    """Validate a session token and return session data if valid."""
+    host = hostutil.normalize_host(host)
+    if not host:
+        raise ValueError("Invalid host")
+    session = await db.instance.get_session(session_key(token))
+    if session and session_expiry(session) >= datetime.now(timezone.utc):
+        if session.host is None:
+            # First time binding: store exact host:port (or IPv6 form) now.
+            await db.instance.set_session_host(session.key, host)
+            session.host = host
+        elif session.host != host:
+            raise ValueError("Session host mismatch")
+        return session
+    raise ValueError("Your session has expired. Please sign in again!")
+
+
+async def refresh_session_token(token: str, *, ip: str, user_agent: str):
+    """Refresh a session extending its expiry."""
+    session_record = await db.instance.get_session(session_key(token))
+    if not session_record:
+        raise ValueError("Session not found or expired")
+    updated = await db.instance.update_session(
+        session_key(token),
+        ip=ip,
+        user_agent=user_agent,
+        renewed=datetime.now(timezone.utc),
+    )
+    if not updated:
+        raise ValueError("Session not found or expired")
+
+
+async def delete_credential(credential_uuid: UUID, auth: str, host: str | None = None):
+    """Delete a specific credential for the current user."""
+    s = await get_session(auth, host=host)
+    await db.instance.delete_credential(credential_uuid, s.user_uuid)

paskia/bootstrap.py

@@ -0,0 +1,190 @@
+"""
+Bootstrap module for passkey authentication system.
+
+This module handles initial system setup when a new database is created,
+including creating default admin user, organization, permissions, and
+generating a reset link for initial admin setup.
+"""
+
+import asyncio
+import logging
+from datetime import datetime, timezone
+
+import uuid7
+
+from paskia import authsession, globals
+from paskia.db import Org, Permission, Role, User
+from paskia.util import hostutil, passphrase, tokens
+
+
+def _init_logger() -> logging.Logger:
+    logger = logging.getLogger(__name__)
+    if not logger.handlers and not logging.getLogger().handlers:
+        h = logging.StreamHandler()
+        h.setFormatter(logging.Formatter("%(message)s"))
+        logger.addHandler(h)
+        logger.setLevel(logging.INFO)
+    return logger
+
+
+logger = _init_logger()
+
+# Shared log message template for admin reset links
+ADMIN_RESET_MESSAGE = """\
+%s
+
+👤 Admin  %s
+   - Use this link to register a Passkey for the admin user!
+"""
+
+
+async def _create_and_log_admin_reset_link(user_uuid, message, session_type) -> str:
+    """Create an admin reset link and log it with the provided message."""
+    token = passphrase.generate()
+    expiry = authsession.reset_expires()
+    await globals.db.instance.create_reset_token(
+        user_uuid=user_uuid,
+        key=tokens.reset_key(token),
+        expiry=expiry,
+        token_type=session_type,
+    )
+    reset_link = hostutil.reset_link_url(token)
+    logger.info(ADMIN_RESET_MESSAGE, message, reset_link)
+    return reset_link
+
+
+async def bootstrap_system() -> dict:
+    """
+    Bootstrap the entire system with default data.
+
+    Returns:
+        dict: Contains information about created entities and reset link
+    """
+    # Create permission first - will fail if already exists
+    perm0 = Permission(id="auth:admin", display_name="Master Admin")
+    await globals.db.instance.create_permission(perm0)
+
+    org = Org(uuid7.create(), "Organization")
+    await globals.db.instance.create_organization(org)
+
+    # After creation, org.permissions now includes the auto-created org admin permission
+    # Allow this org to grant global admin explicitly
+    await globals.db.instance.add_permission_to_organization(str(org.uuid), perm0.id)
+
+    # Create an Administration role granting both org and global admin
+    # Compose permissions for Administration role: global admin + org admin auto-perm
+    role = Role(
+        uuid7.create(),
+        org.uuid,
+        "Administration",
+        permissions=[perm0.id, *org.permissions],
+    )
+    await globals.db.instance.create_role(role)
+
+    user = User(
+        uuid=uuid7.create(),
+        display_name="Admin",
+        role_uuid=role.uuid,
+        created_at=datetime.now(timezone.utc),
+        visits=0,
+    )
+    await globals.db.instance.create_user(user)
+
+    # Generate reset link and log it
+    reset_link = await _create_and_log_admin_reset_link(
+        user.uuid, "✅ Bootstrap completed!", "admin bootstrap"
+    )
+
+    return {
+        "user": user,
+        "org": org,
+        "role": role,
+        "permissions": [
+            perm0,
+            *[Permission(id=p, display_name="") for p in org.permissions],
+        ],
+        "reset_link": reset_link,
+    }
+
+
+async def check_admin_credentials() -> bool:
+    """
+    Check if the admin user needs credentials and create a reset link if needed.
+
+    Returns:
+        bool: True if a reset link was created, False if admin already has credentials
+    """
+    try:
+        # Get permission organizations to find admin users
+        permission_orgs = await globals.db.instance.get_permission_organizations(
+            "auth:admin"
+        )
+
+        if not permission_orgs:
+            return False
+
+        # Get users from the first organization with admin permission
+        org_users = await globals.db.instance.get_organization_users(
+            str(permission_orgs[0].uuid)
+        )
+        admin_users = [user for user, role in org_users if role == "Administration"]
+
+        if not admin_users:
+            return False
+
+        # Check first admin user for credentials
+        admin_user = admin_users[0]
+        credentials = await globals.db.instance.get_credentials_by_user_uuid(
+            admin_user.uuid
+        )
+
+        if not credentials:
+            # Admin exists but has no credentials, create reset link
+            await _create_and_log_admin_reset_link(
+                admin_user.uuid,
+                "⚠️  Admin user has no credentials!",
+                "admin registration",
+            )
+            return True
+
+        return False
+
+    except Exception:
+        return False
+
+
+async def bootstrap_if_needed() -> bool:
+    """
+    Check if system needs bootstrapping and perform it if necessary.
+
+    Returns:
+        bool: True if bootstrapping was performed, False if system was already set up
+    """
+    try:
+        # Check if the admin permission exists - if it does, system is already bootstrapped
+        await globals.db.instance.get_permission("auth:admin")
+        # Permission exists, system is already bootstrapped
+        # Check if admin needs credentials (only for already-bootstrapped systems)
+        await check_admin_credentials()
+        return False
+    except Exception:
+        # Permission doesn't exist, need to bootstrap
+        pass
+
+    # No admin permission found, need to bootstrap
+    # Bootstrap creates the admin user AND the reset link, so no need to check credentials after
+    await bootstrap_system()
+    return True
+
+
+# CLI interface
+async def main():
+    """Main CLI entry point for bootstrapping."""
+    # Configure logging for CLI usage
+    logging.basicConfig(level=logging.INFO, format="%(message)s", force=True)
+
+    await globals.init()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

paskia/config.py

@@ -0,0 +1,25 @@
+from dataclasses import dataclass
+from datetime import timedelta
+
+# Shared configuration constants for session management.
+SESSION_LIFETIME = timedelta(hours=24)
+
+# Lifetime for reset links created by admins
+RESET_LIFETIME = timedelta(days=14)
+
+
+@dataclass
+class PaskiaConfig:
+    """Runtime configuration for the Paskia authentication server."""
+
+    rp_id: str
+    rp_name: str | None
+    origins: list[str] | None
+    auth_host: str | None
+    site_url: str  # Base URL without trailing path (e.g. https://example.com)
+    site_path: str  # Path to auth UI: "/" if auth_host, else "/auth/"
+    # Listen address (one of host:port or uds)
+    host: str | None = None
+    port: int | None = None
+    uds: str | None = None
+    devmode: bool = False