@k2b/cloud 0.46.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/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

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

package/src/capabilities/server-invoke.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { refreshAppWorkloadCredential } from "../_internal/workload-credential";
 import { dispatchCapability, loadCapabilityCatalogPage } from "../api/capabilities";
 import {
   CAPABILITY_FRAMEWORK_ERROR_CODES,
@@ -124,34 +125,51 @@ const invokeCapabilityWithResultSchema = async <TDataSchema extends z.ZodType, T
       });
       return readCapabilityResponse(outcome, capabilityResultSchema(dataSchema, { consumer: true }));
     }
-    const response = await (
-      caller.transport ?? ((request: Request) => fetch(request, caller.workload ? { redirect: "error" } : undefined))
-    )(
-      new Request(request, {
-        body: JSON.stringify(
-          caller.mandate || caller.workload
-            ? {
-                kind: invocation.kind,
-                targetApp: invocation.appId,
-                capabilityId: invocation.capabilityId,
-                input: invocation.input,
-                ...(caller.mandate ? { mandateId: caller.mandate.id, mandateRevision: caller.mandate.revision } : {}),
-                ...(invocation.idempotencyKey ? { idempotencyKey: invocation.idempotencyKey } : {}),
-                ...(caller.requestId || caller.traceparent || caller.tracestate || caller.locale
-                  ? {
-                      metadata: {
-                        ...(caller.requestId ? { requestId: caller.requestId } : {}),
-                        ...(caller.traceparent ? { traceparent: caller.traceparent } : {}),
-                        ...(caller.tracestate ? { tracestate: caller.tracestate } : {}),
-                        ...(caller.locale ? { locale: caller.locale } : {}),
-                      },
-                    }
-                  : {}),
-              }
-            : { input: invocation.input },
-        ),
-      }),
-    );
+    const brokerRequest = new Request(request, {
+      body: JSON.stringify(
+        caller.mandate || caller.workload
+          ? {
+              kind: invocation.kind,
+              targetApp: invocation.appId,
+              capabilityId: invocation.capabilityId,
+              input: invocation.input,
+              ...(caller.mandate ? { mandateId: caller.mandate.id, mandateRevision: caller.mandate.revision } : {}),
+              ...(invocation.idempotencyKey ? { idempotencyKey: invocation.idempotencyKey } : {}),
+              ...(caller.requestId || caller.traceparent || caller.tracestate || caller.locale
+                ? {
+                    metadata: {
+                      ...(caller.requestId ? { requestId: caller.requestId } : {}),
+                      ...(caller.traceparent ? { traceparent: caller.traceparent } : {}),
+                      ...(caller.tracestate ? { tracestate: caller.tracestate } : {}),
+                      ...(caller.locale ? { locale: caller.locale } : {}),
+                    },
+                  }
+                : {}),
+            }
+          : { input: invocation.input },
+      ),
+    });
+    const send = caller.transport ?? ((request: Request) => fetch(request, caller.workload ? { redirect: "error" } : undefined));
+    // Only Core's pre-dispatch workload rejection is safe to retry, including a non-idempotent action.
+    const workloadAppId = caller.mandate?.callingAppId ?? caller.workload?.appId;
+    const retryRequest = workloadAppId ? brokerRequest.clone() : undefined;
+    let response = await send(brokerRequest);
+    const credentialRejected = (reply: Response) => reply.status === 401 && reply.headers.get("x-cloud-workload-auth") === "required";
+    if (workloadAppId && retryRequest && credentialRejected(response)) {
+      await response.body?.cancel();
+      let token: string | undefined;
+      try {
+        token = await refreshAppWorkloadCredential(workloadAppId);
+      } catch {
+        // This rejection happened before dispatch; credential state is retryable unavailability.
+      }
+      if (token) retryRequest.headers.set("authorization", `Bearer ${token}`);
+      response = await send(retryRequest);
+      if (credentialRejected(response)) {
+        await response.body?.cancel();
+        return unavailable(undefined, undefined, caller.locale ?? undefined);
+      }
+    }
     return readCapabilityResponse(response, capabilityResultSchema(dataSchema, { consumer: true }));
   } catch (cause) {
     return unavailable(cause, invocation, caller.locale ?? undefined);

package/src/capabilities/server.ts

@@ -182,7 +182,7 @@ export {
   readCalendarEvents,
 } from "./calendar-sources";
 export { type DiscussionProvider, discussionProviders } from "./discussion-providers";
-export { type ResourceReadersResult, readResourcePrincipals } from "./resource-readers";
+export { ResourceReaderRateLimited, type ResourceReadersResult, readResourcePrincipals } from "./resource-readers";
 export {
   actionReview,
   type CapabilityReviewForms,

package/src/capabilities/types.ts

@@ -2,7 +2,7 @@ import type { z } from "zod";
 import type { CapabilityActionReviewData, CapabilityCatalog, CapabilityErrorSchema, CapabilityResult } from "../contracts/capabilities";
 
 export type CapabilityKind = "query" | "action";
-export type CapabilityClientError = z.infer<typeof CapabilityErrorSchema> & { status: number };
+export type CapabilityClientError = z.infer<typeof CapabilityErrorSchema> & { status: number; retryAfterMs?: number };
 export type CapabilityResultState<T> = { ok: true; data: T } | { ok: false; error: CapabilityClientError };
 export type CapabilityClientResult<T> = CapabilityResultState<CapabilityResult<T>>;
 export type CapabilityReviewClientResult = CapabilityResultState<CapabilityActionReviewData>;

package/src/cli/admin/app-credentials.ts

@@ -10,6 +10,7 @@ const metadata = z.object({
   status: z.string(),
   tokenPrefix: z.string(),
   expiresAt: z.string().nullable(),
+  serviceAccount: z.object({ status: z.string() }).optional(),
 });
 
 export const appCredentialCommands = [
@@ -33,12 +34,15 @@ export const appCredentialCommands = [
         .object({ items: z.array(metadata), page: z.number(), perPage: z.number(), total: z.number(), hasNext: z.boolean() })
         .parse(await apiGet(ctx, `${path(args.app)}?page=${flags.page}&perPage=${flags.perPage}`));
       if (!printStructured(ctx, listing))
-        ctx.table(listing.items, [
-          { key: "id", label: "ID" },
-          { key: "name", label: "Name" },
-          { key: "status", label: "Status" },
-          { key: "expiresAt", label: "Expires" },
-        ]);
+        ctx.table(
+          listing.items.map((item) => ({ ...item, status: item.serviceAccount?.status === "disabled" ? "disabled" : item.status })),
+          [
+            { key: "id", label: "ID" },
+            { key: "name", label: "Name" },
+            { key: "status", label: "Status" },
+            { key: "expiresAt", label: "Expires" },
+          ],
+        );
     },
   }),
   command("app-credentials create", {
@@ -62,8 +66,29 @@ export const appCredentialCommands = [
       if (!printStructured(ctx, result)) ctx.print(result.token);
     },
   }),
+  ...(["enable", "disable"] as const).map((action) =>
+    command(`app-credentials ${action}`, {
+      summary: `${action === "enable" ? "Enable" : "Disable"} workload issuance and calls for every instance of an app`,
+      args: { app: arg.required({ valueLabel: "app" }) },
+      flags: { yes: confirmFlag(`${action} this app's workload access`) },
+      async run({ ctx, args, flags }) {
+        if (!flags.yes)
+          throw new Error(
+            cliText(ctx, {
+              en: "Changing app workload access requires --yes.",
+              de: "App-Hintergrundzugriff ändern erfordert --yes.",
+            }),
+          );
+        const result = await apiJson(ctx, "PATCH", `${root}/${encodeURIComponent(args.app)}`, {
+          status: action === "enable" ? "active" : "disabled",
+        });
+        if (!printStructured(ctx, result))
+          ctx.print(cliText(ctx, { en: "App workload access updated.", de: "App-Hintergrundzugriff aktualisiert." }));
+      },
+    }),
+  ),
   command("app-credentials revoke", {
-    summary: "Revoke one exact app credential; its background calls will stop",
+    summary: "Revoke an app credential; runtime credentials also disable app-wide workload access",
     args: { app: arg.required({ valueLabel: "app" }), credential: arg.required({ valueLabel: "credential" }) },
     flags: { yes: confirmFlag("Revoke this app credential") },
     async run({ ctx, args, flags }) {