feat: initial WireGUI implementation — full VPN management platform

Complete Python/NiceGUI rewrite of the Wirezone (Elixir/Phoenix) VPN
management platform. All 10 implementation phases delivered.

Core stack:
- NiceGUI reactive UI with SQLModel ORM on PostgreSQL (asyncpg)
- Alembic migrations, Valkey/Redis cache, pydantic-settings config
- WireGuard management via subprocess (wg/ip/nft CLIs)
- 164 tests passing, 35% code coverage

Features:
- User/device/rule CRUD with admin and unprivileged roles
- Full device config form with per-device WG overrides
- WireGuard client config generation with QR codes
- REST API (v0) with Bearer token auth for all resources
- TOTP MFA with QR registration and challenge flow
- OIDC SSO with authlib (provider registry, auto-create users)
- Magic link passwordless sign-in via email
- SAML SP-initiated SSO with IdP metadata parsing
- WebAuthn/FIDO2 security key registration
- nftables firewall with per-user chains and masquerade
- Background tasks: WG stats polling, VPN session expiry,
  OIDC token refresh, WAN connectivity checks
- Startup reconciliation (DB ↔ WireGuard state sync)
- In-memory notification system with header badge
- Admin UI: users, devices, rules, settings (3 tabs), diagnostics
- Loguru logging with optional timestamped file output

Deployment:
- Multi-stage Dockerfile (python:3.13-slim)
- Docker Compose prod stack (bridge networking, NET_ADMIN, nftables)
- Forgejo CI: tests → semantic versioning → Docker registry push
- Health endpoint at /api/health

alembic/env.py

@@ -0,0 +1,47 @@
+import asyncio
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlmodel import SQLModel
+
+from wiregui.config import get_settings
+from wiregui.models import *  # noqa: F401, F403 — ensure all models are registered
+
+config = context.config
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = SQLModel.metadata
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode — emit SQL to script output."""
+    context.configure(
+        url=get_settings().database_url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection) -> None:
+    context.configure(connection=connection, target_metadata=target_metadata)
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_migrations_online() -> None:
+    """Run migrations in 'online' mode — connect to the database."""
+    engine = create_async_engine(get_settings().database_url)
+    async with engine.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+    await engine.dispose()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    asyncio.run(run_migrations_online())

alembic/script.py.mako

@@ -0,0 +1,27 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

alembic/versions/0741bc76e748_add_server_keypair_to_configuration.py

@@ -0,0 +1,33 @@
+"""add server keypair to configuration
+
+Revision ID: 0741bc76e748
+Revises: 647a4418cc8c
+Create Date: 2026-03-30 15:37:19.276524
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+
+
+# revision identifiers, used by Alembic.
+revision: str = '0741bc76e748'
+down_revision: Union[str, None] = '647a4418cc8c'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column('configurations', sa.Column('server_private_key', sqlmodel.sql.sqltypes.AutoString(), nullable=True))
+    op.add_column('configurations', sa.Column('server_public_key', sqlmodel.sql.sqltypes.AutoString(), nullable=True))
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_column('configurations', 'server_public_key')
+    op.drop_column('configurations', 'server_private_key')
+    # ### end Alembic commands ###

alembic/versions/647a4418cc8c_initial_schema.py

@@ -0,0 +1,171 @@
+"""initial schema
+
+Revision ID: 647a4418cc8c
+Revises: 
+Create Date: 2026-03-30 13:18:58.766259
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+
+
+# revision identifiers, used by Alembic.
+revision: str = '647a4418cc8c'
+down_revision: Union[str, None] = None
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('configurations',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('allow_unprivileged_device_management', sa.Boolean(), nullable=False),
+    sa.Column('allow_unprivileged_device_configuration', sa.Boolean(), nullable=False),
+    sa.Column('local_auth_enabled', sa.Boolean(), nullable=False),
+    sa.Column('disable_vpn_on_oidc_error', sa.Boolean(), nullable=False),
+    sa.Column('default_client_persistent_keepalive', sa.Integer(), nullable=False),
+    sa.Column('default_client_mtu', sa.Integer(), nullable=False),
+    sa.Column('default_client_endpoint', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('default_client_dns', sa.JSON(), nullable=True),
+    sa.Column('default_client_allowed_ips', sa.JSON(), nullable=True),
+    sa.Column('vpn_session_duration', sa.Integer(), nullable=False),
+    sa.Column('logo_url', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('logo_type', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('openid_connect_providers', sa.JSON(), nullable=True),
+    sa.Column('saml_identity_providers', sa.JSON(), nullable=True),
+    sa.Column('inserted_at', sa.DateTime(), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), nullable=False),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_table('connectivity_checks',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('url', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('response_code', sa.Integer(), nullable=True),
+    sa.Column('response_headers', sa.JSON(), nullable=True),
+    sa.Column('response_body', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('inserted_at', sa.DateTime(), nullable=False),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_table('users',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('email', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('password_hash', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('role', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('last_signed_in_at', sa.DateTime(), nullable=True),
+    sa.Column('last_signed_in_method', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('sign_in_token_hash', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('sign_in_token_created_at', sa.DateTime(), nullable=True),
+    sa.Column('disabled_at', sa.DateTime(), nullable=True),
+    sa.Column('inserted_at', sa.DateTime(), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), nullable=False),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index(op.f('ix_users_email'), 'users', ['email'], unique=True)
+    op.create_table('api_tokens',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('token_hash', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('expires_at', sa.DateTime(), nullable=True),
+    sa.Column('user_id', sa.Uuid(), nullable=False),
+    sa.Column('inserted_at', sa.DateTime(), nullable=False),
+    sa.ForeignKeyConstraint(['user_id'], ['users.id'], ),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index(op.f('ix_api_tokens_token_hash'), 'api_tokens', ['token_hash'], unique=True)
+    op.create_index(op.f('ix_api_tokens_user_id'), 'api_tokens', ['user_id'], unique=False)
+    op.create_table('devices',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('name', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('description', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('public_key', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('preshared_key', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('use_default_allowed_ips', sa.Boolean(), nullable=False),
+    sa.Column('use_default_dns', sa.Boolean(), nullable=False),
+    sa.Column('use_default_endpoint', sa.Boolean(), nullable=False),
+    sa.Column('use_default_mtu', sa.Boolean(), nullable=False),
+    sa.Column('use_default_persistent_keepalive', sa.Boolean(), nullable=False),
+    sa.Column('endpoint', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('mtu', sa.Integer(), nullable=True),
+    sa.Column('persistent_keepalive', sa.Integer(), nullable=True),
+    sa.Column('allowed_ips', sa.JSON(), nullable=True),
+    sa.Column('dns', sa.JSON(), nullable=True),
+    sa.Column('ipv4', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('ipv6', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('remote_ip', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('rx_bytes', sa.Integer(), nullable=True),
+    sa.Column('tx_bytes', sa.Integer(), nullable=True),
+    sa.Column('latest_handshake', sa.DateTime(), nullable=True),
+    sa.Column('user_id', sa.Uuid(), nullable=False),
+    sa.Column('inserted_at', sa.DateTime(), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), nullable=False),
+    sa.ForeignKeyConstraint(['user_id'], ['users.id'], ),
+    sa.PrimaryKeyConstraint('id'),
+    sa.UniqueConstraint('ipv4'),
+    sa.UniqueConstraint('ipv6')
+    )
+    op.create_index(op.f('ix_devices_public_key'), 'devices', ['public_key'], unique=True)
+    op.create_index(op.f('ix_devices_user_id'), 'devices', ['user_id'], unique=False)
+    op.create_table('mfa_methods',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('name', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('type', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('payload', sa.JSON(), nullable=True),
+    sa.Column('last_used_at', sa.DateTime(), nullable=True),
+    sa.Column('user_id', sa.Uuid(), nullable=False),
+    sa.Column('inserted_at', sa.DateTime(), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), nullable=False),
+    sa.ForeignKeyConstraint(['user_id'], ['users.id'], ),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index(op.f('ix_mfa_methods_user_id'), 'mfa_methods', ['user_id'], unique=False)
+    op.create_table('oidc_connections',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('provider', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('refresh_token', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('refresh_response', sa.JSON(), nullable=True),
+    sa.Column('refreshed_at', sa.DateTime(), nullable=True),
+    sa.Column('user_id', sa.Uuid(), nullable=False),
+    sa.Column('inserted_at', sa.DateTime(), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), nullable=False),
+    sa.ForeignKeyConstraint(['user_id'], ['users.id'], ),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index(op.f('ix_oidc_connections_user_id'), 'oidc_connections', ['user_id'], unique=False)
+    op.create_table('rules',
+    sa.Column('id', sa.Uuid(), nullable=False),
+    sa.Column('action', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('destination', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('port_type', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('port_range', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('user_id', sa.Uuid(), nullable=True),
+    sa.Column('inserted_at', sa.DateTime(), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), nullable=False),
+    sa.ForeignKeyConstraint(['user_id'], ['users.id'], ),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index(op.f('ix_rules_user_id'), 'rules', ['user_id'], unique=False)
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index(op.f('ix_rules_user_id'), table_name='rules')
+    op.drop_table('rules')
+    op.drop_index(op.f('ix_oidc_connections_user_id'), table_name='oidc_connections')
+    op.drop_table('oidc_connections')
+    op.drop_index(op.f('ix_mfa_methods_user_id'), table_name='mfa_methods')
+    op.drop_table('mfa_methods')
+    op.drop_index(op.f('ix_devices_user_id'), table_name='devices')
+    op.drop_index(op.f('ix_devices_public_key'), table_name='devices')
+    op.drop_table('devices')
+    op.drop_index(op.f('ix_api_tokens_user_id'), table_name='api_tokens')
+    op.drop_index(op.f('ix_api_tokens_token_hash'), table_name='api_tokens')
+    op.drop_table('api_tokens')
+    op.drop_index(op.f('ix_users_email'), table_name='users')
+    op.drop_table('users')
+    op.drop_table('connectivity_checks')
+    op.drop_table('configurations')
+    # ### end Alembic commands ###