@mcp-z/oauth 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,71 @@
+# @mcp-z/oauth
+
+Docs: https://mcp-z.github.io/oauth
+Multi-account OAuth orchestration and token storage for MCP servers.
+
+## Common uses
+
+- Add consistent account tools to MCP servers
+- Store OAuth tokens with a shared config and storage backend
+- Reuse the same account lifecycle across Google and Microsoft providers
+
+## Install
+
+```bash
+npm install @mcp-z/oauth
+```
+
+Optional storage backends:
+
+```bash
+npm install keyv-duckdb
+npm install keyv-file
+```
+
+## Initialize token storage
+
+```bash
+npx @mcp-z/oauth init
+```
+
+This creates a `.tokens/` directory and a default config file for token storage.
+
+## Account tools and modes
+
+Use `AccountServer` to add account tools to your MCP server.
+
+### Loopback mode (multi-account)
+
+When using loopback OAuth, these tools are added:
+
+- `account-me`
+- `account-switch`
+- `account-remove`
+- `account-list`
+
+### Stateless mode (DCR/bearer)
+
+When using stateless auth (DCR/bearer tokens), only this tool is available:
+
+- `account-me`
+
+## Example
+
+```ts
+import { AccountServer } from '@mcp-z/oauth';
+
+const { tools, prompts } = AccountServer.createLoopback({
+  service: 'gmail',
+  store: tokenStore,
+  logger,
+  auth: authProvider
+});
+```
+
+## Logging helper
+
+Use `sanitizeForLoggingFormatter` to avoid leaking secrets in logs.
+
+## Requirements
+
+- Node.js >= 22

package/dist/cjs/account-utils.d.cts

@@ -0,0 +1,107 @@
+/**
+ * Account management utilities for OAuth token storage
+ *
+ * Provides account lifecycle operations (add, remove, activate) and account data
+ * access (tokens, metadata). Uses named parameters consistent with key-utils.ts.
+ */
+import type { Keyv } from 'keyv';
+import { type AccountKeyParams, type ServiceKeyParams } from './key-utils.js';
+import type { AccountInfo } from './types.js';
+/**
+ * Add account to linked accounts list and set as active if first account.
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (service, accountId)
+ *
+ * @example
+ * await addAccount(tokenStore, {
+ *   service: 'gmail',
+ *   accountId: 'alice@gmail.com'
+ * });
+ */
+export declare function addAccount(store: Keyv, params: AccountKeyParams): Promise<void>;
+/**
+ * Remove account: delete token, metadata, update linked list, and active account.
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (service, accountId)
+ *
+ * @example
+ * await removeAccount(tokenStore, {
+ *   service: 'gmail',
+ *   accountId: 'alice@gmail.com'
+ * });
+ */
+export declare function removeAccount(store: Keyv, params: AccountKeyParams): Promise<void>;
+/**
+ * Get active account ID for a service.
+ *
+ * Key: {service}:active
+ *
+ * @param store - Keyv storage instance
+ * @param params - Service identification (service)
+ * @returns Active account ID or undefined if none set
+ */
+export declare function getActiveAccount(store: Keyv, params: ServiceKeyParams): Promise<string | undefined>;
+/**
+ * Set active account ID for a service.
+ * Pass null as accountId to deactivate (clear active account).
+ *
+ * Key: {service}:active
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (service, accountId). Pass accountId: null to deactivate.
+ */
+export declare function setActiveAccount(store: Keyv, params: AccountKeyParams | (ServiceKeyParams & {
+    accountId: null;
+})): Promise<void>;
+/**
+ * Get list of linked account IDs for a service.
+ *
+ * Key: {service}:linked
+ *
+ * @param store - Keyv storage instance
+ * @param params - Service identification (service)
+ * @returns Array of account IDs (empty array if none)
+ */
+export declare function getLinkedAccounts(store: Keyv, params: ServiceKeyParams): Promise<string[]>;
+/**
+ * Get account metadata (alias, lastUsed, etc).
+ *
+ * Key: {accountId}:{service}:metadata
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (accountId, service)
+ * @returns Account info or undefined if not found
+ */
+export declare function getAccountInfo(store: Keyv, params: AccountKeyParams): Promise<AccountInfo | undefined>;
+/**
+ * Set account metadata (alias, lastUsed, etc).
+ *
+ * Key: {accountId}:{service}:metadata
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (accountId, service)
+ * @param info - Account metadata to store
+ */
+export declare function setAccountInfo(store: Keyv, params: AccountKeyParams, info: AccountInfo): Promise<void>;
+/**
+ * Get OAuth token for an account.
+ *
+ * Key: {accountId}:{service}:token
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (accountId, service)
+ * @returns Token or undefined if not found
+ */
+export declare function getToken<T>(store: Keyv, params: AccountKeyParams): Promise<T | undefined>;
+/**
+ * Set OAuth token for an account.
+ *
+ * Key: {accountId}:{service}:token
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (accountId, service)
+ * @param token - OAuth token data to store
+ */
+export declare function setToken<T>(store: Keyv, params: AccountKeyParams, token: T): Promise<void>;

package/dist/cjs/account-utils.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Account management utilities for OAuth token storage
+ *
+ * Provides account lifecycle operations (add, remove, activate) and account data
+ * access (tokens, metadata). Uses named parameters consistent with key-utils.ts.
+ */
+import type { Keyv } from 'keyv';
+import { type AccountKeyParams, type ServiceKeyParams } from './key-utils.js';
+import type { AccountInfo } from './types.js';
+/**
+ * Add account to linked accounts list and set as active if first account.
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (service, accountId)
+ *
+ * @example
+ * await addAccount(tokenStore, {
+ *   service: 'gmail',
+ *   accountId: 'alice@gmail.com'
+ * });
+ */
+export declare function addAccount(store: Keyv, params: AccountKeyParams): Promise<void>;
+/**
+ * Remove account: delete token, metadata, update linked list, and active account.
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (service, accountId)
+ *
+ * @example
+ * await removeAccount(tokenStore, {
+ *   service: 'gmail',
+ *   accountId: 'alice@gmail.com'
+ * });
+ */
+export declare function removeAccount(store: Keyv, params: AccountKeyParams): Promise<void>;
+/**
+ * Get active account ID for a service.
+ *
+ * Key: {service}:active
+ *
+ * @param store - Keyv storage instance
+ * @param params - Service identification (service)
+ * @returns Active account ID or undefined if none set
+ */
+export declare function getActiveAccount(store: Keyv, params: ServiceKeyParams): Promise<string | undefined>;
+/**
+ * Set active account ID for a service.
+ * Pass null as accountId to deactivate (clear active account).
+ *
+ * Key: {service}:active
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (service, accountId). Pass accountId: null to deactivate.
+ */
+export declare function setActiveAccount(store: Keyv, params: AccountKeyParams | (ServiceKeyParams & {
+    accountId: null;
+})): Promise<void>;
+/**
+ * Get list of linked account IDs for a service.
+ *
+ * Key: {service}:linked
+ *
+ * @param store - Keyv storage instance
+ * @param params - Service identification (service)
+ * @returns Array of account IDs (empty array if none)
+ */
+export declare function getLinkedAccounts(store: Keyv, params: ServiceKeyParams): Promise<string[]>;
+/**
+ * Get account metadata (alias, lastUsed, etc).
+ *
+ * Key: {accountId}:{service}:metadata
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (accountId, service)
+ * @returns Account info or undefined if not found
+ */
+export declare function getAccountInfo(store: Keyv, params: AccountKeyParams): Promise<AccountInfo | undefined>;
+/**
+ * Set account metadata (alias, lastUsed, etc).
+ *
+ * Key: {accountId}:{service}:metadata
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (accountId, service)
+ * @param info - Account metadata to store
+ */
+export declare function setAccountInfo(store: Keyv, params: AccountKeyParams, info: AccountInfo): Promise<void>;
+/**
+ * Get OAuth token for an account.
+ *
+ * Key: {accountId}:{service}:token
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (accountId, service)
+ * @returns Token or undefined if not found
+ */
+export declare function getToken<T>(store: Keyv, params: AccountKeyParams): Promise<T | undefined>;
+/**
+ * Set OAuth token for an account.
+ *
+ * Key: {accountId}:{service}:token
+ *
+ * @param store - Keyv storage instance
+ * @param params - Account identification (accountId, service)
+ * @param token - OAuth token data to store
+ */
+export declare function setToken<T>(store: Keyv, params: AccountKeyParams, token: T): Promise<void>;