@k2b/cloud 0.48.0 → 0.50.0

package/src/services/app-bootstrap.ts

@@ -1,6 +1,6 @@
-import { type SQL, sql } from "bun";
+import type { SQL } from "bun";
 import { decodeJwt, decodeProtectedHeader, type JWTPayload, jwtVerify } from "jose";
-import { importAppPublicKey } from "../app-key";
+import { importAppPublicKey, validateAppKeyAppId } from "../app-key";
 import {
   BOOTSTRAP_PATH,
   BOOTSTRAP_PROOF_BYTES,
@@ -8,9 +8,11 @@ import {
   BOOTSTRAP_REPLAY_RETENTION_SECONDS,
   BOOTSTRAP_TYPE,
   type BootstrapIdentity,
+  BootstrapIdentitySchema,
   bootstrapBodyDigest,
 } from "../runtime/bootstrap-protocol";
-import { getActiveAppKey, getInstallationId } from "./app-keys";
+import { sql } from "../runtime/clients";
+import { getActiveAppKey, getInstallationId, getStoredAppKey, type LastRejectedStart } from "./app-keys";
 import { get } from "./settings";
 
 export class BootstrapProofError extends Error {
@@ -19,8 +21,34 @@ export class BootstrapProofError extends Error {
     this.name = "BootstrapProofError";
   }
 }
+/** Evidence attached only after signature and every request claim have been verified. */
+export class RejectedBootstrapStart extends BootstrapProofError {
+  constructor(
+    readonly identity: BootstrapIdentity,
+    readonly jti: string,
+    readonly reason: LastRejectedStart["reason"],
+  ) {
+    super(reason === "connections_not_permitted" ? reason : "invalid_proof");
+  }
+}
 const invalid = () => new BootstrapProofError("invalid_proof");
 
+/** A refused proof is never consumed. Already-consumed proofs cannot change administrator state. */
+export const recordRejectedBootstrapStart = async (rejection: RejectedBootstrapStart, db: SQL = sql): Promise<void> => {
+  const { identity, jti, reason } = rejection;
+  await db`
+    INSERT INTO auth.app_start_rejections (app_id, rejected_at, reason, key_id)
+    SELECT ${identity.appId}, clock_timestamp(), ${reason}, ${identity.keyId}::uuid
+    WHERE NOT EXISTS (SELECT 1 FROM auth.app_proof_replays WHERE key_id = ${identity.keyId}::uuid AND jti = ${jti})
+    ON CONFLICT (app_id) DO UPDATE
+      SET rejected_at = EXCLUDED.rejected_at, reason = EXCLUDED.reason, key_id = EXCLUDED.key_id
+  `;
+};
+
+export const clearRejectedBootstrapStart = async (appId: string, db: SQL = sql): Promise<void> => {
+  await db`DELETE FROM auth.app_start_rejections WHERE app_id = ${appId}`;
+};
+
 /** Shared Postgres uniqueness rejects a proof used concurrently on different Core replicas. */
 export const consumeBootstrapProof = async (keyId: string, jti: string, exp: number, db: SQL = sql): Promise<boolean> => {
   const rows = await db`
@@ -72,14 +100,10 @@ export const cleanupBootstrapProofs = async (
   return { deleted, remaining: backlog?.count ?? 0 };
 };
 
-/** No caches: every HTTP transmission rechecks revocation, expiry and account state in Postgres. */
-export const authenticateBootstrap = async (
-  proof: string,
-  request: { method: string; path: string; body: Uint8Array<ArrayBuffer> },
-  db: SQL = sql,
-  now = Date.now(),
-): Promise<{ identity: BootstrapIdentity; jti: string; exp: number }> => {
-  if (Buffer.byteLength(proof) > BOOTSTRAP_PROOF_BYTES) throw invalid();
+/** Reject malformed or expired envelopes before allocating or reading a signed request body. Not authentication. */
+export const inspectAppProof = (proof: string, now = Date.now()): { appId: string; keyId: string } => {
+  if (Buffer.byteLength(proof) > BOOTSTRAP_PROOF_BYTES || !/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]{86}$/.test(proof))
+    throw invalid();
   let appId: string;
   let keyId: string;
   try {
@@ -87,14 +111,47 @@ export const authenticateBootstrap = async (
     const claims = decodeJwt(proof);
     if (header.alg !== "EdDSA" || header.typ !== BOOTSTRAP_TYPE || typeof header.kid !== "string" || typeof claims.iss !== "string")
       throw invalid();
+    validateAppKeyAppId(claims.iss);
+    if (!BootstrapIdentitySchema.shape.keyId.safeParse(header.kid).success) throw invalid();
+    const seconds = Math.floor(now / 1000);
+    if (
+      !Number.isSafeInteger(claims.iat) ||
+      !Number.isSafeInteger(claims.exp) ||
+      claims.iat! > seconds + 2 ||
+      claims.exp! <= seconds ||
+      claims.exp! <= claims.iat! ||
+      claims.exp! - claims.iat! > BOOTSTRAP_PROOF_SECONDS
+    )
+      throw invalid();
     appId = claims.iss;
     keyId = header.kid;
   } catch {
     throw invalid();
   }
+  return { appId, keyId };
+};
+
+/** No caches: every HTTP transmission rechecks revocation, expiry and account state in Postgres. */
+export const authenticateAppProof = async (
+  proof: string,
+  request: { method: string; path: string; body: Uint8Array<ArrayBuffer> },
+  db: SQL = sql,
+  now = Date.now(),
+): Promise<{ identity: BootstrapIdentity; key: NonNullable<Awaited<ReturnType<typeof getActiveAppKey>>>; jti: string; exp: number }> => {
+  const { appId, keyId } = inspectAppProof(proof, now);
   // Only validated IDs reach SQL, and the app identity must own this active credential.
   const key = await getActiveAppKey({ appId, keyId }, db);
   if (!key) throw invalid();
+  return verifyAppProof(proof, request, key, db, now);
+};
+
+const verifyAppProof = async (
+  proof: string,
+  request: { method: string; path: string; body: Uint8Array<ArrayBuffer> },
+  key: NonNullable<Awaited<ReturnType<typeof getStoredAppKey>>>,
+  db: SQL,
+  now: number,
+) => {
   let claims: JWTPayload;
   try {
     const verified = await jwtVerify(proof, await importAppPublicKey(key.publicKey), {
@@ -107,19 +164,11 @@ export const authenticateBootstrap = async (
   } catch {
     throw invalid();
   }
-  const seconds = Math.floor(now / 1000);
   if (
-    !Number.isSafeInteger(claims.iat) ||
-    !Number.isSafeInteger(claims.exp) ||
-    claims.iat! > seconds + 2 ||
-    claims.exp! <= claims.iat! ||
-    claims.exp! - claims.iat! > BOOTSTRAP_PROOF_SECONDS ||
     typeof claims.jti !== "string" ||
     claims.jti.length === 0 ||
     claims.jti.length > 64 ||
     claims.jti.includes("\0") ||
-    request.method !== "POST" ||
-    request.path !== BOOTSTRAP_PATH ||
     claims.htm !== request.method ||
     claims.htu !== request.path ||
     claims.bdh !== (await bootstrapBodyDigest(request.body))
@@ -128,7 +177,41 @@ export const authenticateBootstrap = async (
   if (claims.iss !== key.appId || claims.sub !== key.appId) throw new BootstrapProofError("wrong_app");
   const installationId = await getInstallationId(db);
   if (claims.aud !== `cloud-core:${installationId}`) throw new BootstrapProofError("wrong_installation");
-  if (!key.connectionsAllowed) throw new BootstrapProofError("connections_not_permitted");
   // Admission must succeed before the route atomically consumes this verified nonce.
-  return { identity: { installationId, appId, keyId }, jti: claims.jti, exp: claims.exp! };
+  return { identity: { installationId, appId: key.appId, keyId: key.keyId }, key, jti: claims.jti, exp: claims.exp! };
+};
+
+/** Only connection delivery requires connections_allowed; runners can still sign requests. */
+export const authenticateBootstrap = async (
+  proof: string,
+  request: { method: string; path: string; body: Uint8Array<ArrayBuffer> },
+  db: SQL = sql,
+  now = Date.now(),
+): Promise<{ identity: BootstrapIdentity; jti: string; exp: number }> => {
+  const ids = inspectAppProof(proof, now);
+  const key = await getStoredAppKey(ids, db);
+  if (!key) throw invalid();
+  const inactive = key.status !== "active" || key.accountStatus !== "active";
+  let verified: Awaited<ReturnType<typeof verifyAppProof>>;
+  try {
+    verified = await verifyAppProof(proof, request, key, db, now);
+  } catch (error) {
+    // Inactive keys have always returned invalid_proof, regardless of their claims.
+    if (inactive) throw invalid();
+    throw error;
+  }
+  if (request.method !== "POST" || request.path !== BOOTSTRAP_PATH) throw invalid();
+  const reason =
+    key.status === "revoked"
+      ? "revoked"
+      : key.status === "expired"
+        ? "expired"
+        : key.accountStatus === "disabled"
+          ? "disabled"
+          : !key.connectionsAllowed
+            ? "connections_not_permitted"
+            : null;
+  if (reason) throw new RejectedBootstrapStart(verified.identity, verified.jti, reason);
+  const { identity, jti, exp } = verified;
+  return { identity, jti, exp };
 };

package/src/services/app-details.ts

@@ -1,4 +1,4 @@
-import { type SQL, sql } from "bun";
+import type { SQL } from "bun";
 import { resolveCapabilityManifestPresentation } from "../_internal/capabilities";
 import { getApp, listCapabilities } from "../_internal/registry";
 import {
@@ -9,6 +9,7 @@ import {
 } from "../contracts/app-details";
 import { type NotificationDefinitionPresentationCatalog, resolveNotificationDefinitionPresentation } from "../contracts/notification-types";
 import type { AppRegistryEntry, CapabilityRegistryEntry } from "../contracts/registry";
+import { sql } from "../runtime/clients";
 import type { RequestAuthority } from "../server/middleware/auth";
 import { resolveAppIdentityPresentation } from "../shared/app-presentation";
 import { AppAccessManagementError, appAccessGrantCounts, canRepairAppAccess } from "./app-access-management";
@@ -48,8 +49,8 @@ type Dependencies = {
 
 /** Core-owned administration read shared by SSR and HTTP; app access is not administrator authority. */
 export function createAppDetailsService(dependencies: Dependencies = {}) {
-  const db = dependencies.db ?? sql;
   return async (appId: string, options: { authority: RequestAuthority; locale?: string }): Promise<AppDetails | null> => {
+    const db = dependencies.db ?? sql;
     if (!canRepairAppAccess(options.authority))
       throw new AppAccessManagementError("FORBIDDEN", "Cloud administration authority is required.");
     const locale = options.locale ?? "en";

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

@@ -15,8 +15,8 @@ const Metadata = z.object({
   version: Envelope.shape.version.catch(1),
 });
 
-export function createEventAcceptance(db: SQL, reconcile: () => Promise<void>) {
-  const markSeen = async (sequence: number, tx: SQL = db) => {
+export function createEventAcceptance(db: () => SQL, reconcile: () => Promise<void>) {
+  const markSeen = async (sequence: number, tx: SQL = db()) => {
     // Keep holes until replay or the periodic DLQ/retention check accounts for them.
     // Advancing the high watermark alone would hide eviction before the next tick.
     await tx`
@@ -36,7 +36,7 @@ export function createEventAcceptance(db: SQL, reconcile: () => Promise<void>) {
       return;
     }
     const { id, type, source, version } = metadata.data;
-    await db.begin(async (tx) => {
+    await db().begin(async (tx) => {
       // Invalid or oversized input is represented by metadata only, never a second failing payload insert.
       await tx`
         INSERT INTO events.app_events(id, type, version, source, subject_key, envelope, state, code)
@@ -61,7 +61,7 @@ export function createEventAcceptance(db: SQL, reconcile: () => Promise<void>) {
     } catch {
       log.warn("Declaration refresh failed; accepting against persisted declarations", { sequence });
     }
-    const [declaration] = await db<StoredDeclaration[]>`
+    const [declaration] = await db()<StoredDeclaration[]>`
       SELECT * FROM events.app_declarations
       WHERE app_id = ${envelope.source} AND type = ${envelope.type} AND version = ${envelope.version}
     `;
@@ -85,7 +85,7 @@ export function createEventAcceptance(db: SQL, reconcile: () => Promise<void>) {
     }
     const subjectKey = `${envelope.subject.type}:${envelope.subject.id}`;
     try {
-      await db.begin(async (tx) => {
+      await db().begin(async (tx) => {
         const inserted = await tx`
           INSERT INTO events.app_events(id, type, version, source, subject_key, envelope, state, code)
           VALUES (${envelope.id}::uuid, ${envelope.type}, ${envelope.version}, ${envelope.source}, ${subjectKey},

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,11 +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 (
+/** 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 }) | null> => {
+): Promise<(AppKeyMetadata & { connectionsAllowed: boolean; oauthIssueAllowed: boolean }) | null> => {
   try {
     validateAppKeyAppId(params.appId);
   } catch {
@@ -283,11 +309,16 @@ export const getActiveAppKey = async (
   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), connectionsAllowed: row.connections_allowed } : 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";