@k2b/cloud 0.27.0 → 0.29.0

package/src/contracts/app.ts

@@ -119,6 +119,8 @@ export type AppMeta = {
     section: "primary" | "more" | "hidden";
     requiresAuth?: boolean;
     requiresRoles?: Role[];
+    /** Same-origin path of a `GET` route this app serves that returns an `AppNavBadge`; see `defineApp()`. */
+    badge?: string;
   };
   /**
    * Legal/info pages this app owns. Aggregated app-wide and rendered in
@@ -146,6 +148,14 @@ export type AppMeta = {
   cli?: AppCliModules;
 };
 
+/**
+ * Response of an app's `nav.badge` route: how many items wait for the signed-in
+ * person. A positive safe integer shows a count on the app's icon in the rail
+ * and the app grid (above 99 as "99+"); `0`, a non-200 response, or anything
+ * else shows none.
+ */
+export type AppNavBadge = { count: number };
+
 export type WidgetEndpoint = {
   /** Unique-within-the-app id, e.g. "open-requests". */
   id: string;

package/src/contracts/commands.ts

@@ -8,7 +8,9 @@ export const CommandPathSchema = z
   .refine((value) => {
     if (!value.startsWith("/") || /[\\\u0000-\u0020]/u.test(value)) return false;
     try {
-      return new URL(value, "https://cloud.invalid").origin === "https://cloud.invalid";
+      const url = new URL(value, "https://cloud.invalid");
+      // Dot segments can resolve to `//host`, which a browser reads as another host.
+      return url.origin === "https://cloud.invalid" && !url.pathname.startsWith("//");
     } catch {
       return false;
     }

package/src/contracts/notification-group.ts

@@ -0,0 +1,6 @@
+/** App-chosen keys stay separate from the namespaced tags sent to browsers. */
+export const isNotificationGroup = (value: unknown): value is string =>
+  typeof value === "string" && value.length >= 1 && value.length <= 128 && /^[A-Za-z0-9._:-]+$/.test(value);
+
+export const notificationGroupTag = (appId: string, group: string): string | null =>
+  typeof appId === "string" && /^[a-z][a-z0-9-]*$/.test(appId) && isNotificationGroup(group) ? `${appId}:${group}` : null;

package/src/contracts/notification-types.ts

@@ -31,6 +31,12 @@ export const validateNotificationTargetHref = (value: string): `/${string}` => {
 export type NotificationPresentation = {
   title: string;
   body?: string;
+  /** Short text shown in the browser/OS notification, including the lock screen. Cloud passes it only to the browser channel; email, deployment channels, and notification history never receive it. */
+  preview?: string;
+  /** Stable app-chosen browser group key, namespaced by Cloud per application. */
+  group?: string;
+  /** Non-negative safe integer for the app badge; zero clears it. Browser-only. */
+  badge?: number;
   /** Same-origin absolute path. Validated again before persistence and navigation. */
   targetHref?: `/${string}`;
 };

package/src/contracts/outgoing-mail.ts

@@ -1,7 +1,12 @@
+import type { PageParams, Paginated, ServiceError } from "@k2b/stdlib";
 import { z } from "zod";
+import { type RequestActor, ServiceAccountSchema, UserSchema } from "./shared";
 
 export const PlatformPermissionSchema = z.enum(["mail:send"]);
 export type PlatformPermission = z.infer<typeof PlatformPermissionSchema>;
+export const MailRetentionSchema = z.object({ contentDays: z.int().min(1).max(36500), recordDays: z.int().min(1).max(36500) }).strict();
+export type MailRetention = z.infer<typeof MailRetentionSchema>;
+
 export const MailProfileKeySchema = z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/);
 const headerText = z
   .string()
@@ -9,6 +14,26 @@ const headerText = z
   .min(1)
   .max(120)
   .refine((value) => !/[\r\n\0]/.test(value), "Header must not contain control characters");
+export const MailImapInputSchema = z
+  .object({
+    host: z
+      .string()
+      .trim()
+      .min(1)
+      .max(253)
+      .refine((value) => !/[\s/@\0]/.test(value), "Use an IMAP hostname"),
+    port: z.int().min(1).max(65535),
+    secure: z.boolean(),
+    user: z.string().trim().min(1).max(320),
+    password: z.string().max(16384).nullable().optional(),
+    folder: z
+      .string()
+      .trim()
+      .min(1)
+      .max(200)
+      .refine((value) => !/[\x00-\x1f\x7f]/.test(value), "Folder must not contain control characters"),
+  })
+  .strict();
 export const MailProfileInputSchema = z
   .object({
     name: headerText,
@@ -24,6 +49,7 @@ export const MailProfileInputSchema = z
     smtpSecure: z.boolean(),
     smtpUser: z.string().max(320).nullable(),
     smtpPassword: z.string().max(16384).nullable().optional(),
+    imap: MailImapInputSchema.nullable().optional(),
     pacePerMinute: z.int().min(1).max(6000),
     dailyRecipientLimit: z.int().min(1).max(2147483647).nullable(),
     maxAttachmentBytes: z.int().min(1).max(26214400),
@@ -46,6 +72,19 @@ export const MailProfileSchema = z.object({
 });
 export type MailProfile = z.infer<typeof MailProfileSchema>;
 export const MailErrorCodeSchema = z.enum([
+  "bad_input",
+  "profile_not_allowed",
+  "profile_required",
+  "quota_exceeded",
+  "backlog_full",
+  "attachments_too_large",
+  "attachment_storage_full",
+  "profile_removed",
+  "attachment_lost",
+  "cancelled_by_admin",
+  "message_unknown",
+  "batch_unknown",
+  "message_not_queued",
   "mail_unavailable",
   "mail_not_declared",
   "profile_unknown",
@@ -56,9 +95,13 @@ export const MailErrorCodeSchema = z.enum([
   "smtp_failed",
 ]);
 export type MailErrorCode = z.infer<typeof MailErrorCodeSchema>;
-export const AdminMailProfileSchema = MailProfileInputSchema.omit({ smtpPassword: true, revision: true }).extend({
+export const MailBounceErrorCodeSchema = z.enum(["open_failed", "search_failed", "apply_failed", "save_failed", "interrupted"]);
+export type MailBounceErrorCode = z.infer<typeof MailBounceErrorCodeSchema>;
+export const AdminMailProfileSchema = MailProfileInputSchema.omit({ smtpPassword: true, revision: true, imap: true }).extend({
   key: MailProfileKeySchema,
   hasPassword: z.boolean(),
+  imap: MailImapInputSchema.omit({ password: true }).extend({ hasPassword: z.boolean() }).nullable(),
+  bounces: z.object({ checkedAt: z.string().nullable(), error: MailBounceErrorCodeSchema.nullable() }).nullable(),
   isDefault: z.boolean(),
   revision: z.int(),
   createdAt: z.string(),
@@ -75,3 +118,148 @@ export type AdminMailApp = {
   mode: "default" | "selected";
   profiles: string[];
 };
+
+export const MailStatusSchema = z.enum(["queued", "sending", "sent", "failed", "bounced", "cancelled"]);
+export type MailStatus = z.infer<typeof MailStatusSchema>;
+export type MailAttachment = {
+  filename: string;
+  contentType: string;
+  content: Uint8Array | Blob | ReadableStream<Uint8Array>;
+};
+const body = z
+  .string()
+  .refine((value) => !value.includes("\0"), "Body must not contain NUL")
+  .max(512 * 1024)
+  .refine((value) => new TextEncoder().encode(value).byteLength <= 512 * 1024, "Body exceeds 512 KiB");
+const safeHeader = z.string().refine((value) => !/[\r\n\0]/.test(value), "Header must not contain control characters");
+const allowedHeaders = new Set([
+  "list-id",
+  "list-unsubscribe",
+  "list-unsubscribe-post",
+  "in-reply-to",
+  "references",
+  "auto-submitted",
+  "precedence",
+]);
+export const MailHeadersSchema = z.record(z.string(), safeHeader).refine((headers) => {
+  let bytes = 0;
+  const seen = new Set<string>();
+  for (const [name, value] of Object.entries(headers)) {
+    const lower = name.toLowerCase();
+    if (!/^[\x21-\x39\x3B-\x7E]+$/.test(name) || seen.has(lower)) return false;
+    seen.add(lower);
+    if (!(lower.startsWith("x-") && !lower.startsWith("x-cloud-")) && !allowedHeaders.has(lower)) return false;
+    bytes += new TextEncoder().encode(`${name}: ${value}\r\n`).byteLength;
+  }
+  return bytes <= 8192;
+}, "Invalid mail headers or headers exceed 8 KiB");
+const referenceText = z
+  .string()
+  .min(1)
+  .max(200)
+  .refine((value) => !value.includes("\0"), "Reference must not contain NUL");
+const ref = z.object({ scope: referenceText, id: referenceText }).strict();
+const mailAddress = z.email({ pattern: z.regexes.html5Email }).max(320);
+export const MailMessageSchema = z
+  .object({
+    to: z.array(mailAddress).min(1).max(50),
+    subject: safeHeader.max(998),
+    text: body,
+    html: body.optional(),
+    fromName: safeHeader.max(998).optional(),
+    replyTo: mailAddress.optional(),
+    attachments: z
+      .array(
+        z
+          .object({
+            filename: safeHeader.min(1).max(998),
+            contentType: safeHeader.min(1).max(998),
+            content: z.custom<MailAttachment["content"]>(
+              (value) => value instanceof Uint8Array || value instanceof Blob || value instanceof ReadableStream,
+            ),
+          })
+          .strict(),
+      )
+      .max(20)
+      .optional(),
+    headers: MailHeadersSchema.optional(),
+    profile: MailProfileKeySchema.optional(),
+    ref: ref.optional(),
+    actor: z
+      .custom<RequestActor>((value) => {
+        if (!value || typeof value !== "object" || !("kind" in value)) return false;
+        if (value.kind === "user" && "user" in value) return UserSchema.safeParse(value.user).success;
+        return (
+          value.kind === "service_account" && "serviceAccount" in value && ServiceAccountSchema.safeParse(value.serviceAccount).success
+        );
+      })
+      .optional(),
+    key: z
+      .string()
+      .min(1)
+      .max(200)
+      .refine((value) => !value.includes("\0"), "Key must not contain NUL")
+      .optional(),
+  })
+  .strict();
+export type MailMessage = z.infer<typeof MailMessageSchema>;
+export const MailBatchSchema = z
+  .array(MailMessageSchema)
+  .min(1)
+  .max(1000)
+  .refine((messages) => {
+    const keys = messages.flatMap((message) => (message.key === undefined ? [] : [message.key]));
+    return new Set(keys).size === keys.length;
+  }, "Duplicate outgoing mail keys in a batch");
+export const MailFilterSchema = z
+  .object({
+    ref: ref.partial({ id: true }).optional(),
+    ids: z.array(z.uuid()).max(100).optional(),
+    batchId: z.uuid().optional(),
+    status: z.array(MailStatusSchema).max(6).optional(),
+    since: z.iso.datetime({ offset: true }).optional(),
+  })
+  .strict();
+export type MailFilter = z.infer<typeof MailFilterSchema>;
+export const MailRecordSchema = z.object({
+  id: z.uuid(),
+  batchId: z.uuid().optional(),
+  profile: z.string(),
+  ref: ref.optional(),
+  to: z.array(z.string()),
+  subject: z.string(),
+  text: z.string().optional(),
+  attachments: z.array(z.object({ filename: z.string(), contentType: z.string(), size: z.int().nonnegative(), sha256: z.string() })),
+  status: MailStatusSchema,
+  error: z.string().optional(),
+  failures: z.array(z.object({ recipient: z.string(), reason: z.string(), at: z.string() })),
+  attempts: z.int(),
+  actor: z.object({ id: z.string(), name: z.string() }).optional(),
+  createdAt: z.string(),
+  sentAt: z.string().optional(),
+  contentPurgedAt: z.string().optional(),
+});
+export type MailRecord = z.infer<typeof MailRecordSchema>;
+export const AdminMailRecordSchema = MailRecordSchema.omit({ text: true }).extend({
+  appId: z.string(),
+  errorCode: z.string().optional(),
+  response: z.string().optional(),
+});
+export type AdminMailRecord = z.infer<typeof AdminMailRecordSchema>;
+/** Extends the shared offset-page shape with stable keyset navigation. */
+export type MailPageParams = PageParams & { cursor?: string };
+export type MailPage<T = MailRecord> = Paginated<T> & { nextCursor?: string };
+export const MailPageParamsSchema = z
+  .object({ page: z.int().min(1).optional(), perPage: z.int().min(1).max(100).optional(), cursor: z.string().max(1024).optional() })
+  .strict();
+export const AdminMailFilterSchema = MailFilterSchema.extend({
+  app: z.string().min(1).optional(),
+  profile: MailProfileKeySchema.optional(),
+  recipient: z.string().max(320).optional(),
+});
+export type AdminMailFilter = z.infer<typeof AdminMailFilterSchema>;
+export type MailServiceError = ServiceError<MailErrorCode> & {
+  limit?: number;
+  used?: number;
+  requested?: number;
+};

package/src/contracts/registry.ts

@@ -16,6 +16,7 @@ export type AppRegistryNav = {
   section: "primary" | "more" | "hidden";
   requiresAuth?: boolean;
   requiresRoles?: Role[];
+  badge?: string;
   adminHref?: string;
 };
 

package/src/contracts/user-notifications.ts

@@ -58,6 +58,80 @@ export const UserNotificationHistoryResponseSchema = z.object({
 });
 export type UserNotificationHistoryResponse = z.infer<typeof UserNotificationHistoryResponseSchema>;
 
+// Contracts reach the browser bundle, so this uses Intl directly instead of the stdlib date helpers.
+const isTimeZone = (value: string): boolean => {
+  try {
+    new Intl.DateTimeFormat("en", { timeZone: value }).format(0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** Wall-clock time `HH:MM` in the quiet hours' time zone. */
+const QuietTimeOfDaySchema = z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, "Use a time from 00:00 to 23:59");
+
+/**
+ * One recurring quiet period. Days are ISO weekdays (1 = Monday … 7 = Sunday). A period that ends at or before
+ * its start runs overnight into the next day; equal start and end make 24 hours quiet, so 00:00 to 00:00 is the
+ * whole day.
+ */
+export const NotificationQuietPeriodSchema = z.object({
+  days: z
+    .array(z.number().int().min(1).max(7))
+    .min(1)
+    .max(7)
+    .refine((days) => new Set(days).size === days.length, "Each weekday can appear only once"),
+  start: QuietTimeOfDaySchema,
+  end: QuietTimeOfDaySchema,
+});
+export type NotificationQuietPeriod = z.infer<typeof NotificationQuietPeriodSchema>;
+
+/** One period per weekday is the most a weekly schedule needs, so seven periods bound the schedule. */
+export const NOTIFICATION_QUIET_PERIOD_LIMIT = 7;
+
+export const NotificationQuietHoursSchema = z.object({
+  timeZone: z.string().trim().min(1).max(64).refine(isTimeZone, "Unknown time zone"),
+  periods: z.array(NotificationQuietPeriodSchema).max(NOTIFICATION_QUIET_PERIOD_LIMIT),
+});
+export type NotificationQuietHours = z.infer<typeof NotificationQuietHoursSchema>;
+
+export const NotificationQuietReasonSchema = z.enum(["doNotDisturb", "quietHours"]);
+export type NotificationQuietReason = z.infer<typeof NotificationQuietReasonSchema>;
+
+/** Whether Cloud holds back browser notifications right now and, when known, until when. */
+export const NotificationQuietStateSchema = z.object({
+  active: z.boolean(),
+  reason: NotificationQuietReasonSchema.nullable(),
+  /** End of the current quiet time; null when inactive or when no end lies within the next week. */
+  until: z.string().datetime().nullable(),
+  /** Start of the next quiet hours while inactive; null when active or when none starts within the next week. */
+  nextStart: z.string().datetime().nullable(),
+});
+export type NotificationQuietState = z.infer<typeof NotificationQuietStateSchema>;
+
+export const NotificationQuietSettingsSchema = z.object({
+  doNotDisturbUntil: z.string().datetime().nullable(),
+  quietHours: NotificationQuietHoursSchema,
+  state: NotificationQuietStateSchema,
+});
+export type NotificationQuietSettings = z.infer<typeof NotificationQuietSettingsSchema>;
+
+/**
+ * Do not disturb is a pause, so it ends within a year (366 days covers the same date next year). Holding back
+ * browser notifications for longer is turning them off, which the notification preferences and the device do.
+ */
+export const NOTIFICATION_DO_NOT_DISTURB_MAX_DAYS = 366;
+
+export const UpdateNotificationQuietSettingsSchema = z
+  .object({
+    /** A future instant at most `NOTIFICATION_DO_NOT_DISTURB_MAX_DAYS` ahead pauses browser notifications until then; null resumes them. */
+    doNotDisturbUntil: z.iso.datetime({ offset: true }).nullable().optional(),
+    quietHours: NotificationQuietHoursSchema.optional(),
+  })
+  .refine((value) => value.doNotDisturbUntil !== undefined || value.quietHours !== undefined, "Nothing to update");
+export type UpdateNotificationQuietSettings = z.infer<typeof UpdateNotificationQuietSettingsSchema>;
+
 export const isSafeBrowserPushEndpoint = (value: string): boolean => {
   try {
     if (/[\\\u0000-\u001f\u007f]/.test(value)) return false;

package/src/server/middleware/request-logger.ts

@@ -1,6 +1,8 @@
 import { createMiddleware } from "hono/factory";
 import { logger } from "../../services/logging";
+import { redactSensitivePath } from "../../services/logging/redaction";
 import type { AuthContext } from "./auth";
+import { matchedRouteTemplate } from "./route-template";
 
 const log = logger("http");
 
@@ -15,11 +17,18 @@ const SKIP_PREFIXES = ["/public/", "/_ssr/", "/favicon", "/branding/"];
  * - Everything else (2xx, 3xx, 400, 404) → not logged (too noisy)
  */
 export const requestLogger = createMiddleware<AuthContext>(async (c, next) => {
-  const path = c.req.path;
-  if (SKIP_PREFIXES.some((p) => path.startsWith(p))) return next();
+  const requestPath = c.req.path;
+  if (SKIP_PREFIXES.some((p) => requestPath.startsWith(p))) return next();
 
   const start = Date.now();
   await next();
+  let path: string | null = null;
+  try {
+    path = matchedRouteTemplate(c);
+  } catch {
+    // Best-effort: an unrouted context must never break request logging.
+  }
+  path ??= redactSensitivePath(requestPath);
   const status = c.res.status;
   const duration = Date.now() - start;
 

package/src/services/accounts/avatar.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { sql } from "bun";
 import { MAX_AVATAR_BYTES, MAX_AVATAR_DATA_URL_LENGTH } from "../../contracts/profile";
 import type { MutationResult } from "../../contracts/shared";
+import { stripImageMetadata } from "../image-metadata";
 
 export { MAX_AVATAR_BYTES, MAX_AVATAR_DATA_URL_LENGTH } from "../../contracts/profile";
 
@@ -95,10 +96,12 @@ export const setAvatar = async (params: { id: string; dataUrl: string }): Promis
   const parsed = parseAvatarDataUrl(params.dataUrl);
   if (!parsed.ok) return parsed;
 
+  const bytes = Buffer.from(stripImageMetadata(parsed.data.bytes));
+  const dataUrl = `data:${parsed.data.contentType};base64,${bytes.toString("base64")}`;
   const rows = await sql<{ avatar_hash: string }[]>`
     UPDATE auth.users
-    SET avatar_data_url = ${parsed.data.dataUrl},
-        avatar_hash = ${parsed.data.hash}
+    SET avatar_data_url = ${dataUrl},
+        avatar_hash = ${hashAvatar(dataUrl)}
     WHERE id = ${params.id}::uuid
     RETURNING avatar_hash
   `;

package/src/services/help/store.ts

@@ -1,5 +1,6 @@
 import { type SQL, sql } from "bun";
 import { APP_REGISTRY_TTL_MS } from "../../_internal/registry";
+import { ensureSchema } from "../postgres";
 import type { HelpCorpus, HelpMetadata } from "./types";
 
 // One expired app lease of grace after an app can no longer be discovered.
@@ -10,7 +11,7 @@ const searchConfigs = ["english", "german", "simple"] as const;
 export const migrateHelp = async (db: SQL = sql): Promise<void> => {
   await db.begin(async (tx) => {
     await tx`SELECT pg_advisory_xact_lock(hashtext('cloud:help:migrate'))`;
-    await tx`CREATE SCHEMA IF NOT EXISTS help`.simple();
+    await ensureSchema(tx, "help");
     await tx`CREATE TABLE IF NOT EXISTS help.corpora (
     app_id text NOT NULL, manifest_hash text NOT NULL, base_locale text NOT NULL,
     last_seen_at timestamptz NOT NULL DEFAULT now(),