@k2b/cloud 0.6.0-rc.0 → 0.7.0

package/src/services/notifications/platform.ts

@@ -15,7 +15,6 @@ import { encryptSecret } from "../secrets";
 import { ensureNotificationDefinition } from "./catalog";
 import { getNotificationChannel, type NotificationDestination, type ResolvedNotificationRecipient } from "./channels";
 import { processNotificationDelivery } from "./dispatcher";
-import { notificationLive } from "./live";
 import { enqueueNotificationDeliveries, enqueueNotificationDelivery } from "./runtime";
 
 export type TypedNotificationDeliveryStatus = "deferred" | "pending" | "sending" | "delivered" | "suppressed" | "failed";
@@ -406,9 +405,6 @@ export const sendTypedNotification = async <
   });
 
   if (persisted.prepared) {
-    if (resolved.recipient.userId && (requiredChannelSet.has("browser") || preferred.includes("browser"))) {
-      await notificationLive.publish({ userId: resolved.recipient.userId, eventId: identity.id, presentation });
-    }
     for (const deliveryId of persisted.requiredIds) {
       const result = await processNotificationDelivery(deliveryId);
       if (result.status === "retry") await enqueueNotificationDelivery(deliveryId, result.retryAfterMs);

package/src/services/oauth-tokens.ts

@@ -6,7 +6,7 @@ import { isAccountExpired } from "./account-model";
 import { IDENTITY_JWKS_MAX_AGE_SECONDS } from "./identity/constants";
 import { getIdentityRuntimeConfig } from "./identity/runtime-config";
 import type { ServiceAccount } from "./service-accounts";
-import { buildProjectedUser, userProjectionSql } from "./session/user";
+import { buildProjectedUser, userProjectionJoin, userProjectionSql } from "./session/user";
 
 type ServiceAccountActorRow = Record<string, unknown> & {
   service_account_id: string;
@@ -116,7 +116,7 @@ export const resolveOAuthTokenActor = async (
       FROM oauth.clients c
       JOIN auth.service_accounts sa ON sa.id = ${serviceAccountId}::uuid AND sa.status = 'active'
       LEFT JOIN auth.users u ON u.id = sa.delegated_user_id
-      LEFT JOIN auth.user_ipa_data ui ON ui.user_id = u.id
+      ${userProjectionJoin()}
       WHERE c.client_id = ${clientId}
     `;
     const row = rows[0];
@@ -139,7 +139,7 @@ export const resolveOAuthTokenActor = async (
     SELECT ${userProjectionSql(groupsAdmin)}
     FROM oauth.clients c
     JOIN auth.users u ON ${predicate}
-    LEFT JOIN auth.user_ipa_data ui ON ui.user_id = u.id
+    ${userProjectionJoin()}
     WHERE c.client_id = ${clientId}
   `;
   const user = rows[0] ? buildProjectedUser(rows[0]) : null;

package/src/services/pdf/gotenberg.ts

@@ -34,6 +34,18 @@ export type RenderHtmlToPdfInput = {
   headerHtml?: string | null;
   footerHtml?: string | null;
   filename?: string;
+  assets?: Array<{ name: string; data: Blob }>;
+  page?: {
+    format?: "A4" | "A3" | "A5" | "Letter" | "Legal";
+    landscape?: boolean;
+    margin?: { top?: number; right?: number; bottom?: number; left?: number };
+  };
+  tagged?: boolean;
+};
+
+export type AttachPdfFilesInput = {
+  document: Blob;
+  attachments: Array<{ name: string; data: Blob; relationship?: "Source" | "Data" | "Alternative" | "Supplement" | "Unspecified" }>;
 };
 
 export type RenderFacturXHtmlToPdfInput = RenderHtmlToPdfInput & {
@@ -59,6 +71,7 @@ export type GotenbergFetch = (input: string | URL | Request, init?: RequestInit)
 
 export type RenderHtmlToPdfOptions = {
   fetch?: GotenbergFetch;
+  signal?: AbortSignal;
 };
 
 const DEFAULT_PDF_CONTENT_TYPE = "application/pdf";
@@ -105,111 +118,118 @@ const sanitizeFetchError = (error: unknown): GotenbergRenderError => {
   return new GotenbergRenderError("request_failed", "Gotenberg request failed.");
 };
 
-export const renderHtmlToPdfWithConfig = async (
-  input: RenderHtmlToPdfInput,
-  config: GotenbergConfig,
-  options: RenderHtmlToPdfOptions = {},
-): Promise<RenderHtmlToPdfResult> => {
-  const htmlBytes = byteLength(input.html);
-  if (htmlBytes > config.maxHtmlBytes) {
-    throw new GotenbergRenderError("html_too_large", `HTML input is too large (${htmlBytes} bytes, limit ${config.maxHtmlBytes} bytes).`);
-  }
+const dimensions = { A4: [210, 297], A3: [297, 420], A5: [148, 210], Letter: [215.9, 279.4], Legal: [215.9, 355.6] } as const;
+const fileName = (name: string) => {
+  if (!name || name.length > 180 || /[\\/\x00-\x1f]/.test(name) || name === "." || name === "..")
+    throw new GotenbergRenderError("bad_input", "Use a plain filename without directories.");
+  return name;
+};
 
-  const baseUrl = normalizeBaseUrl(config.url);
+function htmlForm(input: RenderHtmlToPdfInput, config: GotenbergConfig): FormData {
+  const total = [input.html, input.headerHtml ?? "", input.footerHtml ?? ""].reduce((sum, value) => sum + byteLength(value), 0)
+    + (input.assets ?? []).reduce((sum, asset) => sum + asset.data.size, 0);
+  if (total > config.maxHtmlBytes) throw new GotenbergRenderError("html_too_large", "HTML and assets exceed the configured input budget.");
   const form = new FormData();
   form.append("files", new Blob([input.html], { type: "text/html" }), "index.html");
   if (input.headerHtml?.trim()) form.append("files", new Blob([input.headerHtml], { type: "text/html" }), "header.html");
   if (input.footerHtml?.trim()) form.append("files", new Blob([input.footerHtml], { type: "text/html" }), "footer.html");
-  form.append("preferCssPageSize", "true");
+  const names = new Set(["index.html", "header.html", "footer.html", "factur-x.xml"]);
+  for (const asset of input.assets ?? []) {
+    const name = fileName(asset.name);
+    if (names.has(name.toLowerCase())) throw new GotenbergRenderError("bad_input", "Asset filenames must be unique and cannot replace HTML documents.");
+    names.add(name.toLowerCase());
+    form.append("files", asset.data, name);
+  }
+  // Preserve the existing CSS page-size contract unless a caller supplies page options.
+  form.append("preferCssPageSize", String(!input.page));
   form.append("printBackground", "true");
+  if (input.tagged !== undefined) form.append("generateTaggedPdf", String(input.tagged));
+  if (input.page) {
+    const [width, height] = dimensions[input.page.format ?? "A4"];
+    form.append("paperWidth", String(width / 25.4));
+    form.append("paperHeight", String(height / 25.4));
+    form.append("landscape", String(input.page.landscape ?? false));
+    for (const side of ["top", "right", "bottom", "left"] as const) {
+      const value = input.page.margin?.[side] ?? 15;
+      if (!Number.isFinite(value) || value < 0) throw new GotenbergRenderError("bad_input", "Page margins must be nonnegative millimeters.");
+      form.append(`margin${side[0]!.toUpperCase()}${side.slice(1)}`, String(value / 25.4));
+    }
+  }
+  return form;
+}
 
+/** Bounded transport shared by HTML conversion and attachment embedding. */
+async function requestPdf(route: string, form: FormData, config: GotenbergConfig, options: RenderHtmlToPdfOptions): Promise<RenderHtmlToPdfResult> {
   const headers = new Headers();
-  const authHeader = basicAuthHeader(config);
-  if (authHeader) headers.set("Authorization", authHeader);
-
-  const transport = options.fetch ?? fetch;
-  let response: Response;
+  const auth = basicAuthHeader(config);
+  if (auth) headers.set("Authorization", auth);
+  const signal = options.signal ? AbortSignal.any([options.signal, abortSignal(config.timeoutMs)]) : abortSignal(config.timeoutMs);
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
   try {
-    response = await transport(`${baseUrl}/forms/chromium/convert/html`, {
-      method: "POST",
-      headers,
-      body: form,
-      signal: abortSignal(config.timeoutMs),
-    });
+    const response = await (options.fetch ?? fetch)(`${normalizeBaseUrl(config.url)}${route}`, { method: "POST", headers, body: form, signal });
+    if (!response.ok) {
+      await response.body?.cancel();
+      throw new GotenbergRenderError("bad_response", `Gotenberg returned HTTP ${response.status}.`, response.status);
+    }
+    const contentType = response.headers.get("content-type") || DEFAULT_PDF_CONTENT_TYPE;
+    if (contentType.split(";")[0] !== DEFAULT_PDF_CONTENT_TYPE) {
+      await response.body?.cancel();
+      throw new GotenbergRenderError("bad_response", "Gotenberg did not return a PDF.");
+    }
+    if (!response.body) throw new GotenbergRenderError("bad_response", "Gotenberg returned an empty response.");
+    reader = response.body.getReader();
+    const chunks: Uint8Array[] = [];
+    let size = 0;
+    while (true) {
+      signal.throwIfAborted();
+      const item = await reader.read();
+      if (item.done) break;
+      size += item.value.byteLength;
+      if (size > config.maxPdfBytes) throw new GotenbergRenderError("pdf_too_large", "PDF output exceeds the configured budget.");
+      chunks.push(item.value);
+    }
+    const pdf = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) { pdf.set(chunk, offset); offset += chunk.byteLength; }
+    return { pdf, contentType };
   } catch (error) {
+    await reader?.cancel().catch(() => {});
     throw sanitizeFetchError(error);
-  }
-
-  if (!response.ok) {
-    throw new GotenbergRenderError("bad_response", `Gotenberg returned HTTP ${response.status}.`, response.status);
-  }
-
-  const buffer = await response.arrayBuffer();
-  if (buffer.byteLength > config.maxPdfBytes) {
-    throw new GotenbergRenderError(
-      "pdf_too_large",
-      `PDF output is too large (${buffer.byteLength} bytes, limit ${config.maxPdfBytes} bytes).`,
-    );
-  }
+  } finally { reader?.releaseLock(); }
+}
 
-  return {
-    pdf: new Uint8Array(buffer),
-    contentType: response.headers.get("content-type") || DEFAULT_PDF_CONTENT_TYPE,
-  };
-};
+export const renderHtmlToPdfWithConfig = async (input: RenderHtmlToPdfInput, config: GotenbergConfig, options: RenderHtmlToPdfOptions = {}): Promise<RenderHtmlToPdfResult> =>
+  requestPdf("/forms/chromium/convert/html", htmlForm(input, config), config, options);
 
-export const renderFacturXHtmlToPdfWithConfig = async (
-  input: RenderFacturXHtmlToPdfInput,
-  config: GotenbergConfig,
-  options: RenderHtmlToPdfOptions = {},
-): Promise<RenderHtmlToPdfResult> => {
-  const htmlBytes = byteLength(input.html);
+export const renderFacturXHtmlToPdfWithConfig = async (input: RenderFacturXHtmlToPdfInput, config: GotenbergConfig, options: RenderHtmlToPdfOptions = {}): Promise<RenderHtmlToPdfResult> => {
   const xmlBytes = byteLength(input.xml);
-  if (htmlBytes > config.maxHtmlBytes) {
-    throw new GotenbergRenderError("html_too_large", `HTML input is too large (${htmlBytes} bytes, limit ${config.maxHtmlBytes} bytes).`);
-  }
-  if (xmlBytes === 0 || xmlBytes > config.maxHtmlBytes) {
-    throw new GotenbergRenderError(
-      xmlBytes === 0 ? "bad_input" : "html_too_large",
-      xmlBytes === 0
-        ? "Factur-X XML must not be empty."
-        : `Factur-X XML input is too large (${xmlBytes} bytes, limit ${config.maxHtmlBytes} bytes).`,
-    );
-  }
-
-  const baseUrl = normalizeBaseUrl(config.url);
-  const form = new FormData();
-  form.append("files", new Blob([input.html], { type: "text/html" }), "index.html");
-  if (input.headerHtml?.trim()) form.append("files", new Blob([input.headerHtml], { type: "text/html" }), "header.html");
-  if (input.footerHtml?.trim()) form.append("files", new Blob([input.footerHtml], { type: "text/html" }), "footer.html");
+  if (!xmlBytes || xmlBytes > config.maxHtmlBytes) throw new GotenbergRenderError(xmlBytes ? "html_too_large" : "bad_input", "Invoice XML is empty or exceeds the configured input budget.");
+  const form = htmlForm(input, { ...config, maxHtmlBytes: config.maxHtmlBytes - xmlBytes });
   form.append("facturxXml", new Blob([input.xml], { type: "application/xml" }), "factur-x.xml");
   form.append("facturxConformanceLevel", input.conformanceLevel ?? "EN 16931");
   form.append("facturxDocumentType", input.documentType ?? "INVOICE");
   form.append("facturxVersion", input.facturXVersion ?? "1.0");
   form.append("pdfa", "PDF/A-3b");
-  form.append("preferCssPageSize", "true");
-  form.append("printBackground", "true");
+  return requestPdf("/forms/chromium/convert/html", form, config, options);
+};
 
-  const headers = new Headers();
-  const authHeader = basicAuthHeader(config);
-  if (authHeader) headers.set("Authorization", authHeader);
-  let response: Response;
-  try {
-    response = await (options.fetch ?? fetch)(`${baseUrl}/forms/chromium/convert/html`, {
-      method: "POST",
-      headers,
-      body: form,
-      signal: abortSignal(config.timeoutMs),
-    });
-  } catch (error) {
-    throw sanitizeFetchError(error);
-  }
-  if (!response.ok) throw new GotenbergRenderError("bad_response", `Gotenberg returned HTTP ${response.status}.`, response.status);
-  const buffer = await response.arrayBuffer();
-  if (buffer.byteLength > config.maxPdfBytes) {
-    throw new GotenbergRenderError("pdf_too_large", `PDF output is too large (${buffer.byteLength} bytes, limit ${config.maxPdfBytes} bytes).`);
+export const attachPdfFilesWithConfig = async (input: AttachPdfFilesInput, config: GotenbergConfig, options: RenderHtmlToPdfOptions = {}): Promise<RenderHtmlToPdfResult> => {
+  if (!input.attachments.length) throw new GotenbergRenderError("bad_input", "At least one attachment is required.");
+  if (input.document.size + input.attachments.reduce((sum, file) => sum + file.data.size, 0) > config.maxPdfBytes)
+    throw new GotenbergRenderError("pdf_too_large", "PDF and attachments exceed the configured input budget.");
+  const form = new FormData();
+  form.append("files", input.document, "document.pdf");
+  const metadata: Record<string, { mimeType: string; relationship: string }> = Object.create(null);
+  const names = new Set<string>();
+  for (const attachment of input.attachments) {
+    const name = fileName(attachment.name);
+    if (names.has(name.toLowerCase())) throw new GotenbergRenderError("bad_input", "Attachment filenames must be unique.");
+    names.add(name.toLowerCase());
+    form.append("embeds", attachment.data, name);
+    metadata[name] = { mimeType: attachment.data.type || "application/octet-stream", relationship: attachment.relationship ?? "Unspecified" };
   }
-  return { pdf: new Uint8Array(buffer), contentType: response.headers.get("content-type") || DEFAULT_PDF_CONTENT_TYPE };
+  form.append("embedsMetadata", JSON.stringify(metadata));
+  return requestPdf("/forms/pdfengines/embed", form, config, options);
 };
 
 export const mergePdfsWithConfig = async (
@@ -288,3 +308,6 @@ export const testGotenberg = async (options: RenderHtmlToPdfOptions = {}): Promi
   const result = await renderHtmlToPdf({ html: TEST_HTML, filename: "index.html" }, options);
   return { bytes: result.pdf.byteLength, contentType: result.contentType };
 };
+
+export const attachPdfFiles = async (input: AttachPdfFilesInput, options: RenderHtmlToPdfOptions = {}): Promise<RenderHtmlToPdfResult> =>
+  attachPdfFilesWithConfig(input, await getGotenbergConfig(), options);

package/src/services/pdf/index.ts

@@ -1,5 +1,6 @@
 export type {
   GotenbergConfig,
+  AttachPdfFilesInput,
   GotenbergRenderErrorCode,
   MergePdfsInput,
   RenderFacturXHtmlToPdfInput,
@@ -10,6 +11,8 @@ export type {
 export {
   GotenbergRenderError,
   getGotenbergConfig,
+  attachPdfFiles,
+  attachPdfFilesWithConfig,
   mergePdfs,
   mergePdfsWithConfig,
   renderFacturXHtmlToPdf,

package/src/services/providers/local/users.ts

@@ -2,6 +2,7 @@ import { sql } from "bun";
 import type { MutationResult, UserProfile } from "../../../contracts/shared";
 import { isAccountCategoryAllowed } from "../../account-category-policy";
 import { writeDeletedAccountAudit } from "../../account-lifecycle/audit";
+import { emailAlreadyUsed, findAccountsByEmail, lockAccountEmail, normalizeAccountEmail } from "../../accounts/email-write";
 import { resolveStoredAdminState } from "../../accounts/model";
 import { writeLocalAccount } from "../../accounts/posix";
 import type { AuditActor } from "../../audit";
@@ -31,6 +32,7 @@ export const create = async (params: {
   admin?: boolean;
   actor?: AuditActor;
 }): Promise<MutationResult<{ id: string }>> => {
+  const email = normalizeAccountEmail(params.data.email);
   const uid = await createLocalUid();
   const admin = resolveStoredAdminState({
     provider: "local",
@@ -42,6 +44,8 @@ export const create = async (params: {
     return await writeLocalAccount(async (tx) => {
       if (!(await isAccountCategoryAllowed({ provider: "local", profile: params.profile }, tx)))
         return { ok: false, error: "This account category is disabled. Contact an administrator.", status: 403 };
+      await lockAccountEmail(tx, email);
+      if ((await findAccountsByEmail(tx, email)).length > 0) return emailAlreadyUsed();
       const rows = await tx<{ id: string }[]>`
       INSERT INTO auth.users (
         uid,
@@ -58,7 +62,7 @@ export const create = async (params: {
         ${uid},
         'local',
         ${params.profile},
-        ${params.data.email},
+        ${email},
         ${params.data.givenname ?? ""},
         ${params.data.sn ?? ""},
         ${params.data.displayName ?? ""},
@@ -118,21 +122,26 @@ export const update = async (params: {
     mail?: string;
   };
 }): Promise<MutationResult<void>> => {
-  const existingRows = await sql<DbRow[]>`SELECT id FROM auth.users WHERE id = ${params.id}::uuid AND provider = 'local'`;
-  if (existingRows.length === 0) {
-    return { ok: false, error: "Local user not found", status: 404 };
-  }
-
-  await sql`
-    UPDATE auth.users
-    SET given_name = CASE WHEN ${params.data.givenname !== undefined} THEN ${params.data.givenname ?? ""} ELSE given_name END,
-        sn = CASE WHEN ${params.data.sn !== undefined} THEN ${params.data.sn ?? ""} ELSE sn END,
-        display_name = CASE WHEN ${params.data.displayName !== undefined} THEN ${params.data.displayName ?? ""} ELSE display_name END,
-        mail = CASE WHEN ${params.data.mail !== undefined} THEN ${params.data.mail ?? null} ELSE mail END
-    WHERE id = ${params.id}::uuid
-  `;
-
-  return { ok: true, data: undefined };
+  return sql.begin(async (tx) => {
+    if (params.data.mail !== undefined) await lockAccountEmail(tx, params.data.mail);
+    else await tx`LOCK TABLE auth.users IN ROW EXCLUSIVE MODE`;
+    const [existing] = await tx<{ mail: string | null }[]>`
+      SELECT mail FROM auth.users WHERE id = ${params.id}::uuid AND provider = 'local' FOR UPDATE
+    `;
+    if (!existing) return { ok: false, error: "Local user not found", status: 404 };
+    const email = params.data.mail === undefined ? undefined : normalizeAccountEmail(params.data.mail);
+    const changed = email !== undefined && email !== normalizeAccountEmail(existing.mail ?? "");
+    if (changed && email && (await findAccountsByEmail(tx, email)).some((row) => row.id !== params.id)) return emailAlreadyUsed();
+    await tx`
+      UPDATE auth.users
+      SET given_name = CASE WHEN ${params.data.givenname !== undefined} THEN ${params.data.givenname ?? ""} ELSE given_name END,
+          sn = CASE WHEN ${params.data.sn !== undefined} THEN ${params.data.sn ?? ""} ELSE sn END,
+          display_name = CASE WHEN ${params.data.displayName !== undefined} THEN ${params.data.displayName ?? ""} ELSE display_name END,
+          mail = CASE WHEN ${changed} THEN ${email || null} ELSE mail END
+      WHERE id = ${params.id}::uuid
+    `;
+    return { ok: true, data: undefined };
+  });
 };
 
 export const setProfile = async (params: {

package/src/services/public-http.ts

@@ -0,0 +1,101 @@
+import { request, type RequestOptions } from "node:https";
+import type { ClientRequest, IncomingMessage } from "node:http";
+import { resolvePublicNetworkAddresses } from "./network-security";
+
+export type PublicHttpInput = {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body?: Uint8Array;
+  maxBytes: number;
+  signal: AbortSignal;
+};
+
+/** One public HTTPS request, pinned to a validated address. Never redirects or retries.
+ * Callers own credential authorization, request budgets and response disclosure. */
+export async function requestPublicHttps(
+  input: PublicHttpInput,
+  dependencies: {
+    resolve: typeof resolvePublicNetworkAddresses;
+    request: (options: RequestOptions, callback: (response: IncomingMessage) => void) => ClientRequest;
+  } = { resolve: resolvePublicNetworkAddresses, request },
+) {
+  if (!Number.isSafeInteger(input.maxBytes) || input.maxBytes < 0) throw new Error("INVALID_BYTE_LIMIT");
+  const url = new URL(input.url);
+  if (url.protocol !== "https:" || url.username || url.password) throw new Error("HTTPS_REQUIRED");
+  input.signal.throwIfAborted();
+  let cancelLookup = () => {};
+  const addresses = await Promise.race([
+    dependencies.resolve(url.hostname),
+    new Promise<never>((_, reject) => {
+      cancelLookup = () => reject(new Error("HTTP_CANCELLED"));
+      input.signal.addEventListener("abort", cancelLookup, { once: true });
+      if (input.signal.aborted) cancelLookup();
+    }),
+  ]).finally(() => input.signal.removeEventListener("abort", cancelLookup));
+  input.signal.throwIfAborted();
+  const target = addresses[0]!;
+  return new Promise<{ status: number; headers: Record<string, string>; body: Uint8Array }>((resolve, reject) => {
+    let settled = false;
+    const fail = () => finish(undefined);
+    const finish = (value?: { status: number; headers: Record<string, string>; body: Uint8Array }) => {
+      if (settled) return;
+      settled = true;
+      input.signal.removeEventListener("abort", abort);
+      if (value) resolve(value);
+      else reject(new Error("HTTP_FAILED"));
+    };
+    const outgoing = dependencies.request(
+      {
+        hostname: target.address,
+        family: target.family,
+        port: url.port || 443,
+        servername: url.hostname.replace(/^\[|\]$/g, ""),
+        rejectUnauthorized: true,
+        path: url.pathname + url.search,
+        method: input.method,
+        headers: { ...input.headers, host: url.host, "accept-encoding": "identity" },
+      },
+      (incoming) => {
+        const status = incoming.statusCode ?? 0;
+        const headers: Record<string, string> = {};
+        for (const name of ["content-type", "retry-after", "etag", "last-modified"]) {
+          const value = incoming.headers[name];
+          if (typeof value === "string") headers[name] = value;
+        }
+        // A redirect never receives a second request or exposes a Location token.
+        if (status >= 300 && status < 400 && status !== 304) {
+          incoming.destroy();
+          finish({ status, headers, body: new Uint8Array() });
+          return;
+        }
+        if (incoming.headers["content-encoding"] && incoming.headers["content-encoding"] !== "identity") {
+          incoming.destroy();
+          fail();
+          return;
+        }
+        const chunks: Uint8Array[] = [];
+        let bytes = 0;
+        incoming.on("data", (chunk: Buffer) => {
+          if (settled) return;
+          bytes += chunk.byteLength;
+          if (bytes > input.maxBytes) {
+            incoming.destroy();
+            fail();
+          } else chunks.push(chunk);
+        });
+        incoming.on("end", () => finish({ status, headers, body: Buffer.concat(chunks, bytes) }));
+        incoming.on("error", fail);
+        incoming.on("aborted", fail);
+      },
+    );
+    const abort = () => {
+      outgoing.destroy();
+      fail();
+    };
+    outgoing.on("error", fail); // Never expose errors containing injected headers.
+    input.signal.addEventListener("abort", abort, { once: true });
+    if (input.signal.aborted) abort();
+    else outgoing.end(input.body);
+  });
+}

package/src/services/rail-shortcuts.ts

@@ -0,0 +1,95 @@
+import { type SQL, sql } from "bun";
+import { RailAdminSchema, RailAdminInputSchema, type RailAdminInput, type RailAdminState } from "../contracts/rail-admin";
+import { RailShortcutSchema } from "../contracts/rail-preferences";
+import { hasRole, type User } from "../contracts/shared";
+import { buildAccessPrincipalCondition, createAccess } from "../server/services/access";
+
+export class RailAdminError extends Error {
+  constructor(
+    public status: 400 | 403 | 409,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+const requireAdmin = (actor: User | undefined) => {
+  if (!actor || !hasRole(actor, "admin")) throw new RailAdminError(403, "Administrator access required");
+};
+
+export const createRailShortcutsService = (db: SQL = sql) => {
+  const list = async (query: SQL = db): Promise<RailAdminState> => {
+    const [state] = await query<{ revision: number }[]>`SELECT revision FROM auth.rail_state WHERE singleton`;
+    const rows = await query<{ shortcut: unknown; access: unknown }[]>`
+      SELECT r.shortcut, COALESCE((
+        SELECT jsonb_agg(jsonb_build_object(
+          'id', a.id, 'permission', a.permission, 'createdAt', a.created_at,
+          'principal', CASE WHEN a.user_id IS NOT NULL THEN jsonb_build_object('type', 'user', 'userId', a.user_id)
+            WHEN a.group_id IS NOT NULL THEN jsonb_build_object('type', 'group', 'groupId', a.group_id)
+            ELSE jsonb_build_object('type', 'authenticated') END,
+          'displayName', COALESCE(u.display_name, g.name, '')
+        ) ORDER BY a.created_at, a.id)
+        FROM auth.rail_shortcut_access ra JOIN auth.access a ON a.id = ra.access_id
+        LEFT JOIN auth.users u ON u.id = a.user_id LEFT JOIN auth.groups g ON g.id = a.group_id
+        WHERE ra.shortcut_id = r.id
+      ), '[]'::jsonb) AS access
+      FROM auth.rail_shortcuts r ORDER BY r.position, r.id
+    `;
+    return RailAdminSchema.parse({ revision: state?.revision ?? 0, entries: rows });
+  };
+  return {
+    async invalidateCache(actor: User | undefined) {
+      requireAdmin(actor);
+      // One generation switch invalidates every user, including concurrent old refills.
+      // Keep the configuration revision unchanged so open editors remain valid.
+      await db`UPDATE auth.rail_state SET cache_version = gen_random_uuid() WHERE singleton`;
+    },
+    async list(actor: User | undefined) {
+      requireAdmin(actor);
+      return list();
+    },
+    async save(actor: User | undefined, input: RailAdminInput) {
+      requireAdmin(actor);
+      const value = RailAdminInputSchema.parse(input);
+      return db.begin(async (tx) => {
+        const [state] = await tx<{ revision: number }[]>`SELECT revision FROM auth.rail_state WHERE singleton FOR UPDATE`;
+        if (state?.revision !== value.revision) throw new RailAdminError(409, "App bar configuration changed. Reload before saving.");
+        await tx`DELETE FROM auth.access WHERE id IN (SELECT access_id FROM auth.rail_shortcut_access)`;
+        await tx`DELETE FROM auth.rail_shortcuts`;
+        for (const [position, entry] of value.entries.entries()) {
+          await tx`INSERT INTO auth.rail_shortcuts(id, position, shortcut)
+            VALUES (${entry.shortcut.id}, ${position}, (${JSON.stringify(entry.shortcut)}::text)::jsonb)`;
+          const seen = new Set<string>();
+          for (const access of entry.access) {
+            const key = JSON.stringify(access.principal);
+            if (seen.has(key)) continue;
+            seen.add(key);
+            const created = await createAccess({ principal: access.principal, permission: "read" }, tx);
+            if (!created.ok) throw new RailAdminError(400, "A selected user or group no longer exists.");
+            await tx`INSERT INTO auth.rail_shortcut_access(shortcut_id, access_id) VALUES (${entry.shortcut.id}, ${created.data.id}::uuid)`;
+          }
+        }
+        await tx`UPDATE auth.rail_state SET revision = revision + 1 WHERE singleton`;
+        return list(tx);
+      });
+    },
+    async forUser(userId: string) {
+      const match = buildAccessPrincipalCondition({
+        subject: { type: "user", userId },
+        columns: {
+          userId: db`a.user_id`,
+          groupId: db`a.group_id`,
+          serviceAccountId: db`a.service_account_id`,
+          authenticatedOnly: db`a.authenticated_only`,
+        },
+      });
+      const rows = await db<{ shortcut: unknown }[]>`
+        SELECT r.shortcut FROM auth.rail_shortcuts r WHERE EXISTS (
+          SELECT 1 FROM auth.rail_shortcut_access ra JOIN auth.access a ON a.id = ra.access_id
+          WHERE ra.shortcut_id = r.id AND a.permission = 'read' AND ${match}
+        ) ORDER BY r.position, r.id
+      `;
+      return rows.map((row) => RailShortcutSchema.parse(row.shortcut));
+    },
+  };
+};
+export const railShortcuts = createRailShortcutsService();

package/src/services/rail-snapshot.ts

@@ -0,0 +1,53 @@
+import { requestCacheRedis } from "./request-cache-redis";
+import { type RailSnapshot, RailSnapshotSchema } from "../contracts/rail-preferences";
+import type { User } from "../contracts/shared";
+import { railPreferences } from "./rail-preferences";
+import { railShortcuts } from "./rail-shortcuts";
+
+// Private request metadata: never serialized into the public User contract.
+const versions = new WeakMap<User, string>();
+export const setRailCacheVersion = (user: User, version: unknown) => {
+  if (typeof version === "string") versions.set(user, version);
+};
+
+/** TTL only bounds unused generations; freshness comes from the current identity query. */
+const CACHE_TTL_SECONDS = 300;
+export const createRailSnapshotReader =
+  (
+    load: (userId: string) => Promise<RailSnapshot>,
+    cache: { get(key: string): Promise<string | null>; set(key: string, value: string): Promise<unknown> },
+  ) =>
+  async (user: User): Promise<RailSnapshot> => {
+    const version = versions.get(user);
+    if (!version) return load(user.id);
+    const key = `appglobalcache:user:${user.id}:rail:v1:${version}`;
+    try {
+      const cached = await cache.get(key);
+      if (cached !== null) {
+        const parsed = RailSnapshotSchema.safeParse(JSON.parse(cached));
+        if (parsed.success) return parsed.data;
+      }
+    } catch {
+      /* Valkey is an optimization; authoritative reads still work. */
+    }
+    const value = await load(user.id);
+    // A concurrent mutation changes the generation. A late refill remains under
+    // this request's old key and cannot poison a subsequent request's snapshot.
+    try {
+      await cache.set(key, JSON.stringify(value));
+    } catch {
+      /* Retry on a later read. */
+    }
+    return value;
+  };
+
+export const readRailSnapshot = createRailSnapshotReader(
+  async (userId) => {
+    const [personal, managedShortcuts] = await Promise.all([railPreferences.get(userId), railShortcuts.forUser(userId)]);
+    return { ...personal, managedShortcuts };
+  },
+  {
+    get: async (key) => (await requestCacheRedis()).get(key),
+    set: async (key, value) => (await requestCacheRedis()).set(key, value, "EX", CACHE_TTL_SECONDS),
+  },
+);

package/src/services/request-cache-redis.ts

@@ -0,0 +1,28 @@
+import { RedisClient } from "bun";
+
+// Cache commands must not queue across a disconnect: delayed fills/invalidations
+// are not useful, and reads must be able to fall back to Postgres. Keep this
+// connection separate from sessions, rate limits and other Redis consumers.
+let client: RedisClient | undefined;
+let initialConnection: Promise<void> | undefined;
+let reconnecting: Promise<void> | undefined;
+
+export const requestCacheRedis = async (): Promise<RedisClient> => {
+  if (!client) {
+    client = new RedisClient(process.env.VALKEY_URL || process.env.REDIS_URL, { enableOfflineQueue: false });
+    // The first operation waits for normal connection establishment (Bun's
+    // connection timeout applies). Later disconnected operations fail promptly.
+    initialConnection = client.connect().catch(() => {});
+  }
+  await initialConnection;
+  if (!client.connected && !reconnecting) {
+    // Bun reconnects automatically; also allow recovery after its retry limit.
+    reconnecting = client
+      .connect()
+      .catch(() => {})
+      .finally(() => {
+        reconnecting = undefined;
+      });
+  }
+  return client;
+};