Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat(auth): one-time login links and demo mode

Juan Denisbd7624130c98
diff --git a/backend/app/api/auth.py b/backend/app/api/auth.py
index 1466f8eb..5eec30f8 100644
--- a/backend/app/api/auth.py
+++ b/backend/app/api/auth.py
@@ -11,8 +11,11 @@ from flask_jwt_extended import (
)
from app import db, limiter
from app.models import User, AuditLog, SystemSettings
+# Aliased: this module already has a `get_current_user` route handler.
+from app.middleware.rbac import admin_required, get_current_user as get_request_user
from app.services.settings_service import SettingsService
from app.services.audit_service import AuditService
+from app.services import login_link_service
logger = logging.getLogger(__name__)
@@ -264,6 +267,150 @@ def login():
}), 200
+# ==========================================
+# ONE-TIME LOGIN LINKS
+# ==========================================
+@auth_bp.route('/login-links', methods=['POST'])
+@admin_required
+def create_login_link():
+ """Mint a single-use login URL. The raw token is returned exactly once."""
+ current = get_request_user()
+ data = request.get_json() or {}
+
+ target_id = data.get('user_id') or current.id
+ target = User.query.get(target_id)
+ if not target:
+ return jsonify({'error': 'User not found'}), 404
+
+ bound_ip = (data.get('bound_ip') or '').strip() or None
+ if bound_ip and len(bound_ip) > 64:
+ return jsonify({'error': 'Invalid IP address'}), 400
+
+ token, link = login_link_service.mint(
+ user_id=target.id,
+ ttl_minutes=data.get('ttl_minutes'),
+ bound_ip=bound_ip,
+ created_by=current.id,
+ )
+
+ AuditService.log(
+ action='login_link.create',
+ user_id=current.id,
+ target_type='user',
+ target_id=target.id,
+ details={'link_id': link.id, 'expires_at': link.expires_at.isoformat(),
+ 'ip_bound': bound_ip is not None},
+ )
+ db.session.commit()
+
+ return jsonify({
+ 'url': f'/login?link={token}',
+ 'token': token,
+ 'expires_at': link.expires_at.isoformat(),
+ 'link': link.to_dict(),
+ }), 201
+
+
+@auth_bp.route('/login-links', methods=['GET'])
+@admin_required
+def list_login_links():
+ """List active (unused, unexpired) login links. Hashes are never exposed."""
+ links = login_link_service.list_active()
+ return jsonify({'links': [l.to_dict() for l in links]}), 200
+
+
+@auth_bp.route('/login-links/<int:link_id>', methods=['DELETE'])
+@admin_required
+def revoke_login_link(link_id):
+ from app.models.login_link import LoginLink
+ link = LoginLink.query.get(link_id)
+ if not link:
+ return jsonify({'error': 'Link not found'}), 404
+
+ current = get_request_user()
+ AuditService.log(
+ action='login_link.revoke',
+ user_id=current.id,
+ target_type='user',
+ target_id=link.user_id,
+ details={'link_id': link.id},
+ )
+ db.session.delete(link)
+ db.session.commit()
+ return jsonify({'message': 'Login link revoked'}), 200
+
+
+@auth_bp.route('/login-links/redeem', methods=['POST'])
[email protected]("30 per minute")
+def redeem_login_link():
+ """Redeem a one-time login link and issue normal JWT tokens."""
+ data = request.get_json() or {}
+ token = data.get('token')
+
+ user, reason = login_link_service.redeem(token, request.remote_addr)
+ if not user:
+ logger.info(f"Login link redeem failed ({reason}) from {request.remote_addr}")
+ return jsonify({'error': 'Invalid or expired link'}), 401
+
+ user.reset_failed_login()
+ user.last_login_at = datetime.utcnow()
+ db.session.commit()
+
+ AuditService.log_login(user.id, success=True, details={'method': 'login_link'})
+ db.session.commit()
+
+ access_token = create_access_token(identity=user.id)
+ refresh_token = create_refresh_token(identity=user.id)
+
+ return jsonify({
+ 'user': user.to_dict(),
+ 'access_token': access_token,
+ 'refresh_token': refresh_token
+ }), 200
+
+
+# ==========================================
+# DEMO MODE
+# ==========================================
+@auth_bp.route('/demo-info', methods=['GET'])
+def demo_info():
+ """Public demo-mode info for the login page.
+
+ Only when demo mode is active: ensures the seeded read-only ``demo``
+ user exists (stable random password stored in settings) and returns
+ its credentials. Otherwise reveals nothing.
+ """
+ from app.middleware.demo import is_demo_mode_active
+
+ if not is_demo_mode_active():
+ return jsonify({'enabled': False}), 200
+
+ import secrets as _secrets
+
+ password = SettingsService.get('demo_password')
+ user = User.query.filter_by(username='demo').first()
+
+ if not password:
+ password = _secrets.token_urlsafe(12)
+ SettingsService.set('demo_password', password)
+
+ if not user:
+ user = User(
+ username='demo',
+ role=User.ROLE_VIEWER,
+ )
+ user.set_password(password)
+ db.session.add(user)
+ db.session.commit()
+ elif not user.check_password(password):
+ # Keep the stored credential authoritative (e.g. rotated setting).
+ user.set_password(password)
+ db.session.commit()
+
+ return jsonify({'enabled': True, 'username': 'demo', 'password': password}), 200
+
+
@auth_bp.route('/refresh', methods=['POST'])
@jwt_required(refresh=True)
def refresh():
diff --git a/backend/app/middleware/demo.py b/backend/app/middleware/demo.py
new file mode 100644
index 00000000..852988b6
--- /dev/null
+++ b/backend/app/middleware/demo.py
@@ -0,0 +1,54 @@
+"""Demo mode middleware.
+
+When active, every mutating /api/v1/* request is rejected with
+``403 {'error': 'demo_mode'}`` so a public demo panel stays read-only.
+Activation: env ``SERVERKIT_DEMO_MODE=1`` (wins) or the ``demo_mode``
+system setting. Default OFF.
+"""
+import os
+
+from flask import request, jsonify
+
+MUTATING_METHODS = {'POST', 'PUT', 'PATCH', 'DELETE'}
+
+# Auth flows must keep working so visitors can sign in as the demo user.
+ALLOWLIST = {
+ '/api/v1/auth/login',
+ '/api/v1/auth/refresh',
+ '/api/v1/auth/logout',
+ '/api/v1/auth/login-links/redeem',
+}
+
+
+def is_demo_mode_active():
+ """True when demo mode is on. The env var wins over the setting."""
+ env = os.environ.get('SERVERKIT_DEMO_MODE')
+ if env is not None:
+ return env.strip().lower() in ('1', 'true', 'yes', 'on')
+ try:
+ from app.services.settings_service import SettingsService
+ return bool(SettingsService.get('demo_mode', False))
+ except Exception:
+ return False
+
+
+def init_demo_mode(app):
+ """Register the demo-mode guard. Idempotent (safe to call twice)."""
+ if app.extensions.get('serverkit_demo_mode'):
+ return
+ app.extensions['serverkit_demo_mode'] = True
+
+ @app.before_request
+ def _demo_mode_guard():
+ if request.method not in MUTATING_METHODS:
+ return None # GET/HEAD/OPTIONS always pass
+ path = request.path.rstrip('/')
+ if not path.startswith('/api/v1/'):
+ return None
+ if path in ALLOWLIST:
+ return None
+ # Only consult config once we know the request would be blocked —
+ # cheap per-request: mutating API calls only.
+ if not is_demo_mode_active():
+ return None
+ return jsonify({'error': 'demo_mode'}), 403
diff --git a/backend/app/models/login_link.py b/backend/app/models/login_link.py
new file mode 100644
index 00000000..80e77c3b
--- /dev/null
+++ b/backend/app/models/login_link.py
@@ -0,0 +1,57 @@
+from datetime import datetime
+
+from app import db
+
+
+class LoginLink(db.Model):
+ """A single-use, short-TTL login URL minted by an admin.
+
+ Only the SHA-256 hash of the token is stored; the raw token is returned
+ exactly once at mint time. A link may optionally be bound to a single
+ client IP. Rows are reaped on a schedule once used or expired.
+ """
+
+ __tablename__ = 'login_links'
+
+ id = db.Column(db.Integer, primary_key=True)
+ token_hash = db.Column(db.String(64), nullable=False, unique=True, index=True)
+ user_id = db.Column(
+ db.Integer, db.ForeignKey('users.id', ondelete='CASCADE'),
+ nullable=False, index=True,
+ )
+ created_by_id = db.Column(
+ db.Integer, db.ForeignKey('users.id', ondelete='SET NULL'),
+ nullable=True,
+ )
+ expires_at = db.Column(db.DateTime, nullable=False)
+ used_at = db.Column(db.DateTime, nullable=True)
+ bound_ip = db.Column(db.String(64), nullable=True)
+ created_at = db.Column(db.DateTime, default=datetime.utcnow)
+
+ user = db.relationship('User', foreign_keys=[user_id])
+ created_by = db.relationship('User', foreign_keys=[created_by_id])
+
+ @property
+ def is_expired(self):
+ return self.expires_at is not None and datetime.utcnow() >= self.expires_at
+
+ @property
+ def is_used(self):
+ return self.used_at is not None
+
+ def to_dict(self):
+ # NEVER expose token_hash — the raw token is shown once at mint time.
+ return {
+ 'id': self.id,
+ 'user_id': self.user_id,
+ 'username': self.user.username if self.user else None,
+ 'created_by_id': self.created_by_id,
+ 'created_by': self.created_by.username if self.created_by else None,
+ 'expires_at': self.expires_at.isoformat() if self.expires_at else None,
+ 'used_at': self.used_at.isoformat() if self.used_at else None,
+ 'bound_ip': self.bound_ip,
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ }
+
+ def __repr__(self):
+ return f'<LoginLink user={self.user_id} expires={self.expires_at}>'
diff --git a/backend/app/services/login_link_service.py b/backend/app/services/login_link_service.py
new file mode 100644
index 00000000..461c4868
--- /dev/null
+++ b/backend/app/services/login_link_service.py
@@ -0,0 +1,110 @@
+"""One-time login links: mint, redeem, and reap single-use login URLs.
+
+Tokens are 256-bit urlsafe secrets; only their SHA-256 hex digest is stored.
+The raw token is returned exactly once at mint time.
+"""
+import hashlib
+import hmac
+import logging
+from datetime import datetime, timedelta
+
+from app import db
+from app.models.login_link import LoginLink # explicit import registers the table
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TTL_MINUTES = 15
+MAX_TTL_MINUTES = 60
+
+REAP_JOB_KIND = 'auth.login_links.reap'
+REAP_SCHEDULE_NAME = 'login-links-reap'
+
+
+def _hash_token(token: str) -> str:
+ return hashlib.sha256(token.encode('utf-8')).hexdigest()
+
+
+def mint(user_id, ttl_minutes=DEFAULT_TTL_MINUTES, bound_ip=None, created_by=None):
+ """Create a single-use login link for ``user_id``.
+
+ Returns ``(raw_token, LoginLink)``. The raw token is never stored and
+ cannot be recovered later.
+ """
+ import secrets
+
+ try:
+ ttl = int(ttl_minutes) if ttl_minutes is not None else DEFAULT_TTL_MINUTES
+ except (TypeError, ValueError):
+ ttl = DEFAULT_TTL_MINUTES
+ ttl = max(1, min(ttl, MAX_TTL_MINUTES))
+
+ token = secrets.token_urlsafe(32)
+ link = LoginLink(
+ token_hash=_hash_token(token),
+ user_id=user_id,
+ created_by_id=created_by,
+ expires_at=datetime.utcnow() + timedelta(minutes=ttl),
+ bound_ip=(bound_ip or None),
+ )
+ db.session.add(link)
+ db.session.commit()
+ return token, link
+
+
+def redeem(token, remote_ip=None):
+ """Redeem a raw token. Returns ``(User, None)`` or ``(None, reason)``.
+
+ The reason is for logging only — API callers must return a generic error.
+ """
+ from app.models import User
+
+ if not token or not isinstance(token, str):
+ return None, 'not_found'
+
+ digest = _hash_token(token)
+ link = LoginLink.query.filter_by(token_hash=digest).first()
+ if link is None or not hmac.compare_digest(link.token_hash, digest):
+ return None, 'not_found'
+ if link.is_used:
+ return None, 'used'
+ if link.is_expired:
+ return None, 'expired'
+ if link.bound_ip and link.bound_ip != (remote_ip or ''):
+ return None, 'ip_mismatch'
+
+ user = User.query.get(link.user_id)
+ if user is None or not user.is_active:
+ return None, 'inactive'
+
+ link.used_at = datetime.utcnow()
+ db.session.commit()
+ return user, None
+
+
+def reap():
+ """Delete expired or already-used links. Returns the number removed."""
+ now = datetime.utcnow()
+ count = LoginLink.query.filter(
+ (LoginLink.used_at.isnot(None)) | (LoginLink.expires_at < now)
+ ).delete(synchronize_session=False)
+ db.session.commit()
+ if count:
+ logger.info(f'Reaped {count} login link(s)')
+ return count
+
+
+def list_active():
+ """Active (unused, unexpired) links, newest first."""
+ now = datetime.utcnow()
+ return (
+ LoginLink.query
+ .filter(LoginLink.used_at.is_(None), LoginLink.expires_at >= now)
+ .order_by(LoginLink.created_at.desc())
+ .all()
+ )
+
+
+def register_jobs():
+ """Register the reap handler with the unified job registry."""
+ from app.jobs import registry
+ registry.register(REAP_JOB_KIND, lambda job: reap(), replace=True)
diff --git a/backend/migrations/versions/049_login_links.py b/backend/migrations/versions/049_login_links.py
new file mode 100644
index 00000000..f0e32501
--- /dev/null
+++ b/backend/migrations/versions/049_login_links.py
@@ -0,0 +1,51 @@
+"""One-time login links.
+
+Adds the login_links table: single-use, short-TTL, optionally IP-bound
+login URLs minted by an admin. Only the SHA-256 token hash is stored.
+
+Idempotent: MigrationService runs _fix_missing_columns() + db.create_all() on boot
+before Alembic, so guard on the live schema.
+
+Revision ID: 049_login_links
+Revises: 048_app_resource_limits
+Create Date: 2026-07-03
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = '049_login_links'
+down_revision = '048_app_resource_limits'
+branch_labels = None
+depends_on = None
+
+TABLE = 'login_links'
+
+
+def upgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ if TABLE in set(inspector.get_table_names()):
+ return
+ op.create_table(
+ TABLE,
+ sa.Column('id', sa.Integer(), primary_key=True),
+ sa.Column('token_hash', sa.String(64), nullable=False),
+ sa.Column('user_id', sa.Integer(),
+ sa.ForeignKey('users.id', ondelete='CASCADE'), nullable=False),
+ sa.Column('created_by_id', sa.Integer(),
+ sa.ForeignKey('users.id', ondelete='SET NULL'), nullable=True),
+ sa.Column('expires_at', sa.DateTime(), nullable=False),
+ sa.Column('used_at', sa.DateTime(), nullable=True),
+ sa.Column('bound_ip', sa.String(64), nullable=True),
+ sa.Column('created_at', sa.DateTime(), nullable=True),
+ )
+ op.create_index('ix_login_links_token_hash', TABLE, ['token_hash'], unique=True)
+ op.create_index('ix_login_links_user_id', TABLE, ['user_id'])
+
+
+def downgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ if TABLE not in set(inspector.get_table_names()):
+ return
+ op.drop_table(TABLE)
diff --git a/backend/tests/test_demo_mode.py b/backend/tests/test_demo_mode.py
new file mode 100644
index 00000000..0fe8a42f
--- /dev/null
+++ b/backend/tests/test_demo_mode.py
@@ -0,0 +1,117 @@
+"""Demo mode: mutation blocking, allowlist, env-wins precedence, demo-info."""
+import pytest
+
+from app.middleware.demo import init_demo_mode
+
+
+def demo_app(app):
+ """The conftest app with the demo guard wired (not yet in create_app)."""
+ init_demo_mode(app)
+ # Idempotency: a second call must be a no-op (no double-registration).
+ init_demo_mode(app)
+ return app
+
+
+def demo_client(demo_app):
+ return demo_app.test_client()
+
+
+def _no_env_flag(monkeypatch):
+ monkeypatch.delenv('SERVERKIT_DEMO_MODE', raising=False)
+
+
+def _env_flag_on(monkeypatch):
+ monkeypatch.setenv('SERVERKIT_DEMO_MODE', '1')
+
+
+def test_flag_off_mutations_pass(_no_env_flag, demo_client, auth_headers):
+ resp = demo_client.post('/api/v1/auth/login-links', json={},
+ headers=auth_headers)
+ assert resp.status_code == 201 # not blocked
+
+
+def test_env_flag_blocks_mutations(_env_flag_on, demo_client, auth_headers):
+ resp = demo_client.post('/api/v1/auth/login-links', json={},
+ headers=auth_headers)
+ assert resp.status_code == 403
+ assert resp.get_json() == {'error': 'demo_mode'}
+
+ resp = demo_client.delete('/api/v1/auth/login-links/1', headers=auth_headers)
+ assert resp.status_code == 403
+ assert resp.get_json() == {'error': 'demo_mode'}
+
+
+def test_env_flag_get_passes(_env_flag_on, demo_client, auth_headers):
+ resp = demo_client.get('/api/v1/auth/login-links', headers=auth_headers)
+ assert resp.status_code == 200
+
+
+def test_login_allowlisted_in_demo_mode(_env_flag_on, demo_client, auth_headers):
+ # auth_headers created the 'testadmin' user with password 'testpass'
+ resp = demo_client.post('/api/v1/auth/login',
+ json={'email': 'testadmin', 'password': 'testpass'})
+ assert resp.status_code == 200
+ assert resp.get_json()['access_token']
+
+
+def test_settings_flag_blocks_mutations(_no_env_flag, demo_app, demo_client,
+ auth_headers):
+ from app.services.settings_service import SettingsService
+ with demo_app.app_context():
+ SettingsService.set('demo_mode', True)
+
+ resp = demo_client.post('/api/v1/auth/login-links', json={},
+ headers=auth_headers)
+ assert resp.status_code == 403
+ assert resp.get_json() == {'error': 'demo_mode'}
+
+
+def test_env_wins_over_setting(demo_app, demo_client, auth_headers, monkeypatch):
+ from app.services.settings_service import SettingsService
+ with demo_app.app_context():
+ SettingsService.set('demo_mode', True)
+ monkeypatch.setenv('SERVERKIT_DEMO_MODE', '0') # env OFF overrides setting ON
+
+ resp = demo_client.post('/api/v1/auth/login-links', json={},
+ headers=auth_headers)
+ assert resp.status_code == 201
+
+
+def test_demo_info_off(_no_env_flag, demo_app, demo_client):
+ resp = demo_client.get('/api/v1/auth/demo-info')
+ assert resp.status_code == 200
+ assert resp.get_json() == {'enabled': False}
+
+ # No demo user was created
+ from app.models import User
+ with demo_app.app_context():
+ assert User.query.filter_by(username='demo').first() is None
+
+
+def test_demo_info_on_seeds_working_readonly_user(_env_flag_on, demo_app,
+ demo_client):
+ resp = demo_client.get('/api/v1/auth/demo-info')
+ assert resp.status_code == 200
+ data = resp.get_json()
+ assert data['enabled'] is True
+ assert data['username'] == 'demo'
+ assert data['password']
+
+ # Stable across calls
+ again = demo_client.get('/api/v1/auth/demo-info').get_json()
+ assert again['password'] == data['password']
+
+ # Seeded user is a viewer and the credentials actually log in
+ from app.models import User
+ with demo_app.app_context():
+ user = User.query.filter_by(username='demo').first()
+ assert user is not None
+ assert user.role == User.ROLE_VIEWER
+
+ login = demo_client.post('/api/v1/auth/login',
+ json={'email': 'demo', 'password': data['password']})
+ assert login.status_code == 200
diff --git a/backend/tests/test_login_links.py b/backend/tests/test_login_links.py
new file mode 100644
index 00000000..78d832ca
--- /dev/null
+++ b/backend/tests/test_login_links.py
@@ -0,0 +1,182 @@
+"""One-time login links: mint / redeem / expiry / single-use / IP-bound / RBAC."""
+from datetime import datetime, timedelta
+
+import pytest
+
+# Explicit import so the table registers with SQLAlchemy even though
+# app/models/__init__.py does not (yet) import it.
+from app.models.login_link import LoginLink # noqa: F401
+from app.services import login_link_service
+
+
+def viewer_headers(app):
+ """A non-admin (viewer) user's JWT headers."""
+ from app import db
+ from app.models import User
+ from flask_jwt_extended import create_access_token
+
+ with app.app_context():
+ user = User(email='[email protected]', username='vieweruser',
+ role=User.ROLE_VIEWER, is_active=True)
+ user.set_password('viewerpass')
+ db.session.add(user)
+ db.session.commit()
+ token = create_access_token(identity=user.id)
+ return {'Authorization': f'Bearer {token}'}
+
+
+def _mint(client, auth_headers, body=None):
+ return client.post('/api/v1/auth/login-links', json=body or {},
+ headers=auth_headers)
+
+
+def test_mint_requires_admin(client, auth_headers, viewer_headers):
+ # No auth
+ resp = client.post('/api/v1/auth/login-links', json={})
+ assert resp.status_code == 401
+
+ # Non-admin
+ resp = client.post('/api/v1/auth/login-links', json={}, headers=viewer_headers)
+ assert resp.status_code == 403
+
+ # Admin
+ resp = _mint(client, auth_headers)
+ assert resp.status_code == 201
+
+
+def test_mint_returns_token_once_and_list_hides_hashes(client, auth_headers):
+ resp = _mint(client, auth_headers, {'ttl_minutes': 30})
+ assert resp.status_code == 201
+ data = resp.get_json()
+ assert data['token']
+ assert data['url'] == f"/login?link={data['token']}"
+ assert data['expires_at']
+ assert 'token_hash' not in data['link']
+
+ listing = client.get('/api/v1/auth/login-links', headers=auth_headers)
+ assert listing.status_code == 200
+ links = listing.get_json()['links']
+ assert len(links) == 1
+ assert 'token_hash' not in links[0]
+ assert 'token' not in links[0]
+
+
+def test_ttl_capped_at_60_minutes(client, auth_headers):
+ resp = _mint(client, auth_headers, {'ttl_minutes': 500})
+ assert resp.status_code == 201
+ expires = datetime.fromisoformat(resp.get_json()['expires_at'])
+ assert expires <= datetime.utcnow() + timedelta(minutes=61)
+
+
+def test_redeem_success_and_single_use(client, auth_headers):
+ token = _mint(client, auth_headers).get_json()['token']
+
+ resp = client.post('/api/v1/auth/login-links/redeem', json={'token': token})
+ assert resp.status_code == 200
+ data = resp.get_json()
+ assert data['access_token'] and data['refresh_token']
+ assert data['user']['username'] == 'testadmin'
+
+ # The minted access token actually works
+ me = client.get('/api/v1/auth/me',
+ headers={'Authorization': f"Bearer {data['access_token']}"})
+ assert me.status_code == 200
+ assert me.get_json()['user']['username'] == 'testadmin'
+
+ # Second redeem fails with a generic error
+ again = client.post('/api/v1/auth/login-links/redeem', json={'token': token})
+ assert again.status_code == 401
+ assert again.get_json() == {'error': 'Invalid or expired link'}
+
+
+def test_redeem_expired_link_fails(app, client, auth_headers):
+ from app import db
+
+ token = _mint(client, auth_headers).get_json()['token']
+ with app.app_context():
+ link = LoginLink.query.first()
+ link.expires_at = datetime.utcnow() - timedelta(minutes=1)
+ db.session.commit()
+
+ resp = client.post('/api/v1/auth/login-links/redeem', json={'token': token})
+ assert resp.status_code == 401
+ assert resp.get_json() == {'error': 'Invalid or expired link'}
+
+
+def test_redeem_unknown_token_fails(client):
+ resp = client.post('/api/v1/auth/login-links/redeem', json={'token': 'bogus'})
+ assert resp.status_code == 401
+ assert resp.get_json() == {'error': 'Invalid or expired link'}
+
+
+def test_ip_bound_link(client, auth_headers):
+ # Bound to a foreign IP → rejected (test client is 127.0.0.1)
+ token = _mint(client, auth_headers, {'bound_ip': '10.9.8.7'}).get_json()['token']
+ resp = client.post('/api/v1/auth/login-links/redeem', json={'token': token})
+ assert resp.status_code == 401
+
+ # Bound to the caller's IP → accepted
+ token = _mint(client, auth_headers, {'bound_ip': '127.0.0.1'}).get_json()['token']
+ resp = client.post('/api/v1/auth/login-links/redeem', json={'token': token})
+ assert resp.status_code == 200
+
+
+def test_revoke_link(client, auth_headers):
+ minted = _mint(client, auth_headers).get_json()
+ link_id = minted['link']['id']
+
+ resp = client.delete(f'/api/v1/auth/login-links/{link_id}', headers=auth_headers)
+ assert resp.status_code == 200
+
+ listing = client.get('/api/v1/auth/login-links', headers=auth_headers)
+ assert listing.get_json()['links'] == []
+
+ resp = client.post('/api/v1/auth/login-links/redeem',
+ json={'token': minted['token']})
+ assert resp.status_code == 401
+
+
+def test_mint_for_another_user(app, client, auth_headers):
+ from app import db
+ from app.models import User
+
+ with app.app_context():
+ other = User(email='[email protected]', username='otheruser',
+ role=User.ROLE_DEVELOPER, is_active=True)
+ other.set_password('otherpass123')
+ db.session.add(other)
+ db.session.commit()
+ other_id = other.id
+
+ token = _mint(client, auth_headers, {'user_id': other_id}).get_json()['token']
+ resp = client.post('/api/v1/auth/login-links/redeem', json={'token': token})
+ assert resp.status_code == 200
+ assert resp.get_json()['user']['username'] == 'otheruser'
+
+
+def test_reap_removes_used_and_expired(app, client, auth_headers):
+ from app import db
+
+ with app.app_context():
+ # used
+ used_token, used_link = login_link_service.mint(user_id=1)
+ used_link.used_at = datetime.utcnow()
+ # expired
+ _, expired_link = login_link_service.mint(user_id=1)
+ expired_link.expires_at = datetime.utcnow() - timedelta(minutes=5)
+ # live
+ _, live_link = login_link_service.mint(user_id=1)
+ db.session.commit()
+
+ removed = login_link_service.reap()
+ assert removed == 2
+ remaining = LoginLink.query.all()
+ assert [l.id for l in remaining] == [live_link.id]
+
+
+def test_register_jobs_registers_reap_kind(app):
+ with app.app_context():
+ from app.jobs import registry
+ login_link_service.register_jobs()
+ assert login_link_service.REAP_JOB_KIND in registry.registered_kinds()
diff --git a/frontend/src/components/settings/LoginLinksSection.jsx b/frontend/src/components/settings/LoginLinksSection.jsx
new file mode 100644
index 00000000..1909e036
--- /dev/null
+++ b/frontend/src/components/settings/LoginLinksSection.jsx
@@ -0,0 +1,202 @@
+import { useState, useEffect, useCallback } from 'react';
+import api from '../../services/api';
+import { Button } from '@/components/ui/button';
+
+const TTL_OPTIONS = [15, 30, 60];
+
+/**
+ * Admin card for one-time login links: mint a single-use, short-lived
+ * sign-in URL (optionally IP-bound), reveal it once, list + revoke.
+ */
+const LoginLinksSection = ({ users, currentUserId }) => {
+ const [links, setLinks] = useState([]);
+ const [error, setError] = useState('');
+ const [minting, setMinting] = useState(false);
+
+ // Mint form
+ const [userId, setUserId] = useState(currentUserId || '');
+ const [ttl, setTtl] = useState(15);
+ const [bindIp, setBindIp] = useState(false);
+ const [boundIp, setBoundIp] = useState('');
+
+ // Reveal-once state
+ const [minted, setMinted] = useState(null);
+ const [copied, setCopied] = useState(false);
+
+ const loadLinks = useCallback(async () => {
+ try {
+ const data = await api.getLoginLinks();
+ setLinks(data.links || []);
+ } catch (err) {
+ setError(err.message || 'Failed to load login links');
+ }
+ }, []);
+
+ useEffect(() => {
+ loadLinks();
+ }, [loadLinks]);
+
+ useEffect(() => {
+ if (currentUserId && !userId) setUserId(currentUserId);
+ }, [currentUserId, userId]);
+
+ async function handleMint(e) {
+ e.preventDefault();
+ setError('');
+ setMinting(true);
+ setMinted(null);
+ setCopied(false);
+ try {
+ const body = { user_id: Number(userId), ttl_minutes: ttl };
+ if (bindIp && boundIp.trim()) body.bound_ip = boundIp.trim();
+ const res = await api.mintLoginLink(body);
+ setMinted({
+ url: `${window.location.origin}${res.url}`,
+ expiresAt: res.expires_at,
+ });
+ await loadLinks();
+ } catch (err) {
+ setError(err.message || 'Failed to create login link');
+ } finally {
+ setMinting(false);
+ }
+ }
+
+ async function handleCopy() {
+ try {
+ await navigator.clipboard.writeText(minted.url);
+ setCopied(true);
+ } catch {
+ /* clipboard unavailable — the URL stays visible for manual copy */
+ }
+ }
+
+ async function handleRevoke(id) {
+ setError('');
+ try {
+ await api.revokeLoginLink(id);
+ await loadLinks();
+ } catch (err) {
+ setError(err.message || 'Failed to revoke login link');
+ }
+ }
+
+ function formatExpiry(dateString) {
+ if (!dateString) return '—';
+ return new Date(`${dateString}Z`).toLocaleTimeString([], {
+ hour: '2-digit',
+ minute: '2-digit',
+ });
+ }
+
+ return (
+ <div className="login-links">
+ <div className="tab-header">
+ <div className="tab-header-content">
+ <h3>One-Time Login Links</h3>
+ <p>
+ Mint a single-use sign-in URL for a user. The link is shown
+ once, expires automatically, and can be bound to one IP.
+ </p>
+ </div>
+ </div>
+
+ {error && <div className="error-message">{error}</div>}
+
+ <form className="login-links__form" onSubmit={handleMint}>
+ <label className="login-links__field">
+ <span>User</span>
+ <select value={userId} onChange={(e) => setUserId(e.target.value)}>
+ {(users || []).map((u) => (
+ <option key={u.id} value={u.id}>
+ {u.username}{u.id === currentUserId ? ' (you)' : ''}
+ </option>
+ ))}
+ </select>
+ </label>
+
+ <label className="login-links__field">
+ <span>Expires in</span>
+ <select value={ttl} onChange={(e) => setTtl(Number(e.target.value))}>
+ {TTL_OPTIONS.map((minutes) => (
+ <option key={minutes} value={minutes}>{minutes} minutes</option>
+ ))}
+ </select>
+ </label>
+
+ <label className="login-links__bind">
+ <input
+ type="checkbox"
+ checked={bindIp}
+ onChange={(e) => setBindIp(e.target.checked)}
+ />
+ <span>Bind to an IP</span>
+ </label>
+
+ {bindIp && (
+ <label className="login-links__field">
+ <span>Allowed IP</span>
+ <input
+ type="text"
+ value={boundIp}
+ onChange={(e) => setBoundIp(e.target.value)}
+ placeholder="e.g. 203.0.113.7"
+ />
+ </label>
+ )}
+
+ <Button type="submit" variant="secondary" disabled={minting || !userId}>
+ {minting ? 'Generating…' : 'Generate Link'}
+ </Button>
+ </form>
+
+ {bindIp && (
+ <p className="login-links__note">
+ The link will only work from the IP entered above — use the
+ recipient&apos;s public IP, not your own.
+ </p>
+ )}
+
+ {minted && (
+ <div className="login-links__reveal">
+ <p className="login-links__reveal-title">
+ Copy this URL now — it will not be shown again.
+ </p>
+ <div className="login-links__reveal-row">
+ <code>{minted.url}</code>
+ <Button type="button" size="sm" onClick={handleCopy}>
+ {copied ? 'Copied' : 'Copy URL'}
+ </Button>
+ </div>
+ </div>
+ )}
+
+ {links.length > 0 && (
+ <ul className="login-links__list">
+ {links.map((link) => (
+ <li key={link.id} className="login-links__item">
+ <div className="login-links__item-info">
+ <span className="login-links__item-user">{link.username}</span>
+ <span className="login-links__item-meta">
+ expires {formatExpiry(link.expires_at)}
+ {link.bound_ip ? ` · bound to ${link.bound_ip}` : ''}
+ {link.created_by ? ` · by ${link.created_by}` : ''}
+ </span>
+ </div>
+ <Button
+ type="button"
+ variant="ghost"
+ size="sm"
+ onClick={() => handleRevoke(link.id)}
+ >
+ Revoke
+ </Button>
+ </li>
+ ))}
+ </ul>
+ )}
+ </div>
+ );
+};
+
+export default LoginLinksSection;
diff --git a/frontend/src/components/settings/UsersTab.jsx b/frontend/src/components/settings/UsersTab.jsx
index 62266f5d..948ccbdf 100644
--- a/frontend/src/components/settings/UsersTab.jsx
+++ b/frontend/src/components/settings/UsersTab.jsx
@@ -3,6 +3,7 @@ import api from '../../services/api';
import { useAuth } from '../../contexts/AuthContext';
import UserModal from './UserModal';
import InvitationsTab from './InvitationsTab';
+import LoginLinksSection from './LoginLinksSection';
import Modal from '../Modal';
import { Button } from '@/components/ui/button';
import { Badge } from '@/components/ui/badge';
@@ -240,6 +241,8 @@ const UsersTab = () => {
</Modal>
)}
+ <LoginLinksSection users={users} currentUserId={currentUser?.id} />
+
<InvitationsTab />
</div>
);
diff --git a/frontend/src/pages/Login.jsx b/frontend/src/pages/Login.jsx
index 4c2cd8f7..77addd92 100644
--- a/frontend/src/pages/Login.jsx
+++ b/frontend/src/pages/Login.jsx
@@ -14,6 +14,11 @@ const Login = () => {
const [error, setError] = useState('');
const [loading, setLoading] = useState(false);
+ // One-time login link + demo mode state
+ const [redeemingLink, setRedeemingLink] = useState(false);
+ const [demoInfo, setDemoInfo] = useState(null);
+ const linkAttempted = useRef(false);
+
// 2FA state
const [requires2FA, setRequires2FA] = useState(false);
const [tempToken, setTempToken] = useState('');
@@ -37,6 +42,42 @@ const Login = () => {
}
}, [location.state]);
+ // One-time login link redemption (?link=<token>). Single-use, so guard
+ // against double-invocation (React StrictMode re-runs effects).
+ useEffect(() => {
+ const token = new URLSearchParams(location.search).get('link');
+ if (!token || linkAttempted.current) return;
+ linkAttempted.current = true;
+
+ setRedeemingLink(true);
+ api.redeemLoginLink(token)
+ .then((response) => {
+ setUser(response.user);
+ navigate('/', { replace: true });
+ })
+ .catch((err) => {
+ setError(err.message || 'Invalid or expired login link');
+ setRedeemingLink(false);
+ navigate('/login', { replace: true });
+ });
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [location.search]);
+
+ // Demo mode: surface read-only credentials when the panel runs as a demo.
+ useEffect(() => {
+ api.getDemoInfo()
+ .then((info) => {
+ if (info?.enabled) setDemoInfo(info);
+ })
+ .catch(() => { /* demo info is a nicety — never block login */ });
+ }, []);
+
+ function fillDemoCredentials() {
+ if (!demoInfo) return;
+ setEmail(demoInfo.username);
+ setPassword(demoInfo.password);
+ }
+
async function handleSSOLogin(provider) {
setSsoLoading(provider);
setError('');
@@ -241,6 +282,23 @@ const Login = () => {
);
}
+ // A one-time login link is being redeemed — show a minimal waiting card
+ if (redeemingLink) {
+ return (
+ <div className="auth-container">
+ <div className="auth-card">
+ <div className="auth-header">
+ <div className="brand-logo">
+ <ServerKitLogo width={40} height={40} />
+ </div>
+ <h1>ServerKit</h1>
+ <p>Signing you in…</p>
+ </div>
+ </div>
+ </div>
+ );
+ }
+
// Render normal login form
return (
<div className="auth-container">
@@ -255,6 +313,18 @@ const Login = () => {
{error && <div className="error-message">{error}</div>}
+ {demoInfo && (
+ <div className="demo-hint">
+ <div className="demo-hint__title">Demo mode — sign in read-only</div>
+ <div className="demo-hint__creds">
+ <code>{demoInfo.username}</code> / <code>{demoInfo.password}</code>
+ </div>
+ <Button type="button" variant="link" className="demo-hint__fill" onClick={fillDemoCredentials}>
+ Use demo credentials
+ </Button>
+ </div>
+ )}
+
{ssoProviders && ssoProviders.length > 0 && (
<div className="sso-providers">
{ssoProviders.map(p => (
diff --git a/frontend/src/services/api/auth.js b/frontend/src/services/api/auth.js
index febf601b..bfb6a42f 100644
--- a/frontend/src/services/api/auth.js
+++ b/frontend/src/services/api/auth.js
@@ -47,6 +47,36 @@ export async function updateCurrentUser(data) {
});
}
+// One-time login links
+export async function mintLoginLink(data = {}) {
+ return this.request('/auth/login-links', {
+ method: 'POST',
+ body: data,
+ });
+}
+
+export async function getLoginLinks() {
+ return this.request('/auth/login-links');
+}
+
+export async function revokeLoginLink(id) {
+ return this.request(`/auth/login-links/${id}`, { method: 'DELETE' });
+}
+
+export async function redeemLoginLink(token) {
+ const data = await this.request('/auth/login-links/redeem', {
+ method: 'POST',
+ body: { token },
+ });
+ this.setTokens(data.access_token, data.refresh_token);
+ return data;
+}
+
+// Demo mode
+export async function getDemoInfo() {
+ return this.request('/auth/demo-info');
+}
+
// Admin - User Management endpoints
export async function getUsers() {
return this.request('/admin/users');
diff --git a/frontend/src/styles/components/_users.scss b/frontend/src/styles/components/_users.scss
index 6a5816b9..bc6f06a6 100644
--- a/frontend/src/styles/components/_users.scss
+++ b/frontend/src/styles/components/_users.scss
@@ -830,3 +830,113 @@
color: $text-tertiary;
}
}
+
+// --------------------------------------------
+// One-Time Login Links (Users tab)
+// --------------------------------------------
+.login-links {
+ margin-top: $space-10;
+
+ &__form {
+ display: flex;
+ flex-wrap: wrap;
+ align-items: flex-end;
+ gap: $space-4;
+ }
+
+ &__field {
+ display: flex;
+ flex-direction: column;
+ gap: $space-1;
+
+ span {
+ font-size: $font-size-xs;
+ color: $text-secondary;
+ }
+
+ select,
+ input {
+ min-width: 160px;
+ padding: $space-2 $space-3;
+ background: $bg-card;
+ border: 1px solid $border-default;
+ border-radius: $radius-md;
+ color: $text-primary;
+ font-size: $font-size-sm;
+ }
+ }
+
+ &__bind {
+ display: inline-flex;
+ align-items: center;
+ gap: $space-2;
+ padding-bottom: $space-2;
+ font-size: $font-size-sm;
+ color: $text-secondary;
+ cursor: pointer;
+ }
+
+ &__note {
+ margin-top: $space-2;
+ font-size: $font-size-xs;
+ color: $text-tertiary;
+ }
+
+ &__reveal {
+ margin-top: $space-4;
+ padding: $space-4;
+ border: 1px solid $border-default;
+ border-radius: $radius-md;
+ background: $bg-hover;
+
+ &-title {
+ margin: 0 0 $space-2;
+ font-size: $font-size-sm;
+ font-weight: 600;
+ }
+
+ &-row {
+ display: flex;
+ align-items: center;
+ gap: $space-3;
+
+ code {
+ flex: 1;
+ overflow-x: auto;
+ white-space: nowrap;
+ font-size: $font-size-xs;
+ }
+ }
+ }
+
+ &__list {
+ list-style: none;
+ margin: $space-4 0 0;
+ padding: 0;
+ border: 1px solid $border-default;
+ border-radius: $radius-md;
+ }
+
+ &__item {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: $space-3;
+ padding: $space-3 $space-4;
+
+ + .login-links__item {
+ border-top: 1px solid $border-subtle;
+ }
+ }
+
+ &__item-user {
+ font-size: $font-size-sm;
+ font-weight: 500;
+ margin-right: $space-2;
+ }
+
+ &__item-meta {
+ font-size: $font-size-xs;
+ color: $text-tertiary;
+ }
+}
diff --git a/frontend/src/styles/pages/_auth.scss b/frontend/src/styles/pages/_auth.scss
index ee54d376..38e6cf10 100644
--- a/frontend/src/styles/pages/_auth.scss
+++ b/frontend/src/styles/pages/_auth.scss
@@ -122,3 +122,43 @@
from { transform: rotate(0deg); }
to { transform: rotate(360deg); }
}
+
+// Demo mode hint on the login card
+.demo-hint {
+ margin-bottom: $space-6;
+ padding: $space-4;
+ border: 1px solid $border-subtle;
+ border-radius: $radius-lg;
+ background: $bg-hover;
+ text-align: center;
+
+ &__title {
+ font-size: $font-size-sm;
+ font-weight: $font-weight-medium;
+ margin-bottom: $space-2;
+ }
+
+ &__creds {
+ font-size: $font-size-sm;
+ color: $text-secondary;
+ margin-bottom: $space-3;
+
+ code {
+ color: $text-primary;
+ }
+ }
+
+ &__fill {
+ background: none;
+ border: none;
+ padding: 0;
+ color: $accent-primary;
+ font-size: $font-size-sm;
+ font-weight: $font-weight-medium;
+ cursor: pointer;
+
+ &:hover {
+ text-decoration: underline;
+ }
+ }
+}