@nitrostack/core 1.0.0

package/dist/auth/quick-setup.js

@@ -0,0 +1,210 @@
+import { createSimpleJWTAuth, generateJWT } from './simple-jwt.js';
+import { createAPIKeyAuth, generateAPIKey, hashAPIKey } from './api-key.js';
+import { configureServerAuth } from './server-integration.js';
+/**
+ * Quick Setup Helpers
+ *
+ * Make it dead simple to add authentication to NitroStack servers
+ */
+/**
+ * Setup Simple JWT Authentication (1-liner!)
+ *
+ * @example
+ * ```typescript
+ * const server = createServer({...});
+ *
+ * // That's it! JWT auth enabled
+ * setupJWTAuth(server.app, {
+ *   secret: process.env.JWT_SECRET!,
+ * });
+ *
+ * server.start();
+ * ```
+ */
+export function setupJWTAuth(app, config, path = '/mcp') {
+    const middleware = createSimpleJWTAuth(config);
+    app.use(path, middleware);
+    console.log(`✅ Simple JWT auth enabled on ${path}`);
+    console.log(`   Audience: ${config.audience || 'any'}`);
+    console.log(`   Issuer: ${config.issuer || 'any'}`);
+    console.log(`   Algorithm: ${config.algorithm || 'HS256'}`);
+}
+/**
+ * Setup API Key Authentication (1-liner!)
+ *
+ * @example
+ * ```typescript
+ * const server = createServer({...});
+ *
+ * // That's it! API key auth enabled
+ * setupAPIKeyAuth(server.app, {
+ *   keys: [process.env.API_KEY!],
+ * });
+ *
+ * server.start();
+ * ```
+ */
+export function setupAPIKeyAuth(app, config, path = '/mcp') {
+    const middleware = createAPIKeyAuth(config);
+    app.use(path, middleware);
+    console.log(`✅ API Key auth enabled on ${path}`);
+    console.log(`   Header: ${config.headerName || 'X-API-Key'}`);
+    console.log(`   Keys: ${config.keys.length} configured`);
+    console.log(`   Query param: ${config.allowQueryParam ? 'enabled' : 'disabled'}`);
+}
+/**
+ * Setup OAuth 2.1 Authentication (full enterprise setup)
+ *
+ * @example
+ * ```typescript
+ * const server = createServer({...});
+ *
+ * // Full OAuth 2.1 with PKCE
+ * setupOAuthAuth(server.app, {
+ *   resourceUri: 'https://mcp.example.com',
+ *   authorizationServers: ['https://auth.example.com'],
+ *   tokenIntrospectionEndpoint: '...',
+ *   tokenIntrospectionClientId: '...',
+ *   tokenIntrospectionClientSecret: process.env.INTROSPECTION_SECRET,
+ * });
+ *
+ * server.start();
+ * ```
+ */
+export function setupOAuthAuth(app, config, path = '/mcp') {
+    configureServerAuth(app, config, {
+        protectRoutes: [path],
+    });
+    console.log(`✅ OAuth 2.1 auth enabled on ${path}`);
+    console.log(`   Resource URI: ${config.resourceUri}`);
+    console.log(`   Auth Servers: ${config.authorizationServers.join(', ')}`);
+    console.log(`   Scopes: ${config.scopesSupported?.join(', ') || 'none'}`);
+}
+/**
+ * Generate test credentials (for development)
+ *
+ * @example
+ * ```typescript
+ * const creds = generateTestCredentials();
+ * console.log('JWT Secret:', creds.jwtSecret);
+ * console.log('API Key:', creds.apiKey);
+ * console.log('Sample Token:', creds.sampleToken);
+ * ```
+ */
+export function generateTestCredentials(options) {
+    const jwtSecret = generateAPIKey('jwt_secret');
+    const apiKey = generateAPIKey(options?.apiKeyPrefix);
+    const sampleToken = generateJWT({
+        secret: jwtSecret,
+        payload: {
+            sub: 'test-user',
+            scopes: ['mcp:read', 'mcp:write'],
+        },
+        expiresIn: '1h',
+        audience: options?.jwtAudience,
+        issuer: options?.jwtIssuer,
+    });
+    return {
+        jwtSecret,
+        apiKey,
+        apiKeyHashed: hashAPIKey(apiKey),
+        sampleToken,
+    };
+}
+/**
+ * Print auth setup instructions
+ */
+export function printAuthSetupInstructions(type) {
+    console.log('\n╔══════════════════════════════════════════════════════════════╗');
+    console.log('║                    AUTH SETUP INSTRUCTIONS                   ║');
+    console.log('╚══════════════════════════════════════════════════════════════╝\n');
+    if (type === 'jwt') {
+        console.log('📝 Simple JWT Authentication Setup:\n');
+        console.log('1. Generate a secret:');
+        console.log('   const creds = generateTestCredentials();');
+        console.log('   console.log(creds.jwtSecret);\n');
+        console.log('2. Add to .env:');
+        console.log('   JWT_SECRET=jwt_secret_...\n');
+        console.log('3. Enable in server:');
+        console.log('   setupJWTAuth(server.app, {');
+        console.log('     secret: process.env.JWT_SECRET!,');
+        console.log('     audience: "my-mcp-server",');
+        console.log('   });\n');
+        console.log('4. Generate tokens:');
+        console.log('   const token = generateJWT({');
+        console.log('     secret: process.env.JWT_SECRET!,');
+        console.log('     payload: { sub: "user123" },');
+        console.log('     expiresIn: "1h",');
+        console.log('   });\n');
+        console.log('5. Use in client:');
+        console.log('   Authorization: Bearer <token>\n');
+    }
+    if (type === 'apikey') {
+        console.log('📝 API Key Authentication Setup:\n');
+        console.log('1. Generate API keys:');
+        console.log('   const key1 = generateAPIKey();');
+        console.log('   const key2 = generateAPIKey();\n');
+        console.log('2. Add to .env:');
+        console.log('   API_KEY_1=sk_...');
+        console.log('   API_KEY_2=sk_...\n');
+        console.log('3. Enable in server:');
+        console.log('   setupAPIKeyAuth(server.app, {');
+        console.log('     keys: [');
+        console.log('       process.env.API_KEY_1!,');
+        console.log('       process.env.API_KEY_2!,');
+        console.log('     ],');
+        console.log('   });\n');
+        console.log('4. Use in client:');
+        console.log('   X-API-Key: sk_...\n');
+    }
+    if (type === 'oauth') {
+        console.log('📝 OAuth 2.1 Authentication Setup:\n');
+        console.log('1. Deploy an OAuth 2.1 authorization server');
+        console.log('   (e.g., Auth0, Keycloak, Azure AD)\n');
+        console.log('2. Configure in server:');
+        console.log('   setupOAuthAuth(server.app, {');
+        console.log('     resourceUri: "https://mcp.example.com",');
+        console.log('     authorizationServers: ["https://auth.example.com"],');
+        console.log('     tokenIntrospectionEndpoint: "...",');
+        console.log('     tokenIntrospectionClientId: "...",');
+        console.log('     tokenIntrospectionClientSecret: process.env.SECRET,');
+        console.log('   });\n');
+        console.log('3. Use the inspector AUTH tab to test\n');
+    }
+    console.log('═══════════════════════════════════════════════════════════════\n');
+}
+/**
+ * Validate auth environment variables
+ */
+export function validateAuthEnv(type) {
+    const missing = [];
+    if (type === 'jwt') {
+        if (!process.env.JWT_SECRET) {
+            missing.push('JWT_SECRET');
+        }
+    }
+    if (type === 'apikey') {
+        if (!process.env.API_KEY_1 && !process.env.API_KEY) {
+            missing.push('API_KEY_1 or API_KEY');
+        }
+    }
+    if (type === 'oauth') {
+        const required = [
+            'OAUTH_RESOURCE_URI',
+            'OAUTH_AUTH_SERVER',
+            'OAUTH_INTROSPECTION_ENDPOINT',
+            'OAUTH_CLIENT_ID',
+            'OAUTH_CLIENT_SECRET',
+        ];
+        for (const key of required) {
+            if (!process.env[key]) {
+                missing.push(key);
+            }
+        }
+    }
+    return {
+        valid: missing.length === 0,
+        missing,
+    };
+}
+//# sourceMappingURL=quick-setup.js.map

package/dist/auth/quick-setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quick-setup.js","sourceRoot":"","sources":["../../src/auth/quick-setup.ts"],"names":[],"mappings":"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"}

package/dist/auth/secure-secret.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Secure Secret Value
+ *
+ * Provides a type-safe way to handle secrets that prevents accidental hardcoding.
+ * Secrets must be explicitly created from environment variables or marked as explicit.
+ *
+ * @example
+ * ```typescript
+ * // ✅ Recommended: Load from environment variable
+ * const secret = SecretValue.fromEnv('JWT_SECRET');
+ *
+ * // ✅ For testing only: Mark as explicit
+ * const testSecret = SecretValue.fromValue('test-secret', { allowHardcoded: true });
+ *
+ * // ❌ This will fail at runtime:
+ * const badSecret = SecretValue.fromValue('hardcoded'); // throws error
+ * ```
+ */
+declare const SecretBrand: unique symbol;
+/**
+ * A branded type representing a secret value.
+ * Cannot be created directly - must use factory methods.
+ */
+export type SecretString = string & {
+    readonly [SecretBrand]: 'SecretValue';
+};
+/**
+ * Options for creating a secret from a direct value
+ */
+export interface FromValueOptions {
+    /**
+     * Explicitly allow hardcoded values.
+     * Only set to true for testing purposes.
+     */
+    allowHardcoded?: boolean;
+    /**
+     * Description of why hardcoded is allowed (for audit purposes)
+     */
+    reason?: string;
+}
+/**
+ * Secure wrapper for secret values
+ */
+export declare class SecretValue {
+    private readonly value;
+    private readonly source;
+    private constructor();
+    /**
+     * Create a secret from an environment variable.
+     * This is the recommended way to handle secrets.
+     *
+     * @param envVarName - Name of the environment variable
+     * @param options - Optional configuration
+     * @throws Error if the environment variable is not set
+     *
+     * @example
+     * ```typescript
+     * const jwtSecret = SecretValue.fromEnv('JWT_SECRET');
+     * const dbPassword = SecretValue.fromEnv('DATABASE_PASSWORD');
+     * ```
+     */
+    static fromEnv(envVarName: string, options?: {
+        required?: boolean;
+    }): SecretValue;
+    /**
+     * Create a secret from a direct value.
+     *
+     * **WARNING**: This should only be used for testing.
+     * For production, always use `fromEnv()`.
+     *
+     * @param value - The secret value
+     * @param options - Must set allowHardcoded: true to use this method
+     * @throws Error if allowHardcoded is not explicitly set to true
+     *
+     * @example
+     * ```typescript
+     * // For testing only
+     * const testSecret = SecretValue.fromValue('test-secret-for-unit-tests', {
+     *   allowHardcoded: true,
+     *   reason: 'Unit test fixture'
+     * });
+     * ```
+     */
+    static fromValue(value: string, options?: FromValueOptions): SecretValue;
+    /**
+     * Create a secret from an environment variable or return undefined.
+     * Useful for optional secrets.
+     *
+     * @param envVarName - Name of the environment variable
+     *
+     * @example
+     * ```typescript
+     * const optionalSecret = SecretValue.fromEnvOptional('OPTIONAL_API_KEY');
+     * if (optionalSecret) {
+     *   // Use the secret
+     * }
+     * ```
+     */
+    static fromEnvOptional(envVarName: string): SecretValue | undefined;
+    /**
+     * Get the unwrapped secret value.
+     *
+     * @returns The raw secret string
+     */
+    unwrap(): SecretString;
+    /**
+     * Get the secret value as a plain string.
+     * Alias for unwrap() for compatibility.
+     */
+    getValue(): string;
+    /**
+     * Check if this secret was loaded from environment
+     */
+    isFromEnvironment(): boolean;
+    /**
+     * Prevent accidental logging of secret values
+     */
+    toString(): string;
+    /**
+     * Prevent accidental JSON serialization of secret values
+     */
+    toJSON(): string;
+}
+/**
+ * Type guard to check if a value is a SecretValue
+ */
+export declare function isSecretValue(value: unknown): value is SecretValue;
+/**
+ * Helper to unwrap a secret if it's a SecretValue, or use as-is if string.
+ * Useful for backward compatibility.
+ *
+ * @deprecated Prefer using SecretValue directly
+ */
+export declare function unwrapSecret(secret: SecretValue | string): string;
+export {};
+//# sourceMappingURL=secure-secret.d.ts.map

package/dist/auth/secure-secret.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secure-secret.d.ts","sourceRoot":"","sources":["../../src/auth/secure-secret.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,CAAC,MAAM,WAAW,EAAE,OAAO,MAAM,CAAC;AAEzC;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,WAAW,CAAC,EAAE,aAAa,CAAA;CAAE,CAAC;AAE9E;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAE5C,OAAO;IAiBP;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,WAAW;IAkBjF;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,WAAW;IAsBxE;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAQnE;;;;OAIG;IACH,MAAM,IAAI,YAAY;IAItB;;;OAGG;IACH,QAAQ,IAAI,MAAM;IAIlB;;OAEG;IACH,iBAAiB,IAAI,OAAO;IAI5B;;OAEG;IACH,QAAQ,IAAI,MAAM;IAIlB;;OAEG;IACH,MAAM,IAAI,MAAM;CAUjB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,GAAG,MAAM,CAYjE"}

package/dist/auth/secure-secret.js

@@ -0,0 +1,182 @@
+/**
+ * Secure Secret Value
+ *
+ * Provides a type-safe way to handle secrets that prevents accidental hardcoding.
+ * Secrets must be explicitly created from environment variables or marked as explicit.
+ *
+ * @example
+ * ```typescript
+ * // ✅ Recommended: Load from environment variable
+ * const secret = SecretValue.fromEnv('JWT_SECRET');
+ *
+ * // ✅ For testing only: Mark as explicit
+ * const testSecret = SecretValue.fromValue('test-secret', { allowHardcoded: true });
+ *
+ * // ❌ This will fail at runtime:
+ * const badSecret = SecretValue.fromValue('hardcoded'); // throws error
+ * ```
+ */
+/**
+ * Secure wrapper for secret values
+ */
+export class SecretValue {
+    value;
+    source;
+    constructor(value, source) {
+        if (!value || value.length === 0) {
+            throw new Error('Secret value cannot be empty');
+        }
+        // Minimum length check for security
+        if (value.length < 16) {
+            console.warn('[SecretValue] Warning: Secret is less than 16 characters. ' +
+                'Consider using a longer secret for better security.');
+        }
+        this.value = value;
+        this.source = source;
+    }
+    /**
+     * Create a secret from an environment variable.
+     * This is the recommended way to handle secrets.
+     *
+     * @param envVarName - Name of the environment variable
+     * @param options - Optional configuration
+     * @throws Error if the environment variable is not set
+     *
+     * @example
+     * ```typescript
+     * const jwtSecret = SecretValue.fromEnv('JWT_SECRET');
+     * const dbPassword = SecretValue.fromEnv('DATABASE_PASSWORD');
+     * ```
+     */
+    static fromEnv(envVarName, options) {
+        const value = process.env[envVarName];
+        const required = options?.required !== false;
+        if (!value) {
+            if (required) {
+                throw new Error(`Environment variable ${envVarName} is not set. ` +
+                    `Please set it in your environment or .env file.`);
+            }
+            // Return a placeholder that will fail if used
+            throw new Error(`Environment variable ${envVarName} is not set.`);
+        }
+        return new SecretValue(value, 'env');
+    }
+    /**
+     * Create a secret from a direct value.
+     *
+     * **WARNING**: This should only be used for testing.
+     * For production, always use `fromEnv()`.
+     *
+     * @param value - The secret value
+     * @param options - Must set allowHardcoded: true to use this method
+     * @throws Error if allowHardcoded is not explicitly set to true
+     *
+     * @example
+     * ```typescript
+     * // For testing only
+     * const testSecret = SecretValue.fromValue('test-secret-for-unit-tests', {
+     *   allowHardcoded: true,
+     *   reason: 'Unit test fixture'
+     * });
+     * ```
+     */
+    static fromValue(value, options) {
+        if (!options?.allowHardcoded) {
+            throw new Error('Hardcoded secrets are not allowed. ' +
+                'Use SecretValue.fromEnv() to load secrets from environment variables. ' +
+                'If you must use a hardcoded value (e.g., for testing), ' +
+                'set allowHardcoded: true explicitly.');
+        }
+        // Log warning in non-test environments
+        if (process.env.NODE_ENV !== 'test') {
+            console.warn(`[SecretValue] Warning: Using hardcoded secret value. ` +
+                `Reason: ${options.reason || 'Not specified'}. ` +
+                `This should not be used in production.`);
+        }
+        return new SecretValue(value, 'explicit');
+    }
+    /**
+     * Create a secret from an environment variable or return undefined.
+     * Useful for optional secrets.
+     *
+     * @param envVarName - Name of the environment variable
+     *
+     * @example
+     * ```typescript
+     * const optionalSecret = SecretValue.fromEnvOptional('OPTIONAL_API_KEY');
+     * if (optionalSecret) {
+     *   // Use the secret
+     * }
+     * ```
+     */
+    static fromEnvOptional(envVarName) {
+        const value = process.env[envVarName];
+        if (!value) {
+            return undefined;
+        }
+        return new SecretValue(value, 'env');
+    }
+    /**
+     * Get the unwrapped secret value.
+     *
+     * @returns The raw secret string
+     */
+    unwrap() {
+        return this.value;
+    }
+    /**
+     * Get the secret value as a plain string.
+     * Alias for unwrap() for compatibility.
+     */
+    getValue() {
+        return this.value;
+    }
+    /**
+     * Check if this secret was loaded from environment
+     */
+    isFromEnvironment() {
+        return this.source === 'env';
+    }
+    /**
+     * Prevent accidental logging of secret values
+     */
+    toString() {
+        return '[SecretValue: REDACTED]';
+    }
+    /**
+     * Prevent accidental JSON serialization of secret values
+     */
+    toJSON() {
+        return '[SecretValue: REDACTED]';
+    }
+    /**
+     * For Node.js util.inspect
+     */
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        return `SecretValue { source: '${this.source}', value: [REDACTED] }`;
+    }
+}
+/**
+ * Type guard to check if a value is a SecretValue
+ */
+export function isSecretValue(value) {
+    return value instanceof SecretValue;
+}
+/**
+ * Helper to unwrap a secret if it's a SecretValue, or use as-is if string.
+ * Useful for backward compatibility.
+ *
+ * @deprecated Prefer using SecretValue directly
+ */
+export function unwrapSecret(secret) {
+    if (secret instanceof SecretValue) {
+        return secret.getValue();
+    }
+    // Log warning for raw strings in production
+    if (process.env.NODE_ENV === 'production') {
+        console.warn('[SecretValue] Warning: Using raw string as secret. ' +
+            'Consider migrating to SecretValue.fromEnv() for better security.');
+    }
+    return secret;
+}
+//# sourceMappingURL=secure-secret.js.map

package/dist/auth/secure-secret.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secure-secret.js","sourceRoot":"","sources":["../../src/auth/secure-secret.ts"],"names":[],"mappings":"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"}

package/dist/auth/server-integration.d.ts

@@ -0,0 +1,97 @@
+import { Express } from 'express';
+import { McpAuthConfig } from './types.js';
+import { requireScopes } from './middleware.js';
+export type { McpAuthConfig } from './types.js';
+/**
+ * Server Integration Utilities
+ *
+ * Easy integration of OAuth 2.1 auth into MCP servers
+ */
+/**
+ * Configure authentication for MCP server
+ *
+ * This adds:
+ * 1. Protected Resource Metadata endpoint
+ * 2. Authentication middleware to specified routes
+ *
+ * @param app - Express application
+ * @param config - Auth configuration
+ * @param protectRoutes - Routes to protect with auth (default: all /mcp routes)
+ *
+ * @example
+ * ```typescript
+ * const app = express();
+ *
+ * configureServerAuth(app, {
+ *   resourceUri: 'https://mcp.example.com',
+ *   authorizationServers: ['https://auth.example.com'],
+ *   tokenIntrospectionEndpoint: 'https://auth.example.com/oauth/introspect',
+ *   tokenIntrospectionClientId: 'mcp-server',
+ *   tokenIntrospectionClientSecret: process.env.INTROSPECTION_SECRET,
+ *   audience: 'https://mcp.example.com',
+ *   scopesSupported: ['mcp:read', 'mcp:write']
+ * }, {
+ *   protectRoutes: ['/mcp/*']
+ * });
+ * ```
+ */
+export declare function configureServerAuth(app: Express, config: McpAuthConfig, options?: {
+    protectRoutes?: string[];
+    metadataPath?: string;
+}): void;
+/**
+ * Scope-based route protection helper
+ *
+ * @example
+ * ```typescript
+ * const scopes = createScopeGuards(['mcp:read', 'mcp:write', 'mcp:admin']);
+ *
+ * app.get('/mcp/tools', scopes.read, (req, res) => {
+ *   // List tools - requires mcp:read
+ * });
+ *
+ * app.post('/mcp/tools/execute', scopes.write, (req, res) => {
+ *   // Execute tool - requires mcp:write
+ * });
+ *
+ * app.delete('/mcp/resources', scopes.admin, (req, res) => {
+ *   // Delete resource - requires mcp:admin
+ * });
+ * ```
+ */
+export declare function createScopeGuards(scopeConfig: {
+    read?: string[];
+    write?: string[];
+    admin?: string[];
+    [key: string]: string[] | undefined;
+}): Record<string, ReturnType<typeof requireScopes>>;
+/**
+ * Create standard MCP scope configuration
+ *
+ * Returns scope guards for common MCP operations:
+ * - read: List tools, resources, prompts
+ * - execute: Execute tools, get prompts
+ * - write: Modify resources
+ * - admin: Server configuration
+ *
+ * @param scopePrefix - Scope prefix (default: 'mcp')
+ */
+export declare function createMCPScopeGuards(scopePrefix?: string): Record<string, import("express").RequestHandler<import("express-serve-static-core").ParamsDictionary, any, any, import("qs").ParsedQs, Record<string, any>>>;
+/**
+ * Generate suggested scopes for MCP server
+ *
+ * Returns standard scope definitions for MCP operations
+ */
+export declare function getStandardMCPScopes(scopePrefix?: string): {
+    scopes: string[];
+    descriptions: Record<string, string>;
+};
+/**
+ * Helper to validate auth configuration
+ */
+export declare function validateAuthConfig(config: McpAuthConfig): {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+};
+//# sourceMappingURL=server-integration.d.ts.map

package/dist/auth/server-integration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-integration.d.ts","sourceRoot":"","sources":["../../src/auth/server-integration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,OAAO,EAAwB,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGtE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,aAAa,EACrB,OAAO,CAAC,EAAE;IACR,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GACA,IAAI,CA0BN;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE;IAC7C,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;CACrC,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC,CAUnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,GAAE,MAAc,gKAO/D;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,GAAE,MAAc,GAAG;IACjE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC,CAgBA;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,GAAG;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAkEA"}