@k2b/cloud 0.6.0-rc.0

package/src/server/services/geo.ts

@@ -0,0 +1,198 @@
+import { err, fail, ok, type PageParams, type Paginated, paginate, type Result } from "@k2b/stdlib";
+import { z } from "zod";
+import { readBoundedJson } from "../../_internal/bounded-json";
+
+const GEO_TIMEOUT_MS = 2_000;
+const GEO_MAX_RESPONSE_BYTES = 256 * 1024;
+const GEO_MAX_PLACES = 500;
+
+const GeoApiPlaceSchema = z
+  .object({
+    name: z.string().trim().min(1).max(160),
+    latitude: z.number().finite().min(-90).max(90),
+    longitude: z.number().finite().min(-180).max(180),
+    country_code: z.string().trim().max(16).optional(),
+    admin1_code: z.string().trim().max(160).optional(),
+    feature_class: z.string().trim().max(16).optional(),
+    feature_code: z.string().trim().max(32).optional(),
+  })
+  .strip();
+
+const GeoApiSearchResponseSchema = z
+  .object({
+    places: z.array(z.unknown()).max(GEO_MAX_PLACES).optional(),
+  })
+  .strip();
+
+type GeoApiPlace = z.infer<typeof GeoApiPlaceSchema>;
+
+export type GeoPlace = {
+  name: string;
+  lat: number;
+  lon: number;
+  country?: string;
+  state?: string;
+  featureClass?: string;
+  featureCode?: string;
+};
+
+/**
+ * Normalizes and validates geo API base URLs before outbound requests.
+ */
+const normalizeBaseUrl = (baseUrl: string): Result<string> => {
+  const value = baseUrl.trim();
+  if (!value) {
+    return fail(err.badInput("Geo API base URL is required"));
+  }
+  return ok(value.replace(/\/$/, ""));
+};
+
+const unavailable = <T>(): Result<T> =>
+  fail({
+    code: "GEO_UNAVAILABLE",
+    message: "Geo service is unavailable",
+    status: 500,
+  });
+
+const geoSignal = (signal?: AbortSignal): AbortSignal =>
+  signal ? AbortSignal.any([signal, AbortSignal.timeout(GEO_TIMEOUT_MS)]) : AbortSignal.timeout(GEO_TIMEOUT_MS);
+
+const readGeoResponse = async (response: Response): Promise<Result<z.infer<typeof GeoApiSearchResponseSchema>>> => {
+  const body = await readBoundedJson(response, GEO_MAX_RESPONSE_BYTES);
+  if (!body.ok) return unavailable();
+  const parsed = GeoApiSearchResponseSchema.safeParse(body.data);
+  return parsed.success ? ok(parsed.data) : unavailable();
+};
+
+/**
+ * Maps one geo API place record to the internal place model and drops invalid rows.
+ */
+const toPlace = (place: GeoApiPlace): GeoPlace | null => {
+  if (typeof place.name !== "string" || typeof place.latitude !== "number" || typeof place.longitude !== "number") {
+    return null;
+  }
+
+  return {
+    name: place.name,
+    lat: place.latitude,
+    lon: place.longitude,
+    country: place.country_code,
+    state: place.admin1_code,
+    featureClass: place.feature_class,
+    featureCode: place.feature_code,
+  };
+};
+
+/**
+ * Searches places through the configured geo API and returns paginated, normalized matches.
+ */
+const list = async (config: {
+  baseUrl: string;
+  pagination?: PageParams;
+  signal?: AbortSignal;
+  filter: {
+    query: string;
+    country?: string;
+    featureClass?: string;
+    featureCode?: string;
+  };
+}): Promise<Result<Paginated<GeoPlace>>> => {
+  const query = config.filter.query.trim();
+  if (!query) {
+    const { page, perPage } = paginate(config.pagination);
+    return ok({
+      items: [],
+      page,
+      perPage,
+      total: 0,
+      hasNext: false,
+    });
+  }
+
+  const baseUrlResult = normalizeBaseUrl(config.baseUrl);
+  if (!baseUrlResult.ok) return baseUrlResult;
+
+  const params = new URLSearchParams({ q: query });
+  if (config.filter.country?.trim()) {
+    params.set("country", config.filter.country.trim());
+  }
+
+  try {
+    const res = await fetch(`${baseUrlResult.data}/geo/search?${params}`, { signal: geoSignal(config.signal) });
+    if (!res.ok) {
+      return unavailable();
+    }
+
+    const body = await readGeoResponse(res);
+    if (!body.ok) return body;
+    const mapped = (body.data.places ?? [])
+      .flatMap((candidate) => {
+        const place = GeoApiPlaceSchema.safeParse(candidate);
+        return place.success ? [place.data] : [];
+      })
+      .map(toPlace)
+      .filter((place): place is GeoPlace => place !== null);
+
+    const filtered = mapped.filter((place) => {
+      if (config.filter.featureClass && place.featureClass !== config.filter.featureClass) {
+        return false;
+      }
+      if (config.filter.featureCode && place.featureCode !== config.filter.featureCode) {
+        return false;
+      }
+      return true;
+    });
+
+    const { page, perPage, offset } = paginate(config.pagination);
+    const items = filtered.slice(offset, offset + perPage);
+    return ok({
+      items,
+      page,
+      perPage,
+      total: filtered.length,
+      hasNext: page * perPage < filtered.length,
+    });
+  } catch {
+    return unavailable();
+  }
+};
+
+/**
+ * Resolves one place by coordinates via reverse geocoding.
+ */
+const get = async (config: { baseUrl: string; lat: number; lon: number }): Promise<Result<GeoPlace | null>> => {
+  const baseUrlResult = normalizeBaseUrl(config.baseUrl);
+  if (!baseUrlResult.ok) return baseUrlResult;
+
+  try {
+    const res = await fetch(`${baseUrlResult.data}/geo/reverse?lat=${config.lat}&lng=${config.lon}`, { signal: geoSignal() });
+    if (!res.ok) {
+      return unavailable();
+    }
+
+    const body = await readGeoResponse(res);
+    if (!body.ok) return body;
+    const first = (body.data.places ?? [])
+      .flatMap((candidate) => {
+        const place = GeoApiPlaceSchema.safeParse(candidate);
+        return place.success ? [place.data] : [];
+      })
+      .map(toPlace)
+      .find((place): place is GeoPlace => place !== null);
+
+    return ok(first ?? null);
+  } catch {
+    return unavailable();
+  }
+};
+
+export const geoService = {
+  place: {
+    list,
+    get,
+  },
+};
+
+export type GeoService = typeof geoService;
+
+export const geo = geoService;

package/src/server/services/index.ts

@@ -0,0 +1,48 @@
+// Cloud-specific server services
+
+export type {
+  AccessDb,
+  AccessEntry,
+  AccessPrincipalColumns,
+  AccessPrincipalTierConditions,
+  AccessSubject,
+  AccessUser,
+  AccessUserSource,
+  EffectiveGroup,
+  PermissionLevel,
+  Principal,
+  PrincipalType,
+  ResourceAccessAdapter,
+} from "./access";
+export {
+  buildAccessPrincipalCondition,
+  buildAccessPrincipalTierConditions,
+  createAccess,
+  deleteAccess,
+  getAccess,
+  getEffectiveGroupIds,
+  getEffectiveGroups,
+  getEffectivePermission,
+  hasPermission,
+  listUsersWithAccess,
+  PERMISSION_LEVELS,
+  resolveDisplayNames,
+  updateAccess,
+} from "./access";
+export { freeipa } from "./freeipa";
+export type { GeoPlace, GeoService } from "./geo";
+
+export { geo, geoService } from "./geo";
+export { paginateItems } from "./pagination";
+export { services } from "./services";
+
+// Re-export from stdlib for backward compatibility
+// Prefer importing directly from @k2b/stdlib
+import { password as _password, svg as _svg } from "@k2b/stdlib";
+
+export type { PageParams, Paginated, Result, ServiceError, ServiceErrorCode } from "@k2b/stdlib";
+export { crypto, err, fail, isServiceError, ok, okMany, paginate, password, svg, tryCatch, unwrap } from "@k2b/stdlib";
+
+// Compat aliases for old API names
+export const images = { generateFallback: _svg.generateAvatar, parseWebpDataUrl: _svg.parseWebpDataUrl };
+export const generatePassword = _password.random;

package/src/server/services/pagination.ts

@@ -0,0 +1,22 @@
+import { type PageParams, type Paginated, paginate } from "@k2b/stdlib";
+
+export const paginateItems = <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,
+  };
+};

package/src/server/services/services.ts

@@ -0,0 +1,13 @@
+import { err, fail, isServiceError, ok, okMany, paginate, password, svg, tryCatch, unwrap } from "@k2b/stdlib";
+import * as access from "./access";
+import { freeipa } from "./freeipa";
+import { geo } from "./geo";
+
+export const services = {
+  access,
+  freeipa,
+  geo,
+  images: { generateFallback: svg.generateAvatar, parseWebpDataUrl: svg.parseWebpDataUrl },
+  password,
+  result: { ok, okMany, fail, err, unwrap, paginate, tryCatch, isServiceError },
+} as const;

package/src/server/time.ts

@@ -0,0 +1,33 @@
+import type { DateContext } from "@k2b/stdlib";
+import { normalizeTimeZone, TIMEZONE_COOKIE } from "../shared/time";
+import { getLocale } from "./locale";
+import { readCookie } from "./request-cookies";
+
+export { TIMEZONE_COOKIE };
+
+type TimeContext = {
+  get(key: "settings"): Record<string, any> | undefined;
+  req: { raw: { headers: Headers } };
+};
+
+export const getTimeZone = (c: TimeContext): string => {
+  const settingsTimeZone = c.get("settings")?.app?.timezone;
+  const fallback = normalizeTimeZone(typeof settingsTimeZone === "string" ? settingsTimeZone : undefined, "UTC");
+  return normalizeTimeZone(readCookie(c.req.raw.headers, TIMEZONE_COOKIE), fallback);
+};
+
+/**
+ * Request-scoped date config for stdlib formatters: the viewer's timezone and
+ * the canonical request locale, resolved independently of each other.
+ */
+export const getDateConfig = (c: TimeContext): DateContext => ({
+  timeZone: getTimeZone(c),
+  locale: getLocale(c),
+  firstDayOfWeek: 1,
+});
+
+export const time = {
+  TIMEZONE_COOKIE,
+  getTimeZone,
+  getDateConfig,
+} as const;

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

@@ -0,0 +1,51 @@
+import { sql } from "bun";
+import {
+  type AccountCategory,
+  type AccountCategoryPolicy,
+  accountCategory,
+  DEFAULT_ACCOUNT_CATEGORY_POLICY,
+} from "../contracts/account-categories";
+import { decryptValue } from "./settings/crypto";
+
+const prefix = "user.category.";
+
+// Authorization reads the durable value directly. A stale settings cache must
+// not re-enable a category after an operator has disabled it.
+const readValue = async (key: string, fallback: boolean | string, db: typeof sql): Promise<boolean | string> => {
+  const [row] = await db<{ value: string }[]>`SELECT value FROM settings.entries WHERE key = ${prefix + key}`;
+  if (!row) return fallback;
+  const value: unknown = await decryptValue(row.value);
+  if (typeof value !== typeof fallback) throw new Error("Invalid account category configuration");
+  if (typeof value !== "string" && 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,
+): Promise<boolean> => (await readValue(`${accountCategory(user)}.enabled`, true, db)) === true;
+
+export const readAccountCategoryPolicy = async (db: typeof sql = sql): Promise<AccountCategoryPolicy> => {
+  const policy = structuredClone(DEFAULT_ACCOUNT_CATEGORY_POLICY);
+  const rows = await db<
+    { key: string; value: string }[]
+  >`SELECT key, value FROM settings.entries WHERE key IN ('user.category.guest.enabled', 'user.category.guest.visible', 'user.category.login.enabled', 'user.category.login.visible', 'user.category.login.label', 'user.category.freeipa.enabled', 'user.category.freeipa.visible')`;
+  const values = new Map(
+    await Promise.all(rows.map(async (row) => [row.key.slice(prefix.length), await decryptValue(row.value)] as const)),
+  );
+  for (const category of ["guest", "login", "freeipa"] satisfies AccountCategory[]) {
+    for (const field of ["enabled", "visible"] as const) {
+      const key = `${category}.${field}`;
+      if (!values.has(key)) continue;
+      const value = values.get(key);
+      if (typeof value !== "boolean") throw new Error("Invalid account category configuration");
+      policy[category][field] = value;
+    }
+  }
+  if (values.has("login.label")) {
+    const label = values.get("login.label");
+    if (typeof label !== "string") throw new Error("Invalid account category configuration");
+    policy.login.label = label.trim() || "Login";
+  }
+  return policy;
+};

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

@@ -0,0 +1,41 @@
+import { sql } from "bun";
+import type { UserProfile, UserProvider } from "../../contracts/shared";
+
+export type DeletedAccountReason =
+  | "ipa_expired_demoted"
+  | "ipa_expired_deleted"
+  | "sync_out_of_scope_demoted"
+  | "sync_out_of_scope_deleted"
+  | "guest_expired_deleted"
+  | "local_user_expired_deleted"
+  | "manual_delete"
+  | "manual_demote";
+
+type SqlExecutor = typeof sql;
+
+export const writeDeletedAccountAudit = async (config: {
+  userId: string;
+  uid: string;
+  mail: string | null;
+  displayName: string | null;
+  previousProvider: UserProvider;
+  previousProfile: UserProfile;
+  reason: DeletedAccountReason;
+  meta?: Record<string, unknown>;
+  db?: SqlExecutor;
+}): Promise<void> => {
+  const db = config.db ?? sql;
+  await db`
+    INSERT INTO auth.deleted_accounts (deleted_user_id, uid, mail, display_name, previous_provider, previous_profile, reason, meta)
+    VALUES (
+      ${config.userId}::uuid,
+      ${config.uid},
+      ${config.mail},
+      ${config.displayName},
+      ${config.previousProvider},
+      ${config.previousProfile},
+      ${config.reason},
+      ${JSON.stringify(config.meta ?? {})}::jsonb
+    )
+  `;
+};