@valentinkolb/cloud 0.1.0

package/src/services/providers/local/users.ts

@@ -0,0 +1,255 @@
+import { sql } from "bun";
+import { writeDeletedAccountAudit } from "../../account-lifecycle/audit";
+import { session } from "../../session";
+import * as settings from "../../settings";
+import { generateUniqueAbbreviation } from "../../ipa/users";
+import { resolveStoredAdminState } from "../../accounts/model";
+import { isUniqueViolation } from "../../postgres";
+import type { MutationResult, UserProfile } from "../../../contracts/shared";
+
+type DbRow = Record<string, unknown>;
+
+export type LocalUserCreateData = {
+  email: string;
+  givenname?: string;
+  sn?: string;
+  displayName?: string;
+};
+
+const createLocalUid = async (): Promise<string> => {
+  const abbrLen = await settings.get<number>("user.abbr_length");
+  return generateUniqueAbbreviation(abbrLen);
+};
+
+export const create = async (params: {
+  data: LocalUserCreateData;
+  profile: UserProfile;
+  accountExpires: Date | null;
+  admin?: boolean;
+}): Promise<MutationResult<{ id: string }>> => {
+  const uid = await createLocalUid();
+  const admin = resolveStoredAdminState({
+    provider: "local",
+    profile: params.profile,
+    requestedAdmin: params.admin,
+  });
+
+  try {
+    const rows = await sql<DbRow[]>`
+      INSERT INTO auth.users (
+        uid,
+        provider,
+        profile,
+        mail,
+        given_name,
+        sn,
+        display_name,
+        admin,
+        account_expires
+      )
+      VALUES (
+        ${uid},
+        'local',
+        ${params.profile},
+        ${params.data.email},
+        ${params.data.givenname ?? ""},
+        ${params.data.sn ?? ""},
+        ${params.data.displayName ?? ""},
+        ${admin},
+        ${params.accountExpires}
+      )
+      RETURNING id
+    `;
+    return { ok: true, data: { id: rows[0]!.id as string } };
+  } catch (error) {
+    // Map Postgres unique violations to a typed 409 instead of leaking raw DB
+    // errors. Two possible collisions: generated uid (extremely rare, retry at
+    // next call) or email already used by another local account.
+    if (isUniqueViolation(error, "users_uid_key")) {
+      return { ok: false, error: "Generated UID collided. Please retry.", status: 409 };
+    }
+    if (isUniqueViolation(error, "idx_users_provider_mail")) {
+      return { ok: false, error: "A local account with this email already exists.", status: 409 };
+    }
+    throw error;
+  }
+};
+
+export const createGuest = async (params: {
+  email: string;
+  givenname?: string;
+  sn?: string;
+  displayName?: string;
+  accountExpires?: Date | null;
+}): Promise<MutationResult<{ id: string }>> => {
+  let accountExpires = params.accountExpires ?? null;
+  if (params.accountExpires === undefined) {
+    const configured = await settings.get<number | null>("user.account.local_guest_expires_days");
+    const days = typeof configured === "number" ? configured : 365;
+    accountExpires = days > 0 ? new Date(Date.now() + days * 24 * 60 * 60 * 1000) : null;
+  }
+
+  return create({
+    data: {
+      email: params.email,
+      givenname: params.givenname,
+      sn: params.sn,
+      displayName: params.displayName,
+    },
+    profile: "guest",
+    accountExpires,
+  });
+};
+
+export const update = async (params: {
+  id: string;
+  data: {
+    givenname?: string;
+    sn?: string;
+    displayName?: string;
+    mail?: string;
+  };
+}): Promise<MutationResult<void>> => {
+  const existingRows = await sql<DbRow[]>`SELECT id FROM auth.users WHERE id = ${params.id}::uuid AND provider = 'local'`;
+  if (existingRows.length === 0) {
+    return { ok: false, error: "Local user not found", status: 404 };
+  }
+
+  await sql`
+    UPDATE auth.users
+    SET given_name = CASE WHEN ${params.data.givenname !== undefined} THEN ${params.data.givenname ?? ""} ELSE given_name END,
+        sn = CASE WHEN ${params.data.sn !== undefined} THEN ${params.data.sn ?? ""} ELSE sn END,
+        display_name = CASE WHEN ${params.data.displayName !== undefined} THEN ${params.data.displayName ?? ""} ELSE display_name END,
+        mail = CASE WHEN ${params.data.mail !== undefined} THEN ${params.data.mail ?? null} ELSE mail END
+    WHERE id = ${params.id}::uuid
+  `;
+
+  return { ok: true, data: undefined };
+};
+
+export const setProfile = async (params: {
+  id: string;
+  profile: UserProfile;
+  accountExpires: Date | null;
+}): Promise<MutationResult<void>> => {
+  const rows = await sql<DbRow[]>`
+    SELECT provider, admin
+    FROM auth.users
+    WHERE id = ${params.id}::uuid
+  `;
+  if (rows.length === 0) return { ok: false, error: "User not found", status: 404 };
+  if ((rows[0]!.provider as string) !== "local") {
+    return { ok: false, error: "Only local accounts can change profile locally", status: 400 };
+  }
+
+  const admin = resolveStoredAdminState({
+    provider: "local",
+    profile: params.profile,
+    currentAdmin: Boolean(rows[0]!.admin),
+  });
+
+  await sql`
+    UPDATE auth.users
+    SET provider = 'local',
+        profile = ${params.profile},
+        admin = ${admin},
+        account_expires = ${params.accountExpires}
+    WHERE id = ${params.id}::uuid
+  `;
+
+  return { ok: true, data: undefined };
+};
+
+export const setExpiry = async (params: {
+  id: string;
+  profile: UserProfile;
+  accountExpires: Date | null;
+}): Promise<MutationResult<void>> => {
+  const rows = await sql<DbRow[]>`
+    SELECT provider
+    FROM auth.users
+    WHERE id = ${params.id}::uuid
+  `;
+  if (rows.length === 0) return { ok: false, error: "User not found", status: 404 };
+  if ((rows[0]!.provider as string) !== "local") {
+    return { ok: false, error: "Only local accounts support local expiry changes", status: 400 };
+  }
+
+  await sql`
+    UPDATE auth.users
+    SET account_expires = ${params.accountExpires}
+    WHERE id = ${params.id}::uuid
+  `;
+
+  return { ok: true, data: undefined };
+};
+
+export const setAdmin = async (params: {
+  id: string;
+  admin: boolean;
+}): Promise<MutationResult<void>> => {
+  const rows = await sql<DbRow[]>`
+    SELECT provider, profile, admin
+    FROM auth.users
+    WHERE id = ${params.id}::uuid
+  `;
+  if (rows.length === 0) return { ok: false, error: "User not found", status: 404 };
+  const row = rows[0]!;
+  if ((row.provider as string) !== "local") {
+    return { ok: false, error: "Only local full accounts can be granted admin access", status: 400 };
+  }
+  if ((row.profile as string) !== "user") {
+    return { ok: false, error: "Guest accounts cannot be granted admin access", status: 400 };
+  }
+  const currentAdmin = Boolean(row.admin);
+  if (currentAdmin === params.admin) {
+    return { ok: false, error: params.admin ? "Account is already an admin" : "Account is not an admin", status: 409 };
+  }
+
+  await sql`
+    UPDATE auth.users
+    SET admin = ${params.admin}
+    WHERE id = ${params.id}::uuid
+  `;
+
+  return { ok: true, data: undefined };
+};
+
+export const remove = async (params: {
+  id: string;
+  actor: { userId: string; uid: string };
+}): Promise<MutationResult<void>> => {
+  const rows = await sql<DbRow[]>`
+    SELECT uid, profile, mail, display_name
+    FROM auth.users
+    WHERE id = ${params.id}::uuid
+      AND provider = 'local'
+  `;
+  if (rows.length === 0) return { ok: false, error: "Local user not found", status: 404 };
+
+  const row = rows[0]!;
+  const uid = row.uid as string;
+  await sql.begin(async (tx) => {
+    await writeDeletedAccountAudit({
+      db: tx,
+      userId: params.id,
+      uid,
+      mail: (row.mail as string) ?? null,
+      displayName: (row.display_name as string) ?? null,
+      previousProvider: "local",
+      previousProfile: (row.profile as UserProfile | null) ?? "guest",
+      reason: "manual_delete",
+      meta: {
+        actorUserId: params.actor.userId,
+        actorUid: params.actor.uid,
+        deletedFromFreeIpa: false,
+        freeIpaUserAlreadyMissing: false,
+      },
+    });
+    await tx`DELETE FROM auth.users WHERE id = ${params.id}::uuid`;
+  });
+
+  await session.revokeAllForUser(params.id);
+
+  return { ok: true, data: undefined };
+};

package/src/services/session/index.ts

@@ -0,0 +1,137 @@
+import type { Context } from "hono";
+import { getCookie, setCookie, deleteCookie } from "hono/cookie";
+import { redis, sql } from "bun";
+import { env } from "../../config/env";
+import * as settings from "../settings";
+
+/**
+ * Session data stored in Redis per session key.
+ *
+ * `gen` captures the user's session-generation counter at the time the session
+ * was created. Revoking all sessions for a user is an atomic INCR on that
+ * counter; any stored session whose `gen` is below the current counter is
+ * rejected by `getData()` without touching the session key itself.
+ */
+type SessionData = {
+  userId: string;
+  ipaSession: string | null;
+  gen: number;
+};
+
+const sessionKey = (userId: string, randomToken: string) => `session:${userId}:${randomToken}`;
+const genKey = (userId: string) => `session:gen:${userId}`;
+
+/**
+ * Read the current generation counter for a user. Missing key is treated as 0.
+ * The counter never resets, only increments, so a user's earliest session has
+ * `gen = 0` implicitly even before the first revocation.
+ */
+const readGen = async (userId: string): Promise<number> => {
+  const raw = await redis.get(genKey(userId));
+  if (!raw) return 0;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : 0;
+};
+
+const parseToken = (token: string): { userId: string; randomToken: string } | null => {
+  const colonIndex = token.indexOf(":");
+  if (colonIndex === -1) return null;
+  const userId = token.slice(0, colonIndex);
+  const randomToken = token.slice(colonIndex + 1);
+  if (!userId || !randomToken) return null;
+  return { userId, randomToken };
+};
+
+const parseBearer = (header: string | undefined): string | null => {
+  if (!header) return null;
+  const match = header.match(/^Bearer\s+(\S+)$/i);
+  return match?.[1] ?? null;
+};
+
+export const session = {
+  /**
+   * Get session token from cookie or Authorization header.
+   * Token format: userId:randomToken
+   *
+   * Note: the userId is embedded in the token to enable efficient generation
+   * lookup and per-user key namespacing. The userId (UUID) is not secret.
+   */
+  getToken: (c: Context): string | null => {
+    const cookie = getCookie(c, "session_token");
+    const bearer = parseBearer(c.req.header("Authorization"));
+    return cookie || bearer || null;
+  },
+
+  parseToken,
+
+  create: async (c: Context, userId: string, ipaSession: string | null = null): Promise<string> => {
+    const randomToken = crypto.randomUUID();
+    const expiryHours = await settings.get<number>("user.session.expiry_hours");
+    const ttl = expiryHours * 60 * 60;
+
+    const gen = await readGen(userId);
+    const data: SessionData = { userId, ipaSession, gen };
+    await redis.set(sessionKey(userId, randomToken), JSON.stringify(data), "EX", ttl);
+
+    await sql`UPDATE auth.users SET last_login_local = now() WHERE id = ${userId}`;
+
+    const clientToken = `${userId}:${randomToken}`;
+
+    setCookie(c, "session_token", clientToken, {
+      httpOnly: true,
+      secure: !env.IS_DEVELOPMENT,
+      sameSite: "Lax",
+      maxAge: ttl,
+      path: "/",
+    });
+
+    return clientToken;
+  },
+
+  /** Explicit logout — drops the current session key and cookie. Does not affect other sessions. */
+  delete: async (c: Context): Promise<void> => {
+    const token = session.getToken(c);
+    if (token) {
+      const parsed = parseToken(token);
+      if (parsed) {
+        await redis.del(sessionKey(parsed.userId, parsed.randomToken));
+      }
+    }
+    deleteCookie(c, "session_token", { path: "/" });
+  },
+
+  /**
+   * Atomically revoke every existing session for a user by bumping the
+   * generation counter. Replaces the former SCAN+DEL loop. Future reads
+   * via `getData()` will reject any session stored with the previous `gen`.
+   *
+   * Race-safe against concurrent `session.create()`: the newly-created session
+   * either writes the pre-INCR gen (and is immediately invalid) or the
+   * post-INCR gen (and is intentionally valid if the caller ordered INCR
+   * before granting the new login).
+   */
+  revokeAllForUser: async (userId: string): Promise<void> => {
+    await redis.incr(genKey(userId));
+  },
+
+  /**
+   * Load session data, enforcing the generation check. Returns `null` when the
+   * token is malformed, the key is missing/expired, or the stored `gen` is
+   * below the user's current counter.
+   */
+  getData: async (token: string): Promise<SessionData | null> => {
+    const parsed = parseToken(token);
+    if (!parsed) return null;
+    const raw = await redis.get(sessionKey(parsed.userId, parsed.randomToken));
+    if (!raw) return null;
+    const data = JSON.parse(raw) as SessionData;
+    const currentGen = await readGen(parsed.userId);
+    if ((data.gen ?? 0) < currentGen) return null;
+    return data;
+  },
+
+  getIpaSession: async (token: string): Promise<string | null> => {
+    const data = await session.getData(token);
+    return data?.ipaSession ?? null;
+  },
+};

package/src/services/settings/api.ts

@@ -0,0 +1,61 @@
+/**
+ * Typed async settings API.
+ *
+ * Two surfaces are exposed:
+ *
+ *  1. `app.settings` — created by `defineApp`, typed against that app's own
+ *     declared settings (plus any core settings since core's snapshot is
+ *     loaded into every container). Available on the AppDefinition return value.
+ *
+ *  2. `coreSettings` — for cloud-lib internal services that don't have an
+ *     `app` reference (e.g. `services/notifications/email.ts`,
+ *     `services/weather/forecast.ts`, OpenAPI middleware, cron callbacks).
+ *     Loosely typed (caller provides the value type via the `T` generic).
+ *
+ * Backend: cache-aside via `store.ts` (Redis 5min TTL + DB fallback). All
+ * functions are async — sync render-time access uses the per-request snapshot
+ * exposed via `c.get("settings")`.
+ */
+
+import type { AppSettingsMap, KindToType } from "../../contracts/settings-types";
+import { deleteKey, readKey, writeKey } from "./store";
+
+/**
+ * Per-app typed settings API. Keys constrained to those declared in the
+ * app's `defineApp({ settings: ... })` block.
+ */
+export interface SettingsAPI<F extends Record<string, unknown>> {
+  get<K extends keyof F & string>(key: K): Promise<F[K]>;
+  set<K extends keyof F & string>(key: K, value: F[K]): Promise<void>;
+  remove<K extends keyof F & string>(key: K): Promise<void>;
+}
+
+/**
+ * Build a typed SettingsAPI for a given AppSettingsMap.
+ *
+ * The runtime is identical for every app (delegates to store.ts); the typing
+ * is purely a TS construct that constrains keys/values to what was declared.
+ */
+export const createSettingsAPI = <S extends AppSettingsMap>(): SettingsAPI<{
+  [K in keyof S]: KindToType<S[K]["kind"]>;
+}> => ({
+  get: async (key) => readKey(key) as never,
+  set: async (key, value) => writeKey(key, value),
+  remove: async (key) => deleteKey(key),
+});
+
+/**
+ * cloud-lib internal services and other apps use `coreSettings` for any
+ * setting access outside of a per-request context. Loose-typed (the caller
+ * specifies the expected value type via the `T` generic) — apps that need
+ * tight typing for their OWN settings use `app.settings.get/set` instead.
+ *
+ * Usage:
+ *   await coreSettings.get<string>("app.name");          // string
+ *   await coreSettings.set("freeipa.enable", true);       // value type free
+ */
+export const coreSettings = {
+  get: <T = unknown>(key: string): Promise<T> => readKey(key) as Promise<T>,
+  set: (key: string, value: unknown): Promise<void> => writeKey(key, value),
+  remove: (key: string): Promise<void> => deleteKey(key),
+};

package/src/services/settings/app.ts

@@ -0,0 +1,101 @@
+/**
+ * App-facing settings service. Wraps the lower-level primitives in
+ * `services/settings` (get, set, getAll, remove + SETTINGS_MAP) with the
+ * filtered list / validated update / reset surface the admin UIs need.
+ *
+ * Lives in cloud-lib because every app that has app-scoped settings needs
+ * the same API to render its admin form (files, weather, etc.).
+ */
+import { err, fail, ok, paginate, type PageParams, type Paginated } from "@valentinkolb/stdlib";
+import * as settingsPrimitives from ".";
+import type { SettingEntry } from ".";
+import { SETTINGS_MAP, validateSettingValue } from "./defaults";
+
+const paginateEntries = <T>(items: T[], pagination?: PageParams): Paginated<T> => {
+  if (!pagination) {
+    return { items, page: 1, perPage: items.length, total: items.length, hasNext: false };
+  }
+  const { page, perPage, offset } = paginate(pagination);
+  return {
+    items: items.slice(offset, offset + perPage),
+    page,
+    perPage,
+    total: items.length,
+    hasNext: page * perPage < items.length,
+  };
+};
+
+/**
+ * Redact secret-kind setting values before they leave the server.
+ *
+ * Secret values are encrypted at rest and decrypted on read for runtime use,
+ * but the admin UI receives them via SSR `data-props` (visible in HTML
+ * source, browser caches, devtools). For secrets we hide the actual value
+ * and rely on the form's change-tracking: if the admin doesn't type a new
+ * value, no PUT is sent and the stored value stays. The placeholder hint in
+ * the UI signals "leave empty to keep current".
+ */
+const redactSecretValue = (entry: SettingEntry): SettingEntry => {
+  if (entry.kind !== "secret") return entry;
+  return { ...entry, value: "" };
+};
+
+export const settingsService = {
+  entry: {
+    list: async (config?: {
+      pagination?: PageParams;
+      filter?: { query?: string; group?: string };
+    }): Promise<Paginated<SettingEntry>> => {
+      const entries = await settingsPrimitives.getAll();
+      const query = config?.filter?.query?.trim().toLowerCase();
+      const group = config?.filter?.group?.trim().toLowerCase();
+
+      const filtered = entries
+        .filter((entry) => {
+          if (group && entry.group.toLowerCase() !== group) return false;
+          if (!query) return true;
+          return (
+            entry.key.toLowerCase().includes(query) ||
+            entry.label.toLowerCase().includes(query) ||
+            entry.description.toLowerCase().includes(query)
+          );
+        })
+        .map(redactSecretValue);
+
+      return paginateEntries(filtered, config?.pagination);
+    },
+    update: async (config: { key: string; value: unknown }) => {
+      if (!SETTINGS_MAP.has(config.key)) {
+        return fail(err.badInput(`Unknown setting: ${config.key}`));
+      }
+      const def = SETTINGS_MAP.get(config.key)!;
+      const validated = validateSettingValue(def, config.value);
+      if (!validated.ok) {
+        return fail(err.badInput(validated.error));
+      }
+      try {
+        await settingsPrimitives.set(config.key, validated.value);
+        return ok(undefined);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.startsWith("Unknown setting:")) {
+          return fail(err.badInput(message));
+        }
+        return fail(err.internal(`Failed to update setting: ${message}`));
+      }
+    },
+    reset: async (config: { key: string }) => {
+      if (!SETTINGS_MAP.has(config.key)) {
+        return fail(err.badInput(`Unknown setting: ${config.key}`));
+      }
+      try {
+        await settingsPrimitives.remove(config.key);
+        return ok(undefined);
+      } catch (error) {
+        return fail(err.internal(`Failed to reset setting: ${error instanceof Error ? error.message : String(error)}`));
+      }
+    },
+  },
+};
+
+export type SettingsService = typeof settingsService;

package/src/services/settings/crypto.ts

@@ -0,0 +1,69 @@
+/**
+ * Encryption helpers for settings at-rest.
+ *
+ * Settings DB rows are encrypted via stdlib's `crypto.symmetric.encrypt`
+ * (AES-256-GCM with HKDF key derivation). The key material comes from
+ * `APP_SECRET` — see `getAppSecret()` for the hex/passphrase handling.
+ */
+
+import { createHash } from "node:crypto";
+import { env } from "../../config/env";
+import { crypto } from "../../server/services";
+
+/**
+ * Resolve the encryption key passed to stdlib's `crypto.symmetric.encrypt`.
+ *
+ * Stdlib derives keys via HKDF and requires the input to be a hex string
+ * (it calls `fromHex(key)` internally). Two cases:
+ *
+ *  1. APP_SECRET is already a valid hex string (any even length).
+ *     Pass it through unchanged. THIS IS THE PRODUCTION PATH — existing
+ *     deployments use hex secrets and have data encrypted with the secret
+ *     verbatim. Any transformation here would change the derived HKDF key
+ *     and make every previously encrypted settings row unreadable.
+ *
+ *  2. APP_SECRET is not valid hex (e.g. a passphrase like "supersecret").
+ *     Deterministically derive a 32-byte hex key via SHA-256. Same input
+ *     always produces the same hex output, so settings encrypted with a
+ *     non-hex secret stay decryptable across restarts.
+ *
+ * ⚠️  DO NOT change the hex-passthrough branch. Hashing a hex secret would
+ * silently break every prod instance: encrypted settings could no longer
+ * be decrypted because the HKDF input would differ from what was used at
+ * write time. The branch exists specifically to preserve backward compat
+ * with deployments that have always used hex-format APP_SECRET.
+ */
+export const getAppSecret = (): string => {
+  const raw = env.APP_SECRET.trim();
+  if (!raw) {
+    throw new Error("APP_SECRET is required to read or write encrypted settings");
+  }
+  // Case 1: already hex — pass through (backward-compat, see doc above).
+  if (raw.length % 2 === 0 && /^[0-9a-fA-F]+$/.test(raw)) {
+    return raw;
+  }
+  // Case 2: non-hex passphrase — deterministically derive hex via SHA-256.
+  return createHash("sha256").update(raw).digest("hex");
+};
+
+export const encryptValue = async (value: unknown): Promise<string> =>
+  crypto.symmetric.encrypt({
+    payload: JSON.stringify(value),
+    key: getAppSecret(),
+    stretched: false,
+  });
+
+export const decryptValue = async (value: string): Promise<unknown> => {
+  const decrypted = await crypto.symmetric.decrypt({
+    payload: value,
+    key: getAppSecret(),
+  });
+  try {
+    return JSON.parse(decrypted);
+  } catch {
+    // Decrypt succeeded but the plaintext isn't JSON. Either pre-JSON-encoding
+    // legacy data or external write — return the raw string so callers can
+    // decide. Throwing here would corrupt the read path entirely.
+    return decrypted;
+  }
+};