@k2b/cloud 0.43.0 → 0.44.0

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

@@ -10,47 +10,35 @@ 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 { listAiCredentialProfileIds, pruneAiCredentials, setAiCredential, splitAiProfileCredentials } from "../ai/credentials";
 import { enrichDirtyAiConversations } from "../ai/enrich";
-import {
-  type AiModelAccessChange,
-  AiModelAccessConflict,
-  AiModelAccessInvalid,
-  aiModelAccess,
-  splitAiModelAccess,
-} from "../ai/model-access";
-import { listAiRequestHeaderNames, planAiProfileRequestHeaders, storeAiRequestHeaderPlan } from "../ai/request-headers";
-import {
-  parseAiModelProfiles,
-  planAiProfileCredentials,
-  prepareAiModelProfileImages,
-  validateAiSettingsConfiguration,
-} from "../ai/settings";
-import { type AiSettingsIssueWithMessage, aiSettingsNotSavedMessage, describeAiSettingsIssues } from "../ai/settings-messages";
 import { type AuthContext, auth, getLocale, jsonResponse, requiresAdmin, v } from "../server";
-import { settingsDeleteLegacyKeys, settingsListLegacyKeys } from "../services";
+import { settingsDeleteLegacyKeys, settingsListLegacyKeys, settingsService } from "../services";
 import { readAccountCategoryPolicy } from "../services/account-category-policy";
 import { audit } from "../services/audit";
+import { ConfigConflict } from "../services/config-conflict";
 import { validateFreeIpaCaCert } from "../services/freeipa-config";
 import { ImageMetadataError } from "../services/image-metadata";
 import { testFreeIpaConnection } from "../services/ipa/connection";
 import { GotenbergRenderError, testGotenberg } from "../services/pdf";
 import * as settings from "../services/settings";
 import { SETTINGS_MAP, validateSettingValue } from "../services/settings/defaults";
-
 import { assertGeoBudgetPair, GeoBudgetSettingError } from "../services/settings/geo-budget";
 import { invalidateSettingsCacheForAdmin } from "../services/settings/store";
+import { assertSettingVersions } from "../services/settings/versions";
 
+const BulkUpdatesSchema = z
+  .object({
+    updates: z.record(z.string(), z.unknown()).optional().default({}),
+    resets: z.array(z.string()).optional().default([]),
+    replaceUnreadable: z.array(z.string()).optional().default([]),
+    expectedUpdatedAt: z.record(z.string(), z.string().nullable()).optional().default({}),
+  })
+  .strict();
 const BulkSaveSchema = z.union([
-  z
-    .object({
-      updates: z.record(z.string(), z.unknown()).optional().default({}),
-      resets: z.array(z.string()).optional().default([]),
-      replaceUnreadable: z.array(z.string()).optional().default([]),
-    })
-    .strict(),
-  z.record(z.string(), z.unknown()).transform((updates) => ({ updates, resets: [] as string[], replaceUnreadable: [] as string[] })),
+  BulkUpdatesSchema,
+  z.record(z.string(), z.unknown()).transform((updates) => BulkUpdatesSchema.parse({ updates })),
 ]);
 const LEGAL_DOCUMENTS = [
   { kind: "terms", path: "/legal/terms" },
@@ -72,150 +60,8 @@ const isKnownSetting = (key: string): boolean => SETTINGS_MAP.has(key);
 const GEO_KEY = "geo.api_key";
 const GEO_KEY_DEDICATED = "Set or remove the Geoapify key with /api/admin/core/geo/key, which verifies it first.";
 
-const AI_PROFILES_KEY = "ai.model_profiles_json";
-const AI_ENABLED_KEY = "ai.enabled";
-const AI_DEFAULT_MODEL_KEY = "ai.default_model_id";
-const AI_BACKGROUND_MODEL_KEY = "ai.background_model_id";
-const AI_AUDIO_MODEL_KEY = "ai.audio_model_id";
-const AI_VISION_MODEL_KEY = "ai.vision_model_id";
-const AI_WORKFLOW_MODEL_KEY = "ai.workflow_model_id";
-const AI_CONFIGURATION_KEYS = new Set([
-  AI_ENABLED_KEY,
-  AI_DEFAULT_MODEL_KEY,
-  AI_BACKGROUND_MODEL_KEY,
-  AI_VISION_MODEL_KEY,
-  AI_AUDIO_MODEL_KEY,
-  AI_WORKFLOW_MODEL_KEY,
-  AI_PROFILES_KEY,
-]);
 const INTEGER_FREEIPA_SETTINGS = new Set(["freeipa.sync_guard.max_user_changes", "freeipa.sync_guard.max_group_deletions"]);
 
-/**
- * Move provider keys out of the model-profiles value before it is stored.
- *
- * The admin form posts profiles as one value, and a newly typed key rides along
- * on its profile. Keys must not land in the setting — it is a `text` setting and
- * would be handed back to the browser in full — so they go to
- * `ai.model_credentials` here and are stripped from what gets saved. A profile
- * whose key field was left empty keeps whatever is already stored.
- *
- * Doing this in the route rather than the settings service keeps the generic
- * store free of AI knowledge, and keeps the admin page at a single save request.
- */
-const storeAiCredentials = async (
-  split: NonNullable<ReturnType<typeof splitAiProfileCredentials>>,
-  keepCredentialProfileIds: readonly string[],
-  db: typeof sql,
-): Promise<void> => {
-  for (const { profileId, secret } of split.credentials) await setAiCredential(profileId, secret, db);
-  await pruneAiCredentials(keepCredentialProfileIds, db);
-};
-
-type AiSettingsMutationPlan = {
-  errors: FieldErrors;
-  /** Structured validation issues with stable codes; `errors` carries the same messages keyed by setting. */
-  issues?: AiSettingsIssueWithMessage[];
-  keepCredentialProfileIds?: string[];
-  headerPlan?: ReturnType<typeof planAiProfileRequestHeaders>;
-  modelProfileIds?: string[];
-};
-
-const valueAfterMutation = <T>(key: string, current: T, updates: Record<string, unknown>, resets: readonly string[]): T => {
-  if (key in updates) return updates[key] as T;
-  if (resets.includes(key)) return SETTINGS_MAP.get(key)?.default as T;
-  return current;
-};
-
-const prepareAiSettingsMutation = async (
-  updates: Record<string, unknown>,
-  resets: readonly string[],
-  aiSplit: ReturnType<typeof splitAiProfileCredentials>,
-  locale: string,
-): Promise<AiSettingsMutationPlan> => {
-  const keys = [...Object.keys(updates), ...resets];
-  if (!keys.some((key) => AI_CONFIGURATION_KEYS.has(key))) return { errors: {} };
-
-  const [
-    currentEnabled,
-    currentDefaultModelId,
-    currentBackgroundModelId,
-    currentVisionModelId,
-    currentAudioModelId,
-    currentWorkflowModelId,
-    currentProfilesJson,
-  ] = await Promise.all([
-    settings.get<boolean>(AI_ENABLED_KEY),
-    settings.get<string>(AI_DEFAULT_MODEL_KEY),
-    settings.get<string>(AI_BACKGROUND_MODEL_KEY),
-    settings.get<string>(AI_VISION_MODEL_KEY),
-    settings.get<string>(AI_AUDIO_MODEL_KEY),
-    settings.get<string>(AI_WORKFLOW_MODEL_KEY),
-    settings.get<string>(AI_PROFILES_KEY),
-  ]);
-
-  const currentParsed = parseAiModelProfiles(currentProfilesJson ?? "[]");
-  const profilesUpdated = AI_PROFILES_KEY in updates;
-  const profilesReset = resets.includes(AI_PROFILES_KEY);
-  const nextParsed: ReturnType<typeof parseAiModelProfiles> = profilesUpdated
-    ? parseAiModelProfiles(aiSplit?.profilesJson ?? "[]")
-    : profilesReset
-      ? { profiles: [] }
-      : currentParsed;
-  if (nextParsed.error) return { errors: nextParsed.error.fields ?? { [AI_PROFILES_KEY]: nextParsed.error.message } };
-
-  const nextEnabled = Boolean(valueAfterMutation(AI_ENABLED_KEY, currentEnabled, updates, resets));
-  const existingCredentialProfileIds = profilesUpdated || (!profilesReset && nextEnabled) ? await listAiCredentialProfileIds() : [];
-
-  let keepCredentialProfileIds: string[] | undefined;
-  if (profilesUpdated || profilesReset) {
-    const credentialPlan = planAiProfileCredentials({
-      currentProfiles: currentParsed.profiles,
-      nextProfiles: nextParsed.profiles,
-      existingCredentialProfileIds,
-      submittedCredentialProfileIds: aiSplit?.credentials.map(({ profileId }) => profileId) ?? [],
-    });
-    if (credentialPlan.unsupportedCredentialProfileId) {
-      return {
-        errors: {
-          [AI_PROFILES_KEY]: `Profile "${credentialPlan.unsupportedCredentialProfileId}" does not support provider credentials.`,
-        },
-      };
-    }
-    keepCredentialProfileIds = credentialPlan.keepCredentialProfileIds;
-  }
-
-  const headerPlan =
-    profilesUpdated || profilesReset
-      ? planAiProfileRequestHeaders({
-          currentProfiles: currentParsed.profiles,
-          nextProfiles: nextParsed.profiles,
-          existingNames: profilesUpdated ? await listAiRequestHeaderNames() : {},
-          submitted: aiSplit?.requestHeaders ?? [],
-        })
-      : undefined;
-  if (headerPlan?.error) return { errors: { [AI_PROFILES_KEY]: headerPlan.error } };
-
-  const issues = validateAiSettingsConfiguration({
-    enabled: nextEnabled,
-    defaultModelId: String(valueAfterMutation(AI_DEFAULT_MODEL_KEY, currentDefaultModelId ?? "", updates, resets)),
-    backgroundModelId: String(valueAfterMutation(AI_BACKGROUND_MODEL_KEY, currentBackgroundModelId ?? "", updates, resets)),
-    audioModelId: String(valueAfterMutation(AI_AUDIO_MODEL_KEY, currentAudioModelId ?? "", updates, resets)),
-    visionModelId: String(valueAfterMutation(AI_VISION_MODEL_KEY, currentVisionModelId ?? "", updates, resets)),
-    workflowModelId: String(valueAfterMutation(AI_WORKFLOW_MODEL_KEY, currentWorkflowModelId ?? "", updates, resets)),
-    profiles: nextParsed.profiles,
-    credentialProfileIds: keepCredentialProfileIds ?? existingCredentialProfileIds,
-  });
-  // Stored profiles come second so a profile that is being removed keeps its label.
-  const described = describeAiSettingsIssues(issues, { locale, profiles: [...nextParsed.profiles, ...currentParsed.profiles] });
-  return {
-    errors: described.errors,
-    issues: described.issues,
-    headerPlan,
-    keepCredentialProfileIds,
-    modelProfileIds: profilesUpdated || profilesReset ? nextParsed.profiles.map((profile) => profile.id) : undefined,
-  };
-};
-
 const invalidateCommittedSettings = async (keys: readonly string[]): Promise<void> => {
   try {
     await settings.invalidateSettingsCache(keys);
@@ -316,6 +162,22 @@ const app = new Hono<AuthContext>()
     );
     return c.json({ items });
   })
+  // The current values and versions of one settings group, so a form can continue after a save without a reload.
+  .get(
+    "/entries",
+    auth.requireRole("admin"),
+    describeRoute({
+      tags: ["Administration"],
+      summary: "Read the settings of one group with their versions",
+      ...requiresAdmin,
+    }),
+    v("query", z.object({ group: z.string().min(1).max(64) })),
+    async (c) => {
+      const result = await settingsService.entry.list({ filter: { group: c.req.valid("query").group }, locale: getLocale(c) });
+      c.header("Cache-Control", "no-store");
+      return c.json({ items: result.items });
+    },
+  )
   .get("/legacy", auth.requireRole("admin"), async (c) => {
     return c.json(await settingsListLegacyKeys(await liveSettingKeys()));
   })
@@ -345,6 +207,33 @@ const app = new Hono<AuthContext>()
       return c.json({ message: "Failed to test Gotenberg PDF rendering" }, 500);
     }
   })
+  .post(
+    "/test-storage",
+    auth.requireRole("admin"),
+    describeRoute({
+      tags: ["Administration"],
+      summary: "Test the saved Garage storage connection",
+      ...requiresAdmin,
+      responses: { 200: jsonResponse(z.object({ ok: z.literal(true) }), "Object written, read and deleted") },
+    }),
+    async (c) => {
+      c.header("Cache-Control", "no-store");
+      try {
+        await testObjectStoreConnection();
+        return c.json({ ok: true as const });
+      } catch (error) {
+        return c.json(
+          {
+            message:
+              error instanceof ObjectStoreConfigurationError || error instanceof ObjectStoreConnectionError
+                ? error.message
+                : "Storage test failed. Check the saved settings, Garage availability and bucket permissions, then retry.",
+          },
+          502,
+        );
+      }
+    },
+  )
   .post("/test-freeipa", auth.requireRole("admin"), async (c) => {
     const result = await testFreeIpaConnection();
     if (result.ok) return c.json({ ok: true });
@@ -368,12 +257,12 @@ const app = new Hono<AuthContext>()
     }),
     v("json", BulkSaveSchema),
     async (c) => {
-      const { updates, resets, replaceUnreadable } = c.req.valid("json");
+      const { updates, resets, replaceUnreadable, expectedUpdatedAt } = c.req.valid("json");
       const replace = new Set(replaceUnreadable);
       const updateKeys = Object.keys(updates);
       const keys = [...updateKeys, ...resets];
 
-      if (keys.length === 0 && replace.size === 0) {
+      if (keys.length === 0 && replace.size === 0 && Object.keys(expectedUpdatedAt).length === 0) {
         return c.body(null, 204);
       }
 
@@ -383,6 +272,9 @@ const app = new Hono<AuthContext>()
           ownership[key] = `Unknown setting "${key}"`;
         }
       }
+      for (const key of Object.keys(expectedUpdatedAt)) {
+        if (!keys.includes(key)) ownership[key] = `Setting "${key}" must be included in updates or resets`;
+      }
       for (const key of replace) {
         if (!Object.hasOwn(updates, key)) ownership[key] = `Setting "${key}" must be included in updates to replace its unreadable value`;
       }
@@ -405,38 +297,7 @@ const app = new Hono<AuthContext>()
         return c.json({ message: settingsNotSavedMessage(getLocale(c)), errors: unreadable, code: "setting_unreadable" }, 409);
       }
 
-      // Strip AI provider keys before anything is validated or written, so the
-      // value that gets checked is the value that gets stored.
-      const aiSplit = AI_PROFILES_KEY in updates ? splitAiProfileCredentials(updates[AI_PROFILES_KEY]) : null;
-      if (AI_PROFILES_KEY in updates && !aiSplit) {
-        // Unsplittable means the keys could not be separated out, and storing the
-        // value as posted would put them back in a setting the browser reads.
-        return c.json({ message: "Invalid values", errors: { [AI_PROFILES_KEY]: "Model profiles must be a JSON array" } }, 400);
-      }
-      let accessChanges: AiModelAccessChange[] = [];
-      if (aiSplit) {
-        try {
-          aiSplit.profilesJson = prepareAiModelProfileImages(aiSplit.profilesJson);
-        } catch (error) {
-          if (error instanceof ImageMetadataError)
-            return c.json({ message: error.message, code: error.code, errors: { [AI_PROFILES_KEY]: error.message } }, 422);
-          throw error;
-        }
-        try {
-          const split = splitAiModelAccess(aiSplit.profilesJson);
-          aiSplit.profilesJson = split.profilesJson;
-          accessChanges = split.changes;
-        } catch {
-          return c.json(
-            {
-              message: "Invalid model permissions",
-              errors: { [AI_PROFILES_KEY]: "Invalid Assistant model permissions. Reload the settings and try again." },
-            },
-            400,
-          );
-        }
-      }
-      const finalValues: Record<string, unknown> = aiSplit ? { ...updates, [AI_PROFILES_KEY]: aiSplit.profilesJson } : updates;
+      const finalValues = updates;
 
       // Validate everything up front. settings.set validates as it writes, so a
       // single bad field used to leave the earlier keys already saved — with the
@@ -461,26 +322,17 @@ const app = new Hono<AuthContext>()
         return c.json({ message: "Invalid values", errors: invalid }, 400);
       }
 
-      let aiPlan: AiSettingsMutationPlan;
-      try {
-        aiPlan = await prepareAiSettingsMutation(validatedValues, resets, aiSplit, getLocale(c));
-      } catch (error) {
-        console.error("[settings] failed to validate the prospective AI configuration", error);
-        return c.json({ message: "Failed to validate AI settings" }, 500);
-      }
-      if (Object.keys(aiPlan.errors).length > 0) {
-        return c.json({ message: aiSettingsNotSavedMessage(getLocale(c)), errors: aiPlan.errors, issues: aiPlan.issues ?? [] }, 400);
-      }
-
       const fieldErrors: FieldErrors = {};
       try {
         // Every settings and AI credential write runs on the transaction's own
         // connection, so a failure rolls the whole save back.
         await sql.begin(async (tx) => {
+          await assertSettingVersions(expectedUpdatedAt, tx);
           await assertGeoBudgetPair(tx, validatedValues, resets);
           for (const [key, value] of Object.entries(validatedValues)) {
             try {
               await settings.set(key, value, tx, { replaceUnreadable: replace.has(key) });
+              await tx`UPDATE settings.entries SET updated_by=${c.get("user").id}::uuid WHERE key=${key}`;
             } catch (error) {
               fieldErrors[key] = `Failed to save ${key}`;
               throw error;
@@ -512,15 +364,6 @@ const app = new Hono<AuthContext>()
               },
               tx,
             );
-          if (aiSplit && aiPlan.keepCredentialProfileIds) {
-            await storeAiCredentials(aiSplit, aiPlan.keepCredentialProfileIds, tx);
-          } else if (aiPlan.keepCredentialProfileIds) {
-            await pruneAiCredentials(aiPlan.keepCredentialProfileIds, tx);
-          }
-          if (aiPlan.headerPlan) await storeAiRequestHeaderPlan(aiPlan.headerPlan, tx);
-          if (aiPlan.modelProfileIds) {
-            await aiModelAccess.syncProfiles(aiPlan.modelProfileIds, accessChanges, tx);
-          }
         });
       } catch (error) {
         if (error instanceof GeoBudgetSettingError) return error.getResponse();
@@ -535,12 +378,11 @@ const app = new Hono<AuthContext>()
           );
         }
         if (error instanceof ImageMetadataError) return c.json({ message: error.message, code: error.code, errors: fieldErrors }, 422);
-        if (error instanceof AiModelAccessConflict || error instanceof AiModelAccessInvalid) {
+        if (error instanceof ConfigConflict)
           return c.json(
-            { message: error.message, errors: { [AI_PROFILES_KEY]: error.message } },
-            error instanceof AiModelAccessConflict ? 409 : 400,
+            { code: error.code, current: error.current, key: error.key, changedBy: error.changedBy, changedAt: error.changedAt },
+            409,
           );
-        }
         console.error("[settings] failed to commit settings update", error);
         return c.json(
           {
@@ -565,17 +407,6 @@ const app = new Hono<AuthContext>()
     }
     if (key === GEO_KEY) return c.json({ message: GEO_KEY_DEDICATED, errors: { [GEO_KEY]: GEO_KEY_DEDICATED } }, 400);
 
-    let aiPlan: AiSettingsMutationPlan;
-    try {
-      aiPlan = await prepareAiSettingsMutation({}, [key], null, getLocale(c));
-    } catch (error) {
-      console.error("[settings] failed to validate the prospective AI configuration", error);
-      return c.json({ message: "Failed to validate AI settings" }, 500);
-    }
-    if (Object.keys(aiPlan.errors).length > 0) {
-      return c.json({ message: aiSettingsNotSavedMessage(getLocale(c)), errors: aiPlan.errors, issues: aiPlan.issues ?? [] }, 400);
-    }
-
     try {
       await sql.begin(async (tx) => {
         await assertGeoBudgetPair(tx, {}, [key]);
@@ -591,13 +422,6 @@ const app = new Hono<AuthContext>()
             },
             tx,
           );
-        if (aiPlan.keepCredentialProfileIds) {
-          await pruneAiCredentials(aiPlan.keepCredentialProfileIds, tx);
-        }
-        if (aiPlan.headerPlan) await storeAiRequestHeaderPlan(aiPlan.headerPlan, tx);
-        if (aiPlan.modelProfileIds) {
-          await aiModelAccess.syncProfiles(aiPlan.modelProfileIds, [], tx);
-        }
       });
     } catch (error) {
       if (error instanceof GeoBudgetSettingError || error instanceof settings.SettingUnreadableError) return error.getResponse();

package/src/api/app-approval.ts

@@ -27,9 +27,10 @@ import {
   type createAppApprovalService,
 } from "../services/app-approval";
 import { type NewBrowserSignInNotifier, readBrowserCookie } from "../services/known-browsers";
-import { SessionAppDeviceInactiveError, SessionEpochChangedError } from "../services/session";
+import { SessionAccountMismatchError, SessionAppDeviceInactiveError, SessionEpochChangedError } from "../services/session";
 import { appNameIn } from "../ssr/runtime";
 import { createDeviceActions } from "./app-approval-actions";
+import { accountMismatchResponse } from "./auth/account-mismatch";
 
 const PairingIdSchema = z.object({ pairingId: z.string().uuid() }).strict();
 const DevicePageSchema = z.object({ after: z.string().uuid().optional() }).strict();
@@ -56,6 +57,7 @@ export const createAppApprovalRoutes = (
     .use("/device", noTransform())
     .use("/device/*", noTransform())
     .onError((error, c) => {
+      if (error instanceof SessionAccountMismatchError) return accountMismatchResponse(c);
       if (error instanceof AppApprovalError) return c.json({ code: error.code, message: error.code }, error.status);
       if (error instanceof HTTPException && error.status < 500) return c.json({ code: "INVALID_REQUEST" }, error.status);
       // Never include SQL, pairing secrets, signature bodies or keys in errors.

package/src/api/app-event-delivery.ts

@@ -0,0 +1,51 @@
+import { Hono } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import { z } from "zod";
+import type { CompiledCapabilities } from "../_internal/capabilities";
+import { AppEventEnvelopeSchema, appEventSubscriptionId } from "../contracts/app-events";
+import { deliverAppEvent } from "../events/app-events";
+import { REQUEST_IDLE_TIMEOUT_SECONDS, setRequestTimeout } from "../server/request-timeout";
+import { verifyAppEventInvocation } from "../services/identity/invocation-token";
+
+const DeliveryInput = z
+  .object({ envelope: AppEventEnvelopeSchema, subscriptionId: z.string().max(400), attempt: z.number().int().min(1).max(8) })
+  .strict();
+export const createAppEventDeliveryRoutes = (compiled: CompiledCapabilities, verify = verifyAppEventInvocation) =>
+  new Hono().use(bodyLimit({ maxSize: 8192 })).post("/deliver", async (c) => {
+    const payload: unknown = await c.req.json().catch(() => null);
+    const parsed = DeliveryInput.safeParse(payload);
+    if (!parsed.success) return c.json({ code: "schema_mismatch" }, 422);
+    const { envelope, subscriptionId, attempt } = parsed.data;
+    const token = c.req.header("authorization")?.match(/^Bearer (\S+)$/i)?.[1];
+    if (!token || !(await verify(token, { appId: compiled.manifest.appId, subscriptionId, eventId: envelope.id, payload })))
+      return c.json({ code: "unauthorized" }, 401);
+    const sub = compiled.subscribes.get(envelope.type);
+    if (
+      !sub ||
+      sub.manifest.version !== envelope.version ||
+      subscriptionId !== appEventSubscriptionId(compiled.manifest.appId, envelope.type, envelope.version)
+    )
+      return c.json({ code: "subscription_removed" }, 410);
+    if (envelope.place) return c.json({ code: "resource_events_unsupported" }, 410);
+    if (!sub.definition.schema.safeParse(envelope.data).success) return c.json({ code: "schema_mismatch" }, 422);
+    const signal = AbortSignal.any([c.req.raw.signal, AbortSignal.timeout(30000)]);
+    let onAbort: () => void = () => {};
+    const aborted = new Promise<never>((_, reject) => {
+      onAbort = () => reject(signal.reason);
+      signal.addEventListener("abort", onAbort, { once: true });
+      if (signal.aborted) onAbort();
+    });
+    setRequestTimeout(c, 40);
+    try {
+      await Promise.race([
+        deliverAppEvent({ compiled, subscriptionId, envelope, context: { subscriptionId, eventId: envelope.id, attempt, signal } }),
+        aborted,
+      ]);
+      return c.json({ done: true });
+    } catch {
+      return c.json({ code: signal.aborted && signal.reason?.name === "TimeoutError" ? "handler_timeout" : "handler_failed" }, 503);
+    } finally {
+      signal.removeEventListener("abort", onAbort);
+      setRequestTimeout(c, REQUEST_IDLE_TIMEOUT_SECONDS);
+    }
+  });

package/src/api/app-events.ts

@@ -0,0 +1,123 @@
+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 { type AuthContext, auth, expectUserBackedActor, getLocale, v } from "../server";
+import { AppAccessManagementError } from "../services/app-access-management";
+import { appDetails } from "../services/app-details";
+import { appEventShape, appEventShapeId, recordedAppEventShape } from "../services/app-event-shapes";
+import { appEventBroker } from "../services/app-events";
+
+const App = z.string().regex(/^[a-z][a-z0-9-]{0,79}$/);
+const Filter = z.object({
+  app: App.optional(),
+  state: z.enum(["pending", "retrying", "done", "failed", "cancelled"]).optional(),
+  eventType: CapabilityQualifiedIdSchema.optional(),
+  offset: z.coerce.number().int().min(0).default(0),
+  limit: z.coerce.number().int().min(1).max(100).default(50),
+});
+export const createAppEventRoutes = (
+  authenticate: MiddlewareHandler<AuthContext> = auth.requireRole("admin"),
+  service = appEventBroker,
+  details = appDetails,
+) =>
+  new Hono<AuthContext>()
+    .use(authenticate)
+    .use(auth.requireOAuthScope("admin"))
+    .get(
+      "/apps/:appId",
+      describeRoute({ tags: ["App events"], summary: "Inspect one application's access, events and notifications" }),
+      v("param", z.object({ appId: App })),
+      async (c) => {
+        try {
+          const result = await details(c.req.valid("param").appId, { authority: auth.getAuthority(c), locale: getLocale(c) });
+          return result ? c.json(AppDetailsSchema.parse(result)) : c.json({ code: "app_not_found" }, 404);
+        } catch (error) {
+          if (error instanceof AppAccessManagementError) return c.json({ code: error.code, message: error.message }, error.status);
+          throw error;
+        }
+      },
+    )
+    .get("/catalog", describeRoute({ tags: ["App events"], summary: "List declared event types and subscribers" }), async (c) =>
+      c.json(await service.catalog(getLocale(c))),
+    )
+    .get(
+      "/subscriptions",
+      describeRoute({ tags: ["App events"], summary: "Inspect declared subscriptions and delivery counts" }),
+      v("query", z.object({ app: App.optional() })),
+      async (c) => c.json(await service.subscriptions(c.req.valid("query").app)),
+    )
+    .get("/deliveries", describeRoute({ tags: ["App events"], summary: "List app event deliveries" }), v("query", Filter), async (c) =>
+      c.json(await service.deliveries(c.req.valid("query"))),
+    )
+    .post(
+      "/deliveries/:id/redeliver",
+      describeRoute({ tags: ["App events"], summary: "Retry one delivery preserving its event ID" }),
+      v("param", z.object({ id: z.uuid() })),
+      async (c) => {
+        const user = expectUserBackedActor(c);
+        const result = await service.redeliver(c.req.valid("param").id, {
+          userId: user.id,
+          uid: user.uid,
+          provider: user.provider,
+          roles: user.roles,
+        });
+        return result ? c.json(result) : c.json({ code: "not_redeliverable" }, 409);
+      },
+    )
+    .post("/status/acknowledge", describeRoute({ tags: ["App events"], summary: "Acknowledge a reconciled retention gap" }), async (c) => {
+      const user = expectUserBackedActor(c);
+      const result = await service.acknowledgeGap({ userId: user.id, uid: user.uid, provider: user.provider, roles: user.roles });
+      return result ? c.json(result) : c.json({ code: "no_gap_detected" }, 409);
+    })
+    .get(
+      "/status",
+      describeRoute({ tags: ["App events"], summary: "Read broker progress, retention gaps and rejected-event metadata" }),
+      async (c) => c.json(await service.status()),
+    )
+    .get(
+      "/record/:eventType",
+      describeRoute({ tags: ["App events"], summary: "Record schema-only JSONL fixtures; no stored event values are returned" }),
+      v("param", z.object({ eventType: CapabilityQualifiedIdSchema })),
+      v("query", z.object({ shapeOnly: z.literal("true"), limit: z.coerce.number().int().min(1).max(100).default(10) })),
+      async (c) => {
+        const { eventType } = c.req.valid("param");
+        const { limit } = c.req.valid("query");
+        const catalog = await service.catalog();
+        const rows = await sql<
+          { version: number; envelope: { data: unknown } }[]
+        >`SELECT version, envelope FROM events.app_events WHERE type=${eventType} AND state='accepted' ORDER BY seq DESC LIMIT ${limit}`;
+        try {
+          const shapes = new Map<string, { version: number; shape: ReturnType<typeof recordedAppEventShape> }>();
+          for (const row of rows) {
+            const shape = recordedAppEventShape(row.envelope.data);
+            shapes.set(JSON.stringify([row.version, shape]), { version: row.version, shape });
+          }
+          const lines = [...shapes.values()].map((row) => {
+            const declaration = catalog.events.find((event) => event.type === eventType && event.version === row.version);
+            if (!declaration) throw new Error("shape_unavailable");
+            return JSON.stringify(
+              AppEventEnvelopeSchema.parse({
+                id: appEventShapeId(eventType, row.version, row.shape),
+                type: eventType,
+                version: row.version,
+                source: eventType.split(".")[0],
+                time: "2000-01-01T00:00:00.000Z",
+                subject: { type: declaration.subject, id: "00000000-0000-4000-8000-000000000001" },
+                ...(declaration.place ? { place: { type: declaration.place, id: "00000000-0000-4000-8000-000000000001" } } : {}),
+                data: appEventShape(declaration.dataSchema, 0, row.shape),
+              }),
+            );
+          });
+          return c.body(lines.length ? lines.join("\n") + "\n" : "", 200, {
+            "content-type": "application/x-ndjson",
+            "cache-control": "no-store",
+          });
+        } catch {
+          return c.json({ code: "shape_unavailable", message: "A deterministic fixture cannot be generated for this declaration." }, 422);
+        }
+      },
+    );

package/src/api/app-resource-access.ts

@@ -0,0 +1,48 @@
+import { type Context, Hono } from "hono";
+import { bindAppAccessRequest } from "../_internal/app-access-request";
+import { hasLocalResourceAppAccess } from "../_internal/app-access-resources";
+import { getApp } from "../_internal/registry";
+import type { AppMeta } from "../contracts/app";
+import { type AuthContext, auth, type RequestAuthority } from "../server/middleware/auth";
+import { rateLimit } from "../server/middleware/rate-limit";
+import { canUseApp } from "../services/app-access";
+import { resolveInvocationAuthority } from "../services/identity/invocation-actor";
+import { isInvocationJwtCandidate, verifyAppAccessProbe } from "../services/identity/invocation-token";
+
+/** Framework-only endpoint, mounted before the app gate to avoid recursive entry checks. */
+export const createResourceAppAccessRoutes = (app: Pick<AppMeta, "id" | "access">) => {
+  const router = new Hono<AuthContext>();
+  if (app.access?.kind === "resources")
+    router.post("/check", auth.readOnly, async (c) => {
+      c.header("Cache-Control", "private, no-store");
+      const token = c.req.header("authorization")?.match(/^Bearer (\S+)$/i)?.[1];
+      if (!token || !isInvocationJwtCandidate(token)) return c.body(null, 401);
+      const claims = await verifyAppAccessProbe(token, app.id);
+      if (!claims) return c.body(null, 401);
+      if (!hasLocalResourceAppAccess(app.id)) return c.body(null, 403);
+      const authority = await resolveInvocationAuthority(claims);
+      if (!authority) return c.body(null, 401);
+      return c.body(null, (await canUseApp(bindAppAccessRequest(authority, c.req.raw), app)) ? 204 : 403);
+    });
+  if (app.id === "core")
+    router.post(
+      "/apps/:appId",
+      auth.readOnly,
+      async (c, next) => {
+        c.header("Cache-Control", "private, no-store");
+        const token = c.req.header("authorization")?.match(/^Bearer (\S+)$/i)?.[1];
+        if (token && isInvocationJwtCandidate(token)) return c.body(null, 401);
+        await next();
+      },
+      auth.requireRole("authenticated"),
+      rateLimit(),
+      (c) => answerCoreProbe(c, auth.getAuthority(c)),
+    );
+  return router;
+};
+
+const answerCoreProbe = async (c: Context<AuthContext>, authority: RequestAuthority): Promise<Response> => {
+  const target = await getApp(c.req.param("appId") ?? "");
+  if (!target || target.access?.kind !== "resources") return c.body(null, 404);
+  return c.body(null, (await canUseApp(bindAppAccessRequest(authority, c.req.raw), target)) ? 204 : 403);
+};