@primethoughts/credence-sdk

TypeScript SDK for Credence Trust OS. Wraps all 82 gateway REST endpoints across 8 service modules.

Installation

npm install @primethoughts/credence-sdk

Requires Node.js >= 20.0.0.

Quick Start

import { CredenceClient } from '@primethoughts/credence-sdk';

// Register a new supplier (public — no JWT required)
const credence = new CredenceClient({
  baseUrl: 'https://gateway.credence.example:8080',
});

const auth = await credence.identity.register({
  name: 'Jane Doe',
  email: '[email protected]',
  password: 'Secret123!',
  role: 'SUPPLIER',
});
credence.setToken(auth.token); // all subsequent calls authenticated

// Or login with existing credentials
const loginAuth = await credence.identity.login({
  email: '[email protected]',
  password: 'Secret123!',
});
credence.setToken(loginAuth.token);

// Identity — tenant management
const tenant = await credence.identity.createTenant({ name: 'Acme Corp' });
const tenants = await credence.identity.listTenants();

// Messaging — accept an invitation from DIA authority
const connection = await credence.messaging.acceptInvitation({
  invitationUrl: 'https://agent.example.com?oob=eyJhbGciOiJFZERTQSJ9',
  alias: 'dia-authority',
});

// Credentials
const credential = await credence.credentials.issue({ schemaId, subjectDid, claims });
const result = await credence.credentials.verifyV2({ presentationId, policyId });

// Registry (TRQP read)
const frameworks = await credence.registry.listFrameworks();

// Registry (admin write)
const framework = await credence.registry.admin.createFramework({ did, name, version });

// VDR
const schema = await credence.vdr.writeSchema({ name, version, attributes });

Modules

| Module | Description | Endpoint Prefix | |--------|------------|----------------| | identity | Auth (register, login, password reset, refresh), tenants, DIDs, wallets | /api/v1/auth/**, /api/v1/tenants/** | | messaging | Connections, create/accept invitations | /api/v1/connections/** | | credentials | Issue, verify, revoke | /api/v1/credentials/** | | presentations | Presentation exchange, OID4VP | /api/v1/presentations/** | | registry | TRQP queries + admin write | /api/v1/registry/**, /api/v1/admin/** | | compliance | Checks, audit events, rules | /api/v1/compliance/** | | evidence | Upload, verify, link | /api/v1/evidence/** | | vdr | Schemas, cred-defs, NYMs, revocation | /api/vdr/** |

Features

• Zero runtime dependencies — uses only Node.js builtins (node:crypto)
• Dual ESM + CJS build — works in all Node.js environments
• Full TypeScript types — mirrored from Credence backend DTOs
• Auto correlation ID — X-Correlation-ID header on every request
• Retry with backoff — configurable retry for 429/502/503/504
• RFC 7807 errors — structured error responses with CredenceApiError
• DID validation — client-side allowlist check (did:key, did:peer, did:indy, did:web)
• Key material detection — prevents accidental secret leakage

Configuration

const credence = new CredenceClient({
  baseUrl: 'https://gateway:8080',
  auth: { type: 'jwt', token: 'eyJ...' },
  retry: { maxRetries: 3, baseDelay: 1000, maxDelay: 30000 },
  timeout: 30000,
  correlationId: 'custom-correlation-id', // optional; auto-generated if omitted
});

// Refresh token
credence.setToken(newToken);

// Add interceptors
credence.addRequestInterceptor(async (url, init) => {
  // modify request before sending
  return init;
});

Breaking Changes (v0.2.0)

Governance VC lifecycle methods now require LifecycleTransitionRequest

All 5 governance VC lifecycle methods (submitForReview, activateGovernanceVc, suspendGovernanceVc, reinstateGovernanceVc, revokeGovernanceVc) now require a LifecycleTransitionRequest body with a mandatory actorDid field:

// Before (v0.1.x) — no longer works
await credence.registry.admin.submitForReview(vcId);

// After (v0.2.0) — actorDid is required
await credence.registry.admin.submitForReview(vcId, {
  actorDid: 'did:web:steward.example.com',
  reason: 'Ready for governance board review', // optional
});

GovernanceVcCreateRequest now requires proofHash

The proofHash field (SHA-256 hash of canonical VC JSON) is now required when creating governance VCs for deduplication:

await credence.registry.admin.createGovernanceVc({
  frameworkId: '...',
  vcType: 'ISSUER_AUTHORIZATION',
  vcJson: { /* W3C VCDM 2.0 */ },
  issuerDid: 'did:web:authority.example.com',
  subjectDid: 'did:web:issuer.example.com',
  validFrom: '2026-01-01T00:00:00Z',
  proofHash: 'sha256-hex-hash-of-canonical-vc-json', // now required
});

Framework request field renames

TrustFrameworkCreateRequest and TrustFrameworkUpdateRequest use did (not governingAuthority) and metadata (not description):

await credence.registry.admin.createFramework({
  did: 'did:web:authority.example.com',  // was: governingAuthority
  name: 'My Framework',
  version: '1.0.0',
  metadata: { description: '...' },       // was: description (string)
});

Development

npm install          # Install dependencies
npm run build        # Build ESM + CJS + DTS
npm test             # Run 152 unit tests
npm run typecheck    # TypeScript type checking

Spec & Compliance

• Spec: specs/credence-sdk/spec.md (85 FRs, 8 NFRs)
• Compliance audit: specs/credence-sdk/compliance-audit.md — all PASS
• KB references: [KB:00-system], [KB:01-architecture], [KB:14-learnings-v1-v2]