@k2b/cloud 0.6.0-rc.0

package/src/cli/output.ts

@@ -0,0 +1,58 @@
+/**
+ * Output helpers for app CLI commands.
+ *
+ * Every command has to honour `ctx.options.output`, and hand-writing that
+ * branch is where it goes wrong: several apps checked only for "json" and then
+ * printed a text table under `--jsonl`, which silently breaks the machine
+ * -readable contract agents rely on.
+ *
+ * Both helpers emit the *full* value in structured modes, not the table
+ * projection — a table drops fields on purpose, a JSON consumer wants them.
+ */
+
+import type { CloudCliContext, CloudCliTableColumn } from "./index";
+
+/**
+ * Render a list: full payload as JSON, one object per line as JSONL, or a
+ * table in text mode.
+ *
+ * `value` is what structured consumers get. `rows`/`columns` are the text
+ * projection, and may be a narrower shape than `value`.
+ */
+export const printRows = <TRow extends Record<string, unknown>>(
+  ctx: CloudCliContext,
+  value: unknown,
+  rows: TRow[],
+  columns: CloudCliTableColumn<TRow>[],
+): void => {
+  if (ctx.options.output === "json") {
+    ctx.json(value);
+    return;
+  }
+  if (ctx.options.output === "jsonl") {
+    for (const item of Array.isArray(value) ? value : [value]) ctx.jsonLine(item);
+    return;
+  }
+  ctx.table(rows, columns);
+};
+
+/**
+ * Handle the structured modes for a single value and report whether anything
+ * was printed. Use it to guard bespoke text rendering:
+ *
+ * ```ts
+ * if (printStructured(ctx, mailbox)) return;
+ * ctx.print(`${mailbox.name} — ${mailbox.address}`);
+ * ```
+ */
+export const printStructured = (ctx: CloudCliContext, value: unknown): boolean => {
+  if (ctx.options.output === "json") {
+    ctx.json(value);
+    return true;
+  }
+  if (ctx.options.output === "jsonl") {
+    ctx.jsonLine(value);
+    return true;
+  }
+  return false;
+};

package/src/clients/core.ts

@@ -0,0 +1,20 @@
+/**
+ * Typed client for the core platform API.
+ *
+ * Apps that need to call core endpoints (`/api/auth/*`, `/api/me/*`,
+ * `/api/admin/lifecycle/*`, `/api/accounts/entities`) import this client
+ * instead of constructing their own — the type stays in lockstep with the
+ * actual route definitions in `@k2b/cloud/api`.
+ */
+
+import type { CoreApiType } from "../api";
+import { api } from "../server/api-client";
+
+export const coreClient = api.create<CoreApiType>({ baseUrl: "/api" });
+
+/**
+ * Alias for islands that already use the conventional name `apiClient`.
+ * Both names refer to the same client; use whichever fits the call site.
+ */
+export const apiClient = coreClient;
+export type { CoreApiType };

package/src/config/env.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 optional = (key: string): string | undefined => process.env[key]?.trim() || undefined;
+
+const int = (key: string, fallback: number): number => {
+  const value = process.env[key];
+  const parsed = parseInt(value ?? "", 10);
+  return isNaN(parsed) ? fallback : parsed;
+};
+
+const bool = (key: string, fallback: boolean): boolean => {
+  const value = process.env[key]?.trim().toLowerCase();
+  if (!value) return fallback;
+  return value === "true" || value === "1";
+};
+
+const list = (key: string): string[] =>
+  (process.env[key] ?? "")
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+
+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"),
+
+  // NATS / @k2b/sync (Postgres and Redis are read by Bun from DATABASE_URL / REDIS_URL)
+  /** Bootstrap servers, comma-separated `nats://host:port` URLs. Required by `connectNats()`. */
+  NATS_SERVERS: list("NATS_SERVERS"),
+  /** Sync namespace shared by every app of one Cloud installation (e.g. `dev`, `prod`). Required. */
+  SYNC_NAMESPACE: str("SYNC_NAMESPACE"),
+  /** Path to a mounted NATS `.creds` file (JWT + NKey). Unset = server-side no-auth. */
+  NATS_CREDS_FILE: optional("NATS_CREDS_FILE"),
+  /** Path to a mounted CA certificate; enables TLS with that CA. Unset = plain TCP. */
+  NATS_TLS_CA_FILE: optional("NATS_TLS_CA_FILE"),
+  /**
+   * Default true: only dial the servers listed in NATS_SERVERS. Clustered
+   * nodes gossip their peers' advertised addresses, which are Docker-internal
+   * hostnames (`ipa_nats_2`) that host-side clients (tests, `dev:cld` tooling)
+   * cannot resolve. Set to `false` when clients can reach every advertised
+   * address and should learn new nodes at runtime.
+   */
+  NATS_IGNORE_CLUSTER_UPDATES: bool("NATS_IGNORE_CLUSTER_UPDATES", true),
+} as const;

package/src/config/index.ts

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

package/src/contracts/account-categories.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+
+/** Presentation categories are derived, never stored on an account. */
+export type AccountCategory = "guest" | "login" | "freeipa";
+const categoryPolicy = z.object({ enabled: z.boolean(), visible: z.boolean() }).strict();
+export const AccountCategoryPolicySchema = z
+  .object({
+    guest: categoryPolicy,
+    login: categoryPolicy
+      .extend({
+        label: z
+          .string()
+          .trim()
+          .transform((label) => label || "Login"),
+      })
+      .strict(),
+    freeipa: categoryPolicy,
+  })
+  .strict();
+export type AccountCategoryPolicy = z.infer<typeof AccountCategoryPolicySchema>;
+
+export const DEFAULT_ACCOUNT_CATEGORY_POLICY: AccountCategoryPolicy = {
+  guest: { enabled: true, visible: true },
+  login: { enabled: true, visible: true, label: "Login" },
+  freeipa: { enabled: true, visible: true },
+};
+
+export const accountCategory = (user: { provider: "local" | "ipa"; profile: "guest" | "user" }): AccountCategory =>
+  user.provider === "ipa" ? "freeipa" : user.profile === "guest" ? "guest" : "login";
+
+export const accountCategoryLabel = (user: { provider: "local" | "ipa"; profile: "guest" | "user" }, loginLabel = "Login"): string => {
+  const category = accountCategory(user);
+  return category === "freeipa" ? "FreeIPA" : category === "guest" ? "Guest" : loginLabel.trim() || "Login";
+};
+
+export const visibleAccountCategories = (policy: AccountCategoryPolicy, freeIpaEnabled: boolean): AccountCategory[] =>
+  (["guest", "login", "freeipa"] as const).filter(
+    (category) => policy[category].enabled && policy[category].visible && (category !== "freeipa" || freeIpaEnabled),
+  );
+
+/** Explicit links can open hidden, allowed categories; cookies cannot. Legacy
+ * email links remain unbound to Guest so existing full-account links work. */
+export const resolveAccountCategoryLogin = (input: {
+  policy: AccountCategoryPolicy;
+  freeIpaEnabled: boolean;
+  method?: string;
+  remembered?: string | null;
+  hasToken?: boolean;
+  hideGuest?: boolean;
+}): { visible: AccountCategory[]; active: AccountCategory | "email" | null } => {
+  const visible = visibleAccountCategories(input.policy, input.freeIpaEnabled).filter(
+    (category) => !input.hideGuest || category === "freeipa",
+  );
+  if (input.hasToken) return { visible, active: "email" };
+  if (input.method === "email") return { visible, active: input.policy.guest.enabled || input.policy.login.enabled ? "email" : null };
+  const method = input.method === "ipa" ? "freeipa" : input.method;
+  if (method === "guest" || method === "login" || method === "freeipa") {
+    return { visible, active: input.policy[method].enabled && (method !== "freeipa" || input.freeIpaEnabled) ? method : null };
+  }
+  const remembered = input.remembered === "ipa" ? "freeipa" : input.remembered;
+  return { visible, active: visible.find((category) => category === remembered) ?? visible[0] ?? null };
+};

package/src/contracts/announcements.ts

@@ -0,0 +1,121 @@
+import { z } from "zod";
+
+export const ANNOUNCEMENTS_COOKIE = "cloud_announcements";
+export const ANNOUNCEMENTS_COOKIE_MAX_AGE_SECONDS = 60 * 60 * 24 * 365;
+export const MAX_DISMISSED_BANNER_VERSIONS = 50;
+
+export const AnnouncementKindSchema = z.enum(["announcement", "banner"]);
+export type AnnouncementKind = z.infer<typeof AnnouncementKindSchema>;
+
+export const AnnouncementToneSchema = z.enum(["info", "success", "warning", "danger"]);
+export type AnnouncementTone = z.infer<typeof AnnouncementToneSchema>;
+
+export const AnnouncementCookieStateSchema = z.object({
+  seenAnnouncementVersion: z.number().int().nonnegative().default(0),
+  dismissedBannerVersions: z.array(z.number().int().positive()).default([]),
+});
+export type AnnouncementCookieState = z.infer<typeof AnnouncementCookieStateSchema>;
+
+export const DEFAULT_ANNOUNCEMENT_COOKIE_STATE: AnnouncementCookieState = {
+  seenAnnouncementVersion: 0,
+  dismissedBannerVersions: [],
+};
+
+export const AnnouncementEntrySchema = z.object({
+  id: z.uuid(),
+  version: z.number().int().positive(),
+  kind: AnnouncementKindSchema,
+  title: z.string(),
+  body: z.string(),
+  tone: AnnouncementToneSchema,
+  publishedAt: z.string().datetime(),
+  expiresAt: z.string().datetime().nullable(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+  createdBy: z.uuid().nullable(),
+  updatedBy: z.uuid().nullable(),
+});
+export type AnnouncementEntry = z.infer<typeof AnnouncementEntrySchema>;
+
+export const AnnouncementDisplayEntrySchema = AnnouncementEntrySchema.omit({ body: true }).extend({
+  bodyHtml: z.string(),
+});
+export type AnnouncementDisplayEntry = z.infer<typeof AnnouncementDisplayEntrySchema>;
+
+const DatetimeInputSchema = z.string().datetime();
+const NullableDatetimeInputSchema = z.string().datetime().nullable();
+
+export const CreateAnnouncementSchema = z.object({
+  kind: AnnouncementKindSchema,
+  title: z.string().trim().min(1).max(180),
+  body: z.string().trim().min(1).max(20_000),
+  tone: AnnouncementToneSchema.default("info"),
+  publishedAt: DatetimeInputSchema.optional(),
+  expiresAt: NullableDatetimeInputSchema.optional(),
+});
+export type CreateAnnouncement = z.infer<typeof CreateAnnouncementSchema>;
+
+export const UpdateAnnouncementSchema = z
+  .object({
+    kind: AnnouncementKindSchema.optional(),
+    title: z.string().trim().min(1).max(180).optional(),
+    body: z.string().trim().min(1).max(20_000).optional(),
+    tone: AnnouncementToneSchema.optional(),
+    publishedAt: DatetimeInputSchema.optional(),
+    expiresAt: NullableDatetimeInputSchema.optional(),
+  })
+  .refine((value) => Object.keys(value).length > 0, "Provide at least one field to update.");
+export type UpdateAnnouncement = z.infer<typeof UpdateAnnouncementSchema>;
+
+export const AnnouncementListResponseSchema = z.object({
+  items: z.array(AnnouncementEntrySchema),
+});
+export type AnnouncementListResponse = z.infer<typeof AnnouncementListResponseSchema>;
+
+export const ActiveAnnouncementsResponseSchema = z.object({
+  banners: z.array(AnnouncementDisplayEntrySchema),
+  announcements: z.array(AnnouncementDisplayEntrySchema),
+  latestAnnouncementVersion: z.number().int().nonnegative(),
+});
+export type ActiveAnnouncementsResponse = z.infer<typeof ActiveAnnouncementsResponseSchema>;
+
+const normalizeCookieState = (value: unknown): AnnouncementCookieState => {
+  const parsed = AnnouncementCookieStateSchema.safeParse(value);
+  if (!parsed.success) return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
+  const dismissed = [...new Set(parsed.data.dismissedBannerVersions)]
+    .filter((version) => Number.isInteger(version) && version > 0)
+    .sort((a, b) => b - a)
+    .slice(0, MAX_DISMISSED_BANNER_VERSIONS);
+
+  return {
+    seenAnnouncementVersion: Math.max(0, parsed.data.seenAnnouncementVersion),
+    dismissedBannerVersions: dismissed,
+  };
+};
+
+export const parseAnnouncementCookieValue = (value: string | null | undefined): AnnouncementCookieState => {
+  if (!value) return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
+  try {
+    return normalizeCookieState(JSON.parse(decodeURIComponent(value)));
+  } catch {
+    return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
+  }
+};
+
+export const parseAnnouncementCookieHeader = (cookieHeader: string | null | undefined): AnnouncementCookieState => {
+  if (!cookieHeader) return DEFAULT_ANNOUNCEMENT_COOKIE_STATE;
+  const match = cookieHeader.match(new RegExp(`(?:^|;\\s*)${ANNOUNCEMENTS_COOKIE}=([^;]+)`));
+  return parseAnnouncementCookieValue(match?.[1]);
+};
+
+export const serializeAnnouncementCookieState = (state: AnnouncementCookieState): string =>
+  encodeURIComponent(JSON.stringify(normalizeCookieState(state)));
+
+export const mergeAnnouncementCookieState = (
+  current: AnnouncementCookieState,
+  patch: Partial<AnnouncementCookieState>,
+): AnnouncementCookieState =>
+  normalizeCookieState({
+    seenAnnouncementVersion: Math.max(current.seenAnnouncementVersion, patch.seenAnnouncementVersion ?? 0),
+    dismissedBannerVersions: [...current.dismissedBannerVersions, ...(patch.dismissedBannerVersions ?? [])],
+  });

package/src/contracts/app-approval.ts

@@ -0,0 +1,197 @@
+import { z } from "zod";
+
+/** Version 1 has a single algorithm and fixed signing encodings. No negotiation. */
+export const APP_APPROVAL_PROTOCOL = "cloud-app-approval-v1";
+export const APP_APPROVAL_PATH = "/api/auth/app-approval/v1";
+export const APP_APPROVAL_LIMITS = {
+  bodyBytes: 8192,
+  pairingSeconds: 300,
+  loginSeconds: 300,
+  proofSeconds: 60,
+  recentSessionSeconds: 600,
+  devicesPerAccount: 20,
+  pendingPerAccount: 5,
+  pageSize: 20,
+  pollSeconds: 5,
+} as const;
+
+const Id = z.string().uuid();
+const Secret = z.string().regex(/^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/);
+const Signature = z.string().regex(/^[A-Za-z0-9_-]{85}[AQgw]$/);
+export const AppDevicePublicKeySchema = z
+  .object({
+    kty: z.literal("EC"),
+    crv: z.literal("P-256"),
+    x: Secret,
+    y: Secret,
+  })
+  .strict();
+export type AppDevicePublicKey = z.infer<typeof AppDevicePublicKeySchema>;
+export const AppPairingStartSchema = z.object({ userId: Id.optional() }).strict();
+export const AppPairingClaimSchema = z
+  .object({
+    pairingId: Id,
+    secret: Secret,
+    publicKey: AppDevicePublicKeySchema,
+    name: z.string().trim().min(1).max(80),
+    signature: Signature,
+  })
+  .strict();
+export const AppPairingReferenceSchema = z.object({ pairingId: Id, secret: Secret, publicKey: AppDevicePublicKeySchema }).strict();
+export const AppPairingConfirmSchema = z.object({ pairingId: Id, comparison: z.string().regex(/^\d{6}$/) }).strict();
+export const AppLoginStartSchema = z
+  .object({
+    identifier: z.string().trim().min(1).max(254),
+    category: z.enum(["guest", "login", "freeipa"]),
+  })
+  .strict();
+export const AppLoginReferenceSchema = z.object({ requestId: Id, browserSecret: Secret }).strict();
+export const AppDeviceMutationSchema = z.discriminatedUnion("operation", [
+  z.object({ operation: z.literal("rename"), deviceId: Id, name: z.string().trim().min(1).max(80) }).strict(),
+  z.object({ operation: z.literal("revoke"), deviceId: Id }).strict(),
+]);
+export const AppDeviceCommandSchema = z.discriminatedUnion("operation", [
+  z.object({ operation: z.literal("pending") }).strict(),
+  z.object({ operation: z.literal("revoke") }).strict(),
+  z
+    .object({
+      operation: z.literal("decide"),
+      requestId: Id,
+      challenge: Secret,
+      comparison: z.string().regex(/^\d{6}$/),
+      decision: z.enum(["approve", "deny"]),
+    })
+    .strict(),
+]);
+export const AppDeviceProofSchema = z
+  .object({
+    issuer: z.string().url(),
+    deviceId: Id,
+    jti: Id,
+    issuedAt: z.number().int().nonnegative(),
+    expiresAt: z.number().int().positive(),
+    command: AppDeviceCommandSchema,
+  })
+  .strict();
+export const AppDeviceRequestSchema = z.object({ proof: AppDeviceProofSchema, signature: Signature }).strict();
+export type AppDeviceProof = z.infer<typeof AppDeviceProofSchema>;
+export type AppDeviceRequest = z.infer<typeof AppDeviceRequestSchema>;
+
+/** UTF-8 of this exact JSON array; signatures use WebCrypto ECDSA P-256/SHA-256,
+ * 64-byte IEEE-P1363 r||s, encoded as unpadded base64url. */
+export const appDeviceProofMessage = (proof: AppDeviceProof): string => {
+  const c = proof.command;
+  return JSON.stringify([
+    APP_APPROVAL_PROTOCOL,
+    "device",
+    proof.issuer,
+    proof.deviceId,
+    proof.jti,
+    proof.issuedAt,
+    proof.expiresAt,
+    c.operation,
+    ...(c.operation === "decide" ? [c.requestId, c.challenge, c.comparison, c.decision] : []),
+  ]);
+};
+export const appPairingProofMessage = (issuer: string, claim: Omit<z.infer<typeof AppPairingClaimSchema>, "signature">): string =>
+  JSON.stringify([
+    APP_APPROVAL_PROTOCOL,
+    "pair",
+    issuer,
+    claim.pairingId,
+    claim.secret,
+    claim.publicKey.kty,
+    claim.publicKey.crv,
+    claim.publicKey.x,
+    claim.publicKey.y,
+    claim.name,
+  ]);
+
+const DateTime = z.string().datetime();
+const Comparison = z.string().regex(/^\d{6}$/);
+export const AppDeviceViewSchema = z
+  .object({
+    id: Id,
+    name: z.string(),
+    createdAt: DateTime,
+    lastUsedAt: DateTime.nullable(),
+    revokedAt: DateTime.nullable(),
+    assisted: z.boolean(),
+  })
+  .strict();
+export const AppPendingLoginSchema = z
+  .object({ requestId: Id, challenge: Secret, comparison: Comparison, createdAt: DateTime, expiresAt: DateTime })
+  .strict();
+export const AppPairingPayloadSchema = z
+  .object({ protocol: z.literal(APP_APPROVAL_PROTOCOL), issuer: z.string().url(), pairingId: Id, secret: Secret, expiresAt: DateTime })
+  .strict();
+export type AppPairingPayload = z.infer<typeof AppPairingPayloadSchema>;
+
+const pairingOrigin = (value: string): string => {
+  const url = new URL(value);
+  const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (
+    (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) ||
+    url.username ||
+    url.password ||
+    url.pathname !== "/" ||
+    url.search ||
+    url.hash
+  )
+    throw new Error("Invalid pairing origin");
+  return url.origin;
+};
+
+/** The same fragment-only link is used for QR, copy/paste and same-device opening. */
+export const appPairingLink = (authenticatorOrigin: string, payload: AppPairingPayload): string => {
+  const parsed = AppPairingPayloadSchema.parse(payload);
+  if (pairingOrigin(parsed.issuer) !== parsed.issuer) throw new Error("Invalid pairing issuer");
+  const link = `${pairingOrigin(authenticatorOrigin)}/#pairing=${encodeURIComponent(JSON.stringify(parsed))}`;
+  if (link.length > APP_APPROVAL_LIMITS.bodyBytes) throw new Error("Pairing link too long");
+  return link;
+};
+
+/** Parses untrusted pasted/scanned text without fetching or trusting the issuer.
+ * The caller must obtain consent, validate discovery and clear the fragment. */
+export const parseAppPairingLink = (input: string, authenticatorOrigin: string): AppPairingPayload => {
+  if (input.length > APP_APPROVAL_LIMITS.bodyBytes) throw new Error("Pairing link too long");
+  const url = new URL(input.trim());
+  if (
+    url.origin !== pairingOrigin(authenticatorOrigin) ||
+    url.username ||
+    url.password ||
+    url.pathname !== "/" ||
+    url.search ||
+    !url.hash.startsWith("#pairing=")
+  )
+    throw new Error("Invalid pairing link");
+  const payload = AppPairingPayloadSchema.parse(JSON.parse(decodeURIComponent(url.hash.slice("#pairing=".length))));
+  if (pairingOrigin(payload.issuer) !== payload.issuer) throw new Error("Invalid pairing issuer");
+  return payload;
+};
+export const AppPairingClaimResultSchema = z.object({ deviceId: Id, comparison: Comparison, expiresAt: DateTime }).strict();
+export const AppPairingResultSchema = z
+  .object({ state: z.enum(["pending", "claimed", "confirmed", "cancelled"]), deviceId: Id.nullable(), comparison: Comparison.nullable() })
+  .strict();
+/** Initiating Cloud session only; never returned to an unpaired device. */
+export const AppPairingInspectionSchema = AppPairingResultSchema.extend({ name: z.string().nullable(), userId: Id });
+export const AppDeviceResponseSchema = z.union([
+  z
+    .object({
+      requests: z.array(AppPendingLoginSchema).max(APP_APPROVAL_LIMITS.pendingPerAccount),
+      pollAfterSeconds: z.number().positive(),
+    })
+    .strict(),
+  z.object({ state: z.enum(["approved", "denied", "revoked"]) }).strict(),
+]);
+export const AppLoginStartResultSchema = z
+  .object({ requestId: Id, browserSecret: Secret, comparison: Comparison, expiresAt: DateTime, pollAfterSeconds: z.number().positive() })
+  .strict();
+export const AppLoginStatusSchema = z
+  .object({ state: z.enum(["pending", "approved", "denied", "consumed", "expired"]), pollAfterSeconds: z.number().positive() })
+  .strict();
+export const AppDevicesPageSchema = z
+  .object({ items: z.array(AppDeviceViewSchema).max(APP_APPROVAL_LIMITS.pageSize), nextCursor: Id.nullable() })
+  .strict();
+export type AppDeviceView = z.infer<typeof AppDeviceViewSchema>;
+export type AppPendingLogin = z.infer<typeof AppPendingLoginSchema>;

package/src/contracts/app.ts

@@ -0,0 +1,162 @@
+import type { Sync } from "@k2b/sync";
+import type { HelpManifest } from "../shared/help";
+import type { Role } from "./shared";
+import type { DashboardWidgetPresentation } from "./widgets";
+
+/**
+ * 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 AppAppearanceColor = `#${string}`;
+
+export type AppAppearance = {
+  accent: AppAppearanceColor;
+  background?: {
+    from: AppAppearanceColor;
+    via?: AppAppearanceColor;
+    to?: AppAppearanceColor;
+    angle?: number;
+    /** Edge color intensity from 0 to 100. Defaults to 20. */
+    strength?: number;
+  };
+};
+
+export type AppAdminNavigationLink = {
+  label: string;
+  href: string;
+  icon: string;
+};
+
+export type AppAdminNavigationGroup = {
+  /** Stable key used only to localize this presentation group. */
+  id?: string;
+  label: string;
+  links: AppAdminNavigationLink[];
+};
+
+export type AppPresentationTranslation = {
+  name?: string;
+  description?: string;
+  /** Group labels keyed by `adminNav[].id`. */
+  adminGroups?: Readonly<Record<string, string>>;
+  /** Link labels keyed by their stable same-origin href. */
+  adminLinks?: Readonly<Record<string, string>>;
+  /** Legal-link labels keyed by their stable same-origin href. */
+  legalLinks?: Readonly<Record<string, string>>;
+};
+
+export type AppPresentationCatalog = {
+  /** Locale of the complete `name`, `description`, `adminNav`, and `legalLinks` declaration. */
+  baseLocale: string;
+  /** Partial presentation overlays with exact -> ancestor -> base fallback. */
+  translations: Readonly<Record<string, AppPresentationTranslation>>;
+};
+
+export type AppMeta = {
+  id: string;
+  name: string;
+  icon: string;
+  description: string;
+  presentation?: AppPresentationCatalog;
+  appearance?: AppAppearance;
+  adminHref?: string;
+  /** Optional multi-link admin navigation owned by this app. */
+  adminNav?: AppAdminNavigationGroup[];
+  /**
+   * 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`).
+   * Core resolves the initiating user before dispatching these; the endpoint
+   * is responsible for permission / role gating and returns 204 to silently
+   * skip rendering for the current user.
+   */
+  widgets?: WidgetEndpoint[];
+  /** Setting keys declared by this app. Used by admin tooling to protect active app-owned settings. */
+  settingKeys?: readonly string[];
+  /** Gateway-relative URL where this app's OpenAPI JSON is served, or undefined. */
+  openapi?: string;
+};
+
+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;
+  /** Optional initial layout recommendation. Explicit user choices win. */
+  presentation?: DashboardWidgetPresentation;
+};
+
+export type RuntimeAppMeta = AppMeta & {
+  help?: HelpManifest;
+  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;
+};
+
+/** Lifecycle hooks additionally receive the ready process-wide @k2b/sync instance. */
+export type CloudLifecycleContext = CloudContext & { sync: Sync };
+
+export type AppLifecycle = {
+  setup?: (ctx: CloudLifecycleContext) => Promise<void>;
+  start?: (ctx: CloudLifecycleContext) => Promise<void>;
+  stop?: (ctx: CloudLifecycleContext) => Promise<void>;
+};
+
+export type AppSearchTagHelpEntry = {
+  tag: string;
+  help: string;
+};
+
+/**
+ * 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);