Merge pull request 'feat: add 'agent' API key role (content CRUD + backup)' (#4) from feat/agent-role into main

Reviewed-on: #4

api/__init__.py

@@ -224,3 +224,24 @@ def update_last_used(api_key):
             {APIKey.last_used_at: datetime.now(UTC)}
         )
         session.commit()
+
+
+def get_actor():
+    """Identity string to record as author/last_modified_by.
+
+    - X-API-Key request -> the key's alias
+    - Keycloak Bearer request -> the literal 'admin' (the backend does not
+      track individual KC identities)
+    - otherwise -> None
+    Call only from endpoints already behind @require_auth.
+    """
+    api_key_header = request.headers.get('X-API-Key')
+    if api_key_header:
+        api_key = get_api_key(api_key_header)
+        if api_key:
+            return api_key.alias
+        return None
+    auth_header = request.headers.get('Authorization')
+    if auth_header and auth_header.startswith('Bearer'):
+        return 'admin'
+    return None

api/apikey/__init__.py

@@ -1,3 +1,4 @@
+from datetime import datetime, timedelta, UTC
 from flask import Blueprint, request, jsonify
 from api import generate_api_key
 from db import get_db
@@ -8,15 +9,33 @@ api_key_bp = Blueprint('apikey', __name__, url_prefix='/api/apikey')
 
 # An API key must never be able to request a role broader than what the
 # product defines, regardless of what the request body asks for.
-ALLOWED_API_KEY_ROLES = {'admin', 'creator', 'user'}
+ALLOWED_API_KEY_ROLES = {'admin', 'creator', 'user', 'agent'}
+
+# Validity window applied on create and on every renewal.
+KEY_TTL = timedelta(days=15)
 
 @api_key_bp.route('/', methods=['POST'])
 @require_auth(roles=['admin'])
 def create_key():
-    data = request.get_json(silent=True)
+    """Create an API key, or renew an existing one.
 
-    if not data or 'name' not in data:
+    `alias` is required and unique. Creating with an alias that already
+    exists is treated as a RENEWAL of that key: the same key string is
+    kept (so existing integrations keep working), its validity window is
+    reset, it is reactivated, and name/roles are updated. The (unchanged)
+    key string is returned again.
+    """
+    data = request.get_json(silent=True)
+    if not data:
+        return jsonify({"error": "invalid or missing JSON body"}), 400
+
+    alias = data.get('alias')
+    name = data.get('name')
+    if not alias or not str(alias).strip():
+        return jsonify({"error": "alias is required"}), 400
+    if not name:
         return jsonify({"error": "Name is required"}), 400
+    alias = str(alias).strip()
 
     roles = data.get('roles', [])
     if not isinstance(roles, list) or any(r not in ALLOWED_API_KEY_ROLES for r in roles):
@@ -24,10 +43,29 @@ def create_key():
 
     try:
         with get_db() as session:
-            apikey = APIKey(key=generate_api_key(), name=data['name'], roles=roles)
+            existing = session.query(APIKey).filter_by(alias=alias).first()
+            if existing is not None:
+                # Renewal: keep the key string, reset validity, reactivate.
+                existing.name = name
+                existing.roles = roles
+                existing.is_active = True
+                existing.expire = datetime.now(UTC) + KEY_TTL
+                session.commit()
+                result = existing.to_dict()
+                result['renewed'] = True
+                return jsonify(result), 200
+
+            apikey = APIKey(
+                key=generate_api_key(),
+                alias=alias,
+                name=name,
+                roles=roles,
+                expire=datetime.now(UTC) + KEY_TTL,
+            )
             session.add(apikey)
             session.commit()
             result = apikey.to_dict()
+            result['renewed'] = False
         return jsonify(result), 201
     except Exception as e:
         return jsonify({"error": str(e)}), 500

api/backup.py

@@ -346,7 +346,7 @@ def convert_backup_endpoint():
 
 backup_lock = threading.Lock()
 @backup_bp.route('/', methods=['GET'])
-@require_auth(roles=['admin'])
+@require_auth(roles=['admin', 'agent'])
 def get_backup():
     """
     Create a backup of the application's data.
@@ -558,7 +558,7 @@ def traverse(path_id, paths):
 
 
 @backup_bp.route('/load', methods=['POST'])
-@require_auth(roles=['admin'])
+@require_auth(roles=['admin', 'agent'])
 def load_backup():
     """
     Restore data from a backup file.

api/markdown.py

@@ -1,8 +1,9 @@
 from flask import Blueprint, request, jsonify
 from sqlalchemy import or_
 from api import limiter
-from api import require_auth, etag_response, verify_token, is_user_admin
+from api import require_auth, etag_response, verify_token, is_user_admin, get_actor
 from contexts.RequestContext import RequestContext
+from datetime import datetime, UTC
 from db import get_db
 from db.models.Markdown import Markdown
 from db.models.MarkdownSetting import MarkdownSetting
@@ -193,7 +194,7 @@ def get_markdown(markdown_id):
         return jsonify(markdown.to_dict()), 200
 
 @markdown_bp.route('/', methods=['POST'])
-@require_auth(roles=['admin', 'creator'])
+@require_auth(roles=['admin', 'creator', 'agent'])
 @limiter.limit(api.get_rate_limit)
 def create_markdown():
     """
@@ -225,7 +226,13 @@ def create_markdown():
     setting_id = data.get('setting_id', None)
     if not title or not content:
         return jsonify({"error": "missing required fields"}), 400
-    new_markdown = Markdown(title=title, content=content, path_id=path_id, shortcut=shortcut, setting_id=setting_id)
+    actor = get_actor()
+    now = datetime.now(UTC)
+    new_markdown = Markdown(
+        title=title, content=content, path_id=path_id, shortcut=shortcut,
+        setting_id=setting_id, author=actor, last_modified_by=actor,
+        created_at=now, updated_at=now,
+    )
     with get_db() as session:
         try:
             if shortcut != "":
@@ -243,7 +250,7 @@ def create_markdown():
             return jsonify({"error": f"create failed - {errno}"}), 500
 
 @markdown_bp.route('/<int:markdown_id>', methods=['PUT', 'PATCH'])
-@require_auth(roles=['admin', 'creator'])
+@require_auth(roles=['admin', 'creator', 'agent'])
 @limiter.limit(api.get_rate_limit)
 def update_markdown(markdown_id):
     """
@@ -301,12 +308,14 @@ def update_markdown(markdown_id):
                 markdown.shortcut = data.get('shortcut')
             if 'setting_id' in data:
                 markdown.setting_id = data.get('setting_id')
+        markdown.updated_at = datetime.now(UTC)
+        markdown.last_modified_by = get_actor()
         session.commit()
         markdown_updated.send(None, payload=markdown.to_dict())
         return jsonify(markdown.to_dict()), 200
 
 @markdown_bp.route('/<int:markdown_id>', methods=['DELETE'])
-@require_auth(roles=['admin'])
+@require_auth(roles=['admin', 'agent'])
 @limiter.limit(api.get_rate_limit)
 def delete_markdown(markdown_id):
     """
@@ -382,7 +391,7 @@ def delete_markdown(markdown_id):
 
 
 @markdown_bp.route('/move_forward/<int:markdown_id>', methods=['PATCH'])
-@require_auth(roles=['admin'])
+@require_auth(roles=['admin', 'agent'])
 @limiter.limit(api.get_rate_limit)
 def move_forward(markdown_id):
     """
@@ -419,7 +428,7 @@ def move_forward(markdown_id):
 
 
 @markdown_bp.route('/move_backward/<int:markdown_id>', methods=['PATCH'])
-@require_auth(roles=['admin'])
+@require_auth(roles=['admin', 'agent'])
 @limiter.limit(api.get_rate_limit)
 def move_backward(markdown_id):
     """

api/patch.py

@@ -1,5 +1,6 @@
+from datetime import datetime, UTC
 from flask import Blueprint, request, jsonify
-from api import limiter, require_auth, is_user_admin
+from api import limiter, require_auth, is_user_admin, get_actor
 from contexts.RequestContext import RequestContext
 from db import get_db
 from db.models.Markdown import Markdown
@@ -50,7 +51,7 @@ def get_patches(markdown_id):
 
 
 @patch_bp.route('/', methods=['POST'])
-@require_auth(roles=['admin', 'creator'])
+@require_auth(roles=['admin', 'creator', 'agent'])
 @limiter.limit(api.get_rate_limit)
 def create_patch():
     """Create a patch card. Body: markdown_id, content, title?, order?"""
@@ -65,11 +66,17 @@ def create_patch():
         if session.query(Markdown).get(markdown_id) is None:
             return jsonify({"error": "markdown not found"}), 404
         try:
+            actor = get_actor()
+            now = datetime.now(UTC)
             patch = MarkdownPatch(
                 markdown_id=markdown_id,
                 title=data.get('title'),
                 content=content,
                 order=data.get('order', 0),
+                author=actor,
+                last_modified_by=actor,
+                created_at=now,
+                updated_at=now,
             )
             session.add(patch)
             session.commit()
@@ -82,7 +89,7 @@ def create_patch():
 
 
 @patch_bp.route('/<int:patch_id>', methods=['PUT', 'PATCH'])
-@require_auth(roles=['admin', 'creator'])
+@require_auth(roles=['admin', 'creator', 'agent'])
 @limiter.limit(api.get_rate_limit)
 def update_patch(patch_id):
     """Update a patch card (title/content/order)."""
@@ -104,12 +111,14 @@ def update_patch(patch_id):
                 patch.content = data.get('content')
             if 'order' in data:
                 patch.order = data.get('order')
+        patch.updated_at = datetime.now(UTC)
+        patch.last_modified_by = get_actor()
         session.commit()
         return jsonify(patch.to_dict()), 200
 
 
 @patch_bp.route('/<int:patch_id>', methods=['DELETE'])
-@require_auth(roles=['admin'])
+@require_auth(roles=['admin', 'agent'])
 @limiter.limit(api.get_rate_limit)
 def delete_patch(patch_id):
     """Delete a patch card."""

api/path.py

@@ -82,7 +82,7 @@ def get_path_by_parent(parent_id):
 
 @path_bp.route('/', methods=['POST'])
 @limiter.limit(api.get_rate_limit)
-@require_auth(roles=['admin', 'creator'])
+@require_auth(roles=['admin', 'creator', 'agent'])
 def create_path():
     """
     Create a new path.
@@ -119,7 +119,7 @@ def create_path():
 
 @path_bp.route('/<int:path_id>', methods=['PUT'])
 @limiter.limit(api.get_rate_limit)
-@require_auth(roles=['admin'])
+@require_auth(roles=['admin', 'agent'])
 def update_path(path_id):
     """
     Update a path.
@@ -158,7 +158,7 @@ def update_path(path_id):
 
 @path_bp.route('/<int:path_id>', methods=['PATCH'])
 @limiter.limit(api.get_rate_limit)
-@require_auth(roles=['admin'])
+@require_auth(roles=['admin', 'agent'])
 def patch_path(path_id):
     """
     Partially update a path.
@@ -205,7 +205,7 @@ def patch_path(path_id):
 
 @path_bp.route('/<int:path_id>', methods=['DELETE'])
 @limiter.limit(api.get_rate_limit)
-@require_auth(roles=['admin'])
+@require_auth(roles=['admin', 'agent'])
 def delete_path(path_id):
     """
     Delete a path.
@@ -240,7 +240,7 @@ def delete_path(path_id):
 
 
 @path_bp.route('/move_forward/<int:path_id>', methods=['PATCH'])
-@require_auth(roles=['admin'])
+@require_auth(roles=['admin', 'agent'])
 @limiter.limit(api.get_rate_limit)
 def move_forward(path_id):
     """
@@ -277,7 +277,7 @@ def move_forward(path_id):
 
 
 @path_bp.route('/move_backward/<int:path_id>', methods=['PATCH'])
-@require_auth(roles=['admin'])
+@require_auth(roles=['admin', 'agent'])
 @limiter.limit(api.get_rate_limit)
 def move_backward(path_id):
     """

apikey_cli.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""Admin CLI for API key management — no HTTP, no admin login.
+
+Operates directly on the database (same env as the backend), so it must
+run where the DB is reachable, e.g. inside the backend container:
+
+    docker compose exec backend python apikey_cli.py create \
+        --alias ci-bot --name "CI bot" --roles creator
+
+    docker compose exec backend python apikey_cli.py list
+    docker compose exec backend python apikey_cli.py revoke --alias ci-bot
+
+`create` with an existing --alias renews that key (same key string,
+validity reset, reactivated, name/roles updated) — matching the HTTP
+POST /api/apikey behaviour.
+"""
+import argparse
+import secrets
+import string
+import sys
+from datetime import datetime, timedelta, UTC
+
+from db import get_db
+from db.models.APIKey import APIKey
+
+# Keep in sync with api.apikey.ALLOWED_API_KEY_ROLES
+ALLOWED_ROLES = {"admin", "creator", "user", "agent"}
+KEY_TTL_DEFAULT_DAYS = 15
+
+
+def _gen_key(length=32):
+    alphabet = string.ascii_letters + string.digits
+    return "".join(secrets.choice(alphabet) for _ in range(length))
+
+
+def _validate_roles(roles):
+    bad = [r for r in roles if r not in ALLOWED_ROLES]
+    if bad:
+        sys.exit(f"error: invalid role(s) {bad}; allowed: {sorted(ALLOWED_ROLES)}")
+
+
+def cmd_create(args):
+    alias = args.alias.strip()
+    if not alias:
+        sys.exit("error: --alias is required")
+    roles = args.roles or []
+    _validate_roles(roles)
+    expire = datetime.now(UTC) + timedelta(days=args.ttl_days)
+
+    with get_db() as session:
+        existing = session.query(APIKey).filter_by(alias=alias).first()
+        if existing is not None:
+            existing.name = args.name
+            existing.roles = roles
+            existing.is_active = True
+            existing.expire = expire
+            session.commit()
+            row, renewed = existing.to_dict(), True
+        else:
+            ak = APIKey(
+                key=_gen_key(), alias=alias, name=args.name,
+                roles=roles, expire=expire,
+            )
+            session.add(ak)
+            session.commit()
+            row, renewed = ak.to_dict(), False
+
+    print("renewed" if renewed else "created")
+    print(f"  alias : {row['alias']}")
+    print(f"  name  : {row['name']}")
+    print(f"  roles : {row['roles']}")
+    print(f"  expire: {row['expire']}")
+    print(f"  key   : {row['key']}")
+
+
+def cmd_list(args):
+    with get_db() as session:
+        keys = session.query(APIKey).order_by(APIKey.created_at).all()
+        rows = [k.to_dict() for k in keys]
+    if not rows:
+        print("(no API keys)")
+        return
+    for r in rows:
+        key = r["key"] if args.show_keys else (r["key"][:6] + "…")
+        state = "active" if r["is_active"] else "revoked"
+        print(
+            f"{r['alias']!r:<22} {state:<8} roles={r['roles']} "
+            f"expire={r['expire']} last_used={r['last_used_at']} "
+            f"name={r['name']!r} key={key}"
+        )
+
+
+def cmd_revoke(args):
+    with get_db() as session:
+        q = session.query(APIKey)
+        ak = (q.filter_by(alias=args.alias).first() if args.alias
+              else q.filter_by(key=args.key).first())
+        if ak is None:
+            sys.exit("error: API key not found")
+        ak.is_active = False
+        session.commit()
+        print(f"revoked: alias={ak.alias} name={ak.name!r}")
+
+
+def main():
+    p = argparse.ArgumentParser(prog="apikey_cli", description=__doc__)
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    c = sub.add_parser("create", help="create or renew (by alias) an API key")
+    c.add_argument("--alias", required=True, help="unique alias; reuse to renew")
+    c.add_argument("--name", required=True, help="human-readable name")
+    c.add_argument("--roles", nargs="*", default=[],
+                   help=f"subset of {sorted(ALLOWED_ROLES)}")
+    c.add_argument("--ttl-days", type=int, default=KEY_TTL_DEFAULT_DAYS,
+                   dest="ttl_days", help="validity window in days")
+    c.set_defaults(func=cmd_create)
+
+    l = sub.add_parser("list", help="list all API keys")
+    l.add_argument("--show-keys", action="store_true",
+                   help="print full key strings (default: masked)")
+    l.set_defaults(func=cmd_list)
+
+    r = sub.add_parser("revoke", help="deactivate an API key")
+    g = r.add_mutually_exclusive_group(required=True)
+    g.add_argument("--alias", help="revoke by alias")
+    g.add_argument("--key", help="revoke by key string")
+    r.set_defaults(func=cmd_revoke)
+
+    args = p.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

db/__init__.py

@@ -59,12 +59,71 @@ def init_payload():
         session.commit()
 
 
+def _column_exists(conn, table, column):
+    row = conn.execute(text(
+        "SELECT 1 FROM information_schema.columns "
+        "WHERE table_schema = :db AND table_name = :t AND column_name = :c"
+    ), {"db": DB_NAME, "t": table, "c": column}).first()
+    return row is not None
+
+
+def _index_exists(conn, table, index):
+    row = conn.execute(text(
+        "SELECT 1 FROM information_schema.statistics "
+        "WHERE table_schema = :db AND table_name = :t AND index_name = :i"
+    ), {"db": DB_NAME, "t": table, "i": index}).first()
+    return row is not None
+
+
+def run_migrations():
+    """Idempotent additive schema migrations for already-existing tables.
+
+    create_all() creates missing tables (with the new columns) for a fresh
+    DB, but never alters existing ones. This adds the new columns to legacy
+    tables and backfills sensible defaults. Safe to run on every startup.
+    """
+    # (table, column, DDL, backfill SQL or None)
+    steps = [
+        ("apikey", "alias", "ALTER TABLE apikey ADD COLUMN alias VARCHAR(255) NULL",
+         "UPDATE apikey SET alias = `key` WHERE alias IS NULL"),
+        ("markdown", "updated_at", "ALTER TABLE markdown ADD COLUMN updated_at DATETIME NULL",
+         "UPDATE markdown SET updated_at = created_at WHERE updated_at IS NULL"),
+        ("markdown", "author", "ALTER TABLE markdown ADD COLUMN author VARCHAR(255) NULL",
+         "UPDATE markdown SET author = 'admin' WHERE author IS NULL"),
+        ("markdown", "last_modified_by", "ALTER TABLE markdown ADD COLUMN last_modified_by VARCHAR(255) NULL",
+         "UPDATE markdown SET last_modified_by = 'admin' WHERE last_modified_by IS NULL"),
+        ("markdown_patch", "author", "ALTER TABLE markdown_patch ADD COLUMN author VARCHAR(255) NULL",
+         "UPDATE markdown_patch SET author = 'admin' WHERE author IS NULL"),
+        ("markdown_patch", "last_modified_by", "ALTER TABLE markdown_patch ADD COLUMN last_modified_by VARCHAR(255) NULL",
+         "UPDATE markdown_patch SET last_modified_by = 'admin' WHERE last_modified_by IS NULL"),
+    ]
+    try:
+        with engine.begin() as conn:
+            for table, column, ddl, backfill in steps:
+                if not _column_exists(conn, table, column):
+                    conn.execute(text(ddl))
+                    if backfill:
+                        conn.execute(text(backfill))
+                    print(f"[ x ] migrated {table}.{column}")
+            # Unique constraint on apikey.alias once it is populated.
+            if not _index_exists(conn, "apikey", "uq_apikey_alias"):
+                conn.execute(text(
+                    "ALTER TABLE apikey ADD CONSTRAINT uq_apikey_alias UNIQUE (alias)"
+                ))
+                print("[ x ] migrated apikey.alias unique constraint")
+    except Exception as e:
+        # Don't block startup on a migration hiccup; surface loudly.
+        print(f"[ ! ] run_migrations error (continuing): {e}")
+
+
 def setup_db():
     if DB_SCHEMA_UPDATED:
         clear_db()
         print("[ x ] db cleared")
     create_all()
     print("[ x ] db created")
+    run_migrations()
+    print("[ x ] db migrations applied")
     run_scripts()
     print("[ x ] db scripts executed")
     init_payload()

db/migrations/2026-05-16_apikey_alias_authorship.sql

@@ -0,0 +1,79 @@
+-- ============================================================================
+-- Production migration: apikey.alias (unique) + markdown/patch authorship
+-- ============================================================================
+-- Idempotent. Safe to run multiple times. Target: MySQL 8 (no native
+-- ADD COLUMN IF NOT EXISTS, so columns are guarded via information_schema
+-- + a prepared statement). Mirrors the app's db.run_migrations(); running
+-- both is harmless.
+--
+-- Apply against the application schema, e.g.:
+--   docker exec -i mysql sh -c 'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" hangmanlab' \
+--       < 2026-05-16_apikey_alias_authorship.sql
+-- ============================================================================
+
+SET @schema := DATABASE();
+
+-- ---- helper macro is not available in plain SQL; repeat the guarded block --
+
+-- apikey.alias --------------------------------------------------------------
+SET @c := (SELECT COUNT(*) FROM information_schema.columns
+           WHERE table_schema=@schema AND table_name='apikey' AND column_name='alias');
+SET @ddl := IF(@c=0,
+    'ALTER TABLE apikey ADD COLUMN alias VARCHAR(255) NULL',
+    'DO 0');
+PREPARE st FROM @ddl; EXECUTE st; DEALLOCATE PREPARE st;
+-- backfill: existing keys get alias = their (unique) key string
+UPDATE apikey SET alias = `key` WHERE alias IS NULL;
+
+-- apikey unique constraint on alias -----------------------------------------
+SET @i := (SELECT COUNT(*) FROM information_schema.statistics
+           WHERE table_schema=@schema AND table_name='apikey' AND index_name='uq_apikey_alias');
+SET @ddl := IF(@i=0,
+    'ALTER TABLE apikey ADD CONSTRAINT uq_apikey_alias UNIQUE (alias)',
+    'DO 0');
+PREPARE st FROM @ddl; EXECUTE st; DEALLOCATE PREPARE st;
+
+-- markdown.updated_at -------------------------------------------------------
+SET @c := (SELECT COUNT(*) FROM information_schema.columns
+           WHERE table_schema=@schema AND table_name='markdown' AND column_name='updated_at');
+SET @ddl := IF(@c=0,
+    'ALTER TABLE markdown ADD COLUMN updated_at DATETIME NULL',
+    'DO 0');
+PREPARE st FROM @ddl; EXECUTE st; DEALLOCATE PREPARE st;
+UPDATE markdown SET updated_at = created_at WHERE updated_at IS NULL;
+
+-- markdown.author -----------------------------------------------------------
+SET @c := (SELECT COUNT(*) FROM information_schema.columns
+           WHERE table_schema=@schema AND table_name='markdown' AND column_name='author');
+SET @ddl := IF(@c=0,
+    'ALTER TABLE markdown ADD COLUMN author VARCHAR(255) NULL',
+    'DO 0');
+PREPARE st FROM @ddl; EXECUTE st; DEALLOCATE PREPARE st;
+UPDATE markdown SET author = 'admin' WHERE author IS NULL;
+
+-- markdown.last_modified_by -------------------------------------------------
+SET @c := (SELECT COUNT(*) FROM information_schema.columns
+           WHERE table_schema=@schema AND table_name='markdown' AND column_name='last_modified_by');
+SET @ddl := IF(@c=0,
+    'ALTER TABLE markdown ADD COLUMN last_modified_by VARCHAR(255) NULL',
+    'DO 0');
+PREPARE st FROM @ddl; EXECUTE st; DEALLOCATE PREPARE st;
+UPDATE markdown SET last_modified_by = 'admin' WHERE last_modified_by IS NULL;
+
+-- markdown_patch.author -----------------------------------------------------
+SET @c := (SELECT COUNT(*) FROM information_schema.columns
+           WHERE table_schema=@schema AND table_name='markdown_patch' AND column_name='author');
+SET @ddl := IF(@c=0,
+    'ALTER TABLE markdown_patch ADD COLUMN author VARCHAR(255) NULL',
+    'DO 0');
+PREPARE st FROM @ddl; EXECUTE st; DEALLOCATE PREPARE st;
+UPDATE markdown_patch SET author = 'admin' WHERE author IS NULL;
+
+-- markdown_patch.last_modified_by -------------------------------------------
+SET @c := (SELECT COUNT(*) FROM information_schema.columns
+           WHERE table_schema=@schema AND table_name='markdown_patch' AND column_name='last_modified_by');
+SET @ddl := IF(@c=0,
+    'ALTER TABLE markdown_patch ADD COLUMN last_modified_by VARCHAR(255) NULL',
+    'DO 0');
+PREPARE st FROM @ddl; EXECUTE st; DEALLOCATE PREPARE st;
+UPDATE markdown_patch SET last_modified_by = 'admin' WHERE last_modified_by IS NULL;

db/models/APIKey.py

@@ -6,6 +6,9 @@ class APIKey(Base):
     __tablename__ = 'apikey'
 
     key = Column(String(64), primary_key=True)
+    # Stable human identity of the key. Unique; creating with an existing
+    # alias is treated as a renewal of that key (see api/apikey).
+    alias = Column(String(255), nullable=False, unique=True)
     name = Column(String(255), nullable=False)
     created_at = Column(DateTime, nullable=False, default=lambda: datetime.now(UTC))
     last_used_at = Column(DateTime)
@@ -16,6 +19,7 @@ class APIKey(Base):
     def to_dict(self):
         return {
             "key": self.key,
+            "alias": self.alias,
             "name": self.name,
             "created_at": self.created_at.isoformat() if self.created_at else None,
             "last_used_at": self.last_used_at.isoformat() if self.last_used_at else None,

db/models/Markdown.py

@@ -9,7 +9,15 @@ class Markdown(Base):
     id = Column(Integer, primary_key=True)
     title = Column(String(255), nullable=False)
     content = Column(Text, nullable=False)
-    created_at = Column(DateTime, default=datetime.datetime.now(datetime.UTC))
+    created_at = Column(DateTime, default=lambda: datetime.datetime.now(datetime.UTC))
+    updated_at = Column(
+        DateTime,
+        default=lambda: datetime.datetime.now(datetime.UTC),
+        onupdate=lambda: datetime.datetime.now(datetime.UTC),
+    )
+    # Actor strings: alias of the API key, or 'admin' for KC-logged-in UI.
+    author = Column(String(255), nullable=True)
+    last_modified_by = Column(String(255), nullable=True)
     path_id = Column(Integer, ForeignKey('path.id'), nullable=False)
     order = Column(String(36), default=lambda: str(uuid.uuid4()))
     shortcut = Column(String(36), default="")
@@ -21,6 +29,9 @@ class Markdown(Base):
             'title': self.title,
             'content': self.content,
             'created_at': self.created_at,
+            'updated_at': self.updated_at,
+            'author': self.author,
+            'last_modified_by': self.last_modified_by,
             'path_id': self.path_id,
             'order': self.order,
             'shortcut': self.shortcut,

db/models/MarkdownPatch.py

@@ -17,6 +17,9 @@ class MarkdownPatch(Base):
     )
     title = Column(String(255), nullable=True)
     content = Column(Text, nullable=False)
+    # Actor strings: alias of the API key, or 'admin' for KC-logged-in UI.
+    author = Column(String(255), nullable=True)
+    last_modified_by = Column(String(255), nullable=True)
     order = Column(Integer, default=0)
     created_at = Column(DateTime, default=lambda: datetime.datetime.now(datetime.UTC))
     updated_at = Column(
@@ -31,6 +34,8 @@ class MarkdownPatch(Base):
             'markdown_id': self.markdown_id,
             'title': self.title,
             'content': self.content,
+            'author': self.author,
+            'last_modified_by': self.last_modified_by,
             'order': self.order,
             'created_at': self.created_at,
             'updated_at': self.updated_at,