@yadacoin/agent-auth (JavaScript)

Client-side JavaScript SDK for the YadaCoin KEL Agent Auth Protocol.

Implements protocol version 1.2. Works in browsers (ESM) and Node.js ≥ 18.

Install

npm install @yadacoin/agent-auth @noble/curves @noble/hashes

Or via CDN (no bundler):

<script type="importmap">
  {
    "imports": {
      "@noble/curves/secp256k1": "https://esm.sh/@noble/[email protected]/secp256k1",
      "@noble/hashes/sha256": "https://esm.sh/@noble/[email protected]/sha256",
      "@noble/hashes/hmac": "https://esm.sh/@noble/[email protected]/hmac",
      "@noble/hashes/utils": "https://esm.sh/@noble/[email protected]/utils"
    }
  }
</script>
<script type="module">
  import {
    AgentAuthClient,
    buildVCScope,
  } from "https://esm.sh/@yadacoin/[email protected]";
</script>

Quick start

import {
  AgentAuthClient,
  buildVCScope,
  deriveSecurePath,
  getPublicKey,
} from "@yadacoin/agent-auth";

// 1. Derive the agent key from stored key material + second factor
const child = deriveSecurePath(
  storedPrivKeyHex,
  storedChainCodeHex,
  secondFactor,
);
const agentPubHex = toHex(getPublicKey(child.privateKey));

// 2. Build the W3C VC 2.0 scope to commit on-chain
const relationshipB64 = buildVCScope({
  operatorPubHex: "02a1b2c3...",
  agentPubHex,
  authorizationType: "TravelBookingAuthorization",
  authorization: {
    destination: "New York",
    checkin: "May 10",
    checkout: "May 15",
    services: ["hotel", "flight"],
  },
  kelStatusMode: "rotation", // or "temporal" for long-lived credentials
});

// 3. Broadcast the rotation transaction with the VC in the relationship field
await fetch("/key-rotation/derived-child-key", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    public_key: childPubHex,
    second_factor: sf,
    relationship: relationshipB64,
  }),
});

// 4. Authenticate to a vendor with a VP
const client = new AgentAuthClient({
  challengeEndpoint: "/api/vendor/hotel/challenge",
});
const result = await client.authenticatedVPRequest("/api/vendor/hotel", {
  publicKey: agentPubHex,
  privateKey: agentPrivKey,
  vc: onChainVC,
});

Credential status modes

VCs built with kelStatusMode: "rotation" (default) are one-time-use — revoked once the key rotates. kelStatusMode: "temporal" allows the credential to survive key rotations; the verifier checks that the VP is signed with the holder's current active key per the KEL.

See §5.1 of the spec.

API

| Export | Description | | -------------------------------------- | ----------------------------------------------------------------- | | AgentAuthClient | High-level client — challenge fetch, signing, VP construction | | buildVCScope(opts) | Build a base64-encoded W3C VC 2.0 scope document | | parseScope(b64) | Decode + normalise a scope document from a KEL relationship field | | signChallenge(challenge, privateKey) | Sign a challenge string → base64 DER signature | | deriveSecurePath(priv, cc, sf) | BIP32-style key derivation (matches keyrotation.py) | | getPublicKey(privateKey) | Derive a compressed secp256k1 public key | | buildVCScope | Build + base64-encode a W3C VC 2.0 scope document | | buildScope | (deprecated) Legacy flat scope builder |

Related

• Python SDK — yadacoin-agent-auth
• Protocol specification
• did:yadacoin method spec
• YadaCoin node

License

YadaCoin Open Source License (YOSL) v1.1 — Copyright © 2017-2026 Matthew Vogel, Inc.