@valentinkolb/cloud 0.1.0

package/src/_internal/heartbeat.ts

@@ -0,0 +1,33 @@
+/**
+ * Simple heartbeat for app registry entries.
+ * Uses setInterval — KISS over scheduler+job+cron.
+ *
+ * The entry's TTL is set on the ephemeral-store factory (see ./registry.ts);
+ * `touch` extends that TTL without re-sending the value. A failed touch means
+ * the entry has expired and we fall back to `upsert` to re-seed it.
+ */
+import { appRegistry } from "./registry";
+import type { AppRegistryEntry } from "../contracts/registry";
+
+const HEARTBEAT_INTERVAL_MS = 60_000;
+
+export const createHeartbeat = (appId: string, entry: AppRegistryEntry) => {
+  let timer: Timer | null = null;
+  const key = `apps/${appId}`;
+
+  return {
+    start: async () => {
+      await appRegistry.upsert({ key, value: entry });
+      timer = setInterval(async () => {
+        const result = await appRegistry.touch({ key });
+        if (!result.ok) {
+          await appRegistry.upsert({ key, value: entry });
+        }
+      }, HEARTBEAT_INTERVAL_MS);
+    },
+    stop: async () => {
+      if (timer) clearInterval(timer);
+      await appRegistry.remove({ key });
+    },
+  };
+};

package/src/_internal/registry.ts

@@ -0,0 +1,100 @@
+import { ephemeral } from "@valentinkolb/sync";
+import type { AppRegistryEntry } from "../contracts/registry";
+
+/**
+ * Shared app registry backed by Redis via @valentinkolb/sync ephemeral store.
+ * Replaces the v4 `registry` module with `ephemeral<T>` + prefix filter.
+ *
+ * TTL is 3× the heartbeat interval (see `./heartbeat.ts`).
+ */
+const REGISTRY_TTL_MS = 120_000;
+
+export const appRegistry = ephemeral<AppRegistryEntry>({
+  id: "cloud-apps",
+  ttlMs: REGISTRY_TTL_MS,
+});
+
+/**
+ * App entry enriched with registry metadata.
+ * `createdAt` = first registration of the container (uptime anchor).
+ * `updatedAt` = most recent heartbeat touch.
+ */
+export type AppRegistryDetail = AppRegistryEntry & {
+  createdAt: number;
+  updatedAt: number;
+  expiresAt: number;
+  version: string;
+};
+
+/**
+ * List all currently live (TTL-valid) app registry entries.
+ */
+export const listApps = async (): Promise<AppRegistryEntry[]> => {
+  const snap = await appRegistry.snapshot({ prefix: "apps/" });
+  return snap.entries.map((e) => e.value);
+};
+
+/**
+ * Same as `listApps` but returns registry metadata for admin observability.
+ */
+export const listAppsDetailed = async (): Promise<AppRegistryDetail[]> => {
+  const snap = await appRegistry.snapshot({ prefix: "apps/" });
+  return snap.entries.map((e) => ({
+    ...e.value,
+    createdAt: e.createdAt,
+    updatedAt: e.updatedAt,
+    expiresAt: e.expiresAt,
+    version: e.version,
+  }));
+};
+
+/**
+ * Aggregate every running app's `legalLinks` into one flat list. Used by the
+ * login footer, app Footer, and rail "more" dropdown to render a unified set
+ * of legal/info links (Imprint, Privacy, Terms, FAQ, …).
+ *
+ * Order = registration order across apps (no explicit weights — KISS). Within
+ * one app, declaration order is preserved. Duplicate `href`s are de-duped
+ * (last-seen wins).
+ */
+export const listLegalLinks = async (): Promise<Array<{ label: string; href: string; icon?: string }>> => {
+  const apps = await listApps();
+  const seen = new Map<string, { label: string; href: string; icon?: string }>();
+  for (const app of apps) {
+    for (const link of app.legalLinks ?? []) seen.set(link.href, { ...link });
+  }
+  return [...seen.values()];
+};
+
+/**
+ * Aggregate every running app's widget endpoints into one flat list. Used by
+ * the dashboard app to build the widget grid: it fetches each widget URL
+ * with the user's session forwarded and renders the response.
+ *
+ * Order = registration order across apps.
+ */
+export type DashboardWidget = {
+  appId: string;
+  appName: string;
+  appIcon: string;
+  widgetId: string;
+  /** Fully-qualified URL — `<baseUrl>/<path>`. */
+  url: string;
+};
+
+export const listWidgets = async (): Promise<DashboardWidget[]> => {
+  const apps = await listApps();
+  const out: DashboardWidget[] = [];
+  for (const app of apps) {
+    for (const w of app.widgets ?? []) {
+      out.push({
+        appId: app.id,
+        appName: app.name,
+        appIcon: app.icon,
+        widgetId: w.id,
+        url: `${app.baseUrl.replace(/\/$/, "")}${w.path.startsWith("/") ? w.path : `/${w.path}`}`,
+      });
+    }
+  }
+  return out;
+};

package/src/_internal/runtime-context.ts

@@ -0,0 +1,38 @@
+import type { CloudRuntime, RuntimeAppMeta } from "../contracts/app";
+import type { AppRegistryEntry } from "../contracts/registry";
+import type { Role } from "../contracts/shared";
+
+/**
+ * Builds a `CloudRuntime` (the shape consumed by Layout, AdminSidebar, NavMenu)
+ * from registry entries.
+ *
+ * This produces the exact same shape as `createRuntimeContext()` in core/runtime.ts,
+ * so all existing UI components work unchanged.
+ */
+export const buildRuntimeFromRegistry = (entries: AppRegistryEntry[]): CloudRuntime => ({
+  apps: entries.map(
+    (e): RuntimeAppMeta => ({
+      id: e.id,
+      name: e.name,
+      icon: e.icon,
+      description: e.description,
+      adminHref: e.nav?.adminHref,
+      routes: e.routes,
+      nav: e.nav
+        ? {
+            href: e.nav.href,
+            match: e.nav.match,
+            section: e.nav.section,
+            requiresAuth: e.nav.requiresAuth,
+            // Registry stores roles as serialized strings; the source type is
+            // Role[] and round-trip is value-preserving.
+            requiresRoles: e.nav.requiresRoles as Role[] | undefined,
+          }
+        : undefined,
+      searchTags: e.search?.tags,
+      searchHelp: e.search?.help,
+      searchTagHelp: e.search?.tagHelp,
+      legalLinks: e.legalLinks ? e.legalLinks.map((l) => ({ ...l })) : undefined,
+    }),
+  ),
+});

package/src/api/accounts-entities.ts

@@ -0,0 +1,134 @@
+import { Hono } from "hono";
+import { describeRoute } from "hono-openapi";
+import { z } from "zod";
+import { accountsAppService as accountsService } from "../services";
+import { respond, auth, jsonResponse, requiresAuth, v } from "../server";
+import { err, fail } from "@valentinkolb/stdlib";
+import {
+  EntityKindSchema,
+  EntityListItemSchema,
+  ErrorResponseSchema,
+  PaginationQuerySchema,
+  PaginationResponseSchema,
+  UserProfileSchema,
+  UserProviderSchema,
+  createPagination,
+  parsePagination,
+} from "../contracts";
+
+const EntitiesListResponseSchema = z.object({
+  items: z.array(EntityListItemSchema),
+  pagination: PaginationResponseSchema,
+});
+
+const VALID_ENTITY_KINDS = new Set<z.infer<typeof EntityKindSchema>>(EntityKindSchema.options);
+
+const QuerySchema = z
+  .object({
+    ...PaginationQuerySchema.shape,
+    search: z.string().optional(),
+    kinds: z.string().optional(),
+    provider: UserProviderSchema.optional(),
+    profile: UserProfileSchema.optional(),
+    exclude_user_ids: z.string().optional(),
+    exclude_group_ids: z.string().optional(),
+    user_member_of_group_ids: z.string().optional(),
+    member_of_group_id: z.uuid().optional(),
+    manager_of_group_id: z.uuid().optional(),
+    parent_group_id: z.uuid().optional(),
+    managed_by_user_id: z.uuid().optional(),
+    recursive: z.enum(["true", "false"]).optional(),
+  })
+  .refine((value) => {
+    const relationFilters = [
+      value.member_of_group_id,
+      value.manager_of_group_id,
+      value.parent_group_id,
+      value.managed_by_user_id,
+    ].filter(Boolean);
+    return relationFilters.length <= 1;
+  }, {
+    message: "Only one relation filter can be used at a time.",
+    path: ["member_of_group_id"],
+  });
+
+const parseCsv = (value?: string) =>
+  value
+    ?.split(",")
+    .map((part) => part.trim())
+    .filter(Boolean) ?? [];
+
+const parseKinds = (value?: string) => {
+  const kinds = parseCsv(value);
+  if (kinds.length === 0) return { ok: true as const, value: undefined };
+  if (kinds.every((kind): kind is z.infer<typeof EntityKindSchema> => VALID_ENTITY_KINDS.has(kind as z.infer<typeof EntityKindSchema>))) {
+    return { ok: true as const, value: [...new Set(kinds)] };
+  }
+  return { ok: false as const, message: "Invalid kinds query parameter." };
+};
+
+const parseUuidList = (value: string | undefined, label: string) => {
+  const ids = parseCsv(value);
+  if (ids.length === 0) return { ok: true as const, value: undefined };
+  const parsed = z.array(z.uuid()).safeParse(ids);
+  if (parsed.success) {
+    return { ok: true as const, value: parsed.data };
+  }
+  return { ok: false as const, message: `Invalid ${label} query parameter.` };
+};
+
+const app = new Hono()
+  .get(
+    "/entities",
+    auth.requireRole("user"),
+    describeRoute({
+      tags: ["Accounts"],
+      summary: "List mixed users and groups",
+      description: "List users and groups together with SQL-backed filtering, relation scoping, and pagination.",
+      ...requiresAuth,
+      responses: {
+        200: jsonResponse(EntitiesListResponseSchema, "Paginated mixed entity list"),
+        401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+        403: jsonResponse(ErrorResponseSchema, "Full account required"),
+      },
+    }),
+    v("query", QuerySchema),
+    async (c) => {
+      const query = c.req.valid("query");
+      const params = parsePagination(query);
+      const kinds = parseKinds(query.kinds);
+      if (!kinds.ok) return respond(c, fail(err.badInput(kinds.message)));
+      const excludeUserIds = parseUuidList(query.exclude_user_ids, "exclude_user_ids");
+      if (!excludeUserIds.ok) return respond(c, fail(err.badInput(excludeUserIds.message)));
+      const excludeGroupIds = parseUuidList(query.exclude_group_ids, "exclude_group_ids");
+      if (!excludeGroupIds.ok) return respond(c, fail(err.badInput(excludeGroupIds.message)));
+      const userMemberOfGroupIds = parseUuidList(query.user_member_of_group_ids, "user_member_of_group_ids");
+      if (!userMemberOfGroupIds.ok) return respond(c, fail(err.badInput(userMemberOfGroupIds.message)));
+
+      const result = await accountsService.entity.list({
+        pagination: { page: params.page, perPage: params.perPage },
+        search: query.search,
+        kinds: kinds.value,
+        provider: query.provider,
+        profile: query.profile,
+        excludeUserIds: excludeUserIds.value,
+        excludeGroupIds: excludeGroupIds.value,
+        userMemberOfGroupIds: userMemberOfGroupIds.value,
+        memberOfGroupId: query.member_of_group_id,
+        managerOfGroupId: query.manager_of_group_id,
+        parentGroupId: query.parent_group_id,
+        managedByUserId: query.managed_by_user_id,
+        recursive: query.recursive === "true",
+      });
+
+      return respond(c, {
+        ok: true,
+        data: {
+          items: result.items,
+          pagination: createPagination(params, result.total),
+        },
+      });
+    },
+  );
+
+export default app;

package/src/api/admin-lifecycle.ts

@@ -0,0 +1,210 @@
+import { Hono } from "hono";
+import { describeRoute } from "hono-openapi";
+import { z } from "zod";
+import { v, jsonResponse, requiresAdmin, auth, type AuthContext, respond } from "../server";
+import { ok } from "@valentinkolb/stdlib";
+import { accountLifecycle, lifecycleJobs } from "../services";
+import { ErrorResponseSchema, MessageResponseSchema, PaginationQuerySchema, createPagination, parsePagination } from "../contracts";
+
+const DeletedAccountSchema = z.object({
+  id: z.uuid(),
+  deletedUserId: z.uuid(),
+  uid: z.string(),
+  mail: z.string().nullable(),
+  displayName: z.string().nullable(),
+  previousProvider: z.string().nullable(),
+  previousProfile: z.string().nullable(),
+  reason: z.string(),
+  deletedAt: z.string().datetime(),
+  meta: z.record(z.string(), z.unknown()),
+});
+
+const ReminderAuditSchema = z.object({
+  id: z.uuid(),
+  userId: z.uuid().nullable(),
+  uid: z.string().nullable(),
+  mail: z.string().nullable(),
+  displayName: z.string().nullable(),
+  kind: z.enum(["account_expiry"]),
+  thresholdDays: z.number().int().positive(),
+  targetExpiryAt: z.string().datetime(),
+  status: z.enum(["pending", "sent", "error"]),
+  attemptCount: z.number().int().nonnegative(),
+  lastAttemptAt: z.string().datetime().nullable(),
+  sentAt: z.string().datetime().nullable(),
+  lastError: z.string().nullable(),
+  createdAt: z.string().datetime(),
+});
+
+const DeletedAccountsResponseSchema = z.object({
+  items: z.array(DeletedAccountSchema),
+  pagination: z.object({
+    page: z.number(),
+    per_page: z.number(),
+    total: z.number(),
+    total_pages: z.number(),
+    has_next: z.boolean(),
+  }),
+});
+
+const ReminderAuditResponseSchema = z.object({
+  items: z.array(ReminderAuditSchema),
+  pagination: z.object({
+    page: z.number(),
+    per_page: z.number(),
+    total: z.number(),
+    total_pages: z.number(),
+    has_next: z.boolean(),
+  }),
+});
+
+const TriggerJobResponseSchema = z.object({
+  message: z.string(),
+  jobId: z.string(),
+});
+
+const app = new Hono<AuthContext>()
+  .use(auth.requireRole("admin"))
+  .get(
+    "/deleted-accounts",
+    describeRoute({
+      tags: ["Admin Lifecycle"],
+      summary: "List deleted account lifecycle entries",
+      ...requiresAdmin,
+      responses: {
+        200: jsonResponse(DeletedAccountsResponseSchema, "Deleted account lifecycle entries"),
+        401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+        403: jsonResponse(ErrorResponseSchema, "Admin access required"),
+      },
+    }),
+    v(
+      "query",
+      z.object({
+        ...PaginationQuerySchema.shape,
+        reason: z.string().optional(),
+        search: z.string().optional(),
+      }),
+    ),
+    async (c) => {
+      const query = c.req.valid("query");
+      const pagination = parsePagination(query);
+      const result = await accountLifecycle.listDeletedAccounts({
+        page: pagination.page,
+        perPage: pagination.perPage,
+        reason: query.reason,
+        search: query.search,
+      });
+
+      return c.json({
+        items: result.items,
+        pagination: createPagination(pagination, result.total),
+      });
+    },
+  )
+  .get(
+    "/reminders",
+    describeRoute({
+      tags: ["Admin Lifecycle"],
+      summary: "List reminder history entries",
+      ...requiresAdmin,
+      responses: {
+        200: jsonResponse(ReminderAuditResponseSchema, "Reminder history entries"),
+        401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+        403: jsonResponse(ErrorResponseSchema, "Admin access required"),
+      },
+    }),
+    v(
+      "query",
+      z.object({
+        ...PaginationQuerySchema.shape,
+        status: z.enum(["pending", "sent", "error"]).optional(),
+        kind: z.enum(["account_expiry"]).optional(),
+        search: z.string().optional(),
+      }),
+    ),
+    async (c) => {
+      const query = c.req.valid("query");
+      const pagination = parsePagination(query);
+      const result = await accountLifecycle.listReminderAudit({
+        page: pagination.page,
+        perPage: pagination.perPage,
+        status: query.status,
+        kind: query.kind,
+        search: query.search,
+      });
+
+      return c.json({
+        items: result.items,
+        pagination: createPagination(pagination, result.total),
+      });
+    },
+  )
+  // Single unified job-dispatch endpoint. The five RPC POSTs it replaces all
+  // mapped to `lifecycleJobs.submit*`; consolidating keeps the API surface
+  // small and makes adding job kinds a one-line change.
+  .post(
+    "/jobs",
+    describeRoute({
+      tags: ["Admin Lifecycle"],
+      summary: "Submit a lifecycle job",
+      description: "Dispatches one of the configured account-lifecycle jobs. Returns the submitted job ID.",
+      ...requiresAdmin,
+      responses: {
+        200: jsonResponse(TriggerJobResponseSchema, "Job submitted"),
+        400: jsonResponse(ErrorResponseSchema, "Unknown job kind"),
+        401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+        403: jsonResponse(ErrorResponseSchema, "Admin access required"),
+      },
+    }),
+    v(
+      "json",
+      z.object({
+        kind: z.enum(["ipa-sync", "ipa-backfill", "local-user-backfill", "guest-backfill", "reminders"]),
+      }),
+    ),
+    async (c) =>
+      respond(c, async () => {
+        const { kind } = c.req.valid("json");
+        switch (kind) {
+          case "ipa-sync":
+            return ok({ message: "IPA sync job submitted", jobId: await lifecycleJobs.submitIpaSync() });
+          case "ipa-backfill":
+            return ok({ message: "IPA backfill job submitted", jobId: await lifecycleJobs.submitIpaBackfill() });
+          case "local-user-backfill":
+            return ok({ message: "Local user backfill job submitted", jobId: await lifecycleJobs.submitLocalUserBackfill() });
+          case "guest-backfill":
+            return ok({ message: "Local guest backfill job submitted", jobId: await lifecycleJobs.submitGuestBackfill() });
+          case "reminders":
+            return ok({ message: "Reminder job submitted", jobId: await lifecycleJobs.submitReminderRun() });
+        }
+      }),
+  )
+  .get(
+    "/health",
+    describeRoute({
+      tags: ["Admin Lifecycle"],
+      summary: "Scheduler health metrics",
+      ...requiresAdmin,
+      responses: {
+        200: jsonResponse(z.object({ metrics: z.record(z.string(), z.unknown()) }), "Scheduler metrics"),
+        401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+        403: jsonResponse(ErrorResponseSchema, "Admin access required"),
+      },
+    }),
+    async (c) => c.json({ metrics: lifecycleJobs.metrics() }),
+  )
+  .get(
+    "/",
+    describeRoute({
+      tags: ["Admin Lifecycle"],
+      summary: "Lifecycle API root",
+      ...requiresAdmin,
+      responses: {
+        200: jsonResponse(MessageResponseSchema, "Lifecycle API available"),
+      },
+    }),
+    (c) => c.json({ message: "Account lifecycle admin API" }),
+  );
+
+export default app;
+export type ApiType = typeof app;

package/src/api/auth/schemas.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+import { UserSchema } from "../../contracts";
+
+export const LoginSchema = z.object({
+  username: z.string(),
+  password: z.string(),
+  acceptedAgb: z.literal(true),
+});
+
+export const EmailLoginSchema = z.object({
+  email: z.email(),
+  acceptedAgb: z.literal(true),
+});
+
+export const VerifyTokenSchema = z.object({
+  token: z.uuid(),
+  acceptedAgb: z.literal(true),
+});
+
+export const AdminLoginSchema = z.object({
+  token: z.string().min(1),
+});
+
+export const AuthResponseSchema = z.object({
+  session_token: z.string(),
+  user: UserSchema,
+});