Upload 12 files

core/models/__init__.py

@@ -0,0 +1,37 @@
+"""
+Core models for PyRunner.
+
+This module exports all models for easy importing:
+    from core.models import User, MagicToken, UserInvite, PasswordResetToken, Environment, Script, Run, ScriptSchedule, ScheduleHistory, GlobalSettings, PackageOperation, Secret, Tag, DataStore, DataStoreEntry, DataStoreAPIToken
+"""
+
+from .user import User, MagicToken, UserInvite, PasswordResetToken
+from .environment import Environment
+from .script import Script
+from .run import Run
+from .schedule import ScriptSchedule, ScheduleHistory
+from .settings import GlobalSettings
+from .package import PackageOperation
+from .secret import Secret
+from .tag import Tag
+from .datastore import DataStore, DataStoreEntry
+from .api_token import DataStoreAPIToken
+
+__all__ = [
+    "User",
+    "MagicToken",
+    "UserInvite",
+    "PasswordResetToken",
+    "Environment",
+    "Script",
+    "Run",
+    "ScriptSchedule",
+    "ScheduleHistory",
+    "GlobalSettings",
+    "PackageOperation",
+    "Secret",
+    "Tag",
+    "DataStore",
+    "DataStoreEntry",
+    "DataStoreAPIToken",
+]

core/models/api_token.py

@@ -0,0 +1,104 @@
+"""
+API Token model for datastore API access.
+"""
+
+import secrets
+import uuid
+
+from django.conf import settings
+from django.db import models
+
+
+class DataStoreAPIToken(models.Model):
+    """
+    API token for accessing datastore data via REST API.
+    Tokens can be scoped to a single datastore or grant access to all datastores.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+
+    # The actual token value (64-char URL-safe string)
+    token = models.CharField(
+        max_length=64,
+        unique=True,
+        db_index=True,
+        help_text="API token value (auto-generated)",
+    )
+
+    # Friendly name to identify this token
+    name = models.CharField(
+        max_length=100,
+        help_text="Friendly name for this token",
+    )
+
+    # Optional: Restrict to specific datastore (null = global access to all datastores)
+    datastore = models.ForeignKey(
+        "DataStore",
+        on_delete=models.CASCADE,
+        null=True,
+        blank=True,
+        related_name="api_tokens",
+        help_text="If set, token only grants access to this datastore. Leave empty for global access.",
+    )
+
+    # Timestamps
+    created_at = models.DateTimeField(auto_now_add=True)
+    last_used_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="Last time this token was used",
+    )
+    expires_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="Optional expiration date. Leave empty for no expiration.",
+    )
+
+    # Who created this token
+    created_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="created_api_tokens",
+    )
+
+    # Active flag for soft-disable
+    is_active = models.BooleanField(
+        default=True,
+        help_text="Inactive tokens cannot be used for API access",
+    )
+
+    class Meta:
+        db_table = "datastore_api_tokens"
+        verbose_name = "API token"
+        verbose_name_plural = "API tokens"
+        ordering = ["-created_at"]
+
+    def __str__(self):
+        if self.datastore:
+            return f"{self.name} ({self.datastore.name})"
+        return f"{self.name} (global)"
+
+    @staticmethod
+    def generate_token() -> str:
+        """Generate a secure random API token (64 chars, URL-safe)."""
+        return secrets.token_urlsafe(48)
+
+    def get_masked_token(self) -> str:
+        """Return a masked version of the token for display."""
+        if len(self.token) <= 12:
+            return "*" * len(self.token)
+        return f"{self.token[:8]}...{self.token[-4:]}"
+
+    @property
+    def is_global(self) -> bool:
+        """Return True if this is a global token (not scoped to a datastore)."""
+        return self.datastore is None
+
+    @property
+    def scope_display(self) -> str:
+        """Return a human-readable scope description."""
+        if self.datastore:
+            return f"Datastore: {self.datastore.name}"
+        return "All datastores"

core/models/datastore.py

@@ -0,0 +1,113 @@
+"""
+DataStore models for script data persistence.
+"""
+
+import json
+import uuid
+
+from django.conf import settings
+from django.db import models
+
+
+class DataStore(models.Model):
+    """
+    A named data store that scripts can use for simple key-value storage.
+    Data stores are backed by the instance SQLite database.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+
+    name = models.CharField(
+        max_length=100,
+        unique=True,
+        help_text="Unique name for this data store (used in scripts)",
+    )
+
+    description = models.TextField(
+        blank=True,
+        help_text="Optional description of what this data store is used for",
+    )
+
+    # Timestamps
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    # Who created this data store
+    created_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="created_datastores",
+    )
+
+    class Meta:
+        db_table = "datastores"
+        verbose_name = "data store"
+        verbose_name_plural = "data stores"
+        ordering = ["name"]
+
+    def __str__(self):
+        return self.name
+
+    @property
+    def entry_count(self) -> int:
+        """Return the number of entries in this data store."""
+        return self.entries.count()
+
+
+class DataStoreEntry(models.Model):
+    """
+    A key-value entry in a data store.
+    Values are stored as JSON to support various data types.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+
+    datastore = models.ForeignKey(
+        DataStore,
+        on_delete=models.CASCADE,
+        related_name="entries",
+    )
+
+    key = models.CharField(
+        max_length=255,
+        help_text="Unique key within this data store",
+    )
+
+    # Value stored as JSON text (supports strings, numbers, lists, dicts, etc.)
+    value_json = models.TextField(
+        help_text="JSON-encoded value",
+    )
+
+    # Timestamps
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        db_table = "datastore_entries"
+        verbose_name = "data store entry"
+        verbose_name_plural = "data store entries"
+        unique_together = [["datastore", "key"]]
+        ordering = ["key"]
+        indexes = [
+            models.Index(fields=["datastore", "key"]),
+        ]
+
+    def __str__(self):
+        return f"{self.datastore.name}:{self.key}"
+
+    def get_value(self):
+        """Deserialize and return the stored value."""
+        return json.loads(self.value_json)
+
+    def set_value(self, value) -> None:
+        """Serialize and store a value."""
+        self.value_json = json.dumps(value)
+
+    def get_display_value(self) -> str:
+        """Return a displayable version of the value (truncated if too long)."""
+        value = self.value_json
+        if len(value) > 100:
+            return value[:100] + "..."
+        return value

core/models/environment.py

@@ -0,0 +1,151 @@
+"""
+Environment model for isolated Python virtual environments.
+"""
+
+import os
+import re
+import uuid
+
+from django.conf import settings
+from django.core.exceptions import ValidationError
+from django.db import models
+
+
+def validate_environment_path(value: str) -> None:
+    """
+    Validate environment path to prevent path traversal attacks.
+
+    Only allows simple directory names: alphanumeric, hyphens, underscores.
+    Blocks: .., absolute paths, drive letters, special characters.
+    """
+    if not value:
+        raise ValidationError("Path cannot be empty")
+
+    # Block path traversal sequences
+    if ".." in value:
+        raise ValidationError("Path cannot contain '..'")
+
+    # Block absolute paths (Unix and Windows)
+    if value.startswith("/") or value.startswith("\\"):
+        raise ValidationError("Path cannot be absolute")
+
+    # Block Windows drive letters (e.g., C:, D:)
+    if len(value) >= 2 and value[1] == ":":
+        raise ValidationError("Path cannot contain drive letters")
+
+    # Only allow safe characters: alphanumeric, hyphen, underscore
+    if not re.match(r"^[a-zA-Z0-9_-]+$", value):
+        raise ValidationError(
+            "Path can only contain letters, numbers, hyphens, and underscores"
+        )
+
+    # Length limit
+    if len(value) > 100:
+        raise ValidationError("Path cannot exceed 100 characters")
+
+
+class Environment(models.Model):
+    """
+    Represents an isolated Python virtual environment for script execution.
+    Each environment has its own set of installed packages.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    name = models.CharField(max_length=100)
+    description = models.TextField(blank=True)
+
+    # Path relative to ENVIRONMENTS_ROOT
+    path = models.CharField(
+        max_length=255,
+        unique=True,
+        validators=[validate_environment_path],
+        help_text="Directory name within the environments folder",
+    )
+
+    # Python version info (captured at creation time)
+    python_version = models.CharField(max_length=20, blank=True)
+
+    # Installed packages (pip freeze output)
+    requirements = models.TextField(
+        blank=True,
+        help_text="Installed packages in pip requirements format",
+    )
+
+    is_default = models.BooleanField(
+        default=False,
+        help_text="Whether this is the default environment for new scripts",
+    )
+    is_active = models.BooleanField(
+        default=True,
+        help_text="Whether this environment is available for use",
+    )
+
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+    created_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="created_environments",
+    )
+
+    class Meta:
+        db_table = "environments"
+        verbose_name = "environment"
+        verbose_name_plural = "environments"
+        ordering = ["-is_default", "name"]
+
+    def __str__(self):
+        suffix = " (default)" if self.is_default else ""
+        return f"{self.name}{suffix}"
+
+    def save(self, *args, **kwargs):
+        # Ensure only one environment is marked as default
+        if self.is_default:
+            Environment.objects.filter(is_default=True).exclude(pk=self.pk).update(
+                is_default=False
+            )
+        super().save(*args, **kwargs)
+
+    def get_full_path(self) -> str:
+        """Return the absolute path to this environment's directory."""
+        # Runtime validation as defense-in-depth
+        validate_environment_path(self.path)
+        return os.path.join(settings.ENVIRONMENTS_ROOT, self.path)
+
+    def get_python_executable(self) -> str:
+        """Return the absolute path to this environment's Python executable."""
+        base_path = self.get_full_path()
+        if os.name == "nt":
+            # Windows
+            return os.path.join(base_path, "Scripts", "python.exe")
+        else:
+            # Unix/Linux/macOS
+            return os.path.join(base_path, "bin", "python")
+
+    def get_pip_executable(self) -> str:
+        """Return the absolute path to this environment's pip executable."""
+        base_path = self.get_full_path()
+        if os.name == "nt":
+            return os.path.join(base_path, "Scripts", "pip.exe")
+        else:
+            return os.path.join(base_path, "bin", "pip")
+
+    def exists(self) -> bool:
+        """Check if the environment directory exists on disk."""
+        return os.path.isdir(self.get_full_path())
+
+    def python_exists(self) -> bool:
+        """Check if the Python executable exists."""
+        return os.path.isfile(self.get_python_executable())
+
+    @property
+    def script_count(self) -> int:
+        """Return the number of scripts using this environment."""
+        return self.scripts.count()
+
+    @property
+    def can_delete(self) -> bool:
+        """Check if this environment can be deleted (no scripts assigned)."""
+        return self.script_count == 0 and not self.is_default

core/models/package.py

@@ -0,0 +1,117 @@
+"""
+Package operation model for tracking async pip operations.
+"""
+
+import uuid
+
+from django.conf import settings
+from django.db import models
+
+
+class PackageOperation(models.Model):
+    """
+    Tracks async package installation/uninstallation operations.
+    Used to provide progress feedback in the UI.
+    """
+
+    class Operation(models.TextChoices):
+        INSTALL = "install", "Install"
+        UNINSTALL = "uninstall", "Uninstall"
+        BULK_INSTALL = "bulk_install", "Bulk Install"
+
+    class Status(models.TextChoices):
+        PENDING = "pending", "Pending"
+        RUNNING = "running", "Running"
+        SUCCESS = "success", "Success"
+        FAILED = "failed", "Failed"
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+
+    environment = models.ForeignKey(
+        "core.Environment",
+        on_delete=models.CASCADE,
+        related_name="package_operations",
+    )
+
+    operation = models.CharField(
+        max_length=20,
+        choices=Operation.choices,
+    )
+
+    package_spec = models.CharField(
+        max_length=500,
+        help_text="Package specification (e.g., 'requests==2.31.0') or requirements content for bulk install",
+    )
+
+    status = models.CharField(
+        max_length=20,
+        choices=Status.choices,
+        default=Status.PENDING,
+    )
+
+    output = models.TextField(
+        blank=True,
+        help_text="pip stdout",
+    )
+
+    error = models.TextField(
+        blank=True,
+        help_text="pip stderr",
+    )
+
+    task_id = models.CharField(
+        max_length=100,
+        blank=True,
+        help_text="django-q2 task ID for tracking",
+    )
+
+    created_at = models.DateTimeField(auto_now_add=True)
+    started_at = models.DateTimeField(null=True, blank=True)
+    completed_at = models.DateTimeField(null=True, blank=True)
+
+    created_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="package_operations",
+    )
+
+    class Meta:
+        db_table = "package_operations"
+        ordering = ["-created_at"]
+        verbose_name = "package operation"
+        verbose_name_plural = "package operations"
+
+    def __str__(self):
+        return f"{self.get_operation_display()} {self.package_spec[:50]} ({self.status})"
+
+    @property
+    def is_finished(self) -> bool:
+        """Check if the operation has completed (success or failed)."""
+        return self.status in (self.Status.SUCCESS, self.Status.FAILED)
+
+    @property
+    def is_successful(self) -> bool:
+        """Check if the operation completed successfully."""
+        return self.status == self.Status.SUCCESS
+
+    @property
+    def duration(self):
+        """Return the duration of the operation if completed."""
+        if self.started_at and self.completed_at:
+            return self.completed_at - self.started_at
+        return None
+
+    @property
+    def duration_display(self) -> str:
+        """Return a human-readable duration string."""
+        duration = self.duration
+        if not duration:
+            return "-"
+        total_seconds = int(duration.total_seconds())
+        if total_seconds < 60:
+            return f"{total_seconds}s"
+        minutes = total_seconds // 60
+        seconds = total_seconds % 60
+        return f"{minutes}m {seconds}s"

core/models/run.py

@@ -0,0 +1,179 @@
+"""
+Run model for tracking script execution history.
+"""
+
+import uuid
+
+from django.conf import settings
+from django.db import models
+
+from .script import Script
+
+
+class Run(models.Model):
+    """
+    Represents a single execution of a script.
+    Tracks timing, output, and status of each run.
+    """
+
+    class Status(models.TextChoices):
+        PENDING = "pending", "Pending"
+        RUNNING = "running", "Running"
+        SUCCESS = "success", "Success"
+        FAILED = "failed", "Failed"
+        TIMEOUT = "timeout", "Timeout"
+        CANCELLED = "cancelled", "Cancelled"
+
+    class TriggerType(models.TextChoices):
+        MANUAL = "manual", "Manual"
+        SCHEDULED = "scheduled", "Scheduled"
+        API = "api", "API"
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    script = models.ForeignKey(
+        Script,
+        on_delete=models.CASCADE,
+        related_name="runs",
+    )
+
+    # Execution status
+    status = models.CharField(
+        max_length=20,
+        choices=Status.choices,
+        default=Status.PENDING,
+        db_index=True,
+    )
+    exit_code = models.IntegerField(
+        null=True,
+        blank=True,
+        help_text="Process exit code (0 = success)",
+    )
+
+    # Output capture
+    stdout = models.TextField(
+        blank=True,
+        help_text="Standard output from script execution",
+    )
+    stderr = models.TextField(
+        blank=True,
+        help_text="Standard error from script execution",
+    )
+
+    # Timing
+    started_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="When execution started",
+    )
+    ended_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="When execution ended",
+    )
+
+    # Snapshot of script code at execution time (for audit trail)
+    code_snapshot = models.TextField(
+        blank=True,
+        help_text="Copy of script code at time of execution",
+    )
+
+    # Who triggered the run
+    triggered_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="triggered_runs",
+    )
+
+    # django-q2 task tracking
+    task_id = models.CharField(
+        max_length=100,
+        blank=True,
+        db_index=True,
+        help_text="django-q2 task ID for tracking async execution",
+    )
+
+    # How this run was triggered
+    trigger_type = models.CharField(
+        max_length=20,
+        choices=TriggerType.choices,
+        default=TriggerType.MANUAL,
+        help_text="How this run was triggered",
+    )
+
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        db_table = "runs"
+        verbose_name = "run"
+        verbose_name_plural = "runs"
+        ordering = ["-created_at"]
+        indexes = [
+            models.Index(fields=["script", "-created_at"]),
+            models.Index(fields=["status", "-created_at"]),
+        ]
+
+    def __str__(self):
+        return f"Run {self.id} - {self.script.name} ({self.status})"
+
+    @property
+    def duration(self) -> float | None:
+        """Return the duration in seconds, or None if not completed."""
+        if self.started_at and self.ended_at:
+            return (self.ended_at - self.started_at).total_seconds()
+        return None
+
+    @property
+    def duration_display(self) -> str:
+        """Return a human-readable duration string."""
+        d = self.duration
+        if d is None:
+            return "-"
+        if d < 60:
+            return f"{d:.1f}s"
+        minutes = int(d // 60)
+        seconds = d % 60
+        if minutes < 60:
+            return f"{minutes}m {seconds:.0f}s"
+        hours = minutes // 60
+        minutes = minutes % 60
+        return f"{hours}h {minutes}m"
+
+    @property
+    def is_finished(self) -> bool:
+        """Check if the run has completed (successfully or not)."""
+        return self.status in [
+            self.Status.SUCCESS,
+            self.Status.FAILED,
+            self.Status.TIMEOUT,
+            self.Status.CANCELLED,
+        ]
+
+    @property
+    def is_successful(self) -> bool:
+        """Check if the run completed successfully."""
+        return self.status == self.Status.SUCCESS
+
+    @property
+    def has_output(self) -> bool:
+        """Check if there is any output (stdout or stderr)."""
+        return bool(self.stdout or self.stderr)
+
+    def get_stdout_preview(self, max_lines: int = 10) -> str:
+        """Return a preview of stdout (last N lines)."""
+        if not self.stdout:
+            return ""
+        lines = self.stdout.split("\n")
+        if len(lines) <= max_lines:
+            return self.stdout
+        return "...\n" + "\n".join(lines[-max_lines:])
+
+    def get_stderr_preview(self, max_lines: int = 10) -> str:
+        """Return a preview of stderr (last N lines)."""
+        if not self.stderr:
+            return ""
+        lines = self.stderr.split("\n")
+        if len(lines) <= max_lines:
+            return self.stderr
+        return "...\n" + "\n".join(lines[-max_lines:])

core/models/schedule.py

@@ -0,0 +1,228 @@
+"""
+Schedule models for script execution scheduling.
+"""
+
+import uuid
+
+from django.conf import settings
+from django.db import models
+
+from .script import Script
+
+
+class ScriptSchedule(models.Model):
+    """
+    Represents a schedule configuration for a Script.
+    Links to django-q2 Schedule objects for actual task scheduling.
+    """
+
+    class RunMode(models.TextChoices):
+        MANUAL = "manual", "Manual"
+        INTERVAL = "interval", "Interval"
+        DAILY = "daily", "Daily"
+        WEEKLY = "weekly", "Weekly"
+        MONTHLY = "monthly", "Monthly"
+
+    class IntervalChoice(models.IntegerChoices):
+        FIVE_MINUTES = 5, "Every 5 minutes"
+        TEN_MINUTES = 10, "Every 10 minutes"
+        FIFTEEN_MINUTES = 15, "Every 15 minutes"
+        THIRTY_MINUTES = 30, "Every 30 minutes"
+        ONE_HOUR = 60, "Every hour"
+        TWO_HOURS = 120, "Every 2 hours"
+        SIX_HOURS = 360, "Every 6 hours"
+        TWELVE_HOURS = 720, "Every 12 hours"
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+
+    # One-to-one relationship with Script
+    script = models.OneToOneField(
+        Script,
+        on_delete=models.CASCADE,
+        related_name="schedule",
+    )
+
+    # Run mode selection
+    run_mode = models.CharField(
+        max_length=20,
+        choices=RunMode.choices,
+        default=RunMode.MANUAL,
+    )
+
+    # Interval mode configuration
+    interval_minutes = models.PositiveIntegerField(
+        null=True,
+        blank=True,
+        choices=IntervalChoice.choices,
+        help_text="Interval in minutes (for interval mode)",
+    )
+
+    # Daily mode configuration - stored as JSON array of time strings
+    daily_times = models.JSONField(
+        default=list,
+        blank=True,
+        help_text='List of times in HH:MM format, e.g., ["09:00", "18:00"]',
+    )
+
+    # Timezone for scheduled runs
+    timezone = models.CharField(
+        max_length=50,
+        default="UTC",
+        help_text="Timezone for scheduled runs (e.g., 'America/New_York')",
+    )
+
+    # Weekly mode configuration
+    weekly_days = models.JSONField(
+        default=list,
+        blank=True,
+        help_text='Days of week [0-6] where 0=Monday, e.g., [0, 2, 4] for Mon/Wed/Fri',
+    )
+    weekly_times = models.JSONField(
+        default=list,
+        blank=True,
+        help_text='List of times in HH:MM format for weekly mode',
+    )
+
+    # Monthly mode configuration
+    monthly_days = models.JSONField(
+        default=list,
+        blank=True,
+        help_text='Days of month [1-31], e.g., [1, 15] for 1st and 15th',
+    )
+    monthly_times = models.JSONField(
+        default=list,
+        blank=True,
+        help_text='List of times in HH:MM format for monthly mode',
+    )
+
+    # Schedule state
+    is_active = models.BooleanField(
+        default=True,
+        help_text="Whether this schedule is active (can be paused without deleting)",
+    )
+
+    # Link to django-q2 Schedule objects (can be multiple for daily with multiple times)
+    # Stored as JSON array of django-q2 Schedule IDs
+    q_schedule_ids = models.JSONField(
+        default=list,
+        blank=True,
+        help_text="django-q2 Schedule object IDs",
+    )
+
+    # Tracking
+    next_run = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="Cached next scheduled run time",
+    )
+    last_scheduled_run = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="When the schedule last triggered a run",
+    )
+
+    # Metadata
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+    created_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="created_schedules",
+    )
+
+    class Meta:
+        db_table = "script_schedules"
+        verbose_name = "script schedule"
+        verbose_name_plural = "script schedules"
+
+    def __str__(self):
+        return f"Schedule for {self.script.name} ({self.run_mode})"
+
+    @property
+    def is_scheduled(self) -> bool:
+        """Check if this script has an active schedule (not manual)."""
+        return self.run_mode != self.RunMode.MANUAL and self.is_active
+
+    DAY_NAMES = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
+
+    @property
+    def schedule_display(self) -> str:
+        """Human-readable schedule description."""
+        if self.run_mode == self.RunMode.MANUAL:
+            return "Manual"
+        elif self.run_mode == self.RunMode.INTERVAL:
+            # Find the display label from choices
+            for value, label in self.IntervalChoice.choices:
+                if value == self.interval_minutes:
+                    return label
+            return f"Every {self.interval_minutes} minutes"
+        elif self.run_mode == self.RunMode.DAILY:
+            times = ", ".join(self.daily_times) if self.daily_times else "No times set"
+            return f"Daily at {times} ({self.timezone})"
+        elif self.run_mode == self.RunMode.WEEKLY:
+            days = ", ".join(self.DAY_NAMES[d] for d in sorted(self.weekly_days)) if self.weekly_days else "No days set"
+            times = ", ".join(self.weekly_times) if self.weekly_times else "No times set"
+            return f"Weekly on {days} at {times} ({self.timezone})"
+        elif self.run_mode == self.RunMode.MONTHLY:
+            days = ", ".join(str(d) for d in sorted(self.monthly_days)) if self.monthly_days else "No days set"
+            times = ", ".join(self.monthly_times) if self.monthly_times else "No times set"
+            return f"Monthly on day {days} at {times} ({self.timezone})"
+        return "Unknown"
+
+
+class ScheduleHistory(models.Model):
+    """
+    Tracks changes to script schedules for audit purposes.
+    """
+
+    class ChangeType(models.TextChoices):
+        CREATED = "created", "Created"
+        UPDATED = "updated", "Updated"
+        ENABLED = "enabled", "Enabled"
+        DISABLED = "disabled", "Disabled"
+        DELETED = "deleted", "Deleted"
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+
+    schedule = models.ForeignKey(
+        ScriptSchedule,
+        on_delete=models.CASCADE,
+        related_name="history",
+    )
+
+    change_type = models.CharField(
+        max_length=20,
+        choices=ChangeType.choices,
+    )
+
+    # Snapshot of schedule configuration at time of change
+    previous_config = models.JSONField(
+        null=True,
+        blank=True,
+        help_text="Previous schedule configuration",
+    )
+    new_config = models.JSONField(
+        null=True,
+        blank=True,
+        help_text="New schedule configuration",
+    )
+
+    changed_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+    )
+
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        db_table = "schedule_history"
+        verbose_name = "schedule history"
+        verbose_name_plural = "schedule history entries"
+        ordering = ["-created_at"]
+
+    def __str__(self):
+        return f"{self.change_type} - {self.schedule.script.name} at {self.created_at}"

core/models/script.py

@@ -0,0 +1,205 @@
+"""
+Script model for user-created Python scripts.
+"""
+
+import secrets
+import uuid
+
+from django.conf import settings
+from django.db import models
+
+from .environment import Environment
+
+
+class Script(models.Model):
+    """
+    Represents a Python script that can be executed.
+    Scripts are associated with an environment and can be run manually or on schedule.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    name = models.CharField(max_length=200)
+    description = models.TextField(blank=True)
+
+    # The actual Python code
+    code = models.TextField(help_text="Python code to execute")
+
+    # Execution settings
+    environment = models.ForeignKey(
+        Environment,
+        on_delete=models.PROTECT,
+        related_name="scripts",
+        help_text="Python environment to use for execution",
+    )
+
+    # Tags for categorization
+    tags = models.ManyToManyField(
+        "Tag",
+        blank=True,
+        related_name="scripts",
+        help_text="Tags for organizing and filtering scripts",
+    )
+
+    timeout_seconds = models.PositiveIntegerField(
+        default=3600,  # 1 hour default
+        help_text="Maximum execution time in seconds (default: 1 hour, max: 24 hours)",
+    )
+
+    # Status
+    is_enabled = models.BooleanField(
+        default=True,
+        help_text="Whether this script can be executed",
+    )
+
+    # Webhook
+    webhook_token = models.CharField(
+        max_length=64,
+        unique=True,
+        null=True,
+        blank=True,
+        db_index=True,
+        help_text="Unique token for webhook URL (auto-generated)",
+    )
+
+    # Notification settings
+    class NotifyOn(models.TextChoices):
+        NEVER = "never", "Never"
+        FAILURE = "failure", "On Failure"
+        SUCCESS = "success", "On Success"
+        BOTH = "both", "On Success and Failure"
+
+    notify_on = models.CharField(
+        max_length=20,
+        choices=NotifyOn.choices,
+        default=NotifyOn.NEVER,
+        help_text="When to send notifications for this script",
+    )
+    notify_email = models.EmailField(
+        blank=True,
+        help_text="Override email for this script (uses global default if empty)",
+    )
+    notify_webhook_url = models.URLField(
+        blank=True,
+        max_length=500,
+        help_text="URL to POST notification webhooks to",
+    )
+    notify_webhook_enabled = models.BooleanField(
+        default=False,
+        help_text="Enable webhook notifications for this script",
+    )
+
+    # Retention overrides (null = use global settings)
+    retention_days_override = models.PositiveIntegerField(
+        null=True,
+        blank=True,
+        help_text="Override global retention days for this script",
+    )
+    retention_count_override = models.PositiveIntegerField(
+        null=True,
+        blank=True,
+        help_text="Override global retention count for this script",
+    )
+
+    # Archive fields (soft delete)
+    archived_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="When this script was archived (null = not archived)",
+    )
+    archived_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="archived_scripts",
+    )
+
+    # Metadata
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+    created_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="scripts",
+    )
+
+    class Meta:
+        db_table = "scripts"
+        verbose_name = "script"
+        verbose_name_plural = "scripts"
+        ordering = ["-updated_at"]
+
+    def __str__(self):
+        if self.is_archived:
+            return f"{self.name} (archived)"
+        status = "enabled" if self.is_enabled else "disabled"
+        return f"{self.name} ({status})"
+
+    @property
+    def is_archived(self) -> bool:
+        """Check if this script is archived."""
+        return self.archived_at is not None
+
+    @property
+    def can_run(self) -> bool:
+        """Check if this script can be executed (enabled and not archived)."""
+        return self.is_enabled and not self.is_archived
+
+    @property
+    def last_run(self):
+        """Return the most recent run for this script."""
+        return self.runs.order_by("-created_at").first()
+
+    @property
+    def last_successful_run(self):
+        """Return the most recent successful run for this script."""
+        return self.runs.filter(status="success").order_by("-created_at").first()
+
+    @property
+    def run_count(self) -> int:
+        """Return the total number of runs for this script."""
+        return self.runs.count()
+
+    @property
+    def success_rate(self) -> float | None:
+        """Return the success rate as a percentage, or None if no runs."""
+        total = self.run_count
+        if total == 0:
+            return None
+        successful = self.runs.filter(status="success").count()
+        return (successful / total) * 100
+
+    def get_code_preview(self, max_lines: int = 5) -> str:
+        """Return a preview of the script code (first N lines)."""
+        lines = self.code.split("\n")[:max_lines]
+        preview = "\n".join(lines)
+        if len(self.code.split("\n")) > max_lines:
+            preview += "\n..."
+        return preview
+
+    @staticmethod
+    def generate_webhook_token() -> str:
+        """Generate a secure random webhook token (64 chars, URL-safe)."""
+        return secrets.token_urlsafe(48)  # 48 bytes = 64 chars in base64
+
+    def create_webhook_token(self) -> str:
+        """Create and save a new webhook token for this script."""
+        self.webhook_token = self.generate_webhook_token()
+        self.save(update_fields=["webhook_token", "updated_at"])
+        return self.webhook_token
+
+    def regenerate_webhook_token(self) -> str:
+        """Regenerate the webhook token, invalidating the old one."""
+        return self.create_webhook_token()
+
+    def clear_webhook_token(self) -> None:
+        """Remove the webhook token, disabling webhook access."""
+        self.webhook_token = None
+        self.save(update_fields=["webhook_token", "updated_at"])
+
+    @property
+    def has_webhook(self) -> bool:
+        """Check if this script has a webhook token configured."""
+        return bool(self.webhook_token)

core/models/secret.py

@@ -0,0 +1,85 @@
+"""
+Secret model for encrypted credential storage.
+"""
+
+import uuid
+
+from django.conf import settings
+from django.db import models
+
+
+class Secret(models.Model):
+    """
+    Stores encrypted secrets (API keys, credentials) that are injected
+    as environment variables when scripts run.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+
+    # Key name - must be uppercase with underscores (e.g., API_KEY, DATABASE_URL)
+    key = models.CharField(
+        max_length=100,
+        unique=True,
+        help_text="Environment variable name (uppercase, underscores allowed)",
+    )
+
+    # Encrypted value - stores the Fernet-encrypted bytes as base64 string
+    encrypted_value = models.TextField(
+        help_text="Fernet-encrypted secret value",
+    )
+
+    # Optional description to help remember what this secret is for
+    description = models.TextField(
+        blank=True,
+        help_text="Optional description of what this secret is used for",
+    )
+
+    # Timestamps
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    # Who created this secret
+    created_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="created_secrets",
+    )
+
+    class Meta:
+        db_table = "secrets"
+        verbose_name = "secret"
+        verbose_name_plural = "secrets"
+        ordering = ["key"]
+
+    def __str__(self):
+        return self.key
+
+    def get_masked_value(self) -> str:
+        """
+        Return a masked preview of the decrypted value.
+        Shows first 3 and last 3 characters with ... in between.
+        Example: "sk-abc123xyz789" -> "sk-...789"
+        """
+        from core.services import EncryptionService
+
+        try:
+            value = EncryptionService.decrypt(self.encrypted_value)
+            if len(value) <= 8:
+                return "*" * len(value)
+            return f"{value[:3]}...{value[-3:]}"
+        except Exception:
+            return "[decryption error]"
+
+    def get_decrypted_value(self) -> str:
+        """Return the decrypted secret value."""
+        from core.services import EncryptionService
+
+        return EncryptionService.decrypt(self.encrypted_value)
+
+    def set_value(self, plaintext: str) -> None:
+        """Encrypt and store a new value."""
+        from core.services import EncryptionService
+
+        self.encrypted_value = EncryptionService.encrypt(plaintext)

core/models/settings.py

@@ -0,0 +1,342 @@
+"""
+Global application settings model.
+"""
+
+from django.conf import settings
+from django.db import models
+
+
+class GlobalSettings(models.Model):
+    """
+    Singleton model for global application settings.
+    Uses get_solo pattern - always ID=1.
+    """
+
+    class EmailBackend(models.TextChoices):
+        DISABLED = "disabled", "Disabled"
+        SMTP = "smtp", "SMTP"
+        RESEND = "resend", "Resend API"
+
+    # Schedule settings
+    schedules_paused = models.BooleanField(
+        default=False,
+        help_text="Global pause for all scheduled script executions",
+    )
+
+    schedules_paused_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="When schedules were paused",
+    )
+
+    schedules_paused_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="+",
+    )
+
+    updated_at = models.DateTimeField(auto_now=True)
+
+    # Email notification settings
+    email_backend = models.CharField(
+        max_length=20,
+        choices=EmailBackend.choices,
+        default=EmailBackend.DISABLED,
+        help_text="Email backend for notifications",
+    )
+
+    # SMTP configuration
+    smtp_host = models.CharField(
+        max_length=255,
+        blank=True,
+        help_text="SMTP server hostname",
+    )
+    smtp_port = models.PositiveIntegerField(
+        default=587,
+        help_text="SMTP server port",
+    )
+    smtp_username = models.CharField(
+        max_length=255,
+        blank=True,
+        help_text="SMTP username",
+    )
+    smtp_password_encrypted = models.TextField(
+        blank=True,
+        help_text="SMTP password (encrypted)",
+    )
+    smtp_use_tls = models.BooleanField(
+        default=True,
+        help_text="Use TLS for SMTP connection",
+    )
+    smtp_from_email = models.EmailField(
+        blank=True,
+        help_text="From email address for SMTP",
+    )
+
+    # Resend configuration
+    resend_api_key_encrypted = models.TextField(
+        blank=True,
+        help_text="Resend API key (encrypted)",
+    )
+    resend_from_email = models.EmailField(
+        blank=True,
+        help_text="From email address for Resend",
+    )
+
+    # Default notification email
+    default_notification_email = models.EmailField(
+        blank=True,
+        help_text="Default email address for all notifications",
+    )
+
+    # General Settings
+    instance_name = models.CharField(
+        max_length=100,
+        default="PyRunner",
+        blank=True,
+        help_text="Instance name displayed in header and emails",
+    )
+    timezone = models.CharField(
+        max_length=50,
+        default="UTC",
+        help_text="Default timezone for the instance",
+    )
+
+    class DateFormat(models.TextChoices):
+        ISO = "YYYY-MM-DD", "YYYY-MM-DD (ISO)"
+        US = "MM/DD/YYYY", "MM/DD/YYYY (US)"
+        EU = "DD/MM/YYYY", "DD/MM/YYYY (EU)"
+        DOT = "DD.MM.YYYY", "DD.MM.YYYY"
+
+    date_format = models.CharField(
+        max_length=20,
+        choices=DateFormat.choices,
+        default=DateFormat.ISO,
+        help_text="Date display format",
+    )
+
+    class TimeFormat(models.TextChoices):
+        H24 = "24h", "24-hour"
+        H12 = "12h", "12-hour"
+
+    time_format = models.CharField(
+        max_length=10,
+        choices=TimeFormat.choices,
+        default=TimeFormat.H24,
+        help_text="Time display format",
+    )
+
+    # Security Settings
+    admin_url_slug = models.CharField(
+        max_length=100,
+        default="django-admin",
+        help_text="URL path for Django admin interface (requires restart)",
+    )
+
+    # Log Retention Settings
+    retention_days = models.PositiveIntegerField(
+        default=0,
+        help_text="Delete runs older than X days (0 = keep forever)",
+    )
+    retention_count = models.PositiveIntegerField(
+        default=0,
+        help_text="Keep last X runs per script (0 = unlimited)",
+    )
+    auto_cleanup_enabled = models.BooleanField(
+        default=False,
+        help_text="Automatically clean up old runs daily",
+    )
+    last_cleanup_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="When the last cleanup was performed",
+    )
+
+    # Worker heartbeat for status detection
+    worker_heartbeat_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="Last heartbeat from django-q workers",
+    )
+
+    # Worker Settings (Q_CLUSTER configuration)
+    q_workers = models.PositiveIntegerField(
+        default=2,
+        help_text="Number of worker processes for task queue",
+    )
+    q_timeout = models.PositiveIntegerField(
+        default=600,
+        help_text="Task timeout in seconds (0 for no timeout)",
+    )
+    q_retry = models.PositiveIntegerField(
+        default=660,
+        help_text="Seconds before a task is retried after timeout",
+    )
+    q_queue_limit = models.PositiveIntegerField(
+        default=20,
+        help_text="Maximum number of tasks in the queue",
+    )
+    worker_settings_updated_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="When worker settings were last updated (requires restart)",
+    )
+
+    # Setup wizard tracking
+    setup_completed = models.BooleanField(
+        default=False,
+        help_text="Whether initial setup has been completed",
+    )
+    setup_completed_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="When the initial setup was completed",
+    )
+
+    # Registration control
+    allow_registration = models.BooleanField(
+        default=True,
+        help_text="Allow new users to register without an invite (auto-disabled after first user)",
+    )
+
+    # S3 Storage Configuration
+    s3_enabled = models.BooleanField(
+        default=False,
+        help_text="Enable S3-compatible storage for backups",
+    )
+    s3_endpoint_url = models.CharField(
+        max_length=500,
+        blank=True,
+        help_text="S3 endpoint URL (leave empty for AWS S3)",
+    )
+    s3_region = models.CharField(
+        max_length=50,
+        blank=True,
+        default="us-east-1",
+        help_text="S3 region",
+    )
+    s3_bucket_name = models.CharField(
+        max_length=255,
+        blank=True,
+        help_text="S3 bucket name",
+    )
+    s3_access_key_encrypted = models.TextField(
+        blank=True,
+        help_text="S3 access key (encrypted)",
+    )
+    s3_secret_key_encrypted = models.TextField(
+        blank=True,
+        help_text="S3 secret key (encrypted)",
+    )
+    s3_use_ssl = models.BooleanField(
+        default=True,
+        help_text="Use SSL/TLS for S3 connections",
+    )
+    s3_path_style = models.BooleanField(
+        default=False,
+        help_text="Use path-style addressing (required for MinIO)",
+    )
+    s3_last_tested_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="When S3 connection was last successfully tested",
+    )
+
+    # S3 Scheduled Backup Configuration
+    class S3BackupSchedule(models.TextChoices):
+        DISABLED = "disabled", "Disabled"
+        DAILY = "daily", "Daily"
+        WEEKLY = "weekly", "Weekly"
+
+    s3_backup_enabled = models.BooleanField(
+        default=False,
+        help_text="Enable scheduled backups to S3",
+    )
+    s3_backup_schedule = models.CharField(
+        max_length=20,
+        choices=S3BackupSchedule.choices,
+        default=S3BackupSchedule.DISABLED,
+        help_text="Backup schedule frequency",
+    )
+    s3_backup_time = models.TimeField(
+        default="02:00",
+        help_text="Time of day to run backup (in instance timezone)",
+    )
+    s3_backup_day = models.PositiveSmallIntegerField(
+        default=0,
+        help_text="Day of week for weekly backups (0=Monday, 6=Sunday)",
+    )
+    s3_backup_prefix = models.CharField(
+        max_length=255,
+        blank=True,
+        default="pyrunner-backups/",
+        help_text="S3 key prefix for backup files",
+    )
+    s3_backup_retention_count = models.PositiveIntegerField(
+        default=7,
+        help_text="Number of backups to keep in S3 (0 = keep all)",
+    )
+
+    # Backup content options
+    s3_backup_include_runs = models.BooleanField(
+        default=False,
+        help_text="Include run history in scheduled backups",
+    )
+    s3_backup_max_runs = models.PositiveIntegerField(
+        default=1000,
+        help_text="Maximum runs to include in backup",
+    )
+    s3_backup_include_datastores = models.BooleanField(
+        default=True,
+        help_text="Include datastores in scheduled backups",
+    )
+
+    # Backup tracking fields
+    s3_backup_last_run_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="When the last scheduled backup ran",
+    )
+    s3_backup_last_status = models.CharField(
+        max_length=20,
+        blank=True,
+        default="",
+        help_text="Status of last backup (success/failed)",
+    )
+    s3_backup_last_error = models.TextField(
+        blank=True,
+        default="",
+        help_text="Error message from last failed backup",
+    )
+    s3_backup_last_size = models.PositiveIntegerField(
+        default=0,
+        help_text="Size of last backup in bytes",
+    )
+
+    class Meta:
+        db_table = "global_settings"
+        verbose_name = "global settings"
+        verbose_name_plural = "global settings"
+
+    def __str__(self):
+        status = "paused" if self.schedules_paused else "active"
+        return f"Global Settings (schedules: {status})"
+
+    def save(self, *args, **kwargs):
+        # Enforce singleton pattern
+        self.pk = 1
+        super().save(*args, **kwargs)
+
+    @classmethod
+    def get_settings(cls):
+        """Get or create the singleton settings instance."""
+        obj, _ = cls.objects.get_or_create(pk=1)
+        return obj
+
+    def worker_restart_required(self) -> bool:
+        """Check if worker restart is required due to pending settings changes."""
+        if not self.worker_settings_updated_at or not self.worker_heartbeat_at:
+            return False
+        return self.worker_settings_updated_at > self.worker_heartbeat_at

core/models/tag.py

@@ -0,0 +1,60 @@
+"""
+Tag model for categorizing scripts.
+"""
+
+import uuid
+
+from django.conf import settings
+from django.db import models
+
+
+class Tag(models.Model):
+    """
+    A tag for categorizing and filtering scripts.
+    """
+
+    class Color(models.TextChoices):
+        GRAY = "gray", "Gray"
+        RED = "red", "Red"
+        ORANGE = "orange", "Orange"
+        YELLOW = "yellow", "Yellow"
+        GREEN = "green", "Green"
+        BLUE = "blue", "Blue"
+        PURPLE = "purple", "Purple"
+        PINK = "pink", "Pink"
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    name = models.CharField(
+        max_length=50,
+        unique=True,
+        help_text="Tag name (must be unique)",
+    )
+    color = models.CharField(
+        max_length=20,
+        choices=Color.choices,
+        default=Color.GRAY,
+        help_text="Tag color for visual distinction",
+    )
+
+    created_at = models.DateTimeField(auto_now_add=True)
+    created_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="created_tags",
+    )
+
+    class Meta:
+        db_table = "tags"
+        verbose_name = "tag"
+        verbose_name_plural = "tags"
+        ordering = ["name"]
+
+    def __str__(self):
+        return self.name
+
+    @property
+    def script_count(self) -> int:
+        """Return the number of scripts using this tag."""
+        return self.scripts.count()

core/models/user.py

@@ -0,0 +1,282 @@
+"""
+User, MagicToken, and PasswordResetToken models for authentication.
+Supports both password-based and magic link authentication.
+"""
+
+import secrets
+from datetime import timedelta
+
+from django.contrib.auth.models import AbstractUser
+from django.db import models
+from django.utils import timezone
+
+
+class User(AbstractUser):
+    """
+    Custom user model supporting both password and magic link authentication.
+    Uses email as the primary identifier instead of username.
+    """
+
+    email = models.EmailField(unique=True)
+    is_verified = models.BooleanField(
+        default=False,
+        help_text="Whether the user has verified their email via magic link",
+    )
+
+    # Use email as the username field
+    USERNAME_FIELD = "email"
+    REQUIRED_FIELDS = []  # Email is already required via USERNAME_FIELD
+
+    class Meta:
+        db_table = "users"
+        verbose_name = "user"
+        verbose_name_plural = "users"
+
+    def __str__(self):
+        return self.email
+
+    def save(self, *args, **kwargs):
+        # Auto-set username to email if not provided
+        if not self.username:
+            self.username = self.email
+        # Only set unusable password for new users without a password
+        # This allows password auth while keeping magic link as an option
+        if self._state.adding and not self.password:
+            self.set_unusable_password()
+        super().save(*args, **kwargs)
+
+
+class MagicToken(models.Model):
+    """
+    One-time use token for passwordless authentication.
+    Tokens expire after a configurable time and can only be used once.
+    """
+
+    EXPIRY_MINUTES = 15
+
+    token = models.CharField(max_length=64, unique=True, db_index=True)
+    user = models.ForeignKey(
+        User,
+        on_delete=models.CASCADE,
+        related_name="magic_tokens",
+        null=True,
+        blank=True,
+    )
+    email = models.EmailField(help_text="Email address this token was sent to")
+    created_at = models.DateTimeField(auto_now_add=True)
+    expires_at = models.DateTimeField()
+    used_at = models.DateTimeField(null=True, blank=True)
+    ip_address = models.GenericIPAddressField(
+        null=True,
+        blank=True,
+        help_text="IP address that requested this token",
+    )
+
+    class Meta:
+        db_table = "magic_tokens"
+        verbose_name = "magic token"
+        verbose_name_plural = "magic tokens"
+        indexes = [
+            models.Index(fields=["token", "expires_at"]),
+            models.Index(fields=["email", "created_at"]),
+        ]
+
+    def __str__(self):
+        status = "used" if self.used_at else ("expired" if not self.is_valid() else "valid")
+        return f"MagicToken for {self.email} ({status})"
+
+    @classmethod
+    def create_for_email(cls, email: str, ip_address: str = None) -> "MagicToken":
+        """
+        Create a new magic token for an email address.
+        Invalidates any existing unused tokens for the same email.
+
+        The first user to register is automatically promoted to admin (superuser).
+        """
+        # Invalidate existing unused tokens for this email
+        cls.objects.filter(email=email, used_at__isnull=True).update(
+            expires_at=timezone.now()
+        )
+
+        # Check if this will be the first user (before creating)
+        is_first_user = User.objects.count() == 0
+
+        # Get or create user for this email
+        user, created = User.objects.get_or_create(
+            email=email,
+            defaults={"is_verified": False},
+        )
+
+        # Auto-promote first user to admin and disable open registration
+        if created and is_first_user:
+            user.is_staff = True
+            user.is_superuser = True
+            user.save(update_fields=["is_staff", "is_superuser"])
+
+            # Auto-disable open registration after first user
+            from core.models.settings import GlobalSettings
+            settings = GlobalSettings.get_settings()
+            settings.allow_registration = False
+            settings.save(update_fields=["allow_registration"])
+
+        # Create new token
+        return cls.objects.create(
+            token=secrets.token_urlsafe(48),
+            user=user,
+            email=email,
+            expires_at=timezone.now() + timedelta(minutes=cls.EXPIRY_MINUTES),
+            ip_address=ip_address,
+        )
+
+    def is_valid(self) -> bool:
+        """Check if the token is still valid (not expired and not used)."""
+        return self.used_at is None and self.expires_at > timezone.now()
+
+    def consume(self) -> User:
+        """
+        Mark the token as used and return the associated user.
+        Also marks the user as verified.
+        """
+        if not self.is_valid():
+            raise ValueError("Token is no longer valid")
+
+        self.used_at = timezone.now()
+        self.save(update_fields=["used_at"])
+
+        # Mark user as verified
+        self.user.is_verified = True
+        self.user.save(update_fields=["is_verified"])
+
+        return self.user
+
+
+class UserInvite(models.Model):
+    """
+    Invitation for a new user. Admin creates invite, gets shareable link.
+    Can be used once to create an account when registration is closed.
+    """
+
+    EXPIRY_DAYS = 7
+
+    email = models.EmailField(
+        unique=True,
+        help_text="Email address of the invited user",
+    )
+    token = models.CharField(max_length=64, unique=True, db_index=True)
+    created_by = models.ForeignKey(
+        User,
+        on_delete=models.CASCADE,
+        related_name="sent_invites",
+    )
+    created_at = models.DateTimeField(auto_now_add=True)
+    expires_at = models.DateTimeField()
+    used_at = models.DateTimeField(null=True, blank=True)
+    used_by = models.ForeignKey(
+        User,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="received_invite",
+    )
+
+    class Meta:
+        db_table = "user_invites"
+        verbose_name = "user invite"
+        verbose_name_plural = "user invites"
+        indexes = [
+            models.Index(fields=["token"]),
+            models.Index(fields=["email"]),
+        ]
+
+    def __str__(self):
+        status = "used" if self.used_at else ("expired" if not self.is_valid() else "pending")
+        return f"Invite for {self.email} ({status})"
+
+    @classmethod
+    def create_invite(cls, email: str, created_by: User) -> "UserInvite":
+        """
+        Create a new invitation. Deletes any existing unused invite for the same email.
+        """
+        # Delete existing unused invite for this email
+        cls.objects.filter(email__iexact=email, used_at__isnull=True).delete()
+
+        return cls.objects.create(
+            email=email.lower().strip(),
+            token=secrets.token_urlsafe(48),
+            created_by=created_by,
+            expires_at=timezone.now() + timedelta(days=cls.EXPIRY_DAYS),
+        )
+
+    def is_valid(self) -> bool:
+        """Check if the invite is still valid (not expired and not used)."""
+        return self.used_at is None and self.expires_at > timezone.now()
+
+    def mark_used(self, user: User) -> None:
+        """Mark the invite as used by the specified user."""
+        self.used_at = timezone.now()
+        self.used_by = user
+        self.save(update_fields=["used_at", "used_by"])
+
+
+class PasswordResetToken(models.Model):
+    """
+    Token for password reset functionality.
+    Allows users to reset their password via email link.
+    """
+
+    EXPIRY_HOURS = 24
+
+    token = models.CharField(max_length=64, unique=True, db_index=True)
+    user = models.ForeignKey(
+        User,
+        on_delete=models.CASCADE,
+        related_name="password_reset_tokens",
+    )
+    created_at = models.DateTimeField(auto_now_add=True)
+    expires_at = models.DateTimeField()
+    used_at = models.DateTimeField(null=True, blank=True)
+
+    class Meta:
+        db_table = "password_reset_tokens"
+        verbose_name = "password reset token"
+        verbose_name_plural = "password reset tokens"
+        indexes = [
+            models.Index(fields=["token", "expires_at"]),
+        ]
+
+    def __str__(self):
+        status = "used" if self.used_at else ("expired" if not self.is_valid() else "valid")
+        return f"PasswordResetToken for {self.user.email} ({status})"
+
+    @classmethod
+    def create_for_user(cls, user: User) -> "PasswordResetToken":
+        """
+        Create a new password reset token for a user.
+        Invalidates any existing unused tokens for the same user.
+        """
+        # Invalidate existing unused tokens for this user
+        cls.objects.filter(user=user, used_at__isnull=True).update(
+            expires_at=timezone.now()
+        )
+
+        return cls.objects.create(
+            token=secrets.token_urlsafe(48),
+            user=user,
+            expires_at=timezone.now() + timedelta(hours=cls.EXPIRY_HOURS),
+        )
+
+    def is_valid(self) -> bool:
+        """Check if the token is still valid (not expired and not used)."""
+        return self.used_at is None and self.expires_at > timezone.now()
+
+    def consume(self) -> User:
+        """
+        Mark the token as used and return the associated user.
+        """
+        if not self.is_valid():
+            raise ValueError("Token is no longer valid")
+
+        self.used_at = timezone.now()
+        self.save(update_fields=["used_at"])
+
+        return self.user