@frontmcp/sdk 0.4.1 → 0.5.0

package/src/auth/utils/audience.validator.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Audience Validator
+ *
+ * Validates JWT audience claims per RFC 7519 and MCP Authorization spec.
+ * The audience (aud) claim identifies the recipients that the JWT is intended for.
+ */
+/**
+ * Validation result
+ */
+export interface AudienceValidationResult {
+    /** Whether the audience is valid */
+    valid: boolean;
+    /** Error message if invalid */
+    error?: string;
+    /** Matched audience value (if valid) */
+    matchedAudience?: string;
+}
+/**
+ * Audience validator options
+ */
+export interface AudienceValidatorOptions {
+    /**
+     * Expected audience values
+     * Token must contain at least one of these audiences
+     */
+    expectedAudiences: string[];
+    /**
+     * Whether to allow tokens with no audience claim
+     * @default false
+     */
+    allowNoAudience?: boolean;
+    /**
+     * Case-sensitive comparison
+     * @default true
+     */
+    caseSensitive?: boolean;
+    /**
+     * Allow wildcard matching (e.g., *.example.com)
+     * @default false
+     */
+    allowWildcards?: boolean;
+}
+/**
+ * Validate JWT audience claim
+ *
+ * @param tokenAudience - The audience claim from the JWT (can be string or array)
+ * @param options - Validation options
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * // Single expected audience
+ * validateAudience('https://api.example.com', {
+ *   expectedAudiences: ['https://api.example.com'],
+ * });
+ * // => { valid: true, matchedAudience: 'https://api.example.com' }
+ *
+ * // Multiple audiences in token
+ * validateAudience(['aud1', 'aud2', 'aud3'], {
+ *   expectedAudiences: ['aud2'],
+ * });
+ * // => { valid: true, matchedAudience: 'aud2' }
+ *
+ * // No match
+ * validateAudience('wrong-aud', {
+ *   expectedAudiences: ['expected-aud'],
+ * });
+ * // => { valid: false, error: 'Token audience does not match expected audiences' }
+ * ```
+ */
+export declare function validateAudience(tokenAudience: string | string[] | undefined, options: AudienceValidatorOptions): AudienceValidationResult;
+/**
+ * Create an audience validator function
+ *
+ * @param options - Validator options
+ * @returns A validation function that takes token audience and returns validation result
+ *
+ * @example
+ * ```typescript
+ * const validator = createAudienceValidator({
+ *   expectedAudiences: ['https://api.example.com', 'https://api.example.org'],
+ * });
+ *
+ * validator('https://api.example.com'); // => { valid: true, ... }
+ * validator('wrong-aud'); // => { valid: false, ... }
+ * ```
+ */
+export declare function createAudienceValidator(options: AudienceValidatorOptions): (audience: string | string[] | undefined) => AudienceValidationResult;
+/**
+ * Derive expected audience from the resource URL
+ *
+ * Per MCP Authorization spec, the audience should typically be the
+ * resource server URL (the MCP server URL).
+ *
+ * @param resourceUrl - The resource server URL
+ * @returns Array of expected audiences
+ *
+ * @example
+ * ```typescript
+ * deriveExpectedAudience('https://api.example.com/v1/mcp');
+ * // => ['https://api.example.com/v1/mcp', 'https://api.example.com', 'api.example.com']
+ * ```
+ */
+export declare function deriveExpectedAudience(resourceUrl: string): string[];
+/**
+ * AudienceValidator class for reusable validation with configuration
+ */
+export declare class AudienceValidator {
+    private options;
+    constructor(options?: Partial<AudienceValidatorOptions> & {
+        expectedAudiences?: string[];
+    });
+    /**
+     * Validate an audience claim
+     */
+    validate(audience: string | string[] | undefined): AudienceValidationResult;
+    /**
+     * Add expected audiences
+     */
+    addAudiences(...audiences: string[]): void;
+    /**
+     * Set expected audiences (replace existing)
+     */
+    setAudiences(audiences: string[]): void;
+    /**
+     * Create validator from resource URL
+     */
+    static fromResourceUrl(resourceUrl: string, options?: Omit<AudienceValidatorOptions, 'expectedAudiences'>): AudienceValidator;
+}

package/src/auth/utils/audience.validator.js

@@ -0,0 +1,196 @@
+"use strict";
+// auth/utils/audience.validator.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AudienceValidator = void 0;
+exports.validateAudience = validateAudience;
+exports.createAudienceValidator = createAudienceValidator;
+exports.deriveExpectedAudience = deriveExpectedAudience;
+/**
+ * Validate JWT audience claim
+ *
+ * @param tokenAudience - The audience claim from the JWT (can be string or array)
+ * @param options - Validation options
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * // Single expected audience
+ * validateAudience('https://api.example.com', {
+ *   expectedAudiences: ['https://api.example.com'],
+ * });
+ * // => { valid: true, matchedAudience: 'https://api.example.com' }
+ *
+ * // Multiple audiences in token
+ * validateAudience(['aud1', 'aud2', 'aud3'], {
+ *   expectedAudiences: ['aud2'],
+ * });
+ * // => { valid: true, matchedAudience: 'aud2' }
+ *
+ * // No match
+ * validateAudience('wrong-aud', {
+ *   expectedAudiences: ['expected-aud'],
+ * });
+ * // => { valid: false, error: 'Token audience does not match expected audiences' }
+ * ```
+ */
+function validateAudience(tokenAudience, options) {
+    const { expectedAudiences, allowNoAudience = false, caseSensitive = true, allowWildcards = false } = options;
+    // Handle missing audience
+    if (tokenAudience === undefined || tokenAudience === null) {
+        if (allowNoAudience) {
+            return { valid: true };
+        }
+        return {
+            valid: false,
+            error: 'Token is missing audience claim',
+        };
+    }
+    // Handle empty expected audiences (accept any)
+    if (expectedAudiences.length === 0) {
+        const firstAud = Array.isArray(tokenAudience) ? tokenAudience[0] : tokenAudience;
+        return {
+            valid: false,
+            error: 'No expected audiences configured - cannot validate token',
+        };
+    }
+    // Normalize token audience to array
+    const tokenAuds = Array.isArray(tokenAudience) ? tokenAudience : [tokenAudience];
+    // Check each token audience against expected audiences
+    for (const tokenAud of tokenAuds) {
+        for (const expectedAud of expectedAudiences) {
+            if (matchesAudience(tokenAud, expectedAud, caseSensitive, allowWildcards)) {
+                return { valid: true, matchedAudience: tokenAud };
+            }
+        }
+    }
+    return {
+        valid: false,
+        error: `Token audience does not match expected audiences. Got: ${tokenAuds.join(', ')}. Expected one of: ${expectedAudiences.join(', ')}`,
+    };
+}
+/**
+ * Check if a token audience matches an expected audience
+ */
+function matchesAudience(tokenAud, expectedAud, caseSensitive, allowWildcards) {
+    // Direct match
+    if (caseSensitive) {
+        if (tokenAud === expectedAud)
+            return true;
+    }
+    else {
+        if (tokenAud.toLowerCase() === expectedAud.toLowerCase())
+            return true;
+    }
+    // Wildcard matching with ReDoS protection
+    if (allowWildcards && expectedAud.includes('*')) {
+        // Limit wildcards to prevent potential ReDoS from complex patterns
+        const wildcardCount = (expectedAud.match(/\*/g) || []).length;
+        if (wildcardCount > 2) {
+            // Reject patterns with more than 2 wildcards for safety
+            return false;
+        }
+        const pattern = expectedAud
+            .replace(/[.+?^${}()|[\]\\]/g, '\\$&') // Escape regex special chars
+            .replace(/\*/g, '[^.]*'); // Convert * to non-greedy segment match (safer than .*)
+        const regex = new RegExp(`^${pattern}$`, caseSensitive ? '' : 'i');
+        if (regex.test(tokenAud))
+            return true;
+    }
+    return false;
+}
+/**
+ * Create an audience validator function
+ *
+ * @param options - Validator options
+ * @returns A validation function that takes token audience and returns validation result
+ *
+ * @example
+ * ```typescript
+ * const validator = createAudienceValidator({
+ *   expectedAudiences: ['https://api.example.com', 'https://api.example.org'],
+ * });
+ *
+ * validator('https://api.example.com'); // => { valid: true, ... }
+ * validator('wrong-aud'); // => { valid: false, ... }
+ * ```
+ */
+function createAudienceValidator(options) {
+    return (audience) => validateAudience(audience, options);
+}
+/**
+ * Derive expected audience from the resource URL
+ *
+ * Per MCP Authorization spec, the audience should typically be the
+ * resource server URL (the MCP server URL).
+ *
+ * @param resourceUrl - The resource server URL
+ * @returns Array of expected audiences
+ *
+ * @example
+ * ```typescript
+ * deriveExpectedAudience('https://api.example.com/v1/mcp');
+ * // => ['https://api.example.com/v1/mcp', 'https://api.example.com', 'api.example.com']
+ * ```
+ */
+function deriveExpectedAudience(resourceUrl) {
+    const audiences = [];
+    try {
+        const url = new URL(resourceUrl);
+        // Full URL (most specific)
+        audiences.push(resourceUrl.replace(/\/$/, ''));
+        // Origin only (e.g., https://api.example.com)
+        if (url.pathname !== '/' && url.pathname !== '') {
+            audiences.push(url.origin);
+        }
+        // Host only (e.g., api.example.com)
+        audiences.push(url.host);
+    }
+    catch {
+        // If not a valid URL, use as-is
+        audiences.push(resourceUrl);
+    }
+    return audiences;
+}
+/**
+ * AudienceValidator class for reusable validation with configuration
+ */
+class AudienceValidator {
+    options;
+    constructor(options = {}) {
+        this.options = {
+            expectedAudiences: [...(options.expectedAudiences ?? [])],
+            allowNoAudience: options.allowNoAudience ?? false,
+            caseSensitive: options.caseSensitive ?? true,
+            allowWildcards: options.allowWildcards ?? false,
+        };
+    }
+    /**
+     * Validate an audience claim
+     */
+    validate(audience) {
+        return validateAudience(audience, this.options);
+    }
+    /**
+     * Add expected audiences
+     */
+    addAudiences(...audiences) {
+        this.options.expectedAudiences.push(...audiences);
+    }
+    /**
+     * Set expected audiences (replace existing)
+     */
+    setAudiences(audiences) {
+        this.options.expectedAudiences = audiences;
+    }
+    /**
+     * Create validator from resource URL
+     */
+    static fromResourceUrl(resourceUrl, options = {}) {
+        return new AudienceValidator({
+            ...options,
+            expectedAudiences: deriveExpectedAudience(resourceUrl),
+        });
+    }
+}
+exports.AudienceValidator = AudienceValidator;
+//# sourceMappingURL=audience.validator.js.map

package/src/auth/utils/audience.validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audience.validator.js","sourceRoot":"","sources":["../../../../src/auth/utils/audience.validator.ts"],"names":[],"mappings":"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","sourcesContent":["// auth/utils/audience.validator.ts\n\n/**\n * Audience Validator\n *\n * Validates JWT audience claims per RFC 7519 and MCP Authorization spec.\n * The audience (aud) claim identifies the recipients that the JWT is intended for.\n */\n\n/**\n * Validation result\n */\nexport interface AudienceValidationResult {\n  /** Whether the audience is valid */\n  valid: boolean;\n  /** Error message if invalid */\n  error?: string;\n  /** Matched audience value (if valid) */\n  matchedAudience?: string;\n}\n\n/**\n * Audience validator options\n */\nexport interface AudienceValidatorOptions {\n  /**\n   * Expected audience values\n   * Token must contain at least one of these audiences\n   */\n  expectedAudiences: string[];\n\n  /**\n   * Whether to allow tokens with no audience claim\n   * @default false\n   */\n  allowNoAudience?: boolean;\n\n  /**\n   * Case-sensitive comparison\n   * @default true\n   */\n  caseSensitive?: boolean;\n\n  /**\n   * Allow wildcard matching (e.g., *.example.com)\n   * @default false\n   */\n  allowWildcards?: boolean;\n}\n\n/**\n * Validate JWT audience claim\n *\n * @param tokenAudience - The audience claim from the JWT (can be string or array)\n * @param options - Validation options\n * @returns Validation result\n *\n * @example\n * ```typescript\n * // Single expected audience\n * validateAudience('https://api.example.com', {\n *   expectedAudiences: ['https://api.example.com'],\n * });\n * // => { valid: true, matchedAudience: 'https://api.example.com' }\n *\n * // Multiple audiences in token\n * validateAudience(['aud1', 'aud2', 'aud3'], {\n *   expectedAudiences: ['aud2'],\n * });\n * // => { valid: true, matchedAudience: 'aud2' }\n *\n * // No match\n * validateAudience('wrong-aud', {\n *   expectedAudiences: ['expected-aud'],\n * });\n * // => { valid: false, error: 'Token audience does not match expected audiences' }\n * ```\n */\nexport function validateAudience(\n  tokenAudience: string | string[] | undefined,\n  options: AudienceValidatorOptions,\n): AudienceValidationResult {\n  const { expectedAudiences, allowNoAudience = false, caseSensitive = true, allowWildcards = false } = options;\n\n  // Handle missing audience\n  if (tokenAudience === undefined || tokenAudience === null) {\n    if (allowNoAudience) {\n      return { valid: true };\n    }\n    return {\n      valid: false,\n      error: 'Token is missing audience claim',\n    };\n  }\n\n  // Handle empty expected audiences (accept any)\n  if (expectedAudiences.length === 0) {\n    const firstAud = Array.isArray(tokenAudience) ? tokenAudience[0] : tokenAudience;\n    return {\n      valid: false,\n      error: 'No expected audiences configured - cannot validate token',\n    };\n  }\n\n  // Normalize token audience to array\n  const tokenAuds = Array.isArray(tokenAudience) ? tokenAudience : [tokenAudience];\n\n  // Check each token audience against expected audiences\n  for (const tokenAud of tokenAuds) {\n    for (const expectedAud of expectedAudiences) {\n      if (matchesAudience(tokenAud, expectedAud, caseSensitive, allowWildcards)) {\n        return { valid: true, matchedAudience: tokenAud };\n      }\n    }\n  }\n\n  return {\n    valid: false,\n    error: `Token audience does not match expected audiences. Got: ${tokenAuds.join(\n      ', ',\n    )}. Expected one of: ${expectedAudiences.join(', ')}`,\n  };\n}\n\n/**\n * Check if a token audience matches an expected audience\n */\nfunction matchesAudience(\n  tokenAud: string,\n  expectedAud: string,\n  caseSensitive: boolean,\n  allowWildcards: boolean,\n): boolean {\n  // Direct match\n  if (caseSensitive) {\n    if (tokenAud === expectedAud) return true;\n  } else {\n    if (tokenAud.toLowerCase() === expectedAud.toLowerCase()) return true;\n  }\n\n  // Wildcard matching with ReDoS protection\n  if (allowWildcards && expectedAud.includes('*')) {\n    // Limit wildcards to prevent potential ReDoS from complex patterns\n    const wildcardCount = (expectedAud.match(/\\*/g) || []).length;\n    if (wildcardCount > 2) {\n      // Reject patterns with more than 2 wildcards for safety\n      return false;\n    }\n\n    const pattern = expectedAud\n      .replace(/[.+?^${}()|[\\]\\\\]/g, '\\\\$&') // Escape regex special chars\n      .replace(/\\*/g, '[^.]*'); // Convert * to non-greedy segment match (safer than .*)\n    const regex = new RegExp(`^${pattern}$`, caseSensitive ? '' : 'i');\n    if (regex.test(tokenAud)) return true;\n  }\n\n  return false;\n}\n\n/**\n * Create an audience validator function\n *\n * @param options - Validator options\n * @returns A validation function that takes token audience and returns validation result\n *\n * @example\n * ```typescript\n * const validator = createAudienceValidator({\n *   expectedAudiences: ['https://api.example.com', 'https://api.example.org'],\n * });\n *\n * validator('https://api.example.com'); // => { valid: true, ... }\n * validator('wrong-aud'); // => { valid: false, ... }\n * ```\n */\nexport function createAudienceValidator(\n  options: AudienceValidatorOptions,\n): (audience: string | string[] | undefined) => AudienceValidationResult {\n  return (audience) => validateAudience(audience, options);\n}\n\n/**\n * Derive expected audience from the resource URL\n *\n * Per MCP Authorization spec, the audience should typically be the\n * resource server URL (the MCP server URL).\n *\n * @param resourceUrl - The resource server URL\n * @returns Array of expected audiences\n *\n * @example\n * ```typescript\n * deriveExpectedAudience('https://api.example.com/v1/mcp');\n * // => ['https://api.example.com/v1/mcp', 'https://api.example.com', 'api.example.com']\n * ```\n */\nexport function deriveExpectedAudience(resourceUrl: string): string[] {\n  const audiences: string[] = [];\n\n  try {\n    const url = new URL(resourceUrl);\n\n    // Full URL (most specific)\n    audiences.push(resourceUrl.replace(/\\/$/, ''));\n\n    // Origin only (e.g., https://api.example.com)\n    if (url.pathname !== '/' && url.pathname !== '') {\n      audiences.push(url.origin);\n    }\n\n    // Host only (e.g., api.example.com)\n    audiences.push(url.host);\n  } catch {\n    // If not a valid URL, use as-is\n    audiences.push(resourceUrl);\n  }\n\n  return audiences;\n}\n\n/**\n * AudienceValidator class for reusable validation with configuration\n */\nexport class AudienceValidator {\n  private options: AudienceValidatorOptions;\n\n  constructor(options: Partial<AudienceValidatorOptions> & { expectedAudiences?: string[] } = {}) {\n    this.options = {\n      expectedAudiences: [...(options.expectedAudiences ?? [])],\n      allowNoAudience: options.allowNoAudience ?? false,\n      caseSensitive: options.caseSensitive ?? true,\n      allowWildcards: options.allowWildcards ?? false,\n    };\n  }\n\n  /**\n   * Validate an audience claim\n   */\n  validate(audience: string | string[] | undefined): AudienceValidationResult {\n    return validateAudience(audience, this.options);\n  }\n\n  /**\n   * Add expected audiences\n   */\n  addAudiences(...audiences: string[]): void {\n    this.options.expectedAudiences.push(...audiences);\n  }\n\n  /**\n   * Set expected audiences (replace existing)\n   */\n  setAudiences(audiences: string[]): void {\n    this.options.expectedAudiences = audiences;\n  }\n\n  /**\n   * Create validator from resource URL\n   */\n  static fromResourceUrl(\n    resourceUrl: string,\n    options: Omit<AudienceValidatorOptions, 'expectedAudiences'> = {},\n  ): AudienceValidator {\n    return new AudienceValidator({\n      ...options,\n      expectedAudiences: deriveExpectedAudience(resourceUrl),\n    });\n  }\n}\n"]}

package/src/auth/utils/index.d.ts

@@ -0,0 +1,2 @@
+export * from './www-authenticate.utils';
+export * from './audience.validator';

package/src/auth/utils/index.js

@@ -0,0 +1,7 @@
+"use strict";
+// auth/utils/index.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./www-authenticate.utils"), exports);
+tslib_1.__exportStar(require("./audience.validator"), exports);
+//# sourceMappingURL=index.js.map

package/src/auth/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/auth/utils/index.ts"],"names":[],"mappings":";AAAA,sBAAsB;;;AAEtB,mEAAyC;AACzC,+DAAqC","sourcesContent":["// auth/utils/index.ts\n\nexport * from './www-authenticate.utils';\nexport * from './audience.validator';\n"]}

package/src/auth/utils/www-authenticate.utils.d.ts

@@ -0,0 +1,97 @@
+/**
+ * WWW-Authenticate Header Builder
+ *
+ * Implements RFC 9728 (OAuth 2.0 Protected Resource Metadata) and
+ * RFC 6750 (Bearer Token Usage) compliant WWW-Authenticate headers.
+ */
+/**
+ * Error codes per RFC 6750 Section 3.1
+ */
+export type BearerErrorCode = 'invalid_request' | 'invalid_token' | 'insufficient_scope';
+/**
+ * Options for building WWW-Authenticate header
+ */
+export interface WwwAuthenticateOptions {
+    /**
+     * The resource_metadata URL pointing to the PRM document
+     * Per RFC 9728, this is the primary mechanism for resource discovery
+     */
+    resourceMetadataUrl?: string;
+    /**
+     * OAuth 2.0 realm (optional per RFC 6750)
+     */
+    realm?: string;
+    /**
+     * Required scopes for the resource (space-delimited)
+     */
+    scope?: string | string[];
+    /**
+     * Error code when authentication fails
+     */
+    error?: BearerErrorCode;
+    /**
+     * Human-readable error description
+     */
+    errorDescription?: string;
+    /**
+     * Error URI pointing to additional information
+     */
+    errorUri?: string;
+}
+/**
+ * Build a WWW-Authenticate header for Bearer authentication
+ *
+ * @param options - Header options
+ * @returns The formatted WWW-Authenticate header value
+ *
+ * @example
+ * ```typescript
+ * // Basic protected resource metadata header
+ * buildWwwAuthenticate({
+ *   resourceMetadataUrl: 'https://api.example.com/.well-known/oauth-protected-resource',
+ * });
+ * // => 'Bearer resource_metadata="https://api.example.com/.well-known/oauth-protected-resource"'
+ *
+ * // With error information
+ * buildWwwAuthenticate({
+ *   resourceMetadataUrl: 'https://api.example.com/.well-known/oauth-protected-resource',
+ *   error: 'insufficient_scope',
+ *   scope: ['read', 'write'],
+ *   errorDescription: 'Additional permissions required',
+ * });
+ * // => 'Bearer resource_metadata="...", error="insufficient_scope", scope="read write", error_description="..."'
+ * ```
+ */
+export declare function buildWwwAuthenticate(options?: WwwAuthenticateOptions): string;
+/**
+ * Build the Protected Resource Metadata URL for a given base URL and path
+ *
+ * @param baseUrl - The server base URL
+ * @param entryPath - The entry path prefix
+ * @param routeBase - The route base path
+ * @returns The full PRM URL
+ */
+export declare function buildPrmUrl(baseUrl: string, entryPath: string, routeBase: string): string;
+/**
+ * Build WWW-Authenticate header for unauthorized requests (no token)
+ */
+export declare function buildUnauthorizedHeader(prmUrl: string): string;
+/**
+ * Build WWW-Authenticate header for invalid token errors
+ */
+export declare function buildInvalidTokenHeader(prmUrl: string, description?: string): string;
+/**
+ * Build WWW-Authenticate header for insufficient scope errors
+ */
+export declare function buildInsufficientScopeHeader(prmUrl: string, requiredScopes: string[], description?: string): string;
+/**
+ * Build WWW-Authenticate header for invalid request errors
+ */
+export declare function buildInvalidRequestHeader(prmUrl: string, description?: string): string;
+/**
+ * Parse a WWW-Authenticate header value
+ *
+ * @param header - The WWW-Authenticate header value
+ * @returns Parsed header options
+ */
+export declare function parseWwwAuthenticate(header: string): WwwAuthenticateOptions;

package/src/auth/utils/www-authenticate.utils.js

@@ -0,0 +1,183 @@
+"use strict";
+// auth/utils/www-authenticate.utils.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildWwwAuthenticate = buildWwwAuthenticate;
+exports.buildPrmUrl = buildPrmUrl;
+exports.buildUnauthorizedHeader = buildUnauthorizedHeader;
+exports.buildInvalidTokenHeader = buildInvalidTokenHeader;
+exports.buildInsufficientScopeHeader = buildInsufficientScopeHeader;
+exports.buildInvalidRequestHeader = buildInvalidRequestHeader;
+exports.parseWwwAuthenticate = parseWwwAuthenticate;
+/**
+ * Build a WWW-Authenticate header for Bearer authentication
+ *
+ * @param options - Header options
+ * @returns The formatted WWW-Authenticate header value
+ *
+ * @example
+ * ```typescript
+ * // Basic protected resource metadata header
+ * buildWwwAuthenticate({
+ *   resourceMetadataUrl: 'https://api.example.com/.well-known/oauth-protected-resource',
+ * });
+ * // => 'Bearer resource_metadata="https://api.example.com/.well-known/oauth-protected-resource"'
+ *
+ * // With error information
+ * buildWwwAuthenticate({
+ *   resourceMetadataUrl: 'https://api.example.com/.well-known/oauth-protected-resource',
+ *   error: 'insufficient_scope',
+ *   scope: ['read', 'write'],
+ *   errorDescription: 'Additional permissions required',
+ * });
+ * // => 'Bearer resource_metadata="...", error="insufficient_scope", scope="read write", error_description="..."'
+ * ```
+ */
+function buildWwwAuthenticate(options = {}) {
+    const parts = ['Bearer'];
+    const params = [];
+    // Resource metadata URL (RFC 9728)
+    if (options.resourceMetadataUrl) {
+        params.push(`resource_metadata="${escapeQuotedString(options.resourceMetadataUrl)}"`);
+    }
+    // Realm (RFC 6750)
+    if (options.realm) {
+        params.push(`realm="${escapeQuotedString(options.realm)}"`);
+    }
+    // Error code (RFC 6750)
+    if (options.error) {
+        params.push(`error="${options.error}"`);
+    }
+    // Error description (RFC 6750)
+    if (options.errorDescription) {
+        params.push(`error_description="${escapeQuotedString(options.errorDescription)}"`);
+    }
+    // Error URI (RFC 6750)
+    if (options.errorUri) {
+        params.push(`error_uri="${escapeQuotedString(options.errorUri)}"`);
+    }
+    // Scope (RFC 6750) - space-delimited
+    if (options.scope) {
+        const scopeValue = Array.isArray(options.scope) ? options.scope.join(' ') : options.scope;
+        params.push(`scope="${escapeQuotedString(scopeValue)}"`);
+    }
+    if (params.length > 0) {
+        parts.push(params.join(', '));
+    }
+    return parts.join(' ');
+}
+/**
+ * Build the Protected Resource Metadata URL for a given base URL and path
+ *
+ * @param baseUrl - The server base URL
+ * @param entryPath - The entry path prefix
+ * @param routeBase - The route base path
+ * @returns The full PRM URL
+ */
+function buildPrmUrl(baseUrl, entryPath, routeBase) {
+    const normalizedEntry = normalizePathSegment(entryPath);
+    const normalizedRoute = normalizePathSegment(routeBase);
+    return `${baseUrl}/.well-known/oauth-protected-resource${normalizedEntry}${normalizedRoute}`;
+}
+/**
+ * Build WWW-Authenticate header for unauthorized requests (no token)
+ */
+function buildUnauthorizedHeader(prmUrl) {
+    return buildWwwAuthenticate({
+        resourceMetadataUrl: prmUrl,
+    });
+}
+/**
+ * Build WWW-Authenticate header for invalid token errors
+ */
+function buildInvalidTokenHeader(prmUrl, description) {
+    return buildWwwAuthenticate({
+        resourceMetadataUrl: prmUrl,
+        error: 'invalid_token',
+        errorDescription: description ?? 'The access token is invalid or expired',
+    });
+}
+/**
+ * Build WWW-Authenticate header for insufficient scope errors
+ */
+function buildInsufficientScopeHeader(prmUrl, requiredScopes, description) {
+    return buildWwwAuthenticate({
+        resourceMetadataUrl: prmUrl,
+        error: 'insufficient_scope',
+        scope: requiredScopes,
+        errorDescription: description ?? 'The request requires higher privileges',
+    });
+}
+/**
+ * Build WWW-Authenticate header for invalid request errors
+ */
+function buildInvalidRequestHeader(prmUrl, description) {
+    return buildWwwAuthenticate({
+        resourceMetadataUrl: prmUrl,
+        error: 'invalid_request',
+        errorDescription: description ?? 'The request is missing required parameters',
+    });
+}
+/**
+ * Parse a WWW-Authenticate header value
+ *
+ * @param header - The WWW-Authenticate header value
+ * @returns Parsed header options
+ */
+function parseWwwAuthenticate(header) {
+    const result = {};
+    // Check for Bearer scheme
+    if (!header.toLowerCase().startsWith('bearer')) {
+        return result;
+    }
+    // Extract parameters
+    const paramString = header.substring(6).trim();
+    const paramRegex = /(\w+)="([^"\\]*(?:\\.[^"\\]*)*)"/g;
+    let match;
+    while ((match = paramRegex.exec(paramString)) !== null) {
+        const [, key, value] = match;
+        const unescapedValue = unescapeQuotedString(value);
+        switch (key.toLowerCase()) {
+            case 'resource_metadata':
+                result.resourceMetadataUrl = unescapedValue;
+                break;
+            case 'realm':
+                result.realm = unescapedValue;
+                break;
+            case 'error':
+                result.error = unescapedValue;
+                break;
+            case 'error_description':
+                result.errorDescription = unescapedValue;
+                break;
+            case 'error_uri':
+                result.errorUri = unescapedValue;
+                break;
+            case 'scope':
+                result.scope = unescapedValue;
+                break;
+        }
+    }
+    return result;
+}
+/**
+ * Escape special characters for quoted-string per RFC 7230
+ */
+function escapeQuotedString(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+/**
+ * Unescape quoted-string per RFC 7230
+ */
+function unescapeQuotedString(value) {
+    return value.replace(/\\(.)/g, '$1');
+}
+/**
+ * Normalize a path segment (ensure leading slash, no trailing slash)
+ */
+function normalizePathSegment(path) {
+    if (!path || path === '/')
+        return '';
+    const normalized = path.startsWith('/') ? path : `/${path}`;
+    return normalized.replace(/\/+$/, '');
+}
+//# sourceMappingURL=www-authenticate.utils.js.map

package/src/auth/utils/www-authenticate.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"www-authenticate.utils.js","sourceRoot":"","sources":["../../../../src/auth/utils/www-authenticate.utils.ts"],"names":[],"mappings":"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","sourcesContent":["// auth/utils/www-authenticate.utils.ts\n\n/**\n * WWW-Authenticate Header Builder\n *\n * Implements RFC 9728 (OAuth 2.0 Protected Resource Metadata) and\n * RFC 6750 (Bearer Token Usage) compliant WWW-Authenticate headers.\n */\n\n/**\n * Error codes per RFC 6750 Section 3.1\n */\nexport type BearerErrorCode = 'invalid_request' | 'invalid_token' | 'insufficient_scope';\n\n/**\n * Options for building WWW-Authenticate header\n */\nexport interface WwwAuthenticateOptions {\n  /**\n   * The resource_metadata URL pointing to the PRM document\n   * Per RFC 9728, this is the primary mechanism for resource discovery\n   */\n  resourceMetadataUrl?: string;\n\n  /**\n   * OAuth 2.0 realm (optional per RFC 6750)\n   */\n  realm?: string;\n\n  /**\n   * Required scopes for the resource (space-delimited)\n   */\n  scope?: string | string[];\n\n  /**\n   * Error code when authentication fails\n   */\n  error?: BearerErrorCode;\n\n  /**\n   * Human-readable error description\n   */\n  errorDescription?: string;\n\n  /**\n   * Error URI pointing to additional information\n   */\n  errorUri?: string;\n}\n\n/**\n * Build a WWW-Authenticate header for Bearer authentication\n *\n * @param options - Header options\n * @returns The formatted WWW-Authenticate header value\n *\n * @example\n * ```typescript\n * // Basic protected resource metadata header\n * buildWwwAuthenticate({\n *   resourceMetadataUrl: 'https://api.example.com/.well-known/oauth-protected-resource',\n * });\n * // => 'Bearer resource_metadata=\"https://api.example.com/.well-known/oauth-protected-resource\"'\n *\n * // With error information\n * buildWwwAuthenticate({\n *   resourceMetadataUrl: 'https://api.example.com/.well-known/oauth-protected-resource',\n *   error: 'insufficient_scope',\n *   scope: ['read', 'write'],\n *   errorDescription: 'Additional permissions required',\n * });\n * // => 'Bearer resource_metadata=\"...\", error=\"insufficient_scope\", scope=\"read write\", error_description=\"...\"'\n * ```\n */\nexport function buildWwwAuthenticate(options: WwwAuthenticateOptions = {}): string {\n  const parts: string[] = ['Bearer'];\n  const params: string[] = [];\n\n  // Resource metadata URL (RFC 9728)\n  if (options.resourceMetadataUrl) {\n    params.push(`resource_metadata=\"${escapeQuotedString(options.resourceMetadataUrl)}\"`);\n  }\n\n  // Realm (RFC 6750)\n  if (options.realm) {\n    params.push(`realm=\"${escapeQuotedString(options.realm)}\"`);\n  }\n\n  // Error code (RFC 6750)\n  if (options.error) {\n    params.push(`error=\"${options.error}\"`);\n  }\n\n  // Error description (RFC 6750)\n  if (options.errorDescription) {\n    params.push(`error_description=\"${escapeQuotedString(options.errorDescription)}\"`);\n  }\n\n  // Error URI (RFC 6750)\n  if (options.errorUri) {\n    params.push(`error_uri=\"${escapeQuotedString(options.errorUri)}\"`);\n  }\n\n  // Scope (RFC 6750) - space-delimited\n  if (options.scope) {\n    const scopeValue = Array.isArray(options.scope) ? options.scope.join(' ') : options.scope;\n    params.push(`scope=\"${escapeQuotedString(scopeValue)}\"`);\n  }\n\n  if (params.length > 0) {\n    parts.push(params.join(', '));\n  }\n\n  return parts.join(' ');\n}\n\n/**\n * Build the Protected Resource Metadata URL for a given base URL and path\n *\n * @param baseUrl - The server base URL\n * @param entryPath - The entry path prefix\n * @param routeBase - The route base path\n * @returns The full PRM URL\n */\nexport function buildPrmUrl(baseUrl: string, entryPath: string, routeBase: string): string {\n  const normalizedEntry = normalizePathSegment(entryPath);\n  const normalizedRoute = normalizePathSegment(routeBase);\n  return `${baseUrl}/.well-known/oauth-protected-resource${normalizedEntry}${normalizedRoute}`;\n}\n\n/**\n * Build WWW-Authenticate header for unauthorized requests (no token)\n */\nexport function buildUnauthorizedHeader(prmUrl: string): string {\n  return buildWwwAuthenticate({\n    resourceMetadataUrl: prmUrl,\n  });\n}\n\n/**\n * Build WWW-Authenticate header for invalid token errors\n */\nexport function buildInvalidTokenHeader(prmUrl: string, description?: string): string {\n  return buildWwwAuthenticate({\n    resourceMetadataUrl: prmUrl,\n    error: 'invalid_token',\n    errorDescription: description ?? 'The access token is invalid or expired',\n  });\n}\n\n/**\n * Build WWW-Authenticate header for insufficient scope errors\n */\nexport function buildInsufficientScopeHeader(prmUrl: string, requiredScopes: string[], description?: string): string {\n  return buildWwwAuthenticate({\n    resourceMetadataUrl: prmUrl,\n    error: 'insufficient_scope',\n    scope: requiredScopes,\n    errorDescription: description ?? 'The request requires higher privileges',\n  });\n}\n\n/**\n * Build WWW-Authenticate header for invalid request errors\n */\nexport function buildInvalidRequestHeader(prmUrl: string, description?: string): string {\n  return buildWwwAuthenticate({\n    resourceMetadataUrl: prmUrl,\n    error: 'invalid_request',\n    errorDescription: description ?? 'The request is missing required parameters',\n  });\n}\n\n/**\n * Parse a WWW-Authenticate header value\n *\n * @param header - The WWW-Authenticate header value\n * @returns Parsed header options\n */\nexport function parseWwwAuthenticate(header: string): WwwAuthenticateOptions {\n  const result: WwwAuthenticateOptions = {};\n\n  // Check for Bearer scheme\n  if (!header.toLowerCase().startsWith('bearer')) {\n    return result;\n  }\n\n  // Extract parameters\n  const paramString = header.substring(6).trim();\n  const paramRegex = /(\\w+)=\"([^\"\\\\]*(?:\\\\.[^\"\\\\]*)*)\"/g;\n  let match: RegExpExecArray | null;\n\n  while ((match = paramRegex.exec(paramString)) !== null) {\n    const [, key, value] = match;\n    const unescapedValue = unescapeQuotedString(value);\n\n    switch (key.toLowerCase()) {\n      case 'resource_metadata':\n        result.resourceMetadataUrl = unescapedValue;\n        break;\n      case 'realm':\n        result.realm = unescapedValue;\n        break;\n      case 'error':\n        result.error = unescapedValue as BearerErrorCode;\n        break;\n      case 'error_description':\n        result.errorDescription = unescapedValue;\n        break;\n      case 'error_uri':\n        result.errorUri = unescapedValue;\n        break;\n      case 'scope':\n        result.scope = unescapedValue;\n        break;\n    }\n  }\n\n  return result;\n}\n\n/**\n * Escape special characters for quoted-string per RFC 7230\n */\nfunction escapeQuotedString(value: string): string {\n  return value.replace(/\\\\/g, '\\\\\\\\').replace(/\"/g, '\\\\\"');\n}\n\n/**\n * Unescape quoted-string per RFC 7230\n */\nfunction unescapeQuotedString(value: string): string {\n  return value.replace(/\\\\(.)/g, '$1');\n}\n\n/**\n * Normalize a path segment (ensure leading slash, no trailing slash)\n */\nfunction normalizePathSegment(path: string): string {\n  if (!path || path === '/') return '';\n  const normalized = path.startsWith('/') ? path : `/${path}`;\n  return normalized.replace(/\\/+$/, '');\n}\n"]}