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/kyaQuick 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)andvalidateAgentCredential(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
typheader.
Type guards
isDeveloperCredentialandisAgentCredentialrefine 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-specfor validation parity with the CLI.
Examples and fixtures
- Human-readable examples:
beltic-spec/examples/developer-example-v1.mdandbeltic-spec/examples/agent-example-v1.md. - JSON fixtures for tests:
beltic-spec/examples/developer/v1/tests/*andbeltic-spec/examples/agent/v1/tests/*(valid and invalid cases). - Pair SDK validation with those fixtures to mirror CLI behavior while schemas remain in-repo.