@k2b/cloud 0.36.0 → 0.38.0

package/src/services/help/types.ts

@@ -1,6 +1,6 @@
 import type { AppRegistryHelpSummary } from "../../contracts/registry";
 import type { RequestActor } from "../../contracts/shared";
-import type { HelpDocumentManifest } from "../../shared/help";
+import type { HelpAccessLevel, HelpArticleLink, HelpDocumentManifest, HelpKind } from "../../shared/help";
 
 export type HelpDocument = {
   id: string;
@@ -8,6 +8,10 @@ export type HelpDocument = {
   icon?: string;
   description?: string;
   order: number;
+  kind: HelpKind;
+  needs?: HelpAccessLevel;
+  next?: string;
+  related: readonly string[];
   markdown: string;
   searchText: string;
 };
@@ -30,8 +34,12 @@ export type HelpMetadata = {
   description?: string;
   icon?: string;
   order: number;
+  kind: HelpKind;
+  needs?: HelpAccessLevel;
+  next?: string;
+  related: readonly string[];
 };
-export type HelpArticle = HelpMetadata & { markdown: string };
+export type HelpArticle = HelpMetadata & { markdown: string; links: Readonly<Record<string, HelpArticleLink>> };
 export type HelpMatch = Pick<HelpMetadata, "appId" | "appName" | "locale" | "documentId" | "title" | "description"> & { kind: "help" };
 export type HelpSearchInput = { query: string; appId?: string; limit?: number };
 export type HelpReadInput = { appId: string; documentId: string };

package/src/services/index.ts

@@ -8,6 +8,7 @@ export { accountIdentities, AccountIdentityError } from "./accounts/identities";
 export type { AccountIdentityUser, AccountIdentityGroup, AccountIdentityPage, AccountIdentityAvailability } from "./accounts/identities";
 export type { AccountIdentityReconciliation } from "./accounts/identity-reconciliation";
 export { providers } from "./providers";
+export { createAllowedNetworkFetch } from "./allowed-network-fetch";
 export { requestPublicHttps, type PublicHttpInput } from "./public-http";
 export { authFlows } from "./auth-flows";
 export { toPgIntArray, toPgTextArray, toPgUuidArray, escapeLikePattern, isUniqueViolation } from "./postgres";
@@ -221,6 +222,7 @@ export type {
 
 export {
   NetworkTargetBlockedError,
+  isNetworkTargetBlocked,
   pinnedNetworkLookup,
   resolvePublicNetworkAddresses,
   resolveAllowedNetworkAddresses,

package/src/services/network-security.ts

@@ -52,6 +52,34 @@ export const resolveAllowedNetworkAddresses = async (
   return normalized;
 };
 
+/** Save-time hint only: every request must still resolve, validate and pin its target. */
+export const isNetworkTargetBlocked = async (
+  hostname: string,
+  allowlist: NetworkAllowlist,
+  {
+    resolve = resolveAllowedNetworkAddresses,
+    timeoutMs = 5000,
+  }: {
+    resolve?: typeof resolveAllowedNetworkAddresses;
+    timeoutMs?: number;
+  } = {},
+): Promise<boolean> => {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    await Promise.race([
+      resolve(hostname, allowlist),
+      new Promise<void>((resolve) => {
+        timer = setTimeout(resolve, timeoutMs);
+      }),
+    ]);
+    return false;
+  } catch (error) {
+    return error instanceof NetworkTargetBlockedError;
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
 export const resolvePublicNetworkAddresses = (rawHostname: string, lookup?: NetworkLookup): Promise<PublicNetworkAddress[]> =>
   resolveAllowedNetworkAddresses(rawHostname, EMPTY_NETWORK_ALLOWLIST, lookup);
 

package/src/services/outgoing-mail/dispatcher.ts

@@ -12,7 +12,7 @@ import { allowedMailProfile, type MessageRow, messageAttachmentRefs, messageReco
 import { OutgoingMailError, resolveMailCredentials } from "./store";
 import { mailAttachments, mailSettled } from "./sync";
 import { smtpFailureMessage } from "./test-send";
-import { buildMailTransport } from "./transport";
+import { resolveMailTransport } from "./transport";
 
 export const cleanupMailAttachments = async (id: string): Promise<void> => {
   const row = await outgoingMailMessages.read(id);
@@ -136,7 +136,12 @@ export const attemptOutgoingMail = async (row: MessageRow, signal?: AbortSignal)
       socket.once("connect", () => {
         if (attempt.signal.aborted) socket.destroy();
       });
-      const transport = buildMailTransport(credentials, socket);
+      const resolved = await resolveMailTransport(credentials, attempt.signal).catch((error: unknown) => {
+        socket.destroy();
+        throw error;
+      });
+      // Nodemailer cannot fall back across IP literals; each queued retry rotates to the next checked address.
+      const transport = resolved.build(Math.max(0, row.attempt_count - 1), socket);
       const stop = () => {
         socket.destroy();
         transport.close();

package/src/services/outgoing-mail/resolve-host.ts

@@ -0,0 +1,39 @@
+import { env } from "../../config/env";
+import { networkAddressFamily, normalizeNetworkHostname, parseNetworkAllowlistEnv } from "../../shared/network-address";
+import { NetworkTargetBlockedError, resolveAllowedNetworkAddresses } from "../network-security";
+
+export const outgoingMailAllowlist = () => parseNetworkAllowlistEnv("OUTGOING_MAIL_ALLOWED_TARGETS", env.OUTGOING_MAIL_ALLOWED_TARGETS);
+
+/** One bounded lookup shared by SMTP and bounce IMAP; clients use only the checked addresses. */
+export const resolveMailHost = async (host: string, signal?: AbortSignal, resolve = resolveAllowedNetworkAddresses) => {
+  const hostname = normalizeNetworkHostname(host);
+  const deadline = new AbortController();
+  const timer = setTimeout(() => deadline.abort(new Error("Outgoing mail DNS lookup timed out.")), 5000);
+  const cancellation = signal ? AbortSignal.any([signal, deadline.signal]) : deadline.signal;
+  let abort: (() => void) | undefined;
+  try {
+    cancellation.throwIfAborted();
+    const addresses = await Promise.race([
+      resolve(hostname, outgoingMailAllowlist()),
+      new Promise<never>((_, reject) => {
+        abort = () => reject(cancellation.reason);
+        cancellation.addEventListener("abort", abort, { once: true });
+        if (cancellation.aborted) abort();
+      }),
+    ]);
+    return {
+      host: hostname,
+      addresses: [...addresses.filter((entry) => entry.family === 4), ...addresses.filter((entry) => entry.family === 6)],
+      servername: networkAddressFamily(hostname) ? undefined : hostname,
+    };
+  } catch (error) {
+    if (error instanceof NetworkTargetBlockedError)
+      throw new NetworkTargetBlockedError(
+        "Outgoing mail target is on an internal network. An operator can allow it with OUTGOING_MAIL_ALLOWED_TARGETS.",
+      );
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    if (abort) cancellation.removeEventListener("abort", abort);
+  }
+};

package/src/services/outgoing-mail/test-send.ts

@@ -1,7 +1,7 @@
 import { audit } from "../audit";
 import { get } from "../settings";
 import { type MailAuditContext, OutgoingMailError, resolveMailCredentials } from "./store";
-import { buildMailTransport } from "./transport";
+import { resolveMailTransport } from "./transport";
 
 export const smtpFailureMessage = (error: unknown, secrets: readonly (string | null)[]): string => {
   let message = error instanceof Error ? error.message : "SMTP delivery failed.";
@@ -17,8 +17,23 @@ export const outgoingMailTest = {
     const event = { ...context, action: "outgoing_mail.profile.test", target: { type: "outgoing_mail_profile", id: key } };
     // Fail before the external effect if audit storage is unavailable.
     await audit.record({ ...event, outcome: "allowed" });
-    const transport = buildMailTransport(profile);
+    let transport: ReturnType<Awaited<ReturnType<typeof resolveMailTransport>>["build"]> | undefined;
     try {
+      const resolved = await resolveMailTransport(profile);
+      for (let index = 0; index < resolved.count; index++) {
+        transport = resolved.build(index);
+        try {
+          // CONN also labels socket errors after DATA. Only fall back during a
+          // preflight that cannot send a message, then send once to that address.
+          await transport.verify();
+          break;
+        } catch (error) {
+          transport.close();
+          transport = undefined;
+          if (!(error instanceof Error) || !("command" in error) || error.command !== "CONN" || index === resolved.count - 1) throw error;
+        }
+      }
+      if (!transport) throw new Error("No validated SMTP address.");
       await transport.sendMail({
         from: { address: profile.fromAddress, name: profile.fromName ?? (await get<string>("app.name")) },
         to: recipient,
@@ -34,7 +49,7 @@ export const outgoingMailTest = {
       await audit.recordResultAfterSideEffect({ ...event, result: { ok: false, error: { code: "smtp_failed", message, status: 500 } } });
       throw new OutgoingMailError("smtp_failed", message, 502);
     } finally {
-      transport.close();
+      transport?.close();
     }
   },
 };

package/src/services/outgoing-mail/transport.ts

@@ -1,17 +1,28 @@
 import type { Socket } from "node:net";
 import { createTransport } from "nodemailer";
+import { resolveMailHost } from "./resolve-host";
 import type { resolveMailCredentials } from "./store";
 
-export const buildMailTransport = (profile: Awaited<ReturnType<typeof resolveMailCredentials>>, socket?: Socket) =>
-  createTransport({
-    // Workers own the raw socket so timeout/shutdown can destroy it. Nodemailer
-    // still owns SMTP and upgrades this socket for implicit TLS or STARTTLS.
-    ...(socket ? { socket } : {}),
-    host: profile.smtpHost,
-    port: profile.smtpPort,
-    secure: profile.smtpSecure,
-    ...(profile.smtpUser ? { auth: { user: profile.smtpUser, pass: profile.smtpPassword ?? "" } } : {}),
-    connectionTimeout: 10000,
-    greetingTimeout: 10000,
-    socketTimeout: 60000,
-  });
+export const resolveMailTransport = async (profile: Awaited<ReturnType<typeof resolveMailCredentials>>, signal?: AbortSignal) => {
+  const target = await resolveMailHost(profile.smtpHost, signal);
+  signal?.throwIfAborted();
+  const count = target.addresses.length;
+  return {
+    count,
+    build: (index: number, socket?: Socket) =>
+      createTransport({
+        // Workers own the raw socket so timeout/shutdown can destroy it. Nodemailer
+        // still owns SMTP and upgrades this socket for implicit TLS or STARTTLS.
+        ...(socket ? { socket } : {}),
+        host: target.addresses[Math.max(0, index) % count]!.address,
+        servername: target.servername,
+        tls: { servername: target.servername },
+        port: profile.smtpPort,
+        secure: profile.smtpSecure,
+        ...(profile.smtpUser ? { auth: { user: profile.smtpUser, pass: profile.smtpPassword ?? "" } } : {}),
+        connectionTimeout: 10000,
+        greetingTimeout: 10000,
+        socketTimeout: 60000,
+      }),
+  };
+};

package/src/services/settings/index.ts

@@ -6,7 +6,8 @@
  * Custom DB values are encrypted at rest using APP_SECRET. All read/write
  * goes through the Redis cache-aside layer in `./store.ts` (5-minute TTL).
  * `loadCache()` runs once at boot to normalize legacy rows and bootstrap
- * env-backed entries into Postgres.
+ * env-backed entries into Postgres. Startup never replaces an existing row;
+ * env bootstrap only fills missing keys.
  */
 
 import { redis, sql } from "bun";
@@ -17,11 +18,12 @@ import { bulkRead, deleteKey, readKey, writeKey } from "./store";
 type SqlClient = typeof sql;
 
 type StoredRow = { key: string; value: string };
-type PendingRow = { key: string; value: unknown; rewrite: boolean; existed: boolean };
+type PendingRow = { value: unknown; originalCiphertext: string };
 type NormalizationStats = {
   encryptedLoaded: number;
   normalizedUpdated: number;
   envBootstrapped: number;
+  undecryptable: number;
   invalidSkipped: number;
 };
 
@@ -58,23 +60,18 @@ const shouldBootstrapValue = (def: SettingDef, value: unknown): boolean => {
   }
 };
 
-const upsertEncryptedRow = async (key: string, value: unknown): Promise<void> => {
-  const encryptedValue = await encryptValue(value);
-  await sql`
-    INSERT INTO settings.entries (key, value, updated_at)
-    VALUES (${key}, ${encryptedValue}, now())
-    ON CONFLICT (key)
-    DO UPDATE SET value = ${encryptedValue}, updated_at = now()
-  `;
-  await redis.del(REDIS_KEY(key));
-};
-
-const normalizeStoredEntries = async (): Promise<{ rows: Array<{ key: string; value: unknown }>; stats: NormalizationStats }> => {
+const normalizeStoredEntries = async (): Promise<{
+  rows: Array<{ key: string; value: unknown }>;
+  storedKeys: Set<string>;
+  stats: NormalizationStats;
+}> => {
   const rows = await sql<StoredRow[]>`SELECT key, value FROM settings.entries`;
+  const storedKeys = new Set(rows.map((row) => row.key));
   const stats: NormalizationStats = {
     encryptedLoaded: 0,
     normalizedUpdated: 0,
     envBootstrapped: 0,
+    undecryptable: 0,
     invalidSkipped: 0,
   };
   const pendingRows = new Map<string, PendingRow>();
@@ -82,11 +79,17 @@ const normalizeStoredEntries = async (): Promise<{ rows: Array<{ key: string; va
   for (const row of rows) {
     try {
       const value = await decryptValue(row.value);
-      pendingRows.set(row.key, { key: row.key, value, rewrite: false, existed: true });
+      pendingRows.set(row.key, { value, originalCiphertext: row.value });
       stats.encryptedLoaded += 1;
     } catch {
-      console.warn(`[settings] skipping invalid stored value for "${row.key}"`);
-      stats.invalidSkipped += 1;
+      // An unreadable value is not a missing value (#1295). Usually this
+      // process runs with another APP_SECRET than the writer; applications
+      // with the right key still read this row. Keep its key in `storedKeys`
+      // so env bootstrap never replaces it, and never log the value.
+      console.warn(
+        `[settings] cannot decrypt stored value for "${row.key}" with this APP_SECRET; keeping the row unchanged, reads use the environment fallback or default`,
+      );
+      stats.undecryptable += 1;
     }
   }
 
@@ -109,28 +112,47 @@ const normalizeStoredEntries = async (): Promise<{ rows: Array<{ key: string; va
 
     normalized.push({ key, value: validated.value });
 
-    if (row.rewrite || !row.existed || !isEqual(row.value, validated.value)) {
-      await upsertEncryptedRow(key, validated.value);
-      stats.normalizedUpdated += 1;
+    if (!isEqual(row.value, validated.value)) {
+      const encryptedValue = await encryptValue(validated.value);
+      const updated = await sql<{ key: string }[]>`
+        UPDATE settings.entries SET value = ${encryptedValue}, updated_at = now()
+        WHERE key = ${key} AND value = ${row.originalCiphertext}
+        RETURNING key
+      `;
+      if (updated.length > 0) {
+        await redis.del(REDIS_KEY(key));
+        stats.normalizedUpdated += 1;
+      }
     }
   }
 
-  return { rows: normalized, stats };
+  return { rows: normalized, storedKeys, stats };
 };
 
 const bootstrapEnvBackedEntries = async (config: {
   rows: Array<{ key: string; value: unknown }>;
+  storedKeys: Set<string>;
   stats: NormalizationStats;
 }): Promise<Array<{ key: string; value: unknown }>> => {
   const rowsByKey = new Map(config.rows.map((row) => [row.key, row.value]));
 
   for (const def of SETTINGS) {
-    if (rowsByKey.has(def.key)) continue;
+    // Existing rows block bootstrap even if unreadable, unknown, or invalid.
+    if (config.storedKeys.has(def.key)) continue;
 
     const envValue = resolveEnvValue(def, "bootstrap");
     if (!shouldBootstrapValue(def, envValue)) continue;
 
-    await upsertEncryptedRow(def.key, envValue);
+    const encryptedValue = await encryptValue(envValue);
+    const inserted = await sql<{ key: string }[]>`
+      INSERT INTO settings.entries (key, value, updated_at)
+      VALUES (${def.key}, ${encryptedValue}, now())
+      ON CONFLICT (key) DO NOTHING
+      RETURNING key
+    `;
+    if (inserted.length === 0) continue;
+
+    await redis.del(REDIS_KEY(def.key));
     rowsByKey.set(def.key, envValue);
     config.stats.envBootstrapped += 1;
   }
@@ -145,11 +167,11 @@ const bootstrapEnvBackedEntries = async (config: {
  */
 export async function loadCache(): Promise<void> {
   getAppSecret();
-  const { rows, stats } = await normalizeStoredEntries();
-  const bootstrappedRows = await bootstrapEnvBackedEntries({ rows, stats });
+  const { rows, storedKeys, stats } = await normalizeStoredEntries();
+  const bootstrappedRows = await bootstrapEnvBackedEntries({ rows, storedKeys, stats });
 
   console.log(
-    `[settings] loaded ${bootstrappedRows.length} custom setting(s) (${stats.encryptedLoaded} encrypted, ${stats.normalizedUpdated} normalized, ${stats.envBootstrapped} env-bootstrapped, ${stats.invalidSkipped} skipped)`,
+    `[settings] loaded ${bootstrappedRows.length} custom setting(s) (${stats.encryptedLoaded} encrypted, ${stats.normalizedUpdated} normalized, ${stats.envBootstrapped} env-bootstrapped, ${stats.undecryptable} undecryptable, ${stats.invalidSkipped} skipped)`,
   );
 }
 

package/src/shared/help.ts

@@ -1,5 +1,39 @@
 import { localeFallbackChain } from "./locale";
 
+export const HELP_KINDS = ["start", "task", "reference", "troubleshoot"] as const;
+export type HelpKind = (typeof HELP_KINDS)[number];
+/** The glossary's access levels; Help names only these, never app-specific permissions. */
+export const HELP_ACCESS_LEVELS = ["view", "edit", "manage"] as const;
+export type HelpAccessLevel = (typeof HELP_ACCESS_LEVELS)[number];
+/** An article another article points to, resolved for the current reader. */
+export type HelpArticleLink = {
+  appId: string;
+  appName: string;
+  /** The target app's accent colour (registry appearance), when it declares one. */
+  accent?: string;
+  documentId: string;
+  title: string;
+  description?: string;
+  icon?: string;
+  /** Canonical page path: `/help/apps/<appId>/<documentId>`. */
+  url: string;
+};
+
+export type HelpLinkResolver = (ref: { appId?: string; documentId: string }) => HelpArticleLink | undefined;
+
+/** References have the same app-id grammar as capability declarations. */
+export const HELP_REFERENCE_PATTERN = /^(?:[a-z][a-z0-9-]*\/)?[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const parseHelpReference = (value: string): { appId?: string; documentId: string; fragment: string } | undefined => {
+  const [reference = "", ...fragments] = value.split("#");
+  if (!HELP_REFERENCE_PATTERN.test(reference)) return undefined;
+  const parts = reference.split("/");
+  return {
+    appId: parts.length === 2 ? parts[0] : undefined,
+    documentId: parts.at(-1)!,
+    fragment: fragments.length ? `#${fragments.join("#")}` : "",
+  };
+};
+
 export type HelpDocumentManifest = {
   /** Resolved content locale on central Help manifests. */
   locale?: string;
@@ -8,6 +42,8 @@ export type HelpDocumentManifest = {
   icon?: string;
   description?: string;
   order: number;
+  /** Where the Help start lists the article; missing means `task`. */
+  kind?: HelpKind;
   /** Core-owned endpoint used for debounced full-text search. */
   searchUrl: string;
   url: string;
@@ -24,8 +60,13 @@ export type HelpDocumentPayload = {
   locale: string;
   id: string;
   title: string;
+  /** Agent text with Help-only presentation converted to portable Markdown. */
   markdown: string;
   html: string;
+  kind: HelpKind;
+  needs?: HelpAccessLevel;
+  next?: HelpArticleLink;
+  related: HelpArticleLink[];
 };
 
 /** Exact locale, then BCP 47 ancestors, then the corpus base locale. */

package/src/shared/index.ts

@@ -46,7 +46,15 @@ export * from "./login-method";
 export { markdown } from "./markdown";
 export { markdownCalloutSanitizeOptions } from "./markdown/callout-sanitizer";
 export type { ErrorCode, EvalContext, EvalError, EvalResult, EvalValue, ProgressValue } from "./markdown/formula";
-export { createProgressValue, evaluateFormula, formatValue, isFormula, isTotalRow, parseProgressValue } from "./markdown/formula";
+export {
+  createProgressValue,
+  evaluateFormula,
+  evaluateTableCell,
+  formatValue,
+  isFormula,
+  isTotalRow,
+  parseProgressValue,
+} from "./markdown/formula";
 export type { MockCover, MockCoverIcon, MockCoverOptions, MockCoverTheme } from "./mock-cover";
 export { createMockCover, createMockCoverSvg, parseDataUrl } from "./mock-cover";
 export * from "./network-address";