@k2b/cloud 0.47.0 → 0.49.0

package/src/services/geo/ledger.ts

@@ -1,8 +1,10 @@
-import { type SQL, sql } from "bun";
+import type { SQL } from "bun";
 import type { AppPwaActor } from "../../app-pwa/contracts";
-import type { AccessSubject, CapabilityExecutionContext } from "../../contracts";
+import type { CapabilityAppExecutionContext, CapabilityExecutionContext } from "../../contracts";
+import { sql } from "../../runtime/clients";
 import { audit } from "../audit";
 import { GeoError } from "./errors";
+import type { GeoBudgetSubject } from "./identity";
 import type { GeoConfig } from "./settings";
 
 export type GeoBudgetConfig = Pick<GeoConfig, "timezone" | "monthlyCredits" | "personDailyCredits">;
@@ -30,126 +32,136 @@ export const geoPeriods = (now: Date, timezone: string): { person: GeoPeriod; cl
     cloud: { period: day.slice(0, 7), resetsAt: boundary(32 * 86400_000, 7) },
   };
 };
-export const geoSubjectKey = (subject: AccessSubject) =>
-  subject.type === "user" ? `user:${subject.userId}` : `service_account:${subject.serviceAccountId}`;
+export const geoSubjectKey = (subject: GeoBudgetSubject) =>
+  subject.type === "app"
+    ? `app:${subject.appId}`
+    : subject.type === "user"
+      ? `user:${subject.userId}`
+      : `service_account:${subject.serviceAccountId}`;
 export type GeoReservation = {
   cost: number;
   group: string;
   rows: Array<{ scope: "cloud" | "person"; subject: string; period: string; resetsAt: string; limit: number }>;
 };
-const rowsFor = (subject: AccessSubject, config: GeoBudgetConfig, now: Date) => {
+const rowsFor = (subject: GeoBudgetSubject, config: GeoBudgetConfig, now: Date) => {
   const periods = geoPeriods(now, config.timezone);
   return [
     { scope: "cloud", subject: "*", ...periods.cloud, limit: config.monthlyCredits * 1000 },
     { scope: "person", subject: geoSubjectKey(subject), ...periods.person, limit: config.personDailyCredits * 1000 },
   ] satisfies GeoReservation["rows"];
 };
-export const createGeoLedger = (db: SQL = sql) => ({
-  async reserve(subject: AccessSubject, config: GeoBudgetConfig, cost: number, group: string, now: Date): Promise<GeoReservation> {
-    if (!Number.isSafeInteger(cost) || cost < 0) throw new Error("Invalid geo reservation");
-    const rows = rowsFor(subject, config, now);
-    await db.begin(async (tx) => {
-      // Fixed order across upserts, updates, shares and settlement: Cloud first, person second.
-      for (const row of rows)
-        await tx`INSERT INTO geo.usage(scope,subject,period) VALUES(${row.scope},${row.subject},${row.period}) ON CONFLICT DO NOTHING`;
-      for (const row of rows) {
-        // Keep the refusal's available/shortfall numbers in the same row-lock snapshot as admission.
-        const [balance] = await tx<{ used: number }[]>`SELECT used::float8 AS used FROM geo.usage
+export const createGeoLedger = (injectedDb?: SQL) => {
+  const db = () => injectedDb ?? sql;
+  return {
+    async reserve(subject: GeoBudgetSubject, config: GeoBudgetConfig, cost: number, group: string, now: Date): Promise<GeoReservation> {
+      if (!Number.isSafeInteger(cost) || cost < 0) throw new Error("Invalid geo reservation");
+      const rows = rowsFor(subject, config, now);
+      await db().begin(async (tx) => {
+        // Fixed order across upserts, updates, shares and settlement: Cloud first, person second.
+        for (const row of rows)
+          await tx`INSERT INTO geo.usage(scope,subject,period) VALUES(${row.scope},${row.subject},${row.period}) ON CONFLICT DO NOTHING`;
+        for (const row of rows) {
+          // Keep the refusal's available/shortfall numbers in the same row-lock snapshot as admission.
+          const [balance] = await tx<{ used: number }[]>`SELECT used::float8 AS used FROM geo.usage
           WHERE scope=${row.scope} AND subject=${row.subject} AND period=${row.period} FOR UPDATE`;
-        const changed = await tx`UPDATE geo.usage SET used=used+${cost} WHERE scope=${row.scope} AND subject=${row.subject}
+          const changed = await tx`UPDATE geo.usage SET used=used+${cost} WHERE scope=${row.scope} AND subject=${row.subject}
           AND period=${row.period} AND used+${cost}<=${row.limit} RETURNING used`;
-        if (!changed.length) {
-          const available = row.limit - (balance?.used ?? 0);
-          throw new GeoError("GEO_BUDGET_EXHAUSTED", {
-            scope: row.scope,
-            resetsAt: row.resetsAt,
-            requiredCredits: cost / 1000,
-            availableCredits: available / 1000,
-            shortfallCredits: (cost - available) / 1000,
-          });
+          if (!changed.length) {
+            const available = row.limit - (balance?.used ?? 0);
+            throw new GeoError("GEO_BUDGET_EXHAUSTED", {
+              scope: row.scope,
+              resetsAt: row.resetsAt,
+              requiredCredits: cost / 1000,
+              availableCredits: available / 1000,
+              shortfallCredits: (cost - available) / 1000,
+            });
+          }
         }
-      }
-      for (const row of rows)
-        await tx`INSERT INTO geo.shares(scope,subject,period,function_group,used)
+        for (const row of rows)
+          await tx`INSERT INTO geo.shares(scope,subject,period,function_group,used)
         VALUES(${row.scope},${row.subject},${row.period},${group},${cost})
         ON CONFLICT(scope,subject,period,function_group) DO UPDATE SET used=geo.shares.used+EXCLUDED.used`;
-    });
-    return { cost, group, rows };
-  },
-  async settle(reservation: GeoReservation, referenceCost: number) {
-    const refund = reservation.cost - referenceCost;
-    if (!Number.isSafeInteger(referenceCost) || referenceCost < 0 || !Number.isSafeInteger(refund))
-      throw new Error("Invalid geo settlement");
-    if (!refund) return;
-    // Negative refunds truthfully debit known routing overruns. Admission still uses the original
-    // bounded CAS transaction; future reservations see the overdrawn counters and are refused.
-    // Settle once per reservation, in the same fixed row order as admission.
-    await db.begin(async (tx) => {
-      for (const row of reservation.rows) {
-        await tx`UPDATE geo.usage SET used=used-${refund} WHERE scope=${row.scope} AND subject=${row.subject} AND period=${row.period}`;
-        await tx`UPDATE geo.shares SET used=used-${refund} WHERE scope=${row.scope} AND subject=${row.subject} AND period=${row.period} AND function_group=${reservation.group}`;
-      }
-    });
-  },
-  async availability(subject: AccessSubject, config: GeoBudgetConfig, now: Date) {
-    const balances = [];
-    for (const row of rowsFor(subject, config, now)) {
-      const [used] = await db<{ used: number }[]>`SELECT used::float8 AS used FROM geo.usage
+      });
+      return { cost, group, rows };
+    },
+    async settle(reservation: GeoReservation, referenceCost: number) {
+      const refund = reservation.cost - referenceCost;
+      if (!Number.isSafeInteger(referenceCost) || referenceCost < 0 || !Number.isSafeInteger(refund))
+        throw new Error("Invalid geo settlement");
+      if (!refund) return;
+      // Negative refunds truthfully debit known routing overruns. Admission still uses the original
+      // bounded CAS transaction; future reservations see the overdrawn counters and are refused.
+      // Settle once per reservation, in the same fixed row order as admission.
+      await db().begin(async (tx) => {
+        for (const row of reservation.rows) {
+          await tx`UPDATE geo.usage SET used=used-${refund} WHERE scope=${row.scope} AND subject=${row.subject} AND period=${row.period}`;
+          await tx`UPDATE geo.shares SET used=used-${refund} WHERE scope=${row.scope} AND subject=${row.subject} AND period=${row.period} AND function_group=${reservation.group}`;
+        }
+      });
+    },
+    async availability(subject: GeoBudgetSubject, config: GeoBudgetConfig, now: Date) {
+      const balances = [];
+      for (const row of rowsFor(subject, config, now)) {
+        const [used] = await db()<{ used: number }[]>`SELECT used::float8 AS used FROM geo.usage
         WHERE scope=${row.scope} AND subject=${row.subject} AND period=${row.period}`;
-      balances.push({ exhausted: (used?.used ?? 0) >= row.limit, resetsAt: row.resetsAt });
-    }
-    return { cloud: balances[0]!, person: balances[1]! };
-  },
-  async recordTransition(
-    event: "provider_key_rejected" | "monthly_budget_exhausted" | "route_cost_overrun",
-    timezone: string,
-    context: { actor: CapabilityExecutionContext["actor"] | AppPwaActor; requestId?: string },
-    now: Date,
-    metadata: Record<string, number> = {},
-  ) {
-    const period = geoPeriods(now, timezone).cloud.period;
-    await db.begin(async (tx) => {
-      const inserted =
-        event === "route_cost_overrun"
-          ? [true]
-          : await tx`INSERT INTO geo.audit_transitions(event,period) VALUES(${event},${period}) ON CONFLICT DO NOTHING RETURNING event`;
-      if (!inserted.length) return;
-      const actor =
-        context.actor.kind === "device" || context.actor.kind === "visit"
-          ? null
-          : context.actor.kind === "user"
-            ? {
-                userId: context.actor.user.id,
-                uid: context.actor.user.uid,
-                provider: context.actor.user.provider,
-                roles: context.actor.user.roles,
-              }
-            : { uid: `service-account:${context.actor.serviceAccount.id}`, provider: "service_account", roles: context.actor.scopes };
-      await audit.record(
-        {
-          action: `core.geo.${event}`,
-          outcome: event === "monthly_budget_exhausted" ? "denied" : "failed",
-          actor,
-          requestId: context.requestId,
-          metadata: {
-            period,
-            ...metadata,
-            ...(context.actor.kind === "device" || context.actor.kind === "visit"
-              ? {
-                  appId: context.actor.appId,
-                  subject: { type: "user", userId: context.actor.ownerUserId },
-                  via: {
-                    kind: context.actor.kind,
+        balances.push({ exhausted: (used?.used ?? 0) >= row.limit, resetsAt: row.resetsAt });
+      }
+      return { cloud: balances[0]!, person: balances[1]! };
+    },
+    async recordTransition(
+      event: "provider_key_rejected" | "monthly_budget_exhausted" | "route_cost_overrun",
+      timezone: string,
+      context: { actor: CapabilityExecutionContext["actor"] | CapabilityAppExecutionContext["actor"] | AppPwaActor; requestId?: string },
+      now: Date,
+      metadata: Record<string, number> = {},
+    ) {
+      const period = geoPeriods(now, timezone).cloud.period;
+      await db().begin(async (tx) => {
+        const inserted =
+          event === "route_cost_overrun"
+            ? [true]
+            : await tx`INSERT INTO geo.audit_transitions(event,period) VALUES(${event},${period}) ON CONFLICT DO NOTHING RETURNING event`;
+        if (!inserted.length) return;
+        const actor =
+          context.actor.kind === "device" || context.actor.kind === "visit"
+            ? null
+            : context.actor.kind === "app"
+              ? { uid: `app:${context.actor.appId}`, provider: "app", roles: [] }
+              : context.actor.kind === "user"
+                ? {
+                    userId: context.actor.user.id,
+                    uid: context.actor.user.uid,
+                    provider: context.actor.user.provider,
+                    roles: context.actor.user.roles,
+                  }
+                : { uid: `service-account:${context.actor.serviceAccount.id}`, provider: "service_account", roles: context.actor.scopes };
+        await audit.record(
+          {
+            action: `core.geo.${event}`,
+            outcome: event === "monthly_budget_exhausted" ? "denied" : "failed",
+            actor,
+            requestId: context.requestId,
+            metadata: {
+              period,
+              ...metadata,
+              ...(context.actor.kind === "app" ? { appId: context.actor.appId, keyId: context.actor.keyId } : {}),
+              ...(context.actor.kind === "device" || context.actor.kind === "visit"
+                ? {
                     appId: context.actor.appId,
-                    deviceId: context.actor.deviceId,
-                    ...(context.actor.kind === "visit" ? { visitId: context.actor.visitId } : {}),
-                  },
-                }
-              : {}),
+                    subject: { type: "user", userId: context.actor.ownerUserId },
+                    via: {
+                      kind: context.actor.kind,
+                      appId: context.actor.appId,
+                      deviceId: context.actor.deviceId,
+                      ...(context.actor.kind === "visit" ? { visitId: context.actor.visitId } : {}),
+                    },
+                  }
+                : {}),
+            },
           },
-        },
-        tx,
-      );
-    });
-  },
-});
+          tx,
+        );
+      });
+    },
+  };
+};

package/src/services/geo/migrate.ts

@@ -1,4 +1,5 @@
-import { type SQL, sql } from "bun";
+import type { SQL } from "bun";
+import { sql } from "../../runtime/clients";
 export const migrate = async (db: SQL = sql): Promise<void> => {
   await db.begin(async (tx) => {
     await tx`SELECT pg_advisory_xact_lock(hashtextextended('core.geo.migrations', 0))`;

package/src/services/geo/route-chain.ts

@@ -6,9 +6,9 @@ import type { createGeoCache } from "./cache";
 import { geoCacheKey } from "./cache";
 import { geoReferenceCost } from "./costs";
 import { GeoError, GeoProviderError, limitExceeded } from "./errors";
+import { type GeoContext, geoIdentity } from "./identity";
 import type { createGeoLedger } from "./ledger";
 import { geoRouteReferenceCost } from "./route-costs";
-import type { GeoContext } from "./service";
 import { type GeoConfig, geoPlan } from "./settings";
 
 export type GeoRouteChainDependencies = {
@@ -42,14 +42,14 @@ export const runGeoRouteChain = async <T>(
   work: (call: GeoRouteChainCall) => Promise<T>,
 ): Promise<T> => {
   const { ledger, bucket, cache, now } = dependencies;
-  if (!context.accessSubject) throw new GeoError("GEO_FORBIDDEN");
+  const { accessSubject } = geoIdentity(context);
   context.signal?.throwIfAborted();
   const maximumCredits = Math.min(config.personDailyCredits, config.monthlyCredits);
   if (reserveCost > maximumCredits * 1000) limitExceeded("reservationCredits", maximumCredits, reserveCost / 1000);
   let reservation: Awaited<ReturnType<typeof ledger.reserve>>;
   try {
     // One atomic admission for all known geocodes and every possible paid routing step.
-    reservation = await ledger.reserve(context.accessSubject, config, reserveCost, "route", now());
+    reservation = await ledger.reserve(accessSubject, config, reserveCost, "route", now());
   } catch (error) {
     if (error instanceof GeoError && error.code === "GEO_BUDGET_EXHAUSTED" && error.details.scope === "cloud")
       await dependencies.recordTransition("monthly_budget_exhausted", config.timezone, context);

package/src/services/geo/service.ts

@@ -1,6 +1,4 @@
 import type { z } from "zod";
-import type { AppPwaActor } from "../../app-pwa/contracts";
-import type { AccessSubject, CapabilityExecutionContext, RequestActor } from "../../contracts";
 import {
   GeoAutocompleteDataSchema,
   type GeoAutocompleteInput,
@@ -26,28 +24,10 @@ import { cutGeoWindow, decodePolyline6, locateOnGeoLine, simplifyGeoLine } from
 import { createGeoRouteService } from "./route-service";
 import { type GeoConfig, geoPlan, readGeoConfig } from "./settings";
 
-export type GeoContext = Partial<Pick<CapabilityExecutionContext, "actor" | "accessSubject" | "locale" | "signal" | "requestId">>;
-/** Internal, narrow App-PWA autocomplete adapter; never a RequestActor or capability caller. */
-export type AppPwaGeoContext = { actor: AppPwaActor; locale?: string; signal?: AbortSignal; requestId?: string };
-type GeoCallContext = GeoContext | AppPwaGeoContext;
-export const geoIdentity = (context: GeoContext): { actor: RequestActor; accessSubject: AccessSubject } => {
-  const { actor, accessSubject } = context;
-  if (
-    !actor ||
-    !accessSubject ||
-    !(actor.kind === "user" ? actor.user?.id : actor.kind === "service_account" ? actor.serviceAccount?.id : undefined) ||
-    !(accessSubject.type === "user" ? accessSubject.userId : accessSubject.serviceAccountId)
-  )
-    throw new GeoError("GEO_FORBIDDEN");
-  return { actor, accessSubject };
-};
-const geoCallIdentity = (context: GeoCallContext): { actor: RequestActor | AppPwaActor; accessSubject: AccessSubject } => {
-  if (context.actor?.kind === "device" || context.actor?.kind === "visit") {
-    if (!context.actor.ownerUserId) throw new GeoError("GEO_FORBIDDEN");
-    return { actor: context.actor, accessSubject: { type: "user", userId: context.actor.ownerUserId } };
-  }
-  return geoIdentity({ actor: context.actor, accessSubject: "accessSubject" in context ? context.accessSubject : undefined });
-};
+export { type AppPwaGeoContext, type GeoContext, geoIdentity } from "./identity";
+
+import { type AppPwaGeoContext, type GeoCallContext, type GeoContext, geoCallIdentity, geoIdentity } from "./identity";
+
 const bound = (name: string, value: number, min: number, max: number, integer = false) => {
   if (!Number.isFinite(value) || value > max || value < min || (integer && !Number.isInteger(value)))
     limitExceeded(name, value < min ? min : max, value);

package/src/services/geoip/index.ts

@@ -1,4 +1,3 @@
-import { sql } from "bun";
 import { HTTPException } from "hono/http-exception";
 import {
   DBIP_ATTRIBUTION,
@@ -8,6 +7,7 @@ import {
   type GeoIpAdminStatus,
   type GeoIpKind,
 } from "../../contracts/geoip";
+import { sql } from "../../runtime/clients";
 import { createGeoIp, type GeoIp, type GeoIpDatabaseInfo, getGeoIp } from "../../server/request-context/geoip";
 import { audit } from "../audit";
 import { GeoIpError, parseGeoIpUpload, readGeoIpUpload } from "./upload";
@@ -79,11 +79,11 @@ const serialized = <T>(write: () => Promise<T>): Promise<T> => {
   return run;
 };
 export const createGeoIpService = (options: { db?: typeof sql; reader?: GeoIp; bundled?: () => ReturnType<GeoIp["status"]> } = {}) => {
-  const db = options.db ?? sql;
+  const db = () => options.db ?? sql;
   const reader = () => options.reader ?? getGeoIp();
   const status = async (actor: Actor, config: { now?: () => number } = {}): Promise<GeoIpAdminStatus> => {
     requireAdmin(actor);
-    const rows = await db<GeoIpUploadInfo[]>`
+    const rows = await db()<GeoIpUploadInfo[]>`
       SELECT d.kind, d.sha256, (d.metadata->>'size')::int AS size, d.database_type, d.build_epoch,
         d.metadata->'description'->>'en' AS description, d.uploaded_at, d.uploaded_by,
         COALESCE(NULLIF(u.display_name, ''), u.uid) AS uploader_name
@@ -103,7 +103,7 @@ export const createGeoIpService = (options: { db?: typeof sql; reader?: GeoIp; b
         database.info.sha256 = sha256;
         config.signal?.throwIfAborted();
         await serialized(async () => {
-          await db.begin(async (tx) => {
+          await db().begin(async (tx) => {
             await tx`
               INSERT INTO geoip.databases (kind, data, sha256, database_type, build_epoch, metadata, uploaded_by)
               VALUES (${kind}, ${bytes}, ${sha256}, ${metadata.databaseType}, ${metadata.buildEpoch}::timestamptz,
@@ -132,7 +132,7 @@ export const createGeoIpService = (options: { db?: typeof sql; reader?: GeoIp; b
     async reset(actor: Actor, kind: GeoIpKind) {
       requireAdmin(actor);
       const changed = await serialized(async () => {
-        const deleted = await db.begin(async (tx) => {
+        const deleted = await db().begin(async (tx) => {
           const [row] = await tx<{ sha256: string; database_type: string; build_epoch: Date; size: number }[]>`
           DELETE FROM geoip.databases WHERE kind = ${kind}
           RETURNING sha256, database_type, build_epoch, octet_length(data) AS size`;

package/src/services/geoip/store.ts

@@ -1,30 +1,33 @@
-import { sql } from "bun";
 import { GEOIP_MAX_DATABASE_BYTES, type GeoIpKind } from "../../contracts/geoip";
+import { sql } from "../../runtime/clients";
 import type { GeoIpUploads } from "../../server/request-context/geoip";
 
 const SLICE_BYTES = 8 * 1024 * 1024;
-export const createGeoIpUploads = (db: typeof sql = sql): GeoIpUploads => ({
-  async versions() {
-    const rows = await db<{ kind: GeoIpKind; sha256: string }[]>`SELECT kind, sha256 FROM geoip.databases`;
-    return Object.fromEntries(rows.map((row) => [row.kind, row.sha256]));
-  },
-  async read(kind, sha256) {
-    const [row] = await db<{ size: number }[]>`
+export const createGeoIpUploads = (injectedDb?: typeof sql): GeoIpUploads => {
+  const db = () => injectedDb ?? sql;
+  return {
+    async versions() {
+      const rows = await db()<{ kind: GeoIpKind; sha256: string }[]>`SELECT kind, sha256 FROM geoip.databases`;
+      return Object.fromEntries(rows.map((row) => [row.kind, row.sha256]));
+    },
+    async read(kind, sha256) {
+      const [row] = await db()<{ size: number }[]>`
       SELECT octet_length(data) AS size FROM geoip.databases WHERE kind = ${kind} AND sha256 = ${sha256}`;
-    if (!row) return null;
-    if (row.size < 1 || row.size > GEOIP_MAX_DATABASE_BYTES) throw new Error("Invalid GeoIP database size");
-    const bytes = Buffer.allocUnsafe(row.size);
-    for (let offset = 0; offset < bytes.length; offset += SLICE_BYTES) {
-      const length = Math.min(SLICE_BYTES, bytes.length - offset);
-      const [slice] = await db<{ data: Uint8Array }[]>`
+      if (!row) return null;
+      if (row.size < 1 || row.size > GEOIP_MAX_DATABASE_BYTES) throw new Error("Invalid GeoIP database size");
+      const bytes = Buffer.allocUnsafe(row.size);
+      for (let offset = 0; offset < bytes.length; offset += SLICE_BYTES) {
+        const length = Math.min(SLICE_BYTES, bytes.length - offset);
+        const [slice] = await db()<{ data: Uint8Array }[]>`
         SELECT substring(data FROM ${offset + 1} FOR ${length}) AS data
         FROM geoip.databases WHERE kind = ${kind} AND sha256 = ${sha256}`;
-      if (!slice) return null;
-      if (slice.data.byteLength !== length) throw new Error("Incomplete GeoIP database slice");
-      bytes.set(slice.data, offset);
-    }
-    return bytes;
-  },
-});
+        if (!slice) return null;
+        if (slice.data.byteLength !== length) throw new Error("Incomplete GeoIP database slice");
+        bytes.set(slice.data, offset);
+      }
+      return bytes;
+    },
+  };
+};
 
 export const geoIpUploads = createGeoIpUploads();

package/src/services/help/index.ts

@@ -1,8 +1,9 @@
-import { type SQL, sql } from "bun";
+import type { SQL } from "bun";
 import { appAudienceRoles, hasAnyAppRole } from "../../_internal/app-roles";
 import { getApp, listApps } from "../../_internal/registry";
 import type { AppRegistryEntry } from "../../contracts/registry";
 import type { RequestActor } from "../../contracts/shared";
+import { sql } from "../../runtime/clients";
 import type { RequestAuthority } from "../../server/middleware/auth";
 import { resolveAppPresentations } from "../../shared/app-presentation";
 import { type HelpArticleLink, helpLocaleChain, parseHelpReference } from "../../shared/help";

package/src/services/help/store.ts

@@ -1,5 +1,6 @@
-import { type SQL, sql } from "bun";
+import type { SQL } from "bun";
 import { APP_REGISTRY_TTL_MS } from "../../_internal/registry";
+import { sql } from "../../runtime/clients";
 import type { HelpAccessLevel, HelpKind } from "../../shared/help";
 import { ensureSchema, toPgTextArray } from "../postgres";
 import type { HelpCorpus, HelpMetadata } from "./types";

package/src/services/identity/app-request.ts

@@ -0,0 +1,44 @@
+import { getAppWorkloadCredential } from "../../_internal/workload-credential";
+import { parseAppKey } from "../../app-key";
+import { env } from "../../config/env";
+import { CapabilityAppIdSchema } from "../../contracts/capabilities";
+import { signAppProof } from "../../runtime/bootstrap-protocol";
+
+/** Send only to Core. Call for every transmission, including safe caller-owned retries. */
+export const sendAppRequest = async (
+  request: Request,
+  options: {
+    appId: string;
+    transport?: (request: Request) => Promise<Response>;
+    /** Release N legacy authority; evaluated only when no app key is configured. */
+    bearer?: () => string | undefined;
+  },
+): Promise<Response> => {
+  const appId = CapabilityAppIdSchema.parse(options.appId);
+  const headers = new Headers(request.headers);
+  const declaredApp = headers.get("X-Cloud-App-Id");
+  if (declaredApp !== null && declaredApp !== appId) throw new Error("App identity header does not match the calling application");
+  headers.set("X-Cloud-App-Id", appId);
+  const keyValue = env.CLOUD_APP_KEY;
+  if (keyValue) {
+    const key = parseAppKey(keyValue);
+    if (key.appId !== options.appId) throw new Error("App-key appId does not match the calling application");
+    const url = new URL(request.url);
+    const proof = await signAppProof(key, {
+      method: request.method,
+      path: url.pathname + url.search,
+      body: new Uint8Array(await request.clone().arrayBuffer()),
+    });
+    headers.set("authorization", `Bearer ${proof}`);
+  } else if (!headers.has("authorization")) {
+    const token = (options.bearer ?? getAppWorkloadCredential)();
+    if (!token) throw new Error("App workload authorization is unavailable");
+    headers.set("authorization", `Bearer ${token}`);
+  }
+  // A proof is bound to this target; redirects must never carry it elsewhere.
+  return (options.transport ?? fetch)(new Request(request, { headers, redirect: "error" }));
+};
+
+/** Legacy workload tokens and the OAuth secret never contain JWT separators. */
+export const isAppRequestProof = (authorization: string | undefined): boolean =>
+  authorization?.startsWith("Bearer ") === true && authorization.slice(7).includes(".");

package/src/services/identity/constants.ts

@@ -1,6 +1,7 @@
 export const CLOUD_SESSION_JWKS_PATH = "/.well-known/cloud-session-jwks.json";
 export const CLOUD_INVOCATION_JWKS_PATH = "/.well-known/cloud-invocation-jwks.json";
 export const CLOUD_OAUTH_JWKS_PATH = "/.well-known/jwks.json";
+export const CLOUD_INTERNAL_OAUTH_JWKS_PATH = "/api/_internal/identity/v1/oauth/jwks";
 export const CLOUD_SESSION_TOKEN_TYPE = "cloud-session+jwt";
 export const CLOUD_SESSION_AUDIENCE = "cloud";
 export const CLOUD_INVOCATION_TOKEN_TYPE = "cloud-invocation+jwt";

package/src/services/identity/index.ts

@@ -1,4 +1,5 @@
 export { getAppWorkloadCredential } from "../../_internal/workload-credential";
+export { isAppRequestProof, sendAppRequest } from "./app-request";
 export {
   CLOUD_INVOCATION_JWKS_PATH,
   CLOUD_INVOCATION_PROTOCOL_VERSION,

package/src/services/identity/invocation-actor.ts

@@ -1,4 +1,5 @@
-import { sql } from "bun";
+import { sql } from "../../runtime/clients";
+
 import type { RequestActor } from "../../server/middleware/auth";
 import type { AccessSubject } from "../../server/services/access";
 import { isAccountCategoryAllowed } from "../account-category-policy";