Serverless Express Gateway

Relevant source files

The following files were used as context for generating this wiki page:

• server.ts
• api/[...path].ts
• vercel.json
• README.md
• AGENTS.md
• src/lib/auth.server.ts
• src/lib/api-contracts.ts

The Serverless Express Gateway serves as the primary entry point for all API requests within the Isabella Villaseñor AI infrastructure. It operates as a hybrid architecture, utilizing a standard Express application defined in server.ts that is dynamically served through a Vercel serverless function. This setup ensures that the same routing logic, middleware, and security protocols apply across development and production environments.

The gateway manages core functions including request routing, authentication via JWT and API keys, rate limiting, and interaction with specialized cognitive modules like ISA, SOPHIA, and ARGUS. It enforces a Zero-Trust security model, requiring explicit scopes and roles for all governed operations, such as quantum execution or agent leasing.

Sources: README.md:144-156, AGENTS.md:10-14, server.ts:133-145

Architecture and Deployment

The architecture bridges a traditional monolithic Express server with a modern serverless deployment model. In development, the system runs as a standard Node.js process using tsx. In production, Vercel hosts the application, routing all /api/* traffic to a single catch-all serverless function.

The diagram shows the request flow from the user through the Vercel infrastructure into the underlying Express application.
Sources: vercel.json:11-15, api/[...path].ts:1-25, server.ts:133-145

Serverless Routing Configuration

The vercel.json file defines the bridge between the deployment environment and the Express application. It uses a rewrite rule to capture all paths under /api/ and forward them to the [...path].ts function handler.

Setting	Value	Description
Version	2	Vercel platform version.
Function Path	api/[...path].ts	The entry point for serverless execution.
Max Duration	55 seconds	Maximum execution time for API requests.
API Rewrite	/api/(.*)	Matches all API sub-paths for the handler.
Frontend Rewrite	/((?!api/).*)	Routes non-API traffic to index.html (SPA).

Sources: vercel.json:1-17

Request Lifecycle and Security

The gateway implements a multi-layered security pipeline for every incoming request. It enforces strict HTTP headers and specialized guards before reaching domain logic.

Security Pipeline Sequence

Every request must pass through a defined sequence of middleware to ensure integrity and authorization.

This sequence illustrates the "deny-by-default" approach where requests are validated for security and identity before domain execution.
Sources: server.ts:120-132, src/lib/auth.server.ts:98-150

Integrated Security Guards

• Strict Headers: The server disables x-powered-by and sets X-Content-Type-Options: nosniff, X-Frame-Options: DENY, and strict Referrer-Policy.
• CSRF Protection: Issues and validates CSRF tokens via /api/v1/security/csrf-token.
• Injection Guard: Employs a promptInjectionGuard to filter malicious patterns in request payloads.
• Fail-Closed Authorization: If the external Policy Decision Point (PDP) sidecar is unconfigured, the system fails closed for sensitive operations.

Sources: server.ts:120-132, README.md:162-166

Authentication Mechanisms

The gateway supports four distinct layers for identity resolution, prioritized to favor security and resilience.

1. __Host-isa_session Cookie: A preferred httpOnly, Secure, SameSite=Lax cookie that is immune to XSS attacks.
2. Native JWT: Validates JSON Web Tokens in the Authorization: Bearer header.
3. API Keys: Validates keys provided in the x-api-key header against a SQLite repository.
4. Development Fallback: In non-production environments, provides an administrative "dev-local" principal to facilitate testing.

Sources: src/lib/auth.server.ts:98-160, server.ts:176-180

Authorization Scopes

Operations are governed by granular scopes. A "system" role is required to use the wildcard * scope; otherwise, exact matches are mandatory.

Scope	Description
keys:manage	Allows creation, rotation, and revocation of API keys.
agent:lease	Authorizes the leasing of autonomous Isabella agent sessions.
quantum:execute	Grants access to the PennyLane quantum execution mesh.
audit:read	Allows reading the cryptographic audit trail.
memory:write	Authorizes registering new items in the hierarchical memory.

Sources: src/lib/auth.server.ts:182-200, src/lib/api-contracts.ts:60-95

Cognitive and Specialized Endpoints

The gateway routes traffic to specialized modules within the Isabella ecosystem. These modules represent the "12 Heads" of the architecture.

Perception and Inference

The POST /api/v1/isabella endpoint handles governed cognitive inputs. The request is normalized into an IsabellaPerception object before processing.

// src/lib/api-contracts.ts:24-32
export const PerceptionInputSchema = z.object({
  sessionId: z.string().max(256).optional(),
  territoryId: z.string().max(128).optional(),
  inputType: z.enum(["chat", "event", "signal", "api", "ui"]).optional(),
  payload: z.record(z.string(), z.unknown()).optional(),
  text: z.string().max(50000).optional(),
  metadata: z.record(z.string(), z.unknown()).optional(),
  timestamp: z.string().max(64).optional(),
});

Sources: src/lib/api-contracts.ts:24-32, server.ts:470-498

Quantum Mesh Execution

The gateway facilitates hybrid quantum-classical execution through the POST /api/v1/quantum/execute endpoint. This process involves a 13-step governed pipeline, including policy evaluation and circuit execution via providers like PennyLane.
Sources: server.ts:740-770, src/lib/api-contracts.ts:85-95

Resilience and Self-Healing

The gateway is integrated with an Automation Mesh that monitors the health of all 24 core modules. It provides human-friendly interfaces to diagnose and repair system failures.

• Diagnostic Endpoints: GET /api/v1/automation/status and GET /api/v1/automation/health provide real-time snapshots of system integrity.
• Repair Chains: When a failure is detected, the system generates a RepairChain that can be executed step-by-step via POST /api/v1/automation/repair/:chainId/next.
• Kill-Switch: Administrators can activate a global or component-specific kill-switch to halt operations during critical incidents.

Sources: server.ts:880-920, src/lib/automation/human-interface.ts:208-250

The Serverless Express Gateway ensures that Isabella Villaseñor AI remains a territorial, governed, and secure infrastructure by centralizing all policy enforcement and routing into a single, auditable entry point.