@stackwright-pro/openapi 0.1.0 → 0.1.1

package/dist/index.d.mts

@@ -1,10 +1,65 @@
 import { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
-import { z } from 'zod';
+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
  */
@@ -13,6 +68,8 @@ interface OpenAPIConfig {
     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';
@@ -28,6 +85,8 @@ interface OpenAPIConfig {
         /** Optional filters */
         filters?: Record<string, unknown>;
     }>;
+    /** Endpoint filter - only generate code for matching endpoints */
+    endpoints?: EndpointFilter$1;
 }
 /**
  * Result of OpenAPI compilation
@@ -141,6 +200,8 @@ interface ZodGenerationOptions {
     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
@@ -263,6 +324,8 @@ interface ProviderGenerationOptions {
         type: 'bearer' | 'apiKey';
         headerName?: string;
     };
+    /** If true, emit only the class code without import statements */
+    bare?: boolean;
 }
 /**
  * Generates CollectionProvider implementations from OpenAPI specs
@@ -359,6 +422,7 @@ declare class ClientGenerator {
     private resolver;
     private schemaMapping?;
     private requiredSchemas;
+    private generatedRequestSchemas;
     constructor(document: OpenAPIDocument, schemaMapping?: SchemaMapping);
     /**
      * Generate typed API client code from OpenAPI document
@@ -510,6 +574,19 @@ declare class ClientGenerator {
      * 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
      */
@@ -604,10 +681,30 @@ interface PrebuildPlugin {
  * - 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;
@@ -631,4 +728,236 @@ declare class OpenAPIPlugin implements PrebuildPlugin {
  */
 declare function createOpenAPIPlugin(): PrebuildPlugin;
 
-export { type ClientGenerationOptions, ClientGenerator, type CollectionConfig, CollectionProviderGenerator, OpenAPICollectionProvider, type OpenAPICompilationResult, type OpenAPIConfig, type OpenAPIDocument, OpenAPIParser, OpenAPIPlugin, type ParseOptions, type ParseResult, type ProviderGenerationOptions, type SchemaMapping, SchemaResolver, type TypeGenerationOptions, TypeGenerator, type ZodGenerationOptions, ZodSchemaGenerator, createOpenAPIPlugin };
+/**
+ * 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 };