TypeScript Getting Started

Attesta ships a first-class TypeScript SDK under the @kyberon/attesta package. It provides the same approval pipeline as the Python SDK — risk scoring, escalating challenges, tamper-proof audit trails, and adaptive trust — with idiomatic TypeScript conventions and full generic type safety.

Installation

npm install @kyberon/attesta

If you use a specific integration, install the peer dependency alongside it:

npm install @kyberon/attesta ai

npm install @kyberon/attesta @langchain/core

The @kyberon/attesta package has zero runtime dependencies. Integration modules import peer dependencies lazily, so they are only required if you actually use them.

Basic Usage

Protecting a Function with `gate`

The gate function wraps any async function with the Attesta approval pipeline. When the wrapped function is called, Attesta intercepts the invocation, scores the risk, presents the appropriate challenge, and either allows or blocks execution.

import { gate } from "@kyberon/attesta";

const deleteUser = gate(async (userId: string): Promise<string> => {
  // This only executes if Attesta approves
  return `Deleted user ${userId}`;
});

// Triggers risk assessment + approval prompt
const result = await deleteUser("usr_12345");

Passing Options

Provide a configuration object as the first argument to customize risk scoring, hints, and metadata:

import { gate } from "@kyberon/attesta";

const deployService = gate(
  {
    risk: "high",
    riskHints: { production: true, destructive: false },
    agentId: "deploy-bot",
    environment: "production",
    minReviewSeconds: 10.0,
  },
  async (service: string, version: string): Promise<string> => {
    return `Deployed ${service} v${version}`;
  }
);

Curried Factory

You can also create a pre-configured gate factory and reuse it across multiple functions:

import { gate } from "@kyberon/attesta";

const productionGate = gate({
  environment: "production",
  riskHints: { production: true },
  minReviewSeconds: 5.0,
});

const deploy = productionGate(async (service: string, version: string) => {
  return `Deployed ${service} v${version}`;
});

const rollback = productionGate(async (service: string) => {
  return `Rolled back ${service}`;
});

Using the Attesta Class

For production use, create an Attesta instance that holds shared defaults for risk scoring, rendering, audit logging, and trust. All gates created from the instance inherit these defaults.

import { Attesta, gate } from "@kyberon/attesta";

// Create an Attesta instance with shared defaults
const attesta = new Attesta();

// gate() is a standalone function — pass the attesta instance as an option
const readConfig = gate(async (key: string) => {
  return `Value for ${key}`;
}, { attesta });

const deleteUser = gate(
  async (userId: string) => {
    return `Deleted ${userId}`;
  },
  { attesta, riskHints: { destructive: true, pii: true } }
);

Or configure with custom components:

import { Attesta } from "@kyberon/attesta";

const attesta = new Attesta({
  riskScorer: myCustomScorer,
  renderer: myCustomRenderer,
  auditLogger: myCustomLogger,
  minReviewSeconds: 3.0,
});

Type Definitions

The TypeScript SDK exports all core types for full type safety. Here are the most commonly used types:

import {
  // Core API
  gate,
  Attesta,
  AttestaDenied,

  // Types
  ActionContext,
  ApprovalResult,
  RiskAssessment,
  ChallengeResult,

  // Enums
  RiskLevel,
  Verdict,
  ChallengeType,

  // Protocols (interfaces)
  RiskScorer,
  Renderer,
  AuditLogger,
  ChallengeProtocol,
} from "@kyberon/attesta";

Key Interfaces

Interface	Description
`ActionContext`	Describes a function call under review: name, args, doc, environment, hints
`ApprovalResult`	The outcome of an evaluation: verdict, risk assessment, challenge result, audit ID
`RiskAssessment`	Risk score (0-1), risk level enum, scorer name, and contributing factors
`ChallengeResult`	Whether the challenge was passed, the challenge type, and response time

Generics

The gate function preserves the original function’s type signature using TypeScript generics:

import { gate } from "@kyberon/attesta";

// TypeScript infers the full signature
const add = gate(async (a: number, b: number): Promise<number> => {
  return a + b;
});

// Type-safe: (a: number, b: number) => Promise<number>
const result: number = await add(1, 2);   // OK
const bad: string = await add(1, 2);      // Type error

The generic signature ensures that wrapped functions retain their parameter types, return types, and arity through the gate wrapper.

Handling Denials

When an operator denies an action or fails a challenge, the wrapped function throws an AttestaDenied error. The protected function is never executed.

import { gate, AttestaDenied } from "@kyberon/attesta";

const dropTable = gate(
  { risk: "critical" },
  async (tableName: string) => {
    return `Dropped ${tableName}`;
  }
);

try {
  await dropTable("users");
} catch (error) {
  if (error instanceof AttestaDenied) {
    console.log(`Blocked: ${error.message}`);
    console.log(`Verdict: ${error.result?.verdict}`);
    console.log(`Risk score: ${error.result?.riskAssessment.score}`);
  }
}

Python vs TypeScript at a Glance

Aspect	Python	TypeScript
Package	`pip install attesta`	`npm install @kyberon/attesta`
Gate syntax	`@gate` decorator	`gate(fn)` wrapper
Naming	`snake_case`	`camelCase`
Async	`asyncio` / `await`	Promises / `await`
Config loading	`Attesta.from_config()`	Constructor only (`new Attesta()`)
Protocols	`Protocol` classes (structural)	`interface` (structural)
Custom scorers	Duck typing via `Protocol`	`implements` keyword

For a detailed comparison, see the Python vs TypeScript API page.

Next Steps

Python vs TypeScript API

Detailed side-by-side comparison of both SDKs

@gate Decorator

Full parameter reference for the gate function

Vercel AI SDK

TypeScript-native Vercel AI integration

Protocols

Implement custom scorers, renderers, and loggers

Getting Started

Core Concepts

Configuration

Domain Profiles

Examples

Guides

TypeScript

Resources

TypeScript Getting Started

Installation

Basic Usage

Protecting a Function with `gate`

Passing Options

Curried Factory

Using the Attesta Class

Type Definitions

Key Interfaces

Generics

Handling Denials

Python vs TypeScript at a Glance

Next Steps

Python vs TypeScript API

@gate Decorator

Vercel AI SDK

Protocols

​Installation

​Basic Usage

​Protecting a Function with gate

​Passing Options

​Curried Factory

​Using the Attesta Class

​Type Definitions

​Key Interfaces

​Generics

​Handling Denials

​Python vs TypeScript at a Glance

​Next Steps

Python vs TypeScript API

@gate Decorator

Vercel AI SDK

Protocols

Installation

Basic Usage

Protecting a Function with `gate`

Passing Options

Curried Factory

Using the Attesta Class

Type Definitions

Key Interfaces

Generics

Handling Denials

Python vs TypeScript at a Glance

Next Steps