@k2b/cloud 0.45.0 → 0.46.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -30,6 +30,7 @@
     "./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 +67,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 +96,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",
@@ -125,7 +128,7 @@
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.18.0",
     "@k2b/ssr": "0.20.1",
-    "@k2b/ui": "0.35.0",
+    "@k2b/ui": "0.36.0",
     "@k2b/stdlib": "0.30.0",
     "@k2b/sync": "7.0.1",
     "@nats-io/jetstream": "3.4.0",

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

@@ -12,6 +12,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";
@@ -916,6 +917,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,

package/src/_internal/registry-validation.ts

@@ -160,8 +160,8 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
       return invalid("widgets", "an array of valid widgets");
     }
   }
-  if (value.platformPermissions !== undefined && !PlatformPermissionSchema.array().safeParse(value.platformPermissions).success)
-    return invalid("platformPermissions", "an array of platform permissions");
+  if (value.platformPermissions !== undefined && !isStringArray(value.platformPermissions))
+    return invalid("platformPermissions", "an array of permission IDs");
   if (value.settingKeys !== undefined && !isStringArray(value.settingKeys)) return invalid("settingKeys", "an array of strings");
   if (
     value.cliModules !== undefined &&
@@ -198,5 +198,18 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
   return null;
 };
 
-export const asAppRegistryEntry = (value: unknown): AppRegistryEntry | null =>
-  validateAppRegistryEntry(value) === null ? (value as AppRegistryEntry) : null;
+export const asAppRegistryEntry = (value: unknown): AppRegistryEntry | null => {
+  if (validateAppRegistryEntry(value) !== null) return null;
+  const entry = value as AppRegistryEntry;
+  return {
+    ...entry,
+    ...(entry.platformPermissions !== undefined
+      ? {
+          platformPermissions: entry.platformPermissions.flatMap((permission) => {
+            const parsed = PlatformPermissionSchema.safeParse(permission);
+            return parsed.success ? [parsed.data] : [];
+          }),
+        }
+      : {}),
+  };
+};

package/src/_internal/registry.ts

@@ -3,6 +3,7 @@ import type { EphemeralConfig, MutexConfig } from "@k2b/sync";
 import type { AppAppearanceColor } from "../contracts/app";
 import { calendarSourceIssues } from "../contracts/calendar-source";
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "../contracts/capabilities";
+import { discussionsIssues } from "../contracts/discussions";
 import { fileProviderIssues } from "../contracts/file-provider";
 import type { AppRegistryEntry, CapabilityRegistryEntry } from "../contracts/registry";
 import { resourcePageIssue } from "../contracts/resource-pages";
@@ -18,7 +19,7 @@ import {
 import { resolveAppPresentations } from "../shared/app-presentation";
 import { compileCapabilityPresentation, parseCapabilityManifest } from "./capabilities";
 import { lazySync } from "./process-sync";
-import { validateAppRegistryEntry } from "./registry-validation";
+import { asAppRegistryEntry, validateAppRegistryEntry } from "./registry-validation";
 import { watchRegistryChanges } from "./registry-watch";
 import { WidgetSettingsDeclarationSchema } from "./widget-settings";
 
@@ -150,7 +151,7 @@ export const readAppRegistrySnapshot = async (): Promise<AppRegistrySnapshot> =>
       continue;
     }
     loggedInvalidReasons.delete(entry.key);
-    const value = entry.value as AppRegistryEntry;
+    const value = asAppRegistryEntry(entry.value)!;
     const updatedAt = entry.updatedAt.getTime();
     apps.push({
       ...value,
@@ -194,7 +195,7 @@ export const getApp = async (appId: string): Promise<AppRegistryEntry | null> =>
       : validateAppRegistryEntry(entry.value);
   if (!reason) {
     loggedInvalidReasons.delete(key);
-    return entry.value;
+    return asAppRegistryEntry(entry.value);
   }
   reportInvalidEntry({ key, version: entry.revision, reason });
   return null;
@@ -237,6 +238,7 @@ const reportLeftOutEntries = (sent: unknown, manifest: CapabilityManifest): void
   });
   if (groups.calendarSource !== undefined && !manifest.calendarSource) leftOut.push("calendarSource");
   if (groups.fileProvider !== undefined && !manifest.fileProvider) leftOut.push("fileProvider");
+  if (groups.discussions !== undefined && !manifest.discussions) leftOut.push("discussions");
   if (leftOut.length === 0) return;
   console.warn(
     JSON.stringify({
@@ -320,6 +322,32 @@ const withValidCalendarSource = (manifest: CapabilityManifest): CapabilityManife
   return rest;
 };
 
+const checkedDiscussions = new Map<string, { manifestHash: string; valid: boolean }>();
+const withValidDiscussions = (manifest: CapabilityManifest): CapabilityManifest => {
+  if (!manifest.discussions) return manifest;
+  const checked = checkedDiscussions.get(manifest.appId);
+  let valid = checked?.manifestHash === manifest.manifestHash ? checked.valid : undefined;
+  if (valid === undefined) {
+    const issues = discussionsIssues(manifest);
+    valid = issues.length === 0;
+    checkedDiscussions.set(manifest.appId, { manifestHash: manifest.manifestHash, valid });
+    if (!valid)
+      console.error(
+        JSON.stringify({
+          level: "error",
+          source: "capability-registry",
+          message: "Ignored an incompatible discussions provider",
+          appId: manifest.appId,
+          manifestHash: manifest.manifestHash,
+          issues,
+        }),
+      );
+  }
+  if (valid) return manifest;
+  const { discussions: _ignored, ...rest } = manifest;
+  return rest;
+};
+
 /** Ignores record fields from a newer release; the endpoint always comes from the live app registry. */
 export const resolveLiveCapabilityRegistryEntry = (
   key: string,
@@ -334,7 +362,7 @@ export const resolveLiveCapabilityRegistryEntry = (
   if (!endpoint) return null;
   try {
     const read = parseCapabilityManifest(record.manifest, app.id);
-    const supported = withValidCalendarSource(withValidFileProvider(read));
+    const supported = withValidDiscussions(withValidCalendarSource(withValidFileProvider(read)));
     const manifest = supported.resourcePages
       ? {
           ...supported,

package/src/_internal/resource-principals.ts

@@ -0,0 +1,36 @@
+import { sql } from "bun";
+import type { ResourcePrincipal } from "../contracts/capabilities";
+import { decodeAccountCategoryEnabled } from "../services/account-category-policy";
+import { toPgTextArray } from "../services/postgres";
+
+/** One bounded identity lookup before any provider-owned readability check. */
+export const activeResourcePrincipals = async (principals: ResourcePrincipal[]): Promise<ResourcePrincipal[]> => {
+  if (!principals.length) return [];
+  const users = principals.flatMap((principal) => (principal.type === "user" ? [principal.userId] : []));
+  const accounts = principals.flatMap((principal) => (principal.type === "service_account" ? [principal.serviceAccountId] : []));
+  const rows = await sql<{ type: ResourcePrincipal["type"]; id: string; category_enabled: string | null }[]>`
+    SELECT 'user' AS type, u.id, category.value AS category_enabled
+    FROM auth.users u
+    LEFT JOIN settings.entries category ON category.key = 'user.category.' ||
+      CASE WHEN u.provider = 'ipa' THEN 'freeipa' WHEN u.profile = 'guest' THEN 'guest' ELSE 'login' END || '.enabled'
+    WHERE u.id = ANY(${toPgTextArray(users)}::uuid[])
+      AND (u.account_expires IS NULL OR u.account_expires > clock_timestamp())
+    UNION ALL
+    SELECT 'service_account', sa.id, category.value
+    FROM auth.service_accounts sa
+    LEFT JOIN auth.users du ON du.id = sa.delegated_user_id
+    LEFT JOIN settings.entries category ON sa.kind = 'user_delegated' AND category.key = 'user.category.' ||
+      CASE WHEN du.provider = 'ipa' THEN 'freeipa' WHEN du.profile = 'guest' THEN 'guest' ELSE 'login' END || '.enabled'
+    WHERE sa.id = ANY(${toPgTextArray(accounts)}::uuid[]) AND sa.status = 'active'
+      AND (sa.kind <> 'user_delegated' OR (du.id IS NOT NULL AND (du.account_expires IS NULL OR du.account_expires > clock_timestamp())))
+  `;
+  const enabled = new Map<string | null, boolean>();
+  const active = new Set<string>();
+  for (const row of rows) {
+    if (!enabled.has(row.category_enabled)) enabled.set(row.category_enabled, await decodeAccountCategoryEnabled(row.category_enabled));
+    if (enabled.get(row.category_enabled)) active.add(`${row.type}:${row.id}`);
+  }
+  return principals.filter((principal) =>
+    active.has(`${principal.type}:${(principal.type === "user" ? principal.userId : principal.serviceAccountId).toLowerCase()}`),
+  );
+};

package/src/ai/capabilities.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import type { Tool, ToolContext, ToolResolver } from "@k2b/nessi";
 import { z } from "zod";
-import { resolveCapabilityActionWording, resolveCapabilityOperationTitle } from "../_internal/capabilities";
+import { isPersonVisibleCapabilityQuery, resolveCapabilityActionWording, resolveCapabilityOperationTitle } from "../_internal/capabilities";
 import { capabilityReviewView } from "../_internal/capability-reviews";
 import {
   CAPABILITY_APPROVAL_REASON_FIELD,
@@ -164,7 +164,9 @@ export const buildAiCapabilityCatalog = (apps: CapabilityRegistryEntry[], locale
         : app.appName;
       return [
         ...app.manifest.actions.map((operation) => ({ app, appName, operation, kind: "action" as const })),
-        ...app.manifest.queries.map((operation) => ({ app, appName, operation, kind: "query" as const })),
+        ...app.manifest.queries
+          .filter(isPersonVisibleCapabilityQuery)
+          .map((operation) => ({ app, appName, operation, kind: "query" as const })),
       ];
     })
     .map(