@oxy.so/core 7.19.1 → 7.20.0

package/dist/types/HttpService.d.ts

@@ -22,6 +22,12 @@ export type AccessTokenProvider = () => string | null;
  * — `null` to send it anonymous. See {@link HttpService.setAnonymousAuthProvider}.
  */
 export type AnonymousAuthProvider = () => Promise<string | null>;
+/**
+ * Told that Oxy answered 401 to a bearer an {@link AnonymousAuthProvider}
+ * supplied; `true` when it dropped that bearer, so the request is sent once
+ * more with the provider's next one.
+ */
+export type AnonymousAuthRejectedHandler = (token: string) => boolean;
 declare const credentialGenerationBrand: unique symbol;
 /**
  * An opaque, immutable token for ONE installation of a bearer in a client.
@@ -241,6 +247,7 @@ export declare class HttpService {
     private authRefreshHandler;
     private accessTokenProvider;
     private anonymousAuthProvider;
+    private anonymousAuthRejected;
     private deviceSecretMintInFlight;
     /**
      * Bumped by every {@link endSession}. A re-mint captures it before its first
@@ -557,8 +564,12 @@ export declare 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: AnonymousAuthProvider | null): void;
+    setAnonymousAuthProvider(provider: AnonymousAuthProvider | null, onRejected?: AnonymousAuthRejectedHandler): void;
     clearTokens(): void;
     /**
      * Subscribe to access-token changes on this instance.

package/dist/types/server/OxyServer.d.ts

@@ -6,7 +6,7 @@ import type { HttpMethod } from '../client/context';
 import type { RequestOptions, ResponsePayload } from '../HttpService';
 import { type WorkloadCredentialProvider } from './workloadIdentity';
 import { type OxyAccountEvent, type OxyAccountEventFeedPage, type OxyMiddleware, type ServiceActingAsVerification, type VerifyAccountEventOptions } from './middleware';
-import { type AppPermissionsOptions, type AppPermissionsRequest, type OxyAppPermissions } from './appPermissions';
+import { type AppPermissionsOptions, type AppPermissionsSource, type OxyAppPermissions } from './appPermissions';
 import { ServerAccountsApi, ServerAppsApi, ServerAgencyApi, ServerAssetsApi, ServerLinkedAccountsApi, ServerNotificationsApi, ServerReputationApi } from './namespaces';
 import { type CallerAccessOptions, type OxyAccountAccess, type OxyApplicationAccess } from './callerAccess';
 import type { OxyCallerRequest } from './callerAuthority';
@@ -295,12 +295,23 @@ export declare class OxyServer extends OxyServices {
         requesterContext?: string;
         serviceTokenScopes?: string[];
     }): Promise<ResponsePayload<T>>;
+    /**
+     * Drop every cached entry that holds `token` (and is not minting): `true`
+     * when one did, so the next mint asks Oxy again.
+     */
+    private forgetServiceToken;
     /**
      * Which of this application's own declared permissions the PERSON behind
      * `req` holds (application roles, `docs/auth/application-roles.md`). `req`
      * 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
@@ -308,7 +319,7 @@ export declare class OxyServer extends OxyServices {
      * application id (`APP_PERMISSION_NOT_CONFIGURED`) — and never answers
      * "nothing held" for a failure.
      */
-    appPermissionsFor(req: AppPermissionsRequest, options?: AppPermissionsOptions): Promise<OxyAppPermissions>;
+    appPermissionsFor(req: AppPermissionsSource, options?: AppPermissionsOptions): Promise<OxyAppPermissions>;
     /**
      * Drop cached caller-authority answers — application permissions and
      * account / application access — all of them, or one person's (as the
@@ -383,6 +394,7 @@ export declare class OxyServer extends OxyServices {
     }): void;
     private defaultApplicationId;
     private fetchRolesMe;
+    private fetchMcpAppPermissions;
     /**
      * Resolve authority live by default. Explicit read-only reuse lasts at most
      * 60s positive / 10s negative, anchored to request start; errors never cache.

package/dist/types/server/appPermissions.d.ts

@@ -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
@@ -54,7 +71,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
@@ -80,6 +98,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. */
@@ -89,7 +109,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;
 }
 export interface RequireAppPermissionOptions extends AppPermissionsOptions {
@@ -112,6 +136,18 @@ export interface RequireAppPermissionOptions extends AppPermissionsOptions {
 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;
 /** The status the middleware answers an error with, under `deny`. */
 export declare function appPermissionErrorStatus(error: OxyAppPermissionError, deny?: OxyAppPermissionDenyStatus): number;
 /** The response body for a status: the API error envelope (`docs/api-conventions.md`). */
@@ -122,6 +158,11 @@ export declare function assertApplicationPermissionKey(permission: unknown): ass
 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;
@@ -135,10 +176,10 @@ export declare class OxyAppPermissionsResolver {
     private readonly cache;
     constructor(host: AppPermissionsHost);
     /**
-     * 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.
      */
-    resolve(req: AppPermissionsRequest, options?: AppPermissionsOptions): Promise<OxyAppPermissions>;
+    resolve(source: AppPermissionsSource, options?: AppPermissionsOptions): Promise<OxyAppPermissions>;
     /**
      * Forget cached answers: every one, or those about one person (matched as
      * either the session's user or the resolved operator).
@@ -146,5 +187,13 @@ export declare class OxyAppPermissionsResolver {
     invalidate(filter?: {
         userId?: string;
     }): void;
+    /**
+     * 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 resolveMcp;
+    private applicationIdFor;
+    private lookupMcp;
     private lookup;
 }

package/dist/types/server/callerAuthority.d.ts

@@ -36,6 +36,16 @@ export interface OxyCallerSession {
     readonly sessionId: string;
     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
@@ -113,7 +123,7 @@ export declare class CallerAuthorityCache<T> {
      *   resolved operator), for {@link invalidate}.
      */
     constructor(ttlMs: number, isAbout?: (value: T, userId: string) => boolean);
-    read(resourceKey: readonly string[], session: OxyCallerSession, fresh: boolean, lookup: () => Promise<T>): Promise<T>;
+    read(resourceKey: readonly string[], session: OxyCallerCacheKey, fresh: boolean, lookup: () => Promise<T>): Promise<T>;
     /** Forget every answer, or those about one person. */
     invalidate(filter?: {
         userId?: string;

package/dist/types/server/index.d.ts

@@ -49,7 +49,7 @@ export type { AliaMachineCredentialIntrospection, OxyAliaMachinePrincipal, OxyAl
 export type { CapabilityTicketGrant, CapabilityTicketIntrospection, CreateExecutionAuthorizationInput, ServiceCallOptions, ServiceCapabilityCatalog, ServiceUploadBody, ServiceUploadDescription, } from './namespaces';
 export { OxyAccountEventError, OXY_ACCOUNT_DELETED_EVENT_URI } from './middleware';
 export { APP_PERMISSIONS_CACHE_TTL_MS, OxyAppPermissionError, appPermissionErrorStatus, } from './appPermissions';
-export type { AppPermissionsOptions, OxyAppPermissionDenyStatus, OxyAppPermissionErrorCode, OxyAppPermissions, RequireAppPermissionOptions, } from './appPermissions';
+export type { AppPermissionsOptions, AppPermissionsSource, OxyMcpCallerRequest, OxyAppPermissionDenyStatus, OxyAppPermissionErrorCode, OxyAppPermissions, RequireAppPermissionOptions, } from './appPermissions';
 export type { AuthMiddlewareOptions, OxyAccountEvent, OxyAccountEventFeedItem, OxyAccountEventFeedPage, OxyMiddleware, RequireAccessOptions, ServiceActingAsVerification, ServiceApp, VerifyAccountEventOptions, } from './middleware';
 export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyActor, getOxyAuthRefusal, getOxyBillingPrincipal, getOxyDelegatedUserId, getOxyRequestAttribution, getOxyUserId, getRequiredOxyBillingPrincipal, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, OXY_SERVICE_ENVIRONMENTS, } from './auth';
 export type { OxyAuthHost } from './auth';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "7.19.1",
+  "version": "7.20.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/HttpService.ts

@@ -55,6 +55,12 @@ export type AccessTokenProvider = () => string | null;
  * — `null` to send it anonymous. See {@link HttpService.setAnonymousAuthProvider}.
  */
 export type AnonymousAuthProvider = () => Promise<string | null>;
+/**
+ * Told that Oxy answered 401 to a bearer an {@link AnonymousAuthProvider}
+ * supplied; `true` when it dropped that bearer, so the request is sent once
+ * more with the provider's next one.
+ */
+export type AnonymousAuthRejectedHandler = (token: string) => boolean;
 
 declare const credentialGenerationBrand: unique symbol;
 /**
@@ -604,6 +610,7 @@ export class HttpService {
   private authRefreshHandler: AuthRefreshHandler | null = null;
   private accessTokenProvider: AccessTokenProvider | null = null;
   private anonymousAuthProvider: AnonymousAuthProvider | null = null;
+  private anonymousAuthRejected: AnonymousAuthRejectedHandler | null = null;
   private deviceSecretMintInFlight: Promise<DeviceSecretMintOutcome> | null = null;
   /**
    * Bumped by every {@link endSession}. A re-mint captures it before its first
@@ -1145,6 +1152,33 @@ 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<T>({
+              ...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.
@@ -2319,9 +2353,17 @@ 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: AnonymousAuthProvider | null): void {
+  setAnonymousAuthProvider(
+    provider: AnonymousAuthProvider | null,
+    onRejected?: AnonymousAuthRejectedHandler,
+  ): void {
     this.anonymousAuthProvider = provider;
+    this.anonymousAuthRejected = provider ? (onRejected ?? null) : null;
   }
 
   clearTokens(): void {

package/src/server/OxyServer.ts

@@ -66,7 +66,7 @@ import { OxyServices, type OxyConfig } from '../OxyServices';
 import { HttpService } from '../HttpService';
 import { createAuthenticatedFetch } from '../authenticatedFetch';
 import { awaitRequestSignal } from '../utils/requestSignal';
-import { createCancelledError } from '../utils/errorUtils';
+import { createCancelledError, extractErrorStatus } from '../utils/errorUtils';
 import type { HttpMethod, ServiceLane } from '../client/context';
 import type { RequestOptions, ResponsePayload } from '../HttpService';
 import { logger } from '../logger';
@@ -94,7 +94,7 @@ import {
   APP_PERMISSIONS_CACHE_TTL_MS,
   OxyAppPermissionsResolver,
   type AppPermissionsOptions,
-  type AppPermissionsRequest,
+  type AppPermissionsSource,
   type OxyAppPermissions,
 } from './appPermissions';
 import {
@@ -365,7 +365,10 @@ 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) {
@@ -381,6 +384,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,
@@ -873,8 +877,7 @@ export class OxyServer extends OxyServices {
       serviceTokenScopes,
       ...rest
     } = options;
-    const token = await this.platformServiceToken({ scopes: serviceTokenScopes });
-    const merged: Record<string, string> = { ...headers, Authorization: `Bearer ${token}` };
+    const merged: Record<string, string> = { ...headers };
     if (actAs) merged['X-Oxy-User-Id'] = actAs;
     if (
       [requesterToken, taskId, capabilityTicket, requesterContext].filter(
@@ -886,16 +889,52 @@ export class OxyServer extends OxyServices {
     if (taskId) merged['X-Oxy-Task-Id'] = taskId;
     if (capabilityTicket) merged['X-Oxy-Capability-Ticket'] = capabilityTicket;
     if (requesterContext) merged['X-Oxy-Requester-Context'] = requesterContext;
-    return this.request<T>(method, target.href, data, {
-      cache: false,
-      ...rest,
-      ...([requesterToken, taskId, capabilityTicket, requesterContext].some(
-        (proof) => proof !== undefined,
-      )
-        ? { cache: false, deduplicate: false, retry: false }
-        : {}),
-      headers: merged,
-    });
+    const send = (token: string) =>
+      this.request<T>(method, target.href, data, {
+        cache: false,
+        ...rest,
+        ...([requesterToken, taskId, capabilityTicket, requesterContext].some(
+          (proof) => proof !== undefined,
+        )
+          ? { cache: false, deduplicate: false, retry: false }
+          : {}),
+        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.
+   */
+  private forgetServiceToken(token: string): boolean {
+    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 ────────────────────────────────────────────────────
@@ -906,6 +945,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
@@ -914,7 +959,7 @@ export class OxyServer extends OxyServices {
    * "nothing held" for a failure.
    */
   appPermissionsFor(
-    req: AppPermissionsRequest,
+    req: AppPermissionsSource,
     options: AppPermissionsOptions = {},
   ): Promise<OxyAppPermissions> {
     return this.appPermissions.resolve(req, options);
@@ -1047,6 +1092,15 @@ export class OxyServer extends OxyServices {
     );
   }
 
+  private fetchMcpAppPermissions(mcpAccessToken: string): Promise<unknown> {
+    return this.serviceRequest<unknown>(
+      'POST',
+      '/auth/mcp/oauth/app-permissions',
+      { token: mcpAccessToken },
+      { cache: false, deduplicate: false, retry: false },
+    );
+  }
+
   // ── Delegation and account events ────────────────────────────────────────
 
   /**