@k2b/cloud 0.47.0 → 0.49.0

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

@@ -3,7 +3,7 @@ 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 { type AuthContext, auth, jsonResponse, respond, v } from "../server";
 import { noTransform } from "../server/middleware/no-transform";
 import { appKeys } from "../services/app-keys";
 
@@ -21,9 +21,49 @@ const pagination = z.object({
   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() })
+  .object({
+    publicKey: z.string().length(43),
+    name: z.string().trim().min(1).max(120).optional(),
+    expiresAt: z.iso.datetime().optional(),
+    grants: z.array(z.literal("oauth:issue")).max(1).optional(),
+  })
   .strict();
 
+const keyListResponse = z.object({
+  installationId: z.uuid(),
+  items: z.array(
+    z.object({
+      keyId: z.uuid(),
+      appId: z.string(),
+      serviceAccountId: z.uuid(),
+      kind: z.literal("app_key"),
+      name: z.string(),
+      publicKey: z.string(),
+      grants: z.array(z.literal("oauth:issue")),
+      fingerprint: z.string(),
+      status: z.enum(["active", "expired", "revoked"]),
+      accountStatus: z.enum(["active", "disabled"]),
+      createdAt: z.iso.datetime(),
+      createdBy: z.uuid().nullable(),
+      expiresAt: z.iso.datetime().nullable(),
+      revokedAt: z.iso.datetime().nullable(),
+      revokedBy: z.uuid().nullable(),
+      lastUsedAt: z.iso.datetime().nullable(),
+    }),
+  ),
+  lastRejectedStart: z
+    .object({
+      at: z.iso.datetime(),
+      reason: z.enum(["revoked", "expired", "disabled", "connections_not_permitted"]),
+      keyId: z.uuid().nullable(),
+    })
+    .nullable(),
+  page: z.number().int(),
+  perPage: z.number().int(),
+  total: z.number().int(),
+  hasNext: z.boolean(),
+});
+
 export const createAdminAppKeyRoutes = (
   authenticate: MiddlewareHandler<AuthContext> = auth.requireRole("admin"),
   service: typeof appKeys = appKeys,
@@ -44,7 +84,11 @@ export const createAdminAppKeyRoutes = (
     )
     .get(
       "/:appId/keys",
-      describeRoute({ tags: ["App keys"], summary: "List app public keys and lifecycle metadata" }),
+      describeRoute({
+        tags: ["App keys"],
+        summary: "List app public keys, lifecycle metadata and last rejected start",
+        responses: { 200: jsonResponse(keyListResponse, "App keys and last rejected start") },
+      }),
       v("param", params),
       v("query", pagination),
       (c) => respond(c, () => service.list({ actor: c.get("user"), ...c.req.valid("param"), ...c.req.valid("query") })),

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

@@ -6,13 +6,13 @@
  * core app mounts it under `/api/admin/core/settings`.
  */
 
-import { sql } from "bun";
 import { Hono } from "hono";
 import { describeRoute } from "hono-openapi";
 import { z } from "zod";
 import { ObjectStoreConfigurationError, ObjectStoreConnectionError, testObjectStoreConnection } from "../_internal/object-store-config";
 import { listApps } from "../_internal/registry";
 import { enrichDirtyAiConversations } from "../ai/enrich";
+import { sql } from "../runtime/clients";
 import { type AuthContext, auth, getLocale, jsonResponse, requiresAdmin, v } from "../server";
 import { settingsDeleteLegacyKeys, settingsListLegacyKeys, settingsService } from "../services";
 import { readAccountCategoryPolicy } from "../services/account-category-policy";

package/src/api/admin-outgoing-mail.ts

@@ -1,4 +1,3 @@
-import { sql } from "bun";
 import { type Context, Hono, type MiddlewareHandler } from "hono";
 import { describeRoute, validator } from "hono-openapi";
 import { z } from "zod";
@@ -13,6 +12,7 @@ import {
   MailRetentionSchema,
   MailStatusSchema,
 } from "../contracts/outgoing-mail";
+import { sql } from "../runtime/clients";
 import { type AuthContext, auth, jsonResponse, requiresAdmin } from "../server";
 import { noTransform } from "../server/middleware/no-transform";
 import { audit } from "../services/audit";

package/src/api/app-bootstrap.ts

@@ -0,0 +1,153 @@
+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,
+  clearRejectedBootstrapStart,
+  consumeBootstrapProof,
+  RejectedBootstrapStart,
+  recordRejectedBootstrapStart,
+} from "../services/app-bootstrap";
+import { touchAppKey } from "../services/app-keys";
+import { logger } from "../services/logging";
+
+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 RejectedBootstrapStart) {
+            try {
+              const rate = dependencies.admit ? await dependencies.admit(error.identity.keyId) : await admit("key", error.identity.keyId);
+              if (!rate.limited) await recordRejectedBootstrapStart(error, dependencies.db);
+            } catch {
+              logger("app-bootstrap").warn("Could not record rejected app start", { appId: error.identity.appId });
+            }
+          }
+          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");
+        try {
+          await clearRejectedBootstrapStart(identity.appId, dependencies.db);
+        } catch {
+          logger("app-bootstrap").warn("Could not clear rejected app start", { appId: identity.appId });
+        }
+        c.header("Content-Type", "application/json");
+        return c.body(response);
+      },
+    );
+};

package/src/api/app-events.ts

@@ -1,10 +1,10 @@
-import { sql } from "bun";
 import { Hono, type MiddlewareHandler } from "hono";
 import { describeRoute } from "hono-openapi";
 import { z } from "zod";
 import { AppDetailsSchema } from "../contracts/app-details";
 import { AppEventEnvelopeSchema } from "../contracts/app-events";
 import { CapabilityQualifiedIdSchema } from "../contracts/capabilities";
+import { sql } from "../runtime/clients";
 import { type AuthContext, auth, expectUserBackedActor, getLocale, v } from "../server";
 import { AppAccessManagementError } from "../services/app-access-management";
 import { appDetails } from "../services/app-details";

package/src/api/auth.ts

@@ -1,10 +1,10 @@
-import { sql } from "bun";
 import { type Context, Hono } from "hono";
 import { describeRoute } from "hono-openapi";
 import { z } from "zod";
 import { env } from "../config";
 import { ChangeExpiredPasswordSchema } from "../contracts";
 import { coreUserEventPublisher } from "../events/core-user-created";
+import { sql } from "../runtime/clients";
 import { type AuthContext, auth, getLocale, jsonResponse, rateLimit, respond, v } from "../server";
 import { accounts, audit, authFlows, getFreeIpaConfig, logger, webauthn } from "../services";
 import { isAccountCategoryAllowed } from "../services/account-category-policy";

package/src/api/authenticate-app-request.ts

@@ -0,0 +1,129 @@
+import type { SQL } from "bun";
+import type { Context } from "hono";
+import { getConnInfo } from "hono/bun";
+import { CAPABILITY_MAX_REQUEST_BYTES } from "../contracts/capabilities";
+import { clientIpBucket } from "../server/client-ip";
+import { type RateLimitResult, ratelimit } from "../server/ratelimit";
+import { REQUEST_IDLE_TIMEOUT_SECONDS } from "../server/request-timeout";
+import {
+  authenticateAppProof,
+  BootstrapProofError,
+  bootstrapRateLimit,
+  consumeBootstrapProof,
+  inspectAppProof,
+} from "../services/app-bootstrap";
+import { touchAppKey } from "../services/app-keys";
+import type { AuthenticatedWorkload } from "../services/identity/workload-auth";
+
+type Dependencies = {
+  db?: SQL;
+  ingress?: (peer: string) => Promise<RateLimitResult>;
+  admit?: (keyId: string) => Promise<RateLimitResult>;
+};
+const admission = async (kind: "ingress" | "key", id: string) =>
+  ratelimit({ id: `app-bootstrap-${kind}`, limit: await bootstrapRateLimit() }).check(id);
+
+/** Core-only request authentication; the body remains available to the domain handler. */
+export const authenticateSignedAppRequest = async (
+  c: Context,
+  scope: "identity:invoke" | "oauth:issue",
+  dependencies: Dependencies = {},
+): Promise<AuthenticatedWorkload | Response> => {
+  c.header("Cache-Control", "no-store");
+  const deadline = AbortSignal.timeout(REQUEST_IDLE_TIMEOUT_SECONDS * 1000);
+  const signal = AbortSignal.any([c.req.raw.signal, deadline]);
+  const reject = (status: 401 | 403 | 413 | 429 | 503 | 504, code: string, message: string) => c.json({ code, message }, status);
+  const limited = (rate: RateLimitResult) => {
+    c.header("Retry-After", String(Math.max(1, Math.ceil(rate.resetIn / 1000))));
+    return reject(429, "RATE_LIMITED", "App request admission limit reached");
+  };
+  try {
+    let peer = "unknown";
+    try {
+      peer = getConnInfo(c).remote.address ?? peer;
+    } catch {
+      /* In-process requests have no socket. */
+    }
+    const ingress = await (dependencies.ingress ?? ((id) => admission("ingress", id)))(clientIpBucket(peer));
+    if (ingress.limited) return limited(ingress);
+    const header = c.req.header("Authorization") ?? "";
+    if (!header.startsWith("Bearer ")) return reject(401, "invalid_proof", "A valid app proof is required");
+    inspectAppProof(header.slice(7));
+    const tooLarge = () => reject(413, "body_too_large", "App request exceeds the byte limit");
+    if (Number(c.req.header("Content-Length")) > CAPABILITY_MAX_REQUEST_BYTES) {
+      void c.req.raw.body?.cancel().catch(() => undefined);
+      return tooLarge();
+    }
+    signal.throwIfAborted();
+    const copy = c.req.raw.clone();
+    const reader = copy.body?.getReader();
+    const bytes = new Uint8Array(CAPABILITY_MAX_REQUEST_BYTES);
+    let total = 0;
+    if (reader) {
+      const cancel = () => {
+        // A tee cancels its source only after both branches cancel. Never await a stalled source.
+        void reader.cancel(signal.reason).catch(() => undefined);
+        void c.req.raw.body?.cancel(signal.reason).catch(() => undefined);
+      };
+      signal.addEventListener("abort", cancel, { once: true });
+      try {
+        signal.throwIfAborted();
+        while (true) {
+          const chunk = await reader.read();
+          if (chunk.done) break;
+          if (total + chunk.value.byteLength > bytes.byteLength) {
+            cancel();
+            return tooLarge();
+          }
+          bytes.set(chunk.value, total);
+          total += chunk.value.byteLength;
+        }
+        signal.throwIfAborted();
+      } catch (error) {
+        cancel();
+        if (signal.aborted) throw signal.reason;
+        throw error;
+      } finally {
+        signal.removeEventListener("abort", cancel);
+        reader.releaseLock();
+      }
+    }
+    const url = new URL(c.req.url);
+    const verified = await authenticateAppProof(
+      header.slice(7),
+      { method: c.req.method, path: url.pathname + url.search, body: bytes.slice(0, total) },
+      dependencies.db,
+    );
+    // Recheck the operator-owned key grant on every transmission.
+    if (scope === "oauth:issue" && !verified.key.oauthIssueAllowed)
+      return reject(403, "scope_not_permitted", "App is not permitted to issue OAuth credentials");
+    const declaredApp = c.req.header("X-Cloud-App-Id");
+    if (declaredApp && declaredApp !== verified.identity.appId) return reject(403, "wrong_app", "App identity does not match the proof");
+    const rate = await (dependencies.admit ?? ((id) => admission("key", id)))(verified.identity.keyId);
+    if (rate.limited) return limited(rate);
+    if (!(await consumeBootstrapProof(verified.identity.keyId, verified.jti, verified.exp, dependencies.db)))
+      return reject(403, "replayed_proof", "App proof has already been used");
+    await touchAppKey(verified.identity, dependencies.db);
+    return {
+      appId: verified.identity.appId,
+      keyId: verified.identity.keyId,
+      serviceAccountId: verified.key.serviceAccountId,
+      credentialId: verified.identity.keyId,
+      scope: "identity:invoke",
+    };
+  } catch (error) {
+    if (signal.aborted && error === signal.reason) {
+      void c.req.raw.body?.cancel(signal.reason).catch(() => undefined);
+      return c.req.raw.signal.aborted
+        ? Response.json(
+            { code: "REQUEST_CANCELLED", message: "App request was cancelled" },
+            { status: 499, headers: { "Cache-Control": "no-store" } },
+          )
+        : reject(504, "DEADLINE_EXCEEDED", "App request body deadline exceeded");
+    }
+    if (error instanceof BootstrapProofError)
+      return reject(error.code === "invalid_proof" ? 401 : 403, error.code, "App proof was rejected");
+    c.header("Retry-After", "1");
+    return reject(503, "app_proof_unavailable", "App request authentication is temporarily unavailable");
+  }
+};

package/src/api/capabilities.ts

@@ -61,11 +61,12 @@ import { noTransform } from "../server/middleware/no-transform";
 import { hasOAuthScope } from "../server/oauth-scope";
 import { ratelimit } from "../server/ratelimit";
 import { appAccessAuthority, canUseApp } from "../services/app-access";
+import { bootstrapRateLimit } from "../services/app-bootstrap";
 import { discoverableApps } from "../services/app-discovery";
 import { authorityFromParentInvocation, invocationAuthorityFromRequest } from "../services/identity/invocation-authority";
 import { capabilityInvocationOperation } from "../services/identity/invocation-operations";
 import type { CloudInvocationClaims, InvocationAuthority } from "../services/identity/invocation-token";
-import { normalizeInvocationRequestId, signAppQueryInvocation } from "../services/identity/invocation-token";
+import { normalizeInvocationRequestId, signAppCapabilityInvocation, signAppQueryInvocation } from "../services/identity/invocation-token";
 import { issueInvocationToken as signInvocationToken } from "../services/identity/issue-invocation";
 import { withActiveIdentitySigner } from "../services/identity/key-ring";
 import {
@@ -128,6 +129,7 @@ export type CapabilityRouteDependencies = {
   withMandateIssueAuthority?: typeof withMandateIssueAuthority;
   queryTimeoutMs?: number;
   actionTimeoutMs?: number;
+  checkAppCapabilityRate?: (appId: string) => Promise<{ limited: boolean; resetIn: number }>;
   checkAppQueryRate?: (appId: string) => Promise<{ limited: boolean }>;
   reviewTimeoutMs?: number;
   appUrl?: () => Promise<string>;
@@ -135,6 +137,7 @@ export type CapabilityRouteDependencies = {
 
 export type CapabilityDispatchDependencies = Pick<
   CapabilityRouteDependencies,
+  | "checkAppCapabilityRate"
   | "checkAppQueryRate"
   | "getApp"
   | "getCapability"
@@ -293,10 +296,14 @@ export type CapabilityDispatchParams = {
   deadline?: number;
   /** Core-only authenticated workload. Never populated from request JSON. */
   workload?: AuthenticatedWorkload;
+  /** Verified Ed25519 app identity, separate from person and legacy workload authority. */
+  appCaller?: { appId: string; keyId: string };
   mandate?: MandatedCapabilityAuthority;
   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;
 };
 
@@ -361,6 +368,39 @@ const runCapabilityDispatch = async (
   }
   if ("appOnly" in operation && operation.appOnly !== undefined && !params.workload)
     return errorResponse("FORBIDDEN", "App authority required for this query", 403);
+  if (params.appCaller) {
+    if (
+      params.authority ||
+      params.workload ||
+      params.mandate ||
+      params.parentInvocation ||
+      params.review ||
+      !operation.appPermission ||
+      operation.stream
+    )
+      return errorResponse("FORBIDDEN", "This capability does not accept app authority", 403);
+    try {
+      const app = params.appCaller;
+      const caller = await deadline.wait(() => (params.dependencies?.getApp ?? getApp)(app.appId));
+      if (!caller) return errorResponse("APP_UNAVAILABLE", "Calling app registry entry unavailable", 503);
+      if (!caller.platformPermissions?.includes(operation.appPermission))
+        return errorResponse("APP_CAPABILITY_NOT_ADMITTED", `App caller does not declare ${operation.appPermission}`, 403);
+      // Same operator-owned per-second budget as signed app ingress; shared by all keys of the app.
+      const rate = await deadline.wait(() =>
+        (
+          params.dependencies?.checkAppCapabilityRate ??
+          (async (appId) => ratelimit({ id: "app-capabilities", limit: await bootstrapRateLimit() }).check(appId))
+        )(app.appId),
+      );
+      if (rate.limited)
+        return errorResponse("RATE_LIMITED", "App capability rate limit reached", 429, {
+          retryAfter: Math.max(1, Math.ceil(rate.resetIn / 1000)),
+        });
+    } catch {
+      deadline.check();
+      return errorResponse("APP_UNAVAILABLE", "App capability admission unavailable", 503);
+    }
+  }
   if (params.workload) {
     if (
       params.authority ||
@@ -542,6 +582,36 @@ const runCapabilityDispatch = async (
           });
         })()
       : await (async () => {
+          if (params.appCaller && operation.appPermission) {
+            const app = params.appCaller;
+            const permission = operation.appPermission;
+            return deadline.wait(() =>
+              (params.dependencies?.withActiveSigner ?? withActiveIdentitySigner)(
+                "invocation",
+                async (signer) => {
+                  deadline.check();
+                  const signed = await signAppCapabilityInvocation({
+                    app,
+                    permission,
+                    kind: params.kind === "queries" ? "query" : "action",
+                    targetAppId: params.appId,
+                    capabilityId: params.capabilityId,
+                    schemaHash: operation.schemaHash,
+                    input: input.data,
+                    requestId,
+                    signer,
+                  });
+                  observed.invocationId = signed.claims.jti;
+                  return new Headers({
+                    "content-type": "application/json",
+                    accept: "application/json",
+                    authorization: `Bearer ${signed.token}`,
+                  });
+                },
+                { signal, timeoutMs: deadline.remainingMs() },
+              ),
+            );
+          }
           if (params.workload) {
             const workload = params.workload;
             return deadline.wait(() =>
@@ -673,7 +743,11 @@ const runCapabilityDispatch = async (
       ? {
           appId: params.appId,
           capability: `${params.appId}.${params.capabilityId}`,
-          principal: claimPrincipal ? `${claimPrincipal.type}:${claimPrincipal.id}` : "anonymous",
+          principal: params.appCaller
+            ? `app:${params.appCaller.appId}`
+            : claimPrincipal
+              ? `${claimPrincipal.type}:${claimPrincipal.id}`
+              : "anonymous",
           keyHash: capabilityIdempotencyKeyHash(idempotencyKey.data),
         }
       : null;
@@ -747,7 +821,7 @@ const runCapabilityDispatch = async (
     params.onUpstreamAttempt?.();
     const fetchResponse = () =>
       fetchUpstream(
-        `${entry.endpoint}/${params.workload ? "app-queries" : params.kind}/${encodeURIComponent(params.capabilityId)}${params.review ? "/review" : ""}`,
+        `${entry.endpoint}/${params.appCaller ? `app-capabilities/${params.kind}` : params.workload ? "app-queries" : params.kind}/${encodeURIComponent(params.capabilityId)}${params.review ? "/review" : ""}`,
         {
           method: "POST",
           headers,
@@ -789,7 +863,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");
@@ -979,13 +1058,15 @@ export const dispatchCapability = async (params: CapabilityDispatchParams): Prom
         origin: params.origin,
         invocationId: observed.invocationId,
         parentInvocationId: params.parentInvocation?.jti,
-        viaAppId: params.workload?.appId ?? (params.parentInvocation ? params.callingAppId : undefined),
+        viaAppId: params.appCaller?.appId ?? params.workload?.appId ?? (params.parentInvocation ? params.callingAppId : undefined),
         appId: params.appId,
         capability: `${params.appId}.${params.capabilityId}`,
         kind: params.kind === "queries" ? "query" : "action",
         destructive: observed.destructive,
-        actorKind: params.workload ? "app" : (principal?.type ?? null),
+        actorKind: params.appCaller || params.workload ? "app" : (principal?.type ?? null),
         actorId: principal?.id ?? null,
+        actorAppId: params.appCaller?.appId ?? params.workload?.appId,
+        actorKeyId: params.appCaller?.keyId,
         userId: actor?.kind === "user" ? actor.user.id : (actor?.delegatedUser?.id ?? (principal?.type === "user" ? principal.id : null)),
         accessSubject: subject && subject.id !== principal?.id ? subject : null,
         status: executionStatus(outcome.status, errorCode),

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 adminAppDomainRoutes from "./admin-app-domains";
 import adminAppKeyRoutes from "./admin-app-keys";
 import adminCoreSettingsRoutes from "./admin-core-settings";
 import adminDirectorySharesRoutes from "./admin-directory-shares";
@@ -107,6 +108,7 @@ 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)
@@ -135,8 +137,13 @@ 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";
+/** Core-owned app-key request authentication. */
+export { authenticateSignedAppRequest } from "./authenticate-app-request";
 export {
   CLOUD_MCP_PATH,
   CLOUD_MCP_PROTECTED_RESOURCE_PATH,

package/src/api/me.ts

@@ -5,7 +5,6 @@
  */
 
 import { err, fail, ok, type Result } from "@k2b/stdlib";
-import { sql } from "bun";
 import { type Context, Hono, type MiddlewareHandler } from "hono";
 import { deleteCookie } from "hono/cookie";
 import { createMiddleware } from "hono/factory";
@@ -42,6 +41,7 @@ import {
   WebAuthnPasskeySchema,
 } from "../contracts";
 import { CapabilityAppIdSchema } from "../contracts/capabilities";
+import { sql } from "../runtime/clients";
 import { type AuthContext, auth, getLocale, getTimeZone, jsonResponse, rateLimit, requiresAuth, respond, v } from "../server";
 import { APP_SESSION_FORBIDDEN } from "../server/middleware/auth";
 import { noTransform } from "../server/middleware/no-transform";

package/src/api/search.bench.ts

@@ -1,10 +1,10 @@
 import { ok } from "@k2b/stdlib";
-import { sql } from "bun";
 import type { MiddlewareHandler } from "hono";
 import { generateKeyPair, jwtVerify, SignJWT } from "jose";
 import { compileCapabilities } from "../_internal/capabilities";
 import { defineCapabilities, UniversalSearchDataSchema, UniversalSearchInputSchema } from "../contracts/capabilities";
 import type { CapabilityRegistryEntry } from "../contracts/registry";
+import { sql } from "../runtime/clients";
 import type { AuthContext } from "../server";
 import type { signInvocationToken } from "../services/identity/invocation-token";
 import type { withActiveIdentitySigner } from "../services/identity/key-ring";

package/src/app-pwa/service.ts

@@ -1,8 +1,9 @@
-import { sql, type TransactionSQL } from "bun";
+import type { TransactionSQL } from "bun";
 import { z } from "zod";
 import { GeoAutocompleteInputSchema } from "../contracts/geo";
 import { isInstallablePath } from "../contracts/installable";
 import { PWA_LIMITS } from "../contracts/pwa";
+import { sql } from "../runtime/clients";
 import { ratelimit } from "../server/ratelimit";
 import { REQUEST_IDLE_TIMEOUT_SECONDS } from "../server/request-timeout";
 import { getEffectivePermission, hasPermission } from "../server/services/access";