@k2b/cloud 0.30.0 → 0.32.0

package/src/services/approvals/index.ts

@@ -0,0 +1,241 @@
+import { type SQL, sql } from "bun";
+import { capabilityRequestHash } from "../../capabilities/claims";
+import { APPROVAL_ACP_CLIENT } from "../../contracts/approvals";
+import type { CapabilityActionReview } from "../../contracts/capabilities";
+import { isAppSessionActor } from "../../server/actor";
+import type { RequestActor, RequestCredentialKind } from "../../server/middleware/auth";
+import { audit } from "../audit";
+import { toPgTextArray } from "../postgres";
+
+export { countPending, listPending, presentPendingApproval } from "./list";
+export { migrateApprovals } from "./migrate";
+
+// Derived from chat's AI_ACTION_BUDGET_MS and Studio's one-day abandonment of pending calls.
+export const APPROVAL_MAX_WAIT_MS = 24 * 60 * 60_000;
+export type ApprovalDecisionChannel = "web_session" | "app_session" | "oauth" | "api_key" | "invocation" | "acp_bridge" | "cloud_login";
+export type ApprovalRequesterKind = "assistant_turn" | "studio_app";
+export type ApprovalStatus = "pending" | "approved" | "rejected" | "expired" | "cancelled" | "consumed";
+export type ApprovalAssurance = "standard" | "confirm";
+
+/**
+ * `standard` when the person may remember the approval of this call: an Action with `approval: "rememberable"` whose
+ * review names a scope for these arguments, a tool whose policy allows remembering, or a website. Otherwise `confirm`.
+ */
+export const approvalAssurance = (rememberable: boolean): ApprovalAssurance => (rememberable ? "standard" : "confirm");
+export const approvalArgsDigest = (input: unknown): string => capabilityRequestHash(input);
+export const approvalReviewDigest = (review: CapabilityActionReview | null | undefined): string => capabilityRequestHash(review ?? null);
+export const approvalDecisionChannel = (input: {
+  credentialKind?: RequestCredentialKind;
+  actor?: RequestActor;
+  client?: string | null;
+}): ApprovalDecisionChannel =>
+  input.client === APPROVAL_ACP_CLIENT
+    ? "acp_bridge"
+    : input.credentialKind === "session"
+      ? isAppSessionActor(input.actor)
+        ? "app_session"
+        : "web_session"
+      : (input.credentialKind ?? "invocation");
+export const approvalScopeFromToolName = (name: string): { appId: string; action: string } => {
+  const dot = name.indexOf(".");
+  return dot < 0 ? { appId: "assistant", action: name } : { appId: name.slice(0, dot), action: name.slice(dot + 1) };
+};
+
+export type ApprovalRequestInput = {
+  appId: string;
+  action: string;
+  approvalScope?: string | null;
+  requester: { kind: ApprovalRequesterKind; ref: string; appId: string; title?: string | null };
+  subjectId: string;
+  approverUserId: string;
+  assurance: ApprovalAssurance;
+  sentence: string;
+  review?: CapabilityActionReview | null;
+  input: unknown;
+  expiresInMs: number;
+};
+export type ApprovalRequest = {
+  id: string;
+  appId: string;
+  action: string;
+  approvalScope: string | null;
+  requesterKind: ApprovalRequesterKind;
+  requesterRef: string;
+  requesterAppId: string;
+  requesterTitle: string | null;
+  subjectId: string;
+  approverUserId: string;
+  assurance: ApprovalAssurance;
+  sentence: string;
+  details: CapabilityActionReview | null;
+  argsDigest: string;
+  reviewDigest: string;
+  status: ApprovalStatus;
+  decidedVia: ApprovalDecisionChannel | null;
+  decidedAt: Date | null;
+  consumedAt: Date | null;
+  createdAt: Date;
+  expiresAt: Date;
+};
+// SQL aliases keep the public row shape identical for reads and locked transaction reads. A function, because a
+// fragment built at import time would bind the default sql handle before a test can choose its database.
+const columns = () => sql`id, app_id AS "appId", action, approval_scope AS "approvalScope",
+  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_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));
+
+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
+ * open request unchanged: its snapshot is what the person may already see, so a changed effect fails `consume` and
+ * asks again instead of rebinding that decision. A reference whose request is decided, expired, or another person's
+ * is a conflict.
+ */
+export const request = async (input: ApprovalRequestInput, db?: SQL): Promise<ApprovalRequestResult> => {
+  // Zero or less records a request that is already expired, such as a call that waited too long before the upgrade.
+  const expiresInMs = Number.isNaN(input.expiresInMs)
+    ? APPROVAL_MAX_WAIT_MS
+    : Math.max(0, Math.min(input.expiresInMs, APPROVAL_MAX_WAIT_MS));
+  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)
+      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,
+        ${approvalArgsDigest(input.input)}, ${approvalReviewDigest(input.review)}, now() + (${expiresInMs} * interval '1 millisecond'))
+      ON CONFLICT (requester_kind, requester_ref) DO NOTHING
+      RETURNING id
+    `;
+    if (row) return { ok: true, id: row.id };
+    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_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" };
+  });
+};
+
+export const get = async (id: string, db?: SQL): Promise<ApprovalRequest | null> =>
+  transaction(db, async (tx) => {
+    const [row] = await tx<ApprovalRequest[]>`SELECT ${columns()} FROM approvals.requests WHERE id=${id}::uuid`;
+    return row ?? null;
+  });
+
+export type ApprovalDecisionResult =
+  | { ok: true; status: ApprovalStatus; replay: boolean }
+  | { ok: false; code: "EXPIRED" | "NOT_FOUND" | "REJECT_ONLY" }
+  | { ok: false; code: "ALREADY_DECIDED"; status: ApprovalStatus };
+export const decide = async (
+  id: string,
+  decision: { approved: boolean },
+  actor: { userId: string; via: ApprovalDecisionChannel; deviceId?: string },
+  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" };
+    }
+    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" };
+    const rejectOnly = decision.approved && row.assurance === "confirm" && actor.via === "acp_bridge";
+    const status = decision.approved ? "approved" : "rejected";
+    const [won] = rejectOnly
+      ? []
+      : await tx<ApprovalRequest[]>`
+      UPDATE approvals.requests SET status=${status}, decided_via=${actor.via}, decided_at=now()
+      WHERE id=${id}::uuid AND approver_user_id=${actor.userId}::uuid AND status='pending' AND expires_at > now()
+      RETURNING ${columns()}
+    `;
+    if (won) {
+      await audit.record(
+        {
+          action: decision.approved ? "auth.action.approve" : "auth.action.deny",
+          outcome: "allowed",
+          actor: { userId: actor.userId },
+          target: { type: "approval_request", id, label: `${won.appId}.${won.action}` },
+          metadata: {
+            appId: won.appId,
+            action: won.action,
+            assurance: won.assurance,
+            decidedVia: actor.via,
+            ...(actor.deviceId !== undefined ? { deviceId: actor.deviceId } : {}),
+            requesterKind: won.requesterKind,
+            requesterAppId: won.requesterAppId,
+          },
+        },
+        tx,
+      );
+      return { ok: true, status, replay: false };
+    }
+    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`;
+      return { ok: false, code: expired || !rejectOnly ? "EXPIRED" : "REJECT_ONLY" };
+    }
+    if (
+      (decision.approved && (row.status === "approved" || row.status === "consumed")) ||
+      (!decision.approved && row.status === "rejected")
+    )
+      return { ok: true, status: row.status, replay: true };
+    return { ok: false, code: "ALREADY_DECIDED", status: row.status };
+  });
+  // Publish a later NATS decision hint only after the owning transaction commits.
+  return result;
+};
+
+export type ApprovalConsumeResult =
+  | { ok: true }
+  | { ok: false; code: "NOT_FOUND" | "NOT_APPROVED" | "ALREADY_CONSUMED" | "INPUT_CHANGED" | "REVIEW_CHANGED" };
+export const consume = async (
+  id: string,
+  input: { input: unknown; review: CapabilityActionReview | null; requester: { kind: ApprovalRequesterKind; ref: string } },
+  db?: SQL,
+): Promise<ApprovalConsumeResult> => {
+  const argsDigest = approvalArgsDigest(input.input),
+    reviewDigest = approvalReviewDigest(input.review);
+  return transaction(db, async (tx): Promise<ApprovalConsumeResult> => {
+    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.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" };
+    }
+    await tx`UPDATE approvals.requests SET status='consumed', consumed_at=now() WHERE id=${id}::uuid AND status='approved'
+      AND requester_kind=${input.requester.kind} AND requester_ref=${input.requester.ref}
+      AND args_digest=${argsDigest} AND review_digest=${reviewDigest}`;
+    return { ok: true };
+  });
+};
+
+export const cancel = async (ids: string[], db?: SQL): Promise<void> => {
+  if (!ids.length) return;
+  await transaction(db, async (tx) => {
+    await tx`UPDATE approvals.requests SET status='cancelled' WHERE id=ANY(${toPgTextArray(ids)}::uuid[]) AND status IN ('pending','approved')`;
+  });
+};
+
+export const pruneApprovalRequests = async (before: Date): Promise<number> => {
+  let total = 0;
+  let deleted: number;
+  do {
+    const result = await sql`WITH expired AS (SELECT id FROM approvals.requests WHERE expires_at < ${before} LIMIT 5000)
+      DELETE FROM approvals.requests request USING expired WHERE request.id=expired.id`;
+    deleted = result.count;
+    total += deleted;
+  } while (deleted === 5000);
+  return total;
+};
+
+export const approvals = { request, get, decide, consume, cancel };

package/src/services/approvals/list.ts

@@ -0,0 +1,120 @@
+import { sql } from "bun";
+import { AI_WEBSITE_APPROVAL_TOOL, aiTurnAllowsRememberedApprovals } from "../../ai/approvals";
+import type { AiTurnRunConfig } from "../../ai/types";
+import type { RuntimeAppMeta } from "../../contracts/app";
+import { APPROVALS_PAGE_SIZE, type ApprovalCounts, type PendingApproval } from "../../contracts/approvals";
+import { CapabilityActionReviewSchema } from "../../contracts/capabilities";
+import type { ApprovalAssurance } from ".";
+import { decodeApprovalCursor, encodeApprovalCursor } from "./cursor";
+
+export type PendingApprovalRow = {
+  id: string;
+  appId: string;
+  action: string;
+  argsDigest: string;
+  requesterAppId: string;
+  /** The chat title when Cloud asked; unlike `conversationTitle`, a later rename does not change it. */
+  requesterTitle: string | null;
+  assurance: ApprovalAssurance;
+  sentence: string;
+  details: unknown;
+  createdAt: Date;
+  expiresAt: Date;
+  cursorCreatedAt: string;
+  conversationShortId: string;
+  conversationTitle: string | null;
+  allowChat: boolean | null;
+  allowAlways: boolean;
+  rememberToolName: string | null;
+  toolName: string;
+  runConfig: AiTurnRunConfig | null;
+};
+
+// 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 (${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`
+  (${appId ?? null}::text IS NULL OR r.app_id=${appId ?? null} OR r.requester_app_id=${appId ?? null})
+  AND (${link ?? null}::text IS NULL OR COALESCE(r.details->'links' @> jsonb_build_array(jsonb_build_object('href', ${link ?? null}::text)),false))`;
+
+export const listPending = async (input: {
+  approverUserId: string;
+  id?: string;
+  appId?: string;
+  link?: string;
+  cursor?: string;
+  limit?: number;
+}): Promise<{ items: PendingApprovalRow[]; nextCursor: string | null; count: number; elsewhere: number }> => {
+  const limit = input.limit ?? APPROVALS_PAGE_SIZE;
+  if (!Number.isInteger(limit) || limit < 1 || limit > APPROVALS_PAGE_SIZE) throw new RangeError("Invalid approval page size.");
+  const cursor = input.cursor ? decodeApprovalCursor(input.cursor) : null;
+  if (input.cursor && !cursor) throw new RangeError("Invalid approval cursor.");
+  const [counts] = await sql<{ count: number; elsewhere: number }[]>`WITH open AS (${openRequests(input.approverUserId, input.id)})
+    SELECT count(*) FILTER (WHERE ${matches(input.appId, input.link)})::int AS count,
+      count(*) FILTER (WHERE NOT (${matches(input.appId, input.link)}))::int AS elsewhere FROM open r`;
+  const rows = await sql<PendingApprovalRow[]>`WITH open AS (${openRequests(input.approverUserId, input.id)})
+    SELECT r.id, r.app_id AS "appId", r.action, r.requester_app_id AS "requesterAppId", r.requester_title AS "requesterTitle", r.assurance, r.sentence, r.details, r.args_digest AS "argsDigest",
+      r.created_at AS "createdAt", r.expires_at AS "expiresAt",
+      to_char(r.created_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"') AS "cursorCreatedAt",
+      question.short_id AS "conversationShortId", question.title AS "conversationTitle",
+      question.allow_chat AS "allowChat", question.allow_always AS "allowAlways",
+      question.remember_tool_name AS "rememberToolName", question.tool_name AS "toolName", question.run_config AS "runConfig"
+    FROM open r JOIN LATERAL (
+      SELECT c.short_id, c.title, p.allow_chat, p.allow_always, p.remember_tool_name, p.tool_name, t.run_config
+      FROM ai.pending_actions p JOIN ai.conversations c ON c.id=p.conversation_id JOIN ai.turns t ON t.id=p.turn_id
+      WHERE p.approval_id=r.id AND p.status='pending' ORDER BY p.created_at DESC, p.id DESC LIMIT 1
+    ) question ON true
+    WHERE ${matches(input.appId, input.link)}
+      AND (${cursor?.id ?? null}::uuid IS NULL OR (r.created_at,r.id) < (${cursor?.createdAt ?? null}::timestamptz,${cursor?.id ?? null}::uuid))
+    ORDER BY r.created_at DESC,r.id DESC LIMIT ${limit + 1}`;
+  const items = rows.slice(0, limit);
+  const last = items.at(-1);
+  return {
+    items,
+    nextCursor: rows.length > limit && last ? encodeApprovalCursor({ createdAt: last.cursorCreatedAt, id: last.id }) : null,
+    count: counts?.count ?? 0,
+    elsewhere: counts?.elsewhere ?? 0,
+  };
+};
+
+export const countPending = async (input: { approverUserId: string }): Promise<ApprovalCounts> => {
+  const [row] = await sql<ApprovalCounts[]>`WITH open AS MATERIALIZED (${openRequests(input.approverUserId)}),
+    app_requests AS (SELECT DISTINCT r.id AS request_id, app.id AS app_id FROM open r
+      CROSS JOIN LATERAL unnest(ARRAY[r.app_id,r.requester_app_id]) app(id)),
+    app_counts AS (SELECT app_id AS id,count(*)::int AS count FROM app_requests GROUP BY app_id)
+    SELECT (SELECT count(*)::int FROM open) AS total,
+      COALESCE((SELECT jsonb_object_agg(id,count) FROM app_counts),'{}'::jsonb) AS apps`;
+  return row ?? { total: 0, apps: {} };
+};
+
+export const presentPendingApproval = (
+  row: PendingApprovalRow,
+  apps: readonly Pick<RuntimeAppMeta, "id" | "name" | "icon">[],
+): PendingApproval => {
+  const app = apps.find((entry) => entry.id === row.appId);
+  const review = CapabilityActionReviewSchema.nullable().safeParse(row.details);
+  const remember = row.assurance === "standard" && aiTurnAllowsRememberedApprovals(row.runConfig);
+  return {
+    id: row.id,
+    app: { id: row.appId, name: app?.name ?? row.appId, icon: app?.icon ?? null },
+    action: row.action,
+    assurance: row.assurance,
+    sentence: row.sentence,
+    review: review.success ? review.data : null,
+    requester: {
+      kind: "chat",
+      appId: row.requesterAppId,
+      title: row.conversationTitle,
+      href: `/app/assistant?conversation=${encodeURIComponent(row.conversationShortId)}`,
+    },
+    remember: {
+      chat: remember && (row.allowChat ?? row.allowAlways),
+      always: remember && row.allowAlways,
+      website: (row.rememberToolName ?? row.toolName) === AI_WEBSITE_APPROVAL_TOOL,
+    },
+    createdAt: row.createdAt.toISOString(),
+    expiresAt: row.expiresAt.toISOString(),
+  };
+};

package/src/services/approvals/migrate.ts

@@ -0,0 +1,41 @@
+import { sql } from "bun";
+
+export const migrateApprovals = async (): Promise<void> => {
+  await sql`CREATE SCHEMA IF NOT EXISTS approvals`.simple();
+  await sql`
+    CREATE TABLE IF NOT EXISTS approvals.requests (
+      id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+      app_id TEXT NOT NULL,
+      action TEXT NOT NULL,
+      approval_scope TEXT,
+      requester_kind TEXT NOT NULL CHECK (requester_kind IN ('assistant_turn','studio_app')),
+      requester_ref TEXT NOT NULL,
+      requester_app_id TEXT NOT NULL,
+      requester_title TEXT,
+      subject_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
+      approver_user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
+      assurance TEXT NOT NULL CHECK (assurance IN ('standard','confirm')),
+      sentence TEXT NOT NULL,
+      details JSONB,
+      args_digest TEXT NOT NULL,
+      review_digest TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending','approved','rejected','expired','cancelled','consumed')),
+      decided_via TEXT CHECK (decided_via IS NULL OR decided_via IN ('web_session','app_session','oauth','api_key','invocation','acp_bridge','cloud_login')),
+      decided_at TIMESTAMPTZ,
+      consumed_at TIMESTAMPTZ,
+      created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+      expires_at TIMESTAMPTZ NOT NULL,
+      UNIQUE (requester_kind, requester_ref)
+    )
+  `.simple();
+  await sql`DO $$ BEGIN
+    IF EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid='approvals.requests'::regclass
+      AND conname='requests_decided_via_check' AND position('cloud_login' in pg_get_constraintdef(oid))=0) THEN
+      ALTER TABLE approvals.requests DROP CONSTRAINT requests_decided_via_check;
+      ALTER TABLE approvals.requests ADD CONSTRAINT requests_decided_via_check
+        CHECK (decided_via IS NULL OR decided_via IN ('web_session','app_session','oauth','api_key','invocation','acp_bridge','cloud_login'));
+    END IF;
+  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();
+};

package/src/services/identity/models-only-auth.ts

@@ -0,0 +1,25 @@
+import { AI_INFERENCE_SCOPE, type User } from "../../contracts/shared";
+import { isAccountExpired } from "../account-model";
+import { serviceAccountCredentials } from "../service-account-credentials";
+
+export const authenticateModelsOnlyCredential = async (
+  token: string | null | undefined,
+): Promise<{ user: User; credentialId: string } | null> => {
+  if (!token || !serviceAccountCredentials.isApiToken(token)) return null;
+  const authenticated = await serviceAccountCredentials.authenticateApiToken(token);
+  if (!authenticated) return null;
+  const { credential, serviceAccount, delegatedUser } = authenticated;
+  if (
+    credential.kind !== "api_token" ||
+    credential.status !== "active" ||
+    credential.serviceAccountId !== serviceAccount.id ||
+    serviceAccount.status !== "active" ||
+    serviceAccount.kind !== "user_delegated" ||
+    !delegatedUser ||
+    serviceAccount.delegatedUserId !== delegatedUser.id ||
+    !credential.scopes.includes(AI_INFERENCE_SCOPE) ||
+    isAccountExpired(delegatedUser.accountExpires)
+  )
+    return null;
+  return { user: delegatedUser, credentialId: credential.id };
+};

package/src/services/notifications/email-frame.ts

@@ -1,5 +1,5 @@
 import sanitizeHtml from "sanitize-html";
-import { sanitizeEmailHtml } from "../../shared/email-html";
+import { EMAIL_HTML_SANITIZE_OPTIONS } from "../../shared/email-html";
 import * as settings from "../settings";
 import { coreSettings } from "../settings/api";
 
@@ -8,16 +8,29 @@ const sanitizeContent = (content: string): string => sanitizeHtml(content, { all
 // sanitize-html decodes entities before escaping &, < and > again. Decode only
 // those escapes once, so literal entity text is not recursively interpreted.
 const htmlText = (html: string): string =>
-  sanitizeContent(html.replace(/<br\b[^>]*>|<\/(?:p|div|h[1-6]|li|tr|td|th|ul|ol|table)>/gi, " "))
+  sanitizeContent(html.replace(/<br\b[^>]*>|<\/(?:p|pre|blockquote|div|h[1-6]|li|tr|td|th|ul|ol|table)>/gi, " "))
     .replace(/&(amp|lt|gt);/g, (entity) => (entity === "&amp;" ? "&" : entity === "&lt;" ? "<" : ">"))
     .replace(/\s+/g, " ")
     .trim();
 
+// The frame has no stylesheet, so a `pre` would keep the client default `white-space: pre` and push long
+// lines past the frame. The sender's own style comes last and still wins.
+const frameHtmlOptions = {
+  ...EMAIL_HTML_SANITIZE_OPTIONS,
+  transformTags: {
+    ...EMAIL_HTML_SANITIZE_OPTIONS.transformTags,
+    pre: (tagName, attribs) => ({
+      tagName,
+      attribs: { ...attribs, style: `white-space:pre-wrap;overflow-wrap:break-word;${attribs.style ?? ""}` },
+    }),
+  },
+} satisfies sanitizeHtml.IOptions;
+
 export const prepareNotificationEmail = async (opts: { content?: string; rawHtml?: string }): Promise<{ html: string; text: string }> => {
   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 body = opts.rawHtml ? sanitizeEmailHtml(opts.rawHtml) : opts.content ? `<p>${sanitizeContent(opts.content)}</p>` : "";
+  const body = opts.rawHtml ? sanitizeHtml(opts.rawHtml, frameHtmlOptions) : opts.content ? `<p>${sanitizeContent(opts.content)}</p>` : "";
   return { html: await buildHtml(appUrl, appName, body), text: opts.content ? sanitizeContent(opts.content) : htmlText(body) };
 };
 

package/src/services/service-account-credentials.ts

@@ -1,7 +1,7 @@
 import { createHash, timingSafeEqual } from "node:crypto";
 import { crypto, err, fail, ok, type PageParams, type Paginated, type Result } from "@k2b/stdlib";
 import { type SQL, sql } from "bun";
-import type { User } from "../contracts/shared";
+import { AI_INFERENCE_SCOPE, type User } from "../contracts/shared";
 import { accounts } from "./accounts";
 import { audit } from "./audit";
 import { isUniqueViolation, toPgTextArray } from "./postgres";
@@ -199,12 +199,16 @@ const generateTokenParts = (): { tokenPrefix: string; secret: string; token: str
 };
 
 // API token secrets carry 256 bits of entropy, so a fast digest is sufficient and avoids password-KDF cost per request.
-const hashApiTokenSecret = (secret: string): string => `sha256:${createHash("sha256").update(secret).digest("hex")}`;
+// Domain-separate models-only keys so older platforms fail verification instead of granting full authority.
+const hashApiTokenSecret = (secret: string, scopes: readonly string[]): string =>
+  `sha256:${createHash("sha256")
+    .update(scopes.includes(AI_INFERENCE_SCOPE) ? `${AI_INFERENCE_SCOPE}:${secret}` : secret)
+    .digest("hex")}`;
 
-const verifyApiTokenSecret = async (secret: string, storedHash: string): Promise<boolean> => {
+const verifyApiTokenSecret = async (secret: string, storedHash: string, scopes: readonly string[]): Promise<boolean> => {
   const match = storedHash.match(SECRET_HASH_PATTERN);
   if (match) {
-    const actual = Buffer.from(hashApiTokenSecret(secret).slice("sha256:".length), "hex");
+    const actual = Buffer.from(hashApiTokenSecret(secret, scopes).slice("sha256:".length), "hex");
     const expected = Buffer.from(match[1]!, "hex");
     return timingSafeEqual(actual, expected);
   }
@@ -338,7 +342,7 @@ const insertApiToken = async (
   }
 
   const parts = await generateUniqueTokenParts();
-  const secretHash = hashApiTokenSecret(parts.secret);
+  const secretHash = hashApiTokenSecret(parts.secret, params.scopes ?? []);
 
   try {
     const [row] = await db<DbCredentialRow[]>`
@@ -371,16 +375,20 @@ const insertApiToken = async (
   }
 };
 
-export const createApiToken = (params: {
+export const createApiToken = async (params: {
   serviceAccountId: string;
   name: string;
   createdBy?: string | null;
   expiresAt?: string | null;
   scopes?: string[];
-}): Promise<Result<{ credential: ServiceAccountCredential; token: string }>> => insertApiToken(sql, params);
+}): Promise<Result<{ credential: ServiceAccountCredential; token: string }>> => {
+  if (params.scopes?.includes(AI_INFERENCE_SCOPE)) return fail(err.badInput("ai:inference is reserved for models-only personal API keys"));
+  return insertApiToken(sql, params);
+};
 
 export const createUserApiToken = async (params: {
   user: User;
+  access?: "full" | "models";
   name: string;
   expiresAt?: string | null;
 }): Promise<Result<{ credential: ServiceAccountCredential; token: string }>> => {
@@ -396,6 +404,7 @@ export const createUserApiToken = async (params: {
       name: params.name,
       expiresAt: params.expiresAt,
       createdBy: params.user.id,
+      scopes: params.access === "models" ? [AI_INFERENCE_SCOPE] : [],
     });
 
     return audit.recordResult({
@@ -404,6 +413,7 @@ export const createUserApiToken = async (params: {
       target: { type: "service_account_credential", id: result.ok ? result.data.credential.id : null, label: params.name },
       metadata: {
         serviceAccountId: serviceAccountResult.data.id,
+        access: params.access ?? "full",
         kind: "api_token",
         expiresAt: params.expiresAt ?? null,
       },
@@ -420,6 +430,7 @@ export const createResourceApiToken = async (params: {
   expiresAt?: string | null;
   scopes?: string[];
 }): Promise<Result<{ credential: ServiceAccountCredential; token: string }>> => {
+  if (params.scopes?.includes(AI_INFERENCE_SCOPE)) return fail(err.badInput("ai:inference is reserved for models-only personal API keys"));
   const serviceAccount = await serviceAccounts.get({ id: params.serviceAccountId });
   if (!serviceAccount || serviceAccount.kind !== "resource_bound") return fail(err.notFound("Resource service account"));
   if (serviceAccount.status !== "active") return fail(err.badInput("Resource service account is disabled"));
@@ -460,6 +471,7 @@ export const createStandaloneApiToken = async (params: {
   expiresAt?: string | null;
   scopes?: string[];
 }): Promise<Result<{ credential: ServiceAccountCredential; token: string }>> => {
+  if (params.scopes?.includes(AI_INFERENCE_SCOPE)) return fail(err.badInput("ai:inference is reserved for models-only personal API keys"));
   const serviceAccount = await serviceAccounts.get({ id: params.serviceAccountId });
   if (!serviceAccount || !isStandaloneServiceAccountKind(serviceAccount.kind)) return fail(err.notFound("Service account"));
   if (serviceAccount.status !== "active") return fail(err.badInput("Service account is disabled"));
@@ -780,7 +792,7 @@ const recordSuccessfulAuthentication = async (params: {
   serviceAccount: ServiceAccount;
   delegatedUser: User | null;
 }): Promise<void> => {
-  const upgradedSecretHash = SECRET_HASH_PATTERN.test(params.row.secret_hash) ? null : hashApiTokenSecret(params.secret);
+  const upgradedSecretHash = SECRET_HASH_PATTERN.test(params.row.secret_hash) ? null : hashApiTokenSecret(params.secret, params.row.scopes);
   if (!upgradedSecretHash && !params.row.activity_due) return;
 
   if (upgradedSecretHash) {
@@ -836,10 +848,10 @@ const recordSuccessfulAuthentication = async (params: {
 const pendingSecretVerifications = new Map<string, Promise<boolean>>();
 
 const verifyApiTokenSecretOnce = async (secret: string, row: DbCredentialWithSecretRow): Promise<boolean> => {
-  const key = `${row.id}:${row.secret_hash}:${hashApiTokenSecret(secret)}`;
+  const key = `${row.id}:${row.secret_hash}:${hashApiTokenSecret(secret, row.scopes)}`;
   let pending = pendingSecretVerifications.get(key);
   if (!pending) {
-    pending = verifyApiTokenSecret(secret, row.secret_hash);
+    pending = verifyApiTokenSecret(secret, row.secret_hash, row.scopes);
     pendingSecretVerifications.set(key, pending);
   }
   try {

package/src/services/settings/core-settings.ts

@@ -296,6 +296,13 @@ export const CORE_SETTINGS = {
     placeholder: "Keep answers concise. The current user is {{ user.displayName }} and today is {{ today }}.",
     templateVars: ["user.displayName", "user.uid", "user.mail", "appId", "now", "today", "time"],
   },
+  "ai.local_client_instructions": {
+    kind: "text",
+    label: "Instructions for local clients",
+    default: "",
+    description:
+      "Added to turns from local clients such as cld after the organization instructions. Leave empty to use the built-in text, which improves with each release.",
+  },
   "ai.compaction_instructions": {
     kind: "text",
     label: "Additional Compaction Instructions",
@@ -328,6 +335,26 @@ export const CORE_SETTINGS = {
     description: "Firecrawl API key used by Cloud AI web_search and web_extract tools.",
     placeholder: "fc-...",
   },
+  "ai.openai_api_enabled": {
+    kind: "boolean",
+    label: "OpenAI-compatible API",
+    default: false,
+    description:
+      "Let people create API keys with the access “AI models only” and call the Assistant models they may use. Checked on every request: turning this off stops existing keys too. Models without reference prices have no usage limit; only the rate limit and the concurrent request limit protect them.",
+  },
+  // Default 4: one process runs at most 8 chat turns at once (AI_TURN_WORKER_CONCURRENCY in ai/runtime.ts), and this
+  // synchronous API bypasses that queue, so one person may hold at most half of it. Typical clients need 1-2 (one
+  // request after another plus a connection test); 4 leaves room for a second client without letting a script in a
+  // loop crowd out everyone else. Operators with more provider capacity raise it.
+  "ai.openai_api_max_concurrent_requests": {
+    kind: "number",
+    label: "OpenAI API concurrent requests per person",
+    integer: true,
+    min: 1,
+    max: 64,
+    default: 4,
+    description: "Maximum simultaneous OpenAI-compatible API requests per person across all Cloud instances.",
+  },
   // ── PDF rendering ─────────────────────────────────────────────────────
   "gotenberg.url": {
     kind: "url",