AI-STS

Framework-agnostic capability authorization for AI tool execution

Architecture | Quick Start | Security | Development

Overview

AI-STS is a TypeScript authorization runtime for AI tool execution. It treats model-generated tool calls as untrusted input and enforces capability-based execution boundaries.

Core invariant:

• No protected tool executes unless a valid capability token is verified for exact tool and resource scope.

Why AI-STS

AI agent systems often run with broad credentials and static permissions. That creates overreach and weak delegation boundaries. AI-STS gives you deterministic, runtime authorization and cryptographic proof of delegated scope at the final execution boundary.

What It Provides

• Provider payload normalization to a shared ToolCall shape.
• Deterministic allow/deny policy evaluation with deny-by-default semantics.
• HS256-signed short-lived capability tokens.
• Mandatory execution boundary guard for protected tool calls.
• Structured audit logging for authorization and verification decisions.
• Strict runtime validation and deterministic error classes.

Architecture At A Glance

1. Provider payload is normalized into ToolCall.
2. evaluateToolCall(...) validates input and evaluates policy.
3. On allow, runtime mints a short-lived capability token.
4. Guard verifies token signature, expiry, tool, and resource.
5. Protected tool executes only after successful verification.

See detailed design in architecture.md.

Installation

npm install

Quick Start

import {
  evaluateToolCall,
  initializeAiSts,
  verifyCapability
} from "ai-sts";

initializeAiSts({
  toolRegistry: {
    tools: {
      "crm.update": { resource_type: "deal" }
    }
  },
  roleRegistry: {
    roles: {
      sales_agent: { allowed_actions: ["crm.update"] }
    }
  },
  policy: {
    allow: [
      {
        when: {
          agent_role: "sales_agent",
          user_role: "sales_rep",
          action: "crm.update"
        }
      }
    ]
  },
  signingSecret: process.env.AI_STS_SIGNING_SECRET
});

const capability = await evaluateToolCall(
  {
    tool: "crm.update",
    action: "crm.update",
    resource: "deal:123",
    arguments: { status: "closed_won" }
  },
  {
    userId: "user-1",
    userRole: "sales_rep"
  },
  {
    agentId: "agent-1",
    agentRole: "sales_agent"
  }
);

verifyCapability(capability.token, "crm.update", "deal:123");

Policy and Resource Semantics

1. Authorization is explicit allow only.
2. No matching allow rule means deny.
3. Tool actions map to resource_type in the tool registry.
4. Runtime enforces resource format as <resource_type>:<id>.
5. Policy rules may optionally pin exact resources using when.resource.

Example policy with exact resource pinning:

allow:
  - when:
      agent_role: sales_agent
      user_role: sales_rep
      action: crm.read
      resource: deal:123

Public API

Core interfaces:

export interface ToolCall {
  tool: string;
  action: string;
  resource: string;
  arguments: Record<string, unknown>;
}

export interface UserContext {
  userId: string;
  userRole: string;
}

export interface AgentContext {
  agentId: string;
  agentRole: string;
}

export interface CapabilityToken {
  token: string;
  expiresAt: number;
}

Core functions:

export async function evaluateToolCall(
  toolCall: ToolCall,
  user: UserContext,
  agent: AgentContext
): Promise<CapabilityToken>;

export function verifyCapability(
  token: string,
  expectedTool: string,
  expectedResource: string
): void;

Error Taxonomy

• AuthorizationError
• InvalidSignatureError
• ExpiredTokenError
• ScopeMismatchError
• MalformedTokenError
• ConfigurationError

Audit Logging

AI-STS emits structured events for:

• Authorization allow/deny decisions.
• Verification allow/deny decisions.

Events include user, agent, action/tool, resource, decision, timestamp, and jti when available.

Demo

Run the end-to-end CRM flow:

npm run demo

Demo config files are in examples/config/.

Development

npm run lint
npm run typecheck
npm test
npm run demo

CI runs lint, typecheck, and tests on push/PR via .github/workflows/ci.yml.

Security Behavior

• Deny by default.
• Runtime validation on all public boundaries.
• Short-lived capability tokens (default TTL: 120 seconds).
• Exact tool and resource verification at execution boundary.
• Fail-fast startup on invalid or inconsistent config.

Non-Goals

• Prompt injection detection
• Probabilistic risk scoring
• Hosted policy UI/dashboard
• OAuth/IAM replacement
• Token revocation service
• Multi-provider adapter breadth beyond OpenAI

Known Limits

• OpenAI adapter only.
• No wildcard permissions.
• Single shared signing secret.
• No built-in key rotation service.
• No hosted control plane.

Repository Layout

src/                  # core runtime, policy, token, adapter, guard
examples/             # runnable CRM demo and YAML config
tests/                # unit and integration suites
.prodman/             # roadmap, epics, specs, issues
.github/workflows/    # CI pipeline