@mcp-z/oauth-google 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kevin Malakoff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# @mcp-z/oauth-google
+
+Docs: https://mcp-z.github.io/oauth-google
+OAuth client for Google APIs with multi-account support and PKCE.
+
+## Common uses
+
+- Gmail/Drive/Sheets OAuth in MCP servers
+- CLI and desktop OAuth flows
+- Service account auth for server-to-server access
+- DCR (self-hosted) for shared HTTP servers
+
+## Install
+
+```bash
+npm install @mcp-z/oauth-google keyv
+```
+
+## Create a Google Cloud app
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/).
+2. Create or select a project.
+3. Enable the API you need (Gmail, Drive, or Sheets).
+4. Create OAuth 2.0 credentials (Desktop app).
+5. Copy the Client ID and Client Secret.
+
+## OAuth modes
+
+### Loopback OAuth (interactive)
+
+```ts
+import { LoopbackOAuthProvider } from '@mcp-z/oauth-google';
+import Keyv from 'keyv';
+import { KeyvFile } from 'keyv-file';
+
+const provider = new LoopbackOAuthProvider({
+  service: 'gmail',
+  clientId: process.env.GOOGLE_CLIENT_ID!,
+  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+  scope: 'https://www.googleapis.com/auth/gmail.modify',
+  tokenStore: new Keyv({ store: new KeyvFile({ filename: '.tokens/google.json' }) })
+});
+```
+
+### Service account
+
+```ts
+import { ServiceAccountProvider } from '@mcp-z/oauth-google';
+
+const provider = new ServiceAccountProvider({
+  keyFilePath: '/path/to/service-account.json',
+  scopes: ['https://www.googleapis.com/auth/drive']
+});
+```
+
+### DCR (self-hosted)
+
+Use `DcrOAuthProvider` for bearer validation and `createDcrRouter` to host the DCR endpoints.
+
+```ts
+import { DcrOAuthProvider, createDcrRouter } from '@mcp-z/oauth-google';
+
+const provider = new DcrOAuthProvider({
+  clientId: process.env.GOOGLE_CLIENT_ID!,
+  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+  scope: 'openid email profile',
+  verifyEndpoint: 'https://your-host.com/oauth/verify'
+});
+
+const router = createDcrRouter({
+  store,
+  issuerUrl: 'https://your-host.com',
+  baseUrl: 'https://your-host.com',
+  scopesSupported: ['openid', 'email', 'profile'],
+  clientConfig: {
+    clientId: process.env.GOOGLE_CLIENT_ID!,
+    clientSecret: process.env.GOOGLE_CLIENT_SECRET!
+  }
+});
+```
+
+## Config helpers
+
+Use `parseConfig()` and `parseDcrConfig()` to load CLI + env settings for servers.
+
+## Schemas and handler types
+
+- `schemas` - Shared Zod schemas used by tools
+- `EnrichedExtra` - Handler extra type with auth context
+
+## Requirements
+
+- Node.js >= 22

package/dist/cjs/index.d.cts

@@ -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/cjs/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/cjs/index.js

@@ -0,0 +1,112 @@
+/**
+ * @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
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get DcrOAuthProvider () {
+        return _dcrts.DcrOAuthProvider;
+    },
+    get DcrTokenVerifier () {
+        return _tokenverifierts.DcrTokenVerifier;
+    },
+    get LoopbackOAuthProvider () {
+        return _loopbackoauthts.LoopbackOAuthProvider;
+    },
+    get ServiceAccountProvider () {
+        return _serviceaccountts.ServiceAccountProvider;
+    },
+    get createConfig () {
+        return _configts.createConfig;
+    },
+    get createDcrRouter () {
+        return _dcrrouterts.createDcrRouter;
+    },
+    get parseConfig () {
+        return _configts.parseConfig;
+    },
+    get parseDcrConfig () {
+        return _configts.parseDcrConfig;
+    },
+    get schemas () {
+        return _indexts;
+    },
+    get verifyBearerToken () {
+        return _dcrverifyts.verifyBearerToken;
+    }
+});
+var _dcrrouterts = require("./lib/dcr-router.js");
+var _dcrverifyts = require("./lib/dcr-verify.js");
+var _tokenverifierts = require("./lib/token-verifier.js");
+var _dcrts = require("./providers/dcr.js");
+var _loopbackoauthts = require("./providers/loopback-oauth.js");
+var _serviceaccountts = require("./providers/service-account.js");
+var _indexts = /*#__PURE__*/ _interop_require_wildcard(require("./schemas/index.js"));
+var _configts = require("./setup/config.js");
+_export_star(require("./types.js"), exports);
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}
+function _getRequireWildcardCache(nodeInterop) {
+    if (typeof WeakMap !== "function") return null;
+    var cacheBabelInterop = new WeakMap();
+    var cacheNodeInterop = new WeakMap();
+    return (_getRequireWildcardCache = function(nodeInterop) {
+        return nodeInterop ? cacheNodeInterop : cacheBabelInterop;
+    })(nodeInterop);
+}
+function _interop_require_wildcard(obj, nodeInterop) {
+    if (!nodeInterop && obj && obj.__esModule) {
+        return obj;
+    }
+    if (obj === null || typeof obj !== "object" && typeof obj !== "function") {
+        return {
+            default: obj
+        };
+    }
+    var cache = _getRequireWildcardCache(nodeInterop);
+    if (cache && cache.has(obj)) {
+        return cache.get(obj);
+    }
+    var newObj = {
+        __proto__: null
+    };
+    var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor;
+    for(var key in obj){
+        if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) {
+            var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null;
+            if (desc && (desc.get || desc.set)) {
+                Object.defineProperty(newObj, key, desc);
+            } else {
+                newObj[key] = obj[key];
+            }
+        }
+    }
+    newObj.default = obj;
+    if (cache) {
+        cache.set(obj, newObj);
+    }
+    return newObj;
+}
+/* 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/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":["DcrOAuthProvider","DcrTokenVerifier","LoopbackOAuthProvider","ServiceAccountProvider","createConfig","createDcrRouter","parseConfig","parseDcrConfig","schemas","verifyBearerToken"],"mappings":"AAAA;;;;;;CAMC;;;;;;;;;;;QAKQA;eAAAA,uBAAgB;;QADDC;eAAAA,iCAAgB;;QAE/BC;eAAAA,sCAAqB;;QACMC;eAAAA,wCAAsB;;QAEjDC;eAAAA,sBAAY;;QAPZC;eAAAA,4BAAe;;QAODC;eAAAA,qBAAW;;QAAEC;eAAAA,wBAAc;;QADtCC;;;QALsBC;eAAAA,8BAAiB;;;2BADG;2BACK;+BACX;qBACc;+BACxB;gCAC4B;+DACzC;wBACiC;qBAC5C"}

package/dist/cjs/lib/dcr-router.d.cts

@@ -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;

package/dist/cjs/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;