@oxy.so/core 7.19.1 → 7.20.0

package/README.md

@@ -172,8 +172,8 @@ router.get('/orgs/:accountId', async (req, res) => {
 
 `createOxyAuthMiddleware(oxy)` resolves the bearer session and requires a user
 in one middleware; `createOptionalOxyAuth(oxy)` is the optional form. The
-permission questions (`appPermissionsFor`, `accountAccessFor`,
-`applicationAccessFor`), user clients (`withUser`), per-call options
+permission questions (`appPermissionsFor` — for a session or an MCP tool call —
+`accountAccessFor`, `applicationAccessFor`), user clients (`withUser`), per-call options
 (`oxy.withCallOptions({ timeout, deadline, retry, signal })`), files and
 outbound HTTP (`safeFetch`, with `validated` to reuse an `assertSafePublicUrl`
 check and `requireHttps` for an all-https chain) are in

package/dist/cjs/HttpService.js

@@ -373,6 +373,7 @@ class HttpService {
         this.authRefreshHandler = null;
         this.accessTokenProvider = null;
         this.anonymousAuthProvider = null;
+        this.anonymousAuthRejected = null;
         this.deviceSecretMintInFlight = null;
         /**
          * Bumped by every {@link endSession}. A re-mint captures it before its first
@@ -819,6 +820,32 @@ class HttpService {
                 }
                 // Handle response
                 if (!response.ok) {
+                    // A 401 to the bearer the anonymous provider supplied (a backend's
+                    // own service token, no user session): once its owner has dropped
+                    // it, send the request once more with the provider's next one. A
+                    // 401 means the request never ran, so this is safe for any method.
+                    if (response.status === 401 &&
+                        !contextToken &&
+                        usesSessionAuth &&
+                        !config.expectedCredentialGeneration &&
+                        !config._isAuthRetry &&
+                        authHeader?.startsWith('Bearer ') &&
+                        this.anonymousAuthRejected?.(authHeader.slice('Bearer '.length))) {
+                        void discardResponseBody(response);
+                        if (domain.aborted)
+                            throw (0, errorUtils_1.createCancelledError)();
+                        // Same reasons as the session retry below: no dedupe (the original
+                        // is still in flight under its key), no queue slot (this attempt
+                        // holds one).
+                        return this.request({
+                            ...config,
+                            _isAuthRetry: true,
+                            retry: false,
+                            deduplicate: false,
+                            bypassQueue: true,
+                            signal: domain,
+                        });
+                    }
                     // On 401, delegate to the installed auth refresh handler and retry
                     // once before giving up. HttpService deliberately does not know any
                     // session routes; the refresh handler owns session rotation.
@@ -1842,9 +1869,14 @@ class HttpService {
      * `OxyConfig.serviceIdentity`). A user session always wins: the provider is
      * consulted only when there is no access token, and never for `skipAuth`
      * requests. `null` removes it.
+     *
+     * `onRejected` hears of a 401 to one of the provider's bearers; when it
+     * drops that bearer (`true`), the request is sent once more with the
+     * provider's next one — a rotated or revoked service token heals itself.
      */
-    setAnonymousAuthProvider(provider) {
+    setAnonymousAuthProvider(provider, onRejected) {
         this.anonymousAuthProvider = provider;
+        this.anonymousAuthRejected = provider ? (onRejected ?? null) : null;
     }
     clearTokens() {
         if (this.tokenStore.getAccessToken())

package/dist/cjs/server/OxyServer.js

@@ -155,7 +155,7 @@ class OxyServer extends OxyServices_1.OxyServices {
         };
         this.context.service = serviceLane;
         if (config.serviceIdentity === 'when-anonymous') {
-            this.http.setAnonymousAuthProvider(() => this.serviceTokenForAnonymousRequest());
+            this.http.setAnonymousAuthProvider(() => this.serviceTokenForAnonymousRequest(), (token) => this.forgetServiceToken(token));
         }
         const ttl = config.appPermissionsCacheTtlMs ?? appPermissions_1.APP_PERMISSIONS_CACHE_TTL_MS;
         if (!Number.isFinite(ttl) || ttl < 0) {
@@ -171,6 +171,7 @@ class OxyServer extends OxyServices_1.OxyServices {
             ttlMs: ttl,
             defaultApplicationId: () => this.defaultApplicationId(),
             fetchRolesMe: (applicationId, accessToken) => this.fetchRolesMe(applicationId, accessToken),
+            fetchMcpAppPermissions: (mcpAccessToken) => this.fetchMcpAppPermissions(mcpAccessToken),
         });
         this.callerAccess = new callerAccess_1.OxyCallerAccessResolver({
             ttlMs: ttl,
@@ -558,8 +559,7 @@ class OxyServer extends OxyServices_1.OxyServices {
             throw new Error('Service requests must target the configured API origin');
         }
         const { actAs, requesterToken, taskId, capabilityTicket, requesterContext, headers, serviceTokenScopes, ...rest } = options;
-        const token = await this.platformServiceToken({ scopes: serviceTokenScopes });
-        const merged = { ...headers, Authorization: `Bearer ${token}` };
+        const merged = { ...headers };
         if (actAs)
             merged['X-Oxy-User-Id'] = actAs;
         if ([requesterToken, taskId, capabilityTicket, requesterContext].filter((proof) => proof !== undefined).length > 1)
@@ -572,14 +572,48 @@ class OxyServer extends OxyServices_1.OxyServices {
             merged['X-Oxy-Capability-Ticket'] = capabilityTicket;
         if (requesterContext)
             merged['X-Oxy-Requester-Context'] = requesterContext;
-        return this.request(method, target.href, data, {
+        const send = (token) => this.request(method, target.href, data, {
             cache: false,
             ...rest,
             ...([requesterToken, taskId, capabilityTicket, requesterContext].some((proof) => proof !== undefined)
                 ? { cache: false, deduplicate: false, retry: false }
                 : {}),
-            headers: merged,
+            headers: { ...merged, Authorization: `Bearer ${token}` },
         });
+        const token = await this.platformServiceToken({ scopes: serviceTokenScopes });
+        try {
+            return await send(token);
+        }
+        catch (error) {
+            // A 401 refused the request before it ran, so sending it again is safe
+            // whatever its method. A cached token Oxy no longer accepts (keys
+            // rotated, credential revoked) is dropped and the request sent once
+            // more with a freshly minted one: once, never after an abort, and only
+            // when the refused token was this server's cached one.
+            if ((0, errorUtils_1.extractErrorStatus)(error) !== 401 ||
+                rest.signal?.aborted ||
+                !this.forgetServiceToken(token)) {
+                throw error;
+            }
+            const fresh = await this.platformServiceToken({ scopes: serviceTokenScopes });
+            if (fresh === token)
+                throw error;
+            return send(fresh);
+        }
+    }
+    /**
+     * Drop every cached entry that holds `token` (and is not minting): `true`
+     * when one did, so the next mint asks Oxy again.
+     */
+    forgetServiceToken(token) {
+        let forgot = false;
+        for (const [cacheKey, entry] of this.serviceTokens) {
+            if (entry.token === token && !entry.pending) {
+                this.serviceTokens.delete(cacheKey);
+                forgot = true;
+            }
+        }
+        return forgot;
     }
     // ── Application roles ────────────────────────────────────────────────────
     /**
@@ -588,6 +622,12 @@ class OxyServer extends OxyServices_1.OxyServices {
      * must have passed `middleware.auth()`: the answer is read from Oxy with the
      * request's own verified bearer, for the human operator of its session.
      *
+     * An MCP tool call is asked the same way: pass its `extra`
+     * (`CatalogInvocationContext.request`), whose `authInfo.token` is the access
+     * token `@oxy.so/mcp` introspected. Oxy answers, for the person who
+     * authorized that token, only about the application that registered its
+     * resource — this server's own (`APP_PERMISSION_NOT_CONFIGURED` otherwise).
+     *
      * Cached per session for `appPermissionsCacheTtlMs` (30 s); pass
      * `{ fresh: true }` before a write. Throws `OxyAppPermissionError` — no
      * session (`APP_PERMISSION_SESSION_REQUIRED`, also for any service-token
@@ -700,6 +740,9 @@ class OxyServer extends OxyServices_1.OxyServices {
         }
         return this.request('GET', `/applications/${encodeURIComponent(applicationId)}/roles/me`, undefined, { cache: false, retry: false, headers: { Authorization: `Bearer ${accessToken}` } });
     }
+    fetchMcpAppPermissions(mcpAccessToken) {
+        return this.serviceRequest('POST', '/auth/mcp/oauth/app-permissions', { token: mcpAccessToken }, { cache: false, deduplicate: false, retry: false });
+    }
     // ── Delegation and account events ────────────────────────────────────────
     /**
      * Resolve authority live by default. Explicit read-only reuse lasts at most

package/dist/cjs/server/appPermissions.js

@@ -35,6 +35,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
@@ -51,6 +68,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OxyAppPermissionsResolver = exports.appPermissionErrorBody = exports.OxyAppPermissionError = exports.APP_PERMISSIONS_CACHE_TTL_MS = void 0;
 exports.appPermissionErrorStatus = appPermissionErrorStatus;
 exports.assertApplicationPermissionKey = assertApplicationPermissionKey;
+const node_crypto_1 = require("node:crypto");
 const contracts_1 = require("@oxy.so/contracts");
 const logger_1 = require("../logger");
 const callerAuthority_1 = require("./callerAuthority");
@@ -67,6 +85,9 @@ class OxyAppPermissionError extends Error {
     }
 }
 exports.OxyAppPermissionError = OxyAppPermissionError;
+function isMcpCallerRequest(source) {
+    return source.authInfo !== undefined;
+}
 /** The status the middleware answers an error with, under `deny`. */
 function appPermissionErrorStatus(error, deny = 404) {
     switch (error.code) {
@@ -101,16 +122,48 @@ class OxyAppPermissionsResolver {
         this.cache = new callerAuthority_1.CallerAuthorityCache(host.ttlMs, (value, userId) => value.operatorId === userId);
     }
     /**
-     * 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, options = {}) {
-        const caller = (0, callerAuthority_1.readCallerSession)(req);
+    async resolve(source, options = {}) {
+        if (isMcpCallerRequest(source))
+            return this.resolveMcp(source, options);
+        const caller = (0, callerAuthority_1.readCallerSession)(source);
         if (!caller.ok) {
             throw new OxyAppPermissionError('APP_PERMISSION_SESSION_REQUIRED', caller.reason === 'service'
                 ? 'Application permissions are held by a person in a session; this request is authenticated by a service token'
                 : 'No verified user session on this request; mount middleware.auth() first');
         }
+        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 = {}) {
+        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.
+     */
+    async resolveMcp(source, options) {
+        const token = source.authInfo?.token;
+        if (typeof token !== 'string' || !(0, callerAuthority_1.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:${(0, node_crypto_1.createHash)('sha256').update(token).digest('base64url')}`,
+            userId: null,
+        };
+        return this.cache.read([appId], cacheKey, options.fresh === true, () => this.lookupMcp(appId, token));
+    }
+    async applicationIdFor(options) {
         let applicationId = options.applicationId ?? null;
         if (!applicationId) {
             try {
@@ -123,15 +176,43 @@ class OxyAppPermissionsResolver {
         if (!applicationId) {
             throw new OxyAppPermissionError('APP_PERMISSION_NOT_CONFIGURED', '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 = {}) {
-        this.cache.invalidate(filter);
+    async lookupMcp(applicationId, mcpAccessToken) {
+        let answer;
+        try {
+            answer = await this.host.fetchMcpAppPermissions(mcpAccessToken);
+        }
+        catch (error) {
+            const status = (0, callerAuthority_1.errorStatus)(error);
+            if (status === 401 && error.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_1.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 = contracts_1.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_1.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);
     }
     async lookup(applicationId, accessToken) {
         let answer;

package/dist/esm/HttpService.js

@@ -369,6 +369,7 @@ export class HttpService {
         this.authRefreshHandler = null;
         this.accessTokenProvider = null;
         this.anonymousAuthProvider = null;
+        this.anonymousAuthRejected = null;
         this.deviceSecretMintInFlight = null;
         /**
          * Bumped by every {@link endSession}. A re-mint captures it before its first
@@ -815,6 +816,32 @@ export class HttpService {
                 }
                 // Handle response
                 if (!response.ok) {
+                    // A 401 to the bearer the anonymous provider supplied (a backend's
+                    // own service token, no user session): once its owner has dropped
+                    // it, send the request once more with the provider's next one. A
+                    // 401 means the request never ran, so this is safe for any method.
+                    if (response.status === 401 &&
+                        !contextToken &&
+                        usesSessionAuth &&
+                        !config.expectedCredentialGeneration &&
+                        !config._isAuthRetry &&
+                        authHeader?.startsWith('Bearer ') &&
+                        this.anonymousAuthRejected?.(authHeader.slice('Bearer '.length))) {
+                        void discardResponseBody(response);
+                        if (domain.aborted)
+                            throw createCancelledError();
+                        // Same reasons as the session retry below: no dedupe (the original
+                        // is still in flight under its key), no queue slot (this attempt
+                        // holds one).
+                        return this.request({
+                            ...config,
+                            _isAuthRetry: true,
+                            retry: false,
+                            deduplicate: false,
+                            bypassQueue: true,
+                            signal: domain,
+                        });
+                    }
                     // On 401, delegate to the installed auth refresh handler and retry
                     // once before giving up. HttpService deliberately does not know any
                     // session routes; the refresh handler owns session rotation.
@@ -1838,9 +1865,14 @@ export class HttpService {
      * `OxyConfig.serviceIdentity`). A user session always wins: the provider is
      * consulted only when there is no access token, and never for `skipAuth`
      * requests. `null` removes it.
+     *
+     * `onRejected` hears of a 401 to one of the provider's bearers; when it
+     * drops that bearer (`true`), the request is sent once more with the
+     * provider's next one — a rotated or revoked service token heals itself.
      */
-    setAnonymousAuthProvider(provider) {
+    setAnonymousAuthProvider(provider, onRejected) {
         this.anonymousAuthProvider = provider;
+        this.anonymousAuthRejected = provider ? (onRejected ?? null) : null;
     }
     clearTokens() {
         if (this.tokenStore.getAccessToken())

package/dist/esm/server/OxyServer.js

@@ -46,7 +46,7 @@ import { OxyServices } from '../OxyServices.js';
 import { HttpService } from '../HttpService.js';
 import { createAuthenticatedFetch } from '../authenticatedFetch.js';
 import { awaitRequestSignal } from '../utils/requestSignal.js';
-import { createCancelledError } from '../utils/errorUtils.js';
+import { createCancelledError, extractErrorStatus } from '../utils/errorUtils.js';
 import { logger } from '../logger/index.js';
 import { canAttestWorkloadIdentity, requestWorkloadServiceToken, } from './workloadIdentity.js';
 import { createOxyMiddleware, OXY_ACCOUNT_DELETED_EVENT_URI, OXY_JWT_ISSUER, OxyAccountEventError, parseJsonSegment, resolveServiceTokenPublicKey, } from './middleware.js';
@@ -151,7 +151,7 @@ export class OxyServer extends OxyServices {
         };
         this.context.service = serviceLane;
         if (config.serviceIdentity === 'when-anonymous') {
-            this.http.setAnonymousAuthProvider(() => this.serviceTokenForAnonymousRequest());
+            this.http.setAnonymousAuthProvider(() => this.serviceTokenForAnonymousRequest(), (token) => this.forgetServiceToken(token));
         }
         const ttl = config.appPermissionsCacheTtlMs ?? APP_PERMISSIONS_CACHE_TTL_MS;
         if (!Number.isFinite(ttl) || ttl < 0) {
@@ -167,6 +167,7 @@ export class OxyServer extends OxyServices {
             ttlMs: ttl,
             defaultApplicationId: () => this.defaultApplicationId(),
             fetchRolesMe: (applicationId, accessToken) => this.fetchRolesMe(applicationId, accessToken),
+            fetchMcpAppPermissions: (mcpAccessToken) => this.fetchMcpAppPermissions(mcpAccessToken),
         });
         this.callerAccess = new OxyCallerAccessResolver({
             ttlMs: ttl,
@@ -554,8 +555,7 @@ export class OxyServer extends OxyServices {
             throw new Error('Service requests must target the configured API origin');
         }
         const { actAs, requesterToken, taskId, capabilityTicket, requesterContext, headers, serviceTokenScopes, ...rest } = options;
-        const token = await this.platformServiceToken({ scopes: serviceTokenScopes });
-        const merged = { ...headers, Authorization: `Bearer ${token}` };
+        const merged = { ...headers };
         if (actAs)
             merged['X-Oxy-User-Id'] = actAs;
         if ([requesterToken, taskId, capabilityTicket, requesterContext].filter((proof) => proof !== undefined).length > 1)
@@ -568,14 +568,48 @@ export class OxyServer extends OxyServices {
             merged['X-Oxy-Capability-Ticket'] = capabilityTicket;
         if (requesterContext)
             merged['X-Oxy-Requester-Context'] = requesterContext;
-        return this.request(method, target.href, data, {
+        const send = (token) => this.request(method, target.href, data, {
             cache: false,
             ...rest,
             ...([requesterToken, taskId, capabilityTicket, requesterContext].some((proof) => proof !== undefined)
                 ? { cache: false, deduplicate: false, retry: false }
                 : {}),
-            headers: merged,
+            headers: { ...merged, Authorization: `Bearer ${token}` },
         });
+        const token = await this.platformServiceToken({ scopes: serviceTokenScopes });
+        try {
+            return await send(token);
+        }
+        catch (error) {
+            // A 401 refused the request before it ran, so sending it again is safe
+            // whatever its method. A cached token Oxy no longer accepts (keys
+            // rotated, credential revoked) is dropped and the request sent once
+            // more with a freshly minted one: once, never after an abort, and only
+            // when the refused token was this server's cached one.
+            if (extractErrorStatus(error) !== 401 ||
+                rest.signal?.aborted ||
+                !this.forgetServiceToken(token)) {
+                throw error;
+            }
+            const fresh = await this.platformServiceToken({ scopes: serviceTokenScopes });
+            if (fresh === token)
+                throw error;
+            return send(fresh);
+        }
+    }
+    /**
+     * Drop every cached entry that holds `token` (and is not minting): `true`
+     * when one did, so the next mint asks Oxy again.
+     */
+    forgetServiceToken(token) {
+        let forgot = false;
+        for (const [cacheKey, entry] of this.serviceTokens) {
+            if (entry.token === token && !entry.pending) {
+                this.serviceTokens.delete(cacheKey);
+                forgot = true;
+            }
+        }
+        return forgot;
     }
     // ── Application roles ────────────────────────────────────────────────────
     /**
@@ -584,6 +618,12 @@ export class OxyServer extends OxyServices {
      * must have passed `middleware.auth()`: the answer is read from Oxy with the
      * request's own verified bearer, for the human operator of its session.
      *
+     * An MCP tool call is asked the same way: pass its `extra`
+     * (`CatalogInvocationContext.request`), whose `authInfo.token` is the access
+     * token `@oxy.so/mcp` introspected. Oxy answers, for the person who
+     * authorized that token, only about the application that registered its
+     * resource — this server's own (`APP_PERMISSION_NOT_CONFIGURED` otherwise).
+     *
      * Cached per session for `appPermissionsCacheTtlMs` (30 s); pass
      * `{ fresh: true }` before a write. Throws `OxyAppPermissionError` — no
      * session (`APP_PERMISSION_SESSION_REQUIRED`, also for any service-token
@@ -696,6 +736,9 @@ export class OxyServer extends OxyServices {
         }
         return this.request('GET', `/applications/${encodeURIComponent(applicationId)}/roles/me`, undefined, { cache: false, retry: false, headers: { Authorization: `Bearer ${accessToken}` } });
     }
+    fetchMcpAppPermissions(mcpAccessToken) {
+        return this.serviceRequest('POST', '/auth/mcp/oauth/app-permissions', { token: mcpAccessToken }, { cache: false, deduplicate: false, retry: false });
+    }
     // ── Delegation and account events ────────────────────────────────────────
     /**
      * Resolve authority live by default. Explicit read-only reuse lasts at most

package/dist/esm/server/appPermissions.js

@@ -34,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
@@ -46,9 +63,10 @@
  *
  * 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/index.js';
-import { authorityErrorBody, CallerAuthorityCache, errorStatus, permissionSet, readCallerSession, } from './callerAuthority.js';
+import { authorityErrorBody, CallerAuthorityCache, errorStatus, permissionSet, isBearerToken, readCallerSession, } from './callerAuthority.js';
 /** Default cache lifetime of one answer. */
 export const APP_PERMISSIONS_CACHE_TTL_MS = 30000;
 /** The typed failure of {@link OxyAppPermissionsResolver.resolve} and the middleware. */
@@ -61,6 +79,9 @@ export class OxyAppPermissionError extends Error {
         this.cause = options.cause;
     }
 }
+function isMcpCallerRequest(source) {
+    return source.authInfo !== undefined;
+}
 /** The status the middleware answers an error with, under `deny`. */
 export function appPermissionErrorStatus(error, deny = 404) {
     switch (error.code) {
@@ -95,16 +116,48 @@ export class OxyAppPermissionsResolver {
         this.cache = new CallerAuthorityCache(host.ttlMs, (value, userId) => value.operatorId === userId);
     }
     /**
-     * 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, options = {}) {
-        const caller = readCallerSession(req);
+    async resolve(source, options = {}) {
+        if (isMcpCallerRequest(source))
+            return this.resolveMcp(source, options);
+        const caller = readCallerSession(source);
         if (!caller.ok) {
             throw new OxyAppPermissionError('APP_PERMISSION_SESSION_REQUIRED', caller.reason === 'service'
                 ? 'Application permissions are held by a person in a session; this request is authenticated by a service token'
                 : 'No verified user session on this request; mount middleware.auth() first');
         }
+        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 = {}) {
+        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.
+     */
+    async resolveMcp(source, options) {
+        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));
+    }
+    async applicationIdFor(options) {
         let applicationId = options.applicationId ?? null;
         if (!applicationId) {
             try {
@@ -117,15 +170,43 @@ export class OxyAppPermissionsResolver {
         if (!applicationId) {
             throw new OxyAppPermissionError('APP_PERMISSION_NOT_CONFIGURED', '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 = {}) {
-        this.cache.invalidate(filter);
+    async lookupMcp(applicationId, mcpAccessToken) {
+        let answer;
+        try {
+            answer = await this.host.fetchMcpAppPermissions(mcpAccessToken);
+        }
+        catch (error) {
+            const status = errorStatus(error);
+            if (status === 401 && error.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);
     }
     async lookup(applicationId, accessToken) {
         let answer;