@k2b/cloud 0.33.0 → 0.35.0

package/src/services/approvals/index.ts

@@ -72,6 +72,8 @@ export type ApprovalRequest = {
   reviewDigest: string;
   status: ApprovalStatus;
   decidedVia: ApprovalDecisionChannel | null;
+  decidedDeviceId: string | null;
+  approverAuthEpoch: string | null;
   decidedAt: Date | null;
   consumedAt: Date | null;
   createdAt: Date;
@@ -83,11 +85,23 @@ const columns = () => sql`id, app_id AS "appId", action, approval_scope AS "appr
   requester_kind AS "requesterKind", requester_ref AS "requesterRef", requester_app_id AS "requesterAppId",
   requester_title AS "requesterTitle", subject_id AS "subjectId", approver_user_id AS "approverUserId",
   assurance, sentence, details, args_digest AS "argsDigest", review_digest AS "reviewDigest", status,
+  decided_device_id AS "decidedDeviceId", approver_auth_epoch::text AS "approverAuthEpoch",
   decided_via AS "decidedVia", decided_at AS "decidedAt", consumed_at AS "consumedAt",
   created_at AS "createdAt", expires_at AS "expiresAt"`;
 
 const transaction = <T>(db: SQL | undefined, run: (tx: SQL) => Promise<T>): Promise<T> => (db && db !== sql ? run(db) : sql.begin(run));
 
+const lockDecider = async (tx: SQL, userId: string, deviceId: string | null) => {
+  // User before device before request: sign-out everywhere updates the user first, then devices.
+  const [user] = await tx<{ epoch: string }[]>`SELECT auth_epoch::text AS epoch FROM auth.users WHERE id=${userId}::uuid FOR SHARE`;
+  const [device] =
+    deviceId === null
+      ? []
+      : await tx`SELECT 1 FROM auth.app_devices
+    WHERE id=${deviceId}::uuid AND user_id=${userId}::uuid AND revoked_at IS NULL FOR SHARE`;
+  return { epoch: user?.epoch ?? null, deviceActive: !!device };
+};
+
 export type ApprovalRequestResult = { ok: true; id: string } | { ok: false; code: "CONFLICT" };
 /**
  * Records the question once per requester reference. Asking again, for example after a worker restart, returns the
@@ -103,10 +117,10 @@ export const request = async (input: ApprovalRequestInput, db?: SQL): Promise<Ap
   return transaction(db, async (tx): Promise<ApprovalRequestResult> => {
     const [row] = await tx<{ id: string }[]>`
       INSERT INTO approvals.requests (app_id, action, approval_scope, requester_kind, requester_ref, requester_app_id,
-        requester_title, subject_id, approver_user_id, assurance, sentence, details, args_digest, review_digest, expires_at)
+        requester_title, subject_id, approver_user_id, approver_auth_epoch, assurance, sentence, details, args_digest, review_digest, expires_at)
       VALUES (${input.appId}, ${input.action}, ${input.approvalScope ?? null}, ${input.requester.kind}, ${input.requester.ref},
         ${input.requester.appId}, ${input.requester.title ?? null}, ${input.subjectId}::uuid, ${input.approverUserId}::uuid,
-        ${input.assurance}, ${input.sentence}, ${JSON.stringify(input.review ?? null)}::text::jsonb,
+        (SELECT auth_epoch FROM auth.users WHERE id=${input.approverUserId}::uuid), ${input.assurance}, ${input.sentence}, ${JSON.stringify(input.review ?? null)}::text::jsonb,
         ${approvalArgsDigest(input.input)}, ${approvalReviewDigest(input.review)}, now() + (${expiresInMs} * interval '1 millisecond'))
       ON CONFLICT (requester_kind, requester_ref) DO NOTHING
       RETURNING id
@@ -115,6 +129,7 @@ export const request = async (input: ApprovalRequestInput, db?: SQL): Promise<Ap
     const [open] = await tx<{ id: string }[]>`SELECT id FROM approvals.requests
       WHERE requester_kind=${input.requester.kind} AND requester_ref=${input.requester.ref}
         AND status='pending' AND expires_at > now() AND subject_id=${input.subjectId}::uuid
+        AND approver_auth_epoch=(SELECT auth_epoch FROM auth.users WHERE id=${input.approverUserId}::uuid)
         AND approver_user_id=${input.approverUserId}::uuid AND app_id=${input.appId} AND action=${input.action}`;
     return open ? { ok: true, id: open.id } : { ok: false, code: "CONFLICT" };
   });
@@ -137,12 +152,9 @@ export const decide = async (
   db?: SQL,
 ): Promise<ApprovalDecisionResult> => {
   const result = await transaction(db, async (tx): Promise<ApprovalDecisionResult> => {
-    // Lock the device before the request so revocation and the decision serialize.
-    if (actor.deviceId !== undefined) {
-      const [device] = await tx`SELECT 1 FROM auth.app_devices
-        WHERE id=${actor.deviceId}::uuid AND user_id=${actor.userId}::uuid AND revoked_at IS NULL FOR SHARE`;
-      if (!device) return { ok: false, code: "NOT_FOUND" };
-    }
+    // Lock the approver and device before the request so revocation and decisions serialize.
+    const decider = await lockDecider(tx, actor.userId, actor.deviceId ?? null);
+    if (actor.deviceId !== undefined && !decider.deviceActive) return { ok: false, code: "NOT_FOUND" };
     const [row] = await tx<ApprovalRequest[]>`SELECT ${columns()} FROM approvals.requests
       WHERE id=${id}::uuid AND approver_user_id=${actor.userId}::uuid FOR UPDATE`;
     if (!row) return { ok: false, code: "NOT_FOUND" };
@@ -151,8 +163,9 @@ export const decide = async (
     const [won] = rejectOnly
       ? []
       : await tx<ApprovalRequest[]>`
-      UPDATE approvals.requests SET status=${status}, decided_via=${actor.via}, decided_at=now()
+      UPDATE approvals.requests SET status=${status}, decided_via=${actor.via}, decided_device_id=${actor.deviceId ?? null}::uuid, decided_at=now()
       WHERE id=${id}::uuid AND approver_user_id=${actor.userId}::uuid AND status='pending' AND expires_at > now()
+        AND approver_auth_epoch=${decider.epoch}::bigint
       RETURNING ${columns()}
     `;
     if (won) {
@@ -178,7 +191,8 @@ export const decide = async (
     }
     if (row.status === "pending") {
       const [expired] = await tx<{ id: string }[]>`UPDATE approvals.requests SET status='expired'
-        WHERE id=${id}::uuid AND status='pending' AND expires_at <= now() RETURNING id`;
+        WHERE id=${id}::uuid AND status='pending'
+          AND (expires_at <= now() OR approver_auth_epoch IS DISTINCT FROM ${decider.epoch}::bigint) RETURNING id`;
       return { ok: false, code: expired || !rejectOnly ? "EXPIRED" : "REJECT_ONLY" };
     }
     if (
@@ -194,7 +208,7 @@ export const decide = async (
 
 export type ApprovalConsumeResult =
   | { ok: true }
-  | { ok: false; code: "NOT_FOUND" | "NOT_APPROVED" | "ALREADY_CONSUMED" | "INPUT_CHANGED" | "REVIEW_CHANGED" };
+  | { ok: false; code: "NOT_FOUND" | "NOT_APPROVED" | "ALREADY_CONSUMED" | "INPUT_CHANGED" | "REVIEW_CHANGED" | "REVOKED" };
 export const consume = async (
   id: string,
   input: { input: unknown; review: CapabilityActionReview | null; requester: { kind: ApprovalRequesterKind; ref: string } },
@@ -203,11 +217,26 @@ export const consume = async (
   const argsDigest = approvalArgsDigest(input.input),
     reviewDigest = approvalReviewDigest(input.review);
   return transaction(db, async (tx): Promise<ApprovalConsumeResult> => {
+    const [initial] = await tx<ApprovalRequest[]>`SELECT ${columns()} FROM approvals.requests
+      WHERE id=${id}::uuid AND requester_kind=${input.requester.kind} AND requester_ref=${input.requester.ref}`;
+    if (!initial) return { ok: false, code: "NOT_FOUND" };
+    if (initial.status === "consumed") return { ok: false, code: "ALREADY_CONSUMED" };
+    if (initial.status !== "approved") return { ok: false, code: "NOT_APPROVED" };
+    const decider = await lockDecider(tx, initial.approverUserId, initial.decidedDeviceId);
     const [row] = await tx<ApprovalRequest[]>`SELECT ${columns()} FROM approvals.requests
       WHERE id=${id}::uuid AND requester_kind=${input.requester.kind} AND requester_ref=${input.requester.ref} FOR UPDATE`;
     if (!row) return { ok: false, code: "NOT_FOUND" };
     if (row.status === "consumed") return { ok: false, code: "ALREADY_CONSUMED" };
     if (row.status !== "approved") return { ok: false, code: "NOT_APPROVED" };
+    if (
+      (row.decidedVia === "cloud_login" && row.decidedDeviceId === null) ||
+      (row.decidedDeviceId !== null && !decider.deviceActive) ||
+      row.approverAuthEpoch === null ||
+      row.approverAuthEpoch !== decider.epoch
+    ) {
+      await tx`UPDATE approvals.requests SET status='cancelled' WHERE id=${id}::uuid AND status='approved'`;
+      return { ok: false, code: "REVOKED" };
+    }
     if (row.argsDigest !== argsDigest || row.reviewDigest !== reviewDigest) {
       await tx`UPDATE approvals.requests SET status='cancelled' WHERE id=${id}::uuid AND status='approved'`;
       return { ok: false, code: row.argsDigest !== argsDigest ? "INPUT_CHANGED" : "REVIEW_CHANGED" };

package/src/services/approvals/list.ts

@@ -33,6 +33,7 @@ export type PendingApprovalRow = {
 // Start with this person's indexed pending rows; a Studio page alone cannot continue a chat.
 const openRequests = (approverUserId: string, id?: string) => sql`SELECT r.* FROM approvals.requests r
   WHERE r.approver_user_id=${approverUserId}::uuid AND r.status='pending' AND r.expires_at > now()
+    AND r.approver_auth_epoch=(SELECT auth_epoch FROM auth.users WHERE id=${approverUserId}::uuid)
     AND (${id ?? null}::uuid IS NULL OR r.id=${id ?? null}::uuid)
     AND EXISTS (SELECT 1 FROM ai.pending_actions p WHERE p.approval_id=r.id AND p.status='pending')`;
 const matches = (appId?: string, link?: string) => sql`

package/src/services/approvals/migrate.ts

@@ -38,4 +38,14 @@ export const migrateApprovals = async (): Promise<void> => {
   END $$`.simple();
   await sql`CREATE INDEX IF NOT EXISTS approvals_requests_pending ON approvals.requests(approver_user_id, created_at) WHERE status='pending'`.simple();
   await sql`CREATE INDEX IF NOT EXISTS approvals_requests_expiry ON approvals.requests(expires_at)`.simple();
+  await sql`ALTER TABLE approvals.requests ADD COLUMN IF NOT EXISTS decided_device_id UUID`.simple();
+  // Backfill pending rows once at column creation; approved rows and older-release rows keep NULL and count as ended.
+  await sql`DO $$ BEGIN
+    IF NOT EXISTS (SELECT 1 FROM information_schema.columns
+      WHERE table_schema='approvals' AND table_name='requests' AND column_name='approver_auth_epoch') THEN
+      ALTER TABLE approvals.requests ADD COLUMN approver_auth_epoch BIGINT;
+      UPDATE approvals.requests r SET approver_auth_epoch=u.auth_epoch FROM auth.users u
+        WHERE u.id=r.approver_user_id AND r.status='pending';
+    END IF;
+  END $$`.simple();
 };

package/src/services/network-security.ts

@@ -1,5 +1,6 @@
 import { lookup as dnsLookup } from "node:dns/promises";
-import { isUnsafeNetworkAddress, isUnsafeNetworkHostname, networkAddressFamily, normalizeNetworkHostname } from "../shared/network-address";
+import type { LookupFunction } from "node:net";
+import { isUnsafeNetworkAddress, isUnsafeNetworkHostname, normalizeNetworkHostname, parseNetworkAddress } from "../shared/network-address";
 
 export type PublicNetworkAddress = { address: string; family: 4 | 6 };
 export type NetworkLookup = (
@@ -7,25 +8,48 @@ export type NetworkLookup = (
   options: { all: true; verbatim: true },
 ) => Promise<Array<{ address: string; family: number }>>;
 
+export class NetworkTargetBlockedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "NetworkTargetBlockedError";
+  }
+}
+
 export const resolvePublicNetworkAddresses = async (
   rawHostname: string,
   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");
+  if (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");
+    throw new NetworkTargetBlockedError("Network target resolved to a private or reserved address");
   }
   return normalized;
 };
+
+/** 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/services/pdf/markdown.ts

@@ -127,19 +127,23 @@ hr { border: 0; border-top: 1px solid #d1d5db; margin: .9em 0; }
 };
 
 /**
- * Markdown info blocks print as the calm NoticeCard: a light tint per tone, no
- * border, and the preset's own text colour, so they stay readable on paper.
+ * Markdown callouts print with a light tint and no border. The inline icon
+ * and title use print-safe tone ink; the body keeps the preset's text colour.
  * The tints are a step stronger than on screen because paper and printers wash
  * them out. Every preset and application document shares them.
  */
 const INFO_BLOCK_PRINT_CSS = `
 .k2b-sr-only { position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
 .k2b-notice-card { margin: 0 0 1em; padding: .85em 1.05em; border-radius: .8em; background: var(--notice-tint); break-inside: avoid; print-color-adjust: exact; -webkit-print-color-adjust: exact; }
-.k2b-notice-card[data-tone="neutral"] { --notice-tint: #f1f2f4; }
-.k2b-notice-card[data-tone="info"] { --notice-tint: #e9f1fe; }
-.k2b-notice-card[data-tone="success"] { --notice-tint: #e6f6ee; }
-.k2b-notice-card[data-tone="warning"] { --notice-tint: #fcf2da; }
-.k2b-notice-card[data-tone="danger"] { --notice-tint: #fcebeb; }
+.k2b-notice-card[data-tone="neutral"] { --notice-tint: #f1f2f4; --notice-ink: #4b5563; }
+.k2b-notice-card[data-tone="info"] { --notice-tint: #e9f1fe; --notice-ink: #1d4ed8; }
+.k2b-notice-card[data-tone="success"] { --notice-tint: #e6f6ee; --notice-ink: #15803d; }
+.k2b-notice-card[data-tone="warning"] { --notice-tint: #fcf2da; --notice-ink: #92400e; }
+.k2b-notice-card[data-tone="danger"] { --notice-tint: #fcebeb; --notice-ink: #b91c1c; }
+.k2b-callout { display: grid; grid-template-columns: 1.25em minmax(0, 1fr); column-gap: .7em; }
+.k2b-callout > * { grid-column: 2; }
+.k2b-callout > .k2b-callout__icon { grid-column: 1; grid-row: 1 / span 2; width: 1.25em; height: 1lh; color: var(--notice-ink); }
+.k2b-callout > .k2b-notice-card__title { color: var(--notice-ink); }
 .k2b-notice-card__title { margin: 0 0 .25em; font-weight: 600; }
 .k2b-notice-card__body > :first-child { margin-top: 0; }
 .k2b-notice-card__body > :last-child { margin-bottom: 0; }

package/src/services/pwa-devices.ts

@@ -1,6 +1,7 @@
 import { timingSafeEqual } from "node:crypto";
 import { type SQL, sql } from "bun";
 import type { Context } from "hono";
+import { lazySync } from "../_internal/process-sync";
 import { PWA_LIMITS as limits, type PwaDeviceView, type PwaErrorCode, type PwaPairingState, type PwaPlatform } from "../contracts/pwa";
 import { isAccountCategoryAllowed } from "./account-category-policy";
 import { audit } from "./audit";
@@ -30,6 +31,13 @@ const fail = (code: PwaErrorCode, status: PwaError["status"], attemptsLeft?: num
 
 /** The initiating web session of a pairing. */
 export type PwaWebActor = { userId: string; sid: string };
+/** Best-effort wake-ups for browsers waiting on a pairing claim. Postgres stays authoritative. */
+export type PwaPairingClaimHints = {
+  /** Call after the claim commits. Must not throw or delay the caller. */
+  publish(pairingId: string): void;
+  /** Settles on the first hint for this pairing, or when `signal` aborts. */
+  wait(pairingId: string, signal: AbortSignal): Promise<void>;
+};
 /** Administration of another account's phones needs current admin authority. */
 export type PwaDeviceAdministrator = { userId: string; admin: boolean };
 export type PwaRevocationReason = "user" | "unpaired" | "admin" | "replaced" | "account_expired";
@@ -87,6 +95,25 @@ type UserRow = {
 };
 
 const log = logger("pwa-devices");
+const claimTopic = lazySync((sync) =>
+  sync.topic<null>({
+    id: "cloud:pwa-pairing-claims",
+    owner: "cloud",
+    retention: { maxAgeMs: 120_000, maxBytes: 1_048_576 },
+    maxPayloadBytes: 2000,
+  }),
+);
+/** Core NATS broadcast reaches the waiting browser on any replica. */
+export const syncPairingClaimHints: PwaPairingClaimHints = {
+  publish: (pairingId) => {
+    void Promise.resolve()
+      .then(() => claimTopic().publish({ tenantId: pairingId, data: null }))
+      .catch((error) => log.warn("App pairing claim hint failed", { error: error instanceof Error ? error.name : "UnknownError" }));
+  },
+  wait: async (pairingId, signal) => {
+    for await (const _event of claimTopic().live({ tenantId: pairingId, signal })) return;
+  },
+};
 const iso = (value: Date | string) => new Date(value).toISOString();
 const passed = (value: Date | string) => new Date(value).getTime() <= Date.now();
 const DEVICE_KEY = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.([A-Za-z0-9_-]{43})$/;
@@ -243,7 +270,7 @@ export type PwaCompletion =
   | { state: "paired"; credentials: PwaCredentials | null; platform: PwaPlatform }
   | { state: "waiting"; code: string; account: { name: string }; expiresAt: string };
 
-export const createPwaDeviceService = () => {
+export const createPwaDeviceService = (hints: PwaPairingClaimHints = syncPairingClaimHints) => {
   const appSession = (deviceId: string) => ({ ttlSeconds: limits.sessionSeconds, pwaDeviceId: deviceId, recordLogin: false });
 
   /**
@@ -334,21 +361,46 @@ export const createPwaDeviceService = () => {
     },
 
     /** Never returns the code: the person types what the phone shows. */
-    inspectPairing: async (actor: PwaWebActor, id: string) => {
-      const [p] = await sql<(PairingRow & { current_epoch: string })[]>`
-        SELECT p.*, u.auth_epoch AS current_epoch FROM auth.pwa_pairings p JOIN auth.users u ON u.id = p.user_id
-        WHERE p.id = ${id}::uuid AND p.user_id = ${actor.userId}::uuid AND p.initiator_sid = ${actor.sid}::uuid
-      `;
-      if (!p) return fail("NOT_FOUND", 404);
-      if (passed(p.expires_at) || p.current_epoch !== p.auth_epoch || (p.state === "pending" && passed(p.claim_until)))
-        return fail("EXPIRED", 410);
-      return {
-        state: p.state,
-        claimUntil: iso(p.claim_until),
-        expiresAt: iso(p.expires_at),
-        device: p.state === "pending" || !p.device_name || !p.platform ? null : { name: p.device_name, platform: p.platform },
-        attemptsLeft: Math.max(0, limits.confirmAttempts - p.failed_attempts),
+    inspectPairing: async (actor: PwaWebActor, id: string, hold?: { ms: number; signal?: AbortSignal }) => {
+      const read = async (validateInitiator = false) => {
+        const [p] = await sql<(PairingRow & { current_epoch: string })[]>`
+          SELECT p.*, u.auth_epoch AS current_epoch FROM auth.pwa_pairings p JOIN auth.users u ON u.id = p.user_id
+          WHERE p.id = ${id}::uuid AND p.user_id = ${actor.userId}::uuid AND p.initiator_sid = ${actor.sid}::uuid
+        `;
+        if (!p) return fail("NOT_FOUND", 404);
+        if (passed(p.expires_at) || p.current_epoch !== p.auth_epoch || (p.state === "pending" && passed(p.claim_until)))
+          return fail("EXPIRED", 410);
+        if (validateInitiator && !(await initiatorValid(sql, p))) return fail("EXPIRED", 410);
+        return {
+          state: p.state,
+          claimUntil: iso(p.claim_until),
+          expiresAt: iso(p.expires_at),
+          device: p.state === "pending" || !p.device_name || !p.platform ? null : { name: p.device_name, platform: p.platform },
+          attemptsLeft: Math.max(0, limits.confirmAttempts - p.failed_attempts),
+        };
       };
+      if (!hold) return read();
+      // Listen before the first read so a claim committed in between usually wakes this request.
+      // live() has no subscription-ready barrier, so the hint is best effort; the deadline re-read is the guarantee.
+      // The read after the hold also checks the initiating web session, which may have ended meanwhile.
+      const waiting = new AbortController();
+      const ended = new Promise((resolve) => waiting.signal.addEventListener("abort", resolve, { once: true }));
+      const stop = () => waiting.abort();
+      hold.signal?.addEventListener("abort", stop, { once: true });
+      if (hold.signal?.aborted) stop();
+      const hint = hints.wait(id, waiting.signal).catch(() => {});
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      try {
+        const first = await read();
+        if (first.state !== "pending") return first;
+        timer = setTimeout(stop, Math.min(hold.ms, new Date(first.claimUntil).getTime() - Date.now()));
+        await Promise.race([hint, ended]);
+        return await read(true);
+      } finally {
+        clearTimeout(timer);
+        hold.signal?.removeEventListener("abort", stop);
+        stop();
+      }
     },
 
     confirmPairing: async (actor: PwaWebActor, id: string, code: string) => {
@@ -438,6 +490,7 @@ export const createPwaDeviceService = () => {
           WHERE id = ${p.id}::uuid`;
         return { account: { name: accountName(user) }, expiresAt: p.expires_at };
       });
+      hints.publish(snapshot.id);
       return { code, account: result.account, expiresAt: iso(result.expiresAt), completionSecret };
     },
 

package/src/shared/app-presentation.ts

@@ -26,7 +26,22 @@ const mergedTranslation = (catalog: AppPresentationCatalog, requestedLocale: str
       widgets: Object.fromEntries(
         [...new Set([...Object.keys(current.widgets ?? {}), ...Object.keys(next.widgets ?? {})])].map((id) => [
           id,
-          { ...current.widgets?.[id], ...next.widgets?.[id] },
+          {
+            ...current.widgets?.[id],
+            ...next.widgets?.[id],
+            settings: Object.fromEntries(
+              [...new Set([...Object.keys(current.widgets?.[id]?.settings ?? {}), ...Object.keys(next.widgets?.[id]?.settings ?? {})])].map(
+                (name) => [
+                  name,
+                  {
+                    ...current.widgets?.[id]?.settings?.[name],
+                    ...next.widgets?.[id]?.settings?.[name],
+                    options: { ...current.widgets?.[id]?.settings?.[name]?.options, ...next.widgets?.[id]?.settings?.[name]?.options },
+                  },
+                ],
+              ),
+            ),
+          },
         ]),
       ),
     };
@@ -65,6 +80,39 @@ export const resolveAppPresentation = <T extends AppMeta>(app: T, requestedLocal
       ...widget,
       title: translation.widgets?.[widget.id]?.title ?? widget.title,
       description: translation.widgets?.[widget.id]?.description ?? widget.description,
+      ...(widget.settings && typeof widget.settings === "object" && !Array.isArray(widget.settings)
+        ? {
+            settings: Object.fromEntries(
+              Object.entries(widget.settings).map(([name, field]) => {
+                if (!field || typeof field !== "object") return [name, field];
+                const translated = translation.widgets?.[widget.id]?.settings?.[name];
+                return [
+                  name,
+                  {
+                    ...field,
+                    label: translated?.label ?? field.label,
+                    ...(field.kind === "text" ? { placeholder: translated?.placeholder ?? field.placeholder } : {}),
+                    ...(field.kind === "choice" && Array.isArray(field.options)
+                      ? {
+                          options: field.options.map((option) =>
+                            option && typeof option === "object"
+                              ? {
+                                  ...option,
+                                  label:
+                                    translated?.options && Object.hasOwn(translated.options, option.value)
+                                      ? (translated.options[option.value] ?? option.label)
+                                      : option.label,
+                                }
+                              : option,
+                          ),
+                        }
+                      : {}),
+                  },
+                ];
+              }),
+            ),
+          }
+        : {}),
     })),
   };
 };

package/src/shared/index.ts

@@ -44,6 +44,7 @@ export * from "./locale";
 export * from "./locale-preference";
 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 type { MockCover, MockCoverIcon, MockCoverOptions, MockCoverTheme } from "./mock-cover";

package/src/shared/markdown/callout-sanitizer.ts

@@ -0,0 +1,37 @@
+import { MARKDOWN_CALLOUT_ICON_ATTRIBUTES } from "@k2b/ui";
+import type sanitizeHtml from "sanitize-html";
+
+/** Fresh sanitize-html options for one document: SVG is limited to fixed callout icons. */
+export const markdownCalloutSanitizeOptions = () => {
+  const elements: { inIcon: boolean; discard: boolean }[] = [];
+  let closed: { inIcon: boolean; discard: boolean } | undefined;
+  return {
+    allowedTags: ["svg", "path"],
+    allowedAttributes: { svg: Object.keys(MARKDOWN_CALLOUT_ICON_ATTRIBUTES), path: ["d"] },
+    // onOpenTag sees raw attributes before transforms; discarded SVG must keep ordinary HTML and text.
+    onOpenTag: (tag, attrs) => {
+      const parent = elements.at(-1);
+      elements.push({
+        inIcon: !!parent?.inIcon || (tag === "svg" && attrs.class === MARKDOWN_CALLOUT_ICON_ATTRIBUTES.class),
+        discard: !!parent?.discard || (!!parent?.inIcon && tag !== "path"),
+      });
+    },
+    // sanitize-html closes a tag before calling exclusiveFilter for that element.
+    onCloseTag: () => {
+      closed = elements.pop();
+    },
+    // excludeTag preserves ordinary content, including after an unclosed author SVG.
+    exclusiveFilter: ({ tag }) => closed?.discard || ((tag === "svg" || tag === "path") && !closed?.inIcon ? "excludeTag" : false),
+    textFilter: (text) => (elements.at(-1)?.inIcon ? "" : text),
+    transformTags: {
+      svg: (tagName) => ({
+        tagName,
+        attribs: { ...MARKDOWN_CALLOUT_ICON_ATTRIBUTES },
+      }),
+      path: (tagName, attrs) => ({
+        tagName,
+        attribs: Object.fromEntries(Object.entries(attrs).filter(([name]) => name === "d")),
+      }),
+    },
+  } satisfies sanitizeHtml.IOptions;
+};

package/src/shared/markdown/index.ts

@@ -8,6 +8,7 @@
 import { markdownInfoBlocks } from "@k2b/ui";
 import { Marked, type MarkedExtension } from "marked";
 import sanitizeHtml from "sanitize-html";
+import { markdownCalloutSanitizeOptions } from "./callout-sanitizer";
 import { markdownClient } from "./client";
 import { codeExtension, plainCodeExtension } from "./extensions/code";
 import { guidedHelpExtension } from "./extensions/guided-help";
@@ -73,8 +74,10 @@ export type MarkdownRenderOptions = {
   locale?: string;
 };
 
-const sanitizeRenderedHtml = (html: string): string =>
-  sanitizeHtml(html, {
+const sanitizeRenderedHtml = (html: string): string => {
+  const callouts = markdownCalloutSanitizeOptions();
+  return sanitizeHtml(html, {
+    ...callouts,
     allowedTags: [
       ...sanitizeHtml.defaults.allowedTags,
       "annotation",
@@ -101,6 +104,7 @@ const sanitizeRenderedHtml = (html: string): string =>
       "mtext",
       "semantics",
       "span",
+      ...callouts.allowedTags,
       "sub",
       "sup",
       "table",
@@ -129,6 +133,7 @@ const sanitizeRenderedHtml = (html: string): string =>
       input: ["checked", "class", "disabled", "type"],
       math: ["xmlns"],
       pre: ["class"],
+      ...callouts.allowedAttributes,
       span: ["aria-hidden", "class", "style", "title"],
     },
     allowedSchemes: ["http", "https", "mailto", "tel", "note", "attach"],
@@ -150,6 +155,7 @@ const sanitizeRenderedHtml = (html: string): string =>
       },
     },
   });
+};
 
 /**
  * Render markdown to HTML for server-side display.