@k2b/cloud 0.6.0 → 0.8.0

package/src/contracts/commands.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+
+/** Commands carry small public references/options, never document bodies or secrets. */
+export const COMMAND_MAX_URL_LENGTH = 8192;
+export const CommandPathSchema = z
+  .string()
+  .max(2000)
+  .refine((value) => {
+    if (!value.startsWith("/") || /[\\\u0000-\u0020]/u.test(value)) return false;
+    try {
+      return new URL(value, "https://cloud.invalid").origin === "https://cloud.invalid";
+    } catch {
+      return false;
+    }
+  }, "Expected a Cloud path");
+
+export const CommandOptionsSchema = z.object({ returnTo: CommandPathSchema.optional() }).strict();
+export type CommandOptions = z.infer<typeof CommandOptionsSchema>;
+export const CommandRequestSchema = CommandOptionsSchema.extend({ input: z.unknown() }).strict();
+export const CommandLinkSchema = z.object({ href: z.url().max(COMMAND_MAX_URL_LENGTH) }).strict();
+
+export const commandPath = (path: string, command: string, input: unknown, options: CommandOptions = {}): string => {
+  const url = new URL(CommandPathSchema.parse(path), "https://cloud.invalid");
+  url.searchParams.set("command", command);
+  url.searchParams.set("commandInput", JSON.stringify(input));
+  const parsed = CommandOptionsSchema.parse(options);
+  if (parsed.returnTo) url.searchParams.set("commandReturn", parsed.returnTo);
+  else url.searchParams.delete("commandReturn");
+  const result = `${url.pathname}${url.search}${url.hash}`;
+  if (result.length > COMMAND_MAX_URL_LENGTH) throw new Error("Command link is too large");
+  return result;
+};
+
+export const readCommand = (url: URL) => {
+  const id = url.searchParams.get("command");
+  if (!id) return null;
+  const raw = url.searchParams.get("commandInput") ?? "{}";
+  if (url.href.length > COMMAND_MAX_URL_LENGTH) throw new Error("Command link is too large");
+  return {
+    id,
+    input: JSON.parse(raw) as unknown,
+    options: CommandOptionsSchema.parse({ returnTo: url.searchParams.get("commandReturn") ?? undefined }),
+  };
+};
+
+export const clearCommand = (url: URL): string => {
+  for (const key of ["command", "commandInput", "commandReturn"]) url.searchParams.delete(key);
+  return `${url.pathname}${url.search}${url.hash}`;
+};

package/src/contracts/index.ts

@@ -1,14 +1,17 @@
 export * from "./account-categories";
 export * from "./announcements";
 export * from "./app";
+export * from "./app-approval";
 export * from "./capabilities";
-export * from "./notification-live";
+export * from "./commands";
 export * from "./notification-types";
 export * from "./posix";
 export * from "./profile";
+// Core app bar administration and shared shortcut values.
+export { RailAccessSchema, type RailAdminEntry, RailAdminInputSchema, RailAdminSchema, type RailAdminState } from "./rail-admin";
+export type { RailShortcut } from "./rail-preferences";
 export * from "./registry";
 export * from "./resource-clipboard";
 export * from "./shared";
 export * from "./user-notifications";
 export * from "./widgets";
-export * from "./app-approval";

package/src/contracts/rail-admin.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { RAIL_PREFERENCES_MAX_BYTES, RailShortcutSchema } from "./rail-preferences";
+import { AccessEntrySchema } from "./shared";
+
+export const RailAccessSchema = AccessEntrySchema.extend({
+  principal: z.discriminatedUnion("type", [
+    z.object({ type: z.literal("authenticated") }).strict(),
+    z.object({ type: z.literal("user"), userId: z.uuid() }).strict(),
+    z.object({ type: z.literal("group"), groupId: z.uuid() }).strict(),
+  ]),
+  permission: z.literal("read"),
+});
+export const RailAdminEntrySchema = z.object({ shortcut: RailShortcutSchema, access: z.array(RailAccessSchema) }).strict();
+const revision = z.number().int().nonnegative().max(2_147_483_647);
+export const RailAdminSchema = z.object({ revision, entries: z.array(RailAdminEntrySchema) }).strict();
+/** Strip presentation metadata from editor drafts before sending or persisting grants. */
+export const RailAdminInputSchema = z
+  .object({
+    revision,
+    entries: z.array(
+      z
+        .object({
+          shortcut: RailShortcutSchema,
+          access: z.array(RailAccessSchema.pick({ principal: true, permission: true })),
+        })
+        .strict(),
+    ),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    if (new TextEncoder().encode(JSON.stringify(value)).byteLength > RAIL_PREFERENCES_MAX_BYTES)
+      ctx.addIssue({ code: "custom", message: "Global app bar configuration exceeds 16 KiB" });
+    if (new Set(value.entries.map((entry) => entry.shortcut.id)).size !== value.entries.length)
+      ctx.addIssue({ code: "custom", message: "Shortcut IDs must be unique" });
+  });
+export type RailAdminInput = z.infer<typeof RailAdminInputSchema>;
+export type RailAdminState = z.infer<typeof RailAdminSchema>;
+export type RailAdminEntry = z.infer<typeof RailAdminEntrySchema>;

package/src/contracts/rail-preferences.ts

@@ -51,3 +51,19 @@ export const RailPreferencesSchema = z
   });
 export type RailPreferences = z.infer<typeof RailPreferencesSchema>;
 export const defaultRailPreferences = (): RailPreferences => ({ revision: 0, visibility: {}, shortcuts: [] });
+
+/** Managed entries are separate from the writable personal API contract. */
+export type RailSnapshot = RailPreferences & { managedShortcuts?: RailShortcut[] };
+export const RailSnapshotSchema = z
+  .object({
+    revision: z.number(),
+    visibility: z.record(z.string(), z.boolean()),
+    shortcuts: z.array(RailShortcutSchema),
+    managedShortcuts: z.array(RailShortcutSchema).optional(),
+  })
+  .strict()
+  .superRefine(({ managedShortcuts, ...personal }, ctx) => {
+    if (!RailPreferencesSchema.safeParse(personal).success) ctx.addIssue({ code: "custom", message: "Invalid personal app bar settings" });
+    if (new TextEncoder().encode(JSON.stringify(managedShortcuts ?? [])).byteLength > RAIL_PREFERENCES_MAX_BYTES)
+      ctx.addIssue({ code: "custom", message: "Managed shortcuts exceed the 16 KiB page budget" });
+  });

package/src/contracts/registry.ts

@@ -1,5 +1,4 @@
-import type { HelpManifest } from "../shared/help";
-import type { AppAdminNavigationGroup, AppAppearance, AppAppearanceColor, AppPresentationCatalog } from "./app";
+import type { AppAdminNavigationGroup, AppAppearance, AppAppearanceColor, AppPresentationCatalog, AppSearchLink } from "./app";
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "./capabilities";
 import type { Role } from "./shared";
 import type { DashboardWidgetPresentation } from "./widgets";
@@ -36,31 +35,7 @@ export type CapabilityRegistryEntry = {
   presentation?: CapabilityPresentationCatalog;
 };
 
-export type AppRegistryHelpSummary = HelpManifest;
-
-export type HelpRegistryDocument = {
-  id: string;
-  title: string;
-  icon?: string;
-  description?: string;
-  order: number;
-  markdown: string;
-  /** Precomputed by the app. Older registry entries may omit it during rolling upgrades. */
-  searchText?: string;
-};
-
-/** Full Markdown lives separately so normal app discovery stays small. */
-export type HelpRegistryEntry = {
-  appId: string;
-  appName: string;
-  appIcon: string;
-  manifestHash: string;
-  /** Base language that owns the complete logical article set. Absent on legacy registrations. */
-  baseLocale?: string;
-  /** Partial localized article variants stored in the same bounded logical registration. */
-  documentsByLocale?: Readonly<Record<string, readonly HelpRegistryDocument[]>>;
-  documents: readonly HelpRegistryDocument[];
-};
+export type AppRegistryHelpSummary = { manifestHash: string; pageBase: string; baseLocale: string };
 
 export type AppRegistryLegalLink = {
   label: string;
@@ -76,6 +51,8 @@ export type AppRegistryWidget = {
 };
 
 export type AppRuntimeMetadata = {
+  /** Cloud version of the running app. Missing on apps built before versions were baked in. */
+  version?: string;
   release: string;
   syncVersion: string;
 };
@@ -102,6 +79,7 @@ export type AppRegistryEntry = {
   capabilities?: AppRegistryCapabilitySummary;
   help?: AppRegistryHelpSummary;
   legalLinks?: AppRegistryLegalLink[];
+  searchLinks?: readonly AppSearchLink[];
   widgets?: AppRegistryWidget[];
   /** Setting keys declared by this app. Used by admin tooling to avoid treating live app-owned settings as legacy. */
   settingKeys?: readonly string[];

package/src/contracts/settings-types.ts

@@ -43,7 +43,7 @@ type StringLikeKind = "string" | "text" | "email" | "url" | "secret" | "image" |
 export type AppSettingDef =
   | (CommonDef & { kind: StringLikeKind; default: string; placeholder?: string; templateVars?: readonly string[] })
   | (CommonDef & { kind: "boolean"; default: boolean })
-  | (CommonDef & { kind: "number"; default: number; min?: number; max?: number; placeholder?: string })
+  | (CommonDef & { kind: "number"; default: number; min?: number; max?: number; integer?: boolean; placeholder?: string })
   | (CommonDef & { kind: "enum"; default: string; options: ReadonlyArray<SettingOption> })
   | (CommonDef & { kind: "string_list"; default: readonly string[]; placeholder?: string })
   | (CommonDef & { kind: "number_list"; default: readonly number[]; placeholder?: string });

package/src/contracts/shared.ts

@@ -288,12 +288,25 @@ export const AccountActivityListResponseSchema = z.object({
 });
 export type AccountActivityListResponse = z.infer<typeof AccountActivityListResponseSchema>;
 
+export const AuthenticatedPrincipalSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("user").describe("One user account."),
+    userId: z.uuid().describe("Exact user ID returned by the Accounts directory."),
+  }),
+  z.object({
+    type: z.literal("group").describe("Members of one group."),
+    groupId: z.uuid().describe("Exact group ID returned by the Accounts directory."),
+  }),
+  z.object({
+    type: z.literal("service_account").describe("One service account."),
+    serviceAccountId: z.uuid().describe("Exact service account ID returned by the Accounts directory."),
+  }),
+  z.object({ type: z.literal("authenticated").describe("Every authenticated identity; no directory ID is needed.") }),
+]);
+
 export const PrincipalSchema = z.discriminatedUnion("type", [
-  z.object({ type: z.literal("user"), userId: z.uuid() }),
-  z.object({ type: z.literal("group"), groupId: z.uuid() }),
-  z.object({ type: z.literal("service_account"), serviceAccountId: z.uuid() }),
-  z.object({ type: z.literal("authenticated") }),
-  z.object({ type: z.literal("public") }),
+  ...AuthenticatedPrincipalSchema.options,
+  z.object({ type: z.literal("public").describe("Public access where supported by the resource; no directory ID is needed.") }),
 ]);
 export type Principal = z.infer<typeof PrincipalSchema>;
 

package/src/contracts/web-vitals.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+
+/** One metric plus six server phases and bounded routing metadata. */
+export const WEB_VITALS_MAX_BYTES = 4096;
+export const WebVitalsReportSchema = z
+  .object({
+    appId: z
+      .string()
+      .min(1)
+      .max(64)
+      .regex(/^[a-z0-9-]+$/),
+    routeTemplate: z
+      .string()
+      .min(1)
+      .max(200)
+      .regex(/^\/[a-zA-Z0-9_/:.*-]*$/),
+    id: z.string().min(1).max(100),
+    name: z.enum(["LCP", "INP", "CLS"]),
+    value: z.number().nonnegative(),
+    navigationType: z.string().max(32),
+    serverTiming: z.partialRecord(
+      z.enum(["auth", "settings", "runtime", "ssr_data", "ssr_finalize", "ssr_render"]),
+      z.number().nonnegative(),
+    ),
+  })
+  .strict();
+export type WebVitalsReport = z.infer<typeof WebVitalsReportSchema>;

package/src/desktop/index.ts

@@ -311,6 +311,7 @@ const getSql = (): DesktopSql => {
   const { Database } = requireFn("bun:sqlite") as { Database: new (path: string) => any };
   const { dirname, resolve } = requireFn("node:path") as typeof import("node:path");
   const { mkdirSync } = requireFn("node:fs") as typeof import("node:fs");
+  // Declared in the platform registry; this browser-safe module must not import zod-backed config.
   const dbPath = process.env.CLOUD_DESKTOP_SQLITE_PATH ?? resolve(process.cwd(), ".local", "desktop.sqlite");
   mkdirSync(dirname(dbPath), { recursive: true });
   const db = new Database(dbPath);

package/src/desktop/solid.tsx

@@ -1,6 +1,6 @@
 import { deserialize as deserializeProps, serialize as serializeProps } from "seroval";
 import type { Component, JSX, ParentProps } from "solid-js";
-import { children, createContext, createEffect, createMemo, createSignal, For, onCleanup, onMount, Show, useContext } from "solid-js";
+import { children, createContext, createMemo, createSignal, For, onCleanup, onMount, Show, useContext } from "solid-js";
 import { Dynamic, Portal } from "solid-js/web";
 import {
   type DesktopEnvironment,

package/src/index.ts

@@ -10,21 +10,23 @@ export {
   unbindProcessSync,
 } from "./_internal/process-sync";
 export { APP_READINESS_PATH } from "./_internal/readiness";
-export type { AppRegistryDetail, AppRegistryIssue, AppRegistrySnapshot, CapabilityRegistryRecord, DashboardWidget } from "./_internal/registry";
+export type {
+  AppRegistryDetail,
+  AppRegistryIssue,
+  AppRegistrySnapshot,
+  CapabilityRegistryRecord,
+  DashboardWidget,
+} from "./_internal/registry";
 export {
   APP_REGISTRY_CONFIG,
   APP_REGISTRY_PREFIX,
   APP_REGISTRY_TTL_MS,
-  CAPABILITY_REGISTRY_CONFIG,
-  HELP_REGISTRY_CONFIG,
   appRegistry,
+  CAPABILITY_REGISTRY_CONFIG,
   capabilityRegistry,
   getApp,
-  getHelp,
-  helpRegistry,
   listApps,
   listAppsDetailed,
-  listHelp,
   listLegalLinks,
   listWidgets,
   readAppRegistrySnapshot,

package/src/server/index.ts

@@ -8,6 +8,7 @@ export { defineHelp, defineHelpCollection, type HelpCollection, type HelpDefinit
 export { DEFAULT_LOCALE, getLocale, LOCALE_COOKIE, LOCALE_HEADER, locale, preferredLocale, resolveLocale } from "./locale";
 export type {
   AuthContext,
+  InvocationExpectation,
   InvocationProvenance,
   RateLimitConfig,
   RateLimitRouteOverride,
@@ -26,6 +27,7 @@ export {
   rateLimit,
   rejectReservedWorkloadCredential,
   requestLogger,
+  requireInvocation,
   requiresAdmin,
   requiresAuth,
   requiresIpa,
@@ -56,6 +58,7 @@ export type {
   ServiceErrorCode,
 } from "./services";
 export {
+  accessRevision,
   buildAccessPrincipalCondition,
   buildAccessPrincipalTierConditions,
   createAccess,

package/src/server/middleware/auth.ts

@@ -1,5 +1,6 @@
 import type { Context } from "hono";
 import { createMiddleware } from "hono/factory";
+import { measureServerPhase } from "../../_internal/server-timing";
 import type { MessageResponse, Role, RoleOrSpecial, User, UserProfile, UserProvider } from "../../contracts/shared";
 import { isAccountExpired } from "../../services/account-model";
 import { isReservedWorkloadApiCredential } from "../../services/identity/workload-auth";
@@ -215,10 +216,10 @@ const loadAuthenticatedActor = (
   c: Context<AuthContext>,
   options: Pick<RoleOptions, "oauthAudience"> = {},
 ): Promise<AuthenticatedActorResult> => {
-  if (options.oauthAudience) return loadAuthenticatedActorUncached(c, options);
+  if (options.oauthAudience) return measureServerPhase(c, "auth", () => loadAuthenticatedActorUncached(c, options));
   const existing = actorResolutionByRequest.get(c);
   if (existing) return existing;
-  const pending = loadAuthenticatedActorUncached(c, options);
+  const pending = measureServerPhase(c, "auth", () => loadAuthenticatedActorUncached(c, options));
   actorResolutionByRequest.set(c, pending);
   return pending;
 };

package/src/server/middleware/route-template.ts

@@ -16,6 +16,8 @@
  * Templates only: the request path itself never leaves the app, so ids
  * and query strings stay out of telemetry by construction.
  */
+
+import type { Context } from "hono";
 import { createMiddleware } from "hono/factory";
 import { routePath } from "hono/route";
 import { ROUTE_TEMPLATE_HEADER } from "../../services/gateway";
@@ -32,14 +34,18 @@ const MAX_TEMPLATE_LENGTH = 200;
  */
 const stripParamConstraints = (template: string): string => template.replace(/\{[^}]*\}/g, "");
 
+export const matchedRouteTemplate = (c: Context): string | null => {
+  const template = routePath(c);
+  return !template || template === UNMATCHED ? null : stripParamConstraints(template).slice(0, MAX_TEMPLATE_LENGTH);
+};
+
 export const routeTemplate = createMiddleware(async (c, next) => {
   await next();
 
   // Best-effort: telemetry enrichment must never break a response.
   try {
-    const template = routePath(c);
-    if (!template || template === UNMATCHED) return;
-    c.res.headers.set(ROUTE_TEMPLATE_HEADER, stripParamConstraints(template).slice(0, MAX_TEMPLATE_LENGTH));
+    const template = matchedRouteTemplate(c);
+    if (template) c.res.headers.set(ROUTE_TEMPLATE_HEADER, template);
   } catch {
     // Immutable response headers or an unrouted context — nothing to report.
   }

package/src/server/middleware/runtime.ts

@@ -9,11 +9,12 @@
  */
 import { createMiddleware } from "hono/factory";
 import { ensureRuntimeWatcher, getCurrentRuntime } from "../../_internal/runtime-watcher";
+import { measureServerPhase } from "../../_internal/server-timing";
 import { routeTemplate } from "./route-template";
 
 export const runtime = () =>
   createMiddleware(async (c, next) => {
-    await ensureRuntimeWatcher();
+    await measureServerPhase(c, "runtime", ensureRuntimeWatcher);
     (c as unknown as { set: (k: string, v: unknown) => void }).set("runtime", getCurrentRuntime());
     // Piggybacks on the middleware every proxied app already installs, so
     // gateway telemetry gets per-endpoint route templates without any app

package/src/server/middleware/settings.ts

@@ -13,6 +13,7 @@
  * `.use()` path instead.
  */
 import { createMiddleware } from "hono/factory";
+import { measureServerPhase } from "../../_internal/server-timing";
 import {
   type ActiveAnnouncementsResponse,
   type AnnouncementCookieState,
@@ -38,18 +39,23 @@ export const settings = (opts?: { skipPrefixes?: readonly string[] }) => {
   return createMiddleware(async (c, next) => {
     const path = c.req.path;
     if (!skip.some((p) => path.startsWith(p))) {
-      (c as unknown as { set: (k: string, v: unknown) => void }).set("settings", await loadSnapshot());
-    }
-    const cookieHeader = c.req.header("Cookie") ?? null;
-    if (shouldLoadAnnouncements(path, cookieHeader)) {
-      const cookieState = parseAnnouncementCookieHeader(cookieHeader);
-      try {
-        const active = await announcements.active.forState({ state: cookieState });
-        (c as unknown as { set: (k: string, v: unknown) => void }).set("announcements", { ...active, cookieState });
-      } catch (error) {
-        log.warn("Failed to preload announcements", { error: error instanceof Error ? error.message : String(error) });
-      }
+      (c as unknown as { set: (k: string, v: unknown) => void }).set("settings", await measureServerPhase(c, "settings", loadSnapshot));
     }
     await next();
   });
 };
+
+/** Called by SSR finalization, after redirects and non-HTML responses are known. */
+export const preloadLayoutAnnouncements = async (c: import("hono").Context): Promise<void> => {
+  const path = c.req.path;
+  const cookieHeader = c.req.header("Cookie") ?? null;
+  if (shouldLoadAnnouncements(path, cookieHeader)) {
+    const cookieState = parseAnnouncementCookieHeader(cookieHeader);
+    try {
+      const active = await announcements.active.forState({ state: cookieState });
+      (c as unknown as { set: (k: string, v: unknown) => void }).set("announcements", { ...active, cookieState });
+    } catch (error) {
+      log.warn("Failed to preload announcements", { error: error instanceof Error ? error.message : String(error) });
+    }
+  }
+};

package/src/server/ratelimit.ts

@@ -86,7 +86,7 @@ export class RateLimitError extends Error {
 // ==========================
 
 export const ratelimit = (config: RateLimiterConfig): RateLimiter => {
-  // windowSecs: 0 — e.g. Number(process.env.RL_WINDOW) on an unset var — made
+  // windowSecs: 0 — e.g. `Number()` of an unset variable — made
   // both window keys Infinity and collapse to one, elapsedRatio NaN, and
   // `EXPIRE key 0` delete the counter on every first increment, so the
   // weighted count never exceeded the limit and the limiter allowed

package/src/server/services/access-revision.ts

@@ -0,0 +1,10 @@
+import { createHash } from "node:crypto";
+import type { PermissionLevel, Principal } from "./access";
+
+/** Compare the grants that were reviewed with those held under a resource lock. */
+export function accessRevision(entries: ReadonlyArray<{ id: string; principal: Principal; permission: PermissionLevel }>): string {
+  const state = entries
+    .map((entry) => [entry.id, entry.permission, Object.entries(entry.principal).sort(([left], [right]) => left.localeCompare(right))])
+    .sort((left, right) => String(left[0]).localeCompare(String(right[0])));
+  return createHash("sha256").update(JSON.stringify(state)).digest("hex");
+}

package/src/server/services/access.ts

@@ -568,7 +568,9 @@ export const listUsersWithAccess = async (params: {
  * Resolve display names for access entries.
  * Populates the displayName field based on principal type.
  */
-export const resolveDisplayNames = async (entries: AccessEntry[]): Promise<AccessEntry[]> => {
+export const resolveDisplayNames = async <T extends { principal: Principal }>(
+  entries: T[],
+): Promise<(T & { displayName: string; avatarHash?: string | null })[]> => {
   const userIds = entries.filter((e) => e.principal.type === "user").map((e) => (e.principal as { type: "user"; userId: string }).userId);
 
   const groupIds = entries

package/src/server/services/index.ts

@@ -46,3 +46,4 @@ export { crypto, err, fail, isServiceError, ok, okMany, paginate, password, svg,
 // Compat aliases for old API names
 export const images = { generateFallback: _svg.generateAvatar, parseWebpDataUrl: _svg.parseWebpDataUrl };
 export const generatePassword = _password.random;
+export { accessRevision } from "./access-revision";

package/src/services/account-category-policy.ts

@@ -20,6 +20,15 @@ const readValue = async (key: string, fallback: boolean | string, db: typeof sql
   return value;
 };
 
+/** Decode a policy selected alongside a user, without a second database read. */
+export const decodeAccountCategoryEnabled = async (encrypted: unknown): Promise<boolean> => {
+  if (encrypted === null || encrypted === undefined) return true;
+  if (typeof encrypted !== "string") throw new Error("Invalid account category configuration");
+  const value = await decryptValue(encrypted);
+  if (typeof value !== "boolean") throw new Error("Invalid account category configuration");
+  return value;
+};
+
 export const isAccountCategoryAllowed = async (
   user: { provider: "local" | "ipa"; profile: "guest" | "user" },
   db: typeof sql = sql,

package/src/services/account-lifecycle/audit.ts

@@ -35,7 +35,7 @@ export const writeDeletedAccountAudit = async (config: {
       ${config.previousProvider},
       ${config.previousProfile},
       ${config.reason},
-      ${JSON.stringify(config.meta ?? {})}::jsonb
+      ${JSON.stringify(config.meta ?? {})}::text::jsonb
     )
   `;
 };

package/src/services/accounts/app.ts

@@ -37,6 +37,7 @@ import { listDuplicateEmails } from "./duplicate-emails";
 import * as entities from "./entities";
 import * as groups from "./groups";
 import type { AccountsNotificationSender } from "./notification-sender";
+import { PosixError } from "./posix";
 import { accountRequestsEnabled } from "./request-policy";
 import * as users from "./users";
 
@@ -141,6 +142,15 @@ const fromMutationResult = <T>(result: MutationResult<T>): Result<T> => {
   return fail(toServiceError(result.status, result.error));
 };
 
+const fromGroupMutation = async <T>(operation: () => Promise<MutationResult<T>>): Promise<Result<T>> => {
+  try {
+    return fromMutationResult(await operation());
+  } catch (error) {
+    if (error instanceof PosixError) return fail({ code: error.code, message: error.message, status: error.status });
+    throw error;
+  }
+};
+
 const mapAccountRequestRow = (row: DbRow): AccountRequest => ({
   id: row.id as string,
   userId: row.user_id as string | null,
@@ -1119,7 +1129,7 @@ export const accountsAppService = {
         target: { type: "group", label: config.name, provider: config.provider },
       });
       if (adminError) return adminError;
-      const result = fromMutationResult(await groups.create(config));
+      const result = await fromGroupMutation(() => groups.create(config));
       return recordCompletedMutation({
         action: "accounts.group.create",
         actor: auditActor(config.actor),
@@ -1164,7 +1174,7 @@ export const accountsAppService = {
         target,
       });
       if (adminError) return adminError;
-      const result = fromMutationResult(await groups.makePosix(config));
+      const result = await fromGroupMutation(() => groups.makePosix(config));
       return recordCompletedMutation({
         action: "accounts.group.make_posix",
         actor: auditActor(config.actor),

package/src/services/accounts/email-write.ts

@@ -0,0 +1,23 @@
+import type { sql } from "bun";
+
+export const normalizeAccountEmail = (email: string): string => email.trim().toLowerCase();
+
+/** Hold through the write (including a FreeIPA mutation), on the same transaction. */
+export const lockAccountEmail = async (db: typeof sql, email: string): Promise<void> => {
+  // Take the table's ordinary write lock before the advisory lock. Local POSIX
+  // provisioning takes a stronger table lock first; this keeps their order compatible.
+  await db`LOCK TABLE auth.users IN ROW EXCLUSIVE MODE`;
+  await db`SELECT pg_advisory_xact_lock(hashtextextended('cloud:account-email:' || ${normalizeAccountEmail(email)}, 0))`;
+};
+
+export const findAccountsByEmail = (db: typeof sql, email: string) =>
+  db<
+    {
+      id: string;
+      uid: string;
+      provider: "local" | "ipa";
+      mail: string;
+    }[]
+  >`SELECT id, uid, provider, mail FROM auth.users WHERE lower(btrim(mail)) = ${normalizeAccountEmail(email)}`;
+
+export const emailAlreadyUsed = () => ({ ok: false as const, error: "An account with this email already exists.", status: 409 as const });

package/src/services/accounts/groups.ts

@@ -4,9 +4,11 @@ import { freeipa } from "../../server/services";
 import { getServiceIpaSession } from "../ipa/service-account";
 import { toPgUuidArray } from "../postgres";
 import { providers } from "../providers";
+import type { AccountsActor } from "./authz";
 import { buildBaseGroup } from "./base-group";
 import { buildManagedGroupScopeCondition, buildMemberGroupScopeCondition } from "./group-sql";
 import * as localGroups from "./local-groups";
+import { posix } from "./posix";
 
 type DbRow = Record<string, unknown>;
 
@@ -146,13 +148,14 @@ export const getManagedGroups = async (params: { id: string; provider?: UserProv
 };
 
 export const create = async (params: {
+  actor: AccountsActor;
   provider: UserProvider;
   name: string;
   description?: string;
   posix?: boolean;
 }): Promise<MutationResult<BaseGroup>> => {
   if (params.provider === "local") {
-    if (params.posix) return { ok: false, error: "Local groups do not support POSIX mode", status: 400 };
+    if (params.posix) return { ok: true, data: await posix.createGroup({ id: params.actor.userId, roles: params.actor.roles }, params) };
     return localGroups.create({ name: params.name, description: params.description });
   }
   const serviceSession = await getServiceIpaSession();
@@ -188,9 +191,17 @@ export const remove = async (params: { id: string; provider?: UserProvider }): P
   });
 };
 
-export const makePosix = async (params: { id: string; provider?: UserProvider }): Promise<MutationResult<{ gidnumber: number | null }>> => {
-  const provider = params.provider ?? (await getGroup(params.id))?.provider;
-  if (provider === "local") return { ok: false, error: "Local groups do not support POSIX mode", status: 400 };
+export const makePosix = async (params: {
+  actor: AccountsActor;
+  id: string;
+  provider?: UserProvider;
+}): Promise<MutationResult<{ gidnumber: number | null }>> => {
+  const provider = (await getGroup(params.id))?.provider;
+  if (!provider) return { ok: false, error: "Group not found", status: 404 };
+  if (provider === "local") {
+    const result = await posix.provisionGroup({ id: params.actor.userId, roles: params.actor.roles }, params.id);
+    return { ok: true, data: { gidnumber: result.gidNumber } };
+  }
   const serviceSession = await getServiceIpaSession();
   if (!serviceSession.ok) return serviceSession;
   return providers.ipa.groups.makePosix({