Zero-Trust Request Flow Context

Relevant source files

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

• README.md
• server.ts
• src/lib/auth.server.ts
• src/lib/native-auth.ts
• src/lib/api-keys.ts
• scripts/authz/isabella_scopes_catalog_v2.json
• tests/identity-authority.test.ts

Zero-Trust Request Flow Context establishes a transitively secure environment for every operation within the Isabella Villaseñor AI infrastructure. It ensures that every request is accompanied by verified identity, tenant isolation, and granular authorization metadata that follows the request through its entire lifecycle. This system implements a "fail-closed" philosophy where the absence of valid context leads to immediate rejection of the operation.

The architecture relies on four primary layers of context resolution: correlation tracking, tenant isolation, principal identification, and policy enforcement. These components ensure that no client-supplied identity is trusted blindly and that all administrative actions require hardware-backed assurance levels.

Sources: README.md:95-100, tests/identity-authority.test.ts:14-16

Architecture and Core Components

The request flow context is managed through a multi-layered middleware stack in the Express server. It validates credentials from multiple sources including httpOnly cookies, Authorization headers, and custom API key headers.

Request Lifecycle Flow

The following diagram illustrates how a request progresses through the Zero-Trust validation layers before reaching the core logic.

The system prioritizes secure transports, specifically favoring __Host-isa_session cookies to mitigate XSS risks.
Sources: server.ts:167-190, src/lib/auth.server.ts:85-95, README.md:148-155

Authentication and Principal Resolution

The system resolves an AuthenticatedPrincipal object for every request. This object contains the subject ID (sub), tenant identifier (tenantId), roles, and assigned scopes.

Principal Data Structure

Field	Type	Description
sub	string	Unique identifier for the authenticated subject.
tenantId	string	The specific jurisdiction or organization ID.
roles	IsabellaRole[]	Array of roles (viewer, citizen, operator, admin, system).
scopes	string[]	Specific granular permissions granted to the principal.
kind	"jwt" | "api-key"	The transport mechanism used for authentication.

Sources: src/lib/auth.server.ts:11-20, scripts/authz/isabella_scopes_catalog_v2.json:50-100

Multi-Layered Resolution Logic

1. Cookie Layer: Extracts __Host-isa_session and verifies the Native JWT.
2. Authorization Layer: Validates Bearer tokens against the native or external secrets.
3. API Key Layer: Processes x-api-key headers against the persistent key repository.
4. Dev Fallback: Provides a pre-configured admin context only in non-production environments.

Sources: src/lib/auth.server.ts:85-155, server.ts:167-185

Tenant Isolation and Correlation

Tenant isolation ensures that data from one organization is never accessible by another. The system utilizes constant-time comparison for tenant IDs to prevent timing attacks.

• Native Tenancy: Every principal is strictly bound to a tenantId (e.g., nodo-cero-rdm).
• Correlation Tracking: Requests generate or carry a traceId and correlation-context to ensure auditability across distributed services.
• Fail-Closed Policy: If the tenantId is missing or invalid in the credential, the request is rejected immediately.

Sources: README.md:100-105, src/lib/auth.server.ts:60-65, server.ts:544-550

Policy and Scope Governance

Authorization is governed by a granular scope catalog. Scopes define exactly what actions a principal can perform within their tenant boundary.

Assurance Levels and Risk Gating

Isabella uses different Assurance Levels based on the sensitivity of the operation.

Hardware-backed identity is required for high-risk operations like modifying policies or activating the system kill-switch.
Sources: scripts/authz/isabella_scopes_catalog_v2.json:20-45, server.ts:400-420

Critical Security Rules

• Wildcard Prohibition: The wildcard scope (*) is strictly forbidden for all roles except system.
• Guest Confinement: Guest sessions are minted with low-privilege roles (citizen) and restricted to an allowlist of safe scopes (e.g., chat:read, image:gen).
• Step-Up Authentication: Specific scopes (e.g., billing:checkout, recovery:activate) require step-up authentication regardless of the principal's base role.

Sources: src/lib/auth.server.ts:180-195, src/lib/native-auth.ts:120-135, tests/identity-authority.test.ts:20-30

Implementation Details

Verify Function Snippet

The following logic demonstrates how Isabella validates tokens without trusting client-supplied claims blindly.

// src/lib/auth.server.ts:49-75
export function verifyHs256Jwt(token: string, secret: string): AuthenticatedPrincipal | null {
  const parts = token.split(".");
  if (parts.length !== 3) return null;
  // ... validation of signature using timingSafeEqual ...
  const payload = safeJson<any>(base64UrlDecode(encodedPayload));
  if (!payload?.sub || typeof payload.sub !== "string") return null;
  if (payload.exp && Number(payload.exp) * 1000 <= Date.now()) return null;
  
  const roles = Array.isArray(payload.roles) ? payload.roles : [payload.role || "citizen"];
  return {
    sub: payload.sub,
    tenantId: String(payload.tenantId || payload.tid || "nodo-cero-rdm"),
    roles: roles.filter((r: string) => r in roleRank),
    scopes: Array.isArray(payload.scopes) ? payload.scopes.map(String) : [],
  };
}

Sources: src/lib/auth.server.ts:49-75

Summary

The Zero-Trust Request Flow Context provides a robust security foundation by ensuring that every interaction is authenticated, authorized, and isolated. By enforcing hardware-backed identity for critical actions and strict tenant boundaries for data access, the system maintains high integrity even in complex agéntic orchestrations. The use of a decoupled Policy Decision Point (PDP) and granular scope catalog allows for flexible yet secure governance across the entire Isabella infrastructure.