@k2b/cloud 0.38.0 → 0.40.0

package/src/contracts/panel-context-plain.ts

@@ -0,0 +1,99 @@
+import {
+  HELP_SHORTCUT_DESCRIPTION_MAX_LENGTH,
+  HELP_SHORTCUT_ID_MAX_LENGTH,
+  HELP_SHORTCUT_KEYS_MAX_LENGTH,
+  HELP_SHORTCUT_TITLE_MAX_LENGTH,
+  HELP_START_SHORTCUT_LIMIT,
+  type HelpShortcut,
+} from "../ssr/layout-help-start";
+import type { PanelContextMessage, PanelPageContext } from "./panel-context";
+
+/**
+ * The zod-free half of the panel context contract, for code on every page: islands, the provider runtime and the
+ * slot markup must not pull the schema into their first load (shell and Mail first-load guards). The zod schema in
+ * ./panel-context stays the contract; a parity test keeps the check below at least as strict.
+ */
+export const PANEL_CONTEXT_PARAM = "cloud_panel_context";
+
+/** Core is the platform's own surface. Every other provider asks once per app. */
+export const panelProviderNeedsConsent = (appId: string): boolean => appId !== "core";
+
+/**
+ * Only application-owned same-origin paths. The context must already be valid: Layout and the slot controller build
+ * it from validated parts. Null also removes a caller-supplied reserved parameter.
+ */
+export function withPanelContext(href: string, context: PanelPageContext | null): string {
+  // The parsed result decides, not the raw text: a query may hold a raw backslash (browsers keep it), while
+  // `/\\host` or `/\t/host` resolve to another origin and `/.//host` normalises to a protocol-relative path.
+  const base = "https://panel.invalid";
+  const url = href.startsWith("/") ? new URL(href, base) : null;
+  if (!url || url.origin !== base || url.pathname.startsWith("//")) throw new Error("Expected a same-origin panel path");
+  url.searchParams.delete(PANEL_CONTEXT_PARAM);
+  if (context) url.searchParams.set(PANEL_CONTEXT_PARAM, JSON.stringify(context));
+  return `${url.pathname}${url.search}${url.hash}`;
+}
+
+const HELP_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const APP_ID = /^[a-z][a-z0-9-]*$/;
+const QUALIFIED_ID = /^[a-z][a-z0-9-]*\.[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/;
+// RFC 9562 versions 1 to 8 with the RFC variant; the shell always uses crypto.randomUUID().
+const PAGE_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+// Exact keys, including symbol and non-enumerable ones, like the other panel messages.
+const exactKeys = (value: unknown, required: string[], optional: string[] = []): value is Record<string, unknown> => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const keys = Reflect.ownKeys(value);
+  return (
+    required.every((key) => Object.hasOwn(value, key)) &&
+    keys.every((key) => typeof key === "string" && (required.includes(key) || optional.includes(key)))
+  );
+};
+const text = (value: unknown, min: number, max: number, pattern?: RegExp): value is string =>
+  typeof value === "string" && value.length >= min && value.length <= max && (!pattern || pattern.test(value));
+
+export function isPanelPageContext(value: unknown): value is PanelPageContext {
+  if (!exactKeys(value, ["v", "seq", "pageId", "app"], ["scope", "help"])) return false;
+  const { v, seq, pageId, app, scope, help } = value;
+  return (
+    v === 1 &&
+    typeof seq === "number" &&
+    Number.isSafeInteger(seq) &&
+    seq >= 0 &&
+    text(pageId, 36, 36, PAGE_ID) &&
+    text(app, 1, 80, APP_ID) &&
+    (scope === undefined || (exactKeys(scope, ["type", "id"]) && text(scope.type, 3, 180, QUALIFIED_ID) && text(scope.id, 1, 512))) &&
+    (help === undefined ||
+      // Index by index: `every` skips the holes of a sparse array, which the schema rejects.
+      (Array.isArray(help) &&
+        help.length >= 1 &&
+        help.length <= 3 &&
+        Array.from({ length: help.length }, (_, index) => index).every((index) => index in help && text(help[index], 0, 180, HELP_ID))))
+  );
+}
+
+export function isPanelShortcut(value: unknown): value is HelpShortcut {
+  return (
+    exactKeys(value, ["id", "title", "shortcut"], ["description", "scope"]) &&
+    text(value.id, 1, HELP_SHORTCUT_ID_MAX_LENGTH) &&
+    text(value.title, 1, HELP_SHORTCUT_TITLE_MAX_LENGTH) &&
+    (value.description === undefined || text(value.description, 0, HELP_SHORTCUT_DESCRIPTION_MAX_LENGTH)) &&
+    text(value.shortcut, 1, HELP_SHORTCUT_KEYS_MAX_LENGTH) &&
+    (value.scope === undefined || value.scope === "selection" || value.scope === "page")
+  );
+}
+
+export function isPanelContextMessage(value: unknown): value is PanelContextMessage {
+  if (!exactKeys(value, ["type", "v", "context"], ["shortcuts"])) return false;
+  const { shortcuts } = value;
+  return (
+    value.type === "cloud.panel.context" &&
+    value.v === 1 &&
+    (value.context === null || isPanelPageContext(value.context)) &&
+    (shortcuts === undefined ||
+      (value.context !== null &&
+        Array.isArray(shortcuts) &&
+        shortcuts.length <= HELP_START_SHORTCUT_LIMIT &&
+        Array.from({ length: shortcuts.length }, (_, index) => index).every(
+          (index) => index in shortcuts && isPanelShortcut(shortcuts[index]),
+        )))
+  );
+}

package/src/contracts/panel-context.ts

@@ -0,0 +1,93 @@
+import { z } from "zod";
+
+export {
+  isPanelContextMessage,
+  isPanelPageContext,
+  PANEL_CONTEXT_PARAM,
+  panelProviderNeedsConsent,
+  withPanelContext,
+} from "./panel-context-plain";
+
+import { HELP_VIEW_LIMIT } from "../shared/help";
+import {
+  HELP_SHORTCUT_DESCRIPTION_MAX_LENGTH,
+  HELP_SHORTCUT_ID_MAX_LENGTH,
+  HELP_SHORTCUT_KEYS_MAX_LENGTH,
+  HELP_SHORTCUT_TITLE_MAX_LENGTH,
+  HELP_START_SHORTCUT_LIMIT,
+} from "../ssr/layout-help-start";
+import {
+  CAPABILITY_APP_ID_MAX_LENGTH,
+  CAPABILITY_QUALIFIED_ID_MAX_LENGTH,
+  CapabilityAppIdSchema,
+  CLOUD_RESOURCE_ID_MAX_LENGTH,
+  CloudResourceRefSchema,
+} from "./capabilities";
+
+/** Local Help document ids, as accepted by Layout.help, bounded for URL transport. */
+export const PANEL_HELP_ID_MAX_LENGTH = 180;
+export const PanelPageContextSchema = z
+  .object({
+    v: z.literal(1),
+    seq: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    pageId: z.uuid(),
+    app: CapabilityAppIdSchema,
+    scope: CloudResourceRefSchema.optional(),
+    help: z
+      .array(
+        z
+          .string()
+          .max(PANEL_HELP_ID_MAX_LENGTH)
+          .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+      )
+      .min(1)
+      .max(HELP_VIEW_LIMIT)
+      .optional(),
+  })
+  .strict();
+/** v1 carries only the place and static Help ids. Later fields are additive; never infer authority from a ref. */
+export type PanelPageContext = z.infer<typeof PanelPageContextSchema>;
+export type PanelConsentSnapshot = { provider: string; allowed: boolean | null; revision: number };
+
+// 128 chars cover JSON keys/punctuation, version and a 16-digit safe seq; add UUID (36), app (80),
+// ref type (180), ref id (512), and three Help ids (180 each + quotes/comma).
+// Only ref ids allow JSON escapes: each UTF-16 unit can expand to six characters (\uXXXX).
+export const PANEL_CONTEXT_PARAM_MAX_LENGTH =
+  128 +
+  36 +
+  CAPABILITY_APP_ID_MAX_LENGTH +
+  CAPABILITY_QUALIFIED_ID_MAX_LENGTH +
+  6 * CLOUD_RESOURCE_ID_MAX_LENGTH +
+  HELP_VIEW_LIMIT * (PANEL_HELP_ID_MAX_LENGTH + 3);
+
+export const encodePanelContextParam = (context: PanelPageContext): string => JSON.stringify(PanelPageContextSchema.parse(context));
+
+export function parsePanelContextParam(value: string | null | undefined): PanelPageContext | null {
+  if (!value || value.length > PANEL_CONTEXT_PARAM_MAX_LENGTH) return null;
+  try {
+    const parsed = PanelPageContextSchema.safeParse(JSON.parse(value));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+
+const PanelShortcutSchema = z
+  .object({
+    id: z.string().min(1).max(HELP_SHORTCUT_ID_MAX_LENGTH),
+    title: z.string().min(1).max(HELP_SHORTCUT_TITLE_MAX_LENGTH),
+    description: z.string().max(HELP_SHORTCUT_DESCRIPTION_MAX_LENGTH).optional(),
+    shortcut: z.string().min(1).max(HELP_SHORTCUT_KEYS_MAX_LENGTH),
+    scope: z.enum(["selection", "page"]).optional(),
+  })
+  .strict();
+export const PanelContextMessageSchema = z
+  .object({
+    type: z.literal("cloud.panel.context"),
+    v: z.literal(1),
+    context: PanelPageContextSchema.nullable(),
+    shortcuts: z.array(PanelShortcutSchema).max(HELP_START_SHORTCUT_LIMIT).optional(),
+  })
+  .strict()
+  .refine((message) => message.context !== null || message.shortcuts === undefined);
+export type PanelContextMessage = z.infer<typeof PanelContextMessageSchema>;

package/src/contracts/registry.ts

@@ -1,4 +1,4 @@
-import type { AppAdminNavigationGroup, AppAppearance, AppAppearanceColor, AppPresentationCatalog, AppSearchLink } from "./app";
+import type { AppAdminNavigationGroup, AppAppearance, AppAppearanceColor, AppPanel, AppPresentationCatalog, AppSearchLink } from "./app";
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "./capabilities";
 import type { PlatformPermission } from "./outgoing-mail";
 import type { Role } from "./shared";
@@ -103,6 +103,8 @@ export type AppRegistryEntry = {
   searchLinks?: readonly AppSearchLink[];
   /** The app's part of the mobile app (preview); `href` is `/pwa/<id>`. Older readers ignore it. */
   pwa?: AppRegistryPwaPart;
+  /** Optional panel declaration; older readers ignore it. */
+  panel?: AppPanel;
   widgets?: AppRegistryWidget[];
   /** Setting keys declared by this app. Used by admin tooling to avoid treating live app-owned settings as legacy. */
   settingKeys?: readonly string[];

package/src/contracts/seen-hints.ts

@@ -0,0 +1,35 @@
+export const SEEN_HINTS_COOKIE = "cloud_seen_hints";
+export const SEEN_HINTS_COOKIE_MAX_AGE_SECONDS = 60 * 60 * 24 * 365;
+export const MAX_SEEN_HINTS = 64;
+
+const COOKIE_ATTRIBUTES = `; Path=/; Max-Age=${SEEN_HINTS_COOKIE_MAX_AGE_SECONDS}; SameSite=Lax`;
+// RFC 6265's 4096-byte budget includes name, value and attributes. Reserve Secure on HTTP too.
+const MAX_COOKIE_VALUE_LENGTH = 4096 - `${SEEN_HINTS_COOKIE}=${COOKIE_ATTRIBUTES}; Secure`.length;
+
+export const isHintId = (id: unknown): id is string => typeof id === "string" && /^[a-z0-9][a-z0-9._-]{0,63}$/.test(id);
+
+/** Keep the most recent occurrence, with the newest hints last. */
+const normalize = (ids: readonly string[]): string[] => {
+  const recent = [...new Set(ids.filter(isHintId).toReversed())].reverse().slice(-MAX_SEEN_HINTS);
+  while (recent.join("~").length > MAX_COOKIE_VALUE_LENGTH) recent.shift();
+  return recent;
+};
+
+export const parseSeenHintsCookieHeader = (header: string | null | undefined): string[] => {
+  const value = header
+    ?.split(";")
+    .map((part) => part.trim())
+    .find((part) => part.startsWith(`${SEEN_HINTS_COOKIE}=`))
+    ?.slice(SEEN_HINTS_COOKIE.length + 1);
+  return normalize(value?.split("~") ?? []);
+};
+
+export const serializeSeenHints = (ids: readonly string[]): string => normalize(ids).join("~");
+
+export const mergeSeenHints = (current: readonly string[], id: string): string[] => {
+  if (!isHintId(id)) throw new Error(`Invalid hint id: ${id}`);
+  return normalize([...current, id]);
+};
+
+export const seenHintsSetCookie = (ids: readonly string[], secure: boolean): string =>
+  `${SEEN_HINTS_COOKIE}=${serializeSeenHints(ids)}${COOKIE_ATTRIBUTES}${secure ? "; Secure" : ""}`;

package/src/contracts/shared.ts

@@ -401,6 +401,8 @@ export type SettingEntry = {
   valueSource: SettingValueSource;
   resetValueSource: Exclude<SettingValueSource, "custom">;
   isCustom: boolean;
+  /** A stored row exists but this application cannot decrypt or validate it; `value` is the fallback in use. */
+  unreadable: boolean;
   templateVars?: string[];
   options?: SettingOption[];
   min?: number;

package/src/server/client-ip.ts

@@ -0,0 +1,5 @@
+import type { Context } from "hono";
+
+// The gateway (packages/gateway/src/client-address.ts) resolves this address using GATEWAY_TRUSTED_PROXIES.
+export const clientIp = (c: Context): string =>
+  c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ?? c.req.header("x-real-ip") ?? "unknown";

package/src/server/help-payload.ts

@@ -0,0 +1,38 @@
+import { keyboardPlatform } from "@k2b/ui";
+import { helpAgentMarkdown } from "../_internal/help-catalog";
+import type { HelpArticle } from "../services/help/types";
+import { type HelpDocumentPayload, parseHelpReference } from "../shared/help";
+import { renderHelpMarkdown } from "../shared/markdown";
+
+/** The same authorized article presentation for the API and the server's first frame. */
+export const buildHelpDocumentPayload = (
+  document: HelpArticle,
+  userAgent: string,
+  renderMarkdown: typeof renderHelpMarkdown = renderHelpMarkdown,
+): HelpDocumentPayload => {
+  const links = (reference: { appId?: string; documentId: string }) =>
+    document.links[`${reference.appId ?? document.appId}/${reference.documentId}`];
+  const resolve = (reference: string) => {
+    const ref = parseHelpReference(reference);
+    return ref ? links(ref) : undefined;
+  };
+  const payload: HelpDocumentPayload = {
+    locale: document.locale,
+    id: document.documentId,
+    title: document.title,
+    markdown: helpAgentMarkdown(document),
+    kind: document.kind,
+    needs: document.needs,
+    next: document.next ? resolve(document.next) : undefined,
+    related: document.related.flatMap((reference) => {
+      const target = resolve(reference);
+      return target ? [target] : [];
+    }),
+    html: renderMarkdown(document.markdown, {
+      locale: document.locale,
+      platform: keyboardPlatform(userAgent),
+      links,
+    }),
+  };
+  return payload;
+};

package/src/server/middleware/auth.ts

@@ -411,7 +411,16 @@ const getAuthority = (c: Context<AuthContext>): RequestAuthority => {
  * True when the request acts through the mobile app's session, directly or through an
  * invocation made for one. Such requests cannot create authority that outlives the phone.
  */
-const isAppSession = (c: Context<AuthContext>): boolean => isAppSessionActor(c.get("actor"));
+const isAppSession = <E extends AuthContext>(c: Context<E>): boolean => isAppSessionActor(c.get("actor"));
+
+/** Returns only the browser session identity authenticated for this request. */
+const browserSignIn = async <E extends AuthContext>(c: Context<E>): Promise<{ userId: string; sid: string } | null> => {
+  if (c.get("credentialKind") !== "session" || c.get("actor")?.kind !== "user" || isAppSession(c)) return null;
+  const token = c.get("sessionToken");
+  if (!token) return null;
+  const authenticated = await session.authenticateRequest(c, token);
+  return authenticated?.data.kind === "web" ? { userId: authenticated.data.userId, sid: authenticated.data.sid } : null;
+};
 
 /** The standard answer for actions the mobile app may not take. */
 export const APP_SESSION_FORBIDDEN = { code: "FORBIDDEN", message: "Use Cloud on the web for this." } as const;
@@ -460,6 +469,7 @@ export const auth = {
   requireRole,
   requireUser,
   isAppSession,
+  browserSignIn,
   rejectAppSession,
   requireOAuthScope,
   getAuthority,

package/src/server/middleware/middleware.ts

@@ -23,6 +23,7 @@
  * orthogonal to the request lifecycle.
  */
 import { describeRoute } from "hono-openapi";
+import { noTransform } from "./no-transform";
 import { rateLimit } from "./rate-limit";
 import { requestLogger } from "./request-logger";
 import { routeTemplate } from "./route-template";
@@ -31,6 +32,14 @@ import { settings } from "./settings";
 import { validator } from "./validator";
 
 export const middleware = {
+  /**
+   * Use when another party can repeatedly write text beside unreadable text,
+   * personal submissions or secrets worth guessing, including live refetches.
+   * Metadata alone and containers every writer can read stay compressed.
+   * Mount `.use("*", middleware.noTransform())` first on the app/route-group
+   * router, or use it as per-route middleware. Sets Cache-Control: no-transform.
+   */
+  noTransform,
   /**
    * Live cluster registry on `c.get("runtime")`. Required for Layout/Sidebar.
    * Also reports the matched route template to gateway telemetry — you do not

package/src/server/middleware/no-transform.ts

@@ -0,0 +1,19 @@
+import { createMiddleware } from "hono/factory";
+
+export const noTransform = () =>
+  createMiddleware(async (c, next) => {
+    await next();
+    if (c.res.status === 101) return;
+    const value = c.res.headers.get("Cache-Control");
+    if (
+      (value?.match(/(?:[^,"]|"[^"]*")+/g) ?? []).some((directive) => directive.split("=", 1)[0]?.trim().toLowerCase() === "no-transform")
+    )
+      return;
+    const merged = value ? `${value}, no-transform` : "no-transform";
+    try {
+      c.res.headers.set("Cache-Control", merged);
+    } catch {
+      c.res = new Response(c.res.body, c.res);
+      c.res.headers.set("Cache-Control", merged);
+    }
+  });

package/src/server/middleware/rate-limit.ts

@@ -2,6 +2,7 @@ import type { Context, MiddlewareHandler } from "hono";
 import { createMiddleware } from "hono/factory";
 import type { MessageResponse } from "../../contracts/shared";
 import * as settings from "../../services/settings";
+import { clientIp } from "../client-ip";
 import { ratelimit } from "../ratelimit";
 import { type AuthContext, auth } from "./auth";
 
@@ -29,9 +30,6 @@ const DEFAULT_WINDOW_SECS = 1;
 const LIMITER_PREFIX = "cloud:rate-limit";
 const limiterCache = new Map<string, ReturnType<typeof ratelimit>>();
 
-const getClientIp = (c: Context): string =>
-  c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ?? c.req.header("x-real-ip") ?? "unknown";
-
 const pathMatches = (requestPath: string, matcher: string | RegExp): boolean => {
   if (matcher instanceof RegExp) return matcher.test(requestPath);
   return requestPath === matcher || requestPath.startsWith(`${matcher}/`);
@@ -83,13 +81,13 @@ const getLimiter = (limitPerSecond: number, windowSecs: number) => {
 };
 
 const resolveIdentifier = async (c: Context<AuthContext>, keyBy: RateLimitConfig["keyBy"]): Promise<string> => {
-  if (keyBy === "ip") return `ip:${getClientIp(c)}`;
+  if (keyBy === "ip") return `ip:${clientIp(c)}`;
 
   const token = auth.session.getToken(c);
-  if (!token) return `ip:${getClientIp(c)}`;
+  if (!token) return `ip:${clientIp(c)}`;
 
   const userId = await auth.session.getRequestSubject(c, token);
-  if (!userId) return `ip:${getClientIp(c)}`;
+  if (!userId) return `ip:${clientIp(c)}`;
 
   return `user:${userId}`;
 };

package/src/server/request-context/address.ts

@@ -0,0 +1,45 @@
+import { isUnsafeNetworkAddress, parseNetworkAddress } from "../../shared/network-address";
+
+const ADDRESS_BUDGET = 64;
+
+const ipv6Groups = (address: string): number[] => {
+  const [left = "", right = ""] = address.split("::");
+  const leading = left ? left.split(":") : [];
+  const trailing = right ? right.split(":") : [];
+  return [...leading, ...Array<string>(8 - leading.length - trailing.length).fill("0"), ...trailing].map((group) =>
+    Number.parseInt(group, 16),
+  );
+};
+
+export const publicClientAddress = (raw: string | null | undefined): string | null => {
+  try {
+    const input = raw?.trim();
+    if (!input || input.length > ADDRESS_BUDGET) return null;
+    if (input.includes("[") || input.includes("]")) return null;
+    const parsed = parseNetworkAddress(input);
+    if (!parsed || isUnsafeNetworkAddress(parsed.address)) return null;
+    if (parsed.family === 6) {
+      const groups = ipv6Groups(parsed.address);
+      if (
+        [0, 0, 0, 0, 0, 0xffff].every((group, index) => groups[index] === group) ||
+        [0x64, 0xff9b, 0, 0, 0, 0].every((group, index) => groups[index] === group)
+      ) {
+        const high = groups[6]!;
+        const low = groups[7]!;
+        return [high >> 8, high & 255, low >> 8, low & 255].join(".");
+      }
+    }
+    return parsed.address;
+  } catch {
+    return null;
+  }
+};
+
+export const addressPrefix = (address: string): string | null => {
+  const canonical = publicClientAddress(address);
+  if (!canonical) return null;
+  if (!canonical.includes(":")) return canonical;
+  const groups = ipv6Groups(canonical).map((group) => group.toString(16));
+  const prefix = parseNetworkAddress(`${groups.slice(0, 4).join(":")}:0:0:0:0`);
+  return prefix ? `${prefix.address}/64` : null;
+};