@k2b/cloud 0.46.0 → 0.47.0

package/src/ai/default-tool-contracts.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { chartDataIssue, chartDateTime, chartDrawingIssue, chartSteppingIssue, cloudAiChartMarks } from "./chart-block";
+import { chartDataIssue, chartDrawingIssue, cloudAiChartMarks } from "./chart-block";
 
 const ToneSchema = z.enum(["neutral", "blue", "teal", "green", "amber", "red"]);
 
@@ -28,261 +28,30 @@ export const CLOUD_AI_VIEW_MAX_MARKS = CLOUD_AI_CHART_MAX_SERIES * CLOUD_AI_CHAR
  */
 export const CLOUD_AI_GROUP_MAX_CHARTS = 6;
 
-// Every chart schema is built by a function whose call is marked pure, so a bundle that imports neither chart contract
-// leaves them out. App frames include the app contract through `cloud.chart()`.
-export const cloudAiNumberFormatSchema = () =>
-  z
-    .strictObject({
-      style: z.enum(["number", "percent", "currency"]).optional(),
-      currency: z
-        .string()
-        .regex(/^[A-Z]{3}$/)
-        .optional(),
-      // Units fit after a value in the shared renderer, like the existing gauge unit.
-      unit: z.string().trim().min(1).max(12).optional(),
-      // Intl.NumberFormat supports this precision; table formats already use 0..10.
-      decimals: z.number().int().min(0).max(10).optional(),
-      compact: z.boolean().optional(),
-    })
-    .superRefine((value, ctx) => {
-      if ((value.style === "currency") !== (value.currency !== undefined))
-        ctx.addIssue({ code: "custom", path: ["currency"], message: "Currency is required exactly when style is currency." });
-    });
-const dateFormatSchema = () => z.strictObject({ date: z.enum(["day", "minute", "second"]) });
-export const cloudAiFormatSchema = () => z.union([cloudAiNumberFormatSchema(), dateFormatSchema()]);
-export type CloudAiNumberFormat = z.output<ReturnType<typeof cloudAiNumberFormatSchema>>;
-export type CloudAiDateFormat = z.output<ReturnType<typeof dateFormatSchema>>;
-export type CloudAiFormat = CloudAiNumberFormat | CloudAiDateFormat;
+import {
+  type ChartInput as CloudAiChartInput,
+  type ChartDateFormat as CloudAiDateFormat,
+  type ChartFormat as CloudAiFormat,
+  type ChartNumberFormat as CloudAiNumberFormat,
+  chartKinds,
+  chartParts,
+  chartSchema,
+  chartKindSchema as cloudAiChartKindSchema,
+  chartFormatSchema as cloudAiFormatSchema,
+  chartNumberFormatSchema as cloudAiNumberFormatSchema,
+} from "@k2b/editor/charts";
 
-export const cloudAiChartKindSchema = () =>
-  z.enum(["bar", "line", "scatter", "pie", "donut", "histogram", "gauge", "sparkline", "boxplot", "heatmap", "barGauge", "stat"]);
+export type { CloudAiChartInput, CloudAiDateFormat, CloudAiFormat, CloudAiNumberFormat };
+// Portable formats and chart types retain their existing Cloud export names.
+export { cloudAiChartKindSchema, cloudAiFormatSchema, cloudAiNumberFormatSchema };
 
-const chartParts = (limits = true) => {
-  const ChartLabel = limits ? z.string().trim().min(1).max(80) : z.union([z.string(), z.number().transform(String)]);
-  const ChartTooltip = z
-    .strictObject({ label: ChartLabel.optional(), format: cloudAiNumberFormatSchema().optional() })
-    .describe("All kinds: what tooltips and the data table call the value and how they format it; axes keep their own format.");
-  // Missing observations stay numeric so the renderer can omit them with its finite-value checks.
-  const ChartNumber = limits
-    ? z.number()
-    : z
-        .custom<number>((value) => typeof value === "number", "Expected a number, null or undefined.")
-        .nullable()
-        .optional()
-        .transform((value) => value ?? Number.NaN);
-  const list = <T extends z.ZodType>(item: T, min: number, max?: number, message?: string) => {
-    const array = z.array(item);
-    const bounded = limits && min > 0 ? array.min(min) : array;
-    return limits && max !== undefined ? bounded.max(max, message) : bounded;
-  };
-  const ChartDate = z
-    .string()
-    .regex(/^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2})?)?$/)
-    .refine((value) => chartDateTime(value) !== undefined, "Not a valid date.");
-  const ChartPoint = z.object({
-    x: z.union([ChartNumber, ChartDate]).describe("line, scatter: number or YYYY-MM-DD[THH:mm[:ss]], wall-clock time without an offset."),
-    y: ChartNumber.describe("line, scatter: value."),
-  });
-  // As many lines as series a reader can tell apart.
-  const ChartReferences = list(
-    z.object({ value: z.union([z.number(), ChartDate]), axis: z.enum(["x", "y"]).optional(), label: ChartLabel.optional() }),
-    0,
-    CLOUD_AI_CHART_MAX_SERIES,
-    `Use at most ${CLOUD_AI_CHART_MAX_SERIES} references.`,
-  );
-  // One palette color per band.
-  const ChartThresholds = list(
-    z.object({ value: z.number(), label: ChartLabel.optional() }),
-    1,
-    CLOUD_AI_CHART_MAX_SERIES,
-    `Use at most ${CLOUD_AI_CHART_MAX_SERIES} thresholds.`,
-  );
-  return {
-    ChartLabel,
-    ChartTooltip,
-    ChartNumber,
-    list,
-    ChartReferences,
-    ChartThresholds,
-    ChartAxis: z.object({
-      label: ChartLabel.optional(),
-      domain: z.array(z.number()).length(2).optional().describe("Exact [min, max]; must contain every value and reference."),
-      ticks: (limits ? z.number().int().min(2).max(12) : z.number().int().min(2)).optional(),
-      scale: z.enum(["linear", "log"]).optional().describe("log needs values above zero."),
-      format: cloudAiFormatSchema().optional(),
-    }),
-    ChartCategory: z.object({ label: ChartLabel, value: ChartNumber }),
-    ChartSlice: z.object({ label: ChartLabel, value: limits ? z.number().min(0) : ChartNumber }),
-    ChartSeries: (points: z.ZodArray<typeof ChartPoint>) =>
-      z.object({
-        label: ChartLabel.optional(),
-        data: points,
-        role: z.literal("reference").optional(),
-      }),
-    ChartPoints: list(ChartPoint, 0, CLOUD_AI_CHART_MAX_VALUES),
-    ChartBins: z
-      .union([
-        limits ? z.number().int().min(1).max(CLOUD_AI_CHART_MAX_VALUES) : z.number().int().min(1),
-        limits
-          ? z
-              .array(z.number())
-              .min(2)
-              .max(CLOUD_AI_CHART_MAX_VALUES + 1)
-          : z.array(z.number()).min(2),
-      ])
-      .describe("histogram: a bin count or ascending bin edges."),
-    ChartCommon: {
-      title: (limits ? z.string().trim().min(1).max(160) : z.string()).describe("All kinds and groups: chart title."),
-      subtitle: (limits ? z.string().trim().min(1).max(300) : z.string())
-        .optional()
-        .describe("All kinds and groups: unit, period or source."),
-    },
-    ChartUnit: limits ? z.string().trim().min(1).max(12) : z.string(),
-    ChartBox: z.object({ label: ChartLabel, values: list(ChartNumber, 1) }),
-    ChartCell: z.object({ x: ChartLabel, y: ChartLabel, value: ChartNumber }),
-    ChartBarGauge: z.object({ label: ChartLabel, value: ChartNumber, min: z.number().optional(), max: z.number().optional() }),
-  };
-};
-
-const chartKinds = (limits = true) => {
-  const {
-    ChartNumber,
-    list,
-    ChartAxis,
-    ChartBins,
-    ChartCategory,
-    ChartCommon,
-    ChartTooltip,
-    ChartLabel,
-    ChartPoints,
-    ChartSeries,
-    ChartSlice,
-    ChartReferences,
-    ChartThresholds,
-    ChartUnit,
-    ChartBox,
-    ChartCell,
-    ChartBarGauge,
-  } = chartParts(limits);
-  const ChartKindCommon = { ...ChartCommon, tooltip: ChartTooltip.optional() };
-  const numberFormat = cloudAiNumberFormatSchema();
-  return z.discriminatedUnion("kind", [
-    z.object({
-      kind: z.literal("bar"),
-      ...ChartKindCommon,
-      data: list(ChartCategory, 1, CLOUD_AI_CHART_MAX_VALUES),
-      xAxis: ChartAxis.pick({ label: true }).strict().optional(),
-      yAxis: ChartAxis.optional(),
-      colorByBar: z.boolean().optional(),
-      showValues: z.boolean().optional(),
-      legend: z.boolean().optional(),
-      references: ChartReferences.optional(),
-    }),
-    z.object({
-      kind: z.literal("line"),
-      ...ChartKindCommon,
-      series: list(
-        ChartSeries(
-          limits
-            ? ChartPoints.min(2, "A line needs at least two points per series; show single values as a bar or scatter chart.")
-            : ChartPoints,
-        ).extend({ style: z.enum(["solid", "dashed", "dotted"]).optional() }),
-        1,
-        CLOUD_AI_CHART_MAX_SERIES,
-      ),
-      xAxis: ChartAxis.optional(),
-      yAxis: ChartAxis.optional(),
-      legend: z.boolean().optional(),
-      area: z.boolean().optional(),
-      smooth: z.boolean().optional(),
-      references: ChartReferences.optional(),
-    }),
-    z.object({
-      kind: z.literal("scatter"),
-      ...ChartKindCommon,
-      series: list(ChartSeries(limits ? ChartPoints.min(1) : ChartPoints), 1, CLOUD_AI_CHART_MAX_SERIES),
-      xAxis: ChartAxis.optional(),
-      yAxis: ChartAxis.optional(),
-      legend: z.boolean().optional(),
-      references: ChartReferences.optional(),
-    }),
-    z.object({
-      kind: z.enum(["pie", "donut"]),
-      ...ChartKindCommon,
-      data: list(ChartSlice, 1, CLOUD_AI_CHART_MAX_VALUES),
-      legend: z.boolean().optional(),
-      showLabels: z.boolean().optional(),
-      format: numberFormat.optional(),
-    }),
-    z.object({
-      kind: z.literal("histogram"),
-      ...ChartKindCommon,
-      data: list(ChartNumber, 1, CLOUD_AI_CHART_MAX_VALUES),
-      bins: ChartBins.optional(),
-      references: ChartReferences.optional(),
-    }),
-    z.object({
-      kind: z.literal("gauge"),
-      ...ChartKindCommon,
-      value: ChartNumber,
-      min: z.number().optional(),
-      max: z.number().optional(),
-      label: ChartLabel.optional(),
-      unit: ChartUnit.optional(),
-      format: numberFormat.optional(),
-      thresholds: ChartThresholds.optional(),
-    }),
-    z.object({
-      kind: z.literal("sparkline"),
-      ...ChartKindCommon,
-      data: list(ChartNumber, 2, CLOUD_AI_CHART_MAX_VALUES),
-      area: z.boolean().optional(),
-    }),
-    z.object({
-      kind: z.literal("boxplot"),
-      ...ChartKindCommon,
-      data: list(ChartBox, 1, CLOUD_AI_CHART_MAX_VALUES),
-      yAxis: ChartAxis.optional(),
-      references: ChartReferences.optional(),
-    }),
-    z.object({
-      kind: z.literal("heatmap"),
-      ...ChartKindCommon,
-      data: list(ChartCell, 1, CLOUD_AI_VIEW_MAX_MARKS),
-      format: numberFormat.optional(),
-      showValues: z.boolean().optional(),
-      min: z.number().optional(),
-      max: z.number().optional(),
-    }),
-    z.object({
-      kind: z.literal("barGauge"),
-      ...ChartKindCommon,
-      // The shared renderer draws 280 units high and a bar gauge row is 28 units, so 8 rows fit without a taller drawing.
-      data: list(ChartBarGauge, 1, CLOUD_AI_CHART_MAX_SERIES, `Use at most ${CLOUD_AI_CHART_MAX_SERIES} bar gauge items.`),
-      min: z.number().optional(),
-      max: z.number().optional(),
-      unit: ChartUnit.optional(),
-      format: numberFormat.optional(),
-      thresholds: ChartThresholds.optional(),
-    }),
-    z.object({
-      kind: z.literal("stat"),
-      ...ChartKindCommon,
-      value: ChartNumber,
-      format: numberFormat.optional(),
-      unit: ChartUnit.optional(),
-      delta: limits ? z.number().optional() : ChartNumber,
-      better: z.enum(["up", "down"]).optional(),
-      sparkline: list(ChartNumber, 2, CLOUD_AI_CHART_MAX_VALUES).optional(),
-    }),
-  ]);
-};
+const chartLimits = { maxSeries: CLOUD_AI_CHART_MAX_SERIES, maxValues: CLOUD_AI_CHART_MAX_VALUES, maxMarks: CLOUD_AI_VIEW_MAX_MARKS };
 
 /** Checks run on complete input only, so out-of-range input fails on its bounds before anything is computed or drawn. */
 const whenValid = { when: (payload: { issues: readonly unknown[] }) => payload.issues.length === 0 };
 
 export const cloudAiChartSchema = () =>
-  chartKinds().superRefine((chart, context) => {
+  chartKinds(chartLimits).superRefine((chart, context) => {
     const total = cloudAiChartMarks(chart);
     const issue =
       total > CLOUD_AI_VIEW_MAX_MARKS
@@ -291,16 +60,9 @@ export const cloudAiChartSchema = () =>
     if (issue) context.addIssue({ code: "custom", message: issue });
   }, whenValid);
 /** Apps retain the renderer's permissive data contract, except values that would stall tick generation. */
-export const cloudAiAppChartSchema = () =>
-  chartKinds(false).superRefine((chart, context) => {
-    const issue = chartSteppingIssue(chart);
-    if (issue) context.addIssue({ code: "custom", message: issue });
-  }, whenValid);
+export const cloudAiAppChartSchema = chartSchema;
 const ChartSchema = /* @__PURE__ */ cloudAiChartSchema();
 
-/** One chart as the renderers read it: a `cloud.chart()` kind with its options. */
-export type CloudAiChartInput = z.output<ReturnType<typeof chartKinds>>;
-
 /**
  * Reads one chart without drawing it; undefined when it is not a chart. Writers have drawn it once already, so
  * renderers draw only for display.
@@ -311,7 +73,7 @@ export const parseCloudAiChartInput = (value: unknown): CloudAiChartInput | unde
 };
 
 export const cloudAiGroupSchema = () => {
-  const { ChartCommon } = chartParts();
+  const { ChartCommon } = chartParts(chartLimits);
   return z
     .strictObject({
       ...ChartCommon,
@@ -354,7 +116,7 @@ const flatChartSchema = () => {
     ChartThresholds,
     ChartUnit,
     ChartTooltip,
-  } = chartParts();
+  } = chartParts(chartLimits);
   return z.object({
     kind: cloudAiChartKindSchema().optional().describe("Single charts: kind. Omit for groups."),
     ...ChartCommon,

package/src/api/admin-app-keys.ts

@@ -0,0 +1,66 @@
+import type { MiddlewareHandler } from "hono";
+import { Hono } from "hono";
+import { describeRoute } from "hono-openapi";
+import { z } from "zod";
+import { validateAppKeyAppId } from "../app-key";
+import { type AuthContext, auth, respond, v } from "../server";
+import { noTransform } from "../server/middleware/no-transform";
+import { appKeys } from "../services/app-keys";
+
+const appId = z.string().refine((value) => {
+  try {
+    validateAppKeyAppId(value);
+    return true;
+  } catch {
+    return false;
+  }
+}, "Invalid or reserved app ID");
+const params = z.object({ appId });
+const pagination = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  perPage: z.coerce.number().int().min(1).max(500).default(100),
+});
+const input = z
+  .object({ publicKey: z.string().length(43), name: z.string().trim().min(1).max(120).optional(), expiresAt: z.iso.datetime().optional() })
+  .strict();
+
+export const createAdminAppKeyRoutes = (
+  authenticate: MiddlewareHandler<AuthContext> = auth.requireRole("admin"),
+  service: typeof appKeys = appKeys,
+) =>
+  new Hono<AuthContext>()
+    .use("*", noTransform())
+    .use(authenticate)
+    .use("*", async (c, next) => {
+      c.header("Cache-Control", "no-store");
+      if (["POST", "DELETE"].includes(c.req.method)) return auth.requireOAuthScope("write", "admin")(c, next);
+      return next();
+    })
+    .get(
+      "/keys",
+      describeRoute({ tags: ["App keys"], summary: "List apps with enrolled keys and the installation ID" }),
+      v("query", pagination),
+      (c) => respond(c, () => service.listApps({ actor: c.get("user"), ...c.req.valid("query") })),
+    )
+    .get(
+      "/:appId/keys",
+      describeRoute({ tags: ["App keys"], summary: "List app public keys and lifecycle metadata" }),
+      v("param", params),
+      v("query", pagination),
+      (c) => respond(c, () => service.list({ actor: c.get("user"), ...c.req.valid("param"), ...c.req.valid("query") })),
+    )
+    .post(
+      "/:appId/keys",
+      describeRoute({ tags: ["App keys"], summary: "Idempotently enroll an Ed25519 public key; at most two active keys per app" }),
+      v("param", params),
+      v("json", input),
+      (c) => respond(c, () => service.register({ actor: c.get("user"), ...c.req.valid("param"), ...c.req.valid("json") })),
+    )
+    .delete(
+      "/:appId/keys/:keyId",
+      describeRoute({ tags: ["App keys"], summary: "Idempotently revoke an app key" }),
+      v("param", params.extend({ keyId: z.uuid() })),
+      (c) => respond(c, () => service.revoke({ actor: c.get("user"), ...c.req.valid("param") })),
+    );
+
+export default createAdminAppKeyRoutes();

package/src/api/admin-core-settings.ts

@@ -27,6 +27,7 @@ import { SETTINGS_MAP, validateSettingValue } from "../services/settings/default
 import { assertGeoBudgetPair, GeoBudgetSettingError } from "../services/settings/geo-budget";
 import { invalidateSettingsCacheForAdmin } from "../services/settings/store";
 import { assertSettingVersions } from "../services/settings/versions";
+import { adminSettingsEnvRoutes } from "./admin-settings-env";
 
 const BulkUpdatesSchema = z
   .object({
@@ -72,6 +73,7 @@ const invalidateCommittedSettings = async (keys: readonly string[]): Promise<voi
 const liveSettingKeys = async () => (await listApps()).flatMap((app) => [...(app.settingKeys ?? [])]);
 
 const app = new Hono<AuthContext>()
+  .route("/env", adminSettingsEnvRoutes)
   .get("/web-vitals", auth.requireRole("admin"), async (c) =>
     c.json({ enabled: (await settings.get("observability.web_vitals.enabled")) === true }),
   )

package/src/api/admin-identity.ts

@@ -86,7 +86,10 @@ type IdentityAdminDependencies = {
   status: typeof getIdentitySigningKeyStatus;
   rewrap: typeof rewrapIdentitySigningKeys;
   revoke: typeof revokeIdentitySigningKey;
-  serviceAccounts: Pick<typeof serviceAccounts, "getOrCreateResourceBound" | "createStandalone" | "listStandalone" | "get" | "setStatus">;
+  serviceAccounts: Pick<
+    typeof serviceAccounts,
+    "getByResource" | "getOrCreateResourceBound" | "createStandalone" | "listStandalone" | "get" | "setStatus"
+  >;
   credentials: Pick<
     typeof serviceAccountCredentials,
     "createResourceApiToken" | "createStandaloneApiToken" | "getOverview" | "listOverview" | "revoke"
@@ -151,6 +154,29 @@ export const createAdminIdentityRoutes = (
           }),
         ),
     )
+    .patch(
+      "/workloads/:appId",
+      describeRoute({ tags: ["App credentials"], summary: "Enable or disable app workload issuance and calls across all instances" }),
+      v("param", WorkloadAppParamsSchema),
+      v("json", ServiceAccountStatusInputSchema),
+      async (c) =>
+        respond(c, async () => {
+          const { appId } = c.req.valid("param");
+          const { status } = c.req.valid("json");
+          const account = await service.serviceAccounts.getByResource({ appId, resourceType: "cloud.app", resourceId: appId });
+          if (!account) return fail(err.notFound("Workload service account"));
+          const updated = await service.serviceAccounts.setStatus({ id: account.id, status });
+          if (!updated.ok) return updated;
+          await service.audit.record({
+            action: status === "disabled" ? "service_account.disable" : "service_account.enable",
+            outcome: "allowed",
+            actor: auditActor(c.get("user")),
+            target: { type: "service_account", id: account.id, label: account.name },
+            metadata: { appId, serviceAccountId: account.id, status },
+          });
+          return ok({ appId, status });
+        }),
+    )
     .post(
       "/workloads/:appId/credentials",
       describeRoute({ tags: ["App credentials"], summary: "Create an app-bound credential; return its token once" }),

package/src/api/admin-settings-env.ts

@@ -0,0 +1,120 @@
+import { Hono } from "hono";
+import { describeRoute } from "hono-openapi";
+import { z } from "zod";
+import { readBoundedJson } from "../_internal/bounded-json";
+import { getApp, listApps } from "../_internal/registry";
+import { EnvSettingStatusSchema, type EnvSettingsProcessSchema, EnvSettingsStatusSchema } from "../contracts/settings-env";
+import { type AuthContext, auth, jsonResponse, requiresAdmin, setRequestTimeout, v } from "../server";
+import { listGatewayRouteSnapshots } from "../services/gateway";
+import { invocationAuthorityFromRequest } from "../services/identity/invocation-authority";
+import { issueInvocationToken } from "../services/identity/issue-invocation";
+import { withActiveIdentitySigner } from "../services/identity/key-ring";
+import { readEnvSettingsStatus } from "../services/settings/env-status";
+import { settingsInvocationOperation } from "./settings-ops";
+
+const reply = z.object({ settings: z.array(EnvSettingStatusSchema) });
+export const adminSettingsEnvRoutes = new Hono<AuthContext>()
+  .use("*", auth.requireRole("admin"))
+  .use("*", auth.requireOAuthScope("admin"))
+  .get(
+    "/status",
+    describeRoute({
+      tags: ["Administration"],
+      summary: "Check environment-backed settings without returning values",
+      ...requiresAdmin,
+      responses: { 200: jsonResponse(EnvSettingsStatusSchema, "Migration status") },
+    }),
+    async (c) => {
+      setRequestTimeout(c, 240);
+      const signal = AbortSignal.any([c.req.raw.signal, AbortSignal.timeout(230_000)]);
+      try {
+        const processes: z.infer<typeof EnvSettingsProcessSchema>[] = [
+          { appId: "core", status: "ok", settings: await readEnvSettingsStatus() },
+        ];
+        for (const app of await listApps()) {
+          if (app.id === "core") continue;
+          try {
+            const response = await requestSettings(app, "GET", "env", auth.getAuthority(c), undefined, signal);
+            const data = await readBoundedJson(response, 4 * 1024 * 1024);
+            if (!response.ok || !data.ok) throw new Error("Unavailable");
+            processes.push({ appId: app.id, status: "ok", settings: reply.parse(data.data).settings });
+          } catch {
+            processes.push({ appId: app.id, status: "unavailable", settings: [] });
+          }
+        }
+        const gateways = await listGatewayRouteSnapshots();
+        if (!gateways.length) processes.push({ appId: "gateway", status: "unavailable", settings: [] });
+        for (const gateway of gateways) {
+          const parsed = z.array(EnvSettingStatusSchema).safeParse(gateway.envSettings);
+          processes.push({
+            appId: "gateway",
+            instanceId: gateway.instanceId,
+            sampledAt: gateway.updatedAt,
+            status: parsed.success ? "ok" : "unavailable",
+            settings: parsed.success ? parsed.data : [],
+          });
+        }
+        return c.json(
+          { needsAttention: processes.some((p) => p.status !== "ok" || p.settings.some((s) => s.needsAttention)), processes },
+          200,
+          { "cache-control": "no-store" },
+        );
+      } finally {
+        setRequestTimeout(c, 10);
+      }
+    },
+  )
+  .put("/:appId/:key", v("json", z.object({ value: z.unknown(), replaceUnreadable: z.boolean().optional() })), async (c) => {
+    const app = await getApp(c.req.param("appId") ?? "");
+    if (!app) return c.json({ message: "App is not registered; start it before changing its settings" }, 404);
+    try {
+      const response = await requestSettings(
+        app,
+        "PUT",
+        c.req.param("key") ?? "",
+        auth.getAuthority(c),
+        c.req.valid("json"),
+        c.req.raw.signal,
+      );
+      const body = await readBoundedJson(response, 4 * 1024 * 1024);
+      if (!body.ok) throw new Error("Unavailable");
+      return Response.json(body.data, { status: response.status, headers: { "cache-control": "no-store" } });
+    } catch {
+      return c.json({ message: "Application settings unavailable" }, 502);
+    }
+  });
+
+const requestSettings = async (
+  app: { id: string; baseUrl: string },
+  method: "GET" | "PUT",
+  key: string,
+  authority: Parameters<typeof invocationAuthorityFromRequest>[0],
+  body: unknown,
+  parentSignal: AbortSignal,
+) => {
+  const signal = AbortSignal.any([parentSignal, AbortSignal.timeout(5_000)]);
+  const signed = await withActiveIdentitySigner(
+    "invocation",
+    (signer, db) =>
+      issueInvocationToken(
+        {
+          targetAppId: app.id,
+          callingAppId: "core",
+          operation: settingsInvocationOperation(method, key),
+          schemaHash: null,
+          authority: invocationAuthorityFromRequest(authority),
+          signer,
+          issuer: signer.issuer,
+        },
+        { db, groupsAdmin: signer.groupsAdmin, signal },
+      ),
+    { signal, timeoutMs: 5_000 },
+  );
+  return fetch(new URL(`/_internal/settings/${encodeURIComponent(key)}`, app.baseUrl), {
+    method,
+    headers: { authorization: `Bearer ${signed.token}`, "content-type": "application/json" },
+    body: body === undefined ? undefined : JSON.stringify(body),
+    signal,
+    redirect: "manual",
+  });
+};

package/src/api/capabilities.ts

@@ -260,11 +260,17 @@ const errorResponse = (code: string, message: string, status: number, details?:
   status,
 });
 
-const capabilityJsonResponse = (body: unknown, status: number): Response =>
-  Response.json(body, {
+const capabilityJsonResponse = (body: unknown, status: number): Response => {
+  const limited =
+    status === 429 ? z.object({ details: z.object({ retryAfter: z.number().int().positive().safe() }) }).safeParse(body) : null;
+  return Response.json(body, {
     status,
-    headers: { "content-type": "application/json" },
+    headers: {
+      "content-type": "application/json",
+      ...(limited?.success ? { "retry-after": String(limited.data.details.retryAfter) } : {}),
+    },
   });
+};
 
 export type CapabilityDispatchParams = {
   /** Trusted Core continuation binding; never read from client headers. */

package/src/api/index.ts

@@ -26,6 +26,7 @@ import adminAiProjectsRoutes from "./admin-ai-projects";
 import adminAiQuotaRoutes from "./admin-ai-quotas";
 import adminAiSkillsRoutes from "./admin-ai-skills";
 import adminAiUsageRoutes from "./admin-ai-usage";
+import adminAppKeyRoutes from "./admin-app-keys";
 import adminCoreSettingsRoutes from "./admin-core-settings";
 import adminDirectorySharesRoutes from "./admin-directory-shares";
 import adminGeoRoutes from "./admin-geo";
@@ -106,6 +107,7 @@ const buildCoreApi = (options: CoreApiOptions) => {
     .route("/admin/core/geo", adminGeoRoutes)
     .route("/admin/identity/directory-shares", adminDirectorySharesRoutes)
     .route("/admin/identity", adminIdentityRoutes)
+    .route("/admin/apps", adminAppKeyRoutes)
     .route("/admin/sync", createSyncOpsProxyRoutes())
     .route("/admin/lifecycle", adminLifecycleRoutes)
     .route("/ai/approval-preferences", approvalPreferenceRoutes)
@@ -133,6 +135,7 @@ export const createCoreApiRouter = (options: CoreApiOptions) => {
   return { api };
 };
 
+export { createAdminAppKeyRoutes } from "./admin-app-keys";
 export { createAppAccessRoutes } from "./app-access";
 export {
   CLOUD_MCP_PATH,

package/src/api/settings-ops.ts

@@ -0,0 +1,35 @@
+import { Hono } from "hono";
+import { z } from "zod";
+// Concrete modules, not the server barrel: defineApp imports this file, and the barrel imports defineApp.
+import { type AuthContext, auth } from "../server/middleware/auth";
+import { v } from "../server/middleware/validator";
+import { settingsService } from "../services/settings/app";
+import { SETTINGS_MAP } from "../services/settings/defaults";
+import { readEnvSettingsStatus } from "../services/settings/env-status";
+
+export const settingsInvocationOperation = (method: string, key: string) => {
+  try {
+    return `settings.${method === "GET" ? "env" : "set"}:${decodeURIComponent(key)}`;
+  } catch {
+    return "settings.invalid";
+  }
+};
+
+export const createSettingsOpsRoutes = (keys: readonly string[]) =>
+  new Hono<AuthContext>()
+    .use("*", async (c, next) => {
+      if (!c.get("user")?.roles.includes("admin")) return c.json({ message: "Insufficient permissions" }, 403);
+      return next();
+    })
+    .use("*", auth.requireOAuthScope("admin"))
+    .get("/env", async (c) => c.json({ settings: await readEnvSettingsStatus() }, 200, { "cache-control": "no-store" }))
+    .put("/:key", v("json", z.object({ value: z.unknown(), replaceUnreadable: z.boolean().optional() })), async (c) => {
+      const key = c.req.param("key") ?? "";
+      const def = SETTINGS_MAP.get(key);
+      if (!keys.includes(key) || !def || !(def.envBootstrap || def.envFallback))
+        return c.json({ message: "Unknown application setting" }, 400);
+      const body = c.req.valid("json");
+      const result = await settingsService.entry.update({ key, value: body.value, replaceUnreadable: body.replaceUnreadable });
+      if (!result.ok) return c.json({ message: result.error.message }, 400);
+      return c.json({ saved: true });
+    });