TypeScript SDK

The IDProva TypeScript SDK (@idprova/core) provides native Rust performance through napi-rs bindings. All cryptographic operations run in compiled Rust — TypeScript gets a fully typed API with JSDoc documentation.

Installation

npm install @idprova/core

Requirements: Node.js 18+. Pre-built native binaries for Linux, macOS, and Windows.

Quick Start

1. Create an agent identity

   import { AgentIdentity } from '@idprova/core';
   
   const identity = AgentIdentity.create('my-agent', 'example.com');
   console.log(identity.did); // did:idprova:example.com:my-agent

2. Issue a delegation token

   const dat = identity.issueDat(
     'did:idprova:example.com:sub-agent',
     ['mcp:tool:read', 'mcp:resource:docs:write'],
     3600, // 1 hour
   );
   console.log(dat.toCompact()); // JWS compact serialization

3. Verify the token

   const valid = dat.verifySignature(identity.publicKeyBytes);
   dat.validateTiming(); // throws if expired
   console.log(`Scopes: ${dat.scope}`);

Core Classes

AgentIdentity

High-level convenience class — the fastest way to get started.

import { AgentIdentity } from '@idprova/core';

// Create with auto-generated Ed25519 keypair
const identity = AgentIdentity.create(
  'my-agent',
  'example.com',                             // optional, default: "local.dev"
  'did:idprova:example.com:alice',           // optional controller
);

// Access components
const aid = identity.aid();          // AID document
const keypair = identity.keypair();  // Ed25519 KeyPair
const did = identity.did;            // "did:idprova:example.com:my-agent"

// Issue delegation tokens
const dat = identity.issueDat(
  'did:idprova:example.com:sub-agent',
  ['mcp:tool:*:read'],
  3600,
);

KeyPair

Ed25519 key pair for signing and verification. Private keys are held in Rust memory and never exposed to JavaScript.

import { KeyPair } from '@idprova/core';

// Generate a new keypair
const kp = KeyPair.generate();

// Sign and verify
const sig = kp.sign(Buffer.from('hello world'));
const valid = kp.verify(Buffer.from('hello world'), sig); // true

// Access public key
console.log(kp.publicKeyMultibase); // z6Mk... (base58btc)
console.log(kp.publicKeyBytes.length); // 32

// Restore from saved secret (32 bytes)
const kp2 = KeyPair.fromSecretBytes(secretBuffer);

AID & AIDBuilder

Create W3C DID Documents with agent metadata.

import { AidBuilder, Aid, KeyPair } from '@idprova/core';

const kp = KeyPair.generate();

const builder = new AidBuilder();
builder.setId('did:idprova:example.com:my-agent');
builder.setController('did:idprova:example.com:alice');
builder.setName('My Agent');
builder.setDescription('A research assistant agent');
builder.setModel('anthropic/claude-sonnet-4-5');
builder.setRuntime('node/22');
builder.setTrustLevel('L0');
builder.addEd25519Key(kp);

const aid = builder.build();

// Serialize / deserialize
const json = aid.toJson();
const aid2 = Aid.fromJson(json);
aid2.validate(); // throws on invalid structure

DAT (Delegation Attestation Token)

Signed, scoped, time-bounded permission tokens.

import { Dat, KeyPair } from '@idprova/core';

const issuerKp = KeyPair.generate();

const dat = Dat.issue(
  'did:idprova:example.com:alice',           // issuer
  'did:idprova:example.com:my-agent',        // subject
  ['mcp:tool:filesystem:read', 'mcp:tool:filesystem:write'], // scopes
  86400,                                      // 24 hours
  issuerKp,                                   // signing key
  1000,                                       // maxActions (optional)
  true,                                       // requireReceipt (optional)
);

// Serialize to JWS compact format
const compact = dat.toCompact();

// Parse and verify
const dat2 = Dat.fromCompact(compact);
dat2.verifySignature(issuerKp.publicKeyBytes);
dat2.validateTiming(); // throws if expired

// Inspect claims
console.log(dat2.issuer);    // did:idprova:example.com:alice
console.log(dat2.subject);   // did:idprova:example.com:my-agent
console.log(dat2.scope);     // ["mcp:tool:filesystem:read", ...]
console.log(dat2.jti);       // unique token ID
console.log(dat2.isExpired); // false
console.log(dat2.expiresAt); // Unix timestamp

Scope

Permission scope validation with wildcard support.

import { Scope } from '@idprova/core';

const parent = new Scope('mcp:tool:filesystem:*');
const child = new Scope('mcp:tool:filesystem:read');

console.log(parent.covers(child));  // true — wildcard matches
console.log(child.covers(parent));  // false — can't escalate

TrustLevel

Trust level comparison and validation.

import { TrustLevel } from '@idprova/core';

const l1 = new TrustLevel('L1');
const l2 = new TrustLevel('L2');

console.log(l2.meetsMinimum(l1));  // true — L2 >= L1
console.log(l1.meetsMinimum(l2));  // false — L1 < L2
console.log(l1.description);       // Human-readable description

ReceiptLog

Append-only, hash-chained audit log.

import { ReceiptLog } from '@idprova/core';

const log = new ReceiptLog();
console.log(log.lastHash);      // "genesis"
console.log(log.nextSequence);  // 0
console.log(log.length);        // 0

// Verify chain integrity
log.verifyIntegrity(); // throws if tampered

// Serialize
const json = log.toJson();

Planned Packages

The TypeScript SDK is structured as a monorepo with three packages:

Package	Status	Description
@idprova/core	Available	Native Rust bindings — crypto, AID, DAT, receipts
@idprova/sdk	Coming soon	High-level wrapper with convenience helpers
@idprova/mcp	Coming soon	MCP authentication middleware for servers and clients

Security Notes

• Private keys never leave Rust memory — JavaScript only holds opaque references
• Dat.fromCompact() rejects tokens with alg: "none" (SEC-3 algorithm confusion)
• All cryptographic operations use audited ed25519-dalek via Rust/napi-rs
• Buffer inputs for keys and signatures prevent string encoding issues

Next Steps

• Quick Start — End-to-end walkthrough with CLI
• MCP Authentication — Integrate IDProva with MCP servers
• Concepts: Delegation — Understand scope grammar and chains