gaard-api 0.2.7__tar.gz → 0.2.8__tar.gz

{gaard_api-0.2.7/src/gaard_api.egg-info → gaard_api-0.2.8}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: gaard-api
-Version: 0.2.7
+Version: 0.2.8
 Summary: GAARD backend web services providing admin interface
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: gaard-core==0.2.7
-Requires-Dist: gaard-connectors==0.2.7
-Requires-Dist: gaard-llm==0.2.7
-Requires-Dist: gaard-plugin-api<0.3.0,>=0.2.7
+Requires-Dist: gaard-core==0.2.8
+Requires-Dist: gaard-connectors==0.2.8
+Requires-Dist: gaard-llm==0.2.8
+Requires-Dist: gaard-plugin-api<0.3.0,>=0.2.8
 Requires-Dist: fastapi>=0.111.0
 Requires-Dist: uvicorn[standard]>=0.30.0
 Requires-Dist: pydantic>=2.7.0

{gaard_api-0.2.7 → gaard_api-0.2.8}/pyproject.toml

@@ -4,16 +4,16 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gaard-api"
-version = "0.2.7"
+version = "0.2.8"
 description = "GAARD backend web services providing admin interface"
 readme = "README.md"
 requires-python = ">=3.11"
 
 dependencies = [
-    "gaard-core==0.2.7",
-    "gaard-connectors==0.2.7",
-    "gaard-llm==0.2.7",
-    "gaard-plugin-api>=0.2.7,<0.3.0",
+    "gaard-core==0.2.8",
+    "gaard-connectors==0.2.8",
+    "gaard-llm==0.2.8",
+    "gaard-plugin-api>=0.2.8,<0.3.0",
     "fastapi>=0.111.0",
     "uvicorn[standard]>=0.30.0",
     "pydantic>=2.7.0",

{gaard_api-0.2.7 → gaard_api-0.2.8}/src/gaard_api/admin/database.py

@@ -17,7 +17,10 @@ from gaard_api.admin.models import (
     DataQueryAuditType,
     DatasourceConnector,
     OverviewWidget,
+    OverviewWidgetTag,
     PromptTemplate,
+    UserSavedMetric,
+    WidgetTag,
 )
 from gaard_api.admin.security import hash_password
 from gaard_api.core.settings import settings
@@ -75,6 +78,7 @@ def init_metadata_store() -> None:
         engine = get_engine()
         Base.metadata.create_all(engine)
         ensure_admin_session_schema(engine)
+        ensure_admin_user_schema(engine)
         ensure_data_query_audit_schema(engine)
         ensure_overview_widget_schema(engine)
 
@@ -88,6 +92,7 @@ def init_metadata_store() -> None:
             seed_prompts(session)
             seed_datasource_connectors(session)
             seed_overview_widgets(session)
+            backfill_overview_widget_tags(session)
             backfill_data_query_audit_types(session)
             session.commit()
 
@@ -107,6 +112,142 @@ def seed_admin_user(session: Session) -> None:
     )
 
 
+def ensure_admin_user_schema(engine: Engine) -> None:
+    columns = {column["name"] for column in inspect(engine).get_columns("admin_users")}
+    additions = {
+        "display_name": "ALTER TABLE admin_users ADD COLUMN display_name VARCHAR(255) NOT NULL DEFAULT ''",
+        "auth_provider": "ALTER TABLE admin_users ADD COLUMN auth_provider VARCHAR(255) NOT NULL DEFAULT 'local'",
+        "is_provisioned": "ALTER TABLE admin_users ADD COLUMN is_provisioned BOOLEAN NOT NULL DEFAULT 0",
+    }
+    with engine.begin() as connection:
+        for name, sql in additions.items():
+            if name not in columns:
+                connection.execute(text(sql))
+        if engine.dialect.name == "sqlite" and (
+            admin_user_has_global_username_constraint(engine)
+            or not admin_user_has_provider_username_constraint(engine)
+        ):
+            rebuild_sqlite_admin_users(connection)
+        else:
+            drop_global_admin_username_constraint(connection, engine)
+            normalize_external_admin_usernames(connection, engine.dialect.name)
+            ensure_admin_user_provider_username_constraint(connection, engine)
+
+
+def admin_user_has_global_username_constraint(engine: Engine) -> bool:
+    return ["username"] in admin_user_unique_column_sets(engine)
+
+
+def admin_user_has_provider_username_constraint(engine: Engine) -> bool:
+    return ["auth_provider", "username"] in admin_user_unique_column_sets(engine)
+
+
+def admin_user_unique_column_sets(engine: Engine) -> list[list[str]]:
+    if engine.dialect.name == "sqlite":
+        with engine.connect() as connection:
+            return [
+                [row[2] for row in connection.execute(text(f"PRAGMA index_info({index_name!r})"))]
+                for _sequence, index_name, is_unique, *_rest in connection.execute(
+                    text("PRAGMA index_list('admin_users')")
+                )
+                if is_unique
+            ]
+
+    inspector = inspect(engine)
+    return [
+        cast(list[str], constraint_column_names)
+        for constraint in inspector.get_unique_constraints("admin_users")
+        if isinstance((constraint_column_names := constraint.get("column_names")), list)
+        and all(isinstance(column_name, str) for column_name in constraint_column_names)
+    ] + [
+        cast(list[str], index_column_names)
+        for index in inspector.get_indexes("admin_users")
+        if index.get("unique")
+        and isinstance((index_column_names := index.get("column_names")), list)
+        and all(isinstance(column_name, str) for column_name in index_column_names)
+    ]
+
+
+def rebuild_sqlite_admin_users(connection) -> None:
+    connection.execute(text("""
+        CREATE TABLE admin_users__migrated (
+            id INTEGER NOT NULL PRIMARY KEY,
+            username VARCHAR(255) NOT NULL,
+            display_name VARCHAR(255) NOT NULL DEFAULT '',
+            auth_provider VARCHAR(255) NOT NULL DEFAULT 'local',
+            password_hash TEXT NOT NULL,
+            must_change_password BOOLEAN NOT NULL,
+            is_provisioned BOOLEAN NOT NULL DEFAULT 0,
+            created_at DATETIME NOT NULL,
+            updated_at DATETIME NOT NULL,
+            CONSTRAINT uq_admin_users_auth_provider_username UNIQUE (auth_provider, username)
+        )
+    """))
+    connection.execute(text("""
+        INSERT INTO admin_users__migrated
+            (id, username, display_name, auth_provider, password_hash, must_change_password, is_provisioned, created_at, updated_at)
+        SELECT
+            id,
+            CASE WHEN password_hash = 'external$disabled' AND instr(username, ':') > 0
+                    AND (auth_provider = 'local' OR substr(username, 1, instr(username, ':') - 1) = auth_provider)
+                THEN substr(username, instr(username, ':') + 1) ELSE username END,
+            display_name,
+            CASE WHEN auth_provider = 'local' AND password_hash = 'external$disabled' AND instr(username, ':') > 0
+                THEN substr(username, 1, instr(username, ':') - 1) ELSE auth_provider END,
+            password_hash, must_change_password, 0, created_at, updated_at
+        FROM admin_users
+    """))
+    connection.execute(text("DROP TABLE admin_users"))
+    connection.execute(text("ALTER TABLE admin_users__migrated RENAME TO admin_users"))
+    connection.execute(text("CREATE INDEX ix_admin_users_username ON admin_users (username)"))
+    connection.execute(text("CREATE INDEX ix_admin_users_auth_provider ON admin_users (auth_provider)"))
+
+
+def drop_global_admin_username_constraint(connection, engine: Engine) -> None:
+    if engine.dialect.name != "postgresql":
+        return
+    inspector = inspect(engine)
+    quote = connection.dialect.identifier_preparer.quote
+    for constraint in inspector.get_unique_constraints("admin_users"):
+        if constraint.get("column_names") == ["username"]:
+            connection.execute(text(f"ALTER TABLE admin_users DROP CONSTRAINT {quote(constraint['name'])}"))
+
+
+def normalize_external_admin_usernames(connection, dialect_name: str) -> None:
+    if dialect_name == "sqlite":
+        username = "substr(username, instr(username, ':') + 1)"
+        provider = "substr(username, 1, instr(username, ':') - 1)"
+        has_prefix = "instr(username, ':') > 0"
+        prefix_matches_provider = "substr(username, 1, instr(username, ':') - 1) = auth_provider"
+    elif dialect_name == "postgresql":
+        username = "substring(username from position(':' in username) + 1)"
+        provider = "substring(username from 1 for position(':' in username) - 1)"
+        has_prefix = "position(':' in username) > 0"
+        prefix_matches_provider = "substring(username from 1 for position(':' in username) - 1) = auth_provider"
+    else:
+        return
+    connection.execute(text(
+        "UPDATE admin_users "
+        f"SET username = {username}, auth_provider = CASE WHEN auth_provider = 'local' THEN {provider} ELSE auth_provider END "
+        "WHERE password_hash = 'external$disabled' "
+        f"AND {has_prefix} AND (auth_provider = 'local' OR {prefix_matches_provider})"
+    ))
+
+
+def ensure_admin_user_provider_username_constraint(connection, engine: Engine) -> None:
+    if engine.dialect.name != "postgresql":
+        return
+    constraints = inspect(engine).get_unique_constraints("admin_users")
+    if not any(
+        constraint.get("column_names") == ["auth_provider", "username"]
+        for constraint in constraints
+    ):
+        connection.execute(text(
+            "ALTER TABLE admin_users ADD CONSTRAINT uq_admin_users_auth_provider_username "
+            "UNIQUE (auth_provider, username)"
+        ))
+
+
 def seed_settings(session: Session) -> None:
     defaults = {
         "gaard_intent_classification_mode": settings.gaard_intent_classification_mode,
@@ -278,6 +419,7 @@ def seed_overview_widgets(session: Session) -> None:
             "result_mode": "data",
             "position": 10,
             "grid_width": 1,
+            "grid_height": 2,
         },
         {
             "widget_key": "audit_retention",
@@ -296,6 +438,7 @@ def seed_overview_widgets(session: Session) -> None:
             "result_mode": "data",
             "position": 20,
             "grid_width": 1,
+            "grid_height": 2,
         },
         {
             "widget_key": "schema_cache_ttl",
@@ -314,6 +457,7 @@ def seed_overview_widgets(session: Session) -> None:
             "result_mode": "data",
             "position": 30,
             "grid_width": 1,
+            "grid_height": 2,
         },
         {
             "widget_key": "license_edition",
@@ -328,6 +472,7 @@ def seed_overview_widgets(session: Session) -> None:
             "result_mode": "data",
             "position": 40,
             "grid_width": 1,
+            "grid_height": 2,
         },
         {
             "widget_key": "runtime_daily_queries",
@@ -343,6 +488,7 @@ def seed_overview_widgets(session: Session) -> None:
             "result_mode": "data",
             "position": 250,
             "grid_width": 12,
+            "grid_height": 4,
             "active": False,
         },
         {
@@ -362,6 +508,7 @@ def seed_overview_widgets(session: Session) -> None:
             "result_mode": "data",
             "position": 130,
             "grid_width": 12,
+            "grid_height": 4,
         },
     ]
 
@@ -516,6 +663,18 @@ def ensure_overview_widget_schema(engine: Engine) -> None:
                 text("ALTER TABLE overview_widgets ADD COLUMN grid_width INTEGER DEFAULT 1")
             )
 
+    if "grid_height" not in columns:
+        with engine.begin() as connection:
+            connection.execute(
+                text("ALTER TABLE overview_widgets ADD COLUMN grid_height INTEGER DEFAULT 2")
+            )
+            connection.execute(
+                text(
+                    "UPDATE overview_widgets SET grid_height = 4 "
+                    "WHERE widget_type <> 'scalar'"
+                )
+            )
+
     if "result_mode" not in columns:
         with engine.begin() as connection:
             connection.execute(
@@ -525,6 +684,33 @@ def ensure_overview_widget_schema(engine: Engine) -> None:
                 )
             )
 
+def backfill_overview_widget_tags(session: Session) -> None:
+    """Give legacy widgets public and saved-metric owner tags."""
+    if session.scalar(select(WidgetTag).where(WidgetTag.name == "public")) is None:
+        session.add(WidgetTag(name="public"))
+        session.flush()
+    widget_ids_with_tags = set(session.scalars(select(OverviewWidgetTag.widget_id)))
+    for widget_id in session.scalars(select(OverviewWidget.id)):
+        if widget_id not in widget_ids_with_tags:
+            session.add(OverviewWidgetTag(widget_id=widget_id, tag_name="public"))
+
+    existing_assignments = set(
+        session.execute(select(OverviewWidgetTag.widget_id, OverviewWidgetTag.tag_name))
+    )
+    for widget_id, owner_username in session.execute(
+        select(OverviewWidget.id, UserSavedMetric.owner_username).join(
+            UserSavedMetric,
+            UserSavedMetric.widget_key == OverviewWidget.widget_key,
+        )
+    ):
+        if not owner_username:
+            continue
+        if session.get(WidgetTag, owner_username) is None:
+            session.add(WidgetTag(name=owner_username))
+            session.flush()
+        if (widget_id, owner_username) not in existing_assignments:
+            session.add(OverviewWidgetTag(widget_id=widget_id, tag_name=owner_username))
+
 
 def reset_metadata_store_for_tests() -> None:
     global _engine, _engine_url, _session_factory

{gaard_api-0.2.7 → gaard_api-0.2.8}/src/gaard_api/admin/defaults.py

@@ -218,6 +218,40 @@ Return exactly one of:
 personal_data, sensitive_data, technical_data, neutral_data, unknown
 """
 
+DEFAULT_ANSWER_EXPLANATION_SYSTEM_PROMPT = """You are GAARD Answer Explanation.
+
+Your task is to explain why a specific SQL query was generated for the user's data question.
+
+Use the provided:
+- original user question,
+- generated SQL,
+- interpreted answer and raw result rows,
+- inference metadata,
+- prompt metadata,
+- approved business logic and schema/rule context.
+
+Rules:
+1. Answer in the same language as the user's question.
+2. Explain the logical mapping from the question to the SQL.
+3. Mention the selected tables, columns, joins, filters, time ranges, grouping,
+   aggregation, ordering and limits when they are relevant.
+4. If business logic affected the SQL, describe that rule in plain language.
+5. Distinguish explicit evidence from assumptions.
+6. Do not invent tables, columns, rules, filters or results that are not present in the input.
+7. Do not reveal hidden chain-of-thought.
+8. Do not include <think> blocks.
+9. Do not use markdown tables.
+10. Return only the final explanation.
+"""
+
+DEFAULT_ANSWER_EXPLANATION_USER_PROMPT = """Explain why this SQL was generated for the user's question.
+
+Input JSON:
+{payload}
+
+Return only the final explanation.
+"""
+
 DEFAULT_GOVERNANCE_POLICY_CONFIG = {
     "final_answer": {
         "record_level_pii_allowed": False,
@@ -280,4 +314,11 @@ DEFAULT_PROMPTS = [
         "system_prompt": DEFAULT_RESULT_CLASSIFICATION_SYSTEM_PROMPT,
         "user_prompt_template": DEFAULT_RESULT_CLASSIFICATION_USER_PROMPT,
     },
+    {
+        "prompt_key": "answer_explanation",
+        "name": "Answer explanation",
+        "description": "Explains why a generated SQL query answered a user question.",
+        "system_prompt": DEFAULT_ANSWER_EXPLANATION_SYSTEM_PROMPT,
+        "user_prompt_template": DEFAULT_ANSWER_EXPLANATION_USER_PROMPT,
+    },
 ]

{gaard_api-0.2.7 → gaard_api-0.2.8}/src/gaard_api/admin/models.py

@@ -6,6 +6,7 @@ from sqlalchemy import (
     DateTime,
     Enum as SAEnum,
     Float,
+    ForeignKey,
     Integer,
     String,
     Text,
@@ -26,11 +27,19 @@ class Base(DeclarativeBase):
 
 class AdminUser(Base):
     __tablename__ = "admin_users"
+    __table_args__ = (
+        UniqueConstraint("auth_provider", "username", name="uq_admin_users_auth_provider_username"),
+    )
 
     id: Mapped[int] = mapped_column(Integer, primary_key=True)
-    username: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    username: Mapped[str] = mapped_column(String(255), index=True)
+    display_name: Mapped[str] = mapped_column(String(255), default="")
+    auth_provider: Mapped[str] = mapped_column(String(255), index=True, default="local")
     password_hash: Mapped[str] = mapped_column(Text)
     must_change_password: Mapped[bool] = mapped_column(Boolean, default=True)
+    # Provider refreshes create provisional records so they can be assigned before login.
+    # The provider may safely remove only records which remain provisional.
+    is_provisioned: Mapped[bool] = mapped_column(Boolean, default=False)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
     updated_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True),
@@ -180,6 +189,22 @@ class DashboardUserState(Base):
     )
 
 
+class UserDatasourceSelection(Base):
+    """Client datasource selections, scoped to one authenticated user."""
+
+    __tablename__ = "user_datasource_selections"
+
+    owner_user_id: Mapped[str] = mapped_column(String(255), primary_key=True)
+    owner_username: Mapped[str] = mapped_column(String(255), index=True, default="")
+    datasource_ids_json: Mapped[str] = mapped_column(Text, default="[]")
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=utc_now,
+        onupdate=utc_now,
+    )
+
+
 class UserSavedMetric(Base):
     __tablename__ = "user_saved_metrics"
     __table_args__ = (
@@ -303,6 +328,7 @@ class OverviewWidget(Base):
     result_mode: Mapped[str] = mapped_column(String(50), default="data")
     position: Mapped[int] = mapped_column(Integer, default=100)
     grid_width: Mapped[int] = mapped_column(Integer, default=1)
+    grid_height: Mapped[int] = mapped_column(Integer, default=2)
     active: Mapped[bool] = mapped_column(Boolean, default=True)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
     updated_at: Mapped[datetime] = mapped_column(
@@ -313,6 +339,26 @@ class OverviewWidget(Base):
     updated_by: Mapped[str] = mapped_column(String(255), default="system")
 
 
+class WidgetTag(Base):
+    """Permanent catalogue of every tag that has been used on a widget."""
+
+    __tablename__ = "widget_tags"
+
+    name: Mapped[str] = mapped_column(String(255), primary_key=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+
+
+class OverviewWidgetTag(Base):
+    __tablename__ = "overview_widget_tags"
+
+    widget_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("overview_widgets.id", ondelete="CASCADE"), primary_key=True
+    )
+    tag_name: Mapped[str] = mapped_column(
+        String(255), ForeignKey("widget_tags.name"), primary_key=True
+    )
+
+
 class BusinessLogicSuggestion(Base):
     __tablename__ = "business_logic_suggestions"
 

{gaard_api-0.2.7 → gaard_api-0.2.8}/src/gaard_api/admin/prompt_runtime.py

@@ -212,6 +212,44 @@ class MetadataResultClassificationPromptCompiler:
         )
 
 
+class MetadataAnswerExplanationPromptCompiler:
+    def __init__(self, prompt_template: PromptTemplate) -> None:
+        self.prompt_template = prompt_template
+
+    def compile(self, payload: dict[str, Any]) -> CompiledPrompt:
+        payload_json = json_dumps(payload, ensure_ascii=False, indent=2)
+        metadata = payload.get("metadata")
+        inference_metadata = payload.get("inference_metadata")
+        prompt_metadata = payload.get("prompt_metadata")
+
+        return CompiledPrompt(
+            system_prompt=self.prompt_template.system_prompt,
+            user_prompt=self.prompt_template.user_prompt_template.format(
+                payload=payload_json,
+                question=str(payload.get("question") or ""),
+                sql=str(payload.get("sql") or ""),
+                answer=str(payload.get("answer") or ""),
+                metadata=json_dumps(metadata, ensure_ascii=False),
+                inference_metadata=json_dumps(inference_metadata, ensure_ascii=False),
+                prompt_metadata=json_dumps(prompt_metadata, ensure_ascii=False),
+                business_logic=str(payload.get("business_logic") or ""),
+            ),
+            metadata={
+                "prompt_key": self.prompt_template.prompt_key,
+                "prompt_version": self.prompt_template.version,
+                "has_sql": bool(str(payload.get("sql") or "").strip()),
+                "has_result_rows": bool(
+                    (payload.get("result") or {}).get("rows")
+                    if isinstance(payload.get("result"), dict)
+                    else False
+                ),
+                "has_business_logic": bool(
+                    str(payload.get("business_logic") or "").strip()
+                ),
+            },
+        )
+
+
 def get_sql_generation_prompt_compiler() -> MetadataSqlGenerationPromptCompiler | None:
     prompt_template = get_active_prompt_template_safe("sql_generation")
 
@@ -263,3 +301,14 @@ def get_result_classification_prompt_compiler() -> (
         return None
 
     return MetadataResultClassificationPromptCompiler(prompt_template=prompt_template)
+
+
+def get_answer_explanation_prompt_compiler() -> (
+    MetadataAnswerExplanationPromptCompiler | None
+):
+    prompt_template = get_active_prompt_template_safe("answer_explanation")
+
+    if prompt_template is None:
+        return None
+
+    return MetadataAnswerExplanationPromptCompiler(prompt_template=prompt_template)

{gaard_api-0.2.7 → gaard_api-0.2.8}/src/gaard_api/admin/services.py

@@ -2367,6 +2367,7 @@ def get_datasource_schema_contexts_safe(
                 for datasource_id in datasource_ids
                 if (connector := get_datasource_connector_by_key(session, datasource_id))
                 is not None
+                and connector.active
                 and not is_system_datasource_connector(connector)
             ]
         else:

gaard_api-0.2.8/src/gaard_api/admin-web/assets/identity.js

@@ -0,0 +1,109 @@
+export function createIdentityModule({ api, escapeHtml, state, render, setMessage }) {
+  let selected = null;
+  let paneWidth = 420;
+  let loaded = false;
+  let editAction = null;
+  let refreshOnAttach = false;
+  let pageResizeObserver = null;
+
+  function providerSpecific(user) {
+    const entries = Object.entries(user.attributes || {});
+    if (!entries.length) return "";
+    return `<h3>Provider specific</h3><table class="identity-provider-table"><tbody>${entries.map(([key, value]) => `<tr><th>${escapeHtml(key)}</th><td>${escapeHtml(Array.isArray(value) ? value.join(", ") : value)}</td></tr>`).join("")}</tbody></table>`;
+  }
+
+  function actionButton(action, label, enabled) {
+    return `<button type="button" data-identity-action="${action}" ${enabled ? "" : "disabled"}>${label}</button>`;
+  }
+
+  function userDashboards(user) {
+    const dashboards = user.dashboards || [];
+    if (!dashboards.length) return `<h3>Dashboards</h3><p class="identity-empty">No dashboards created.</p>`;
+    return `<h3>Dashboards</h3><table class="identity-provider-table"><thead><tr><th>Name</th><th>Last updated</th></tr></thead><tbody>${dashboards.map((dashboard) => `<tr><td><strong>${escapeHtml(dashboard.name || "Untitled dashboard")}</strong>${dashboard.description ? `<br><span class="identity-dashboard-description">${escapeHtml(dashboard.description)}</span>` : ""}</td><td>${escapeHtml(dashboard.updated_at || "-")}</td></tr>`).join("")}</tbody></table>`;
+  }
+
+  function renderPane(user) {
+    const editable = Boolean(user.editable_name || user.editable_password);
+    return `<aside class="identity-pane" style="width:${paneWidth}px">
+      <div class="identity-resizer" id="identity-resizer" title="Drag to resize"></div>
+      <header><div><h2>${escapeHtml(user.name || user.username)}</h2><p>${escapeHtml(user.provider)}</p></div><button id="identity-close" type="button" aria-label="Close">×</button></header>
+      <div class="identity-pane-content">
+        <dl class="identity-basics"><dt>Name</dt><dd>${escapeHtml(user.name || user.username)}</dd><dt>Username</dt><dd>${escapeHtml(user.username)}${user.overshadowed ? ` <span class="identity-warning" title="Overshadowed by ${escapeHtml(user.overshadowed_by?.username || "another user")} from ${escapeHtml(user.overshadowed_by?.provider || "another provider")}">⚠️</span>` : ""}</dd></dl>
+        <div class="identity-actions">${actionButton("username", "Change username", editable)}${actionButton("password", "Change password", Boolean(user.editable_password))}</div>
+        ${userDashboards(user)}
+        ${providerSpecific(user)}
+      </div>
+    </aside>`;
+  }
+
+  function renderEditModal() {
+    if (!editAction || !selected) return "";
+    const isPassword = editAction === "password";
+    const label = isPassword ? "New password" : "New username";
+    const value = isPassword ? "" : escapeHtml(selected.username);
+    return `<div class="modal-backdrop" data-identity-modal-backdrop><section class="modal-panel modal-panel-small" role="dialog" aria-modal="true" aria-labelledby="identity-modal-title"><div class="modal-header"><div><h2 id="identity-modal-title">${isPassword ? "Change password" : "Change username"}</h2><p>${escapeHtml(selected.name || selected.username)}</p></div></div><form id="identity-edit-modal-form" class="form-grid"><label>${label}<input name="value" ${isPassword ? "type=\"password\" minlength=\"8\" autocomplete=\"new-password\"" : "autocomplete=\"username\""} value="${value}" required /></label><div class="form-actions"><button type="button" data-identity-modal-cancel>Cancel</button><button class="primary" type="submit">Apply now</button></div></form></section></div>`;
+  }
+
+  function renderIdentity() {
+    const rows = (state.identities || []).map((user) => `<tr class="identity-table-row${selected?.id === user.id ? " selected" : ""}" data-identity-id="${escapeHtml(user.id)}"><td>${escapeHtml(user.name || user.username)}</td><td>${escapeHtml(user.username)}${user.overshadowed ? ` <span class="identity-warning" title="Overshadowed by ${escapeHtml(user.overshadowed_by?.username || "another user")} from ${escapeHtml(user.overshadowed_by?.provider || "another provider")}">⚠️</span>` : ""}</td><td>${escapeHtml(user.role)}</td><td>${escapeHtml(user.provider)}</td></tr>`).join("");
+    return `<section class="panel identities-page"><div class="panel-header"><h2>Identities</h2><button id="identity-refresh" type="button">Refresh</button></div><div class="table-wrap"><table><thead><tr><th>Name</th><th>Username</th><th>Role</th><th>Provider</th></tr></thead><tbody>${rows || `<tr><td colspan="4">No users found.</td></tr>`}</tbody></table></div>${selected ? renderPane(selected) : ""}</section>${renderEditModal()}`;
+  }
+
+  function clampPaneWidth() {
+    const page = document.querySelector(".identities-page");
+    const pane = document.querySelector(".identity-pane");
+    if (!page || !pane) return;
+    const maximum = Math.max(320, Math.floor(page.getBoundingClientRect().width));
+    paneWidth = Math.min(paneWidth, maximum);
+    pane.style.width = `${paneWidth}px`;
+  }
+
+  function observePageWidth() {
+    const page = document.querySelector(".identities-page");
+    if (!page || !window.ResizeObserver) return;
+    pageResizeObserver?.disconnect();
+    pageResizeObserver = new ResizeObserver(clampPaneWidth);
+    pageResizeObserver.observe(page);
+  }
+
+  async function load(refresh = false, refreshAfterLoad = false) {
+    try {
+      state.identities = (await api(`/api/v1/admin/identities${refresh ? "?refresh=true" : ""}`)).items || [];
+      if (selected) selected = state.identities.find((item) => item.id === selected.id) || null;
+      loaded = true;
+      render();
+      if (refreshAfterLoad) void load(true);
+    } catch (error) { setMessage("error", error.message); }
+  }
+
+  function attachResize() {
+    clampPaneWidth(); observePageWidth();
+    document.querySelector("#identity-resizer")?.addEventListener("pointerdown", (event) => {
+      event.preventDefault(); const startX = event.clientX; const startWidth = paneWidth;
+      const move = (moveEvent) => { const page = document.querySelector(".identities-page"); const maximum = Math.max(320, Math.floor(page?.getBoundingClientRect().width || 320)); paneWidth = Math.min(maximum, Math.max(320, startWidth + startX - moveEvent.clientX)); clampPaneWidth(); };
+      const stop = () => { window.removeEventListener("pointermove", move); };
+      window.addEventListener("pointermove", move); window.addEventListener("pointerup", stop, { once: true });
+    });
+  }
+
+  function attachModal() {
+    document.querySelector("[data-identity-modal-cancel]")?.addEventListener("click", () => { editAction = null; render(); });
+    document.querySelector("[data-identity-modal-backdrop]")?.addEventListener("click", (event) => { if (event.target === event.currentTarget) { editAction = null; render(); } });
+    document.querySelector("#identity-edit-modal-form")?.addEventListener("submit", async (event) => { event.preventDefault(); const value = String(new FormData(event.currentTarget).get("value") || ""); const body = editAction === "password" ? { new_password: value } : { username: value }; try { await api(`/api/v1/admin/identities/${encodeURIComponent(selected.id)}`, { method: "PATCH", body: JSON.stringify(body) }); editAction = null; setMessage("success", "Identity updated. The affected user has been signed out."); await load(); } catch (error) { setMessage("error", error.message); } });
+  }
+
+  function attach() {
+    document.querySelector("#identity-refresh")?.addEventListener("click", () => void load(true));
+    document.querySelectorAll("[data-identity-id]").forEach((row) => row.addEventListener("click", () => { selected = state.identities.find((item) => item.id === row.dataset.identityId) || null; render(); }));
+    document.querySelector("#identity-close")?.addEventListener("click", () => { selected = null; render(); });
+    document.querySelectorAll("[data-identity-action]").forEach((button) => button.addEventListener("click", () => { editAction = button.dataset.identityAction; render(); }));
+    attachResize(); attachModal();
+    if (!loaded || refreshOnAttach) {
+      const loadFromCacheFirst = (state.identities || []).length === 0;
+      refreshOnAttach = false;
+      void load(!loadFromCacheFirst, loadFromCacheFirst);
+    }
+  }
+  function activate() { refreshOnAttach = true; }
+  return { render: renderIdentity, attach, activate };
+}