paskia 0.8.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

paskia/db/operations.py

@@ -1,34 +1,27 @@
 """
 Database for WebAuthn passkey authentication.
 
-Read operations: Access _db._data directly, use build_* helpers to get public structs.
+Read operations: Access _db directly, use build_* helpers to get public structs.
 Context lookup: get_session_context() returns full SessionContext with effective permissions.
 Write operations: Functions that validate and commit, or raise ValueError.
 """
 
 import hashlib
-import json
 import logging
 import os
 import secrets
-import sys
-from collections import deque
-from contextlib import contextmanager
 from datetime import datetime, timezone
-from pathlib import Path
-from typing import Any
 from uuid import UUID
 
-import msgspec
+import uuid7
 
+from paskia.config import SESSION_LIFETIME
 from paskia.db.jsonl import (
     DB_PATH_DEFAULT,
-    _ChangeRecord,
-    compute_diff,
-    create_change_record,
-    load_jsonl,
+    JsonlStore,
 )
 from paskia.db.structs import (
+    DB,
     Credential,
     Org,
     Permission,
@@ -37,220 +30,32 @@ from paskia.db.structs import (
     Session,
     SessionContext,
     User,
-    _CredentialData,
-    _DatabaseData,
-    _OrgData,
-    _PermissionData,
-    _ResetTokenData,
-    _RoleData,
-    _SessionData,
-    _UserData,
 )
+from paskia.util.hostutil import normalize_host
+from paskia.util.passphrase import generate as generate_passphrase
 from paskia.util.passphrase import is_well_formed as _is_passphrase
 
 _logger = logging.getLogger(__name__)
 
-# msgspec encoder/decoder
-_json_encoder = msgspec.json.Encoder()
-_json_decoder = msgspec.json.Decoder(_DatabaseData)
-
-
-class DB:
-    """In-memory database with JSONL persistence.
-
-    Access data directly via _data for reads.
-    Use transaction() context manager for writes.
-    """
-
-    def __init__(self, db_path: str = DB_PATH_DEFAULT):
-        self.db_path = Path(db_path)
-        self._data = _DatabaseData(
-            permissions={},
-            orgs={},
-            roles={},
-            users={},
-            credentials={},
-            sessions={},
-            reset_tokens={},
-        )
-        self._previous_builtins: dict[str, Any] = {}
-        self._pending_changes: deque[_ChangeRecord] = deque()
-        self._current_action: str = "system"
-        self._current_user: str | None = None
-
-    async def load(self, db_path: str | None = None) -> None:
-        """Load data from JSONL change log.
-
-        If file doesn't exist or is empty, keeps the initialized empty structure and
-        sets _previous_builtins to {} for creating a new database.
-        """
-        if db_path is not None:
-            self.db_path = Path(db_path)
-        try:
-            data_dict = await load_jsonl(self.db_path)
-            if data_dict:  # Only decode if we have data
-                self._data = _json_decoder.decode(_json_encoder.encode(data_dict))
-                # Track the JSONL file state directly - this is what we diff against
-                self._previous_builtins = data_dict
-            # If data_dict is empty, keep initialized _data and _previous_builtins = {}
-        except ValueError:
-            if self.db_path.exists():
-                raise  # File exists but failed to load - re-raise
-            # File doesn't exist: keep initialized _data, _previous_builtins stays {}
-
-    def _queue_change(self) -> None:
-        current = msgspec.to_builtins(self._data)
-        diff = compute_diff(self._previous_builtins, current)
-        if diff:
-            self._pending_changes.append(
-                create_change_record(self._current_action, diff, self._current_user)
-            )
-            self._previous_builtins = current
-            # Log the change with user display name if available
-            user_display = None
-            if self._current_user:
-                try:
-                    user_uuid = UUID(self._current_user)
-                    if user_uuid in self._data.users:
-                        user_display = self._data.users[user_uuid].display_name
-                except (ValueError, KeyError):
-                    user_display = self._current_user
-
-            diff_json = json.dumps(diff, default=str)
-            if user_display:
-                print(
-                    f"{self._current_action} by {user_display}: {diff_json}",
-                    file=sys.stderr,
-                )
-            else:
-                print(f"{self._current_action}: {diff_json}", file=sys.stderr)
-
-    @contextmanager
-    def transaction(
-        self,
-        action: str,
-        ctx: SessionContext | None = None,
-        *,
-        user: str | None = None,
-    ):
-        """Wrap writes in transaction. Queues change on successful exit.
-
-        Args:
-            action: Describes the operation (e.g., "Created user", "Login")
-            ctx: Session context of user performing the action (None for system operations)
-            user: User UUID string (alternative to ctx when full context unavailable)
-        """
-        old_action = self._current_action
-        old_user = self._current_user
-        self._current_action = action
-        # Prefer ctx.user.uuid if ctx provided, otherwise use user param
-        self._current_user = str(ctx.user.uuid) if ctx else user
-        try:
-            yield
-            self._queue_change()
-        finally:
-            self._current_action = old_action
-            self._current_user = old_user
-
-
-# Global instance, always available (empty until init() loads data)
+# Global database instance (empty until init() loads data)
 _db = DB()
+_store = JsonlStore(_db)
+_db._store = _store
+_initialized = False
 
 
 async def init(*args, **kwargs):
-    """Load database and start background flush task."""
-    from paskia.db.background import start_background
-
+    """Load database from JSONL file."""
+    global _db, _initialized
+    if _initialized:
+        _logger.debug("Database already initialized, skipping reload")
+        return
     db_path = os.environ.get("PASKIA_DB", DB_PATH_DEFAULT)
     if db_path.startswith("json:"):
         db_path = db_path[5:]
-    await _db.load(db_path)
-    await start_background()
-
-
-# -------------------------------------------------------------------------
-# Builders: Convert internal _*Data to public structs
-# -------------------------------------------------------------------------
-
-
-def build_permission(uuid: UUID) -> Permission:
-    p = _db._data.permissions[uuid]
-    return Permission(
-        uuid=uuid, scope=p.scope, display_name=p.display_name, domain=p.domain
-    )
-
-
-def build_user(uuid: UUID) -> User:
-    u = _db._data.users[uuid]
-    return User(
-        uuid=uuid,
-        display_name=u.display_name,
-        role_uuid=u.role,
-        created_at=u.created_at,
-        last_seen=u.last_seen,
-        visits=u.visits,
-    )
-
-
-def build_role(uuid: UUID) -> Role:
-    r = _db._data.roles[uuid]
-    return Role(
-        uuid=uuid,
-        org_uuid=r.org,
-        display_name=r.display_name,
-        permissions=[str(pid) for pid in r.permissions.keys()],
-    )
-
-
-def build_org(uuid: UUID, include_roles: bool = False) -> Org:
-    o = _db._data.orgs[uuid]
-    perm_uuids = [
-        str(pid) for pid, p in _db._data.permissions.items() if uuid in p.orgs
-    ]
-    org = Org(uuid=uuid, display_name=o.display_name, permissions=perm_uuids)
-    if include_roles:
-        org.roles = [
-            build_role(rid) for rid, r in _db._data.roles.items() if r.org == uuid
-        ]
-    return org
-
-
-def build_credential(uuid: UUID) -> Credential:
-    c = _db._data.credentials[uuid]
-    return Credential(
-        uuid=uuid,
-        credential_id=c.credential_id,
-        user_uuid=c.user,
-        aaguid=c.aaguid,
-        public_key=c.public_key,
-        sign_count=c.sign_count,
-        created_at=c.created_at,
-        last_used=c.last_used,
-        last_verified=c.last_verified,
-    )
-
-
-def build_session(key: str) -> Session:
-    s = _db._data.sessions[key]
-    return Session(
-        key=key,
-        user_uuid=s.user,
-        credential_uuid=s.credential,
-        host=s.host,
-        ip=s.ip,
-        user_agent=s.user_agent,
-        expiry=s.expiry,
-    )
-
-
-def build_reset_token(key: bytes) -> ResetToken:
-    t = _db._data.reset_tokens[key]
-    return ResetToken(
-        key=key,
-        user_uuid=t.user,
-        expiry=t.expiry,
-        token_type=t.token_type,
-    )
+    await _store.load(db_path)
+    _db = _store.db
+    _initialized = True
 
 
 # -------------------------------------------------------------------------
@@ -258,155 +63,46 @@ def build_reset_token(key: bytes) -> ResetToken:
 # -------------------------------------------------------------------------
 
 
-def get_permission(permission_id: str | UUID) -> Permission | None:
-    """Get permission by UUID or scope.
-
-    For backwards compatibility, this accepts either:
-    - A UUID string (the primary key)
-    - A scope string (searches for matching scope)
-    """
-    # First try as UUID key
-    if isinstance(permission_id, UUID):
-        if permission_id in _db._data.permissions:
-            return build_permission(permission_id)
-    else:
-        try:
-            uuid = UUID(permission_id)
-            if uuid in _db._data.permissions:
-                return build_permission(uuid)
-        except ValueError:
-            pass
-    # Fall back to scope search
-    for uuid, p in _db._data.permissions.items():
-        if p.scope == str(permission_id):
-            return build_permission(uuid)
-    return None
-
-
-def get_permission_by_scope(scope: str) -> Permission | None:
-    """Get permission by scope identifier."""
-    for uuid, p in _db._data.permissions.items():
-        if p.scope == scope:
-            return build_permission(uuid)
-    return None
-
-
-def list_permissions() -> list[Permission]:
-    """List all permissions."""
-    return [build_permission(uuid) for uuid in _db._data.permissions]
-
-
-def get_permission_organizations(scope: str) -> list[Org]:
-    """Get organizations that can grant a permission scope."""
-    for p in _db._data.permissions.values():
-        if p.scope == scope:
-            return [build_org(org_uuid) for org_uuid in p.orgs]
-    return []
-
-
-def get_organization(uuid: str | UUID) -> Org | None:
-    """Get organization by UUID."""
-    if isinstance(uuid, str):
-        uuid = UUID(uuid)
-    return build_org(uuid, include_roles=True) if uuid in _db._data.orgs else None
-
-
-def list_organizations() -> list[Org]:
-    """List all organizations."""
-    return [build_org(uuid, include_roles=True) for uuid in _db._data.orgs]
-
-
-def get_organization_users(org_uuid: str | UUID) -> list[tuple[User, str]]:
-    """Get all users in an organization with their role names."""
-    if isinstance(org_uuid, str):
-        org_uuid = UUID(org_uuid)
-    role_map = {
-        rid: r.display_name for rid, r in _db._data.roles.items() if r.org == org_uuid
-    }
-    return [
-        (build_user(uid), role_map[u.role])
-        for uid, u in _db._data.users.items()
-        if u.role in role_map
-    ]
-
-
-def get_role(uuid: str | UUID) -> Role | None:
-    """Get role by UUID."""
-    if isinstance(uuid, str):
-        uuid = UUID(uuid)
-    return build_role(uuid) if uuid in _db._data.roles else None
-
-
-def get_roles_by_organization(org_uuid: str | UUID) -> list[Role]:
-    """Get all roles in an organization."""
-    if isinstance(org_uuid, str):
-        org_uuid = UUID(org_uuid)
-    return [build_role(rid) for rid, r in _db._data.roles.items() if r.org == org_uuid]
-
-
-def get_user_by_uuid(uuid: str | UUID) -> User | None:
-    """Get user by UUID."""
-    if isinstance(uuid, str):
-        uuid = UUID(uuid)
-    return build_user(uuid) if uuid in _db._data.users else None
-
-
-def get_user_organization(user_uuid: str | UUID) -> tuple[Org, str]:
+def get_user_organization(user_uuid: UUID) -> tuple[Org, str]:
     """Get the organization a user belongs to and their role name.
 
     Raises ValueError if user not found.
+
+    Call sites:
+    - Get user's organization when updating user role (admin.py:493)
+    - Get user's organization for user credential listing (admin.py:530)
+    - Get user's organization for user details API (admin.py:579)
+    - Get user's organization for updating user display name (admin.py:721)
+    - Get user's organization for deleting user credential (admin.py:754)
+    - Get user's organization for deleting user session (admin.py:783)
     """
-    if isinstance(user_uuid, str):
-        user_uuid = UUID(user_uuid)
-    if user_uuid not in _db._data.users:
+    if user_uuid not in _db.users:
         raise ValueError(f"User {user_uuid} not found")
-    role_uuid = _db._data.users[user_uuid].role
-    if role_uuid not in _db._data.roles:
+    role_uuid = _db.users[user_uuid].role
+    if role_uuid not in _db.roles:
         raise ValueError(f"Role {role_uuid} not found")
-    role_data = _db._data.roles[role_uuid]
+    role_data = _db.roles[role_uuid]
     org_uuid = role_data.org
-    return build_org(org_uuid, include_roles=True), role_data.display_name
-
-
-def get_credential_by_id(credential_id: bytes) -> Credential | None:
-    """Get credential by credential_id (the authenticator's ID)."""
-    for uuid, c in _db._data.credentials.items():
-        if c.credential_id == credential_id:
-            return build_credential(uuid)
-    return None
+    return _db.orgs[org_uuid], role_data.display_name
 
 
-def get_credentials_by_user_uuid(user_uuid: str | UUID) -> list[Credential]:
-    """Get all credentials for a user."""
-    if isinstance(user_uuid, str):
-        user_uuid = UUID(user_uuid)
-    return [
-        build_credential(cid)
-        for cid, c in _db._data.credentials.items()
-        if c.user == user_uuid
-    ]
+def get_organization_users(org_uuid: UUID) -> list[tuple[User, str]]:
+    """Get all users in an organization with their role names.
 
+    Returns list of (User, role_display_name) tuples.
+    """
+    role_map = {
+        rid: r.display_name for rid, r in _db.roles.items() if r.org == org_uuid
+    }
+    return [(u, role_map[u.role]) for u in _db.users.values() if u.role in role_map]
 
-def get_session(key: str) -> Session | None:
-    """Get session by key."""
-    if key not in _db._data.sessions:
-        return None
-    s = _db._data.sessions[key]
-    if s.expiry < datetime.now(timezone.utc):
-        return None
-    return build_session(key)
 
+def get_user_credential_ids(user_uuid: UUID) -> list[bytes]:
+    """Get credential IDs for a user (for WebAuthn exclude lists).
 
-def list_sessions_for_user(user_uuid: str | UUID) -> list[Session]:
-    """Get all active sessions for a user."""
-    if isinstance(user_uuid, str):
-        user_uuid = UUID(user_uuid)
-    now = datetime.now(timezone.utc)
-    return [
-        build_session(key)
-        for key, s in _db._data.sessions.items()
-        if s.user == user_uuid and s.expiry >= now
-    ]
+    Returns empty list if user has no credentials.
+    """
+    return [c.credential_id for c in _db.credentials.values() if c.user == user_uuid]
 
 
 def _reset_key(passphrase: str) -> bytes:
@@ -421,14 +117,13 @@ def _reset_key(passphrase: str) -> bytes:
 
 
 def get_reset_token(passphrase: str) -> ResetToken | None:
-    """Get reset token by passphrase."""
+    """Get reset token by passphrase.
+
+    Call sites:
+    - Get reset token to validate it (authsession.py:34)
+    """
     key = _reset_key(passphrase)
-    if key not in _db._data.reset_tokens:
-        return None
-    t = _db._data.reset_tokens[key]
-    if t.expiry < datetime.now(timezone.utc):
-        return None
-    return build_reset_token(key)
+    return _db.reset_tokens.get(key)
 
 
 # -------------------------------------------------------------------------
@@ -447,68 +142,65 @@ def get_session_context(
 
     Returns:
         SessionContext if valid, None if session not found, expired, or host mismatch
+
+    Call sites:
+    - Example usage in docstring (db/__init__.py:16)
+    - Get session context from auth token (util/permutil.py:43)
     """
-    from paskia.util.hostutil import normalize_host
 
-    if session_key not in _db._data.sessions:
+    if session_key not in _db.sessions:
         return None
 
-    s = _db._data.sessions[session_key]
+    s = _db.sessions[session_key]
     if s.expiry < datetime.now(timezone.utc):
         return None
 
-    # Handle host binding
-    if host is not None:
-        if s.host is None:
-            # Bind session to this host
-            with _db.transaction("host_binding"):
-                s.host = host
-        elif s.host != host:
-            # Session bound to different host
-            return None
+    # Validate host matches (sessions are always created with a host)
+    if host is not None and s.host != host:
+        # Session bound to different host
+        return None
 
     # Validate user exists
-    if s.user not in _db._data.users:
+    if s.user not in _db.users:
         return None
 
     # Validate role exists
-    role_uuid = _db._data.users[s.user].role
-    if role_uuid not in _db._data.roles:
+    role_uuid = _db.users[s.user].role
+    if role_uuid not in _db.roles:
         return None
 
     # Validate org exists
-    org_uuid = _db._data.roles[role_uuid].org
-    if org_uuid not in _db._data.orgs:
+    org_uuid = _db.roles[role_uuid].org
+    if org_uuid not in _db.orgs:
         return None
 
-    session = build_session(session_key)
-    user = build_user(s.user)
-    role = build_role(role_uuid)
-    org = build_org(org_uuid)
-    credential = (
-        build_credential(s.credential)
-        if s.credential in _db._data.credentials
-        else None
-    )
+    session = _db.sessions[session_key]
+    user = _db.users[s.user]
+    role = _db.roles[role_uuid]
+    org = _db.orgs[org_uuid]
+
+    # Credential must exist (sessions are cascade-deleted when credential is deleted)
+    if s.credential not in _db.credentials:
+        return None
+    credential = _db.credentials[s.credential]
 
     # Effective permissions: role's permissions that the org can grant
     # Also filter by domain if host is provided
-    org_perm_uuids = set(org.permissions)  # Set of permission UUID strings
+    org_perm_uuids = {pid for pid, p in _db.permissions.items() if org_uuid in p.orgs}
     normalized_host = normalize_host(host)
     host_without_port = normalized_host.rsplit(":", 1)[0] if normalized_host else None
 
     effective_perms = []
-    for perm_uuid_str in role.permissions:
-        if perm_uuid_str not in org_perm_uuids:
+    for perm_uuid in role.permission_set:
+        if perm_uuid not in org_perm_uuids:
             continue
-        perm_uuid = UUID(perm_uuid_str)
-        if perm_uuid not in _db._data.permissions:
+        if perm_uuid not in _db.permissions:
             continue
-        p = _db._data.permissions[perm_uuid]
+        p = _db.permissions[perm_uuid]
         # Check domain restriction
         if p.domain is not None and p.domain != host_without_port:
             continue
-        effective_perms.append(build_permission(perm_uuid))
+        effective_perms.append(_db.permissions[perm_uuid])
 
     return SessionContext(
         session=session,
@@ -516,7 +208,7 @@ def get_session_context(
         org=org,
         role=role,
         credential=credential,
-        permissions=effective_perms or None,
+        permissions=effective_perms,
     )
 
 
@@ -527,473 +219,361 @@ def get_session_context(
 
 def create_permission(perm: Permission, *, ctx: SessionContext | None = None) -> None:
     """Create a new permission."""
-    if perm.uuid in _db._data.permissions:
+    if perm.uuid in _db.permissions:
         raise ValueError(f"Permission {perm.uuid} already exists")
-    with _db.transaction("Created permission", ctx):
-        _db._data.permissions[perm.uuid] = _PermissionData(
-            scope=perm.scope,
-            display_name=perm.display_name,
-            domain=perm.domain,
-            orgs={},
-        )
-
-
-def update_permission(perm: Permission, *, ctx: SessionContext | None = None) -> None:
-    """Update a permission's scope, display_name, and domain."""
-    if perm.uuid not in _db._data.permissions:
-        raise ValueError(f"Permission {perm.uuid} not found")
-    with _db.transaction("Updated permission", ctx):
-        _db._data.permissions[perm.uuid].scope = perm.scope
-        _db._data.permissions[perm.uuid].display_name = perm.display_name
-        _db._data.permissions[perm.uuid].domain = perm.domain
+    with _db.transaction("admin:create_permission", ctx):
+        _db.permissions[perm.uuid] = perm
 
 
-def rename_permission(
-    old_scope: str,
-    new_scope: str,
+def update_permission(
+    uuid: UUID,
+    scope: str,
     display_name: str,
     domain: str | None = None,
     *,
     ctx: SessionContext | None = None,
 ) -> None:
-    """Rename a permission's scope. The UUID remains the same.
+    """Update a permission's scope, display_name, and domain.
 
-    Since roles reference permissions by UUID, no role updates are needed.
-    Note: Scopes do not need to be unique (same scope with different domains is valid).
+    Only these fields can be modified; created_at and other metadata remain immutable.
     """
-    # Find permission by old scope
-    key = None
-    for pid, p in _db._data.permissions.items():
-        if p.scope == old_scope:
-            key = pid
-            break
-    if not key:
-        raise ValueError(f"Permission with scope '{old_scope}' not found")
-
-    with _db.transaction("Renamed permission", ctx):
-        # Update the permission
-        _db._data.permissions[key].scope = new_scope
-        _db._data.permissions[key].display_name = display_name
-        _db._data.permissions[key].domain = domain
+    if uuid not in _db.permissions:
+        raise ValueError(f"Permission {uuid} not found")
+    with _db.transaction("admin:update_permission", ctx):
+        _db.permissions[uuid].scope = scope
+        _db.permissions[uuid].display_name = display_name
+        _db.permissions[uuid].domain = domain
 
 
-def delete_permission(uuid: str | UUID, *, ctx: SessionContext | None = None) -> None:
+def delete_permission(uuid: UUID, *, ctx: SessionContext | None = None) -> None:
     """Delete a permission and remove it from all roles."""
-    if isinstance(uuid, str):
-        uuid = UUID(uuid)
-    if uuid not in _db._data.permissions:
+    if uuid not in _db.permissions:
         raise ValueError(f"Permission {uuid} not found")
-    with _db.transaction("Deleted permission", ctx):
+    with _db.transaction("admin:delete_permission", ctx):
         # Remove this permission from all roles
-        for role in _db._data.roles.values():
+        for role in _db.roles.values():
             role.permissions.pop(uuid, None)
-        del _db._data.permissions[uuid]
+        del _db.permissions[uuid]
 
 
-def create_organization(org: Org, *, ctx: SessionContext | None = None) -> None:
+def create_org(org: Org, *, ctx: SessionContext | None = None) -> None:
     """Create a new organization with an Administration role.
 
     Automatically creates an 'Administration' role with auth:org:admin permission.
     """
-    if org.uuid in _db._data.orgs:
+    if org.uuid in _db.orgs:
         raise ValueError(f"Organization {org.uuid} already exists")
-    with _db.transaction("Created organization", ctx):
-        _db._data.orgs[org.uuid] = _OrgData(
-            display_name=org.display_name, created_at=datetime.now(timezone.utc)
-        )
-        # Grant listed permissions to this org (org.permissions contains UUIDs now)
-        for perm_uuid_str in org.permissions:
-            perm_uuid = (
-                UUID(perm_uuid_str) if isinstance(perm_uuid_str, str) else perm_uuid_str
-            )
-            if perm_uuid in _db._data.permissions:
-                _db._data.permissions[perm_uuid].orgs[org.uuid] = True
+    with _db.transaction("admin:create_org", ctx):
+        new_org = Org(display_name=org.display_name)
+        _db.orgs[org.uuid] = new_org
+        new_org.uuid = org.uuid
         # Create Administration role with org admin permission
-        import uuid7
 
         admin_role_uuid = uuid7.create()
         # Find the auth:org:admin permission UUID
         org_admin_perm_uuid = None
-        for pid, p in _db._data.permissions.items():
+        for pid, p in _db.permissions.items():
             if p.scope == "auth:org:admin":
                 org_admin_perm_uuid = pid
                 break
         role_permissions = {org_admin_perm_uuid: True} if org_admin_perm_uuid else {}
-        _db._data.roles[admin_role_uuid] = _RoleData(
+        admin_role = Role(
             org=org.uuid,
             display_name="Administration",
             permissions=role_permissions,
         )
+        admin_role.uuid = admin_role_uuid
+        _db.roles[admin_role_uuid] = admin_role
 
 
-def update_organization_name(
-    uuid: str | UUID,
+def update_org_name(
+    uuid: UUID,
     display_name: str,
     *,
     ctx: SessionContext | None = None,
 ) -> None:
     """Update organization display name."""
-    if isinstance(uuid, str):
-        uuid = UUID(uuid)
-    if uuid not in _db._data.orgs:
+    if uuid not in _db.orgs:
         raise ValueError(f"Organization {uuid} not found")
-    with _db.transaction("Renamed organization", ctx):
-        _db._data.orgs[uuid].display_name = display_name
+    with _db.transaction("admin:update_org_name", ctx):
+        _db.orgs[uuid].display_name = display_name
 
 
-def delete_organization(uuid: str | UUID, *, ctx: SessionContext | None = None) -> None:
+def delete_org(uuid: UUID, *, ctx: SessionContext | None = None) -> None:
     """Delete organization and all its roles/users."""
-    if isinstance(uuid, str):
-        uuid = UUID(uuid)
-    if uuid not in _db._data.orgs:
+    if uuid not in _db.orgs:
         raise ValueError(f"Organization {uuid} not found")
-    with _db.transaction("Deleted organization", ctx):
+    with _db.transaction("admin:delete_org", ctx):
         # Remove org from all permissions
-        for p in _db._data.permissions.values():
+        for p in _db.permissions.values():
             p.orgs.pop(uuid, None)
         # Delete roles in this org
-        role_uuids = [rid for rid, r in _db._data.roles.items() if r.org == uuid]
+        role_uuids = [rid for rid, r in _db.roles.items() if r.org == uuid]
         for rid in role_uuids:
-            del _db._data.roles[rid]
+            del _db.roles[rid]
         # Delete users with those roles
-        user_uuids = [uid for uid, u in _db._data.users.items() if u.role in role_uuids]
+        user_uuids = [uid for uid, u in _db.users.items() if u.role in role_uuids]
         for uid in user_uuids:
-            del _db._data.users[uid]
-        del _db._data.orgs[uuid]
+            del _db.users[uid]
+        del _db.orgs[uuid]
 
 
-def add_permission_to_organization(
-    org_uuid: str | UUID,
-    permission_id: str | UUID,
+def add_permission_to_org(
+    org_uuid: UUID,
+    permission_uuid: UUID,
     *,
     ctx: SessionContext | None = None,
 ) -> None:
     """Grant a permission to an organization by UUID."""
-    if isinstance(org_uuid, str):
-        org_uuid = UUID(org_uuid)
-    if org_uuid not in _db._data.orgs:
+    if org_uuid not in _db.orgs:
         raise ValueError(f"Organization {org_uuid} not found")
 
-    # Convert permission_id to UUID
-    if isinstance(permission_id, str):
-        try:
-            permission_uuid = UUID(permission_id)
-        except ValueError:
-            # It's a scope - look up the UUID (backwards compat)
-            for pid, p in _db._data.permissions.items():
-                if p.scope == permission_id:
-                    permission_uuid = pid
-                    break
-            else:
-                raise ValueError(f"Permission {permission_id} not found")
-    else:
-        permission_uuid = permission_id
-
-    if permission_uuid not in _db._data.permissions:
+    if permission_uuid not in _db.permissions:
         raise ValueError(f"Permission {permission_uuid} not found")
 
-    with _db.transaction("Granted org permission", ctx):
-        _db._data.permissions[permission_uuid].orgs[org_uuid] = True
+    with _db.transaction("admin:add_permission_to_org", ctx):
+        _db.permissions[permission_uuid].orgs[org_uuid] = True
 
 
-def remove_permission_from_organization(
-    org_uuid: str | UUID,
-    permission_id: str | UUID,
+def remove_permission_from_org(
+    org_uuid: UUID,
+    permission_uuid: UUID,
     *,
     ctx: SessionContext | None = None,
 ) -> None:
     """Remove a permission from an organization by UUID."""
-    if isinstance(org_uuid, str):
-        org_uuid = UUID(org_uuid)
-    if org_uuid not in _db._data.orgs:
+    if org_uuid not in _db.orgs:
         raise ValueError(f"Organization {org_uuid} not found")
 
-    # Convert permission_id to UUID
-    if isinstance(permission_id, str):
-        try:
-            permission_uuid = UUID(permission_id)
-        except ValueError:
-            # It's a scope - look up the UUID (backwards compat)
-            for pid, p in _db._data.permissions.items():
-                if p.scope == permission_id:
-                    permission_uuid = pid
-                    break
-            else:
-                return  # Permission not found, silently return
-    else:
-        permission_uuid = permission_id
-
-    if permission_uuid not in _db._data.permissions:
+    if permission_uuid not in _db.permissions:
         return  # Permission not found, silently return
 
-    with _db.transaction("Revoked org permission", ctx):
-        _db._data.permissions[permission_uuid].orgs.pop(org_uuid, None)
+    with _db.transaction("admin:remove_permission_from_org", ctx):
+        _db.permissions[permission_uuid].orgs.pop(org_uuid, None)
 
 
 def create_role(role: Role, *, ctx: SessionContext | None = None) -> None:
     """Create a new role."""
-    if role.uuid in _db._data.roles:
+    if role.uuid in _db.roles:
         raise ValueError(f"Role {role.uuid} already exists")
-    if role.org_uuid not in _db._data.orgs:
-        raise ValueError(f"Organization {role.org_uuid} not found")
-    with _db.transaction("Created role", ctx):
-        _db._data.roles[role.uuid] = _RoleData(
-            org=role.org_uuid,
-            display_name=role.display_name,
-            permissions={UUID(pid): True for pid in role.permissions},
-        )
+    if role.org not in _db.orgs:
+        raise ValueError(f"Organization {role.org} not found")
+    with _db.transaction("admin:create_role", ctx):
+        _db.roles[role.uuid] = role
 
 
 def update_role_name(
-    uuid: str | UUID,
+    uuid: UUID,
     display_name: str,
     *,
     ctx: SessionContext | None = None,
 ) -> None:
     """Update role display name."""
-    if isinstance(uuid, str):
-        uuid = UUID(uuid)
-    if uuid not in _db._data.roles:
+    if uuid not in _db.roles:
         raise ValueError(f"Role {uuid} not found")
-    with _db.transaction("Renamed role", ctx):
-        _db._data.roles[uuid].display_name = display_name
+    with _db.transaction("admin:update_role_name", ctx):
+        _db.roles[uuid].display_name = display_name
 
 
 def add_permission_to_role(
-    role_uuid: str | UUID,
-    permission_uuid: str | UUID,
+    role_uuid: UUID,
+    permission_uuid: UUID,
     *,
     ctx: SessionContext | None = None,
 ) -> None:
     """Add permission to role by UUID."""
-    if isinstance(role_uuid, str):
-        role_uuid = UUID(role_uuid)
-    if isinstance(permission_uuid, str):
-        permission_uuid = UUID(permission_uuid)
-    if role_uuid not in _db._data.roles:
+    if role_uuid not in _db.roles:
         raise ValueError(f"Role {role_uuid} not found")
-    if permission_uuid not in _db._data.permissions:
+    if permission_uuid not in _db.permissions:
         raise ValueError(f"Permission {permission_uuid} not found")
-    with _db.transaction("Granted role permission", ctx):
-        _db._data.roles[role_uuid].permissions[permission_uuid] = True
+    with _db.transaction("admin:add_permission_to_role", ctx):
+        _db.roles[role_uuid].permissions[permission_uuid] = True
 
 
 def remove_permission_from_role(
-    role_uuid: str | UUID,
-    permission_uuid: str | UUID,
+    role_uuid: UUID,
+    permission_uuid: UUID,
     *,
     ctx: SessionContext | None = None,
 ) -> None:
     """Remove permission from role by UUID."""
-    if isinstance(role_uuid, str):
-        role_uuid = UUID(role_uuid)
-    if isinstance(permission_uuid, str):
-        permission_uuid = UUID(permission_uuid)
-    if role_uuid not in _db._data.roles:
+    if role_uuid not in _db.roles:
         raise ValueError(f"Role {role_uuid} not found")
-    with _db.transaction("Revoked role permission", ctx):
-        _db._data.roles[role_uuid].permissions.pop(permission_uuid, None)
+    with _db.transaction("admin:remove_permission_from_role", ctx):
+        _db.roles[role_uuid].permissions.pop(permission_uuid, None)
 
 
-def delete_role(uuid: str | UUID, *, ctx: SessionContext | None = None) -> None:
+def delete_role(uuid: UUID, *, ctx: SessionContext | None = None) -> None:
     """Delete a role."""
-    if isinstance(uuid, str):
-        uuid = UUID(uuid)
-    if uuid not in _db._data.roles:
+    if uuid not in _db.roles:
         raise ValueError(f"Role {uuid} not found")
     # Check no users have this role
-    if any(u.role == uuid for u in _db._data.users.values()):
+    if any(u.role == uuid for u in _db.users.values()):
         raise ValueError(f"Cannot delete role {uuid}: users still assigned")
-    with _db.transaction("Deleted role", ctx):
-        del _db._data.roles[uuid]
+    with _db.transaction("admin:delete_role", ctx):
+        del _db.roles[uuid]
 
 
 def create_user(new_user: User, *, ctx: SessionContext | None = None) -> None:
     """Create a new user."""
-    if new_user.uuid in _db._data.users:
+    if new_user.uuid in _db.users:
         raise ValueError(f"User {new_user.uuid} already exists")
-    if new_user.role_uuid not in _db._data.roles:
-        raise ValueError(f"Role {new_user.role_uuid} not found")
-    with _db.transaction("Created user", ctx):
-        _db._data.users[new_user.uuid] = _UserData(
-            display_name=new_user.display_name,
-            role=new_user.role_uuid,
-            created_at=new_user.created_at or datetime.now(timezone.utc),
-            last_seen=new_user.last_seen,
-            visits=new_user.visits,
-        )
+    if new_user.role not in _db.roles:
+        raise ValueError(f"Role {new_user.role} not found")
+    with _db.transaction("admin:create_user", ctx):
+        _db.users[new_user.uuid] = new_user
 
 
 def update_user_display_name(
-    uuid: str | UUID,
+    uuid: UUID,
     display_name: str,
     *,
     ctx: SessionContext | None = None,
 ) -> None:
     """Update user display name.
 
-    For self-service (user updating own name), ctx can be None and user is derived from uuid.
-    For admin operations, ctx should be provided.
+    The acting user should be logged via ctx.
+    For self-service (user updating own name), pass user's ctx.
+    For admin operations, pass admin's ctx.
     """
     if isinstance(uuid, str):
         uuid = UUID(uuid)
-    if uuid not in _db._data.users:
+    if uuid not in _db.users:
         raise ValueError(f"User {uuid} not found")
-    # For self-service, derive user from the uuid being modified
-    user_str = str(uuid) if not ctx else None
-    with _db.transaction("Renamed user", ctx, user=user_str):
-        _db._data.users[uuid].display_name = display_name
+    with _db.transaction("update_user_display_name", ctx):
+        _db.users[uuid].display_name = display_name
 
 
 def update_user_role(
-    uuid: str | UUID,
-    role_uuid: str | UUID,
+    uuid: UUID,
+    role_uuid: UUID,
     *,
     ctx: SessionContext | None = None,
 ) -> None:
     """Update user's role."""
-    if isinstance(uuid, str):
-        uuid = UUID(uuid)
-    if isinstance(role_uuid, str):
-        role_uuid = UUID(role_uuid)
-    if uuid not in _db._data.users:
+    if uuid not in _db.users:
         raise ValueError(f"User {uuid} not found")
-    if role_uuid not in _db._data.roles:
+    if role_uuid not in _db.roles:
         raise ValueError(f"Role {role_uuid} not found")
-    with _db.transaction("Changed user role", ctx):
-        _db._data.users[uuid].role = role_uuid
+    with _db.transaction("admin:update_user_role", ctx):
+        _db.users[uuid].role = role_uuid
 
 
 def update_user_role_in_organization(
-    user_uuid: str | UUID,
+    user_uuid: UUID,
     role_name: str,
     *,
     ctx: SessionContext | None = None,
 ) -> None:
     """Update user's role by role name within their current organization."""
-    if isinstance(user_uuid, str):
-        user_uuid = UUID(user_uuid)
-    if user_uuid not in _db._data.users:
+    if user_uuid not in _db.users:
         raise ValueError(f"User {user_uuid} not found")
-    current_role_uuid = _db._data.users[user_uuid].role
-    if current_role_uuid not in _db._data.roles:
+    current_role_uuid = _db.users[user_uuid].role
+    if current_role_uuid not in _db.roles:
         raise ValueError("Current role not found")
-    org_uuid = _db._data.roles[current_role_uuid].org
+    org_uuid = _db.roles[current_role_uuid].org
     # Find role by name in the same org
     new_role_uuid = None
-    for rid, r in _db._data.roles.items():
+    for rid, r in _db.roles.items():
         if r.org == org_uuid and r.display_name == role_name:
             new_role_uuid = rid
             break
     if new_role_uuid is None:
         raise ValueError(f"Role '{role_name}' not found in organization")
-    with _db.transaction("Changed user role", ctx):
-        _db._data.users[user_uuid].role = new_role_uuid
+    with _db.transaction("admin:update_user_role", ctx):
+        _db.users[user_uuid].role = new_role_uuid
 
 
-def delete_user(uuid: str | UUID, *, ctx: SessionContext | None = None) -> None:
+def delete_user(uuid: UUID, *, ctx: SessionContext | None = None) -> None:
     """Delete user and their credentials/sessions."""
-    if isinstance(uuid, str):
-        uuid = UUID(uuid)
-    if uuid not in _db._data.users:
+    if uuid not in _db.users:
         raise ValueError(f"User {uuid} not found")
-    with _db.transaction("Deleted user", ctx):
+    with _db.transaction("admin:delete_user", ctx):
         # Delete credentials
-        cred_uuids = [cid for cid, c in _db._data.credentials.items() if c.user == uuid]
+        cred_uuids = [cid for cid, c in _db.credentials.items() if c.user == uuid]
         for cid in cred_uuids:
-            del _db._data.credentials[cid]
+            del _db.credentials[cid]
         # Delete sessions
-        sess_keys = [k for k, s in _db._data.sessions.items() if s.user == uuid]
+        sess_keys = [k for k, s in _db.sessions.items() if s.user == uuid]
         for k in sess_keys:
-            del _db._data.sessions[k]
+            del _db.sessions[k]
         # Delete reset tokens
-        token_keys = [k for k, t in _db._data.reset_tokens.items() if t.user == uuid]
+        token_keys = [k for k, t in _db.reset_tokens.items() if t.user == uuid]
         for k in token_keys:
-            del _db._data.reset_tokens[k]
-        del _db._data.users[uuid]
+            del _db.reset_tokens[k]
+        del _db.users[uuid]
 
 
 def create_credential(cred: Credential, *, ctx: SessionContext | None = None) -> None:
     """Create a new credential."""
-    if cred.uuid in _db._data.credentials:
+    if cred.uuid in _db.credentials:
         raise ValueError(f"Credential {cred.uuid} already exists")
-    if cred.user_uuid not in _db._data.users:
-        raise ValueError(f"User {cred.user_uuid} not found")
-    with _db.transaction("Added credential", ctx):
-        _db._data.credentials[cred.uuid] = _CredentialData(
-            credential_id=cred.credential_id,
-            user=cred.user_uuid,
-            aaguid=cred.aaguid,
-            public_key=cred.public_key,
-            sign_count=cred.sign_count,
-            created_at=cred.created_at,
-            last_used=cred.last_used,
-            last_verified=cred.last_verified,
-        )
+    if cred.user not in _db.users:
+        raise ValueError(f"User {cred.user} not found")
+    with _db.transaction("create_credential", ctx):
+        _db.credentials[cred.uuid] = cred
 
 
 def update_credential_sign_count(
-    uuid: str | UUID,
+    uuid: UUID,
     sign_count: int,
     last_used: datetime | None = None,
     *,
     ctx: SessionContext | None = None,
 ) -> None:
     """Update credential sign count and last_used."""
-    if isinstance(uuid, str):
-        uuid = UUID(uuid)
-    if uuid not in _db._data.credentials:
+    if uuid not in _db.credentials:
         raise ValueError(f"Credential {uuid} not found")
-    with _db.transaction("Updated credential", ctx):
-        _db._data.credentials[uuid].sign_count = sign_count
+    with _db.transaction("update_credential_sign_count", ctx):
+        _db.credentials[uuid].sign_count = sign_count
         if last_used:
-            _db._data.credentials[uuid].last_used = last_used
+            _db.credentials[uuid].last_used = last_used
 
 
 def delete_credential(
-    uuid: str | UUID,
-    user_uuid: str | UUID | None = None,
+    uuid: UUID,
+    user_uuid: UUID | None = None,
     *,
     ctx: SessionContext | None = None,
 ) -> None:
-    """Delete a credential.
+    """Delete a credential and all sessions using it.
 
     If user_uuid is provided, validates that the credential belongs to that user.
     """
-    if isinstance(uuid, str):
-        uuid = UUID(uuid)
-    if uuid not in _db._data.credentials:
+    if uuid not in _db.credentials:
         raise ValueError(f"Credential {uuid} not found")
     if user_uuid is not None:
-        if isinstance(user_uuid, str):
-            user_uuid = UUID(user_uuid)
-        cred_user = _db._data.credentials[uuid].user
+        cred_user = _db.credentials[uuid].user
         if cred_user != user_uuid:
             raise ValueError(f"Credential {uuid} does not belong to user {user_uuid}")
-    with _db.transaction("Deleted credential", ctx):
-        del _db._data.credentials[uuid]
+    with _db.transaction("delete_credential", ctx):
+        # Delete all sessions using this credential
+        keys = [k for k, s in _db.sessions.items() if s.credential == uuid]
+        for k in keys:
+            del _db.sessions[k]
+        del _db.credentials[uuid]
 
 
 def create_session(
     key: str,
     user_uuid: UUID,
     credential_uuid: UUID,
-    host: str | None,
-    ip: str | None,
-    user_agent: str | None,
+    host: str,
+    ip: str,
+    user_agent: str,
     expiry: datetime,
     *,
     ctx: SessionContext | None = None,
 ) -> None:
     """Create a new session."""
-    if key in _db._data.sessions:
+    if key in _db.sessions:
         raise ValueError("Session already exists")
-    if user_uuid not in _db._data.users:
+    if user_uuid not in _db.users:
         raise ValueError(f"User {user_uuid} not found")
-    if credential_uuid not in _db._data.credentials:
+    if credential_uuid not in _db.credentials:
         raise ValueError(f"Credential {credential_uuid} not found")
-    with _db.transaction("Created session", ctx):
-        _db._data.sessions[key] = _SessionData(
+    with _db.transaction("create_session", ctx):
+        _db.sessions[key] = Session(
             user=user_uuid,
             credential=credential_uuid,
             host=host,
@@ -1013,10 +593,10 @@ def update_session(
     ctx: SessionContext | None = None,
 ) -> None:
     """Update session metadata."""
-    if key not in _db._data.sessions:
+    if key not in _db.sessions:
         raise ValueError("Session not found")
-    with _db.transaction("Updated session", ctx):
-        s = _db._data.sessions[key]
+    with _db.transaction("update_session", ctx):
+        s = _db.sessions[key]
         if host is not None:
             s.host = host
         if ip is not None:
@@ -1035,33 +615,29 @@ def set_session_host(key: str, host: str, *, ctx: SessionContext | None = None)
 def delete_session(key: str, *, ctx: SessionContext | None = None) -> None:
     """Delete a session.
 
-    For logout (user deleting own session), ctx can be None and user is derived from session.
-    For admin operations, ctx should be provided.
+    The acting user should be logged via ctx.
+    For user logout, pass ctx of the user's session.
+    For admin terminating a session, pass admin's ctx.
     """
-    if key not in _db._data.sessions:
+    if key not in _db.sessions:
         raise ValueError("Session not found")
-    # For self-service logout, derive user from the session being deleted
-    user_str = str(_db._data.sessions[key].user) if not ctx else None
-    with _db.transaction("Deleted session", ctx, user=user_str):
-        del _db._data.sessions[key]
+    with _db.transaction("delete_session", ctx):
+        del _db.sessions[key]
 
 
 def delete_sessions_for_user(
-    user_uuid: str | UUID, *, ctx: SessionContext | None = None
+    user_uuid: UUID, *, ctx: SessionContext | None = None
 ) -> None:
     """Delete all sessions for a user.
 
-    For logout-all (user deleting own sessions), ctx can be None and user is derived from user_uuid.
-    For admin operations, ctx should be provided.
+    The acting user should be logged via ctx.
+    For user logout-all, pass ctx of the user's session.
+    For admin bulk termination, pass admin's ctx.
     """
-    if isinstance(user_uuid, str):
-        user_uuid = UUID(user_uuid)
-    # For self-service, derive user from the user_uuid param
-    user_str = str(user_uuid) if not ctx else None
-    with _db.transaction("Deleted user sessions", ctx, user=user_str):
-        keys = [k for k, s in _db._data.sessions.items() if s.user == user_uuid]
+    with _db.transaction("admin:delete_sessions_for_user", ctx):
+        keys = [k for k, s in _db.sessions.items() if s.user == user_uuid]
         for k in keys:
-            del _db._data.sessions[k]
+            del _db.sessions[k]
 
 
 def create_reset_token(
@@ -1074,28 +650,28 @@ def create_reset_token(
 ) -> None:
     """Create a reset token from a passphrase.
 
-    For self-service (user creating own recovery link), ctx can be None and user is derived from user_uuid.
-    For admin operations, ctx should be provided.
+    The acting user should be logged via ctx.
+    For self-service (user creating own recovery link), pass user's ctx.
+    For admin operations, pass admin's ctx.
+    For system operations (bootstrap), pass neither to log no user.
     """
     key = _reset_key(passphrase)
-    if key in _db._data.reset_tokens:
+    if key in _db.reset_tokens:
         raise ValueError("Reset token already exists")
-    if user_uuid not in _db._data.users:
+    if user_uuid not in _db.users:
         raise ValueError(f"User {user_uuid} not found")
-    # For self-service, derive user from the user_uuid param
-    user_str = str(user_uuid) if not ctx else None
-    with _db.transaction("Created reset token", ctx, user=user_str):
-        _db._data.reset_tokens[key] = _ResetTokenData(
+    with _db.transaction("create_reset_token", ctx):
+        _db.reset_tokens[key] = ResetToken(
             user=user_uuid, expiry=expiry, token_type=token_type
         )
 
 
 def delete_reset_token(key: bytes, *, ctx: SessionContext | None = None) -> None:
     """Delete a reset token."""
-    if key not in _db._data.reset_tokens:
+    if key not in _db.reset_tokens:
         raise ValueError("Reset token not found")
-    with _db.transaction("Deleted reset token", ctx):
-        del _db._data.reset_tokens[key]
+    with _db.transaction("delete_reset_token", ctx):
+        del _db.reset_tokens[key]
 
 
 # -------------------------------------------------------------------------
@@ -1107,16 +683,14 @@ def cleanup_expired() -> int:
     """Remove expired sessions and reset tokens. Returns count removed."""
     now = datetime.now(timezone.utc)
     count = 0
-    with _db.transaction("Cleaned up expired"):
-        expired_sessions = [k for k, s in _db._data.sessions.items() if s.expiry < now]
+    with _db.transaction("expiry"):
+        expired_sessions = [k for k, s in _db.sessions.items() if s.expiry < now]
         for k in expired_sessions:
-            del _db._data.sessions[k]
+            del _db.sessions[k]
             count += 1
-        expired_tokens = [
-            k for k, t in _db._data.reset_tokens.items() if t.expiry < now
-        ]
+        expired_tokens = [k for k, t in _db.reset_tokens.items() if t.expiry < now]
         for k in expired_tokens:
-            del _db._data.reset_tokens[k]
+            del _db.reset_tokens[k]
             count += 1
     return count
 
@@ -1132,11 +706,12 @@ def _create_token() -> str:
 
 
 def login(
-    user_uuid: str | UUID,
-    credential: Credential,
-    host: str | None,
-    ip: str | None,
-    user_agent: str | None,
+    user_uuid: UUID,
+    credential_uuid: UUID,
+    sign_count: int,
+    host: str,
+    ip: str,
+    user_agent: str,
     expiry: datetime,
 ) -> str:
     """Update user/credential on login and create session in a single transaction.
@@ -1152,24 +727,24 @@ def login(
     if isinstance(user_uuid, str):
         user_uuid = UUID(user_uuid)
     now = datetime.now(timezone.utc)
-    if user_uuid not in _db._data.users:
+    if user_uuid not in _db.users:
         raise ValueError(f"User {user_uuid} not found")
-    if credential.uuid not in _db._data.credentials:
-        raise ValueError(f"Credential {credential.uuid} not found")
+    if credential_uuid not in _db.credentials:
+        raise ValueError(f"Credential {credential_uuid} not found")
 
     session_key = _create_token()
     user_str = str(user_uuid)
-    with _db.transaction("User logged in", user=user_str):
+    with _db.transaction("login", user=user_str):
         # Update user
-        _db._data.users[user_uuid].last_seen = now
-        _db._data.users[user_uuid].visits += 1
+        _db.users[user_uuid].last_seen = now
+        _db.users[user_uuid].visits += 1
         # Update credential
-        _db._data.credentials[credential.uuid].sign_count = credential.sign_count
-        _db._data.credentials[credential.uuid].last_used = now
+        _db.credentials[credential_uuid].sign_count = sign_count
+        _db.credentials[credential_uuid].last_used = now
         # Create session
-        _db._data.sessions[session_key] = _SessionData(
+        _db.sessions[session_key] = Session(
             user=user_uuid,
-            credential=credential.uuid,
+            credential=credential_uuid,
             host=host,
             ip=ip,
             user_agent=user_agent,
@@ -1181,9 +756,9 @@ def login(
 def create_credential_session(
     user_uuid: UUID,
     credential: Credential,
-    host: str | None,
-    ip: str | None,
-    user_agent: str | None,
+    host: str,
+    ip: str,
+    user_agent: str,
     display_name: str | None = None,
     reset_key: bytes | None = None,
 ) -> str:
@@ -1197,35 +772,25 @@ def create_credential_session(
 
     Returns the generated session token.
     """
-    from paskia.config import SESSION_LIFETIME
 
     now = datetime.now(timezone.utc)
     expiry = now + SESSION_LIFETIME
     session_key = _create_token()
 
-    if user_uuid not in _db._data.users:
+    if user_uuid not in _db.users:
         raise ValueError(f"User {user_uuid} not found")
 
     user_str = str(user_uuid)
-    with _db.transaction("Registered credential", user=user_str):
+    with _db.transaction("create_credential_session", user=user_str):
         # Update display name if provided
         if display_name:
-            _db._data.users[user_uuid].display_name = display_name
+            _db.users[user_uuid].display_name = display_name
 
         # Create credential
-        _db._data.credentials[credential.uuid] = _CredentialData(
-            credential_id=credential.credential_id,
-            user=user_uuid,
-            aaguid=credential.aaguid,
-            public_key=credential.public_key,
-            sign_count=credential.sign_count,
-            created_at=credential.created_at,
-            last_used=credential.last_used,
-            last_verified=credential.last_verified,
-        )
+        _db.credentials[credential.uuid] = credential
 
         # Create session
-        _db._data.sessions[session_key] = _SessionData(
+        _db.sessions[session_key] = Session(
             user=user_uuid,
             credential=credential.uuid,
             host=host,
@@ -1236,6 +801,118 @@ def create_credential_session(
 
         # Delete reset token if provided
         if reset_key:
-            if reset_key in _db._data.reset_tokens:
-                del _db._data.reset_tokens[reset_key]
+            if reset_key in _db.reset_tokens:
+                del _db.reset_tokens[reset_key]
     return session_key
+
+
+# -------------------------------------------------------------------------
+# Bootstrap (single transaction for initial system setup)
+# -------------------------------------------------------------------------
+
+
+def bootstrap(
+    org_name: str = "Organization",
+    admin_name: str = "Admin",
+    reset_passphrase: str | None = None,
+    reset_expiry: datetime | None = None,
+) -> str:
+    """Bootstrap the entire system in a single transaction.
+
+    Creates:
+    - auth:admin permission (Master Admin)
+    - auth:org:admin permission (Org Admin)
+    - Organization with Administration role
+    - Admin user with Administration role
+    - Reset token for admin registration
+
+    This is the only way to create a new database file (besides migrate).
+    All data is created atomically - if any step fails, nothing is written.
+
+    Args:
+        org_name: Display name for the organization (default: "Organization")
+        admin_name: Display name for the admin user (default: "Admin")
+        reset_passphrase: Passphrase for the reset token (generated if not provided)
+        reset_expiry: Expiry datetime for the reset token (default: 14 days)
+
+    Returns:
+        The reset passphrase for admin registration.
+    """
+
+    # Check if system is already bootstrapped
+    for p in _db.permissions.values():
+        if p.scope == "auth:admin":
+            raise ValueError(
+                "System already bootstrapped (auth:admin permission exists)"
+            )
+
+    # Generate UUIDs upfront
+    perm_admin_uuid = uuid7.create()
+    perm_org_admin_uuid = uuid7.create()
+    org_uuid = uuid7.create()
+    role_uuid = uuid7.create()
+    user_uuid = uuid7.create()
+
+    # Generate reset token components
+    if reset_passphrase is None:
+        reset_passphrase = generate_passphrase()
+    if reset_expiry is None:
+        from paskia.authsession import reset_expires  # noqa: PLC0415
+
+        reset_expiry = reset_expires()
+    reset_key = _reset_key(reset_passphrase)
+
+    now = datetime.now(timezone.utc)
+
+    with _db.transaction("bootstrap"):
+        # Create auth:admin permission
+        perm_admin = Permission(
+            scope="auth:admin",
+            display_name="Master Admin",
+            orgs={org_uuid: True},  # Grant to org
+        )
+        perm_admin.uuid = perm_admin_uuid
+        _db.permissions[perm_admin_uuid] = perm_admin
+
+        # Create auth:org:admin permission
+        perm_org_admin = Permission(
+            scope="auth:org:admin",
+            display_name="Org Admin",
+            orgs={org_uuid: True},  # Grant to org
+        )
+        perm_org_admin.uuid = perm_org_admin_uuid
+        _db.permissions[perm_org_admin_uuid] = perm_org_admin
+
+        # Create organization
+        new_org = Org(display_name=org_name)
+        new_org.uuid = org_uuid
+        _db.orgs[org_uuid] = new_org
+
+        # Create Administration role with both permissions
+        admin_role = Role(
+            org=org_uuid,
+            display_name="Administration",
+            permissions={perm_admin_uuid: True, perm_org_admin_uuid: True},
+        )
+        admin_role.uuid = role_uuid
+        _db.roles[role_uuid] = admin_role
+
+        # Create admin user
+        admin_user = User(
+            display_name=admin_name,
+            role=role_uuid,
+            created_at=now,
+            last_seen=None,
+            visits=0,
+        )
+        admin_user.uuid = user_uuid
+        _db.users[user_uuid] = admin_user
+
+        # Create reset token
+        _db.reset_tokens[reset_key] = ResetToken(
+            user=user_uuid,
+            expiry=reset_expiry,
+            token_type="admin bootstrap",
+        )
+
+    return reset_passphrase