@k2b/cloud 0.43.0 → 0.44.0

package/src/contracts/resource-clipboard.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { type CloudResourceRef, CloudResourceRefSchema } from "./capabilities";
+import { cloudResourceHref } from "./resource-href";
 
 export const CLOUD_RESOURCE_CLIPBOARD_MIME_TYPE = "application/vnd.k2b.cloud-resource-ref+json";
 export const CLOUD_RESOURCE_CLIPBOARD_WEB_FORMAT = `web ${CLOUD_RESOURCE_CLIPBOARD_MIME_TYPE}`;
@@ -31,3 +32,37 @@ export const parseCloudResourceClipboard = (value: string, cloudUrl: string): Cl
     return null;
   }
 };
+
+/** Longest permalink a consumer accepts, like `CloudResourceHrefSchema`. */
+const CLOUD_RESOURCE_URL_MAX_LENGTH = 8_192;
+const CLOUD_RESOURCE_PATH = /^\/open\/([^/]+)\/~([^/]+)$/;
+
+/** The absolute permalink of a resource: the text form people copy, paste, and open. */
+export const formatCloudResourceUrl = (ref: CloudResourceRef, cloudUrl: string): string =>
+  new URL(cloudResourceHref(CloudResourceRefSchema.parse(ref)), cloudUrl).href;
+
+/**
+ * Reads a resource from its permalink on this Cloud, absolute or root-relative. Anything else, such as another
+ * installation's link, an app page, or a query or fragment, returns `null`.
+ */
+export const parseCloudResourceUrl = (value: string, cloudUrl: string): CloudResourceRef | null => {
+  const text = value.trim();
+  if (text.length === 0 || text.length > CLOUD_RESOURCE_URL_MAX_LENGTH) return null;
+  let url: URL;
+  try {
+    url = text.startsWith("/") && !text.startsWith("//") ? new URL(text, cloudUrl) : new URL(text);
+  } catch {
+    return null;
+  }
+  if (url.origin !== cloudUrl || url.search || url.hash) return null;
+  const match = CLOUD_RESOURCE_PATH.exec(url.pathname);
+  if (!match?.[1] || !match[2]) return null;
+  let id: string;
+  try {
+    id = decodeURIComponent(match[2]);
+  } catch {
+    return null;
+  }
+  const ref = CloudResourceRefSchema.safeParse({ type: match[1], id });
+  return ref.success ? ref.data : null;
+};

package/src/contracts/resource-pages.ts

@@ -0,0 +1,140 @@
+import type { CloudResourceRef } from "./capabilities";
+
+/** Eight alternate pages per Type, within the manifest's 200-Type budget. */
+export const RESOURCE_PAGES_PER_TYPE = 8;
+/** Like other manifest route declarations, page patterns are bounded short paths. */
+export const RESOURCE_PAGE_MAX_LENGTH = 300;
+export const RESOURCE_URL_MAX_LENGTH = 8_192;
+
+type Part = { literal: string } | { capture: string };
+type Pattern = { segments: Part[]; query: [string, Part][] };
+const capture = /^:([a-zA-Z][a-zA-Z0-9_]*)$/;
+const decode = (value: string): string => decodeURIComponent(value);
+const part = (value: string): Part => {
+  const match = capture.exec(value);
+  if (match?.[1]) return { capture: match[1] };
+  if (!value || value.includes(":")) throw new Error("Captures must occupy a whole segment or query value");
+  const literal = decode(value);
+  if (!literal || literal === "." || literal === ".." || /[\\/\u0000-\u001f]/.test(literal)) throw new Error("Invalid literal segment");
+  return { literal };
+};
+
+const parsePattern = (path: string): Pattern => {
+  if (!path.startsWith("/") || path.startsWith("//") || path.length > RESOURCE_PAGE_MAX_LENGTH || /[\s#\\]/.test(path))
+    throw new Error(`Expected a root-relative page pattern of at most ${RESOURCE_PAGE_MAX_LENGTH} characters`);
+  const [pathname = "", search = "", extra] = path.split("?");
+  if (extra !== undefined) throw new Error("Page patterns may contain only one query separator");
+  const route = pathname.replace(/\/$/, "").slice(1);
+  const segments = route ? route.split("/").map(part) : [];
+  const keys = new Set<string>();
+  const query: [string, Part][] = search
+    ? search.split("&").map((entry) => {
+        const [key = "", value, extraValue] = entry.split("=");
+        if (!key || value === undefined || extraValue !== undefined) throw new Error("Expected query key=value");
+        const decodedKey = decode(key.replace(/\+/g, " "));
+        if (!decodedKey || decodedKey.includes(":") || keys.has(decodedKey)) throw new Error("Invalid or repeated query key");
+        keys.add(decodedKey);
+        return [decodedKey, part(value.replace(/\+/g, " "))];
+      })
+    : [];
+  const parts = [...segments, ...query.map(([, value]) => value)];
+  if (parts.filter((value) => "capture" in value && value.capture === "id").length !== 1)
+    throw new Error("A page pattern must contain exactly one :id capture");
+  return { segments, query };
+};
+
+/** Validates syntax and ownership; prefixes use the gateway's literal segment boundary. */
+export const resourcePageIssue = (path: string, prefixes?: readonly string[], appId?: string): string | null => {
+  try {
+    const pattern = parsePattern(path);
+    const namespace = pattern.segments[0];
+    const owner = pattern.segments[1];
+    if (
+      appId &&
+      namespace &&
+      "literal" in namespace &&
+      namespace.literal === "app" &&
+      (!owner || !("literal" in owner) || owner.literal !== appId)
+    )
+      return "Only app <id> may declare pages below /app/<id>";
+    if (
+      prefixes &&
+      !prefixes.some((prefix) => {
+        if (prefix === "/") return true;
+        if (!prefix.startsWith("/") || /[?#%\\:]/.test(prefix)) return false;
+        const segments = prefix.replace(/\/$/, "").slice(1).split("/");
+        return segments.every((value, index) => {
+          const segment = pattern.segments[index];
+          return segment && "literal" in segment && segment.literal === value;
+        });
+      })
+    )
+      return "Page pattern must lie under an application's declared route prefix";
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error.message : "Invalid page pattern";
+  }
+};
+
+export type CloudResourcePage = { type: string; path: string; prefixes: readonly string[] };
+
+/** Required query keys outrank literal path segments. Equal best scores for different refs are ambiguous. */
+export const matchCloudResourcePage = (path: string, pages: readonly CloudResourcePage[]): CloudResourceRef | null => {
+  if (!path.startsWith("/") || path.startsWith("//") || path.length > RESOURCE_URL_MAX_LENGTH || /[\s\\]/.test(path)) return null;
+  try {
+    const url = new URL(path, "https://cloud.invalid");
+    const route = url.pathname.replace(/\/$/, "").slice(1);
+    const segments = route ? route.split("/").map(decode) : [];
+    // URLSearchParams silently repairs malformed escapes: validate before reading it.
+    decode(url.search.replace(/\+/g, " "));
+    if (segments.some((value) => !value)) return null;
+    let best: { ref: CloudResourceRef; queries: number; literals: number } | undefined;
+    let ambiguous = false;
+    for (const page of pages) {
+      if (resourcePageIssue(page.path, page.prefixes, page.type.split(".")[0])) continue;
+      const pattern = parsePattern(page.path);
+      if (segments.length !== pattern.segments.length) continue;
+      let id: string | undefined;
+      const matches = (part: Part, value: string | undefined): boolean => {
+        if (!value) return false;
+        if ("literal" in part) return part.literal === value;
+        if (part.capture === "id") id = value;
+        return true;
+      };
+      if (!pattern.segments.every((part, index) => matches(part, segments[index]))) continue;
+      if (
+        !pattern.query.every(([key, part]) => {
+          const values = url.searchParams.getAll(key);
+          return values.length === 1 && matches(part, values[0]);
+        }) ||
+        !id
+      )
+        continue;
+      const ref = { type: page.type, id };
+      const queries = pattern.query.length;
+      const literals = pattern.segments.filter((part) => "literal" in part).length;
+      if (!best || queries > best.queries || (queries === best.queries && literals > best.literals)) {
+        best = { ref, queries, literals };
+        ambiguous = false;
+      } else if (queries === best.queries && literals === best.literals && (ref.type !== best.ref.type || ref.id !== best.ref.id)) {
+        ambiguous = true;
+      }
+    }
+    return best && !ambiguous ? best.ref : null;
+  } catch {
+    return null;
+  }
+};
+
+/** No network activity: accept one local URL token and reject origin tricks before catalog lookup. */
+export const localCloudResourceUrl = (text: string, origin: string | null): URL | null => {
+  if (!text || text.length > RESOURCE_URL_MAX_LENGTH || /[\s\\\u0000-\u001f]/.test(text) || text.startsWith("//")) return null;
+  try {
+    const relative = text.startsWith("/");
+    const url = relative ? new URL(text, origin ?? "https://cloud.invalid") : new URL(text);
+    if (!/^https?:$/.test(url.protocol) || url.username || url.password || (!relative && (!origin || url.origin !== origin))) return null;
+    return url;
+  } catch {
+    return null;
+  }
+};

package/src/contracts/resource-resolution.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { CloudResourceHrefSchema, CloudResourceRefSchema } from "./capabilities";
+
+export const ResolvedCloudResourceUrlSchema = z
+  .object({
+    ref: CloudResourceRefSchema,
+    title: z.string().min(1).max(500),
+    icon: z.string().min(1).max(120).optional(),
+    href: CloudResourceHrefSchema,
+  })
+  .strict();
+
+export type ResolvedCloudResourceUrl = z.infer<typeof ResolvedCloudResourceUrlSchema>;

package/src/contracts/shared.ts

@@ -392,6 +392,8 @@ export type SettingOption = {
 export type SettingValueSource = "custom" | "env" | "default";
 
 export type SettingEntry = {
+  updatedAt?: string | null;
+  updatedBy?: { id: string; name: string } | null;
   key: string;
   label: string;
   kind: SettingKind;
@@ -443,6 +445,8 @@ export type ServiceAccountRequestActor = {
   delegatedUser: User | null;
   scopes: string[];
   credentialId?: string | null;
+  /** Public OAuth client identifier, never the bearer token. */
+  oauthClientId?: string | null;
   credentialExpiresAt?: string | null;
   delegation?: InvocationProvenance;
 };

package/src/contracts/user-notifications.ts

@@ -12,6 +12,8 @@ export const UserNotificationPreferenceSchema = z.object({
   description: z.string(),
   recommendedChannels: z.array(z.string()),
   requiredChannels: z.array(z.string()),
+  excludedChannels: z.array(z.string()),
+  excludedReason: z.string().nullable(),
   selectedChannels: z.array(z.string()),
   effectiveChannels: z.array(z.string()),
   customized: z.boolean(),

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

@@ -0,0 +1,100 @@
+import type { Topic, TopicConfig } from "@k2b/sync";
+import { sql } from "bun";
+import { assertAppEventSize } from "../_internal/app-event-schemas";
+import { lazySync } from "../_internal/process-sync";
+import { type AppEventEnvelope, AppEventEnvelopeSchema } from "../contracts/app-events";
+import { logger } from "../services/logging";
+import { createPgOutbox } from "../services/outbox";
+
+/**
+ * Frozen shared stream. It only buffers events until Core has stored them, and
+ * JetStream reserves `maxBytes` on every replica: 256 MiB hold 52,428 envelopes
+ * at the 4096-byte limit plus a 1024-byte transport allowance. The shared
+ * producer budget and thin-envelope outage scenarios are in operations/app-events.
+ * Retention passing unseen events becomes a visible gap.
+ */
+export const appEventTopicConfig = () =>
+  ({
+    id: "cloud:app-events",
+    owner: "cloud",
+    retention: { maxAgeMs: 7 * 24 * 3_600_000, maxBytes: 256 * 1024 ** 2 },
+    maxPayloadBytes: 8 * 1024,
+    deadLetterRetention: { maxBytes: 1024 ** 2 },
+  }) satisfies TopicConfig;
+
+const topic = lazySync((sync) => sync.topic<AppEventEnvelope>(appEventTopicConfig()));
+export const appEventTopic = (): Topic<AppEventEnvelope> => topic();
+
+export type AppEventOutboxRow = {
+  id: string;
+  app_id: string;
+  created_at: Date | string;
+  attempts: number;
+  ordering_key: string;
+  payload: AppEventEnvelope;
+};
+
+/** The committed row owns identity, source and timestamp, including for SQL writers. */
+export const appEventFromOutbox = (row: AppEventOutboxRow): AppEventEnvelope => {
+  const envelope = AppEventEnvelopeSchema.parse({
+    ...row.payload,
+    id: row.id,
+    source: row.app_id,
+    time: new Date(row.created_at).toISOString(),
+  });
+  assertAppEventSize(envelope);
+  return envelope;
+};
+
+export const appEventOutbox = (appId: string, publish: (row: AppEventOutboxRow) => Promise<unknown>) =>
+  createPgOutbox<AppEventOutboxRow>({
+    table: "events.outbox",
+    name: `events:app:${appId}`,
+    where: { kind: "event", app_id: appId },
+    orderBy: "ordering_key",
+    sequence: "seq",
+    reconcileIntervalMs: 1_000,
+    publish,
+  });
+
+const dispatchers = new Map<string, (() => void) | null>();
+export const registerAppEventPublisher = (appId: string): void => {
+  if (!dispatchers.has(appId)) dispatchers.set(appId, null);
+};
+export const wakeAppEventDelivery = (appId: string): void => dispatchers.get(appId)?.();
+
+export const startAppEventDelivery = async (appId: string): Promise<(() => Promise<void>) | null> => {
+  if (!dispatchers.has(appId)) return null;
+  const [installed] = await sql<{ ready: boolean }[]>`
+    SELECT to_regprocedure('events.enqueue(uuid,text,text,text,jsonb,text)') IS NOT NULL AS ready
+  `;
+  if (!installed?.ready) throw new Error(`"${appId}" publishes app events: update Cloud Core first to install events.outbox`);
+  const destination = appEventTopic();
+  const outbox = appEventOutbox(appId, (row) =>
+    destination.publish({
+      data: appEventFromOutbox(row),
+      orderingKey: row.ordering_key,
+      idempotencyKey: row.id,
+    }),
+  );
+  outbox.start();
+  dispatchers.set(appId, () => void outbox.notify());
+  const log = logger("events:app");
+  const staleCheck = setInterval(() => {
+    sql<
+      { count: number }[]
+    >`SELECT COUNT(*)::int AS count FROM events.outbox WHERE kind = 'event' AND app_id = ${appId} AND created_at < now() - interval '60 seconds'`
+      .then(([row]) => {
+        if (row && row.count > 0) log.warn("App events wait to be published", { appId, count: row.count });
+      })
+      .catch((error: unknown) =>
+        log.warn("App event outbox check failed", { appId, error: error instanceof Error ? error.message : String(error) }),
+      );
+  }, 60_000);
+  staleCheck.unref();
+  return async () => {
+    clearInterval(staleCheck);
+    dispatchers.set(appId, null);
+    await outbox.stop();
+  };
+};

package/src/events/app-events.testing.ts

@@ -0,0 +1,65 @@
+import {
+  type AppEventDeliveryContext,
+  type AppEventEnvelope,
+  AppEventEnvelopeSchema,
+  appEventSubscriptionId,
+} from "../contracts/app-events";
+import type { CapabilityDefinitions } from "../contracts/capabilities";
+import {
+  type AppEventPublishInput,
+  appEventBinding,
+  bindAppEvents,
+  buildAppEventEnvelope,
+  deliverAppEvent as deliverCompiledAppEvent,
+} from "./app-events";
+
+type EventKey<T extends CapabilityDefinitions> = Extract<keyof NonNullable<T["events"]>, string>;
+
+/** Producer fixture, validated exactly like publish. A standalone test may supply its app ID explicitly. */
+export const appEventFixture = <const T extends CapabilityDefinitions, Key extends EventKey<T>>(
+  capabilities: T,
+  localName: Key,
+  input: AppEventPublishInput<T, Key>,
+  options: { id?: string; time?: string; appId?: string } = {},
+): AppEventEnvelope => {
+  if (options.appId !== undefined) bindAppEvents(options.appId, capabilities);
+  return buildAppEventEnvelope(capabilities, localName, input, {
+    id: options.id ?? "00000000-0000-4000-8000-000000000001",
+    time: options.time ?? "2026-01-01T00:00:00.000Z",
+  });
+};
+
+/** Exercises the framework's real delivery validation and the declared subscriber. */
+export const deliverAppEvent = async (
+  capabilities: CapabilityDefinitions,
+  eventType: string,
+  envelope: unknown,
+  context: Partial<AppEventDeliveryContext> & { appId?: string } = {},
+): Promise<void> => {
+  if (context.appId !== undefined) bindAppEvents(context.appId, capabilities);
+  const { appId, compiled } = appEventBinding(capabilities);
+  const parsed = AppEventEnvelopeSchema.parse(envelope);
+  if (parsed.type !== eventType) throw new Error("App event type does not match the tested subscription");
+  const subscriptionId = appEventSubscriptionId(appId, eventType, parsed.version);
+  await deliverCompiledAppEvent({
+    compiled,
+    subscriptionId,
+    envelope,
+    context: {
+      subscriptionId: context.subscriptionId ?? subscriptionId,
+      eventId: context.eventId ?? parsed.id,
+      attempt: context.attempt ?? 1,
+      signal: context.signal ?? new AbortController().signal,
+    },
+  });
+};
+
+/** Explicit app ID for standalone declarations that have no defineApp binding. */
+export const createAppEventTestHarness = (appId: string, capabilities: CapabilityDefinitions) => {
+  bindAppEvents(appId, capabilities);
+  return {
+    manifest: appEventBinding(capabilities).compiled.manifest,
+    deliver: (envelope: AppEventEnvelope, context: Partial<AppEventDeliveryContext> = {}): Promise<void> =>
+      deliverAppEvent(capabilities, envelope.type, envelope, context),
+  };
+};

package/src/events/app-events.ts

@@ -0,0 +1,134 @@
+import { isDeepStrictEqual } from "node:util";
+import type { SQL } from "bun";
+import { z } from "zod";
+import { assertAppEventSize } from "../_internal/app-event-schemas";
+import { type CompiledCapabilities, compileCapabilities } from "../_internal/capabilities";
+import { capabilityHash } from "../_internal/capability-schemas";
+import {
+  type AppEventDeliveryContext,
+  type AppEventEnvelope,
+  AppEventEnvelopeSchema,
+  appEventSubscriptionId,
+} from "../contracts/app-events";
+import { CapabilityAppIdSchema, type CapabilityDefinitions } from "../contracts/capabilities";
+import { registerAppEventPublisher, wakeAppEventDelivery } from "./app-event-delivery";
+
+type EventBinding = { appId: string; compiled: CompiledCapabilities };
+const bindings = new WeakMap<CapabilityDefinitions, EventBinding>();
+const bindingsByApp = new Map<string, EventBinding>();
+
+/** Framework hook: bind the exact declaration object when defineApp assigns its app ID. */
+export const bindAppEvents = (appId: string, definitions: CapabilityDefinitions, compiledInput?: CompiledCapabilities): void => {
+  CapabilityAppIdSchema.parse(appId);
+  const prior = bindings.get(definitions);
+  if (prior && prior.appId !== appId) throw new Error(`Capabilities are already bound to ${prior.appId}`);
+  const compiled = compiledInput ?? prior?.compiled ?? compileCapabilities(appId, definitions);
+  const binding = { appId, compiled };
+  bindings.set(definitions, binding);
+  bindingsByApp.set(appId, binding);
+  if (compiled.events.size > 0) registerAppEventPublisher(appId);
+};
+
+export const appEventBinding = (definitions: CapabilityDefinitions | string) => {
+  const binding = typeof definitions === "string" ? bindingsByApp.get(definitions) : bindings.get(definitions);
+  if (!binding)
+    throw new Error("Bind event capabilities with defineApp before publishing or testing; a test harness accepts an explicit appId");
+  return binding;
+};
+
+type EventDeclarations<T extends CapabilityDefinitions> = NonNullable<T["events"]>;
+export type AppEventPublishInput<T extends CapabilityDefinitions, Key extends keyof EventDeclarations<T>> = {
+  subject: string;
+  data: z.input<EventDeclarations<T>[Key]["schema"]>;
+  requestId?: string;
+} & (EventDeclarations<T>[Key] extends { place: string } ? { place: string } : { place?: never });
+
+/** The same declaration, JSON and byte validation for publishers and producer fixtures. */
+export const buildAppEventEnvelope = <const T extends CapabilityDefinitions, Key extends Extract<keyof EventDeclarations<T>, string>>(
+  definitions: T | string,
+  localId: Key,
+  input: AppEventPublishInput<T, Key>,
+  identity: { id: string; time: string },
+): AppEventEnvelope => {
+  const binding = appEventBinding(definitions);
+  const event = binding.compiled.events.get(localId);
+  if (!event) throw new Error(`Unknown app event ${localId}`);
+  if ((event.manifest.place !== undefined) !== (input.place !== undefined)) {
+    throw new Error(`Event ${localId} place does not match its declaration`);
+  }
+  const data = z.json().parse(input.data);
+  if (!isDeepStrictEqual(input.data, JSON.parse(JSON.stringify(data)))) {
+    throw new Error("Event data must round-trip through JSON without normalization");
+  }
+  const parsed = event.definition.schema.parse(data);
+  if (capabilityHash(parsed) !== capabilityHash(data)) throw new Error("Event schema must preserve the original JSON data");
+  const envelope = AppEventEnvelopeSchema.parse({
+    ...identity,
+    type: `${binding.appId}.${localId}`,
+    version: event.manifest.version,
+    source: binding.appId,
+    subject: { type: `${binding.appId}.${event.manifest.subject}`, id: input.subject },
+    ...(event.manifest.place !== undefined ? { place: { type: `${binding.appId}.${event.manifest.place}`, id: input.place } } : {}),
+    ...(input.requestId !== undefined ? { cause: { requestId: input.requestId } } : {}),
+    data,
+  });
+  assertAppEventSize(envelope);
+  return envelope;
+};
+
+/** Writes in the domain transaction; wake only after commit. Delivery is at least once. */
+export const appEvents = <const T extends CapabilityDefinitions>(definitions: T | string) => ({
+  publish: async <Key extends Extract<keyof EventDeclarations<T>, string>>(
+    tx: SQL,
+    localId: Key,
+    input: AppEventPublishInput<T, Key>,
+  ): Promise<AppEventEnvelope> => {
+    const envelope = buildAppEventEnvelope<T, Key>(definitions, localId, input, {
+      id: crypto.randomUUID(),
+      time: new Date().toISOString(),
+    });
+    // A full valid resource ref can exceed the existing outbox's 600-character key bound.
+    const orderingKey = capabilityHash(envelope.subject);
+    await tx`SELECT events.enqueue(${envelope.id}::uuid, ${envelope.source}, 'event', ${orderingKey}, ${JSON.stringify(envelope)}::text::jsonb)`;
+    return envelope;
+  },
+  wake: (): void => {
+    const binding = typeof definitions === "string" ? bindingsByApp.get(definitions) : bindings.get(definitions);
+    if (binding) wakeAppEventDelivery(binding.appId);
+  },
+});
+
+/** Shared by the framework route and subscription tests; validates before executing application code. */
+export const deliverAppEvent = async (params: {
+  compiled: CompiledCapabilities;
+  subscriptionId: string;
+  envelope: unknown;
+  context: AppEventDeliveryContext;
+}): Promise<void> => {
+  const envelope = AppEventEnvelopeSchema.parse(params.envelope);
+  assertAppEventSize(envelope);
+  if (
+    !envelope.type.startsWith(`${envelope.source}.`) ||
+    !envelope.subject.type.startsWith(`${envelope.source}.`) ||
+    (envelope.place && !envelope.place.type.startsWith(`${envelope.source}.`))
+  )
+    throw new Error("App event source does not match its namespaced types");
+  if (envelope.place) throw new Error("resource_events_unsupported");
+  const subscription = params.compiled.subscribes.get(envelope.type);
+  if (!subscription || subscription.manifest.version !== envelope.version) {
+    throw new Error("App event subscription not found for type and version");
+  }
+  if (params.subscriptionId !== appEventSubscriptionId(params.compiled.manifest.appId, envelope.type, envelope.version)) {
+    throw new Error("App event subscription ID mismatch");
+  }
+  if (
+    params.context.subscriptionId !== params.subscriptionId ||
+    params.context.eventId !== envelope.id ||
+    !Number.isSafeInteger(params.context.attempt) ||
+    params.context.attempt < 1
+  )
+    throw new Error("App event delivery context mismatch");
+  params.context.signal.throwIfAborted();
+  const data = subscription.definition.schema.parse(envelope.data);
+  await subscription.definition.run({ ...envelope, data }, params.context);
+};

package/src/events/core-user-created.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { defineCapabilities } from "../contracts/capabilities";
+import { appEvents, bindAppEvents } from "./app-events";
+
+export const coreUserEventTypes = {
+  user: { title: "User", description: "A Cloud user identity.", icon: "ti ti-user" },
+} as const;
+export const coreUserEvents = {
+  "user.created": {
+    version: 1,
+    title: "User created",
+    description: "A user identity was first created in Cloud.",
+    subject: "user",
+    schema: z.object({ userId: z.uuid(), provider: z.enum(["local", "ipa"]) }).strict(),
+  },
+} as const;
+const declarations = defineCapabilities({ protocolVersion: 2, types: coreUserEventTypes, events: coreUserEvents });
+const publisher = appEvents(declarations);
+
+/** Creation services explicitly bind Core's shared event declarations before publishing. */
+export const coreUserEventPublisher = () => {
+  bindAppEvents("core", declarations);
+  return publisher;
+};

package/src/events/index.ts

@@ -1,2 +1,11 @@
+export type {
+  AppEventDefinition,
+  AppEventDeliveryContext,
+  AppEventEnvelope,
+  AppEventSubscriptionDefinition,
+} from "../contracts/app-events";
+export { APP_EVENT_MAX_BYTES, AppEventEnvelopeSchema, appEventSubscriptionId } from "../contracts/app-events";
+
+export { appEvents } from "./app-events";
 export type { LiveChannel, LiveViewer } from "./live";
 export { defineLive } from "./live";

package/src/events/testing.ts

@@ -1,6 +1,8 @@
 import { CursorMismatchError, RetentionGapError, type TopicEvent } from "@k2b/sync";
 import type { LiveEnvelope, LiveTopic } from "./live-engine";
 
+export { appEventFixture, createAppEventTestHarness, deliverAppEvent } from "./app-events.testing";
+
 /** Publishes an application's real outbox without starting its application. */
 export { startLiveOutbox } from "./live";
 export {

package/src/index.ts

@@ -36,7 +36,7 @@ export type { RuntimeCompatibilityIssue } from "./_internal/runtime-compatibilit
 export { assessRuntimeCompatibility } from "./_internal/runtime-compatibility";
 export { buildRuntimeFromRegistry } from "./_internal/runtime-context";
 export { type AppSkillDefinition, skill } from "./ai/app-skills";
-export type { AppAccessDeclaration, AppAccessRule, FixedAppAccessRule } from "./contracts/app-access";
+export type { AppAccessDeclaration, AppAccessRule, FixedAppAccessRule, ResourceAppAccessAdapter } from "./contracts/app-access";
 export { appAccess } from "./contracts/app-access";
 export { defineCapabilities } from "./contracts/capabilities";
 export type { AppInstallable } from "./contracts/installable";

package/src/server/api/respond.ts

@@ -43,6 +43,11 @@ const toErrorResponse = (result: AnyResult): [ApiErrorBody, number] => {
   return [{ message: "Internal server error", code: "INTERNAL" }, 500];
 };
 
+export async function respond<T>(
+  c: Context,
+  resultOrFn: ResultOrFn<AnyResult<T>>,
+  successStatus: 202,
+): Promise<JsonTypedResponse<T, 202> | ApiErrorResponse>;
 export async function respond<E extends ServiceError>(
   c: Context,
   resultOrFn: ResultOrFn<Result<never, E>>,
@@ -71,8 +76,8 @@ export async function respond<T>(
 export async function respond<T>(
   c: Context,
   resultOrFn: ResultOrFn<AnyResult<T>>,
-  successStatus: SuccessStatus = 200,
-): Promise<JsonTypedResponse<T, SuccessStatus> | ApiErrorResponse> {
+  successStatus: SuccessStatus | 202 = 200,
+): Promise<JsonTypedResponse<T, SuccessStatus | 202> | ApiErrorResponse> {
   const result = typeof resultOrFn === "function" ? await resultOrFn() : await resultOrFn;
 
   if (!result.ok) {
@@ -80,7 +85,7 @@ export async function respond<T>(
     return c.json(body, status as ApiErrorStatus) as ApiErrorResponse;
   }
 
-  return c.json(result.data, successStatus as 200 | 201) as JsonTypedResponse<T, SuccessStatus>;
+  return c.json(result.data, successStatus) as JsonTypedResponse<T, SuccessStatus | 202>;
 }
 
 export const respondMessage = (c: Context, resultPromise: Promise<Result<void>>, message: string) =>

package/src/server/index.ts

@@ -26,6 +26,7 @@ export type {
 export {
   auth,
   imageResponse,
+  isRequestCredentialCurrent,
   jsonResponse,
   middleware,
   openApiMeta,

package/src/server/middleware/app-access.ts

@@ -22,7 +22,7 @@ export const stopAppAccessConnections = (): void => {
 export const appAccessDeniedBody = (app: AccessApp) => ({
   code: "app_access_denied" as const,
   app: app.id,
-  message: `You cannot use ${app.name ?? app.id}. ${app.access?.kind === "grants" ? "Ask someone who manages access to this app." : "Ask your Cloud administrator about access."}`,
+  message: `You cannot use ${app.name ?? app.id}. ${app.access?.kind === "grants" ? "Ask someone who manages access to this app." : app.access?.kind === "resources" ? "Ask someone who manages resource permissions in this app." : "Ask your Cloud administrator about access."}`,
 });
 
 export class AppAccessDeniedError extends Error {