npm - @valentinkolb/cloud - Versions diffs - 0.1.0 - Mend

@valentinkolb/cloud 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (196) hide show

package/package.json +69 -0
package/public/logo.svg +1 -0
package/scripts/build.ts +113 -0
package/scripts/preload.ts +73 -0
package/src/_internal/define-app.ts +399 -0
package/src/_internal/heartbeat.ts +33 -0
package/src/_internal/registry.ts +100 -0
package/src/_internal/runtime-context.ts +38 -0
package/src/api/accounts-entities.ts +134 -0
package/src/api/admin-lifecycle.ts +210 -0
package/src/api/auth/schemas.ts +28 -0
package/src/api/auth.ts +230 -0
package/src/api/index.ts +66 -0
package/src/api/me.ts +206 -0
package/src/api/search/schemas.ts +43 -0
package/src/api/search.ts +130 -0
package/src/clients/core.ts +19 -0
package/src/config/env.ts +23 -0
package/src/config/index.ts +6 -0
package/src/config/ssr.ts +58 -0
package/src/contracts/app.ts +140 -0
package/src/contracts/index.ts +5 -0
package/src/contracts/profile.ts +67 -0
package/src/contracts/registry.ts +50 -0
package/src/contracts/settings-types.ts +84 -0
package/src/contracts/shared.ts +258 -0
package/src/contracts/widgets.ts +121 -0
package/src/index.ts +6 -0
package/src/server/api/index.ts +1 -0
package/src/server/api/respond.ts +55 -0
package/src/server/api-client.ts +54 -0
package/src/server/app-context.ts +39 -0
package/src/server/index.ts +62 -0
package/src/server/middleware/auth.ts +168 -0
package/src/server/middleware/index.ts +7 -0
package/src/server/middleware/middleware.ts +47 -0
package/src/server/middleware/openapi.ts +126 -0
package/src/server/middleware/rate-limit.ts +126 -0
package/src/server/middleware/request-logger.ts +41 -0
package/src/server/middleware/validator.ts +35 -0
package/src/server/services/access.ts +294 -0
package/src/server/services/freeipa/client.ts +100 -0
package/src/server/services/freeipa/index.ts +9 -0
package/src/server/services/freeipa/session.ts +78 -0
package/src/server/services/freeipa/tls.ts +48 -0
package/src/server/services/freeipa/util.ts +60 -0
package/src/server/services/geo.ts +154 -0
package/src/server/services/index.ts +28 -0
package/src/server/services/services.ts +13 -0
package/src/services/account-lifecycle/audit.ts +41 -0
package/src/services/account-lifecycle/index.ts +907 -0
package/src/services/account-lifecycle/scheduler.ts +347 -0
package/src/services/account-model.ts +21 -0
package/src/services/accounts/app.ts +966 -0
package/src/services/accounts/authz.ts +22 -0
package/src/services/accounts/base-group.ts +11 -0
package/src/services/accounts/base-user.ts +45 -0
package/src/services/accounts/entities.ts +529 -0
package/src/services/accounts/group-sql.ts +106 -0
package/src/services/accounts/groups.ts +246 -0
package/src/services/accounts/index.ts +14 -0
package/src/services/accounts/ipa-data.ts +64 -0
package/src/services/accounts/lifecycle.ts +2 -0
package/src/services/accounts/local-groups.ts +491 -0
package/src/services/accounts/model.ts +135 -0
package/src/services/accounts/switching.ts +117 -0
package/src/services/accounts/users.ts +714 -0
package/src/services/auth-flows/index.ts +6 -0
package/src/services/auth-flows/ipa.ts +128 -0
package/src/services/auth-flows/magic-link.ts +119 -0
package/src/services/freeipa-config.ts +89 -0
package/src/services/index.ts +46 -0
package/src/services/ipa/auth.ts +122 -0
package/src/services/ipa/groups.ts +684 -0
package/src/services/ipa/guard.ts +17 -0
package/src/services/ipa/index.ts +17 -0
package/src/services/ipa/profile.ts +90 -0
package/src/services/ipa/search.ts +154 -0
package/src/services/ipa/sync.ts +740 -0
package/src/services/ipa/users.ts +794 -0
package/src/services/logging/index.ts +294 -0
package/src/services/notifications/email.ts +123 -0
package/src/services/notifications/index.ts +413 -0
package/src/services/postgres.ts +51 -0
package/src/services/providers/index.ts +27 -0
package/src/services/providers/local/auth.ts +13 -0
package/src/services/providers/local/index.ts +4 -0
package/src/services/providers/local/users.ts +255 -0
package/src/services/session/index.ts +137 -0
package/src/services/settings/api.ts +61 -0
package/src/services/settings/app.ts +101 -0
package/src/services/settings/crypto.ts +69 -0
package/src/services/settings/defaults.ts +824 -0
package/src/services/settings/index.ts +203 -0
package/src/services/settings/namespace.ts +9 -0
package/src/services/settings/snapshot.ts +49 -0
package/src/services/settings/store.ts +179 -0
package/src/services/settings/templates.ts +10 -0
package/src/services/weather/forecast.ts +287 -0
package/src/services/weather/geo.ts +110 -0
package/src/services/weather/index.ts +99 -0
package/src/services/weather/location.ts +24 -0
package/src/services/weather/locations.ts +125 -0
package/src/services/weather/migrate.ts +22 -0
package/src/services/weather/types.ts +61 -0
package/src/services/weather/ui.ts +50 -0
package/src/shared/account-display.ts +17 -0
package/src/shared/account-session.ts +15 -0
package/src/shared/icons.ts +109 -0
package/src/shared/index.ts +10 -0
package/src/shared/markdown/client.ts +130 -0
package/src/shared/markdown/extensions/code.ts +58 -0
package/src/shared/markdown/extensions/images.ts +43 -0
package/src/shared/markdown/extensions/info-blocks.ts +93 -0
package/src/shared/markdown/extensions/katex.ts +120 -0
package/src/shared/markdown/extensions/links.ts +34 -0
package/src/shared/markdown/extensions/tables.ts +88 -0
package/src/shared/markdown/extensions/task-list.ts +53 -0
package/src/shared/markdown/index.ts +97 -0
package/src/shared/markdown/shared.ts +36 -0
package/src/ssr/AdminLayout.tsx +42 -0
package/src/ssr/AdminSidebar.tsx +95 -0
package/src/ssr/Footer.island.tsx +62 -0
package/src/ssr/GlobalSearchDialog.tsx +389 -0
package/src/ssr/GlobalSearchHelpDialog.tsx +106 -0
package/src/ssr/GlobalSearchTrigger.island.tsx +42 -0
package/src/ssr/HotkeysHelpRail.island.tsx +99 -0
package/src/ssr/Layout.tsx +326 -0
package/src/ssr/MoreAppsDropdown.island.tsx +61 -0
package/src/ssr/NavMenu.island.tsx +108 -0
package/src/ssr/ThemeToggleRail.island.tsx +27 -0
package/src/ssr/index.ts +5 -0
package/src/ssr/islands/SearchBar.island.tsx +77 -0
package/src/ssr/islands/index.ts +1 -0
package/src/ssr/runtime.ts +22 -0
package/src/styles/base-popover.css +28 -0
package/src/styles/effects.css +65 -0
package/src/styles/global.css +133 -0
package/src/styles/input.css +54 -0
package/src/styles/tokens.css +35 -0
package/src/styles/utilities-buttons.css +125 -0
package/src/styles/utilities-feedback.css +65 -0
package/src/styles/utilities-layout.css +122 -0
package/src/styles/utilities-navigation.css +196 -0
package/src/types/ambient.d.ts +8 -0
package/src/ui/admin-settings.tsx +148 -0
package/src/ui/dialog-core.ts +146 -0
package/src/ui/filter/FilterChip.tsx +196 -0
package/src/ui/filter/index.ts +2 -0
package/src/ui/index.ts +19 -0
package/src/ui/input/Checkbox.tsx +55 -0
package/src/ui/input/ColorInput.tsx +122 -0
package/src/ui/input/DateTimeInput.tsx +86 -0
package/src/ui/input/ImageInput.tsx +170 -0
package/src/ui/input/NumberInput.tsx +113 -0
package/src/ui/input/PinInput.tsx +169 -0
package/src/ui/input/SegmentedControl.tsx +99 -0
package/src/ui/input/Select.tsx +288 -0
package/src/ui/input/SelectChip.tsx +61 -0
package/src/ui/input/Slider.tsx +118 -0
package/src/ui/input/Switch.tsx +62 -0
package/src/ui/input/TagsInput.tsx +115 -0
package/src/ui/input/TextInput.tsx +160 -0
package/src/ui/input/index.ts +13 -0
package/src/ui/input/types.ts +42 -0
package/src/ui/input/util.tsx +105 -0
package/src/ui/ipa/Avatar.tsx +28 -0
package/src/ui/ipa/GroupView.tsx +36 -0
package/src/ui/ipa/LoginBtn.tsx +16 -0
package/src/ui/ipa/UserView.tsx +58 -0
package/src/ui/ipa/index.ts +4 -0
package/src/ui/misc/ContextMenu.tsx +211 -0
package/src/ui/misc/CopyButton.tsx +28 -0
package/src/ui/misc/Dropdown.tsx +194 -0
package/src/ui/misc/EntitySearch.tsx +213 -0
package/src/ui/misc/Lightbox.tsx +194 -0
package/src/ui/misc/LinkCard.tsx +34 -0
package/src/ui/misc/LogEntriesTable.tsx +61 -0
package/src/ui/misc/MarkdownView.tsx +65 -0
package/src/ui/misc/Pagination.tsx +51 -0
package/src/ui/misc/PermissionEditor.tsx +379 -0
package/src/ui/misc/ProgressBar.tsx +47 -0
package/src/ui/misc/RemoveBtn.tsx +27 -0
package/src/ui/misc/StatCell.tsx +90 -0
package/src/ui/misc/index.ts +18 -0
package/src/ui/navigation.ts +32 -0
package/src/ui/prompts.tsx +854 -0
package/src/ui/sidebar.tsx +468 -0
package/src/ui/widgets/Widget.tsx +62 -0
package/src/ui/widgets/WidgetCard.tsx +19 -0
package/src/ui/widgets/WidgetHero.tsx +39 -0
package/src/ui/widgets/WidgetList.tsx +84 -0
package/src/ui/widgets/WidgetPills.tsx +68 -0
package/src/ui/widgets/WidgetStat.tsx +67 -0
package/src/ui/widgets/WidgetStatus.tsx +62 -0
package/src/ui/widgets/index.ts +9 -0

package/src/config/env.ts ADDED Viewed

@@ -0,0 +1,23 @@
+/**
+ * Environment variable parsing.
+ * All env vars are parsed and validated here, then exported as typed `env` object.
+ */
+const str = (key: string, fallback: string = ""): string => process.env[key] ?? fallback;
+const int = (key: string, fallback: number): number => {
+  const value = process.env[key];
+  const parsed = parseInt(value ?? "", 10);
+  return isNaN(parsed) ? fallback : parsed;
+};
+export const env = {
+  // Application (infrastructure — not changeable at runtime)
+  APP_SECRET: str("APP_SECRET"),
+  PORT: int("PORT", 3000),
+  IS_DEVELOPMENT: process.env.NODE_ENV === "development",
+  // Admin login (local emergency access — token-based, no IPA required)
+  ADMIN_LOGIN_TOKEN: str("ADMIN_LOGIN_TOKEN"),
+} as const;

package/src/config/index.ts ADDED Viewed

@@ -0,0 +1,6 @@
+/**
+ * Main config export.
+ * Re-exports env vars. SSR config is per-app via defineApp().
+ */
+export { env } from "./env";

package/src/config/ssr.ts ADDED Viewed

@@ -0,0 +1,58 @@
+/**
+ * SSR configuration and helpers.
+ */
+import { createConfig } from "@valentinkolb/ssr";
+import { createSSRHandler } from "@valentinkolb/ssr/hono";
+import { env } from "./env";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Cache-busting version stamp — changes on every server start / rebuild. */
+const v = Date.now();
+type PageOptions = {
+  title?: string;
+  description?: string;
+  theme?: "light" | "dark";
+};
+export const { config, plugin, html } = createConfig<PageOptions>({
+  dev: env.IS_DEVELOPMENT,
+  verbose: true,
+  // Scan all workspace packages so app islands are bundled too (not only core islands).
+  rootDir: resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", ".."),
+  template: ({ body, scripts, title, description, theme }) => {
+    // If theme is explicitly set, don't let the script override it
+    const themeFixed = theme !== undefined;
+    return `<!DOCTYPE html>
+<html lang="de" class="${theme ?? "light"}"${themeFixed ? " data-theme-fixed" : ""}>
+  <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="view-transition" content="same-origin">
+    <title>${title ?? "StuVe"}</title>
+    <meta name="description" content="${description ?? "Cloud workspace"}">
+    <meta name="theme-color" content="#09090b">
+    <meta name="mobile-web-app-capable" content="yes">
+    <link rel="icon" href="/branding/favicon">
+    <link rel="stylesheet" href="/public/build.css?v=${v}">
+    <link rel="stylesheet" href="/public/katex.css?v=${v}">
+    <script>
+      (function() {
+        var el = document.documentElement;
+        if (!el.hasAttribute('data-theme-fixed')) {
+          var theme = document.cookie.match(/theme=([^;]+)/)?.[1] || 'light';
+          el.classList.add(theme);
+        }
+      })();
+    </script>
+  </head>
+  <body>
+    ${body}
+  </body>
+  ${scripts}
+</html>`;
+  },
+});
+export const ssr = createSSRHandler(html);

package/src/contracts/app.ts ADDED Viewed

@@ -0,0 +1,140 @@
+import type { Role, User } from "./shared";
+/**
+ * One link entry contributed by an app to the global legal/info footer
+ * (login page, app footer, rail dropdown). Aggregated across all running
+ * apps via `listLegalLinks()`.
+ */
+export type LegalLink = {
+  label: string;
+  href: string;
+  icon?: string;
+};
+export type AppMeta = {
+  id: string;
+  name: string;
+  icon: string;
+  description: string;
+  adminHref?: string;
+  /**
+   * Top-level URL prefixes the gateway routes to this app. The gateway
+   * is dumb — it just builds a prefix-trie from these strings.
+   */
+  routes: readonly string[];
+  nav?: {
+    href: string;
+    match?: string;
+    section: "primary" | "more" | "hidden";
+    requiresAuth?: boolean;
+    requiresRoles?: Role[];
+  };
+  /**
+   * Legal/info pages this app owns. Aggregated app-wide and rendered in
+   * login footer, app Footer, and the rail "more" dropdown. Each app
+   * contributes its own (e.g. settings → terms/privacy/imprint, faq → FAQ).
+   */
+  legalLinks?: LegalLink[];
+  /**
+   * Dashboard widget endpoints this app exposes. Each entry references an
+   * HTTP endpoint that returns a `WidgetResponse` (see `contracts/widgets.ts`).
+   * The dashboard app fetches these with the user's session forwarded; the
+   * endpoint is responsible for permission / role gating and returns 204 to
+   * silently skip rendering for the current user.
+   */
+  widgets?: WidgetEndpoint[];
+};
+export type WidgetEndpoint = {
+  /** Unique-within-the-app id, e.g. "open-requests". */
+  id: string;
+  /** Absolute path on the app's HTTP service, e.g. "/api/accounts/widget/open-requests". */
+  path: string;
+};
+export type RuntimeAppMeta = AppMeta & {
+  searchTags?: string[];
+  searchHelp?: string;
+  searchTagHelp?: AppSearchTagHelpEntry[];
+};
+export type CloudLogger = {
+  debug: (message: string, metadata?: Record<string, unknown>) => void;
+  info: (message: string, metadata?: Record<string, unknown>) => void;
+  warn: (message: string, metadata?: Record<string, unknown>) => void;
+  error: (message: string, metadata?: Record<string, unknown>) => void;
+};
+export type CloudRuntime = {
+  apps: readonly RuntimeAppMeta[];
+};
+export type CloudContext = {
+  logger: (source: string) => CloudLogger;
+  settings: {
+    get: <T = unknown>(key: string) => Promise<T>;
+    set: (key: string, value: unknown) => Promise<void>;
+  };
+  runtime: CloudRuntime;
+};
+export type CloudLifecycleContext = CloudContext;
+export type AppLifecycle = {
+  setup?: (ctx: CloudContext) => Promise<void>;
+  start?: (ctx: CloudContext) => Promise<void>;
+  stop?: (ctx: CloudContext) => Promise<void>;
+};
+export type SearchPriority = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+export type AppSearchContext = {
+  get: <K extends "user" | "sessionToken">(key: K) => K extends "user" ? User : string;
+};
+export type AppSearchInput = {
+  query: string;
+  tags: string[];
+  limit: number;
+  ctx: AppSearchContext;
+};
+export type AppSearchMetadataEntry = {
+  label: string;
+  value: string;
+};
+export type AppSearchTagHelpEntry = {
+  tag: string;
+  help: string;
+};
+export type AppSearchResult = {
+  id: string;
+  title: string;
+  href: string;
+  preview?: string;
+  icon?: string;
+  priority?: SearchPriority;
+  metadata?: AppSearchMetadataEntry[];
+  previewUrl?: string;
+};
+export type AppCapabilities = {
+  search?: {
+    tags?: readonly string[];
+    help?: string;
+    tagHelp?: readonly AppSearchTagHelpEntry[];
+    run: (input: AppSearchInput) => Promise<AppSearchResult[]>;
+  };
+};
+/**
+ * Removes query parameters from a navigation href so path matching stays stable.
+ */
+export const stripQuery = (href: string): string => href.split("?")[0] ?? href;
+/**
+ * Resolves the active-path matcher for a nav entry.
+ */
+export const resolveNavMatch = (meta: AppMeta): string | undefined => meta.nav?.match ?? (meta.nav ? stripQuery(meta.nav.href) : undefined);

package/src/contracts/index.ts ADDED Viewed

@@ -0,0 +1,5 @@
+export * from "./app";
+export * from "./shared";
+export * from "./registry";
+export * from "./profile";
+export * from "./widgets";

package/src/contracts/profile.ts ADDED Viewed

@@ -0,0 +1,67 @@
+import { z } from "zod";
+/**
+ * Schemas for account profile / password / request inputs. Live in core
+ * contracts so both the core `/api/me` router and the accounts admin app can
+ * consume the same shapes without cross-app imports.
+ */
+const SSH_PUBLIC_KEY_PATTERN = /^(ssh-(rsa|ed25519|dss)|ecdsa-sha2-nistp(256|384|521))\s+[A-Za-z0-9+/=]+(?:\s+.+)?$/;
+/**
+ * IPA-only self-service fields. Exposed so an admin schema can compose the
+ * same inner shape without extending the refined self-service schema.
+ */
+export const IpaProfileFieldsSchema = z.object({
+  phone: z.string().optional(),
+  address: z
+    .object({
+      street: z.string().optional(),
+      postalCode: z.string().optional(),
+      city: z.string().optional(),
+      state: z.string().optional(),
+    })
+    .optional(),
+  sshPublicKeys: z.array(z.string().regex(SSH_PUBLIC_KEY_PATTERN, "Invalid SSH public key format")).optional(),
+});
+export const UpdateProfileSchema = z
+  .object({
+    givenname: z.string().min(1).optional(),
+    sn: z.string().min(1).optional(),
+    displayName: z.string().min(1).optional(),
+    ipa: IpaProfileFieldsSchema.optional(),
+  })
+  .refine(
+    (data) => data.givenname !== undefined || data.sn !== undefined || data.displayName !== undefined || data.ipa !== undefined,
+    { message: "At least one profile field must be provided" },
+  );
+export const ChangePasswordSchema = z
+  .object({
+    currentPassword: z.string().min(1),
+    newPassword: z.string().min(8),
+    confirmPassword: z.string().min(1),
+  })
+  .refine((data) => data.newPassword === data.confirmPassword, {
+    message: "Passwords do not match",
+    path: ["confirmPassword"],
+  });
+export const ChangeExpiredPasswordSchema = z
+  .object({
+    username: z.string().min(1),
+    currentPassword: z.string().min(1),
+    newPassword: z.string().min(8),
+    confirmPassword: z.string().min(1),
+  })
+  .refine((data) => data.newPassword === data.confirmPassword, {
+    message: "Passwords do not match",
+    path: ["confirmPassword"],
+  });
+export const CreateAccountRequestSchema = z.object({
+  phone: z.string().optional().describe("Optional phone number for the request"),
+  comment: z.string().optional().describe("Why do you need a FreeIPA account?"),
+  acceptedAgb: z.literal(true).describe("Must accept terms of service"),
+});

package/src/contracts/registry.ts ADDED Viewed

@@ -0,0 +1,50 @@
+/**
+ * App-registry entry type. Populated internally by `defineApp()` + the
+ * heartbeat runtime; never parsed from external input — plain TS types are
+ * enough for type safety (no runtime validation needed).
+ */
+export type AppRegistryNav = {
+  href: string;
+  match?: string;
+  section: "primary" | "more" | "hidden";
+  requiresAuth?: boolean;
+  requiresRoles?: string[];
+  adminHref?: string;
+};
+export type AppRegistrySearch = {
+  tags: string[];
+  help: string;
+  tagHelp: Array<{ tag: string; help: string }>;
+  endpoint: string;
+};
+export type AppRegistryLegalLink = {
+  label: string;
+  href: string;
+  icon?: string;
+};
+export type AppRegistryWidget = {
+  id: string;
+  /** Absolute path on the app's HTTP service, e.g. "/api/quotes/widget/random". */
+  path: string;
+};
+export type AppRegistryEntry = {
+  id: string;
+  name: string;
+  icon: string;
+  description: string;
+  baseUrl: string;
+  /**
+   * Top-level URL prefixes the gateway routes to this app. The gateway
+   * builds a prefix-trie from these strings, no derivation or heuristics.
+   */
+  routes: readonly string[];
+  nav?: AppRegistryNav;
+  search?: AppRegistrySearch;
+  legalLinks?: AppRegistryLegalLink[];
+  widgets?: AppRegistryWidget[];
+};

package/src/contracts/settings-types.ts ADDED Viewed

@@ -0,0 +1,84 @@
+/**
+ * Type-level scaffolding for `defineApp({ settings: { ... } })`.
+ *
+ * These types let TypeScript derive a per-app `Settings` shape from the literal
+ * settings declaration in defineApp. The derived shape is:
+ *
+ *   1. **Flat** — `{ "files.filegate_url": string, "freeipa.enable": boolean, ... }`
+ *      (used by the typed async API: `app.settings.get("files.filegate_url")`)
+ *
+ *   2. **Nested + readonly** — `{ files: { filegate_url: string }, freeipa: { enable: boolean } }`
+ *      (used by the per-request snapshot exposed via `c.get("settings")`)
+ *
+ * No runtime in this file — pure TypeScript.
+ */
+import type { SettingOption } from "../services/settings/defaults";
+// ── Setting definition shape (what users write inside defineApp.settings) ───
+type EnvResolver = () => unknown;
+type CommonDef = {
+  label?: string;
+  description?: string;
+  envBootstrap?: EnvResolver;
+  envFallback?: EnvResolver;
+};
+type StringLikeKind = "string" | "text" | "email" | "url" | "secret" | "image" | "cron" | "timezone" | "template";
+export type AppSettingDef =
+  | (CommonDef & { kind: StringLikeKind; default: string; placeholder?: string; templateVars?: readonly string[] })
+  | (CommonDef & { kind: "boolean"; default: boolean })
+  | (CommonDef & { kind: "number"; default: number; min?: number; max?: number; placeholder?: string })
+  | (CommonDef & { kind: "enum"; default: string; options: ReadonlyArray<SettingOption> })
+  | (CommonDef & { kind: "string_list"; default: readonly string[]; placeholder?: string })
+  | (CommonDef & { kind: "number_list"; default: readonly number[]; placeholder?: string });
+/** A map of setting-key → definition. The key strings are dotted paths like "files.filegate_url". */
+export type AppSettingsMap = Record<string, AppSettingDef>;
+// ── Type-level transforms ───────────────────────────────────────────────────
+/** Map a setting `kind` literal to the runtime value type returned by reads. */
+export type KindToType<K extends string> =
+  K extends "boolean" ? boolean :
+  K extends "number" ? number :
+  K extends "string_list" ? string[] :
+  K extends "number_list" ? number[] :
+  string;
+/**
+ * Derive a flat `{ key: value }` map from a SettingsMap.
+ *
+ * Example:
+ *   SettingsFlat<{ "app.name": { kind: "string"; default: "" } }>
+ *   = { readonly "app.name": string }
+ */
+export type SettingsFlat<S extends Record<string, { kind: string }>> = {
+  readonly [K in keyof S]: KindToType<S[K]["kind"]>;
+};
+/**
+ * Recursively un-flatten dotted-key maps into nested objects.
+ *
+ * Example:
+ *   Unflatten<{ "files.filegate_url": string; "files.base_homes": string; "app.name": string }>
+ *   = { readonly files: { readonly filegate_url: string; readonly base_homes: string }, readonly app: { readonly name: string } }
+ */
+export type Unflatten<T extends Record<string, unknown>> = {
+  readonly [K in Extract<keyof T, string> as K extends `${infer Head}.${string}` ? Head : K]:
+    K extends `${infer Head}.${string}`
+      ? Unflatten<{ [P in Extract<keyof T, `${Head}.${string}`> as P extends `${Head}.${infer R}` ? R : never]: T[P] }>
+      : T[K];
+};
+/**
+ * Final per-app Settings shape: nested, readonly, derived from the App type.
+ *
+ * Used by `AppContext<App>` to type `c.get("settings")` correctly per-app.
+ */
+export type AppSettings<App> =
+  App extends { readonly _settings: infer S extends Record<string, { kind: string }> }
+    ? Unflatten<SettingsFlat<S>>
+    : never;

package/src/contracts/shared.ts ADDED Viewed

@@ -0,0 +1,258 @@
+import { z } from "zod";
+export const RoleSchema = z.enum([
+  "admin",
+  "ipa",
+  "guest",
+  "group-manager",
+  "local",
+  "user",
+  "ipa/user",
+  "ipa/guest",
+  "local/user",
+  "local/guest",
+]);
+export type Role = z.infer<typeof RoleSchema>;
+export const UserProviderSchema = z.enum(["ipa", "local"]);
+export type UserProvider = z.infer<typeof UserProviderSchema>;
+export const UserProfileSchema = z.enum(["user", "guest"]);
+export type UserProfile = z.infer<typeof UserProfileSchema>;
+export const SpecialRoleSchema = z.enum(["*", "authenticated", "anonymous"]);
+export type SpecialRole = z.infer<typeof SpecialRoleSchema>;
+export type RoleOrSpecial = Role | SpecialRole;
+export const hasRole = (user: { roles: Role[] }, ...roles: Role[]): boolean => roles.some((role) => user.roles.includes(role));
+export const BaseUserSchema = z.object({
+  id: z.string(),
+  uid: z.string(),
+  roles: z.array(RoleSchema),
+  provider: UserProviderSchema,
+  profile: UserProfileSchema,
+  givenname: z.string(),
+  sn: z.string(),
+  displayName: z.string(),
+  mail: z.string().nullable(),
+});
+export type BaseUser = z.infer<typeof BaseUserSchema>;
+export const IpaUserDataSchema = z.object({
+  uidNumber: z.number().nullable(),
+  phone: z.string().nullable(),
+  employeeType: z.string().nullable(),
+  mobile: z.string().nullable(),
+  address: z.object({
+    street: z.string().nullable(),
+    postalCode: z.string().nullable(),
+    city: z.string().nullable(),
+    state: z.string().nullable(),
+  }),
+  passwordExpires: z.string().nullable(),
+  lastLoginIpa: z.string().nullable(),
+  syncedAt: z.string().nullable(),
+  sshPublicKeys: z.array(z.string()),
+  sshFingerprints: z.array(z.string()),
+});
+export type IpaUserData = z.infer<typeof IpaUserDataSchema>;
+const RichUserFields = {
+  accountExpires: z.string().nullable(),
+  lastLoginLocal: z.string().nullable(),
+  memberofGroup: z.array(z.string()),
+  memberofGroupIds: z.array(z.uuid()),
+  manages: z.array(z.string()),
+  managesGroupIds: z.array(z.uuid()),
+} satisfies z.ZodRawShape;
+export const IpaUserSchema = BaseUserSchema.extend({
+  provider: z.literal("ipa"),
+  ipa: IpaUserDataSchema,
+  ...RichUserFields,
+});
+export type IpaUser = z.infer<typeof IpaUserSchema>;
+export const LocalUserSchema = BaseUserSchema.extend({
+  provider: z.literal("local"),
+  ipa: z.null(),
+  ...RichUserFields,
+});
+export type LocalUser = z.infer<typeof LocalUserSchema>;
+export const UserSchema = z.discriminatedUnion("provider", [IpaUserSchema, LocalUserSchema]);
+export type User = z.infer<typeof UserSchema>;
+export const BaseGroupSchema = z.object({
+  id: z.uuid(),
+  provider: UserProviderSchema,
+  name: z.string(),
+  description: z.string().nullable(),
+  gidnumber: z.number().nullable(),
+});
+export type BaseGroup = z.infer<typeof BaseGroupSchema>;
+export const EntityKindSchema = z.enum(["user", "group"]);
+export type EntityKind = z.infer<typeof EntityKindSchema>;
+export const EntityRelationSchema = z.object({
+  direct: z.boolean().optional(),
+});
+export type EntityRelation = z.infer<typeof EntityRelationSchema>;
+export const EntityListItemSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("user"),
+    user: BaseUserSchema,
+    relation: EntityRelationSchema.optional(),
+  }),
+  z.object({
+    kind: z.literal("group"),
+    group: BaseGroupSchema,
+    relation: EntityRelationSchema.optional(),
+  }),
+]);
+export type EntityListItem = z.infer<typeof EntityListItemSchema>;
+export const GroupMemberSchema = z.object({
+  type: z.enum(["user", "group"]),
+  id: z.string(),
+  displayName: z.string().nullable(),
+});
+export type GroupMember = z.infer<typeof GroupMemberSchema>;
+export const SearchQuerySchema = z.object({
+  search: z.string().optional(),
+});
+export const PaginationQuerySchema = z.object({
+  page: z.coerce.number().int().positive().optional().default(1),
+  per_page: z.coerce.number().int().min(1).max(100).optional().default(20),
+});
+export type PaginationQuery = z.infer<typeof PaginationQuerySchema>;
+export const PaginationResponseSchema = z.object({
+  page: z.number(),
+  per_page: z.number(),
+  total: z.number(),
+  total_pages: z.number(),
+  has_next: z.boolean(),
+});
+export type PaginationResponse = z.infer<typeof PaginationResponseSchema>;
+export type PaginationParams = {
+  page: number;
+  perPage: number;
+  offset: number;
+};
+export const parsePagination = (query: { page?: number; per_page?: number }): PaginationParams => {
+  const page = query.page ?? 1;
+  const perPage = query.per_page ?? 20;
+  const offset = (page - 1) * perPage;
+  return { page, perPage, offset };
+};
+export const createPagination = (params: PaginationParams, total: number): PaginationResponse => {
+  const totalPages = Math.ceil(total / params.perPage);
+  return {
+    page: params.page,
+    per_page: params.perPage,
+    total,
+    total_pages: totalPages,
+    has_next: params.page < totalPages,
+  };
+};
+export const ErrorResponseSchema = z.object({
+  message: z.string(),
+  code: z.string().optional(),
+});
+export type ErrorResponse = z.infer<typeof ErrorResponseSchema>;
+export const MessageResponseSchema = z.object({
+  message: z.string(),
+});
+export type MessageResponse = z.infer<typeof MessageResponseSchema>;
+export type MutationResult<T = void> = { ok: true; data: T } | { ok: false; error: string; status: 400 | 401 | 403 | 404 | 409 | 500 };
+export const PermissionLevelSchema = z.enum(["none", "read", "write", "admin"]);
+export type PermissionLevel = z.infer<typeof PermissionLevelSchema>;
+export const PrincipalSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("user"), userId: z.uuid() }),
+  z.object({ type: z.literal("group"), groupId: z.uuid() }),
+  z.object({ type: z.literal("authenticated") }),
+  z.object({ type: z.literal("public") }),
+]);
+export type Principal = z.infer<typeof PrincipalSchema>;
+export const AccessEntrySchema = z.object({
+  id: z.uuid(),
+  principal: PrincipalSchema,
+  permission: PermissionLevelSchema,
+  createdAt: z.string(),
+  displayName: z.string().optional(),
+});
+export type AccessEntry = z.infer<typeof AccessEntrySchema>;
+export const NotebookPresenceParticipantSchema = z.object({
+  userId: z.uuid(),
+  displayName: z.string(),
+  color: z.string(),
+  peerCount: z.number().int().positive(),
+  joinedAt: z.string(),
+});
+export type NotebookPresenceParticipant = z.infer<typeof NotebookPresenceParticipantSchema>;
+export const GrantAccessSchema = z.object({
+  principal: PrincipalSchema,
+  permission: PermissionLevelSchema,
+});
+export type GrantAccess = z.infer<typeof GrantAccessSchema>;
+export const UpdateAccessSchema = z.object({
+  permission: PermissionLevelSchema,
+});
+export type UpdateAccess = z.infer<typeof UpdateAccessSchema>;
+// ── Settings (browser-safe types) ────────────────────────────────────
+export type SettingKind =
+  | "string"
+  | "text"
+  | "email"
+  | "url"
+  | "secret"
+  | "image"
+  | "boolean"
+  | "number"
+  | "enum"
+  | "string_list"
+  | "number_list"
+  | "cron"
+  | "timezone"
+  | "template";
+export type SettingOption = {
+  value: string;
+  label: string;
+};
+export type SettingEntry = {
+  key: string;
+  label: string;
+  kind: SettingKind;
+  description: string;
+  placeholder?: string;
+  group: string;
+  value: unknown;
+  default: unknown;
+  isCustom: boolean;
+  templateVars?: string[];
+  options?: SettingOption[];
+  min?: number;
+  max?: number;
+};