@mcp-z/oauth-google 1.0.0

package/dist/cjs/types.d.cts

@@ -0,0 +1,173 @@
+/**
+ * Standalone types for Google 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 { OAuth2Client } from 'google-auth-library';
+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 };
+/**
+ * Google service types that support OAuth
+ * OAuth clients support all Google services provided by googleapis
+ * @public
+ */
+export type GoogleService = 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;
+}
+/**
+ * Google OAuth configuration interface.
+ * @public
+ */
+export interface OAuthConfig {
+    clientId: string;
+    /** Optional for public clients */
+    clientSecret?: string;
+    auth: 'loopback-oauth' | 'service-account' | 'dcr';
+    /** No browser interaction when true */
+    headless: boolean;
+    /** Defaults to ephemeral loopback */
+    redirectUri?: string;
+    /** Required when auth === 'service-account' */
+    serviceAccountKeyFile?: 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 Google APIs */
+    clientId: string;
+    /** OAuth client secret (optional for public clients) */
+    clientSecret?: string;
+    /** OAuth scopes to request */
+    scope: string;
+    /** Logger instance */
+    logger?: Logger;
+}
+/**
+ * Configuration for loopback OAuth client
+ * @public
+ */
+export interface LoopbackOAuthConfig {
+    service: GoogleService;
+    clientId: string;
+    /** Optional for public clients */
+    clientSecret?: string | undefined;
+    scope: string;
+    /** No browser interaction when true */
+    headless: boolean;
+    logger: Logger;
+    tokenStore: Keyv<unknown>;
+    /** Defaults to ephemeral loopback */
+    redirectUri?: string;
+}
+/**
+ * Auth context injected into extra by middleware
+ * @public
+ */
+export interface AuthContext {
+    /**
+     * OAuth2Client ready for googleapis
+     * GUARANTEED to exist when handler runs
+     */
+    auth: OAuth2Client;
+    /**
+     * Account being used (for logging, debugging)
+     */
+    accountId: string;
+    /**
+     * User ID (multi-tenant only)
+     */
+    /**
+     * Additional metadata (e.g., service account email)
+     */
+    metadata?: {
+        serviceEmail?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * 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;
+    _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;
+    /** Google 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;
+    /** Google provider tokens */
+    providerTokens: ProviderTokens;
+    created_at: number;
+}
+/**
+ * Authentication required response type
+ * Re-exported from @mcp-z/oauth for consistency
+ * @public
+ */
+export type { AuthRequired, AuthRequiredBranch } from './schemas/index.js';

package/dist/cjs/types.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Standalone types for Google 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 { OAuth2Client } from 'google-auth-library';
+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 };
+/**
+ * Google service types that support OAuth
+ * OAuth clients support all Google services provided by googleapis
+ * @public
+ */
+export type GoogleService = 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;
+}
+/**
+ * Google OAuth configuration interface.
+ * @public
+ */
+export interface OAuthConfig {
+    clientId: string;
+    /** Optional for public clients */
+    clientSecret?: string;
+    auth: 'loopback-oauth' | 'service-account' | 'dcr';
+    /** No browser interaction when true */
+    headless: boolean;
+    /** Defaults to ephemeral loopback */
+    redirectUri?: string;
+    /** Required when auth === 'service-account' */
+    serviceAccountKeyFile?: 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 Google APIs */
+    clientId: string;
+    /** OAuth client secret (optional for public clients) */
+    clientSecret?: string;
+    /** OAuth scopes to request */
+    scope: string;
+    /** Logger instance */
+    logger?: Logger;
+}
+/**
+ * Configuration for loopback OAuth client
+ * @public
+ */
+export interface LoopbackOAuthConfig {
+    service: GoogleService;
+    clientId: string;
+    /** Optional for public clients */
+    clientSecret?: string | undefined;
+    scope: string;
+    /** No browser interaction when true */
+    headless: boolean;
+    logger: Logger;
+    tokenStore: Keyv<unknown>;
+    /** Defaults to ephemeral loopback */
+    redirectUri?: string;
+}
+/**
+ * Auth context injected into extra by middleware
+ * @public
+ */
+export interface AuthContext {
+    /**
+     * OAuth2Client ready for googleapis
+     * GUARANTEED to exist when handler runs
+     */
+    auth: OAuth2Client;
+    /**
+     * Account being used (for logging, debugging)
+     */
+    accountId: string;
+    /**
+     * User ID (multi-tenant only)
+     */
+    /**
+     * Additional metadata (e.g., service account email)
+     */
+    metadata?: {
+        serviceEmail?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * 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;
+    _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;
+    /** Google 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;
+    /** Google provider tokens */
+    providerTokens: ProviderTokens;
+    created_at: number;
+}
+/**
+ * Authentication required response type
+ * Re-exported from @mcp-z/oauth for consistency
+ * @public
+ */
+export type { AuthRequired, AuthRequiredBranch } from './schemas/index.js';

package/dist/cjs/types.js

@@ -0,0 +1,16 @@
+/**
+ * Standalone types for Google OAuth
+ * No dependencies on other @mcp-z packages except @mcp-z/oauth
+ */ // Shared types from base @mcp-z/oauth package
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "AuthRequiredError", {
+    enumerable: true,
+    get: function() {
+        return _oauth.AuthRequiredError;
+    }
+});
+var _oauth = require("@mcp-z/oauth");
+/* CJS INTEROP */ if (exports.__esModule && exports.default) { try { Object.defineProperty(exports.default, '__esModule', { value: true }); for (var key in exports) { exports.default[key] = exports[key]; } } catch (_) {}; module.exports = exports.default; }

package/dist/cjs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/oauth/oauth-google/src/types.ts"],"sourcesContent":["/**\n * Standalone types for Google OAuth\n * No dependencies on other @mcp-z packages except @mcp-z/oauth\n */\n\n// Shared types from base @mcp-z/oauth package\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 { OAuth2Client } from 'google-auth-library';\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// Re-export additional types for internal package use\nexport type { ToolHandler, AuthFlowDescriptor, OAuth2TokenStorageProvider, UserAuthProvider, RequestHandlerExtra, ServerRequest, ServerNotification };\n\n/**\n * Google service types that support OAuth\n * OAuth clients support all Google services provided by googleapis\n * @public\n */\nexport type GoogleService = 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}\n\n/**\n * Google OAuth configuration interface.\n * @public\n */\nexport interface OAuthConfig {\n  clientId: string;\n  /** Optional for public clients */\n  clientSecret?: string;\n  auth: 'loopback-oauth' | 'service-account' | 'dcr';\n  /** No browser interaction when true */\n  headless: boolean;\n  /** Defaults to ephemeral loopback */\n  redirectUri?: string;\n  /** Required when auth === 'service-account' */\n  serviceAccountKeyFile?: 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 Google APIs */\n  clientId: string;\n  /** OAuth client secret (optional for public clients) */\n  clientSecret?: 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  service: GoogleService;\n  clientId: string;\n  /** Optional for public clients */\n  clientSecret?: string | undefined;\n  scope: string;\n  /** No browser interaction when true */\n  headless: boolean;\n  logger: Logger;\n  tokenStore: Keyv<unknown>;\n  /** Defaults to ephemeral loopback */\n  redirectUri?: string;\n}\n\n// =============================================================================\n// Middleware Types\n// =============================================================================\n\n/**\n * Auth context injected into extra by middleware\n * @public\n */\nexport interface AuthContext {\n  /**\n   * OAuth2Client ready for googleapis\n   * GUARANTEED to exist when handler runs\n   */\n  auth: OAuth2Client;\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   * Additional metadata (e.g., service account email)\n   */\n  metadata?: {\n    serviceEmail?: string;\n    [key: string]: unknown;\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  // 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  /** Google 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  /** Google provider tokens */\n  providerTokens: ProviderTokens;\n  created_at: number;\n}\n\n// =============================================================================\n// Schema Types\n// =============================================================================\n\n/**\n * Authentication required response type\n * Re-exported from @mcp-z/oauth for consistency\n * @public\n */\nexport type { AuthRequired, AuthRequiredBranch } from './schemas/index.ts';\n"],"names":["AuthRequiredError"],"mappings":"AAAA;;;CAGC,GAED,8CAA8C;;;;;+BAWrCA;;;eAAAA,wBAAiB;;;qBAAQ"}

package/dist/esm/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @mcp-z/oauth-google - Shared Google OAuth implementation
+ *
+ * Provides OAuth authentication:
+ * - Loopback OAuth (RFC 8252) - Server-managed, file-based tokens
+ * - Service Account authentication for server-to-server scenarios
+ */
+export { createDcrRouter, type DcrRouterConfig } from './lib/dcr-router.js';
+export { type VerificationResult, verifyBearerToken } from './lib/dcr-verify.js';
+export { type AuthInfo, DcrTokenVerifier } from './lib/token-verifier.js';
+export { DcrOAuthProvider, type DcrOAuthProviderConfig } from './providers/dcr.js';
+export { LoopbackOAuthProvider } from './providers/loopback-oauth.js';
+export { type ServiceAccountConfig, ServiceAccountProvider } from './providers/service-account.js';
+export * as schemas from './schemas/index.js';
+export { createConfig, parseConfig, parseDcrConfig } from './setup/config.js';
+export * from './types.js';

package/dist/esm/index.js

@@ -0,0 +1,16 @@
+/**
+ * @mcp-z/oauth-google - Shared Google OAuth implementation
+ *
+ * Provides OAuth authentication:
+ * - Loopback OAuth (RFC 8252) - Server-managed, file-based tokens
+ * - Service Account authentication for server-to-server scenarios
+ */ export { createDcrRouter } from './lib/dcr-router.js';
+export { verifyBearerToken } from './lib/dcr-verify.js';
+export { DcrTokenVerifier } from './lib/token-verifier.js';
+export { DcrOAuthProvider } from './providers/dcr.js';
+export { LoopbackOAuthProvider } from './providers/loopback-oauth.js';
+export { ServiceAccountProvider } from './providers/service-account.js';
+import * as _schemas from './schemas/index.js';
+export { _schemas as schemas };
+export { createConfig, parseConfig, parseDcrConfig } from './setup/config.js';
+export * from './types.js';

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/oauth/oauth-google/src/index.ts"],"sourcesContent":["/**\n * @mcp-z/oauth-google - Shared Google OAuth implementation\n *\n * Provides OAuth authentication:\n * - Loopback OAuth (RFC 8252) - Server-managed, file-based tokens\n * - Service Account authentication for server-to-server scenarios\n */\n\nexport { createDcrRouter, type DcrRouterConfig } from './lib/dcr-router.ts';\nexport { type VerificationResult, verifyBearerToken } from './lib/dcr-verify.ts';\nexport { type AuthInfo, DcrTokenVerifier } from './lib/token-verifier.ts';\nexport { DcrOAuthProvider, type DcrOAuthProviderConfig } from './providers/dcr.ts';\nexport { LoopbackOAuthProvider } from './providers/loopback-oauth.ts';\nexport { type ServiceAccountConfig, ServiceAccountProvider } from './providers/service-account.ts';\nexport * as schemas from './schemas/index.ts';\nexport { createConfig, parseConfig, parseDcrConfig } from './setup/config.ts';\nexport * from './types.ts';\n"],"names":["createDcrRouter","verifyBearerToken","DcrTokenVerifier","DcrOAuthProvider","LoopbackOAuthProvider","ServiceAccountProvider","schemas","createConfig","parseConfig","parseDcrConfig"],"mappings":"AAAA;;;;;;CAMC,GAED,SAASA,eAAe,QAA8B,sBAAsB;AAC5E,SAAkCC,iBAAiB,QAAQ,sBAAsB;AACjF,SAAwBC,gBAAgB,QAAQ,0BAA0B;AAC1E,SAASC,gBAAgB,QAAqC,qBAAqB;AACnF,SAASC,qBAAqB,QAAQ,gCAAgC;AACtE,SAAoCC,sBAAsB,QAAQ,iCAAiC;AACnG,0BAAyB,qBAAqB;AAA9C,SAAO,YAAKC,OAAO,GAA2B;AAC9C,SAASC,YAAY,EAAEC,WAAW,EAAEC,cAAc,QAAQ,oBAAoB;AAC9E,cAAc,aAAa"}

package/dist/esm/lib/dcr-router.d.ts

@@ -0,0 +1,44 @@
+/**
+ * DCR Router - OAuth 2.0 Authorization Server
+ *
+ * Implements OAuth 2.0 Dynamic Client Registration Protocol (RFC 7591)
+ * and OAuth 2.0 Authorization Server endpoints (RFC 6749, RFC 8414, RFC 9728).
+ *
+ * Endpoints:
+ * - GET /.well-known/oauth-authorization-server (RFC 8414 metadata)
+ * - GET /.well-known/oauth-protected-resource (RFC 9728 metadata - root)
+ * - GET /.well-known/oauth-protected-resource/mcp (RFC 9728 metadata - sub-path)
+ * - POST /oauth/register (RFC 7591 client registration)
+ * - GET /oauth/authorize (RFC 6749 authorization endpoint)
+ * - POST /oauth/token (RFC 6749 token endpoint)
+ * - POST /oauth/revoke (RFC 7009 token revocation)
+ * - GET /oauth/verify (token verification for Resource Server)
+ */
+import express from 'express';
+import type { Keyv } from 'keyv';
+import type { OAuthClientConfig } from '../types.js';
+/**
+ * Configuration for DCR Router (self-hosted mode only)
+ */
+export interface DcrRouterConfig {
+    /** Single Keyv store for all DCR data */
+    store: Keyv;
+    /** Authorization Server issuer URL */
+    issuerUrl: string;
+    /** Base URL for OAuth endpoints */
+    baseUrl: string;
+    /** Supported OAuth scopes */
+    scopesSupported: string[];
+    /** OAuth client configuration for upstream provider */
+    clientConfig: OAuthClientConfig;
+}
+/**
+ * Create DCR Router with OAuth 2.0 endpoints (self-hosted mode)
+ *
+ * For external mode (Auth0/Stitch), don't call this function - no router needed.
+ * The server code should check DcrConfig.mode and only call this for 'self-hosted'.
+ *
+ * @param config - Router configuration
+ * @returns Express router with OAuth endpoints
+ */
+export declare function createDcrRouter(config: DcrRouterConfig): express.Router;