@k2b/cloud 0.45.0 → 0.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.45.0",
+  "version": "0.47.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -21,15 +21,19 @@
     "!src/**/*.test-fixture.ts",
     "!src/**/*.test-fixture.tsx",
     "!scripts/**/*.test.ts",
+    "!scripts/**/*.test-fixture.ts",
     "!scripts/runtime-recovery-*.ts"
   ],
   "exports": {
     ".": "./src/index.ts",
+    "./app-key": "./src/app-key.ts",
+    "./start": "./src/start.ts",
     "./desktop": "./src/desktop/index.ts",
     "./desktop/solid": "./src/desktop/solid.tsx",
     "./server": "./src/server/index.ts",
     "./server/*": "./src/server/*",
     "./geo/ui": "./src/geo/ui.ts",
+    "./geo/document": "./src/contracts/geo-document.ts",
     "./browser": "./src/server/api-client.ts",
     "./browser/session": "./src/browser/session.ts",
     "./browser/shared-text": "./src/browser/shared-text.ts",
@@ -66,6 +70,7 @@
     "./shared": "./src/shared/index.ts",
     "./shared-text": "./src/shared-text/index.ts",
     "./services": "./src/services/index.ts",
+    "./services/pdf": "./src/services/pdf/index.ts",
     "./services/image-metadata": "./src/services/image-metadata.ts",
     "./services/document-extraction": "./src/services/document-extraction.ts",
     "./services/outbox": "./src/services/outbox.ts",
@@ -94,6 +99,7 @@
     "./config": "./src/config/index.ts",
     "./config/*": "./src/config/*",
     "./contracts": "./src/contracts/index.ts",
+    "./contracts/geo-snapshot": "./src/contracts/geo-snapshot.ts",
     "./contracts/notifications": "./src/contracts/notification-types.ts",
     "./contracts/*": "./src/contracts/*",
     "./events/testing": "./src/events/testing.ts",
@@ -124,8 +130,8 @@
     "@tabler/icons": "3.48.0",
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.18.0",
-    "@k2b/ssr": "0.20.1",
-    "@k2b/ui": "0.35.0",
+    "@k2b/ssr": "0.20.2",
+    "@k2b/ui": "0.37.0",
     "@k2b/stdlib": "0.30.0",
     "@k2b/sync": "7.0.1",
     "@nats-io/jetstream": "3.4.0",
@@ -156,7 +162,8 @@
     "yjs": "13.6.33",
     "hash-wasm": "4.12.0",
     "@types/sanitize-html": "2.16.1",
-    "@types/web-push": "3.6.4"
+    "@types/web-push": "3.6.4",
+    "@k2b/editor": "0.1.0"
   },
   "devDependencies": {
     "@babel/core": "8.0.6",

package/scripts/build.ts

@@ -116,9 +116,13 @@ const { app, plugin } = await import(configPath);
 // every production app without requiring app-owned bootstrap imports.
 const serverEntry = resolve(dist, ".server-entry.ts");
 const reflectMetadata = Bun.resolveSync("reflect-metadata", frameworkDir);
+const platformStart = resolve(frameworkDir, "src/start.ts");
+const declaredAppId = app?.meta.id ?? appId;
+if (declaredAppId !== appId)
+  throw new Error(`APP_ID ${JSON.stringify(appId)} does not match declared app ${JSON.stringify(declaredAppId)}`);
 await writeFile(
   serverEntry,
-  `import ${JSON.stringify(reflectMetadata)};\nexport { default } from ${JSON.stringify(resolve(appDir, "src/index.ts"))};\n`,
+  `import ${JSON.stringify(reflectMetadata)};\nimport { startPlatform } from ${JSON.stringify(platformStart)};\nconst application = await startPlatform({ appId: ${JSON.stringify(declaredAppId)}, load: () => import(${JSON.stringify(resolve(appDir, "src/index.ts"))}) });\nexport default application.default;\n`,
 );
 let server: Awaited<ReturnType<typeof Bun.build>>;
 try {

package/scripts/preload.ts

@@ -22,6 +22,7 @@ import { cp, mkdir } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import tailwind from "bun-plugin-tailwind";
+import { startPlatform } from "../src/start";
 import { writeAppFavicon } from "./app-favicon";
 import { buildBrowserPerformance } from "./browser-performance";
 import { writeInstallableIcons } from "./installable-assets";
@@ -43,7 +44,10 @@ if (!existsSync(appDir)) throw new Error(`Unknown app dir: ${appDir} (set APP_DI
 // Share the resolved source directory with defineApp before importing config.
 process.env.APP_DIR = appDir;
 
-const { app, plugin } = await import(resolve(appDir, "src/config"));
+const { app, plugin } = await startPlatform({ appId, load: () => import(resolve(appDir, "src/config")) });
+if (app && app.meta.id !== appId) {
+  throw new Error(`APP_ID ${JSON.stringify(appId)} does not match declared app ${JSON.stringify(app.meta.id)}`);
+}
 Bun.plugin((app?.plugin ?? plugin)());
 
 // ── Build CSS ───────────────────────────────────────────────────────────────

package/src/_internal/app-queries.ts

@@ -0,0 +1,73 @@
+import { sql } from "bun";
+import { Hono } from "hono";
+import { CAPABILITY_MAX_REQUEST_BYTES } from "../contracts/capabilities";
+import { resolveLocale } from "../server/locale";
+import { verifyAppQueryInvocation } from "../services/identity/invocation-token";
+import { get } from "../services/settings";
+import { readBoundedJson } from "./bounded-json";
+import { type CompiledCapabilities, invokeCompiledCapability, serializeCapabilityProviderResult } from "./capabilities";
+import { withCapabilityRequestTimeout } from "./capability-timeout";
+
+/** Framework-only route: never installs an app actor in the ordinary auth middleware. */
+export const createAppQueryRoutes = (compiled: CompiledCapabilities) =>
+  new Hono().post("/:capabilityId", (c) =>
+    withCapabilityRequestTimeout(c, "query", async () => {
+      const operation = compiled.queries.get(c.req.param("capabilityId"));
+      const deny = () => c.json({ code: "FORBIDDEN", message: "A permitted app query invocation is required" }, 403);
+      if (operation?.manifest.appOnly !== true || operation.manifest.stream) return deny();
+      const parsed = await readBoundedJson(c.req.raw, CAPABILITY_MAX_REQUEST_BYTES);
+      if (
+        !parsed.ok ||
+        !parsed.data ||
+        typeof parsed.data !== "object" ||
+        Array.isArray(parsed.data) ||
+        Object.keys(parsed.data).length !== 1 ||
+        !("input" in parsed.data)
+      )
+        return c.json({ code: "VALIDATION_FAILED", message: "Expected a bounded input object" }, 400);
+      const token = c.req.header("authorization")?.match(/^Bearer (\S+)$/)?.[1];
+      if (!token) return deny();
+      let claims: Awaited<ReturnType<typeof verifyAppQueryInvocation>>;
+      try {
+        claims = await verifyAppQueryInvocation(token, {
+          appId: compiled.manifest.appId,
+          capabilityId: operation.manifest.localId,
+          schemaHash: operation.manifest.schemaHash,
+          input: parsed.data.input,
+        });
+      } catch {
+        return c.json({ code: "APP_UNAVAILABLE", message: "Invocation verification unavailable" }, 503);
+      }
+      if (!claims) return deny();
+      // Revoking/expiring the workload credential also invalidates already-issued query tokens.
+      const [active] = await sql<{ id: string }[]>`
+    SELECT c.id FROM auth.service_account_credentials c JOIN auth.service_accounts sa ON sa.id = c.service_account_id
+    WHERE c.id = ${claims.credential_id}::uuid AND sa.id = ${claims.service_account_id}::uuid
+      AND c.kind = 'api_token' AND c.status = 'active' AND (c.expires_at IS NULL OR c.expires_at > now())
+      AND 'identity:invoke' = ANY(c.scopes) AND sa.status = 'active' AND sa.kind = 'resource_bound'
+      AND sa.delegated_user_id IS NULL AND sa.app_id = ${claims.sub} AND sa.resource_type = 'cloud.app' AND sa.resource_id = ${claims.sub}
+  `;
+      if (!active) return deny();
+      const result = await invokeCompiledCapability({
+        compiled,
+        kind: "query",
+        localId: operation.manifest.localId,
+        input: parsed.data.input,
+        expectedSchemaHash: claims.schema_hash,
+        context: {
+          actor: { kind: "app", appId: claims.sub },
+          accessSubject: { type: "none" },
+          user: null,
+          locale: resolveLocale(c.req.raw.headers, await get<string>("app.locale")),
+          requestId: claims.request_id,
+          origin: "app",
+          signal: c.req.raw.signal,
+        },
+      });
+      const response = serializeCapabilityProviderResult(result);
+      return new Response(response.body, {
+        status: response.status,
+        headers: { "content-type": "application/json", "cache-control": "no-store" },
+      });
+    }),
+  );

package/src/_internal/capabilities.ts

@@ -30,12 +30,14 @@ import {
   CapabilityActionPolicySchema,
   type CapabilityActionReviewResult,
   type CapabilityActionSentences,
+  type CapabilityAppExecutionContext,
   type CapabilityCalendarSourceDeclaration,
   CapabilityCalendarSourceManifestSchema,
   type CapabilityCommandDefinition,
   type CapabilityCommandManifest,
   CapabilityCommandManifestSchema,
   type CapabilityDefinitions,
+  CapabilityDiscussionsManifestSchema,
   type CapabilityError,
   CapabilityErrorSchema,
   type CapabilityExecutionContext,
@@ -51,16 +53,21 @@ import {
   type CapabilityQueryDefinition,
   type CapabilityQueryManifest,
   type CapabilityResourceTypeDefinition,
+  type CapabilityResourceTypeModel,
   type CapabilitySearchTagDefinition,
   type CapabilityStreamDefinition,
   type CapabilityUniversalSearchDefinition,
   CloudResourceViewSchema,
   capabilityActionPolicy,
   capabilityResultSchema,
+  ResourceReadableDataSchema,
+  ResourceReadableInputSchema,
   UniversalSearchDataSchema,
   UniversalSearchInputSchema,
 } from "../contracts/capabilities";
+import { discussionsIssues } from "../contracts/discussions";
 import { fileProviderIssues } from "../contracts/file-provider";
+import { typeViewIssues } from "../contracts/resource-types";
 import { canonicalLocale, localeFallbackChain, normalizeLocale } from "../shared/locale";
 import { capabilityActionReceiptIssues, capabilityActionReviewIssues, capabilityQueryChecksActionOutcome } from "./capability-reviews";
 import {
@@ -71,6 +78,10 @@ import {
   parseCapabilitySentence,
   resolveCapabilityActionSentences,
 } from "./capability-sentences";
+import { activeResourcePrincipals } from "./resource-principals";
+
+/** App-only queries never enter a person catalog. */
+export const isPersonVisibleCapabilityQuery = (query: CapabilityQueryManifest): boolean => query.appOnly !== true;
 
 type JsonSchema = Record<string, unknown>;
 const MAX_CAPABILITY_MANIFEST_BYTES = 256 * 1024;
@@ -96,6 +107,7 @@ const DECLARATION_FIELDS = {
   commands: true,
   fileProvider: true,
   calendarSource: true,
+  discussions: true,
   events: true,
   subscribes: true,
 } satisfies DefinedFields<CapabilityDefinitions>;
@@ -114,8 +126,11 @@ const TYPE_FIELDS = {
   color: true,
   reader: true,
   pages: true,
+  container: true,
+  access: true,
 } satisfies DefinedFields<CapabilityResourceTypeDefinition>;
 const QUERY_FIELDS = {
+  appOnly: true,
   title: true,
   description: true,
   input: true,
@@ -138,7 +153,7 @@ const ACTION_FIELDS = {
   policy: true,
   review: true,
   run: true,
-} satisfies DefinedFields<CapabilityActionDefinition>;
+} satisfies DefinedFields<Omit<CapabilityActionDefinition, "appOnly">>;
 const COMMAND_FIELDS = {
   title: true,
   description: true,
@@ -170,8 +185,14 @@ const assertDefinedStreamFields = (stream: CapabilityStreamDefinition | undefine
   if (stream) assertDefinedFields(stream, stream.direction === "write" ? WRITE_STREAM_FIELDS : READ_STREAM_FIELDS, `${label} stream`);
 };
 
+type AppQueryDefinition = Omit<CapabilityQueryDefinition, "appOnly" | "run"> & {
+  appOnly: true;
+  run: (input: unknown, context: CapabilityAppExecutionContext) => Promise<CapabilityInvocationResult<unknown>>;
+};
+type QueryDefinition = CapabilityQueryDefinition | AppQueryDefinition;
+
 export type CompiledCapabilityQuery = {
-  definition: CapabilityQueryDefinition;
+  definition: QueryDefinition;
   manifest: CapabilityQueryManifest;
   resultSchema: z.ZodType;
 };
@@ -621,7 +642,7 @@ const assertLocalId = (localId: string, label: string): void => {
   if (!parsed.success) throw new Error(`${label} key "${localId}" is invalid: ${parsed.error.issues[0]?.message ?? "invalid id"}`);
 };
 
-const normalizeSearchTags = (definition: CapabilityQueryDefinition, label: string) => {
+const normalizeSearchTags = (definition: QueryDefinition, label: string) => {
   if (!definition.universalSearch) return undefined;
   assertDefinedFields(definition.universalSearch, UNIVERSAL_SEARCH_FIELDS, `${label} universalSearch`);
   const seen = new Set<string>();
@@ -647,7 +668,7 @@ const normalizeSearchTags = (definition: CapabilityQueryDefinition, label: strin
   return { tags, ...(definition.universalSearch.scopeTypes ? { scopeTypes: [...new Set(definition.universalSearch.scopeTypes)] } : {}) };
 };
 
-const compileOperationSchemas = (definition: CapabilityQueryDefinition | CapabilityActionDefinition, label: string) => {
+const compileOperationSchemas = (definition: QueryDefinition | CapabilityActionDefinition, label: string) => {
   assertText(definition.title, `${label} title`, 120);
   assertText(definition.description, `${label} description`, 1000);
   const inputSchema = projectSchema(definition.input, `${label} input`, "input");
@@ -667,6 +688,7 @@ const compileOperationSchemas = (definition: CapabilityQueryDefinition | Capabil
     schemaHash: capabilityHash({
       inputSchema,
       dataSchema,
+      ...("appOnly" in definition && definition.appOnly !== undefined ? { appOnly: definition.appOnly } : {}),
       ...(definition.stream ? { stream: { direction: definition.stream.direction, maxBytes: definition.stream.maxBytes } } : {}),
     }),
   };
@@ -688,6 +710,26 @@ export const compileCapabilities = (
   }
   if (definitions.fileProvider) assertDefinedFields(definitions.fileProvider, FILE_PROVIDER_FIELDS, "fileProvider");
 
+  if (definitions.discussions !== undefined) CapabilityDiscussionsManifestSchema.parse(definitions.discussions);
+  for (const [localId, type] of Object.entries(definitions.types ?? {})) {
+    if (type.access !== undefined) {
+      assertDefinedFields(type.access, { readable: true }, `Resource type ${localId} access`);
+      if (type.access.readable !== undefined && typeof type.access.readable !== "function")
+        throw new Error(`Resource type ${localId} access.readable must be a function`);
+    }
+    const visited = new Set([localId]);
+    let container = type.container;
+    while (container !== undefined) {
+      CapabilityLocalIdSchema.parse(container);
+      const parent = definitions.types?.[container];
+      if (!parent || !Object.hasOwn(definitions.types ?? {}, container))
+        throw new Error(`Resource type ${localId}: unknown container ${container}`);
+      if (visited.has(container)) throw new Error(`Resource type ${localId}: container cycle at ${container}`);
+      visited.add(container);
+      container = parent.container;
+    }
+  }
+
   const localIds = new Set<string>();
   const registerLocalId = (localId: string, kind: string): void => {
     assertLocalId(localId, kind);
@@ -722,11 +764,55 @@ export const compileCapabilities = (
     });
   const typeIds = new Set(types.map((type) => qualifiedId(appId, type.localId)));
 
+  for (const [localId, definition] of Object.entries(definitions.queries ?? {}))
+    if (Object.hasOwn(definition, "appOnly")) throw new Error(`Query ${localId}: appOnly is reserved for platform-generated reader checks`);
+  const generated: Record<string, AppQueryDefinition> = {};
+  for (const [localId, type] of Object.entries(definitions.types ?? {})) {
+    const readable = type.access?.readable;
+    if (!readable) continue;
+    const queryId = `${localId}.readable`;
+    if (Object.hasOwn(definitions.queries ?? {}, queryId)) throw new Error(`Generated Query ${queryId} collides with a declared Query`);
+    const container = type.container;
+    const input = container
+      ? ResourceReadableInputSchema.extend({
+          container: ResourceReadableInputSchema.shape.container
+            .unwrap()
+            .extend({ type: z.literal(qualifiedId(appId, container)).describe("Declared container type.") })
+            .describe("Expected current container of the resource."),
+        })
+      : ResourceReadableInputSchema;
+    generated[queryId] = {
+      title: "Check resource readers",
+      description: `Check current principal readability of ${type.title} without granting content access.`,
+      input,
+      data: ResourceReadableDataSchema,
+      openWorld: false,
+      appOnly: true,
+      run: async (value: unknown, context) => {
+        if (!isAppCapabilityContext(context))
+          return { ok: false, error: { code: "FORBIDDEN", message: "App authority required", status: 403 } };
+        const parsed = input.parse(value);
+        const principals = await activeResourcePrincipals(parsed.principals);
+        const key = (principal: (typeof principals)[number]) => JSON.stringify(principal);
+        const requested = new Set(principals.map(key));
+        const result = ResourceReadableDataSchema.parse({ readable: await readable({ ...parsed, principals }, context) });
+        if (result.readable.some((principal) => !requested.has(key(principal))))
+          throw new Error(`Resource type ${localId} readable returned an unrequested principal`);
+        return { ok: true, data: { data: result } };
+      },
+    };
+  }
   const queries = new Map<string, CompiledCapabilityQuery>();
-  for (const [localId, definition] of Object.entries(definitions.queries ?? {}).sort(([left], [right]) => left.localeCompare(right))) {
+  for (const [localId, definition] of Object.entries({ ...definitions.queries, ...generated }).sort(([left], [right]) =>
+    left.localeCompare(right),
+  )) {
     registerLocalId(localId, "Query");
     const label = `Query ${localId}`;
     assertDefinedFields(definition, QUERY_FIELDS, label);
+    if (definition.appOnly !== undefined) {
+      z.literal(true).parse(definition.appOnly);
+      if (definition.stream) throw new Error(`${label}: app-only queries cannot use streams`);
+    }
     assertDefinedStreamFields(definition.stream, label);
     if (
       definition.stream &&
@@ -756,6 +842,7 @@ export const compileCapabilities = (
       ...(definition.stream ? { stream: { direction: definition.stream.direction, maxBytes: definition.stream.maxBytes } } : {}),
       openWorld: definition.openWorld,
       universalSearch: normalizeSearchTags(definition, label),
+      ...(definition.appOnly !== undefined ? { appOnly: definition.appOnly } : {}),
     } satisfies CapabilityQueryManifest;
     for (const type of manifest.universalSearch?.scopeTypes ?? []) {
       if (!typeIds.has(qualifiedId(appId, type))) throw new Error(`${label} declares an unknown search scope type ${type}`);
@@ -770,6 +857,7 @@ export const compileCapabilities = (
     if (!type.reader) continue;
     const reader = queries.get(type.reader);
     if (!reader) throw new Error(`Resource type ${type.localId} reader ${type.reader} must name an existing Query`);
+    if (reader.manifest.appOnly) throw new Error(`Resource type ${type.localId} reader cannot be app-only`);
     assertCanonicalReaderInput(reader.manifest.inputSchema, `Resource type ${type.localId} reader ${type.reader} input`);
   }
   const actions = new Map<string, CompiledCapabilityAction>();
@@ -931,7 +1019,25 @@ export const compileCapabilities = (
   const resourcePages = Object.entries(definitions.types ?? {})
     .sort(([a], [b]) => a.localeCompare(b))
     .flatMap(([type, definition]) => (definition.pages ?? []).map((path) => ({ type, path })));
+  const resourceTypes: CapabilityResourceTypeModel[] = types.flatMap((type) => {
+    const declaration = definitions.types?.[type.localId];
+    const model: CapabilityResourceTypeModel = {
+      type: type.localId,
+      ...(declaration?.container ? { container: declaration.container } : {}),
+      ...(declaration?.access?.readable ? { readable: true } : {}),
+    };
+    const reader = type.reader ? queries.get(type.reader) : undefined;
+    if (
+      reader &&
+      typeViewIssues({ types, queries: [...queries.values()].map((query) => query.manifest), resourceTypes: [model] }, type.localId)
+        .length === 0
+    )
+      model.view = true;
+    return model.container || model.readable || model.view ? [model] : [];
+  });
   const manifestBase = {
+    ...(resourceTypes.length ? { resourceTypes } : {}),
+    ...(definitions.discussions ? { discussions: definitions.discussions } : {}),
     ...(resourcePages.length ? { resourcePages } : {}),
     protocolVersion: CAPABILITY_PROTOCOL_VERSION,
     appId,
@@ -952,6 +1058,9 @@ export const compileCapabilities = (
     ...manifestBase,
     manifestHash: capabilityHash(manifestBase),
   });
+  const discussionIssues = discussionsIssues(manifest);
+  if (discussionIssues.length)
+    throw new Error(`discussions: ${discussionIssues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`);
   const calendarIssues = calendarSourceIssues(manifest);
   if (calendarIssues.length)
     throw new Error(
@@ -1124,6 +1233,8 @@ export const resolveCapabilityManifestPresentation = (
           }
         : {}),
       ...(current.subscribes ? { subscribes: current.subscribes } : {}),
+      ...(current.resourceTypes ? { resourceTypes: current.resourceTypes } : {}),
+      ...(current.discussions ? { discussions: current.discussions } : {}),
       ...(current.resourcePages ? { resourcePages: current.resourcePages } : {}),
       ...(current.calendarSource ? { calendarSource: current.calendarSource } : {}),
       ...(current.fileProvider ? { fileProvider: current.fileProvider } : {}),
@@ -1157,9 +1268,11 @@ const assertUsableOperation = (operation: CapabilityQueryManifest | CapabilityAc
   if (operation.stream?.direction === "write" && (!("idempotency" in operation) || operation.idempotency !== "required")) {
     throw new Error(`Operation ${operation.localId} write streams require an idempotent Action`);
   }
+  if ("appOnly" in operation && operation.appOnly !== undefined && operation.stream) throw new Error("App-only queries cannot use streams");
   const expectedSchemaHash = capabilityHash({
     inputSchema: operation.inputSchema,
     dataSchema: operation.dataSchema,
+    ...("appOnly" in operation && operation.appOnly !== undefined ? { appOnly: operation.appOnly } : {}),
     ...(operation.stream ? { stream: operation.stream } : {}),
   });
   if (operation.schemaHash !== expectedSchemaHash) throw new Error(`Operation ${operation.localId} schemaHash does not match its schemas`);
@@ -1542,13 +1655,17 @@ const cancelledInvocation = (locale: string) => ({
   },
 });
 
+const isAppCapabilityContext = (
+  context: CapabilityExecutionContext | CapabilityAppExecutionContext,
+): context is CapabilityAppExecutionContext => context.actor.kind === "app";
+
 export const invokeCompiledCapability = async (params: {
   compiled: CompiledCapabilities;
   kind: "query" | "action";
   localId: string;
   input: unknown;
   expectedSchemaHash: string | null;
-  context: CapabilityExecutionContext;
+  context: CapabilityExecutionContext | CapabilityAppExecutionContext;
   onUnexpectedError?: (error: unknown) => void;
 }): Promise<CapabilityInvocationResult<unknown>> => {
   if (!hasOAuthScope(params.context.authority, params.kind === "query" ? "read" : "write", "admin"))
@@ -1564,6 +1681,8 @@ export const invokeCompiledCapability = async (params: {
       },
     };
   }
+  if (!isAppCapabilityContext(params.context) && "appOnly" in operation.definition && operation.definition.appOnly !== undefined)
+    return { ok: false, error: { code: "FORBIDDEN", message: "App authority required", status: 403 } };
   if (params.expectedSchemaHash !== operation.manifest.schemaHash) {
     return {
       ok: false,
@@ -1575,7 +1694,7 @@ export const invokeCompiledCapability = async (params: {
       },
     };
   }
-  let context: CapabilityExecutionContext = {
+  let context: CapabilityExecutionContext | CapabilityAppExecutionContext = {
     ...params.context,
     via: capabilityVia(params.context.origin),
   };
@@ -1624,7 +1743,7 @@ export const invokeCompiledCapability = async (params: {
         },
       };
     }
-    context = { ...context, idempotencyKey: idempotencyKey.data };
+    if (!isAppCapabilityContext(context)) context = { ...context, idempotencyKey: idempotencyKey.data };
   }
   const input = operation.definition.input.safeParse(params.input);
   if (!input.success) {
@@ -1652,7 +1771,16 @@ export const invokeCompiledCapability = async (params: {
   // cross into application code for the first time with an aborted invocation.
   if (context.signal.aborted) return cancelledInvocation(context.locale);
   try {
-    const invoked = await operation.definition.run(input.data, context);
+    let invoked: CapabilityInvocationResult<unknown>;
+    if (isAppCapabilityContext(context)) {
+      const definition = operation.definition;
+      if (params.kind !== "query" || !("appOnly" in definition) || definition.appOnly !== true)
+        return { ok: false, error: { code: "FORBIDDEN", message: "App caller is not allowed", status: 403 } };
+      invoked = await definition.run(input.data, context);
+    } else {
+      if (operation.definition.appOnly) return { ok: false, error: { code: "FORBIDDEN", message: "App authority required", status: 403 } };
+      invoked = await operation.definition.run(input.data, context);
+    }
     if (!invoked.ok) {
       return normalizeProviderError(invoked.error, "Capability returned an invalid error", params.onUnexpectedError);
     }

package/src/_internal/define-app.ts

@@ -2,6 +2,7 @@ import { type AppSkillDefinition, appSkillManifestHash, registerAppSkills, valid
 import { createOwnedAppAccessRoutes } from "../api/app-access";
 import { createAppEventDeliveryRoutes } from "../api/app-event-delivery";
 import { createResourceAppAccessRoutes } from "../api/app-resource-access";
+import { createSettingsOpsRoutes, settingsInvocationOperation } from "../api/settings-ops";
 import { type AppAccessDeclaration, compileAppAccess } from "../contracts/app-access";
 import { startAppEventDelivery } from "../events/app-event-delivery";
 import { bindAppEvents } from "../events/app-events";
@@ -12,6 +13,7 @@ import { registerPageSwap } from "../ssr/page-swap";
 import { preloadPanelConsent } from "../ssr/panel-consent";
 import { appAccessManagementPath } from "./app-access-path";
 import { bindResourceAppAccess, RESOURCE_ACCESS_PATH } from "./app-access-resources";
+import { createAppQueryRoutes } from "./app-queries";
 import { registerApplicationPackage, resolveApplicationPackage } from "./application-package";
 import { invokeCapabilityStream } from "./capability-streams";
 import { withCapabilityRequestTimeout } from "./capability-timeout";
@@ -118,6 +120,7 @@ import { publicFileVersion, servePublicAsset, sharedStylesheetVersion, versioned
 import { createStatusPreservingSsrHandler } from "./status-preserving-ssr";
 import { WEB_VITALS_ASSET_HREF } from "./web-vitals-asset";
 import { compileWidgetDeclarations } from "./widget-declarations";
+import { createAppWorkloadCredential } from "./workload-credential";
 
 /** Only development links use this start stamp to pick up rebuilds. */
 const developmentStamp = Date.now();
@@ -690,6 +693,10 @@ export const defineApp = <
   // ── 3. start() — builds and boots the Hono server ────────────────────
   const start = async (startOpts: StartOptions): Promise<StartResult> => {
     const port = startOpts.port ?? 3000;
+    if (env.GOTENBERG_URL)
+      console.warn("[deprecation] GOTENBERG_URL only bootstraps gotenberg.url; remove it after cld admin settings status --env succeeds.");
+    if (env.CLOUD_IDENTITY_JWKS_ORIGIN)
+      console.warn("[deprecation] CLOUD_IDENTITY_JWKS_ORIGIN is deprecated; use CLOUD_CORE_INTERNAL_ORIGIN instead.");
     const baseUrl = opts.baseUrl;
     const log = logger("app");
     const http = createHttpDrain();
@@ -863,6 +870,7 @@ export const defineApp = <
         await capabilityHeartbeat?.stop();
       });
       cleanup.push(() => heartbeat.stop());
+      cleanup.push(() => membership.leave());
 
       // Runtime context — start the registry watcher so middleware.runtime() and
       // the lifecycle context below see populated cluster state. Idempotent: the
@@ -908,6 +916,18 @@ export const defineApp = <
           if (!c.get("user")?.roles.includes("admin")) return c.json({ message: "Insufficient permissions" }, 403);
           return next();
         })
+        .use(
+          "/_internal/settings/*",
+          requireInvocation(
+            (c) => ({
+              targetAppId: meta.id,
+              operation: settingsInvocationOperation(c.req.method, new URL(c.req.url).pathname.slice("/_internal/settings/".length)),
+              schemaHash: null,
+            }),
+            invocationApp,
+          ),
+        )
+        .route("/_internal/settings", createSettingsOpsRoutes(Object.keys(opts.settings ?? {})))
         .route("/_internal/sync", createSyncOpsRoutes(getProcessSync));
 
       if (installable) server.route("/", createInstallableRoutes(meta.id, installable));
@@ -916,6 +936,7 @@ export const defineApp = <
         server.route("/api/_internal/events/v1", createAppEventDeliveryRoutes(compiledCapabilities));
 
       if (compiledCapabilities) {
+        server.route("/api/_internal/capabilities/v1/app-queries", createAppQueryRoutes(compiledCapabilities));
         const invoke = async (c: Context<AuthContext>, kind: "query" | "action" | "review") =>
           withCapabilityRequestTimeout(c, kind, async () => {
             // Framework-owned endpoints run before the app's settings middleware,
@@ -1143,6 +1164,8 @@ export const defineApp = <
 
       let stopNotificationRegistration: (() => void) | undefined;
       cleanup.push(() => stopNotificationRegistration?.());
+      let workloadCredential: ReturnType<typeof createAppWorkloadCredential> | undefined;
+      cleanup.push(() => workloadCredential?.stop());
       const stopLifecycle = startOpts.lifecycle?.stop;
       if (stopLifecycle) cleanup.push(() => stopLifecycle(cloudCtx));
 
@@ -1167,6 +1190,23 @@ export const defineApp = <
 
       await loadSettingsCache();
 
+      // The instance can obtain its credential before workers run; routes remain undiscoverable.
+      await membership.register();
+      workloadCredential = createAppWorkloadCredential({
+        appId: meta.id,
+        instanceId: membership.instanceId,
+        onRecovered: () => log.info("App workload credential refresh recovered", { appId: meta.id }),
+        onUnavailable: (reason) => {
+          if (reason === "release_unavailable") {
+            log.warn("Workload credential release was not confirmed; Core will reconcile after removal", { appId: meta.id });
+          } else {
+            log.error("App workload credential unavailable; background invocation is disabled", { appId: meta.id, reason });
+          }
+        },
+      });
+      // The NATS request has a five-second timeout; an outage leaves workers fail-closed.
+      await workloadCredential.start();
+
       if (startOpts.lifecycle?.start) {
         log.info(`Start: ${meta.id}`);
         await startOpts.lifecycle.start(cloudCtx);

package/src/_internal/heartbeat.ts

@@ -94,6 +94,25 @@ export const createRegistryMembership = (
   };
 
   return {
+    instanceId,
+    // Establish process identity before lifecycle workers start, without advertising routes yet.
+    register: async () => {
+      let timer: Timer | undefined;
+      // This runs before the ordinary heartbeat supplies its write deadline.
+      const write = upsert().finally(async () => {
+        if (left) await options.registry().delete({ key });
+      });
+      try {
+        await Promise.race([
+          write,
+          new Promise<never>((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`Instance registration timed out after ${writeTimeoutMs}ms`)), writeTimeoutMs);
+          }),
+        ]);
+      } finally {
+        clearTimeout(timer);
+      }
+    },
     join: async (sharedKey: string, sharedValue: unknown, entry: SharedEntry): Promise<void> => {
       left = false;
       await prepareShared(sharedKey);

package/src/_internal/postgres-application-name.ts

@@ -1,3 +1,4 @@
+// Slice 7 removes this legacy env-URL rewrite together with Bun-global client imports.
 /** Name Bun's default pool before its first use without changing connection ownership. */
 export const configurePostgresApplicationName = (
   applicationId: string,
@@ -28,3 +29,13 @@ export const configurePostgresApplicationName = (
   url.searchParams.set("application_name", `cloud:${applicationId}`);
   environment[variable] = url.toString();
 };
+
+/** Preserve operator URL options; otherwise name every connection through native client options. */
+export const postgresApplicationOptions = (applicationId: string, connectionUrl: string): Record<string, string> => {
+  const url = new URL(connectionUrl);
+  let operatorConfigured = false;
+  url.searchParams.forEach((_value, key) => {
+    if (key.toLowerCase() === "application_name" || key.toLowerCase() === "options") operatorConfigured = true;
+  });
+  return operatorConfigured ? {} : { application_name: `cloud:${applicationId}` };
+};