@k2b/cloud 0.42.0 → 0.44.0

package/src/_internal/object-store-config.ts

@@ -0,0 +1,101 @@
+import { S3Client } from "bun";
+import { z } from "zod";
+import { readStates } from "../services/settings/store";
+
+export const objectStoreSettingKeys = [
+  "storage.endpoint",
+  "storage.region",
+  "storage.bucket",
+  "storage.access_key_id",
+  "storage.secret_access_key",
+  "storage.max_object_bytes",
+] as const;
+const bucket = z
+  .string()
+  .min(3)
+  .max(63)
+  .regex(/^[a-z0-9][a-z0-9.-]*[a-z0-9]$/);
+const Config = z.object({
+  endpoint: z.string().min(1),
+  region: z.string().min(1),
+  bucket,
+  access_key_id: z.string().min(1),
+  secret_access_key: z.string().min(1),
+  max_object_bytes: z
+    .number()
+    .int()
+    .min(1)
+    .max(5 * 1024 ** 3),
+});
+export class ObjectStoreConfigurationError extends Error {}
+export class ObjectStoreConnectionError extends Error {}
+let cached: { signature: string; client: S3Client } | undefined;
+
+export const objectStoreBackend = async () => {
+  // Read one coherent DB snapshot, including stored-state checks. No local TTL:
+  // changes and secret rotation apply to the next operation in every process.
+  const states = await readStates(objectStoreSettingKeys);
+  if (objectStoreSettingKeys.some((key) => states.get(key)?.stored === "unreadable")) {
+    throw new ObjectStoreConfigurationError(
+      "Storage settings cannot be decrypted. Check this process uses the installation APP_SECRET, then replace unreadable settings in Administration > Settings > Storage.",
+    );
+  }
+  const parsed = Config.safeParse(
+    Object.fromEntries(objectStoreSettingKeys.map((key) => [key.slice("storage.".length), states.get(key)?.value])),
+  );
+  if (!parsed.success)
+    throw new ObjectStoreConfigurationError(
+      "Storage is not configured. Set the Garage endpoint, region, bucket and credentials in Administration > Settings > Storage.",
+    );
+  const config = parsed.data;
+  const endpoint = URL.parse(config.endpoint);
+  if (
+    !endpoint ||
+    !["http:", "https:"].includes(endpoint.protocol) ||
+    endpoint.username ||
+    endpoint.password ||
+    endpoint.search ||
+    endpoint.hash ||
+    endpoint.pathname !== "/"
+  ) {
+    throw new ObjectStoreConfigurationError("Storage endpoint must be an HTTP(S) origin without credentials, path, query or fragment.");
+  }
+  const signature = JSON.stringify(config);
+  if (cached?.signature !== signature) {
+    const options = {
+      endpoint: endpoint.href,
+      accessKeyId: config.access_key_id,
+      secretAccessKey: config.secret_access_key,
+      region: config.region,
+    };
+    cached = { signature, client: new S3Client({ ...options, bucket: config.bucket }) };
+  }
+  return { client: cached.client, limit: config.max_object_bytes };
+};
+
+/** Internal administrator check; never an application API or a credential response. */
+export const testObjectStoreConnection = async (): Promise<void> => {
+  const backend = await objectStoreBackend();
+  const file = backend.client.file(`cloud-connection-test/${crypto.randomUUID()}`);
+  const content = "Cloud storage connection test";
+  let step = "write";
+  try {
+    await file.write(content, { type: "text/plain" });
+    step = "read";
+    if ((await file.text()) !== content) throw new Error("Unexpected content");
+    step = "delete";
+    await file.delete();
+    if (await file.exists()) throw new Error("Object still exists");
+  } catch {
+    try {
+      await file.delete();
+    } catch {
+      throw new ObjectStoreConnectionError(
+        `Storage test failed at ${step}; cleanup failed. Remove cloud-connection-test/ objects after fixing the connection.`,
+      );
+    }
+    throw new ObjectStoreConnectionError(
+      `Storage test failed at ${step}. Check the saved settings, Garage availability and bucket permissions, then retry.`,
+    );
+  }
+};

package/src/_internal/object-store-key.ts

@@ -0,0 +1,14 @@
+// S3's complete object key, including the area, is limited to 1,024 UTF-8 bytes.
+// Reject percent signs altogether, including nested encodings, before Bun sees a key.
+export const validateObjectKey = (key: string, area: string, allowPrefix = false): string => {
+  if (typeof key !== "string" || !key.isWellFormed() || key !== key.normalize("NFC") || /[\\%\p{Cc}\p{Cf}]/u.test(key)) {
+    throw new TypeError("Object keys must be NFC text without controls, backslashes, or percent escapes.");
+  }
+  if (allowPrefix && key === "") return key;
+  const path = allowPrefix && key.endsWith("/") ? key.slice(0, -1) : key;
+  if (!path || path.split("/").some((segment) => !segment || segment === "." || segment === "..")) {
+    throw new TypeError("Object keys must be relative paths without empty, dot, or parent segments.");
+  }
+  if (Buffer.byteLength(area + key) > 1024) throw new RangeError("Object key exceeds S3's 1,024-byte limit including its area.");
+  return key;
+};

package/src/_internal/page-responses.ts

@@ -1,11 +1,18 @@
 import type { HtmlFn } from "@k2b/ssr";
 import type { Context } from "hono";
 import type { ClientErrorStatusCode, ServerErrorStatusCode } from "hono/utils/http-status";
+import type { AppMeta } from "../contracts/app";
 import { PWA_AUTH_PATH, PWA_SCOPE } from "../contracts/pwa";
 import { getLocale } from "../server/locale";
-import { preloadLayoutAnnouncements } from "../server/middleware/settings";
+import { runtime } from "../server/middleware/runtime";
+import { preloadLayoutAnnouncements, settings } from "../server/middleware/settings";
+import { appAccessAuthority } from "../services/app-access";
+import { appAccessManagers, canRepairAppAccess } from "../services/app-access-management";
+import { logger } from "../services/logging";
+import { resolveAppPresentation } from "../shared/app-presentation";
 import { createLoginRedirectUrl } from "../shared/redirect";
 import { readThemePreferenceFromCookieHeader } from "../shared/theme";
+import { preloadDisplayApps } from "../ssr/runtime";
 import type { PageOptions } from "./define-app";
 
 export type PageErrorOptions = {
@@ -19,10 +26,12 @@ export type PageErrorOptions = {
 export type PageErrorStatus = ClientErrorStatusCode | ServerErrorStatusCode;
 
 /** Explicit document responses, bound to the owning application's SSR template. */
-export const createPageResponses = (html: HtmlFn<PageOptions>) => {
+export const createPageResponses = <T extends PageOptions>(html: HtmlFn<T>, appId: string, requestOptions?: (c: Context) => Partial<T>) => {
   const error = async (c: Context, status: PageErrorStatus, options: PageErrorOptions = {}): Promise<Response> => {
     // Auth middleware may reject before ssr() initializes page metadata.
     c.set("page", {
+      ...requestOptions?.(c),
+      pwaOwner: appId,
       lang: getLocale(c),
       themePreference: readThemePreferenceFromCookieHeader(c.req.header("Cookie")),
     });
@@ -58,5 +67,27 @@ export const createPageResponses = (html: HtmlFn<PageOptions>) => {
     },
   };
 
-  return { access, pwaAccess, error };
+  const appAccessDenied = async (c: Context, app: AppMeta): Promise<Response> => {
+    await runtime()(c, async () => {});
+    await settings()(c, async () => {});
+    c.set("page", { lang: getLocale(c), themePreference: readThemePreferenceFromCookieHeader(c.req.header("Cookie")) });
+    await preloadDisplayApps(c);
+    const managers =
+      app.access?.kind === "grants"
+        ? await appAccessManagers(app.id).catch((error: unknown) => {
+            logger("app-access").error("Could not load application access contacts", { appId: app.id, error });
+            // Cloud administration remains the recovery contact when the list is unavailable.
+            return [];
+          })
+        : [];
+    const authority = appAccessAuthority(c);
+    const { renderAppAccessDenied } = await import("../ssr/AppAccessDenied");
+    const response = await html(
+      renderAppAccessDenied(c, resolveAppPresentation(app, getLocale(c)), managers, !!authority && canRepairAppAccess(authority)),
+      c.get("page"),
+    );
+    response.headers.set("Cache-Control", "private, no-store");
+    return new Response(response.body, { status: 403, headers: response.headers });
+  };
+  return { access, pwaAccess, error, appAccessDenied };
 };

package/src/_internal/process-identity.ts

@@ -2,20 +2,25 @@ import type { PlatformPermission } from "../contracts/outgoing-mail";
 
 /** Identity of the application started in this process, derived from its declaration. */
 let applicationId: string | undefined;
+let applicationPackage: string | undefined;
 let platformPermissions: readonly PlatformPermission[] = [];
 export const getProcessPlatformPermissions = (): readonly PlatformPermission[] => platformPermissions;
 
 export const getProcessApplicationId = (): string | undefined => applicationId;
 
-export const bindProcessApplicationId = (id: string, permissions: readonly PlatformPermission[] = []): void => {
-  if (applicationId !== undefined && applicationId !== id) {
+export const getProcessApplicationPackage = (): string | undefined => applicationPackage;
+
+export const bindProcessApplicationId = (id: string, permissions: readonly PlatformPermission[] = [], packageName = id): void => {
+  if (applicationId !== undefined && (applicationId !== id || applicationPackage !== packageName)) {
     throw new Error(`This process already hosts application "${applicationId}"`);
   }
   applicationId = id;
+  applicationPackage = packageName;
   platformPermissions = [...permissions];
 };
 
 export const clearProcessApplicationId = (): void => {
   applicationId = undefined;
+  applicationPackage = undefined;
   platformPermissions = [];
 };

package/src/_internal/registry-validation.ts

@@ -1,5 +1,7 @@
 import { CLOUD_CLI_MODULE_NAME } from "../cli/plugin";
+import { APP_ADMIN_AREAS } from "../contracts/app";
 import { AppAccessRuleSchema } from "../contracts/app-access";
+import { validateInstallable } from "../contracts/installable";
 import { PlatformPermissionSchema } from "../contracts/outgoing-mail";
 import type { AppRegistryEntry } from "../contracts/registry";
 import { isOwnAppPath, SAME_ORIGIN_PATH } from "./app-path";
@@ -18,6 +20,9 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
   for (const field of ["id", "name", "icon", "description", "baseUrl"] as const) {
     if (!isString(value[field]) || value[field].length === 0) return invalid(field, "a non-empty string");
   }
+  if (value.package !== undefined && (typeof value.package !== "string" || !/^[a-z][a-z0-9-]{0,79}$/.test(value.package))) {
+    return invalid("package", "a lowercase package name of 1–80 characters");
+  }
   try {
     const baseUrl = new URL(value.baseUrl as string);
     if (!(["http:", "https:"] as const).includes(baseUrl.protocol as "http:" | "https:") || baseUrl.username || baseUrl.password) {
@@ -29,6 +34,9 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
   if (!isStringArray(value.routes) || value.routes.some((route) => !route.startsWith("/"))) {
     return invalid("routes", "an array of absolute paths");
   }
+  if (value.installable !== undefined && !validateInstallable(String(value.id), value.routes, value.installable)) {
+    return invalid("installable", "a canonical standalone surface covered by the app's own declared routes");
+  }
   if (value.access !== undefined && !AppAccessRuleSchema.safeParse(value.access).success)
     return invalid("access", "a declarative app access rule");
   if (value.startedAt !== undefined && !(typeof value.startedAt === "number" && Number.isFinite(value.startedAt))) {
@@ -96,7 +104,7 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
         (group) =>
           !isRecord(group) ||
           (group.id !== undefined && !isString(group.id)) ||
-          (group.section !== undefined && group.section !== "ai") ||
+          (group.section !== undefined && !(APP_ADMIN_AREAS as readonly unknown[]).includes(group.section)) ||
           !isString(group.label) ||
           !Array.isArray(group.links) ||
           group.links.some((link) => !isRecord(link) || !isString(link.label) || !isString(link.href) || !isString(link.icon)),
@@ -137,6 +145,12 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
     if (value.pwa.requiresRoles !== undefined && !isStringArray(value.pwa.requiresRoles)) {
       return invalid("pwa.requiresRoles", "an array of strings");
     }
+    for (const field of ["badge", "summary"] as const) {
+      const path = value.pwa[field];
+      if (path !== undefined && (!isString(path) || !isOwnAppPath(path, value.routes))) {
+        return invalid(`pwa.${field}`, "a same-origin path below one of the app's routes");
+      }
+    }
   }
   if (value.widgets !== undefined) {
     if (

package/src/_internal/registry.ts

@@ -1,9 +1,11 @@
 import { createHash } from "node:crypto";
 import type { EphemeralConfig, MutexConfig } from "@k2b/sync";
 import type { AppAppearanceColor } from "../contracts/app";
+import { calendarSourceIssues } from "../contracts/calendar-source";
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "../contracts/capabilities";
 import { fileProviderIssues } from "../contracts/file-provider";
 import type { AppRegistryEntry, CapabilityRegistryEntry } from "../contracts/registry";
+import { resourcePageIssue } from "../contracts/resource-pages";
 import { type Role, RoleSchema } from "../contracts/shared";
 import {
   type DashboardWidgetPresentation,
@@ -233,6 +235,7 @@ const reportLeftOutEntries = (sent: unknown, manifest: CapabilityManifest): void
       return typeof localId === "string" && !kept.has(localId) ? [`${group}/${localId}`] : [];
     });
   });
+  if (groups.calendarSource !== undefined && !manifest.calendarSource) leftOut.push("calendarSource");
   if (groups.fileProvider !== undefined && !manifest.fileProvider) leftOut.push("fileProvider");
   if (leftOut.length === 0) return;
   console.warn(
@@ -283,6 +286,40 @@ const withValidFileProvider = (manifest: CapabilityManifest): CapabilityManifest
   return rest;
 };
 
+const checkedCalendarSources = new Map<string, { manifestHash: string; valid: boolean }>();
+
+/**
+ * Ignores a calendar source that does not match the contract, logging once per manifest; the app's other
+ * capabilities stay available. The delivered `manifestHash` stays, because it identifies what the app registered.
+ */
+const withValidCalendarSource = (manifest: CapabilityManifest): CapabilityManifest => {
+  if (!manifest.calendarSource) return manifest;
+  const checked = checkedCalendarSources.get(manifest.appId);
+  let valid = checked?.manifestHash === manifest.manifestHash ? checked.valid : undefined;
+  if (valid === undefined) {
+    const issues = calendarSourceIssues(manifest);
+    valid = issues.length === 0;
+    checkedCalendarSources.set(manifest.appId, { manifestHash: manifest.manifestHash, valid });
+    if (!valid) {
+      console.error(
+        JSON.stringify({
+          level: "error",
+          source: "capability-registry",
+          message: "Ignored a calendar source that does not match the calendar-source contract",
+          appId: manifest.appId,
+          manifestHash: manifest.manifestHash,
+          issues: issues
+            .slice(0, 10)
+            .map(({ function: name, localId, code, path, message }) => ({ function: name, localId, code, path, message })),
+        }),
+      );
+    }
+  }
+  if (valid) return manifest;
+  const { calendarSource: _ignored, ...rest } = manifest;
+  return rest;
+};
+
 /** Ignores record fields from a newer release; the endpoint always comes from the live app registry. */
 export const resolveLiveCapabilityRegistryEntry = (
   key: string,
@@ -297,7 +334,13 @@ export const resolveLiveCapabilityRegistryEntry = (
   if (!endpoint) return null;
   try {
     const read = parseCapabilityManifest(record.manifest, app.id);
-    const manifest = withValidFileProvider(read);
+    const supported = withValidCalendarSource(withValidFileProvider(read));
+    const manifest = supported.resourcePages
+      ? {
+          ...supported,
+          resourcePages: supported.resourcePages.filter((page) => !resourcePageIssue(page.path, app.routes, app.id)),
+        }
+      : supported;
     const presentation = compileCapabilityPresentation(manifest, record.presentation, "reader");
     if (app.capabilities.protocolVersion !== manifest.protocolVersion || app.capabilities.manifestHash !== manifest.manifestHash) {
       return null;

package/src/_internal/runtime-context.ts

@@ -71,7 +71,15 @@ export const buildRuntimeFromRegistry = (entries: AppRegistryEntry[], capabiliti
       ),
       legalLinks: e.legalLinks ? e.legalLinks.map((l) => ({ ...l })) : undefined,
       searchLinks: e.searchLinks?.map((link) => ({ ...link, keywords: link.keywords ? [...link.keywords] : undefined })),
-      pwa: e.pwa ? { href: e.pwa.href, requiresRoles: e.pwa.requiresRoles ? ([...e.pwa.requiresRoles] as Role[]) : undefined } : undefined,
+      pwa: e.pwa
+        ? {
+            href: e.pwa.href,
+            requiresRoles: e.pwa.requiresRoles ? ([...e.pwa.requiresRoles] as Role[]) : undefined,
+            ...(e.pwa.badge ? { badge: e.pwa.badge } : {}),
+            ...(e.pwa.summary ? { summary: e.pwa.summary } : {}),
+          }
+        : undefined,
+      installable: e.installable ? structuredClone(e.installable) : undefined,
       openapi: e.openapi,
     };
   }),

package/src/_internal/runtime-watcher.ts

@@ -11,6 +11,7 @@
  */
 
 import type { CloudRuntime } from "../contracts/app";
+import { pwaBuilds } from "../contracts/pwa-builds";
 import { logger } from "../services/logging";
 import { superviseRuntimeTask } from "../services/runtime-lifecycle";
 import { listApps, listCapabilities, watchAppRegistry } from "./registry";
@@ -19,6 +20,11 @@ import { buildRuntimeFromRegistry } from "./runtime-context";
 const log = logger("runtime-watcher");
 
 let current: CloudRuntime | undefined;
+let mobileBuilds: Record<string, string> = {};
+
+/** Current registered release identities for the existing mobile session keepalive. */
+export const registeredPwaBuilds = (): Record<string, string> => mobileBuilds;
+
 let coreRelease: string | undefined;
 let initPromise: Promise<void> | undefined;
 let watcherTask: Promise<void> | undefined;
@@ -28,6 +34,7 @@ const refresh = async () => {
   const apps = await listApps();
   const capabilities = await listCapabilities(apps);
   current = buildRuntimeFromRegistry(apps, capabilities);
+  mobileBuilds = pwaBuilds(apps);
   coreRelease = apps.find((app) => app.id === "core")?.runtime?.release;
 };
 
@@ -74,6 +81,7 @@ export const stopRuntimeWatcher = async (): Promise<void> => {
   initPromise = undefined;
   current = undefined;
   coreRelease = undefined;
+  mobileBuilds = {};
 };
 
 export const getCurrentRuntime = (): CloudRuntime => {

package/src/_internal/status-preserving-ssr.ts

@@ -1,8 +1,10 @@
 import type { HtmlFn, RenderFn } from "@k2b/ssr";
 import { createSSRHandler } from "@k2b/ssr/hono";
 import type { Context, Env, MiddlewareHandler, TypedResponse } from "hono";
+import { setCookie } from "hono/cookie";
 import type { StatusCode } from "hono/utils/http-status";
 import type { PanelConsentSnapshot } from "../contracts/panel-context";
+import { PWA_COOKIES, PWA_LIMITS, PWA_SCOPE } from "../contracts/pwa";
 import type { RailSnapshot } from "../contracts/rail-preferences";
 import type { SettingsFlat, Unflatten } from "../contracts/settings-types";
 import type { User } from "../contracts/shared";
@@ -12,7 +14,7 @@ import { measureServerPhase } from "./server-timing";
 
 type PageEnv<T extends object> = {
   Variables: {
-    page: Partial<T>;
+    page: Partial<T> & { pwaAddress?: string };
     user?: User;
     railPreferences?: RailSnapshot;
     panelConsent?: PanelConsentSnapshot;
@@ -62,6 +64,15 @@ export const createStatusPreservingSsrHandler = <T extends object>(
       response.headers.forEach((value, key) => {
         headers[key] = value;
       });
+      const address = context.get("page").pwaAddress;
+      if (address && status < 400) {
+        setCookie(context, PWA_COOKIES.lastAddress, address, {
+          path: PWA_SCOPE,
+          secure: true,
+          sameSite: "Lax",
+          maxAge: PWA_LIMITS.idleDays * 86_400,
+        });
+      }
       const document = context.newResponse(response.body, status as StatusCode, headers);
       // A rendered document carries the signed-in user's state. Without an
       // explicit policy, a browser may show it again on Back from its HTTP