@frontmcp/testing 0.5.0

package/src/auth/token-factory.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @file token-factory.ts
+ * @description JWT token factory for testing authentication
+ */
+import { type JWK } from 'jose';
+export interface CreateTokenOptions {
+    /** Subject (user ID) - required */
+    sub: string;
+    /** Issuer URL */
+    iss?: string;
+    /** Audience */
+    aud?: string | string[];
+    /** OAuth scopes */
+    scopes?: string[];
+    /** Expiration time in seconds from now (default: 3600) */
+    exp?: number;
+    /** Additional custom claims */
+    claims?: Record<string, unknown>;
+}
+export interface TokenFactoryOptions {
+    /** Default issuer URL */
+    issuer?: string;
+    /** Default audience */
+    audience?: string;
+}
+/**
+ * Factory for creating JWT tokens for testing
+ *
+ * @example
+ * ```typescript
+ * const factory = new TestTokenFactory();
+ *
+ * // Create a token with claims
+ * const token = await factory.createTestToken({
+ *   sub: 'user-123',
+ *   scopes: ['read', 'write'],
+ * });
+ *
+ * // Create convenience tokens
+ * const adminToken = await factory.createAdminToken();
+ * const userToken = await factory.createUserToken();
+ * ```
+ */
+export declare class TestTokenFactory {
+    private readonly issuer;
+    private readonly audience;
+    private privateKey;
+    private publicKey;
+    private jwk;
+    private keyId;
+    constructor(options?: TokenFactoryOptions);
+    /**
+     * Initialize the key pair (called automatically on first use)
+     */
+    private ensureKeys;
+    /**
+     * Create a JWT token with the specified claims
+     */
+    createTestToken(options: CreateTokenOptions): Promise<string>;
+    /**
+     * Create an admin token with full access
+     */
+    createAdminToken(sub?: string): Promise<string>;
+    /**
+     * Create a regular user token
+     */
+    createUserToken(sub?: string, scopes?: string[]): Promise<string>;
+    /**
+     * Create an anonymous user token
+     */
+    createAnonymousToken(): Promise<string>;
+    /**
+     * Create an expired token (for testing token expiration)
+     */
+    createExpiredToken(options: Pick<CreateTokenOptions, 'sub'>): Promise<string>;
+    /**
+     * Create a token with an invalid signature (for testing signature validation)
+     */
+    createTokenWithInvalidSignature(options: Pick<CreateTokenOptions, 'sub'>): string;
+    /**
+     * Get the public JWKS for verifying tokens
+     */
+    getPublicJwks(): Promise<{
+        keys: JWK[];
+    }>;
+    /**
+     * Get the issuer URL
+     */
+    getIssuer(): string;
+    /**
+     * Get the audience
+     */
+    getAudience(): string;
+}

package/src/auth/token-factory.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * @file token-factory.ts
+ * @description JWT token factory for testing authentication
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestTokenFactory = void 0;
+const jose_1 = require("jose");
+// ═══════════════════════════════════════════════════════════════════
+// TOKEN FACTORY CLASS
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Factory for creating JWT tokens for testing
+ *
+ * @example
+ * ```typescript
+ * const factory = new TestTokenFactory();
+ *
+ * // Create a token with claims
+ * const token = await factory.createTestToken({
+ *   sub: 'user-123',
+ *   scopes: ['read', 'write'],
+ * });
+ *
+ * // Create convenience tokens
+ * const adminToken = await factory.createAdminToken();
+ * const userToken = await factory.createUserToken();
+ * ```
+ */
+class TestTokenFactory {
+    issuer;
+    audience;
+    privateKey = null;
+    publicKey = null;
+    jwk = null;
+    keyId;
+    constructor(options = {}) {
+        this.issuer = options.issuer ?? 'https://test.frontmcp.local';
+        this.audience = options.audience ?? 'frontmcp-test';
+        this.keyId = `test-key-${Date.now()}`;
+    }
+    /**
+     * Initialize the key pair (called automatically on first use)
+     */
+    async ensureKeys() {
+        if (this.privateKey && this.publicKey)
+            return;
+        // Generate RSA key pair
+        const { publicKey, privateKey } = await (0, jose_1.generateKeyPair)('RS256', {
+            extractable: true,
+        });
+        this.privateKey = privateKey;
+        this.publicKey = publicKey;
+        // Export public key as JWK
+        this.jwk = await (0, jose_1.exportJWK)(publicKey);
+        this.jwk.kid = this.keyId;
+        this.jwk.use = 'sig';
+        this.jwk.alg = 'RS256';
+    }
+    /**
+     * Create a JWT token with the specified claims
+     */
+    async createTestToken(options) {
+        await this.ensureKeys();
+        const now = Math.floor(Date.now() / 1000);
+        const exp = options.exp ?? 3600;
+        const payload = {
+            iss: options.iss ?? this.issuer,
+            sub: options.sub,
+            aud: options.aud ?? this.audience,
+            iat: now,
+            exp: now + exp,
+            scope: options.scopes?.join(' '),
+            ...options.claims,
+        };
+        const token = await new jose_1.SignJWT(payload)
+            .setProtectedHeader({ alg: 'RS256', kid: this.keyId })
+            .sign(this.privateKey);
+        return token;
+    }
+    /**
+     * Create an admin token with full access
+     */
+    async createAdminToken(sub = 'admin-001') {
+        return this.createTestToken({
+            sub,
+            scopes: ['admin:*', 'read', 'write', 'delete'],
+            claims: {
+                email: 'admin@test.local',
+                name: 'Test Admin',
+                role: 'admin',
+            },
+        });
+    }
+    /**
+     * Create a regular user token
+     */
+    async createUserToken(sub = 'user-001', scopes = ['read', 'write']) {
+        return this.createTestToken({
+            sub,
+            scopes,
+            claims: {
+                email: 'user@test.local',
+                name: 'Test User',
+                role: 'user',
+            },
+        });
+    }
+    /**
+     * Create an anonymous user token
+     */
+    async createAnonymousToken() {
+        return this.createTestToken({
+            sub: `anon:${Date.now()}`,
+            scopes: ['anonymous'],
+            claims: {
+                name: 'Anonymous',
+                role: 'anonymous',
+            },
+        });
+    }
+    /**
+     * Create an expired token (for testing token expiration)
+     */
+    async createExpiredToken(options) {
+        await this.ensureKeys();
+        const now = Math.floor(Date.now() / 1000);
+        const payload = {
+            iss: this.issuer,
+            sub: options.sub,
+            aud: this.audience,
+            iat: now - 7200, // 2 hours ago
+            exp: now - 3600, // Expired 1 hour ago
+        };
+        const token = await new jose_1.SignJWT(payload)
+            .setProtectedHeader({ alg: 'RS256', kid: this.keyId })
+            .sign(this.privateKey);
+        return token;
+    }
+    /**
+     * Create a token with an invalid signature (for testing signature validation)
+     */
+    createTokenWithInvalidSignature(options) {
+        const now = Math.floor(Date.now() / 1000);
+        // Create a fake JWT with an invalid signature
+        const header = Buffer.from(JSON.stringify({ alg: 'RS256', kid: this.keyId })).toString('base64url');
+        const payload = Buffer.from(JSON.stringify({
+            iss: this.issuer,
+            sub: options.sub,
+            aud: this.audience,
+            iat: now,
+            exp: now + 3600,
+        })).toString('base64url');
+        // Invalid signature (just random bytes)
+        const signature = Buffer.from('invalid-signature-' + Date.now()).toString('base64url');
+        return `${header}.${payload}.${signature}`;
+    }
+    /**
+     * Get the public JWKS for verifying tokens
+     */
+    async getPublicJwks() {
+        await this.ensureKeys();
+        return {
+            keys: [this.jwk],
+        };
+    }
+    /**
+     * Get the issuer URL
+     */
+    getIssuer() {
+        return this.issuer;
+    }
+    /**
+     * Get the audience
+     */
+    getAudience() {
+        return this.audience;
+    }
+}
+exports.TestTokenFactory = TestTokenFactory;
+//# sourceMappingURL=token-factory.js.map

package/src/auth/token-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-factory.js","sourceRoot":"","sources":["../../../src/auth/token-factory.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,+BAAsF;AA+BtF,sEAAsE;AACtE,sBAAsB;AACtB,sEAAsE;AAEtE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAa,gBAAgB;IACV,MAAM,CAAS;IACf,QAAQ,CAAS;IAC1B,UAAU,GAAyB,IAAI,CAAC;IACxC,SAAS,GAAyB,IAAI,CAAC;IACvC,GAAG,GAAe,IAAI,CAAC;IACvB,KAAK,CAAS;IAEtB,YAAY,UAA+B,EAAE;QAC3C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,6BAA6B,CAAC;QAC9D,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,eAAe,CAAC;QACpD,IAAI,CAAC,KAAK,GAAG,YAAY,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;IACxC,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,UAAU;QACtB,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO;QAE9C,wBAAwB;QACxB,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,MAAM,IAAA,sBAAe,EAAC,OAAO,EAAE;YAC/D,WAAW,EAAE,IAAI;SAClB,CAAC,CAAC;QAEH,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAE3B,2BAA2B;QAC3B,IAAI,CAAC,GAAG,GAAG,MAAM,IAAA,gBAAS,EAAC,SAAS,CAAC,CAAC;QACtC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC;QAC1B,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,KAAK,CAAC;QACrB,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,OAAO,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,eAAe,CAAC,OAA2B;QAC/C,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QAExB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAC1C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC;QAEhC,MAAM,OAAO,GAAe;YAC1B,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,MAAM;YAC/B,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,QAAQ;YACjC,GAAG,EAAE,GAAG;YACR,GAAG,EAAE,GAAG,GAAG,GAAG;YACd,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC;YAChC,GAAG,OAAO,CAAC,MAAM;SAClB,CAAC;QAEF,MAAM,KAAK,GAAG,MAAM,IAAI,cAAO,CAAC,OAAO,CAAC;aACrC,kBAAkB,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;aACrD,IAAI,CAAC,IAAI,CAAC,UAAW,CAAC,CAAC;QAE1B,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,gBAAgB,CAAC,GAAG,GAAG,WAAW;QACtC,OAAO,IAAI,CAAC,eAAe,CAAC;YAC1B,GAAG;YACH,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC;YAC9C,MAAM,EAAE;gBACN,KAAK,EAAE,kBAAkB;gBACzB,IAAI,EAAE,YAAY;gBAClB,IAAI,EAAE,OAAO;aACd;SACF,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,eAAe,CAAC,GAAG,GAAG,UAAU,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;QAChE,OAAO,IAAI,CAAC,eAAe,CAAC;YAC1B,GAAG;YACH,MAAM;YACN,MAAM,EAAE;gBACN,KAAK,EAAE,iBAAiB;gBACxB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,MAAM;aACb;SACF,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,oBAAoB;QACxB,OAAO,IAAI,CAAC,eAAe,CAAC;YAC1B,GAAG,EAAE,QAAQ,IAAI,CAAC,GAAG,EAAE,EAAE;YACzB,MAAM,EAAE,CAAC,WAAW,CAAC;YACrB,MAAM,EAAE;gBACN,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,WAAW;aAClB;SACF,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,kBAAkB,CAAC,OAAwC;QAC/D,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QAExB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAE1C,MAAM,OAAO,GAAe;YAC1B,GAAG,EAAE,IAAI,CAAC,MAAM;YAChB,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,GAAG,EAAE,IAAI,CAAC,QAAQ;YAClB,GAAG,EAAE,GAAG,GAAG,IAAI,EAAE,cAAc;YAC/B,GAAG,EAAE,GAAG,GAAG,IAAI,EAAE,qBAAqB;SACvC,CAAC;QAEF,MAAM,KAAK,GAAG,MAAM,IAAI,cAAO,CAAC,OAAO,CAAC;aACrC,kBAAkB,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;aACrD,IAAI,CAAC,IAAI,CAAC,UAAW,CAAC,CAAC;QAE1B,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,+BAA+B,CAAC,OAAwC;QACtE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAE1C,8CAA8C;QAC9C,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;QACpG,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CACzB,IAAI,CAAC,SAAS,CAAC;YACb,GAAG,EAAE,IAAI,CAAC,MAAM;YAChB,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,GAAG,EAAE,IAAI,CAAC,QAAQ;YAClB,GAAG,EAAE,GAAG;YACR,GAAG,EAAE,GAAG,GAAG,IAAI;SAChB,CAAC,CACH,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;QAExB,wCAAwC;QACxC,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,oBAAoB,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;QAEvF,OAAO,GAAG,MAAM,IAAI,OAAO,IAAI,SAAS,EAAE,CAAC;IAC7C,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,aAAa;QACjB,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QACxB,OAAO;YACL,IAAI,EAAE,CAAC,IAAI,CAAC,GAAI,CAAC;SAClB,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;CACF;AA/KD,4CA+KC","sourcesContent":["/**\n * @file token-factory.ts\n * @description JWT token factory for testing authentication\n */\n\nimport { SignJWT, generateKeyPair, exportJWK, type JWTPayload, type JWK } from 'jose';\n\n// ═══════════════════════════════════════════════════════════════════\n// TYPES\n// ═══════════════════════════════════════════════════════════════════\n\nexport interface CreateTokenOptions {\n  /** Subject (user ID) - required */\n  sub: string;\n  /** Issuer URL */\n  iss?: string;\n  /** Audience */\n  aud?: string | string[];\n  /** OAuth scopes */\n  scopes?: string[];\n  /** Expiration time in seconds from now (default: 3600) */\n  exp?: number;\n  /** Additional custom claims */\n  claims?: Record<string, unknown>;\n}\n\nexport interface TokenFactoryOptions {\n  /** Default issuer URL */\n  issuer?: string;\n  /** Default audience */\n  audience?: string;\n}\n\n// Type for crypto key\ntype CryptoKeyLike = CryptoKey | Uint8Array;\n\n// ═══════════════════════════════════════════════════════════════════\n// TOKEN FACTORY CLASS\n// ═══════════════════════════════════════════════════════════════════\n\n/**\n * Factory for creating JWT tokens for testing\n *\n * @example\n * ```typescript\n * const factory = new TestTokenFactory();\n *\n * // Create a token with claims\n * const token = await factory.createTestToken({\n *   sub: 'user-123',\n *   scopes: ['read', 'write'],\n * });\n *\n * // Create convenience tokens\n * const adminToken = await factory.createAdminToken();\n * const userToken = await factory.createUserToken();\n * ```\n */\nexport class TestTokenFactory {\n  private readonly issuer: string;\n  private readonly audience: string;\n  private privateKey: CryptoKeyLike | null = null;\n  private publicKey: CryptoKeyLike | null = null;\n  private jwk: JWK | null = null;\n  private keyId: string;\n\n  constructor(options: TokenFactoryOptions = {}) {\n    this.issuer = options.issuer ?? 'https://test.frontmcp.local';\n    this.audience = options.audience ?? 'frontmcp-test';\n    this.keyId = `test-key-${Date.now()}`;\n  }\n\n  /**\n   * Initialize the key pair (called automatically on first use)\n   */\n  private async ensureKeys(): Promise<void> {\n    if (this.privateKey && this.publicKey) return;\n\n    // Generate RSA key pair\n    const { publicKey, privateKey } = await generateKeyPair('RS256', {\n      extractable: true,\n    });\n\n    this.privateKey = privateKey;\n    this.publicKey = publicKey;\n\n    // Export public key as JWK\n    this.jwk = await exportJWK(publicKey);\n    this.jwk.kid = this.keyId;\n    this.jwk.use = 'sig';\n    this.jwk.alg = 'RS256';\n  }\n\n  /**\n   * Create a JWT token with the specified claims\n   */\n  async createTestToken(options: CreateTokenOptions): Promise<string> {\n    await this.ensureKeys();\n\n    const now = Math.floor(Date.now() / 1000);\n    const exp = options.exp ?? 3600;\n\n    const payload: JWTPayload = {\n      iss: options.iss ?? this.issuer,\n      sub: options.sub,\n      aud: options.aud ?? this.audience,\n      iat: now,\n      exp: now + exp,\n      scope: options.scopes?.join(' '),\n      ...options.claims,\n    };\n\n    const token = await new SignJWT(payload)\n      .setProtectedHeader({ alg: 'RS256', kid: this.keyId })\n      .sign(this.privateKey!);\n\n    return token;\n  }\n\n  /**\n   * Create an admin token with full access\n   */\n  async createAdminToken(sub = 'admin-001'): Promise<string> {\n    return this.createTestToken({\n      sub,\n      scopes: ['admin:*', 'read', 'write', 'delete'],\n      claims: {\n        email: 'admin@test.local',\n        name: 'Test Admin',\n        role: 'admin',\n      },\n    });\n  }\n\n  /**\n   * Create a regular user token\n   */\n  async createUserToken(sub = 'user-001', scopes = ['read', 'write']): Promise<string> {\n    return this.createTestToken({\n      sub,\n      scopes,\n      claims: {\n        email: 'user@test.local',\n        name: 'Test User',\n        role: 'user',\n      },\n    });\n  }\n\n  /**\n   * Create an anonymous user token\n   */\n  async createAnonymousToken(): Promise<string> {\n    return this.createTestToken({\n      sub: `anon:${Date.now()}`,\n      scopes: ['anonymous'],\n      claims: {\n        name: 'Anonymous',\n        role: 'anonymous',\n      },\n    });\n  }\n\n  /**\n   * Create an expired token (for testing token expiration)\n   */\n  async createExpiredToken(options: Pick<CreateTokenOptions, 'sub'>): Promise<string> {\n    await this.ensureKeys();\n\n    const now = Math.floor(Date.now() / 1000);\n\n    const payload: JWTPayload = {\n      iss: this.issuer,\n      sub: options.sub,\n      aud: this.audience,\n      iat: now - 7200, // 2 hours ago\n      exp: now - 3600, // Expired 1 hour ago\n    };\n\n    const token = await new SignJWT(payload)\n      .setProtectedHeader({ alg: 'RS256', kid: this.keyId })\n      .sign(this.privateKey!);\n\n    return token;\n  }\n\n  /**\n   * Create a token with an invalid signature (for testing signature validation)\n   */\n  createTokenWithInvalidSignature(options: Pick<CreateTokenOptions, 'sub'>): string {\n    const now = Math.floor(Date.now() / 1000);\n\n    // Create a fake JWT with an invalid signature\n    const header = Buffer.from(JSON.stringify({ alg: 'RS256', kid: this.keyId })).toString('base64url');\n    const payload = Buffer.from(\n      JSON.stringify({\n        iss: this.issuer,\n        sub: options.sub,\n        aud: this.audience,\n        iat: now,\n        exp: now + 3600,\n      }),\n    ).toString('base64url');\n\n    // Invalid signature (just random bytes)\n    const signature = Buffer.from('invalid-signature-' + Date.now()).toString('base64url');\n\n    return `${header}.${payload}.${signature}`;\n  }\n\n  /**\n   * Get the public JWKS for verifying tokens\n   */\n  async getPublicJwks(): Promise<{ keys: JWK[] }> {\n    await this.ensureKeys();\n    return {\n      keys: [this.jwk!],\n    };\n  }\n\n  /**\n   * Get the issuer URL\n   */\n  getIssuer(): string {\n    return this.issuer;\n  }\n\n  /**\n   * Get the audience\n   */\n  getAudience(): string {\n    return this.audience;\n  }\n}\n"]}

package/src/auth/user-fixtures.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @file user-fixtures.ts
+ * @description Pre-defined test user fixtures
+ */
+export interface TestUserFixture {
+    /** User subject ID */
+    sub: string;
+    /** User email */
+    email?: string;
+    /** User display name */
+    name?: string;
+    /** OAuth scopes */
+    scopes: string[];
+    /** User role */
+    role?: string;
+}
+/**
+ * Pre-defined test users for common testing scenarios
+ */
+export declare const TestUsers: Record<string, TestUserFixture>;
+/**
+ * Create a custom test user
+ */
+export declare function createTestUser(overrides: Partial<TestUserFixture> & {
+    sub: string;
+}): TestUserFixture;

package/src/auth/user-fixtures.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * @file user-fixtures.ts
+ * @description Pre-defined test user fixtures
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestUsers = void 0;
+exports.createTestUser = createTestUser;
+/**
+ * Pre-defined test users for common testing scenarios
+ */
+exports.TestUsers = {
+    /**
+     * Admin user with full access
+     */
+    admin: {
+        sub: 'admin-001',
+        email: 'admin@test.local',
+        name: 'Test Admin',
+        scopes: ['admin:*', 'read', 'write', 'delete'],
+        role: 'admin',
+    },
+    /**
+     * Regular user with read/write access
+     */
+    user: {
+        sub: 'user-001',
+        email: 'user@test.local',
+        name: 'Test User',
+        scopes: ['read', 'write'],
+        role: 'user',
+    },
+    /**
+     * Read-only user
+     */
+    readOnly: {
+        sub: 'readonly-001',
+        email: 'readonly@test.local',
+        name: 'Read Only User',
+        scopes: ['read'],
+        role: 'readonly',
+    },
+    /**
+     * Anonymous user
+     */
+    anonymous: {
+        sub: 'anon:001',
+        name: 'Anonymous',
+        scopes: ['anonymous'],
+        role: 'anonymous',
+    },
+    /**
+     * User with no scopes (for testing access denied)
+     */
+    noScopes: {
+        sub: 'noscopes-001',
+        email: 'noscopes@test.local',
+        name: 'No Scopes User',
+        scopes: [],
+        role: 'user',
+    },
+    /**
+     * User with only tool execution scope
+     */
+    toolsOnly: {
+        sub: 'toolsonly-001',
+        email: 'toolsonly@test.local',
+        name: 'Tools Only User',
+        scopes: ['tools:execute'],
+        role: 'user',
+    },
+    /**
+     * User with only resource read scope
+     */
+    resourcesOnly: {
+        sub: 'resourcesonly-001',
+        email: 'resourcesonly@test.local',
+        name: 'Resources Only User',
+        scopes: ['resources:read'],
+        role: 'user',
+    },
+};
+/**
+ * Create a custom test user
+ */
+function createTestUser(overrides) {
+    return {
+        scopes: [],
+        ...overrides,
+    };
+}
+//# sourceMappingURL=user-fixtures.js.map

package/src/auth/user-fixtures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-fixtures.js","sourceRoot":"","sources":["../../../src/auth/user-fixtures.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAmGH,wCAKC;AAzFD;;GAEG;AACU,QAAA,SAAS,GAAoC;IACxD;;OAEG;IACH,KAAK,EAAE;QACL,GAAG,EAAE,WAAW;QAChB,KAAK,EAAE,kBAAkB;QACzB,IAAI,EAAE,YAAY;QAClB,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC;QAC9C,IAAI,EAAE,OAAO;KACd;IAED;;OAEG;IACH,IAAI,EAAE;QACJ,GAAG,EAAE,UAAU;QACf,KAAK,EAAE,iBAAiB;QACxB,IAAI,EAAE,WAAW;QACjB,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;QACzB,IAAI,EAAE,MAAM;KACb;IAED;;OAEG;IACH,QAAQ,EAAE;QACR,GAAG,EAAE,cAAc;QACnB,KAAK,EAAE,qBAAqB;QAC5B,IAAI,EAAE,gBAAgB;QACtB,MAAM,EAAE,CAAC,MAAM,CAAC;QAChB,IAAI,EAAE,UAAU;KACjB;IAED;;OAEG;IACH,SAAS,EAAE;QACT,GAAG,EAAE,UAAU;QACf,IAAI,EAAE,WAAW;QACjB,MAAM,EAAE,CAAC,WAAW,CAAC;QACrB,IAAI,EAAE,WAAW;KAClB;IAED;;OAEG;IACH,QAAQ,EAAE;QACR,GAAG,EAAE,cAAc;QACnB,KAAK,EAAE,qBAAqB;QAC5B,IAAI,EAAE,gBAAgB;QACtB,MAAM,EAAE,EAAE;QACV,IAAI,EAAE,MAAM;KACb;IAED;;OAEG;IACH,SAAS,EAAE;QACT,GAAG,EAAE,eAAe;QACpB,KAAK,EAAE,sBAAsB;QAC7B,IAAI,EAAE,iBAAiB;QACvB,MAAM,EAAE,CAAC,eAAe,CAAC;QACzB,IAAI,EAAE,MAAM;KACb;IAED;;OAEG;IACH,aAAa,EAAE;QACb,GAAG,EAAE,mBAAmB;QACxB,KAAK,EAAE,0BAA0B;QACjC,IAAI,EAAE,qBAAqB;QAC3B,MAAM,EAAE,CAAC,gBAAgB,CAAC;QAC1B,IAAI,EAAE,MAAM;KACb;CACF,CAAC;AAEF;;GAEG;AACH,SAAgB,cAAc,CAAC,SAAqD;IAClF,OAAO;QACL,MAAM,EAAE,EAAE;QACV,GAAG,SAAS;KACb,CAAC;AACJ,CAAC","sourcesContent":["/**\n * @file user-fixtures.ts\n * @description Pre-defined test user fixtures\n */\n\nexport interface TestUserFixture {\n  /** User subject ID */\n  sub: string;\n  /** User email */\n  email?: string;\n  /** User display name */\n  name?: string;\n  /** OAuth scopes */\n  scopes: string[];\n  /** User role */\n  role?: string;\n}\n\n/**\n * Pre-defined test users for common testing scenarios\n */\nexport const TestUsers: Record<string, TestUserFixture> = {\n  /**\n   * Admin user with full access\n   */\n  admin: {\n    sub: 'admin-001',\n    email: 'admin@test.local',\n    name: 'Test Admin',\n    scopes: ['admin:*', 'read', 'write', 'delete'],\n    role: 'admin',\n  },\n\n  /**\n   * Regular user with read/write access\n   */\n  user: {\n    sub: 'user-001',\n    email: 'user@test.local',\n    name: 'Test User',\n    scopes: ['read', 'write'],\n    role: 'user',\n  },\n\n  /**\n   * Read-only user\n   */\n  readOnly: {\n    sub: 'readonly-001',\n    email: 'readonly@test.local',\n    name: 'Read Only User',\n    scopes: ['read'],\n    role: 'readonly',\n  },\n\n  /**\n   * Anonymous user\n   */\n  anonymous: {\n    sub: 'anon:001',\n    name: 'Anonymous',\n    scopes: ['anonymous'],\n    role: 'anonymous',\n  },\n\n  /**\n   * User with no scopes (for testing access denied)\n   */\n  noScopes: {\n    sub: 'noscopes-001',\n    email: 'noscopes@test.local',\n    name: 'No Scopes User',\n    scopes: [],\n    role: 'user',\n  },\n\n  /**\n   * User with only tool execution scope\n   */\n  toolsOnly: {\n    sub: 'toolsonly-001',\n    email: 'toolsonly@test.local',\n    name: 'Tools Only User',\n    scopes: ['tools:execute'],\n    role: 'user',\n  },\n\n  /**\n   * User with only resource read scope\n   */\n  resourcesOnly: {\n    sub: 'resourcesonly-001',\n    email: 'resourcesonly@test.local',\n    name: 'Resources Only User',\n    scopes: ['resources:read'],\n    role: 'user',\n  },\n};\n\n/**\n * Create a custom test user\n */\nexport function createTestUser(overrides: Partial<TestUserFixture> & { sub: string }): TestUserFixture {\n  return {\n    scopes: [],\n    ...overrides,\n  };\n}\n"]}

package/src/client/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @file client/index.ts
+ * @description MCP Test Client exports
+ */
+export { McpTestClient } from './mcp-test-client';
+export { McpTestClientBuilder } from './mcp-test-client.builder';
+export type { McpTestClientConfig, McpResponse, McpErrorInfo, TestTransportType, TestAuthConfig, ToolResultWrapper, ResourceContentWrapper, PromptResultWrapper, LogEntry, LogLevel, RequestTrace, NotificationEntry, ProgressUpdate, SessionInfo, AuthState, TransportState, JSONRPCRequest, JSONRPCResponse, InitializeResult, ListToolsResult, CallToolResult, ListResourcesResult, ReadResourceResult, ListResourceTemplatesResult, ListPromptsResult, GetPromptResult, Tool, Resource, ResourceTemplate, Prompt, } from './mcp-test-client.types';

package/src/client/index.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * @file client/index.ts
+ * @description MCP Test Client exports
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpTestClientBuilder = exports.McpTestClient = void 0;
+var mcp_test_client_1 = require("./mcp-test-client");
+Object.defineProperty(exports, "McpTestClient", { enumerable: true, get: function () { return mcp_test_client_1.McpTestClient; } });
+var mcp_test_client_builder_1 = require("./mcp-test-client.builder");
+Object.defineProperty(exports, "McpTestClientBuilder", { enumerable: true, get: function () { return mcp_test_client_builder_1.McpTestClientBuilder; } });
+//# sourceMappingURL=index.js.map

package/src/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,qDAAkD;AAAzC,gHAAA,aAAa,OAAA;AACtB,qEAAiE;AAAxD,+HAAA,oBAAoB,OAAA","sourcesContent":["/**\n * @file client/index.ts\n * @description MCP Test Client exports\n */\n\nexport { McpTestClient } from './mcp-test-client';\nexport { McpTestClientBuilder } from './mcp-test-client.builder';\nexport type {\n  McpTestClientConfig,\n  McpResponse,\n  McpErrorInfo,\n  TestTransportType,\n  TestAuthConfig,\n  ToolResultWrapper,\n  ResourceContentWrapper,\n  PromptResultWrapper,\n  LogEntry,\n  LogLevel,\n  RequestTrace,\n  NotificationEntry,\n  ProgressUpdate,\n  SessionInfo,\n  AuthState,\n  TransportState,\n  // JSON-RPC types\n  JSONRPCRequest,\n  JSONRPCResponse,\n  // Re-exports from MCP SDK\n  InitializeResult,\n  ListToolsResult,\n  CallToolResult,\n  ListResourcesResult,\n  ReadResourceResult,\n  ListResourceTemplatesResult,\n  ListPromptsResult,\n  GetPromptResult,\n  Tool,\n  Resource,\n  ResourceTemplate,\n  Prompt,\n} from './mcp-test-client.types';\n"]}

package/src/client/mcp-test-client.builder.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @file mcp-test-client.builder.ts
+ * @description Builder pattern for creating McpTestClient instances
+ */
+import type { McpTestClientConfig, TestTransportType, TestAuthConfig } from './mcp-test-client.types';
+import { McpTestClient } from './mcp-test-client';
+/**
+ * Builder for creating McpTestClient instances with fluent API
+ *
+ * @example
+ * ```typescript
+ * const client = await McpTestClient.create({ baseUrl: 'http://localhost:3003' })
+ *   .withTransport('streamable-http')
+ *   .withToken('my-jwt-token')
+ *   .withTimeout(5000)
+ *   .withDebug()
+ *   .buildAndConnect();
+ * ```
+ */
+export declare class McpTestClientBuilder {
+    private config;
+    constructor(config: McpTestClientConfig);
+    /**
+     * Set the authentication configuration
+     */
+    withAuth(auth: TestAuthConfig): this;
+    /**
+     * Set the bearer token for authentication
+     */
+    withToken(token: string): this;
+    /**
+     * Add custom headers to all requests
+     */
+    withHeaders(headers: Record<string, string>): this;
+    /**
+     * Set the transport type
+     */
+    withTransport(transport: TestTransportType): this;
+    /**
+     * Set the request timeout in milliseconds
+     */
+    withTimeout(timeoutMs: number): this;
+    /**
+     * Enable debug logging
+     */
+    withDebug(enabled?: boolean): this;
+    /**
+     * Enable public mode - skip authentication entirely.
+     * When true, no Authorization header is sent and anonymous token is not requested.
+     * Use this for testing public/unauthenticated endpoints in CI/CD pipelines.
+     */
+    withPublicMode(enabled?: boolean): this;
+    /**
+     * Set the MCP protocol version to request
+     */
+    withProtocolVersion(version: string): this;
+    /**
+     * Set the client info sent during initialization
+     */
+    withClientInfo(info: {
+        name: string;
+        version: string;
+    }): this;
+    /**
+     * Build the McpTestClient instance (does not connect)
+     */
+    build(): McpTestClient;
+    /**
+     * Build the McpTestClient and connect to the server
+     */
+    buildAndConnect(): Promise<McpTestClient>;
+}

package/src/client/mcp-test-client.builder.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * @file mcp-test-client.builder.ts
+ * @description Builder pattern for creating McpTestClient instances
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpTestClientBuilder = void 0;
+const mcp_test_client_1 = require("./mcp-test-client");
+/**
+ * Builder for creating McpTestClient instances with fluent API
+ *
+ * @example
+ * ```typescript
+ * const client = await McpTestClient.create({ baseUrl: 'http://localhost:3003' })
+ *   .withTransport('streamable-http')
+ *   .withToken('my-jwt-token')
+ *   .withTimeout(5000)
+ *   .withDebug()
+ *   .buildAndConnect();
+ * ```
+ */
+class McpTestClientBuilder {
+    config;
+    constructor(config) {
+        this.config = { ...config };
+    }
+    /**
+     * Set the authentication configuration
+     */
+    withAuth(auth) {
+        this.config.auth = { ...this.config.auth, ...auth };
+        return this;
+    }
+    /**
+     * Set the bearer token for authentication
+     */
+    withToken(token) {
+        this.config.auth = { ...this.config.auth, token };
+        return this;
+    }
+    /**
+     * Add custom headers to all requests
+     */
+    withHeaders(headers) {
+        this.config.auth = {
+            ...this.config.auth,
+            headers: { ...this.config.auth?.headers, ...headers },
+        };
+        return this;
+    }
+    /**
+     * Set the transport type
+     */
+    withTransport(transport) {
+        this.config.transport = transport;
+        return this;
+    }
+    /**
+     * Set the request timeout in milliseconds
+     */
+    withTimeout(timeoutMs) {
+        this.config.timeout = timeoutMs;
+        return this;
+    }
+    /**
+     * Enable debug logging
+     */
+    withDebug(enabled = true) {
+        this.config.debug = enabled;
+        return this;
+    }
+    /**
+     * Enable public mode - skip authentication entirely.
+     * When true, no Authorization header is sent and anonymous token is not requested.
+     * Use this for testing public/unauthenticated endpoints in CI/CD pipelines.
+     */
+    withPublicMode(enabled = true) {
+        this.config.publicMode = enabled;
+        return this;
+    }
+    /**
+     * Set the MCP protocol version to request
+     */
+    withProtocolVersion(version) {
+        this.config.protocolVersion = version;
+        return this;
+    }
+    /**
+     * Set the client info sent during initialization
+     */
+    withClientInfo(info) {
+        this.config.clientInfo = info;
+        return this;
+    }
+    /**
+     * Build the McpTestClient instance (does not connect)
+     */
+    build() {
+        return new mcp_test_client_1.McpTestClient(this.config);
+    }
+    /**
+     * Build the McpTestClient and connect to the server
+     */
+    async buildAndConnect() {
+        const client = this.build();
+        await client.connect();
+        return client;
+    }
+}
+exports.McpTestClientBuilder = McpTestClientBuilder;
+//# sourceMappingURL=mcp-test-client.builder.js.map

package/src/client/mcp-test-client.builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-test-client.builder.js","sourceRoot":"","sources":["../../../src/client/mcp-test-client.builder.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAGH,uDAAkD;AAElD;;;;;;;;;;;;GAYG;AACH,MAAa,oBAAoB;IACvB,MAAM,CAAsB;IAEpC,YAAY,MAA2B;QACrC,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,IAAoB;QAC3B,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC;QACpD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,KAAa;QACrB,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;QAClD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,OAA+B;QACzC,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG;YACjB,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI;YACnB,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE;SACtD,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,SAA4B;QACxC,IAAI,CAAC,MAAM,CAAC,SAAS,GAAG,SAAS,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,SAAiB;QAC3B,IAAI,CAAC,MAAM,CAAC,OAAO,GAAG,SAAS,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,OAAO,GAAG,IAAI;QACtB,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,OAAO,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,cAAc,CAAC,OAAO,GAAG,IAAI;QAC3B,IAAI,CAAC,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,mBAAmB,CAAC,OAAe;QACjC,IAAI,CAAC,MAAM,CAAC,eAAe,GAAG,OAAO,CAAC;QACtC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,cAAc,CAAC,IAAuC;QACpD,IAAI,CAAC,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,KAAK;QACH,OAAO,IAAI,+BAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACxC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,eAAe;QACnB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC5B,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AAnGD,oDAmGC","sourcesContent":["/**\n * @file mcp-test-client.builder.ts\n * @description Builder pattern for creating McpTestClient instances\n */\n\nimport type { McpTestClientConfig, TestTransportType, TestAuthConfig } from './mcp-test-client.types';\nimport { McpTestClient } from './mcp-test-client';\n\n/**\n * Builder for creating McpTestClient instances with fluent API\n *\n * @example\n * ```typescript\n * const client = await McpTestClient.create({ baseUrl: 'http://localhost:3003' })\n *   .withTransport('streamable-http')\n *   .withToken('my-jwt-token')\n *   .withTimeout(5000)\n *   .withDebug()\n *   .buildAndConnect();\n * ```\n */\nexport class McpTestClientBuilder {\n  private config: McpTestClientConfig;\n\n  constructor(config: McpTestClientConfig) {\n    this.config = { ...config };\n  }\n\n  /**\n   * Set the authentication configuration\n   */\n  withAuth(auth: TestAuthConfig): this {\n    this.config.auth = { ...this.config.auth, ...auth };\n    return this;\n  }\n\n  /**\n   * Set the bearer token for authentication\n   */\n  withToken(token: string): this {\n    this.config.auth = { ...this.config.auth, token };\n    return this;\n  }\n\n  /**\n   * Add custom headers to all requests\n   */\n  withHeaders(headers: Record<string, string>): this {\n    this.config.auth = {\n      ...this.config.auth,\n      headers: { ...this.config.auth?.headers, ...headers },\n    };\n    return this;\n  }\n\n  /**\n   * Set the transport type\n   */\n  withTransport(transport: TestTransportType): this {\n    this.config.transport = transport;\n    return this;\n  }\n\n  /**\n   * Set the request timeout in milliseconds\n   */\n  withTimeout(timeoutMs: number): this {\n    this.config.timeout = timeoutMs;\n    return this;\n  }\n\n  /**\n   * Enable debug logging\n   */\n  withDebug(enabled = true): this {\n    this.config.debug = enabled;\n    return this;\n  }\n\n  /**\n   * Enable public mode - skip authentication entirely.\n   * When true, no Authorization header is sent and anonymous token is not requested.\n   * Use this for testing public/unauthenticated endpoints in CI/CD pipelines.\n   */\n  withPublicMode(enabled = true): this {\n    this.config.publicMode = enabled;\n    return this;\n  }\n\n  /**\n   * Set the MCP protocol version to request\n   */\n  withProtocolVersion(version: string): this {\n    this.config.protocolVersion = version;\n    return this;\n  }\n\n  /**\n   * Set the client info sent during initialization\n   */\n  withClientInfo(info: { name: string; version: string }): this {\n    this.config.clientInfo = info;\n    return this;\n  }\n\n  /**\n   * Build the McpTestClient instance (does not connect)\n   */\n  build(): McpTestClient {\n    return new McpTestClient(this.config);\n  }\n\n  /**\n   * Build the McpTestClient and connect to the server\n   */\n  async buildAndConnect(): Promise<McpTestClient> {\n    const client = this.build();\n    await client.connect();\n    return client;\n  }\n}\n"]}