@k2b/cloud 0.34.0 → 0.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -107,7 +107,7 @@
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.18.0",
     "@k2b/ssr": "0.16.0",
-    "@k2b/ui": "0.25.0",
+    "@k2b/ui": "0.26.0",
     "@k2b/stdlib": "0.29.0",
     "@k2b/sync": "7.0.0",
     "@nats-io/jetstream": "3.4.0",

package/src/access/GroupCoverage.tsx

@@ -68,12 +68,13 @@ const firstPage = (coverage: GroupCoverage) => coverage.members.pages()[0];
  * The members toggle beside the group name. Its label never changes, so
  * loading the members moves nothing in the row; the count leads the list.
  */
-export function GroupCoverageToggle(props: { coverage: GroupCoverage; groupName: string }) {
+export function GroupCoverageToggle(props: { coverage: GroupCoverage; groupName: string; disabled?: boolean }) {
   const locale = useLocale();
   const t = () => accessMessages.resolve([locale()]).t;
   return (
     <button
       type="button"
+      disabled={props.disabled}
       aria-expanded={props.coverage.open()}
       aria-controls={props.coverage.panelId}
       // The group name tells several group rows apart.

package/src/access/PermissionEditor.tsx

@@ -1,14 +1,14 @@
 import { mutation } from "@k2b/stdlib/solid";
-import { IconButton, Placeholder, prompts, SelectChip, Tooltip, useLocale } from "@k2b/ui";
-import { createMemo, For, Show } from "solid-js";
-import { createStore } from "solid-js/store";
+import { announce, IconButton, Placeholder, prompts, SelectChip, Tooltip, useLocale } from "@k2b/ui";
+import { createMemo, createSignal, For, onCleanup, Show } from "solid-js";
+import { createStore, reconcile } from "solid-js/store";
 import { CloudAvatar } from "../account/Avatar";
 import type { AccessEntry, PermissionLevel, Principal, ServiceAccountKind } from "../contracts/shared";
 import { groupDisplayName } from "../shared/account-display";
 import { createGroupCoverage, type GroupCoverage, GroupCoveragePanel, GroupCoverageToggle } from "./GroupCoverage";
 import { isManagerEntry } from "./managers";
 import { accessMessages } from "./messages";
-import PrincipalPicker from "./PrincipalPicker";
+import PrincipalPicker, { principalKey } from "./PrincipalPicker";
 import { serviceAccountKindDisplay } from "./service-account-kind";
 
 // ─────────────────────────────────────────────────────────────────────────
@@ -180,6 +180,12 @@ export default function PermissionEditor(props: PermissionEditorProps) {
   // A store keeps each row's identity across level changes, so an expanded member list stays open. It holds
   // copies: store writes go into the objects themselves, and the caller's entries are not the editor's to change.
   const [entries, setEntries] = createStore<AccessEntry[]>(props.initialEntries.map((entry) => ({ ...entry })));
+  const [pending, setPending] = createSignal<string | null>(null);
+  const grantPending = () => pending() !== null;
+  let disposed = false;
+  onCleanup(() => {
+    disposed = true;
+  });
   const canEdit = () => props.canEdit !== false;
   const allowPublic = () => props.allowPublic === true;
   const allowAuthenticated = () => props.allowAuthenticated !== false;
@@ -196,18 +202,38 @@ export default function PermissionEditor(props: PermissionEditorProps) {
     }
   }
 
-  const grantMut = mutation.create({
-    mutation: async (data: {
-      principal: Principal;
-      permission: GrantableLevel;
-      scope: string | undefined;
-      display: { displayName: string; serviceAccountKind?: ServiceAccountKind };
-    }) => props.grantAccess(data.principal, data.permission, data.display, data.scope),
-    onSuccess: (newEntry) => {
-      setEntries(entries.length, { ...newEntry });
-    },
-    onError: (err) => prompts.error(err.message),
-  });
+  const grant = async (principal: Principal, display: { displayName: string; serviceAccountKind?: ServiceAccountKind }) => {
+    if (disposed || grantPending() || updateMut.loading() || revokeMut.loading()) return;
+    const key = principalKey(principal);
+    if (entries.some((entry) => principalKey(entry.principal) === key)) return;
+    const first = allowed(principal)[0];
+    if (!first) return;
+    const id = `pending:${key}`;
+    setPending(id);
+    setEntries(entries.length, {
+      id,
+      principal,
+      permission: first.level,
+      scope: first.scope,
+      createdAt: new Date().toISOString(),
+      ...display,
+    });
+    try {
+      const entry = await props.grantAccess(principal, first.level, display, first.scope);
+      if (disposed) return;
+      const index = entries.findIndex((entry) => entry.id === id);
+      if (index !== -1) setEntries(index, reconcile({ ...entry }));
+      announce(t().accessGranted({ name: display.displayName }));
+    } catch (err) {
+      if (!disposed) setEntries((current) => current.filter((entry) => entry.id !== id));
+      // Prompts are global, so a grant that fails after its dialog closed still says so.
+      if (!(typeof err === "object" && err !== null && "name" in err && err.name === "AbortError")) {
+        prompts.error(err instanceof Error ? err.message : String(err));
+      }
+    } finally {
+      if (!disposed) setPending(null);
+    }
+  };
 
   type LevelChange = { accessId: string; permission: GrantableLevel; scope: string | undefined };
   const updateMut = mutation.create<LevelChange, LevelChange>({
@@ -239,11 +265,12 @@ export default function PermissionEditor(props: PermissionEditorProps) {
     },
     onError: (err) => prompts.error(err.message),
   });
-  const busy = () => grantMut.loading() || updateMut.loading() || revokeMut.loading();
+  const busy = () => grantPending() || updateMut.loading() || revokeMut.loading();
   // The service refuses to remove the last manager; the row says so up front.
   const lastManagerId = createMemo(() => {
     // A grant on part of the resource never manages it.
-    const managers = (props.effectiveEntries?.(entries) ?? entries).filter((entry) => !entry.scope && isManagerEntry(entry));
+    const granted = entries.filter((entry) => entry.id !== pending());
+    const managers = (props.effectiveEntries?.(granted) ?? granted).filter((entry) => !entry.scope && isManagerEntry(entry));
     return managers.length === 1 ? managers[0]!.id : null;
   });
 
@@ -260,6 +287,7 @@ export default function PermissionEditor(props: PermissionEditorProps) {
                 entry={entry}
                 coverage={coverage}
                 canEdit={canEdit()}
+                pending={entry.id === pending()}
                 disabled={busy()}
                 lastManager={entry.id === lastManagerId()}
                 allowed={allowed(entry.principal)}
@@ -288,11 +316,9 @@ export default function PermissionEditor(props: PermissionEditorProps) {
           allowPublic={allowPublic()}
           allowAuthenticated={allowAuthenticated()}
           allowServiceAccounts={props.allowServiceAccounts}
-          disabled={busy()}
-          onSelect={(principal, display) => {
-            const first = allowed(principal)[0];
-            if (first && !busy()) grantMut.mutate({ principal, permission: first.level, scope: first.scope, display });
-          }}
+          readOnly={grantPending()}
+          disabled={updateMut.loading() || revokeMut.loading()}
+          onSelect={(principal, display) => void grant(principal, display)}
         />
       </Show>
     </div>
@@ -307,6 +333,7 @@ function AccessEntryRow(props: {
   entry: AccessEntry;
   canEdit: boolean;
   disabled: boolean;
+  pending?: boolean;
   /** The only entry that manages the resource: it keeps its level and cannot be removed. */
   lastManager: boolean;
   allowed: ResolvedLevel[];
@@ -326,14 +353,14 @@ function AccessEntryRow(props: {
   const manageLabel = () => resolveEntryDisplay("admin", undefined, props.allowed, t()).label;
   const removeLabel = () => (props.lastManager ? t().lastManager({ level: manageLabel() }) : t().remove({ name: displayName() }));
   const isInteractive = () =>
-    props.canEdit && !props.disabled && !props.singlePicker && props.allowed.some((option) => option.key === entryKey());
+    props.canEdit && !props.disabled && !props.pending && !props.singlePicker && props.allowed.some((option) => option.key === entryKey());
 
   const badgeClass =
     "flex min-h-7 items-center gap-1 rounded-full border border-transparent bg-[var(--ui-surface-muted)] px-2.5 py-1 text-xs text-secondary";
 
   const badgeContent = (
     <>
-      <i class={`ti ${display().icon}`} />
+      <i class={props.pending ? "ti ti-loader-2 animate-spin" : `ti ${display().icon}`} />
       <span>{display().label}</span>
       <Show when={isInteractive()}>
         <i class="ti ti-chevron-down text-[10px]" />
@@ -343,7 +370,7 @@ function AccessEntryRow(props: {
 
   return (
     <div>
-      <div class="group/access-row flex items-center gap-2 py-1.5">
+      <div class="group/access-row flex items-center gap-2 py-1.5" aria-busy={props.pending ? "true" : undefined}>
         <Show
           when={props.entry.principal.type === "user"}
           fallback={
@@ -381,7 +408,9 @@ function AccessEntryRow(props: {
           >
             {(label) => <span class="truncate text-xs text-dimmed">({label()})</span>}
           </Show>
-          <Show when={props.coverage}>{(coverage) => <GroupCoverageToggle coverage={coverage()} groupName={displayName()} />}</Show>
+          <Show when={props.coverage}>
+            {(coverage) => <GroupCoverageToggle coverage={coverage()} groupName={displayName()} disabled={props.pending} />}
+          </Show>
         </div>
 
         {/* Permission badge — interactive single-value picker when editable,
@@ -422,7 +451,7 @@ function AccessEntryRow(props: {
               variant="ghost"
               size="xs"
               onClick={props.onRevoke}
-              disabled={props.disabled || props.lastManager}
+              disabled={props.disabled || props.pending || props.lastManager}
               aria-label={t().remove({ name: displayName() })}
               // A disabled button takes no focus and touch has no hover, so the reason also reaches assistive technology.
               aria-description={props.lastManager ? removeLabel() : undefined}

package/src/access/PrincipalPicker.tsx

@@ -33,6 +33,7 @@ export default function PrincipalPicker(props: {
   allowAuthenticated?: boolean;
   allowServiceAccounts?: boolean;
   disabled?: boolean;
+  readOnly?: boolean;
   /** `serviceAccountKind` is set for service accounts so a new row can show the same kind as the result. */
   onSelect: (principal: Principal, display: { displayName: string; serviceAccountKind?: ServiceAccountKind }) => void;
 }) {
@@ -100,6 +101,7 @@ export default function PrincipalPicker(props: {
   return (
     <Combobox
       disabled={props.disabled}
+      readOnly={props.readOnly}
       placeholder={
         props.allowAuthenticated !== false || props.allowPublic
           ? props.allowServiceAccounts

package/src/access/messages.ts

@@ -14,6 +14,7 @@ export const accessMessages = i18n.define({
       publicDescription: "Anyone with the link, including people who are not signed in",
       removeAccessConfirm: ({ name }: { name: string }) => `Remove access for ${name}?`,
       removeAccess: "Remove access",
+      accessGranted: ({ name }: { name: string }) => `Added ${name}`,
       userBoundServiceAccount: "User-bound service account",
       resourceBoundServiceAccount: "Resource-bound service account",
       standaloneServiceAccount: "Service account",
@@ -92,6 +93,7 @@ export const accessMessages = i18n.define({
       publicDescription: "Alle mit dem Link, auch ohne Anmeldung",
       removeAccessConfirm: ({ name }) => `Zugriff für ${name} entfernen?`,
       removeAccess: "Zugriff entfernen",
+      accessGranted: ({ name }) => `${name} hinzugefügt`,
       userBoundServiceAccount: "Benutzergebundenes Dienstkonto",
       resourceBoundServiceAccount: "Ressourcengebundenes Dienstkonto",
       standaloneServiceAccount: "Dienstkonto",

package/src/ai/capabilities.ts

@@ -425,6 +425,7 @@ const SCHEMA_KEYS = new Set([
   "required",
   "items",
   "prefixItems",
+  "additionalItems",
   "additionalProperties",
   "anyOf",
   "oneOf",
@@ -435,29 +436,139 @@ const SCHEMA_KEYS = new Set([
   "definitions",
 ]);
 
-const reduceSchemaValue = (value: unknown, key?: string): unknown => {
-  if (key === "const") return structuredClone(value);
+type SchemaReductionContext = {
+  root: Record<string, unknown>;
+  mirrorNames: Map<string, string>;
+  mirrors: Record<string, Record<string, unknown>>;
+};
+
+/** A local reference into the input schema: the root (`#`) or one of its `$defs` or `definitions`. */
+const localReference = (
+  reference: unknown,
+  root: Record<string, unknown>,
+): { identity: string; keyword: string; name: string; schema: unknown } | null => {
+  if (reference === "#") {
+    const { $defs: _defs, definitions: _definitions, ...schema } = root;
+    return { identity: "#", keyword: "$defs", name: "root", schema };
+  }
+  const match = typeof reference === "string" ? /^#\/(\$defs|definitions)\/([^/]+)$/.exec(reference) : null;
+  if (!match) return null;
+  const [, keyword, encodedName] = match;
+  const name = encodedName!.replace(/~1/g, "/").replace(/~0/g, "~");
+  const definitions = root[keyword!];
+  if (!definitions || typeof definitions !== "object" || !Object.hasOwn(definitions, name)) return null;
+  return { identity: `${keyword}/${name}`, keyword: keyword!, name, schema: Reflect.get(definitions, name) };
+};
+
+/** Whether a raw schema reaches a tuple; `visited` keeps each definition to one visit per question. */
+const containsTuple = (value: unknown, context: SchemaReductionContext, key?: string, visited = new Set<string>()): boolean => {
+  if (key === "const" || key === "enum" || key === "default" || key === "required" || key === "type") return false;
+  if (Array.isArray(value)) return value.some((item) => containsTuple(item, context, undefined, visited));
+  if (!value || typeof value !== "object") return false;
+  if (key === "properties" || key === "$defs" || key === "definitions") {
+    return Object.values(value).some((schema) => containsTuple(schema, context, undefined, visited));
+  }
+  if (Object.hasOwn(value, "prefixItems") || Array.isArray(Reflect.get(value, "items"))) return true;
+  const reference = localReference(Reflect.get(value, "$ref"), context.root);
+  if (reference && !visited.has(reference.identity)) {
+    visited.add(reference.identity);
+    if (containsTuple(reference.schema, context, undefined, visited)) return true;
+  }
+  return Object.entries(value).some(([childKey, childValue]) => containsTuple(childValue, context, childKey, visited));
+};
+
+const reduceSchemaValue = (value: unknown, context: SchemaReductionContext, key?: string, merged = false): unknown => {
+  if (key === "const" || key === "default") return structuredClone(value);
   if (Array.isArray(value)) {
     if (key === "required" || key === "enum" || key === "type") return structuredClone(value);
-    return value.map((item) => reduceSchemaValue(item));
+    return value.map((item) => reduceSchemaValue(item, context, undefined, merged));
   }
   if (!value || typeof value !== "object") return value;
+  if (key === "properties" || key === "$defs" || key === "definitions") {
+    return Object.fromEntries(Object.entries(value).map(([name, schema]) => [name, reduceSchemaValue(schema, context, undefined, merged)]));
+  }
 
   const output: Record<string, unknown> = {};
   for (const [childKey, childValue] of Object.entries(value)) {
-    if (key === "properties" || key === "$defs" || key === "definitions") {
-      output[childKey] = reduceSchemaValue(childValue);
-      continue;
+    if (!SCHEMA_KEYS.has(childKey) || (merged && childKey === "default")) continue;
+    // Tuple widening can make surrounding union branches overlap, so their defaults belong to the app.
+    const unionMerged =
+      merged ||
+      ((childKey === "anyOf" || childKey === "oneOf") &&
+        Array.isArray(childValue) &&
+        childValue.some((branch) => containsTuple(branch, context)));
+    output[childKey] = reduceSchemaValue(childValue, context, childKey, unionMerged);
+  }
+  if (output.oneOf !== undefined) {
+    if (output.anyOf === undefined) output.anyOf = output.oneOf;
+    else {
+      output.allOf = [...(Array.isArray(output.allOf) ? output.allOf : []), { anyOf: output.anyOf }, { anyOf: output.oneOf }];
+      delete output.anyOf;
     }
-    if (!SCHEMA_KEYS.has(childKey)) continue;
-    output[childKey] = reduceSchemaValue(childValue, childKey);
+    delete output.oneOf;
+  }
+
+  const positions = Array.isArray(output.prefixItems) ? output.prefixItems : Array.isArray(output.items) ? output.items : null;
+  if (positions) {
+    const rest = Array.isArray(output.prefixItems) ? output.items : output.additionalItems;
+    // Extra items of an open tuple may be anything, so the AI side must not narrow them to the positions.
+    const schemas = rest === undefined || rest === true ? [] : rest === false ? positions : [...positions, rest];
+    // Position-erased branches must leave defaults to the app's authoritative tuple schema.
+    const mergedSchemas = schemas.some((schema) => JSON.stringify(schema) !== JSON.stringify(schemas[0]))
+      ? schemas.map((schema) => reduceSchemaValue(schema, context, undefined, true))
+      : schemas;
+    const distinct = mergedSchemas.filter(
+      (schema, index) => mergedSchemas.findIndex((candidate) => JSON.stringify(candidate) === JSON.stringify(schema)) === index,
+    );
+    output.items = distinct.length === 0 ? {} : distinct.length === 1 ? distinct[0] : { anyOf: distinct };
+    if (rest === false)
+      output.maxItems = Math.min(typeof output.maxItems === "number" ? output.maxItems : positions.length, positions.length);
+  }
+  delete output.prefixItems;
+  delete output.additionalItems;
+  if (output.items === false) output.maxItems = 0;
+  // Zod drops array bounds without an item schema, so "any item" stays an empty schema.
+  if (typeof output.items === "boolean") output.items = {};
+  const reference = merged ? localReference(output.$ref, context.root) : null;
+  if (reference) {
+    const { identity, keyword, name } = reference;
+    const definitions = context.root[keyword];
+    const mirrors = context.mirrors[keyword] ?? {};
+    context.mirrors[keyword] = mirrors;
+    let mirrorName = context.mirrorNames.get(identity);
+    if (mirrorName === undefined) {
+      mirrorName = `${name}.ai`;
+      for (
+        let suffix = 1;
+        (definitions && typeof definitions === "object" && Object.hasOwn(definitions, mirrorName)) || Object.hasOwn(mirrors, mirrorName);
+        suffix++
+      ) {
+        mirrorName = `${name}.ai${suffix}`;
+      }
+      // Reserve the mirror before descending so recursive refs never reach default-bearing originals.
+      context.mirrorNames.set(identity, mirrorName);
+      mirrors[mirrorName] = {};
+      mirrors[mirrorName] = reduceSchemaValue(reference.schema, context, undefined, true);
+    }
+    output.$ref = `#/${keyword}/${mirrorName.replace(/~/g, "~0").replace(/\//g, "~1")}`;
   }
   return output;
 };
 
-/** Keep the provider-useful shape while leaving authoritative validation in the target app. */
-export const reduceAiCapabilityInputSchema = (schema: Record<string, unknown>): Record<string, unknown> =>
-  reduceSchemaValue(schema) as Record<string, unknown>;
+/**
+ * Keep the provider-useful shape while leaving authoritative validation in the target app.
+ * Tuples reach the model as bounded arrays of their item schemas and `oneOf` as `anyOf`, because loosened branches may
+ * overlap; the app still validates exact tuple positions and exclusive unions.
+ */
+export const reduceAiCapabilityInputSchema = (schema: Record<string, unknown>): Record<string, unknown> => {
+  const context: SchemaReductionContext = { root: schema, mirrorNames: new Map(), mirrors: {} };
+  const reduced = reduceSchemaValue(schema, context) as Record<string, unknown>;
+  for (const [keyword, mirrors] of Object.entries(context.mirrors)) {
+    const definitions = reduced[keyword];
+    reduced[keyword] = { ...(definitions && typeof definitions === "object" ? definitions : {}), ...mirrors };
+  }
+  return reduced;
+};
 
 export const aiCapabilityInputSchema = (schema: Record<string, unknown>): z.ZodType =>
   z.fromJSONSchema(reduceAiCapabilityInputSchema(schema));

package/src/ai/firecrawl-tools.ts

@@ -1,8 +1,8 @@
-import { isIP } from "node:net";
 import { type ToolContext, truncateMiddle } from "@k2b/nessi";
 import { z } from "zod";
 import type { RequestActor } from "../server";
 import { coreSettings } from "../services";
+import { isUnsafeNetworkAddress, isUnsafeNetworkHostname, parseNetworkAddress } from "../shared/network-address";
 import { AI_WEBSITE_APPROVAL_TOOL, aiTurnAllowsWebsiteApprovals, aiWebsiteApprovalScope, findRememberedAiToolApproval } from "./approvals";
 import { aiConversations } from "./store";
 import { defineAiTool } from "./tools";
@@ -141,31 +141,6 @@ const truncate = (text: string, maxChars: number): { text: string; truncated: bo
   return { text: text.slice(0, Math.max(0, maxChars)).trimEnd(), truncated: true };
 };
 
-const isPrivateIpv4 = (hostname: string): boolean => {
-  const parts = hostname.split(".").map((part) => Number(part));
-  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return true;
-  const [a, b] = parts as [number, number, number, number];
-  if (a === 0 || a === 10 || a === 127) return true;
-  if (a === 100 && b >= 64 && b <= 127) return true;
-  if (a === 169 && b === 254) return true;
-  if (a === 172 && b >= 16 && b <= 31) return true;
-  if (a === 192 && (b === 0 || b === 168)) return true;
-  if (a === 198 && (b === 18 || b === 19)) return true;
-  return a >= 224;
-};
-
-const isPrivateIpv6 = (hostname: string): boolean => {
-  const normalized = hostname.replace(/^\[|\]$/g, "").toLowerCase();
-  return (
-    normalized === "::" ||
-    normalized === "::1" ||
-    normalized.startsWith("fc") ||
-    normalized.startsWith("fd") ||
-    normalized.startsWith("fe80:") ||
-    normalized.startsWith("2001:db8:")
-  );
-};
-
 export const assertPublicHttpUrl = (rawUrl: string): string => {
   let parsed: URL;
   try {
@@ -176,13 +151,11 @@ export const assertPublicHttpUrl = (rawUrl: string): string => {
   if (parsed.protocol !== "https:" && parsed.protocol !== "http:") throw new Error("URL must use http or https.");
 
   const hostname = parsed.hostname.toLowerCase();
-  if (!hostname || hostname === "localhost" || hostname.endsWith(".localhost")) {
+  if (isUnsafeNetworkHostname(hostname)) {
     throw new Error("URL host is not allowed.");
   }
 
-  const ipKind = isIP(hostname.replace(/^\[|\]$/g, ""));
-  if (ipKind === 4 && isPrivateIpv4(hostname)) throw new Error("URL must not point to a private IP address.");
-  if (ipKind === 6 && isPrivateIpv6(hostname)) throw new Error("URL must not point to a private IP address.");
+  if (parseNetworkAddress(hostname) && isUnsafeNetworkAddress(hostname)) throw new Error("URL must not point to a private IP address.");
   return parsed.toString();
 };
 

package/src/browser/reload.ts

@@ -9,11 +9,26 @@ import { type ToastHandle, toast } from "@k2b/ui";
  */
 export const AUTOMATIC_RELOAD_WINDOW_MS = 30_000;
 
+let reloadPending = false;
+/** One notice at a time: every deferred reload has the same remedy. */
+let pageChanged: ToastHandle | undefined;
+
+/**
+ * An open modal dialog holds the reload. A modeless window, such as global search moved aside, leaves the page
+ * usable and may stay open for long, so it does not: the page would otherwise stay stale without notice.
+ */
+const modalOpen = () => document.querySelector('dialog[open]:not([aria-modal="false"])') !== null;
+
 const storageKey = (key: string) => `cloud.reload.${key}`;
 
 /**
  * Reloads the page for an automatic reason (a live event, a failed live
  * subscription, a changed view) at most once per `key` and window in this tab.
+ * While a modal dialog is open, it does not reload: once the last one closes,
+ * it shows a notice with a reload action. The person may have confirmed work
+ * in that dialog whose request a reload would cancel, so only they reload.
+ * The call returns `true` in both cases; a dialog that shows live data says
+ * itself that it is stale.
  *
  * Returns `false` without reloading when the same key already reloaded within
  * the window, or when `sessionStorage` is unavailable and a repeat therefore
@@ -22,6 +37,7 @@ const storageKey = (key: string) => `cloud.reload.${key}`;
  * need this guard.
  */
 export const reloadOnce = (key: string, options: { windowMs?: number } = {}): boolean => {
+  if (reloadPending) return true;
   const windowMs = options.windowMs ?? AUTOMATIC_RELOAD_WINDOW_MS;
   const now = Date.now();
   try {
@@ -32,7 +48,20 @@ export const reloadOnce = (key: string, options: { windowMs?: number } = {}): bo
   } catch {
     return false;
   }
-  window.location.reload();
+  if (typeof document === "undefined" || !modalOpen()) {
+    window.location.reload();
+    return true;
+  }
+  reloadPending = true;
+  const observer = new MutationObserver(() => {
+    if (modalOpen()) return;
+    observer.disconnect();
+    reloadPending = false;
+    const t = reloadMessages.resolve([document.documentElement.lang || "en"]).t;
+    pageChanged?.dismiss();
+    pageChanged = toast(t.pageChanged, { duration: 0, action: { label: t.reload, onClick: () => window.location.reload() } });
+  });
+  observer.observe(document.documentElement, { subtree: true, childList: true, attributes: true, attributeFilter: ["open", "aria-modal"] });
   return true;
 };
 
@@ -41,10 +70,12 @@ const reloadMessages = i18n.define({
   messages: {
     en: {
       codeUnavailable: "Part of this page could not load. Reload the page and try again.",
+      pageChanged: "This page changed. Reload it to see the latest version.",
       reload: "Reload",
     },
     de: {
       codeUnavailable: "Ein Teil dieser Seite konnte nicht geladen werden. Lade die Seite neu und versuche es erneut.",
+      pageChanged: "Diese Seite hat sich geändert. Lade sie neu, um den aktuellen Stand zu sehen.",
       reload: "Neu laden",
     },
   },

package/src/services/index.ts

@@ -218,3 +218,11 @@ export type {
   MailPage,
   MailServiceError,
 } from "../contracts/outgoing-mail";
+
+export {
+  NetworkTargetBlockedError,
+  pinnedNetworkLookup,
+  resolvePublicNetworkAddresses,
+  resolveAllowedNetworkAddresses,
+} from "./network-security";
+export type { NetworkLookup, PublicNetworkAddress } from "./network-security";

package/src/services/network-security.ts

@@ -1,5 +1,14 @@
 import { lookup as dnsLookup } from "node:dns/promises";
-import { isUnsafeNetworkAddress, isUnsafeNetworkHostname, networkAddressFamily, normalizeNetworkHostname } from "../shared/network-address";
+import type { LookupFunction } from "node:net";
+import {
+  EMPTY_NETWORK_ALLOWLIST,
+  isAllowlistedNetworkAddress,
+  isUnsafeNetworkAddress,
+  isUnsafeNetworkHostname,
+  type NetworkAllowlist,
+  normalizeNetworkHostname,
+  parseNetworkAddress,
+} from "../shared/network-address";
 
 export type PublicNetworkAddress = { address: string; family: 4 | 6 };
 export type NetworkLookup = (
@@ -7,25 +16,56 @@ export type NetworkLookup = (
   options: { all: true; verbatim: true },
 ) => Promise<Array<{ address: string; family: number }>>;
 
-export const resolvePublicNetworkAddresses = async (
+export class NetworkTargetBlockedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "NetworkTargetBlockedError";
+  }
+}
+
+export const resolveAllowedNetworkAddresses = async (
   rawHostname: string,
+  allowlist: NetworkAllowlist,
   lookup: NetworkLookup = (hostname) => dnsLookup(hostname, { all: true, verbatim: true }),
 ): Promise<PublicNetworkAddress[]> => {
   const hostname = normalizeNetworkHostname(rawHostname);
-  if (!hostname || isUnsafeNetworkHostname(hostname)) throw new Error("Network target host is not allowed");
+  const trustedHost = allowlist.hosts.has(hostname);
+  if (!trustedHost && isUnsafeNetworkHostname(rawHostname)) throw new NetworkTargetBlockedError("Network target host is not allowed");
 
-  const literalFamily = networkAddressFamily(hostname);
-  const addresses = literalFamily ? [{ address: hostname, family: literalFamily }] : await lookup(hostname, { all: true, verbatim: true });
+  const literal = parseNetworkAddress(rawHostname);
+  const addresses = literal ? [literal] : await lookup(hostname, { all: true, verbatim: true });
   if (addresses.length === 0) throw new Error("Network target could not be resolved");
 
   const normalized: PublicNetworkAddress[] = addresses.map((entry) => {
-    const address = normalizeNetworkHostname(entry.address);
-    if (entry.family !== 4 && entry.family !== 6) throw new Error("Network target returned an unsupported address family");
-    if (networkAddressFamily(address) !== entry.family) throw new Error("Network target returned an invalid address");
-    return { address, family: entry.family };
+    const literal = parseNetworkAddress(entry.address);
+    if (entry.family !== 4 && entry.family !== 6)
+      throw new NetworkTargetBlockedError("Network target returned an unsupported address family");
+    if (!literal || literal.family !== entry.family) throw new NetworkTargetBlockedError("Network target returned an invalid address");
+    return literal;
   });
-  if (normalized.some((entry) => isUnsafeNetworkAddress(entry.address))) {
-    throw new Error("Network target resolved to a private or reserved address");
+  if (
+    !trustedHost &&
+    normalized.some((entry) => isUnsafeNetworkAddress(entry.address) && !isAllowlistedNetworkAddress(allowlist, entry.address))
+  ) {
+    throw new NetworkTargetBlockedError("Network target resolved to a private or reserved address");
   }
   return normalized;
 };
+
+export const resolvePublicNetworkAddresses = (rawHostname: string, lookup?: NetworkLookup): Promise<PublicNetworkAddress[]> =>
+  resolveAllowedNetworkAddresses(rawHostname, EMPTY_NETWORK_ALLOWLIST, lookup);
+
+/** Socket lookup using only addresses already checked by the public resolver. */
+export const pinnedNetworkLookup =
+  (addresses: readonly PublicNetworkAddress[]): LookupFunction =>
+  (_hostname, options, callback) => {
+    const family = options.family === 4 || options.family === 6 ? options.family : 0;
+    const candidates = family ? addresses.filter((entry) => entry.family === family) : [...addresses];
+    const selected = candidates[0];
+    if (!selected) {
+      callback(Object.assign(new Error("No validated address for requested IP family"), { code: "ENOTFOUND" }), "", family || undefined);
+      return;
+    }
+    if (options.all) callback(null, candidates);
+    else callback(null, selected.address, selected.family);
+  };

package/src/shared/network-address.ts

@@ -32,22 +32,12 @@ const UNSAFE_IPV4_RANGES: ReadonlyArray<readonly [string, number]> = [
   ["240.0.0.0", 4],
 ];
 
-const ipv6ToBigInt = (rawAddress: string): bigint | null => {
-  let address = rawAddress.toLowerCase().split("%")[0] ?? "";
-  if (address.includes(".")) {
-    const separator = address.lastIndexOf(":");
-    const ipv4 = ipv4ToNumber(address.slice(separator + 1));
-    if (separator < 0 || ipv4 === null) return null;
-    address = `${address.slice(0, separator)}:${(ipv4 >>> 16).toString(16)}:${(ipv4 & 0xffff).toString(16)}`;
-  }
+// Only canonical IPv6 from the WHATWG parser reaches this conversion.
+const ipv6ToBigInt = (address: string): bigint => {
   const halves = address.split("::");
-  if (halves.length > 2) return null;
   const left = halves[0] ? halves[0].split(":") : [];
   const right = halves[1] ? halves[1].split(":") : [];
-  const missing = halves.length === 2 ? 8 - left.length - right.length : 0;
-  if (missing < 0 || (halves.length === 1 && left.length !== 8)) return null;
-  const groups = [...left, ...Array.from({ length: missing }, () => "0"), ...right];
-  if (groups.length !== 8 || groups.some((group) => !/^[0-9a-f]{1,4}$/.test(group))) return null;
+  const groups = [...left, ...Array.from({ length: 8 - left.length - right.length }, () => "0"), ...right];
   return groups.reduce((value, group) => (value << 16n) | BigInt(`0x${group}`), 0n);
 };
 
@@ -57,51 +47,133 @@ const ipv6InRange = (address: bigint, base: bigint, bits: number): boolean => {
 };
 
 const UNSAFE_IPV6_RANGES: ReadonlyArray<readonly [bigint, number]> = [
-  [ipv6ToBigInt("::")!, 96],
-  [ipv6ToBigInt("64:ff9b::")!, 96],
-  [ipv6ToBigInt("64:ff9b:1::")!, 48],
-  [ipv6ToBigInt("100::")!, 64],
-  [ipv6ToBigInt("2001::")!, 32],
-  [ipv6ToBigInt("2001:2::")!, 48],
-  [ipv6ToBigInt("2001:db8::")!, 32],
-  [ipv6ToBigInt("2002::")!, 16],
-  [ipv6ToBigInt("3fff::")!, 20],
-  [ipv6ToBigInt("fc00::")!, 7],
-  [ipv6ToBigInt("fe80::")!, 10],
-  [ipv6ToBigInt("fec0::")!, 10],
-  [ipv6ToBigInt("ff00::")!, 8],
+  [ipv6ToBigInt("2001::"), 23],
+  [ipv6ToBigInt("2001:db8::"), 32],
+  [ipv6ToBigInt("2002::"), 16],
+  [ipv6ToBigInt("3fff::"), 20],
 ];
 
-export const normalizeNetworkHostname = (hostname: string): string =>
-  hostname
-    .toLowerCase()
-    .replace(/^\[|\]$/g, "")
-    .replace(/\.$/, "");
+export const normalizeNetworkHostname = (hostname: string): string => {
+  const lower = hostname.toLowerCase();
+  if (lower.startsWith("[") && lower.endsWith("]") && lower.includes(":")) return lower.slice(1, -1);
+  return lower.includes(":") ? lower : lower.replace(/\.$/, "");
+};
+
+// WHATWG's "ends in a number" rule: these hosts must parse as IPv4,
+// rather than falling back to DNS (including invalid octal and overflow).
+const endsInNumber = (hostname: string): boolean => {
+  const last = hostname.split(".").at(-1) ?? "";
+  return /^\d+$/.test(last) || /^0x[0-9a-f]*$/i.test(last);
+};
 
-export const networkAddressFamily = (rawAddress: string): 4 | 6 | null => {
+/** Parse all URL IP literal forms without DNS or server-only dependencies. */
+export const parseNetworkAddress = (rawAddress: string): { address: string; family: 4 | 6 } | null => {
   const address = normalizeNetworkHostname(rawAddress);
-  if (ipv4ToNumber(address) !== null) return 4;
-  return ipv6ToBigInt(address) !== null ? 6 : null;
+  const ipv6 = address.includes(":");
+  if (!address || /[\s/@\\?#%\[\]]/.test(address) || (!ipv6 && !endsInNumber(address))) return null;
+  try {
+    // URL implements legacy IPv4 (decimal, octal, hex and shortened forms),
+    // as well as IPv6 compression and dotted tails. Reject zone IDs above.
+    const parsed = new URL(`http://${ipv6 ? `[${address}]` : address}/`).hostname;
+    if (ipv6) return { address: normalizeNetworkHostname(parsed), family: 6 };
+    return ipv4ToNumber(parsed) !== null ? { address: parsed, family: 4 } : null;
+  } catch {
+    return null;
+  }
 };
 
+export const networkAddressFamily = (rawAddress: string): 4 | 6 | null => parseNetworkAddress(rawAddress)?.family ?? null;
+
 export const isUnsafeNetworkAddress = (rawAddress: string): boolean => {
-  const address = normalizeNetworkHostname(rawAddress);
-  const family = networkAddressFamily(address);
-  if (family === 4) return UNSAFE_IPV4_RANGES.some(([base, bits]) => ipv4InRange(address, base, bits));
-  if (family !== 6) return true;
-  const value = ipv6ToBigInt(address);
-  if (value === null) return true;
-  if (value >> 32n === 0xffffn) {
+  const literal = parseNetworkAddress(rawAddress);
+  if (!literal) return true;
+  if (literal.family === 4) return UNSAFE_IPV4_RANGES.some(([base, bits]) => ipv4InRange(literal.address, base, bits));
+  const value = ipv6ToBigInt(literal.address);
+  if (value >> 32n === 0xffffn || ipv6InRange(value, ipv6ToBigInt("64:ff9b::"), 96)) {
     const mapped = Number(value & 0xffffffffn);
-    const ipv4 = [mapped >>> 24, (mapped >>> 16) & 255, (mapped >>> 8) & 255, mapped & 255].join(".");
-    return isUnsafeNetworkAddress(ipv4);
+    return isUnsafeNetworkAddress([mapped >>> 24, (mapped >>> 16) & 255, (mapped >>> 8) & 255, mapped & 255].join("."));
   }
-  return UNSAFE_IPV6_RANGES.some(([base, bits]) => ipv6InRange(value, base, bits));
+  return !ipv6InRange(value, ipv6ToBigInt("2000::"), 3) || UNSAFE_IPV6_RANGES.some(([base, bits]) => ipv6InRange(value, base, bits));
 };
 
 export const isUnsafeNetworkHostname = (rawHostname: string): boolean => {
   const hostname = normalizeNetworkHostname(rawHostname);
   return (
-    hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "metadata.google.internal" || hostname.endsWith(".internal")
+    !hostname ||
+    ["localhost", "localhost.localdomain", "metadata", "metadata.google.internal", "instance-data"].includes(hostname) ||
+    [".localhost", ".internal", ".local", ".home.arpa"].some((suffix) => hostname.endsWith(suffix)) ||
+    /[%\[\]]/.test(hostname) ||
+    ((endsInNumber(hostname) || hostname.includes(":")) && !parseNetworkAddress(hostname))
   );
 };
+
+/** Operator-owned exact DNS names and canonical IP networks. Never populate from person input. */
+export type NetworkAllowlist = {
+  readonly hosts: ReadonlySet<string>;
+  readonly networks: ReadonlyArray<Readonly<{ address: string; family: 4 | 6; bits: number }>>;
+};
+
+export const EMPTY_NETWORK_ALLOWLIST: NetworkAllowlist = { hosts: new Set(), networks: [] };
+
+export const parseNetworkAllowlist = (entries: readonly string[]): NetworkAllowlist => {
+  const hosts = new Set<string>();
+  const networks: Array<{ address: string; family: 4 | 6; bits: number }> = [];
+  for (const entry of entries) {
+    const invalid = (reason = "expected an exact host name, IP address or CIDR") =>
+      new Error(`Invalid network allowlist entry "${entry}": ${reason}`);
+    const parts = entry.split("/");
+    const raw = parts[0] ?? "";
+    const literal = parseNetworkAddress(raw);
+    if (literal) {
+      // Allowlist entries use strict IP notation, even though URL destinations may use legacy IPv4.
+      if (literal.family === 4 && ipv4ToNumber(raw) === null) throw invalid();
+      if (literal.family === 6 && raw.includes(".") && ipv4ToNumber(raw.replace(/\]$/, "").split(":").at(-1) ?? "") === null)
+        throw invalid();
+      const width = literal.family === 4 ? 32 : 128;
+      if (parts.length > 2 || (parts.length === 2 && !/^(0|[1-9]\d*)$/.test(parts[1] ?? ""))) throw invalid();
+      const bits = parts.length === 2 ? Number(parts[1]) : width;
+      if (bits > width) throw invalid();
+      if (bits === 0) throw invalid("a /0 network allows every address; list the internal hosts or ranges instead");
+      const value = literal.family === 4 ? BigInt(ipv4ToNumber(literal.address)!) : ipv6ToBigInt(literal.address);
+      const shift = BigInt(width - bits);
+      const base = (value >> shift) << shift;
+      if (base !== value) {
+        const address =
+          literal.family === 4
+            ? [24n, 16n, 8n, 0n].map((shift) => Number((base >> shift) & 255n)).join(".")
+            : parseNetworkAddress(
+                Array.from({ length: 8 }, (_, index) => ((base >> BigInt((7 - index) * 16)) & 65535n).toString(16)).join(":"),
+              )!.address;
+        throw invalid(`host bits are set; use ${address}/${bits}`);
+      }
+      networks.push({ ...literal, bits });
+      continue;
+    }
+    const hostname = normalizeNetworkHostname(raw);
+    if (
+      parts.length !== 1 ||
+      endsInNumber(hostname) ||
+      raw.includes(":") ||
+      hostname.length > 253 ||
+      !hostname.split(".").every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label))
+    )
+      throw invalid();
+    hosts.add(hostname);
+  }
+  return { hosts, networks };
+};
+
+export const isAllowlistedNetworkAddress = (allowlist: NetworkAllowlist, rawAddress: string): boolean => {
+  const literal = parseNetworkAddress(rawAddress);
+  if (!literal) return false;
+  if (literal.family === 6) {
+    const value = ipv6ToBigInt(literal.address);
+    // Only IPv4-mapped IPv6 reaches the embedded IPv4 host directly.
+    if (value >> 32n === 0xffffn) {
+      const ipv4 = [24n, 16n, 8n, 0n].map((shift) => Number((value >> shift) & 255n)).join(".");
+      if (isAllowlistedNetworkAddress(allowlist, ipv4)) return true;
+    }
+    return allowlist.networks.some((network) => network.family === 6 && ipv6InRange(value, ipv6ToBigInt(network.address), network.bits));
+  }
+  return allowlist.networks.some((network) => network.family === 4 && ipv4InRange(literal.address, network.address, network.bits));
+};

package/src/ssr/LayoutHelp.tsx

@@ -8,6 +8,7 @@ import {
   MarkdownView,
   NoticeCard,
   Placeholder,
+  prefersReducedMotion,
   prompts,
   ScrollArea,
   TextInput,
@@ -186,7 +187,7 @@ const HelpShell = (props: {
     ).find((element) => element.id === hash);
     if (!heading) return false;
     setActiveSectionId(hash);
-    heading.scrollIntoView({ block: "start", behavior: window.matchMedia("(prefers-reduced-motion: reduce)").matches ? "auto" : "smooth" });
+    heading.scrollIntoView({ block: "start", behavior: prefersReducedMotion() ? "auto" : "smooth" });
     return true;
   };
 

package/src/styles/global.css

@@ -255,8 +255,26 @@ html:has(.k2b-mobile-shell) body {
   --color-selection-fg: rgb(239 246 255);
 }
 
-@view-transition {
-  navigation: auto;
+/* @k2b/ui makes motion inside .k2b-ui instant under reduced motion; the
+   page owns its view transitions, so the same two sources stop them here. */
+@media (prefers-reduced-motion: no-preference) {
+  @view-transition {
+    navigation: auto;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-group(*),
+  ::view-transition-old(*),
+  ::view-transition-new(*) {
+    animation: none !important;
+  }
+}
+
+html[data-k2b-motion="reduced"]::view-transition-group(*),
+html[data-k2b-motion="reduced"]::view-transition-old(*),
+html[data-k2b-motion="reduced"]::view-transition-new(*) {
+  animation: none !important;
 }
 
 ::selection {
@@ -275,15 +293,6 @@ solid-island {
   display: contents;
 }
 
-@media (prefers-reduced-motion: reduce) {
-  *,
-  *::before,
-  *::after {
-    scroll-behavior: auto !important;
-    transition-duration: 0.01ms !important;
-  }
-}
-
 /* Cloud has three shell modes. Phones, below md, get the header and no rail.
    From md, signed-in people get the rail instead of the header: up to 2xl the
    app area meets the window's top, right and bottom edges, and from 2xl it is