@auth4agents/ts-sdk

TypeScript SDK for the Auth4Agents protocol.

Auth4Agents is a decentralized authentication and authorization system designed for autonomous agents, AI systems, services, and machine identities.

Instead of relying on static API keys or centralized OAuth providers, agents authenticate using cryptographic identity proofs backed by Ed25519 signatures, operator trust verification, and signed JWT access tokens.

The protocol is designed around:

• decentralized agent identities
• detached proof signatures
• operator-controlled authorization
• domain-backed trust establishment
• cross-language interoperability
• verifiable JWT infrastructure

The SDK provides a high-level interface for:

• operator registration
• agent registration
• challenge-based authentication
• JWT issuance
• JWT verification
• authorization scope management
• domain verification workflows

---

Features

• Raw Ed25519 identity generation
• Detached cryptographic proof authentication
• Operator-managed authorization scopes
• JWT verification via JWKS discovery
• Cross-language interoperability with Go server/CLI
• Runtime protocol validation
• Typed response contracts
• Structured SDK error system

---

Installation

pnpm add @auth4agents/sdk

or

npm install @auth4agents/sdk

---

Basic Usage

Initialize SDK

import {
  Auth4Agent
} from "@auth4agents/sdk"

const sdk =
  new Auth4Agent({
    server:
      "http://localhost:8080"
  })

---

Create Operator Identity

const operatorIdentity =
  await sdk.identity.create(
    "example.com"
  )

---

Register Operator

const operator =
  await sdk.operator.register({

    domain:
      "example.com",

    identity:
      operatorIdentity
  })

---

Get Verification Instructions

const instructions =
  await sdk.operator
    .verification
    .instructions(
      operator.id
    )

console.log(instructions)

---

Confirm Verification

const result =
  await sdk.operator
    .verification
    .confirm(
      operator.id
    )

---

Register Agent

const agentIdentity =
  await sdk.identity.create(
    "example.com"
  )

const agent =
  await sdk.agent.register({

    operatorId:
      operator.id,

    identity:
      agentIdentity
  })

---

Update Allowed Scopes

await sdk.agent.updateScopes({

  operatorId:
    operator.id,

  did:
    agentIdentity.did,

  allowedScopes: [
    "read:payments"
  ]
})

---

Authenticate Agent

const token =
  await sdk.authenticate({

    did:
      agentIdentity.did,

    seed:
      agentIdentity.seed,

    scope:
      "read:payments",

    audience:
      "api.example.com"
  })

---

Verify JWT

const verified =
  await sdk.verify(
    token.token
  )

console.log(
  verified.claims
)

---

Protocol Architecture

The protocol separates:

Layer	Responsibility
Identity	cryptographic ownership
Verification	operator trust establishment
Authorization	permission policy
Authentication	detached proof validation
Access Control	signed JWT access tokens

This separation is intentional.

The SDK does not rely on centralized OAuth providers or static API keys.

---

Cryptographic Design

The SDK uses:

• Ed25519 signatures
• raw cryptographic identities
• detached proof signing
• JWKS-based JWT verification
• signed access tokens using EdDSA

Authentication works through challenge-response verification.

Agents never transmit private keys.

---

Error Handling

The SDK exposes structured error classes.

import {
  VerificationError,
  AuthorizationError,
  ProtocolError
} from "@auth4agents/sdk"

Example:

try {

  await sdk.authenticate(...)

} catch (err) {

  if (
    err instanceof AuthorizationError
  ) {

    console.log(
      "scope denied"
    )
  }
}

---

Security Notes

This SDK currently stores raw Ed25519 seed material directly in memory.

The caller is responsible for:

• secure key storage
• encryption at rest
• process isolation
• memory handling
• operational key protection

The SDK currently does NOT provide:

• hardware-backed key storage
• HSM integration
• TPM integration
• secure enclave support
• OS-native keystore integration
• remote signing infrastructure

Do not treat this SDK as production-grade secret management infrastructure.

---

Current Status

Current release status:

• protocol stable
• SDK usable
• production hardening incomplete

The following are not fully implemented yet:

• key rotation
• token revocation lists
• multi-key JWKS rotation
• HSM support
• delegated authorization
• distributed trust federation
• audit trails
• secure seed persistence

---

Development

pnpm install

Build:

pnpm build

Run tests:

pnpm tsx tests/test-bootstrap.ts
pnpm tsx tests/test-verify.ts
pnpm tsx tests/test-authenticate.ts

---

License

MIT