Externalized Authorization (PDP)
Relevant source files
The following files were used as context for generating this wiki page:
Externalized Authorization in Isabella Villaseñor AI utilizes a Policy Decision Point (PDP) sidecar to manage access control decisions independently from the main application logic. This system implements a "fail-closed" mechanism, ensuring that if the authorization runtime is unavailable or misconfigured, the system denies access by default. The PDP handles complex Attribute-Based Access Control (ABAC) and Role-Based Access Control (RBAC) logic by intersecting identity, tenant, scopes, roles, and session assurance levels.
Sources: README.md:120-128, README.md:167-172, scripts/authz/isabella_scopes_catalog_v2.json:7-11
System Architecture
The authorization architecture consists of a TypeScript client within the main Express server and a Python-based runtime sidecar. The Express server forwards authorization requests to the PDP sidecar via the authorizeWithPdp function. The PDP evaluates these requests against a centralized scopes catalog and return an ALLOW or DENY decision.
High-Level Authorization Flow
The following diagram illustrates the request flow from the User Interface through the Gateway to the PDP Sidecar.
Core Components
PDP Sidecar (authz-runtime)
The authz-runtime is a Python service that operates as the source of truth for authorization decisions. It uses a catalog-driven model to define permissions. It specifically validates "assurance levels" (e.g., local, mtls, hardware-backed) and enforces that administrative or high-risk operations require elevated security, such as hardware-backed identity or dual control.
Sources: scripts/authz/isabella_scopes_catalog_v2.json:23-36, README.md:167-172
Scopes Catalog
The system uses a JSON-based catalog (isabella-scopes-v2.0.0) to define the relationship between roles, scopes, and risks. The policy model is "default-deny", meaning access must be explicitly granted.
| Role | Rank | Description |
|---|---|---|
| citizen | 1 | End user. Read access to own tenant data. |
| agent | 2 | Automated agent with scoped write access. |
| operator | 3 | System operator. Manages tools and quantum jobs. |
| admin | 4 | Administrative access. Cannot manage secrets. |
| governance_admin | 5 | Policy authority. Requires hardware step-up. |
| system | 6 | Automated system. May use wildcard scope. |
Sources: scripts/authz/isabella_scopes_catalog_v2.json:37-44
Security Implementation
Fail-Closed Logic
The TypeScript client implements a strict timeout and fallback mechanism. If the ISABELLA_AUTHZ_RUNTIME_URL environment variable is not configured, or if the PDP service times out (default 1500ms), the system returns a DENY decision to protect the resource.
// Example of fail-closed implementation in the PDP Client
export async function authorizeWithPdp(req: PdpRequest, timeoutMs = 1500): Promise<PdpDecision> {
const runtimeUrl = process.env.ISABELLA_AUTHZ_RUNTIME_URL;
if (!runtimeUrl) {
return { status: "DENY", reason: "PDP_NOT_CONFIGURED" };
}
// ... fetch logic with AbortSignal.timeout(timeoutMs)
}
Sources: src/lib/authz-runtime/client.ts:47-65, server.ts:241-252
Assurance Levels and Step-Up
Certain scopes require higher "Assurance Levels" to be executed. The PDP evaluates if the principal's session meets the requirement for the requested scope.
- Local: Standard JWT over HTTPS (Low risk).
- mTLS: Mutual TLS with client certificate (Medium risk).
- Hardware-Backed: WebAuthn, HSM, or TEE attestation (Critical operations).
Sources: scripts/authz/isabella_scopes_catalog_v2.json:23-36, scripts/authz/isabella_scopes_catalog_v2.json:115-125
Scope Gating and Wildcards
The system strictly controls scope minting. Wildcard scopes (*) are forbidden for all roles except the system role. Guest sessions are limited to an allowlist of low-privilege scopes (e.g., chat:read, chat:write) and are stripped of administrative scopes like keys:manage during session minting.
Sources: tests/auth-hardening.test.ts:33-40, tests/auth-hardening.test.ts:58-62, server.ts:275-285
Critical Protected Scopes
The following table summarizes high-risk scopes managed by the PDP.
| Scope | Minimum Role | Risk | Requirement |
|---|---|---|---|
quantum:execute | operator | medium | mTLS |
tools:admin | admin | critical | Hardware Step-Up |
kill-switch:activate | system | critical | Hardware + Dual Control |
admin:policy | governance_admin | critical | Hardware + Dual Control |
admin:secrets | governance_admin | critical | HSM Failover Monitor |
Sources: scripts/authz/isabella_scopes_catalog_v2.json:96-106, scripts/authz/isabella_scopes_catalog_v2.json:375-395, scripts/authz/isabella_scopes_catalog_v2.json:406-415
Conclusion
The Externalized Authorization (PDP) system provides a robust, decoupled security layer for Isabella Villaseñor AI. By separating policy evaluation from execution, the system enforces fine-grained access control, prevents scope elevation attacks, and ensures that critical operations like quantum execution or policy changes meet stringent hardware-backed assurance requirements. The fail-closed design serves as a final safeguard against infrastructure failures.