Merge branch 'feat/user-display-persistent-cache' into 'main'

feat(user-display): persistent DB cache + Keycloak Admin lookup (Phase 1+2) See merge request 2-6/2-6-4/terravault/ordinis!180
2026-05-14 11:52:20 +00:00
parent b5920e4d5f 83caf9c3c8
commit a73549d38d
12 changed files with 707 additions and 47 deletions
@@ -0,0 +1,136 @@
+# Keycloak Admin client setup for UserDisplayService Phase 2
+
+`KeycloakAdminUserResolver` resolves a JWT `sub` against the Keycloak Admin
+REST API on cache miss, so users that never hit ordinis still get a
+display name in audit / reviews / changelog / events / history. Without
+this, only users who personally made an authenticated request show up
+with a real name (the "ток мой UUID отображается" pain).
+
+This is a per-environment one-time setup. Disabled by default — flip on
+once the Keycloak client + vault secret exist.
+
+## Step 1: Create service-account client in Keycloak
+
+Realm: `nstart`. Path: Clients → Create client.
+
+| Field | Value |
+|---|---|
+| Client type | OpenID Connect |
+| Client ID | `ordinis-admin-client` |
+| Client authentication | **On** (confidential) |
+| Authorization | Off |
+| Standard flow | Off |
+| Direct access grants | Off |
+| Service accounts roles | **On** |
+
+Save. On the created client → **Service accounts roles** tab → **Assign
+role** → Filter by clients → `realm-management` → check **`view-users`**
+→ Assign.
+
+(`view-users` is the minimum scope needed for `GET /admin/realms/{realm}/users/{id}`.
+Don't assign `manage-users` — read-only is enough.)
+
+Then **Credentials** tab → copy the `Client secret` (long random string).
+
+## Step 2: Store secret in Vault
+
+The cluster-domain matters here — staging is `265.local`, prod is
+`altum.local`. Both have separate Vault instances.
+
+Staging (cluster.265, namespace `config`):
+```bash
+kubectl -n config exec -it vault-0 -- sh -c '
+  vault login <root-or-admin-token>
+  vault kv put secret/ordinis/cuod/keycloak-admin \
+    client_id=ordinis-admin-client \
+    client_secret=<paste-from-keycloak>
+'
+```
+
+Prod (altum, namespace `vault`):
+```bash
+ssh root@192.168.100.142 'kubectl -n vault exec -it vault-0 -- sh -c "
+  vault login <prod-root-token>
+  vault kv put secret/ordinis/cuod/keycloak-admin \
+    client_id=ordinis-admin-client \
+    client_secret=<paste-from-keycloak>
+"'
+```
+
+⚠️ Different secret per environment — staging and prod have separate
+Keycloak clients (and certainly separate secrets).
+
+## Step 3: Wire into ordinis-app deployment
+
+Add to `ordinis-app` helm chart annotations (vault agent injector
+template) — same pattern as `secret-postgres` / `secret-kafka` already
+present in the chart:
+
+```yaml
+vault.hashicorp.com/agent-inject-secret-keycloak-admin: secret/data/ordinis/cuod/keycloak-admin
+vault.hashicorp.com/agent-inject-template-keycloak-admin: |
+  {{- with secret "secret/data/ordinis/cuod/keycloak-admin" -}}
+  export ORDINIS_KEYCLOAK_ADMIN_CLIENT_ID="{{ .Data.data.client_id }}"
+  export ORDINIS_KEYCLOAK_ADMIN_CLIENT_SECRET="{{ .Data.data.client_secret }}"
+  {{- end }}
+```
+
+Add env vars to the deployment:
+
+```yaml
+env:
+  - name: ORDINIS_KEYCLOAK_ADMIN_ENABLED
+    value: "true"
+  - name: ORDINIS_KEYCLOAK_ADMIN_URL
+    value: "https://auth.nstart.space"   # both envs use the same Keycloak
+  - name: ORDINIS_KEYCLOAK_ADMIN_REALM
+    value: "nstart"
+  # CLIENT_ID + CLIENT_SECRET arrive via the vault-injected
+  # /vault/secrets/keycloak-admin file sourced before java starts.
+```
+
+## Step 4: Verify
+
+After redeploy, check the pod log on startup:
+
+```
+KeycloakAdminUserResolver active — base=https://auth.nstart.space realm=nstart client=ordinis-admin-client
+```
+
+End-to-end:
+
+```bash
+# Find a sub that's NOT in the JVM cache (e.g. a user who never logged in).
+# Hit the display endpoint as an admin user:
+curl -s -H "Authorization: Bearer $TOKEN" \
+  https://ordinis.k8s.265.nstart.cloud/api/v1/admin/users/<uuid>/display | jq
+# Expect 200 with username/name/email even on cold cache, instead of 404.
+```
+
+Then check the DB — the row was persisted from the on-demand resolve:
+
+```sql
+SELECT sub, preferred_username, source, synced_at
+  FROM user_display_cache
+ WHERE sub = '<uuid>';
+-- source = KEYCLOAK_ON_DEMAND
+```
+
+## Step 5: Phase 3 (later — scheduled bulk sync)
+
+When ready to refill the table proactively (avoids the per-user
+on-demand latency for fresh subs), add a Spring `@Scheduled` task that
+calls `GET /admin/realms/{realm}/users` paginated and writes via
+`UserDisplayService.upsertFromKeycloak`. Recommended every 6h. Not
+included in this MR — depends on observed cache miss rate.
+
+## Failure modes
+
+- **Service-account client missing `view-users`** → 403 on lookup,
+  resolver throws RuntimeException, UserDisplayService logs warn,
+  caller falls back to short UUID. No outage, just no resolve.
+- **Keycloak unreachable** → connect timeout / 502. Same fallback as
+  above. Cached entries (DB tier) keep working.
+- **client_secret rotated in Keycloak but vault not updated** → 401 on
+  token request → resolver wipes cached token and surfaces
+  RuntimeException. Update vault secret and the next attempt succeeds.
@@ -1,6 +1,7 @@
 import { useTranslation } from 'react-i18next'
 import { Badge, LoadingBlock, Modal, QueryErrorState } from '@/ui'
 import { useChangelogDiff } from '@/api/queries'
+import { UserCell } from '@/lib/useUserDisplay'
 import { kindBadgeVariant, kindLabel } from './kind-meta'

 /**
@@ -52,9 +53,9 @@ export function ChangelogDiffModal({
          {/* Header strip — kind + author */}
          <div className="flex flex-wrap items-center gap-2">
            <Badge variant={kindBadgeVariant(data.kind)}>{kindLabel(data.kind, t)}</Badge>
-            <span className="text-cell text-mute">
+            <span className="text-cell text-mute inline-flex items-center gap-1">
              {t('changelog.diff.by', { defaultValue: 'автор' })}:{' '}
-              <span className="text-ink font-mono">{data.publishedBy.name}</span>
+              <UserCell uuid={data.publishedBy.sub} />
            </span>
          </div>

@@ -6,6 +6,7 @@ import type { ChangelogEntry, DictionaryDetail, FlattenedRecord } from '@/api/cl
 import { useChangelog, useChangelogDiff, useRecords } from '@/api/queries'
 import { kindBadgeVariant, kindIcon, kindLabel } from '@/components/changelog/kind-meta'
 import { ChangelogDiffModal } from '@/components/changelog/ChangelogDiffModal'
+import { UserCell } from '@/lib/useUserDisplay'
 import { cn } from '@/lib/utils'

 /**
@@ -411,7 +412,9 @@ function ComparePanel({
            · <span className="text-mono">{note}</span>
          </span>
        )}
-        {author && <span className="text-mute">· {author}</span>}
+        {author && (
+          <span className="text-mute inline-flex items-center gap-1">· <UserCell uuid={author} /></span>
+        )}
      </div>
    </div>
  )
@@ -683,7 +686,7 @@ function ChangesTabContent({
                <span className="tabular-nums">
                  {new Date(e.publishedAt).toLocaleString()}
                </span>
-                <span className="font-mono">{e.publishedBy.name}</span>
+                <UserCell uuid={e.publishedBy.sub} />
                <button
                  type="button"
                  onClick={() => onOpenDiff(e.id)}
@@ -895,7 +898,7 @@ function SchemaTabContent({
              <dt className="text-cap text-mute uppercase tracking-wider">
                {t('timeTravel.schema.author', { defaultValue: 'автор' })}
              </dt>
-              <dd className="font-mono">{pickedEntry.publishedBy.name}</dd>
+              <dd><UserCell uuid={pickedEntry.publishedBy.sub} /></dd>
              <dt className="text-cap text-mute uppercase tracking-wider">
                {t('timeTravel.schema.date', { defaultValue: 'дата' })}
              </dt>
@@ -56,6 +56,7 @@ import { TimeTravelModal } from '@/components/timetravel/TimeTravelModal'
 import { ChangelogDiffModal } from '@/components/changelog/ChangelogDiffModal'
 import { kindBadgeVariant, kindIcon, kindLabel, isVersioningKind } from '@/components/changelog/kind-meta'
 import { CreateSchemaDraftModal } from '@/components/workflow/CreateSchemaDraftModal'
+import { UserCell } from '@/lib/useUserDisplay'
 import { nowIsoLocal } from '@/lib/dates'
 import { recordDisplayName } from '@/lib/locales'
 import { SCOPE_BORDER_TOP } from '@/lib/scope-style'
@@ -2258,8 +2259,8 @@ function EventsTabContent({ dictName }: { dictName: string }) {
                      {status}
                    </span>
                  </td>
-                  <td className="px-3 py-2 text-mono text-cell text-ink-2">
-                    {r.userId ?? 'anonymous'}
+                  <td className="px-3 py-2 text-cell text-ink-2">
+                    {r.userId ? <UserCell uuid={r.userId} /> : <span className="text-mono text-mute">anonymous</span>}
                  </td>
                  <td className="px-3 py-2 text-cell text-ink-2 max-w-md truncate">
                    {r.businessKey ? (
@@ -2396,7 +2397,7 @@ function ChangelogTimelineItem({
            )}
            <div className="flex items-center gap-3 mt-1 text-cell text-mute">
              <span className="tabular-nums">{occurredAt.toLocaleString()}</span>
-              <span className="font-mono">{entry.publishedBy.name}</span>
+              <UserCell uuid={entry.publishedBy.sub} />
              {entry.recordsAffected > 0 && (
                <span>
                  {t('changelog.recordsAffected', {
@@ -211,3 +211,16 @@ ordinis:
    issuer: ${jwt-issuer:}
    require-authentication: ${ORDINIS_AUTH_REQUIRED:false}
    allow-query-scope: ${ORDINIS_AUTH_ALLOW_QUERY_SCOPE:true}
+
+  # Keycloak Admin REST integration for UserDisplayService Phase 2 — on-demand
+  # sub→user lookup when JWT capture cache + DB cache both miss. See
+  # KeycloakAdminUserResolver.java + 0023-user-display-cache.xml migration.
+  # Disabled by default; flip on per-environment when the service-account
+  # client + vault secret are provisioned.
+  keycloak:
+    admin:
+      enabled: ${ORDINIS_KEYCLOAK_ADMIN_ENABLED:false}
+      url: ${ORDINIS_KEYCLOAK_ADMIN_URL:}
+      realm: ${ORDINIS_KEYCLOAK_ADMIN_REALM:nstart}
+      client-id: ${ORDINIS_KEYCLOAK_ADMIN_CLIENT_ID:}
+      client-secret: ${ORDINIS_KEYCLOAK_ADMIN_CLIENT_SECRET:}
@@ -0,0 +1,124 @@
+package cloud.nstart.terravault.ordinis.domain.userdisplay;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+import org.hibernate.annotations.UpdateTimestamp;
+
+import java.time.OffsetDateTime;
+
+/**
+ * Persistent cache entry for JWT sub → display info resolve. See
+ * migration 0023-user-display-cache.xml for the table contract and
+ * the multi-tier resolve strategy.
+ *
+ * <p>Source semantics:
+ * <ul>
+ *   <li>{@link Source#JWT_CAPTURE} — written by JwtUserCaptureFilter
+ *       on every authenticated request. Highest accuracy (claims as
+ *       the user actually saw them).</li>
+ *   <li>{@link Source#KEYCLOAK_SYNC} — written by the periodic
+ *       Phase 3 scheduled bulk sync from Keycloak Admin API.</li>
+ *   <li>{@link Source#KEYCLOAK_ON_DEMAND} — written when a cache miss
+ *       triggers a one-shot Keycloak Admin lookup. Phase 2.</li>
+ * </ul>
+ */
+@Entity
+@Table(name = "user_display_cache")
+public class UserDisplayCacheEntry {
+
+  @Id
+  @Column(name = "sub", nullable = false, length = 64)
+  private String sub;
+
+  @Column(name = "preferred_username", length = 255)
+  private String preferredUsername;
+
+  @Column(name = "name", length = 255)
+  private String name;
+
+  @Column(name = "email", length = 320)
+  private String email;
+
+  @Enumerated(EnumType.STRING)
+  @Column(name = "source", nullable = false, length = 32)
+  private Source source = Source.JWT_CAPTURE;
+
+  @Column(name = "synced_at", nullable = false)
+  private OffsetDateTime syncedAt;
+
+  @UpdateTimestamp
+  @Column(name = "updated_at", nullable = false)
+  private OffsetDateTime updatedAt;
+
+  protected UserDisplayCacheEntry() {
+    // JPA
+  }
+
+  public UserDisplayCacheEntry(String sub, String preferredUsername, String name,
+                               String email, Source source, OffsetDateTime syncedAt) {
+    this.sub = sub;
+    this.preferredUsername = preferredUsername;
+    this.name = name;
+    this.email = email;
+    this.source = source;
+    this.syncedAt = syncedAt;
+  }
+
+  public String getSub() {
+    return sub;
+  }
+
+  public String getPreferredUsername() {
+    return preferredUsername;
+  }
+
+  public String getName() {
+    return name;
+  }
+
+  public String getEmail() {
+    return email;
+  }
+
+  public Source getSource() {
+    return source;
+  }
+
+  public OffsetDateTime getSyncedAt() {
+    return syncedAt;
+  }
+
+  public OffsetDateTime getUpdatedAt() {
+    return updatedAt;
+  }
+
+  /**
+   * Idempotent merge from a fresh capture / sync. Updates fields that
+   * have a new non-null value; leaves existing data otherwise (e.g.
+   * Keycloak sync may have richer email than JWT capture, don't blank).
+   */
+  public void mergeFrom(String preferredUsername, String name, String email,
+                        Source source, OffsetDateTime syncedAt) {
+    if (preferredUsername != null && !preferredUsername.isBlank()) {
+      this.preferredUsername = preferredUsername;
+    }
+    if (name != null && !name.isBlank()) {
+      this.name = name;
+    }
+    if (email != null && !email.isBlank()) {
+      this.email = email;
+    }
+    this.source = source;
+    this.syncedAt = syncedAt;
+  }
+
+  public enum Source {
+    JWT_CAPTURE,
+    KEYCLOAK_SYNC,
+    KEYCLOAK_ON_DEMAND
+  }
+}
@@ -0,0 +1,9 @@
+package cloud.nstart.terravault.ordinis.domain.userdisplay;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+
+public interface UserDisplayCacheRepository extends JpaRepository<UserDisplayCacheEntry, String> {
+  // PK is sub (String). Built-in findById(sub), save, etc. covers Phase 1+2.
+  // Phase 3 (scheduled bulk sync) will add `findAllBySyncedAtBefore(...)`
+  // and `findAllByOrderBySyncedAtAsc(Pageable)` for stale-first refresh.
+}
@@ -0,0 +1,81 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<databaseChangeLog
+  xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
+                      http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.27.xsd">
+
+  <!--
+    User display cache (sub → username/email/name) — persistent backing store
+    for UserDisplayService.
+
+    Цель: остановить bleeding "ток мой UUID отображается" в audit/reviews/
+    history/changelog. Раньше UserDisplayService держал данные in-memory →
+    pod restart терял всё → users которые редко логинились показывались
+    как UUID.
+
+    Three-tier resolve chain (после wire-up в UserDisplayService):
+      1. JVM ConcurrentHashMap (hot cache, ~µs)
+      2. user_display_cache table (этот migration, ~ms)
+      3. Keycloak Admin API on-demand (~10-50ms, only if not in DB)
+         + nightly scheduled bulk sync to refill (Phase 3).
+
+    Decisions:
+    - PK = sub (UUID-like Keycloak user id). Match'ит JWT sub claim
+      directly — нет surrogate id.
+    - source ENUM текстом ('JWT_CAPTURE' | 'KEYCLOAK_SYNC' |
+      'KEYCLOAK_ON_DEMAND') — Hibernate @Enumerated(STRING) уrok из 0020.
+    - synced_at = когда последний раз обновили из источника. updated_at =
+      row mtime (Hibernate @UpdateTimestamp). Разные потому что
+      KEYCLOAK_SYNC bulk job обновляет каждые 6h даже если данные не
+      изменились.
+    - Soft cap on rows не нужен — Keycloak realm пока ~50 users, table
+      будет ≤ 1k entries обозримо.
+  -->
+
+  <changeSet id="0023-1-user-display-cache" author="ordinis">
+    <comment>user_display_cache — persistent sub → display info, three-tier resolve</comment>
+    <createTable tableName="user_display_cache">
+      <column name="sub" type="VARCHAR(64)">
+        <constraints primaryKey="true" nullable="false"/>
+      </column>
+      <column name="preferred_username" type="VARCHAR(255)">
+        <constraints nullable="true"/>
+      </column>
+      <column name="name" type="VARCHAR(255)">
+        <constraints nullable="true"/>
+      </column>
+      <column name="email" type="VARCHAR(320)"><!-- RFC 5321 max -->
+        <constraints nullable="true"/>
+      </column>
+      <column name="source" type="VARCHAR(32)" defaultValue="JWT_CAPTURE">
+        <constraints nullable="false"/>
+      </column>
+      <column name="synced_at" type="TIMESTAMP WITH TIME ZONE" defaultValueComputed="NOW()">
+        <constraints nullable="false"/>
+      </column>
+      <column name="updated_at" type="TIMESTAMP WITH TIME ZONE" defaultValueComputed="NOW()">
+        <constraints nullable="false"/>
+      </column>
+    </createTable>
+  </changeSet>
+
+  <changeSet id="0023-2-user-display-cache-source-check" author="ordinis">
+    <comment>Enforce source enum values inline в DB чтобы insert с typo шумел</comment>
+    <sql>
+      ALTER TABLE user_display_cache
+        ADD CONSTRAINT user_display_cache_source_check
+        CHECK (source IN ('JWT_CAPTURE', 'KEYCLOAK_SYNC', 'KEYCLOAK_ON_DEMAND'));
+    </sql>
+    <rollback>
+      ALTER TABLE user_display_cache DROP CONSTRAINT user_display_cache_source_check;
+    </rollback>
+  </changeSet>
+
+  <changeSet id="0023-3-user-display-cache-synced-index" author="ordinis">
+    <comment>Index for Phase 3 nightly sync — pull stale entries by synced_at</comment>
+    <createIndex tableName="user_display_cache" indexName="idx_user_display_synced_at">
+      <column name="synced_at"/>
+    </createIndex>
+  </changeSet>
+</databaseChangeLog>
@@ -32,5 +32,6 @@
  <include file="changes/0020-fix-draft-status-case.xml" relativeToChangelogFile="true"/>
  <include file="changes/0021-notifications.xml" relativeToChangelogFile="true"/>
  <include file="changes/0022-schema-workflow.xml" relativeToChangelogFile="true"/>
+  <include file="changes/0023-user-display-cache.xml" relativeToChangelogFile="true"/>

 </databaseChangeLog>
@@ -0,0 +1,171 @@
+package cloud.nstart.terravault.ordinis.restapi.service;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.stereotype.Service;
+import org.springframework.util.LinkedMultiValueMap;
+import org.springframework.util.MultiValueMap;
+import org.springframework.web.client.HttpClientErrorException;
+import org.springframework.web.client.RestClient;
+import org.springframework.web.util.UriComponentsBuilder;
+
+import java.time.Duration;
+import java.time.Instant;
+import java.util.Optional;
+
+/**
+ * Phase 2: resolve {@code sub} via Keycloak Admin REST API. Activated when
+ * {@code ordinis.keycloak.admin.enabled=true} (and required env vars set).
+ *
+ * <p>Auth flow: client_credentials grant against
+ * {@code {issuer}/protocol/openid-connect/token}. The service-account
+ * client must have realm role {@code view-users} (composite of
+ * {@code realm-management/view-users}).
+ *
+ * <p>Token caching: the access_token from Keycloak typically lives
+ * 60-300s. We cache it minus 30s safety margin and refresh on miss.
+ *
+ * <p>Lookup uses {@code GET /admin/realms/{realm}/users/{sub}} which
+ * returns 404 cleanly when the sub is unknown. Network/5xx are surfaced
+ * as RuntimeException so {@link UserDisplayService} can log and skip.
+ */
+@Service
+@ConditionalOnProperty(name = "ordinis.keycloak.admin.enabled", havingValue = "true")
+public class KeycloakAdminUserResolver implements KeycloakUserResolver {
+
+  private static final Logger log = LoggerFactory.getLogger(KeycloakAdminUserResolver.class);
+  private static final Duration TOKEN_REFRESH_MARGIN = Duration.ofSeconds(30);
+
+  private final String adminBaseUrl;
+  private final String realm;
+  private final String clientId;
+  private final String clientSecret;
+  private final RestClient http;
+
+  // Token cache — Keycloak access_token + expiry. Access is single-threaded
+  // in practice (one resolver call at a time); volatile is enough.
+  private volatile String cachedToken;
+  private volatile Instant cachedTokenExpiresAt = Instant.EPOCH;
+
+  public KeycloakAdminUserResolver(
+      @Value("${ordinis.keycloak.admin.url}") String adminBaseUrl,
+      @Value("${ordinis.keycloak.admin.realm}") String realm,
+      @Value("${ordinis.keycloak.admin.client-id}") String clientId,
+      @Value("${ordinis.keycloak.admin.client-secret}") String clientSecret) {
+    this.adminBaseUrl = trimTrailingSlash(adminBaseUrl);
+    this.realm = realm;
+    this.clientId = clientId;
+    this.clientSecret = clientSecret;
+    this.http = RestClient.builder()
+        .baseUrl(this.adminBaseUrl)
+        .build();
+    log.info("KeycloakAdminUserResolver active — base={} realm={} client={}",
+        this.adminBaseUrl, realm, clientId);
+  }
+
+  @Override
+  public Optional<KeycloakUser> findById(String sub) {
+    if (sub == null || sub.isBlank()) return Optional.empty();
+    String token = currentToken();
+    String url = UriComponentsBuilder.fromHttpUrl(adminBaseUrl)
+        .pathSegment("admin", "realms", realm, "users", sub)
+        .toUriString();
+    try {
+      KeycloakUserDto dto = http.get()
+          .uri(url)
+          .header(HttpHeaders.AUTHORIZATION, "Bearer " + token)
+          .retrieve()
+          .body(KeycloakUserDto.class);
+      if (dto == null || dto.id == null) return Optional.empty();
+      String name = composeName(dto.firstName, dto.lastName);
+      return Optional.of(new KeycloakUser(
+          dto.id,
+          dto.username,
+          name,
+          dto.email));
+    } catch (HttpClientErrorException.NotFound e) {
+      // Sub doesn't exist in this realm — definitive miss. Don't cache the
+      // negative; UserDisplayService.find returns Optional.empty and UserCell
+      // falls back to short UUID. Negative cache TTL would help latency on
+      // bots/scanners but adds complexity not justified yet.
+      return Optional.empty();
+    } catch (HttpClientErrorException.Unauthorized e) {
+      // Cached token rejected — wipe and retry once. If still 401, surface.
+      cachedToken = null;
+      cachedTokenExpiresAt = Instant.EPOCH;
+      throw new RuntimeException("Keycloak admin auth rejected (token wiped, will retry)", e);
+    }
+  }
+
+  // --- token management ---
+
+  private synchronized String currentToken() {
+    if (cachedToken != null && Instant.now().isBefore(cachedTokenExpiresAt)) {
+      return cachedToken;
+    }
+    return fetchAndCacheToken();
+  }
+
+  private String fetchAndCacheToken() {
+    String tokenUrl = UriComponentsBuilder.fromHttpUrl(adminBaseUrl)
+        .pathSegment("realms", realm, "protocol", "openid-connect", "token")
+        .toUriString();
+    MultiValueMap<String, String> form = new LinkedMultiValueMap<>();
+    form.add("grant_type", "client_credentials");
+    form.add("client_id", clientId);
+    form.add("client_secret", clientSecret);
+    TokenResponse tr = http.post()
+        .uri(tokenUrl)
+        .contentType(MediaType.APPLICATION_FORM_URLENCODED)
+        .body(form)
+        .retrieve()
+        .onStatus(s -> s.is4xxClientError() || s.is5xxServerError(), (req, res) -> {
+          throw new RuntimeException("Keycloak admin token request failed: HTTP "
+              + res.getStatusCode() + " — check client_id/secret + realm");
+        })
+        .body(TokenResponse.class);
+    if (tr == null || tr.accessToken == null) {
+      throw new RuntimeException("Keycloak admin token response missing access_token");
+    }
+    cachedToken = tr.accessToken;
+    int expiresIn = tr.expiresIn != null ? tr.expiresIn : 60;
+    cachedTokenExpiresAt = Instant.now()
+        .plusSeconds(expiresIn)
+        .minus(TOKEN_REFRESH_MARGIN);
+    return cachedToken;
+  }
+
+  // --- helpers ---
+
+  private static String trimTrailingSlash(String s) {
+    return (s != null && s.endsWith("/")) ? s.substring(0, s.length() - 1) : s;
+  }
+
+  private static String composeName(String first, String last) {
+    String f = (first == null || first.isBlank()) ? "" : first.trim();
+    String l = (last == null || last.isBlank()) ? "" : last.trim();
+    String joined = (f + " " + l).trim();
+    return joined.isEmpty() ? null : joined;
+  }
+
+  // --- DTOs (Keycloak 26 admin API) ---
+
+  @JsonIgnoreProperties(ignoreUnknown = true)
+  private record TokenResponse(
+      @com.fasterxml.jackson.annotation.JsonProperty("access_token") String accessToken,
+      @com.fasterxml.jackson.annotation.JsonProperty("expires_in") Integer expiresIn) {}
+
+  @JsonIgnoreProperties(ignoreUnknown = true)
+  private record KeycloakUserDto(
+      String id,
+      String username,
+      String firstName,
+      String lastName,
+      String email) {}
+}
@@ -0,0 +1,24 @@
+package cloud.nstart.terravault.ordinis.restapi.service;
+
+import java.util.Optional;
+
+/**
+ * Phase 2 contract: resolve sub → user info via Keycloak Admin API. The
+ * implementation (Phase 2) will be an HTTP client using a service-account
+ * client + role {@code view-users} on realm {@code nstart}.
+ *
+ * <p>{@link UserDisplayService} consumes this as an optional dependency —
+ * if no bean exists in the context, the third resolve tier is skipped and
+ * UserCell falls back to short UUID. This keeps the Phase 1 (DB cache only)
+ * deployment runnable without Keycloak admin creds.
+ *
+ * <p>Implementations must throw {@link RuntimeException} on transient errors
+ * (network, 5xx) so the caller can log and continue. Return {@link Optional#empty()}
+ * for definitive 404 — sub does not exist in the realm.
+ */
+public interface KeycloakUserResolver {
+
+  Optional<KeycloakUser> findById(String sub);
+
+  record KeycloakUser(String sub, String preferredUsername, String name, String email) {}
+}
@@ -1,69 +1,165 @@
 package cloud.nstart.terravault.ordinis.restapi.service;

+import cloud.nstart.terravault.ordinis.domain.userdisplay.UserDisplayCacheEntry;
+import cloud.nstart.terravault.ordinis.domain.userdisplay.UserDisplayCacheEntry.Source;
+import cloud.nstart.terravault.ordinis.domain.userdisplay.UserDisplayCacheRepository;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;

 import java.time.OffsetDateTime;
 import java.util.Optional;
 import java.util.concurrent.ConcurrentHashMap;

 /**
- * In-memory кэш user display info (sub → preferredUsername / name / email),
- * заполняемый из JWT claims на каждом authenticated запросе через
- * {@link cloud.nstart.terravault.ordinis.restapi.auth.JwtUserCaptureFilter}.
+ * Three-tier resolve sub → display info:
+ * <ol>
+ *   <li>JVM ConcurrentHashMap hot cache (~µs).</li>
+ *   <li>{@code user_display_cache} Postgres table (~ms, persistent across pod restart).</li>
+ *   <li>Keycloak Admin API on-demand fallback (~10-50ms, Phase 2 — wired
+ *       via optional {@link KeycloakUserResolver} bean).</li>
+ * </ol>
 *
- * <p><b>Зачем:</b> audit log + record drafts хранят actor как JWT
- * {@code sub} UUID. Frontend (UserCell в audit / reviews) показывает short
- * UUID + tooltip — плохой UX. Этот сервис позволяет резолвить sub →
- * читаемое имя для display, не запрашивая Keycloak Admin API на каждое
- * отображение.
+ * <p>JwtUserCaptureFilter calls {@link #put} on every authenticated request
+ * → updates both hot cache and DB (idempotent merge).
 *
- * <p><b>Trade-offs:</b>
- * <ul>
- *   <li>In-memory — пропадает на pod restart. Постепенно заполняется
- *       обратно по мере того как users делают запросы. Для display это OK.</li>
- *   <li>Без Keycloak Admin API — не видим users которые ни разу не
- *       логинились в Ordinis. Display fallback → short UUID.</li>
- *   <li>Stale: если user сменит preferred_username в Keycloak, кэш
- *       обновится только на следующий его login + request.</li>
- * </ul>
+ * <p>Phase 3 (TBD): scheduled bulk sync from Keycloak will call
+ * {@link #upsertFromKeycloak} for every realm user every 6h to refill
+ * stale entries.
 *
- * <p>Альтернатива (на будущее): миграция 0023 user_display_cache table
- * + periodic Keycloak sync. Сделать когда станет реально нужно
- * (пока display name никто не редактирует постоянно).
+ * <p>Hot cache reads from DB lazily on miss — no warm-up at startup
+ * (would block readiness probe + Keycloak might be cold). First request
+ * for each sub after restart pays a single DB hit.
 */
@Service
 public class UserDisplayService {

-  /** Cap чтобы не держать миллионы entries в RAM при abuse. ~100 байт per
-   *  entry → 10k = 1MB. Eviction policy — LRU не нужен, hash без bound — fine. */
-  private static final int SOFT_CAP = 10_000;
-
-  private final ConcurrentHashMap<String, UserDisplayInfo> cache = new ConcurrentHashMap<>();
+  private static final Logger log = LoggerFactory.getLogger(UserDisplayService.class);

  /**
-   * Обновляет / создаёт запись для {@code sub}. Idempotent. Вызывается
-   * из {@code JwtUserCaptureFilter} на каждом authenticated request —
-   * стоимость ~O(1) hash put.
+   * Cap чтобы не держать миллионы entries в RAM при abuse. ~100 байт per
+   * entry → 10k = 1MB. Eviction policy — LRU не нужен, hash без bound — fine.
+   * DB table сама разрастается без cap (см. migration 0023 design notes).
   */
+  private static final int HOT_CACHE_CAP = 10_000;
+
+  private final ConcurrentHashMap<String, UserDisplayInfo> hotCache = new ConcurrentHashMap<>();
+  private final UserDisplayCacheRepository repository;
+  private final KeycloakUserResolver keycloakResolver;
+
+  public UserDisplayService(UserDisplayCacheRepository repository,
+                            @Autowired(required = false) KeycloakUserResolver keycloakResolver) {
+    this.repository = repository;
+    this.keycloakResolver = keycloakResolver;
+    if (keycloakResolver == null) {
+      log.info("UserDisplayService: KeycloakUserResolver not wired — three-tier resolve "
+          + "will fall back to short-UUID for users that never made an authenticated "
+          + "request to ordinis.");
+    }
+  }
+
+  /**
+   * Capture from JWT (called per-request by JwtUserCaptureFilter). Cheap and
+   * idempotent. Writes to hot cache + DB. Source is always JWT_CAPTURE here —
+   * KEYCLOAK_SYNC / KEYCLOAK_ON_DEMAND have their own write paths.
+   */
+  @Transactional
  public void put(String sub, String preferredUsername, String name, String email) {
    if (sub == null || sub.isBlank()) return;
-    if (cache.size() >= SOFT_CAP) return; // soft cap, don't grow unbounded
-    cache.put(sub, new UserDisplayInfo(
-        sub,
+    upsert(sub, preferredUsername, name, email, Source.JWT_CAPTURE);
+  }
+
+  /**
+   * Three-tier lookup. Returns empty only if sub absent in all three tiers
+   * AND Keycloak is unreachable (transient — caller's UserCell will fall
+   * back to short UUID, retry next time it renders).
+   */
+  @Transactional
+  public Optional<UserDisplayInfo> find(String sub) {
+    if (sub == null || sub.isBlank()) return Optional.empty();
+
+    // Tier 1: hot cache
+    UserDisplayInfo hot = hotCache.get(sub);
+    if (hot != null) return Optional.of(hot);
+
+    // Tier 2: DB
+    Optional<UserDisplayCacheEntry> dbHit = repository.findById(sub);
+    if (dbHit.isPresent()) {
+      UserDisplayInfo info = toInfo(dbHit.get());
+      cacheHot(sub, info);
+      return Optional.of(info);
+    }
+
+    // Tier 3: Keycloak Admin on-demand (Phase 2)
+    if (keycloakResolver != null) {
+      try {
+        Optional<KeycloakUserResolver.KeycloakUser> kc = keycloakResolver.findById(sub);
+        if (kc.isPresent()) {
+          KeycloakUserResolver.KeycloakUser u = kc.get();
+          UserDisplayInfo info = upsert(sub, u.preferredUsername(), u.name(), u.email(),
+              Source.KEYCLOAK_ON_DEMAND);
+          return Optional.of(info);
+        }
+      } catch (RuntimeException e) {
+        log.warn("Keycloak on-demand lookup failed for sub={}: {}", sub, e.getMessage());
+      }
+    }
+
+    return Optional.empty();
+  }
+
+  /**
+   * Phase 3 entry point — scheduled sync writes every realm user with
+   * Source.KEYCLOAK_SYNC. Same idempotent merge as {@link #put}.
+   */
+  @Transactional
+  public void upsertFromKeycloak(String sub, String preferredUsername, String name, String email) {
+    if (sub == null || sub.isBlank()) return;
+    upsert(sub, preferredUsername, name, email, Source.KEYCLOAK_SYNC);
+  }
+
+  /** Stats для observability. */
+  public int hotCacheSize() {
+    return hotCache.size();
+  }
+
+  // --- internals ---
+
+  private UserDisplayInfo upsert(String sub, String preferredUsername, String name,
+                                 String email, Source source) {
+    OffsetDateTime now = OffsetDateTime.now();
+    UserDisplayCacheEntry entry = repository.findById(sub).orElse(null);
+    if (entry == null) {
+      entry = new UserDisplayCacheEntry(sub,
          nullIfBlank(preferredUsername),
          nullIfBlank(name),
          nullIfBlank(email),
-        OffsetDateTime.now()));
+          source,
+          now);
+    } else {
+      entry.mergeFrom(preferredUsername, name, email, source, now);
+    }
+    repository.save(entry);
+    UserDisplayInfo info = toInfo(entry);
+    cacheHot(sub, info);
+    return info;
  }

-  public Optional<UserDisplayInfo> find(String sub) {
-    if (sub == null || sub.isBlank()) return Optional.empty();
-    return Optional.ofNullable(cache.get(sub));
+  private void cacheHot(String sub, UserDisplayInfo info) {
+    if (hotCache.size() < HOT_CACHE_CAP) {
+      hotCache.put(sub, info);
+    }
  }

-  /** Stats для observability — сколько users закэшировано. */
-  public int size() {
-    return cache.size();
+  private static UserDisplayInfo toInfo(UserDisplayCacheEntry e) {
+    return new UserDisplayInfo(
+        e.getSub(),
+        e.getPreferredUsername(),
+        e.getName(),
+        e.getEmail(),
+        e.getUpdatedAt());
  }

  private static String nullIfBlank(String s) {