@code-rag/api-server 0.1.0

package/dist/middleware/auth.js

@@ -0,0 +1,92 @@
+/**
+ * Parse the CODERAG_API_KEYS env var.
+ *
+ * Format: comma-separated keys. Keys suffixed with `:admin` grant admin privileges.
+ * Example: "key1,key2:admin,key3"
+ */
+export function parseApiKeys(envValue) {
+    if (!envValue || envValue.trim() === '') {
+        return [];
+    }
+    return envValue
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0)
+        .map((entry) => {
+        if (entry.endsWith(':admin')) {
+            return { key: entry.slice(0, -6), admin: true };
+        }
+        return { key: entry, admin: false };
+    });
+}
+/**
+ * Create an authentication middleware that validates API keys.
+ *
+ * Accepts keys from:
+ * - `Authorization: Bearer <key>` header
+ * - `X-API-Key: <key>` header
+ *
+ * When no API keys are configured (empty CODERAG_API_KEYS),
+ * authentication is disabled and all requests pass through.
+ */
+export function createAuthMiddleware(apiKeys) {
+    return (req, res, next) => {
+        // If no keys configured, auth is disabled (development mode)
+        if (apiKeys.length === 0) {
+            next();
+            return;
+        }
+        const key = extractApiKey(req);
+        if (!key) {
+            res.status(401).json({
+                error: 'Unauthorized',
+                message: 'Missing API key. Provide via Authorization: Bearer <key> or X-API-Key: <key> header.',
+            });
+            return;
+        }
+        const entry = apiKeys.find((k) => k.key === key);
+        if (!entry) {
+            res.status(401).json({
+                error: 'Unauthorized',
+                message: 'Invalid API key.',
+            });
+            return;
+        }
+        // Attach the validated key entry to the request
+        req.apiKey = entry;
+        next();
+    };
+}
+/**
+ * Middleware that requires admin privileges on the API key.
+ * Must be used after createAuthMiddleware.
+ */
+export function requireAdmin(req, res, next) {
+    const authReq = req;
+    // If no apiKey is set, auth is disabled (development mode) — allow through
+    if (!authReq.apiKey && !res.headersSent) {
+        next();
+        return;
+    }
+    if (!authReq.apiKey?.admin) {
+        res.status(403).json({
+            error: 'Forbidden',
+            message: 'Admin privileges required for this endpoint.',
+        });
+        return;
+    }
+    next();
+}
+function extractApiKey(req) {
+    // Check Authorization: Bearer <key>
+    const authHeader = req.headers['authorization'];
+    if (authHeader && authHeader.startsWith('Bearer ')) {
+        return authHeader.slice(7).trim();
+    }
+    // Check X-API-Key: <key>
+    const apiKeyHeader = req.headers['x-api-key'];
+    if (typeof apiKeyHeader === 'string' && apiKeyHeader.trim().length > 0) {
+        return apiKeyHeader.trim();
+    }
+    return undefined;
+}

package/dist/middleware/auth.js.map

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

package/dist/middleware/rate-limit.d.ts

@@ -0,0 +1,26 @@
+import type { Request, Response, NextFunction } from 'express';
+/**
+ * Configuration for rate limiting.
+ */
+export interface RateLimitConfig {
+    /** Maximum requests per window. Default: 60 */
+    readonly maxRequests: number;
+    /** Window size in milliseconds. Default: 60_000 (1 minute) */
+    readonly windowMs: number;
+}
+/**
+ * Parse rate limit configuration from environment.
+ *
+ * - CODERAG_RATE_LIMIT: requests per minute (default: 60)
+ * - CODERAG_RATE_WINDOW_MS: window in ms (default: 60000)
+ */
+export declare function parseRateLimitConfig(env: Record<string, string | undefined>): RateLimitConfig;
+/**
+ * Create a token-bucket rate limiter middleware.
+ *
+ * Each API key (or IP address for unauthenticated requests) gets its own bucket.
+ * The bucket is refilled at the configured rate.
+ *
+ * When the limit is exceeded, returns 429 with a Retry-After header.
+ */
+export declare function createRateLimitMiddleware(config?: RateLimitConfig): (req: Request, res: Response, next: NextFunction) => void;

package/dist/middleware/rate-limit.js

@@ -0,0 +1,79 @@
+const DEFAULT_CONFIG = {
+    maxRequests: 60,
+    windowMs: 60_000,
+};
+/**
+ * Parse rate limit configuration from environment.
+ *
+ * - CODERAG_RATE_LIMIT: requests per minute (default: 60)
+ * - CODERAG_RATE_WINDOW_MS: window in ms (default: 60000)
+ */
+export function parseRateLimitConfig(env) {
+    const maxRequests = parseInt(env['CODERAG_RATE_LIMIT'] ?? '', 10);
+    const windowMs = parseInt(env['CODERAG_RATE_WINDOW_MS'] ?? '', 10);
+    return {
+        maxRequests: Number.isFinite(maxRequests) && maxRequests > 0 ? maxRequests : DEFAULT_CONFIG.maxRequests,
+        windowMs: Number.isFinite(windowMs) && windowMs > 0 ? windowMs : DEFAULT_CONFIG.windowMs,
+    };
+}
+/**
+ * Create a token-bucket rate limiter middleware.
+ *
+ * Each API key (or IP address for unauthenticated requests) gets its own bucket.
+ * The bucket is refilled at the configured rate.
+ *
+ * When the limit is exceeded, returns 429 with a Retry-After header.
+ */
+export function createRateLimitMiddleware(config = DEFAULT_CONFIG) {
+    const buckets = new Map();
+    return (req, res, next) => {
+        const now = Date.now();
+        const clientKey = getClientKey(req);
+        const bucket = getOrCreateBucket(buckets, clientKey, config, now);
+        // Refill tokens based on elapsed time
+        const elapsed = now - bucket.lastRefill;
+        const tokensToAdd = (elapsed / config.windowMs) * config.maxRequests;
+        bucket.tokens = Math.min(config.maxRequests, bucket.tokens + tokensToAdd);
+        bucket.lastRefill = now;
+        if (bucket.tokens < 1) {
+            const retryAfterMs = ((1 - bucket.tokens) / config.maxRequests) * config.windowMs;
+            const retryAfterSeconds = Math.ceil(retryAfterMs / 1000);
+            res.setHeader('Retry-After', String(retryAfterSeconds));
+            res.setHeader('X-RateLimit-Limit', String(config.maxRequests));
+            res.setHeader('X-RateLimit-Remaining', '0');
+            res.status(429).json({
+                error: 'Too Many Requests',
+                message: `Rate limit exceeded. Try again in ${retryAfterSeconds} second(s).`,
+                retry_after: retryAfterSeconds,
+            });
+            return;
+        }
+        // Consume a token
+        bucket.tokens -= 1;
+        // Set rate limit headers
+        res.setHeader('X-RateLimit-Limit', String(config.maxRequests));
+        res.setHeader('X-RateLimit-Remaining', String(Math.floor(bucket.tokens)));
+        next();
+    };
+}
+function getClientKey(req) {
+    const authReq = req;
+    if (authReq.apiKey) {
+        return `key:${authReq.apiKey.key}`;
+    }
+    // Fall back to IP address
+    const ip = req.ip ?? req.socket.remoteAddress ?? 'unknown';
+    return `ip:${ip}`;
+}
+function getOrCreateBucket(buckets, key, config, now) {
+    const existing = buckets.get(key);
+    if (existing) {
+        return existing;
+    }
+    const bucket = {
+        tokens: config.maxRequests,
+        lastRefill: now,
+    };
+    buckets.set(key, bucket);
+    return bucket;
+}

package/dist/middleware/rate-limit.js.map

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

package/dist/openapi.d.ts

@@ -0,0 +1,14 @@
+/**
+ * OpenAPI 3.0 specification for the CodeRAG Cloud API.
+ */
+export interface OpenAPISpec {
+    readonly openapi: string;
+    readonly info: {
+        readonly title: string;
+        readonly version: string;
+        readonly description: string;
+    };
+    readonly paths: Record<string, unknown>;
+    readonly components: Record<string, unknown>;
+}
+export declare function createOpenAPISpec(): OpenAPISpec;

package/dist/openapi.js

@@ -0,0 +1,363 @@
+export function createOpenAPISpec() {
+    return {
+        openapi: '3.0.3',
+        info: {
+            title: 'CodeRAG Cloud API',
+            version: '0.1.0',
+            description: 'REST API for CodeRAG — an intelligent codebase context engine for AI coding agents. ' +
+                'Provides semantic search, context assembly, and index management over shared code indices.',
+        },
+        paths: {
+            '/api/v1/search': {
+                post: {
+                    summary: 'Search the codebase',
+                    description: 'Search the indexed codebase using hybrid semantic + keyword search. ' +
+                        'Returns matching code chunks with file paths, types, content, and relevance scores.',
+                    operationId: 'searchCode',
+                    tags: ['Search'],
+                    security: [{ apiKeyAuth: [] }, { bearerAuth: [] }],
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    required: ['query'],
+                                    properties: {
+                                        query: {
+                                            type: 'string',
+                                            minLength: 1,
+                                            description: 'Natural language search query',
+                                        },
+                                        language: {
+                                            type: 'string',
+                                            description: 'Filter results by programming language (e.g. "typescript", "python")',
+                                        },
+                                        file_path: {
+                                            type: 'string',
+                                            description: 'Filter results by file path substring',
+                                        },
+                                        chunk_type: {
+                                            type: 'string',
+                                            description: 'Filter by chunk type: function, method, class, module, interface, type_alias, config_block, import_block',
+                                        },
+                                        top_k: {
+                                            type: 'integer',
+                                            minimum: 1,
+                                            maximum: 100,
+                                            default: 10,
+                                            description: 'Maximum number of results to return',
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '200': {
+                            description: 'Search results',
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        type: 'object',
+                                        properties: {
+                                            results: {
+                                                type: 'array',
+                                                items: { $ref: '#/components/schemas/SearchResult' },
+                                            },
+                                            total: { type: 'integer' },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                        '400': { $ref: '#/components/responses/ValidationError' },
+                        '401': { $ref: '#/components/responses/Unauthorized' },
+                        '429': { $ref: '#/components/responses/RateLimited' },
+                        '503': { $ref: '#/components/responses/ServiceUnavailable' },
+                    },
+                },
+            },
+            '/api/v1/context': {
+                post: {
+                    summary: 'Get file context',
+                    description: 'Assemble rich context for a specific file, including primary code chunks, ' +
+                        'related chunks from the dependency graph, and a dependency graph excerpt. Output is token-budgeted.',
+                    operationId: 'getContext',
+                    tags: ['Context'],
+                    security: [{ apiKeyAuth: [] }, { bearerAuth: [] }],
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    required: ['file_path'],
+                                    properties: {
+                                        file_path: {
+                                            type: 'string',
+                                            minLength: 1,
+                                            description: 'Target file path to get context for',
+                                        },
+                                        include_tests: {
+                                            type: 'boolean',
+                                            default: true,
+                                            description: 'Include test files in context',
+                                        },
+                                        include_interfaces: {
+                                            type: 'boolean',
+                                            default: true,
+                                            description: 'Include interface/type chunks in context',
+                                        },
+                                        max_tokens: {
+                                            type: 'integer',
+                                            minimum: 1,
+                                            maximum: 128000,
+                                            default: 8000,
+                                            description: 'Maximum token budget for assembled context',
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '200': {
+                            description: 'Assembled context',
+                            content: {
+                                'application/json': {
+                                    schema: { $ref: '#/components/schemas/ContextResponse' },
+                                },
+                            },
+                        },
+                        '400': { $ref: '#/components/responses/ValidationError' },
+                        '401': { $ref: '#/components/responses/Unauthorized' },
+                        '429': { $ref: '#/components/responses/RateLimited' },
+                        '503': { $ref: '#/components/responses/ServiceUnavailable' },
+                    },
+                },
+            },
+            '/api/v1/status': {
+                get: {
+                    summary: 'Get index status',
+                    description: 'Get the current status of the CodeRAG index, including total chunks, model info, and health.',
+                    operationId: 'getStatus',
+                    tags: ['Status'],
+                    security: [{ apiKeyAuth: [] }, { bearerAuth: [] }],
+                    responses: {
+                        '200': {
+                            description: 'Index status',
+                            content: {
+                                'application/json': {
+                                    schema: { $ref: '#/components/schemas/StatusResponse' },
+                                },
+                            },
+                        },
+                        '401': { $ref: '#/components/responses/Unauthorized' },
+                        '429': { $ref: '#/components/responses/RateLimited' },
+                    },
+                },
+            },
+            '/api/v1/index': {
+                post: {
+                    summary: 'Trigger re-indexing (admin)',
+                    description: 'Trigger re-indexing of the codebase. Requires admin API key.',
+                    operationId: 'triggerIndex',
+                    tags: ['Admin'],
+                    security: [{ apiKeyAuth: [] }, { bearerAuth: [] }],
+                    requestBody: {
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    properties: {
+                                        root_dir: {
+                                            type: 'string',
+                                            description: 'Root directory to index (uses server default if omitted)',
+                                        },
+                                        force: {
+                                            type: 'boolean',
+                                            default: false,
+                                            description: 'Force full re-index even if files are unchanged',
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '200': {
+                            description: 'Indexing result',
+                            content: {
+                                'application/json': {
+                                    schema: { $ref: '#/components/schemas/IndexResponse' },
+                                },
+                            },
+                        },
+                        '400': { $ref: '#/components/responses/ValidationError' },
+                        '401': { $ref: '#/components/responses/Unauthorized' },
+                        '403': { $ref: '#/components/responses/Forbidden' },
+                        '429': { $ref: '#/components/responses/RateLimited' },
+                        '503': { $ref: '#/components/responses/ServiceUnavailable' },
+                    },
+                },
+            },
+            '/health': {
+                get: {
+                    summary: 'Health check',
+                    description: 'Simple health check endpoint. No authentication required.',
+                    operationId: 'healthCheck',
+                    tags: ['Health'],
+                    responses: {
+                        '200': {
+                            description: 'Server is healthy',
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        type: 'object',
+                                        properties: {
+                                            status: { type: 'string', enum: ['ok'] },
+                                            timestamp: { type: 'string', format: 'date-time' },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+        components: {
+            securitySchemes: {
+                bearerAuth: {
+                    type: 'http',
+                    scheme: 'bearer',
+                    description: 'API key passed as Bearer token in the Authorization header',
+                },
+                apiKeyAuth: {
+                    type: 'apiKey',
+                    in: 'header',
+                    name: 'X-API-Key',
+                    description: 'API key passed in the X-API-Key header',
+                },
+            },
+            schemas: {
+                SearchResult: {
+                    type: 'object',
+                    properties: {
+                        file_path: { type: 'string' },
+                        chunk_type: { type: 'string' },
+                        name: { type: 'string' },
+                        content: { type: 'string' },
+                        nl_summary: { type: 'string' },
+                        score: { type: 'number' },
+                    },
+                },
+                ContextResponse: {
+                    type: 'object',
+                    properties: {
+                        context: { type: 'string' },
+                        token_count: { type: 'integer' },
+                        truncated: { type: 'boolean' },
+                        primary_chunks: { type: 'integer' },
+                        related_chunks: { type: 'integer' },
+                    },
+                },
+                StatusResponse: {
+                    type: 'object',
+                    properties: {
+                        total_chunks: { type: 'integer' },
+                        last_indexed: { type: 'string', nullable: true },
+                        model: { type: 'string' },
+                        languages: {
+                            oneOf: [
+                                { type: 'array', items: { type: 'string' } },
+                                { type: 'string', enum: ['auto'] },
+                            ],
+                        },
+                        health: {
+                            type: 'string',
+                            enum: ['ok', 'degraded', 'not_initialized'],
+                        },
+                    },
+                },
+                IndexResponse: {
+                    type: 'object',
+                    properties: {
+                        status: { type: 'string', enum: ['completed'] },
+                        indexed_files: { type: 'integer' },
+                        duration_ms: { type: 'integer' },
+                    },
+                },
+                ErrorResponse: {
+                    type: 'object',
+                    properties: {
+                        error: { type: 'string' },
+                        message: { type: 'string' },
+                    },
+                },
+            },
+            responses: {
+                ValidationError: {
+                    description: 'Request validation error',
+                    content: {
+                        'application/json': {
+                            schema: {
+                                type: 'object',
+                                properties: {
+                                    error: { type: 'string' },
+                                    details: { type: 'array', items: { type: 'object' } },
+                                },
+                            },
+                        },
+                    },
+                },
+                Unauthorized: {
+                    description: 'Missing or invalid API key',
+                    content: {
+                        'application/json': {
+                            schema: { $ref: '#/components/schemas/ErrorResponse' },
+                        },
+                    },
+                },
+                Forbidden: {
+                    description: 'Insufficient permissions (admin required)',
+                    content: {
+                        'application/json': {
+                            schema: { $ref: '#/components/schemas/ErrorResponse' },
+                        },
+                    },
+                },
+                RateLimited: {
+                    description: 'Rate limit exceeded',
+                    headers: {
+                        'Retry-After': {
+                            description: 'Seconds until the rate limit resets',
+                            schema: { type: 'integer' },
+                        },
+                    },
+                    content: {
+                        'application/json': {
+                            schema: {
+                                type: 'object',
+                                properties: {
+                                    error: { type: 'string' },
+                                    message: { type: 'string' },
+                                    retry_after: { type: 'integer' },
+                                },
+                            },
+                        },
+                    },
+                },
+                ServiceUnavailable: {
+                    description: 'Service not initialized',
+                    content: {
+                        'application/json': {
+                            schema: { $ref: '#/components/schemas/ErrorResponse' },
+                        },
+                    },
+                },
+            },
+        },
+    };
+}

package/dist/openapi.js.map

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

package/dist/routes/context.d.ts

@@ -0,0 +1,15 @@
+import { Router } from 'express';
+import { z } from 'zod';
+import { type HybridSearch, type ContextExpander } from '@code-rag/core';
+export declare const contextRequestSchema: z.ZodObject<{
+    file_path: z.ZodString;
+    include_tests: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    include_interfaces: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    max_tokens: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+export type ContextRequest = z.infer<typeof contextRequestSchema>;
+export interface ContextRouteDeps {
+    readonly hybridSearch: HybridSearch | null;
+    readonly contextExpander: ContextExpander | null;
+}
+export declare function createContextRouter(deps: ContextRouteDeps): Router;