@k2b/cloud 0.6.0-rc.0

package/src/contracts/notification-types.ts

@@ -0,0 +1,235 @@
+import type { output, ZodType } from "zod";
+import { canonicalLocale, localeFallbackChain } from "../shared/locale";
+
+export type NotificationRecipientKind = "user" | "email";
+
+/** Deployment channel packages extend this registry through module augmentation. */
+export interface NotificationChannelRegistry {
+  email: true;
+  browser: true;
+}
+
+export type NotificationChannelId = Extract<keyof NotificationChannelRegistry, string>;
+
+const NOTIFICATION_TARGET_ORIGIN = "https://cloud.invalid";
+
+export const isSafeNotificationTargetHref = (value: string): value is `/${string}` => {
+  if (!value.startsWith("/") || value.startsWith("//") || /[\\\u0000-\u001f\u007f]/.test(value)) return false;
+  try {
+    const target = new URL(value, NOTIFICATION_TARGET_ORIGIN);
+    return target.origin === NOTIFICATION_TARGET_ORIGIN && `${target.pathname}${target.search}${target.hash}` === value;
+  } catch {
+    return false;
+  }
+};
+
+export const validateNotificationTargetHref = (value: string): `/${string}` => {
+  if (!isSafeNotificationTargetHref(value)) throw new Error("Notification targetHref must be a canonical same-origin absolute path");
+  return value;
+};
+
+export type NotificationPresentation = {
+  title: string;
+  body?: string;
+  /** Same-origin absolute path. Validated again before persistence and navigation. */
+  targetHref?: `/${string}`;
+};
+
+export type EmailNotificationPresentation = {
+  subject: string;
+  content?: string;
+  rawHtml?: string;
+};
+
+export type NotificationRenderContext = {
+  /** Canonical locale selected by the sender for this rendered notification. */
+  locale: string;
+};
+
+export type NotificationDeliveryPolicy = {
+  recommended?: readonly NotificationChannelId[];
+  required?: readonly NotificationChannelId[];
+};
+
+export type NotificationDefinitionPresentationTranslation = {
+  label?: string;
+  description?: string;
+};
+
+export type NotificationDefinitionPresentationCatalog = {
+  /** Locale of the complete `label` and `description` declaration. */
+  baseLocale: string;
+  /** Partial presentation overlays with exact -> ancestor -> base fallback. */
+  translations: Readonly<Record<string, NotificationDefinitionPresentationTranslation>>;
+};
+
+export type NotificationDefinitionInput<R extends NotificationRecipientKind, S extends ZodType> = {
+  recipient: R;
+  label: string;
+  description: string;
+  presentation?: NotificationDefinitionPresentationCatalog;
+  data: S;
+  delivery?: NotificationDeliveryPolicy;
+  render: (data: output<S>, context: NotificationRenderContext) => NotificationPresentation | Promise<NotificationPresentation>;
+  email?: (data: output<S>, context: NotificationRenderContext) => EmailNotificationPresentation | Promise<EmailNotificationPresentation>;
+};
+
+const notificationDefinitionMarker = Symbol("cloud.notification-definition");
+
+export type NotificationDefinition<R extends NotificationRecipientKind = NotificationRecipientKind, S extends ZodType = ZodType> = Readonly<
+  NotificationDefinitionInput<R, S> & {
+    readonly [notificationDefinitionMarker]: true;
+  }
+>;
+
+type AnyNotificationDefinition = Readonly<{
+  recipient: NotificationRecipientKind;
+  label: string;
+  description: string;
+  presentation?: NotificationDefinitionPresentationCatalog;
+  data: ZodType;
+  delivery?: NotificationDeliveryPolicy;
+  render: (...args: never[]) => NotificationPresentation | Promise<NotificationPresentation>;
+  email?: (...args: never[]) => EmailNotificationPresentation | Promise<EmailNotificationPresentation>;
+  readonly [notificationDefinitionMarker]: true;
+}>;
+
+export type NotificationDefinitionMap = Record<string, AnyNotificationDefinition>;
+
+export type BoundNotificationDefinition<
+  AppId extends string = string,
+  Key extends string = string,
+  R extends NotificationRecipientKind = NotificationRecipientKind,
+  S extends ZodType = ZodType,
+> = NotificationDefinition<R, S> & {
+  readonly appId: AppId;
+  readonly key: Key;
+  readonly id: `${AppId}.${Key}`;
+};
+
+export type AnyBoundNotificationDefinition = AnyNotificationDefinition & {
+  readonly appId: string;
+  readonly key: string;
+  readonly id: `${string}.${string}`;
+};
+
+export type BoundNotificationMap<AppId extends string, N extends NotificationDefinitionMap> = {
+  readonly [K in keyof N]: N[K] extends NotificationDefinition<infer R, infer S>
+    ? BoundNotificationDefinition<AppId, Extract<K, string>, R, S>
+    : never;
+};
+
+export type NotificationRecipient<R extends NotificationRecipientKind> = R extends "user" ? { userId: string } : { email: string };
+
+export type NotificationSendInput<D extends AnyBoundNotificationDefinition> =
+  D extends BoundNotificationDefinition<string, string, infer R, infer S>
+    ? {
+        recipient: NotificationRecipient<R>;
+        data: output<S>;
+        idempotencyKey: string;
+        sentBy?: string;
+        /** Locale for final human-facing notification and email content. */
+        locale?: string;
+      }
+    : never;
+
+const hasDuplicates = (values: readonly string[]): boolean => new Set(values).size !== values.length;
+
+const requiredPresentationText = (value: string, field: string): string => {
+  const normalized = value.trim();
+  if (!normalized) throw new Error(`Notification presentation ${field} is required`);
+  return normalized;
+};
+
+const compileDefinitionPresentation = (
+  catalog: NotificationDefinitionPresentationCatalog | undefined,
+): NotificationDefinitionPresentationCatalog | undefined => {
+  if (!catalog) return undefined;
+  const baseLocale = canonicalLocale(catalog.baseLocale);
+  if (!baseLocale) throw new Error("Notification presentation baseLocale must be a valid BCP 47 locale");
+
+  const translations: Record<string, NotificationDefinitionPresentationTranslation> = {};
+  for (const [locale, translation] of Object.entries(catalog.translations)) {
+    const canonical = canonicalLocale(locale);
+    if (!canonical) throw new Error(`Notification presentation locale ${JSON.stringify(locale)} is not a valid BCP 47 locale`);
+    if (canonical === baseLocale) throw new Error(`Notification presentation translations must not repeat base locale ${baseLocale}`);
+    if (translations[canonical]) throw new Error(`Notification presentation locale ${canonical} is duplicated after canonicalization`);
+    translations[canonical] = Object.freeze({
+      ...(translation.label !== undefined ? { label: requiredPresentationText(translation.label, `${canonical}.label`) } : {}),
+      ...(translation.description !== undefined
+        ? { description: requiredPresentationText(translation.description, `${canonical}.description`) }
+        : {}),
+    });
+  }
+  return Object.freeze({ baseLocale, translations: Object.freeze(translations) });
+};
+
+export const resolveNotificationDefinitionPresentation = (
+  definition: {
+    label: string;
+    description: string;
+    presentation?: NotificationDefinitionPresentationCatalog | null;
+  },
+  requestedLocale?: string | null,
+): { label: string; description: string } => {
+  const catalog = definition.presentation;
+  if (!catalog || !requestedLocale) return { label: definition.label, description: definition.description };
+  const translations = new Map(Object.entries(catalog.translations));
+  return localeFallbackChain(requestedLocale, catalog.baseLocale)
+    .filter((locale) => locale !== catalog.baseLocale)
+    .reverse()
+    .reduce((resolved, locale) => ({ ...resolved, ...translations.get(locale) }), {
+      label: definition.label,
+      description: definition.description,
+    });
+};
+
+export const notification = <const R extends NotificationRecipientKind, const S extends ZodType>(
+  input: NotificationDefinitionInput<R, S>,
+): NotificationDefinition<R, S> => {
+  const label = input.label.trim();
+  const description = input.description.trim();
+  if (!label) throw new Error("Notification label is required");
+  if (!description) throw new Error(`Notification "${label}" description is required`);
+
+  const recommended = [...(input.delivery?.recommended ?? [])];
+  const required = [...(input.delivery?.required ?? [])];
+  if (hasDuplicates(recommended) || hasDuplicates(required)) {
+    throw new Error(`Notification "${label}" contains duplicate delivery channels`);
+  }
+  const overlappingChannel = recommended.find((channel) => required.includes(channel));
+  if (overlappingChannel) {
+    throw new Error(`Notification "${label}" cannot recommend and require the "${overlappingChannel}" channel`);
+  }
+  if (input.recipient === "email" && !required.includes("email")) {
+    throw new Error(`Email-recipient notification "${label}" must require the email channel`);
+  }
+  const presentation = compileDefinitionPresentation(input.presentation);
+
+  const definition: NotificationDefinition<R, S> = {
+    ...input,
+    label,
+    description,
+    ...(presentation ? { presentation } : {}),
+    delivery: Object.freeze({ recommended: Object.freeze(recommended), required: Object.freeze(required) }),
+    [notificationDefinitionMarker]: true,
+  };
+  return Object.freeze(definition);
+};
+
+export const bindNotificationDefinitions = <const AppId extends string, const N extends NotificationDefinitionMap>(
+  appId: AppId,
+  definitions?: N,
+): BoundNotificationMap<AppId, N> => {
+  const result: Record<string, AnyBoundNotificationDefinition> = {};
+  for (const [key, definition] of Object.entries(definitions ?? {})) {
+    if (!/^[a-z][a-zA-Z0-9]*$/.test(key)) {
+      throw new Error(`Notification key "${key}" must be lower camelCase`);
+    }
+    result[key] = Object.freeze({ ...definition, appId, key, id: `${appId}.${key}` });
+  }
+
+  // Object iteration erases each heterogeneous definition's schema. The map
+  // is rebuilt one-to-one without changing values, so callers safely retain N.
+  return result as BoundNotificationMap<AppId, N>;
+};

package/src/contracts/posix.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+
+// Match the platform's INTEGER storage. Zero is never allocated to a Cloud account.
+export const PosixNumberSchema = z.number().int().min(1).max(2_147_483_647);
+export const PosixPathSchema = z
+  .string()
+  .min(2)
+  .max(4095)
+  .refine(
+    (value) =>
+      value.startsWith("/") &&
+      !/[\s:\x00-\x1f\x7f]/.test(value) &&
+      !value
+        .slice(1)
+        .split("/")
+        .some((part) => part === "." || part === ".." || part === ""),
+    "Use an absolute path without whitespace, colons or relative segments",
+  );
+
+export const PosixIdentitySchema = z.object({
+  userId: z.uuid(),
+  managedBy: z.enum(["local", "ipa"]),
+  uidNumber: PosixNumberSchema.nullable(),
+  primaryGidNumber: PosixNumberSchema.nullable(),
+  homeDirectory: z.string().nullable(),
+  loginShell: z.string().nullable(),
+});
+export type PosixIdentity = z.infer<typeof PosixIdentitySchema>;
+
+export const LinuxIdentityConfigurationSchema = z
+  .object({
+    enabled: z.boolean(),
+    rangeStart: z.number().int().min(0).max(2_147_483_647),
+    rangeEnd: z.number().int().min(0).max(2_147_483_647),
+    homeTemplate: z.string().min(1).max(4095),
+    loginShell: PosixPathSchema,
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    if (value.enabled && (value.rangeStart < 1000 || value.rangeEnd < value.rangeStart)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["rangeStart"],
+        message: "Choose a reserved range above system accounts (at least 1000), with end >= start",
+      });
+    }
+    if (
+      !value.homeTemplate.includes("{username}") ||
+      !PosixPathSchema.safeParse(value.homeTemplate.replaceAll("{username}", "user")).success ||
+      /[{}]/.test(value.homeTemplate.replaceAll("{username}", "user"))
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["homeTemplate"],
+        message: "Use an absolute home path containing {username}; no other placeholders are supported",
+      });
+    }
+  });
+export type LinuxIdentityConfiguration = z.infer<typeof LinuxIdentityConfigurationSchema>;
+export const DEFAULT_LINUX_IDENTITY_CONFIGURATION: LinuxIdentityConfiguration = {
+  enabled: false,
+  rangeStart: 0,
+  rangeEnd: 0,
+  homeTemplate: "/home/{username}",
+  loginShell: "/bin/bash",
+};
+
+export const PosixOverridesSchema = z.object({ homeDirectory: PosixPathSchema, loginShell: PosixPathSchema }).strict();
+export const isPosixName = (value: string): boolean => /^[a-z_][a-z0-9_-]{0,31}$/.test(value);

package/src/contracts/profile.ts

@@ -0,0 +1,85 @@
+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 MAX_AVATAR_DATA_URL_LENGTH = 65_536;
+export const MAX_AVATAR_BYTES = 48 * 1024;
+
+export const AvatarDataUrlSchema = z
+  .string()
+  .max(MAX_AVATAR_DATA_URL_LENGTH)
+  .regex(/^data:image\/(?:png|jpeg|webp);base64,[A-Za-z0-9+/]+={0,2}$/, "Avatar must be a PNG, JPEG, or WebP data URL");
+
+export const UpdateAvatarSchema = z.object({
+  dataUrl: AvatarDataUrlSchema,
+});
+export type UpdateAvatar = z.infer<typeof UpdateAvatarSchema>;
+
+export const UpdateAvatarResponseSchema = z.object({
+  message: z.string(),
+  avatarHash: z.string(),
+});
+export type UpdateAvatarResponse = z.infer<typeof UpdateAvatarResponseSchema>;
+
+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/rail-preferences.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+
+/** Rail settings travel with each SSR page: budget the complete snapshot at 16 KiB. */
+export const RAIL_PREFERENCES_MAX_BYTES = 16 * 1024;
+const id = z.string().trim().min(1).max(120);
+
+export const isRailShortcutHref = (value: string): boolean => {
+  if (/[\u0000-\u0020\u007f\\]/.test(value)) return false;
+  if (value.startsWith("/") && !value.startsWith("//")) return true;
+  try {
+    const url = new URL(value);
+    return (url.protocol === "https:" || url.protocol === "http:") && !url.username && !url.password;
+  } catch {
+    return false;
+  }
+};
+
+export const RailShortcutSchema = z.discriminatedUnion("kind", [
+  z.object({ id, kind: z.literal("app"), appId: id }).strict(),
+  z
+    .object({
+      id,
+      kind: z.literal("link"),
+      title: z.string().trim().min(1).max(80),
+      href: z.string().trim().min(1).max(2000).refine(isRailShortcutHref, "Use an absolute path or an HTTP(S) URL"),
+      icon: z
+        .string()
+        .regex(/^ti ti-[a-z0-9-]+$/)
+        .max(120),
+    })
+    .strict(),
+]);
+export type RailShortcut = z.infer<typeof RailShortcutSchema>;
+
+export const RailPreferencesSchema = z
+  .object({
+    revision: z.number().int().nonnegative().max(2_147_483_647),
+    visibility: z.record(id, z.boolean()),
+    shortcuts: z.array(RailShortcutSchema),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    if (new TextEncoder().encode(JSON.stringify({ ...value, revision: 2_147_483_647 })).byteLength > RAIL_PREFERENCES_MAX_BYTES) {
+      ctx.addIssue({ code: "custom", message: "App bar settings exceed the 16 KiB page budget" });
+    }
+    if (new Set(value.shortcuts.map((entry) => entry.id)).size !== value.shortcuts.length) {
+      ctx.addIssue({ code: "custom", message: "Shortcut IDs must be unique" });
+    }
+    const apps = value.shortcuts.flatMap((entry) => (entry.kind === "app" ? [entry.appId] : []));
+    if (new Set(apps).size !== apps.length) ctx.addIssue({ code: "custom", message: "An app can only be pinned once" });
+  });
+export type RailPreferences = z.infer<typeof RailPreferencesSchema>;
+export const defaultRailPreferences = (): RailPreferences => ({ revision: 0, visibility: {}, shortcuts: [] });

package/src/contracts/registry.ts

@@ -0,0 +1,110 @@
+import type { HelpManifest } from "../shared/help";
+import type { AppAdminNavigationGroup, AppAppearance, AppAppearanceColor, AppPresentationCatalog } from "./app";
+import type { CapabilityManifest, CapabilityPresentationCatalog } from "./capabilities";
+import type { Role } from "./shared";
+import type { DashboardWidgetPresentation } from "./widgets";
+
+/**
+ * App-registry entry type. Populated internally by `defineApp()` + the
+ * heartbeat runtime. Values are validated when read because Redis may still
+ * contain records written by older or interrupted runtimes.
+ */
+
+export type AppRegistryNav = {
+  href: string;
+  match?: string;
+  section: "primary" | "more" | "hidden";
+  requiresAuth?: boolean;
+  requiresRoles?: Role[];
+  adminHref?: string;
+};
+
+export type AppRegistryCapabilitySummary = {
+  protocolVersion: number;
+  manifestHash: string;
+};
+
+/** Validated Capability manifest joined to its matching live app lease. */
+export type CapabilityRegistryEntry = {
+  appId: string;
+  appName: string;
+  appIcon: string;
+  appAccent?: AppAppearanceColor;
+  appDescription: string;
+  endpoint: string;
+  manifest: CapabilityManifest;
+  presentation?: CapabilityPresentationCatalog;
+};
+
+export type AppRegistryHelpSummary = HelpManifest;
+
+export type HelpRegistryDocument = {
+  id: string;
+  title: string;
+  icon?: string;
+  description?: string;
+  order: number;
+  markdown: string;
+  /** Precomputed by the app. Older registry entries may omit it during rolling upgrades. */
+  searchText?: string;
+};
+
+/** Full Markdown lives separately so normal app discovery stays small. */
+export type HelpRegistryEntry = {
+  appId: string;
+  appName: string;
+  appIcon: string;
+  manifestHash: string;
+  /** Base language that owns the complete logical article set. Absent on legacy registrations. */
+  baseLocale?: string;
+  /** Partial localized article variants stored in the same bounded logical registration. */
+  documentsByLocale?: Readonly<Record<string, readonly HelpRegistryDocument[]>>;
+  documents: readonly HelpRegistryDocument[];
+};
+
+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;
+  presentation?: DashboardWidgetPresentation;
+};
+
+export type AppRuntimeMetadata = {
+  release: string;
+  syncVersion: string;
+};
+
+export type AppRegistryEntry = {
+  id: string;
+  name: string;
+  icon: string;
+  description: string;
+  presentation?: AppPresentationCatalog;
+  appearance?: AppAppearance;
+  baseUrl: string;
+  /** Build metadata reported by the running app. Missing on older app releases. */
+  runtime?: AppRuntimeMetadata;
+  /** Process start time (epoch ms) reported by the running app; the registry cannot know it. */
+  startedAt?: number;
+  /**
+   * 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;
+  adminNav?: AppAdminNavigationGroup[];
+  capabilities?: AppRegistryCapabilitySummary;
+  help?: AppRegistryHelpSummary;
+  legalLinks?: AppRegistryLegalLink[];
+  widgets?: AppRegistryWidget[];
+  /** Setting keys declared by this app. Used by admin tooling to avoid treating live app-owned settings as legacy. */
+  settingKeys?: readonly string[];
+  /** Gateway-relative URL where this app serves its OpenAPI JSON spec. */
+  openapi?: string;
+};

package/src/contracts/resource-clipboard.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { type CloudResourceRef, CloudResourceRefSchema } from "./capabilities";
+
+export const CLOUD_RESOURCE_CLIPBOARD_MIME_TYPE = "application/vnd.k2b.cloud-resource-ref+json";
+export const CLOUD_RESOURCE_CLIPBOARD_WEB_FORMAT = `web ${CLOUD_RESOURCE_CLIPBOARD_MIME_TYPE}`;
+export const CLOUD_RESOURCE_CLIPBOARD_MAX_BYTES = 4_096;
+
+export const CloudResourceClipboardPayloadSchema = z
+  .object({
+    version: z.literal(1),
+    cloudUrl: z
+      .string()
+      .url()
+      .refine((value) => new URL(value).origin === value, "Expected the canonical Cloud origin"),
+    ref: CloudResourceRefSchema,
+  })
+  .strict();
+
+export type CloudResourceClipboardPayload = z.infer<typeof CloudResourceClipboardPayloadSchema>;
+
+export const serializeCloudResourceClipboard = (input: { cloudUrl: string; ref: CloudResourceRef }): string =>
+  JSON.stringify(CloudResourceClipboardPayloadSchema.parse({ version: 1, ...input }));
+
+export const parseCloudResourceClipboard = (value: string, cloudUrl: string): CloudResourceRef | null => {
+  if (new TextEncoder().encode(value).byteLength > CLOUD_RESOURCE_CLIPBOARD_MAX_BYTES) return null;
+
+  try {
+    const payload = CloudResourceClipboardPayloadSchema.safeParse(JSON.parse(value));
+    return payload.success && payload.data.cloudUrl === cloudUrl ? payload.data.ref : null;
+  } catch {
+    return null;
+  }
+};

package/src/contracts/settings-types.ts

@@ -0,0 +1,98 @@
+/**
+ * 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;
+
+export type AppSettingPresentationTranslation = {
+  label?: string;
+  description?: string;
+  placeholder?: string;
+  options?: Readonly<Record<string, string>>;
+};
+
+export type AppSettingPresentation = {
+  /** Partial overlays; the complete fields use the application's presentation base locale. */
+  translations: Readonly<Record<string, AppSettingPresentationTranslation>>;
+};
+
+type CommonDef = {
+  label?: string;
+  description?: string;
+  presentation?: AppSettingPresentation;
+  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;