@k2b/cloud 0.40.0 → 0.42.0

package/src/services/geo/service.ts

@@ -0,0 +1,300 @@
+import type { z } from "zod";
+import type { AccessSubject, CapabilityExecutionContext, RequestActor } from "../../contracts";
+import {
+  GeoAutocompleteDataSchema,
+  type GeoAutocompleteInput,
+  GeoAutocompleteInputSchema,
+  type GeoFunction,
+  GeoGeocodeDataSchema,
+  type GeoGeocodeInput,
+  GeoGeocodeInputSchema,
+  GeoPlaceSearchDataSchema,
+  type GeoPlaceSearchInput,
+  GeoPlaceSearchInputSchema,
+  GeoReverseDataSchema,
+  type GeoReverseInput,
+  GeoReverseInputSchema,
+} from "../../contracts/geo";
+import { createGeoBucket, GEO_TIMEOUT_MS } from "./bucket";
+import { createGeoCache, GEO_MAX_JSON_BYTES, geoCacheKey } from "./cache";
+import { geoReferenceCost, geoReserveCost } from "./costs";
+import { GeoError, GeoProviderError, limitExceeded } from "./errors";
+import { GeoapifyAdapter } from "./geoapify";
+import { createGeoLedger, geoPeriods } from "./ledger";
+import { cutGeoWindow, decodePolyline6, locateOnGeoLine, simplifyGeoLine } from "./polyline";
+import { createGeoRouteService } from "./route-service";
+import { type GeoConfig, geoPlan, readGeoConfig } from "./settings";
+
+export type GeoContext = Partial<Pick<CapabilityExecutionContext, "actor" | "accessSubject" | "locale" | "signal" | "requestId">>;
+export const geoIdentity = (context: GeoContext): { actor: RequestActor; accessSubject: AccessSubject } => {
+  const { actor, accessSubject } = context;
+  if (
+    !actor ||
+    !accessSubject ||
+    !(actor.kind === "user" ? actor.user?.id : actor.serviceAccount?.id) ||
+    !(accessSubject.type === "user" ? accessSubject.userId : accessSubject.serviceAccountId)
+  )
+    throw new GeoError("GEO_FORBIDDEN");
+  return { actor, accessSubject };
+};
+const bound = (name: string, value: number, min: number, max: number, integer = false) => {
+  if (!Number.isFinite(value) || value > max || value < min || (integer && !Number.isInteger(value)))
+    limitExceeded(name, value < min ? min : max, value);
+};
+const parse = <T>(schema: z.ZodType<T>, input: unknown): T => {
+  const parsed = schema.safeParse(input);
+  if (!parsed.success) throw new GeoError("GEO_UNSUPPORTED_OPTION");
+  return parsed.data;
+};
+const country = (value?: string) => {
+  if (value !== undefined && !/^[a-z]{2}$/i.test(value)) throw new GeoError("GEO_UNSUPPORTED_OPTION");
+};
+const area = (value?: GeoPlaceSearchInput["area"]) => {
+  if (!value) return;
+  if (value.type === "circle") bound("area.radiusMeters", value.radiusMeters, Number.MIN_VALUE, Number.MAX_SAFE_INTEGER);
+  else {
+    bound("area.west", value.west, -180, 180);
+    bound("area.east", value.east, -180, 180);
+    bound("area.south", value.south, -90, 90);
+    bound("area.north", value.north, -90, 90);
+    if (value.west >= value.east || value.south >= value.north) throw new GeoError("GEO_UNSUPPORTED_OPTION");
+  }
+};
+export const createGeoService = (
+  options: {
+    config?: () => Promise<GeoConfig>;
+    now?: () => Date;
+    adapter?: GeoapifyAdapter;
+    cache?: ReturnType<typeof createGeoCache>;
+    bucket?: ReturnType<typeof createGeoBucket>;
+    ledger?: ReturnType<typeof createGeoLedger>;
+  } = {},
+) => {
+  const now = options.now ?? (() => new Date());
+  const config = options.config ?? readGeoConfig;
+  const adapter = options.adapter ?? new GeoapifyAdapter({ now });
+  const cache = options.cache ?? createGeoCache();
+  const bucket = options.bucket ?? createGeoBucket();
+  const ledger = options.ledger ?? createGeoLedger();
+  const budgets = (settings: GeoConfig) => ({
+    timezone: settings.timezone,
+    monthlyCredits: settings.monthlyCredits,
+    personDailyCredits: settings.personDailyCredits,
+  });
+  const recordTransition = async (event: "monthly_budget_exhausted" | "provider_key_rejected", timezone: string, context: GeoContext) => {
+    const identity = geoIdentity(context);
+    try {
+      await ledger.recordTransition(event, timezone, { ...context, ...identity }, now());
+    } catch {
+      // The transaction rolls back the dedup row too, allowing the next refusal to record it.
+      // Preserve the original recovery details and paid/unknown costs on audit outages.
+      console.error("[geo] Audit transition could not be recorded", { event });
+    }
+  };
+  const configured = async (context: GeoContext) => {
+    geoIdentity(context);
+    const value = await config();
+    if (!value.apiKey.trim()) throw new GeoError("GEO_NOT_CONFIGURED");
+    return value;
+  };
+  const paid = async <T>(
+    fn: GeoFunction,
+    input: unknown,
+    context: GeoContext,
+    settings: GeoConfig,
+    schema: z.ZodType<T>,
+    request: (signal: AbortSignal) => Promise<T>,
+    limit?: number,
+    cacheInput = input,
+    empty: (value: T) => boolean = () => false,
+  ): Promise<T> => {
+    const identity = geoIdentity(context);
+    const locale = context.locale ?? "en";
+    const key = geoCacheKey(fn, cacheInput, locale);
+    const hit = await cache.get(key, schema);
+    if (hit !== null) return hit;
+    const deadline = AbortSignal.timeout(GEO_TIMEOUT_MS[fn]);
+    const signal = context.signal ? AbortSignal.any([context.signal, deadline]) : deadline;
+    const release = await bucket.acquire(fn, geoPlan(settings).rps);
+    let reserved: Awaited<ReturnType<typeof ledger.reserve>> | undefined;
+    let settlementAttempted = false;
+    const reference = geoReferenceCost({ fn, limit });
+    try {
+      // A canceled request which has not been sent never reserves provider credit.
+      signal.throwIfAborted();
+      reserved = await ledger.reserve(
+        identity.accessSubject,
+        budgets(settings),
+        geoReserveCost([{ fn, limit }]),
+        fn === "places" ? "places" : "address",
+        now(),
+      );
+      const response = await request(signal);
+      settlementAttempted = true;
+      await ledger.settle(reserved, reference);
+      const value = schema.safeParse(response);
+      if (!value.success || Buffer.byteLength(JSON.stringify({ data: response })) > GEO_MAX_JSON_BYTES)
+        throw new GeoProviderError("GEO_PROVIDER_FAILED", "known");
+      await cache.put(key, fn, value.data, empty(value.data));
+      return value.data;
+    } catch (cause) {
+      let error = cause instanceof GeoError ? cause : new GeoError("GEO_PROVIDER_FAILED");
+      if (error.code === "GEO_BUDGET_EXHAUSTED" && error.details.scope === "cloud") {
+        await recordTransition("monthly_budget_exhausted", settings.timezone, context);
+      }
+      if (reserved) {
+        const charge = cause instanceof GeoProviderError ? cause.charge : cause instanceof GeoError ? "known" : "unknown";
+        let settled = charge === "known" ? reference : 0;
+        let unknown = charge === "unknown" ? reserved.cost : 0;
+        if (!settlementAttempted) {
+          settlementAttempted = true;
+          try {
+            await ledger.settle(reserved, charge === "none" ? 0 : charge === "unknown" ? reserved.cost : reference);
+          } catch {
+            settled = 0;
+            unknown = reserved.cost;
+          }
+        }
+        if (error.code === "GEO_PROVIDER_FAILED" || error.code === "GEO_BUSY")
+          error = new GeoError(error.code, {
+            ...error.details,
+            costs: { settledCredits: settled / 1000, unknownCredits: unknown / 1000 },
+          });
+      }
+      if (cause instanceof GeoProviderError && cause.keyRejected) {
+        await recordTransition("provider_key_rejected", settings.timezone, context);
+      }
+      throw error;
+    } finally {
+      await release();
+    }
+  };
+  const routes = createGeoRouteService({ configured, adapter, cache, bucket, ledger, now, recordTransition });
+  return {
+    ...routes,
+    async autocomplete(input: GeoAutocompleteInput, context: GeoContext) {
+      const settings = await configured(context);
+      const value = parse(GeoAutocompleteInputSchema, input);
+      bound("text", value.text.length, 3, 300);
+      bound("text", value.text.trim().length, 3, 300);
+      bound("limit", value.limit ?? 5, 1, 5, true);
+      country(value.countryCode);
+      area(value.area);
+      return paid(
+        "autocomplete",
+        value,
+        context,
+        settings,
+        GeoAutocompleteDataSchema,
+        (signal) => adapter.autocomplete(value, settings.apiKey, context.locale ?? "en", signal),
+        value.limit,
+        { ...value, limit: value.limit ?? 5 },
+        (result) => !result.suggestions.length,
+      );
+    },
+    async geocode(input: GeoGeocodeInput, context: GeoContext) {
+      const settings = await configured(context);
+      const value = parse(GeoGeocodeInputSchema, input);
+      if (value.text !== undefined) {
+        bound("text", value.text.length, 1, 300);
+        bound("text", value.text.trim().length, 1, 300);
+      }
+      for (const [name, field] of Object.entries(value.fields ?? {}))
+        if (field !== undefined) bound(`fields.${name}`, field.length, 0, 200);
+      country(value.countryCode);
+      if (!!value.text?.trim() === !!Object.values(value.fields ?? {}).some((v) => v?.trim())) throw new GeoError("GEO_UNSUPPORTED_OPTION");
+      return paid("geocode", value, context, settings, GeoGeocodeDataSchema, async (signal) => {
+        const result = await adapter.geocode(value, settings.apiKey, context.locale ?? "en", signal);
+        if (!result.candidates.length) throw new GeoError("GEO_ADDRESS_NOT_FOUND");
+        if (result.candidates.length > 1) throw new GeoError("GEO_ADDRESS_AMBIGUOUS", { candidates: result.candidates });
+        return { address: result.candidates[0]!, provenance: result.provenance };
+      });
+    },
+    async reverse(input: GeoReverseInput, context: GeoContext) {
+      const settings = await configured(context);
+      const value = parse(GeoReverseInputSchema, input);
+      return paid("reverse", value, context, settings, GeoReverseDataSchema, async (signal) => {
+        const result = await adapter.reverse(value, settings.apiKey, context.locale ?? "en", signal);
+        if (!result.address) throw new GeoError("GEO_ADDRESS_NOT_FOUND");
+        return { address: result.address, provenance: result.provenance };
+      });
+    },
+    async searchPlaces(input: GeoPlaceSearchInput, context: GeoContext) {
+      const settings = await configured(context);
+      const value = parse(GeoPlaceSearchInputSchema, input);
+      bound("categories", value.categories.length, 1, 5, true);
+      bound("limit", value.limit ?? 20, 1, 20, true);
+      area(value.area);
+      const along = value.along;
+      if (along) {
+        bound("along.windowKm", along.toKm - along.fromKm, Number.MIN_VALUE, 200);
+        bound("along.fromKm", along.fromKm, 0, Number.MAX_SAFE_INTEGER);
+        bound("along.bufferMeters", along.bufferMeters ?? 1000, 100, 5000);
+      }
+      if ([value.near, value.area, value.along].filter(Boolean).length !== 1) throw new GeoError("GEO_UNSUPPORTED_OPTION");
+      const cut = along ? cutGeoWindow(decodePolyline6(along.polyline6), along.fromKm * 1000, along.toKm * 1000) : undefined;
+      const simplified = cut ? simplifyGeoLine(cut) : undefined;
+      const cacheInput = {
+        ...value,
+        limit: value.limit ?? 20,
+        categories: [...new Set(value.categories)],
+        ...(along ? { along: { ...along, bufferMeters: along.bufferMeters ?? 1000 } } : {}),
+      };
+      return paid<z.infer<typeof GeoPlaceSearchDataSchema>>(
+        "places",
+        value,
+        context,
+        settings,
+        GeoPlaceSearchDataSchema,
+        async (signal) => {
+          // Radial reduction and Douglas–Peucker can each move the line by one tolerance.
+          // Widen the provider corridor to cover the original cut; filter locally with the requested buffer.
+          const providerInput =
+            along && simplified
+              ? {
+                  ...value,
+                  // Twenty provider candidates still cost one credit; apply the caller's limit after local filtering.
+                  limit: 20,
+                  along: {
+                    ...along,
+                    bufferMeters: Math.min(100000, Math.ceil((along.bufferMeters ?? 1000) + 2 * simplified.toleranceMeters)),
+                  },
+                }
+              : value;
+          const result = await adapter.places(providerInput, settings.apiKey, context.locale ?? "en", signal, simplified?.line);
+          if (!cut || !along) return result;
+          const places = result.places
+            .map((place) => {
+              const position = locateOnGeoLine(place.point, cut);
+              return { ...place, ...position, atMeters: along.fromKm * 1000 + position.atMeters };
+            })
+            .filter((place) => place.distanceToRouteMeters <= (along.bufferMeters ?? 1000))
+            .sort((a, b) => a.atMeters - b.atMeters);
+          return {
+            ...result,
+            places: places.slice(0, value.limit ?? 20),
+            simplificationToleranceMeters: simplified!.toleranceMeters,
+            truncated: result.places.length === 20 && places.length < (value.limit ?? 20),
+          };
+        },
+        value.limit,
+        cacheInput,
+        (result) => !result.places.length,
+      );
+    },
+    async availability(context: GeoContext) {
+      const { accessSubject } = geoIdentity(context);
+      const settings = await config();
+      if (!settings.apiKey.trim()) {
+        const periods = geoPeriods(now(), settings.timezone);
+        return {
+          configured: false,
+          person: { exhausted: false, resetsAt: periods.person.resetsAt },
+          cloud: { exhausted: false, resetsAt: periods.cloud.resetsAt },
+        };
+      }
+      return { configured: true, ...(await ledger.availability(accessSubject, budgets(settings), now())) };
+    },
+  };
+};
+export const coreGeo = createGeoService();

package/src/services/geo/settings.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { GEO_PLAN_IDS } from "../../contracts/geo-admin";
+import { readStates } from "../settings/store";
+
+export const GEO_PLANS = {
+  free: { dailyCredits: 3000, rps: 5 },
+  api10: { dailyCredits: 10000, rps: 12 },
+  api25: { dailyCredits: 25000, rps: 15 },
+  api50: { dailyCredits: 50000, rps: 20 },
+  api100: { dailyCredits: 100000, rps: 25 },
+  api250: { dailyCredits: 250000, rps: 30 },
+} as const;
+const ConfigSchema = z.object({
+  apiKey: z.string(),
+  timezone: z.string(),
+  plan: z.enum(GEO_PLAN_IDS),
+  customRps: z.number().int().positive(),
+  customDailyCredits: z.number().int().positive(),
+  monthlyCredits: z.number().int().nonnegative(),
+  personDailyCredits: z.number().int().nonnegative(),
+});
+export type GeoConfig = z.infer<typeof ConfigSchema>;
+export const geoPlan = (config: GeoConfig) =>
+  config.plan === "custom" ? { rps: config.customRps, dailyCredits: config.customDailyCredits } : GEO_PLANS[config.plan];
+export const readGeoConfig = async (): Promise<GeoConfig> => {
+  // Direct encrypted-row reads: configuration checks never touch Valkey or put this key in its settings cache.
+  const keys = [
+    "geo.api_key",
+    "geo.plan",
+    "geo.custom_rps",
+    "geo.custom_daily_credits",
+    "geo.monthly_budget_credits",
+    "geo.person_daily_credits",
+    "app.timezone",
+  ];
+  const values = await readStates(keys);
+  const unreadable = keys.filter((key) => key.startsWith("geo.") && values.get(key)?.stored === "unreadable");
+  if (unreadable.length) console.warn("[geo] Unreadable settings; geo is not configured", { keys: unreadable });
+  return ConfigSchema.parse({
+    // A fallback budget must never admit paid work over an unreadable stored value.
+    apiKey: unreadable.length ? "" : values.get("geo.api_key")?.value,
+    plan: values.get("geo.plan")?.value,
+    customRps: values.get("geo.custom_rps")?.value,
+    customDailyCredits: values.get("geo.custom_daily_credits")?.value,
+    monthlyCredits: values.get("geo.monthly_budget_credits")?.value,
+    personDailyCredits: values.get("geo.person_daily_credits")?.value,
+    timezone: values.get("app.timezone")?.value,
+  });
+};

package/src/services/help/index.ts

@@ -3,9 +3,12 @@ import { appAudienceRoles, hasAnyAppRole } from "../../_internal/app-roles";
 import { getApp, listApps } from "../../_internal/registry";
 import type { AppRegistryEntry } from "../../contracts/registry";
 import type { RequestActor } from "../../contracts/shared";
+import type { RequestAuthority } from "../../server/middleware/auth";
 import { resolveAppPresentations } from "../../shared/app-presentation";
 import { type HelpArticleLink, helpLocaleChain, parseHelpReference } from "../../shared/help";
 import { lexHelpMarkdown, walkHelpTokens } from "../../shared/markdown";
+import { canUseApp } from "../app-access";
+import { discoverableApps } from "../app-discovery";
 import { logger } from "../logging";
 import { HELP_RESOURCE_PAGE_SIZE, type HelpSelection, hasHelpBm25, metadata, queryHelp } from "./store";
 import type { HelpReader } from "./types";
@@ -30,13 +33,16 @@ export const createHelpReader = (
   locale: string,
   viewer: RequestActor | undefined,
   dependencies: {
+    authority?: RequestAuthority | null;
     db?: SQL;
     listApps?: () => Promise<AppRegistryEntry[]>;
     getApp?: (appId: string) => Promise<AppRegistryEntry | null>;
   } = {},
 ): HelpReader => {
   const db = dependencies.db ?? sql;
-  const visible = (app: AppRegistryEntry | null): app is AppRegistryEntry => app !== null && canReadAppHelp(app, viewer);
+  const visible = (app: AppRegistryEntry | null): app is AppRegistryEntry =>
+    app !== null && (app.access !== undefined || canReadAppHelp(app, viewer));
+  const visibleApps = async (apps: (AppRegistryEntry | null)[]) => discoverableApps(dependencies.authority ?? null, apps.filter(visible));
   const selectionFor = (apps: AppRegistryEntry[]): HelpSelection[] =>
     apps.flatMap((app) =>
       app.help
@@ -52,12 +58,12 @@ export const createHelpReader = (
     );
   const select = async (appId?: string): Promise<HelpSelection[]> => {
     const apps = appId ? [await (dependencies.getApp ?? getApp)(appId)] : await (dependencies.listApps ?? listApps)();
-    return selectionFor(resolveAppPresentations(apps.filter(visible), locale));
+    return selectionFor(resolveAppPresentations(await visibleApps(apps), locale));
   };
   return {
     async manifest(appId) {
       const app = await (dependencies.getApp ?? getApp)(appId);
-      if (!visible(app) || !app.help) return null;
+      if (!visible(app) || !app.help || !(await canUseApp(dependencies.authority ?? null, app))) return null;
       const [corpus] = await db`SELECT 1 FROM help.corpora WHERE app_id=${app.id} AND manifest_hash=${app.help.manifestHash}`;
       if (!corpus) return null;
       const rows = await queryHelp(
@@ -110,10 +116,13 @@ export const createHelpReader = (
       const referencedApps = new Set([...references].map((reference) => reference.split("/")[0]));
       const apps = references.size
         ? resolveAppPresentations(
-            (referencedApps.size === 1 && referencedApps.has(input.appId)
-              ? [await (dependencies.getApp ?? getApp)(input.appId)]
-              : await (dependencies.listApps ?? listApps)()
-            ).filter((app): app is AppRegistryEntry => visible(app) && referencedApps.has(app.id)),
+            (
+              await visibleApps(
+                referencedApps.size === 1 && referencedApps.has(input.appId)
+                  ? [await (dependencies.getApp ?? getApp)(input.appId)]
+                  : await (dependencies.listApps ?? listApps)(),
+              )
+            ).filter((app) => referencedApps.has(app.id)),
             locale,
           )
         : [];

package/src/services/help/types.ts

@@ -1,5 +1,6 @@
 import type { AppRegistryHelpSummary } from "../../contracts/registry";
 import type { RequestActor } from "../../contracts/shared";
+import type { RequestAuthority } from "../../server/middleware/auth";
 import type { HelpAccessLevel, HelpArticleLink, HelpDocumentManifest, HelpKind } from "../../shared/help";
 
 export type HelpDocument = {
@@ -52,4 +53,8 @@ export type HelpReader = {
   search(input: HelpSearchInput): Promise<HelpMatch[]>;
   read(input: HelpReadInput): Promise<HelpArticle | null>;
 };
-export type HelpReaderFactory = (locale: string, viewer: RequestActor | undefined) => HelpReader;
+export type HelpReaderFactory = (
+  locale: string,
+  viewer: RequestActor | undefined,
+  options?: { authority?: RequestAuthority | null },
+) => HelpReader;

package/src/services/identity/invocation-actor.ts

@@ -28,7 +28,25 @@ export type ResolvedInvocationAuthority = {
   scopes: string[];
 };
 
-const provenance = (claims: CloudInvocationClaims): NonNullable<RequestActor["delegation"]> => ({
+export type InvocationPrincipalClaims = Pick<
+  CloudInvocationClaims,
+  | "sub"
+  | "principal_type"
+  | "session_kind"
+  | "scopes"
+  | "credential_id"
+  | "exp"
+  | "act"
+  | "credential_kind"
+  | "jti"
+  | "request_id"
+  | "mandate_id"
+  | "mandate_revision"
+  | "workload_type"
+  | "workload_id"
+>;
+
+const provenance = (claims: InvocationPrincipalClaims): NonNullable<RequestActor["delegation"]> => ({
   kind: "invocation",
   callingAppId: claims.act.sub.slice("app:".length),
   credentialKind: claims.credential_kind,
@@ -58,7 +76,7 @@ const mapServiceAccount = (row: ServiceAccountRow): ServiceAccount => ({
 });
 
 export const resolveInvocationAuthority = async (
-  claims: CloudInvocationClaims,
+  claims: InvocationPrincipalClaims,
   query: typeof sql = sql,
   groupsAdminOverride?: string[],
 ): Promise<ResolvedInvocationAuthority | null> => {

package/src/services/identity/issue-invocation.ts

@@ -0,0 +1,67 @@
+import type { SQL } from "bun";
+import { getApp } from "../../_internal/registry";
+import type { AppMeta } from "../../contracts/app";
+import { AppAccessDeniedError } from "../../server/middleware/app-access";
+import type { RequestAuthority } from "../../server/middleware/auth";
+import { canUseApp } from "../app-access";
+import { recordAppAccessDenied } from "../app-access-metrics";
+import { CLOUD_INVOCATION_TOKEN_TTL_SECONDS } from "./constants";
+import { resolveInvocationAuthority } from "./invocation-actor";
+import { type InvocationAuthority, signInvocationToken } from "./invocation-token";
+import { readIdentityGroupsAdmin } from "./runtime-config";
+
+/** Reload the principal while retaining the original credential's scopes and mobile-session restriction. */
+export const resolveIssuanceAuthority = async (
+  authority: InvocationAuthority,
+  callingAppId: string,
+  query?: Parameters<typeof resolveInvocationAuthority>[1],
+  groupsAdmin?: readonly string[],
+): Promise<RequestAuthority | null> => {
+  const preparedGroups = groupsAdmin ?? (query ? await readIdentityGroupsAdmin(query) : undefined);
+  return resolveInvocationAuthority(
+    {
+      ...authority,
+      act: { sub: `app:${callingAppId}` },
+      jti: crypto.randomUUID(),
+      exp: Math.floor(Date.now() / 1_000) + CLOUD_INVOCATION_TOKEN_TTL_SECONDS,
+    },
+    query,
+    preparedGroups ? [...preparedGroups] : undefined,
+  );
+};
+
+type RegisteredAppAccessOptions = {
+  db?: SQL;
+  getApp?: (id: string) => Promise<Pick<AppMeta, "id" | "access"> | null>;
+};
+
+export const requireRegisteredAppAccess = async (
+  authority: RequestAuthority | null,
+  appId: string,
+  options: RegisteredAppAccessOptions = {},
+): Promise<void> => {
+  const app = await (options.getApp ?? getApp)(appId).catch(() => null);
+  if (!app || !authority || !(await canUseApp(authority, app, { db: options.db }))) {
+    if (app) recordAppAccessDenied(app.id);
+    throw new AppAccessDeniedError(app ?? { id: appId });
+  }
+};
+
+/** The production broker seam for capability, widget, search, stream, and inter-app issuance. */
+export const issueInvocationToken = async (
+  params: Parameters<typeof signInvocationToken>[0],
+  dependencies: RegisteredAppAccessOptions & {
+    groupsAdmin?: readonly string[];
+    resolve?: typeof resolveIssuanceAuthority;
+    sign?: typeof signInvocationToken;
+  } = {},
+): ReturnType<typeof signInvocationToken> => {
+  const authority = await (dependencies.resolve ?? resolveIssuanceAuthority)(
+    params.authority,
+    params.callingAppId,
+    dependencies.db,
+    dependencies.groupsAdmin,
+  );
+  await requireRegisteredAppAccess(authority, params.targetAppId, dependencies);
+  return (dependencies.sign ?? signInvocationToken)(params);
+};

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

@@ -378,7 +378,7 @@ export const prepareIdentitySigner = async (purpose: SigningKeyPurpose): Promise
  */
 export const withActiveIdentitySigner = async <T>(
   purpose: SigningKeyPurpose,
-  callback: (signer: PreparedIdentitySigner & { issuer: string }, db: typeof sql) => Promise<T>,
+  callback: (signer: PreparedIdentitySigner & { issuer: string; readonly groupsAdmin?: readonly string[] }, db: typeof sql) => Promise<T>,
   options: { pool?: typeof sql; signal?: AbortSignal; timeoutMs?: number } = {},
 ): Promise<T> => {
   const timeoutMs = options.timeoutMs ?? 30_000;
@@ -404,7 +404,9 @@ export const withActiveIdentitySigner = async <T>(
     // holding a caller's transaction: every issuance needs just one connection.
     for (let attempt = 0; attempt < 2; attempt += 1) {
       const signer = await wait("signer refresh", () => prepareIdentitySigner(purpose));
-      const { issuer } = await wait("identity settings", getIdentityRuntimeConfig);
+      const { issuer, groupsAdmin } = await wait("identity settings", getIdentityRuntimeConfig);
+      // Keep this issuance independent of cache expiry while it waits for a connection or key lock.
+      const preparedGroupsAdmin = Object.freeze([...groupsAdmin]);
       const run = async (db: typeof sql): Promise<{ active: false } | { active: true; result: T }> => {
         // A caller released at its deadline must not sign once a connection frees up.
         check();
@@ -422,7 +424,7 @@ export const withActiveIdentitySigner = async <T>(
         check();
         if (!active) return { active: false };
         step = "signing";
-        const result = await callback({ ...signer, issuer }, db);
+        const result = await callback({ ...signer, issuer, groupsAdmin: preparedGroupsAdmin }, db);
         // Roll back what the callback wrote instead of committing a result the caller never gets.
         check();
         return { active: true, result };

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

@@ -1,6 +1,9 @@
+import type { SQL } from "bun";
 import { env } from "../../config/env";
 import { publicCloudOrigin } from "../../shared/app-url";
 import { get as getSetting } from "../settings";
+import { decryptValue } from "../settings/crypto";
+import { SETTINGS_MAP, validateSettingValue } from "../settings/defaults";
 import { CLOUD_INVOCATION_JWKS_PATH, CLOUD_OAUTH_JWKS_PATH, CLOUD_SESSION_JWKS_PATH, IDENTITY_REFRESH_TIMEOUT_MS } from "./constants";
 
 const RUNTIME_CONFIG_TTL_MS = 60_000;
@@ -29,6 +32,26 @@ const normalizeGroups = (value: unknown): string[] => {
   return groups.length > 0 ? groups : ["admins"];
 };
 
+/** Transaction-local admin groups for callers that already hold a connection.
+ * Never fill the process/settings cache with an uncommitted setting.
+ */
+export const readIdentityGroupsAdmin = async (db: SQL): Promise<readonly string[]> => {
+  const key = "freeipa.groups.admin";
+  const def = SETTINGS_MAP.get(key);
+  if (!def) throw new Error("Missing identity admin-group setting definition");
+  const [row] = await db<{ value: string }[]>`SELECT value FROM settings.entries WHERE key = ${key}`;
+  let groups: unknown = def.default;
+  if (row) {
+    try {
+      const validated = validateSettingValue(def, await decryptValue(row.value));
+      if (validated.ok) groups = validated.value;
+    } catch {
+      // Match the settings store's unreadable-row fallback without mutating the row.
+    }
+  }
+  return Object.freeze(normalizeGroups(groups));
+};
+
 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);

package/src/services/index.ts

@@ -1,4 +1,5 @@
 // biome-ignore-all assist/source/organizeImports: Preserve grouped service barrel exports.
+export { appAccessAuthority, canUseApp, usableAppIds } from "./app-access";
 export { ipa } from "./ipa";
 export { accounts } from "./accounts";
 export { accountsAppService } from "./accounts";
@@ -227,6 +228,8 @@ export type { WebVitalsOverview, WebVitalsQuery, WebVitalMetric, WebVitalName }
 
 export { mail } from "./outgoing-mail";
 export type {
+  MailContent,
+  MailContentContext,
   MailProfile,
   MailAttachment,
   MailMessage,
@@ -257,3 +260,11 @@ export {
   type NewBrowserSignInNotifier,
 } from "./known-browsers";
 export { LASTING_ACCESS_SIGN_IN_SECONDS, requireConfirmedBrowserSignIn } from "./session/recent";
+
+export { deviceOffersApproval } from "./approvals/device";
+
+/** Core-owned geo implementation; applications use geoClient from the server entry. */
+export { coreGeo, createGeoService } from "./geo/service";
+export { migrate as migrateGeo } from "./geo/migrate";
+
+export { coreGeoMap, createGeoMapService } from "./geo/map";