@mcp-z/oauth 1.0.0

package/dist/cjs/lib/dcr-types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/oauth/oauth/src/lib/dcr-types.ts"],"sourcesContent":["/**\n * Dynamic Client Registration (DCR) types per RFC 7591\n *\n * Defines core types for OAuth 2.0 Dynamic Client Registration Protocol.\n * Used by providers to register clients dynamically with authorization servers.\n *\n * @see https://datatracker.ietf.org/doc/html/rfc7591\n */\n\nimport type { Logger } from '../types.ts';\n\n/**\n * Client metadata for dynamic registration request (RFC 7591 Section 2)\n *\n * All fields are optional per RFC 7591. Authorization server may have\n * required fields or default values based on policy.\n */\nexport interface DcrClientMetadata {\n  /** Array of redirection URI strings for redirect-based flows */\n  redirect_uris?: string[];\n\n  /** Client authentication method for token endpoint */\n  token_endpoint_auth_method?: 'none' | 'client_secret_post' | 'client_secret_basic';\n\n  /** OAuth 2.0 grant types the client may use */\n  grant_types?: string[];\n\n  /** OAuth 2.0 response types the client may use */\n  response_types?: string[];\n\n  /** Human-readable client name */\n  client_name?: string;\n\n  /** URL providing information about the client */\n  client_uri?: string;\n\n  /** URL referencing a logo for the client */\n  logo_uri?: string;\n\n  /** Space-separated list of scope values */\n  scope?: string;\n\n  /** Array of contact strings (typically email addresses) */\n  contacts?: string[];\n\n  /** URL pointing to terms of service document */\n  tos_uri?: string;\n\n  /** URL pointing to privacy policy document */\n  policy_uri?: string;\n\n  /** URL referencing the client's JSON Web Key Set */\n  jwks_uri?: string;\n\n  /** Client's JSON Web Key Set document value */\n  jwks?: object;\n\n  /** Unique identifier for the client software */\n  software_id?: string;\n\n  /** Version identifier for the client software */\n  software_version?: string;\n\n  /** JWT containing client metadata claims (signed software statement) */\n  software_statement?: string;\n}\n\n/**\n * Client information response from successful registration (RFC 7591 Section 3.2.1)\n *\n * Authorization server returns client credentials and echoes/modifies metadata.\n * client_id is always returned, client_secret is optional for public clients.\n */\nexport interface DcrClientInformation {\n  /** REQUIRED: OAuth 2.0 client identifier string */\n  client_id: string;\n\n  /** OPTIONAL: OAuth 2.0 client secret (omitted for public clients) */\n  client_secret?: string;\n\n  /** OPTIONAL: Timestamp of client ID issuance (seconds since Unix epoch) */\n  client_id_issued_at?: number;\n\n  /**\n   * REQUIRED if client_secret issued: Expiration timestamp (seconds since epoch)\n   * Value of 0 indicates the secret does not expire\n   */\n  client_secret_expires_at?: number;\n\n  // All registered metadata fields (echoed or server-modified)\n  redirect_uris?: string[];\n  token_endpoint_auth_method?: string;\n  grant_types?: string[];\n  response_types?: string[];\n  client_name?: string;\n  client_uri?: string;\n  logo_uri?: string;\n  scope?: string;\n  contacts?: string[];\n  tos_uri?: string;\n  policy_uri?: string;\n  jwks_uri?: string;\n  jwks?: object;\n  software_id?: string;\n  software_version?: string;\n}\n\n/**\n * Provider tokens for stateless DCR pattern\n *\n * In stateless mode, DCR provider receives provider credentials from context\n * rather than managing token storage. Used for MCP server deployments where\n * client manages all tokens.\n */\nexport interface ProviderTokens {\n  /** OAuth 2.0 access token for provider API calls */\n  accessToken: string;\n\n  /** Optional refresh token for token renewal */\n  refreshToken?: string;\n\n  /** Token expiration timestamp (seconds since Unix epoch) */\n  expiresAt?: number;\n\n  /** Space-separated list of granted scopes */\n  scope?: string;\n}\n\n/**\n * Configuration for DCR provider initialization\n *\n * Minimal config for creating DCR provider instances. Additional provider-specific\n * config (client IDs, secrets, redirect URIs) handled by concrete implementations.\n */\nexport interface DcrConfig {\n  /** Authorization server's registration endpoint URL */\n  registrationEndpoint: string;\n\n  /** Client metadata to register with authorization server */\n  metadata: DcrClientMetadata;\n\n  /** Optional logger for DCR operations */\n  logger?: Logger;\n}\n\n/**\n * DCR error response per RFC 7591 Section 3.2.2\n *\n * Authorization server returns HTTP 400 with error details when\n * registration fails due to invalid metadata or policy violations.\n */\nexport interface DcrErrorResponse {\n  /** REQUIRED: Single ASCII error code string */\n  error: 'invalid_redirect_uri' | 'invalid_client_metadata' | 'invalid_software_statement' | 'unapproved_software_statement' | string;\n\n  /** OPTIONAL: Human-readable ASCII description */\n  error_description?: string;\n}\n"],"names":[],"mappings":"AAAA;;;;;;;CAOC"}

package/dist/cjs/lib/rfc-metadata-types.d.cts

@@ -0,0 +1,46 @@
+/**
+ * RFC 8414 Authorization Server Metadata
+ * @see https://www.rfc-editor.org/rfc/rfc8414.html
+ */
+export interface RFC8414Metadata {
+    /** Authorization server issuer URL */
+    issuer: string;
+    /** OAuth 2.0 authorization endpoint */
+    authorization_endpoint: string;
+    /** OAuth 2.0 token endpoint */
+    token_endpoint: string;
+    /** Dynamic Client Registration endpoint (RFC 7591) */
+    registration_endpoint: string;
+    /** Optional: Token revocation endpoint */
+    revocation_endpoint?: string;
+    /** Optional: Supported OAuth scopes */
+    scopes_supported?: string[];
+    /** Optional: Supported response types */
+    response_types_supported?: string[];
+    /** Optional: Supported grant types */
+    grant_types_supported?: string[];
+    /** Optional: Supported token endpoint auth methods */
+    token_endpoint_auth_methods_supported?: string[];
+    /** Optional: Supported PKCE code challenge methods (RFC 7636) */
+    code_challenge_methods_supported?: string[];
+    /** Optional: Service documentation URL */
+    service_documentation?: string;
+    /** Allow additional provider-specific fields */
+    [key: string]: unknown;
+}
+/**
+ * RFC 9728 Protected Resource Metadata
+ * @see https://www.rfc-editor.org/rfc/rfc9728.html
+ */
+export interface RFC9728Metadata {
+    /** Protected resource URL */
+    resource: string;
+    /** List of authorization servers that can issue tokens for this resource */
+    authorization_servers: string[];
+    /** OAuth scopes supported by this resource */
+    scopes_supported: string[];
+    /** Methods for providing bearer tokens (typically ['header']) */
+    bearer_methods_supported: string[];
+    /** Allow additional provider-specific fields */
+    [key: string]: unknown;
+}

package/dist/cjs/lib/rfc-metadata-types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * RFC 8414 Authorization Server Metadata
+ * @see https://www.rfc-editor.org/rfc/rfc8414.html
+ */
+export interface RFC8414Metadata {
+    /** Authorization server issuer URL */
+    issuer: string;
+    /** OAuth 2.0 authorization endpoint */
+    authorization_endpoint: string;
+    /** OAuth 2.0 token endpoint */
+    token_endpoint: string;
+    /** Dynamic Client Registration endpoint (RFC 7591) */
+    registration_endpoint: string;
+    /** Optional: Token revocation endpoint */
+    revocation_endpoint?: string;
+    /** Optional: Supported OAuth scopes */
+    scopes_supported?: string[];
+    /** Optional: Supported response types */
+    response_types_supported?: string[];
+    /** Optional: Supported grant types */
+    grant_types_supported?: string[];
+    /** Optional: Supported token endpoint auth methods */
+    token_endpoint_auth_methods_supported?: string[];
+    /** Optional: Supported PKCE code challenge methods (RFC 7636) */
+    code_challenge_methods_supported?: string[];
+    /** Optional: Service documentation URL */
+    service_documentation?: string;
+    /** Allow additional provider-specific fields */
+    [key: string]: unknown;
+}
+/**
+ * RFC 9728 Protected Resource Metadata
+ * @see https://www.rfc-editor.org/rfc/rfc9728.html
+ */
+export interface RFC9728Metadata {
+    /** Protected resource URL */
+    resource: string;
+    /** List of authorization servers that can issue tokens for this resource */
+    authorization_servers: string[];
+    /** OAuth scopes supported by this resource */
+    scopes_supported: string[];
+    /** Methods for providing bearer tokens (typically ['header']) */
+    bearer_methods_supported: string[];
+    /** Allow additional provider-specific fields */
+    [key: string]: unknown;
+}

package/dist/cjs/lib/rfc-metadata-types.js

@@ -0,0 +1,8 @@
+/**
+ * RFC 8414 Authorization Server Metadata
+ * @see https://www.rfc-editor.org/rfc/rfc8414.html
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+/* 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/lib/rfc-metadata-types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/oauth/oauth/src/lib/rfc-metadata-types.ts"],"sourcesContent":["/**\n * RFC 8414 Authorization Server Metadata\n * @see https://www.rfc-editor.org/rfc/rfc8414.html\n */\nexport interface RFC8414Metadata {\n  /** Authorization server issuer URL */\n  issuer: string;\n  /** OAuth 2.0 authorization endpoint */\n  authorization_endpoint: string;\n  /** OAuth 2.0 token endpoint */\n  token_endpoint: string;\n  /** Dynamic Client Registration endpoint (RFC 7591) */\n  registration_endpoint: string;\n  /** Optional: Token revocation endpoint */\n  revocation_endpoint?: string;\n  /** Optional: Supported OAuth scopes */\n  scopes_supported?: string[];\n  /** Optional: Supported response types */\n  response_types_supported?: string[];\n  /** Optional: Supported grant types */\n  grant_types_supported?: string[];\n  /** Optional: Supported token endpoint auth methods */\n  token_endpoint_auth_methods_supported?: string[];\n  /** Optional: Supported PKCE code challenge methods (RFC 7636) */\n  code_challenge_methods_supported?: string[];\n  /** Optional: Service documentation URL */\n  service_documentation?: string;\n  /** Allow additional provider-specific fields */\n  [key: string]: unknown;\n}\n\n/**\n * RFC 9728 Protected Resource Metadata\n * @see https://www.rfc-editor.org/rfc/rfc9728.html\n */\nexport interface RFC9728Metadata {\n  /** Protected resource URL */\n  resource: string;\n  /** List of authorization servers that can issue tokens for this resource */\n  authorization_servers: string[];\n  /** OAuth scopes supported by this resource */\n  scopes_supported: string[];\n  /** Methods for providing bearer tokens (typically ['header']) */\n  bearer_methods_supported: string[];\n  /** Allow additional provider-specific fields */\n  [key: string]: unknown;\n}\n"],"names":[],"mappings":"AAAA;;;CAGC"}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{ "type": "commonjs" }

package/dist/cjs/pkce.d.cts

@@ -0,0 +1,36 @@
+/**
+ * PKCE (Proof Key for Code Exchange) utilities for OAuth 2.0
+ *
+ * Implements RFC 7636 PKCE extension for public OAuth clients.
+ * Generates cryptographically secure code verifier and challenge.
+ */
+/**
+ * PKCE code verifier and challenge pair
+ */
+export interface PKCEPair {
+    /** Code verifier - random string sent to token endpoint */
+    verifier: string;
+    /** Code challenge - SHA256 hash of verifier sent to authorization endpoint */
+    challenge: string;
+}
+/**
+ * Generate PKCE code verifier and challenge pair
+ *
+ * Uses SHA-256 hashing (S256 method) as recommended by RFC 7636.
+ * Code verifier is 32 random bytes base64url-encoded (43 characters).
+ *
+ * @returns PKCE pair with verifier and challenge
+ *
+ * @example
+ * ```typescript
+ * const { verifier, challenge } = generatePKCE();
+ *
+ * // Use challenge in authorization URL
+ * authUrl.searchParams.set('code_challenge', challenge);
+ * authUrl.searchParams.set('code_challenge_method', 'S256');
+ *
+ * // Later, use verifier in token exchange
+ * tokenParams.code_verifier = verifier;
+ * ```
+ */
+export declare function generatePKCE(): PKCEPair;

package/dist/cjs/pkce.d.ts

@@ -0,0 +1,36 @@
+/**
+ * PKCE (Proof Key for Code Exchange) utilities for OAuth 2.0
+ *
+ * Implements RFC 7636 PKCE extension for public OAuth clients.
+ * Generates cryptographically secure code verifier and challenge.
+ */
+/**
+ * PKCE code verifier and challenge pair
+ */
+export interface PKCEPair {
+    /** Code verifier - random string sent to token endpoint */
+    verifier: string;
+    /** Code challenge - SHA256 hash of verifier sent to authorization endpoint */
+    challenge: string;
+}
+/**
+ * Generate PKCE code verifier and challenge pair
+ *
+ * Uses SHA-256 hashing (S256 method) as recommended by RFC 7636.
+ * Code verifier is 32 random bytes base64url-encoded (43 characters).
+ *
+ * @returns PKCE pair with verifier and challenge
+ *
+ * @example
+ * ```typescript
+ * const { verifier, challenge } = generatePKCE();
+ *
+ * // Use challenge in authorization URL
+ * authUrl.searchParams.set('code_challenge', challenge);
+ * authUrl.searchParams.set('code_challenge_method', 'S256');
+ *
+ * // Later, use verifier in token exchange
+ * tokenParams.code_verifier = verifier;
+ * ```
+ */
+export declare function generatePKCE(): PKCEPair;

package/dist/cjs/pkce.js

@@ -0,0 +1,25 @@
+/**
+ * PKCE (Proof Key for Code Exchange) utilities for OAuth 2.0
+ *
+ * Implements RFC 7636 PKCE extension for public OAuth clients.
+ * Generates cryptographically secure code verifier and challenge.
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "generatePKCE", {
+    enumerable: true,
+    get: function() {
+        return generatePKCE;
+    }
+});
+var _crypto = require("crypto");
+function generatePKCE() {
+    var verifier = (0, _crypto.randomBytes)(32).toString('base64url');
+    var challenge = (0, _crypto.createHash)('sha256').update(verifier).digest('base64url');
+    return {
+        verifier: verifier,
+        challenge: challenge
+    };
+}
+/* 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/pkce.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/oauth/oauth/src/pkce.ts"],"sourcesContent":["/**\n * PKCE (Proof Key for Code Exchange) utilities for OAuth 2.0\n *\n * Implements RFC 7636 PKCE extension for public OAuth clients.\n * Generates cryptographically secure code verifier and challenge.\n */\n\nimport { createHash, randomBytes } from 'crypto';\n\n/**\n * PKCE code verifier and challenge pair\n */\nexport interface PKCEPair {\n  /** Code verifier - random string sent to token endpoint */\n  verifier: string;\n  /** Code challenge - SHA256 hash of verifier sent to authorization endpoint */\n  challenge: string;\n}\n\n/**\n * Generate PKCE code verifier and challenge pair\n *\n * Uses SHA-256 hashing (S256 method) as recommended by RFC 7636.\n * Code verifier is 32 random bytes base64url-encoded (43 characters).\n *\n * @returns PKCE pair with verifier and challenge\n *\n * @example\n * ```typescript\n * const { verifier, challenge } = generatePKCE();\n *\n * // Use challenge in authorization URL\n * authUrl.searchParams.set('code_challenge', challenge);\n * authUrl.searchParams.set('code_challenge_method', 'S256');\n *\n * // Later, use verifier in token exchange\n * tokenParams.code_verifier = verifier;\n * ```\n */\nexport function generatePKCE(): PKCEPair {\n  const verifier = randomBytes(32).toString('base64url');\n  const challenge = createHash('sha256').update(verifier).digest('base64url');\n\n  return {\n    verifier,\n    challenge,\n  };\n}\n"],"names":["generatePKCE","verifier","randomBytes","toString","challenge","createHash","update","digest"],"mappings":"AAAA;;;;;CAKC;;;;+BAkCeA;;;eAAAA;;;sBAhCwB;AAgCjC,SAASA;IACd,IAAMC,WAAWC,IAAAA,mBAAW,EAAC,IAAIC,QAAQ,CAAC;IAC1C,IAAMC,YAAYC,IAAAA,kBAAU,EAAC,UAAUC,MAAM,CAACL,UAAUM,MAAM,CAAC;IAE/D,OAAO;QACLN,UAAAA;QACAG,WAAAA;IACF;AACF"}

package/dist/cjs/sanitizer.d.cts

@@ -0,0 +1,37 @@
+/**
+ * Data sanitization utilities for secure logging.
+ * Redacts sensitive OAuth tokens, API keys, and credentials from log output.
+ *
+ * @example
+ * ```typescript
+ * sanitizeData({ accountId: 'test@example.com', access_token: 'secret_token_value' })
+ * // { accountId: 'test@example.com', access_token: 'secr****alue' }
+ *
+ * sanitizeForLogging('Processing token', { token: 'secret_value' })
+ * // { message: 'Processing token', meta: { token: 'secr****alue' } }
+ * ```
+ */
+export declare function sanitizeData(data: unknown): unknown;
+/**
+ * Prevent log injection attacks by escaping control characters
+ * SECURITY: Critical for preventing CRLF injection (OWASP A03)
+ */
+export declare function sanitizeLogMessage(message: string, maxLength?: number): string;
+/**
+ * Sanitize log message and metadata for safe logging
+ * Applies both CRLF protection and sensitive data redaction
+ *
+ * @param message - The log message to sanitize
+ * @param meta - Optional metadata object to sanitize
+ * @param enableDataSanitization - Whether to apply sensitive data redaction (default: true)
+ * @returns Sanitized message and metadata ready for logging
+ */
+export declare function sanitizeForLogging(message: string, meta?: Record<string, unknown>, enableDataSanitization?: boolean): {
+    message: string;
+    meta: Record<string, unknown>;
+};
+export declare function sanitizeForLoggingFormatter(): {
+    log: (obj: any) => {
+        msg: string;
+    };
+};

package/dist/cjs/sanitizer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Data sanitization utilities for secure logging.
+ * Redacts sensitive OAuth tokens, API keys, and credentials from log output.
+ *
+ * @example
+ * ```typescript
+ * sanitizeData({ accountId: 'test@example.com', access_token: 'secret_token_value' })
+ * // { accountId: 'test@example.com', access_token: 'secr****alue' }
+ *
+ * sanitizeForLogging('Processing token', { token: 'secret_value' })
+ * // { message: 'Processing token', meta: { token: 'secr****alue' } }
+ * ```
+ */
+export declare function sanitizeData(data: unknown): unknown;
+/**
+ * Prevent log injection attacks by escaping control characters
+ * SECURITY: Critical for preventing CRLF injection (OWASP A03)
+ */
+export declare function sanitizeLogMessage(message: string, maxLength?: number): string;
+/**
+ * Sanitize log message and metadata for safe logging
+ * Applies both CRLF protection and sensitive data redaction
+ *
+ * @param message - The log message to sanitize
+ * @param meta - Optional metadata object to sanitize
+ * @param enableDataSanitization - Whether to apply sensitive data redaction (default: true)
+ * @returns Sanitized message and metadata ready for logging
+ */
+export declare function sanitizeForLogging(message: string, meta?: Record<string, unknown>, enableDataSanitization?: boolean): {
+    message: string;
+    meta: Record<string, unknown>;
+};
+export declare function sanitizeForLoggingFormatter(): {
+    log: (obj: any) => {
+        msg: string;
+    };
+};