@stackwright-pro/openapi 0.0.0-beta-20260417191149

package/dist/index.d.mts

@@ -0,0 +1,981 @@
+import { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
+import { z, ZodSchema } from 'zod';
+
+/**
+ * Supported OpenAPI versions
+ */
+type OpenAPIDocument = OpenAPIV3.Document | OpenAPIV3_1.Document;
+/**
+ * An approved API specification.
+ * Used by enterprise customers to whitelist specific OpenAPI specs.
+ */
+interface ApprovedSpec {
+    /** Human-readable name for the spec */
+    name: string;
+    /** URL or file path to the approved spec */
+    url: string;
+    /** Expected SHA-256 hash of the spec content */
+    sha256: string;
+}
+/**
+ * Security configuration for approved specs enforcement.
+ * Configured in stackwright.yml under `prebuild.security`.
+ */
+interface PrebuildSecurityConfig {
+    /** Enable approved-specs enforcement */
+    enabled: boolean;
+    /** List of approved specifications */
+    allowlist: ApprovedSpec[];
+}
+/**
+ * Result of validating a spec against the approved list.
+ */
+interface ValidationResult {
+    /** Whether the spec is approved */
+    valid: boolean;
+    /** Error code if not valid */
+    errorCode?: 'SPEC_NOT_ON_ALLOWLIST' | 'SPEC_MODIFIED' | 'DOWNLOAD_FAILED';
+    /** Human-readable error message */
+    error?: string;
+    /** URL of the spec that was validated */
+    specUrl?: string;
+}
+/**
+ * Extended site config with prebuild security.
+ * Users can add this to stackwright.yml.
+ */
+interface SiteConfig {
+    /** Prebuild configuration */
+    prebuild?: {
+        /** Security settings for approved-specs enforcement */
+        security?: PrebuildSecurityConfig;
+    };
+}
+/**
+ * Endpoint filter configuration
+ */
+interface EndpointFilter$1 {
+    /** Endpoints/patterns to include (default: all) */
+    include?: string[];
+    /** Endpoints/patterns to exclude */
+    exclude?: string[];
+}
+/**
+ * Configuration for OpenAPI integration in stackwright.yml
+ */
+interface OpenAPIConfig {
+    /** Name of this integration */
+    name: string;
+    /** OpenAPI spec (URL or local file path) */
+    spec: string;
+    /** Mock server URL for development (e.g., http://localhost:4010) */
+    mockUrl?: string;
+    /** Authentication configuration */
+    auth?: {
+        type: 'bearer' | 'apiKey' | 'oauth2';
+        token?: string;
+        apiKey?: string;
+    };
+    /** Collections to generate from endpoints */
+    collections?: Array<{
+        /** API endpoint path */
+        endpoint: string;
+        /** Field to use as slug/ID */
+        slug_field: string;
+        /** Optional filters */
+        filters?: Record<string, unknown>;
+    }>;
+    /** Endpoint filter - only generate code for matching endpoints */
+    endpoints?: EndpointFilter$1;
+}
+/**
+ * Result of OpenAPI compilation
+ */
+interface OpenAPICompilationResult {
+    /** Generated Zod schemas as code */
+    schemas: string;
+    /** Generated TypeScript types */
+    types: string;
+    /** Generated CollectionProvider implementation */
+    provider: string;
+    /** Generated API client */
+    client: string;
+}
+
+interface ParseOptions {
+    /** Whether to dereference $ref (default: true) */
+    dereference?: boolean;
+    /** Whether to validate the spec (default: true) */
+    validate?: boolean;
+}
+interface ParseResult {
+    /** Parsed and normalized OpenAPI document */
+    document: OpenAPIDocument;
+    /** OpenAPI version (3.0.x or 3.1.x) */
+    version: string;
+    /** Whether the spec was dereferenced */
+    dereferenced: boolean;
+}
+/**
+ * OpenAPI spec parser and validator
+ *
+ * Handles both OpenAPI 3.0 and 3.1 specs.
+ * Can parse from URL or local file path.
+ */
+declare class OpenAPIParser {
+    /**
+     * Parse an OpenAPI specification from URL or file path
+     *
+     * @param specPath - URL or local file path to OpenAPI spec
+     * @param options - Parsing options
+     * @returns Parsed and validated OpenAPI document
+     *
+     * @example
+     * ```typescript
+     * const parser = new OpenAPIParser();
+     * const result = await parser.parse('https://api.example.com/openapi.json');
+     * console.log(`Parsed OpenAPI ${result.version}`);
+     * ```
+     */
+    parse(specPath: string, options?: ParseOptions): Promise<ParseResult>;
+    /**
+     * Detect OpenAPI version from document
+     */
+    private detectVersion;
+    /**
+     * Enhance error messages with context
+     */
+    private enhanceError;
+    /**
+     * Check if a spec path is a URL
+     */
+    static isURL(specPath: string): boolean;
+    /**
+     * Validate that a document is OpenAPI 3.x (not Swagger 2.x)
+     */
+    static isOpenAPI3(document: unknown): document is OpenAPIDocument;
+}
+
+type SchemaObject$1 = OpenAPIV3.SchemaObject | OpenAPIV3_1.SchemaObject;
+/**
+ * Resolves schemas from OpenAPI documents
+ *
+ * Handles extracting and normalizing schemas for code generation.
+ */
+declare class SchemaResolver {
+    private document;
+    constructor(document: OpenAPIV3.Document | OpenAPIV3_1.Document);
+    /**
+     * Get schema for a specific path and method
+     *
+     * @param path - API path (e.g., '/equipment')
+     * @param method - HTTP method (e.g., 'get')
+     * @param responseCode - Response code (default: '200')
+     * @returns Schema object or undefined
+     */
+    getResponseSchema(path: string, method: string, responseCode?: string): SchemaObject$1 | undefined;
+    /**
+     * Get all schemas defined in components
+     */
+    getAllSchemas(): Record<string, SchemaObject$1>;
+    /**
+     * Get a specific component schema by name
+     */
+    getComponentSchema(name: string): SchemaObject$1 | undefined;
+    /**
+     * Extract all endpoints from the OpenAPI document
+     */
+    getAllEndpoints(): Array<{
+        path: string;
+        method: string;
+        operationId?: string;
+        summary?: string;
+        description?: string;
+    }>;
+}
+
+type SchemaObject = OpenAPIV3.SchemaObject | OpenAPIV3_1.SchemaObject;
+interface ZodGenerationOptions {
+    /** Whether to make all fields optional by default */
+    optionalByDefault?: boolean;
+    /** Custom name for the generated schema */
+    schemaName?: string;
+    /** If true, emit only the schema + type — no import statements */
+    bare?: boolean;
+}
+/**
+ * Generates Zod schemas from OpenAPI schema objects
+ *
+ * This is the CORE of the "mathematically proven code" value proposition.
+ * OpenAPI schemas → Zod validation = runtime safety guarantees.
+ */
+declare class ZodSchemaGenerator {
+    /**
+     * Generate a Zod schema from an OpenAPI schema object
+     *
+     * @param schema - OpenAPI schema object
+     * @param options - Generation options
+     * @returns Zod schema code as string
+     */
+    generate(schema: SchemaObject, options?: ZodGenerationOptions): string;
+    /**
+     * Convert OpenAPI schema to Zod schema code
+     */
+    private schemaToZod;
+    /**
+     * Map OpenAPI type to Zod schema
+     */
+    private schemaTypeToZod;
+    /**
+     * Handle string schemas with formats and enums
+     */
+    private stringToZod;
+    /**
+     * Handle number/integer schemas
+     */
+    private numberToZod;
+    /**
+     * Handle array schemas
+     */
+    private arrayToZod;
+    /**
+     * Handle object schemas
+     */
+    private objectToZod;
+    /**
+     * Handle allOf, anyOf, oneOf composition
+     */
+    private handleComposition;
+}
+
+interface TypeGenerationOptions {
+    /** Name for the generated type */
+    typeName?: string;
+    /** Whether to include JSDoc comments */
+    includeJsDoc?: boolean;
+}
+/**
+ * Generates TypeScript types from Zod schemas
+ *
+ * Converts runtime-validatable Zod schemas into compile-time TypeScript types.
+ */
+declare class TypeGenerator {
+    /**
+     * Generate TypeScript type definition from a Zod schema
+     *
+     * @param zodSchema - Zod schema object
+     * @param options - Generation options
+     * @returns TypeScript type definition as string
+     *
+     * @example
+     * ```typescript
+     * const schema = z.object({ name: z.string(), age: z.number() });
+     * const generator = new TypeGenerator();
+     * const typeCode = generator.generate(schema, { typeName: 'User' });
+     * // export type User = { name: string; age: number; };
+     * ```
+     */
+    generate(zodSchema: z.ZodTypeAny, options?: TypeGenerationOptions): string;
+    /**
+     * Generate type from Zod schema code string
+     *
+     * This is used when we have the schema as code (from ZodSchemaGenerator)
+     * rather than as a runtime Zod object.
+     *
+     * @param zodSchemaCode - Zod schema as TypeScript code string
+     * @param typeName - Name for the generated type
+     * @returns TypeScript type definition
+     */
+    generateFromCode(zodSchemaCode: string, typeName: string): string;
+    /**
+     * Generate multiple types from a map of Zod schemas
+     *
+     * @param schemas - Map of schema names to Zod schemas
+     * @returns Object with type definitions for each schema
+     */
+    generateMultiple(schemas: Record<string, z.ZodTypeAny>, options?: Omit<TypeGenerationOptions, 'typeName'>): Record<string, string>;
+    /**
+     * Combine multiple type definitions into a single TypeScript module
+     *
+     * @param types - Map of type names to type code
+     * @param imports - Additional imports to include
+     * @returns Complete TypeScript module code
+     */
+    createModule(types: Record<string, string>, imports?: string[]): string;
+}
+
+interface CollectionConfig {
+    /** API endpoint path */
+    endpoint: string;
+    /** Field to use as slug/ID */
+    slugField: string;
+    /** HTTP method (default: 'get') */
+    method?: string;
+    /** Collection name (defaults to sanitized endpoint) */
+    name?: string;
+}
+interface ProviderGenerationOptions {
+    /** Name for the provider class */
+    providerName?: string;
+    /** Base URL for the API */
+    baseUrl?: string;
+    /** Auth configuration */
+    auth?: {
+        type: 'bearer' | 'apiKey';
+        headerName?: string;
+    };
+    /** If true, emit only the class code without import statements */
+    bare?: boolean;
+}
+/**
+ * Generates CollectionProvider implementations from OpenAPI specs
+ *
+ * This is the bridge between OpenAPI APIs and Stackwright's content system.
+ */
+declare class CollectionProviderGenerator {
+    private document;
+    constructor(document: OpenAPIDocument);
+    /**
+     * Generate a CollectionProvider implementation for a specific endpoint
+     *
+     * @param config - Collection configuration
+     * @param options - Generation options
+     * @returns TypeScript code for the provider
+     */
+    generate(config: CollectionConfig, options?: ProviderGenerationOptions): string;
+    /**
+     * Generate the complete provider code
+     */
+    private generateProviderCode;
+    /**
+     * Generate get method implementation
+     */
+    private generateGetMethod;
+    /**
+     * Generate auth header code
+     */
+    private generateAuthHeader;
+    /**
+     * Get base URL from OpenAPI spec
+     */
+    private getBaseUrl;
+    /**
+     * Generate provider class name from config
+     */
+    private generateProviderName;
+    /**
+     * Sanitize path to valid identifier
+     */
+    private sanitizePath;
+    /**
+     * Capitalize string
+     */
+    private capitalize;
+    /**
+     * Guess which field might be a good title
+     */
+    private guessTitle;
+}
+
+/**
+ * Mapping of operationId to schema names
+ */
+interface SchemaMapping {
+    [operationId: string]: {
+        /** Schema name for request validation (null if no params) */
+        requestSchema: string | null;
+        /** Schema name for response validation */
+        responseSchema: string;
+    };
+}
+/**
+ * Options for client generation
+ */
+interface ClientGenerationOptions {
+    /** Name of the client class */
+    className?: string;
+    /** Whether to include JSDoc comments (default: true) */
+    includeJsDoc?: boolean;
+    /** Base URL for the API */
+    baseUrl?: string;
+    /** Whether to validate responses with Zod (default: true) */
+    validateResponses?: boolean;
+    /** Use strict validation - throw on parse errors vs safe parse (default: false) */
+    strictValidation?: boolean;
+    /** Mapping of operationId to schema names for Zod validation */
+    schemaMapping?: SchemaMapping;
+}
+/**
+ * ClientGenerator
+ *
+ * Generates fully typed API client functions from OpenAPI operations.
+ * Each endpoint becomes a type-safe function with runtime Zod validation.
+ *
+ * **Refactored to use Zod schemas as single source of truth:**
+ * - Types inferred from Zod schemas (no more manual type generation)
+ * - Request validation before API calls
+ * - Response validation after API calls
+ * - Optional strict validation mode
+ */
+declare class ClientGenerator {
+    private document;
+    private resolver;
+    private schemaMapping?;
+    private requiredSchemas;
+    private generatedRequestSchemas;
+    constructor(document: OpenAPIDocument, schemaMapping?: SchemaMapping);
+    /**
+     * Generate typed API client code from OpenAPI document
+     */
+    generate(options?: ClientGenerationOptions): string;
+    /**
+     * Generate import statements including Zod and schemas
+     */
+    private generateImports;
+    /**
+     * Track which schemas are used for imports
+     */
+    private addRequiredSchema;
+    /**
+     * Generate Zod schemas for request parameters
+     *
+     * This generates schemas like:
+     * export const ListEquipmentRequestSchema = z.object({
+     *   query: z.object({ ... }).optional(),
+     * });
+     */
+    private generateRequestSchemas;
+    /**
+     * Generate request schema for a single endpoint
+     */
+    private generateRequestSchemaForEndpoint;
+    /**
+     * Generate Zod schema for path parameters
+     */
+    private generatePathParamsSchema;
+    /**
+     * Generate Zod schema for query parameters
+     */
+    private generateQueryParamsSchema;
+    /**
+     * Generate Zod schema for header parameters
+     */
+    private generateHeaderParamsSchema;
+    /**
+     * Generate Zod schema for request body
+     */
+    private generateRequestBodySchema;
+    /**
+     * Convert parameter schema to Zod schema string
+     */
+    private parameterSchemaToZod;
+    /**
+     * Convert OpenAPI schema object to Zod schema string
+     *
+     * This is a simplified version for parameter schemas.
+     * Reuses logic similar to ZodSchemaGenerator but outputs inline.
+     */
+    private schemaObjectToZod;
+    /**
+     * Convert string schema to Zod
+     */
+    private stringSchemaToZod;
+    /**
+     * Convert number schema to Zod
+     */
+    private numberSchemaToZod;
+    /**
+     * Check if header is a common header handled by fetch
+     */
+    private isCommonHeader;
+    /**
+     * Extract component name from $ref
+     */
+    private extractComponentName;
+    /**
+     * Escape string for use in Zod .describe()
+     */
+    private escapeString;
+    /**
+     * Get list of all required schema names
+     */
+    private getRequiredSchemas;
+    /**
+     * Generate TypeScript types for request/response
+     *
+     * If schemaMapping is provided, use z.infer<> to get types from Zod schemas.
+     * Otherwise, fall back to legacy manual type generation.
+     */
+    private generateTypes;
+    /**
+     * Generate types using Zod inference (NEW)
+     */
+    /**
+     * Generate types using Zod inference (NEW)
+     *
+     * Request types infer from request schemas (defined in this file).
+     * Response types infer from response schemas (imported from ./schemas).
+     */
+    private generateTypesFromZod;
+    /**
+     * Generate types using manual conversion (LEGACY - backward compatible)
+     */
+    private generateTypesLegacy;
+    /**
+     * Generate request type for an operation (LEGACY)
+     */
+    private generateRequestTypeLegacy;
+    /**
+     * Generate response type for an operation (LEGACY)
+     */
+    private generateResponseTypeLegacy;
+    /**
+     * Get request body type (LEGACY)
+     */
+    private getRequestBodyTypeLegacy;
+    /**
+     * Convert OpenAPI schema to TypeScript type (LEGACY)
+     *
+     * NOTE: This method is kept for backward compatibility but should be
+     * replaced with Zod inference in new code.
+     */
+    private getTypeFromSchemaLegacy;
+    /**
+     * Generate error classes for API errors and validation errors
+     */
+    /**
+     * Generate error classes (APIError and ValidationError)
+     */
+    private generateErrorClasses;
+    /**
+     * Generate the main client class
+     */
+    private generateClientClass;
+    /**
+     * Generate constructor
+     */
+    private generateConstructor;
+    /**
+     * Generate a method for an endpoint with Zod validation (NEW)
+     */
+    /**
+     * Generate a method for an endpoint with Zod validation (NEW)
+     */
+    private generateMethodWithValidation;
+    /**
+     * Generate a method for an endpoint (LEGACY)
+     */
+    private generateMethodLegacy;
+    /**
+     * Generate the request helper method
+     */
+    private generateRequestHelper;
+    /**
+     * Get all endpoints from the document
+     */
+    private getAllEndpoints;
+    /**
+     * Deduplicate colliding operationIds by appending a path-based suffix.
+     *
+     * Real-world specs (e.g. SAM.gov) reuse the same operationId across
+     * versioned paths. We make each one unique so the generated client
+     * has no duplicate method names.
+     */
+    private deduplicateOperationIds;
+    /**
+     * Turn an API path into a valid, readable identifier suffix.
+     * e.g. '/entity-information/v4/download-entities' -> 'entityInformationV4DownloadEntities'
+     */
+    private sanitizePath;
+    /**
+     * Get parameters for an operation
+     */
+    private getOperationParameters;
+    /**
+     * Check if operation has request body
+     */
+    private hasRequestBody;
+    /**
+     * Check if request body is required
+     */
+    private isRequestBodyRequired;
+    /**
+     * Get method name from endpoint
+     */
+    private getMethodName;
+    /**
+     * Get type name for operation
+     */
+    private getOperationTypeName;
+    /**
+     * Convert to camelCase
+     */
+    private camelCase;
+    /**
+     * Convert to PascalCase
+     */
+    private pascalCase;
+    /**
+     * Get default base URL from servers
+     */
+    private getDefaultBaseUrl;
+    /**
+     * Get API title
+     */
+    private getAPITitle;
+    /**
+     * Get API description
+     */
+    private getAPIDescription;
+}
+
+/**
+ * OpenAPICollectionProvider
+ *
+ * Runtime implementation of CollectionProvider for OpenAPI endpoints.
+ * This is the runtime component that actually fetches data.
+ */
+declare class OpenAPICollectionProvider {
+    private baseUrl;
+    private auth?;
+    constructor(baseUrl: string, auth?: {
+        type: string;
+        token?: string;
+        apiKey?: string;
+    } | undefined);
+    /**
+     * Fetch items from an API endpoint
+     */
+    fetchItems(endpoint: string): Promise<unknown[]>;
+    /**
+     * Fetch a single item by slug
+     */
+    fetchItem(endpoint: string, slug: string): Promise<unknown>;
+}
+
+/**
+ * Prebuild plugin types
+ * TODO: Move to @stackwright/types package when created
+ */
+interface PrebuildPluginContext {
+    /** Parsed site configuration from stackwright.yml */
+    siteConfig: Record<string, any>;
+    /** Project root directory */
+    projectRoot: string;
+}
+interface PrebuildPlugin {
+    /** Plugin name */
+    name: string;
+    /** Called before build starts */
+    beforeBuild?(context: PrebuildPluginContext): Promise<void>;
+    /** Called after build completes */
+    afterBuild?(context: PrebuildPluginContext): Promise<void>;
+}
+/**
+ * Prebuild plugin for OpenAPI integration
+ *
+ * Reads OpenAPI configuration from stackwright.yml and generates:
+ * - Zod validation schemas
+ * - TypeScript type definitions
+ * - CollectionProvider implementations
+ * - Typed API client functions
+ *
+ * All generated code is written to src/generated/{integrationName}/
+ *
+ * === Phase 2: Approved-Specs Enforcement ===
+ *
+ * Enterprise customers can enable security enforcement via stackwright.yml:
+ *
+ * ```yaml
+ * prebuild:
+ *   security:
+ *     enabled: true
+ *     allowlist:
+ *       - name: logistics-api
+ *         url: https://api.gov.mil/logistics/v1/openapi.yaml
+ *         sha256: a1b2c3d4e5f6...
+ * ```
+ *
+ * This ensures only approved API specs can generate code.
+ */
+declare class OpenAPIPlugin implements PrebuildPlugin {
+    name: string;
+    beforeBuild(context: PrebuildPluginContext): Promise<void>;
+    /**
+     * Print a security rejection error in a formatted box
+     */
+    private printSecurityRejection;
+    private processIntegration;
+    private generateSchemas;
+    private generateTypes;
+    private generateProvider;
+    private generateClient;
+    private extractComponentName;
+    private getOperationTypeName;
+    private generateOperationId;
+    private getResponseSchemaName;
+    private sanitizeName;
+    private capitalize;
+}
+/**
+ * Factory function to create the plugin instance
+ *
+ * Usage in user's prebuild script:
+ * ```typescript
+ * const { createOpenAPIPlugin } = require('@stackwright-pro/openapi/prebuild');
+ * runPrebuild({ plugins: [createOpenAPIPlugin()] });
+ * ```
+ */
+declare function createOpenAPIPlugin(): PrebuildPlugin;
+
+/**
+ * NOTE: Validates the URL structure and hostname at call time.
+ * Does NOT re-validate after DNS resolution (DNS rebinding).
+ * This is acceptable for build-time prebuild use.
+ * DO NOT reuse this function for runtime server-side request proxying
+ * without adding post-resolution IP validation.
+ */
+/**
+ * Validates that a URL is safe to fetch (SSRF prevention).
+ * Exported for use by external consumers and tests.
+ *
+ * @throws Error if URL targets internal networks or disallowed protocols
+ */
+declare function validateUrlSafe(baseUrl: string): URL;
+/**
+ * Alias for validateUrlSafe — backward compatibility export
+ */
+declare const isUrlSafe: typeof validateUrlSafe;
+/**
+ * Configuration for OpenAPI source adapter
+ */
+interface OpenAPISourceConfig<T = unknown> {
+    /** Base URL of the API */
+    baseUrl: string;
+    /** API endpoint path */
+    endpoint: string;
+    /** HTTP method (default: 'get') */
+    method?: 'get' | 'post' | 'put' | 'patch' | 'delete';
+    /** Optional query parameters */
+    params?: Record<string, string | number | boolean>;
+    /** Optional request body */
+    body?: unknown;
+    /** Optional headers */
+    headers?: Record<string, string>;
+    /** Optional Zod schema for validation */
+    schema?: ZodSchema<T>;
+    /** Authentication config */
+    auth?: {
+        type: 'bearer' | 'apiKey';
+        token?: string;
+        apiKey?: string;
+        headerName?: string;
+    };
+}
+/**
+ * Creates a fetcher function from OpenAPI configuration
+ *
+ * @example
+ * ```typescript
+ * const fetcher = createOpenAPIFetcher({
+ *   baseUrl: 'https://api.example.com',
+ *   endpoint: '/equipment',
+ *   auth: { type: 'bearer', token: process.env.API_TOKEN }
+ * });
+ *
+ * // Use with Pulse
+ * <Pulse fetcher={fetcher} interval={5000} />
+ * ```
+ */
+declare function createOpenAPIFetcher<T = unknown>(config: OpenAPISourceConfig<T>): () => Promise<T>;
+
+/**
+ * Filters endpoints based on include/exclude patterns.
+ *
+ * Supports:
+ * - Exact match: /equipment
+ * - Path prefix (includes subpaths): /equipment matches /equipment and /equipment/123
+ * - Path with params: /equipment/{id}
+ * - Single wildcard: /admin/* matches /admin/users (not /admin itself)
+ * - Double wildcard: /admin/** matches /admin/users and /admin/nested/deep
+ * - Root path: / matches all paths
+ */
+declare class EndpointFilter {
+    private include;
+    private exclude;
+    constructor(filter?: EndpointFilter$1);
+    /**
+     * Check if a path should be included in code generation.
+     *
+     * Logic:
+     * 1. If path matches any exclude pattern → excluded
+     * 2. If path matches any include pattern → included
+     * 3. Otherwise → excluded (default deny)
+     */
+    matches(path: string): boolean;
+    /**
+     * Match path against a pattern.
+     */
+    private matchPattern;
+    /**
+     * Convert a glob-like pattern to a RegExp.
+     *
+     * Pattern semantics:
+     * - `*` = single path segment (no slashes), minimum 1 character
+     * - `**` = multiple path segments (includes slashes), zero or more segments
+     * - `{param}` = single path segment parameter
+     * - Exact match segments are literal strings
+     */
+    private globToRegex;
+}
+
+/**
+ * Validates that OpenAPI specs are on the approved list
+ * and haven't been modified since approval.
+ *
+ * @example
+ * ```typescript
+ * const config: PrebuildSecurityConfig = {
+ *   enabled: true,
+ *   allowlist: [
+ *     {
+ *       name: 'Government Logistics API',
+ *       url: 'https://api.gov.mil/logistics/v1/openapi.yaml',
+ *       sha256: 'a1b2c3d4e5f6...'
+ *     }
+ *   ]
+ * };
+ *
+ * const validator = new ApprovedSpecsValidator(config);
+ * const result = await validator.validate('https://api.gov.mil/logistics/v1/openapi.yaml');
+ *
+ * if (!result.valid) {
+ *   console.error('Security rejection:', result.error);
+ *   process.exit(1);
+ * }
+ * ```
+ */
+declare class ApprovedSpecsValidator {
+    private allowlist;
+    private cache;
+    private skipHashVerification;
+    private readonly ALLOWED_DIRS;
+    private readonly MAX_RESPONSE_SIZE;
+    /**
+     * Create a new ApprovedSpecsValidator
+     *
+     * @param config - Security configuration from stackwright.yml
+     * @param skipHashVerification - Skip hash check (for testing/development)
+     */
+    constructor(config: PrebuildSecurityConfig, skipHashVerification?: boolean);
+    /**
+     * Build list of allowed directories for path traversal prevention.
+     * Defaults to cwd, specs subdir, and .stackwright cache dir.
+     */
+    private buildAllowedDirs;
+    /**
+     * Validate that a file path is within allowed directories (path traversal prevention).
+     * Uses realpathSync to resolve symlinks and prevent symlink traversal attacks.
+     *
+     * @param filePath - File path to validate
+     * @returns true if path is allowed, false otherwise
+     */
+    private isPathAllowed;
+    /**
+     * Check if a URL/path is a path traversal attempt.
+     * This is checked BEFORE the allowlist to prevent bypassing path security.
+     *
+     * @param specUrl - URL or path to check
+     * @returns true if this is a path traversal attempt
+     */
+    private isPathTraversalAttempt;
+    /**
+     * Validate that a hex string is a valid SHA-256 hash (64 hex characters).
+     *
+     * @param hash - String to validate
+     * @returns true if valid SHA-256 hex format
+     */
+    private isValidHex;
+    /**
+     * Validate that a redirect URL is safe (SSRF protection).
+     * Blocks:
+     * - HTTPS → HTTP downgrades
+     * - Private IP ranges (10.x.x.x, 172.16-31.x.x, 192.168.x.x, 127.x.x.x)
+     * - Localhost and loopback addresses
+     * - Cloud metadata endpoints
+     * - IPv6 private/link-local addresses
+     *
+     * @param location - Redirect location URL
+     * @param originalProtocol - Protocol of the original request
+     * @returns true if redirect is safe, false if it should be blocked
+     */
+    private isRedirectSafe;
+    /**
+     * Atomically check if path is allowed and read content if so.
+     * Prevents TOCTOU race conditions by combining existence check,
+     * symlink resolution, path validation, and file read in a single operation.
+     *
+     * @param filePath - File path to check and read
+     * @returns Object with content if successful, or error message
+     */
+    private readAllowedFile;
+    /**
+     * Check if security enforcement is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Get the allowlist count
+     */
+    getAllowlistCount(): number;
+    /**
+     * Validate that a spec is on the approved list and matches expected hash.
+     *
+     * @param specUrl - URL or file path to the spec to validate
+     * @returns ValidationResult indicating if the spec is approved
+     */
+    validate(specUrl: string): Promise<ValidationResult>;
+    /**
+     * Validate multiple specs at once (batch validation).
+     * Fails fast on first error.
+     *
+     * @param specUrls - Array of URLs/paths to validate
+     * @returns Map of URL to ValidationResult
+     */
+    validateAll(specUrls: string[]): Promise<Map<string, ValidationResult>>;
+    /**
+     * Validate all specs and return all results (non-fail-fast).
+     *
+     * @param specUrls - Array of URLs/paths to validate
+     * @returns Map of URL to ValidationResult
+     */
+    validateAllComplete(specUrls: string[]): Promise<Map<string, ValidationResult>>;
+    /**
+     * Get content hash from cache or download.
+     */
+    private getHash;
+    /**
+     * Download content from URL or file.
+     * Includes path traversal and SSRF protection.
+     */
+    private download;
+    /**
+     * Check if two URLs match (handles trailing slashes, case sensitivity, etc.).
+     * Strips credentials and hash to prevent bypass via @ symbol.
+     */
+    private urlsMatch;
+    /**
+     * Format error message for spec not on allowlist
+     */
+    private formatAllowlistError;
+    /**
+     * Format error message for hash mismatch
+     */
+    private formatHashMismatchError;
+    /**
+     * Clear the download cache.
+     * Useful for long-running processes.
+     */
+    clearCache(): void;
+}
+
+export { type ApprovedSpec, ApprovedSpecsValidator, type ClientGenerationOptions, ClientGenerator, type CollectionConfig, CollectionProviderGenerator, EndpointFilter, OpenAPICollectionProvider, type OpenAPICompilationResult, type OpenAPIConfig, type OpenAPIDocument, OpenAPIParser, OpenAPIPlugin, type OpenAPISourceConfig, type ParseOptions, type ParseResult, type PrebuildSecurityConfig, type ProviderGenerationOptions, type SchemaMapping, SchemaResolver, type SiteConfig, type TypeGenerationOptions, TypeGenerator, type ValidationResult, type ZodGenerationOptions, ZodSchemaGenerator, createOpenAPIFetcher, createOpenAPIPlugin, isUrlSafe, validateUrlSafe };