@oxy.so/core 7.19.0 → 7.20.0

package/src/server/appPermissions.ts

@@ -2,10 +2,13 @@
  * Application roles, from the application's side: which of THIS application's
  * declared permissions does the person behind a request hold?
  *
- * Oxy decides who holds an app's operator powers (`docs/auth/application-roles.md`).
- * An app declares its keys (`payments.operate`, …) in the Console, its owners
- * grant them to people, and its backend asks — so no app keeps a
- * `*_OPERATOR_OXY_USER_IDS` allow-list in its environment.
+ * Oxy decides who holds an app's operator powers (`docs/auth/application-roles.md`),
+ * and the backend asks — so no app keeps a `*_OPERATOR_OXY_USER_IDS` allow-list
+ * in its environment. One of Oxy's own applications declares its keys
+ * (`payments.operate`, …) in Oxy's first-party registry, each held by roles of
+ * the owning organization (ADR 0056); a third-party app declares them in the
+ * Console and its owners grant them to people. The answer has the same shape
+ * either way.
  *
  * ```ts
  * const oxy = new OxyServer({ baseURL: 'https://api.oxy.so', applicationId: process.env.OXY_APPLICATION_ID });
@@ -31,6 +34,23 @@
  * `X-Oxy-User-Id`, is refused — an operator power is exercised by a person in
  * a session, never through delegation.
  *
+ * ## An MCP tool call
+ *
+ * An MCP request carries no session: its bearer is an access token Oxy issued
+ * for this app's MCP resource, which `@oxy.so/mcp`'s transport introspected
+ * live before the tool ran. Pass the call's `extra` (`context.request` in a
+ * catalog handler or `authorize`) the same way:
+ *
+ * ```ts
+ * const held = await oxy.appPermissionsFor(context.request, { fresh: true });
+ * ```
+ *
+ * The SDK presents that token, with THIS process's service token, to
+ * `POST /auth/mcp/oauth/app-permissions`. Oxy answers only for a token whose
+ * resource this application registered, only about this application, and for
+ * the person who authorized the token — whichever account the connection is
+ * acting as. Same answer type, cache, `fresh` and errors as a session.
+ *
  * ## Caching, and how soon a revocation lands
  *
  * Answers are cached per (application, session, user) for
@@ -44,6 +64,7 @@
  * Node only; reachable solely from `@oxy.so/core/server`.
  */
 
+import { createHash } from 'node:crypto';
 import { applicationRolesMeSchema, isApplicationPermissionKey } from '@oxy.so/contracts';
 import { logger } from '../logger';
 import {
@@ -51,6 +72,7 @@ import {
   CallerAuthorityCache,
   errorStatus,
   permissionSet,
+  isBearerToken,
   readCallerSession,
   type OxyCallerRequest,
 } from './callerAuthority';
@@ -64,7 +86,8 @@ export type OxyAppPermissionDenyStatus = 403 | 404;
 /**
  * - `APP_PERMISSION_DENIED` — a person in a session, without the permission.
  * - `APP_PERMISSION_SESSION_REQUIRED` — no user session on the request: anonymous,
- *   or authenticated by a service token (delegated or not).
+ *   or authenticated by a service token (delegated or not); for an MCP call, no
+ *   access token, or one Oxy refused (revoked, expired, another app's resource).
  * - `APP_PERMISSION_UNAVAILABLE` — Oxy could not be asked or gave no usable
  *   answer. Fails closed; answered 503.
  * - `APP_PERMISSION_NOT_CONFIGURED` — this server knows no application id, or
@@ -104,6 +127,8 @@ export interface OxyAppPermissions {
    * The HUMAN Oxy resolved from the session — record THIS as the actor in an
    * audit log. It differs from `req.userId` when a person acts as an
    * organization (the session speaks as the org; the operator is the person).
+   * For an MCP call it is the person who authorized the token, which may differ
+   * from the account the connection is acting as.
    */
   readonly operatorId: string;
   /** The held keys, sorted. */
@@ -114,7 +139,11 @@ export interface OxyAppPermissions {
 export interface AppPermissionsOptions {
   /** Skip the cache and ask Oxy (the answer still refreshes the cache). Use on writes. */
   fresh?: boolean;
-  /** Ask about another application than the server's configured one. */
+  /**
+   * Ask about another application than the server's configured one. Not for an
+   * MCP call: Oxy answers it only about the application that registered the
+   * token's resource, and any other id is `APP_PERMISSION_NOT_CONFIGURED`.
+   */
   applicationId?: string;
 }
 
@@ -140,6 +169,22 @@ export interface AppPermissionsRequest extends OxyCallerRequest {
   oxyAppPermissions?: OxyAppPermissions;
 }
 
+/**
+ * An MCP tool call: the `extra` (`RequestHandlerExtra`) an MCP handler receives,
+ * whose `authInfo` `@oxy.so/mcp`'s transport set after Oxy introspected the
+ * access token live. `CatalogInvocationContext.request` is one.
+ */
+export interface OxyMcpCallerRequest {
+  readonly authInfo?: { readonly token: string };
+}
+
+/** What `appPermissionsFor` reads: a request after `middleware.auth()`, or an MCP tool call. */
+export type AppPermissionsSource = AppPermissionsRequest | OxyMcpCallerRequest;
+
+function isMcpCallerRequest(source: AppPermissionsSource): source is OxyMcpCallerRequest {
+  return (source as OxyMcpCallerRequest).authInfo !== undefined;
+}
+
 /** The status the middleware answers an error with, under `deny`. */
 export function appPermissionErrorStatus(
   error: OxyAppPermissionError,
@@ -181,6 +226,11 @@ function heldPermissions(
 export interface AppPermissionsHost {
   /** `GET /applications/:appId/roles/me` with this bearer, uncached. Rejects with the API error. */
   fetchRolesMe(applicationId: string, accessToken: string): Promise<unknown>;
+  /**
+   * `POST /auth/mcp/oauth/app-permissions` with this MCP access token, as this
+   * server's service, uncached. Rejects with the API error.
+   */
+  fetchMcpAppPermissions(mcpAccessToken: string): Promise<unknown>;
   /** The configured application id, or the one this server's service token names. */
   defaultApplicationId(): Promise<string | null>;
   readonly ttlMs: number;
@@ -201,14 +251,16 @@ export class OxyAppPermissionsResolver {
   }
 
   /**
-   * What the person behind `req` holds. Throws {@link OxyAppPermissionError};
+   * What the person behind `source` holds. Throws {@link OxyAppPermissionError};
    * never answers "nothing held" for a failure.
    */
   async resolve(
-    req: AppPermissionsRequest,
+    source: AppPermissionsSource,
     options: AppPermissionsOptions = {},
   ): Promise<OxyAppPermissions> {
-    const caller = readCallerSession(req);
+    if (isMcpCallerRequest(source)) return this.resolveMcp(source, options);
+
+    const caller = readCallerSession(source);
     if (!caller.ok) {
       throw new OxyAppPermissionError(
         'APP_PERMISSION_SESSION_REQUIRED',
@@ -218,6 +270,49 @@ export class OxyAppPermissionsResolver {
       );
     }
 
+    const appId = await this.applicationIdFor(options);
+    return this.cache.read([appId], caller.session, options.fresh === true, () =>
+      this.lookup(appId, caller.session.accessToken),
+    );
+  }
+
+  /**
+   * Forget cached answers: every one, or those about one person (matched as
+   * either the session's user or the resolved operator).
+   */
+  invalidate(filter: { userId?: string } = {}): void {
+    this.cache.invalidate(filter);
+  }
+
+  /**
+   * An MCP call: Oxy names the application (the one that registered the token's
+   * resource) and the person (who authorized the token); the answer is refused
+   * unless the application is the one this server expects.
+   */
+  private async resolveMcp(
+    source: OxyMcpCallerRequest,
+    options: AppPermissionsOptions,
+  ): Promise<OxyAppPermissions> {
+    const token = source.authInfo?.token;
+    if (typeof token !== 'string' || !isBearerToken(token)) {
+      throw new OxyAppPermissionError(
+        'APP_PERMISSION_SESSION_REQUIRED',
+        'No verified MCP access token on this call',
+      );
+    }
+    const appId = await this.applicationIdFor(options);
+    // The person is known only once Oxy answers; the token's digest keys the
+    // entry, so the bearer itself is never held as a cache key.
+    const cacheKey = {
+      sessionId: `mcp:${createHash('sha256').update(token).digest('base64url')}`,
+      userId: null,
+    };
+    return this.cache.read([appId], cacheKey, options.fresh === true, () =>
+      this.lookupMcp(appId, token),
+    );
+  }
+
+  private async applicationIdFor(options: AppPermissionsOptions): Promise<string> {
     let applicationId = options.applicationId ?? null;
     if (!applicationId) {
       try {
@@ -236,19 +331,69 @@ export class OxyAppPermissionsResolver {
         'No application id: set OxyServerConfig.applicationId, configure service auth, or pass { applicationId }',
       );
     }
-
-    const appId = applicationId;
-    return this.cache.read([appId], caller.session, options.fresh === true, () =>
-      this.lookup(appId, caller.session.accessToken),
-    );
+    return applicationId;
   }
 
-  /**
-   * Forget cached answers: every one, or those about one person (matched as
-   * either the session's user or the resolved operator).
-   */
-  invalidate(filter: { userId?: string } = {}): void {
-    this.cache.invalidate(filter);
+  private async lookupMcp(
+    applicationId: string,
+    mcpAccessToken: string,
+  ): Promise<OxyAppPermissions> {
+    let answer: unknown;
+    try {
+      answer = await this.host.fetchMcpAppPermissions(mcpAccessToken);
+    } catch (error) {
+      const status = errorStatus(error);
+      if (status === 401 && (error as { code?: unknown }).code === 'invalid_grant') {
+        throw new OxyAppPermissionError(
+          'APP_PERMISSION_SESSION_REQUIRED',
+          'Oxy refused the MCP access token while resolving application permissions',
+          { cause: error },
+        );
+      }
+      if (status === 403) {
+        throw new OxyAppPermissionError(
+          'APP_PERMISSION_DENIED',
+          'Oxy refused this application’s permissions for the MCP access token',
+          { cause: error },
+        );
+      }
+      // Anything else — this service's own credential refused (401
+      // `invalid_client`), an Oxy without the route, a 5xx, a timeout — is not
+      // an answer about the person.
+      logger.warn('[oxy.appPermissions] Could not resolve application permissions for MCP', {
+        component: 'auth',
+        method: 'appPermissions',
+        applicationId,
+        status,
+      });
+      throw new OxyAppPermissionError(
+        'APP_PERMISSION_UNAVAILABLE',
+        'Could not resolve application permissions from Oxy',
+        { cause: error },
+      );
+    }
+
+    const parsed = applicationRolesMeSchema.safeParse(answer);
+    if (!parsed.success) {
+      throw new OxyAppPermissionError(
+        'APP_PERMISSION_UNAVAILABLE',
+        'Oxy answered with a malformed permission set',
+      );
+    }
+    if (parsed.data.applicationId !== applicationId) {
+      // Oxy answers about the application behind this server's service token;
+      // a different one means the configured id names another application.
+      logger.error(
+        `[oxy.appPermissions] Oxy answered for application ${parsed.data.applicationId}, not ${applicationId}; check OxyServerConfig.applicationId`,
+        undefined,
+        { component: 'auth', method: 'appPermissions' },
+      );
+      throw new OxyAppPermissionError(
+        'APP_PERMISSION_NOT_CONFIGURED',
+        'An MCP access token answers only for the application behind this server’s service token',
+      );
+    }
+    return heldPermissions(applicationId, parsed.data.userId, parsed.data.permissions);
   }
 
   private async lookup(applicationId: string, accessToken: string): Promise<OxyAppPermissions> {

package/src/server/callerAuthority.ts

@@ -42,6 +42,17 @@ export interface OxyCallerSession {
   readonly accessToken: string;
 }
 
+/**
+ * Whose answer a cache entry is: the session (or other credential) it was read
+ * with, and the person, when known before asking. A caller whose person only
+ * Oxy's answer names (an MCP access token) passes `userId: null`; the reader's
+ * `isAbout` still matches the answer for {@link CallerAuthorityCache.invalidate}.
+ */
+export interface OxyCallerCacheKey {
+  readonly sessionId: string;
+  readonly userId: string | null;
+}
+
 /**
  * The person behind `req`, or why there is none: `service` for a request
  * authenticated by a service token (delegated or not — its bearer is the
@@ -175,7 +186,7 @@ export function accessFailure(error: unknown, what: string): OxyAccessError {
 
 interface CacheEntry<T> {
   value: T;
-  userId: string;
+  userId: string | null;
   startedAt: number;
   expiresAt: number;
 }
@@ -204,7 +215,7 @@ export class CallerAuthorityCache<T> {
 
   async read(
     resourceKey: readonly string[],
-    session: OxyCallerSession,
+    session: OxyCallerCacheKey,
     fresh: boolean,
     lookup: () => Promise<T>,
   ): Promise<T> {
@@ -244,7 +255,13 @@ export class CallerAuthorityCache<T> {
     }
   }
 
-  private remember(key: string, userId: string, value: T, startedAt: number, ttl: number): void {
+  private remember(
+    key: string,
+    userId: string | null,
+    value: T,
+    startedAt: number,
+    ttl: number,
+  ): void {
     const existing = this.entries.get(key);
     if (existing && existing.startedAt > startedAt) return;
     this.entries.delete(key);

package/src/server/index.ts

@@ -97,6 +97,8 @@ export {
 } from './appPermissions';
 export type {
   AppPermissionsOptions,
+  AppPermissionsSource,
+  OxyMcpCallerRequest,
   OxyAppPermissionDenyStatus,
   OxyAppPermissionErrorCode,
   OxyAppPermissions,