@k2b/cloud 0.6.0-rc.0

package/src/services/identity/session-token.ts

@@ -0,0 +1,152 @@
+import { createRemoteJWKSet, decodeProtectedHeader, errors, type JWTVerifyGetKey, jwtVerify, SignJWT } from "jose";
+import { z } from "zod";
+import {
+  CLOUD_IDENTITY_ALGORITHM,
+  CLOUD_SESSION_AUDIENCE,
+  CLOUD_SESSION_TOKEN_TYPE,
+  IDENTITY_CLOCK_TOLERANCE_SECONDS,
+  IDENTITY_JWKS_MAX_AGE_SECONDS,
+  IDENTITY_MAX_COMPACT_TOKEN_BYTES,
+} from "./constants";
+import type { PreparedIdentitySigner } from "./key-ring";
+import { prepareIdentitySigner } from "./key-ring";
+import { identityMetrics } from "./metrics";
+import { getIdentityRuntimeConfig } from "./runtime-config";
+
+const SessionPayloadSchema = z
+  .object({
+    iss: z.string().url(),
+    aud: z.literal(CLOUD_SESSION_AUDIENCE),
+    token_use: z.literal("session"),
+    sub: z.string().uuid(),
+    sid: z.string().uuid(),
+    auth_epoch: z.number().int().nonnegative(),
+    iat: z.number().int().nonnegative(),
+    exp: z.number().int().positive(),
+  })
+  .strict();
+
+export type CloudSessionClaims = z.infer<typeof SessionPayloadSchema>;
+
+type RemoteSetState = { key: JWTVerifyGetKey; lastForcedRefreshAt: number };
+const remoteSets = new Map<string, RemoteSetState>();
+
+const createRemoteSet = (url: URL): JWTVerifyGetKey =>
+  createRemoteJWKSet(url, {
+    cacheMaxAge: IDENTITY_JWKS_MAX_AGE_SECONDS * 1_000,
+    cooldownDuration: 30_000,
+    timeoutDuration: 5_000,
+  });
+
+const remoteSet = (url: URL): RemoteSetState => {
+  const key = url.href;
+  const existing = remoteSets.get(key);
+  if (existing) return existing;
+  const created = { key: createRemoteSet(url), lastForcedRefreshAt: 0 };
+  remoteSets.set(key, created);
+  return created;
+};
+
+const assertProtectedHeader = (header: ReturnType<typeof decodeProtectedHeader>): void => {
+  const names = Object.keys(header).sort();
+  if (names.join(",") !== "alg,kid,typ") throw new Error("Cloud session JWT has an unsupported protected header");
+  if (header.alg !== CLOUD_IDENTITY_ALGORITHM || header.typ !== CLOUD_SESSION_TOKEN_TYPE) {
+    throw new Error("Cloud session JWT uses the wrong algorithm or token type");
+  }
+  if (typeof header.kid !== "string" || !/^[0-9a-f-]{36}$/.test(header.kid)) {
+    throw new Error("Cloud session JWT has an invalid key id");
+  }
+};
+
+export const isSessionJwtCandidate = (token: string): boolean => {
+  if (new TextEncoder().encode(token).byteLength > IDENTITY_MAX_COMPACT_TOKEN_BYTES) return false;
+  try {
+    const header = decodeProtectedHeader(token);
+    return header.typ === CLOUD_SESSION_TOKEN_TYPE;
+  } catch {
+    return false;
+  }
+};
+
+export const signSessionToken = async (params: {
+  userId: string;
+  sid: string;
+  authEpoch: number;
+  issuedAt: Date;
+  expiresAt: Date;
+  signer?: PreparedIdentitySigner;
+}): Promise<{ token: string; kid: string }> => {
+  const { issuer } = await getIdentityRuntimeConfig();
+  const signer = params.signer ?? (await prepareIdentitySigner("session"));
+  if (params.expiresAt.getTime() <= params.issuedAt.getTime()) throw new Error("Cloud session expiry must follow issuance");
+  try {
+    const token = await new SignJWT({ token_use: "session", sid: params.sid, auth_epoch: params.authEpoch })
+      .setProtectedHeader({ alg: CLOUD_IDENTITY_ALGORITHM, typ: CLOUD_SESSION_TOKEN_TYPE, kid: signer.kid })
+      .setIssuer(issuer)
+      .setAudience(CLOUD_SESSION_AUDIENCE)
+      .setSubject(params.userId)
+      .setIssuedAt(Math.floor(params.issuedAt.getTime() / 1_000))
+      .setExpirationTime(Math.floor(params.expiresAt.getTime() / 1_000))
+      .sign(signer.key);
+    if (new TextEncoder().encode(token).byteLength > IDENTITY_MAX_COMPACT_TOKEN_BYTES) {
+      throw new Error("Generated Cloud session JWT exceeds 4 KiB");
+    }
+    identityMetrics.increment("sign_success");
+    return { token, kid: signer.kid };
+  } catch (error) {
+    identityMetrics.increment("sign_failure");
+    throw error;
+  }
+};
+
+export const verifySessionToken = async (
+  token: string,
+  options: { issuer?: string; key?: JWTVerifyGetKey; jwksUrl?: URL; now?: Date } = {},
+): Promise<CloudSessionClaims | null> => {
+  if (new TextEncoder().encode(token).byteLength > IDENTITY_MAX_COMPACT_TOKEN_BYTES) return null;
+  let remote: { url: URL; state: RemoteSetState } | null = null;
+  try {
+    const runtime = options.issuer && (options.key || options.jwksUrl) ? null : await getIdentityRuntimeConfig();
+    const issuer = options.issuer ?? runtime!.issuer;
+    const jwksUrl = options.jwksUrl ?? runtime?.sessionJwksUrl;
+    const state = options.key || !jwksUrl ? null : remoteSet(jwksUrl);
+    if (state && jwksUrl) remote = { url: jwksUrl, state };
+    let key = options.key ?? state?.key;
+    if (!key) throw new Error("Cloud session verifier has no public key source");
+    assertProtectedHeader(decodeProtectedHeader(token));
+    const verify = (candidate: JWTVerifyGetKey) =>
+      jwtVerify(token, candidate, {
+        algorithms: [CLOUD_IDENTITY_ALGORITHM],
+        audience: CLOUD_SESSION_AUDIENCE,
+        issuer,
+        typ: CLOUD_SESSION_TOKEN_TYPE,
+        clockTolerance: IDENTITY_CLOCK_TOLERANCE_SECONDS,
+        currentDate: options.now,
+      });
+    let verified: Awaited<ReturnType<typeof jwtVerify>>;
+    try {
+      verified = await verify(key);
+    } catch (error) {
+      if (!(error instanceof errors.JWKSNoMatchingKey) || !remote) throw error;
+      const now = Date.now();
+      if (now - remote.state.lastForcedRefreshAt < 30_000) throw error;
+      remote.state.lastForcedRefreshAt = now;
+      identityMetrics.increment("unknown_kid_refresh");
+      key = createRemoteSet(remote.url);
+      verified = await verify(key);
+      remote.state.key = key;
+    }
+    const parsed = SessionPayloadSchema.safeParse(verified.payload);
+    if (!parsed.success || parsed.data.exp <= parsed.data.iat) throw new Error("Cloud session JWT claims are invalid");
+    identityMetrics.increment("verify_success");
+    return parsed.data;
+  } catch (error) {
+    if (error instanceof errors.JWKSNoMatchingKey && !remote) identityMetrics.increment("unknown_kid_refresh");
+    identityMetrics.increment("verify_failure");
+    return null;
+  }
+};
+
+export const clearSessionVerifierCachesForTest = (): void => {
+  remoteSets.clear();
+};

package/src/services/identity/signer-refresh.ts

@@ -0,0 +1,44 @@
+type Flight<Value> = {
+  generation: number;
+  promise: Promise<Value>;
+};
+
+/** Coalesces refreshes while preventing invalidated work from committing. */
+export class SignerRefreshes<Key, Value> {
+  readonly #flights = new Map<Key, Flight<Value>>();
+  readonly #generations = new Map<Key, number>();
+
+  run(key: Key, refresh: () => Promise<Value>, commit: (value: Value) => void): Promise<Value> {
+    const generation = this.#generations.get(key) ?? 0;
+    const current = this.#flights.get(key);
+    if (current?.generation === generation) return current.promise;
+
+    const flight: Flight<Value> = {
+      generation,
+      promise: Promise.resolve()
+        .then(refresh)
+        .then((value) => {
+          if ((this.#generations.get(key) ?? 0) !== generation) {
+            throw new Error("Cloud identity signer refresh was invalidated");
+          }
+          commit(value);
+          return value;
+        }),
+    };
+    this.#flights.set(key, flight);
+    const cleanup = () => {
+      if (this.#flights.get(key) === flight) this.#flights.delete(key);
+    };
+    void flight.promise.then(cleanup, cleanup);
+    return flight.promise;
+  }
+
+  invalidate(key: Key): void {
+    this.#generations.set(key, (this.#generations.get(key) ?? 0) + 1);
+    this.#flights.delete(key);
+  }
+
+  invalidateAll(): void {
+    for (const key of new Set([...this.#generations.keys(), ...this.#flights.keys()])) this.invalidate(key);
+  }
+}

package/src/services/identity/workload-auth.ts

@@ -0,0 +1,64 @@
+import { type AuthenticatedServiceAccountCredential, serviceAccountCredentials } from "../service-account-credentials";
+
+export const WORKLOAD_SCOPES = ["identity:invoke"] as const;
+
+export type WorkloadScope = (typeof WORKLOAD_SCOPES)[number];
+
+export type AuthenticatedWorkload = {
+  appId: string;
+  serviceAccountId: string;
+  credentialId: string;
+  scope: WorkloadScope;
+};
+
+type WorkloadCredentialAuthenticator = Pick<typeof serviceAccountCredentials, "isApiToken" | "authenticateApiToken">;
+
+const workloadScopes = new Set<string>(WORKLOAD_SCOPES);
+
+// Retired OAuth credentials must not become ordinary API keys after the hard cut.
+export const hasReservedWorkloadScope = (scopes: readonly string[]): boolean =>
+  scopes.some((scope) => workloadScopes.has(scope) || scope === "identity:oauth-issue");
+
+export const isReservedWorkloadApiCredential = (authenticated: AuthenticatedServiceAccountCredential): boolean =>
+  authenticated.serviceAccount.kind === "resource_bound" && hasReservedWorkloadScope(authenticated.credential.scopes);
+
+/** Resolve one app workload credential without exposing or retaining its raw token. */
+export const authenticateWorkloadCredential = async (params: {
+  token: string | null | undefined;
+  appId: string;
+  scope: WorkloadScope;
+  credentials?: WorkloadCredentialAuthenticator;
+}): Promise<AuthenticatedWorkload | null> => {
+  const appId = params.appId;
+  if (!appId || appId !== appId.trim() || !workloadScopes.has(params.scope)) return null;
+
+  const credentials = params.credentials ?? serviceAccountCredentials;
+  if (!params.token || !credentials.isApiToken(params.token)) return null;
+
+  const authenticated: AuthenticatedServiceAccountCredential | null = await credentials.authenticateApiToken(params.token);
+  if (!authenticated) return null;
+
+  const { credential, serviceAccount } = authenticated;
+  if (
+    credential.kind !== "api_token" ||
+    credential.status !== "active" ||
+    credential.serviceAccountId !== serviceAccount.id ||
+    serviceAccount.status !== "active" ||
+    serviceAccount.kind !== "resource_bound" ||
+    serviceAccount.delegatedUserId !== null ||
+    authenticated.delegatedUser !== null ||
+    serviceAccount.appId !== appId ||
+    serviceAccount.resourceType !== "cloud.app" ||
+    serviceAccount.resourceId !== appId ||
+    !credential.scopes.includes(params.scope)
+  ) {
+    return null;
+  }
+
+  return {
+    appId,
+    serviceAccountId: serviceAccount.id,
+    credentialId: credential.id,
+    scope: params.scope,
+  };
+};

package/src/services/index.ts

@@ -0,0 +1,187 @@
+// biome-ignore-all assist/source/organizeImports: Preserve grouped service barrel exports.
+export { ipa } from "./ipa";
+export { accounts } from "./accounts";
+export { accountsAppService } from "./accounts";
+export { posix as linuxIdentities, PosixError } from "./accounts/posix";
+export type { PosixCandidate } from "./accounts/posix";
+export { providers } from "./providers";
+export { authFlows } from "./auth-flows";
+export { toPgIntArray, toPgTextArray, toPgUuidArray, escapeLikePattern, isUniqueViolation } from "./postgres";
+
+export { logger, logging, TRACE_STUCK_AFTER_MS, trace } from "./logging";
+export {
+  createRuntimeLifecycle,
+  createRuntimeTaskTracker,
+  stopRuntimeJobs,
+  stopRuntimeResources,
+  superviseRuntimeTask,
+} from "./runtime-lifecycle";
+export type { RuntimeTaskFailure, RuntimeTaskTracker } from "./runtime-lifecycle";
+export type {
+  LogEntry,
+  TraceAttributeValue,
+  TraceAttributes,
+  TraceCategory,
+  TraceContext,
+  TraceEvent,
+  TraceListFilter,
+  TraceRunStats,
+  TraceSeverity,
+  TraceSpan,
+  TraceSpanKind,
+  TraceSourceGroup,
+  TraceStatus,
+  TraceSummary,
+  TraceWindow,
+} from "./logging";
+export { audit } from "./audit";
+export type { AuditActionGroup, AuditActor, AuditEvent, AuditListFilter, AuditOutcome, AuditRecordParams, AuditTarget } from "./audit";
+
+export {
+  GATEWAY_TELEMETRY_TENANT,
+  ROUTE_TEMPLATE_HEADER,
+  buildGatewayRouteSnapshot,
+  gatewayTelemetryTopic,
+  latestGatewayRouteSnapshot,
+  listGatewayRouteSnapshots,
+  publishGatewayRouteSnapshot,
+  publishRequestTelemetry,
+  removeGatewayRouteSnapshot,
+} from "./gateway";
+export type { GatewayRouteSnapshot, GatewayRouteSnapshotInput, GatewayRouteWarning, GatewayTelemetryEvent } from "./gateway";
+
+export { notificationBatches, notifications } from "./notifications";
+export { registerNotificationChannel } from "./notifications/channels";
+export { startNotificationRuntime, stopNotificationRuntime } from "./notifications/runtime";
+export { browserNotifications } from "./notifications/browser";
+export type {
+  NotificationBatch,
+  NotificationBatchPreview,
+  NotificationBatchRecipient,
+  NotificationBatchRecipientStatus,
+  NotificationBatchSelection,
+  NotificationBatchStatus,
+  NotificationType,
+  NotificationStatus,
+  SendNotificationParams,
+  SendToUserParams,
+  NotificationMessage,
+} from "./notifications";
+export type { NotificationChannelDriver } from "./notifications/channels";
+export type { TypedNotificationDeliveryStatus, TypedNotificationSendResult } from "./notifications/platform";
+export { announcements } from "./announcements";
+export type { AnnouncementsService } from "./announcements";
+
+export { session } from "./session";
+export { mandateMetrics, mandates, startMandateMaintenance } from "./mandates";
+export type {
+  Mandate,
+  MandateInteractiveAuthority,
+  MandateIssueAuthority,
+  MandateListScope,
+  MandateMetricName,
+  MandateMutationAuthority,
+  MandatePolicyV1,
+  MandateState,
+  MandateSubject,
+} from "./mandates";
+export { serviceAccounts } from "./service-accounts";
+export type { ServiceAccount, ServiceAccountKind, ServiceAccountStatus } from "./service-accounts";
+export { serviceAccountCredentials } from "./service-account-credentials";
+export type {
+  AuthenticatedServiceAccountCredential,
+  ServiceAccountCredential,
+  ServiceAccountCredentialKind,
+  ServiceAccountCredentialOverview,
+  ServiceAccountCredentialOwner,
+  ServiceAccountCredentialStatus,
+} from "./service-account-credentials";
+export { oauthTokens } from "./oauth-tokens";
+export type { AuthenticatedOAuthToken } from "./oauth-tokens";
+export { webauthn } from "./webauthn";
+export type { WebAuthnRp } from "./webauthn";
+
+export { accountLifecycle } from "./account-lifecycle";
+export type { AccountLifecycleService } from "./account-lifecycle";
+export type { AccountLifecycleNotificationSender } from "./account-lifecycle/notification-sender";
+export { lifecycleJobs } from "./account-lifecycle/scheduler";
+
+export { settings } from "./settings/namespace";
+export { loadCache, get, set, remove, getAll } from "./settings";
+export type { SettingEntry } from "./settings";
+export { SETTINGS, SETTINGS_MAP, registerSettings } from "./settings/defaults";
+export { validateSettingValue, normalizeSettingValue, getSettingLabel } from "./settings/defaults";
+export type { SettingDef, SettingKind, SettingOption } from "./settings/defaults";
+export { renderTemplate } from "./settings/templates";
+export { settingsService } from "./settings/app";
+export type { SettingsService } from "./settings/app";
+export { decryptSecret, encryptSecret, secrets } from "./secrets";
+
+// Typed async API + cache-aside primitives.
+export { coreSettings, createSettingsAPI } from "./settings/api";
+export type { SettingsAPI } from "./settings/api";
+export {
+  readKey as settingsReadKey,
+  writeKey as settingsWriteKey,
+  deleteKey as settingsDeleteKey,
+  bulkRead as settingsBulkRead,
+  allKnownKeys as settingsAllKnownKeys,
+  listLegacyKeys as settingsListLegacyKeys,
+  deleteLegacyKeys as settingsDeleteLegacyKeys,
+} from "./settings/store";
+export type { LegacySettingRow } from "./settings/store";
+export { loadSnapshot as loadSettingsSnapshot } from "./settings/snapshot";
+
+export { weatherService } from "./weather";
+export type { WeatherService, WeatherData, DailyForecast, CurrentWeather, HourlyForecast, WeatherIcon } from "./weather";
+export { migrate as migrateWeather } from "./weather/migrate";
+export { getFreeIpaConfig } from "./freeipa-config";
+export type { FreeIpaConfig } from "./freeipa-config";
+export {
+  GotenbergRenderError,
+  MARKDOWN_PDF_MAX_CUSTOM_CSS_BYTES,
+  MARKDOWN_PDF_TEMPLATE_IDS,
+  MarkdownPdfError,
+  buildMarkdownPdfHtml,
+  getGotenbergConfig,
+  mergePdfs,
+  mergePdfsWithConfig,
+  renderMarkdownToPdf,
+  renderMarkdownToPdfWithConfig,
+  renderHtmlToPdf,
+  renderHtmlToPdfWithConfig,
+  renderTemplatePdfPreview,
+  testGotenberg,
+} from "./pdf";
+export type {
+  GotenbergConfig,
+  GotenbergRenderErrorCode,
+  MarkdownPdfErrorCode,
+  MarkdownPdfTemplateId,
+  MergePdfsInput,
+  RenderMarkdownToPdfInput,
+  RenderMarkdownToPdfOptions,
+  RenderTemplatePdfPreviewInput,
+  RenderTemplatePdfPreviewOptions,
+  RenderHtmlToPdfInput,
+  RenderHtmlToPdfOptions,
+  RenderHtmlToPdfResult,
+  TemplatePdfPreviewError,
+  TemplatePdfPreviewPhase,
+  TemplatePdfPreviewResult,
+} from "./pdf";
+
+export { createSyncOpsRoutes, SYNC_OPS_DEAD_LETTER_LIMIT } from "./sync-ops";
+export type {
+  SyncDeadLetterEntry,
+  SyncDeadLetterKind,
+  SyncDeadLetterStoreView,
+  SyncOpsRoutes,
+  SyncOpsRoutesDependencies,
+  SyncScheduleView,
+} from "./sync-ops";
+
+export { latestTopicCursor } from "./topic-cursor";
+export { readAccountCategoryPolicy, isAccountCategoryAllowed } from "./account-category-policy";
+export { appApproval, type AppDeviceEnrollmentNotice } from "./app-approval";
+export { legalConsent } from "./legal-consent";

package/src/services/ipa/auth.ts

@@ -0,0 +1,216 @@
+import type { MutationResult } from "../../contracts/shared";
+import { freeipa } from "../../server/services";
+import { getFreeIpaTls } from "../../server/services/freeipa/tls";
+import {
+  FreeIpaTransportError,
+  isFreeIpaUpstreamStatus,
+  readFreeIpaErrorBody,
+  withFreeIpaResponse,
+} from "../../server/services/freeipa/transport";
+import { getFreeIpaConfig } from "../freeipa-config";
+import { logger } from "../logging";
+
+const log = logger("ipa:auth");
+
+const getEnabledConfig = async (): Promise<MutationResult<{ url: string; serviceUser: string; servicePassword: string }>> => {
+  const config = await getFreeIpaConfig();
+  if (!config.enabled) {
+    return { ok: false, error: "FreeIPA is disabled.", status: 400 };
+  }
+  if (!config.configured) {
+    return { ok: false, error: `FreeIPA is enabled but not fully configured. Missing: ${config.missingSettings.join(", ")}.`, status: 500 };
+  }
+  return {
+    ok: true,
+    data: {
+      url: config.url,
+      serviceUser: config.serviceUser,
+      servicePassword: config.servicePassword,
+    },
+  };
+};
+
+const normalizePasswordChangeText = (value: string): string =>
+  value
+    .replace(/<[^>]+>/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+
+const extractPasswordPolicyMessage = (policyError: string | null, body: string): string | null => {
+  const headerMessage = normalizePasswordChangeText(policyError ?? "");
+  if (headerMessage) return headerMessage;
+
+  const normalized = normalizePasswordChangeText(body);
+  const policyMatch = normalized.match(/policy-error[^:]*:\s*(.+)$/i);
+  if (policyMatch?.[1]) return policyMatch[1].trim();
+
+  if (/password|policy|quality|history|complexity|character|length|short|reuse/i.test(normalized)) {
+    return normalized.slice(0, 240);
+  }
+  return null;
+};
+
+const isCurrentPasswordFailure = (pwchangeResult: string | null, body: string): boolean => {
+  const haystack = `${pwchangeResult ?? ""} ${normalizePasswordChangeText(body)}`.toLowerCase();
+  return (
+    haystack.includes("invalid credentials") ||
+    haystack.includes("authentication failed") ||
+    haystack.includes("current password is incorrect") ||
+    haystack.includes("old password is incorrect") ||
+    haystack.includes("incorrect current password") ||
+    haystack.includes("incorrect old password")
+  );
+};
+
+const mapPasswordChangeFailure = (params: {
+  status: number;
+  pwchangeResult: string | null;
+  policyError: string | null;
+  body: string;
+}): Extract<MutationResult<void>, { ok: false }> => {
+  const policyMessage = extractPasswordPolicyMessage(params.policyError, params.body);
+  if (params.pwchangeResult === "policy-error" || normalizePasswordChangeText(params.policyError ?? "")) {
+    return {
+      ok: false,
+      error: policyMessage ?? "FreeIPA rejected the new password. Choose a different password and try again.",
+      status: 400,
+    };
+  }
+
+  if (isCurrentPasswordFailure(params.pwchangeResult, params.body)) {
+    return { ok: false, error: "Current password is incorrect.", status: 401 };
+  }
+
+  if (policyMessage) {
+    return { ok: false, error: policyMessage, status: 400 };
+  }
+
+  return {
+    ok: false,
+    error: "FreeIPA rejected the new password. Choose a different password and try again.",
+    status: params.status >= 500 ? 500 : 400,
+  };
+};
+
+// ==========================
+// Login
+// ==========================
+
+export type LoginResult = { status: "success"; session: string } | { status: "password_expired" } | { status: "failed" };
+export type IpaPasswordChangeResult = MutationResult<void> | { ok: false; error: string; status: 503 };
+export const login = async (username: string, password: string): Promise<LoginResult> => {
+  const config = await getEnabledConfig();
+  if (!config.ok) return { status: "failed" };
+  return freeipa.session.login({ url: config.data.url, username, password });
+};
+
+export const getServiceSession = async (): Promise<string> => {
+  const config = await getEnabledConfig();
+  if (!config.ok) {
+    throw new Error(config.error);
+  }
+  return freeipa.session.getServiceSession({
+    url: config.data.url,
+    serviceUser: config.data.serviceUser,
+    servicePassword: config.data.servicePassword,
+  });
+};
+
+// ==========================
+// Change Password (for expired passwords, no session required)
+// ==========================
+
+/**
+ * Change an expired or temporary password using FreeIPA's change_password endpoint.
+ * This endpoint works without an active session.
+ */
+export const changeExpiredPassword = async (params: {
+  username: string;
+  currentPassword: string;
+  newPassword: string;
+}): Promise<IpaPasswordChangeResult> => {
+  const { username, currentPassword, newPassword } = params;
+  const config = await getEnabledConfig();
+  if (!config.ok) return config;
+
+  const tls = await getFreeIpaTls();
+  try {
+    return await withFreeIpaResponse(
+      `${freeipa.client.baseUrl(config.data.url)}/ipa/session/change_password`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Referer: `${freeipa.client.baseUrl(config.data.url)}/ipa`,
+          Accept: "text/plain",
+        },
+        body: new URLSearchParams({
+          user: username,
+          old_password: currentPassword,
+          new_password: newPassword,
+        }),
+        tls,
+      },
+      async (res): Promise<IpaPasswordChangeResult> => {
+        // FreeIPA returns X-IPA-Pwchange-Result header
+        const pwchangeResult = res.headers.get("X-IPA-Pwchange-Result");
+        if (!res.ok || pwchangeResult !== "ok") {
+          const policyError = res.headers.get("X-IPA-Pwchange-Policy-Error");
+          const body = (await readFreeIpaErrorBody(res)).text;
+          if (isFreeIpaUpstreamStatus(res.status)) {
+            return { ok: false, error: `FreeIPA returned HTTP ${res.status}`, status: 503 };
+          }
+          const failure = mapPasswordChangeFailure({ status: res.status, pwchangeResult, policyError, body });
+          log.warn("FreeIPA password change failed", {
+            status: res.status,
+            pwchangeResult,
+            mappedStatus: failure.status,
+          });
+          return failure;
+        }
+
+        await res.body?.cancel().catch(() => undefined);
+        return { ok: true, data: undefined };
+      },
+    );
+  } catch (error) {
+    if (error instanceof FreeIpaTransportError) return { ok: false, error: error.message, status: 503 };
+    throw error;
+  }
+};
+
+export const __ipaAuthTest = {
+  mapPasswordChangeFailure,
+};
+
+// ==========================
+// Change Password (with session, for authenticated users)
+// ==========================
+
+/**
+ * Change password for an authenticated user using their session.
+ */
+export const changePassword = async (params: { ipaSession: string; uid: string; newPassword: string }): Promise<MutationResult<void>> => {
+  const { ipaSession, uid, newPassword } = params;
+  const config = await getEnabledConfig();
+  if (!config.ok) return config;
+
+  const response = await freeipa.client.call({
+    url: config.data.url,
+    ipaSession,
+    method: "user_mod",
+    args: [uid],
+    options: {
+      userpassword: newPassword,
+    },
+  });
+  if (response.error) {
+    return {
+      ok: false,
+      error: response.error.message ?? "Failed to change password.",
+      status: freeipa.util.mapIpaErrorCode(response.error.code),
+    };
+  }
+
+  return { ok: true, data: undefined };
+};