Beltic logo
SDK Guide

TypeScript SDK

Validate, sign, verify, and build trust chains in JavaScript runtimes

The @belticlabs/kya package provides Beltic credential utilities for Node 18+ and modern runtimes. It mirrors the CLI capabilities with a developer-friendly API.

Install

npm install @belticlabs/kya

Quick start

import {
  validateDeveloperCredential,
  validateAgentCredential,
  decodeToken,
  verifyHttpSignature,
  generateKeyDirectory,
} from '@belticlabs/kya';

// Validate a developer credential
const devResult = validateDeveloperCredential(credentialData);
if (!devResult.valid) {
  console.error('Validation errors:', devResult.errors);
}

// Validate an agent credential
const agentResult = validateAgentCredential(agentData);
if (agentResult.valid) {
  console.log('Agent:', agentResult.data.agentName);
}

API highlights

Validation

  • validateDeveloperCredential(input) and validateAgentCredential(input) return { valid, data, errors, warnings }.
  • Validates against the official FACT v1 JSON schemas.

HTTP Signature Verification

  • verifyHttpSignature(request, options) verifies RFC 9421 HTTP Message Signatures.
  • fetchKeyDirectory(url) fetches and parses a key directory from a URL.
  • fetchAgentCredential(signatureAgentUrl) fetches credential from key directory.

Key Directory

  • generateKeyDirectory(options) generates a key directory JSON for Web Bot Auth.
  • signDirectoryResponse(directory, options) signs the directory response.

Token Operations

  • decodeToken(jwt) decodes JWS/JWT tokens without verification.
  • Type detection based on typ header.

Type guards

  • isDeveloperCredential and isAgentCredential refine types at runtime.

Developer credential example (SDK)

import { validateDeveloperCredential, isDeveloperCredential } from '@belticlabs/kya';

const dev = require('../beltic-spec/examples/developer/v1/tests/valid-individual-minimal.json');

const result = validateDeveloperCredential(dev);
if (!result.valid) {
  throw new Error('Invalid developer credential');
}

console.log('Developer verified:', result.data.legalName);

Agent credential example (SDK)

import { validateAgentCredential, isAgentCredential } from '@belticlabs/kya';

const agent = require('../beltic-spec/examples/agent/v1/tests/valid-simple-agent.json');

const result = validateAgentCredential(agent);
if (result.valid) {
  console.log('Agent name:', result.data.agentName);
  console.log('Safety scores:', result.data.safetyAttestation);
}

HTTP Signature Verification Example

import { verifyHttpSignature, fetchAgentCredential } from '@belticlabs/kya';

// Verify incoming signed request
const result = await verifyHttpSignature(
  {
    method: req.method,
    url: `https://${req.hostname}${req.path}`,
    headers: req.headers,
    body: req.body
  },
  {
    fetchKeyDirectory: async (url) => {
      const response = await fetch(url);
      return response.json();
    }
  }
);

if (result.valid) {
  // Optionally fetch the agent's full credential
  const { credential } = await fetchAgentCredential(result.signatureAgentUrl);
  console.log('Request from verified agent');
}

Requirements

  • Node 18 or newer; ES2022 support.
  • Use alongside the Beltic schemas from beltic-spec for validation parity with the CLI.

Examples and fixtures

  • Human-readable examples: beltic-spec/examples/developer-example-v1.md and beltic-spec/examples/agent-example-v1.md.
  • JSON fixtures for tests: beltic-spec/examples/developer/v1/tests/* and beltic-spec/examples/agent/v1/tests/* (valid and invalid cases).
  • Pair SDK validation with those fixtures to mirror CLI behavior while schemas remain in-repo.