@k2b/cloud 0.6.0-rc.0 → 0.7.0

package/src/server/middleware/auth.ts

@@ -1,5 +1,6 @@
 import type { Context } from "hono";
 import { createMiddleware } from "hono/factory";
+import { measureServerPhase } from "../../_internal/server-timing";
 import type { MessageResponse, Role, RoleOrSpecial, User, UserProfile, UserProvider } from "../../contracts/shared";
 import { isAccountExpired } from "../../services/account-model";
 import { isReservedWorkloadApiCredential } from "../../services/identity/workload-auth";
@@ -215,10 +216,10 @@ const loadAuthenticatedActor = (
   c: Context<AuthContext>,
   options: Pick<RoleOptions, "oauthAudience"> = {},
 ): Promise<AuthenticatedActorResult> => {
-  if (options.oauthAudience) return loadAuthenticatedActorUncached(c, options);
+  if (options.oauthAudience) return measureServerPhase(c, "auth", () => loadAuthenticatedActorUncached(c, options));
   const existing = actorResolutionByRequest.get(c);
   if (existing) return existing;
-  const pending = loadAuthenticatedActorUncached(c, options);
+  const pending = measureServerPhase(c, "auth", () => loadAuthenticatedActorUncached(c, options));
   actorResolutionByRequest.set(c, pending);
   return pending;
 };

package/src/server/middleware/route-template.ts

@@ -16,6 +16,8 @@
  * Templates only: the request path itself never leaves the app, so ids
  * and query strings stay out of telemetry by construction.
  */
+
+import type { Context } from "hono";
 import { createMiddleware } from "hono/factory";
 import { routePath } from "hono/route";
 import { ROUTE_TEMPLATE_HEADER } from "../../services/gateway";
@@ -32,14 +34,18 @@ const MAX_TEMPLATE_LENGTH = 200;
  */
 const stripParamConstraints = (template: string): string => template.replace(/\{[^}]*\}/g, "");
 
+export const matchedRouteTemplate = (c: Context): string | null => {
+  const template = routePath(c);
+  return !template || template === UNMATCHED ? null : stripParamConstraints(template).slice(0, MAX_TEMPLATE_LENGTH);
+};
+
 export const routeTemplate = createMiddleware(async (c, next) => {
   await next();
 
   // Best-effort: telemetry enrichment must never break a response.
   try {
-    const template = routePath(c);
-    if (!template || template === UNMATCHED) return;
-    c.res.headers.set(ROUTE_TEMPLATE_HEADER, stripParamConstraints(template).slice(0, MAX_TEMPLATE_LENGTH));
+    const template = matchedRouteTemplate(c);
+    if (template) c.res.headers.set(ROUTE_TEMPLATE_HEADER, template);
   } catch {
     // Immutable response headers or an unrouted context — nothing to report.
   }

package/src/server/middleware/runtime.ts

@@ -9,11 +9,12 @@
  */
 import { createMiddleware } from "hono/factory";
 import { ensureRuntimeWatcher, getCurrentRuntime } from "../../_internal/runtime-watcher";
+import { measureServerPhase } from "../../_internal/server-timing";
 import { routeTemplate } from "./route-template";
 
 export const runtime = () =>
   createMiddleware(async (c, next) => {
-    await ensureRuntimeWatcher();
+    await measureServerPhase(c, "runtime", ensureRuntimeWatcher);
     (c as unknown as { set: (k: string, v: unknown) => void }).set("runtime", getCurrentRuntime());
     // Piggybacks on the middleware every proxied app already installs, so
     // gateway telemetry gets per-endpoint route templates without any app

package/src/server/middleware/settings.ts

@@ -13,6 +13,7 @@
  * `.use()` path instead.
  */
 import { createMiddleware } from "hono/factory";
+import { measureServerPhase } from "../../_internal/server-timing";
 import {
   type ActiveAnnouncementsResponse,
   type AnnouncementCookieState,
@@ -38,18 +39,23 @@ export const settings = (opts?: { skipPrefixes?: readonly string[] }) => {
   return createMiddleware(async (c, next) => {
     const path = c.req.path;
     if (!skip.some((p) => path.startsWith(p))) {
-      (c as unknown as { set: (k: string, v: unknown) => void }).set("settings", await loadSnapshot());
-    }
-    const cookieHeader = c.req.header("Cookie") ?? null;
-    if (shouldLoadAnnouncements(path, cookieHeader)) {
-      const cookieState = parseAnnouncementCookieHeader(cookieHeader);
-      try {
-        const active = await announcements.active.forState({ state: cookieState });
-        (c as unknown as { set: (k: string, v: unknown) => void }).set("announcements", { ...active, cookieState });
-      } catch (error) {
-        log.warn("Failed to preload announcements", { error: error instanceof Error ? error.message : String(error) });
-      }
+      (c as unknown as { set: (k: string, v: unknown) => void }).set("settings", await measureServerPhase(c, "settings", loadSnapshot));
     }
     await next();
   });
 };
+
+/** Called by SSR finalization, after redirects and non-HTML responses are known. */
+export const preloadLayoutAnnouncements = async (c: import("hono").Context): Promise<void> => {
+  const path = c.req.path;
+  const cookieHeader = c.req.header("Cookie") ?? null;
+  if (shouldLoadAnnouncements(path, cookieHeader)) {
+    const cookieState = parseAnnouncementCookieHeader(cookieHeader);
+    try {
+      const active = await announcements.active.forState({ state: cookieState });
+      (c as unknown as { set: (k: string, v: unknown) => void }).set("announcements", { ...active, cookieState });
+    } catch (error) {
+      log.warn("Failed to preload announcements", { error: error instanceof Error ? error.message : String(error) });
+    }
+  }
+};

package/src/server/services/access-revision.ts

@@ -0,0 +1,10 @@
+import { createHash } from "node:crypto";
+import type { Principal, PermissionLevel } from "./access";
+
+/** Compare the grants that were reviewed with those held under a resource lock. */
+export function accessRevision(entries: ReadonlyArray<{ id: string; principal: Principal; permission: PermissionLevel }>): string {
+  const state = entries.map(entry => [entry.id, entry.permission,
+    Object.entries(entry.principal).sort(([left], [right]) => left.localeCompare(right))])
+    .sort((left, right) => String(left[0]).localeCompare(String(right[0])));
+  return createHash("sha256").update(JSON.stringify(state)).digest("hex");
+}

package/src/server/services/access.ts

@@ -568,7 +568,7 @@ export const listUsersWithAccess = async (params: {
  * Resolve display names for access entries.
  * Populates the displayName field based on principal type.
  */
-export const resolveDisplayNames = async (entries: AccessEntry[]): Promise<AccessEntry[]> => {
+export const resolveDisplayNames = async <T extends { principal: Principal }>(entries: T[]): Promise<(T & { displayName: string; avatarHash?: string | null })[]> => {
   const userIds = entries.filter((e) => e.principal.type === "user").map((e) => (e.principal as { type: "user"; userId: string }).userId);
 
   const groupIds = entries

package/src/server/services/index.ts

@@ -46,3 +46,4 @@ export { crypto, err, fail, isServiceError, ok, okMany, paginate, password, svg,
 // Compat aliases for old API names
 export const images = { generateFallback: _svg.generateAvatar, parseWebpDataUrl: _svg.parseWebpDataUrl };
 export const generatePassword = _password.random;
+export { accessRevision } from "./access-revision";

package/src/services/account-category-policy.ts

@@ -20,6 +20,15 @@ const readValue = async (key: string, fallback: boolean | string, db: typeof sql
   return value;
 };
 
+/** Decode a policy selected alongside a user, without a second database read. */
+export const decodeAccountCategoryEnabled = async (encrypted: unknown): Promise<boolean> => {
+  if (encrypted === null || encrypted === undefined) return true;
+  if (typeof encrypted !== "string") throw new Error("Invalid account category configuration");
+  const value = await decryptValue(encrypted);
+  if (typeof value !== "boolean") throw new Error("Invalid account category configuration");
+  return value;
+};
+
 export const isAccountCategoryAllowed = async (
   user: { provider: "local" | "ipa"; profile: "guest" | "user" },
   db: typeof sql = sql,

package/src/services/account-lifecycle/audit.ts

@@ -35,7 +35,7 @@ export const writeDeletedAccountAudit = async (config: {
       ${config.previousProvider},
       ${config.previousProfile},
       ${config.reason},
-      ${JSON.stringify(config.meta ?? {})}::jsonb
+      ${JSON.stringify(config.meta ?? {})}::text::jsonb
     )
   `;
 };

package/src/services/accounts/app.ts

@@ -37,6 +37,7 @@ import { listDuplicateEmails } from "./duplicate-emails";
 import * as entities from "./entities";
 import * as groups from "./groups";
 import type { AccountsNotificationSender } from "./notification-sender";
+import { PosixError } from "./posix";
 import { accountRequestsEnabled } from "./request-policy";
 import * as users from "./users";
 
@@ -141,6 +142,15 @@ const fromMutationResult = <T>(result: MutationResult<T>): Result<T> => {
   return fail(toServiceError(result.status, result.error));
 };
 
+const fromGroupMutation = async <T>(operation: () => Promise<MutationResult<T>>): Promise<Result<T>> => {
+  try {
+    return fromMutationResult(await operation());
+  } catch (error) {
+    if (error instanceof PosixError) return fail({ code: error.code, message: error.message, status: error.status });
+    throw error;
+  }
+};
+
 const mapAccountRequestRow = (row: DbRow): AccountRequest => ({
   id: row.id as string,
   userId: row.user_id as string | null,
@@ -1119,7 +1129,7 @@ export const accountsAppService = {
         target: { type: "group", label: config.name, provider: config.provider },
       });
       if (adminError) return adminError;
-      const result = fromMutationResult(await groups.create(config));
+      const result = await fromGroupMutation(() => groups.create(config));
       return recordCompletedMutation({
         action: "accounts.group.create",
         actor: auditActor(config.actor),
@@ -1164,7 +1174,7 @@ export const accountsAppService = {
         target,
       });
       if (adminError) return adminError;
-      const result = fromMutationResult(await groups.makePosix(config));
+      const result = await fromGroupMutation(() => groups.makePosix(config));
       return recordCompletedMutation({
         action: "accounts.group.make_posix",
         actor: auditActor(config.actor),

package/src/services/accounts/email-write.ts

@@ -0,0 +1,23 @@
+import type { sql } from "bun";
+
+export const normalizeAccountEmail = (email: string): string => email.trim().toLowerCase();
+
+/** Hold through the write (including a FreeIPA mutation), on the same transaction. */
+export const lockAccountEmail = async (db: typeof sql, email: string): Promise<void> => {
+  // Take the table's ordinary write lock before the advisory lock. Local POSIX
+  // provisioning takes a stronger table lock first; this keeps their order compatible.
+  await db`LOCK TABLE auth.users IN ROW EXCLUSIVE MODE`;
+  await db`SELECT pg_advisory_xact_lock(hashtextextended('cloud:account-email:' || ${normalizeAccountEmail(email)}, 0))`;
+};
+
+export const findAccountsByEmail = (db: typeof sql, email: string) =>
+  db<
+    {
+      id: string;
+      uid: string;
+      provider: "local" | "ipa";
+      mail: string;
+    }[]
+  >`SELECT id, uid, provider, mail FROM auth.users WHERE lower(btrim(mail)) = ${normalizeAccountEmail(email)}`;
+
+export const emailAlreadyUsed = () => ({ ok: false as const, error: "An account with this email already exists.", status: 409 as const });

package/src/services/accounts/groups.ts

@@ -4,9 +4,11 @@ import { freeipa } from "../../server/services";
 import { getServiceIpaSession } from "../ipa/service-account";
 import { toPgUuidArray } from "../postgres";
 import { providers } from "../providers";
+import type { AccountsActor } from "./authz";
 import { buildBaseGroup } from "./base-group";
 import { buildManagedGroupScopeCondition, buildMemberGroupScopeCondition } from "./group-sql";
 import * as localGroups from "./local-groups";
+import { posix } from "./posix";
 
 type DbRow = Record<string, unknown>;
 
@@ -146,13 +148,14 @@ export const getManagedGroups = async (params: { id: string; provider?: UserProv
 };
 
 export const create = async (params: {
+  actor: AccountsActor;
   provider: UserProvider;
   name: string;
   description?: string;
   posix?: boolean;
 }): Promise<MutationResult<BaseGroup>> => {
   if (params.provider === "local") {
-    if (params.posix) return { ok: false, error: "Local groups do not support POSIX mode", status: 400 };
+    if (params.posix) return { ok: true, data: await posix.createGroup({ id: params.actor.userId, roles: params.actor.roles }, params) };
     return localGroups.create({ name: params.name, description: params.description });
   }
   const serviceSession = await getServiceIpaSession();
@@ -188,9 +191,17 @@ export const remove = async (params: { id: string; provider?: UserProvider }): P
   });
 };
 
-export const makePosix = async (params: { id: string; provider?: UserProvider }): Promise<MutationResult<{ gidnumber: number | null }>> => {
-  const provider = params.provider ?? (await getGroup(params.id))?.provider;
-  if (provider === "local") return { ok: false, error: "Local groups do not support POSIX mode", status: 400 };
+export const makePosix = async (params: {
+  actor: AccountsActor;
+  id: string;
+  provider?: UserProvider;
+}): Promise<MutationResult<{ gidnumber: number | null }>> => {
+  const provider = (await getGroup(params.id))?.provider;
+  if (!provider) return { ok: false, error: "Group not found", status: 404 };
+  if (provider === "local") {
+    const result = await posix.provisionGroup({ id: params.actor.userId, roles: params.actor.roles }, params.id);
+    return { ok: true, data: { gidnumber: result.gidNumber } };
+  }
   const serviceSession = await getServiceIpaSession();
   if (!serviceSession.ok) return serviceSession;
   return providers.ipa.groups.makePosix({

package/src/services/accounts/identities.ts

@@ -0,0 +1,249 @@
+import { type SQLQuery, sql } from "bun";
+import { z } from "zod";
+import { DEFAULT_LINUX_IDENTITY_CONFIGURATION, LinuxIdentityConfigurationSchema } from "../../contracts/posix";
+import type { RequestActor, UserProfile, UserProvider } from "../../contracts/shared";
+import { userFromActor } from "../../server/actor";
+import { isAccountCategoryAllowed } from "../account-category-policy";
+import { toPgTextArray } from "../postgres";
+import { decryptValue } from "../settings/crypto";
+import { buildMemberGroupScopeCondition } from "./group-sql";
+import { type AccountIdentityReconciliation, readUpstreamIdentity } from "./identity-reconciliation";
+
+export type AccountIdentityUser = {
+  id: string;
+  provider: UserProvider;
+  username: string;
+  profile: UserProfile;
+  posix: { uidNumber: number; primaryGidNumber: number } | null;
+};
+export type AccountIdentityGroup = { id: string; provider: UserProvider; name: string; gidNumber: number | null };
+export type AccountIdentityPage<T> = { items: T[]; nextCursor: string | null };
+export type AccountIdentityAvailability = { localLinuxEnabled: boolean; freeipaEnabled: boolean };
+type InventoryFilter = { provider: UserProvider; after?: string; id?: string; name?: string };
+
+export class AccountIdentityError extends Error {
+  constructor(
+    public readonly code: string,
+    public readonly status: 400 | 401 | 403 = 403,
+  ) {
+    super(code);
+  }
+}
+
+// The same bounded page size as Linux identity administration.
+const PAGE_SIZE = 50;
+const cursorSchema = z.uuid();
+const positiveId = (value: number | null): value is number => Number.isSafeInteger(value) && value !== null && value > 0;
+type UserRow = {
+  id: string;
+  provider: UserProvider;
+  uid: string;
+  profile: UserProfile;
+  admin: boolean;
+  expired: boolean;
+  managed_by: UserProvider | null;
+  uid_number: number | null;
+  primary_gid_number: number | null;
+};
+const projectUser = (row: UserRow): AccountIdentityUser => ({
+  id: row.id,
+  provider: row.provider,
+  username: row.uid,
+  profile: row.profile,
+  posix:
+    row.managed_by === row.provider && positiveId(row.uid_number) && positiveId(row.primary_gid_number)
+      ? { uidNumber: row.uid_number, primaryGidNumber: row.primary_gid_number }
+      : null,
+});
+const page = <T extends { id: string }>(rows: T[]): AccountIdentityPage<T> => ({
+  items: rows.slice(0, PAGE_SIZE),
+  nextCursor: rows.length > PAGE_SIZE ? rows[PAGE_SIZE - 1]!.id : null,
+});
+const cursor = (after?: string): string | null => {
+  if (after !== undefined && !cursorSchema.safeParse(after).success) throw new AccountIdentityError("invalid_cursor", 400);
+  return after ?? null;
+};
+
+/** Server-side identity reads. Authentication and application resource authorization remain caller-owned. */
+export const createAccountIdentityService = (db: typeof sql = sql, upstreamIdentity = readUpstreamIdentity) => {
+  const setting = async (key: string, fallback: unknown): Promise<unknown> => {
+    const [row] = await db<{ value: string }[]>`SELECT value FROM settings.entries WHERE key = ${key}`;
+    return row ? decryptValue(row.value) : fallback;
+  };
+  const availability = async (): Promise<AccountIdentityAvailability> => {
+    const [raw, ipa] = await Promise.all([
+      setting("linux.identity_config", DEFAULT_LINUX_IDENTITY_CONFIGURATION),
+      setting("freeipa.enable", false),
+    ]);
+    try {
+      const config = LinuxIdentityConfigurationSchema.parse(typeof raw === "string" ? JSON.parse(raw) : raw);
+      if (typeof ipa !== "boolean") throw new Error("Invalid FreeIPA state");
+      return { localLinuxEnabled: config.enabled, freeipaEnabled: ipa };
+    } catch {
+      throw new AccountIdentityError("invalid_identity_configuration");
+    }
+  };
+  const userRows = (filter: SQLQuery) => db<UserRow[]>`
+    SELECT u.id, u.provider, u.uid, u.profile, u.admin,
+      (u.account_expires IS NOT NULL AND u.account_expires <= now()) AS expired,
+      p.managed_by, p.uid_number, p.primary_gid_number
+    FROM auth.users u LEFT JOIN auth.user_posix p ON p.user_id = u.id
+    WHERE ${filter}
+    ORDER BY u.id LIMIT ${PAGE_SIZE + 1}
+  `;
+  const requireUser = async (actor: RequestActor) => {
+    const supplied = userFromActor(actor);
+    if (!supplied) throw new AccountIdentityError("user_required", 401);
+    const [row] = await userRows(sql`u.id = ${supplied.id}::uuid`);
+    if (!row || row.expired || row.provider !== supplied.provider || row.uid !== supplied.uid || row.profile !== supplied.profile)
+      throw new AccountIdentityError("identity_unavailable");
+    if (!(await isAccountCategoryAllowed(row, db))) throw new AccountIdentityError("identity_unavailable");
+    const state = await availability();
+    if (row.provider === "ipa" && !state.freeipaEnabled) throw new AccountIdentityError("identity_unavailable");
+    return { row, state, supplied };
+  };
+  const requireAdmin = async (actor: RequestActor) => {
+    const current = await requireUser(actor);
+    if (!current.supplied.roles.includes("admin")) throw new AccountIdentityError("admin_required");
+    if (current.row.provider === "local") {
+      if (!current.row.admin || current.row.profile !== "user") throw new AccountIdentityError("admin_required");
+    } else {
+      const configured = await setting("freeipa.groups.admin", ["admins"]);
+      if (!Array.isArray(configured) || !configured.every((value): value is string => typeof value === "string"))
+        throw new AccountIdentityError("invalid_identity_configuration");
+      const names = configured.length > 0 ? configured : ["admins"];
+      const [membership] = await db`SELECT 1 FROM auth.ipa_user_effective_groups
+        WHERE user_id = ${current.row.id}::uuid AND group_name = ANY(${toPgTextArray(names)}::text[]) LIMIT 1`;
+      if (!membership) throw new AccountIdentityError("admin_required");
+    }
+    return current;
+  };
+  const groupRows = async (filter: SQLQuery) => {
+    const rows = await db<{ id: string; provider: UserProvider; name: string; gid_number: number | null }[]>`
+      SELECT g.id, g.provider, g.name, g.gid_number FROM auth.groups g
+      WHERE ${filter} ORDER BY g.id LIMIT ${PAGE_SIZE + 1}
+    `;
+    return rows.map(
+      (row): AccountIdentityGroup => ({
+        id: row.id,
+        provider: row.provider,
+        name: row.name,
+        gidNumber: positiveId(row.gid_number) ? row.gid_number : null,
+      }),
+    );
+  };
+  async function inventory(
+    actor: RequestActor,
+    options: InventoryFilter & { kind: "users" },
+  ): Promise<AccountIdentityPage<AccountIdentityUser>>;
+  async function inventory(
+    actor: RequestActor,
+    options: InventoryFilter & { kind: "groups" },
+  ): Promise<AccountIdentityPage<AccountIdentityGroup>>;
+  async function inventory(actor: RequestActor, options: InventoryFilter & { kind: "users" | "groups" }) {
+    await requireAdmin(actor);
+    const after = cursor(options.after);
+    const id = cursor(options.id);
+    const name = options.name ?? null;
+    if (options.provider !== "local" && options.provider !== "ipa") throw new AccountIdentityError("invalid_provider", 400);
+    if (options.kind === "users") {
+      return page(
+        (
+          await userRows(sql`u.provider = ${options.provider} AND (${after}::uuid IS NULL OR u.id > ${after}::uuid)
+        AND (${id}::uuid IS NULL OR u.id = ${id}::uuid) AND (${name}::text IS NULL OR u.uid = ${name})`)
+        ).map(projectUser),
+      );
+    }
+    if (options.kind !== "groups") throw new AccountIdentityError("invalid_inventory_kind", 400);
+    return page(
+      await groupRows(sql`g.provider = ${options.provider} AND (${after}::uuid IS NULL OR g.id > ${after}::uuid)
+      AND (${id}::uuid IS NULL OR g.id = ${id}::uuid) AND (${name}::text IS NULL OR g.name = ${name})`),
+    );
+  }
+  const readLocalIdentity = async (input: {
+    kind: "users" | "groups";
+    name: string;
+    identityId?: string;
+  }): Promise<AccountIdentityReconciliation> => {
+    if (input.kind === "users") {
+      const rows = await userRows(sql`(u.provider = 'local' AND u.uid = ${input.name}) OR u.id = ${input.identityId ?? null}::uuid`);
+      const expected = rows.find((row) => row.id === input.identityId);
+      if (expected && (expected.provider !== "local" || expected.uid !== input.name))
+        return { state: "unknown", reason: "identity_conflict" };
+      const matches = rows.filter((row) => row.provider === "local" && row.uid === input.name);
+      if (!matches.length) return { state: "absent" };
+      if (matches.length !== 1) return { state: "unknown", reason: "invalid_response" };
+      const current = projectUser(matches[0]!);
+      return {
+        state: "present",
+        identity: {
+          id: current.id,
+          name: current.username,
+          uidNumber: current.posix?.uidNumber ?? null,
+          gidNumber: current.posix?.primaryGidNumber ?? null,
+        },
+        eligible: current.profile === "user",
+      };
+    }
+    const rows = await groupRows(sql`(g.provider = 'local' AND g.name = ${input.name}) OR g.id = ${input.identityId ?? null}::uuid`);
+    const expected = rows.find((row) => row.id === input.identityId);
+    if (expected && (expected.provider !== "local" || expected.name !== input.name))
+      return { state: "unknown", reason: "identity_conflict" };
+    const matches = rows.filter((row) => row.provider === "local" && row.name === input.name);
+    if (!matches.length) return { state: "absent" };
+    if (matches.length !== 1) return { state: "unknown", reason: "invalid_response" };
+    const current = matches[0]!;
+    return {
+      state: "present",
+      identity: { id: current.id, name: current.name, uidNumber: null, gidNumber: current.gidNumber },
+      eligible: current.gidNumber !== null,
+    };
+  };
+  const validateLookup = (input: { kind: "users" | "groups"; name: string }) => {
+    if ((input.kind !== "users" && input.kind !== "groups") || typeof input.name !== "string" || !input.name || input.name.includes("\0"))
+      throw new AccountIdentityError("invalid_identity_lookup", 400);
+  };
+  return {
+    async reconcile(
+      actor: RequestActor,
+      input: { kind: "users" | "groups"; provider: UserProvider; name: string; identityId?: string; signal?: AbortSignal },
+    ): Promise<AccountIdentityReconciliation> {
+      const { state } = await requireAdmin(actor);
+      validateLookup(input);
+      if (input.provider !== "local" && input.provider !== "ipa") throw new AccountIdentityError("invalid_identity_lookup", 400);
+      if (input.identityId !== undefined) cursor(input.identityId);
+      if (input.signal?.aborted) return { state: "unknown", reason: "provider_unavailable" };
+      if (input.provider === "ipa") {
+        if (!state.freeipaEnabled) return { state: "unknown", reason: "provider_disabled" };
+        return upstreamIdentity(input);
+      }
+      const result = await readLocalIdentity(input);
+      return input.signal?.aborted ? { state: "unknown", reason: "provider_unavailable" } : result;
+    },
+    /** Trusted application jobs only; this read does not authorize an HTTP caller or a filesystem mutation. */
+    async localLifecycle(input: { kind: "users" | "groups"; identityId: string; name: string }) {
+      validateLookup(input);
+      cursor(input.identityId);
+      const { localLinuxEnabled } = await availability();
+      return { localLinuxEnabled, identity: await readLocalIdentity(input) };
+    },
+    async self(actor: RequestActor) {
+      const { row, state } = await requireUser(actor);
+      return { user: projectUser(row), availability: state };
+    },
+    async groups(actor: RequestActor, options: { after?: string } = {}): Promise<AccountIdentityPage<AccountIdentityGroup>> {
+      const { row, state } = await requireUser(actor);
+      const after = cursor(options.after);
+      return page(
+        await groupRows(sql`
+        (${after}::uuid IS NULL OR g.id > ${after}::uuid)
+        AND (g.provider = 'local' OR ${state.freeipaEnabled})
+        AND ${buildMemberGroupScopeCondition({ userId: row.id, groupProvider: sql`g.provider` })}
+      `),
+      );
+    },
+    inventory,
+  };
+};
+
+export const accountIdentities = createAccountIdentityService();

package/src/services/accounts/identity-reconciliation.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import { freeipa } from "../../server/services";
+import type { IpaRpcResponse } from "../../server/services/freeipa/client";
+import { FREEIPA_REQUEST_TIMEOUT_MS } from "../../server/services/freeipa/transport";
+import { getFreeIpaConfig } from "../freeipa-config";
+
+export type AccountIdentityReconciliation =
+  | {
+      state: "present";
+      identity: { id: string | null; name: string; uidNumber: number | null; gidNumber: number | null };
+      eligible: boolean;
+    }
+  | { state: "absent" }
+  | { state: "unknown"; reason: "provider_disabled" | "provider_unavailable" | "invalid_response" | "identity_conflict" };
+export type IdentityLookup = { kind: "users" | "groups"; name: string; signal?: AbortSignal };
+
+const number = z
+  .union([z.number().int(), z.string().regex(/^\d+$/).transform(Number)])
+  .pipe(z.number().int().positive().max(2_147_483_647));
+const attributeNumber = z.array(number).length(1).optional();
+const userRecord = z.object({ uid: z.array(z.string()).length(1), uidnumber: attributeNumber, gidnumber: attributeNumber });
+const groupRecord = z.object({ cn: z.array(z.string()).length(1), gidnumber: attributeNumber });
+const notFound = (response: IpaRpcResponse) =>
+  response.error?.kind === "rpc" && response.error.code === 4001 && response.error.name === "NotFound";
+
+// Exact show responses have no pagination or Cloud sync filter. Only the named
+// upstream NotFound error proves absence; HTTP 404 and malformed success do not.
+export function parseIdentityShow(input: IdentityLookup, response: IpaRpcResponse): AccountIdentityReconciliation {
+  if (notFound(response)) return { state: "absent" };
+  if (response.error)
+    return { state: "unknown", reason: response.error.kind === "invalid_response" ? "invalid_response" : "provider_unavailable" };
+  const parsed = input.kind === "users" ? userRecord.safeParse(response.result?.result) : groupRecord.safeParse(response.result?.result);
+  if (!parsed.success) return { state: "unknown", reason: "invalid_response" };
+  const record = parsed.data;
+  const name = "uid" in record ? record.uid[0]! : record.cn[0]!;
+  if (name !== input.name) return { state: "unknown", reason: "invalid_response" };
+  const uidNumber = "uidnumber" in record ? (record.uidnumber?.[0] ?? null) : null;
+  const gidNumber = record.gidnumber?.[0] ?? null;
+  return {
+    state: "present",
+    identity: { id: null, name, uidNumber, gidNumber },
+    eligible: gidNumber !== null && (input.kind === "groups" || uidNumber !== null),
+  };
+}
+
+export const readUpstreamIdentity = async (
+  input: IdentityLookup,
+  deps = { config: getFreeIpaConfig, session: freeipa.session.getServiceSession, call: freeipa.client.call },
+): Promise<AccountIdentityReconciliation> => {
+  try {
+    const timeout = AbortSignal.timeout(FREEIPA_REQUEST_TIMEOUT_MS);
+    const signal = input.signal ? AbortSignal.any([input.signal, timeout]) : timeout;
+    signal.throwIfAborted();
+    const config = await deps.config();
+    signal.throwIfAborted();
+    if (!config.enabled) return { state: "unknown", reason: "provider_disabled" };
+    if (!config.configured) return { state: "unknown", reason: "provider_unavailable" };
+    const ipaSession = await deps.session({
+      url: config.url,
+      serviceUser: config.serviceUser,
+      servicePassword: config.servicePassword,
+      signal,
+    });
+    signal.throwIfAborted();
+    const query = async (method: string) => {
+      signal.throwIfAborted();
+      const response = await deps.call({
+        url: config.url,
+        ipaSession,
+        method,
+        args: [input.name],
+        options: { all: true, no_members: true },
+        signal,
+      });
+      signal.throwIfAborted();
+      return response;
+    };
+    const result = parseIdentityShow(input, await query(input.kind === "users" ? "user_show" : "group_show"));
+    if (input.kind !== "users" || result.state !== "absent") return result;
+    // user_show includes preserved users, but staged users live in a separate
+    // container and can retain a former account's data while awaiting activation.
+    const staged = parseIdentityShow(input, await query("stageuser_show"));
+    return staged.state === "present" ? { ...staged, eligible: false } : staged;
+  } catch {
+    return { state: "unknown", reason: "provider_unavailable" };
+  }
+};

package/src/services/accounts/ipa-data.ts

@@ -3,9 +3,9 @@ import type { IpaUserData } from "../../contracts/shared";
 
 type DbRow = Record<string, unknown>;
 
-export const userIpaDataJoin = sql`LEFT JOIN auth.user_ipa_data ui ON ui.user_id = u.id`;
+export const userIpaDataJoin = () => sql`LEFT JOIN auth.user_ipa_data ui ON ui.user_id = u.id`;
 
-export const userIpaDataColumns = sql`
+export const userIpaDataColumns = () => sql`
   CASE WHEN EXISTS(SELECT 1 FROM auth.user_posix p WHERE p.user_id = u.id AND p.managed_by = 'ipa')
     THEN (SELECT p.uid_number FROM auth.user_posix p WHERE p.user_id = u.id AND p.managed_by = 'ipa')
     ELSE ui.uid_number END AS ipa_uid_number,

package/src/services/accounts/local-groups.ts

@@ -77,10 +77,10 @@ export const get = async (params: { id: string }): Promise<BaseGroup | null> =>
   return row ? toBaseGroup(row) : null;
 };
 
-export const create = async (params: { name: string; description?: string }): Promise<MutationResult<BaseGroup>> => {
+export const create = async (params: { name: string; description?: string }, db: typeof sql = sql): Promise<MutationResult<BaseGroup>> => {
   const storedCn = `local:${params.name}`;
   try {
-    const rows = await sql<DbRow[]>`
+    const rows = await db<DbRow[]>`
       INSERT INTO auth.groups (id, cn, provider, name, description, synced_at)
       VALUES (gen_random_uuid(), ${storedCn}, 'local', ${params.name}, ${params.description ?? null}, now())
       RETURNING id, provider, name, description, gid_number