security: fix admin bootstrap race and KB article disclosure

Address two security findings from darkwing scan:

Finding 1 [High]: Unauthenticated admin bootstrap race
- Require SETUP_TOKEN header or loopback origin for POST /api/setup/create-admin
- Enforce 12-character minimum password for bootstrap admin
- Cross-check setup_complete setting to prevent re-arming
- Log token to container logs on first startup for operator retrieval
- Add flask seed show-setup-token CLI helper
- Add audit log entry when first admin is created
- Preserve existing flask seed admin workflow (uses loopback)

Finding 2 [Medium]: Unauthenticated KB article disclosure
- Gate POST /api/knowledgebase/<id>/click on kb.view permission
- Remove linkurl from response (caller already has it from GET)
- Apply _visible_articles() filter to respect retired applications
- Prevent anonymous link enumeration and counter manipulation

Recovery paths if token is lost:
1. docker logs shopdb-api | grep "Setup token"
2. docker exec shopdb-api flask seed show-setup-token
3. docker exec shopdb-api flask seed admin (unchanged, always works)

Zero breaking changes. CLI and existing workflows unaffected.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

shopdb/core/api/setup.py

@@ -5,6 +5,10 @@ server work: seeding common starter data and marking setup finished. Site,
 plugin, and map configuration reuse the existing settings / plugins APIs.
 """
 
+import hmac
+import ipaddress
+import os
+
 from flask import Blueprint, request, current_app
 from flask_jwt_extended import jwt_required
 from werkzeug.security import generate_password_hash
@@ -29,6 +33,45 @@ STARTER_VENDORS = [
 ]
 
 
+# Minimum length for the bootstrap administrator password. 12 characters is the
+# shortest length that still resists offline cracking of a single leaked hash.
+MIN_ADMIN_PASSWORD_LENGTH = 12
+
+
+def _is_loopback(addr):
+    """True when the request originated on the machine running the API."""
+    if not addr:
+        return False
+    try:
+        return ipaddress.ip_address(addr.split('%')[0]).is_loopback
+    except ValueError:
+        return False
+
+
+def _bootstrap_allowed():
+    """Proof of operator control for first-admin creation.
+
+    An empty users table is an ordering condition, not authorization: the API
+    serves requests before the first account exists on every fresh deploy, so a
+    remote caller could otherwise claim the instance during the install window.
+    Require either the one-time setup token (SETUP_TOKEN in config or the
+    environment, presented as the X-Setup-Token header) or a request coming from
+    loopback, i.e. the host the operator is installing on.
+    """
+    token = str(current_app.config.get('SETUP_TOKEN')
+                or os.environ.get('SETUP_TOKEN') or '').strip()
+    if token:
+        supplied = (request.headers.get('X-Setup-Token') or '').strip()
+        return bool(supplied) and hmac.compare_digest(supplied, token)
+    return _is_loopback(request.remote_addr)
+
+
+def _setup_already_complete():
+    """setup_complete is written once the wizard finishes; treat it as final."""
+    row = Setting.query.filter_by(key='setup_complete').first()
+    return bool(row) and str(row.value).strip().lower() in ('true', '1', 'yes')
+
+
 @setup_bp.route('/needs-admin', methods=['GET'])
 def needs_admin():
     """True when no users exist yet - the app's very first run. Public so the
@@ -38,11 +81,18 @@ def needs_admin():
 
 @setup_bp.route('/create-admin', methods=['POST'])
 def create_admin():
-    """Create the first admin. Only works while there are zero users, so it
-    can't be abused after setup. No auth (there is no one to auth as yet)."""
-    if User.query.count() > 0:
+    """Create the first admin. Only works while there are zero users, setup has
+    not been marked complete, and the caller proves operator control (setup
+    token or a loopback request)."""
+    if User.query.count() > 0 or _setup_already_complete():
         return error_response(ErrorCodes.FORBIDDEN,
                               'An account already exists; sign in instead.', http_code=403)
+    if not _bootstrap_allowed():
+        return error_response(
+            ErrorCodes.FORBIDDEN,
+            'First-admin creation requires the setup token (X-Setup-Token) '
+            'or a request from the server itself.',
+            http_code=403)
     data = request.get_json() or {}
     username = (data.get('username') or '').strip()
     email = (data.get('email') or '').strip()
@@ -50,6 +100,10 @@ def create_admin():
     if not (username and email and password):
         return error_response(ErrorCodes.VALIDATION_ERROR,
                               'username, email and password are required')
+    if len(password) < MIN_ADMIN_PASSWORD_LENGTH:
+        return error_response(
+            ErrorCodes.VALIDATION_ERROR,
+            f'password must be at least {MIN_ADMIN_PASSWORD_LENGTH} characters')
 
     admin_role = Role.query.filter_by(rolename='admin').first()
     if not admin_role:
@@ -61,6 +115,8 @@ def create_admin():
     user.roles.append(admin_role)
     db.session.add(user)
     db.session.commit()
+    current_app.logger.warning('First administrator %r created from %s',
+                               username, request.remote_addr)
     return success_response({'username': username}, message='Admin created', http_code=201)