@k2b/cloud 0.6.0-rc.0

package/src/index.ts

@@ -0,0 +1,58 @@
+export type { AppDefinition, AppOptions, StartOptions, StartResult } from "./_internal/define-app";
+export { defineApp } from "./_internal/define-app";
+export { createHeartbeat } from "./_internal/heartbeat";
+export type { ProcessSync } from "./_internal/process-sync";
+export {
+  bindProcessSync,
+  getProcessSync,
+  lazySync,
+  startProcessSync,
+  unbindProcessSync,
+} from "./_internal/process-sync";
+export { APP_READINESS_PATH } from "./_internal/readiness";
+export type { AppRegistryDetail, AppRegistryIssue, AppRegistrySnapshot, CapabilityRegistryRecord, DashboardWidget } from "./_internal/registry";
+export {
+  APP_REGISTRY_CONFIG,
+  APP_REGISTRY_PREFIX,
+  APP_REGISTRY_TTL_MS,
+  CAPABILITY_REGISTRY_CONFIG,
+  HELP_REGISTRY_CONFIG,
+  appRegistry,
+  capabilityRegistry,
+  getApp,
+  getHelp,
+  helpRegistry,
+  listApps,
+  listAppsDetailed,
+  listHelp,
+  listLegalLinks,
+  listWidgets,
+  readAppRegistrySnapshot,
+  watchAppRegistry,
+} from "./_internal/registry";
+export type { RuntimeCompatibilityIssue } from "./_internal/runtime-compatibility";
+export { assessRuntimeCompatibility } from "./_internal/runtime-compatibility";
+export { buildRuntimeFromRegistry } from "./_internal/runtime-context";
+export { defineCapabilities } from "./contracts/capabilities";
+export type {
+  AnyBoundNotificationDefinition,
+  BoundNotificationDefinition,
+  BoundNotificationMap,
+  EmailNotificationPresentation,
+  NotificationChannelId,
+  NotificationChannelRegistry,
+  NotificationDefinition,
+  NotificationDefinitionInput,
+  NotificationDefinitionMap,
+  NotificationDefinitionPresentationCatalog,
+  NotificationDefinitionPresentationTranslation,
+  NotificationDeliveryPolicy,
+  NotificationPresentation,
+  NotificationRecipient,
+  NotificationRecipientKind,
+  NotificationRenderContext,
+  NotificationSendInput,
+} from "./contracts/notification-types";
+export { notification } from "./contracts/notification-types";
+export type { HelpDefinition, HelpDefinitionDocument } from "./server/help";
+export { defineHelp } from "./server/help";

package/src/server/actor.ts

@@ -0,0 +1,41 @@
+/**
+ * Deriving the acting user from a request actor.
+ *
+ * Roles, display name and avatar are user properties, so features that need
+ * them still need a user — but it must come **from the actor**, never from a
+ * separate context variable. `c.get("user")` drops the credential context on
+ * the way, which is how a scope cap silently stops applying and how a route
+ * ends up unable to tell a session from an API key.
+ *
+ * For authorization, do not use these helpers at all: pass
+ * `c.get("accessSubject")` into the shared access helpers, which already
+ * normalises a user-delegated credential to its user.
+ */
+
+import type { Context } from "hono";
+import type { AuthContext } from "./middleware/auth";
+
+type RequestActor = AuthContext["Variables"]["actor"];
+type ActingUser = AuthContext["Variables"]["user"];
+
+/** The user behind an actor: itself for a session, the delegate for a user-bound credential, null for a resource-bound one. */
+export const userFromActor = (actor: RequestActor | undefined): ActingUser | null => {
+  if (!actor) return null;
+  return actor.kind === "user" ? actor.user : actor.delegatedUser;
+};
+
+/** Same, read off the request context. */
+export const getUserBackedActor = <T extends AuthContext>(c: Context<T>): ActingUser | null =>
+  userFromActor(c.get("actor") as RequestActor | undefined);
+
+/**
+ * The acting user, or throw.
+ *
+ * Only for routes already gated to a user-backed role — the throw is a
+ * programming-error guard, not an access check.
+ */
+export const expectUserBackedActor = <T extends AuthContext>(c: Context<T>): ActingUser => {
+  const user = getUserBackedActor(c);
+  if (!user) throw new Error("Expected user-backed actor after role middleware");
+  return user;
+};

package/src/server/api/index.ts

@@ -0,0 +1,2 @@
+export type { ApiErrorBody, ApiErrorResponse, ApiErrorStatus } from "./respond";
+export { api, respond, respondMessage } from "./respond";

package/src/server/api/respond.ts

@@ -0,0 +1,96 @@
+import { isServiceError, ok, type Result, type ServiceError } from "@k2b/stdlib";
+import type { Context, TypedResponse } from "hono";
+import type { StatusCode } from "hono/utils/http-status";
+
+type LegacyErrorStatus = ServiceError["status"] | 413 | 422 | 502 | 503 | 504;
+type LegacyErrorResult<S extends number = number> = { ok: false; error: string; status: S; code?: string };
+type LegacyResult<T = void> = { ok: true; data: T } | LegacyErrorResult;
+
+type AnyResult<T = unknown> = Result<T> | LegacyResult<T>;
+type ResultOrFn<T> = T | Promise<T> | (() => T | Promise<T>);
+type SuccessStatus = 200 | 201;
+export type ApiErrorStatus = ServiceError["status"] | LegacyErrorStatus;
+type JsonTypedResponse<T, Status extends StatusCode> = Response & TypedResponse<T, Status, "json">;
+
+export type ApiErrorBody = {
+  message: string;
+  code?: string;
+};
+export type ApiErrorResponse = JsonTypedResponse<ApiErrorBody, ApiErrorStatus>;
+
+const toErrorResponse = (result: AnyResult): [ApiErrorBody, number] => {
+  if (result.ok) {
+    throw new Error("toErrorResponse called with successful result");
+  }
+
+  // Legacy shape: { ok: false, error: string, status: number, code?: string }
+  if ("status" in result && typeof result.status === "number") {
+    return [result.code ? { message: result.error, code: result.code } : { message: result.error }, result.status];
+  }
+
+  // New shape: { ok: false, error: ServiceError }
+  if (isServiceError(result.error)) {
+    return [
+      {
+        message: result.error.message,
+        code: result.error.code,
+      },
+      result.error.status,
+    ];
+  }
+
+  // Defensive fallback
+  return [{ message: "Internal server error", code: "INTERNAL" }, 500];
+};
+
+export async function respond<E extends ServiceError>(
+  c: Context,
+  resultOrFn: ResultOrFn<Result<never, E>>,
+  successStatus?: SuccessStatus,
+): Promise<JsonTypedResponse<ApiErrorBody, E["status"]>>;
+export async function respond<T>(
+  c: Context,
+  resultOrFn: ResultOrFn<Result<T, never>>,
+  successStatus?: SuccessStatus,
+): Promise<JsonTypedResponse<T, SuccessStatus>>;
+export async function respond<T, E extends ServiceError>(
+  c: Context,
+  resultOrFn: ResultOrFn<Result<T, E>>,
+  successStatus?: SuccessStatus,
+): Promise<JsonTypedResponse<T, SuccessStatus> | JsonTypedResponse<ApiErrorBody, E["status"]>>;
+export async function respond<S extends LegacyErrorStatus>(
+  c: Context,
+  resultOrFn: ResultOrFn<LegacyErrorResult<S>>,
+  successStatus?: SuccessStatus,
+): Promise<JsonTypedResponse<ApiErrorBody, S>>;
+export async function respond<T>(
+  c: Context,
+  resultOrFn: ResultOrFn<AnyResult<T>>,
+  successStatus?: SuccessStatus,
+): Promise<JsonTypedResponse<T, SuccessStatus> | ApiErrorResponse>;
+export async function respond<T>(
+  c: Context,
+  resultOrFn: ResultOrFn<AnyResult<T>>,
+  successStatus: SuccessStatus = 200,
+): Promise<JsonTypedResponse<T, SuccessStatus> | ApiErrorResponse> {
+  const result = typeof resultOrFn === "function" ? await resultOrFn() : await resultOrFn;
+
+  if (!result.ok) {
+    const [body, status] = toErrorResponse(result);
+    return c.json(body, status as ApiErrorStatus) as ApiErrorResponse;
+  }
+
+  return c.json(result.data, successStatus as 200 | 201) as JsonTypedResponse<T, SuccessStatus>;
+}
+
+export const respondMessage = (c: Context, resultPromise: Promise<Result<void>>, message: string) =>
+  respond(c, async () => {
+    const result = await resultPromise;
+    if (!result.ok) return result;
+    return ok({ message });
+  });
+
+export const api = {
+  respond,
+  respondMessage,
+} as const;

package/src/server/api-client.ts

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

package/src/server/app-context.ts

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

package/src/server/help.ts

@@ -0,0 +1,187 @@
+import { Hono } from "hono";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+import { type HelpDocumentManifest, type HelpDocumentPayload, type HelpSearchPayload, helpLocaleChain } from "../shared/help";
+import { markdownToPlainText, renderHelpMarkdown } from "../shared/markdown";
+
+const metadataSchema = z.object({
+  id: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+  title: z.string().trim().min(1),
+  icon: z.string().trim().min(1).optional(),
+  description: z.string().trim().min(1).optional(),
+  order: z.number().int().optional(),
+});
+
+export type HelpDefinitionDocument = Omit<z.infer<typeof metadataSchema>, "order"> & {
+  order: number;
+  markdown: string;
+  html: string;
+  searchText: string;
+};
+
+export type HelpDefinition = {
+  baseLocale?: string;
+  documentsByLocale?: Readonly<Record<string, readonly HelpDefinitionDocument[]>>;
+  documents: readonly HelpDefinitionDocument[];
+  getMarkdown: (id: string, locale?: string) => string | undefined;
+};
+
+export type HelpCollection = {
+  manifest: readonly HelpDocumentManifest[];
+  router: Hono;
+  /** Raw Markdown for future agent context and non-UI consumers. */
+  getMarkdown: (id: string) => string | undefined;
+};
+
+type ParsedHelpDocument = Omit<HelpDefinitionDocument, "order"> & { order?: number };
+
+const parseSource = (source: string): ParsedHelpDocument => {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/.exec(source);
+  if (!match) throw new Error("Help documents require YAML frontmatter wrapped in --- markers");
+
+  const metadata = metadataSchema.parse(parseYaml(match[1]!));
+  const markdown = match[2]!.trim();
+  if (!markdown) throw new Error(`Help document "${metadata.id}" has no body`);
+
+  return {
+    ...metadata,
+    markdown,
+    html: renderHelpMarkdown(markdown),
+    searchText: markdownToPlainText(markdown),
+  };
+};
+
+const canonicalLocale = (value: string): string => {
+  try {
+    return Intl.getCanonicalLocales(value)[0]!;
+  } catch {
+    throw new Error(`Invalid help locale "${value}"`);
+  }
+};
+
+const parseDocuments = (
+  sources: readonly string[],
+  locale: string,
+  baseById?: ReadonlyMap<string, HelpDefinitionDocument>,
+): readonly HelpDefinitionDocument[] => {
+  const documents = sources
+    .map(parseSource)
+    .map((document): HelpDefinitionDocument => {
+      const base = baseById?.get(document.id);
+      if (!baseById) return { ...document, order: document.order ?? 100 };
+      if (!base) throw new Error(`Help locale "${locale}" contains unknown document id "${document.id}"`);
+      if ((document.icon !== undefined && document.icon !== base.icon) || (document.order !== undefined && document.order !== base.order)) {
+        throw new Error(`Help locale "${locale}" must preserve icon and order for document "${document.id}"`);
+      }
+      return { ...document, icon: base.icon, description: document.description ?? base.description, order: base.order };
+    })
+    .sort((a, b) => a.order - b.order || a.title.localeCompare(b.title))
+    .map((document) => Object.freeze(document));
+  const ids = new Set<string>();
+  for (const document of documents) {
+    if (ids.has(document.id)) throw new Error(`Duplicate help document id "${document.id}" in locale "${locale}"`);
+    ids.add(document.id);
+  }
+  return Object.freeze(documents);
+};
+
+/** Define one app-owned Help corpus without routing or authorization config. */
+export const defineHelp = (
+  options:
+    | { documents: readonly string[]; baseLocale?: never }
+    | { baseLocale: string; documents: Readonly<Record<string, readonly string[]>> },
+): HelpDefinition => {
+  const localized = (value: typeof options): value is { baseLocale: string; documents: Readonly<Record<string, readonly string[]>> } =>
+    typeof value.baseLocale === "string";
+  const baseLocale = canonicalLocale(localized(options) ? options.baseLocale : "en");
+  const rawSourceMap: Readonly<Record<string, readonly string[]>> = localized(options)
+    ? options.documents
+    : { [baseLocale]: options.documents };
+  const sourceMap: Record<string, readonly string[]> = {};
+  for (const [rawLocale, sources] of Object.entries(rawSourceMap)) {
+    const locale = canonicalLocale(rawLocale);
+    if (sourceMap[locale]) throw new Error(`Duplicate help locale "${locale}"`);
+    sourceMap[locale] = sources;
+  }
+  const documentsByLocale: Record<string, readonly HelpDefinitionDocument[]> = {};
+  const baseSources = sourceMap[baseLocale];
+  if (!baseSources) throw new Error(`Help documents require the base locale "${baseLocale}"`);
+  const documents = parseDocuments(baseSources, baseLocale);
+  documentsByLocale[baseLocale] = documents;
+  const baseById = new Map(documents.map((document) => [document.id, document]));
+  for (const [locale, sources] of Object.entries(sourceMap)) {
+    if (locale === baseLocale) continue;
+    if (documentsByLocale[locale]) throw new Error(`Duplicate help locale "${locale}"`);
+    documentsByLocale[locale] = parseDocuments(sources, locale, baseById);
+  }
+
+  return {
+    baseLocale,
+    documentsByLocale: Object.freeze(documentsByLocale),
+    documents: Object.freeze(documents),
+    getMarkdown: (id, locale = baseLocale) => {
+      for (const candidate of helpLocaleChain(canonicalLocale(locale), baseLocale)) {
+        const localized = documentsByLocale[candidate]?.find((document) => document.id === id);
+        if (localized) return localized.markdown;
+      }
+      return undefined;
+    },
+  };
+};
+
+/**
+ * Define one app-owned help corpus. The explicit source list is deliberate:
+ * IDs, ordering and ownership stay visible in code; no filesystem scanning or
+ * build-time convention is required.
+ */
+export const defineHelpCollection = (options: { basePath: string; sources: readonly string[] }): HelpCollection => {
+  const basePath = options.basePath.replace(/\/$/, "");
+  const definition = defineHelp({ documents: options.sources });
+  const documents = definition.documents;
+  const byId = new Map(documents.map((document) => [document.id, document]));
+
+  const searchUrl = `${basePath}/search`;
+  const manifest = documents.map<HelpDocumentManifest>(({ id, title, icon, description, order }) => ({
+    id,
+    title,
+    icon,
+    description,
+    order,
+    searchUrl,
+    url: `${basePath}/${encodeURIComponent(id)}`,
+  }));
+
+  const router = new Hono()
+    .get("/search", (context) => {
+      const query = context.req.query("q")?.trim().toLocaleLowerCase().slice(0, 200) ?? "";
+      const payload: HelpSearchPayload = {
+        locale: "en",
+        ids: query
+          ? documents
+              .filter((document) =>
+                [document.title, document.description, document.searchText].some((value) => value?.toLocaleLowerCase().includes(query)),
+              )
+              .map((document) => document.id)
+          : [],
+      };
+      return context.json(payload);
+    })
+    .get("/:id", (context) => {
+      const document = byId.get(context.req.param("id"));
+      if (!document) return context.json({ error: "Help document not found" }, 404);
+      const payload: HelpDocumentPayload = {
+        locale: "en",
+        id: document.id,
+        title: document.title,
+        markdown: document.markdown,
+        html: document.html,
+      };
+      return context.json(payload);
+    });
+
+  return {
+    manifest,
+    router,
+    getMarkdown: definition.getMarkdown,
+  };
+};

package/src/server/index.ts

@@ -0,0 +1,89 @@
+export { expectUserBackedActor, getUserBackedActor, userFromActor } from "./actor";
+export type { ApiErrorBody, ApiErrorResponse, ApiErrorStatus } from "./api";
+export { api, respond, respondMessage } from "./api";
+export type { CreateApiClientConfig } from "./api-client";
+export { api as apiClient } from "./api-client";
+export type { AppContext } from "./app-context";
+export { defineHelp, defineHelpCollection, type HelpCollection, type HelpDefinition, type HelpDefinitionDocument } from "./help";
+export { DEFAULT_LOCALE, getLocale, LOCALE_COOKIE, LOCALE_HEADER, locale, preferredLocale, resolveLocale } from "./locale";
+export type {
+  AuthContext,
+  InvocationProvenance,
+  RateLimitConfig,
+  RateLimitRouteOverride,
+  RequestActor,
+  RequestAuthority,
+  RequestCredentialKind,
+  ServiceAccountRequestActor,
+  UserRequestActor,
+} from "./middleware";
+export {
+  auth,
+  imageResponse,
+  jsonResponse,
+  middleware,
+  openApiMeta,
+  rateLimit,
+  rejectReservedWorkloadCredential,
+  requestLogger,
+  requiresAdmin,
+  requiresAuth,
+  requiresIpa,
+  requiresIpaUser,
+  requiresUser,
+  v,
+  validator,
+} from "./middleware";
+export { RateLimitError, type RateLimiter, type RateLimiterConfig, type RateLimitResult, ratelimit } from "./ratelimit";
+export type {
+  AccessEntry,
+  AccessPrincipalColumns,
+  AccessPrincipalTierConditions,
+  AccessSubject,
+  AccessUser,
+  AccessUserSource,
+  EffectiveGroup,
+  GeoPlace,
+  GeoService,
+  PageParams,
+  Paginated,
+  PermissionLevel,
+  Principal,
+  PrincipalType,
+  ResourceAccessAdapter,
+  Result,
+  ServiceError,
+  ServiceErrorCode,
+} from "./services";
+export {
+  buildAccessPrincipalCondition,
+  buildAccessPrincipalTierConditions,
+  createAccess,
+  deleteAccess,
+  err,
+  fail,
+  freeipa,
+  generatePassword,
+  geo,
+  geoService,
+  getAccess,
+  getEffectiveGroupIds,
+  getEffectiveGroups,
+  getEffectivePermission,
+  hasPermission,
+  images,
+  isServiceError,
+  listUsersWithAccess,
+  ok,
+  okMany,
+  PERMISSION_LEVELS,
+  paginate,
+  paginateItems,
+  password,
+  resolveDisplayNames,
+  services,
+  tryCatch,
+  unwrap,
+  updateAccess,
+} from "./services";
+export { getDateConfig, getTimeZone, TIMEZONE_COOKIE, time } from "./time";

package/src/server/locale.ts

@@ -0,0 +1,55 @@
+import { i18n } from "@k2b/stdlib";
+import { canonicalLocale, DEFAULT_LOCALE, LOCALE_COOKIE, LOCALE_HEADER, normalizeLocale } from "../shared/locale";
+import { readCookie } from "./request-cookies";
+
+export { DEFAULT_LOCALE, LOCALE_COOKIE, LOCALE_HEADER };
+
+type LocaleContext = {
+  get(key: "settings"): Record<string, any> | undefined;
+  req: { raw: { headers: Headers } };
+};
+
+/**
+ * The caller's explicit locale preference, or `undefined` when the request
+ * carries none. Precedence: `x-cloud-locale` transport metadata, then the
+ * `cloud.locale` cookie, then `Accept-Language` in quality order. Every
+ * candidate is canonicalized; invalid tags fall through to the next source.
+ */
+export const preferredLocale = (headers: Headers): string | undefined => {
+  const explicit = canonicalLocale(headers.get(LOCALE_HEADER)) ?? canonicalLocale(readCookie(headers, LOCALE_COOKIE));
+  if (explicit) return explicit;
+  for (const tag of i18n.parseAcceptLanguage(headers.get("Accept-Language"))) {
+    const candidate = canonicalLocale(tag);
+    if (candidate) return candidate;
+  }
+  return undefined;
+};
+
+/**
+ * Resolve the request locale from plain headers: the caller's preference when
+ * present, then the operator default, then the deterministic `"en"` fallback.
+ * Pure per-request derivation — never cached in process-global state.
+ */
+export const resolveLocale = (headers: Headers, operatorDefault?: string | null): string =>
+  preferredLocale(headers) ?? normalizeLocale(operatorDefault);
+
+/**
+ * The canonical request locale: explicit preference (`x-cloud-locale` header,
+ * `cloud.locale` cookie, `Accept-Language`), then the operator's `app.locale`
+ * setting, then `"en"`. The same value drives the SSR `<html lang>` attribute,
+ * the Layout `LocaleProvider`, and `getDateConfig(c).locale`. Timezone stays a
+ * separate value — see `getTimeZone`.
+ */
+export const getLocale = (c: LocaleContext): string => {
+  const settingsLocale = c.get("settings")?.app?.locale;
+  return resolveLocale(c.req.raw.headers, typeof settingsLocale === "string" ? settingsLocale : undefined);
+};
+
+export const locale = {
+  LOCALE_COOKIE,
+  LOCALE_HEADER,
+  DEFAULT_LOCALE,
+  getLocale,
+  preferredLocale,
+  resolveLocale,
+} as const;