@k2b/cloud 0.46.0 → 0.48.0

package/src/api/app-bootstrap.ts

@@ -0,0 +1,131 @@
+import type { SQL } from "bun";
+import { Hono, type MiddlewareHandler } from "hono";
+import { getConnInfo } from "hono/bun";
+import {
+  BOOTSTRAP_BODY,
+  BOOTSTRAP_PATH,
+  BOOTSTRAP_RESPONSE_BYTES,
+  BootstrapConnectionsSchema,
+  BootstrapResponseSchema,
+} from "../runtime/bootstrap-protocol";
+import { connections } from "../runtime/connections";
+import { clientIpBucket } from "../server/client-ip";
+import { type RateLimitResult, ratelimit } from "../server/ratelimit";
+import { authenticateBootstrap, BootstrapProofError, bootstrapRateLimit, consumeBootstrapProof } from "../services/app-bootstrap";
+import { touchAppKey } from "../services/app-keys";
+
+type BootstrapContext = { Variables: { bootstrapBody: Uint8Array<ArrayBuffer> } };
+
+/** Count actual bytes even when Content-Length is missing or forged. Never await cancellation. */
+const limitBody: MiddlewareHandler<BootstrapContext> = async (c, next) => {
+  const max = Buffer.byteLength(BOOTSTRAP_BODY);
+  const reject = () => c.json({ code: "body_too_large" }, 413);
+  if (Number(c.req.header("Content-Length")) > max) {
+    void c.req.raw.body?.cancel().catch(() => undefined);
+    return reject();
+  }
+  const reader = c.req.raw.body?.getReader();
+  const bytes = new Uint8Array(max);
+  let total = 0;
+  if (reader) {
+    try {
+      while (true) {
+        const chunk = await reader.read();
+        if (chunk.done) break;
+        if (total + chunk.value.byteLength > max) {
+          void reader.cancel().catch(() => undefined);
+          return reject();
+        }
+        bytes.set(chunk.value, total);
+        total += chunk.value.byteLength;
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  c.set("bootstrapBody", bytes.slice(0, total));
+  await next();
+};
+
+type Dependencies = {
+  db?: SQL;
+  ingress?: MiddlewareHandler;
+  admit?: (keyId: string) => Promise<RateLimitResult>;
+};
+const admit = async (kind: "ingress" | "key", identifier: string) => {
+  // Use the installation's existing per-second security budget, in separate ingress and authenticated-key buckets.
+  const limit = await bootstrapRateLimit();
+  return ratelimit({ id: `app-bootstrap-${kind}`, limit }).check(identifier);
+};
+
+const ingress: MiddlewareHandler<BootstrapContext> = async (c, next) => {
+  // Bootstrap uses the direct Core socket. Unknown peers share one bounded bucket.
+  let peer = "unknown";
+  try {
+    peer = getConnInfo(c).remote.address ?? peer;
+  } catch {
+    /* In-process requests have no socket. */
+  }
+  const rate = await admit("ingress", clientIpBucket(peer));
+  if (rate.limited) {
+    c.header("Retry-After", String(Math.max(1, Math.ceil(rate.resetIn / 1000))));
+    return c.json({ code: "bootstrap_ingress_limited" }, 429);
+  }
+  await next();
+};
+
+/** Core-only mount. Capture the startup snapshot once, including NATS file contents. */
+export const createAppBootstrapRoutes = (dependencies: Dependencies = {}) => {
+  const { database, valkey, nats, appSecret } = connections();
+  const snapshot = BootstrapConnectionsSchema.parse({ database, valkey, nats, appSecret });
+  // Refuse an undeliverable Core configuration at startup, using the largest valid identity.
+  const largestIdentity = {
+    installationId: "11111111-1111-4111-8111-111111111111",
+    appId: "a".repeat(80),
+    keyId: "22222222-2222-4222-8222-222222222222",
+  };
+  if (Buffer.byteLength(JSON.stringify({ identity: largestIdentity, connections: snapshot })) > BOOTSTRAP_RESPONSE_BYTES)
+    throw new Error("Bootstrap response exceeds protocol budget");
+  // The startup snapshot includes appId/sources; only the delivery contract goes on the wire.
+  return new Hono<BootstrapContext>()
+    .onError(() =>
+      Response.json({ code: "bootstrap_unavailable" }, { status: 503, headers: { "Cache-Control": "no-store", "Retry-After": "1" } }),
+    )
+    .post(
+      BOOTSTRAP_PATH,
+      async (c, next) => {
+        c.header("Cache-Control", "no-store");
+        await next();
+      },
+      // The v1 request is exactly two UTF-8 bytes. This runs before proof parsing, even for invalid proofs.
+      limitBody,
+      dependencies.ingress ?? ingress,
+      async (c) => {
+        const url = new URL(c.req.url);
+        if (url.search) return c.json({ code: "invalid_request" }, 400);
+        const body = c.get("bootstrapBody");
+        const header = c.req.header("Authorization") ?? "";
+        if (!header.startsWith("Bearer ")) return c.json({ code: "invalid_proof" }, 401);
+        let verified: Awaited<ReturnType<typeof authenticateBootstrap>>;
+        try {
+          verified = await authenticateBootstrap(header.slice(7), { method: c.req.method, path: url.pathname, body }, dependencies.db);
+        } catch (error) {
+          if (error instanceof BootstrapProofError) return c.json({ code: error.code }, error.code === "invalid_proof" ? 401 : 403);
+          throw error;
+        }
+        if (new TextDecoder().decode(body) !== BOOTSTRAP_BODY) return c.json({ code: "invalid_request" }, 400);
+        const { identity, jti, exp } = verified;
+        const rate = dependencies.admit ? await dependencies.admit(identity.keyId) : await admit("key", identity.keyId);
+        if (rate.limited) {
+          c.header("Retry-After", String(Math.max(1, Math.ceil(rate.resetIn / 1000))));
+          return c.json({ code: "bootstrap_rate_limited" }, 429);
+        }
+        if (!(await consumeBootstrapProof(identity.keyId, jti, exp, dependencies.db))) return c.json({ code: "replayed_proof" }, 403);
+        await touchAppKey(identity, dependencies.db);
+        const response = JSON.stringify(BootstrapResponseSchema.parse({ identity, connections: snapshot }));
+        if (Buffer.byteLength(response) > BOOTSTRAP_RESPONSE_BYTES) throw new Error("Bootstrap response exceeds protocol budget");
+        c.header("Content-Type", "application/json");
+        return c.body(response);
+      },
+    );
+};

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. */
@@ -291,6 +297,8 @@ export type CapabilityDispatchParams = {
   callingAppId?: string;
   /** Internal observation only: called immediately before attempting the app request. */
   onUpstreamAttempt?: () => void;
+  /** Core-only aggregate budget, charged on upstream bytes before parsing or validation. */
+  consumeResponseBytes?: (bytes: number) => void;
   dependencies?: CapabilityDispatchDependencies;
 };
 
@@ -783,7 +791,12 @@ const runCapabilityDispatch = async (
   let upstreamBody: Awaited<ReturnType<typeof readBoundedJson>>;
   try {
     upstreamBody = await deadline.wait(() =>
-      readBoundedJson(response, params.review ? CAPABILITY_MAX_REVIEW_RESPONSE_BYTES : CAPABILITY_MAX_RESULT_BYTES, signal),
+      readBoundedJson(
+        response,
+        params.review ? CAPABILITY_MAX_REVIEW_RESPONSE_BYTES : CAPABILITY_MAX_RESULT_BYTES,
+        signal,
+        params.consumeResponseBytes,
+      ),
     );
   } catch {
     if (actionWithoutRetrySafety) return settle(outcomeUnknown(), "uncertain");

package/src/api/index.ts

@@ -26,6 +26,8 @@ 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 adminAppDomainRoutes from "./admin-app-domains";
+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 +108,8 @@ const buildCoreApi = (options: CoreApiOptions) => {
     .route("/admin/core/geo", adminGeoRoutes)
     .route("/admin/identity/directory-shares", adminDirectorySharesRoutes)
     .route("/admin/identity", adminIdentityRoutes)
+    .route("/admin/apps", adminAppDomainRoutes)
+    .route("/admin/apps", adminAppKeyRoutes)
     .route("/admin/sync", createSyncOpsProxyRoutes())
     .route("/admin/lifecycle", adminLifecycleRoutes)
     .route("/ai/approval-preferences", approvalPreferenceRoutes)
@@ -133,7 +137,11 @@ export const createCoreApiRouter = (options: CoreApiOptions) => {
   return { api };
 };
 
+export { createAdminAppDomainRoutes } from "./admin-app-domains";
+export { createAdminAppKeyRoutes } from "./admin-app-keys";
 export { createAppAccessRoutes } from "./app-access";
+/** Core-owned internal startup protocol; applications use @k2b/cloud/start. */
+export { createAppBootstrapRoutes } from "./app-bootstrap";
 export {
   CLOUD_MCP_PATH,
   CLOUD_MCP_PROTECTED_RESOURCE_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 });
+    });

package/src/app-key.ts

@@ -0,0 +1,125 @@
+/** Portable Ed25519 app-key format. No server, environment, or barrel dependencies. */
+const PREFIX = "cloud-app-key-v1";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const APP_ID = /^[a-z][a-z0-9-]{0,79}$/;
+const PKCS8_PREFIX = new Uint8Array([48, 46, 2, 1, 0, 48, 5, 6, 3, 43, 101, 112, 4, 34, 4, 32]);
+
+export type AppKey = { installationId: string; appId: string; keyId: string; seed: string };
+
+export const validateAppKeyAppId = (appId: string): string => {
+  if (!APP_ID.test(appId) || appId.trim() !== appId) throw new Error("App ID must match ^[a-z][a-z0-9-]{0,79}$");
+  if (appId === "core" || appId === "gateway") throw new Error("Core and Gateway cannot have app keys");
+  return appId;
+};
+
+const encode = (bytes: Uint8Array): string =>
+  btoa(String.fromCharCode(...bytes))
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replace(/=+$/, "");
+
+const decode32 = (value: string, label: string): Uint8Array<ArrayBuffer> => {
+  if (!/^[A-Za-z0-9_-]{43}$/.test(value)) throw new Error(`${label} must be 32 bytes in unpadded base64url`);
+  const bytes = Uint8Array.from(atob(`${value.replaceAll("-", "+").replaceAll("_", "/")}=`), (c) => c.charCodeAt(0));
+  if (bytes.length !== 32 || encode(bytes) !== value) throw new Error(`${label} must use canonical base64url`);
+  return bytes;
+};
+
+export const parseAppKey = (value: string): AppKey => {
+  const parts = value.split(".");
+  if (parts.length !== 5 || parts[0] !== PREFIX) throw new Error("Expected cloud-app-key-v1.<installationId>.<appId>.<keyId>.<seed>");
+  const [, installationId, appId, keyId, seed] = parts;
+  if (!installationId || installationId.length !== 36 || !UUID.test(installationId))
+    throw new Error("Invalid app-key installation ID (expected canonical UUID)");
+  if (!keyId || keyId.length !== 36 || !UUID.test(keyId)) throw new Error("Invalid app-key key ID (expected canonical UUID)");
+  validateAppKeyAppId(appId ?? "");
+  decode32(seed ?? "", "App-key seed");
+  return { installationId, appId: appId!, keyId, seed: seed! };
+};
+
+export const formatAppKey = (key: AppKey): string => {
+  const value = `${PREFIX}.${key.installationId}.${key.appId}.${key.keyId}.${key.seed}`;
+  parseAppKey(value);
+  return value;
+};
+
+export const importAppKeySeed = async (seed: string): Promise<CryptoKey> => {
+  const der = new Uint8Array(48);
+  der.set(PKCS8_PREFIX);
+  der.set(decode32(seed, "App-key seed"), 16);
+  return crypto.subtle.importKey("pkcs8", der, "Ed25519", true, ["sign"]);
+};
+
+export const deriveAppPublicKey = async (seed: string): Promise<string> => {
+  const jwk = await crypto.subtle.exportKey("jwk", await importAppKeySeed(seed));
+  if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || !jwk.x) throw new Error("Ed25519 public key export failed");
+  decode32(jwk.x, "App public key");
+  return jwk.x;
+};
+
+// WebCrypto raw import accepts arbitrary 32-byte strings in Bun. Check the
+// canonical compressed Edwards point as well, including small-order points.
+const P = (1n << 255n) - 19n;
+const mod = (x: bigint): bigint => ((x % P) + P) % P;
+const pow = (x: bigint, exponent: bigint): bigint => {
+  let result = 1n;
+  for (let n = exponent; n > 0n; n >>= 1n) {
+    if (n & 1n) result = mod(result * x);
+    x = mod(x * x);
+  }
+  return result;
+};
+const D = mod(-121665n * pow(121666n, P - 2n));
+const validPoint = (bytes: Uint8Array): boolean => {
+  let compressed = 0n;
+  for (let i = 31; i >= 0; i--) compressed = (compressed << 8n) | BigInt(bytes[i]!);
+  const sign = compressed >> 255n;
+  const y = compressed & ((1n << 255n) - 1n);
+  if (y >= P) return false;
+  const y2 = mod(y * y);
+  const x2 = mod((y2 - 1n) * pow(mod(D * y2 + 1n), P - 2n));
+  let x = pow(x2, (P + 3n) / 8n);
+  if (mod(x * x) !== x2) x = mod(x * pow(2n, (P - 1n) / 4n));
+  if (mod(x * x) !== x2 || (x === 0n && sign !== 0n)) return false;
+  if ((x & 1n) !== sign) x = P - x;
+  // Three projective doublings: [8]P must not be the identity.
+  let X = x;
+  let Y = y;
+  let Z = 1n;
+  for (let i = 0; i < 3; i++) {
+    const a = mod(X * X),
+      b = mod(Y * Y),
+      c = mod(2n * Z * Z),
+      d = mod(-a);
+    const e = mod((X + Y) ** 2n - a - b),
+      g = mod(d + b),
+      f = mod(g - c),
+      h = mod(d - b);
+    X = mod(e * f);
+    Y = mod(g * h);
+    Z = mod(f * g);
+  }
+  return X !== 0n || mod(Y - Z) !== 0n;
+};
+
+export const importAppPublicKey = async (publicKey: string): Promise<CryptoKey> => {
+  const bytes = decode32(publicKey, "App public key");
+  if (!validPoint(bytes)) throw new Error("App public key must be a canonical Ed25519 point of non-small order");
+  return crypto.subtle.importKey("raw", bytes, "Ed25519", true, ["verify"]);
+};
+
+/** First 16 bytes of SHA-256(raw public key), displayed as 32 lowercase hex characters. */
+export const appKeyFingerprint = async (publicKey: string): Promise<string> => {
+  await importAppPublicKey(publicKey);
+  const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", decode32(publicKey, "App public key")));
+  return Array.from(hash.subarray(0, 16), (byte) => byte.toString(16).padStart(2, "0")).join("");
+};
+
+export const generateAppKeyPair = async (): Promise<{ seed: string; publicKey: string }> => {
+  const pair = await crypto.subtle.generateKey("Ed25519", true, ["sign", "verify"]);
+  const jwk = await crypto.subtle.exportKey("jwk", pair.privateKey);
+  if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || !jwk.d || !jwk.x) throw new Error("Ed25519 key generation failed");
+  decode32(jwk.d, "App-key seed");
+  await importAppPublicKey(jwk.x);
+  return { seed: jwk.d, publicKey: jwk.x };
+};

package/src/browser/CloudResourceSearch.tsx

@@ -247,6 +247,7 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
     // Instant rows come first: streamed app sections are appended below them and never push them down.
     return [...commands, ...results()];
   });
+  const itemsByKey = createMemo(() => new Map(items().map((item) => [itemKey(item), item])));
   const selectable = (item: SearchItem) =>
     !props.disabled &&
     !choosingTag() &&
@@ -627,48 +628,54 @@ export default function CloudResourceSearch(props: CloudResourceSearchProps) {
               </Show>
               <Show when={showList()}>
                 <section id={`${id}-options`} role="listbox" aria-label={t().searchCloudResources} class="cloud-resource-search__results">
-                  <For each={items()}>
-                    {(item, index) => (
-                      <>
-                        <Show when={index() === 0 || items()[index() - 1]?.appId !== item.appId}>
-                          <div class="cloud-resource-search__group" role="presentation">
-                            {item.appName}
-                          </div>
-                        </Show>
-                        <button
-                          type="button"
-                          id={`${id}-result-${index()}`}
-                          data-result-index={index()}
-                          role="option"
-                          aria-selected={props.selectionMode ? selectedKey() === itemKey(item) : activeIndex() === index()}
-                          aria-disabled={!selectable(item)}
-                          class="cloud-resource-search__result"
-                          classList={{
-                            "is-active": activeIndex() === index(),
-                            "is-selected": props.selectionMode && selectedKey() === itemKey(item),
-                          }}
-                          onFocus={() => selectIndex(index())}
-                          onMouseEnter={() => {
-                            if (!props.selectionMode) selectIndex(index());
-                          }}
-                          onClick={(event) => {
-                            if ((event.metaKey || event.ctrlKey) && props.onOpenInNewTab && !props.selectionMode) {
-                              if (selectable(item)) openNewTab(item);
-                            } else chooseItem(item);
-                          }}
-                        >
-                          <i class={item.icon ?? item.appIcon} aria-hidden="true" />
-                          <span class="cloud-resource-search__result-copy">
-                            <span>{item.title}</span>
-                            <small>{isApp(item) ? t().app : (item.preview ?? item.appName)}</small>
-                          </span>
-                          <Show when={commandFor(item)?.shortcut}>{(shortcut) => <Kbd keys={shortcut()} />}</Show>
-                          <Show when={props.selectionMode && selectedKey() === itemKey(item)}>
-                            <i class="ti ti-check" aria-hidden="true" />
+                  {/* Keyed by result, not object: commands become new objects whenever results stream in, and a row
+                      replaced between press and release would swallow the click. */}
+                  <For each={items().map(itemKey)}>
+                    {(key, index) => {
+                      const first = itemsByKey().get(key)!;
+                      const item = () => itemsByKey().get(key) ?? first;
+                      return (
+                        <>
+                          <Show when={index() === 0 || items()[index() - 1]?.appId !== item().appId}>
+                            <div class="cloud-resource-search__group" role="presentation">
+                              {item().appName}
+                            </div>
                           </Show>
-                        </button>
-                      </>
-                    )}
+                          <button
+                            type="button"
+                            id={`${id}-result-${index()}`}
+                            data-result-index={index()}
+                            role="option"
+                            aria-selected={props.selectionMode ? selectedKey() === itemKey(item()) : activeIndex() === index()}
+                            aria-disabled={!selectable(item())}
+                            class="cloud-resource-search__result"
+                            classList={{
+                              "is-active": activeIndex() === index(),
+                              "is-selected": props.selectionMode && selectedKey() === itemKey(item()),
+                            }}
+                            onFocus={() => selectIndex(index())}
+                            onMouseEnter={() => {
+                              if (!props.selectionMode) selectIndex(index());
+                            }}
+                            onClick={(event) => {
+                              if ((event.metaKey || event.ctrlKey) && props.onOpenInNewTab && !props.selectionMode) {
+                                if (selectable(item())) openNewTab(item());
+                              } else chooseItem(item());
+                            }}
+                          >
+                            <i class={item().icon ?? item().appIcon} aria-hidden="true" />
+                            <span class="cloud-resource-search__result-copy">
+                              <span>{item().title}</span>
+                              <small>{isApp(item()) ? t().app : (item().preview ?? item().appName)}</small>
+                            </span>
+                            <Show when={commandFor(item())?.shortcut}>{(shortcut) => <Kbd keys={shortcut()} />}</Show>
+                            <Show when={props.selectionMode && selectedKey() === itemKey(item())}>
+                              <i class="ti ti-check" aria-hidden="true" />
+                            </Show>
+                          </button>
+                        </>
+                      );
+                    }}
                   </For>
                 </section>
               </Show>

package/src/capabilities/discussion-providers.ts

@@ -16,7 +16,7 @@ export type DiscussionProvider = {
 /** Request-local discovery. Failure, truncation, and cancellation throw; no partial success or retained authority. */
 export const discussionProviders = async (
   caller: CapabilityCaller,
-  options: { deadline: number; signal?: AbortSignal },
+  options: { deadline: number; signal?: AbortSignal; page?: <T>(read: () => Promise<T>) => Promise<T> },
 ): Promise<DiscussionProvider[]> => {
   if (!Number.isFinite(options.deadline)) throw new RangeError("Discussion deadline must be a finite epoch time in milliseconds");
   const controller = new AbortController();
@@ -68,7 +68,8 @@ export const discussionProviders = async (
     for (let calls = 0; calls < MAX_CALLS; calls++) {
       if (options.deadline <= Date.now()) controller.abort(new Error("DISCUSSION_DEADLINE"));
       signal.throwIfAborted();
-      const page = await Promise.race([listCapabilityCatalog({ caller: credentials, cursor, limit: 25 }), cancelled]);
+      const read = () => listCapabilityCatalog({ caller: credentials, cursor, limit: 25 });
+      const page = await Promise.race([options.page ? options.page(read) : read(), cancelled]);
       signal.throwIfAborted();
       if (!page.ok) throw new Error(`Discussion discovery unavailable: ${page.error.code}`);
       if (caller.authority) addBytes(new TextEncoder().encode(JSON.stringify(page.data)).byteLength);

package/src/capabilities/resource-readers.ts

@@ -1,5 +1,6 @@
 import { getProcessApplicationId } from "../_internal/process-identity";
 import { getCapability } from "../_internal/registry";
+import { getAppWorkloadCredential } from "../_internal/workload-credential";
 import { env } from "../config/env";
 import {
   CloudResourceRefSchema,
@@ -13,6 +14,13 @@ export type ResourceReadersResult =
   | { state: "checked"; readable: ResourcePrincipal[] }
   | { state: "not_configured"; reason: "no_readable" | "no_credential" | "no_internal_origin" | "no_app_identity" | "not_admitted" };
 
+/** Admission is temporary; consumers may schedule a bounded fresh check after this delay. */
+export class ResourceReaderRateLimited extends Error {
+  constructor(readonly retryAfterMs: number) {
+    super("Resource reader rate limited");
+  }
+}
+
 /** An empty checked subset means not readable; an unavailable check throws for the caller's retry. */
 export const readResourcePrincipals = async (options: {
   ref: { type: string; id: string };
@@ -23,7 +31,9 @@ export const readResourcePrincipals = async (options: {
   requestId?: string;
 }): Promise<ResourceReadersResult> => {
   const ref = CloudResourceRefSchema.parse(options.ref);
-  if (!env.CLOUD_APP_CREDENTIAL) return { state: "not_configured", reason: "no_credential" };
+  // Core issues the credential automatically; an explicit CLOUD_APP_CREDENTIAL override wins.
+  const credential = getAppWorkloadCredential();
+  if (!credential) return { state: "not_configured", reason: "no_credential" };
   if (!env.CLOUD_CORE_INTERNAL_ORIGIN) return { state: "not_configured", reason: "no_internal_origin" };
   const callerAppId = getProcessApplicationId();
   if (!callerAppId) return { state: "not_configured", reason: "no_app_identity" };
@@ -44,7 +54,7 @@ export const readResourcePrincipals = async (options: {
     ResourceReadableDataSchema,
     {
       workload: { appId: callerAppId },
-      authorization: `Bearer ${env.CLOUD_APP_CREDENTIAL}`,
+      authorization: `Bearer ${credential}`,
       signal: options.signal,
       locale: options.locale,
       requestId: options.requestId,
@@ -52,6 +62,7 @@ export const readResourcePrincipals = async (options: {
   );
   if (!result.ok) {
     if (result.error.code === "APP_QUERY_NOT_ADMITTED") return { state: "not_configured", reason: "not_admitted" };
+    if (result.error.code === "RATE_LIMITED") throw new ResourceReaderRateLimited(result.error.retryAfterMs ?? 60_000);
     throw new Error(`Resource reader check unavailable: ${result.error.code}`);
   }
   return { state: "checked", readable: result.data.data.readable };

package/src/capabilities/response.ts

@@ -8,8 +8,9 @@ export const readCapabilityResponse = async <T>(
   schema: z.ZodType<T>,
   maxBytes = CAPABILITY_MAX_RESULT_BYTES,
   signal?: AbortSignal,
+  consumeBytes?: (bytes: number) => void,
 ): Promise<CapabilityResultState<T>> => {
-  const parsedBody = await readBoundedJson(response, maxBytes, signal);
+  const parsedBody = await readBoundedJson(response, maxBytes, signal, consumeBytes);
   if (!parsedBody.ok && parsedBody.reason === "too_large") {
     return {
       ok: false,
@@ -23,10 +24,13 @@ export const readCapabilityResponse = async <T>(
   const body = parsedBody.ok ? parsedBody.data : null;
   if (!response.ok) {
     const error = CapabilityErrorSchema.safeParse(body);
+    const retryAfter = response.headers.get("Retry-After");
+    const retryAfterMs =
+      retryAfter === null ? NaN : /^\d+$/.test(retryAfter.trim()) ? Number(retryAfter) * 1000 : Date.parse(retryAfter) - Date.now();
     return {
       ok: false,
       error: error.success
-        ? { ...error.data, status: response.status }
+        ? { ...error.data, status: response.status, ...(Number.isSafeInteger(retryAfterMs) && retryAfterMs > 0 ? { retryAfterMs } : {}) }
         : { code: "INVALID_APP_RESPONSE", message: "Cloud returned an invalid capability error", status: response.status },
     };
   }