@valentinkolb/cloud 0.1.0

package/src/contracts/widgets.ts

@@ -0,0 +1,121 @@
+/**
+ * Widget JSON contract — what an app's widget endpoint must return when the
+ * dashboard fetches it. Each block maps 1:1 to a `<Widget*>` SolidJS component
+ * (see `packages/cloud/src/ui/widgets/`).
+ *
+ * The dashboard fetches each widget endpoint with the user's cookie forwarded;
+ * the endpoint is responsible for permission gating:
+ *   - `200` + body  → render
+ *   - `204`         → skip silently (user has no permission / no content)
+ *   - anything else → log and skip
+ */
+
+export type WidgetTone = "emerald" | "amber" | "red" | "blue" | "zinc";
+
+export type WidgetAccent = {
+  tone: WidgetTone;
+  /** Tabler icon class, e.g. `"ti ti-trending-up"`. */
+  icon: string;
+  /** When set, renders as a pill with bg+text. Without text, plain colored icon. */
+  text?: string;
+};
+
+export type WidgetStatBlock = {
+  kind: "stat";
+  value: string | number;
+  label: string;
+  sub?: string;
+  /** Override the default value colour, e.g. `"text-amber-600 dark:text-amber-400"`. */
+  valueClass?: string;
+  accent?: WidgetAccent;
+  /** Block fills remaining vertical space inside the widget and centres its content. */
+  grow?: boolean;
+};
+
+export type WidgetListItem = {
+  icon?: string;
+  /** Override the default dimmed icon colour with a tone — useful for
+   *  conveying priority, status, or category at a glance. */
+  iconTone?: WidgetTone;
+  label: string;
+  sub?: string;
+  /** Right-aligned trailing meta (timestamp, count). */
+  meta?: string;
+  /** When set, the row becomes a clickable link. */
+  href?: string;
+};
+
+export type WidgetListBlock = {
+  kind: "list";
+  items: WidgetListItem[];
+  /** Shown when `items` is empty. */
+  emptyMessage?: string;
+  /** Block fills remaining vertical space (with internal scroll if needed). */
+  grow?: boolean;
+};
+
+export type WidgetStatusBlock = {
+  kind: "status";
+  tone: "ok" | "warn" | "error" | "info";
+  title: string;
+  message?: string;
+  /** Override the tone-default icon. */
+  icon?: string;
+  /** Block fills remaining vertical space and centres its content. */
+  grow?: boolean;
+};
+
+export type WidgetPill = {
+  label: string;
+  value: string | number;
+  tone?: WidgetTone;
+  href?: string;
+};
+
+export type WidgetPillsBlock = {
+  kind: "pills";
+  pills: WidgetPill[];
+  /** Block fills remaining vertical space and centres its content. */
+  grow?: boolean;
+};
+
+/**
+ * Hero block — single big centred message. Use for spotlight content like a
+ * quote, a single weather location, or empty-state messages ("All clear",
+ * "No locations saved yet"). Always grows to fill available space.
+ */
+export type WidgetHeroBlock = {
+  kind: "hero";
+  /** Big centred line, e.g. quote text, "14°C · partly cloudy", "All caught up". */
+  title: string;
+  /** Smaller dimmed line below the title, e.g. author, city, hint. */
+  subtitle?: string;
+  /** Tabler icon class shown above the title. */
+  icon?: string;
+  /** Tone for the icon. Defaults to dimmed. */
+  tone?: WidgetTone;
+};
+
+/** Discriminated union of every block type the dashboard can render. */
+export type WidgetBlock =
+  | WidgetStatBlock
+  | WidgetListBlock
+  | WidgetStatusBlock
+  | WidgetPillsBlock
+  | WidgetHeroBlock;
+
+/**
+ * Top-level shape returned by a widget endpoint. The dashboard renders the
+ * `<Widget>` container with the given title/icon/href/meta, then stacks the
+ * blocks vertically — composition is open: any number, any order.
+ */
+export type WidgetResponse = {
+  title: string;
+  /** Tabler icon class for the widget header. */
+  icon?: string;
+  /** When set, the widget header becomes a link to this URL. */
+  href?: string;
+  /** Tiny meta string in the header (e.g. "last 24h"). */
+  meta?: string;
+  blocks: WidgetBlock[];
+};

package/src/index.ts

@@ -0,0 +1,6 @@
+export { defineApp } from "./_internal/define-app";
+export type { AppOptions, StartOptions, StartResult, AppDefinition } from "./_internal/define-app";
+export { appRegistry, listApps, listAppsDetailed, listLegalLinks, listWidgets } from "./_internal/registry";
+export type { AppRegistryDetail, DashboardWidget } from "./_internal/registry";
+export { createHeartbeat } from "./_internal/heartbeat";
+export { buildRuntimeFromRegistry } from "./_internal/runtime-context";

package/src/server/api/index.ts

@@ -0,0 +1 @@
+export { api, respond } from "./respond";

package/src/server/api/respond.ts

@@ -0,0 +1,55 @@
+import type { Context } from "hono";
+import { isServiceError, type Result } from "@valentinkolb/stdlib";
+
+type LegacyResult<T = void> = { ok: true; data: T } | { ok: false; error: string; status: number };
+
+type AnyResult<T = unknown> = Result<T> | LegacyResult<T>;
+
+type ErrorResponseBody = {
+  message: string;
+  code?: string;
+};
+
+const toErrorResponse = (result: AnyResult): [ErrorResponseBody, number] => {
+  if (result.ok) {
+    throw new Error("toErrorResponse called with successful result");
+  }
+
+  // Legacy shape: { ok: false, error: string, status: number }
+  if ("status" in result && typeof result.status === "number") {
+    return [{ message: result.error }, result.status];
+  }
+
+  // New shape: { ok: false, error: ServiceError }
+  if (isServiceError(result.error)) {
+    return [
+      {
+        message: result.error.message,
+        code: result.error.code,
+      },
+      result.error.status,
+    ];
+  }
+
+  // Defensive fallback
+  return [{ message: "Internal server error", code: "INTERNAL" }, 500];
+};
+
+export const respond = async <T>(
+  c: Context,
+  resultOrFn: AnyResult<T> | Promise<AnyResult<T>> | (() => AnyResult<T> | Promise<AnyResult<T>>),
+  successStatus = 200,
+) => {
+  const result = typeof resultOrFn === "function" ? await resultOrFn() : await resultOrFn;
+
+  if (!result.ok) {
+    const [body, status] = toErrorResponse(result);
+    return c.json(body, status as 400 | 401 | 403 | 404 | 409 | 500);
+  }
+
+  return c.json(result.data, successStatus as 200 | 201);
+};
+
+export const api = {
+  respond,
+} as const;

package/src/server/api-client.ts

@@ -0,0 +1,54 @@
+import { hc } from "hono/client";
+import type { Hono } from "hono";
+
+export type CreateApiClientConfig = {
+  baseUrl?: string;
+};
+
+// ==========================
+// API Client
+// ==========================
+
+/**
+ * Creates a typed Hono API client.
+ */
+export const createApiClient = <TApi extends Hono<any, any, any>>(config: CreateApiClientConfig = {}) => hc<TApi>(config.baseUrl ?? "/api");
+
+/**
+ * Untyped fallback API client for core-only browser code.
+ */
+export const apiClient: any = hc("/api");
+
+// ==========================
+// Clipboard
+// ==========================
+
+/**
+ * Copies text to the clipboard.
+ * Fails silently with console error if clipboard API is unavailable.
+ */
+export const copyToClipboard = async (text: string): Promise<void> => {
+  try {
+    await navigator.clipboard.writeText(text);
+  } catch (err) {
+    console.error("Failed to copy:", err);
+  }
+};
+
+/**
+ * Checks if a value is an image URL served by the API.
+ * Used to determine if an image field contains an existing server URL or new base64 data.
+ */
+export const isImageUrl = (value: string | null | undefined): boolean => typeof value === "string" && value.includes("/avatar");
+
+export const api = {
+  create: createApiClient,
+} as const;
+
+export const clipboard = {
+  copy: copyToClipboard,
+} as const;
+
+export const url = {
+  isImage: isImageUrl,
+} as const;

package/src/server/app-context.ts

@@ -0,0 +1,39 @@
+/**
+ * `AppContext<App>` — Hono context type for routes mounted by an app.
+ *
+ * Combines the existing `AuthContext` variables (user, sessionToken) with a
+ * typed per-request settings snapshot derived from the app's `defineApp.settings`
+ * declaration.
+ *
+ * Convention: each app exports a named alias from its `index.ts`:
+ *
+ *   ```ts
+ *   import { app } from "./config";
+ *   import type { AppContext } from "@valentinkolb/cloud/server";
+ *   export type FilesAppContext = AppContext<typeof app>;
+ *   ```
+ *
+ * Then routes:
+ *
+ *   ```ts
+ *   import { type FilesAppContext } from "..";
+ *   new Hono<FilesAppContext>().get("/", (c) => {
+ *     const s = c.get("settings");          // typed nested readonly object
+ *     s.app.name                             // string (from core's settings)
+ *     s.files.filegate_url                   // string (from app-files's own settings)
+ *   });
+ *   ```
+ *
+ * The `settings` variable is populated by the per-request snapshot middleware
+ * registered by `app.start()`; the snapshot is frozen for the duration of the
+ * request.
+ */
+import type { AppDefinition } from "../_internal/define-app";
+import type { AppSettings } from "../contracts/settings-types";
+import type { AuthContext } from "./middleware/auth";
+
+export type AppContext<App extends AppDefinition<any>> = {
+  Variables: AuthContext["Variables"] & {
+    settings: AppSettings<App>;
+  };
+};

package/src/server/index.ts

@@ -0,0 +1,62 @@
+export { api, respond } from "./api";
+export { api as apiClient } from "./api-client";
+export type { CreateApiClientConfig } from "./api-client";
+
+export {
+  middleware,
+  auth,
+  jsonResponse,
+  imageResponse,
+  openApiMeta,
+  requiresAuth,
+  requiresAdmin,
+  requiresIpa,
+  requiresIpaUser,
+  requiresUser,
+  rateLimit,
+  requestLogger,
+  validator,
+  v,
+} from "./middleware";
+export type { AuthContext, RateLimitConfig, RateLimitRouteOverride } from "./middleware";
+export type { AppContext } from "./app-context";
+
+export {
+  services,
+  freeipa,
+  images,
+  password,
+  generatePassword,
+  geo,
+  geoService,
+  PERMISSION_LEVELS,
+  hasPermission,
+  createAccess,
+  getAccess,
+  updateAccess,
+  deleteAccess,
+  getEffectivePermission,
+  resolveDisplayNames,
+  ok,
+  okMany,
+  fail,
+  err,
+  unwrap,
+  paginate,
+  tryCatch,
+  isServiceError,
+} from "./services";
+export type {
+  AccessEntry,
+  PermissionLevel,
+  PrincipalType,
+  Principal,
+  ResourceAccessAdapter,
+  GeoService,
+  GeoPlace,
+  Result,
+  Paginated,
+  PageParams,
+  ServiceError,
+  ServiceErrorCode,
+} from "./services";

package/src/server/middleware/auth.ts

@@ -0,0 +1,168 @@
+import type { Context } from "hono";
+import { createMiddleware } from "hono/factory";
+import type { MessageResponse, Role, RoleOrSpecial, User, UserProfile, UserProvider } from "../../contracts/shared";
+import { accounts } from "../../services/accounts";
+import { session } from "../../services/session";
+
+// ==========================
+// Types
+// ==========================
+
+/** Hono context with authenticated user variables. */
+export type AuthContext = {
+  Variables: {
+    user: User;
+    sessionToken: string;
+  };
+};
+
+// ==========================
+// Role-based Middleware
+// ==========================
+
+type RejectResult = string | Response | { message: string; status: number };
+
+type RoleOptions = {
+  onReject?: (c: Context, reason: "unauthenticated" | "forbidden") => RejectResult;
+};
+
+type AccountOptions = RoleOptions & {
+  provider?: UserProvider;
+  profile?: UserProfile;
+};
+
+const handleReject = (c: Context, options: RoleOptions, reason: "unauthenticated" | "forbidden"): Response | Promise<Response> => {
+  if (options.onReject) {
+    const result = options.onReject(c, reason);
+    if (typeof result === "string") return c.redirect(result);
+    if (result instanceof Response) return result;
+    return c.json({ message: result.message } as MessageResponse, result.status as 400 | 401 | 403 | 404 | 500);
+  }
+  // Default: JSON response
+  if (reason === "unauthenticated") {
+    return c.json({ message: "Authentication required" } as MessageResponse, 401);
+  }
+  return c.json({ message: "Insufficient permissions" } as MessageResponse, 403);
+};
+
+const loadSessionUser = async (c: Context<AuthContext>): Promise<{ token: string | null; user: User | null }> => {
+  const token = session.getToken(c);
+  const data = token ? await session.getData(token) : null;
+  const user = data ? await accounts.users.get({ id: data.userId }) : null;
+
+  if (user && token) {
+    c.set("user", user);
+    c.set("sessionToken", token);
+  }
+
+  return { token, user };
+};
+
+/**
+ * Universal auth middleware. Handles authentication AND authorization.
+ *
+ * @param args - Roles to check (OR logic) + optional RoleOptions at the end. Special roles:
+ *   - "*": No check, always passes (like optionalAuth)
+ *   - "authenticated": Any logged-in user
+ *   - "anonymous": Only non-logged-in users (for login page)
+ *
+ * @example
+ * // API: Only admins (returns JSON 401/403)
+ * .use(requireRole("admin"))
+ *
+ * // API: Admins OR group managers
+ * .use(requireRole("admin", "group-manager"))
+ *
+ * // SSR: Admin area with redirect
+ * .use(requireRole("admin", redirect("/")))
+ *
+ * // SSR: Protected page with login redirect
+ * .use(requireRole("authenticated", redirectToLogin))
+ *
+ * // SSR: Login page (only for non-logged-in users)
+ * .use(requireRole("anonymous", redirect("/")))
+ */
+const requireRole = (...args: (RoleOrSpecial | RoleOptions)[]) => {
+  // Parse args: roles + optional options at the end
+  const lastArg = args[args.length - 1];
+  const hasOptions = typeof lastArg === "object" && lastArg !== null && "onReject" in lastArg;
+  const options: RoleOptions = hasOptions ? (args.pop() as RoleOptions) : {};
+  const roles = args as RoleOrSpecial[];
+
+  return createMiddleware<AuthContext>(async (c, next) => {
+    // "*" = no check at all, pass through (but try to load user)
+    if (roles.includes("*")) {
+      await loadSessionUser(c);
+      return next();
+    }
+
+    const { user } = await loadSessionUser(c);
+
+    // "anonymous" = must NOT be logged in
+    if (roles.includes("anonymous")) {
+      if (user) {
+        return handleReject(c, options, "forbidden");
+      }
+      return next();
+    }
+
+    // All other roles require authentication
+    if (!user) {
+      return handleReject(c, options, "unauthenticated");
+    }
+
+    // "authenticated" = any logged-in user
+    if (roles.includes("authenticated")) {
+      return next();
+    }
+
+    // Check if user has at least one required role
+    const hasRequiredRole = roles.some((role) => user.roles.includes(role as Role));
+    if (!hasRequiredRole) {
+      return handleReject(c, options, "forbidden");
+    }
+
+    return next();
+  });
+};
+
+/** Preset: Redirect to a fixed URL on rejection */
+const redirect = (url: string): RoleOptions => ({
+  onReject: () => url,
+});
+
+/** Preset: Redirect to login page with returnTo parameter */
+const redirectToLogin: RoleOptions = {
+  onReject: (c) => `/auth/login?redirectTo=${encodeURIComponent(new URL(c.req.url).pathname)}`,
+};
+
+const requireAccount = (options: AccountOptions) =>
+  createMiddleware<AuthContext>(async (c, next) => {
+    const { user } = await loadSessionUser(c);
+
+    if (!user) {
+      return handleReject(c, options, "unauthenticated");
+    }
+
+    if (options.provider && user.provider !== options.provider) {
+      return handleReject(c, options, "forbidden");
+    }
+
+    if (options.profile && user.profile !== options.profile) {
+      return handleReject(c, options, "forbidden");
+    }
+
+    return next();
+  });
+
+// ==========================
+// Export
+// ==========================
+
+export const auth = {
+  session,
+  requireRole,
+  requireAccount,
+  redirect,
+  redirectToLogin,
+};

package/src/server/middleware/index.ts

@@ -0,0 +1,7 @@
+export { middleware } from "./middleware";
+
+export { auth, type AuthContext } from "./auth";
+export { jsonResponse, imageResponse, openApiMeta, requiresAuth, requiresAdmin, requiresIpa, requiresIpaUser, requiresUser } from "./openapi";
+export { rateLimit, type RateLimitConfig, type RateLimitRouteOverride } from "./rate-limit";
+export { requestLogger } from "./request-logger";
+export { validator, v } from "./validator";

package/src/server/middleware/middleware.ts

@@ -0,0 +1,47 @@
+import { auth } from "./auth";
+import { imageResponse, jsonResponse, openApiMeta, requiresAdmin, requiresAuth, requiresIpa, requiresIpaUser, requiresUser } from "./openapi";
+import { rateLimit } from "./rate-limit";
+import { requestLogger } from "./request-logger";
+import { validator, v } from "./validator";
+
+export const middleware = {
+  get auth() {
+    return auth;
+  },
+  get jsonResponse() {
+    return jsonResponse;
+  },
+  get imageResponse() {
+    return imageResponse;
+  },
+  get openApiMeta() {
+    return openApiMeta;
+  },
+  get requiresAuth() {
+    return requiresAuth;
+  },
+  get requiresAdmin() {
+    return requiresAdmin;
+  },
+  get requiresIpa() {
+    return requiresIpa;
+  },
+  get requiresIpaUser() {
+    return requiresIpaUser;
+  },
+  get requiresUser() {
+    return requiresUser;
+  },
+  get rateLimit() {
+    return rateLimit;
+  },
+  get requestLogger() {
+    return requestLogger;
+  },
+  get validator() {
+    return validator;
+  },
+  get v() {
+    return v;
+  },
+} as const;

package/src/server/middleware/openapi.ts

@@ -0,0 +1,126 @@
+import { resolver, type GenerateSpecOptions } from "hono-openapi";
+import type { ZodType } from "zod";
+
+// ==========================
+// Response Helpers
+// ==========================
+
+/**
+ * Helper to define JSON response schema for OpenAPI documentation.
+ *
+ * @param schema - Zod schema for the response body
+ * @param description - Human-readable description of the response
+ * @returns OpenAPI response object with application/json content type
+ */
+export const jsonResponse = <T extends ZodType>(schema: T, description: string) => ({
+  description,
+  content: {
+    "application/json": {
+      schema: resolver(schema),
+    },
+  },
+});
+
+/**
+ * Helper to define image response for OpenAPI documentation.
+ *
+ * @param description - Human-readable description of the response
+ * @returns OpenAPI response object with image/webp content type
+ */
+export const imageResponse = (description: string) => ({
+  description,
+  content: {
+    "image/webp": {
+      schema: { type: "string" as const, format: "binary" },
+    },
+  },
+});
+
+// ==========================
+// OpenAPI Specification
+// ==========================
+
+/**
+ * OpenAPI spec metadata for the API documentation.
+ * Includes info, tags, and security schemes.
+ */
+export const openApiMeta: Partial<GenerateSpecOptions> = {
+  documentation: {
+    info: {
+      // Hardcoded — the OpenAPI spec is generated at module-load and
+      // settings reads are async. The dynamic per-deployment app name
+      // appears elsewhere (Layout header, page titles).
+      title: "Cloud API",
+      version: "0.0.1",
+      description: "IPA Management Tool API",
+    },
+    servers: [{ url: "/api", description: "API Server" }],
+    tags: [
+      {
+        name: "Auth",
+        description: "Authentication endpoints (login, logout, refresh)",
+      },
+      { name: "Users", description: "User listing and search (admin)" },
+      { name: "Groups", description: "Group listing and search (admin)" },
+    ],
+    components: {
+      securitySchemes: {
+        cookieAuth: {
+          type: "apiKey",
+          in: "cookie",
+          name: "session_token",
+          description: "Session cookie (automatically set after login)",
+        },
+        bearerAuth: {
+          type: "http",
+          scheme: "bearer",
+          description: "Bearer token in Authorization header",
+        },
+      },
+    },
+  },
+};
+
+// ==========================
+// Security Requirements
+// ==========================
+
+/**
+ * Security requirement for routes that need authentication.
+ * Accepts either cookie or bearer token.
+ */
+export const requiresAuth = {
+  security: [{ cookieAuth: [] as string[], bearerAuth: [] as string[] }],
+};
+
+/**
+ * Security requirement for routes that need admin role.
+ * Accepts either cookie or bearer token.
+ */
+export const requiresAdmin = {
+  security: [{ cookieAuth: [] as string[], bearerAuth: [] as string[] }],
+};
+
+/**
+ * Security requirement for routes that need any authenticated user.
+ * Accepts either cookie or bearer token.
+ */
+export const requiresIpa = {
+  security: [{ cookieAuth: [] as string[], bearerAuth: [] as string[] }],
+};
+
+/**
+ * Security requirement for routes that need a full user profile.
+ * Accepts either cookie or bearer token.
+ */
+export const requiresUser = {
+  security: [{ cookieAuth: [] as string[], bearerAuth: [] as string[] }],
+};
+
+/**
+ * Security requirement for routes that need an IPA-backed full user.
+ * Accepts either cookie or bearer token.
+ */
+export const requiresIpaUser = {
+  security: [{ cookieAuth: [] as string[], bearerAuth: [] as string[] }],
+};