@auths-dev/sdk

Auths Node SDK

Decentralized identity for developers and AI agents. Sign, verify, and manage cryptographic identities with Git-native storage.

Install

npm install @auths-dev/sdk

Quick start

import { Auths, verifyAttestation } from '@auths-dev/sdk'

const auths = new Auths()

// Verify an attestation
const result = verifyAttestation(attestationJson, publicKeyHex)
console.log(result.valid) // true

// Create an identity and sign
const identity = auths.identities.create({ label: 'laptop' })
const sig = auths.signAs({ message: Buffer.from('hello world'), identityDid: identity.did })
console.log(sig.signature) // hex-encoded Ed25519 signature

Keyless service-to-service verify

Verify an agent's credential presentation (or a raw credential) offline against a pinned root — one call, a typed discriminated verdict, no thrown exception for a denial:

import { verifyPresentation, PresentationStatus } from '@auths-dev/sdk'

// `bundleJson` is the Auths-Presentation request bundle the caller sent.
const report = verifyPresentation(bundleJson)

switch (report.status) {
  case PresentationStatus.Valid:
    console.log(`granted ${report.subject} caps=${report.caps?.join(',')}`)
    break
  case PresentationStatus.CredentialNotValid:
    console.warn(`credential rejected: ${report.credential?.status}`)
    break
  default:
    console.warn(`denied: ${report.status}`) // wrongAudience, holderNotCurrentKey, expired, …
}

verifyCredential(bundleJson) returns a CredentialReport the same way (e.g. CredentialStatus.CredentialRevoked carries report.revokedAt). Malformed input returns a typed MalformedRequest status — it never throws.

Identity management

import { Auths } from '@auths-dev/sdk'

const auths = new Auths({ repoPath: '~/.auths' })

// Create a cryptographic identity
const identity = auths.identities.create({ label: 'laptop' })
console.log(identity.did) // did:keri:EBfd...

// Provision an agent (for CI, MCP servers, etc.)
const agent = auths.identities.delegateAgent({
  identityDid: identity.did,
  name: 'deploy-bot',
  capabilities: ['sign'],
})

// Sign using the keychain-stored identity key
const result = auths.signAs({
  message: Buffer.from('hello world'),
  identityDid: identity.did,
})

// Link and manage devices
const device = auths.devices.link({
  identityDid: identity.did,
  capabilities: ['sign'],
})
auths.devices.revoke({
  deviceDid: device.did,
  identityDid: identity.did,
  note: 'replaced',
})

Policy engine

import { PolicyBuilder, evaluatePolicy } from '@auths-dev/sdk'

// Build a standard policy
const policy = PolicyBuilder.standard('sign_commit')

// Evaluate against a context
const decision = policy.evaluate({
  issuer: 'did:keri:EOrg',
  subject: 'did:key:zDevice',
  capabilities: ['sign_commit'],
})
console.log(decision.allowed) // true

// Compose complex policies
const ciPolicy = new PolicyBuilder()
  .notRevoked()
  .notExpired()
  .requireCapability('sign')
  .requireAgent()
  .requireRepo('org/repo')
  .toJson()

Organization management

const org = auths.orgs.create({ label: 'my-team' })

const member = auths.orgs.addMember({
  orgDid: org.orgDid,
  memberDid: devIdentity.did,
  role: 'member',
  memberPublicKeyHex: devIdentity.publicKey,
})

const members = auths.orgs.listMembers({ orgDid: org.orgDid })

Verification

import {
  verifyAttestation,
  verifyChain,
  verifyAtTime,
} from '@auths-dev/sdk'

// Single attestation
const result = verifyAttestation(attestationJson, issuerPublicKeyHex)

// Attestation chain
const report = verifyChain(attestationChain, rootPublicKeyHex)
console.log(report.status.statusType) // 'Valid' | 'Invalid' | ...

// Time-pinned verification
const atResult = verifyAtTime(attestationJson, issuerPublicKeyHex, '2024-06-15T00:00:00Z')

Capability/role authority is no longer checked at verification time. A capability grant comes from a holder-verified ACDC credential, not the attestation.

Error handling

import { Auths, VerificationError, CryptoError, NetworkError } from '@auths-dev/sdk'

const auths = new Auths()
try {
  const result = auths.signAs({ message: data, identityDid: did })
} catch (e) {
  if (e instanceof CryptoError) {
    console.log(e.code)    // 'key_not_found'
    console.log(e.message) // 'No key found for identity...'
  }
  if (e instanceof NetworkError && e.shouldRetry) {
    // safe to retry
  }
}

All errors inherit from AuthsError and carry .code and .message.

Configuration

// Auto-discover (uses ~/.auths)
const auths = new Auths()

// Explicit repo path
const auths = new Auths({ repoPath: '/path/to/identity-repo' })

// With passphrase (or set AUTHS_PASSPHRASE env var)
const auths = new Auths({ passphrase: 'my-secret' })

// Headless / CI mode
// Set AUTHS_KEYCHAIN_BACKEND=file for environments without a system keychain

License

Apache-2.0