@k2b/cloud 0.7.0 → 0.8.0

package/src/config/env.ts

@@ -1,57 +1,150 @@
 /**
- * Environment variable parsing.
- * All env vars are parsed and validated here, then exported as typed `env` object.
+ * Platform environment registry.
+ * Every variable a Cloud process reads is declared here or in an application's
+ * `src/env.ts`; values are parsed lazily on access (see `define-env.ts`).
  */
+import { z } from "zod";
+import { defineEnv, envBoolean, envList } from "./define-env";
 
-const str = (key: string, fallback: string = ""): string => process.env[key] ?? fallback;
-
-const optional = (key: string): string | undefined => process.env[key]?.trim() || undefined;
-
-const bool = (key: string, fallback: boolean): boolean => {
-  const value = process.env[key]?.trim().toLowerCase();
-  if (!value) return fallback;
-  return value === "true" || value === "1";
-};
-
-const syncReplicas = (): 1 | 3 | 5 => {
-  const value = str("SYNC_REPLICAS", "3").trim();
-  if (value === "1") return 1;
-  if (value === "3") return 3;
-  if (value === "5") return 5;
-  throw new Error("SYNC_REPLICAS must be 1, 3, or 5");
-};
-
-const list = (key: string): string[] =>
-  (process.env[key] ?? "")
-    .split(",")
-    .map((entry) => entry.trim())
-    .filter(Boolean);
-
-export const env = {
-  // Application (infrastructure — not changeable at runtime)
-  APP_SECRET: str("APP_SECRET"),
-  IS_DEVELOPMENT: process.env.NODE_ENV === "development",
-
-  // Admin login (temporary first access or recovery — Core only, no IPA required)
-  ADMIN_LOGIN_TOKEN: str("ADMIN_LOGIN_TOKEN"),
-
-  // NATS / @k2b/sync (Postgres and Redis are read by Bun from DATABASE_URL / REDIS_URL)
-  /** Bootstrap servers, comma-separated `nats://host:port` URLs. Required by `connectNats()`. */
-  NATS_SERVERS: list("NATS_SERVERS"),
-  /** Sync namespace shared by every app of one Cloud installation (e.g. `dev`, `prod`). Required. */
-  SYNC_NAMESPACE: str("SYNC_NAMESPACE"),
-  /** Persistent stream replica count; consistent across the installation. */
-  SYNC_REPLICAS: syncReplicas(),
-  /** Path to a mounted NATS `.creds` file (JWT + NKey). Unset = server-side no-auth. */
-  NATS_CREDS_FILE: optional("NATS_CREDS_FILE"),
-  /** Path to a mounted CA certificate; enables TLS with that CA. Unset = plain TCP. */
-  NATS_TLS_CA_FILE: optional("NATS_TLS_CA_FILE"),
-  /**
-   * Default true: only dial the servers listed in NATS_SERVERS. Clustered
-   * nodes gossip their peers' advertised addresses, which are Docker-internal
-   * hostnames (`ipa_nats_2`) that host-side clients (tests, `dev:cld` tooling)
-   * cannot resolve. Set to `false` when clients can reach every advertised
-   * address and should learn new nodes at runtime.
-   */
-  NATS_IGNORE_CLUSTER_UPDATES: bool("NATS_IGNORE_CLUSTER_UPDATES", true),
-} as const;
+const syncReplicas = z
+  .enum(["1", "3", "5"], { error: "must be 1, 3, or 5" })
+  .transform((value): 1 | 3 | 5 => (value === "1" ? 1 : value === "3" ? 3 : 5));
+
+const registry = defineEnv({
+  // Process
+  NODE_ENV: {
+    schema: z.string(),
+    doc: "Release images set `production`; `development` enables development-only behavior such as insecure cookies and HTTP issuers.",
+  },
+  HOSTNAME: {
+    schema: z.string(),
+    doc: "Container or host name; the default instance identity in worker leases and gateway registration.",
+  },
+
+  // Infrastructure
+  DATABASE_URL: {
+    schema: z.string(),
+    example: "postgresql://ipa:ipa@localhost:5432/ipa",
+    doc: "Postgres connection read by Bun SQL and by application-owned pools.",
+  },
+  REDIS_URL: {
+    schema: z.string(),
+    aliases: ["VALKEY_URL"],
+    example: "redis://localhost:6379",
+    doc: "Valkey connection used by Bun Redis for caches and rate limits.",
+  },
+  NATS_SERVERS: {
+    schema: envList,
+    default: [],
+    example: "nats://localhost:4222",
+    doc: "Comma-separated NATS JetStream bootstrap servers; the client dials all of them.",
+  },
+  SYNC_NAMESPACE: {
+    schema: z.string(),
+    default: "",
+    example: "dev",
+    doc: "Sync namespace shared by every app of one installation; isolates its NATS resources from other installations on the same cluster.",
+  },
+  SYNC_REPLICAS: {
+    schema: syncReplicas,
+    default: 3,
+    example: "1",
+    doc: "Persistent JetStream replica count (1, 3 or 5); keep it consistent across the installation and migrate existing resources before changing it.",
+  },
+  NATS_CREDS_FILE: {
+    schema: z.string(),
+    doc: "Path to a mounted NATS `.creds` file (JWT and NKey); unset means server-side no-auth.",
+  },
+  NATS_TLS_CA_FILE: {
+    schema: z.string(),
+    doc: "Path to a mounted CA certificate that enables TLS to NATS; unset means plain TCP.",
+  },
+  NATS_IGNORE_CLUSTER_UPDATES: {
+    schema: envBoolean,
+    default: true,
+    example: "true",
+    doc: "Only dial the listed servers and ignore cluster-advertised peer addresses; set to `false` when every advertised address is reachable.",
+  },
+
+  // Installation
+  APP_URL: {
+    schema: z.string(),
+    example: "localhost:3000",
+    doc: "Public Cloud URL used to bootstrap the `app.url` setting; the stored setting wins once written.",
+  },
+  APP_SECRET: {
+    schema: z.string(),
+    default: "",
+    scope: "secret",
+    example: "change-me-generate-with-openssl-rand-hex-32",
+    doc: "Deployment-wide secret for at-rest settings encryption and signed cursors; generate once with `openssl rand -hex 32` and never change it after data has been written.",
+  },
+  ADMIN_LOGIN_TOKEN: {
+    schema: z.string(),
+    default: "",
+    scope: "secret",
+    doc: "Core only: temporary first-administrator or recovery login token; remove it after normal administrator sign-in works.",
+  },
+
+  // Identity and OAuth
+  CLOUD_IDENTITY_KEY_ENCRYPTION_KEY: {
+    schema: z.string(),
+    scope: "secret",
+    example: "change-me-generate-with-openssl-rand-hex-32",
+    doc: "Core only: 64-hex KEK for platform identity signing keys stored in Postgres; generate once with `openssl rand -hex 32` and never distribute it to other apps.",
+  },
+  CLOUD_IDENTITY_NEXT_KEY: {
+    schema: z.string(),
+    scope: "secret",
+    doc: "Core only: pre-distributed next KEK before promoting it to current; cannot be combined with `CLOUD_IDENTITY_PREVIOUS_KEY`.",
+  },
+  CLOUD_IDENTITY_PREVIOUS_KEY: {
+    schema: z.string(),
+    scope: "secret",
+    doc: "Core only: old KEK set during an explicit rolling rewrap of stored identity signing keys, then removed.",
+  },
+  CLOUD_OAUTH_BROKER_SECRET: {
+    schema: z.string(),
+    scope: "secret",
+    doc: "Core and OAuth only: 64-hex secret that lets the OAuth app request token signatures from Core; generate independently with `openssl rand -hex 32`.",
+  },
+  CLOUD_CORE_INTERNAL_ORIGIN: {
+    schema: z.string(),
+    doc: "Direct Core listener origin for OAuth issuance, mandate-backed background work and internal callbacks; host-run callers use the Core port, not the gateway.",
+  },
+  CLOUD_APP_CREDENTIAL: {
+    schema: z.string(),
+    scope: "secret",
+    doc: "App-bound workload credential provisioned through Core's admin workload API; background apps such as Mail need one with `identity:invoke`.",
+  },
+  CLOUD_IDENTITY_JWKS_ORIGIN: {
+    schema: z.string(),
+    doc: "Optional private origin of the Core listener for session and invocation JWKS; unset fetches keys from the public issuer origin.",
+  },
+  CLOUD_OAUTH_JWKS_ORIGIN: {
+    schema: z.string(),
+    doc: "Optional private origin of the OAuth listener for OAuth JWKS; unset fetches keys from the public issuer origin.",
+  },
+
+  // Build and standalone development
+  APP_DIR: {
+    schema: z.string(),
+    scope: "development",
+    doc: "Application directory for standalone consumers running `@k2b/cloud/scripts/build.ts` or the SSR dev server outside the monorepo; defaults to the package directory.",
+  },
+
+  // Desktop
+  CLOUD_DESKTOP_SQLITE_PATH: {
+    schema: z.string(),
+    scope: "development",
+    doc: "SQLite file used by `desktop.sql` in the Bun desktop process; defaults to `.local/desktop.sqlite` in the working directory.",
+  },
+});
+
+type PlatformEnv = typeof registry & { readonly IS_DEVELOPMENT: boolean };
+
+/** Platform environment; `IS_DEVELOPMENT` derives from `NODE_ENV === "development"`. */
+export const env: PlatformEnv = Object.defineProperty(registry as PlatformEnv, "IS_DEVELOPMENT", {
+  enumerable: true,
+  get: () => registry.NODE_ENV === "development",
+});

package/src/config/index.ts

@@ -1,6 +1,8 @@
 /**
  * Main config export.
- * Re-exports env vars. SSR config is per-app via defineApp().
+ * Re-exports the platform environment registry and the registry factory used
+ * by application `src/env.ts` files. SSR config is per-app via defineApp().
  */
 
+export { defineEnv, type EnvRegistry, type EnvScope, type EnvSpec, type EnvSpecs, envBoolean, envList, envString } from "./define-env";
 export { env } from "./env";

package/src/contracts/capabilities.ts

@@ -1,5 +1,12 @@
-import { CapabilityStreamSchema, CapabilityStreamPolicySchema, type CapabilityStream, type CapabilityStreamDefinition } from "./capability-streams";
+import {
+  type CapabilityStream,
+  type CapabilityStreamDefinition,
+  CapabilityStreamPolicySchema,
+  CapabilityStreamSchema,
+} from "./capability-streams";
+
 export * from "./capability-streams";
+
 import { z } from "zod";
 import { CommandPathSchema } from "./commands";
 import type { AccessSubject, RequestActor, User } from "./shared";

package/src/contracts/index.ts

@@ -1,19 +1,17 @@
 export * from "./account-categories";
 export * from "./announcements";
 export * from "./app";
+export * from "./app-approval";
 export * from "./capabilities";
+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";
-
-// Core app bar administration and shared shortcut values.
-export { RailAccessSchema, RailAdminInputSchema, RailAdminSchema, type RailAdminEntry, type RailAdminState } from "./rail-admin";
-export type { RailShortcut } from "./rail-preferences";
-
-export * from "./commands";

package/src/contracts/registry.ts

@@ -51,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;
 };

package/src/contracts/shared.ts

@@ -289,9 +289,18 @@ 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("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.") }),
 ]);
 

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,13 +10,19 @@ 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,
   appRegistry,
+  CAPABILITY_REGISTRY_CONFIG,
   capabilityRegistry,
   getApp,
   listApps,

package/src/server/index.ts

@@ -8,8 +8,8 @@ export { defineHelp, defineHelpCollection, type HelpCollection, type HelpDefinit
 export { DEFAULT_LOCALE, getLocale, LOCALE_COOKIE, LOCALE_HEADER, locale, preferredLocale, resolveLocale } from "./locale";
 export type {
   AuthContext,
-  InvocationProvenance,
   InvocationExpectation,
+  InvocationProvenance,
   RateLimitConfig,
   RateLimitRouteOverride,
   RequestActor,
@@ -26,8 +26,8 @@ export {
   openApiMeta,
   rateLimit,
   rejectReservedWorkloadCredential,
-  requireInvocation,
   requestLogger,
+  requireInvocation,
   requiresAdmin,
   requiresAuth,
   requiresIpa,

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

@@ -1,10 +1,10 @@
 import { createHash } from "node:crypto";
-import type { Principal, PermissionLevel } from "./access";
+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))])
+  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 <T extends { principal: Principal }>(entries: T[]): Promise<(T & { displayName: string; avatarHash?: string | null })[]> => {
+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/services/accounts/notification-sender.ts

@@ -3,7 +3,12 @@ import type { TypedNotificationSendResult } from "../notifications/platform";
 export type AccountNotificationDeliveryResult = Pick<TypedNotificationSendResult, "id" | "status">;
 
 export type AccountsNotificationSender = {
-  sendLoginLink: (input: { email: string; token: string; magicLink: string; locale?: string }) => Promise<AccountNotificationDeliveryResult>;
+  sendLoginLink: (input: {
+    email: string;
+    token: string;
+    magicLink: string;
+    locale?: string;
+  }) => Promise<AccountNotificationDeliveryResult>;
   sendFreeIpaWelcome: (input: {
     userId: string;
     uid: string;
@@ -11,7 +16,12 @@ export type AccountsNotificationSender = {
     accountExpires: string | null;
     locale?: string;
   }) => Promise<AccountNotificationDeliveryResult>;
-  sendLocalWelcome: (input: { userId: string; email: string; accountExpires: string | null; locale?: string }) => Promise<AccountNotificationDeliveryResult>;
+  sendLocalWelcome: (input: {
+    userId: string;
+    email: string;
+    accountExpires: string | null;
+    locale?: string;
+  }) => Promise<AccountNotificationDeliveryResult>;
   sendRequestDenied: (input: {
     requestId: string;
     userId: string;

package/src/services/announcements/index.ts

@@ -1,11 +1,7 @@
-import { requestCacheRedis } from "../request-cache-redis";
 import { err, fail, ok, type Result } from "@k2b/stdlib";
 import { sql } from "bun";
 import { HTTPException } from "hono/http-exception";
-import { hasRole, type User } from "../../contracts/shared";
 import { z } from "zod";
-import { AnnouncementDisplayEntrySchema } from "../../contracts/announcements";
-import { claimCacheFill, completeCacheFill } from "../cache-fill";
 import type {
   AnnouncementCookieState,
   AnnouncementDisplayEntry,
@@ -13,8 +9,12 @@ import type {
   CreateAnnouncement,
   UpdateAnnouncement,
 } from "../../contracts/announcements";
+import { AnnouncementDisplayEntrySchema } from "../../contracts/announcements";
+import { hasRole, type User } from "../../contracts/shared";
 import { markdown } from "../../shared/markdown";
+import { claimCacheFill, completeCacheFill } from "../cache-fill";
 import { logger } from "../logging";
+import { requestCacheRedis } from "../request-cache-redis";
 
 const log = logger("announcements");
 const ACTIVE_CACHE_KEY = "appglobalcache:shared:announcements:v1";

package/src/services/app-approval.ts

@@ -1,23 +1,24 @@
 import { createHash, randomBytes, randomInt, timingSafeEqual } from "node:crypto";
-import { sql, type SQL } from "bun";
+import { type SQL, sql } from "bun";
+import { env } from "../config/env";
+import { type AccountCategory, accountCategory } from "../contracts/account-categories";
 import {
-  APP_APPROVAL_LIMITS as limits,
   APP_APPROVAL_PATH,
   APP_APPROVAL_PROTOCOL,
-  AppDevicePublicKeySchema,
-  appDeviceProofMessage,
-  appPairingProofMessage,
   type AppDevicePublicKey,
+  AppDevicePublicKeySchema,
   type AppDeviceRequest,
   type AppDeviceView,
   type AppPendingLogin,
+  appDeviceProofMessage,
+  appPairingProofMessage,
+  APP_APPROVAL_LIMITS as limits,
 } from "../contracts/app-approval";
-import { accountCategory, type AccountCategory } from "../contracts/account-categories";
+import { publicCloudOrigin } from "../shared/app-url";
 import { isAccountCategoryAllowed } from "./account-category-policy";
 import { audit } from "./audit";
-import { decryptValue } from "./settings/crypto";
-import { publicCloudOrigin } from "../shared/app-url";
 import { CORE_SETTINGS } from "./settings/core-settings";
+import { decryptValue } from "./settings/crypto";
 
 export class AppApprovalError extends Error {
   constructor(
@@ -47,13 +48,13 @@ export const readAppApprovalConfig = async (db: SQL = sql, requireAppOrigin = tr
   const adminPairing = values.get("user.app_approval.admin_pairing") ?? false;
   if (typeof enabled !== "boolean" || typeof adminPairing !== "boolean") return reject("UNAVAILABLE", 503);
   // The issuer is the operator's canonical URL, never the request Host header.
-  const rawIssuer = values.get("app.url") ?? process.env.APP_URL ?? "localhost:3000";
+  const rawIssuer = values.get("app.url") ?? env.APP_URL ?? "localhost:3000";
   const rawOrigin = values.get("user.app_approval.origin") ?? CORE_SETTINGS["user.app_approval.origin"].default;
   const origin = (value: unknown) => {
     if (typeof value !== "string") return reject("UNAVAILABLE", 503);
     try {
       const url = new URL(value);
-      const development = process.env.NODE_ENV !== "production" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+      const development = env.NODE_ENV !== "production" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
       if (
         (url.protocol !== "https:" && !(url.protocol === "http:" && development)) ||
         url.username ||

package/src/services/identity/key-config.ts

@@ -1,5 +1,6 @@
 import { crypto } from "@k2b/stdlib";
 import { getProcessApplicationId } from "../../_internal/process-identity";
+import { env } from "../../config/env";
 
 const KEY_PATTERN = /^[0-9a-f]{64}$/i;
 
@@ -27,9 +28,9 @@ export const readIdentityKeyEncryptionConfig = async (): Promise<IdentityKeyEncr
   if (getProcessApplicationId() !== "core") {
     throw new Error("Private Cloud identity keys may only be loaded by the Core application");
   }
-  const current = parseKey("CLOUD_IDENTITY_KEY_ENCRYPTION_KEY", process.env.CLOUD_IDENTITY_KEY_ENCRYPTION_KEY, true)!;
-  const previous = parseKey("CLOUD_IDENTITY_PREVIOUS_KEY", process.env.CLOUD_IDENTITY_PREVIOUS_KEY, false);
-  const next = parseKey("CLOUD_IDENTITY_NEXT_KEY", process.env.CLOUD_IDENTITY_NEXT_KEY, false);
+  const current = parseKey("CLOUD_IDENTITY_KEY_ENCRYPTION_KEY", env.CLOUD_IDENTITY_KEY_ENCRYPTION_KEY, true)!;
+  const previous = parseKey("CLOUD_IDENTITY_PREVIOUS_KEY", env.CLOUD_IDENTITY_PREVIOUS_KEY, false);
+  const next = parseKey("CLOUD_IDENTITY_NEXT_KEY", env.CLOUD_IDENTITY_NEXT_KEY, false);
   const currentIdentified = await identify(current);
   const previousIdentified = previous ? await identify(previous) : null;
   const nextIdentified = next ? await identify(next) : null;
@@ -37,6 +38,7 @@ export const readIdentityKeyEncryptionConfig = async (): Promise<IdentityKeyEncr
   if (new Set(ids).size !== ids.length) {
     throw new Error("Configured Cloud identity KEKs must be distinct");
   }
-  if (previousIdentified && nextIdentified) throw new Error("Configure either CLOUD_IDENTITY_PREVIOUS_KEY or CLOUD_IDENTITY_NEXT_KEY, not both");
+  if (previousIdentified && nextIdentified)
+    throw new Error("Configure either CLOUD_IDENTITY_PREVIOUS_KEY or CLOUD_IDENTITY_NEXT_KEY, not both");
   return { current: currentIdentified, previous: previousIdentified, next: nextIdentified };
 };

package/src/services/identity/runtime-config.ts

@@ -1,3 +1,4 @@
+import { env } from "../../config/env";
 import { publicCloudOrigin } from "../../shared/app-url";
 import { get as getSetting } from "../settings";
 import { CLOUD_INVOCATION_JWKS_PATH, CLOUD_OAUTH_JWKS_PATH, CLOUD_SESSION_JWKS_PATH } from "./constants";
@@ -28,7 +29,7 @@ const normalizeGroups = (value: unknown): string[] => {
   return groups.length > 0 ? groups : ["admins"];
 };
 
-const resolveCoreJwksUrl = (issuer: string, path: string, transportOrigin = process.env.CLOUD_IDENTITY_JWKS_ORIGIN?.trim()): URL => {
+const resolveCoreJwksUrl = (issuer: string, path: string, transportOrigin = env.CLOUD_IDENTITY_JWKS_ORIGIN): URL => {
   if (!transportOrigin) return new URL(path, issuer);
   const origin = new URL(transportOrigin);
   if (origin.protocol !== "http:" && origin.protocol !== "https:") {
@@ -37,13 +38,13 @@ const resolveCoreJwksUrl = (issuer: string, path: string, transportOrigin = proc
   return new URL(path, origin);
 };
 
-export const resolveSessionJwksUrl = (issuer: string, transportOrigin = process.env.CLOUD_IDENTITY_JWKS_ORIGIN?.trim()): URL =>
+export const resolveSessionJwksUrl = (issuer: string, transportOrigin = env.CLOUD_IDENTITY_JWKS_ORIGIN): URL =>
   resolveCoreJwksUrl(issuer, CLOUD_SESSION_JWKS_PATH, transportOrigin);
 
-export const resolveInvocationJwksUrl = (issuer: string, transportOrigin = process.env.CLOUD_IDENTITY_JWKS_ORIGIN?.trim()): URL =>
+export const resolveInvocationJwksUrl = (issuer: string, transportOrigin = env.CLOUD_IDENTITY_JWKS_ORIGIN): URL =>
   resolveCoreJwksUrl(issuer, CLOUD_INVOCATION_JWKS_PATH, transportOrigin);
 
-export const resolveOAuthJwksUrl = (issuer: string, transportOrigin = process.env.CLOUD_OAUTH_JWKS_ORIGIN?.trim()): URL => {
+export const resolveOAuthJwksUrl = (issuer: string, transportOrigin = env.CLOUD_OAUTH_JWKS_ORIGIN): URL => {
   if (!transportOrigin) return new URL(CLOUD_OAUTH_JWKS_PATH, issuer);
 
   const url = new URL(CLOUD_OAUTH_JWKS_PATH, transportOrigin);
@@ -56,7 +57,7 @@ export const resolveOAuthJwksUrl = (issuer: string, transportOrigin = process.en
 const load = async (): Promise<IdentityRuntimeConfig> => {
   const [appUrl, rawGroupsAdmin] = await Promise.all([getSetting<string>("app.url"), getSetting<unknown>("freeipa.groups.admin")]);
   const issuer = publicCloudOrigin(appUrl);
-  if (process.env.NODE_ENV === "production" && new URL(issuer).protocol !== "https:") {
+  if (env.NODE_ENV === "production" && new URL(issuer).protocol !== "https:") {
     throw new Error("Cloud identity issuer must use HTTPS in production");
   }
   return {

package/src/services/ipa/posix.ts

@@ -1,4 +1,4 @@
-import { sql } from "bun";
+import type { sql } from "bun";
 
 /** Mirror directory-owned attributes, including missing values; never apply local defaults. */
 export const mirrorIpaPosix = async (

package/src/services/ipa/sync.ts

@@ -6,9 +6,9 @@ import { applyIpaAccountTransitionPolicy } from "../accounts/switching";
 import { getFreeIpaConfig } from "../freeipa-config";
 import { logger } from "../logging";
 import { session } from "../session";
-import { mirrorIpaPosix } from "./posix";
 import * as settings from "../settings";
 import { buildEffectiveIpaGroupsByUid } from "./effective-groups";
+import { mirrorIpaPosix } from "./posix";
 import { calculateIpaProfileFromEffectiveProjection, getEffectiveUserGroups } from "./profile";
 import { createIpaRuntimeCheckpoint, type IpaSyncRuntime } from "./runtime";
 import { assessIpaDestructionGuard, formatIpaDestructionGuardFailure, readCompleteIpaList, selectStaleLocalIpaRows } from "./sync-planning";

package/src/services/logging/index.ts

@@ -1,10 +1,10 @@
-import { readWebVitals } from "./web-vitals";
 import { sql } from "bun";
 import type { PaginationParams } from "../../contracts/shared";
 import { escapeLikePattern, parsePgJsonRecord, toPgTextArray } from "../postgres";
 import { registerSettings } from "../settings/defaults";
 import { redactMetadata } from "./redaction";
 import { observeSyncEvent, TRACE_STUCK_AFTER_MS, trace } from "./trace";
+import { readWebVitals } from "./web-vitals";
 
 export type {
   TraceAttributes,

package/src/services/logging/trace.ts

@@ -1,7 +1,7 @@
-import { getProcessApplicationId } from "../../_internal/process-identity";
 import { createHash, randomBytes } from "node:crypto";
 import type { SyncEvent } from "@k2b/sync";
 import { sql } from "bun";
+import { getProcessApplicationId } from "../../_internal/process-identity";
 import type { PaginationParams } from "../../contracts/shared";
 import { escapeLikePattern, parsePgJsonRecord, toPgTextArray } from "../postgres";
 import { isSensitiveMetadataKey, REDACTED, redactMetadata } from "./redaction";

package/src/services/mandates/index.ts

@@ -9,9 +9,9 @@ import { parsePgJsonValue } from "../postgres";
 import { isMandatePolicyNarrowing, type MandatePolicyV1, MandatePolicyV1Schema, mandatePolicyAllows, parseMandatePolicy } from "./policy";
 
 export {
-  CapabilityGrantsSchema,
-  CapabilityGrantSchema,
   type CapabilityGrant,
+  CapabilityGrantSchema,
+  CapabilityGrantsSchema,
   capabilityGrantAllows,
   isMandatePolicyNarrowing,
   MANDATE_POLICY_MAX_IDENTIFIERS,
@@ -20,6 +20,9 @@ export {
   MandatePolicyV1Schema,
   mandatePolicyAllows,
   parseMandatePolicy,
+  type TaskGrant,
+  TaskGrantSchema,
+  TaskGrantsSchema,
 } from "./policy";
 
 export type MandateState = "active" | "paused" | "revoked";