@mcp-z/oauth-microsoft 1.0.0

package/dist/esm/types.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Standalone types for Microsoft OAuth
+ * No dependencies on other @mcp-z packages except @mcp-z/oauth
+ */
+import type { AuthFlowDescriptor, CachedToken, DcrClientInformation, DcrClientMetadata, Logger, OAuth2TokenStorageProvider, ProviderTokens, ToolHandler, ToolModule, UserAuthProvider } from '@mcp-z/oauth';
+import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import type { ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types.js';
+import type { Keyv } from 'keyv';
+export type { Logger, CachedToken, ToolModule, ProviderTokens, DcrClientMetadata, DcrClientInformation };
+export { AuthRequiredError } from '@mcp-z/oauth';
+export type { ToolHandler, AuthFlowDescriptor, OAuth2TokenStorageProvider, UserAuthProvider, RequestHandlerExtra, ServerRequest, ServerNotification };
+/**
+ * Microsoft service types that support OAuth
+ * OAuth clients support all Microsoft services provided by Microsoft Graph
+ * @public
+ */
+export type MicrosoftService = string;
+/**
+ * OAuth client configuration for upstream provider
+ * @public
+ */
+export interface OAuthClientConfig {
+    /** OAuth client ID for upstream provider */
+    clientId: string;
+    /** OAuth client secret (optional for some flows) */
+    clientSecret?: string;
+    /** Tenant/directory ID (for multi-tenant providers) */
+    tenantId?: string;
+}
+/**
+ * Microsoft OAuth configuration interface.
+ * Contains all OAuth-related configuration from CLI arguments and environment variables.
+ * @public
+ */
+export interface OAuthConfig {
+    /** OAuth client ID */
+    clientId: string;
+    /** OAuth client secret (optional for public clients) */
+    clientSecret?: string;
+    /** Azure AD tenant ID */
+    tenantId: string;
+    /** OAuth adapter mode */
+    auth: 'loopback-oauth' | 'device-code' | 'dcr';
+    /** Whether to run in headless mode (no browser interaction) */
+    headless: boolean;
+    /** Optional redirect URI override (defaults to ephemeral loopback) */
+    redirectUri?: string;
+}
+/**
+ * DCR configuration for dynamic client registration
+ * @public
+ */
+export interface DcrConfig {
+    /** DCR mode: self-hosted (runs own OAuth server) or external (uses Auth0/Stitch) */
+    mode: 'self-hosted' | 'external';
+    /** External verification endpoint URL (required for external mode) */
+    verifyUrl?: string;
+    /** DCR client storage URI (required for self-hosted mode) */
+    storeUri?: string;
+    /** OAuth client ID for Microsoft Graph */
+    clientId: string;
+    /** OAuth client secret (optional for public clients) */
+    clientSecret?: string;
+    /** Azure AD tenant ID */
+    tenantId: string;
+    /** OAuth scopes to request */
+    scope: string;
+    /** Logger instance */
+    logger?: Logger;
+}
+/**
+ * Configuration for loopback OAuth client
+ * @public
+ */
+export interface LoopbackOAuthConfig {
+    /** Microsoft service type (e.g., 'outlook') */
+    service: MicrosoftService;
+    /** OAuth client ID */
+    clientId: string;
+    /** OAuth client secret (optional for public clients) */
+    clientSecret?: string | undefined;
+    /** Azure AD tenant ID */
+    tenantId: string;
+    /** OAuth scopes to request */
+    scope: string;
+    /** Whether to run in headless mode (no browser interaction) */
+    headless: boolean;
+    /** Logger instance */
+    logger: Logger;
+    /** Token storage */
+    tokenStore: Keyv<unknown>;
+    /** Optional redirect URI override (defaults to ephemeral loopback) */
+    redirectUri?: string;
+}
+/**
+ * Microsoft Graph AuthenticationProvider interface
+ * Used by Microsoft Graph SDK for API authentication
+ * @public
+ */
+export interface MicrosoftAuthProvider {
+    getAccessToken: () => Promise<string>;
+}
+/**
+ * Auth context injected into extra by middleware
+ * @public
+ */
+export interface AuthContext {
+    /**
+     * Microsoft Graph AuthenticationProvider ready for Graph SDK
+     * GUARANTEED to exist when handler runs
+     */
+    auth: MicrosoftAuthProvider;
+    /**
+     * Account being used (for logging, debugging)
+     */
+    accountId: string;
+}
+/**
+ * Enriched extra with guaranteed auth context and logger
+ * Handlers receive this type - never plain RequestHandlerExtra
+ * @public
+ */
+export interface EnrichedExtra extends RequestHandlerExtra<ServerRequest, ServerNotification> {
+    /**
+     * Auth context injected by middleware
+     * GUARANTEED to exist (middleware catches auth failures)
+     */
+    authContext: AuthContext;
+    /**
+     * Logger injected by middleware
+     * GUARANTEED to exist
+     */
+    logger: Logger;
+    /**
+     * HTTP request object (for HTTP transport scenarios)
+     * Optional - present when using HTTP transport with JWT/session auth
+     */
+    req?: unknown;
+    _meta?: {
+        accountId?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Registered client with full metadata
+ * Extends DcrClientInformation with internal timestamps
+ * @internal
+ */
+export interface RegisteredClient extends DcrClientInformation {
+    /** Creation timestamp (milliseconds since epoch) */
+    created_at: number;
+}
+/**
+ * Authorization code data structure
+ * @public
+ */
+export interface AuthorizationCode {
+    code: string;
+    client_id: string;
+    redirect_uri: string;
+    scope: string;
+    code_challenge?: string;
+    code_challenge_method?: string;
+    /** Microsoft provider tokens obtained during authorization */
+    providerTokens: ProviderTokens;
+    created_at: number;
+    expires_at: number;
+}
+/**
+ * Access token data structure
+ * @public
+ */
+export interface AccessToken {
+    access_token: string;
+    token_type: 'Bearer';
+    expires_in: number;
+    refresh_token?: string;
+    scope: string;
+    client_id: string;
+    /** Microsoft provider tokens */
+    providerTokens: ProviderTokens;
+    created_at: number;
+}
+/**
+ * Auth required response interface
+ * Re-exported from @mcp-z/oauth for consistency
+ */
+export type { AuthRequired, AuthRequiredBranch } from './schemas/index.js';

package/dist/esm/types.js

@@ -0,0 +1,8 @@
+/**
+ * Standalone types for Microsoft OAuth
+ * No dependencies on other @mcp-z packages except @mcp-z/oauth
+ */ // Import shared types from base @mcp-z/oauth package
+// Public types (will be re-exported)
+// Internal-only types (not re-exported, used by providers)
+// Re-export error class
+export { AuthRequiredError } from '@mcp-z/oauth';

package/dist/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/oauth/oauth-microsoft/src/types.ts"],"sourcesContent":["/**\n * Standalone types for Microsoft OAuth\n * No dependencies on other @mcp-z packages except @mcp-z/oauth\n */\n\n// Import shared types from base @mcp-z/oauth package\n// Public types (will be re-exported)\n// Internal-only types (not re-exported, used by providers)\nimport type { AuthFlowDescriptor, CachedToken, DcrClientInformation, DcrClientMetadata, Logger, OAuth2TokenStorageProvider, ProviderTokens, ToolHandler, ToolModule, UserAuthProvider } from '@mcp-z/oauth';\nimport type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';\nimport type { ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types.js';\nimport type { Keyv } from 'keyv';\n\n// Re-export only essential shared types for public API\nexport type { Logger, CachedToken, ToolModule, ProviderTokens, DcrClientMetadata, DcrClientInformation };\n\n// Re-export error class\nexport { AuthRequiredError } from '@mcp-z/oauth';\n\n// Make internal types available for internal use without exporting\nexport type { ToolHandler, AuthFlowDescriptor, OAuth2TokenStorageProvider, UserAuthProvider, RequestHandlerExtra, ServerRequest, ServerNotification };\n\n// ============================================================================\n// Core Authentication Types\n// ============================================================================\n\n/**\n * Microsoft service types that support OAuth\n * OAuth clients support all Microsoft services provided by Microsoft Graph\n * @public\n */\nexport type MicrosoftService = string;\n\n// ============================================================================\n// Configuration Types\n// ============================================================================\n\n/**\n * OAuth client configuration for upstream provider\n * @public\n */\nexport interface OAuthClientConfig {\n  /** OAuth client ID for upstream provider */\n  clientId: string;\n  /** OAuth client secret (optional for some flows) */\n  clientSecret?: string;\n  /** Tenant/directory ID (for multi-tenant providers) */\n  tenantId?: string;\n}\n\n/**\n * Microsoft OAuth configuration interface.\n * Contains all OAuth-related configuration from CLI arguments and environment variables.\n * @public\n */\nexport interface OAuthConfig {\n  /** OAuth client ID */\n  clientId: string;\n  /** OAuth client secret (optional for public clients) */\n  clientSecret?: string;\n  /** Azure AD tenant ID */\n  tenantId: string;\n  /** OAuth adapter mode */\n  auth: 'loopback-oauth' | 'device-code' | 'dcr';\n  /** Whether to run in headless mode (no browser interaction) */\n  headless: boolean;\n  /** Optional redirect URI override (defaults to ephemeral loopback) */\n  redirectUri?: string;\n}\n\n/**\n * DCR configuration for dynamic client registration\n * @public\n */\nexport interface DcrConfig {\n  /** DCR mode: self-hosted (runs own OAuth server) or external (uses Auth0/Stitch) */\n  mode: 'self-hosted' | 'external';\n  /** External verification endpoint URL (required for external mode) */\n  verifyUrl?: string;\n  /** DCR client storage URI (required for self-hosted mode) */\n  storeUri?: string;\n  /** OAuth client ID for Microsoft Graph */\n  clientId: string;\n  /** OAuth client secret (optional for public clients) */\n  clientSecret?: string;\n  /** Azure AD tenant ID */\n  tenantId: string;\n  /** OAuth scopes to request */\n  scope: string;\n  /** Logger instance */\n  logger?: Logger;\n}\n\n/**\n * Configuration for loopback OAuth client\n * @public\n */\nexport interface LoopbackOAuthConfig {\n  /** Microsoft service type (e.g., 'outlook') */\n  service: MicrosoftService;\n  /** OAuth client ID */\n  clientId: string;\n  /** OAuth client secret (optional for public clients) */\n  clientSecret?: string | undefined;\n  /** Azure AD tenant ID */\n  tenantId: string;\n  /** OAuth scopes to request */\n  scope: string;\n  /** Whether to run in headless mode (no browser interaction) */\n  headless: boolean;\n  /** Logger instance */\n  logger: Logger;\n  /** Token storage */\n  tokenStore: Keyv<unknown>;\n  /** Optional redirect URI override (defaults to ephemeral loopback) */\n  redirectUri?: string;\n}\n\n// ============================================================================\n// Middleware Types\n// ============================================================================\n\n/**\n * Microsoft Graph AuthenticationProvider interface\n * Used by Microsoft Graph SDK for API authentication\n * @public\n */\nexport interface MicrosoftAuthProvider {\n  getAccessToken: () => Promise<string>;\n}\n\n/**\n * Auth context injected into extra by middleware\n * @public\n */\nexport interface AuthContext {\n  /**\n   * Microsoft Graph AuthenticationProvider ready for Graph SDK\n   * GUARANTEED to exist when handler runs\n   */\n  auth: MicrosoftAuthProvider;\n\n  /**\n   * Account being used (for logging, debugging)\n   */\n  accountId: string;\n\n  /**\n   * User ID (multi-tenant only)\n   */\n}\n\n/**\n * Enriched extra with guaranteed auth context and logger\n * Handlers receive this type - never plain RequestHandlerExtra\n * @public\n */\nexport interface EnrichedExtra extends RequestHandlerExtra<ServerRequest, ServerNotification> {\n  /**\n   * Auth context injected by middleware\n   * GUARANTEED to exist (middleware catches auth failures)\n   */\n  authContext: AuthContext;\n\n  /**\n   * Logger injected by middleware\n   * GUARANTEED to exist\n   */\n  logger: Logger;\n\n  /**\n   * HTTP request object (for HTTP transport scenarios)\n   * Optional - present when using HTTP transport with JWT/session auth\n   */\n  req?: unknown;\n\n  // Preserve backchannel support\n  _meta?: {\n    accountId?: string;\n    [key: string]: unknown;\n  };\n}\n\n// ============================================================================\n// DCR Internal Types\n// ============================================================================\n\n/**\n * Registered client with full metadata\n * Extends DcrClientInformation with internal timestamps\n * @internal\n */\nexport interface RegisteredClient extends DcrClientInformation {\n  /** Creation timestamp (milliseconds since epoch) */\n  created_at: number;\n}\n\n/**\n * Authorization code data structure\n * @public\n */\nexport interface AuthorizationCode {\n  code: string;\n  client_id: string;\n  redirect_uri: string;\n  scope: string;\n  code_challenge?: string;\n  code_challenge_method?: string;\n  /** Microsoft provider tokens obtained during authorization */\n  providerTokens: ProviderTokens;\n  created_at: number;\n  expires_at: number;\n}\n\n/**\n * Access token data structure\n * @public\n */\nexport interface AccessToken {\n  access_token: string;\n  token_type: 'Bearer';\n  expires_in: number;\n  refresh_token?: string;\n  scope: string;\n  client_id: string;\n  /** Microsoft provider tokens */\n  providerTokens: ProviderTokens;\n  created_at: number;\n}\n\n// ============================================================================\n// Schema Types\n// ============================================================================\n\n/**\n * Auth required response interface\n * Re-exported from @mcp-z/oauth for consistency\n */\nexport type { AuthRequired, AuthRequiredBranch } from './schemas/index.ts';\n"],"names":["AuthRequiredError"],"mappings":"AAAA;;;CAGC,GAED,qDAAqD;AACrD,qCAAqC;AACrC,2DAA2D;AAS3D,wBAAwB;AACxB,SAASA,iBAAiB,QAAQ,eAAe"}

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@mcp-z/oauth-microsoft",
+  "version": "1.0.0",
+  "description": "OAuth 2.0 client for Microsoft Graph with multi-account support, PKCE security, and swappable storage backends",
+  "keywords": [
+    "oauth2",
+    "microsoft-graph",
+    "authentication",
+    "multi-account",
+    "outlook",
+    "azure-ad",
+    "msal-alternative",
+    "pkce",
+    "graph-api",
+    "token-storage"
+  ],
+  "homepage": "https://github.com/mcp-z/oauth-microsoft#readme",
+  "bugs": {
+    "url": "https://github.com/mcp-z/oauth-microsoft/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mcp-z/oauth-microsoft.git"
+  },
+  "license": "MIT",
+  "author": "Kevin Malakoff <kmalakoff.info@gmail.com>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsds build",
+    "format": "tsds format",
+    "prepublish:check": "ncp",
+    "prepublishOnly": "tsds validate",
+    "test": "npm run test:unit && npm run test:integration",
+    "test:engines": "nvu engines tsds test:node --no-timeouts 'test/**/*.test.ts'",
+    "test:integration": "tsds test:node --no-timeouts 'test/integration/**/*.test.ts'",
+    "test:setup": "node --env-file=.env.test test/lib/setup-token.ts",
+    "test:unit": "tsds test:node --no-timeouts 'test/unit/**/*.test.ts'",
+    "version": "tsds version"
+  },
+  "dependencies": {
+    "@mcp-z/oauth": "^1.0.0",
+    "express": "^5.0.0",
+    "open": "^11.0.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@mcp-z/client": "^1.0.0",
+    "@microsoft/microsoft-graph-client": "^3.0.7",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^25.0.2",
+    "cors": "^2.0.0",
+    "dotenv": "^17.2.3",
+    "get-port": "^7.1.0",
+    "keyv": "^5.5.5",
+    "keyv-file": "^5.3.3",
+    "node-version-use": "^2.1.6",
+    "ts-dev-stack": "^1.21.3",
+    "tsds-config": "^1.0.0",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "keyv": "^5.5.5"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "tsds": {
+    "source": "src/index.ts"
+  }
+}