@k2b/cloud 0.45.0 → 0.47.0

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/browser/notifications.ts

@@ -13,6 +13,8 @@ export type BrowserNotificationState = {
   permission: NotificationPermission;
   enabled: boolean;
   reason?: string;
+  /** On iPhone and iPad outside the Home Screen app: notifications start working once Cloud is added to the Home Screen. */
+  homeScreenRequired?: true;
 };
 
 const isIos = (): boolean =>
@@ -21,7 +23,15 @@ const isIos = (): boolean =>
 const isStandalone = (): boolean =>
   window.matchMedia("(display-mode: standalone)").matches || (navigator as Navigator & { standalone?: boolean }).standalone === true;
 
-const support = (): { supported: boolean; reason?: string } => {
+const support = (): { supported: boolean; reason?: string; homeScreenRequired?: true } => {
+  // Safari on iPhone and iPad offers push only to the Home Screen app, so it lacks the APIs checked below.
+  if (typeof window !== "undefined" && isIos() && !isStandalone()) {
+    return {
+      supported: false,
+      reason: "On iPhone and iPad, add Cloud to your Home Screen before enabling browser notifications.",
+      homeScreenRequired: true,
+    };
+  }
   if (
     typeof window === "undefined" ||
     !window.isSecureContext ||
@@ -31,12 +41,6 @@ const support = (): { supported: boolean; reason?: string } => {
   ) {
     return { supported: false, reason: "Browser notifications are not supported in this browser." };
   }
-  if (isIos() && !isStandalone()) {
-    return {
-      supported: false,
-      reason: "On iPhone and iPad, add Cloud to your Home Screen before enabling browser notifications.",
-    };
-  }
   return { supported: true };
 };
 
@@ -101,7 +105,13 @@ const pushSubscriptionError = (cause: unknown): Error => {
 const currentState = async (registration?: ServiceWorkerRegistration): Promise<BrowserNotificationState> => {
   const capability = support();
   if (!capability.supported) {
-    return { supported: false, permission: "denied", enabled: false, reason: capability.reason };
+    return {
+      supported: false,
+      permission: "denied",
+      enabled: false,
+      reason: capability.reason,
+      ...(capability.homeScreenRequired ? { homeScreenRequired: true } : {}),
+    };
   }
   return withNotificationTimeout(
     (async () => {
@@ -131,6 +141,13 @@ export const browserNotificationClient = {
     return (await response.json()).state;
   },
 
+  /** End do not disturb now, for every app. Quiet hours keep their schedule. Returns the quiet state afterwards. */
+  endDoNotDisturb: async (): Promise<NotificationQuietState> => {
+    const response = await apiClient.me.notifications.quiet.$patch({ json: { doNotDisturbUntil: null } });
+    if (!response.ok) throw await responseError(response, "Failed to end do not disturb.");
+    return (await response.json()).state;
+  },
+
   /** Close this application's group on this device without opting into notifications. */
   closeGroup: async (appId: string, group: string): Promise<void> => {
     const tag = notificationGroupTag(appId, group);

package/src/capabilities/discussion-providers.ts

@@ -0,0 +1,100 @@
+import { discussionsIssues } from "../contracts/discussions";
+import { type CapabilityCaller, listCapabilityCatalog } from "./server-invoke";
+import type { CapabilityCatalogApp } from "./types";
+
+// Same interactive discovery budget as the calendar reader. Cursor pages are sequential (one in flight).
+const MAX_CALLS = 60;
+const MAX_BYTES = 4 * 1024 * 1024;
+export type DiscussionProvider = {
+  app: CapabilityCatalogApp;
+  itemType: string;
+  containerType: string;
+  containers: string;
+  activity?: string;
+};
+
+/** 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; 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();
+  const signal = AbortSignal.any([
+    controller.signal,
+    ...[caller.signal, options.signal].filter((signal): signal is AbortSignal => !!signal),
+  ]);
+  const timer = setTimeout(() => controller.abort(new Error("DISCUSSION_DEADLINE")), Math.max(0, options.deadline - Date.now()));
+  let bytes = 0;
+  const addBytes = (size: number) => {
+    bytes += size;
+    if (bytes > MAX_BYTES) {
+      controller.abort(new Error("DISCUSSION_BYTE_BUDGET"));
+      signal.throwIfAborted();
+    }
+  };
+  const credentials: CapabilityCaller = {
+    ...caller,
+    signal,
+    ...(!caller.authority
+      ? {
+          transport: async (request: Request) => {
+            const response = await (caller.transport ?? ((request: Request) => fetch(request, { redirect: "error" })))(request);
+            if (!response.body) return response;
+            const body = response.body.pipeThrough(
+              new TransformStream<Uint8Array, Uint8Array>({
+                transform(chunk, stream) {
+                  addBytes(chunk.byteLength);
+                  stream.enqueue(chunk);
+                },
+              }),
+              { signal },
+            );
+            return new Response(body, { status: response.status, headers: response.headers });
+          },
+        }
+      : {}),
+  };
+  const providers: DiscussionProvider[] = [];
+  const seen = new Set<string>();
+  const appIds = new Set<string>();
+  let cursor: string | undefined;
+  let onAbort: (() => void) | undefined;
+  const cancelled = new Promise<never>((_, reject) => {
+    onAbort = () => reject(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+  try {
+    for (let calls = 0; calls < MAX_CALLS; calls++) {
+      if (options.deadline <= Date.now()) controller.abort(new Error("DISCUSSION_DEADLINE"));
+      signal.throwIfAborted();
+      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);
+      for (const app of page.data.apps) {
+        const role = app.manifest.discussions;
+        const model = app.manifest.resourceTypes?.find((model) => model.type === role?.item);
+        if (!role || !model?.container || discussionsIssues(app.manifest).length || appIds.has(app.appId)) continue;
+        appIds.add(app.appId);
+        providers.push({
+          app,
+          itemType: `${app.appId}.${role.item}`,
+          containerType: `${app.appId}.${model.container}`,
+          containers: role.containers,
+          ...(role.activity ? { activity: role.activity } : {}),
+        });
+      }
+      if (!page.data.page.hasMore) return providers;
+      cursor = page.data.page.nextCursor;
+      if (seen.has(cursor)) throw new Error("DISCUSSION_CURSOR_LOOP");
+      seen.add(cursor);
+    }
+    throw new Error("DISCUSSION_CALL_BUDGET");
+  } finally {
+    clearTimeout(timer);
+    if (onAbort) signal.removeEventListener("abort", onAbort);
+    controller.abort();
+  }
+};

package/src/capabilities/executions.ts

@@ -63,7 +63,7 @@ export type CapabilityExecutionInput = {
   capability: string;
   kind: "query" | "action";
   destructive: boolean;
-  actorKind?: "user" | "service_account" | null;
+  actorKind?: "user" | "service_account" | "app" | null;
   actorId?: string | null;
   userId?: string | null;
   /** Recorded only when the access subject differs from the acting principal. */
@@ -90,7 +90,7 @@ export type CapabilityExecution = {
   capability: string;
   kind: "query" | "action";
   destructive: boolean;
-  actorKind: "user" | "service_account" | null;
+  actorKind: "user" | "service_account" | "app" | null;
   actorId: string | null;
   userId: string | null;
   accessSubjectType: "user" | "service_account" | null;

package/src/capabilities/migrate.ts

@@ -35,7 +35,7 @@ export const migrateCloudCapabilities = async (): Promise<void> => {
       duration_ms INTEGER NOT NULL DEFAULT 0,
       CONSTRAINT capabilities_executions_origin_check CHECK (origin IN ('assistant', 'mcp', 'http', 'app')),
       CONSTRAINT capabilities_executions_kind_check CHECK (kind IN ('query', 'action')),
-      CONSTRAINT capabilities_executions_actor_kind_check CHECK (actor_kind IS NULL OR actor_kind IN ('user', 'service_account')),
+      CONSTRAINT capabilities_executions_actor_kind_check CHECK (actor_kind IS NULL OR actor_kind IN ('user', 'service_account', 'app')),
       CONSTRAINT capabilities_executions_subject_check CHECK (access_subject_type IS NULL OR access_subject_type IN ('user', 'service_account')),
       CONSTRAINT capabilities_executions_status_check CHECK (status IN ('succeeded', 'failed', 'denied', 'invalid_input', 'timed_out', 'rejected'))
     )
@@ -59,6 +59,15 @@ export const migrateCloudCapabilities = async (): Promise<void> => {
   await sql`ALTER TABLE capabilities.executions ADD COLUMN IF NOT EXISTS parent_invocation_id UUID`.simple();
   await sql`ALTER TABLE capabilities.executions ADD COLUMN IF NOT EXISTS via_app_id TEXT`.simple();
 
+  await sql`DO $$ BEGIN
+    IF EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = 'capabilities.executions'::regclass
+      AND conname = 'capabilities_executions_actor_kind_check' AND position('''app''' in pg_get_constraintdef(oid)) = 0) THEN
+      ALTER TABLE capabilities.executions DROP CONSTRAINT capabilities_executions_actor_kind_check;
+      ALTER TABLE capabilities.executions ADD CONSTRAINT capabilities_executions_actor_kind_check
+        CHECK (actor_kind IS NULL OR actor_kind IN ('user', 'service_account', 'app'));
+    END IF;
+  END $$`.simple();
+
   // Platform-owned idempotency claims. One row per
   // (app, capability, principal, key); the dispatcher claims before it
   // forwards and resolves the row once the outcome is known. Response bodies

package/src/capabilities/resource-readers.ts

@@ -0,0 +1,69 @@
+import { getProcessApplicationId } from "../_internal/process-identity";
+import { getCapability } from "../_internal/registry";
+import { getAppWorkloadCredential } from "../_internal/workload-credential";
+import { env } from "../config/env";
+import {
+  CloudResourceRefSchema,
+  type ResourcePrincipal,
+  ResourceReadableDataSchema,
+  ResourceReadableInputSchema,
+} from "../contracts/capabilities";
+import { invokeCapabilityWithDataSchema } from "./server-invoke";
+
+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 };
+  container?: { type: string; id: string };
+  principals: readonly ResourcePrincipal[];
+  signal?: AbortSignal;
+  locale?: string;
+  requestId?: string;
+}): Promise<ResourceReadersResult> => {
+  const ref = CloudResourceRefSchema.parse(options.ref);
+  // 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" };
+  options.signal?.throwIfAborted();
+  const separator = ref.type.indexOf(".");
+  const appId = ref.type.slice(0, separator);
+  const localType = ref.type.slice(separator + 1);
+  const entry = await getCapability(appId);
+  if (!entry) throw new Error("Resource reader provider registry entry unavailable");
+  const model = entry.manifest.resourceTypes?.find((model) => model.type === localType);
+  if (!model?.readable || !entry.manifest.queries.some((query) => query.localId === `${localType}.readable` && query.appOnly))
+    return { state: "not_configured", reason: "no_readable" };
+  const input = ResourceReadableInputSchema.parse({ id: ref.id, container: options.container, principals: options.principals });
+  if (model.container && input.container?.type !== `${appId}.${model.container}`)
+    throw new Error("Reader check requires a reference to the declared container type");
+  const result = await invokeCapabilityWithDataSchema(
+    { appId, capabilityId: `${localType}.readable`, kind: "query", input },
+    ResourceReadableDataSchema,
+    {
+      workload: { appId: callerAppId },
+      authorization: `Bearer ${credential}`,
+      signal: options.signal,
+      locale: options.locale,
+      requestId: options.requestId,
+    },
+  );
+  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

@@ -23,10 +23,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 },
     };
   }