TypeScript Types

oauth-callback

import type {
  AuthorizationCodeResult,
  AuthorizationUrlBuilder,
  GetAuthCodeOptions,
} from "oauth-callback";

AuthorizationUrlBuilder

Builds the authorization URL once the loopback listener is bound. redirect_uri and state are appended when absent (not on PAR/JAR URLs, whose request object carries them); if present they must equal the provided values exactly.

type AuthorizationUrlBuilder = (ctx: {
  /** Bound redirect URI, e.g. `http://127.0.0.1:53124/callback`: the exact value to send. */
  redirectUri: string;
  /** 32 random bytes, base64url. */
  state: string;
  /** Aborted on timeout or cancellation; pass it to any `fetch` (e.g. PAR). */
  signal: AbortSignal;
}) => string | URL | Promise<string | URL>;

GetAuthCodeOptions

interface GetAuthCodeOptions {
  /**
   * Loopback redirect URI to listen on. Builder form: defaults to `http://127.0.0.1:0/callback`
   * (port 0 = OS-assigned). URL form: taken from the URL's `redirect_uri`; required when absent.
   */
  redirectUri?: string | URL;
  /** Opens the final authorization URL. Default: system browser. Only a rejection (or throw) fails the flow. */
  launch?: (url: URL) => unknown;
  /** Milliseconds for the whole attempt; integer in [1, 2_147_483_647]. Default 300_000. */
  timeout?: number;
  signal?: AbortSignal;
  /** Static HTML served after a successful callback. */
  successHtml?: string;
  /** Static HTML served after an error callback. */
  errorHtml?: string;
}

AuthorizationCodeResult

interface AuthorizationCodeResult {
  code: string;
  /** Exact redirect URI of this flow; send it verbatim in the token request if the authorization request carried it. */
  redirectUri: string;
  /** Full callback query (`state`, `iss`, `scope`, extensions, …). */
  params: URLSearchParams;
}

OAuthCallbackError

A class, exported as a value. See OAuthCallbackError.

class OAuthCallbackError extends Error {
  readonly name: "OAuthCallbackError";
  readonly error: string;
  readonly description?: string;
  readonly uri?: string;
  readonly params: URLSearchParams;
}

Timeouts reject with a DOMException whose name is "TimeoutError"; there is no separate timeout class.

oauth-callback/mcp

import type {
  BrowserAuth,
  BrowserAuthOptions,
  CredentialStore,
} from "oauth-callback/mcp";

MCP SDK types (Client, ConnectOptions, OAuthClientProvider, OAuthClientMetadata, StoredOAuthClientInformation, StreamableHTTPClientTransportOptions) come from @modelcontextprotocol/client.

BrowserAuthOptions

interface BrowserAuthOptions {
  /** The one MCP server this provider (and its store) serves. */
  serverUrl: string | URL;
  /** Fixed loopback redirect URI, e.g. `http://127.0.0.1:8765/callback` (no port 0). */
  redirectUri: string | URL;
  /** Client name for Dynamic Client Registration; required unless `clientInformation` is set. */
  clientName?: string;
  /** Pre-registered client, instead of `clientName`; `issuer` is the MCP server's `authorization_servers` entry. */
  clientInformation?: StoredOAuthClientInformation & { issuer: string };
  /** Extra client metadata (e.g. `scope`, `grant_types`). */
  clientMetadata?: Partial<
    Omit<
      OAuthClientMetadata,
      "client_name" | "redirect_uris" | "response_types" | "application_type"
    >
  >;
  /** Credential persistence. Default: memory. */
  store?: CredentialStore;
  /** Opens the URL; only a rejection fails the flow. */
  launch?: (url: URL) => unknown;
  /** Milliseconds for one interactive authorization, browser through token exchange; bound your own transport's fetch. Default 300_000. */
  timeout?: number;
  successHtml?: string;
  errorHtml?: string;
}

BrowserAuth

interface BrowserAuth extends OAuthClientProvider {
  invalidateCredentials(
    scope: "all" | "client" | "tokens" | "verifier" | "discovery",
  ): Promise<void>; // required here
  connect(
    client: Client,
    options?: ConnectOptions & {
      transportOptions?: Omit<
        StreamableHTTPClientTransportOptions,
        "authProvider"
      >;
    },
  ): Promise<void>;
  completeAuthorization(
    transport: { finishAuth(params: URLSearchParams): Promise<void> },
    options?: { signal?: AbortSignal },
  ): Promise<void>;
}

See browserAuth.

CredentialStore

interface CredentialStore {
  /** Returns the saved text, or `undefined` when empty. */
  load(): Promise<string | undefined>;
  /** Replaces the saved text; `undefined` clears it. */
  save(value: string | undefined): Promise<void>;
}

See CredentialStore.

Runtime exports

Entry point	Values	Types
oauth-callback	getAuthCode, OAuthCallbackError	AuthorizationCodeResult, AuthorizationUrlBuilder, GetAuthCodeOptions
oauth-callback/mcp	browserAuth, fileStore	BrowserAuth, BrowserAuthOptions, CredentialStore