@k2b/cloud 0.42.0 → 0.44.0

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,9 +36,10 @@ 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";
 export type {
   AnyBoundNotificationDefinition,
   BoundNotificationDefinition,

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

@@ -8,7 +8,7 @@ import type { AppMeta } from "../../contracts/app";
 import { appAccessAuthority, canUseApp } from "../../services/app-access";
 import { recordAppAccessDenied } from "../../services/app-access-metrics";
 import { createLoginRedirectUrl } from "../../shared/redirect";
-import { type AuthContext, auth, type RequestAuthority } from "./auth";
+import { type AuthContext, auth, loadAuthenticatedActor, type RequestAuthority } from "./auth";
 
 type AccessApp = Pick<AppMeta, "id" | "access"> & { name?: string };
 export const APP_ACCESS_RECHECK_MS = 50_000;
@@ -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 {
@@ -280,10 +280,10 @@ export const requireAppAccess = (
   const isPublic = appPublicRouteMatcher(app);
   return createMiddleware<AuthContext>(async (c, next) => {
     if (!app.access || isPublic(c.req.path)) return next();
-    let resolved: RequestAuthority | null = null;
-    await auth.requireRole("*")(c, async () => {
-      resolved = appAccessAuthority(c);
-    });
+    // The framework checks application entry before the app router is matched.
+    // Route-level OAuth policy belongs to the app authentication middleware.
+    await loadAuthenticatedActor(c);
+    const resolved = appAccessAuthority(c);
     const browser =
       c.req.method === "GET" && c.req.header("accept")?.includes("text/html") && c.req.header("upgrade")?.toLowerCase() !== "websocket";
     if (!resolved) {
@@ -304,6 +304,7 @@ export const requireAppAccess = (
       const body = appAccessDeniedBody(app);
       const response = browser ? await renderDenied(c, body.message) : c.json(body, 403);
       response.headers.set("Cache-Control", "private, no-store");
+      response.headers.set("X-Cloud-App-Access-Denied", app.id);
       return response;
     }
     await next();

package/src/server/middleware/auth.ts

@@ -1,5 +1,8 @@
-import type { Context } from "hono";
+import type { Context, Env, MiddlewareHandler } from "hono";
 import { createMiddleware } from "hono/factory";
+import { matchedRoutes } from "hono/route";
+import { findTargetHandler } from "hono/utils/handler";
+import { bindAppAccessRequest } from "../../_internal/app-access-request";
 import { measureServerPhase } from "../../_internal/server-timing";
 import {
   AI_INFERENCE_SCOPE,
@@ -29,6 +32,7 @@ export type InvocationProvenance = {
   callingAppId: string;
   credentialKind: "session" | "oauth" | "api_key" | "mandate";
   invocationId: string;
+  parentInvocationId?: string;
   requestId?: string | null;
   mandateId?: string;
   mandateRevision?: number;
@@ -55,6 +59,8 @@ export type ServiceAccountRequestActor =
       delegatedUser: User;
       scopes: string[];
       credentialId?: string | null;
+      /** Public OAuth client identifier; safe to retain, never the bearer token. */
+      oauthClientId?: string | null;
       credentialExpiresAt?: string | null;
       delegation?: InvocationProvenance;
     }
@@ -64,6 +70,8 @@ export type ServiceAccountRequestActor =
       delegatedUser: null;
       scopes: string[];
       credentialId?: string | null;
+      /** Public OAuth client identifier; safe to retain, never the bearer token. */
+      oauthClientId?: string | null;
       credentialExpiresAt?: string | null;
       delegation?: InvocationProvenance;
     };
@@ -72,7 +80,14 @@ export type RequestActor = UserRequestActor | ServiceAccountRequestActor;
 
 export type RequestCredentialKind = "session" | "oauth" | "api_key" | "invocation";
 
+/** Core keeps only revocation coordinates, never the original bearer credential. */
+export type RequestCredentialProof =
+  | { kind: "session"; userId: string; sid: string; authEpoch: number; expiresAt: string }
+  | { kind: "oauth"; payload: import("jose").JWTPayload }
+  | { kind: "api_key"; credentialId: string };
+
 export type RequestAuthority = {
+  credentialProof?: RequestCredentialProof;
   actor: RequestActor;
   accessSubject: AccessSubject;
   credentialKind: RequestCredentialKind;
@@ -92,6 +107,7 @@ export type AuthContext = {
     sessionKind?: SessionKind;
     /** Constraints carried by OAuth/API credentials; absent sessions are unrestricted by transport scope. */
     credentialScopes?: string[];
+    credentialProof?: RequestCredentialProof;
     /** OAuth scopes for bearer-token requests. Absent for sessions and API credentials. */
     oauthScopes?: string[];
   };
@@ -159,6 +175,13 @@ const loadAuthenticatedActorUncached = async (
     c.set("sessionToken", token);
     c.set("credentialKind", "session");
     c.set("sessionKind", authenticatedSession.data.kind);
+    c.set("credentialProof", {
+      kind: "session",
+      userId: user.id,
+      sid: authenticatedSession.data.sid,
+      authEpoch: authenticatedSession.data.authEpoch,
+      expiresAt: authenticatedSession.data.expiresAt,
+    });
     return { token, user, actor };
   }
 
@@ -185,6 +208,7 @@ const loadAuthenticatedActorUncached = async (
     };
     c.set("actor", actor);
     c.set("credentialKind", "api_key");
+    c.set("credentialProof", { kind: "api_key", credentialId: authResult.credential.id });
     c.set("credentialScopes", authResult.credential.scopes);
     if (authResult.delegatedUser) {
       c.set("accessSubject", { type: "user", userId: authResult.delegatedUser.id });
@@ -200,6 +224,14 @@ const loadAuthenticatedActorUncached = async (
     const authResult = await oauthTokens.verifyAccessToken(bearer, expectedAudience);
     if (!authResult) return { token: null, user: null, actor: null };
 
+    c.set("credentialProof", {
+      kind: "oauth",
+      payload: Object.fromEntries(
+        ["sub", "id", "uid", "client_id", "auth_epoch", "service_account_id", "scope", "exp"].flatMap((key) =>
+          authResult.payload[key] === undefined ? [] : [[key, authResult.payload[key]]],
+        ),
+      ),
+    });
     if (authResult.kind === "user") {
       if (isAccountExpired(authResult.user.accountExpires)) return { token: null, user: null, actor: null };
       const actor: RequestActor = { kind: "user", user: authResult.user };
@@ -221,6 +253,7 @@ const loadAuthenticatedActorUncached = async (
       delegatedUser: authResult.delegatedUser,
       scopes: authResult.scopes,
       credentialId: null,
+      oauthClientId: authResult.oauthClientId,
       credentialExpiresAt: typeof authResult.payload.exp === "number" ? new Date(authResult.payload.exp * 1_000).toISOString() : null,
     };
     c.set("actor", actor);
@@ -239,7 +272,7 @@ const loadAuthenticatedActorUncached = async (
   return { token: null, user: null, actor: null };
 };
 
-const loadAuthenticatedActor = (
+export const loadAuthenticatedActor = (
   c: Context<AuthContext>,
   options: Pick<RoleOptions, "oauthAudience"> = {},
 ): Promise<AuthenticatedActorResult> => {
@@ -289,8 +322,24 @@ export const isRequestCredentialCurrent = async (
   return false;
 };
 
+const readOnlyMiddlewares = new WeakSet<object>();
+
+/**
+ * Declare middleware that only authenticates, authorizes, validates or reads.
+ * A read-only route cannot exempt another unmarked ALL handler: Hono uses
+ * ALL for both `.use()` middleware and terminal `.all()` routes.
+ * This declaration never exempts an endpoint from the default write requirement.
+ */
+const readOnlyMiddleware = <E extends Env = AuthContext>(handler: MiddlewareHandler<E>): MiddlewareHandler<E> => {
+  readOnlyMiddlewares.add(handler);
+  return handler;
+};
+
 /**
  * Universal auth middleware. Handles authentication AND authorization.
+ * OAuth requests require `write` or `admin` scope for methods other than GET,
+ * HEAD and OPTIONS, unless the route explicitly declares `auth.readOnly`.
+ * Browser sessions and personal API keys keep their existing authority.
  *
  * @param args - Roles to check (OR logic) + optional RoleOptions at the end. Special roles:
  *   - "*": No check, always passes (like optionalAuth)
@@ -320,45 +369,49 @@ const requireRole = (...args: (RoleOrSpecial | RoleOptions)[]) => {
   const options: RoleOptions = hasOptions ? (args.pop() as RoleOptions) : {};
   const roles = args as RoleOrSpecial[];
 
-  return createMiddleware<AuthContext>(async (c, next) => {
-    // "*" = no check at all, pass through (but try to load user)
-    if (roles.includes("*")) {
-      await loadAuthenticatedActor(c, options);
-      return next();
-    }
+  return readOnlyMiddleware(
+    createMiddleware<AuthContext>(async (c, next) => {
+      const continueRequest = () => requireOAuthMutationScope(c, next);
 
-    const { user, actor } = await loadAuthenticatedActor(c, options);
+      // "*" skips role checks but still resolves any credential and its scopes.
+      if (roles.includes("*")) {
+        await loadAuthenticatedActor(c, options);
+        return continueRequest();
+      }
 
-    // "anonymous" = must NOT be logged in
-    if (roles.includes("anonymous")) {
-      if (actor) {
-        return handleReject(c, options, "forbidden");
+      const { user, actor } = await loadAuthenticatedActor(c, options);
+
+      // "anonymous" = must NOT be logged in
+      if (roles.includes("anonymous")) {
+        if (actor) {
+          return handleReject(c, options, "forbidden");
+        }
+        return continueRequest();
       }
-      return next();
-    }
 
-    // All other roles require authentication
-    if (!actor) {
-      return handleReject(c, options, "unauthenticated");
-    }
+      // All other roles require authentication
+      if (!actor) {
+        return handleReject(c, options, "unauthenticated");
+      }
 
-    // "authenticated" = any logged-in user
-    if (roles.includes("authenticated")) {
-      return next();
-    }
+      // "authenticated" = any logged-in user
+      if (roles.includes("authenticated")) {
+        return continueRequest();
+      }
 
-    if (!user) {
-      return handleReject(c, options, "forbidden");
-    }
+      if (!user) {
+        return handleReject(c, options, "forbidden");
+      }
 
-    // Check if user has at least one required role
-    const hasRequiredRole = roles.some((role) => user.roles.includes(role as Role));
-    if (!hasRequiredRole) {
-      return handleReject(c, options, "forbidden");
-    }
+      // Check if user has at least one required role
+      const hasRequiredRole = roles.some((role) => user.roles.includes(role as Role));
+      if (!hasRequiredRole) {
+        return handleReject(c, options, "forbidden");
+      }
 
-    return next();
-  });
+      return continueRequest();
+    }),
+  );
 };
 
 /**
@@ -376,35 +429,80 @@ const requireRole = (...args: (RoleOrSpecial | RoleOptions)[]) => {
  * turns into further down.
  */
 const requireUser = (options: RoleOptions = {}) =>
-  createMiddleware<AuthContext>(async (c, next) => {
-    const { user } = await loadAuthenticatedActor(c);
-    if (user) return next();
-    // A caller that reaches here is authenticated but has no user, so the
-    // generic "Insufficient permissions" would send them looking for a missing
-    // role. `onReject` still wins, which is what keeps SSR redirects working.
-    if (options.onReject) return handleReject(c, options, "forbidden");
-    return c.json({ message: "Self-service endpoints require a user-backed actor", code: "FORBIDDEN" }, 403);
-  });
+  readOnlyMiddleware(
+    createMiddleware<AuthContext>(async (c, next) => {
+      const { user } = await loadAuthenticatedActor(c);
+      if (user) return requireOAuthMutationScope(c, next);
+      // A caller that reaches here is authenticated but has no user, so the
+      // generic "Insufficient permissions" would send them looking for a missing
+      // role. `onReject` still wins, which is what keeps SSR redirects working.
+      if (options.onReject) return handleReject(c, options, "forbidden");
+      return c.json({ message: "Self-service endpoints require a user-backed actor", code: "FORBIDDEN" }, 403);
+    }),
+  );
 
 /** Require one OAuth scope when the caller uses OAuth. Sessions and API credentials are unaffected. */
 const requireOAuthScope = (...requiredScopes: string[]) =>
-  createMiddleware<AuthContext>(async (c, next) => {
-    const scopes = c.get("oauthScopes");
-    if (!scopes || requiredScopes.some((scope) => scopes.includes(scope))) return next();
-    return c.json({ code: "FORBIDDEN", message: `OAuth scope ${requiredScopes.join(" or ")} is required` }, 403);
-  });
+  readOnlyMiddleware(
+    createMiddleware<AuthContext>(async (c, next) => {
+      const scopes = c.get("oauthScopes");
+      if (!scopes || requiredScopes.some((scope) => scopes.includes(scope))) return next();
+      return c.json({ code: "FORBIDDEN", message: `OAuth scope ${requiredScopes.join(" or ")} is required` }, 403);
+    }),
+  );
+
+/**
+ * Explicitly declare a read-only POST route. Register on the route itself,
+ * as its first handler, never with `.use()`: authentication can see the declaration before it runs.
+ * This does not replace resource authorization or make a handler read-only.
+ */
+const readOnly = requireOAuthScope("read", "admin");
+
+/** Internal protocol dispatchers check scope against the resolved operation. */
+export const oauthScopeByOperation = createMiddleware<AuthContext>(async (_c, next) => next());
+
+export const requireOAuthMutationScope = createMiddleware<AuthContext>(async (c, next) => {
+  if (["GET", "HEAD", "OPTIONS"].includes(c.req.method)) return next();
+  // Only an explicit method registration can relax the default. A declaration
+  // accidentally mounted with `.use()` or on a wildcard cannot exempt a subtree.
+  const matched = matchedRoutes(c);
+  const lastMethod = matched.findLastIndex((route) => route.method !== "ALL");
+  const unguardedAllHandler = matched
+    .slice(c.req.routeIndex + 1, lastMethod)
+    .some((route) => route.method === "ALL" && !readOnlyMiddlewares.has(findTargetHandler(route.handler)));
+  const routes = matched.filter((route) => route.method !== "ALL");
+  const first = routes[0];
+  const handler = first && findTargetHandler(first.handler);
+  const declared =
+    !unguardedAllHandler &&
+    first?.method === c.req.method &&
+    !first.path.includes("*") &&
+    (handler === readOnly || handler === oauthScopeByOperation) &&
+    routes.every((route) => route.method === first.method && route.path === first.path);
+  if (declared) return handler === readOnly ? requireOAuthScope("read", "admin")(c, next) : next();
+  return requireOAuthScope("write", "admin")(c, next);
+});
 
 const getAuthority = <E extends AuthContext>(c: Context<E>): RequestAuthority => {
   const actor = c.get("actor");
   const accessSubject = c.get("accessSubject");
   const credentialKind = c.get("credentialKind");
   if (!actor || !accessSubject || !credentialKind) throw new Error("Request authority has not been resolved");
-  return {
-    actor,
-    accessSubject,
-    credentialKind,
-    scopes: [...(c.get("credentialScopes") ?? [])],
-  };
+  return bindAppAccessRequest(
+    {
+      actor,
+      accessSubject,
+      credentialKind,
+      scopes: [...(c.get("credentialScopes") ?? [])],
+      ...(c.get("credentialProof") ? { credentialProof: c.get("credentialProof") } : {}),
+    },
+    c.req.raw,
+    credentialKind === "session"
+      ? c.get("sessionToken")
+      : credentialKind !== "invocation"
+        ? (session.getBearerToken(c) ?? undefined)
+        : undefined,
+  );
 };
 
 /**
@@ -444,23 +542,25 @@ const redirectToLogin: RoleOptions = {
 };
 
 const requireAccount = (options: AccountOptions) =>
-  createMiddleware<AuthContext>(async (c, next) => {
-    const { user } = await loadAuthenticatedActor(c);
+  readOnlyMiddleware(
+    createMiddleware<AuthContext>(async (c, next) => {
+      const { user } = await loadAuthenticatedActor(c);
 
-    if (!user) {
-      return handleReject(c, options, "unauthenticated");
-    }
+      if (!user) {
+        return handleReject(c, options, "unauthenticated");
+      }
 
-    if (options.provider && user.provider !== options.provider) {
-      return handleReject(c, options, "forbidden");
-    }
+      if (options.provider && user.provider !== options.provider) {
+        return handleReject(c, options, "forbidden");
+      }
 
-    if (options.profile && user.profile !== options.profile) {
-      return handleReject(c, options, "forbidden");
-    }
+      if (options.profile && user.profile !== options.profile) {
+        return handleReject(c, options, "forbidden");
+      }
 
-    return next();
-  });
+      return requireOAuthMutationScope(c, next);
+    }),
+  );
 
 // ==========================
 // Export
@@ -474,6 +574,8 @@ export const auth = {
   browserSignIn,
   rejectAppSession,
   requireOAuthScope,
+  readOnly,
+  readOnlyMiddleware,
   getAuthority,
   requireAccount,
   redirect,

package/src/server/middleware/index.ts

@@ -4,6 +4,7 @@ export {
   type AuthContext,
   auth,
   type InvocationProvenance,
+  isRequestCredentialCurrent,
   type RequestActor,
   type RequestAuthority,
   type RequestCredentialKind,

package/src/server/middleware/invocation.ts

@@ -1,5 +1,6 @@
 import type { Context, MiddlewareHandler } from "hono";
 import { createMiddleware } from "hono/factory";
+import { bindAppAccessRequest } from "../../_internal/app-access-request";
 import { getApp } from "../../_internal/registry";
 import type { AppMeta } from "../../contracts/app";
 import { canUseApp } from "../../services/app-access";
@@ -7,7 +8,7 @@ import { recordAppAccessDenied } from "../../services/app-access-metrics";
 import { type ResolvedInvocationAuthority, resolveInvocationAuthority } from "../../services/identity/invocation-actor";
 import { type CloudInvocationClaims, isInvocationJwtCandidate, verifyInvocationToken } from "../../services/identity/invocation-token";
 import { appAccessDeniedBody } from "./app-access";
-import type { AuthContext } from "./auth";
+import { type AuthContext, requireOAuthMutationScope } from "./auth";
 
 export type InvocationExpectation = {
   targetAppId: string;
@@ -53,6 +54,7 @@ export const requireInvocation = (
     if (!claims) return reject(c);
     const authority = await (dependencies.resolve ?? resolveInvocationAuthority)(claims);
     if (!authority) return reject(c);
+    bindAppAccessRequest(authority, c.req.raw);
     const app = await (dependencies.getApp ?? getApp)(expectation.targetAppId).catch(() => null);
     if (!app || !(await canUseApp(authority, app))) {
       if (app) recordAppAccessDenied(app.id);
@@ -62,5 +64,5 @@ export const requireInvocation = (
       return c.json({ code: "SCHEMA_MISMATCH", message: "The invocation schema no longer matches the target" }, 409);
     }
     installAuthority(c, claims, authority);
-    return next();
+    return requireOAuthMutationScope(c, next);
   });

package/src/server/middleware/workload.ts

@@ -1,7 +1,7 @@
 import type { Context, MiddlewareHandler } from "hono";
 import { createMiddleware } from "hono/factory";
 import { hasReservedWorkloadScope } from "../../services/identity/workload-auth";
-import type { AuthContext } from "./auth";
+import { type AuthContext, auth } from "./auth";
 
 /** Reserved app workload keys are valid only at their dedicated Core authority routes. */
 export const isReservedWorkloadCredential = (c: Context<AuthContext>): boolean => {
@@ -17,6 +17,6 @@ export const isReservedWorkloadCredential = (c: Context<AuthContext>): boolean =
 const reservedWorkloadResponse = (c: Context<AuthContext>): Response =>
   c.json({ code: "FORBIDDEN", message: "App workload credentials require a dedicated Core authority route" }, 403);
 
-export const rejectReservedWorkloadCredential: MiddlewareHandler<AuthContext> = createMiddleware<AuthContext>(async (c, next) =>
-  isReservedWorkloadCredential(c) ? reservedWorkloadResponse(c) : await next(),
+export const rejectReservedWorkloadCredential: MiddlewareHandler<AuthContext> = auth.readOnlyMiddleware(
+  createMiddleware<AuthContext>(async (c, next) => (isReservedWorkloadCredential(c) ? reservedWorkloadResponse(c) : await next())),
 );

package/src/server/oauth-scope.ts

@@ -0,0 +1,10 @@
+import type { RequestAuthority } from "./middleware/auth";
+
+/** Credential ceilings survive inter-app invocation; sessions and API keys retain their own contracts. */
+export const hasOAuthScope = (authority: RequestAuthority | undefined, ...required: string[]): boolean => {
+  if (!authority) return true;
+  const oauth =
+    authority.credentialKind === "oauth" ||
+    (authority.credentialKind === "invocation" && authority.actor.delegation?.credentialKind === "oauth");
+  return !oauth || required.some((scope) => authority.scopes.includes(scope));
+};