@k2b/cloud 0.6.0 → 0.8.0

package/src/services/app-approval.ts

@@ -1,23 +1,24 @@
 import { createHash, randomBytes, randomInt, timingSafeEqual } from "node:crypto";
-import { sql, type SQL } from "bun";
+import { type SQL, sql } from "bun";
+import { env } from "../config/env";
+import { type AccountCategory, accountCategory } from "../contracts/account-categories";
 import {
-  APP_APPROVAL_LIMITS as limits,
   APP_APPROVAL_PATH,
   APP_APPROVAL_PROTOCOL,
-  AppDevicePublicKeySchema,
-  appDeviceProofMessage,
-  appPairingProofMessage,
   type AppDevicePublicKey,
+  AppDevicePublicKeySchema,
   type AppDeviceRequest,
   type AppDeviceView,
   type AppPendingLogin,
+  appDeviceProofMessage,
+  appPairingProofMessage,
+  APP_APPROVAL_LIMITS as limits,
 } from "../contracts/app-approval";
-import { accountCategory, type AccountCategory } from "../contracts/account-categories";
+import { publicCloudOrigin } from "../shared/app-url";
 import { isAccountCategoryAllowed } from "./account-category-policy";
 import { audit } from "./audit";
-import { decryptValue } from "./settings/crypto";
-import { publicCloudOrigin } from "../shared/app-url";
 import { CORE_SETTINGS } from "./settings/core-settings";
+import { decryptValue } from "./settings/crypto";
 
 export class AppApprovalError extends Error {
   constructor(
@@ -47,13 +48,13 @@ export const readAppApprovalConfig = async (db: SQL = sql, requireAppOrigin = tr
   const adminPairing = values.get("user.app_approval.admin_pairing") ?? false;
   if (typeof enabled !== "boolean" || typeof adminPairing !== "boolean") return reject("UNAVAILABLE", 503);
   // The issuer is the operator's canonical URL, never the request Host header.
-  const rawIssuer = values.get("app.url") ?? process.env.APP_URL ?? "localhost:3000";
+  const rawIssuer = values.get("app.url") ?? env.APP_URL ?? "localhost:3000";
   const rawOrigin = values.get("user.app_approval.origin") ?? CORE_SETTINGS["user.app_approval.origin"].default;
   const origin = (value: unknown) => {
     if (typeof value !== "string") return reject("UNAVAILABLE", 503);
     try {
       const url = new URL(value);
-      const development = process.env.NODE_ENV !== "production" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+      const development = env.NODE_ENV !== "production" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
       if (
         (url.protocol !== "https:" && !(url.protocol === "http:" && development)) ||
         url.username ||

package/src/services/audit/index.ts

@@ -236,7 +236,7 @@ const record = async (params: AuditRecordParams, db: AuditDb = sql): Promise<voi
         ${asString(params.error?.code ?? null)},
         ${sanitizeAuditText(params.error?.message ?? null)},
         ${asString(params.requestId)},
-        ${JSON.stringify(metadata)}::jsonb
+        ${JSON.stringify(metadata)}::text::jsonb
       )
     `;
   } catch (error) {

package/src/services/cache-fill.ts

@@ -0,0 +1,35 @@
+import { requestCacheRedis } from "./request-cache-redis";
+
+// Non-JSON markers remain compatible with older readers: they discard them and
+// use Postgres. A marker can never be confused with a stored JSON setting value.
+export const MISSING_SETTING = "!cloud:missing-setting:v1";
+const FILL_PREFIX = "!cloud:cache-fill:v1:";
+const COMPLETE = `if redis.call('GET', KEYS[1]) == ARGV[1] then
+  return redis.call('SET', KEYS[1], ARGV[2], 'EX', ARGV[3])
+end return nil`;
+const DISCARD = `if redis.call('GET', KEYS[1]) == ARGV[1] then
+  return redis.call('DEL', KEYS[1])
+end return 0`;
+
+/** A concurrent invalidation deletes the lease, so an old read cannot refill it. */
+export const claimCacheFill = async (key: string, observed: string | null): Promise<string | null> => {
+  try {
+    if (observed?.startsWith(FILL_PREFIX)) return null;
+    const redis = await requestCacheRedis();
+    if (observed !== null) await redis.send("EVAL", [DISCARD, "1", key, observed]);
+    const token = FILL_PREFIX + crypto.randomUUID();
+    // A slow loader may still return its value, but loses permission to cache it.
+    return (await redis.send("SET", [key, token, "NX", "EX", "5"])) === "OK" ? token : null;
+  } catch {
+    return null;
+  }
+};
+
+export const completeCacheFill = async (key: string, token: string | null, value: string, ttlSeconds: number): Promise<void> => {
+  if (!token) return;
+  try {
+    await (await requestCacheRedis()).send("EVAL", [COMPLETE, "1", key, token, value, String(ttlSeconds)]);
+  } catch {
+    // A cache failure does not change a successful authoritative read.
+  }
+};

package/src/services/help/index.ts

@@ -0,0 +1,109 @@
+import { type SQL, sql } from "bun";
+import { getApp, listApps } from "../../_internal/registry";
+import type { AppRegistryEntry } from "../../contracts/registry";
+import { resolveAppPresentations } from "../../shared/app-presentation";
+import { helpLocaleChain } from "../../shared/help";
+import { logger } from "../logging";
+import { HELP_RESOURCE_PAGE_SIZE, type HelpSelection, hasHelpBm25, metadata, queryHelp } from "./store";
+import type { HelpReader } from "./types";
+
+export { cleanupHelp, migrateHelp, registerHelp } from "./store";
+export type { HelpArticle, HelpMatch, HelpMetadata, HelpReader, HelpReaderFactory } from "./types";
+
+const log = logger("help");
+
+export const createHelpReader = (
+  locale: string,
+  dependencies: {
+    db?: SQL;
+    listApps?: () => Promise<AppRegistryEntry[]>;
+    getApp?: (appId: string) => Promise<AppRegistryEntry | null>;
+  } = {},
+): HelpReader => {
+  const db = dependencies.db ?? sql;
+  const select = async (appId?: string): Promise<HelpSelection[]> => {
+    const apps = appId
+      ? [await (dependencies.getApp ?? getApp)(appId)].filter((app): app is AppRegistryEntry => app !== null)
+      : await (dependencies.listApps ?? listApps)();
+    return resolveAppPresentations(apps, locale).flatMap((app) =>
+      app.help
+        ? [
+            {
+              app_id: app.id,
+              app_name: app.name,
+              manifest_hash: app.help.manifestHash,
+              locales: helpLocaleChain(locale, app.help.baseLocale),
+            },
+          ]
+        : [],
+    );
+  };
+  return {
+    async manifest(appId) {
+      const app = await (dependencies.getApp ?? getApp)(appId);
+      if (!app?.help) return null;
+      const [corpus] = await db`SELECT 1 FROM help.corpora WHERE app_id=${app.id} AND manifest_hash=${app.help.manifestHash}`;
+      if (!corpus) return null;
+      const rows = await queryHelp(
+        [
+          {
+            app_id: app.id,
+            app_name: app.name,
+            manifest_hash: app.help.manifestHash,
+            locales: helpLocaleChain(locale, app.help.baseLocale),
+          },
+        ],
+        {},
+        db,
+      );
+      return {
+        ...app.help,
+        locale,
+        documents: rows
+          .sort((a, b) => a.sort_order - b.sort_order || a.title.localeCompare(b.title))
+          .map((row) => ({
+            id: row.document_id,
+            title: row.title,
+            icon: row.icon ?? undefined,
+            description: row.description ?? undefined,
+            order: row.sort_order,
+            locale: row.locale,
+            searchUrl: `/api/help/v1/${encodeURIComponent(appId)}/search`,
+            url: `/api/help/v1/${encodeURIComponent(appId)}/documents/${encodeURIComponent(row.document_id)}`,
+          })),
+      };
+    },
+    async list(cursor = "") {
+      return (await queryHelp(await select(), { cursor, limit: HELP_RESOURCE_PAGE_SIZE + 1 }, db)).map(metadata);
+    },
+    async read(input) {
+      const [row] = await queryHelp(await select(input.appId), { documentId: input.documentId, body: true, limit: 1 }, db);
+      return row?.markdown === undefined ? null : { ...metadata(row), markdown: row.markdown };
+    },
+    async search(input) {
+      const query = input.query.trim().slice(0, 200);
+      if (!query) return [];
+      const selection = await select(input.appId);
+      if (!selection.length) return [];
+      const options = { query, limit: Math.max(1, Math.min(Math.floor(Number.isFinite(input.limit) ? input.limit! : 10), 25)) };
+      const bm25 = await hasHelpBm25(db);
+      const rows = await queryHelp(selection, { ...options, bm25 }, db).catch((error: unknown) => {
+        // Only missing optional SQL objects qualify for fallback, not connection/query errors.
+        const code = error && typeof error === "object" ? (Reflect.get(error, "errno") ?? Reflect.get(error, "code")) : undefined;
+        if (!bm25 || !["42883", "42704", "42P01"].includes(String(code))) throw error;
+        log.warn("BM25 unavailable; using native Help search");
+        return queryHelp(selection, options, db);
+      });
+      return rows.map((row) => ({
+        kind: "help",
+        appId: row.app_id,
+        appName: row.app_name,
+        locale: row.locale,
+        documentId: row.document_id,
+        title: row.title,
+        description: row.description ?? undefined,
+      }));
+    },
+  };
+};
+export { startHelpMaintenance } from "./maintenance";

package/src/services/help/maintenance.ts

@@ -0,0 +1,25 @@
+import { logger } from "../logging";
+import { cleanupHelp } from "./store";
+
+const log = logger("help:maintenance");
+/** Core owns the timer; stop waits for the current bounded deletion. */
+export const startHelpMaintenance = (): (() => Promise<void>) => {
+  let stopped = false;
+  let inFlight: Promise<void> | undefined;
+  let timer: ReturnType<typeof setTimeout>;
+  const run = () => {
+    inFlight = cleanupHelp()
+      .catch((error) => {
+        log.error("Expired Help cleanup failed", { error: error instanceof Error ? error.message : String(error) });
+      })
+      .finally(() => {
+        if (!stopped) timer = setTimeout(run, 60_000);
+      });
+  };
+  timer = setTimeout(run, 60_000);
+  return async () => {
+    stopped = true;
+    clearTimeout(timer);
+    await inFlight;
+  };
+};

package/src/services/help/store.ts

@@ -0,0 +1,180 @@
+import { type SQL, sql } from "bun";
+import { APP_REGISTRY_TTL_MS } from "../../_internal/registry";
+import type { HelpCorpus, HelpMetadata } from "./types";
+
+// One expired app lease of grace after an app can no longer be discovered.
+export const HELP_RETENTION_MS = APP_REGISTRY_TTL_MS * 2;
+export const HELP_RESOURCE_PAGE_SIZE = 100;
+const searchConfigs = ["english", "german", "simple"] as const;
+
+export const migrateHelp = async (db: SQL = sql): Promise<void> => {
+  await db.begin(async (tx) => {
+    await tx`SELECT pg_advisory_xact_lock(hashtext('cloud:help:migrate'))`;
+    await tx`CREATE SCHEMA IF NOT EXISTS help`.simple();
+    await tx`CREATE TABLE IF NOT EXISTS help.corpora (
+    app_id text NOT NULL, manifest_hash text NOT NULL, base_locale text NOT NULL,
+    last_seen_at timestamptz NOT NULL DEFAULT now(),
+    PRIMARY KEY (app_id, manifest_hash)
+  )`.simple();
+    await tx`CREATE INDEX IF NOT EXISTS help_expiry_idx ON help.corpora(last_seen_at)`.simple();
+    await tx`CREATE TABLE IF NOT EXISTS help.documents (
+    app_id text NOT NULL, manifest_hash text NOT NULL, locale text NOT NULL, document_id text NOT NULL,
+    title text NOT NULL, description text, icon text, sort_order integer NOT NULL,
+    markdown text NOT NULL, search_text text NOT NULL, search_config text NOT NULL,
+    search_document tsvector NOT NULL,
+    PRIMARY KEY (app_id, manifest_hash, locale, document_id),
+    FOREIGN KEY (app_id, manifest_hash) REFERENCES help.corpora ON DELETE CASCADE
+  )`.simple();
+    await tx`CREATE INDEX IF NOT EXISTS help_search_idx ON help.documents USING gin(search_document)`.simple();
+  });
+  // The operator enables the extension; Help never installs server extensions.
+  const [extension] = await db<{ installed: boolean }[]>`SELECT EXISTS (
+    SELECT 1 FROM pg_extension WHERE extname = 'pg_textsearch') AS installed`;
+  if (extension?.installed) {
+    try {
+      for (const config of searchConfigs) {
+        await db
+          .unsafe(`CREATE INDEX IF NOT EXISTS help_bm25_${config}_idx ON help.documents
+        USING bm25(search_text) WITH (text_config='${config}') WHERE search_config='${config}'`)
+          .simple();
+      }
+    } catch (error) {
+      console.warn("Optional Help BM25 indexes unavailable; native search remains active", error);
+    }
+  }
+};
+
+/** Commit the complete source once; subsequent app heartbeats only renew its lease. */
+export const registerHelp = async (corpus: HelpCorpus, db: SQL = sql): Promise<void> => {
+  await db.begin(async (tx) => {
+    await tx`SET LOCAL statement_timeout = '10s'`.simple();
+    const renewed = await tx`UPDATE help.corpora SET last_seen_at = clock_timestamp()
+      WHERE app_id = ${corpus.appId} AND manifest_hash = ${corpus.manifestHash} RETURNING app_id`;
+    if (renewed.length) return;
+    const inserted = await tx`INSERT INTO help.corpora(app_id, manifest_hash, base_locale)
+      VALUES (${corpus.appId}, ${corpus.manifestHash}, ${corpus.baseLocale})
+      ON CONFLICT (app_id, manifest_hash) DO UPDATE SET last_seen_at = clock_timestamp()
+      RETURNING (xmax = 0) AS inserted`;
+    if (!inserted[0]?.inserted) return;
+    for (const [locale, documents] of [[corpus.baseLocale, corpus.documents] as const, ...Object.entries(corpus.documentsByLocale)]) {
+      const config = locale.split("-")[0] === "de" ? "german" : locale.split("-")[0] === "en" ? "english" : "simple";
+      // One bounded article per statement; no duplicate whole-corpus JSON transport.
+      for (const document of documents) {
+        const text = `${document.title}\n${document.description ?? ""}\n${document.searchText}`;
+        await tx`INSERT INTO help.documents(app_id, manifest_hash, locale, document_id, title, description, icon,
+          sort_order, markdown, search_text, search_config, search_document)
+          VALUES (${corpus.appId}, ${corpus.manifestHash}, ${locale}, ${document.id}, ${document.title},
+            ${document.description ?? null}, ${document.icon ?? null}, ${document.order}, ${document.markdown}, ${text}, ${config},
+            setweight(to_tsvector(${config}::regconfig, ${document.id + " " + document.title}), 'A') ||
+            setweight(to_tsvector(${config}::regconfig, ${document.description ?? ""}), 'B') ||
+            setweight(to_tsvector(${config}::regconfig, ${document.searchText}), 'D'))`;
+      }
+    }
+  });
+};
+
+/** Row locks serialize cleanup with publication/renewal. Delete at most one corpus per tick. */
+export const cleanupHelp = async (db: SQL = sql): Promise<void> => {
+  await db.begin(async (tx) => {
+    await tx`SET LOCAL statement_timeout = '10s'`.simple();
+    await tx`DELETE FROM help.corpora WHERE (app_id, manifest_hash) IN (
+    SELECT app_id, manifest_hash FROM help.corpora
+    WHERE last_seen_at < now() - ${HELP_RETENTION_MS} * interval '1 millisecond'
+    ORDER BY last_seen_at LIMIT 1 FOR UPDATE SKIP LOCKED
+  )`;
+  });
+};
+
+export type HelpSelection = { app_id: string; app_name: string; manifest_hash: string; locales: string[] };
+type Row = {
+  app_id: string;
+  app_name: string;
+  manifest_hash: string;
+  locale: string;
+  document_id: string;
+  title: string;
+  description: string | null;
+  icon: string | null;
+  sort_order: number;
+  markdown?: string;
+};
+export const metadata = (row: Row): HelpMetadata => ({
+  appId: row.app_id,
+  appName: row.app_name,
+  manifestHash: row.manifest_hash,
+  locale: row.locale,
+  documentId: row.document_id,
+  title: row.title,
+  description: row.description ?? undefined,
+  icon: row.icon ?? undefined,
+  order: row.sort_order,
+});
+
+export const hasHelpBm25 = async (db: SQL = sql): Promise<boolean> => {
+  const [row] = await db<{ ready: boolean }[]>`SELECT
+    EXISTS (SELECT 1 FROM pg_extension WHERE extname='pg_textsearch') AND
+    (SELECT count(*) = 3 FROM pg_index i JOIN pg_class c ON c.oid=i.indexrelid JOIN pg_am a ON a.oid=c.relam
+      WHERE c.oid IN (to_regclass('help.help_bm25_english_idx'), to_regclass('help.help_bm25_german_idx'),
+        to_regclass('help.help_bm25_simple_idx')) AND i.indisvalid AND a.amname='bm25') AS ready`;
+  return row?.ready === true;
+};
+
+/** Locale precedence is applied before matching, ranking and limiting, including partial translations. */
+export const queryHelp = async (
+  selection: HelpSelection[],
+  input: {
+    query?: string;
+    documentId?: string;
+    body?: boolean;
+    limit?: number;
+    cursor?: string;
+    bm25?: boolean;
+  },
+  db: SQL = sql,
+): Promise<Row[]> => {
+  if (!selection.length) return [];
+  const ranked = input.query !== undefined;
+  const nativeRank = `ts_rank_cd(d.search_document, websearch_to_tsquery(d.search_config::regconfig, $2))`;
+  const bm25Rank = `CASE d.search_config ${searchConfigs
+    .map((config) => `WHEN '${config}' THEN d.search_text <@> to_bm25query($2, 'help.help_bm25_${config}_idx')`)
+    .join(" ")} END`;
+  const matching = searchConfigs
+    .map((config) => `(d.search_config='${config}' AND d.search_document @@ websearch_to_tsquery('${config}', $2))`)
+    .join(" OR ");
+  const pending = db.unsafe<Row[]>(
+    `WITH active AS (
+    SELECT * FROM jsonb_to_recordset(($1::text)::jsonb) AS a(app_id text, app_name text, manifest_hash text, locales text[])
+  ) SELECT d.app_id, a.app_name, d.manifest_hash, d.locale, d.document_id, d.title, d.description, d.icon, d.sort_order
+    ${input.body ? ", d.markdown" : ""}
+    FROM help.documents d JOIN active a ON a.app_id=d.app_id AND a.manifest_hash=d.manifest_hash
+    WHERE length($2::text) >= 0 AND d.locale=ANY(a.locales)
+      AND NOT EXISTS (SELECT 1 FROM help.documents preferred
+        WHERE preferred.app_id=d.app_id AND preferred.manifest_hash=d.manifest_hash AND preferred.document_id=d.document_id
+          AND preferred.locale=ANY(a.locales) AND array_position(a.locales, preferred.locale)<array_position(a.locales, d.locale))
+      AND ($3::text IS NULL OR d.document_id=$3)
+      AND ($4::text IS NULL OR ('cloud://help/' || d.app_id || '/' || d.document_id) COLLATE "C" > $4)
+      ${ranked ? `AND (lower(d.document_id)=lower($2) OR lower(d.title)=lower($2) OR ${matching})` : ""}
+    ORDER BY ${
+      ranked
+        ? `(lower(d.document_id)=lower($2) OR lower(d.title)=lower($2)) DESC,
+      ${input.bm25 ? bm25Rank + " ASC," : ""} ${nativeRank} DESC,`
+        : ""
+    }
+      d.app_id COLLATE "C", ${input.cursor !== undefined ? "" : "d.sort_order,"} d.document_id COLLATE "C"
+    ${input.limit !== undefined ? "LIMIT $5" : ""}`,
+    [
+      JSON.stringify(selection),
+      input.query ?? "",
+      input.documentId ?? null,
+      input.cursor ?? null,
+      ...(input.limit !== undefined ? [input.limit] : []),
+    ],
+  );
+  // Match the app publication write deadline and bound abandoned reads at the driver.
+  const timeout = setTimeout(() => pending.cancel(), 10_000);
+  try {
+    return await pending;
+  } finally {
+    clearTimeout(timeout);
+  }
+};

package/src/services/help/types.ts

@@ -0,0 +1,46 @@
+import type { AppRegistryHelpSummary } from "../../contracts/registry";
+import type { HelpDocumentManifest } from "../../shared/help";
+
+export type HelpDocument = {
+  id: string;
+  title: string;
+  icon?: string;
+  description?: string;
+  order: number;
+  markdown: string;
+  searchText: string;
+};
+
+export type HelpCorpus = {
+  appId: string;
+  manifestHash: string;
+  baseLocale: string;
+  documents: readonly HelpDocument[];
+  documentsByLocale: Readonly<Record<string, readonly HelpDocument[]>>;
+};
+
+export type HelpMetadata = {
+  appId: string;
+  appName: string;
+  manifestHash: string;
+  locale: string;
+  documentId: string;
+  title: string;
+  description?: string;
+  icon?: string;
+  order: number;
+};
+export type HelpArticle = HelpMetadata & { markdown: string };
+export type HelpMatch = Pick<HelpMetadata, "appId" | "appName" | "locale" | "documentId" | "title" | "description"> & { kind: "help" };
+export type HelpSearchInput = { query: string; appId?: string; limit?: number };
+export type HelpReadInput = { appId: string; documentId: string };
+export type HelpManifestResult = AppRegistryHelpSummary & { locale: string; documents: readonly HelpDocumentManifest[] };
+
+/** One request's language; operations resolve the current published app versions. */
+export type HelpReader = {
+  manifest(appId: string): Promise<HelpManifestResult | null>;
+  list(cursor?: string): Promise<HelpMetadata[]>;
+  search(input: HelpSearchInput): Promise<HelpMatch[]>;
+  read(input: HelpReadInput): Promise<HelpArticle | null>;
+};
+export type HelpReaderFactory = (locale: string) => HelpReader;

package/src/services/identity/invocation-actor.ts

@@ -4,7 +4,7 @@ import type { AccessSubject } from "../../server/services/access";
 import { isAccountCategoryAllowed } from "../account-category-policy";
 import { isAccountExpired } from "../account-model";
 import type { ServiceAccount } from "../service-accounts";
-import { buildProjectedUser, loadCurrentUser, userProjectionSql } from "../session/user";
+import { buildProjectedUser, loadCurrentUser, userProjectionJoin, userProjectionSql } from "../session/user";
 import type { CloudInvocationClaims } from "./invocation-token";
 import { getIdentityRuntimeConfig } from "./runtime-config";
 
@@ -92,7 +92,7 @@ export const resolveInvocationAuthority = async (
       ${userProjectionSql(groupsAdmin)}
     FROM auth.service_accounts sa
     LEFT JOIN auth.users u ON u.id = sa.delegated_user_id
-    LEFT JOIN auth.user_ipa_data ui ON ui.user_id = u.id
+    ${userProjectionJoin()}
     WHERE sa.id = ${claims.sub}::uuid
       AND sa.status = 'active'
   `;

package/src/services/identity/key-config.ts

@@ -1,4 +1,6 @@
 import { crypto } from "@k2b/stdlib";
+import { getProcessApplicationId } from "../../_internal/process-identity";
+import { env } from "../../config/env";
 
 const KEY_PATTERN = /^[0-9a-f]{64}$/i;
 
@@ -23,12 +25,12 @@ const identify = async (key: string): Promise<{ id: string; key: string }> => ({
 });
 
 export const readIdentityKeyEncryptionConfig = async (): Promise<IdentityKeyEncryptionConfig> => {
-  if ((process.env.APP_ID ?? "").trim() !== "core") {
+  if (getProcessApplicationId() !== "core") {
     throw new Error("Private Cloud identity keys may only be loaded by the Core application");
   }
-  const current = parseKey("CLOUD_IDENTITY_KEY_ENCRYPTION_KEY", process.env.CLOUD_IDENTITY_KEY_ENCRYPTION_KEY, true)!;
-  const previous = parseKey("CLOUD_IDENTITY_PREVIOUS_KEY", process.env.CLOUD_IDENTITY_PREVIOUS_KEY, false);
-  const next = parseKey("CLOUD_IDENTITY_NEXT_KEY", process.env.CLOUD_IDENTITY_NEXT_KEY, false);
+  const current = parseKey("CLOUD_IDENTITY_KEY_ENCRYPTION_KEY", env.CLOUD_IDENTITY_KEY_ENCRYPTION_KEY, true)!;
+  const previous = parseKey("CLOUD_IDENTITY_PREVIOUS_KEY", env.CLOUD_IDENTITY_PREVIOUS_KEY, false);
+  const next = parseKey("CLOUD_IDENTITY_NEXT_KEY", env.CLOUD_IDENTITY_NEXT_KEY, false);
   const currentIdentified = await identify(current);
   const previousIdentified = previous ? await identify(previous) : null;
   const nextIdentified = next ? await identify(next) : null;
@@ -36,6 +38,7 @@ export const readIdentityKeyEncryptionConfig = async (): Promise<IdentityKeyEncr
   if (new Set(ids).size !== ids.length) {
     throw new Error("Configured Cloud identity KEKs must be distinct");
   }
-  if (previousIdentified && nextIdentified) throw new Error("Configure either CLOUD_IDENTITY_PREVIOUS_KEY or CLOUD_IDENTITY_NEXT_KEY, not both");
+  if (previousIdentified && nextIdentified)
+    throw new Error("Configure either CLOUD_IDENTITY_PREVIOUS_KEY or CLOUD_IDENTITY_NEXT_KEY, not both");
   return { current: currentIdentified, previous: previousIdentified, next: nextIdentified };
 };

package/src/services/identity/key-ring.ts

@@ -181,7 +181,7 @@ const insertKey = async (
       purpose, state, kid, alg, public_jwk, encrypted_private_jwk, encryption_key_id,
       created_at, activate_at, activated_at, sign_until, verify_until
     ) VALUES (
-      ${purpose}, ${state}, ${generated.kid}, ${CLOUD_IDENTITY_ALGORITHM}, ${JSON.stringify(generated.publicJwk)}::jsonb,
+      ${purpose}, ${state}, ${generated.kid}, ${CLOUD_IDENTITY_ALGORITHM}, ${JSON.stringify(generated.publicJwk)}::text::jsonb,
       ${generated.encryptedPrivateJwk}, ${generated.encryptionKeyId}, ${now}, ${activateAt},
       ${state === "active" ? now : null}, ${signUntil}, ${verifyUntil}
     )

package/src/services/identity/runtime-config.ts

@@ -1,3 +1,4 @@
+import { env } from "../../config/env";
 import { publicCloudOrigin } from "../../shared/app-url";
 import { get as getSetting } from "../settings";
 import { CLOUD_INVOCATION_JWKS_PATH, CLOUD_OAUTH_JWKS_PATH, CLOUD_SESSION_JWKS_PATH } from "./constants";
@@ -28,7 +29,7 @@ const normalizeGroups = (value: unknown): string[] => {
   return groups.length > 0 ? groups : ["admins"];
 };
 
-const resolveCoreJwksUrl = (issuer: string, path: string, transportOrigin = process.env.CLOUD_IDENTITY_JWKS_ORIGIN?.trim()): URL => {
+const resolveCoreJwksUrl = (issuer: string, path: string, transportOrigin = env.CLOUD_IDENTITY_JWKS_ORIGIN): URL => {
   if (!transportOrigin) return new URL(path, issuer);
   const origin = new URL(transportOrigin);
   if (origin.protocol !== "http:" && origin.protocol !== "https:") {
@@ -37,13 +38,13 @@ const resolveCoreJwksUrl = (issuer: string, path: string, transportOrigin = proc
   return new URL(path, origin);
 };
 
-export const resolveSessionJwksUrl = (issuer: string, transportOrigin = process.env.CLOUD_IDENTITY_JWKS_ORIGIN?.trim()): URL =>
+export const resolveSessionJwksUrl = (issuer: string, transportOrigin = env.CLOUD_IDENTITY_JWKS_ORIGIN): URL =>
   resolveCoreJwksUrl(issuer, CLOUD_SESSION_JWKS_PATH, transportOrigin);
 
-export const resolveInvocationJwksUrl = (issuer: string, transportOrigin = process.env.CLOUD_IDENTITY_JWKS_ORIGIN?.trim()): URL =>
+export const resolveInvocationJwksUrl = (issuer: string, transportOrigin = env.CLOUD_IDENTITY_JWKS_ORIGIN): URL =>
   resolveCoreJwksUrl(issuer, CLOUD_INVOCATION_JWKS_PATH, transportOrigin);
 
-export const resolveOAuthJwksUrl = (issuer: string, transportOrigin = process.env.CLOUD_OAUTH_JWKS_ORIGIN?.trim()): URL => {
+export const resolveOAuthJwksUrl = (issuer: string, transportOrigin = env.CLOUD_OAUTH_JWKS_ORIGIN): URL => {
   if (!transportOrigin) return new URL(CLOUD_OAUTH_JWKS_PATH, issuer);
 
   const url = new URL(CLOUD_OAUTH_JWKS_PATH, transportOrigin);
@@ -56,7 +57,7 @@ export const resolveOAuthJwksUrl = (issuer: string, transportOrigin = process.en
 const load = async (): Promise<IdentityRuntimeConfig> => {
   const [appUrl, rawGroupsAdmin] = await Promise.all([getSetting<string>("app.url"), getSetting<unknown>("freeipa.groups.admin")]);
   const issuer = publicCloudOrigin(appUrl);
-  if (process.env.NODE_ENV === "production" && new URL(issuer).protocol !== "https:") {
+  if (env.NODE_ENV === "production" && new URL(issuer).protocol !== "https:") {
     throw new Error("Cloud identity issuer must use HTTPS in production");
   }
   return {

package/src/services/index.ts

@@ -4,7 +4,11 @@ export { accounts } from "./accounts";
 export { accountsAppService } from "./accounts";
 export { posix as linuxIdentities, PosixError } from "./accounts/posix";
 export type { PosixCandidate } from "./accounts/posix";
+export { accountIdentities, AccountIdentityError } from "./accounts/identities";
+export type { AccountIdentityUser, AccountIdentityGroup, AccountIdentityPage, AccountIdentityAvailability } from "./accounts/identities";
+export type { AccountIdentityReconciliation } from "./accounts/identity-reconciliation";
 export { providers } from "./providers";
+export { requestPublicHttps, type PublicHttpInput } from "./public-http";
 export { authFlows } from "./auth-flows";
 export { toPgIntArray, toPgTextArray, toPgUuidArray, escapeLikePattern, isUniqueViolation } from "./postgres";
 
@@ -144,6 +148,10 @@ export {
   MarkdownPdfError,
   buildMarkdownPdfHtml,
   getGotenbergConfig,
+  attachPdfFiles,
+  attachPdfFilesWithConfig,
+  renderFacturXHtmlToPdf,
+  renderFacturXHtmlToPdfWithConfig,
   mergePdfs,
   mergePdfsWithConfig,
   renderMarkdownToPdf,
@@ -155,6 +163,8 @@ export {
 } from "./pdf";
 export type {
   GotenbergConfig,
+  AttachPdfFilesInput,
+  RenderFacturXHtmlToPdfInput,
   GotenbergRenderErrorCode,
   MarkdownPdfErrorCode,
   MarkdownPdfTemplateId,
@@ -185,3 +195,8 @@ export { latestTopicCursor } from "./topic-cursor";
 export { readAccountCategoryPolicy, isAccountCategoryAllowed } from "./account-category-policy";
 export { appApproval, type AppDeviceEnrollmentNotice } from "./app-approval";
 export { legalConsent } from "./legal-consent";
+
+/** Core-owned app bar administration; service methods enforce administrator access. */
+export { railShortcuts } from "./rail-shortcuts";
+
+export type { WebVitalsOverview, WebVitalsQuery, WebVitalMetric, WebVitalName } from "./logging/web-vitals";

package/src/services/ipa/posix.ts

@@ -1,4 +1,4 @@
-import { sql } from "bun";
+import type { sql } from "bun";
 
 /** Mirror directory-owned attributes, including missing values; never apply local defaults. */
 export const mirrorIpaPosix = async (

package/src/services/ipa/sync.ts

@@ -6,9 +6,9 @@ import { applyIpaAccountTransitionPolicy } from "../accounts/switching";
 import { getFreeIpaConfig } from "../freeipa-config";
 import { logger } from "../logging";
 import { session } from "../session";
-import { mirrorIpaPosix } from "./posix";
 import * as settings from "../settings";
 import { buildEffectiveIpaGroupsByUid } from "./effective-groups";
+import { mirrorIpaPosix } from "./posix";
 import { calculateIpaProfileFromEffectiveProjection, getEffectiveUserGroups } from "./profile";
 import { createIpaRuntimeCheckpoint, type IpaSyncRuntime } from "./runtime";
 import { assessIpaDestructionGuard, formatIpaDestructionGuardFailure, readCompleteIpaList, selectStaleLocalIpaRows } from "./sync-planning";