@k2b/cloud 0.25.0 → 0.27.0

package/src/cli/admin/ai-quotas.ts

@@ -1,4 +1,9 @@
 import { type AiModelPricing, AiModelPricingSchema } from "../../shared/ai-costs";
+import {
+  type AiModelRequestSettings,
+  AiModelRequestSettingsSchema,
+  AiModelRequestSettingsUpdateSchema,
+} from "../../shared/ai-model-request-settings";
 import {
   type AiQuotaConfig,
   AiQuotaConfigSchema,
@@ -7,7 +12,7 @@ import {
   AiQuotaReportQuerySchema,
   AiQuotaResetSchema,
 } from "../../shared/ai-quotas";
-import { type CloudCliContext, cliText, command, confirmFlag, flag, printRows, printStructured } from "../index";
+import { type CloudCliContext, cliText, command, confirmFlag, flag, printRows, printStructured, readCliInput } from "../index";
 import { apiGet, apiJson, queryString, readJsonInput } from "./shared";
 
 const path = "/api/admin/core/ai-quotas";
@@ -23,6 +28,70 @@ const confirm = (ctx: CloudCliContext, yes: boolean) => {
 };
 
 export const aiQuotaCommands = [
+  command("ai models settings get", {
+    summary: "Read model thinking level, extra parameters and configured header names",
+    flags: { id: flag.string({ required: true, description: "Model profile ID" }) },
+    async run({ ctx, flags }) {
+      print(ctx, AiModelRequestSettingsSchema.parse(await apiGet(ctx, `${path}/models/${encodeURIComponent(flags.id!)}/settings`)));
+    },
+  }),
+  command("ai models settings set", {
+    summary: "Patch one model's request settings; header values are write-only",
+    flags: {
+      id: flag.string({ required: true, description: "Model profile ID" }),
+      thinkingLevel: flag.string({ name: "thinking-level", description: "Provider-specific thinking level" }),
+      clearThinkingLevel: flag.boolean({ name: "clear-thinking-level", description: "Use the model's default thinking level" }),
+      extraBody: flag.input({ name: "extra-body", description: "Extra parameters JSON: --extra-body, --extra-body-file or --stdin" }),
+      clearExtraBody: flag.boolean({ name: "clear-extra-body", description: "Remove extra parameters" }),
+      headers: flag.input({
+        stdinName: "headers-stdin",
+        description: "Header patch JSON; use --headers-file or --headers-stdin for secrets",
+      }),
+      clearHeaders: flag.boolean({ name: "clear-headers", description: "Remove all configured extra headers before applying the patch" }),
+      yes: confirmFlag("Confirm model request settings change"),
+    },
+    async run({ ctx, flags }) {
+      if (!flags.yes) throw new Error("Model request settings changes require --yes.");
+      if (flags.thinkingLevel !== undefined && flags.clearThinkingLevel)
+        throw new Error("Choose --thinking-level or --clear-thinking-level.");
+      if (flags.extraBody.provided && flags.clearExtraBody) throw new Error("Choose --extra-body or --clear-extra-body.");
+      if (
+        !flags.extraBody.provided &&
+        !flags.headers.provided &&
+        flags.thinkingLevel === undefined &&
+        !flags.clearThinkingLevel &&
+        !flags.clearExtraBody &&
+        !flags.clearHeaders
+      )
+        throw new Error("Select at least one model request setting to change.");
+      if (flags.extraBody.source === "stdin" && flags.headers.source === "stdin")
+        throw new Error("Read one JSON input from stdin and supply the other from a file.");
+      const parseInput = async (input: typeof flags.headers, label: string): Promise<unknown> => {
+        const raw = await readCliInput(input, { required: true, label });
+        try {
+          return JSON.parse(raw!);
+        } catch {
+          throw new Error(`Invalid ${label} JSON.`);
+        }
+      };
+      const patch: Record<string, unknown> = {};
+      if (flags.thinkingLevel !== undefined || flags.clearThinkingLevel)
+        patch.reasoningEffort = flags.clearThinkingLevel ? null : flags.thinkingLevel;
+      if (flags.extraBody.provided || flags.clearExtraBody)
+        patch.extraBody = flags.clearExtraBody ? null : await parseInput(flags.extraBody, "extra parameters");
+      if (flags.headers.provided) patch.requestHeaders = await parseInput(flags.headers, "extra headers");
+      if (flags.clearHeaders) patch.clearRequestHeaders = true;
+      // Validate locally before reading the current revision or sending secrets.
+      const valid = AiModelRequestSettingsUpdateSchema.parse({ ...patch, expected: "pending" });
+      const current = await apiGet<AiModelRequestSettings>(ctx, `${path}/models/${encodeURIComponent(flags.id!)}/settings`);
+      print(
+        ctx,
+        AiModelRequestSettingsSchema.parse(
+          await apiJson(ctx, "PUT", `${path}/models/${encodeURIComponent(flags.id!)}/settings`, { ...valid, expected: current.revision }),
+        ),
+      );
+    },
+  }),
   command("ai models pricing get", {
     summary: "List configured model input/output reference prices per million tokens",
     async run({ ctx }) {

package/src/cli/admin/index.ts

@@ -25,6 +25,7 @@ import { logCommands } from "./logs";
 import { metricsCommands } from "./metrics";
 import { natsCommands } from "./nats";
 import { notificationCommands } from "./notifications";
+import { outgoingMailCommands } from "./outgoing-mail";
 import { syncCommands } from "./sync";
 import { telemetryCommands } from "./telemetry";
 import { webhookCommands } from "./webhooks";
@@ -38,6 +39,7 @@ export default defineCliCommands({
     ai: "Manage AI models, quotas, Skills, and usage.",
     "ai models": "Manage AI model configuration.",
     "ai models pricing": "Manage model reference prices.",
+    "ai models settings": "Manage model thinking levels, extra parameters, and extra headers.",
     "ai quotas background": "Inspect and release the background emergency stop.",
     "ai skills": "Inspect Assistant Skills and trusted templates.",
     "ai usage": "Inspect AI runs and usage facets.",
@@ -55,6 +57,9 @@ export default defineCliCommands({
     "nats consumers": "Inspect NATS consumers.",
     "nats streams": "Find NATS streams and buckets.",
     "notification-batches": "Manage account notification batches.",
+    "outgoing-mail": "Manage outgoing mail sender profiles and application access.",
+    "outgoing-mail profiles": "Manage outgoing mail sender profiles.",
+    "outgoing-mail apps": "Manage application outgoing mail access.",
     notifications: "Inspect and resend email notifications.",
     postgres: "Inspect Postgres diagnostics.",
     redis: "Inspect Valkey diagnostics.",
@@ -96,6 +101,7 @@ export default defineCliCommands({
     ...workflowCommands,
     ...dataCommands,
     ...notificationCommands,
+    ...outgoingMailCommands,
     ...webhookCommands,
     ...metricsCommands,
     ...natsCommands,

package/src/cli/admin/outgoing-mail.ts

@@ -0,0 +1,118 @@
+import { type AdminMailApp, type AdminMailProfile, MailProfileInputSchema } from "../../contracts/outgoing-mail";
+import { arg, type CloudCliContext, command, confirmFlag, flag, readCliInput } from "../index";
+import { apiGet, apiJson, printJsonOrTable } from "./shared";
+
+const root = "/api/admin/core/outgoing-mail";
+const profilePath = (key: string) => `${root}/profiles/${encodeURIComponent(key)}`;
+const keyArgs = { key: arg.required({ valueLabel: "key" }) };
+const print = (ctx: CloudCliContext, value: unknown) => {
+  if (ctx.options.output === "json") ctx.json(value);
+  else ctx.print(JSON.stringify(value, null, 2));
+};
+const confirmed = (yes: boolean) => {
+  if (!yes) throw new Error("Outgoing mail policy changes require --yes.");
+};
+export const outgoingMailCommands = [
+  command("outgoing-mail profiles list", {
+    summary: "List outgoing mail sender profiles",
+    async run({ ctx }) {
+      const result = await apiGet<{ items: AdminMailProfile[] }>(ctx, `${root}/profiles`);
+      printJsonOrTable(
+        ctx,
+        result,
+        result.items.map((p) => ({ key: p.key, name: p.name, from: p.fromAddress, default: p.isDefault, revision: p.revision })),
+        [{ key: "key" }, { key: "name" }, { key: "from" }, { key: "default" }, { key: "revision" }],
+      );
+    },
+  }),
+  command("outgoing-mail profiles get", {
+    summary: "Read one outgoing mail sender profile",
+    args: keyArgs,
+    async run({ ctx, args }) {
+      print(ctx, await apiGet(ctx, profilePath(args.key)));
+    },
+  }),
+  command("outgoing-mail profiles put", {
+    summary: "Create or replace a sender profile with its current revision",
+    args: keyArgs,
+    flags: { config: flag.input({ required: true, description: "Profile JSON; SMTP passwords only via --config-file or --stdin" }) },
+    async run({ ctx, args, flags }) {
+      const input = await readCliInput(flags.config, { label: "outgoing mail profile", required: true });
+      let raw: unknown;
+      try {
+        raw = JSON.parse(input ?? "");
+      } catch {
+        throw new Error("Invalid outgoing mail profile JSON.");
+      }
+      if (flags.config.source === "value" && raw && typeof raw === "object" && "smtpPassword" in raw)
+        throw new Error("Pass smtpPassword only through --config-file or --stdin.");
+      print(ctx, await apiJson(ctx, "PUT", profilePath(args.key), MailProfileInputSchema.parse(raw)));
+    },
+  }),
+  command("outgoing-mail profiles set-default", {
+    summary: "Choose the default outgoing mail sender",
+    args: keyArgs,
+    flags: { yes: confirmFlag("Confirm changing the default sender") },
+    async run({ ctx, args, flags }) {
+      confirmed(flags.yes);
+      print(ctx, await apiJson(ctx, "POST", `${profilePath(args.key)}/default`));
+    },
+  }),
+  command("outgoing-mail profiles delete", {
+    summary: "Delete a sender profile that is not the default",
+    args: keyArgs,
+    flags: { yes: confirmFlag("Confirm deleting the sender profile") },
+    async run({ ctx, args, flags }) {
+      confirmed(flags.yes);
+      const response = await ctx.fetch(profilePath(args.key), { method: "DELETE" });
+      if (!response.ok) await ctx.readJson(response);
+      print(ctx, { deleted: args.key });
+    },
+  }),
+  command("outgoing-mail profiles test", {
+    summary: "Send a test email through a sender profile",
+    args: keyArgs,
+    flags: { to: flag.string({ required: true, description: "Recipient email address" }) },
+    async run({ ctx, args, flags }) {
+      print(ctx, await apiJson(ctx, "POST", `${profilePath(args.key)}/test`, { recipient: flags.to }));
+    },
+  }),
+  command("outgoing-mail apps list", {
+    summary: "List application outgoing mail permissions and profile access",
+    async run({ ctx }) {
+      const result = await apiGet<{ defaultProfile: string | null; items: AdminMailApp[] }>(ctx, `${root}/apps`);
+      printJsonOrTable(
+        ctx,
+        result,
+        result.items.map((app) => ({ ...app, profiles: app.profiles.join(",") })),
+        [{ key: "appId" }, { key: "name" }, { key: "declared" }, { key: "mode" }, { key: "profiles" }],
+      );
+    },
+  }),
+  command("outgoing-mail apps set", {
+    summary: "Set default, selected, or blocked outgoing mail access",
+    args: { app: arg.required({ valueLabel: "app" }) },
+    flags: {
+      default: flag.boolean({ description: "Use the default sender" }),
+      profiles: flag.string({ description: "Comma-separated profile keys" }),
+      none: flag.boolean({ description: "Block sending with an empty selected list" }),
+      yes: confirmFlag("Confirm application outgoing mail access change"),
+    },
+    async run({ ctx, args, flags }) {
+      confirmed(flags.yes);
+      if ([flags.default, flags.none, flags.profiles !== undefined].filter(Boolean).length !== 1)
+        throw new Error("Choose exactly one of --default, --profiles or --none.");
+      const profiles = flags.profiles?.split(",").map((key) => key.trim());
+      if (profiles?.some((key) => !key)) throw new Error("--profiles requires non-empty profile keys; use --none to block sending.");
+      print(
+        ctx,
+        await apiJson(
+          ctx,
+          "PUT",
+          `${root}/apps/${encodeURIComponent(args.app)}`,
+          flags.default ? { mode: "default" } : { mode: "selected", profiles: profiles ?? [] },
+        ),
+      );
+    },
+  }),
+];

package/src/contracts/app.ts

@@ -1,4 +1,5 @@
 import type { Sync } from "@k2b/sync";
+import type { PlatformPermission } from "./outgoing-mail";
 import type { AppRegistryHelpSummary } from "./registry";
 import type { Role } from "./shared";
 import type { DashboardWidgetPresentation } from "./widgets";
@@ -97,6 +98,7 @@ export type AppPwaPart = {
 };
 
 export type AppMeta = {
+  platformPermissions?: readonly PlatformPermission[];
   id: string;
   name: string;
   icon: string;

package/src/contracts/index.ts

@@ -8,6 +8,7 @@ export * from "./commands";
 export * from "./contact-directory";
 export * from "./file-provider";
 export * from "./notification-types";
+export * from "./outgoing-mail";
 export * from "./posix";
 export * from "./profile";
 export * from "./pwa";

package/src/contracts/outgoing-mail.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+
+export const PlatformPermissionSchema = z.enum(["mail:send"]);
+export type PlatformPermission = z.infer<typeof PlatformPermissionSchema>;
+export const MailProfileKeySchema = z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/);
+const headerText = z
+  .string()
+  .trim()
+  .min(1)
+  .max(120)
+  .refine((value) => !/[\r\n\0]/.test(value), "Header must not contain control characters");
+export const MailProfileInputSchema = z
+  .object({
+    name: headerText,
+    fromAddress: z.email().max(320),
+    fromName: headerText.nullable(),
+    smtpHost: z
+      .string()
+      .trim()
+      .min(1)
+      .max(253)
+      .refine((value) => !/[\s/@\0]/.test(value), "Use an SMTP hostname"),
+    smtpPort: z.int().min(1).max(65535),
+    smtpSecure: z.boolean(),
+    smtpUser: z.string().max(320).nullable(),
+    smtpPassword: z.string().max(16384).nullable().optional(),
+    pacePerMinute: z.int().min(1).max(6000),
+    dailyRecipientLimit: z.int().min(1).max(2147483647).nullable(),
+    maxAttachmentBytes: z.int().min(1).max(26214400),
+    revision: z.int().min(1).max(2147483647).optional(),
+  })
+  .strict();
+export type MailProfileInput = z.infer<typeof MailProfileInputSchema>;
+export const MailAppAccessSchema = z.discriminatedUnion("mode", [
+  z.object({ mode: z.literal("default") }).strict(),
+  z.object({ mode: z.literal("selected"), profiles: z.array(MailProfileKeySchema) }).strict(),
+]);
+export type MailAppAccess = z.infer<typeof MailAppAccessSchema>;
+export const MailProfileSchema = z.object({
+  key: MailProfileKeySchema,
+  name: z.string(),
+  from: z.email(),
+  default: z.boolean(),
+  maxAttachmentBytes: z.int(),
+  quota: z.object({ dailyRecipients: z.int().nullable(), usedLast24h: z.int() }),
+});
+export type MailProfile = z.infer<typeof MailProfileSchema>;
+export const MailErrorCodeSchema = z.enum([
+  "mail_unavailable",
+  "mail_not_declared",
+  "profile_unknown",
+  "profile_exists",
+  "profile_is_default",
+  "revision_conflict",
+  "invalid_profile",
+  "smtp_failed",
+]);
+export type MailErrorCode = z.infer<typeof MailErrorCodeSchema>;
+export const AdminMailProfileSchema = MailProfileInputSchema.omit({ smtpPassword: true, revision: true }).extend({
+  key: MailProfileKeySchema,
+  hasPassword: z.boolean(),
+  isDefault: z.boolean(),
+  revision: z.int(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  updatedBy: z.string().nullable(),
+  appCount: z.int(),
+});
+export type AdminMailProfile = z.infer<typeof AdminMailProfileSchema>;
+export type AdminMailApp = {
+  appId: string;
+  name: string;
+  registered: boolean;
+  declared: boolean;
+  mode: "default" | "selected";
+  profiles: string[];
+};

package/src/contracts/registry.ts

@@ -1,5 +1,6 @@
 import type { AppAdminNavigationGroup, AppAppearance, AppAppearanceColor, AppPresentationCatalog, AppSearchLink } from "./app";
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "./capabilities";
+import type { PlatformPermission } from "./outgoing-mail";
 import type { Role } from "./shared";
 import type { DashboardWidgetPresentation } from "./widgets";
 
@@ -38,6 +39,8 @@ export type CapabilityRegistryEntry = {
   endpoint: string;
   manifest: CapabilityManifest;
   presentation?: CapabilityPresentationCatalog;
+  /** The app's own name and description overlays, so capability consumers can present the app in the reader's locale. */
+  appPresentation?: AppPresentationCatalog;
 };
 
 export type AppRegistryHelpSummary = { manifestHash: string; pageBase: string; baseLocale: string };
@@ -63,6 +66,7 @@ export type AppRuntimeMetadata = {
 };
 
 export type AppRegistryEntry = {
+  platformPermissions?: readonly PlatformPermission[];
   id: string;
   name: string;
   icon: string;

package/src/services/index.ts

@@ -204,3 +204,6 @@ export { legalConsent } from "./legal-consent";
 export { railShortcuts } from "./rail-shortcuts";
 
 export type { WebVitalsOverview, WebVitalsQuery, WebVitalMetric, WebVitalName } from "./logging/web-vitals";
+
+export { mail } from "./outgoing-mail";
+export type { MailProfile } from "../contracts/outgoing-mail";

package/src/services/notifications/email.ts

@@ -1,24 +1,10 @@
-import { createTransport, type Transporter } from "nodemailer";
 import sanitizeHtml from "sanitize-html";
 import { sanitizeEmailHtml } from "../../shared";
+import { resolveMailCredentials } from "../outgoing-mail/store";
+import { buildMailTransport } from "../outgoing-mail/transport";
 import * as settings from "../settings";
 import { coreSettings } from "../settings/api";
 
-/** Lazily-created transporter — uses current settings on each send. */
-const getTransporter = async (): Promise<Transporter> => {
-  const host = await settings.get<string>("mail.noreply.smtp_host");
-  const port = await settings.get<number>("mail.noreply.smtp_port");
-  const user = await settings.get<string>("mail.noreply.user");
-  const pass = await settings.get<string>("mail.noreply.password");
-
-  return createTransport({
-    host,
-    port,
-    secure: port === 465,
-    auth: { user, pass },
-  });
-};
-
 /** Sanitize plain text content (no HTML allowed). */
 const sanitizeContent = (content: string): string => sanitizeHtml(content, { allowedTags: [], allowedAttributes: {} });
 
@@ -31,7 +17,7 @@ export const sendEmail = async (
   const rawAppUrl = await settings.get<string>("app.url");
   const appUrl = rawAppUrl.startsWith("http") ? rawAppUrl : `https://${rawAppUrl}`;
   const appName = await settings.get<string>("app.name");
-  const emailFrom = await settings.get<string>("mail.noreply.from");
+  const profile = await resolveMailCredentials();
 
   let body = "";
   if (opts.rawHtml) {
@@ -42,16 +28,20 @@ export const sendEmail = async (
   const text = opts.content ? sanitizeContent(opts.content) : undefined;
 
   const html = await buildHtml(appUrl, appName, body);
-  const transporter = await getTransporter();
+  const transporter = buildMailTransport(profile);
 
-  await transporter.sendMail({
-    from: `"${appName}" <${emailFrom}>`,
-    to,
-    subject,
-    ...(opts.messageId ? { messageId: opts.messageId } : {}),
-    html,
-    ...(text ? { text } : {}),
-  });
+  try {
+    await transporter.sendMail({
+      from: { address: profile.fromAddress, name: profile.fromName ?? appName },
+      to,
+      subject,
+      ...(opts.messageId ? { messageId: opts.messageId } : {}),
+      html,
+      ...(text ? { text } : {}),
+    });
+  } finally {
+    transporter.close();
+  }
 };
 
 /**

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

@@ -0,0 +1,19 @@
+import { fail, ok, type Result } from "@k2b/stdlib";
+import { getProcessApplicationId, getProcessPlatformPermissions } from "../../_internal/process-identity";
+import type { MailProfile } from "../../contracts/outgoing-mail";
+import { outgoingMailStore } from "./store";
+
+export const mail = {
+  async profiles(): Promise<Result<MailProfile[]>> {
+    const appId = getProcessApplicationId();
+    if (!appId)
+      return fail({ code: "mail_unavailable", message: "Start the application before reading outgoing mail profiles.", status: 500 });
+    if (!getProcessPlatformPermissions().includes("mail:send"))
+      return fail({ code: "mail_not_declared", message: 'Declare platformPermissions: ["mail:send"].', status: 403 });
+    try {
+      return ok(await outgoingMailStore.profilesForApp(appId));
+    } catch {
+      return fail({ code: "mail_unavailable", message: "Outgoing mail profiles are unavailable.", status: 500 });
+    }
+  },
+};