@k2b/cloud 0.47.0 → 0.49.0

package/src/services/app-events/admin.ts

@@ -13,12 +13,12 @@ type Dependencies = {
   deadLetters: (after?: string) => Promise<TopicDeadLetter<AppEventEnvelope>[]>;
   streams: () => AsyncIterable<Pick<TopicInventoryEntry, "id" | "firstSequence">>;
 };
-export function createEventAdministration(db: SQL, dependencies: Dependencies) {
+export function createEventAdministration(db: () => SQL, dependencies: Dependencies) {
   const catalog = async (locale = "en"): Promise<{ events: CapabilityEventCatalogEntry[] }> => {
     const [entries, declarations, storedSubscriptions] = await Promise.all([
       dependencies.registry(),
-      db<StoredDeclaration[]>`SELECT * FROM events.app_declarations WHERE retired_at IS NULL ORDER BY type, version`,
-      db<
+      db()<StoredDeclaration[]>`SELECT * FROM events.app_declarations WHERE retired_at IS NULL ORDER BY type, version`,
+      db()<
         {
           appId: string;
           subscriptionId: string;
@@ -62,7 +62,7 @@ export function createEventAdministration(db: SQL, dependencies: Dependencies) {
   };
   const subscriptions = async (app?: string) => {
     return {
-      items: await db`
+      items: await db()`
         SELECT subscription.id, subscription.app_id AS "appId", subscription.event_type AS "eventType", subscription.version,
           subscription.state, subscription.reason, subscription.first_seen_at AS "firstSeenAt",
           (SELECT jsonb_object_agg(state, count) FROM (
@@ -77,7 +77,7 @@ export function createEventAdministration(db: SQL, dependencies: Dependencies) {
   const deliveries = async (filter: { app?: string; state?: string; eventType?: string; offset?: number; limit?: number } = {}) => {
     const limit = Math.max(1, Math.min(100, filter.limit ?? 50));
     const offset = Math.max(0, filter.offset ?? 0);
-    const rows = await db`
+    const rows = await db()`
       SELECT delivery.id, delivery.event_id AS "eventId", delivery.subscription_id AS "subscriptionId",
         subscription.app_id AS "appId", event.type AS "eventType", delivery.state, delivery.code, delivery.attempts,
         delivery.last_error AS "lastError", delivery.last_attempt_at AS "lastAttemptAt",
@@ -104,7 +104,7 @@ export function createEventAdministration(db: SQL, dependencies: Dependencies) {
     };
   };
   const redeliver = async (id: string, actor: AuditActor) =>
-    db.begin(async (tx) => {
+    db().begin(async (tx) => {
       const changed = await tx`
         UPDATE events.app_deliveries delivery SET state = 'pending', code = NULL, last_error = NULL,
           attempts = 0, unreachable_count = 0, retained_from = now(), next_attempt_at = now(), claimed_until = NULL, claim_token = NULL, updated_at = now()
@@ -129,12 +129,12 @@ export function createEventAdministration(db: SQL, dependencies: Dependencies) {
     });
 
   const status = async () => {
-    const [stored] = await db`
+    const [stored] = await db()`
       SELECT state, code, last_sequence AS "lastSequence", gap_from AS "gapFrom", gap_to AS "gapTo", updated_at AS "updatedAt"
       FROM events.app_broker_status WHERE id = true
     `;
-    const [rejected] = await db`SELECT count(*)::int AS count FROM events.app_events WHERE state = 'rejected'`;
-    const rejections = await db`
+    const [rejected] = await db()`SELECT count(*)::int AS count FROM events.app_events WHERE state = 'rejected'`;
+    const rejections = await db()`
       SELECT type, source, code, received_at AS time FROM events.app_events
       WHERE state = 'rejected' ORDER BY seq DESC LIMIT 10
     `;
@@ -156,7 +156,7 @@ export function createEventAdministration(db: SQL, dependencies: Dependencies) {
     };
   };
   const checkGap = async () => {
-    const [stored] = await db<{ last_sequence: string }[]>`
+    const [stored] = await db()<{ last_sequence: string }[]>`
       SELECT last_sequence FROM events.app_broker_status WHERE id = true
     `;
     let position = Number(stored?.last_sequence ?? 0);
@@ -175,7 +175,7 @@ export function createEventAdministration(db: SQL, dependencies: Dependencies) {
       after = next;
     }
     if (seen.size) {
-      await db`
+      await db()`
         UPDATE events.app_broker_status SET unseen_sequences = unseen_sequences - (
           SELECT range_agg(int8range(sequence, sequence + 1, '[)'))
           FROM unnest(${toPgTextArray([...seen].map(String))}::bigint[]) AS sequence
@@ -183,13 +183,13 @@ export function createEventAdministration(db: SQL, dependencies: Dependencies) {
       `;
     }
     while (seen.has(position + 1)) position++;
-    await db`
+    await db()`
       UPDATE events.app_broker_status SET last_sequence = ${position}, updated_at = now()
       WHERE id = true AND last_sequence < ${position}
     `;
     for await (const stream of dependencies.streams()) {
       if (stream.id !== "cloud:app-events") continue;
-      await db`
+      await db()`
         UPDATE events.app_broker_status SET state = 'gap_detected', code = 'reconcile_required',
           gap_from = COALESCE(gap_from, LEAST(lower(unseen_sequences), last_sequence + 1)), gap_to = ${stream.firstSequence - 1}, updated_at = now()
         WHERE id = true AND LEAST(lower(unseen_sequences), last_sequence + 1) < ${stream.firstSequence}
@@ -199,7 +199,7 @@ export function createEventAdministration(db: SQL, dependencies: Dependencies) {
     }
   };
   const acknowledgeGap = async (actor: AuditActor) =>
-    db.begin(async (tx) => {
+    db().begin(async (tx) => {
       const [previous] = await tx`
         SELECT state, gap_from, gap_to FROM events.app_broker_status WHERE id = true FOR UPDATE
       `;
@@ -223,7 +223,7 @@ export function createEventAdministration(db: SQL, dependencies: Dependencies) {
       return result;
     });
   const retain = async () =>
-    db.begin(async (tx) => {
+    db().begin(async (tx) => {
       await tx`
         UPDATE events.app_deliveries SET state = 'cancelled', code = 'retention_expired',
           claimed_until = NULL, claim_token = NULL, updated_at = now()

package/src/services/app-events/declarations.ts

@@ -34,13 +34,14 @@ async function auditTransitions(tx: SQL, transitions: Transition[]) {
   }
 }
 
-export function createDeclarationSync(db: SQL, registry: () => Promise<CapabilityRegistryEntry[]>) {
+export function createDeclarationSync(db: () => SQL, registry: () => Promise<CapabilityRegistryEntry[]>) {
   let previousSnapshot: string | undefined;
+  let previousDatabase: SQL | undefined;
   let lastCheckedAt = -Infinity;
   let running: Promise<void> | undefined;
 
   async function sync(entries: CapabilityRegistryEntry[]) {
-    await db.begin(async (tx) => {
+    await db().begin(async (tx) => {
       for (const entry of entries.toSorted((left, right) => left.appId.localeCompare(right.appId))) {
         const hash = capabilityHash({ events: entry.manifest.events ?? [], subscribes: entry.manifest.subscribes ?? [] });
         const [known] = await tx`SELECT hash FROM events.app_manifests WHERE app_id = ${entry.appId}`;
@@ -173,11 +174,13 @@ export function createDeclarationSync(db: SQL, registry: () => Promise<Capabilit
         }))
         .sort((left, right) => left.appId.localeCompare(right.appId)),
     );
-    if (snapshotHash === previousSnapshot && performance.now() - lastCheckedAt < 30_000) return;
+    const database = db();
+    if (database === previousDatabase && snapshotHash === previousSnapshot && performance.now() - lastCheckedAt < 30_000) return;
     running = sync(entries);
     try {
       await running;
       previousSnapshot = snapshotHash;
+      previousDatabase = database;
       lastCheckedAt = performance.now();
     } finally {
       running = undefined;

package/src/services/app-events/deliver.ts

@@ -40,14 +40,14 @@ async function auditFailure(tx: SQL, row: Delivery, code: string | null) {
 }
 
 export function createEventDelivery(
-  db: SQL,
+  db: () => SQL,
   findApp: typeof getCapability,
   reconcileSubscriptions: () => Promise<void>,
   dependencies: Dependencies,
 ) {
   async function postpone(row: Delivery) {
     const delay = Math.min(30_000 * 2 ** Math.min(row.unreachable_count, 7), 3_600_000);
-    await db`
+    await db()`
       UPDATE events.app_deliveries SET state = 'retrying', code = 'subscriber_unreachable', attempts = attempts - 1,
         unreachable_count = unreachable_count + 1, claimed_until = NULL, claim_token = NULL,
         next_attempt_at = now() + ${delay} * interval '1 millisecond', updated_at = now()
@@ -55,7 +55,7 @@ export function createEventDelivery(
     `;
   }
   const claim = async () =>
-    db.begin(async (tx) => {
+    db().begin(async (tx) => {
       const exhausted = await tx<Delivery[]>`
         UPDATE events.app_deliveries SET state = 'failed', code = 'attempts_exhausted',
           claimed_until = NULL, claim_token = NULL, updated_at = now()
@@ -99,7 +99,7 @@ export function createEventDelivery(
     code: string | null,
     error: string | null = null,
   ) =>
-    db.begin(async (tx) => {
+    db().begin(async (tx) => {
       const delay = APP_EVENT_DELIVERY_BACKOFF_MS[Math.min(row.attempts - 1, APP_EVENT_DELIVERY_BACKOFF_MS.length - 1)] ?? 0;
       const changed = await tx`
         UPDATE events.app_deliveries SET state = ${state}, code = ${code}, last_error = ${error},
@@ -122,7 +122,7 @@ export function createEventDelivery(
 
   const deliver = async (row: Delivery) => {
     try {
-      const [subscription] = await db`
+      const [subscription] = await db()`
         SELECT state, reason FROM events.app_subscriptions WHERE id = ${row.subscription_id}
       `;
       if (subscription?.state === "cancelled") {
@@ -131,7 +131,7 @@ export function createEventDelivery(
       }
       if (subscription?.state !== "active") {
         // A declaration transition can block a subscription after this delivery was claimed.
-        await db`
+        await db()`
           UPDATE events.app_deliveries SET state = 'retrying', code = ${subscription?.reason ?? "subscription_blocked"},
             attempts = attempts - 1, claimed_until = NULL, claim_token = NULL, next_attempt_at = now(), updated_at = now()
           WHERE id = ${row.id}::uuid AND claim_token = ${row.claim_token}::uuid AND state IN ('pending', 'retrying')

package/src/services/app-events.ts

@@ -1,10 +1,11 @@
 import type { TopicDeadLetter, TopicInventoryEntry } from "@k2b/sync";
-import { type SQL, sql } from "bun";
+import type { SQL } from "bun";
 import { lazySync } from "../_internal/process-sync";
 import { getCapability, listCapabilities } from "../_internal/registry";
 import type { AppEventEnvelope } from "../contracts/app-events";
 import type { CapabilityRegistryEntry } from "../contracts/registry";
 import { appEventTopic } from "../events/app-event-delivery";
+import { sql } from "../runtime/clients";
 import { createEventAcceptance } from "./app-events/accept";
 import { createEventAdministration } from "./app-events/admin";
 import { createDeclarationSync } from "./app-events/declarations";
@@ -28,7 +29,7 @@ type BrokerDependencies = {
 const message = (error: unknown): string => (error instanceof Error ? error.message : String(error)).slice(0, 1000);
 
 export const createAppEventBroker = (dependencies: BrokerDependencies = {}) => {
-  const db = dependencies.db ?? sql;
+  const db = () => dependencies.db ?? sql;
   const registry = dependencies.registry ?? listCapabilities;
   const declarations = createDeclarationSync(db, registry);
   const admin = createEventAdministration(db, {

package/src/services/app-keys.ts

@@ -1,7 +1,8 @@
 import { err, fail, ok, type Result } from "@k2b/stdlib";
-import { type SQL, sql } from "bun";
+import type { SQL } from "bun";
 import { appKeyFingerprint, validateAppKeyAppId } from "../app-key";
 import type { User } from "../contracts/shared";
+import { sql } from "../runtime/clients";
 import { audit } from "./audit";
 import { serviceAccounts } from "./service-accounts";
 
@@ -13,6 +14,7 @@ export type AppKeyMetadata = {
   kind: "app_key";
   name: string;
   publicKey: string;
+  grants: "oauth:issue"[];
   fingerprint: string;
   status: "active" | "expired" | "revoked";
   accountStatus: "active" | "disabled";
@@ -23,12 +25,18 @@ export type AppKeyMetadata = {
   revokedBy: string | null;
   lastUsedAt: string | null;
 };
+export type LastRejectedStart = {
+  at: string;
+  reason: "revoked" | "expired" | "disabled" | "connections_not_permitted";
+  keyId: string | null;
+};
 type Row = {
   id: string;
   app_id: string;
   service_account_id: string;
   name: string;
   public_key: string;
+  oauth_issue_allowed: boolean;
   fingerprint: string;
   key_status: AppKeyMetadata["status"];
   account_status: AppKeyMetadata["accountStatus"];
@@ -46,6 +54,7 @@ const map = (row: Row): AppKeyMetadata => ({
   kind: "app_key",
   name: row.name,
   publicKey: row.public_key,
+  grants: row.oauth_issue_allowed ? ["oauth:issue"] : [],
   fingerprint: row.fingerprint,
   status: row.key_status,
   accountStatus: row.account_status,
@@ -88,6 +97,7 @@ export const registerAppKey = async (params: {
   publicKey: string;
   name?: string;
   expiresAt?: string;
+  grants?: "oauth:issue"[];
 }): Promise<
   Result<{
     keyId: string;
@@ -99,6 +109,7 @@ export const registerAppKey = async (params: {
 > => {
   const valid = validateAdmin(params.actor, params.appId);
   if (!valid.ok) return valid;
+  if (params.grants?.some((grant) => grant !== "oauth:issue")) return fail(err.badInput("Unknown app key grant"));
   const name = params.name?.trim() ?? "App key";
   if (!name || name.length > 120) return fail(err.badInput("Key name must contain 1 to 120 characters"));
   let fingerprint: string;
@@ -159,10 +170,11 @@ export const registerAppKey = async (params: {
     `;
     if ((count?.active ?? 0) >= 2)
       return fail({ ...err.conflict("App key"), message: "An app can have at most two active keys; revoke an old key first" });
+    // Grants are explicit on every new enrollment, including rotation.
     const [row] = await db<{ id: string }[]>`
       INSERT INTO auth.service_account_credentials
-        (service_account_id, name, kind, public_key, fingerprint, created_by, expires_at)
-      VALUES (${accountId}::uuid, ${name}, 'app_key', ${params.publicKey}, ${fingerprint}, ${params.actor.id}::uuid, ${expiresAt})
+        (service_account_id, name, kind, public_key, fingerprint, created_by, expires_at, oauth_issue_allowed)
+      VALUES (${accountId}::uuid, ${name}, 'app_key', ${params.publicKey}, ${fingerprint}, ${params.actor.id}::uuid, ${expiresAt}, ${params.grants?.includes("oauth:issue") ?? false})
       RETURNING id
     `;
     if (!row) throw new Error("App key registration returned no key");
@@ -172,7 +184,7 @@ export const registerAppKey = async (params: {
         outcome: "allowed",
         actor: actorForAudit(params.actor),
         target: { type: "service_account_credential", id: row.id, label: name },
-        metadata: { appId: params.appId, serviceAccountId: accountId, fingerprint },
+        metadata: { appId: params.appId, serviceAccountId: accountId, fingerprint, grants: params.grants ?? [] },
       },
       db,
     );
@@ -201,7 +213,21 @@ export const listAppKeys = async (params: { actor: AdminActor; appId: string; pa
     `;
     total = count?.total ?? 0;
   }
-  return ok({ installationId: await getInstallationId(), items: rows.map(map), page, perPage, total, hasNext: page * perPage < total });
+  const [rejection] = await sql<{ rejected_at: Date; reason: LastRejectedStart["reason"]; key_id: string | null }[]>`
+    SELECT rejected_at, reason, key_id FROM auth.app_start_rejections WHERE app_id = ${params.appId}
+  `;
+  const lastRejectedStart: LastRejectedStart | null = rejection
+    ? { at: rejection.rejected_at.toISOString(), reason: rejection.reason, keyId: rejection.key_id }
+    : null;
+  return ok({
+    installationId: await getInstallationId(),
+    items: rows.map(map),
+    lastRejectedStart,
+    page,
+    perPage,
+    total,
+    hasNext: page * perPage < total,
+  });
 };
 
 export const listAppsWithKeys = async (params: { actor: AdminActor; page?: number; perPage?: number }) => {
@@ -268,8 +294,11 @@ export const revokeAppKey = async (params: { actor: AdminActor; appId: string; k
   });
 };
 
-/** Bootstrap and signed workload requests must query this directly; no cache. */
-export const getActiveAppKey = async (params: { appId: string; keyId: string }, db: SQL = sql): Promise<AppKeyMetadata | null> => {
+/** Core bootstrap diagnostics need the stored public key even after revocation; this does not authenticate it. */
+export const getStoredAppKey = async (
+  params: { appId: string; keyId: string },
+  db: SQL = sql,
+): Promise<(AppKeyMetadata & { connectionsAllowed: boolean; oauthIssueAllowed: boolean }) | null> => {
   try {
     validateAppKeyAppId(params.appId);
   } catch {
@@ -277,14 +306,19 @@ export const getActiveAppKey = async (params: { appId: string; keyId: string },
   }
   if (params.keyId.length !== 36 || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(params.keyId))
     return null;
-  const [row] = await db<Row[]>`
+  const [row] = await db<(Row & { connections_allowed: boolean })[]>`
     SELECT ${db.unsafe(columns)} FROM auth.service_account_credentials c
     JOIN auth.service_accounts sa ON sa.id = c.service_account_id
-    WHERE c.kind = 'app_key' AND c.id = ${params.keyId}::uuid AND c.status = 'active'
-      AND (c.expires_at IS NULL OR c.expires_at > now()) AND sa.status = 'active'
+    WHERE c.kind = 'app_key' AND c.id = ${params.keyId}::uuid
       AND sa.kind = 'resource_bound' AND sa.app_id = ${params.appId} AND sa.resource_type = 'cloud.app' AND sa.resource_id = ${params.appId}
   `;
-  return row ? map(row) : null;
+  return row ? { ...map(row), connectionsAllowed: row.connections_allowed, oauthIssueAllowed: row.oauth_issue_allowed } : null;
+};
+
+/** Bootstrap and signed workload requests must query this directly; no cache. */
+export const getActiveAppKey = async (params: { appId: string; keyId: string }, db: SQL = sql) => {
+  const key = await getStoredAppKey(params, db);
+  return key?.status === "active" && key.accountStatus === "active" ? key : null;
 };
 
 /** Call only after successful authentication; a late touch cannot revive a key. */

package/src/services/approvals/content.ts

@@ -1,6 +1,6 @@
-import { sql } from "bun";
 import { parseStoredReviewContent } from "../../capabilities/review-storage";
 import { CAPABILITY_MAX_REVIEW_CONTENT_BYTES } from "../../contracts/capabilities";
+import { sql } from "../../runtime/clients";
 
 // Start with this person's indexed pending rows; a Studio page alone cannot continue a chat.
 export const openRequests = (approverUserId: string, id?: string) => sql`SELECT r.* FROM approvals.requests r

package/src/services/approvals/index.ts

@@ -1,9 +1,10 @@
-import { type SQL, sql } from "bun";
+import type { SQL } from "bun";
 import { capabilityRequestHash } from "../../capabilities/claims";
 import { restoreReviewSnapshot, serializeReviewSnapshot } from "../../capabilities/review-storage";
 import { APPROVAL_ACP_CLIENT } from "../../contracts/approvals";
 import type { CapabilityActionReviewData } from "../../contracts/capabilities";
 import { CapabilityActionReviewPresentationSchema } from "../../contracts/capabilities";
+import { sql } from "../../runtime/clients";
 import { isAppSessionActor } from "../../server/actor";
 import type { RequestActor, RequestCredentialKind } from "../../server/middleware/auth";
 import { audit } from "../audit";

package/src/services/approvals/list.ts

@@ -1,10 +1,10 @@
-import { sql } from "bun";
 import { type AiStoredActionReview, storedActionReview } from "../../ai/action-review";
 import { AI_WEBSITE_APPROVAL_TOOL, aiTurnAllowsRememberedApprovals } from "../../ai/approvals";
 import type { AiTurnRunConfig } from "../../ai/types";
 import type { RuntimeAppMeta } from "../../contracts/app";
 import { APPROVALS_PAGE_SIZE, type ApprovalCounts, type PendingApproval } from "../../contracts/approvals";
 import { type CapabilityActionPolicy, CapabilityActionReviewPresentationSchema } from "../../contracts/capabilities";
+import { sql } from "../../runtime/clients";
 import type { ApprovalAssurance } from ".";
 import { compactApprovalDetailsSql, openRequests } from "./content";
 import { decodeApprovalCursor, encodeApprovalCursor } from "./cursor";

package/src/services/approvals/migrate.ts

@@ -1,4 +1,4 @@
-import { sql } from "bun";
+import { sql } from "../../runtime/clients";
 
 export const migrateApprovals = async (): Promise<void> => {
   await sql`CREATE SCHEMA IF NOT EXISTS approvals`.simple();

package/src/services/audit/index.ts

@@ -1,5 +1,6 @@
-import { type SQL, sql } from "bun";
+import type { SQL } from "bun";
 import type { UserProvider } from "../../contracts/shared";
+import { sql } from "../../runtime/clients";
 import { err, fail, type PageParams, type Paginated, paginate, type Result, type ServiceError } from "../../server/services";
 import { logger } from "../logging";
 import { escapeLikePattern, parsePgJsonRecord, toPgTextArray } from "../postgres";

package/src/services/auth-flows/ipa.ts

@@ -1,5 +1,5 @@
-import { sql } from "bun";
 import type { User } from "../../contracts/shared";
+import { sql } from "../../runtime/clients";
 import { isAccountCategoryAllowed } from "../account-category-policy";
 import { accounts } from "../accounts";
 import { logger } from "../logging";

package/src/services/auth-flows/magic-link.ts

@@ -1,6 +1,6 @@
-import { redis, sql } from "bun";
 import { accountCategory } from "../../contracts/account-categories";
 import type { User } from "../../contracts/shared";
+import { redis, sql } from "../../runtime/clients";
 import { createAuthLoginUrl } from "../../shared/redirect";
 import { isAccountCategoryAllowed } from "../account-category-policy";
 import { accounts } from "../accounts";

package/src/services/auth-flows/password-reset.ts

@@ -1,5 +1,5 @@
-import { redis, sql } from "bun";
 import type { User } from "../../contracts/shared";
+import { redis, sql } from "../../runtime/clients";
 import { createAuthPasswordResetUrl } from "../../shared/redirect";
 import { isAccountCategoryAllowed } from "../account-category-policy";
 import { getFreeIpaConfig } from "../freeipa-config";

package/src/services/auth-flows/proxy-return.ts

@@ -1,4 +1,4 @@
-import { redis } from "bun";
+import { redis } from "../../runtime/clients";
 
 const KEY_PREFIX = "auth:proxy-return:";
 const DEFAULT_TTL_SECONDS = 300;

package/src/services/downstream-budget.ts

@@ -1,4 +1,4 @@
-import { env } from "../config/env";
+import { connections } from "../runtime/connections";
 import { logger } from "./logging";
 import { requestCacheRedis } from "./request-cache-redis";
 
@@ -31,7 +31,7 @@ export const createDownstreamBudget = (options: { client?: () => Promise<Client>
   async acquire(input: { downstream: Downstream; timeoutMs: number; signal: AbortSignal }): Promise<() => void> {
     input.signal.throwIfAborted();
     if (!Number.isFinite(input.timeoutMs) || input.timeoutMs <= 0) throw new RangeError("Downstream timeout must be positive and finite");
-    const namespace = options.namespace?.() ?? env.SYNC_NAMESPACE;
+    const namespace = options.namespace?.() ?? connections().nats.namespace;
     if (!namespace.trim()) throw new Error("SYNC_NAMESPACE is required for shared downstream budgets");
     const key = `cloud:downstream:{${namespace}}:${input.downstream}`;
     const token = crypto.randomUUID();

package/src/services/geo/admin.ts

@@ -1,4 +1,4 @@
-import { type SQL, sql } from "bun";
+import type { SQL } from "bun";
 import { HTTPException } from "hono/http-exception";
 import {
   GEO_USAGE_GROUPS,
@@ -12,6 +12,7 @@ import {
   geoKeyProblem,
   validateGeoBudget,
 } from "../../contracts/geo-admin";
+import { sql } from "../../runtime/clients";
 import { audit } from "../audit";
 import { toPgTextArray } from "../postgres";
 import * as settings from "../settings";
@@ -83,7 +84,7 @@ export const verifyGeoapifyKey =
   };
 
 export const createGeoAdmin = (options: { db?: SQL; verify?: Verify; now?: () => Date } = {}) => {
-  const db = options.db ?? sql;
+  const db = () => options.db ?? sql;
   const verify = options.verify ?? verifyGeoapifyKey();
   const now = options.now ?? (() => new Date());
 
@@ -92,7 +93,7 @@ export const createGeoAdmin = (options: { db?: SQL; verify?: Verify; now?: () =>
    * carries that transaction's exact timestamp, and so does every row that event wrote.
    */
   const changedBy = async (action: string, keys: readonly string[]): Promise<GeoAdminPerson | null> => {
-    const [row] = await db<{ actor_user_id: string; name: string | null }[]>`
+    const [row] = await db()<{ actor_user_id: string; name: string | null }[]>`
       SELECT e.actor_user_id, COALESCE(NULLIF(u.display_name, ''), u.uid) AS name
       FROM audit.events e LEFT JOIN auth.users u ON u.id = e.actor_user_id
       WHERE e.action = ${action} AND e.actor_user_id IS NOT NULL
@@ -111,7 +112,7 @@ export const createGeoAdmin = (options: { db?: SQL; verify?: Verify; now?: () =>
     const [config, states, rows, keyBy, budgetBy] = await Promise.all([
       readGeoConfig(),
       settings.readStates([KEY, ...BUDGET_KEYS]),
-      db<{ key: string; updated_at: Date }[]>`
+      db()<{ key: string; updated_at: Date }[]>`
         SELECT key, updated_at FROM settings.entries WHERE key = ANY(${toPgTextArray([KEY, ...BUDGET_KEYS])}::text[])`,
       changedBy(KEY_ACTION, [KEY]),
       changedBy(BUDGET_ACTION, BUDGET_KEYS),
@@ -147,15 +148,15 @@ export const createGeoAdmin = (options: { db?: SQL; verify?: Verify; now?: () =>
     const periods = geoPeriods(now(), config.timezone);
     const plan = config.plan === "custom" ? { dailyCredits: config.customDailyCredits } : GEO_PLANS[config.plan];
     const [[month], [today], shares, [overruns]] = await Promise.all([
-      db<
+      db()<
         { used: number }[]
       >`SELECT used::float8 AS used FROM geo.usage WHERE scope = 'cloud' AND subject = '*' AND period = ${periods.cloud.period}`,
-      db<{ used: number; at_limit: number }[]>`
-        SELECT COALESCE(sum(used), 0)::float8 AS used, count(*) FILTER (WHERE used >= ${config.personDailyCredits * 1000})::int AS at_limit
+      db()<{ used: number; at_limit: number }[]>`
+        SELECT COALESCE(sum(used), 0)::float8 AS used, count(*) FILTER (WHERE used >= ${config.personDailyCredits * 1000} AND subject NOT LIKE 'app:%')::int AS at_limit
         FROM geo.usage WHERE scope = 'person' AND period = ${periods.person.period}`,
-      db<{ function_group: string; used: number }[]>`
+      db()<{ function_group: string; used: number }[]>`
         SELECT function_group, used::float8 AS used FROM geo.shares WHERE scope = 'cloud' AND subject = '*' AND period = ${periods.cloud.period}`,
-      db<{ count: number }[]>`SELECT count(*)::int AS count FROM audit.events
+      db()<{ count: number }[]>`SELECT count(*)::int AS count FROM audit.events
         WHERE action = 'core.geo.route_cost_overrun' AND metadata->>'period' = ${periods.cloud.period}`,
     ]);
     return {
@@ -193,7 +194,7 @@ export const createGeoAdmin = (options: { db?: SQL; verify?: Verify; now?: () =>
       await verify(apiKey, signal);
       signal?.throwIfAborted();
       const before = (await settings.readStates([KEY])).get(KEY)?.stored ?? "none";
-      await db.begin(async (tx) => {
+      await db().begin(async (tx) => {
         // The person replaces whatever is stored, including a value this installation cannot read.
         await settings.set(KEY, apiKey, tx, { replaceUnreadable: true });
         await audit.record(
@@ -206,7 +207,7 @@ export const createGeoAdmin = (options: { db?: SQL; verify?: Verify; now?: () =>
     },
     async removeKey(actor: Actor): Promise<GeoAdminStatus> {
       requireAdmin(actor);
-      await db.begin(async (tx) => {
+      await db().begin(async (tx) => {
         const [row] = await tx<{ key: string }[]>`DELETE FROM settings.entries WHERE key = ${KEY} RETURNING key`;
         if (row) await audit.record({ action: "core.geo.key_removed", outcome: "allowed", actor: auditActor(actor) }, tx);
       });
@@ -230,7 +231,7 @@ export const createGeoAdmin = (options: { db?: SQL; verify?: Verify; now?: () =>
       // resets their unreadable values to the defaults instead of leaving geo off behind a field nobody sees.
       const inactive = BUDGET_FIELDS.flatMap(([, name]) => (name in updates ? [] : [name]));
       const resets: string[] = [];
-      await db.begin(async (tx) => {
+      await db().begin(async (tx) => {
         // Same lock and final-pair rule as every other writer of these settings.
         await assertGeoBudgetPair(tx, updates, []);
         // Saving the form is the explicit replacement of a value this installation cannot read.

package/src/services/geo/identity.ts

@@ -0,0 +1,46 @@
+import type { AppPwaActor } from "../../app-pwa/contracts";
+import type { AccessSubject, CapabilityAppExecutionContext, RequestActor } from "../../contracts";
+import { GeoError } from "./errors";
+
+export type GeoContext = {
+  actor?: RequestActor | CapabilityAppExecutionContext["actor"];
+  accessSubject?: AccessSubject | { type: "none" };
+  locale?: string;
+  signal?: AbortSignal;
+  requestId?: string;
+};
+export type GeoBudgetSubject = AccessSubject | { type: "app"; appId: string };
+export type AppPwaGeoContext = { actor: AppPwaActor; locale?: string; signal?: AbortSignal; requestId?: string };
+export type GeoCallContext = GeoContext | AppPwaGeoContext;
+export const geoIdentity = (
+  context: GeoContext,
+): {
+  actor: RequestActor | CapabilityAppExecutionContext["actor"];
+  accessSubject: GeoBudgetSubject;
+} => {
+  const { actor, accessSubject } = context;
+  if (actor?.kind === "app" && actor.keyId && accessSubject?.type === "none")
+    return { actor, accessSubject: { type: "app", appId: actor.appId } };
+  if (
+    !actor ||
+    actor.kind === "app" ||
+    !accessSubject ||
+    accessSubject.type === "none" ||
+    !(actor.kind === "user" ? actor.user?.id : actor.serviceAccount?.id) ||
+    !(accessSubject.type === "user" ? accessSubject.userId : accessSubject.serviceAccountId)
+  )
+    throw new GeoError("GEO_FORBIDDEN");
+  return { actor, accessSubject };
+};
+export const geoCallIdentity = (
+  context: GeoCallContext,
+): {
+  actor: RequestActor | CapabilityAppExecutionContext["actor"] | AppPwaActor;
+  accessSubject: GeoBudgetSubject;
+} => {
+  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 });
+};