@mcp-native/mcp 0.5.0 → 0.6.0

package/dist/oauth.d.ts

@@ -0,0 +1,147 @@
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import type { FetchLike, OAuthClientInformationContext, OAuthClientMetadata, OAuthClientProvider, OAuthDiscoveryState, ReconnectionScheduler, StoredOAuthClientInformation, StoredOAuthTokens, StreamableHTTPReconnectionOptions } from "@modelcontextprotocol/client";
+export { McpNativeOAuthError } from "./oauth-error.js";
+export type { McpNativeOAuthErrorCode } from "./oauth-error.js";
+export { McpNativeOAuthAuthorizationSession, McpNativeOAuthPlatformSecureStore, createMcpNativeOAuthAuthorizationSession, createMcpNativeOAuthPlatformSecureStore, } from "./oauth-native.js";
+export type { McpNativeOAuthAuthorizationSessionOptions, McpNativeOAuthAuthorizationSessionResult, McpNativeOAuthPlatformSecureStoreOptions, McpNativeOAuthSecretBackend, } from "./oauth-native.js";
+export type McpNativeOAuthCredentialScope = "all" | "client" | "discovery" | "tokens" | "verifier";
+/** Durable authorization context used only while completing its state-bound callback. */
+export interface McpNativeOAuthPendingAuthorizationRecord {
+    readonly resource: string;
+    readonly issuer?: string;
+    readonly scopes: readonly string[];
+}
+/**
+ * Host-owned durable storage for one interactive OAuth session.
+ *
+ * Production native hosts should back secrets with the OS keychain or an equivalent
+ * encrypted store. Plain files and AsyncStorage are not suitable for access tokens,
+ * refresh tokens, client secrets, PKCE verifiers, or OAuth state.
+ */
+export interface McpNativeOAuthSecureStore {
+    loadClientInformation(issuer: string): StoredOAuthClientInformation | undefined | Promise<StoredOAuthClientInformation | undefined>;
+    saveClientInformation(issuer: string, information: StoredOAuthClientInformation): void | Promise<void>;
+    loadTokens(issuer?: string): StoredOAuthTokens | undefined | Promise<StoredOAuthTokens | undefined>;
+    saveTokens(issuer: string, tokens: StoredOAuthTokens): void | Promise<void>;
+    loadCodeVerifier(): string | undefined | Promise<string | undefined>;
+    saveCodeVerifier(verifier: string): void | Promise<void>;
+    loadPendingAuthorization(): unknown | Promise<unknown>;
+    savePendingAuthorization(record: McpNativeOAuthPendingAuthorizationRecord): void | Promise<void>;
+    /** Reserves this authorization context for one live provider before state generation begins. */
+    reserveOAuthState(owner: object): void | Promise<void>;
+    /**
+     * Atomically reserves the single pending-state slot for one interactive attempt. It must
+     * fail when a state is already reserved so concurrent providers sharing a namespace cannot
+     * overwrite each other's redirect state.
+     */
+    saveOAuthState(state: string, owner: object): void | Promise<void>;
+    /**
+     * Atomically compares and claims the stored state to prevent callback replay while retaining
+     * the reservation until verifier cleanup finishes and `clearOAuthState(owner)` releases it.
+     */
+    consumeOAuthState(state: string, owner: object): boolean | Promise<boolean>;
+    /** Acquires cleanup ownership, including for a reservation left by a terminated process. */
+    claimOAuthStateForCleanup(owner: object): void | Promise<void>;
+    /** Releases a reservation owned by the calling provider. */
+    clearOAuthState(owner: object): void | Promise<void>;
+    loadDiscoveryState(): OAuthDiscoveryState | undefined | Promise<OAuthDiscoveryState | undefined>;
+    saveDiscoveryState(state: OAuthDiscoveryState): void | Promise<void>;
+    /** `verifier` and `all` invalidation must also remove the pending authorization record. */
+    invalidate(scope: McpNativeOAuthCredentialScope, issuer?: string): void | Promise<void>;
+}
+export interface McpNativeOAuthProviderOptions {
+    /** Exact protected MCP Streamable HTTP endpoint this provider may authorize. */
+    readonly serverUrl: string | URL;
+    /** Native deep link, app link, or loopback URL registered for this client. */
+    readonly redirectUrl: string | URL;
+    readonly clientMetadata: OAuthClientMetadata;
+    readonly clientMetadataUrl?: string;
+    readonly storage: McpNativeOAuthSecureStore;
+    /** Optional durable, resource-bound history used for cross-request scope-upgrade decisions. */
+    readonly scopeStore?: McpNativeOAuthScopeStore;
+    /** Must return a fresh, cryptographically random, URL-safe value for every redirect. */
+    readonly createState: () => string | Promise<string>;
+    /** Host-owned browser or authentication-session handoff. */
+    readonly openAuthorization: (authorizationUrl: URL) => void | Promise<void>;
+    /**
+     * Required before the SDK may open a new authorization request while credentials exist.
+     * `addedScopes` identifies an actual scope increase and may be empty on a repeated challenge.
+     * Return exactly `true` only after the host has applied its user-decision and retry policy.
+     */
+    readonly approveReauthorization?: (request: McpNativeOAuthReauthorizationRequest) => boolean | Promise<boolean>;
+}
+export interface McpNativeOAuthReauthorizationRequest {
+    readonly resource: string;
+    readonly issuer: string | undefined;
+    readonly currentScopes: readonly string[];
+    readonly requestedScopes: readonly string[];
+    readonly addedScopes: readonly string[];
+}
+export interface McpNativeOAuthScopeRecord {
+    readonly resource: string;
+    readonly issuer: string;
+    readonly scopes: readonly string[];
+}
+/** Host-owned durable storage for non-token OAuth scope history. */
+export interface McpNativeOAuthScopeStore {
+    load(resource: string): unknown | Promise<unknown>;
+    save(record: McpNativeOAuthScopeRecord): void | Promise<void>;
+    remove(resource: string): void | Promise<void>;
+}
+export interface McpNativeOAuthTransportOptions {
+    /** Additional non-credential headers. Authorization and Cookie are rejected. */
+    readonly headers?: Record<string, string> | readonly (readonly [string, string])[];
+    readonly fetch?: FetchLike;
+    readonly reconnectionOptions?: StreamableHTTPReconnectionOptions;
+    readonly reconnectionScheduler?: ReconnectionScheduler;
+    /**
+     * `host-approved` enables the SDK's bounded step-up retry only when the provider has
+     * an `approveReauthorization` callback. The default surfaces `InsufficientScopeError`.
+     */
+    readonly scopeEscalation?: "throw" | "host-approved";
+}
+type OAuthFinisher = Pick<StreamableHTTPClientTransport, "finishAuth">;
+/**
+ * SDK v2 OAuth provider with an explicit native-host persistence and callback boundary.
+ * Discovery, PKCE, issuer validation, token exchange, and refresh remain owned by the
+ * official SDK; this class pins their host-controlled seams.
+ */
+export declare class McpNativeOAuthClientProvider implements OAuthClientProvider {
+    #private;
+    readonly redirectUrl: URL;
+    readonly clientMetadata: OAuthClientMetadata;
+    readonly clientMetadataUrl?: string;
+    constructor(options: McpNativeOAuthProviderOptions);
+    state(): Promise<string>;
+    clientInformation(context?: OAuthClientInformationContext): Promise<StoredOAuthClientInformation | undefined>;
+    saveClientInformation(information: StoredOAuthClientInformation, context?: OAuthClientInformationContext): Promise<void>;
+    tokens(context?: OAuthClientInformationContext): Promise<StoredOAuthTokens | undefined>;
+    saveTokens(tokens: StoredOAuthTokens, context?: OAuthClientInformationContext): Promise<void>;
+    redirectToAuthorization(authorizationUrl: URL): Promise<void>;
+    saveCodeVerifier(verifier: string): Promise<void>;
+    codeVerifier(): Promise<string>;
+    validateResourceURL(serverUrl: string | URL, resource?: string): Promise<URL>;
+    saveDiscoveryState(state: OAuthDiscoveryState): Promise<void>;
+    discoveryState(): Promise<OAuthDiscoveryState | undefined>;
+    invalidateCredentials(scope: McpNativeOAuthCredentialScope): Promise<void>;
+    /**
+     * Clears an abandoned interactive attempt after the platform handoff has settled, including a
+     * reservation persisted by an earlier process. Active state setup, handoff, and callback
+     * completion cannot be cancelled through this method.
+     */
+    cancelAuthorization(): Promise<void>;
+    /**
+     * Validates an app/loopback callback before asking the SDK to redeem its code.
+     * OAuth state is consumed before token exchange, so the callback cannot be replayed.
+     */
+    finishAuthorization(finisher: OAuthFinisher, callbackUrl: string | URL): Promise<void>;
+    assertServerUrl(serverUrl: string | URL): URL;
+    hasReauthorizationApproval(): boolean;
+}
+export declare function createMcpNativeOAuthProvider(options: McpNativeOAuthProviderOptions): McpNativeOAuthClientProvider;
+/**
+ * Creates the supported protected Streamable HTTP transport profile.
+ * Scope step-up is surfaced to the host so consent can be obtained before reauthorization.
+ */
+export declare function createMcpNativeOAuthTransport(serverUrl: string | URL, provider: McpNativeOAuthClientProvider, options?: McpNativeOAuthTransportOptions): StreamableHTTPClientTransport;
+//# sourceMappingURL=oauth.d.ts.map

package/dist/oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"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"}